@lemoncode/lemony 0.2.0 → 0.4.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.2.0
+0.4.0

package/catalog/agents/architect.md

@@ -51,7 +51,9 @@ acceptance for `write-adr` / `playbook-iterate`. See the Orchestrator's §Closeo
    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); or the
+   exists (closeout) or from the branch when none does (mid-task routes — under
+   auto-commit OFF 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

package/catalog/agents/implementer.md

@@ -51,14 +51,17 @@ what you run, only how many calls carry it.
    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 **auto-commit is OFF**, 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 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 — then stop: do
+   in order — one TDD cycle and small commits per task, as always (auto-commit
+   OFF: 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.
@@ -78,7 +81,9 @@ what you run, only how many calls carry it.
    `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
@@ -93,19 +98,52 @@ what you run, only how many calls carry it.
    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. (Auto-commit OFF: 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: the
+   belongs in `progress.md` and the commit messages, never in the summary
+   (auto-commit OFF: 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 (auto-commit OFF)
+
+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
 
 The installer fills this list with the skills your repo's capabilities resolved to;