mandrel 2.54.0 → 2.56.0

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

@@ -49,6 +49,13 @@ issue state rather than against anything you hand it. That is why there is no
 batch label to pass and why a blocker that landed in an unrelated run is simply
 seen as done.
 
+**A Story with no `agent::*` label is refused.** The audit sweep files Stories
+deliberately without one — their bodies are audit prose, not a scoped change
+with verifiable acceptance criteria — so resolving one means dispatching a
+worker at an unenriched body, after taking its lease. Route it through
+`/mandrel-plan` first, which applies `agent::ready` at the end of planning.
+`--allow-unlabelled` is the deliberate escape hatch.
+
 **The non-zero exit codes.** **2** — `cycleError`: the graph is
 self-referential; fix `depends_on`, do not retry. **3** — `wedged`: nothing
 dispatchable and nothing in flight, with the undone Stories and their unmet
@@ -292,10 +299,10 @@ 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` — **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.
+- `epic-close` — **reports** which of the run's container Epics its land tails
+  left closed and which are still open. **Read-only** — it derives nothing:
+  every child state change is already a rollup edge, so the container was
+  derived from a complete child set by the last Story's own land tail.
 
 A single-Story run skips the epilogue — follow-ups are captured on merge
 confirm instead (`captureStoryFollowUps`).
@@ -304,9 +311,12 @@ confirm instead (`captureStoryFollowUps`).
 
 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.
+children at **every edge that changes a child's state** — the
+`agent::executing` flip in `single-story-init.js`, the post-land tail
+(reported as the tail's `epicRollup` step), and `plan-persist`'s supersede
+close (reported as `supersede.epicRollup`) — which is why it holds at **N=1**,
+where no epilogue runs, and why a cohort superseded by a re-plan no longer
+strands its container open above finished work.
 
 - **Status** follows the children's composition (`deriveParentState` mapped
   onto the board's three options): any **open** child executing or blocked →
@@ -319,13 +329,24 @@ children at both per-Story lifecycle edges — the `agent::executing` flip in
   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.
+- **Closure** is one-way: a container whose children are all finished closes,
+  as `completed` when at least one child landed and as `not_planned` when none
+  did (a cohort superseded by a re-plan is finished, but nothing merged). A
+  reopened child moves Status back to `In Progress` and does **not** reopen the
+  issue — which is why the lookup reads `state: 'all'`, since an open-only
+  listing cannot see the container it would have to correct.
+- The parent lookup resolves the native parent edge in **one** call
+  (`getParentIssue`), because linkage is parent→child only; it falls back to a
+  `type::epic` scan for a child linked by checklist alone. Children are read as
+  the body checklist **union** the native sub-issue edges — literally the same
+  reader `/mandrel-deliver`'s expansion uses, so an Epic can never be
+  expandable but unclosable — bounded at 5 concurrent reads.
+- A checklist row citing an id that resolves to nothing is **dropped with a
+  warning** when the native read succeeded: hand-edited prose can cite a
+  deleted or mistyped issue, and no re-run will make it resolve. An
+  unresolvable *native* edge still fails the read. An Epic-typed child is
+  refused by name (`epic-typed-child`) and neither blocks nor advances the
+  parent.
 - Every step is best-effort and never throws: a stale container costs
   tidiness, not a landed Story's envelope.
 

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

@@ -240,9 +240,10 @@ discovers them only after the whole close pipeline has run, at several times
 the cost of one full-suite run in the worktree.
 
 **Run it once, last, so close can credit it.** The run belongs **after** the
-self-eval loop's last fix commit and immediately **before** the hand-off push,
-so its stamp describes the tree that is pushed; redraft rounds run scoped
-tests. Close skips a gate that already passed at the current HEAD, but a bare
+self-eval loop's last fix commit and **after** the hand-off push — the credit
+is keyed on the tree, not on push state, so pushing first keeps the stamp and
+buys the ordering Step 2.5 needs (the capture is backgrounded, and its
+completion ends the turn); redraft rounds run scoped tests. Close skips a gate that already passed at the current HEAD, but a bare
 `npm test` deposits no such record — the suite then runs twice per delivery,
 once here and once in the close gate chain. Pick the invocation by the same
 predicate `close-validation/gates.js` uses to choose its test gate:
@@ -262,7 +263,9 @@ The credit expires the moment it stops describing the tree: evidence is keyed
 on HEAD, the capture stamp on a content digest of `crap.targetDirs`. A
 self-eval fix — or any commit — invalidates it and close re-runs the suite for
 real, so this never trades away the gate. That keying is exactly why the run
-comes last.
+comes last, and why the push before it is free. Close's own base-sync can
+spend the stamp too when it lands base commits; it now says so out loud rather
+than silently re-running the suite.
 
 **`verify[]` reuses the same stamp.** A `verify[]` entry that is itself a
 full-suite command is reported **credited** against that stamp rather than
@@ -679,13 +682,28 @@ When the watch exits, branch on the exit code:
 
 **Triage authority.** How to classify and remediate a red (or repeatedly slow)
 check — the root-cause-only decision tree for infra/transient and flaky failures
-(reproduce → check `main` → bisect env vs code → fix in-scope or file a
-`meta::framework-gap` issue), the never-rerun / never-quarantine prohibitions,
-and the escalation criteria (three-strikes, the 30-minute wall-clock timebox,
-and the clearly-environmental fast path) — is defined once in
+(reproduce → check `main` → bisect env vs code → fix in-scope, or reach an
+Option-2 verdict and file the intake issue), the never-rerun / never-quarantine
+prohibitions, and the escalation criteria (three-strikes, the 30-minute
+wall-clock timebox, and the clearly-environmental fast path) — is defined once in
 [`.agents/rules/ci-remediation.md`](../../rules/ci-remediation.md). Read it
 before remediating a red check.
 
+**Filing an out-of-scope root cause is one command, never a hand-run `gh issue
+create`:**
+
+```bash
+node <agentRoot>/scripts/file-ci-gap.js --story <storyId> \
+  --verdict <pre-existing|capacity|unreproducible-tier> \
+  --owner <consumer|framework|platform> --evidence "<proof reading>" [--block]
+```
+
+It reads the digest, routes the filing to the repo that owns the fault, updates
+the existing ticket when the signature is a repeat, posts the `friction`
+comment, and with `--block` flips the Story. What it files is an **intake**
+issue, not a Story — `/mandrel-plan <issue number>` graduates it on the next
+planning pass, so the delivery never waits on planning.
+
 ### The auto-merge wait is an internally-blocking step
 
 This is the single most important contract of this workflow, and the seam

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

@@ -93,18 +93,21 @@ are reference § Step 2. Hard gates always run in Step 3 — the derived level
 never disables them; do **not** pre-run the chain here — Step 2.5's credited
 suite run is the sole exception.
 
-### Step 2.5 — The creditable full-suite run, then push and hand off
-
-Run the full suite **once**, after the self-eval loop's last fix commit and
-immediately **before** the push, in the shape close credits (**digest § 5**):
-the credit is keyed on the tree, so any later commit invalidates it, and a bare
-`npm test` deposits none. Red → fix, commit, re-run. An inline run makes the
-same run before Step 3.
-
-Then (sub-agent dispatch only) push `story-<storyId>` to `origin`, confirm the
-remote ref moved, and return the hand-off — Story id, `workCwd`, branch, pushed
-head SHA, self-eval verdict, `verify[]` evidence — then stop. Do not open the
-PR; do not compose a terminal envelope.
+### Step 2.5 — Push, then the creditable full-suite run, then hand off
+
+**Push first.** After the self-eval loop's last fix commit, push
+`story-<storyId>` to `origin`, confirming the remote ref moved: the capture
+below is backgrounded, so *its* completion ends the turn.
+
+Then run the full suite **once**, after the push, in the shape close credits
+(**digest § 5**): the credit is keyed on the tree, not on push state, so only
+a *later* commit invalidates it; a bare `npm test` deposits none. Red →
+fix, commit, push, re-capture.
+
+Then (sub-agent dispatch only) return the hand-off — Story id, `workCwd`,
+branch, pushed head SHA, self-eval verdict, `verify[]` evidence — and stop.
+Do not open the PR or compose a terminal envelope. An inline run captures
+before Step 3.
 
 ## Step 3 — Close and land (`single-story-close.js`)
 

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

@@ -92,6 +92,36 @@ The marker keeps the operator's undelegated decisions findable after the
 fact: reviewing a `--yes` plan means scanning its decisions-made-by-default,
 not re-deriving which assumptions were really the agent's to make.
 
+## Gate #1 → the memory-pool advisory (`memoryPoolAdvisory`)
+
+On a truthy `memoryPoolAdvisory.recommend`, name
+[`/memory-consolidate`](../memory-consolidate.md) at Gate #1, quoting its
+`reasons[]`. Purely advisory: a stale pool degrades recall, it does not make
+the plan wrong, so it never blocks and never reroutes.
+
+## Gate #1 → graduating a CI-gap intake filing (`intake`)
+
+The envelope's `priorFeedback` arrays carry the open `meta::*` feedback issues.
+A row flagged `intake: true` is a **CI-gap intake filing** — written by
+[`file-ci-gap.js`](../../scripts/file-ci-gap.js) when a delivery reached an
+Option-2 verdict in [`ci-remediation.md`](../../rules/ci-remediation.md) and the
+root cause was outside its scope. It carries evidence (failure signature, run
+link, occurrence history, ownership routing) but **no `## Spec`, no
+`acceptance[]` / `verify[]` and no `agent::*` label**, so `/mandrel-deliver`
+cannot take it: it is intake awaiting graduation, by design. Delivery files it
+and moves on rather than blocking on a planning pass nobody is present for.
+
+Graduating one is exactly **tickets mode**: `/mandrel-plan <issue number>`
+rewrites it into a Story, `supersedes[]` claims it, and persist closes it.
+
+At Gate #1, in **ask** and **seed** mode, name any open intake rows and offer
+that instead of the seed in front of you — a filing that keeps recurring
+(its `## Occurrences` table is the count) is usually the better next Story than
+whatever prompted this run. It is **advisory**: never reroute automatically, and
+skip the offer entirely under `--yes`, where nobody is at the keyboard to take
+it. A `platformGaps[]` row is the same shape with a different owner — the
+Story it graduates into may well be a config or runbook change rather than code.
+
 ## Gate #1 → the light path (in-session handoff)
 
 On a confirmed `deliverLightSuggestion`, `/mandrel-plan` routes into

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

@@ -25,8 +25,7 @@ mode from what the operator typed, announce it, act**:
 
 **Resolving a bare id.** Read live state rather than asking: `agent::done` can
 only be amended, an open unplanned issue only planned. **Announce the
-derivation** — "4712 is `agent::done` → amending". Ask **only** for an open
-Story already at `agent::ready`.
+derivation**. Ask **only** for an open Story already at `agent::ready`.
 
 ## Saying what you want
 
@@ -59,10 +58,9 @@ and derives source ids from its `sourceTickets[]`; it also writes
 
 The envelope carries docs context, the story-author prompt, `sourceTickets[]`,
 `duplicates[]` (open **Stories**, never Epics), `epicCandidates[]` +
-`dependencyCandidates[]` (Gate #3; path collisions) and advisory
-`complexitySignals` (**no routing authority**). A trivial scope can claim the
-lite route at persist — shape-validated, failing closed to `full`
-([ref](helpers/plan-reference.md)).
+`dependencyCandidates[]` (Gate #3; path collisions), `priorFeedback` and
+advisory `complexitySignals` (**no routing authority**). A trivial scope claims
+the lite route at persist, failing closed to `full`.
 
 **Triage each unknown by resolver** ([ref](helpers/plan-reference.md)): an
 **AFK** unknown (research settles it) is resolved before authoring, never
@@ -70,12 +68,9 @@ assumed; a **HITL** unknown goes to Gate #1. Under `--yes` do not ask free-form
 operator questions — AFK unknowns are still researched; only HITL unknowns land
 in Key Assumptions, each a decision-made-by-default.
 
-**Gate #1** — STOP to confirm the sharpened plan intent and any
-duplicate-candidate review. Under `--yes`, auto-proceed.
-
-On a truthy `memoryPoolAdvisory.recommend`, name
-[`/memory-consolidate`](memory-consolidate.md) quoting its `reasons[]`;
-advisory.
+**Gate #1** — STOP to confirm the sharpened plan intent, any
+duplicate-candidate review, and any `intake` row worth graduating
+([ref](helpers/plan-reference.md)). Under `--yes`, auto-proceed.
 
 On a truthy `deliverLightSuggestion.suggested`, offer — advisory, never an
 automatic reroute — to deliver the seed instead; on confirm route **in this
@@ -93,7 +88,9 @@ persist parses either, serializes canonical markdown and syncs top-level
 
 **Grounding = your reads + Phase 8.** Nothing inventories the repo: read each
 file you cite; persist hard-errors on any `{path, assumption}` absent from the
-tree. Fields: [ref](helpers/plan-reference.md).
+tree — a `refactors-existing` on a path the base branch **deleted or renamed**
+included. One rescue: a **never-tracked** one normalises to `creates`. Fields:
+[ref](helpers/plan-reference.md).
 
 Artifacts under `temp/plan-<slug>/`: `stories.json` (**length 1 by default**;
 over-budget Specs fail closed — split or tighten, never under `docs/`); optional

package/.agents/workflows/memory-consolidate.md

@@ -100,19 +100,24 @@ Then write the receipt to `.consolidation-stamp.json` in the pool root:
 count the directory, never the plan. It is the baseline the next run measures
 growth against, so a wrong number silently mis-arms the nudge.
 
-The `/mandrel-plan` Phase 0 advisory re-arms on exactly two conditions: the
-stamp aging past `planning.memoryPool.staleAfterDays` (30), or
-`planning.memoryPool.growthDelta` (25) entries written since that count. Pool
-size alone never triggers it — a pass that keeps every entry still quiets the
-nudge. A stamp with no `entryCount` leaves growth unmeasured, and only the age
-arm can speak until the next pass writes one.
+The `/mandrel-plan` Phase 0 advisory re-arms on exactly three conditions: the
+stamp aging past `planning.memoryPool.staleAfterDays` (30),
+`planning.memoryPool.growthDelta` (25) entries written since that count, or
+`MEMORY.md` exceeding `planning.memoryPool.indexByteCeiling` (24576) bytes.
+Pool size alone never triggers it — a pass that keeps every entry still quiets
+the first two arms. A stamp with no `entryCount` leaves growth unmeasured, and
+only the age and index arms can speak until the next pass writes one; a stamp
+dated in the future reads as no stamp at all.
 
 Write it **only** after Gate #2 — the stamp asserts an operator reviewed the
 pass, so writing it early makes it a lie.
 
-Close with counts: entries read, corrected, merged, pruned, and the new total.
-Then the forecast the operator would otherwise derive by hand: when the
-advisory next fires, and which arm reaches it first.
+Close with counts: entries read, corrected, merged, pruned, the new total, and
+**the rewritten `MEMORY.md`'s size in bytes beside that count** — the index is
+truncated at the byte ceiling, so a pass that pruned entries but left the
+index over the cap has not fixed the loss, and the number is the only way the
+operator can see that. Then the forecast the operator would otherwise derive
+by hand: when the advisory next fires, and which arm reaches it first.
 
 ## Constraints
 

package/docs/CHANGELOG.md

@@ -15,6 +15,43 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.56.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.55.0...mandrel-v2.56.0) (2026-09-11)
+
+
+### Added
+
+* audit-to-stories: dedup against a host-supplied issue index, so a sweep on a gh-less host stops re-filing what it already filed ([#5301](https://github.com/dsj1984/mandrel/issues/5301)) ([#5304](https://github.com/dsj1984/mandrel/issues/5304)) ([1b8abf0](https://github.com/dsj1984/mandrel/commit/1b8abf072a05db65e54a63cb8ec6cf6f06bc80ab))
+* audit-to-stories: make Phase 5a filings visible to the next sweep — record the ledger from plan-persist and stamp the audit labels the corpus is listed by ([#5307](https://github.com/dsj1984/mandrel/issues/5307)) ([#5308](https://github.com/dsj1984/mandrel/issues/5308)) ([094ba8a](https://github.com/dsj1984/mandrel/commit/094ba8ae6e2640ba3ac7cb5a4aeb9309aa72e42d))
+* audit-to-stories: record filed Issues in the cross-run ledger, so its suppression branch stops being unreachable ([#5305](https://github.com/dsj1984/mandrel/issues/5305)) ([#5306](https://github.com/dsj1984/mandrel/issues/5306)) ([d5e36ab](https://github.com/dsj1984/mandrel/commit/d5e36ab796f6946bf93d7161efa1470cad8a0a2b))
+* cI-gap intake: script-backed, repo-routed, deduped meta filings that /mandrel-plan can graduate ([#5300](https://github.com/dsj1984/mandrel/issues/5300)) ([#5302](https://github.com/dsj1984/mandrel/issues/5302)) ([37bc287](https://github.com/dsj1984/mandrel/commit/37bc2875ed8c98298afd90c72ece4f318e2c233d))
+
+## [2.55.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.54.0...mandrel-v2.55.0) (2026-09-11)
+
+
+### Added
+
+* a backgrounded capture ends the worker's turn on an unpushed branch, and close's base-sync silently spends the credit that capture was earning ([#5267](https://github.com/dsj1984/mandrel/issues/5267)) ([#5273](https://github.com/dsj1984/mandrel/issues/5273)) ([8d2bed1](https://github.com/dsj1984/mandrel/commit/8d2bed1e2132bc8b8901b58a33231b2bda5fd61c))
+* epic rollup: every child state change is an edge, the parent is resolved in one call, and provider reads carry one declared shape ([#5280](https://github.com/dsj1984/mandrel/issues/5280)) ([#5294](https://github.com/dsj1984/mandrel/issues/5294)) ([c2c9b96](https://github.com/dsj1984/mandrel/commit/c2c9b9654497404c20105bc3b7edcdbd45fb307e))
+* full-suite credit: a deposit path exists, the lock is liveness-aware, and stamps and evidence are keyed on content ([#5278](https://github.com/dsj1984/mandrel/issues/5278)) ([#5296](https://github.com/dsj1984/mandrel/issues/5296)) ([96c3240](https://github.com/dsj1984/mandrel/commit/96c32405025768de96d2e12680a54ed326787345))
+* memory advisory: measure the index against the harness byte cap, reject future-dated stamps, tighten the skill-id schema, and correct the rename cutover text ([#5285](https://github.com/dsj1984/mandrel/issues/5285)) ([#5289](https://github.com/dsj1984/mandrel/issues/5289)) ([22389a1](https://github.com/dsj1984/mandrel/commit/22389a106cb8e3ce42b0fde288ee473b88e49b99))
+* tests: a portability lint catches the Windows-only shapes before they land, and a vanished temp root is recorded instead of healed ([#5284](https://github.com/dsj1984/mandrel/issues/5284)) ([#5295](https://github.com/dsj1984/mandrel/issues/5295)) ([3358eef](https://github.com/dsj1984/mandrel/commit/3358eefeb0e5f36446b84a4f995e4b90641f64dc))
+
+
+### Fixed
+
+* a test fixture that loses its temp root mid-run fails with an unreadable ENOENT, and every later makeTempDir in that process fails with it ([#5274](https://github.com/dsj1984/mandrel/issues/5274)) ([#5275](https://github.com/dsj1984/mandrel/issues/5275)) ([5ac8699](https://github.com/dsj1984/mandrel/commit/5ac86995b92537b33bb209492cf9c3d9a064f792))
+* audit sweep: empty groups parse, the ledger commit is re-runnable from the remote base, SCA attribution is per advisory, and label-less audit Stories cannot be dispatched ([#5281](https://github.com/dsj1984/mandrel/issues/5281)) ([#5290](https://github.com/dsj1984/mandrel/issues/5290)) ([e229b0f](https://github.com/dsj1984/mandrel/commit/e229b0fb07e37e251b713a35646105cc54e791c9))
+* baselines: the merge driver is installed wherever base-sync runs, the refresh ack is scoped to the tagged commit's diff, and the land-time write-back cannot launder a regression ([#5277](https://github.com/dsj1984/mandrel/issues/5277)) ([#5292](https://github.com/dsj1984/mandrel/issues/5292)) ([9354e93](https://github.com/dsj1984/mandrel/commit/9354e93f7e74f263ffaf64c6e72056784a9b74d4))
+* close result: the merged flag is derived from what the run observed, failed closes report only registered gates, and advisory blocks carry their own remedy ([#5279](https://github.com/dsj1984/mandrel/issues/5279)) ([#5293](https://github.com/dsj1984/mandrel/issues/5293)) ([93414ac](https://github.com/dsj1984/mandrel/commit/93414ac756bd3f3300f869d46c28f680883edce4))
+* close's result note claims a merge it never confirmed, and a timed-out advisory scan blocks with the same class and remedies as a real violation ([#5266](https://github.com/dsj1984/mandrel/issues/5266)) ([#5271](https://github.com/dsj1984/mandrel/issues/5271)) ([585a2c3](https://github.com/dsj1984/mandrel/commit/585a2c340d96b972028d2d2f469e2f6b287f7ac2))
+* **deps:** override smol-toml past the GHSA-7w5x-hrqm-74c2 DoS advisory (refs [#5264](https://github.com/dsj1984/mandrel/issues/5264)) ([#5268](https://github.com/dsj1984/mandrel/issues/5268)) ([8db060c](https://github.com/dsj1984/mandrel/commit/8db060ca23a5242c1d13e4a049647be86e853504))
+* git-cleanup: weak-signal remote deletes need an explicit opt-in under --yes, and the bulk PR index short-circuits its per-branch fallback ([#5283](https://github.com/dsj1984/mandrel/issues/5283)) ([#5288](https://github.com/dsj1984/mandrel/issues/5288)) ([8346932](https://github.com/dsj1984/mandrel/commit/83469327b63488ea41a2bd9fb53a37bc2f57d1c0))
+* plan-persist reports two things the tree contradicts: a refactors-existing path deleted weeks ago, and a wave table promising parallelism the dispatch guard refuses ([#5265](https://github.com/dsj1984/mandrel/issues/5265)) ([#5270](https://github.com/dsj1984/mandrel/issues/5270)) ([1b5d1ff](https://github.com/dsj1984/mandrel/commit/1b5d1ffdd6e8821c833d320e93381f7804cb61c8))
+* scoped lint: a degraded surface no longer discards the other surface's findings ([#5282](https://github.com/dsj1984/mandrel/issues/5282)) ([#5287](https://github.com/dsj1984/mandrel/issues/5287)) ([75005ee](https://github.com/dsj1984/mandrel/commit/75005ee925d463d46f5cb24cb3788647e08a37b2))
+* **tests:** a RegExp built from a raw path can never match on Windows (refs [#5274](https://github.com/dsj1984/mandrel/issues/5274)) ([#5276](https://github.com/dsj1984/mandrel/issues/5276)) ([8d5efb2](https://github.com/dsj1984/mandrel/commit/8d5efb256d936f7dd955eff55c68d70d8abbfb9c))
+* **tests:** close the two Windows-only breaks Epic [#5286](https://github.com/dsj1984/mandrel/issues/5286) left on main, and the class behind them ([#5297](https://github.com/dsj1984/mandrel/issues/5297)) ([ec419c7](https://github.com/dsj1984/mandrel/commit/ec419c7b7462f4e6e0adf76805c22735ac2e9673))
+* **tests:** prove the workflows-doc drift gate on a fixture root, not the live checkout ([#5291](https://github.com/dsj1984/mandrel/issues/5291)) ([e44aa99](https://github.com/dsj1984/mandrel/commit/e44aa991027859c5d94d9dc875e80d41e1572c00))
+
 ## [2.54.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.53.0...mandrel-v2.54.0) (2026-09-09)
 
 

package/lib/cli/registry.js

@@ -28,7 +28,8 @@ import { fileURLToPath } from 'node:url';
 import {
   BASELINE_MERGE_DRIVER_CONFIG_KEY,
   BASELINE_MERGE_DRIVER_REMEDY,
-  declaresBaselineMergeDriver,
+  parseBaselineMergeDriverCommand,
+  probeBaselineMergeDriver,
 } from '../../.agents/scripts/lib/bootstrap/baseline-merge-driver.js';
 import {
   REQUIRED_NODE_CEILING_MAJOR,
@@ -59,8 +60,8 @@ import {
  * @param {string[]} args
  * @returns {{ status: number|null, stdout: string, stderr: string, error?: NodeJS.ErrnoException }}
  */
-function spawn(cmd, args) {
-  const r = spawnSync(cmd, args, { encoding: 'utf8' });
+function spawn(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', ...opts });
   return {
     status: r.status,
     stdout: typeof r.stdout === 'string' ? r.stdout : '',
@@ -1101,34 +1102,76 @@ function runVersionCurrent({ cachePath, installedVersion, fsImpl = fs } = {}) {
  */
 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)) {
+  // Both git calls run from `projectRoot`: the config key is per-clone, and
+  // reading it from wherever `mandrel doctor` was typed answers about a
+  // different repository (or none).
+  const { declared, command } = probeBaselineMergeDriver({
+    projectRoot,
+    fsImpl,
+    runGit: (args) => runner('git', args, { cwd: projectRoot }),
+  });
+  if (!declared) {
     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() };
+  if (command === '') {
+    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,
+    };
   }
+  return probeConfiguredDriver(command, runner, projectRoot);
+}
 
+/**
+ * Does the configured driver command actually RUN? (Story #5277)
+ *
+ * A set-but-broken key is the failure mode a presence check cannot see, and it
+ * is the common one: the command names an absolute node binary, and an nvm or
+ * volta version bump moves that binary out from under it months after the
+ * driver was installed. Git's behaviour then is the same silence a missing key
+ * produces — the driver exits non-zero, git leaves the file conflicted, and the
+ * operator reads it as "baselines conflict again" rather than as a broken
+ * registration. So the check executes what git would execute.
+ *
+ * `--help` is the probe because the driver's real invocation mutates `%A` in
+ * place; the shipped CLI answers `--help` with exit 0 and touches nothing.
+ *
+ * The command is tokenised, never handed to a shell
+ * ({@link parseBaselineMergeDriverCommand}) — it is a config value, and running
+ * it through `shell: true` would make any write to that key arbitrary command
+ * execution (security-baseline § Output & Rendering).
+ *
+ * The probe runs from `projectRoot`, because the command's script path is
+ * relative to the worktree root — which is where git invokes a merge driver
+ * from, and is not necessarily where `mandrel doctor` was typed.
+ *
+ * @param {string} command
+ * @param {typeof spawn} runner
+ * @param {string} projectRoot
+ * @returns {{ ok: boolean, detail: string, remedy?: string }}
+ */
+function probeConfiguredDriver(command, runner, projectRoot) {
+  const parsed = parseBaselineMergeDriverCommand(command);
+  if (!parsed) {
+    return {
+      ok: false,
+      detail: `${BASELINE_MERGE_DRIVER_CONFIG_KEY} is set to ${JSON.stringify(command)}, which has no runnable command in it`,
+      remedy: BASELINE_MERGE_DRIVER_REMEDY,
+    };
+  }
+  const probe = runner(parsed.file, [...parsed.args, '--help'], {
+    cwd: projectRoot,
+  });
+  if (probe.status === 0) return { ok: true, detail: command };
+  const why = probe.error?.message ?? `exit ${probe.status}`;
   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`,
+    detail: `${BASELINE_MERGE_DRIVER_CONFIG_KEY} is set to ${JSON.stringify(command)} but running it failed (${why}) — git would fall back to text-merging baselines/*.json exactly as if the key were unset`,
     remedy: BASELINE_MERGE_DRIVER_REMEDY,
   };
 }

package/lib/cli/sync.js

@@ -38,14 +38,24 @@
  *     {@link readVersionMarker} for how callers consume it.
  *
  * Security (Tech Spec #3459 "Postinstall safety"):
- *   - Does nothing beyond a local file copy: no network, no shell, no writes
- *     outside `./.agents/`.
+ *   - No network, and no shell: every child process is spawned with argv
+ *     tokens and `shell: false`.
  *   - Logs only paths and counts, never file contents or environment values.
+ *   - One write outside `./.agents/` (Story #5277): the per-clone
+ *     `merge.mandrel-baseline.driver` git config, and only when the project's
+ *     own tracked `.gitattributes` already declares the attribute that needs
+ *     it. That half of the registration cannot ship with the repository — git
+ *     will not execute a command chosen by whoever wrote it — so every fresh
+ *     clone silently text-merges generated baselines until something installs
+ *     it locally, and `sync` is the one command every consumer runs. It never
+ *     creates or edits `.gitattributes`; a project that has not opted into the
+ *     quality surface is left untouched.
  *
  * Injectable seams (used by lib/cli/__tests__/sync.test.js):
  *   - `resolvePackageRoot` — replaces real `mandrel` resolution
  *   - `fs`                 — replaces the node:fs surface used here
  *   - `cwd`                — replaces process.cwd()
+ *   - `ensureMergeDriver`  — replaces the git-config merge-driver install
  *   - `write`              — replaces process.stdout.write
  *   - `writeErr`           — replaces process.stderr.write
  *   - `exit`               — replaces process.exit
@@ -55,6 +65,7 @@ import nodeFs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 
+import { ensureBaselineMergeDriver } from '../../.agents/scripts/lib/bootstrap/baseline-merge-driver.js';
 import { LEDGER_RELATIVE_PATH } from '../../.agents/scripts/lib/bootstrap/install-ledger.js';
 
 export const PACKAGE_NAME = 'mandrel';
@@ -337,6 +348,7 @@ function listDestFiles(dir, fsImpl, prefix = '') {
  *   write?: (s: string) => void,
  *   writeErr?: (s: string) => void,
  *   exit?: (code: number) => void,
+ *   ensureMergeDriver?: typeof ensureBaselineMergeDriver,
  * }} [opts]
  * @returns {{ copied: number, planned: number, pruned: number, dryRun: boolean }}
  *   Summary (also returned in dry-run / error paths for testability).
@@ -344,6 +356,7 @@ function listDestFiles(dir, fsImpl, prefix = '') {
 export function runSync({
   argv = [],
   resolvePackageRoot = defaultResolvePackageRoot,
+  ensureMergeDriver = ensureBaselineMergeDriver,
   fs = nodeFs,
   cwd = () => process.cwd(),
   write = (s) => process.stdout.write(s),
@@ -435,6 +448,18 @@ export function runSync({
     `${packageVersion}\n`,
   );
 
+  // Baseline merge driver (Story #5277) — config half only; see the module
+  // preamble's security note. Never allowed to fail the sync: a consumer
+  // without git, or with a read-only config, still gets their `.agents/` tree.
+  const driver = ensureMergeDriver({
+    projectRoot,
+    configOnly: true,
+    fsImpl: fs,
+  });
+  if (driver?.action === 'updated') {
+    write('✅  Registered the baselines/*.json merge driver for this clone\n');
+  }
+
   if (staleFiles.length > 0) {
     write(
       `✅  Installed ${payloadFiles.length} file(s) into ./.agents/ (pruned ${staleFiles.length} stale file(s))\n`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.54.0",
+  "version": "2.56.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",
@@ -32,6 +32,7 @@
     "baseline:agents-loc": "node baselines/agents-loc-baseline.mjs",
     "baselines:scope": "node .agents/scripts/check-baseline-scope.js",
     "baselines:prune": "node .agents/scripts/prune-baseline-orphans.js",
+    "baselines:merge-driver": "node .agents/scripts/merge-baseline.js --install",
     "lint:md": "markdownlint-cli2 \".agents/**/*.md\" \"*.md\" \"!node_modules/**\" \"!.worktrees/**\"",
     "lint": "node .agents/scripts/run-lint.js && node .agents/scripts/check-generated-validator.js --check && node .agents/scripts/check-pinned-override-notes.js && npm run docs:check",
     "docs:gen": "node .agents/scripts/generate-config-docs.js && node .agents/scripts/generate-workflows-doc.js && node .agents/scripts/generate-lens-checklists.js",
@@ -63,7 +64,7 @@
     "quality:watch": "node .agents/scripts/quality-watch.js",
     "sync:commands": "node bin/mandrel.js sync-commands",
     "sync:agents": "node .agents/scripts/sync-claude-agents.js",
-    "prepare": "husky && npm run sync:commands && npm run sync:agents",
+    "prepare": "husky && npm run sync:commands && npm run sync:agents && npm run baselines:merge-driver",
     "postinstall": "node bin/postinstall.js mandrel sync"
   },
   "repository": {
@@ -130,10 +131,12 @@
   "//": {
     "peerDependencies.@cucumber/gherkin": "OPTIONAL peer, mirroring the `typescript` precedent, and deliberately NOT a runtime dependency. `check-gherkin-corpus.js` is the only consumer and it is opt-in behind `qa.gherkinLint`, so a consumer with no BDD tier must gain nothing from an upgrade. The devDependency alongside it is what lets this repository's own suite drive the real parser. The gate resolves it through a require path anchored at the consumer project — `.agents/` reaches a consumer by plain file copy, so a bare specifier would resolve against the consumer's module chain, which under a non-hoisting linker need not hold it.",
     "overrides.js-yaml": "COUPLED to devDependencies.markdownlint-cli2 — do not bump either alone, and do NOT drop this override. It is load-bearing: markdownlint-cli2 0.22.x pulls js-yaml 4.1.1, which carries GHSA-52cp-r559-cp3m (high) and GHSA-h67p-54hq-rp68 (moderate); removing the override was measured to reintroduce both (1 high + 1 moderate), while with it in place `npm audit` is clean. An npm override also wins over a transitive package's own pin, so this tree-wide ^4.3.2 is imposed on every js-yaml consumer regardless of what they declare — and markdownlint-cli2 0.23.x declares an exact js-yaml 5.2.1. A dry-run bump confirmed the trap: markdownlint-cli2 0.23.1 resolves against js-yaml 4.3.0, two majors off what it declares, silently. The only safe move is to raise this override and bump markdownlint-cli2 in ONE reviewed commit (first confirming cosmiconfig, under @commitlint/cli, tolerates the same major). renovate.json excludes markdownlint-cli2 from devDependency auto-merge so that pair cannot drift apart unattended. The floor has since been raised twice for advisories against the pinned range itself (most recently to ^4.3.2 for GHSA-2883-xcg3-v3hh, whose fix is 4.3.2) — raising it is safe and does NOT touch the coupling above; check-pinned-override-notes.js now fails the build if this sentence and the pin disagree.",
-    "dependencies.js-yaml": "States the SAME range as overrides.js-yaml above. The two are deliberate duplicates — npm has no way to reference the direct range from the overrides block — so they MUST move in lockstep; changing one without the other silently splits the direct and transitive resolutions."
+    "dependencies.js-yaml": "States the SAME range as overrides.js-yaml above. The two are deliberate duplicates — npm has no way to reference the direct range from the overrides block — so they MUST move in lockstep; changing one without the other silently splits the direct and transitive resolutions.",
+    "overrides.smol-toml": "Load-bearing: markdownlint-cli2 0.22.1 declares an EXACT smol-toml 1.6.1, which carries GHSA-7w5x-hrqm-74c2 (high — denial of service via malformed TOML). The advisory’s vulnerable range is everything <= 1.7.0, so no lockfile-only resolution reaches a patched version and this tree-wide ^1.7.1 pin is what clears it. npm’s own `audit fix --force` instead proposes markdownlint-cli2 0.21.0 — a DOWNGRADE presented as a breaking change; do not take it. An npm override wins over a transitive package’s own exact pin, so markdownlint-cli2 runs against a minor it never declared: `npm run lint` was confirmed green under the forced version and is what must be re-run if this pin moves. knip declares ^1.6.1 and is satisfied natively. smol-toml is NOT a direct dependency, so unlike overrides.js-yaml there is no lockstep duplicate range to keep in sync."
   },
   "overrides": {
     "js-yaml": "^4.3.2",
-    "markdown-it": "^14.2.0"
+    "markdown-it": "^14.2.0",
+    "smol-toml": "^1.7.1"
   }
 }