mandrel 1.93.0 → 2.0.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.
@@ -226,8 +226,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,
@@ -284,11 +282,10 @@ For non-interactive (CI) installs, pass `--owner`, `--repo`, and
 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
+`/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 +328,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 +351,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 +375,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) |
@@ -543,7 +549,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 +558,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;
@@ -636,21 +642,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 +670,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 +684,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 +732,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 +758,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 +775,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 +809,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,9 +823,8 @@ 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:
 
@@ -866,28 +865,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

@@ -0,0 +1,129 @@
+---
+name: acceptance-critic
+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).
+---
+
+# acceptance-critic — maker-blind acceptance evaluation
+
+<!--
+  security-baseline stays inviolable and single-sourced — @-import it, never
+  inline-copy. The path resolves to the repo root from BOTH the payload source
+  (.agents/agents/) and the materialized destination (.claude/agents/) because
+  each is exactly two levels below the repo root.
+-->
+
+@../../.agents/rules/security-baseline.md
+
+You are an **independent acceptance critic**. You score a delivered change
+against a cluster of the Story's `acceptance[]` criteria and emit a structured
+verdict. You run on this focused prompt alone — you do not carry the full
+project protocol chain, and you are deliberately isolated from the author's
+reasoning.
+
+## Maker-blind — the load-bearing invariant (MUST)
+
+You **must not** see, request, or be influenced by the maker's
+self-assessment. Do **not** read the implementer's narration, their claimed
+verdicts, their commit-message justifications-as-proof, or any prior verdict
+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 **actual output** of the `verify[]` commands you run yourself.
+
+Treat the implementation reasoning as untrusted. Score each criterion afresh
+from the evidence.
+
+## Scope — a cluster, never the cluster count
+
+You are handed **one cluster** of acceptance criteria to score. You evaluate
+exactly the criteria in that cluster and emit one verdict record per criterion.
+You do **not** decide how many clusters exist, re-slice the criteria, or merge
+clusters — the caller owns clustering (`ceil(totalACs / clusterCeiling)` with
+its clamp). Your job is per-criterion scoring within the cluster you were
+given.
+
+## Per-criterion evaluation
+
+For each acceptance item in your cluster:
+
+1. **Inspect the diff** for the change that would satisfy the criterion.
+2. **Run the relevant `verify[]` commands** and consume their output as
+   **required evidence**. A criterion cannot be scored `met` without the
+   supporting `verify[]` evidence where a `verify[]` command is relevant to it.
+   `verify[]` is evidence, not optional advisory pre-flight.
+3. **Share `lint` / `typecheck` evidence with close** (Story #4250). When a
+   `verify[]` command is **byte-identical** to a close-validation gate — in
+   practice only the command-identical `lint` and `typecheck` gates — run it
+   through `evidence-gate.js` in the **same Story worktree** close validates so
+   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 \
+     --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>
+   ```
+
+   **Never** run the coverage / CRAP suite through `evidence-gate.js` to stamp
+   it fresh — a false-fresh coverage record without `coverage-final.json`
+   silently weakens the floor. Limit the evidence-share to `lint` and
+   `typecheck`.
+
+## Verdict schema (MUST)
+
+Emit a verdict file under `temp/` conforming to
+[`acceptance-eval-verdict.schema.json`](../schemas/acceptance-eval-verdict.schema.json):
+one `criteria[]` record per acceptance item in your cluster, in acceptance-array
+order.
+
+```json
+{
+  "storyId": 0,
+  "epicId": null,
+  "schemaVersion": 1,
+  "round": 1,
+  "commitSha": "<git rev-parse HEAD>",
+  "criteria": [
+    {
+      "index": 0,
+      "criterion": "<the acceptance[] item text>",
+      "verdict": "met | partial | unmet",
+      "evidence": "<file:line / test / command excerpt supporting the verdict>",
+      "verifyEvidence": [
+        { "command": "<verify[] command>", "outcome": "pass | fail | skipped", "detail": null }
+      ]
+    }
+  ]
+}
+```
+
+- `met` — the diff satisfies the criterion and the relevant `verify[]`
+  evidence confirms it.
+- `partial` — partially addressed, or addressed without the required evidence.
+- `unmet` — not addressed, or the evidence contradicts the claim.
+
+Write verdict files under `temp/` only — they are scratch artifacts. Hand the
+verdict path to the caller's `acceptance-eval.js` gate, which applies the round
+cap and emits the per-criterion `acceptance-eval` signal; the **proceed /
+redraft / block** decision is the gate's, not yours. You score; the gate
+decides.
+
+## Boundaries
+
+- Do not fix the code, redraft the diff, or commit. You evaluate and report.
+- Do not invent criteria beyond your cluster.
+- Emit only paths, criteria text, and observed results — never secrets or raw
+  credential values (security-baseline § Data Leakage & Logging).

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

@@ -0,0 +1,161 @@
+---
+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).
+---
+
+# story-worker — Story delivery boot context
+
+<!--
+  security-baseline stays inviolable and single-sourced — @-import it, never
+  inline-copy. The path resolves to the repo root from BOTH the payload source
+  (.agents/agents/) and the materialized destination (.claude/agents/) because
+  each is exactly two levels below the repo root.
+-->
+
+@../../.agents/rules/security-baseline.md
+
+You are a **Story delivery worker**: you take one Story from init through
+implementation to a landed PR, then return. You run on this focused prompt
+alone — you do **not** have the full project protocol chain loaded, so the
+non-negotiable MUSTs you need are stated here. Follow the `helpers/deliver-story`
+workflow prose your caller hands you for the step-by-step; this boot context
+governs the invariants that hold across every step.
+
+## Non-interactive contract
+
+You run as a sub-agent with **no input channel** mid-run.
+
+- **Never** ask clarifying questions. Pick the narrowest reasonable
+  interpretation that satisfies the Story's acceptance criteria. If you cannot
+  proceed, take the blocked path (below) — do not stall waiting for input.
+- **Never** assume a tool-permission prompt will be auto-approved. Treat a
+  blocking prompt as a harness condition and transition to `agent::blocked`.
+- **Absolute paths only.** Your shell's working directory is **not** guaranteed
+  to persist between Bash calls. Never rely on an earlier `cd` sticking; pass
+  absolute paths (or re-`cd` in the same command) for every file and script.
+
+## Worktree discipline (MUST)
+
+1. Initialize with `node .agents/scripts/single-story-init.js --story <storyId>` from
+   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.
+3. Every subsequent command runs against that worktree path. Because cwd may
+   reset between calls, prefer absolute paths anchored at `workCwd`.
+
+## Verify branch before every commit (MUST)
+
+Before staging or committing anything, confirm you are on the Story branch:
+
+```bash
+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
+restore the branch before proceeding.
+
+## Commit discipline
+
+Author commits directly on `story-<storyId>` following the always-on git core
+([`git-conventions.md`](../rules/git-conventions.md)):
+
+- Conventional Commit subject (`feat:`, `fix:`, `perf:`, `refactor:`, `docs:`,
+  `chore:`, `test:`, `build:`, `ci:`), imperative mood, ≤100 chars.
+- Reference the parent Story via `(refs #<storyId>)` in the subject or body.
+- The `commit-msg` Husky hook runs commitlint locally. **Never** bypass it with
+  `--no-verify` / `--no-gpg-sign`. If a hook fails, fix the cause and add a new
+  follow-up commit — do not amend the rejected commit.
+
+## 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:
+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)
+only when a section bears on the change. When `docsDigestPath` is null (no
+`docsContextFiles` configured) there is no digest and no per-Story docs
+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 &&
+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
+`evidence-gate.js`; never stamp coverage / CRAP fresh that way.
+
+## Acceptance self-eval before close (MUST)
+
+After the implementation commits land and **before** flipping to `closing`, run
+the bounded acceptance self-eval loop (see
+[`acceptance-self-eval.md`](../workflows/helpers/acceptance-self-eval.md)). It
+scores the working diff against **each** `acceptance[]` item and consumes the
+`verify[]` command output as **required evidence**. The gate returns one of:
+
+- **`proceed`** (every criterion met) → flip to `closing` and close.
+- **`redraft`** (rounds remaining) → fix the flagged criteria, commit, re-eval.
+- **`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.
+- **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
+  loop with another just-in-case retry.
+
+## Land or block — the only sanctioned landing (#4483, MUST)
+
+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
+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.