@lemoncode/lemony 0.2.0 → 0.3.0

package/catalog/agents/reviewer.md

@@ -3,6 +3,7 @@ name: reviewer
 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}}'
@@ -13,6 +14,11 @@ vendor_version: '{{vendor_version}}'
 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
 
@@ -30,15 +36,10 @@ is _earned_ — never cut an experiment; cut the calls that carry it.
   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.
-- **Script mutant probes: one trip per mutant.** Probing test strength by
-  mutating source is a judgment call, never a mandate — and with a declared
-  `test:mutation` script, the `mutation-testing` skill's single scripted run
-  already is the batch. When you do hand-probe, the apply → focused-test →
-  revert round trip is **one composite command** with the revert
-  unconditional — `;`-separated or a scripted loop, never `&&` before the
-  revert, and never separate edit / test / revert calls — and it leaves the
-  tree exactly as you found it. The probe set itself never shrinks: batching
-  buys trips, not experiments.
+- **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;
@@ -54,59 +55,201 @@ 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.
-Never inline it in the summary. Two things always ride your return in full, as
+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.
 
-## Turn economy
+## Evidence ledger
 
-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.
+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.
 
-- **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.
-- **Script mutant probes: one trip per mutant.** Probing test strength by
-  mutating source is a judgment call, never a mandate — and with a declared
-  `test:mutation` script, the `mutation-testing` skill's single scripted run
-  already is the batch. When you do hand-probe, the apply → focused-test →
-  revert round trip is **one composite command** with the revert
-  unconditional — `;`-separated or a scripted loop, never `&&` before the
-  revert, and never separate edit / test / revert calls — and it leaves the
-  tree exactly as you found it. The probe set itself never shrinks: batching
-  buys trips, not 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.
+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:
 
-## Evidence routing
+| 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 |
 
-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.
-Never inline it 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.
+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
 
@@ -114,15 +257,28 @@ 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
+**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). Two deviations from the procedure
+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
+`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.
@@ -150,12 +306,31 @@ empirically).
    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
@@ -164,10 +339,48 @@ empirically).
    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
@@ -240,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 /
@@ -57,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/triage.md

@@ -8,8 +8,8 @@
 > 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 output and keep its number (never open a
-> second issue). An **architecture-drift stub** is a pending stub too, so 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.
 
@@ -17,14 +17,15 @@ For small bugs that don't earn the full SDD ceremony. They skip the spec and its
 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, and create the issue with `harness:managed`
+   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 — §Sub-agent invocation in the core; on an architecture-drift stub the
+   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`,
@@ -33,6 +34,8 @@ but the branch, PR, and merge gate are the same — no path auto-merges:
    `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.
+   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.

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>`
@@ -32,16 +35,36 @@ interview yourself** to finish `ui-handoff.md` (the UI Designer then critiques i
 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