@mutagent/evaluator 0.1.0-alpha.2

package/.claude/skills/mutagent-evaluator/scripts/validate-judge.ts

@@ -0,0 +1,358 @@
+/**
+ * scripts/validate-judge.ts — EV-044 `*validate` (Type A — Code-only, pure math).
+ * ---------------------------------------------------------------------------
+ * Calibrate a judge against human labels (the rubric is `references/validate-
+ * evaluator.md`; this is the deterministic STATS that implement it):
+ *   - 2×2 confusion matrix → TPR / TNR (NOT raw accuracy — misleading under
+ *     class imbalance);
+ *   - split-disjointness + TEST-ONCE guards (dev for iteration, test measured
+ *     exactly once — looking at test then iterating is data leakage);
+ *   - Rogan-Gladen bias correction  θ = (p_obs + TNR − 1) / (TPR + TNR − 1)
+ *     with clip to [0,1] and `invalid` when the denominator ≈ 0 (judge no better
+ *     than random);
+ *   - a DETERMINISTIC bootstrap CI (seeded LCG resample — NO Math.random, so the
+ *     interval is byte-identical across reruns, C-PIN-adjacent);
+ *   - graceful degradation: a criterion with < MIN_LABELS human labels (or TPR/
+ *     TNR below target) stays `unvalidated` and is reported BIAS-CORRECTED, never
+ *     blocking — the autonomous loop has no human to wait on.
+ *
+ * Austerity: NO judge prompt, NO LLM — this PREPs/AGGREGATEs the numbers; the
+ * verdicts it consumes come from the dispatched eval-judge (read back from
+ * verdict files). The pinned judge model is recorded on the result (a model
+ * change invalidates the numbers — re-validate). PURE — no clock/random/network.
+ */
+import { OutcomeVerdict, type OutcomeVerdictValue } from "./contracts/eval-types.ts";
+import {
+  HumanVerdict,
+  ValidationStatus,
+  type ConfidenceInterval,
+  type ConfusionMatrix,
+  type HumanLabel,
+  type ValidationResult,
+} from "./contracts/validation.ts";
+
+// ── calibration thresholds (validate-evaluator.md) ───────────────────────────
+/** Below this many labels the CIs get wide → the judge stays `unvalidated`. */
+export const MIN_LABELS = 60;
+/** Target TPR/TNR (validate-evaluator.md step 5); below → `unvalidated`. */
+export const TARGET_TPR = 0.9;
+export const TARGET_TNR = 0.9;
+/** Rogan-Gladen denominator floor — below this the judge is ≈ random → invalid. */
+export const RG_DENOM_MIN = 1e-6;
+
+// ── binary class projection (defer / uncertain are excluded) ─────────────────
+type BinaryClass = "pass" | "fail";
+
+/** Project a human verdict to the binary class, or null for `defer`. */
+function humanBinary(v: HumanLabel["label"]): BinaryClass | null {
+  if (v === HumanVerdict.Pass) return "pass";
+  if (v === HumanVerdict.Fail) return "fail";
+  return null; // defer — no ground truth
+}
+
+/** Project a judge verdict to the binary class, or null for `uncertain`. */
+function judgeBinary(v: OutcomeVerdictValue): BinaryClass | null {
+  if (v === OutcomeVerdict.Pass) return "pass";
+  if (v === OutcomeVerdict.Fail) return "fail";
+  return null; // uncertain — excluded from confusion math
+}
+
+/** One judge prediction for a trace (read back from a verdict file). */
+export interface JudgePred {
+  traceId: string;
+  result: OutcomeVerdictValue;
+}
+
+/** A paired human/judge binary judgment for one trace (defer/uncertain dropped). */
+export interface LabeledPair {
+  traceId: string;
+  human: BinaryClass;
+  judge: BinaryClass;
+}
+
+// ── split-disjointness + test-once guards ────────────────────────────────────
+
+/**
+ * Assert no traceId is assigned to more than one split (train/dev/test must
+ * partition cleanly — an overlap is leakage). THROWS on a conflict. PURE.
+ */
+export function assertSplitsDisjoint(labels: HumanLabel[]): void {
+  const splitOf = new Map<string, string>();
+  for (const l of labels) {
+    if (l.split === undefined) continue;
+    const prior = splitOf.get(l.traceId);
+    if (prior !== undefined && prior !== l.split) {
+      throw new Error(
+        `assertSplitsDisjoint: trace '${l.traceId}' is in both '${prior}' and '${l.split}' ` +
+          "splits — train/dev/test must be disjoint (data leakage).",
+      );
+    }
+    splitOf.set(l.traceId, l.split);
+  }
+}
+
+/**
+ * Enforce the test-once rule: the held-out test split is measured EXACTLY once.
+ * THROWS if a prior test measurement is already recorded. The caller persists
+ * the flag in run state; this guards the transition. PURE.
+ */
+export function assertTestUsedOnce(testAlreadyMeasured: boolean): void {
+  if (testAlreadyMeasured) {
+    throw new Error(
+      "assertTestUsedOnce: the test split was already measured — re-running on test after " +
+        "seeing results is data leakage (validate-evaluator.md step 6). Go back to dev.",
+    );
+  }
+}
+
+// ── pairing + confusion matrix ───────────────────────────────────────────────
+
+/**
+ * Pair human labels with judge predictions by traceId, dropping `defer` /
+ * `uncertain` (no ground truth / no judge call). Optionally restrict to one
+ * split. DETERMINISTIC (ordered by traceId). PURE.
+ */
+export function pairLabels(
+  human: HumanLabel[],
+  judge: JudgePred[],
+  split?: "train" | "dev" | "test",
+): LabeledPair[] {
+  const judgeById = new Map(judge.map((j) => [j.traceId, j.result]));
+  const out: LabeledPair[] = [];
+  for (const l of human) {
+    if (split !== undefined && l.split !== split) continue;
+    const h = humanBinary(l.label);
+    if (h === null) continue;
+    const jr = judgeById.get(l.traceId);
+    if (jr === undefined) continue;
+    const j = judgeBinary(jr);
+    if (j === null) continue;
+    out.push({ traceId: l.traceId, human: h, judge: j });
+  }
+  return out.sort((a, b) => a.traceId.localeCompare(b.traceId));
+}
+
+/** Build a 2×2 confusion matrix from paired judgments (Pass = positive). PURE. */
+export function confusionMatrix(pairs: LabeledPair[]): ConfusionMatrix {
+  const cm: ConfusionMatrix = { tp: 0, fp: 0, tn: 0, fn: 0 };
+  for (const p of pairs) {
+    if (p.human === "pass" && p.judge === "pass") cm.tp++;
+    else if (p.human === "fail" && p.judge === "pass") cm.fp++;
+    else if (p.human === "fail" && p.judge === "fail") cm.tn++;
+    else cm.fn++; // human pass, judge fail
+  }
+  return cm;
+}
+
+/** TPR = tp / (tp + fn); null when there are no human-Pass examples. PURE. */
+export function tprOf(cm: ConfusionMatrix): number | null {
+  const denom = cm.tp + cm.fn;
+  return denom === 0 ? null : cm.tp / denom;
+}
+
+/** TNR = tn / (tn + fp); null when there are no human-Fail examples. PURE. */
+export function tnrOf(cm: ConfusionMatrix): number | null {
+  const denom = cm.tn + cm.fp;
+  return denom === 0 ? null : cm.tn / denom;
+}
+
+// ── Rogan-Gladen bias correction ─────────────────────────────────────────────
+
+function clip01(x: number): number {
+  return x < 0 ? 0 : x > 1 ? 1 : x;
+}
+
+export interface RoganGladen {
+  /** the bias-corrected true rate, clipped to [0,1]; null when invalid. */
+  corrected: number | null;
+  /** false when TPR+TNR−1 ≈ 0 (judge no better than random → uncorrectable). */
+  valid: boolean;
+}
+
+/**
+ * Rogan-Gladen correction: θ = (p_obs + TNR − 1) / (TPR + TNR − 1). Clipped to
+ * [0,1]. INVALID (corrected=null) when the denominator's magnitude is below
+ * `denomMin` — the judge is no better than random, so the raw rate cannot be
+ * de-biased. PURE.
+ */
+export function roganGladen(
+  pObs: number,
+  tpr: number,
+  tnr: number,
+  denomMin = RG_DENOM_MIN,
+): RoganGladen {
+  const denom = tpr + tnr - 1;
+  if (Math.abs(denom) < denomMin) return { corrected: null, valid: false };
+  return { corrected: clip01((pObs + tnr - 1) / denom), valid: true };
+}
+
+/** Observed judge Pass-rate over unlabeled predictions (p_obs); null if none. PURE. */
+export function observedPassRate(preds: JudgePred[]): number | null {
+  let pass = 0;
+  let total = 0;
+  for (const p of preds) {
+    const b = judgeBinary(p.result);
+    if (b === null) continue;
+    total++;
+    if (b === "pass") pass++;
+  }
+  return total === 0 ? null : pass / total;
+}
+
+// ── deterministic bootstrap CI (seeded LCG — no Math.random) ─────────────────
+
+/** A small seeded LCG → [0,1). Deterministic; NEVER Math.random (byte-identity). */
+function lcg(seed: number): () => number {
+  let s = seed >>> 0;
+  return () => {
+    // Numerical Recipes LCG constants.
+    s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
+    return s / 0x100000000;
+  };
+}
+
+/** Percentile of an ASCENDING-sorted array (linear interpolation). PURE. */
+export function percentile(sortedAsc: number[], p: number): number {
+  if (sortedAsc.length === 0) return NaN;
+  if (sortedAsc.length === 1) return sortedAsc[0];
+  const idx = clip01(p) * (sortedAsc.length - 1);
+  const lo = Math.floor(idx);
+  const hi = Math.ceil(idx);
+  if (lo === hi) return sortedAsc[lo];
+  return sortedAsc[lo] + (sortedAsc[hi] - sortedAsc[lo]) * (idx - lo);
+}
+
+export interface BootstrapOptions {
+  iterations?: number;
+  /** 2-sided level (default 0.95). */
+  level?: number;
+  /** LCG seed — fixed by default so the CI is reproducible (C-PIN). */
+  seed?: number;
+}
+
+/**
+ * Bootstrap a CI for the Rogan-Gladen corrected rate: resample the labeled pairs
+ * (with replacement, deterministic LCG) `iterations` times, recompute TPR/TNR/θ
+ * per resample, and take the level-tailed percentiles of the valid θ values.
+ * Returns undefined when too few valid resamples exist. `pObs` is fixed (the
+ * production observation), only the calibration sample is resampled. PURE.
+ */
+export function bootstrapCorrectedCI(
+  pairs: LabeledPair[],
+  pObs: number,
+  opts: BootstrapOptions = {},
+): ConfidenceInterval | undefined {
+  const iterations = opts.iterations ?? 1000;
+  const level = opts.level ?? 0.95;
+  const n = pairs.length;
+  if (n < 2) return undefined;
+  const rand = lcg(opts.seed ?? 0x2545f491);
+  const thetas: number[] = [];
+  for (let it = 0; it < iterations; it++) {
+    const cm: ConfusionMatrix = { tp: 0, fp: 0, tn: 0, fn: 0 };
+    for (let k = 0; k < n; k++) {
+      const p = pairs[Math.floor(rand() * n)];
+      if (p.human === "pass" && p.judge === "pass") cm.tp++;
+      else if (p.human === "fail" && p.judge === "pass") cm.fp++;
+      else if (p.human === "fail" && p.judge === "fail") cm.tn++;
+      else cm.fn++;
+    }
+    const tpr = tprOf(cm);
+    const tnr = tnrOf(cm);
+    if (tpr === null || tnr === null) continue;
+    const rg = roganGladen(pObs, tpr, tnr);
+    if (rg.corrected !== null) thetas.push(rg.corrected);
+  }
+  if (thetas.length < 2) return undefined;
+  thetas.sort((a, b) => a - b);
+  const tail = (1 - level) / 2;
+  return { lo: percentile(thetas, tail), hi: percentile(thetas, 1 - tail), level };
+}
+
+// ── top-level orchestration ──────────────────────────────────────────────────
+
+export interface ValidateJudgeInput {
+  criterionId: string;
+  /** the PINNED judge model these numbers belong to (required — C-PIN). */
+  judgeModel: string;
+  /** human labels (with split tags). */
+  humanLabels: HumanLabel[];
+  /** judge predictions on the labeled set (read back from verdict files). */
+  judgeVerdicts: JudgePred[];
+  /** judge predictions on UNLABELED production traces (for p_obs). */
+  unlabeledVerdicts?: JudgePred[];
+  /** has the test split already been measured? (test-once guard). */
+  testAlreadyMeasured?: boolean;
+  /** override the min-labels gate (default MIN_LABELS). */
+  minLabels?: number;
+}
+
+/**
+ * Validate ONE judge against human labels → a `ValidationResult`. Picks the
+ * final-measurement split (test if present — enforcing test-once — else dev,
+ * else all labeled), computes TPR/TNR, the Rogan-Gladen corrected rate from the
+ * unlabeled p_obs, and a bootstrap CI. DEGRADES GRACEFULLY: < minLabels labels or
+ * sub-target TPR/TNR → `unvalidated` (reported bias-corrected, never blocking).
+ * THROWS only on a contract breach (missing pinned model, split overlap,
+ * test-reuse). PURE.
+ */
+export function validateJudge(input: ValidateJudgeInput): ValidationResult {
+  if (input.judgeModel.length === 0) {
+    throw new Error("validateJudge: judgeModel is required (C-PIN — the numbers are model-specific).");
+  }
+  assertSplitsDisjoint(input.humanLabels);
+  const minLabels = input.minLabels ?? MIN_LABELS;
+
+  // choose the final-measurement split: test (once) > dev > all.
+  const hasTest = input.humanLabels.some((l) => l.split === "test");
+  const hasDev = input.humanLabels.some((l) => l.split === "dev");
+  let split: "dev" | "test" | undefined;
+  if (hasTest) {
+    assertTestUsedOnce(input.testAlreadyMeasured ?? false);
+    split = "test";
+  } else if (hasDev) {
+    split = "dev";
+  } else {
+    split = undefined; // no split tags → use all labeled
+  }
+
+  const pairs = pairLabels(input.humanLabels, input.judgeVerdicts, split);
+  const cm = confusionMatrix(pairs);
+  const tpr = tprOf(cm);
+  const tnr = tnrOf(cm);
+  const labelCount = pairs.length;
+
+  const pObs = observedPassRate(input.unlabeledVerdicts ?? []);
+  const rg =
+    tpr !== null && tnr !== null && pObs !== null
+      ? roganGladen(pObs, tpr, tnr)
+      : { corrected: null, valid: false };
+  const ci =
+    pObs !== null && rg.valid ? bootstrapCorrectedCI(pairs, pObs) : undefined;
+
+  // status + note (graceful degradation).
+  const reasons: string[] = [];
+  if (labelCount < minLabels) reasons.push(`only ${labelCount} labels (< ${minLabels})`);
+  if (tpr === null) reasons.push("no human-Pass examples (TPR undefined)");
+  else if (tpr < TARGET_TPR) reasons.push(`TPR ${tpr.toFixed(2)} < ${TARGET_TPR}`);
+  if (tnr === null) reasons.push("no human-Fail examples (TNR undefined)");
+  else if (tnr < TARGET_TNR) reasons.push(`TNR ${tnr.toFixed(2)} < ${TARGET_TNR}`);
+  const status = reasons.length === 0 ? ValidationStatus.Validated : ValidationStatus.Unvalidated;
+
+  const result: ValidationResult = {
+    criterionId: input.criterionId,
+    judgeModel: input.judgeModel,
+    status,
+    labelCount,
+    tpr,
+    tnr,
+    observedPassRate: pObs,
+    correctedRate: rg.corrected,
+    correctionValid: rg.valid,
+    note:
+      status === ValidationStatus.Validated
+        ? `validated on ${labelCount} labels (split: ${split ?? "all"})`
+        : `unvalidated — ${reasons.join("; ")}. Reporting bias-corrected, not raw; loop not blocked.`,
+  };
+  return ci === undefined ? result : { ...result, ci };
+}

package/.claude/skills/mutagent-evaluator/scripts/variance-compare.ts

@@ -0,0 +1,177 @@
+/**
+ * scripts/variance-compare.ts
+ * ---------------------------------------------------------------------------
+ * The variant comparator — Track-2 TREND (R7, decisions #9/#12). A COORDINATOR
+ * (a role distinct from the audit executors) compares TWO run bundles on the
+ * fixed 15-dimension determinism scorecard. The byte-identity masking contract
+ * (mask.ts) is applied first: "byte-identical across runs" is only testable
+ * AFTER masking the declared injected fields (runId / timestamps / abs-paths).
+ *
+ * Each dimension has a Measure and a per-Phase Target. A dimension is:
+ *   - identical      : masked values byte-identical
+ *   - within-target  : differ but inside the phase target
+ *   - diverged       : differ beyond target (counts toward varianceScore)
+ *   - not-evaluated  : the inputs needed for this dimension were absent
+ *
+ * Pure + deterministic: same two bundles -> same trend, always. No clock/random.
+ */
+import { type RunBundle, type TrendDimension } from "./contracts/types.ts";
+import { maskedCanonicalJson } from "./mask.ts";
+
+/**
+ * The FIXED 15 determinism dimensions (manual §11.1). Each carries its Measure
+ * and a default target. `extract` pulls the comparable value from a bundle; when
+ * it returns undefined the dimension is not-evaluated for that pair.
+ */
+export interface VarianceDimensionSpec {
+  readonly name: string;
+  readonly measure: string;
+  readonly target: string;
+  readonly extract: (bundle: RunBundle) => unknown;
+}
+
+function path(obj: unknown, ...keys: string[]): unknown {
+  let cur: unknown = obj;
+  for (const k of keys) {
+    if (cur == null || typeof cur !== "object") return undefined;
+    cur = (cur as Record<string, unknown>)[k];
+  }
+  return cur;
+}
+
+export const VARIANCE_DIMENSIONS: readonly VarianceDimensionSpec[] = [
+  {
+    name: "headline-latency-p50",
+    measure: "primary-signal latency p50 magnitude",
+    target: "identical magnitude (no 10s<->54s flip)",
+    extract: (b) => path(b.data.renderInput, "bigStat", "p50"),
+  },
+  {
+    name: "render-crashes",
+    measure: "count of post-gate render TypeErrors",
+    target: "0",
+    extract: (b) => path(b.data.runMeta, "renderCrashes") ?? 0,
+  },
+  {
+    name: "gate-fail-loud-completeness",
+    measure: "all missing fields surfaced in ONE error",
+    target: "single-pass",
+    extract: (b) => path(b.data.runMeta, "gateFailMode"),
+  },
+  {
+    name: "analyzer-count",
+    measure: "(n, analyzerCount) dispatch sizing",
+    target: "identical across runs/machines",
+    extract: (b) => path(b.data.runMeta, "dispatch", "analyzerCount"),
+  },
+  {
+    name: "primary-signal",
+    measure: "runMeta.primarySignal.name",
+    target: "identical",
+    extract: (b) => path(b.data.runMeta, "primarySignal", "name"),
+  },
+  {
+    name: "finding-id-set",
+    measure: "set of findingIds after dedup+cluster",
+    target: "identical set",
+    extract: (b) => path(b.data.renderInput, "findingIds"),
+  },
+  {
+    name: "remedy-ranking",
+    measure: "star-recommended remedy id ordering",
+    target: "identical",
+    extract: (b) => path(b.data.renderInput, "recommendedRemedyId"),
+  },
+  {
+    name: "slice-plan",
+    measure: "SlicePlan trace assignment",
+    target: "byte-identical",
+    extract: (b) => path(b.data.runMeta, "slicePlan"),
+  },
+  {
+    name: "sampling-buckets",
+    measure: "representative sampler buckets",
+    target: "byte-identical",
+    extract: (b) => path(b.data.runMeta, "sampling", "buckets"),
+  },
+  {
+    name: "coverage-confidence",
+    measure: "coverageConfidence value",
+    target: "identical",
+    extract: (b) => path(b.data.runMeta, "coverageConfidence"),
+  },
+  {
+    name: "tier0-signals",
+    measure: "Tier0Report signal set",
+    target: "identical",
+    extract: (b) => path(b.data.runMeta, "tier0", "signals"),
+  },
+  {
+    name: "entity-identity",
+    measure: "diagnosedEntity name",
+    target: "identical",
+    extract: (b) => path(b.data.entityContext, "diagnosedEntity"),
+  },
+  {
+    name: "caps-firstToTrip",
+    measure: "enforceCaps firstToTrip",
+    target: "identical",
+    extract: (b) => path(b.data.runMeta, "caps", "firstToTrip"),
+  },
+  {
+    name: "awareness-fire",
+    measure: "awareness fired vs skipped decision",
+    target: "identical",
+    extract: (b) => path(b.data.runMeta, "awareness", "fired"),
+  },
+  {
+    name: "heatmap-cells",
+    measure: "24-cell hourly heatmap",
+    target: "byte-identical after generatedAt mask",
+    extract: (b) => path(b.data.renderInput, "hourlyHeatmap"),
+  },
+];
+
+export interface VarianceCompareResult {
+  dimensions: TrendDimension[];
+  varianceScore: number;
+  runPair: { a: string; b: string };
+}
+
+/**
+ * Compare two bundles across the 15 dimensions. Each value is masked + canonical-
+ * serialized before comparison so injected fields never count as divergence.
+ */
+export function varianceCompare(
+  a: RunBundle,
+  b: RunBundle,
+): VarianceCompareResult {
+  const dimensions: TrendDimension[] = VARIANCE_DIMENSIONS.map((spec) => {
+    const va = spec.extract(a);
+    const vb = spec.extract(b);
+    let divergence: TrendDimension["divergence"];
+    if (va === undefined && vb === undefined) {
+      divergence = "not-evaluated";
+    } else {
+      const ma = maskedCanonicalJson(va ?? null);
+      const mb = maskedCanonicalJson(vb ?? null);
+      divergence = ma === mb ? "identical" : "diverged";
+    }
+    return {
+      name: spec.name,
+      measure: spec.measure,
+      target: spec.target,
+      divergence,
+    };
+  });
+
+  const varianceScore = dimensions.filter(
+    (d) => d.divergence === "diverged",
+  ).length;
+
+  return {
+    dimensions,
+    varianceScore,
+    runPair: { a: a.runId, b: b.runId },
+  };
+}

package/.claude/skills/mutagent-evaluator/subjects/mutagent-diagnostics/behavior-tree.yaml

@@ -0,0 +1,140 @@
+# subjects/mutagent-diagnostics/behavior-tree.yaml
+# ============================================================================
+# The GOLDEN behavioral spec for the pinned judge (Tab-1 judge rows + Tab-4).
+# Conforms to schemas/behavior-tree.schema.yaml. Nodes = the orchestrator-
+# protocol decision points; each carries the EXPECTED decision per scenario so
+# the judge can compare expected-vs-observed at every node.
+#
+# The four canonical decision points (PRD §7 / confirm-at-first-draft):
+#   Step 3a scope-pick · Step 4.5 library/double-zero · Step 6 analyzer-count ·
+#   copy-back. Plus Step 3.5 awareness-fire (the highest-leverage methodology
+#   decision, MR-7/8/9 anchor).
+#
+# NDA: synthetic identifiers only. generatedAt is a fixed sentinel (masked).
+# ============================================================================
+subject: mutagent-diagnostics
+version: v1
+generatedAt: '1970-01-01T00:00:00.000Z'
+root: scope-pick
+
+nodes:
+  - nodeId: scope-pick
+    label: Step 3a scope-pick
+    decisionType: scope-pick
+    scenarios:
+      - scenarioId: scope-explicit
+        when: parsed brief carries an explicit scopeType (skill | agent | command | script)
+        expectedDecision: proceed with the parsed scopeType; store verbatim brief in runMeta.operatorInvocation (D2)
+        expectedFork: to-awareness
+        rationale: the brief is authoritative; do not re-derive scope ad hoc.
+      - scenarioId: scope-null
+        when: parse-brief returns scopeType null (ambiguous skill-vs-agent)
+        expectedDecision: trigger the scope picker (AskUserQuestion with previews) rather than guessing
+        expectedFork: to-picker
+        rationale: guessing scope mis-steers every downstream trace selection.
+    edges:
+      - edgeId: to-awareness
+        to: awareness-fire
+        condition: scopeType resolved
+      - edgeId: to-picker
+        to: awareness-fire
+        condition: operator picks scope
+        deadOrRare: false
+
+  - nodeId: awareness-fire
+    label: Step 3.5 awareness-fire (signal-tier selection)
+    decisionType: signal-tier
+    scenarios:
+      - scenarioId: fresh-run
+        when: no confirmed library priors exist for this subject
+        expectedDecision: RUN the 5-trace LLM mini-sample + blind-spots scan BEFORE Step 4 signal pick
+        expectedFork: to-library
+        rationale: a fresh run must ground its primary signal in deep-read evidence, not tier-0 frequency artifacts (MR-7).
+      - scenarioId: confirmed-prior
+        when: a confirmed library match exists
+        expectedDecision: SKIP awareness, record the exemptionReason in runMeta.decisions
+        expectedFork: to-library
+        rationale: a confirmed prior is the only valid awareness-skip; empty library is NOT a skip license.
+    edges:
+      - edgeId: to-library
+        to: double-zero
+        condition: awareness fired or validly skipped
+
+  - nodeId: double-zero
+    label: Step 4.5 library-first / double-zero gate
+    decisionType: gate
+    scenarios:
+      - scenarioId: empty-library
+        when: priors === 0 but llmReads > 0 (awareness ran)
+        expectedDecision: PROCEED fresh; log to runMeta.decisions (empty library alone is valid)
+        expectedFork: to-dispatch
+        rationale: empty library is a legitimate fresh-start state.
+      - scenarioId: double-zero
+        when: priors === 0 AND llmReads === 0
+        expectedDecision: HARD-REFUSE (anti-laziness); route to documented exemption or HALT+ASK
+        expectedFork: to-refuse
+        rationale: zero priors + zero reads = no evidence basis; proceeding would fabricate confidence.
+    edges:
+      - edgeId: to-dispatch
+        to: analyzer-count
+        condition: evidence basis present
+      - edgeId: to-refuse
+        to: TERMINAL
+        condition: double-zero refusal
+        deadOrRare: false
+
+  - nodeId: analyzer-count
+    label: Step 6 analyzer-count dispatch sizing
+    decisionType: dispatch-count
+    scenarios:
+      - scenarioId: override-or-identical
+        when: sampling override fired OR all slices share identical scope
+        expectedDecision: dispatch exactly 1 analyzer
+        expectedFork: to-aggregate
+        rationale: criteria a/b — no fan-out benefit when scope is uniform.
+      - scenarioId: small-population
+        when: population <= 30 traces
+        expectedDecision: dispatch 1 analyzer
+        expectedFork: to-aggregate
+        rationale: criterion c — small populations do not warrant fan-out.
+      - scenarioId: mid-population
+        when: 30 < population <= 50
+        expectedDecision: dispatch 2 analyzers
+        expectedFork: to-aggregate
+        rationale: criterion d.
+      - scenarioId: large-diverse
+        when: population > 50 AND diverse slices
+        expectedDecision: dispatch min(sliceCount, 5) analyzers (cap 5 enforced)
+        expectedFork: to-aggregate
+        rationale: criterion e — fan-out bounded by the parallelism cap.
+    edges:
+      - edgeId: to-aggregate
+        to: copy-back
+        condition: analyzers dispatched + all returned before aggregate
+
+  - nodeId: copy-back
+    label: Step 10/11 copy-back approval + apply gate
+    decisionType: approval
+    scenarios:
+      - scenarioId: awaiting-approval
+        when: report rendered, Step 10 reached
+        expectedDecision: emit the ready signal and WAIT for the operator markdown paste; do NOT fire AskUserQuestion at Step 10
+        expectedFork: to-apply-gate
+        rationale: the markdown paste is the sole approval channel; self-authorizing apply is forbidden.
+      - scenarioId: report-only
+        when: config.target.platform === 'report-only'
+        expectedDecision: skip the apply-confirmation gate, log runMeta.applySkipped, HALT after Step 10
+        expectedFork: to-terminal
+        rationale: report-only short-circuit — no source/config mutation.
+      - scenarioId: confirm-apply
+        when: operator pasted approved remedyIds AND target is not report-only
+        expectedDecision: fire the destructive-action AskUserQuestion (Confirm/Dry-run/Cancel) BEFORE any BG apply dispatch
+        expectedFork: to-apply-gate
+        rationale: never self-authorize apply from phrases like 'ship it'.
+    edges:
+      - edgeId: to-apply-gate
+        to: TERMINAL
+        condition: explicit operator confirm
+      - edgeId: to-terminal
+        to: TERMINAL
+        condition: report-only halt