@lemoncode/lemony 0.5.0 → 0.6.0

package/catalog/schemas/tier2-events.md

@@ -36,14 +36,14 @@ Every event line starts with this envelope. Per-type fields are added at the
 same top level — there is no nested `payload`, so Zod discriminated unions key on
 `type`.
 
-| Field             | Type   | Required | Axis            | Notes                                                                                                                                                                                                                                                                 |
-| ----------------- | ------ | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `type`            | string | yes      | `internal-enum` | One of the 9 event types listed below. Discriminator.                                                                                                                                                                                                                 |
-| `ts`              | string | yes      | `metric`        | UTC ISO 8601 with `Z` suffix (e.g. `2026-05-28T14:30:00.000Z`). **No local offsets.**                                                                                                                                                                                 |
-| `user`            | string | yes      | `local-only`    | `git config user.email` of the actor. Never exported in any tier.                                                                                                                                                                                                     |
-| `project`         | string | yes      | `identity`      | `task_storage.repo` slug (e.g. `acme/widgets`), from `harness.config.yml`. **Never `OWNER/REPO`** — the CLI refuses to emit while that placeholder is the value (see [Placeholder guard](#placeholder-guard)).                                                        |
-| `task_id`         | string | no       | `identity`      | Task issue id (e.g. `42`) when the event has a task context. Absent on global events; `session_closed` carries it when HEAD is a `harness/<id>-<slug>` task branch. A per-project correlator — only meaningful alongside `project`, so it shares the `identity` axis. |
-| `harness_version` | string | yes      | `metric`        | `version` of the **installed** `@lemoncode/lemony` package — _not_ `vendor_version` from config.                                                                                                                                                                      |
+| Field             | Type   | Required | Axis            | Notes                                                                                                                                                                                                                                                                                                       |
+| ----------------- | ------ | -------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`            | string | yes      | `internal-enum` | One of the 9 event types listed below. Discriminator.                                                                                                                                                                                                                                                       |
+| `ts`              | string | yes      | `metric`        | UTC ISO 8601 with `Z` suffix (e.g. `2026-05-28T14:30:00.000Z`). **No local offsets.**                                                                                                                                                                                                                       |
+| `user`            | string | yes      | `local-only`    | `git config user.email` of the actor. Never exported in any tier.                                                                                                                                                                                                                                           |
+| `project`         | string | yes      | `identity`      | `task_storage.repo` slug (e.g. `acme/widgets`), from `harness.config.yml`. **Never `OWNER/REPO`** — the CLI refuses to emit while that placeholder is the value (see [Placeholder guard](#placeholder-guard)).                                                                                              |
+| `task_id`         | string | no       | `identity`      | Task issue id (e.g. `42`) when the event has a task context. Absent on global events; `session_closed` carries it when the live branch is a `harness/<id>-<slug>` or `harness/closeout-<id>` task branch. A per-project correlator — only meaningful alongside `project`, so it shares the `identity` axis. |
+| `harness_version` | string | yes      | `metric`        | `version` of the **installed** `@lemoncode/lemony` package — _not_ `vendor_version` from config.                                                                                                                                                                                                            |
 
 ### Placeholder guard
 
@@ -115,8 +115,9 @@ forward-compatible — readers dispatch on `type` and ignore unknowns.
 
 Emitted by `session-close.sh` on `SessionEnd` or `/pause` (manual). One per
 session. The envelope's `task_id` is derived from the live branch at close time
-(`harness/<id>-<slug>` → `<id>`); a session closed on the default branch or a
-detached HEAD carries none.
+(`harness/<id>-<slug>` or `harness/closeout-<id>` → `<id>`) — while a rebase has
+HEAD detached, the branch being rebased; a session closed on the default branch or
+any other detached HEAD carries none.
 
 | Field              | Type    | Required | Axis            | Notes                                                                                                           |
 | ------------------ | ------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------------- |
@@ -148,17 +149,18 @@ Emitted by the Orchestrator when it transitions `spec-in-progress → spec-ready
 
 ### 4. `task_done` _(P5)_
 
-Emitted by the Orchestrator at closeout (after `gh pr view` confirms `MERGED`,
-before `git rm` of the task state).
+Emitted by the Orchestrator at closeout **finalize** — after the closeout PR,
+which archives the spec and drops the task's `progress.md`, has merged.
 
-| 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. |
+| 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), and on an L1 task whose gate choice closeout could not recover.                                                                                                                                                                                          |
+| `steps`             | number | no       | `metric`        | Count of **distinct steps** (distinct `step` values) across this task's `step_completed` events (≥ 1, int). Only meaningful when `mode` is `step_by_step`; < total groups after a mid-task downgrade. Before 0.6.0 it counted every event — see [history](tier2-events-history.md).                                                                                                                    |
+| `checkpoints`       | number | no       | `metric`        | Count of `step_completed` events for this task (≥ 1, int) — one per resolved human checkpoint, so a step sent back counts again. Sent together with `steps`; `checkpoints − steps` is the task's extra checkpoint rounds — normally its `changes` answers at step checkpoints. Not counted: any human gate after a downgrade to all-at-once (it emits nothing), and change requests at the merge gate. |
 
 ### 5. `review_rejected` _(P5)_
 
@@ -211,7 +213,9 @@ post-merge / production signal; conflating them would dirty the post-merge metri
 ### 9. `step_completed` _(step-by-step mode)_
 
 Emitted by the Orchestrator each time a human checkpoint **resolves** in
-step-by-step mode (L1 opt-in, chosen at the approval gate). One event per
+step-by-step mode (L1 opt-in, chosen at the approval gate), through the
+`checkpoint` verb that also makes the resolution's commits — or by hand,
+late, when that call never ran for an answer. One event per
 checkpoint, not per step: a step the human sends back ("changes") emits again
 when it re-checkpoints, with the same `step`. This is the signal that justifies
 (or condemns) the mode — the rate of checkpoints that catch things, and where
@@ -272,7 +276,11 @@ A writer (the `lemony emit` CLI):
 2. Merges per-type fields into the same top level (no nested `payload`).
 3. Validates against the Zod schema for `type` (each schema is `.strict()`,
    so an unknown key — typically a typo'd `--task-iid` flag — **rejects**
-   loud). Never writes a partial line.
+   loud). `task_done` also rejects step counts that contradict each other:
+   `steps`/`checkpoints` on a task whose `mode` is not `step_by_step`,
+   `checkpoints` without `steps`, and `checkpoints < steps`. These rules run at
+   emit time only — readers do not re-check lines already written. Never writes
+   a partial line.
 4. Appends the JSON line via `fs.appendFile` (single `O_APPEND` `write(2)`,
    POSIX-atomic up to `PIPE_BUF`) to `.claude/state/events.jsonl`. Creates the
    file (and parent dir, scaffolded by `install`) when missing.

package/catalog/skills/build-ui/SKILL.md

@@ -10,7 +10,9 @@ invoked-by: [implementer]
 # Build UI
 
 The implementer's **build method**: turn a `ui-handoff.md` (the design contract) plus
-`docs/design-tokens.json` (the token source of truth) into UI code that applies the
+`docs/design-tokens.json` (the token source of truth — or the path `design_tokens.file` names
+in `harness.config.yml`, when set; read that file wherever this skill says
+`docs/design-tokens.json`) into UI code that applies the
 project's tokens correctly, carries the design's point of view instead of generic
 defaults, and is accessible by construction.
 
@@ -44,7 +46,8 @@ v3→v4 jump turns it into a lie); the live model does not. So this skill names
 
 ## Tokens-as-code — the contract
 
-`docs/design-tokens.json` is the **single, client-owned source of truth**, a 3-tier
+`docs/design-tokens.json` is the **single, client-owned source of truth** (or the path
+`harness.config.yml` names in `design_tokens.file`, when set — read that file instead), a 3-tier
 W3C-DTCG model: **primitive** (raw scale values) → **semantic** (intent: `color.surface`,
 `space.inset.md`) → **component** (a component's specific slots). Two rules hold on every
 stack:

package/catalog/skills/design-tool-sync/SKILL.md

@@ -20,6 +20,11 @@ ahead. That asymmetry shapes everything here:
 - **drift** is one-directional and deterministic: "has the JSON changed since the last
   export?" — a pure-JSON check that needs no tool connection.
 
+**Which file.** `docs/design-tokens.json` is the default path. When `harness.config.yml` sets
+`design_tokens.file`, the path it names (relative to the repository root) is the token file:
+read the binding from it and expect the CLI's import and export to act on it, wherever this
+skill says `docs/design-tokens.json`. Never create a second file at the default.
+
 You are invoked two ways: by `/sync-design-tokens` (the human's explicit handle, argument
 `import` or `export`), and at DEFINE when the drift check shows an export is pending and the
 current user has the tool connected.
@@ -70,34 +75,70 @@ variables and the DTCG JSON:
 - `name` — the variable's dotted path. Map it to/from the tool's own grouping separator.
 - `value` for a literal; `ref` for an alias (the name of the variable it points at).
 - `modes` — per-theme overrides (the base theme is `value`/`ref`, not repeated).
+- Every `value` and mode value is a **string** — `"1024"`, not `1024` — and every `ref` a
+  non-empty one; each variable carries a `value` or a `ref` (a `value` beside a `ref` is
+  ignored), and `modes` is an object whose mode names are not blank nor `__proto__`. A name
+  is dot-separated segments, none empty, none starting with `$`, none `__proto__`, not just
+  a tier (`primitive`, `semantic`, `component`), and no two variables share one. The CLI
+  refuses a file that breaks any of these, naming the variable (and the mode, for a mode
+  value).
 
 The CLI maps this to the 3-tier DTCG model: `ref` → an alias `{path}`, `modes` →
-`$extensions["com.lemony.modes"]`, and the tier follows the path (a literal defaults to
-`primitive`, an alias to `semantic` when the name carries no tier).
+`$extensions["com.lemony.modes"]`, and the tier follows the path. A name without a tier
+lands on the one tier `docs/design-tokens.json` already has it in; otherwise a variable that
+is literal in every mode defaults to `primitive`, and one that is an alias in its base value
+or any mode to `semantic` (a primitive is literal in every mode). A bare `ref` — or a bare
+`{alias}` mode value — resolves to the tiered path its target lands at in the same neutral
+file, or to the one tier the token file has it in.
 
 ## import — tool → JSON
 
 1. **Read** the tool's variables over MCP and write them to a neutral file (a temp path).
 2. **Preview** the diff (writes nothing):
    `lemony design-tokens import --from=<neutral-file>`. It prints, per token, the target tier
-   and `new` / `changed` (with the old → new value) / `unchanged`.
+   and `new` / `changed` (each thing that changes, old → new: the value, the `$type`, each
+   mode) / `unchanged`. When
+   `docs/design-tokens.json` already fails validation it adds a `Warning:` saying so: the
+   apply will refuse any slice that leaves it failing, so tell the human before curating.
 3. **Present and curate.** Walk the human through it: which new tokens to take, which changes
    to accept, and — where a tool-origin name is ambiguous — whether a literal belongs in
    `primitive` or `semantic`. The human owns the slice.
 4. **Apply** the agreed slice:
    `lemony design-tokens import --from=<neutral-file> --apply --only=<dotted,paths>`.
    This does the additive merge into `docs/design-tokens.json` deterministically (it
-   bootstraps the file if it does not exist yet). Then run `lemony design-tokens validate` to
-   confirm the result is well-formed.
+   bootstraps the file if it does not exist yet and the slice writes something). A changed
+   token keeps what the neutral file does not carry — `$description`, a contrast pairing,
+   other extensions — and an unchanged one is left as it is. A token the tool cannot hold
+   (see export) is never written over: the preview shows it as a change from
+   `(outside the sync: <why>)`, and the apply lists it as not applied. It writes nothing
+   when the merged file would fail validation — typically a `semantic` alias whose
+   `primitive` target is neither in the file nor in the slice: add the target to the same
+   `--only`, or fix the file first. When the neutral file does not carry the target at
+   all, the refusal says so: create it in the tool first, or leave out what references
+   it. A fault no slice fixes, such as a `primitive` that aliases, is named the same way:
+   fix that variable in the tool, or leave it out. An `--only` path no variable lands at
+   is refused rather than skipped. A refusal prints the preview again, so the slice can be
+   re-curated from the paths it lists. Then run `lemony design-tokens validate` to confirm
+   the result is well-formed.
 
 ## export — JSON → tool
 
-1. **Plan.** Read the tool's current variables over MCP into a neutral file, then:
+1. **Plan.** `export` refuses (exit 1) a `docs/design-tokens.json` that fails
+   `lemony design-tokens validate` — fix the file first. Read the tool's current variables
+   over MCP into a neutral file, then:
    `lemony design-tokens export --tool-state=<tool-state> --out=<projection-file>`. It prints
    the additive upsert plan (how many to create, how many to update — **never any deletes**)
    and writes the projection the tool should hold to `<projection-file>`. The `--tool-state`
    is optional; without it every variable is planned as a create (the upsert is idempotent by
-   name either way).
+   name either way). A tool variable named without its tier (`color.brand`) is matched to the
+   path `import` lands it at (`primitive.color.brand`), so when you push, write into that
+   existing variable rather than creating a tiered twin. A token a tool variable cannot hold
+   is not projected: a composite (a shadow, a typography, a cubic Bézier — an object or
+   array `$value`), a token whose modes the neutral format cannot carry (a mode value that
+   is not text, a number or a boolean, a blank or `__proto__` mode name, a modes extension
+   that is not an object), and any alias to one of those. The plan names each as "not
+   projected", with why — say so to the human. `--out` takes a file path (not a pipe, nor
+   the token file itself).
 2. **Confirm.** Show the plan; the human approves.
 3. **Push.** Write the projection's variables into the tool over MCP — create new ones, update
    changed ones, leave tool-only variables untouched.

package/catalog/skills/grill-ui/SKILL.md

@@ -75,7 +75,10 @@ the design direction it settles can inform the spec. Before the first question:
   [Persisting personas](#persisting-personas-when-absent)) — an opt-in offer on your human-facing
   surface, never an unasked write.
 - **Consume `docs/design-tokens.json` if it exists** — the single source of truth for tokens. The
-  handoff §11 points at it; you never inline token values.
+  handoff §11 points at it; you never inline token values. That is the default path: when
+  `harness.config.yml` sets `design_tokens.file`, the path it names (relative to the repository
+  root) is the token file — read, scaffold, bind and point at that path wherever this skill says
+  `docs/design-tokens.json`, and never create a second file at the default.
 - **Read `docs/architecture.md` if it exists** — orient against the system's shape so design
   proposals don't contradict existing surfaces. Absent is fine; never push the user to create it.
 

package/catalog/skills/grill-ui/ui-handoff-format.md

@@ -84,7 +84,8 @@ Every section is **N/A-able** per task: mark a section N/A rather than padding i
 
 ## 11. Token reference
 
-Reference `docs/design-tokens.json` — the single, client-owned source of truth, a 3-tier
+Reference the token file — `docs/design-tokens.json`, or the path `design_tokens.file` names in
+`harness.config.yml` — the single, client-owned source of truth, a 3-tier
 W3C-DTCG model (`primitive` → `semantic` → `component`). **Never inline token values here; point at
 the file.** If the project has no token file yet, the interview offers to scaffold one (derived from
 the answers) or to connect a design tool; if the human declines both, say so and capture it as an

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

@@ -71,19 +71,33 @@ Without a script, each probe is yours to run. The mechanics:
   as accounted-for, is the ledger contract's rule, not this skill's — the floor asks
   for accounting, never exhaustion. One or two well-aimed probes per logic-bearing
   file usually answer the question.
-- **The round trip is one composite command with the revert unconditional.** Apply the
-  mutation, run the focused test, and restore — `;`-separated or a scripted loop,
-  **never `&&` before the revert** (a red test must still revert), and never separate
-  edit / test / revert calls. It leaves the tree exactly as you found it:
+- **The round trip is one composite command whose revert is a trap, installed before
+  the mutation.** Apply the mutation, run the focused test, and restore — in one
+  shell invocation, never separate edit / test / revert calls, and never a revert
+  that a red test or an interrupt can skip. The session can be stopped at any instant
+  (Esc stops the running command with SIGTERM), and a mutant left behind reads as
+  real work to whoever resumes. The `EXIT` trap restores on every way out — green,
+  red, or interrupted:
 
   ```bash
-  sed -i.bak '128s/>=/>/' src/queue.ts; \
-  npx vitest run src/queue.spec.ts; \
-  mv src/queue.ts.bak src/queue.ts
+  ( trap 'mv -f src/queue.ts.bak src/queue.ts 2>/dev/null' EXIT; \
+    trap 'kill $! 2>/dev/null; exit 130' INT TERM HUP; \
+    sed -i.bak '128s/>=/>/' src/queue.ts; \
+    npx vitest run src/queue.spec.ts & wait $! )
   ```
 
   (Line-addressed on purpose — one targeted mutant per trip keeps the kill
-  attributable; the `.bak` the in-place edit leaves is the revert.)
+  attributable; the `.bak` the in-place edit leaves is the revert. The subshell
+  scopes the traps to the probe; the `INT TERM HUP` trap stops the runner and turns
+  the signal into an ordinary exit so the `EXIT` trap runs. The test runs in the
+  background under `wait` because a shell runs no trap while a foreground child is
+  still running, and Claude Code follows Esc's SIGTERM with a SIGKILL within a
+  second or two: `wait` returns on the signal, so the restore lands first. The
+  `kill $!` matters for a Ctrl-C too — a background job in a non-interactive shell
+  ignores SIGINT. Only a `SIGKILL` before the trap runs or a machine crash can
+  still strand a mutant — `git status` after the
+  trip shows the tree exactly as you found it, and a leftover `.bak` is the sign
+  one was stranded.)
 
   A **killed** mutant (the focused test went red) is the good outcome; a **survivor**
   (still green on broken code) is the finding. Batching buys trips, never

package/catalog/skills/prd-to-spec/SKILL.md

@@ -209,7 +209,11 @@ close, is always read as the declaration: it is reported if it does not end the
 even when a list ends a later line. Keep every other `(R<n>)` mention in detail prose
 **mid-line**. When two lists end continuation lines the validator cannot tell which is
 the declaration and reports the task; on a task that declares no list, the one
-line-ending mention is read as its declaration, and a mid-line one is reported.
+line-ending mention is read as its declaration, and a mid-line one is reported. An
+aside that must open a parenthesis with a requirement id opens it with `per` —
+`(per R42, …)` — because a bare `(R42…` falls under the rules above exactly like a
+declaration, and can be elected over the real list, sometimes silently. A `per` aside
+is never read, so it never stands in for the list: the task still declares its own.
 
 The review evidence ledger's validator enumerates each group's review slice from these
 refs; a task it cannot read is reported as `malformed-task-refs` — a spec defect that
@@ -220,14 +224,32 @@ when the task reaches green, with the task's commit. Write every task `- [ ]`; t
 validator reports a task still `[ ]` in a group the loop has passed
 (`unticked-completed-task`), so the file tracks the progress its shape promises.
 
+**Line shapes — read by the same script.** A task line is `- [ ]` or `- [x]` and a bare
+`T<n>` id, at the task list's own indentation; a group header is exactly `## Group <n>`,
+numbered from 1, with `Group` in English even when the spec is written in another
+language. A line that looks like one but is not — an in-progress `[-]`, a suffixed
+`T12b` or `T1.1`, a numbered `1. [ ]` item, a `- T6` with no box, a task inside a `>`
+quote, a `T<n>` sub-item indented under another task, `### Group 3`, `## Group 0`, a
+digit-less `## Group P`, a translated `## Grupo 2 — … _(…)_` — is reported
+(`malformed-task-line`, `malformed-group-header`), never skipped; a note bullet about a
+task opens with
+something other than its `T<n>`. Every `T<n>` is used once in the file
+(`duplicate-task-id` otherwise). Detail prose may run to several paragraphs: a blank
+line inside a task is fine while the next line stays indented at least to the task's
+text (two spaces under `- [ ]`); less, and it is no longer the task's. Code fences and
+`>` quotes are never read as tasks, but a task or header shape inside one is reported
+too — a quoted sample looks exactly like a task under a fence left open — so quote
+samples without a `T<n>` id or a group header.
+
 Rules: order so the first task is a tracer bullet; never "write all tests" then
 "write all code"; keep each task small enough to verify on its own. Grouping never
 changes task granularity — checkboxes stay atomic and TDD runs per task; only review
 and checkpoint frequency follow the groups (all-at-once mode ignores the headers).
-Tasks added mid-implementation (from a discovery) default to **their own group** —
-they are risk by definition, and grouping rule 5 applies to them unchanged — but they
-are added **after** the spec gate, and no later gate presents a group header, so their
-tags get no human reading at all. Tag them for the record; do not rely on anyone
+Tasks added mid-implementation (from a discovery) take the **next free `T<n>`** (never
+a suffixed `T12b`) and default to **their own group** — they are risk by definition,
+and grouping rule 5 applies to them unchanged — but they are added **after** the spec
+gate, and no later gate presents a group header, so their tags get no human reading at
+all. Tag them for the record; do not rely on anyone
 catching a wrong one.
 
 ### 5. Self-check before handing off

package/catalog/skills/review-pr/SKILL.md

@@ -37,7 +37,7 @@ Read the repo's `CLAUDE.md` (and `CONTEXT.md` if present). Summarize in ≤ 50 l
 code-style rules, comment conventions, naming, architecture constraints. This is what
 the analysis judges "against project convention" by.
 
-### 2. Analyze (single sub-agent, the review lenses as a checklist)
+### 2. Analyze (one pass — a single sub-agent, or inline — the review lenses as a checklist)
 
 Spawn **one** `Explore` sub-agent with the full diff, the changed-files list, and the
 project context. Its prompt walks the five review lenses as a checklist — **not** five
@@ -58,6 +58,12 @@ The agent returns a strict JSON array of findings (see [reference.md](reference.
 the exact prompt and schema). It returns `[]` when the diff is clean — it must **not**
 manufacture findings to seem thorough.
 
+**A Reviewer, or no `Agent` tool?** A Reviewer never spawns, whatever its tools (the
+opening rule of the Reviewer contract, `.claude/agents/reviewer.md`), and an agent at
+Claude Code's nesting depth limit has no `Agent` tool unless it is a fork. Then walk
+the five lenses yourself, in this context, with the same prompt as your checklist, and
+produce the same JSON array; the rest of the flow is unchanged.
+
 ### 3. Dry-run
 
 Print the findings as a numbered table (don't post anything yet):

package/catalog/skills/review-pr/reference.md

@@ -2,8 +2,9 @@
 
 ## Analysis agent prompt
 
-Pass this to the single `Explore` sub-agent. The five lenses are a **checklist one
-agent walks**, not a fan-out.
+Pass this to the single `Explore` sub-agent — or, as a Reviewer or with no `Agent`
+tool (SKILL.md §2), walk it yourself. The five lenses are a **checklist one agent
+walks**, not a fan-out.
 
 ```
 You are reviewing a GitHub PR diff. Find real issues worth posting as inline review

package/catalog/templates/claude-code/agents.md.tpl

@@ -105,7 +105,8 @@ A task deserves the harness if it is **specifiable**, **verifiable**, or
    checks precondition (`.claude/hooks/lib/merge-pr.sh --approve-issue <issue>`)
    and never lands on red, absent, or still-pending checks without asking — nor
    content that no longer matches what the Reviewer's APPROVE reviewed (the
-   stale-approve guard; a clean update-branch stays valid, any content change
+   stale-approve guard; a clean update-branch or a task-state write under
+   `.claude/state` stays valid, any other content change
    routes back to re-review). The task stays at `in-review`
    until merged.
 10. **Closeout** — `task-closeout`: confirm the merge via `gh`, run the three Architect

package/catalog/templates/claude-code/harness.config.yml.tpl

@@ -83,16 +83,25 @@ rollback:
 #   - test
 #   - build
 
-# Design tokens (`design-tokens validate` / `design-tokens contrast`).
+# Design tokens (the `design-tokens` verbs, and the token lines of `doctor` / `status`).
 # `scan_extensions`: the anti-hardcode scan inspects a built-in set of UI/style
 # extensions (.css/.scss/.ts/.tsx/.vue/.svelte/.astro/.js/.mdx/.html/…). Add extra
 # suffixes here for a stack the built-ins don't cover — additive, never a replacement.
 # Default none.
-# `verify`: a command line `design-tokens contrast` runs after its own WCAG checks
+# `verify`: a command line `design-tokens contrast` runs alongside its own WCAG checks
 # (through `sh -c`, in the repo root) — your design system's own verifier for the rules
 # only it can know (palette under colour-vision-deficiency simulation, property grammar,
-# CSS scans). Its output is forwarded; a non-zero exit fails the gate. Default none.
+# CSS scans). Its output is forwarded; a non-zero exit fails the gate. It runs on every
+# path: with no token file only the WCAG pair check is skipped, and a file
+# that cannot be read or parsed is reported alongside it — never the verifier you
+# declared. Default none.
+# `file`: where the token file lives, relative to the repository root — for a DTCG
+# file kept (or generated) somewhere other than docs/design-tokens.json. Every
+# design-tokens verb, `doctor` and `status` read it from here. An absolute path, a `\`
+# separator, a path that leads out of the repository or names its root, or one ending
+# in `/` or `/.` is a config error. Default docs/design-tokens.json.
 # design_tokens:
 #   scan_extensions:
 #     - .foo
 #   verify: pnpm exec my-design-system verify
+#   file: design/tokens.json