mandrel 2.56.0 → 2.57.0

package/.agents/schemas/agentrc.schema.json

@@ -327,145 +327,21 @@
     },
     "planning": {
       "type": "object",
-      "description": "Inputs to `/mandrel-plan`: risk escalation heuristics, ceremony-lite routing, the memory-hygiene advisory thresholds, and the cross-Story conflict-finding severity gates.",
+      "description": "Inputs to `/mandrel-plan`: the memory-hygiene advisory ceiling and the opt-in navigability reachability gate.",
       "properties": {
-        "riskHeuristics": {
-          "oneOf": [
-            {
-              "type": "array",
-              "items": {
-                "type": "string"
-              }
-            },
-            {
-              "type": "object",
-              "properties": {
-                "append": {
-                  "type": "array",
-                  "items": {
-                    "type": "string"
-                  }
-                },
-                "prepend": {
-                  "type": "array",
-                  "items": {
-                    "type": "string"
-                  }
-                }
-              },
-              "additionalProperties": false
-            }
-          ],
-          "description": "Prose heuristics the planner escalates a Story against. A plain array replaces the framework list; the `{ append, prepend }` extender form deep-merges with it.",
-          "default": [
-            "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).",
-            "Changes to CI/CD, deployment pipelines, or release gating that could disable safety checks or ship unverified code to production.",
-            "Monorepo-wide AST or text replacements touching overlapping files in parallel (catastrophic merge-conflict risk across concurrent agents).",
-            "Schema migrations that rewrite existing rows or drop columns without a backfill or rollback plan."
-          ]
-        },
-        "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.",
-          "properties": {
-            "enabled": {
-              "type": "boolean",
-              "description": "Master switch. When false, lite routing is disabled everywhere: persist refuses lite claims and dispatch always takes the sub-agent path. Default true."
-            },
-            "maxArtifacts": {
-              "type": "integer",
-              "minimum": 0,
-              "description": "Enumerated-artifact threshold reported by the plan-context complexity signals. An input signal for the planner verdict — carries no routing authority. Default 1."
-            }
-          },
-          "additionalProperties": false
-        },
         "memoryPool": {
           "type": "object",
-          "description": "Thresholds for the memory-hygiene advisory `/mandrel-plan` surfaces at Gate #1. Advisory only: it recommends `/memory-consolidate` and never gates, reroutes, or mutates the memory pool.",
+          "description": "Threshold for the memory-hygiene advisory `/mandrel-plan` surfaces at Gate #1. Advisory only: it recommends `/memory-consolidate` and never gates, reroutes, or mutates the memory pool.",
           "properties": {
-            "staleAfterDays": {
-              "type": "integer",
-              "minimum": 1,
-              "description": "Recommend a consolidation pass once the pool's stamp is older than this many days. Default 30.",
-              "default": 30
-            },
-            "growthDelta": {
-              "type": "integer",
-              "minimum": 1,
-              "description": "Recommend a consolidation pass once this many entries have been written since the last one. Measured against the entry count the last pass stamped, so a stamp predating that field leaves growth unmeasured and only the age threshold applies. Default 25.",
-              "default": 25
-            },
             "indexByteCeiling": {
               "type": "integer",
               "minimum": 1,
-              "description": "Recommend a consolidation pass once the pool's `MEMORY.md` index exceeds this many bytes. Independent of the age and growth thresholds: the harness truncates the index it loads into each session at its own byte cap, so an oversized index is a loss already happening — every entry listed after the cut is invisible — rather than a hygiene forecast. Default 24576, the harness cap itself.",
+              "description": "Recommend a consolidation pass once the pool's `MEMORY.md` index exceeds this many bytes. The harness truncates the index it loads into each session at its own byte cap, so an oversized index is a loss already happening — every entry listed after the cut is invisible — rather than a hygiene forecast. Default 24576, the harness cap itself.",
               "default": 24576
             }
           },
           "additionalProperties": false
         },
-        "failOnSharedEditors": {
-          "type": "boolean",
-          "description": "When true, upgrade shared-editor conflict findings to hard errors (default false — advisory soft findings only).",
-          "default": false
-        },
-        "requireExplicitCrossStoryDeps": {
-          "type": "boolean",
-          "description": "When true, upgrade implicit cross-Story dependency findings to hard errors (default false — advisory soft findings only).",
-          "default": false
-        },
-        "crossCuttingRegistries": {
-          "oneOf": [
-            {
-              "type": "array",
-              "items": {
-                "type": "string"
-              }
-            },
-            {
-              "type": "object",
-              "properties": {
-                "append": {
-                  "type": "array",
-                  "items": {
-                    "type": "string"
-                  }
-                },
-                "prepend": {
-                  "type": "array",
-                  "items": {
-                    "type": "string"
-                  }
-                }
-              },
-              "additionalProperties": false
-            }
-          ],
-          "description": "Registry path patterns whose concurrent edits across Stories are flagged as conflicts. Defaults to the framework listener/handler index patterns when omitted.",
-          "default": [
-            "lib/orchestration/lifecycle/listeners/index.js",
-            "**/listeners/index.js",
-            "**/handlers/index.js"
-          ]
-        },
-        "failOnRegistryConflicts": {
-          "type": "boolean",
-          "description": "When true, upgrade cross-cutting registry conflict findings to hard errors (default false).",
-          "default": false
-        },
-        "failOnLargeFanOut": {
-          "type": "boolean",
-          "description": "When true, upgrade fan-out-warning findings (delete blast radius) to hard errors (default false — soft advisory).",
-          "default": false
-        },
-        "largeFanOutThreshold": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Call-site count above which a Story that deletes a module emits a fan-out-warning. Counts base-branch references to the deleted path basename. Soft by default; does not size or reject Stories. Default 10.",
-          "default": 10
-        },
         "navigation": {
           "type": "object",
           "description": "Opt-in navigability reachability gate. Absent or empty routeGlobs is a silent no-op.",
@@ -494,7 +370,7 @@
     },
     "delivery": {
       "type": "object",
-      "description": "Everything `/mandrel-deliver` and `single-story-close` consume: execution timeouts, worktree isolation, runner concurrency, docs freshness, signals, quality gates, merge/CI watch, review ceremony, and the feedback loop.",
+      "description": "Everything `/mandrel-deliver` and `single-story-close` consume: execution timeouts, worktree isolation, runner concurrency, docs freshness, quality gates, merge/CI watch, review ceremony, and the feedback loop.",
       "properties": {
         "execution": {
           "type": "object",
@@ -671,39 +547,6 @@
             }
           ]
         },
-        "signals": {
-          "type": "object",
-          "description": "Detector thresholds for the surviving performance-signal categories. Each block is shallow-merged by the resolver.",
-          "properties": {
-            "rework": {
-              "type": "object",
-              "description": "Rework detector — repeated edits to one file in a run.",
-              "properties": {
-                "editsPerFile": {
-                  "type": "integer",
-                  "minimum": 1,
-                  "description": "Edits to a single file within one run that trip the rework signal.",
-                  "default": 5
-                }
-              },
-              "additionalProperties": false
-            },
-            "retry": {
-              "type": "object",
-              "description": "Retry detector — the same command failing repeatedly.",
-              "properties": {
-                "repeatCount": {
-                  "type": "integer",
-                  "minimum": 1,
-                  "description": "Repeats of an identical failing command that trip the retry signal.",
-                  "default": 3
-                }
-              },
-              "additionalProperties": false
-            }
-          },
-          "additionalProperties": false
-        },
         "quality": {
           "type": "object",
           "description": "Quality-gate configuration. Every gate lives under `gates.<tier>` and shares the same `{ enabled, baselinePath, tolerance, floors, components }` base; shared scoping lives at this block root.",
@@ -1610,12 +1453,6 @@
                   "description": "Cyclomatic complexity at which a new or changed method is flagged for a refactor look.",
                   "default": 8
                 },
-                "cyclomaticMustFix": {
-                  "type": "integer",
-                  "minimum": 1,
-                  "description": "Cyclomatic complexity at which a new or changed method must be decomposed before the diff closes.",
-                  "default": 12
-                },
                 "requireSiblingTest": {
                   "type": "boolean",
                   "description": "When true, a new source file with no colocated sibling test is reported by the guardrails pass.",
@@ -1857,12 +1694,6 @@
               "description": "Maximum auto-fix retry attempts per finding in /mandrel-deliver Phase 5 (code-review). 0 disables auto-fix. Default 3.",
               "default": 3
             },
-            "maxFixScopeFiles": {
-              "type": "integer",
-              "minimum": 1,
-              "description": "Maximum file count a single auto-fix may modify before escalating to agent::blocked. Default 5.",
-              "default": 5
-            },
             "autoFixSeverity": {
               "type": "string",
               "enum": ["high", "medium"],
@@ -1898,12 +1729,12 @@
         },
         "acceptanceEval": {
           "type": "object",
-          "description": "Story #3819. Bounded per-Story acceptance self-eval loop. After the implementation commits land and before the Story-implementation phase flips to `closing`, an independent (fresh-context) critic pass scores the caller-injected change set against each inline `acceptance[]` item, redrafts the unmet items, and re-evaluates — capped at `maxRounds` redraft rounds, then escalates to `agent::blocked` when criteria remain unmet. There is no `enabled` flag: the loop is a hard cutover (always on).",
+          "description": "Story #3819. Bounded per-Story acceptance self-eval loop. After the implementation commits land and before the Story-implementation phase flips to `closing`, an independent (fresh-context) critic pass scores the caller-injected change set against each inline `acceptance[]` item, redrafts the unmet items, and re-evaluates — capped at `maxRounds` redraft rounds (0 = scored once, no redraft), then escalates to `agent::blocked` when criteria remain unmet. There is no `enabled` flag: the scoring pass is a hard cutover (always on).",
           "properties": {
             "maxRounds": {
               "type": "integer",
-              "minimum": 1,
-              "description": "Maximum number of redraft rounds before escalation. Default 2; clamped into [1, hard ceiling] by lib/config/acceptance-eval.js so the cap can never be disabled (maxRounds: 0 clamps up to 1).",
+              "minimum": 0,
+              "description": "Maximum number of redraft rounds before escalation. Default 2; 0 means the verdict is scored once with no redraft round (Story #5313 dropped the hard ceiling and the floor-of-one clamp).",
               "default": 2
             }
           },
@@ -2012,24 +1843,17 @@
         },
         "routing": {
           "type": "object",
-          "description": "v2 delivery-spawn routing: role-scoped boot contexts and maker-checker sampling. The v1 singleDelivery epic-route kill-switch was removed in Stage 6.",
+          "description": "v2 delivery-spawn routing: role-scoped boot contexts and the ceremony profile. The v1 singleDelivery epic-route kill-switch was removed in Stage 6; the freshCriticSampleRate sampling floor was retired in Story #5313.",
           "properties": {
             "roleScopedAgents": {
               "type": "boolean",
               "description": "Epic #4478 (M7-B). Kill-switch for the role-scoped boot contexts. When true (default), a converted delivery spawn (`story-worker`, `acceptance-critic`) boots on its own `.claude/agents/<role>.md` system prompt instead of re-paying the full CLAUDE.md @-import closure. When false, every converted spawn falls back to `subagent_type: general-purpose` — the instant, code-rollback-free per-consumer revert, and the universal escape for hosts that ignore `.claude/agents/`. The fallback is the full-closure agent that ran before M7-B, so flipping it off never drops a gate.",
               "default": true
             },
-            "freshCriticSampleRate": {
-              "type": "number",
-              "minimum": 0,
-              "maximum": 1,
-              "description": "Epic #4478 (M7-B, Part 2). Maker-checker sampling floor. Under the standard profile, a change set touching no sensitive path routes its acceptance clusters down the contract-identical inline critic path, but this fraction of them is still forced through a fresh-context critic so a low derived level never means zero independent checking. Clamped to [0, 1]; 0 disables the floor, 1 forces every cluster fresh. Consumed by resolveCeremonyForRisk (lib/orchestration/ceremony-routing.js).",
-              "default": 0.2
-            },
             "ceremonyProfile": {
               "type": "string",
               "enum": ["minimal", "standard", "strict"],
-              "description": "Acceptance-ceremony depth. minimal = always inline critic; strict = always fresh-context critic; standard (default) = routed off the change level derived from the Story diff, with the maker-checker sampling floor.",
+              "description": "Acceptance-ceremony depth. minimal = always inline critic; strict = always fresh-context critic; standard (default) = routed off the change level derived from the Story diff: high or underivable → fresh, low → inline.",
               "default": "standard"
             },
             "closeAndLand": {

package/.agents/schemas/story-deliver-terminal.schema.json

@@ -161,7 +161,7 @@
           "type": "array",
           "minItems": 1,
           "items": { "type": "string", "minLength": 1 },
-          "description": "The gate's reasons verbatim — the same strings the ask-operator path prints, so attended and unattended over-scope explain themselves identically."
+          "description": "The gate's reasons verbatim — the same strings the gate logs, so an escalation explains itself identically on every surface."
         },
         "created": {
           "type": "object",

package/.agents/scripts/acceptance-eval.js

@@ -17,8 +17,8 @@
  *   1. Validate the verdict file against the verdict JSON Schema (a
  *      malformed verdict is a hard error — the loop refuses to guess).
  *   2. Decide `proceed | redraft | block` from the per-criterion verdicts
- *      and the resolved, undisableable round cap
- *      (`delivery.acceptanceEval.maxRounds`, clamped to `[1, ceiling]`).
+ *      and the resolved redraft budget (`delivery.acceptanceEval.maxRounds`;
+ *      `0` means the verdict is scored once with no redraft round).
  *   3. Emit one per-criterion `acceptance-eval` signal into the retro /
  *      feedback substrate so the retro and `/mandrel-plan` Phase 0 feedback
  *      fetch can see which acceptance items needed rework and the round
@@ -46,14 +46,19 @@
  * the caller into ONE verdict — `criteria[]` in acceptance-array order — and
  * scored here exactly once. Invoking the gate per cluster instead would burn
  * one Story-level round per cluster (distinct fingerprints defeat the replay
- * guard) and race the `signals.ndjson` round ledger. `--expected-criteria`
- * makes that contract enforceable: a partial (single-cluster) verdict is
- * rejected before scoring, so the mistake costs no round.
+ * guard) and race the `signals.ndjson` round ledger. The gate reads the
+ * Story's own `acceptance[]` count off its body (Story #5313) and rejects a
+ * verdict whose `criteria[]` length differs **before** scoring, so the
+ * mistake costs no round. `--expected-criteria` is still accepted but is
+ * redundant with the derived count: when both are known they must agree.
+ * An inline-owned verdict is one file scored in one call — the cluster
+ * merge applies only to fresh critics.
  *
  * CLI:
  *   --story <id>              Story ID (required).
  *   --verdict <path>          Path to the round's verdict JSON (required).
- *   --expected-criteria <n>   Reject a verdict not covering exactly n criteria.
+ *   --expected-criteria <n>   Optional; must equal the Story's acceptance[]
+ *                             count when the body is readable.
  *   --no-signal               Suppress the signal emit (tests).
  *
  * Stdout: a single JSON envelope
@@ -93,6 +98,8 @@ import {
   FULL_SUITE_SHAPE_WARNING,
   isFullSuiteCommand,
 } from './lib/orchestration/verify-credit.js';
+import { createProvider } from './lib/provider-factory.js';
+import { parse as parseStoryBody } from './lib/story-body/story-body.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -181,10 +188,84 @@ const MERGE_CONTRACT =
   "merge every cluster's records into a single criteria[] in acceptance[] order, " +
   'one per acceptance item, before scoring.';
 
+/**
+ * Read the Story's `acceptance[]` count off its body (Story #5313), so the
+ * coverage assertion no longer depends on the caller restating a number it
+ * already read. Total: any failure — no provider, an unreadable ticket, an
+ * unparseable body — yields `null`, which routes the caller to the flag (when
+ * passed) and otherwise to a stated, logged skip. It never manufactures a
+ * count.
+ *
+ * @param {{ storyId: number, config: object }} args
+ * @param {{ createProviderFn?: typeof createProvider, parseBodyFn?: typeof parseStoryBody }} [deps]
+ * @returns {Promise<number|null>}
+ */
+export async function readStoryAcceptanceCount(
+  { storyId, config },
+  { createProviderFn = createProvider, parseBodyFn = parseStoryBody } = {},
+) {
+  try {
+    const ticket = await createProviderFn(config).getTicket(storyId);
+    const body = typeof ticket?.body === 'string' ? ticket.body : null;
+    if (body === null) return null;
+    const acceptance = parseBodyFn(body)?.body?.acceptance;
+    return Array.isArray(acceptance) && acceptance.length > 0
+      ? acceptance.length
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reconcile the body-derived count with the optional flag (Story #5313): the
+ * derived count is authoritative; a flag that disagrees with it is a wiring
+ * error worth failing on rather than a value to prefer silently.
+ *
+ * @param {{ derived: number|null, flagged: number|null }} args
+ * @returns {number|null}
+ */
+export function reconcileExpectedCriteria({ derived, flagged }) {
+  if (derived === null) return flagged;
+  if (flagged !== null && flagged !== derived) {
+    throw new Error(
+      `acceptance-eval: --expected-criteria ${flagged} disagrees with the Story's acceptance[] count (${derived}); drop the flag — the gate reads the count itself.`,
+    );
+  }
+  return derived;
+}
+
+/**
+ * The count the coverage assertion runs against: the body-derived count,
+ * reconciled with the optional flag, with a stated skip when neither is
+ * readable (Story #5313). Split out of `runAcceptanceEvalCli` so the CLI
+ * body's own branching stays inside its committed cyclomatic budget.
+ *
+ * @param {{ storyId: number, config: object, flagged: number|null, readAcceptanceCountImpl: typeof readStoryAcceptanceCount, logger: { warn?: Function } }} args
+ * @returns {Promise<number|null>}
+ */
+async function resolveExpectedCriteriaCount({
+  storyId,
+  config,
+  flagged,
+  readAcceptanceCountImpl,
+  logger,
+}) {
+  const derived = await readAcceptanceCountImpl({ storyId, config });
+  const expected = reconcileExpectedCriteria({ derived, flagged });
+  if (expected === null) {
+    logger.warn?.(
+      '[acceptance-eval] ⚠ the Story acceptance[] count could not be read and no --expected-criteria was passed — the coverage assertion is skipped for this round.',
+    );
+  }
+  return expected;
+}
+
 /**
  * Resolve the optional `--expected-criteria` flag to a positive integer, or
- * `null` when the flag is absent (which preserves the pre-#4951 behaviour
- * exactly — no coverage assertion is made).
+ * `null` when the flag is absent. Since Story #5313 the gate derives the
+ * count from the Story body; the flag remains accepted for callers that
+ * still pass it and is checked against the derived value.
  *
  * Exported for tests.
  *
@@ -225,7 +306,7 @@ export function assertCriteriaCoverage(verdict, expectedCriteria) {
   const actual = Array.isArray(verdict?.criteria) ? verdict.criteria.length : 0;
   if (actual === expectedCriteria) return;
   throw new Error(
-    `acceptance-eval: verdict covers ${actual} criteria but --expected-criteria is ${expectedCriteria}. ` +
+    `acceptance-eval: verdict covers ${actual} criteria but the Story's acceptance[] count is ${expectedCriteria}. ` +
       `${MERGE_CONTRACT} No round was consumed.`,
   );
 }
@@ -409,6 +490,7 @@ export async function runAcceptanceEval(
  *   resolveConfigImpl?: typeof resolveConfig,
  *   validateVerdictImpl?: typeof validateVerdict,
  *   runAcceptanceEvalImpl?: typeof runAcceptanceEval,
+ *   readAcceptanceCountImpl?: typeof readStoryAcceptanceCount,
  *   logger?: { info: Function, warn?: Function },
  * }} [deps]
  * @returns {Promise<object>} the emitted envelope.
@@ -422,11 +504,12 @@ export async function runAcceptanceEvalCli(
     resolveConfigImpl = resolveConfig,
     validateVerdictImpl = validateVerdict,
     runAcceptanceEvalImpl = runAcceptanceEval,
+    readAcceptanceCountImpl = readStoryAcceptanceCount,
     logger = Logger,
   } = deps;
   const { storyId, verdictPath, expectedCriteria, emitSignal } =
     parseCliArgs(argv);
-  const expected = resolveExpectedCriteria(expectedCriteria);
+  const flagged = resolveExpectedCriteria(expectedCriteria);
 
   if (!storyId) {
     throw new Error(
@@ -461,9 +544,17 @@ export async function runAcceptanceEvalCli(
 
   const verdict = validateVerdictImpl(parsed);
 
-  // Story #4951: a merged verdict must cover every acceptance[] item. This
-  // runs before the round ledger is touched, so a partial cluster verdict is
-  // a free mistake.
+  // Story #4951 / #5313: a merged verdict must cover every acceptance[] item,
+  // and the count comes from the Story body itself. This runs before the
+  // round ledger is touched, so a partial cluster verdict is a free mistake.
+  const config = resolveConfigImpl();
+  const expected = await resolveExpectedCriteriaCount({
+    storyId,
+    config,
+    flagged,
+    readAcceptanceCountImpl,
+    logger,
+  });
   assertCriteriaCoverage(verdict, expected);
 
   // A verdict whose embedded storyId disagrees with the CLI flag is a
@@ -479,7 +570,6 @@ export async function runAcceptanceEvalCli(
   // caller that injects its own scorer.
   warnOnFullSuiteVerify(verdict, logger);
 
-  const config = resolveConfigImpl();
   const { envelope, exitCode } = await runAcceptanceEvalImpl({
     storyId,
     verdict,
@@ -522,9 +612,9 @@ runAsCli(import.meta.url, main, {
       ['--verdict <path>', 'Path to the authored verdict JSON (required).'],
       [
         '--expected-criteria <n>',
-        'Reject — before scoring, consuming no round — a verdict whose criteria[] ' +
-          "length is not n. Pass the Story's acceptance[] count so a partial " +
-          'cluster verdict cannot be scored as the round.',
+        "Optional and redundant since Story #5313: the gate reads the Story's " +
+          'acceptance[] count itself and rejects a shorter verdict before ' +
+          'scoring. When passed it must agree with that count.',
       ],
       [
         '--no-signal',

package/.agents/scripts/ceremony-derive.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+
+/**
+ * ceremony-derive.js — derive a Story's acceptance ceremony from ground truth
+ * (Story #5313).
+ *
+ * The deliver digest used to hand the worker a three-module import block to
+ * paste into `node --input-type=module -e` — compute the change set, derive
+ * the level, resolve the ceremony — and every hand-carried incantation is a
+ * transcription risk (the object-vs-string `derivedLevel` slip alone routed a
+ * whole class of Stories to the null fail-safe). This CLI is that block,
+ * scripted: one invocation, one JSON object, computed from the branch rather
+ * than recalled.
+ *
+ *   1. Compute the change set ONCE for `<base>...story-<id>`
+ *      (`lib/orchestration/change-set.js`).
+ *   2. Derive the change level and the sensitive-path classes from it
+ *      (`lib/orchestration/review-depth.js#deriveChangeLevel`).
+ *   3. Resolve the ceremony for the configured profile
+ *      (`lib/orchestration/ceremony-routing.js#resolveCeremonyForRisk`).
+ *
+ * Stdout: a single JSON object —
+ *   { storyId, baseRef, headRef, files, enumerated, level, classes, profile,
+ *     mode, reason, verdictOwner }
+ *
+ * `files` is the one change set every acceptance critic must be handed; the
+ * caller never lets a critic re-enumerate it. `files: null` means the diff
+ * could not be enumerated, which routes to the fail-safe fresh critic.
+ *
+ * Exit codes: 0 on a derived decision (including the `null` fail-safe — an
+ * unenumerable diff is a decision, not an error), 1 on a usage error.
+ */
+
+import { parseArgs } from 'node:util';
+
+import { runAsCli } from './lib/cli-utils.js';
+import { getDeliveryRouting } from './lib/config/delivery-routing.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { resolveCeremonyForRisk } from './lib/orchestration/ceremony-routing.js';
+import { computeChangeSet } from './lib/orchestration/change-set.js';
+import { deriveChangeLevel } from './lib/orchestration/review-depth.js';
+
+const USAGE = {
+  invocation:
+    'node .agents/scripts/ceremony-derive.js --story <id> [--base <ref>] [--cwd <path>]',
+  summary:
+    'Compute the Story change set once, derive its change level and sensitive-path classes, resolve the acceptance ceremony, and print one JSON object.',
+  flags: [
+    ['--story <id>', 'Story issue number; the head ref is story-<id>.'],
+    [
+      '--base <ref>',
+      'Base ref for the three-dot diff (default: project.baseBranch, normally main).',
+    ],
+    [
+      '--cwd <path>',
+      'Checkout to run the diff in (default: the current directory).',
+    ],
+  ],
+};
+
+/**
+ * Parse the CLI argv. Exported for tests.
+ *
+ * @param {string[]} argv
+ * @returns {{ storyId: number|null, base: string|null, cwd: string|null }}
+ */
+export function parseArgv(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      story: { type: 'string' },
+      base: { type: 'string' },
+      cwd: { type: 'string' },
+    },
+    strict: false,
+  });
+  const storyId = Number.parseInt(values.story ?? '', 10);
+  return {
+    storyId: Number.isInteger(storyId) && storyId > 0 ? storyId : null,
+    base: values.base ?? null,
+    cwd: values.cwd ?? null,
+  };
+}
+
+/**
+ * The derivation itself — pure over its injected collaborators, so tests can
+ * pin the envelope without spawning git or reading a config.
+ *
+ * @param {{ storyId: number, baseRef: string, cwd: string, ceremonyProfile: string }} input
+ * @param {{
+ *   computeChangeSetImpl?: typeof computeChangeSet,
+ *   deriveChangeLevelImpl?: typeof deriveChangeLevel,
+ *   resolveCeremonyImpl?: typeof resolveCeremonyForRisk,
+ * }} [deps]
+ * @returns {{
+ *   storyId: number, baseRef: string, headRef: string,
+ *   files: string[]|null, enumerated: boolean,
+ *   level: 'low'|'high'|null, classes: string[],
+ *   profile: string, mode: 'fresh'|'inline', reason: string,
+ *   verdictOwner: 'fresh-critic'|'inline-self-eval',
+ * }}
+ */
+export function deriveCeremony(
+  { storyId, baseRef, cwd, ceremonyProfile },
+  deps = {},
+) {
+  const {
+    computeChangeSetImpl = computeChangeSet,
+    deriveChangeLevelImpl = deriveChangeLevel,
+    resolveCeremonyImpl = resolveCeremonyForRisk,
+  } = deps;
+  const headRef = `story-${storyId}`;
+  const changeSet = computeChangeSetImpl({ baseRef, headRef, cwd });
+  const { level, classes } = deriveChangeLevelImpl({
+    changedFiles: changeSet.files,
+  });
+  // `derivedLevel` is the level STRING — handing the `{ level, classes }`
+  // object here was the transcription slip this CLI exists to retire.
+  const ceremony = resolveCeremonyImpl({
+    derivedLevel: level,
+    clusterIndex: 0,
+    ceremonyProfile,
+  });
+  return {
+    storyId,
+    baseRef,
+    headRef,
+    files: changeSet.files,
+    enumerated: changeSet.enumerated,
+    level,
+    classes,
+    profile: ceremony.profile,
+    mode: ceremony.mode,
+    reason: ceremony.reason,
+    verdictOwner: ceremony.verdictOwner,
+  };
+}
+
+/**
+ * CLI shell: resolve the config-backed defaults, derive, print.
+ *
+ * @param {string[]} [argv]
+ * @param {{
+ *   resolveConfigImpl?: typeof resolveConfig,
+ *   stdout?: { write: (s: string) => void },
+ *   cwd?: string,
+ * } & Parameters<typeof deriveCeremony>[1]} [deps]
+ * @returns {Promise<object>} the printed envelope
+ */
+export async function runCeremonyDeriveCli(
+  argv = process.argv.slice(2),
+  deps = {},
+) {
+  const {
+    resolveConfigImpl = resolveConfig,
+    stdout = process.stdout,
+    cwd: defaultCwd = process.cwd(),
+    ...derivationDeps
+  } = deps;
+  const { storyId, base, cwd } = parseArgv(argv);
+  if (!storyId) {
+    throw new Error(
+      'ceremony-derive: --story <id> is required (a positive integer).',
+    );
+  }
+  const workCwd = cwd ?? defaultCwd;
+  const config = resolveConfigImpl({ cwd: workCwd });
+  const envelope = deriveCeremony(
+    {
+      storyId,
+      baseRef: base ?? config?.project?.baseBranch ?? 'main',
+      cwd: workCwd,
+      ceremonyProfile: getDeliveryRouting(config).ceremonyProfile,
+    },
+    derivationDeps,
+  );
+  stdout.write(`${JSON.stringify(envelope)}\n`);
+  return envelope;
+}
+
+async function main() {
+  await runCeremonyDeriveCli();
+  return 0;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'ceremony-derive',
+  propagateExitCode: true,
+  errorPrefix: '[ceremony-derive] ❌ Fatal error',
+  usage: USAGE,
+});