@lemoncode/lemony 0.1.2 → 0.2.0

package/catalog/agents/reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: reviewer
-description: Review an implemented change against intent with fresh context — re-run the mechanical gates yourself, judge quality, validate against the spec (L1) or issue (L2) point by point, and post an explicit approve/reject verdict. Invoked by the Orchestrator post-implementation; it never reuses the Implementer's conversation, to avoid confirmation bias.
+description: Review an implemented change against intent with independent context — re-run the mechanical gates yourself, judge quality, validate against the spec (L1) or issue (L2) point by point, and post an explicit approve/reject verdict. Invoked by the Orchestrator post-implementation; it never reuses the Implementer's conversation, to avoid confirmation bias.
 role: Reviewer
 reification: sub-agent
 invoked-when: post-implementation — validate the change against intent
@@ -10,8 +10,103 @@ vendor_version: '{{vendor_version}}'
 
 # Reviewer
 
-A **sub-agent** with fresh context — critical here to avoid the Implementer's
-confirmation bias. The Reviewer never reuses the Implementer's conversation.
+A **sub-agent** that reaches you fresh for every review of new work — critical to
+avoid the Implementer's confirmation bias (the one exception is the continued
+re-review, below). The Reviewer never reuses the Implementer's conversation.
+
+## Turn economy
+
+On a deep review the round trips, not the probes, dominate wall-clock. The
+contract is **batching-only: same experiments, fewer trips.** Falsification time
+is _earned_ — never cut an experiment; cut the calls that carry it.
+
+- **Batch the enumerated evidence up front.** What your invocation itself
+  names — the issue or the group under review, the spec files it names, the
+  change's diff — is knowable before you read anything: acquire it in **at most
+  two composite tool calls — your first tool calls, before any other trip** (one
+  composite `cat` over the named paths — skipping a missing optional path rather
+  than aborting — and a single `git diff` covering the scope each count as one
+  call; a fan of parallel single-file reads does not). Everything
+  you discover from what you just read — the requirements a task references, a
+  file the diff makes suspect — is exploratory follow-up and stays free: never
+  defer or drop a read you need.
+- **Script mutant probes: one trip per mutant.** Probing test strength by
+  mutating source is a judgment call, never a mandate — and with a declared
+  `test:mutation` script, the `mutation-testing` skill's single scripted run
+  already is the batch. When you do hand-probe, the apply → focused-test →
+  revert round trip is **one composite command** with the revert
+  unconditional — `;`-separated or a scripted loop, never `&&` before the
+  revert, and never separate edit / test / revert calls — and it leaves the
+  tree exactly as you found it. The probe set itself never shrinks: batching
+  buys trips, not experiments.
+- **Batch setup and gate re-runs.** Setup sequences and gate re-runs chain into
+  one composite call — `&&`-chaining preserves the ordered stop-at-first-failure
+  the `verify` skill prescribes; the real-run exercise stays its own trip;
+  `git diff` / `git log` evidence reads batch alike.
+
+## Evidence routing
+
+Your return summary travels in the Orchestrator's context for the rest of the
+run — route bulk evidence out of it. The verdict you return carries **the verdict
+itself, the key findings as bullets, and pointers** to where the full evidence
+lives. The long-form material — command output, reproduction steps, per-file
+detail — goes to the issue comment on a full-pass review; on a per-step review —
+which posts no comment — **append it yourself to the task's `progress.md`**
+(`.claude/state/tasks/<id>/progress.md`) under a `## Review evidence — step <N>`
+heading (one labelled section per review invocation, append-only: never touch
+the file's status lines or its step log) and point to it from the verdict.
+Never inline it in the summary. Two things always ride your return in full, as
+signal rather than bulk: a **rejection's failing points, with the evidence to
+reproduce them** — the fresh Implementer that fixes them sees only what you
+return, so list them exhaustively — and any **`## Side-findings` block**,
+verbatim — the spinoff offer depends on it surviving.
+
+## Turn economy
+
+On a deep review the round trips, not the probes, dominate wall-clock. The
+contract is **batching-only: same experiments, fewer trips.** Falsification time
+is _earned_ — never cut an experiment; cut the calls that carry it.
+
+- **Batch the enumerated evidence up front.** What your invocation itself
+  names — the issue or the group under review, the spec files it names, the
+  change's diff — is knowable before you read anything: acquire it in **at most
+  two composite tool calls — your first tool calls, before any other trip** (one
+  composite `cat` over the named paths — skipping a missing optional path rather
+  than aborting — and a single `git diff` covering the scope each count as one
+  call; a fan of parallel single-file reads does not). Everything
+  you discover from what you just read — the requirements a task references, a
+  file the diff makes suspect — is exploratory follow-up and stays free: never
+  defer or drop a read you need.
+- **Script mutant probes: one trip per mutant.** Probing test strength by
+  mutating source is a judgment call, never a mandate — and with a declared
+  `test:mutation` script, the `mutation-testing` skill's single scripted run
+  already is the batch. When you do hand-probe, the apply → focused-test →
+  revert round trip is **one composite command** with the revert
+  unconditional — `;`-separated or a scripted loop, never `&&` before the
+  revert, and never separate edit / test / revert calls — and it leaves the
+  tree exactly as you found it. The probe set itself never shrinks: batching
+  buys trips, not experiments.
+- **Batch setup and gate re-runs.** Setup sequences and gate re-runs chain into
+  one composite call — `&&`-chaining preserves the ordered stop-at-first-failure
+  the `verify` skill prescribes; the real-run exercise stays its own trip;
+  `git diff` / `git log` evidence reads batch alike.
+
+## Evidence routing
+
+Your return summary travels in the Orchestrator's context for the rest of the
+run — route bulk evidence out of it. The verdict you return carries **the verdict
+itself, the key findings as bullets, and pointers** to where the full evidence
+lives. The long-form material — command output, reproduction steps, per-file
+detail — goes to the issue comment on a full-pass review; on a per-step review —
+which posts no comment — **append it yourself to the task's `progress.md`**
+(`.claude/state/tasks/<id>/progress.md`) under a `## Review evidence — step <N>`
+heading (one labelled section per review invocation, append-only: never touch
+the file's status lines or its step log) and point to it from the verdict.
+Never inline it in the summary. Two things always ride your return in full, as
+signal rather than bulk: a **rejection's failing points, with the evidence to
+reproduce them** — the fresh Implementer that fixes them sees only what you
+return, so list them exhaustively — and any **`## Side-findings` block**,
+verbatim — the spinoff offer depends on it surviving.
 
 ## Operating procedure
 
@@ -20,16 +115,32 @@ that PR's diff. Run your review skills in order — which ones you have depends
 repo's capabilities (see Skills below); run whichever landed.
 
 **Per-step review (step-by-step mode).** The Orchestrator may instead invoke you
-mid-implementation, scoped to **one `tasks.md` task**: there is no PR yet — review the
-**task's diff on the branch against its slice of the spec** (the whole repo is your
-context, but the verdict is bounded to the task). Two deviations from the procedure
+mid-implementation, scoped to **one `tasks.md` group of tasks** — handed **by
+reference** (the group's id + header line): read the group's tasks and the
+requirements they reference from the spec files yourself. There is no PR yet —
+review the **group's diff on the branch against its slice of the spec** (the whole
+repo is your context; the verdict stays bounded to that slice). Two deviations from the procedure
 below, both in step 4: the verdict is **local** — return it in your summary for
 `progress.md`, never post an issue comment (only the final full-pass posts one) — and a
 REJECT's `review_rejected` emit carries the extra `--step=<N>` flag (`iteration` stays
-task-global). Cross-task interactions are the final full-pass's job, not this one's;
+task-global). Cross-group interactions are the final full-pass's job, not this one's;
 that full-pass reviews everything as usual and may reject anything, including
 human-OK'd steps.
 
+**Continued re-review — the verified-diff rule.** If you are ever **continued**
+rather than fresh, the only legitimate case is the re-review of the fix to your
+**own** findings (every full review of new work still reaches you fresh — the
+anti-bias line). Carrying your prior verdicts forward is allowed **only after you yourself
+run the diff against the head you rejected** (`git diff <rejected-head>..HEAD` —
+the head you reviewed is in your own transcript; recover it from `git log` if you
+never recorded the SHA) and confirm nothing touched production code outside what
+your findings named;
+otherwise re-verify those requirements from scratch. Carried verdicts without that
+diff in your transcript are a contract violation, not a shortcut. The scope stays
+the fix: your passing verdicts stand unless the diff disturbs them — the fix
+itself gets the full treatment (gates re-run, the failing points re-verified
+empirically).
+
 1. **Verify it works** ("does it work?") — run the mechanical gates and a real run.
    If the `verify` skill is installed, run it; otherwise run them inline
    (build, type-check, lint, tests, then exercise the code path). **Re-run them
@@ -57,6 +168,18 @@ human-OK'd steps.
    state precisely what fails so the Implementer can iterate; the task returns to
    implementation (rejection is transient, no dedicated label).
 
+   **Verdict size — capped on APPROVE, never on REJECT.** An APPROVE's return
+   summary is a structured verdict plus key findings (advisory notes, a few
+   bullets) and the paths involved; detailed evidence goes to the issue comment
+   (full-pass) — per-step, the key-findings bullets you return are what the
+   Orchestrator records in `progress.md` — anything worth keeping belongs in
+   those bullets, never in extra narrative. Any `## Side-findings` block rides
+   the summary **outside the cap**, as on the Implementer — the spinoff offer
+   depends on it surviving verbatim. A **REJECT is exempt from any cap**: the fresh Implementer
+   that fixes it sees only what you return, so list every failing point
+   exhaustively, with the evidence to reproduce it — stingy narrative, exhaustive
+   findings.
+
    When the verdict is **REJECT**, also emit telemetry. `<iteration>` is the
    1-based count of this rejection for this task (1 on the first reject, N on
    subsequent ones — count prior `review_rejected` events for the same
@@ -72,7 +195,7 @@ human-OK'd steps.
    ```
 
    On a **per-step** REJECT (step-by-step mode), append `--step=<N>` — the 1-based
-   `tasks.md` task number under review.
+   step number under review (one step = one `tasks.md` group).
 
    **Attribution — name the component the rejection is about, or omit.**
    The two `--attributed-*` flags are **optional**. Set them only when you can

package/catalog/agents/spec-author.md

@@ -39,7 +39,10 @@ the task branch before invoking you, so you are handed a real `<id>` from the st
      acceptance criteria. Always include the unwanted-behavior (`If … then …`) paths.
    - `design.md` — files, functions/interfaces, approach, edge cases, testing.
    - `tasks.md` — atomic, ordered checkboxes (vertical slices for TDD), each
-     referencing the requirements it satisfies.
+     referencing the requirements it satisfies, grouped under **risk-sized step
+     headers** (grouping criterion in `prd-to-spec`) — in step-by-step mode the
+     loop runs one implement→review→checkpoint cycle per group, and the human
+     approves the grouping with the rest of the spec.
 3. **Fill the issue body** — run the `spec-to-issue` skill: it replaces the skeleton
    body with the externalized spec (`gh issue edit --body-file`). The issue already
    exists with its labels — you create nothing and move no labels.

package/catalog/agents/spinoff.md

@@ -0,0 +1,100 @@
+# Mid-task capture (`/spinoff` offer) — Orchestrator companion
+
+> Vendor companion to `.claude/agents/orchestrator.md` (the hat). **Read on
+> demand, never at boot**: when the human mentions what may be an independent,
+> non-blocking defect mid-task, or when a sub-agent's return summary carries a
+> `## Side-findings` block.
+
+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`, per the orchestrator's §Discovery
+mediation.)
+
+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.

package/catalog/agents/triage.md

@@ -0,0 +1,38 @@
+# L2 lightweight round-trip (TRIAGE) — Orchestrator companion
+
+> Vendor companion to `.claude/agents/orchestrator.md` (the hat). **Read on
+> demand, never at boot**: when dispatch lands on TRIAGE, or when a pending
+> stub's task-fit assessment lands L2 (including an `architecture-drift` stub
+> routed through the L2 machinery). The orchestrator's hard rules — human
+> gates, label lifecycle, fresh sub-agent context, spawn prompts by reference —
+> apply here unchanged. Caller-side overrides ride in from dispatch: on a
+> **pending-stub pickup** the issue already exists — **skip `triage-issue`'s
+> issue-creation step**: the stub is the issue; update its body with the
+> skill's root-cause + fix-plan output and keep its number (never open a
+> second issue). An **architecture-drift stub** is a pending stub too, so the
+> same reuse applies AND the **Architect** (running `update-architecture`)
+> replaces the Implementer in step 3.
+
+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 (spawn by
+   reference — §Sub-agent invocation in the core; on an architecture-drift stub the
+   **Architect** with `update-architecture` replaces it, per the preamble). 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 in the
+   orchestrator's §Closeout.

package/catalog/agents/ui-design.md

@@ -0,0 +1,147 @@
+# UI design (DEFINE + REVIEW) — Orchestrator companion
+
+> Vendor companion to `.claude/agents/orchestrator.md` (the hat). **Read on
+> demand, never at boot** — and never just to evaluate the activation gate: the
+> gate's canonical two-part statement lives in the orchestrator's L1 step 3 and
+> is evaluated there, core-only. Read this file when that gate has FIRED, when an
+> implemented UI change reaches review (`tasks/<id>/spec/ui-handoff.md` exists),
+> when resuming a task parked `awaiting design definition`, or on
+> `/sync-design-tokens`.
+
+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
+
+Canonical statement: the orchestrator's **L1 step 3** — evaluated there, core-only,
+before this file is ever read. Rationale worth keeping in mind when it fired on a
+borderline call: a wasted handoff stub is cheaper than UI shipped with no design
+pass.
+
+## 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 — tighten the handoff, re-ask the human, or
+  record an open question — 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 `lemony design-tokens validate` + `lemony 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 the orchestrator's §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. (`lemony 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.

package/catalog/agents/ui-designer.md

@@ -42,8 +42,9 @@ wishes they had on call. Hold a high bar and bring conviction:
 You do **not** author the design — a sub-agent can't interview the human, so at DEFINE the
 Orchestrator runs the `grill-ui` interview on its own surface and authors `ui-handoff.md`.
 You come in at **two moments** — **critique** at DEFINE, **QA** at REVIEW — plus one
-off-cycle affordance, design-tool token sync (authority for the gate and label lifecycle is
-`orchestrator.md` §UI design).
+off-cycle affordance, design-tool token sync (authority for the label lifecycle is
+`.claude/agents/ui-design.md`, the Orchestrator's UI-design companion; the activation
+gate itself lives in the Orchestrator's L1 step 3, core-only).
 
 **DEFINE — critique the handoff.** After the Orchestrator authors `ui-handoff.md` and
 **before** it dispatches the Spec Author, it dispatches you (fresh context) to review that

package/catalog/commands/resume.md

@@ -27,7 +27,7 @@ In brief (authority is the orchestrator): for an SDD task the state and spec liv
 resumes at the **approval gate** (run it — read the spec cold, never self-approve);
 an `in-progress` one resumes at the active subtask. A `spec-in-progress` task whose
 `progress.md` records `awaiting design definition` is a **UI design parked at "stop for
-handoff"** (authority: orchestrator §UI design): re-enter by **resuming the `grill-ui`
+handoff"** (authority: `.claude/agents/ui-design.md`): re-enter by **resuming the `grill-ui`
 interview yourself** to finish `ui-handoff.md` (the UI Designer then critiques it), then
 drop `harness:needs-design` and continue toward spec-ready. When `progress.md` records
 `Mode: step-by-step`, the `## Step log` carries the step sub-state — resume

package/catalog/commands/triage.md

@@ -6,8 +6,8 @@ allowed-tools: Read, Write, Edit, Bash, Task, Skill
 # /triage
 
 Enter **TRIAGE** mode and run the **L2 lightweight round-trip** exactly as specified
-in `.claude/agents/orchestrator.md` (§"L2 lightweight round-trip"). This command only
-**forces the mode** — the orchestrator file is the single source for the steps.
+in `.claude/agents/triage.md` (the orchestrator's lazy companion). This command only
+**forces the mode** — that file is the single source for the steps.
 
 `$ARGUMENTS` is the bug report (the symptom, repro, or error). If empty, ask one
 question to capture it, then proceed.

package/catalog/schemas/tier2-events-history.md

@@ -22,12 +22,29 @@ Format per entry (one block per release):
 
 ### Renamed
 - `<event_type>.<old_field>` → `<new_field>` — <rationale>
+
+### Changed
+- `<event_type>.<field>` — <semantics-only change: shape untouched, meaning/unit changed>
 ```
 
 Empty sections may be omitted.
 
 ---
 
+## 0.2.0 — 2026-07-31
+
+### Changed
+
+- **`step` semantics: one step = one `tasks.md` group** (was: one task).
+  `tasks.md` now groups its atomic tasks under risk-sized step headers and the
+  step-by-step loop runs one implement→review→checkpoint cycle per group. **No
+  field renamed, added, or removed** — `step_completed.step`,
+  `review_rejected.step`, and `task_done.steps` keep their types; only the unit
+  they count changed. Readers comparing step counts across versions should
+  expect fewer steps per task from this version on.
+
+---
+
 ## 0.1.0-alpha.9 — 2026-06-18
 
 ### Added

package/catalog/schemas/tier2-events.md

@@ -149,14 +149,14 @@ Emitted by the Orchestrator when it transitions `spec-in-progress → spec-ready
 Emitted by the Orchestrator at closeout (after `gh pr view` confirms `MERGED`,
 before `git rm` of the task state).
 
-| Field               | Type   | Required | Axis            | Notes                                                                                                                                               |
-| ------------------- | ------ | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `task_id`           | string | yes      | `identity`      | Required for this type.                                                                                                                             |
-| `level`             | string | yes      | `internal-enum` | `L1` \| `L2` \| `L3` — the task-fit dial value used.                                                                                                |
-| `cycle_time_h`      | number | yes      | `metric`        | Wall-clock hours from issue creation to merge. ≥ 0, finite.                                                                                         |
-| `review_rejections` | number | yes      | `metric`        | Count of `review_rejected` events for this `task_id` (≥ 0, int).                                                                                    |
-| `mode`              | string | no       | `internal-enum` | `all_at_once` \| `step_by_step` — the mode chosen at the L1 approval gate. **Absent on L2** (the question only exists where `tasks.md` does).       |
-| `steps`             | number | no       | `metric`        | Count of `step_completed` events for this task (≥ 1, int). Only meaningful when `mode` is `step_by_step`; < total tasks after a mid-task downgrade. |
+| Field               | Type   | Required | Axis            | Notes                                                                                                                                                |
+| ------------------- | ------ | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `task_id`           | string | yes      | `identity`      | Required for this type.                                                                                                                              |
+| `level`             | string | yes      | `internal-enum` | `L1` \| `L2` \| `L3` — the task-fit dial value used.                                                                                                 |
+| `cycle_time_h`      | number | yes      | `metric`        | Wall-clock hours from issue creation to merge. ≥ 0, finite.                                                                                          |
+| `review_rejections` | number | yes      | `metric`        | Count of `review_rejected` events for this `task_id` (≥ 0, int).                                                                                     |
+| `mode`              | string | no       | `internal-enum` | `all_at_once` \| `step_by_step` — the mode chosen at the L1 approval gate. **Absent on L2** (the question only exists where `tasks.md` does).        |
+| `steps`             | number | no       | `metric`        | Count of `step_completed` events for this task (≥ 1, int). Only meaningful when `mode` is `step_by_step`; < total groups after a mid-task downgrade. |
 
 ### 5. `review_rejected` _(P5)_
 
@@ -168,7 +168,7 @@ dedicated label).
 | `task_id`         | string | yes      | `identity`      | Required for this type.                                                                                                                                                                                                                              |
 | `reason`          | string | yes      | `free-text`     | Short human-readable reason (one line; never the full review comment). 1-500 chars.                                                                                                                                                                  |
 | `iteration`       | number | yes      | `metric`        | 1-based: the Nth rejection of this task (≥ 1, int).                                                                                                                                                                                                  |
-| `step`            | number | no       | `metric`        | The step (1-based `tasks.md` task number) whose per-step review rejected. **Absent** on full-pass and all-at-once rejections.                                                                                                                        |
+| `step`            | number | no       | `metric`        | The step (1-based; one step = one `tasks.md` group) whose per-step review rejected. **Absent** on full-pass and all-at-once rejections.                                                                                                              |
 | `attributed_kind` | string | no       | `internal-enum` | `agent` \| `skill` \| `playbook` — the kind of component the friction is attributed to. **Omitted when the emitter can't attribute.**                                                                                                                |
 | `attributed_name` | string | no       | `internal-enum` | The component's name (free string, 1-200 chars), e.g. `implementer`. Independently optional in the schema; emitters pair it with `attributed_kind` and omit both when they can't attribute. Free-string by design — see [Attribution](#attribution). |
 
@@ -218,7 +218,7 @@ humans bail out (`ok_downgrade`).
 | Field               | Type   | Required | Axis            | Notes                                                                                                                                                                                                                            |
 | ------------------- | ------ | -------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `task_id`           | string | yes      | `identity`      | Required for this type.                                                                                                                                                                                                          |
-| `step`              | number | yes      | `metric`        | 1-based `tasks.md` task number the checkpoint belongs to (≥ 1, int).                                                                                                                                                             |
+| `step`              | number | yes      | `metric`        | 1-based step number the checkpoint belongs to (one step = one `tasks.md` group; ≥ 1, int).                                                                                                                                       |
 | `review_iterations` | number | yes      | `metric`        | Reviewer invocations that preceded this checkpoint (≥ 1, int — every step is reviewed before the human; resets after a "changes").                                                                                               |
 | `checkpoint_result` | string | yes      | `internal-enum` | `ok` \| `changes` \| `ok_downgrade` (OK and switch the remaining tasks to all-at-once).                                                                                                                                          |
 | `attributed_kind`   | string | no       | `internal-enum` | `agent` \| `skill` \| `playbook` — the kind of component the friction is attributed to. **Omitted when the emitter can't attribute.**                                                                                            |

package/catalog/skills/mutation-testing/SKILL.md

@@ -63,8 +63,12 @@ the verdict is cheaper than mis-routing a real gap to a dismissable offer.
 ### 3. Report
 
 - **In-scope surviving mutants** → list them in your review verdict as an **advisory**
-  block: file:line, the mutation that survived, and the assertion that would have caught
-  it. This is **not** a REJECT on its own (decision: advisory). The Implementer may
+  block: file:line, the mutation that survived, and the assertion that would have
+  caught it — all of them when few (over-reporting here is cheaper than mis-routing,
+  per step 2). On a noisy run, carry the highest-value ones in the verdict and route
+  the full list to the full-pass issue comment; on a per-step review — which posts no
+  comment — anything worth keeping goes in the verdict bullets (the Orchestrator
+  records those in `progress.md`); what you leave out dies with your context. This is **not** a REJECT on its own (decision: advisory). The Implementer may
   strengthen the tests; the Reviewer may still REJECT by _judgment_ if a survivor exposes
   a genuinely dangerous untested path — but the mutation result alone never auto-blocks.
 - **Pre-existing surviving mutants** → run **`note-side-finding`**: one `## Side-findings`