mandrel 2.20.0 → 2.22.0

package/.agents/README.md

@@ -325,7 +325,7 @@ persists Stories with inline `acceptance[]` / `verify[]` and a folded
 `main`. There is no `type::epic` / `type::task` label, Epic issue form, or
 `epic/<id>` integration branch; a ticket carrying an `Epic: #N` footer is
 refused by `/deliver`. The execution-model contract is owned by
-[`instructions.md` § 5.D](instructions.md) and [`docs/SDLC.md`](docs/SDLC.md).
+[`instructions.md` § 5.B](instructions.md) and [`docs/SDLC.md`](docs/SDLC.md).
 
 ---
 

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

@@ -102,6 +102,11 @@ close pipeline is the authoritative gate. The acceptance self-eval loop may
 share `lint` / `typecheck` evidence with close via `evidence-gate.js`;
 never stamp coverage / CRAP fresh that way.
 
+Before trusting a gate's output — or diagnosing a red one — read
+[`known-tooling-behavior.md`](../rules/known-tooling-behavior.md): measured
+cases where a command prints what it does not mean (lint exits 1 under a
+`0 error(s)` summary; a green `check-baselines.js` is not `baselines`).
+
 ## Acceptance self-eval before close (MUST)
 
 After the implementation commits land and **before** flipping to `closing`,
@@ -134,6 +139,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/instructions.md

@@ -14,10 +14,10 @@ and is read when the task engages it.
 ### A. Role Framing
 
 No persona packs, no `persona::*` labels — constraints come from this
-file, the rules, and skills. Role-scoped spawn contexts live under
+file, the rules, and skills; "act as [role]" means apply the matching
+skill or workflow guidance. Role-scoped spawn contexts live under
 `.agents/agents/` (`delivery.routing.roleScopedAgents`); `qa.personas`
-are a separate fixture concept. "Act as [role]" = apply the matching
-skill / workflow guidance.
+is a separate fixture concept.
 
 ### B. Skill Activation
 
@@ -32,11 +32,11 @@ Unsure? Match against the `description`s in
 
 ### C. Proactive Documentation
 
-For any code involving third-party libraries, fetch the latest official
-docs **before** writing code via the host's best live-documentation
-mechanism (docs MCP server, IDE lookup) — do not ask permission.
-Fallbacks: (1) in-repo docs and the package's bundled README/CHANGELOG,
-(2) web fetch/search. Note the channel you used.
+Before writing against a third-party API you are unsure of — or one
+that moves fast enough that recall may be stale — fetch the current
+official docs via the host's best live-documentation mechanism (docs
+MCP server, IDE lookup); do not ask permission. Fallbacks: (1) in-repo
+docs and the package's bundled README/CHANGELOG, (2) web fetch/search.
 
 ### D. Error Handling & Degradation
 
@@ -64,7 +64,8 @@ read **before** the matching work (each opens with a one-line "applies
 when…" scope header): `git-conventions-reference.md`,
 `shell-conventions.md`, `testing-standards.md`,
 `orchestration-error-handling.md` (scripts under `.agents/scripts/**`),
-`ci-remediation.md`, `api-conventions.md`, `gherkin-standards.md`,
+`ci-remediation.md`, `known-tooling-behavior.md`,
+`api-conventions.md`, `gherkin-standards.md`,
 `changelog-style.md`, `test-seams.md`. Read when unsure (on-demand
 loading does not lower a rule's authority — § 1.K).
 
@@ -138,8 +139,6 @@ sizing) **fail closed** naming what to trim:
 3. **Artifacts over Chat.** Write test/build/debug output to log
    files, not into chat.
 4. **Idempotency.** Scripts must be safe to run repeatedly.
-5. **Security First.** Never hardcode secrets; use environment variables
-   and secret scanning.
 
 ---
 
@@ -151,11 +150,9 @@ sizing) **fail closed** naming what to trim:
   spawn only when the work justifies replicating context. One objective
   per subagent; depth compounds the cost (every nested level re-pays).
 - **Anti-Laziness / No Dead Code.** NEVER use placeholder comments like
-  `// ... existing code ...` — output the ENTIRE file or complete
-  function; remove unused imports, commented-out code, and dead branches
+  `// ... existing code ...`; every edit must leave complete, runnable
+  code. Remove unused imports, commented-out code, and dead branches
   before finalizing.
-- **Lint Compliance.** Adhere strictly to project linters and
-  formatters.
 - **Verification.** Include explicit verification steps in every plan.
 
 ---
@@ -167,7 +164,7 @@ reference: `story-<storyId>` branches seeded by `single-story-init.js`,
 every Story reaching `main` via its own PR
 (`helpers/deliver-story` / `single-story-close.js`).
 
-### B. Status Tracking & Commit Standards
+### A. Status Tracking & Commit Standards
 
 State mutations are GitHub labels (`agent::ready`, `agent::executing`,
 `agent::done`) via
@@ -175,7 +172,7 @@ State mutations are GitHub labels (`agent::ready`, `agent::executing`,
 Do NOT manually update issue descriptions or status fields unless
 prompted.
 
-### D. Ticket hierarchy (Story-only)
+### B. Ticket hierarchy (Story-only)
 
 The v2 ticket model is Story-only: `acceptance[]` / `verify[]` live
 inline plus the folded Tech Spec in `## Spec` (over-budget Specs fail

package/.agents/rules/git-conventions.md

@@ -19,7 +19,7 @@ commit on that branch only. Close opens a PR against `main` (squash +
 required checks). No `epic/<id>` integration branch, no `--no-ff` wave
 merge, no child tickets: commits land on `story-<storyId>` directly, the
 subject referencing the Story via `(refs #<storyId>)` — see
-[`.agents/instructions.md` § 5.D](../instructions.md).
+[`.agents/instructions.md` § 5.B](../instructions.md).
 
 ## Conventional Commits
 

package/.agents/rules/known-tooling-behavior.md

@@ -0,0 +1,114 @@
+# Known Tooling Behavior
+
+This rule applies when you are about to trust the output of a gate, a
+baseline ratchet, or a local stand-in for a CI check — before pushing,
+before declaring a check green, and before diagnosing a red one.
+
+Each entry below records a **measured** behavior of this repository's own
+tooling: a place where a command's visible output does not mean what it
+looks like it means. Entries exist because each one has already cost a
+delivery cycle.
+
+## The entry bar
+
+- An entry states behavior that was **measured against this repo**, never
+  recalled and never assumed.
+- Every entry carries a **reproduction command** that was actually run. If
+  the command stops reproducing the behavior, **delete the entry** — do not
+  annotate it. A stale entry is worse than a missing one, because it is
+  trusted.
+- Entries describe the observable behavior and the safe move. They never
+  describe a way to bypass a gate, and recording a behavior here is not a
+  decision to keep it.
+
+## 1. `npm run lint` prints `Summary: 0 error(s)` and can still exit 1
+
+**Behavior.** `npm run lint` is `run-lint.js`, which spawns six tools
+concurrently with inherited stdio and exits with the first non-zero code.
+`Summary: 0 error(s)` is **markdownlint-cli2's own verdict**, not the
+aggregate — it is printed whether or not Biome, the lifecycle lint, the
+workflow-CLI lint, the label-vocabulary lint, or the arch-cycle ratchet
+failed. Because the tools run in parallel, that line can land anywhere in
+the output, including last, so the tail of a failing run reads green.
+Biome's format diagnostics are `error`-severity, so a file that only needs
+reformatting fails the check while emitting no lint rule name at all.
+
+**Reproduce.**
+
+```bash
+# a format-only diff is an error, not a warning
+printf 'export const x = {a:1,   b:2};\n' | npx biome check --stdin-file-path=probe.js
+echo "biome exit=$?"   # 1 — "The contents aren't fixed"
+
+# and markdownlint's Summary line is unconditional
+npm run lint 2>&1 | grep -c 'Summary: 0 error(s)'
+```
+
+**Safe move.** Trust the exit code, never the last line. When `npm run lint`
+exits non-zero and you cannot see why, re-run `npx biome ci .` on its own —
+`.agents/scripts/run-lint.js` lists every tool it fans out to. Fix formatting
+with `npm run format`; never reach for `--no-verify`.
+
+## 2. `check-baselines.js` is not the whole `baselines` check
+
+**Behavior.** `.agentrc.json` declares the `baselines` required check as
+`node .agents/scripts/check-baselines.js`, but that script only runs the
+gates configured under `delivery.quality.gates` — currently **crap,
+maintainability, and duplication**. CI's job named `baselines` in
+`.github/workflows/ci.yml` runs that script **and then five standalone
+ratchets** the script knows nothing about, so a locally green
+`check-baselines.js` is not evidence that the `baselines` check will pass.
+
+| Ratchet CI's `baselines` job runs | Covered by `check-baselines.js` | Covered by `npm run lint` | Covered by `npm run verify` |
+| --- | --- | --- | --- |
+| `.agents/scripts/check-arch-cycles.js` | no | **yes** | via `lint` |
+| `.agents/scripts/check-dead-exports.js` | no | no | **yes** |
+| `.agents/scripts/check-dead-exports.js --production` | no | no | **yes** |
+| `.agents/scripts/check-context-budget.js` | no | no | **yes** |
+| `.agents/scripts/check-workflow-citations.js` | no | no | **no** |
+
+`check-workflow-citations.js` is currently in **no** local aggregate command
+— it is reachable only as `npm run check:workflow-citations` or a direct
+invocation.
+
+**Reproduce.**
+
+```bash
+node .agents/scripts/check-baselines.js --format text   # names the 3 gates it ran
+sed -n '/name: baselines/,/windows-smoke/p' .github/workflows/ci.yml | grep 'check-'
+grep "label: '" .agents/scripts/run-verify.js            # the 7 steps verify covers
+```
+
+**Safe move.** `npm run verify` is the closest local mirror; run
+`node .agents/scripts/check-workflow-citations.js` alongside it when the
+change touches workflow prose under `.agents/workflows/`. Reproducing only
+the `.agentrc.json` command before a push is a false green.
+
+## 3. The two dead-export passes disagree, and the production pass is silent without `!`
+
+**Behavior.** `check-dead-exports.js` runs twice with two separate
+baselines. The default pass treats `tests/**` as knip entry points, so an
+export whose only importer is a test still reads as *used*; the
+`--production` pass discounts test importers and therefore sees a much
+larger surface — `baselines/dead-exports.json` carries 165 rows against
+`baselines/dead-exports-production.json`'s 667. A new export that is only
+imported by its test passes the default pass and fails the production one.
+
+The production pass depends entirely on the `!` suffix on the `entry` and
+`project` patterns in `knip.json`: `!` marks a pattern as
+production-relevant. Strip the suffixes and `knip --production` reports
+**zero** export rows and exits clean — a green that means "nothing was
+analyzed", not "nothing is dead".
+
+**Reproduce.**
+
+```bash
+node .agents/scripts/check-dead-exports.js              # default pass
+node .agents/scripts/check-dead-exports.js --production # strictly larger row set
+grep -c '!"' knip.json                                  # the production markers
+```
+
+**Safe move.** Run both passes before pushing. When an export is genuinely
+test-only, keep it and refresh the production baseline deliberately —
+`.agents/rules/test-seams.md` governs which seams are sanctioned. Never
+remove the `!` suffixes from `knip.json` to quieten the production pass.

package/.agents/scripts/check-context-budget.js

@@ -25,6 +25,21 @@
  * ratchet — each role def is a standalone system prompt a converted spawn boots
  * on, and adding another role def is legitimate.
  *
+ * The recorded `agentBoot` rows are additionally held **in sync with the tree**
+ * (Story #4830), because those rows are what an author sizes an edit against.
+ * The two drift directions are deliberately asymmetric:
+ *
+ *   - **permissive** (the row understates the file, or no row exists) — the row
+ *     promises headroom that does not exist, the gate stays green, and the
+ *     shortfall only lands as a ceiling failure once the edit is written. This
+ *     fails the gate.
+ *   - **restrictive** (the row overstates the file) — an author under-spends
+ *     and the ceiling is never surprised, so it is self-correcting. Reported as
+ *     a `-` line; exit stays 0.
+ *
+ * Each row also records its `headroomBytes` under the ceiling, so the budget an
+ * author reads is stated rather than re-derived.
+ *
  * A read-tier that resolves **empty** is skipped silently (the `docsContextFiles`
  * half skips when unconfigured / its files are absent), so a repo with no
  * `CLAUDE.md` and no context docs is a clean no-op.
@@ -98,6 +113,100 @@ export function agentBootOverflow(tierMap, ceiling = AGENT_BOOT_CEILING_BYTES) {
     .map((f) => ({ path: f.path, bytes: f.bytes, ceiling }));
 }
 
+/**
+ * Classify one agent-boot file against its recorded baseline row (#4830).
+ * Returns `null` when the row already agrees with the tree.
+ *
+ * `permissive` drift is the failure class this gate exists for: the row
+ * understates the file (or is missing entirely), so the headroom an author
+ * computes from it is larger than the headroom that exists, and the shortfall
+ * only surfaces as a ceiling failure *after* the edit is written.
+ * `restrictive` drift is the benign mirror — the row overstates the file, so an
+ * author under-spends and the ceiling gate is never surprised.
+ *
+ * @param {{ path: string, bytes: number }} file live file measurement
+ * @param {{ bytes?: number, headroomBytes?: number } | undefined} row recorded row
+ * @param {number} ceiling
+ * @returns {{ path: string, recorded: number|null, actual: number, delta: number,
+ *   direction: 'permissive'|'restrictive', recordedHeadroom: number|null,
+ *   headroomBytes: number } | null}
+ */
+function classifyBootRow(file, row, ceiling) {
+  const actual = file.bytes;
+  const headroomBytes = ceiling - actual;
+  const recorded = Number.isFinite(row?.bytes) ? row.bytes : null;
+  const recordedHeadroom = Number.isFinite(row?.headroomBytes)
+    ? row.headroomBytes
+    : recorded === null
+      ? null
+      : ceiling - recorded;
+  // A row is in sync only when both the byte count and the headroom it
+  // advertises match the tree — a stale headroom misleads on its own.
+  if (recorded === actual && recordedHeadroom === headroomBytes) return null;
+  const permissive =
+    recorded === null ||
+    recorded < actual ||
+    (recordedHeadroom !== null && recordedHeadroom > headroomBytes);
+  return {
+    path: file.path,
+    recorded,
+    actual,
+    delta: recorded === null ? actual : actual - recorded,
+    direction: permissive ? 'permissive' : 'restrictive',
+    recordedHeadroom,
+    headroomBytes,
+  };
+}
+
+/**
+ * Compare every recorded `agentBoot` row against the tree it describes.
+ *
+ * @param {{ tiers: Record<string, Array<{ path: string, bytes: number }>> }} tierMap
+ * @param {{ agentBoot?: { ceilingBytes?: number, files?: Array<{ path: string, bytes: number, headroomBytes?: number }> } } | null} baseline
+ * @param {number} [ceiling]
+ * @returns {Array<ReturnType<typeof classifyBootRow>>} drift rows (empty = in sync)
+ */
+export function agentBootDrift(tierMap, baseline, ceiling) {
+  const recordedCeiling = Number.isFinite(baseline?.agentBoot?.ceilingBytes)
+    ? baseline.agentBoot.ceilingBytes
+    : AGENT_BOOT_CEILING_BYTES;
+  const effective = Number.isFinite(ceiling) ? ceiling : recordedCeiling;
+  const rows = new Map(
+    (baseline?.agentBoot?.files ?? []).map((f) => [f.path, f]),
+  );
+  const drift = [];
+  for (const file of tierMap?.tiers?.agentBoot ?? []) {
+    if (!Number.isFinite(file?.bytes)) continue;
+    const row = classifyBootRow(file, rows.get(file.path), effective);
+    if (row) drift.push(row);
+  }
+  return drift;
+}
+
+/**
+ * Render the agent-boot drift lines. `+` lines are permissive drift (gate
+ * fail); `-` lines are restrictive drift (informational). Each line states the
+ * **real** remaining headroom, so the author sizing the next edit reads the
+ * true number rather than re-deriving it from a row that just proved stale.
+ *
+ * @param {Array<ReturnType<typeof classifyBootRow>>} drift
+ * @returns {string[]}
+ */
+export function renderBootDrift(drift) {
+  return drift.map((d) => {
+    const marker = d.direction === 'permissive' ? '+' : '-';
+    const recorded =
+      d.recorded === null
+        ? 'has no recorded row'
+        : `records ${d.recorded} bytes but the file is ${d.actual}`;
+    const note =
+      d.direction === 'permissive'
+        ? 'the row overstates the headroom an author would size an edit against'
+        : 'the row is conservative — refresh at leisure';
+    return `${marker} agentBoot drift: ${d.path} ${recorded} — ${note} (real headroom ${d.headroomBytes})`;
+  });
+}
+
 /**
  * Parse argv for `--baseline <path>`, `--root <path>`, `--update`, `--json`.
  * Exported so unit tests can pin the parser.
@@ -168,7 +277,14 @@ export function buildBaseline(tierMap, toleranceBytes) {
   // The agent-boot tier is recorded top-level (not under `tiers`) because it is
   // gated by a per-file ceiling, not the total-byte ratchet the `tiers` entries
   // use — keeping it out of `tiers` keeps the ratchet diff loop unambiguous.
-  const agentBootFiles = tierMap.tiers.agentBoot ?? [];
+  // Each row carries the headroom it leaves under the ceiling, so an author
+  // sizing an edit reads the remaining budget straight off the row (#4830)
+  // instead of re-deriving it — and `agentBootDrift` keeps both numbers honest.
+  const agentBootFiles = (tierMap.tiers.agentBoot ?? []).map((f) => ({
+    path: f.path,
+    bytes: f.bytes,
+    headroomBytes: AGENT_BOOT_CEILING_BYTES - f.bytes,
+  }));
   return {
     $schema: 'https://mandrel.dev/baselines/context-budget.schema.json',
     generatedAt: new Date().toISOString(),
@@ -353,7 +469,14 @@ export async function runCli({
     ? baseline.agentBoot.ceilingBytes
     : AGENT_BOOT_CEILING_BYTES;
   const bootOverflow = agentBootOverflow(tierMap, ceiling);
-  const exitCode = diff.grown.length > 0 || bootOverflow.length > 0 ? 1 : 0;
+  const bootDrift = agentBootDrift(tierMap, baseline, ceiling);
+  const permissiveDrift = bootDrift.filter((d) => d.direction === 'permissive');
+  const exitCode =
+    diff.grown.length > 0 ||
+    bootOverflow.length > 0 ||
+    permissiveDrift.length > 0
+      ? 1
+      : 0;
 
   if (json) {
     const envelope = {
@@ -370,6 +493,7 @@ export async function runCli({
       skipped: diff.skipped,
       agentBootCeilingBytes: ceiling,
       agentBootOverflow: bootOverflow,
+      agentBootDrift: bootDrift,
       workflowReachableBytes: tierMap.workflowClosure?.reachableTotalBytes ?? 0,
       exitCode,
     };
@@ -384,7 +508,15 @@ export async function runCli({
         `+ agentBoot: ${o.path} is ${o.bytes} bytes, over the ${o.ceiling}-byte per-agent ceiling\n`,
       );
     }
+    for (const line of renderBootDrift(bootDrift)) {
+      stdout.write(`${line}\n`);
+    }
     if (exitCode === 1) {
+      if (permissiveDrift.length > 0) {
+        stderr.write(
+          `[context-budget] ❌ a recorded agentBoot row understates the file it describes, so it overstates the headroom an author would size an edit against — refresh it with \`node .agents/scripts/check-context-budget.js --update\` (the ceiling is unchanged)\n`,
+        );
+      }
       if (bootOverflow.length > 0) {
         stderr.write(
           `[context-budget] ❌ a role-agent boot context exceeds the ${ceiling}-byte per-agent ceiling — trim the role def (the ceiling is a hard cap, not a starve target)\n`,

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' },