docs: add docs validation ci checks

.github/workflows/docs-review.yml

@@ -9,6 +9,8 @@ on:
       - "**/*.md"
       - "**/*.mdc"
       - "docs/**"
+      - "scripts/check-docs-commands.py"
+      - "tests/unit/test_check_docs_commands_script.py"
       - "tests/unit/docs/test_docs_review.py"
       - ".github/workflows/docs-review.yml"
   push:
@@ -17,6 +19,8 @@ on:
       - "**/*.md"
       - "**/*.mdc"
       - "docs/**"
+      - "scripts/check-docs-commands.py"
+      - "tests/unit/test_check_docs_commands_script.py"
       - "tests/unit/docs/test_docs_review.py"
       - ".github/workflows/docs-review.yml"
   workflow_dispatch:
@@ -44,7 +48,7 @@ jobs:
       - name: Install docs review dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install pytest
+          python -m pip install pytest click typer PyYAML beartype icontract rich pydantic specfact-cli
 
       - name: Run docs review suite
         run: |
@@ -53,6 +57,13 @@ jobs:
           python -m pytest tests/unit/docs/test_docs_review.py -q 2>&1 | tee "$DOCS_REVIEW_LOG"
           exit "${PIPESTATUS[0]:-$?}"
 
+      - name: Validate docs commands and cross-site links
+        run: |
+          mkdir -p logs/docs-review
+          DOCS_COMMAND_LOG="logs/docs-review/docs-command-validation_$(date -u +%Y%m%d_%H%M%S).log"
+          python scripts/check-docs-commands.py 2>&1 | tee "$DOCS_COMMAND_LOG"
+          exit "${PIPESTATUS[0]:-$?}"
+
       - name: Upload docs review logs
         if: always()
         uses: actions/upload-artifact@v4

docs/adapters/azuredevops.md

@@ -412,7 +412,7 @@ raw_format = proposal.source_tracking.source_metadata.get("raw_format")  # "mark
 
 When exporting from stored bundles, the adapter uses raw content if available to preserve 100% fidelity, even when syncing to a different adapter (e.g., ADO → GitHub).
 
-**See**: [Cross-Adapter Sync Guide](../guides/devops-adapter-integration.md#cross-adapter-sync-lossless-round-trip-migration) for complete documentation.
+**See**: [Cross-Adapter Sync Guide](/integrations/devops-adapter-overview/#cross-adapter-sync-lossless-round-trip-migration) for complete documentation.
 
 ## Source Tracking Matching
 
@@ -558,5 +558,5 @@ specfact project sync bridge --adapter ado --mode export-only \
 
 - **[Backlog Adapter Patterns](./backlog-adapter-patterns.md)** - Patterns for backlog adapters
 - **[GitHub Adapter](./github.md)** - GitHub adapter documentation
-- **[Validation Integration](../validation-integration.md)** - Validation with change proposals
-- **[DevOps Adapter Integration](../guides/devops-adapter-integration.md)** - DevOps workflow integration
+- **[Thorough codebase validation](/reference/thorough-codebase-validation/)** - Validation and release-readiness guidance
+- **[DevOps Adapter Integration](/integrations/devops-adapter-overview/)** - DevOps workflow integration

docs/adapters/backlog-adapter-patterns.md

@@ -491,6 +491,6 @@ When implementing new backlog adapters:
 
 - **[GitHub Adapter Documentation](./github.md)** - GitHub adapter reference
 - **[Azure DevOps Adapter Documentation](./azuredevops.md)** - Azure DevOps adapter reference
-- **[DevOps Adapter Integration Guide](../guides/devops-adapter-integration.md)** - Complete integration guide for GitHub and ADO
-- **[Validation Integration](../validation-integration.md)** - Validation with change proposals
-- **[Bridge Adapter Interface](../bridge-adapter-interface.md)** - Base adapter interface
+- **[DevOps Adapter Integration Guide](/integrations/devops-adapter-overview/)** - Complete integration guide for GitHub and ADO
+- **[Thorough codebase validation](/reference/thorough-codebase-validation/)** - Validation and release-readiness guidance
+- **[Adapter development guide](/authoring/adapter-development/)** - Base adapter interface and implementation patterns

docs/adapters/github.md

@@ -354,7 +354,7 @@ specfact project sync bridge --adapter github --mode export-only \
 
 After a successful run, each change’s `openspec/changes/<change-id>/proposal.md` will contain a **Source Tracking** block with the new issue number and URL. Use that section to link the PR and keep backlog in sync.
 
-For public repos, add `--sanitize` when exporting so content is sanitized before creating issues. See [DevOps Adapter Integration](../guides/devops-adapter-integration.md) and the [sync bridge command reference](../reference/commands.md#sync-bridge).
+For public repos, add `--sanitize` when exporting so content is sanitized before creating issues. See [DevOps Adapter Integration](/integrations/devops-adapter-overview/) and the [sync bridge command reference](/reference/commands/#project-sync-bridge).
 
 ### Updating Archived Change Proposals
 
@@ -385,7 +385,7 @@ This ensures archived issues get updated with:
 - Enhanced comment formatting
 - Latest status information
 
-See [DevOps Adapter Integration Guide](../guides/devops-adapter-integration.md#updating-archived-change-proposals) for complete documentation.
+See [DevOps Adapter Integration Guide](/integrations/devops-adapter-overview/#updating-archived-change-proposals) for complete documentation.
 
 ## Lossless Content Preservation
 
@@ -403,11 +403,11 @@ raw_format = proposal.source_tracking.source_metadata.get("raw_format")  # "mark
 
 When exporting from stored bundles, the adapter uses raw content if available to preserve 100% fidelity, even when syncing to a different adapter (e.g., GitHub → ADO).
 
-**See**: [Cross-Adapter Sync Guide](../guides/devops-adapter-integration.md#cross-adapter-sync-lossless-round-trip-migration) for complete documentation.
+**See**: [Cross-Adapter Sync Guide](/integrations/devops-adapter-overview/#cross-adapter-sync-lossless-round-trip-migration) for complete documentation.
 
 ## Related Documentation
 
 - **[Backlog Adapter Patterns](./backlog-adapter-patterns.md)** - Patterns for backlog adapters
 - **[Azure DevOps Adapter](./azuredevops.md)** - Azure DevOps adapter documentation
-- **[Validation Integration](../validation-integration.md)** - Validation with change proposals
-- **[DevOps Adapter Integration](../guides/devops-adapter-integration.md)** - DevOps workflow integration
+- **[Thorough codebase validation](/reference/thorough-codebase-validation/)** - Validation and release-readiness guidance
+- **[DevOps Adapter Integration](/integrations/devops-adapter-overview/)** - DevOps workflow integration

docs/bundles/backlog/policy-engine.md

@@ -14,9 +14,9 @@ Use SpecFact policy commands to scaffold, validate, and improve policy configura
 
 The policy engine currently supports:
 
-- `specfact policy init` to scaffold `.specfact/policy.yaml` from a built-in template.
-- `specfact policy validate` to evaluate configured rules deterministically against policy input artifacts.
-- `specfact policy suggest` to generate confidence-scored, patch-ready recommendations (no automatic writes).
+- `specfact backlog policy init` to scaffold `.specfact/policy.yaml` from a built-in template.
+- `specfact backlog policy validate` to evaluate configured rules deterministically against policy input artifacts.
+- `specfact backlog policy suggest` to generate confidence-scored, patch-ready recommendations (no automatic writes).
 
 ## Commands
 
@@ -25,7 +25,7 @@ The policy engine currently supports:
 Create a starter policy configuration file:
 
 ```bash
-specfact policy init --repo . --template scrum
+specfact backlog policy init --repo . --template scrum
 ```
 
 Supported templates:
@@ -38,7 +38,7 @@ Supported templates:
 Interactive mode (template prompt):
 
 ```bash
-specfact policy init --repo .
+specfact backlog policy init --repo .
 ```
 
 The command writes `.specfact/policy.yaml`. Use `--force` to overwrite an existing file.
@@ -48,7 +48,7 @@ The command writes `.specfact/policy.yaml`. Use `--force` to overwrite an existi
 Run policy checks with deterministic output:
 
 ```bash
-specfact policy validate --repo . --format both
+specfact backlog policy validate --repo . --format both
 ```
 
 Artifact resolution order when `--snapshot` is omitted:
@@ -59,20 +59,20 @@ Artifact resolution order when `--snapshot` is omitted:
 You can still override with an explicit path:
 
 ```bash
-specfact policy validate --repo . --snapshot ./snapshot.json --format both
+specfact backlog policy validate --repo . --snapshot ./snapshot.json --format both
 ```
 
 Filter and scope output:
 
 ```bash
 # only one rule family, max 20 findings
-specfact policy validate --repo . --rule scrum.dor --limit 20 --format json
+specfact backlog policy validate --repo . --rule scrum.dor --limit 20 --format json
 
 # item-centric grouped output
-specfact policy validate --repo . --group-by-item --format both
+specfact backlog policy validate --repo . --group-by-item --format both
 
 # in grouped mode, --limit applies to item groups
-specfact policy validate --repo . --group-by-item --limit 4 --format json
+specfact backlog policy validate --repo . --group-by-item --limit 4 --format json
 ```
 
 Output formats:
@@ -88,20 +88,20 @@ When config is missing or invalid, the command prints a docs hint pointing back
 Generate suggestions from validation findings:
 
 ```bash
-specfact policy suggest --repo .
+specfact backlog policy suggest --repo .
 ```
 
 Suggestion shaping options:
 
 ```bash
 # suggestions for one rule family, limited output
-specfact policy suggest --repo . --rule scrum.dod --limit 10
+specfact backlog policy suggest --repo . --rule scrum.dod --limit 10
 
 # grouped suggestions by backlog item index
-specfact policy suggest --repo . --group-by-item
+specfact backlog policy suggest --repo . --group-by-item
 
 # grouped mode limits item groups, not per-item fields
-specfact policy suggest --repo . --group-by-item --limit 4
+specfact backlog policy suggest --repo . --group-by-item --limit 4
 ```
 
 Suggestions include confidence scores and patch-ready structure, but no file is modified automatically.

docs/bundles/backlog/refinement.md

@@ -785,7 +785,6 @@ Templates are automatically loaded in priority order (custom templates override
 
 1. **Project templates** (`.specfact/templates/backlog/`) - Highest priority, overrides built-in
 2. **Built-in templates** (`resources/templates/backlog/`) - Included with package
-3. **Legacy location** (`src/specfact_cli/templates/`) - Fallback for backward compatibility
 
 Within each location, templates are loaded from:
 

docs/getting-started/README.md

@@ -45,11 +45,10 @@ specfact project --help
 
 Flat root commands were removed. Use the mounted grouped command forms:
 
-- `specfact validate ...` -> `specfact code validate ...`
-- `specfact code repro ...` -> `specfact code repro ...`
-- `specfact sync ...` -> `specfact project sync ...`
-- `specfact govern enforce ...` -> `specfact govern enforce ...`
-- `specfact policy ...` -> `specfact backlog policy ...`
+- root-level `validate` moved under `specfact code validate ...`
+- root-level `sync` moved under `specfact project sync ...`
+- root-level policy actions moved under `specfact backlog policy ...`
+- grouped command surfaces such as `specfact code repro ...` and `specfact govern enforce ...` remain current
 
 First-run bundle selection examples:
 

docs/getting-started/first-steps.md

@@ -6,7 +6,7 @@ permalink: /getting-started/first-steps/
 
 # Legacy Workflow Note
 
-This page described older `specfact plan`, `specfact generate`, `specfact contract`, or `specfact sdd constitution` workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`.
+This page described older plan-generation, contract, and constitution workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`.
 
 Use the current mounted entrypoints instead:
 

docs/getting-started/installation.md

@@ -493,7 +493,7 @@ specfact --version
 
 # Get help
 specfact --help
-specfact <command> --help
+specfact project --help
 
 # Inspect currently mounted project workflows
 specfact project --help
@@ -535,4 +535,4 @@ hatch run format
 hatch run lint
 ```
 
-See [CONTRIBUTING.md](../../CONTRIBUTING.md) for detailed contribution guidelines.
+See the [repository contributing guide](https://github.com/nold-ai/specfact-cli-modules/blob/dev/CONTRIBUTING.md) for detailed contribution guidelines.

docs/getting-started/tutorial-backlog-refine-ai-ide.md

@@ -170,9 +170,9 @@ If your team uses **custom fields** (e.g. Azure DevOps custom process templates)
 
 ## Related Documentation
 
-- **[Backlog Refinement Guide](../guides/backlog-refinement.md)** — Full reference: templates, options, export/import, DoR
-- **[Story scope and specification level](../guides/backlog-refinement.md#story-scope-and-specification-level)** — Underspecification, over-specification, fit-for-scope
-- **[Definition of Ready (DoR)](../guides/backlog-refinement.md#step-45-definition-of-ready-dor-validation-optional)** — DoR configuration and validation
+- **[Backlog Refinement Guide](/bundles/backlog/refinement/)** — Full reference: templates, options, export/import, DoR
+- **[Story scope and specification level](/bundles/backlog/refinement/#story-scope-and-specification-level)** — Underspecification, over-specification, fit-for-scope
+- **[Definition of Ready (DoR)](/bundles/backlog/refinement/#step-45-definition-of-ready-dor-validation-optional)** — DoR configuration and validation
 - **[Template Customization](../guides/template-customization.md)** — Custom templates for advanced teams
 - **[Custom Field Mapping](../guides/custom-field-mapping.md)** — ADO custom field mapping
 - **[IDE Integration](../guides/ide-integration.md)** — Set up slash commands in Cursor, VS Code, etc.

docs/getting-started/tutorial-daily-standup-sprint-review.md

@@ -65,7 +65,7 @@ specfact backlog ceremony standup ado
 
 If you're **not** in a clone (e.g. different directory), use one of:
 
-- **`.nold-ai/specfact-backlog.yaml`** in the project (see [Project backlog context](../guides/devops-adapter-integration.md#project-backlog-context-specfactbacklogyaml))
+- **`.nold-ai/specfact-backlog.yaml`** in the project (see [Project backlog context](/integrations/devops-adapter-overview/#project-backlog-context-specfactbacklogyaml))
 - **Environment variables**: `SPECFACT_GITHUB_REPO_OWNER`, `SPECFACT_GITHUB_REPO_NAME` or `SPECFACT_ADO_ORG`, `SPECFACT_ADO_PROJECT`
 - **CLI options**: `--repo-owner` / `--repo-name` or `--ado-org` / `--ado-project`
 
@@ -214,5 +214,5 @@ supported. Use it with the **`specfact.backlog-daily`** slash prompt for interac
 ## Related Documentation
 
 - **[Agile/Scrum Workflows](../guides/agile-scrum-workflows.md)** — Daily standup, iteration/sprint, unassigned items, blockers-first
-- **[DevOps Adapter Integration](../guides/devops-adapter-integration.md)** — Project backlog context (`.nold-ai/specfact-backlog.yaml`), env vars, **Git fallback (auto-detect from clone)** for GitHub and Azure DevOps
-- **[Backlog Refinement Guide](../guides/backlog-refinement.md)** — Template-driven refinement (complementary to daily standup)
+- **[DevOps Adapter Integration](/integrations/devops-adapter-overview/)** — Project backlog context (`.nold-ai/specfact-backlog.yaml`), env vars, **Git fallback (auto-detect from clone)** for GitHub and Azure DevOps
+- **[Backlog Refinement Guide](/bundles/backlog/refinement/)** — Template-driven refinement (complementary to daily standup)

docs/getting-started/tutorial-openspec-speckit.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: OpenSpec and Speckit Legacy Workflow Note
+permalink: /getting-started/tutorial-openspec-speckit/
+---
+
 # Legacy Workflow Note
 
 This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands.

docs/guides/README.md

@@ -29,14 +29,14 @@ Practical module-owned guides for official bundles, adapters, publishing, and wo
 
 - **[IDE Integration](ide-integration.md)** - Set up slash commands in your IDE
 - **[CoPilot Mode](copilot-mode.md)** - Using `--mode copilot` on CLI commands
-- **[DevOps Adapter Integration](devops-adapter-integration.md)** - Integrate with GitHub Issues, Azure DevOps, Linear, Jira for backlog tracking
-- **[Backlog Refinement](backlog-refinement.md)** - AI-assisted template-driven refinement with filtering and DoR checks
+- **[DevOps Adapter Integration](/integrations/devops-adapter-overview/)** - Integrate with GitHub Issues, Azure DevOps, Linear, Jira for backlog tracking
+- **[Backlog Refinement](/bundles/backlog/refinement/)** - AI-assisted template-driven refinement with filtering and DoR checks
 - **[Specmatic Integration](specmatic-integration.md)** - API contract testing with Specmatic
 - **[Troubleshooting](troubleshooting.md)** - Common issues and solutions
 - **[Installing Modules](installing-modules.md)** - Install, list, show, search, enable/disable, uninstall, and upgrade modules
 - **[Module Marketplace](module-marketplace.md)** - Discovery priority, trust vs origin semantics, and security model
-- **[Custom registries](custom-registries.md)** - Add, list, remove registries; trust levels and priority
-- **[Publishing modules](publishing-modules.md)** - Package, sign, and publish modules to a registry
+- **[Custom registries](/authoring/custom-registries/)** - Add, list, remove registries; trust levels and priority
+- **[Publishing modules](/authoring/publishing-modules/)** - Package, sign, and publish modules to a registry
 - **[Module Signing and Key Rotation](module-signing-and-key-rotation.md)** - Public key placement, signing workflow, CI verification, rotation, and revocation runbook
 - **[Competitive Analysis](competitive-analysis.md)** - How SpecFact compares to other tools
 - **[Operational Modes](../reference/modes.md)** - CI/CD vs CoPilot modes