docs-15 follow-up: single-pass route mapping, tasks scope, parity wording

[djm81]

Summary

Follow-up on docs-15 code review validation guardrails after prior merges to dev.

Changes

• scripts/docs_site_validation.py: Add build_route_mappings() so route_to_path and path_to_route are built in one pass over the docs tree; scan_published_route_body_links, build_valid_internal_routes, and build_route_index / build_path_to_canonical_route use it (no double full-tree reads for link scanning).
• OpenSpec tasks.md: Clarify that §6 CI/pre-commit/docs artifacts are owned by specfact-cli-modules, not the paired specfact-cli repo unless explicitly coordinated.
• Docs + tests: Replace private-helper names in user docs with behavior-facing phrases (review flags, request validation, conflicting targeting styles); parity tests assert those phrases instead of symbol names. test_docs_review.py uses build_route_mappings once for nav resolution.

Verification

• Pre-commit (including contract test slice) passed locally for the commit.
• pytest tests/unit/docs/test_code_review_docs_parity.py tests/unit/docs/test_docs_review.py and python scripts/check-docs-commands.py were run during development.

Made with Cursor

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4b5b4324-e1ac-4c76-9500-6ec980456b74

📥 Commits

Reviewing files that changed from the base of the PR and between 5fb5a28 and 97c2ed9.

📒 Files selected for processing (6)

• docs/bundles/code-review/run.md
• docs/modules/code-review.md
• openspec/changes/docs-15-code-review-validation-guardrails/tasks.md
• scripts/docs_site_validation.py
• tests/unit/docs/test_code_review_docs_parity.py
• tests/unit/docs/test_docs_review.py

---

📝 Walkthrough

Pull Request Summary: docs-15 follow-up (Single-Pass Route Mapping & Parity Wording)

Bundles and Modules Surface

No command interface, adapter, or runtime behavior changes. This PR is purely documentation and internal validation infrastructure:

• Docs accuracy for specfact-code-review: Updated docs/bundles/code-review/run.md and docs/modules/code-review.md to describe CLI flag validation using behavior-facing language ("review flags", "request validation", "conflicting targeting styles") instead of internal helper function names. Runtime error messages and exit codes remain unchanged.
• Docs URL contract integrity: No routing or publishing changes; all existing published permalinks remain bound to the same markdown sources.

Manifest and Registry

No changes to module-package.yaml, pyproject.toml versioning, or publish workflows:

• All six module manifests (packages/specfact-*/module-package.yaml) unchanged
• No semver bump or version string updates (remains 0.1.0)
• No registry publication impacts

Internal Tooling Optimization

Refactored scripts/docs_site_validation.py (documentation validation, not deployed code):

• New build_route_mappings(docs_root) function performs single traversal producing both route_to_path and path_to_route mappings
• Public functions build_route_index() and build_path_to_canonical_route() now delegate to build_route_mappings()—signatures unchanged, implementations optimized
• Reduces redundant doc-tree reads in link scanning and route validation workflows
• Updated test_code_review_docs_parity.py assertions to verify human-readable phrases instead of symbol names
• Simplified test_docs_review.py to call build_route_mappings() once for navigation resolution

Cross-Repo Coordination: specfact-cli

No required specfact-cli changes. OpenSpec clarification added to openspec/changes/docs-15-code-review-validation-guardrails/tasks.md:

• §6 ("Local And CI Gate Integration") now explicitly states that CI/pre-commit/docs validation artifacts are implemented and maintained in nold-ai/specfact-cli-modules repository
• Clarifies that these artifacts should not be expected in the paired nold-ai/specfact-cli dev branch unless separately coordinated
• Eliminates sync confusion between repositories; no contract or import changes required

Verification

Pre-commit checks (including contract test slice) and targeted unit tests passed locally:

• pytest tests/unit/docs/test_code_review_docs_parity.py tests/unit/docs/test_docs_review.py
• python scripts/check-docs-commands.py

Walkthrough

The PR updates documentation describing CLI flag validation order in the code-review command, clarifies implementation location in the openspec tracking file, and refactors the docs validation script to consolidate route and path mappings into a single unified builder function while updating corresponding tests.

Changes

Cohort / File(s)	Summary
Documentation clarifications docs/bundles/code-review/run.md, docs/modules/code-review.md	Updated validation order descriptions for incompatible CLI flag combinations, removing references to specific helper function names and clarifying when checks occur in the pipeline.
Openspec tracking openspec/changes/docs-15-code-review-validation-guardrails/tasks.md	Added note clarifying that docs-validation deliverables are maintained in nold-ai/specfact-cli-modules, not expected in nold-ai/specfact-cli dev branch.
Docs validation script refactoring scripts/docs_site_validation.py	Introduced build_route_mappings() to unify route-to-path and path-to-route construction in a single traversal; refactored existing functions to call this consolidation point, reducing redundant file processing.
Test updates tests/unit/docs/test_code_review_docs_parity.py, tests/unit/docs/test_docs_review.py	Updated assertions to use descriptive phrases ("review flags", "request validation", "conflicting targeting styles") instead of internal function names; adjusted docs route-building calls to use new unified build_route_mappings().

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• [Change] Docs validation guardrails for Code Review docs and module links #202: Directly addresses the docs-15 code-review validation guardrails initiative mentioned in the openspec tracking file within this PR.

Possibly related PRs

• docs(docs-15): modules docs validation guardrails and code-review parity #203: Modifies the same docs validation codepaths and tests, switching to the consolidated route/path mapping logic.
• Promote dev to main: code review hardening, sidecar FastAPI, CI signing #193: Updates CLI flag validation documentation and test coverage, relating to the validation logic reassignment described in this PR's doc changes.
• docs: URL contract, legacy /guides/ redirects, and docs-06 follow-up #109: Modifies the docs test harness and route-building logic for the docs site validation pipeline.

Suggested labels

documentation, enhancement, openspec

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/docs-15-validation-followup-2

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}