mandrel 2.46.0 → 2.48.0

package/.agents/scripts/single-story-init.js

@@ -55,6 +55,7 @@ import { getStoryBranch, gitSpawn, gitSync } from './lib/git-utils.js';
 import { Logger } from './lib/Logger.js';
 import { TYPE_LABELS } from './lib/label-constants.js';
 import { emitTerseResult } from './lib/observability/terse-result.js';
+import { rollUpEpicForStory } from './lib/orchestration/epic-rollup.js';
 import {
   executeFastForward,
   planFastForward,
@@ -223,6 +224,34 @@ async function flipStoryToExecuting(provider, storyId, story) {
   }
 }
 
+/**
+ * Roll any container Epic listing this Story up from its children.
+ *
+ * A container carries no `agent::*` label, so the Status sync that follows
+ * the flip above cannot reach it — its column is derived from its children
+ * instead. This is the edge where the first child of an Epic starts moving,
+ * which is what puts the Epic on the board as In Progress with an owner.
+ *
+ * Best-effort by construction: the rollup never throws, and a container left
+ * at a stale column must never cost the Story its init.
+ *
+ * @param {object} provider
+ * @param {number} storyId
+ * @param {object} config
+ * @returns {Promise<void>}
+ */
+async function rollUpContainerEpic(provider, storyId, config) {
+  const outcome = await rollUpEpicForStory({ storyId, provider, config });
+  for (const epic of outcome.epics) {
+    if (!epic.column) continue;
+    progress(
+      'EPIC',
+      `🗃️  Epic #${epic.epicId} → ${epic.column}` +
+        (epic.assigned ? ' (assigned)' : ''),
+    );
+  }
+}
+
 /**
  * Undo this run's claim when provisioning fails after the early
  * `agent::executing` flip: revert the label to `agent::ready` and release the
@@ -675,6 +704,12 @@ export async function runSingleStoryInit({
     // install window instead of reading agent::ready and double-dispatching.
     await flipStoryToExecuting(provider, storyId, story);
 
+    // Story #5205 — the child is now in flight, so any container Epic listing
+    // it is too. Fired here rather than after provisioning so the board shows
+    // In Progress for the whole install window, and after the flip so the
+    // rollup reads the state it derives from.
+    await rollUpContainerEpic(provider, storyId, config);
+
     // Any failure from here on leaves a claimed, executing-labelled Story with
     // no live run behind it — revert the label and release the lease so the
     // Story is not stranded as phantom-executing.

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

@@ -292,18 +292,40 @@ This executes, in order:
   (files issues when auto-file is on; posts `follow-ups`).
 - `sibling-coherence` — Spec/Acceptance coherence check across sibling bodies
   (`plan-run-sibling-coherence`).
-- `epic-close` — closes a container Epic once **every** child Story is
-  `agent::done`, as `completed`. This is the only completion cascade v2 has:
-  it closes the container and nothing else — no child status roll-up, no label
-  inheritance, no reopening. Because linkage is parent→child only, the parent
-  is found by scanning open `type::epic` issues, and only an Epic containing
-  one of *this run's* Stories is considered, so an unrelated container is
-  never swept. An Epic with an outstanding child is reported `pending` and
-  left open.
+- `epic-close` — **reports** which container Epics this run closed and which
+  are still pending. It derives nothing itself: every step here and the
+  per-Story land tail alike delegate to `epic-rollup.js`, so one rule decides
+  a container's state.
 
 A single-Story run skips the epilogue — follow-ups are captured on merge
 confirm instead (`captureStoryFollowUps`).
 
+## Container-Epic rollup (every N)
+
+A container Epic is never delivered, so nothing used to write to it during
+the run it was the subject of. `epic-rollup.js` derives its state from its
+children at both per-Story lifecycle edges — the `agent::executing` flip in
+`single-story-init.js` and the post-land tail (reported as the tail's
+`epicRollup` step) — which is why it holds at **N=1**, where no epilogue runs.
+
+- **Status** follows the children's composition (`deriveParentState` mapped
+  onto the board's three options): any child executing or blocked → `In
+  Progress`, every child `agent::done` or closed → `Done`. It is written
+  **directly**, never via a label: the container carries no `agent::*` label
+  by construction, which is what keeps it out of the bare `/mandrel-deliver`
+  ready list.
+- **Owner** — `github.operatorHandle` is added to the Epic while any child is
+  in flight, through the additive assignees endpoint, and is never removed.
+- **Closure** is one-way: every child landed closes the container as
+  `completed`; a reopened child moves Status back to `In Progress` and does
+  **not** reopen it.
+- The parent lookup scans open `type::epic` issues, because linkage is
+  parent→child only, and reads children as the body checklist **union** the
+  native sub-issue edges — the same reader `/mandrel-deliver`'s expansion
+  uses, so an Epic can never be expandable but unclosable.
+- Every step is best-effort and never throws: a stale container costs
+  tidiness, not a landed Story's envelope.
+
 ## Ceremony (profiles + two scopes)
 
 Ceremony depth is selected by `delivery.routing.ceremonyProfile`
@@ -323,7 +345,7 @@ sensitive-path classes in `audit-rules.json`
 | **Per-Story (always)** | Gates, branch discipline, close-and-land | `deliver-story` / `single-story-close` |
 | **Per-Story (profile + derived level)** | Acceptance critic mode; review depth | `ceremony-routing.js` + `review-depth.js` + `code-review.js` |
 | **Per-run (N>1)** | Audit roster · follow-up roll-up · sibling coherence | `plan-run-epilogue.js` once at run end |
-| **Per-Story land tail** | Follow-up capture · status resync · ref cleanup · base fast-forward | `single-story-close/phases/post-land.js` (in-process, per-step reported) |
+| **Per-Story land tail** | Follow-up capture · status resync · Epic rollup · ref cleanup · base fast-forward | `single-story-close/phases/post-land.js` (in-process, per-step reported) |
 
 ## Async merge-confirm mode (`delivery.mergeWatch.mode: "async"`)
 

package/.agents/workflows/mandrel-deliver.md

@@ -102,9 +102,9 @@ to an attended run.
 
 4. **Close each hand-off** (§ Closing what the workers hand back), then, with
    every Story landed, run the **per-run epilogue (N>1)**:
-   `node .agents/scripts/plan-run-epilogue.js --stories 101,102`, which also
-   closes a container Epic whose children all landed. N=1 skips it
-   ([reference](helpers/deliver-reference.md)).
+   `node .agents/scripts/plan-run-epilogue.js --stories 101,102`; N=1 has none
+   ([reference](helpers/deliver-reference.md)). Every close rolls its container
+   Epic up from its children.
 
 5. **Correct what the change invalidated.** If a memory you recalled this
    session is now wrong — a trap this landed, a budget it moved — fix that entry

package/docs/CHANGELOG.md

@@ -15,6 +15,25 @@ 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)
+
+
+### Added
+
+* roll a container Epic's board status, assignee and closure up from its child Stories ([#5205](https://github.com/dsj1984/mandrel/issues/5205)) ([#5206](https://github.com/dsj1984/mandrel/issues/5206)) ([38aae8b](https://github.com/dsj1984/mandrel/commit/38aae8bb4c273b258b420b463781970df18f58e1))
+
 ## [2.46.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.45.0...mandrel-v2.46.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.46.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/",