mandrel 2.55.0 → 2.57.0

package/.agents/scripts/audit-to-stories.js

@@ -36,18 +36,20 @@ import { parseArgs } from 'node:util';
 import { buildStoryBody } from './lib/audit-to-stories/build-story-body.js';
 import { classifyGroupsAgainstGitHub } from './lib/audit-to-stories/dedupe-against-github.js';
 import { formatEpicGrouping } from './lib/audit-to-stories/epic-grouping-directive.js';
-import { withFingerprints } from './lib/audit-to-stories/finding-adapter.js';
+import {
+  toCanonicalFinding,
+  withFingerprints,
+} from './lib/audit-to-stories/finding-adapter.js';
 import { groupFindings } from './lib/audit-to-stories/group-findings.js';
 import {
-  DEFAULT_LEDGER_PATH,
-  readLedger,
-  reconcileLedger,
-  writeLedger,
-} from './lib/audit-to-stories/ledger.js';
+  loadIssuesFile,
+  normaliseIssueHit,
+} from './lib/audit-to-stories/issues-file.js';
 import {
   resolveLedgerSummary,
   runLedgerCommit,
 } from './lib/audit-to-stories/ledger-commit.js';
+import { recordFiledIssues } from './lib/audit-to-stories/ledger-record.js';
 import {
   parseAuditReports,
   readSeverityTally,
@@ -55,6 +57,12 @@ import {
 import { buildPlanSeedMarkdown } from './lib/audit-to-stories/seed-from-findings.js';
 import { wireAuditStoryEdges } from './lib/audit-to-stories/wire-dependencies.js';
 import { runAsCli } from './lib/cli-utils.js';
+import {
+  DEFAULT_LEDGER_PATH,
+  readLedger,
+  reconcileLedger,
+  writeLedger,
+} from './lib/findings/audit-ledger.js';
 import { searchSemanticCandidates } from './lib/findings/semantic-issue-search.js';
 import {
   normalizeSeverity,
@@ -366,28 +374,6 @@ class ProviderUnavailableError extends Error {
   }
 }
 
-/**
- * Flatten one raw `searchIssues` hit onto the `{ number, state, title, body }`
- * shape the dedupe module reads, collapsing every closed-ish state spelling
- * (`CLOSED`, `state_reason: not_planned`, …) onto `'closed'`.
- *
- * @param {object} hit
- * @returns {{ number: number, state: 'open'|'closed', title: string, body: string }}
- */
-function normaliseIssueHit(hit) {
-  return {
-    number: hit.number,
-    state: (hit.state ?? hit.state_reason ?? 'open')
-      .toString()
-      .toLowerCase()
-      .includes('closed')
-      ? 'closed'
-      : 'open',
-    title: hit.title ?? '',
-    body: hit.body ?? '',
-  };
-}
-
 /**
  * Walk the list endpoint once per label and merge the pages into one
  * deduplicated, normalised issue list.
@@ -649,6 +635,136 @@ function dedupDegradedWarning(entries) {
   );
 }
 
+/**
+ * Render the operator-visible line naming a host-supplied index and its size.
+ *
+ * Always emitted for a `--issues-file` run, because "how many issues did you
+ * actually check against" is the one number that separates a real dedup from a
+ * plan that merely looks checked. At zero it is the load-bearing case: an empty
+ * corpus is a legitimate first sweep AND exactly what a broken fetch writes, so
+ * the operator — not the run — decides which this was. Deliberately distinct in
+ * wording from both `dedupSkippedWarning` and `dedupDegradedWarning` so the
+ * three are never confused in a scrollback.
+ *
+ * @param {{ source?: string, size?: number }} dedupIndex
+ * @returns {string}
+ */
+function dedupIndexWarning({ size = 0 } = {}) {
+  if (size === 0) {
+    return (
+      'dedup index: 0 issues supplied via --issues-file. Dedup DID run and ' +
+      'every group is correctly "create" — but that is also what a fetch that ' +
+      'returned nothing looks like. If audit issues already exist, the fetch ' +
+      'that wrote this file is broken and this run will re-file them.'
+    );
+  }
+  return `dedup index: ${size} issue(s) supplied via --issues-file; every exact-fingerprint lookup was answered from it.`;
+}
+
+/**
+ * Render the warning for a pre-fetch of the issue index that could not
+ * complete. The run still dedups — it falls back to a per-finding search — but
+ * it loses the one-list saving, and until Story #5301 this failure was
+ * swallowed whole: the operator saw only the downstream per-group degradation
+ * and could not tell that the pre-fetch itself was the cause.
+ *
+ * @param {string} reason
+ * @returns {string}
+ */
+function dedupIndexDegradedWarning(reason) {
+  return (
+    `dedup index unavailable: ${reason}. Dedup fell back to a per-finding ` +
+    'search, which is slower and rate-limited — if those searches also fail, ' +
+    'every affected group is classified "create" WITHOUT a dedup check.'
+  );
+}
+
+/**
+ * Phase 6: classify every group against GitHub, and say loudly whichever way
+ * it went.
+ *
+ * Extracted from `buildPlan` because the gate has three outcomes, not two, and
+ * inlining them pushed the caller past its complexity ceiling. The three:
+ *
+ *   - **deduped** — a provider resolved, or the host supplied a corpus, or
+ *     both. A host-supplied corpus is a dedup source in its own right, which is
+ *     the whole point: the gate asks "can we dedup at all", not "did a provider
+ *     resolve". While it asked the latter, `--no-provider --issues-file` — the
+ *     one invocation a `gh`-less host can run — short-circuited to the seeded
+ *     all-`create` classifications however well the dedupe module worked.
+ *   - **skipped, no port** — a provider was wanted but could not be adapted.
+ *   - **skipped, disabled** — `--no-provider` with no corpus to fall back on.
+ *
+ * Every outcome warns on stderr, so the `--scan` JSON on stdout stays clean and
+ * a create-only plan is never read as "checked, found nothing".
+ *
+ * @param {{ groups: Array<object>, useProvider?: boolean,
+ *   issues?: Array<object>|null }} params
+ * @param {{ loadProviderImpl: Function, classifyGroupsImpl: Function,
+ *   logger: { warn: Function } }} deps
+ * @returns {Promise<{ classifications: Array<object>, summary: object,
+ *   dedupApplied: boolean }>}
+ */
+async function runDedupPhase(
+  { groups, useProvider, issues },
+  { loadProviderImpl, classifyGroupsImpl, logger },
+) {
+  const provider = useProvider ? await loadProviderImpl() : null;
+  if (!provider && !issues) {
+    logger.warn(
+      dedupSkippedWarning(useProvider ? 'no-provider-port' : 'disabled'),
+    );
+    return {
+      classifications: groups.map((group) => ({
+        group,
+        action: 'create',
+        matchedIssues: [],
+        matchedFingerprints: [],
+      })),
+      summary: { create: groups.length, skipOpen: 0, skipReoccurring: 0 },
+      dedupApplied: false,
+    };
+  }
+
+  const { classifications, summary } = await classifyGroupsImpl({
+    groups,
+    provider,
+    searchCandidates: provider?.searchCandidates,
+    listAuditIssues: provider?.listAuditIssues,
+    issues,
+  });
+  for (const warning of dedupPhaseWarnings({ issues, summary })) {
+    logger.warn(warning);
+  }
+  return { classifications, summary, dedupApplied: true };
+}
+
+/**
+ * Every warning a completed dedup pass owes the operator, in order. Pure, so
+ * the wording stays unit-testable and `runDedupPhase` keeps one write site.
+ *
+ * @param {{ issues?: Array<object>|null, summary: object }} params
+ * @returns {string[]}
+ */
+function dedupPhaseWarnings({ issues, summary }) {
+  const warnings = [];
+  if (issues) warnings.push(dedupIndexWarning(summary.dedupIndex));
+  // The pre-fetch failing is a distinct fact from any group's lookup failing,
+  // and used to be invisible: the operator saw only the downstream per-group
+  // degradation and could not tell what had caused it.
+  if (summary.dedupDegraded?.indexPrefetch) {
+    warnings.push(
+      dedupIndexDegradedWarning(summary.dedupDegraded.indexPrefetch),
+    );
+  }
+  // A partially-checked plan is a useful result — name the groups that degraded
+  // to create because their lookup could not complete (Story #4678).
+  if (summary.dedupDegraded?.count > 0) {
+    warnings.push(dedupDegradedWarning(summary.dedupDegraded.groups));
+  }
+  return warnings;
+}
+
 /**
  * Scan → group → dedup → (optionally) reconcile the cross-run ledger, and
  * return the plan envelope.
@@ -657,12 +773,14 @@ function dedupDegradedWarning(entries) {
  * implementation (`.agents/rules/test-seams.md` rules 1-2, 4), so `main`,
  * `runAuto`, and every production caller are unchanged.
  *
- * @param {{ glob?: string, severity?: string, useProvider?: boolean, ledger?: object }} params
+ * @param {{ glob?: string, severity?: string, useProvider?: boolean,
+ *   issuesFile?: string, ledger?: object }} params
  * @param {{
  *   collectReportPathsImpl?: typeof collectReportPaths,
  *   readReportsImpl?: typeof readReports,
  *   loadProviderImpl?: typeof loadProviderOrNull,
  *   classifyGroupsImpl?: typeof classifyGroupsAgainstGitHub,
+ *   loadIssuesFileImpl?: typeof loadIssuesFile,
  *   reconcileScanLedgerImpl?: typeof reconcileScanLedger,
  *   logger?: { warn: Function },
  * }} [deps]
@@ -673,6 +791,7 @@ async function buildPlan(
     glob: pattern,
     severity,
     useProvider,
+    issuesFile,
     ledger,
     allowMissingTally,
     failOnReportFailures,
@@ -684,9 +803,14 @@ async function buildPlan(
     readReportsImpl = readReports,
     loadProviderImpl = loadProviderOrNull,
     classifyGroupsImpl = classifyGroupsAgainstGitHub,
+    loadIssuesFileImpl = loadIssuesFile,
     reconcileScanLedgerImpl = reconcileScanLedger,
     logger = Logger,
   } = deps;
+  // Deliberately BEFORE the reports are read: an unusable corpus is a usage
+  // error, and failing fast costs the operator nothing, where failing late
+  // would tempt a fallback that silently dedups nothing.
+  const issues = issuesFile ? loadIssuesFileImpl(issuesFile) : null;
   const reportPaths = await collectReportPathsImpl(pattern ?? DEFAULT_GLOB);
   if (reportPaths.length === 0) {
     return {
@@ -724,45 +848,10 @@ async function buildPlan(
   const stamped = withFingerprints(filtered.filter((f) => Boolean(f.severity)));
   const { groups, edges } = groupFindings(stamped);
 
-  let classifications = groups.map((g) => ({
-    group: g,
-    action: 'create',
-    matchedIssues: [],
-    matchedFingerprints: [],
-  }));
-  let summary = { create: groups.length, skipOpen: 0, skipReoccurring: 0 };
-  let dedupApplied = false;
-
-  if (useProvider) {
-    const provider = await loadProviderImpl();
-    if (provider) {
-      const result = await classifyGroupsImpl({
-        groups,
-        provider,
-        searchCandidates: provider.searchCandidates,
-        listAuditIssues: provider.listAuditIssues,
-      });
-      classifications = result.classifications;
-      summary = result.summary;
-      dedupApplied = true;
-      // A partially-checked plan is a useful result — warn loudly (stderr, so
-      // the --scan JSON on stdout stays clean) naming the groups that degraded
-      // to create because their lookup could not complete (Story #4678).
-      if (summary.dedupDegraded?.count > 0) {
-        logger.warn(dedupDegradedWarning(summary.dedupDegraded.groups));
-      }
-    } else {
-      // The provider could not resolve a searchIssues port — the dedup gate
-      // is silently a no-op without this. Surface it loudly (stderr, so the
-      // --scan JSON on stdout stays clean) so the operator does not read a
-      // create-only plan as "no duplicates found".
-      logger.warn(dedupSkippedWarning('no-provider-port'));
-    }
-  } else {
-    // Operator explicitly opted out via --no-provider. Still warn so a
-    // duplicate-opening re-run is never a surprise.
-    logger.warn(dedupSkippedWarning('disabled'));
-  }
+  const { classifications, summary, dedupApplied } = await runDedupPhase(
+    { groups, useProvider, issues },
+    { loadProviderImpl, classifyGroupsImpl, logger },
+  );
 
   // Cross-run ledger (Story #4626): fold this scan onto the committed memory,
   // suppress findings a prior run recorded as accepted-risk, and (unless the
@@ -832,6 +921,9 @@ function reconcileScanLedger({ ledgerPath, findings, classifications, write }) {
     ledger: prior,
     findings,
     issueStates,
+    // The ledger lives in the shared findings layer and cannot import the
+    // audit adapter without closing a cycle, so the projection is ours to pass.
+    toCanonical: toCanonicalFinding,
   });
   if (write !== false) writeLedger(ledgerPath, next);
   return new Set(
@@ -918,6 +1010,7 @@ async function runAuto({
   severity,
   dryRun,
   useProvider,
+  issuesFile,
   ledgerPath,
   ledgerCommit,
   git,
@@ -930,6 +1023,7 @@ async function runAuto({
     glob,
     severity: floor,
     useProvider,
+    issuesFile,
     ledger: { path: resolvedLedgerPath, write: !dryRun },
     // `--auto` never accepts `--allow-missing-tally`: an unattended sweep has
     // no operator to read a warning, so every report failure is fatal here.
@@ -967,6 +1061,11 @@ async function runAuto({
       skipReoccurring: byAction.skipReoccurring.length,
       suppressedByLedger: byAction.suppressed.length,
     },
+    // `--auto` opens no Issues itself — the caller does, from the `--emit-stories`
+    // drafts — so these keys are the only thing standing between its summary and
+    // the `--wire-edges --ids` map. Without them an unattended sweep cannot
+    // record what it filed, and the ledger stays empty however well it works.
+    createGroupKeys: eligible.map((g) => g?.groupKey).filter(Boolean),
     // Re-detected open Issues the operator may want a "re-detected" comment on.
     reDetected: byAction.skipOpen
       .flatMap((c) => c.matchedIssues ?? [])
@@ -1076,20 +1175,50 @@ function wireEdgesPreconditionError(reason, detail) {
  * re-rendered with a canonical `blocked by #N` footer and the same edges are
  * mirrored as native `blocked_by` relations.
  *
+ * The same map is what the cross-run ledger needs to record what this run
+ * filed, so the record rides along here rather than arriving as a second
+ * command an operator must remember (Story #5305).
+ *
  * @param {object} params
  * @param {object} params.plan   A `--scan` plan envelope.
  * @param {Record<string, number>} params.issueByGroupKey
+ * @param {string} [params.ledgerPath] — ledger to record into; defaults to
+ *   `DEFAULT_LEDGER_PATH` inside the record.
+ * @param {boolean} [params.write] — `false` computes the record without
+ *   persisting it (what `--dry-run` passes).
  * @param {object} [deps]
  * @param {Function} [deps.loadProviderImpl]
  * @param {Function} [deps.wireImpl]
- * @returns {Promise<object>} the wiring summary.
+ * @param {Function} [deps.recordFiledIssuesImpl]
+ * @returns {Promise<object>} the wiring summary, with the ledger record on
+ *   `ledger`.
  */
-async function wireEdges({ plan, issueByGroupKey }, deps = {}) {
-  const { loadProviderImpl = loadProvider, wireImpl = wireAuditStoryEdges } =
-    deps;
+async function wireEdges(
+  { plan, issueByGroupKey, ledgerPath, write },
+  deps = {},
+) {
+  const {
+    loadProviderImpl = loadProvider,
+    wireImpl = wireAuditStoryEdges,
+    recordFiledIssuesImpl = recordFiledIssues,
+  } = deps;
   const groups = (plan.classifications ?? [])
     .filter((c) => c.action === 'create')
     .map((c) => c.group);
+
+  // Record BEFORE the provider is loaded. The record is pure local filesystem
+  // work, while the wiring below needs a provider exposing `updateTicket` — and
+  // the host most likely to lack one is the `gh`-less host where the ledger is
+  // the only duplicate protection there is. Recording first means such a run
+  // still remembers what it filed, and the precondition error below still
+  // surfaces unchanged afterwards.
+  const ledger = recordFiledIssuesImpl({
+    ledgerPath,
+    groups,
+    issueByGroupKey,
+    write,
+  });
+
   let provider;
   try {
     provider = await loadProviderImpl();
@@ -1099,7 +1228,7 @@ async function wireEdges({ plan, issueByGroupKey }, deps = {}) {
   if (typeof provider?.updateTicket !== 'function') {
     throw wireEdgesPreconditionError('fixture-no-write-port');
   }
-  return wireImpl({
+  const wired = await wireImpl({
     groups,
     edges: plan.edges ?? [],
     issueByGroupKey,
@@ -1107,6 +1236,7 @@ async function wireEdges({ plan, issueByGroupKey }, deps = {}) {
     updateBody: (issueNumber, body) =>
       provider.updateTicket(issueNumber, { body }),
   });
+  return { ...wired, ledger };
 }
 
 /**
@@ -1161,6 +1291,8 @@ export const __testing = {
   loadProviderOrNull,
   dedupSkippedWarning,
   dedupDegradedWarning,
+  dedupIndexWarning,
+  dedupIndexDegradedWarning,
   buildAndGateStories,
   runAuto,
   resolveSeverityFloor,
@@ -1291,6 +1423,7 @@ export async function runAuditToStories(
       plan: { type: 'string' },
       out: { type: 'string' },
       'no-provider': { type: 'boolean' },
+      'issues-file': { type: 'string' },
       'allow-missing-tally': { type: 'boolean' },
       json: { type: 'boolean' },
     },
@@ -1308,6 +1441,7 @@ export async function runAuditToStories(
         severity: values.severity,
         dryRun: values['dry-run'],
         useProvider: !values['no-provider'],
+        issuesFile: values['issues-file'],
         ledgerPath: values.ledger,
         ledgerCommit: values['ledger-commit'],
       })
@@ -1334,6 +1468,7 @@ export async function runAuditToStories(
       glob: values.glob,
       severity: values.severity,
       useProvider: !values['no-provider'],
+      issuesFile: values['issues-file'],
       allowMissingTally: values['allow-missing-tally'],
     });
 
@@ -1359,6 +1494,11 @@ export async function runAuditToStories(
     wireEdgesImpl({
       plan: loadPlanImpl(values.plan),
       issueByGroupKey: parseIssueMapImpl(values.ids),
+      ledgerPath: values.ledger,
+      // `--scan` still never writes the ledger; `--wire-edges` runs only after
+      // the Issues were really opened, where recording is never wrong — so the
+      // record is on by default here and `--dry-run` is what suppresses it.
+      write: !values['dry-run'],
     });
 
   // One table, not a chain of `if (values.X) { …; return; }`. Each entry
@@ -1435,7 +1575,7 @@ runAsCli(import.meta.url, main, {
       ['--emit-stories', 'Emit the Story drafts as JSON.'],
       [
         '--wire-edges',
-        'Second pass: resolve the detected group edges to blocked by #N footers plus native blocked_by relations. Needs --plan and --ids.',
+        'Second pass: resolve the detected group edges to blocked by #N footers plus native blocked_by relations, and record the mapped issues in the cross-run ledger as filed. Needs --plan and --ids; --dry-run suppresses the ledger write.',
       ],
       [
         '--ids <json|path>',
@@ -1443,7 +1583,10 @@ runAsCli(import.meta.url, main, {
       ],
       ['--glob <pattern>', 'Override the audit-results glob.'],
       ['--severity <level>', 'Lowest severity to include (high|medium|low).'],
-      ['--ledger <path>', 'Path to the dedup ledger.'],
+      [
+        '--ledger <path>',
+        `Path to the cross-run dedup ledger (default ${DEFAULT_LEDGER_PATH}).`,
+      ],
       [
         '--ledger-commit',
         'After the --auto summary prints, commit a changed ledger onto chore/audit-ledger-<date>, push it, and open a PR against the base branch (never auto-merged). Ignored under --dry-run.',
@@ -1454,6 +1597,10 @@ runAsCli(import.meta.url, main, {
       ],
       ['--out <path>', 'Write output to a file instead of stdout.'],
       ['--no-provider', 'Skip live GitHub dedup lookups (offline).'],
+      [
+        '--issues-file <path>',
+        'Dedup against a JSON array of issues the host already fetched (every issue labelled audit::*, state all) instead of listing them through the provider. Lets dedup run where there is no gh CLI; composes with --no-provider.',
+      ],
       [
         '--allow-missing-tally',
         'Downgrade a missing "Severity tally:" line to a warning (--scan only; --auto ignores it).',

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,
+});