[Change] code-review-09 - integrate code review into pre-commit workflows

.github/workflows/pr-orchestrator.yml

@@ -139,11 +139,12 @@ jobs:
           cache-dependency-path: |
             pyproject.toml
 
-      - name: Install hatch and coverage
+      - name: Install hatch and fallback test dependencies
         if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
         run: |
           python -m pip install --upgrade pip
-          pip install "hatch" "virtualenv<21" coverage
+          pip install "hatch" "virtualenv<21" coverage "coverage[toml]" pytest pytest-cov pytest-mock pytest-asyncio pytest-xdist pytest-timeout
+          pip install -e .
 
       - name: Cache hatch environments
         if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
@@ -199,7 +200,7 @@ jobs:
       - name: Generate coverage XML for quality gates
         if: needs.changes.outputs.skip_tests_dev_to_main != 'true' && env.RUN_UNIT_COVERAGE == 'true'
         run: |
-          hatch -e hatch-test.py3.12 run xml
+          python -m coverage xml -o logs/tests/coverage/coverage.xml --data-file=logs/tests/coverage/.coverage
 
       - name: Upload test logs
         if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
@@ -428,26 +429,16 @@ jobs:
           cache: "pip"
           cache-dependency-path: |
             pyproject.toml
-      - name: Install hatch
+      - name: Install type-check dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install "hatch" "virtualenv<21"
-      - name: Cache hatch environments
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.local/share/hatch
-            ~/.cache/uv
-          key: ${{ runner.os }}-hatch-typecheck-py312-${{ hashFiles('pyproject.toml') }}
-          restore-keys: |
-            ${{ runner.os }}-hatch-typecheck-py312-
-            ${{ runner.os }}-hatch-
+          pip install -e . basedpyright
       - name: Run type checking
         run: |
           echo "🔍 Running basedpyright type checking..."
           mkdir -p logs/type-check
           TYPE_CHECK_LOG="logs/type-check/type-check_$(date -u +%Y%m%d_%H%M%S).log"
-          hatch run type-check 2>&1 | tee "$TYPE_CHECK_LOG"
+          python -m basedpyright --pythonpath "$(python -c 'import sys; print(sys.executable)')" 2>&1 | tee "$TYPE_CHECK_LOG"
           exit "${PIPESTATUS[0]:-$?}"
       - name: Upload type-check logs
         if: always()
@@ -476,28 +467,22 @@ jobs:
           cache-dependency-path: |
             pyproject.toml
 
-      - name: Install dependencies
+      - name: Install lint dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install "hatch" "virtualenv<21"
-
-      - name: Cache hatch environments
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.local/share/hatch
-            ~/.cache/uv
-          key: ${{ runner.os }}-hatch-lint-py312-${{ hashFiles('pyproject.toml') }}
-          restore-keys: |
-            ${{ runner.os }}-hatch-lint-py312-
-            ${{ runner.os }}-hatch-
+          pip install -e . ruff basedpyright pylint
 
       - name: Run linting
         run: |
           echo "🔍 Running linting checks..."
           mkdir -p logs/lint
           LINT_LOG="logs/lint/lint_$(date -u +%Y%m%d_%H%M%S).log"
-          hatch run lint 2>&1 | tee "$LINT_LOG" || echo "⚠️ Linting incomplete"
+          {
+            ruff format . --check
+            python -m basedpyright --pythonpath "$(python -c 'import sys; print(sys.executable)')"
+            ruff check .
+            pylint src tests tools
+          } 2>&1 | tee "$LINT_LOG" || echo "⚠️ Linting incomplete"
       - name: Upload lint logs
         if: always()
         uses: actions/upload-artifact@v4

.pre-commit-config.yaml

@@ -1,6 +1,11 @@
 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

CHANGELOG.md

@@ -8,6 +8,22 @@ All notable changes to this project will be documented in this file.
 **Important:** Changes need to be documented below this block as this is the header section. Each section should be separated by a horizontal rule. Newer changelog entries need to be added on top of prior ones to keep the history chronological with most recent changes first.
 
 
+---
+
+## [0.42.1] - 2026-03-17
+
+### Added
+
+- Integrated `specfact code review run` into this repository's pre-commit flow through a staged-file review gate and helper script, so blocking review verdicts fail commit validation while advisory verdicts remain green.
+
+### Changed
+
+- Expanded `docs/modules/code-review.md` with repo-local pre-commit setup, portable adoption guidance for other projects, optional `house_rules` workflow guidance, and JSON-first reward-ledger documentation with optional backend persistence.
+
+### Fixed
+
+- Declared `radon` in the runtime, dev, and Hatch default environments so `specfact code review run` can resolve its complexity runner consistently in fresh local bootstraps and worktrees.
+
 ---
 
 ## [0.41.0] - 2026-03-11

CONTRIBUTING.md

@@ -75,6 +75,10 @@ hatch test --cover -v
 ### Pre-commit Checks
 
 ```bash
+# Install repo hooks
+pre-commit install
+scripts/setup-git-hooks.sh
+
 # Format code
 hatch run format
 
@@ -88,6 +92,10 @@ hatch run lint
 hatch run contract-test-full
 ```
 
+The repo-owned pre-commit flow now also runs `specfact code review run` on
+staged Python files and blocks commits only when the review verdict is
+blocking.
+
 ## Contributor License Agreement (CLA)
 
 Before we can accept your pull request, you need to agree to our [Contributor License Agreement](./CLA.md). By opening a pull request, you acknowledge that you've read and agreed to the terms.

docs/modules/code-review.md

@@ -99,3 +99,84 @@ The scaffolded `ReviewReport` envelope carries these fields:
 - `schema_version`, `run_id`, `timestamp`, `overall_verdict`, and `ci_exit_code` are always present.
 - Review-specific fields (`score`, `reward_delta`, `findings`, `summary`, `house_rules_updates`) extend the standard evidence shape without replacing it.
 - CI can treat `ci_exit_code` as the contract-bound gate result from the start.
+
+## Pre-Commit Review Gate
+
+This repository wires `specfact code review run` into pre-commit before a
+commit is considered green.
+
+The local hook entry lives in `.pre-commit-config.yaml`:
+
+```yaml
+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?$
+```
+
+The helper script scopes the gate to staged Python files only and then runs:
+
+```bash
+specfact code review run --score-only <staged-python-files>
+```
+
+Commit behavior:
+
+- `PASS` keeps the commit green
+- `PASS_WITH_ADVISORY` keeps the commit green
+- `FAIL` blocks the commit
+
+To install the repo-owned hook flow:
+
+```bash
+pre-commit install
+scripts/setup-git-hooks.sh
+```
+
+## Add to Any Project
+
+For another project, you can use the same gate without this repo's helper
+script by adding a local pre-commit hook that runs `specfact` directly:
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: specfact-code-review
+        name: specfact code review gate
+        entry: specfact code review run --score-only
+        language: system
+        files: \.pyi?$
+```
+
+This makes code review part of commit validation before the commit is green.
+Pre-commit passes the staged matching files as arguments to the command.
+
+## Optional house_rules Workflow
+
+If a project maintains `house_rules`, keep that guidance current with:
+
+```bash
+specfact code review rules update
+specfact code review rules show
+```
+
+The pre-commit gate does not require a `house_rules` file, but projects can use
+the generated guidance as part of their broader coding workflow.
+
+## Ledger Storage
+
+For most local and offline use cases, the reward ledger should be treated as a
+JSON file stored at:
+
+```text
+~/.specfact/ledger.json
+```
+
+That local JSON path is the default assumption for day-to-day usage. Supabase
+remains optional when a team explicitly configures remote persistence or wants a
+shared backend-backed ledger.

openspec/changes/code-review-09-f4-automation-upgrade/CHANGE_VALIDATION.md

@@ -1,48 +1,59 @@
 # Change Validation Report: code-review-09-f4-automation-upgrade
 
-**Validation Date**: 2026-03-10
+**Validation Date**: 2026-03-17
 **Change Proposal**: [proposal.md](./proposal.md)
-**Validation Method**: Dry-run simulation — new module in specfact-cli-modules (no existing production code modified)
+**Validation Method**: OpenSpec artifact review after grounding scope against the
+current `specfact-cli` repository and internal planning documents
 
 ## Executive Summary
 
 - Breaking Changes: 0 detected
-- Dependent Files: 0 (purely additive new module in specfact-cli-modules)
-- Impact Level: Low (no existing specfact-cli commands or interfaces modified)
+- Dependent Files: Low to medium, centered on `.pre-commit-config.yaml`,
+  review-gate integration helpers, and `docs/modules/code-review.md`
+- Impact Level: Medium
 - Validation Result: Pass
 - User Decision: N/A
 
 ## Breaking Changes Detected
 
-None. This change is purely additive:
-- New module package in specfact-cli-modules
-- No existing production code in specfact-cli is modified
-- `bundle_group_command: code` extends the existing group additively via `_merge_typer_apps`
+None. The rewritten change adds repo-local enforcement and documentation rather
+than changing the review verdict model or public command semantics.
 
 ## Dependencies Affected
 
 ### Critical Updates Required
-None.
+
+- The previously proposed `n8n` / `F-4` / `coding-workflow.js` integrations were
+  removed because they are not grounded in the current repository surface.
 
 ### Recommended Updates
-None.
+
+- Update GitHub issue `#393` so backlog text matches the rewritten OpenSpec
+  change instead of the stale F-4 automation framing.
 
 ## Impact Assessment
 
-- **Code Impact**: New files only in specfact-cli-modules; additive extension in specfact-cli command registry
-- **Test Impact**: New test files in specfact-cli-modules; no existing tests modified
-- **Documentation Impact**: docs/modules/code-review.md to be created
-- **Release Impact**: Minor (new feature; new installable module)
+- **Code Impact**: `.pre-commit-config.yaml` and any repo-owned review-gate helper
+- **Test Impact**: Targeted validation for pre-commit gating behavior and staged-file selection
+- **Documentation Impact**: `docs/modules/code-review.md` plus any related adoption guidance
+- **Release Impact**: Minor integration improvement on top of existing code-review commands
 
 ## Format Validation
 
 - **proposal.md Format**: Pass — has Why, What Changes, Capabilities, Impact, Source Tracking
 - **tasks.md Format**: Pass — git worktree first, TDD-first enforced, PR last, post-merge cleanup
-- **specs Format**: Pass — ADDED Requirements with Requirement + Scenario blocks in GIVEN/WHEN/THEN
+- **specs Format**: Pass — ADDED requirements aligned to pre-commit gating and portable adoption
 - **Config.yaml Compliance**: Pass — TDD order, git workflow, quality gates, docs task included
 
+## Dependency Analysis
+
+- New capabilities: `pre-commit-review-gate`, `portable-review-adoption`
+- Modified capability: `reward-ledger` (deployment/documentation posture only)
+- Primary dependencies: `code-review-01`, `code-review-02`, `code-review-03`,
+  `code-review-04`, `code-review-06`
+
 ## OpenSpec Validation
 
 - **Status**: Pass
 - **Command**: `openspec validate code-review-09-f4-automation-upgrade --strict`
-- **Issues Found/Fixed**: 0 (after spec format correction to GIVEN/WHEN/THEN)
+- **Issues Found/Fixed**: 0

openspec/changes/code-review-09-f4-automation-upgrade/TDD_EVIDENCE.md

@@ -0,0 +1,66 @@
+# TDD Evidence: code-review-09-f4-automation-upgrade
+
+## Failing Validation Before Implementation
+
+Date: 2026-03-17
+
+Command:
+
+```bash
+.venv/bin/pytest tests/unit/scripts/test_pre_commit_code_review.py tests/unit/scripts/test_pre_commit_smart_checks_docs.py tests/unit/scripts/test_code_review_module_docs.py -q
+```
+
+Expected failure reasons before implementation:
+
+- `scripts/pre_commit_code_review.py` did not exist
+- `scripts/pre-commit-smart-checks.sh` did not invoke the code review gate
+- `docs/modules/code-review.md` did not yet describe the repo pre-commit gate,
+  portable adoption guidance, or JSON-first ledger posture
+
+## Passing Validation After Implementation
+
+Date: 2026-03-17
+
+Command:
+
+```bash
+.venv/bin/pytest tests/unit/scripts/test_pre_commit_code_review.py tests/unit/scripts/test_pre_commit_smart_checks_docs.py tests/unit/scripts/test_code_review_module_docs.py -q
+```
+
+Result:
+
+- 11 tests passed
+- Verified staged-file filtering, PASS/PASS_WITH_ADVISORY non-blocking behavior,
+  FAIL blocking behavior, actionable setup guidance, and updated module
+  documentation coverage
+
+## Integration Validation and Quality Evidence
+
+Date: 2026-03-17
+
+Commands:
+
+```bash
+PYLINTHOME=/tmp/pylint .venv/bin/pylint scripts/pre_commit_code_review.py tests/unit/scripts/test_pre_commit_code_review.py tests/unit/scripts/test_pre_commit_smart_checks_docs.py tests/unit/scripts/test_code_review_module_docs.py
+.venv/bin/ruff check scripts/pre_commit_code_review.py tests/unit/scripts/test_pre_commit_code_review.py --fix
+.venv/bin/ruff format scripts/pre_commit_code_review.py tests/unit/scripts/test_pre_commit_code_review.py
+PATH=$(pwd)/.venv/bin:$PATH .venv/bin/specfact code review run --json scripts/pre_commit_code_review.py tests/unit/scripts/test_pre_commit_code_review.py tests/unit/scripts/test_pre_commit_smart_checks_docs.py tests/unit/scripts/test_code_review_module_docs.py
+PATH=$(pwd)/.venv/bin:$PATH .venv/bin/python scripts/pre_commit_code_review.py scripts/pre_commit_code_review.py tests/unit/scripts/test_pre_commit_code_review.py tests/unit/scripts/test_pre_commit_smart_checks_docs.py tests/unit/scripts/test_code_review_module_docs.py
+```
+
+Results:
+
+- Targeted `pylint` on the new helper/tests passed with `10.00/10`
+- Targeted `ruff` checks passed after one formatting/import cleanup pass
+- Direct `specfact code review run` on the changed Python scope passed with
+  `overall_verdict=PASS`, `score=116`, `ci_exit_code=0`
+- The remaining review findings are advisory CrossHair notes only
+- `radon` was initially missing from the worktree `.venv`; declaring it in
+  `pyproject.toml` and installing it into the local environment resolved the
+  blocking review failure
+
+Known repo baseline limitation:
+
+- Full repo-wide `pylint src tests tools` remains red on pre-existing unrelated
+  findings outside this change, so the repo-wide `hatch run lint` task is left
+  open intentionally