@lemoncode/lemony 0.1.2 → 0.3.0

package/catalog/agents/ui-design.md

@@ -0,0 +1,147 @@
+# UI design (DEFINE + REVIEW) — Orchestrator companion
+
+> Vendor companion to `.claude/agents/orchestrator.md` (the hat). **Read on
+> demand, never at boot** — and never just to evaluate the activation gate: the
+> gate's canonical two-part statement lives in the orchestrator's L1 step 3 and
+> is evaluated there, core-only. Read this file when that gate has FIRED, when an
+> implemented UI change reaches review (`tasks/<id>/spec/ui-handoff.md` exists),
+> when resuming a task parked `awaiting design definition`, or on
+> `/sync-design-tokens`.
+
+UI design threads into an L1 task that touches UI — never a linear step. **The interactive
+design interview is yours**: a sub-agent can't talk to the human, so at DEFINE **you** run
+the `grill-ui` skill on your human-facing surface and author the `ui-handoff.md` contract.
+The **UI Designer** sub-agent — always installed, invoked **on-demand**, your only invoker —
+is your design **critic and QA**: at DEFINE it reviews the handoff you just authored (before
+the Spec Author runs); at REVIEW it runs a mechanical pre-pass (the deterministic
+`design-tokens` gates + the project's a11y tooling) then the `design-critique` and
+`a11y-audit` judgment lenses, and returns one design verdict. You own the human dialogue, the
+`ui-handoff.md` artifact, and the labels; it critiques and reports.
+
+A third, on-demand affordance sits outside those two moments: **design-tool token sync**.
+When the human runs `/sync-design-tokens` (or accepts the DEFINE offer when a drift check
+shows an export is pending), dispatch the UI Designer to run its `design-tool-sync` skill.
+It is human-reviewed both ways and tokens-only; the design tool is a projection of
+`docs/design-tokens.json`, never a peer source of truth.
+
+## Activation gate
+
+Canonical statement: the orchestrator's **L1 step 3** — evaluated there, core-only,
+before this file is ever read. Rationale worth keeping in mind when it fired on a
+borderline call: a wasted handoff stub is cheaper than UI shipped with no design
+pass.
+
+## Design-stop offer
+
+When the gate fires, **put `harness:needs-design`** on the issue and offer the human,
+inline, in one line — three choices:
+
+> This task touches UI. (1) **Continue** — define the design now, as part of the spec;
+> (2) **Stop for handoff** — park here so a designer picks it up later; (3) **No UI after
+> all** — skip design.
+
+- **Continue** → **run `grill-ui` yourself** — the interactive design interview on your
+  human-facing surface — authoring `ui-handoff.md` under `tasks/<id>/spec/`. Then dispatch
+  the **UI Designer** (fresh context, Task tool) with the `<id>` and branch to **critique**
+  the handoff, and resolve its findings — tighten the handoff, re-ask the human, or
+  record an open question — before the Spec Author runs. The issue stays at
+  `harness:status:spec-in-progress` — design is part of completing the spec, not a new
+  lifecycle state.
+- **Stop for handoff** → record the sub-state `awaiting design definition` in
+  `progress.md`, commit and push the task state to the branch, and stop. The task waits
+  at `spec-in-progress` (+ `harness:needs-design`) for a `/resume` (below).
+- **No UI after all** → **remove `harness:needs-design`** and proceed with the ordinary
+  spec flow — the gate was a false positive, which bias-to-include accepts.
+
+## Persisting personas (offer)
+
+`docs/personas.md` is **client-owned** — the harness consumes it, never imposes it. When your
+`grill-ui` interview captured personas **inline** because `docs/personas.md` was **absent** (§1
+of the handoff), make the offer — a human-facing choice, so it is yours:
+
+> The design defined these personas inline. Persist them to `docs/personas.md` so future UI
+> tasks reuse them? (yes / no)
+
+- **Yes** → write a minimal `docs/personas.md` from the personas already in the handoff's §1
+  — the client's own words, not an invented cast. Then continue toward spec-ready.
+- **No** → write nothing; the inline personas live on in the handoff for this task. The next
+  UI task simply asks again.
+
+Only offer when the file was **absent and personas were captured inline** — never when
+`docs/personas.md` already exists (it was consumed, nothing to persist) and never unasked.
+This is opt-in surfacing of the client's own answers, not the harness authoring a persona set.
+
+## Design-tokens & design-tool on-ramp (offer)
+
+`docs/design-tokens.json` and a design-tool connection are **client-owned inputs** — consumed if
+present, never imposed. A repo adopting the harness fresh has neither, and silence there is a dead
+end. So when your `grill-ui` interview finds **either absent**, surface it as an opt-in offer (a
+human-facing choice, so it is yours) rather than only an open question:
+
+- **No `docs/design-tokens.json`** → offer to **scaffold** a starter token set derived from the
+  direction the interview just settled (the client's own colours/type/spacing, not a vendor
+  template), plus an opt-in follow-up to generate a sensible starter set for the aspects the
+  interview didn't cover. On **yes**, write the file and run `lemony design-tokens validate` before
+  closing; on **no**, capture it as an open question.
+- **No `com.lemony.design-tool` binding** → offer to **connect a design tool** (write the binding +
+  first import via the UI Designer's `design-tool-sync` skill / `/sync-design-tokens`), or **stay
+  pure-code**. Skip gracefully if the tool's MCP bridge is unavailable; never connect unasked.
+
+The mechanics live in the `grill-ui` skill; you run the offers on your human-facing surface. Only
+offer when the input is **absent** — never re-offer a token file or binding that already exists.
+
+## Label put/remove
+
+`harness:needs-design` is an **orthogonal presence flag** (same family as
+`harness:architecture-drift`), never a status:
+
+- **Put** it as soon as the gate classifies the task as touching UI and design is not
+  yet complete.
+- **Remove** it the moment `ui-handoff.md` is **complete** — at or before the flip to
+  `harness:status:spec-ready`. **Complete** = the handoff carries **this task's** design
+  decisions (its sections hold real content, not the verbatim placeholder template), the UI
+  Designer's critique **passed** (or you resolved its findings), and **no** open design fork
+  remains (an open fork means design is still open — keep the label and resolve it first).
+  Ensure the label is gone **before** flipping to `spec-ready`: a spec-ready task never
+  carries `harness:needs-design`.
+
+## `awaiting design definition` sub-state + /resume re-entry
+
+A task parked at "stop for handoff" sits at `harness:status:spec-in-progress` with
+`progress.md` recording the sub-state `awaiting design definition`. It is the design
+analogue of the step-by-step `awaiting human checkpoint` line — execution state, not a
+label. `/resume <id>` re-enters there: check out the branch, read the captured context,
+resume the `grill-ui` interview yourself to finish `ui-handoff.md`, dispatch the UI Designer
+to critique it, then remove `harness:needs-design` and continue toward spec-ready. The resume
+queue surfaces the parked design (`resume.md` lists `spec-in-progress` too).
+
+## REVIEW — the design lens
+
+When an implemented UI change reaches review (L1 step 8), invoke the **UI Designer** as
+a **distinct lens** alongside the Reviewer (code). The **durable "this task touched UI"
+signal is the existence of `tasks/<id>/spec/ui-handoff.md`** — `harness:needs-design` is
+already gone by spec-ready, so it can't be the cue; the handoff artifact persists and
+survives a cold `/resume`, so it is what to check. Either lens rejecting routes back to
+the Implementer (rejection is transient — no dedicated label); both passing reaches the
+single human merge gate (two inputs, one gate).
+
+The UI Designer's lens mirrors the Reviewer's own shape — a **mechanical pre-pass** (the
+deterministic `lemony design-tokens validate` + `lemony design-tokens contrast` gates, plus the
+project's a11y tooling), then **judgment** (`design-critique` + `a11y-audit`), returning
+**one design verdict** with findings grouped by source (tokens / accessibility / craft).
+The Reviewer's code lens stays design-unaware; you still see exactly two review inputs.
+
+**Deterministic vs judgment, by level.** The two deterministic gates are cheap, agent-free
+facts, so they run **per-step** on UI-touching steps in step-by-step mode (a bad contrast
+in step 2 must not ride to step 6 — see the orchestrator's §Step-by-step implementation);
+the project's a11y lint rides the per-step lint the same way. The **judgment lenses run
+full-pass only** — design is holistic, and a mid-component critique is noise. There is no
+per-step design agent and no new cap: a full-pass design rejection routes back like any
+other rejection. (`lemony design-tokens validate` / `contrast` also run in CI independently of
+review.)
+
+## Closeout
+
+`ui-handoff.md` lives in `tasks/<id>/spec/`, so closeout archives it with the rest of
+the spec (`task-closeout` `git mv`s the whole `spec/` into `_archive/<id>/`) — no
+special handling.

package/catalog/agents/ui-designer.md

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

package/catalog/commands/add-capability.md

@@ -43,10 +43,10 @@ latent ones.
      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.
 
-   - **Any other latent capability** (e.g. a `test:mutation` script → `mutation-testing`):
-     its guided activation is **not wired yet**. Say so plainly and **end the command** — do
-     **not** fabricate the artifact. (Tracked as a follow-up; the activation behaviour plugs
-     in here.)
+   - **Any other latent capability**: it has no guided activation. Say so plainly and
+     **end the command** — do **not** fabricate the artifact. (Guided activation beyond
+     the architecture map is a deliberate non-feature, not a pending seam; wiring one up
+     for a future capability is its own decision.)
 
 4. **Re-sync so the gated skill installs** — only when step 3 actually wrote the artifact.
    Run:

package/catalog/commands/define.md

@@ -22,3 +22,10 @@ self-approve, and move the `harness:status:*` labels per the lifecycle.
 If the task turns out to be too small for the full ceremony — nothing to specify,
 verify, or review — nudge toward `/triage` (L2) or `/bypass` (L3) per the task-fit
 dial (`.claude/agents/fit-assessment.md`). When in doubt, keep it in the harness.
+
+The dial's ceiling is the **partition question**: if the closed PRD bundles separable,
+independently mergeable wants, the orchestrator asks — at the define's close, before
+opening the task — whether to cut the feature into several issues, each its own
+branch, PR and merge gate (authority: `.claude/agents/partition.md`, read on trigger).
+An approved cut opens a parent partition-plan issue (`harness:partition-plan`, never a
+task) and Part 1 as a normal task; later parts open at their turn.

package/catalog/commands/hotfix.md

@@ -23,7 +23,21 @@ question to capture it, then proceed.
    issue, so it auto-closes on merge).
 3. **Skip the human-wait gates.** Do **not** pause for an approval gate, and do
    **not** wait on the merge gate — merge/ship as soon as the test is green and CI
-   passes. This is the one path where you don't wait for a human to sign off first.
+   passes. "As soon as CI passes" is mechanical, not a vibe: execute the merge
+   through the checks-precondition executor
+   (`.claude/hooks/lib/merge-pr.sh <pr> --squash` — no `--approve-issue` here:
+   the hotfix review runs async, so there is no APPROVE to bind at merge time;
+   the stale-approve guard belongs to the reviewed task path), which waits for green and
+   refuses red or absent checks — urgency skips the _human_ wait, never the
+   verification. This is the one path where you don't wait for a human to sign
+   off first. On any non-zero exit (red / no checks / timeout / no verdict),
+   act on the exit code exactly as the Orchestrator's "Executing an authorized
+   merge — the checks precondition" section prescribes: surface the real state
+   and ask. Urgency never authorizes `--force` on your own initiative — a fire
+   does not lower the bar for merging on red or unverified checks. One
+   adaptation: a standing no-checks answer has no closeout PR to ride on this
+   path — commit the `merge.allow_no_checks: true` line onto the **hotfix
+   branch** before merging, so it lands with the hotfix PR.
 4. **Run the Reviewer asynchronously.** After shipping, dispatch the **Reviewer**
    sub-agent (fresh context, `senior-review`) on the merged change. The review is not
    skipped — it's deferred. If it surfaces problems, file a follow-up fix (a normal

package/catalog/commands/pause.md

@@ -50,3 +50,8 @@ A two-step pause:
 
 The hook prints `git status --porcelain` after emitting — it never
 auto-commits. Decide what (if anything) to stage and commit before leaving.
+Exception — a task running **pre-commit review ON** (orchestrator §Pre-commit
+review ON): do **not** commit; the zero-commit deferral binds `/pause` too.
+Leave the staged save-point untouched (it survives the session; staging
+anything now is the mid-experiment `add` the protocol forbids), note the pause
+in `progress.md` — disk-only, per the mode's contract.

package/catalog/commands/resume.md

@@ -16,8 +16,11 @@ is the single source for the procedure.
 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
-pick up.
+the task PR's `Closes #<id>`, so an open-only listing would miss them), and **partition
+parents** (`-l harness:partition-plan` — not tasks; one with unticked parts surfaces as
+"partition in progress: next part per the plan" — or "waiting on #<id> (Part <j>)" when
+the next row is blocked by an in-flight child — and resuming it starts the next eligible
+part, or names the blocker, per `.claude/agents/partition.md`), and ask which to pick up.
 
 In brief (authority is the orchestrator): for an SDD task the state and spec live
 **only on the branch** until merge — `git fetch` and check out `harness/<id>-<slug>`
@@ -27,21 +30,41 @@ In brief (authority is the orchestrator): for an SDD task the state and spec liv
 resumes at the **approval gate** (run it — read the spec cold, never self-approve);
 an `in-progress` one resumes at the active subtask. A `spec-in-progress` task whose
 `progress.md` records `awaiting design definition` is a **UI design parked at "stop for
-handoff"** (authority: orchestrator §UI design): re-enter by **resuming the `grill-ui`
+handoff"** (authority: `.claude/agents/ui-design.md`): re-enter by **resuming the `grill-ui`
 interview yourself** to finish `ui-handoff.md` (the UI Designer then critiques it), then
 drop `harness:needs-design` and continue toward spec-ready. When `progress.md` records
 `Mode: step-by-step`, the `## Step log` carries the step sub-state — resume
 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:
-the orchestrator §Step-by-step implementation). If the Mode line carries a
+checkpoint (inspect / run / OK / changes / OK+downgrade; in all-at-once under
+pre-commit review ON the line carries no `(step N/M)` counter — same
+re-entry); a `fix-loop iteration K`
+line re-enters the per-step implement→review loop at that iteration; an
+`awaiting ledger retry (step N/M, retry 1/1)` line — or its full-pass twin
+`awaiting ledger retry (full pass, retry 1/1)` — re-runs
+`lemony review-ledger validate` on the sidecar on disk (`--anchor` per the
+orchestrator: per-step, the `(anchor <oid>)` on the step-log line; full pass, the
+fingerprint merge-base — except pre-commit review ON's pre-gate twin, which anchors
+at the recorded single-group anchor, = the branch head: ON defers every commit) —
+green re-presents the gate
+the pass feeds, red goes to that gate with the verb's lines, the single retry being spent
+(authority: the orchestrator §Step-by-step implementation). If the Mode line carries a
 `(downgraded to all-at-once at step N)` suffix, the remaining tasks run all-at-once —
 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**: 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
+signaling done, and step-by-step pushes at each checkpoint-wait. Exception: a task
+running **pre-commit review ON** defers every commit and push until a checkpoint OK
+— in-flight work and its `progress.md` updates exist only in the implementing
+machine's worktree, so from another machine the branch reads as of the last OK'd
+group; before the first OK it is **indistinguishable from idle** (the knob record
+itself is deferred — the documented price of the mode, orchestrator §Pre-commit
+review ON). When config pins `implementation.pre_commit_review: on`, or the
+branch's `progress.md` already carries the `Pre-commit review: on` line (some OK
+landed), surface the mode instead of concluding the task is idle. A discovery
+pause still surfaces cross-machine via its labels and issue comment, though the
+full `discoveries.md` entry stays machine-local. If a **local** copy
 of the branch is ahead of origin, prefer it (it is the newer state — this is what
 makes same-machine resume lossless). From a **different** machine, anything committed
 after the last successful push is unreachable and undetectable (origin is
@@ -51,9 +74,14 @@ checkpoint is a conscious replay, not a silent assumption. An `in-review` one re
 **merge gate**: surface the open PR's review comments and run the merge-gate procedure
 (route change-requests back to the Implementer, then offer to post threaded replies —
 authority is the orchestrator). A `closeout-pending` task has **nothing to check out** —
-its task PR already merged and its state is archived under `_archive/<id>/`: re-enter the
-`task-closeout` skill at its **finalize** step (step 6) once the open
-`harness/closeout-<id>` record PR is merged — the skill owns the finalize operations
+its task PR already merged and its state is archived under `_archive/<id>/`: if the open
+`harness/closeout-<id>` record PR is still unmerged, **re-run the self-merge executor on
+it** (`.claude/hooks/lib/merge-pr.sh harness/closeout-<id> --squash --delete-branch` —
+the skill's step-5 line verbatim, flags included: a bare invocation is rejected by
+`gh pr merge` non-interactively and would re-park forever. The park may have been a
+transient pending/red that has since settled; a repeat not-green re-parks), then re-enter the
+`task-closeout` skill at its **finalize** step (step 6) once that PR is merged — the
+skill owns the finalize operations
 (delete the task branch, flip to `done`, emit `task_done`, close the issue). A
 `pending` stub has **no branch
 yet** — nothing to check out: read the captured context (the title is the symptom; the

package/catalog/commands/triage.md

@@ -6,14 +6,15 @@ allowed-tools: Read, Write, Edit, Bash, Task, Skill
 # /triage
 
 Enter **TRIAGE** mode and run the **L2 lightweight round-trip** exactly as specified
-in `.claude/agents/orchestrator.md` (§"L2 lightweight round-trip"). This command only
-**forces the mode** — the orchestrator file is the single source for the steps.
+in `.claude/agents/triage.md` (the orchestrator's lazy companion). This command only
+**forces the mode** — that file is the single source for the steps.
 
 `$ARGUMENTS` is the bug report (the symptom, repro, or error). If empty, ask one
 question to capture it, then proceed.
 
 In brief (authority is the orchestrator): triage the codebase to find the root cause
-and draft a TDD-based fix plan (`triage-issue`), creating the issue with
+draft a TDD-based fix plan and declare the risk surfaces (`triage-issue`), creating
+the issue with
 `harness:managed` (no `harness:sdd` — its absence marks the lightweight path), then
 branch and scaffold `progress.md`, implement (`tdd`), review (`senior-review`), and
 run the human merge gate before closeout. L2 skips the spec and its approval gate, but

package/catalog/harness.config.schema.json

@@ -92,6 +92,46 @@
         }
       },
       "additionalProperties": false
+    },
+    "merge": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "checks_timeout_secs": {
+          "default": 600,
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        },
+        "allow_no_checks": {
+          "default": false,
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "implementation": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "pre_commit_review": {
+          "default": "human",
+          "type": "string",
+          "enum": [
+            "human",
+            "on",
+            "off"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "gates": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
     }
   },
   "required": [