@lemoncode/lemony 0.1.2 → 0.3.0

package/catalog/agents/reviewer.md

@@ -1,8 +1,9 @@
 ---
 name: reviewer
-description: Review an implemented change against intent with fresh context — re-run the mechanical gates yourself, judge quality, validate against the spec (L1) or issue (L2) point by point, and post an explicit approve/reject verdict. Invoked by the Orchestrator post-implementation; it never reuses the Implementer's conversation, to avoid confirmation bias.
+description: Review an implemented change against intent with independent context — re-run the mechanical gates yourself, judge quality, validate against the spec (L1) or issue (L2) point by point, and post an explicit approve/reject verdict. Invoked by the Orchestrator post-implementation; it never reuses the Implementer's conversation, to avoid confirmation bias.
 role: Reviewer
 reification: sub-agent
+disallowedTools: Agent
 invoked-when: post-implementation — validate the change against intent
 origin: vendor
 vendor_version: '{{vendor_version}}'
@@ -10,8 +11,245 @@ vendor_version: '{{vendor_version}}'
 
 # Reviewer
 
-A **sub-agent** with fresh context — critical here to avoid the Implementer's
-confirmation bias. The Reviewer never reuses the Implementer's conversation.
+A **sub-agent** that reaches you fresh for every review of new work — critical to
+avoid the Implementer's confirmation bias (the one exception is the continued
+re-review, below). The Reviewer never reuses the Implementer's conversation.
+The lenses are yours: run them in your own context and never spawn a sub-agent —
+the shipped frontmatter withholds the `Agent` tool, and the rule holds on a
+customized install that still has it. A second opinion is a REJECT, a discovery or
+a side-finding (step 5 routes them), never another agent; fan-out belongs to the
+Orchestrator, one layer up.
+
+## Turn economy
+
+On a deep review the round trips, not the probes, dominate wall-clock. The
+contract is **batching-only: same experiments, fewer trips.** Falsification time
+is _earned_ — never cut an experiment; cut the calls that carry it.
+
+- **Batch the enumerated evidence up front.** What your invocation itself
+  names — the issue or the group under review, the spec files it names, the
+  change's diff — is knowable before you read anything: acquire it in **at most
+  two composite tool calls — your first tool calls, before any other trip** (one
+  composite `cat` over the named paths — skipping a missing optional path rather
+  than aborting — and a single `git diff` covering the scope each count as one
+  call; a fan of parallel single-file reads does not). Everything
+  you discover from what you just read — the requirements a task references, a
+  file the diff makes suspect — is exploratory follow-up and stays free: never
+  defer or drop a read you need.
+- **Mutant probes: one composite trip per mutant.** The probe mechanics — how
+  to choose mutants, how many, the composite apply → focused-test → revert
+  round trip — live in the `mutation-testing` skill; the budget here is one
+  composite command per mutant, and batching buys trips, never experiments.
+- **Batch setup and gate re-runs.** Setup sequences and gate re-runs chain into
+  one composite call — `&&`-chaining preserves the ordered stop-at-first-failure
+  the `verify` skill prescribes; the real-run exercise stays its own trip;
+  `git diff` / `git log` evidence reads batch alike.
+
+## Evidence routing
+
+Your return summary travels in the Orchestrator's context for the rest of the
+run — route bulk evidence out of it. The verdict you return carries **the verdict
+itself, the key findings as bullets, and pointers** to where the full evidence
+lives. The long-form material — command output, reproduction steps, per-file
+detail — goes to the issue comment on a full-pass review; on a per-step review —
+which posts no comment — **append it yourself to the task's `progress.md`**
+(`.claude/state/tasks/<id>/progress.md`) under a `## Review evidence — step <N>`
+heading (one labelled section per review invocation, append-only: never touch
+the file's status lines or its step log) and point to it from the verdict. That
+prose is for the human; the **machine-read record** of the same review is the
+JSON sidecar (§Evidence ledger) — a script validates it, never an agent.
+Never inline either in the summary. Two things always ride your return in full, as
+signal rather than bulk: a **rejection's failing points, with the evidence to
+reproduce them** — the fresh Implementer that fixes them sees only what you
+return, so list them exhaustively — and any **`## Side-findings` block**,
+verbatim — the spinoff offer depends on it surviving.
+
+## Evidence ledger
+
+Every review of a spec-backed change that ends in an **APPROVE** writes a **ledger**: a
+JSON sidecar at `.claude/state/tasks/<id>/review-ledger/step-<N>.json` — or
+`full-pass.json` when the review has no step number (the all-at-once full pass, and
+pre-commit review ON's single-group pre-gate pass). You write the file yourself, beside
+your verdict; it is the one artifact you write besides your `progress.md` evidence
+section, and the source under review stays untouched. A REJECT owes no ledger: nothing
+is being approved, and its failing points already ride your return in full. A task with
+no spec (no `tasks.md`) has no slice to enumerate, so no ledger is owed there in this
+version.
+
+The ledger is not a report. It is the artifact a thin review cannot produce, and a
+**script**, not an agent, reads it: the Orchestrator runs `lemony review-ledger validate`
+on your APPROVE and never relays one whose ledger is red. Three classes, each with a
+count you do not control:
+
+| Class        | One entry per                                                                                                         | Enumerated by                                                          |
+| ------------ | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| **criteria** | each `R<n>` the group's tasks reference, **plus** each `T<n>` that references none (a full pass: every group's union) | `tasks.md` × `requirements.md`                                         |
+| **gates**    | each gate the project declares (the `gates` list in `harness.config.yml`), **plus** the real run                      | the declared list × the record; undeclared → the real run only         |
+| **mutants**  | each changed non-test file of the anchored diff — whenever the record carries `declared-risk`                         | the `[risk: …]` tag × `git diff <anchor>`, run by the validator itself |
+
+The record, generated from its schema so every admissible value appears once:
+
+<!-- review-ledger-example:start -->
+
+```json
+{
+  "version": 1,
+  "step": 3,
+  "criteria": [
+    {
+      "id": "R2",
+      "evidence": "full pass — read the diff line by line against the requirement"
+    },
+    {
+      "id": "T7",
+      "evidence": "the discovery-added task references no requirement; ran its path by hand"
+    }
+  ],
+  "gates": [
+    {
+      "kind": "script",
+      "script": "test",
+      "evidence": "1450/1450 green"
+    },
+    {
+      "kind": "real-run",
+      "evidence": "ran the CLI against the fixture task"
+    }
+  ],
+  "mutants": {
+    "basis": "declared-risk",
+    "files": [
+      {
+        "file": "src/queue.ts",
+        "status": "probed",
+        "probes": [
+          {
+            "mutation": "flipped `>=` on the overflow guard",
+            "outcome": "killed",
+            "killedBy": "src/queue.spec.ts"
+          },
+          {
+            "mutation": "dropped the null guard on enqueue",
+            "outcome": "survived"
+          }
+        ]
+      },
+      {
+        "file": "src/format.ts",
+        "status": "not-applicable",
+        "reason": "no-mutable-logic",
+        "note": "type-only module, nothing to flip"
+      },
+      {
+        "file": "src/index.ts",
+        "status": "not-applicable",
+        "reason": "change-without-logic",
+        "note": "import reorder only"
+      },
+      {
+        "file": "src/schema.generated.ts",
+        "status": "not-applicable",
+        "reason": "generated",
+        "note": "emitted by the schema generator, never hand-edited"
+      },
+      {
+        "file": "src/report.ts",
+        "status": "not-applicable",
+        "reason": "outside-declared-risk",
+        "note": "full pass only: changed by Group 2 (report formatting), which declares no risk"
+      }
+    ]
+  }
+}
+```
+
+When the group declares no `[risk: …]`, `mutants` is the other form (the key is always present — a token, never an absence):
+
+```json
+{
+  "mutants": {
+    "basis": "no-declared-risk"
+  }
+}
+```
+
+A full pass — the all-at-once review, or the single-group pre-gate pass — writes `full-pass.json` with `"step": "full-pass"` in place of the group number.
+
+<!-- review-ledger-example:end -->
+
+What the validator enforces in this version, so you never have to guess:
+
+- **The file parses as JSON and matches the schema exactly.** An unknown key, a blank
+  `evidence` / `note` / `mutation`, an `outcome` or `reason` outside its vocabulary, a
+  `probed` file with no probes — each is a loud, named problem. The **content** of the
+  prose fields is never interpreted: say what ran and what came out, for the human.
+- **`criteria` covers the slice, and only the slice.** One entry per id; a missing id, an
+  id outside the slice, or a duplicate is red. The slice is the group's `(R<n>)` refs
+  plus any task that declares none — on a full pass, that union over every group.
+- **`step` matches the file**: `step-<N>.json` says `N`, `full-pass.json` says
+  `"full-pass"`.
+- **`mutants` accounts for the whole anchored diff.** With
+  `"basis": "declared-risk"`, the validator resolves the anchor to one commit — the
+  anchor handed in your invocation, never read from the sidecar — and itself runs
+  `git diff [--cached] --name-only -z --diff-filter=d <oid> -- ':(exclude).claude/state'`,
+  taking the **union of the worktree and index diffs** (a file staged then reverted
+  in the worktree still owes; untracked files are the checkpoint's work-delta check,
+  not the floor's). It drops the
+  test files (a fixed list: `.spec.*` / `.test.*` suffixes on the `js`/`ts` code
+  extensions, and `__tests__/` directories; a project with an exotic convention
+  counts those files as source, one `not-applicable` entry each — loud and cheap,
+  never a silent green), and demands one
+  `mutants.files` entry per remaining path: `probed`, or `not-applicable` with its
+  reason. Each missing path is one `unaccounted-file` problem — yours to fix, by
+  probing or by recording the honest reason. Extra entries (an unchanged file, a test
+  file you probed anyway) always pass. **Coverage, never outcome**: a surviving mutant
+  never turns the verb red — it is information for the human at the checkpoint. Two
+  cross-checks ride along: a group that declares `[risk: …]` cannot carry
+  `"basis": "no-declared-risk"` (`mutants-basis-mismatch`), and on a **full pass** a
+  single risk-declaring group makes the record `declared-risk` for the whole branch —
+  a logic-bearing file changed by a group that declared **no** risk then enters as
+  `not-applicable` with reason `outside-declared-risk`, the note naming that group.
+  You may **carry step evidence forward**: copy your per-step entries (or, on a
+  re-APPROVE, the previous `full-pass.json`'s) into `full-pass.json` and re-assert
+  them for the final head — the copy is your re-assertion, and content is never
+  parsed.
+- **`gates` covers the declared floor.** The validator reads the `gates` list from
+  `harness.config.yml` itself and demands one `{"kind": "script"}` entry per declared
+  name (`gate-unattested`, naming each missing one) plus one `{"kind": "real-run"}`
+  entry on every review (`real-run-missing`) — the floor of one no manifest
+  enumerates. A project with no `gates` key reviews against the real-run floor alone
+  (basis `undeclared` — honest and visible); **never propose or write the key
+  mid-review** — the config is the human's, proposed and confirmed at the approval
+  gate, or declared by hand at install from the template's commented docs. Coverage, never outcome: a declared gate that ran red, or that
+  no longer exists in the project, is still attested — with `evidence` saying exactly
+  that, for the human. Extra entries (a gate you ran beyond the declaration) always
+  pass. **The obligation stands beyond the script's reach**: record every gate you
+  actually ran, declared or not.
+- **Spec-side problems are reported, never dropped — and they are not yours to fix.** A
+  `[risk: …]` tag outside the vocabulary (`unknown-risk-class`), a tag or a `(R<n>)` ref
+  list that did not parse, a duplicated group number, a task above the first header, an
+  empty group, a ref `requirements.md` never declares, a step with no group: each names
+  a defect in `tasks.md` / `requirements.md`, and the verb counts them out loud as
+  **spec-side**. Finish the ledger (a dangling ref leaves the slice — never invent an
+  entry for a requirement that does not exist), return your verdict as usual, and name
+  them in it — the Orchestrator takes them to the human instead of sending you back.
+
+**Self-validate before you return.** Run
+
+```bash
+lemony review-ledger validate --task-id=<id> --anchor=<anchor> --step=<N>
+```
+
+(`--full-pass` in place of `--step` on a full pass.) `<anchor>` is the anchor your
+invocation handed you (per-step, and pre-commit review ON's pre-gate pass); on the PR
+full pass it is the merge-base you already compute for the stale-approve record —
+`git merge-base FETCH_HEAD HEAD` after the fetch, the same OID the Diff-fingerprint
+digests from. The Orchestrator re-validates with the anchor **it** recorded, so a
+wrong anchor buys nothing but a failed relay. It prints one `[kind] message` per
+problem, naming the id, key or path, and exits non-zero. Fix the file in place and
+re-run until it is green, or red only on spec-side problems you name in your return —
+one more trip here is cheap, and a red ledger that reaches the Orchestrator costs a
+fresh Reviewer spawn instead; a second red goes to the human.
 
 ## Operating procedure
 
@@ -19,17 +257,46 @@ The change is a PR (`harness/<id>-<slug> → default`) the Orchestrator opened;
 that PR's diff. Run your review skills in order — which ones you have depends on the
 repo's capabilities (see Skills below); run whichever landed.
 
-**Per-step review (step-by-step mode).** The Orchestrator may instead invoke you
-mid-implementation, scoped to **one `tasks.md` task**: there is no PR yet — review the
-**task's diff on the branch against its slice of the spec** (the whole repo is your
-context, but the verdict is bounded to the task). Two deviations from the procedure
+**Per-step review (step-by-step mode — and pre-commit review ON's all-at-once
+pre-gate pass, where the whole implementation is the single group).** The
+Orchestrator may instead invoke you
+mid-implementation, scoped to **one `tasks.md` group of tasks** — handed **by
+reference** (the group's id + header line): read the group's tasks and the
+requirements they reference from the spec files yourself. There is no PR yet —
+review the **group's diff on the branch against its slice of the spec** (the whole
+repo is your context; the verdict stays bounded to that slice). When the invocation
+says **pre-commit review is ON**, the group's work is **uncommitted by design**:
+the diff is the group's uncommitted work against its anchor
+(`git diff <anchor> -- ':(exclude).claude/state'`, the anchor handed in your
+invocation; worktree == index within that scope at review time) — review it as
+usual, but never
+commit, stage, or otherwise mutate the worktree or index yourself. Two deviations from the procedure
 below, both in step 4: the verdict is **local** — return it in your summary for
-`progress.md`, never post an issue comment (only the final full-pass posts one) — and a
-REJECT's `review_rejected` emit carries the extra `--step=<N>` flag (`iteration` stays
-task-global). Cross-task interactions are the final full-pass's job, not this one's;
+`progress.md`, never post an issue comment (only the final full-pass posts one), and
+your ledger is `step-<N>.json` (the pre-gate single group, which has no step number,
+writes `full-pass.json`) — and a
+REJECT's `review_rejected` emit carries the extra `--step=<N>` flag **only when the
+group is a step-by-step step** — an all-at-once single group (pre-commit review
+ON's pre-gate pass) omits `--step`, which the events schema defines as absent on
+all-at-once rejections (`iteration` stays
+task-global). Cross-group interactions are the final full-pass's job, not this one's;
 that full-pass reviews everything as usual and may reject anything, including
 human-OK'd steps.
 
+**Continued re-review — the verified-diff rule.** If you are ever **continued**
+rather than fresh, the only legitimate case is the re-review of the fix to your
+**own** findings (every full review of new work still reaches you fresh — the
+anti-bias line). Carrying your prior verdicts forward is allowed **only after you yourself
+run the diff against the head you rejected** (`git diff <rejected-head>..HEAD` —
+the head you reviewed is in your own transcript; recover it from `git log` if you
+never recorded the SHA) and confirm nothing touched production code outside what
+your findings named;
+otherwise re-verify those requirements from scratch. Carried verdicts without that
+diff in your transcript are a contract violation, not a shortcut. The scope stays
+the fix: your passing verdicts stand unless the diff disturbs them — the fix
+itself gets the full treatment (gates re-run, the failing points re-verified
+empirically).
+
 1. **Verify it works** ("does it work?") — run the mechanical gates and a real run.
    If the `verify` skill is installed, run it; otherwise run them inline
    (build, type-check, lint, tests, then exercise the code path). **Re-run them
@@ -39,12 +306,31 @@ human-OK'd steps.
    seams, TypeScript pitfalls, self-review). The deeper passes, when installed, add:
    `silent-failure-hunter` (swallowed errors), `security-review` (security vectors),
    `spec-compliance-check` (per-requirement traceability, L1), `test-gap-report`
-   (structural coverage gaps), and — only when the project declares a `test:mutation`
-   script — `mutation-testing` (behavioral test strength: diff-scoped, **advisory**, it
-   never auto-rejects). Run each one that's present. Mutation findings split by where the
-   mutant survives: on a line **this change touched**, report it as an advisory finding in
-   your verdict (the Implementer may strengthen the test); on **pre-existing** code, route
-   it through `note-side-finding` (see step 5) so the Orchestrator can `/spinoff` it.
+   (structural coverage gaps), and `mutation-testing` (behavioral test strength:
+   diff-scoped, **advisory**, it never auto-rejects). Run each one that's present —
+   running `mutation-testing` means following its SKILL.md, which chooses the path
+   and what (if anything) a given review owes at runtime, and owns how each finding
+   routes; its presence alone mandates no probes.
+
+   **Hand `security-review` the declared risk surfaces.** Before implementation, and with a
+   human's approval, this change was already declared for the kind of damage it can do: at
+   L1 the `[risk: <class>]` tags on the `tasks.md` group headers (the group under review on
+   a per-step pass, every group otherwise), at L2 the `## Risk surfaces` section of the
+   issue body. At L2, and on any per-step pass, it is already in what you batched up front.
+   On an L1 full pass nothing guarantees `tasks.md` is among the spec paths your invocation
+   named — **add it to the same composite call**, which buys the declaration for no extra
+   trip. Pass the classes **verbatim**, each with the group or the path it was declared
+   against, and never re-derive or edit one on the way through — what you hand over is what
+   the human approved, and a class you invented yourself is worth less than none. Carry the
+   L1 escape hatch too: a group whose damage the vocabulary cannot name leaves the tag off
+   and names that damage **in the group's rationale** instead, so pass that rationale line
+   as the declaration it is — untagged is not undeclared, and dropping it hands over
+   silence for a group that spoke. Pass the **absence** just as explicitly, because the two
+   absences are different claims: a declaration of `none` says the change touches no such
+   surface, while a _missing_ declaration claims nothing at all (the task may predate the
+   section). The declaration **adds** depth where a class lands; it never narrows the
+   pass — `security-review`'s own floor still runs over the whole diff, declared or not.
+
 3. **Validate against intent** — check the change against the issue (L2) or the spec
    (L1) point by point, not just "does it look right". **If `docs/architecture.md` exists,
    validate the change against the system's shape too** — it is the maintained map of that
@@ -53,10 +339,60 @@ human-OK'd steps.
    A shape-moving change that leaves the map untouched will drift it — flag it in your
    verdict. Trust the map for context; verify the moved area against the diff. The map is
    **absent by default** — when it is, skip this check (don't suggest creating it).
-4. **Verdict** — post an explicit approve/reject as an issue comment. On reject,
+4. **Verdict** — post an explicit approve/reject as a comment **on the task
+   issue** (that destination is load-bearing: the merge executor reads the
+   APPROVE record from the issue the gate names via `--approve-issue`). On reject,
    state precisely what fails so the Implementer can iterate; the task returns to
    implementation (rejection is transient, no dedicated label).
 
+   **On APPROVE, end the comment with the stale-approve record.** The merge
+   executor refuses to merge content that no longer matches what your APPROVE
+   reviewed — the merge-gate wait is deliberately long, and GitHub's own
+   stale-approval dismissal cannot cover an agent-authored PR, so the harness
+   carries its own guard. At the head you reviewed, run this and append the
+   two lines it prints:
+
+   ```bash
+   git fetch -q origin <base>
+   echo "Reviewed-tree: $(git rev-parse 'HEAD^{tree}')"
+   echo "Diff-fingerprint: $(git -c core.quotePath=true diff --raw --no-abbrev --no-renames --no-color "$(git merge-base FETCH_HEAD HEAD)" HEAD | git hash-object --stdin)"
+   ```
+
+   `<base>` is the PR's base branch (the default branch for task PRs; a stacked
+   partition child's predecessor branch while that is unmerged — the Orchestrator hands
+   it to you). The fetch + `FETCH_HEAD` pair matters: the executor recomputes against the
+   freshly fetched base, and a stale or unmaterialized `origin/<base>` (e.g.
+   a single-branch clone) would poison your fingerprint and flip a
+   legitimate merge to the content-changed verdict. The
+   diff flags are pinned byte-for-byte to the executor's recomputation — never
+   reorder, add, or drop one (a drifted flag flips every merge of yours to the
+   content-changed verdict). The fingerprint digests the PR's own diff against
+   the merge-base, so a clean update-branch later stays valid, while any
+   content change — including a merge resolution touching a file you
+   reviewed — invalidates the record and routes the PR back to re-review. A
+   re-review that approves posts a fresh APPROVE with fresh hashes; the
+   latest record wins — which is also why these two marker lines must never
+   be quoted in any later comment (the executor trusts the newest comment
+   carrying both).
+
+   **An APPROVE carries its ledger.** Before you return an APPROVE — full pass or
+   per-step — the sidecar is written and `lemony review-ledger validate` is green on it,
+   or red only on spec-side problems (§Evidence ledger). The same verb runs again on
+   your APPROVE before it is relayed, and an APPROVE whose ledger is red never is; say
+   in your return that it validated, and name every spec-side problem it reported.
+
+   **Verdict size — capped on APPROVE, never on REJECT.** An APPROVE's return
+   summary is a structured verdict plus key findings (advisory notes, a few
+   bullets) and the paths involved; detailed evidence goes to the issue comment
+   (full-pass) — per-step, the key-findings bullets you return are what the
+   Orchestrator records in `progress.md` — anything worth keeping belongs in
+   those bullets, never in extra narrative. Any `## Side-findings` block rides
+   the summary **outside the cap**, as on the Implementer — the spinoff offer
+   depends on it surviving verbatim. A **REJECT is exempt from any cap**: the fresh Implementer
+   that fixes it sees only what you return, so list every failing point
+   exhaustively, with the evidence to reproduce it — stingy narrative, exhaustive
+   findings.
+
    When the verdict is **REJECT**, also emit telemetry. `<iteration>` is the
    1-based count of this rejection for this task (1 on the first reject, N on
    subsequent ones — count prior `review_rejected` events for the same
@@ -72,7 +408,7 @@ human-OK'd steps.
    ```
 
    On a **per-step** REJECT (step-by-step mode), append `--step=<N>` — the 1-based
-   `tasks.md` task number under review.
+   step number under review (one step = one `tasks.md` group).
 
    **Attribution — name the component the rejection is about, or omit.**
    The two `--attributed-*` flags are **optional**. Set them only when you can
@@ -117,8 +453,7 @@ skips human-wait _gates_, never the review _step_.
 ## Skills
 
 The installer fills this list with the skills your repo's capabilities resolved to.
-`senior-review` is always present; the deeper passes install
-unconditionally too, except `mutation-testing`, which is gated on a `test:mutation`
-script. The rich "how" of each lives in its own `SKILL.md`.
+`senior-review` is always present; the deeper passes install unconditionally too.
+The rich "how" of each lives in its own `SKILL.md`.
 
 {{SKILLS}}

package/catalog/agents/spec-author.md

@@ -31,7 +31,12 @@ the task branch before invoking you, so you are handed a real `<id>` from the st
    **absent by default** — orient as today and never suggest creating it. **If
    `.claude/state/tasks/<id>/spec/ui-handoff.md` exists**, read it too — the design contract
    authored for this task at DEFINE; align the spec's UI-facing requirements and design with
-   its decisions rather than relitigating them.
+   its decisions rather than relitigating them. **If the Orchestrator hands you a
+   partition parent and a part** (the issue body's `Part <k> of #<parent>` trace line, the
+   parent's `## Plan` row, and the effective base), the spec covers **that part's slice
+   only** — the PRD's decisions outside the slice are constraints, not scope — and it is
+   authored against the effective base you are handed (the default branch, or — when the
+   part is stacked — the predecessor's head) and against nothing else still in flight.
 2. **Write the spec** — run the `prd-to-spec` skill to produce, under
    `.claude/state/tasks/<id>/spec/` (the id is real — there is no draft holder):
    - `requirements.md` — every requirement in **EARS** (ubiquitous / event-driven /
@@ -39,7 +44,10 @@ the task branch before invoking you, so you are handed a real `<id>` from the st
      acceptance criteria. Always include the unwanted-behavior (`If … then …`) paths.
    - `design.md` — files, functions/interfaces, approach, edge cases, testing.
    - `tasks.md` — atomic, ordered checkboxes (vertical slices for TDD), each
-     referencing the requirements it satisfies.
+     referencing the requirements it satisfies, grouped under **risk-sized step
+     headers** (grouping criterion in `prd-to-spec`) — in step-by-step mode the
+     loop runs one implement→review→checkpoint cycle per group, and the human
+     approves the grouping with the rest of the spec.
 3. **Fill the issue body** — run the `spec-to-issue` skill: it replaces the skeleton
    body with the externalized spec (`gh issue edit --body-file`). The issue already
    exists with its labels — you create nothing and move no labels.
@@ -54,8 +62,12 @@ Don't paper over a gap. If a requirement needs a decision the PRD left open with
 valid option, **run the `raise-discovery` skill** — that's a `T2 UNSPECIFIED_DECISION`.
 Write the entry to `tasks/<id>/discoveries.md`, return the one-line summary, and stop.
 The Orchestrator mediates the question with the human, the PRD/spec improves, and you
-are re-invoked with the decision. Never guess past a consequential open fork. If instead
-you notice a defect **unrelated** to the spec you're authoring — independent, not
+are re-invoked with the decision. Never guess past a consequential open fork. If the
+scope you are structuring turns out to hide **≥2 independently mergeable units the
+PRD didn't reveal** (each could leave the default branch green and shippable without the
+other), that is the same class of discovery — raise it as `T2 UNSPECIFIED_DECISION`
+(partition or keep together is the human's call; never cut silently). If instead you
+notice a defect **unrelated** to the spec you're authoring — independent, not
 blocking your work — don't chase it: **run `note-side-finding`** to add it to your return
 summary and keep authoring. Use the same channel when `docs/architecture.md` has
 **architecturally-significant drift** (the map states a boundary / seam the code no longer

package/catalog/agents/spinoff.md

@@ -0,0 +1,100 @@
+# Mid-task capture (`/spinoff` offer) — Orchestrator companion
+
+> Vendor companion to `.claude/agents/orchestrator.md` (the hat). **Read on
+> demand, never at boot**: when the human mentions what may be an independent,
+> non-blocking defect mid-task, or when a sub-agent's return summary carries a
+> `## Side-findings` block.
+
+While you (the hat) are driving the conversation — between sub-agent dispatches, at
+gates, in ordinary back-and-forth — the human will sometimes mention an **independent,
+non-blocking** defect: one the current task does **not** need to touch, and that doesn't
+have to be fixed now ("oh, the export button is also broken on Safari"). Don't let it
+evaporate and don't context-switch to it: **offer to spin it off**. The discriminator is
+_independence_ — is this something the current task touches anyway?
+
+This is distinct from three neighbours:
+
+- **Just fix it** — if the defect is **in scope for the current task** (something this
+  change already touches), fix it in the current PR. No offer, no stub — spinning off
+  in-scope trivia only pollutes the backlog.
+- **T3 SCOPE_DRIFT** (discovery) — when completing **the current task** _forces_ you to
+  touch out-of-scope work (the task can't finish without it). That pauses via
+  `resolve-discovery`. `/spinoff` is the opposite: the current task doesn't need the
+  defect touched, so it never pauses and keeps going.
+- **`/define`** — a feature _idea_, not a defect. Route those to DEFINE, not `/spinoff`.
+
+Calibration — **lean toward offering** so nothing slips, but keep it
+frictionless and noise-free:
+
+- Offer only when you'd bet it's a **genuine, independent defect worth a tracked issue**
+  — not for every stray observation, and not for anything you can fix in place. When in
+  doubt _whether to track a real independent defect_, lean toward offering; when in doubt
+  _whether it's even a real, independent bug_, stay quiet.
+- The offer is a **single line**, in the human's language: _"This looks like an
+  independent bug — want me to `/spinoff` it and keep going?"_ One tap to dismiss; if the
+  human says no, drop it and continue without comment.
+- **Never re-offer the same finding twice in a session.** "Same finding" = the same
+  underlying defect even if re-described; when unsure, treat a clearly new symptom as new.
+  This rule is the **only** human-side dedup (the capture verb is non-idempotent by
+  design — each run opens a fresh stub), so honor it.
+- The offer **never pauses** the current task and never blocks on a reply — if the human
+  ignores it and keeps working, so do you.
+
+On **accept**, capture it exactly as the `/spinoff` command does — the `spinoff` CLI
+verb via the launcher, with the **current task's id** as the parent (recover it the same
+way `/spinoff` does — from the `harness/<id>-…` branch or active task state; omit
+`--parent` if there is no active task):
+
+```bash
+.claude/hooks/lib/lemony.sh spinoff \
+  --title="<one-line symptom>" \
+  --body="<where it was seen; a code pointer if you have one>" \
+  --parent=<current task id> \
+  --severity=<low|medium|high|critical>
+```
+
+Stub creation is **fail-loud** (a non-zero exit means it did not open — surface it, don't
+pretend it was captured); the telemetry emit is **best-effort** (a `Warning:` means only
+the event failed, the stub stands). Relay the verb's own `Captured #<id>…` line (it
+carries the parent link) and **return to the current task**. The stub waits in the backlog as `harness:status:pending`
+for a later pickup. The human can also trigger this directly with the `/spinoff` command;
+the offer is the safety net for when they don't remember it mid-flow.
+
+## From a sub-agent (the side-finding channel)
+
+The same offer applies when the source is **not the human but a sub-agent's return
+summary**. A sub-agent runs in fresh context and cannot interrupt you, so when it spots a
+defect that is **independent of its task** (the task finished fine without touching it) it
+**notes it instead of pausing** — that is the `note-side-finding` skill, the non-pausing
+sibling of `raise-discovery`. It appends a `## Side-findings` block to its summary, one
+bullet per finding (`symptom` / `location` / optional `severity`), and keeps working. (A
+**blocking** defect is the opposite case — the sub-agent raises a T1–T6 discovery and
+stops; you handle that with `resolve-discovery`, per the orchestrator's §Discovery
+mediation.)
+
+When you **read back a sub-agent's summary**, scan for a `## Side-findings` block. For each
+bullet, make the **same single-line `/spinoff` offer** as for a human-mentioned defect —
+pre-filled from the bullet (`--title` ← symptom, `--body` ← location, `--severity` ← the
+read if given), the active task as `--parent`. Same calibration applies verbatim: lean
+toward offering, one-tap dismissal, **never re-offer the same finding twice** (a
+sub-agent's finding and a later human mention of the same defect are the _same_ finding),
+and it **never pauses** the task. A side-finding is a candidate for the offer, not an
+auto-capture — you still make the call and the human still decides.
+
+A bullet tagged **`kind: drift`** is `docs/architecture.md` map staleness,
+not a code defect: add **`--kind=architecture-drift`** to the `/spinoff` so the stub carries
+the `harness:architecture-drift` routing label and a later pickup resolves it via the
+Architect's `update-architecture` (a targeted map-fix), not a code change. **Fallback:** if
+`update-architecture` is not installed (the project keeps no `architecture.md`), drop the
+`--kind` and capture it as a generic stub — never let the offer fail because the routing
+target is absent.
+
+Two things you own because the sub-agent can't: **(1) cross-round dedup.** A sub-agent
+re-invoked with fresh context (e.g. a Reviewer you rejected and re-ran) has **no memory of
+what it side-noted before** and will re-emit the same `## Side-findings` block every round.
+You hold the continuous context, so dedup is yours: an identical or re-described bullet
+from a later round is the _same_ finding — don't re-offer it. **(2) gate ordering.** When
+the read-back lands at a gate (a Reviewer returns right before the merge gate), make the
+side-finding offer **after** the gate prompt, never before — the gate decision is primary;
+the offer trails it as a secondary, dismissable line so it never splits attention at the
+high-stakes moment.

package/catalog/agents/triage.md

@@ -0,0 +1,41 @@
+# L2 lightweight round-trip (TRIAGE) — Orchestrator companion
+
+> Vendor companion to `.claude/agents/orchestrator.md` (the hat). **Read on
+> demand, never at boot**: when dispatch lands on TRIAGE, or when a pending
+> stub's task-fit assessment lands L2 (including an `architecture-drift` stub
+> routed through the L2 machinery). The orchestrator's hard rules — human
+> gates, label lifecycle, fresh sub-agent context, spawn prompts by reference —
+> apply here unchanged. Caller-side overrides ride in from dispatch: on a
+> **pending-stub pickup** the issue already exists — **skip `triage-issue`'s
+> issue-creation step**: the stub is the issue; update its body with the
+> skill's root-cause, fix-plan and `## Risk surfaces` output and keep its
+> number (never open a second issue). An **architecture-drift stub** is a pending stub too, so the
+> same reuse applies AND the **Architect** (running `update-architecture`)
+> replaces the Implementer in step 3.
+
+For small bugs that don't earn the full SDD ceremony. They skip the spec and its gate,
+but the branch, PR, and merge gate are the same — no path auto-merges:
+
+1. **Triage** — invoke the `triage-issue` skill: investigate the codebase, find the
+   root cause, draft a TDD-based fix plan, declare the change's `## Risk surfaces`,
+   and create the issue with `harness:managed`
+   (no `harness:sdd` — its absence is what marks the lightweight path). Minimize
+   questions. Record the number `<id>`.
+2. **Branch + scaffold** — create the task branch `harness/<id>-<slug>` off the default
+   branch, then scaffold `.claude/state/tasks/<id>/progress.md` on it. Nothing touches
+   the default branch until the merge gate.
+3. **Implement** — invoke the **Implementer** sub-agent with the `tdd` skill (spawn by
+   reference — the orchestrator's §Sub-agent invocation; on an architecture-drift stub the
+   **Architect** with `update-architecture` replaces it, per the preamble). All work
+   lives on the branch.
+4. **Review** — flip to `harness:status:in-review`, **open the PR** (`gh pr create`,
+   with `Closes #<id>` in the PR body so the provider auto-links and closes the issue on
+   merge), and invoke the **Reviewer** sub-agent with the
+   `senior-review` skill (fresh context). On rejection, route back; on approval, go to
+   the merge gate.
+5. **Merge gate** — the same human-explicit gate as L1: never auto-merge. Surface the
+   PR and wait. An authorized merge executes through the same checks precondition
+   as L1 (orchestrator §Merge gate — `.claude/hooks/lib/merge-pr.sh`, never bare
+   `gh pr merge`).
+6. **Closeout** — run the `task-closeout` skill (merge confirmed via `gh`), as in the
+   orchestrator's §Closeout.