code-review-runner

# /code-review-runner Deterministic code review with LLM-powered findings. Two-tier architecture: - **T0 (deterministic)**: best-practices-* validators, ruff lint, compile() check, file limits - **T1 (LLM)**: codex/scillm review with structured findings prompt Each finding is scored by severity. Suggested fixes remain advisory because the runner does not apply them; current-tree compilation or DoD results cannot validate a proposed fix. Critical and major findings fail the review until they are reconciled. SciLLM requests use the active proxy key from the environment or running proxy container and always send `X-Caller-Skill: code-review-runner`. A 401 from a stale environment key triggers one retry with the running proxy container key. The Codex backend uses the current one-shot `gpt-5.5` route and omits `temperature` and `max_tokens` as required by the SciLLM paved path. An HTTP failure, empty assistant response, or malformed findings payload makes the review status `error` and the CLI exits nonzero; zero provider output must never become PASS. ## Architecture ``` Input: ReviewSpec (files, cwd, context, dod_command) | v T0: Deterministic validators (no LLM) - ruff lint (Python files) - compile() syntax check (Python files) - best-practices-python (800 LOC, loguru, httpx, etc.) - best-practices-d3 (D3 anti-patterns for TSX/TS) - best-practices-skills (SKILL.md structure) | v T1: LLM review (scillm codex or provider of choice) - Reads all target files + context - Produces structured findings (severity, location, description, fix) - Suggested fixes remain advisory until applied and independently checked | v Scoring: findings impact is severity-derived; unapplied fixes remain advisory | v Output: ReviewResult JSON - findings[]: severity, location, description, suggested_fix, validated - t0_violations[]: deterministic rule violations - score: 0.0-1.0 quality score - summary: one-line verdict ``` ## Usage ```bash # Review files with default settings (scillm codex) ./run.sh review <spec.json> # Dry-run: show T0 validators only, no LLM call ./run.sh dry-run <spec.json> # Parse result ./run.sh result <result.json> ``` ## Spec Format ```json { "task_id": "review-auth-module", "files": ["src/auth.py", "src/auth_test.py"], "cwd": "/path/to/repo", "context": "Auth module rewrite for compliance", "dod_command": "uv run pytest tests/test_auth.py -q", "backend": "codex", "max_rounds": 2, "base_ref": "origin/main" } ``` Set `base_ref` for pull-request or branch review. The runner then includes the authoritative git diff in the model request and fails closed if the diff cannot be built or is empty. File excerpts are supporting context, not a substitute for the change set. ## Scoring | Severity | Weight | Description | |----------|--------|-------------| | critical | 1.0 | Security, data loss, crash | | major | 0.7 | Logic error, contract violation | | minor | 0.3 | Style, naming, minor inefficiency | | info | 0.1 | Suggestion, nitpick | Suggested fixes remain advisory because this runner does not apply them. It must not mark a fix validated merely because the current tree compiles or its DoD passes. Critical or major advisory findings remain in the result and fail the review pending reconciliation. If any requested provider round fails, the whole review returns `error`; successful rounds cannot mask an unavailable or unauthorized review round. ## Integration | Skill | Role | |-------|------| | `/orchestrate` | T2 gate calls this after code-runner passes | | `/best-practices-python` | T0 validator: 800 LOC, loguru, httpx, etc. | | `/best-practices-d3` | T0 validator: D3 anti-patterns | | `/best-practices-skills` | T0 validator: SKILL.md structure | | `/review-code` | Fallback for full multi-round review | | `/memory` | Learn review patterns, recall prior findings | ## Pipeline Position ``` /code-runner (writes code) -> /code-review-runner (reviews it) -> /orchestrate (gates it) ```