branch-review

description: Review a branch before merge argument-hint: [commit hashes | from..to | blank = this branch] [low|medium|high|max]

Pre-merge review gate. General review, then a full security audit, then an adversarial verify pass, then a docs sweep. It never edits code: findings are reported and handed back, and fixing is a separate, separately authorized action. The docs sweep is the one stage that writes, and only to docs — it updates the project's docs for what this branch changed and commits exactly that.

Only Critical and High findings block the merge. Everything else is appended to the fix ledger (.factory/remember/fix-ledger.md) — a local, cumulative list, living beside MEMORY.md, usually gitignored, that /refactor (no arguments) works through between features. The report is blockers plus the ledger count. This command never runs /refactor itself — it nudges.

Run this before /release, which refuses to run without a review at the current HEAD SHA.

Guardrails

• Spawn a worker, mid tier stated explicitly (omitted inherits the parent's, not the balanced one; not cheapest/fastest either — judgment degrades there; never a vendor model name), and hand it this file's path — a worker has no skill text of its own. Fall back to running inline if your tool has no subagent mechanism.
• Escalate, never assume. Anything you cannot decide, cannot verify, or that this spec does not cover → stop and report it to the orchestrator (the main session). Never improvise, never widen scope, never fix a side issue you noticed along the way.
• The worker does the work itself — no delegation. The review subagent must not spawn subagents of its own. Everything it reports has to be something it read, ran, or grepped with its own tool calls; a relayed "I executed X" is hearsay. (Same rule /security carries inside stage 2.)
• No edits — three exceptions. You have no authorization to change code, even for a finding you are certain about. Report it. The only files you may write are .factory/remember/fix-ledger.md (append bullets; never rewrite or delete), .factory/remember/last-review.md (overwrite; the review record described at the end of this file), and the doc files Stage 4 touches — edited and then committed by that stage alone, never for code, skills, config, or tests.
• Prove it with two checks, because neither sees what the other does. git status --porcelain, at start and again before you report, proves the tree is clean — no code or config changed, and, when Stage 4 ran (review settled), that its doc edits landed as the last act before you report. It cannot police your own two .factory/ writes (.factory/ is normally gitignored), so also hash the files there before you start and again before you report:

  find .factory/remember -maxdepth 1 -type f -exec md5sum {} + | sort -k2
  

  and show the comparison: only fix-ledger.md and last-review.md may differ. And run git diff --name-only <reviewed sha>..HEAD before you report: it must list only the files on the record's docs: line — anything else means an edit escaped Stage 4's scope. Both results are shown on the proof: line of the closing block.