mandrel 2.19.0 → 2.21.0

package/.agents/scripts/lib/test-temp.js

@@ -0,0 +1,311 @@
+/**
+ * Managed test temp directories (Story #4808).
+ *
+ * The suite used to mint `os.tmpdir()` directories directly at ~71 call
+ * sites across 25 files that never reaped them, accumulating tens of
+ * thousands of entries per run into a temp root shared with self-hosted CI
+ * runners. The damaging axis is **entry count**, not bytes: a runner's
+ * job-started hook scanning an 841k-entry temp root burned 5m29s inside the
+ * job clock and timed jobs out.
+ *
+ * Per-call-site teardown had already failed 25 times, so this module makes
+ * teardown structural instead: a directory cannot be created without its
+ * reaping already registered.
+ *
+ * ## Why one suite root
+ *
+ * A guard over a *shared* `os.tmpdir()` cannot attribute an entry to this
+ * suite. A prefix allowlist rots the moment someone invents a new prefix,
+ * and a bare "no new entries" assertion false-positives on any unrelated
+ * process that happened to run concurrently. Nesting every managed
+ * directory inside a single per-process root
+ * (`mandrel-suite-<pid>-<random>`) makes attribution exact: the guard asks
+ * only whether a *suite root* survived, which is a question about this
+ * suite alone. The suite contributes exactly one shared-root entry per
+ * process, and reaps it.
+ *
+ * ## Why the root is never published to children
+ *
+ * Deliberately unlike `MANDREL_TEST_TEMP_ROOT` (the scratch seam in
+ * `test-env.js` / `config/temp-paths.js`, which children inherit): each
+ * process owns its own suite root, so "did I create it?" is always
+ * answerable locally and a child can never reap its parent's root
+ * mid-run.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import picomatch from 'picomatch';
+
+/**
+ * Directory-name prefix identifying a per-process suite root. The guard
+ * matches on this, so it is the one string both sides must agree on.
+ */
+export const SUITE_ROOT_PREFIX = 'mandrel-suite-';
+
+/**
+ * Reserved snapshot-manifest key under which the guard records the suite
+ * roots observed at `--snapshot` time. It cannot collide with a stream
+ * entry: those are always `*.ndjson` relative paths.
+ */
+export const SUITE_ROOTS_KEY = '#suiteRoots';
+
+/** Per-process suite root, or `null` before the first `makeTempDir`. */
+let _suiteRoot = null;
+
+/** Guards against registering the exit reaper more than once. */
+let _reaperRegistered = false;
+
+/**
+ * Test-only: forget the per-process suite root without removing it, so a
+ * test can exercise the creation branch repeatedly in one process.
+ */
+export function _resetSuiteTempRootForTests() {
+  _suiteRoot = null;
+  _reaperRegistered = false;
+}
+
+/**
+ * Test-only: report whether this process currently owns a suite root.
+ * @returns {string|null}
+ */
+export function _currentSuiteTempRoot() {
+  return _suiteRoot;
+}
+
+/**
+ * Remove this process's suite root and everything under it.
+ *
+ * A teardown failure is reported on stderr and swallowed: a suite that
+ * passed must not start failing because a directory could not be unlinked
+ * (a Windows file lock, a read-only mount). The leak is the lesser defect
+ * and the guard reports it separately.
+ *
+ * Only the process that minted the root can reach a non-null `_suiteRoot`,
+ * so this is creator-only by construction.
+ *
+ * @param {{ fsImpl?: typeof fs, warn?: (msg: string) => void }} [deps]
+ * @returns {string|null} the removed root, or `null` when there was none
+ */
+export function reapSuiteTempRoot({
+  fsImpl = fs,
+  warn = (msg) => process.stderr.write(`${msg}\n`),
+} = {}) {
+  const root = _suiteRoot;
+  if (root === null) return null;
+  _suiteRoot = null;
+  try {
+    fsImpl.rmSync(root, { recursive: true, force: true });
+  } catch (err) {
+    warn(`[test-temp] failed to reap suite temp root ${root}: ${err.message}`);
+  }
+  return root;
+}
+
+/**
+ * Resolve (creating on first use) this process's suite root.
+ *
+ * The reaper is registered on `exit` at creation time, so a directory
+ * cannot exist without its teardown already armed — including when the
+ * suite fails, since a failing `node --test` run still exits normally.
+ *
+ * @param {{ fsImpl?: typeof fs, tmpdir?: () => string, onExit?: (fn: () => void) => void }} [deps]
+ * @returns {string} absolute path to the suite root
+ */
+export function suiteTempRoot({
+  fsImpl = fs,
+  tmpdir = os.tmpdir,
+  onExit = (fn) => process.once('exit', fn),
+} = {}) {
+  if (_suiteRoot !== null) return _suiteRoot;
+  _suiteRoot = fsImpl.mkdtempSync(
+    path.join(tmpdir(), `${SUITE_ROOT_PREFIX}${process.pid}-`),
+  );
+  if (!_reaperRegistered) {
+    _reaperRegistered = true;
+    onExit(() => reapSuiteTempRoot({ fsImpl }));
+  }
+  return _suiteRoot;
+}
+
+/**
+ * Create a fresh temp directory for a test, nested inside this process's
+ * suite root and reaped with it.
+ *
+ * Drop-in for `mkdtempSync(path.join(os.tmpdir(), prefix))` — the returned
+ * path is absolute and unique, so call sites change only where the
+ * directory comes from, never how it is used.
+ *
+ * @param {string} [prefix='t-'] label kept for readability in a stack trace
+ * @param {{ fsImpl?: typeof fs, tmpdir?: () => string, onExit?: (fn: () => void) => void }} [deps]
+ * @returns {string} absolute path to the new directory
+ */
+export function makeTempDir(prefix = 't-', deps = {}) {
+  const root = suiteTempRoot(deps);
+  const fsImpl = deps.fsImpl ?? fs;
+  return fsImpl.mkdtempSync(path.join(root, prefix));
+}
+
+/**
+ * Register removal of one specific scratch directory at process exit.
+ *
+ * For the two scratch seams (`test-env.js`, `config/temp-paths.js`) that
+ * mint a root *outside* the suite tree because children inherit its path
+ * through `MANDREL_TEST_TEMP_ROOT`. Call this only from the branch that
+ * actually minted the directory — a process that inherited the path must
+ * never reap it, or it deletes its parent's scratch mid-run.
+ *
+ * Teardown failures are swallowed for the same reason as
+ * {@link reapSuiteTempRoot}: a leak must not turn a passing suite red.
+ *
+ * @param {string} dirPath absolute path this process minted
+ * @param {{ fsImpl?: typeof fs, onExit?: (fn: () => void) => void, warn?: (msg: string) => void }} [deps]
+ * @returns {void}
+ */
+export function reapOnExit(
+  dirPath,
+  {
+    fsImpl = fs,
+    onExit = (fn) => process.once('exit', fn),
+    warn = (msg) => process.stderr.write(`${msg}\n`),
+  } = {},
+) {
+  onExit(() => {
+    try {
+      fsImpl.rmSync(dirPath, { recursive: true, force: true });
+    } catch (err) {
+      warn(`[test-temp] failed to reap scratch dir ${dirPath}: ${err.message}`);
+    }
+  });
+}
+
+/**
+ * List the suite roots currently present in `tmpDir`, sorted.
+ *
+ * Names only (not absolute paths) so the guard can diff them against a
+ * recorded snapshot without embedding the temp root's absolute location.
+ *
+ * @param {string} tmpDir
+ * @param {{ fsImpl?: typeof fs }} [deps]
+ * @returns {string[]}
+ */
+export function listSuiteTempRoots(tmpDir, { fsImpl = fs } = {}) {
+  if (!fsImpl.existsSync(tmpDir)) return [];
+  return fsImpl
+    .readdirSync(tmpDir, { withFileTypes: true })
+    .filter(
+      (ent) => ent.isDirectory() && ent.name.startsWith(SUITE_ROOT_PREFIX),
+    )
+    .map((ent) => ent.name)
+    .sort();
+}
+
+/**
+ * Suite roots that appeared since the snapshot and are still on disk —
+ * i.e. roots this suite run created and failed to reap.
+ *
+ * Diffing against the snapshot rather than asserting an empty set is what
+ * keeps a concurrently-running suite (another checkout, another worktree)
+ * from failing this one.
+ *
+ * @param {string} tmpDir
+ * @param {string[]} snapshotRoots
+ * @param {{ fsImpl?: typeof fs }} [deps]
+ * @returns {string[]}
+ */
+export function survivingSuiteTempRoots(tmpDir, snapshotRoots, deps = {}) {
+  const known = new Set(snapshotRoots ?? []);
+  return listSuiteTempRoots(tmpDir, deps).filter((name) => !known.has(name));
+}
+
+/**
+ * Matches a `mkdtemp` / `mkdtempSync` call whose argument reaches
+ * `tmpdir()`. The lookahead spans the call's argument text rather than
+ * trying to balance parentheses, so it catches every shape in use:
+ * `mkdtempSync(path.join(os.tmpdir(), 'x-'))`, `mkdtempSync(join(tmpdir(),
+ * 'x-'))`, and `fs.mkdtempSync(...)`.
+ */
+const RAW_TMPDIR_MKDTEMP =
+  /mkdtemp(?:Sync)?\s*\([^;\n]{0,200}?tmpdir\s*\(\s*\)/;
+
+/**
+ * Opt-out marker for a line that must call `mkdtemp` against the real OS
+ * temp root — the guard's own tests, and the scratch seams that
+ * deliberately mint a root outside the suite tree.
+ */
+const LINT_ESCAPE = 'test-temp-allow';
+
+/**
+ * Flag test files that mint OS temp directories directly instead of going
+ * through {@link makeTempDir}.
+ *
+ * This is the half of the backstop that catches the *next* leaking file at
+ * authoring time rather than after it has already leaked, so it is scoped
+ * to explicitly-passed globs: `check-test-temp-hygiene.js` ships in the
+ * materialized `.agents/` payload, and a consumer's tests are none of this
+ * rule's business.
+ *
+ * @param {string} repoRoot
+ * @param {string[]} globs repo-relative picomatch patterns
+ * @param {{ fsImpl?: typeof fs }} [deps]
+ * @returns {{ file: string, line: number, text: string }[]}
+ */
+export function findRawTmpdirMkdtemp(repoRoot, globs, { fsImpl = fs } = {}) {
+  const patterns = (globs ?? []).filter(Boolean);
+  // Negation is handled here rather than handed to picomatch: passing a
+  // mixed `['a/**', '!a/b']` array makes the `!` entry read as its own
+  // positive "everything but a/b" matcher, which silently *widens* the
+  // scan instead of narrowing it.
+  const include = patterns.filter((p) => !p.startsWith('!'));
+  const exclude = patterns
+    .filter((p) => p.startsWith('!'))
+    .map((p) => p.slice(1));
+  if (include.length === 0) return [];
+  const isIncluded = picomatch(include);
+  const isExcluded = exclude.length > 0 ? picomatch(exclude) : () => false;
+  const findings = [];
+  for (const rel of walkFiles(repoRoot, fsImpl)) {
+    if (!isIncluded(rel) || isExcluded(rel)) continue;
+    const lines = fsImpl
+      .readFileSync(path.join(repoRoot, rel), 'utf8')
+      .split('\n');
+    lines.forEach((text, i) => {
+      if (!RAW_TMPDIR_MKDTEMP.test(text)) return;
+      if (text.includes(LINT_ESCAPE)) return;
+      if (i > 0 && lines[i - 1].includes(LINT_ESCAPE)) return;
+      findings.push({ file: rel, line: i + 1, text: text.trim() });
+    });
+  }
+  return findings;
+}
+
+/**
+ * Walk `root` for JavaScript sources, returning POSIX-normalised relative
+ * paths. Unlike the `test-isolate` walker this descends dot-prefixed
+ * directories (the `.agents/` payload carries `__tests__` trees) while
+ * still skipping the trees that are never source: `node_modules`,
+ * `.worktrees`, and `.git`.
+ *
+ * @param {string} root
+ * @param {typeof fs} fsImpl
+ * @returns {string[]}
+ */
+function walkFiles(root, fsImpl) {
+  const out = [];
+  const skip = new Set(['node_modules', '.worktrees', '.git', 'temp']);
+  const walk = (dir, prefix) => {
+    if (!fsImpl.existsSync(dir)) return;
+    for (const ent of fsImpl.readdirSync(dir, { withFileTypes: true })) {
+      if (skip.has(ent.name)) continue;
+      const rel = prefix ? `${prefix}/${ent.name}` : ent.name;
+      if (ent.isDirectory()) {
+        walk(path.join(dir, ent.name), rel);
+      } else if (/\.(?:js|mjs|cjs)$/.test(ent.name)) {
+        out.push(rel);
+      }
+    }
+  };
+  walk(root, '');
+  return out.sort();
+}

package/.agents/scripts/single-story-confirm-merge.js

@@ -204,7 +204,7 @@ async function logConfirmResult(result, terminal, config) {
       status: terminal?.status,
     },
   });
-  emitTerminalEnvelope(terminal);
+  emitTerminalEnvelope(terminal, { config });
   await emitTerminalFriction({ envelope: terminal, config });
   return { success: terminal.status !== 'failed', result, terminal };
 }

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

@@ -49,7 +49,9 @@ multi-capability enumeration). Size is enforced where ground truth is available:
 the diff backstop in step 4. Do not talk yourself past that one.
 
 Sensitivity is the exception and stays absolute: a footprint touching an auth,
-crypto, billing, or migration class routes `full` however small or mechanical.
+crypto, billing, or migration class routes `full` however small or mechanical —
+and unlike a ceiling, it is **not overridable** (§ Recording a proceed-light
+answer).
 
 ## Four invariants (do not skip one)
 
@@ -58,9 +60,11 @@ crypto, billing, or migration class routes `full` however small or mechanical.
    **and** a ledgered model verdict with a recorded reason. Both must agree on
    `lite`.
 2. **Over-scope stops — it never hard-fails.** An over-ceiling prompt STOPS and
-   asks the operator to escalate to `/plan` or proceed light. Under `--yes` it
-   fails closed to an **`escalated` terminal envelope** that ends the session
-   (§ Escalation is terminal).
+   asks the operator to escalate to `/plan` or proceed light. **Both answers
+   are executable** — `--operator-proceed-light` records the second one
+   (§ Recording a proceed-light answer). Under `--yes` it fails closed to an
+   **`escalated` terminal envelope** that ends the session (§ Escalation is
+   terminal).
 3. **Diff-derived backstop.** After implementation the ACTUAL change set is
    re-checked — the diff is the real scope signal — and an over-ceiling diff is
    blocked rather than landed.
@@ -89,7 +93,10 @@ crypto, billing, or migration class routes `full` however small or mechanical.
      `nextCommands`. Continue to step 2.
    - **`ask-operator`** — predicted scope exceeds the light ceilings. STOP and
      ask the operator to escalate to `/plan` or proceed light. Do not proceed
-     on your own. This is a **question, not a terminal** — wait for the answer.
+     on your own. This is a **question, not a terminal** — wait for the answer,
+     then act on it: *escalate* leaves for `/plan`, *proceed light* re-runs the
+     same command with `--operator-proceed-light "<their reason>"`
+     (§ Recording a proceed-light answer).
    - **over-scope under `--yes`** — no `action` to branch on: the gate emits an
      **`escalated` terminal envelope** instead (exit 2). § Escalation is
      terminal governs; you are finished.
@@ -144,6 +151,39 @@ crypto, billing, or migration class routes `full` however small or mechanical.
    [`deliver-digest.md`](deliver-digest.md) § 5 — every close
    gate runs byte-identical to the full path.
 
+## Recording a proceed-light answer {#recording-a-proceed-light-answer}
+
+The gate offers the operator two options, so **both** have to be executable.
+Re-run the identical gate command with their answer appended:
+
+```bash
+node .agents/scripts/deliver-light.js --prompt "<prompt>" … \
+  --operator-proceed-light "<the operator's reason, in their words>"
+```
+
+The gate then proceeds light, records the decision in the receipt Story, and
+returns it on the envelope's `override`. Do **not** instead re-shape the
+prediction — shrinking `--refactors` until the gate stops objecting is
+under-declaring the footprint, which is the one thing the coarse design must
+not reward.
+
+It is deliberately narrow, and a refusal is printed rather than silent:
+
+- **Only a size prediction is waivable** — change kinds, magnitude,
+  uncertainty, deployable span. A sensitive-path class, a
+  migration-with-consumers span, and an unknown footprint (undeclared, glob,
+  no acceptance, unclassifiable) are refused: those are risk, not size, and
+  § Scope by effort keeps them absolute.
+- **The ledgered verdict still stands on its own.** The override substitutes
+  for the predicted *shape* only; `--route lite --reason "<why>"` is still
+  required.
+- **Attended-only.** With `--yes` it is a usage error, not a quiet no-op —
+  an unattended run has no operator whose answer this could be, and over-scope
+  there still fails closed (§ Escalation is terminal).
+
+What licenses this at all is step 4: the operator waives a *guess*, never the
+diff backstop, which re-checks the actual change set against ground truth.
+
 ## Escalation is terminal {#escalation-is-terminal}
 
 Over-scope under `--yes` emits a schema-validated `story-deliver-terminal`

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

@@ -745,6 +745,39 @@ unconfirmed merge is a **contract violation** — the parent cannot distinguish
 "still working" from "done but silent". `pending` is the honest,
 machine-readable alternative: "not finished, here is exactly how to continue."
 
+### The envelope also lands on disk
+
+Stdout has exactly one reader — the turn that launched the close — and that
+reader is not always still listening. A child that reports progress and ends
+its turn while its close is mid-gate-chain is behaving reasonably, but the
+envelope it never relayed is gone, and reconstructing the Story's state from
+labels costs a recovery round trip plus a full resume of the child. Observed
+four times across three workers in a single consumer run, on unrelated
+footprints, and not new to that run.
+
+So `emitTerminalEnvelope` — the one writer behind every emit site — also
+persists the validated envelope to
+`<tempRoot>/orchestration/story-deliver-terminal-<storyId>.json`:
+
+- **It is the same object**, not a summary. Read it and branch exactly as you
+  would on stdout; the copy is written before the markers are, so a caller
+  that saw them can rely on the file.
+- **It is best-effort.** A failed write returns null and changes nothing about
+  the emitted envelope or the exit code — a landed PR must never become a
+  crash because a temp directory was unwritable.
+- **It is a fallback, not a licence.** A worker still holds its turn until the
+  envelope arrives; see [`agents/story-worker.md`](../../agents/story-worker.md).
+
+`deliver-recover.js` reads the same artifact, plus the freshness of
+`close-gates-<storyId>.log`, to split the one genuinely ambiguous row of its
+table. `agent::executing` with no PR used to answer "Implementation never
+finished" — false for the whole duration of a close, whose gates and push
+happen before any PR exists, and actively hazardous, because acting on its
+re-init suggestion can put a second close on one PR. It now answers
+`close-in-flight` (a gate log touched inside the window: wait, then re-probe)
+or `close-envelope-on-disk` (the close already reached a verdict: relay it),
+and falls back to the original verdict only when neither artifact exists.
+
 ### Exit-code compatibility note (`--no-wait-merge`)
 
 Every close flag keeps its meaning, but the **exit code** of a

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

@@ -148,10 +148,13 @@ budget is exhausted. Reference § Step 7.
 
 ## Recovering a stranded Story {#recover}
 
-Unclear state (killed run, lost envelope, a re-run refusal — incl.
-merged-but-label-stale)? Do not guess — probe **read-only** with
+**Lost envelope first: read it off disk.** Close persists each to
+`temp/orchestration/story-deliver-terminal-<storyId>.json`; branch on it per
+digest § 5. Otherwise (killed run, re-run refusal, merged-but-label-stale)
+do not guess — probe **read-only** with
 `node .agents/scripts/deliver-recover.js --story <storyId>`; it prints the
-**one** next command with its evidence, never a menu.
+**one** next command with its evidence, never a menu. A live close answers
+`close-in-flight`: wait, never re-init underneath it.
 
 ## Idempotence & constraints
 

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

@@ -42,8 +42,8 @@ On a confirmed `deliverLightSuggestion`, `/plan` routes into
 [`deliver-light.md`](deliver-light.md) **without ending the session**. Two
 things make that safe, and both are worth understanding before changing it:
 
-1. **The handoff carries the envelope, not the seed.** Gate #1 already holds a
-   codebase snapshot and `complexitySignals`; fill the light gate's `--creates`
+1. **The handoff carries the envelope, not the seed.** Gate #1 already holds
+   the interrogated `complexitySignals`; fill the light gate's `--creates`
    / `--refactors` / `--acceptance` / `--reason` from those. Re-deriving from
    raw seed text throws away the better signal and can disagree with the
    suggestion that routed you.
@@ -135,8 +135,8 @@ ceilings on `STORY_SHAPE_CEILINGS` in
 ## Correct-by-construction authoring template
 
 `plan-context.js --out` writes `stories.template.json` as a
-**correct-by-construction** skeleton, built from the same repo snapshot the
-`complexitySignals` probed:
+**correct-by-construction** skeleton, built from the same repo probe the
+`complexitySignals` ran:
 
 - **`verify[]` placeholders already end with a valid `(tier)` tag.** Keep
   every filled entry's trailing tag one of `(unit)` / `(contract)` /
@@ -161,6 +161,21 @@ A faithfully-filled skeleton — placeholders replaced, pre-resolved entries
 kept, tags valid — passes the persist ticket validators with no
 round-trip.
 
+### Authored entry shape
+
+Each `stories.json` entry: `slug` (`^[a-z0-9][a-z0-9-]*$`), `type: "story"`,
+`title`, `body` (`goal`, optional `spec`, `changes[{path, assumption}]` —
+`creates|refactors-existing|deletes`, `non_goals`, `reason_to_exist`),
+top-level `acceptance[]`, `verify[]` (`… (unit|contract|e2e|validate)`), and
+`depends_on[]` (N>1 only).
+
+Nothing in that shape inventories the repo for the author. `changes[]` arrives
+pre-resolved against the working tree, and Phase 8's
+`validateStoryFileAssumptions` re-probes every `{path, assumption}` at persist
+as a hard error — so the grounding contract is the author's own targeted reads
+plus that gate. There is no pre-computed codebase snapshot to fall back on,
+and no manifest-derived replacement to build.
+
 ## Tickets mode — authoring `supersedes[]`
 
 In `--tickets` mode each Story carries a top-level `supersedes` array claiming

package/.agents/workflows/plan.md

@@ -64,7 +64,7 @@ node .agents/scripts/plan-context.js --seed "<seed>" \
 and derives source ids from its `sourceTickets[]`; the CLI also writes
 **`stories.template.json`**, the skeleton step 2 starts from.
 
-The envelope carries docs context, the codebase snapshot, the story-author
+The envelope carries docs context, the story-author
 prompt, `sourceTickets[]`, `duplicates[]` (open **Stories**, never Epics), and
 advisory `complexitySignals` (**no routing authority**). A trivial scope earns
 `--route-downgrade-reason "<why>"` at persist — shape-validated, failing closed
@@ -93,11 +93,12 @@ valid. `body` is a markdown string **or** a structured object; persist parses
 either, serializes the canonical markdown, and syncs top-level `acceptance[]` /
 `verify[]` into it — never dual-author those lists.
 
-Each entry (the `stories.template.json` shape): `slug`
-(`^[a-z0-9][a-z0-9-]*$`), `type: "story"`, `title`, `body` (`goal`, optional
-`spec`, `changes[{path, assumption}]` — `creates|refactors-existing|deletes`,
-`non_goals`, `reason_to_exist`), top-level `acceptance[]`, `verify[]` (`…
-(unit|contract|e2e|validate)`), `depends_on[]` (N>1 only).
+**Grounding = your reads + Phase 8.** Nothing inventories the repo for you:
+read each file you cite, then persist's file-assumption gate hard-errors on
+every `{path, assumption}` that misses the real tree.
+
+Entry fields (the `stories.template.json` shape):
+[reference](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/`);

package/docs/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.21.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.20.0...mandrel-v2.21.0) (2026-07-28)
+
+
+### Added
+
+* deliver-light: make the gate's `proceed-light` answer representable, attended-only, and auditable ([#4815](https://github.com/dsj1984/mandrel/issues/4815)) ([#4817](https://github.com/dsj1984/mandrel/issues/4817)) ([74aa28e](https://github.com/dsj1984/mandrel/commit/74aa28e57d0192bcad698461d600806a77de092f))
+* persist the close terminal envelope and teach recovery a live-close state (refs [#4816](https://github.com/dsj1984/mandrel/issues/4816)) ([#4819](https://github.com/dsj1984/mandrel/issues/4819)) ([ffa61d8](https://github.com/dsj1984/mandrel/commit/ffa61d8f56f39c33705bfa379cefdcaaeb523115))
+
+## [2.20.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.19.0...mandrel-v2.20.0) (2026-07-27)
+
+
+### Added
+
+* retire the planner codebase snapshot; Phase 8 file-assumption validation is the grounding gate ([#4811](https://github.com/dsj1984/mandrel/issues/4811)) ([#4812](https://github.com/dsj1984/mandrel/issues/4812)) ([48621a8](https://github.com/dsj1984/mandrel/commit/48621a8fdcbfa5076a1c94ebe9098bb36736db09))
+* route every suite temp dir under one reaped per-process root and guard the OS temp root against regression ([#4808](https://github.com/dsj1984/mandrel/issues/4808)) ([#4809](https://github.com/dsj1984/mandrel/issues/4809)) ([2e81c05](https://github.com/dsj1984/mandrel/commit/2e81c05f3113378ff2ed96b0f1802c406f4e61bf))
+
 ## [2.19.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.18.0...mandrel-v2.19.0) (2026-07-27)
 
 

package/lib/migrations/index.js

@@ -56,6 +56,7 @@ import { retireMiDropKnobs } from './steps/2.1.0-retire-mi-drop-knobs.js';
 import { retireVerifyConcurrencyCap } from './steps/2.1.0-retire-verify-concurrency-cap.js';
 import { retireEpicAcTags } from './steps/2.2.0-retire-epic-ac-tags.js';
 import { retireMaxSeedWords } from './steps/2.11.0-retire-max-seed-words.js';
+import { retireCodebaseSnapshot } from './steps/2.20.0-retire-codebase-snapshot.js';
 
 /**
  * Ordered registry of migration steps. MUST stay sorted ascending by
@@ -73,6 +74,7 @@ export const migrations = [
   retireVerifyConcurrencyCap,
   retireEpicAcTags,
   retireMaxSeedWords,
+  retireCodebaseSnapshot,
 ];
 
 /**