feat: doc frontmatter validation, v0.43.2 review JSON gate, and pre-commit review UX

.coderabbit.yaml

@@ -0,0 +1,105 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+#
+# CodeRabbit aligns with AGENTS.md: contract-first APIs, OpenSpec, Hatch quality gates.
+# `reviews.auto_review.base_branches` includes `dev` so PRs into `dev` are auto-reviewed (not only the
+# repo default branch). See https://docs.coderabbit.ai/reference/configuration (auto_review).
+# Pre-push / finalize: run `cr --base dev` (or `coderabbit review`) from repo root; see
+# https://docs.coderabbit.ai/cli/overview
+# PR description: include `@coderabbitai summary` (default placeholder) for the high-level summary.
+#
+language: "en-US"
+early_access: false
+tone_instructions: >-
+  Provide architectural insights on system design, scalability, and long-term maintainability.
+  Prioritize contract-first public APIs (@icontract, @beartype), Typer/Rich CLI boundaries, OpenSpec
+  traceability, and cross-repo impact for bundled modules.
+
+reviews:
+  profile: assertive
+  request_changes_workflow: false
+  high_level_summary: true
+  high_level_summary_in_walkthrough: true
+  review_details: true
+  sequence_diagrams: true
+  estimate_code_review_effort: true
+  assess_linked_issues: true
+  related_issues: true
+  related_prs: true
+  poem: false
+  collapse_walkthrough: true
+  changed_files_summary: true
+  review_status: true
+  commit_status: true
+  high_level_summary_instructions: |
+    Structure the summary for SpecFact CLI maintainers:
+    - User-visible behavior and CLI surface (commands, options, defaults).
+    - Contract/API impact: public functions, Pydantic models, module package boundaries.
+    - Testing and quality gates: contracts, hatch run contract-test, coverage implications.
+    - If applicable: OpenSpec change ID, docs/ and CHANGELOG touchpoints, module signing / version bumps.
+  auto_review:
+    enabled: true
+    drafts: false
+    auto_incremental_review: true
+    # PRs targeting `dev` (not only the GitHub default branch, e.g. `main`) get automatic reviews.
+    base_branches:
+      - "^dev$"
+  path_instructions:
+    - path: "src/specfact_cli/**/*.py"
+      instructions: |
+        Focus on modular CLI architecture: lazy module loading, registry/bootstrap patterns, and
+        dependency direction. Flag breaking changes to public APIs, Pydantic models, and resource
+        bundling. Verify @icontract + @beartype on public surfaces; prefer centralized logging
+        (get_bridge_logger) over print().
+    - path: "openspec/**/*.md"
+      instructions: |
+        Treat as specification source of truth: proposal/tasks/spec deltas vs. code behavior,
+        CHANGE_ORDER consistency, and scenario coverage. Surface drift between OpenSpec and
+        implementation.
+    - path: "tests/**/*.py"
+      instructions: |
+        Contract-first testing: meaningful scenarios, not redundant assertions already covered by
+        contracts. Flag flakiness, environment coupling, and missing coverage for changed behavior.
+    - path: ".github/workflows/**"
+      instructions: |
+        CI safety: secrets usage, workflow dependencies, alignment with hatch test / contract-test
+        gates, and action versions.
+    - path: "scripts/**/*.py"
+      instructions: |
+        Deterministic tooling: subprocess safety, Hatch integration, and parity with documented
+        quality gates (format, type-check, module signing).
+    - path: "docs/**/*.md"
+      instructions: |
+        User-facing accuracy: CLI examples match current behavior; preserve Jekyll front matter;
+        call out when README/docs index need sync.
+
+  tools:
+    ruff:
+      enabled: true
+    semgrep:
+      enabled: true
+    yamllint:
+      enabled: true
+    actionlint:
+      enabled: true
+    shellcheck:
+      enabled: true
+
+  pre_merge_checks:
+    title:
+      mode: warning
+      requirements: "Prefer Conventional Commits-style prefixes (feat:, fix:, docs:, test:, refactor:, chore:)."
+    issue_assessment:
+      mode: warning
+
+knowledge_base:
+  learnings:
+    scope: local
+  linked_repositories:
+    - repository: "nold-ai/specfact-cli-modules"
+      instructions: >-
+        Companion repo: bundled module packages (module-package.yaml), IDE prompts, and
+        modules.specfact.io content. When CLI surface, imports, or bundled module contracts change,
+        flag required updates, version bumps, and signature verification impacts.
+
+chat:
+  auto_reply: true

.github/workflows/docs-review.yml

@@ -9,9 +9,16 @@ on:
       - "**/*.md"
       - "**/*.mdc"
       - "docs/**"
+      - "docs/.doc-frontmatter-enforced"
       - "tests/unit/docs/**"
+      - "tests/unit/scripts/test_doc_frontmatter/**"
+      - "tests/integration/scripts/test_doc_frontmatter/**"
+      - "tests/helpers/doc_frontmatter.py"
+      - "tests/helpers/doc_frontmatter_fixtures.py"
+      - "tests/helpers/doc_frontmatter_types.py"
       - "scripts/check-docs-commands.py"
       - "scripts/check-cross-site-links.py"
+      - "scripts/check_doc_frontmatter.py"
       - "pyproject.toml"
       - ".github/workflows/docs-review.yml"
   push:
@@ -20,9 +27,16 @@ on:
       - "**/*.md"
       - "**/*.mdc"
       - "docs/**"
+      - "docs/.doc-frontmatter-enforced"
       - "tests/unit/docs/**"
+      - "tests/unit/scripts/test_doc_frontmatter/**"
+      - "tests/integration/scripts/test_doc_frontmatter/**"
+      - "tests/helpers/doc_frontmatter.py"
+      - "tests/helpers/doc_frontmatter_fixtures.py"
+      - "tests/helpers/doc_frontmatter_types.py"
       - "scripts/check-docs-commands.py"
       - "scripts/check-cross-site-links.py"
+      - "scripts/check_doc_frontmatter.py"
       - "pyproject.toml"
       - ".github/workflows/docs-review.yml"
   workflow_dispatch:
@@ -62,11 +76,14 @@ jobs:
         continue-on-error: true
         run: hatch run check-cross-site-links --warn-only
 
-      - name: Run docs review suite
+      - name: Validate documentation frontmatter (enforced paths; aligns with local docs-validate / pre-commit)
+        run: hatch run doc-frontmatter-check
+
+      - name: Run docs review test suites
         run: |
           mkdir -p logs/docs-review
           DOCS_REVIEW_LOG="logs/docs-review/docs-review_$(date -u +%Y%m%d_%H%M%S).log"
-          hatch run pytest tests/unit/docs/ -q 2>&1 | tee "$DOCS_REVIEW_LOG"
+          hatch run pytest tests/unit/docs/ tests/unit/scripts/test_doc_frontmatter/ tests/integration/scripts/test_doc_frontmatter/ -q 2>&1 | tee "$DOCS_REVIEW_LOG"
           exit "${PIPESTATUS[0]:-$?}"
 
       - name: Upload docs review logs

.github/workflows/pr-orchestrator.yml

@@ -151,7 +151,6 @@ jobs:
         uses: actions/cache@v4
         with:
           path: |
-            ~/.local/share/hatch
             ~/.cache/uv
           key: ${{ runner.os }}-hatch-tests-py312-${{ hashFiles('pyproject.toml', 'src/specfact_cli/modules/*/__init__.py') }}
           restore-keys: |
@@ -219,7 +218,7 @@ jobs:
   compat-py311:
     name: Compatibility (Python 3.11)
     runs-on: ubuntu-latest
-    needs: [changes, tests]
+    needs: [changes, verify-module-signatures]
     if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
     permissions:
       contents: read
@@ -248,7 +247,6 @@ jobs:
         uses: actions/cache@v4
         with:
           path: |
-            ~/.local/share/hatch
             ~/.cache/uv
           key: ${{ runner.os }}-hatch-compat-py311-${{ hashFiles('pyproject.toml', 'src/specfact_cli/modules/*/__init__.py') }}
           restore-keys: |
@@ -274,7 +272,7 @@ jobs:
   contract-first-ci:
     name: Contract-First CI
     runs-on: ubuntu-latest
-    needs: [changes, tests, compat-py311]
+    needs: [changes, verify-module-signatures]
     if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
     permissions:
       contents: read
@@ -303,7 +301,6 @@ jobs:
         uses: actions/cache@v4
         with:
           path: |
-            ~/.local/share/hatch
             ~/.cache/uv
           key: ${{ runner.os }}-hatch-contract-first-py312-${{ hashFiles('pyproject.toml', 'src/specfact_cli/modules/*/__init__.py') }}
           restore-keys: |
@@ -336,7 +333,7 @@ jobs:
   cli-validation:
     name: CLI Command Validation
     runs-on: ubuntu-latest
-    needs: [changes, contract-first-ci]
+    needs: [changes, verify-module-signatures]
     if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
     permissions:
       contents: read
@@ -414,7 +411,7 @@ jobs:
   type-checking:
     name: Type Checking (basedpyright)
     runs-on: ubuntu-latest
-    needs: [changes, tests]
+    needs: [changes, verify-module-signatures]
     if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
     permissions:
       contents: read
@@ -449,7 +446,7 @@ jobs:
   linting:
     name: Linting (ruff, pylint)
     runs-on: ubuntu-latest
-    needs: [changes, tests]
+    needs: [changes, verify-module-signatures]
     if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
     permissions:
       contents: read

.pre-commit-config.yaml

@@ -1,14 +1,23 @@
 repos:
   - repo: local
     hooks:
-      - id: specfact-code-review-gate
-        name: Run code review gate on staged Python files
-        entry: hatch run python scripts/pre_commit_code_review.py
-        language: system
-        files: \.pyi?$
       - id: verify-module-signatures
         name: Verify module signatures and version bumps
         entry: hatch run ./scripts/verify-modules-signature.py --require-signature --enforce-version-bump
         language: system
         pass_filenames: false
         always_run: true
+      - id: check-doc-frontmatter
+        name: Check documentation ownership frontmatter (enforced paths)
+        entry: hatch run doc-frontmatter-check
+        language: system
+        files: ^(docs/.*\.md|USAGE-FAQ\.md)$
+        pass_filenames: false
+        always_run: false
+      - id: specfact-code-review-gate
+        name: Run code review gate on staged Python files
+        entry: hatch run python scripts/pre_commit_code_review.py
+        language: system
+        files: \.pyi?$
+        # Show summary + copy-paste lines on success; pre-commit hides hook output otherwise.
+        verbose: true

AGENTS.md

@@ -37,6 +37,9 @@ hatch run lint-workflows            # GitHub Actions actionlint
 
 # Code scanning
 hatch run scan-all                  # semgrep analysis
+
+# SpecFact code review JSON (dogfood; see "SpecFact Code Review JSON" below and openspec/config.yaml)
+hatch run specfact code review run --json --out .specfact/code-review.json
 ```
 
 ## Architecture
@@ -172,6 +175,36 @@ Run all steps in order before committing. Every step must pass with no errors.
 5. `hatch run contract-test`         # contract-first validation
 6. `hatch run smart-test`            # targeted test run (use `smart-test-full` for larger modifications)
 
+With `pre-commit` installed (`pre-commit install`), staged `*.py` / `*.pyi` files also run the local code review gate (`scripts/pre_commit_code_review.py`), which writes the same `.specfact/code-review.json` path. That hook is fast feedback; it does not replace the **PR / change-completion** review rules in the next section when your OpenSpec tasks require a full-scope run.
+
+### SpecFact Code Review JSON (Dogfood, Quality Gate)
+
+This matches **`openspec/config.yaml`** (project `context` and **`rules.tasks`** for code review): treat **`.specfact/code-review.json`** as mandatory evidence before an OpenSpec change is considered complete and before you rely on “all gates green” for a PR.
+
+**When to (re)run the review**
+
+- The file is **missing**, or
+- It is **stale**: the report’s last-modified time is older than any file you changed for this work under `src/`, `scripts/`, `tools/`, `tests/`, or under `openspec/changes/<change-id>/` **except** `openspec/changes/<change-id>/TDD_EVIDENCE.md` — evidence-only edits there do **not** by themselves invalidate the review; re-run when proposal, specs, tasks, design, or code change.
+
+**Command**
+
+```bash
+hatch run specfact code review run --json --out .specfact/code-review.json
+```
+
+- While iterating on a branch, prefer a **changed-files scope** when available (e.g. `--scope changed`) so feedback stays fast.
+- Before the **final PR** for a change, run a **full** (or equivalent) scope so the report covers the whole quality surface your tasks expect (e.g. `--scope full`).
+
+**Remediation**
+
+- Read the JSON report and fix **every** finding at any severity (warning, advisory, error, or equivalent in the schema) unless the change proposal documents a **rare, explicit, justified** exception.
+- After substantive edits, re-run until the report shows a **passing** outcome from the review module (e.g. overall verdict PASS / CI exit 0 per schema).
+- Record the review command(s) and timestamp in `openspec/changes/<change-id>/TDD_EVIDENCE.md` or in the PR description when the change touches behavior or quality gates.
+
+**Consistency**
+
+- OpenSpec change **`tasks.md`** should include explicit tasks for generating/updating this file and clearing findings (see `openspec/config.yaml` → `rules.tasks` → “SpecFact code review JSON”). Agent runs should treat those tasks and this section as the same bar.
+
 ### Module Signature Gate (Required for Change Finalization)
 
 Before PR creation, every change MUST pass bundled module signature verification:

CHANGELOG.md

@@ -9,6 +9,49 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.43.2] - 2026-03-29
+
+### Added
+
+- Documentation ownership frontmatter rollout:
+  - `scripts/check_doc_frontmatter.py`
+  - `docs/.doc-frontmatter-enforced` (rollout scope)
+  - `hatch run doc-frontmatter-check`
+  - Pre-commit hook integration
+  - Guide: `docs/contributing/docs-sync.md`
+  - Sample pages include the extended schema; use `--all-docs` for a full-site check.
+
+### Fixed
+
+- **Tests:** Register doc-frontmatter shared fixtures via root ``tests/conftest.py``
+  ``pytest_plugins`` (Pytest 8+ forbids ``pytest_plugins`` in nested conftests); scope env/cache
+  isolation to ``test_doc_frontmatter`` paths only.
+- OpenSpec (`openspec/config.yaml`): **SpecFact code review JSON** dogfood tasks — require a fresh
+  `.specfact/code-review.json`, remediate review findings before merge, and record TDD evidence; **freshness**
+  excludes `openspec/changes/<change-id>/TDD_EVIDENCE.md` from the staleness comparison so evidence-only edits
+  there do not by themselves force a new review run.
+- `scripts/pre_commit_code_review.py`: invoke review from repo root (`cwd`), emit JSON as above, and enforce a
+  300s subprocess timeout with `TimeoutExpired` handling so the hook cannot hang indefinitely.
+
+### Changed
+
+- **CI:** `Docs Review` GitHub Actions workflow runs `hatch run doc-frontmatter-check`
+  and includes doc-frontmatter unit/integration tests alongside `tests/unit/docs/`, with path
+  filters for frontmatter scripts and helpers.
+- Pre-commit `specfact-code-review-gate`: switched from `specfact code review run` with `--score-only` to
+  `specfact code review run --json --out .specfact/code-review.json`, writing governed `ReviewReport` JSON under
+  gitignored `.specfact/` for IDE and Copilot workflows; the hook now prints severity counts on stderr, a short
+  summary with the report path (absolute path hint), copy-paste prompts for Copilot/Cursor, and relies on
+  `verbose: true` so successful runs still surface that feedback next to the nested CLI output.
+- Documentation: `docs/modules/code-review.md` updated for the JSON report path and the pre-commit hook behavior.
+- Tests: `tests/unit/scripts/test_pre_commit_code_review.py` and `test_code_review_module_docs.py` updated for
+  `--json`/`--out`, repo-root `cwd`, and timeout handling.
+- Doc frontmatter validation now uses a Pydantic `DocFrontmatter` model, stricter `tracks` glob checks
+  (`fnmatch.translate` + `re.compile` after bracket/brace balance), and a reference page at
+  `docs/contributing/frontmatter-schema.md`.
+
+---
+
 ## [0.43.1] - 2026-03-28
 
 ### Changed

CONTRIBUTING.md

@@ -70,6 +70,7 @@ hatch test --cover -v
 - **Type Hints**: Use type hints with `@beartype` runtime checking
 - **Testing**: Contract-first testing with scenario tests
 - **Documentation**: Update relevant documentation
+- **Docs site (`docs/`)**: Jekyll pages keep existing frontmatter (`layout`, `title`, `permalink`, …). Pages listed in `docs/.doc-frontmatter-enforced` must also include the doc-sync ownership fields (`doc_owner`, `tracks`, `last_reviewed`, `exempt`, `exempt_reason`). See [docs/contributing/docs-sync.md](docs/contributing/docs-sync.md).
 - **Docstrings**: Follow Google Python Style Guide
 
 ### Pre-commit Checks

docs/.doc-frontmatter-enforced

@@ -0,0 +1,8 @@
+# Paths (relative to repo root) that must carry full doc-sync frontmatter.
+# Expand this list as the rollout progresses; use `scripts/check_doc_frontmatter.py --all-docs` for a full-site check.
+docs/index.md
+docs/getting-started/quickstart.md
+docs/core-cli/init.md
+docs/reference/documentation-url-contract.md
+docs/contributing/docs-sync.md
+docs/contributing/frontmatter-schema.md