review-code

name	review-code
description	Verify a pull request against its linked issue's acceptance criteria before it merges — a fresh-eyes QA gate over the configured target repo's issue pipeline. Trigger on "review this PR", "verify PR

review-code

You are the gate. write-code already picked a triaged issue, implemented it on a branch, and opened a PR with Fixes #N linking the issue. Your job is to verify that PR against the linked issue's acceptance-criteria checklist — one criterion at a time — and land a clear pass-or-fail verdict on the PR.

You come to this fresh, with no sunk-cost attachment to the implementation. That detachment is the whole point: the agent that wrote the code is the worst judge of whether it's done, because it knows what it meant to do. You only know what the issue asked for (the acceptance criteria) and what the PR actually does (the diff, the tests, the behavior). Verify the second against the first, from the outside, the way a separate QA pass derives a task's done-state from its acceptance criteria rather than from the implementer's say-so.

Authority limit: you never merge

You do not merge. Not on a pass, not ever, not on your own authority. Your output is a verdict — an approval signal the PR is merge-ready, or a fail comment listing what's missing. Merging is a separate, deliberate act performed by the ship-it skill (the one stage granted merge authority) — for the blocking set (§CP) too, only gated on a @kamp-us/control-plane approval at head that ship-it then enqueues on (ADR 0135). You signal merge-ready; ship-it is the consumer that asserts your PASS signal, confirms CI is green, and squash-merges. Your "you never merge" invariant holds precisely because ship-it is the single writer of the merge. Conflating "verified" with "merged" is exactly the self-grading collapse this stage exists to prevent.

All GitHub ops via gh api REST — never GraphQL

The kamp-us org runs a legacy Projects-classic integration that breaks GraphQL issue and PR queries. Every issue/PR/review/comment read and write goes through gh api REST. This is not a style preference — GraphQL calls error out on this org.

Resolve the target repo once, up front. This skill is repo-agnostic — every gh api call targets $REPO, not a hardcoded repo. Resolve it at the top of your run per the shared contract's Target repo resolution (../gh-issue-intake-formats.md): $CLAUDE_PIPELINE_REPO if set, else the current repository. In phoenix this defaults to kamp-us/phoenix, so the behavior is unchanged with no config (ADR 0062 §1).

REPO="${CLAUDE_PIPELINE_REPO:-$(gh repo view --json nameWithOwner -q .nameWithOwner)}"

Read-only on git working state

You never mutate the git working tree of the checkout you run in — the single canonical rule lives in ../gh-issue-intake-formats.md §RO; cite it, don't restate the prohibition (the five verbatim copies were the #375-class drift §RO closes). Step 2's mechanism already enforces it by construction (the head reaches a per-run ref + throwaway worktree; your session tree is never switched, reset, or checked out — ADR 0052/0067).

The formats contract

Your gate is format 2, the sub-issue body's ### Acceptance criteria checklist — read the contract so you know the shape you're verifying against: ../gh-issue-intake-formats.md §2.

The key invariant: every issue carries at least one acceptance criterion. That's the floor that guarantees there is always something to verify. If an issue you're handed somehow has zero criteria, the issue is malformed, not the PR — flag that as a process gap (it should have been caught at plan-epic/report time) rather than rubber-stamping. You read the checklist tolerantly: recognize criteria by their checkbox-bullet shape under an "Acceptance criteria" heading, not by exact punctuation.

You also read the progress comments (format 3) on the issue and the PR description — write-code leaves a trail there explaining what it did and why. That trail is context, not evidence: a criterion is satisfied by what the diff/tests/behavior actually show, not by the implementer asserting it in a comment.

The glossary — read .glossary/, use the canonical terms

When you write a FAIL finding, an appended acceptance criterion, or any verdict prose, reach for the repo-owned vocabulary register rather than inventing names (the one-concept-named-four-ways drift the audit found, #851): .glossary/TERMS.md (domain nouns) and .glossary/LANGUAGE.md (architecture vocabulary). Point at the glossary, never copy a definition into this skill — the register is the single source. (ADR 0099.)

---

Step 1 — Resolve the PR and its linked issue

You're given a PR number (or you're told to review the PR for issue #N). Establish the PR ↔ issue pairing, because the issue is where the acceptance criteria live.

PR=<pr number>
# the PR: state, head branch, body (the Fixes #N lives here), mergeability
gh api repos/$REPO/pulls/$PR \
  --jq '{number, state, draft, merged, head: .head.ref, base: .base.ref, body}'

Find the linked issue from the PR body's Fixes #N / Closes #N (the seam write-code writes). If the body names it, that's your issue. Cross-check via the timeline if it's not obvious:

# timeline shows "connected"/"cross-referenced" events linking PR ↔ issue
# --paginate + a STREAMING --jq: per_page caps at 100, so a link event past event 100 is
# invisible without it on a long-lived PR's timeline (#4193)
gh api --paginate "repos/$REPO/issues/$PR/timeline?per_page=100" \
  --jq '.[] | select(.event=="connected" or .event=="cross-referenced") | .source.issue.number // .issue.number' 2>/dev/null

Pin down ISSUE=<N>. If there is no linked issue, the rule is class-aware — this is the code-lane mirror of review-doc Step 1's issueless carve-out (ADR 0075), extended to the code lane by ADR 0184. Reuse the PR's changed-file class — the same file set Step 2's class routing reads (one class signal, not a second taxonomy; the ADR 0075 discipline review-doc follows in reusing its Step-0 class):

# no linked issue → class-aware. The carve-out is scoped EXACTLY to the conversation-authored
# coining class: the diff touches the `.glossary/**` CODE-class vocabulary coining site (ADR 0128)
# AND every changed path lies on a conversation-authored surface — `.glossary/**`, or a doc
# companion (`.decisions/**` / `.patterns/**`) carried in the same recording — and NOTHING else.
# Any path off those surfaces (`apps/**`, `packages/**`, `infra/**`, a code-root README, a root
# script) is behavioral work with a missing `Fixes #N` ⇒ a broken seam ⇒ hard-stop. Same file set +
# same path-prefix class Step 2's skills-only route uses — no second class mechanism.
# "every path is conversation-authored" is the EMPTY-OUTPUT form, never `! grep -qv` (§WL, #4155).
FILES="$(gh api --paginate "repos/$REPO/pulls/$PR/files?per_page=100" --jq '.[].filename')"
OFFSURFACE="$(grep -vE '^(\.glossary|\.decisions|\.patterns)/' <<<"$FILES")"
if [ -n "$FILES" ] \
   && grep -qE '^\.glossary/' <<<"$FILES" \
   && [ -z "$OFFSURFACE" ]; then
  echo "conversation-authored .glossary/** coining site, no Fixes #N — legitimate (ADR 0184/0075): ISSUE stays unset, AC half N/A"
else
  echo "no linked issue on a PR carrying behavioral code — broken seam: hard-stop (dangling-code guard, ADR 0184)"
fi

• Behavioral code is present (the diff carries any path off the conversation-authored coining surface — apps/**, packages/**, infra/**, a code-root README, or any product code) → stop and report no linked issue. In this pipeline write-code always writes Fixes #N, so a missing link on a PR carrying behavioral code is a broken seam, not a normal state — dangling code work with no AC to verify against. Comment on the PR that there's no linked issue to verify against (the Fixes #N seam is missing), and stop. ADR 0184 leaves this dangling-code seam guard intact: the carve-out never widens to behavioral code.
• Conversation-authored .glossary/** coining site only (the diff touches .glossary/** and every changed path lies on a conversation-authored surface, no behavioral code) → a missing Fixes #N is a legitimate state, not a broken seam. A conversation-authored vocabulary edit — a /adr-adjacent coining/redefining of a term in .glossary/LANGUAGE.md / .glossary/TERMS.md (the primary-coining-site artifact ADR 0128 routes here) — records a settled choice that was never tracked work, so there is nothing for a Fixes #N to close and no acceptance criteria to verify against. Leave ISSUE unset, treat the acceptance-criteria half as N/A (skip the per-criterion Step 3 — there is no checklist), and let the rest of the review-code gate stand as the sole contract. Emit no no-linked-issue refusal; it is not an anomaly. This relaxes only the linked-issue half — the SHA-bound verdict (ADR 0058), the glossary-freshness (Step 3c) / comment / staleness sub-gates, and the §CP-by-content routing (ADR 0164) are all unchanged and still apply in full, and the verdict for such a PR rests on them alone.

When ISSUE is set, honor it as today — pull the issue and its acceptance criteria:

ISSUE=<N>
gh api repos/$REPO/issues/$ISSUE --jq '{number, state, assignee: .assignee.login, body}'
# the progress trail write-code left — context, not evidence
gh api "repos/$REPO/issues/$ISSUE/comments?per_page=100" --jq '.[].body'

Extract the ### Acceptance criteria checklist from the issue body. That list — every box — is the contract you verify. (For an epic this won't normally apply; review-code gates the PRs that close executable issues, which carry the checklist. When ISSUE is unset per the conversation-authored .glossary/** carve-out above, the acceptance-criteria half is N/A and the rest of the review-code gate is the whole contract.)

---

Step 2 — Read what the PR actually does, and exercise its product code

Source ALL code under review from the PR head — never the launched checkout's working copy (§HEAD, mandatory). This gate is frequently spawned with isolation:worktree, whose CWD is a branch cut from origin/main (the base) — so a plain full-file Read/cat/grep in CWD reads the pre-PR base, and you would review the wrong file version while binding the verdict to the right head SHA (issue #793; the false-PASS hazard). Obey ../gh-issue-intake-formats.md §HEAD before the per-criterion checks — cite it, don't re-derive the steps: resolve the live head via REST (gh pr view $PR --repo "$REPO" --json headRefOid -q .headRefOid), fetch it into the per-run $PR_REF + assert git rev-parse "$PR_REF" equals it, read every full file from the head ($REVIEW_WT below, or git show "$PR_REF:<path>") and never from CWD, and re-check the live head before posting (§HEAD #4). The head-worktree + denylist mechanism below is §HEAD's materialization for this gate; the verdict (§5) must bind to the SHA whose files you actually read and assert it read the PR head.

Verification is grounded in the diff, the tests, and — where it matters — the behavior, not in the PR's self-description. Pull the change:

# the full diff — gh pr diff is the reliable form; the diff media type is the REST equivalent
gh pr diff $PR \
  || gh api repos/$REPO/pulls/$PR -H "Accept: application/vnd.github.v3.diff"
# files touched, at a glance
gh api --paginate "repos/$REPO/pulls/$PR/files?per_page=100" --jq '.[] | "\(.status)\t+\(.additions)/-\(.deletions)\t\(.filename)"'   # --paginate: streaming --jq, pages concatenate — the full set past file #100 (#725)

This same loaded diff (and the review worktree below) is what the specialist fan-out runs over — see Specialist fan-out + route-don't-grade after this step; it reuses this context, it does not re-load the diff.

Route a mis-classed PR away first (skills-only → review-skill)

Before any verification, check artifact class. A skill under skills/** is not your class — it is a behavioral artifact gated by review-skill (ADR 0073, which supersedes ADR 0063's skills/** → review-code routing). If the diff is a skills-only PR (every file under skills/**), report not a code PR — route to review-skill (a plain note, not a review-code: marker — there's no code to verdict) and stop. This is the symmetric off-ramp to review-doc's skills-only / pure-code routes and review-skill's "not a skill PR" route — each gate hands a mis-classed PR to the gate that owns its class:

# the file set drives the class decision (same list pulled above)
FILES="$(gh api --paginate "repos/$REPO/pulls/$PR/files?per_page=100" --jq '.[].filename')"   # --paginate + streaming --jq: full set past file #100 (the API caps per_page at 100; #725)
# skills-only ⇒ every changed path is under skills/ or agents/ — review-skill's class, not yours
# (agents/** are behavioral artifacts, review-skill-routed for the verdict — ADR 0150/#2003).
# Empty-output form, never `! grep -qv`: a false-true here `exit 0`s the code gate on a PR that
# does carry code (§WL of ../gh-issue-intake-formats.md, #4155).
OFFCLASS="$(grep -vE '^claude-plugins/kampus-pipeline/(skills|agents)/' <<<"$FILES")"
if [ -n "$FILES" ] && [ -z "$OFFCLASS" ]; then
  echo "not a code PR — route to review-skill"   # plain note, no review-code: marker; stop
  exit 0
fi

A mixed PR (skills/** and apps/web/packages code) is not skills-only — you verify the code class here and emit the review-code marker, while review-skill verifies the skills class and emits its own; ship-it requires the latest PASS in each namespace present before it merges (the same mixed-class split review-doc Step 0 spells out). A skill PR that also touches a gate-critical skill is still control plane regardless — that's the merge-blocking flag below (§CP), a separate axis from this routing decision (ADR 0073 §4).

A mixed-class PR's review is not complete until every present namespace has a current-head verdict — resolve them all in one pass (the routing-completeness rule). Routing by artifact class is not "pick one class and stop": it is "run the matching gate for every non-blocking artifact class the diff spans," so the PR reaches ship-it with a current-head PASS already standing in each present namespace. Emitting your own review-code marker covers only the code class; the doc/skill classes the diff also touches still need their gates run in the same review pass. Do not stop at the review-code marker and merely note that review-doc/review-skill "must also pass" — that note, left to a later pass, is exactly the gap that costs a mixed PR an extra review→ship round-trip (a review-code: PASS lands, ship-it fail-closes on the missing review-doc, the PR bounces back for a second review pass — #1460 / the PR #1442 incident). So when you finish the code class on a mixed PR, ensure the gate for every other present class is also run against this same head before the review is reported complete — load and follow the sibling gate(s) (review-doc for the docs class, review-skill for the skills class) in this pass, or have the routing dispatch fan out to them, so each present namespace carries a current-head verdict. Emit each namespace's verdict as its OWN separate PR comment — one comment per namespace, marker on that comment's literal first line — never two markers stacked in one comment (the second would be un-anchored, resolve empty, and fail-close a substantively-PASS PR — the PR #2456 stall; the forbidden "stacked" emit form in ../gh-issue-intake-formats.md §5). ship-it's per-present-class requirement (its Step 2) is unchanged — it remains the fail-closed late catch, the safety net for a genuinely-missing namespace, not the first place the second namespace is discovered.

The trust split: head = code under test, base = the reviewer's instructions (ADR 0052)

You are reviewing the PR head, but you must never let it review you. The head's .claude/**, root CLAUDE.md, hooks, .decisions/**, and .patterns/** are your own operating instructions — and they are editable by the very PR under review. If you checked out the head and ran in its tree, a PR could rewrite your instructions, suppress a check, or install a hook while you review it (the trust inversion ADR 0052 closes). So the split is: product code comes from the head, your config/instructions come from the trusted base ref. You verify the head's behavior without ever loading the head's instructions.

Mechanism: cone-mode checkout of the head's whole tree MINUS a fixed instruction denylist into a throwaway worktree, fetched into a ref the session tree never switches to (ADR 0067, which refined ADR 0052's non-cone product-only allowlist into this cone-minus-denylist so the in-worktree pnpm typecheck can bootstrap again — see "Typecheck is authoritative" below). Chosen over diff-only review (ADR 0052 rejects it — it forfeits behavior verification) and over "load base config then trust the harness not to reload" (that polices the invalid state rather than making it unrepresentable — ADR 0052 §Decision point 4). Two properties make the isolation hold by construction, not by your remembering to behave:

• Cone minus a denylist, not an enumerated allowlist. The security set is what the reviewer must not trust, a short fixed denylist: root CLAUDE.md, .claude/**, .decisions/**, .patterns/** (the ADR 0049/0052 harness boundary). Everything else — the head's full product workspace plus its build inputs (biome.jsonc + biome-plugins/, patches/, the catalog, the lockfile, everything fate generate needs) — is present by default because it is not on the denylist, so the typecheck bootstrap is whole and no new build prereq silently re-breaks the gate (ADR 0067 rejected growing the old allowlist for that creep). But cone mode (--cone) always materializes every top-level file regardless of the include set — so a naive cone checkout leaks the head's root CLAUDE.md. The denylist is therefore enforced explicitly after checkout: remove the denied paths from disk, then assert they are absent (below). The isolation does not come for free from the pattern set the way it did under non-cone — the remove-and-assert is the load-bearing step that keeps ADR 0052's guarantee intact.
• The head reaches a ref, never your working tree. You fetch the head into a dedicated per-run ref ($PR_REF, a refs/pr/$PR-<uuid>) and add the throwaway worktree from that ref. Your own session tree is never switched, reset, or checked out to the head — so even the cross-fork path never materializes head-controlled config into the tree you operate from. The head's checks run against the review worktree via pnpm -C, never by switching your session into it.

Your own session stays in this worktree (the trusted base config you were launched under).

# §CLI — resolve the shim by path; `pipeline-cli` is NOT on PATH (ADR 0207; #3314).
PCLI="${CLAUDE_PLUGIN_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null)/claude-plugins/kampus-pipeline}/bin/pipeline-cli"
# Isolation preflight FIRST, before any head fetch / `git worktree add` below. If this
# review-code spawn expected worktree isolation (reviewer agent-type) but the #2440 harness no-op
# dropped it onto the shared PRIMARY checkout ($WORKTREE_ROOT unset), materializing the head here
# is the #2452/#2453 primary-checkout-detach surface — fail closed LOUD and route up, never
# materialize. Single-sourced in gh-issue-intake-formats.md §RO-iso (ADR 0172; the write-code
# wt_preflight sibling). A genuine standalone run on the owner's checkout still proceeds.
iso_preflight review-code || exit 1   # ../gh-issue-intake-formats.md §RO-iso — define it there, cite here

# the trusted base — the PR's merge target at tip; your config already comes from here
BASE_REF="$(gh api repos/$REPO/pulls/$PR --jq '.base.ref')"   # normally main

# Refresh the base BEFORE any "is-it-shipped on main" ground-truth check (below). The PR
# head reaches its own ref, but the base is the *other* half of verification — a long-lived
# or busy checkout's local main goes stale, so an "is X shipped?" check read off the working
# tree is only as fresh as whoever's checkout the gate ran in. This is the freshness gap
# complementary to ADR 0052's config-isolation: 0052 pins your *config* to the base; this
# pins your *ground-truth* to the base too. (PR #305 false-FAILed on exactly this — a doc
# whose consumers had merged minutes earlier was FAILed against a stale local main.)
git fetch origin "$BASE_REF"

# §HEAD steps 1–3 (resolve the live head SHA, fetch pull/$PR/head into a per-run ref WITHOUT
# touching the session tree, assert the fetched ref IS that head, add a throwaway DETACHED head
# worktree) are the shared `pipeline-cli review-head materialize` verb (#3690 / #793 / #1807) —
# cite it, don't re-derive it. `pull/<pr>/head` resolves for same-repo AND cross-fork PRs, so there
# is no separate cross-fork branch to check out (the trust inversion ADR 0052 closes); the verb
# never runs `gh pr checkout` / `git checkout` / `git switch` (which would land the head in the
# shared PRIMARY the harness resets this cwd to and detach the human's `main` — #2270/#1103), and it
# nonce-uniques the ref per invocation so a concurrent review of the same PR can't overwrite it
# (#1807). It emits the resolved head + ref + worktree as JSON. Persist those to a per-run mktemp
# handle so they survive the harness cwd/shell reset between Bash calls (a shell var is lost across
# calls); re-source them with `. "$WT_FILE"` at each later step — NEVER re-derive from a shared leaf
# name (a `git worktree list` re-derivation matches a SIBLING reviewer's tree and pins the wrong head).
# The `--worktree` tree is a FULL checkout (ADR 0067): biome.jsonc + biome-plugins/, patches/, the
# catalog/lockfile, and everything `fate generate` needs are present, so the typecheck bootstrap is
# whole. A full checkout also lands the head's root CLAUDE.md + .claude/.decisions/.patterns — that
# leak is closed by the explicit denylist removal + absence-assert below, NOT by any pattern set.
WT_FILE="$(mktemp /tmp/review-code-wt.XXXXXX)"
"$PCLI" review-head materialize --pr "$PR" --worktree \
  | jq -r '"REVIEW_WT=\(.worktreeDir)\nPR_REF=\(.prRef)\nHEAD_SHA=\(.headSha)"' > "$WT_FILE"
. "$WT_FILE"
[ -n "${REVIEW_WT:-}" ] && [ -n "${PR_REF:-}" ] && [ -n "${HEAD_SHA:-}" ] || {
  echo "FATAL: review-head materialize did not yield a head worktree — aborting (never review the base tree; §HEAD)." >&2; exit 1; }

# LAYER-2 containment (#2666): a freshly materialized worktree MUST come up pristine — assert it
# clean NOW, before the denylist `rm --cached` below deliberately dirties it. A dirty materialization
# means a corrupted head checkout, and reviewing a contaminated tree is a false signal. Fail-closed
# LOUD via the single-sourced, tested helper (packages/pipeline-cli/src/tools/worktree-guard).
node packages/pipeline-cli/src/bin.ts worktree-guard assert-clean --path "$REVIEW_WT" || {
  echo "FATAL: review worktree came up dirty at materialization — aborting (never review a contaminated tree; #2666)." >&2
  exit 1
}

# Enforce the instruction denylist EXPLICITLY: remove the head's instruction surfaces from
# the review tree so they never reach the reviewing agent's path (ADR 0049/0052 boundary; a
# full checkout would otherwise leave root CLAUDE.md on disk). Config still comes from the
# trusted base — this tree is run *against* via `pnpm -C`, never `cd`'d into.
git -C "$REVIEW_WT" rm -r -q --cached --ignore-unmatch \
  CLAUDE.md .claude .decisions .patterns
rm -rf "$REVIEW_WT/CLAUDE.md" "$REVIEW_WT/.claude" "$REVIEW_WT/.decisions" "$REVIEW_WT/.patterns"

# ASSERT absence — the load-bearing isolation check (ADR 0067 §Consequences). If any denied
# path is still on disk the isolation is broken: abort the review rather than read head config.
for p in CLAUDE.md .claude .decisions .patterns; do
  if [ -e "$REVIEW_WT/$p" ]; then
    echo "FATAL: denied instruction surface '$p' present in review worktree — isolation broken; aborting" >&2
    exit 1
  fi
done

The cross-fork case needs no special branch: pull/$PR/head is the GitHub-provided ref for the PR head whether it lives on this repo or a fork, so the single git fetch above covers both — and because it lands in $PR_REF (not your working tree) and the denylist is removed

• asserted-absent above, head config never reaches your instruction path on any path.

For criteria that assert behavior (a test passes, typecheck is clean, a command produces an output), run the repo's commands inside the review worktree — behavior verified by running beats behavior inferred from a diff:

. "$WT_FILE"                   # re-source the run-unique $REVIEW_WT/$PR_REF after a between-call reset (#1807) — never re-derive from the shared `review-head-${PR}` leaf
pnpm -C "$REVIEW_WT" install   # the catalog/lockfile + patches/ are present, so this succeeds
# Lint via `pnpm lint:worktree`, never `pnpm lint` / `biome check .`: bare `.` resolves to the
# review worktree's CWD (sits under .claude/worktrees → matches `!**/.claude/worktrees`) and exits
# 0 WITHOUT linting (false green; #236, ADR 0060). `lint:worktree` lints the EXPLICIT changed files
# vs origin/main (committed + working-tree, biome-extension-filtered; docs-only/empty = clean skip),
# so it catches root + `.claude/**` violations a bare `biome check apps packages` would miss and
# reliably predicts the CI lint job (#553/#559):
pnpm -C "$REVIEW_WT" lint:worktree   # and/or the specific test the criterion names
# Scoping a test to the criterion is fine when the SHA-bound run-evidence bundle (Step 2)
# corroborates the full surface. But when the bundle is DEGRADED (absent/expired/stale-for-SHA),
# a feature-scoped run under-verifies the change's blast radius — see the "fail closed on the
# test surface" rule in the degrade block below: run the FULL unit project, never a subset.
rm -rf "$REVIEW_WT" && git worktree prune && git update-ref -d "$PR_REF"   # tear the throwaway tree + ref down

Teardown runs on EVERY exit path — PASS, FAIL, or a mid-run error, not just the happy path. The line above is the review's own rm -rf of a detached, already-pushed throwaway it materialized itself (safe — it holds no branch and no unpushed work), so run it even when the review is exiting FAIL or aborting after a typecheck/lint error; a leaked review-head-* tree accumulates on the shared primary otherwise (#2785). To catch a mid-block error inside a single Bash call, register it as a trap right after git worktree add: trap 'rm -rf "$REVIEW_WT"; git worktree prune; git update-ref -d "$PR_REF"' EXIT. And the standing net for the un-catchable case — a session-end abort between Bash calls, which no in-shell trap can reach — is pipeline-cli worktree-sweep --execute (#2785): it reclaims any leaked review-head-* tree that is clean + idle + unlocked, without --force (a dirty / active / locked one is KEPT — the #2240 liveness guard), so nothing accumulates unbounded.

The in-worktree typecheck is authoritative (ADR 0067, reversing ADR 0060's deferred-to-CI workaround). The cone-minus-denylist worktree carries the full build inputs, so the typecheck bootstrap is whole — run it and treat its result as the typecheck signal:

pnpm -C "$REVIEW_WT" typecheck   # `pnpm install` above made patches/ hashable + `fate generate` resolvable

CI and the SHA-bound run-evidence bundle (below) are now corroboration, not the sole signal. Only when the in-worktree typecheck genuinely cannot run (e.g. an environment fault unrelated to the PR) do you fall back to the PR's CI checks + the bundle — and say so in the verdict; do not treat CI as the authoritative typecheck once the in-worktree run works. (The lint invocation is unchanged by ADR 0067 — still explicit paths, never bare ., per the inline note above and ADR 0060.)

Don't run more than the criteria demand — you're verifying this issue's checklist, not auditing the whole repo. But for any criterion whose truth is observable by running something, run it; that's the strongest evidence you can attach.

Read the run-evidence bundle — the reproducible, SHA-bound evidence source (ADR 0054 §3)

CI publishes a run-evidence bundle for the PR's head commit: a run-evidence GitHub Actions artifact carrying a manifest.json whose structured checks[] and tests are the SHA-bound proof of what ran (ADRs 0054 §3, 0056). When it exists, cite its numbers — concrete test counts and the names of failing suites — instead of scraping raw CI logs; that is what makes a criterion's evidence reproducible rather than a prose summary. The bundle is a verdict input, never a merge authority: you still verify each criterion and you still never merge.

Fetch it through the one tested verb — never a hand-rolled gh api chain: pipeline-cli run-evidence read (#3991) resolves the producer run for that exact SHA, downloads the artifact, and validates it before interpreting it (the ZIP magic bytes prove you received an archive and not a 503 error body; schemaVersion and manifest.commit == HEAD_SHA prove the manifest attests this head). The head-SHA filter is load-bearing: a bundle from a stale earlier push is not evidence for this commit.

# §CLI — resolve the shim by path; `pipeline-cli` is NOT on PATH (ADR 0207; #3314).
PCLI="${CLAUDE_PLUGIN_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null)/claude-plugins/kampus-pipeline}/bin/pipeline-cli"
HEAD_SHA="$(gh api repos/$REPO/pulls/$PR --jq '.head.sha')"
# Exit 0 means `present` — a validated, head-bound bundle. Every other state comes back on stdout
# as JSON, so read the state rather than branching on the exit alone.
BUNDLE="$("$PCLI" run-evidence read --pr "$PR")" || true
BUNDLE_STATE="$(jq -r '.state' <<<"$BUNDLE")"     # present | pending | absent | unknown
BUNDLE_LINE="$(jq -r '.reportLine' <<<"$BUNDLE")" # the verdict line, evidence already in it

When the state is present, .manifest carries the structured results (ADR 0054 §2 fields): checks[] is each gate step ({name, status: pass|fail}), tests is the folded JUnit summary ({total, passed, failed, skipped, failingSuites[]}).

[ "$BUNDLE_STATE" = present ] && jq '.manifest | {commit, schemaVersion, checks, tests}' <<<"$BUNDLE"

Cite those numbers as the evidence for any criterion they speak to — "lint/typecheck/unit all pass per the bundle's checks[]", "tests: 47 passed / 0 failed (bundle for <short-sha>)", or on a miss the named failing suites — rather than re-deriving them from a log scrape. The verb has already asserted manifest.commit == HEAD_SHA and the schema version, so a present state is the sanity check; don't re-derive it.

Degrade gracefully — but report WHICH state you observed. A pending or unreadable bundle is not an absent one (#3991). Three of the four states are non-present, they are different facts, and reporting any of them as "absent" is a false claim about the PR:

• pending — the producer exists but has published nothing for this head yet (no run at the head, or a run still in flight). This says nothing about the PR; calling it absent invents a CI gap (PR #3913: the verdict posted 11 minutes before the producer's only run at that head was even created).
• absent — positive evidence the producer yielded nothing: no run-evidence workflow in the repo, a run that completed and published no artifact, or an expired artifact.
• unknown — the lookup could not be read (a 5xx after retries, a non-archive payload, a non-conforming response, a gh non-zero exit). A failed read is not a missing bundle; the same distinction ship-it Step 3.5 draws between unverified-transient and no bundle.

On any non-present state, paste $BUNDLE_LINE verbatim into the verdict — it already names the state, the queried head, the producer run id (or an explicit zero-runs result) and the artifact id, so the claim is falsifiable from the comment alone — then fall back to verifying the criteria from the diff, the tests you run in the review worktree above, and the PR's checks the ordinary way. Do not fail the gate, refuse to review, or block on the bundle: it strengthens evidence when present; its absence costs only reproducibility, not the review. And never write the state as free prose: a rationale you did not read off the lookup ("skipped by change-detection" — a mechanism .github/workflows/run-evidence.yml does not have) is the confabulated-verified-claim class ADR 0152 forbids.

But fail closed on the test surface (ADR 0092) — a PASS must never be reachable on a strictly-narrower test surface than the change's blast radius. On any non-present state you fall back to running tests in the review worktree, and the SHA-bound proof of what CI ran is gone, so a feature-scoped run (--project unit <feature-path>) can miss a cross-cutting contract test that lives outside the changed feature's cone — e.g. a new server-emittable wire code has repo-wide contract blast radius against apps/web/worker/features/fate/wireCodes.unit.test.ts (asserts every server code is in the SPA decode list), not feature-local blast radius. A feature-scoped green while that contract test is red is the #1657-class false-green a trust gate exists to prevent. On the degrade path therefore:

• Run the full unit project, not a feature-scoped subset. Use pnpm -C "$REVIEW_WT/apps/web" test:unit (the apps/web package script = vitest run --config vitest.config.ts --project unit, the whole unit surface — test:unit lives in apps/web/package.json, NOT the repo root, since $REVIEW_WT is the repo root a bare pnpm -C "$REVIEW_WT" test:unit hits ERR_PNPM_NO_SCRIPT), never --project unit <feature-path>. This is the fail-closed fix: it verifies the change's real blast radius, so a cross-cutting contract test cannot slip past a degraded verification.

  . "$WT_FILE"                              # re-source $REVIEW_WT/$PR_REF after a between-call reset (#1807)
  pnpm -C "$REVIEW_WT/apps/web" test:unit   # FULL unit project (the apps/web script) — never path-narrowed on the degrade path
  

• If — and only if — the full unit project genuinely cannot run (an environment fault unrelated to the PR, not a slow/large suite), fence the verdict as partial rather than emitting a full-trust PASS: review-code: PASS (partial local verification — CI-authoritative) @ <sha>, and name in the body what was and was not run. A downstream human hand-merging a §CP PR (ADRs 0053/0073) must not over-trust a narrow-surface PASS; the fence tells them (and ship-it) that CI is the authority for the surface you could not cover. Fencing is the fallback, not the default — prefer running the full unit project.

Flag a control-plane PR (complementary signal, not the isolation)

The cone-minus-denylist checkout above is what keeps you safe. Independently, note for the verdict whether the PR's diff touches the control plane — and use ship-it's blocking set exactly, because this flag predicts the consumer's (ship-it's) behavior, and that consumer refuses only the control plane. Two distinct sets are in play here; keep them apart:

• 0052's instruction-trust set (.claude/**, root CLAUDE.md, hooks, .decisions/**, .patterns/**) is what the reviewer must never load — already handled, above, by the cone-minus-denylist checkout that removes those paths and asserts them absent. It is an isolation set, not a merge-blocking set.
• The control-plane set — the single canonical definition in §CP of ../gh-issue-intake-formats.md: .claude/**, .github/**, plus the six gate-critical skills (claude-plugins/kampus-pipeline/skills/ship-it/**, claude-plugins/kampus-pipeline/skills/review-code/**, claude-plugins/kampus-pipeline/skills/review-doc/**, claude-plugins/kampus-pipeline/skills/review-skill/**, claude-plugins/kampus-pipeline/skills/review-plan/**, claude-plugins/kampus-pipeline/skills/gh-issue-intake-formats.md) — is what ship-it refuses to auto-merge (ADR 0053 §4, widened to the gate-critical skills by ADR 0065, with review-skill/** added by ADR 0073). §CP is the authoritative source — cite it, don't re-hard-code the list (the independent copies are the #375 drift class §CP closes, ADR 0073 §6). .decisions/** and .patterns/** — and every non-gate-critical skills/** — are non-blocking: they auto-merge through their gate. So the merge-blocking flag must match this exact set; flagging a .decisions/.patterns-only (or non-gate-critical skills/**) PR as "not auto-mergeable" would lie about what ship-it does and stall the autonomous lane.

So the verdict's not-auto-mergeable flag matches the canonical §CP set (the same one ship-it Step 0 uses) — and, like ship-it, it is resolved from origin/main at run time, not from the copy embedded in this skill body. The embedded copy travels in the injected snapshot, which can lag origin/main even when the on-disk file is current, so a pre-amendment snapshot once mis-classified a now-control-plane PR (#981); reading §CP freshly from origin/main (and failing closed if that read can't be made) keeps the flag tracking main, not snapshot age.

The boundary is only half of it: the changed-file list the boundary is matched against is a fallible network read too, and a failed read used to resolve to "no control-plane path touched" (#4216). Define cp_changed_files and cp_head_sha from §CPREAD — copy them verbatim, it is the single source — before running the block below, which consumes their $CP_FILES / $CP_FILES_N / $CP_HEAD_SHA and holds §CP on a non-zero return:

# §CP travels in the INJECTED skill snapshot, which can lag origin/main even when the on-disk file
# is current — a pre-amendment snapshot once mis-classified a now-control-plane PR (#981).
# §CP boundary is single-sourced in pipeline-cli (control-plane-paths/control-plane-re.ts, #2761);
# run `pipeline-cli control-plane-paths` to print it. It is re-resolved from origin/main right below
# (the #981 anti-self-authorization read), so this is only a fail-closed sentinel, never the live source.
CONTROL_PLANE_RE='.'   # fail-closed default: every path is control-plane until origin/main resolves
# Re-resolve §CP from origin/main at run time so a stale snapshot can't mis-flag a now-control-plane
# PR as auto-mergeable (#981). ADR 0073 §6 names gh-issue-intake-formats.md the single source; read it
# freshly via REST raw (never GraphQL). origin/main's line wins over the snapshot; fail closed on read failure.
CP_LIVE="$(gh api "repos/$REPO/contents/claude-plugins/kampus-pipeline/skills/gh-issue-intake-formats.md?ref=main" -H 'Accept: application/vnd.github.raw' 2>/dev/null | grep '^CONTROL_PLANE_RE=' | head -n1 || true)"
if [ -n "$CP_LIVE" ]; then
  CONTROL_PLANE_RE="$(printf '%s' "$CP_LIVE" | sed "s/^CONTROL_PLANE_RE='//; s/'$//")"   # the flag tracks origin/main, not the snapshot's age (AC1/AC2)
else
  CONTROL_PLANE_RE='.'   # FAIL CLOSED: can't read origin/main's boundary ⇒ flag EVERY path control-plane (not-auto-mergeable), never trust the possibly-stale snapshot
fi
# ONE hardened read of the changed-file list, feeding BOTH §CP clauses below. `cp_changed_files` is
# §CPREAD of ../gh-issue-intake-formats.md — exit-status-checked, shape-asserted, scope-emitting; a
# non-zero return means the read COULD NOT EXECUTE, which is UNKNOWN, not "no §CP path touched". Read
# the why there once; do not re-derive it here. It also removes the second read this step used to make
# (the GUARD_TOUCHING loop re-fetched the same list), so both clauses now see the same scanned scope.
if ! cp_changed_files "$REPO" "$PR"; then
  # FAIL CLOSED (#4216): a blinded read blinds BOTH clauses at once — the path regex AND the ADR-0164
  # content probe, which is the only §CP signal a `.decisions/**`-only PR can produce. So resolve BOTH
  # toward §CP; the sentinel is non-empty, which is exactly what Step 4a branches on.
  CONTROL_PLANE_TOUCHED="<changed-file list unreadable — §CP UNKNOWN, held as control-plane>"
  GUARD_TOUCHING="<changed-file list unreadable — §CP UNKNOWN, held as control-plane>"
else
  # grep aggregates the §CP matches ACROSS the concatenated pages — a jq `[ … ]` aggregate would
  # instead emit one array PER PAGE. `|| true` here is now safe and means ONLY what it says: no §CP
  # match is grep exit 1 over a list that was PROVEN to arrive (#725 + #4216).
  CONTROL_PLANE_TOUCHED="$(printf '%s\n' "$CP_FILES" | grep -E "$CONTROL_PLANE_RE" || true)"
  # non-empty → control-plane: emit the advisory line in the verdict (Step 4a) per ADR 0053/0065/0073
  # §CP by CONTENT (ADR 0164): a touched .decisions/** ADR is not path-§CP, but a guard-RELAXING one is
  # control-plane by nature. Probe each ADR's content at head with the SHARED `guard-content-probe` verb
  # — the SAME probe ship-it Step 0, review-doc, and the driver (via trivial-diff) call, so a guard-touching
  # ADR reads §CP consistently everywhere (issue #3645, founder ruling #3416). A mixed code+guard-ADR PR
  # fans BOTH gates; either flagging the ADR carries the §CP merge-authority hold.
  # The ref is a fallible read too — `cp_head_sha` is §CPREAD's companion to `cp_changed_files`
  # (copy it verbatim from there). It leaves HEAD_SHA EMPTY on failure by DISCARDING gh's payload,
  # which is what makes the `[ -n ]` test below a live guard rather than a dead one.
  cp_head_sha "$REPO" "$PR"; HEAD_SHA="$CP_HEAD_SHA"
  # Assert on the probe's STATE WORD, never on its exit status — the exit code discriminates the two
  # verdicts only once the verb has RUN, so the old `>/dev/null && …` shape accumulated NOTHING when it
  # never ran (bad flag / nested-cwd module-not-found / missing shim) and read an unprobed ADR as
  # ordinary. The `*)` arm keeps could-not-determine a HOLD, exactly as an unreadable body is (#4219).
  # §CLI — resolve the shim by path; `pipeline-cli` is NOT on PATH (ADR 0207; #3314).
  PCLI="${CLAUDE_PLUGIN_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null)/claude-plugins/kampus-pipeline}/bin/pipeline-cli"
  GUARD_TOUCHING=""
  [ -n "$HEAD_SHA" ] || GUARD_TOUCHING="<head SHA unreadable — ADR content unprobeable, held as control-plane>"   # fail closed: no ref ⇒ no probe ⇒ UNKNOWN
  ADR_N=0
  while IFS= read -r adr; do
    [ -z "$adr" ] && continue
    [ -n "$HEAD_SHA" ] || break
    ADR_N=$((ADR_N + 1))
    # Capture and CHECK before classifying, never a straight pipe — §CPREAD #2.
    adr_body="$(gh api "repos/$REPO/contents/$adr?ref=$HEAD_SHA" -H 'Accept: application/vnd.github.raw' 2>/dev/null)" || adr_body=""
    if [ -z "$adr_body" ]; then
      GUARD_TOUCHING="$GUARD_TOUCHING $adr(body-unreadable⇒§CP)"   # fail closed: never auto-ship an ADR that could not be read and proven guard-free
    else
      GC_STATE="$(printf '%s' "$adr_body" | "$PCLI" guard-content-probe classify --path "$adr" 2>/dev/null)"
      case "$GC_STATE" in
        not-guard-touching) : ;;   # proven ordinary — the ONLY value that may skip the §CP hold
        guard-touching) GUARD_TOUCHING="$GUARD_TOUCHING $adr" ;;
        *) GUARD_TOUCHING="$GUARD_TOUCHING $adr(undetermined:'$GC_STATE')" ;;
      esac
    fi
  done < <(printf '%s\n' "$CP_FILES" | grep -E '^\.decisions/.*\.md$' || true)
  echo "§CP scope: $CP_FILES_N file(s) scanned, $ADR_N .decisions/** ADR(s) content-probed"   # §ZS #1 (ADR 0092): a §CP classification always states its scope
fi
# non-empty $GUARD_TOUCHING → §CP-advisory, same as CONTROL_PLANE_TOUCHED above (Step 4a; ADR 0164/0135)

---

Specialist fan-out + route-don't-grade (ADR 0079) — the shared reference

This is the reference implementation of the ADR 0079 mechanism. The AC checklist (Step 3) catches what the issue named; it is blind to a real, in-scope defect the issue's AC never named — a swallowed fault, a missing invariant, an untested behavioral path that is genuinely part of "make this work" sails through a green gate because there is no open-ended correctness sweep (by design — focus over a nitpick firehose). The fan-out closes that blind spot by routing such a finding back into the single converging mechanism the loop already drains — the AC checklist — instead of onto a parallel severity/advisory track.

This section is the citable home for the other three gates. review-doc, review-skill, and review-plan wire the same fan-out + route behavior into their own classes by citing this section (ADR 0079 §1–§2) — not by re-deriving the dimensions, the route decision, or the append mechanism. Read it as one logic with four call sites: only the diff each gate already loads and the class it verifies differ.

Fan out over the already-loaded diff (don't re-load it)

Run the specialists over the diff Step 2 already pulled (and the review worktree it already materialized) — the fan-out adds no second checkout, no extra gh/worktree cost. The starting dimensions, per ADR 0079 §1 and pinned in epic #493's Resolved questions, are three — and each is a checklist line within this single review pass, not a separately spawned agent (epic #493's resolved split: a checklist line reuses the loaded context with zero added orchestration; a dimension graduates to a dedicated agent only on evidence it can't hold the rigor as a line, filed via report if/when that happens — the same seam-graduation discipline as ADR 0040's testing tiers):

• silent-failure — a swallowed error, an empty catch, a dropped Effect failure channel, a result whose error path is discarded — a fault the diff makes unobservable at runtime.
• type-design — a representable invalid state, a widened type that admits what the domain forbids, an invariant the types stop enforcing (the "make invalid states unrepresentable" bar this repo holds).
• test-gap — a behavioral path the diff adds or changes that no test exercises — coverage the AC checklist didn't name but "make this work" implies.

Each dimension produces zero or more findings: a concrete defect with its diff site. The fan-out feeds findings into the route step below; it does not itself emit a verdict.

Route, don't grade — a finding is a binary in/out-of-scope decision

A finding is routed, not graded (ADR 0079 §2). There is no severity tier and no confidence score — the decision is the single binary the plan-epic story-trace test already draws:

• In-scope — the finding traces to the linked issue's stated goal / user story, the same trace-to-stated-goal test plan-epic enforces for story coverage (ADR 0046). Route it by appending a new acceptance criterion to the linked issue, using the reviewer-append surface defined in ../gh-issue-intake-formats.md §2 — its exact checkbox shape, its canonical provenance tag (<!-- ac:review-code pr:#<PR> round:K -->), and its four fences (append-only · in-scope-only · ACL-gated/fail-closed · frozen-after-round-K). §2 is the single source — cite it; do not restate the tag fields or the fences here, so this reference and the contract cannot drift.
• Out-of-scope — the finding is real but does not trace to this issue's stated goal (a tangential defect, an adjacent refactor, a pre-existing bug the diff merely surfaces). File it via report as a fresh status:needs-triage issue; it re-enters the pipeline at intake on its own merits. The current PR is not blocked by it — routing a tangential finding to report is exactly what keeps the AC list finite and the bounded repair loop converging (§2 fence 2).

What the append does (and does not) change in this review

The fan-out + route is additive to the existing AC-verification verdict — it does not replace or weaken it. The append is the route's output, not a new gate:

• The conjunctive AC verdict (Step 3), the SHA-bound review-code: marker (§5), and the single-merge-authority invariant are unchanged. An appended criterion does not change this PR's pass/fail computation beyond the existing rules: it lands as a new unchecked [ ] row on the issue, so on the next review cycle it is an ordinary criterion the conjunctive verdict already covers (an unmet new row is a [FAIL] like any other). It enters the next cycle's work-list; write-code's repair round drains it like any other [FAIL] row (the existing converging loop), and the next review verifies it.
• Append the AC before composing the Step 3 / Step 4 verdict, so the verdict you post already reflects the appended row (it shows as a fresh [FAIL] in the table, telling write-code exactly what to drain next round). The append is gated by §2 fence 3 (only a write+ reviewer's append counts, fail-closed — the same ACL author-gate ADR 0055 applies to the verdict marker) and fence 4 (an append in/after round K = N = 3 escalates to a human instead of looping — §2's freeze, bound to write-code's existing N=3 repair cap).
• Out-of-scope findings never touch the AC list or this PR's verdict — they are report residue only.

Performing the append — the four fences, enforced at this site (ADR 0079)

§2 defines the four fences; this is where they are enforced, so an invalid append is unrepresentable rather than merely discouraged. §2 stays the single source of what each fence is — cite it, don't restate the definitions; the steps below are how the append step obeys them. The other three gates run this same procedure (one logic, four call sites). Append by reconstructing the issue body — read it, gate, append the one new row, write it back — never by a blind edit:

# the §2 in-scope-only fence (fence 2) gates whether you may append AT ALL:
# only an in-scope finding (traces to the issue's stated goal — Route, don't grade above)
# reaches here. A finding that fails the trace test was already routed to `report`; it must
# NOT arrive at this append step. If it did, route it to `report` and stop — never append it.

# ── Fence 3: ACL-gated, FAILS CLOSED ──────────────────────────────────────────────────────
# resolve your OWN authority at the GitHub ACL — the same write+ floor ADR 0055 applies to
# verdict-marker authority — BEFORE writing anything. No checked-in allowlist; the repo ACL is
# the trust root. Any non-write+/lookup-failure result fails closed: skip the append, route the
# finding to `report` instead (the PR is not blocked — it still gets your normal verdict).
ME="$(gh api user --jq .login)"
PERM="$(gh api "repos/$REPO/collaborators/$ME/permission" --jq .permission 2>/dev/null)"
case "$PERM" in
  admin|maintain|write) : ;;                       # authorized — proceed
  *) echo "below write+ floor (or ACL lookup failed) — fail closed: do NOT append, route to report"; exit 0 ;;
esac

# ── Fence 4: frozen-after-round-K (K = N = 3) ─────────────────────────────────────────────
# resolve the round K you would tag this append with — the §5/Bounding round-cluster index for
# THIS PR (the same count write-code's cap uses). An append in/after the final repair round has
# no round left to drain-and-re-verify it within the bound, so it ESCALATES to a human instead
# of appending-and-looping (the append-side of write-code's drain-side freeze — §2 fence 4).
ROUND_K=<the §5/Bounding round-cluster index for this PR>   # 1-based; a first review is round 1
if [ "$ROUND_K" -ge 3 ]; then
  # frozen: append-rate must not outrun fix-rate. Escalate, never append — name the finding,
  # hand the PR to a human, surface for re-triage (mirrors write-code's N=3 escalation path).
  gh api repos/$REPO/issues/$ISSUE/comments -f body="$(cat <<EOF
### Append escalation — in-scope finding raised at/after the final repair round (round $ROUND_K)

A reviewer specialist surfaced an in-scope finding, but it arrives in/after \`write-code\`'s
final repair round (K = N = 3), so there is no round left to drain-and-re-verify a fresh AC
within the bound. Per ADR 0079 §2 fence 4 the append is **frozen** — escalating to a human
instead of appending-and-looping:

- <finding> — <the in-scope defect; what an AC would have required>

Needs a human decision (accept as-is, extend the AC's life by a fresh triage, or drop it).
EOF
)"
  gh api -X POST repos/$REPO/issues/$ISSUE/labels -f "labels[]=status:needs-triage"
  exit 0   # frozen → escalated, NOT appended
fi

# ── Fence 1: append-only — add the one new row, never edit/remove a pre-existing one ───────
# read the CURRENT body, append exactly one §2-shaped row (provenance-tagged), write it back.
# Reconstructing the body this way makes removal/edit unrepresentable: every pre-existing line
# is carried through byte-for-byte; only a trailing criterion is added.
BODY="$(gh api repos/$REPO/issues/$ISSUE --jq .body)"
NEW_AC="- [ ] <criterion — observable, checkable from the outside> <!-- ac:review-code pr:#$PR round:$ROUND_K -->"
# append the row under the ### Acceptance criteria list; do not touch any existing row
UPDATED="$(printf '%s\n%s\n' "$BODY" "$NEW_AC")"   # illustrative — insert under the AC heading, preserving every prior line
# fail-closed integrity guard: refuse to write back a body that DROPPED or ALTERED any prior
# line — append-only means every prior line survives verbatim in the new body. If a pre-existing
# line would change, abort (never write a body that lost a criterion — the gate-weakening
# catastrophe fence 1 forbids):
diff <(printf '%s' "$BODY") <(printf '%s' "$UPDATED") | grep -qE '^< ' && { echo "append-only violation: a pre-existing line would change — ABORT, do not write"; exit 1; }
gh api -X PATCH repos/$REPO/issues/$ISSUE -f body="$UPDATED"

The append is append-only by construction (fence 1): the body is rebuilt from the existing one with a single row added, and a diff guard refuses any write that would drop or mutate a prior line — so a reviewer flow cannot edit or remove an existing AC (the catastrophe review-skill's gate-invariant check exists to catch). It is in-scope-only (fence 2): only a finding that passed the trace-to-stated-goal test (Route, don't grade) reaches this step; a tangential one was routed to report and never arrives. It is ACL-gated and fails closed (fence 3): a below-write+ author — or any ACL lookup failure — skips the append entirely, so an unauthorized identity's "append" never lands on the issue and never counts toward the gate. And it is frozen after round K = N = 3 (fence 4): an in-scope finding raised in/after the final repair round escalates to a human rather than appending-and-looping, so append-rate stays bounded by fix-rate. None of this changes the verdict computation — the conjunctive AC verdict, the SHA-bound marker, the ACL author-gate on verdicts, the control-plane boundary, and single-merge-authority are all untouched; the enforcement only makes the append safer.

---

Step 3 — Verify one criterion at a time

Skip this step when ISSUE is unset (the conversation-authored .glossary/** no-link carve-out, Step 1 / ADR 0184) — there is no acceptance-criteria checklist to walk, the acceptance-criteria half is N/A, and the rest of the review-code gate (Steps 2/3c and the comment/staleness/§CP sub-gates) is the sole contract. Otherwise walk the checklist as below.

Walk the checklist one box at a time. For each criterion, reach an independent verdict and capture the evidence that supports it. This per-criterion discipline is the heart of the gate: a blanket "looks good" is exactly the rubber-stamp the fresh QA pass exists to prevent. Each criterion gets its own verdict and its own evidence.

For a criterion that is a ground-truth check against the merge target — "the prerequisite is shipped on main", "the consumer this PR depends on is present", "the path it references exists upstream" — verify it against the freshly fetched origin/$BASE_REF from Step 2, never the working tree or a local main (which can be stale, or even reverted — the false-PASS hazard). Use git cat-file -e "origin/$BASE_REF:<path>" to assert a path exists on fresh main and git show "origin/$BASE_REF:<path>" to read its shipped content; this is what makes the verdict's freshness structural rather than dependent on the runner's checkout.

For each criterion, decide one of:

• PASS — the diff/tests/behavior demonstrably satisfy it. Evidence is concrete: the file + lines that implement it, the test that covers it and that you saw pass, the command output that shows it. When the run-evidence bundle (Step 2) covers the criterion, prefer its structured numbers — the checks[] status and the tests counts/failing-suite names — as the citation; they are SHA-bound and reproducible where a log scrape is not. (When the bundle is absent, your run-in-worktree output and the diff are the evidence, exactly as before.)
• FAIL — it's not satisfied, or only partially. Evidence is what's missing or wrong: the criterion asked for X, the PR does Y (or nothing); the test it needs is absent; the command errors.
• UNVERIFIABLE — you cannot determine it from the PR (e.g., it depends on infra you can't exercise, or the criterion is too vague to check). Treat as a soft fail: say why you can't verify, and what evidence the PR would need to add to make it checkable. Don't pass something you couldn't actually confirm.

Build a per-criterion table as you go — this becomes the verdict you post:

- [PASS] <criterion text> — <evidence: file:lines / test name / command output>
- [FAIL] <criterion text> — <what's missing: asked X, PR does Y>
- [UNVERIFIABLE] <criterion text> — <why it can't be confirmed; what'd make it checkable>

The overall verdict is conjunctive: every criterion must PASS for the PR to pass. One FAIL or UNVERIFIABLE → the PR fails the gate. This mirrors the ≥1-AC invariant from the other side: the checklist is the contract, and the contract holds only when every clause does.

Run the specialist fan-out + route step before you compose the verdict. Having verified the named criteria above, route each specialist finding per Specialist fan-out + route-don't-grade: an in-scope finding appends a new AC to the linked issue (§2 surface), so it shows in this verdict's table as a fresh [FAIL] row for write-code to drain next cycle; an out-of-scope finding goes to report and does not affect this verdict. The conjunctive computation is unchanged — an appended-then-unmet row is a [FAIL] like any other, by the existing rule.

Step 3b — Verify the flag-gating on a containment-marked PR

On a PR whose linked issue is marked **Containment:** flag (default-off), the gate carries one extra obligation: verify the change actually ships dark. The product-development cycle makes agents own deployment and humans own release (ADR 0083), and that contract is only real if a mis-gated dark-ship can't slip past the gate live. This step is the enforcement point: plan-epic stamps the marker, write-code ships dark, and review-code verifies the gating before the PR may pass. The marker contract — its values, its tolerant-read rule, who writes vs reads it — is defined once in ../gh-issue-intake-formats.md (§The product-development cycle hook); read it there, this step is the reader's behavior.

When ISSUE is unset (the conversation-authored .glossary/** no-link carve-out, Step 1 / ADR 0184) this step is a clean no-op — there is no linked issue carrying a **Containment:** marker, and a conversation-authored vocabulary recording ships no dark product surface to gate; CONTAINMENT reads as none and this contributes no criterion. Otherwise:

Read the marker off the linked issue (the ISSUE body already loaded in Step 1), tolerantly per the formats §Reading stance — a **Containment:** line, with a leading bold-marker, anywhere in the body:

# the linked issue's containment marker; a missing line reads as `none` (formats §2 tolerant-read rule)
CONTAINMENT=$(gh api repos/$REPO/issues/$ISSUE --jq '.body' \
  | grep -ioE '\**\s*Containment:\**\s*(flag|exempt|none)' | head -n1 \
  | grep -ioE '(flag|exempt|none)' || echo none)

Graceful absence — skip cleanly, never false-FAIL. The gating check runs only when the marker resolves to flag and the repo has a cycle doc. On exempt, none, a missing line, or an absent product-development-cycle.md (the canonical probe, formats §1 — a foreign install has no cycle and no flag substrate), this step is a no-op: there is nothing to contain, so it contributes no criterion to the conjunctive verdict and never emits a FAIL. Mis-firing the flag check on an exempt/foreign PR is the failure mode this guard exists to prevent — absence is a correct, first-class state (ADR 0062 portability), exactly as a missing milestone is.

# the one canonical cycle-doc probe (formats §1); absent ⇒ no cycle ⇒ skip the gating check
gh api "repos/$REPO/contents/product-development-cycle.md" --jq '.path' >/dev/null 2>&1 \
  && CYCLE_DOC=present || CYCLE_DOC=absent
# run the gating verification below ONLY when:  [ "$CONTAINMENT" = flag ] && [ "$CYCLE_DOC" = present ]

Zero-scope = FAIL — a flag-marked PR that touches no user-facing surface fails (ADR 0092 / §ZS). A **Containment:** flag (default-off) marker is the issue claiming to deliver user-facing value shipped dark — so when this check fires, the PR's user-facing surface is the gate's relevant input, and an empty surface is precisely the silent-no-op trap §ZS closes: with nothing to verify, the three-facet check below would vacuously pass and the gate would wave through a "feature" PR that changed no user-facing code (the unfiring-gate class — gh-issue-intake-formats.md §ZS, ADR 0092). So, before the facet checks, scan the diff for a user-facing surface, emit what you scanned, and FAIL CLOSED when it is empty. The user-facing surface is the set of changed paths a user can reach — apps/web/src/**/*.{tsx,css} (UI markup + stylesheets), and new fate resolvers / HTTP routes / mutations under apps/web/worker/** (the data + API surface a flag would gate). .css is in-surface because an unconditional CSS-only PR (a contrast promotion, a tap-target floor, a focus-ring fix) changes rendered surface the same way a .tsx change does — omitting it zero-scoped a correct CSS-only PR into a false FAIL (#2185). This is deliberately the reachable surface, not "any file": a flag-marked PR whose entire diff is a refactor, a test, a doc, or a config change is one that shipped no user-facing path to contain, which on a flag marker is the FAIL — there is no dark feature here to gate (it is not a graceful skip; the skip is for exempt/none/absent above, where the gate is out of surface — here the marker put it in surface and the surface came back empty):

# the PR's user-facing surface (reachable UI + new data/API entry points), off the changed file set.
# Emit the count + matched paths (ADR 0092 §ZS #1 — a gate states its scope), then fail closed on zero.
FILES="$(gh api --paginate "repos/$REPO/pulls/$PR/files?per_page=100" --jq '.[].filename')"   # the changed paths (same set Step 2 pulled; --paginate past file #100, #725)
USERFACING=$(printf '%s\n' "$FILES" | grep -E '^apps/web/src/.*\.(tsx|css)$|^apps/web/worker/.*\.(ts|tsx)$' || true)
USERFACING_N=$(printf '%s\n' "$USERFACING" | grep -c . || true)
echo "flag-gating user-facing scope: $USERFACING_N path(s) matched"; printf '%s\n' "$USERFACING"
if [ "$USERFACING_N" -eq 0 ]; then
  # relevant input (flag marker present), zero matches ⇒ FAIL CLOSED, never a silent PASS (§ZS #2).
  # Emit ONE [FAIL] row into the conjunctive verdict; the PR is not merge-ready.
  echo "- [FAIL] flag-gating (default-off) — \`**Containment:** flag\` marks a dark-shipped feature, but the diff touches NO user-facing surface (apps/web/src/**/*.{tsx,css}, new apps/web/worker/** resolver/route/mutation): empty scope on a flag-marked PR is a FAIL (ADR 0092 §ZS), not a pass — there is no user-facing path to gate."
fi

The matched-paths emit is load-bearing, not narration (§ZS #1): the verdict states the exact user-facing scope it found, so a future drift where this scan silently stops matching is visible in the run output rather than reading green. When USERFACING_N is zero you stop the Step 3b work here — the empty-scope [FAIL] row is the verdict's flag-gating entry, and the conjunctive rule (Step 3) makes it fail the PR; do not fall through to the facet checks (there is no gated path to inspect). Only a non-empty user-facing scope proceeds to the three facets below.

When it does fire with a non-empty user-facing scope, verify all three facets of the default = safe-state invariant — the load-bearing flag contract grounded in .patterns/feature-flags.md (§The one invariant) and the dark-ship procedure in .patterns/feature-flags-agent-workflow.md. Each facet is its own pass/fail line in the verdict table; any one unmet → FAIL (a flag-marked PR that ships the new path live, or with an unsafe/inverted default, is not merge-ready):

• Default-off declaration. The flag's IaC declaration sets the off / old / safe variation as its default — a FlagshipFlag(..., { defaultVariation: "off", … }) in apps/web/worker/db/resources.ts (or the dashboard-declared equivalent for a non-IaC flag). A declaration that defaults the flag on is a FAIL: a default-on flag is live the instant it merges, which defeats containment.
• Safe value as the read default. Every read site — server flags.get*(key, default) and client useFlag(key, default) / <FlagGate> — passes the safe (old-path) value as the read default, so the new path is unreachable until the flip and a Flagship outage degrades to the old path. A read that defaults to the new path (or omits the default) is a FAIL.
• No leak — the new path is unreachable with the flag off. Trace every entry into the new behavior on the diff and confirm it sits behind the gate: no default-on, no inverted gate (rendering the new path when the flag reads false), and no ungated client path that renders the new surface without consulting the flag. If any route reaches the new code with the flag off, it leaks → FAIL.

Cite the concrete evidence per facet, exactly as Step 3 demands — the defaultVariation line, the read-site key, default arguments, the gate expression wrapping the new path. Fold the result into the per-criterion table as one combined entry (or three), so the conjunctive verdict accounts for it like any other criterion:

- [PASS] flag-gating (default-off) — resources.ts:NN defaultVariation:"off"; reads pass old-path default (worker/...:NN, src/...:NN); new path gated behind FlagGate, no ungated entry
- [FAIL] flag-gating (default-off) — <which facet failed: e.g. useFlag(key, true) defaults to the NEW path → ships live>
- [FAIL] flag-gating (default-off) — flag-marked PR touches no user-facing surface (apps/web/src/**/*.{tsx,css}, new apps/web/worker/** resolver/route/mutation): empty scope = FAIL (ADR 0092 §ZS)

When the marker is exempt/none/absent or no cycle doc exists, omit this row entirely — a skipped check is not an UNVERIFIABLE (which is a soft fail); it contributes nothing, by design. That graceful omission is only for the out-of-surface case (no marker / no cycle); it is not the same as the empty-user-facing-scope FAIL above, where the marker is present and the gate's relevant surface came back empty — that one emits the [FAIL] row, never omits it (the §ZS #2 vs #3 distinction: a relevant-but-zero-match FAIL is not an out-of-surface skip).

Step 3c — Glossary-freshness gate: a new surface MUST touch .glossary/TERMS.md

A PR that adds a new domain surface — a new feature folder under apps/web/worker/features/*, or a new public package / a new public export from one — ships a concept that needs a name the rest of the codebase and the pipeline can reach for. When that name lands only in code and the repo-owned vocabulary (.glossary/TERMS.md) is left untouched, the glossary lags the shipped surface: the same concept ends up named four different ways across issues, PRs, plans, and code (the cluster-16 / #864 drift the audit found). This step turns that prose advice into an enforced gate — a PR that adds a new surface but does not also touch .glossary/TERMS.md FAILs the freshness check, so the term enters the glossary in the same change that ships the surface.

Read-only and computed off the already-loaded file list (formats §RO). The check runs over the status/filename list Step 2 already pulled — it adds no worktree mutation, no git checkout/reset/stash, no second fetch. New-ness is read from the per-file status (added) and from a read-only git cat-file -e "origin/$BASE_REF:<path>" against the freshly-fetched base (Step 2's git fetch origin "$BASE_REF"), never the working tree — a folder is new only when its marker path is absent on fresh base.

# the file list WITH status (Step 2 already loaded the diff; this reuses the same files endpoint)
# --paginate + streaming --jq so the full set past file #100 is seen (the API caps per_page at 100; #725)
FILES_STATUS="$(gh api --paginate "repos/$REPO/pulls/$PR/files?per_page=100" \
  --jq '.[] | "\(.status)\t\(.filename)"')"
ADDED="$(printf '%s\n' "$FILES_STATUS" | awk -F'\t' '$1=="added"{print $2}')"

# (1) a NEW feature folder: an added file under apps/web/worker/features/<dir>/... whose <dir>
#     did not exist on fresh base. Dedupe to the folder; a folder is new iff base has no tree there.
NEW_FEATURE_DIRS=""
for d in $(printf '%s\n' "$ADDED" \
            | sed -nE 's#^(apps/web/worker/features/[^/]+)/.*#\1#p' | sort -u); do
  # read-only existence probe against FRESH base — never the working tree (formats §RO)
  git cat-file -e "origin/$BASE_REF:$d" 2>/dev/null || NEW_FEATURE_DIRS="$NEW_FEATURE_DIRS $d"
done

# (2) a NEW public package: an added packages/<pkg>/package.json whose package dir is absent on base
NEW_PACKAGES=""
for p in $(printf '%s\n' "$ADDED" \
            | sed -nE 's#^(packages/[^/]+)/package\.json$#\1#p' | sort -u); do
  git cat-file -e "origin/$BASE_REF:$p/package.json" 2>/dev/null || NEW_PACKAGES="$NEW_PACKAGES $p"
done

# A new public EXPORT from an existing package is the third surface — a public entry point
# (packages/<pkg>/src/index.ts, or the file a package.json "exports"/"main" names) that the diff
# CHANGES to expose a new name. This one is read from the diff hunk, not a path-status test:
# inspect the diff of any touched public entry for an added `export …` line. Treat a public-entry
# file with an added export as a new surface for this gate.
PUBLIC_ENTRY_EXPORT_ADDED="$(gh pr diff $PR \
  | awk '/^\+\+\+ b\/packages\/[^/]+\/src\/index\.(ts|tsx)$/{e=1;next}
         /^\+\+\+ /{e=0} e && /^\+[^+].*\bexport\b/{print}')"

# the union: is there ANY new surface?
NEW_SURFACE="$(printf '%s %s %s' "$NEW_FEATURE_DIRS" "$NEW_PACKAGES" "$PUBLIC_ENTRY_EXPORT_ADDED" | tr -s ' ')"

# does the PR touch the glossary's domain-noun file? (added OR modified — any touch counts)
GLOSSARY_TOUCHED="$(printf '%s\n' "$FILES_STATUS" | awk -F'\t' '$2==".glossary/TERMS.md"{print}')"

The self-asserting / fail-closed verdict (formats §ZS, ADR 0092) — three outcomes, never a silent PASS. This gate's signature failure mode is scanning nothing and reading green, so it follows §ZS exactly: it emits what it scanned every run, FAILs on the relevant-but-zero-match case, and expresses a legitimately-empty scope as an explicit not-applicable skip — distinct from a FAIL:

• New surface present, .glossary/TERMS.md NOT touched ⇒ FAIL (the relevant-but-zero-match case). Emit the new surface you found and that the glossary went untouched. The remedy is in scope by construction (name the new concept in TERMS.md in this PR), so it may also be routed as an appended acceptance criterion via the §2 reviewer-append surface (per the Specialist fan-out + route-don't-grade procedure) — it traces to the issue's own "ship this surface" goal — landing it as a fresh [FAIL] row write-code drains next round. Either way the conjunctive verdict reflects it.
• New surface present, .glossary/TERMS.md touched ⇒ PASS for this facet — the surface and its term shipped together. Cite the new surface + the glossary touch as evidence.
• No new surface ⇒ explicit not-applicable skip (the §ZS #3 out-of-surface case): emit glossary-freshness: not applicable — no new feature folder / public package / export in this PR and omit the row from the conjunctive table (a skip, not an UNVERIFIABLE soft-fail, exactly as Step 3b omits its row when the containment marker doesn't fire). The emitted line is the self-assertion that the gate fired and found nothing in its surface — never a silent green.

if [ -n "$(printf '%s' "$NEW_SURFACE" | tr -d ' ')" ]; then
  echo "glossary-freshness: scanned new surfaces ⇒$NEW_SURFACE"   # §ZS #1: emit what it scanned
  if [ -n "$GLOSSARY_TOUCHED" ]; then
    echo "glossary-freshness: PASS — new surface ships with a .glossary/TERMS.md touch"
  else
    echo "glossary-freshness: FAIL — new surface added but .glossary/TERMS.md untouched (§ZS relevant-but-zero-match)"
    # fold as a FAIL facet in the verdict table (and/or append the in-scope AC per the §2 surface)
  fi
else
  echo "glossary-freshness: not applicable — no new feature folder / public package / export in this PR"   # §ZS #3 skip
fi

Fold the result into the per-criterion table as one line, exactly like Step 3b's flag-gating facet — so the conjunctive verdict (Step 3) accounts for it like any other criterion:

- [PASS] glossary-freshness — new feature folder apps/web/worker/features/<x> ships with a .glossary/TERMS.md touch (TERMS.md modified)
- [FAIL] glossary-freshness — new feature folder apps/web/worker/features/<x> added, but .glossary/TERMS.md untouched; name the surface's concept in TERMS.md (or it is appended as an AC)

When there is no new surface, omit this row entirely (the not-applicable skip), exactly as Step 3b omits its flag-gating row when the containment marker doesn't fire — a skip contributes nothing to the conjunctive verdict, by design, and is never a silent PASS because the emitted not applicable line above is its self-assertion.

Graceful absence — no .glossary/TERMS.md on the base ⇒ no glossary to enforce against. If the repo has not yet adopted the glossary (.glossary/TERMS.md absent on fresh origin/$BASE_REF — a read-only git cat-file -e "origin/$BASE_REF:.glossary/TERMS.md"), this whole step is a not-applicable skip: there is no vocabulary file to require a touch of, so it emits glossary-freshness: not applicable — no .glossary/TERMS.md on base and contributes no row. This is the same portability / graceful-absence contract the cycle-doc probe (Step 3b, formats §1) and the milestone default follow — absence is a first-class state, not a defect.

Step 3d — Comment-discipline gate: the fresh-eyes judge of comment slop (ADR 0119)

CLAUDE.md's "Comments earn their place or die" is a standing rule, but until ADR 0119 the only enforcement was write-code Step 4c — the author self-deslopping its own diff. That is structurally author-biased: the agent that just wrote each justification, believing every line earned its place, is the worst judge of its own slop, so slop kept landing in merged PRs (#1242 goal unmet; evidence #1380/#1378, ~29% comment lines with the same invariant re-derived 3×). This step gives comment-discipline the same fresh-eyes pass correctness already gets — you, the independent reviewer, are the judge; the author only fixes via the normal repair loop. It is a