mandrel 2.19.0 → 2.20.0

package/.agents/docs/agentrc-reference.json

@@ -67,27 +67,6 @@
     }
   },
   "planning": {
-    "codebaseSnapshot": {
-      "tier": "skinny",
-      "include": [
-        ".agents/scripts/**",
-        "src/**",
-        "lib/**",
-        "app/**",
-        "packages/**"
-      ],
-      "exclude": [
-        "**/node_modules/**",
-        "**/dist/**",
-        "**/build/**",
-        "**/.next/**",
-        "**/.turbo/**",
-        "**/coverage/**",
-        "**/*.test.*",
-        "**/*.spec.*"
-      ],
-      "recentCommitWindow": 30
-    },
     "riskHeuristics": [
       "Destructive or irreversible data mutations (dropping tables, deleting rows without soft-delete or backup, truncating production state).",
       "Modifications to shared security or auth infrastructure (IAM policies, auth middleware, session or token handling, secret rotation).",

package/.agents/docs/configuration.md

@@ -26,7 +26,7 @@ with the runtime validators.
   "$schema": "./.agents/schemas/agentrc.schema.json",
   "project":  { /* paths, commands, baseBranch, docsContextFiles */ },
   "github":   { /* owner, repo, branchProtection, mergeMethods, notifications */ },
-  "planning": { /* riskHeuristics, conflict gates, codebaseSnapshot, context */ },
+  "planning": { /* riskHeuristics, conflict gates, complexityGate, navigation */ },
   "delivery": { /* execution, quality, worktreeIsolation, deliverRunner, ... */ }
 }
 ```
@@ -38,7 +38,7 @@ top-level keys are validation errors.
 | ------------- | -------- | ---------------------------------------------------------------------------------- |
 | `project`     | **Yes**  | Project-local paths, base branch, validation commands, and context-hydration files. |
 | `github`      | No       | Ticketing provider config: owner/repo, branch protection, merge methods, notifications. |
-| `planning`    | No       | `/plan` tuning: conflict advisories, codebase snapshot, context cap. (Story sizing ceilings are code-absolute — not agentrc.) |
+| `planning`    | No       | `/plan` tuning: conflict advisories, complexity routing, navigability gate. (Story sizing ceilings and the planner-context cap are code-absolute — not agentrc.) |
 | `delivery`    | No       | `/deliver` tuning: quality gates, worktree isolation, runners, CI watch, code-review providers. |
 | `$schema`     | No       | JSON Schema pointer for editor tooling.                                            |
 
@@ -97,11 +97,6 @@ top-level keys are validation errors.
 | Key | Required | Type | Default | Description |
 | --- | --- | --- | --- | --- |
 | `riskHeuristics` | No | `string[]` or `{ append?, prepend? }` | — | — |
-| `codebaseSnapshot` | No | `object` | — | Nested configuration block. |
-| `codebaseSnapshot.tier` | No | `"skinny"` \| `"medium"` | — | — |
-| `codebaseSnapshot.include` | No | `array<string>` | — | — |
-| `codebaseSnapshot.exclude` | No | `array<string>` | — | — |
-| `codebaseSnapshot.recentCommitWindow` | No | `integer` | — | — |
 | `complexityGate` | No | `object` | — | Shape-derived ceremony-lite complexity routing. A lite claim is validated against the authored Story shape at persist and re-derived from the Story body at dispatch; conservative (full on any doubt). Never relaxes the Story-ticket / PR-to-main / repo-gates / security-baseline non-negotiables. |
 | `complexityGate.enabled` | No | `boolean` | — | Master switch. When false, lite routing is disabled everywhere: persist refuses lite claims and dispatch always takes the sub-agent path. Default true. |
 | `complexityGate.maxArtifacts` | No | `integer` | — | Enumerated-artifact threshold reported by the plan-context complexity signals. An input signal for the planner verdict — carries no routing authority. Default 1. |
@@ -352,13 +347,15 @@ Defaults are **advisory, not Story-width ceilings**. Session-mass ceilings live
 as absolute authored-token constants on `DEFAULT_MODEL_CAPACITY` in
 `ticket-validator-sizing.js` (soft 30k / hard 75k); there is no `maxTokenBudget`
 envelope, and cohesion / split policy / conflict advisories are the primary
-sizing signal. The `codebaseSnapshot` `skinny` tier caps at 250 paths using
-**per-top-level-directory proportional budgeting** (round-robin across matched
-trees) so a large dot-prefixed tree like `.agents/scripts/**` cannot monopolise
-the budget and truncate away the consumer's own source; the shipped `include`
-scans `.agents/scripts/**`, `src/**`, `lib/**`, `app/**`, `packages/**` and
-`exclude` drops `node_modules`, build dirs, and test files. Override `include`
-only when the project's source layout differs.
+sizing signal.
+
+There is no snapshot knob to tune: Story #4811 retired the structural-snapshot
+block outright. Spec authoring is grounded by the author's own targeted repo
+retrieval plus the Phase 8 `validateStoryFileAssumptions` gate, which probes
+every authored `{path, assumption}` against the real tree as a hard error — a
+pre-computed inventory added a second, staler answer to the same question.
+A config still carrying the retired key is a hard validation failure; the
+2.20.0 retirement migration strips it on upgrade.
 
 - **`complexityGate`.** Shape-derived ceremony-lite routing (Story #4722,
   superseding the word-count gate of Stories #4683/#4707). The full ceremony

package/.agents/docs/execution-reference.md

@@ -96,12 +96,15 @@ over-ceiling envelope or an over-budget Story count.
 - **`PLAN_CONTEXT_ENVELOPE_BYTE_CEILING`** (`lib/orchestration/plan-context.js`):
   256 KB (≈64K tokens at the ≈4-chars/token estimate) on the serialized
   envelope `buildPlanContext` assembles, checked at the single choke point
-  every mode returns through. Measured envelopes on this repo land at ~42 KB,
-  so the ceiling is >2× headroom over a worst-case seed plus a medium-tier
-  codebase snapshot.
+  every mode returns through. A measured seed-mode envelope on this repo is
+  ~120 KB — `docsContext` (~63 KB) and `systemPrompts` (~54 KB) are the whole
+  of it, every other field under 1 KB — so the ceiling carries roughly 2×
+  headroom. Story #4811 retired the codebase snapshot that used to sit
+  alongside them, leaving the operator-supplied seed the only unbounded
+  contributor.
 - **On refusal**, the error names the envelope's largest fields. Trim the seed,
-  plan fewer `--tickets` source issues in one run, or narrow
-  `planning.codebaseSnapshot`. The seed is carried **verbatim** by design — it
+  or plan fewer `--tickets` source issues in one run. The seed is carried
+  **verbatim** by design — it
   is the operator's request, and summarizing it silently would degrade planning
   quality precisely when the input is richest — so there is no elision path to
   fall back on. Raising the ceiling needs a measured justification.

package/.agents/schemas/agentrc.schema.json

@@ -324,9 +324,6 @@
         "riskHeuristics": {
           "$ref": "#/$defs/listOrExtenderOfStrings"
         },
-        "codebaseSnapshot": {
-          "$ref": "#/$defs/codebaseSnapshot"
-        },
         "complexityGate": {
           "type": "object",
           "description": "Shape-derived ceremony-lite complexity routing. A lite claim is validated against the authored Story shape at persist and re-derived from the Story body at dispatch; conservative (full on any doubt). Never relaxes the Story-ticket / PR-to-main / repo-gates / security-baseline non-negotiables.",
@@ -392,34 +389,6 @@
       },
       "additionalProperties": false
     },
-    "codebaseSnapshot": {
-      "type": "object",
-      "properties": {
-        "tier": {
-          "type": "string",
-          "enum": ["skinny", "medium"]
-        },
-        "include": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "minLength": 1
-          }
-        },
-        "exclude": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "minLength": 1
-          }
-        },
-        "recentCommitWindow": {
-          "type": "integer",
-          "minimum": 1
-        }
-      },
-      "additionalProperties": false
-    },
     "execution": {
       "type": "object",
       "properties": {

package/.agents/scripts/check-test-temp-hygiene.js

@@ -15,16 +15,41 @@
  * per-process scratch dir. This script is the regression guard that keeps
  * the fix honest, plus a local cleanup mode for the accumulated noise:
  *
+ * The guard covers two distinct temp roots, and conflating them is how the
+ * second one went unmeasured for so long:
+ *
+ *   1. The repo's own `temp/` telemetry tree — the original dimension above.
+ *   2. The **OS temp root** (Story #4808). The redirect in (1) sends stray
+ *      writes into `os.tmpdir()` scratch dirs, and nothing ever reaped them:
+ *      the remedy for (1) became the largest single leaker into (2). Since
+ *      the damaging axis there is entry *count*, the suite now nests every
+ *      managed dir inside one per-process `mandrel-suite-*` root
+ *      (`lib/test-temp.js`) and reaps it, and this guard asserts that no
+ *      such root survives a run.
+ *
  *   --snapshot         Record a fingerprint (size + sha256) of every stream
- *                      file under `temp/` to the snapshot baseline. Run this
- *                      before the suite.
+ *                      file under `temp/`, plus the `mandrel-suite-*` roots
+ *                      already present in the OS temp root, to the snapshot
+ *                      baseline. Run this before the suite.
  *   --assert           Re-scan and fail if any stream file was added or grew
- *                      relative to the snapshot. Run this after the suite. A
- *                      missing snapshot is a hard failure ("snapshot missing
+ *                      relative to the snapshot, or if a suite root appeared
+ *                      and survived. Run this after the suite. A missing
+ *                      snapshot is a hard failure ("snapshot missing
  *                      — guard cannot attest"), never a silent re-baseline:
  *                      the baseline lives *outside* the protected `temp/`
  *                      tree (Story #4711), so a test wiping `temp/` can no
  *                      longer destroy the baseline and fail the guard open.
+ *                      Recording pre-existing suite roots (rather than
+ *                      asserting an empty set) is what keeps a concurrent
+ *                      suite in another checkout from failing this one.
+ *   --lint-globs <g>   Comma-separated repo-relative globs to scan for test
+ *                      files that call `mkdtemp` against `os.tmpdir()`
+ *                      directly instead of going through `makeTempDir`.
+ *                      **Off unless passed**: this script ships in the
+ *                      materialized `.agents/` payload and a consumer's
+ *                      tests are none of this rule's business. A line (or
+ *                      the line above it) carrying `test-temp-allow` opts
+ *                      out.
  *   --baseline <path>  Explicit snapshot-baseline path (CI sets this to a
  *                      runner-temp path). Defaults to an OS scratch location
  *                      keyed by the resolved repo root. Refused when it
@@ -53,6 +78,12 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runAsCli } from './lib/cli-utils.js';
+import {
+  findRawTmpdirMkdtemp,
+  listSuiteTempRoots,
+  SUITE_ROOTS_KEY,
+  survivingSuiteTempRoots,
+} from './lib/test-temp.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
@@ -193,17 +224,27 @@ export function buildManifest(tempDir) {
  * `defaultBaselinePath` — never inside `temp/`).
  * @param {string} repoRoot
  * @param {string} [baselinePath]
- * @returns {{ snapshotPath: string, count: number }}
+ * @param {{ tmpDir?: string }} [deps] Injectable OS temp root for tests.
+ * @returns {{ snapshotPath: string, count: number, suiteRoots: number }}
  */
-export function writeSnapshot(repoRoot, baselinePath) {
+export function writeSnapshot(repoRoot, baselinePath, { tmpDir } = {}) {
   const snapshotPath = checkedBaselinePath(
     repoRoot,
     baselinePath ?? defaultBaselinePath(repoRoot),
   );
   const manifest = buildManifest(tempDirFor(repoRoot));
+  const count = Object.keys(manifest).length;
+  // Reserved key: stream entries are always `*.ndjson` relative paths, so
+  // this cannot shadow one, and `diffAgainstSnapshot` only ever looks up
+  // keys derived from the tree it just walked.
+  manifest[SUITE_ROOTS_KEY] = listSuiteTempRoots(tmpDir ?? os.tmpdir());
   mkdirSync(path.dirname(snapshotPath), { recursive: true });
   writeFileSync(snapshotPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
-  return { snapshotPath, count: Object.keys(manifest).length };
+  return {
+    snapshotPath,
+    count,
+    suiteRoots: manifest[SUITE_ROOTS_KEY].length,
+  };
 }
 
 /**
@@ -331,7 +372,7 @@ export function cleanFixtureDirs({
 /**
  * Parse the CLI argv into a normalised options object.
  * @param {string[]} argv
- * @returns {{ mode: 'snapshot'|'assert'|'clean', apply: boolean, ids: number[]|null, repoRoot: string, baseline: string|null }}
+ * @returns {{ mode: 'snapshot'|'assert'|'clean', apply: boolean, ids: number[]|null, repoRoot: string, baseline: string|null, lintGlobs: string[] }}
  */
 export function parseArgv(argv) {
   let mode = 'assert';
@@ -339,13 +380,20 @@ export function parseArgv(argv) {
   let ids = null;
   let repoRoot = REPO_ROOT;
   let baseline = null;
+  let lintGlobs = [];
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--snapshot') mode = 'snapshot';
     else if (arg === '--assert') mode = 'assert';
     else if (arg === '--clean') mode = 'clean';
     else if (arg === '--yes') apply = true;
-    else if (arg === '--ids') {
+    else if (arg === '--lint-globs') {
+      i += 1;
+      lintGlobs = String(argv[i] ?? '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    } else if (arg === '--ids') {
       i += 1;
       ids = String(argv[i] ?? '')
         .split(',')
@@ -359,7 +407,7 @@ export function parseArgv(argv) {
       baseline = path.resolve(String(argv[i] ?? '.'));
     }
   }
-  return { mode, apply, ids, repoRoot, baseline };
+  return { mode, apply, ids, repoRoot, baseline, lintGlobs };
 }
 
 /**
@@ -369,14 +417,23 @@ export function parseArgv(argv) {
  *
  * @param {ReturnType<typeof parseArgv>} opts
  * @param {(line: string) => void} [log]
+ * @param {{ tmpDir?: string }} [deps] Injectable OS temp root for tests.
  * @returns {number}
  */
-export function runHygiene(opts, log = (l) => process.stdout.write(`${l}\n`)) {
-  const { mode, apply, ids, repoRoot, baseline = null } = opts;
+export function runHygiene(
+  opts,
+  log = (l) => process.stdout.write(`${l}\n`),
+  { tmpDir = os.tmpdir() } = {},
+) {
+  const { mode, apply, ids, repoRoot, baseline = null, lintGlobs = [] } = opts;
   if (mode === 'snapshot') {
-    const { snapshotPath, count } = writeSnapshot(repoRoot, baseline);
+    const { snapshotPath, count, suiteRoots } = writeSnapshot(
+      repoRoot,
+      baseline,
+      { tmpDir },
+    );
     log(
-      `[test-temp-hygiene] snapshot recorded (${count} stream file(s)) → ${snapshotPath}`,
+      `[test-temp-hygiene] snapshot recorded (${count} stream file(s), ${suiteRoots} pre-existing suite root(s)) → ${snapshotPath}`,
     );
     return 0;
   }
@@ -409,6 +466,26 @@ export function runHygiene(opts, log = (l) => process.stdout.write(`${l}\n`)) {
     );
     return 1;
   }
+  // Every dimension runs and reports; a failure in one must not hide a
+  // failure in another, so the exit code is the max rather than an
+  // early return.
+  const codes = [
+    assertStreamTree(repoRoot, snapshot, log),
+    assertNoSurvivingSuiteRoots(snapshot, log, tmpDir),
+    assertNoRawTmpdirMkdtemp(repoRoot, lintGlobs, log),
+  ];
+  return Math.max(...codes);
+}
+
+/**
+ * Dimension 1 — the repo's own `temp/` telemetry tree (Story #4696).
+ *
+ * @param {string} repoRoot
+ * @param {Record<string, unknown>} snapshot
+ * @param {(line: string) => void} log
+ * @returns {number} exit code
+ */
+function assertStreamTree(repoRoot, snapshot, log) {
   const { added, changed } = diffAgainstSnapshot(
     tempDirFor(repoRoot),
     snapshot,
@@ -428,6 +505,68 @@ export function runHygiene(opts, log = (l) => process.stdout.write(`${l}\n`)) {
   return 1;
 }
 
+/**
+ * Dimension 2 — the OS temp root (Story #4808). Fails when a suite root
+ * appeared since the snapshot and is still on disk, which means the run
+ * created it and never reaped it.
+ *
+ * @param {Record<string, unknown>} snapshot
+ * @param {(line: string) => void} log
+ * @param {string} tmpDir
+ * @returns {number} exit code
+ */
+function assertNoSurvivingSuiteRoots(snapshot, log, tmpDir) {
+  const before = Array.isArray(snapshot[SUITE_ROOTS_KEY])
+    ? snapshot[SUITE_ROOTS_KEY]
+    : [];
+  const surviving = survivingSuiteTempRoots(tmpDir, before);
+  if (surviving.length === 0) {
+    log('[test-temp-hygiene] OK — no suite temp roots survived the run.');
+    return 0;
+  }
+  log(
+    `[test-temp-hygiene] FAIL — ${surviving.length} suite temp root(s) survived in ${tmpDir}:`,
+  );
+  for (const name of surviving) log(`  + leaked ${name}`);
+  log(
+    '[test-temp-hygiene] a process minted a suite root and exited without reaping it. Do not delete these by hand — find the writer that bypassed makeTempDir().',
+  );
+  return 1;
+}
+
+/**
+ * Dimension 3 — the static backstop (Story #4808). Skipped, and reported
+ * as skipped, unless the caller passed `--lint-globs`.
+ *
+ * @param {string} repoRoot
+ * @param {string[]} globs
+ * @param {(line: string) => void} log
+ * @returns {number} exit code
+ */
+function assertNoRawTmpdirMkdtemp(repoRoot, globs, log) {
+  if (!globs || globs.length === 0) {
+    log(
+      '[test-temp-hygiene] SKIP — raw-tmpdir lint not requested (pass --lint-globs to enable).',
+    );
+    return 0;
+  }
+  const findings = findRawTmpdirMkdtemp(repoRoot, globs);
+  if (findings.length === 0) {
+    log(
+      '[test-temp-hygiene] OK — no test file mints OS temp dirs outside makeTempDir().',
+    );
+    return 0;
+  }
+  log(
+    `[test-temp-hygiene] FAIL — ${findings.length} raw os.tmpdir() mkdtemp call(s) in test files:`,
+  );
+  for (const f of findings) log(`  ${f.file}:${f.line}  ${f.text}`);
+  log(
+    "[test-temp-hygiene] use makeTempDir() from .agents/scripts/lib/test-temp.js so teardown is registered, or mark the line 'test-temp-allow: <reason>' when the real root is genuinely required.",
+  );
+  return 1;
+}
+
 runAsCli(
   import.meta.url,
   async () => {

package/.agents/scripts/lib/baselines/kinds/maintainability.js

@@ -60,11 +60,10 @@ export const MAINTAINABILITY_EXCLUSIONS = Object.freeze(
     // the audit-to-stories parser reuses the same regex-property scan
     // patterns as acceptance-spec-reconciler.
     '.agents/scripts/lib/audit-to-stories/parse-audit-md.js',
-    // escomplex: same "pattern" parse failure family — BDD scanner and
-    // codebase snapshot helpers walk source trees with regex visitors that
-    // hit the upstream destructuring bug.
+    // escomplex: same "pattern" parse failure family — the BDD scanner walks
+    // source trees with regex visitors that hit the upstream destructuring
+    // bug.
     '.agents/scripts/lib/bdd-scenario-scanner.js',
-    '.agents/scripts/lib/codebase-snapshot.js',
     // escomplex: same "pattern" parse failure — the wave-runner tick uses
     // the regex-property destructuring escomplex chokes on.
     '.agents/scripts/lib/wave-runner/tick.js',

package/.agents/scripts/lib/bdd-scenario-scanner.js

@@ -1,8 +1,9 @@
 /**
  * bdd-scenario-scanner.js — Gherkin scenario index for /plan Phase 7.
  *
- * Story #2637 (sibling to #2634 codebase-snapshot, #2635 spec-freshness,
- * #2636 file-assumption gate). The Acceptance Engineer step of
+ * Story #2637 (sibling to #2636's file-assumption gate; the #2634 and #2635
+ * planner-grounding siblings were retired in Story #4811). The Acceptance
+ * Engineer step of
  * `epic-plan-spec-author` currently writes ACs from Epic/Tech Spec narrative
  * alone — it never inspects the consumer project's existing `.feature`
  * files. Planned ACs frequently duplicate scenarios that already exist or

package/.agents/scripts/lib/config/explain.js

@@ -114,14 +114,6 @@ const KEY_MEANINGS = Object.freeze({
     'Allowlist of events that fire a webhook notification.',
 
   // planning.*
-  'planning.codebaseSnapshot.tier':
-    'Depth of the structural codebase view threaded into spec authoring.',
-  'planning.codebaseSnapshot.include':
-    'Glob patterns included in the codebase snapshot.',
-  'planning.codebaseSnapshot.exclude':
-    'Glob patterns excluded from the codebase snapshot.',
-  'planning.codebaseSnapshot.recentCommitWindow':
-    'How many recent commits the snapshot summarizes.',
   'planning.riskHeuristics':
     'Phrases that flag a Story as high-risk for HITL escalation.',
   'planning.failOnSharedEditors':

package/.agents/scripts/lib/config/temp-paths.js

@@ -56,6 +56,8 @@ import { mkdtempSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
+import { reapOnExit } from '../test-temp.js';
+
 /**
  * Cache the resolved main-checkout root per spawn cwd so the
  * `git rev-parse` shell-out runs at most once per distinct working
@@ -223,7 +225,7 @@ function inNodeTestContext(env, execArgv) {
  *
  * @param {string} tempRoot
  * @param {NodeJS.ProcessEnv} [env=process.env]
- * @param {{ mkdtemp?: typeof mkdtempSync, execArgv?: string[] }} [deps]
+ * @param {{ mkdtemp?: typeof mkdtempSync, execArgv?: string[], onExit?: (fn: () => void) => void }} [deps]
  *   Injectable for tests.
  * @returns {string}
  */
@@ -238,9 +240,18 @@ export function anchorTempRoot(tempRoot, env = process.env, deps = {}) {
   ) {
     if (_testContextScratchDir === null) {
       const mkdtemp = deps.mkdtemp ?? mkdtempSync;
+      // test-temp-allow: published to children below, so it must live
+      // outside the per-process suite root that this process reaps.
       _testContextScratchDir = mkdtemp(
         path.join(os.tmpdir(), 'mandrel-test-temp-'),
       );
+      // Creator-only reaping (Story #4808): a process that read the root
+      // from the env returned at `scratch` above and never reaches here,
+      // so it can never remove a root its parent is still writing to.
+      reapOnExit(
+        _testContextScratchDir,
+        deps.onExit ? { onExit: deps.onExit } : {},
+      );
       if (env === process.env) {
         // Children spawned by this test process inherit the same scratch.
         process.env[TEST_TEMP_ROOT_ENV] = _testContextScratchDir;

package/.agents/scripts/lib/config-settings-schema.js

@@ -249,35 +249,19 @@ const GITHUB_SCHEMA = {
 // rejected as an additional property, so a resurrected key fails loudly rather
 // than silently doing nothing.
 
-/**
- * Story #2634 — `planning.codebaseSnapshot` controls the structural
- * view of the consumer repo threaded into `/plan` Phase 7 spec
- * authoring. Absent / partial entries resolve to defaults inside
- * `lib/codebase-snapshot.js#resolveSnapshotConfig` — the schema only
- * enforces shape (correct enum value, well-formed glob arrays).
- */
-const CODEBASE_SNAPSHOT_SCHEMA = {
-  type: 'object',
-  properties: {
-    tier: { type: 'string', enum: ['skinny', 'medium'] },
-    include: {
-      type: 'array',
-      items: { type: 'string', minLength: 1 },
-    },
-    exclude: {
-      type: 'array',
-      items: { type: 'string', minLength: 1 },
-    },
-    recentCommitWindow: { type: 'integer', minimum: 1 },
-  },
-  additionalProperties: false,
-};
+// Story #4811: the `planning` block's structural-snapshot key was retired
+// along with the snapshot itself. The pre-computed view it configured grounded
+// nothing — its default include globs missed the standard monorepo layout, and
+// its knobs only re-filtered the same matched set. Spec authoring is grounded
+// by the author's own targeted repo retrieval plus the Phase 8
+// `validateStoryFileAssumptions` gate, neither of which is configurable here.
+// `planning` carries `additionalProperties: false`, so a resurrected key fails
+// loudly; the 2.20.0 retirement migration strips it on upgrade.
 
 const PLANNING_SCHEMA = {
   type: 'object',
   properties: {
     riskHeuristics: LIST_OR_EXTENDER_OF_STRINGS,
-    codebaseSnapshot: CODEBASE_SNAPSHOT_SCHEMA,
     // Story #4722 (superseding #4683's word-count gate) — shape-derived
     // ceremony-lite routing. Complexity routes on the objective shape of the
     // authored work (changes[] count, acceptance count, creates-vs-refactors

package/.agents/scripts/lib/orchestration/file-assumptions.js

@@ -60,8 +60,10 @@ import { isObjectPathEntry } from './task-body-validator.js';
 /**
  * Default git probe — returns `true` when `path` exists at
  * `baseBranchRef`. Mirrors the existence check used by
- * {@link ./ticket-validator.js#validateAcFreshness} and
- * {@link ./spec-freshness.js} so all three gates share semantics.
+ * {@link ./ticket-validator.js#validateAcFreshness} so both gates share
+ * semantics. (Story #4811 deleted the third sharer, `spec-freshness.js`,
+ * along with the codebase snapshot it grounded; this gate — Phase 8 — is
+ * now the grounding gate and its behaviour is unchanged.)
  *
  * @param {{ baseBranchRef: string, path: string, cwd?: string }} opts
  * @returns {boolean}

package/.agents/scripts/lib/orchestration/plan-context.js

@@ -48,15 +48,16 @@ const SOURCE_TICKET_FETCH_CONCURRENCY = 4;
  * body and ship the raw seed on `seed.content` instead — the budget bounded
  * a field that never left the function.
  *
- * The envelope's bounded parts are: the tier-capped codebase snapshot
- * (~35 KB skinny on this repo), the three rendered system prompts (~15 KB),
- * and the digest-first `docsContext` (outline-only, or inline digest in
- * one-pager/seed mode). The seed itself is operator-supplied and carried
- * verbatim. Measured folded envelopes on this repo land at ~42 KB; 256 KB
- * (~64K tokens at the ≈4-chars/token estimate) gives >2× headroom over a
- * worst-case seed + medium-tier snapshot while staying an order of magnitude
- * under the session budget. The test suite asserts serialized envelopes stay
- * under this value — raise it only with a measured justification.
+ * A measured seed-mode envelope on this repo is ~120 KB, dominated by the
+ * digest-first `docsContext` (~63 KB inline digest) and the rendered
+ * `systemPrompts` (~54 KB); every other field is under 1 KB. Story #4811
+ * retired the tier-capped codebase snapshot that used to sit alongside them
+ * (~35 KB skinny here). The seed itself is operator-supplied, carried
+ * verbatim, and is the only unbounded contributor. 256 KB (~64K tokens at the
+ * ≈4-chars/token estimate) leaves roughly 2× headroom over that measurement
+ * while staying well under the session budget. The test suite asserts
+ * serialized envelopes stay under this value — raise it only with a measured
+ * justification.
  */
 export const PLAN_CONTEXT_ENVELOPE_BYTE_CEILING = 256_000;
 
@@ -112,9 +113,9 @@ function assertPlanContextWithinCeiling(envelope, opts = {}) {
     `[plan-context] the assembled "${envelope?.mode}" envelope is ` +
       `${Math.round(bytes / 1024)} KB, over the ` +
       `${Math.round(ceiling / 1024)} KB planner-context ceiling. Largest ` +
-      `fields: ${largest}. Trim the seed, plan fewer --tickets source issues ` +
-      'in one run, or narrow `planning.codebaseSnapshot`. Raising the ceiling ' +
-      'needs a measured justification — see PLAN_CONTEXT_ENVELOPE_BYTE_CEILING.',
+      `fields: ${largest}. Trim the seed, or plan fewer --tickets source ` +
+      'issues in one run. Raising the ceiling needs a measured ' +
+      'justification — see PLAN_CONTEXT_ENVELOPE_BYTE_CEILING.',
   );
 }
 
@@ -890,7 +891,6 @@ async function buildSeedFileModeEnvelope({
     ),
     duplicates,
     docsContext,
-    codebaseSnapshot: authoring.codebaseSnapshot,
     bddRunner: authoring.bddRunner,
     bddScenarios: authoring.bddScenarios,
     memoryFreshness: authoring.memoryFreshness,
@@ -1052,7 +1052,6 @@ async function buildTicketsModeEnvelope({
     ),
     duplicates,
     docsContext,
-    codebaseSnapshot: authoring.codebaseSnapshot,
     bddRunner: authoring.bddRunner,
     bddScenarios: authoring.bddScenarios,
     memoryFreshness: authoring.memoryFreshness,