@dzhechkov/harness-core 0.8.36 → 0.8.38

package/src/run-records.ts

@@ -13,7 +13,133 @@
  * Pure: payload in, verdict out. The CLI owns paths, the append, the read-back and the exit code.
  */
 
+import { matchCodexRollouts } from './codex-rollouts.js';
+import type { CodexRollout } from './codex-rollouts.js';
 import { redactTrainingPayload } from './feature-adr-checkpoints.js';
+import { validateExperimentEnvelope } from './feature-adr-envelope.js';
+
+/** Structural — a caller passes `cost-scoring.ts`'s `ModelPricing`; kept local so `run-records.ts`
+ *  does not have to import `cost-scoring.ts` just to name a type.
+ *
+ *  measurement-integrity fix-round-1/F6 (Codex r1 HIGH #6): `cacheCreation` used to be dropped here —
+ *  the snapshot silently lacked the ONE rate a cache-WRITE-heavy row needs to reproduce its own cost
+ *  later, even though the caller's own `ModelPricing` carries it. Now carried through verbatim. */
+export interface LedgerPriceEntry {
+  readonly prompt: number;
+  readonly completion: number;
+  readonly cachedInput: number;
+  readonly cacheCreation: number;
+}
+
+/** measurement-integrity fix-round-1/F4 (Codex r1 HIGH #4): a resolvable executor spec, split into
+ *  its three parts. Never invents a model: {@link parseModelSpec} returns `null` for anything it
+ *  cannot resolve to exactly one model, rather than guessing. */
+export interface ParsedModelSpec {
+  readonly family: 'claude' | 'codex';
+  readonly model: string;
+  readonly effort: string | null;
+}
+
+/** Bare Claude model names the pipeline actually emits with no `claude:` prefix (`coder: 'sonnet'`,
+ *  `'opus'`, `'fable'`, real values observed in `.dz/feature-adr/run-cost-ledger.jsonl`). */
+const BARE_CLAUDE_NAMES = new Set(['sonnet', 'opus', 'haiku', 'fable']);
+/** id/effort alphabet a model spec component may use (lead delta after Codex r2, new MEDIUM #3). */
+const SPEC_PART = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * Parse an executor spec — the shapes actually recorded in `coder`/`reviewer` fields
+ * (`codex:gpt-5.6-sol:high`, `claude:sonnet`, bare `sonnet`/`opus`, bare `codex`, bare `claude`) —
+ * into `{family, model, effort}`. Pure, never throws.
+ *
+ * Returns `null` (never a guess) for anything that cannot be resolved to exactly ONE model:
+ * - a bare `'codex'` or `'claude'` (family named, no model at all);
+ * - an annotated/aggregate field such as `'claude:sonnet x2'` or `'qe-bridge:claude x2 + lead'` (real
+ *   values this ledger carries for a MULTI-reviewer round) — any embedded whitespace means the field
+ *   names more than one resolvable spec, and picking one would misattribute to the others;
+ * - a bare model id with no family marker that is not one of the known bare Claude names (e.g. a full
+ *   `'claude-sonnet-5'` — that shape is handled by the OLDER vendor-prefix path in {@link priceLookup}
+ *   for backward compatibility, not by this parser).
+ */
+export function parseModelSpec(spec: unknown): ParsedModelSpec | null {
+  if (typeof spec !== 'string') return null;
+  const trimmed = spec.trim();
+  if (trimmed === '' || /\s/.test(trimmed)) return null;
+  const parts = trimmed.split(':');
+  const head = parts[0] ?? '';
+  if (head === 'codex') {
+    const model = parts[1];
+    if (model === undefined || model === '') return null; // bare 'codex' — no reliable model
+    // Lead delta after Codex r2 (new MEDIUM #3): exactly 2 or 3 non-empty components, id alphabet
+    // only — `codex:gpt-5.6-sol:high:garbage` is a corrupt/aggregate spec, never a reliable model.
+    if (parts.length > 3 || !SPEC_PART.test(model) || (parts.length === 3 && (parts[2] === '' || !SPEC_PART.test(parts[2]!)))) return null;
+    const effort = parts[2] ?? null;
+    return { family: 'codex', model, effort: effort === '' ? null : effort };
+  }
+  if (head === 'claude') {
+    const model = parts[1];
+    if (model === undefined || model === '') return null; // bare 'claude' — no reliable model
+    return { family: 'claude', model, effort: null };
+  }
+  if (parts.length === 1 && BARE_CLAUDE_NAMES.has(head)) {
+    return { family: 'claude', model: head, effort: null };
+  }
+  return null;
+}
+
+/** measurement-integrity FR-5/FR-6: enrichment the WRITER supplies at write time — the rollout logs
+ *  it already read (I/O lives in the CLI; this stays pure) and the price table snapshot. Absent
+ *  entirely ⇒ zero behavior change from before this feature (NFR-1). */
+export interface LedgerEnrichInput {
+  /** Parsed Codex rollout logs for the window the CLI read — usually every rollout from the days the
+   *  window spans. Pure data; the CLI is the one that walked `~/.codex/sessions`. */
+  readonly rollouts?: readonly CodexRollout[];
+  /** The stage's own time window — usually [the previous ledger row's `ts`, this write's `ts`], or
+   *  an explicit `--window-from/--window-to`. Omitted ⇒ no rollout match is even attempted. */
+  readonly window?: { readonly from: string; readonly to: string };
+  /** Narrows an otherwise-ambiguous match — usually the repo root the stage ran in. */
+  readonly cwd?: string;
+  /** A model-pricing table SNAPSHOT (FR-6) — the CALLER's table, captured at write time, never the
+   *  ledger's own idea of "current" pricing (ADR-001 D4 rejects re-pricing after the fact). */
+  readonly prices?: Readonly<Record<string, LedgerPriceEntry>>;
+}
+
+function isCodexFamily(v: unknown): boolean {
+  return typeof v === 'string' && /codex/i.test(v);
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Longest-prefix match against the CALLER'S OWN table (never `cost-scoring.ts`'s internal
+ *  constant) — the whole point of a price SNAPSHOT is that it answers only from what the caller
+ *  handed in at write time, mirroring `pricingFor`'s matching rule without importing it.
+ *
+ *  measurement-integrity fix-round-1/F7 (Codex r1 HIGH #7): the OLD version stripped only a
+ *  `vendor/`-shaped prefix, so the REAL recorded shape `codex:gpt-5.6-sol:high` (or `claude:sonnet`)
+ *  never matched anything and always landed in `prices.unknown[]`. This now runs the id through the
+ *  SAME {@link parseModelSpec} FR-4's matcher uses, then reconstructs the normalized id the way
+ *  `cost-scoring.ts`'s `pricingFor`/`hasKnownPricing` key their table (`claude-<model>` for the
+ *  Claude family; the bare model for Codex — its ids carry no vendor prefix). A spec this parser
+ *  cannot resolve falls back to the OLD vendor-prefix strip, so an already-working bare id
+ *  (`claude-sonnet-5`, `gpt-4o`) keeps matching exactly as before (NFR-1). */
+function priceLookup(modelId: string, table: Readonly<Record<string, LedgerPriceEntry>>): LedgerPriceEntry | null {
+  if (typeof modelId !== 'string' || modelId.length === 0) return null;
+  const parsed = parseModelSpec(modelId);
+  const id = parsed !== null
+    ? (parsed.family === 'claude' ? `claude-${parsed.model}` : parsed.model).toLowerCase()
+    : modelId.toLowerCase().replace(/^[a-z0-9-]+\//, '');
+  let best: LedgerPriceEntry | null = null;
+  let bestLen = 0;
+  for (const [key, price] of Object.entries(table)) {
+    const k = key.toLowerCase();
+    if (id.startsWith(k) && k.length > bestLen) {
+      best = price;
+      bestLen = k.length;
+    }
+  }
+  return best;
+}
 
 export type RecordKind = 'ledger' | 'training-pair';
 
@@ -65,7 +191,7 @@ const noop = (verdict: 'duplicate' | 'skipped', reason: string): RecordDecision
   line: null,
 });
 
-function shapeMismatch(kind: RecordKind, payload: Record<string, unknown>): string | null {
+function shapeMismatch(kind: RecordKind, payload: Record<string, unknown>, autoFlag: boolean): string | null {
   // AM-1 FIRST, before the required-field sweep. A ledger row offered as a training pair fails BOTH
   // checks, and the wrong-kind reason is the one that tells the caller what actually happened —
   // "missing field `output`" sends them looking for a field they never meant to send.
@@ -78,6 +204,39 @@ function shapeMismatch(kind: RecordKind, payload: Record<string, unknown>): stri
   if (kind === 'training-pair' && 'tokens' in payload && !('input' in payload)) {
     return 'this payload looks like a ledger row (`tokens` without `input`), not a training pair';
   }
+  // experiment-envelope FR-5 / ADR-001 D2: `auto:true` marks a pipeline-written row, and the pipeline
+  // is obligated to carry the envelope built once after the Step-0 router — a row missing it is
+  // useless for learning and would silently corrupt the sample (the "warn but write" alternative was
+  // rejected in the ADR: a warning nobody reads left `tokens=null` unnoticed for years). A MANUAL row
+  // (no `auto`) stays compatible: no envelope required, but one that IS present is still validated —
+  // never trusted just because a human typed it.
+  //
+  // fix-round-1/F2 (cross-family review, HIGH #2): the PAYLOAD's own `auto` field used to be the
+  // ONLY signal — an automatic producer that forgot it, or sent `"true"`/`false`, was silently
+  // accepted as a manual row and skipped the envelope requirement entirely. `autoFlag` is the CLI's
+  // own trusted `--auto` argument (never JSON a caller could typo): it is a SECOND, independent
+  // trust source, unioned with the payload field rather than replacing it — nothing that used to be
+  // gated stops being gated, and a `--auto`-dispatched caller is now gated even if its hand-built
+  // payload forgot the field. Independently of either source, a PRESENT `auto` field is checked for
+  // shape: only the literal `true` is a legal value — anything else (a string, `false`, a number) is
+  // refused outright, because a field whose only sane value is `true` holding something else is a
+  // caller bug worth surfacing, not silently downgrading to "manual".
+  if (kind === 'ledger') {
+    const rawAuto = payload['auto'];
+    if (rawAuto !== undefined && rawAuto !== true) {
+      return 'a ledger record\'s `auto` field must be `true` or absent';
+    }
+    const envelope = payload['envelope'];
+    const envelopePresent = envelope !== undefined && envelope !== null;
+    const isAuto = autoFlag === true || rawAuto === true;
+    if (isAuto && !envelopePresent) {
+      return 'an auto ledger row must carry `envelope` (experiment-envelope FR-5)';
+    }
+    if (envelopePresent) {
+      const v = validateExperimentEnvelope(envelope);
+      if (!v.ok) return `envelope invalid — ${v.reason}`;
+    }
+  }
   const required = kind === 'ledger' ? LEDGER_REQUIRED : PAIR_REQUIRED;
   for (const field of required) {
     const v = payload[field];
@@ -125,7 +284,16 @@ export function decideRecordWrite(input: {
   /** Who ran it. Supplied by the CALLER, which lives outside the workflow sandbox and can see the
    *  host; absent stays absent (see the stamping comment below). */
   runnerId?: string | null;
+  /** fix-round-1/F2: the CLI's own trusted `--auto` flag — see the comment inside `shapeMismatch`. */
+  auto?: boolean;
   maxChars?: number;
+  /** measurement-integrity FR-5/FR-6: rollout-log + price enrichment for a ledger row. Absent ⇒ zero
+   *  behavior change (NFR-1). */
+  enrich?: LedgerEnrichInput;
+  /** experiment-instrument FR-2/A3 (ADR-001): when `true`, an AUTO ledger row that would be written
+   *  `complete:false` is refused instead (exit 2, before any write) — a круг-B default candidate, opt-
+   *  in today so nothing that already writes incomplete auto rows starts failing underfoot (NFR-1). */
+  strict?: boolean;
 }): RecordDecision {
   const { kind, payloadRaw, stage } = input;
   if (kind !== 'ledger' && kind !== 'training-pair') {
@@ -153,7 +321,7 @@ export function decideRecordWrite(input: {
   // the read-back, the refusal texts — ever sees a byte of the profile block.
   const obj = (kind === 'training-pair' ? redactTrainingPayload(payload) : payload) as Record<string, unknown>;
 
-  const mismatch = shapeMismatch(kind, obj);
+  const mismatch = shapeMismatch(kind, obj, input.auto === true);
   if (mismatch !== null) return refuse(mismatch);
 
   // The record is filed under `--stage`, and the payload carries its own. A disagreement means the
@@ -182,6 +350,11 @@ export function decideRecordWrite(input: {
   // inside an already-serialised document — text surgery on a structured value, and the exact place
   // a payload containing that literal token could corrupt itself.
   const stamped: Record<string, unknown> = { ...obj };
+  // fix-round-1/F2: the CLI's own `--auto` flag is authoritative — when set, the written row MUST
+  // carry `auto:true` too (not just gate on it transiently), so every downstream reader of the
+  // PERSISTED line keeps seeing the same signal `shapeMismatch` already gated on above. A no-op when
+  // the payload already said `auto:true` (shapeMismatch already refused any OTHER value).
+  if (kind === 'ledger' && input.auto === true) stamped['auto'] = true;
   const isGap = (v: unknown): boolean => v === null || v === undefined || (typeof v === 'string' && v.trim() === '');
   if (input.timestamp != null && input.timestamp !== '') {
     // An EMPTY STRING is a gap, not a value. Stamping only over null/undefined let
@@ -273,6 +446,168 @@ export function decideRecordWrite(input: {
     }
   }
 
+  // measurement-integrity FR-5 (rollout enrichment) + FR-6 (price snapshot). Both are ADDITIVE and
+  // OPT-IN on `input.enrich` — a caller that never passes it gets byte-identical output to before
+  // this feature (NFR-1).
+  if (kind === 'ledger' && input.enrich !== undefined) {
+    const enrich = input.enrich;
+
+    // FR-5: only a codex-family coder/reviewer with `tokens: null` is a candidate — a Claude row, or
+    // one that already has a token figure, is left untouched. The loose `/codex/i` check below only
+    // decides whether this row is WORTH TRYING at all.
+    const tokensIsNull = stamped['tokens'] === null;
+    const looksCodexFamily = isCodexFamily(stamped['coder']) || isCodexFamily(stamped['reviewer']);
+    if (tokensIsNull && looksCodexFamily) {
+      // measurement-integrity fix-round-1/F4 (Codex r1 HIGH #4): the matcher REQUIRES a reliable
+      // model, parsed the same way FR-7's price lookup parses one — never `/codex/i` alone. If
+      // `coder`/`reviewer` do not resolve to exactly ONE codex model between them (a bare `'codex'`
+      // with no model at all, or the two fields naming DIFFERENT codex models), the matcher is never
+      // even called with an unreliable/omitted model filter — a lone rollout in the window would
+      // otherwise be accepted as `'one'` on time+cwd alone and its tokens misattributed to the wrong
+      // model's stage.
+      const codexModels = new Set(
+        [parseModelSpec(stamped['coder']), parseModelSpec(stamped['reviewer'])]
+          .filter((s): s is ParsedModelSpec => s !== null && s.family === 'codex')
+          .map((s) => s.model),
+      );
+      if (codexModels.size !== 1) {
+        stamped['tokensSource'] = 'codex-rollout:no-model';
+      } else if (enrich.window !== undefined) {
+        const model = [...codexModels][0]!;
+        const match = matchCodexRollouts(enrich.rollouts ?? [], {
+          from: enrich.window.from,
+          to: enrich.window.to,
+          model,
+          ...(enrich.cwd !== undefined ? { cwd: enrich.cwd } : {}),
+        });
+        if (match.status === 'one') {
+          stamped['tokens'] = match.rollout.totals.total;
+          const startMs = match.rollout.startedAt !== null ? Date.parse(match.rollout.startedAt) : NaN;
+          const endMs = match.rollout.endedAt !== null ? Date.parse(match.rollout.endedAt) : NaN;
+          // measurement-integrity fix-round-1/F6 (Codex r1 HIGH #6): fill-ONLY-null — an existing
+          // `minutes` figure (a manually recorded one, say) must never be silently overwritten by a
+          // derived rollout duration.
+          if (stamped['minutes'] === null && Number.isFinite(startMs) && Number.isFinite(endMs) && endMs >= startMs) {
+            stamped['minutes'] = Math.round(((endMs - startMs) / 60000) * 10) / 10;
+          }
+          stamped['tokensSource'] = 'codex-rollout';
+          stamped['rolloutId'] = match.rollout.id;
+        } else {
+          // `none` or `ambiguous` — NFR-3: an explicit status, never a guessed number.
+          stamped['tokensSource'] = `codex-rollout:${match.status}`;
+        }
+      } else {
+        // Eligible in principle (codex family, one reliable model, tokens null) but no window was
+        // supplied — AC-4's "old row without a window": no enrichment is even attempted, and that
+        // fact is itself recorded rather than left silently absent.
+        stamped['tokensSource'] = 'unavailable';
+      }
+    }
+
+    // FR-6: the price snapshot, for every model this row names — independent of the FR-5 branch
+    // above (a Claude row gets priced too; only tokens enrichment is codex-specific).
+    if (enrich.prices !== undefined) {
+      const modelIds = new Set<string>();
+      for (const v of [stamped['coder'], stamped['reviewer']]) {
+        if (typeof v === 'string' && v.trim() !== '') modelIds.add(v.trim());
+      }
+      const envelope = stamped['envelope'];
+      if (isRecord(envelope)) {
+        const chosen = envelope['chosen'];
+        if (isRecord(chosen)) {
+          const stages = chosen['stages'];
+          if (isRecord(stages)) {
+            for (const v of Object.values(stages)) {
+              if (typeof v === 'string' && v.trim() !== '') modelIds.add(v.trim());
+            }
+          }
+        }
+      }
+      const table: Record<string, LedgerPriceEntry> = {};
+      const unknown: string[] = [];
+      for (const modelId of modelIds) {
+        const price = priceLookup(modelId, enrich.prices);
+        if (price === null) unknown.push(modelId);
+        else table[modelId] = { prompt: price.prompt, completion: price.completion, cachedInput: price.cachedInput, cacheCreation: price.cacheCreation };
+      }
+      const computedPrices = {
+        snapshotAt: input.timestamp ?? null,
+        table,
+        ...(unknown.length > 0 ? { unknown } : {}),
+      };
+      // measurement-integrity fix-round-1/F6 (Codex r1 HIGH #6): fill-ONLY-null for `prices` too — an
+      // existing snapshot (a previous write already priced this row) is never unconditionally
+      // replaced. Equal → left alone (idempotent re-enrichment, common on a retried write). Different
+      // → a named `pricesConflict`, never a silent re-price (ADR-001 D4 forbids re-pricing after the
+      // fact — a DIFFERING recomputation is exactly that, so it is surfaced, not applied).
+      const existingPrices = stamped['prices'];
+      if (existingPrices === undefined || existingPrices === null) {
+        stamped['prices'] = computedPrices;
+      } else if (isRecord(existingPrices) && isRecord(existingPrices['table']) && (existingPrices['unknown'] === undefined || Array.isArray(existingPrices['unknown']))) {
+        // Lead delta after Codex r2 (new MEDIUM #4): compare the WHOLE snapshot canonically (table +
+        // sorted unknown), not the table alone.
+        const canon = (t: unknown, u: unknown): string => JSON.stringify({ table: t, unknown: Array.isArray(u) ? [...u].map(String).sort() : [] });
+        if (canon(existingPrices['table'], existingPrices['unknown']) !== canon(table, unknown)) {
+          stamped['pricesConflict'] = { existing: existingPrices, recomputed: computedPrices };
+        }
+      } else {
+        // A malformed existing snapshot (no table / bad unknown) is a CONFLICT, never silently trusted.
+        stamped['pricesConflict'] = { existing: existingPrices, recomputed: computedPrices, reason: 'existing prices snapshot is malformed' };
+      }
+    }
+  }
+
+  // experiment-instrument FR-2/A3 (ADR-001): completeness of an AUTO ledger row. `minutes` is
+  // fill-only-null from a `wallSec` the payload carries (the workflow sandbox has a clock delta even
+  // when it has no wall clock of its own — FR-2's `wallSec` field, distinct from `minutesSincePrev`
+  // above, which needs a PREVIOUS row and a runId neither of which every auto row has). `tokens` is
+  // judged complete when it is a real number OR the row already NAMES why it is not (`tokensSource`,
+  // set above by the FR-5 rollout match, or supplied by the caller) — an unexplained non-number is the
+  // one shape that is actually incomplete. Gated on `auto` only: a MANUAL row never gains any of these
+  // three keys, so it stays byte-identical to before this feature (NFR-1).
+  if (kind === 'ledger' && stamped['auto'] === true) {
+    const incompleteReasons: string[] = [];
+    if (stamped['minutes'] === null || stamped['minutes'] === undefined) {
+      const wallSec = stamped['wallSec'];
+      if (typeof wallSec === 'number' && Number.isFinite(wallSec) && wallSec >= 0) {
+        stamped['minutes'] = Math.round((wallSec / 60) * 10) / 10;
+        stamped['minutesSource'] = 'wallSec';
+      } else {
+        incompleteReasons.push('minutes');
+      }
+    }
+    // r1-10 (Codex r1 HIGH #10): completeness requires a real, finite NUMBER of tokens. Naming why
+    // tokens are missing (`tokensSource:'unavailable'`, or any other provenance) is diagnostic, never
+    // a substitute for the number itself — ADR-001 says missing tokens makes the row incomplete, full
+    // stop. The old check (`tokensSource === undefined`) treated a NAMED absence as if it were data.
+    if (typeof stamped['tokens'] !== 'number' || !Number.isFinite(stamped['tokens'])) {
+      incompleteReasons.push('tokens');
+    }
+    // r1-11 (Codex r1 MEDIUM #11): a payload that ALREADY declared itself incomplete (its own
+    // `complete:false` + `incompleteReasons`, e.g. a workflow-side `'artifact'` reason this module
+    // knows nothing about) must never be overwritten back to `complete:true` just because THIS
+    // module's own minutes/tokens checks both passed — that erases a true fact and leaves a
+    // contradictory row (`complete:true` alongside a stale `incompleteReasons`). Preserve and MERGE.
+    const existingCompleteRaw = stamped['complete'];
+    const existingWasIncomplete = existingCompleteRaw === false;
+    const existingReasonsRaw = stamped['incompleteReasons'];
+    const existingReasons = Array.isArray(existingReasonsRaw)
+      ? existingReasonsRaw.filter((r): r is string => typeof r === 'string')
+      : [];
+    const mergedReasons = existingWasIncomplete
+      ? [...new Set([...existingReasons, ...incompleteReasons])]
+      : incompleteReasons;
+    const complete = mergedReasons.length === 0 && !existingWasIncomplete;
+    // A3: under `--strict`, incompleteness is a REFUSAL — before any write, the target untouched —
+    // rather than a loudly-marked write. Without `--strict` (the default today; круг-B may flip it),
+    // the row is still written, just honestly marked `complete:false` with its reasons.
+    if (input.strict === true && !complete) {
+      return refuse(`auto ledger row is incomplete (${mergedReasons.join(', ') || 'previously marked incomplete'}) — refused under --strict before any write`);
+    }
+    stamped['complete'] = complete;
+    if (!complete) stamped['incompleteReasons'] = mergedReasons.length > 0 ? mergedReasons : existingReasons;
+  }
+
   let line: string;
   try {
     line = JSON.stringify(stamped);
@@ -324,3 +659,54 @@ export function decideReadBack(appended: string, lastLineOnDisk: string | null):
 export function recordVerdictLine(kind: RecordKind, stage: string, d: RecordDecision): string {
   return `feature-adr record (${kind}/${stage}): ${d.verdict.toUpperCase()} — ${d.reason}`;
 }
+
+/** experiment-instrument FR-1/FR-3 (ADR-001): what `round.ts`'s `readOpenRoundTaskId` returns — the
+ *  single source `applyTaskId` fills from. Duplicated here rather than imported so this pure module
+ *  never depends on `round.ts`'s own shape; the CLI is the one holding both and wiring them together.
+ *  r1-1/r1-2 (Codex r1 #1/#2): extended with `'derived-legacy'` and `'unavailable'` to stay in
+ *  lockstep with `round.ts`'s own `readOpenRoundTaskId` return type. */
+export interface TaskIdLookup {
+  readonly taskId: string | null;
+  readonly source: 'open-round' | 'derived-legacy' | 'no-open-round' | 'ambiguous' | 'unavailable';
+}
+
+/**
+ * experiment-instrument FR-1/FR-3/A8 (ADR-001): propagate `taskId` onto a ledger/training-pair payload
+ * BEFORE it reaches {@link decideRecordWrite} — fill-only-null, never overwritten.
+ *
+ * - The payload already names a non-empty `taskId` string ⇒ it is authoritative. When it DISAGREES
+ *   with the round's own current taskId, that disagreement is a real fact worth keeping — recorded as
+ *   `taskIdConflict: {payload, round}` — never silently resolved either way (A8).
+ * - The payload's `taskId` key is absent, or explicitly `null`/`undefined` ⇒ filled from `lookup`,
+ *   INCLUDING the honest `null` case: no open round (A4) or two of them (A5) still stamps `taskId:
+ *   null` + `taskIdSource` naming why, rather than leaving the field silently absent — absence with a
+ *   named reason beats absence with none.
+ * - r1-3 (Codex r1 HIGH #3): the payload's `taskId` key is PRESENT with a value that is neither a
+ *   non-empty string nor null/undefined (a number, a boolean, an object, or a blank/whitespace-only
+ *   string) ⇒ that is a present-but-INVALID value, a THIRD case distinct from both of the above. It
+ *   used to be treated exactly like "absent" (`typeof !== 'string'` fell through to the fill branch),
+ *   silently replacing the caller's own (malformed) value with the round's — violating both
+ *   fill-only-null and "a present payload value always wins". Now: the row's own value is preserved
+ *   UNTOUCHED (never replaced with a guess about what the caller meant), and the problem is named in
+ *   `taskIdInvalid` so a reader can see the row was neither filled nor trusted blindly.
+ *
+ * Pure: no filesystem, no clock. The CALLER (the cli) is the one that read `.dz/rounds/` to build
+ * `lookup` in the first place.
+ */
+export function applyTaskId(row: Record<string, unknown>, lookup: TaskIdLookup): Record<string, unknown> {
+  const hasTaskIdKey = Object.prototype.hasOwnProperty.call(row, 'taskId');
+  const rawPayloadTaskId = row['taskId'];
+  if (hasTaskIdKey && rawPayloadTaskId !== null && rawPayloadTaskId !== undefined) {
+    if (typeof rawPayloadTaskId === 'string' && rawPayloadTaskId.trim() !== '') {
+      const payloadTaskId = rawPayloadTaskId.trim();
+      if (lookup.taskId !== null && lookup.taskId !== payloadTaskId) {
+        return { ...row, taskIdConflict: { payload: payloadTaskId, round: lookup.taskId } };
+      }
+      return { ...row };
+    }
+    // r1-3: present but not a usable identity (non-string, or blank after trim) — refuse to replace
+    // it with a lookup guess; preserve it verbatim and name the problem.
+    return { ...row, taskIdInvalid: { value: rawPayloadTaskId, reason: 'taskId present but not a non-empty string' } };
+  }
+  return { ...row, taskId: lookup.taskId, taskIdSource: lookup.source };
+}

package/src/score.ts

@@ -21,6 +21,7 @@
  */
 
 import { amendmentIdsIn } from './amendment-trace.js';
+import { QE_SEVERITIES, findInvalidQeVerdictLines, parseQeFindings, readQeVerdictLines, type QeFindingsRefusedRow, type QeFindingsSummary } from './qe-findings.js';
 
 export type DisciplineVerdict = 'pass' | 'partial' | 'absent';
 
@@ -45,11 +46,29 @@ export interface RunScorecard {
    * stay distinguishable.
    */
   readonly mutationEvidence?: MutationEvidence;
+  /**
+   * qe-findings-record FR-4: where `qeGrade` came from — a machine-written `QE-VERDICT:` line, the
+   * pre-existing prose scan, or neither. ADDITIVE for the same reason as `mutationEvidence`: every
+   * scorecard built before this field existed still satisfies `RunScorecard`.
+   */
+  readonly gradeSource?: GradeSource;
+  /**
+   * qe-findings-record FR-4: the report's Findings ledger, when one exists. `absent` for the 406
+   * pre-existing reports that carry neither the table nor the heading (NFR-1) — never omitted, for
+   * the same "gate never ran vs a field an older scorer never wrote" reason `mutationEvidence` gives.
+   */
+  readonly findings?: QeFindingsScoreView;
   readonly passed: number;
   readonly total: number;
   readonly summary: string;
 }
 
+/** A lighter projection of `QeFindingsResult` for the scorecard — summary + refused + hollow, never
+ *  the full row list (that stays in `parseQeFindings`'s own return value for a caller that wants it). */
+export type QeFindingsScoreView =
+  | { readonly status: 'absent' }
+  | { readonly status: 'present'; readonly hollow: boolean; readonly summary: QeFindingsSummary; readonly refused: readonly QeFindingsRefusedRow[] };
+
 /** The artifact texts of one run, keyed by RELATIVE path under `features/<slug>/`. */
 /**
  * The exact heading Step 5 asks for, and the exact heading the check looks for — ONE constant, so
@@ -306,7 +325,22 @@ function normaliseGradeSign(grade: string): string {
   return grade.replace('\u2212', '-');
 }
 
-export type GradeReadStatus = 'unique' | 'ambiguous' | 'none';
+/**
+ * fix-round-1 (codex-r1-verdict finding 2): `'invalid'` is a report that ATTEMPTED a machine verdict
+ * (a line starting `QE-VERDICT`, any case/spacing) and got the grammar wrong — `QE-VERDICT: B – final`
+ * (en dash + trailing prose), wrong case, no colon, a grade outside A-D. That is a DIFFERENT fact from
+ * `'none'` (no attempt at all, legacy prose scan still applies): a malformed attempt must never fall
+ * back to guessing a grade from prose — the malformed line is itself evidence the report is unreliable
+ * here, and guessing past it would silently launder that unreliability into a confident number.
+ */
+export type GradeReadStatus = 'unique' | 'ambiguous' | 'none' | 'invalid';
+
+/**
+ * qe-findings-record (ADR-001 D1): where the grade came from. `'verdict-line'` — a machine-written
+ * `QE-VERDICT:` line, the source of truth when present. `'prose'` — the pre-existing GRADE_RE scan,
+ * unchanged, used only when NO verdict line exists. `'none'` — neither surface names a grade.
+ */
+export type GradeSource = 'verdict-line' | 'prose' | 'none';
 
 export interface GradeReading {
   readonly status: GradeReadStatus;
@@ -314,6 +348,7 @@ export interface GradeReading {
   readonly grade: string | null;
   /** Every distinct grade found, normalised — what makes an `ambiguous` verdict inspectable. */
   readonly found: readonly string[];
+  readonly source: GradeSource;
 }
 
 /**
@@ -329,6 +364,44 @@ export interface GradeReading {
  * report is ambiguous, which is a fact about the report, not a missing number.
  */
 export function readQeGrade(qeText: string): GradeReading {
+  // ADR-001 D1: a machine-written verdict line is the source of truth WHEN it exists — checked
+  // first, and the prose scan below never runs when it does. Exactly one -> unique; more than one
+  // -> ambiguous ("две строки — ambiguous, никогда «последняя побеждает»", even if both name the
+  // SAME grade — two lines is a fact about the report, not a number to reconcile); zero -> the
+  // prose scan runs exactly as it always has (NFR-1: 406 pre-existing reports are unaffected) —
+  // UNLESS a malformed attempt exists (fix-round-1 finding 2, checked next): the report is `invalid`
+  // and the prose fallback is refused, never silently reached.
+  const verdictLines = readQeVerdictLines(qeText);
+  // Lead delta after Codex r2 (new HIGH #1): a malformed declaration next to a valid one is NOT a
+  // unique verdict — `QE-VERDICT: A` + `qe-verdict: D` used to read as unique A. Invalid lines are
+  // checked FIRST, whatever the count of valid ones.
+  const invalidFirst = findInvalidQeVerdictLines(qeText);
+  if (invalidFirst.length > 0) {
+    const reasons = invalidFirst.map(
+      (l) => `line ${l.line}: ${JSON.stringify(l.text.trim())} does not match "QE-VERDICT: <A|B|C|D><+|-> "`,
+    );
+    return { status: 'invalid', grade: null, found: [...verdictLines, ...reasons], source: 'verdict-line' };
+  }
+  if (verdictLines.length === 1) {
+    return { status: 'unique', grade: verdictLines[0] as string, found: verdictLines, source: 'verdict-line' };
+  }
+  if (verdictLines.length > 1) {
+    const distinct: string[] = [];
+    for (const g of verdictLines) if (!distinct.includes(g)) distinct.push(g);
+    return { status: 'ambiguous', grade: null, found: distinct, source: 'verdict-line' };
+  }
+
+  // fix-round-1 finding 2: zero GRAMMATICALLY VALID verdict lines is not yet "no attempt" — a line
+  // that clearly opens a verdict declaration but botches the grammar (wrong dash, wrong case, no
+  // colon, a grade outside A-D) is `invalid`, and the legacy prose scan below is FORBIDDEN for it.
+  // The reason lives inside `found` (GradeReading keeps the same 4-field shape for every status).
+  // Lead delta after Codex r2 (#2 PARTIAL): the prose fallback is for LEGACY reports only. A report
+  // that already carries the new-format ledger heading but no verdict line is a NEW-format report
+  // missing its verdict — `invalid`, never a prose guess.
+  if (/^## Findings ledger\s*$/m.test(qeText)) {
+    return { status: 'invalid', grade: null, found: ['new-format report (has "## Findings ledger") without a QE-VERDICT line'], source: 'verdict-line' };
+  }
+
   const found: string[] = [];
   const lines = qeText.split('\n');
   // Line offsets once, so each match maps to ITS line for the negation screen (67d7883d: the
@@ -352,9 +425,9 @@ export function readQeGrade(qeText: string): GradeReading {
     const g = normaliseGradeSign(m[1] as string);
     if (!found.includes(g)) found.push(g);
   }
-  if (found.length === 0) return { status: 'none', grade: null, found: [] };
-  if (found.length === 1) return { status: 'unique', grade: found[0] as string, found };
-  return { status: 'ambiguous', grade: null, found };
+  if (found.length === 0) return { status: 'none', grade: null, found: [], source: 'none' };
+  if (found.length === 1) return { status: 'unique', grade: found[0] as string, found, source: 'prose' };
+  return { status: 'ambiguous', grade: null, found, source: 'prose' };
 }
 
 export function extractQeGrade(qeText: string): string | null {
@@ -451,7 +524,13 @@ export function scoreRun(slug: string, artifacts: RunArtifacts): RunScorecard {
   );
 
   // 3. Cross-model QE — an independent family reviewed it, and a grade exists.
-  const grade = extractQeGrade(qeText);
+  const gradeReading = readQeGrade(qeText);
+  const grade = gradeReading.grade;
+  const findingsParsed = parseQeFindings(qeText);
+  const findings: QeFindingsScoreView =
+    findingsParsed.status === 'absent'
+      ? { status: 'absent' }
+      : { status: 'present', hollow: findingsParsed.hollow, summary: findingsParsed.summary, refused: findingsParsed.refused };
   if (qeText === '') {
     add('cross-model-qe', 'independent cross-model review with a grade', 'absent', 'no 08_qe_report.md artifact');
   } else {
@@ -559,11 +638,36 @@ export function scoreRun(slug: string, artifacts: RunArtifacts): RunScorecard {
     (grade !== null ? ` · QE grade ${grade}` : ' · no QE grade') +
     (worst.length > 0 ? ` · absent: ${worst.join(', ')}` : '');
 
-  return { slug, disciplines, qeGrade: grade, mutationEvidence, passed, total, summary };
+  return { slug, disciplines, qeGrade: grade, gradeSource: gradeReading.source, findings, mutationEvidence, passed, total, summary };
 }
 
 const MARK: Record<DisciplineVerdict, string> = { pass: '✓', partial: '◐', absent: '✗' };
 
+/** qe-findings-record FR-4: the one-line summary `dz score` prints for a report's Findings ledger —
+ *  "findings: 3 HIGH / 2 MEDIUM; 1 refused (line 84: severity "Major" not in dictionary)". Ordered by
+ *  QE_SEVERITIES (BLOCKER first) so the worst finding always reads first. `null` when there is no
+ *  table at all — the common case, which earns no noise (same rule as mutationEvidence above). */
+export function renderFindingsLine(findings: QeFindingsScoreView | undefined): string | null {
+  if (findings === undefined || findings.status === 'absent') return null;
+  // fix-round-1 finding 6: hollow used to short-circuit BEFORE the refused check, so a report whose
+  // real ledger table (with CRITICAL rows) was refused as duplicate/outside-section alongside an
+  // empty accepted table read as pure "EMPTY" — the refused rows vanished from the printed line, not
+  // merely from the tally. Both facts are ALWAYS reported together now; neither hides the other.
+  const refusedSuffix = ((): string => {
+    if (findings.refused.length === 0) return '';
+    const first = findings.refused[0] as QeFindingsRefusedRow;
+    const more = findings.refused.length > 1 ? `, +${findings.refused.length - 1} more` : '';
+    return `; ${findings.refused.length} refused (line ${first.line}: ${first.reason})${more}`;
+  })();
+  if (findings.hollow) {
+    return `findings: table present but EMPTY (hollow) — worse than no table at all${refusedSuffix}`;
+  }
+  const bySev = findings.summary.bySeverity;
+  const parts = QE_SEVERITIES.filter((s) => (bySev[s] ?? 0) > 0).map((s) => `${bySev[s]} ${s}`);
+  const head = parts.length > 0 ? parts.join(' / ') : 'no rows';
+  return `findings: ${head}${refusedSuffix}`;
+}
+
 export function renderScorecard(card: RunScorecard): string {
   const out: string[] = [];
   out.push(`dz score — ${card.slug} (process scorecard; descriptive-only, never a gate)`);
@@ -581,6 +685,11 @@ export function renderScorecard(card: RunScorecard): string {
     out.push('');
     out.push(`  ${card.mutationEvidence.evidence}`);
   }
+  const findingsLine = renderFindingsLine(card.findings);
+  if (findingsLine !== null) {
+    out.push('');
+    out.push(`  ${findingsLine}${card.gradeSource !== undefined && card.gradeSource !== 'none' ? ` (grade source: ${card.gradeSource})` : ''}`);
+  }
   out.push('');
   out.push(`  ${card.summary}`);
   return out.join('\n');