@mutagent/evaluator 0.1.0-alpha.5 → 0.1.0-alpha.6

package/.claude/skills/mutagent-evaluator/scripts/memory/ratify.ts

@@ -0,0 +1,165 @@
+/**
+ * scripts/memory/ratify.ts — EV-4: persist ratify / do-not decisions + hold the verdict.
+ * ---------------------------------------------------------------------------
+ * The dominant dogfood finding ("router-as-doer") rested on a NORMATIVE call —
+ * what counts as correct routing — that only the operator can settle. The review
+ * UI already CAPTURES the operator's verify/eliminate decisions on each surfaced
+ * assumption (`build-review-ui.ts` `setCalib` → `calibration.json`), but wrote them
+ * NOWHERE: a verdict resting on an unratified standard still read as final.
+ *
+ * This is the LEAN wiring (decision EV-4 option a — NO new criterion schema):
+ *   1. ROUTE each calibration decision into `appendMemory` — the same store the
+ *      next run's judges read at start (`memory/read.ts`), deduped by slug.
+ *   2. HOLD the verdict: a NORMATIVE criterion with no `verify` ratification in the
+ *      decision set is `needs-ratification`; while any is pending the run's verdict
+ *      is HELD (not final) — the value call must be settled first.
+ *
+ * PURE cores (deterministic; `now` injected). The only fs edge reuses `appendMemory`.
+ */
+import { appendMemory, Lifecycle, MemoryType, type AppendResult } from "./append.ts";
+import { AssumptionKind, type CriterionVerdict } from "../contracts/eval-types.ts";
+
+/**
+ * The criterion ids whose verdict rests on a NORMATIVE assumption (a value/standard
+ * call — `AssumptionKind.Normative`), whether surfaced in `assumptions[]` or the
+ * `blockedBy` payload. These are the criteria that REQUIRE operator ratification
+ * before their verdict can be final. PURE.
+ */
+export function normativeCriterionIds(verdicts: CriterionVerdict[]): string[] {
+  const ids = new Set<string>();
+  for (const v of verdicts) {
+    const inAssumptions = (v.assumptions ?? []).some((a) => a.kind === AssumptionKind.Normative);
+    const inBlock = v.blockedBy?.kind === AssumptionKind.Normative;
+    if (inAssumptions || inBlock) ids.add(v.criterionId);
+  }
+  return [...ids].sort();
+}
+
+/** The verify/eliminate action a review-UI calibration button emits (`data-action`). */
+export const RatifyAction = {
+  /** the operator RATIFIES the surfaced assumption/standard (accept it). */
+  Verify: "verify",
+  /** the operator rejects it (do-not — drop this standard). */
+  Eliminate: "eliminate",
+} as const;
+export type RatifyActionValue = (typeof RatifyAction)[keyof typeof RatifyAction];
+
+/**
+ * One calibration decision as the review UI exports it (`calibration.json`). Shape
+ * mirrors `build-review-ui.ts` `setCalib` EXACTLY so the operator's export routes
+ * with no transform.
+ */
+export interface CalibrationDecision {
+  traceId: string;
+  criterionId: string;
+  assumptionIndex: number;
+  action: RatifyActionValue;
+  decidedAt?: string;
+}
+
+/** A stable slug for a ratification memory (dedupe: re-deciding the same pair updates). */
+export function ratificationSlug(d: CalibrationDecision): string {
+  return `ratify-${d.criterionId}-a${d.assumptionIndex}`;
+}
+
+/**
+ * Project a calibration decision → an AutoMemory FeedbackInput. A `verify` is a
+ * standing "this standard IS ratified" fact the next run's judge honours; an
+ * `eliminate` records the operator dropped it. PURE.
+ */
+export function calibrationToMemory(
+  d: CalibrationDecision,
+  criterionStatement?: string,
+): { title: string; description: string; body: string } {
+  const ratified = d.action === RatifyAction.Verify;
+  const what = criterionStatement !== undefined && criterionStatement.length > 0 ? criterionStatement : d.criterionId;
+  const title = ratificationSlug(d);
+  const verb = ratified ? "RATIFIED" : "REJECTED (do-not)";
+  return {
+    title,
+    description: `Normative ratification — criterion ${d.criterionId} assumption #${d.assumptionIndex} ${verb}`,
+    body:
+      `Operator ${verb} the normative standard for criterion \`${d.criterionId}\` ` +
+      `(assumption #${d.assumptionIndex}).\n\n` +
+      `**What:** ${what}\n` +
+      `**Why:** a normative criterion (what SHOULD count as good) is an operator value call — ` +
+      `the judge cannot settle it. This decision is the settled standard.\n` +
+      `**How to apply:** ${ratified
+        ? "treat this standard as ratified — the verdict on this criterion may now be final."
+        : "do NOT gate on this standard — the operator dropped it."}\n` +
+      (d.decidedAt !== undefined ? `\n(decided ${d.decidedAt})` : ""),
+  };
+}
+
+/**
+ * ROUTE calibration decisions into AutoMemory (EV-4). One `appendMemory` per
+ * decision, deduped by slug (re-deciding UPDATES). Returns the append results.
+ * `now` (YYYY-MM-DD) is INJECTED. `statements` optionally maps criterionId → its
+ * statement for a richer memory body.
+ */
+export function persistCalibrations(
+  memoryDir: string,
+  decisions: CalibrationDecision[],
+  now: string,
+  statements: Record<string, string> = {},
+): AppendResult[] {
+  return decisions.map((d) => {
+    const m = calibrationToMemory(d, statements[d.criterionId]);
+    return appendMemory(
+      memoryDir,
+      {
+        title: m.title,
+        description: m.description,
+        lifecycle: Lifecycle.Evaluate,
+        type: MemoryType.Feedback, // a standing steer the next run's judge honours
+        feedback: { text: m.body },
+      },
+      now,
+    );
+  });
+}
+
+/** The ratification state of one normative criterion (EV-4). */
+export interface RatificationStatus {
+  criterionId: string;
+  /** true when a `verify` decision ratified it; false ⇒ needs-ratification. */
+  ratified: boolean;
+}
+
+/**
+ * Given the NORMATIVE criterion ids (those resting on a normative assumption) and
+ * the operator's calibration decisions, report which are RATIFIED (a `verify`
+ * exists) vs still `needs-ratification`. An `eliminate` does NOT ratify — the
+ * standard was dropped, not settled-as-correct. PURE.
+ */
+export function ratificationStatus(
+  normativeCriterionIds: string[],
+  decisions: CalibrationDecision[],
+): RatificationStatus[] {
+  const ratified = new Set(
+    decisions.filter((d) => d.action === RatifyAction.Verify).map((d) => d.criterionId),
+  );
+  return normativeCriterionIds.map((id) => ({ criterionId: id, ratified: ratified.has(id) }));
+}
+
+/**
+ * The criterion ids that HOLD the verdict (EV-4): normative criteria not yet
+ * ratified. While this list is non-empty the run's verdict is NOT final — the
+ * operator must settle the value call first. PURE.
+ */
+export function pendingRatifications(
+  normativeCriterionIds: string[],
+  decisions: CalibrationDecision[],
+): string[] {
+  return ratificationStatus(normativeCriterionIds, decisions)
+    .filter((s) => !s.ratified)
+    .map((s) => s.criterionId);
+}
+
+/** Is the run's verdict HELD pending an operator ratification? (EV-4) */
+export function isVerdictHeldForRatification(
+  normativeCriterionIds: string[],
+  decisions: CalibrationDecision[],
+): boolean {
+  return pendingRatifications(normativeCriterionIds, decisions).length > 0;
+}

package/.claude/skills/mutagent-evaluator/scripts/prep-tasks.ts

@@ -27,7 +27,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { extractOutcomeSignals, type JudgeInvoke } from "./determine-outcome.ts";
-import { buildOutcomePrompt } from "./judge-prompt-template.ts";
+import { buildOutcomePrompt, type SubjectFrame } from "./judge-prompt-template.ts";
 import {
   writeJudgeTask,
   verdictFileName,
@@ -53,19 +53,27 @@ const PREP_PLACEHOLDER = JSON.stringify({
  */
 export function prepDeterminerTasks(
   traces: EvalTrace[],
-  opts: { dir: string; pin: PinnedEnvelope; vocab: SubjectVocab },
+  opts: { dir: string; pin: PinnedEnvelope; vocab: SubjectVocab; subject?: SubjectFrame },
 ): JudgeTaskSpec[] {
   return traces.map((trace) => {
+    // EV-1 — the subject frame MUST match what the Stage-B pipeline renders (byte-
+    // identity for the cross-stage cache), so the caller derives it from the SAME
+    // full trace batch buildSubjectProfile sees in run-pipeline.
     const { system, user } = buildOutcomePrompt(
       trace,
       extractOutcomeSignals(trace, opts.vocab),
       opts.vocab,
+      opts.subject,
     );
     return writeJudgeTask(opts.dir, {
       unit: { kind: "discover", traceId: trace.id },
       system,
       user,
       pin: opts.pin,
+      // INF-3 — salt the determiner cache key with the trace id so two sessions with
+      // an identical (e.g. empty) determiner prompt never collapse onto one verdict.
+      // AGGREGATE reads the stored `spec.verdictFile`, so this needs no re-derive there.
+      keyId: trace.id,
     });
   });
 }
@@ -84,8 +92,11 @@ export function createCapturingJudge(opts: {
   pin: PinnedEnvelope;
 }): { judge: JudgeInvoke; captured: JudgeTaskSpec[] } {
   const captured: JudgeTaskSpec[] = [];
-  const judge: JudgeInvoke = (system, user) => {
-    const vpath = join(opts.verdictDir, verdictFileName(system, user));
+  const judge: JudgeInvoke = (system, user, keyId) => {
+    // INF-3 — the determiner passes its trace id (keyId) so the salted stage-A
+    // verdict file is found; criterion-judge prompts pass no keyId ⇒ unsalted,
+    // and are CAPTURED as build-evals tasks below (byte-identical key, C-PIN).
+    const vpath = join(opts.verdictDir, verdictFileName(system, user, keyId));
     if (existsSync(vpath)) return Promise.resolve(readFileSync(vpath, "utf8"));
     captured.push(
       // D4 — the criterion judging axis (*build-evals / Step-2b). `kind` now matches the

package/.claude/skills/mutagent-evaluator/scripts/read-manifest.ts

@@ -0,0 +1,120 @@
+/**
+ * scripts/read-manifest.ts — EV-6: the sibling TraceManifest leg of the Discovery handoff.
+ * ---------------------------------------------------------------------------
+ * The Discovery handoff is a PATH PAIR — the UniTF `.jsonl` PLUS a sibling
+ * `TraceManifest` that reports the slice (count · format · truncation · coverage).
+ * Diagnostics reads BOTH and audits the slice BEFORE it judges; the evaluator used
+ * to read only the JSONL (a bare `--traces` path) and never opened the manifest —
+ * so a truncated or partially-malformed export was judged silently as if complete
+ * (EV-6). This wires the manifest leg into the evaluator intake, WARN-not-fail, the
+ * way diagnostics' `read-unitf.ts` `validateUniTFManifest` does.
+ *
+ * STANDALONE — the manifest shape is VENDORED (a minimal structural subset of
+ * `@mutagent/tools` `trace-manifest.ts`), NOT imported: the standalone-publish
+ * guard forbids the evaluator reaching into `@mutagent/tools`
+ * (MIGRATION-diagnostics-evaluator.md:417). Only the fields the audit reads are
+ * mirrored; diagnostics vendors its own identical copy.
+ *
+ * PURE except for the effectful `validateSiblingManifest` (one fs read of a sibling
+ * path). No clock / random / network.
+ */
+import { existsSync, readFileSync } from "node:fs";
+
+/** The manifest `format` marker that pairs with the UniTF version. */
+export const UNITF_MANIFEST_FORMAT = "unitf@0.1" as const;
+
+/**
+ * The sibling TraceManifest (frozen `TraceManifest v0.1.0`), structural subset —
+ * only the fields the slice audit inspects. Every field is optional so a partial
+ * or older manifest degrades to fewer warnings rather than throwing.
+ */
+export interface UnitfTraceManifest {
+  manifest_version?: string;
+  count?: number;
+  truncated?: boolean;
+  truncationReason?: string;
+  format?: string;
+  coverage?: {
+    fetched?: number;
+    malformed?: number;
+    deduped?: number;
+  };
+  warnings?: string[];
+}
+
+/**
+ * The sibling manifest path for a handed-over traces file: `<path>.manifest.json`,
+ * with a `.jsonl` suffix REPLACED (`traces.jsonl` → `traces.manifest.json`) —
+ * mirrors `@mutagent/tools` `manifestPathFor`. A `.gz` suffix is stripped first
+ * (the evaluator loads `.jsonl.gz` too) so `traces.jsonl.gz` also resolves to
+ * `traces.manifest.json`. PURE.
+ */
+export function manifestPathForTraces(tracesPath: string): string {
+  const base = tracesPath.endsWith(".gz") ? tracesPath.slice(0, -".gz".length) : tracesPath;
+  return base.endsWith(".jsonl")
+    ? base.slice(0, -".jsonl".length) + ".manifest.json"
+    : base + ".manifest.json";
+}
+
+/**
+ * Validate a parsed manifest against the parsed trace count. Returns WARNINGS
+ * (never throws, never aborts) — the migration's "surface warnings but do NOT
+ * abort a partial export" rule. Empty array = clean / no manifest. Mirrors
+ * diagnostics `validateUniTFManifest`.
+ */
+export function validateUnitfManifest(
+  manifest: UnitfTraceManifest | undefined,
+  actualTraceCount: number,
+): string[] {
+  const warnings: string[] = [];
+  if (!manifest) return warnings;
+  if (manifest.format !== undefined && manifest.format !== UNITF_MANIFEST_FORMAT) {
+    warnings.push(`manifest.format is "${manifest.format}" — expected "${UNITF_MANIFEST_FORMAT}"`);
+  }
+  if (manifest.count !== undefined && manifest.count !== actualTraceCount) {
+    warnings.push(
+      `manifest.count (${manifest.count}) != parsed trace count (${actualTraceCount}) — ` +
+        `the slice is incomplete (a truncated/partially-malformed export judged as if complete)`,
+    );
+  }
+  if (manifest.truncated === true) {
+    warnings.push(
+      `export is truncated${manifest.truncationReason ? ` (${manifest.truncationReason})` : ""} — ` +
+        `judging a PARTIAL slice`,
+    );
+  }
+  // Coverage cross-check: fetched should account for the parsed + malformed + deduped
+  // records; a fetched count that exceeds what landed on disk is a silent drop.
+  const cov = manifest.coverage;
+  if (cov?.fetched !== undefined) {
+    const accountedFor = actualTraceCount + (cov.malformed ?? 0) + (cov.deduped ?? 0);
+    if (cov.fetched !== accountedFor) {
+      warnings.push(
+        `manifest.coverage.fetched (${cov.fetched}) != parsed(${actualTraceCount}) + ` +
+          `malformed(${cov.malformed ?? 0}) + deduped(${cov.deduped ?? 0}) = ${accountedFor} — ` +
+          `records went missing between fetch and hand-off`,
+      );
+    }
+  }
+  if (manifest.warnings) warnings.push(...manifest.warnings);
+  return warnings;
+}
+
+/**
+ * Read + validate the sibling manifest for a handed-over traces file. Effectful
+ * (one fs read). NON-fatal throughout: an ABSENT manifest returns [] (the handoff
+ * may predate the manifest leg); an UNREADABLE / unparseable manifest yields a
+ * single warning and proceeds. Returns the human-readable warning list the caller
+ * surfaces on stderr.
+ */
+export function validateSiblingManifest(tracesPath: string, actualTraceCount: number): string[] {
+  const manifestPath = manifestPathForTraces(tracesPath);
+  if (!existsSync(manifestPath)) return []; // no manifest leg — nothing to audit
+  let manifest: UnitfTraceManifest | undefined;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as UnitfTraceManifest;
+  } catch {
+    return [`sibling manifest '${manifestPath}' failed to read/parse — proceeding without slice audit`];
+  }
+  return validateUnitfManifest(manifest, actualTraceCount);
+}

package/.claude/skills/mutagent-evaluator/scripts/read-unitf-traces.ts

@@ -23,6 +23,30 @@ export interface ParsedUnitfTraces {
   traces: EvalTrace[];
   /** lines that failed to parse OR lacked the minimal UniTF shape (surfaced). */
   skipped: number;
+  /**
+   * INF-1 — traceIds of records that carry a prompt-bearing span (a user/system
+   * turn, or an assistant/agent GENERATION span) yet projected to an EMPTY
+   * `input.prompt`. This is the exact silent-empty symptom that read 21/21 blank
+   * on Claude Code traces: the reader must WARN, never emit empty in silence. The
+   * effectful reader/CLI surfaces this list; a non-empty list is a projection miss.
+   */
+  emptyPromptTraceIds: string[];
+}
+
+/**
+ * Does this record carry a span that SHOULD yield a prompt — an explicit user/
+ * system turn, or a GENERATION span (kind llm/agent, the Langfuse shape whose
+ * `input` holds the prompt)? Used to WARN when such a record still projects an
+ * empty `input.prompt` (the INF-1 silent-empty class). PURE.
+ */
+function hasPromptBearingSpan(rec: UnifiedTraceLike): boolean {
+  return rec.spans.some(
+    (s) =>
+      s.role === "user" ||
+      s.role === "system" ||
+      s.kind === "llm" ||
+      s.kind === "agent",
+  );
 }
 
 /**
@@ -45,6 +69,7 @@ function asUnitfRecord(value: unknown): UnifiedTraceLike | null {
  */
 export function parseUnitfJsonl(text: string): ParsedUnitfTraces {
   const traces: EvalTrace[] = [];
+  const emptyPromptTraceIds: string[] = [];
   let skipped = 0;
   for (const line of text.split("\n")) {
     const trimmed = line.trim();
@@ -61,9 +86,16 @@ export function parseUnitfJsonl(text: string): ParsedUnitfTraces {
       skipped += 1;
       continue;
     }
-    traces.push(projectUnitfToEvalTrace(rec));
+    const trace = projectUnitfToEvalTrace(rec);
+    traces.push(trace);
+    // INF-1 — WARN, never silently emit empty: a record with a prompt-bearing span
+    // that still projected an empty prompt is a projection miss (the Claude Code
+    // 21/21-blank class). Recorded here; the CLI/reader surfaces it.
+    if (hasPromptBearingSpan(rec) && (trace.input?.prompt ?? "").length === 0) {
+      emptyPromptTraceIds.push(trace.id);
+    }
   }
-  return { traces, skipped };
+  return { traces, skipped, emptyPromptTraceIds };
 }
 
 /**

package/.claude/skills/mutagent-evaluator/scripts/render-build-cards.ts

@@ -83,6 +83,33 @@ export function renderBuildEvalsProgressCard(p: BuildEvalsProgress): string {
   ].join("\n");
 }
 
+// ── EVAL-1 — "what this stage will produce" notice (up-front, at stage start) ─
+export interface StageProducesNotice {
+  subject: string;
+  /** the command about to run (e.g. "*build-dataset" | "*build-evals" | "*eval"). */
+  command: string;
+  /** the named deliverables this stage emits (dataset · criteria · which files). */
+  produces: string[];
+}
+
+/**
+ * EVAL-1 (1) — render the up-front notice that names WHAT this stage will produce,
+ * so a build never runs silently with the operator unaware a dataset/criteria are
+ * coming. Emitted at Step 0, BEFORE the build. PURE. NOT an approval gate — a
+ * notification only (operator constraint).
+ */
+export function renderStageProducesNotice(n: StageProducesNotice): string {
+  const lines = [
+    TOP,
+    row(`▷ ${n.command} — ${n.subject}`),
+    MID,
+    row("this stage will produce:"),
+  ];
+  for (const p of n.produces) lines.push(row(`  • ${p}`));
+  lines.push(BOT);
+  return lines.join("\n");
+}
+
 // ── F22 — dataset entity card (verbose, after *build-dataset) ─────────────────
 export interface DatasetEntity {
   subject: string;
@@ -99,6 +126,12 @@ export function renderDatasetEntityCard(e: DatasetEntity): string {
     MID,
     row(`categories (${e.categories.length}) · ${e.totalItems} items total`),
   ];
+  // EVAL-1 — a build that produced NOTHING must WARN, never render a blank card that
+  // reads as a silent success (the dogfood symptom: a build that reported and a build
+  // that stayed silent looked identical).
+  if (e.categories.length === 0 || e.totalItems === 0) {
+    lines.push(row("⚠ EMPTY — this build produced no dataset items (nothing to evaluate)."));
+  }
   for (const c of e.categories) {
     lines.push(row(`  • ${c.id}: ${c.items} items  (edge: ${c.edgeItems})`));
   }
@@ -129,6 +162,10 @@ export function renderEvalsEntityCard(e: EvalsEntity): string {
     row(`output sink: ${e.outputSink}`),
     row(`criteria (${e.criteria.length}):`),
   ];
+  // EVAL-1 — an eval suite with zero criteria is a silent no-op build; WARN loudly.
+  if (e.criteria.length === 0) {
+    lines.push(row("⚠ EMPTY — this build produced no criteria (the suite judges nothing)."));
+  }
   for (const c of e.criteria) {
     lines.push(row(`  • ${c.id}  [${c.severity}·${c.kind}]`));
   }

package/.claude/skills/mutagent-evaluator/scripts/render-eval-report.ts

@@ -69,6 +69,14 @@ import { assessEmitCompleteness, type EmitCompleteness } from "./emit-completene
 import type { Scorecard } from "./evaluate.ts";
 import type { SourceMap } from "./source-map.ts";
 import { routeFailures, type FailureRef, type HandoverBundle } from "./route-failures.ts";
+// EV-3 — the step<->criterion side-by-side render fns (`cvRefs` + `critiqueBlock`
+// + `sideBySide`, the last carrying its local `refExaminesStep` + `covEntry`) are
+// EXTRACTED VERBATIM into report-fragments.ts and spliced back into the client
+// script IN PLACE below, so this report's emitted HTML is byte-identical to
+// before the extraction. The review UI (`build-review-ui.ts`) imports the SAME
+// constant to render the identical view. Byte-identity is guarded by this file's
+// render tests + a before/after HTML diff.
+import { SIDE_BY_SIDE_FRAGMENT_JS } from "./report-fragments.ts";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const BRAND_DIR = join(HERE, "..", "assets", "brand");
@@ -3319,97 +3327,7 @@ function render(){var qi=document.getElementById('q');if(!qi)return;var q=(qi.va
 // critique-before-verdict + grounding refs, read off the verdict file's verdicts[].
 // Shared by BOTH the side-by-side drill (walk traces) and the per-trajectory
 // scorecard drill (no-walk traces) so NO judged trace renders an empty panel.
-function cvRefs(refs){if(!refs||!refs.length)return '';
-  return '<div class="cvrefs">'+refs.map(function(rf){var s=(typeof rf==='string')?rf:[rf.obs,rf.path,rf.value].filter(Boolean).join(' · ');return s?'<span class="cvref">'+esc(s)+'</span>':'';}).join('')+'</div>';}
-function critiqueBlock(cvs){if(!cvs||!cvs.length)return '';
-  var order={fail:0,uncertain:1,indeterminate:1,pass:2,na:3};
-  var rows=cvs.slice().sort(function(a,b){return (order[a.result]==null?9:order[a.result])-(order[b.result]==null?9:order[b.result]);}).map(function(v){
-    var res=v.result||'na';var disp=res==='uncertain'?'indeterminate':res;
-    var conf=(v.confidence!=null)?'<span class="cvconf">conf '+esc(v.confidence)+(v.confidenceBand?' · '+esc(v.confidenceBand):'')+'</span>':'';
-    var crit=v.critique?'<div class="cvcrit">'+esc(v.critique)+'</div>':'<div class="cvcrit dim">— no critique recorded for this criterion</div>';
-    return '<div class="cvrow '+esc(res)+'"><div class="cvh"><span class="cvb '+esc(res)+'">'+esc(disp)+'</span><span class="cvid">'+esc(v.criterionId||'')+'</span>'+conf+'</div>'+crit+cvRefs(v.refs)+'</div>';}).join('');
-  return '<div class="ctx cvblock"><div class="ctx-h">◇ how the judge reasoned — per-criterion verdict · critique-before-verdict · grounding refs ('+cvs.length+')</div><div class="cvbody">'+rows+'</div></div>';}
-function sideBySide(d){var ctx=d.context||{};
-  // Gap A — the §2 "input + scenario" cell renders the RAW triggering INPUT (the
-  // thing that fired the agent) ABOVE the judge's scenario LABEL. Long inputs
-  // collapse into a <details> (lean, no JS) so the cell stays compact; short ones
-  // render inline (clamped). ABSENT input ⇒ the cell shows the scenario alone (or
-  // "—"). Font stays at the --fs-2xs (11px) floor + brand mono.
-  var inputCell=function(raw,scen){
-    var sc=scen?'<div class="iscn">scenario · '+esc(scen)+'</div>':'';
-    if(!raw)return (scen?'<div class="ival">'+esc(scen)+'</div>':'—');
-    var long=String(raw).length>180;
-    var body=long
-      ? '<details class="iexp"><summary>raw input · '+String(raw).length+' chars</summary><pre class="iraw">'+esc(raw)+'</pre></details>'
-      : '<pre class="iraw clamp">'+esc(raw)+'</pre>';
-    return body+sc;};
-  var refStr=function(rf){if(!rf)return '';if(typeof rf==='string')return rf;return [rf.obs,rf.path,rf.value].filter(Boolean).join(':');};
-  // UI-4 — surface the judge's REASONING (why the verdict + why the exit-states were
-  // concluded) from the EXISTING judge walk: an ordered why-chain band + the decide/bind
-  // text inlined where it explains a conclusion. No emit-contract change — read-only over
-  // the judge_steps already on the verdict file.
-  var KORD={gather:0,context:1,examine:2,detect:3,bind:4,ground:5,critique:6,decide:7,verify:8};
-  var allJs=(d.judgeSteps||[]).slice();
-  var stepText=function(kind){return allJs.filter(function(s){return s.kind===kind;}).map(function(s){return s.text||'';}).filter(Boolean).join(' · ');};
-  var decideWhy=stepText('decide')||stepText('critique');
-  var stateWhy=[stepText('bind'),stepText('gather')].filter(Boolean).join(' · ');
-  var chainSteps=allJs.slice().sort(function(a,b){var x=KORD[a.kind];var y=KORD[b.kind];return (x==null?9:x)-(y==null?9:y);});
-  var whyChain=chainSteps.length?('<div class="ctx whychain"><div class="ctx-h">◇ judge reasoning — full why-chain (gather → bind → ground → decide)</div><div class="wc-body">'+chainSteps.map(function(s){var rs=refStr(s.ref);return '<div class="jstep"><span class="k '+esc(s.kind)+'">'+esc(s.kind)+'</span><span class="t">'+esc(s.text||'')+(rs?' <span class=ref>'+esc(rs)+'</span>':'')+'</span></div>';}).join('')+'</div></div>'):'';
-  var verdictWhy=decideWhy?('<div class="band whyverdict"><div class="bh" style="color:var(--primary-soft)">◇ why this verdict</div><div class="wv-t">'+esc(decideWhy)+'</div></div>'):'';
-  // -- §2 judge lane = per-step EVAL COVERAGE --
-  // The judge lane (.step-r) used to filter judgeSteps by anchor === a.n -- but
-  // judges never emit an anchor, so EVERY step rendered a bare dash. Instead we
-  // map each agent step -> the per-criterion verdicts (d.criterionVerdicts) whose
-  // grounding refs EXAMINED that step: a precise ref.obs === step.obs match plus
-  // the tool-name fallback (ref.path === 'name' && ref.value === step.tool).
-  // Each examining criterion renders one compact entry -- result + CODE/JUDGE tag
-  // + criterionId + the judge reasoning (critique). A step no criterion references
-  // says 'not examined by any eval' (honest), never a bare dash. Any judge step
-  // that DOES carry a real anchor is still honored (future-proof).
-  var cvAll=(d.criterionVerdicts||[]);
-  var refExaminesStep=function(rf,a){
-    if(!rf||typeof rf==='string')return false;
-    if(a.obs&&rf.obs&&String(rf.obs)===String(a.obs))return true;
-    if(rf.path==='name'&&rf.value!=null&&a.tool&&String(rf.value)===String(a.tool))return true;
-    return false;};
-  var covEntry=function(v,a){
-    var res=v.result||'na';var disp=res==='uncertain'?'indeterminate':res;
-    // the router carries TWO vocabularies: matrix-derived ('deterministic') and
-    // mined ('code-based'); 'hybrid' is shared. A '[code-eval ...]'-prefixed critique
-    // is the deterministic-logic fallback when the method is unset.
-    var method=((typeof C!=='undefined'&&C[v.criterionId])||{}).m||'';
-    var isCode=method==='deterministic'||method==='code-based'||method==='hybrid'||String(v.critique||'').trim().indexOf('[code-eval')===0;
-    var tag=method==='hybrid'?'HYBRID':(isCode?'CODE':'JUDGE');
-    var matched=(v.refs||[]).filter(function(rf){return typeof rf!=='string'&&refExaminesStep(rf,a);});
-    var crit=v.critique?esc(v.critique):'<span class="dim">— no critique recorded</span>';
-    return '<div class="jcov '+esc(res)+'"><div class="jcov-h"><span class="cvb '+esc(res)+'">'+esc(disp)+'</span><span class="jm '+(isCode?'code':'judge')+'" title="'+(isCode?'deterministically checked by a code-eval (not LLM-judged)':'reasoned by the LLM judge')+'">'+esc(tag)+'</span><span class="jcid">'+esc(v.criterionId||'')+'</span></div><div class="jcrit">'+crit+'</div>'+cvRefs(matched)+'</div>';};
-  var rowsHtml='';(d.agentSteps||[]).forEach(function(a){
-    // future-proof: a judge step that carries a REAL anchor still renders.
-    var js=(d.judgeSteps||[]).filter(function(s){return s.anchor!=null&&String(s.anchor)===String(a.n)&&s.kind!=='context';});
-    var anchoredHtml=js.map(function(s){var rs=refStr(s.ref);return '<div class="jstep"><span class="k '+esc(s.kind)+'">'+esc(s.kind)+'</span><span class="t">'+esc(s.text||'')+' '+(rs?'<span class=ref>'+esc(rs)+'</span>':'')+'</span></div>';}).join('');
-    var examiners=cvAll.filter(function(v){return (v.refs||[]).some(function(rf){return refExaminesStep(rf,a);});});
-    var covHtml=examiners.map(function(v){return covEntry(v,a);}).join('');
-    var jhtml=anchoredHtml+covHtml;
-    if(!jhtml)jhtml='<div class="jstep noexam"><span class="t">— not examined by any eval</span></div>';
-    rowsHtml+='<div class="step-l"><div class="evb"><div class="top"><span class="tool">'+esc(a.tool||'')+'</span><span class="st '+esc(a.status||'')+'">'+esc(a.status||'')+'</span></div><div class="det">'+esc(a.detail||'')+'</div></div></div><div class="node '+esc(a.status||'')+'"><div class="ln"></div><div class="n">'+esc(a.n)+'</div><div class="ln"></div></div><div class="step-r"><div class="evb r">'+jhtml+'</div></div>';});
-  var h=d.health||{};
-  var sp=d.subjectProfile;
-  var spHtml=sp?'<div class="ctx"><div class="ctx-h">◇ judge · subject profile (M1) · '+esc(sp.provenance||'')+'</div><div class="ctx-g"><div class="ctx-c"><div class="l">identity</div><div class="v">'+esc(sp.identity||'—')+'</div></div><div class="ctx-c"><div class="l">purpose</div><div class="v">'+esc(sp.purpose||'—')+'</div></div><div class="ctx-c"><div class="l">scope · harness</div><div class="v">'+esc((sp.scope||'—'))+' · harness: '+esc(sp.harness||'—')+'</div></div></div></div>':'';
-  var u=d.understanding;
-  var uHtml=u?'<div class="band"><div class="bh" style="color:var(--cyan)">◇ node-0 GATHER — understanding (M2)</div><div class="re-rephrase" style="margin-top:4px">“'+esc(u.rephrase||'')+'”</div></div>':'';
-  var et=d.expectedTrajectory||[];
-  var etHtml=et.length?'<div class="band"><div class="bh" style="color:var(--primary-soft)">◇ node-0.5 EXPECTED-TRAJECTORY (M3) — how it SHOULD have acted</div><ol class="re-ul" style="margin-top:4px">'+et.map(function(s,i){return '<li><b>'+esc(s.step||i+1)+'.</b> '+esc(s.expected||'')+(s.rationale?' <span class=re-rat>— '+esc(s.rationale)+'</span>':'')+'</li>';}).join('')+'</ol></div>':'';
-  return '<div class="drillbox"><div style="display:flex;gap:9px;align-items:center;flex-wrap:wrap;margin-bottom:6px"><b class="mono">'+esc(d.traceId)+'</b><span class="chip">'+esc(d.route||'all')+'</span><span class="verd '+(d.verdict=='FAIL'?'fail':d.verdict=='PASS'?'pass':'inc')+'">'+esc(d.verdict)+'</span></div>'+
-    resRouting(d.res||'judge-walk')+
-    spHtml+
-    verdictWhy+
-    critiqueBlock(d.criterionVerdicts)+
-    '<div class="ctx"><div class="ctx-h">◇ judge · gather context</div><div class="ctx-g"><div class="ctx-c"><div class="l">harness</div><div class="v">'+esc(ctx.harness||'—')+'</div></div><div class="ctx-c"><div class="l">input + scenario</div><div class="v">'+inputCell(d.input,ctx.scenario)+'</div></div><div class="ctx-c"><div class="l">exit states</div><div class="v">'+esc(ctx.exitStates||'—')+(stateWhy?'<div class="why-note"><span class="ref">why concluded:</span> '+esc(stateWhy)+'</div>':'')+'</div></div></div></div>'+
-    whyChain+
-    uHtml+etHtml+
-    '<div class="lanehdr"><div class="a">target agent — what it did</div><div class="x">step</div><div class="j">judge — eval coverage (which criteria examined this step)</div></div>'+
-    '<div class="grid2">'+rowsHtml+'<div class="band loc"><div class="bh">↯ localize (root, not symptom)</div><div style="font-size:var(--fs-sm);margin-top:4px">'+esc(d.localize||'—')+'</div></div></div>'+
-    '<div class="health"><div class="hc"><div class="l">context</div><div class="v good">'+(h.contextGathered?'✓':'—')+'</div></div><div class="hc"><div class="l">grounded</div><div class="v good">'+esc(h.grounded||0)+'</div></div><div class="hc"><div class="l">assumed</div><div class="v '+((h.assumed||0)>0?'warn':'good')+'">'+esc(h.assumed||0)+'</div></div><div class="hc"><div class="l">root vs symptom</div><div class="v good">'+(h.stoppedAtSymptom?'symptom':'✓ root')+'</div></div></div></div>';}
+${SIDE_BY_SIDE_FRAGMENT_JS}
 function scorecard(r){var order={fail:0,uncertain:1,indeterminate:1,pass:2,na:3};
   var cells=Object.keys(r.c).sort(function(a,b){return (order[r.c[a]]||9)-(order[r.c[b]]||9);}).map(function(k){var v=r.c[k];var disp=v=='uncertain'?'indeterminate':v;
     return '<div class="scc '+esc(v)+'"><span class="nm" title="'+esc((C[k]||{}).n||k)+'">'+esc(k)+'</span><span style="margin-left:auto;color:var(--muted)">'+esc(disp)+'</span></div>';}).join('');