mandrel 2.47.0 → 2.49.0

package/.agents/scripts/merge-baseline.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+
+/**
+ * merge-baseline.js — git merge driver for `baselines/*.json` (Story #5215).
+ *
+ * ## The failure it replaces
+ *
+ * Every baseline write stamps `generatedAt` on line 4, so two branches that
+ * each refresh a baseline ALWAYS differ there — even when they moved
+ * completely disjoint rows. Git merges JSON as text, so whether it can
+ * separate that hunk from the moved rows is an accident of proximity:
+ *
+ *   - it cannot → a conflict on work that never overlapped (the observed
+ *     `coverage.json` / `maintainability.json` "always conflicts" pattern);
+ *   - it can → it splices both sides' row lines into a row set neither side
+ *     scored, and the ratchet then guards a number no scorer produced (the
+ *     observed `crap.json` "silently auto-merges" pattern).
+ *
+ * The quiet one is the worse one. A baseline is a set of rows keyed by
+ * identity plus a rollup derived from them, so this driver merges it as
+ * that — see `lib/baselines/merge-envelopes.js` for the semantics.
+ *
+ * ## Contract
+ *
+ *   node .agents/scripts/merge-baseline.js %O %A %B %P
+ *
+ * git's merge-driver calling convention: `%O` ancestor, `%A` ours (and the
+ * file the driver MUST leave its result in), `%B` theirs, `%P` the real
+ * pathname being merged. Exit 0 merged clean, non-zero conflicted.
+ *
+ * Registered per clone (registration is per-clone, so `mandrel doctor` is
+ * the guard that it happened, not `mandrel sync`):
+ *
+ *   .gitattributes:  baselines/*.json merge=mandrel-baseline
+ *   git config:      merge.mandrel-baseline.driver
+ *
+ * ## Not every `baselines/*.json` is an envelope
+ *
+ * That glob also matches arch-cycles, cyclomatic, dead-exports, audit-ledger,
+ * context-budget and workflow-citations — files with their own shapes and no
+ * row identity. Anything whose `$schema` is not a known per-kind envelope is
+ * handed straight back to `git merge-file`, so registering the driver cannot
+ * change their behaviour.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { assertEnvelope } from './lib/baselines/envelope.js';
+import {
+  kindFromEnvelope,
+  mergeEnvelopes,
+} from './lib/baselines/merge-envelopes.js';
+import { writeFile as writeEnvelopeFile } from './lib/baselines/writer.js';
+import { spawnChild } from './lib/child-exec.js';
+import { runAsCli } from './lib/cli-utils.js';
+
+/** Indent one row's canonical JSON to its position inside `rows`. */
+function rowBlock(row) {
+  return JSON.stringify(row, null, 2)
+    .split('\n')
+    .map((line) => `    ${line}`)
+    .join('\n');
+}
+
+/**
+ * Wrap each conflicting row in git conflict markers, leaving every other row
+ * merged. Operates on the canonical text the writer already produced, so the
+ * non-conflicting remainder of the file is byte-identical to what a clean
+ * merge would have written.
+ *
+ * @param {string} text Canonical serialization of the merged envelope.
+ * @param {Array<object>} conflicts Row-scoped conflict records.
+ * @returns {string}
+ */
+export function renderConflictMarkers(text, conflicts) {
+  let out = text;
+  for (const conflict of conflicts) {
+    const placed = conflict.ours ?? conflict.theirs;
+    if (placed === undefined) continue;
+    const block = rowBlock(placed);
+    // The row may or may not be the last element of `rows`; keep whichever
+    // separator follows it on both sides so the markers wrap whole lines.
+    const withComma = `${block},`;
+    const [needle, suffix] = out.includes(withComma)
+      ? [withComma, ',']
+      : [block, ''];
+    if (!out.includes(needle)) continue;
+    const ourSide =
+      conflict.ours === undefined
+        ? ''
+        : `${rowBlock(conflict.ours)}${suffix}\n`;
+    const theirSide =
+      conflict.theirs === undefined
+        ? ''
+        : `${rowBlock(conflict.theirs)}${suffix}\n`;
+    out = out.replace(
+      needle,
+      `<<<<<<< ours\n${ourSide}=======\n${theirSide}>>>>>>> theirs`.replace(
+        /\n$/,
+        '',
+      ),
+    );
+  }
+  return out;
+}
+
+/** Read and parse a merge input; a missing or empty side is `null`. */
+function readSide(file) {
+  if (!file || !fs.existsSync(file)) return null;
+  const raw = fs.readFileSync(file, 'utf8');
+  if (raw.trim() === '') return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return undefined; // present but unparseable — caller falls back to git
+  }
+}
+
+/**
+ * Hand the merge back to git's own text merge. Used for every
+ * `baselines/*.json` that is not a known per-kind envelope, and for one that
+ * is too damaged to parse — in both cases the driver must not invent a
+ * result, and git's behaviour is exactly what the repo had before.
+ *
+ * @returns {number} git merge-file's own exit code.
+ */
+function delegateToGit(basePath, oursPath, theirsPath) {
+  // `stdio: 'inherit'` so git's own conflict reporting reaches the operator
+  // exactly as it would have with no driver registered. `spawnChild` returns
+  // the RAW result deliberately: a `status` of null means the child was
+  // killed, and that must never be read as a clean merge.
+  const result = spawnChild(
+    'git',
+    ['merge-file', oursPath, basePath, theirsPath],
+    { stdio: 'inherit' },
+  );
+  if (result.error) {
+    process.stderr.write(
+      `merge-baseline: could not run git merge-file: ${result.error.message}\n`,
+    );
+    return 1;
+  }
+  return result.status ?? 1;
+}
+
+/**
+ * @param {string[]} argv Positional arguments: %O %A %B [%P].
+ * @returns {number} Process exit code.
+ */
+export function runMergeBaseline(argv) {
+  const [baseArg, oursArg, theirsArg, mergedPath] = argv;
+  if (!baseArg || !oursArg || !theirsArg) {
+    process.stderr.write(
+      'merge-baseline: expected the git merge-driver arguments %O %A %B %P\n',
+    );
+    return 2;
+  }
+
+  // Git hands the driver temp filenames RELATIVE to the worktree root it
+  // invokes us from (`.merge_file_xxxxxx`), so every path is resolved before
+  // use — the shared writer refuses a relative path, and that refusal only
+  // shows up under a real `git merge`, never when the driver is called
+  // directly with absolute paths.
+  const [basePath, oursPath, theirsPath] = [baseArg, oursArg, theirsArg].map(
+    (p) => path.resolve(p),
+  );
+
+  const ours = readSide(oursPath);
+  const theirs = readSide(theirsPath);
+  const base = readSide(basePath);
+
+  const kind = kindFromEnvelope(ours) ?? kindFromEnvelope(theirs);
+  if (!kind || ours === undefined || theirs === undefined) {
+    return delegateToGit(basePath, oursPath, theirsPath);
+  }
+
+  let merged;
+  try {
+    merged = mergeEnvelopes({ base, ours, theirs, kind });
+  } catch (err) {
+    process.stderr.write(`merge-baseline: ${kind}: ${err.message}\n`);
+    return delegateToGit(basePath, oursPath, theirsPath);
+  }
+
+  const rowConflicts = merged.conflicts.filter((c) => c.scope === 'row');
+  const envelopeConflicts = merged.conflicts.filter(
+    (c) => c.scope === 'envelope',
+  );
+
+  // Write the canonical projection first even when conflicted: the marker
+  // rendering operates on exactly the bytes a clean merge would have left,
+  // so the merged remainder of a conflicted file is identical to it.
+  writeEnvelopeFile(oursPath, merged.envelope);
+
+  if (merged.conflicts.length === 0) {
+    assertEnvelope(merged.envelope);
+    return 0;
+  }
+
+  const label = mergedPath || oursPath;
+  for (const conflict of envelopeConflicts) {
+    process.stderr.write(
+      `merge-baseline: conflict ${kind} envelope key "${conflict.identity}" in ${label} — ours ${JSON.stringify(conflict.ours)}, theirs ${JSON.stringify(conflict.theirs)}\n`,
+    );
+  }
+  for (const conflict of rowConflicts) {
+    process.stderr.write(
+      `merge-baseline: conflict ${kind} row "${conflict.identity}" in ${label}\n`,
+    );
+  }
+
+  if (rowConflicts.length > 0) {
+    const text = fs.readFileSync(oursPath, 'utf8');
+    fs.writeFileSync(oursPath, renderConflictMarkers(text, rowConflicts));
+  }
+  return 1;
+}
+
+function main() {
+  return runMergeBaseline(process.argv.slice(2));
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'merge-baseline',
+  propagateExitCode: true,
+  usage: {
+    invocation: 'node .agents/scripts/merge-baseline.js %O %A %B %P',
+    summary:
+      'Git merge driver for baselines/*.json. Merges per-kind envelopes by ROW IDENTITY — disjoint refreshes merge clean, the rollup is recomputed from the merged rows, and generatedAt resolves to the later stamp instead of conflicting. A baselines file that is not a known per-kind envelope is handed back to git merge-file unchanged. Exit 0 clean, 1 conflicted.',
+    flags: [
+      ['%O', 'Merge ancestor (git supplies this).'],
+      ['%A', 'Our version — the driver writes its result here.'],
+      ['%B', 'Their version.'],
+      ['%P', 'Real pathname being merged; used in conflict messages.'],
+    ],
+  },
+});

package/.agents/scripts/providers/github/errors.js

@@ -87,17 +87,67 @@ function matchesAny(haystack, needles) {
   return false;
 }
 
+/** `gh` renders the HTTP status onto stderr as `HTTP 403: <reason>`. */
+const GH_STDERR_STATUS_RE = /\bHTTP (\d{3})\b/i;
+
+/**
+ * The captured `gh` stderr, or `''` when the error carries none.
+ *
+ * Its own function so {@link extractErrorFields} keeps the cyclomatic weight it
+ * had before stderr became a classification input — the field is read twice
+ * there, and inlining the guard twice is what pushed the CRAP ratchet.
+ *
+ * @param {unknown} err
+ * @returns {string}
+ */
+function stderrText(err) {
+  return typeof err?.stderr === 'string' ? err.stderr : '';
+}
+
 /**
- * Extract `{ lower, status, code }` from an error in the shape `gh-exec`
- * throws. Pure — exported style for unit-testability without instantiating
- * the provider. Defensive on shape: errors arrive as `Error` objects, plain
- * `{message,status,code}` bags, or non-Errors stringified into `String(err)`.
+ * Recover the HTTP status from a `gh`-CLI failure's stderr.
+ *
+ * The `fetch` transport sets `err.status`; the `gh` transport does not — it
+ * has only an exit code, and puts the status in the text it printed. Without
+ * this, every `gh`-path failure reached the status rules as `undefined` and a
+ * 403 or a 429 was indistinguishable from an unclassifiable error (Story
+ * #5210).
+ *
+ * @param {unknown} stderr
+ * @returns {number|undefined}
+ */
+function statusFromStderr(stderr) {
+  if (typeof stderr !== 'string') return undefined;
+  const m = GH_STDERR_STATUS_RE.exec(stderr);
+  return m ? Number.parseInt(m[1], 10) : undefined;
+}
+
+/**
+ * Extract `{ lower, detail, status, code }` from an error in the shape
+ * `gh-exec` throws. Pure — exported style for unit-testability without
+ * instantiating the provider. Defensive on shape: errors arrive as `Error`
+ * objects, plain `{message,status,code}` bags, or non-Errors stringified into
+ * `String(err)`.
+ *
+ * `lower` is the message alone. `detail` is the message **plus** any captured
+ * `stderr`, and is what the keyword rules read: on the `gh` path the message
+ * is the classified summary (`gh-exec: gh exited with code 1`) and every
+ * actionable word — the status line, `secondary rate limit`, the missing
+ * GraphQL field — lives only on stderr. Matching the keyword lists against the
+ * message alone is what flattened a retryable 403 to `permanent` and let the
+ * Epic rollup treat a rate-limit burst as a settled answer (Story #5210).
  */
 export function extractErrorFields(err) {
   const message = typeof err.message === 'string' ? err.message : String(err);
+  const stderr = stderrText(err);
+  const lower = message.toLowerCase();
   return {
-    lower: message.toLowerCase(),
-    status: typeof err.status === 'number' ? err.status : undefined,
+    lower,
+    // Unconditional concatenation: with no stderr this is the message plus a
+    // trailing space, which every `includes` rule below reads identically.
+    detail: `${lower} ${stderr.toLowerCase()}`,
+    status:
+      typeof err.status === 'number' ? err.status : statusFromStderr(stderr),
     code: typeof err.code === 'string' ? err.code : undefined,
   };
 }
@@ -127,17 +177,23 @@ export function classifyGithubError(err) {
   // no `.status` / `.code`. Match by `err.name` to avoid a circular import
   // between this module and `lib/gh-exec.js`. Story #2860.
   if (err.name === 'GhExecTimeoutError') return 'transient';
-  const { lower, status, code } = extractErrorFields(err);
-  if (matchesAny(lower, FEATURE_DISABLED_MESSAGES)) return 'feature-disabled';
+  // Every keyword rule below reads `detail` (message + stderr), never `lower`
+  // alone: the `gh` transport carries its reason exclusively on stderr, so a
+  // message-only match sees nothing but the exit code. Rule ORDER is
+  // load-bearing and unchanged — a secondary rate limit is delivered as HTTP
+  // 403, so the transient rules must stay ahead of the permission rule or it
+  // would bucket as 'permission' and never retry.
+  const { detail, status, code } = extractErrorFields(err);
+  if (matchesAny(detail, FEATURE_DISABLED_MESSAGES)) return 'feature-disabled';
   if (isTransientStatus(status)) return 'transient';
-  if (isTransientByCodeOrMessage(code, lower)) return 'transient';
+  if (isTransientByCodeOrMessage(code, detail)) return 'transient';
   // Union with the former `transient-retry.js` predicate (Story #4298):
   // retry on network/connectivity blips the status/code checks above miss
   // (e.g. a `dial tcp ... i/o timeout` on `err.stderr` from the gh-CLI path,
   // or `ECONNREFUSED` / `ENETUNREACH`). Checked before the permission rule so
   // a transient network failure never masquerades as a permanent denial.
   if (isTransientNetworkError(err)) return 'transient';
-  if (isPermissionSignal(status, lower)) return 'permission';
+  if (isPermissionSignal(status, detail)) return 'permission';
   return 'permanent';
 }
 

package/.agents/scripts/providers/github/sub-issues.js

@@ -23,6 +23,7 @@
  * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
  */
 
+import { describeGhFailure } from '../../lib/gh-exec.js';
 import { Logger } from '../../lib/Logger.js';
 import {
   classifyGithubError as defaultClassifyGithubError,
@@ -104,8 +105,14 @@ export class SubIssueGateway {
         );
         return [];
       }
+      // `describeGhFailure`, not `err.message`: on the gh transport the
+      // message is only the classified summary (`gh exited with code 1`) and
+      // the actionable sentence — the HTTP status, the rate-limit notice — is
+      // on stderr. Three identical opaque lines are what made the Epic-rollup
+      // incident unreadable until the API was queried by hand (Story #5210).
       Logger.error(
-        `[GitHubProvider] sub-issues GraphQL failed (parent #${parentId}, category=${category}): ${err.message}`,
+        `[GitHubProvider] sub-issues GraphQL failed (parent #${parentId}, ` +
+          `category=${category}): ${describeGhFailure(err)}`,
       );
       throw err;
     }

package/.agents/workflows/helpers/deliver-digest.md

@@ -1,10 +1,9 @@
 ---
 description: >-
-  The deliver path's one bundled framework read. Carries what
-  every Story delivery always needs — dispatch decision, engine invariants,
-  the change-set/ceremony incantation, the acceptance-eval gate, the credited
-  full-suite run, and the terminal envelope contract — so the engine reads one
-  file instead of re-reading the helper/schema set each session.
+  The deliver path's one bundled framework read: dispatch decision, engine
+  invariants, the change-set/ceremony incantation, the acceptance-eval gate,
+  the credited full-suite run, and the terminal envelope contract — the
+  engine reads one file, not the helper/schema set, each session.
 ---
 
 # Deliver digest (read once per session)
@@ -23,9 +22,9 @@ Read `stories[].dispatchMode` from the `resolve-stories.js` envelope.
 `inline` names one indivisible resource — **the router's own session** — so one
 rule produces it:
 
-1. **Run topology.** A run resolving **one** Story is `inline`
-   whatever its shape — sub-agent isolation is load-bearing only against a
-   *concurrent* sibling racing the same checkout, and a one-Story run has none.
+1. **Run topology.** A run resolving **one** Story is `inline` whatever its
+   shape — sub-agent isolation only matters against a *concurrent* sibling
+   racing the same checkout, and a one-Story run has none.
 2. **Every other run is `subagent`.** A multi-Story run dispatches every Story
    as a sub-agent however trivial its shape. Shape still sets ceremony; the
    `route::lite` label is a human-visible hint, never the control signal.
@@ -67,8 +66,8 @@ node --input-type=module -e '
   const { level, classes } = deriveChangeLevel({ changedFiles: files });
   // resolveCeremonyForRisk({ derivedLevel, clusterIndex?, freshCriticSampleRate?,
   //   ceremonyProfile? }) -> { mode, reason, sampled, profile, verdictOwner }.
-  // derivedLevel is that level STRING. Handing it the object above matches no
-  // tier, so it routes to the null fail-safe: a fresh critic, silently.
+  // derivedLevel is that level STRING — the object above matches no tier and
+  // routes to the null fail-safe: a fresh critic, silently.
   const ceremony = resolveCeremonyForRisk({ derivedLevel: level, clusterIndex: 0 });
   console.log(JSON.stringify({ files, level, classes, ...ceremony }));
 '
@@ -96,11 +95,8 @@ every cluster's records into a single `criteria[]` in `acceptance[]` order, one
 per acceptance item, and score that once. A gate call per cluster spends a
 round *per cluster* and races the round ledger:
 
-```bash
-node <main-repo>/.agents/scripts/acceptance-eval.js \
-  --story <storyId> --verdict <merged-verdict-path> \
-  --expected-criteria <acceptance[] count>
-```
+`node <main-repo>/.agents/scripts/acceptance-eval.js --story <storyId>
+--verdict <merged-verdict-path> --expected-criteria <acceptance[] count>`
 
 Pass `--expected-criteria` — **without it the coverage assertion is inert**, so
 an unmerged cluster verdict scores a fraction of the criteria and still reports
@@ -115,20 +111,27 @@ Per-round mechanics: [`acceptance-self-eval.md`](acceptance-self-eval.md).
 **After the self-eval loop's last fix commit, immediately before the push** —
 the credit is keyed on the tree, so any later commit invalidates it. Redraft
 rounds run scoped tests; only this final run needs credit, and a bare
-`npm test` / `pnpm run test` deposits **none**, so close re-runs the identical
-suite. Shape it by the predicate `close-validation/gates.js` uses for its test
-gate:
+`npm test` / `pnpm run test` deposits **none**, so close re-runs it. Shape it
+by what `close-validation/gates.js` runs:
 
 ```bash
-# CRAP gate on (default) + a `test:coverage` script — writes the stamp the
-# close `coverage-capture` gate reads:
+# CRAP gate on (default) + a `test:coverage` script — writes close's stamp:
 node <main-repo>/.agents/scripts/coverage-capture.js --cwd <workCwd>
-# otherwise — the record the close `test` gate reads. <workCwd> ABSOLUTE,
-# runner exactly `npm test`: both sides hash {cmd, args, cwd}.
+# otherwise — the record close's `test` gate reads; <workCwd> ABSOLUTE,
+# runner exactly `npm test` (both sides hash {cmd, args, cwd}):
 node <main-repo>/.agents/scripts/evidence-gate.js --standalone \
   --scope-id <storyId> --gate test --worktree <workCwd> -- npm test
 ```
 
+Dispatch it in the **background**: it outruns the host's synchronous Bash
+ceiling, and its completion re-invokes you. Never spawn a task to poll or
+`sleep`-loop against it ([`parallel-tooling.md`](parallel-tooling.md)
+Rule 2).
+
+Read the **output**, not the exit code: capture skips — no test run, no
+credit — when nothing changed under the CRAP `targetDirs`, so run the suite
+yourself before handing off.
+
 `verify[]` is scoped entries **plus** this one run: an entry that is itself a
 full-suite command is reported credited against the same stamp, never
 respawned.
@@ -162,7 +165,8 @@ restores live streaming.
 
 ## 7. When to leave this file
 
-- Unclear state / a re-run refusal → `deliver-recover.js --story <id>` (read-only).
-- Lease, sweep, worktree-scope detail → [`deliver-story-reference.md`](deliver-story-reference.md).
-- CI red after the PR opens → [`rules/ci-remediation.md`](../../rules/ci-remediation.md).
-- Sequencing, epilogue, checklist threading → [`deliver-reference.md`](deliver-reference.md).
+Unclear state / a re-run refusal → `deliver-recover.js --story <id>`
+(read-only). Lease, sweep, worktree scope; sequencing, epilogue, checklist
+threading → [`deliver-story-reference.md`](deliver-story-reference.md) and
+[`deliver-reference.md`](deliver-reference.md). CI red after the PR opens →
+[`rules/ci-remediation.md`](../../rules/ci-remediation.md).

package/.agents/workflows/helpers/parallel-tooling.md

@@ -47,6 +47,23 @@ the full duration and blocks every other parallel opportunity.
 - **Don't poll with `sleep`:** `Monitor` returns on each stdout line. Loop
   on `until <condition>; do sleep 2; done` only when no event stream is
   available — never as a substitute for the event channel.
+- **A hand-rolled waiter outlives the agent that spawned it.** Prefer the
+  completion notification: it is the signal, and needs no waiter at all. Two
+  measured failure shapes, both from one delivery run whose waiters were
+  still listed running nearly eight hours after their agent had finished and
+  its worktree had been deleted:
+  - An `until` guard that inverts to permanently-false the moment the run
+    **succeeds** — `until [ -n "$(grep -l 'Test Files' $LOG)" ] && ! grep -q
+    'Test Files' $LOG` exits only while the log both has and lacks the same
+    marker.
+  - `pgrep -f <literal>` matching the waiter's **own** command line, so it
+    finds itself and concludes the work is still running. Forever.
+
+  The tell is a task file of **0 bytes** with no backing process. If you must
+  wait, hold the PID and test `kill -0 "$PID"`, or break the self-match with
+  a bracketed pattern (`pgrep -f "[m]y-script.js"`) — and always bound the
+  loop with a maximum iteration count so a wrong condition ends the wait
+  instead of the agent.
 
 ## Rule 3 — N parallel `Agent` calls in one turn for N independent units
 

package/docs/CHANGELOG.md

@@ -15,6 +15,31 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.49.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.48.0...mandrel-v2.49.0) (2026-09-08)
+
+
+### Added
+
+* give story-worker a reachable long-command dispatch contract so the credited suite run stops growing hand-rolled waiters ([#5219](https://github.com/dsj1984/mandrel/issues/5219)) ([#5220](https://github.com/dsj1984/mandrel/issues/5220)) ([e2bb9eb](https://github.com/dsj1984/mandrel/commit/e2bb9eba8aaaf49ecf0d8069f36fc4438edf5e40))
+* write improved maintainability rows back at land time so upward baseline drift stops accumulating ([#5224](https://github.com/dsj1984/mandrel/issues/5224)) ([#5227](https://github.com/dsj1984/mandrel/issues/5227)) ([95d2e38](https://github.com/dsj1984/mandrel/commit/95d2e38db7fe87c410dbb40d43818e31ee80a497))
+
+
+### Fixed
+
+* tell the worker what to do when the credited full-suite command legitimately skips ([#5225](https://github.com/dsj1984/mandrel/issues/5225)) ([#5226](https://github.com/dsj1984/mandrel/issues/5226)) ([330ecaf](https://github.com/dsj1984/mandrel/commit/330ecaf6001755a515c45f69a495310d8b65643a))
+
+## [2.48.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.47.0...mandrel-v2.48.0) (2026-09-08)
+
+
+### Added
+
+* baselines: merge concurrent refreshes by row identity with a git merge driver ([#5215](https://github.com/dsj1984/mandrel/issues/5215)) ([#5216](https://github.com/dsj1984/mandrel/issues/5216)) ([bcc7057](https://github.com/dsj1984/mandrel/commit/bcc7057d8aad647ec4dae0dc859dd35865fe40a5))
+
+
+### Fixed
+
+* never close a container Epic on a degraded child read, and stop flattening gh transport failures to permanent ([#5210](https://github.com/dsj1984/mandrel/issues/5210)) ([#5212](https://github.com/dsj1984/mandrel/issues/5212)) ([08520d7](https://github.com/dsj1984/mandrel/commit/08520d7b5ca0962f98042ca4b103cf0c295516cf))
+
 ## [2.47.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.46.0...mandrel-v2.47.0) (2026-09-07)
 
 

package/lib/cli/registry.js

@@ -25,6 +25,11 @@ import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import {
+  BASELINE_MERGE_DRIVER_CONFIG_KEY,
+  BASELINE_MERGE_DRIVER_REMEDY,
+  declaresBaselineMergeDriver,
+} from '../../.agents/scripts/lib/bootstrap/baseline-merge-driver.js';
 import {
   REQUIRED_NODE_CEILING_MAJOR,
   REQUIRED_NODE_FLOOR,
@@ -1074,6 +1079,60 @@ function runVersionCurrent({ cachePath, installedVersion, fsImpl = fs } = {}) {
 // Registry
 // ---------------------------------------------------------------------------
 
+/**
+ * Is this clone's `baselines/*.json` merge driver actually registered?
+ *
+ * The two halves of that registration live in different places on purpose.
+ * `.gitattributes` is tracked, so the "use the driver" half ships with the
+ * repo; the driver COMMAND is per-clone `git config`, because git will not
+ * execute a command chosen by whoever wrote the repository. A fresh clone
+ * therefore has the first half and not the second — and git reports nothing
+ * at all, it just quietly falls back to text-merging baselines, which is the
+ * behaviour the driver exists to replace.
+ *
+ * Silent degradation is why this is a doctor check rather than a one-time
+ * install step. It is scoped to repos that opted in: when `.gitattributes`
+ * does not declare the driver, the check passes as skipped, so a consumer
+ * who never installed the quality surface is not told to fix something they
+ * did not ask for.
+ *
+ * @param {{cwd?: () => string, fsImpl?: typeof fs, runner?: typeof spawn}} [opts]
+ * @returns {{ ok: boolean, detail: string, remedy?: string }}
+ */
+export function runMergeDriver({ cwd, fsImpl = fs, runner = spawn } = {}) {
+  const projectRoot = (cwd ?? (() => process.cwd()))();
+  const attributesPath = path.join(projectRoot, '.gitattributes');
+
+  let attributes = '';
+  try {
+    attributes = fsImpl.readFileSync(attributesPath, 'utf8');
+  } catch {
+    attributes = '';
+  }
+  if (!declaresBaselineMergeDriver(attributes)) {
+    return {
+      ok: true,
+      detail:
+        'skipped — .gitattributes does not route baselines/*.json through the mandrel merge driver',
+    };
+  }
+
+  const configured = runner('git', [
+    'config',
+    '--get',
+    BASELINE_MERGE_DRIVER_CONFIG_KEY,
+  ]);
+  if (configured.status === 0 && configured.stdout.trim() !== '') {
+    return { ok: true, detail: configured.stdout.trim() };
+  }
+
+  return {
+    ok: false,
+    detail: `${BASELINE_MERGE_DRIVER_CONFIG_KEY} is unset — baselines/*.json will fall back to git's text merge, which conflicts on the generatedAt stamp and can splice rows neither branch scored`,
+    remedy: BASELINE_MERGE_DRIVER_REMEDY,
+  };
+}
+
 /**
  * Ordered array of doctor checks. Each entry follows the
  * `{ name: string, run(opts?): { ok: boolean, detail: string, remedy?: string } }` contract.
@@ -1123,6 +1182,10 @@ export const registry = [
     name: 'agents-drift',
     run: (opts) => runAgentsDrift(opts),
   },
+  {
+    name: 'merge-driver',
+    run: (opts) => runMergeDriver(opts),
+  },
   {
     name: 'pin-current',
     // Fatal, unlike version-current below (Story #4525/#4530): a pin/install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.47.0",
+  "version": "2.49.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",