docs-15: bundle link validation, OpenSpec deltas, Code Review run guide

[djm81]

Summary

This PR continues docs-15-code-review-validation-guardrails (issue #202) with follow-up work already reviewed locally.

Changes

• Published-route vs filesystem links for /bundles/: When a page permalink is under /bundles/ and a link path contains .., validation now requires browser URL resolution to match the resolved markdown target (or report a missing route). Fixes wrong ../../ links that passed filesystem checks but 404ed on the site; updates cross-bundle overview links to root-absolute URLs.
• OpenSpec: Normalized delta spec headings (## MODIFIED Requirements, ### Requirement:, #### Scenario:) so openspec validate docs-15-code-review-validation-guardrails --strict passes for future archive.
• Code Review docs: Expanded docs/bundles/code-review/run.md with worked examples (shadow + JSON, --focus, --path, --level, --bug-hunt, noise/interactive); clarified that run reviews .py/.pyi only and points Markdown site checks to scripts/check-docs-commands.py. Module notes link to the bundle run guide for recipes.

Verification

• python scripts/check-docs-commands.py
• hatch run pytest (docs parity, authored link scan, link-agreement unit tests)
• hatch run contract-test (during earlier commits)
• openspec validate docs-15-code-review-validation-guardrails --strict

Made with Cursor

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4a1cbd26-c877-4d43-bd8c-6aece377ae12

📥 Commits

Reviewing files that changed from the base of the PR and between 940028b and 097111c.

📒 Files selected for processing (2)

• docs/bundles/code-review/run.md
• docs/modules/code-review.md

📜 Recent review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: quality (3.11)
• GitHub Check: quality (3.12)
• GitHub Check: quality (3.13)

🧰 Additional context used

📓 Path-based instructions (1)

docs/**/*.md

⚙️ CodeRabbit configuration file

docs/**/*.md: User-facing and cross-site accuracy: Jekyll front matter, links per documentation-url-contract,
CLI examples matching bundled commands.

Files:

• docs/modules/code-review.md
• docs/bundles/code-review/run.md

🧠 Learnings (3)

📚 Learning: 2026-04-13T10:38:43.524Z

Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-13T10:38:43.524Z
Learning: Fix SpecFact code review findings, including warnings, unless a rare explicit exception is documented

Applied to files:

• docs/modules/code-review.md
• docs/bundles/code-review/run.md

📚 Learning: 2026-04-13T10:38:22.837Z

Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-04-13T10:38:22.837Z
Learning: This repository enforces the clean-code review gate through hatch run specfact code review run --json --out .specfact/code-review.json

Applied to files:

• docs/modules/code-review.md
• docs/bundles/code-review/run.md

📚 Learning: 2026-04-13T10:38:29.379Z

Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-13T10:38:29.379Z
Learning: When a change is paired with work in specfact-cli, review the paired public change artifacts there before widening scope or redefining shared workflow semantics

Applied to files:

• docs/modules/code-review.md
• docs/bundles/code-review/run.md

🔀 Multi-repo context nold-ai/specfact-cli

Findings for nold-ai/specfact-cli

• scripts/check-docs-commands.py exists and is wired into pyproject and CI:

  • pyproject.toml: npm script entry "check-docs-commands = "python scripts/check-docs-commands.py"" [::nold-ai/specfact-cli::pyproject.toml]
  • .github/workflows/docs-review.yml references scripts/check-docs-commands.py (CI will run docs validation) [::nold-ai/specfact-cli::.github/workflows/docs-review.yml]
  • scripts/check-docs-commands.py present at scripts/check-docs-commands.py (used by PR verification) [::nold-ai/specfact-cli::scripts/check-docs-commands.py]

• scripts/check-cross-site-links.py and other docs validation utilities present in scripts/:

  • scripts/check-cross-site-links.py (called by docs-validate composite) [::nold-ai/specfact-cli::scripts/check-cross-site-links.py]
  • scripts/check_doc_frontmatter.py also present and referenced in docs-validate [::nold-ai/specfact-cli::scripts/check_doc_frontmatter.py]

• Repository contains many docs referencing root-relative /bundles/ routes:

  • Multiple docs files reference /bundles/ and the docs permalink contract (e.g., docs/reference/documentation-url-contract.md, docs/reference/core-to-modules-handoff-urls.md) [::nold-ai/specfact-cli::docs/reference/documentation-url-contract.md], [::nold-ai/specfact-cli::docs/reference/core-to-modules-handoff-urls.md]

• I did not find scripts/docs_site_validation.py or tests/unit/scripts/test_docs_site_validation_link_agreement.py in this checkout (those filenames in the PR summary are not present in the current workspace). The scripts/ directory listings show many validation scripts but not docs_site_validation.py or the new test module mentioned in the PR. [::nold-ai/specfact-cli::scripts/]

Assessment / relevance to the PR

• The repo already contains the docs-validation tooling invoked by CI; the PR's behavioral change (requiring published-route agreement for ../ links under /bundles/) would be implemented in the docs validation scripts and their unit tests. The presence of check-docs-commands.py and check-cross-site-links.py indicates CI and tooling will surface any regressions for changed link-resolution semantics. However, I could not locate the specific modified file scripts/docs_site_validation.py or the new unit test file in this checkout to verify the exact changes; confirm the PR indeed adds/updates those files in the feature branch.

🔇 Additional comments (6)

docs/bundles/code-review/run.md (4)

19-20: Accurate Python-only scope and docs-tree validation guidance.

This wording correctly distinguishes Python-path docs/ focus from Markdown-site checks and points to the right validation script.

As per coding guidelines, “document that the pipeline reviews only Python sources (.py/.pyi), clarify --focus docs … and direct modules docs-tree validation to python scripts/check-docs-commands.py.”

---

34-34: --level behavior now matches runtime scoring semantics.

The pre-scoring filter description is precise and consistent with the command surface.

As per coding guidelines, “ensure the --level error|warning semantics are expressed as a pre-scoring severity filter …”

---

60-117: Examples are consistent with targeting and flag-compatibility rules.

The example set cleanly reflects auto-scope, shadow mode, focus facets, positional-file usage, and interactive/noise flows without mixing incompatible controls.

As per coding guidelines, “keep invalid-flag-combination examples consistent with the Typer/runtime behavior (especially around FILES... vs --scope/--path, and --focus vs --include-tests/--exclude-tests).”

---

127-127: Cross-doc link uses stable root-absolute permalink.

Good switch to /modules/code-review/ for published-route safety.

As per coding guidelines, “links per documentation-url-contract.”

docs/modules/code-review.md (2)

47-50: --level filtering text is now contract-accurate.

This correctly states pre-scoring filtering and its effect on score/verdict/JSON/ci_exit_code.

As per coding guidelines, “keep --level error|warning documentation consistent with the run guide: treat it as a pre-scoring filter …”

---

105-108: Module-to-bundle handoff is clear and consistent.

Great pointer to the bundle run guide for copy-pastable recipes while preserving the same Typer behavior narrative.

As per coding guidelines, “point readers to the bundle run guide for copy-pastable recipes … and ensure the module narrative matches the Typer surface/behavior.”

---

📝 Walkthrough

Bundle and module surface

• Code Review bundle docs: expanded docs/bundles/code-review/run.md with detailed examples, flag semantics, and usage notes covering:
  • Supported targets: reviews only .py and .pyi files; --focus docs matches Python files whose path includes a docs/ segment (not Markdown pages).
  • Exact flag behaviors and invalid combinations (positional FILES vs auto-scope, focus vs include/exclude-tests, --out only with --json, etc.).
  • Reporting and scoring semantics: --level error keeps only errors (drops warnings/info) before scoring; --level warning keeps errors+warnings (drops info); omission preserves all severities — JSON, score, verdict, and ci_exit_code reflect the filtered set.
  • Shadow mode: --mode shadow forces process exit 0 and JSON ci_exit_code: 0 while preserving overall_verdict.
  • Examples: auto-discovery, positional files, --path repeats, --bug-hunt with JSON, --no-tests, noise flags, interactive prompts.
• Module docs linking: docs/modules/code-review.md updated to point to the bundle run guide (copy-pastable recipes using the same Typer surface).

Bundle/runtime vs specfact_cli APIs

• No changes to exported runtime APIs, adapters, or command signatures. Documentation now clarifies behavior of the existing specfact code review run surface (Typer validation order and runtime checks) and flags that affect report construction and scoring.
• The run bundle behavior described aligns with current runner behavior (e.g., pre-scoring filtering for --level and shadow JSON/exit semantics); documentation fixes align examples and module notes with implemented behavior.

Manifest and integrity

• No changes to module-package.yaml, semver, signature verification, or registry-related metadata. All edits are documentation, tests, and validation tooling; no package manifests or published artifacts were altered.

Cross-repo / specfact-cli implications

• No required code changes to specfact-cli core; changes are docs and a scripts validator within this repo.
• Consumers who rely on previously ambiguous link-authoring rules for /bundles/ pages should note the stricter validation behavior in the docs/tooling (see scripts/docs_site_validation.py). No dev-dependency path or import contract changes were introduced.
• The new docs-site validation logic is internal to the docs tooling and unit tests; no cross-repo import or contract updates are necessary.

Manifest / module-package effects on registry or consumers

• No impact on published bundles or registry consumers; bundle-owned assets and runner payload locations remain unchanged. Consumers of the Code Review bundle should update their bookmarks to root-absolute permalinks where applicable.

Docs changes and published-site URL contract

• Enforced published-route contract for /bundles/: converted many intra-site relative links from repository-relative (../, ../../) to root-absolute permalinks (/bundles/..., /modules/..., /reference/...) in:
  • docs/bundles/code-review/overview.md
  • docs/bundles/codebase/overview.md
  • docs/bundles/project/overview.md
  • docs/bundles/govern/overview.md
  • docs/bundles/spec/overview.md
  • and updated cross-links within code-review run and module docs.
• Added guidance to run python scripts/check-docs-commands.py for module-docs link/front-matter/command-example validation.

Scripts, tests, and verification

• scripts/docs_site_validation.py: added resolve_internal_link_hybrid() bundle-specific mismatch diagnostics:
  • For pages whose published permalink is under /bundles/ and whose link contains parent traversal (..), resolver now verifies filesystem resolution and browser-permalink (published route) resolution agree; if they diverge returns None and a message suggesting root-absolute paths.
  • Helper functions added to detect .. traversal, classify bundle-published pages, and produce human-readable mismatch labels.
• tests/unit/scripts/test_docs_site_validation_link_agreement.py: new unit tests covering four scenarios:
  1. Reject repo-relative ../../ from deep /bundles/ when disk and browser targets diverge.
  2. Accept root-absolute /... links when target exists.
  3. Preserve filesystem-first semantics for parent traversal outside /bundles/.
  4. Use published-route semantics when filesystem misses sibling-style links within bundles.
• Verification listed in PR objectives: python scripts/check-docs-commands.py, hatch run pytest (docs parity, link-agreement unit tests), hatch run contract-test, and openspec validate ... --strict passed locally per TDD_EVIDENCE.

OpenSpec change ID and scenario coverage

• OpenSpec change: openspec/changes/docs-15-code-review-validation-guardrails
  • Normalized delta headings across five spec documents to canonical form (## MODIFIED Requirements / ### Requirement: / #### Scenario:) to satisfy strict validation.
  • Added explicit validation requirement in specs/modules-docs-command-validation/spec.md: when a page has a canonical published route under /bundles/ and a Markdown link contains parent-directory segments (..), the link must resolve to the same target via filesystem and browser permalink semantics; divergence produces a published-link finding and a non-zero validation exit.
  • Other spec files (bundle-overview-pages, modules-docs-publishing, modules-pre-commit-quality-parity, review-run-command) had only heading/structure normalizations (no semantic changes).

CHANGELOG / release notes

• Changes are documentation, tests, and OpenSpec deltas. Consider a docs/validation bullet in the next CHANGELOG noting stricter /bundles/ link validation and the Code Review run docs clarifications (especially --level pre-scoring semantics and file-type scope).

Risk and review effort

• No runtime API risk. Primary code change is docs-site validation script logic (internal helpers) and unit tests — review effort: medium for the docs-site validator (scripts/docs_site_validation.py changes), low elsewhere. No manifest/registry/signature impacts.

Walkthrough

Standardized bundle overview links to root-relative paths, expanded Code Review run docs with explicit examples and semantics (Python-only focus, --level filtering, shadow mode, JSON output, incompatible flags), added bundle-aware repo-relative link validation in the docs resolver, and added unit tests and OpenSpec doc updates reflecting these behaviors.

Changes

Cohort / File(s)	Summary
Bundle overview link standardization docs/bundles/code-review/overview.md, docs/bundles/codebase/overview.md, docs/bundles/govern/overview.md, docs/bundles/project/overview.md, docs/bundles/spec/overview.md	Converted relative cross-bundle links (../, ../../) to absolute site-root paths (/bundles/..., /modules/..., /reference/...).
Code-review documentation expansion docs/bundles/code-review/run.md, docs/modules/code-review.md	Documented that the review pipeline targets only .py/.pyi; clarified --focus docs semantics; defined --level as a pre-scoring filter; added shadow mode, JSON --out, repeated --focus, positional-files examples, and incompatible-flag guidance; cross-link updated to absolute route.
Docs site validation (bundle-aware) scripts/docs_site_validation.py	Added bundle-specific hybrid resolver behavior: detect .. traversal from pages under /bundles/, compute both filesystem and published-permalink targets, and reject repo-relative links when filesystem and published-route canonical targets diverge; added helper predicates and richer error messaging.
Link agreement tests tests/unit/scripts/test_docs_site_validation_link_agreement.py	New unit tests covering repo-relative rejection for divergent filesystem/published targets, acceptance of root-absolute links, legacy filesystem-first behavior outside bundles, and published-route semantics for sibling-style links under /bundles/.
OpenSpec docs / spec updates openspec/changes/docs-15-code-review-validation-guardrails/*.md, openspec/changes/docs-15-code-review-validation-guardrails/specs/*.md	Reflowed section headers (e.g., "ADDED Requirements" → "MODIFIED Requirements") and normalized scenario heading levels; added requirement describing parent-directory link validation for /bundles/ pages and recorded evidence in TDD_EVIDENCE.md.

Sequence Diagram(s)

sequenceDiagram
    participant AuthoringPage as Authoring Page
    participant Resolver as Docs Resolver
    participant FS as Filesystem
    participant RouteMap as Published Route Map
    AuthoringPage->>Resolver: submit internal link (may contain "..")
    Resolver->>Resolver: detect ".." and is_under_bundles(route)
    alt non-bundles or no ".."
        Resolver->>FS: resolve link via filesystem
        FS-->>Resolver: file path (or None)
        Resolver-->>AuthoringPage: accept/resolve result
    else bundles + ".."
        Resolver->>FS: resolve filesystem target (if any)
        Resolver->>RouteMap: resolve permalink-relative target
        FS-->>Resolver: fs_target (or None)
        RouteMap-->>Resolver: permalink_target (or None)
        Resolver->>Resolver: compare canonical targets
        alt targets match
            Resolver-->>AuthoringPage: accept fs_target
        else targets differ
            Resolver-->>AuthoringPage: return None + published-route mismatch error
        end
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~28 minutes

Possibly related PRs

• Promote dev to main: docs validation, code-review parity, and CI hardening #204 — overlapping changes to docs validation code and tests, including scripts/docs_site_validation.py and docs link checks.
• docs-15 follow-up: single-pass route mapping, tasks scope, parity wording #206 — related refactor and link-resolution edits in the same validation code paths.
• docs: add missing command reference pages #114 — touches the same Code Review docs and bundle overview link surfaces adjusted here.

Suggested labels

openspec

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	Title does not follow Conventional Commits-style prefixes; uses descriptive format instead of 'docs:', 'fix:', etc.	Reformat title to use Conventional Commits prefix, e.g., 'docs: bundle link validation, OpenSpec deltas, Code Review run guide'
Description check	❓ Inconclusive	PR description provides substantive context and verification steps but omits most required template sections (Scope, Bundle Impact, local gates, signature checks, CI alignment).	Complete template sections: mark relevant Scope checkboxes, list any version bumps under Bundle Impact, document which local gates passed, and confirm signature/CI status.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 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.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 940028be3a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".