mandrel 2.0.0 → 2.1.0

package/.agents/README.md

@@ -96,17 +96,17 @@ The bootstrap pipeline, in order:
 3. **Project-side mutations.** Seeds `.agentrc.json` from
    [`starter-agentrc.json`](starter-agentrc.json), merges the framework's
    runtime dependencies into `package.json`, runs the install, wires the
-   command-sync hook (the UserPromptSubmit hook that regenerates the flat
-   `.claude/commands/` tree so every `/<command>` loads), wires the system
-   prompt (see below), gitignores derived artefacts, and runs the
-   quality-gates installer.
+   system prompt (see below), gitignores derived artefacts, and runs the
+   quality-gates installer. The flat `.claude/commands/` tree is generated
+   at install time (via `prepare`) and on every `mandrel sync`/`update` —
+   see [`mandrel sync-commands`](#mandrel-sync-commands) below.
 4. **GitHub-side mutations.** Creates the label taxonomy, branch protection,
    and merge-method settings. Skipped with `--skip-github`. Two additional
    mutations are **opt-in** (prompted y/N, defaulting No, or passed as flags):
    - `--with-project-board` — provision the Projects V2 Status field and
      custom fields on an existing board.
-   - `--with-issue-forms` — generate `.github/ISSUE_TEMPLATE/story.yml` and
-     `epic.yml` from the ticket-body schema.
+   - `--with-issue-forms` — generate `.github/ISSUE_TEMPLATE/story.yml`
+     from the ticket-body schema.
 
 The bootstrap is idempotent — safe to re-run; an already-configured
 clone produces zero file mutations.
@@ -154,6 +154,7 @@ Run `mandrel --help` for a subcommand list. Each subcommand supports
 | `init` | Install + configure mandrel in the current project (cold-start). | `--assume-yes`, `--skip-github`, `--dry-run` |
 | `sync` | Re-materialize `.agents/` from the installed package payload. | `--dry-run` |
 | `sync-commands` | Regenerate `.claude/commands/` from `.agents/workflows/`. | — |
+| `sync-agents` | Regenerate `.claude/agents/` from `.agents/agents/`. | — |
 | `doctor` | Run readiness checks and print per-check remedies. | — |
 | `update` | Upgrade mandrel to the newest published version. | `--dry-run`, `--install-cmd` |
 | `migrate` | Apply version-keyed migrations for a version range. | `--from`, `--to`, `--dry-run` |
@@ -175,13 +176,27 @@ mandrel explain --json     # same report as JSON
 ### `mandrel sync-commands`
 
 Regenerates the flat `.claude/commands/` projection from `.agents/workflows/`.
-The bootstrap wires a `UserPromptSubmit` hook that runs this automatically on
-every Claude Code prompt submission, so manual runs are rarely needed.
+Runs automatically at install time (via the `prepare` script) and as part of
+`mandrel sync` / `mandrel update`; doctor's `commands-in-sync` check flags a
+hand-edited or stale tree. Refuses to project when the materialized `.agents/`
+tree doesn't match the running CLI's own version — run `mandrel sync` first.
 
 ```bash
 mandrel sync-commands      # rebuild .claude/commands/
 ```
 
+### `mandrel sync-agents`
+
+Regenerates the flat `.claude/agents/` projection from `.agents/agents/` —
+the role-scoped boot contexts (`story-worker`, `acceptance-critic`) that
+`delivery.routing.roleScopedAgents` (default `true`) dispatches spawns
+against. Same delegation shape, wiring, and version-match refusal as
+`sync-commands` above.
+
+```bash
+mandrel sync-agents        # rebuild .claude/agents/
+```
+
 ### `mandrel uninstall`
 
 Reverses a recorded install using the install ledger
@@ -247,6 +262,13 @@ read-when-relevant pattern skills use).
   [`rules/test-seams.md`](rules/test-seams.md)) — when the task is in that
   domain.
 - Every `SKILL.md` under [`skills/`](skills/) — when the task hits its trigger.
+  A `SKILL.md` is itself split the same way: it leads with its **Policy
+  Capsule** (the contract, and the whole cost of activating the skill) plus
+  pointers into an on-demand `reference.md` sibling carrying the long-form
+  material. Activating a skill costs the capsule, not the essay — open a
+  `reference.md` section only when the task engages it. Routing does not
+  depend on the long-form being inline: skill descriptions live in the
+  generated [`skills/skills.index.json`](skills/skills.index.json).
 - [`docs/execution-reference.md`](docs/execution-reference.md) — log-level and
   token-budget reference detail lifted out of `instructions.md`.
 
@@ -280,10 +302,10 @@ For non-interactive (CI) installs, pass `--owner`, `--repo`, and
 `--assume-yes`; pass `--skip-github` to defer the remote half.
 
 After bootstrap, every Mandrel command is generated into a flat
-`.claude/commands/` tree by `npm run sync:commands` (the UserPromptSubmit hook
-keeps it current) and loads as a bare `/<command>` slash command — e.g.
-`/plan`, `/deliver`, `/audit-security`. The commands load in every Claude Code
-environment. The [SDLC guide](docs/SDLC.md) walks end-to-end planning and
+`.claude/commands/` tree by `npm run sync:commands` (kept current at install
+time and on every `mandrel sync`/`update`) and loads as a bare `/<command>`
+slash command — e.g. `/plan`, `/deliver`, `/audit-security`. The commands load
+in every Claude Code environment. The [SDLC guide](docs/SDLC.md) walks end-to-end planning and
 delivery; Stories pair [`/plan`](workflows/plan.md) (idea → drafted Story Issue)
 with [`/deliver`](workflows/deliver.md) (Story Issue → merged
 PR).
@@ -408,9 +430,9 @@ rule:
 > GitHub I/O, label transitions, JSON validators, NDJSON readers,
 > diff-vs-baseline gates, template renderers.
 >
-> **Prompt + judgment → make it a Skill.** Examples: composing a Tech
-> Spec from an Epic body, classifying friction signals from a failed shell
-> command, decomposing a Tech Spec into a ticket hierarchy.
+> **Prompt + judgment → make it a Skill.** Examples: composing a Story's
+> `## Spec` from planning context, classifying friction signals from a
+> failed shell command, decomposing a Spec into Stories.
 
 The rule is two-sided on purpose. "Has an LLM step adjacent" is *not*
 the signal — many deterministic scripts emit a JSON envelope that a host
@@ -424,17 +446,18 @@ The collapsed plan pipeline (`plan-context.js` → author → `plan-persist.js`,
 Epic #4474) is a **split**: the deterministic halves stay as scripts, the
 judgment middle moves to a Skill.
 
-- **`--emit-context`** (script half) — fetches the Epic body (which
-  carries the folded Tech Spec sections), scrapes project docs, emits a
-  JSON envelope. Parseable in, parseable out. Stays a script.
+- **`--emit-context`** (script half) — fetches the seed/source tickets
+  and scrapes project docs, emits a JSON envelope. Parseable in,
+  parseable out. Stays a script.
 - **Authoring middle** (Skill half) — given the envelope, author the
-  ticket hierarchy JSON. Pure prompt + judgment. Migrates to a Skill
+  Story JSON. Pure prompt + judgment. Migrates to a Skill
   under `.agents/skills/core/` so it ships with declarative
   `allowed_tools` and a smoke test rather than bespoke prompt-template
   plumbing inside a Node module.
 - **Persist half** (script half) — given the author-provided tickets
-  JSON, validate against the schema, create GitHub issues, flip the Epic
-  label. Deterministic GitHub I/O + schema validation. Stays a script.
+  JSON, validate against the schema, create the `type::story` issue(s)
+  and label them `agent::ready`. Deterministic GitHub I/O + schema
+  validation. Stays a script.
 
 The split codifies the "host LLM authors directly" pattern explicitly:
 the prompt+judgment step gets a `description`, an
@@ -524,8 +547,8 @@ comment) is the cross-runtime contract.
 The SDK barrel is `scripts/lib/orchestration/index.js`; its exports are
 the source of truth for the public in-process surface. Key families
 include dispatch (`dispatch-engine.js`, `manifest-builder.js`), context
-hydration, planning state, label transitions, Epic runner phases,
-Story-close internals, retro heuristics, and structured error capture.
+hydration, planning state, label transitions, Story-close internals,
+retro proposals, and structured error capture.
 
 ### GitHub authentication
 
@@ -578,7 +601,7 @@ environment inside the check. A finding includes `id`, `severity`,
 `autoCorrectable`.
 
 `autoCorrect: 'auto'` means the fix is local, bounded, and reversible.
-Auto-fixes must not push to remotes, commit to `epic/*` or `main`, amend
+Auto-fixes must not push to remotes, commit to `main`, amend
 history, recursively delete outside `.worktrees/<id>/`, write GitHub
 state, or read secret values. Anything requiring those operations must be
 `refuse-and-print` with a human-run `fixCommand`.
@@ -828,7 +851,7 @@ Two operators can drive the same repository at once — for example, two
 runs from clobbering one another with **two distinct coordination layers**.
 They solve different problems and must not be confused:
 
-- **Filesystem locks** (`epic-merge-lock`, `sweep-lock`) serialise work
+- **Filesystem locks** (`sweep-lock`) serialise work
   **within a single machine/clone**. They are keyed on local process PIDs
   and live under `.git/` (or a local lockfile path), so they do **not**
   coordinate across clones. See
@@ -844,8 +867,16 @@ The lease primitive lives in
 [`scripts/lib/orchestration/ticket-lease.js`](scripts/lib/orchestration/ticket-lease.js).
 Rather than inventing a new state column, the lease rides the ticket's
 existing **assignees** field: the single assignee *is* the lease owner.
-Liveness is decided by the owner's most-recent `story.heartbeat` timestamp
-compared against a configurable TTL (`delivery.lease.ttlMs`).
+Liveness is decided by the owner's last-heartbeat timestamp compared against
+a configurable TTL (`delivery.lease.ttlMs`).
+
+> **In practice the lease always fails closed.** There is no live heartbeat
+> source — the `story.heartbeat` emitter was structurally inert and has been
+> deleted (A22) — so every guard anchors the owner's heartbeat to *now*,
+> making **any** foreign claim read as live. The **stale-claim reclaim** row
+> below is therefore unreachable in normal operation: a stranded claim is
+> cleared with `--steal`, never by TTL expiry. The TTL and the reclaim branch
+> remain as a seam for a caller that supplies its own `heartbeatAt`.
 
 The model has five behaviours, all expressed through `acquireLease` /
 `releaseLease`:
@@ -855,7 +886,7 @@ The model has five behaviours, all expressed through `acquireLease` /
 | **Acquire by self-assign** | The ticket is unassigned. | The operator is written to `assignees`; the run proceeds (`reason: 'unclaimed'`). |
 | **Re-affirm a self-held claim** | The operator already holds the lease. | No write; the run proceeds (`reason: 'already-held'`). |
 | **Refuse-if-foreign** | A *different* operator holds the lease and their heartbeat is within the TTL (the claim is **live**). | The acquire **fails closed** — the run refuses to start and names the current owner so you know who to coordinate with (`reason: 'held'`). |
-| **Stale-claim reclaim** | A foreign claim exists but its heartbeat is older than the TTL (or the owner never heartbeated). | The lease is automatically reassigned to the operator (`reason: 'reclaimed'`). An abandoned claim never wedges the ticket. |
+| **Stale-claim reclaim** *(unreachable — see above)* | A foreign claim exists but the caller supplied a `heartbeatAt` older than the TTL. | The lease is reassigned to the operator (`reason: 'reclaimed'`). No shipped caller supplies one, so this never fires today. |
 | **`--steal` override** | A foreign claim is *live* and the operator passes `--steal`. | The live claim is forcibly transferred (`reason: 'stolen'`). This is the **only** way past a live foreign claim. |
 
 On a clean completion the holder **releases** the lease (clears the

package/.agents/agents/acceptance-critic.md

@@ -4,8 +4,9 @@ description: >-
   Role-scoped boot context for a maker-blind acceptance critic. Booted on its
   own system prompt (no CLAUDE.md / instructions.md closure). Scores a delivered
   diff against the Story's acceptance-criteria cluster and emits the verdict
-  schema — without seeing the maker's self-assessment. INERT under M7-A — no
-  workflow references this agent type yet (that is M7-B).
+  schema — without seeing the maker's self-assessment. Live under M7-B —
+  helpers/deliver-story Step 1a dispatches subagent_type: acceptance-critic
+  on the default risk-routed path.
 ---
 
 # acceptance-critic — maker-blind acceptance evaluation
@@ -34,8 +35,11 @@ file they authored. You grade the **work product**, not the homework the maker
 turned in about it. Your only trusted inputs are:
 
 - the working **diff** (`git diff origin/<baseBranch>...HEAD`),
-- the Story's inline `acceptance[]` and `verify[]` arrays (from the
-  `story-init` structured comment: `context.acceptance` / `context.verify`),
+- the Story's inline `acceptance[]` and `verify[]` arrays, read from the
+  **Story body itself** (`gh issue view <storyId> --json body`) — its `##
+  Acceptance` / `## Verify` sections are the SSOT. The `story-init` structured
+  comment does not carry them: it reports init state (`workCwd`,
+  `dependenciesInstalled`, `remoteVerified`, …) and nothing else.
 - the **actual output** of the `verify[]` commands you run yourself.
 
 Treat the implementation reasoning as untrusted. Score each criterion afresh
@@ -66,12 +70,10 @@ For each acceptance item in your cluster:
    a passing run records an evidence entry in the keyspace close consults:
 
    ```bash
-   # Epic-attached Story:
    node <main-repo>/.agents/scripts/evidence-gate.js \
-     --epic-id <epicId> --scope-id <storyId> --gate lint \
+     --standalone --scope-id <storyId> --gate lint \
      --worktree <worktree> -- npm run lint
 
-   # Standalone Story (no parent Epic): use --standalone, omit --epic-id.
    node <main-repo>/.agents/scripts/evidence-gate.js \
      --standalone --scope-id <storyId> --gate typecheck \
      --worktree <worktree> -- <resolved typecheck command>

package/.agents/agents/story-worker.md

@@ -3,8 +3,8 @@ name: story-worker
 description: >-
   Role-scoped boot context for a single Story delivery child, booted on its own
   system prompt (no CLAUDE.md / instructions.md closure). Carries the
-  load-bearing delivery MUSTs standalone. INERT under M7-A — no workflow
-  references this agent type yet (that is M7-B).
+  load-bearing delivery MUSTs standalone. Dispatched by helpers/deliver-story
+  when delivery.routing.roleScopedAgents is enabled (the default).
 ---
 
 # story-worker — Story delivery boot context
@@ -44,10 +44,10 @@ You run as a sub-agent with **no input channel** mid-run.
    the **main checkout** (the worktree does not exist yet). Invoke it
    **synchronously** with the Bash maximum timeout — a per-worktree install can
    take several minutes; do not background it.
-2. Capture `workCwd`, `dependenciesInstalled`, and `context.parentId` from the
-   init envelope. When worktree isolation is on, `cd` into the printed
-   **absolute** `workCwd` before doing any implementation work. The main
-   checkout's HEAD is never moved by you.
+2. Capture `workCwd` and `dependenciesInstalled` from the init envelope (it
+   is flat — there is no `context` block). When worktree isolation is on, `cd`
+   into the printed **absolute** `workCwd` before doing any implementation
+   work. The main checkout's HEAD is never moved by you.
 3. Every subsequent command runs against that worktree path. Because cwd may
    reset between calls, prefer absolute paths anchored at `workCwd`.
 
@@ -60,8 +60,7 @@ git -C "<workCwd>" branch --show-current   # MUST print story-<storyId>
 ```
 
 If it does **not** report `story-<storyId>`, **STOP** — do not commit. Never
-commit Story work to `main`, to an Epic branch directly, or outside the
-worktree/branch. Re-run `single-story-init.js` (it is idempotent on partial state) to
+commit Story work to `main` or outside the worktree/branch. Re-run `single-story-init.js` (it is idempotent on partial state) to
 restore the branch before proceeding.
 
 ## Commit discipline
@@ -79,7 +78,7 @@ Author commits directly on `story-<storyId>` following the always-on git core
 ## Docs context — digest first
 
 Do **not** re-read every file in `project.docsContextFiles`. Your caller passes
-a `docsDigestPath` (the per-Epic docs digest — a compact per-file outline:
+a `docsDigestPath` (the per-run docs digest — a compact per-file outline:
 path, size, heading outline with line numbers, first paragraph under each
 `##`). Read that digest, decide which docs bear on this Story, then **pull the
 full file on demand** (jump to the section at the line number the digest names)
@@ -89,9 +88,9 @@ mandate — read a full doc only if the Story's own context points you at one.
 
 ## Close gates — do not pre-run
 
-`story-close.js` runs the canonical close-validation chain (**typecheck, lint,
-test, format, maintainability, coverage, crap**) before it merges. Do **not**
-pre-run those gates as a matter of course — running `npm run typecheck &&
+`single-story-close.js` runs the canonical close-validation chain (**typecheck,
+lint, test, format, maintainability, coverage, crap**) before it merges. Do
+**not** pre-run those gates as a matter of course — running `npm run typecheck &&
 npm run lint && npm test` as advisory pre-flight while iterating on a fix is
 fine, but the close pipeline is the authoritative gate. The bounded acceptance
 self-eval loop (below) may share `lint` / `typecheck` evidence with close via
@@ -110,21 +109,16 @@ scores the working diff against **each** `acceptance[]` item and consumes the
 - **`block`** (round cap reached, criteria still unmet) → take the blocked path.
   Never silently proceed to close.
 
-## Lifecycle: heartbeat & blocked (MUST)
-
-- **Heartbeat.** Emit a `story.heartbeat` lifecycle event on every phase
-  transition (or when you stall on a long-running step) so the parent
-  `/deliver` idle watchdog can tell a live child from a dead one. In practice
-  this is the `story-run-progress` structured comment (via
-  `post-structured-comment.js` / the close pipeline) at each transition;
-  write it at every transition, and relay one terse line per transition
-  (e.g. `Story #<id>: implementing → closing`), not the full body.
-- **Blocked.** If you genuinely cannot proceed, flip the snapshot to `blocked`,
-  transition the Story to `agent::blocked`, post a `friction` comment naming
-  the decision needed (or the unmet criteria and their evidence), and **exit
-  non-zero**. **Never fall silent** — a child with no heartbeat, no commit, and
-  no `agent::blocked` label is exactly the dead-child failure the watchdog is
-  built to catch.
+## Lifecycle: progress & blocked (MUST)
+
+- **Progress.** Relay one terse line per phase transition (e.g.
+  `Story #<id>: implementing → closing`), not a full body. Your commits on
+  `story-<id>` and these lines are the progress surface.
+- **Blocked.** If you genuinely cannot proceed, transition the Story to
+  `agent::blocked`, post a `friction` comment naming the decision needed (or
+  the unmet criteria and their evidence), and **exit non-zero**.
+  **Never fall silent** — a child that stalls without an `agent::blocked`
+  label and no commit is indistinguishable from a dead one.
 - **Anti-thrashing.** If you hit the same error class twice with the same fix,
   or drift through reads without narrowing the problem, STOP: summarize what
   recurred and either re-plan or take the blocked path. Do not paper over a
@@ -136,26 +130,27 @@ The Story's init envelope carries `remoteVerified` + `remoteProbe`. When
 `remoteVerified` is `false`, transition the Story to `agent::blocked` quoting
 `remoteProbe.detail` and stop. Implementing the Story inline outside the
 worktree / branch / PR path — or committing it to local `main` — is expressly
-**forbidden**. The close pipeline's push (`story-close.js`) is the only
+**forbidden**. The close pipeline's push (`single-story-close.js`) is the only
 sanctioned way the work lands.
 
 ## Return schema
 
-Your authoritative status is the `story-run-progress` snapshot comment that
-the deliver/close pipeline upserts at each transition — the parent
-`/deliver` aggregator reads that, not your chat. On completion, return a
-compact JSON object naming the terminal state and evidence:
-
-```json
-{
-  "storyId": "<storyId>",
-  "state": "done | blocked",
-  "branch": "story-<storyId>",
-  "prUrl": "<url or null>",
-  "gates": { "acceptanceEval": "proceed | block", "close": "passed | n/a" },
-  "blockedReason": "<null, or the friction summary when state=blocked>"
-}
-```
-
-Exit zero only when the Story reached `agent::done` (merged/landed via the
-close pipeline). Exit non-zero on any blocked terminus.
+Your return contract is
+[`story-deliver-terminal.schema.json`](../schemas/story-deliver-terminal.schema.json)
+— the SSOT for every field (Story #4543). Fields are deliberately not
+restated here; that duplication is what drifted.
+
+`single-story-close.js` emits a validated envelope between its
+`--- STORY DELIVER TERMINAL ---` markers. **Relay it**; never hand-compose
+one. Its `status` is one of four; your exit code mirrors it:
+
+- `landed` → 0. Merged, `agent::done`, tail attempted (a `false` in `tail.*`
+  degrades the report, not the land).
+- `pending` → 3. **Resumable, not a failure** — the bounded merge wait
+  expired with the PR healthy, or a human owns the merge. Nothing was
+  mutated; `nextCommand` resumes it. The only sanctioned no-merge ending.
+- `blocked` / `failed` → exit non-zero. Take the blocked path above.
+
+Stranded? Probe, don't guess:
+`node .agents/scripts/deliver-recover.js --story <id>` (read-only, prints
+one next command).

package/.agents/audit-checklists/performance.md

@@ -6,7 +6,7 @@
 
 # Performance & Bottleneck Audit — authoring checklist
 
-> Audit hot paths, algorithmic complexity, and I/O bottlenecks in the tooling surface (`epic-close`, dispatcher, gates); propose remediations.
+> Audit hot paths, algorithmic complexity, and I/O bottlenecks in the tooling surface (`single-story-close`, dispatcher, gates); propose remediations.
 
 Self-check your change against this lens's concerns before you ship:
 

package/.agents/docs/SDLC.md

@@ -2,7 +2,7 @@
 
 Mandrel uses **Story-centric GitHub orchestration** — GitHub Issues,
 Labels, and Projects V2 are the Single Source of Truth. Plans persist as
-`type::story` tickets (optionally grouped by a `plan-run::<id>` label);
+`type::story` tickets ordered by `depends_on` edges;
 each Story is delivered on its own `story-<id>` branch and reaches `main`
 through its own PR.
 
@@ -49,19 +49,23 @@ From zero to shipped:
       probe, risk heuristics, `systemPrompts.story`). Duplicate review
       folds into **gate #1**.
    2. **Author** — write `stories.json` (**one Story by default**) with a
-      folded Tech Spec in `## Spec` / `## Slicing`, plus
-      `risk-verdict.json` (axes + summary only — no `deliveryShape`).
+      folded Tech Spec in `## Spec` / `## Slicing`. There is no risk artifact
+      to author (Story #4542).
       Binding criteria live in top-level `acceptance[]` / `verify[]`;
       changes/references are `{ path, assumption }` objects. Split into
       N>1 only under the default-single split policy.
-   3. **Persist** — **gate #2** (risk-routed; typically skipped for N=1
-      low-risk) then `plan-persist.js` runs every deterministic gate and
-      creates Story issue(s) with `type::story` + `agent::ready` (plus a
-      shared `plan-run::<id>` label when N>1).
+   3. **Persist** — **gate #2** (raised only by an explicit `--force-review`)
+      then `plan-persist.js` runs every deterministic gate and
+      creates Story issue(s) with `type::story` + `agent::ready`, writing
+      each authored `depends_on` edge into the sibling body as a
+      `blocked by #<id>` footer when N>1.
 
 2. **Deliver the Story.** Run [`/deliver <storyId>`](../workflows/deliver.md)
-   (or `/deliver <a> <b> …`, or `/deliver --run <planRunId>` for a
-   multi-Story plan-run) in your IDE. `/deliver` owns input resolution and
+   (or `/deliver <a> <b> …` for several) in your IDE. `/deliver` takes
+   only Story ids and resolves their dependency graph from live state —
+   body edges union native GitHub `blocked_by` edges, with every blocker
+   checked against its real issue state, so a Story whose blocker landed in
+   an earlier plan run is simply ready. `/deliver` owns input resolution and
    `depends_on` sequencing only — every Story runs through
    [`helpers/deliver-story`](../workflows/helpers/deliver-story.md), the
    single v2 delivery engine. Per-Story it:
@@ -72,11 +76,12 @@ From zero to shipped:
    2. **Implement** — the agent delivers the Story in one guarded session
       against its inline `acceptance[]` / `verify[]` contract (optional
       `## Slicing` intra-session checkpoints).
-   3. **Acceptance self-eval** — a bounded, risk-routed critic loop scores
-      the working diff against each acceptance item before close (see
+   3. **Acceptance self-eval** — a bounded critic loop scores the working
+      diff against each acceptance item before close (see
       [`helpers/acceptance-self-eval`](../workflows/helpers/acceptance-self-eval.md)).
-   4. **Ceremony** — risk-routed acceptance critics, review depth, and
-      audit lenses (`ceremony-routing.js`).
+   4. **Ceremony** — acceptance critic mode and review depth, both routed off
+      the change level derived from the Story's own diff
+      (`review-depth.js#deriveChangeLevel` → `ceremony-routing.js`).
    5. **Close** (`single-story-close.js`) — runs close-validation gates,
       the maker-blind Story-scope code review, pushes `story-<id>`, opens
       a PR to `main`, and (under the default `delivery.ci.autoMerge:
@@ -88,7 +93,7 @@ From zero to shipped:
       `MERGED` PR the Story flips to `agent::done`; local branch cleanup
       and Projects-v2 Status re-assert run out-of-band.
 
-   For a multi-Story plan-run, `/deliver` sequences ready Stories by
+   For a multi-Story run, `/deliver` sequences ready Stories by
    `depends_on` and runs the per-run epilogue (audit roster · follow-up
    roll-up · sibling coherence) once after the last Story lands.
 
@@ -105,8 +110,8 @@ rather than re-documenting the ceremony they own.
 - **Layered state stores with explicit precedence.** Ticket status lives
   in GitHub Issues and Labels; the lifecycle bus
   (`temp/run-<id>/lifecycle.ndjson`) is the canonical resume target for
-  in-flight runs; structured comments (`story-run-progress`,
-  `verification-results`, retro) are the operator-visible rollup. The
+  in-flight runs; structured comments (`verification-results`, retro) are
+  the operator-visible rollup. The
   stores, their owners, and their conflict-resolution rules are listed in
   [§ State stores](#state-stores) — that matrix is the single source of
   truth for "who owns which write."
@@ -149,9 +154,8 @@ on-disk layout resolved by
 | State Store | Owner (canonical writer) | Mutation API | Idempotency key | Conflict resolution |
 | --- | --- | --- | --- | --- |
 | GitHub labels | `transitionTicketState` via `ticketing.js` | `gh issue edit --add-label / --remove-label`, wrapped in `update-ticket-state.js` | `(ticketId, label-set)` — set-equality before write | Authoritative for current ticket lifecycle state; if a label disagrees with the lifecycle ledger, the **ledger wins on resume** and the label is re-derived. |
-| `story-run-progress` comment | `story-phase.js` (per Story, per phase transition) | `post-structured-comment.js` (upsert by `kind`) | `(storyId, kind='story-run-progress')` | Authoritative for Story-level phase progress. |
 | `verification-results` comment | `lib/orchestration/code-review.js` | `post-structured-comment.js` (upsert by `kind`) | `(storyId, kind='verification-results')` | Authoritative for the Story-scope review + lens findings; critical findings block close. |
-| Lifecycle ledger NDJSON | `lifecycle-emit.js` (single append-only writer per run) | Append-only line write to `temp/run-<id>/lifecycle.ndjson` | `(runId, eventId)` — `eventId` is a content hash of `{type, ts, payload}` | **Canonical resume target.** When labels / comments disagree with the ledger, the ledger wins and the others are re-derived. |
+| Lifecycle ledger NDJSON | `LedgerWriter` (`lib/orchestration/lifecycle/ledger-writer.js`, registered as the first listener on every bus event — single append-only writer per run) | Append-only line write to `temp/run-<id>/lifecycle.ndjson` | `(runId, eventId)` — `eventId` is a content hash of `{type, ts, payload}` | **Canonical resume target.** When labels / comments disagree with the ledger, the ledger wins and the others are re-derived. |
 | Validation evidence cache | `evidence-gate.js` | JSON cache file under the run temp tree, keyed by HEAD SHA | `(gate, git rev-parse HEAD)` | Pure cache: a missing entry triggers a re-run; presence is a fast-path skip. Cache eviction is safe. |
 | PR / auto-merge state | `single-story-close.js` (sole authorized caller of `gh pr merge`) | `gh pr merge --auto --squash --delete-branch`; PR open via the close pipeline's `gh pr create` | `(prNumber, head-branch SHA)` — `gh pr list --head` probes before create | GitHub is authoritative for PR + auto-merge arming state; the ledger records the *intent* to arm, GitHub records the outcome. |
 | Worktree cleanup state | `WorktreeManager.reap` (via `single-story-close.js` / `git-cleanup.js`) | `git worktree remove` + on-disk pending-cleanup JSON under the run temp tree | `(storyId, worktree-path)` | Filesystem is authoritative for "is the worktree gone?"; the pending-cleanup JSON only tracks stale-registry entries needing a follow-up sweep. |
@@ -180,12 +184,12 @@ graph LR
         A["👤 /plan --seed | --seed-file | --tickets"]:::manual
         B["🤖 interrogate → author → persist"]:::agentic
         A --> B
-        B -.-> B_Art["📄 type::story issue(s)<br/>(+ optional plan-run::&lt;id&gt;)"]:::artifact
+        B -.-> B_Art["📄 type::story issue(s)<br/>(+ depends_on edges)"]:::artifact
     end
 
     subgraph Phase2 ["Phase 2: Deliver"]
         direction TB
-        E["👤 /deliver &lt;storyId&gt;<br/>(or --run &lt;planRunId&gt;)"]:::manual
+        E["👤 /deliver &lt;storyId&gt; [&lt;storyId&gt;…]"]:::manual
         F["🤖 deliver-story: story-&lt;id&gt; from main<br/>implement → self-eval → ceremony → close"]:::agentic
         G["🤖 close-validation → code-review → open PR"]:::agentic
         E --> F --> G
@@ -267,7 +271,7 @@ the SDLC depends on:
 - **One Story by default.** `/plan` authors a single `type::story` issue
   whose body carries a folded `## Spec` (inline only — never spilled to
   `docs/`) plus top-level `acceptance[]` / `verify[]`. It splits into N>1
-  siblings (sharing a `plan-run::<id>` label + `depends_on` edges) **only**
+  siblings (ordered by `depends_on` edges) **only**
   under the default-single split policy: near-zero overlap or a genuine
   architectural seam. Coupled work stays one Story and is decomposed inside
   `## Slicing` as intra-session checkpoints, not sibling tickets.
@@ -278,8 +282,7 @@ the SDLC depends on:
   `assertAcceptancePartition` so every acceptance criterion belongs to
   exactly one Story.
 - **Handoff.** Persist creates the Story issue(s) at `agent::ready` and
-  names the delivery command: `/deliver <storyId>` (or `/deliver --run
-  <planRunId>`).
+  names the delivery command: `/deliver <storyId> [<storyId> ...]`.
 
 Optional split advisory notes come from
 [`core/scope-triage`](../skills/core/scope-triage/SKILL.md); there is no
@@ -308,8 +311,7 @@ self-eval, ceremony, close, CI watch, confirm-merge, cleanup) lives in the
 | Mode | Entry point | When to use |
 | --- | --- | --- |
 | **Single Story** | `/deliver <storyId>` | Deliver one Story end-to-end; ends with a PR open to `main`. |
-| **Story set** | `/deliver <storyId> [<storyId>…]` | Deliver multiple Stories in `depends_on` order (default concurrency **3**); each lands through its own PR. |
-| **Plan-run** | `/deliver --run <planRunId>` | Resolve Stories labeled `plan-run::<id>`, sequence them, and run the per-run epilogue after the set lands. |
+| **Story set** | `/deliver <storyId> [<storyId>…]` | Deliver multiple Stories in `depends_on` order (default concurrency **3**), resolved from live state so edges may point at Stories from earlier plan runs; each lands through its own PR, and the per-run epilogue runs after the set lands. |
 | **Story worker (internal)** | *helper* `helpers/deliver-story <storyId>` | Per-Story engine invoked internally by `/deliver`; not an operator slash command. |
 
 The single operator-facing entry point is `/deliver`. It performs no
@@ -374,14 +376,14 @@ Concurrent runs are serialised by **two distinct layers**:
   assignee; `--steal` is the only override. See
   [`README.md` § Multi-developer coordination](../README.md#multi-developer-coordination).
 
-### Concurrent close — push retry
+### Concurrent close
 
 `single-story-close.js` syncs the Story branch from `origin/main` before
-pushing and opening/locating the PR. Bounded retry constants live in
-`.agents/scripts/lib/config/runners.js` (`DEFAULT_STORY_MERGE_RETRY`:
-3 attempts, `[250, 500, 1000]` ms backoff). A real content conflict aborts
-the loop with a clear error, leaves the tree clean, and exits non-zero for
-manual resolution.
+pushing and opening/locating the PR, so concurrent closes serialize through
+their own worktrees rather than racing one shared branch. The push does not
+retry: a rejected push, or a real content conflict at base-sync, aborts with
+a clear error, leaves the tree clean, and exits non-zero for manual
+resolution.
 
 ---
 
@@ -486,14 +488,18 @@ pass — the tiers below *are* the audit machinery.
 | --- | --- | --- | --- |
 | Tier 1 — write-time | During Story implementation | Footprint-matched **local**-lens authoring checklists threaded into the Story prompt (`checklistPath`) | advisory |
 | Tier 2 — Story-scope | `single-story-close.js` (maker-blind subprocess) | Local-tier lens roster over the Story diff (`selectLocalLenses`) + review pillars, posted as `verification-results` | blocking on 🔴 |
-| Tier 3 — run closeout | `/deliver` per-run epilogue (`plan-run-epilogue.js`, N>1 only) | Cumulative + global + risk-routed lenses (`selectAudits` / `resolveAuditLenses`) over the combined landed tip | blocking |
+| Tier 3 — run closeout | `/deliver` per-run epilogue (`plan-run-epilogue.js`, N>1 only) | Cumulative + global lenses (`selectAudits`) over the combined landed tip | blocking |
 
 - **`local`** lenses (decidable from a single Story's diff) are verified at
   Tiers 1–2 and are **not** re-run at run closeout.
-- **`cumulative`** lenses (only decidable across a plan-run's combined diff)
+- **`cumulative`** lenses (only decidable across a run's combined diff)
   and **`global`** lenses (whole-product properties) are verified at Tier 3.
-- **Risk-routed** lenses run regardless of tier when a high-risk axis (or a
-  route-adding change set) demands them.
+
+There is no risk-routed lens tier. Story #4542 deleted the risk→lens router:
+it had zero callers while this document claimed it ran inside close. Lens
+selection is change-set-matched (`selectAudits` / `selectLocalLenses`); the
+`sensitivePaths` classes in `audit-rules.json` route review **depth**, not
+lenses.
 
 The run-closeout roster is deliberately **slim**: it excludes every
 local-tier change-set lens so the outermost tier — where a fix is most
@@ -504,8 +510,8 @@ expensive — does not re-verify a concern already covered shift-left.
 The Story-scope code review runs **outside the maker's context**, inside
 the `single-story-close.js` close subprocess, over `main...story-<id>`
 (see [`helpers/code-review.md`](../workflows/helpers/code-review.md)). It
-walks the Story diff once, executing the risk-routed lens roster as review
-dimensions alongside the review pillars, and posts the unified
+walks the Story diff once, executing the change-set-matched local lens roster
+as review dimensions alongside the review pillars, and posts the unified
 `verification-results` comment. Remediation is tier-aware and split by
 finding class off `delivery.codeReview.autoFixSeverity` (default `medium`);
 surviving 🔴 Critical findings halt the run. The legacy `scope: epic`
@@ -513,12 +519,14 @@ Epic-branch review path was removed with the v2 cutover.
 
 ### Quality ratchets
 
-- **Maintainability ratchet** (`check-maintainability.js`) — fails if the
+- **Maintainability ratchet** (`check-baselines.js` via
+  `lib/baselines/kinds/maintainability.js`) — fails if the
   composite score drops below the established baseline.
-- **CRAP gate** (`check-crap.js`) — per-method complexity × coverage risk
+- **CRAP gate** (`check-baselines.js` via `lib/baselines/kinds/crap.js`) —
+  per-method complexity × coverage risk
   against `baselines/crap.json`, wired into close-validation, `ci.yml`, and
-  `.husky/pre-push`. The `baseline-refresh:`-tagged commit convention is the
-  project standard for baseline edits (see
+  `.husky/pre-push`. The `baseline-refresh: true` commit-trailer convention
+  is the project standard for baseline edits (see
   [`core/gates-and-baselines`](../skills/core/gates-and-baselines/SKILL.md)).
 
 ### Audits → Stories
@@ -552,7 +560,7 @@ Severity vocabulary (`eventSeverity()` derives it for state transitions):
 
 | Severity | Used for | Webhook prefix |
 | --- | --- | --- |
-| `low` | `story-run-progress` upserts, intermediate transitions, audit reports. | `[low]` |
+| `low` | Intermediate transitions, audit reports. | `[low]` |
 | `medium` | Operator-visible milestones: Story state transitions, story merged, run complete. | `[medium]` |
 | `high` | Operator must act (HITL gates, Story blockers, autonomous-chain failures); body leads with `🚨 Action Required:`. | `[Action Required]` |
 
@@ -650,8 +658,7 @@ the ticket or re-plan the work as a v2 Story via `/plan --tickets <id>`.
 | `/plan --seed-file <path>` | Plan from on-disk notes / a plan seed (the `/audit-to-stories` handoff). |
 | `/plan --tickets <ids>` | Analyze existing issue(s) into proper Stories (prefer an N=1 rewrite). |
 | `/deliver <storyId>` | Deliver one Story via `helpers/deliver-story` — `story-<id>` → PR → `main`. |
-| `/deliver <storyId> [<storyId>…]` | Deliver multiple Stories in `depends_on` order; each lands through its own PR. |
-| `/deliver --run <planRunId>` | Resolve Stories labeled `plan-run::<id>`, sequence them, and run the per-run epilogue. |
+| `/deliver <storyId> [<storyId>…]` | Deliver multiple Stories in `depends_on` order (resolved from live state), then run the per-run epilogue. |
 | *helper* `helpers/deliver-story` | Per-Story engine invoked by `/deliver`; not an operator slash command. See [`deliver-story.md`](../workflows/helpers/deliver-story.md). |
 | `/audit-to-stories` | Convert audit findings into a plan seed / Stories → `/plan --seed-file`. |
 | `/qa-explore` · `/qa-assist` · `/qa-run` | Agent-led / human-led exploratory QA and the automated Gherkin harness. |