Review

Review is where the loop earns its name. Every candidate that finishes implementation gets an evaluation round by a configurable panel; findings synthesize into an auditable recommendation; and the decision drives one of three modeled edges — fix, re-spec, or accept. Review also selects tournament winners, drives the merge, and mines finished work for the learnings that start the next loop.

Panels and lenses

A review round is evaluated by a panel. The default panel is four reviewer agents, each with an explicit lens:

A design-system lens is available for projects with UI surface, and you can add human members — a specific person or a role. Panel composition is snapshotted when a round starts, so config edits never mutate reviews in flight.

Reviewer sessions run read-only — exact candidate-commit mounts, no write or shell access, one structured finding-submission tool — and each receives the North Star documents relevant to its lens plus the candidate’s spec and provenance, so findings are grounded in your project’s own doctrine rather than reviewer taste. Iteration n+1 receives all prior findings, so it verifies fixes instead of rediscovering them.

Findings and the recommendation

Findings carry severity (blocker, major, minor, info), a kind, code references with commit SHAs, and a suggested action. When the panel completes, duplicates are clustered and deterministic rules produce the recommendation:

1. Any open re-spec finding of major severity or above → re-spec.
2. Otherwise any open blocker, or a major fix from a blocking lens → fix.
3. Otherwise → accept, held until the change set’s checks are green.

Agents propose; rules decide; humans confirm per your checkpoint policy.

The three edges

• Fix issues a fix directive — a tracked document that reopens the named tasks (or creates new ones) and reports back when the work completes. REVIEW_FIX returns the candidate to Implement; round n+1 verifies.
• Re-spec escalates past a fix: the candidate’s spec reopens as a new revision with the findings attached as context. See Plan.
• Accept moves toward merge, through the review.signoff gate and then the epic.merge gate — the irreversibility point, which requires human approval by default.

Every decision routes through the same checkpoints whether it comes from the UI, the CLI, or the API.

GitHub, both directions

Findings with code references can post as pull-request review comments, and PR reviews written on GitHub flow back in as findings — “Request changes” on GitHub is honored as a major fix suggestion. Check runs project onto the review live, and accept is gated on green checks by default.

Tournament selection

When the last candidate of a tournament becomes selection-ready, a selection round starts with a comparison matrix per candidate: open and resolved findings by severity, fix cycles, checks state, score impact, spec fidelity, and cost. A selection reviewer produces a ranking with rationale; the decision is sign-off gated; the winner proceeds to merge and the losers are archived with structured learnings.

Merge

Review is the sole initiator of merges. A merge run verifies preflight (checks green, PRs mergeable and current, approvals present, gate satisfied), then merges the winning candidate’s branch-set in dependency order across every repository in scope. Cross-repo merges are ordered, not atomic — and the product says so honestly: a failure halts at position k with the reason recorded, and recovery is resume (continue from k) or a commanded rollback that opens revert PRs for the already-merged members.

Closing the loop

Merge completion records a completion learning and drafts seed intents from accumulated learnings and unresolved observations. Promote a seed and it becomes a real intent carrying its provenance; dismiss the ones that don’t warrant a loop. Resolution notices answer the signals that motivated the work. The loop begins again.

Working with review