@mutagent/helix 0.1.0-alpha.14

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/scripts/cli/variance-check.ts

@@ -0,0 +1,105 @@
+/**
+ * scripts/cli/variance-check.ts — coordinator entrypoint.
+ * ---------------------------------------------------------------------------
+ * The COORDINATOR role (executor != reviewer): compares TWO run bundles on the
+ * fixed 15-dim determinism scorecard and emits the delta + trend. This is fully
+ * deterministic — no judge, no model — so it runs as a complete wired script.
+ *
+ *   variance-check.ts <bundleDirA> <bundleDirB> [--out <scorecard.json>]
+ *                     [--generated-at <iso>] [--emit-masked]
+ */
+import { writeFileSync } from "node:fs";
+import { loadBundle } from "../load-bundle.ts";
+import { varianceCompare } from "../variance-compare.ts";
+import { assembleScorecard } from "../assemble-scorecard.ts";
+import { maskedCanonicalJson } from "../mask.ts";
+import { DEFAULT_GENERATED_AT } from "./audit-run.ts";
+
+interface Args {
+  a: string;
+  b: string;
+  out?: string;
+  generatedAt: string;
+  emitMasked: boolean;
+}
+
+function parseArgs(argv: string[]): Args {
+  const positional: string[] = [];
+  const flags: Record<string, string | boolean> = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) {
+        flags[key] = next;
+        i++;
+      } else flags[key] = true;
+    } else positional.push(a);
+  }
+  if (positional.length < 2) {
+    throw new Error(
+      "usage: variance-check.ts <bundleDirA> <bundleDirB> [--out <file>] [--generated-at <iso>] [--emit-masked]",
+    );
+  }
+  return {
+    a: positional[0],
+    b: positional[1],
+    out: (flags.out as string) || undefined,
+    generatedAt: (flags["generated-at"] as string) || DEFAULT_GENERATED_AT,
+    emitMasked: flags["emit-masked"] === true,
+  };
+}
+
+export function main(argvIn?: string[]): number {
+  const argv =
+    argvIn ??
+    (typeof Bun !== "undefined" ? Bun.argv.slice(2) : process.argv.slice(2));
+  const args = parseArgs(argv);
+
+  const { bundle: a } = loadBundle(args.a);
+  const { bundle: b } = loadBundle(args.b);
+  const trend = varianceCompare(a, b);
+
+  // Carry the trend into a TREND-only scorecard frame (GATE empty — this is the
+  // coordinator's variance comparison, not a conformance gate).
+  const scorecard = assembleScorecard({
+    subject: a.runId,
+    runId: `${a.runId}__vs__${b.runId}`,
+    generatedAt: args.generatedAt,
+    rows: [],
+    trendDimensions: trend.dimensions,
+    trendRunPair: trend.runPair,
+  });
+
+  const json = args.emitMasked
+    ? maskedCanonicalJson(scorecard)
+    : JSON.stringify(scorecard, null, 2);
+  if (args.out) writeFileSync(args.out, json + "\n");
+
+  console.info(
+    JSON.stringify(
+      {
+        runPair: trend.runPair,
+        varianceScore: trend.varianceScore,
+        dimensions: trend.dimensions.length,
+        diverged: trend.dimensions
+          .filter((d) => d.divergence === "diverged")
+          .map((d) => d.name),
+        out: args.out ?? "(stdout only)",
+      },
+      null,
+      2,
+    ),
+  );
+  // exit 0 when byte-identical (varianceScore 0), 1 otherwise.
+  return trend.varianceScore === 0 ? 0 : 1;
+}
+
+declare const Bun: { argv: string[] } | undefined;
+const isMain =
+  typeof import.meta !== "undefined" &&
+  (import.meta as unknown as { main?: boolean }).main === true;
+if (isMain) {
+  process.exit(main());
+}

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/scripts/code-eval.ts

@@ -0,0 +1,248 @@
+/**
+ * scripts/code-eval.ts — P3 (EX-2): the v2 CODE-track primitive library.
+ * ---------------------------------------------------------------------------
+ * Code-class criteria (§5b `check_method: deterministic`, and the pre-filter
+ * half of `hybrid`) are evaluated by DETERMINISTIC code-eval scripts the
+ * evaluator agent runs via its Bash tool — NO LLM, ZERO judge tokens,
+ * byte-identical across reruns (restores full C-PIN on code rows; closes M1/M2).
+ *
+ * This is a generic, SUBJECT-AGNOSTIC primitive set over the `EvalTrace` shape:
+ *   - presence              — a field is present + non-empty
+ *   - string-equality       — exact (optionally case-insensitive) match
+ *   - format-validity       — a regex/format conformance check
+ *   - schema-conformance    — an object carries the required keys
+ *   - ref-integrity         — cross-stage: every value produced in stage A is
+ *                             present in stage B's output (referential integrity)
+ *   - recovery-after-failure — TEMPORAL: a failure marker on an observation MUST
+ *                             be followed by a recovery tool LATER in the trace; an
+ *                             un-recovered failure is a "silent drop" (FAIL).
+ *   - tool-output-failure   — a named tool's success flag is false on any call (FAIL).
+ * A per-subject extraction (check-method-router.ts) maps a code-class
+ * MinedCriterion → one of these specs; the primitives themselves hold NO subject
+ * literal — the field names, fail values, and tool names are all PARAMETERS, so
+ * the temporal/tool primitives are reusable on ANY agent's failure modes (the
+ * sample `send-failure-silent-drop` mode is just one parameterization).
+ *
+ * TWO-WORLDS BOUNDARY: this is the v2 code-track over `EvalTrace` +
+ * `MinedCriterion`. It deliberately does NOT import the v1 audit world
+ * (`run-deterministic.ts` / `contracts/types.ts` 6-value Track over RunBundle) —
+ * the two stay disjoint.
+ *
+ * PURE + deterministic: no clock / random / network. Reading a trace field is
+ * the only effect-free input; the verdict is a pure function of (spec, trace).
+ */
+import type { EvalTrace, TraceObservation } from "./contracts/eval-types.ts";
+
+/** A single code-eval's binary, deterministic outcome. `detail` → verdict critique. */
+export interface CodeEvalResult {
+  result: "pass" | "fail";
+  detail: string;
+}
+
+/**
+ * Read a dotted path off an `EvalTrace`. Supports:
+ *   - `output.response`, `input.prompt`        → navigate the trace object
+ *   - `obs:<name>.<path>`                       → the named GENERATION observation's
+ *                                                 output, then navigate (SV-1: per-stage
+ *                                                 outputs live in the observations)
+ * Returns undefined for any missing segment (tolerant — never throws). PURE.
+ */
+export function readTracePath(trace: EvalTrace, path: string): unknown {
+  if (path.startsWith("obs:")) {
+    const rest = path.slice(4);
+    const dot = rest.indexOf(".");
+    const name = dot === -1 ? rest : rest.slice(0, dot);
+    const sub = dot === -1 ? "" : rest.slice(dot + 1);
+    const obs = trace.observations.find(
+      (o: TraceObservation) => o.name === name && typeof o.type === "string" && o.type.toUpperCase() === "GENERATION",
+    );
+    if (obs === undefined) return undefined;
+    return sub.length === 0 ? obs.output : navigate(obs.output, sub);
+  }
+  return navigate(trace as unknown, path);
+}
+
+/** Navigate a dotted path through a plain object graph. Undefined on any gap. */
+function navigate(root: unknown, path: string): unknown {
+  let cur: unknown = root;
+  for (const seg of path.split(".")) {
+    if (cur === null || typeof cur !== "object") return undefined;
+    cur = (cur as Record<string, unknown>)[seg];
+    if (cur === undefined) return undefined;
+  }
+  return cur;
+}
+
+/** Coerce a value to a search "haystack" string for ref-integrity. */
+function haystack(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value === undefined || value === null) return "";
+  return JSON.stringify(value);
+}
+
+/** Coerce a producer value to its set of string tokens (array → items; scalar → [it]). */
+function tokens(value: unknown): string[] {
+  if (Array.isArray(value)) return value.map((v) => (typeof v === "string" ? v : JSON.stringify(v)));
+  if (value === undefined || value === null) return [];
+  return [typeof value === "string" ? value : JSON.stringify(value)];
+}
+
+/**
+ * Coerce a scalar trace value to a canonical string for EXACT equality compare
+ * (used by the temporal/tool primitives). Booleans/numbers stringify (`false` →
+ * "false", `0` → "0"); strings pass through; null/undefined → "" (so a missing
+ * field never spuriously equals a non-empty `failEquals`); objects JSON-serialize.
+ */
+function coerce(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (typeof value === "boolean" || typeof value === "number" || typeof value === "bigint") {
+    return String(value);
+  }
+  if (value === undefined || value === null) return "";
+  return JSON.stringify(value);
+}
+
+/** The `name` of an observation, or "" when unnamed. */
+function obsName(o: TraceObservation): string {
+  return typeof o.name === "string" ? o.name : "";
+}
+
+// ── The CodeEvalSpec union (one per primitive) ──────────────────────────────
+
+export type CodeEvalSpec =
+  | { primitive: "presence"; field: string }
+  | { primitive: "string-equality"; field: string; expected: string; caseInsensitive?: boolean }
+  | { primitive: "format-validity"; field: string; pattern: string }
+  | { primitive: "schema-conformance"; field: string; requiredKeys: string[] }
+  | { primitive: "ref-integrity"; producer: string; consumer: string }
+  | {
+      primitive: "recovery-after-failure";
+      /** path read RELATIVE TO each observation (e.g. "output.status"). */
+      failField: string;
+      /** the coerced value at `failField` that marks an observation as a failure. */
+      failEquals: string;
+      /** observation `name`s that count as a recovery reaction AFTER the failure. */
+      recoveryTools: string[];
+    }
+  | {
+      primitive: "tool-output-failure";
+      /** the observation `name` of the tool to inspect. */
+      tool: string;
+      /** path read RELATIVE TO the tool observation; `false` (bool/string) ⇒ failure. */
+      successPath: string;
+    };
+
+function pass(detail: string): CodeEvalResult {
+  return { result: "pass", detail };
+}
+function fail(detail: string): CodeEvalResult {
+  return { result: "fail", detail };
+}
+
+/**
+ * Run one code-eval over a trace → a deterministic binary verdict. Exhaustive on
+ * the primitive union; an UNKNOWN primitive THROWS (no silent pass — a
+ * misconfigured code-eval is a fail-loud error, never a fabricated success). PURE.
+ */
+export function runCodeEval(spec: CodeEvalSpec, trace: EvalTrace): CodeEvalResult {
+  switch (spec.primitive) {
+    case "presence": {
+      const v = readTracePath(trace, spec.field);
+      const empty =
+        v === undefined ||
+        v === null ||
+        (typeof v === "string" && v.length === 0) ||
+        (Array.isArray(v) && v.length === 0);
+      return empty ? fail(`'${spec.field}' is absent/empty`) : pass(`'${spec.field}' is present`);
+    }
+    case "string-equality": {
+      const v = readTracePath(trace, spec.field);
+      const s = typeof v === "string" ? v : haystack(v);
+      const a = spec.caseInsensitive === true ? s.toLowerCase() : s;
+      const b = spec.caseInsensitive === true ? spec.expected.toLowerCase() : spec.expected;
+      return a === b
+        ? pass(`'${spec.field}' equals expected`)
+        : fail(`'${spec.field}'='${s}' != expected '${spec.expected}'`);
+    }
+    case "format-validity": {
+      const v = readTracePath(trace, spec.field);
+      const s = typeof v === "string" ? v : haystack(v);
+      return new RegExp(spec.pattern).test(s)
+        ? pass(`'${spec.field}' matches /${spec.pattern}/`)
+        : fail(`'${spec.field}'='${s}' does not match /${spec.pattern}/`);
+    }
+    case "schema-conformance": {
+      const v = readTracePath(trace, spec.field);
+      if (v === null || typeof v !== "object") {
+        return fail(`'${spec.field}' is not an object`);
+      }
+      const obj = v as Record<string, unknown>;
+      const missing = spec.requiredKeys.filter((k) => obj[k] === undefined);
+      return missing.length === 0
+        ? pass(`'${spec.field}' has all required keys`)
+        : fail(`'${spec.field}' missing keys: ${missing.join(", ")}`);
+    }
+    case "ref-integrity": {
+      const producerTokens = tokens(readTracePath(trace, spec.producer));
+      const hay = haystack(readTracePath(trace, spec.consumer));
+      const missing = producerTokens.filter((t) => !hay.includes(t));
+      return missing.length === 0
+        ? pass(`all ${producerTokens.length} '${spec.producer}' value(s) present in '${spec.consumer}'`)
+        : fail(`'${spec.consumer}' is missing producer value(s): ${missing.join(", ")}`);
+    }
+    case "recovery-after-failure": {
+      // TEMPORAL: find the FIRST observation whose `failField` marks a failure, then
+      // require a recovery-tool observation AFTER it. No failure ⇒ vacuously pass.
+      let failIdx = -1;
+      for (let i = 0; i < trace.observations.length; i++) {
+        const v = navigate(trace.observations[i], spec.failField);
+        if (v !== undefined && coerce(v) === spec.failEquals) {
+          failIdx = i;
+          break;
+        }
+      }
+      if (failIdx === -1) {
+        return pass(
+          `no observation has '${spec.failField}'=='${spec.failEquals}' — no failure to recover from`,
+        );
+      }
+      const recoverySet = new Set(spec.recoveryTools);
+      const after = trace.observations.slice(failIdx + 1);
+      const recovered = after.find((o) => recoverySet.has(obsName(o)));
+      return recovered !== undefined
+        ? pass(
+            `failure at obs#${failIdx} ('${spec.failField}'=='${spec.failEquals}') was followed by ` +
+              `recovery tool '${obsName(recovered)}'`,
+          )
+        : fail(
+            `failure at obs#${failIdx} ('${spec.failField}'=='${spec.failEquals}') with NO recovery ` +
+              `tool (${spec.recoveryTools.join(" | ")}) AFTER it — silent drop`,
+          );
+    }
+    case "tool-output-failure": {
+      const calls = trace.observations.filter((o) => obsName(o) === spec.tool);
+      if (calls.length === 0) {
+        return pass(`no '${spec.tool}' observation present — nothing to check`);
+      }
+      const failed = calls.filter((o) => {
+        const v = navigate(o, spec.successPath);
+        return v === false || coerce(v) === "false";
+      });
+      return failed.length === 0
+        ? pass(`all ${calls.length} '${spec.tool}' call(s) report '${spec.successPath}' != false`)
+        : fail(
+            `'${spec.tool}' reports failure ('${spec.successPath}'==false) in ` +
+              `${failed.length}/${calls.length} call(s)`,
+          );
+    }
+    default: {
+      // exhaustiveness: an unknown primitive is a fail-loud error.
+      const unknown = spec as { primitive?: unknown };
+      throw new Error(
+        `runCodeEval: unknown code-eval primitive '${String(unknown.primitive)}'. ` +
+          "Known: presence | string-equality | format-validity | schema-conformance | " +
+          "ref-integrity | recovery-after-failure | tool-output-failure.",
+      );
+    }
+  }
+}

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/scripts/code-quality-verdict.ts

@@ -0,0 +1,285 @@
+/**
+ * scripts/code-quality-verdict.ts — the CODE-QUALITY judge mode (Wave-2 W2I1).
+ * ---------------------------------------------------------------------------
+ * A JUDGE mode that scores a CODE subject's QUALITY (the amended/scaffolded
+ * implementation of a `code`-kind subject) and emits a binary PASS/FAIL quality
+ * verdict with a critique-before-verdict per criterion. It is the (b) half of the
+ * ⑤ IMPROVE loop's code-target BOTH-gate: "converged" for a `code` subject = the
+ * subject's OWN test suite green (a deterministic gate the session records as
+ * `testsGreen`) AND this code-quality verdict PASSes. Neither alone converges.
+ *
+ * DISTINCT FROM `code-eval.ts`. That file is the DETERMINISTIC code-track primitive
+ * library (presence/string-equality/... over an EvalTrace — no LLM, byte-identical).
+ * This file is an LLM JUDGE mode: it scores the irreducibly-subjective quality of a
+ * code implementation (spec-faithfulness, maintainability, error-handling, ...) that
+ * a deterministic primitive cannot decide.
+ *
+ * INVARIANTS (consistent with the existing evaluator cell):
+ *   - JUDGE-ONLY (EV-051). It scores; it NEVER fixes. Failures route to the ⑤ loop's
+ *     ai-engineer amend (via the loop, not from here).
+ *   - HOST-RUNTIME. Under the DEFAULT agent-dispatch substrate the authoritative
+ *     rubric lives in the evaluator agent def (`#mode-judge-code-quality`), and the
+ *     verdict comes from a dispatched subagent — this file's prompt is the
+ *     provider-callable MIRROR for the OPTIONAL in-house / export substrate (same
+ *     operator-named exception as judge-prompt-template.ts). No provider key on the
+ *     default path.
+ *   - PINNED model + temperature 0 (C-PIN). `runCodeQualityJudge` THROWS if the pin
+ *     is not (modelId present AND temperature === 0) — reruns must be byte-identical.
+ *   - PURE renderer + a thin injected-seam run wrapper. No clock, no random, no
+ *     network; the LLM call is the injected `JudgeInvoke` seam so tests drive it.
+ */
+import { parseCritiqueVerdict, type JudgeInvoke } from "./determine-outcome.ts";
+import type { JudgePin } from "./build-evals.ts";
+import type { CritiqueVerdict } from "./contracts/eval-types.ts";
+
+/** Severity of a code-quality criterion — gates the aggregate (CRIT/HIGH block). */
+export const CodeQualitySeverity = {
+  Critical: "critical",
+  High: "high",
+  Medium: "medium",
+} as const;
+export type CodeQualitySeverityValue =
+  (typeof CodeQualitySeverity)[keyof typeof CodeQualitySeverity];
+
+/** One binary code-quality criterion the judge scores. */
+export interface CodeQualityCriterion {
+  /** Stable id (byte-identity key + report anchor). */
+  id: string;
+  /** The one-line binary statement the judge decides pass/fail on. */
+  statement: string;
+  /** What a PASS looks like (concrete, so the judge is not guessing). */
+  passDefinition: string;
+  /** What a FAIL looks like. */
+  failDefinition: string;
+  /** Gating weight — a `fail`/`uncertain` on a CRIT/HIGH criterion blocks the gate. */
+  severity: CodeQualitySeverityValue;
+}
+
+/**
+ * ⚠️ FLAGGED-FOR-OPERATOR-SIGN-OFF (Wave-2 W2I1). This is the DRAFT default set of
+ * acceptance criteria that define "code quality-pass" BEYOND tests-green. It is
+ * implemented behind this clearly-named default so the operator can confirm/adjust
+ * the criteria + their severities WITHOUT a code change to the loop. The picks
+ * below are a conservative, subject-agnostic starting point — NOT a final contract.
+ *
+ * The five drafted criteria (each BINARY, critique-before-verdict):
+ *   Q1 spec-faithful  (critical) — the impl realizes the agentspec DEFINITION the
+ *                                  amend targeted; no dropped tool / JTBD / silently
+ *                                  altered system_prompt (def→impl cascade held).
+ *   Q2 addresses-diagnosis (high) — the change actually targets the diagnosed
+ *                                  root-cause locus, not an adjacent symptom.
+ *   Q3 no-regression  (high)    — no unrelated behavior removed/broken; scope stayed
+ *                                  on what the remedy named (scope discipline).
+ *   Q4 error-handling (high)    — failure paths are handled, not silently dropped
+ *                                  (recovery/observability preserved).
+ *   Q5 maintainable   (medium)  — readable, framework-idiomatic, no dead code /
+ *                                  copy-paste / obvious footgun introduced.
+ *
+ * Aggregation (also FLAGGED): the gate is severity-gated — a `fail` OR `uncertain`
+ * on any CRITICAL/HIGH criterion blocks the quality-pass; MEDIUM is advisory. The
+ * operator may instead choose strict-all-pass or a different severity map.
+ */
+export const DEFAULT_CODE_QUALITY_CRITERIA: readonly CodeQualityCriterion[] = [
+  {
+    id: "Q1-spec-faithful",
+    statement: "The implementation realizes the agentspec definition the amend targeted.",
+    passDefinition:
+      "PASS: every spec-declared tool / job-to-be-done is present and the operative system_prompt is unchanged except where the amend intended; the def→impl cascade held.",
+    failDefinition:
+      "FAIL: a spec-declared tool or JTBD is missing, or the system_prompt was altered beyond the amend intent (the impl forked from the SSoT).",
+    severity: CodeQualitySeverity.Critical,
+  },
+  {
+    id: "Q2-addresses-diagnosis",
+    statement: "The change targets the diagnosed root-cause locus, not an adjacent symptom.",
+    passDefinition:
+      "PASS: the edit is at (or directly causes a fix at) the RCA-named locus / the failing-case root.",
+    failDefinition:
+      "FAIL: the change edits an unrelated place or patches a symptom while the root cause remains.",
+    severity: CodeQualitySeverity.High,
+  },
+  {
+    id: "Q3-no-regression",
+    statement: "The change introduces no unrelated regression and stays in scope.",
+    passDefinition:
+      "PASS: only the remedy-named surface changed; no unrelated behavior was removed or broken.",
+    failDefinition:
+      "FAIL: unrelated code was changed/removed, or a previously-working path was broken.",
+    severity: CodeQualitySeverity.High,
+  },
+  {
+    id: "Q4-error-handling",
+    statement: "Failure paths are handled, not silently dropped.",
+    passDefinition:
+      "PASS: error/failure branches surface, recover, or log per the subject's contract; no new silent drop.",
+    failDefinition:
+      "FAIL: a failure is swallowed with no recovery/notify/observability (a silent-drop regression).",
+    severity: CodeQualitySeverity.High,
+  },
+  {
+    id: "Q5-maintainable",
+    statement: "The code is readable, framework-idiomatic, and free of obvious footguns.",
+    passDefinition:
+      "PASS: clear structure, idiomatic to the target framework, no dead code / copy-paste / obvious footgun introduced.",
+    failDefinition:
+      "FAIL: unreadable/duplicated/dead code or an obvious maintainability footgun was introduced.",
+    severity: CodeQualitySeverity.Medium,
+  },
+] as const;
+
+/** The code subject under quality review (minimal, subject-agnostic). */
+export interface CodeQualitySubject {
+  /** Subject id (spec_id / target name) — provenance only. */
+  subjectId: string;
+  /** The target framework/harness the impl was built into (context for the judge). */
+  framework: string;
+  /** A compact summary of the agentspec DEFINITION the impl must realize (the SSoT). */
+  specSummary: string;
+  /** The applied change under review — the amend diff, or the scaffold summary. */
+  appliedChange: string;
+  /**
+   * The diagnosed root-cause / remedy locus this change was meant to address (feeds
+   * Q2). Empty for a fresh scaffold with no prior diagnosis.
+   */
+  diagnosisLocus?: string;
+}
+
+/** One criterion's judged result (critique-before-verdict, binary). */
+export interface CodeQualityCriterionVerdict {
+  criterionId: string;
+  severity: CodeQualitySeverityValue;
+  result: CritiqueVerdict["result"]; // pass | fail | uncertain
+  critique: string;
+  confidence: number;
+}
+
+/** The aggregated code-quality verdict for one subject. */
+export interface CodeQualityVerdict {
+  subjectId: string;
+  /** The binary quality gate — the (b) half of the ⑤ code-target BOTH-gate. */
+  pass: boolean;
+  perCriterion: CodeQualityCriterionVerdict[];
+  /** C-PIN provenance stamped on the verdict (byte-identity guarantee). */
+  pinned: JudgePin;
+}
+
+/**
+ * Render the code-quality judge prompt for ONE criterion — the provider-callable
+ * mirror of the `#mode-judge-code-quality` rubric. Critique-BEFORE-verdict, strictly
+ * BINARY (no Likert), judge-only. No decision is made here.
+ */
+export function buildCodeQualityPrompt(
+  criterion: CodeQualityCriterion,
+  subject: CodeQualitySubject,
+): { system: string; user: string } {
+  const system = [
+    "You are a BINARY Pass/Fail code-QUALITY judge for ONE criterion of a CODE",
+    "subject (an agent/tooling implementation). Judge exactly this criterion and",
+    "nothing else. You are a JUDGE ONLY — you NEVER propose or write a fix.",
+    "",
+    "Quality is assessed BEYOND the subject's test suite (tests-green is a separate",
+    "deterministic gate). Judge the code as written against the criterion.",
+    "",
+    `Criterion (${criterion.id}, severity ${criterion.severity}): ${criterion.statement}`,
+    criterion.passDefinition,
+    criterion.failDefinition,
+    "",
+    "Outcomes are strictly BINARY: pass or fail (use uncertain ONLY when the change",
+    "genuinely lacks the evidence to decide). NO Likert scales, NO 1-5 / letter",
+    "grades, NO partial credit.",
+    "",
+    "Output STRICT JSON with the critique BEFORE the verdict (reason first, then",
+    "commit):",
+    '{ "critique": "<evidence-citing assessment>", "result": "pass"|"fail"|"uncertain",',
+    '  "confidence": <0..1> }',
+  ].join("\n");
+
+  const user = [
+    `Subject: ${subject.subjectId}  ·  target framework: ${subject.framework}`,
+    "",
+    "Agentspec definition the implementation must realize (the SSoT):",
+    subject.specSummary,
+    "",
+    subject.diagnosisLocus !== undefined && subject.diagnosisLocus.length > 0
+      ? `Diagnosed root-cause / remedy locus (for the addresses-diagnosis check):\n${subject.diagnosisLocus}\n`
+      : "",
+    "Applied change under review (diff or scaffold summary):",
+    subject.appliedChange,
+  ]
+    .filter((l) => l !== "")
+    .join("\n");
+
+  return { system, user };
+}
+
+/**
+ * The PURE aggregation: severity-gate the per-criterion verdicts into ONE binary
+ * quality-pass. FLAGGED default rule — a `fail` OR `uncertain` on any CRITICAL/HIGH
+ * criterion blocks the pass; MEDIUM is advisory (never blocks). Deterministic.
+ */
+export function codeQualityGatePass(
+  perCriterion: readonly CodeQualityCriterionVerdict[],
+): boolean {
+  for (const v of perCriterion) {
+    const gating =
+      v.severity === CodeQualitySeverity.Critical || v.severity === CodeQualitySeverity.High;
+    if (gating && v.result !== "pass") return false;
+  }
+  return true;
+}
+
+/**
+ * Run the code-quality judge over the criteria set under a PINNED model. THROWS if
+ * the pin is not (modelId present AND temperature === 0) — C-PIN (byte-identical
+ * reruns). Renders each criterion → the injected `JudgeInvoke` seam → parses
+ * (critique-before-verdict) → severity-gated aggregate. Under the DEFAULT
+ * agent-dispatch substrate the verdicts instead come from a dispatched
+ * `#mode-judge-code-quality` subagent (verdict files) and this wrapper is not used.
+ * Deterministic given (subject, judge, pin, criteria).
+ */
+export async function runCodeQualityJudge(
+  subject: CodeQualitySubject,
+  judge: JudgeInvoke,
+  pin: JudgePin,
+  criteria: readonly CodeQualityCriterion[] = DEFAULT_CODE_QUALITY_CRITERIA,
+): Promise<CodeQualityVerdict> {
+  if (typeof pin.modelId !== "string" || pin.modelId.length === 0) {
+    throw new Error(
+      "runCodeQualityJudge: 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(
+      `runCodeQualityJudge: judge temperature=${pin.temperature} (!= 0) — not pinned. ` +
+        "MODEL INTENT IS SACRED: reruns must be byte-identical (C-PIN); refusing.",
+    );
+  }
+  if (criteria.length === 0) {
+    throw new Error(
+      "runCodeQualityJudge: empty criteria set — a code-quality verdict with no " +
+        "criteria would vacuously pass (a false-green). Refusing.",
+    );
+  }
+
+  const perCriterion: CodeQualityCriterionVerdict[] = [];
+  for (const criterion of criteria) {
+    const { system, user } = buildCodeQualityPrompt(criterion, subject);
+    const raw = await judge(system, user);
+    const v = parseCritiqueVerdict(raw);
+    perCriterion.push({
+      criterionId: criterion.id,
+      severity: criterion.severity,
+      result: v.result,
+      critique: v.critique,
+      confidence: v.confidence,
+    });
+  }
+
+  return {
+    subjectId: subject.subjectId,
+    pass: codeQualityGatePass(perCriterion),
+    perCriterion,
+    pinned: { modelId: pin.modelId, temperature: pin.temperature },
+  };
+}