mandrel 2.36.0 → 2.38.0

package/.agents/scripts/lib/git-branch-lifecycle.js

@@ -89,7 +89,7 @@ export function branchExistsViaTrackingRef(branch, cwd) {
 /**
  * Pure: classify how a `story-<id>` branch should be seeded from the (local,
  * remote) ref-presence matrix. This is the single source of truth for
- * `single-story-init.js#decideStoryBranchSeed` (v2 `/deliver` path).
+ * `single-story-init.js#decideStoryBranchSeed` (v2 `/mandrel-deliver` path).
  *
  * The init path previously re-implemented the same `local → no-op, remote →
  * fetch, else create` decision tree; it now delegates here so the branching
@@ -122,7 +122,7 @@ export function classifyBranchSeed({ localHas, remoteHas }) {
  * The two callers differ in exactly two behavioural axes, both of which are
  * parameters here — no other conditional branching is introduced:
  *   - **`baseRef`** — the ref to branch from on `create` (`main` for v2
- *     `/deliver`; pre-v2 Epic close used the Epic branch).
+ *     `/mandrel-deliver`; pre-v2 Epic close used the Epic branch).
  *   - **`swallowCreateRace`** — when `true`, a `git branch` that exits
  *     non-zero with an "already exists" stderr is treated as reuse rather
  *     than a fatal error (pre-v2 concurrent wave dispatch). When `false`, any create failure

package/.agents/scripts/lib/install-cmd-parser.js

@@ -17,7 +17,7 @@ import { spawnSync as defaultSpawnSync } from 'node:child_process';
  * @param {string} installCmd
  * @returns {{ bin: string, args: string[], shell: boolean }}
  */
-export function parseInstallCmd(installCmd) {
+function parseInstallCmd(installCmd) {
   const tokens = String(installCmd ?? '')
     .trim()
     .split(/\s+/)

package/.agents/scripts/lib/knip-entry-sync.js

@@ -59,6 +59,7 @@ import {
   resolveKnipEntryPatterns,
   __testing as resolverTesting,
 } from './knip-config-resolver.js';
+import { stripJsComments } from './source-text/strip-js-comments.js';
 
 // Only `resolveEntrySync` and `renderEntrySyncReport` are public — they are
 // what `check-knip-entries.js` calls. Everything else is module-private and
@@ -89,63 +90,6 @@ const INVOCATION_SURFACES = Object.freeze([
   { kind: 'dir', at: SCRIPTS_DIR, test: /\.js$/ },
 ]);
 
-/**
- * Strip line and block comments from JavaScript source, preserving string and
- * template literals so a `'https://…'` or a `` `${x}//y` `` is not mangled.
- *
- * Comments are stripped before scanning `.js` surfaces so a JSDoc paragraph
- * that merely *names* a CLI ("superseded by `node .agents/scripts/foo.js`")
- * cannot confer liveness on it. Several such mentions exist today; every one
- * of them is prose about a script's internals, not a call.
- *
- * Replaces comment bodies with equivalent whitespace rather than deleting
- * them, so byte offsets and line numbers survive for any future caller that
- * wants to report a position.
- *
- * @param {string} source
- * @returns {string}
- */
-function stripJsComments(source) {
-  const text = String(source ?? '');
-  let out = '';
-  let i = 0;
-  const blank = (s) => s.replace(/[^\n]/g, ' ');
-  while (i < text.length) {
-    const two = text.slice(i, i + 2);
-    if (two === '//') {
-      const end = text.indexOf('\n', i);
-      const stop = end === -1 ? text.length : end;
-      out += blank(text.slice(i, stop));
-      i = stop;
-    } else if (two === '/*') {
-      const end = text.indexOf('*/', i + 2);
-      const stop = end === -1 ? text.length : end + 2;
-      out += blank(text.slice(i, stop));
-      i = stop;
-    } else {
-      const ch = text[i];
-      if (ch === "'" || ch === '"' || ch === '`') {
-        let j = i + 1;
-        while (j < text.length) {
-          if (text[j] === '\\') {
-            j += 2;
-            continue;
-          }
-          if (text[j] === ch) break;
-          j += 1;
-        }
-        const stop = Math.min(j + 1, text.length);
-        out += text.slice(i, stop);
-        i = stop;
-      } else {
-        out += ch;
-        i += 1;
-      }
-    }
-  }
-  return out;
-}
-
 /**
  * Recursively list files under `dir`, skipping `node_modules` and `.git`.
  *

package/.agents/scripts/lib/label-constants.js

@@ -15,7 +15,7 @@ export const AGENT_LABELS = {
   // the Story PR is opened against `main`. It flips to
   // `agent::done` only after the close pipeline confirms the PR merge
   // landed; if the close is killed mid-flight, the Story remains at
-  // `agent::closing` so `/deliver` can pick up at the
+  // `agent::closing` so `/mandrel-deliver` can pick up at the
   // post-merge phase rather than re-running preflight. The label is the
   // distinguishing signal between "hung close" and "finished work".
   CLOSING: 'agent::closing',
@@ -101,7 +101,7 @@ export const ACCEPTANCE_NA = ACCEPTANCE_LABELS.N_A;
  * loop). `meta::framework-gap` is applied to issues that surface a defect or
  * missing capability in the framework itself; `meta::consumer-improvement`
  * is applied to issues that surface improvements to a consumer project
- * (workflow tweaks, ergonomic asks, doc polish). The `/plan` Phase 0
+ * (workflow tweaks, ergonomic asks, doc polish). The `/mandrel-plan` Phase 0
  * fetcher (see `lib/feedback-loop/prior-feedback-fetcher.js`) reads open
  * issues carrying either label and surfaces them to the planner so retro
  * signals are routed into durable substrates rather than lost in chat.

package/.agents/scripts/lib/label-taxonomy.js

@@ -40,7 +40,7 @@ export const LABEL_TAXONOMY = [
     name: AGENT_LABELS.READY,
     color: LABEL_COLORS.AGENT,
     description:
-      'Parking state — frozen dispatch manifest exists; awaiting local /deliver',
+      'Parking state — frozen dispatch manifest exists; awaiting local /mandrel-deliver',
   },
   {
     name: AGENT_LABELS.EXECUTING,

package/.agents/scripts/lib/maintainability-utils.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { minimatch } from 'minimatch';
+import { Minimatch } from 'minimatch';
 import { canonicalise as canonicalisePath } from './baselines/path-canon.js';
 import { POOL_SERIAL_THRESHOLD, runOnPool } from './cpu-pool.js';
 import { Logger } from './Logger.js';
@@ -27,6 +27,57 @@ const IGNORED_DIRS = new Set([
   '.next',
 ]);
 
+/**
+ * Compiled-matcher cache for `isIgnoredByGlobs`, keyed on the pattern list.
+ *
+ * `minimatch(path, glob)` re-parses `glob` into an AST on every call, so the
+ * scan was paying O(files × globs) glob *compilations* to answer O(files ×
+ * globs) glob *matches* — 12–17 ms over the 619-file tree against 0.5 ms
+ * once the patterns are compiled (Story #5109). The number of distinct
+ * pattern lists in a process is tiny (one per gate), and each list is
+ * config-derived and immutable, so an unbounded `Map` keyed on the joined
+ * patterns is bounded in practice.
+ *
+ * Each entry also memoises the per-path verdict. The baseline gates ask the
+ * same question about the same path many times over — `crap.json` carries
+ * thousands of method rows spread over a few hundred files, and the evaluate
+ * phase filters every row — so the second and later asks about a path cost a
+ * `Map` lookup instead of a globstar walk. Both caches are keyed on
+ * config-derived, immutable inputs, and both are bounded by the tree the
+ * process is scanning.
+ *
+ * `\u0000` is the join separator because it cannot occur in a glob, so two
+ * different lists cannot collide onto one key.
+ *
+ * @type {Map<string, {matchers: import('minimatch').Minimatch[], verdicts: Map<string, boolean>}>}
+ */
+const IGNORE_MATCHER_CACHE = new Map();
+
+/**
+ * Compile (once) the `Minimatch` instances for a pattern list, alongside the
+ * per-path verdict memo that shares their lifetime.
+ *
+ * Non-string patterns are dropped rather than compiled — `minimatch()` would
+ * have thrown on them, and the functional call site never fed it any, so
+ * dropping preserves the observable result set.
+ *
+ * @param {string[]} ignoreGlobs
+ * @returns {{matchers: import('minimatch').Minimatch[], verdicts: Map<string, boolean>}}
+ */
+function ignoreMatcherEntry(ignoreGlobs) {
+  const key = ignoreGlobs.join('\u0000');
+  let entry = IGNORE_MATCHER_CACHE.get(key);
+  if (entry) return entry;
+  entry = {
+    matchers: ignoreGlobs
+      .filter((g) => typeof g === 'string')
+      .map((g) => new Minimatch(g, { dot: true })),
+    verdicts: new Map(),
+  };
+  IGNORE_MATCHER_CACHE.set(key, entry);
+  return entry;
+}
+
 /**
  * Test whether an absolute (or repo-relative) file path matches any of the
  * configured `ignoreGlobs`. This is the single source of truth for how the
@@ -39,22 +90,62 @@ const IGNORED_DIRS = new Set([
  *
  * Matching mirrors `scanDirectory`: the path is reduced to a canonicalised,
  * POSIX, repo-relative form and tested against each glob with minimatch's
- * `{ dot: true }` so dot-prefixed roots like `.agents/` match.
+ * `{ dot: true }` so dot-prefixed roots like `.agents/` match. The patterns
+ * are compiled at most once per distinct list (see `IGNORE_MATCHER_CACHE`);
+ * the matched set is identical to the functional `minimatch()` call this
+ * replaced, which is what the `gate-scan-fast-path` test pins over the real
+ * configured `ignoreGlobs`.
  *
  * @param {string} filePath absolute or relative path to the source file
  * @param {string[]} ignoreGlobs minimatch patterns; empty/absent is a no-op
  * @param {string} [cwd] root for repo-relative resolution; defaults to cwd
  * @returns {boolean} true when the file matches at least one ignore glob
  */
-export function isIgnoredByGlobs(filePath, ignoreGlobs = [], cwd) {
-  if (!Array.isArray(ignoreGlobs) || ignoreGlobs.length === 0) return false;
-  const matchCwd = cwd ?? process.cwd();
+/**
+ * Reduce an absolute-or-relative path to the canonicalised, POSIX,
+ * repo-relative form the ignore patterns are written against.
+ *
+ * @param {string} filePath
+ * @param {string} matchCwd
+ * @returns {string}
+ */
+function canonicalRelPath(filePath, matchCwd) {
   const absFilePath = path.isAbsolute(filePath)
     ? filePath
     : path.resolve(matchCwd, filePath);
   const rawRel = path.relative(matchCwd, absFilePath).replace(/\\/g, '/');
-  const relPath = canonicalisePath(rawRel);
-  return ignoreGlobs.some((g) => minimatch(relPath, g, { dot: true }));
+  return canonicalisePath(rawRel);
+}
+
+/**
+ * Answer "does this path match any of the entry's patterns", consulting and
+ * populating the entry's verdict memo.
+ *
+ * Split out of `isIgnoredByGlobs` rather than inlined: the memo's
+ * hit/miss test is a branch, and folding it into the caller pushed that
+ * function from cyclomatic 4 to 5 — over the per-method CRAP contract the
+ * pre-push preview enforces. The lookup belongs beside the cache it reads
+ * anyway, and the hot function keeps a flat shape.
+ *
+ * @param {{matchers: import('minimatch').Minimatch[], verdicts: Map<string, boolean>}} entry
+ * @param {string} relPath Canonicalised, POSIX, repo-relative path.
+ * @returns {boolean}
+ */
+function memoisedIgnoreVerdict(entry, relPath) {
+  const memoised = entry.verdicts.get(relPath);
+  if (memoised !== undefined) return memoised;
+  const verdict = entry.matchers.some((m) => m.match(relPath));
+  entry.verdicts.set(relPath, verdict);
+  return verdict;
+}
+
+export function isIgnoredByGlobs(filePath, ignoreGlobs = [], cwd) {
+  if (!Array.isArray(ignoreGlobs) || ignoreGlobs.length === 0) return false;
+  const matchCwd = cwd ?? process.cwd();
+  return memoisedIgnoreVerdict(
+    ignoreMatcherEntry(ignoreGlobs),
+    canonicalRelPath(filePath, matchCwd),
+  );
 }
 
 /**
@@ -107,7 +198,7 @@ export function scanDirectory(dir, fileList = [], opts = {}) {
  * Calculates maintainability scores for a list of file paths.
  *
  * Each file's transpile-then-analyze unit is dispatched to a
- * worker_threads pool sized to `os.availableParallelism()`. Workers
+ * worker_threads pool whose width `runOnPool` resolves. Workers
  * are recycled across files so TypeScript loads at most once per
  * worker. The pool is bypassed for batches of fewer than
  * `SERIAL_THRESHOLD` files because spawn overhead dominates at small
@@ -129,9 +220,16 @@ export function scanDirectory(dir, fileList = [], opts = {}) {
  * and nothing said so.
  *
  * @param {string[]} paths
+ * @param {{serialThreshold?: number}} [opts] `serialThreshold` overrides the
+ *   pool-vs-serial cutover for this call only. Production callers omit it;
+ *   the parity tests use it to drive the pooled path on a small fixture set
+ *   rather than materialising 256 files to clear the cutover.
  * @returns {Promise<Record<string, number>>}
  */
-export async function calculateAll(paths) {
+export async function calculateAll(paths, opts = {}) {
+  const serialThreshold = Number.isFinite(opts?.serialThreshold)
+    ? opts.serialThreshold
+    : SERIAL_THRESHOLD;
   const cwd = process.cwd();
   const indexed = paths.map((p) => ({
     abs: p,
@@ -139,7 +237,7 @@ export async function calculateAll(paths) {
   }));
 
   let perFile;
-  if (indexed.length < SERIAL_THRESHOLD) {
+  if (indexed.length < serialThreshold) {
     perFile = indexed.map(({ abs, relPath }) => {
       try {
         return { relPath, ...scoreFile(abs) };

package/.agents/scripts/lib/observability/source-classifier.js

@@ -94,6 +94,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'check-cyclomatic.js',
   'check-dead-exports.js',
   'check-doc-links.js',
+  'check-generated-validator.js',
   'check-gherkin-corpus.js',
   'check-knip-entries.js',
   'check-lifecycle-lint.js',

package/.agents/scripts/lib/onboard/init-tail.js

@@ -7,7 +7,7 @@
  *
  *   Phase 1 — Offer to scaffold missing docsContextFiles (scaffold-docs.js).
  *   Phase 2 — Run `mandrel doctor` as a readiness gate.
- *   Phase 3 — Print the /plan handoff next-step text.
+ *   Phase 3 — Print the /mandrel-plan handoff next-step text.
  *
  * The whole tail is idempotent: re-running after an already-onboarded project
  * re-checks and re-offers scaffolding without duplicating stubs (the scaffolder
@@ -31,13 +31,13 @@ import { STUB_MARKER, scaffoldDocs } from './scaffold-docs.js';
 // ---------------------------------------------------------------------------
 
 /**
- * Text printed at the end of the init tail to hand the operator off to /plan.
+ * Text printed at the end of the init tail to hand the operator off to /mandrel-plan.
  *
  * @type {string}
  */
 export const PLAN_HANDOFF_TEXT =
   '\n✅  Mandrel is ready. Start your first project:\n\n' +
-  '    /plan --seed "<one-line description of what you want to build>"\n';
+  '    /mandrel-plan --seed "<one-line description of what you want to build>"\n';
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -200,7 +200,7 @@ export async function runInitTail({
     return { scaffoldResult, doctorStatus, ok: false };
   }
 
-  // --- Phase 3: Handoff to /plan -------------------------------------------
+  // --- Phase 3: Handoff to /mandrel-plan -------------------------------------------
   stdout(PLAN_HANDOFF_TEXT);
   return { scaffoldResult, doctorStatus, ok: true };
 }

package/.agents/scripts/lib/onboard/scaffold-docs.js

@@ -25,7 +25,7 @@ const AGENT_ROOT = path.resolve(__dirname, '../../..');
 const DOCS_TEMPLATE_DIR = path.join(AGENT_ROOT, 'templates', 'docs');
 
 /**
- * Deterministic marker written into every scaffolded stub. The `/plan`
+ * Deterministic marker written into every scaffolded stub. The `/mandrel-plan`
  * first-run preflight (and any tooling that wants to detect unedited stubs)
  * keys off this exact string — do not change it without a hard cutover.
  *
@@ -59,7 +59,7 @@ function genericStub(fileName) {
 /**
  * Read the dedicated template body for a docsContextFile, or fall back to the
  * generic stub when no template ships for that name. Either path prepends the
- * {@link STUB_MARKER} so the `/plan` first-run preflight can detect un-edited
+ * {@link STUB_MARKER} so the `/mandrel-plan` first-run preflight can detect un-edited
  * stubs regardless of whether a dedicated template was used.
  *
  * @param {string} fileName

package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js

@@ -170,7 +170,7 @@ export function decideAcceptanceEval({ verdict, maxRounds, round: roundIn }) {
 /**
  * Build the per-criterion acceptance-eval signal payload for the retro /
  * feedback substrate. Carries which acceptance items needed rework and the
- * round count so `/plan` Phase 0 feedback fetch and the retro can
+ * round count so `/mandrel-plan` Phase 0 feedback fetch and the retro can
  * surface acceptance churn. PII-free by construction — it carries only
  * acceptance-item indices, verdicts, and the terminal decision.
  *

package/.agents/scripts/lib/orchestration/code-review.js

@@ -3,7 +3,7 @@
  *
  * Story #1155 (Epic #1142, 5.40.0) — extracted the helper-driven
  * `epic-code-review` invocation into a callable module so the
- * `/deliver` runner can run Phase D without spawning a child
+ * `/mandrel-deliver` runner can run Phase D without spawning a child
  * process or routing through an LLM-driven helper.
  *
  * Story #2831 (Epic #2815, Pluggable Code Review) — refactored to load
@@ -32,11 +32,11 @@
  *     `code-review` and `audit-results` findings contracts into this one
  *     `verification-results` marker.
  *   - Treats severity.critical > 0 as a halting blocker — the merged
- *     `/deliver` runner consults `halted` and refuses to advance
+ *     `/mandrel-deliver` runner consults `halted` and refuses to advance
  *     to Phase E (retro) when set.
  *
  * Halting on critical findings is the in-process replacement for the
- * helper's "operator must remediate before /deliver" gate.
+ * helper's "operator must remediate before /mandrel-deliver" gate.
  */
 
 import { hasSurvivingCritical } from '../audit-suite/findings.js';
@@ -129,7 +129,7 @@ function resolveScopeEnvelope(opts, config) {
 }
 
 /**
- * In-process wrapper that the `/deliver` runner and the
+ * In-process wrapper that the `/mandrel-deliver` runner and the
  * `/single-story-deliver` close path consume.
  *
  * Story #2252 — emits `code-review.start` immediately on entry and

package/.agents/scripts/lib/orchestration/complexity-gate.js

@@ -132,7 +132,7 @@ export const LITE_ROUTE_LABEL = 'route::lite';
  *                        footprint: `trivial` < `moderate` < `substantial`.
  *   - `maxUncertainty` — is the shape determined by the request
  *                        (`determined`), or does it still need the design
- *                        decisions `/plan` exists to resolve
+ *                        decisions `/mandrel-plan` exists to resolve
  *                        (`needs-design`)?
  *   - `maxDeployables` — named deployable roots (`apps/<x>`, `packages/<x>`, …)
  *                        the footprint spans; more than one is epic by
@@ -325,7 +325,7 @@ const EFFORT_RULES = Object.freeze([
       UNCERTAINTY_SCALE.indexOf(s.uncertainty) >
       UNCERTAINTY_SCALE.indexOf(c.maxUncertainty),
     reason: (s) =>
-      `the shape is not determined by the request (uncertainty "${s.uncertainty}") — the design decisions /plan exists to resolve are still open; full route`,
+      `the shape is not determined by the request (uncertainty "${s.uncertainty}") — the design decisions /mandrel-plan exists to resolve are still open; full route`,
   },
   {
     code: SHAPE_CODES.DEPLOYABLE_SPAN,
@@ -657,7 +657,7 @@ function buildEffortShape({
 /**
  * Derive the complexity route from an authored Story's **effort and risk**
  * (Story #4722 AC-3/AC-4; re-anchored off artifact cardinality by Story #4764)
- * — the single shape function persist's backstop and `/deliver`'s dispatch
+ * — the single shape function persist's backstop and `/mandrel-deliver`'s dispatch
  * derivation both read, so the two can never disagree about the same body.
  *
  * `lite` requires **every** signal to agree, against
@@ -804,7 +804,7 @@ export function deriveStoryShape({
 }
 
 /**
- * Decide how `/deliver` executes a Story: **run topology, and nothing else.**
+ * Decide how `/mandrel-deliver` executes a Story: **run topology, and nothing else.**
  *
  * **`inline` names one indivisible resource: the router's own session.** Two
  * Stories cannot both own it, so exactly one premise can grant it —
@@ -839,7 +839,7 @@ export function deriveStoryShape({
  * module header's non-negotiables.
  *
  * @param {{ storyCount?: unknown }} [args] `storyCount` is the number of
- *   Stories the invoking `/deliver` run resolved. Omitted (or not exactly 1)
+ *   Stories the invoking `/mandrel-deliver` run resolved. Omitted (or not exactly 1)
  *   means the run cannot be shown sibling-free and therefore dispatches as a
  *   sub-agent — never an assumed 1.
  * @returns {{ mode: 'inline'|'subagent', reasons: string[] }}

package/.agents/scripts/lib/orchestration/deliver-recover.js

@@ -21,7 +21,7 @@
  *   - `closing` with a red PR → enter the fix loop. Waiting is pointless; no
  *     budget turns a failed check green.
  *   - `closing` with a MERGED PR → run confirm. **This is the strand a
- *     `/deliver` re-run refuses outright**, because `single-story-init.js`
+ *     `/mandrel-deliver` re-run refuses outright**, because `single-story-init.js`
  *     hard-errors on an already-closed Story — so before this surface, the
  *     merged-but-label-stale Story had no automated way back.
  *   - `done` with a drifted board → run resync. The GitHub Projects bot won
@@ -367,7 +367,7 @@ export function decideRecovery({
       nextCommand: NEXT_COMMANDS.confirmMerge(storyId),
       detail:
         `PR #${pr.number} is MERGED but the Story is at \`${label ?? 'no state label'}\`. ` +
-        `A /deliver re-run cannot fix this — single-story-init.js hard-errors on an ` +
+        `A /mandrel-deliver re-run cannot fix this — single-story-init.js hard-errors on an ` +
         `already-closed Story. The confirm CLI is idempotent and flips the label from ` +
         `the already-merged PR, then runs the land tail.`,
       evidence,
@@ -482,7 +482,7 @@ export function decideRecovery({
     nextCommand: NEXT_COMMANDS.close(storyId),
     detail:
       `Story is at \`${label ?? 'no agent:: state label'}\` — not mid-delivery, so there ` +
-      `is no strand to recover. Deliver it normally via /deliver ${storyId}.`,
+      `is no strand to recover. Deliver it normally via /mandrel-deliver ${storyId}.`,
     evidence,
   };
 }

package/.agents/scripts/lib/orchestration/docs-digest.js

@@ -1,7 +1,7 @@
 /**
  * docs-digest.js — per-run docs digest builder (Story #4338).
  *
- * `/deliver` story sub-agents previously re-read every file in
+ * `/mandrel-deliver` story sub-agents previously re-read every file in
  * `project.docsContextFiles` on every Story, re-paying the full docs payload
  * per child. This module produces a single **digest** — one compact markdown
  * outline per configured doc — that the parent threads into every child prompt
@@ -17,7 +17,7 @@
  * generate-and-write export so the planner-context surface
  * (`plan-context.js` / `authoring-context.js`) can produce a session docs
  * digest without duplicating the mkdir+writeFile plumbing shared by
- * `plan-context.js` / `authoring-context.js` and the `/deliver` workflow.
+ * `plan-context.js` / `authoring-context.js` and the `/mandrel-deliver` workflow.
  */
 
 import fs from 'node:fs';
@@ -145,7 +145,7 @@ export async function buildDocsDigest({ docsContextFiles, docsRoot } = {}) {
  * Build the docs digest and write it to `outputPath`, returning `null` (no
  * write) when there is nothing to digest. This is the single shared
  * generate-and-persist export both digest producers call: the per-run
- * `/deliver` docs digest (`helpers/deliver-story.md`) and the planner-
+ * `/mandrel-deliver` docs digest (`helpers/deliver-story.md`) and the planner-
  * context digest (`plan-context.js` → `authoring-context.js`, Story
  * #4433). Callers own path construction (temp-root layout, run id, etc.)
  * so both surfaces can keep — or deliberately share — their own convention;

package/.agents/scripts/lib/orchestration/lease-guard-shared.js

@@ -3,7 +3,7 @@
  * kernel shared by the three per-surface lease guards.
  *
  * The per-surface lease guards — today `single-story-lease-guard.js`;
- * historically also the retired Epic-tier deliver/plan guards —
+ * historically also the retired Epic-tier deliver/mandrel-plan guards —
  * each carried their own copy of
  * the operator-handle resolution and the fail-closed acquire wrapper around
  * `ticket-lease.acquireLease` (refuse any foreign assignee, throwing an
@@ -20,7 +20,7 @@
  *
  *   - **Operator candidates** — each surface supplies its own ordered
  *     candidate list (e.g. `--as` flag → `github.operatorHandle` →
- *     `git user.email` for `/deliver`; bare `operatorHandle` for the
+ *     `git user.email` for `/mandrel-deliver`; bare `operatorHandle` for the
  *     plan/standalone paths).
  *   - **Missing-handle behaviour** — `'null'` (return null; the caller fails
  *     closed at acquire time) vs `'throw'` (refuse immediately with surface

package/.agents/scripts/lib/orchestration/light-backstop.js

@@ -71,7 +71,7 @@ function runDiffBackstop({
  *
  * A refusal also **preserves** the work before it reports (Story #4875): the
  * implementation is finished and the recycle command hands the receipt to
- * `/plan`, so leaving it on an untracked local branch that routine cleanup may
+ * `/mandrel-plan`, so leaving it on an untracked local branch that routine cleanup may
  * reap is not an acceptable end state. Preservation is best-effort and its
  * outcome is reported either way — a failed push degrades the message, never
  * the verdict or the exit code.

package/.agents/scripts/lib/orchestration/light-escalation.js

@@ -7,9 +7,9 @@
  * {@link module:lib/orchestration/light-suitability}:
  *
  *   1. **Recycling the receipt.** A blocked diff backstop used to tell the
- *      operator to "escalate to `/plan`", which authored a brand-new Story and
+ *      operator to "escalate to `/mandrel-plan`", which authored a brand-new Story and
  *      left the receipt open with no successor — orphaning its branch, its
- *      worktree, and a finished implementation. Naming the receipt as `/plan`'s
+ *      worktree, and a finished implementation. Naming the receipt as `/mandrel-plan`'s
  *      *input* recycles it instead: tickets mode already fetches a ticket,
  *      rewrites it into properly-planned Stories, and closes the source as
  *      superseded.
@@ -45,13 +45,13 @@ import {
 } from '../observability/runtime-friction.js';
 
 /**
- * The `/plan` invocation that owns a Story the light path could not land.
+ * The `/mandrel-plan` invocation that owns a Story the light path could not land.
  *
  * @param {number} storyId
  * @returns {string}
  */
 function buildRecycleCommand(storyId) {
-  return `/plan ${storyId}`;
+  return `/mandrel-plan ${storyId}`;
 }
 
 /**
@@ -106,7 +106,7 @@ export async function recordGateRefusal({
 
 /**
  * Handle a blocked diff backstop: record the refusal as friction and return the
- * `/plan` invocation that recycles the receipt.
+ * `/mandrel-plan` invocation that recycles the receipt.
  *
  * Lives here rather than in the CLI so the shell stays a shell — the backstop
  * mode's job is to branch and print, not to decide what a refusal means.
@@ -152,7 +152,7 @@ export async function handleBlockedBackstop({
  * recoverable (Story #4875).
  *
  * A blocked backstop refuses the *land*, not the *work*: the implementation is
- * complete and the recycle command hands the receipt to `/plan`, which will
+ * complete and the recycle command hands the receipt to `/mandrel-plan`, which will
  * want it. Before this, that work existed only as a local `story-<id>` branch
  * with no remote ref — an untracked branch is exactly what the routine merged-
  * branch sweeps and worktree reaping treat as disposable, so the only copy of a