mandrel 2.47.0 → 2.48.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/docs/CHANGELOG.md

@@ -15,6 +15,18 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [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.48.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",