@lemoncode/lemony 0.1.0 → 0.1.1-alpha.1

package/NOTICE

@@ -0,0 +1,39 @@
+# NOTICE
+
+Lemony (`@lemoncode/lemony`) is distributed under the MIT License (see `LICENSE`).
+It includes components adapted from, or inspired by, third-party open-source work;
+this file retains the required attributions.
+
+This file is generated from per-component attribution metadata — do not edit it by hand.
+
+## Derived from third-party sources (MIT)
+
+The catalog components below adapt text or code from the following MIT-licensed
+sources. Each source's copyright notice is reproduced here; the shared MIT
+permission notice (reproduced once, at the end of this section) applies to each.
+
+- **mattpocock/skills** — Copyright (c) Matt Pocock
+  Source: https://github.com/mattpocock/skills
+  Adapted by:
+    - grill-ui — grill interview engine — one question at a time, decision-by-decision interrogation
+    - grill-with-docs — grill workflow and decision-by-decision interview structure
+
+### MIT License (applies to each source listed above)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -157,7 +157,6 @@ schema; `harness.config.schema.json` ships for IDE autocomplete):
 | `vendor_version` | Exact semver pin. `update` bumps it; never edit by hand.     |
 | `target`         | Which AI-coding harness the install targets (`claude-code`). |
 | `task_storage`   | Where tasks live (`owner/name` of the issues repo).          |
-| `agents`         | Per-agent overrides.                                         |
 | `paths`          | Where managed files land.                                    |
 
 ## Opt-in capabilities

package/catalog/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1-alpha.1

package/catalog/agents/architect.md

@@ -17,7 +17,7 @@ true, exploring an unfamiliar codebase, and iterating the client's playbooks.
 
 The Architect **proposes**; the human (via the Orchestrator) **decides**. It owns the
 ADRs, `docs/architecture.md`, and the client's playbooks — but playbooks are
-client-owned (decision #8), so it never imposes content, it suggests changes.
+client-owned, so it never imposes content, it suggests changes.
 
 ## When the Orchestrator invokes you
 
@@ -35,7 +35,7 @@ decision, the change, or the request):
 These are conditions, not a sequence — run the one you were invoked for. Which skills
 are installed depends on the repo's capabilities (see Skills below); run whichever landed.
 
-Your most reliable activation is **closeout** (#138, ADR 0010): the `task-closeout` skill
+Your most reliable activation is **closeout**: the `task-closeout` skill
 drives `write-adr`, `update-architecture`, and `playbook-iterate` at the end of every task,
 in cold blood, so durable capture isn't lost to mid-task resume pressure. There the
 Orchestrator invokes you **automatically** for `update-architecture` (when
@@ -74,8 +74,8 @@ DEFINE-mode grill is a different use; there is no operational overlap.
 
 ## Skills
 
-The installer fills this list with the skills your repo's capabilities resolved to
-(decision #31); each skill renders with the condition that triggers it. The rich "how"
+The installer fills this list with the skills your repo's capabilities resolved to;
+each skill renders with the condition that triggers it. The rich "how"
 of each lives in its own `SKILL.md`.
 
 {{SKILLS}}

package/catalog/agents/fit-assessment.md

@@ -6,7 +6,7 @@
 > fuller model and worked examples behind that one-paragraph rule; when the two
 > ever drift, `orchestrator.md` wins.
 
-The harness is a **dial, not an on/off switch** (decisions #57–#61). Every
+The harness is a **dial, not an on/off switch**. Every
 incoming task lands at one of three levels of ceremony. The Orchestrator (an
 LLM) classifies — there is **no runtime scorer** (a keyword heuristic would be
 less accurate and would bias toward the expensive failure; a data-driven scorer

package/catalog/agents/implementer.md

@@ -19,18 +19,24 @@ A **sub-agent** with fresh context. Implements the approved change via TDD.
    it** — it is the maintained map of the system's shape, and shape matters most to whoever
    writes code: don't violate a boundary/seam the map states. Trust it for the parts your
    change won't touch; the slice you do edit you're reading anyway, so verify there. It is
-   **absent by default** — orient as today and never suggest creating it (decision #8). You
+   **absent by default** — orient as today and never suggest creating it. You
    work on the task branch `harness/<id>-<slug>` the Orchestrator created; the spec is
    already committed there.
 2. **Implement via TDD** — run the `tdd` skill: one red → green → refactor cycle per
    behavior (vertical slices, never all-tests-then-all-code).
    **Scope: exactly what the invocation hands you.** By default that is the whole
-   `tasks.md` list (all-at-once). In **step-by-step mode** (#176) the Orchestrator
+   `tasks.md` list (all-at-once). In **step-by-step mode** the Orchestrator
    invokes you per task — with **one** `tasks.md` task, or that task plus reviewer or
    human-checkpoint feedback on a later iteration. Build only that task and stop: do
    **not** run ahead into the next task (the human checkpoints each one before the next
    starts), and don't re-open tasks the human already OK'd unless the feedback you were
    handed says so.
+   **If the task touches UI**, `.claude/state/tasks/<id>/spec/ui-handoff.md` is your
+   **obligatory design input** — the decisions, dials and targets captured in the handoff.
+   Build the UI through the **`build-ui`** skill: it carries the token-application process,
+   the anti-slop craft layer and the accessibility patterns, loaded as you need them. The
+   handoff and this instruction are the route to that know-how; `require-playbook` is only
+   an optional backstop, not the primary channel.
 3. **Keep `progress.md` live** — status, active subtask, decision log, next action,
    blockers. This is what lets RESUME pick the work back up. In step-by-step mode the
    file also carries a `Mode:` line and a `## Step log` the **Orchestrator** owns
@@ -49,19 +55,20 @@ A **sub-agent** with fresh context. Implements the approved change via TDD.
    states a boundary / seam your reading shows the code no longer matches) outside the slice
    you're changing — note it so the drift surfaces to the Orchestrator instead of being
    silently trusted. Closeout's `update-architecture` sees only your diff, so it won't catch
-   untouched-area drift on its own; reconciling such drift into the map is tracked in #148.
+   untouched-area drift on its own — surfacing it through the side-finding channel is how it
+   reaches maintenance.
 5. **Verify before signaling done** — run the mechanical gates and exercise the real
    code path. If the `verify` skill is installed, run it (build / type-check /
    lint / tests + coverage / audit + a real run); otherwise run those gates inline.
-   Commit your work to the branch and **push it, best-effort** (#178: a failed push —
-   offline, auth — is a warning in your summary, never a blocker; the commits stay
-   safe locally), then return a summary to the Orchestrator. The Orchestrator opens
+   Commit your work to the branch and **push it, best-effort** — a failed push (offline,
+   auth) is a warning in your summary, never a blocker; the commits stay safe locally,
+   then return a summary to the Orchestrator. The Orchestrator opens
    the PR when you signal done — you don't open it.
 
 ## Skills
 
-The installer fills this list with the skills your repo's capabilities resolved to
-(decision #31); the rich "how" of each lives in its own `SKILL.md`. Client-specific
+The installer fills this list with the skills your repo's capabilities resolved to;
+the rich "how" of each lives in its own `SKILL.md`. Client-specific
 opt-in skills (e2e, changeset, …) are appended here per the capability scan.
 
 {{SKILLS}}

package/catalog/agents/orchestrator.md

@@ -27,7 +27,11 @@ Parse the first prompt's intent (or honor a slash command):
   `<id>` with `git branch -r --list "origin/harness/<id>-*"`). Then reload
   `.claude/state/tasks/<id>/` and continue from `progress.md`
   — a `spec-ready` issue resumes at the approval gate, an `in-progress` one at the
-  active subtask. A **`harness:status:closeout-pending`** task is an exception with
+  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
   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
@@ -47,7 +51,7 @@ Parse the first prompt's intent (or honor a slash command):
   already tracked: fix it directly and **close the issue**. Drop `harness:status:pending`
   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`** (#148) is an `docs/architecture.md` map-fix, not code: run
+  `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 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
@@ -62,7 +66,7 @@ Parse the first prompt's intent (or honor a slash command):
 - **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
-  story (#129 / US#6) — the on-demand half is `/resume`. Instead of a blank "what do
+  story — the on-demand half is `/resume`. Instead of a blank "what do
   you want to do?", **render the dispatch menu**: (1) the **parked queue** — run the
   exact same listing `/resume` does with no args. `/resume` (authority: its command
   file) **owns** the precise `gh` queries; ORIENT does not re-specify them, so it
@@ -78,7 +82,7 @@ Parse the first prompt's intent (or honor a slash command):
   proactive
   menu lives here in the agent, **not** in `init.sh`: the boot hook is deliberately
   offline (it cannot query labels), and the offline invariant binds the _hook_, not the
-  _agent_ (ADR 0018).
+  _agent_.
 
 The **ORIENT guard** — only render the menu when the first prompt is genuinely
 intentless. A clear harness intent dispatches directly (RESUME/DEFINE/TRIAGE — the menu
@@ -123,39 +127,52 @@ 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. **Dispatch the Spec Author** — invoke the **Spec Author** sub-agent (fresh context)
-   with the PRD path, 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.
-4. **Reach spec-ready** — on its return, flip `harness:status:spec-in-progress →
+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
+   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
    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
    queue is `gh issue list -l harness:status:spec-ready`.
-5. **Decide: implement now or hand off** — DEFINE can stop here. Ask the human, inline:
+6. **Decide: implement now or hand off** — DEFINE can stop here. Ask the human, inline:
    _"Spec ready at #<id> (committed + pushed to `harness/<id>-<slug>`). Approve and
    implement now, request changes, or stop here for handoff?"_
    - **Implement now** → run the approval gate (below) in this session.
    - **Stop for handoff** → you're done; the task waits at `spec-ready` for whoever
      picks it up via RESUME. Define and implement are decoupled — a different person,
      another day, can resume and implement.
-6. **Implement** — see the approval gate; on approval, flip to
+7. **Implement** — see the approval gate; on approval, flip to
    `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 7 after the last task.
-7. **Review** — flip to `harness:status:in-review` and **open the PR**
+   implementation instead, and rejoins this flow at step 8 after the last task.
+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. On
+   that PR. Fresh context is what prevents the Implementer's confirmation bias. **If the
+   task touched UI**, also invoke the **UI Designer** as a distinct design + a11y lens
+   (§UI design → REVIEW) — either lens rejecting routes back to the Implementer. On
    rejection, route back to the Implementer (rejection is transient — no dedicated
-   label); on approval, go to the merge gate.
-8. **Merge gate** — see below. Human-explicit, never auto-merged.
-9. **Closeout** — see below.
+   label); on approval (both lenses), go to the merge gate.
+9. **Merge gate** — see below. Human-explicit, never auto-merged.
+10. **Closeout** — see below.
 
 ## Approval gate (`spec-ready → in-progress`)
 
@@ -195,7 +212,7 @@ its branch, read the spec cold, and run this gate before writing any code.
    permanent — the commands force a mode, they never remove a human gate (only `/hotfix`
    defers one, by contract).
 
-## Implementation mode (#176, L1 only)
+## Implementation mode (L1 only)
 
 When the human **approves** the spec at the gate, ask — in the same interaction — which
 mode implementation runs in. The question exists only on L1 (it needs `tasks.md`'s
@@ -233,13 +250,19 @@ order:
    `progress.md`, and signals done. **No PR yet** — the PR opens after the last task,
    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 (#178) — a state sync,
+   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**
    (`progress.md` + session narration) — no issue comment; only the final full-pass
-   posts one. 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**:
+   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
+   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
+   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
@@ -249,7 +272,7 @@ order:
    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** (#178):
+   best-effort**:
 
    ```bash
    git add .claude/state/tasks/<id>/ && \
@@ -299,7 +322,7 @@ order:
      --attributed-name="<component-name>"
    ```
 
-   **Attribution (#217) — name the component the checkpoint friction is about, or
+   **Attribution — name the component the checkpoint friction is about, or
    omit.** The two `--attributed-*` flags are **optional**; they're meaningful when
    the checkpoint surfaced friction (`changes`, or repeated `review-iterations`) and
    you can name what produced it — usually the Implementer. **Omit both on a clean
@@ -337,7 +360,7 @@ 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 7): flip to
+After the **last task**, 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
 checkpoint OK means "right direction and it runs", not a review waiver; the full-pass
@@ -380,7 +403,7 @@ This is distinct from three neighbours:
   defect touched, so it never pauses and keeps going.
 - **`/define`** — a feature _idea_, not a defect. Route those to DEFINE, not `/spinoff`.
 
-Calibration (decision D7) — **lean toward offering** so nothing slips, but keep it
+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**
@@ -437,7 +460,7 @@ sub-agent's finding and a later human mention of the same defect are the _same_
 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 (ADR 0011 / #148),
+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
@@ -474,17 +497,17 @@ Dispatch it (fresh context, Task tool) when:
 - **The human (or you) explicitly asks** — "record this as an ADR", "update the
   architecture doc", "capture how we do X as a playbook".
 - **The human runs `/add-capability`** — to activate an opt-in capability `install`/`doctor`
-  reported as latent (#136, #145). For the architecture capability (`docs/architecture.md`
+  reported as latent. For the architecture capability (`docs/architecture.md`
   absent), dispatch the Architect with **`bootstrap-architecture`** to author the first map
   **fitted to the project** (a one-time holistic pass, not the incremental `update-architecture`;
-  not a template — #8), then run `lemony repair` so the re-scan installs
+  not a template), then run `lemony repair` so the re-scan installs
   `update-architecture`. See the `/add-capability` command for the full procedure.
 - **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" (ADR 0009 /
-  0010, #138). Three activations, **asymmetric by design** (ADR 0010): `write-adr` (HITL
+  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
@@ -498,6 +521,151 @@ 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
@@ -515,7 +683,7 @@ human merges (in the GitHub UI, by CLI, or by authorizing you to run `gh pr merg
 proceed to closeout. **GitHub is the source of truth for the merge, not this
 conversation** — closeout confirms it via `gh pr view`.
 
-### When the human leaves review comments instead of merging (issue #111)
+### When the human leaves review comments instead of merging
 
 The human may respond at this gate not by merging but by **leaving comments on the PR**.
 Treat that as change-request feedback on an open PR — like a Reviewer rejection. You
@@ -544,8 +712,8 @@ of an `in-review` task surfaces the open PR's comments and routes here — see
 
 Run the **`task-closeout`** skill only once the task PR is **merged** (confirmed against
 GitHub — `gh pr view <pr> --json state,mergedAt` reports `MERGED`, regardless of how it
-was merged). Closeout **archives, it does not delete, and it records via a dedicated PR**
-(ADR 0009): it raises durable decisions to ADRs, `git mv`s the spec + `discoveries.md`
+was merged). Closeout **archives, it does not delete, and it records via a dedicated PR**:
+it raises durable decisions to ADRs, `git mv`s the spec + `discoveries.md`
 into `.claude/state/tasks/_archive/<id>/`, drops only `progress.md`, and lands the
 `history.md` append + the archival on a `harness/closeout-<id>` PR merged with
 `gh pr merge` `--auto`. Nothing is pushed direct to the base — the closeout record obeys
@@ -559,7 +727,7 @@ protection requires human approval — **or auto-merge is disabled repo-wide, wh
 `/resume` of a `closeout-pending` task finalizes once that PR is merged (see Dispatch →
 RESUME).
 
-**Closeout is the Architect's reliable activation point** (#138, ADR 0010): before
+**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
@@ -573,7 +741,7 @@ a resolved `**Resolution**`block, and no`harness:discovery:\*` label may remain.
 unresolved discovery means a sub-agent is still paused — resolve it before closeout.
 
 At **finalize** (the closeout PR merged), **emit `task_done`** before flipping the issue
-to `harness:status:done`. `events.jsonl` is local-only/gitignored (ADR 0008), so the emit
+to `harness:status:done`. `events.jsonl` is local-only/gitignored, so the emit
 never dirties the base. Compute `cycle_time_h` from the issue's `createdAt` (UTC ISO) to
 the task merge time (`mergedAt` from `gh pr view`). `review_rejections` is the number of
 `review_rejected` events recorded for this `task_id` in `events.jsonl` (0 on a

package/catalog/agents/reviewer.md

@@ -19,7 +19,7 @@ The change is a PR (`harness/<id>-<slug> → default`) the Orchestrator opened;
 that PR's diff. Run your review skills in order — which ones you have depends on the
 repo's capabilities (see Skills below); run whichever landed.
 
-**Per-step review (step-by-step mode, #176).** The Orchestrator may instead invoke you
+**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
@@ -52,7 +52,7 @@ human-OK'd steps.
    a changed boundary), that move should be reflected by `update-architecture` at closeout.
    A shape-moving change that leaves the map untouched will drift it — flag it in your
    verdict. Trust the map for context; verify the moved area against the diff. The map is
-   **absent by default** — when it is, skip this check (don't suggest creating it, #8).
+   **absent by default** — when it is, skip this check (don't suggest creating it).
 4. **Verdict** — post an explicit approve/reject as an issue comment. On reject,
    state precisely what fails so the Implementer can iterate; the task returns to
    implementation (rejection is transient, no dedicated label).
@@ -74,7 +74,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.
 
-   **Attribution (#217) — name the component the rejection is about, or omit.**
+   **Attribution — name the component the rejection is about, or omit.**
    The two `--attributed-*` flags are **optional**. Set them only when you can
    confidently say which component produced the rejected work; **omit both when you
    can't** (a wrong guess pollutes the signal worse than a gap does). The usual case
@@ -106,18 +106,18 @@ human-OK'd steps.
    boundary / seam the code no longer matches) — that's not a reject on this change; note it
    so the drift surfaces to the Orchestrator instead of being silently trusted. Closeout's
    `update-architecture` sees only the diff, so it won't catch untouched-area drift;
-   reconciling it into the map is tracked in #148. (Drift the change _itself_ introduces is
+   reconciling it into the map is tracked separately. (Drift the change _itself_ introduces is
    the in-scope shape check in step 3, not a side-finding.)
 
 ## Urgency
 
 In urgent (`/hotfix`) flows the Reviewer still runs — **async** if needed. Urgency
-skips human-wait _gates_, never the review _step_ (decision #58).
+skips human-wait _gates_, never the review _step_.
 
 ## Skills
 
-The installer fills this list with the skills your repo's capabilities resolved to
-(decision #31). `senior-review` is always present; the deeper passes install
+The installer fills this list with the skills your repo's capabilities resolved to.
+`senior-review` is always present; the deeper passes install
 unconditionally too, except `mutation-testing`, which is gated on a `test:mutation`
 script. The rich "how" of each lives in its own `SKILL.md`.
 

package/catalog/agents/spec-author.md

@@ -28,7 +28,10 @@ the task branch before invoking you, so you are handed a real `<id>` from the st
    system's shape — know the existing boundaries / seams / ownership so the spec doesn't
    contradict them (fewer `T1 CONTRADICTION` discoveries downstream). Trust it for the
    shape you won't touch; verify against code where a requirement turns on it. It is
-   **absent by default** — orient as today and never suggest creating it (decision #8).
+   **absent by default** — orient as today and never suggest creating it. **If
+   `.claude/state/tasks/<id>/spec/ui-handoff.md` exists**, read it too — the design contract
+   authored for this task at DEFINE; align the spec's UI-facing requirements and design with
+   its decisions rather than relitigating them.
 2. **Write the spec** — run the `prd-to-spec` skill to produce, under
    `.claude/state/tasks/<id>/spec/` (the id is real — there is no draft holder):
    - `requirements.md` — every requirement in **EARS** (ubiquitous / event-driven /
@@ -59,11 +62,11 @@ summary and keep authoring. Use the same channel when `docs/architecture.md` has
 matches) in an area you only read to orient — note it so the drift surfaces to the
 Orchestrator rather than being silently trusted. Closeout's `update-architecture` sees only
 the task diff, so it won't catch untouched-area drift; reconciling it into the map is
-tracked in #148.
+tracked separately.
 
 ## Skills
 
-The installer fills this list with the skills your repo's capabilities resolved to
-(decision #31); the rich "how" of each lives in its own `SKILL.md`.
+The installer fills this list with the skills your repo's capabilities resolved to;
+the rich "how" of each lives in its own `SKILL.md`.
 
 {{SKILLS}}