@lemoncode/lemony 0.1.2 → 0.3.0

package/README.md

@@ -22,6 +22,7 @@ to semver.
 
 - **Node.js ≥ 24** and **npm ≥ 11** (`node --version`).
 - **[Claude Code](https://claude.com/claude-code)** installed in the target repo.
+- **[GitHub CLI](https://cli.github.com) ≥ 2.50**, authenticated (`gh auth login`) — the merge executor reads check status via `gh pr checks --json`, added in 2.50. An older gh fails closed (the gated path never merges) with gh's own `unknown flag` message.
 
 ## Install
 
@@ -127,20 +128,24 @@ directly; the Orchestrator and sub-agents do, gated by your repo's capabilities.
 
 ## Commands
 
-The CLI ships nine verbs. Run `lemony <command> --help` (or `-h`) for usage;
-`lemony version` (or `-v`) prints the installed version.
-
-| Command     | What it does                                                                    | Key flags                                                                                    |
-| ----------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `install`   | Install into a fresh repo, or reconcile a pre-existing `.claude/`.              | `--target=<claude-code>` `--task-storage-repo=<owner/name>` `--on-conflict=<vendor\|client>` |
-| `update`    | Move the install to the CLI's catalog version (3-way merge).                    | `--on-conflict=<vendor\|client>` `--dry-run`                                                 |
-| `repair`    | Re-sync at the **pinned** version (restore missing files, never clobber edits). | `--dry-run`                                                                                  |
-| `rollback`  | Restore a pre-change snapshot (offline).                                        | `--to=<version>` `--list` `--cleanup` `--force`                                              |
-| `uninstall` | Remove vendor-managed files (keeps your docs, state, adopted skills).           | `--labels`                                                                                   |
-| `doctor`    | Diagnose the installation (read-only); proposes `repair`.                       | —                                                                                            |
-| `status`    | Show installed version, branch drift, and open tasks.                           | —                                                                                            |
-| `emit`      | Append a telemetry event to `.claude/state/events.jsonl`.                       | `<type> [--key=value …]`                                                                     |
-| `telemetry` | Inspect or control the local anonymous telemetry.                               | `status` `show` `disable` `enable`                                                           |
+The CLI ships 13 verbs. Run `lemony <command> --help` (or `-h`) for usage;
+`lemony version` (or `--version` / `-v`) prints the installed version.
+
+| Command         | What it does                                                                                                                            | Key flags                                                                                        |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `install`       | Install into a fresh repo, or reconcile a pre-existing `.claude/`.                                                                      | `--target=<claude-code>` `--task-storage-repo=<owner/name>` `--on-conflict=<vendor\|client>`     |
+| `update`        | Move the install to the CLI's catalog version (3-way merge).                                                                            | `--on-conflict=<vendor\|client>` `--dry-run`                                                     |
+| `repair`        | Re-sync at the **pinned** version (restore missing files, never clobber edits).                                                         | `--dry-run`                                                                                      |
+| `rollback`      | Restore a pre-change snapshot (offline).                                                                                                | `--to=<version>` `--list` `--cleanup` `--force`                                                  |
+| `uninstall`     | Remove vendor-managed files (keeps your docs, state, adopted skills).                                                                   | `--labels`                                                                                       |
+| `doctor`        | Diagnose the installation (read-only); proposes `repair`.                                                                               | —                                                                                                |
+| `status`        | Show installed version, branch drift, and open tasks.                                                                                   | —                                                                                                |
+| `emit`          | Append a telemetry event to `.claude/state/events.jsonl`.                                                                               | `<type> [--key=value …]`                                                                         |
+| `discovery`     | Reflect a raised/resolved discovery onto its issue (label flip; `pause` also comments).                                                 | `<pause\|resume>` `--task-id=<id>` `--tier=<T1..T6>` `--status=<…>` `--note=<text>`              |
+| `design-tokens` | Validate the design-token file, check WCAG contrast, or sync with a design tool (consume-if-exists).                                    | `<validate\|contrast\|import\|export>` `--scan=<dir>` `--from=<file>` `--apply` `--only=<paths>` |
+| `review-ledger` | Validate the Reviewer's evidence-ledger sidecar against the spec, the anchored diff and the declared gates (deterministic, agent-free). | `validate` `--task-id=<id>` `--anchor=<oid>` `--step=<N>` `--full-pass`                          |
+| `spinoff`       | Capture a non-blocking defect found mid-task as a pending stub.                                                                         | `--title=<text>` `--body=<text>` `--parent=<id>` `--severity=<…>` `--kind=<…>`                   |
+| `telemetry`     | Inspect or control the local anonymous telemetry.                                                                                       | `status` `show` `flush` `enable` `disable [--purge-local]`                                       |
 
 The harness keeps a **committed baseline** under `.claude/.harness/baseline/<version>/` — a
 verbatim copy of every installed vendor file at the pinned version — so `update` is a true

package/catalog/VERSION

@@ -1 +1 @@
-0.1.2
+0.3.0

package/catalog/agents/architect.md

@@ -21,8 +21,11 @@ client-owned, so it never imposes content, it suggests changes.
 
 ## When the Orchestrator invokes you
 
-You are dispatched for one of these, with the relevant context (the discovery entry, the
-decision, the change, or the request):
+You are dispatched for one of these, with the relevant context arriving **as paths
+plus a short delta** (the `discoveries.md` entry's path with the decision — stated in
+full when routed mid-resolution, before its `**Resolution**` block is recorded; its
+gist once recorded; the PR number at closeout, or the branch/working tree on mid-task
+routes where no PR exists yet; or the request) — read the files yourself:
 
 | Trigger                                                                                | Skill to run          |
 | -------------------------------------------------------------------------------------- | --------------------- |
@@ -44,8 +47,14 @@ acceptance for `write-adr` / `playbook-iterate`. See the Orchestrator's §Closeo
 
 ## Operating procedure
 
-1. **Orient.** Read the context the Orchestrator gave you — the discovery entry and its
-   resolution, the changed code, or the request. If the codebase is unfamiliar and the
+1. **Orient.** Read the context the Orchestrator referenced — the discovery entry and
+   its resolution from `discoveries.md` (when routed before the `**Resolution**`
+   block is recorded, the decision arrives in the spawn prompt instead — don't
+   stall looking for it in the entry); the changed code from the PR diff when a PR
+   exists (closeout) or from the branch when none does (mid-task routes — under
+   pre-commit review ON read the **worktree**: mid-task the branch holds only
+   OK'd groups, or nothing before the first OK); or the
+   request. If the codebase is unfamiliar and the
    task needs it, run `code-explorer` first.
 2. **Do the one thing you were invoked for**, via its skill. Keep edits surgical and
    the rationale linked, not duplicated: an ADR records the _why_, `architecture.md` the

package/catalog/agents/implementer.md

@@ -12,6 +12,34 @@ vendor_version: '{{vendor_version}}'
 
 A **sub-agent** with fresh context. Implements the approved change via TDD.
 
+## Turn economy
+
+On a long implementation the round trips, not the work, dominate wall-clock. The
+contract is **batching-only: same experiments, fewer trips** — it never reduces
+what you run, only how many calls carry it.
+
+- **Batch the enumerated evidence up front.** The inputs your invocation itself
+  names — the issue, the task state files, the spec files for your assigned
+  scope — are knowable before you read anything: acquire them in **at most two
+  composite tool calls — your first tool calls, before any other trip** (one
+  composite `cat` over the named paths counts as one call — skip a missing
+  optional path rather than abort; a fan of parallel single-file reads does not
+  count as one). Everything you discover from there — the ADRs / playbooks the
+  spec points to, files you choose _because of_ what you just read — is
+  exploratory follow-up and stays free: never defer or drop a read you need.
+- **Batch auxiliary commands.** Git ceremony travels composite
+  (`git add … && git commit … && git log -1; git push`-style one-liners — the
+  best-effort push rides `;`-separated so its failure reads as a warning, never
+  as the commit failing); setup sequences chain into one call; gate sequences
+  chain into one composite run — `&&`-chaining preserves the ordered
+  stop-at-first-failure the `verify` skill prescribes; the real-run exercise
+  stays its own trip.
+- **The TDD core is exempt and untouchable.** The red → green → refactor runs per
+  behavior happen as the `tdd` skill prescribes and are never batched or merged:
+  **no batch may merge a red with its green**, and re-running to reach green or
+  after a refactor step is never a trip to save. Batching applies to auxiliary
+  trips only — never to the experiments that prove the work.
+
 ## Operating procedure
 
 1. **Orient** — read the issue, the task state (`.claude/state/tasks/<id>/`), and any
@@ -23,14 +51,20 @@ A **sub-agent** with fresh context. Implements the approved change via TDD.
    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).
+   behavior (vertical slices, never all-tests-then-all-code). When your invocation
+   says **pre-commit review is ON**, the whole run obeys §Staging protocol (below) —
+   zero commits, staged save-points.
    **Scope: exactly what the invocation hands you.** By default that is the whole
    `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.
+   invokes you per step — scoped to **one group**, handed **by reference** (the
+   group's id + header line): read that group's tasks from the spec's `tasks.md`
+   yourself. On a later iteration the reference comes with reviewer or
+   human-checkpoint feedback. Work the group's tasks
+   in order — one TDD cycle and small commits per task, as always (ON: staged
+   save-points per task — §Staging protocol) — then stop: do
+   **not** run ahead into the next group (the human checkpoints each group 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,
@@ -47,7 +81,9 @@ A **sub-agent** with fresh context. Implements the approved change via TDD.
    `tasks/<id>/discoveries.md`, return the one-line summary, and stop. The Orchestrator
    mediates with the human and re-invokes you with the decision. Don't code past a
    contradiction (T1), a genuine unspecified fork (T2), scope drift (T3), or work that
-   already exists (T4). If instead you notice a defect that is **independent** of your
+   already exists (T4). A scope that turns out to hide **≥2 independently mergeable
+   units** the plan didn't reveal is a T2 too (partition or keep together is the human's
+   call — never cut it yourself). If instead you notice a defect that is **independent** of your
    task — it doesn't block you and your change never touches it — don't pause and don't
    fix it: **run `note-side-finding`** to add it to your return summary, then carry on
    (blocking → discovery; independent → side-finding). The same channel covers
@@ -62,8 +98,51 @@ A **sub-agent** with fresh context. Implements the approved change via TDD.
    lint / tests + coverage / audit + a real run); otherwise run those gates inline.
    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
+   then return a summary to the Orchestrator. (Pre-commit review ON: no commit and
+   no push — leave **everything staged** and say so in the summary; the Orchestrator
+   commits at the human's OK.) The Orchestrator opens
    the PR when you signal done — you don't open it.
+6. **Report small, log rich** — your return summary is **capped**: the outcome
+   (done / blocked / discovery raised), key decisions or deviations as a few bullets,
+   the paths touched, a one-line verification result (command + outcome — the
+   checkpoint's "how to run it" is presented from it), and any `## Side-findings`
+   block. Long-form material — reasoning, alternatives weighed, per-task notes —
+   belongs in `progress.md` and the commit messages, never in the summary
+   (pre-commit review ON: in `progress.md` alone — there are no commit messages
+   until the human OK, so it carries everything a fresh iteration will need): the
+   Orchestrator carries your summary in context for the rest of the task, so every
+   extra line taxes the whole run. The cap trims narrative, not signal — a blocker,
+   a deviation from the spec, or a side-finding is always stated, however long the
+   list.
+
+## Staging protocol (pre-commit review ON)
+
+Active **only when your invocation says so** — the human chose to review the work
+**uncommitted**, so the branch must receive nothing until their OK. This inverts
+the tdd add-early reflex; the branch history won't help you here, and a fresh
+iteration only knows what this contract and the worktree tell it:
+
+- **Zero commits, zero pushes.** Never `git commit`, never `git push` — not for
+  code, not for state. The Orchestrator commits once the human OKs.
+- **Stage after every green task** — `git add -A` when a checkbox/task reaches
+  green (suite passing). The index is your save-point ladder: everything staged
+  is a proven-green floor.
+- **Never stage mid-experiment.** A `git add` while red or mid-refactor silently
+  **overwrites the save-point** — `git status` looks identical afterwards, and
+  recovery yields nameless blobs (practically unrecoverable). Stage only at
+  green, immediately after the suite passes, and nowhere else.
+- **Failed experiment ⇒ roll back to the save-point**: `git restore . && git clean -fd`
+  returns the worktree to the last staged state — staged content survives
+  verbatim, including new files (`clean` respects the index and `.gitignore`).
+- **Watch what `-A` scoops.** Before your first stage, eyeball `git status` for
+  unexpected untracked files (secrets, scratch, build junk) — `git add -A`
+  trusts `.gitignore`. Fix the ignore file or remove the junk **before**
+  staging, never after (a cleanup `add` mid-experiment is exactly the
+  save-point-destroying move above).
+- **On a fix iteration** (checkpoint `changes`), the Orchestrator hands you a
+  worktree that may carry the human's own revalidated edits: **stage everything
+  first** (`git add -A` — that snapshot is your safe starting point), then
+  iterate under this same protocol.
 
 ## Skills