@mutagent/helix 0.1.0-alpha.14

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/scripts/judge-prompt-template.ts

@@ -0,0 +1,253 @@
+/**
+ * scripts/judge-prompt-template.ts — EV-050 judge-PROMPT renderer + in-house/export run wrappers.
+ * ---------------------------------------------------------------------------
+ * The ONE place a judge prompt is rendered into a provider-callable string. This
+ * is the operator-named **exception** to the script-austerity rule: "a script
+ * that EXTRACTS/EXPORTS a custom LLM-as-judge PROMPT artifact (for the user's
+ * CI/framework, EV-050) is fine — that's templating, not skill-triggered
+ * judging." It exists for exactly two consumers:
+ *
+ *   (1) the OPTIONAL **in-house** provider substrate (`judge-provider.ts` →
+ *       @langchain/google-genai) — it has no subagent, so it MUST carry the
+ *       rendered prompt to call the model;
+ *   (2) **user-framework export** (Vitest / promptfoo / Braintrust) — emit the
+ *       judge prompt as an artifact for the user's own CI.
+ *
+ * **The DEFAULT agent-dispatch path NEVER imports this file.** Under
+ * agent-dispatch the AUTHORITATIVE judging rubric lives in the subagent defs
+ * (`assets/agents/{error-analyst,eval-judge,eval-matrix-judge}.md`); the host
+ * runtime reasons from the def + the DATA packet, and the verdict file is keyed
+ * by task DATA (trajectory id / criterion id), not by a rendered prompt. The
+ * prose below is a MIRROR of those defs for the provider path — the defs are the
+ * source of truth; keep them in lockstep.
+ *
+ * `determine-outcome.ts` + `build-evals.ts` are therefore slimmed to Type-A DATA
+ * only (signals · parse · assemble · spec · split · leakage-guard). The
+ * LLM-wrapper run functions (`determineOutcome` / `runJudge`) live HERE because
+ * they call the injected `JudgeInvoke` seam.
+ */
+import {
+  extractOutcomeSignals,
+  parseCritiqueVerdict,
+  type JudgeInvoke,
+} from "./determine-outcome.ts";
+import type { JudgePin } from "./build-evals.ts";
+import type { SubjectProfile } from "./contracts/eval-matrix.ts";
+import type {
+  CriterionVerdict,
+  EvalTrace,
+  JudgeSpec,
+  OutcomeResult,
+  OutcomeSignals,
+  SubjectVocab,
+} from "./contracts/eval-types.ts";
+
+function promptOf(trace: EvalTrace): string {
+  return typeof trace.input?.prompt === "string" ? trace.input.prompt : "";
+}
+
+// ── Determiner (EV-042) prompt — MIRRORS assets/agents/error-analyst.md ──────
+
+/**
+ * Render the determiner judge prompt for the in-house/export substrate. The
+ * AUTHORITATIVE "inaction can be success" rubric is `error-analyst.md`; this is
+ * its provider-callable mirror. No decision is made here.
+ */
+export function buildOutcomePrompt(
+  trace: EvalTrace,
+  signals: OutcomeSignals,
+  vocab: SubjectVocab,
+): { system: string; user: string } {
+  const system = [
+    "You are a success/failure determiner for an autonomous agent session.",
+    "Decide whether the session REACHED THE GOAL implied by its input event.",
+    "",
+    "CRITICAL RULE — inaction can be success. Holding (sending nothing, calling",
+    "no tool) is the CORRECT outcome when the event is a restraint directive",
+    "(e.g. a guard/hold directive) or when acting would be wrong. You MUST NOT",
+    'use "the agent called a tool" or "the agent sent a message" as a success',
+    "proxy. A zero-tool session that correctly HOLDS is a PASS.",
+    "",
+    "Output STRICT JSON with the critique BEFORE the verdict:",
+    '{ "critique": "<your reasoning>", "result": "pass"|"fail"|"uncertain",',
+    '  "confidence": <0..1> }',
+    "Reason first in `critique`, then commit to `result`.",
+  ].join("\n");
+
+  // Generic guard-counter label — the attribute NAME comes from the subject vocab.
+  const guardLabel = vocab.guardCounterAttr ?? "guard counter";
+  const user = [
+    `Event kind: ${signals.eventKind}`,
+    `Guard ${guardLabel}: ${signals.guardConsecutive ?? "n/a"}`,
+    `Tools called: ${signals.toolCount}`,
+    // EV-049 honest-null: render UNKNOWN as "unknown" (the subject's send tool is
+    // unset/uninferred) — never coerce it to "false", which would lie to the judge.
+    `Sent a message: ${signals.sentMessage === null ? "unknown" : signals.sentMessage}`,
+    `Send succeeded: ${signals.sendSucceeded ?? "n/a (no send)"}`,
+    `Recovery tool present: ${signals.recoveryPresent}`,
+    "",
+    "Input event prompt:",
+    promptOf(trace),
+    "",
+    "Agent self-summary (output.response):",
+    typeof trace.output?.response === "string" ? trace.output.response : "(none)",
+  ].join("\n");
+
+  return { system, user };
+}
+
+/**
+ * In-house/export run wrapper for the determiner: render → call the injected
+ * `JudgeInvoke` seam → parse (critique-before-verdict). Under the DEFAULT
+ * agent-dispatch substrate the verdict instead comes from a dispatched
+ * error-analyst subagent (a verdict file), and this wrapper is not used.
+ * Deterministic given (trace, judge).
+ */
+export async function determineOutcome(
+  trace: EvalTrace,
+  judge: JudgeInvoke,
+  vocab: SubjectVocab,
+): Promise<OutcomeResult> {
+  const signals = extractOutcomeSignals(trace, vocab);
+  const { system, user } = buildOutcomePrompt(trace, signals, vocab);
+  const raw = await judge(system, user);
+  const verdict = parseCritiqueVerdict(raw);
+  return {
+    traceId: trace.id,
+    reached: verdict.result as OutcomeResult["reached"],
+    confidence: verdict.confidence,
+    rationale: verdict.critique,
+    signals,
+  };
+}
+
+// ── Per-criterion judge (EV-043) prompt — MIRRORS assets/agents/eval-judge.md ─
+
+/** Compact one trace for the judge's view (prompt + trajectory + response). */
+function traceView(trace: EvalTrace): string {
+  const prompt = typeof trace.input?.prompt === "string" ? trace.input.prompt : "";
+  const tools = trace.observations
+    .filter((o) => o.type === "TOOL")
+    .map((o) => o.name ?? "?")
+    .join(", ");
+  const resp = typeof trace.output?.response === "string" ? trace.output.response : "(none)";
+  return [
+    `Event/prompt:\n${prompt}`,
+    `Tool trajectory: [${tools}]`,
+    `Agent self-summary: ${resp}`,
+  ].join("\n");
+}
+
+/** Render the M1 subject-profile preamble for the provider-path mirror (§9.4.4). */
+function profilePreamble(profile?: SubjectProfile): string[] {
+  if (profile === undefined) {
+    return [
+      "SUBJECT PROFILE (M1): not supplied — RECONSTRUCT who the agent is from the trace",
+      "(its tools, the input it handled, its evident scope) before you judge. Mark the",
+      "harness `unknown` if you cannot know it — NEVER confabulate it.",
+      "",
+    ];
+  }
+  return [
+    "SUBJECT PROFILE (M1) — who the agent is (read this BEFORE judging):",
+    `  identity: ${profile.identity}`,
+    `  purpose:  ${profile.purpose}`,
+    `  scope:    ${profile.scope}`,
+    `  tools:    ${(profile.tools ?? []).join(", ") || "(none observed)"}`,
+    profile.skill !== undefined ? `  skill:    ${profile.skill}` : "",
+    `  harness:  ${profile.harness}`,
+    `  provenance: ${profile.provenance}${profile.version !== undefined ? ` · version ${profile.version}` : ""}`,
+    "",
+  ].filter((l) => l !== "");
+}
+
+/**
+ * Render the 4-component per-criterion judge prompt for the in-house/export
+ * substrate. The AUTHORITATIVE 4-component / binary / critique-before-verdict
+ * rubric is `eval-judge.md` (+ §9.4.4 M1–M5); this is its provider-callable mirror.
+ */
+export function buildJudgePrompt(
+  spec: JudgeSpec,
+  subjectTrace: EvalTrace,
+  subjectProfile?: SubjectProfile,
+): { system: string; user: string } {
+  const fewShotBlock = spec.fewShot
+    .map(
+      (ex, i) =>
+        `Example ${i + 1} (${ex.label}):\nCritique: ${ex.why}\nResult: ${ex.label}`,
+    )
+    .join("\n\n");
+
+  const system = [
+    "You are a BINARY Pass/Fail judge for ONE criterion. Judge exactly this and",
+    "nothing else.",
+    "",
+    ...profilePreamble(subjectProfile),
+    `Criterion: ${spec.statement}`,
+    spec.passDefinition,
+    spec.failDefinition,
+    "",
+    "JUDGE-WHAT-IS (M5): judge ONLY this defined criterion. If you notice a real",
+    "failure with no matching criterion, you MAY note it as a detection — but NEVER",
+    "mint a new eval or judge an undefined behaviour here.",
+    "",
+    "Outcomes are strictly BINARY: pass or fail (use uncertain ONLY if the trace",
+    "genuinely lacks the evidence to decide). NO Likert scales, NO 1-5 / letter",
+    "grades, NO partial credit — if severity matters, that is a separate judge.",
+    "",
+    spec.fewShot.length > 0 ? `Few-shot examples (from the TRAIN split only):\n${fewShotBlock}` : "",
+    "",
+    "Output STRICT JSON with the critique BEFORE the verdict (reason first, then",
+    "commit). Follow the Judge DAG v2.2 walk (§9.4.2 + §9.4.4): GATHER (M2 — rephrase",
+    "the agent's job in your own words, mark given-vs-inferred) → EXPECT (M3 — decide",
+    "how the target SHOULD act BEFORE you examine) → EXAMINE actual-vs-expected (a",
+    "truncated trace HARD short-circuits — emit INCOMPLETE and score NO criteria, never",
+    "a row of abstains) → BIND → GROUND (absence-split: a bare-absence inferred from",
+    "silence abstains, never fails) → CRITIQUE → DECIDE. Expose your train-of-thought at",
+    "every phase (M4). Emit a `confidenceBand` (high|med|low) BESIDE the binary verdict",
+    "— a calibration side-signal, NOT a Likert grade; it never alters `result`:",
+    '{ "critique": "<detailed, evidence-citing assessment>", "result":',
+    '  "pass"|"fail"|"uncertain", "confidence": <0..1>,',
+    '  "confidenceBand": "high"|"med"|"low" }',
+  ].join("\n");
+
+  const user = ["Subject trace under evaluation:", "", traceView(subjectTrace)].join("\n");
+  return { system, user };
+}
+
+/**
+ * In-house/export run wrapper for one per-criterion judge under a PINNED model.
+ * THROWS if the pin is not (modelId present AND temperature===0) — model intent
+ * is sacred (C-PIN). Renders → calls the injected `JudgeInvoke` seam → parses
+ * (critique-before-verdict). Under agent-dispatch the verdict instead comes from
+ * a dispatched eval-judge subagent (a verdict file).
+ */
+export async function runJudge(
+  spec: JudgeSpec,
+  subjectTrace: EvalTrace,
+  judge: JudgeInvoke,
+  pin: JudgePin,
+): Promise<CriterionVerdict> {
+  if (typeof pin.modelId !== "string" || pin.modelId.length === 0) {
+    throw new Error(
+      "runJudge: judge is not pinned (missing modelId). MODEL INTENT IS SACRED " +
+        "— a non-pinned judge can never produce a verdict (C-PIN).",
+    );
+  }
+  if (pin.temperature !== 0) {
+    throw new Error(
+      `runJudge: judge temperature=${pin.temperature} (!= 0) — not pinned. ` +
+        "MODEL INTENT IS SACRED: reruns must be byte-identical (C-PIN); refusing.",
+    );
+  }
+  const { system, user } = buildJudgePrompt(spec, subjectTrace);
+  const raw = await judge(system, user);
+  const verdict = parseCritiqueVerdict(raw);
+  return {
+    criterionId: spec.criterionId,
+    traceId: subjectTrace.id,
+    result: verdict.result as OutcomeResult["reached"],
+    confidence: verdict.confidence,
+    critique: verdict.critique,
+  };
+}

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

@@ -0,0 +1,135 @@
+/**
+ * scripts/judge-provider.ts — EV-050 in-house judge transport (the default substrate).
+ * ---------------------------------------------------------------------------
+ * The in-house AI-SDK judge: the @langchain/google-genai ChatGoogleGenerativeAI
+ * shape proven in the orchestrator's eval-routing.ts (temp 0, model resolved
+ * from --model | config.models.default, THROW on unsupported/missing creds).
+ * Re-implemented here (sealed-sibling: the SHAPE is mirrored, the orchestrator
+ * module is never imported).
+ *
+ * DI split (model intent sacred): construction asserts a supported model + creds
+ * SYNCHRONOUSLY — no swap, no silent fallback. The provider SDK is imported
+ * LAZILY, only when the returned JudgeInvoke is actually CALLED, so the
+ * deterministic gate (which never calls it) never loads a provider. The CLI /
+ * an opt-in integration seam are the only callers of the returned function.
+ */
+import type { JudgeInvoke } from "./determine-outcome.ts";
+
+/** A minimal ctor shape for ChatGoogleGenerativeAI (avoids a type-time SDK dep). */
+interface ChatGoogleCtor {
+  new (opts: { model: string; temperature: number; apiKey: string }): {
+    invoke: (messages: [string, string][]) => Promise<{ content: unknown }>;
+  };
+}
+
+/** Detect the provider implied by a model id. Closed + explicit (no fuzzing). */
+export function detectProvider(model: string): "google" | "unsupported" {
+  return /^gemini/i.test(model) ? "google" : "unsupported";
+}
+
+/** Assert the model has a wired provider. THROWS (no swap) if not — model intent sacred. */
+export function assertSupportedModel(model: string): void {
+  if (detectProvider(model) === "unsupported") {
+    throw new Error(
+      `judge-provider: model '${model}' has no provider wired (only Google/` +
+        "gemini-* is wired). MODEL INTENT IS SACRED: this will NOT silently swap " +
+        "to another model/provider. Pass a supported --model, or wire its " +
+        "provider (mirror the repo call shape) — never substitute.",
+    );
+  }
+}
+
+/** Assert creds are present. Takes the key EXPLICITLY (env-independent → testable). */
+export function assertCreds(apiKey: string | undefined): string {
+  if (apiKey === undefined || apiKey === "") {
+    throw new Error(
+      "judge-provider: GOOGLE_API_KEY is not set. Source the env first " +
+        "(set -a && source mutagent-core/.env && source mutagent/.env && set +a). " +
+        "NOT substituting another provider (model intent is sacred).",
+    );
+  }
+  return apiKey;
+}
+
+export interface ModelDecision {
+  model: string;
+  source: "--model" | "config.models.default";
+}
+
+/**
+ * Resolve the judge model: explicit --model wins (an intentional override, NOT
+ * a silent swap), else config.models.default, else REFUSE. PURE — the caller
+ * passes the values; this never reads a file or env.
+ */
+export function resolveJudgeModel(opts: {
+  model?: string;
+  configDefault?: string;
+}): ModelDecision {
+  if (opts.model !== undefined && opts.model !== "") {
+    return { model: opts.model, source: "--model" };
+  }
+  if (opts.configDefault !== undefined && opts.configDefault !== "") {
+    return { model: opts.configDefault, source: "config.models.default" };
+  }
+  throw new Error(
+    "resolveJudgeModel: no model resolved. Pass --model <id>, or set " +
+      "shared.models.default. MODEL INTENT IS SACRED: the harness will not pick " +
+      "a model for you.",
+  );
+}
+
+/** Coerce a LangChain message `content` (string | content-blocks) to plain text. */
+function extractContentText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => {
+        if (typeof part === "string") return part;
+        if (
+          part !== null &&
+          typeof part === "object" &&
+          "text" in part &&
+          typeof (part as { text: unknown }).text === "string"
+        ) {
+          return (part as { text: string }).text;
+        }
+        return "";
+      })
+      .join("");
+  }
+  return content === undefined || content === null ? "" : String(content);
+}
+
+export interface InHouseJudgeOptions {
+  model: string;
+  /** explicit key; falls back to process.env.GOOGLE_API_KEY when omitted. */
+  apiKey?: string;
+}
+
+/**
+ * Build the in-house JudgeInvoke. Asserts model + creds SYNCHRONOUSLY (so a
+ * misconfiguration fails fast, in the caller, not deep in an async call). The
+ * SDK is imported LAZILY inside the returned function — the gate never reaches
+ * that path. temperature is pinned to 0 (C-PIN: byte-identical reruns).
+ */
+export function createInHouseJudge(opts: InHouseJudgeOptions): JudgeInvoke {
+  assertSupportedModel(opts.model);
+  const apiKey = assertCreds(opts.apiKey ?? process.env.GOOGLE_API_KEY);
+
+  return async (systemPrompt: string, userPrompt: string): Promise<string> => {
+    // Lazy import — the deterministic harness never loads the provider SDK.
+    const mod = (await import("@langchain/google-genai")) as unknown as {
+      ChatGoogleGenerativeAI: ChatGoogleCtor;
+    };
+    const client = new mod.ChatGoogleGenerativeAI({
+      model: opts.model,
+      temperature: 0, // judging is a classification — pinned deterministic decoding
+      apiKey,
+    });
+    const response = await client.invoke([
+      ["system", systemPrompt],
+      ["human", userPrompt],
+    ]);
+    return extractContentText(response.content);
+  };
+}

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/scripts/lint-grounding.ts

@@ -0,0 +1,229 @@
+/**
+ * scripts/lint-grounding.ts — GA the deterministic grounding-lint floor (L3).
+ * ---------------------------------------------------------------------------
+ * A pure, code-only lint that runs BEFORE any judgement and enforces the cheap,
+ * mechanical grounding hygiene the LLM should never have to be trusted with:
+ *
+ *   R1 assumption-token-without-surfaced-assumption — text that hedges
+ *      ("assume", "presumably", "likely", "should", "expected to", …) WITHOUT a
+ *      surfaced assumption is a hidden premise → flag.
+ *   R2 every claim → resolvable ref (L2 floor) — a judge-class `observed`
+ *      criterion must cite ≥1 ref (and, when traces are supplied, ≥1 must
+ *      RE-RESOLVE exact-match). Code-class rows verify FREE → exempt.
+ *   R3 ground absence (L3) — an OBSERVED judge-class absence claim ("did not",
+ *      "never", "no X", "missing", "without") needs a positive check of the
+ *      field where X would be → ≥1 cited ref that re-resolves. Scoped to
+ *      `observed` (mirrors R2): an INFERRED criterion deliberately empties its
+ *      refs, so its absence wording is a good-practice guard, NOT flagged.
+ *
+ * GRANDFATHER (regression-safety rule #3): findings on a NEWLY-MINTED artifact
+ * are ERRORS (`ok=false`); findings on a PRE-EXISTING artifact are WARNINGS
+ * (`ok=true`). `isNew` selects which — never retroactively voids old evals.
+ *
+ * PURE — no clock/random/network. Deterministic findings in criterion order.
+ */
+import {
+  Grounding,
+  MetricSubstrate,
+  assertGroundingHonest,
+  type CriterionVerdict,
+  type EvalTrace,
+  type MinedCriterion,
+} from "./contracts/eval-types.ts";
+
+/** Hedge tokens that signal an un-surfaced assumption (R1). */
+const ASSUMPTION_TOKENS: readonly string[] = [
+  "assume",
+  "assuming",
+  "presumably",
+  "probably",
+  "likely",
+  "should be",
+  "should have",
+  "expected to",
+  "i think",
+  "seems to",
+  "appears to",
+  "must have",
+];
+
+/** Absence-claim tokens (R3) — a negative claim needs a positive field check. */
+const ABSENCE_TOKENS: readonly string[] = [
+  "did not",
+  "didn't",
+  "never",
+  "no ",
+  "not ",
+  "missing",
+  "without",
+  "absent",
+  "failed to",
+];
+
+export interface LintFinding {
+  criterionId: string;
+  rule: "R1-assumption-token" | "R2-claim-needs-ref" | "R3-ground-absence";
+  level: "error" | "warn";
+  message: string;
+}
+
+export interface LintOptions {
+  /** newly-minted artifact ⇒ findings are ERRORS; pre-existing ⇒ WARNINGS. */
+  isNew?: boolean;
+  /** trace batch for R2 exact re-resolution (optional — structural-only if absent). */
+  traces?: EvalTrace[];
+}
+
+export interface LintResult {
+  findings: LintFinding[];
+  errorCount: number;
+  warnCount: number;
+  /** false iff ≥1 ERROR-level finding (only possible on a new artifact). */
+  ok: boolean;
+}
+
+function lower(s: string): string {
+  return s.toLowerCase();
+}
+
+function hasToken(haystack: string, tokens: readonly string[]): boolean {
+  const h = lower(haystack);
+  return tokens.some((t) => h.includes(t));
+}
+
+/** Is this criterion a CODE-class row (verifies FREE → exempt from R2/R3)? */
+function isCodeClass(c: MinedCriterion): boolean {
+  return c.metadata.substrate === MetricSubstrate.Code;
+}
+
+/** Lint ONE mined criterion. Returns findings (level fixed by `isNew`). PURE. */
+export function lintGroundingCriterion(
+  c: MinedCriterion,
+  opts: LintOptions = {},
+): LintFinding[] {
+  const level: LintFinding["level"] = opts.isNew === true ? "error" : "warn";
+  const out: LintFinding[] = [];
+  const text = `${c.statement} ${c.discovery.targets} ${c.discovery.why_problem} ${c.discovery.reasoning}`;
+  const surfaced = c.discovery.assumptions.length > 0;
+
+  // R1 — hedge token without a surfaced assumption.
+  if (hasToken(text, ASSUMPTION_TOKENS) && !surfaced) {
+    out.push({
+      criterionId: c.id,
+      rule: "R1-assumption-token",
+      level,
+      message:
+        "text hedges (assumption token present) but surfaces NO assumption — " +
+        "a hidden premise; surface it as a typed assumption.",
+    });
+  }
+
+  const observed = c.discovery.evidence.grounding === Grounding.Observed;
+  const codeFree = isCodeClass(c);
+
+  // R2 — judge-class observed claim must cite ≥1 (re-resolving) ref.
+  if (observed && !codeFree) {
+    if (c.discovery.evidence.refs.length === 0) {
+      out.push({
+        criterionId: c.id,
+        rule: "R2-claim-needs-ref",
+        level,
+        message: "observed (judge-class) criterion cites NO refs — every claim needs a resolvable ref.",
+      });
+    } else if (opts.traces !== undefined && opts.traces.length > 0) {
+      let resolves = true;
+      try {
+        assertGroundingHonest(c, opts.traces);
+      } catch {
+        resolves = false;
+      }
+      if (!resolves) {
+        out.push({
+          criterionId: c.id,
+          rule: "R2-claim-needs-ref",
+          level,
+          message: "observed criterion's refs do NOT re-resolve exact-match against the trace batch.",
+        });
+      }
+    }
+  }
+
+  // R3 — absence claim on an OBSERVED judge-class row needs a positive field
+  // check (a re-resolving ref). Scoped to `observed && !codeFree` to MIRROR R2:
+  // an INFERRED criterion deliberately empties its refs (deriveMinedCriteria) —
+  // its absence wording is a good-practice guard, not an ungrounded observation,
+  // so it must NOT trigger R3. The observed path is NOT weakened: an observed
+  // absence claim with no ref — OR with a ref that does not re-resolve against
+  // the supplied trace batch — still fires.
+  if (observed && !codeFree && hasToken(text, ABSENCE_TOKENS)) {
+    if (c.discovery.evidence.refs.length === 0) {
+      out.push({
+        criterionId: c.id,
+        rule: "R3-ground-absence",
+        level,
+        message:
+          "observed (judge-class) absence claim ('did not'/'never'/'no …') with no " +
+          "cited ref — ground the absence with a positive check of the field where " +
+          "the behavior would appear.",
+      });
+    } else if (opts.traces !== undefined && opts.traces.length > 0) {
+      let resolves = true;
+      try {
+        assertGroundingHonest(c, opts.traces);
+      } catch {
+        resolves = false;
+      }
+      if (!resolves) {
+        out.push({
+          criterionId: c.id,
+          rule: "R3-ground-absence",
+          level,
+          message:
+            "observed (judge-class) absence claim's ref does NOT re-resolve exact-match " +
+            "against the trace batch — ground the absence with a positive field check.",
+        });
+      }
+    }
+  }
+
+  return out;
+}
+
+/** Lint a batch of mined criteria. PURE — deterministic, criterion order. */
+export function lintGrounding(
+  criteria: MinedCriterion[],
+  opts: LintOptions = {},
+): LintResult {
+  const findings = criteria.flatMap((c) => lintGroundingCriterion(c, opts));
+  const errorCount = findings.filter((f) => f.level === "error").length;
+  const warnCount = findings.filter((f) => f.level === "warn").length;
+  return { findings, errorCount, warnCount, ok: errorCount === 0 };
+}
+
+/**
+ * Lint a JUDGE VERDICT (the GA `*build-evals`/`*evaluate` floor): R1 hedge
+ * tokens in the critique without a surfaced assumption, and an `uncertain`
+ * verdict that carries NO `blockedBy` (an unrouted abstain). PURE.
+ */
+export function lintVerdict(v: CriterionVerdict, opts: LintOptions = {}): LintFinding[] {
+  const level: LintFinding["level"] = opts.isNew === true ? "error" : "warn";
+  const out: LintFinding[] = [];
+  const surfaced = (v.assumptions?.length ?? 0) > 0 || v.blockedBy !== undefined;
+  if (hasToken(v.critique, ASSUMPTION_TOKENS) && !surfaced) {
+    out.push({
+      criterionId: v.criterionId,
+      rule: "R1-assumption-token",
+      level,
+      message: "critique hedges but surfaces no assumption / blockedBy — a hidden premise.",
+    });
+  }
+  if (v.result === "uncertain" && v.blockedBy === undefined) {
+    out.push({
+      criterionId: v.criterionId,
+      rule: "R3-ground-absence",
+      level,
+      message: "uncertain verdict with NO blockedBy — an unrouted abstain; type the blocker.",
+    });
+  }
+  return out;
+}