fix(docs): remediate writing-style convention violations (#865)

This PR addresses writing-style convention violations across the
hve-core documentation. It systematically remediates three violation
patterns (em dashes, bolded-prefix list items, and pseudo-headings)
across 52 files while adding markdownlint rules that prevent future
regressions. All changes are documentation and configuration only; no
functional code was modified.

## Changes

### Linting Infrastructure

Two new **custom markdownlint rules** were added via
`markdownlint-rule-search-replace` (v1.2.0) to catch future
writing-style violations at lint time.

- Added `no-em-dash` rule to *`.markdownlint.json`* detecting U+2014 em
dash characters in prose
- Added `no-bolded-prefix-list` rule to *`.markdownlint.json`* detecting
`**Term:** description` patterns in list items
- Both rules include `information` URLs pointing back to
*writing-style.instructions.md* for contributor guidance
- Registered the search-replace plugin in *`.markdownlint-cli2.jsonc`*
- Changed `MD024.siblings_only` from `false` to `true` to accommodate
new headings introduced by pseudo-heading conversions
- Added `markdownlint-rule-search-replace` as a dev dependency in
*package.json*

### Em Dash Remediation

Replaced 41 em dash instances across documentation with
context-appropriate punctuation following the writing-style convention.

- Substituted colons where the em dash introduced an explanation or
elaboration
- Substituted parentheses where the em dash framed a parenthetical aside
- Applied across contributing guides, architecture docs, RPI workflow
documentation, extension templates, getting-started guides, and
customization content

### Bolded-Prefix and Pseudo-Heading Conversions

Converted 370+ instances of bolded-prefix list items and pseudo-headings
into convention-compliant formatting using three remediation strategies
matched to content type.

- Converted bolded text used as section headers into proper markdown
headings (`###`, `####`, `#####`) based on document hierarchy
- Replaced `**Term:** description` patterns with plain `Term:
description` for inline definitions
- Restructured metadata-style lists into definition tables where the
content warranted tabular presentation
- Added an inline `<!-- markdownlint-disable-next-line search-replace
-->` comment in *writing-style.instructions.md* to suppress a
false-positive lint hit on the instructional em dash example

### Documentation Updates

Applied writing-style fixes across all major documentation areas.

- *docs/architecture/*: Heading conversions and em dash replacements in
workflow and testing docs
- *docs/contributing/*: Bolded-prefix remediation across instructions,
prompts, agents, and release process guides
- *docs/getting-started/*: Consistent fixes across all six installation
method guides
- *docs/rpi/*: Pseudo-heading conversions in researcher, planner, and
implementor docs
- *docs/security/*: Heading and list-item formatting in security
planning documentation
- *docs/customization/* and *docs/design-thinking/*: Em dash and
bolded-prefix fixes
- *scripts/*: README heading conversions across extension, lib, linting,
security, and tests directories
- *extension/*: Pseudo-heading fixes in *PACKAGING.md* and em dash
replacement in *README.template.md*
- *.devcontainer/README.md* and *SUPPORT.md*: Writing-style compliance
fixes

## Related Issues

Closes #504

## Notes

- The 662 remaining lint violations (158 em dash + 504 bolded-prefix)
are in out-of-scope files (instructions, agents, prompts, skills) and
represent the expected baseline documented in Issue #504
- Content meaning and structure are preserved through all conversions;
only formatting changed

Co-authored-by: Bill Berry <wbery@microsoft.com>

Author: WilliamBerryiii

.devcontainer/README.md

@@ -58,9 +58,9 @@ A pre-configured development environment that includes all tools, extensions, an
 
 ### Code Quality
 
-* **Markdown**: markdownlint, markdown-table-formatter
-* **Spelling**: Code Spell Checker (VS Code extension)
-* **Shell**: shellcheck
+* Markdown: markdownlint, markdown-table-formatter
+* Spelling: Code Spell Checker (VS Code extension)
+* Shell: shellcheck
 
 ### Security
 
@@ -74,9 +74,9 @@ A pre-configured development environment that includes all tools, extensions, an
 
 ## Pre-installed VS Code Extensions
 
-* **Spell Checking**: Street Side Software Spell Checker
-* **Markdown**: markdownlint, Markdown All in One, Mermaid support
-* **GitHub**: GitHub Pull Requests
+* Spell Checking: Street Side Software Spell Checker
+* Markdown: markdownlint, Markdown All in One, Mermaid support
+* GitHub: GitHub Pull Requests
 
 ## Common Commands
 
@@ -98,9 +98,9 @@ gitleaks detect --source . --verbose
 
 ## Troubleshooting
 
-**Container won't build**: Ensure Docker Desktop is running and you have sufficient disk space (5GB+).
+Container won't build: Ensure Docker Desktop is running and you have sufficient disk space (5GB+).
 
-**Extensions not loading**: Reload the window (`F1` → **Developer: Reload Window**).
+Extensions not loading: Reload the window (`F1` → **Developer: Reload Window**).
 
 For more help, see [SUPPORT.md](../SUPPORT.md).
 

.github/CUSTOM-AGENTS.md

@@ -420,7 +420,7 @@ The Research-Plan-Implement (RPI) workflow provides a structured approach to com
 * **Linting Exemption:** Files in `.copilot-tracking/**` are exempt from repository linting rules
 * **Agent Switching:** Clear context or start a new chat when switching between specialized agents
 * **Research First:** Task planner requires completed research; will automatically invoke researcher if missing
-* **No Implementation:** Task planner and researcher never implement actual project code—they create planning artifacts only
+* **No Implementation:** Task planner and researcher never implement actual project code. They create planning artifacts only
 * **Subagent Requirements:** Several agents require a subagent tool enabled in Copilot settings
 
 ## Tips

.github/PULL_REQUEST_TEMPLATE.md

@@ -33,11 +33,11 @@ Select all that apply:
 * [ ] Copilot agent (`.github/agents/*.agent.md`)
 * [ ] Copilot skill (`.github/skills/*/SKILL.md`)
 
-> **Note for AI Artifact Contributors**:
+> Note for AI Artifact Contributors:
 >
-> * **Agents**: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review `.github/agents/` before creating new ones.
-> * **Skills**: Must include both bash and PowerShell scripts. See [Skills](../docs/contributing/skills.md).
-> * **Model Versions**: Only contributions targeting the **latest Anthropic and OpenAI models** will be accepted. Older model versions (e.g., GPT-3.5, Claude 3) will be rejected.
+> * Agents: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review `.github/agents/` before creating new ones.
+> * Skills: Must include both bash and PowerShell scripts. See [Skills](../docs/contributing/skills.md).
+> * Model Versions: Only contributions targeting the **latest Anthropic and OpenAI models** will be accepted. Older model versions (e.g., GPT-3.5, Claude 3) will be rejected.
 > * See [Agents Not Accepted](../docs/contributing/custom-agents.md#agents-not-accepted) and [Model Version Requirements](../docs/contributing/ai-artifacts-common.md#model-version-requirements).
 
 **Other:**
@@ -64,11 +64,11 @@ Select all that apply:
 
 For detailed contribution requirements, see:
 
-* **Common Standards**: [docs/contributing/ai-artifacts-common.md](../docs/contributing/ai-artifacts-common.md) - Shared standards for XML blocks, markdown quality, RFC 2119, validation, and testing
-* **Agents**: [docs/contributing/custom-agents.md](../docs/contributing/custom-agents.md) - Agent configurations with tools and behavior patterns
-* **Prompts**: [docs/contributing/prompts.md](../docs/contributing/prompts.md) - Workflow-specific guidance with template variables
-* **Instructions**: [docs/contributing/instructions.md](../docs/contributing/instructions.md) - Technology-specific standards with glob patterns
-* **Skills**: [docs/contributing/skills.md](../docs/contributing/skills.md) - Task execution utilities with cross-platform scripts
+* Common Standards: [docs/contributing/ai-artifacts-common.md](../docs/contributing/ai-artifacts-common.md) - Shared standards for XML blocks, markdown quality, RFC 2119, validation, and testing
+* Agents: [docs/contributing/custom-agents.md](../docs/contributing/custom-agents.md) - Agent configurations with tools and behavior patterns
+* Prompts: [docs/contributing/prompts.md](../docs/contributing/prompts.md) - Workflow-specific guidance with template variables
+* Instructions: [docs/contributing/instructions.md](../docs/contributing/instructions.md) - Technology-specific standards with glob patterns
+* Skills: [docs/contributing/skills.md](../docs/contributing/skills.md) - Task execution utilities with cross-platform scripts
 
 ## Testing
 <!-- Describe how you tested these changes -->

.github/instructions/hve-core/writing-style.instructions.md

@@ -62,6 +62,7 @@ Avoid these common patterns that reduce clarity and create clutter.
 
 ### Em Dashes
 
+<!-- markdownlint-disable-next-line search-replace -->
 Do not use em dashes (—) for parenthetical statements, explanations, or dramatic pauses. Use these alternatives instead:
 
 | Instead of Em Dash  | Use This    | Example                                         |

.github/workflows/README.md

@@ -54,9 +54,9 @@ Compose multiple reusable workflows for comprehensive validation and security sc
 | `weekly-security-maintenance.yml` | Schedule (Sun 2AM UTC)                  | 4 (validate-pinning, check-staleness, codeql-analysis, summary) | Soft-fail warnings         | Weekly security posture              |
 | `scorecard.yml`                   | Push to main, Schedule (Sun 3AM UTC)    | 1 (scorecard)                                                   | SARIF upload               | OpenSSF Scorecard security posture   |
 
-**pr-validation.yml jobs**: codeql-analysis, spell-check, markdown-lint, table-format, psscriptanalyzer, frontmatter-validation, link-lang-check, markdown-link-check, dependency-pinning-check
+pr-validation.yml jobs: codeql-analysis, spell-check, markdown-lint, table-format, psscriptanalyzer, frontmatter-validation, link-lang-check, markdown-link-check, dependency-pinning-check
 
-**release-stable.yml jobs**: spell-check, markdown-lint, table-format, codeql-analysis, dependency-pinning-scan
+release-stable.yml jobs: spell-check, markdown-lint, table-format, codeql-analysis, dependency-pinning-scan
 
 ## Reusable Workflows
 
@@ -75,7 +75,7 @@ Compose multiple reusable workflows for comprehensive validation and security sc
 
 All validation workflows use `permissions: contents: read`, publish PR annotations, and retain artifacts for 30 days.
 
-**Usage example**:
+Usage example:
 
 ```yaml
 jobs:
@@ -89,10 +89,10 @@ jobs:
 
 Each modular workflow implements comprehensive 4-channel result publishing:
 
-1. **PR Annotations**: Warnings/errors appear on Files Changed tab
-2. **Artifacts**: Raw output files retained for 30 days
-3. **SARIF Reports**: Security tab integration (security workflows only)
-4. **Job Summaries**: Rich markdown summaries in Actions tab
+1. PR Annotations: Warnings/errors appear on Files Changed tab
+2. Artifacts: Raw output files retained for 30 days
+3. SARIF Reports: Security tab integration (security workflows only)
+4. Job Summaries: Rich markdown summaries in Actions tab
 
 ## Security Best Practices
 
@@ -144,67 +144,67 @@ The SHA staleness check workflow complements Dependabot by monitoring for stale
 
 #### `codeql-analysis.yml`
 
-**Purpose**: Performs comprehensive security analysis using GitHub CodeQL
+Purpose: Performs comprehensive security analysis using GitHub CodeQL
 
-**Triggers**: `schedule` (Sundays at 4 AM UTC), `workflow_call`
+Triggers: `schedule` (Sundays at 4 AM UTC), `workflow_call`
 
-**Features**:
+Features:
 
-* **Languages**: JavaScript/TypeScript analysis
-* **Queries**: security-extended and security-and-quality query suites
-* **Coverage**: Detects SQL injection, XSS, command injection, path traversal, and 200+ other vulnerabilities
-* **Integration**: Results appear in Security > Code Scanning tab
-* **Auto-build**: Automatically detects and builds JavaScript/TypeScript projects
+* Languages: JavaScript/TypeScript analysis
+* Queries: security-extended and security-and-quality query suites
+* Coverage: Detects SQL injection, XSS, command injection, path traversal, and 200+ other vulnerabilities
+* Integration: Results appear in Security > Code Scanning tab
+* Auto-build: Automatically detects and builds JavaScript/TypeScript projects
 
-**Outputs**: SARIF results uploaded to GitHub Security tab, job summary with analysis details
+Outputs: SARIF results uploaded to GitHub Security tab, job summary with analysis details
 
 #### `dependency-review.yml`
 
-**Purpose**: Reviews dependency changes in pull requests for known vulnerabilities
+Purpose: Reviews dependency changes in pull requests for known vulnerabilities
 
-**Triggers**: `pull_request`, `workflow_call`
+Triggers: `pull_request`, `workflow_call`
 
-**Features**:
+Features:
 
-* **Threshold**: Fails on moderate or higher severity vulnerabilities
-* **PR Comments**: Automatically comments on PRs with vulnerability summary
-* **Coverage**: Checks npm packages against GitHub Advisory Database
-* **Integration**: Works with Dependabot alerts and security advisories
+* Threshold: Fails on moderate or higher severity vulnerabilities
+* PR Comments: Automatically comments on PRs with vulnerability summary
+* Coverage: Checks npm packages against GitHub Advisory Database
+* Integration: Works with Dependabot alerts and security advisories
 
-**Behavior**: Blocks PRs introducing vulnerable dependencies (moderate+ severity)
+Behavior: Blocks PRs introducing vulnerable dependencies (moderate+ severity)
 
 #### `dependency-pinning-scan.yml`
 
-**Purpose**: Validates that all GitHub Actions use SHA-pinned versions
+Purpose: Validates that all GitHub Actions use SHA-pinned versions
 
-**Inputs**:
+Inputs:
 
 * `threshold` (number, default: 95): Minimum compliance percentage
 * `dependency-types` (string, default: 'actions,containers'): Types to validate
 * `soft-fail` (boolean, default: false): Continue on failures
 * `upload-sarif` (boolean, default: false): Upload to Security tab
 * `upload-artifact` (boolean, default: true): Upload JSON results
 
-**Outputs**:
+Outputs:
 
 * `compliance-score`: Percentage of dependencies properly pinned
 * `unpinned-count`: Number of unpinned dependencies
 * `is-compliant`: Boolean indicating threshold met
 
 #### `sha-staleness-check.yml`
 
-**Purpose**: Detects outdated GitHub Action SHA pins
+Purpose: Detects outdated GitHub Action SHA pins
 
-**Inputs**:
+Inputs:
 
 * `max-age-days` (number, default: 30): Maximum age before stale
 
-**Outputs**:
+Outputs:
 
 * `stale-count`: Number of stale SHA pins
 * `has-stale`: Boolean indicating stale pins found
 
-**Severity Levels**:
+Severity Levels:
 
 * Info: 0-30 days
 * Low: 31-90 days
@@ -214,18 +214,18 @@ The SHA staleness check workflow complements Dependabot by monitoring for stale
 
 #### `scorecard.yml`
 
-**Purpose**: Performs OpenSSF Scorecard analysis for security posture assessment
+Purpose: Performs OpenSSF Scorecard analysis for security posture assessment
 
-**Triggers**: `schedule` (Sundays at 3 AM UTC), `push` to main
+Triggers: `schedule` (Sundays at 3 AM UTC), `push` to main
 
-**Features**:
+Features:
 
-* **Analysis**: Supply chain security, CI/CD best practices, code review practices
-* **Integration**: Results published to OpenSSF Scorecard API and GitHub Security tab
-* **Badge**: Live Scorecard badge available for README display
-* **Artifacts**: SARIF results retained for 90 days
+* Analysis: Supply chain security, CI/CD best practices, code review practices
+* Integration: Results published to OpenSSF Scorecard API and GitHub Security tab
+* Badge: Live Scorecard badge available for README display
+* Artifacts: SARIF results retained for 90 days
 
-**Outputs**: SARIF results uploaded to GitHub Security tab, job summary with badge link
+Outputs: SARIF results uploaded to GitHub Security tab, job summary with badge link
 
 ## Architecture Decisions
 
@@ -235,9 +235,9 @@ The SHA staleness check workflow complements Dependabot by monitoring for stale
 
 **Current Architecture:** CodeQL now runs exclusively through orchestrator workflows to prevent duplicate runs and ensure consistent security scanning:
 
-* **CodeQL PR validation**: Runs via `pr-validation.yml` on all PR activity (open, push, reopen)
-* **Main branch**: Runs via `release-stable.yml` on every push to main
-* **Weekly scan**: Standalone scheduled run every Sunday at 4 AM UTC for continuous security monitoring
+* CodeQL PR validation: Runs via `pr-validation.yml` on all PR activity (open, push, reopen)
+* Main branch: Runs via `release-stable.yml` on every push to main
+* Weekly scan: Standalone scheduled run every Sunday at 4 AM UTC for continuous security monitoring
 
 This architecture ensures:
 
@@ -246,7 +246,7 @@ This architecture ensures:
 * Clear ownership of when and why CodeQL executes
 * Reduced GitHub Actions minutes consumption
 
-**Workflow Execution Matrix**:
+Workflow Execution Matrix:
 
 | Event                                | Workflows That Run                                       | CodeQL Included       |
 |--------------------------------------|----------------------------------------------------------|-----------------------|
@@ -359,10 +359,10 @@ jobs:
 
 ### Artifact Handling
 
-* **Retention**: 30 days for all artifacts
-* **Naming**: `{workflow-name}-results`
-* **Contents**: JSON results, markdown summaries, logs
-* **Condition**: `if: always()` to upload even on failure
+* Retention: 30 days for all artifacts
+* Naming: `{workflow-name}-results`
+* Contents: JSON results, markdown summaries, logs
+* Condition: `if: always()` to upload even on failure
 
 ### GitHub Annotations
 

.markdownlint-cli2.jsonc

@@ -15,6 +15,13 @@
     "plugins/**/commands/**",
     "plugins/**/skills/**",
     "plugins/**/docs/**",
-    "plugins/**/scripts/**"
+    "plugins/**/scripts/**",
+    ".github/instructions/**",
+    ".github/agents/**",
+    ".github/prompts/**",
+    ".github/skills/**"
+  ],
+  "customRules": [
+    "markdownlint-rule-search-replace"
   ]
 }

.markdownlint.json

@@ -49,7 +49,7 @@
   },
   "MD023": true,
   "MD024": {
-    "siblings_only": false
+    "siblings_only": true
   },
   "MD025": {
     "level": 1,
@@ -146,5 +146,23 @@
   "MD058": true,
   "MD060": {
     "style": "leading_and_trailing"
+  },
+  "search-replace": {
+    "rules": [
+      {
+        "name": "no-em-dash",
+        "message": "Do not use em dashes (—); use colons, commas, or parentheses instead",
+        "searchPattern": "/—/g",
+        "searchScope": "text",
+        "information": "https://github.com/microsoft/hve-core/blob/main/.github/instructions/hve-core/writing-style.instructions.md"
+      },
+      {
+        "name": "no-bolded-prefix-list",
+        "message": "Do not use bolded-prefix list items (e.g., '* **Label**: desc'); use tables, headings, or plain lists",
+        "searchPattern": "/\\*\\*[^*]+\\*\\*\\s*[:—–-]/g",
+        "searchScope": "text",
+        "information": "https://github.com/microsoft/hve-core/blob/main/.github/instructions/hve-core/writing-style.instructions.md"
+      }
+    ]
   }
 }

CONTRIBUTING.md

@@ -357,10 +357,10 @@ This project uses [release-please](https://github.com/googleapis/release-please)
 
 ### How Releases Work
 
-1. **Commit with Conventional Commits** - All commits to `main` must follow conventional commit format (see [commit message instructions](./.github/instructions/hve-core/commit-message.instructions.md))
-2. **Release PR Creation** - After commits are pushed to `main`, release-please automatically creates or updates a "release PR"
-3. **Review Release PR** - Maintainers review the release PR to verify version bump and changelog accuracy
-4. **Merge to Release** - When the release PR is merged, a git tag and GitHub Release are automatically created
+1. Commit with Conventional Commits - All commits to `main` must follow conventional commit format (see [commit message instructions](./.github/instructions/hve-core/commit-message.instructions.md))
+2. Release PR Creation - After commits are pushed to `main`, release-please automatically creates or updates a "release PR"
+3. Review Release PR - Maintainers review the release PR to verify version bump and changelog accuracy
+4. Merge to Release - When the release PR is merged, a git tag and GitHub Release are automatically created
 
 ### Version Determination
 

GOVERNANCE.md

@@ -17,7 +17,7 @@ HVE Core uses a liberal contribution model where active contributors are recogni
 
 ## Governance Model
 
-This project operates under a **corporate-sponsored maintainer model**:
+This project operates under a corporate-sponsored maintainer model:
 
 * Microsoft provides stewardship, infrastructure, and core maintainer resources
 * Community contributors participate through standard open source workflows
@@ -148,9 +148,9 @@ Nomination process:
 
 When contributors disagree on technical or process matters:
 
-1. **Discussion**: Parties discuss the issue in the relevant pull request or issue
-2. **Maintainer input**: If unresolved, a maintainer provides guidance
-3. **Maintainer decision**: If consensus remains elusive, maintainers make a binding decision
+1. Discussion: Parties discuss the issue in the relevant pull request or issue
+2. Maintainer input: If unresolved, a maintainer provides guidance
+3. Maintainer decision: If consensus remains elusive, maintainers make a binding decision
 
 Code of conduct violations follow the process defined in [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
 

SUPPORT.md

@@ -30,23 +30,23 @@ HVE Core is an open-source project maintained by Microsoft and community contrib
 | Major (Accessibility)      | Significant accessibility issues                 | 3-5 business days              |
 | General Issues & Questions | Bug reports, feature requests, questions         | 48-hour (24x6) response window |
 
-**Note**: Response times indicate initial acknowledgment. Resolution time varies based on issue complexity and community availability.
+Note: Response times indicate initial acknowledgment. Resolution time varies based on issue complexity and community availability.
 
 ### Our Support Performance
 
 We track our response time commitments publicly. Our performance metrics demonstrate consistent delivery:
 
-* **48-hour SLO Compliance**: High compliance rate with response targets
-* **Average PR Completion**: Typically completed within 3 days
-* **Fast Resolution**: Significant portion of issues/PRs resolved in under 1 day
+* 48-hour SLO Compliance: High compliance rate with response targets
+* Average PR Completion: Typically completed within 3 days
+* Fast Resolution: Significant portion of issues/PRs resolved in under 1 day
 
 ## Filing Issues
 
 ### General Issues, Bugs, and Feature Requests
 
 1. **Search existing issues** in our [GitHub Issues](https://github.com/microsoft/hve-core/issues)
 2. **Create a new issue** if yours isn't already tracked: [New Issue](https://github.com/microsoft/hve-core/issues/new/choose)
-3. **Provide details**:
+3. Provide details:
    * Clear description of the problem or request
    * Steps to reproduce (for bugs)
    * Expected vs. actual behavior