anton-abyzov/specweave/sw-review

sw-review: adversarial review with citations

A fresh reader hunts for real failures in the increment's diff, cites path:line for each, re-checks every claim, and writes .specweave/increments/<id>/reports/review.md. This is also the quality check: its verdict says whether the increment is ready.

Non-negotiables

• Fresh context. The session that wrote the code never approves it. Use a new

session, a subagent if your tool supports them, or another model (below). If you wrote this code here and cannot get a fresh context, say so in the report.

• Every finding cites `path:line` and a concrete failure: input or state leads to

wrong output, a crash, a hang, data loss or a leak. "Consider refactoring" is not one.

• Re-verify. Re-open the lines and, where a test can show it, run one. Drop what

does not survive; mark what you could not prove as plausible.

• Severity is critical, high, medium or low. Critical and high block the close.
• At most 5 nits, in one line at the end.

Steps

1. Evidence first. specweave verify (or its existing reports/verify.md): red

tests, lint or build are findings before any reading.

1. Scope. Read spec.md (ACs, Approach, the tasks' Files) and review that diff,

not the repository: git diff $(git merge-base HEAD origin/HEAD)...HEAD -- <Files>.

1. Pass, in this order: correctness (logic, error paths, races, off-by-one) →

security (injection, path traversal, secrets, unsafe exec) → spec compliance (ACs claimed but not implemented, tests that assert nothing, mock the subject or only restate the implementation) → portability (bash-only commands, \ paths, BOMs, >> in PowerShell). --full: run the three lenses correctness, security and spec compliance separately (in parallel if your tool has subagents). Each lens returns only a JSON list of {"severity","file","line","summary","verified"}; merge by deduping on (file,line), then re-open every line yourself before it goes in the report.

1. Report in the shape below; specweave complete reads its verdict line. Optional

machine form, reports/review.json, nothing gates on it: {"ok":false,"findings":[{"severity":"high","file":"src/a.ts","line":88,"summary":"...","verified":true}]}.

1. Hand back. Each critical or high finding becomes a task in spec.md

(### T-09 Fix empty evidence + - AC: AC-02 | Files: ... | Test: ...) for sw-do, or is fixed and re-tested now. Then verify again and close with sw-done.

Another model

A model reviewing code its own family wrote shares that code's blind spots. specweave review hands the increment to a reviewer from another family: it reads who finished the tasks from the ledger (claude@mbp is Claude), runs Codex with GPT-6.1-Sol on Claude-written code (Claude Opus on OpenAI-written code), and writes reports/review-codex.md in the shape below plus a ledger note. Exit 0: ship; 3: fix first, or no verdict; 1: no reviewer installed, or it failed.

• Run it when review.crossModel is true in .specweave/config.json, when the user

asks for another model, or when you wrote the code and have no fresh context.

• --brief prints the brief (ACs, tasks and their Files, the diff) to paste into any

model by hand; --reviewer claude, --base origin/main and --timeout 45 override.

• review.reviewer pins one reviewer; review.reviewers.<name>.command adds a CLI that

reads the brief on stdin and answers on stdout, or into {out} when it names one.

Its findings get the same treatment as yours: re-open each line before acting on it.

reports/review.md

# Review: 0042 Ledger fold
Verdict: fix first · risk: high · 6 files · 2 findings (1 critical, 1 high)
Reviewer context: new session
 
## [critical] src/core/tasks/ledger.ts:142 lost claim under equal timestamps
Two agents claim T-01 in the same second; the fold sorts only by `at`, so both read
themselves as owner. Fix: break ties by `by`, then file order.
 
Nits: naming in ledger.ts:31.

Verdict is fix first while any critical or high finding survives, else ship. specweave complete notes a fix first verdict in the newest review report.

Manual path (no CLI)

Nothing changes: git diff and the project's own test runner are the whole toolchain, and you write reports/review.md yourself.