mandrel 1.94.0 → 2.1.0

package/.agents/README.md

@@ -1,13 +1,13 @@
 # Mandrel Framework
 
 An opinionated workflow framework for AI coding assistants built on
-Epic-centric GitHub orchestration. Planning, execution, and state all live natively in GitHub Issues, Labels, and Projects V2.
+Story-centric GitHub orchestration. Planning, execution, and state all live natively in GitHub Issues, Labels, and Projects V2.
 
 This is the consumer README inside the distributed `.agents/` bundle. It explains what each part of the bundle is for and captures the cross-directory authoring conventions. The process narrative for
 `/plan` and `/deliver` stays in [`docs/SDLC.md`](docs/SDLC.md).
 
 The framework payload (`.agents/`) is consumed by host repos. It ships inside the [`mandrel`](https://www.npmjs.com/package/mandrel)
-npm package and is materialized into a consumer's `./.agents/` directory by `mandrel sync`. It carries a system prompt, a baseline rule pack, a two-tier skill library, a slash-command workflow set, and the orchestration engine that runs Epic → Story plans on GitHub.
+npm package and is materialized into a consumer's `./.agents/` directory by `mandrel sync`. It carries a system prompt, a baseline rule pack, a two-tier skill library, a slash-command workflow set, and the orchestration engine that runs Story-centric plans on GitHub (`/plan` → Stories, `/deliver` → `story-*` → `main`).
 
 The framework version is the version of the installed [`mandrel`](https://www.npmjs.com/package/mandrel) npm package — run `npm ls mandrel` (or read `package.json`), not a
 count here.
@@ -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
@@ -226,8 +241,6 @@ read-when-relevant pattern skills use).
 **Always-load (the recommended core):**
 
 - [`instructions.md`](instructions.md) — the core agent protocol.
-- [`personas/engineer.md`](personas/engineer.md) — the default persona (swap in
-  another persona when the task calls for it).
 - [`rules/security-baseline.md`](rules/security-baseline.md) — inviolable
   security MUSTs, relevant to every change.
 - [`rules/git-conventions.md`](rules/git-conventions.md) — every commit,
@@ -249,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`.
 
@@ -282,13 +302,12 @@ 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`, `/plan`, `/deliver`, `/audit-security`. The
-commands load in every Claude Code environment. The [SDLC guide](docs/SDLC.md) walks
-an end-to-end Epic; standalone Stories pair
-[`/plan`](workflows/helpers/plan-story.md) (idea → drafted Story
-Issue) with [`/deliver`](workflows/helpers/deliver-stories.md) (Story Issue → merged
+`.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).
 
 ---
@@ -331,9 +350,18 @@ in `runtime-deps.json`.
 
 ## Ticket Hierarchy
 
-Mandrel uses a **2-tier hierarchy** (Epic → Story) with inline `acceptance[]` / `verify[]` on story bodies.
+Orchestration and planning are **Story-only** (`type::story`): `/plan`
+persists Stories with inline `acceptance[]` / `verify[]` and a folded
+`## Spec`; `/deliver` runs `helpers/deliver-story` on
+`story-<id>` → PR → `main`. There is no `type::epic` / `type::task`
+label and no Epic issue form — an Epic is at most an optional untyped
+human umbrella issue outside orchestration. There is no Epic wave /
+`epic/<id>` integration branch. Tickets that still carry an `Epic: #N`
+footer are refused by `/deliver` and must be closed or re-planned as
+v2 Stories.
 
-See [`docs/SDLC.md` § Ticket hierarchy](docs/SDLC.md) for the diagram and execution-model implications.
+See [`docs/SDLC.md`](docs/SDLC.md) and [`instructions.md` § 5.D](instructions.md)
+for the execution-model contract.
 
 ---
 
@@ -345,7 +373,7 @@ See [`docs/SDLC.md` § Ticket hierarchy](docs/SDLC.md) for the diagram and execu
 | [`docs/SDLC.md`](docs/SDLC.md) | Operator process for `/plan` and `/deliver`. |
 | [`starter-agentrc.json`](starter-agentrc.json) | Bootstrap delta-seed copied to the consumer repo root as `.agentrc.json`. |
 | [`agentrc-reference.json`](docs/agentrc-reference.json) | Exhaustive editor reference enumerating every schema key with its framework default. |
-| [`personas/`](personas/) | Role-specific behavior packs selected by task persona or explicit user instruction. |
+| [`agents/`](agents/) | Optional role-scoped spawn boot contexts (`delivery.routing.roleScopedAgents`). |
 | [`rules/`](rules/) | Domain-agnostic coding, security, testing, shell, git, and workflow rules. |
 | [`skills/core/`](skills/core/) | Universal process skills such as debugging, TDD, security, documentation, and code review. |
 | [`skills/stack/`](skills/stack/) | Stack-specific guardrails for frameworks, services, and testing tools. |
@@ -369,7 +397,7 @@ See [`docs/SDLC.md` § Ticket hierarchy](docs/SDLC.md) for the diagram and execu
 | Quality-gate runbooks (CRAP, MI, lint, friction) plus the baseline envelope, component model, and writer/reader contract | [`.agents/docs/quality-gates.md`](docs/quality-gates.md) |
 | Slash-command workflow definitions | [`workflows/`](workflows/) |
 | Render the signals span-tree (debug helper) | [`workflows/helpers/signals.md`](workflows/helpers/signals.md) |
-| Persona behavior packs | [`personas/`](personas/) |
+| Role-scoped spawn boot contexts | [`agents/`](agents/) |
 | Domain-agnostic baseline rules | [`rules/`](rules/) |
 | Skill library (core process + stack guardrails) | [`skills/core/`](skills/core/) · [`skills/stack/`](skills/stack/) |
 | Decision rule: should this be a Skill or a Script? | [§ When to use a Skill vs a Script](#when-to-use-a-skill-vs-a-script) |
@@ -402,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
@@ -418,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
@@ -518,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
 
@@ -543,7 +572,7 @@ sessions, `gh auth login` is sufficient.
 ## Self-Healing Checks
 
 `scripts/lib/checks/` is the discovery-based registry of named checks
-consumed by preflight guards (`/deliver`, `/story-close`, `npm test`),
+consumed by preflight guards (`/deliver`, `single-story-close`, `npm test`),
 the `diagnose.js` ad-hoc viewer, and the retro surface. Use one check per
 file. The runner (`index.js`) loads checks at process start and filters by
 scope at each call site.
@@ -552,9 +581,9 @@ Each check module default-exports an object with this shape:
 
 ```js
 export default {
-  id: 'stale-origin-epic',
+  id: 'stale-origin-main',
   severity: 'blocker', // 'blocker' | 'warning' | 'info'
-  scope: ['epic-deliver', 'story-close', 'retro'],
+  scope: ['deliver', 'single-story-close', 'retro'],
   autoCorrect: 'refuse-and-print', // 'auto' | 'refuse-and-print'
   detect(state) {
     return null;
@@ -572,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`.
@@ -636,21 +665,19 @@ follow-up **Epic #1943**.
 
 `schemas/` contains JSON Schema draft 2020-12 contracts consumed by the
 orchestration layer. Each schema describes one structured artefact:
-configuration, structural Epic specs, runtime reports, dispatch
-manifests, or persisted state. Where a runtime AJV schema also exists,
-the JSON file is a mirror kept in sync by a drift test.
+configuration, runtime reports, dispatch manifests, or persisted state.
+Where a runtime AJV schema also exists, the JSON file is a mirror kept
+in sync by a drift test.
 
 Important schema groups:
 
-- Structural specs: `epic-spec.schema.json` for the declarative
-  `epic.yaml` plus reconciler flow.
 - Configuration: `agentrc.schema.json`, mirrored from the runtime config
   schemas.
+- Story / signal contracts: `signal-event.schema.json`, acceptance-eval
+  verdicts, and related runtime envelopes.
 - Runtime reports: audit results, CRAP and maintainability reports,
   performance summaries, friction and signal events, and validation
   evidence.
-- Dispatch: `dispatch-manifest.json`, the per-Epic dispatch manifest
-  schema written by `dispatcher.js`.
 
 Schema conventions:
 
@@ -666,18 +693,13 @@ Schema conventions:
 
 ## Code review providers (pluggable chain)
 
-`runCodeReview()` (invoked at the end of `helpers/epic-deliver-story`,
-`helpers/single-story-deliver`, and `/deliver`'s `delivery.code-review`
-state) loads its review backend through a pluggable registry. Two configuration shapes are supported:
-
-- **Legacy single provider** — `delivery.codeReview.provider: "native"`
-  (default), `"codex"`, or `"security-review"`. Returns one adapter; one
-  set of findings; one structured comment.
-- **Provider chain** (Story #2871) — `delivery.codeReview.providers: []`
-  iterates a declared list of entries, merges every inline adapter's
-  `Finding[]` in declaration order, and appends a non-blocking
-  "Manual Review Suggestions" section for any manual-prompt entries
-  that contributed text. When both fields are set, `providers` wins.
+`runCodeReview()` (invoked from `helpers/deliver-story` and `/deliver`'s
+risk-routed ceremony) loads its review backend through a pluggable registry.
+Configure a provider chain via `delivery.codeReview.providers` — an array
+of entries iterated in declaration order. Inline adapters merge their
+`Finding[]`; manual-prompt entries append a non-blocking
+"Manual Review Suggestions" section. When `providers` is unset or empty,
+the factory defaults to `[{ name: "native" }]`.
 
 ```json
 {
@@ -685,10 +707,10 @@ state) loads its review backend through a pluggable registry. Two configuration
     "codeReview": {
       "providers": [
         { "name": "native" },
-        { "name": "security-review", "scopes": ["epic"], "optional": true },
+        { "name": "security-review", "scopes": ["story"], "optional": true },
         {
           "name": "ultrareview",
-          "scopes": ["epic"],
+          "scopes": ["story"],
           "manualPrompt": true,
           "when": { "label": "risk::high" }
         }
@@ -733,9 +755,9 @@ chain, `security-review`, and `ultrareview` were added in Story #2871.
 
 ## Feedback loop — verification-results auto-graduation
 
-When the Epic finalize listener runs, non-blocking findings (severity
-`high`, `medium`, or `suggestion`) that survived merge are auto-graduated
-into follow-up issues in a SINGLE pass over the unified
+When a Story (or plan-run) finalize path runs, non-blocking findings
+(severity `high`, `medium`, or `suggestion`) that survived merge are
+auto-graduated into follow-up issues in a SINGLE pass over the unified
 `verification-results` structured comment (Story #4411 folded the former
 `code-review` and `audit-results` comments into one), routed by source
 classification into the framework repo or the consumer repo. The toggle
@@ -759,7 +781,7 @@ stabilization window), set the toggle to `false` in your root
 ```
 
 When disabled, the listener short-circuits and leaves the
-`verification-results` comment on the Epic ticket untouched. Re-enabling
+`verification-results` comment on the Story ticket untouched. Re-enabling
 the toggle is safe: the graduator embeds a content-derived idempotency
 marker in each filed issue body, so re-runs skip findings that already
 have an issue.
@@ -776,15 +798,16 @@ each with different cost/portability trade-offs:
 
 | Strategy       | When to use                                                      | Cold-start cost          | Notes                                                                                                       |
 | -------------- | ---------------------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------- |
-| `per-worktree` | Default-safe — no host setup, no symlink semantics to worry about. | Full `npm ci` per Story. | Slowest. Each worktree gets an independent `node_modules`.                                                  |
+| `clone`        | **Shipped default on darwin/linux** — copy-on-write clone of donor `node_modules`. | Near-zero on APFS/reflink FS. | Falls back to `per-worktree` on unsupported filesystems or cross-volume clones. |
+| `per-worktree` | Default on Windows; also the safe fallback everywhere.           | Full `npm ci` per Story. | Each worktree gets an independent `node_modules`.                                                           |
 | `symlink`      | npm/yarn repos that want the fast path. **Opt-in.**              | Near-zero.               | Junctions a single donor `node_modules` into each worktree. Refuses on Windows unless explicitly opted in.  |
-| `pnpm-store`   | pnpm repos. **Shipped consumer default in `agentrc-reference.json`.** | Fast (store-backed).     | Runs `pnpm install --frozen-lockfile` against the shared content-addressable store.                         |
+| `pnpm-store`   | pnpm repos. **Opt-in.**                                          | Fast (store-backed).     | Runs `pnpm install --frozen-lockfile` against the shared content-addressable store.                         |
 
 The **shipped consumer default in
-[`.agents/docs/agentrc-reference.json`](./docs/agentrc-reference.json) remains
-`pnpm-store`**. Repos that do not use pnpm should opt in to `symlink`
-explicitly in their root `.agentrc.json`; this repo dogfoods that
-configuration.
+[`.agents/docs/agentrc-reference.json`](./docs/agentrc-reference.json) is
+`clone`** (Windows resolves to `per-worktree` via the platform-aware
+accessor). Repos that use pnpm or want symlink semantics should set
+`nodeModulesStrategy` explicitly in their root `.agentrc.json`.
 
 ### Symlink opt-in (npm / yarn)
 
@@ -809,13 +832,13 @@ To opt in, set three fields on `delivery.worktreeIsolation` in your root
 - **`primeFromPath`** — relative path (from the repo root) to the donor
   worktree whose `node_modules/` is reused. `"."` means the root
   checkout, which must already have `node_modules/` populated before a
-  Story initializes. `story-init.js` enforces this with a pre-check.
+  Story initializes. `single-story-init.js` enforces this with a pre-check.
 - **`allowSymlinkOnWindows`** — required on Windows. The strategy uses
   junctions (no admin rights needed) on Windows when this is `true`; it
   refuses with an explanatory error otherwise, because symlink semantics
   vary by Windows version.
 
-Once these are set, `story-init.js` skips `npm ci` in the worktree and
+Once these are set, `single-story-init.js` skips `npm ci` in the worktree and
 junctions/symlinks `node_modules` from the donor — typical cold-start
 falls from minutes to under a second.
 
@@ -823,13 +846,12 @@ falls from minutes to under a second.
 
 ## Multi-developer coordination
 
-Two operators can drive the same repository at once — one running
-`/deliver <id>`, another running `/single-story-deliver <id>`, or two
-operators on the same Epic from separate clones. The framework keeps those
+Two operators can drive the same repository at once — for example, two
+`/deliver <storyId>` runs from separate clones. The framework keeps those
 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
@@ -845,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`:
@@ -856,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
@@ -866,28 +896,15 @@ yanks the claim back from whoever legitimately took over.
 
 **Where it's wired:**
 
-- **`/deliver`** acquires the lease on the **Epic** ticket during its
-  prepare phase, before any mutating git work
-  ([`epic-deliver-lease-guard.js`](scripts/lib/orchestration/epic-deliver-lease-guard.js)).
-  A live foreign claim refuses the run; pass `--steal` to override and
-  `--as <handle>` to claim under a specific identity. The operator is
-  resolved from `--as`, then `github.operatorHandle`, then
-  `git config user.email`; when none resolve, the lease step is skipped
-  (the checkout-safety guard still runs).
-- **`/single-story-deliver`** acquires the lease on the **Story** ticket at
-  init and releases it at close
+- **`/deliver`** runs each Story through `helpers/deliver-story`, which
+  acquires the lease on the **Story** ticket at init and releases it at close
   ([`single-story-lease-guard.js`](scripts/lib/orchestration/single-story-lease-guard.js)).
-  The standalone path requires `github.operatorHandle` to be set — without
-  an operator identity the lease has no owner to record.
-- **`/plan`** acquires the lease on the **Epic** ticket before Phase 7
-  (spec) and releases it after Phase 8 (decompose)
-  ([`epic-plan-lease-guard.js`](scripts/lib/orchestration/epic-plan-lease-guard.js)).
-  Because planning emits no `story.heartbeat` (heartbeats are a
-  delivery-time signal), the plan path has no live-heartbeat source and so
-  **fails closed**: any foreign assignee is treated as a live claim and
-  refuses the run unless `--steal` transfers it. Unassigned or self-held
-  Epics proceed. When `github.operatorHandle` is unset the lease cannot be
-  keyed and the preflight degrades to a no-op.
+  A live foreign claim refuses the run; pass `--steal` to override. The Story
+  path requires `github.operatorHandle` to be set — without an operator identity
+  the lease has no owner to record.
+- **`/plan`** does not take a planning lease on an Epic ticket. Planning is a
+  short authoring ceremony over Stories; concurrent `/plan` runs coordinate
+  via ordinary GitHub issue creation, not an Epic lease guard.
 
 ---
 

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>