Promote dev to main

.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

@@ -64,7 +64,7 @@ The adapter automatically derives work item type from your project's process tem
 You can override with `--ado-work-item-type`:
 
 ```bash
-specfact project sync bridge --adapter ado --mode export-only \
+specfact sync bridge --adapter ado --mode export-only \
   --ado-org your-org \
   --ado-project your-project \
   --ado-work-item-type "Bug" \
@@ -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
 
@@ -434,7 +434,7 @@ This handles cases where:
 
 ```bash
 # Export OpenSpec change proposals to Azure DevOps work items
-specfact project sync bridge --adapter ado --mode export-only \
+specfact sync bridge --adapter ado --mode export-only \
   --ado-org your-org \
   --ado-project your-project \
   --repo /path/to/openspec-repo
@@ -444,7 +444,7 @@ specfact project sync bridge --adapter ado --mode export-only \
 
 ```bash
 # Import work items AND export proposals
-specfact project sync bridge --adapter ado --bidirectional \
+specfact sync bridge --adapter ado --bidirectional \
   --ado-org your-org \
   --ado-project your-project \
   --repo /path/to/openspec-repo
@@ -454,7 +454,7 @@ specfact project sync bridge --adapter ado --bidirectional \
 
 ```bash
 # Import specific work items into bundle
-specfact project sync bridge --adapter ado --mode bidirectional \
+specfact sync bridge --adapter ado --mode bidirectional \
   --ado-org your-org \
   --ado-project your-project \
   --bundle main \
@@ -466,7 +466,7 @@ specfact project sync bridge --adapter ado --mode bidirectional \
 
 ```bash
 # Update existing work item with latest proposal content
-specfact project sync bridge --adapter ado --mode export-only \
+specfact sync bridge --adapter ado --mode export-only \
   --ado-org your-org \
   --ado-project your-project \
   --change-ids add-feature-x \
@@ -478,7 +478,7 @@ specfact project sync bridge --adapter ado --mode export-only \
 
 ```bash
 # Detect code changes and add progress comments
-specfact project sync bridge --adapter ado --mode export-only \
+specfact sync bridge --adapter ado --mode export-only \
   --ado-org your-org \
   --ado-project your-project \
   --track-code-changes \
@@ -490,7 +490,7 @@ specfact project sync bridge --adapter ado --mode export-only \
 
 ```bash
 # Export from bundle to ADO (uses stored lossless content)
-specfact project sync bridge --adapter ado --mode export-only \
+specfact sync bridge --adapter ado --mode export-only \
   --ado-org your-org \
   --ado-project your-project \
   --bundle main \
@@ -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

@@ -334,14 +334,14 @@ To create a GitHub issue from an OpenSpec change and have the issue number/URL w
 
 ```bash
 # Export one or more changes; creates issues and updates proposal.md Source Tracking
-specfact project sync bridge --adapter github --mode export-only \
+specfact sync bridge --adapter github --mode export-only \
   --repo . \
   --repo-owner nold-ai \
   --repo-name specfact-cli \
   --change-ids <change-id>
 
 # Example: export backlog-scrum-05-summarize-markdown-output
-specfact project sync bridge --adapter github --mode export-only \
+specfact sync bridge --adapter github --mode export-only \
   --repo . \
   --repo-owner nold-ai \
   --repo-name specfact-cli \
@@ -354,23 +354,23 @@ 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
 
 When you improve comment logic or branch detection, use `--include-archived` to update existing GitHub issues for archived proposals:
 
 ```bash
 # Update all archived proposals with new comment logic
-specfact project sync bridge --adapter github --mode export-only \
+specfact sync bridge --adapter github --mode export-only \
   --repo-owner your-org \
   --repo-name your-repo \
   --include-archived \
   --update-existing \
   --repo /path/to/openspec-repo
 
 # Update specific archived proposal
-specfact project sync bridge --adapter github --mode export-only \
+specfact sync bridge --adapter github --mode export-only \
   --repo-owner your-org \
   --repo-name your-repo \
   --change-ids add-code-change-tracking \
@@ -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

@@ -555,7 +555,7 @@ The most common workflow is to refine backlog items and then sync them to extern
 **Workflow**: `backlog ceremony refinement` → `sync bridge`
 
 1. **Refine Backlog Items**: Use `specfact backlog ceremony refinement` to standardize backlog items with templates
-2. **Sync to External Tools**: Use `specfact project sync bridge` to sync refined items back to backlog tools (GitHub, ADO, etc.)
+2. **Sync to External Tools**: Use `specfact sync bridge` to sync refined items back to backlog tools (GitHub, ADO, etc.)
 
 ```bash
 # Complete command chaining workflow
@@ -567,7 +567,7 @@ specfact backlog ceremony refinement github \
   --state open
 
 # 2. Sync refined items to external tool (same or different adapter)
-specfact project sync bridge --adapter github \
+specfact sync bridge --adapter github \
   --repo-owner my-org --repo-name my-repo \
   --backlog-ids 123,456 \
   --mode export-only
@@ -578,7 +578,7 @@ specfact backlog ceremony refinement github \
   --write \
   --labels feature
 
-specfact project sync bridge --adapter ado \
+specfact sync bridge --adapter ado \
   --ado-org my-org --ado-project my-project \
   --backlog-ids 123,456 \
   --mode export-only
@@ -614,12 +614,12 @@ When syncing backlog items between different adapters (e.g., GitHub ↔ ADO), Sp
 
 ```bash
 # 1. Import closed GitHub issues into bundle (state "closed" is preserved)
-specfact project sync bridge --adapter github --mode bidirectional \
+specfact sync bridge --adapter github --mode bidirectional \
   --repo-owner nold-ai --repo-name specfact-cli \
   --backlog-ids 110,122
 
 # 2. Export to ADO (state is automatically mapped: closed → Closed)
-specfact project sync bridge --adapter ado --mode export-only \
+specfact sync bridge --adapter ado --mode export-only \
   --ado-org dominikusnold --ado-project "SpecFact CLI" \
   --bundle cross-sync-test --change-ids add-ado-backlog-adapter,add-template-driven-backlog-refinement
 
@@ -646,14 +646,14 @@ specfact project sync bridge --adapter ado --mode export-only \
 
 Backlog refinement works seamlessly with the [DevOps Adapter Integration](/integrations/devops-adapter-overview/):
 
-1. **Import Backlog Items**: Use `specfact project sync bridge` to import backlog items as OpenSpec proposals
+1. **Import Backlog Items**: Use `specfact sync bridge` to import backlog items as OpenSpec proposals
 2. **Refine Items**: Use `specfact backlog ceremony refinement` to standardize imported items
-3. **Export Refined Items**: Use `specfact project sync bridge` to export refined proposals back to backlog tools
+3. **Export Refined Items**: Use `specfact sync bridge` to export refined proposals back to backlog tools
 
 ```bash
 # Complete workflow
 # 1. Import GitHub issues as OpenSpec proposals
-specfact project sync bridge --adapter github --mode bidirectional \
+specfact sync bridge --adapter github --mode bidirectional \
   --repo-owner my-org --repo-name my-repo \
   --backlog-ids 123,456
 
@@ -662,7 +662,7 @@ specfact backlog ceremony refinement github --bundle my-project --auto-bundle \
   --search "is:open"
 
 # 3. Export refined proposals back to GitHub
-specfact project sync bridge --adapter github --mode export-only \
+specfact sync bridge --adapter github --mode export-only \
   --bundle my-project --change-ids <refined-change-id>
 ```
 
@@ -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:
 
@@ -938,11 +937,11 @@ If adapter search methods are not available:
 # "Note: GitHub issue fetching requires adapter.search_issues() implementation"
 ```
 
-**Workaround**: Use `specfact project sync bridge` to import backlog items first, then refine:
+**Workaround**: Use `specfact sync bridge` to import backlog items first, then refine:
 
 ```bash
 # 1. Import backlog items
-specfact project sync bridge --adapter github --mode bidirectional \
+specfact sync bridge --adapter github --mode bidirectional \
   --backlog-ids 123,456
 
 # 2. Refine imported items from bundle