mandrel 2.40.0 → 2.42.0

package/.agents/scripts/lib/orchestration/plan-persist/epic-adoption.js

@@ -0,0 +1,192 @@
+/**
+ * epic-adoption.js — join the Stories of this persist run to an Epic that
+ * already exists.
+ *
+ * Story #5155. `epic-ops.js` opens a *new* container and, on a resumed run,
+ * re-adopts the one carrying its exact fingerprint. This module covers the
+ * case neither does: an operator pointing a fresh plan at an Epic an earlier
+ * plan opened, with a different cohort and no fingerprint in common.
+ *
+ * **The posture is deliberately stricter than creation's.** Creation degrades
+ * — an unensurable label just skips the container, because the Stories are the
+ * part that matters and a missing Epic costs only tidiness. Adoption cannot
+ * degrade the same way: the operator named a specific id, so silently not
+ * adopting it would leave them believing their Stories were filed somewhere
+ * they were not. A bad target is therefore a **hard error, raised before the
+ * first Story is created** (dry run included), when nothing has been written
+ * and the fix is free. Once the Stories exist, the posture flips to creation's
+ * — a failed checklist write or sub-issue edge warns, because by then refusing
+ * would strand live Stories over a cosmetic link.
+ *
+ * @module lib/orchestration/plan-persist/epic-adoption
+ * @see Story #5155
+ */
+
+import { Logger } from '../../Logger.js';
+import { TYPE_LABELS } from '../../label-constants.js';
+import { appendEpicChildIds } from '../epic-checklist.js';
+import { isEpicTicket } from '../epic-container.js';
+import { mirrorSubIssueEdges } from './epic-ops.js';
+
+/**
+ * Resolve and validate the Epic an operator asked to adopt.
+ *
+ * Called **before any create**, so every refusal below costs the operator a
+ * re-run of a command that wrote nothing.
+ *
+ * A null/absent `epicId` is the ordinary "no adoption requested" case and
+ * resolves to `null` — only a *supplied* id can be wrong, and every wrong one
+ * throws.
+ *
+ * @param {{ provider: object, epicId: number|null }} opts
+ * @returns {Promise<{ id: number, title: string, body: string }|null>}
+ * @throws {Error} When a supplied id is missing, closed, or not a container Epic.
+ */
+export async function resolveAdoptionTarget({ provider, epicId }) {
+  if (epicId === null || epicId === undefined) return null;
+  const id = Number(epicId);
+  if (!Number.isInteger(id) || id <= 0) {
+    throw new Error(
+      `[plan-persist] --epic expects a positive issue id (got "${epicId}").`,
+    );
+  }
+  if (typeof provider?.getTicket !== 'function') {
+    throw new Error(
+      '[plan-persist] provider exposes no getTicket — cannot verify the Epic to adopt.',
+    );
+  }
+
+  let issue;
+  try {
+    issue = await provider.getTicket(id);
+  } catch (err) {
+    throw new Error(
+      `[plan-persist] --epic #${id} could not be read (${err?.message ?? err}). ` +
+        'Adoption needs an existing open container Epic.',
+    );
+  }
+  if (!issue) {
+    throw new Error(`[plan-persist] --epic #${id} does not exist.`);
+  }
+
+  const state = String(issue.state ?? 'open').toLowerCase();
+  if (state !== 'open') {
+    throw new Error(
+      `[plan-persist] --epic #${id} is ${state}. A closed Epic is a finished body of ` +
+        'work and is never reopened by a plan — open a new container, or reopen it by hand first.',
+    );
+  }
+  if (!isEpicTicket(issue)) {
+    throw new Error(
+      `[plan-persist] --epic #${id} does not carry "${TYPE_LABELS.EPIC}" — it is not a ` +
+        'container Epic. Adopting an ordinary Story would file this plan under a work item.',
+    );
+  }
+
+  return {
+    id,
+    title: typeof issue.title === 'string' ? issue.title : '',
+    body: typeof issue.body === 'string' ? issue.body : '',
+  };
+}
+
+/**
+ * Link this run's Stories into an already-resolved Epic.
+ *
+ * Runs **after** the Stories exist, because both halves of the linkage need
+ * their real ids: the checklist embeds issue numbers and the sub-issue edges
+ * need database ids.
+ *
+ * @param {{
+ *   provider: object,
+ *   target: { id: number, title: string, body: string },
+ *   created: Array<{ id: number }>,
+ *   opts?: { dryRun?: boolean },
+ * }} args
+ * @returns {Promise<{
+ *   id: number,
+ *   title: string,
+ *   childIds: number[],
+ *   adopted: true,
+ *   edges: { added: number, skipped: number, failed: number }|null,
+ * }|null>}
+ */
+export async function adoptContainerEpic({
+  provider,
+  target,
+  created,
+  opts = {},
+}) {
+  const { dryRun = false } = opts;
+  if (!target) return null;
+
+  const all = Array.isArray(created) ? created : [];
+
+  // Dry run reports the intent write-free. `created` carries negative
+  // placeholder ids there, so report them as-is rather than filtering to the
+  // positives and claiming an empty adoption.
+  if (dryRun) {
+    return {
+      id: target.id,
+      title: target.title,
+      childIds: all.map((s) => s.id),
+      adopted: true,
+      edges: null,
+    };
+  }
+
+  const childIds = all
+    .map((s) => s.id)
+    .filter((id) => Number.isInteger(id) && id > 0);
+  if (childIds.length === 0) return null;
+
+  await appendChecklist({ provider, target, childIds });
+  const edges = await mirrorSubIssueEdges({
+    provider,
+    epicNumber: target.id,
+    childIds,
+  });
+
+  Logger.info(
+    `[plan-persist] adopted container Epic #${target.id} — it now groups ` +
+      `${childIds.length} more Story(ies): /mandrel-deliver ${target.id}`,
+  );
+
+  return {
+    id: target.id,
+    title: target.title,
+    childIds,
+    adopted: true,
+    edges,
+  };
+}
+
+/**
+ * Write the appended checklist back to the Epic body.
+ *
+ * Non-fatal: the Stories are already live, and the native sub-issue edges
+ * written next are the other half of the linkage. Losing the checklist costs
+ * the body-only fallback path, not the grouping.
+ *
+ * @param {{ provider: object, target: { id: number, body: string }, childIds: number[] }} opts
+ * @returns {Promise<void>}
+ */
+async function appendChecklist({ provider, target, childIds }) {
+  if (typeof provider?.updateTicket !== 'function') {
+    Logger.warn(
+      '[plan-persist] provider exposes no updateTicket — the adopted Epic body was not ' +
+        'updated. The native sub-issue edges still record the grouping.',
+    );
+    return;
+  }
+  const next = appendEpicChildIds(target.body, childIds);
+  if (next === target.body) return;
+  try {
+    await provider.updateTicket(target.id, { body: next });
+  } catch (err) {
+    Logger.warn(
+      `[plan-persist] could not update Epic #${target.id}'s checklist ` +
+        `(${err?.message ?? err}). The native sub-issue edges still record the grouping.`,
+    );
+  }
+}

package/.agents/scripts/lib/orchestration/plan-persist/epic-ops.js

@@ -150,10 +150,14 @@ async function findExistingEpic({ provider, fingerprint }) {
  * `getSubTickets` reads it as a first-class child source. A lost edge costs
  * the GitHub UI's nesting, not the grouping itself.
  *
+ * Exported since Story #5155 so the adoption path (`epic-adoption.js`) links
+ * children exactly the way creation does — one mirroring rule, not two that
+ * drift.
+ *
  * @param {{ provider: object, epicNumber: number, childIds: number[] }} opts
  * @returns {Promise<{ added: number, skipped: number, failed: number }|null>}
  */
-async function mirrorSubIssueEdges({ provider, epicNumber, childIds }) {
+export async function mirrorSubIssueEdges({ provider, epicNumber, childIds }) {
   if (
     typeof provider?.getDependencyWriteContext !== 'function' ||
     typeof provider?.getTicket !== 'function'

package/.agents/scripts/lib/orchestration/plan-persist/external-deps.js

@@ -0,0 +1,164 @@
+/**
+ * external-deps.js — `depends_on` entries that point outside this plan run.
+ *
+ * Story #5155. A `depends_on[]` entry has always been a **sibling slug**: a
+ * name resolvable only inside the `stories.json` being persisted. That makes
+ * every ordering edge intra-plan by construction, and leaves the cross-plan
+ * case — a new Story that must wait for an open Story from an earlier run —
+ * expressible only by hand-editing the issue body after persist.
+ *
+ * An entry of the form `#1234` is that missing case: an **external** blocker,
+ * already live on the tracker. The two forms are distinguished lexically and
+ * totally, so nothing has to guess:
+ *
+ *   - `some-slug` → a sibling, resolved against this run's slug map;
+ *   - `#1234`     → an existing issue, resolved against the tracker.
+ *
+ * External refs are excluded from sibling ordering and cycle detection. They
+ * cannot participate in either: a Story already open is not scheduled by this
+ * run, so it has no position in the topological sort, and it cannot close a
+ * cycle back into a Story that does not exist yet. Treating them as siblings
+ * is what would break — the unknown-slug guard would reject every one.
+ *
+ * They are validated strictly, and **before any create**: an unresolvable
+ * blocker that surfaced after the fact would leave a live Story gated on
+ * something that can never satisfy it, which the delivery engine reads as a
+ * permanent wedge rather than an error.
+ *
+ * @module lib/orchestration/plan-persist/external-deps
+ * @see Story #5155
+ */
+
+import { TYPE_LABELS } from '../../label-constants.js';
+
+/** A `depends_on` entry naming an existing issue: `#` followed by digits. */
+const EXTERNAL_REF_RE = /^#(\d+)$/;
+
+/**
+ * Is this `depends_on` entry an external issue reference?
+ *
+ * @param {unknown} entry
+ * @returns {boolean}
+ */
+export function isExternalDependencyRef(entry) {
+  return typeof entry === 'string' && EXTERNAL_REF_RE.test(entry.trim());
+}
+
+/**
+ * The issue number an external ref names, or `null` for a sibling slug.
+ *
+ * @param {unknown} entry
+ * @returns {number|null}
+ */
+export function externalDependencyId(entry) {
+  if (typeof entry !== 'string') return null;
+  const match = entry.trim().match(EXTERNAL_REF_RE);
+  if (!match) return null;
+  const id = Number.parseInt(match[1], 10);
+  return Number.isInteger(id) && id > 0 ? id : null;
+}
+
+/**
+ * Every distinct external id declared across a plan's Stories, in first-seen
+ * order.
+ *
+ * @param {Array<{ depends_on?: string[] }>} stories
+ * @returns {number[]}
+ */
+export function collectExternalDependencyIds(stories) {
+  const seen = new Set();
+  const out = [];
+  for (const story of Array.isArray(stories) ? stories : []) {
+    for (const entry of story?.depends_on ?? []) {
+      const id = externalDependencyId(entry);
+      if (id === null || seen.has(id)) continue;
+      seen.add(id);
+      out.push(id);
+    }
+  }
+  return out;
+}
+
+/**
+ * Normalize an issue's labels to plain strings.
+ *
+ * @param {unknown} raw
+ * @returns {string[]}
+ */
+function labelNames(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((l) => (typeof l === 'string' ? l : l?.name))
+    .filter((n) => typeof n === 'string');
+}
+
+/**
+ * Explain why one external blocker is unusable, or `null` when it is fine.
+ *
+ * @param {number} id
+ * @param {object|null} issue
+ * @returns {string|null}
+ */
+function rejectionReason(id, issue) {
+  if (!issue) return `#${id} does not exist`;
+  const state = String(issue.state ?? 'open').toLowerCase();
+  if (state !== 'open') {
+    return `#${id} is ${state} — a landed Story cannot gate new work, so the edge would never lift`;
+  }
+  const labels = labelNames(issue.labels);
+  if (labels.includes(TYPE_LABELS.EPIC)) {
+    return `#${id} is a container Epic — Epics are never delivered, so nothing would ever satisfy the edge`;
+  }
+  if (!labels.includes(TYPE_LABELS.STORY)) {
+    return `#${id} is not a ${TYPE_LABELS.STORY} — only a Story can be delivered and thereby unblock this one`;
+  }
+  return null;
+}
+
+/**
+ * Verify every external `depends_on` ref resolves to an open Story.
+ *
+ * Hard-errors listing **every** bad ref rather than the first, so an operator
+ * fixing a plan sees the whole set in one pass.
+ *
+ * @param {{ provider: object, stories: Array<{ slug: string, depends_on?: string[] }> }} args
+ * @returns {Promise<number[]>} The validated external ids (possibly empty).
+ * @throws {Error} When any ref is missing, closed, an Epic, or not a Story.
+ */
+export async function assertExternalDependenciesResolvable({
+  provider,
+  stories,
+}) {
+  const ids = collectExternalDependencyIds(stories);
+  if (ids.length === 0) return [];
+
+  if (typeof provider?.getTicket !== 'function') {
+    throw new Error(
+      '[plan-persist] provider exposes no getTicket — cannot verify the external ' +
+        `depends_on reference(s): ${ids.map((i) => `#${i}`).join(', ')}.`,
+    );
+  }
+
+  const problems = [];
+  for (const id of ids) {
+    let issue = null;
+    try {
+      issue = await provider.getTicket(id);
+    } catch (err) {
+      problems.push(`#${id} could not be read (${err?.message ?? err})`);
+      continue;
+    }
+    const reason = rejectionReason(id, issue);
+    if (reason) problems.push(reason);
+  }
+
+  if (problems.length > 0) {
+    throw new Error(
+      `[plan-persist] ${problems.length} external depends_on reference(s) cannot gate ` +
+        `this plan:\n  - ${problems.join('\n  - ')}\n\nEvery "#<id>" entry must name an ` +
+        `open ${TYPE_LABELS.STORY}. Drop the entry, or point it at a Story that is still open.`,
+    );
+  }
+
+  return ids;
+}

package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js

@@ -68,7 +68,10 @@ import {
   renderHardConflictError,
 } from '../ticket-validator-conflicts.js';
 import { upsertStructuredComment } from '../ticketing.js';
-import { createContainerEpic } from './epic-ops.js';
+import {
+  resolveContainerEpic,
+  resolveCrossPlanLinks,
+} from './cross-plan-links.js';
 import {
   enforceFanOutGate,
   surfaceSoftConflictFindings,
@@ -751,6 +754,14 @@ export async function runPlanPersist({
   });
   await enforceReachability(reachability, config);
 
+  // Story #5155 — the plan's outward references (`--epic <id>`, and any
+  // `#<id>` blocker) resolve BEFORE the first create, dry run included.
+  const adoptionTarget = await resolveCrossPlanLinks({
+    provider,
+    stories: rawStories,
+    epicId: opts.adoptEpicId ?? null,
+  });
+
   // Split policy + inline Spec fold (over-budget Specs fail closed — no docs/).
   const { stories } = assemblePlanStories(rawStories, {
     sharedSpec: techSpecContent,
@@ -850,8 +861,9 @@ export async function runPlanPersist({
   // database ids, neither of which exists until the Stories are live. It is
   // never load-bearing, so a failure here degrades to "no container" and the
   // Stories still deliver by id.
-  const containerEpic = await createContainerEpic({
+  const containerEpic = await resolveContainerEpic({
     provider,
+    adoptionTarget,
     epic,
     created,
     opts: { dryRun },

package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js

@@ -34,6 +34,10 @@ import {
 } from '../../util/concurrent-map.js';
 import { assertSpecWithinBudget } from '../spec-spill.js';
 import { assertAcceptancePartition } from '../split-policy-validator.js';
+import {
+  externalDependencyId,
+  isExternalDependencyRef,
+} from './external-deps.js';
 import {
   assertSupersedePartition,
   normalizeSupersedes,
@@ -557,7 +561,9 @@ function orderStoriesByDependencies(stories) {
   const list = Array.isArray(stories) ? stories : [];
   const known = new Set(list.map((story) => story.slug));
   for (const story of list) {
-    const unknown = story.depends_on.filter((slug) => !known.has(slug));
+    const unknown = story.depends_on.filter(
+      (slug) => !isExternalDependencyRef(slug) && !known.has(slug),
+    );
     if (unknown.length > 0) {
       throw new Error(
         `[plan-persist] Story "${story.slug}" depends on unknown sibling(s): ${unknown.join(', ')}`,
@@ -568,8 +574,13 @@ function orderStoriesByDependencies(stories) {
   const scheduled = new Set();
   const pending = [...list];
   while (pending.length > 0) {
+    // External refs gate delivery, never creation order: the blocker is
+    // already live, so it can never become "scheduled" in this run and would
+    // otherwise wedge the sort into a false cycle (Story #5155).
     const index = pending.findIndex((story) =>
-      story.depends_on.every((slug) => scheduled.has(slug)),
+      story.depends_on
+        .filter((slug) => !isExternalDependencyRef(slug))
+        .every((slug) => scheduled.has(slug)),
     );
     if (index === -1) {
       throw new Error(
@@ -720,8 +731,8 @@ function warnOnDivergentSameTitleStory(story, idsByTitle) {
  * @returns {string}
  */
 function renderStoryBodyForCreate(story, idBySlug) {
-  const dependencyRefs = story.depends_on.map(
-    (slug) => `#${idBySlug.get(slug)}`,
+  const dependencyRefs = story.depends_on.map((slug) =>
+    isExternalDependencyRef(slug) ? slug.trim() : `#${idBySlug.get(slug)}`,
   );
   let base = story.body;
   if (dependencyRefs.length > 0) {
@@ -798,12 +809,22 @@ async function mirrorNativeDependencyEdges({ provider, stories, idBySlug }) {
 
   try {
     const { gh, owner, repo } = provider.getDependencyWriteContext();
+    // `applyBlockedByDependencies` resolves every entry through this one map,
+    // so an external `#<id>` ref only needs an identity entry to be mirrored
+    // by the same code path as a sibling (Story #5155).
+    const slugToIssueNumber = Object.fromEntries(idBySlug);
+    for (const story of stories) {
+      for (const entry of story.depends_on) {
+        const externalId = externalDependencyId(entry);
+        if (externalId !== null) slugToIssueNumber[entry.trim()] = externalId;
+      }
+    }
     const summary = await applyBlockedByDependencies({
       stories: stories.map((story) => ({
         slug: story.slug,
         dependsOn: story.depends_on,
       })),
-      slugToIssueNumber: Object.fromEntries(idBySlug),
+      slugToIssueNumber,
       getTicket: (issueNumber) => provider.getTicket(issueNumber),
       owner,
       repo,

package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js

@@ -27,8 +27,12 @@ import {
 const PHASE_ORDER = Object.freeze([
   'init',
   'wrong-tree-guard',
-  'close-validation',
+  // Story #5172 — base-sync now precedes close-validation, so the tree the
+  // gates validate is the tree the push sends. The order here is not
+  // decoration: it is how a failed terminal decides which gates had already
+  // cleared, so it MUST track `runPrePushPhases`.
   'base-sync',
+  'close-validation',
   'push',
   'pull-request',
   'code-review',
@@ -45,6 +49,62 @@ const GATE_PHASES = Object.freeze([
   ['codeReview', 'code-review'],
 ]);
 
+/**
+ * The names the split baselines gate registers under, mirrored from
+ * `BASELINES_GATE_NAMES` in `lib/close-validation/gates.js` (Story #5172).
+ *
+ * Deliberately a local copy rather than an import: several close suites
+ * replace that module wholesale via `t.mock.module`, and a named import here
+ * would fail to link against a mock that does not re-export the constant —
+ * turning an unrelated test's mock into a load error on the CLI's own entry
+ * path. `tests/close-validation-gates-enum.test.js` pins the two lists
+ * against each other so the copy cannot drift.
+ */
+const BASELINES_ENTRY_NAMES = Object.freeze([
+  'check-baselines-independent',
+  'check-baselines-coverage',
+]);
+
+/**
+ * Outcome for each split baselines entry on a run that died at `phase`.
+ *
+ * The two entries sit in ONE pipeline phase, so the phase walk alone cannot
+ * separate them — `failedGate` (tagged onto the error by the close-validation
+ * phase) is what names the entry that actually broke. Rules, in the module's
+ * house style of never claiming a pass it cannot prove:
+ *   - validation skipped, or the run died before reaching it → both `skipped`.
+ *   - the run cleared validation entirely → both `passed`.
+ *   - the run died IN validation on the coverage-independent entry → that one
+ *     `failed`, the coverage one `skipped` (it runs behind `coverage-capture`,
+ *     which the failure pre-empted).
+ *   - died on the coverage-consuming entry → that one `failed`, and the
+ *     independent one `passed`: it is in the parallel partition that must go
+ *     green before any serial gate starts.
+ *   - died in validation on some other gate → both `skipped`; which of them
+ *     had run is not knowable from the phase alone.
+ *
+ * @param {string} phase
+ * @param {{ skipValidation?: boolean, failedGate?: string|null }} args
+ * @returns {Record<string, 'passed'|'failed'|'skipped'>}
+ */
+function baselinesGatesForFailedPhase(phase, { skipValidation, failedGate }) {
+  const [independent, coverage] = BASELINES_ENTRY_NAMES;
+  const both = (outcome) => ({ [independent]: outcome, [coverage]: outcome });
+  const failedAt = PHASE_ORDER.indexOf(phase);
+  const validationAt = PHASE_ORDER.indexOf('close-validation');
+  if (skipValidation || failedAt < 0 || failedAt < validationAt) {
+    return both('skipped');
+  }
+  if (failedAt > validationAt) return both('passed');
+  if (failedGate === independent) {
+    return { [independent]: 'failed', [coverage]: 'skipped' };
+  }
+  if (failedGate === coverage) {
+    return { [independent]: 'passed', [coverage]: 'failed' };
+  }
+  return both('skipped');
+}
+
 /**
  * Report every gate's outcome for a run that died at `phase`.
  *
@@ -59,8 +119,14 @@ const GATE_PHASES = Object.freeze([
  * turned off via `--skip-validation` / `--skip-sync` is `skipped` too (it did
  * not pass — it never ran).
  *
+ * Story #5172 — the reported set also carries the two split baselines
+ * entries under their own names, so a failed close says WHICH half of the
+ * baselines gate breached instead of a single generic verdict.
+ *
  * @param {string} phase The phase the run died in.
- * @param {{ skipValidation?: boolean, skipSync?: boolean }} args Parsed CLI args.
+ * @param {{ skipValidation?: boolean, skipSync?: boolean, failedGate?: string|null }} args
+ *   Parsed CLI args, plus the gate name tagged onto the error by the
+ *   close-validation phase.
  * @returns {Record<string, 'passed'|'failed'|'skipped'>}
  */
 export function gatesForFailedPhase(phase, args = {}) {
@@ -73,7 +139,13 @@ export function gatesForFailedPhase(phase, args = {}) {
     else if (failedAt < 0 || at > failedAt) gates[gate] = 'skipped';
     else gates[gate] = skipped[gate] ? 'skipped' : 'passed';
   }
-  return gates;
+  return {
+    ...gates,
+    ...baselinesGatesForFailedPhase(phase, {
+      skipValidation: args.skipValidation,
+      failedGate: args.failedGate ?? null,
+    }),
+  };
 }
 
 /**
@@ -91,6 +163,10 @@ export function gatesForFailedPhase(phase, args = {}) {
  * holding the script had been reaped mid-run. On failure this returns null
  * and the caller rethrows the original.
  *
+ * `err.closeGate` — tagged by the close-validation phase — names the gate that
+ * died inside that phase, which is what lets the reported gates separate the
+ * two split baselines entries (Story #5172).
+ *
  * @param {unknown} err
  * @param {{ storyId?: string|number, skipValidation?: boolean, skipSync?: boolean }} args
  *   Parsed CLI args — the story id the envelope reports on, plus the skip
@@ -108,7 +184,10 @@ export function failedTerminalFor(err, args = {}) {
       storyId,
       status: 'failed',
       phase,
-      gates: gatesForFailedPhase(phase, args),
+      gates: gatesForFailedPhase(phase, {
+        ...args,
+        failedGate: err?.closeGate ?? null,
+      }),
       failure: { reason: String(err?.message ?? err) },
       nextCommand: NEXT_COMMANDS.recover(storyId),
       elapsedSeconds: 0,

package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js

@@ -79,6 +79,10 @@ import { createGateLogSink as defaultCreateGateLogSink } from '../gate-log.js';
  *   runScopedFormatAutofix?: typeof defaultRunScopedFormatAutofix,
  *   createGateLogSink?: typeof defaultCreateGateLogSink,
  * }} args
+ * @returns {Promise<{ gates: Record<string, 'passed'|'skipped'> }>} Per-gate
+ *   outcomes keyed by gate name — the terminal envelope reports the split
+ *   baselines entries from this (Story #5172). A failure throws instead, with
+ *   `err.closeGate` naming the gate that died.
  */
 export async function runCloseValidationPhase({
   cwd,
@@ -144,17 +148,18 @@ export async function runCloseValidationPhase({
   // Story #4736 — one sink for both `log` seams (gate construction and gate
   // execution), so nothing in the chain can route around the artifact.
   const gateLog = createGateLogSink({ storyId, config });
+  const gateList = buildDefaultGates({
+    config,
+    baseBranch,
+    cwd: worktreePath || cwd,
+    log: gateLog.log,
+  });
   let validation;
   try {
     validation = await runCloseValidation({
       cwd,
       worktreePath,
-      gates: buildDefaultGates({
-        config,
-        baseBranch,
-        cwd: worktreePath || cwd,
-        log: gateLog.log,
-      }),
+      gates: gateList,
       log: gateLog.log,
       storyId,
       // Story #4250 — standalone storyId-anchored evidence keyspace. No
@@ -182,10 +187,37 @@ export async function runCloseValidationPhase({
     // The evidence is the point on this path: replay the captured tail inline
     // rather than making the caller open a file to learn why close stopped.
     gateLog.replay();
-    throw new Error(
+    const err = new Error(
       `[single-story-close] Gate failed: ${gate.name} (exit ${status})${gateCwd ? ` in ${gateCwd}` : ''}.` +
         (gate.hint ? ` ${gate.hint}` : ''),
     );
+    // Story #5172 — the phase tracker tags `closePhase`; this tags WHICH gate
+    // inside the phase died, so the failed terminal can name the split
+    // baselines entry rather than reporting a generic validation failure.
+    err.closeGate = gate.name;
+    throw err;
   }
   progress('VALIDATE', `✅ All gates passed. ${gateLog.digest()}`);
+  return { gates: gateOutcomes(gateList, validation) };
+}
+
+/**
+ * Per-gate outcomes for a validation run that passed (Story #5172).
+ *
+ * Every registered gate passed unless the runner reported it skipped — an
+ * evidence short-circuit at unchanged HEAD, or a changed-file scope that
+ * matched nothing. `skipped` is the honest verdict for both: the gate did not
+ * run in THIS invocation, and the terminal schema's own contract is that a
+ * skipped gate is reported as skipped rather than quietly counted as a pass.
+ *
+ * @param {Array<{ name: string }>} gateList The gates this run registered.
+ * @param {{ skipped?: Array<{ gate: { name: string } }> }} validation
+ * @returns {Record<string, 'passed'|'skipped'>}
+ */
+function gateOutcomes(gateList, validation) {
+  const outcomes = {};
+  for (const gate of gateList) outcomes[gate.name] = 'passed';
+  for (const { gate } of validation.skipped ?? [])
+    outcomes[gate.name] = 'skipped';
+  return outcomes;
 }