@dzhechkov/harness-core 0.8.36 → 0.8.38

package/src/feature-adr-envelope.ts

@@ -0,0 +1,242 @@
+/**
+ * The experiment envelope (ADR-001, experiment-envelope). Pure data, built ONCE per run right after
+ * the Step-0 router and before Step 1, then carried unchanged into every autorow the pipeline writes
+ * (the run-cost ledger, training pairs, the round state). It answers two questions the pipeline used
+ * to leave unanswered: what STRATUM was this run (task kind, tier, priority) and what DECISION did
+ * routing make (which arms were considered, which one was chosen, by which policy, evaluated by whom).
+ *
+ * D1 (ADR-001): collecting these fields per-writer let three sources disagree — `mode` and `runId`
+ * already drifted across the ledger (133/343 and 34/343 respectively, MEASURED in Step 0). Building
+ * the envelope once and threading the same object through every writer removes that class of drift
+ * by construction.
+ */
+
+export const ENVELOPE_SCHEMA = 1 as const;
+
+export const TASK_KINDS = ['feature', 'bugfix', 'refactor', 'tooling', 'docs', 'research'] as const;
+export type TaskKind = typeof TASK_KINDS[number];
+
+export const PRIORITIES = ['speed', 'balance', 'quality', 'unset'] as const;
+export type EnvelopePriority = typeof PRIORITIES[number];
+
+export const TIERS = ['S', 'M', 'L', 'XL'] as const;
+export type EnvelopeTier = typeof TIERS[number];
+
+export interface ExperimentEnvelopeArms {
+  readonly mode: readonly string[];
+  readonly stages: Readonly<Record<string, readonly string[]>>;
+}
+
+export interface ExperimentEnvelopeChosen {
+  readonly mode: string;
+  readonly stages: Readonly<Record<string, string>>;
+  /** Lead delta after Codex r2 (HIGH): a stage whose chosen spec was NOT among the offered arms
+   * (usage-override, session-inherited fallback) is recorded HERE explicitly — arms stay the set that
+   * was actually offered; the winner is never appended to them after the fact. */
+  readonly overrides?: Readonly<Record<string, string>>;
+}
+
+export interface ExperimentEnvelopePolicy {
+  readonly name: string;
+  readonly version: string;
+  readonly propensity: number | null;
+}
+
+export interface ExperimentEnvelopeEvaluator {
+  readonly family: 'claude' | 'codex' | null;
+  readonly model: string | null;
+  readonly source: 'planned' | 'actual';
+}
+
+export interface ExperimentEnvelope {
+  readonly schema: 1;
+  readonly runId: string;
+  /**
+   * fix-round-1/F4: `null` when the persistent `.fa-state/attempt` counter probe failed — never a
+   * fabricated guess (the old `resumedStages.length > 0 ? 2 : 1` heuristic silently reported "2" for
+   * every third-and-later retry). Mirrors the `treeSha`/`treeShaReason` null+reason shape below.
+   */
+  readonly attempt: number | null;
+  /** Required (non-empty) exactly when `attempt` is null; null whenever `attempt` is a real count. */
+  readonly attemptReason: string | null;
+  readonly taskKind: TaskKind;
+  readonly tier: EnvelopeTier;
+  readonly priority: EnvelopePriority;
+  readonly treeSha: string | null;
+  readonly treeShaReason: string | null;
+  readonly arms: ExperimentEnvelopeArms;
+  readonly chosen: ExperimentEnvelopeChosen;
+  readonly policy: ExperimentEnvelopePolicy;
+  readonly evaluator: ExperimentEnvelopeEvaluator;
+}
+
+export interface BuildExperimentEnvelopeInput {
+  readonly runId: string;
+  readonly attempt: number | null;
+  readonly attemptReason?: string | null;
+  readonly taskKind: TaskKind;
+  readonly tier: EnvelopeTier;
+  readonly priority: EnvelopePriority;
+  readonly treeSha: string | null;
+  readonly treeShaReason?: string | null;
+  readonly arms: ExperimentEnvelopeArms;
+  readonly chosen: ExperimentEnvelopeChosen;
+  readonly policy: ExperimentEnvelopePolicy;
+  readonly evaluator: ExperimentEnvelopeEvaluator;
+}
+
+/**
+ * Assembles the normalized envelope object from already-resolved inputs. This function does not
+ * derive routing decisions itself (the caller — the Step-0-adjacent block in the workflow — resolves
+ * `arms`/`chosen`/`evaluator` from the routing tables); it only shapes the result consistently and
+ * fills the one field that has a computed default: `treeShaReason` is populated only when `treeSha`
+ * is null, and cleared when it is not.
+ */
+export function buildExperimentEnvelope(input: BuildExperimentEnvelopeInput): ExperimentEnvelope {
+  return {
+    schema: ENVELOPE_SCHEMA,
+    runId: input.runId,
+    attempt: input.attempt,
+    attemptReason: input.attempt === null ? (input.attemptReason ?? 'unavailable') : null,
+    taskKind: input.taskKind,
+    tier: input.tier,
+    priority: input.priority,
+    treeSha: input.treeSha,
+    treeShaReason: input.treeSha === null ? (input.treeShaReason ?? 'unavailable') : null,
+    arms: { mode: [...input.arms.mode], stages: { ...input.arms.stages } },
+    chosen: { mode: input.chosen.mode, stages: { ...input.chosen.stages }, overrides: { ...(input.chosen.overrides ?? {}) } },
+    policy: { ...input.policy },
+    evaluator: { ...input.evaluator },
+  };
+}
+
+const HEX40 = /^[0-9a-f]{40}$/i;
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function isNonEmptyString(v: unknown): v is string {
+  return typeof v === 'string' && v.trim() !== '';
+}
+
+/**
+ * Validates an envelope value field by field, IN ORDER, and returns the FIRST invalid field by name
+ * (never a batch of errors — the refusal channel this feeds, `run-records.ts` FR-5, prints one reason
+ * line and that line must name something actionable).
+ */
+export function validateExperimentEnvelope(value: unknown): { ok: true } | { ok: false; reason: string } {
+  if (!isPlainObject(value)) return { ok: false, reason: 'envelope: expected an object' };
+  const v = value;
+
+  if (v.schema !== ENVELOPE_SCHEMA) {
+    return { ok: false, reason: `schema: expected ${ENVELOPE_SCHEMA}, got ${JSON.stringify(v.schema)}` };
+  }
+  if (!isNonEmptyString(v.runId)) {
+    return { ok: false, reason: 'runId: expected a non-empty string' };
+  }
+  if (v.attempt !== null) {
+    if (typeof v.attempt !== 'number' || !Number.isInteger(v.attempt) || v.attempt < 1) {
+      return { ok: false, reason: 'attempt: expected an integer >= 1 or null' };
+    }
+  } else if (!isNonEmptyString(v.attemptReason)) {
+    return { ok: false, reason: 'attemptReason: required (non-empty) when attempt is null' };
+  }
+  if (typeof v.taskKind !== 'string' || !(TASK_KINDS as readonly string[]).includes(v.taskKind)) {
+    return { ok: false, reason: `taskKind: expected one of ${TASK_KINDS.join('|')}, got ${JSON.stringify(v.taskKind)}` };
+  }
+  if (typeof v.tier !== 'string' || !(TIERS as readonly string[]).includes(v.tier)) {
+    return { ok: false, reason: `tier: expected one of ${TIERS.join('|')}, got ${JSON.stringify(v.tier)}` };
+  }
+  if (typeof v.priority !== 'string' || !(PRIORITIES as readonly string[]).includes(v.priority)) {
+    return { ok: false, reason: `priority: expected one of ${PRIORITIES.join('|')}, got ${JSON.stringify(v.priority)}` };
+  }
+  if (v.treeSha !== null) {
+    if (typeof v.treeSha !== 'string' || !HEX40.test(v.treeSha)) {
+      return { ok: false, reason: 'treeSha: expected 40 hex chars or null' };
+    }
+  } else if (!isNonEmptyString(v.treeShaReason)) {
+    return { ok: false, reason: 'treeShaReason: required (non-empty) when treeSha is null' };
+  }
+
+  if (!isPlainObject(v.arms)) return { ok: false, reason: 'arms: expected an object' };
+  const arms = v.arms;
+  if (!Array.isArray(arms.mode) || arms.mode.length === 0 || !arms.mode.every((m) => isNonEmptyString(m))) {
+    return { ok: false, reason: 'arms.mode: expected a non-empty array of non-empty strings' };
+  }
+  const armsMode = arms.mode as readonly string[];
+  if (!isPlainObject(arms.stages)) return { ok: false, reason: 'arms.stages: expected an object' };
+  const armsStageEntries = Object.entries(arms.stages);
+  if (armsStageEntries.length === 0) return { ok: false, reason: 'arms.stages: expected at least one stage' };
+  for (const [stage, specs] of armsStageEntries) {
+    // F7: an empty stage NAME (a real, if odd, JS object key) is refused too — a stage nobody can
+    // name is a stage nobody can dispatch to member-check against.
+    if (stage.trim() === '') return { ok: false, reason: 'arms.stages: stage name must not be empty' };
+    if (!Array.isArray(specs) || specs.length === 0 || !specs.every((s) => isNonEmptyString(s))) {
+      return { ok: false, reason: `arms.stages.${stage}: expected a non-empty array of non-empty strings` };
+    }
+  }
+
+  if (!isPlainObject(v.chosen)) return { ok: false, reason: 'chosen: expected an object' };
+  const chosen = v.chosen;
+  if (!isNonEmptyString(chosen.mode)) return { ok: false, reason: 'chosen.mode: expected a non-empty string' };
+  // F7 (fix-round-1): a valid-SHAPED row can still describe an IMPOSSIBLE decision — `chosen.mode`
+  // naming an option `arms.mode` never offered, or a stage's chosen spec absent from what that
+  // stage's own arms offered. Membership is checked AFTER shape, so a shape error is still reported
+  // first (the more actionable message).
+  if (!armsMode.includes(chosen.mode)) {
+    return { ok: false, reason: `chosen.mode: "${chosen.mode}" is not a member of arms.mode (${armsMode.join('|')})` };
+  }
+  if (!isPlainObject(chosen.stages)) return { ok: false, reason: 'chosen.stages: expected an object' };
+  const chosenStageEntries = Object.entries(chosen.stages);
+  if (chosenStageEntries.length === 0) return { ok: false, reason: 'chosen.stages: expected at least one stage' };
+  for (const [stage, spec] of chosenStageEntries) {
+    if (stage.trim() === '') return { ok: false, reason: 'chosen.stages: stage name must not be empty' };
+    if (!isNonEmptyString(spec)) return { ok: false, reason: `chosen.stages.${stage}: expected a non-empty string` };
+  }
+  const armsStageNames = new Set(Object.keys(arms.stages as Record<string, unknown>));
+  const chosenStageNames = new Set(Object.keys(chosen.stages as Record<string, unknown>));
+  if (armsStageNames.size !== chosenStageNames.size || ![...armsStageNames].every((s) => chosenStageNames.has(s))) {
+    return { ok: false, reason: 'chosen.stages: stage set disagrees with arms.stages' };
+  }
+  const armsStages = arms.stages as Record<string, readonly string[]>;
+  // Lead delta after Codex r2 (HIGH): arms are IMMUTABLE — the offered set. A chosen spec outside it is
+  // legal only when `chosen.overrides` names that stage with the SAME spec (an explicit, auditable
+  // "chosen outside the offered arms"), never by appending the winner to arms after the fact.
+  const overridesRaw = chosen.overrides === undefined ? {} : chosen.overrides;
+  if (!isPlainObject(overridesRaw)) return { ok: false, reason: 'chosen.overrides: expected an object when present' };
+  const overrides = overridesRaw as Record<string, unknown>;
+  for (const [stage, spec] of Object.entries(overrides)) {
+    if (!(stage in (chosen.stages as Record<string, unknown>))) return { ok: false, reason: `chosen.overrides.${stage}: names a stage absent from chosen.stages` };
+    if (!isNonEmptyString(spec)) return { ok: false, reason: `chosen.overrides.${stage}: expected a non-empty string` };
+    if ((chosen.stages as Record<string, unknown>)[stage] !== spec) return { ok: false, reason: `chosen.overrides.${stage}: "${String(spec)}" disagrees with chosen.stages.${stage}` };
+  }
+  for (const [stage, spec] of chosenStageEntries) {
+    const offered = armsStages[stage]!;
+    if (!offered.includes(spec as string) && overrides[stage] !== spec) {
+      return { ok: false, reason: `chosen.stages.${stage}: "${String(spec)}" is not a member of arms.stages.${stage} (${offered.join('|')}) and not declared in chosen.overrides` };
+    }
+  }
+
+  if (!isPlainObject(v.policy)) return { ok: false, reason: 'policy: expected an object' };
+  const policy = v.policy;
+  if (!isNonEmptyString(policy.name)) return { ok: false, reason: 'policy.name: expected a non-empty string' };
+  if (!isNonEmptyString(policy.version)) return { ok: false, reason: 'policy.version: expected a non-empty string' };
+  if (policy.propensity !== null && typeof policy.propensity !== 'number') {
+    return { ok: false, reason: 'policy.propensity: expected a number or null' };
+  }
+
+  if (!isPlainObject(v.evaluator)) return { ok: false, reason: 'evaluator: expected an object' };
+  const evaluator = v.evaluator;
+  if (evaluator.family !== null && evaluator.family !== 'claude' && evaluator.family !== 'codex') {
+    return { ok: false, reason: 'evaluator.family: expected claude, codex, or null' };
+  }
+  if (evaluator.model !== null && typeof evaluator.model !== 'string') {
+    return { ok: false, reason: 'evaluator.model: expected a string or null' };
+  }
+  if (evaluator.source !== 'planned' && evaluator.source !== 'actual') {
+    return { ok: false, reason: 'evaluator.source: expected planned or actual' };
+  }
+
+  return { ok: true };
+}

package/src/feature-adr-routing.ts

@@ -259,6 +259,57 @@ export function budgetPresetName(axis: BudgetAxis): 'normal' | 'eco' | 'hybrid'
   return null;
 }
 
+/**
+ * `args.priority` — a LABEL for the run's learning stratum (ADR-001 D3), applied as a preset one
+ * level ABOVE `budget`/`deliveryGate`: an explicit knob always wins. `speed` trades quality for
+ * cost; `quality` turns on the delivery gate; `balance` is today's default made nameable. Not yet a
+ * full selector (no calibration data) — see the ADR for what is deliberately out of scope.
+ */
+export type PriorityName = 'speed' | 'balance' | 'quality';
+export type EnvelopePriorityValue = PriorityName | 'unset';
+export interface PriorityPreset {
+  readonly budget: 'normal' | 'eco';
+  readonly deliveryGate: boolean;
+}
+
+export const PRIORITY_PRESETS: Record<PriorityName, PriorityPreset> = {
+  speed: { budget: 'eco', deliveryGate: false },
+  balance: { budget: 'normal', deliveryGate: false },
+  quality: { budget: 'normal', deliveryGate: true },
+};
+
+/** Unknown values return a named `{error}` rather than silently collapsing to `'unset'` (FR-4). */
+export function resolvePriority(raw: unknown): EnvelopePriorityValue | { readonly error: string } {
+  // fix-round-1/F5: the literal string 'unset' is accepted as an explicit "not set" — the SAME
+  // result as the argument being absent. Before this fix the error message listed 'unset' among the
+  // valid values while passing exactly that string was refused (a self-contradicting error).
+  if (raw === undefined || raw === null || raw === 'unset') return 'unset';
+  if (typeof raw === 'string' && Object.prototype.hasOwnProperty.call(PRIORITY_PRESETS, raw)) {
+    return raw as PriorityName;
+  }
+  const valid = Object.keys(PRIORITY_PRESETS).join('|') + '|unset';
+  return { error: 'priority: unknown "' + String(raw) + '" — valid: ' + valid };
+}
+
+/**
+ * Applies the priority preset UNDER explicit `budget`/`deliveryGate` knobs — an explicit value
+ * always wins, the preset only fills what the caller left unspecified. `routingRequested` reports
+ * whether a non-`unset` priority alone should turn routing on (NFR-1: without `args.priority` this
+ * stays `false`, byte-identical to today).
+ */
+export function applyPriorityPreset(
+  priority: EnvelopePriorityValue,
+  explicit: { readonly budget?: unknown; readonly deliveryGate?: unknown },
+): { readonly budget: unknown; readonly deliveryGate: unknown; readonly routingRequested: boolean } {
+  if (priority === 'unset') {
+    return { budget: explicit.budget, deliveryGate: explicit.deliveryGate, routingRequested: false };
+  }
+  const preset = PRIORITY_PRESETS[priority];
+  const budget = explicit.budget !== undefined ? explicit.budget : preset.budget;
+  const deliveryGate = explicit.deliveryGate !== undefined ? explicit.deliveryGate : preset.deliveryGate;
+  return { budget, deliveryGate, routingRequested: true };
+}
+
 /** The Claude model names the Workflow runtime accepts as `agent()` `model`. */
 export const CLAUDE_NAMES: Record<string, number> = { fable: 1, opus: 1, sonnet: 1, haiku: 1 };
 
@@ -1998,7 +2049,12 @@ export function scopedQePrompt(input: ScopedQePromptInput): string {
   if (slug !== '') out += ' They are the changed files of feature ' + slug + '.';
   out += '\n\nAnswer these ' + questions.length + ' questions about them:\n';
   for (let i = 0; i < questions.length; i++) out += i + 1 + '. ' + questions[i] + '\n';
-  out += '\nFinish with a single final line: Grade: <A|B|C|D>';
+  // qe-findings-record fix-round-1 finding 8: this is the mirror `export function scopedQePrompt`
+  // of the SAME function inlined in `.claude/workflows/feature-adr.js` (and its byte-identical twin)
+  // — the pipeline gained the QE-VERDICT tail so `dz score`/`dz recap` can read a Codex-graded run
+  // machine-readably, and this mirror had drifted (still asking for only `Grade:`). Text pinned
+  // identical to the pipeline by test/codex-scoped-review.test.ts and test/qe-findings-wiring.test.ts.
+  out += '\nFinish with two final lines: Grade: <A|B|C|D> and QE-VERDICT: <same>';
   return out;
 }
 
@@ -2134,7 +2190,11 @@ export function gradeFromReviewFindings(findings: readonly CodexQeFinding[] | nu
  * The LOCKED decline taxonomy. A `kind` outside this set is a bug, not a new case — which is why
  * {@link codexQeDeclineReason} throws on one rather than rendering something plausible.
  */
-export const CODEX_QE_DECLINE_KINDS: readonly string[] = ['timeout', 'no-verdict', 'tool-error', 'unusable-output', 'unavailable', 'over-ceiling', 'wrong-tree'];
+// 'scope-not-established' and 'base-ref-not-established' joined the set 2026-09-17 (feature
+// codex-review-scope + its fix-round-1, finding #7): the workflow's two inline mirrors grew both
+// kinds; this export copy diverged behind them until now. Appended, never reordered — the SAME
+// order the two workflow-twin mirrors carry.
+export const CODEX_QE_DECLINE_KINDS: readonly string[] = ['timeout', 'no-verdict', 'tool-error', 'unusable-output', 'unavailable', 'over-ceiling', 'wrong-tree', 'scope-not-established', 'base-ref-not-established'];
 
 export interface ClassifyCodexQeInput {
   readonly exit?: number | null;
@@ -2294,6 +2354,12 @@ export function codexQeDeclineReason(kind: string | null | undefined, detail?: C
   if (canonical === 'over-ceiling') {
     return 'prompt is ' + chars + ' chars / unscoped — refused before dispatch';
   }
+  if (canonical === 'scope-not-established') {
+    return 'review scope NOT ESTABLISHED for uncommitted QE — ' + (d.reason === undefined || d.reason === null || String(d.reason) === '' ? 'the change set could not be measured' : String(d.reason)) + ' — refusing to fall back to --uncommitted on the shared tree';
+  }
+  if (canonical === 'base-ref-not-established') {
+    return 'base ref for the isolated review scope NOT ESTABLISHED — ' + (d.reason === undefined || d.reason === null || String(d.reason) === '' ? 'the base-ref probe failed or was unparseable' : String(d.reason)) + ' — refusing to silently fall back to HEAD';
+  }
   throw new Error('codexQeDeclineReason: unknown kind ' + k);
 }
 
@@ -2504,6 +2570,13 @@ export interface PlanGateCmdOpts {
   gateScript?: string
   /** Pin the workspace root instead of resolving it live with `pwd -P` (tests; deterministic pins). */
   workspace?: string
+  /**
+   * FR-2 (ADR-001 plan-inherits-requirements): promotes C8 (01_requirements.md id coverage) from a
+   * WARN-with-count to a per-id FAIL. Opt-in per caller — the pipeline's one call site sets it; the
+   * bare/positional 3-arg form and any opts object without this field stay byte-identical to the
+   * pre-C8 command.
+   */
+  requireRequirements?: boolean
 }
 
 /** Both interpolated knobs are shell-spliced, so both get the same build-time shape check. */
@@ -2538,6 +2611,11 @@ function assertAbsoluteNoTraversal(value: unknown, knob: string): string {
 export function planCompletenessGateCmd(repo: string, featureDir: string, tier?: string | null, opts?: PlanGateCmdOpts): string {
   const q = (s: string) => "'" + String(s).replace(/'/g, "'\\''") + "'"
   const t = (typeof tier === 'string' && tier !== '') ? ' --tier=' + q(tier) : ''
+  // FR-2 (ADR-001 plan-inherits-requirements): opt-in per caller via opts.requireRequirements, not
+  // baked into every invocation — the pipeline's one call site sets it (below), so C8 (01_requirements.md
+  // coverage) is a per-id FAIL there; a caller that omits opts, or opts without the flag, is unaffected —
+  // the bare/positional form stays byte-identical to the pre-C8 command.
+  const req = (opts && opts.requireRequirements) ? ' --require-requirements' : ''
   if (opts === undefined || opts === null) {
     return 'cd ' + q(repo) + ' && node ' + q(PLAN_GATE_SCRIPT) + ' ' + q(featureDir) + t + ' 2>&1; echo K2_EXIT=$?'
   }
@@ -2561,7 +2639,7 @@ export function planCompletenessGateCmd(repo: string, featureDir: string, tier?:
     // twice and the chain silently degenerated from three candidates to two. Saying so turns a
     // puzzling duplicate into an instruction. Not verdict-shaped, so the parser anchoring is untouched.
     '[ "$C2" = "$C3" ] && echo "K2_GATE_NOTE=the workspace candidate resolved to the TARGET repo (WS==repo), so only two distinct candidates were tried; pass args.workspace or args.gateScript when the feature-adr skill is installed outside the target repo"',
-    'if [ -z "$GS" ]; then echo "K2 plan-completeness: NOT-ESTABLISHED — tooling-missing: no gate script at any candidate on the K2_GATE_TRIED line above"; echo "K2_EXIT=3"; else cd ' + q(repo) + ' && node "$GS" ' + q(featureDir) + t + ' 2>&1; echo "K2_EXIT=$?"; fi',
+    'if [ -z "$GS" ]; then echo "K2 plan-completeness: NOT-ESTABLISHED — tooling-missing: no gate script at any candidate on the K2_GATE_TRIED line above"; echo "K2_EXIT=3"; else cd ' + q(repo) + ' && node "$GS" ' + q(featureDir) + t + req + ' 2>&1; echo "K2_EXIT=$?"; fi',
   ].join('\n')
 }
 
@@ -2599,6 +2677,75 @@ export function parsePlanGateVerdict(raw: string | null | undefined): PlanGateVe
   return { verdict: byName, exit: exitCode, reason: reason, output: output }
 }
 
+/** Snapshot of a plan taken around the ONE repair round (FR-6 preservation check, plan-inherits-requirements). */
+export interface PlanSnapshot { present: boolean; len: number; cksum: number | null; headings: string[]; targets: string[] }
+
+/**
+ * FR-6 preservation check — pure halves of the plan-repair round, mirrored INLINE in
+ * `.claude/workflows/feature-adr.js` (the sandbox cannot import) and body-pinned by the drift guard in
+ * `test/feature-adr-model-routing.test.ts`. See the workflow's own comment block above these functions
+ * for the design, the Codex round-2/3 findings each one answers, and the NAMED LIMIT (task bodies are
+ * not proven preserved by any metric).
+ */
+export function shellQuote(s: string): string {
+    return "'" + String(s).replace(/'/g, "'\\''") + "'";
+}
+export function planBackupCmd(f: string): string {
+  return 'f=' + shellQuote(f) + '; if [ -f "$f" ] && [ ! -L "$f" ] && [ -s "$f" ] && [ ! -e "$f.pre-repair" ] && cp "$f" "$f.pre-repair"; then echo "BACKUP_OK"; else echo "BACKUP_FAILED"; fi'
+}
+export function planRestoreCmd(f: string): string {
+  return 'f=' + shellQuote(f) + '; if [ -f "$f.pre-repair" ] && [ ! -L "$f.pre-repair" ] && [ -s "$f.pre-repair" ] && mv "$f.pre-repair" "$f"; then echo "RESTORE_OK"; else echo "RESTORE_FAILED"; fi'
+}
+export function planArchiveBackupCmd(f: string, stateDir: string): string {
+  return 'f=' + shellQuote(f) + '; d=' + shellQuote(stateDir) + '; if [ -f "$f.pre-repair" ] && [ ! -L "$f.pre-repair" ] && mkdir -p "$d" && mv "$f.pre-repair" "$d/06_implementation_plan.pre-repair"; then echo "ARCHIVE_OK"; else echo "ARCHIVE_FAILED"; fi'
+}
+export function planSnapshotCmd(f: string): string {
+  return 'f=' + shellQuote(f) + '; if [ -f "$f" ] && [ ! -L "$f" ] && [ -s "$f" ]; then ' +
+    'len=$(wc -c < "$f" | tr -d " "); ck=$(cksum < "$f" | cut -d " " -f 1); ' +
+    'echo "SNAP_TARGETS_START"; ' +
+    'awk \'/^EXPECTED_CODE_TARGETS:/{f=1;next} f&&/^[ \\t]*[-*][ \\t]/{s=$0; sub(/^[ \\t]*[-*][ \\t]*/,"",s); sub(/[ \\t]+$/,"",s); print s; next} f&&/^[ \\t]*$/{next} f{exit}\' "$f"; ' +
+    'echo "SNAP_TARGETS_END"; ' +
+    'echo "SNAP_HEADS_START"; grep -E "^#{2,4}[[:space:]]" "$f"; echo "SNAP_HEADS_END"; ' +
+    'echo "SNAP_LEN=$len"; echo "SNAP_CKSUM=$ck"; echo "SNAP_DONE"; ' +
+    'else echo "SNAP_ABSENT"; echo "SNAP_DONE"; fi'
+}
+/** One marker-delimited block: WHOLE-LINE markers, FIRST start to LAST end (a plan line spelling a marker lands inside the block). */
+export function snapshotBlock(head: string, startMark: string, endMark: string): string[] | null {
+  const startRe = new RegExp('(^|\n)' + startMark + '(\r?\n)')
+  const sm = startRe.exec(head)
+  if (sm === null) return null
+  const s = sm.index + sm[0].length
+  const endRe = new RegExp('(^|\n)' + endMark + '(\r?\n|$)', 'g')
+  let e = -1
+  let em = endRe.exec(head)
+  while (em !== null) { e = em.index + (em[1] === '' ? 0 : 1); em = endRe.exec(head) }
+  if (e < 0 || e < s) return null
+  return head.slice(s, e).split('\n').map((l) => l.trim()).filter((l) => l !== '')
+}
+/** The LAST whole-line `<name>=<digits>` in the snapshot. */
+export function snapshotNumber(head: string, name: string): number | null {
+  const re = new RegExp('(^|\n)' + name + '=(\\d+)[ \t\r]*(\n|$)', 'g')
+  let v = null
+  let m = re.exec(head)
+  while (m !== null) { v = Number(m[2]); m = re.exec(head) }
+  return v
+}
+/** null = the probe never completed or a field is unparseable — the caller REJECTS the repair on null, never reads it as "nothing to compare". */
+export function parsePlanSnapshot(raw: string | null | undefined): PlanSnapshot | null {
+  const text = String(raw === null || raw === undefined ? '' : raw)
+  const doneIdx = text.lastIndexOf('SNAP_DONE')
+  if (doneIdx < 0) return null
+  const head = text.slice(0, doneIdx)
+  if (/(^|\n)SNAP_ABSENT[ \t\r]*\n?[ \t\r]*$/.test(head)) return { present: false, len: 0, cksum: null, headings: [], targets: [] }
+  const len = snapshotNumber(head, 'SNAP_LEN')
+  const cksum = snapshotNumber(head, 'SNAP_CKSUM')
+  if (len === null || cksum === null) return null
+  const targets = snapshotBlock(head, 'SNAP_TARGETS_START', 'SNAP_TARGETS_END')
+  const headings = snapshotBlock(head, 'SNAP_HEADS_START', 'SNAP_HEADS_END')
+  if (targets === null || headings === null) return null
+  return { present: true, len: len, cksum: cksum, headings: headings, targets: targets }
+}
+
 /**
  * The operator note a refused plan gate carries — ONE reason→text table, so the workflow's inline
  * copy cannot drift into telling an operator to fix a plan that is not broken.

package/src/feature-adr-stage-canon.ts

@@ -0,0 +1,141 @@
+/**
+ * The canonical stage taxonomy (feature `measurement-integrity`, ADR-001 D1).
+ *
+ * `cost-ledger.ts` keys its per-stage rows off `stageLabel()` output VERBATIM — deliberately, so the
+ * ledger never invents its own taxonomy (the prior feature's FR-2). That is correct for the ledger's
+ * own scope, but it leaves nothing to GROUP by: one recorded run (`wf_5a7755c7-f92`, feature-adr,
+ * 66 agents) carries 47 distinct verbatim labels (`resolve-root:1`, `runs-record:heartbeat:Design`,
+ * `requirements · sonnet`, `ckpt:write:plan`, `trainpair:code`, `ledger:append`, `score:auto`, …)
+ * against the pipeline's own 11 canonical stages (`STAGE_EFFORT.override` in `feature-adr.js`:
+ * router, requirements, research, adr, ideation, ddd, architecture, plan, code, qe, fleet). Step 0's
+ * assessment counted 48 on the same record; a live reproducer today counts 47 — the one-off
+ * difference is not chased here (it does not change which prefixes are needed), and every label the
+ * reproducer found is in {@link STAGE_LABEL_FIXTURE} below.
+ *
+ * This module adds ONE thing: a pure, ordered-rule classifier from a verbatim label to a canonical
+ * stage. It never replaces or rewrites the verbatim label — `cost-ledger.ts` stamps `stageCanonical`
+ * NEXT TO the untouched `stage` field (ADR-001 D1). An unrecognised label is `{stage:'unknown'}`,
+ * never silently folded into `infra` — a taxonomy that quietly swallows what it does not recognise
+ * would hide exactly the drift this feature exists to surface (ADR-001 rejects that alternative).
+ *
+ * PURE. No filesystem, no clock, no process — this module must never gain a `node:fs` import; the
+ * `core-boundary` ratchet (`test/core-boundary.test.ts`) pins the current count and any I/O added
+ * here would grow it.
+ *
+ * @packageDocumentation
+ */
+
+/** The pipeline's own 11 design/work stages, plus `infra` for the bookkeeping/plumbing labels that
+ *  surround them (checkpoints, run-record heartbeats, training-pair capture, the ledger writer
+ *  itself, `dz score`, `dz round`, the architecture-map refresh, …). 12 values total. */
+export const CANONICAL_STAGES = [
+  'router',
+  'requirements',
+  'research',
+  'adr',
+  'ideation',
+  'ddd',
+  'architecture',
+  'plan',
+  'code',
+  'qe',
+  'fleet',
+  'infra',
+] as const;
+
+export type CanonicalStage = (typeof CANONICAL_STAGES)[number];
+
+export interface KnownStageResult {
+  readonly stage: CanonicalStage;
+  /** The INPUT label, verbatim and unmodified — the classifier never rewrites what it classifies. */
+  readonly label: string;
+  readonly known: true;
+}
+
+export interface UnknownStageResult {
+  readonly stage: 'unknown';
+  readonly label: string;
+  readonly known: false;
+}
+
+export type StageCanonResult = KnownStageResult | UnknownStageResult;
+
+export interface StageLabelRule {
+  /** Tested against the label's PREFIX (everything before a ` · model` suffix, when present). */
+  readonly test: RegExp;
+  readonly stage: CanonicalStage;
+}
+
+/**
+ * ONE ordered table (ADR-001 D1 / C-3: "one canon table, one completeness test"). Rules are tried in
+ * order and the FIRST match wins, so a more specific rule (an exact router-time probe) must be listed
+ * before a broader prefix that would otherwise also claim it (the generic `arch-` → infra catch-all).
+ *
+ * Every entry below is justified against the 47-label fixture in
+ * `test/feature-adr-stage-canon.test.ts` (copied from the live record `wf_5a7755c7-f92`):
+ *
+ * - `router:*`, the Step-0 decision-recall receipt, and the ONE step-0 architecture-sync probe
+ *   (`arch-сverka:step0` — a Cyrillic С, copied verbatim from the label the pipeline actually emits)
+ *   are ROUTER, even though the last one would otherwise fall into the generic `arch-` infra bucket.
+ * - `design:*` is folded into `adr`: the S/M-tier pipeline runs ONE design agent that covers
+ *   ADR+ideation+DDD+architecture at once (`feature-adr-ultracode.md`'s "design-aggregate"), so its
+ *   probe labels have no separate canonical home — `adr` is the least-wrong single bucket, named here
+ *   so the choice is not silent.
+ * - `qe:baseline*` (the Step-7.5 Codex-landed barrier's baseline hash/targets check) is CODE, not QE:
+ *   it runs as part of confirming code landed, before the QE stage proper starts.
+ * - Everything else that is checkpoint/heartbeat/training-pair/ledger/score/round/architecture-map/
+ *   resolve-root/usage-probe/project-skills plumbing is INFRA — it surrounds every design/work stage
+ *   without belonging to any one of them.
+ */
+// measurement-integrity fix-round-1/F3 (Codex r1 HIGH #3): every prefix rule below is now BOUNDED —
+// the literal prefix must be followed by `:` or end-of-string (or, for the one dash-separated infra
+// catch-all, `-`) before it may match. The unbounded form (`/^requirements/`) let an unrelated,
+// never-emitted label like `requirementsBROKEN` or `code-new-stage` silently classify as a known
+// stage — exactly the silent-swallow this module's own doc comment says D1 forbids. `roundtrip` is
+// the sharpest case: the OLD infra alternation `/^(...|round)/` had no boundary at all, so any label
+// merely STARTING WITH "round" (never emitted, but never refused either) read as infra plumbing.
+// Negative fixtures for all three land in `test/feature-adr-stage-canon.test.ts`.
+export const STAGE_LABEL_RULES: readonly StageLabelRule[] = [
+  { test: /^router(?::|$)/, stage: 'router' },
+  { test: /^decision-recall:step0(?::|$)/, stage: 'router' },
+  { test: /^arch-сverka:step0$/, stage: 'router' },
+  { test: /^requirements(?::|$)/, stage: 'requirements' },
+  { test: /^research(?::|$)/, stage: 'research' },
+  { test: /^design(?::|$)/, stage: 'adr' },
+  { test: /^adr(?::|$)/, stage: 'adr' },
+  { test: /^ideation(?::|$)/, stage: 'ideation' },
+  { test: /^ddd(?::|$)/, stage: 'ddd' },
+  { test: /^architecture(?::|$)/, stage: 'architecture' },
+  { test: /^decision-recall:step6(?::|$)/, stage: 'plan' },
+  { test: /^plan(?::|$)/, stage: 'plan' },
+  // `qe:baseline-hash` / `qe:baseline-targets` use a DASH after the "qe:baseline" root (not a colon),
+  // so the boundary set here is `[-:]` or end — never a bare "qe:baselineWHATEVER" glued on.
+  { test: /^qe:baseline(?:[-:]|$)/, stage: 'code' },
+  { test: /^code(?::|$)/, stage: 'code' },
+  { test: /^probe:/, stage: 'code' },
+  { test: /^qe(?::|$)/, stage: 'qe' },
+  { test: /^fleet(?::|$)/, stage: 'fleet' },
+  { test: /^(?:resolve-root|runs-record|ckpt|usage|project-skills|trainpair|ledger|score|round)(?::|$)/, stage: 'infra' },
+  // `arch-` is the one DASH-bounded catch-all (the dash IS the boundary — `arch-map:refresh`), kept
+  // as its own rule rather than folded into the colon-bounded alternation above.
+  { test: /^arch-/, stage: 'infra' },
+];
+
+/**
+ * Classify one `stageLabel()` string. A label of the shape `requirements · sonnet` (verbatim label
+ * plus a ` · model` suffix — the shape `cost-ledger.ts` rows already carry for a mixed-model bucket)
+ * is matched on the part BEFORE ` · `; the returned `label` is always the untouched input.
+ *
+ * Never throws. A non-string or empty label is `unknown`, same as one that matches no rule.
+ */
+export function canonicalStage(label: string): StageCanonResult {
+  if (typeof label !== 'string' || label.length === 0) {
+    return { stage: 'unknown', label: typeof label === 'string' ? label : '', known: false };
+  }
+  const sepIndex = label.indexOf(' · ');
+  const base = sepIndex === -1 ? label : label.slice(0, sepIndex);
+  for (const rule of STAGE_LABEL_RULES) {
+    if (rule.test.test(base)) return { stage: rule.stage, label, known: true };
+  }
+  return { stage: 'unknown', label, known: false };
+}