mandrel 2.37.0 → 2.39.0

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

@@ -8,6 +8,15 @@
 // generator output (ignoring the volatile `generatedAt` field) and exits
 // non-zero with a diff-style message if they diverge.
 //
+// Two indexes, never one (Story #5135). The shipped manifest above is a
+// committed payload file that `mandrel doctor` / `mandrel sync-agents`
+// compare byte-for-byte against the installed package, so consumer-authored
+// skills under the `.agents/local/skills/` zone MUST NOT be folded into it —
+// a merged index would read as payload drift in every consumer that authored
+// a skill, and those commands would refuse. Local skills are therefore
+// indexed into their own `.agents/local/skills/skills.index.json`, inside
+// the zone sync never prunes and drift never walks.
+//
 // CLI surface:
 //
 //   node generate-skills-index.js [--check] [--root <dir>] [--out <file>]
@@ -38,7 +47,18 @@ import { runAsCli } from './lib/cli-utils.js';
 import { formatGeneratedJson } from './lib/format-generated-json.js';
 import { Logger } from './lib/Logger.js';
 import { parseSkill } from './lib/skills/parse-skill.js';
-import { collectSkillFiles } from './lib/skills/walk-skill-files.js';
+import {
+  diffManifests,
+  INDEX_FILENAME,
+  indexPathFor,
+  readManifest,
+} from './lib/skills/skills-index.js';
+import {
+  collectLocalSkillFiles,
+  collectSkillFiles,
+  LOCAL_SKILLS_SEGMENTS,
+  PAYLOAD_SKILLS_SEGMENTS,
+} from './lib/skills/walk-skill-files.js';
 
 const GENERATOR_ID = 'generate-skills-index.js@1';
 
@@ -103,8 +123,8 @@ function projectEntry(parsed) {
  * Build the manifest object (without `generatedAt`) by walking the tree
  * and projecting each parsed SKILL.md into an index entry.
  */
-export function buildManifestBody(repoRoot) {
-  const skillFiles = collectSkillFiles(repoRoot);
+export function buildManifestBody(repoRoot, collect = collectSkillFiles) {
+  const skillFiles = collect(repoRoot);
   const skills = skillFiles.map((absPath) =>
     projectEntry(parseSkill(absPath, { repoRoot })),
   );
@@ -118,8 +138,8 @@ export function buildManifestBody(repoRoot) {
  * Build the full manifest with `generatedAt`. `nowIso` is injected so
  * tests can pin the timestamp deterministically.
  */
-export function buildManifest(repoRoot, { nowIso } = {}) {
-  const body = buildManifestBody(repoRoot);
+export function buildManifest(repoRoot, { nowIso, collect } = {}) {
+  const body = buildManifestBody(repoRoot, collect);
   return {
     generatedAt: nowIso ?? new Date().toISOString(),
     generator: body.generator,
@@ -143,66 +163,147 @@ export function serializeManifest(manifest) {
 }
 
 /**
- * Read the on-disk manifest as a parsed object, or null when missing /
- * unparseable. The --check pipeline distinguishes "missing" (drift) from
- * "unparseable" (drift) via the returned `reason` channel.
+ * Resolve the manifest output path given (root, optional explicit
+ * override).
+ */
+function resolveOutPath(root, override) {
+  return override
+    ? path.resolve(override)
+    : indexPathFor(root, PAYLOAD_SKILLS_SEGMENTS);
+}
+
+/**
+ * Resolve the local-zone manifest path. Deliberately NOT overridable by
+ * `--out`: that flag redirects the payload manifest (tests stage fixture
+ * trees with it), and letting it also move the local manifest would let one
+ * invocation write both indexes to the same file.
+ */
+function resolveLocalOutPath(root) {
+  return indexPathFor(root, LOCAL_SKILLS_SEGMENTS);
+}
+
+/**
+ * Write one manifest through the project formatter so a regeneration on a
+ * clean tree leaves no format drift behind.
  */
-function readOnDiskManifest(outPath) {
-  if (!fs.existsSync(outPath)) {
-    return { manifest: null, reason: 'missing' };
+function writeManifest(manifest, outPath, root) {
+  const serialized = serializeManifest(manifest);
+  const opts = { cwd: root, filename: INDEX_FILENAME };
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(
+    outPath,
+    formatGeneratedJson(serialized, opts) ?? serialized,
+  );
+}
+
+/**
+ * Write (or reap) the local-zone manifest. A consumer who deletes their last
+ * local skill would otherwise be left with a stale index reporting skills
+ * that no longer exist, so an emptied zone removes the artifact rather than
+ * leaving it behind.
+ */
+function writeLocalManifest(localFresh, localOutPath, root) {
+  const rel = path.relative(root, localOutPath).split(path.sep).join('/');
+  if (localFresh === null) {
+    if (fs.existsSync(localOutPath)) {
+      fs.rmSync(localOutPath);
+      Logger.info(`removed ${rel} (no local skills remain)`);
+    }
+    return;
   }
-  let src;
-  try {
-    src = fs.readFileSync(outPath, 'utf8');
-  } catch (err) {
-    return { manifest: null, reason: `read-error: ${err.message}` };
+  writeManifest(localFresh, localOutPath, root);
+  Logger.info(`wrote ${rel} (${localFresh.skills.length} entries)`);
+}
+
+/**
+ * Compare the local-zone manifest against fresh generator output. Returns
+ * null when in sync (including the common case of no local skills and no
+ * artifact), or a diff-style message.
+ */
+function checkLocalManifest(localFresh, localOutPath) {
+  const exists = fs.existsSync(localOutPath);
+  if (localFresh === null) {
+    return exists
+      ? 'local skills.index.json drift detected: the local skills zone is ' +
+          'empty but .agents/local/skills/skills.index.json still exists — ' +
+          "run 'node .agents/scripts/generate-skills-index.js' to reap it"
+      : null;
   }
-  try {
-    return { manifest: JSON.parse(src), reason: null };
-  } catch (err) {
-    return { manifest: null, reason: `parse-error: ${err.message}` };
+  if (!exists) {
+    return (
+      'local skills.index.json drift detected: missing — run ' +
+      "'node .agents/scripts/generate-skills-index.js' to write it"
+    );
   }
+  const { manifest: disk } = readManifest(localOutPath);
+  return diffManifests(disk, localFresh, 'local skills.index.json');
 }
 
 /**
- * Compare two manifests ignoring `generatedAt`. Returns null when they
- * match, or a short diff-style message when they diverge.
+ * Build the local zone's manifest plan for this invocation: its output path,
+ * and a fresh manifest when the consumer has authored any local skill (null
+ * otherwise, which is the signal to reap a stale artifact).
+ *
+ * Split out of `run` so the payload path and the local path each read as one
+ * step there rather than interleaving.
+ *
+ * @param {string} root
+ * @param {Date} now
+ * @returns {{ localFresh: object | null, localOutPath: string }}
  */
-function diffManifestsIgnoringTimestamp(diskManifest, freshManifest) {
-  if (diskManifest === null) {
-    return 'on-disk manifest is missing or unreadable';
-  }
-  const a = { ...diskManifest };
-  const b = { ...freshManifest };
-  delete a.generatedAt;
-  delete b.generatedAt;
-  const sa = JSON.stringify(a);
-  const sb = JSON.stringify(b);
-  if (sa === sb) return null;
-  // Surface a structural summary rather than a full JSON dump.
-  const diskCount = Array.isArray(diskManifest.skills)
-    ? diskManifest.skills.length
-    : 'n/a';
-  const freshCount = Array.isArray(freshManifest.skills)
-    ? freshManifest.skills.length
-    : 'n/a';
-  const summary = [
-    'skills.index.json drift detected:',
-    `  on-disk entries:  ${diskCount}`,
-    `  generated entries: ${freshCount}`,
-    "  run 'node .agents/scripts/generate-skills-index.js' to refresh",
-  ].join('\n');
-  return summary;
+function buildLocalPlan(root, now) {
+  const localOutPath = resolveLocalOutPath(root);
+  const localFresh =
+    collectLocalSkillFiles(root).length > 0
+      ? buildManifest(root, {
+          nowIso: now.toISOString(),
+          collect: collectLocalSkillFiles,
+        })
+      : null;
+  return { localFresh, localOutPath };
 }
 
 /**
- * Resolve the manifest output path given (root, optional explicit
- * override).
+ * Render the freshness line's entry counts, naming the local zone only when
+ * one exists.
+ *
+ * @param {object} fresh
+ * @param {object | null} localFresh
+ * @returns {string}
  */
-function resolveOutPath(root, override) {
-  return override
-    ? path.resolve(override)
-    : path.join(root, '.agents', 'skills', 'skills.index.json');
+function describeCounts(fresh, localFresh) {
+  const base = `${fresh.skills.length} entries`;
+  return localFresh === null
+    ? base
+    : `${base}, ${localFresh.skills.length} local`;
+}
+
+/**
+ * `--check` mode: compare both manifests against fresh generator output and
+ * report the first drift found, payload first.
+ *
+ * Lives outside `run` so the entry point reads as "resolve inputs, then check
+ * or write" — and so the check path's branches are not charged to a function
+ * that also owns argument resolution.
+ *
+ * @param {{ outPath: string, fresh: object, localOutPath: string, localFresh: object | null }} plan
+ * @returns {{ status: number, output: string }}
+ */
+function checkBothManifests({ outPath, fresh, localOutPath, localFresh }) {
+  const { manifest: disk, reason } = readManifest(outPath);
+  if (disk === null) {
+    return { status: 1, output: `${INDEX_FILENAME} drift detected: ${reason}` };
+  }
+  const drift =
+    diffManifests(disk, fresh, INDEX_FILENAME) ??
+    checkLocalManifest(localFresh, localOutPath);
+  if (drift !== null) {
+    return { status: 1, output: drift };
+  }
+  Logger.info(
+    `${INDEX_FILENAME} is fresh (${describeCounts(fresh, localFresh)})`,
+  );
+  return { status: 0, output: '' };
 }
 
 /**
@@ -225,35 +326,17 @@ export function run({ argv = [], now = new Date(), repoRoot } = {}) {
     : (repoRoot ?? defaultRepoRoot());
   const outPath = resolveOutPath(root, parsed.out);
   const fresh = buildManifest(root, { nowIso: now.toISOString() });
+  const { localFresh, localOutPath } = buildLocalPlan(root, now);
 
   if (parsed.check) {
-    const { manifest: disk, reason } = readOnDiskManifest(outPath);
-    if (disk === null) {
-      return {
-        status: 1,
-        output: `skills.index.json drift detected: ${reason}`,
-      };
-    }
-    const diff = diffManifestsIgnoringTimestamp(disk, fresh);
-    if (diff === null) {
-      Logger.info(
-        `skills.index.json is fresh (${fresh.skills.length} entries)`,
-      );
-      return { status: 0, output: '' };
-    }
-    return { status: 1, output: diff };
+    return checkBothManifests({ outPath, fresh, localOutPath, localFresh });
   }
 
-  const serialized = serializeManifest(fresh);
-  const opts = { cwd: root, filename: 'skills.index.json' };
-  fs.mkdirSync(path.dirname(outPath), { recursive: true });
-  fs.writeFileSync(
-    outPath,
-    formatGeneratedJson(serialized, opts) ?? serialized,
-  );
+  writeManifest(fresh, outPath, root);
   Logger.info(
     `wrote ${path.relative(root, outPath).split(path.sep).join('/')} (${fresh.skills.length} entries)`,
   );
+  writeLocalManifest(localFresh, localOutPath, root);
   return { status: 0, output: '' };
 }
 

package/.agents/scripts/generate-workflows-doc.js

@@ -93,7 +93,7 @@ export function renderWorkflowsDoc(catalog, loopCatalog = []) {
     'Every command file lives at `.agents/workflows/<name>.md` and is projected',
     'into a flat `.claude/commands/` tree by `npm run sync:commands` (kept',
     'current at install time and on every `mandrel sync`/`update`) so it shows',
-    'up as a bare `/<name>` slash command (e.g. `/deliver`). The projection',
+    'up as a bare `/<name>` slash command (e.g. `/mandrel-deliver`). The projection',
     'writes only `.claude/commands/<name>.md` — there is no plugin manifest and no',
     'marketplace listing. The commands load in every Claude Code environment.',
     '',

package/.agents/scripts/lib/audit-suite/selector.js

@@ -701,7 +701,7 @@ export function changeSetLacksSiblingTest(changedFiles) {
  *   callers MUST pass the requested Epic's own branch ref (e.g.
  *   `refs/heads/epic/<id>`) so the change set is pinned to that Epic's branch
  *   rather than whatever HEAD the shared checkout happens to sit on. Under two
- *   concurrent `/deliver` runs sharing one checkout, diffing against
+ *   concurrent `/mandrel-deliver` runs sharing one checkout, diffing against
  *   `HEAD` silently resolves the *other* Epic's change set (Story #3362). When
  *   `headRef` cannot be resolved in the repo, the selector returns a
  *   `degraded: true` envelope (or hard-fails in gate-mode) instead of diffing

package/.agents/scripts/lib/audit-to-stories/audit-label-taxonomy.js

@@ -140,7 +140,7 @@ const AUDIT_STORY_AXIS_LABELS = Object.freeze([
     name: AGENT_LABELS.READY,
     color: hex(LABEL_COLORS.AGENT),
     description:
-      'Parking state — frozen dispatch manifest exists; awaiting local /deliver',
+      'Parking state — frozen dispatch manifest exists; awaiting local /mandrel-deliver',
   },
   {
     name: RISK_LABELS.HIGH,

package/.agents/scripts/lib/audit-to-stories/build-story-body.js

@@ -292,7 +292,7 @@ export function buildStoryBody({ group, edges = [], issueByGroupKey = null }) {
   };
 
   // The `---` / `blocked by #N` footer is the canonical serializer's own, so
-  // the body round-trips through `parse()` and `/deliver`'s resolver reads the
+  // the body round-trips through `parse()` and `/mandrel-deliver`'s resolver reads the
   // ordering from the same place it reads every other Story's.
   const canonicalSections = serialize(storyBody, {
     includeFooter: storyBody.depends_on.length > 0,

package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js

@@ -1,8 +1,8 @@
 /**
  * lib/audit-to-stories/seed-from-findings.js
  *
- * Build the `/plan --seed`-shaped one-pager markdown that the audit-to-
- * stories Single-plan grouping path emits for `/plan` to consume.
+ * Build the `/mandrel-plan --seed`-shaped one-pager markdown that the audit-to-
+ * stories Single-plan grouping path emits for `/mandrel-plan` to consume.
  *
  * The seed renders the canonical one-pager sections so the authoring
  * pass can sharpen it without having to invent context:
@@ -10,7 +10,7 @@
  *   - Recommended Direction (rollup of recommendations by dimension)
  *   - Key Assumptions (carries the source-report links forward)
  *   - MVP Scope (the proposed Stories, one bullet per group)
- *   - Key Files (explicit file paths so `/plan` authoring has concrete
+ *   - Key Files (explicit file paths so `/mandrel-plan` authoring has concrete
  *     anchors)
  *   - Not Doing (out-of-scope items by convention)
  *
@@ -97,8 +97,8 @@ function formatMVPScope(groups) {
       const dims = g.dimensions.join(' / ');
       const file = g.files[0] ? ` (\`${g.files[0]}\`)` : '';
       // Carry each group's fingerprint (and location-based semantic-key)
-      // footer into the seed so a Story authored from it via `/plan` inherits
-      // the dedup identity — without this the recommended `/plan --seed-file`
+      // footer into the seed so a Story authored from it via `/mandrel-plan` inherits
+      // the dedup identity — without this the recommended `/mandrel-plan --seed-file`
       // path is invisible to the next sweep's dedup (Story #4626). The footers
       // are HTML comments, so they never render in the visible one-pager but
       // stay machine-readable for the dedup probe.

package/.agents/scripts/lib/audit-to-stories/wire-dependencies.js

@@ -17,7 +17,7 @@
  * edges**. Both halves are written:
  *
  *   1. The **body footer** (`---` / `blocked by #N`) — canonical, parsed by
- *      `/deliver`'s resolver, and the fallback when the dependencies API is
+ *      `/mandrel-deliver`'s resolver, and the fallback when the dependencies API is
  *      unavailable.
  *   2. The **native `blocked_by` relation** — visible in the GitHub UI,
  *      readable without parsing markdown, and settable by an operator later.

package/.agents/scripts/lib/bdd-runner-detect.js

@@ -13,7 +13,7 @@
  * The verification is **static**: we inspect `package.json` for a known BDD
  * runner dependency, and consult a small lookup table of which runners
  * support which pending/skip tag. We do not boot the runner. This keeps
- * `/plan` Phase 7 hermetic and offline.
+ * `/mandrel-plan` Phase 7 hermetic and offline.
  *
  * **Workspace awareness (Story #2956).** In a pnpm / npm / yarn monorepo the
  * BDD runner is rarely a root devDependency — it lives in the workspace

package/.agents/scripts/lib/bdd-scenario-budget.js

@@ -1,6 +1,6 @@
 /**
  * bdd-scenario-budget.js — envelope byte budget for the `bddScenarios`
- * `/plan` context-envelope field (Story #4977).
+ * `/mandrel-plan` context-envelope field (Story #4977).
  *
  * `bdd-scenario-scanner.js`'s `scanBddScenarios` stays a faithful, uncapped
  * index of the project's `.feature` corpus — that scan is also used

package/.agents/scripts/lib/bdd-scenario-scanner.js

@@ -1,5 +1,5 @@
 /**
- * bdd-scenario-scanner.js — Gherkin scenario index for /plan Phase 7.
+ * bdd-scenario-scanner.js — Gherkin scenario index for /mandrel-plan Phase 7.
  *
  * Story #2637 (sibling to #2636's file-assumption gate; the #2634 and #2635
  * planner-grounding siblings were retired in Story #4811). The Acceptance
@@ -8,7 +8,7 @@
  * alone — it never inspects the consumer project's existing `.feature`
  * files. Planned ACs frequently duplicate scenarios that already exist or
  * re-specify behaviour the codebase already proves; the duplication is
- * only discovered (at best) during `/deliver` or (at worst) after
+ * only discovered (at best) during `/mandrel-deliver` or (at worst) after
  * a redundant PR ships.
  *
  * `scanBddScenarios` walks every configured feature root, parses each
@@ -21,7 +21,7 @@
  * have a matching scenario.
  *
  * Determinism is load-bearing: the matcher is keyword-based, not
- * embedding-based, so re-running `/plan` against the same
+ * embedding-based, so re-running `/mandrel-plan` against the same
  * acceptance spec produces the same disposition annotations.
  */
 

package/.agents/scripts/lib/bdd-step-index.js

@@ -9,7 +9,7 @@
  *   1. **Discovery** — which files under a scope's `stepRoots` hold step
  *      definitions, and which `.feature` files sit under its `featureRoots`.
  *      Feature discovery is delegated to `listFeatureFiles` in
- *      `bdd-scenario-scanner.js` rather than copied: /plan's scenario index and
+ *      `bdd-scenario-scanner.js` rather than copied: /mandrel-plan's scenario index and
  *      this gate must agree on what counts as a feature file, and two walkers
  *      would eventually disagree.
  *   2. **Matching** — turn each definition's Cucumber expression or regular

package/.agents/scripts/lib/bootstrap/branch-protection.js

@@ -7,7 +7,7 @@
  *   - `enforce_admins: true` — admins do not bypass the prGate suite.
  *   - `required_pull_request_reviews.required_approving_review_count: 0` —
  *     CI is the gate; the operator monitors and iterates the open PR
- *     to green via `/deliver`'s Phase 7 watch loop.
+ *     to green via `/mandrel-deliver`'s Phase 7 watch loop.
  *
  * Behaviour rules
  * ---------------

package/.agents/scripts/lib/bootstrap/commit-push.js

@@ -112,8 +112,8 @@ export function buildManualInstructions({ stagePaths, baseBranch }) {
     `  git push -u origin ${baseBranch}`,
     '',
     'Story delivery runs in git worktrees that check out tracked files only,',
-    'so the .agents/ wiring MUST be committed before any /deliver or',
-    '/deliver run — otherwise the worktree has no scripts and breaks.',
+    'so the .agents/ wiring MUST be committed before any /mandrel-deliver or',
+    '/mandrel-deliver run — otherwise the worktree has no scripts and breaks.',
   ].join('\n');
 }
 

package/.agents/scripts/lib/bootstrap/issue-forms-template.js

@@ -325,7 +325,7 @@ function renderConformanceWorkflow() {
 # Generated by agents-bootstrap-github. Runs the canonical story-body parser
 # against human-opened type::story issues and comments when the
 # body does not round-trip, instead of letting the supported human entry
-# points (e.g. /plan from an existing Epic ID) fail silently later. The lint
+# points (e.g. /mandrel-plan from an existing Epic ID) fail silently later. The lint
 # informs; it never fails the issue. Re-run /agents-bootstrap-github to refresh.
 name: Issue Body Conformance
 

package/.agents/scripts/lib/changed-files.js

@@ -122,13 +122,98 @@ export function getChangedFiles({
   return parseNameOnlyStdout(res.stdout);
 }
 
+/**
+ * A full-length hex object id, as `git rev-parse` prints it. Used to reject
+ * anything that is not a resolved commit — a stubbed git interface in a test
+ * answers every `gitSpawn` with the same canned stdout, and a file list must
+ * never be mistaken for a merge head.
+ */
+const OBJECT_ID_RE = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
+
+/**
+ * Resolve the commit an in-progress merge is merging **in**, or `null` when no
+ * merge is in progress.
+ *
+ * Story #5131. `git diff --cached` with no commit argument diffs the index
+ * against `HEAD`, and during a merge `HEAD` is still the pre-merge tip — so a
+ * base-sync merge commit (`git merge --no-edit origin/<base>`, which
+ * `single-story-close`'s base-sync phase tells the operator to run by hand)
+ * put every file the base branch had landed into the staged scope. The
+ * pre-commit MI/CRAP gate then blocked the resolution commit for deltas
+ * belonging to already-landed, already-gated work, with no remedy: the preview
+ * is a delta against the baseline, not a baseline comparison, so no baseline
+ * refresh could silence it.
+ *
+ * Two details are load-bearing:
+ *
+ *   - **Ask git, never the filesystem.** `.git` is a *file*, not a directory,
+ *     in the linked worktrees this repo delivers from, so an
+ *     `existsSync('.git/MERGE_HEAD')` probe would be silently inert exactly
+ *     where deliveries happen. `rev-parse --verify` resolves the ref through
+ *     git's own worktree-aware lookup.
+ *   - **`--verify` fails closed on an octopus merge.** It refuses a
+ *     `MERGE_HEAD` naming more than one head, which lands here as `null` — the
+ *     pre-#5131 behaviour. Narrowing the scope wrongly would hide a real
+ *     regression; widening it only restores the status quo.
+ *
+ * Never throws: a merge is either detectable or it is not, and an
+ * undetectable one must degrade to the plain cached diff rather than fail the
+ * gate.
+ *
+ * @param {object} [params]
+ * @param {string} [params.cwd=process.cwd()]
+ * @param {ReturnType<typeof createGitInterface>} [params.git]
+ * @returns {string | null} The merge head's object id, or `null`.
+ */
+export function resolveMergeHead({ cwd = process.cwd(), git } = {}) {
+  const gitIface = git ?? createGitInterface({});
+  let res;
+  try {
+    res = gitIface.gitSpawn(cwd, 'rev-parse', '-q', '--verify', 'MERGE_HEAD');
+  } catch {
+    return null;
+  }
+  if (res?.status !== 0) return null;
+  const sha = (res.stdout ?? '').trim();
+  return OBJECT_ID_RE.test(sha) ? sha : null;
+}
+
+/**
+ * Read the index file list against an explicit base, shared by
+ * `getStagedFiles` and `resolvePreviewScope` so the merge head is resolved
+ * once per scope resolution rather than once per caller.
+ *
+ * @param {object} params
+ * @param {string} params.cwd
+ * @param {ReturnType<typeof createGitInterface>} params.git
+ * @param {string | null} params.mergeHead
+ * @returns {string[]}
+ */
+function stagedFilesAgainst({ cwd, git, mergeHead }) {
+  const args = ['diff', '--name-only', '--cached'];
+  if (mergeHead) args.push(mergeHead);
+  const res = git.gitSpawn(cwd, ...args);
+  if (res.status !== 0) {
+    const detail = res.stderr || res.stdout || `exit ${res.status}`;
+    throw new Error(`[staged] unable to read cached diff: ${detail}`);
+  }
+  return parseNameOnlyStdout(res.stdout);
+}
+
 /**
  * Resolve paths in the index (staged for commit). Used by `quality-preview
  * --staged` so pre-commit gates score only the commit payload, not unstaged
  * working-tree edits.
  *
  * Semantics:
- *   - Runs `git diff --name-only --cached`.
+ *   - Runs `git diff --name-only --cached`, which diffs the index against
+ *     `HEAD`.
+ *   - **During a merge**, diffs the index against `MERGE_HEAD` instead
+ *     (Story #5131), so the scope is the merging branch's own contribution
+ *     plus its conflict resolutions — not the base branch's incoming work.
+ *     `git merge-base HEAD MERGE_HEAD` would *not* do: diffing the index
+ *     against the fork point re-admits everything the base branch landed since
+ *     it, which is the whole defect.
  *   - Returns forward-slash-normalized repo-relative paths.
  *   - Non-zero git exit throws — staged mode must not silently widen scope.
  *
@@ -139,12 +224,11 @@ export function getChangedFiles({
  */
 export function getStagedFiles({ cwd = process.cwd(), git } = {}) {
   const gitIface = git ?? createGitInterface({});
-  const res = gitIface.gitSpawn(cwd, 'diff', '--name-only', '--cached');
-  if (res.status !== 0) {
-    const detail = res.stderr || res.stdout || `exit ${res.status}`;
-    throw new Error(`[staged] unable to read cached diff: ${detail}`);
-  }
-  return parseNameOnlyStdout(res.stdout);
+  return stagedFilesAgainst({
+    cwd,
+    git: gitIface,
+    mergeHead: resolveMergeHead({ cwd, git: gitIface }),
+  });
 }
 
 /**
@@ -154,6 +238,11 @@ export function getStagedFiles({ cwd = process.cwd(), git } = {}) {
  * is ignored. Otherwise a `changedSinceRef` limits to that three-dot diff;
  * when both are absent the caller runs in full-repo mode (`scopeSet: null`).
  *
+ * In `staged` scope, `diffRef` carries the in-progress merge head when there
+ * is one (Story #5131) and `null` otherwise, so a caller can tell the operator
+ * *why* the scope narrowed. `scope` stays `'staged'` either way — the merge is
+ * a property of the base the index is read against, not a different mode.
+ *
  * @param {object} [params]
  * @param {boolean} [params.staged=false]
  * @param {string | null} [params.changedSinceRef=null]
@@ -172,8 +261,10 @@ export function resolvePreviewScope({
   git,
 } = {}) {
   if (staged) {
-    const files = getStagedFiles({ cwd, git });
-    return { scopeSet: new Set(files), scope: 'staged', diffRef: null };
+    const gitIface = git ?? createGitInterface({});
+    const mergeHead = resolveMergeHead({ cwd, git: gitIface });
+    const files = stagedFilesAgainst({ cwd, git: gitIface, mergeHead });
+    return { scopeSet: new Set(files), scope: 'staged', diffRef: mergeHead };
   }
   if (changedSinceRef) {
     try {

package/.agents/scripts/lib/checks/core-bare-clean.js

@@ -26,7 +26,7 @@ export default {
   severity: 'blocker',
   // 'npm-test' keeps the test-wrapper preflight's refusal claim true: a
   // poisoned shared config is caught before a suite (or N concurrent
-  // /deliver workers) inherits it, not only at close/retro time (#4580).
+  // /mandrel-deliver workers) inherits it, not only at close/retro time (#4580).
   scope: ['story-close', 'retro', 'npm-test'],
   autoCorrect: 'refuse-and-print',
   detect(state) {

package/.agents/scripts/lib/checks/story-init-not-backgrounded.js

@@ -11,7 +11,7 @@
  *
  * Scope: 'story-close', 'retro'. The check runs at every
  * preflight surface that has the opportunity to invoke Story init —
- * primarily `/deliver`'s init step — and surfaces as a retro audit
+ * primarily `/mandrel-deliver`'s init step — and surfaces as a retro audit
  * signal if the failure mode resurfaces during a sprint.
  *
  * The check is `refuse-and-print`. Auto-rewriting an orchestration call

package/.agents/scripts/lib/cli-args.js

@@ -253,7 +253,7 @@ export function parseSprintArgs(
       process.env.AGENT_WORKTREE_ROOT ||
       null,
     recutOf: parseTicketId(values['recut-of']),
-    // Story #4253: pre-resolved Epic linkage threaded by the /deliver
+    // Story #4253: pre-resolved Epic linkage threaded by the /mandrel-deliver
     // fan-out so `single-story-init.js` can skip redundant Epic lookups when
     // the parent already threaded Epic context (pre-v2; field retained for
     // CLI compatibility).

package/.agents/scripts/lib/command-header.js

@@ -36,7 +36,7 @@ export function applyHeader(content, header) {
  * True when a workflow opts out of slash-command projection via a
  * `command: false` key in its YAML frontmatter (#4482). Used for dual-use
  * lens files (e.g. `audit-security.md`) that stay in
- * the payload as `/deliver` audit-suite prompts but must NOT surface as
+ * the payload as `/mandrel-deliver` audit-suite prompts but must NOT surface as
  * standalone slash commands because the host ships a native equivalent.
  *
  * Both `sync-claude-commands.js` (projection + orphan-reap) and the

package/.agents/scripts/lib/config/delivery-routing.js

@@ -36,7 +36,7 @@ export const DELIVERY_ROUTING_DEFAULTS = Object.freeze({
   /** @type {'minimal'|'standard'|'strict'} */
   ceremonyProfile: 'standard',
   /**
-   * When true (default), attended `/deliver` lands through merge in one
+   * When true (default), attended `/mandrel-deliver` lands through merge in one
    * close (`--wait-merge` semantics) instead of stopping at `agent::closing`.
    * Operators opt out per-run with `--no-wait-merge`.
    */