docs-15 follow-up: review fixes after merge to dev

[djm81]

Follow-up to the docs-15 work merged via #203. This PR applies the remaining review feedback that landed after that merge.

Changes

• Docs (run.md, code-review.md): Clarify Typer vs run_command() validation, document --json + --score-only, and use neutral “positional file paths” wording.
• OpenSpec (docs-15 change): Add H1 titles (MD041), hyphenate “overview-related”, and align review-run-command spec with the public files contract.
• docs_site_validation.py: Resolve directory links via index.md after README.md; do not swallow FileNotFoundError for missing bundle when running bundle check.
• Tests: Extend code-review docs parity checks for documented behavior strings and resolver/helper references.

Verification

• pytest tests/unit/docs/test_code_review_docs_parity.py
• python scripts/check-docs-commands.py
• hatch run lint

Made with Cursor

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Summary: docs-15 Follow-up Review Fixes (PR #205)

Bundle Surface & Runtime Behavior

No code or interface changes to specfact-code-review bundle. Documentation-only refinements to clarify validation strategy already implemented in the merged docs-15 PR #203:

• Validation tier clarification (not a new constraint): Typer entry-point _resolve_review_run_flags() enforces flag pair conflicts (--include-tests + --exclude-tests; --focus + targeting flags), raising typer.BadParameter.
• Command-layer validators (existing behavior): run_command() applies additional checks via _validate_review_request() and _raise_if_targeting_styles_conflict(), which also surface as typer.BadParameter.
• Documented incompatibility: --json and --score-only cannot be used together (now explicitly documented; behavior unchanged).
• Positional file targeting refinement: Updated terminology to explicitly align with public run(files: list[Path]) signature—"explicit positional files (file paths)" replaces previous phrasing.

Manifest & Semver

No changes to packages/specfact-code-review/module-package.yaml (v0.47.9 unchanged), integrity checksums, signature verification, or core compatibility bounds. Follow-up documentation fix only; no release trigger.

Cross-repo & Specfact-CLI Alignment

No required specfact-cli changes. In-repo OpenSpec reference documentation (docs-15 change set) updated for consistency and markdown linting:

• design.md, proposal.md, tasks.md: Added H1 title headers (MD041).
• specs/review-run-command/spec.md: Aligned terminology to public contract ("explicit positional files").
• specs/bundle-overview-pages/spec.md: Fixed hyphenation ("overview-related").

Docs Accuracy & modules.specfact.io Contract

• docs/bundles/code-review/run.md (+4/-2): New "Invalid combinations" and "Supported targeting" sections clarify which validator enforces which constraint, and specify positional targets as .py/.pyi files the pipeline accepts.
• docs/modules/code-review.md (+2/-1): Documents --json + --score-only incompatibility in the command options reference.
• scripts/docs_site_validation.py (+4/-3): Enhanced documentation-link validation—directory-link resolution now checks candidate/index.md (after candidate/README.md) for publishable doc targets; scan_gemfile_lock_installability() no longer silently skips when bundle unavailable (assumes it's on PATH).

Test Coverage & Docs Parity Enforcement

tests/unit/docs/test_code_review_docs_parity.py (+16/-0): Extended parity assertions to verify docs/bundles/code-review/run.md documents:

• Feature descriptions: progress, spinner/status, default mode format, "Optional reporting level override" section, --bug-hunt flag, "exploratory" mode, review-report.json output.
• Validator function names in invalid-combinations section: _resolve_review_run_flags(), _validate_review_request(), _raise_if_targeting_styles_conflict().

Parity tests ensure internal implementation details are correctly exposed in public-facing documentation.

Walkthrough

This PR documents code review CLI flag validation timing and sources, updates invalid combination guidance across documentation and specifications, refines spec headers, and enhances docs site validation with index.md support and bundle availability assumptions.

Changes

Cohort / File(s)	Summary
Code Review Documentation docs/bundles/code-review/run.md, docs/modules/code-review.md	Clarified flag validation timing by specifying that Typer's _resolve_review_run_flags() handles certain conflicts (e.g., --include-tests + --exclude-tests), while command-layer validators (_validate_review_request(), _raise_if_targeting_styles_conflict()) handle other pairings. Added --json + --score-only as invalid combination. Tightened positional target guidance to explicitly reference .py/.pyi files.
docs-15 Specification Updates openspec/changes/docs-15-code-review-validation-guardrails/design.md, proposal.md, tasks.md, specs/bundle-overview-pages/spec.md, specs/review-run-command/spec.md	Added top-level document headers and refined requirement wording; updated "Bundle overview related links" to "Bundle overview-related links" and refined positional file terminology to align with public run(files: list[Path]) signature.
Docs Site Validation Tooling scripts/docs_site_validation.py	Enhanced directory-link resolution to consider candidate/index.md in addition to candidate/README.md. Modified scan_gemfile_lock_installability() to remove FileNotFoundError handling, now assuming bundle is always available on PATH.
Documentation Parity Tests tests/unit/docs/test_code_review_docs_parity.py	Extended test assertions to validate presence of progress, spinner/status, enforce default formatting, --bug-hunt flag, exploratory mode, review-report.json, and internal validator function names (_resolve_review_run_flags(), _validate_review_request(), _raise_if_targeting_styles_conflict())

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related issues

• [Change] Docs validation guardrails for Code Review docs and module links #202: Implements the broader "docs-15 — Code review validation guardrails" effort that encompasses the validation documentation and specification work in this PR.

Possibly related PRs

• docs(docs-15): modules docs validation guardrails and code-review parity #203: Shares updates to docs/bundles/code-review/run.md and related parity test assertions documenting the same flag validation and CLI behavior.
• Promote dev to main: code review hardening, sidecar FastAPI, CI signing #193: Introduced the validator helper functions (_resolve_review_run_flags(), _validate_review_request(), _raise_if_targeting_styles_conflict()) that this PR's documentation and tests now explicitly reference.
• docs: add missing command reference pages #114: Originally introduced docs/bundles/code-review/run.md; this PR refines its validation guidance and timing details.

Suggested labels

documentation, openspec

🚥 Pre-merge checks | ❌ 3

❌ Failed checks (3 warnings)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	Title uses descriptive language but lacks a Conventional Commits prefix (feat:, fix:, docs:, etc.) as specified in requirements.	Adopt Conventional Commits format: consider 'docs: docs-15 follow-up review fixes' or 'fix: docs-15 post-merge validation' to meet style guidelines.
Description check	⚠️ Warning	Description provides clear context and verification steps but omits most required template sections including Scope checkboxes, Bundle Impact, Validation Evidence, and CI/branch protection details.	Complete the required template sections: add Scope checkboxes (docs changes indicated), Bundle Impact (list affected bundles), and Validation Evidence (include command outputs/workflow runs for all required gates).
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/docs-15-post-merge-review

---

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