metareview

Local-first review, repair, and hardening for humans and coding agents. metareview brings structured, adversarial, evidence-backed rigor to the parts of the software lifecycle where quality is actually decided — reviewing work before it lands, finding and fixing bugs with proof that the fix holds, and driving critical code to exhaustive tests. It's Go-backed, Markdown-friendly, model-swappable, and runs standalone or as a deeper review engine inside metaswarm, Superpowers, and Beads workflows.

What metareview does

• 🔍 Reviews before you commit. Named gates for specs, plans, code, epics, and PRs — ten adversarial reviewer lenses, deterministic blockers, and durable Markdown evidence. Not another "please review this" prompt: real gates with explicit verdicts. Lenses also report advisory findings — the real, important, not-defects class (latent defects, design risks, simplification opportunities, code smells) that a staff-level reviewer would actually raise, quality-gated so the channel informs instead of flooding.
• 🐛 Finds and fixes bugs — with proof. metareview fsm drives an audited discover → adjudicate → fix → prove → verify loop where a fix is trusted only when it carries a differential proof (a reproduction / pin / deletion) that metareview runs deterministically against your real tests. A {commit, summary} is not evidence; a proof is.
• 🧪 Hardens critical code toward exhaustive tests. Ingests mutation-tool output (gremlins / Stryker / mutmut) so a surviving mutant on a "100%-covered" line becomes an actionable finding, plus a Go-native coverage gate that only ratchets up.
• 🌐 Works across languages — Go, TypeScript/Jest, Vitest, Python/pytest — using each test runner's own structured output (no bespoke parser).
• 🔀 Model-swappable, auditable judges. Pick the judge per run — Claude, Codex/GPT, GLM, Kimi — every judge call is recorded and swappable, and runs are forkable and resumable.
• 📐 Typed lens-output contract (0.12). Lens findings carry a typed schema (tag/file/lines/issue/consequence/confidence/severity) validated deterministically before they can become candidates: malformed entries are rejected and counted (never crash the run), and an anchor-in-diff gate (±10 context lines) rejects findings that cite files or lines the diff never touched. Benchmarked in the lab (#159): the typed schema cut output tokens 27%, and the anchor gate is a real fabricated-finding catcher at F1-neutral. Judge transports also retry a gateway's 400 output-limit answer once at 4× the cap — transport headroom only, calibration frozen.
• 📚 Learns locally. Post-merge learning extracts durable, git-native, human-readable lessons — no proprietary SaaS lock-in.

→ New here? Read USAGE.md for a task-oriented walkthrough, and INSTALL.md to get set up.

Use Cases

• Workflow runs. metareview fsm drives sdlc-loop (discover → adjudicate → fix → verify) and review-loop as an audited state machine: the agent does the host nodes' work in its own warm session, judge calls are auditable and swappable, and resume is a fork. Contract: metareview fsm --agent-prompt; guide: docs/fsm/driving-a-workflow.md.

metareview is for any moment where a human or coding agent needs a second, structured pass before moving work forward:

• Spec review: check whether requirements are complete, testable, internally consistent, and aligned with the original user intent.
• Plan review: challenge implementation plans before work starts, including sequencing, scope control, missing failure paths, and acceptance gates.
• Architecture review: evaluate service boundaries, data flow, ownership, coupling, scalability, security, and fit with existing repository patterns.
• Feasibility review: identify technical unknowns, external dependencies, risky assumptions, migration hazards, and places where a spike is needed.
• Decomposition review: inspect epics, child tasks, dependency graphs, work-unit boundaries, and DoD coverage before agents start executing.
• Fractal child-plan review: recursively review decomposed child plans and sub-epics until every level is implementation-ready.
• Code review: review local task-sized code chunks before an agent claims done, with repository context and deterministic blocker handling.
• Test and acceptance review: verify that tests, acceptance criteria, validation evidence, and edge cases prove the intended behavior.
• PR readiness review: check branch-level completeness before push, PR creation, or merge readiness.
• Intent-drift review: after iterative revisions, compare the result back to the original request so local fixes do not quietly change the mission.
• Post-merge learning: extract durable lessons from merged work, review feedback, failures, and session history into local knowledge.
• Repository knowledge review: use service inventories, Beads knowledge, session history, and prior GitHub context to avoid duplicate services and repeated mistakes.

What Is This?

metareview brings the discipline of structured, adversarial agent workflows to the review side of software development. It gives humans and coding agents repeatable gates for:

• reviewing specs, plans, architecture notes, designs, decompositions, and documentation
• reviewing local task-sized code chunks before an agent claims the task is done
• checking whether an epic or parent task is actually ready after child tasks complete
• checking whether a branch is ready to push, open as a PR, or merge
• extracting post-merge learning into durable local knowledge

On first use in an existing repository, metareview performs the same kind of initial repository analysis that experienced reviewers do manually: it looks for existing architecture notes, service inventories, Beads knowledge, prior sessions, and GitHub history. If no service registry exists, setup can create a metareview-compatible docs/SERVICE_INVENTORY.md seed so future reviews have a shared map of important services, ownership boundaries, and repeated code paths.

Unlike proprietary SaaS review products such as CodeRabbit, Greptile, and similar hosted reviewers, metareview keeps this learning local, nonproprietary, and user-readable. Its knowledgebase is Markdown/JSONL-friendly and can be synced through git. Each time review feedback is resolved and work is merged, metareview can incorporate useful lessons, idiosyncratic repository decisions, and reviewer calibration while pruning stale, overly specific, or self-evident entries as the codebase evolves.

The goal is not another loose "please review this" prompt. The goal is a review harness with named gates, explicit evidence, deterministic blocker policy, durable Markdown artifacts, service registry context, and knowledge feedback loops that help future agents avoid repeating mistakes.

Agentic Review Patterns

metareview is built around review patterns that work well when humans and coding agents are collaborating:

• Adversarial multi-agent reviews: run independent reviewer lenses such as architecture, code quality, security, test adequacy, product/user impact, and acceptance completeness against the same artifact or diff.
• Iterations with hard gates: treat critical, high, and spec-contract findings as blockers; retry only while the gate reports NEEDS_REVISION, and stop autonomous retries on ESCALATED.
• Fractal review loops: decompose large work into epics, tasks, and child plans, then review each level before implementation proceeds.
• Cross-level intent checks: after multiple revision loops, compare the accepted child work back to the parent plan and original user request.
• Evidence-backed reviews: attach test output, validation commands, acceptance notes, and PR context so reviewers judge the real work product, not a summary.
• Deterministic local reviewers: use stable local rules for baseline gates so agents cannot skip known failure modes or bury blockers in prose.
• Specialist optional reviewers: bring in business analysts, user advocates, interaction designers, copywriters, SREs, security reviewers, and release engineers when the artifact needs those perspectives.
• Repository-knowledge priming: load service inventories, Beads knowledge, session history, and GitHub history so reviewers catch duplicated services, stale assumptions, and prior mistakes.
• Review artifact accountability: write durable Markdown context and review logs so future humans and agents can inspect what was reviewed, what blocked, and why it passed.
• Post-merge reflection: after a PR lands, extract accepted learnings, discarded candidates, and reviewer calibration so the next review starts smarter.

Highlights in 0.12.0

0.12.0 is the typed-contract release (evidence in dsifry/metareview#159):

• Typed lens-output contract + anchor-in-diff gate. Lens findings carry a typed schema (tag/file/lines/issue/consequence/confidence/severity), validated deterministically before they can become candidates: malformed entries are rejected and counted (never crash the run), and findings citing files or lines the diff never touched are rejected as fabricated (±10 context lines of slack). Lab-measured: output tokens −27%, the anchor gate F1-neutral while catching real fabrications.
• Output-cap retry in the judge transports. A gateway that answers a too-small token budget with a 400 instead of a truncation no longer kills the call: one retry at 4× the cap, prompts and calibration untouched.
• Benchmark-driven lens clauses + reclassifications. The eight 0.11.2-rc7 hunt clauses (config-backed sinks, authz-cache asymmetry, nonce-vs-static-secret, security-header regressions, CONFUSABLE-PAIR-BINDING, FALSY-ZERO-ON-NUMERIC-DOMAINS, MISLEADING-ERROR-CONTENT, dimensioned magic numbers), and two ratified reclassifications: dimensioned magic numbers and misleading error-message content are minor bugs, not style nits. Conformance corpus in CI pins the contract behavior.
• OAuth judges (from PR #160). claude-cli/… judge transport on the Claude Code CLI's logged-in session, plus the live-verified codex/ judge.

Highlights in 0.11.x

0.11.x is the benchmark-driven review-quality line (each change measured against a Compound Engineering baseline under the same adjudicator):

• 0.11.0 — the tenth lens. Runtime-reliability owns the ~90 confirmed findings no prior lens covered: unhandled async failure, optimistic-state desync, silent partial success, outbound-call hardening, error-shape leakage, and cross-boundary credential lifecycle. Five rubric briefs sharpened against the same evidence (FORMAT-DRIFT, api-contract broadening, cascading-failure async, RE-RUN-SAFETY, sibling-flag propagation).
• 0.11.1 — advisory findings, phrasing discipline, six new hunts. Lenses additionally report advisory findings — the staff-reviewer class (CE produces 21.8/PR of them where 0.11.0 produced 1.2) through three quality gates (stated consequence, steel-man rebuttal, convergence weighting) plus a one-call staff-surrogate filter on advisories only; validated bugs pass through untouched. Findings are phrased as definite claims about concrete failure modes (hedged phrasing measurably loses real findings to mis-adjudication). Six new hunt clauses from the measured residue: client/server schema-copy drift, partial-field stale updates, missing include/association, unbounded reply-to growth, silently changed defaults, and N×M duplicate remote operations. No new lens, no numeric caps; style nits stay suppressed.

Highlights in 0.10.0

0.10.0 turns metareview from a review harness into a review-and-repair harness:

• The proved SDLC loop. metareview fsm runs sdlc-loop-proved (discover → adjudicate → fix → prove → verify) as an audited state machine. The fix node must declare a differential proof for each bug, and the prove node runs it deterministically against your real test command — a reproduction (a test that fails-before / passes-after with a real assertion), a pin (a mutation-verified guard), or a deletion proof. A fix that can't prove itself doesn't clear the gate.
• Multi-language proofs. A pluggable test-convention seam reads each runner's own machine-readable output — go test -json, jest --json, vitest run --reporter=json, pytest JUnit XML — so the proof engine works for Go, TypeScript/Jest, Vitest, and Python/pytest without a bespoke parser.
• Model-swappable, auditable judges. Choose the judge per run with --judge-model: Claude (Anthropic API or the Claude Code CLI), Codex/GPT (via the Codex CLI), or any OpenAI-compatible provider including GLM and Kimi (OPENAI_BASE_URL). Reasoning models get a generous token budget automatically; compare two runs with metareview fsm diff.
• Mutation-aware review + a Go-native coverage gate. Pass a mutation report to any gate (--mutation-report) so surviving mutants surface as findings; a dishonest mutation summary (timeouts scored as kills) is refused. The coverage gate holds critical packages at 100% of statements and floors the rest.
• Consent-gated custom commands. The loop runs your real test command, but only after an explicit, hash-pinned human consent (--allow-custom-cmds <sha>).
• A git-native enforcement gate. metareview setup --install-hooks wires deterministic git hooks so the review gate is enforced by git itself: git push is blocked until the branch is review-clean (fail-closed; --no-verify escapes), while metareview never blocks a commit — its post-commit hook just nudges you to review the files it wrote. Because git invokes the hooks on the real operation, no spelling of the push command walks around the gate, and pushing a ref that is not the checked-out branch is blocked rather than silently waved through (#82). Install is interactive, non-destructive, and reversible.

See USAGE.md for how to use all of this, and CHANGELOG.md for full notes.

What Changed In 0.8.3

0.8.3 closes the sharded-review loop, so an oversized branch diff can now reach a passing gate:

• Sharded review results: on task-done and PR-ready, a branch diff over the context limit is measured in full, cut into content-stable shards, and written as one prompt pack per shard. The agent reviews each pack and writes a result file back.
• A clearable context-risk blocker: when every shard of the current plan has a fresh passing result — and, for a multi-shard plan, a cross-shard result covering the seams — the blocking "Review context risk" finding becomes advisory and the deterministic lints run over the whole branch diff. (epic-ready renders "not sharded": ingestion there is a follow-up.)
• Freshness by content hash: a result is matched to a shard by that shard's content hash, so a result about superseded content is ignored with a reason rather than silently counted.

What Changed From 0.4.0 To 0.6.0

0.6.0 made metareview more useful for real agent work by adding concrete coverage accounting around the review surface:

• Structured evidence receipts: metareview evidence run -- <command> records validation commands as JSON receipts with exit codes, timestamps, summaries, and output hashes. metareview evidence import --github-checks <pr-number> imports GitHub check results into the same receipt format. Task-done and PR-ready parse those receipts as validation evidence; epic-ready accepts the same evidence file as child-completion context.
• Context preflight: task-done, epic-ready, and PR-ready reviews now include a Context Profile that records raw and filtered diff size, generated review-artifact exclusions, omitted or truncated untracked files, and context-risk reasons.
• Shard planning: large or risky diffs get deterministic Context Shard Plans so agents can split review work by source paths while preserving a shared source diff hash.
• Review Manifest aggregation: task-done and PR-ready context packs now account for source paths, generated path dispositions, shard assignments, manifest hashes, static runtime status, and manifest blockers.
• Stateful PR-ready projection: PR-ready reconciles prior findings by target and run chain, so resolved or unrelated blockers do not keep blocking a later branch review.
• 0.6.0 metadata alignment: npm, Codex plugin, Claude Code plugin, and Go source checkout version reporting now agree on 0.6.0.

See CHANGELOG.md for the full release notes.

Install

npm Package

npm install -g metareview
metareview setup --check

Packaged releases include a built bin/metareview binary. Source checkout mode requires Go 1.26+ and falls back to:

go run ./cmd/metareview

Codex Plugin

codex plugin marketplace add dsifry/metareview
codex

Then open /plugins, select the metareview marketplace, and install metareview. Codex invokes metareview skills with $setup, $review-task-done, $review-epic-ready, $review-pr-ready, $review-artifact, $learn-post-merge, $status, and $fsm.

For local development from a checkout:

codex plugin marketplace add /path/to/metareview
codex

Claude Code Plugin

claude plugin marketplace add dsifry/metareview
claude plugin install metareview@metareview

Claude Code invokes metareview through /setup, /review-task-done, /review-epic-ready, /review-pr-ready, /review-artifact, /learn-post-merge, /status, and /fsm.

Source Checkout

git clone https://github.com/dsifry/metareview.git
cd metareview
npm install
npm run build
./bin/metareview setup --check

See INSTALL.md, docs/README.codex.md, and docs/README.claude.md for details.

To enforce the review gate with git-native hooks (block an unreviewed git push; nudge on each commit):

metareview setup --install-hooks        # interactive; --yes headless, --dry-run preview, --uninstall-hooks to reverse

It sets core.hooksPath for this clone (non-destructive — it refuses rather than override an existing one). See the "Enforce the review gate" section of INSTALL.md.

Works even better with metaswarm!

metaswarm is a multi-agent orchestration framework for Claude Code, Codex CLI, and Gemini CLI. It coordinates specialized agent roles, Beads-backed task graphs, Superpowers workflows, adversarial design and plan review gates, TDD-oriented work-unit execution, PR shepherding, and post-merge learning across a full software development lifecycle.

metareview is useful on its own, but it is designed to be strongest when installed alongside metaswarm, Superpowers, and Beads.

Use metaswarm as the lifecycle owner: issue intake, decomposition, Beads task graph, Superpowers planning/TDD workflows, orchestration, PR shepherding, and post-merge closure. Use metareview as the deeper review harness at the points where work quality is decided:

• artifact review before a spec, plan, or decomposition becomes implementation input
• task-done review after each work unit or small local chunk
• epic-ready review when child tasks are complete and the parent is ready to land
• pr-ready review before push, PR creation, or merge readiness
• post-merge learning after the PR is confirmed merged

In a repository that already has metaswarm/Superpowers/Beads, run:

metareview setup --check

Expected mode is metaswarm-extension. In that mode, metareview should extend metaswarm's review framework, not overwrite metaswarm files or take ownership of Beads task state.

How The Workflow Works

flowchart TD
    intent[Original intent, issue, spec, or human request]
    artifact[Review artifact<br/>metareview review artifact path]
    approved{Approved with no blockers?}
    revise[Revise artifact]
    decompose[Decompose into epics, tasks, or work units]
    child[Child unit decomposition]
    childReview[Fractal decomposition review<br/>review each child plan/artifact]
    childApproved{Child review passes?}
    childRevise[Revise child decomposition]
    implement[Implement smallest ready work unit]
    taskDone[Task-done review<br/>metareview review task-done target --base ref --evidence file]
    taskPass{Task review passes?}
    fix[Fix blockers and rerun with previous run]
    moreChildren{More child units?}
    parentIntent{Parent intent preserved?}
    parentRevise[Reconcile drift against original intent]
    epicReady[Epic-ready review<br/>metareview review epic-ready target --base ref --evidence file]
    epicPass{Epic review passes?}
    prReady[PR-ready review<br/>metareview review pr-ready --base ref --evidence file]
    prPass{PR review passes?}
    merge[Push, PR, merge]
    learn[Post-merge learning<br/>metareview learn --post-merge pr --base pre-merge-ref]

    intent --> artifact --> approved
    approved -- no --> revise --> artifact
    approved -- yes --> decompose --> child
    child --> childReview --> childApproved
    childApproved -- no --> childRevise --> childReview
    childApproved -- yes --> implement --> taskDone --> taskPass
    taskPass -- NEEDS_REVISION --> fix --> taskDone
    taskPass -- ESCALATED --> escalate
    taskPass -- PASS/PASS_ADVISORY --> moreChildren
    moreChildren -- yes --> child
    moreChildren -- no --> parentIntent
    parentIntent -- no --> parentRevise --> childReview
    parentIntent -- yes --> epicReady --> epicPass
    epicPass -- NEEDS_REVISION --> childReview
    epicPass -- ESCALATED --> escalate
    epicPass -- PASS/PASS_ADVISORY --> prReady --> prPass
    prPass -- NEEDS_REVISION --> fix --> prReady
    prPass -- ESCALATED --> escalate
    prPass -- PASS/PASS_ADVISORY --> merge --> learn
    escalate[Human narrows, splits, or redesigns target]

Loading

The decomposition loop is intentionally fractal: a parent plan can be decomposed into child epics, each child can be decomposed again, and each level gets reviewed before implementation continues. After the iteration converges, metareview checks back against the original parent intent so accumulated local fixes do not quietly drift away from the user request.

Every review produces Markdown artifacts under docs/metareview/ and local transient state under .metareview/. A blocking finding is current work. A NOT_REVIEWED artifact scaffold is also current work, not a pass. Artifact review runs the ten required lenses as parallel subagents by default; in-session-emulated fallback is weaker evidence and must say the review is not independently adversarial. Review logs classify findings into four sections — ## Blocking Findings (gate-closing defects), ## Advisory Findings (real, important, not defects), ## Follow-up Findings, and ## Warnings. Advisories pass a quality bar, not a count cap: each states its consequence, survives a steel-man of the author's counter-argument, and meets the convergence bar (reached independently by two or more lenses, or anchor 75 / a P1 consequence alone); the orchestrator then runs one staff-bar filter over the consolidated list before the log is written. Blocking and defect findings never pass through that filter, and style/deprecation nits stay suppressed at every gate.

Lifecycle gate results have a small operating contract:

• PASS: proceed.
• PASS_ADVISORY: proceed only when the review reports zero blocking findings.
• NEEDS_REVISION: fix blockers, then re-run the same gate with --previous-run <run-id>.
• ESCALATED: stop same-target retries; human must narrow, split, or redesign the target.

Exit handling: 0 means verify PASS/PASS_ADVISORY with zero blockers; 1 with a review path means follow that log; nonzero without a path means read stderr. For metareview fsm: 3 = the FSM needs the host to do a node's work; 1 + GATE_FAILED = run resume_hint (it forks a child — a new run id); 1 + ERR_* = read code (detail is data); 2 = nothing was recorded, fix the input and retry unless it is a consent or escalation code, which waits for a human; STOPPED/DONE are terminal. FSM escalation is per fork lineage: forking an ancestor or re-running init on the same base is a human decision.

How Humans Use It

Humans use metareview to make review timing explicit:

tmp_evidence="$(mktemp)"
metareview evidence run -- go test ./... > "$tmp_evidence"
metareview evidence run -- git diff --check >> "$tmp_evidence"

metareview review artifact docs/spec.md
metareview review task-done docs/tasks/task-001.md --base main --evidence "$tmp_evidence"
metareview review epic-ready docs/epics/epic-001.md --base main --evidence "$tmp_evidence"
metareview review pr-ready --base main --evidence "$tmp_evidence"
metareview learn --post-merge 42 --base pre-merge-sha

Use the smallest gate that matches the decision you are making. If you are deciding whether a plan is good enough, use artifact; the default command creates a NOT_REVIEWED scaffold and exits nonzero until the required reviewer rows and final verdict are completed. The reviewer set should return the actual artifact-review verdict it finds, not a fixed example result. Use --scaffold-only only for explicit scaffold generation. If you are deciding whether a task is done, use task-done. If you are deciding whether a branch is ready, use pr-ready.

How Coding Agents Use It

Coding agents should treat metareview as a completion gate, not an optional commentary tool:

• Before implementation, review the artifact that defines the work.
• After each local task-sized code change, run task-done with the exact base ref and evidence file.
• After child tasks complete, run epic-ready before landing the parent.
• Before push, PR creation, or merge, run pr-ready.
• After merge, run learn --post-merge so repository knowledge improves.

Agents must not say work is done while a blocking finding remains unresolved or while a gate is NEEDS_REVISION or ESCALATED. They should commit durable review/context artifacts when the repository's artifact policy says to do so, and keep transient .metareview/findings.jsonl and .metareview/runs.jsonl local.

When configuring .gitignore in ordinary project repositories, ignore those transient files with exact file entries. Do not ignore docs/metareview/ or the whole .metareview/ directory, because durable learning, calibration, and fallback knowledge can live there (FSM runs under .metareview/runs/ ignore themselves — nothing to add; metareview fsm init warns when .metareview/runs.jsonl is not ignored; docs/metareview/fsm/ export bundles are durable):

.metareview/findings.jsonl
.metareview/runs.jsonl

Core Commands

metareview setup --check
metareview setup --bootstrap-prereqs --dry-run
metareview evidence run -- <command> [args...]
metareview evidence import --github-checks <pr-number> [--repo <owner/repo>]
metareview review artifact <path>
metareview review task-done <task-id-or-path> --base <base-ref> --evidence <file>
metareview review epic-ready <epic-id-or-path> --base <base-ref> --evidence <file>
metareview review pr-ready --base <base-ref> --evidence <file>
metareview learn --post-merge <pr-number> --base <pre-merge-ref>
metareview status

# find-and-fix loop (audited state machine); driver contract: metareview fsm --agent-prompt
metareview fsm init --workflow sdlc-loop-proved --base <ref> --judge-model <model> --judge-effort medium
metareview fsm state
metareview fsm advance

# record an escalation rather than working around a blocker
metareview override request <finding-id> --reason "<why>"
metareview override grant   <finding-id> --reason "<why accepted>"

Philosophy

metareview follows a few practical rules:

1. Review early enough that the agent still has context.
2. Review against written intent, not vibes.
3. Separate advisory notes from blockers.
4. Preserve evidence in Markdown so humans can inspect it.
5. Keep transient state local and durable learning git-native.
6. Re-check original intent after iterative revisions so the work does not drift.
7. Prefer local, repo-aware review over remote black-box review when the codebase's tacit knowledge matters.

More Docs

• USAGE.md - task-oriented guide: review, find & fix bugs with proof, harden tests, pick a judge
• INSTALL.md - installation paths and troubleshooting
• CHANGELOG.md - release notes
• docs/quickstart.md - short operator guide
• docs/README.codex.md - Codex plugin usage
• docs/README.claude.md - Claude Code plugin usage
• docs/index.html - static GitHub Pages entrypoint

License

MIT. See LICENSE.