thermo-nuclear-code-quality-review

Thermo-Nuclear Code Quality Review

Review current branch changes through five lenses, in order (the checkout you were launched in — execute-plan launches the reviewer in the ticket worktree). Phases 0–3 are review-first: report findings, change code only if the user says "fix". Phase 4 (docs) is always applied where a feature-docs flow exists. If the conversation was summarized mid-review, re-read this file before continuing — never grade from a summary of the lenses.

Maker/checker is unconditional for agent-authored diffs: if any part of the diff was written by an agent in any session (execute-plan or otherwise — resumed agent-authored branches included), run the review as a read-only subagent — the reviewer must not share the implementer's context or be able to edit. Manual invocation on a human-authored diff may run inline. No subagent facility in this harness → stop and tell the user; proceed inline only on their explicit say-so, and record reviewer: inline (no subagent — maker/checker not independent) in the ## Review entry so the degraded review is visible at resume and retro. Number every finding N | file:line | severity | problem | fix so accepted findings can be appended to the plan file as structured remediation tasks (see the review loop below).

Pinned review model: the reviewer subagent is launched with a pinned review model. Independence comes from the reviewer's fresh, read-only context (maker/checker above), not from running a different model — the reviewer may use the implementer session's own model. Never drop to a weaker model just to differ from it. Resolution, in order:

1. review-model: <slug> set on the line below → use exactly that slug. If the tool does not offer it, stop and ask the user; never silently substitute.
2. Not set → pick the strongest reasoning/thinking model the tool can actually launch (newest, highest thinking tier), the session's own model included. If that model is listed but fails to launch (quota, credits, rate limit), take the next strongest and say so. Record the slug chosen, and whether it matches the implementer's model, in the ## Review entry.

review-model: (unset — fill to pin a fixed slug)

This section is the single source of truth for the slug — write-plan and execute-plan reference it instead of hardcoding it; when the model changes, update it here only.

Persist the verdict: when a plan file exists for the branch, the invoking session (orchestrator) owns the ## Review entry, one per cycle, written in two halves — the reviewer subagent is read-only and cannot write the plan; on standalone inline runs the session itself writes both halves:

1. Before the reviewer runs: cycle <c> | reviewed @ <HEAD SHA> | base @ <base SHA> | suite: <cmd> → <result> — the full-suite evidence the ship rule below reads.
2. After the verdict: the 3-line rollup, the model used, and the reviewer subagent link, appended to that same entry.

A review that leaves no ## Review entry did not happen — execute-plan's resume check depends on it. An entry with no Verdict: line is an in-flight cycle. A ship verdict is valid only for its recorded HEAD and base SHAs — any later commit invalidates it and requires a new cycle, except commits touching only docs/ paths that leave spec decisions unchanged (doc sync, plan/spec promotion, ## Review entries). A docs commit that edits decisions in spec.md / design.md un-reviews the code; if the base branch moved, re-review before merge.

Step 0 — preconditions, then the diff.

1. Re-run guard: if the plan's last ## Review entry records Verdict: ship at the current HEAD (or differing from it only by docs-only commits that leave spec decisions unchanged), report "already reviewed at this commit" and stop — re-review only if the user explicitly forces it. A last entry with no Verdict: line is the in-flight cycle you are running — proceed.
2. Clean tree required: git status --porcelain must be empty. Staged, unstaged, and untracked changes are invisible to git diff <base>...HEAD and would silently escape review. Dirty tree → stop and report; have the work committed first.
3. Quirks doc: read the project quirks doc when one exists (e.g. docs/quirks.md — hard-learned domain gotchas) — its entries feed Phase 0's semantic-drift sweep and Phase 3.
4. Base & anchor: resolve the base (git symbolic-ref refs/remotes/origin/HEAD or main/master), then capture git rev-parse HEAD and git rev-parse <base> — they must match the current ## Review line's reviewed @ / base @; a mismatch means the suite evidence is for another commit (see the ship rule).
5. Review git diff <base>...HEAD. Lenses below reconcile cleanly: Phase 0 checks the diff does what was decided; Phase 1 removes what should not exist; Phase 2 restructures what remains.