mandrel 2.19.0 → 2.20.0

package/.agents/scripts/lib/orchestration/planning/authoring-context.js

@@ -14,15 +14,12 @@ import {
   verifyBddRunnerPendingTag,
 } from '../../bdd-runner-detect.js';
 import { scanBddScenarios } from '../../bdd-scenario-scanner.js';
-import { buildCodebaseSnapshot } from '../../codebase-snapshot.js';
 import { getPaths, PROJECT_ROOT } from '../../config-resolver.js';
 import { scanMemoryFreshness } from '../../feedback-loop/memory-freshness.js';
 import { fetchPriorFeedback } from '../../feedback-loop/prior-feedback-fetcher.js';
 import { Logger } from '../../Logger.js';
 import { hasTicketSection } from '../../ticket-body-sections.js';
 import { ensureDocsDigest } from '../docs-digest.js';
-import { collectReferences, hasNewFileCue } from '../spec-freshness.js';
-import { buildAuthoringGrounding } from './spec-authoring-grounding.js';
 
 /**
  * Resolve the per-project memory directory used by the memory-freshness
@@ -179,68 +176,18 @@ export async function buildAuthoringContext(
     repo: githubCfg?.repo,
   });
 
-  // Story #2634 — codebase snapshot. Generates a bounded structural view
-  // of the consumer repo (file tree + package surface + recent activity
-  // + optional export signatures at the `medium` tier) so the Architect
-  // can prefer real module names over doc-only ones. The check is
-  // best-effort: any git/filesystem error degrades to an empty snapshot
-  // so Phase 7 stays non-blocking.
-  let codebaseSnapshot = null;
-  try {
-    codebaseSnapshot = buildCodebaseSnapshot({
-      cwd: PROJECT_ROOT,
-      tier: settings?.planning?.codebaseSnapshot?.tier,
-      include: settings?.planning?.codebaseSnapshot?.include,
-      exclude: settings?.planning?.codebaseSnapshot?.exclude,
-      recentCommitWindow:
-        settings?.planning?.codebaseSnapshot?.recentCommitWindow,
-    });
-    // Story #4139 (F10) — ground the spec author in the files it will cite.
-    // Two signals are attached to the snapshot envelope so the author (which
-    // consumes the JSON, not stderr) cannot miss them:
-    //   1. `grounding.truncation` — the structured, in-envelope form of the
-    //      Story #3959 dropped-file warning. The skinny-tier cap used to drop
-    //      the majority of matched files with only a stderr `Logger.warn` and
-    //      a bare `truncated: true` flag; the author never learned the
-    //      snapshot was partial (a real run dropped "377 of 627 files").
-    //   2. `grounding.citedButAbsent` — path-shaped references in the Epic
-    //      body (the prose the author grounds *from*) that are absent from
-    //      the snapshot's file set and not phrased as net-new, so cited-but-
-    //      absent surfaces are visible *during* authoring rather than only
-    //      after the post-author freshness gate (Story #2635).
-    // The grounding consults only the snapshot's file set and the Epic body —
-    // no new filesystem or git probes — so the context stays bounded for cost.
-    if (codebaseSnapshot) {
-      const grounding = buildAuthoringGrounding({
-        snapshot: codebaseSnapshot,
-        prose: epic.body ?? '',
-        collectReferences,
-        hasNewFileCue,
-      });
-      codebaseSnapshot.grounding = grounding;
-      if (grounding.truncation) {
-        const { dropped, matched, tier } = grounding.truncation;
-        Logger.warn(
-          `[plan-context] codebase snapshot truncated: ${dropped} of ` +
-            `${matched} matched file(s) dropped from the ${tier}-tier view. ` +
-            `The /plan authoring context is partial. To restore full ` +
-            `grounding, ` +
-            `set planning.codebaseSnapshot.tier: "medium" and/or narrow ` +
-            `planning.codebaseSnapshot.include in .agentrc.json.`,
-        );
-      }
-      if (grounding.citedButAbsent.length > 0) {
-        Logger.warn(
-          `[plan-context] ${grounding.citedButAbsent.length} path(s) cited ` +
-            `in the authored Spec are absent from the codebase snapshot: ` +
-            `${grounding.citedButAbsent.join(', ')}. /plan will flag these ` +
-            `as drift unless they are net-new.`,
-        );
-      }
-    }
-  } catch (err) {
-    Logger.warn(`[plan-context] codebase snapshot skipped: ${err.message}`);
-  }
+  // Story #4811 — the codebase snapshot (#2634), its authoring grounding
+  // (#4139 F10) and the spec-freshness helpers behind it are retired. The
+  // pre-computed structural view grounded nothing it promised: the default
+  // include globs missed the standard monorepo layout outright, its remedies
+  // pointed at knobs that re-filtered the same set, and its cited-but-absent
+  // signal inverted into noise whenever the snapshot was the thing that was
+  // wrong. Grounding now rests on the two mechanisms that read the real tree:
+  // the authoring model's own targeted retrieval (the digest-first precedent
+  // of Story #4433) and the Phase 8 `validateStoryFileAssumptions` gate, which
+  // probes every authored `{path, assumption}` against the working tree as a
+  // hard error. Nothing pre-computed replaces it — a stale inventory is the
+  // failure mode, not the fix.
 
   // Story #4542 — planning authors no risk artifact at all. Review depth and
   // the acceptance-critic mode are derived from the diff at close time
@@ -262,7 +209,6 @@ export async function buildAuthoringContext(
       },
     },
     docsContext,
-    codebaseSnapshot,
     bddRunner,
     bddScenarios,
     memoryFreshness,

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

@@ -3,6 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 
 import { TEST_TEMP_ROOT_ENV } from './config/temp-paths.js';
+import { reapOnExit } from './test-temp.js';
 
 /**
  * Per-process memo for the created scratch dir, so repeated calls in one
@@ -32,16 +33,26 @@ export function _clearTestScratchTempRootCache() {
  * `temp/` telemetry tree — the regression that let 99% of friction records
  * be test-fixture pollution.
  *
+ * Reaping (Story #4808): the minting process registers removal of the
+ * scratch dir at exit. This branch is creator-only by construction — a
+ * process that inherited an absolute root returns above without ever
+ * touching the memo, so a child can never delete its parent's scratch
+ * while the parent is still writing to it. Left unreaped, this seam was
+ * the single largest contributor to the OS-temp-root leak (870 surviving
+ * `mandrel-test-temp-` roots on one host), because it mints one per
+ * `run-tests.js` invocation.
+ *
  * Directly unit-tested via the injectable `mkdtemp` seam in
  * `tests/lib/test-env.test.js` (Story #4711).
  *
  * @param {NodeJS.ProcessEnv} [baseEnv=process.env]
- * @param {{ mkdtemp?: typeof mkdtempSync }} [deps] Injectable for tests.
+ * @param {{ mkdtemp?: typeof mkdtempSync, onExit?: (fn: () => void) => void }} [deps]
+ *   Injectable for tests.
  * @returns {string} absolute scratch tempRoot
  */
 export function ensureTestScratchTempRoot(
   baseEnv = process.env,
-  { mkdtemp = mkdtempSync } = {},
+  { mkdtemp = mkdtempSync, onExit } = {},
 ) {
   const existing = baseEnv?.[TEST_TEMP_ROOT_ENV];
   if (
@@ -52,7 +63,8 @@ export function ensureTestScratchTempRoot(
     return existing;
   }
   if (_createdScratchDir === null) {
-    _createdScratchDir = mkdtemp(path.join(os.tmpdir(), 'mandrel-test-temp-'));
+    _createdScratchDir = mkdtemp(path.join(os.tmpdir(), 'mandrel-test-temp-')); // test-temp-allow: children inherit this path, so it lives outside the suite root.
+    reapOnExit(_createdScratchDir, onExit ? { onExit } : {});
   }
   return _createdScratchDir;
 }

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/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,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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,
 ];
 
 /**

package/lib/migrations/steps/2.20.0-retire-codebase-snapshot.js

@@ -0,0 +1,113 @@
+// lib/migrations/steps/2.20.0-retire-codebase-snapshot.js
+/**
+ * Story #4811 — strip the retired `planning.codebaseSnapshot` block from a
+ * consumer's `.agentrc.json` / `.agentrc.local.json`.
+ *
+ * #4811 hard-cutover-removed the `/plan` codebase snapshot: the pre-computed
+ * structural view grounded nothing it promised (its default include globs
+ * missed the standard monorepo layout, and its knobs only re-filtered the same
+ * matched set), and spec authoring is grounded instead by the author's own
+ * targeted repo retrieval plus the Phase 8 `validateStoryFileAssumptions`
+ * gate. The whole block was dropped from the runtime AJV schema and the
+ * published mirror. `planning` carries `additionalProperties: false`, so a
+ * consumer whose config still sets `codebaseSnapshot` hits a hard validation
+ * failure on upgrade, not a warning. This step strips the key before that
+ * check runs — the same contract-cutover pattern as
+ * `2.11.0-retire-max-seed-words.js`, widened to the local override file
+ * because a snapshot narrowed for one checkout is exactly the kind of knob an
+ * operator pins in `.agentrc.local.json`.
+ */
+
+import nodeFs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Both config files the resolver deep-merges. A key surviving in either one
+ * fails validation, so both are stripped.
+ */
+const AGENTRC_FILENAMES = ['.agentrc.json', '.agentrc.local.json'];
+
+const RETIRED_KEY = 'codebaseSnapshot';
+
+/**
+ * @param {unknown} ctx
+ * @param {string} filename
+ * @returns {string}
+ */
+function resolveAgentrcPath(ctx, filename) {
+  const projectRoot = ctx?.projectRoot ?? process.cwd();
+  return path.join(projectRoot, filename);
+}
+
+/**
+ * @param {unknown} ctx
+ * @param {string} filename
+ * @param {typeof nodeFs} fsImpl
+ * @returns {object | null}
+ */
+function readAgentrcConfig(ctx, filename, fsImpl) {
+  try {
+    const raw = fsImpl.readFileSync(resolveAgentrcPath(ctx, filename), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {object | null} config
+ * @returns {boolean}
+ */
+function hasRetiredKey(config) {
+  const planning = config?.planning;
+  return Boolean(planning) && Object.hasOwn(planning, RETIRED_KEY);
+}
+
+/**
+ * Strip the key and prune the containers it emptied, so a config that carried
+ * nothing but the snapshot does not keep an orphan `planning: {}`.
+ *
+ * @param {object} config
+ * @returns {void}
+ */
+function stripRetiredKey(config) {
+  delete config.planning[RETIRED_KEY];
+  if (Object.keys(config.planning).length === 0) {
+    delete config.planning;
+  }
+}
+
+export const retireCodebaseSnapshot = {
+  version: '2.20.0',
+  description:
+    'strip retired planning.codebaseSnapshot from .agentrc.json / ' +
+    '.agentrc.local.json (spec authoring is grounded by targeted retrieval ' +
+    'plus the Phase 8 file-assumption gate — Story #4811)',
+  /**
+   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
+   * @returns {boolean}
+   */
+  detect(ctx) {
+    const fsImpl = ctx?.fs ?? nodeFs;
+    return AGENTRC_FILENAMES.some((filename) =>
+      hasRetiredKey(readAgentrcConfig(ctx, filename, fsImpl)),
+    );
+  },
+  /**
+   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
+   * @returns {void}
+   */
+  apply(ctx) {
+    const fsImpl = ctx?.fs ?? nodeFs;
+    for (const filename of AGENTRC_FILENAMES) {
+      const config = readAgentrcConfig(ctx, filename, fsImpl);
+      if (!hasRetiredKey(config)) continue;
+
+      stripRetiredKey(config);
+      fsImpl.writeFileSync(
+        resolveAgentrcPath(ctx, filename),
+        `${JSON.stringify(config, null, 2)}\n`,
+      );
+    }
+  },
+};