mandrel 2.24.0 → 2.26.0

package/.agents/scripts/lib/import-graph.js

@@ -0,0 +1,156 @@
+/**
+ * import-graph.js — the shared static-import graph seam (Story #4902).
+ *
+ * Extracted verbatim from `check-arch-cycles.js`, which owned the only
+ * import-graph builder in the repository and kept it private to its own
+ * cycle ratchet. A second consumer now needs the same graph for a very
+ * different question — `audit-baselines.js` ranks hotspot files by import
+ * in-degree — and re-deriving "which module imports which" a second time
+ * would guarantee the two answers drift.
+ *
+ * Note this is a **module** graph, not the task/DAG graph in `lib/Graph.js`;
+ * the two are unrelated despite the shared word.
+ *
+ * The extraction is behaviour-preserving: `check-arch-cycles.js` imports
+ * these helpers and re-exports them, so its public surface (and the ratchet's
+ * output) is unchanged.
+ *
+ * @module lib/import-graph
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Default scan roots making up the project's distributed surface — the
+ * directories published to npm via `package.json` `files[]`. Resolving
+ * them into one graph (relativized against the repo root) means a cycle
+ * crossing two roots is visible to consumers of the graph.
+ *
+ * @type {string[]}
+ */
+export const DEFAULT_ROOTS = [path.join('.agents', 'scripts'), 'bin', 'lib'];
+
+/**
+ * Recursively collect `.js` files under `rootDir`, skipping
+ * `node_modules`. Returns absolute paths, sorted for determinism.
+ *
+ * @param {string} rootDir
+ * @returns {string[]}
+ */
+export function collectJsFiles(rootDir) {
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules') continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.isFile() && entry.name.endsWith('.js')) {
+        out.push(full);
+      }
+    }
+  };
+  walk(rootDir);
+  return out.sort();
+}
+
+const IMPORT_RE = /from\s+['"](\.\.?\/[^'"]+\.js)['"]/g;
+
+/**
+ * Pure helper: extract relative static-import specifiers from source text.
+ *
+ * @param {string} source
+ * @returns {string[]}
+ */
+export function parseRelativeImports(source) {
+  const specs = [];
+  for (const m of source.matchAll(IMPORT_RE)) {
+    specs.push(m[1]);
+  }
+  return specs;
+}
+
+/**
+ * Build a directed import graph over the given files. Node identity is the
+ * file path relative to `rootDir`, posix-separated, so the graph (and any
+ * cycles found in it) serializes identically across platforms. Edges that
+ * resolve outside the scanned file set are dropped.
+ *
+ * @param {string[]} files absolute paths
+ * @param {string} rootDir
+ * @param {{ readFile?: (p: string) => string }} [opts]
+ * @returns {Map<string, string[]>}
+ */
+export function buildGraph(files, rootDir, { readFile } = {}) {
+  const read = readFile ?? ((p) => fs.readFileSync(p, 'utf-8'));
+  const toId = (abs) => path.relative(rootDir, abs).split(path.sep).join('/');
+  const idSet = new Set(files.map(toId));
+  const graph = new Map();
+  for (const file of files) {
+    const id = toId(file);
+    let source;
+    try {
+      source = read(file);
+    } catch {
+      graph.set(id, []);
+      continue;
+    }
+    const edges = [];
+    for (const spec of parseRelativeImports(source)) {
+      const target = path
+        .relative(rootDir, path.resolve(path.dirname(file), spec))
+        .split(path.sep)
+        .join('/');
+      if (idSet.has(target) && target !== id) edges.push(target);
+    }
+    graph.set(id, [...new Set(edges)].sort());
+  }
+  return graph;
+}
+
+/**
+ * Build the whole-repository import graph by scanning the roots that exist
+ * under `cwd`. Returns `null` when none of the roots is present — the
+ * "no resolvable import graph" degradation every consumer must tolerate
+ * rather than treating an absent graph as a graph with no edges.
+ *
+ * @param {string} cwd repository root the ids are relativized against
+ * @param {{ roots?: string[] }} [opts]
+ * @returns {Map<string, string[]> | null}
+ */
+export function resolveRepoGraph(cwd, { roots = DEFAULT_ROOTS } = {}) {
+  const present = roots
+    .map((dir) => path.resolve(cwd, dir))
+    .filter((dir) => fs.existsSync(dir));
+  if (present.length === 0) return null;
+  const files = present.flatMap((dir) => collectJsFiles(dir));
+  if (files.length === 0) return null;
+  return buildGraph(files, path.resolve(cwd));
+}
+
+/**
+ * Count inbound edges per node. Nodes with no inbound edge are present in
+ * the result with a count of 0, so callers never have to distinguish
+ * "unknown module" from "module nothing imports".
+ *
+ * @param {Map<string, string[]> | null} graph
+ * @returns {Map<string, number>} empty when `graph` is null
+ */
+export function computeInDegree(graph) {
+  const degrees = new Map();
+  if (!graph) return degrees;
+  for (const node of graph.keys()) degrees.set(node, 0);
+  for (const edges of graph.values()) {
+    for (const target of edges) {
+      degrees.set(target, (degrees.get(target) ?? 0) + 1);
+    }
+  }
+  return degrees;
+}

package/.agents/scripts/lib/label-constants.js

@@ -111,6 +111,22 @@ export const META_LABELS = {
   CONSUMER_IMPROVEMENT: 'meta::consumer-improvement',
 };
 
+/**
+ * Risk-axis labels. Planning/audit metadata only — `risk::high` carries no
+ * runtime behaviour (the single runtime pause point is `agent::blocked`, see
+ * `.agents/instructions.md` § 1.J); it marks a ticket a human should look at
+ * first. Applied by the audit filer to a Story whose merge contains a Critical
+ * finding.
+ *
+ * Named here because it was a bare `'risk::high'` string literal in
+ * `audit-to-stories/build-story-body.js` and defined by no taxonomy at all —
+ * neither `LABEL_TAXONOMY` nor the audit bootstrap created it, so the audit
+ * filer generated a label the repo did not have (Story #4877).
+ */
+export const RISK_LABELS = {
+  HIGH: 'risk::high',
+};
+
 /**
  * Planning-axis labels (Epic #2880 F7). Currently scoped to the
  * `planning::healthcheck-waived` operator-applied waiver — a historical
@@ -147,6 +163,7 @@ export const PLANNING_HEALTHCHECK_WAIVED = 'planning::healthcheck-waived';
  */
 export const LABEL_COLORS = {
   TYPE: '#7057FF',
+  RISK_HIGH: '#B60205',
   AGENT: '#0E8A16',
   STATUS_BLOCKED: '#D93F0B',
   ACCEPTANCE: '#FBCA04',

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

@@ -534,18 +534,33 @@ function frictionForTerminal(envelope) {
  * Emit the friction record (if any) implied by a terminal envelope.
  * Best-effort; never throws.
  *
+ * `tool` is the CALLER's name, threaded in rather than assumed: TWO CLIs emit
+ * terminal envelopes — `single-story-close.js` (plus its runner) and
+ * `single-story-confirm-merge.js` — and `retro-proposals.js` reads
+ * `emitter.tool` (via {@link normalizeGatheredSignal}) to name the surface a
+ * candidate came from, so hard-coding the close name here attributed every
+ * confirm-merge record to a CLI that never ran and misdirected the follow-up.
+ * Both callers already declare their name once via `runAsCli({ source })`;
+ * pass that same string. The default keeps the close paths — the original
+ * callers, which pass none — emitting exactly what they always did.
+ *
  * @param {object} args
  * @param {object} args.envelope
+ * @param {string} [args.tool] Emitting surface (default `single-story-close`).
  * @param {object} [args.config]
  * @returns {Promise<boolean>} true when a record was appended.
  */
-export async function emitTerminalFriction({ envelope, config } = {}) {
+export async function emitTerminalFriction({
+  envelope,
+  tool = 'single-story-close',
+  config,
+} = {}) {
   const verdict = frictionForTerminal(envelope);
   if (!verdict) return false;
   return emitRuntimeFriction({
     storyId: envelope?.storyId,
     category: verdict.category,
-    tool: 'single-story-close',
+    tool,
     details: verdict.details,
     config,
   });

package/.agents/scripts/lib/observability/source-classifier.js

@@ -17,6 +17,9 @@
  *       - `.agentrc.json`
  *       - `.claude/`
  *       - `node .agents/scripts/`
+ *     …or (Story #4916) names one of the CLI entry points shipped at the
+ *     top level of `.agents/scripts/` by **bare basename**, so recognition
+ *     does not depend on how the caller spelled the reference.
  *   - Anything else (or empty input) defaults to `"consumer"`. The default
  *     is intentional — most friction comes from consumer code touching
  *     framework tooling, and we'd rather under-tag than mis-route a
@@ -47,6 +50,133 @@ const FRAMEWORK_PREFIXES = Object.freeze([
   'node .agents/scripts/',
 ]);
 
+/**
+ * Basenames of the CLI entry points shipped at the top level of
+ * `.agents/scripts/` (Story #4916).
+ *
+ * The prefix scan above recognises a framework script only when the caller
+ * spelled a path — `node .agents/scripts/acceptance-eval.js` classifies
+ * `framework`, while the same script named bare (`acceptance-eval.js --story
+ * 4901`) matched no prefix and fell through to `consumer`, so a real framework
+ * defect was routed as consumer-actionable and discarded. Recognition must not
+ * depend on how the caller spelled the reference.
+ *
+ * Kept as **static data**, not a directory read: `classifySignalSource` is
+ * called once per signal and MUST stay pure — no filesystem I/O at classify
+ * time. The sync test in
+ * `tests/lib/observability/source-classifier.test.js` reads the real directory
+ * and fails when a script is added, renamed, or removed without this list
+ * being updated, so the set cannot go stale and silently restore the blind
+ * spot.
+ *
+ * Scoped to the top level deliberately: those are the entry points a command
+ * line names. Library modules under `.agents/scripts/lib/` carry generic
+ * basenames (`index.js`, `config.js`) that a consumer command could plausibly
+ * name, and widening to them would trade one mis-route for another.
+ *
+ * @type {readonly string[]}
+ */
+const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
+  'acceptance-eval.js',
+  'agents-bootstrap-github.js',
+  'apply-quality-bootstrap.js',
+  'audit-baselines.js',
+  'audit-labels-bootstrap.js',
+  'audit-to-stories.js',
+  'boot-sweep.js',
+  'bootstrap.js',
+  'check-action-pinning.js',
+  'check-arch-cycles.js',
+  'check-baseline-drift.js',
+  'check-baselines.js',
+  'check-context-budget.js',
+  'check-cyclomatic.js',
+  'check-dead-exports.js',
+  'check-doc-links.js',
+  'check-gherkin-placeholders.js',
+  'check-lifecycle-doc-drift.js',
+  'check-lifecycle-lint.js',
+  'check-schema-references.js',
+  'check-test-temp-hygiene.js',
+  'check-windows-git-perf.js',
+  'check-workflow-citations.js',
+  'check-workflow-cli-lint.js',
+  'check-workflow-timeouts.js',
+  'cleanup-repo-test-temp.js',
+  'coverage-capture.js',
+  'deliver-light.js',
+  'deliver-recover.js',
+  'diagnose-friction.js',
+  'diagnose.js',
+  'drain-pending-cleanup.js',
+  'evidence-gate.js',
+  'generate-config-docs.js',
+  'generate-lens-checklists.js',
+  'generate-lifecycle-docs.js',
+  'generate-skills-index.js',
+  'generate-workflows-doc.js',
+  'git-cleanup.js',
+  'install-matrix-assert.js',
+  'lint-baseline.js',
+  'lint-issue-body.js',
+  'lint-label-vocabulary.js',
+  'mandrel-update-preflight.js',
+  'nav-registry-diff.js',
+  'notify.js',
+  'plan-context.js',
+  'plan-critics.js',
+  'plan-persist.js',
+  'plan-run-epilogue.js',
+  'post-structured-comment.js',
+  'pr-watch-with-update.js',
+  'provision-git-hooks.js',
+  'quality-preview.js',
+  'quality-watch.js',
+  'resolve-doc-tiers.js',
+  'resolve-stories.js',
+  'resync-status-column.js',
+  'run-coverage.js',
+  'run-lint.js',
+  'run-test-profile.js',
+  'run-tests.js',
+  'run-verify.js',
+  'signals-view.js',
+  'single-story-close.js',
+  'single-story-confirm-merge.js',
+  'single-story-init.js',
+  'stories-wave-tick.js',
+  'story-plan.js',
+  'sync-agentrc.js',
+  'sync-branch-from-base.js',
+  'sync-claude-agents.js',
+  'sync-claude-commands.js',
+  'test-isolate.js',
+  'test-wrapper.js',
+  'update-coverage-baseline.js',
+  'update-crap-baseline.js',
+  'update-duplication-baseline.js',
+  'update-maintainability-baseline.js',
+  'update-ticket-state.js',
+  'validate-docs-freshness.js',
+  'validate-skills.js',
+]);
+
+/**
+ * Membership index over {@link FRAMEWORK_SCRIPT_BASENAMES}, built once at
+ * module load so the per-signal scan is a hash lookup.
+ *
+ * @type {ReadonlySet<string>}
+ */
+const FRAMEWORK_SCRIPT_BASENAME_SET = new Set(FRAMEWORK_SCRIPT_BASENAMES);
+
+/**
+ * Characters a shell-ish command line can wrap a token in. Stripped from both
+ * ends before the membership test so `"acceptance-eval.js",` still resolves.
+ *
+ * @type {RegExp}
+ */
+const TOKEN_TRIM = /^[\s'"`(,;:]+|[\s'"`),;:]+$/g;
+
 /**
  * Normalise a value to a string for prefix scanning. Anything that is not
  * a string (undefined, null, numbers, objects) becomes the empty string,
@@ -78,6 +208,44 @@ function containsFrameworkPrefix(haystack) {
   return false;
 }
 
+/**
+ * Return true when `haystack` names a top-level framework script by **bare
+ * basename** — no path segment at all (Story #4916).
+ *
+ * Whitespace-tokenised and matched whole: only a token that *equals* a known
+ * basename counts. A token carrying any path segment is deliberately left to
+ * {@link containsFrameworkPrefix} — `./tools/notify.js` is the consumer's own
+ * script and must stay `consumer`, while `.agents/scripts/notify.js` already
+ * matches a prefix. Likewise `my-notify.js` is not `notify.js`.
+ *
+ * @param {string} haystack
+ * @returns {boolean}
+ */
+function containsFrameworkScriptBasename(haystack) {
+  if (haystack.length === 0) return false;
+  for (const rawToken of haystack.split(/\s+/)) {
+    const token = rawToken.replace(TOKEN_TRIM, '');
+    if (FRAMEWORK_SCRIPT_BASENAME_SET.has(token)) return true;
+  }
+  return false;
+}
+
+/**
+ * True when `haystack` names the framework's own surface, by either
+ * recognition route: a path prefix, or a bare framework-script basename.
+ *
+ * Purely additive over {@link containsFrameworkPrefix} — every string that
+ * matched a prefix still matches here, so widening can only ever move a
+ * classification from `consumer` to `framework`, never the reverse.
+ *
+ * @param {string} haystack
+ * @returns {boolean}
+ */
+function namesFrameworkSurface(haystack) {
+  if (containsFrameworkPrefix(haystack)) return true;
+  return containsFrameworkScriptBasename(haystack);
+}
+
 /**
  * Classify a friction signal as `"framework"` or `"consumer"`.
  *
@@ -92,6 +260,10 @@ function containsFrameworkPrefix(haystack) {
  * `node .agents/scripts/single-story-init.js` — that's framework friction even
  * though the failing test path lives under the consumer.
  *
+ * Either input matches on a framework path prefix **or** on a bare framework
+ * script basename (Story #4916), so `single-story-close.js --story 4906` is
+ * recognised exactly like its fully-pathed spelling.
+ *
  * @param {unknown} failingPath  The path of the file or directory the
  *                               signal blames (e.g. `"tests/foo.test.js"`).
  * @param {unknown} command       The command line the signal blames
@@ -101,8 +273,8 @@ function containsFrameworkPrefix(haystack) {
 export function classifyPathSource(failingPath, command) {
   const path = toScanString(failingPath);
   const cmd = toScanString(command);
-  if (containsFrameworkPrefix(path)) return 'framework';
-  if (containsFrameworkPrefix(cmd)) return 'framework';
+  if (namesFrameworkSurface(path)) return 'framework';
+  if (namesFrameworkSurface(cmd)) return 'framework';
   return 'consumer';
 }
 
@@ -229,5 +401,6 @@ export function classifySignalSource(record) {
 
 export const __testing = Object.freeze({
   FRAMEWORK_PREFIXES,
+  FRAMEWORK_SCRIPT_BASENAMES,
   TOOL_DEGRADED_CATEGORY,
 });

package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js

@@ -17,6 +17,20 @@
  * from the cap enforcement path — a critic that always reports `round: 1`
  * can no longer defeat the bounded-loop guarantee.
  *
+ * ## Reading a verdict is not a round (Story #4874)
+ *
+ * Counting signals made *observation* costly: re-running the gate over an
+ * already-scored verdict — a resumed sub-agent re-reading its own verdict,
+ * an operator re-checking why the loop said `redraft` — appended another
+ * signal and advanced the derived round, so a `redraft` could escalate to
+ * `block` with no work in between. Every appended signal therefore carries
+ * a `details.verdictFingerprint` content-addressing the verdict it scored,
+ * and {@link resolveAcceptanceEvalRound} replays the round already recorded
+ * for that fingerprint instead of minting a new one. A replay is observably
+ * free: the round does not advance and no signal is appended. New work
+ * produces different verdict content, hence a new fingerprint, hence a
+ * genuine round.
+ *
  * ## The three terminal actions
  *
  *   - `proceed`  — every criterion is `met`. The Story may flip to
@@ -39,6 +53,7 @@
  * possible action is `block`.
  */
 
+import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 
 import { runArtifactPath, signalsFile } from '../config/temp-paths.js';
@@ -112,7 +127,7 @@ function partitionCriteria(criteria) {
  *   The resolved (already-clamped) redraft ceiling from
  *   `getAcceptanceEval(config).maxRounds`.
  * @param {number} [args.round]
- *   The current round number, derived via `deriveAcceptanceEvalRound`.
+ *   The current round number, derived via `resolveAcceptanceEvalRound`.
  *   Defaults to 1 when absent or invalid.
  * @returns {{
  *   decision: 'proceed' | 'redraft' | 'block',
@@ -172,6 +187,7 @@ export function buildAcceptanceEvalSignal({
   outcome,
   phase = 'implement',
   clusterId = null,
+  verdictFingerprint = null,
 }) {
   return {
     kind: 'acceptance-eval',
@@ -186,6 +202,13 @@ export function buildAcceptanceEvalSignal({
     phase,
     emitter: { tool: 'acceptance-eval.js' },
     details: {
+      // Content address of the verdict this signal scored. The replay guard
+      // in `resolveAcceptanceEvalRound` matches on it, so a re-read of an
+      // already-scored verdict reuses its round instead of minting one.
+      ...(typeof verdictFingerprint === 'string' &&
+      verdictFingerprint.length > 0
+        ? { verdictFingerprint }
+        : {}),
       decision: outcome.decision,
       round: outcome.round,
       cap: outcome.cap,
@@ -201,29 +224,29 @@ export function buildAcceptanceEvalSignal({
 }
 
 /**
- * Derive the current acceptance-eval round for a Story by counting the
- * `acceptance-eval` signals already appended to the Story's
- * `signals.ndjson` (Story #4019). Round = prior-signal count + 1, so the
- * first run reports round 1 and each completed round (which appends one
- * signal via `acceptance-eval.js`) advances the derived round by one.
+ * Read the `acceptance-eval` records already appended to the Story's (or AC
+ * cluster's) `signals.ndjson`, in append order — the prior rounds
+ * {@link resolveAcceptanceEvalRound} counts from (Story #4019).
  *
- * The derivation is restart-safe: the ledger lives on disk, so a subagent
- * that dies mid-loop and restarts still observes every prior round. A
- * missing or malformed ledger degrades to round 1 (no prior rounds), and
- * malformed lines are skipped — observability corruption never wedges the
- * gate.
+ * The read is restart-safe: the ledger lives on disk, so a subagent that
+ * dies mid-loop and restarts still observes every prior round. A missing or
+ * unreadable ledger degrades to "no prior rounds" and malformed lines are
+ * skipped — observability corruption never wedges the gate.
  *
  * @param {object} args
  * @param {number|null} args.epicId   Parent Epic ID, or `null` for a
  *   standalone Story (routes to `<tempRoot>/standalone/stories/...`).
  * @param {number} args.storyId
+ * @param {string|null} [args.clusterId] AC-cluster id (Epic #4475 M4-B).
  * @param {object} [args.config]      Resolved config (tempRoot resolution).
  * @param {(p: string) => string} [args.readFile]  Injectable reader (tests).
  * @param {(eid: number|null, sid: number, config?: object) => string} [args.signalsPathResolver]
  *   Injectable path resolver (tests). Defaults to `signalsFile`.
- * @returns {number} The 1-based current round.
+ * @param {(eid: number, config?: object) => string} [args.epicSignalsPathResolver]
+ *   Injectable epic-stream path resolver (tests).
+ * @returns {object[]} The matching records, oldest first.
  */
-export function deriveAcceptanceEvalRound({
+function readPriorAcceptanceEvalRecords({
   epicId,
   storyId,
   clusterId = null,
@@ -249,10 +272,10 @@ export function deriveAcceptanceEvalRound({
       : readFile(signalsPathResolver(epicId ?? null, storyId, config));
   } catch (_err) {
     // No ledger yet → no prior rounds.
-    return 1;
+    return [];
   }
 
-  let priorRounds = 0;
+  const records = [];
   for (const line of String(text).split('\n')) {
     const trimmed = line.trim();
     if (trimmed === '') continue;
@@ -269,7 +292,77 @@ export function deriveAcceptanceEvalRound({
     } else if (record.storyId !== storyId) {
       continue;
     }
-    priorRounds += 1;
+    records.push(record);
   }
-  return priorRounds + 1;
+  return records;
+}
+
+/**
+ * Content-address a verdict so re-scoring the same verdict is recognisable
+ * as a re-read rather than a new round (Story #4874).
+ *
+ * The fingerprint covers exactly what the decision depends on — the ordered
+ * per-criterion `index` / `criterion` / `verdict` / `evidence` tuples — and
+ * deliberately nothing else: the verdict's self-reported `round`, its
+ * timestamp, and any authoring scratch must not make an unchanged
+ * evaluation look like a new one. Conversely, real rework changes at least
+ * one criterion's verdict or its evidence, so a genuine re-evaluation
+ * always fingerprints differently.
+ *
+ * @param {{ criteria?: Array<object> }} verdict
+ * @returns {string} 16 hex chars of a SHA-256 over the canonical form.
+ */
+export function computeVerdictFingerprint(verdict) {
+  const criteria = Array.isArray(verdict?.criteria) ? verdict.criteria : [];
+  const canonical = criteria.map((c) => [
+    Number.isInteger(c?.index) ? c.index : null,
+    typeof c?.criterion === 'string' ? c.criterion : '',
+    typeof c?.verdict === 'string' ? c.verdict : '',
+    typeof c?.evidence === 'string' ? c.evidence : '',
+  ]);
+  return createHash('sha256')
+    .update(JSON.stringify(canonical))
+    .digest('hex')
+    .slice(0, 16);
+}
+
+/**
+ * Resolve the round a verdict should be scored under, distinguishing a
+ * genuine evaluation from a re-read of an already-scored verdict
+ * (Story #4874). A genuine round is `prior-signal count + 1`, so the first
+ * run reports round 1 and each completed round advances it by one.
+ *
+ * When the ledger already carries an `acceptance-eval` signal whose
+ * `details.verdictFingerprint` matches, this invocation is a **replay**: it
+ * reports that signal's round and tells the caller not to append a second
+ * one, so reading is observably free and cannot escalate a `redraft` into a
+ * `block`. Otherwise it is a genuine round and the counter advances exactly
+ * as the pre-#4874 count-based derivation always did.
+ *
+ * Signals written before this field existed carry no fingerprint; they can
+ * never match, so legacy ledgers keep their count-based behaviour.
+ *
+ * @param {object} args — {@link readPriorAcceptanceEvalRecords}'s arguments
+ *   plus:
+ * @param {string} args.verdictFingerprint
+ * @returns {{ round: number, replay: boolean }}
+ */
+export function resolveAcceptanceEvalRound(args) {
+  const { verdictFingerprint } = args;
+  const records = readPriorAcceptanceEvalRecords(args);
+  const priorIndex =
+    typeof verdictFingerprint === 'string' && verdictFingerprint.length > 0
+      ? records.findIndex(
+          (r) => r?.details?.verdictFingerprint === verdictFingerprint,
+        )
+      : -1;
+  if (priorIndex === -1) {
+    return { round: records.length + 1, replay: false };
+  }
+  const recorded = records[priorIndex]?.details?.round;
+  return {
+    round:
+      Number.isInteger(recorded) && recorded >= 1 ? recorded : priorIndex + 1,
+    replay: true,
+  };
 }

package/.agents/scripts/lib/orchestration/ceremony-routing.js

@@ -78,7 +78,7 @@
  * @typedef {'fresh'|'inline'} CeremonyMode
  * @typedef {'fresh-critic'|'inline-self-eval'} VerdictOwner
  * @typedef {import('./review-depth.js').ChangeLevel} ChangeLevel
- * @typedef {'minimal'|'standard'|'strict'} CeremonyProfile
+ * @typedef {(typeof CEREMONY_PROFILES)[number]} CeremonyProfile
  */
 
 /**
@@ -93,12 +93,18 @@ export function verdictOwnerForMode(mode) {
   return mode === 'fresh' ? 'fresh-critic' : 'inline-self-eval';
 }
 
-/** @type {readonly CeremonyProfile[]} */
-export const CEREMONY_PROFILES = Object.freeze([
-  'minimal',
-  'standard',
-  'strict',
-]);
+/**
+ * The ceremony-profile vocabulary — the **single** place the three profile
+ * names are written. `normalizeCeremonyProfile` is its reader and the
+ * `CeremonyProfile` typedef is derived from it, so adding a profile is a
+ * one-line change here (Story #4926).
+ *
+ * @type {readonly ['minimal', 'standard', 'strict']}
+ */
+const CEREMONY_PROFILES = Object.freeze(['minimal', 'standard', 'strict']);
+
+/** The profile an absent or unrecognized value degrades to. */
+const DEFAULT_CEREMONY_PROFILE = 'standard';
 
 /**
  * Normalize an operator/config ceremony profile. Unknown values degrade to
@@ -107,11 +113,10 @@ export const CEREMONY_PROFILES = Object.freeze([
  * @param {unknown} value
  * @returns {CeremonyProfile}
  */
-export function normalizeCeremonyProfile(value) {
-  if (value === 'minimal' || value === 'standard' || value === 'strict') {
-    return value;
-  }
-  return 'standard';
+function normalizeCeremonyProfile(value) {
+  return CEREMONY_PROFILES.includes(/** @type {CeremonyProfile} */ (value))
+    ? /** @type {CeremonyProfile} */ (value)
+    : DEFAULT_CEREMONY_PROFILE;
 }
 
 /**