@lemoncode/lemony 0.1.0 → 0.1.1-alpha.0

package/catalog/agents/ui-designer.md

@@ -1,25 +1,125 @@
 ---
 name: ui-designer
-description: Inactive stub slot (decision #11) — NOT active in this build; do not invoke. Kept in the catalog so a UI-design agent can be activated later without restructuring.
+description: Design director + design QA. Invoked on-demand by the Orchestrator at two moments — SPEC (DEFINE — author the ui-handoff.md design contract) and REVIEW (design + accessibility QA as a distinct lens, alongside the Reviewer). Always installed; not a linear step in the flow.
 role: UI Designer
-reification: slot
-invoked-when: inactive by default (decision #11)
-status: stub (inactive slot)
+reification: sub-agent
+invoked-when: SPEC (DEFINE — author ui-handoff.md) and REVIEW (design QA)
+origin: vendor
+vendor_version: '{{vendor_version}}'
 ---
 
 # UI Designer
 
-> **Stub (Sprint 0 S1) — inactive slot.** Not active in the Content Island pilot
-> (decision #11). Kept in the catalog so it can be activated without restructuring.
+A **sub-agent** with fresh context, always installed and invoked **on-demand** by
+the Orchestrator — never a linear step in DEFINE / TRIAGE. It mirrors the Architect's
+reification: present in the catalog, dispatched only when a task needs it. The
+Orchestrator decides _when_ (the activation gate) and owns the human dialogue and the
+labels; the UI Designer produces an artifact and reports.
 
-A **pluggable catalog slot**. When activated (Fase 2, e.g. paired with a Figma
-workflow), this role would help produce wireframes/mockups/prototypes and attach
-designs to issues.
+## Identity & taste
 
-## Notes
+You are a **design director with real taste** — the kind a solo dev without a designer
+wishes they had on call. Hold a high bar and bring conviction:
 
-- Not rendered into a client instance unless explicitly enabled in
-  `harness.config.yml: agents`.
-- Related ECC UI/UX skills are tracked on the Fase 2 radar (`motion-*`,
-  `a11y-architect`, `design-system`) — decision #42 — and are **not** part of the
-  vendor MVP.
+- **Default to deliberate, distinctive design.** The failure mode to avoid is generic
+  "AI slop" — the overused font, the predictable purple gradient, the cookie-cutter
+  card grid, the layout with no point of view. When the user has no opinion, propose a
+  direction, don't reach for the safe average.
+- **Have a point of view, hold it lightly.** Recommend boldly and explain _why_, then
+  let the user decide. It is their product; your job is to make the tasteful choice the
+  obvious one, not to impose it.
+- **Decisions, not know-how.** You set direction — tone, dials, layout, component and
+  state decisions, motion appetite, accessibility targets, microcopy. _How_ to apply
+  tokens to a stack, _how_ to avoid slop in code, _how_ to meet WCAG — that is the
+  implementer's and reviewer's craft, delivered through their skills. Never restate it.
+- **Ground taste in craft, not vibes.** Characterful typography, intentional colour
+  driven by semantic tokens, deliberate spacing and hierarchy, motion that carries
+  meaning, accessible by construction. Cite the reason a choice is good.
+
+## Two invocation moments
+
+The Orchestrator invokes you at exactly two points in an L1 task that touches UI
+(authority for the gate and label lifecycle is `orchestrator.md` §UI design):
+
+1. **SPEC — DEFINE.** After the grill, when the Orchestrator classifies the task as
+   touching UI, you author **`ui-handoff.md`** under `.claude/state/tasks/<id>/spec/`
+   — a sibling of the Spec Author's `requirements.md` / `design.md` / `tasks.md`. Run
+   the **`grill-ui`** interview to do it: a design-direction grill (one question at a
+   time, recommend-don't-impose) that inherits the PRD, consumes `docs/personas.md` if
+   present, and produces the handoff per its 11-section contract. The handoff captures
+   the **design decisions and targets** the implementer needs (not know-how — that
+   lives in skills). It is **part of completing the spec**, not a new lifecycle state:
+   the issue stays at `harness:status:spec-in-progress` while it is authored. You
+   **own** this artifact (the Spec Author owns the other three); when a later discovery
+   changes a design decision, the change routes back to you.
+   - **Personas persistence (Orchestrator-owned offer).** When `docs/personas.md` was
+     **absent** and `grill-ui` gathered personas inline (handoff §1), **flag that in your
+     return** — do not write `docs/personas.md` yourself mid-interview (it is client-owned,
+     and a sub-agent must not interrupt the human). The Orchestrator makes the persist offer
+     on its human-facing surface; if the human accepts, it re-dispatches you to author a
+     minimal `docs/personas.md` from the §1 personas — the client's own words, never a guessed
+     cast. Absent-and-declined is fine: the inline personas stay in the handoff for this task.
+   - **Token sync (on-demand, not a step).** If the project binds a design tool (a
+     `com.lemony.design-tool` provider in `docs/design-tokens.json`), check the drift state
+     (`lemony status`). When an export is pending **and the tool is connected**, offer to
+     project the change with the **`design-tool-sync`** skill — never sync silently, and skip
+     gracefully if the tool isn't connected. The human's explicit handle is
+     `/sync-design-tokens`.
+2. **REVIEW.** When an implemented UI change reaches review, the
+   Orchestrator invokes you as a **distinct lens** alongside the Reviewer (code), judging
+   the design and accessibility of what was built against the `ui-handoff.md` you authored.
+   You mirror the Reviewer's own shape — a **mechanical pre-pass**, then **judgment**,
+   then **one verdict**:
+   - **Mechanical pre-pass** (you have a shell). Run the deterministic gates:
+     `lemony design-tokens validate` and `lemony design-tokens contrast`, and detect and
+     run the project's own accessibility tooling (its a11y lint; axe on the rendered DOM
+     where the repo can render it). These are cheap facts, no judgment.
+   - **Judgment.** Run `design-critique` (does the build carry the handoff's point of
+     view?) and `a11y-audit` (the WCAG criteria the tools can't decide).
+   - **One design verdict.** Return a single pass/reject, with findings **grouped by
+     source** (tokens / accessibility / craft). You are one of exactly two review inputs
+     (you and the Reviewer); either lens rejecting routes back to the Implementer, and both
+     passing reaches the single human merge gate. The Reviewer's code lens is not
+     design-aware — that separation is deliberate.
+
+## The handoff contract
+
+`ui-handoff.md` follows the canonical **11-section** contract carried by the `grill-ui`
+skill (`ui-handoff-format.md`): (1) personas; (2) aesthetic direction — the dials
+(variance / motion / density) and optional tone preset; (3) screen inventory + nav/flow;
+(4) per-screen layout; (5) components; (6) states; (7) responsive; (8) motion/interaction;
+(9) accessibility; (10) microcopy; (11) token reference. Two principles run through it:
+
+- **Graduated altitude.** Decisions-altitude by default (reference the system, name the
+  variant, state what matters); the full component anatomy only for a novel or critical
+  component.
+- **Text-first, tokens by reference.** Screens travel as text — an inventory, a nav/flow
+  map and structural intent; tokens point at `docs/design-tokens.json`, never inlined.
+
+A `Status:` field marks the handoff `in_progress` (design being defined) vs `completed`.
+
+## Artifact ownership
+
+- **`ui-handoff.md`** lives in `tasks/<id>/spec/`, so it travels with the spec on the
+  task branch and is **archived with the spec** at closeout (`task-closeout` `git mv`s
+  the whole `spec/` directory into `_archive/<id>/`). You never create or close the
+  PRD; the Orchestrator owns that via `grill-with-docs`.
+
+## When the design is underspecified
+
+Don't guess past a consequential open fork. If a design decision needs input the PRD
+left open with more than one valid option, **run `raise-discovery`** (a
+`T2 UNSPECIFIED_DECISION`): write the entry to `tasks/<id>/discoveries.md`, return the
+one-line summary, and stop. The Orchestrator mediates with the human and re-invokes
+you with the decision. For an **independent** defect unrelated to your work, use
+`note-side-finding` instead — append it to your return summary and keep going.
+
+## Skills
+
+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`. `grill-ui` is your DEFINE interview;
+`design-critique` and `a11y-audit` are your two REVIEW lenses (run after the mechanical
+pre-pass — see "Two invocation moments"); `design-tool-sync` is the on-demand token
+connector to a design tool (`/sync-design-tokens`).
+
+{{SKILLS}}

package/catalog/commands/add-capability.md

@@ -6,8 +6,8 @@ allowed-tools: Read, Bash, Task
 # /add-capability
 
 Activate an **opt-in** capability that `install`/`doctor` reported as _available but not
-installed_. The harness reports these latent capabilities (#136) but never creates the
-convention artifact on its own (decision #8). This command is the **user-initiated**
+installed_. The harness reports these latent capabilities but never creates the
+convention artifact on its own. This command is the **user-initiated**
 "yes, add it" — it has the right agent author the artifact, then re-syncs so the gated
 skill installs.
 
@@ -38,7 +38,7 @@ latent ones.
      latent): dispatch the **Architect** (Task tool, fresh context) with the
      **`bootstrap-architecture`** skill. It reads the repo and authors the first
      `docs/architecture.md` — a holistic map **fitted to this project**, read from the
-     actual code, never a vendor template (decision #8). When it returns, show the human
+     actual code, never a vendor template. When it returns, show the human
      its summary and the new file — they own the result and may edit it. If the Architect
      reports the project has no meaningful architecture to map, it writes nothing: relay
      that to the user and **end the command** — skip step 4, force nothing.

package/catalog/commands/resume.md

@@ -11,7 +11,9 @@ Enter **RESUME** mode and pick up an existing task exactly as specified in
 is the single source for the procedure.
 
 `$ARGUMENTS` is the task `#id` or name to resume. If empty, list the open queue
-(`gh issue list -l harness:status:spec-ready`, `-l harness:status:in-progress`, and
+(`gh issue list -l harness:status:spec-ready`, `-l harness:status:in-progress`,
+`-l harness:status:spec-in-progress` for specs parked mid-authoring — including a UI task
+parked at `awaiting design definition` (+ `harness:needs-design`), and
 `-l harness:status:pending` for stubs captured by `/spinoff`), plus parked closeouts
 (`-l harness:status:closeout-pending --state all` — their issue is already **closed** by
 the task PR's `Closes #<id>`, so an open-only listing would miss them), and ask which to
@@ -23,8 +25,12 @@ In brief (authority is the orchestrator): for an SDD task the state and spec liv
 `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** (run it — read the spec cold, never self-approve);
-an `in-progress` one resumes at the active subtask. When `progress.md` records
-`Mode: step-by-step` (#176), the `## Step log` carries the step sub-state — resume
+an `in-progress` one resumes at the active subtask. A `spec-in-progress` task whose
+`progress.md` records `awaiting design definition` is a **UI design parked at "stop for
+handoff"** (authority: orchestrator §UI design): re-enter by dispatching the **UI
+Designer** to author/finish `ui-handoff.md`, then drop `harness:needs-design` and
+continue toward spec-ready. When `progress.md` records
+`Mode: step-by-step`, the `## Step log` carries the step sub-state — resume
 exactly there: `awaiting human checkpoint (step N/M)` re-presents that pending
 checkpoint (inspect / run / OK / changes / OK+downgrade); a `fix-loop iteration K`
 line re-enters the per-step implement→review loop at that iteration (authority:
@@ -33,7 +39,7 @@ the orchestrator §Step-by-step implementation). If the Mode line carries a
 resume at the active subtask as usual, not via the step loop (the Step log is then
 history, not sub-state).
 
-**Cross-machine pickup of an `in-progress` task** (#178): the branch on origin
+**Cross-machine pickup of an `in-progress` task**: the branch on origin
 carries the last **successful** best-effort WIP push — the Implementer pushes on
 signaling done, and step-by-step pushes at each checkpoint-wait. If a **local** copy
 of the branch is ahead of origin, prefer it (it is the newer state — this is what

package/catalog/commands/spinoff.md

@@ -37,8 +37,8 @@ code pointer). If empty, ask one short question to capture the symptom, then pro
 
    Omit `--parent` when there is no active task; omit `--severity` unless you can infer
    it cheaply (it is best-effort and never blocks capture). Omit `--kind` for an ordinary
-   defect — its one value, `architecture-drift`, is for `docs/architecture.md` map staleness
-   (#148): it tags the stub `harness:architecture-drift` so pickup routes it to the
+   defect — its one value, `architecture-drift`, is for `docs/architecture.md` map staleness:
+   it tags the stub `harness:architecture-drift` so pickup routes it to the
    Architect's `update-architecture` instead of a code change. The stub creation is
    **fail-loud** — a non-zero exit means the issue did not open, so surface it; do not
    pretend the defect was captured. The telemetry emit is **best-effort** — if only that

package/catalog/commands/sync-design-tokens.md

@@ -0,0 +1,29 @@
+---
+description: Sync design tokens between docs/design-tokens.json and the design tool (import or export).
+allowed-tools: Read, Write, Edit, Bash, Task, Skill
+---
+
+# /sync-design-tokens
+
+Sync the project's design tokens with its design tool. This command only **starts the flow** —
+it does not redefine it. The authority is the **`design-tool-sync`** skill, run by the UI
+Designer; follow the steps there.
+
+`$ARGUMENTS` selects the direction:
+
+- `import` — pull the tool's variables into `docs/design-tokens.json` (the primary flow). The
+  CLI maps them to the 3-tier model and prints a diff; you present it and the human curates
+  which slice lands before it is written.
+- `export` — project the JSON to the tool as an additive upsert (creates and updates, never
+  deletes tool-only variables). Preview the plan, push on confirmation, then record the drift
+  baseline only after the push succeeds.
+- _empty_ — check the drift state (`lemony status`) and, if an export is pending and the tool
+  is connected, offer `export`; otherwise report the current state.
+
+The design tool is a **projection** of the canonical JSON, never a peer source of truth.
+Detect the tool at runtime: read the `com.lemony.design-tool` binding at the root of
+`docs/design-tokens.json`; if no tool is declared, the project is pure-code and there is
+nothing to sync. If the declared tool's MCP server is not connected, skip gracefully with a
+note — the deterministic drift check still works without it.
+
+The human reviews every write (to the JSON and to the tool). Never sync silently.

package/catalog/harness.config.schema.json

@@ -104,6 +104,20 @@
         }
       },
       "additionalProperties": false
+    },
+    "design_tokens": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "scan_extensions": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
     }
   },
   "required": [

package/catalog/hooks/init.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Lemony — Claude Code SessionStart hook (decision #54).
+# Lemony — Claude Code SessionStart hook.
 #
 # Read-only orient run on every session entry filtered by source: orient on
 # {startup, resume, clear}; skip {compact} silently to keep long sessions free
@@ -37,7 +37,7 @@ ERRORS=()
 WARNINGS=()
 
 # ── Block 1 ─ harness.config.yml present and parseable ─────────────────────
-# Pure-bash validation (no yq — #41): presence of the four keys the harness
+# Pure-bash validation (no yq): presence of the four keys the harness
 # needs to operate, checked top-level plus block-scoped under `task_storage`
 # in one awk pass, then extraction of the two values the orient output uses.
 # Deep schema validation (formats, enums, did-you-mean typos) lives in
@@ -96,7 +96,7 @@ fi
 
 # ── Warning 1 ─ vendor version drift (config vs installed CLI) ─────────────
 # Resolve the CLI for the version read: the project-local devDependency bin first
-# (it survives an fnm Node switch, #113), then a global install. No npx fallback —
+# (it survives an fnm Node switch), then a global install. No npx fallback —
 # the orient hook stays inside its <1s p99 budget, so a non-resolvable CLI just
 # skips the drift check rather than paying a network round trip every session.
 LF_BIN=""
@@ -108,7 +108,7 @@ fi
 if [ -n "$CONFIG_VERSION" ] && [ -n "$LF_BIN" ]; then
   INSTALLED_VERSION="$("$LF_BIN" --version 2>/dev/null | head -1)"
   if [ -n "$INSTALLED_VERSION" ] && [ "$CONFIG_VERSION" != "$INSTALLED_VERSION" ]; then
-    # Direction-neutral by design (#172): the hook stays offline + node-free, so it
+    # Direction-neutral by design: the hook stays offline + node-free, so it
     # can't order the two versions reliably (no portable semver compare in bash —
     # BSD `sort` lacks `-V`). It flags the drift with a remedy safe in BOTH
     # directions; `lemony doctor` resolves the precise direction (it has a
@@ -116,10 +116,10 @@ if [ -n "$CONFIG_VERSION" ] && [ -n "$LF_BIN" ]; then
     WARNINGS+=("vendor version drift: harness.config.yml pins $CONFIG_VERSION, installed CLI is $INSTALLED_VERSION. If your CLI is newer, run \`lemony update\`; if it is older, upgrade your CLI (\`npm install\`) and do NOT run \`update\` (it would downgrade the repo). \`lemony doctor\` tells you which.")
   fi
 elif [ -n "$CONFIG_VERSION" ]; then
-  # #180: the repo pins a version but no CLI resolves (a teammate never ran
+  # The repo pins a version but no CLI resolves (a teammate never ran
   # `npm install`, no global). This used to be a silent skip — so a stale CLI could
   # drift with no signal at all. Emit a visible line instead, so the check's absence
-  # isn't mistaken for "no drift". Still offline (#129): no registry lookup, just a
+  # isn't mistaken for "no drift". Still offline: no registry lookup, just a
   # heads-up to install the project-local CLI.
   WARNINGS+=("could not verify CLI version: harness.config.yml pins $CONFIG_VERSION but no \`lemony\` CLI resolved. Run \`npm install\` to get the project-local one (then re-check with \`lemony doctor\`). Version-drift check skipped.")
 fi
@@ -163,7 +163,7 @@ fi
 # If the blocks didn't fire and we know the user, ensure the per-dev pointer
 # file exists with a fresh `session_start_ts` so `session-close.sh` can compute
 # `session_active_h` accurately. The refresh is a pure-awk in-place rewrite of
-# the frontmatter scalar (#41: no yq).
+# the frontmatter scalar (no yq).
 if [ "${#ERRORS[@]}" -eq 0 ] && [ -n "$GIT_USER_EMAIL" ]; then
   NOW_ISO="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
   # `%%@*` strips from the FIRST `@` (parity with status.ts's `email.split('@')[0]`),
@@ -223,11 +223,11 @@ EOF
   fi
 fi
 
-# ── Telemetry opt-out disclosure (#232, D11/D13) ───────────────────────────
+# ── Telemetry opt-out disclosure ───────────────────────────────────────────
 # Anonymous telemetry is on by default, so the first session — and any session
 # after the effective consent changes — must surface the opt-out. The sentinel +
 # fingerprint logic lives in TS (one resolver, no bash duplication of the env ›
-# local › config precedence + .strict() fail-safe — #232 G); init.sh just shells
+# local › config precedence + .strict() fail-safe); init.sh just shells
 # out when a CLI resolves ($LF_BIN from the version-drift check) and skips
 # otherwise. A CLI-less teammate is not left uninformed: `install` already showed
 # the notice once. Healthy-path only, and never fails the boot — the command
@@ -236,8 +236,8 @@ if [ "${#ERRORS[@]}" -eq 0 ] && [ -n "$LF_BIN" ]; then
   "$LF_BIN" telemetry notice 2>/dev/null || true
 fi
 
-# ── Telemetry catch-up send (#228, Phase 4) ────────────────────────────────
-# SessionEnd's send (#225) is the timely path; this is the safety net for a
+# ── Telemetry catch-up send ────────────────────────────────────────────────
+# SessionEnd's send is the timely path; this is the safety net for a
 # session that closed uncleanly (crash / SIGKILL / no SessionEnd fired) and so
 # never shipped its tail. Flush the unsent tail of events.jsonl now, on entry.
 # Detached in a subshell (`( … & )`) with output redirected so SessionStart never

package/catalog/hooks/lib/lemony.sh

@@ -1,10 +1,10 @@
 #!/usr/bin/env bash
-# Lemony — CLI launcher (issues #107 / #113).
+# Lemony — CLI launcher.
 #
 # The harness's hooks, agents and commands invoke the telemetry CLI (`lemony
 # emit …`). Calling the bare `lemony` binary is fragile: an `npx …` install
-# leaves nothing on PATH (#107), and a Node version manager (fnm/nvm) drops the
-# global bin when the active version changes (#113), so `command -v lemony`
+# leaves nothing on PATH, and a Node version manager (fnm/nvm) drops the
+# global bin when the active version changes, so `command -v lemony`
 # silently fails and telemetry is skipped.
 #
 # This launcher resolves the CLI deterministically, preferring the project-local

package/catalog/hooks/lib/playbook-scan.sh

@@ -2,21 +2,21 @@
 # Discover playbooks from two layers and expose lookup helpers used by the
 # require-playbook and suggest-playbook hooks.
 #
-# Layers (decision #11):
+# Layers:
 #   - Local:  <repo_root>/docs/playbooks/<topic>.md          (committed)
 #   - Global: <home>/.claude/playbooks/<topic>.md            (per-developer)
 # A local file shadows the global one for the same topic (filename stem).
 #
-# Frontmatter (see catalog/playbook-format.md):
+# Frontmatter (the playbook format):
 #   applies_to:  list of bash globs    → file paths that REQUIRE this playbook
 #   keywords:    list of regex strings → prompts that SUGGEST this playbook
 # Both lists are optional and independent; missing/empty lists are no-ops.
 #
 # Frontmatter is read with a SINGLE awk pass over every discovered playbook
-# (`_scan_frontmatter_tsv`), not one `yq` fork per playbook (decision #29 — the
+# (`_scan_frontmatter_tsv`), not one `yq` fork per playbook (the
 # per-file fork dominated hook latency, blowing the <50ms p99 target past ~5
 # playbooks). awk is also the only YAML reader now: the keyword format is
-# constrained to the awk-parseable subset (decision #35 — no `\b`/`\d` escape
+# constrained to the awk-parseable subset (no `\b`/`\d` escape
 # sequences), so `yq`'s extra fidelity was unused while its ~10-30ms cold fork
 # was pure cost. jq remains the keyword regex engine (Oniguruma, case-insensitive),
 # batched into one invocation across all keywords. Without jq, suggestion lookups
@@ -31,7 +31,7 @@
 # regress on stock macOS — keep the regex path even when bash 4+ is present.
 
 # Resolve the two playbook lookup dirs into PLAYBOOKS_LOCAL_DIR / PLAYBOOKS_GLOBAL_DIR
-# from `harness.config.yml`'s `paths` block (decision #28 — config-driven):
+# from `harness.config.yml`'s `paths` block (config-driven):
 #   paths.playbooks         → local layer, repo-relative   (default docs/playbooks)
 #   paths.playbooks_global  → global layer, ~ expanded     (default ~/.claude/playbooks)
 #
@@ -138,13 +138,13 @@ discover_playbooks() {
 # playbook path in a single awk pass: one line per item, `<file>\t<field>\t<value>`,
 # with surrounding single or double quotes stripped. This is the batched replacement for
 # the old per-file/per-field reader: at K playbooks the hooks went from K (or
-# 2K) subprocess forks to exactly one (decision #29).
+# 2K) subprocess forks to exactly one.
 #
 # awk reads the leading `---` frontmatter block of each file (resetting on
 # `FNR==1`, stopping at the second `---`). Supports the documented subset —
 # block lists (`field:\n  - item`) and inline lists (`field: [a, b]`) of scalar
 # strings. It does NOT process YAML escape sequences inside double-quoted
-# strings; keywords are constrained to that subset by decision #35 (no `\b`/`\d`
+# strings; keywords are constrained to that subset (no `\b`/`\d`
 # word boundaries). A file with no frontmatter contributes nothing.
 #
 # `FILENAME` is the path exactly as passed (ALL_PLAYBOOKS holds absolute paths),
@@ -204,8 +204,7 @@ _scan_frontmatter_tsv() {
   ' "$@" 2>/dev/null
 }
 
-# Convert a bash glob into an anchored POSIX-ERE regex. Supported subset (kept
-# in sync with catalog/playbook-format.md):
+# Convert a bash glob into an anchored POSIX-ERE regex. Supported subset:
 #   `**/`        — zero or more path components (so `**/x` matches `x` at root
 #                  too; this is what users intuitively expect even though bash
 #                  globstar would require at least one component)
@@ -228,7 +227,7 @@ _scan_frontmatter_tsv() {
 # Result is returned in the global `GLOB_RE`, NOT printed: callers run this once
 # per applies_to glob (5×K times at K playbooks), and a `regex="$(glob_to_regex)"`
 # command substitution would fork a subshell each time — the dominant cost of
-# the require hook at scale (decision #29). Assigning a global keeps it fork-free.
+# the require hook at scale. Assigning a global keeps it fork-free.
 glob_to_regex() {
   local glob="$1"
   local re=""
@@ -359,7 +358,7 @@ playbook_scan_for_path() {
 # contains a regex matching the prompt. A single jq invocation tests the prompt
 # (passed as a JSON-safe --arg, newlines intact) against every keyword regex
 # with jq's Oniguruma engine (case-insensitive), avoiding macOS BSD grep regex
-# limits and the old one-fork-per-keyword cost (decision #29). Distinct matching
+# limits and the old one-fork-per-keyword cost. Distinct matching
 # files are emitted in first-seen (discovery) order.
 playbook_scan_for_prompt() {
   local repo_root="$1"

package/catalog/hooks/session-close.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Lemony — Claude Code SessionEnd hook + `/pause` adaptor (decision #52).
+# Lemony — Claude Code SessionEnd hook + `/pause` adaptor.
 #
 # Fires:
 #   • automatically on SessionEnd (no `--manual`) → auto-close path: writes a
@@ -61,7 +61,7 @@ NOW_ISO="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 # ── Read current-<user>.md frontmatter ─────────────────────────────────────
 # An awk scrape of the leading frontmatter block — works for the shallow
 # scalars the harness writes, fails gracefully on anything richer. yq was
-# removed harness-wide (#41): jq is the sole hard dependency; awk/grep/git
+# removed harness-wide: jq is the sole hard dependency; awk/grep/git
 # (preinstalled) cover the rest.
 CURRENT_PATH="$REPO_ROOT/.claude/state/current-$USER_SLUG.md"
 SESSION_START_TS=""
@@ -148,7 +148,7 @@ EMIT_ARGS=(
 if [ -n "$ACTIVE_TASK" ] && [ "$ACTIVE_TASK" != "null" ]; then
   EMIT_ARGS+=(--task-id="$ACTIVE_TASK")
 fi
-# Resolve the CLI via the launcher (local devDependency → global → fail-fast, #107/#113)
+# Resolve the CLI via the launcher (local devDependency → global → fail-fast)
 # rather than a bare `command -v` on PATH, which an npx install or an fnm Node
 # switch leaves empty. Fail open — a missing launcher or a failed emit warns and
 # continues; the session must never be blocked by telemetry.
@@ -160,13 +160,13 @@ else
   echo "session-close: CLI launcher missing ($LF_CLI) — skipping event emit. Re-run \`lemony install\`." >&2
 fi
 
-# ── Fire-and-forget telemetry send (#225, Phase 1 walking skeleton) ─────────
+# ── Fire-and-forget telemetry send ─────────────────────────────────────────
 # Flush the unsent tail of events.jsonl to the ingest Worker. Detached in a
 # subshell (`( … & )`) so SessionEnd never waits on the network; `nohup` lets it
 # outlive a SIGHUP if the session tears down its process group before the send
-# completes. The CLI has its own hard per-request timeout (D4) and never throws —
+# completes. The CLI has its own hard per-request timeout and never throws —
 # output is discarded and a failure leaves the cursor untouched, so the next run
-# (or init.sh catch-up, #228) retries the same bytes. No-op when no endpoint is
+# (or init.sh catch-up) retries the same bytes. No-op when no endpoint is
 # configured. Telemetry must never block or break session exit.
 if [ -x "$LF_CLI" ]; then
   ( nohup "$LF_CLI" telemetry send >/dev/null 2>&1 & )
@@ -198,7 +198,7 @@ fi
 # ── Update current-<user>.md frontmatter pointers ──────────────────────────
 # Blank session_start_ts (the next SessionStart re-stamps it) and record the
 # close ts. awk in-place rewrite of the frontmatter scalars — mirrors the read
-# fallback above and the session_start_ts rewrite in init.sh (#41: no yq).
+# fallback above and the session_start_ts rewrite in init.sh (no yq).
 if [ -f "$CURRENT_PATH" ]; then
   # Rewrite each scalar if present; if a legacy/hand-edited pointer lacks the
   # line, append it just before the closing `---` (parity with the `yq -i` set

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

@@ -2,8 +2,8 @@
 
 > **Forward-only changelog** of the event schema defined in
 > [`tier2-events.md`](tier2-events.md). Readers add aliases here when they care
-> about renamed fields; the schema document is always the current truth (decision
-> \#51). One entry per release that touches the schema. ~30 min/release.
+> about renamed fields; the schema document is always the current truth. One
+> entry per release that touches the schema. ~30 min/release.
 
 Format per entry (one block per release):
 
@@ -33,16 +33,16 @@ Empty sections may be omitted.
 ### Added
 
 - `review_rejected.attributed_kind` — optional `agent` | `skill` | `playbook`: the
-  kind of component the friction is attributed to (#217). Omitted when the emitter
+  kind of component the friction is attributed to. Omitted when the emitter
   can't attribute.
 - `review_rejected.attributed_name` — optional free string (1-200): the component's
-  name (#217). Free-string by design this phase (measure-then-decide).
-- `step_completed.attributed_kind` — optional, as above (#217).
-- `step_completed.attributed_name` — optional, as above (#217).
+  name. Free-string by design this phase (measure-then-decide).
+- `step_completed.attributed_kind` — optional, as above.
+- `step_completed.attributed_name` — optional, as above.
 
 ### Changed
 
-- **Field-tag model → 5 axes, assigned per `(event_type, field)`** (#226, D9). The
+- **Field-tag model → 5 axes, assigned per `(event_type, field)`**. The
   old `sensitive` / `internal` / `metric` tags become `local-only` / `identity` /
   `free-text` / `internal-enum` / `metric`. **No field renamed, added, or removed** —
   only the axis column changed (the tag is now a property of the occurrence, fixing
@@ -60,17 +60,17 @@ Empty sections may be omitted.
 ### Added
 
 - `step_completed` — new event type emitted by the Orchestrator at each resolved
-  human checkpoint in step-by-step mode (#176). Fields: `task_id` (required),
+  human checkpoint in step-by-step mode. Fields: `task_id` (required),
   `step` (required, 1-based `tasks.md` task number), `review_iterations`
   (required, ≥ 1), `checkpoint_result` (required, `ok` | `changes` |
   `ok_downgrade`). One event per checkpoint — a "changes" step emits again when
   it re-checkpoints.
 - `task_done.mode` — optional `all_at_once` | `step_by_step`: the mode chosen at
-  the L1 approval gate (#176). Absent on L2 and on pre-#176 lines.
+  the L1 approval gate. Absent on L2 and on earlier lines.
 - `task_done.steps` — optional count of `step_completed` events for the task
   (≥ 1). Only meaningful when `mode` is `step_by_step`.
 - `review_rejected.step` — optional 1-based task number when the rejection came
-  from a per-step review (#176). Absent on full-pass and all-at-once rejections.
+  from a per-step review. Absent on full-pass and all-at-once rejections.
 
 ---
 
@@ -78,7 +78,7 @@ Empty sections may be omitted.
 
 ### Added
 
-- `followup_captured` — new event type emitted by `/spinoff` (#112) when a
+- `followup_captured` — new event type emitted by `/spinoff` when a
   non-blocking defect found mid-task is parked as a stub. Fields: `task_id`
   (required, the stub), `parent_task_id` (optional, the originating task),
   `severity` (optional, best-effort). Distinct from `bug_post_merge` (post-merge