# Cabinet Checkpoint Protocol

The single source of truth for how cabinet members review work in
progress. `/execute` and `/execute-group` both **read this file and
follow it** rather than copying the mechanism — so a change here flows to
every checkpoint, everywhere, with no copy-drift.

A checkpoint is a chance to stop before the cost of fixing goes up. The
mechanism is the same at every scale; only the **scope** of what's
reviewed changes.

## When you are told to "follow the checkpoint protocol scoped to X"

The caller names a scope. The scope determines what each spawned agent
reviews — everything else (how to spawn, what to collect, how to
escalate) is identical.

| Scope | Reviews | Runs |
|-------|---------|------|
| `pre-impl` | The plan text + the list of files it will change | Before any code is written |
| `this file group` | The git diff for one logical group of changed files | After each file group is implemented |
| `pre-commit` | The full git diff of all changes | After implementation, before commit |
| `this group's aggregate` *(group runs only)* | The combined diff of all plans in a parallel group | After a parallel group merges |

A *parallel group* (the last row) is `/execute-group`'s unit of work: a
set of conflict-free plans implemented concurrently in separate worktrees,
then merged together. `/execute` never exercises that scope — it runs one
plan at a time and uses only the first three.

## Checkpoint modes — who acts on the verdict

The scope says *what* is reviewed. The **mode** says *what happens to the
verdict*. This distinction is load-bearing: an autonomous gate that reverts
or halts on a false-positive `stop` is fragile and expensive. The default for
high-stakes reviews is to put judgment in front of the operator.

| Mode | Where it runs | What a `stop`/`pause` does | Used by |
|------|---------------|----------------------------|---------|
| **Interactive CP** | Main session (skill level) | Surfaced to the operator, who decides (proceed / drop / override / abort). Never automatic. | `/execute-group` CP1 |
| **Advisory CP** | Workflow | Recorded in the Completion Report as a concern. Never halts or reverts. The only automatic gate alongside it is merge-delta `/validate` — new failures vs the group's pre-merge baseline; inherited debt is reported, not gated. | `/execute-group` CP3 |
| **Full CP** | Main session or workflow | Halts on `stop`, escalates 3+ `pause` to a halt, requires explicit override. The classic gate. | `/execute` CP1/CP2/CP3 |

**Why Interactive and Advisory exist.** `/execute-group` once ran CP1 and CP3
as autonomous gates inside a single workflow: a cabinet `stop` halted the run
or reverted a merge with no human in the loop. False positives there cost real
money (a CP1 halted twice consecutively — 1.6M+ tokens — on concerns the plan
text already addressed). Moving CP1 to interactive (operator decides) and CP3
to advisory (concerns recorded, merge-delta `/validate` is the only hard
gate) keeps the review signal while removing the destructive autonomous
action.

**The hard gate is merge-delta, not absolute.** `/execute-group` captures a
`/validate` baseline on main before the group's first merge. Only failures
NOT in that baseline (i.e. failures the group itself introduced) gate a merge
or completion. Failures that pre-date the group are inherited debt: listed
loudly in the Completion Report's `pre_existing_debt` section, never gated.
This too is field-driven — two consecutive groups were gated on documented
pre-existing main debt with zero merge-delta regressions, and the manual
recovery (judge the delta by hand, close the plans) ran identically both
times, so the delta judgment was promoted into the gate itself. The gate
stays hard for new failures: the point is removing ritual, not weakening it.

### Interactive CP adds a required `addressed_by_plan` field

At Interactive CP (`/execute-group` CP1, `pre-impl` scope), each agent's
verdict carries one extra **required** field, `addressed_by_plan` — the list
of risks the plan already handles. The agent must enumerate these *first*,
before raising any concern. This forces the plan-first discipline structurally:
a risk listed in `addressed_by_plan` cannot also be raised as a concern. It is
the direct fix for the false-positive halts.

## Step 1 — Select which members to spawn

Spawn one Agent per cabinet member that matches **either**:

- **Standing mandate** — `standingMandate` includes the current verb
  (`execute`). Read `.claude/skills/_index.json` to find them. These run
  at every checkpoint regardless of surface area.
- **Surface area** — a file in the reviewed scope matches the member's
  file patterns, or a keyword in the plan description matches the
  member's topic keywords.

Fall back to reading `cabinet-*/SKILL.md` frontmatter if the index is
missing.

**Err toward inclusion.** A member that activates unnecessarily costs a
few seconds; one that stays silent when it was needed costs rework. For
`this file group` scope, narrow to members matching *that group's* files
— a member reviewing 3 changed files gives sharper feedback than one
reviewing 30.

If the project has no cabinet members, skip the checkpoint and proceed —
checkpoints add depth, not structure.

## Step 2 — Spawn the agents (concurrently)

Spawn the selected members concurrently — they don't depend on each
other. **How** you spawn depends on the caller:

- From `/execute` (main session): issue all Agent-tool calls in a single
  message so they run in parallel.
- From `/execute-group` (workflow script): issue the spawns as `agent()`
  calls inside a `parallel()` block. Worktree agents cannot spawn
  reviewers themselves — the workflow orchestrator does it.

Either way, each spawned agent receives:

- The cabinet member's full `SKILL.md` content
- Essential project briefing from `.claude/cabinet/_briefing.md` (read it
  once, reuse for every agent)
- The member's `directives.execute`, if present — paste it in to sharpen
  the member's focus
- **The scoped material:** plan text + file list (`pre-impl`), or the
  relevant git diff (`this file group`, `pre-commit`, aggregate)
- An instruction to return the verdict object below

**Plan-first review discipline (critical for `pre-impl` scope):** at
`pre-impl` scope, the agent receives the plan's full notes. The plan IS
the primary input — it may already address common risks (auth, validation,
XSS, race conditions). The agent MUST:

1. **Read the plan text first.** Understand what the plan says it will do
   and what mitigations it already includes.
2. **Only raise concerns the plan does NOT address.** If the plan says
   "preview action lives in Admin::TargetsController with three-layered
   auth," do not raise "needs admin auth" as a concern — the plan already
   covers it. Explicitly acknowledge addressed concerns rather than
   re-raising them.
3. **Distinguish "the codebase has this risk" from "the plan doesn't
   mitigate this risk."** A checkpoint is not a codebase audit. The
   question is whether THIS PLAN is safe to start — not whether the
   codebase has pre-existing issues outside the plan's scope.

Without this discipline, cabinet members pattern-match against codebase
state and raise false positives that the plan already handles, wasting
tokens on re-runs that produce the same concerns.

## Step 3 — Collect verdicts

Each agent returns exactly this shape:

```json
{
  "cabinet_member": "name",
  "verdict": "continue" | "pause" | "stop",
  "concerns": [
    { "description": "...", "evidence": "...", "severity": "blocking" | "advisory" }
  ]
}
```

At **Interactive CP** (`/execute-group` CP1), add the required
`addressed_by_plan` array described above:

```json
{
  "cabinet_member": "name",
  "addressed_by_plan": ["risks the plan already handles"],
  "verdict": "continue" | "pause" | "stop",
  "concerns": [ ... ]
}
```

## Step 4 — Apply escalation

The escalation below is **Full CP** behavior (used by `/execute`). For
**Interactive CP** the verdicts are surfaced to the operator severity-first
and the operator decides — no automatic halt. For **Advisory CP** the concerns
are recorded in the Completion Report and nothing halts or reverts; merge-delta
`/validate` is the only automatic gate. See "Checkpoint modes" above.

Collect every verdict, then:

- **Any `stop`** → halt. Show the concern. Require an explicit override
  from the user before proceeding.
- **Any `pause`** → show the concern with options: proceed / address /
  abort.
- **3+ `pause`** → escalate to stop-equivalent (halt, require override).
- **All `continue`** → proceed with a brief one-line summary.

At `pre-commit` and aggregate scopes, re-check earlier `continue`
concerns: a concern that was minor in one file group can become
significant once all changes are viewed together.

## Principles

- **Cabinet members are guardrails, not gates.** The user always has the
  final say. A `stop` requires explicit override — it is not an automatic
  rejection.
- **Scope tightly.** The narrower the diff a member reviews, the better
  the feedback.
- **The pre-commit sweep catches emergent issues.** File groups that look
  fine alone create problems in combination — type mismatches across
  boundaries, security gaps from API + frontend changes landing together.