@lemoncode/lemony 0.5.0 → 0.6.0

package/README.md

@@ -128,24 +128,25 @@ directly; the Orchestrator and sub-agents do, gated by your repo's capabilities.
 
 ## Commands
 
-The CLI ships 13 verbs. Run `lemony <command> --help` (or `-h`) for usage;
+The CLI ships 14 verbs. Run `lemony <command> --help` (or `-h`) for usage;
 `lemony version` (or `--version` / `-v`) prints the installed version.
 
-| Command         | What it does                                                                                                                            | Key flags                                                                                        |
-| --------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `install`       | Install into a fresh repo, or reconcile a pre-existing `.claude/`.                                                                      | `--target=<claude-code>` `--task-storage-repo=<owner/name>` `--on-conflict=<vendor\|client>`     |
-| `update`        | Move the install to the CLI's catalog version (3-way merge).                                                                            | `--on-conflict=<vendor\|client>` `--dry-run`                                                     |
-| `repair`        | Re-sync at the **pinned** version (restore missing files, never clobber edits).                                                         | `--dry-run`                                                                                      |
-| `rollback`      | Restore a pre-change snapshot (offline).                                                                                                | `--to=<version>` `--list` `--cleanup` `--force`                                                  |
-| `uninstall`     | Remove vendor-managed files (keeps your docs, state, adopted skills).                                                                   | `--labels`                                                                                       |
-| `doctor`        | Diagnose the installation (read-only); proposes `repair`.                                                                               | —                                                                                                |
-| `status`        | Show installed version, branch drift, and open tasks.                                                                                   | —                                                                                                |
-| `emit`          | Append a telemetry event to `.claude/state/events.jsonl`.                                                                               | `<type> [--key=value …]`                                                                         |
-| `discovery`     | Reflect a raised/resolved discovery onto its issue (label flip; `pause` also comments).                                                 | `<pause\|resume>` `--task-id=<id>` `--tier=<T1..T6>` `--status=<…>` `--note=<text>`              |
-| `design-tokens` | Validate the design-token file, check WCAG contrast, or sync with a design tool (consume-if-exists).                                    | `<validate\|contrast\|import\|export>` `--scan=<dir>` `--from=<file>` `--apply` `--only=<paths>` |
-| `review-ledger` | Validate the Reviewer's evidence-ledger sidecar against the spec, the anchored diff and the declared gates (deterministic, agent-free). | `validate` `--task-id=<id>` `--anchor=<oid>` `--step=<N>` `--full-pass`                          |
-| `spinoff`       | Capture a non-blocking defect found mid-task as a pending stub.                                                                         | `--title=<text>` `--body=<text>` `--parent=<id>` `--severity=<…>` `--kind=<…>`                   |
-| `telemetry`     | Inspect or control the local anonymous telemetry.                                                                                       | `status` `show` `flush` `enable` `disable [--purge-local]`                                       |
+| Command         | What it does                                                                                                                            | Key flags                                                                                                       |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `install`       | Install into a fresh repo, or reconcile a pre-existing `.claude/`.                                                                      | `--target=<claude-code>` `--task-storage-repo=<owner/name>` `--on-conflict=<vendor\|client>`                    |
+| `update`        | Move the install to the CLI's catalog version (3-way merge).                                                                            | `--on-conflict=<vendor\|client>` `--dry-run`                                                                    |
+| `repair`        | Re-sync at the **pinned** version (restore missing files, never clobber edits).                                                         | `--dry-run`                                                                                                     |
+| `rollback`      | Restore a pre-change snapshot (offline).                                                                                                | `--to=<version>` `--list` `--cleanup` `--force`                                                                 |
+| `uninstall`     | Remove vendor-managed files (keeps your docs, state, adopted skills).                                                                   | `--labels`                                                                                                      |
+| `doctor`        | Diagnose the installation (read-only); proposes `repair`.                                                                               | —                                                                                                               |
+| `status`        | Show installed version, branch drift, and open tasks (`--local`: no network call).                                                      | `--local`                                                                                                       |
+| `emit`          | Append a telemetry event to `.claude/state/events.jsonl`.                                                                               | `<type> [--key=value …]`                                                                                        |
+| `discovery`     | Reflect a raised/resolved discovery onto its issue (label flip; `pause` also comments).                                                 | `<pause\|resume>` `--task-id=<id>` `--tier=<T1..T6>` `--status=<…>` `--note=<text>`                             |
+| `checkpoint`    | Resolve a human checkpoint answer: commits, push and the `step_completed` emit in one call (used by the Orchestrator).                  | `<ok\|changes\|ok_downgrade>` `--task-id=<id>` `--auto-commit=<on\|off>` `--step=<N>` `--review-iterations=<K>` |
+| `design-tokens` | Validate the design-token file, check WCAG contrast, or sync with a design tool (consume-if-exists).                                    | `<validate\|contrast\|import\|export>` `--scan=<dir>` `--from=<file>` `--apply` `--only=<paths>`                |
+| `review-ledger` | Validate the Reviewer's evidence-ledger sidecar against the spec, the anchored diff and the declared gates (deterministic, agent-free). | `validate` `--task-id=<id>` `--anchor=<oid>` `--step=<N>` `--full-pass`                                         |
+| `spinoff`       | Capture a non-blocking defect found mid-task as a pending stub.                                                                         | `--title=<text>` `--body=<text>` `--parent=<id>` `--severity=<…>` `--kind=<…>`                                  |
+| `telemetry`     | Inspect or control the local anonymous telemetry.                                                                                       | `status` `show` `flush` `enable` `disable [--purge-local]`                                                      |
 
 The harness keeps a **committed baseline** under `.claude/.harness/baseline/<version>/` — a
 verbatim copy of every installed vendor file at the pinned version — so `update` is a true

package/catalog/VERSION

@@ -1 +1 @@
-0.5.0
+0.6.0

package/catalog/agents/implementer.md

@@ -125,6 +125,31 @@ what you run, only how many calls carry it.
    a deviation from the spec, or a side-finding is always stated, however long the
    list.
 
+## Hand probes (breaking source on purpose)
+
+When you deliberately mutate source to confirm a test catches it — because your
+invocation asks for it, or your own judgment does — the probe is **one shell command
+whose restore is a trap installed before the mutation**, never separate edit / test /
+revert calls:
+
+```bash
+( trap 'mv -f src/queue.ts.bak src/queue.ts 2>/dev/null' EXIT; \
+  trap 'kill $! 2>/dev/null; exit 130' INT TERM HUP; \
+  sed -i.bak '128s/>=/>/' src/queue.ts; \
+  npx vitest run src/queue.spec.ts & wait $! )
+```
+
+The session can stop at any instant — a human's Esc stops your running command
+with SIGTERM and follows it with a SIGKILL within a second or two. The test runs
+in the background under `wait`, so the signal ends the wait at once and the traps
+restore before the SIGKILL lands (a foreground runner would hold every trap until
+it exits). A mutant stranded between
+the edit and a hand revert survives the session boundary as a deliberately wrong
+line, and under auto-commit OFF nothing tells it apart from work in progress (the
+`mutation-testing` skill carries the same recipe). After the trip, `git status`
+shows the tree exactly as before the probe; a leftover `.bak` means a probe was
+stranded — restore from it before anything else.
+
 ## Staging protocol (auto-commit OFF)
 
 Active **only when your invocation says so** — the human chose to review the work
@@ -153,7 +178,17 @@ iteration only knows what this contract and the worktree tell it:
 - **On a fix iteration** (checkpoint `changes`), the Orchestrator hands you a
   worktree that may carry the human's own revalidated edits: **stage everything
   first** (`git add -A` — that snapshot is your safe starting point), then
-  iterate under this same protocol.
+  iterate under this same protocol. When the feedback says the delta
+  revalidated **red**, that snapshot is a red starting point, not a green floor:
+  a rollback returns to it (the human's edits survive), and your first green
+  stage replaces it.
+- **On a resume with unverified work** (the Orchestrator names unstaged files it
+  found mid-implementation): the opposite of the fix iteration — **stage none of
+  it on sight**. It was never proven green and may be a probe stranded mid-flight.
+  Restore any `*.bak` first, read each hunk against the index, then prove each
+  piece green (or redo it) before it enters a save-point. When the resume is under
+  a `(red human delta)` fix-loop line, the staged index may still be that red
+  starting point: run the suite before trusting it as a floor.
 
 ## Skills
 

package/catalog/agents/orchestrator.md

@@ -352,7 +352,8 @@ One step = one `tasks.md` **group**, 1:1 with the grouping the human approved at
 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
+cadence. Tasks added mid-implementation (a resolved discovery) take the next free
+`T<n>` — a suffixed `T12b` is reported, not read — and 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
@@ -430,9 +431,11 @@ numbers still never shift. For each group, in order:
    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, a task still
-     `[ ]` in a group the loop has passed) → no retry. They
+     tag or ref list that did not parse, a task line or group header that did not
+     parse, a duplicated group number, a task id on two task lines, an orphan task, an
+     empty group, a dangling
+     requirement ref, a step with no group, a task still `[ ]` in a group the loop
+     has passed) → 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
@@ -440,7 +443,7 @@ numbers still never shift. For each group, in order:
      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.
-     **`unticked-completed-task` is the one spec-side kind that needs no discovery**:
+     **`unticked-completed-task` is one of two spec-side kinds that need no discovery**:
      the Implementer ticks each task at green, so an unticked task in a passed group
      is a forgotten mark or work that was never done, and only the human can tell
      which. Name the task ids in the checkpoint and ask. `ok` = "done, the mark was
@@ -448,7 +451,16 @@ numbers still never shift. For each group, in order:
      do** (`git add .claude/state/tasks/<id>/spec/tasks.md`) — a mediated edit, staged
      on arrival like a Spec Author update, so the checkpoint contract's spec check
      (item 4) never reads it as an unconfirmed human spec edit — then re-run the verb.
-     Wherever an OK's composite commits state, the staged tick rides its
+     The other is a `malformed-task-line` about the **box** (neither `[ ]` nor `[x]`: an
+     in-progress `[-]`, a padded `[  ]`; a line not written `- [ ] T<n>` — **no** box,
+     a numbered item, inside a quote — is a `shape` defect — maybe a note, not a task —
+     and routes as a discovery) — the same done-mark, so ask
+     the same question
+     and write `- [x]` on `ok`, `- [ ]` otherwise, staged and committed the same way.
+     Every later mention of `unticked-completed-task` in this file — the tick commit,
+     the `[unticked: …]` suffix, the full-pass path, the one mediated edit that is not
+     a discovery — covers this box case too, the `- [ ]` rewrite on `changes` included.
+     Wherever an OK's `checkpoint` call commits state, the staged tick rides its
      `.claude/state` half and needs nothing more: every step OK (both knob states),
      and auto-commit OFF's deferral-ending checkpoint OK, which its pre-gate full pass
      feeds. **At the merge-gate presentation nothing else commits state before the
@@ -463,10 +475,10 @@ numbers still never shift. For each group, in order:
      ```
 
      A merged `tasks.md` still reading `[ ]` is exactly the harm the kind exists to
-     stop. That post-APPROVE state write moves the stale-approve fingerprint the way
-     the ledger's own write does, and routes as the merge gate's exit-40 rule says
-     (§Merge gate) — a fresh APPROVE re-records the hashes; `--force` stays the
-     human's separate, informed call. `changes` = the
+     stop. That post-APPROVE state write lives under `.claude/state`, which the
+     stale-approve fingerprint leaves out (as it does the ledger's own write), so it
+     does not invalidate the APPROVE; a code change riding along in the same push
+     still would (§Merge gate, exit 40). `changes` = the
      task is not done → the normal fix iteration, feedback naming the task. Never tick
      on your own judgment: the mark is the Implementer's claim, and the verb exists so
      a missing one is read by a person, not smoothed over by you.
@@ -476,7 +488,7 @@ numbers still never shift. For each group, in order:
      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
+     Implementer's budget. Set the open step's transient tail 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** →
@@ -510,10 +522,10 @@ numbers still never shift. For each group, in order:
 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
+   step's `progress.md` tail 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
+   This commit and step 4's `checkpoint` call 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`):
@@ -539,9 +551,14 @@ numbers still never shift. For each group, in order:
    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.
+   - **OK** → resolve it with the `checkpoint` verb (step 4), next group.
+   - **Changes** (with feedback) → resolve it with the `checkpoint` verb (`changes`,
+     step 4) in the turn that records the answer — the one that rewrites the open
+     line's tail to `checkpoint: changes → fix-loop iteration K` (step 5) — before
+     dispatching anyone (Implementer, Spec Author, or a discovery) →
+     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
      the human unreviewed**. But first classify the request: if it **contradicts the
      approved spec** (`requirements.md`/`design.md`), don't rewrite anything silently —
@@ -549,32 +566,43 @@ numbers still never shift. For each group, in order:
      pause label as usual) so the interpretation is confirmed with the human **before**
      the Spec Author updates the spec and the loop resumes. In doubt, raise it —
      mediation confirms cheaply.
-   - **OK and switch to all-at-once** → emit `step_completed` with
-     `checkpoint_result=ok_downgrade`, update `progress.md`
+   - **OK and switch to all-at-once** → update `progress.md`
      (`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
+     choice), resolve it with the `checkpoint` verb (`ok_downgrade`, step 4), and run
+     the **remaining** tasks as a single Implementer invocation
      (all-at-once; the auto-commit 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`); 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. Auto-commit OFF: 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 §Auto-commit OFF); on
-   `changes` nothing is committed and the deferral continues. `<review-iterations>` is the number
+4. **Resolution and telemetry** — every **resolved checkpoint** emits one
+   `step_completed` (so a step the human sent back emits more than once, same
+   `--step`). Write the step's resolved `progress.md` line (step 5) first, then
+   resolve the answer with the **`checkpoint` verb** (§Checkpoint contract, item 5)
+   in the same turn — the call makes the commits, the push and the emit together,
+   emit last:
+   - **OK** (plain or `ok_downgrade`): the resolution state commit
+     `step(<id>): step <N> checkpoint OK` over the task's state — without it a cold
+     `/resume` still reads `awaiting` after the last group; auto-commit OFF: preceded
+     by the group's **code commit** `step(<id>): step <N>` (the deferral ends here,
+     §Auto-commit OFF); then a best-effort push, then the emit.
+   - **`changes`**: no commit; auto-commit OFF: it stages the human delta, and the
+     deferral continues; then the emit — **the emit never defers**.
+
+   An answer that arrives bundled with another request (`ok` + `/pause`, a spinoff)
+   still runs the verb before that request runs. A rejected commit (a pre-commit
+   hook) stops the verb before the emit: fix the cause and run the same call again —
+   what already landed is skipped. An answer given **in this session** whose verb
+   call never ran is still resolved, late — never dropped; never back-fill events
+   from other sessions or machines: while the work has not moved on — no later
+   group started and, for a `changes`, no fix-loop Implementer dispatched — run the
+   verb now; once it has (its staging would sweep that work into step N), or when the
+   verb refuses because the answer's commits were already made without it, emit
+   by hand with that phase's own `--review-iterations`. `<review-iterations>` is the number
    of Reviewer invocations that preceded this checkpoint (≥ 1; resets after a
-   "changes"):
+   "changes"). The late emit:
 
    ```bash
    .claude/hooks/lib/lemony.sh emit step_completed \
@@ -587,7 +615,8 @@ numbers still never shift. For each group, in order:
    ```
 
    **Attribution — name the component the checkpoint friction is about, or
-   omit.** The two `--attributed-*` flags are **optional**; they're meaningful when
+   omit.** The two `--attributed-*` flags — on the verb, or on a late emit — 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; a ledger retry is the
    Reviewer's own. **Omit both on a clean
@@ -609,7 +638,9 @@ numbers still never shift. For each group, in order:
 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,
+   (`fix-loop iteration K — in progress` while implementing/reviewing — auto-commit
+   OFF: written in the same turn that stages the human delta, with a
+   `(red human delta)` suffix when it revalidated red, §Auto-commit OFF —
    `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 — with
    the `[unticked: T3, T4]` suffix when the checkpoint is the anticipated one an
@@ -624,9 +655,21 @@ numbers still never shift. For each group, in order:
    - 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)
+   - step 4/6 (anchor f1a2b3c) — review ×1 → awaiting human checkpoint (step 4/6)
    ```
 
+   A review phase — the Reviewer invocations between two checkpoints — is **one**
+   `review ×K (N rejects: …)` segment: K counts that phase's invocations (it resets after
+   `changes`, as `--review-iterations` does) and N its **REJECT verdicts**, not findings
+   — one REJECT listing two problems is still `1 reject`; list findings freely, only the
+   number counts verdicts. Update the open phase's segment in place; never append a
+   second segment that repeats a phase already on the line. While the step is open,
+   its transient sub-state stays the line's tail after the segments already written
+   (`… → checkpoint: changes → fix-loop iteration 1 — in progress`): each new sub-state
+   replaces only the tail, and the step's resolution replaces the tail with its outcome.
+   The turn that writes a `checkpoint: <answer>` also runs the `checkpoint` verb
+   (step 4), `changes` included.
+
    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, and the ledger-retry line
@@ -655,7 +698,7 @@ the step loop the transient line is `awaiting ledger retry (full pass, retry 1/1
 auto-commit-OFF checkpoint when there is one, otherwise the merge-gate presentation,
 with the verb's lines as the content. An `unticked-completed-task` there resolves as
 in step 2's routing bullet — on `ok`, tick and stage the named tasks; at the
-auto-commit-OFF checkpoint the OK's composite commits them, at the merge-gate
+auto-commit-OFF checkpoint the OK's `checkpoint` call commits them, at the merge-gate
 presentation you commit them yourself — then re-run the verb.
 
 ## Checkpoint contract (how a human gate presents work)
@@ -686,7 +729,8 @@ contract, not a vibe:
    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
+4. **The human delta — always detected, always revalidated.** (Every answer then
+   resolves through item 5's call.) Whatever the answer
    (`ok` or `changes: …`), first detect the human's own edits — in auto-commit
    OFF, **two checks with distinct routes** (every agent save-point is staged at
    presentation time, so the staged/unstaged seam is the auto-detect):
@@ -721,21 +765,59 @@ contract, not a vibe:
    The **spec check runs in both knob states** — in auto-commit ON, run it
    **before** step 3's `awaiting` state commit, which would otherwise silently
    commit a pre-existing spec edit before detection. Auto-commit ON's work-delta
-   detection is simply any uncommitted working-tree change.
+   detection is any uncommitted working-tree change outside task state —
+   `git status --porcelain -- . ':(exclude).claude/state'` (task state is never a
+   human delta here: the spec check above owns the spec, and the rest is yours).
    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
+   inherits the group's green. **A red revalidation blocks the OK**: never resolve
+   an OK 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 (auto-commit OFF: staged into the group's commit; auto-commit ON:
    committed as its
-   own commit — `step(<id>): step <N> human delta` — before the next group); on
+   own commit, before you write the resolved line and make item 5's call, with a
+   pathspec that keeps task state out of it:
+   `git add -A -- . ':(exclude).claude/state' && git commit -m "step(<id>): step <N> human delta" -- . ':(exclude).claude/state'`); on
    `changes` it stays in the worktree for
    the fresh Implementer (auto-commit OFF: staged first as the safe starting point —
    §Auto-commit OFF).
 
+5. **Resolve the answer with one call.** Write the resolved `progress.md` line
+   first (step-by-step step 5 — the state commit carries it), then, in the same
+   turn:
+
+   ```bash
+   .claude/hooks/lib/lemony.sh checkpoint <ok|changes|ok_downgrade> \
+     --task-id="<id>" \
+     --auto-commit=<on|off> \
+     --step=<N> \
+     --review-iterations=<count>
+   ```
+
+   `--auto-commit` is the value `progress.md` records; `<count>` is the number of
+   Reviewer invocations since the last `changes` (≥ 1). Add
+   `--attributed-kind`/`--attributed-name` only when the checkpoint surfaced
+   friction you can name (step-by-step step 4, Attribution). The all-at-once gate —
+   auto-commit OFF only, a downgraded remainder included — omits `--step` and
+   `--review-iterations`: on `ok` it still makes the `task(<id>)` commits, but it
+   emits nothing (`step_completed` is step-by-step only). The call makes the
+   commits, the best-effort push and the `step_completed` emit together, emit last
+   (step-by-step step 4 says what each answer lands). **Never make those commits by
+   hand, and never copy them from `git log`**: a checkpoint commit's
+   `Lemony-Checkpoint:` trailer is the call that made it. An answer bundled with
+   another request (`ok` + `/pause`, a spinoff) runs this call before that request.
+   A failed call names the step it stopped at; fix the cause and run the same call
+   again. It refuses up front — nothing staged or committed — a repo it cannot
+   commit safely (no state for the task id, a detached HEAD, an unfinished merge,
+   rebase, cherry-pick or revert, unmerged paths) and, under auto-commit ON, an OK
+   that left `progress.md` unchanged (under auto-commit OFF the file is always dirty, so the
+   check cannot see a missing line — writing it first is on you): write the resolved
+   line first — or, when this answer's commits were
+   already made without the call, emit by hand instead (step-by-step step 4's late
+   emit).
+
 ## Auto-commit OFF (zero commits + staging save-points)
 
 The auto-commit OFF state (chosen at the approval gate — §Implementation mode) moves
@@ -759,6 +841,25 @@ pre-registered exit signals.
   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.
+- **A resume mid-implementation treats unstaged work as unverified.** While the
+  Implementer is still working a group — `progress.md` is **not** at an
+  `awaiting human checkpoint` line — the staged index is the last green
+  save-point (under a `(red human delta)` fix-loop line it may still be that
+  red starting point: tell the fresh Implementer so — it runs the suite before
+  trusting it),
+  and whatever a resume finds **unstaged** (outside
+  `.claude/state`) — the `/pause` note's `Unverified` line lists it — was never
+  proven green, however finished it looks: an interrupted hand probe leaves a
+  deliberately wrong line that reads exactly like work in progress. Never stage,
+  review, or present it as done on sight. Hand it to the fresh Implementer as
+  **unverified work to confirm or redo** — the spawn prompt says so and names the
+  files — and it proves each piece green (suite, and for a suspicious hunk the diff
+  against the index) before the staging protocol lets it in. A leftover `*.bak`
+  beside a source file is a stranded probe: restore from it first. **At an
+  `awaiting` checkpoint the rule does not apply**: every agent save-point was
+  staged at presentation, so unstaged work there is the **human delta** —
+  re-present the checkpoint and route it through the human-delta check (step 4
+  of §Checkpoint contract), never to the Implementer as suspect work.
 - **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
@@ -780,43 +881,44 @@ pre-registered exit signals.
   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>): implementation checkpoint 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.
+  Then the deferral ends with the **`checkpoint` verb** (§Checkpoint contract,
+  item 5) — also when the OK arrives with `/pause` or a spinoff: run it before
+  them (the OK ends the deferral, so `/pause`'s no-commit rule does not reach it).
+  It stages the worktree, then splits the mixed index by pathspec into a code
+  commit (everything outside `.claude/state`) and a state commit, each **guarded on
+  its half holding changes** — 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 — then pushes best-effort. Step-by-step: the
+  commits are `step(<id>): step <N>` and `step(<id>): step <N> checkpoint OK`, and
+  the `step_completed` emit follows (step 4). All-at-once (a downgraded remainder
+  resolves as all-at-once here too — call without `--step`): the commits are
+  `task(<id>): implementation` and `task(<id>): implementation checkpoint 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.
+  under the staging protocol. Nothing is committed and the deferral continues.
+  **The `checkpoint` verb (`changes`) stages that delta for you (`git add -A`) —
+  run it in the same turn that rewrites the open line's tail to
+  `fix-loop iteration K`**, and in step-by-step it emits `changes` there too (step 4;
+  all-at-once, a downgraded remainder included, emits nothing — call without
+  `--step`): a session that dies
+  between the line and the Implementer's own stage-first would otherwise leave
+  the human's edits unstaged under a mid-implementation line, where a resume
+  reads them as unverified work (the resume rule above). The Implementer's
+  stage-first then only picks up task state — a harmless repeat. A delta that
+  revalidated **red** (the human handed it to the Implementer to fix) is staged
+  the same way — unstaged, the Implementer's first rollback would wipe the
+  human's edits — but that floor is **red, not proven green**: write the line as
+  `fix-loop iteration K — in progress (red human delta)` and say so in the
+  feedback. It is the iteration's red starting point until the Implementer's
+  first green stage replaces it.
 - **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
@@ -930,8 +1032,9 @@ pending checks (`merge.checks_timeout_secs` in `harness.config.yml`, default ~10
 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):
+that no longer matches what the APPROVE reviewed (a clean update-branch stays valid,
+and so does a task-state write under `.claude/state`; any other 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`
@@ -1056,12 +1159,31 @@ the task merge time (`mergedAt` from `gh pr view`). `review_rejections` is the n
 `review_rejected` events recorded for this `task_id` in `events.jsonl` (0 on a
 first-pass approval). `<level>` is `L1` for full-SDD tasks (`harness:sdd`
 label), `L2` for triage tasks (no `harness:sdd`). On **L1**, also pass `--mode` —
-the **gate choice**, always: the first mode named on `progress.md`'s `Mode:` line (a
-`(downgraded …)` suffix doesn't change it; a downgraded task still emits
-`--mode=step_by_step`). If `progress.md` is already archived, recover it from
-`events.jsonl`: ≥ 1 `step_completed` event for this `task_id` means `step_by_step`.
-When the gate choice was step-by-step, also pass `--steps` (the count of
-`step_completed` events for this `task_id`). Omit both on L2:
+the **gate choice**: the first mode named on `progress.md`'s `Mode:` line, written
+with underscores (`step-by-step` → `step_by_step`); a `(downgraded …)` suffix
+doesn't change it, so a downgraded task still emits `--mode=step_by_step`. If
+`progress.md` is already gone (the closeout PR drops it), read the `Mode:` line
+from its last committed version:
+
+```bash
+P=.claude/state/tasks/<id>/progress.md
+git show "$(git log -1 --diff-filter=D --format=%H -- ":/$P")^:$P" | grep -m1 '^Mode:'
+```
+
+Only when that prints no `Mode:` line (git has no such version, or it predates
+the line), fall back to `events.jsonl`: ≥ 1
+`step_completed` event for this `task_id` means `step_by_step` — but none on this
+machine does **not** prove all-at-once (the file is local; the steps may have run
+elsewhere), so with neither source omit `--mode` rather than guess.
+When the gate choice was step-by-step, also pass `--steps` and `--checkpoints`,
+both read from the `step_completed` events whose `task_id` is exactly `<id>`:
+`--steps` is the number of **distinct** `step` values (a step the human sent back
+emits again with the same `step` — count it once), `--checkpoints` the number of
+events. A task whose steps 1–4 each needed one `changes` round has 4 steps and 8
+checkpoints. On an all-at-once L1 task pass `--mode` only; on L2 omit all three.
+`events.jsonl` is local to the machine: when this one holds no `step_completed`
+event for a step-by-step task (its steps ran elsewhere), pass
+`--mode=step_by_step` without counts — a guessed count is worse than none:
 
 ```bash
 .claude/hooks/lib/lemony.sh emit task_done \
@@ -1070,7 +1192,8 @@ When the gate choice was step-by-step, also pass `--steps` (the count of
   --cycle-time-h=<hours> \
   --review-rejections=<count> \
   --mode=<all_at_once|step_by_step> \
-  --steps=<count>
+  --steps=<count> \
+  --checkpoints=<count>
 ```
 
 ## Sub-agent invocation

package/catalog/agents/reviewer.md

@@ -227,7 +227,9 @@ What the validator enforces in this version, so you never have to guess:
   actually ran, declared or not.
 - **Spec-side problems are reported, never dropped — and they are not yours to fix.** A
   `[risk: …]` tag outside the vocabulary (`unknown-risk-class`), a tag or a `(R<n>)` ref
-  list that did not parse, a duplicated group number, a task above the first header, an
+  list that did not parse, a task line or group header that did not parse (`[-]`,
+  `T12b`, `### Group 3`), a duplicated group number, a task id on two task lines, a task
+  above the first header, an
   empty group, a ref `requirements.md` never declares, a step with no group, a task
   still `[ ]` in a group the loop has passed (`unticked-completed-task` — the
   Implementer's done-marker is missing, and whether the work is too is the human's
@@ -361,7 +363,7 @@ empirically).
    ```bash
    git fetch -q origin <base>
    echo "Reviewed-tree: $(git rev-parse 'HEAD^{tree}')"
-   echo "Diff-fingerprint: $(git -c core.quotePath=true diff --raw --no-abbrev --no-renames --no-color "$(git merge-base FETCH_HEAD HEAD)" HEAD | git hash-object --stdin)"
+   echo "Diff-fingerprint: $(git --no-literal-pathspecs -c core.quotePath=true diff --raw --no-abbrev --no-renames --no-color "$(git merge-base FETCH_HEAD HEAD)" HEAD -- ':(top,exclude).claude/state' | git hash-object --stdin)"
    ```
 
    `<base>` is the PR's base branch (the default branch for task PRs; a stacked
@@ -375,7 +377,10 @@ empirically).
    content-changed verdict). The fingerprint digests the PR's own diff against
    the merge-base, so a clean update-branch later stays valid, while any
    content change — including a merge resolution touching a file you
-   reviewed — invalidates the record and routes the PR back to re-review. A
+   reviewed — invalidates the record and routes the PR back to re-review.
+   Task state under `.claude/state` is left out of the digest, so your ledger
+   and evidence writes after this comment — and the Orchestrator's — never
+   invalidate it. A
    re-review that approves posts a fresh APPROVE with fresh hashes; the
    latest record wins — which is also why these two marker lines must never
    be quoted in any later comment (the executor trusts the newest comment

package/catalog/agents/spinoff.md

@@ -42,8 +42,9 @@ frictionless and noise-free:
 
 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):
+way `/spinoff` does — the `Active task:` line of
+`.claude/hooks/lib/lemony.sh status --local`; omit `--parent` when it reads `(none)` or
+the command fails):
 
 ```bash
 .claude/hooks/lib/lemony.sh spinoff \