Conversation
…rity Add shared docs site validation (published routes, front matter, optional bundle check), wire pre-commit and docs CI, fix overview/guide links and Gemfile.lock, align code-review module docs with the run guide. Harden the git-branch signature flag test: use git commit --no-verify in the fixture repo and scrub inherited GIT_DIR-style env vars so nested git never touches the outer worktree. Tracks openspec change docs-15-code-review-validation-guardrails. Made-with: Cursor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (13)
📜 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)
🧰 Additional context used📓 Path-based instructions (5)docs/**/*.md⚙️ CodeRabbit configuration file
Files:
openspec/**/*.md⚙️ CodeRabbit configuration file
Files:
**/*.{js,ts,tsx,jsx,py,java,cs,go,rb,php,cpp,c,h}📄 CodeRabbit inference engine (CLAUDE.md)
Files:
tests/**/*.py⚙️ CodeRabbit configuration file
Files:
scripts/**/*.py⚙️ CodeRabbit configuration file
Files:
🧠 Learnings (10)📓 Common learnings📚 Learning: 2026-04-13T10:38:22.837ZApplied to files:
📚 Learning: 2026-04-13T10:38:29.379ZApplied to files:
📚 Learning: 2026-04-13T10:38:43.524ZApplied to files:
📚 Learning: 2026-04-13T10:38:15.842ZApplied to files:
📚 Learning: 2026-04-13T10:38:43.524ZApplied to files:
📚 Learning: 2026-04-13T10:38:29.379ZApplied to files:
📚 Learning: 2026-04-02T21:49:11.371ZApplied to files:
📚 Learning: 2026-04-13T10:38:22.837ZApplied to files:
📚 Learning: 2026-04-13T10:38:29.379ZApplied to files:
🪛 LanguageToolopenspec/changes/docs-15-code-review-validation-guardrails/specs/bundle-overview-pages/spec.md[grammar] ~19-~19: Use a hyphen to join words. (QB_NEW_EN_HYPHEN) 🔀 Multi-repo context nold-ai/specfact-clinold-ai/specfact-cli
Risk / review notes (observed in repo files):
Conclusion: The PR introduces a new validator API and wires it into scripts, tests, pre-commit, and GitHub Actions. Cross-repo impact is contained within this repository (consumers and tests live here), but reviewers should pay attention to:
🔇 Additional comments (22)
📝 WalkthroughBundle and Module SurfaceNo module manifest or API surface changes. All Manifest and IntegrityNo version bumps or signature changes required. Module manifests and their signatures remain untouched. The PR scope is CI/workflow and documentation only. Local validation (documented in Cross-Repo: specfact-cli Contract Alignmentspecfact-cli 0.46.2 pinned in
The new test module Docs: modules.specfact.io Accuracy and Documentation ContractPublished-route link semantics hardened via new Bundle and module overview links fixed to use parent-relative paths ( Guide front-matter completeness: added missing Navigation and "Getting Started" links updated in guides/README.md, getting-started/README.md, openspec-journey.md, and reference/README.md to use correct relative or site-root-relative paths ( Test Infrastructure: Signature Verification IsolationRegression test fix in OpenSpec Change CoverageOpenSpec change ID: Specifications defined:
Coverage: 618 contract tests passed; docs command checks, format/lint, and WalkthroughAdds a published-route-aware docs validation system (new scripts/docs_site_validation.py), integrates it into scripts/check-docs-commands.py, CI workflows, pre-commit gates, and unit tests, and updates documentation links and front-matter to match published permalink semantics. Changes
Sequence Diagram(s)sequenceDiagram
participant Author as Docs (Markdown)
participant Index as Route Index (build_route_index)
participant Resolver as Link Resolver (resolve_internal_link_hybrid)
participant Checker as Validator (scan_published_route_body_links / scan_frontmatter_findings)
participant CI as CI / Pre-commit Gate
Author->>Index: Extract front matter (permalink, redirect_from)
Index-->>Index: Build canonical route mappings
Author->>Resolver: Extract links with line numbers
Resolver->>Index: Resolve link against published routes
alt Resolved
Resolver-->>Checker: OK (no finding)
else Unresolved
Resolver-->>Checker: Emit [published-link] finding (path:line)
end
Author->>Checker: Validate required front-matter keys
alt Missing required keys
Checker-->>Checker: Emit [frontmatter] finding
end
Checker->>CI: Return findings (non-zero if blocking)
CI->>CI: Fail pre-commit / block deploy if findings present
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related issues
Possibly related PRs
Suggested labels
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
|
djm81
added
documentation
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.github/workflows/docs-review.yml (1)
57-62:⚠️ Potential issue | 🟠 MajorPin
specfact-clito stabilize docs-parity CI gates at line 55.This workflow depends directly on specfact-cli's CLI option contracts via
test_code_review_docs_parity.py. Installing an unpinned version can break this CI step on unrelated upstream releases, creating non-deterministic test failures when the code-review command surface changes in specfact-cli.- python -m pip install pytest click typer PyYAML beartype icontract rich pydantic specfact-cli + python -m pip install pytest click typer PyYAML beartype icontract rich pydantic "specfact-cli>=0.46.2"Note:
docs-pages.yml(line 63) andpr-orchestrator.yml(line 143) also install unpinned specfact-cli and may need the same constraint.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/workflows/docs-review.yml around lines 57 - 62, The docs CI installs an unpinned specfact-cli which can break tests due to upstream CLI changes; update the workflow step that runs the docs review suite (the job containing "Run docs review suite" and the DOCS_REVIEW_LOG handling) to install specfact-cli with an explicit pinned version (e.g., add pip install specfact-cli==<fixed-version> before running pytest) so the tests in tests/unit/docs/test_code_review_docs_parity.py use a stable CLI contract; apply the same pin to the specfact-cli installs in the other workflows mentioned (docs-pages.yml and pr-orchestrator.yml) to stabilize the gates.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/workflows/docs-pages.yml:
- Around line 62-64: Replace the floating pip installs on the CI step that runs
"python -m pip install click typer PyYAML beartype icontract rich pydantic
specfact-cli" with a pinned requirements file: add a requirements-docs.txt (or
similar) containing exact versions for those packages (including specfact-cli)
and update the workflow to run "python -m pip install -r requirements-docs.txt"
before invoking "python scripts/check-docs-commands.py --jekyll-bundle-check" so
the docs-validation step is deterministic.
In `@docs/bundles/code-review/run.md`:
- Around line 46-47: Update the user docs to state that positional FILES plus
--path is an invalid combination (in addition to the existing note about
--scope) to match the runtime validation in specfact_code_review.run.commands
that rejects positional files when either --scope or --path is provided; then
extend the unit test test_code_review_docs_parity to assert that the docs
mention --path as an invalid combination so future drifts are caught
automatically.
In
`@openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.md`:
- Line 1: The file currently begins with a level-2 heading "## ADDED
Requirements" which triggers markdownlint MD041; change that first heading to a
level-1 heading by replacing "## ADDED Requirements" with "# ADDED Requirements"
so the document starts with an H1 and satisfies the rule.
In `@scripts/docs_site_validation.py`:
- Around line 73-75: is_publishable_page currently excludes README.md which
prevents front-matter validation for directory landing pages; update
is_publishable_page so README.md files are considered publishable when they are
treated as published index pages by published_route_for_doc/build_route_index
(either remove the path.name != "README.md" exclusion or incorporate the same
published-index detection logic or call
published_route_for_doc/build_route_index to decide); ensure the function still
only returns True for actual docs markdown and that README landing pages trigger
front-matter checks for layout/title/permalink.
- Around line 379-386: The helper extract_markdown_links_with_lines only finds
Markdown-style links and misses HTML <a href="..."> anchors, so update it to
also parse and return href values from HTML anchors per-line; inside
extract_markdown_links_with_lines iterate lines as now (skipping "<!-- TODO:")
and after finding MARKDOWN_LINK_RE matches also parse each line for HTML anchor
hrefs (use Python's html.parser.HTMLParser or urllib.parse + a small regex) and
append (line_number, href) for every found anchor so
scan_published_route_body_links() sees both Markdown and HTML links; keep return
type list[tuple[int,str]] and preserve existing behavior for Markdown matches
(use match.group(1)) while adding href strings from the HTML anchors.
- Around line 492-502: The code currently swallows both FileNotFoundError and
subprocess.TimeoutExpired and returns [] on timeout, masking a hung bundle
check; change the except to only catch FileNotFoundError so missing local
Bundler still returns [] but a subprocess.TimeoutExpired raised by
subprocess.run (the call building proc) will propagate (or be handled upstream)
and thus surface as a docs-build-dependency failure rather than a clean pass;
update the try/except around the subprocess.run(...) that assigns proc
accordingly.
- Around line 441-444: The current logic in scripts/docs_site_validation.py
silently removes "title" from the missing keys when a page is a redirect
stub/only (variables: stub, missing, _REQUIRED_PAGE_KEYS and keys
"redirect_stub"/"redirect_only"), which contradicts the updated spec that a
published redirect page without a title must fail; revert that waiver by
removing the branch that filters out "title" when stub is true (or explicitly
enforce that "title" remains required regardless of stub) so that validation
fails if "title" is not present in missing for any page type.
In `@scripts/pre-commit-quality-checks.sh`:
- Around line 97-107: In run_docs_site_validation_gate, the docs validator is
invoked with plain python which can bypass the Hatch venv; change the invocation
to use Hatch like the other gates by replacing calls to "python
scripts/check-docs-commands.py" with "hatch run python
scripts/check-docs-commands.py" (update the info log, the conditional that runs
the script, and the warn Run hint) so the script runs inside the Hatch
environment and dependencies (click/typer/beartype, etc.) are resolved.
---
Outside diff comments:
In @.github/workflows/docs-review.yml:
- Around line 57-62: The docs CI installs an unpinned specfact-cli which can
break tests due to upstream CLI changes; update the workflow step that runs the
docs review suite (the job containing "Run docs review suite" and the
DOCS_REVIEW_LOG handling) to install specfact-cli with an explicit pinned
version (e.g., add pip install specfact-cli==<fixed-version> before running
pytest) so the tests in tests/unit/docs/test_code_review_docs_parity.py use a
stable CLI contract; apply the same pin to the specfact-cli installs in the
other workflows mentioned (docs-pages.yml and pr-orchestrator.yml) to stabilize
the gates.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: feddb35f-2c65-4fce-b03a-0f6e390cd34f
⛔ Files ignored due to path filters (1)
docs/Gemfile.lockis excluded by!**/*.lock
📒 Files selected for processing (39)
.github/workflows/docs-pages.yml.github/workflows/docs-review.ymldocs/bundles/backlog/overview.mddocs/bundles/code-review/ledger.mddocs/bundles/code-review/overview.mddocs/bundles/code-review/rules.mddocs/bundles/code-review/run.mddocs/bundles/codebase/analyze.mddocs/bundles/codebase/overview.mddocs/bundles/codebase/repro.mddocs/bundles/govern/overview.mddocs/bundles/project/overview.mddocs/bundles/spec/generate-tests.mddocs/bundles/spec/mock.mddocs/guides/brownfield-engineer.mddocs/guides/brownfield-faq.mddocs/guides/brownfield-journey.mddocs/guides/brownfield-roi.mddocs/guides/ide-integration.mddocs/modules/code-review.mdopenspec/CHANGE_ORDER.mdopenspec/changes/docs-15-code-review-validation-guardrails/.openspec.yamlopenspec/changes/docs-15-code-review-validation-guardrails/TDD_EVIDENCE.mdopenspec/changes/docs-15-code-review-validation-guardrails/design.mdopenspec/changes/docs-15-code-review-validation-guardrails/proposal.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/bundle-overview-pages/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-command-validation/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-publishing/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/tasks.mdscripts/check-docs-commands.pyscripts/docs_site_validation.pyscripts/pre-commit-quality-checks.shtests/unit/docs/test_code_review_docs_parity.pytests/unit/docs/test_docs_review.pytests/unit/test_check_docs_commands_script.pytests/unit/test_git_branch_module_signature_flag_script.pytests/unit/test_pre_commit_quality_parity.py
📜 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). (4)
- GitHub Check: quality (3.11)
- GitHub Check: quality (3.12)
- GitHub Check: quality (3.13)
- GitHub Check: Socket Security: Pull Request Alerts
🧰 Additional context used
📓 Path-based instructions (6)
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/bundles/code-review/overview.mddocs/bundles/code-review/rules.mddocs/bundles/codebase/overview.mddocs/bundles/spec/mock.mddocs/bundles/govern/overview.mddocs/guides/brownfield-journey.mddocs/guides/ide-integration.mddocs/bundles/codebase/repro.mddocs/guides/brownfield-engineer.mddocs/bundles/codebase/analyze.mddocs/guides/brownfield-roi.mddocs/bundles/backlog/overview.mddocs/bundles/project/overview.mddocs/bundles/code-review/ledger.mddocs/guides/brownfield-faq.mddocs/modules/code-review.mddocs/bundles/code-review/run.mddocs/bundles/spec/generate-tests.md
.github/workflows/**
⚙️ CodeRabbit configuration file
.github/workflows/**: CI: secrets, hatch/verify-modules-signature gates, contract-test alignment, action versions.
Files:
.github/workflows/docs-pages.yml.github/workflows/docs-review.yml
openspec/**/*.md
⚙️ CodeRabbit configuration file
openspec/**/*.md: Specification truth: proposal/tasks/spec deltas vs. bundle behavior, CHANGE_ORDER, and
drift vs. shipped modules or docs.
Files:
openspec/CHANGE_ORDER.mdopenspec/changes/docs-15-code-review-validation-guardrails/TDD_EVIDENCE.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-publishing/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/bundle-overview-pages/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/proposal.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-command-validation/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/design.mdopenspec/changes/docs-15-code-review-validation-guardrails/tasks.md
**/*.{js,ts,tsx,jsx,py,java,cs,go,rb,php,cpp,c,h}
📄 CodeRabbit inference engine (CLAUDE.md)
Preserve the clean-code compliance gate and its category references (naming, kiss, yagni, dry, and solid)
Files:
tests/unit/test_pre_commit_quality_parity.pytests/unit/test_check_docs_commands_script.pytests/unit/test_git_branch_module_signature_flag_script.pytests/unit/docs/test_code_review_docs_parity.pytests/unit/docs/test_docs_review.pyscripts/check-docs-commands.pyscripts/docs_site_validation.py
tests/**/*.py
⚙️ CodeRabbit configuration file
tests/**/*.py: Contract-first and integration tests: migration suites, bundle validation, and flakiness.
Ensure changes to adapters or bridges have targeted coverage.
Files:
tests/unit/test_pre_commit_quality_parity.pytests/unit/test_check_docs_commands_script.pytests/unit/test_git_branch_module_signature_flag_script.pytests/unit/docs/test_code_review_docs_parity.pytests/unit/docs/test_docs_review.py
scripts/**/*.py
⚙️ CodeRabbit configuration file
scripts/**/*.py: Deterministic tooling: signing, publishing, docs generation; subprocess and path safety.
Files:
scripts/check-docs-commands.pyscripts/docs_site_validation.py
🧠 Learnings (16)
📓 Common learnings
Learnt from: djm81
Repo: nold-ai/specfact-cli-modules PR: 136
File: registry/modules/specfact-spec-0.40.17.tar.gz.sha256:1-1
Timestamp: 2026-04-02T21:49:11.371Z
Learning: In nold-ai/specfact-cli-modules, module tarball signatures (registry/signatures/*.tar.sig) are generated by the `publish-modules` GitHub Actions runner during the publish workflow, not committed locally to the branch. Missing signature files should NOT be flagged as a pre-merge blocker in PRs.
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
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
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: .cursorrules:0-0
Timestamp: 2026-04-13T10:38:15.842Z
Learning: Adhere to worktree policy, OpenSpec gating, GitHub hierarchy-cache refresh, TDD order, quality gates, versioning, and documentation rules as defined in `docs/agent-rules/`
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-13T10:38:29.379Z
Learning: Treat canonical rule docs (docs/agent-rules/INDEX.md) as the source of truth for worktree policy, OpenSpec gating, GitHub completeness checks, TDD order, quality gates, versioning, and documentation rules
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: Signed module or manifest changes require version-bump review and verify-modules-signature
📚 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/bundles/code-review/overview.mddocs/bundles/code-review/rules.mdopenspec/CHANGE_ORDER.mdopenspec/changes/docs-15-code-review-validation-guardrails/TDD_EVIDENCE.mddocs/bundles/code-review/ledger.mdscripts/pre-commit-quality-checks.shopenspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.mddocs/modules/code-review.mdopenspec/changes/docs-15-code-review-validation-guardrails/proposal.mddocs/bundles/code-review/run.mdopenspec/changes/docs-15-code-review-validation-guardrails/tasks.md
📚 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: Perform `spec -> tests -> failing evidence -> code -> passing evidence` in that order for behavior changes
Applied to files:
docs/bundles/spec/mock.mdopenspec/changes/docs-15-code-review-validation-guardrails/TDD_EVIDENCE.mdopenspec/changes/docs-15-code-review-validation-guardrails/tasks.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: Use docs/agent-rules/INDEX.md as the canonical governance dispatcher for governance rules
Applied to files:
docs/bundles/govern/overview.md
📚 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: Finalize completed OpenSpec changes with `openspec archive <change-id>` and do not manually move change folders under `openspec/changes/archive/`
Applied to files:
openspec/changes/docs-15-code-review-validation-guardrails/.openspec.yaml
📚 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: Treat canonical rule docs (docs/agent-rules/INDEX.md) as the source of truth for worktree policy, OpenSpec gating, GitHub completeness checks, TDD order, quality gates, versioning, and documentation rules
Applied to files:
docs/bundles/backlog/overview.mdopenspec/CHANGE_ORDER.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-publishing/spec.mddocs/bundles/code-review/ledger.mdscripts/pre-commit-quality-checks.shopenspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/proposal.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-command-validation/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/design.mdopenspec/changes/docs-15-code-review-validation-guardrails/tasks.md
📚 Learning: 2026-04-13T10:38:15.842Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: .cursorrules:0-0
Timestamp: 2026-04-13T10:38:15.842Z
Learning: Adhere to worktree policy, OpenSpec gating, GitHub hierarchy-cache refresh, TDD order, quality gates, versioning, and documentation rules as defined in `docs/agent-rules/`
Applied to files:
docs/bundles/backlog/overview.mdopenspec/CHANGE_ORDER.mdopenspec/changes/docs-15-code-review-validation-guardrails/TDD_EVIDENCE.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-publishing/spec.mddocs/bundles/code-review/ledger.mdscripts/pre-commit-quality-checks.shopenspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/proposal.mdopenspec/changes/docs-15-code-review-validation-guardrails/tasks.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: Full governance rules live in docs/agent-rules/; do not treat this file (GitHub Copilot Instructions) as a complete standalone handbook
Applied to files:
docs/bundles/backlog/overview.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:
openspec/CHANGE_ORDER.md.github/workflows/docs-review.ymlopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-publishing/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.mddocs/modules/code-review.mdopenspec/changes/docs-15-code-review-validation-guardrails/proposal.mddocs/bundles/code-review/run.mdopenspec/changes/docs-15-code-review-validation-guardrails/tasks.md
📚 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: Treat the clean-code compliance gate as mandatory: the review surface enforces `naming`, `kiss`, `yagni`, `dry`, and `solid` categories and blocks regressions
Applied to files:
openspec/changes/docs-15-code-review-validation-guardrails/TDD_EVIDENCE.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/proposal.mdopenspec/changes/docs-15-code-review-validation-guardrails/design.mdopenspec/changes/docs-15-code-review-validation-guardrails/tasks.md
📚 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:
openspec/changes/docs-15-code-review-validation-guardrails/TDD_EVIDENCE.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.mddocs/modules/code-review.mdopenspec/changes/docs-15-code-review-validation-guardrails/proposal.mddocs/bundles/code-review/run.md
📚 Learning: 2026-04-02T21:49:11.371Z
Learnt from: djm81
Repo: nold-ai/specfact-cli-modules PR: 136
File: registry/modules/specfact-spec-0.40.17.tar.gz.sha256:1-1
Timestamp: 2026-04-02T21:49:11.371Z
Learning: In nold-ai/specfact-cli-modules, module tarball signatures (registry/signatures/*.tar.sig) are generated by the `publish-modules` GitHub Actions runner during the publish workflow, not committed locally to the branch. Missing signature files should NOT be flagged as a pre-merge blocker in PRs.
Applied to files:
openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-publishing/spec.mdtests/unit/test_git_branch_module_signature_flag_script.py
📚 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: Applies to **/*.{js,ts,tsx,jsx,py,java,cs,go,rb,php,cpp,c,h} : Preserve the clean-code compliance gate and its category references (naming, kiss, yagni, dry, and solid)
Applied to files:
openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.mdscripts/pre-commit-quality-checks.shopenspec/changes/docs-15-code-review-validation-guardrails/tasks.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: Treat clean-code regressions (naming, kiss, yagni, dry, solid violations) as blocking until they are fixed or explicitly justified
Applied to files:
openspec/changes/docs-15-code-review-validation-guardrails/design.mdopenspec/changes/docs-15-code-review-validation-guardrails/tasks.md
📚 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: Read docs/agent-rules/05-non-negotiable-checklist.md before implementation
Applied to files:
openspec/changes/docs-15-code-review-validation-guardrails/tasks.md
📚 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: Run the required verification and quality gates for the touched scope before finalization
Applied to files:
openspec/changes/docs-15-code-review-validation-guardrails/tasks.md
🪛 LanguageTool
docs/bundles/codebase/overview.md
[grammar] ~77-~77: Ensure spelling is correct
Context: ...se --repo . ``` ## Deep dives - Code analyze contracts - [Code drift d...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/bundles/codebase/repro.md
[grammar] ~66-~66: Ensure spelling is correct
Context: ...tall-crosshair ``` ## Related - Code analyze contracts - [Code drift d...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
openspec/changes/docs-15-code-review-validation-guardrails/specs/bundle-overview-pages/spec.md
[grammar] ~19-~19: Use a hyphen to join words.
Context: ...w page ### Requirement: Bundle overview related links SHALL be covered by docs v...
(QB_NEW_EN_HYPHEN)
openspec/changes/docs-15-code-review-validation-guardrails/proposal.md
[style] ~33-~33: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...on helper if consolidation is needed. - Affected CI and local gates include `.github/wor...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[uncategorized] ~33-~33: The official name of this software platform is spelled with a capital “H”.
Context: .... - Affected CI and local gates include .github/workflows/docs-review.yml, `.github/wo...
(GITHUB)
[uncategorized] ~33-~33: The official name of this software platform is spelled with a capital “H”.
Context: ...de .github/workflows/docs-review.yml, .github/workflows/docs-pages.yml, `.github/wor...
(GITHUB)
[uncategorized] ~33-~33: The official name of this software platform is spelled with a capital “H”.
Context: ...l, .github/workflows/docs-pages.yml, .github/workflows/pr-orchestrator.yml, .pre-c...
(GITHUB)
openspec/changes/docs-15-code-review-validation-guardrails/design.md
[style] ~22-~22: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...inistic and usable before publishing. - Do not change bundle runtime behavior or r...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~23-~23: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...directly from signed module payloads. - Do not replace the existing Jekyll stack o...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~55-~55: Consider an alternative for the overused word “exactly”.
Context: ...ly on review. Rejected because this was exactly the failure mode. ## Risks / Trade-off...
(EXACTLY_PRECISELY)
[style] ~69-~69: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...tly incomplete redirect/guide pages. 3. Add failing tests for Code Review run optio...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~82-~82: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ndency maintenance change updates it? - Should generated _site link validation be ma...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
openspec/changes/docs-15-code-review-validation-guardrails/tasks.md
[uncategorized] ~4-~4: The official name of this software platform is spelled with a capital “H”.
Context: ...e work is required, refresh and consult .specfact/backlog/github_hierarchy_cache.md and verify parent, ...
(GITHUB)
[uncategorized] ~44-~44: The official name of this software platform is spelled with a capital “H”.
Context: ...visible hook or stage. - [x] 6.3 Update .github/workflows/docs-review.yml so it runs t...
(GITHUB)
[uncategorized] ~45-~45: The official name of this software platform is spelled with a capital “H”.
Context: ...ogs for each category. - [x] 6.4 Update .github/workflows/docs-pages.yml so dependency...
(GITHUB)
🪛 markdownlint-cli2 (0.22.0)
openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-publishing/spec.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
openspec/changes/docs-15-code-review-validation-guardrails/specs/bundle-overview-pages/spec.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
openspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
openspec/changes/docs-15-code-review-validation-guardrails/proposal.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-command-validation/spec.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
openspec/changes/docs-15-code-review-validation-guardrails/design.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
openspec/changes/docs-15-code-review-validation-guardrails/tasks.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
🔀 Multi-repo context nold-ai/specfact-cli
[::nold-ai/specfact-cli::] scripts/check-docs-commands.py
- New CLI parsing (_main(argv: list[str] | None = None)) and import dependency on scripts/docs_site_validation.py (script now calls build_valid_internal_routes, scan_published_route_body_links, scan_frontmatter_findings). Relevant caller sites must pass argv or rely on entrypoint behavior.
[::nold-ai/specfact-cli::] scripts/docs_site_validation.py
- New shared validation library exposing ValidationFinding, build_route_index, build_path_to_canonical_route, resolve_internal_link_hybrid, scan_published_route_body_links, scan_frontmatter_findings, scan_gemfile_lock_installability, format_findings — these are consumed by tests and scripts (above).
[::nold-ai/specfact-cli::] scripts/pre-commit-quality-checks.sh
- Now invokes python scripts/check-docs-commands.py when staged docs changes are present (new helper run_docs_site_validation_gate). Pre-commit flow changes mean commits touching docs/scripts may fail if the new validators find issues.
[::nold-ai/specfact-cli::] .github/workflows/docs-review.yml and .github/workflows/docs-pages.yml
- Workflows now list/execute scripts/check-docs-commands.py and (docs-pages) run python scripts/check-docs-commands.py --jekyll-bundle-check. CI will run the new validators; failing findings will fail CI jobs that previously passed.
[::nold-ai/specfact-cli::] tests/unit/docs/test_code_review_docs_parity.py (new)
- Tests extract Typer/Click options from the Code Review
runcommand and assert parity with docs/bundles/code-review/run.md (looks for flags like --bug-hunt, --mode, --focus, --level, --json/--out and invalid-combination documentation). Any divergence between actual CLI surface and docs will fail unit tests.
[::nold-ai/specfact-cli::] tests/unit/docs/test_docs_review.py and tests/unit/test_check_docs_commands_script.py (modified)
- These tests now import and call functions from scripts/docs_site_validation (via scripts/check-docs-commands.py). They rely on the new exported scanning helpers and the new ValidationFinding shape.
[::nold-ai/specfact-cli::] docs/* (multiple files e.g., docs/bundles/code-review/run.md, docs/modules/code-review.md)
- Doc content was updated to include new flags/behaviors (progress output, --json default output file, --mode shadow|enforce, --focus, --bug-hunt, invalid combinations). Tests enforce docs/CLI parity — changes to the CLI flags will require corresponding docs updates or tests will fail.
Other cross-cutting notes (observed)
- Many tests and tooling reference "specfact code review run" and its flags (rg hits across tests and docs). The new docs validation and parity tests create a coupling: changes to the code-review CLI surface, scripts/check-docs-commands.py signature, or the ValidationFinding shape must be reflected in docs and tests and/or in the new docs_site_validation API.
Conclusion
- The PR introduces a new shared validation API (scripts/docs_site_validation.py) consumed by check-docs-commands.py, CI workflows, pre-commit hooks, and unit tests that assert parity between CLI and docs. These are direct consumers and will need updates if the new APIs/signatures, ValidationFinding fields, or the Code Review CLI option surface change.
🔇 Additional comments (29)
tests/unit/test_git_branch_module_signature_flag_script.py (1)
31-75: Good isolation of the git subprocess boundary.Creating a nested temp repo and scrubbing git-control environment variables makes this regression test deterministic and protects the outer modules worktree from accidental mutation. As per coding guidelines, "Contract-first and integration tests: migration suites, bundle validation, and flakiness. Ensure changes to adapters or bridges have targeted coverage."
docs/bundles/spec/mock.md (1)
53-54: Related links now correctly use published-route-relative targets.
Looks correct and consistent with nested bundle routing semantics.docs/bundles/codebase/analyze.md (1)
43-45: Good fix for nested docs navigation links.
These paths now resolve correctly from the analyze route.docs/bundles/code-review/ledger.md (1)
48-49: Link target correction is accurate for ledger page context.
Nice alignment with the code-review docs parity guardrails.docs/guides/brownfield-journey.md (1)
3-3: Front-matter completeness fix is correct.
Adding an explicit title for the redirect page matches the docs validation guardrail intent.docs/bundles/spec/generate-tests.md (1)
50-51: Related links are now route-correct for this spec bundle page.
This change is consistent with the new published-link validation behavior.docs/bundles/code-review/overview.md (1)
63-65: See-also navigation fix is correct for the overview route depth.
Good parity with thecode reviewbundle command docs structure.docs/bundles/code-review/rules.md (1)
45-46: Related links are correctly adjusted for nested routing.
This is consistent with the guardrail-driven docs link model.openspec/changes/docs-15-code-review-validation-guardrails/.openspec.yaml (1)
1-2: OpenSpec manifest metadata looks valid and complete for change initialization.docs/guides/brownfield-roi.md (1)
3-3: Good front-matter completion for redirect stub.Line 3 adds the missing
titleand keeps redirect wiring intact.As per coding guidelines:
docs/**/*.md: User-facing and cross-site accuracy: Jekyll front matter, links per documentation-url-contract, CLI examples matching bundled commands.docs/bundles/codebase/repro.md (1)
66-68: Related-link route fix looks correct.These parent-relative links should resolve correctly from
/bundles/codebase/repro/in published docs.As per coding guidelines:
docs/**/*.md: User-facing and cross-site accuracy: Jekyll front matter, links per documentation-url-contract, CLI examples matching bundled commands.docs/guides/brownfield-engineer.md (1)
3-3: Front matter update is solid.Line 3 correctly adds a title without altering redirect behavior.
As per coding guidelines:
docs/**/*.md: User-facing and cross-site accuracy: Jekyll front matter, links per documentation-url-contract, CLI examples matching bundled commands.docs/bundles/codebase/overview.md (1)
77-80: Deep-dive link normalization is correct.The
../link targets align with published Jekyll route resolution from the overview page.As per coding guidelines:
docs/**/*.md: User-facing and cross-site accuracy: Jekyll front matter, links per documentation-url-contract, CLI examples matching bundled commands.docs/bundles/govern/overview.md (1)
48-49: See-also links are fixed appropriately.These parent-relative paths should resolve correctly under
/bundles/govern/overview/.As per coding guidelines:
docs/**/*.md: User-facing and cross-site accuracy: Jekyll front matter, links per documentation-url-contract, CLI examples matching bundled commands.docs/guides/brownfield-faq.md (1)
3-3: Redirect stub metadata is now complete.Line 3 adds the missing title cleanly.
As per coding guidelines:
docs/**/*.md: User-facing and cross-site accuracy: Jekyll front matter, links per documentation-url-contract, CLI examples matching bundled commands.docs/guides/ide-integration.md (1)
3-3: Nice front-matter parity fix.Line 3 adds title metadata while preserving the existing redirect contract.
As per coding guidelines:
docs/**/*.md: User-facing and cross-site accuracy: Jekyll front matter, links per documentation-url-contract, CLI examples matching bundled commands.openspec/CHANGE_ORDER.md (1)
81-81: Change-order addition is consistent and traceable.The new
docs + validationpending row is well-formed and keeps dependency context explicit.docs/bundles/backlog/overview.md (1)
69-69: Link target corrections look good.These parent-relative routes are the right direction for published bundle navigation.
Also applies to: 114-117
tests/unit/test_pre_commit_quality_parity.py (1)
38-40: Coverage update is appropriate for the new docs gate.The added required fragments correctly lock in the docs-site validation path.
.github/workflows/docs-review.yml (1)
13-16: Workflow trigger expansion is solid.Including the shared validator and parity test paths is the right CI coupling for docs gate coverage.
Also applies to: 25-28
docs/bundles/project/overview.md (1)
79-79: These cross-bundle link fixes look correct.The parent-relative targets are consistent with the docs site route structure.
Also applies to: 96-97
openspec/changes/docs-15-code-review-validation-guardrails/TDD_EVIDENCE.md (1)
1-19: Evidence log is clear and complete for this scope.The command-level pass evidence is well documented and aligned with the docs-validation guardrail objective.
scripts/pre-commit-quality-checks.sh (1)
258-261: Good ordering: docs validation runs before safe-change bypass.This is the right control-flow placement for docs-only commits.
Also applies to: 271-280
openspec/changes/docs-15-code-review-validation-guardrails/specs/bundle-overview-pages/spec.md (1)
3-27: Spec guardrails are clear and enforceable.The scenarios are concrete and map well to published-route validation behavior.
tests/unit/test_check_docs_commands_script.py (1)
97-117: Good migration to shared docs-validation test flow.These assertions strengthen parity between script behavior and workflow wiring.
Also applies to: 136-146, 154-156
openspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.md (1)
3-27: Parity requirements are well scoped.The scenarios are measurable and suitable for CI-level enforcement.
openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-publishing/spec.md (1)
3-27: Publishing and review gate requirements look solid.The fail-before-deploy behavior is explicitly captured.
docs/modules/code-review.md (1)
28-73: Great parity detail at module-doc level.The option semantics, invalid combinations, and output-mode examples are substantially clearer and operationally useful.
Also applies to: 131-147
openspec/changes/docs-15-code-review-validation-guardrails/proposal.md (1)
5-35: Proposal scope and impact framing are strong.This captures the validation-contract shift and CI/local parity goals clearly.
…parity Add requirements-docs-ci.txt and use it in docs workflows; pin specfact-cli in pr-orchestrator. Harden docs_site_validation (README publishability, HTML hrefs, bundle timeout, redirect title). Run check-docs-commands via hatch in pre-commit; fix OpenSpec spec H1s; align run.md and tests with CLI rules. Made-with: Cursor
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
There was a problem hiding this comment.
Actionable comments posted: 8
♻️ Duplicate comments (2)
scripts/docs_site_validation.py (2)
505-523:⚠️ Potential issue | 🟠 MajorReturn a categorized finding on
bundle checktimeout.A hung
bundle checknow escapes assubprocess.TimeoutExpired, which crashes the docs gate with a traceback instead of emitting the stabledocs-build-dependencycategory the validator is supposed to report.🛠️ Suggested fix
try: proc = subprocess.run( ["bundle", "check"], cwd=str(docs_dir), capture_output=True, text=True, timeout=120, check=False, ) except FileNotFoundError: return [] + except subprocess.TimeoutExpired: + return [ + ValidationFinding( + "docs-build-dependency", + gemfile_lock, + 1, + "bundle check timed out in docs/; dependency health is unknown", + ) + ] if proc.returncode != 0: detail = (proc.stderr or proc.stdout or "").strip()🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@scripts/docs_site_validation.py` around lines 505 - 523, The try/except around subprocess.run currently only catches FileNotFoundError and lets subprocess.TimeoutExpired raise a traceback; update the block around subprocess.run (the call to subprocess.run in scripts/docs_site_validation.py) to also catch subprocess.TimeoutExpired and return a ValidationFinding with category "docs-build-dependency" (using the existing ValidationFinding constructor and gemfile_lock variable) containing a short message indicating the `bundle check` timed out (include a brief detail like "bundle check timed out after 120s"), so the validator emits the same categorized finding instead of crashing.
171-197:⚠️ Potential issue | 🟠 MajorKeep route indexing aligned with
is_publishable_page()for README landings.
is_publishable_page()now requires README front matter, but both route builders still admit anyREADME.mdwhensplit_yaml_front_matter()returns{}. That lets published-link validation treat a frontmatter-less landing page as a valid target whilescan_frontmatter_findings()never reports it.🛠️ Suggested fix
def build_route_index(docs_root: Path) -> dict[str, Path]: """Map every published and redirect alias route to its declaring markdown file.""" route_to_path: dict[str, Path] = {} for path in iter_docs_markdown_paths(docs_root): text = path.read_text(encoding="utf-8") fm, _, _ = split_yaml_front_matter(text) - if not fm and path.name.lower() != "readme.md": + if not fm or not is_publishable_page(path, docs_root): continue canonical = published_route_for_doc(path, docs_root, fm) route_to_path[canonical] = path for alias in list_redirect_from_routes(fm): route_to_path[alias] = path return route_to_path def build_path_to_canonical_route(docs_root: Path) -> dict[Path, str]: mapping: dict[Path, str] = {} for path in iter_docs_markdown_paths(docs_root): fm, _, _ = split_yaml_front_matter(path.read_text(encoding="utf-8")) - if not fm and path.name.lower() != "readme.md": + if not fm or not is_publishable_page(path, docs_root): continue mapping[path.resolve()] = published_route_for_doc(path, docs_root, fm) return mapping🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@scripts/docs_site_validation.py` around lines 171 - 197, Both build_route_index and build_path_to_canonical_route currently special-case README.md by allowing empty front matter, which diverges from is_publishable_page() and lets frontmatter-less README landings slip through validation; update both functions to require non-empty front matter for all files (i.e., remove the path.name.lower() != "readme.md" exception and treat README like any other file by continuing when split_yaml_front_matter returns empty), leaving published_route_for_doc, iter_docs_markdown_paths, and path.resolve() usage unchanged so routing and path mapping align with scan_frontmatter_findings and is_publishable_page().
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/bundles/code-review/run.md`:
- Around line 42-50: Add a new invalid-combination bullet under the "Invalid
combinations" section documenting that the CLI rejects using --json together
with --score-only (e.g., "- **`--json` with `--score-only`**: do not combine
output JSON mode with score-only mode"), mirroring the runtime validation;
update the surrounding list so the wording/format matches existing bullets for
flags like `--out`/`--json` and reference the flags `--json` and `--score-only`
so the docs and CLI validation are consistent.
In
`@openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.md`:
- Around line 3-27: Update the markdown heading levels so they increment by one
level at a time: change the top-level "### Requirement: Docs-only pre-commit
changes SHALL run docs validation before safe bypass" headings from "###" to
"##" and change the nested "#### Scenario: ..." headings to "###" accordingly;
do the same for the second requirement header "### Requirement: Pre-commit and
CI docs gates SHALL share validation categories" and its "#### Scenario: Same
broken docs route reports same category locally and in CI" so all headings
follow a single-level increment sequence (e.g., H1 -> H2 -> H3).
In
`@openspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.md`:
- Around line 3-13: The markdown uses inconsistent heading levels causing
markdownlint heading-increment violations; change the "Requirement: Code Review
run docs SHALL cover the public option surface" heading from H3 to H2 and change
the "Scenario: Newly added review options are documented" and "Scenario: Invalid
option combinations are documented" headings from H4/H3 to H3 so requirements
are H2 and scenarios are H3; apply the same normalization to the other related
spec files referenced (19-27) so all requirement headings use H2 and scenario
headings use H3 to satisfy the lint rule.
- Around line 15-17: The spec example incorrectly uses the CLI flag --focus
while the runtime contract expects --path; update the spec text and all examples
in the review-run-command document to use --path (and any related examples of
positional files vs --scope/--include-tests) so the docs/tests reflect the
actual command contract, and add the user-facing alternative targeting paragraph
that shows using positional file arguments or --path consistently as the
supported targeting style; ensure references to the invalid combination describe
positional files with --scope or --path with --include-tests as the rejected
cases.
In `@tests/unit/docs/test_code_review_docs_parity.py`:
- Around line 60-69: The test currently only checks for flag names; change it to
assert the actual incompatible pairings/messages produced by the code by
importing and using the resolver: call _resolve_review_run_flags() (or the
function that returns/enforces incompatible flag combinations) inside
test_code_review_run_doc_describes_invalid_flag_combinations, extract the list
of incompatible pair tuples/messages, and for each pairing assert that
RUN_DOC.read_text(...) contains the expected human-readable string (e.g., a
formatted "flagA and flagB" or the exact message returned by the resolver). Keep
references to RUN_DOC and _resolve_review_run_flags so the test fails if the
docs drift from the actual incompatible-flag logic.
- Around line 35-58: Replace the hardcoded tuple of expected flags in
test_code_review_run_doc_mentions_public_ty_options with assertions derived from
the command: call _public_option_flags(_review_run_click_command()) to get the
actual public flags and then assert each flag from that flags collection appears
in RUN_DOC.read_text(); i.e., remove the fixed list of "--bug-hunt", "--mode",
... and instead iterate over flags to assert flag in text (and optionally assert
flags is a subset of the documented tokens) so CLI surface changes fail the
module↔CLI parity test.
In `@tests/unit/test_check_docs_commands_script.py`:
- Around line 152-157: The test in tests/unit/test_check_docs_commands_script.py
is asserting an implementation detail by requiring
"scripts/docs_site_validation.py" to appear in the generated workflow; remove
that assertion so the contract only requires the public invocation
"scripts/check-docs-commands.py" (and the other workflow lines already checked
like the pip install and test paths). Specifically, delete the assert that
matches "scripts/docs_site_validation.py" and leave the other assertions intact
so the test validates the workflow's public command usage without coupling to
the helper module path.
- Around line 143-146: The test
test_docs_pages_workflow_runs_python_docs_validation currently only checks
presence of two commands; update it to assert ordering: read the docs-pages
workflow text (as current variable workflow), find the index positions of the
strings "python -m pip install -r requirements-docs-ci.txt" and "python
scripts/check-docs-commands.py --jekyll-bundle-check" and assert install_index <
check_index, then locate the Pages upload/deploy step name (e.g. the job/step
that uploads or deploys Pages artifact) by matching its key or a distinctive
string and assert check_index < pages_upload_index so install -> check -> upload
ordering is enforced. Ensure assertions raise clear messages referencing those
three strings.
---
Duplicate comments:
In `@scripts/docs_site_validation.py`:
- Around line 505-523: The try/except around subprocess.run currently only
catches FileNotFoundError and lets subprocess.TimeoutExpired raise a traceback;
update the block around subprocess.run (the call to subprocess.run in
scripts/docs_site_validation.py) to also catch subprocess.TimeoutExpired and
return a ValidationFinding with category "docs-build-dependency" (using the
existing ValidationFinding constructor and gemfile_lock variable) containing a
short message indicating the `bundle check` timed out (include a brief detail
like "bundle check timed out after 120s"), so the validator emits the same
categorized finding instead of crashing.
- Around line 171-197: Both build_route_index and build_path_to_canonical_route
currently special-case README.md by allowing empty front matter, which diverges
from is_publishable_page() and lets frontmatter-less README landings slip
through validation; update both functions to require non-empty front matter for
all files (i.e., remove the path.name.lower() != "readme.md" exception and treat
README like any other file by continuing when split_yaml_front_matter returns
empty), leaving published_route_for_doc, iter_docs_markdown_paths, and
path.resolve() usage unchanged so routing and path mapping align with
scan_frontmatter_findings and is_publishable_page().
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 1d8c6893-e654-4ef9-b35f-ad7df4a6fc65
📒 Files selected for processing (17)
.github/workflows/docs-pages.yml.github/workflows/docs-review.yml.github/workflows/pr-orchestrator.ymldocs/bundles/code-review/run.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/bundle-overview-pages/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-command-validation/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-publishing/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.mdrequirements-docs-ci.txtscripts/docs_site_validation.pyscripts/pre-commit-quality-checks.shtests/unit/docs/test_code_review_docs_parity.pytests/unit/docs/test_docs_review.pytests/unit/test_check_docs_commands_script.pytests/unit/test_pre_commit_quality_parity.pytests/unit/workflows/test_pr_orchestrator_signing.py
📜 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). (4)
- GitHub Check: quality (3.11)
- GitHub Check: quality (3.12)
- GitHub Check: quality (3.13)
- GitHub Check: Socket Security: Pull Request Alerts
🧰 Additional context used
📓 Path-based instructions (6)
.github/workflows/**
⚙️ CodeRabbit configuration file
.github/workflows/**: CI: secrets, hatch/verify-modules-signature gates, contract-test alignment, action versions.
Files:
.github/workflows/pr-orchestrator.yml.github/workflows/docs-pages.yml.github/workflows/docs-review.yml
**/*.{js,ts,tsx,jsx,py,java,cs,go,rb,php,cpp,c,h}
📄 CodeRabbit inference engine (CLAUDE.md)
Preserve the clean-code compliance gate and its category references (naming, kiss, yagni, dry, and solid)
Files:
tests/unit/workflows/test_pr_orchestrator_signing.pytests/unit/test_pre_commit_quality_parity.pytests/unit/test_check_docs_commands_script.pytests/unit/docs/test_code_review_docs_parity.pyscripts/docs_site_validation.pytests/unit/docs/test_docs_review.py
tests/**/*.py
⚙️ CodeRabbit configuration file
tests/**/*.py: Contract-first and integration tests: migration suites, bundle validation, and flakiness.
Ensure changes to adapters or bridges have targeted coverage.
Files:
tests/unit/workflows/test_pr_orchestrator_signing.pytests/unit/test_pre_commit_quality_parity.pytests/unit/test_check_docs_commands_script.pytests/unit/docs/test_code_review_docs_parity.pytests/unit/docs/test_docs_review.py
openspec/**/*.md
⚙️ CodeRabbit configuration file
openspec/**/*.md: Specification truth: proposal/tasks/spec deltas vs. bundle behavior, CHANGE_ORDER, and
drift vs. shipped modules or docs.
Files:
openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-publishing/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/bundle-overview-pages/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-command-validation/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.md
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/bundles/code-review/run.md
scripts/**/*.py
⚙️ CodeRabbit configuration file
scripts/**/*.py: Deterministic tooling: signing, publishing, docs generation; subprocess and path safety.
Files:
scripts/docs_site_validation.py
🧠 Learnings (9)
📓 Common learnings
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
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: .cursorrules:0-0
Timestamp: 2026-04-13T10:38:15.842Z
Learning: Adhere to worktree policy, OpenSpec gating, GitHub hierarchy-cache refresh, TDD order, quality gates, versioning, and documentation rules as defined in `docs/agent-rules/`
Learnt from: djm81
Repo: nold-ai/specfact-cli-modules PR: 136
File: registry/modules/specfact-spec-0.40.17.tar.gz.sha256:1-1
Timestamp: 2026-04-02T21:49:11.371Z
Learning: In nold-ai/specfact-cli-modules, module tarball signatures (registry/signatures/*.tar.sig) are generated by the `publish-modules` GitHub Actions runner during the publish workflow, not committed locally to the branch. Missing signature files should NOT be flagged as a pre-merge blocker in PRs.
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-13T10:38:29.379Z
Learning: Treat canonical rule docs (docs/agent-rules/INDEX.md) as the source of truth for worktree policy, OpenSpec gating, GitHub completeness checks, TDD order, quality gates, versioning, and documentation rules
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
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-13T10:38:43.524Z
Learning: Treat the clean-code compliance gate as mandatory: the review surface enforces `naming`, `kiss`, `yagni`, `dry`, and `solid` categories and blocks regressions
📚 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:
.github/workflows/pr-orchestrator.ymlopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-publishing/spec.mddocs/bundles/code-review/run.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.md.github/workflows/docs-review.yml
📚 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:
.github/workflows/pr-orchestrator.ymlopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.mdscripts/pre-commit-quality-checks.shdocs/bundles/code-review/run.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.md
📚 Learning: 2026-04-13T10:38:15.842Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: .cursorrules:0-0
Timestamp: 2026-04-13T10:38:15.842Z
Learning: Adhere to worktree policy, OpenSpec gating, GitHub hierarchy-cache refresh, TDD order, quality gates, versioning, and documentation rules as defined in `docs/agent-rules/`
Applied to files:
.github/workflows/docs-pages.ymlopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.mdscripts/pre-commit-quality-checks.shopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-publishing/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.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: Treat canonical rule docs (docs/agent-rules/INDEX.md) as the source of truth for worktree policy, OpenSpec gating, GitHub completeness checks, TDD order, quality gates, versioning, and documentation rules
Applied to files:
openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-publishing/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-command-validation/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.md
📚 Learning: 2026-04-02T21:49:11.371Z
Learnt from: djm81
Repo: nold-ai/specfact-cli-modules PR: 136
File: registry/modules/specfact-spec-0.40.17.tar.gz.sha256:1-1
Timestamp: 2026-04-02T21:49:11.371Z
Learning: In nold-ai/specfact-cli-modules, module tarball signatures (registry/signatures/*.tar.sig) are generated by the `publish-modules` GitHub Actions runner during the publish workflow, not committed locally to the branch. Missing signature files should NOT be flagged as a pre-merge blocker in PRs.
Applied to files:
openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-publishing/spec.md
📚 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: Treat the clean-code compliance gate as mandatory: the review surface enforces `naming`, `kiss`, `yagni`, `dry`, and `solid` categories and blocks regressions
Applied to files:
openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.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: Applies to **/*.{js,ts,tsx,jsx,py,java,cs,go,rb,php,cpp,c,h} : Preserve the clean-code compliance gate and its category references (naming, kiss, yagni, dry, and solid)
Applied to files:
openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.md
📚 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/bundles/code-review/run.mdopenspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.md
🪛 LanguageTool
openspec/changes/docs-15-code-review-validation-guardrails/specs/bundle-overview-pages/spec.md
[grammar] ~19-~19: Use a hyphen to join words.
Context: ...w page ### Requirement: Bundle overview related links SHALL be covered by docs v...
(QB_NEW_EN_HYPHEN)
🪛 markdownlint-cli2 (0.22.0)
openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.md
[warning] 3-3: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
openspec/changes/docs-15-code-review-validation-guardrails/specs/bundle-overview-pages/spec.md
[warning] 3-3: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-command-validation/spec.md
[warning] 3-3: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
🔀 Multi-repo context nold-ai/specfact-cli
[::nold-ai/specfact-cli::] .github/workflows/docs-review.yml — runs "scripts/check-docs-commands.py" and installs requirements-docs-ci.txt (CI consumer of the new docs validator).
[::nold-ai/specfact-cli::] .github/workflows/docs-pages.yml / .github/workflows/github-pages.yml — docs workflow now invokes check-docs-commands.py (with --jekyll-bundle-check) after installing pinned docs requirements (CI consumer that will fail on validator findings).
[::nold-ai/specfact-cli::] scripts/check-docs-commands.py — entrypoint now imports and delegates to scripts/docs_site_validation (ValidationFinding type, build/scan helpers). (file present and modified in PR.)
[::nold-ai/specfact-cli::] scripts/docs_site_validation.py — new shared validation API (exports ValidationFinding, build_route_index, resolve_internal_link_hybrid, scan_published_route_body_links, scan_frontmatter_findings, scan_gemfile_lock_installability). Consumed by check-docs-commands and unit tests.
[::nold-ai/specfact-cli::] scripts/pre-commit-quality-checks.sh — added staged-docs gating and run_docs_site_validation_gate that invokes "hatch run python scripts/check-docs-commands.py" when docs/ or related paths change (local pre-commit consumer of the validator).
[::nold-ai/specfact-cli::] pyproject.toml (tool scripts) — defines check-docs-commands script entry (hatch task) pointing to scripts/check-docs-commands.py (build/test tooling consumer).
[::nold-ai/specfact-cli::] tests/unit/docs/test_code_review_docs_parity.py — new unit test that imports the Code Review Typer app (review_app) via review_commands.review_app and asserts parity between public Typer/Click --* option flags and docs/bundles/code-review/run.md (ties docs content to CLI surface; will break if CLI flags change without docs update).
[::nold-ai/specfact-cli::] tests/unit/docs/test_docs_review.py and tests/unit/test_check_docs_commands_script.py — updated to import and call functions from scripts/docs_site_validation (tests directly depend on the new API/ValidationFinding shape and exported helpers).
[::nold-ai/specfact-cli::] .github/workflows/pr-orchestrator.yml — now pins specfact-cli==0.46.2 when installing CLI in CI (affects which CLI version tests/workflows run against).
[::nold-ai/specfact-cli::] docs/* (multiple docs including docs/bundles/code-review/run.md and docs/modules/code-review.md) — docs were updated to reflect CLI flags (e.g., --bug-hunt, --mode, --focus, --level, --json/--out, invalid combinations); tests enforce parity between these docs and the actual Typer command surface.
[::nold-ai/specfact-cli::] many tests and openspec specs (examples: tests/unit/specfact_cli/test_dogfood_self_review.py, openspec/specs/review-run-command/spec.md, docs/modules/code-review.md) — repository contains numerous references to "specfact code review run" and its flags; the new parity tests and docs-validator increase coupling between CLI option surface, docs, CI, and pre-commit gating.
Implications / risk areas observed:
- Changes to scripts/docs_site_validation API (ValidationFinding shape or exported function names) will break check-docs-commands.py and unit tests that call it ([::nold-ai/specfact-cli::scripts/check-docs-commands.py], [::nold-ai/specfact-cli::tests/unit/docs/test_docs_review.py], [::nold-ai/specfact-cli::tests/unit/test_check_docs_commands_script.py]).
- Changes to the Code Review Typer command flags (review_app) must be mirrored in docs/bundles/code-review/run.md or tests/unit/docs/test_code_review_docs_parity.py will fail ([::nold-ai/specfact-cli::tests/unit/docs/test_code_review_docs_parity.py], [::nold-ai/specfact-cli::docs/bundles/code-review/run.md]).
- Pre-commit and CI now run the docs validator for docs-only changes; failing findings from docs_site_validation will block commits and CI Pages deploys ([::nold-ai/specfact-cli::scripts/pre-commit-quality-checks.sh], [::nold-ai/specfact-cli::.github/workflows/docs-pages.yml]).
🔇 Additional comments (8)
.github/workflows/pr-orchestrator.yml (1)
143-143: Pinnedspecfact-cliinstall is a good CI stability guardrail.This keeps workflow behavior deterministic and aligned with contract-test tooling expectations. As per coding guidelines ".github/workflows/**: CI: secrets, hatch/verify-modules-signature gates, contract-test alignment, action versions".
tests/unit/workflows/test_pr_orchestrator_signing.py (1)
37-40: Nice targeted regression test for workflow contract pinning.This directly guards the adapter boundary expectation that CI installs the intended
specfact-cliversion. As per coding guidelines "tests/**/*.py: Contract-first and integration tests: migration suites, bundle validation, and flakiness. Ensure changes to adapters or bridges have targeted coverage."requirements-docs-ci.txt (1)
1-11: Pinned docs CI dependencies are deterministic and coherent.This manifest is clear, fully pinned, and fits the docs-validation CI contract.
tests/unit/test_pre_commit_quality_parity.py (1)
38-40: Pre-commit parity coverage correctly includes the docs validation gate.The added required fragments align with the new gate function and invocation path.
.github/workflows/docs-pages.yml (1)
8-8: Docs-pages validation wiring looks correct and release-safe.The new trigger and the pinned docs-validation step (including
--jekyll-bundle-check) are aligned with the shared validator flow.Also applies to: 56-65
scripts/pre-commit-quality-checks.sh (1)
76-109: Docs gate ordering is correct for adapter-boundary parity.Running docs validation before safe-change bypass closes the local/CI parity gap for docs-only changes.
Also applies to: 260-260, 279-279
docs/bundles/code-review/run.md (1)
30-37: Option-surface documentation update is well aligned with the current run command.Nice parity improvement for the bundled-module docs.
.github/workflows/docs-review.yml (1)
12-17: Docs-review workflow changes are consistent with parity guardrails.The trigger expansion, pinned install, and parity test inclusion line up with the new docs-validation contract.
Also applies to: 25-30, 57-57, 63-63
Document invalid --json/--score-only pairing in the code-review run bundle. Normalize OpenSpec delta spec headings for markdownlint increment rules and align review-run-command spec with --path targeting and published-link cases. Harden docs_site_validation: treat README like other pages for route indexing, catch bundle check timeouts as categorized findings, and fix README links so check-docs-commands passes. Update parity and workflow tests to follow resolver/CLI flags and public check-docs-commands ordering without coupling to helper script paths. Made-with: Cursor
1 participant
Summary
This change hardens the modules documentation site and quality gates for the OpenSpec work tracked as
docs-15-code-review-validation-guardrails. It adds shared validation for published-route link semantics, front matter completeness, and optionalbundle checkcoverage fordocs/Gemfile.lock, wires those checks into pre-commit (when docs or validation scripts change) and intodocs-review/docs-pagesworkflows, fixes bundle overview and guide links that broke under Jekyll permalinks, refreshesdocs/Gemfile.lockfor resolvable Ruby deps, and aligns Code Review bundle and module docs with the currentspecfact code review runsurface. A regression test fix ensures isolatedgitsubprocesses in tests never inheritGIT_DIR/GIT_WORK_TREEfrom the environment (which could otherwise mutate the outer worktree).Refs:
Scope
packages/registry/index.json,packages/*/module-package.yaml).github/workflows/*)docs/*,README.md,AGENTS.md)scripts/sign-modules.py,scripts/verify-modules-signature.py)Bundle Impact
No bundle or module manifest version changes in this PR (docs, scripts, tests, and workflows only).
Validation Evidence
Local runs on this branch (2026-04-15):
hatch run format— passhatch run type-check— passhatch run lint— passhatch run yaml-lint— passhatch run check-bundle-imports— pass (via pre-commit Block 1)hatch run contract-test— pass (618 tests; invoked from pre-commit Block 2)hatch run test— pass (618 tests)python scripts/check-docs-commands.py— pass (no findings)hatch run verify-modules-signature --payload-from-filesystem --enforce-version-bump— passhatch run specfact code review run --json --out .specfact/code-review.json --scope changed—PASS,ci_exit_code0, emptyfindings(full-repo--scope fullremains red on unrelated historical complexity elsewhere)Required local gates
hatch run formathatch run type-checkhatch run linthatch run yaml-linthatch run check-bundle-importshatch run contract-testhatch run smart-test(orhatch run test)Signature + version integrity (required)
hatch run verify-modules-signature --payload-from-filesystem --enforce-version-bumppasses (matches PRs targetingdev)main, also confirmed:hatch run verify-modules-signature --require-signature --payload-from-filesystem --enforce-version-bump(and/or approval triggeredsign-modules-on-approvalfor same-repo PRs)dev/mainsame-repo PRs) (N/A for this diff)CI and Branch Protection
verify-module-signaturessign-modules-on-approval(on approval, same-repo PRs todev/mainonly)quality (3.11)quality (3.12)quality (3.13)Docs / Pages
docs/)docs-pages.yml, if changed)specfact-clidocs updated (if applicable)Checklist