Review Loop
Get independent multi-angle convergence on one written fix-design artifact BEFORE the change lands. Three scope angles (two SMART verdicts + one mechanical SCOUT) review the same artifact; the loop revises and re-dispatches autonomously under an anti-drift guard. Root receives the terminal outcome and continues already-authorized ready work under its existing gates; convergence itself adds no human approval step or execution authority.
This is the Codex-line binding of the provider-neutral review-loop methodology. The design trunk (shared/references/review-loop-methodology.md) is NOT installed; this skill carries the operative rules for the Codex runtime.
Workflow economy projection
Apply the binding shared Workflow economy (binding) rule: this loop starts only from its documented evidence trigger, never as default pre-implementation review. After a finding, re-dispatch only the exact open finding and its changed delta when coverage is accepted and prior unaffected results remain valid; start a full-artifact round for a human-requested full review, a new defect class, a material upstream revision, or unclear coverage.
Codex execution model (NOT the Claude background-Agent loop)
No verdict angle runs in the author/reviser session. Before dispatch, select and freeze one supported initial route per fresh lane under current user constraints, effective policy and observed host/tools. Ordinary native/host dispatch is supported when external execution is not required; explicit external-only selection remains external-only. No route switch after a failed launch. Preserve exact-runtime requirements and record missing actual metadata as unspecified by runtime, never as observed requested/resolved controls. For ordinary native lanes use the existing ordinary selector, sufficient profession/profile and exact discovered task tools; carry minimal approved context and the unchanged objective. Each reviewer returns its own verdict directly. External lanes use the approved thin wrapper and its strict V2 parser, full external-nonauthorizing tuple and untrusted/potentially-sensitive resultText contract, or declared owner-equivalent execution under the shared assistance contract. A launch or notification is not a verdict. Actual terminal results, independent receiving checks, canonical settlement and readback are required. Model difference alone proves neither scope independence nor commission family diversity.
- Claude external execution is allowed only through an explicitly user-selected approved API-key route, with its own fresh prompt and actual receipt; it is never a fallback after a failed launch. Kimi may be explicitly selected for the deep/wide angle as read-only and nonauthorizing; a failed Kimi lane remains UNVERIFIED and must be re-dispatched or reported as such.
The angles: two SMART verdicts + one mechanical SCOUT
Angles are defined by SCOPE, not by vendor. The FOCUS each is given makes it independent. Select each scope by task fit and supported initial route, not a hardwired transport or strongest model.
| Angle |
Scope |
Produces |
Codex-line default |
| Surgical correctness |
the specific defect, contract/seam violation, "this exact line/binding is wrong", visual-bug detection |
a VERDICT (PASS/REVISE) |
fresh nonauthoring native/host or approved external context |
| Deep reasoning |
blast-radius, cross-system ripple, large-context synthesis, ADR / framing / "is this the right shape" |
a VERDICT (PASS/REVISE) |
separately fresh nonauthoring native/host or approved external context; explicit Kimi is an optional nonauthorizing replacement only |
| Mechanical scout |
fully-specified scans: "does referenced X exist?", "list every reference to Y", sketch-vs-code, symbol/style |
FINDINGS (no verdict) |
strictly mechanical factual role; surfaces raw findings + blind-spot hints |
The scout does not co-judge: it executes spelled-out mechanical scans and surfaces raw facts that FEED the two verdict angles. A scout finding is an INPUT to a verdict, not a verdict. The scout maps to a FACTUAL, non-judging role, never a judging one.
Steps
- Admit the decision and initial route. Use review-loop for an explicit user loop/full-review request, materially competing owner/contract/seam solutions, unresolved coupling without one falsifying oracle, repeated review/fix failure or moving same-class manifestations, or newly evidenced complexity. Resolve missing factual premises first. A verified one-owner local cause, settled contract and one clear falsifying oracle may use the bounded exact-delta route when no mandatory trigger applies. Record the reason at the decision boundary; file count and
design-decision alone do not mandate a loop. Before dispatch, select and freeze one supported initial route per fresh lane under current user constraints, effective policy and observed host/tools. Ordinary native/host dispatch is supported when external execution is not required; explicit external-only selection remains external-only. No route switch after a failed launch. Preserve exact-runtime requirements and record missing actual metadata as unspecified by runtime, never as observed requested/resolved controls. Read effective .agents/.agents-mode.yaml without changing config. A provider setting configures an actually selected external route; it does not make native lanes external. Existing Kimi fixed kimi-code/k3, capability and no-fallback rules remain; Grok remains unavailable in 1.x.
- Confirm the verified premises (hard gate). Apply invariant 1 to verify the artifact's precise claims from current-session primary evidence before admission; secondhand roots remain pointers. Never pin a premise
CONFIRMED — do not re-litigate.
- Write the fix-design artifact under
.scratch/reviews/fix-design-YYYY-MM-DD-<topic>.md: verified premises with claim-appropriate primary evidence and file:line/trace citations, candidate options with cost/risk, recommended option, implementation sketch, validation plan, and what each scope angle should evaluate.
- Admit the frozen round. Prefer installed
review_loop_state.py from project-local .agents/skills/lead/scripts/, then $HOME/.agents/skills/lead/scripts/. Use begin with state below .scratch/reviews/<loop-id>/, file inputs for objective/scope/runtime-root/diff, and the artifact file or verified Git revision. Actual helper execution requires a valid event=ORCHESTRARIUM_REVIEW_LOOP_STATE_V2 receipt and readback. A helper defect permits declared owner-equivalent admission preserving the same state contract; record actual manual provenance, never a fabricated engine receipt. Unmet invariants or host denial stop the action.
- Dispatch only canonically admitted fresh attempts. Use exactly the committed round’s attempt IDs and
artifact_revision, carrying the ORIGINAL objective verbatim and the preselected route. Initial/full rounds admit all three lanes; exact-delta rounds admit affected lanes plus coverage. Record running state before launch through the helper or declared owner-equivalent transition. Run distinct nonauthoring verdict contexts concurrently only on compatible frozen inputs, otherwise sequentially. External prompts use files/stdin; must not request fast, priority, or ultrafast where the existing standard-speed route requires it. Persist results/failures only after route-appropriate terminal checks, canonical settlement/readback and matching round/attempt/revision. A retained lane has no fresh attempt and is never launched or copied. Delta selection changes no role authority, provenance requirement or retry policy.
- Converge autonomously through the state owner. Use the working helper commands below or declared owner-equivalent transitions with the same data guarantees and readback. No human gate per round. Reconcile failures with
admit-retry; finish a structurally clean round with complete-round. After a REVISE, revise the artifact, run the mandatory anti-drift check, classify the changed surface, and call next-round to freeze the new artifact before re-dispatch. The coverage choices are mutually exclusive: omit both flags, or pass --full-review, for backward-compatible full review; otherwise repeat --affected-lane {surgical,deep,scout} only for an accepted non-empty strict subset when every unaffected effective result from the immediately previous round remains valid. Retained verdict lanes must resolve to PASS, and a retained scout must be fully reconciled. Use full review when the human requests it, a new defect class appears, the upstream artifact changes materially, or classification is unclear. Close through close --outcome converged|drift|deadlock or a declared owner-equivalent closure with the same actual state guarantees and final readback. Mutating commands use fresh operation IDs and replay the same ID only for an idempotent retry. When DEVELOPING this pack, the thin scripts/validate-review-loop-state.py entry point checks the same schema owner; it does not create automatic continuous-integration enforcement.
- Receive the terminal outcome under existing authority. Receive the terminal outcome through Root: on convergence, present the accepted design and short round history, verify both verdicts, reconciled scout findings and canonical closure/readback, then continue the next already-authorized ready action under its existing gates. A design-only request ends at its accepted handoff; an actual human, scope, pause or publication gate holds only its dependent action. Drift or deadlock stops the affected loop and escalates its unresolved decision/cap; independent admitted ready work may continue. No human gate is added per round or merely because convergence occurred.
- Implement under existing authority. When Root receives the converged outcome and the next implementation action is already authorized with its required gates passed, the assigned implementer executes its accepted guarantees and invariants, preserving upstream claim identity and required safety corrections that discharge genuine vetoes. Optional reviewer HOW or telemetry suggestions remain advisory/nonblocking unless separately admitted into scope; run the validation plan and capture evidence before the root's verified local checkpoint. Read-only reviewer lanes gain no Source mutation authority.
Autonomous convergence + anti-drift
- Revise → anti-drift check → classify coverage → re-dispatch receipt-admitted angles, every round. Initial and full rounds admit all three; an eligible exact-delta correction round admits only its affected strict subset. Re-dispatching an unchanged artifact is forbidden (a verdict cannot change on identical input).
- Anti-drift (mandatory): the revised artifact must still serve the ORIGINAL pinned objective; a shift in goal, a widened scope, or a new unverified premise is drift → stop and escalate.
- Convergence = both VERDICT angles PASS AND every scout finding reconciled.
- Runaway guard: cap at N = 3 rounds; escalate early if the same blocker survives two rounds.
- Model-mismatch trigger: the cap catches a blocker that stays UNCHANGED; it is blind to a blocker that MOVES — each round the fix closes one manifestation and a new adjacent one appears (a "phase-graph chase"). That recurrence signals the MODEL is wrong, not that the last fix had a bug, and a correctness loop cannot name a model mismatch. When the same defect CLASS reappears at a new spot across ~3 rounds, STOP correctness rounds and dispatch a MODEL-review lane (design/architecture angles —
$architect / $architecture-reviewer, or the external-reviewer lane on the Codex line — asked "is the MECHANISM right, or is the chase a symptom of a model mismatch?" — fed the manifestation PHASE-GRAPH, not the latest diff, to name the right model or confirm the honest documented-residual floor). Resume correctness only after the model is confirmed or replaced. Per the review-the-model-not-just-the-spec precedent.
Hardening invariants (every round)
The runtime gate explicitly enforces hardening invariants 7-8 (failed-lane-is-unverified, fail-closed aggregation); neither silence nor a null lane result can converge.
- Verified premises are a hard gate, not a section. Before admitting the loop, directly acquire primary evidence THIS session sufficient for each decision-driving claim, and name its owner and falsifying probe. A report, plan or commit message is a pointer, never proof of its asserted root. Verify the underlying evidence and causal chain for the exact claim; rule out material alternatives. Current text or Source inspection proves only the inspected wording or logic, not an actual runtime cause, measured value or target outcome. Runtime and target-environment claims require the corresponding actual observation and functional receiving. For a reported runtime-performance symptom, the FIRST action remains live profiling of the actual reported scenario. Unmeasured runtime values and other unresolved driving premises remain ASSUMPTION (UNVERIFIED), advisory, and hold their dependent loop/design/fix until resolved. Never pin a premise
CONFIRMED — do not re-litigate.
- Every angle answers "premises proven for these exact claims?", "scope unchanged?", "verification adequate?" — not only its scope.
- Reject bare
PASS — cite specific blockers (file:line / evidence) or a specific no-blocker rationale.
- Per-round diff — what changed and why (which blocker it answers).
- Verify actual terminal results, not launch acknowledgements or sidecar notifications. Native lanes require terminal host output and independent receiving checks; actual wrapper runs require the strict V2 parser, full external-nonauthorizing tuple and untrusted/potentially-sensitive resultText contract. A defective wrapper permits only a declared owner-equivalent terminal/settlement path preserving those guarantees; no fake wrapper return.
- Escalate early on a stuck blocker.
- Failed lane is unverified. Any expected lane that errors, dies, or hits a time/token/usage limit is UNVERIFIED. Record the failed attempt, re-dispatch that lane, and never infer a clean result from silence. Before convergence, reconcile expected lanes against substantive outputs and recorded failures; every failure must name the successful re-dispatch that supersedes it.
- Fail-closed aggregation. A missing/null sub-verdict or findings payload is NOT-clean. An aggregation or gate remains
REVISE and exits non-zero until every expected lane has substantive output and every recorded failure is reconciled.
review-loop-state ledger (structural backstop)
For an admitted latest round whose fresh attempts were never dispatched, stop through the existing close --outcome drift|deadlock --round <N> --artifact-revision <revision> --reason <factual reason>. Confirm actual no-dispatch before submitting; the owner checks its exact admission and recorded history under the existing lock, not provider execution. Its typed unstarted close receipt preserves every round, attempt, retained result, snapshot and the round budget; it creates no verdict and closes no prior review obligation. Any recorded start, result, failure or retry excludes this route. Partial execution requires existing settlement; ordinary completed-round closure is unchanged. Legacy records remain readable without new fields; only a matching typed receipt proves the new stop action or its replay.
For metadata-only reconciliation of a completed scout result, use amend-scout-reconciliation --state <state> --operation-id <id> --round <current> --attempt-id <scout> --artifact-revision <revision> --metadata-file <json>. The request contains exactly version:1, scout_result_sha256 (lowercase SHA-256 of the entire original complete scout block under sorted-key compact JSON), required expected_head (explicit null initially, otherwise current operation ID), sorted complete links with finding_index/reconciliation_index into the immutable original arrays, and nonempty Root semantic comparison evidence inline or by accepted reference. Each genuine correction appends one immutable typed operation and advances scout_reconciliation_amendment.operation_id; superseded operations remain history and exact old replay never moves the head. Only the latest complete round's direct complete scout in a running loop is amendable. The same effective projection drives close and retained-origin validation. Original findings/dispositions, reviewed artifact, judgments, attempts, retries and caps do not change; this is no new review round or quality vote. Root verifies actual correspondence; evidence shape alone is not semantic proof. Existing frozen-artifact checks apply without a live-source or owner-selfhash requirement. The canonical write owner compares the prepared and committed serialized values before success; uncertainty preserves actual state for readback/replay. Older owners intentionally reject the optional round field; synchronize capable owner/readers before use. Actual helper execution alone emits the helper event. Declared manual-equivalent execution preserves the same logical transaction and uses ORCHESTRARIUM_REVIEW_LOOP_STATE_V2_OWNER_EQUIVALENT_MANUAL, execution_path=owner-equivalent-manual and truthful source evidence, never a fabricated helper receipt.
A shipped formal loop preserves the state owner’s existing schema and guarantees, normally through installed review_loop_state.py, or declared owner-equivalent execution under the shared assistance contract without a fabricated engine receipt. Schema V2 records pinned objective/scope/runtime-root, ordered idempotent operations, and per-round diff, phase, frozen artifact identity, fresh attempts, optional exact-delta coverage and retained references, failed-attempt history, results, and evidence. Full rounds have three current attempts. In a delta round, only affected lanes have attempts; each unaffected lane is a state-owned retained reference to the immediately previous round and revision, with no copied result. The committed receipt exposes attempts only for fresh lanes and exposes coverage for delta admission; retained-lane provenance remains in the committed state rather than a separate receipt field. For each admitted lane, failure history is one append-only immediate-successor chain (A → B → C) with one root and current tip: no branch, merge, cycle, cross-lane reuse, dangling/disconnected node, or historical unresolved failure; at most three retry edges are allowed. A retained lane cannot receive results, failures, or retries. The engine writes JSON below .scratch/reviews/, rejects path/link escapes and unknown fields, atomically replaces and reads back the state, and emits ORCHESTRARIUM_REVIEW_LOOP_STATE_V2 only after the committed record validates. Every attempt and failure echoes the owning round's artifact_revision; a mismatch or changed snapshot fails without counting a result. A retry keeps the round identity; a reviewed-artifact correction is admitted only as a new round with a newly frozen identity. Exact-delta admission does not change the global three-round cap. runtime_root/runtime-root and root_proven remain compatibility names for the verified-premise anchor/question; their names do not assert runtime measurement.
The helper is the preferred $review-loop state path under the shared assistance contract, not an executable host-enforced dispatch gate. It does not observe bypass, so manual-equivalent transitions preserve the state contract but never claim engine execution; unadmitted direct/ad-hoc launches remain outside its guarantees. The historical cross-pack observer gap is fixed; provider-specific observation does not expand this helper's guarantee. Personal/operator-owned reviews remain outside this state path. Mutations serialize through a stable lock file whose ownership is the operating system's exclusive kernel lock, not file presence. Graceful cancellation cleans owned uncommitted resources; hard process termination cannot run cleanup and is reconciled by the next lock-owning invocation. Invalid or uncertain committed state returns RLSTATE_RECOVERY_REQUIRED without deleting candidate evidence. V1 records remain readable by the development/CI validator with RLSTATE_V1_READ_ONLY; V1 mutation requires explicit migration with an authoritative revision for every round. The development validator remains repository-only and delegates to the same state owner rather than maintaining a second schema.
Rules
- This is a utility skill, not a new specialist role, and not a replacement for
$lead.
- The strategic/deep angle returns its verdict DIRECTLY; it is NOT the standalone external-mode
$consultant (which shells out to its own provider — the role-confusion). consultant stays untouched.
- The mechanical scout casts no verdict; map it to a factual role, never a QA-gate role.
- Do not silently downgrade an external angle to internal execution.
- Do NOT commit, push, or install from this skill. Return the accepted artifact to the root; verified local commit checkpoints remain the root's responsibility under shared governance. Human review remains required before push, release, or equivalent publication.
Non-goals
- Not a single advisory opinion (that is
$second-opinion / $consultant).
- Not disjoint parallel helper lanes that each own a different artifact (that is
$external-brigade).
- Not a post-implementation specialist review chain.
- Not for trivial one-line changes, and not for a root that is still an unmeasured runtime value.
Terms and Abbreviations
- angle: one independent review lens (surgical / deep / mechanical-scout) in the loop.
- scout: the mechanical angle — surfaces raw findings, casts no verdict, feeds the verdict angles.
- anti-drift: the per-round check that the revised artifact still serves the original pinned objective.
- convergence: both verdict angles PASS and all scout findings reconciled.
- ledger / review-loop-state: the per-round persisted record giving the autonomous loop an auditable structural backstop.
- ADR: Architecture Decision Record, a written record of a significant design decision and its rationale.
- CLI: Command-Line Interface, a terminal command surface such as
codex or claude.
- PASS / REVISE / BLOCKED: gate verdicts — accept, return for bounded correction, or stop on a real external blocker.
Verdict closure (binding form of decision 2026-07-16-review-verdict-closure)
- Every dispatched external angle on a TRACKED work-item follows the launch and terminal guarantees owned by
external-dispatch.md, through the working approved thin wrapper or declared owner-equivalent launch and settlement when defective. For actual wrapper execution, that owner supplies the strict V2 parser, full external-nonauthorizing
tuple, untrusted/potentially-sensitive resultText handling, and terminal-ledger protocol; an
angle cannot close a work-item directly; only the root owner may perform declared equivalent settlement under the shared assistance contract, preserving that protocol and actual readback.
- Loop-to-PASS is the gate, not a preference: a lane's
REVISE closes only when THAT lane (or a
recorded equivalent, structured fields) re-verifies PASS naming the exact closesRunIds. Author
belief, applied fixes, or a green mechanical validator never close it; check-work-items-state
FAILs on open obligations by default and the root publication gate blocks on them.
HOW→VERIFY independence: VERIFY(F) owner/engine ≠ HOW(F) author. Independence is a property of the HOW→VERIFY edge, not the WHAT→HOW edge: a reviewer may author a fix's HOW while context is fresh; only verification of the implemented fix must stay independent. For an inline-sufficient finding, no separate fix-design/HOW-review pass is required before implementation, but the existing loop-to-PASS re-verification remains mandatory. Author-exclusion for design-class (fix-class: design-decision) fixes: when the implemented fix of a design-decision finding followed a reviewer's authored HOW, at least one discharging verdict MUST come from an angle that did not author that HOW. A distinct scope counts as distinct even on the same engine (see ## The angles); this is stronger than the same-angle re-verification that suffices for inline-sufficient findings. No non-authoring verifier means no clean PASS: leave the HOW advisory and report the gap as UNVERIFIED.
- Review a FROZEN artifact, never the live working tree (2026-07-17, live incident). A verdict is a statement about one artifact revision, so the thing under review must not move while the round runs: dispatch at a committed revision, a
git diff patch file, or a copied snapshot, and give the reviewer its identity (sha or digest). An angle caught this gate's engine mid-edit — including a transient syntax error — and correctly refused the patch: "the moving live target prevents accepting that patch as the current implementation". If a finding forces an edit while a round is in flight, that edit makes a NEW snapshot and a NEW round; it never mutates what the current round is judging. Full lesson: work-items/lessons/2026-07-17-review-a-frozen-snapshot-not-a-live-tree.md.
- Ledger read-back before reporting a verdict (2026-07-17, live incident). On a tracked item, a lane's verdict may be reported or acted on ONLY after the selected route owner completes actual terminal acceptance and canonical settlement/readback. For an actual wrapper run,
external-dispatch.md requires its strict V2 parser, full external-nonauthorizing tuple, and untrusted/potentially-sensitive resultText handling, then the ledger is read back and confirms the terminal event for that launch runId. The terminal wrapper result can describe what the reviewer said, never prove that the obligation moved. This is the polling-anchor discipline applied to closure: anchor on the authoritative store, not on a self-derived signal. The incident that forced the rule: a validator defect rejected terminal events whose artifact was a repository file, the wrapper only WARNed, and TWO real PASS verdicts were reported to the operator from prose while the ledger held nothing (work-items/bugs/2026-07-17-validator-artifact-workitem-relative-only.md).
- Discharge current review obligations, not just the latest finding. Resolve each finding still relevant to the current accepted artifact through the required independent review. When an explicit ledger closer discharges multiple open events, name the exact targets under that operation's contract. Historical bookkeeping alone does not establish current relevance or create a verdict; preserve the recorded events.
- Typed dispositions only:
WAIVED:user with the user's authorization as manual-check evidence
(never against protected or unclassified findings); WAIVED:security-reviewer requires completed
status, exact target-bound manual-check evidence, and role or assignedRole equal to
security-reviewer.
1---2name: review-loop3description: "Review loop: run parallel reviews on a fix design."4metadata:5 source: https://skillmd.com/skills/applicate2628/review-loop6---78# Review Loop910Get independent multi-angle convergence on one written fix-design artifact BEFORE the change lands. Three scope angles (two SMART verdicts + one mechanical SCOUT) review the same artifact; the loop revises and re-dispatches autonomously under an anti-drift guard. Root receives the terminal outcome and continues already-authorized ready work under its existing gates; convergence itself adds no human approval step or execution authority.1112This is the Codex-line binding of the provider-neutral review-loop methodology. The design trunk (`shared/references/review-loop-methodology.md`) is NOT installed; this skill carries the operative rules for the Codex runtime.1314## Workflow economy projection1516Apply the binding shared **Workflow economy (binding)** rule: this loop starts only from its documented evidence trigger, never as default pre-implementation review. After a finding, re-dispatch only the exact open finding and its changed delta when coverage is accepted and prior unaffected results remain valid; start a full-artifact round for a human-requested full review, a new defect class, a material upstream revision, or unclear coverage.1718## Codex execution model (NOT the Claude background-Agent loop)1920No verdict angle runs in the author/reviser session. Before dispatch, select and freeze one supported initial route per fresh lane under current user constraints, effective policy and observed host/tools. Ordinary native/host dispatch is supported when external execution is not required; explicit external-only selection remains external-only. No route switch after a failed launch. Preserve exact-runtime requirements and record missing actual metadata as `unspecified by runtime`, never as observed requested/resolved controls. For ordinary native lanes use the existing ordinary selector, sufficient profession/profile and exact discovered task tools; carry minimal approved context and the unchanged objective. Each reviewer returns its own verdict directly. External lanes use the approved thin wrapper and its strict V2 parser, full external-nonauthorizing tuple and untrusted/potentially-sensitive resultText contract, or declared owner-equivalent execution under the shared assistance contract. A launch or notification is not a verdict. Actual terminal results, independent receiving checks, canonical settlement and readback are required. Model difference alone proves neither scope independence nor commission family diversity.2122- Claude external execution is allowed only through an explicitly user-selected approved API-key route, with its own fresh prompt and actual receipt; it is never a fallback after a failed launch. Kimi may be explicitly selected for the deep/wide angle as read-only and nonauthorizing; a failed Kimi lane remains UNVERIFIED and must be re-dispatched or reported as such.2324## The angles: two SMART verdicts + one mechanical SCOUT2526Angles are defined by **SCOPE, not by vendor**. The FOCUS each is given makes it independent. Select each scope by task fit and supported initial route, not a hardwired transport or strongest model.2728| Angle | Scope | Produces | Codex-line default |29| --- | --- | --- | --- |30| **Surgical correctness** | the specific defect, contract/seam violation, "this exact line/binding is wrong", visual-bug detection | a VERDICT (PASS/REVISE) | fresh nonauthoring native/host or approved external context |31| **Deep reasoning** | blast-radius, cross-system ripple, large-context synthesis, ADR / framing / "is this the right shape" | a VERDICT (PASS/REVISE) | separately fresh nonauthoring native/host or approved external context; explicit Kimi is an optional nonauthorizing replacement only |32| **Mechanical scout** | fully-specified scans: "does referenced X exist?", "list every reference to Y", sketch-vs-code, symbol/style | FINDINGS (no verdict) | strictly mechanical factual role; surfaces raw findings + blind-spot hints |3334The **scout does not co-judge**: it executes spelled-out mechanical scans and surfaces raw facts that FEED the two verdict angles. A scout finding is an INPUT to a verdict, not a verdict. The scout maps to a FACTUAL, non-judging role, never a judging one.3536## Steps37381. **Admit the decision and initial route.** Use review-loop for an explicit user loop/full-review request, materially competing owner/contract/seam solutions, unresolved coupling without one falsifying oracle, repeated review/fix failure or moving same-class manifestations, or newly evidenced complexity. Resolve missing factual premises first. A verified one-owner local cause, settled contract and one clear falsifying oracle may use the bounded exact-delta route when no mandatory trigger applies. Record the reason at the decision boundary; file count and `design-decision` alone do not mandate a loop. Before dispatch, select and freeze one supported initial route per fresh lane under current user constraints, effective policy and observed host/tools. Ordinary native/host dispatch is supported when external execution is not required; explicit external-only selection remains external-only. No route switch after a failed launch. Preserve exact-runtime requirements and record missing actual metadata as `unspecified by runtime`, never as observed requested/resolved controls. Read effective `.agents/.agents-mode.yaml` without changing config. A provider setting configures an actually selected external route; it does not make native lanes external. Existing Kimi fixed `kimi-code/k3`, capability and no-fallback rules remain; Grok remains unavailable in 1.x.392. **Confirm the verified premises (hard gate).** Apply invariant 1 to verify the artifact's precise claims from current-session primary evidence before admission; secondhand roots remain pointers. Never pin a premise `CONFIRMED — do not re-litigate`.403. **Write the fix-design artifact** under `.scratch/reviews/fix-design-YYYY-MM-DD-<topic>.md`: verified premises with claim-appropriate primary evidence and `file:line`/trace citations, candidate options with cost/risk, recommended option, implementation sketch, validation plan, and what each scope angle should evaluate.414. **Admit the frozen round.** Prefer installed `review_loop_state.py` from project-local `.agents/skills/lead/scripts/`, then `$HOME/.agents/skills/lead/scripts/`. Use `begin` with state below `.scratch/reviews/<loop-id>/`, file inputs for objective/scope/runtime-root/diff, and the artifact file or verified Git revision. Actual helper execution requires a valid `event=ORCHESTRARIUM_REVIEW_LOOP_STATE_V2` receipt and readback. A helper defect permits declared owner-equivalent admission preserving the same state contract; record actual manual provenance, never a fabricated engine receipt. Unmet invariants or host denial stop the action.425. **Dispatch only canonically admitted fresh attempts.** Use exactly the committed round’s attempt IDs and `artifact_revision`, carrying the ORIGINAL objective verbatim and the preselected route. Initial/full rounds admit all three lanes; exact-delta rounds admit affected lanes plus `coverage`. Record running state before launch through the helper or declared owner-equivalent transition. Run distinct nonauthoring verdict contexts concurrently only on compatible frozen inputs, otherwise sequentially. External prompts use files/stdin; must not request `fast`, `priority`, or `ultrafast` where the existing standard-speed route requires it. Persist results/failures only after route-appropriate terminal checks, canonical settlement/readback and matching round/attempt/revision. A retained lane has no fresh attempt and is never launched or copied. Delta selection changes no role authority, provenance requirement or retry policy.436. **Converge autonomously through the state owner.** Use the working helper commands below or declared owner-equivalent transitions with the same data guarantees and readback. No human gate per round. Reconcile failures with `admit-retry`; finish a structurally clean round with `complete-round`. After a `REVISE`, revise the artifact, run the mandatory anti-drift check, classify the changed surface, and call `next-round` to freeze the new artifact before re-dispatch. The coverage choices are mutually exclusive: omit both flags, or pass `--full-review`, for backward-compatible full review; otherwise repeat `--affected-lane {surgical,deep,scout}` only for an accepted non-empty strict subset when every unaffected effective result from the immediately previous round remains valid. Retained verdict lanes must resolve to `PASS`, and a retained scout must be fully reconciled. Use full review when the human requests it, a new defect class appears, the upstream artifact changes materially, or classification is unclear. Close through `close --outcome converged|drift|deadlock` or a declared owner-equivalent closure with the same actual state guarantees and final readback. Mutating commands use fresh operation IDs and replay the same ID only for an idempotent retry. When DEVELOPING this pack, the thin `scripts/validate-review-loop-state.py` entry point checks the same schema owner; it does not create automatic continuous-integration enforcement.447. **Receive the terminal outcome under existing authority.** Receive the terminal outcome through Root: on convergence, present the accepted design and short round history, verify both verdicts, reconciled scout findings and canonical closure/readback, then continue the next already-authorized ready action under its existing gates. A design-only request ends at its accepted handoff; an actual human, scope, pause or publication gate holds only its dependent action. Drift or deadlock stops the affected loop and escalates its unresolved decision/cap; independent admitted ready work may continue. No human gate is added per round or merely because convergence occurred.458. **Implement under existing authority.** When Root receives the converged outcome and the next implementation action is already authorized with its required gates passed, the assigned implementer executes its accepted guarantees and invariants, preserving upstream claim identity and required safety corrections that discharge genuine vetoes. Optional reviewer HOW or telemetry suggestions remain advisory/nonblocking unless separately admitted into scope; run the validation plan and capture evidence before the root's verified local checkpoint. Read-only reviewer lanes gain no Source mutation authority.4647## Autonomous convergence + anti-drift4849- **Revise → anti-drift check → classify coverage → re-dispatch receipt-admitted angles**, every round. Initial and full rounds admit all three; an eligible exact-delta correction round admits only its affected strict subset. Re-dispatching an unchanged artifact is forbidden (a verdict cannot change on identical input).50- **Anti-drift (mandatory):** the revised artifact must still serve the ORIGINAL pinned objective; a shift in goal, a widened scope, or a new unverified premise is drift → stop and escalate.51- **Convergence** = both VERDICT angles PASS AND every scout finding reconciled.52- **Runaway guard:** cap at **N = 3** rounds; escalate early if the same blocker survives two rounds.53- **Model-mismatch trigger:** the cap catches a blocker that stays UNCHANGED; it is blind to a blocker that MOVES — each round the fix closes one manifestation and a new adjacent one appears (a "phase-graph chase"). That recurrence signals the MODEL is wrong, not that the last fix had a bug, and a correctness loop cannot name a model mismatch. When the same defect CLASS reappears at a new spot across ~3 rounds, STOP correctness rounds and dispatch a MODEL-review lane (design/architecture angles — `$architect` / `$architecture-reviewer`, or the external-reviewer lane on the Codex line — asked "is the MECHANISM right, or is the chase a symptom of a model mismatch?" — fed the manifestation PHASE-GRAPH, not the latest diff, to name the right model or confirm the honest documented-residual floor). Resume correctness only after the model is confirmed or replaced. Per the `review-the-model-not-just-the-spec` precedent.5455## Hardening invariants (every round)5657The runtime gate explicitly enforces hardening invariants 7-8 (failed-lane-is-unverified, fail-closed aggregation); neither silence nor a null lane result can converge.58591. **Verified premises are a hard gate, not a section.** Before admitting the loop, directly acquire primary evidence THIS session sufficient for each decision-driving claim, and name its owner and falsifying probe. A report, plan or commit message is a pointer, never proof of its asserted root. Verify the underlying evidence and causal chain for the exact claim; rule out material alternatives. Current text or Source inspection proves only the inspected wording or logic, not an actual runtime cause, measured value or target outcome. Runtime and target-environment claims require the corresponding actual observation and functional receiving. For a reported runtime-performance symptom, the FIRST action remains live profiling of the actual reported scenario. Unmeasured runtime values and other unresolved driving premises remain ASSUMPTION (UNVERIFIED), advisory, and hold their dependent loop/design/fix until resolved. Never pin a premise `CONFIRMED — do not re-litigate`.602. Every angle answers "premises proven for these exact claims?", "scope unchanged?", "verification adequate?" — not only its scope.613. Reject bare `PASS` — cite specific blockers (`file:line` / evidence) or a specific no-blocker rationale.624. Per-round diff — what changed and why (which blocker it answers).635. Verify actual terminal results, not launch acknowledgements or sidecar notifications. Native lanes require terminal host output and independent receiving checks; actual wrapper runs require the strict V2 parser, full external-nonauthorizing tuple and untrusted/potentially-sensitive resultText contract. A defective wrapper permits only a declared owner-equivalent terminal/settlement path preserving those guarantees; no fake wrapper return.646. Escalate early on a stuck blocker.657. **Failed lane is unverified.** Any expected lane that errors, dies, or hits a time/token/usage limit is UNVERIFIED. Record the failed attempt, re-dispatch that lane, and never infer a clean result from silence. Before convergence, reconcile expected lanes against substantive outputs and recorded failures; every failure must name the successful re-dispatch that supersedes it.668. **Fail-closed aggregation.** A missing/null sub-verdict or findings payload is NOT-clean. An aggregation or gate remains `REVISE` and exits non-zero until every expected lane has substantive output and every recorded failure is reconciled.6768## review-loop-state ledger (structural backstop)6970For an admitted latest round whose fresh attempts were never dispatched, stop through the existing `close --outcome drift|deadlock --round <N> --artifact-revision <revision> --reason <factual reason>`. Confirm actual no-dispatch before submitting; the owner checks its exact admission and recorded history under the existing lock, not provider execution. Its typed `unstarted` close receipt preserves every round, attempt, retained result, snapshot and the round budget; it creates no verdict and closes no prior review obligation. Any recorded start, result, failure or retry excludes this route. Partial execution requires existing settlement; ordinary completed-round closure is unchanged. Legacy records remain readable without new fields; only a matching typed receipt proves the new stop action or its replay.7172For metadata-only reconciliation of a completed scout result, use `amend-scout-reconciliation --state <state> --operation-id <id> --round <current> --attempt-id <scout> --artifact-revision <revision> --metadata-file <json>`. The request contains exactly `version:1`, `scout_result_sha256` (lowercase SHA-256 of the entire original complete scout block under sorted-key compact JSON), required `expected_head` (explicit null initially, otherwise current operation ID), sorted complete `links` with `finding_index`/`reconciliation_index` into the immutable original arrays, and nonempty Root semantic comparison evidence inline or by accepted reference. Each genuine correction appends one immutable typed operation and advances `scout_reconciliation_amendment.operation_id`; superseded operations remain history and exact old replay never moves the head. Only the latest complete round's direct complete scout in a running loop is amendable. The same effective projection drives close and retained-origin validation. Original findings/dispositions, reviewed artifact, judgments, attempts, retries and caps do not change; this is no new review round or quality vote. Root verifies actual correspondence; evidence shape alone is not semantic proof. Existing frozen-artifact checks apply without a live-source or owner-selfhash requirement. The canonical write owner compares the prepared and committed serialized values before success; uncertainty preserves actual state for readback/replay. Older owners intentionally reject the optional round field; synchronize capable owner/readers before use. Actual helper execution alone emits the helper event. Declared manual-equivalent execution preserves the same logical transaction and uses `ORCHESTRARIUM_REVIEW_LOOP_STATE_V2_OWNER_EQUIVALENT_MANUAL`, `execution_path=owner-equivalent-manual` and truthful source evidence, never a fabricated helper receipt.7374A shipped formal loop preserves the state owner’s existing schema and guarantees, normally through installed `review_loop_state.py`, or declared owner-equivalent execution under the shared assistance contract without a fabricated engine receipt. Schema V2 records pinned objective/scope/runtime-root, ordered idempotent operations, and per-round diff, phase, frozen artifact identity, fresh attempts, optional exact-delta coverage and retained references, failed-attempt history, results, and evidence. Full rounds have three current attempts. In a delta round, only affected lanes have attempts; each unaffected lane is a state-owned retained reference to the immediately previous round and revision, with no copied result. The committed receipt exposes `attempts` only for fresh lanes and exposes `coverage` for delta admission; retained-lane provenance remains in the committed state rather than a separate receipt field. For each admitted lane, failure history is one append-only immediate-successor chain (`A → B → C`) with one root and current tip: no branch, merge, cycle, cross-lane reuse, dangling/disconnected node, or historical unresolved failure; at most three retry edges are allowed. A retained lane cannot receive results, failures, or retries. The engine writes JSON below `.scratch/reviews/`, rejects path/link escapes and unknown fields, atomically replaces and reads back the state, and emits `ORCHESTRARIUM_REVIEW_LOOP_STATE_V2` only after the committed record validates. Every attempt and failure echoes the owning round's `artifact_revision`; a mismatch or changed snapshot fails without counting a result. A retry keeps the round identity; a reviewed-artifact correction is admitted only as a new round with a newly frozen identity. Exact-delta admission does not change the global three-round cap. `runtime_root`/`runtime-root` and `root_proven` remain compatibility names for the verified-premise anchor/question; their names do not assert runtime measurement.7576The helper is the preferred `$review-loop` state path under the shared assistance contract, not an executable host-enforced dispatch gate. It does not observe bypass, so manual-equivalent transitions preserve the state contract but never claim engine execution; unadmitted direct/ad-hoc launches remain outside its guarantees. The historical cross-pack observer gap is fixed; provider-specific observation does not expand this helper's guarantee. Personal/operator-owned reviews remain outside this state path. Mutations serialize through a stable lock file whose ownership is the operating system's exclusive kernel lock, not file presence. Graceful cancellation cleans owned uncommitted resources; hard process termination cannot run cleanup and is reconciled by the next lock-owning invocation. Invalid or uncertain committed state returns `RLSTATE_RECOVERY_REQUIRED` without deleting candidate evidence. V1 records remain readable by the development/CI validator with `RLSTATE_V1_READ_ONLY`; V1 mutation requires explicit migration with an authoritative revision for every round. The development validator remains repository-only and delegates to the same state owner rather than maintaining a second schema.7778## Rules7980- This is a utility skill, not a new specialist role, and not a replacement for `$lead`.81- The strategic/deep angle returns its verdict DIRECTLY; it is NOT the standalone external-mode `$consultant` (which shells out to its own provider — the role-confusion). `consultant` stays untouched.82- The mechanical scout casts no verdict; map it to a factual role, never a QA-gate role.83- Do not silently downgrade an external angle to internal execution.84- Do NOT commit, push, or install from this skill. Return the accepted artifact to the root; verified local commit checkpoints remain the root's responsibility under shared governance. Human review remains required before push, release, or equivalent publication.8586## Non-goals8788- Not a single advisory opinion (that is `$second-opinion` / `$consultant`).89- Not disjoint parallel helper lanes that each own a different artifact (that is `$external-brigade`).90- Not a post-implementation specialist review chain.91- Not for trivial one-line changes, and not for a root that is still an unmeasured runtime value.9293## Terms and Abbreviations9495- **angle**: one independent review lens (surgical / deep / mechanical-scout) in the loop.96- **scout**: the mechanical angle — surfaces raw findings, casts no verdict, feeds the verdict angles.97- **anti-drift**: the per-round check that the revised artifact still serves the original pinned objective.98- **convergence**: both verdict angles PASS and all scout findings reconciled.99- **ledger / review-loop-state**: the per-round persisted record giving the autonomous loop an auditable structural backstop.100- **ADR**: Architecture Decision Record, a written record of a significant design decision and its rationale.101- **CLI**: Command-Line Interface, a terminal command surface such as `codex` or `claude`.102- **PASS / REVISE / BLOCKED**: gate verdicts — accept, return for bounded correction, or stop on a real external blocker.103104## Verdict closure (binding form of decision 2026-07-16-review-verdict-closure)105106- Every dispatched external angle on a TRACKED work-item follows the launch and terminal guarantees owned by107 `external-dispatch.md`, through the working approved thin wrapper or declared owner-equivalent launch and settlement when defective. For actual wrapper execution, that owner supplies the strict V2 parser, full external-nonauthorizing108 tuple, untrusted/potentially-sensitive resultText handling, and terminal-ledger protocol; an109 angle cannot close a work-item directly; only the root owner may perform declared equivalent settlement under the shared assistance contract, preserving that protocol and actual readback.110- **Loop-to-PASS is the gate, not a preference:** a lane's `REVISE` closes only when THAT lane (or a111 recorded equivalent, structured fields) re-verifies `PASS` naming the exact `closesRunIds`. Author112 belief, applied fixes, or a green mechanical validator never close it; `check-work-items-state`113 FAILs on open obligations by default and the root publication gate blocks on them.114- **`HOW→VERIFY independence: VERIFY(F) owner/engine ≠ HOW(F) author`.** Independence is a property of the HOW→VERIFY edge, not the WHAT→HOW edge: a reviewer may author a fix's HOW while context is fresh; only verification of the implemented fix must stay independent. For an `inline-sufficient` finding, no separate fix-design/HOW-review pass is required before implementation, but the existing loop-to-PASS re-verification remains mandatory. **Author-exclusion for design-class (`fix-class: design-decision`) fixes:** when the implemented fix of a `design-decision` finding followed a reviewer's authored HOW, at least one discharging verdict MUST come from an angle that did not author that HOW. A distinct scope counts as distinct even on the same engine (see `## The angles`); this is stronger than the same-angle re-verification that suffices for `inline-sufficient` findings. No non-authoring verifier means no clean `PASS`: leave the HOW advisory and report the gap as `UNVERIFIED`.115- **Review a FROZEN artifact, never the live working tree (2026-07-17, live incident).** A verdict is a statement about one artifact revision, so the thing under review must not move while the round runs: dispatch at a committed revision, a `git diff` patch file, or a copied snapshot, and give the reviewer its identity (sha or digest). An angle caught this gate's engine mid-edit — including a transient syntax error — and correctly refused the patch: "the moving live target prevents accepting that patch as the current implementation". If a finding forces an edit while a round is in flight, that edit makes a NEW snapshot and a NEW round; it never mutates what the current round is judging. Full lesson: `work-items/lessons/2026-07-17-review-a-frozen-snapshot-not-a-live-tree.md`.116- **Ledger read-back before reporting a verdict (2026-07-17, live incident).** On a tracked item, a lane's verdict may be reported or acted on ONLY after the selected route owner completes actual terminal acceptance and canonical settlement/readback. For an actual wrapper run, `external-dispatch.md` requires its strict V2 parser, full external-nonauthorizing tuple, and untrusted/potentially-sensitive resultText handling, then the ledger is read back and confirms the terminal event for that launch `runId`. The terminal wrapper result can describe what the reviewer said, never prove that the obligation moved. This is the polling-anchor discipline applied to closure: anchor on the authoritative store, not on a self-derived signal. The incident that forced the rule: a validator defect rejected terminal events whose artifact was a repository file, the wrapper only WARNed, and TWO real `PASS` verdicts were reported to the operator from prose while the ledger held nothing (`work-items/bugs/2026-07-17-validator-artifact-workitem-relative-only.md`).117- **Discharge current review obligations, not just the latest finding.** Resolve each finding still relevant to the current accepted artifact through the required independent review. When an explicit ledger closer discharges multiple open events, name the exact targets under that operation's contract. Historical bookkeeping alone does not establish current relevance or create a verdict; preserve the recorded events.118- Typed dispositions only: `WAIVED:user` with the user's authorization as manual-check evidence119 (never against protected or unclassified findings); `WAIVED:security-reviewer` requires completed120 status, exact target-bound manual-check evidence, and `role` or `assignedRole` equal to121 `security-reviewer`.