mandrel 2.8.0 → 2.10.0

package/.agents/scripts/lib/observability/metrics-ledger.js

@@ -0,0 +1,217 @@
+/**
+ * metrics-ledger.js — the narrow shared metrics-ledger boundary (Story #4712).
+ *
+ * Owns the one append-tail implementation for the plan-metrics ledger:
+ * path resolution, serialization, lazy directory creation, size-capped
+ * rotation, and the append itself. Every ledger writer — the plan-domain
+ * appenders in `../orchestration/plan-metrics.js` and the close-domain
+ * findings-yield entry point below — routes through
+ * {@link appendLedgerRecord}, so the open→append→rotate→close tail exists
+ * exactly once and cannot drift between call sites.
+ *
+ * The findings-yield entry point (Story #4699) lives here rather than in
+ * the plan-domain module so the story-close review spine
+ * (`../orchestration/story-close/phases/review-core.js`) depends on this
+ * narrow shared ledger module instead of plan-domain internals.
+ *
+ * Wire contract (unchanged by the #4712 re-home): record shapes, file
+ * locations (`temp/run-<id>/plan-metrics.json` / the standalone stream),
+ * and the rotation threshold are exactly what `plan-metrics.js` shipped —
+ * readers (`readPlanMetrics` / `summarizePlanMetrics`) stay plan-side and
+ * key kinded records on `kind`, never on absent fields.
+ *
+ * Robustness contract (mirrors `signals-writer.js`):
+ *   - **No buffering.** Each append opens, writes one line, closes.
+ *   - **Rotation.** When an append would push the ledger past
+ *     `maxBytes`, the current file is renamed to `<name>.1` (replacing any
+ *     prior rollover) and the append starts a fresh ledger.
+ *   - **Best-effort at the entry points.** {@link appendLedgerRecord}
+ *     itself throws on fs failure; each public appender catches, warns via
+ *     `Logger`, and returns `false` so metric capture can never fail the
+ *     wrapped plan phase or Story close.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  anchorTempRoot,
+  runArtifactPath,
+  tempRootFrom,
+} from '../config/temp-paths.js';
+import { Logger } from '../Logger.js';
+
+export const PLAN_METRICS_BASENAME = 'plan-metrics.json';
+export const PLAN_METRICS_SCHEMA_VERSION = 1;
+
+/**
+ * Record kind for a per-close, per-lens findings-yield entry (Story #4699).
+ * One record per Story close whose review ran (or floor-skipped) at least
+ * one local lens:
+ *
+ * ```json
+ * { "v": 1, "kind": "findings-yield", "cli": "story-close-review",
+ *   "storyId": 4699, "epicId": null,
+ *   "lenses": [{ "lens": "audit-clean-code", "findings": 0,
+ *                "skippedByFloor": false }],
+ *   "diffFloor": { "skip": false, "reason": "at-or-above-floor",
+ *                  "floor": 40, "changedLineCount": 120 },
+ *   "at": "..." }
+ * ```
+ *
+ * The ledger only records — no roster behavior changes ride on it. Its
+ * purpose is evidentiary: a lens that stays at zero findings across N
+ * closes becomes droppable on measurement instead of assumption.
+ */
+const PLAN_METRICS_KIND_FINDINGS_YIELD = 'findings-yield';
+
+/**
+ * Rotation threshold. At ~200 bytes per record this is ~5000 invocations —
+ * far beyond any real plan run, so rotation only fires on pathological
+ * accumulation.
+ */
+export const MAX_LEDGER_BYTES = 1024 * 1024;
+
+/**
+ * Resolve the ledger path for an Epic (or the standalone stream when
+ * `epicId` is `null` — the `story-plan.js` / Epic-less healthcheck case).
+ *
+ * @param {number|null} epicId
+ * @param {object} [config] Resolved config (threads `project.paths.tempRoot`).
+ * @returns {string}
+ */
+export function planMetricsPath(epicId, config) {
+  if (epicId === null || epicId === undefined) {
+    return path.join(
+      anchorTempRoot(tempRootFrom(config)),
+      'standalone',
+      PLAN_METRICS_BASENAME,
+    );
+  }
+  return runArtifactPath(epicId, PLAN_METRICS_BASENAME, config);
+}
+
+/**
+ * Rotate the ledger when appending `incomingBytes` would exceed
+ * `maxBytes`. Single-generation rollover: `plan-metrics.json` →
+ * `plan-metrics.json.1` (any prior `.1` is replaced).
+ *
+ * @param {string} filePath
+ * @param {number} incomingBytes
+ * @param {number} maxBytes
+ * @returns {Promise<boolean>} true when a rotation happened.
+ */
+async function rotateIfNeeded(filePath, incomingBytes, maxBytes) {
+  let size = 0;
+  try {
+    size = (await fs.stat(filePath)).size;
+  } catch {
+    return false; // No existing ledger — nothing to rotate.
+  }
+  if (size + incomingBytes <= maxBytes) return false;
+  await fs.rename(filePath, `${filePath}.1`);
+  return true;
+}
+
+/**
+ * The single ledger append tail (Story #4712): serialize the record to one
+ * newline-terminated JSON line, create the ledger directory lazily, rotate
+ * when the byte cap would be exceeded, and append.
+ *
+ * Throws on any fs failure — the best-effort posture (warn + `false`,
+ * never throw) belongs to the public appenders that wrap this, because
+ * each labels its own failure mode.
+ *
+ * @param {object} record Fully-built ledger record (already validated).
+ * @param {{
+ *   epicId?: number|null,
+ *   config?: object,
+ *   maxBytes?: number,
+ * }} [opts] `maxBytes` is a test seam for the rotation threshold.
+ * @returns {Promise<void>}
+ */
+export async function appendLedgerRecord(record, opts = {}) {
+  const filePath = planMetricsPath(opts.epicId ?? null, opts.config);
+  const line = `${JSON.stringify(record)}\n`;
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await rotateIfNeeded(
+    filePath,
+    Buffer.byteLength(line),
+    opts.maxBytes ?? MAX_LEDGER_BYTES,
+  );
+  await fs.appendFile(filePath, line, 'utf8');
+}
+
+/**
+ * Append one findings-yield record (Story #4699). Called once per Story
+ * close by the review spine when the local-lens pass matched (or
+ * floor-skipped) at least one lens. Best-effort: returns `false` (after a
+ * `Logger.warn`) instead of throwing on any failure, so a ledger failure
+ * can never fail the close.
+ *
+ * @param {{
+ *   storyId: number,
+ *   lenses: Array<{ lens: string, findings?: number, skippedByFloor?: boolean }>,
+ *   cli?: string,
+ *   epicId?: number|null,
+ *   diffFloor?: object|null,
+ * }} entry
+ * @param {object} [config]
+ * @param {{ maxBytes?: number }} [opts] Test seam for the rotation threshold.
+ * @returns {Promise<boolean>} true when the line was written.
+ */
+export async function appendFindingsYield(entry, config, opts = {}) {
+  try {
+    if (!entry || typeof entry !== 'object') {
+      throw new TypeError('appendFindingsYield requires an entry object');
+    }
+    const storyId = Number(entry.storyId);
+    if (!Number.isInteger(storyId) || storyId <= 0) {
+      throw new TypeError(
+        'appendFindingsYield requires a positive integer entry.storyId',
+      );
+    }
+    if (!Array.isArray(entry.lenses) || entry.lenses.length === 0) {
+      throw new TypeError(
+        'appendFindingsYield requires a non-empty entry.lenses array',
+      );
+    }
+    const epicId = entry.epicId ?? null;
+    const record = {
+      v: PLAN_METRICS_SCHEMA_VERSION,
+      kind: PLAN_METRICS_KIND_FINDINGS_YIELD,
+      cli:
+        typeof entry.cli === 'string' && entry.cli.length > 0
+          ? entry.cli
+          : 'story-close-review',
+      storyId,
+      epicId,
+      lenses: entry.lenses
+        .filter((l) => l && typeof l.lens === 'string' && l.lens.length > 0)
+        .map((l) => ({
+          lens: l.lens,
+          findings:
+            typeof l.findings === 'number' && Number.isFinite(l.findings)
+              ? l.findings
+              : 0,
+          skippedByFloor: l.skippedByFloor === true,
+        })),
+      diffFloor:
+        entry.diffFloor && typeof entry.diffFloor === 'object'
+          ? entry.diffFloor
+          : null,
+      at: new Date().toISOString(),
+    };
+    await appendLedgerRecord(record, {
+      epicId,
+      config,
+      maxBytes: opts.maxBytes,
+    });
+    return true;
+  } catch (err) {
+    Logger.warn(
+      `[plan-metrics] findings-yield append failed (non-fatal): ${err?.message ?? err}`,
+    );
+    return false;
+  }
+}

package/.agents/scripts/lib/observability/runtime-friction.js

@@ -68,6 +68,13 @@ export const RUNTIME_FRICTION_CATEGORIES = Object.freeze({
   CLOSE_FAILED: 'close-failed',
   /** A bounded merge wait expired with the PR still in flight. */
   MERGE_WAIT_EXHAUSTED: 'merge-wait-exhausted',
+  /**
+   * A review/lens tool failed to *execute* (binary missing, unparseable
+   * output, materialization crash) — an operational degradation, not a code
+   * finding. Story #4699 routes these here so findings severity tiers
+   * reflect code findings only.
+   */
+  TOOL_DEGRADED: 'tool-degraded',
 });
 
 /** Cap on free-form reason text copied into a signal's `details`. */

package/.agents/scripts/lib/observability/terse-result.js

@@ -0,0 +1,114 @@
+import nodeFs from 'node:fs';
+import path from 'node:path';
+
+import { Logger } from '../Logger.js';
+
+/**
+ * Terse hot-path result emission (Story #4685).
+ *
+ * The orchestration CLIs an agent invokes on every delivery turn
+ * (`single-story-init`, `single-story-close`, `single-story-confirm-merge`,
+ * `sync-branch-from-base`, the close `emit-blocked` path) historically dumped
+ * their whole result object to stdout as pretty-printed JSON:
+ *
+ *   --- STORY CLOSE RESULT ---
+ *   { ... every field, 2-space indented ... }
+ *   --- END RESULT ---
+ *
+ * That blob stays resident for the rest of the session and is re-read as
+ * cache every subsequent turn, yet the agent acts on only a handful of its
+ * fields (the machine contract is the separate terminal envelope). This helper
+ * routes the full detail to a temp log the agent can read on demand and emits
+ * a single structured summary line in its place.
+ *
+ * The escape hatch `MANDREL_RESULT_DETAIL=inline` restores the old inline
+ * pretty dump for interactive debugging.
+ */
+
+/** Env var that restores the legacy inline pretty dump when set to `inline`. */
+const RESULT_DETAIL_ENV = 'MANDREL_RESULT_DETAIL';
+
+/**
+ * Turn a human label (`STORY CLOSE RESULT`) into a filesystem-safe log
+ * basename fragment (`story-close-result`).
+ *
+ * @param {string} label
+ * @returns {string}
+ */
+function slugify(label) {
+  return (
+    String(label)
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '') || 'result'
+  );
+}
+
+/**
+ * The full detail block, byte-compatible with the legacy dump the hot-path
+ * scripts used to write to stdout — same markers, same pretty JSON — so a log
+ * a human opens reads exactly as the old inline dump did.
+ *
+ * @param {string} label
+ * @param {unknown} result
+ * @returns {string}
+ */
+function detailBlock(label, result) {
+  return `--- ${label} ---\n${JSON.stringify(result, null, 2)}\n--- END RESULT ---`;
+}
+
+/**
+ * Route a verbose result object off the agent's turn-resident stdout: write the
+ * full pretty detail to a temp log and emit a single-line structured summary in
+ * its place.
+ *
+ * @param {object} args
+ * @param {string} args.label Human label for the result (e.g. `STORY CLOSE RESULT`).
+ * @param {unknown} args.result The full result object; pretty-printed to the log.
+ * @param {Record<string, unknown>} [args.summary] The few fields the agent acts
+ *   on; serialized compactly onto the single summary line.
+ * @param {string|number} [args.scope] Disambiguating suffix for the log name
+ *   (typically the Story id) so concurrent deliveries don't clobber one file.
+ * @param {string} [args.logDir] Directory for the detail log. Defaults to
+ *   `<cwd>/temp/orchestration`.
+ * @param {typeof nodeFs} [args.fs] Filesystem seam (tests).
+ * @param {{ info: (m: string) => void }} [args.log] Logger seam (tests).
+ * @param {NodeJS.ProcessEnv} [args.env] Environment seam (tests).
+ * @returns {{ logPath: string|null, inline: boolean, error?: string }}
+ */
+export function emitTerseResult({
+  label,
+  result,
+  summary = {},
+  scope,
+  logDir,
+  fs = nodeFs,
+  log = Logger,
+  env = process.env,
+} = {}) {
+  const body = detailBlock(label, result);
+
+  // Escape hatch: restore the full inline pretty dump for interactive debugging.
+  if (String(env[RESULT_DETAIL_ENV] ?? '').toLowerCase() === 'inline') {
+    log.info?.(`\n${body}\n`);
+    return { logPath: null, inline: true };
+  }
+
+  const dir = logDir ?? path.join(process.cwd(), 'temp', 'orchestration');
+  const name = `${slugify(label)}${scope ? `-${scope}` : ''}.log`;
+
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    const logPath = path.join(dir, name);
+    fs.writeFileSync(logPath, `${body}\n`);
+    log.info?.(
+      `${label} · ${JSON.stringify(summary)} · full detail → ${logPath}`,
+    );
+    return { logPath, inline: false };
+  } catch (err) {
+    // Never lose detail: if the log write fails, fall back to the inline dump
+    // so the result is still recoverable from the transcript.
+    log.info?.(`\n${body}\n`);
+    return { logPath: null, inline: true, error: err?.message ?? String(err) };
+  }
+}

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

@@ -0,0 +1,318 @@
+/**
+ * lib/orchestration/complexity-gate.js — plan-time ceremony-lite routing gate.
+ *
+ * A **deterministic, conservative** complexity gate that routes a planning seed
+ * onto either the full two-session plan/deliver ceremony (`full`) or a collapsed
+ * ceremony-lite path (`lite`). It exists because the full ceremony imposes a
+ * large fixed cost premium on genuinely trivial single-artifact scopes with no
+ * measured quality gain (Story #4683): the bench cohort spent ~52 turns on a
+ * hello-world scope a bare control delivered in ~6, and no path existed to opt
+ * trivial scopes out.
+ *
+ * ## What "lite" changes and — critically — what it never changes
+ *
+ * The lite route collapses the **advisory ceremony** only: the plan/deliver
+ * session split, the fresh-context critic ceremony, and the Tech-Spec authoring
+ * that a one-artifact scope does not earn. It **never** relaxes a non-negotiable.
+ * {@link LITE_PATH_INVARIANTS} is the machine-readable contract that the lite
+ * path still produces a Story ticket, still lands via a PR to `main`, still runs
+ * every repo quality gate, and still honours `rules/security-baseline.md`. Those
+ * gates run in `single-story-close.js` regardless of route; the gate cannot and
+ * does not switch them off. Every `lite` decision carries this frozen object on
+ * its `preserves` field so a downstream reader can assert the invariants held.
+ *
+ * ## Conservative by construction — full on any doubt
+ *
+ * The gate is total and pure: seed text + resolved config in, decision out. It
+ * routes `lite` **only** when every trivial-scope signal agrees; every other
+ * case — an empty/unreadable seed, a seed above the word ceiling, a seed
+ * enumerating more than one candidate artifact, or the gate disabled by config —
+ * falls to `full`. Being wrong toward `full` costs a session; being wrong toward
+ * `lite` would skip ceremony a real capability slice needs, so the tie always
+ * breaks to `full`.
+ *
+ * ## Threshold + operator override
+ *
+ * {@link DEFAULT_COMPLEXITY_GATE} is the single source of truth for the
+ * threshold. Operators tune it (or disable the gate entirely) via
+ * `planning.complexityGate` in `.agentrc.json`:
+ *
+ *   - `enabled`      (default `true`)  — `false` forces every seed to `full`.
+ *   - `maxSeedWords` (default `150`)   — seed prose word ceiling for `lite`.
+ *   - `maxArtifacts` (default `1`)     — enumerated-artifact ceiling for `lite`.
+ *
+ * Resolution clamps every field toward the conservative default: a malformed or
+ * negative ceiling falls back to the framework default rather than widening the
+ * lite path.
+ *
+ * ## Planner downgrade + the persisted route marker (Story #4707)
+ *
+ * Seed word count is a poor complexity proxy: a well-written 70-word trivial
+ * seed is no less trivial than a terse 40-word one, which is why the ceiling
+ * sits at 150 rather than 60. Two adjacent surfaces live here with the gate so
+ * the whole lite-routing contract has one home:
+ *
+ *   - {@link applyPlannerDowngrade} — the planner may downgrade a `full`
+ *     verdict to `lite` **only** with a recorded reason. The deterministic
+ *     gate itself is unchanged (it still fails toward `full`); the downgrade
+ *     is an auditable model judgment layered on top, never a silent gate
+ *     change. Absent a non-empty reason the deterministic verdict stands.
+ *   - {@link resolveStoryDispatchMode} — the deliver-side reader of the
+ *     persisted {@link LITE_ROUTE_LABEL} marker. A lite-routed Story executes
+ *     inline in the deliver session (no story-worker or acceptance-critic
+ *     sub-agent boots); everything else dispatches as before. Model-side
+ *     fan-out only — never a deterministic close gate.
+ *
+ * @typedef {'lite'|'full'} ComplexityRoute
+ */
+
+/**
+ * Framework defaults for the plan-time complexity gate. The threshold SSOT —
+ * the config schema mirror and the configuration reference both cite these
+ * numbers rather than restating divergent ones.
+ */
+const DEFAULT_COMPLEXITY_GATE = Object.freeze({
+  enabled: true,
+  maxSeedWords: 150,
+  maxArtifacts: 1,
+});
+
+/**
+ * The persisted route marker for a lite-routed Story (Story #4707).
+ *
+ * Applied by plan-persist at create time and read by `/deliver` (via the
+ * resolver envelope's `stories[].labels`) through
+ * {@link resolveStoryDispatchMode}. A full-routed Story carries no marker —
+ * absence is the conservative default, so an unlabelled Story always takes
+ * the sub-agent dispatch path.
+ */
+export const LITE_ROUTE_LABEL = 'route::lite';
+
+/**
+ * The non-negotiables the ceremony-lite path preserves. This is the
+ * contract behind Story #4683 AC-2: collapsing ceremony never means dropping
+ * the Story ticket, the PR-to-`main` landing, the repo quality gates, or the
+ * security baseline. Attached verbatim to every `lite` decision's `preserves`
+ * field; a downstream consumer (or contract test) asserts against it.
+ */
+const LITE_PATH_INVARIANTS = Object.freeze({
+  storyTicket: true,
+  prToMain: true,
+  repoGates: true,
+  securityBaseline: true,
+});
+
+/**
+ * Coerce a candidate ceiling into a non-negative integer, falling back to the
+ * framework default for anything malformed. Non-numbers, non-finite values, and
+ * negatives all fall back — a stray `-1` or `NaN` must never widen the lite path
+ * (the gate fails conservative, toward `full`).
+ *
+ * @param {unknown} value
+ * @param {number} fallback
+ * @returns {number}
+ */
+function normalizeCeiling(value, fallback) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+    return fallback;
+  }
+  return Math.floor(value);
+}
+
+/**
+ * Resolve the effective complexity-gate config, shallow-overlaying an operator
+ * `planning.complexityGate` block onto {@link DEFAULT_COMPLEXITY_GATE}. Accepts
+ * the full resolved config, the bare `planning` bag, or the bare
+ * `complexityGate` bag, mirroring the tolerant unwrap the other routing
+ * accessors use. Module-private: exposed only through the resolved `threshold`
+ * on {@link buildComplexityRouteSignal}'s output, so there is no test-only
+ * export to leave production-dead.
+ *
+ * @param {object | null | undefined} config
+ * @returns {{ enabled: boolean, maxSeedWords: number, maxArtifacts: number }}
+ */
+function resolveComplexityGate(config) {
+  const raw =
+    config?.planning?.complexityGate ?? config?.complexityGate ?? config ?? {};
+  const bag = raw && typeof raw === 'object' ? raw : {};
+  return {
+    enabled:
+      typeof bag.enabled === 'boolean'
+        ? bag.enabled
+        : DEFAULT_COMPLEXITY_GATE.enabled,
+    maxSeedWords: normalizeCeiling(
+      bag.maxSeedWords,
+      DEFAULT_COMPLEXITY_GATE.maxSeedWords,
+    ),
+    maxArtifacts: normalizeCeiling(
+      bag.maxArtifacts,
+      DEFAULT_COMPLEXITY_GATE.maxArtifacts,
+    ),
+  };
+}
+
+/**
+ * Count top-level enumerated items (`- `, `* `, `1. `) in a free-form seed —
+ * the same shape the scope-triage and delivery-shape signals read as candidate
+ * capabilities. Each enumerated line is one predicted artifact; a seed with two
+ * or more is a multi-capability scope that must take the full path.
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+function countSeedArtifacts(text) {
+  if (typeof text !== 'string' || text.length === 0) return 0;
+  return text
+    .split(/\r?\n/)
+    .filter((line) => /^\s*(?:[-*]|\d+\.)\s+\S/.test(line)).length;
+}
+
+/**
+ * Build the advisory complexity-route signal for a planning seed. Deterministic,
+ * total, and conservative (see the module header): every trivial-scope signal
+ * must agree for a `lite` decision; everything else routes `full`.
+ *
+ * The result is folded into the `/plan` context envelope as `complexityRoute`,
+ * so the workflow reads one field instead of re-deriving the decision. Every
+ * `lite` decision carries {@link LITE_PATH_INVARIANTS} on `preserves`.
+ *
+ * @param {{ seedText?: string, config?: object }} [args]
+ * @returns {{
+ *   route: ComplexityRoute,
+ *   reasons: string[],
+ *   threshold: { enabled: boolean, maxSeedWords: number, maxArtifacts: number },
+ *   preserves: typeof LITE_PATH_INVARIANTS,
+ *   advisory: true,
+ * }}
+ */
+export function buildComplexityRouteSignal({ seedText = '', config } = {}) {
+  const threshold = resolveComplexityGate(config);
+  const advisory = /** @type {const} */ (true);
+  const preserves = LITE_PATH_INVARIANTS;
+  const decide = (route, reason) => ({
+    route,
+    reasons: [reason],
+    threshold,
+    preserves,
+    advisory,
+  });
+
+  if (!threshold.enabled) {
+    return decide(
+      'full',
+      'complexity gate disabled (planning.complexityGate.enabled=false) — full plan/deliver ceremony',
+    );
+  }
+
+  const text = typeof seedText === 'string' ? seedText : '';
+  const trimmed = text.trim();
+  if (trimmed.length === 0) {
+    return decide(
+      'full',
+      'empty seed — triviality cannot be judged; conservative full path',
+    );
+  }
+
+  const artifactCount = countSeedArtifacts(text);
+  if (artifactCount > threshold.maxArtifacts) {
+    return decide(
+      'full',
+      `seed enumerates ${artifactCount} candidate artifacts (> maxArtifacts ${threshold.maxArtifacts}) — multi-capability scope takes the full path`,
+    );
+  }
+
+  const wordCount = trimmed.split(/\s+/).filter(Boolean).length;
+  if (wordCount > threshold.maxSeedWords) {
+    return decide(
+      'full',
+      `seed is ${wordCount} words (> maxSeedWords ${threshold.maxSeedWords}) — not a trivial scope; full path`,
+    );
+  }
+
+  return decide(
+    'lite',
+    `trivial single-artifact scope (${wordCount} words ≤ ${threshold.maxSeedWords}, ${artifactCount} enumerated artifact(s) ≤ ${threshold.maxArtifacts}) — collapsed ceremony-lite path; non-negotiables preserved`,
+  );
+}
+
+/**
+ * Apply an auditable planner downgrade to a `full` complexity verdict
+ * (Story #4707).
+ *
+ * The deterministic gate is conservative by construction, and seed word count
+ * is a poor complexity proxy — so the planner is allowed to judge a `full`
+ * verdict down to `lite`, but **only** with a recorded reason. The contract:
+ *
+ *   - No non-empty reason → the deterministic verdict stands, unchanged. A
+ *     downgrade without a reason is indistinguishable from a silent gate
+ *     change, which is exactly what this path must never be.
+ *   - A signal that is not a `full` verdict (already `lite`, or absent) is
+ *     returned unchanged — there is nothing to downgrade.
+ *   - Otherwise the returned signal routes `lite`, appends the reason to
+ *     `reasons`, and carries a frozen `downgraded: { from: 'full', reason }`
+ *     record so the judgment is ledgerable on plan state (plan-persist writes
+ *     it into every created Story's `story-plan-state` checkpoint).
+ *
+ * Pure and total: never mutates `signal`, never throws on malformed input.
+ * The gate itself ({@link buildComplexityRouteSignal}) is untouched — it
+ * still fails toward `full` on any doubt.
+ *
+ * @param {ReturnType<typeof buildComplexityRouteSignal>|null|undefined} signal
+ * @param {{ reason?: unknown }} [args]
+ * @returns {object|null|undefined} The (possibly downgraded) signal.
+ */
+export function applyPlannerDowngrade(signal, { reason } = {}) {
+  if (!signal || typeof signal !== 'object' || signal.route !== 'full') {
+    return signal;
+  }
+  const recorded = typeof reason === 'string' ? reason.trim() : '';
+  if (recorded === '') return signal;
+  return {
+    ...signal,
+    route: 'lite',
+    reasons: [
+      ...(Array.isArray(signal.reasons) ? signal.reasons : []),
+      `planner downgrade full → lite (recorded reason): ${recorded}`,
+    ],
+    downgraded: Object.freeze({ from: 'full', reason: recorded }),
+  };
+}
+
+/**
+ * Decide how `/deliver` executes a Story from its persisted route marker
+ * (Story #4707).
+ *
+ * Reads the labels the resolver envelope already carries. A Story labelled
+ * {@link LITE_ROUTE_LABEL} executes **inline** in the deliver session — no
+ * story-worker sub-agent boot and no fresh acceptance-critic sub-agent
+ * dispatch (sub-agent boots are the dominant deliver-phase token cost at
+ * trivial scope). Every other Story — including one with missing or
+ * malformed labels — dispatches as a sub-agent: absence of the marker is the
+ * conservative default, mirroring the gate's fail-toward-`full` posture.
+ *
+ * Inline execution removes model-side fan-out only. Every deterministic
+ * `single-story-close.js` gate (validation, security baseline, PR-to-`main`)
+ * runs unchanged regardless of mode — see {@link LITE_PATH_INVARIANTS}.
+ *
+ * @param {{ labels?: unknown }} [args]
+ * @returns {{ mode: 'inline'|'subagent', reasons: string[] }}
+ */
+export function resolveStoryDispatchMode({ labels } = {}) {
+  const list = Array.isArray(labels)
+    ? labels.filter((l) => typeof l === 'string')
+    : [];
+  if (list.includes(LITE_ROUTE_LABEL)) {
+    return {
+      mode: 'inline',
+      reasons: [
+        `Story carries the ${LITE_ROUTE_LABEL} route marker — execute deliver-story inline; no story-worker or acceptance-critic sub-agent dispatch (close gates unchanged)`,
+      ],
+    };
+  }
+  return {
+    mode: 'subagent',
+    reasons: [
+      `no ${LITE_ROUTE_LABEL} route marker — standard sub-agent dispatch`,
+    ],
+  };
+}