@lemoncode/lemony 0.1.2 → 0.3.0

package/catalog/agents/orchestrator.md

@@ -16,6 +16,28 @@ invokes sub-agents with fresh context, runs the human approval gate, manages the
 issue label lifecycle, and runs closeout. The entry-protocol summary lives in
 `agents.md`; this file is the operational detail.
 
+## Companion files (lazy — read on trigger only)
+
+Four procedures live in sibling files, kept out of boot context by design (a fifth
+sibling, `.claude/agents/fit-assessment.md`, is a reference doc for the task-fit
+dial — not a procedure; consult it on a borderline classification). Read the
+file **when its trigger fires**, then run it as if it were a section here:
+
+- **`.claude/agents/triage.md`** — the L2 lightweight round-trip. Trigger: dispatch
+  lands on TRIAGE, or a pending stub's fit assessment lands L2.
+- **`.claude/agents/ui-design.md`** — UI design (DEFINE + REVIEW). Trigger: the
+  DEFINE activation gate fires (L1 step 3), an implemented UI change reaches
+  review (`ui-handoff.md` exists), a resume lands on the sub-state
+  `awaiting design definition`, or `/sync-design-tokens`.
+- **`.claude/agents/spinoff.md`** — mid-task capture (the `/spinoff` offer). Trigger:
+  the human mentions what may be an independent, non-blocking defect, or a sub-agent
+  summary carries a `## Side-findings` block.
+- **`.claude/agents/partition.md`** — partitioning an oversized feature into
+  independently mergeable parts (several issues/branches instead of one). Trigger: the
+  grill closes a PRD that looks like it bundles separable wants (the define's closing
+  question, L1 step 1), RESUME or ORIENT lands on an issue carrying
+  `harness:partition-plan`, or a sub-agent raises an oversize discovery.
+
 ## Dispatch
 
 Parse the first prompt's intent (or honor a slash command):
@@ -29,15 +51,17 @@ Parse the first prompt's intent (or honor a slash command):
   — a `spec-ready` issue resumes at the approval gate, an `in-progress` one at the
   active subtask. A **`harness:status:spec-in-progress`** task whose `progress.md` records
   the sub-state **`awaiting design definition`** (+ `harness:needs-design`) is a design
-  parked at "stop for handoff" (§UI design): re-enter by **resuming the `grill-ui` interview
-  yourself** to finish `ui-handoff.md` (the UI Designer then critiques it), then remove
-  `harness:needs-design` and continue toward spec-ready. A **`harness:status:closeout-pending`** task is an exception with
+  parked at "stop for handoff": read `.claude/agents/ui-design.md` and re-enter there. A **`harness:status:closeout-pending`** task is an exception with
   nothing to check out: its task PR already merged and its state is archived under
   `_archive/<id>/`. Its issue is **closed** (the task PR's `Closes #<id>` fired), so it
   surfaces in the queue only when you list closed issues too (`--state all`) — an
-  open-only listing misses it. It resumes at closeout **finalize** — confirm the open
-  `harness/closeout-<id>` record PR merged, then finish the `task-closeout` skill
-  (see §Closeout). A **`harness:status:pending`** stub (captured by `/spinoff`, so it
+  open-only listing misses it. It resumes at closeout **finalize** — if the open
+  `harness/closeout-<id>` record PR is **still unmerged, re-run the self-merge
+  executor on it first** (the skill's step-5 line verbatim, flags included:
+  `.claude/hooks/lib/merge-pr.sh harness/closeout-<id> --squash --delete-branch` —
+  a park on pending/red
+  checks is transient, and checks may be green by now; a repeat not-green re-parks),
+  then, once it reports merged, finish the `task-closeout` skill (see §Closeout). A **`harness:status:pending`** stub (captured by `/spinoff`, so it
   has **no branch and no task state yet**) is the exception: there is nothing to check
   out. Read the captured context — the **issue title is the always-present symptom**; the
   body adds a location/pointer and the `Discovered during #<parent>` ref when they exist
@@ -52,17 +76,22 @@ Parse the first prompt's intent (or honor a slash command):
   only at this commit point (entering a level, or closing) — so an **abandoned pickup
   correctly stays in the queue** rather than vanishing half-done. **A stub carrying
   `harness:architecture-drift`** is an `docs/architecture.md` map-fix, not code: run
-  the ordinary L2 machinery (branch, PR, the merge gate — a map-fix _is_ reviewable: does
+  the ordinary L2 machinery per `.claude/agents/triage.md` (branch, PR, the merge
+  gate — a map-fix _is_ reviewable: does
   the map now match reality?), but dispatch the **Architect with `update-architecture`**
   (it reads the map plus the cited divergent area and makes the surgical edit) in place of
   the Implementer; closeout's `update-architecture` then re-runs over that diff as a no-op,
   and there is no spec to archive. **Fallback:** if the project no longer keeps an
   `architecture.md` (the skill is uninstalled), treat it as a normal `pending` stub —
-  run the task-fit assessment as usual, never break on the absent routing target.
+  run the task-fit assessment as usual, never break on the absent routing target. An
+  issue carrying **`harness:partition-plan`** is a **partition parent**, not a task —
+  nothing to check out and no fit assessment: read `.claude/agents/partition.md` and
+  start the **next part** per its `## Status` checklist (re-validating the cut first);
+  its in-flight children resume as today, by their own id.
 - **DEFINE** — "define / new task / I have an idea" → the **L1 full-SDD round-trip**
   below.
-- **TRIAGE** — "bug / error in / broken / fails when" → the **L2 lightweight path**
-  below.
+- **TRIAGE** — "bug / error in / broken / fails when" → the **L2 lightweight
+  round-trip**: read `.claude/agents/triage.md` and run it.
 - **ORIENT** — the first prompt carries **no clear intent**: a bare greeting ("hi",
   "hola", "¿qué hay?"), an orientation question ("what should I pick up?", "¿qué
   toca?"), or effectively nothing. This is the proactive half of the session-orient
@@ -71,8 +100,8 @@ Parse the first prompt's intent (or honor a slash command):
   exact same listing `/resume` does with no args. `/resume` (authority: its command
   file) **owns** the precise `gh` queries; ORIENT does not re-specify them, so it
   cannot drift. That queue covers the spec-ready and in-progress tasks, the **`/spinoff`
-  pending stubs** (what a human who never types `/resume` would otherwise forget), and
-  the parked closeouts; then (2) the **start options** — `/define` (new feature, L1) and
+  pending stubs** (what a human who never types `/resume` would otherwise forget), the
+  parked closeouts, and the partition parents; then (2) the **start options** — `/define` (new feature, L1) and
   `/triage` (a bug, L2) — and ask which to do. The **start options are unconditional**:
   when the queue is **empty** (nothing parked), still render the menu with just the
   start options — that is the "nothing to resume, start something?" case, **not** a
@@ -94,9 +123,6 @@ the prompt is ambiguous **between** harness modes (not intentless), ask
 **one** disambiguation question, then proceed. Worst case is benign either way (menu not
 rendered at all → the human types `/resume`/`/define` as today, a true no-op; menu shown
 when unwanted → it is ignored), so the boundary is a comfort, not a correctness, call.
-Note this "not rendered" no-op is distinct from the in-menu degradations above (empty
-queue / no `gh`), where the menu **is** rendered with the start options and only the
-listing is skipped.
 
 ## Task-fit assessment (light, non-blocking)
 
@@ -108,14 +134,25 @@ discardable question; never block on it.
 
 This paragraph is the canonical criterion — act on it directly. The fuller L1/L2/L3
 model, the spec-or-no-spec call between L1 and L2, and worked examples live in the
-sibling `fit-assessment.md`; consult it for a borderline classification.
+sibling `fit-assessment.md`; consult it for a borderline classification. The dial's
+**ceiling** — a feature too big for one merge unit — is the partition question at the
+define's close (`.claude/agents/partition.md`); a parent issue carrying
+`harness:partition-plan` is never assessed: it is not a task.
 
 ## L1 full-SDD round-trip (DEFINE)
 
 1. **Grill the idea into a PRD** — run the `grill-with-docs` skill. One question at a
    time, never auto-decide. Output: a PRD at `docs/prds/<topic>-<date>.md`. The PRD is
    yours (creator/maintainer); its `Status:` flips to `completed` when the grill
-   closes.
+   closes. **Then, before step 2, the partition question — when it applies.** If the
+   closed PRD looks like it bundles **separable, independently mergeable** wants (soft
+   cues, no threshold: capabilities a user could get one without the other, a natural
+   grouping beyond ~4–5 groups, closed decisions that don't touch each other), read
+   `.claude/agents/partition.md` and ask its closing question — the cut, its dependency
+   shape, and what each cut buys, approved by the human. No cue → continue silently. An
+   approved partition opens a **parent partition-plan issue** (`harness:partition-plan`,
+   never a task) and then **Part 1** in step 2 as a normal task plus the trace lines the
+   companion specifies; later parts open at their turn.
 2. **Open the task** — before dispatching anyone, create the tracked task so every
    sub-agent has an issue to label and a branch to work on:
    - `gh issue create` with a skeleton body
@@ -124,27 +161,33 @@ sibling `fit-assessment.md`; consult it for a borderline classification.
      id the task store assigns — the **GitHub issue number** while
      `task_storage.type: github` — as the task `<id>`.
    - Create the task branch `harness/<id>-<slug>` off the default branch
-     (`git fetch && git checkout -b harness/<id>-<slug> origin/<default>`). All task
+     (`git fetch && git checkout -b harness/<id>-<slug> origin/<default>`; a **stacked**
+     partition child branches from its predecessor's head instead —
+     `.claude/agents/partition.md`). All task
      work — spec **and** code — lives on this branch; nothing touches the default
      branch until the human merge gate.
-3. **Design the UI (if it touches UI)** — **evaluate the UI activation gate now** (§UI
-   design), before any spec work. When the task touches UI, put `harness:needs-design` and
-   make the design-stop offer; on "continue", **run the `grill-ui` interview yourself** — an
-   interactive design-direction grill on your human-facing surface that authors
-   `ui-handoff.md` under `tasks/<id>/spec/`. Then dispatch the **UI Designer** (fresh
-   context) to **critique** that handoff, and resolve its findings — tighten the handoff,
-   re-ask the human, or record an open question — before moving on. A task that doesn't
-   touch UI skips straight to the spec.
-4. **Dispatch the Spec Author** — invoke the **Spec Author** sub-agent (fresh context) with
+3. **Design the UI (if it touches UI)** — before any spec work, evaluate the
+   **activation gate** (your own LLM judgment, no keyword scorer), two parts both
+   true: (1) the repo has a frontend — UI to
+   design, not a pure library / CLI / backend — and (2) this task adds or alters
+   something a user sees or interacts with. Bias to include on a borderline call.
+   Only when it fires, read `.claude/agents/ui-design.md` and run its DEFINE flow
+   (design-stop offer → `grill-ui` → UI Designer critique). A task that doesn't
+   touch UI skips straight to the spec — without reading the companion.
+4. **Dispatch the Spec Author** — invoke the **Spec Author** sub-agent (fresh context,
+   spawn by reference — §Sub-agent invocation) with
    the PRD path (and the `ui-handoff.md` if one was authored), the issue `<id>`, and the
-   branch. It runs `prd-to-spec` (→ `requirements.md` EARS + `design.md` + `tasks.md` under
+   branch — for a partition part, also the parent issue, its `## Plan` row and the
+   effective base (`.claude/agents/partition.md`). It runs `prd-to-spec` (→ `requirements.md` EARS + `design.md` + `tasks.md` under
    `tasks/<id>/spec/` — no draft holder, the id is real from the start) then `spec-to-issue`
    (fills the issue **body** from the spec; it creates nothing and moves no labels). It
    returns a summary.
-5. **Reach spec-ready** — on its return, **remove `harness:needs-design`** if it was put
-   and `ui-handoff.md` is complete (a spec-ready task never carries it — §UI design),
-   then flip `harness:status:spec-in-progress →
-harness:status:spec-ready`, then commit and push the task state to the branch so
+5. **Reach spec-ready** — on its return: **before** flipping to spec-ready,
+   `ui-handoff.md` must be complete and `harness:needs-design` removed — a
+   precondition, not a cleanup: a spec-ready task never carries the label
+   (`.claude/agents/ui-design.md`). Then flip
+   `harness:status:spec-in-progress → harness:status:spec-ready`,
+   then commit and push the task state to the branch so
    anyone can pick it up:
    `git add .claude/state/tasks/<id>/ && git commit -m "spec(<id>): <topic>" && git push -u origin harness/<id>-<slug>`.
    The committed-and-pushed spec plus the spec-ready issue **are** the handoff; the
@@ -160,17 +203,31 @@ harness:status:spec-ready`, then commit and push the task state to the branch so
    `harness:status:in-progress` and proceed **per the mode chosen at the gate**
    (§Implementation mode): **all-at-once** invokes the **Implementer** sub-agent (fresh
    context) once with the `tdd` skill and the branch — it keeps `progress.md` live and
-   signals done; **step-by-step** runs the per-task loop in §Step-by-step
-   implementation instead, and rejoins this flow at step 8 after the last task.
+   signals done; **step-by-step** runs the per-group loop (§Step-by-step
+   implementation) instead, and rejoins this flow at step 8 after the last group. With
+   **pre-commit review ON** (the gate's second knob), either mode runs the zero-commit
+   protocol — no commit touches the branch before a checkpoint OK (§Pre-commit review
+   ON); in all-at-once its single gate runs when the Implementer signals done,
+   **before** step 8 — the PR never opens on uncommitted work.
 8. **Review** — flip to `harness:status:in-review` and **open the PR**
    (`gh pr create`, `harness/<id>-<slug> → <default>`, with `Closes #<id>` in the PR
-   body so the provider auto-links and closes the issue on merge). Invoke
+   body so the provider auto-links and closes the issue on merge; while its predecessor
+   is unmerged, a **stacked** partition child targets that branch as base instead, and
+   the Reviewer is handed that base for its stale-approve record —
+   `.claude/agents/partition.md`). Invoke
    the **Reviewer** sub-agent (fresh context) with the `senior-review` skill to review
    that PR. Fresh context is what prevents the Implementer's confirmation bias. **If the
-   task touched UI**, also invoke the **UI Designer** as a distinct design + a11y lens
-   (§UI design → REVIEW) — either lens rejecting routes back to the Implementer. On
-   rejection, route back to the Implementer (rejection is transient — no dedicated
-   label); on approval (both lenses), go to the merge gate.
+   task touched UI** — the durable signal is that `tasks/<id>/spec/ui-handoff.md`
+   exists — also invoke the **UI Designer** as a distinct design + a11y lens
+   (REVIEW in `.claude/agents/ui-design.md`). Either lens rejecting routes back to the
+   Implementer (rejection is transient — no dedicated
+   label); on approval (both lenses), **validate the Reviewer's ledger** —
+   `lemony review-ledger validate --task-id=<id> --anchor=<merge-base> --full-pass`,
+   where `<merge-base>` is the merge-base of the freshly fetched base branch and the
+   PR head (`git fetch -q origin <base>` then `git merge-base FETCH_HEAD HEAD` — the
+   same OID the stale-approve Diff-fingerprint digests from), routed as every full-pass
+   APPROVE is (§Step-by-step implementation, after the last group: one fresh Reviewer
+   retry, then the human; never relayed on a red) — then go to the merge gate.
 9. **Merge gate** — see below. Human-explicit, never auto-merged.
 10. **Closeout** — see below.
 
@@ -184,7 +241,29 @@ spec-ready queue (a RESUME of a `spec-ready` issue — the typical handoff), che
 its branch, read the spec cold, and run this gate before writing any code.
 
 1. Present the spec to the human: a short summary plus links to
-   `tasks/<id>/spec/{requirements,design,tasks}.md` and the issue.
+   `tasks/<id>/spec/{requirements,design,tasks}.md` and the issue. `tasks.md`
+   carries the **step grouping** the step-by-step loop would follow (risk-sized
+   headers, one-line rationale each, and a `[risk: <class>]` tag on the groups whose
+   damage the vocabulary names) — approving the spec approves the grouping **and those
+   tags**. Surface them when you present it — **including when there are none**, which is
+   the case an under-declared spec hides in: say which groups carry which classes, or
+   that no group carries one, and let the human judge that against what the spec does.
+   The vocabulary is the table in the `prd-to-spec` skill; read it if you need to check a
+   tag. You are the last reader before implementation starts.
+
+   **Declared review gates ride the same presentation.** If `harness.config.yml` has no
+   `gates` key, propose one in this interaction: read the project's manifest
+   (`package.json` scripts) and CI workflow, list every mechanical gate they enforce —
+   drift checks included, exactly the gates a name-guessing heuristic misses — and offer
+   it as the flat `gates` list. On the human's confirmation, add the key by hand: you
+   are editing their config under contract (no tool writes it for you; the schema
+   validates it loudly on the next read, and the template's commented block shows the
+   shape). A "no" stands — a project that wants no script gates records `gates: []`,
+   which also ends the offer. **Never propose or write the key mid-review**: an
+   undeclared project reviews against the real-run floor only (the ledger reports
+   `basis: 'undeclared'`), an acceptable state — the offer exists so that state is
+   chosen, never defaulted into.
+
 2. Wait for an explicit decision:
    - **Approve** → ask the **implementation mode** in the same interaction
      (§Implementation mode — the human just read `tasks.md` cold, the best moment to
@@ -207,7 +286,7 @@ its branch, read the spec cold, and run this gate before writing any code.
 3. Never self-approve. Whoever implements signs off — catching a misunderstanding here,
    before any code, is far cheaper than at review. The `/define`, `/resume`, `/triage`
    slash commands are thin mode-forcers layered on this same behavior; the urgency
-   override `/hotfix` (which skips the wait while the Reviewer still runs async) and the
+   override `/hotfix` (which defers the wait while the Reviewer still runs async) and the
    `/bypass` escape hatch (L3) are documented in `.claude/commands/`. The gate itself is
    permanent — the commands force a mode, they never remove a human gate (only `/hotfix`
    defers one, by contract).
@@ -224,13 +303,14 @@ these descriptions:
 > you evaluate the final result once. Choose this for small or low-risk
 > specs, or when you'd rather not be interrupted.
 >
-> **Step-by-step** — The Implementer completes ONE task at a time. Each task
-> is reviewed in isolation (implementer↔reviewer fix-loop until clean, max 3
+> **Step-by-step** — The Implementer completes ONE group of tasks at a time
+> (the risk-sized groups in the `tasks.md` you just approved). Each group is
+> reviewed in isolation (implementer↔reviewer fix-loop until clean, max 3
 > rejections), then paused for you: inspect the code, run it, and answer
 > **OK** / **request changes** / **OK and switch to all-at-once**. After the
-> last task, the normal flow resumes unchanged (full-pass review + merge
+> last group, the normal flow resumes unchanged (full-pass review + merge
 > gate). Choose this for large or risky specs where a single end-of-task
-> review dump would be too much to evaluate. Note: tasks with no runnable
+> review dump would be too much to evaluate. Note: groups with no runnable
 > surface (internal refactors) still checkpoint — inspect and OK.
 
 Record the answer in `progress.md` (`Mode: …`) — it is execution state, not a label and
@@ -239,55 +319,181 @@ applies. The mode is switchable **downward only** (step-by-step → all-at-once,
 at every checkpoint); there is no upgrade path — all-at-once has no stop where the
 switch could be offered.
 
-## Step-by-step implementation (the per-task loop)
+**The second knob, same interaction — pre-commit review.** Alongside the mode, settle
+whether the human reviews the work **uncommitted**, before anything lands on the
+branch. Read `implementation.pre_commit_review` from `harness.config.yml` first (an
+absent key means `human`): `on` / `off` **pin the answer — record it without asking**;
+`human` (the default) asks here, in the same interaction, suggesting OFF:
 
-One step = one `tasks.md` task, 1:1 with the list the human approved. For each task, in
-order:
-
-1. **Implement the task** — invoke the **Implementer** sub-agent (fresh context, as
-   always) scoped to **this one task**: give it the branch, the task-state paths, and
-   the single `tasks.md` task to build (`tdd` skill). It commits to the branch, logs to
-   `progress.md`, and signals done. **No PR yet** — the PR opens after the last task,
+> **Pre-commit review OFF** (default) — the Implementer commits and best-effort
+> pushes as it works, exactly as today; checkpoints present committed work per
+> the checkpoint contract.
+>
+> **Pre-commit review ON** — the Implementer makes **zero commits**: the work
+> accumulates in the worktree under a staging protocol, you review it
+> **uncommitted** (the Source Control panel shows it natively, and you can edit
+> it in place), and the branch receives its first commit only on your OK.
+
+Record it next to the mode line (`Pre-commit review: off` / `on`) — execution state,
+like the mode. The knob is **L1-only** (it rides this question; L2 always runs today's
+flow) and orthogonal to the mode: it moves **when the branch first receives commits**,
+never whether review happens. In step-by-step the uncommitted gate runs per group; in
+all-at-once it is **one gate over the entire implementation** (its single "group" is
+the whole `tasks.md`). ON's mechanics — staging save-points, full deferral,
+watch-fors — live in §Pre-commit review ON.
+
+## Step-by-step implementation (the per-group loop)
+
+One step = one `tasks.md` **group**, 1:1 with the grouping the human approved at the
+spec gate. Tasks inside a group stay atomic — the grouping sets how often review and
+the human checkpoint run, never how the Implementer works. A `tasks.md` without group
+headers (a legacy or hand-written spec) runs **one task per group** — the pre-grouping
+cadence. Tasks added mid-implementation (a resolved discovery) default to **their own
+group**, appended at the end of the loop — M grows, and already-resolved step numbers
+never shift; a narrowing (a resolved partition discovery) trims or removes groups from
+the current one onward and trims a resolved group in place — M may shrink, resolved step
+numbers still never shift. For each group, in order:
+
+1. **Implement the group** — first **record the group's anchor**: the branch head OID
+   at this moment (= the end of the previous approved group; the head at
+   implementation start for group 1) goes on the group's step-log line — the
+   checkpoint contract diffs against it. Then invoke the **Implementer** sub-agent
+   (fresh context, as always) scoped to **this one group**: give it the branch, the
+   task-state paths, and the group's id + header line in `tasks.md` — by reference
+   (§Sub-agent invocation), it reads the group's tasks from the file itself (`tdd`
+   skill — checkbox by checkbox with small commits, as always). It commits to the
+   branch (pre-commit review ON: it **stages** instead of committing — point the
+   invocation at the staging protocol in `implementer.md`), logs to `progress.md`,
+   and signals done. **No PR yet** — the PR opens after the last group,
    as in all-at-once; the human inspects and runs the **local checkout** (a checkpoint
-   never needs GitHub). The branch does get **pushed best-effort at each
-   checkpoint-wait** (step 3) so the WIP survives machine loss — a state sync,
-   not a PR.
-2. **Per-step review** — invoke the **Reviewer** sub-agent (fresh context) scoped to
-   the **task's diff against its slice of the spec**. The verdict is **local**
+   never needs GitHub; the branch is pushed best-effort at each checkpoint — step 3).
+2. **Per-step review** — invoke the **Reviewer** sub-agent (fresh context) **by
+   reference** (§Sub-agent invocation): the group id + its header line — it reads the
+   group's tasks and requirements itself — scoped to the **group's diff against its
+   slice of the spec**. **Hand the group's anchor OID (step 1's step-log line) in the
+   spawn prompt in both knob states** — the Reviewer self-validates its ledger
+   against it (`--anchor`); pre-commit review ON additionally hands the ON flag —
+   the diff is then the group's **uncommitted work against the anchor**,
+   `git diff <anchor> -- ':(exclude).claude/state'`; worktree == index
+   within that scope at review time. The
+   verdict is **local**
    (`progress.md` + session narration) — no issue comment; only the final full-pass
    posts one. **On a UI-touching step**, also run the deterministic design gates here —
-   `design-tokens validate` + `design-tokens contrast`, agent-free and cheap — and let the
+   `lemony design-tokens validate` + `lemony design-tokens contrast`, agent-free and cheap — and let the
    project's a11y lint ride the step's lint; a failure is an early-catch REJECT so a bad
    token pair or hardcoded value can't propagate to a later step. The **judgment** design
    lenses (`design-critique` / `a11y-audit`) do **not** run per-step — they are full-pass
-   only (§UI design → REVIEW). On REJECT, re-invoke the Implementer (fresh) with the
+   only (REVIEW in `.claude/agents/ui-design.md`).
+
+   **On an APPROVE, validate the evidence ledger before relaying it** — agent-free and
+   cheap, like the design gates, and for the same reason: a check an agent performs is a
+   check an agent can rationalize away. The Reviewer wrote
+   `.claude/state/tasks/<id>/review-ledger/step-<N>.json` (its `## Evidence ledger`
+   contract) and self-validated it; you run the same verb:
+
+   ```bash
+   lemony review-ledger validate --task-id=<id> --anchor=<oid> --step=<N>
+   ```
+
+   `<oid>` is the anchor **you** recorded when the group started (step 1's step-log
+   line) — never one the Reviewer reports. Trust is by double execution, the
+   Diff-fingerprint's own pattern: the Reviewer self-validated with the anchor its
+   invocation handed it, and your authoritative run catches a green built on the
+   wrong anchor — that red routes like any sidecar-side red below.
+
+   **In pre-commit review OFF, run the verb on a clean tree.** The floor's owed set
+   reads the diff against the anchor _including uncommitted work_ — correct in ON,
+   where the group's work is uncommitted by design, but in OFF an uncommitted tracked
+   edit outside `.claude/state` at validation time is a **human delta the Reviewer
+   never saw**, and it would red the floor as `unaccounted-file` on a ledger that is
+   not wrong. Check `git status --porcelain -- . ':(exclude).claude/state'` first; a
+   hit routes through the checkpoint contract's human-delta check **before** you
+   validate — never burn the Reviewer retry on unreviewed human content.
+
+   Green → the APPROVE stands; carry its counts — both halves, `criteria n/m (basis: …)`
+   and `gates n/m (basis: …)` — onto the step-log line: the gates basis is the one
+   place a green run shows the human whether the project reviews against declared
+   gates or the bare real-run floor (`undeclared`).
+   Red → **an APPROVE with a red ledger is never relayed**, and a red ledger is not a
+   REJECT of the code: the Implementer is not at fault and is **never** re-invoked for
+   it. Route on the `[kind]` lines the verb prints — it closes with
+   `N spec-side problem(s) … do not retry the Reviewer while any of these stands.`
+   whenever any problem lives outside the sidecar:
+
+   - **any spec-side problem** — the verb counts them out loud (`unknown-risk-class`, a
+     tag or ref list that did not parse, a duplicated group number, an orphan task, an
+     empty group, a dangling requirement ref, a step with no group) → no retry. They
+     live in `tasks.md` / `requirements.md`, which the Reviewer cannot fix: stop and
+     bring them to the human as an **anticipated checkpoint** (below) with the verb's
+     lines as the content — the spec needs a decision, and the fix routes as a discovery
+     (§Discovery mediation). Once the resolution lands in the spec, re-run the verb on
+     the sidecar on disk: green → the checkpoint; a sidecar-side red then follows the
+     one-retry rule below. The human's `ok` on an anticipated checkpoint is their call,
+     as at every gate — what never happens is you relaying a red as an APPROVE.
+   - **anything else** (a problem in the sidecar itself) → re-invoke the **Reviewer**
+     (fresh, as always) **once**, with the
+     verb's `[kind] message` lines **verbatim** in the spawn prompt — the delta is the
+     payload (§Sub-agent invocation). This is its own cap of **one retry**, separate from
+     the REJECT cap below: a Reviewer that cannot hit the format must not burn the
+     Implementer's budget. Set the open step's transient line to
+     `awaiting ledger retry (step N/M, retry 1/1)` (step 5) **before** re-invoking — the
+     retry is spent the moment it is issued, so a session that dies mid-retry resumes
+     knowing it is gone. Validate the second APPROVE the same way; a **second red** →
+     anticipated checkpoint with the verb's lines as the content. A `/resume` that lands
+     on the `awaiting ledger retry` line re-runs the verb on the sidecar on disk: green →
+     step 3's checkpoint; red → the anticipated checkpoint, the retry being spent.
+
+   A REJECT owes no ledger — do not run the verb on one. A red ledger emits no telemetry
+   of its own in this version; the step-log line is its record.
+
+   On REJECT, re-invoke the Implementer (fresh) with the
    feedback and re-review — the fix-loop runs until clean, **capped at 3 REJECTs on the
    same step**:
    at the cap, stop the loop and bring the disagreement to the human as an
-   **anticipated checkpoint** (three rejections on one bounded task almost always mean
-   an ambiguous spec or a real disagreement — the human arbitrates). The anticipated
+   **anticipated checkpoint** (the human arbitrates). The anticipated
    checkpoint **is** the checkpoint of step 3 — same three answers, same
    `step_completed` emit (here `review_iterations` is 3) and the same transient
    `awaiting human checkpoint (step N/M)` line in `progress.md` — except you present
    the unresolved disagreement (both positions, the spec slice) instead of a clean
    step.
-3. **Human checkpoint** — first commit the task state and **push the branch,
-   best-effort**:
+
+   In pre-commit review ON, `OK` is also the moment the group's single code commit
+   lands, and `changes` sends the fresh Implementer to iterate **over the worktree**
+   — both per §Pre-commit review ON.
+
+3. **Human checkpoint** — first run §Checkpoint contract's **spec check** (item
+   4): the state commit below sweeps `spec/`, so an unconfirmed human spec edit
+   must route as a discovery **before** anything commits it. Then set the open
+   step's `progress.md` line to
+   `awaiting human checkpoint (step N/M)` (step 5), then commit the task state and
+   **push the branch, best-effort**, as **one composite invocation** (§Turn economy).
+   This commit and step 4's OK-side twin are **yours, anchored to your checkpoint
+   turns** — never delegated to a sub-agent's return path (a commit left to a
+   sub-agent may never land, and the checkpoint is then invisible to a cold
+   `/resume`):
 
    ```bash
    git add .claude/state/tasks/<id>/ && \
-     git commit -m "step(<id>): step <N> awaiting checkpoint"
-   git push   # best-effort — a failure warns, never blocks
+     git commit -m "step(<id>): step <N> awaiting checkpoint" \
+       -- .claude/state/tasks/<id>/; \
+     git push   # best-effort — a failure warns, never blocks
    ```
 
-   The commit carries the `progress.md` `awaiting human checkpoint (step N/M)`
-   sub-state; a failed push — offline, auth — prints a warning and never blocks the
-   checkpoint; the work stays safe locally and the next push carries it.
-   This is the long human wait where a session is likeliest to die, so the push is
-   what lets another machine's `/resume` see the step and its pending checkpoint.
-   Then present the step: what was built, where to look, how to run it. Three
-   answers:
-   - **OK** → emit `step_completed` (below), next task.
+   The commit's pathspec keeps it honest: anything else already staged (e.g. a
+   human edit staged ahead of the checkpoint) stays staged instead of riding
+   mislabeled into the state commit.
+
+   A failed push — offline, auth — warns and never blocks; the next push carries
+   it. This long wait is where a session likeliest dies — the push is what lets
+   another machine's `/resume` see the pending checkpoint.
+   **Pre-commit review ON skips this state commit and push entirely** — until the
+   OK the branch receives _nothing_, state included (§Pre-commit review ON): update
+   the `progress.md` line on disk only, accepting the documented price that the
+   pending checkpoint is invisible to a cold `/resume` from another machine.
+   Then present the step **per §Checkpoint contract**: what was built and how to
+   run it, the group's commits and touched files, the anchored group diff, the
+   richer-view offer, and the human-delta check. Three answers:
+   - **OK** → emit `step_completed` (below), next group.
    - **Changes** (with feedback) → fresh Implementer with the feedback → per-step
      review again (step 2; the review-iteration count resets) → checkpoint again.
      Human-requested changes go through review like any other fix — **nothing reaches
@@ -302,13 +508,25 @@ order:
      (`Mode: step-by-step (downgraded to all-at-once at step N)` — the gate choice
      stays first; the downgrade is a suffix, because `task_done.mode` records the gate
      choice), and run the **remaining** tasks as a single Implementer invocation
-     (today's mode). Checkpoint OKs already given stand.
+     (all-at-once; the pre-commit review knob keeps its recorded setting).
+     Checkpoint OKs already given stand.
 
    Aborting needs no protocol: the human interrupts the session; `/resume` picks the
    step sub-state back up from `progress.md`.
 
 4. **Telemetry** — every **resolved checkpoint** emits one event (so a step the human
-   sent back emits more than once, same `--step`). `<review-iterations>` is the number
+   sent back emits more than once, same `--step`); the emit, the step's resolved
+   `progress.md` line (step 5) and the resolution state commit (on OK, plain or
+   downgrade: `step(<id>): step <N> checkpoint OK`, carrying the same
+   `-- .claude/state/tasks/<id>/` pathspec as step 3's twin so other staged
+   content never rides mislabeled) + best-effort push ride as
+   **one composite turn** (§Turn economy) — without that commit a cold `/resume`
+   still reads `awaiting` after the last group. Pre-commit review ON: on OK the
+   same composite additionally carries the group's **code commit** — the deferral
+   ends here, so code commit + state commit + push + emit land together (exact
+   commands, the pathspec split of the mixed index, and the all-at-once no-emit
+   rule in §Pre-commit review ON); on
+   `changes` nothing is committed and the deferral continues. `<review-iterations>` is the number
    of Reviewer invocations that preceded this checkpoint (≥ 1; resets after a
    "changes"):
 
@@ -325,7 +543,8 @@ order:
    **Attribution — name the component the checkpoint friction is about, or
    omit.** The two `--attributed-*` flags are **optional**; they're meaningful when
    the checkpoint surfaced friction (`changes`, or repeated `review-iterations`) and
-   you can name what produced it — usually the Implementer. **Omit both on a clean
+   you can name what produced it — usually the Implementer; a ledger retry is the
+   Reviewer's own. **Omit both on a clean
    `ok` checkpoint or when you can't confidently attribute** (a wrong guess pollutes
    the signal). Use the **exact** name from this roster so the data aggregates:
 
@@ -337,35 +556,226 @@ order:
      `cli-e2e`, `bash-hooks`)
 
    Per-step Reviewer REJECTs also emit `review_rejected` as usual, with the extra
-   `--step=<N>` flag (the `iteration` count stays task-global, as today).
+   `--step=<N>` flag (the `iteration` count stays task-global, as today; an
+   all-at-once single-group pass — pre-commit review ON's pre-gate review —
+   omits `--step`, per the events schema).
 
 5. **`progress.md` step log** — keep the sub-state explicit so `/resume` can re-enter
    mid-loop. Under a `## Step log` heading, one line per resolved step; the **open**
    step's line is transient — update it in place as the loop progresses
    (`fix-loop iteration K — in progress` while implementing/reviewing,
-   `awaiting human checkpoint (step N/M)` while waiting on the human), then replace it
-   with the resolved outcome:
+   `awaiting ledger retry (step N/M, retry 1/1)` while the fresh Reviewer redoes a red
+   ledger, `awaiting human checkpoint (step N/M)` while waiting on the human), then
+   replace it with the resolved outcome:
 
    ```markdown
    Mode: step-by-step
 
    ## Step log
 
-   - step 1/6 — review ×1 → checkpoint: OK
-   - step 2/6 — review ×3 (2 rejects: missing error path; flaky spec) → checkpoint: changes → review ×1 → checkpoint: OK
-   - step 3/6 — awaiting human checkpoint (step 3/6)
+   - step 1/6 (anchor a1b2c3d) — review ×1 → checkpoint: OK
+   - step 2/6 (anchor e4f5a6b) — review ×3 (2 rejects: missing error path; flaky spec) → checkpoint: changes → review ×1 → checkpoint: OK
+   - step 3/6 (anchor c7d8e9f) — review ×2 (ledger retry ×1) — ledger: criteria 3/3 (basis: requirements), gates 2/2 (basis: config) → checkpoint: OK
+   - step 4/6 (anchor f1a2b3c) — awaiting human checkpoint (step 4/6)
    ```
 
-   Those two transient sub-state strings are exactly what a later `/resume` re-enters
+   Those transient sub-state strings are exactly what a later `/resume` re-enters
    on: the awaiting line re-presents the pending checkpoint, the fix-loop line
-   re-enters the implement→review loop at that iteration.
+   re-enters the implement→review loop at that iteration, and the ledger-retry line
+   says the single retry is already spent. The `(anchor <oid>)`
+   field is the OID step 1 recorded — the checkpoint contract and the per-step
+   Reviewer diff against it.
 
-After the **last task**, rejoin the normal flow unchanged (L1 step 8): flip to
+After the **last group**, rejoin the normal flow unchanged (L1 step 8): flip to
 `in-review`, open the PR, and run the **full-pass Reviewer** over everything against
-the spec. The full-pass may reject anything, **including human-OK'd tasks** — a
+the spec. The full-pass may reject anything, **including human-OK'd steps** — a
 checkpoint OK means "right direction and it runs", not a review waiver; the full-pass
 wins, and the human still holds the merge gate to disagree.
 
+**Every full-pass APPROVE is ledger-validated too** — the step-8 review in either mode,
+pre-commit review ON's single-group pre-gate pass, and a re-APPROVE after the merge gate
+or PR comments sent the PR back to review. The Reviewer writes `full-pass.json` (no step
+number → the union of every group); you run
+`lemony review-ledger validate --task-id=<id> --anchor=<merge-base> --full-pass` —
+the merge-base of the freshly fetched base and the PR head, the Diff-fingerprint's
+own OID (L1 step 8; pre-commit review ON's pre-gate pass instead anchors at the OID
+you recorded when its single group started) — and route a red exactly as
+in step 2 above: one fresh Reviewer retry with the lines verbatim, a second red or any
+spec-side problem to the human, and never an APPROVE relayed on a red ledger. Outside
+the step loop the transient line is `awaiting ledger retry (full pass, retry 1/1)` in
+`progress.md` (no step counter), and "the human" is the gate the pass feeds: the
+pre-commit-ON checkpoint when there is one, otherwise the merge-gate presentation,
+with the verb's lines as the content.
+
+## Checkpoint contract (how a human gate presents work)
+
+Every human checkpoint — per-group in step-by-step, and the single all-at-once gate
+when pre-commit review is ON — presents the same way. "Present the step" is a
+contract, not a vibe:
+
+1. **Anchored scope.** The group's **anchor** — the branch head OID recorded when
+   the group started (= the end of the previous approved group; the head at
+   implementation start when no group has yet been approved — group 1, or an
+   all-at-once run; an all-at-once run that began as a mid-task downgrade anchors
+   at the head after the last OK'd group) — bounds exactly what is
+   under review. Present the commit list + touched-files table, then the **exact
+   group diff**, always excluding task state:
+   - OFF: `git log --oneline <anchor>..HEAD` +
+     `git diff --stat <anchor>..HEAD -- ':(exclude).claude/state'`,
+     then `git diff <anchor>..HEAD -- ':(exclude).claude/state'`;
+   - ON (nothing committed):
+     `git diff --stat <anchor> -- ':(exclude).claude/state'`, then
+     `git diff <anchor> -- ':(exclude).claude/state'` — staged new files are in
+     the index, so they appear.
+2. **The inline rendered diff is the universal floor.** Probe the environment: when
+   a difftool is configured (or an extension like GitLens is present), **offer**
+   the richer side-by-side view — an ephemeral config works without touching the
+   repo's (`git -c diff.tool=<tool> difftool <range>`). Never assume an extension
+   exists. In ON the Source Control panel already shows the work natively — it IS
+   uncommitted.
+3. **What was built and how to run it** — from the Implementer's verification line,
+   as today. Checkpoint narration is the product, never overhead (§Turn economy).
+4. **The human delta — always detected, always revalidated.** Whatever the answer
+   (`ok` or `changes: …`), first detect the human's own edits — in ON, **two
+   checks with distinct routes** (every agent save-point is staged at
+   presentation time, so the staged/unstaged seam is the auto-detect):
+   - **Work delta**: the unstaged section outside task state —
+     `git diff -- ':(exclude).claude/state'` **plus untracked files outside
+     `.claude/state`** (from `git status --porcelain`; `git diff` never shows a
+     file the human created). Your own disk-only `progress.md` edits sit
+     unstaged under `.claude/state` by design — agent noise, never a human
+     delta.
+   - **Spec check**: unstaged edits **or untracked files** under the spec —
+     `git diff -- .claude/state/tasks/<id>/spec/` plus the untracked (`??`)
+     porcelain entries
+     under that path (a human-created spec file is untracked and invisible to
+     the diff). A hit is **not** a work
+     delta: it changes the approved spec, so route it as a **discovery**
+     (§Discovery mediation) before the checkpoint resolves. The Spec Author —
+     the spec's owner — applies the resolution to the file (restoring it if the
+     human's interpretation is rejected), then **re-present this checkpoint**;
+     only after that may any commit run, so `git add -A` lands the resolved
+     spec, never an unconfirmed unstaged edit. **Mediated changes are staged on
+     arrival and never re-raise**: whenever a discovery resolution is applied
+     mid-task — the Spec Author's spec update, an Architect artifact — stage it
+     immediately (`git add` the touched paths). Resolved artifacts join the
+     agent-staged floor, so this check fires only on **unmediated** edits and
+     the re-presented checkpoint is clean; an unstaged edit that matches the
+     recorded `**Resolution**` in `discoveries.md` is confirmed content — stage
+     it, don't re-raise.
+
+   The **spec check runs in both knob states** — in OFF, run it **before** step
+   3's `awaiting` state commit, which would otherwise silently commit a
+   pre-existing spec edit before detection. OFF's work-delta detection is
+   simply any uncommitted working-tree change.
+   The **work delta** then runs the pipeline: present it, confirm it is
+   intended, and **re-run the suite with the delta applied** — the delta never
+   inherits the group's green. **A red revalidation blocks the OK**: never run
+   the commit composite on a red suite — re-present the failure and route it as
+   `changes` (the human decides: fix it themselves, drop the delta, or hand it
+   to the Implementer). On a green revalidation the delta rides with the group:
+   on OK it lands with
+   the group's work (ON: staged into the group's commit; OFF: committed as its
+   own commit — `step(<id>): step <N> human delta` — before the next group); on
+   `changes` it stays in the worktree for
+   the fresh Implementer (ON: staged first as the safe starting point —
+   §Pre-commit review ON).
+
+## Pre-commit review ON (zero commits + staging save-points)
+
+The knob's ON state (chosen at the approval gate — §Implementation mode) moves
+**when the branch first receives commits**; review, fix-loop routing, and the merge
+gate are unchanged. v1 is deliberately an experiment — the watch-fors below are its
+pre-registered exit signals.
+
+- **Zero commits; staging save-points.** The Implementer never commits: it stages
+  after every green task (`git add -A`) and **never stages mid-experiment** — the
+  staging protocol in `implementer.md`, which the spawn prompt must point at
+  explicitly (it inverts the tdd add-early reflex, and a fresh Implementer only
+  knows what the contract and the branch tell it). A failed experiment rolls back
+  with `git restore . && git clean -fd`: the worktree returns to the last green
+  save-point; staged content survives verbatim, including new files.
+- **Everything is deferred** until the human OK: no code commits and **no state
+  commits** either — the checkpoint's `awaiting` state commit + push do not run;
+  `progress.md` updates on disk only. The documented price, accepted at the
+  grill: **no multi-machine durability** during implementation and during the
+  checkpoint wait (the flow's longest, where a session likeliest dies) — a cold
+  `/resume` from another machine sees nothing pending. (One exception: a
+  discovery pause **is** visible cross-machine — its labels and issue comment
+  surface — but the full `discoveries.md` entry stays machine-local until an OK
+  lands it.) Same-machine resume reads the worktree as usual.
+- **The gate** runs at end of group (step-by-step) or end of everything
+  (all-at-once — after the Implementer signals done and **before** the
+  `in-review` flip: the PR never opens on uncommitted work). In all-at-once the
+  whole implementation is the **single group** and the per-group machinery
+  applies to it: the mid-implementation Reviewer runs over the anchored diff
+  **before** the gate — nothing reaches the human unreviewed, in either mode —
+  and the `changes` fix-loop carries the same 3-reject cap into an anticipated
+  checkpoint (whose `step_completed` clause and `step N/M` strings apply only
+  in step-by-step — in all-at-once the no-emit rule below wins and the awaiting
+  line drops the step counter). Its APPROVE is ledger-validated with `--full-pass`
+  and `--anchor=<oid>` — the anchor you recorded when its single group started
+  (§Step-by-step implementation, after the last group), never relayed on a red.
+  Hand that pre-gate Reviewer the anchor, the ON
+  flag, and "the whole `tasks.md` as the single group" in place of a group id.
+  All agent work is
+  staged at presentation time; present per §Checkpoint contract. The human
+  inspects the work natively in the Source Control panel and edits/discards
+  directly in the worktree; answers are `ok` / `changes: …` (step-by-step keeps
+  its third answer, OK-and-downgrade).
+- **OK ⇒ commit + push, after revalidating.** Re-run the suite over the final
+  worktree (human delta staged in) — the gate's green is fresh, never inherited.
+  Then the deferral ends as **one composite turn**, splitting the mixed index by
+  pathspec (`git add -A` staged code and task state together; a bare
+  `git commit` would swallow both into one commit):
+
+  ```bash
+  git add -A && \
+    { git diff --cached --quiet -- . ':(exclude).claude/state' || \
+      git commit -m "<code-msg>" -- . ':(exclude).claude/state'; } && \
+    { git diff --cached --quiet -- .claude/state || \
+      git commit -m "<state-msg>" -- .claude/state; }; \
+    git push   # best-effort — a failure warns, never blocks
+  ```
+
+  Each commit is **guarded on its half of the index holding changes**, so a
+  degenerate group no-ops that half instead of short-circuiting the other: a
+  state-only OK (an audit group whose artifact is progress notes, or a human who
+  discarded the work in the worktree and answered `ok`) still lands its state
+  commit — an unguarded `&&` chain would silently drop it while the push still
+  ran, leaving the resolution nowhere on the branch.
+
+  Step-by-step: `<code-msg>` = `step(<id>): step <N>`, `<state-msg>` =
+  `step(<id>): step <N> checkpoint OK`, and the `step_completed` emit rides the
+  same turn (step 4). All-at-once (a downgraded remainder resolves as
+  all-at-once here too): `<code-msg>` = `task(<id>): implementation`,
+  `<state-msg>` = `task(<id>): pre-commit gate OK`, and **nothing is emitted** —
+  `step_completed` is step-by-step-only (its `--step` has no meaning here, and
+  closeout's mode recovery reads any `step_completed` as proof of step-by-step);
+  the gate resolution reaches telemetry through `task_done` as usual. One commit
+  per group in v1; all-at-once commits the whole implementation as its single
+  group.
+
+- **Changes ⇒ the Implementer iterates over the worktree.** Same routing as any
+  rejection (fresh context, ≤3 rejects per step): it first **stages the
+  revalidated human delta** (its suite result rides in the feedback) as its
+  safe starting point, then continues
+  under the staging protocol. Nothing is committed; the deferral continues.
+- **Watch-fors — pre-registered failure signatures.** v1 tests in real use whether
+  the three roles of tdd commits (fresh-Implementer memory via the branch,
+  granular save-points, 1:1 per-task history) are missed. If one fires, don't
+  improvise: **surface it at the checkpoint and record it in `progress.md`** so
+  the human can decide the swap to the pre-designed fallback — _deferred push_
+  (local tdd commits exactly as today but unpublished; the OK becomes the push:
+  commit = internal memory, push = publication). The signatures:
+  1. **Fix-loop memory** — iteration 2 redoes or overwrites iteration 1's work.
+  2. **Save-point residual** — a mid-experiment `git add` silently destroyed the
+     save-point (`git status` looks identical; recovery yields nameless blobs),
+     or single-level undo proves insufficient (e.g. selectively reverting task
+     N−2).
+  3. **PR narrative** — one commit per group cannot reconstruct the per-task
+     `step(<id>): step <N>` story.
+
 ## Discovery mediation
 
 Any sub-agent (Spec Author, Implementer, Reviewer, Architect) may stop mid-task and
@@ -380,103 +790,15 @@ When you get that summary, run the **`resolve-discovery`** skill. It pauses the
 `paused_from`), has you arbitrate the question with the human, routes the artifact
 update to its owner (the agent that created it), records the resolution in
 `discoveries.md`, clears the discovery flag, restores the status, and re-invokes the
-paused sub-agent with the decision. You are the only one who talks to the human and
-moves labels — never let a sub-agent self-resolve.
-
-## Mid-task capture (`/spinoff` offer)
-
-While you (the hat) are driving the conversation — between sub-agent dispatches, at
-gates, in ordinary back-and-forth — the human will sometimes mention an **independent,
-non-blocking** defect: one the current task does **not** need to touch, and that doesn't
-have to be fixed now ("oh, the export button is also broken on Safari"). Don't let it
-evaporate and don't context-switch to it: **offer to spin it off**. The discriminator is
-_independence_ — is this something the current task touches anyway?
-
-This is distinct from three neighbours:
-
-- **Just fix it** — if the defect is **in scope for the current task** (something this
-  change already touches), fix it in the current PR. No offer, no stub — spinning off
-  in-scope trivia only pollutes the backlog.
-- **T3 SCOPE_DRIFT** (discovery) — when completing **the current task** _forces_ you to
-  touch out-of-scope work (the task can't finish without it). That pauses via
-  `resolve-discovery`. `/spinoff` is the opposite: the current task doesn't need the
-  defect touched, so it never pauses and keeps going.
-- **`/define`** — a feature _idea_, not a defect. Route those to DEFINE, not `/spinoff`.
-
-Calibration — **lean toward offering** so nothing slips, but keep it
-frictionless and noise-free:
-
-- Offer only when you'd bet it's a **genuine, independent defect worth a tracked issue**
-  — not for every stray observation, and not for anything you can fix in place. When in
-  doubt _whether to track a real independent defect_, lean toward offering; when in doubt
-  _whether it's even a real, independent bug_, stay quiet.
-- The offer is a **single line**, in the human's language: _"This looks like an
-  independent bug — want me to `/spinoff` it and keep going?"_ One tap to dismiss; if the
-  human says no, drop it and continue without comment.
-- **Never re-offer the same finding twice in a session.** "Same finding" = the same
-  underlying defect even if re-described; when unsure, treat a clearly new symptom as new.
-  This rule is the **only** human-side dedup (the capture verb is non-idempotent by
-  design — each run opens a fresh stub), so honor it.
-- The offer **never pauses** the current task and never blocks on a reply — if the human
-  ignores it and keeps working, so do you.
-
-On **accept**, capture it exactly as the `/spinoff` command does — the `spinoff` CLI
-verb via the launcher, with the **current task's id** as the parent (recover it the same
-way `/spinoff` does — from the `harness/<id>-…` branch or active task state; omit
-`--parent` if there is no active task):
-
-```bash
-.claude/hooks/lib/lemony.sh spinoff \
-  --title="<one-line symptom>" \
-  --body="<where it was seen; a code pointer if you have one>" \
-  --parent=<current task id> \
-  --severity=<low|medium|high|critical>
-```
-
-Stub creation is **fail-loud** (a non-zero exit means it did not open — surface it, don't
-pretend it was captured); the telemetry emit is **best-effort** (a `Warning:` means only
-the event failed, the stub stands). Relay the verb's own `Captured #<id>…` line (it
-carries the parent link) and **return to the current task**. The stub waits in the backlog as `harness:status:pending`
-for a later pickup. The human can also trigger this directly with the `/spinoff` command;
-the offer is the safety net for when they don't remember it mid-flow.
-
-### From a sub-agent (the side-finding channel)
-
-The same offer applies when the source is **not the human but a sub-agent's return
-summary**. A sub-agent runs in fresh context and cannot interrupt you, so when it spots a
-defect that is **independent of its task** (the task finished fine without touching it) it
-**notes it instead of pausing** — that is the `note-side-finding` skill, the non-pausing
-sibling of `raise-discovery`. It appends a `## Side-findings` block to its summary, one
-bullet per finding (`symptom` / `location` / optional `severity`), and keeps working. (A
-**blocking** defect is the opposite case — the sub-agent raises a T1–T6 discovery and
-stops; you handle that with `resolve-discovery`, above.)
-
-When you **read back a sub-agent's summary**, scan for a `## Side-findings` block. For each
-bullet, make the **same single-line `/spinoff` offer** as for a human-mentioned defect —
-pre-filled from the bullet (`--title` ← symptom, `--body` ← location, `--severity` ← the
-read if given), the active task as `--parent`. Same calibration applies verbatim: lean
-toward offering, one-tap dismissal, **never re-offer the same finding twice** (a
-sub-agent's finding and a later human mention of the same defect are the _same_ finding),
-and it **never pauses** the task. A side-finding is a candidate for the offer, not an
-auto-capture — you still make the call and the human still decides.
-
-A bullet tagged **`kind: drift`** is `docs/architecture.md` map staleness,
-not a code defect: add **`--kind=architecture-drift`** to the `/spinoff` so the stub carries
-the `harness:architecture-drift` routing label and a later pickup resolves it via the
-Architect's `update-architecture` (a targeted map-fix), not a code change. **Fallback:** if
-`update-architecture` is not installed (the project keeps no `architecture.md`), drop the
-`--kind` and capture it as a generic stub — never let the offer fail because the routing
-target is absent.
-
-Two things you own because the sub-agent can't: **(1) cross-round dedup.** A sub-agent
-re-invoked with fresh context (e.g. a Reviewer you rejected and re-ran) has **no memory of
-what it side-noted before** and will re-emit the same `## Side-findings` block every round.
-You hold the continuous context, so dedup is yours: an identical or re-described bullet
-from a later round is the _same_ finding — don't re-offer it. **(2) gate ordering.** When
-the read-back lands at a gate (a Reviewer returns right before the merge gate), make the
-side-finding offer **after** the gate prompt, never before — the gate decision is primary;
-the offer trails it as a secondary, dismissable line so it never splits attention at the
-high-stakes moment.
+paused sub-agent with the decision. A discovery can also be raised by **you** (e.g. a
+checkpoint "changes" request that contradicts the spec): the same skill runs, with
+nothing to re-invoke — the resolution re-enters the loop where it paused. You are the
+only one who talks to the human and
+moves labels — never let a sub-agent self-resolve. An **oversize** discovery — the Spec
+Author or the Implementer finds the scope hides ≥2 independently mergeable units the PRD
+didn't reveal — is a T2 raised and mediated exactly like this; when the human answers
+"partition", read `.claude/agents/partition.md` for the parent/part mechanics (the
+current task keeps the first unit).
 
 ## Architect (on-demand)
 
@@ -505,184 +827,98 @@ Dispatch it (fresh context, Task tool) when:
 - **Orientation is needed** — before a decision or spec in a large or unfamiliar
   codebase, dispatch it with `code-explorer` for a read-only map.
 - **Closeout — the Architect's reliable activation checkpoint** — the `task-closeout`
-  skill drives durable capture at the end of every task, in cold blood, where the
-  discretionary triggers otherwise lose to "unblock the paused sub-agent". Three
-  activations, **asymmetric by design**: `write-adr` (HITL
-  offer per resolved discovery — net-new canon, the human curates it), `update-architecture`
-  (**automatic** dispatch when `docs/architecture.md` exists — the map must _track reality_,
-  reviewed in the closeout PR diff, no pre-offer), and `playbook-iterate` (HITL offer once
-  per task — catches a reusable pattern no `T6` conflict already routed). Each no-ops when
-  its skill isn't installed. See §Closeout and `task-closeout`.
-
-Give it the context (the discovery entry + its resolution, the change, or the request)
-and read back its summary. The Architect is **not a gate** — it produces an artifact and
+  skill drives three durable-capture activations at the end of every task, in cold
+  blood, where the discretionary triggers otherwise lose to "unblock the paused
+  sub-agent". The full list and its asymmetry live in §Closeout.
+
+Give it the context — the branch when no PR exists yet, the `discoveries.md` entry
+by path with the decision (**in full** pre-record — `resolve-discovery` step 3 —
+its gist once recorded), the change or the human's request as a synthesized delta
+(§Sub-agent invocation) — and read back its summary. The Architect is **not a gate** — it produces an artifact and
 reports; it never moves the status machine. If it reports that the trigger didn't
 warrant the artifact (an ADR that fails the three tests, a change that isn't
 architecturally significant, a "playbook" change that's really project-specific), record
 that and move on — no artifact is forced.
 
-## UI design (DEFINE + REVIEW)
-
-UI design threads into an L1 task that touches UI — never a linear step. **The interactive
-design interview is yours**: a sub-agent can't talk to the human, so at DEFINE **you** run
-the `grill-ui` skill on your human-facing surface and author the `ui-handoff.md` contract.
-The **UI Designer** sub-agent — always installed, invoked **on-demand**, your only invoker —
-is your design **critic and QA**: at DEFINE it reviews the handoff you just authored (before
-the Spec Author runs); at REVIEW it runs a mechanical pre-pass (the deterministic
-`design-tokens` gates + the project's a11y tooling) then the `design-critique` and
-`a11y-audit` judgment lenses, and returns one design verdict. You own the human dialogue, the
-`ui-handoff.md` artifact, and the labels; it critiques and reports.
-
-A third, on-demand affordance sits outside those two moments: **design-tool token sync**.
-When the human runs `/sync-design-tokens` (or accepts the DEFINE offer when a drift check
-shows an export is pending), dispatch the UI Designer to run its `design-tool-sync` skill.
-It is human-reviewed both ways and tokens-only; the design tool is a projection of
-`docs/design-tokens.json`, never a peer source of truth.
-
-### Activation gate
-
-After the grill produces the PRD and the task issue exists, judge — **your own LLM
-call**, no runtime keyword scorer — whether this task needs design, as **two parts both
-true**:
-
-1. **The repo has a frontend** — there is UI to design (a SPA/app surface, components,
-   styles), not a pure library / CLI / backend.
-2. **This task touches UI** — the change adds or alters something a user sees or
-   interacts with.
-
-**Bias to include** on a borderline call: a wasted handoff stub is cheaper than UI
-shipped with no design pass. When both hold, the task needs design.
-
-### Design-stop offer
-
-When the gate fires, **put `harness:needs-design`** on the issue and offer the human,
-inline, in one line — three choices:
-
-> This task touches UI. (1) **Continue** — define the design now, as part of the spec;
-> (2) **Stop for handoff** — park here so a designer picks it up later; (3) **No UI after
-> all** — skip design.
-
-- **Continue** → **run `grill-ui` yourself** — the interactive design interview on your
-  human-facing surface — authoring `ui-handoff.md` under `tasks/<id>/spec/`. Then dispatch
-  the **UI Designer** (fresh context, Task tool) with the `<id>` and branch to **critique**
-  the handoff, and resolve its findings before the Spec Author runs. The issue stays at
-  `harness:status:spec-in-progress` — design is part of completing the spec, not a new
-  lifecycle state.
-- **Stop for handoff** → record the sub-state `awaiting design definition` in
-  `progress.md`, commit and push the task state to the branch, and stop. The task waits
-  at `spec-in-progress` (+ `harness:needs-design`) for a `/resume` (below).
-- **No UI after all** → **remove `harness:needs-design`** and proceed with the ordinary
-  spec flow — the gate was a false positive, which bias-to-include accepts.
-
-### Persisting personas (offer)
-
-`docs/personas.md` is **client-owned** — the harness consumes it, never imposes it. When your
-`grill-ui` interview captured personas **inline** because `docs/personas.md` was **absent** (§1
-of the handoff), make the offer — a human-facing choice, so it is yours:
-
-> The design defined these personas inline. Persist them to `docs/personas.md` so future UI
-> tasks reuse them? (yes / no)
-
-- **Yes** → write a minimal `docs/personas.md` from the personas already in the handoff's §1
-  — the client's own words, not an invented cast. Then continue toward spec-ready.
-- **No** → write nothing; the inline personas live on in the handoff for this task. The next
-  UI task simply asks again.
-
-Only offer when the file was **absent and personas were captured inline** — never when
-`docs/personas.md` already exists (it was consumed, nothing to persist) and never unasked.
-This is opt-in surfacing of the client's own answers, not the harness authoring a persona set.
-
-### Design-tokens & design-tool on-ramp (offer)
-
-`docs/design-tokens.json` and a design-tool connection are **client-owned inputs** — consumed if
-present, never imposed. A repo adopting the harness fresh has neither, and silence there is a dead
-end. So when your `grill-ui` interview finds **either absent**, surface it as an opt-in offer (a
-human-facing choice, so it is yours) rather than only an open question:
-
-- **No `docs/design-tokens.json`** → offer to **scaffold** a starter token set derived from the
-  direction the interview just settled (the client's own colours/type/spacing, not a vendor
-  template), plus an opt-in follow-up to generate a sensible starter set for the aspects the
-  interview didn't cover. On **yes**, write the file and run `lemony design-tokens validate` before
-  closing; on **no**, capture it as an open question.
-- **No `com.lemony.design-tool` binding** → offer to **connect a design tool** (write the binding +
-  first import via the UI Designer's `design-tool-sync` skill / `/sync-design-tokens`), or **stay
-  pure-code**. Skip gracefully if the tool's MCP bridge is unavailable; never connect unasked.
-
-The mechanics live in the `grill-ui` skill; you run the offers on your human-facing surface. Only
-offer when the input is **absent** — never re-offer a token file or binding that already exists.
-
-### Label put/remove
-
-`harness:needs-design` is an **orthogonal presence flag** (same family as
-`harness:architecture-drift`), never a status:
-
-- **Put** it as soon as the gate classifies the task as touching UI and design is not
-  yet complete.
-- **Remove** it the moment `ui-handoff.md` is **complete** — at or before the flip to
-  `harness:status:spec-ready`. **Complete** = the handoff carries **this task's** design
-  decisions (its sections hold real content, not the verbatim placeholder template), the UI
-  Designer's critique **passed** (or you resolved its findings), and **no** open design fork
-  remains (an open fork means design is still open — keep the label and resolve it first).
-  Ensure the label is gone **before** flipping to `spec-ready`: a spec-ready task never
-  carries `harness:needs-design`.
-
-### `awaiting design definition` sub-state + /resume re-entry
-
-A task parked at "stop for handoff" sits at `harness:status:spec-in-progress` with
-`progress.md` recording the sub-state `awaiting design definition`. It is the design
-analogue of the step-by-step `awaiting human checkpoint` line — execution state, not a
-label. `/resume <id>` re-enters there: check out the branch, read the captured context,
-resume the `grill-ui` interview yourself to finish `ui-handoff.md`, dispatch the UI Designer
-to critique it, then remove `harness:needs-design` and continue toward spec-ready. The resume
-queue surfaces the parked design (`resume.md` lists `spec-in-progress` too).
-
-### REVIEW — the design lens
-
-When an implemented UI change reaches review (L1 step 8), invoke the **UI Designer** as
-a **distinct lens** alongside the Reviewer (code). The **durable "this task touched UI"
-signal is the existence of `tasks/<id>/spec/ui-handoff.md`** — `harness:needs-design` is
-already gone by spec-ready, so it can't be the cue; the handoff artifact persists and
-survives a cold `/resume`, so it is what to check. Either lens rejecting routes back to
-the Implementer (rejection is transient — no dedicated label); both passing reaches the
-single human merge gate (two inputs, one gate).
-
-The UI Designer's lens mirrors the Reviewer's own shape — a **mechanical pre-pass** (the
-deterministic `design-tokens validate` + `design-tokens contrast` gates, plus the
-project's a11y tooling), then **judgment** (`design-critique` + `a11y-audit`), returning
-**one design verdict** with findings grouped by source (tokens / accessibility / craft).
-The Reviewer's code lens stays design-unaware; you still see exactly two review inputs.
-
-**Deterministic vs judgment, by level.** The two deterministic gates are cheap, agent-free
-facts, so they run **per-step** on UI-touching steps in step-by-step mode (a bad contrast
-in step 2 must not ride to step 6 — see §Step-by-step implementation); the project's a11y
-lint rides the per-step lint the same way. The **judgment lenses run full-pass only** —
-design is holistic, and a mid-component critique is noise. There is no per-step design
-agent and no new cap: a full-pass design rejection routes back like any other rejection.
-(`design-tokens validate` / `contrast` also run in CI independently of review.)
-
-### Closeout
-
-`ui-handoff.md` lives in `tasks/<id>/spec/`, so closeout archives it with the rest of
-the spec (`task-closeout` `git mv`s the whole `spec/` into `_archive/<id>/`) — no
-special handling.
-
 ## Merge gate (`in-review → merged`)
 
 When the Reviewer approves, **do not merge automatically.** Merging the PR is the one
-action that touches the default branch — it may trigger CI and deploys — so it stays a
-human decision. Surface it and wait:
+action that touches the default branch, so it stays a human decision. Surface it and
+wait:
 
 > Reviewed and approved — PR #<pr> is here: <url>.
-> (1) merge it yourself, (2) I'll merge it (`gh pr merge`), or
+> (1) merge it yourself, (2) I'll merge it once checks are green (`gh pr merge`), or
 > (3) run `/review-pr` first for a curated inline pass.
 
-The task stays at `harness:status:in-review` while it waits — there is no
-"approved-awaiting-merge" rung between review and merge (the `closeout-pending` status is
+A **stacked partition child** reaches this gate only once its PR base is the default
+branch — check `baseRefName` first and retarget/merge-in per `.claude/agents/partition.md`;
+never merge a part into a sibling's branch. The task stays at `harness:status:in-review`
+while it waits — there is no "approved-awaiting-merge" rung between review and merge (the `closeout-pending` status is
 **post**-merge, for a parked closeout record PR — not this gate). When the
 human merges (in the GitHub UI, by CLI, or by authorizing you to run `gh pr merge`),
 proceed to closeout. **GitHub is the source of truth for the merge, not this
 conversation** — closeout confirms it via `gh pr view`.
 
+### Executing an authorized merge — the checks precondition
+
+"Merge it" is a **conditional authorization**: the agent merges _when it is safe to do
+so_, not an order to execute immediately. The human's yes carries the implicit
+assumption that CI is fine; this contract makes that assumption an explicit
+precondition. Not green ⇒ you never merge on your own — you re-present this gate with
+the real state. (The failure pattern this kills: nobody _decided_ to merge on red — an
+authorization whose background assumption was false got executed without looking.)
+
+So never run a bare `gh pr merge`. Execute the merge through the shared executor, which
+verifies the check status the platform reports for the PR and waits — bounded — for
+pending checks (`merge.checks_timeout_secs` in `harness.config.yml`, default ~10 min).
+For a task PR, always pass `--approve-issue` with the task's issue number — that arms
+the **stale-approve guard**: the executor reads the Reviewer's APPROVE record
+(`Reviewed-tree` / `Diff-fingerprint`) from that issue and refuses to merge content
+that no longer matches what the APPROVE reviewed (a clean update-branch stays valid;
+any content change does not):
+
+```bash
+.claude/hooks/lib/merge-pr.sh <pr> --approve-issue <issue> --squash   # merge-strategy flags pass through to `gh pr merge`
+```
+
+Act on its exit code:
+
+- **0 — merged.** Proceed to closeout.
+- **10 — checks red.** Never merge on red by omission. Re-present the gate with the
+  failure: "checks red: <check> fails — merge anyway / wait / want to look at it?".
+  Merging on red stays possible, but only as the human's informed decision — on that
+  explicit yes, re-run with `--force`.
+- **30 — still pending after the bound.** The authorization never expires silently; it
+  expires by asking: "checks still running after <N> min — keep waiting, or leave it
+  and I'll tell you when they settle?". "Keep waiting" = re-run the executor (a fresh
+  bound, or a longer one via `--timeout-secs <secs>`).
+- **40 — stale approve: the PR content changed after the review.** A push landed in
+  the merge-gate window (another dev, a re-invoked implementer) and the diff no longer
+  matches what the APPROVE reviewed. Never merge it on the old verdict: route the PR
+  back to the Reviewer — the same back-to-review route as the comments path below; a
+  fresh APPROVE re-records the hashes — then re-surface this gate. Merging anyway
+  stays possible, but only as the human's informed decision — on that explicit yes,
+  re-run with `--force` (which skips the checks precondition too: make sure the
+  informed yes covers both).
+- **20 — no checks reported (after the grace window).** Never merge alone, whatever the
+  cause — repo with no CI, CI outage, path filters: don't try to auto-classify. Ask:
+  "I saw no checks available on this PR — merge?". If the human's answer is standing
+  ("this repo has no CI — merge without checks"), record it **now** as
+  `merge.allow_no_checks: true` in `harness.config.yml` (the executor reads the working
+  tree, so no later merge — including this task's closeout — re-asks); the line lands
+  on the base with the closeout record PR's commit, never a direct push. For the merge
+  at hand, re-run with `--force`.
+- **1 (or any other non-zero)** — not merged, and **not a verdict**: either the check
+  status could not be read (`gh`/auth/network failure — the precondition is
+  unverifiable, which is _not_ the same as "checks failed") or the merge attempt itself
+  was rejected (branch protection wants approval, a conflict, a bad ref). The
+  executor's stderr says which — surface that, verbatim, at the gate.
+
+The precondition is platform-neutral by design — "the merge executor verifies the check
+status the platform reports for the PR"; `gh` is the GitHub rendering of it. Branch
+protection is the user's belt: the harness executes merges and cannot assume it is
+configured, so the executor carries its own precondition either way.
+
 ### When the human leaves review comments instead of merging
 
 The human may respond at this gate not by merging but by **leaving comments on the PR**.
@@ -697,7 +933,14 @@ of an `in-review` task surfaces the open PR's comments and routes here — see
    route as a Reviewer rejection: re-invoke the Implementer sub-agent (fresh context)
    with the feedback (transient, no dedicated label). Skip pure acknowledgements or
    questions that need no code.
-3. **After the fix commit, draft — do not auto-post — the replies.** Compose a short
+3. **Route the fixed PR to re-review.** The fix commits are new, unreviewed content —
+   the Reviewer's standing APPROVE no longer covers them (and the executor's
+   stale-approve guard would refuse the merge with exit 40 anyway). Invoke the
+   Reviewer on the updated PR (continued re-review of its own findings when the
+   comments echo them; fresh otherwise); an approving verdict posts a fresh APPROVE
+   with fresh hashes. A reject routes back to step 2 — never draft "done" replies on
+   work that hasn't re-passed review.
+4. **After the re-APPROVE, draft — do not auto-post — the replies.** Compose a short
    "done ✅" reply threading each addressed comment, then **offer to post them with one
    confirmation**. Posting a reply inside someone's review thread is outward-facing and
    notifies the reviewer, so it is a **HITL gate, never automatic**. On approval, post
@@ -706,7 +949,7 @@ of an `in-review` task surfaces the open PR's comments and routes here — see
    identity it uses for issues, PRs, and merges; there is no separate bot identity). The
    fix commit is visible on the PR regardless, so declining only skips the
    acknowledgement, not the fix.
-4. **Re-surface the merge gate** above.
+5. **Re-surface the merge gate** above.
 
 ## Closeout
 
@@ -715,26 +958,36 @@ GitHub — `gh pr view <pr> --json state,mergedAt` reports `MERGED`, regardless
 was merged). Closeout **archives, it does not delete, and it records via a dedicated PR**:
 it raises durable decisions to ADRs, `git mv`s the spec + `discoveries.md`
 into `.claude/state/tasks/_archive/<id>/`, drops only `progress.md`, and lands the
-`history.md` append + the archival on a `harness/closeout-<id>` PR merged with
-`gh pr merge` `--auto`. Nothing is pushed direct to the base — the closeout record obeys
-the same branch isolation as every other change. The skill owns the full mechanics.
-
-**Closeout splits into two phases** because `--auto` defers to branch protection. If the
-closeout PR self-merges (protection is PR + checks only), closeout finalizes in one go. If
-protection requires human approval — **or auto-merge is disabled repo-wide, which makes
-`--auto` error rather than queue** — the PR waits: flip the issue to
-`harness:status:closeout-pending`, tell the human the record PR is open, and stop. A later
-`/resume` of a `closeout-pending` task finalizes once that PR is merged (see Dispatch →
-RESUME).
+`history.md` append + the archival on a `harness/closeout-<id>` PR self-merged through
+the same checks-precondition executor as the merge gate (`.claude/hooks/lib/merge-pr.sh`
+— **the executor never self-merges on anything but green**; no standing human
+authorization exists on this path, so every not-green outcome takes one of the skill's
+exits — self-fix, park, or a human's informed decision — never an autonomous merge).
+Nothing is pushed direct to the base — the
+closeout record obeys the same branch isolation as every other change. The skill owns
+the full mechanics, including what to do on red, absent, or still-pending checks. A
+task that is a **part of a partition** (its body carries `Part <k> of #<parent>`) also,
+at finalize, ticks its row in the parent's checklist and — on the last part — closes the
+parent with a summary comment; the skill's finalize step owns it (mechanics in
+`.claude/agents/partition.md`).
+
+**Closeout splits into two phases** because the self-merge only happens on green. If the
+closeout PR's checks pass within the bound (and branch protection asks nothing more),
+closeout finalizes in one go. Otherwise — checks red (and not self-fixable), no checks
+and no standing answer, timeout, or protection requiring human approval — the PR waits:
+flip the issue to `harness:status:closeout-pending`, tell the human the record PR is
+open and why it didn't merge, and stop. A later `/resume` of a `closeout-pending` task
+finalizes once that PR is merged (see Dispatch → RESUME).
 
 **Closeout is the Architect's reliable activation point**: before
 archiving, the skill drives three durable-capture activations, **asymmetric by design** —
 `write-adr` (HITL offer per resolved discovery), `update-architecture` (**automatic**
-dispatch with the merged diff when `docs/architecture.md` exists — no pre-offer, the map
+dispatch when `docs/architecture.md` exists, handing the PR and the `spec/design.md`
+path (the Architect reads the merged diff itself) — no pre-offer, the map
 tracks reality and the edit is reviewed in the closeout PR), and `playbook-iterate` (HITL
 offer once per task, for a reusable pattern no `T6` conflict already routed). Closeout
 never drafts the artifact itself — it lights up the Architect, who owns the criteria
-(§Architect on-demand). Each activation no-ops when its skill isn't installed.
+(§Architect). Each activation no-ops when its skill isn't installed.
 
 Before any of this, enforce the discovery invariant: **no `discoveries.md` entry may lack
 a resolved `**Resolution**`block, and no`harness:discovery:\*` label may remain.** An
@@ -767,29 +1020,33 @@ When the gate choice was step-by-step, also pass `--steps` (the count of
 ## Sub-agent invocation
 
 Each sub-agent runs with **fresh context** (a Task-tool invocation), not the hat's
-accumulated conversation. Give it the issue link, the relevant task-state paths, and
-the skill to run. Read back its returned summary; you own the human dialogue, the
-approval gate, and the label lifecycle.
-
-## L2 lightweight round-trip (TRIAGE)
-
-For small bugs that don't earn the full SDD ceremony. They skip the spec and its gate,
-but the branch, PR, and merge gate are the same — no path auto-merges:
-
-1. **Triage** — invoke the `triage-issue` skill: investigate the codebase, find the
-   root cause, draft a TDD-based fix plan, and create the issue with `harness:managed`
-   (no `harness:sdd` — its absence is what marks the lightweight path). Minimize
-   questions. Record the number `<id>`.
-2. **Branch + scaffold** — create the task branch `harness/<id>-<slug>` off the default
-   branch, then scaffold `.claude/state/tasks/<id>/progress.md` on it. Nothing touches
-   the default branch until the merge gate.
-3. **Implement** — invoke the **Implementer** sub-agent with the `tdd` skill. All work
-   lives on the branch.
-4. **Review** — flip to `harness:status:in-review`, **open the PR** (`gh pr create`,
-   with `Closes #<id>` in the PR body so the provider auto-links and closes the issue on
-   merge), and invoke the **Reviewer** sub-agent with the
-   `senior-review` skill (fresh context). On rejection, route back; on approval, go to
-   the merge gate.
-5. **Merge gate** — the same human-explicit gate as L1: never auto-merge. Surface the
-   PR and wait.
-6. **Closeout** — run the `task-closeout` skill (merge confirmed via `gh`), as above.
+accumulated conversation. Read back its returned summary; you own the human dialogue,
+the approval gate, and the label lifecycle. When a summary carries a
+`## Side-findings` block, read `.claude/agents/spinoff.md` and run its offer —
+after any gate prompt the read-back lands on, never before.
+
+**Spawn prompts go by reference, never by quotation.** The prompt carries the issue
+link, the relevant task-state and spec **paths**, the skill to run — plus, in
+step-by-step mode, the group id and its header line — and a short **synthesized
+delta**: only what exists nowhere on disk (reject feedback being addressed, the
+one-line gist of a **recorded** discovery resolution — the full entry lives in
+`discoveries.md`, reference it; pre-record, `resolve-discovery` step 3 routes the
+owner with the decision **stated in full** — or a human instruction from this
+conversation). Never paste spec
+content (`requirements.md` / `design.md` / `tasks.md` text) into the prompt — the
+sub-agent reads those files itself from the paths, always fresher than a quotation.
+One exception is never trimmed: when the delta **is** the payload (a REJECT's
+findings), route the reviewer's full findings verbatim. Scope: this rule binds the
+task loop's role sub-agents; a user-invoked analysis flow (e.g. a PR-review
+command spawning a stateless analysis agent) follows its own skill's prompt shape.
+
+## Turn economy
+
+Latency is paid **per turn**, not per command: run mechanical sequences whose
+intermediate output needs no judgment as **one composite invocation**, and batch
+independent read-only lookups in **one parallel turn**. The step-by-step checkpoint
+is the canonical case (single chained commit+push; post-resolution, the resolved
+step line + state commit + emit ride together). Never compact across a judgment point — reading a
+summary, arbitrating a gate, classifying a discovery each deserve their own turn.
+Checkpoint **narration** is exempt from all dieting: the gate presentation to the
+human is the product, never overhead.