nold-ai · djm81 · Mar 20, 2026 · Mar 20, 2026 · Mar 20, 2026
diff --git a/.github/workflows/docs-review.yml b/.github/workflows/docs-review.yml
@@ -0,0 +1,62 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
+# yamllint disable rule:line-length rule:truthy
+name: Docs Review
+
+on:
+  pull_request:
+    branches: [main, dev]
+    paths:
+      - "**/*.md"
+      - "**/*.mdc"
+      - "docs/**"
+      - "tests/unit/docs/test_release_docs_parity.py"
+      - ".github/workflows/docs-review.yml"
+  push:
+    branches: [main, dev]
+    paths:
+      - "**/*.md"
+      - "**/*.mdc"
+      - "docs/**"
+      - "tests/unit/docs/test_release_docs_parity.py"
+      - ".github/workflows/docs-review.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  docs-review:
+    name: Docs Review
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install docs review dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install pytest
+
+      - name: Run docs review suite
+        run: |
+          mkdir -p logs/docs-review
+          DOCS_REVIEW_LOG="logs/docs-review/docs-review_$(date -u +%Y%m%d_%H%M%S).log"
+          python -m pytest tests/unit/docs/test_release_docs_parity.py -q 2>&1 | tee "$DOCS_REVIEW_LOG"
+          exit "${PIPESTATUS[0]:-$?}"
+
+      - name: Upload docs review logs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-review-logs
+          path: logs/docs-review/
+          if-no-files-found: ignore
diff --git a/docs/adapters/backlog-adapter-patterns.md b/docs/adapters/backlog-adapter-patterns.md
@@ -493,4 +493,4 @@ When implementing new backlog adapters:
 - **[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
+- **[Bridge Adapter Interface](../reference/architecture.md#required-adapter-interface)** - Base adapter interface
diff --git a/docs/examples/integration-showcases/README.md b/docs/examples/integration-showcases/README.md
@@ -39,7 +39,7 @@ This folder contains everything you need to understand and test SpecFact CLI int
 
 ### Setup Script
 
-1. **[`setup-integration-tests.sh`](setup-integration-tests.sh)** 🚀 **AUTOMATED SETUP**
+1. **[`setup-integration-tests.sh`](https://github.com/nold-ai/specfact-cli/blob/main/docs/examples/integration-showcases/setup-integration-tests.sh)** 🚀 **AUTOMATED SETUP**
 
    - **Purpose**: Automated script to create test cases for all examples
    - **Content**: Creates test directories, sample code, and configuration files
@@ -59,7 +59,7 @@ This gives you a complete overview of what SpecFact can do with real examples.
 
 **Step 2**: Choose your path:
 
-- **Want to test the examples?** → Use [`setup-integration-tests.sh`](setup-integration-tests.sh) then follow [`integration-showcases-testing-guide.md`](integration-showcases-testing-guide.md)
+- **Want to test the examples?** → Use [`setup-integration-tests.sh`](https://github.com/nold-ai/specfact-cli/blob/main/docs/examples/integration-showcases/setup-integration-tests.sh) then follow [`integration-showcases-testing-guide.md`](integration-showcases-testing-guide.md)
 
 - **Just need quick commands?** → Check [`integration-showcases-quick-reference.md`](integration-showcases-quick-reference.md)
 

diff --git a/docs/examples/quick-examples.md b/docs/examples/quick-examples.md
@@ -1,7 +1,9 @@
 ---
 layout: default
 title: Quick Examples
-permalink: /quick-examples/
+permalink: /examples/quick-examples/
+redirect_from:
+  - /quick-examples/
 ---
 
 # Quick Examples

diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -541,4 +541,4 @@ hatch run format
 hatch run lint
 ```
 
-See [CONTRIBUTING.md](../../CONTRIBUTING.md) for detailed contribution guidelines.
+See [CONTRIBUTING.md](https://github.com/nold-ai/specfact-cli/blob/main/CONTRIBUTING.md) for detailed contribution guidelines.
diff --git a/docs/getting-started/tutorial-openspec-speckit.md b/docs/getting-started/tutorial-openspec-speckit.md
@@ -688,4 +688,4 @@ gh repo view your-org/your-repo
 
 Copyright © 2025-2026 Nold AI (Owner: Dominikus Nold)
 
-**Trademarks**: All product names, logos, and brands mentioned in this documentation are the property of their respective owners. NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). See [TRADEMARKS.md](../../TRADEMARKS.md) for more information.
+**Trademarks**: All product names, logos, and brands mentioned in this documentation are the property of their respective owners. NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). See [TRADEMARKS.md](/TRADEMARKS/) for more information.
diff --git a/docs/guides/ai-ide-workflow.md b/docs/guides/ai-ide-workflow.md
@@ -1,7 +1,9 @@
 ---
 layout: default
 title: AI IDE Workflow Guide
-permalink: /ai-ide-workflow/
+permalink: /guides/ai-ide-workflow/
+redirect_from:
+  - /ai-ide-workflow/
 ---
 
 # AI IDE Workflow Guide

diff --git a/docs/guides/brownfield-engineer.md b/docs/guides/brownfield-engineer.md
@@ -1,7 +1,9 @@
 ---
 layout: default
 title: Modernizing Legacy Code (Brownfield Engineer Guide)
-permalink: /brownfield-engineer/
+permalink: /guides/brownfield-engineer/
+redirect_from:
+  - /brownfield-engineer/
 ---
 
 # Guide for Legacy Modernization Engineers

diff --git a/docs/guides/brownfield-journey.md b/docs/guides/brownfield-journey.md
@@ -1,7 +1,9 @@
 ---
 layout: default
 title: Brownfield Modernization Journey
-permalink: /brownfield-journey/
+permalink: /guides/brownfield-journey/
+redirect_from:
+  - /brownfield-journey/
 ---
 
 # Brownfield Modernization Journey

diff --git a/docs/guides/common-tasks.md b/docs/guides/common-tasks.md
@@ -1,7 +1,9 @@
 ---
 layout: default
 title: Common Tasks Quick Reference
-permalink: /common-tasks/
+permalink: /guides/common-tasks/
+redirect_from:
+  - /common-tasks/
 ---
 
 # Common Tasks Quick Reference

diff --git a/docs/guides/competitive-analysis.md b/docs/guides/competitive-analysis.md
@@ -1,7 +1,9 @@
 ---
 layout: default
 title: Competitive Analysis
-permalink: /competitive-analysis/
+permalink: /guides/competitive-analysis/
+redirect_from:
+  - /competitive-analysis/
 ---
 
 # What You Gain with SpecFact CLI

diff --git a/docs/guides/copilot-mode.md b/docs/guides/copilot-mode.md
@@ -1,7 +1,9 @@
 ---
 layout: default
 title: Using CoPilot Mode
-permalink: /copilot-mode/
+permalink: /guides/copilot-mode/
+redirect_from:
+  - /copilot-mode/
 ---
 
 # Using CoPilot Mode

diff --git a/docs/guides/ide-integration.md b/docs/guides/ide-integration.md
@@ -342,4 +342,4 @@ The `specfact init` command handles all conversions automatically.
 
 ---
 
-**Trademarks**: All product names, logos, and brands mentioned in this guide are the property of their respective owners. NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). See [TRADEMARKS.md](../../TRADEMARKS.md) for more information.
+**Trademarks**: All product names, logos, and brands mentioned in this guide are the property of their respective owners. NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). See [TRADEMARKS.md](/TRADEMARKS/) for more information.
diff --git a/docs/guides/migration-guide.md b/docs/guides/migration-guide.md
@@ -1,7 +1,9 @@
 ---
 layout: default
 title: Migration Guide
-permalink: /migration-guide/
+permalink: /guides/migration-guide/
+redirect_from:
+  - /migration-guide/
 ---
 
 # Migration Guide

diff --git a/docs/guides/team-collaboration-workflow.md b/docs/guides/team-collaboration-workflow.md
@@ -1,7 +1,9 @@
 ---
 layout: default
 title: Team Collaboration Workflow
-permalink: /team-collaboration-workflow/
+permalink: /guides/team-collaboration-workflow/
+redirect_from:
+  - /team-collaboration-workflow/
 ---
 
 # Team Collaboration Workflow

diff --git a/docs/guides/testing-terminal-output.md b/docs/guides/testing-terminal-output.md
@@ -1,7 +1,9 @@
 ---
 layout: default
 title: Testing Terminal Output Modes
-permalink: /testing-terminal-output/
+permalink: /guides/testing-terminal-output/
+redirect_from:
+  - /testing-terminal-output/
 ---
 
 # Testing Terminal Output Modes

diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md
@@ -1,7 +1,9 @@
 ---
 layout: default
 title: Troubleshooting
-permalink: /troubleshooting/
+permalink: /guides/troubleshooting/
+redirect_from:
+  - /troubleshooting/
 ---
 
 # Troubleshooting

diff --git a/docs/guides/use-cases.md b/docs/guides/use-cases.md
@@ -1,7 +1,9 @@
 ---
 layout: default
 title: Use Cases
-permalink: /use-cases/
+permalink: /guides/use-cases/
+redirect_from:
+  - /use-cases/
 ---
 
 # Use Cases

diff --git a/docs/guides/ux-features.md b/docs/guides/ux-features.md
@@ -1,7 +1,9 @@
 ---
 layout: default
 title: UX Features Guide
-permalink: /ux-features/
+permalink: /guides/ux-features/
+redirect_from:
+  - /ux-features/
 ---
 
 # UX Features Guide

diff --git a/docs/openspec-opsx-migration.md b/docs/openspec-opsx-migration.md
@@ -20,7 +20,7 @@ SpecFact CLI has migrated to **OpenSpec OPSX** (fluid, action-based workflow). P
 
 - **Project context import**: When syncing OpenSpec project context, the bridge resolves `openspec/config.yaml` first; if absent, it uses `openspec/project.md`. No code changes required in repos that still have `project.md`.
 - **Detection**: OpenSpec is detected if `openspec/config.yaml`, `openspec/project.md`, or `openspec/specs/` exists.
-- **Config format**: See [openspec/config.yaml](../openspec/config.yaml) in this repo for an example. The `context:` block is injected into planning; `rules:` apply per-artifact.
+- **Config format**: See [openspec/config.yaml](https://github.com/nold-ai/specfact-cli/blob/main/openspec/config.yaml) in this repo for an example. The `context:` block is injected into planning; `rules:` apply per-artifact.
 
 ## References
 

diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md
@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Architecture
-permalink: /architecture/
+permalink: /reference/architecture/
 ---
 
 # Architecture

diff --git a/docs/reference/debug-logging.md b/docs/reference/debug-logging.md
@@ -1,7 +1,9 @@
 ---
 layout: default
 title: Debug Logging
-permalink: /debug-logging/
+permalink: /reference/debug-logging/
+redirect_from:
+  - /debug-logging/
 ---
 
 <!-- markdownlint-disable-next-line MD025 -->

diff --git a/docs/reference/directory-structure.md b/docs/reference/directory-structure.md
@@ -1,7 +1,9 @@
 ---
 layout: default
 title: SpecFact CLI Directory Structure
-permalink: /directory-structure/
+permalink: /reference/directory-structure/
+redirect_from:
+  - /directory-structure/
 ---
 
 # SpecFact CLI Directory Structure

diff --git a/docs/reference/modes.md b/docs/reference/modes.md
@@ -1,7 +1,9 @@
 ---
 layout: default
 title: Operational Modes
-permalink: /modes/
+permalink: /reference/modes/
+redirect_from:
+  - /modes/
 ---
 
 # Operational Modes

diff --git a/docs/reference/parameter-standard.md b/docs/reference/parameter-standard.md
@@ -237,9 +237,9 @@ def generate_contracts(
 
 ## 🔗 Related Documentation
 
-- **[CLI Reorganization Implementation Plan](../../specfact-cli-internal/docs/internal/implementation/CLI_REORGANIZATION_IMPLEMENTATION_PLAN.md)** - Full reorganization plan
-- **[Command Reference](./commands.md)** - Complete command reference
-- **[Project Bundle Refactoring Plan](../../specfact-cli-internal/docs/internal/implementation/PROJECT_BUNDLE_REFACTORING_PLAN.md)** - Bundle parameter requirements
+- **[Command Reference](./commands.md)** - Complete command reference and current parameter surfaces
+- **[Directory Structure](./directory-structure.md)** - Repository and workspace parameter context
+- **[Architecture](./architecture.md)** - Runtime and adapter architecture context for parameter design
 
 ---
 

diff --git a/docs/reference/schema-versioning.md b/docs/reference/schema-versioning.md
@@ -1,7 +1,9 @@
 ---
 layout: default
 title: Schema Versioning
-permalink: /schema-versioning/
+permalink: /reference/schema-versioning/
+redirect_from:
+  - /schema-versioning/
 ---
 
 # Schema Versioning
@@ -174,5 +176,5 @@ schema_metadata:
 ## Related Documentation
 
 - [Architecture - Change Tracking Models](../reference/architecture.md#change-tracking-models-v11-schema) - Technical details
-- [Architecture - Bridge Adapter Interface](../reference/architecture.md#bridge-adapter-interface) - Adapter implementation guide
+- [Architecture - Required Adapter Interface](../reference/architecture.md#required-adapter-interface) - Adapter implementation guide
 - [Directory Structure](directory-structure.md) - Bundle file organization
diff --git a/docs/technical/README.md b/docs/technical/README.md
@@ -17,7 +17,7 @@ Technical documentation for contributors and developers working on SpecFact CLI.
 
 ### Maintenance Scripts
 
-For maintenance scripts and developer utilities, see the [Contributing Guide](../../CONTRIBUTING.md#developer-tools) section on Developer Tools. This includes:
+For maintenance scripts and developer utilities, see the [Contributing Guide](https://github.com/nold-ai/specfact-cli/blob/main/CONTRIBUTING.md#developer-tools) section on Developer Tools. This includes:
 
 - **Cleanup Acceptance Criteria Script** - Removes duplicate replacement instruction text from acceptance criteria
 - Other maintenance and development utilities in the `scripts/` directory

diff --git a/openspec/CHANGE_ORDER.md b/openspec/CHANGE_ORDER.md
@@ -90,6 +90,7 @@ These are derived extensions of the same 2026-02-15 plan and are required to ope
 |--------|-------|---------------|----------|------------|
 | docs | 01 | docs-01-core-modules-docs-alignment | [#348](https://github.com/nold-ai/specfact-cli/issues/348) | module-migration-01 ✅; module-migration-02 ✅; module-migration-03 ✅; module-migration-05 ✅; module-migration-06/07 outputs inform residual cleanup wording |
 | docs | 03 | ✅ docs-03-command-syntax-parity (archived 2026-03-18) | pending | docs-01 ✅; docs-02 ✅ |
+| docs | 04 | docs-04-docs-review-gate-and-link-integrity | pending | docs-03 ✅ |
 
 ### Marketplace (module distribution)
 

diff --git a/openspec/changes/docs-04-docs-review-gate-and-link-integrity/.openspec.yaml b/openspec/changes/docs-04-docs-review-gate-and-link-integrity/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/docs-04-docs-review-gate-and-link-integrity/CHANGE_VALIDATION.md b/openspec/changes/docs-04-docs-review-gate-and-link-integrity/CHANGE_VALIDATION.md
@@ -0,0 +1,5 @@
+# Change Validation
+
+- Timestamp: 2026-03-20T14:42:35+01:00
+- Command: `openspec validate docs-04-docs-review-gate-and-link-integrity --strict`
+- Result: `Change 'docs-04-docs-review-gate-and-link-integrity' is valid`
diff --git a/openspec/changes/docs-04-docs-review-gate-and-link-integrity/TDD_EVIDENCE.md b/openspec/changes/docs-04-docs-review-gate-and-link-integrity/TDD_EVIDENCE.md
@@ -0,0 +1,25 @@
+# TDD Evidence
+
+## Pre-Implementation Failing Run
+
+- Timestamp: 2026-03-20T14:31:44+01:00
+- Command: `hatch run pytest tests/unit/docs/test_release_docs_parity.py -q`
+- Result: failed
+
+### Failure Summary
+
+- `test_navigation_links_resolve_to_published_docs_routes` failed because the first validator pass still treated Jekyll `{{ ... | relative_url }}` expressions and non-page assets such as `feed.xml` and `assets/main.css` as literal docs routes.
+- `test_authored_internal_docs_links_resolve_to_published_docs_targets` failed because authored docs still mixed true published-route drift with links to non-published repo files and missing published targets.
+- The failing run surfaced the underlying docs regressions that motivated this change, including sidebar routes such as `/reference/directory-structure/`, `/reference/architecture/`, and multiple `/guides/...` links that did not match the authored page permalinks.
+
+## Post-Implementation Passing Run
+
+- Timestamp: 2026-03-20T14:40:50+01:00
+- Command: `hatch run pytest tests/unit/docs/test_release_docs_parity.py -q`
+- Result: passed
+
+### Verification Summary
+
+- The route-aware docs parity suite passed after normalizing guide/reference/example permalinks to the published section routes used by sidebar navigation.
+- Broken authored links to missing repo-local files were replaced with valid published docs targets or GitHub source links where the target is intentionally not a published docs page.
+- The dedicated `Docs Review` workflow now provides a fast mandatory-check path for docs-only changes without waiting for the full code-oriented PR orchestrator.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -688,4 +688,4 @@ gh repo view your-org/your-repo

		Copyright © 2025-2026 Nold AI (Owner: Dominikus Nold)

		Trademarks: All product names, logos, and brands mentioned in this documentation are the property of their respective owners. NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). See [TRADEMARKS.md](../../TRADEMARKS.md) for more information.
		Trademarks: All product names, logos, and brands mentioned in this documentation are the property of their respective owners. NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). See [TRADEMARKS.md](/TRADEMARKS/) for more information.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -342,4 +342,4 @@ The `specfact init` command handles all conversions automatically.

		---

		Trademarks: All product names, logos, and brands mentioned in this guide are the property of their respective owners. NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). See [TRADEMARKS.md](../../TRADEMARKS.md) for more information.
		Trademarks: All product names, logos, and brands mentioned in this guide are the property of their respective owners. NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). See [TRADEMARKS.md](/TRADEMARKS/) for more information.