mandrel 2.18.0 → 2.20.0

package/.agents/scripts/lib/baselines/env-overrides.js

@@ -83,69 +83,61 @@ export function resolveCrapEnvOverrides(crapConfig, env) {
 }
 
 /**
- * Pure helper: resolve the one-shot bundle-size refresh/acknowledge flag
- * (Story #151). Unlike `coverage` / `crap` / `maintainability`, the
- * bundle-size gate has no scorer of its own — the measured sizes come from
- * a build step the operator already runs, not a source-tree rescan — so
- * there is no `refreshBaseline({ kind: 'bundle-size', ... })` path to
- * regenerate a "corrected" baseline. Instead, `BUNDLE_SIZE_REFRESH=1`
- * (mirroring `CRAP_TOLERANCE`'s env-override precedent) tells
- * `check-baselines --gate bundle-size` to treat this run's head
- * measurements as the newly acknowledged baseline: head-vs-base
- * regressions are demoted to `unchanged` for this invocation only. Floors
- * still apply — an acknowledged PR can still fail on an absolute budget
- * breach, only the ratchet-vs-`origin/main` comparison is suspended.
+ * The env var that acknowledges a deliberate baseline refresh for `kind`.
+ * Upper-snakes the kind name, so `bundle-size` → `BUNDLE_SIZE_REFRESH` and
+ * `coverage` → `COVERAGE_REFRESH`. The two names that predate the generic
+ * mechanism (`BUNDLE_SIZE_REFRESH`, Story #151; `MAINTAINABILITY_REFRESH`,
+ * Story #4731) are exactly what this rule produces, so generalizing kept
+ * both working unchanged.
  *
- * The flag is **not persisted** anywhere (no config write, no committed
- * tag): the very next `check-baselines` invocation without the env var —
- * i.e. the next PR — reverts to full strict enforcement automatically, so
- * there is no lingering loosened tolerance to remember to reset (AC-3).
+ * Module-local: `resolveKindRefreshOverrides` is the public surface, and the
+ * naming rule is pinned through it rather than exported for its own sake.
  *
- * Accepted truthy values: `1`, `true` (case-insensitive). Anything else
- * (including unset/empty) resolves to `acknowledged: false`.
- *
- * @param {NodeJS.ProcessEnv} env
- * @returns {{ acknowledged: boolean, overrides: string[] }}
+ * @param {string} kind
+ * @returns {string|null} null when `kind` is not a usable kind name
  */
-export function resolveBundleSizeEnvOverrides(env) {
-  const raw = env?.BUNDLE_SIZE_REFRESH;
-  const acknowledged =
-    typeof raw === 'string' && /^(1|true)$/i.test(raw.trim());
-  const overrides = acknowledged
-    ? [`acknowledged=true (BUNDLE_SIZE_REFRESH=${raw})`]
-    : [];
-  return { acknowledged, overrides };
+function kindRefreshEnvVar(kind) {
+  if (typeof kind !== 'string' || kind.length === 0) return null;
+  return `${kind.toUpperCase().replace(/-/g, '_')}_REFRESH`;
 }
 
 /**
- * Pure helper: resolve the one-shot maintainability refresh/acknowledge flag
- * (Story #4731). This is the env-parity sibling of
- * `resolveBundleSizeEnvOverrides`: `MAINTAINABILITY_REFRESH=1` (or `true`,
- * case-insensitive) tells `check-baselines --gate maintainability` to demote
- * this run's head-vs-base maintainability regressions to `unchanged` for this
- * invocation only. Floors still apply — an acknowledged run can still fail on
- * an absolute floor breach (e.g. a row below `min` 70); only the
- * ratchet-vs-base regression comparison is suspended.
+ * Pure helper: resolve the one-shot baseline refresh/acknowledge flag for any
+ * ratcheted kind (Story #4802, generalizing Story #151 / Story #4731).
+ *
+ * `<KIND>_REFRESH=1` tells `check-baselines --gate <kind>` to demote this
+ * run's head-vs-base regressions to `unchanged` for this invocation only.
+ * Floors still apply — an acknowledged run can still fail on an absolute
+ * floor breach; only the ratchet-vs-base comparison is suspended.
+ *
+ * Why every kind needs this: a diff-scope baseline is an accretion of many
+ * partial runs, not one measurement. Replacing it with a single full-scope
+ * measurement necessarily produces row deltas in both directions that are
+ * arithmetic, not behavioural — so without an acknowledgment path the gate
+ * blocks precisely the correction it should encourage.
  *
- * Unlike bundle-size, maintainability also has a **commit-tagged** trigger
- * (a `baseline-refresh:`-tagged commit in the compared range that touches the
- * maintainability baseline file) resolved in the evaluate phase — this env
- * flag is the manual override the two share by shape. Neither is persisted:
- * the next run without the flag / tag re-enforces the ratchet at full
- * strength automatically.
+ * The flag is **not persisted** anywhere (no config write, no committed tag):
+ * the very next invocation without the env var reverts to full strict
+ * enforcement automatically, so there is no lingering loosened tolerance to
+ * remember to reset. The evaluate phase pairs this with a commit-tagged
+ * trigger that is likewise one-shot by construction.
  *
- * Accepted truthy values: `1`, `true` (case-insensitive). Anything else
- * (including unset/empty) resolves to `acknowledged: false`.
+ * Accepted truthy values: `1`, `true` (case-insensitive), with surrounding
+ * whitespace trimmed. Anything else — including unset, empty, `0`, `false`,
+ * and non-string values — resolves to `acknowledged: false`.
  *
+ * @param {string} kind
  * @param {NodeJS.ProcessEnv} env
  * @returns {{ acknowledged: boolean, overrides: string[] }}
  */
-export function resolveMaintainabilityRefreshOverrides(env) {
-  const raw = env?.MAINTAINABILITY_REFRESH;
+export function resolveKindRefreshOverrides(kind, env) {
+  const varName = kindRefreshEnvVar(kind);
+  if (!varName) return { acknowledged: false, overrides: [] };
+  const raw = env?.[varName];
   const acknowledged =
     typeof raw === 'string' && /^(1|true)$/i.test(raw.trim());
   const overrides = acknowledged
-    ? [`acknowledged=true (MAINTAINABILITY_REFRESH=${raw})`]
+    ? [`acknowledged=true (${varName}=${raw})`]
     : [];
   return { acknowledged, overrides };
 }

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/check-baselines/phases/evaluate.js

@@ -7,10 +7,7 @@
  * @module lib/orchestration/check-baselines/phases/evaluate
  */
 
-import {
-  resolveBundleSizeEnvOverrides,
-  resolveMaintainabilityRefreshOverrides,
-} from '../../../baselines/env-overrides.js';
+import { resolveKindRefreshOverrides } from '../../../baselines/env-overrides.js';
 import { readRangeSubjectsTouchingFile } from '../../../baselines/git-base.js';
 import {
   checkBaselineSemantics,
@@ -91,57 +88,34 @@ function loadHeadBaseline(kind, cwd, configPath) {
 }
 
 /**
- * One-shot bundle-size refresh/acknowledge (Story #151). When
- * `BUNDLE_SIZE_REFRESH=1` is set, demote every `bundle-size` regression to
- * `unchanged` for this run only — floors still apply, so a genuine budget
- * breach is still caught. The flag is read fresh on every invocation and
- * never persisted, so the ratchet returns to full strength automatically on
- * the very next run (no lingering loosened tolerance to remember to reset).
- *
- * No-op for every other kind.
- */
-function applyBundleSizeAcknowledgment(kind, compareOutput, env) {
-  if (kind !== 'bundle-size') return { compareOutput, acknowledged: false };
-  const { acknowledged, overrides } = resolveBundleSizeEnvOverrides(env);
-  if (!acknowledged || compareOutput.regressions.length === 0) {
-    return { compareOutput, acknowledged: false };
-  }
-  Logger.warn(
-    `[bundle-size] ⚠ ${overrides.join(', ')} — ` +
-      `${compareOutput.regressions.length} regression(s) acknowledged for this run only; ` +
-      'floors still enforced. This does not persist: the next run without ' +
-      'BUNDLE_SIZE_REFRESH re-enforces the ratchet at full strength.',
-  );
-  return {
-    acknowledged: true,
-    compareOutput: {
-      ...compareOutput,
-      regressions: [],
-      unchanged: [...compareOutput.unchanged, ...compareOutput.regressions],
-    },
-  };
-}
-
-/**
- * Resolve the maintainability refresh trigger (Story #4731). Two paths, either
- * of which acknowledges — mirroring the bundle-size acknowledge but adding the
- * commit-tagged trigger the breach message already documents:
+ * Resolve the one-shot refresh trigger for any ratcheted kind (Story #4802,
+ * generalizing Story #151's bundle-size env flag and Story #4731's
+ * maintainability env-or-commit-tag pair). Two paths, either of which
+ * acknowledges:
  *
- *   1. Env parity: `MAINTAINABILITY_REFRESH=1` (the manual override).
+ *   1. Env parity: `<KIND>_REFRESH=1` (the manual override) — upper-snaked,
+ *      so the two pre-existing names (`BUNDLE_SIZE_REFRESH`,
+ *      `MAINTAINABILITY_REFRESH`) keep working unchanged.
  *   2. Commit tag: a commit in the compared range `<baseRef>..HEAD` whose
- *      subject contains the configured `refreshTag` AND whose diff touches the
- *      maintainability baseline file. One-shot by construction — once merged,
- *      the refreshed baseline becomes the base and the tag leaves the range.
+ *      subject contains the configured `refreshTag` AND whose diff touches
+ *      that kind's baseline file. One-shot by construction — once merged, the
+ *      refreshed baseline becomes the base and the tag leaves the range.
  *
  * The tag is matched as a plain substring of a conventional commit subject, so
  * commitlint stays satisfied (e.g. `chore(baselines): baseline-refresh: …`).
  *
+ * Fails closed: a kind whose baseline path is neither configured nor present
+ * in `DEFAULT_BASELINE_PATHS` simply skips the commit-tag path rather than
+ * throwing, leaving the run un-acknowledged.
+ *
  * @returns {{ triggered: boolean, reasons: string[] }}
  */
-function resolveMaintainabilityRefreshTrigger({ gateBlock, cmp, cwd, env }) {
+function resolveRefreshTrigger({ kind, gateBlock, cmp, cwd, env }) {
   const reasons = [];
-  const { acknowledged: envAck, overrides } =
-    resolveMaintainabilityRefreshOverrides(env);
+  const { acknowledged: envAck, overrides } = resolveKindRefreshOverrides(
+    kind,
+    env,
+  );
   if (envAck) reasons.push(...overrides);
 
   const baseRef = cmp?.baseRef ?? null;
@@ -154,15 +128,17 @@ function resolveMaintainabilityRefreshTrigger({ gateBlock, cmp, cwd, env }) {
       typeof gateBlock?.baselinePath === 'string' &&
       gateBlock.baselinePath.length
         ? gateBlock.baselinePath
-        : DEFAULT_BASELINE_PATHS.maintainability;
-    const subjects = readRangeSubjectsTouchingFile(baseRef, baselinePath, {
-      cwd,
-    });
-    const match = subjects.find((s) => s.includes(refreshTag));
-    if (match) {
-      reasons.push(
-        `refresh commit "${match}" (subject contains ${JSON.stringify(refreshTag)}, touches ${baselinePath})`,
-      );
+        : DEFAULT_BASELINE_PATHS[kind];
+    if (typeof baselinePath === 'string' && baselinePath.length) {
+      const subjects = readRangeSubjectsTouchingFile(baseRef, baselinePath, {
+        cwd,
+      });
+      const match = subjects.find((s) => s.includes(refreshTag));
+      if (match) {
+        reasons.push(
+          `refresh commit "${match}" (subject contains ${JSON.stringify(refreshTag)}, touches ${baselinePath})`,
+        );
+      }
     }
   }
 
@@ -170,26 +146,24 @@ function resolveMaintainabilityRefreshTrigger({ gateBlock, cmp, cwd, env }) {
 }
 
 /**
- * One-shot maintainability refresh/acknowledge (Story #4731). When triggered
- * (env flag OR a `baseline-refresh:`-tagged range commit touching the baseline),
- * demote every maintainability head-vs-base regression to `unchanged` for this
- * run only — floors still apply, so a row below its `min` floor still breaches.
- * The trigger is read fresh every run and never persisted: post-merge the
- * refreshed baseline is the new base and the tag leaves the range, so the
- * ratchet returns to full strength automatically.
+ * One-shot baseline refresh/acknowledge for any ratcheted kind (Story #4802).
+ * When triggered (env flag OR a `baseline-refresh:`-tagged range commit
+ * touching that kind's baseline), demote every head-vs-base regression to
+ * `unchanged` for this run only — floors still apply, so a row below its floor
+ * still breaches. The trigger is read fresh every run and never persisted:
+ * post-merge the refreshed baseline is the new base and the tag leaves the
+ * range, so the ratchet returns to full strength automatically.
  *
- * No-op for every other kind.
+ * A no-op absent a trigger, so an unacknowledged run of any kind reports its
+ * regressions exactly as before.
  */
-function applyMaintainabilityAcknowledgment(kind, compareOutput, ctx) {
-  if (kind !== 'maintainability') {
-    return { compareOutput, acknowledged: false };
-  }
-  const { triggered, reasons } = resolveMaintainabilityRefreshTrigger(ctx);
+function applyRefreshAcknowledgment(kind, compareOutput, ctx) {
+  const { triggered, reasons } = resolveRefreshTrigger({ ...ctx, kind });
   if (!triggered || compareOutput.regressions.length === 0) {
     return { compareOutput, acknowledged: false };
   }
   Logger.warn(
-    `[maintainability] ⚠ ${reasons.join('; ')} — ` +
+    `[${kind}] ⚠ ${reasons.join('; ')} — ` +
       `${compareOutput.regressions.length} regression(s) acknowledged for this run only; ` +
       'floors still enforced. This does not persist: once the refresh is the ' +
       'new base the ratchet re-enforces at full strength.',
@@ -274,14 +248,14 @@ export async function evaluateKind({
     rawCompare,
     gateBlock.tolerance ?? null,
   );
-  const bundleAck = applyBundleSizeAcknowledgment(kind, toleratedCompare, env);
-  const miAck = applyMaintainabilityAcknowledgment(
-    kind,
-    bundleAck.compareOutput,
-    { gateBlock, cmp, cwd, env },
-  );
-  const compareOutput = miAck.compareOutput;
-  const acknowledged = bundleAck.acknowledged || miAck.acknowledged;
+  const ack = applyRefreshAcknowledgment(kind, toleratedCompare, {
+    gateBlock,
+    cmp,
+    cwd,
+    env,
+  });
+  const compareOutput = ack.compareOutput;
+  const acknowledged = ack.acknowledged;
   return buildGateReport({
     kind,
     gateBlock,

package/.agents/scripts/lib/orchestration/check-baselines/phases/parse-args.js

@@ -44,18 +44,26 @@ compare) over every configured gate, with centralised friction emission and
 aggregated exit codes.
 
 Env vars:
-  BUNDLE_SIZE_REFRESH=1  One-shot acknowledge for an intentional bundle-size
-                         growth: demotes bundle-size regressions to
-                         "unchanged" for this run only (floors still
-                         enforced). Never persisted — the next run without
-                         this flag re-enforces the ratchet.
-  MAINTAINABILITY_REFRESH=1
-                         One-shot acknowledge for a deliberate maintainability
-                         baseline refresh: demotes maintainability head-vs-base
-                         regressions to "unchanged" for this run only (floors
-                         still enforced). Env-parity override for the
-                         'baseline-refresh:'-tagged range commit that touches
-                         baselines/maintainability.json. Never persisted.
+  <KIND>_REFRESH=1       One-shot acknowledge for a deliberate baseline
+                         refresh of that kind: demotes its head-vs-base
+                         regressions to "unchanged" for this run only. Floors
+                         are STILL enforced, so a genuine breach is still
+                         caught. The kind name is upper-snaked, e.g.
+                         COVERAGE_REFRESH, CRAP_REFRESH, DUPLICATION_REFRESH,
+                         MAINTAINABILITY_REFRESH, BUNDLE_SIZE_REFRESH.
+                         Never persisted — the next run without the flag
+                         re-enforces the ratchet at full strength.
+
+                         Equivalent commit-tagged trigger: a commit in the
+                         compared range whose subject contains the gate's
+                         'refreshTag' (default 'baseline-refresh:') AND whose
+                         diff touches that kind's baseline file. One-shot by
+                         construction — once merged the refreshed baseline is
+                         the new base and the tag leaves the range.
+
+                         Use these when replacing a diff-scope baseline with a
+                         full-scope measurement: the resulting row deltas are
+                         arithmetic, not behavioural.
 
 Exit codes:
   0  every enabled gate passes

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/lifecycle/listeners/README.md

@@ -2,7 +2,8 @@
 
 Each listener in this directory subscribes to one or more lifecycle bus
 events and performs a single side effect. The full close-tail roster and
-event taxonomy live in [`docs/LIFECYCLE.md`](../../../../../../docs/LIFECYCLE.md)
+event taxonomy live in
+[`docs/LIFECYCLE.md`](https://github.com/dsj1984/mandrel/blob/main/docs/LIFECYCLE.md)
 — that document is the SSOT. This README only indexes the **files that still
 live in this folder**.
 

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,