mandrel 2.38.0 → 2.39.0

package/.agents/README.md

@@ -775,7 +775,16 @@ time by `resolveQaContract`. Copy the reference shape from
   "qa": {
     "featureRoot": "tests/features",                 // root the selector resolves .feature files against
     "fixturesManifest": "tests/fixtures/personas.json", // persona → seed-data manifest
-    "signInSeam": { "urlTemplate": "/dev/sign-in-as/{persona}" }, // dev seam (see step 3)
+    "environments": {                                // one entry per deployment target
+      "local": {
+        "baseUrl": "http://localhost:3000",
+        "signInSeam": { "urlTemplate": "/dev/sign-in-as/{persona}" } // dev seam (see step 3)
+      },
+      "staging": {
+        "baseUrl": "https://staging.example.test",
+        "allowWrites": false                         // no signInSeam — an honestly seamless target
+      }
+    },
     "personas": ["admin", "member"],                 // name-only array — the honest shape for a url-template seam
     "consoleAllowlist": ["[HMR]"],                   // optional benign-noise filter (default [])
     "designTokens": "src/styles/tokens.css"          // optional visual-check pointer (default null)
@@ -783,8 +792,9 @@ time by `resolveQaContract`. Copy the reference shape from
 }
 ```
 
-`featureRoot`, `fixturesManifest`, `signInSeam`, and `personas` are mandatory;
-omitting any one makes the resolver throw a field-named error.
+`featureRoot`, `fixturesManifest`, `environments`, and `personas` are mandatory;
+omitting any one makes the resolver throw a field-named error. Within an
+environment only `baseUrl` is required — `signInSeam` is optional (see step 3).
 `consoleAllowlist` and `designTokens` default to `[]` and `null`.
 
 `personas` accepts **two shapes** (the resolver normalizes both to one
@@ -800,13 +810,16 @@ canonical internal map keyed by persona name):
   (or credential) seam where that material is genuinely consulted:
 
   ```jsonc
-  "signInSeam": { "skill": "stack/qa/sign-in" },
+  "signInSeam": { "skill": "stack/qa/acme-sso" }, // a skill YOU author (see step 3)
   "personas": {
     "admin": { "credentialRef": "QA_ADMIN_CREDENTIAL" }, // stored-credential reference, never an inline secret
-    "member": { "signInSkill": "stack/qa/sign-in-member" } // or a per-persona sign-in skill
+    "member": { "signInSkill": "stack/qa/acme-sso-member" } // or a per-persona sign-in skill
   }
   ```
 
+  Both skill ids above are **illustrative names for skills you write** — the
+  framework ships no sign-in skill. Step 3 says where they go.
+
 ### 2. Author the fixtures manifest
 
 Create the file referenced by `fixturesManifest`. It binds each persona to the
@@ -824,9 +837,33 @@ credentials are never entered. Expose one of two shapes:
 - **`{ urlTemplate }`** — a dev sign-in route where `{persona}` is substituted
   (e.g. `/dev/sign-in-as/{persona}` → `/dev/sign-in-as/admin`); gate it to
   non-production builds. Pair with the name-only `personas` array.
-- **`{ skill }`** — when sign-in is multi-step or non-URL, point at a consumer
-  skill whose `SKILL.md` the harness reads. Pair with the object-map
-  `personas` form (per step 1).
+- **`{ skill }`** — when sign-in is multi-step or non-URL, name a skill by its
+  tier-relative id (e.g. `stack/qa/acme-sso`) whose `SKILL.md` the harness
+  reads. Pair with the object-map `personas` form (per step 1).
+- **Omit it entirely** — the honest shape for a target with no sign-in seam at
+  all, such as a deployed build whose dev bypass is tree-shaken out. The
+  workflows then drive the unauthenticated surface and record the gap rather
+  than fabricating a session.
+
+**Where a `{ skill }` seam resolves.** The id is looked up under
+`.agents/skills/` (the package payload) and then `.agents/local/skills/` —
+the consumer-writable zone. Author your own sign-in skill in the local zone:
+
+```text
+.agents/local/skills/stack/qa/acme-sso/SKILL.md   →  id: stack/qa/acme-sso
+```
+
+`.agents/local/` is never copied into by `mandrel sync`, never pruned, and
+never reported as payload drift by `mandrel doctor`, so a skill you write
+there survives every upgrade. It is held to the same bar as a shipped skill —
+`validate-skills.js` checks its frontmatter and Policy Capsule, and
+`generate-skills-index.js` writes it into its own
+`.agents/local/skills/skills.index.json` (never into the shipped manifest,
+which must stay byte-identical to the package payload).
+
+A seam naming an id that resolves under neither root is rejected by
+`resolveQaEnvironment` when the contract is resolved — not silently carried
+until a sweep reaches its sign-in step.
 
 Once these three `qa.*` keys are in place, `/qa-explore <surface>`, `/qa-assist`,
 and `/qa-run <selector>` all resolve the contract and operate against the bound

package/.agents/docs/agentrc-reference.json

@@ -363,9 +363,6 @@
       },
       "staging": {
         "baseUrl": "https://staging.example.test",
-        "signInSeam": {
-          "skill": "stack/qa/sign-in"
-        },
         "allowWrites": false
       }
     },
@@ -374,7 +371,7 @@
         "credentialRef": "QA_ADMIN_CREDENTIAL"
       },
       "member": {
-        "signInSkill": "stack/qa/sign-in-member"
+        "credentialRef": "QA_MEMBER_CREDENTIAL"
       }
     },
     "gherkinLint": {

package/.agents/docs/configuration.md

@@ -336,8 +336,8 @@ Agent-driven QA harness contract (Epic #3214; environment-keyed by Epic #4326).
 | --- | --- | --- | --- | --- |
 | `featureRoot` | No | `string` | `"tests/features"` | Directory holding the Gherkin feature files the QA sweep drives. |
 | `fixturesManifest` | No | `string` | `"tests/fixtures/personas.json"` | Path to the persona/fixture manifest the harness seeds from. |
-| `environments` | No | `object<map>` | `{"local":{"baseUrl":"http://localhost:3000","signInSeam":{"urlTemplate":"/dev/sign-in-as/{persona}"}},"staging":{"baseUrl":"https://staging.example.test","signInSeam":{"skill":"stack/qa/sign-in"},"allowWrites":false}}` | Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, its own per-environment sign-in seam (the same url-template/skill union as the top-level seam), and an optional `allowWrites` gate. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. Replaces the retired top-level single `signInSeam`. |
-| `personas` | No | one of: `array`, `object` | `{"admin":{"credentialRef":"QA_ADMIN_CREDENTIAL"},"member":{"signInSkill":"stack/qa/sign-in-member"}}` | Personas the QA-harness sign-in seam accepts. Two accepted shapes: (1) a plain array of persona names — the honest shape for a `urlTemplate` dev-impersonation seam, where the persona name is the sole input the workflow consumes; (2) the object-map form keyed by persona name, where each entry carries per-persona auth material (`credentialRef` or `signInSkill`) consulted only under a skill-based or credential-based seam. |
+| `environments` | No | `object<map>` | `{"local":{"baseUrl":"http://localhost:3000","signInSeam":{"urlTemplate":"/dev/sign-in-as/{persona}"}},"staging":{"baseUrl":"https://staging.example.test","allowWrites":false}}` | Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, an optional per-environment sign-in seam, and an optional `allowWrites` gate. `signInSeam` is the union `{ urlTemplate }` (a dev impersonation route) or `{ skill }` (a skill id such as `stack/qa/acme-sso`, resolved against `.agents/skills/` then the consumer-writable `.agents/local/skills/` zone, and rejected loudly by resolveQaEnvironment when it resolves under neither); omit it entirely for a target with no sign-in seam. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. Replaces the retired top-level single `signInSeam`. |
+| `personas` | No | one of: `array`, `object` | `{"admin":{"credentialRef":"QA_ADMIN_CREDENTIAL"},"member":{"credentialRef":"QA_MEMBER_CREDENTIAL"}}` | Personas the QA-harness sign-in seam accepts. Two accepted shapes: (1) a plain array of persona names — the honest shape for a `urlTemplate` dev-impersonation seam, where the persona name is the sole input the workflow consumes; (2) the object-map form keyed by persona name, where each entry carries per-persona auth material (`credentialRef` or `signInSkill`) consulted only under a skill-based or credential-based seam. |
 | `gherkinLint` | No | `object` | `{"scopes":{"web":{"featureRoots":["apps/web/tests/features"],"stepRoots":["apps/web/tests/steps"]}},"exemptionTags":["@skip"],"stepWaivers":[]}` | Static Gherkin corpus gate (Story #5013). Optional; the gate runs only when this block is present, so an upgrade never reddens the lint of a consumer that never asked the framework to police its `.feature` files. Inside the opt-in it fails closed: an unresolvable `@cucumber/gherkin` parser, or a scope resolving zero step definitions, exits 1 rather than reporting a clean run. |
 | `gherkinLint.scopes` | Yes | `object<map>` | — | Binding scopes, keyed by name. Each scope resolves its own features against its own step definitions only — pooling every step root into one matcher list is what makes a cross-app false bind possible, where a step defined solely in app B silently vouches for app A. The scope name appears verbatim in every unbound finding. |
 | `gherkinLint.exemptionTags` | No | `array<string>` | `["@skip"]` | Tags marking a scenario as intentionally non-binding, so must-bind skips it. Never an escape from must-compile: a parse error in the file still fails the run. Default: ["@skip"]. |

package/.agents/schemas/agentrc.schema.json

@@ -1921,7 +1921,9 @@
             },
             "advisoryAllowlist": {
               "type": "array",
-              "items": { "type": "string" },
+              "items": {
+                "type": "string"
+              },
               "description": "Story #5096. Check-run names exempt from blockOnAdvisoryFailure — a red run whose name matches exactly never blocks arming. Matching is exact; an unnamed run can never match and always blocks.",
               "default": []
             }
@@ -1985,7 +1987,7 @@
         },
         "environments": {
           "type": "object",
-          "description": "Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, its own per-environment sign-in seam (the same url-template/skill union as the top-level seam), and an optional `allowWrites` gate. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. Replaces the retired top-level single `signInSeam`.",
+          "description": "Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, an optional per-environment sign-in seam, and an optional `allowWrites` gate. `signInSeam` is the union `{ urlTemplate }` (a dev impersonation route) or `{ skill }` (a skill id such as `stack/qa/acme-sso`, resolved against `.agents/skills/` then the consumer-writable `.agents/local/skills/` zone, and rejected loudly by resolveQaEnvironment when it resolves under neither); omit it entirely for a target with no sign-in seam. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. Replaces the retired top-level single `signInSeam`.",
           "default": {
             "local": {
               "baseUrl": "http://localhost:3000",
@@ -1995,9 +1997,6 @@
             },
             "staging": {
               "baseUrl": "https://staging.example.test",
-              "signInSeam": {
-                "skill": "stack/qa/sign-in"
-              },
               "allowWrites": false
             }
           },
@@ -2048,7 +2047,7 @@
                 "type": "boolean"
               }
             },
-            "required": ["baseUrl", "signInSeam"],
+            "required": ["baseUrl"],
             "additionalProperties": false
           }
         },
@@ -2059,7 +2058,7 @@
               "credentialRef": "QA_ADMIN_CREDENTIAL"
             },
             "member": {
-              "signInSkill": "stack/qa/sign-in-member"
+              "credentialRef": "QA_MEMBER_CREDENTIAL"
             }
           },
           "oneOf": [

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/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 {