mandrel 2.37.0 → 2.39.0

package/.agents/scripts/lib/qa/resolve-qa-contract.js

@@ -26,11 +26,25 @@
  * harness invocation — by exact name or by raw-URL origin match against each
  * environment's `baseUrl` — and throws loudly (naming the known environments)
  * on an unknown name or unmatched URL.
+ *
+ * It also **resolves the selected environment's `signInSeam`** (Story #5135).
+ * A `{ skill }` seam naming an id that resolves to no readable `SKILL.md`
+ * under either skills root used to fail silently: the contract validated, the
+ * seam was returned unread, and the dangling pointer only surfaced much later
+ * when a sweep reached its sign-in step — after the harness had already
+ * driven a browser. Resolution now happens here, at config-resolution time,
+ * so the failure lands where the operator can fix `.agentrc.json`. A seam
+ * that is absent entirely is a legitimate, declarable state (the workflows
+ * drive the unauthenticated surface and record the gap), not an error.
  */
 
 import Ajv from 'ajv';
-
 import { QA_SCHEMA } from '../config-settings-schema.js';
+import { PROJECT_ROOT } from '../project-root.js';
+import {
+  resolveSkillFile,
+  SKILL_SEARCH_ROOTS,
+} from '../skills/walk-skill-files.js';
 
 /**
  * The harness-required fields. The AJV `QA_SCHEMA` keeps these optional so
@@ -242,6 +256,40 @@ function toOrigin(value) {
   }
 }
 
+/**
+ * Normalize and verify one environment's `signInSeam`.
+ *
+ * An absent seam normalizes to `null` — a declarable state, not an error.
+ * A `{ skill }` seam is resolved against both skills roots and throws when
+ * it resolves under neither, so a dangling pointer is caught here rather
+ * than mid-sweep. The resolved `SKILL.md` path is attached as
+ * `skillPath` so the harness reads the file the check actually found.
+ *
+ * @param {object | undefined} seam
+ * @param {string} envName Environment name, for the error message.
+ * @param {{ repoRoot?: string }} options
+ * @returns {object | null}
+ */
+function resolveSignInSeam(seam, envName, options) {
+  if (seam == null) return null;
+  if (typeof seam.skill !== 'string') return seam;
+
+  const repoRoot = options.repoRoot ?? PROJECT_ROOT;
+  const found = resolveSkillFile(repoRoot, seam.skill);
+  if (found === null) {
+    throw new Error(
+      `qa: environment \`${envName}\` declares signInSeam.skill ` +
+        `\`${seam.skill}\`, which resolves to no readable SKILL.md. ` +
+        `Searched ${SKILL_SEARCH_ROOTS.map((r) => `\`${r}/<skill>/SKILL.md\``).join(' and ')}. ` +
+        'Author the skill under the consumer-writable `.agents/local/skills/` ' +
+        'zone (it is never pruned by `mandrel sync` and never flagged as ' +
+        'payload drift), correct the id, or omit `signInSeam` entirely if ' +
+        'this target genuinely has no sign-in seam.',
+    );
+  }
+  return { ...seam, skillPath: found.path };
+}
+
 /**
  * Resolve a single QA environment for one harness invocation.
  *
@@ -262,13 +310,17 @@ function toOrigin(value) {
  * Fails **loudly**: an unknown name or an unmatched URL throws an error that
  * names the known environments so the operator can correct the invocation.
  *
- * @param {{ environments: Record<string, { baseUrl: string, signInSeam: object, allowWrites?: boolean }>, defaultEnvironment: string }} contract
+ * @param {{ environments: Record<string, { baseUrl: string, signInSeam?: object, allowWrites?: boolean }>, defaultEnvironment: string }} contract
  *   A contract returned by `resolveQaContract`.
  * @param {string} [target] Environment name or raw URL. Omit for the default.
- * @returns {{ name: string, baseUrl: string, signInSeam: object, allowWrites: boolean }}
- * @throws {Error} on an unknown name or unmatched URL.
+ * @param {{ repoRoot?: string }} [options] `repoRoot` roots skill-seam
+ *   resolution; defaults to the project root. Injected by tests.
+ * @returns {{ name: string, baseUrl: string, signInSeam: object | null, allowWrites: boolean }}
+ *   `signInSeam` is `null` when the environment declares none.
+ * @throws {Error} on an unknown name, an unmatched URL, or a `{ skill }` seam
+ *   that resolves under no skills root.
  */
-export function resolveQaEnvironment(contract, target) {
+export function resolveQaEnvironment(contract, target, options = {}) {
   const environments = contract?.environments;
   if (
     environments == null ||
@@ -320,7 +372,7 @@ export function resolveQaEnvironment(contract, target) {
   return {
     name: resolvedName,
     baseUrl: env.baseUrl,
-    signInSeam: env.signInSeam,
+    signInSeam: resolveSignInSeam(env.signInSeam, resolvedName, options),
     allowWrites,
   };
 }

package/.agents/scripts/lib/signals/schema.js

@@ -91,7 +91,7 @@ export const EVENT_KINDS = Object.freeze({
   // Story #3819 — per-criterion acceptance self-eval signal emitted by
   // acceptance-eval.js. One record per Story per eval-loop terminus,
   // carrying which acceptance items needed rework and the round count, so
-  // the retro and /plan Phase 0 feedback fetch can see acceptance
+  // the retro and /mandrel-plan Phase 0 feedback fetch can see acceptance
   // churn alongside friction/hotspot data.
   ACCEPTANCE_EVAL: 'acceptance-eval',
   // Forensic breadcrumb appended to the per-Epic stream by the notify

package/.agents/scripts/lib/skills/skills-index.js

@@ -0,0 +1,168 @@
+// .agents/scripts/lib/skills/skills-index.js
+//
+// Shared I/O for the two skills manifests (Story #5135).
+//
+// Each skills root carries its own `skills.index.json`: the package payload's
+// at `.agents/skills/`, and the consumer-writable zone's at
+// `.agents/local/skills/`. The shipped one is a committed payload file that
+// `mandrel doctor` / `mandrel sync-agents` compare byte-for-byte against the
+// installed package, so the two manifests must never be merged — but they are
+// read, compared and reported identically, and both CLIs need that logic.
+// Before this module `generate-skills-index.js` and `validate-skills.js`
+// each carried their own near-identical reader.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Manifest filename, shared by both roots. */
+export const INDEX_FILENAME = 'skills.index.json';
+
+/**
+ * Absolute path of the manifest for one skills root.
+ *
+ * @param {string} repoRoot
+ * @param {readonly string[]} rootSegments From `walk-skill-files.js`.
+ * @returns {string}
+ */
+export function indexPathFor(repoRoot, rootSegments) {
+  return path.join(repoRoot, ...rootSegments, INDEX_FILENAME);
+}
+
+/**
+ * Read a manifest from disk. Distinguishes "missing" from "unparseable" via
+ * the `reason` channel so callers can report which drift they hit rather than
+ * collapsing both into "not fresh".
+ *
+ * @param {string} indexPath
+ * @returns {{ manifest: object | null, reason: string | null }}
+ */
+export function readManifest(indexPath) {
+  if (!fs.existsSync(indexPath)) {
+    return { manifest: null, reason: 'missing' };
+  }
+  let src;
+  try {
+    src = fs.readFileSync(indexPath, 'utf8');
+  } catch (err) {
+    return { manifest: null, reason: `read-error: ${err.message}` };
+  }
+  try {
+    return { manifest: JSON.parse(src), reason: null };
+  } catch (err) {
+    return { manifest: null, reason: `parse-error: ${err.message}` };
+  }
+}
+
+/**
+ * Read a manifest and project its entry paths into a Set, the shape the
+ * validator's membership check consumes.
+ *
+ * @param {string} indexPath
+ * @returns {{ exists: boolean, paths: Set<string> | null, manifest: object | null, indexPath: string, parseError?: string }}
+ */
+export function readIndexPaths(indexPath) {
+  const { manifest, reason } = readManifest(indexPath);
+  if (reason === 'missing') {
+    return { exists: false, paths: null, manifest: null, indexPath };
+  }
+  if (manifest === null) {
+    return {
+      exists: true,
+      paths: null,
+      manifest: null,
+      indexPath,
+      parseError: reason,
+    };
+  }
+  const paths = new Set(
+    Array.isArray(manifest.skills)
+      ? manifest.skills.map((s) => s.path).filter((p) => typeof p === 'string')
+      : [],
+  );
+  return { exists: true, paths, manifest, indexPath };
+}
+
+/**
+ * Compare two manifests ignoring `generatedAt` — the one volatile field, which
+ * changes on every write and is not content. Returns null when they match, or
+ * a diff-style message naming the entry counts.
+ *
+ * @param {object | null} diskManifest
+ * @param {object} freshManifest
+ * @param {string} label Manifest name for the message.
+ * @returns {string | null}
+ */
+export function diffManifests(diskManifest, freshManifest, label) {
+  if (diskManifest === null) {
+    return `${label}: on-disk manifest is missing or unreadable`;
+  }
+  const a = { ...diskManifest };
+  const b = { ...freshManifest };
+  a.generatedAt = undefined;
+  b.generatedAt = undefined;
+  if (JSON.stringify(a) === JSON.stringify(b)) return null;
+  const count = (m) => (Array.isArray(m.skills) ? m.skills.length : 'n/a');
+  return [
+    `${label} drift detected:`,
+    `  on-disk entries:  ${count(diskManifest)}`,
+    `  generated entries: ${count(freshManifest)}`,
+    "  run 'node .agents/scripts/generate-skills-index.js' to refresh",
+  ].join('\n');
+}
+
+/**
+ * Render a manifest's schema violations as field-named findings. The compiled
+ * AJV validator is passed in so this module stays free of the schema-loading
+ * side effects the validator CLI owns.
+ *
+ * @param {object} manifest
+ * @param {string} indexRelPath Repo-relative manifest path, for the message.
+ * @param {(m: object) => boolean} validateManifest Compiled AJV validator.
+ * @returns {string[]}
+ */
+function validateManifestSchema(manifest, indexRelPath, validateManifest) {
+  const findings = [];
+  if (validateManifest(manifest)) return findings;
+  for (const err of validateManifest.errors ?? []) {
+    const where = err.instancePath || '(root)';
+    findings.push(
+      `${indexRelPath}: manifest-schema: schema violation at ${where}: ${err.message}`,
+    );
+  }
+  return findings;
+}
+
+/**
+ * Audit one root's manifest: present, parseable, and schema-valid. Shared by
+ * both skills roots so a consumer-authored index is held to the same bar as
+ * the shipped one.
+ *
+ * @param {{ exists: boolean, paths: Set<string> | null, manifest: object | null, parseError?: string }} indexInfo
+ * @param {string} indexRelPath
+ * @param {(m: object) => boolean} validateManifest
+ * @param {{ required: boolean }} options
+ * @returns {string[]}
+ */
+export function auditIndex(
+  indexInfo,
+  indexRelPath,
+  validateManifest,
+  { required },
+) {
+  if (!indexInfo.exists) {
+    return required
+      ? [
+          `index missing: ${indexRelPath} not found — run 'node .agents/scripts/generate-skills-index.js'`,
+        ]
+      : [];
+  }
+  if (indexInfo.paths === null) {
+    return [`index unparseable: ${indexRelPath} — ${indexInfo.parseError}`];
+  }
+  if (indexInfo.manifest === null) return [];
+  return validateManifestSchema(
+    indexInfo.manifest,
+    indexRelPath,
+    validateManifest,
+  );
+}

package/.agents/scripts/lib/skills/walk-skill-files.js

@@ -1,12 +1,56 @@
 // .agents/scripts/lib/skills/walk-skill-files.js
 //
-// Shared traversal for SKILL.md files under `.agents/skills/{core,stack}/`.
+// Shared traversal for SKILL.md files across the two skills roots:
+// the package payload (`.agents/skills/{core,stack}/`) and the
+// consumer-writable local zone (`.agents/local/skills/{core,stack}/`).
 // Used by validate-skills.js and generate-skills-index.js so both CLIs
 // enumerate the same paths in the same deterministic order.
+//
+// The two roots stay **separately enumerable** on purpose (Story #5135).
+// `.agents/skills/skills.index.json` is a committed payload file that
+// `mandrel doctor` / `mandrel sync-agents` compare byte-for-byte against
+// the installed package; folding a consumer's local skills into it would
+// make every consumer's regenerated index read as payload drift and cause
+// those commands to refuse. The local zone therefore carries its own
+// index artifact, and the two roots are unified only at *lookup* time, by
+// `resolveSkillFile` — never for the shipped manifest.
 
 import fs from 'node:fs';
 import path from 'node:path';
 
+/** Tier directories a skills root is enumerated under. */
+const TIERS = Object.freeze(['core', 'stack']);
+
+/**
+ * Path segments (from the repo root) of the package-payload skills root.
+ * Materialized by `mandrel sync`; every file under it is payload.
+ */
+export const PAYLOAD_SKILLS_SEGMENTS = Object.freeze(['.agents', 'skills']);
+
+/**
+ * Path segments (from the repo root) of the consumer-writable skills root.
+ * It sits inside the `.agents/local/` zone (Story #3498), which sync never
+ * copies into and never prunes, and which the agents-drift check cannot
+ * flag because that check only walks files present in the package payload.
+ */
+export const LOCAL_SKILLS_SEGMENTS = Object.freeze([
+  '.agents',
+  'local',
+  'skills',
+]);
+
+/**
+ * A skill id is the tier-relative path naming a skill — e.g.
+ * `core/scope-triage` or `stack/qa/playwright`. It is the value that
+ * appears in `skills.index.json` minus the root prefix, and the value a
+ * `qa.environments.*.signInSeam.skill` seam carries.
+ *
+ * The pattern is deliberately strict: ids resolve to filesystem paths, so
+ * anything that could escape a root (`..`, absolute paths, backslashes) or
+ * smuggle a shell metacharacter is rejected rather than normalized.
+ */
+const SKILL_ID_RE = /^[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._-]*)+$/;
+
 /**
  * Recursively enumerate `SKILL.md` paths under a directory.
  *
@@ -38,19 +82,99 @@ function walkSkillFiles(rootDir) {
 }
 
 /**
- * Build the list of SKILL.md files under `<repoRoot>/.agents/skills/{core,
- * stack}/`, sorted by POSIX repo-relative path for deterministic output.
+ * Sort absolute paths by their POSIX repo-relative form so output order is
+ * deterministic across platforms.
  *
+ * @param {string[]} files
  * @param {string} repoRoot
- * @returns {string[]} absolute paths
+ * @returns {string[]}
  */
-export function collectSkillFiles(repoRoot) {
-  const skillsRoot = path.join(repoRoot, '.agents', 'skills');
-  const coreFiles = walkSkillFiles(path.join(skillsRoot, 'core'));
-  const stackFiles = walkSkillFiles(path.join(skillsRoot, 'stack'));
-  return [...coreFiles, ...stackFiles].sort((a, b) => {
+function sortByRepoRelative(files, repoRoot) {
+  return [...files].sort((a, b) => {
     const ra = path.relative(repoRoot, a).split(path.sep).join('/');
     const rb = path.relative(repoRoot, b).split(path.sep).join('/');
     return ra < rb ? -1 : ra > rb ? 1 : 0;
   });
 }
+
+/**
+ * Enumerate the `SKILL.md` files under one skills root, sorted by POSIX
+ * repo-relative path.
+ *
+ * @param {string} repoRoot
+ * @param {readonly string[]} rootSegments One of the exported segment lists.
+ * @returns {string[]} absolute paths
+ */
+function collectUnderRoot(repoRoot, rootSegments) {
+  const skillsRoot = path.join(repoRoot, ...rootSegments);
+  const files = TIERS.flatMap((tier) =>
+    walkSkillFiles(path.join(skillsRoot, tier)),
+  );
+  return sortByRepoRelative(files, repoRoot);
+}
+
+/**
+ * Build the list of payload SKILL.md files under
+ * `<repoRoot>/.agents/skills/{core,stack}/`.
+ *
+ * This is the set the **shipped** `skills.index.json` is generated from —
+ * it must never include local-zone skills (see the module header).
+ *
+ * @param {string} repoRoot
+ * @returns {string[]} absolute paths
+ */
+export function collectSkillFiles(repoRoot) {
+  return collectUnderRoot(repoRoot, PAYLOAD_SKILLS_SEGMENTS);
+}
+
+/**
+ * Build the list of consumer-authored SKILL.md files under
+ * `<repoRoot>/.agents/local/skills/{core,stack}/`. Empty when the
+ * consumer has authored none — the common case, and the case in this
+ * repository itself.
+ *
+ * @param {string} repoRoot
+ * @returns {string[]} absolute paths
+ */
+export function collectLocalSkillFiles(repoRoot) {
+  return collectUnderRoot(repoRoot, LOCAL_SKILLS_SEGMENTS);
+}
+
+/**
+ * Resolve a skill id to a readable `SKILL.md`, searching the payload root
+ * first and the local zone second (payload-wins, matching
+ * {@link collectAllSkillFiles}).
+ *
+ * Returns `null` rather than throwing so callers own the error message —
+ * a config resolver wants to name the offending config key, a workflow
+ * wants to name the seam.
+ *
+ * @param {string} repoRoot
+ * @param {string} skillId Tier-relative id, e.g. `stack/qa/acme-sso`.
+ * @returns {{ path: string, root: string } | null} absolute `SKILL.md`
+ *   path and the POSIX repo-relative root it resolved under.
+ */
+export function resolveSkillFile(repoRoot, skillId) {
+  if (typeof skillId !== 'string' || !SKILL_ID_RE.test(skillId)) return null;
+  for (const segments of [PAYLOAD_SKILLS_SEGMENTS, LOCAL_SKILLS_SEGMENTS]) {
+    const candidate = path.join(repoRoot, ...segments, skillId, 'SKILL.md');
+    try {
+      if (fs.statSync(candidate).isFile()) {
+        return { path: candidate, root: segments.join('/') };
+      }
+    } catch {
+      // Unreadable or absent — try the next root.
+    }
+  }
+  return null;
+}
+
+/**
+ * The POSIX repo-relative skills roots, in search order. Exported so error
+ * messages can name exactly what was searched rather than restating the
+ * paths as literals.
+ */
+export const SKILL_SEARCH_ROOTS = Object.freeze([
+  PAYLOAD_SKILLS_SEGMENTS.join('/'),
+  LOCAL_SKILLS_SEGMENTS.join('/'),
+]);

package/.agents/scripts/lib/story-adjacency.js

@@ -1,7 +1,7 @@
 /**
  * lib/story-adjacency.js — the single story-level adjacency builder.
  *
- * Both pre-v2 Epic wave wrappers and the v2 `/deliver` ready-set path bottom out in the shared
+ * Both pre-v2 Epic wave wrappers and the v2 `/mandrel-deliver` ready-set path bottom out in the shared
  * `lib/Graph.js` kernel (`detectCycle` / `assignLayers` / `computeWaves`),
  * but each historically re-implemented the step that turns a list of Story
  * records into the `Map<storyId, number[]>` adjacency the kernel consumes.
@@ -43,7 +43,7 @@ import { parseBlockedBy } from './dependency-parser.js';
  *   DAG nodes).
  * @param {object} [opts]
  * @param {boolean} [opts.dropForeign=false] When `false` (the v2 default,
- *   matching the `/deliver` path — `stories-wave-tick.js` and the
+ *   matching the `/mandrel-deliver` path — `stories-wave-tick.js` and the
  *   `planReadySet` core), the operator-DAG contract is preserved: a
  *   dependency on an id absent from the input is treated as not-yet-done
  *   and withholds the dependent until it completes. When `true` (the

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -21,7 +21,7 @@ import { BODY_FORMAT_LINTS } from '../story-body/body-format-lints.js';
  *
  * **Single source of the prompt body (Story #4162).** This module is the sole
  * carrier of the full decomposer system-prompt body, delivered to the host
- * LLM in the `systemPrompts.decompose` field of the `/plan` context envelope
+ * LLM in the `systemPrompts.decompose` field of the `/mandrel-plan` context envelope
  * (via `lib/orchestration/planning/decomposer-context.js`), so no second
  * verbatim copy can drift.
  */

package/.agents/scripts/lib/ticket-body-sections.js

@@ -12,7 +12,7 @@
  * Section-scoped writes are the load-bearing contract (extending the
  * single-writer discipline #4303 established for the body trailer):
  *
- *   - The `/plan` persist path upserts the `techSpec` and `acceptanceTable`
+ *   - The `/mandrel-plan` persist path upserts the `techSpec` and `acceptanceTable`
  *     regions.
  *   - The close-time acceptance reconciler
  *     (`acceptance-spec-reconciler.js`) reads and rewrites the

package/.agents/scripts/lib/util/concurrent-map.js

@@ -16,7 +16,7 @@
 /**
  * The one bound every independent-write fan-out over the GitHub API uses
  * (Story #4952 raised those loops off serial; Story #4961 made this the single
- * owner of the number they share). Imported by the `/plan` context gathers,
+ * owner of the number they share). Imported by the `/mandrel-plan` context gathers,
  * the persist checkpoint fan-out, the `agent::ready` flips and the supersede
  * close loop, so re-tuning the policy is one edit rather than six.
  *

package/.agents/scripts/lib/util/parse-id-list.js

@@ -2,7 +2,7 @@
  * parse-id-list — expand a Story-id list that may contain dash ranges.
  *
  * Operators name a contiguous span of Stories the way they read one — as a
- * range: `/deliver 4922 - 4926`. Enumerating it by hand is the kind of
+ * range: `/mandrel-deliver 4922 - 4926`. Enumerating it by hand is the kind of
  * transcription step that silently drops or invents an id, so the range is a
  * first-class shape of every delivery id list rather than something the host
  * expands from prose.

package/.agents/scripts/lib/wave-runner/live-probe.js

@@ -7,7 +7,7 @@
  * in-flight count, and it decides. Until now the only adapter was the
  * flag-driven one (`stories-wave-tick.js --dag/--done/--in-flight`), which
  * pushed the *gathering* of those inputs onto the caller — in practice onto
- * the host LLM following `/deliver`'s prose, re-seeding `--done` and counting
+ * the host LLM following `/mandrel-deliver`'s prose, re-seeding `--done` and counting
  * `--in-flight` by hand every beat. That is hand-maintained accounting on the
  * one correctness-critical path where a mistake silently wedges a run (a
  * dropped foreign blocker) or double-dispatches a Story (a miscounted slot).
@@ -47,7 +47,7 @@
  * The graph resolution is **not** reimplemented here — it reuses
  * `resolve-stories.js`'s machinery wholesale (body `depends_on` ∪ native
  * `blocked_by` edges, foreign-blocker resolution, `files[]` footprints), so
- * the probe and `/deliver`'s step-1 resolution cannot disagree about what
+ * the probe and `/mandrel-deliver`'s step-1 resolution cannot disagree about what
  * depends on what.
  *
  * @module lib/wave-runner/live-probe
@@ -127,7 +127,7 @@ function deriveInFlightIds(storyRecords, dispatched = []) {
  * in-flight, so `detectWedge` dropped it (its "undone work with no unmet
  * blockers would have been dispatched" invariant is precisely what probe mode
  * broke) and the beat reported exit 0 / `ready: []` / `wedged: null` forever.
- * `/deliver` reads that as "waiting", so the `agent::blocked` HITL pause — the
+ * `/mandrel-deliver` reads that as "waiting", so the `agent::blocked` HITL pause — the
  * one runtime gate in the protocol — was never surfaced to the operator.
  *
  * @param {Array<{id?: number, number?: number, labels?: string[], state?: string}>} storyRecords
@@ -193,7 +193,7 @@ function deriveForeignHeld(storyRecords, self, warn) {
  * Resolve the provider + repo coordinates the probe reads through.
  *
  * Shares `resolve-stories.js`'s provider seam, so probe mode authenticates and
- * targets exactly the same repo `/deliver`'s resolution step does. Tests
+ * targets exactly the same repo `/mandrel-deliver`'s resolution step does. Tests
  * inject a stub provider instead of calling this.
  *
  * @param {object} [deps]

package/.agents/scripts/lib/wave-runner/ready-set.js

@@ -2,7 +2,7 @@
  * lib/wave-runner/ready-set.js — the path-agnostic ready-set scheduling
  * core.
  *
- * This module is the scheduling kernel the v2 `/deliver` multi-Story path
+ * This module is the scheduling kernel the v2 `/mandrel-deliver` multi-Story path
  * dispatches through (`stories-wave-tick.js`). It replaces wave-*batch* selection
  * (group N must fully drain before group N+1 opens) with *continuous*,
  * dependency-driven selection: a Story becomes dispatchable the instant

package/.agents/scripts/lib/workflow-closure.js

@@ -345,7 +345,7 @@ function loadDocs(root, fs) {
  * (`helpers/deliver-story.md` → `# /deliver-story …`). The self-naming test is
  * what separates an invocable helper from an appendix that merely titles itself
  * after the command it documents (`helpers/deliver-reference.md` →
- * `# /deliver — reference appendix`), which is read on demand, never invoked.
+ * `# /mandrel-deliver — reference appendix`), which is read on demand, never invoked.
  *
  * @param {WorkflowDoc} doc
  * @returns {boolean}

package/.agents/scripts/lib/worktree/lifecycle/pending-cleanup.js

@@ -7,7 +7,7 @@
  * on a Windows lock-class failure, the entry is appended to
  * `.worktrees/.pending-cleanup.json`. The plan-time `worktree-sweep.js`
  * reader (shipped in Epic #349) picks up the manifest on the next
- * `/plan` run and retries removal
+ * `/mandrel-plan` run and retries removal
  * (`git worktree remove` then `fs.rm`) — by then the live file handles from Node / AV / the Windows
  * Search indexer are almost always gone. If `MAX_SWEEP_ATTEMPTS` elapses
  * without clearing, an `OPERATOR ACTION REQUIRED: persistent-lock` line
@@ -17,7 +17,7 @@
  * git-ignored; no tracked state is mutated.
  *
  * **Story #5112 — the manifest is shared mutable state.** `recordPendingCleanup`
- * runs from the close reap and `drainPendingCleanup` runs from the `/plan`
+ * runs from the close reap and `drainPendingCleanup` runs from the `/mandrel-plan`
  * boot, so two concurrent delivery sessions can read-modify-write the same
  * file. Three properties close that:
  *

package/.agents/scripts/lint-issue-body.js

@@ -10,8 +10,8 @@
  * human files a ticket whose body `parse()` rejects (or which lacks the
  * binding `goal` / `acceptance` / `verify` sections), the lint surfaces a
  * **comment** on the issue rather than failing silently — the supported
- * human entry points (`/plan` from an existing Epic ID, the qa-assist →
- * `/plan` handoff) depend on a parseable body.
+ * human entry points (`/mandrel-plan` from an existing Epic ID, the qa-assist →
+ * `/mandrel-plan` handoff) depend on a parseable body.
  *
  * ## Design
  *
@@ -157,7 +157,7 @@ export function renderConformanceComment(verdict) {
     '### ⚠️ Ticket body does not round-trip through the Mandrel parser',
     '',
     'Agents build ticket bodies from a canonical schema that this body does ' +
-      'not match, so the supported human entry points (e.g. `/plan` from an ' +
+      'not match, so the supported human entry points (e.g. `/mandrel-plan` from an ' +
       'existing Epic ID) will reject it. Please fix the following:',
     '',
     ...verdict.problems.map((p) => `- ${p}`),

package/.agents/scripts/plan-context.js

@@ -2,9 +2,9 @@
 /* node:coverage ignore file */
 
 /**
- * plan-context.js — step 1 of the collapsed `/plan` pipeline.
+ * plan-context.js — step 1 of the collapsed `/mandrel-plan` pipeline.
  *
- * Emits one stdout-pure JSON envelope for the `/plan` authoring middle.
+ * Emits one stdout-pure JSON envelope for the `/mandrel-plan` authoring middle.
  *
  * Two operator modes (exactly one is required):
  *
@@ -25,7 +25,7 @@
  *
  * Flags:
  *   --out <path>     Write the envelope to <path> (parent dirs created).
- *                    `/plan` points this at `<plan-dir>/plan-context.json`,
+ *                    `/mandrel-plan` points this at `<plan-dir>/plan-context.json`,
  *                    which is where `plan-persist.js` auto-discovers the
  *                    `--tickets` source ids from (Story #4554). Without a
  *                    captured envelope persist cannot know a `--tickets` run
@@ -348,7 +348,7 @@ runAsCli(import.meta.url, main, {
     invocation:
       'node .agents/scripts/plan-context.js (--seed "<text>" | --seed-file <path> | --tickets <ids> | --amends <id>) [--out <path>] [--pretty]',
     summary:
-      'Build the /plan authoring-context envelope on stdout. Exactly one entry form must be supplied.',
+      'Build the /mandrel-plan authoring-context envelope on stdout. Exactly one entry form must be supplied.',
     flags: [
       ['--seed "<text>"', 'Inline seed prose.'],
       ['--seed-file <path>', 'Seed document to read.'],

package/.agents/scripts/plan-critics.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 /**
- * plan-critics.js — the /plan critic-dispatch verdict CLI (Story #4592).
+ * plan-critics.js — the /mandrel-plan critic-dispatch verdict CLI (Story #4592).
  *
- * `/plan` step 2.5 (between Author and Persist) runs this against the draft
+ * `/mandrel-plan` step 2.5 (between Author and Persist) runs this against the draft
  * `stories.json`. It evaluates the consolidation + pre-mortem dispatch
  * conditions and prints the verdict as JSON on stdout so the workflow can
  * act on it — dispatching a fresh-context critic sub-agent and folding its

package/.agents/scripts/plan-persist.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * plan-persist.js — flat Story GitHub-write surface for v2 `/plan`
+ * plan-persist.js — flat Story GitHub-write surface for v2 `/mandrel-plan`
  * (Stage 3 — `docs/roadmap.md`).
  *
  * Given the author-written planning artifacts (`stories.json`, optional shared
@@ -201,7 +201,7 @@ async function loadArtifacts(paths) {
  *
  * Exported for tests: this is the join where the envelope-derived source ids
  * meet the persist engine, so a regression here silently un-wires
- * `/plan --tickets` superseding (Story #4554).
+ * `/mandrel-plan --tickets` superseding (Story #4554).
  *
  * @param {object} values Parsed `parseArgs` values.
  * @param {ReturnType<typeof resolveInputPaths>} paths