# Checkpoint Review Chain Contract Canonical owner for gate-review **execution shape** rules shared by the two dev-loop gate boundaries: `draft_gate` and `pre_approval_gate`. ## Purpose Both gates share one structured sub-loop: a build-once neutral context bundle, independent-reviewer fan-out, fan-in synthesis, and iterative fix-then-retry. ### Execution model: build once, seed many (no fork) `GATE-EXEC-BUILD-ONCE-SEED`: Each gate pass MUST build ONE neutral context bundle once via a deterministic context-builder script and seed every independent, fresh-context reviewer with that bundle verbatim. Reviewers MUST NOT fork from, or inherit, a parent agent's loaded context, and the sub-loop MUST NOT depend on any fork primitive or the Workflow tool. Concretely: 1. A deterministic **context-builder script** (`scripts/github/write-gate-context.mjs`) builds ONE generous, neutral context bundle for the head SHA: the full diff plus a structurally-adjacent code bundle (each changed file's 1-hop import in/out-edges) with size guards. Because it is a script, the bundle is neutral (it cannot editorialize) and deterministic (identical head + diff → identical bundle). 2. Each reviewer is an **independent fresh-context Agent** that is **seeded with that identical neutral bundle verbatim** plus its single review angle (per-angle mode / `gate:full`) or every angle in its resolved dispatch unit (grouped mode, [Phase 2](#phase-2--fan-out-independent-reviewers-seeded-with-the-neutral-bundle)), and widens only when a covered angle genuinely needs more. Reviewers never inherit the main (orchestrating) agent's conversation or opinions — that independence is the anti-bias requirement. 3. Fan-in consolidates the per-angle findings unchanged. The cost win is **work-dedup**: the diff + adjacent code is built once, not re-derived by every reviewer; a shared-prefix prompt-cache is an opportunistic bonus, not a requirement. The exact LAYOUT of the seeded briefing text (what precedes what, and what must be byte-identical across reviewers to make prompt-cache reuse possible at all) is owned by `GATE-EXEC-BRIEFING-PREFIX` in [Phase 2](#phase-2--fan-out-independent-reviewers-seeded-with-the-neutral-bundle) below. This contract owns the **execution shape** of gate-review work. It does not own: - which review angles a specific gate runs (that stays in the skill) - the visible gate-review PR comment format (owned by [Gate Review Comment Contract](./gate-review-comment-contract.md), whose evidence is also required for a gate to be satisfied) - the broader PR lifecycle sequencing (owned by the workflow skill and [PR Lifecycle Contract](./pr-lifecycle-contract.md)) A THIRD gate, `review` (`GATE_NAMES`, `scripts/github/_gate-names.mjs`), reuses this execution shape (Phase 1 context-builder, Phase 1.5 primer, Phase 2 fan-out, Phase 3 fan-in + verdict-post) with `--gate review`, but stops after Phase 3 — it never reaches Phase 3.5 (judge), Phase 4 (fix), or Phase 5 (repeat), and carries no gate obligation of its own (reachable on any PR, no auto-resolve, no forbidden-action refusal, no CI wait). It is a deliberately NON-EVIDENCE gate: `review` IS a recognized gate name in the gate-comment header vocabulary a comment is parsed against (`@dev-loops/core/github/copilot-helpers`) — recognized, not absent — and that recognition is exactly what makes the parser return non-evidence immediately for a `review`-headed comment, before it can ever fall through to the lenient whole-body token scan a genuinely unidentifiable comment relies on, regardless of whether the comment carries the `--findings-ledger` gate-findings-review marker. (It is separately, and unrelatedly, absent from `GATE_CONFIG_KEY` in `@dev-loops/core/loop/gate-fanin` — it has no `draft`/`preApproval`-style config threshold — but that absence is not what keeps a `review` verdict from satisfying `draft_gate` or `pre_approval_gate` evidence.) See the [Review skill](../review/SKILL.md). ## Separate chains per gate `GATE-EXEC-SEPARATE-CHAINS`: Each gate (`draft_gate`, `pre_approval_gate`) MUST run its own independent review chain with its own review angles, its own disposition ledger, its own fix cycle, and its own exit conditions. The chains are not interchangeable; each gate's execution is a complete, self-contained sub-loop pass. The `draft_gate` fix cycle covers only findings that block the draft→ready transition; the `pre_approval_gate` fix cycle covers only findings that block final approval readiness. Angles and blocking severities per gate are in [Gate-specific configuration](#gate-specific-configuration). ## Sub-loop phases Both gates run the identical phases with their own review angles. ### Phase 1 — Preamble: context-builder Before fanning out reviewers, run a preamble pass that produces review handoff context in the PR's actual worktree/head — the same checkout the reviewers will run in — so the gitignored, worktree-local `tmp/gate-context` bundle it writes is present for them: - the context-builder runs in fresh context and emits a NEUTRAL artifact; that artifact (never the parent session's chat history or state) is what each downstream reviewer subagent is later seeded with. **Mandatory:** every gate-review subagent must run `scripts/github/verify-fresh-review-context.mjs --scope - --context-path --prefix-hash ` (or `--prefix-file `) at startup and refuse to proceed on contamination or a missing gate-context artifact. Use a gate-prefixed `--scope -` (e.g. `draft-gate-coverage`) so each reviewer writes its own sentinel and attributes to its gate (see [Sentinel lifecycle](#sentinel-lifecycle)), `--context-path` to the artifact this phase writes below, and `--prefix-hash`/`--prefix-file` to record the invariant-briefing prefix hash enforced by `GATE-EXEC-BRIEFING-PREFIX`. - **Worktree isolation is PROHIBITED for per-angle gate reviewers.** They are read-only (they never mutate files), so filesystem isolation buys nothing and actively breaks the "build once, seed many" contract: a fresh worktree is checked out from `main`, not the PR head, and has no access to the gitignored, worktree-local `tmp/gate-context` bundle this phase writes (#1135). Reviewers run in the PR's actual worktree/head — the same checkout the preamble ran in. - the preamble resolves the gate's review angle set: it starts from the configured angle pool (`gates..angles` — an array of angle names/objects, D3/D4) and, when `gates..dynamic.subtractive` is enabled (ON by default since #1579), narrows it to the angles relevant to the change at hand (configured pool → resolved set). Optional code-review lenses not triggered by the change (for example most code lenses for a docs-only change) are dropped, and the reason each angle was dropped is recorded as rationale. Angle entries with `mandatory: true` form a floor and are always included after dynamic selection (filtered only by entries with `enabled: false`); they are never dropped — a mandatory angle runs even when the diff-classifier would otherwise prune it. Adding a plain (non-mandatory) angle entry is additive but not mandatory — a duplicate name is deduplicated by the set union (appears exactly once, never errors, and keeps that angle's existing mandatory/prunable status); an entry with `enabled: false` is removed like any other angle. Because `gates..angles` merges BY NAME across config layers (D3), a consumer can add a new angle, or disable/override an existing one, by naming just that entry — no need to copy-paste/maintain the whole shipped `angles` array. When `dynamic.subtractive` is off (the opt-out escape hatch, or when no diff is available), the configured static pool is used unchanged — set `dynamic.subtractive: false` (full pool) AND apply the `gate:full` label or `gates.fanout.mode: per-angle` to restore the original full static fan-out. The `gate:full` label forces the full (untriered) angle set; as of #1601 (ADR 0048) it no longer forces per-angle DISPATCH — it dispatches grouped, so to also restore one-reviewer-per-angle dispatch shape set `gates.fanout.mode: per-angle`. Symmetrically, when `gates..dynamic.additive` is enabled (default **off**), the resolver may also ADD catalog angles that change-category heuristics recommend but that are not already in the gate's configured pool, drawn from the global lens catalog (the explicit `gates.anglePool` override, or — when `anglePool` is not set or is empty — the union of the built-in persona registry's angle names and every angle actually configured across this config's own `gates.draft`/`gates.preApproval`/`gates.spike` `angles`). A disabled (`enabled: false`) entry remains a hard ceiling on additions — an excluded angle is never added, even if the change categories would otherwise recommend it. Additions are recorded in the rationale with action `"added"`, with a reason naming either the triggering change category or, for always-include lenses, that it is an always-include addition. This additive path is off by default, so existing configured angle pools are unaffected unless a gate explicitly opts in. - **Security-sensitive-seam trigger (`threat-model`).** When the change categories include `SECURITY_SENSITIVE_SEAM` — a **code** file's diff (config/doc/markdown lines that merely name a primitive are file-gated out) touches browser automation, `child_process`/shell execution, untrusted network fetch, or destructive filesystem / local-file-upload ops — the resolver selects the `threat-model` angle (recommended when configured; added from the pool in additive mode). It is never dropped for such a diff, regardless of change size. `threat-model` is an adversarial-security lens that returns an exhaustive trust-boundary checklist (input allowlists, navigation/origin confinement pre-launch **and** at runtime, resource/loop bounds, data-at-rest + cleanup on every fail-closed path, exported/entry-point self-validation, error/teardown safety, path-traversal/deserialization, shell-injection) rather than a spot-check — so a batched up-front pass surfaces the trust-boundary holes that would otherwise be drip-fed serially through Copilot rounds. `input-validation` is likewise part of the core `LOGIC_CHANGE` subset, not pool-only. - the preamble produces one or more review handoff artifacts (branch, head SHA, PR/issue scope, acceptance criteria, touched files, validation posture). The resolved angle set and its rationale are written as a deterministic handoff artifact under `tmp/gate-context//pr-/-.json` so the fan-out phase consumes a stable, auditable briefing per head SHA. - the preamble ALSO builds the deterministic **neutral context bundle** ONCE: the full diff (`scope.diffPath`) plus an adjacent-code bundle (`adjacentCode`) containing each changed file and its 1-hop import in/out-edges (callers/callees/imports), with size guards (skip lockfiles/generated/binary/minified; cap per-file bytes; truncate the long tail) recorded in a `stripped`/`truncated`/`missing` manifest for observability. This is the build-once, work-deduped seed handed verbatim to every reviewer; no reviewer re-derives the diff + adjacent code from scratch. - **`scope.diffSource` posture (CLI `--base`).** `write-gate-context.mjs` records this full bundle only when it has a resolvable diff source. Pass `--base ` and the CLI captures the diff itself (`git diff ...HEAD`, run with color/pager/external-diff config isolated so the persisted bytes are environment-independent) and stamps `scope.diffSource: "base"` — the full build-once bundle (`scope.diffPath` + `scope.changedFiles` + `adjacentCode`). Without `--base`, the CLI does NOT silently emit a full-looking bundle: it warns and stamps `scope.diffSource: "none"` — an explicit **thin briefing** (`scope.diffPath: null`, `scope.changedFiles: []`, no `adjacentCode`) that reviewers detect and fall back from (re-derive via `git diff`). A `--base` that fails to resolve (its `git diff --name-status` fails) fails closed (non-zero exit, no artifact) rather than degrading to a thin briefing. Programmatic `buildGateContext({ diff })` callers are unaffected and omit `scope.diffSource` entirely. - **Partial `"base"` (best-effort full-diff).** `scope.diffSource: "base"` can co-occur with `scope.diffPath: null`: the required `git diff --name-status` succeeded (so `scope.changedFiles` + `adjacentCode` are present — it IS a base-derived bundle) but the best-effort FULL-diff capture degraded (e.g. output exceeded the buffer, a render error), so no persisted `.diff` was written. Reviewers MUST therefore key their diff-fallback on `scope.diffPath` (null → re-derive via `git diff`), NOT on `scope.diffSource`: `diffSource` distinguishes a base-derived bundle (`"base"`) from a thin briefing (`"none"`), while `diffPath` independently signals whether the persisted full diff is available. - **`scope.acceptanceCriteriaSource` posture (CLI-only spec resolution, #1496/#1511).** `write-gate-context.mjs` resolves the PR body, the PR's closing issue reference(s), and each closed issue's body from GitHub itself when the caller omits `--pr-body`/ `--issue-body`/`--acceptance-criteria` — a caller that simply forgets a flag can no longer seed every fan-out reviewer with the false claim that a PR has no description or no acceptance criteria. An unresolvable read (PR or a linked issue) FAILS CLOSED: a named error, no artifact written — the bundle must never assert absence when resolution merely failed. Supplying `--acceptance-criteria` suppresses the automatic issue-body fetch entirely (it overrides the pointer the fetch would otherwise resolve), so a caller who passes only `--acceptance-criteria` gets no linked-issue body and no `## Linked issue` section; pass `--issue-body` too if the prefix should still carry issue text. `scope.acceptanceCriteriaSource` records how `scope.acceptanceCriteria` came to be: `"provided"` (caller flag, regardless of whether an issue body was independently supplied too), `"linked-issue"` (resolved from the closing reference(s), and at least one resolved issue carries the full refinement matrix — Acceptance criteria checklist + DoD checklist + explicit Non-goals, or a linked refinement doc), `"linked-issue-unrefined"` (resolved, but no linked issue carries the full refinement matrix — distinguishes "linked, unrefined or matrix-incomplete" from "not fetched"), or `"none"` (the PR closes no issue). The field is CLI-only: programmatic `buildGateContext`/`writeGateContext` callers omit it entirely, so a null `acceptanceCriteria` WITHOUT this field means "never resolved" and one WITH it means "genuinely absent" or "genuinely unrefined". An umbrella PR closing several issues resolves ALL of them (not just the first), concatenated under one `## Linked issue , ` section with a `### ` sub-heading per issue; a cross-repo closing reference registered by GitHub (`closingIssuesReferences`, which carries the repository alongside the number) resolves against ITS OWN repository, not the PR's — the `Closes #N` body-keyword fallback used when GitHub reports no closing references is same-repo only and cannot capture an `owner/repo` prefix. `--prefix-file` (an orchestrator recording its own already-rendered prefix) skips this resolution entirely — those fields could never reach the recorded bytes. Because the resolved PR/issue text is embedded in the rendered prefix, a same-head rebuild after a live description edit yields different prefix bytes, which would split one fan-out across two prefix hashes — so a conductor MUST NOT rebuild the context while reviewers for that head are still running. This is now ENFORCED, not merely stated in prose (#1537): `write-gate-context.mjs` REFUSES (throws, exit 1, no bytes written) a same-head rebuild that would change the recorded prefix bytes while this gate's reviewer sentinels for that head are still live (a fan-out is in flight). The refusal names the in-flight head and points at the reviewers already briefed on the prior bytes (their sentinel files + recorded prefix hash). A sentinel scan that fails for any reason other than a missing tmp/ dir (EACCES, ENOTDIR, ...) cannot rule out an in-flight fan-out, so it is REFUSED too (fail-closed) rather than allowed through a broken scan that could hide live sentinels; only an unreadable EXISTING prefix (which cannot be proven to differ) stays advisory. A rebuild after the round has retired — no live sentinels — is unaffected: the frozen artifact of an already-completed gate pass is not the case being protected. Round retirement (`GATE-EXEC-ROUND-RETIREMENT`) does not relax this: it recovers a round AFTER a rebuild stranded it, and never licenses rebuilding mid-flight; the sanctioned rebuild path is retire-THEN-rebuild (retire the round, moving its sentinels out of the live namespace, THEN rebuild at the same head). - reference the pi-subagents `parallel context-build` technique when applicable: run parallel `context-builder` agents from fresh context with distinct output paths (e.g. `context-build/request-and-scope.md`, `context-build/codebase-and-patterns.md`, `context-build/validation-and-risks.md`) and synthesize the outputs into the review handoff artifacts #### Request-plan artifact and harness capability `write-gate-context.mjs` writes two sibling files beside the briefing prefix: the dispatch-plan JSON and the briefing-volatile text. Only the first is deterministic; the second carries a genuine per-write timestamp. The plan shape, the `requestGroups` fingerprint rules, and the harness capability vocabulary are owned by `@dev-loops/core/loop/review-dispatch-plan` (`buildReviewDispatchPlan`, `buildAngleRequestGroups`, `normalizeHarnessCapabilities`, `fingerprintRequestPrefix`) — see that module's own header comment and JSDoc for the normative description (the complete cache-relevant fingerprint input set, the four capability dimensions with their honest opaque/unavailable defaults, and the non-claim that a fingerprint proves request-SHAPE identity, never a verified provider cache hit); this section covers only what `write-gate-context.mjs` itself adds on top of that module. - **`-.dispatch-plan.json`** — `buildReviewDispatchPlan`'s output, fed `requestGroups` built by `buildAngleRequestGroups` from the round's PENDING fan-out angles (the resolved angle set minus whatever `options.fanoutDispatch.pendingGroups` already excludes as completed/carried — a group never lists an angle this round will not actually dispatch), each mapped to its concrete resolved model via `resolveRoleModel(config, { role: angle, harness, kind: "angle" })` — the SAME per-angle tier resolution (config override → per-angle tier → built-in review-persona tier → null=inherit) an actual fan-out dispatches on. This is deliberately NOT `resolveReviewerRole(config, angle).model`: that reads only a bare per-angle `model` override and ignores `tier` entirely, so it can merge two angles that dispatch on different tiers into one false "inherit" bucket, or (for a bare no-override angle, which resolves through the built-in review tier to a concrete model on most harnesses) report "inherit" for an angle that never inherits in practice. **`harness` is hardcoded `"claude"` today** — `resolveRoleModel` itself accepts a `harness` parameter and `write-gate-context.mjs` honors `options.harness` when present, but no shipped entrypoint threads a different value through: there is no `--harness` CLI flag, and `buildGateContext`'s option whitelist does not forward `harness` from its caller. So the plan records the `claude`-harness resolution only; built-in tiers are `null` (inherit) for the `pi` harness, so a `pi` fan-out actually dispatches at inherit for every angle with no explicit per-harness override — the plan's concrete `claude`-resolved groups are not evidence of what a `pi` dispatch would do. Threading `harness` through a CLI flag and `buildGateContext`'s whitelist is a later slice. Without a config, every angle resolves to the reserved `"inherit"` bucket (never guessed); a plan written this way records only "no config was consulted," not evidence of real dispatch grouping. Angle names on both sides of the pending-set intersection are trimmed the same way `--angles` itself is validated, so a whitespace-padded angle in `fanoutDispatch.pendingGroups` still matches the trimmed universe rather than silently dropping out of the plan. `sharedPrefixHash` always equals the `sha256:`-prefixed hash of the briefing-prefix bytes actually written in the same call (the independent, bare-hex `prefixHash` `write-gate-context.mjs` returns/uses for its own `#1537` rebuild-detection and `verify-fresh-review-context.mjs`'s sentinel contract is a different, older field this artifact does not own); a mismatch would mean the plan describes a prefix that was never materialized. **Shipped coverage today:** the production call site feeds `buildAngleRequestGroups` only the model, the shared-prefix bytes, and a fixed `blockBoundaries` constant (`REQUEST_PLAN_BLOCK_BOUNDARIES`, owned by `write-gate-context.mjs`) — `toolDefinitions`, `instructions`, and `settings` are NOT yet threaded through (they fall through to that function's empty defaults), so the shipped fingerprint does not yet move when tool definitions, instructions, or settings change; treat those three as documented-but-not-yet-observed until a later slice feeds real values. A group containing a non-`"full"`-scope angle still keeps `cacheBoundary: "after_shared_prefix"`: every angle in the group — scoped or not — is mandated (`GATE-EXEC-BRIEFING-PREFIX`) to read the full shared prefix first, and a scoped companion file is additional material layered AFTER that boundary, never a replacement of the shared prefix bytes within it. `ttlIntent` is derived from the resolved harness capability's `cacheTtlControl`: only `"5m_1h"` (caller-selectable) defaults to `"5m"`; every other posture (`"fixed"`/`"opaque"`) is `"harness_managed"` — the claude harness's shipped default is `"fixed"`, so the production call site writes `"harness_managed"` today. - **`-.briefing-volatile.txt`** — the physically separate volatile tail: round-level values that sit AFTER the cache boundary the briefing prefix establishes AND that `renderBriefingPrefix` never consumes (the rule for what belongs here: volatile-tail material is whatever the stable prefix render does not read). `gate`/`head` are the one deliberate exception to that rule: `renderBriefingPrefix` also states both values (in its own identifying header), so this file's `gate:`/`head:` lines are a repeated identifying header, not volatile-tail material by the rule — they let a reader with only the volatile tail open still tell which round/head it belongs to without cross-referencing the prefix. Today the rest of the content is `validationPosture` (only a pointer, `validationResultsPath`, reaches the prefix — the posture string itself never does; a `validationPosture` containing a newline is rejected rather than interpolated raw, since an embedded newline could forge additional `key: value` lines in this line-structured file) and `loggedAt`, a genuine per-write timestamp with no prefix counterpart — which is why this file, unlike the dispatch plan above, is NOT deterministic. `acceptanceCriteria` is NOT in this file: `write-gate-context.mjs` passes it as `renderBriefingPrefix`'s `issueRef`, which appears in the stable prefix's `## Linked issue ` heading whenever an issue body/sections are present, so it is stable-prefix material (and separately recorded in the JSON context artifact's `scope.acceptanceCriteria`), never volatile-tail material. This file exists so the boundary `cacheBoundary: "after_shared_prefix"` names is a real file boundary, not only a documented convention or a common substring buried inside per-angle prompt text. Writing or changing this file never touches the stable briefing-prefix bytes — the two are independent files, written independently, and a change confined to the volatile file leaves the prefix's bytes (and therefore `GATE-EXEC-BRIEFING-PREFIX`'s hash contract) untouched. **Write ordering.** The briefing prefix is written first, then the volatile tail and the dispatch plan, then the JSON context artifact's completion marker LAST — downstream consumers (`readGateContext`, a reviewer's `--context-path` guard) key on the JSON marker's existence, so a mid-set write failure must never leave a complete-looking artifact pointing at a missing or stale sibling. The plan is built — and validated (`buildAngleRequestGroups`/`buildReviewDispatchPlan` throw on a bad angle/model/capability shape) — BEFORE any destructive write. The prior JSON marker is unlinked only once the prefix bytes are actually changing (an idempotent same-bytes rerun keeps the marker, since no sibling can then contradict it), and only one directory `mkdir` is needed before the first sibling write — every sibling path (prefix, volatile tail, dispatch plan, JSON marker) shares the same directory. This artifact and capability representation are the deterministic foundation a later slice's primer-dispatch evidence consumes: the plan says WHAT the observable request shape and grouping are; a later slice records WHETHER a primer barrier actually ran before the rest of a group's fan-out, using this plan's `requestPrefixFingerprint`/`sharedPrefixHash` as its ordering evidence. ### Phase 1.5 — Cache primer (MANDATORY) `GATE-EXEC-PRIME`: **Every** gate fan-out MUST prime the shared prefix. After Phase 1 renders the byte-identical `-.briefing-prefix.txt` and BEFORE the reviewers read it, establish the shared-prefix cache **once** so the fan-out **cache-READS** the invariant prefix instead of each reviewer racing to write it (1-write-N-reads) — the cold-cache race the build-once bundle otherwise leaves on the table. This is not optional and not a config knob: build context → primer reads → fan-out reads the SAME context bundle plus its angle-specific briefing. **Default execution — one-reviewer-as-primer (zero extra cost):** dispatch ONE real reviewer first, then release the rest once its prefix write has landed — on its first streamed token if the harness streams, else on its completion (see the barrier fallback in step 3). No extra spawn, no extra tokens — the first reviewer runs anyway; the others simply start after its prefix write has landed. This is why priming is mandatory rather than opt-in: in its default form it costs at most a small serialization latency, and it removes an N× cache-write on every fan-out. **Alternative — dedicated angle-less primer:** spawn a single scoped `review` agent seeded with the briefing prefix **verbatim and ONLY** (no angle suffix), which runs the mandatory `verify-fresh-review-context.mjs` check, confirms context, and returns **without reviewing** (no findings artifact). Cleaner to reason about; costs one extra angle-less spawn. Use it where an explicit primer is preferred; otherwise the one-reviewer form is the default. **The `-prime` scope and "no findings artifact" details below apply ONLY to the dedicated angle-less primer variant.** In the default one-reviewer-as-primer path there is no separate priming run: the lead reviewer is a normal reviewer that produces normal findings under its own angle scope, and there is no `-prime` sentinel to account for. **The primer MUST be the `review`-agent request envelope, not a bespoke `context-reader`.** Byte-identical *artifact* bytes are necessary but NOT sufficient: the cache key is the whole **request prefix through the breakpoint** — model, tools + tool ordering, system/project/ agent instructions, message/content-block boundaries, thinking/tool-choice settings, the materialized context bytes, and the breakpoint position + TTL. A primer spawned as a different agent (different system prompt, tool set, or model) writes a DIFFERENT cache that the `review` reviewers never read. So the primer is literally a fan-out reviewer minus the angle suffix — same agent, same envelope — or it is useless. Because it is angle-less it is NOT a review round and **produces no findings artifact, so fan-in ignores it.** If it runs the invariant block's `verify-fresh-review-context.mjs` check, it uses the reserved `-prime` scope and records the SAME prefix hash as the reviewers — so it passes `verify-briefing-prefixes.mjs` **by construction** (a same-hash sentinel is never a mismatch), never a spurious failure. (`verify-briefing-prefixes.mjs` does not today special- case `-prime`; because the primer's hash matches the reviewers', no exclusion is required for correctness. Teaching that verifier to treat `-prime` as a non-angle in its per-gate accounting is an optional follow-up, not a precondition.) **Ordered execution:** 1. **Compile the immutable prefix** — Phase 1's `briefing-prefix.txt` (already byte-identical + hash-recorded). 2. **Prime the shared prefix** over that exact serialized prefix — by default dispatch the lead reviewer first (one-reviewer-as-primer); or, in the dedicated-primer variant, send ONE angle-less primer. Either way the same byte-identical prefix is written once. 3. **Barrier: await the shared-prefix write landing** before releasing ANY reviewer — the write must precede the parallel reads. The write has landed once the primer has produced ANY model output for that request, so the barrier keys on the earliest such signal the harness exposes: - **If the harness exposes streaming** (a token/first-chunk callback): release the rest on the primer's first streamed token. - **If it only exposes completion** (the common case — an agent/subagent call that returns a finished result): **await the primer's completion.** This is the mandatory fallback and the safe default; never release reviewers off an unobservable "start." The two forms of the primer differ only in WHICH signal they key on, never in the write-before-reads ordering. The completion fallback fully serializes the lead reviewer ahead of the rest — a small, bounded latency cost, and the reason the near-free one-reviewer form is still the default rather than a mandatory streaming dependency. 4. **Record ordering evidence** — write the primer-dispatch evidence artifact (issue #1468 slice 3) to the deterministic path `-.primer-evidence.json` beside the gate-context artifacts: `@dev-loops/core/loop/primer-evidence` (`primerEvidencePath` / `buildPrimerEvidence` / `writePrimerEvidence`). The artifact pairs the request plan with the observed primer runs and reviewer releases, binding each primer to its own model + request-prefix fingerprint and each released reviewer to a primer that landed before it. This is what lets fan-in fail closed (see Phase 3 — Consolidation) instead of trusting the rule in prose. 5. **Record before/after cache-telemetry evidence** — where the harness exposes cache usage telemetry (issue #1468 slice 4), record the cache-creation (“before”) and cache-read (“after”) events to the deterministic path `-.cache-telemetry.json` beside the gate-context artifacts: `@dev-loops/core/loop/cache-telemetry-evidence` (`cacheTelemetryPath` / `buildCacheTelemetryEvidence` / `writeCacheTelemetryEvidence`). The artifact pairs the request plan + capability record with the observed creation/read events and an aggregate read:create report. Where the harness is opaque or telemetry is unavailable, the same builder records `cacheReuseVerified: false` with the reason and MUST NOT be described as a verified `1 write + N reads` outcome — only the ordering + request-fingerprint invariants from steps 3-4 may be claimed (Section D honesty gate). 6. **Release the fan-out** over the SAME model and the SAME byte-identical prefix, so each reviewer READS the cache the primer wrote instead of racing to write its own. A differing model or prefix defeats reuse and is the same failure the byte-identity rule already guards against. Rationale (why the primer, not just the shared prefix): a parallel fan-out with no primer launches every reviewer before any has written the cache — a **cold-cache race** where all N pay a cache write and none reads. The barrier collapses that to 1 write + N reads. **No verification pass — dev-loops runs only on agent harnesses (pi, Claude Code).** There is no raw-API path here: the orchestrator spawns primer and reviewers via the harness's agent/subagent mechanism and never sees a request's `usage`, cannot set a `prompt_cache_key`, and cannot place an explicit cache breakpoint — the harness owns caching. So the primer cannot be verified from inside and there is nothing to pin; it relies entirely on the barrier + byte-identical prefix + same model producing a **content-hash cache reuse** across spawns (Anthropic caching matches on the content-prefix hash, org+model scoped — not conversation-scoped, no explicit key required). Priming is mandatory rather than a knob precisely because its default (one-reviewer) form is essentially free: worst case is a small serialization latency (if a harness turns out not to reuse the prefix across spawns), best case turns N cache-writes into 1 write + N reads on every fan-out. The unmeasurability from inside the harness is a reason to prefer the zero-extra-cost one-reviewer form, not a reason to make the win opt-in. `GATE-EXEC-VALIDATION-ARTIFACT`: The preamble MUST run the round's validation set exactly once, before any reviewer is dispatched, via `run-gate-validation.mjs`, and MUST persist the result as `-.validation.json` beside the gate-context artifact. When that artifact exists, the briefing prefix MUST point every reviewer at it (`write-gate-context.mjs --validation-results `), and a reviewer MUST consume it rather than executing any suite it records. A reviewer that finds the artifact absent, unreadable, or stamped with a different head SHA MUST report a gate-evidence finding; it MUST NOT silently run the suite itself and MUST NOT treat the gap as clean. ### Phase 2 — Fan-out: independent reviewers seeded with the neutral bundle **Reviewer-budget preflight (issue #1507).** Before fanning out, the conductor runs a pure reviewer-budget preflight and reads its result from `artifact.fanout.preflight` (emitted by `write-gate-context.mjs`, which derives it via `reviewerBudgetPreflight` from `@dev-loops/core/loop/gate-fanin`). The preflight derives how many reviewers the round needs — one per dispatch unit (the resolved fresh angles + re-verifications, NOT the raw angle count: a group of N angles is one reviewer's scoped dispatch) — and compares it against the harness's remaining reviewer budget, supplied to `write-gate-context` via `--available-reviewers ` (the conductor reads whatever budget the harness exposes and passes it through). The result shape: ``` { ok, dispatch, requiredReviewers, availableReviewers, shortfall, reason, verdict, executionMode, completedAngles, carriedAngles, pendingGroups, skippedGroups } ``` - `dispatch: true` (budget sufficient, OR the harness does not expose a budget so no shortfall can be proven) → proceed with the wave-by-wave fan-out below. - `dispatch: false` (`reason: "budget_shortfall"`, `shortfall` names the exact count the budget is short) → the conductor MUST NOT spawn any reviewer. Zero reviewers are dispatched. The shortfall is a recorded, resumable state: the gate-context artifact itself is the record (it carries the dispatch plan + preflight for this head), and completed per-angle artifacts stay valid for their head. A later session resumes the fan-out instead of restarting it: `reviewerBudgetPreflight` receives `completedAngles` — the angle names that already have a CLEAN findings artifact stamped for this head (scanned by `write-gate-context.mjs` from the per-angle reviews directory) — and a second input, `carriedAngles` (issue #1635: `write-gate-context.mjs --carried-angles `, always emitted at `preflight.carriedAngles` even when empty) — the angle names the fail-closed carry-forward seam has proven carried forward from a prior clean head. It excludes any dispatch unit whose angles are ALL complete-OR-carried from `requiredReviewers` and from `preflight.pendingGroups`. The conductor dispatches only `pendingGroups` (the shortfall), never re-dispatching a group already complete-or-carried at this head, so a session that exhausted its reviewer budget mid-fan-out picks up exactly where it stopped once a later session re-runs `write-gate-context` (`--available-reviewers` with the now-refreshed budget) at the same head and the preflight clears. Completed per-angle artifacts from PRIOR heads stay valid for their head via the carry-forward seam (see [Angle carry-forward (fail-closed)](#angle-carry-forward-fail-closed)); that seam and the same-head resume above are distinct SOURCES — one a head-bump provenance check that intentionally fails closed when `--prev-head` equals `--head-sha`, the other a same-head artifact scan — that both feed this ONE exclusion predicate once a conductor threads the carry-forward result in via `--carried-angles`. **No new gate-exemption path (#1507 AC4).** A budget shortfall is NOT a verdict: `preflight.verdict` and `preflight.executionMode` are always `null`. A shortfall never downgrades a required gate to `inline_single_agent` and never produces a clean verdict — `buildPreMergeGateCheck` / `evaluateInlineFanoutMode` reject a gate with no clean current-head marker and a non-`fanout_fanin` execution mode, so a shortfall state fails closed at merge. The preflight only blocks on a PROVEN shortfall; when the budget is unexposed (`availableReviewers: null`), it proceeds (today's behavior). Fan out one fresh-context reviewer per resolved **dispatch unit**. In the default grouped mode a dispatch unit is a group of angles (`resolveFanoutGroups`, below): configured `gates.fanout.groups` are matched first (unchanged), then the leftover ungrouped angles are auto-chunked into dispatch units of ≤ `gates.fanout.maxAnglesPerGroup` (default 3, #1601) instead of singletons. `mode: per-angle` bypasses configured groups (one singleton per angle); it matches `maxAnglesPerGroup: 1` in unit size only when no configured multi-angle group matches (one singleton unit per angle, bypassing the configured-groups table). `gate:full` no longer restores per-angle dispatch (ADR 0048 supersedes 0047): it forces the full angle set upstream (`resolveGateTier` returns `gate_full_label`, so `resolveGateAnglesDynamic` skips diff-class tier reduction) and dispatches **grouped** — configured groups first, then the leftover pool auto-chunked into units of ≤ N. `gates.fanout.groups` is a **global** reviewer-identity table (not per-gate); a configured group is emitted only for a gate that resolves at least one of its angles, so one table serves every gate without per-gate duplication. The shipped table groups **both** boundaries symmetrically: the `docs-surface` / `process` / `correctness-input` / `determinism-state` groups name draft-gate surfaces, and the `design-simplicity` / `design-solid` / `finalization` groups name the pre-approval gate's design-quality (`dry`/`kiss`/`yagni`/`deep` and `srp`/`soc`/`ocp`/`lsp`/`isp`/`dip`) and finalization (`correctness-final`/`ui-validation`) angles. Without the pre-approval groups those angles would have no configured reviewer-identity unit and would scatter across arbitrary auto-chunked leftover units, so a grouped pre-approval reviewer covering a semantic group would be rejected by `fanoutReviewerPairingError` even though the round was compliant. The draft-gate `docs` and `pr-checklist` angles the pre-approval set also resolves are already covered by the `docs-surface` and `process` groups, so they need no pre-approval-specific entry. The `contradiction-lens` finalization angle is deliberately left ungrouped: it is also a draft-gate angle, and because the table is global a group naming it would peel it into a dedicated unit in the draft gate too, so it stays an auto-chunk leftover in both gates. Only `correctness-final` and `ui-validation` (pre-approval-exclusive) are grouped, keeping all three added groups inert for the draft/spike gates. Grouping only changes how many reviewers are dispatched; the resolved angle SET, the distinct-reviewer floor (`countFreshDispatchUnits`, one distinct reviewer per resolved unit), and `requireFanoutProvenance` are unchanged for full-scope rounds. Two different "group" vocabularies exist and MUST NOT be conflated. A **request group** (`buildAngleRequestGroups`, [Request-plan artifact and harness capability](#request-plan-artifact-and-harness-capability)) buckets angles by concrete resolved model for prompt-prefix / cache batching — it is a cache-fingerprint concern with no bearing on reviewer identity. A **reviewer group** (`resolveFanoutGroups`) names reviewer IDENTITY: which angles one fresh-context reviewer legitimately covers as one dispatch unit. Fan-out **provenance is validated against `resolveFanoutGroups` output, never against `requestGroups`**: `fanoutReviewerPairingError` receives the resolved reviewer groups and honors a shared reviewer identity only when every fresh angle it covers is a member of the same `resolveFanoutGroups` unit. A plan that batches N angles into one model/cache request group is therefore still rejected unless those angles also map to one reviewer group — so a compliant grouped round must be grouped by `resolveFanoutGroups`, not merely batched by model. The reviewer is the scoped `review` agent ([review agent scoped angle-review mode](../../agents/review.md)), spawned once per dispatch unit via the plain Agent tool. Reviewers are **independent and seeded with the identical neutral context bundle verbatim** (Phase 1's diff + `adjacentCode`); they do NOT fork from, or inherit the loaded context of, the main agent or a sibling reviewer. The conductor dispatches wave-by-wave at most `gates.fanout.maxConcurrent` (default 4, #1601) dispatch units concurrently per wave, planned by `scheduleFanoutWaves` (`@dev-loops/core/loop/gate-fanin`, reusing `scheduleParallelWaves`); the wave plan is emitted alongside the per-unit briefings in the gate-context artifact (`write-gate-context.mjs` → `artifact.fanout.wavePlan`), and the conductor dispatches wave-by-wave — awaiting a free slot (wave completion) before launching the next — instead of fire-all-then-retry. **Serial heavy-reviewer bound (issue #1726):** when `gates.fanout.sequential` is set (true), effective concurrency is **one dispatch unit per wave** — the wave plan is built with `resolveFanoutEffectiveConcurrency(config, env)` (`@dev-loops/core/config`, returns 1 when sequential else `resolveFanoutMaxConcurrent`), emitted as `artifact.fanout.effectiveConcurrency`, so each heavy reviewer completes and writes its evidence artifact before the next starts (the mechanism that keeps genuine fan-out from SIGTERMing N heavy reviewers at once under child-safe parallel overload; distinct reviewers, real fan-in/ledger, and provenance are unchanged — never a collapse to inline single-agent). **Claude-harness-scoped concurrency clamp (issue #1971):** under the Claude harness (`isClaudeHarness(env)`, `env` defaulting to `process.env`), `resolveFanoutEffectiveConcurrency` additionally clamps its result to `CLAUDE_MAX_EFFECTIVE_CONCURRENT` (2) — a single-driver Claude session's own model call plus an uncapped wave burst trips that session's rate limit (HTTP 429), so the DEFAULT per-wave burst on Claude is bounded to driver + 2 with no operator-imposed throttle (no lowered `maxConcurrent`, no `sequential: true`) required. This is Claude-scoped only: the shipped cross-harness `gates.fanout.maxConcurrent` default (4) and this repo's `.devloops` override (3) are unchanged, and every other harness (pi, unknown, no env) still resolves the configured value unchanged — the clamp affects only the value Claude sessions see. When a reviewer dispatch 429s despite the cap, the conductor halves the active batch (`backoffMaxConcurrent`), recomputes the wave plan, and retries before escalating to foreground one-at-a-time fallback; the backoff is recorded in the round's provenance. `GATE-EXEC-COLLECTABLE-DISPATCH`: Every fan-out reviewer MUST be dispatched as a **COLLECTABLE** run — one the orchestrating run observes, awaits, and joins by its deterministic per-angle findings artifact (`tmp/gate-reviews//pr-/-/.json`) — and NEVER as a **detached-and-uncollectable async run** the orchestrator cannot observe or join at fan-in (#1723). This is the dispatch-observability root cause of the fan-out failure: detaching reviewers into background runs the orchestrator can neither observe nor collect is what left no per-angle evidence artifacts on disk for the fan-in. Concretely: - The orchestrator spawns each reviewer as an awaited/foreground (or otherwise joinable) run whose completion it blocks on, OR it awaits the reviewer's per-angle findings artifact at its deterministic path; it does NOT detach reviewers into background runs whose completion and artifacts it can neither observe nor collect. A dispatch the orchestrator cannot join at fan-in is a FAILED fan-out, not a dispatch strategy. - A reviewer that dies mid-review (e.g. SIGTERM / resource kill) is OBSERVABLE AS FAILED and MUST be re-dispatched (or its wave retried at the reduced batch), never silently collected as if it had produced evidence. Bounded concurrency is enforced wave-by-wave at `gates.fanout.maxConcurrent` (default 4, #1601) via `scheduleFanoutWaves` (and serialized to one unit per wave when `gates.fanout.sequential` is set, #1726); the conductor awaits a free slot before launching the next wave — never fire-all-then-retry. - Review units are right-sized to complete within the run budget: grouped dispatch (`gates.fanout.maxAnglesPerGroup`, default 3, #1601) keeps each reviewer to a bounded, budget-fitting unit, and each unit writes its per-angle artifacts before the fan-in. - The fan-in (`consolidate-fanin --expected-dispatch-units `) fails closed when any expected unit's artifact is missing on disk, so an uncollected reviewer can never produce a clean verdict. If a genuine fan-out STILL cannot produce evidence within budget, the drive STOPS and surfaces to the operator for a per-PR decision — it NEVER auto-falls back to an inline single-agent verdict. The inline escape hatch #1648 introduced is removed by #1723: inline remains possible only via the light-mode `scopeUnderThreshold` carve-out, or an explicit operator decision per PR. Each reviewer: - starts in fresh context: run the mandatory `verify-fresh-review-context.mjs` invocation exactly as Phase 1 specifies. In the fan-out, `--scope` additionally keeps parallel reviewers in the same working directory from tripping false contamination on each other's sentinels, and `--context-path` (the Phase 1 artifact) fails a reviewer in the wrong/isolated checkout closed. A grouped reviewer runs this ONCE for the whole group, with `--scope -group-` (below), not once per angle it covers. The sentinel is keyed per review ROUND by the current head SHA, so a retry at a new head naturally gets a fresh sentinel — see [Sentinel lifecycle](#sentinel-lifecycle). Here "fresh" means the reviewer's context is the neutral builder artifact + its angle(s), and explicitly NOT the main agent's conversation/state or a prior reviewer session's state: the injected neutral bundle is the intended seed (allowed), while main-agent / cross-session state bleed fails closed. - is composed via the sanctioned composer (`GATE-EXEC-BRIEFING-PREFIX`'s "The composer" paragraph): the same step that runs `verify-fresh-review-context.mjs` (above) ALSO runs `scripts/github/compose-reviewer-prompt.mjs --repo --pr --gate --head-sha --scope --angle-suffix-file `, which inlines this round's invariant-prefix bytes as the leading bytes, appends the volatile tail and the angle suffix, writes the composed prompt, and records its dispatch-prompt layout ATOMICALLY (no separate `record-dispatch-prompt-layout.mjs` call needed on this path — the composer already made it). The orchestrator then delivers the composer's `--out` file bytes to the reviewer per the "Per-harness delivery" paragraph below. Hand-composing a prompt and calling `record-dispatch-prompt-layout.mjs` directly against it remains possible as the underlying primitive, but is no longer the sanctioned fan-out path. - is seeded with the neutral context bundle verbatim (diff + `adjacentCode`) as its base, and widens (loads more files) only when a covered angle genuinely needs more — it does not re-derive the whole diff/adjacent-code graph. When it widens, it records in the findings artifact's optional `contextWidened` field ONLY the files that actually moved its judgment, never every file it opened. Absence of `contextWidened` (or an empty one) means "not consulted" — never "consulted and clean"; carry-forward and audit logic MUST NOT infer clean-ness from that omission. - is scoped to exactly one review angle (one angle per unit under `mode: per-angle`, which bypasses configured groups; every angle in its resolved group (grouped mode, the default — including `gate:full`, which dispatches grouped) — each angle keeps its own prompt, all appended after the one shared invariant prefix (`GATE-EXEC-BRIEFING-PREFIX`) - is **read-only**: inspects the diff and returns findings via output artifacts only; never edits files - runs in the PR's actual worktree/head — **never an isolated worktree** (the Phase 1 prohibition; `verify-fresh-review-context.mjs --context-path` enforces it mechanically — fails closed if the seeded artifact isn't present at the reviewer's cwd). - produces a focused findings artifact PER ANGLE it covers, each with its own verdict (clean/findings_present) and file references, stamped per the head-stamp rule below — a grouped reviewer writes as many artifacts, at the existing per-angle paths, as it has angles, never one merged artifact for the group - completion is detected via the harness completion notification, or the reviewer's findings artifact(s) at their deterministic output paths; the orchestrator awaits fan-in on those paths and joins via the sanctioned fan-in CLI `dev-loops gate consolidate-fanin` (backed by `consolidateFanin`; Phase 3). The forbidden fan-in wait improvisations (transcript-tailing, `node -e`/`python3` tool-JSON parsing, `sleep`-poll loops) and this sanctioned wait are owned by `ANTIPATTERN-FANIN-WAIT` in [anti-patterns](./anti-patterns.md). `GATE-EXEC-FANOUT-DISPATCH-KEY`: Every `runs.all` / batch reviewer dispatch MUST carry a unique `key` field on EACH item (#1681). The Pi harness's `runs.all` workflowScript API requires each collection item to declare its own `key`; omitting it fails the whole dispatch with an `invalid key` validation error, which historically degraded a `requireFanoutEvidence` gate to a single inline reviewer. This rule encodes the fix so the conductor never drops the `key` and never lets a dispatch failure silently collapse fan-out: - Build each dispatch item with a distinct `key` (a per-angle or per-group slug), so the batch validates on the harness; a missing or blank `key` on an item is a dispatch bug, not a harness quirk to work around at fan-in. - When a fan-out dispatch fails for ANY reason (including `invalid key`), the conductor MUST stop and report rather than degrading to an `inline_single_agent` verdict on a gate where `gates.requireFanoutEvidence` is enabled. Merge-time and post-time enforcement both refuse an inline verdict on such a gate through the shared `evaluateInlineFanoutMode` path (`buildPreMergeGateCheck` in `detect-checkpoint-evidence.mjs`, and `upsert-checkpoint-verdict.mjs`), so a degraded gate fails closed rather than passing as fan-out evidence. The only inline acceptance is the light-mode `scopeUnderThreshold` carve-out (or an explicit operator decision per PR), never a silent fallback. **Grouped dispatch (default).** Before fanning out, the conductor resolves this round's dispatch units by calling `resolveFanoutGroups(config, gate, resolvedAngles, { fullLabel })` (`@dev-loops/core/config`): configured `gates.fanout.groups` are matched first (an angle in no configured group joins the leftover pool), then the leftover ungrouped angles are auto-chunked into dispatch units of ≤ `gates.fanout.maxAnglesPerGroup` (default 3, #1601) instead of singletons, and the fan-out spawns ONE reviewer per returned group — never per angle. `mode: per-angle` bypasses the configured-groups table and emits one singleton unit per angle, reproducing the original one-reviewer-per-angle fan-out. `gate:full` no longer makes every group a singleton (ADR 0048 supersedes 0047): it forces the full angle set upstream and dispatches GROUPED. Because fan-in, the disposition ledger, coverage checks, and `GATE-EXEC-ARTIFACT-HEAD-STAMP` all read per-angle artifacts and never the reviewer that produced them, none of that machinery changes between the dispatch shapes. Provenance for a grouped round records the shared group name on every angle a group's reviewer covered (`fanoutReviewerPairingError`'s within-group exception, [Fan-out provenance](#fan-out-provenance-closing-the-self-produced-artifact-loophole)) — not restated here. Both bounds count **dispatch units** (groups), not angles — a group of N angles is one concurrent unit; `countFreshDispatchUnits` derives the `requireFanoutProvenance` `distinctReviewers` floor from fresh dispatch units automatically (#1601, no provenance-mechanism change). `GATE-EXEC-NO-CWD-DEPENDENCE`: A reviewer MUST NOT depend on the shell's working directory — each command may start in the primary checkout, not the worktree under review, so a bare `git branch`/`git log`/`git diff` can read the wrong tree and produce confident false findings. Run the mandatory sentinel invocation as ONE compound command that enters the worktree first (`cd && node scripts/github/verify-fresh-review-context.mjs ...`) with its cwd-relative `--context-path` exactly as briefed — the locality guard depends on that form, and the compound form is the sanctioned remedy for the resetting cwd. After it passes, address the tree explicitly with the explicit-root idiom owned by `WORKTREE-DEFAULT-USE` in [worktree-guidance](./worktree-guidance.md#default-rule-use-a-worktree-for-mutating-local-work) (`git -C `, absolute-path reads), where `` is the briefing prefix's `worktree:` line, echoed back as `repoRoot` in `verify-fresh-review-context.mjs`'s fresh output (the directory the sentinel ran in, worktree-local when the locality guard passed). `GATE-EXEC-SOURCE-READ-WORKTREE`: A reviewer citing a skill/doc/source file in a finding MUST read it from the WORKTREE SOURCE under review, not from an installed skill layout (`.pi/skills/`, `~/.pi/agent/`). Installed copies lag a PR that modifies those source files, so reading them produces false high-severity findings against text the PR already fixed (#1603). Resolve skill/doc paths (e.g. `skills//SKILL.md`, `skills/docs/...`, `docs/...`) as RELATIVE paths from the worktree cwd named on the briefing prefix's `worktree:` line. Before reporting a finding that quotes a skill/doc line, verify the cited text matches `git show HEAD:` (the worktree source at the reviewed head); a finding whose cited text does not appear in `git show HEAD:` is a false positive against a stale installed copy and MUST NOT be reported. This governs SOURCE FILES reviewed as content, not HELPER SCRIPT paths invoked as tooling — those still resolve from the installed skill layout per `ASSET-PATH-SOURCE-NO-REPO-LOCAL`. The briefing prefix carries this invariant as a fixed `## Reviewer source-read invariant` section (below) so every reviewer of a round is seeded with it byte-identically. `GATE-EXEC-ARTIFACT-HEAD-STAMP`: A per-angle findings artifact MUST carry a `headSha` field stamped with the reviewed head from the briefing, and Phase 3's `consolidate-fanin --head-sha ` MUST fail closed, naming the angle, when an artifact's stamp differs from the round's head or is missing/malformed — unknown provenance is a failure, not a bypass. Two exemptions exist: an angle declared carried forward via `--carried-angles`/`--carry-forward-plan` (exact declared name, matched case-insensitively), which keeps the existing carry-forward behavior and leaves the ledger's `carriedFromHead` as the single provenance field; and a `verdict: "blocked"` artifact, whose refusal shape carries no stamp and whose failure is owned by the blocked-verdict fail-closed path. This is what makes a stale artifact staged out of an earlier round distinguishable from a fresh verdict at the reviewed head. #### Briefing composition: invariant prefix first `GATE-EXEC-BRIEFING-PREFIX`: Every per-angle reviewer briefing MUST be composed as an **invariant block** followed by the **angle-specific prompt(s)** of its dispatch unit (one prompt per angle under `mode: per-angle` (bypasses configured groups: one singleton unit per angle); every angle prompt under grouped mode, the default — including `gate:full`, which dispatches grouped as of ADR 0048), in that order — never angle-first. The invariant block MUST be byte-identical across every reviewer of the same gate pass and MUST carry, at minimum: the repo, PR number, head SHA, and worktree path; the `write-gate-context.mjs` gate-context artifact path (`GATE-EXEC-BUILD-ONCE-SEED`); the mandatory `verify-fresh-review-context.mjs` instruction above; and the **findings write-path invariant** — the WORKTREE-ABSOLUTE per-angle findings directory (`/tmp/gate-reviews//pr-/-/`) a reviewer MUST write into (`GATE-EXEC-FINDINGS-WRITE-PATH`, #1978). A reviewer's shell cwd is not trustworthy across its commands (each may start in the primary checkout, not the worktree), so a cwd-relative `tmp/...` write can land in the primary checkout's tmp/ where fan-in never looks — surfacing only as a late "missing evidence" failure. Pinning the absolute dir (and `--tmp-root /tmp` for any findings-writer CLI) in the byte-identical prefix prevents that at dispatch; `consolidate-fanin.mjs` additionally detects a findings artifact stranded in the primary checkout and names it in the missing-evidence diagnostic rather than failing opaque. Angle identity MUST appear ONLY in the suffix (the angle-specific prompt, e.g. `COPILOT-FOLLOWUP-ADVERSARIAL-BRIEFING`'s persona prompt) and the reviewer's `--scope` flag — never inside the invariant block, or the byte-identity requirement is violated by construction and the shared-prefix prompt-cache opportunity is destroyed byte one. **Cache alignment.** Prefix-first, angle-last is the cache-alignment rule: a provider prompt cache matches on a shared PREFIX of the request, so the orchestrator MUST place the byte-identical block at the START of every reviewer prompt and the angle-specific suffix LAST, never interleaved or reordered per reviewer. This governs prompt LAYOUT only — the byte-identity/hash machinery above (`--prefix-hash`/`--prefix-file`, `verify-briefing-prefixes.mjs`) is unchanged, and the rendered `-.briefing-prefix.txt` file remains the recorded proof of what was byte-identical. Under a harness where the orchestrator seeds each reviewer with a pointer to that file rather than inlining its bytes into the prompt (`prefixMode: "file"` below, or any other pointer-based seeding), the pointer LINE ITSELF — not just the file it names — MUST be byte-identical across every reviewer of the round; a pointer that varies per reviewer (e.g. embeds the angle name or a per-reviewer path) defeats prefix matching exactly as an inlined angle-first prefix would, even though the referenced file's bytes are still shared. This pointer-based PREFIX-recording mode is distinct from the sanctioned fan-out dispatch: the emitted UNIT that `GATE-EXEC-FANOUT-DISPATCH-EMIT`'s composer produces ALWAYS inlines the prefix (never a pointer line), and the "Emitted-unit binding" fan-in check below rejects a pointer-seeded emitted prompt as not inline-aligned. Pointer-based seeding governs how the PREFIX bytes are recorded for hash byte-identity; it is not a compliant emitted-prompt LAYOUT for a dispatched reviewer. **The composer (issue #1852, by construction, not by agent discipline).** Hand-composing a reviewer prompt — leading with a per-group preamble and instructing the reviewer to READ the invariant-prefix file rather than inlining its bytes — reflexively defeats the cache-alignment rule above: it reads as ergonomic ("tell the reviewer to read the file") but produces exactly the angle-first / pointer-varying layouts this section forbids, and prose discipline alone never held. `scripts/github/compose-reviewer-prompt.mjs` is the ONE SANCTIONED way a reviewer prompt is produced on the fan-out path: given `--repo`/`--pr`/`--gate`/`--head-sha`/`--scope` and a `--angle-suffix-file` (the per-group/angle-specific prompt text the orchestrator authored), it reads this round's `-.briefing-prefix.txt` and `.briefing-volatile.txt` bytes off disk, concatenates prefix + volatile + angle suffix (in that fixed order, `composeReviewerPromptText` in `@dev-loops/core/loop/review-dispatch-plan`) so the invariant prefix is INLINED as the composed prompt's leading bytes by construction, writes the result, and — in the SAME call — records the dispatch-prompt layout via `record-dispatch-prompt-layout.mjs`'s `recordDispatchPromptLayout` (see "Prompt-LAYOUT enforcement" below). Composing and recording are one atomic call, not two steps an orchestrator could pair incorrectly or skip; hand-composed pointer-seeding (calling `record-dispatch-prompt-layout.mjs` directly against a manually-assembled prompt) remains possible as the underlying primitive but is no longer the sanctioned fan-out path. Angle CONTENT is unchanged by this: the composer never generates or templates the angle-specific text — it is still the orchestrator's own authored persona/instructions (e.g. `COPILOT-FOLLOWUP-ADVERSARIAL-BRIEFING`), supplied verbatim via `--angle-suffix-file`; the composer only enforces WHERE that text goes. `GATE-EXEC-FANOUT-DISPATCH-EMIT` (issue #2092): The composer produces ONE reviewer prompt; turning the whole round's gate-context bundle INTO those per-unit prompts is itself a single sanctioned step — `scripts/github/emit-fanout-dispatch.mjs` — NOT a composition the conductor re-derives per round. Given a gate + head whose `write-gate-context.mjs` bundle is already on disk, the emitter reads the artifact's fan-out dispatch plan (`artifact.fanout.groups`, or `artifact.fanout.pendingGroups` under `--pending`) and, for EACH resolved dispatch unit, writes a minimal angle-suffix and drives the composer above (`composeAndRecordReviewerPrompt`, the same atomic compose-and-record core the CLI uses). It emits one `{ scope, angles, group, promptPath }` per DISPATCH unit plus a `maxConcurrent` field; the conductor then dispatches one fresh-context `review` subagent per emitted unit, seeded with that unit's `promptPath` bytes verbatim, records each unit's `group` on Phase 3's `--provenance` (null for a singleton unit, the resolved unit's own name — the configured group name, or the auto-chunk bundle's own name, for a shared unit), and waves the emitted units at most `maxConcurrent` at a time. The conductor MUST bound this step by the emitter's `maxConcurrent` (`resolveFanoutEffectiveConcurrency`, 1 when `gates.fanout.sequential`), NOT by `artifact.fanout.wavePlan`: that wave plan is computed over the UNSPLIT `resolveFanoutGroups` units and no longer matches this step's split unit set (an over-cap unit the emitter cap-splits into ceil(N/REVIEWER_UNIT_MAX_ANGLES) sub-units would over-dispatch a single wave slot). On success the emitter ALSO persists its emitted round plan to the keyed `-.emit-plan.json` sibling of the gate-context bundle (`buildGateEmitPlanPath` in `write-gate-context.mjs`, the same `buildGateArtifactPath` keying as every other gate artifact), with the emitter's own result object as the body — self-describing and key-stamped — so two concurrent emitters at different gates write distinct files by construction and a coordinator consumes THAT keyed path, retiring the hand-rolled fixed-path stdout-capture habit whose shared file a concurrent gate silently clobbers. This is the ONE documented dispatch path, and it closes three failure modes prose discipline never held: - **No coordinator persona re-derivation.** The emitted angle-suffix only NAMES the unit's angle(s) and instructs the reviewer to self-resolve each angle's persona/focus via `resolveReviewerRole` (see the [review agent's scoped angle-review mode](../../agents/review.md)). The conductor never inspects `print-gates.mjs`, `angleScopes`, or hand-authors persona text — reviewer composition is resolved by the review agent + the neutral bundle (`GATE-EXEC-BUILD-ONCE-SEED`), and the fresh-context sentinel + briefing-prefix hash are enforced unchanged (`GATE-EXEC-BRIEFING-PREFIX`). - **Every multi-angle resolved unit shares a reviewer — configured group or auto-chunk bundle alike (ADR 0048 reconciles this emitter to it).** The emitter shares one reviewer for ANY multi-angle `resolveFanoutGroups` unit: a configured `gates.fanout.groups` group, or an ungrouped-leftover bundle `resolveFanoutGroups` auto-chunked into `group:...`. It records the resolved unit's own name as the reviewer's provenance `group`, capped and split at `REVIEWER_UNIT_MAX_ANGLES` (ordered `-part1`/`-part2`/... sub-units, each still recording the whole unit's name as `group`) exactly as an over-cap configured group already was. Only a genuinely single-angle unit dispatches as a singleton (no shared group). `resolveFanoutGroups` itself draws no dispatch-relevant distinction between a configured group and an auto-chunk bundle (both are "this round's resolved dispatch units"), so the emitter no longer draws one either. The merge guard (`fanoutReviewerPairingError` in `@dev-loops/core/loop/gate-fanin`) is the fail-closed authority for this: it re-derives this round's grouping independently via its own `resolveFanoutGroups` call (`detect-checkpoint-evidence.mjs`) and accepts a shared identity ONLY when every angle it covers is a member of that SAME re-derived unit — configured or auto-chunk — so a claimed group spanning angles the guard's own re-derivation places in different units (or an angle the re-derivation never resolves at all) still fails closed. The emitter no longer needs to be more conservative than the guard by splitting a sanctioned auto-chunk bundle to singletons. Provenance / distinct-reviewer / grouped-dispatch / fail-closed invariants are preserved (a singleton covering one fresh angle is never pair-checked, and a configured group's shared reviewer matches the guard's re-derivation), and this does NOT change which angles/units `resolveFanoutGroups` resolves — only how the emitter dispatches them. - **Fail-closed inputs.** A missing gate-context artifact, an artifact carrying no fan-out plan (a thin briefing built without `--base`), a plan resolving zero units, a unit with no angles, a unit name that sanitizes to an invalid scope, two units deriving a colliding sanitized scope, or a unit whose invariant-prefix record is missing all refuse (exit 1) rather than dispatching a partial or persona-less fan-out. Each unit's angle list is normalized ONCE and threaded through the scope, suffix, and provenance `group` derivation, so a malformed unit can never split those three views of whether it is a singleton. **Per-harness delivery.** The composer's `--out` file holds the exact full reviewer prompt bytes; how those bytes REACH the spawned reviewer's actual prompt differs by harness: - **Code-driven fan-out (e.g. a `pi` `runs.all` batch dispatch):** the driver reads the composer's `--out` file (or its stdout `promptPath`) and passes those bytes directly as the spawned reviewer's prompt — a straightforward byte-exact relay with no intermediate agent paraphrase. - **Agent-driven fan-out (Claude Code's Agent/Task tool):** the orchestrating agent has no primitive that injects a program-constructed byte-exact prefix into a subagent's prompt independently of the `prompt` STRING PARAMETER it itself constructs for that tool call. The sanctioned sequence is: run the composer, read its `--out` file's exact bytes, and pass those bytes verbatim — with NO added preamble, wrapper text, or paraphrase — as the Agent tool's `prompt` parameter. This makes the prompt CODE-COMPOSED (the composer, not the agent, decides the byte sequence), but the final hop — the orchestrating agent relaying those exact bytes into the tool call — is not itself mechanically enforced by this CLI. On the sanctioned composer path the dispatch record's `promptContentHash` is hashed atomically from the SAME composed bytes that become the emitted `--out` file, so `verify-dispatch-prompt-layout.mjs`'s fan-in check (below) binds the record to that emitted unit and catches a record that is NOT the emitted unit (a hand-composed prompt, a paraphrased suffix, a mismatched delivered prompt) — but it does NOT observe what the agent actually pasted into the tool call, so a FAITHFUL record of the emitted bytes paired with a drifted actual relay (an added preamble in the tool call itself) is the documented delivered-task boundary below ("Three identities, one honest boundary"), not something this check can catch. Honest finding (closes the `#1841` AC3 gap this scope is best-effort on): Claude Code's Agent-tool dispatch layer exposes no usage/cache-read telemetry to the orchestrating agent for a spawned subagent, so REAL provider cache reuse across sibling reviewers of one round (`org+model content-hash reads on reviewers 2..N`) cannot be measured or verified from inside this harness — only the ordering/fingerprint invariants above (byte-identical prefix, by-construction inline alignment, mechanical layout enforcement) are assertable here; a verified-reuse claim would require the harness to expose that telemetry, which is outside this repo's control. This is a harness-capability limit, not a defect in the composer: the composer still guarantees, by construction, that every compliant dispatch UNIT of a round shares a byte-identical leading prefix span, which is the necessary (if not independently provable) precondition for the provider to ever reuse its cache. - **Agent-driven fan-out (Codex's agent tool):** Codex is agent-driven and, like Claude Code, routes through the generic batch/agent adapter rather than a dedicated concrete adapter (only `pi` ships one today; the per-harness fixtures stamp Claude Code and Codex onto the same generic adapter with a distinct env). Its agent-tool dispatch therefore carries the SAME observed limitation as the Claude Code case above: the orchestrating agent has no primitive to inject a program-constructed byte-exact prompt independently of the prompt parameter it constructs, so the final relay hop is not mechanically enforced (the delivered-task boundary), and the dispatch layer exposes no usage/cache-read telemetry for a spawned subagent, so real provider cache reuse is not measurable from inside it either. This repo does NOT independently qualify Codex's agent-tool dispatch for production — the limitation is documented explicitly, never certified away; the same by-construction emitted-unit binding and ordering invariants are what remain assertable. **Content inlining.** `write-gate-context.mjs` renders this invariant block as a `-.briefing-prefix.txt` file sibling to the JSON context artifact, in a fixed section order: header (repo/PR/head/gate/worktree + the verify-fresh instruction), `## Reviewer source-read invariant` (the worktree-source-over-installed-copies rule `GATE-EXEC-SOURCE-READ-WORKTREE`, identical for every reviewer), `## Reviewer token discipline` (the per-reviewer token-waste rules, identical for every reviewer), PR body, linked-issue body (when present), the full diff at the reviewed head, and a changed-files/adjacent-code summary, plus one CONDITIONAL trailing section, `## Validation results at this head`, present only when a validation-results artifact was threaded (`GATE-EXEC-VALIDATION-ARTIFACT`); absent that input, the seven fixed sections are the whole prefix: the conditional section appends after the fixed sections without reordering or changing them. The PR body and each linked-issue body are author-controlled GitHub text (PR author or linked-issue author), so each is carried in its OWN fenced markdown block, never inlined unframed — a fence renders as inert literal text, so a hostile body cannot forge a `##`/`###` section heading (e.g. a fake linked-issue label, or a second `## Diff at reviewed head`/`## Changed files` section ahead of the real one) or emit `PR_BODY_ABSENT_SENTINEL`/`ISSUE_BODY_ABSENT_SENTINEL` as if it were the renderer's own statement. A multi-issue PR's per-issue bodies are passed through as structured data (label + body pairs), never pre-joined into one string, so the renderer itself — not any one issue's body — owns emitting each `###