@lemoncode/lemony 0.1.2 → 0.3.0

package/catalog/schemas/tier2-events-history.md

@@ -22,12 +22,29 @@ Format per entry (one block per release):
 
 ### Renamed
 - `<event_type>.<old_field>` → `<new_field>` — <rationale>
+
+### Changed
+- `<event_type>.<field>` — <semantics-only change: shape untouched, meaning/unit changed>
 ```
 
 Empty sections may be omitted.
 
 ---
 
+## 0.2.0 — 2026-07-31
+
+### Changed
+
+- **`step` semantics: one step = one `tasks.md` group** (was: one task).
+  `tasks.md` now groups its atomic tasks under risk-sized step headers and the
+  step-by-step loop runs one implement→review→checkpoint cycle per group. **No
+  field renamed, added, or removed** — `step_completed.step`,
+  `review_rejected.step`, and `task_done.steps` keep their types; only the unit
+  they count changed. Readers comparing step counts across versions should
+  expect fewer steps per task from this version on.
+
+---
+
 ## 0.1.0-alpha.9 — 2026-06-18
 
 ### Added

package/catalog/schemas/tier2-events.md

@@ -149,14 +149,14 @@ Emitted by the Orchestrator when it transitions `spec-in-progress → spec-ready
 Emitted by the Orchestrator at closeout (after `gh pr view` confirms `MERGED`,
 before `git rm` of the task state).
 
-| Field               | Type   | Required | Axis            | Notes                                                                                                                                               |
-| ------------------- | ------ | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `task_id`           | string | yes      | `identity`      | Required for this type.                                                                                                                             |
-| `level`             | string | yes      | `internal-enum` | `L1` \| `L2` \| `L3` — the task-fit dial value used.                                                                                                |
-| `cycle_time_h`      | number | yes      | `metric`        | Wall-clock hours from issue creation to merge. ≥ 0, finite.                                                                                         |
-| `review_rejections` | number | yes      | `metric`        | Count of `review_rejected` events for this `task_id` (≥ 0, int).                                                                                    |
-| `mode`              | string | no       | `internal-enum` | `all_at_once` \| `step_by_step` — the mode chosen at the L1 approval gate. **Absent on L2** (the question only exists where `tasks.md` does).       |
-| `steps`             | number | no       | `metric`        | Count of `step_completed` events for this task (≥ 1, int). Only meaningful when `mode` is `step_by_step`; < total tasks after a mid-task downgrade. |
+| Field               | Type   | Required | Axis            | Notes                                                                                                                                                |
+| ------------------- | ------ | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `task_id`           | string | yes      | `identity`      | Required for this type.                                                                                                                              |
+| `level`             | string | yes      | `internal-enum` | `L1` \| `L2` \| `L3` — the task-fit dial value used.                                                                                                 |
+| `cycle_time_h`      | number | yes      | `metric`        | Wall-clock hours from issue creation to merge. ≥ 0, finite.                                                                                          |
+| `review_rejections` | number | yes      | `metric`        | Count of `review_rejected` events for this `task_id` (≥ 0, int).                                                                                     |
+| `mode`              | string | no       | `internal-enum` | `all_at_once` \| `step_by_step` — the mode chosen at the L1 approval gate. **Absent on L2** (the question only exists where `tasks.md` does).        |
+| `steps`             | number | no       | `metric`        | Count of `step_completed` events for this task (≥ 1, int). Only meaningful when `mode` is `step_by_step`; < total groups after a mid-task downgrade. |
 
 ### 5. `review_rejected` _(P5)_
 
@@ -168,7 +168,7 @@ dedicated label).
 | `task_id`         | string | yes      | `identity`      | Required for this type.                                                                                                                                                                                                                              |
 | `reason`          | string | yes      | `free-text`     | Short human-readable reason (one line; never the full review comment). 1-500 chars.                                                                                                                                                                  |
 | `iteration`       | number | yes      | `metric`        | 1-based: the Nth rejection of this task (≥ 1, int).                                                                                                                                                                                                  |
-| `step`            | number | no       | `metric`        | The step (1-based `tasks.md` task number) whose per-step review rejected. **Absent** on full-pass and all-at-once rejections.                                                                                                                        |
+| `step`            | number | no       | `metric`        | The step (1-based; one step = one `tasks.md` group) whose per-step review rejected. **Absent** on full-pass and all-at-once rejections.                                                                                                              |
 | `attributed_kind` | string | no       | `internal-enum` | `agent` \| `skill` \| `playbook` — the kind of component the friction is attributed to. **Omitted when the emitter can't attribute.**                                                                                                                |
 | `attributed_name` | string | no       | `internal-enum` | The component's name (free string, 1-200 chars), e.g. `implementer`. Independently optional in the schema; emitters pair it with `attributed_kind` and omit both when they can't attribute. Free-string by design — see [Attribution](#attribution). |
 
@@ -218,7 +218,7 @@ humans bail out (`ok_downgrade`).
 | Field               | Type   | Required | Axis            | Notes                                                                                                                                                                                                                            |
 | ------------------- | ------ | -------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `task_id`           | string | yes      | `identity`      | Required for this type.                                                                                                                                                                                                          |
-| `step`              | number | yes      | `metric`        | 1-based `tasks.md` task number the checkpoint belongs to (≥ 1, int).                                                                                                                                                             |
+| `step`              | number | yes      | `metric`        | 1-based step number the checkpoint belongs to (one step = one `tasks.md` group; ≥ 1, int).                                                                                                                                       |
 | `review_iterations` | number | yes      | `metric`        | Reviewer invocations that preceded this checkpoint (≥ 1, int — every step is reviewed before the human; resets after a "changes").                                                                                               |
 | `checkpoint_result` | string | yes      | `internal-enum` | `ok` \| `changes` \| `ok_downgrade` (OK and switch the remaining tasks to all-at-once).                                                                                                                                          |
 | `attributed_kind`   | string | no       | `internal-enum` | `agent` \| `skill` \| `playbook` — the kind of component the friction is attributed to. **Omitted when the emitter can't attribute.**                                                                                            |

package/catalog/skills/mutation-testing/SKILL.md

@@ -1,9 +1,8 @@
 ---
 name: mutation-testing
-description: Behavioral test-strength analysis of a change — mutate the changed source and check whether the suite actually fails. Surviving mutants mark tests that pass regardless of behavior. Advisory, diff-scoped, and capability-gated (only lands when the project declares a `test:mutation` script). Distinct from `test-gap-report` (structural — which files lack a spec) and `verify` (which just runs the suite).
+description: Behavioral test-strength analysis of a change — mutate the changed source and check whether the suite actually fails. Surviving mutants mark tests that pass regardless of behavior. Advisory and diff-scoped; a declared `test:mutation` script selects the cheap scripted path, its absence the hand-probe path. Distinct from `test-gap-report` (structural — which files lack a spec) and `verify` (which just runs the suite).
 origin: vendor
 vendor_version: '{{vendor_version}}'
-applies-when: [has-mutation-testing]
 phase: post-implementation
 invoked-by: [reviewer]
 ---
@@ -14,7 +13,7 @@ The **behavioral** counterpart to `test-gap-report`'s structural analysis. A str
 gap report asks "which changed files lack a dedicated spec?"; mutation testing asks the
 harder question: **do the tests that exist actually fail when the code misbehaves?** It
 mutates the source (flips `>` to `>=`, drops a line, swaps `&&`/`||`) and re-runs the
-suite. A mutant that **survives** — the tests still pass on the broken code — marks a
+tests. A mutant that **survives** — the tests still pass on the broken code — marks a
 test that asserts nothing load-bearing. Line coverage can't catch this; only mutation
 can.
 
@@ -23,17 +22,31 @@ output is noisy — equivalent mutants are real and unavoidable), and it only mu
 code the change touched, because mutating the whole tree per review is prohibitively
 slow.
 
-## Precondition (capability-gated)
+## Two paths, chosen at runtime
 
-This skill is only installed when the project declares a **`test:mutation`** script in
-`package.json` (the `has-mutation-testing` capability). If you are reading it, the
-script exists — run it. The harness stays tool-agnostic: the script may drive Stryker or
-any mutation tool. Delegate to it exactly as `verify` delegates to the project's
-declared scripts; never assume a specific tool's CLI.
+Check whether `package.json` declares a non-empty **`test:mutation`** script. That one
+fact picks the path:
 
-## Process
+- **Declared** → the **scripted path**: one batch run of the project's own script,
+  diff-scoped. The harness stays tool-agnostic — the script may drive Stryker or any
+  mutation tool. Delegate to it exactly as `verify` delegates to the project's declared
+  scripts; never assume a specific tool's CLI.
+- **Absent** → the **hand-probe path**: you mutate the source yourself, one composite
+  trip per mutant, and revert every time.
 
-### 1. Run the project's mutation script, scoped to the diff
+The two paths do **not** apply equally, by design:
+
+- The **scripted path runs on every review** where the script exists — it is a cheap
+  batch, and its advisory output also catches weak tests in changes that declared no
+  risk.
+- The **hand-probe path is never a per-review mandate.** What you owe by hand is the
+  Reviewer's evidence-ledger mutant floor (accounting for every changed non-test file
+  under `declared-risk` — the Reviewer contract's Evidence-ledger section owns that
+  rule; this skill never duplicates it), plus your own judgment when a survivor-shaped
+  doubt is worth one probe. Probing beyond the floor is a judgment call, never a
+  mandate.
+
+## Scripted path: run the project's mutation script, scoped to the diff
 
 Run the declared script focused on the **files this change modified** — not the whole
 tree. How to scope depends on the project's tool; read its config and adapt:
@@ -46,10 +59,47 @@ tree. How to scope depends on the project's tool; read its config and adapt:
 
 Capture the surviving mutants with their file + line.
 
-### 2. Classify each surviving mutant — the two-case model
+## Hand-probe path: mutate, test, revert — one composite trip per mutant
+
+Without a script, each probe is yours to run. The mechanics:
+
+- **Choose mutants that would expose a weak test.** Target the load-bearing logic the
+  change touched: flip a comparison (`>` ↔ `>=`), negate a guard, drop an early return,
+  swap `&&`/`||`, delete a write. A good mutant is one a real assertion should kill; a
+  cosmetic mutation (rename, whitespace) proves nothing.
+- **How many is judgment, anchored by the floor.** What a review owes, and what counts
+  as accounted-for, is the ledger contract's rule, not this skill's — the floor asks
+  for accounting, never exhaustion. One or two well-aimed probes per logic-bearing
+  file usually answer the question.
+- **The round trip is one composite command with the revert unconditional.** Apply the
+  mutation, run the focused test, and restore — `;`-separated or a scripted loop,
+  **never `&&` before the revert** (a red test must still revert), and never separate
+  edit / test / revert calls. It leaves the tree exactly as you found it:
+
+  ```bash
+  sed -i.bak '128s/>=/>/' src/queue.ts; \
+  npx vitest run src/queue.spec.ts; \
+  mv src/queue.ts.bak src/queue.ts
+  ```
+
+  (Line-addressed on purpose — one targeted mutant per trip keeps the kill
+  attributable; the `.bak` the in-place edit leaves is the revert.)
+
+  A **killed** mutant (the focused test went red) is the good outcome; a **survivor**
+  (still green on broken code) is the finding. Batching buys trips, never
+  experiments — the probe set itself never shrinks to save calls.
+
+- **Say so in your verdict — the nudge.** When this path ran, note in your verdict that
+  the project can buy the cheaper batch: declaring a `test:mutation` script in
+  `package.json` (driving Stryker or any mutation tool) activates the scripted path on
+  the next review. The human reads it at the checkpoint, exactly while the artisanal
+  cost is being paid. (Only when this path actually ran — never as a standing line.)
+
+## Classify each surviving mutant — the two-case model (both paths)
 
 A diff-scoped run mutates changed _files_, but a changed file still contains
-**pre-existing, untouched lines**. Where the mutant survives decides how you report it:
+**pre-existing, untouched lines**. Whichever path produced the survivor, where it
+survives decides how you report it:
 
 | Mutant survives on…                                      | Nature                                     | Channel                                                                |
 | -------------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------- |
@@ -60,16 +110,26 @@ Use the diff to decide which lines the change actually touched. When unsure whet
 mutated line is new or pre-existing, treat it as in-scope (verdict) — over-reporting in
 the verdict is cheaper than mis-routing a real gap to a dismissable offer.
 
-### 3. Report
+## Report
 
 - **In-scope surviving mutants** → list them in your review verdict as an **advisory**
-  block: file:line, the mutation that survived, and the assertion that would have caught
-  it. This is **not** a REJECT on its own (decision: advisory). The Implementer may
-  strengthen the tests; the Reviewer may still REJECT by _judgment_ if a survivor exposes
-  a genuinely dangerous untested path — but the mutation result alone never auto-blocks.
+  block: file:line, the mutation that survived, and the assertion that would have
+  caught it — all of them when few (over-reporting here is cheaper than mis-routing,
+  per the two-case model). On a noisy run, carry the highest-value ones in the
+  verdict and route the full list to the full-pass issue comment; on a per-step
+  review — which posts no comment — anything worth keeping goes in the verdict
+  bullets (the Orchestrator records those in `progress.md`); what you leave out dies
+  with your context. This is **not** a REJECT on its own (decision: advisory). The
+  Implementer may strengthen the tests; the Reviewer may still REJECT by _judgment_
+  if a survivor exposes a genuinely dangerous untested path — but the mutation result
+  alone never auto-blocks.
 - **Pre-existing surviving mutants** → run **`note-side-finding`**: one `## Side-findings`
   bullet each (file:line + the gap), then keep going. The Orchestrator collects it and
   offers the human a `/spinoff`. Don't fix it, don't reject on it — it isn't this task's.
+- **Hand probes under declared risk also land in the ledger.** When the review's record
+  carries `basis: declared-risk`, every probe you ran belongs in the sidecar's
+  `mutants.files` entries per the Evidence-ledger section of the Reviewer contract —
+  this skill points at that contract and never duplicates it.
 
 If no mutant survives on the changed lines, say so in one line — a clean diff-scoped
 mutation run is a meaningful positive signal about the new tests.
@@ -79,6 +139,7 @@ mutation run is a meaningful positive signal about the new tests.
 - **Equivalent mutants** (a mutation that can't change observable behavior, so no test
   could kill it) are expected. Don't chase them; flag a survivor only when a real
   assertion would have caught it.
-- Mutation testing is **slow** — keep it diff-scoped. If a single review's run is
+- Mutation testing is **slow** — keep it diff-scoped, and on the hand path run the
+  focused spec, never the whole suite per mutant. If a single review's scripted run is
   blowing the time budget, report what completed and note the un-covered files rather
   than silently truncating.

package/catalog/skills/prd-to-spec/SKILL.md

@@ -29,7 +29,7 @@ the gap by guessing — surface it (see "When the PRD is insufficient").
   real from the start — there is no `draft-<slug>` holder:
   - `requirements.md` — EARS requirements with acceptance criteria
   - `design.md` — files, functions, approach, edge cases, testing
-  - `tasks.md` — atomic, ordered, checkbox tasks
+  - `tasks.md` — atomic, ordered checkbox tasks, grouped under risk-sized step headers
 
 ## Process
 
@@ -126,16 +126,84 @@ Atomic, ordered checkboxes. Each task is a **vertical slice** (a behavior, not a
 layer) so the Implementer can run TDD red→green per task. Reference the requirements
 each task satisfies.
 
+Group the tasks under **risk-sized step headers**. In step-by-step mode the loop runs
+one implement→review→human-checkpoint cycle **per group**, so the grouping decides how
+often the human is interrupted; the human approves it at the spec gate with the rest
+of the spec. Grouping criterion:
+
+1. **Risk isolates — hard rule.** A task gets its own group iff it concentrates risk:
+   a new seam, a hard-to-reverse decision, a data-loss or security surface.
+2. **Runnable surface closes — soft rule.** Among trivial stretches, prefer group
+   boundaries that leave something the human can run at the checkpoint. Never invent
+   a group to fabricate a demo.
+3. **Soft cap: 4 tasks per group**, exceedable only with explicit justification in
+   the group's rationale (e.g. "5 identical mechanical renames").
+4. **Every group header carries a one-line boundary rationale** so the grouping is
+   auditable at the spec gate.
+5. **A group whose risk has a name carries it as a machine-readable tag.** When the
+   damage a group can do is one the vocabulary below names, the header ends with
+   `[risk: <class>]` — the **last element of the line**, after the rationale; multiple
+   classes are comma-separated (`[risk: data-loss, secrets]`).
+   The vocabulary names what kind of damage the surface can do:
+
+   <!-- risk-vocabulary:start -->
+
+   | Class             | Surface                                                          |
+   | ----------------- | ---------------------------------------------------------------- |
+   | `auth`            | authentication, authorization, session or token handling         |
+   | `payments`        | money movement, billing, pricing                                 |
+   | `shell-process`   | shell invocation, subprocess spawning, argument construction     |
+   | `data-loss`       | writes, deletes, migrations, anything that can destroy user data |
+   | `secrets`         | credentials, keys, tokens — at rest or in transit                |
+   | `executable-mode` | file permissions, exec bits, anything that changes what can run  |
+
+   <!-- risk-vocabulary:end -->
+
+   The tag keys on **damage, not on which rule made the group**. A group that isolates
+   a new seam or a hard-to-reverse decision is a risk isolate under rule 1 and still
+   carries **no tag**, because no class names that damage — and absence is itself the
+   declaration ("nothing here does one of those things"), never an omission.
+
+   If a group's damage has no class in the vocabulary, **leave the tag off and name that
+   damage in the group's rationale** — rule 4 already requires a rationale, and damage
+   named in prose beats a wrong class in a tag. Then say so in your handoff summary, in
+   one line, so the human can decide whether the vocabulary should grow. Do **not** pick
+   the nearest class (the self-check below rejects it), do not invent a one-off class,
+   and do not edit the table here: it is vendor-owned — generated into this skill and
+   `triage-issue` from one source, so the two always agree — and a local edit is
+   discarded on the next harness update.
+
+   The tag is what the **human approves at the spec gate**: approving the spec approves
+   the grouping _and its tags_, so a wrong tag is a spec defect, not a review defect.
+   That approval is where its force starts, and a reader now depends on it: at review the
+   tags are handed to `security-review`, which deepens the section named for each class
+   instead of inferring the surface from the diff. And a script reads them: the review
+   evidence ledger's validator (`lemony review-ledger validate`) checks every tag on the
+   group under review against the vocabulary and reports one outside it as
+   `unknown-risk-class` — a spec defect that reaches the human, never a silent drop.
+
 ```markdown
 # Tasks — <topic>
 
+## Group 1 — <name> _(<one-line boundary rationale>)_
+
 - [ ] T1 — <smallest behavior that proves the path end-to-end> (R1)
 - [ ] T2 — <next behavior> (R2)
+
+## Group 2 — <name> _(<one-line boundary rationale>)_ [risk: data-loss]
+
 - [ ] T3 — <error path> (R2, R3)
 ```
 
 Rules: order so the first task is a tracer bullet; never "write all tests" then
-"write all code"; keep each task small enough to verify on its own.
+"write all code"; keep each task small enough to verify on its own. Grouping never
+changes task granularity — checkboxes stay atomic and TDD runs per task; only review
+and checkpoint frequency follow the groups (all-at-once mode ignores the headers).
+Tasks added mid-implementation (from a discovery) default to **their own group** —
+they are risk by definition, and grouping rule 5 applies to them unchanged — but they
+are added **after** the spec gate, and no later gate presents a group header, so their
+tags get no human reading at all. Tag them for the record; do not rely on anyone
+catching a wrong one.
 
 ### 5. Self-check before handing off
 
@@ -143,6 +211,10 @@ Rules: order so the first task is a tracer bullet; never "write all tests" then
 - [ ] Every requirement is EARS-formatted and testable.
 - [ ] At least one unwanted-behavior (`If … then …`) requirement exists.
 - [ ] Every requirement is covered by at least one task.
+- [ ] Every task sits in a group, and every group header carries a one-line
+      boundary rationale.
+- [ ] Every group that can do damage the vocabulary names ends its header with a
+      `[risk: …]` tag; no group carries a class whose damage it cannot do.
 - [ ] No closed PRD decision is contradicted.
 
 ### 6. Emit `spec_created`

package/catalog/skills/raise-discovery/SKILL.md

@@ -32,6 +32,12 @@ human, and you do not resume yourself — the Orchestrator owns all of that (it
 | **T5** | INFEASIBILITY        | The plan is not implementable as written.                  |
 | **T6** | PLAYBOOK_CONFLICT    | Honoring the spec would contradict a client playbook.      |
 
+**Oversize / partition is a T2.** When the scope you are structuring or implementing
+hides **≥2 independently mergeable units** the plan didn't reveal — each could leave the
+default branch green and shippable without the other — the plan is silent on the cut
+and both "partition" and "keep together" are valid: raise it as `T2 UNSPECIFIED_DECISION`
+with the candidate cut in **Proposed**. Never partition silently from inside a task.
+
 ## When NOT to raise (resolve it yourself)
 
 Escalation is for decisions with architectural or scope impact, not for everything

package/catalog/skills/resolve-discovery/SKILL.md

@@ -64,13 +64,16 @@ is a second discovery — append it, don't fold it in.
 
 The agent that **created** an artifact is the one that updates it. Map the decision to
 the artifact it changes, then invoke that owner (fresh context, Task tool) with the
-decision + the entry as context:
+decision **stated in full** — at this moment it exists nowhere on disk; the entry's
+`**Resolution**` block is only written at step 4 — plus the `discoveries.md` entry
+**by path** for the surrounding context (it reads the entry itself):
 
-| Artifact changed by the decision                                     | Owner to invoke                                                                                                                                             |
-| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `spec/requirements.md`, `spec/design.md`, `spec/tasks.md`            | **Spec Author**                                                                                                                                             |
-| Implementation code, `progress.md`, `notes.md`                       | **Implementer** (often just the resumed sub-agent)                                                                                                          |
-| `docs/adr/NNNN-<slug>.md`, `docs/architecture.md`, `docs/playbooks/` | **Architect** (on-demand) — `write-adr` to record the decision, `update-architecture` to keep the map true, `playbook-iterate` for a `T6 PLAYBOOK_CONFLICT` |
+| Artifact changed by the decision                                                        | Owner to invoke                                                                                                                                             |
+| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `spec/requirements.md`, `spec/design.md`, `spec/tasks.md`                               | **Spec Author**                                                                                                                                             |
+| Implementation code, `progress.md`, `notes.md`                                          | **Implementer** (often just the resumed sub-agent)                                                                                                          |
+| A child issue's trace lines, a triage issue's fix plan, the parent partition-plan issue | **Orchestrator** (you) — `gh issue edit --body-file`, read-modify-write (an oversize discovery answered "partition": `.claude/agents/partition.md`)         |
+| `docs/adr/NNNN-<slug>.md`, `docs/architecture.md`, `docs/playbooks/`                    | **Architect** (on-demand) — `write-adr` to record the decision, `update-architecture` to keep the map true, `playbook-iterate` for a `T6 PLAYBOOK_CONFLICT` |
 
 Not every resolution needs an artifact update first. If the decision is simply "do X"
 with no change to the contract, skip straight to recording it and resuming. If it
@@ -104,7 +107,9 @@ do not edit the raise fields):
    Same fail-loud contract: a non-zero exit means the flag/status did not flip back.
 
 2. Re-invoke the paused sub-agent (fresh context) with: the issue, the task-state
-   paths, the decision, and the updated artifact. It picks up from where it stopped.
+   paths, a one-line gist of the decision (the full `**Resolution**` block now
+   lives in the `discoveries.md` entry — reference it), and the updated artifact's
+   **path**. It reads the files itself and picks up from where it stopped.
 
 ## Closeout invariant
 

package/catalog/skills/security-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: security-review
-description: Security review of a change — OWASP-style vectors plus AI/LLM-specific risks. Checks input validation, authorization/IDOR, injection, secrets & logging, transport/headers, dependencies, and prompt-injection where an LLM is in the loop. Use after `senior-review` on any change touching user input, auth, data access, or an LLM.
+description: Security review of a change — OWASP-style vectors plus AI/LLM-specific risks. Checks input validation, authorization/IDOR, injection, secrets & logging, transport/headers, dependencies, prompt-injection where an LLM is in the loop, shell and subprocess use, money movement, destructive writes, and executable surface. Every risk class a change can be declared under names one section, and a declaration handed over with the invocation deepens that section. Use after `senior-review` on any change touching user input, auth, data access, money, destructive writes, a subprocess, file permissions, or an LLM.
 origin: vendor
 vendor_version: '{{vendor_version}}'
 phase: post-implementation
@@ -15,6 +15,38 @@ endpoint or an LLM call. Consult the project's **security playbook** for project
 specific rules (deployment model, auth scheme, secret tooling); the checklist below is
 the generic floor. Flag only findings you're confident are real, ranked by severity.
 
+## Declared risk surfaces
+
+Your invocation may carry a **declaration**: the kind of damage this change can do, named
+at the structuring moment — before a line of it was written — and approved by a human, as a
+class paired with the group or the file it was declared against. When one reaches you, it
+is a **floor for depth, never a bound on scope**:
+
+- Every section below still runs. The declaration says where to press harder, not what to
+  skip: it was written before the code existed, so it cannot know what the diff ended up
+  touching. Deriving the surface from the change itself remains your job.
+- For each declared class, go to the section whose heading carries it. Every class in the
+  vocabulary names **exactly one** section below — the backticked class at the end of the
+  heading (`` ## 2. Authorization … — `auth` ``) — and a guard pins that the set of classes
+  in these headings and the vocabulary are the same set, so no heading ends in
+  `` — `token` `` unless `token` is a class. Go deep there: read the declared file whole
+  rather than sampling its diff, and follow the vector out of the change into the code it
+  reaches.
+- A declared class that matches **no heading** is drift between the vocabulary and this
+  checklist — a guard should have caught it — not a class you may skip. Review it against
+  the project's security playbook and the generic floor, and **name it in the report** as
+  covered without a dedicated section, so the gap surfaces as a gap and not as silence.
+- Damage the vocabulary could not name arrives as prose rather than a class — an
+  `unclassified: <path> — <what it can do>` line, or the rationale of a group that left its
+  tag off. That is a declaration, not a gap: take the prose as the brief and review that
+  path against it.
+
+**No declaration is not a clean bill of health.** A declaration of `none` is a claim that
+the change touches no such surface; a _missing_ declaration is no claim at all — the task
+may simply predate the section. In both cases scope the depth from the change itself,
+exactly as you would without one, and never report a surface as absent on the strength of a
+declaration alone.
+
 ## 1. Input validation at boundaries
 
 - Every entry point (request body, query/path params, headers, file, env, third-party
@@ -23,28 +55,41 @@ the generic floor. Flag only findings you're confident are real, ranked by sever
   internal type.
 - No mass-assignment: unexpected fields are rejected, not spread into a model.
 
-## 2. Authorization (not just authentication)
+## 2. Authorization (not just authentication) — `auth`
 
 - **Authentication** (who are you?) and **authorization** (are you allowed?) are
   distinct checks — a valid session is not permission.
 - **Ownership / IDOR**: a resource fetched by id verifies it belongs to the caller. An
   auth guard never substitutes for the ownership check.
 - Privileged actions check role/scope server-side, never trusting a client claim.
+- **Session & token handling**: a token is verified before it is trusted — signature and
+  algorithm pinned (never `none`, never caller-chosen), `exp`/`iss`/`aud` checked, claims
+  never read from an unverified decode. Sessions rotate on login and privilege change,
+  and logout/revocation invalidates server-side, not just client-side (cookie flags: §5).
 
 ## 3. Injection
 
 - **SQL/NoSQL**: parameterized queries / validated ids; never interpolate user input
   into a query, never pass a raw request object to a query (object-injection).
-- **Command/path**: no user input concatenated into a shell command or file path
-  (path traversal).
+- **Path**: a path built from user input is resolved and then proven to stay under a
+  fixed base — `join`/`resolve` alone are not that proof (`join` normalizes `..` through,
+  `resolve` lets an absolute segment discard the base); absolute and `..` segments are
+  rejected rather than stripped, and `realpath` is used where symlinks can exist.
+  Shell-command construction is §8.
 - **Output/XSS**: rendered user content is escaped by default; raw-HTML sinks
   (`dangerouslySetInnerHTML`, server-generated HTML/PDF) sanitize at render time.
 
-## 4. Secrets & logging
+## 4. Secrets & logging — `secrets`
 
 - No secret, token, password, key, or PII in code, logs, or error messages (a
   never-log redaction list is configured; emails in failure logs are hashed).
-- No secret committed (`.env` gitignored; `.env.example` carries placeholders only).
+- **At rest**: a secret lives in the platform's secret store or a file only the app can
+  read (0600) — never a world-readable config, an image layer, or the repo (`.env`
+  gitignored; `.env.example` placeholders only). Passwords are stored under a slow KDF
+  (argon2/bcrypt/scrypt), never a bare or fast hash.
+- **In transit**: a secret never rides in a URL or query string (proxies, browser history
+  and `Referer` capture those) — header or body over TLS only (§5) — and a leaked one has
+  a rotation path that does not require a deploy.
 - Constant-time comparison for secrets/tokens (no `===` on a hash); strong randomness
   for generated keys.
 
@@ -73,11 +118,79 @@ the generic floor. Flag only findings you're confident are real, ranked by sever
   third-party model; tool/function access from the model is least-privilege.
 - **Resource limits**: token/cost/loop bounds on agentic calls to prevent runaway use.
 
+## 8. Shell & subprocess — `shell-process`
+
+- **Argument construction**: no untrusted input concatenated into a command string;
+  arguments go as an array to an exec-style API (`execFile`/`spawn` without
+  `shell: true` — and on Windows a `.cmd`/`.bat` target is shell-parsed regardless),
+  never through a shell. An array is not sufficient on its own: a value that can begin
+  with `-` is read by the binary as a flag, so untrusted values sit after `--` or are
+  validated against a known form.
+- **Spawn surface**: every new subprocess is deliberate — the binary resolved from a
+  known path rather than the inherited `PATH`, and the child running with no more
+  privilege than the caller (no `sudo`, setuid, or elevated container).
+- **Secrets across the boundary**: a secret never travels as a command-line argument —
+  argv is world-readable in `ps`. It goes via the child's environment (pruned to what the
+  child needs), stdin, or a file descriptor.
+- **Child I/O**: the child's output is untrusted input at a boundary (§1 — and §7 as well
+  if it reaches an LLM) before it drives anything; its exit code is checked, not assumed;
+  and it cannot hang or flood the parent unbounded (timeout, kill, output cap).
+
+## 9. Money, billing & pricing — `payments`
+
+- **Idempotency**: every charge, refund, or transfer is idempotent under retry
+  (idempotency key, provider-side dedup) — a replayed webhook or a double submit cannot
+  move money twice.
+- **Amount & currency integrity**: amount and currency come from the server-side record,
+  never from the client; arithmetic is in integer minor units (no floats), the rounding
+  rule is explicit, and totals are recomputed rather than trusted.
+- **Bounds & entitlement**: amounts, quantities and discounts are range- and sign-checked
+  server-side — no negative charge, no refund above what was captured, no coupon reused
+  or stacked past its rule — and access a payment buys is granted on settled state and
+  revoked when that state reverses.
+- **Provider trust boundary**: webhooks are signature-verified against the **raw** request
+  body (a JSON body parser mounted ahead of the route silently breaks this) and
+  replay-windowed; state transitions (pending → paid → refunded) are enforced server-side
+  and written to an audit trail (who, what, when).
+
+## 10. Destructive writes & data — `data-loss`
+
+- **Scoped deletes and updates**: every delete or bulk update carries a bounding
+  predicate (tenant/owner/id) that is proven non-empty at runtime, not merely present in
+  the source — an `undefined` id the ORM silently drops, or a filter built from a request
+  that arrives `{}`, is a collection-wide call wearing a `where`.
+- **Irreversibility**: a migration or schema change has a tested rollback, or is
+  explicitly one-way and says so; a destructive data migration runs behind a
+  backup/snapshot step. Soft-delete where a human may need to recover — and where it is
+  used, every read path filters deleted rows and records holding personal data still
+  have a real erasure path, not an indefinite tombstone.
+- **Atomicity**: writes that must succeed together are transactional or idempotently
+  replayable — a partial failure cannot leave data half-written and report success.
+- **On disk**: a write replaces a file atomically (temp + rename), never truncates or
+  deletes a path the change did not create, and never follows a symlink to do it. Any
+  destructive path is proven non-empty before use — a path variable that can be empty
+  turns a scoped delete into a root-relative one.
+
+## 11. Executable surface — `executable-mode`
+
+- **Permission changes**: no `chmod`/exec-bit change beyond what the feature needs;
+  neither the file nor the directory holding it becomes world-writable (a 0755 script in
+  a 0777 directory is replaceable), and no write-then-execute path — a file the app
+  writes is never later executed without a trust decision.
+- **Install-time surface**: files laid down by an installer or updater carry the minimum
+  mode; a hook or script that gains executable mode is reviewed as code that runs, not
+  as data.
+- **What can run**: a change to what the system executes unattended — a new entry point,
+  hook, cron or launch agent, service unit, `postinstall`, or a changed interpreter
+  shebang — is named in the report with who can write to it and what triggers it, even
+  when it looks routine. How this change spawns a process is §8.
+
 ## Report
 
 ```
 ## Security Review — <task name>
 
+**Declared surfaces**: <class → where you pressed> | none declared | no declaration handed over
 **Critical**: <vector — file:line — fix> | none
 **High**: <…> | none
 **Medium**: <…> | none

package/catalog/skills/spec-compliance-check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec-compliance-check
-description: Walk an L1 spec point by point against the implementation and emit a per-requirement pass/fail verdict. Use during review of an SDD task to prove every EARS requirement (including unwanted-behavior paths) is satisfied and tested — a committable audit trail. Complements `senior-review` (quality) with traceability (coverage of intent).
+description: Walk an L1 spec point by point against the implementation and emit a per-requirement pass/fail verdict. Use during review of an SDD task to prove every EARS requirement (including unwanted-behavior paths) is satisfied and tested — a durable audit trail. Complements `senior-review` (quality) with traceability (coverage of intent).
 origin: vendor
 vendor_version: '{{vendor_version}}'
 phase: post-implementation
@@ -11,7 +11,7 @@ invoked-by: [reviewer]
 
 `senior-review` judges whether the code is _good_; this skill proves it does what the
 **spec said** — every requirement, point by point. It produces a traceability matrix:
-a committable audit trail mapping each requirement to its implementation and its test.
+a durable audit trail mapping each requirement to its implementation and its test.
 Only meaningful for **L1 (SDD) tasks** that have a spec under
 `.claude/state/tasks/<id>/spec/`; skip it for L2.
 
@@ -25,8 +25,8 @@ Read all three spec artifacts for the task:
   state-driven / optional-feature / **unwanted-behavior**), each numbered with
   acceptance criteria.
 - `design.md` — the intended files, interfaces, approach, edge cases.
-- `tasks.md` — the atomic checklist, each item referencing the requirements it
-  satisfies.
+- `tasks.md` — the atomic checklist grouped under risk-sized step headers, each
+  item referencing the requirements it satisfies.
 
 ### 2. Trace each requirement to the implementation
 
@@ -55,6 +55,10 @@ and asserts the rejection/guard.
 
 ### 4. Emit the matrix
 
+Destination: the full-pass **issue comment**. In your return summary — and always on
+a per-step review, which posts no comment — carry only the counts + the failing
+rows, per the Reviewer's verdict-size rule.
+
 ```
 ## Spec Compliance — task #<id>
 

package/catalog/skills/spec-to-issue/SKILL.md

@@ -37,6 +37,8 @@ The body is the externalized spec — self-contained enough to read on GitHub, w
 links back to the committed files for the full detail:
 
 ```markdown
+<trace lines, if the skeleton carried any — verbatim, first>
+
 ## Summary
 
 <one paragraph: the capability and why, from the PRD>
@@ -61,7 +63,11 @@ gh issue edit <id> --body-file <body>
 ```
 
 This overwrites the `🚧 Spec in progress …` skeleton the Orchestrator wrote at issue
-creation. Labels are untouched — the issue still carries `harness:managed` +
+creation. **Preserve its trace lines**: a task that is a part of a partitioned feature
+carries `Part <k> of #<parent>` (and `Depends on #<sibling> …`) at the top of the
+skeleton — read the current body first and keep those lines, verbatim, as the first
+lines of the new body. They are how the parent plan, `/resume`, and closeout find the
+task's place in the partition; dropping them orphans the part. Labels are untouched — the issue still carries `harness:managed` +
 `harness:sdd` + `harness:status:spec-in-progress`; the Orchestrator flips it to
 `spec-ready` after you hand back.