mandrel 2.20.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/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/config/temp-paths.js

@@ -312,6 +312,68 @@ export function orchestrationLogDir(config) {
   return path.join(anchorTempRoot(tempRootFrom(config)), ORCHESTRATION_DIRNAME);
 }
 
+/**
+ * Basename of one Story's close gate log (Story #4816 lifted it here from
+ * `single-story-close/gate-log.js`).
+ *
+ * The writer that appends this file and the reader that uses its **freshness**
+ * to tell a live close from a dead one (`deliver-recover.js`) sit in different
+ * subtrees, and the reader importing the writer is the wrong edge to draw for
+ * a filename. Both take it from the module that already owns every other
+ * tempRoot path instead.
+ *
+ * `null` is the sink's no-Story sentinel and keeps its `unknown` spelling.
+ *
+ * @param {number|null} sid
+ * @returns {string}
+ */
+function closeGateLogName(sid) {
+  return `close-gates-${sid ?? 'unknown'}.log`;
+}
+
+/**
+ * `<tempRoot>/orchestration/close-gates-<sid>.log`.
+ *
+ * @param {number|null} sid
+ * @param {object} [config]
+ * @returns {string}
+ */
+export function closeGateLogPath(sid, config) {
+  return path.join(orchestrationLogDir(config), closeGateLogName(sid));
+}
+
+/**
+ * Basename of the persisted terminal envelope for one Story (Story #4816).
+ *
+ * @param {number} sid
+ * @returns {string}
+ */
+function storyTerminalEnvelopeName(sid) {
+  return `story-deliver-terminal-${storyId(sid)}.json`;
+}
+
+/**
+ * `<tempRoot>/orchestration/story-deliver-terminal-<sid>.json` — the on-disk
+ * copy of the one terminal envelope a Story's close-and-land emits (Story
+ * #4816).
+ *
+ * Deliberately a sibling of the gate log rather than a per-Story temp dir
+ * entry: the envelope is a run artifact of the same close that writes
+ * `close-gates-<sid>.log`, and `deliver-recover.js` reads the pair together to
+ * tell a finished close from a live one. Sharing `orchestrationLogDir` also
+ * means it inherits main-checkout anchoring for free — the close runs inside
+ * `.worktrees/story-<sid>/` while the `/deliver` host reads from the main
+ * checkout, and an un-anchored path would put the envelope somewhere the
+ * router never looks.
+ *
+ * @param {number} sid
+ * @param {object} [config]
+ * @returns {string}
+ */
+export function storyTerminalEnvelopePath(sid, config) {
+  return path.join(orchestrationLogDir(config), storyTerminalEnvelopeName(sid));
+}
+
 const runId = (id) => {
   if (!Number.isInteger(id) || id <= 0) {
     throw new Error(`[temp-paths] runId must be a positive integer; got ${id}`);

package/.agents/scripts/lib/orchestration/complexity-gate.js

@@ -259,23 +259,65 @@ function spansMigrationAndConsumers(paths) {
   return migrations.length > 0 && migrations.length < paths.length;
 }
 
+/**
+ * Stable machine-readable identifiers for every reason a shape routes `full` —
+ * the `code` field on a {@link deriveStoryShape} decision (Story #4815).
+ *
+ * The prose in `reasons[]` is written for a human reading a gate envelope and
+ * is free to be re-worded; a caller that must **branch** on *which* rule
+ * objected reads this code instead. That distinction is load-bearing for the
+ * light path's operator override
+ * ({@link module:lib/orchestration/light-suitability.OVERRIDABLE_SHAPE_CODES}),
+ * which may waive a size *prediction* but never a risk rule: keying that
+ * decision off reason text would make a copy-edit a security change.
+ *
+ * Split three ways, and the grouping is the contract:
+ *
+ *   - **Ceiling rules** — `change-kinds`, `magnitude`, `uncertainty`,
+ *     `deployable-span`. Coarse predictions about size, enforced for real
+ *     against ground truth by the diff backstop.
+ *   - **Absolute rules** — `migration-span`, `sensitive-path`. Risk, not size.
+ *   - **Unknown-footprint rejections** — `no-changes`, `unreadable-changes`,
+ *     `glob-footprint`, `no-acceptance`, `classification-unavailable`,
+ *     `unparseable-body`. Nothing was judged, so there is nothing to waive.
+ *
+ * A `lite` route carries `code: null`.
+ */
+export const SHAPE_CODES = Object.freeze({
+  CHANGE_KINDS: 'change-kinds',
+  MAGNITUDE: 'magnitude',
+  UNCERTAINTY: 'uncertainty',
+  DEPLOYABLE_SPAN: 'deployable-span',
+  MIGRATION_SPAN: 'migration-span',
+  SENSITIVE_PATH: 'sensitive-path',
+  NO_CHANGES: 'no-changes',
+  UNREADABLE_CHANGES: 'unreadable-changes',
+  GLOB_FOOTPRINT: 'glob-footprint',
+  NO_ACCEPTANCE: 'no-acceptance',
+  CLASSIFICATION_UNAVAILABLE: 'classification-unavailable',
+  UNPARSEABLE_BODY: 'unparseable-body',
+});
+
 /**
  * Ordered effort/risk rules, evaluated in order; the first hit is the recorded
  * reason for a `full` route. Every rule names an effort, risk, or uncertainty
  * property of the work — none counts artifacts.
  *
  * @type {ReadonlyArray<{
+ *   code: string,
  *   when: (shape: object, ceilings: typeof STORY_SHAPE_CEILINGS) => boolean,
  *   reason: (shape: object, ceilings: typeof STORY_SHAPE_CEILINGS) => string,
  * }>}
  */
 const EFFORT_RULES = Object.freeze([
   {
+    code: SHAPE_CODES.CHANGE_KINDS,
     when: (s, c) => s.kindCount > c.maxChangeKinds,
     reason: (s, c) =>
       `${s.kindCount} distinct change kinds (${s.changeKinds.join(', ')}) > maxChangeKinds ${c.maxChangeKinds} — an explicit multi-capability enumeration, not one capability; full route`,
   },
   {
+    code: SHAPE_CODES.MAGNITUDE,
     when: (s, c) =>
       MAGNITUDE_SCALE.indexOf(s.magnitude) >
       MAGNITUDE_SCALE.indexOf(c.maxMagnitude),
@@ -283,6 +325,7 @@ const EFFORT_RULES = Object.freeze([
       `declared magnitude "${s.magnitude}" > maxMagnitude "${c.maxMagnitude}" — a substantial rewrite is effort a single inline pass should not absorb, however few files it touches; full route`,
   },
   {
+    code: SHAPE_CODES.UNCERTAINTY,
     when: (s, c) =>
       UNCERTAINTY_SCALE.indexOf(s.uncertainty) >
       UNCERTAINTY_SCALE.indexOf(c.maxUncertainty),
@@ -290,16 +333,19 @@ const EFFORT_RULES = Object.freeze([
       `the shape is not determined by the request (uncertainty "${s.uncertainty}") — the design decisions /plan exists to resolve are still open; full route`,
   },
   {
+    code: SHAPE_CODES.DEPLOYABLE_SPAN,
     when: (s, c) => s.deployables.length > c.maxDeployables,
     reason: (s, c) =>
       `footprint spans ${s.deployables.length} deployables (${s.deployables.join(', ')}) > maxDeployables ${c.maxDeployables} — clearly-epic scope; full route`,
   },
   {
+    code: SHAPE_CODES.MIGRATION_SPAN,
     when: (s) => s.migrationSpan,
     reason: () =>
       'footprint pairs a migration with its consumers — clearly-epic scope; full route',
   },
   {
+    code: SHAPE_CODES.SENSITIVE_PATH,
     when: (s) => s.sensitiveClasses.length > 0,
     reason: (s) =>
       `footprint intersects sensitive-path class(es) ${s.sensitiveClasses.join(', ')} — sensitivity wins over a small shape; full route (fresh acceptance critic retained)`,
@@ -307,15 +353,18 @@ const EFFORT_RULES = Object.freeze([
 ]);
 
 /**
- * First effort/risk rule the shape violates, or `null` when it clears them all.
+ * First effort/risk rule the shape violates as a `{ code, reason }` pair, or
+ * `null` when it clears them all.
  *
  * @param {object} shape
  * @param {typeof STORY_SHAPE_CEILINGS} ceilings
- * @returns {string|null}
+ * @returns {{ code: string, reason: string }|null}
  */
 function firstEffortViolation(shape, ceilings) {
   for (const rule of EFFORT_RULES) {
-    if (rule.when(shape, ceilings)) return rule.reason(shape, ceilings);
+    if (rule.when(shape, ceilings)) {
+      return { code: rule.code, reason: rule.reason(shape, ceilings) };
+    }
   }
   return null;
 }
@@ -654,10 +703,13 @@ function buildEffortShape({
  * @returns {{
  *   route: ComplexityRoute,
  *   reasons: string[],
+ *   code: string|null,
  *   shape: ReturnType<typeof buildEffortShape>|null,
  *   ceilings: typeof STORY_SHAPE_CEILINGS,
  *   preserves: typeof LITE_PATH_INVARIANTS,
- * }}
+ * }} `code` is the stable {@link SHAPE_CODES} identifier for the rule that
+ *   rejected the shape (`null` on `lite`) — the field a caller branches on,
+ *   since `reasons[]` is human prose and free to be re-worded.
  */
 export function deriveStoryShape({
   changes,
@@ -670,9 +722,10 @@ export function deriveStoryShape({
 } = {}) {
   const ceilings = STORY_SHAPE_CEILINGS;
   const preserves = LITE_PATH_INVARIANTS;
-  const decide = (route, reason, shape = null) => ({
+  const decide = (route, code, reason, shape = null) => ({
     route,
     reasons: [reason],
+    code,
     shape,
     ceilings,
     preserves,
@@ -681,6 +734,7 @@ export function deriveStoryShape({
   if (!Array.isArray(changes) || changes.length === 0) {
     return decide(
       'full',
+      SHAPE_CODES.NO_CHANGES,
       'no changes[] declared — the footprint is unknown, so the work cannot be judged trivial; conservative full route',
     );
   }
@@ -691,6 +745,7 @@ export function deriveStoryShape({
   } catch (err) {
     return decide(
       'full',
+      SHAPE_CODES.UNREADABLE_CHANGES,
       `changes[] could not be read (${err?.message ?? err}) — unknown footprint; conservative full route`,
     );
   }
@@ -714,6 +769,7 @@ export function deriveStoryShape({
   if (entries.some((e) => e.isGlob)) {
     return decide(
       'full',
+      SHAPE_CODES.GLOB_FOOTPRINT,
       'changes[] contains a glob path — unknown footprint width; conservative full route',
       shape,
     );
@@ -721,13 +777,16 @@ export function deriveStoryShape({
   if (shape.acceptanceCount === 0) {
     return decide(
       'full',
+      SHAPE_CODES.NO_ACCEPTANCE,
       'no acceptance criteria — the contract cannot be judged trivial; conservative full route',
       shape,
     );
   }
 
   const violation = firstEffortViolation(shape, ceilings);
-  if (violation !== null) return decide('full', violation, shape);
+  if (violation !== null) {
+    return decide('full', violation.code, violation.reason, shape);
+  }
 
   if (level !== 'low') {
     // `deriveChangeLevel` degraded to its null fail-safe (unreadable
@@ -735,6 +794,7 @@ export function deriveStoryShape({
     // non-sensitive, and a classification failure must never buy lite.
     return decide(
       'full',
+      SHAPE_CODES.CLASSIFICATION_UNAVAILABLE,
       'sensitive-path classification unavailable — cannot verify the footprint is non-sensitive; conservative full route',
       shape,
     );
@@ -742,6 +802,7 @@ export function deriveStoryShape({
 
   return decide(
     'lite',
+    null,
     `trivial shape: ${shape.kindCount} change kind(s) (${shape.changeKinds.join(', ')}) ≤ ${ceilings.maxChangeKinds} across ${shape.siteCount} site(s), magnitude ${shape.magnitude} ≤ ${ceilings.maxMagnitude}, shape ${shape.uncertainty}, no epic-scope span, no sensitive-path class — inline-eligible; non-negotiables preserved`,
     shape,
   );
@@ -771,6 +832,7 @@ function deriveStoryRouteFromBody(body, opts = {}) {
       reasons: [
         `Story body is unparseable (${err?.message ?? err}) — shape unknown; conservative full route`,
       ],
+      code: SHAPE_CODES.UNPARSEABLE_BODY,
       shape: null,
       ceilings: STORY_SHAPE_CEILINGS,
       preserves: LITE_PATH_INVARIANTS,