@lemoncode/lemony 0.1.2 → 0.2.0

package/catalog/agents/orchestrator.md

@@ -16,6 +16,23 @@ 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)
+
+Three procedures live in sibling files, kept out of boot context by design (a fourth
+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.
+
 ## Dispatch
 
 Parse the first prompt's intent (or honor a slash command):
@@ -29,9 +46,7 @@ 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
@@ -52,7 +67,8 @@ 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,
@@ -61,8 +77,8 @@ Parse the first prompt's intent (or honor a slash command):
   run the task-fit assessment as usual, never break on the absent routing target.
 - **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
@@ -94,9 +110,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)
 
@@ -127,24 +140,27 @@ sibling `fit-assessment.md`; consult it for a borderline classification.
      (`git fetch && git checkout -b harness/<id>-<slug> origin/<default>`). 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
    `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,16 +176,17 @@ 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 in §Step-by-step
+   implementation instead, and rejoins this flow at step 8 after the last group.
 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
    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
+   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), go to the merge gate.
 9. **Merge gate** — see below. Human-explicit, never auto-merged.
 10. **Closeout** — see below.
@@ -184,7 +201,9 @@ 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) — approving the spec approves the grouping.
 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 +226,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 +243,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 +259,64 @@ 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)
-
-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,
+## 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. For each group, in order:
+
+1. **Implement the group** — 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, 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**. 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 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**:
+3. **Human checkpoint** — first 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"; \
+     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.
+   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.
    Then present the step: what was built, where to look, how to run it. Three
    answers:
-   - **OK** → emit `step_completed` (below), next task.
+   - **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
@@ -308,7 +337,11 @@ order:
    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`) + best-effort push ride as
+   **one composite turn** (§Turn economy) — without that commit a cold `/resume`
+   still reads `awaiting` after the last group. `<review-iterations>` is the number
    of Reviewer invocations that preceded this checkpoint (≥ 1; resets after a
    "changes"):
 
@@ -360,9 +393,9 @@ order:
    on: the awaiting line re-presents the pending checkpoint, the fix-loop line
    re-enters the implement→review loop at that iteration.
 
-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.
 
@@ -380,104 +413,12 @@ 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
+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.
 
-## 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.
-
 ## Architect (on-demand)
 
 The **Architect** is always installed but invoked **on-demand** — it is not a step in
@@ -505,172 +446,24 @@ 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
@@ -730,7 +523,8 @@ 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
@@ -767,29 +561,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.