mandrel 2.47.0 → 2.48.0

package/.agents/scripts/lib/bootstrap/baseline-merge-driver.js

@@ -0,0 +1,175 @@
+/**
+ * bootstrap/baseline-merge-driver — register the `baselines/*.json` merge
+ * driver on a consumer clone (Story #5215).
+ *
+ * Registration has two halves that live in different places, and conflating
+ * them is why this needs a doctor check rather than just an installer:
+ *
+ *   1. **`.gitattributes`** says which files use the driver. It is a tracked
+ *      file, so installing the line once ships it to everyone.
+ *   2. **`git config merge.mandrel-baseline.driver`** says what the driver
+ *      actually is. Git deliberately keeps this out of tracked config —
+ *      otherwise a clone would execute a command chosen by whoever wrote the
+ *      repo — so it is **per clone**, and a fresh clone silently falls back
+ *      to git's text merge with no error at all.
+ *
+ * That silence is the whole reason `mandrel doctor` carries a check: an
+ * unregistered clone is not broken in any way it can report on its own, it
+ * just quietly goes back to conflicting (or worse, splicing) baselines.
+ *
+ * This module owns both halves plus the strings they share, so the installer
+ * and the doctor check cannot drift apart on the exact command.
+ *
+ * @module lib/bootstrap/baseline-merge-driver
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnCapture } from '../child-exec.js';
+
+/** Driver name, as it appears on both sides of the registration. */
+const BASELINE_MERGE_DRIVER_NAME = 'mandrel-baseline';
+
+/** The `.gitattributes` line that routes baselines through the driver. */
+const BASELINE_MERGE_ATTRIBUTE = `baselines/*.json merge=${BASELINE_MERGE_DRIVER_NAME}`;
+
+/** Git config key holding the driver command. */
+export const BASELINE_MERGE_DRIVER_CONFIG_KEY = `merge.${BASELINE_MERGE_DRIVER_NAME}.driver`;
+
+/**
+ * The driver command. Relative to the worktree root, which is where git runs
+ * a merge driver from, and where `mandrel sync` materializes `.agents/`.
+ */
+const BASELINE_MERGE_DRIVER_COMMAND =
+  'node .agents/scripts/merge-baseline.js %O %A %B %P';
+
+/** The exact command an operator runs to complete registration. */
+export const BASELINE_MERGE_DRIVER_REMEDY = `git config ${BASELINE_MERGE_DRIVER_CONFIG_KEY} "${BASELINE_MERGE_DRIVER_COMMAND}"`;
+
+/**
+ * Does this `.gitattributes` content route baselines through the driver?
+ * Comment lines do not count — a commented-out registration is not one.
+ *
+ * @param {string|null|undefined} gitattributes
+ * @returns {boolean}
+ */
+export function declaresBaselineMergeDriver(gitattributes) {
+  return String(gitattributes ?? '')
+    .split('\n')
+    .some((line) => {
+      const trimmed = line.trim();
+      if (trimmed === '' || trimmed.startsWith('#')) return false;
+      return trimmed.includes(`merge=${BASELINE_MERGE_DRIVER_NAME}`);
+    });
+}
+
+/**
+ * Add the attribute line, preserving every existing line verbatim.
+ *
+ * @param {string} projectRoot
+ * @param {typeof fs} [fsImpl]
+ * @returns {{ action: 'created'|'appended'|'already-present', path: string }}
+ */
+function ensureGitattributesLine(projectRoot, fsImpl = fs) {
+  const target = path.join(projectRoot, '.gitattributes');
+  if (!fsImpl.existsSync(target)) {
+    fsImpl.writeFileSync(target, `${BASELINE_MERGE_ATTRIBUTE}\n`, 'utf8');
+    return { action: 'created', path: target };
+  }
+  const existing = fsImpl.readFileSync(target, 'utf8');
+  if (declaresBaselineMergeDriver(existing)) {
+    return { action: 'already-present', path: target };
+  }
+  // A file not ending in a newline would otherwise glue our line onto the
+  // last existing one, silently rewriting it.
+  const separator = existing === '' || existing.endsWith('\n') ? '' : '\n';
+  fsImpl.writeFileSync(
+    target,
+    `${existing}${separator}${BASELINE_MERGE_ATTRIBUTE}\n`,
+    'utf8',
+  );
+  return { action: 'appended', path: target };
+}
+
+/**
+ * Point `merge.mandrel-baseline.driver` at the driver in THIS clone.
+ *
+ * @param {string} projectRoot
+ * @param {typeof spawnCapture} [spawnImpl]
+ * @returns {{ action: 'set'|'already-present'|'not-a-repo'|'failed' }}
+ */
+function ensureDriverGitConfig(projectRoot, spawnImpl = spawnCapture) {
+  const opts = {
+    cwd: projectRoot,
+    encoding: 'utf-8',
+    stdio: 'pipe',
+    shell: false,
+  };
+  const inRepo = spawnImpl('git', ['rev-parse', '--git-dir'], opts);
+  if ((inRepo?.status ?? 1) !== 0) return { action: 'not-a-repo' };
+
+  const current = spawnImpl(
+    'git',
+    ['config', '--local', '--get', BASELINE_MERGE_DRIVER_CONFIG_KEY],
+    opts,
+  );
+  if (
+    (current?.status ?? 1) === 0 &&
+    String(current.stdout ?? '').trim() === BASELINE_MERGE_DRIVER_COMMAND
+  ) {
+    return { action: 'already-present' };
+  }
+
+  const set = spawnImpl(
+    'git',
+    [
+      'config',
+      '--local',
+      BASELINE_MERGE_DRIVER_CONFIG_KEY,
+      BASELINE_MERGE_DRIVER_COMMAND,
+    ],
+    opts,
+  );
+  spawnImpl(
+    'git',
+    [
+      'config',
+      '--local',
+      `merge.${BASELINE_MERGE_DRIVER_NAME}.name`,
+      'mandrel baseline merge by row identity',
+    ],
+    opts,
+  );
+  return { action: (set?.status ?? 1) === 0 ? 'set' : 'failed' };
+}
+
+/**
+ * Install both halves. Idempotent: a second run reports `already-present`
+ * and changes no bytes.
+ *
+ * @param {object} ctx
+ * @param {string} ctx.projectRoot
+ * @param {typeof spawnCapture} [ctx.spawnImpl]
+ * @param {typeof fs} [ctx.fsImpl]
+ * @returns {{
+ *   action: 'already-present'|'updated',
+ *   attributes: string,
+ *   config: string,
+ *   path: string,
+ *   line: string,
+ * }}
+ */
+export function ensureBaselineMergeDriver(ctx) {
+  const attributes = ensureGitattributesLine(ctx.projectRoot, ctx.fsImpl ?? fs);
+  const config = ensureDriverGitConfig(ctx.projectRoot, ctx.spawnImpl);
+  const settled =
+    attributes.action === 'already-present' &&
+    (config.action === 'already-present' || config.action === 'not-a-repo');
+  return {
+    action: settled ? 'already-present' : 'updated',
+    attributes: attributes.action,
+    config: config.action,
+    path: attributes.path,
+    line: BASELINE_MERGE_ATTRIBUTE,
+  };
+}

package/.agents/scripts/lib/bootstrap/quality-bootstrap.js

@@ -15,7 +15,11 @@
  *   4. Seeds `delivery.quality.codingGuardrails` and
  *      `delivery.quality.autoRefresh` defaults in `.agentrc.json` when
  *      the keys are absent. Existing values are preserved.
- *   5. Prunes a committed pre-v2 `baselines/epic/` tree (Story #5007). The
+ *   5. Registers the `baselines/*.json` merge driver (Story #5215) — the
+ *      `.gitattributes` line plus this clone's `merge.mandrel-baseline.driver`
+ *      config, so concurrent baseline refreshes merge by row identity instead
+ *      of conflicting on the `generatedAt` stamp.
+ *   6. Prunes a committed pre-v2 `baselines/epic/` tree (Story #5007). The
  *      v2 model is Story-only — nothing writes, reads, or reaps per-Epic
  *      ratchet snapshots — so an upgrading consumer is left carrying a
  *      committed directory no gate consults. Absent on every repo that never
@@ -35,6 +39,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { getAgentrcDefaults, lookupPath } from '../config/defaults.js';
 import { deepEqual } from '../json-utils.js';
+import { ensureBaselineMergeDriver } from './baseline-merge-driver.js';
 
 /**
  * The exact pre-commit body the framework ships. Kept as a single string so
@@ -407,7 +412,7 @@ export function pruneLegacyEpicBaselines(ctx) {
 }
 
 /**
- * Run all five steps in order. Composable wrapper used by the bootstrap
+ * Run all six steps in order. Composable wrapper used by the bootstrap
  * and update workflows. Each step's outcome is returned under its own key
  * so callers can render a per-action summary.
  *
@@ -423,6 +428,7 @@ export function applyQualityBootstrap(ctx) {
     hook: ensurePreCommitHook(ctx),
     scripts: ensureQualityNpmScripts(ctx),
     config: ensureQualityConfigDefaults(ctx),
+    mergeDriver: ensureBaselineMergeDriver(ctx),
     legacyBaselines: pruneLegacyEpicBaselines(ctx),
   };
 }

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

@@ -121,6 +121,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'lint-issue-body.js',
   'lint-label-vocabulary.js',
   'mandrel-update-preflight.js',
+  'merge-baseline.js',
   'nav-registry-diff.js',
   'notify.js',
   'plan-context.js',

package/.agents/scripts/lib/orchestration/epic-container.js

@@ -33,23 +33,35 @@
 import { TYPE_LABELS } from '../label-constants.js';
 
 /**
- * The checklist grammar. `getSubTickets` (`providers/github/issues.js`)
- * already parses this exact form as its strategy-2 child source, so the
- * checklist is a durable mirror of the native sub-issue edges rather than a
- * second, competing representation: when the sub-issues API is unavailable
- * — an older GHES, a revoked scope, a partial write — the children are still
- * discoverable from the body alone.
- *
- * Kept in sync with `_getChecklistChildren` deliberately; a divergence here
- * would strand children the writer believes it linked.
+ * The checklist grammar: a checklist row, and the **first** issue reference
+ * anywhere on it. The checklist is a durable mirror of the native sub-issue
+ * edges rather than a second, competing representation — when the sub-issues
+ * API is unavailable (an older GHES, a revoked scope, a rate-limit burst) the
+ * children are still discoverable from the body alone.
+ *
+ * Deliberately the **loosest** of the three grammars that read this shape, and
+ * looser than it was: it used to require the id to be the whole row
+ * (`- [ ] #123`), which matched none of the annotated rows a hand-maintained
+ * rollout tracker actually carries — `- [ ] Design sign-off (#1897): pending`,
+ * `- [ ] 1.4 #1909 (Part B blocked)`. An Epic with 58 children presented three
+ * to the rollup, which closed it with 23 still open (Story #5210).
+ *
+ * It is NOT in sync with `_getChecklistChildren` (`providers/github/issues.js`)
+ * and no longer claims to be: that one is a general parent→child strategy for
+ * any issue and still requires `#N` immediately after the checkbox. Reading a
+ * superset here is safe in the direction that matters — a spurious id costs a
+ * skipped non-Story child, while a missed id costs a container closed over open
+ * work. The union with the native edges keeps both honest, and after #5210
+ * nothing irreversible is decided on this grammar alone.
  */
-const CHECKLIST_ITEM_RE = /^-\s*\[[ xX]\]\s+#(\d+)\s*$/gm;
+const CHECKLIST_ITEM_RE = /^-\s*\[[ xX]\]\s+.*?#(\d+)\b/gm;
 
 /**
  * The same grammar, unanchored to a global cursor — for callers testing one
- * line at a time. Kept beside its `/g` twin so the two cannot drift.
+ * line at a time. Kept beside its `/g` twin so the two cannot drift; the pair
+ * MUST accept the same line set, which `epic-container.test.js` pins.
  */
-export const CHECKLIST_ITEM_LINE_RE = /^-\s*\[[ xX]\]\s+#\d+\s*$/;
+export const CHECKLIST_ITEM_LINE_RE = /^-\s*\[[ xX]\]\s+.*?#\d+\b/;
 
 /** Heading the container's one prose section renders under. */
 const GOAL_HEADING = '## Goal';
@@ -180,12 +192,23 @@ export function readEpicChildIds(body) {
  * degrades to the checklist rather than propagating, since a body-derived
  * child list is a strictly better answer than an error.
  *
+ * **The degrade is reported, not hidden.** The result carries
+ * `nativeReadFailed`, because a truncated list and a genuinely small Epic are
+ * otherwise indistinguishable downstream — and one caller
+ * (`epic-rollup.js`) decides an irreversible close on the difference. A caller
+ * that only needs "who are the children" reads `ids` and ignores the flag;
+ * a caller about to do something it cannot undo MUST NOT.
+ *
+ * `nativeReadFailed` is false when no reader was injected: a caller that
+ * supplied none never asked for authority and is not degraded relative to what
+ * it requested.
+ *
  * @param {{
  *   epic: { number?: number, id?: number, body?: string, nodeId?: string },
  *   readNativeChildIds?: (epic: object) => Promise<number[]>,
  *   onWarn?: (message: string) => void,
  * }} opts
- * @returns {Promise<number[]>}
+ * @returns {Promise<{ ids: number[], nativeReadFailed: boolean }>}
  */
 export async function readEpicChildIdsFrom({
   epic,
@@ -193,18 +216,22 @@ export async function readEpicChildIdsFrom({
   onWarn,
 } = {}) {
   const fromBody = readEpicChildIds(epic?.body);
-  if (typeof readNativeChildIds !== 'function') return fromBody;
+  if (typeof readNativeChildIds !== 'function') {
+    return { ids: fromBody, nativeReadFailed: false };
+  }
 
-  let native = [];
   try {
-    native = normalizeChildIds(await readNativeChildIds(epic));
+    const native = normalizeChildIds(await readNativeChildIds(epic));
+    return {
+      ids: normalizeChildIds([...native, ...fromBody]),
+      nativeReadFailed: false,
+    };
   } catch (err) {
-    const id = epic?.number ?? epic?.id ?? '?';
     onWarn?.(
-      `[epic-container] native sub-issue read failed for Epic #${id} ` +
-        `(${err?.message ?? String(err)}); using the body checklist alone.`,
+      `[epic-container] native sub-issue read failed for Epic ` +
+        `#${epic?.number ?? epic?.id ?? '?'} (${err?.message ?? String(err)}); ` +
+        'using the body checklist alone — the child list may be incomplete.',
     );
+    return { ids: fromBody, nativeReadFailed: true };
   }
-
-  return normalizeChildIds([...native, ...fromBody]);
 }

package/.agents/scripts/lib/orchestration/epic-expansion.js

@@ -27,6 +27,32 @@ function isStoryTicket(issue) {
     .includes(TYPE_LABELS.STORY);
 }
 
+/**
+ * The error for an Epic that yielded no children.
+ *
+ * The two empty cases have different remedies, so they get different messages:
+ * an operator told to go link Stories that are already linked will do the wrong
+ * thing for what was really a transient API failure (Story #5210).
+ *
+ * @param {number} id
+ * @param {boolean} nativeReadFailed
+ * @returns {Error}
+ */
+function noChildrenError(id, nativeReadFailed) {
+  if (nativeReadFailed) {
+    return new Error(
+      `[resolve-stories] Epic #${id} expanded to no child Stories, but the ` +
+        `native sub-issue read failed — the list is incomplete, not empty. ` +
+        `Re-run once the GitHub API read succeeds.`,
+    );
+  }
+  return new Error(
+    `[resolve-stories] Epic #${id} lists no child Stories. An Epic is a container: ` +
+      `link its Stories (a "- [ ] #N" checklist line or a GitHub sub-issue) ` +
+      `or deliver the Story ids directly.`,
+  );
+}
+
 /**
  * Expand any container-Epic id in the requested set to its open child
  * Stories, leaving every other id untouched.
@@ -90,17 +116,13 @@ export async function expandEpicIds({
       continue;
     }
 
-    const childIds = await readEpicChildIdsFrom({
+    const { ids: childIds, nativeReadFailed } = await readEpicChildIdsFrom({
       epic: issue,
       readNativeChildIds,
       onWarn: warn,
     });
     if (childIds.length === 0) {
-      throw new Error(
-        `[resolve-stories] Epic #${id} lists no child Stories. An Epic is a container: ` +
-          `link its Stories (a "- [ ] #N" checklist line or a GitHub sub-issue) ` +
-          `or deliver the Story ids directly.`,
-      );
+      throw noChildrenError(id, nativeReadFailed);
     }
 
     const open = [];

package/.agents/scripts/lib/orchestration/epic-rollup.js

@@ -28,9 +28,18 @@
  *   3. **Never throws.** Every step degrades with a reason. A stale
  *      container costs tidiness; a delivery failed on a board mutation
  *      costs a landed Story its terminal envelope.
+ *   4. **Closure requires an authoritative child list.** Invariant 3 makes
+ *      every read degrade rather than fail, which is right for the writes
+ *      that recompute next tick and wrong for the one that does not. When
+ *      the native sub-issue read fails, the body checklist still answers
+ *      "who are the children" — but no longer "are these *all* of them",
+ *      and closing on that difference shut an Epic over 23 open children
+ *      (Story #5210). Degraded reads keep the Status and assignee writes
+ *      and lose only the close.
  *
  * @module lib/orchestration/epic-rollup
  * @see Story #5205
+ * @see Story #5210 — fail closed on a degraded child read.
  */
 
 import { Logger } from '../Logger.js';
@@ -120,6 +129,11 @@ function isClosed(issue) {
  * the list it is handed, so a silently dropped child could close a container
  * with work still open under it.
  *
+ * Note the scope: this validates the **readability of the ids it was given**,
+ * never the **completeness of the id list**. Completeness is
+ * `nativeReadFailed`'s job in {@link rollUpOneEpic} — checking only this one
+ * is what let three readable ids stand in for 58 (Story #5210).
+ *
  * @param {{ epicId: number, childIds: number[], provider: object }} opts
  * @returns {Promise<object[]|null>}
  */
@@ -214,10 +228,24 @@ async function applyClosure({ epicId, provider }) {
 /**
  * Roll one Epic up from the children it lists.
  *
- * @param {{ epic: object, childIds: number[], provider: object, columnSync: object, owner: string|null }} opts
+ * `nativeReadFailed` splits the writes by reversibility. Column and assignee
+ * are recomputed from scratch on every later tick, so applying them to a
+ * possibly-truncated list costs at most a stale board cell that self-corrects.
+ * Closure does not: it is the one write no subsequent tick undoes (invariant 2
+ * — a reopened child pulls Status back but MUST NOT reopen the issue), so it
+ * requires a child list we know to be complete.
+ *
+ * @param {{ epic: object, childIds: number[], nativeReadFailed?: boolean, provider: object, columnSync: object, owner: string|null }} opts
  * @returns {Promise<object>} Per-Epic outcome record.
  */
-async function rollUpOneEpic({ epic, childIds, provider, columnSync, owner }) {
+async function rollUpOneEpic({
+  epic,
+  childIds,
+  nativeReadFailed = false,
+  provider,
+  columnSync,
+  owner,
+}) {
   const epicId = Number(epic?.number ?? epic?.id);
   const outcome = {
     epicId,
@@ -261,6 +289,24 @@ async function rollUpOneEpic({ epic, childIds, provider, columnSync, owner }) {
 
   if (isClosed(epic)) return outcome;
 
+  if (nativeReadFailed) {
+    // Every child we could see has landed — but the authoritative read threw,
+    // so "every child" is exactly the claim we cannot make. `readChildren`
+    // above validates that the ids we were handed are *readable*; nothing
+    // there validates that the list is *complete*, which is how an Epic with
+    // 23 open children closed off the three its body happened to spell in the
+    // bare `- [ ] #N` form (Story #5210). Overwrites any column/owner detail
+    // deliberately: this is the reason the Epic is still pending.
+    outcome.pending = true;
+    outcome.detail = 'child-read-degraded';
+    Logger.warn(
+      `[epic-rollup] Epic #${epicId}: every child read looks done, but the ` +
+        'native sub-issue read degraded — refusing to close on a possibly ' +
+        'incomplete child list. Re-run once the API read succeeds.',
+    );
+    return outcome;
+  }
+
   const closure = await applyClosure({ epicId, provider });
   outcome.closed = closure.closed;
   outcome.pending = !closure.closed;
@@ -277,7 +323,7 @@ async function rollUpOneEpic({ epic, childIds, provider, columnSync, owner }) {
  * containers are few, and only one listing this Story is ever read further.
  *
  * @param {{ storyId: number, provider: object, skipEpicIds: Set<number> }} opts
- * @returns {Promise<Array<{ epic: object, childIds: number[] }>>}
+ * @returns {Promise<Array<{ epic: object, childIds: number[], nativeReadFailed: boolean }>>}
  */
 async function findEpicsForStory({ storyId, provider, skipEpicIds }) {
   let epics;
@@ -304,13 +350,25 @@ async function findEpicsForStory({ storyId, provider, skipEpicIds }) {
     // delivery expansion uses. Reading the body alone here is what made an
     // Epic whose children were linked in the GitHub UI expandable but
     // permanently unclosable.
-    const childIds = await readEpicChildIdsFrom({
+    const { ids: childIds, nativeReadFailed } = await readEpicChildIdsFrom({
       epic,
       readNativeChildIds: nativeChildReader(provider),
       onWarn: (message) => Logger.warn(message),
     });
-    if (!childIds.includes(storyId)) continue;
-    matches.push({ epic, childIds });
+    if (!childIds.includes(storyId)) {
+      // A degraded read can truncate this Story out of its own container's
+      // child list, which drops the Epic from the run entirely rather than
+      // rolling it up wrongly. Non-destructive, but silent — say so, since it
+      // is the same root cause as the refusal in `rollUpOneEpic`.
+      if (nativeReadFailed) {
+        Logger.warn(
+          `[epic-rollup] Epic #${epicId}: skipped for Story #${storyId} on a ` +
+            'degraded child read — the Story may in fact be linked to it.',
+        );
+      }
+      continue;
+    }
+    matches.push({ epic, childIds, nativeReadFailed });
   }
   return matches;
 }
@@ -374,11 +432,12 @@ export async function rollUpEpicForStory({
       owner === undefined ? resolveEpicOwner(config) : owner;
 
     const epics = [];
-    for (const { epic, childIds } of matches) {
+    for (const { epic, childIds, nativeReadFailed } of matches) {
       epics.push(
         await rollUpOneEpic({
           epic,
           childIds,
+          nativeReadFailed,
           provider,
           columnSync: sync,
           owner: resolvedOwner,