mandrel 2.19.0 → 2.21.0

package/.agents/agents/story-worker.md

@@ -134,6 +134,16 @@ outside the worktree / branch / PR path — or committing it to local `main`
 — is expressly **forbidden**; the close pipeline's push
 (`single-story-close.js`) is the only sanctioned landing.
 
+## Hold the turn until the envelope arrives (MUST)
+
+Run close in the **foreground** and wait for it. Never background it,
+never delegate it to a child, and never end your turn while it is still
+running — "close is running" is not a return value. Ending early strands
+the envelope in a turn nobody reads and costs your caller a recovery
+cycle plus a full resume of you. Close does persist a copy to
+`temp/orchestration/story-deliver-terminal-<id>.json`; that is your
+caller's fallback, not your licence to return before the verdict.
+
 ## Return schema
 
 The return contract is

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/deliver-light.js

@@ -24,7 +24,10 @@
  *     `proceed-light` it authors the receipt Story (via the plan-persist
  *     `createStoryIssues` surface) and prints the init/close hand-off. On
  *     over-scope it prints `ask-operator` (attended) or emits an `escalated`
- *     terminal envelope (`--yes`), never landing silently.
+ *     terminal envelope (`--yes`), never landing silently. An attended
+ *     `ask-operator` is answerable **either** way: `--operator-proceed-light`
+ *     records the operator's proceed answer (Story #4815), which the gate
+ *     applies only to a coarse size prediction and never to a risk rule.
  *   - **backstop** (`--backstop --story <id>`) — re-check the ACTUAL diff of
  *     the Story branch after implementation; exit non-zero when it exceeds the
  *     light ceilings, so an over-scope diff is blocked rather than landed.
@@ -81,7 +84,7 @@ Usage:
   deliver-light.js --prompt <text> [--creates csv] [--refactors csv]
                    [--acceptance n] [--kinds csv] [--magnitude m]
                    [--uncertainty u] [--route lite|full] [--reason <text>]
-                   [--amends '#id'] [--yes]
+                   [--amends '#id'] [--operator-proceed-light <text>] [--yes]
   deliver-light.js --backstop --story <id>
 
 The thin /deliver-light entry point: suitability gate → inline receipt Story →
@@ -105,6 +108,15 @@ Gate options:
   --route <r>        Ledgered model verdict route: lite | full.
   --reason <text>    Recorded reason for a lite verdict (required for lite).
   --amends <#id>     Mark this as an amendment of an existing issue.
+  --operator-proceed-light <text>
+                     Record the operator's "proceed light" answer to an
+                     ask-operator gate, with their reason. Attended-only:
+                     refused with --yes. Waives a coarse SIZE prediction
+                     (change kinds, magnitude, uncertainty, deployable span)
+                     only — sensitivity, migration span, and an unknown
+                     footprint stay non-negotiable, the ledgered --route lite
+                     verdict is still required, and the --backstop pass still
+                     bounds the actual diff. Recorded in the receipt Story.
   --yes              Unattended: over-scope emits an escalated terminal
                      envelope and ENDS the session (no prompt, no fallback).
 
@@ -182,11 +194,14 @@ export function synthesizeAcceptance(count) {
  *   uncertainty?: string,
  *   route?: string,
  *   reason?: string,
+ *   operatorProceedLight?: string,
  *   yes?: boolean,
  *   injectedRules?: object,
  * }} args `kinds` / `magnitude` / `uncertainty` are the declared effort-and-risk
  *   axes the gate judges (Story #4764); omitting them declares no signal, not a
- *   small one — an unrecognized bucket fails closed.
+ *   small one — an unrecognized bucket fails closed. `operatorProceedLight`
+ *   carries the operator's recorded answer to an `ask-operator` outcome
+ *   (Story #4815) and is adjudicated inside the gate, never applied here.
  * @returns {{ action: string, suitability: object, outcome: object }}
  */
 export function runLightGate({
@@ -198,6 +213,7 @@ export function runLightGate({
   uncertainty,
   route,
   reason,
+  operatorProceedLight,
   yes = false,
   injectedRules,
 } = {}) {
@@ -211,7 +227,11 @@ export function runLightGate({
     verdict: { route, reason },
     injectedRules,
   });
-  const outcome = resolveLightGateOutcome({ suitability, yes });
+  const outcome = resolveLightGateOutcome({
+    suitability,
+    yes,
+    operatorOverride: operatorProceedLight,
+  });
   return { action: outcome.action, suitability, outcome };
 }
 
@@ -224,9 +244,11 @@ export function runLightGate({
  *   prompt: string,
  *   changedFiles?: string[],
  *   amends?: string|number|null,
+ *   override?: object|null,
  *   assembleFn?: typeof assemblePlanStories,
  *   createFn?: typeof createStoryIssues,
- * }} args
+ * }} args `override` is the applied operator scope override (Story #4815),
+ *   recorded in the receipt body so the decision is auditable from the ticket.
  * @returns {Promise<{ storyId: number, url: string|undefined, title: string }>}
  */
 export async function createLightReceipt({
@@ -234,10 +256,16 @@ export async function createLightReceipt({
   prompt,
   changedFiles = [],
   amends = null,
+  override = null,
   assembleFn = assemblePlanStories,
   createFn = createStoryIssues,
 } = {}) {
-  const ticket = buildReceiptStoryTicket({ prompt, changedFiles, amends });
+  const ticket = buildReceiptStoryTicket({
+    prompt,
+    changedFiles,
+    amends,
+    override,
+  });
   const { stories } = assembleFn([ticket]);
   const { created } = await createFn({ provider, stories });
   const receipt = created[0];
@@ -291,6 +319,19 @@ export function runDiffBackstop({
   return checkLightDiffBackstop({ changedFiles: files, injectedRules });
 }
 
+/**
+ * Was a non-blank `--operator-proceed-light` supplied? The gate core decides
+ * whether it *applies*; this only asks whether the operator typed one, so the
+ * attended-only refusal can fire before any adjudication.
+ *
+ * @param {{ 'operator-proceed-light'?: unknown }} values Parsed CLI values.
+ * @returns {boolean}
+ */
+export function hasOperatorOverride(values = {}) {
+  const raw = values['operator-proceed-light'];
+  return typeof raw === 'string' && raw.trim() !== '';
+}
+
 /**
  * Emit a JSON envelope on stdout (the machine surface) so a headless caller can
  * branch on it. Human-readable log lines stay on stderr.
@@ -341,8 +382,10 @@ async function runBackstopMode(values) {
  *     control flow rather than a claim the envelope makes about itself.
  *   - **`ask-operator`** is unchanged: the plain gate envelope and exit 2. It
  *     is not terminal — the operator has a choice to make, and manufacturing a
- *     terminal for it would end a session that is supposed to be waiting.
- *   - **`proceed-light`** authors the receipt Story and prints the hand-off.
+ *     terminal for it would end a session that is supposed to be waiting. The
+ *     operator's proceed answer comes back as `--operator-proceed-light`.
+ *   - **`proceed-light`** authors the receipt Story and prints the hand-off,
+ *     carrying any applied `override` into both the receipt and the envelope.
  *
  * The injectable seams exist so the no-side-effect guarantee is testable
  * without a network: a test asserts the escalate path never reaches them.
@@ -371,6 +414,17 @@ export async function runGateMode(values, deps = {}) {
     throw new Error('[deliver-light] --prompt <text> is required for the gate');
   }
 
+  // Attended-only, enforced loudly (Story #4815). Silently ignoring the flag
+  // under --yes would let an automated caller pass it as a hopeful no-op and
+  // read the resulting escalation as a bug; a usage error says which of the
+  // two the caller has to give up.
+  if (values.yes === true && hasOperatorOverride(values)) {
+    process.stderr.write(HELP);
+    throw new Error(
+      '[deliver-light] --operator-proceed-light is attended-only and cannot be combined with --yes: an unattended run has no operator whose answer this is, and over-scope must fail closed to /plan',
+    );
+  }
+
   const gate = runLightGate({
     creates: parseCsvPaths(values.creates),
     refactors: parseCsvPaths(values.refactors),
@@ -382,6 +436,7 @@ export async function runGateMode(values, deps = {}) {
     uncertainty: values.uncertainty,
     route: values.route,
     reason: values.reason,
+    operatorProceedLight: values['operator-proceed-light'],
     yes: values.yes === true,
   });
 
@@ -408,6 +463,7 @@ export async function runGateMode(values, deps = {}) {
     return EXIT_NOT_PROCEED;
   }
 
+  const override = gate.outcome.override ?? null;
   const provider = createProviderFn(resolveConfigFn());
   const receipt = await createReceiptFn({
     provider,
@@ -417,6 +473,7 @@ export async function runGateMode(values, deps = {}) {
       ...parseCsvPaths(values.refactors),
     ],
     amends: values.amends ?? null,
+    override,
   });
   emitFn(
     {
@@ -424,11 +481,17 @@ export async function runGateMode(values, deps = {}) {
       action: 'proceed-light',
       storyId: receipt.storyId,
       url: receipt.url,
+      ...(override === null ? {} : { override }),
       nextCommands: buildNextCommands(receipt.storyId),
       outcome: gate.outcome,
     },
     values.pretty,
   );
+  if (override !== null) {
+    Logger.warn(
+      `[deliver-light] operator scope override recorded on Story #${receipt.storyId}: waived "${override.overriddenCode}" — ${override.recordedReason}`,
+    );
+  }
   Logger.info(
     `[deliver-light] receipt Story #${receipt.storyId} created — hand off to single-story-init.js.`,
   );
@@ -448,6 +511,7 @@ async function main() {
       route: { type: 'string' },
       reason: { type: 'string' },
       amends: { type: 'string' },
+      'operator-proceed-light': { type: 'string' },
       yes: { type: 'boolean', default: false },
       backstop: { type: 'boolean', default: false },
       story: { type: 'string' },

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':