mandrel 2.14.0 → 2.16.0

package/.agents/scripts/single-story-close.js

@@ -251,4 +251,28 @@ async function main() {
 runAsCli(import.meta.url, main, {
   source: 'single-story-close',
   propagateExitCode: true,
+  usage: {
+    invocation:
+      'node .agents/scripts/single-story-close.js --story <id> [--cwd <main-repo>] [options]',
+    summary:
+      'Run the whole delivery tail for one Story — close gates, base sync, push, PR to the base branch, merge wait, agent::done flip — and emit the terminal envelope.',
+    flags: [
+      ['--story <id>', 'GitHub issue number of the Story (required).'],
+      [
+        '--cwd <main-repo>',
+        'Main-repo checkout to run from (default: project root).',
+      ],
+      ['--skip-validation', 'Skip the close-validation gate chain.'],
+      ['--skip-sync', 'Skip the base-branch sync phase.'],
+      ['--no-auto-merge', 'Open the PR without arming native auto-merge.'],
+      ['--wait-merge', 'Force the in-close merge wait.'],
+      ['--no-wait-merge', 'Return as soon as the PR is open; do not wait.'],
+      ['--max-wait-seconds <n>', 'Per-invocation merge-wait bound.'],
+      ['--no-evidence', 'Do not reuse or write gate evidence stamps.'],
+      ['--dry-run', 'Report the plan; mutate nothing.'],
+    ],
+    notes: [
+      'Exit codes:\n  0  landed\n  1  blocked or failed\n  3  pending (resumable — run the envelope’s nextCommand)',
+    ],
+  },
 });

package/.agents/scripts/single-story-confirm-merge.js

@@ -538,4 +538,20 @@ async function main() {
 runAsCli(import.meta.url, main, {
   source: 'single-story-confirm-merge',
   propagateExitCode: true,
+  usage: {
+    invocation:
+      'node .agents/scripts/single-story-confirm-merge.js --story <id> [--pr <n>] [--wait] [--max-wait-seconds <n>] [--cwd <main-repo>]',
+    summary:
+      'Confirm a Story PR merged and flip the Story to agent::done. With --wait, resumes the bounded merge wait a close handed off.',
+    flags: [
+      ['--story <id>', 'GitHub issue number of the Story (required).'],
+      ['--pr <n>', 'PR number (default: resolved from the Story branch).'],
+      ['--wait', 'Resume the bounded merge wait instead of probing once.'],
+      ['--max-wait-seconds <n>', 'Per-invocation bound for the --wait path.'],
+      [
+        '--cwd <main-repo>',
+        'Main-repo checkout to run from (default: project root).',
+      ],
+    ],
+  },
 });

package/.agents/scripts/single-story-init.js

@@ -831,4 +831,24 @@ export function renderSingleStoryInitComment(result) {
   ].join('\n');
 }
 
-runAsCli(import.meta.url, runSingleStoryInit, { source: 'single-story-init' });
+runAsCli(import.meta.url, runSingleStoryInit, {
+  source: 'single-story-init',
+  usage: {
+    invocation:
+      'node .agents/scripts/single-story-init.js --story <id> [--dry-run] [--steal] [--cwd <main-repo>]',
+    summary:
+      'Initialize a Story for delivery: acquire the lease, seed story-<id> from the base branch, materialize the worktree, and flip the Story to agent::executing.',
+    flags: [
+      ['--story <id>', 'GitHub issue number of the Story (required).'],
+      [
+        '--dry-run',
+        'Report what would happen; no mutations, no lease, no sweep.',
+      ],
+      ['--steal', 'Forcibly transfer a lease held by another assignee.'],
+      [
+        '--cwd <main-repo>',
+        'Main-repo checkout to run from (default: project root).',
+      ],
+    ],
+  },
+});

package/.agents/scripts/stories-wave-tick.js

@@ -880,4 +880,5 @@ async function main(argv) {
 
 runAsCli(import.meta.url, () => main(process.argv.slice(2)), {
   source: 'stories-wave-tick',
+  usage: HELP,
 });

package/.agents/scripts/sync-agentrc.js

@@ -21,15 +21,27 @@
  *   0 — Config is valid (advisories may still appear).
  *   1 — Config is missing, malformed, or fails schema validation.
  *
- * Flags:
- *   --cwd <path>   Project root (defaults to process.cwd()).
- *   --quiet        Suppress advisory rows (only print the status line).
+ * The flag contract lives in `USAGE` below — `--help` is the one home for it.
  */
 
 import { fileURLToPath } from 'node:url';
+import { respondToHelp } from './lib/cli-usage.js';
 import { formatSyncReport, syncAgentrc } from './lib/config/sync-agentrc.js';
 import { Logger } from './lib/Logger.js';
 
+const USAGE = {
+  invocation: 'node .agents/scripts/sync-agentrc.js [--cwd <path>] [--quiet]',
+  summary:
+    'Validate `.agentrc.json` against the framework schema and report every project leaf that merely restates a framework default. Never writes the config.',
+  flags: [
+    ['--cwd <path>', 'Project root (default: process cwd).'],
+    ['--quiet', 'Suppress advisory rows; print only the status line.'],
+  ],
+  notes: [
+    'Exit codes:\n  0  config is valid (advisories may still appear)\n  1  config is missing, malformed, or fails schema validation',
+  ],
+};
+
 function parseArgs(argv) {
   const out = { cwd: null, quiet: false };
   for (let i = 0; i < argv.length; i += 1) {
@@ -67,5 +79,5 @@ function trimAdvisories(report) {
 // cli-opt-out: synchronous CLI with explicit exit-code return.
 const isMain = process.argv[1] === fileURLToPath(import.meta.url);
 if (isMain) {
-  process.exit(main());
+  process.exit(respondToHelp(process.argv.slice(2), USAGE) ? 0 : main());
 }

package/.agents/scripts/update-ticket-state.js

@@ -6,16 +6,37 @@
  */
 
 import { parseArgs } from 'node:util';
+import { respondToHelp } from './lib/cli-usage.js';
 import { resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
 import { transitionTicketState } from './lib/orchestration/ticketing.js';
 import { createProvider } from './lib/provider-factory.js';
 
+const USAGE = {
+  invocation:
+    'node .agents/scripts/update-ticket-state.js --ticket <id> [--state <state> | --remove-label <label>]',
+  summary:
+    'The one sanctioned surface for an agent::* label transition on a ticket.',
+  flags: [
+    ['--ticket <id>', 'GitHub issue number to transition (required).'],
+    [
+      '--state <state>',
+      'Target agent state (e.g. agent::ready, agent::executing, agent::done).',
+    ],
+    [
+      '--remove-label <label>',
+      'Drop a single label without flipping the agent state.',
+    ],
+  ],
+  notes: ['Exactly one of --state or --remove-label is required.'],
+};
+
 // ── CLI Main Block ────────────────────────────────────────────────────────
 // cli-opt-out: re-export shim with a DEBUG_MAIN escape hatch for tests; runAsCli's strict path-equality guard would block the env-flag entry path.
 if (
-  process.argv[1]?.endsWith('update-ticket-state.js') ||
-  process.env.DEBUG_MAIN
+  (process.argv[1]?.endsWith('update-ticket-state.js') ||
+    process.env.DEBUG_MAIN) &&
+  !respondToHelp(process.argv.slice(2), USAGE)
 ) {
   const { values } = parseArgs({
     args: process.argv.slice(2),

package/.agents/workflows/audit-navigability.md

@@ -2,8 +2,8 @@
 description: >-
   Audit the whole route tree against the consumer's nav-registry SSOT —
   every route has a persona nav door and no nav href is dead. A
-  deliberately-global lens (Epic #4131, F2/F3) exempt from the
-  cross-epic-leak guard and routed onto route-adding change sets.
+  deliberately-global lens exempt from the cross-epic-leak guard and
+  routed onto route-adding change sets.
 ---
 
 # Navigability Audit

package/.agents/workflows/audit-to-stories.md

@@ -204,7 +204,7 @@ workflow owns **no** parallel dedup or footer-parsing code: the
 fingerprint, footer round-trip, and routing all live in that one shared
 module.
 
-Dedup runs in **two stages** when a provider resolves (Story #4626): a
+Dedup runs in **two stages** when a provider resolves: a
 meaning-first **semantic candidate** pass (`searchCandidates`, wired to
 [`lib/findings/semantic-issue-search.js`](../scripts/lib/findings/semantic-issue-search.js))
 runs FIRST and widens the net across open + closed issues; the exact

package/.agents/workflows/deliver.md

@@ -1,65 +1,72 @@
 ---
 description:
-  Unified delivery entry point. Takes a list of Story ids, resolves their
-  dependency graph from live state, and delivers each via the single
+  Unified delivery entry point. Takes Story ids or a plain-language prompt,
+  derives which path the work belongs on, and lands it via the single
   deliver-story engine — story-<id> → PR → main.
 ---
 
-# /deliver <storyId...>
+# /deliver
 
-> **Lean spine.** Happy path + gate list. Sequencing edge cases, dispatch
-> mechanics, lite-route inline execution, checklist threading, ceremony, and
-> the per-run epilogue live in the on-demand
-> [`helpers/deliver-reference.md`](helpers/deliver-reference.md). What every
-> delivery always needs is bundled into one read:
-> [`helpers/deliver-digest.md`](helpers/deliver-digest.md) (Story #4736).
+> **Lean spine.** Happy path + gate list. Sequencing, dispatch mechanics,
+> intent phrases, ceremony, and the epilogue live in the on-demand
+> [`helpers/deliver-reference.md`](helpers/deliver-reference.md); the unplanned
+> path in [`helpers/deliver-light.md`](helpers/deliver-light.md). What every
+> delivery always needs is one read:
+> [`helpers/deliver-digest.md`](helpers/deliver-digest.md).
 
 ## Role
 
-Single delivery path, single input shape: **a list of Story ids**. `/deliver`
-owns input resolution and sequencing only — every Story runs through
-[`helpers/deliver-story.md`](helpers/deliver-story.md). No Epic wave loop, no
-`epic/<id>` integration branch, no `--no-ff` wave merges.
-
-The dependency graph is **discovered, not declared**: `resolve-stories.js`
-reads it from live state (body edges ∪ native GitHub `blocked_by` edges, each
-blocker resolved against its real issue state). You never hand it a graph and
-there is no batch label — which is what lets you deliver Stories **across plan
-runs and over time**. `plan-run::<id>` is filter metadata, never a resolution
-input.
-Per-Story routes are **body-derived** too (#4722); `route::lite` is a hint
-only. Ahead of that: a **single-Story run runs the engine inline** whatever the
-shape (#4736) — sub-agent isolation only earns its cost against a concurrent
-sibling.
+One delivery door. `/deliver` owns input resolution and sequencing only — every
+Story lands through [`helpers/deliver-story.md`](helpers/deliver-story.md).
+
+Nothing about the route is declared at the invocation; it is **derived, then
+announced, then acted on**. The dependency graph is **discovered, not
+declared** — `resolve-stories.js` reads it from live state (body edges ∪ native
+`blocked_by` edges, each blocker resolved against its real issue state), so
+there is no graph to hand it and no batch label, which is what lets you deliver
+Stories **across plan runs and over time**.
+`plan-run::<id>` is filter metadata, never a resolution input; `route::lite` is
+a body-derived hint only. Ahead of all of it, a **single-Story run runs the
+engine inline** whatever the shape — sub-agent isolation only earns its cost
+against a concurrent sibling.
 
 ## Inputs
 
-| Invocation | Behavior |
-| --- | --- |
-| `/deliver <storyId>` | Deliver one Story via `helpers/deliver-story.md`, executed **inline in this session** — no `story-worker` spawn. |
-| `/deliver <storyId> <storyId> ...` | Resolve the set with `resolve-stories.js`, then sequence by the discovered graph via `stories-wave-tick.js`, dispatching role-scoped sub-agents. Default concurrency is **3**. |
+Classify what the operator typed **before** doing anything else, and say which
+shape you read it as:
+
+| Invocation | Shape | Behavior |
+| --- | --- | --- |
+| `/deliver` | bare | List the open `agent::ready` Stories and ask which to deliver. Deliver nothing until answered. |
+| `/deliver 4712` | ids | One Story via `helpers/deliver-story.md`, **inline in this session** — no `story-worker` spawn. |
+| `/deliver 4712 4713 …` | ids | Resolve the set, then sequence by the discovered graph via `stories-wave-tick.js`, dispatching role-scoped sub-agents. |
+| `/deliver add a --json flag to doctor` | prompt | Unplanned work: gate, author a receipt Story, land it — [`helpers/deliver-light.md`](helpers/deliver-light.md). |
 
-Any named ticket that is not `type::story`, or still carrying an `Epic: #N`
-footer, is a **hard error** naming the id and the fix (close or re-plan as a v2
-Story). Resolution refuses the whole set rather than silently under-delivering.
+**The discriminator is lexical and total.** Every positional argument matching
+`^#?\d+$` means ids; anything else means a prompt. A **mixed** invocation (ids
+*and* prose) is a **hard error** — refuse it and ask which was meant, the way
+resolution refuses a whole set rather than under-delivering. A named ticket
+that is not `type::story`, or carries an `Epic: #N` footer, is a hard error too.
 
-## Flags
+## Saying what you want
 
-| Flag | Meaning |
-| --- | --- |
-| `--concurrency <n>` | **Optional** per-run override of the fan-out cap. Omit it to honor `delivery.deliverRunner.concurrencyCap` (config default **3**, incl. any `.agentrc.local.json` override); pass **only** for a one-run cap. `1` = sequential. |
-| `--yes` | Suppress the multi-Story confirmation gate. |
-| `--steal` | Forwarded to `single-story-init.js` / lease steal. |
-| `--wait-merge` | Force close-and-land (the default; `delivery.routing.closeAndLand`). |
-| `--no-wait-merge` | Opt out; stop at `agent::closing` for a human land. |
+No flags to remember: state intent — *"…but I'll merge it myself"*, *"…take the
+lease"*, *"…one at a time"* — and announce what you read before acting.
+Phrasings and the flag each fills in:
+[`helpers/deliver-reference.md` § Intent phrases](helpers/deliver-reference.md).
 
-**Operator-merge implies no-wait.** `--no-auto-merge` and
-`delivery.ci.autoMerge: "strict"` rest the Story at `agent::closing`, not
-`agent::blocked` — a genuine *arm failure* still waits and still blocks
-([`helpers/deliver-reference.md` § Operator-merge](helpers/deliver-reference.md)).
+`--yes` is **runner-set, never operator-typed**: cron, `/loop`, and headless
+dispatch set it to mean *nobody is at the keyboard*, which is what makes the
+unplanned path's over-scope stop fail closed to a terminal envelope instead of
+a question. Never offer it to an operator or add it to an attended run.
 
 ## Procedure
 
+0. **Classify and announce.** Read the invocation per § Inputs and state the
+   shape you derived. A prompt leaves for
+   [`helpers/deliver-light.md`](helpers/deliver-light.md); bare asks; ids
+   continue below.
+
 1. **Resolve the set.** One command, for one Story or many:
    `node .agents/scripts/resolve-stories.js --ids <id,id,...>`. It validates
    the set and shows what will run: read `stories[]`, `dag[]`, and `done[]` to
@@ -81,15 +88,14 @@ Story). Resolution refuses the whole set rather than silently under-delivering.
 
    **Do not add `--concurrency` unless the operator explicitly asked for a
    per-run cap** — an explicit value wins over config, so a filled-in literal
-   silently defeats a `.agentrc.local.json` override (see Flags).
+   silently defeats a `.agentrc.local.json` override.
 
    Each beat re-probes live state to derive done / in-flight itself; you never
-   compute them (Story #4594). `--dispatched` is the one thing you must supply —
-   the append-only list of every id you spawned this run — and cross-run
+   compute them. `--dispatched` is the one thing you must supply — the
+   append-only list of every id you spawned this run — and cross-run
    de-confliction via the assignee lease is automatic
-   ([`helpers/deliver-reference.md` § Sequencing edge cases](helpers/deliver-reference.md);
-   [§ Dispatch mechanics](helpers/deliver-reference.md) covers role-scoped
-   spawn, lite-route execution, and `checklistPath`).
+   ([`helpers/deliver-reference.md`](helpers/deliver-reference.md) §§ Sequencing
+   edge cases, Dispatch mechanics).
 
    Branch on the exit code:
    - **0** — dispatch each `ready` id (already capped and overlap-free). Empty
@@ -98,64 +104,57 @@ Story). Resolution refuses the whole set rather than silently under-delivering.
    - **2** — `cycleError`: the graph is self-referential. Fix the `depends_on`
      declarations; do not retry.
    - **3** — `wedged`: nothing dispatchable, nothing in flight, undone Stories
-     waiting on blockers that are not done. The envelope names the stuck ids and
-     unmet blockers. Land the blocker or include it in `--ids`; do not retry
-     unchanged.
+     waiting on unmet blockers — both named in the envelope. Land the blocker
+     or include it in `--ids`; do not retry unchanged.
    - **4** — `blocked`: a Story carries `agent::blocked`, named in `blocked[]`
      with `blockedReason` — the protocol's HITL pause
      ([`instructions.md` § 1.J](../instructions.md)). **Stop the loop and
      surface it; do not poll.** Read the friction comment
      (`gh issue view <id> --comments`) and resume only once the operator
      unblocks it (`update-ticket-state.js --ticket <id> --state agent::ready`).
-     A blocked Story outranks a wedge but not a cycle (fix the graph first).
+     Blocked outranks a wedge but not a cycle (fix the graph first).
 
 4. **Per-run epilogue (N>1).** Once step 3 reports `epilogueDue: true`, run
    `node .agents/scripts/plan-run-epilogue.js --stories 101,102` — audit
-   roster, follow-up roll-up, sibling coherence. A single-Story run skips it.
-   Detail:
-   [`helpers/deliver-reference.md` § Per-run epilogue](helpers/deliver-reference.md).
+   roster, follow-up roll-up, sibling coherence. A single-Story run skips it
+   ([reference § Per-run epilogue](helpers/deliver-reference.md)).
 
 ## Branch model (authoritative)
 
-```text
-story-<id>  →  PR  →  main (squash + required checks)
-```
-
-No `epic/<id>` integration branch and no `--no-ff` wave merge. Dependent
-Stories land sequentially so each builds on the previous merge to `main`.
-Ceremony depth (profiles + derived level via `ceremony-routing.js`,
-review depth reading the same level) and the mechanism table:
+`story-<id>` → PR → `main` (squash + required checks), per digest § 2.
+Dependent Stories land sequentially so each builds on the previous merge.
+Ceremony depth (profiles + derived level via `ceremony-routing.js`, review
+depth reading the same level):
 [`helpers/deliver-reference.md` § Ceremony](helpers/deliver-reference.md).
 
 ## Reading a Story's outcome
 
-Each Story's delivery ends in exactly one schema-validated terminal envelope —
-`landed` | `pending` | `blocked` | `failed`. Statuses, exits, and fields:
-[`helpers/deliver-digest.md`](helpers/deliver-digest.md) § 5, over the shipped
-[schema](../schemas/story-deliver-terminal.schema.json) (Story #4543).
+Each Story ends in exactly one schema-validated terminal envelope — `landed` |
+`pending` | `blocked` | `failed`. Statuses, exits, and fields:
+[`helpers/deliver-digest.md`](helpers/deliver-digest.md) § 5.
 
-`pending` is **not** a failure: the bounded merge wait expired with the PR
-healthy (or a human owns the merge), nothing was mutated, and the
-`nextCommand` resumes it — run that rather than re-dispatching. The slow-CI
-`async` mode (Story #4698) returns `pending` by design — launch its
-`nextCommand` as a background invocation (reference appendix).
+`pending` is **not** a failure: the bounded wait expired with the PR healthy
+(or a human owns the merge), nothing was mutated, and `nextCommand` resumes it
+— run that rather than re-dispatching.
 
 For a Story in an unclear state — including the merged-but-label-stale one a
-`/deliver` re-run refuses outright — probe it read-only with
+re-run refuses outright — probe it read-only with
 `node .agents/scripts/deliver-recover.js --story <storyId>`.
 
 ## Constraints
 
 - **Land or block — never a silent local build** (digest § 2). Attended
   delivers default to close-and-land (`delivery.routing.closeAndLand: true`);
-  use `--no-wait-merge` only when a human lands the PR.
-- `/deliver` never plans — tickets come from [`/plan`](plan.md). The router
-  performs no git/label mutations; `deliver-story` owns every script.
+  rest at `agent::closing` only when a human owns the merge.
+- **`/deliver` never plans.** Planned tickets come from [`/plan`](plan.md), and
+  an over-scope prompt **escalates and ends** — never invoke `/plan` in this
+  session to rescue it ([`helpers/deliver-light.md`](helpers/deliver-light.md)
+  § Escalation is terminal). The router performs no git/label mutations;
+  `deliver-story` owns every script.
 
 ## See also
 
 - [`/plan`](plan.md) — unified planning entry point.
-- [`helpers/deliver-story.md`](helpers/deliver-story.md) — the one Story
-  delivery engine.
-- [`helpers/deliver-reference.md`](helpers/deliver-reference.md) — sequencing,
-  dispatch, ceremony, and epilogue detail.
+- [`helpers/deliver-story.md`](helpers/deliver-story.md) — the one engine.
+- [`helpers/deliver-light.md`](helpers/deliver-light.md) — the unplanned
+  prompt path, shared with `/plan` Gate #1.

package/.agents/workflows/git-cleanup.md

@@ -22,12 +22,12 @@ Reach for it when the automated hygiene left an unusual state behind.
 
 The enumeration + reap logic lives in
 [`git-cleanup.js`](../scripts/git-cleanup.js) — it computes the candidate list,
-the skip taxonomy, the detection signals, and the JSON envelope (add `--json`),
-and prints them itself. Without `--execute` the script is a **dry-run preview**; nothing is
-mutated. When no phase flag is passed, **all four phases run** sequentially; pass
-any of `--fast-forward-main`, `--prune-remotes`, `--branches`, `--stashes` to
-narrow the run. A failure in one phase does not short-circuit the others — each
-runs and reports independently.
+the skip taxonomy, the detection signals, and the JSON envelope, and prints them
+itself. Without `--execute` the script is a **dry-run preview**; nothing is
+mutated. When no phase flag is passed, **all four phases run** sequentially; a
+phase flag narrows the run. A failure in one phase does not short-circuit the
+others — each runs and reports independently. The script documents its own
+flags: `node .agents/scripts/git-cleanup.js --help`.
 
 ## Phases
 
@@ -44,14 +44,9 @@ runs and reports independently.
 > branches, delete remote refs (with `--remote`), and drop stashes. Without
 > `--execute` the script only previews.
 
-- **`--execute`** — the master gate. Omit it for a preview of all four phases.
-- **`--remote`** — extends the branches phase to delete the matching
-  `origin/<branch>` ref (and to delete remote-only merged branches). Cannot be
-  undone without re-pushing.
-- **`--yes`** — bypass every per-step prompt (CI / non-interactive). Under it,
-  stash drops still require `--drop-stashes <ref>`.
-- **`--exclude '<pattern>'`** — carve a branch out of the reap. This is the only
-  way to protect an in-scope merged-PR branch you want to keep.
+Two consequences the flag list alone does not carry: `--remote` deletions cannot
+be undone without re-pushing, and `--exclude '<pattern>'` is the **only** way to
+protect an in-scope merged-PR branch you want to keep.
 
 Do **not** run with `--execute` if there is unmerged work that needs saving. The
 fast-forward phase skips on a dirty tree (safe), but the branches phase reaps any

package/.agents/workflows/helpers/acceptance-self-eval.md

@@ -15,7 +15,7 @@ description: >-
 After the implementation commits land and **before** the Story proceeds to
 close, run an explicit, **independent** eval pass that scores the change set
 computed once for this Story and injected into the critic — never one the
-critic re-derives (Story #4593) — against **each** `acceptance[]` item
+critic re-derives — against **each** `acceptance[]` item
 individually. This is the acceptance gate
 the close-validation chain does not provide: that chain (lint / test / format /
 maintainability / coverage / crap) proves the code is *healthy*, not that it
@@ -30,7 +30,7 @@ mid-delivery, and evaluates the actual work product.
 
 ## Per round
 
-1. **Eval pass — one verdict-owner per cluster (Story #4723).** Exactly
+1. **Eval pass — one verdict-owner per cluster.** Exactly
    **one** pass authors each cluster's verdict: the **fresh-context critic**
    when the ceremony routing below resolves `fresh` (a sub-agent via the
    `Agent` tool, *not* a continuation of your implementing turn — the
@@ -44,7 +44,7 @@ mid-delivery, and evaluates the actual work product.
    of the one authored verdict, not a second (or third) pass over the
    criteria.
 
-   > **Sub-agent type + derived-level ceremony (Epic #4478, M7-B).** When
+   > **Sub-agent type + derived-level ceremony.** When
    > `delivery.routing.roleScopedAgents` is enabled (the **default**), dispatch
    > the critic with `subagent_type: acceptance-critic` — it boots on the
    > role-scoped [`acceptance-critic`](../../agents/acceptance-critic.md) context
@@ -57,8 +57,8 @@ mid-delivery, and evaluates the actual work product.
    > — the same signal `review-depth.js` resolves depth from, so the two
    > decisions cannot disagree. Derive it with `deriveChangeLevel` from
    > [`review-depth.js`](../../scripts/lib/orchestration/review-depth.js) over
-   > the **change set your caller computed once** for this Story (Story #4593 —
-   > `computeChangeSet` from
+   > the **change set your caller computed once** for this Story
+   > (`computeChangeSet` from
    > [`change-set.js`](../../scripts/lib/orchestration/change-set.js); see
    > [`deliver-story.md`](deliver-story.md) Step 2), then
    > resolve the ceremony per cluster with `resolveCeremonyForRisk` from
@@ -73,9 +73,10 @@ mid-delivery, and evaluates the actual work product.
    > full ceremony** (fail-safe). This chooses fresh-vs-inline **per cluster
    > only — it never changes the cluster count**.
    >
-   > Story #4542 re-based this off the planner-authored risk verdict: a level
-   > the plan asserted about itself was exactly the signal that could *reduce*
-   > independent checking, and nothing verified it against the diff.
+   > The routing signal is deliberately **not** a planner-authored risk
+   > verdict: a level the plan asserted about itself was exactly the signal
+   > that could *reduce* independent checking, and nothing verified it
+   > against the diff.
    >
    > **Inline-critic path (low-level-routed OR nesting-absent harness).** The
    > verdict is authored **inline** whenever the risk router above resolves to
@@ -83,8 +84,8 @@ mid-delivery, and evaluates the actual work product.
    > a **fallback** on any harness that cannot spawn the fresh critic.
    > Dispatching the critic as a nested `Agent` is the fresh-context shape and
    > works on any harness that carries `Agent` into sub-agents (Claude Code ≥
-   > 2.1.202; see [#2870](https://github.com/dsj1984/mandrel/issues/2870)). This
-   > eval loop itself runs inside a Story delivery sub-agent, so the nested
+   > 2.1.202). This eval loop itself runs inside a Story delivery
+   > sub-agent, so the nested
    > critic sits at nesting depth 2. If the host does **not** support nested
    > `Agent` dispatch at that depth — the tool is absent, or a spawn attempt
    > returns an unsupported-capability error — do **not** stall the Story
@@ -104,7 +105,7 @@ mid-delivery, and evaluates the actual work product.
    - Inspects the **change set handed to it in its spawn context** — the one
      list computed above — and the Story's inline `acceptance[]` / `verify[]`
      arrays. Pass the file list explicitly when you dispatch the critic; it
-     does not re-enumerate the diff for itself (Story #4593), so a commit
+     does not re-enumerate the diff for itself, so a commit
      landing mid-ceremony cannot leave the critic scoring a different change
      than the one that routed it.
    - **Runs the `verify[]` commands** and consumes their output as **required
@@ -112,7 +113,7 @@ mid-delivery, and evaluates the actual work product.
      optional advisory pre-flight — a criterion cannot be scored `met` without
      the supporting `verify[]` evidence where a `verify[]` command is relevant
      to it.
-   - **Shares `lint` / `typecheck` evidence with close (Story #4250).** When a
+   - **Shares `lint` / `typecheck` evidence with close.** When a
      `verify[]` command is **byte-identical** to a close-validation gate — in
      practice only the cheap, command-identical `lint` and `typecheck` gates
      (`npm run lint` and the resolved `project.commands.typecheck`) — the
@@ -140,7 +141,7 @@ mid-delivery, and evaluates the actual work product.
 2. **Decide.** Run the gate against the verdict (the caller's Step 1a names the
    exact invocation — omit `--epic`). The gate **scores the single verdict
    the round's owner authored** — schema validation, round cap, decision —
-   and never re-scores the criteria itself (Story #4723):
+   and never re-scores the criteria itself:
 
    ```bash
    node <main-repo>/.agents/scripts/acceptance-eval.js \

package/.agents/workflows/helpers/audit-lens-core.md

@@ -1,7 +1,7 @@
 # Audit lens core (shared contract)
 
-> **Single source of truth for every audit lens's shared machinery
-> (Story #4665).** Each `audit-<lens>.md` workflow references this file instead
+> **Single source of truth for every audit lens's shared machinery.**
+> Each `audit-<lens>.md` workflow references this file instead
 > of re-stating the blocks below. A lens carries only its own frontmatter, a
 > short preamble, its `{{changedFiles}}` fence, and its genuinely lens-specific
 > dimensions / detection batteries / applicability gates / boundary

package/.agents/workflows/helpers/code-review.md

@@ -53,9 +53,9 @@ envelope.
 ### Review depth (`depth`)
 
 `depth` is the thoroughness lever: `runCodeReview` derives it from the diff via
-[`review-depth.js`](../../scripts/lib/orchestration/review-depth.js) (Story #4542
-re-based it on that observable signal, so it takes no planner-authored input) and
-forwards it to every provider's `runReview` input.
+[`review-depth.js`](../../scripts/lib/orchestration/review-depth.js) — an
+observable signal that takes no planner-authored input — and forwards it to
+every provider's `runReview` input.
 
 It is an **input-only** signal: it changes *how thorough* the review is, never
 the findings envelope (`{ status, severity, posted, report, halted,
@@ -98,7 +98,7 @@ The caller invokes the in-process code-review pipeline
 (`runCodeReview` in `.agents/scripts/lib/orchestration/code-review.js`)
 with the resolved `{ scope, ticketId, baseRef, headRef, depth }` envelope
 (`depth` defaults to `standard` when the caller omits it). The
-pluggable `ReviewProvider` adapter chain (Epic #2815) runs against the
+pluggable `ReviewProvider` adapter chain runs against the
 diff `baseRef..headRef`, with the LLM-backed providers honoring `depth`
 (see **Review depth** above), and posts a structured summary to `[TICKET_ID]`.
 The pipeline will:
@@ -108,7 +108,7 @@ The pipeline will:
 - Run a focused lint check on the change set.
 - Post a structured summary report to the `[TICKET_ID]` issue.
 
-### Step 1a — Story-scope local-lens pass (`scope: story` only, Epic #4405)
+### Step 1a — Story-scope local-lens pass (`scope: story` only)
 
 When `scope === 'story'`, the shared review spine
 [`runStoryReviewCore`](../../scripts/lib/orchestration/story-close/phases/review-core.js)
@@ -173,7 +173,7 @@ The diff under review is `baseRef..headRef`
 (`main..story-<storyId>`, or the configured base branch to the Story
 branch). The Story-scope local-lens pass (Step 1a) has already covered the
 local-tier concerns. Lens findings and pillar findings share the single
-`verification-results` comment this pass posts (Story #4411). The
+`verification-results` comment this pass posts. The
 integration view here focuses on cross-cutting ripple within the Story and
 contract drift against the base branch. Look for:
 
@@ -257,9 +257,9 @@ prior baseline before merging.
 ## Step 4 — Produce Findings Report
 
 Findings are **persisted as a `verification-results` structured comment on
-the `[TICKET_ID]` issue** by `runCodeReview` (the unified findings contract of
-Story #4411; this single comment carries the
-Story-scope lens findings). The target ticket is the Story. The comment
+the `[TICKET_ID]` issue** by `runCodeReview` (the unified findings contract —
+this single comment carries the Story-scope lens findings). The target
+ticket is the Story. The comment
 is idempotent — re-runs replace the prior one — and its body includes
 severity-tier counts plus the full findings list so downstream workflows
 (notably the retro helper) can summarise blockers/high findings without
@@ -289,7 +289,7 @@ For every finding, provide:
   fix worked. Keep it tight (≤ 5 sentences); the sub-agent will read the
   surrounding code itself.
 
-### The `## Fixed on-branch` section (Story #4399)
+### The `## Fixed on-branch` section
 
 Findings that Step 4.5 remediated on `[HEAD_REF]` MUST be rendered under a
 dedicated **`## Fixed on-branch`** heading, **not** in the severity groups
@@ -322,7 +322,7 @@ the executor: it decides, per finding, between a focused fix on
 `[HEAD_REF]` and leaving the finding on the `verification-results`
 structured comment for the operator.
 
-### Resolve the remediation threshold (Story #4399)
+### Resolve the remediation threshold
 
 Read `delivery.codeReview.autoFixSeverity` from the resolved `.agentrc.json`
 (default **`medium`**; the resolver in