mandrel 2.0.0 → 2.2.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
@@ -33,9 +34,20 @@ 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 **change set** your caller hands you: the list of files this Story
+  touched, computed **once** per delivery by the shared `computeChangeSet`
+  enumerator (`.agents/scripts/lib/orchestration/change-set.js`) and threaded
+  into your spawn context. Read those files and inspect their changes to see
+  the work product. Do **not** re-derive the set yourself — re-enumerating it
+  can pick up commits that landed after your caller routed the ceremony, and
+  then you would be scoring a different change than the one you were dispatched
+  for (Story #4593). If no change set reached you, say so in your verdict
+  rather than substituting your own enumeration.
+- 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
@@ -54,7 +66,8 @@ given.
 
 For each acceptance item in your cluster:
 
-1. **Inspect the diff** for the change that would satisfy the criterion.
+1. **Inspect the change set** — read the files your caller named and look 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.
@@ -66,12 +79,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
@@ -102,29 +101,26 @@ self-eval loop (below) may share `lint` / `typecheck` evidence with close via
 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:
+scores the change set you computed once and injected into the critic — never
+one the critic re-derives (Story #4593) — 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.
+## 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 +132,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: