@mutagent/helix 0.1.0-alpha.14

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

@@ -0,0 +1,168 @@
+/**
+ * scripts/lint-uniformity.ts — the UNIFORM EVAL-STANDARD validator (loud, deterministic).
+ * ---------------------------------------------------------------------------
+ * The operator-signed-off "uniform eval standard": every MinedCriterion carries a
+ * uniform check representation, and the EXECUTABLE half (`codeEval`) must MATCH
+ * the declared `check_method`. This is the deterministic, code-only gate that
+ * makes the standard real — it kills the "tier-0 inert" defect where a criterion
+ * is TYPED code/hybrid but ships no runnable `codeEval`, so the tier-0 pre-pass
+ * silently falls back to the LLM judge (wasting the deterministic signal +
+ * breaking C-PIN). Mirrors `lint-grounding.ts`: pure, criterion-ordered findings.
+ *
+ * THE STANDARD (per `metadata.check_method`):
+ *   - `deterministic` ⇒ codeEval REQUIRED            (pure code row — runs in tier-0)
+ *   - `hybrid`        ⇒ codeEval REQUIRED + judge_inputs non-empty
+ *                                                     (code pre-filter THEN judge)
+ *   - `llm-judge`     ⇒ judge_inputs non-empty + NO codeEval
+ *                                                     (subjective — judge owns it)
+ *
+ * A code/hybrid criterion WITHOUT a `codeEval` is a HARD error — not a warning,
+ * not grandfathered. Uniformity is a structural contract: a violation means the
+ * suite is mis-built (a row that claims to be deterministic but can't run
+ * deterministically), so EVERY finding is an ERROR (`ok=false`). PURE — no
+ * clock/random/network.
+ */
+import {
+  CheckMethod,
+  type MinedCriterion,
+} from "./contracts/eval-types.ts";
+
+export type UniformityRule =
+  | "U1-deterministic-requires-codeeval"
+  | "U2-hybrid-requires-codeeval"
+  | "U3-llm-judge-forbids-codeeval"
+  | "U4-judge-inputs-required";
+
+export interface UniformityFinding {
+  criterionId: string;
+  rule: UniformityRule;
+  /** always "error" — a uniformity breach means the suite is mis-built. */
+  level: "error";
+  message: string;
+}
+
+export interface UniformityResult {
+  findings: UniformityFinding[];
+  errorCount: number;
+  /** false iff ≥1 finding — uniformity is all-or-nothing (no warn tier). */
+  ok: boolean;
+}
+
+/** Does this criterion carry a runnable code-eval spec? */
+function hasCodeEval(c: MinedCriterion): boolean {
+  return c.codeEval !== undefined;
+}
+
+/** Does this criterion declare the minimal judge inputs a judge row needs? */
+function hasJudgeInputs(c: MinedCriterion): boolean {
+  return Array.isArray(c.metadata.judge_inputs) && c.metadata.judge_inputs.length > 0;
+}
+
+/**
+ * Validate ONE mined criterion against the uniform standard. Returns the findings
+ * (all ERROR-level). PURE.
+ */
+export function lintUniformityCriterion(c: MinedCriterion): UniformityFinding[] {
+  const out: UniformityFinding[] = [];
+  const cm = c.metadata.check_method;
+
+  if (cm === CheckMethod.Deterministic) {
+    // pure code row — MUST carry a runnable codeEval (else tier-0 inert).
+    if (!hasCodeEval(c)) {
+      out.push({
+        criterionId: c.id,
+        rule: "U1-deterministic-requires-codeeval",
+        level: "error",
+        message:
+          "check_method=deterministic but NO codeEval — a deterministic row MUST ship a runnable " +
+          "code-eval spec (else the tier-0 pre-pass silently falls back to the LLM judge: tier-0 inert).",
+      });
+    }
+    return out;
+  }
+
+  if (cm === CheckMethod.Hybrid) {
+    // code pre-filter THEN judge — needs BOTH halves.
+    if (!hasCodeEval(c)) {
+      out.push({
+        criterionId: c.id,
+        rule: "U2-hybrid-requires-codeeval",
+        level: "error",
+        message:
+          "check_method=hybrid but NO codeEval — a hybrid row MUST ship a code-eval spec for the " +
+          "deterministic pre-filter half (else there is nothing to pre-filter: tier-0 inert).",
+      });
+    }
+    if (!hasJudgeInputs(c)) {
+      out.push({
+        criterionId: c.id,
+        rule: "U4-judge-inputs-required",
+        level: "error",
+        message:
+          "check_method=hybrid but judge_inputs is empty — a hybrid row MUST declare the judge_inputs " +
+          "the LLM judge reads for the subjective half.",
+      });
+    }
+    return out;
+  }
+
+  if (cm === CheckMethod.LlmJudge) {
+    // subjective row — judge owns it; a codeEval here is contradictory.
+    if (hasCodeEval(c)) {
+      out.push({
+        criterionId: c.id,
+        rule: "U3-llm-judge-forbids-codeeval",
+        level: "error",
+        message:
+          "check_method=llm-judge but a codeEval is present — a judge-only row must NOT carry a " +
+          "code-eval (it would never run: tier-0 routes only deterministic/hybrid). Re-tag the " +
+          "criterion deterministic|hybrid, or drop the codeEval.",
+      });
+    }
+    if (!hasJudgeInputs(c)) {
+      out.push({
+        criterionId: c.id,
+        rule: "U4-judge-inputs-required",
+        level: "error",
+        message:
+          "check_method=llm-judge but judge_inputs is empty — a judge row MUST declare the judge_inputs " +
+          "the LLM judge reads.",
+      });
+    }
+    return out;
+  }
+
+  // unreachable for a parsed MinedCriterion (check_method is a closed union), but
+  // fail-loud rather than silently pass an unknown method.
+  out.push({
+    criterionId: c.id,
+    rule: "U1-deterministic-requires-codeeval",
+    level: "error",
+    message: `unknown check_method '${String(cm)}' — cannot validate uniformity (no silent pass).`,
+  });
+  return out;
+}
+
+/**
+ * Validate a batch of mined criteria against the uniform standard. PURE —
+ * deterministic, criterion order. `ok` is false iff ANY finding exists.
+ */
+export function lintUniformity(criteria: MinedCriterion[]): UniformityResult {
+  const findings = criteria.flatMap((c) => lintUniformityCriterion(c));
+  return { findings, errorCount: findings.length, ok: findings.length === 0 };
+}
+
+/**
+ * Assert the uniform standard — THROWS with a loud, multi-line summary on ANY
+ * violation. The hard gate the discover AGGREGATE / build path can call to refuse
+ * shipping a mis-built suite. PURE (throws or returns void).
+ */
+export function assertUniform(criteria: MinedCriterion[]): void {
+  const { findings, ok } = lintUniformity(criteria);
+  if (ok) return;
+  const lines = findings.map((f) => `  - [${f.rule}] ${f.criterionId}: ${f.message}`);
+  throw new Error(
+    `assertUniform: ${findings.length} uniform-standard violation(s) — the eval suite is mis-built ` +
+      `(a criterion's executable codeEval does not match its declared check_method):\n${lines.join("\n")}`,
+  );
+}

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/scripts/living-suite.ts

@@ -0,0 +1,109 @@
+/**
+ * scripts/living-suite.ts — EV-053 the append-only LIVING-SUITE writer (Type A — Code-only).
+ * ---------------------------------------------------------------------------
+ * The cross-cutting monotonic-growth primitive shared by the eval-suite (the
+ * discovered criteria / judges) AND the datasets (`*build-dataset` /
+ * `*discover-dataset`). Its single invariant: a living artifact NEVER shrinks —
+ * every entry once added is retained; appends only grow it.
+ *
+ * Generic over the entry type `T` + a caller-supplied `keyOf` so it serves any
+ * keyed collection (DatasetCase by id, DiscoveredCriterion by id, …). Carries
+ * provenance (a monotonically-increasing version + counts) WITHOUT a clock —
+ * stamping `appendedAt` would break byte-identity (C-PIN), so provenance is a
+ * pure counter. PURE — no clock / random / network; same (suite, incoming) →
+ * same grown suite.
+ *
+ * Austerity: holds NO LLM reasoning, makes NO pass/fail decision — it is pure
+ * set algebra with a fail-loud monotonicity guard. The dataset scripts route
+ * their appends through `appendOnly` + `assertMonotonicGrowth` here.
+ */
+
+/**
+ * Append `incoming` onto `existing`, deduped by `keyOf`, MONOTONICALLY: every
+ * existing entry is retained (in its original order) and only entries with a
+ * not-yet-seen key are appended (in input order). DETERMINISTIC. PURE.
+ */
+export function appendOnly<T>(existing: T[], incoming: T[], keyOf: (t: T) => string): T[] {
+  const seen = new Set(existing.map(keyOf));
+  const out = [...existing];
+  for (const item of incoming) {
+    const k = keyOf(item);
+    if (!seen.has(k)) {
+      seen.add(k);
+      out.push(item);
+    }
+  }
+  return out;
+}
+
+/**
+ * Enforce the monotonic-growth invariant: every key present in `before` MUST
+ * still be present in `after`, and the set never shrinks. THROWS on any
+ * violation — a living suite/dataset that lost an entry is a contract breach
+ * (EV-053), never silently accepted. PURE.
+ */
+export function assertMonotonicGrowth<T>(
+  before: T[],
+  after: T[],
+  keyOf: (t: T) => string,
+): void {
+  const afterKeys = new Set(after.map(keyOf));
+  for (const b of before) {
+    const k = keyOf(b);
+    if (!afterKeys.has(k)) {
+      throw new Error(
+        `assertMonotonicGrowth: entry '${k}' was DROPPED — a living suite must never ` +
+          "shrink (EV-053). Appends may only grow the set.",
+      );
+    }
+  }
+  if (after.length < before.length) {
+    throw new Error(
+      `assertMonotonicGrowth: suite shrank from ${before.length} to ${after.length} entries ` +
+        "(EV-053 monotonic-growth violation).",
+    );
+  }
+}
+
+/** Provenance for a living suite — a pure counter (NO clock, for byte-identity). */
+export interface SuiteProvenance {
+  /** monotonically-increasing version, bumped on every append. */
+  version: number;
+  /** total entries after the append. */
+  total: number;
+  /** how many genuinely-novel entries the last append added. */
+  lastAppended: number;
+}
+
+/** A keyed, append-only growing collection. */
+export interface LivingSuite<T> {
+  entries: T[];
+  provenance: SuiteProvenance;
+}
+
+/** A fresh empty living suite (version 0, no entries). PURE. */
+export function emptySuite<T>(): LivingSuite<T> {
+  return { entries: [], provenance: { version: 0, total: 0, lastAppended: 0 } };
+}
+
+/**
+ * Grow a living suite by appending `incoming` (deduped by `keyOf`). Enforces the
+ * monotonic-growth invariant, bumps the version, and records how many novel
+ * entries landed. Returns a NEW suite (no mutation). DETERMINISTIC. PURE.
+ */
+export function growLivingSuite<T>(
+  suite: LivingSuite<T>,
+  incoming: T[],
+  keyOf: (t: T) => string,
+): LivingSuite<T> {
+  const entries = appendOnly(suite.entries, incoming, keyOf);
+  assertMonotonicGrowth(suite.entries, entries, keyOf);
+  return {
+    entries,
+    provenance: {
+      version: suite.provenance.version + 1,
+      total: entries.length,
+      lastAppended: entries.length - suite.entries.length,
+    },
+  };
+}

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/scripts/load-bundle.ts

@@ -0,0 +1,203 @@
+/**
+ * scripts/load-bundle.ts
+ * ---------------------------------------------------------------------------
+ * The bundle loader: takes a run-bundle directory (.mutagent/diagnostics/{runId}/)
+ * and the loaded subject profile, discovers + parses the run artifacts, and
+ * returns a validated RunBundle (the "validated audit input" of the data-flow).
+ *
+ * Subject-agnostic: it does not hard-code which artifacts a subject produces. It
+ * discovers a known set of well-known artifact names (best-effort), records
+ * absolute paths, parses any JSON, and surfaces missing-but-optional artifacts
+ * as warnings rather than throwing. Only the bundle directory itself must exist.
+ *
+ * Deterministic: directory entries are sorted before processing; no clock/random.
+ */
+import {
+  existsSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+} from "node:fs";
+import { basename, join } from "node:path";
+import { type RunBundle } from "./contracts/types.ts";
+
+/**
+ * Well-known artifacts the evaluator looks for in a run-bundle. The KEY is the
+ * logical name used downstream (run-deterministic / lenses); the VALUE is the
+ * relative filename within the bundle. Missing entries become warnings.
+ */
+export const WELL_KNOWN_ARTIFACTS: Readonly<Record<string, string>> = {
+  runMeta: "runMeta.json",
+  tracesMetadata: "traces-metadata.json",
+  entityContext: "entity-context.json",
+  renderInput: "render-input.json",
+  report: "evaluation-report.html",
+};
+
+/** Logical names whose VALUE is a sub-directory of evidence files. */
+export const WELL_KNOWN_DIRS: Readonly<Record<string, string>> = {
+  evidence: "evidence",
+  wave6: "wave6",
+};
+
+export interface LoadBundleResult {
+  bundle: RunBundle;
+  ok: boolean;
+}
+
+/**
+ * Identities that mean "this bundle was produced BY the evaluator itself".
+ * Self-grading violates EV-PR-001 (reviewer ≠ executor): an audit must never
+ * grade a run it produced, or it can launder its own non-determinism into a
+ * pass. Compared case-insensitively against the known producer fields.
+ */
+const SELF_PRODUCER_IDENTITIES: ReadonlySet<string> = new Set([
+  "mutagent-evaluator",
+  "@mutagent/evaluator",
+]);
+
+/**
+ * runMeta fields that, by convention, name the process that produced the run.
+ * Checked in order; the first present string value is taken as the producer.
+ */
+const PRODUCER_FIELDS: readonly string[] = ["producer", "tool", "generator"];
+
+/**
+ * EV-PR-001 provenance guard. Inspects the audited run's runMeta for a
+ * producer/tool/generator marker. If it explicitly identifies the evaluator
+ * itself, THROW — a self-produced bundle must not be silently audited.
+ *
+ * ABSENCE of any producer field is OK (the common case; the bundle was produced
+ * by some other process that simply doesn't stamp provenance).
+ */
+function assertNotSelfProduced(runMeta: unknown, bundleDir: string): void {
+  if (typeof runMeta !== "object" || runMeta === null) return;
+  const meta = runMeta as Record<string, unknown>;
+  for (const field of PRODUCER_FIELDS) {
+    const value = meta[field];
+    if (typeof value !== "string") continue;
+    if (SELF_PRODUCER_IDENTITIES.has(value.trim().toLowerCase())) {
+      throw new Error(
+        `load-bundle: reviewer ≠ executor (EV-PR-001) — this bundle is marked as ` +
+          `self-produced (runMeta.${field} = "${value}"); the evaluator must not ` +
+          `audit a run it produced itself: ${bundleDir}`,
+      );
+    }
+  }
+}
+
+function parseJsonSafe(path: string): { value?: unknown; error?: string } {
+  try {
+    return { value: JSON.parse(readFileSync(path, "utf8")) };
+  } catch (e) {
+    return { error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+/**
+ * Load + validate a run-bundle. Throws ONLY when the bundle directory does not
+ * exist (the one structural prerequisite). Everything else is a warning.
+ */
+export function loadBundle(bundleDir: string, runId?: string): LoadBundleResult {
+  if (!existsSync(bundleDir) || !statSync(bundleDir).isDirectory()) {
+    throw new Error(
+      `load-bundle: bundle directory not found or not a directory: ${bundleDir}`,
+    );
+  }
+
+  const artifacts: Record<string, string> = {};
+  const data: Record<string, unknown> = {};
+  const warnings: string[] = [];
+
+  for (const [logical, rel] of Object.entries(WELL_KNOWN_ARTIFACTS)) {
+    const abs = join(bundleDir, rel);
+    if (!existsSync(abs)) {
+      warnings.push(`optional artifact missing: ${rel}`);
+      continue;
+    }
+    artifacts[logical] = abs;
+    if (rel.endsWith(".json")) {
+      const { value, error } = parseJsonSafe(abs);
+      if (error) {
+        warnings.push(`artifact ${rel} present but failed to parse: ${error}`);
+      } else {
+        data[logical] = value;
+      }
+    }
+  }
+
+  // EV-PR-001 provenance guard: a bundle the evaluator produced itself must not
+  // be silently audited (reviewer ≠ executor). Runs as soon as runMeta is
+  // parsed; absence of a producer marker is OK (the common case).
+  assertNotSelfProduced(data.runMeta, bundleDir);
+
+  // Directory-shaped artifacts: record the sorted file listing (deterministic).
+  for (const [logical, rel] of Object.entries(WELL_KNOWN_DIRS)) {
+    const abs = join(bundleDir, rel);
+    if (!existsSync(abs) || !statSync(abs).isDirectory()) {
+      warnings.push(`optional artifact dir missing: ${rel}/`);
+      continue;
+    }
+    artifacts[logical] = abs;
+    const files = readdirSync(abs)
+      .filter((f) => statSync(join(abs, f)).isFile())
+      .sort();
+    data[logical] = files.map((f) => ({
+      file: f,
+      path: join(abs, f),
+    }));
+  }
+
+  const resolvedRunId =
+    runId ??
+    (typeof (data.runMeta as { runId?: unknown } | undefined)?.runId ===
+    "string"
+      ? (data.runMeta as { runId: string }).runId
+      : basename(bundleDir));
+
+  const bundle: RunBundle = {
+    runId: resolvedRunId,
+    bundleDir,
+    artifacts,
+    data,
+    warnings,
+  };
+
+  // "ok" = at least one well-known artifact was found; a totally empty dir is a
+  // load failure worth surfacing (but not a throw — the caller decides).
+  const ok = Object.keys(artifacts).length > 0;
+  return { bundle, ok };
+}
+
+// ── CLI entrypoint ──────────────────────────────────────────────────────────
+declare const Bun: { argv: string[] } | undefined;
+async function main(): Promise<void> {
+  const argv =
+    typeof Bun !== "undefined" ? Bun.argv.slice(2) : process.argv.slice(2);
+  const bundleDir = argv[0];
+  if (!bundleDir) {
+    console.error("usage: load-bundle.ts <bundleDir> [runId]");
+    process.exit(2);
+  }
+  const { bundle, ok } = loadBundle(bundleDir, argv[1]);
+  console.info(
+    JSON.stringify(
+      {
+        runId: bundle.runId,
+        artifacts: Object.keys(bundle.artifacts),
+        warnings: bundle.warnings,
+        ok,
+      },
+      null,
+      2,
+    ),
+  );
+  process.exit(ok ? 0 : 1);
+}
+
+const isMain =
+  typeof import.meta !== "undefined" &&
+  (import.meta as unknown as { main?: boolean }).main === true;
+if (isMain) {
+  void main();
+}

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/scripts/load-profile-vocab.ts

@@ -0,0 +1,64 @@
+/**
+ * scripts/load-profile-vocab.ts — EV-049 operator-supplied SubjectVocab injection.
+ * ---------------------------------------------------------------------------
+ * `inferVocab` (profile-subject.ts) cannot infer the SEMANTIC vocab fields from
+ * traces alone — which tool is the "send" action, which are "recovery", the guard
+ * counter attribute. It honestly leaves them empty (`sendTool=""`, etc.), and the
+ * engine's honest-null path reports those signals as UNKNOWN rather than a false
+ * `false`. This module is the LEAN injection seam: an operator passes a small
+ * profile file (JSON or YAML) supplying those fields, and we OVERLAY them onto the
+ * inferred-vocab base — WITHOUT hardcoding any subject name in the engine.
+ *
+ * Pure: parse + merge + TypeBox-validate. No clock / random / network.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import {
+  parseSubjectVocab,
+  type SubjectVocab,
+} from "./contracts/eval-types.ts";
+
+/**
+ * Overlay a partial vocab (the operator's profile) onto an inferred-vocab base.
+ * Only fields PRESENT in `partial` override; everything else keeps the base
+ * (inferred) value. Returns a fresh object (no mutation of either input).
+ */
+export function mergeVocab(
+  base: SubjectVocab,
+  partial: Partial<SubjectVocab>,
+): SubjectVocab {
+  return {
+    recoveryTools: partial.recoveryTools ?? base.recoveryTools,
+    eventTags: partial.eventTags ?? base.eventTags,
+    sendTool: partial.sendTool ?? base.sendTool,
+    guardCounterAttr:
+      partial.guardCounterAttr !== undefined
+        ? partial.guardCounterAttr
+        : base.guardCounterAttr,
+  };
+}
+
+/**
+ * Load a profile file (`.json` or `.yaml`/`.yml`), overlay it onto `base`, and
+ * VALIDATE the result against the SubjectVocab schema (fail-loud on a bad field
+ * type — a malformed profile must never silently reach the determiner). A
+ * missing file throws.
+ */
+export function loadProfileVocab(path: string, base: SubjectVocab): SubjectVocab {
+  if (!existsSync(path)) {
+    throw new Error(`load-profile-vocab: profile file not found: ${path}`);
+  }
+  const raw = readFileSync(path, "utf8");
+  const parsed = /\.ya?ml$/i.test(path)
+    ? (parseYaml(raw) as unknown)
+    : (JSON.parse(raw) as unknown);
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(
+      `load-profile-vocab: profile must be a JSON/YAML object of vocab fields: ${path}`,
+    );
+  }
+  const merged = mergeVocab(base, parsed as Partial<SubjectVocab>);
+  // Validate the merged result — overlaying a bad type (e.g. sendTool: 123) must
+  // throw here, not corrupt the determiner's signals downstream.
+  return parseSubjectVocab(merged);
+}

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/scripts/load-profile.ts

@@ -0,0 +1,106 @@
+/**
+ * scripts/load-profile.ts
+ * ---------------------------------------------------------------------------
+ * Loads + validates a subject profile (subjects/<name>/eval-matrix.yaml and its
+ * siblings) against the TypeBox contracts. The agent ships ZERO subject-specific
+ * logic — everything skill-specific lives in these generated YAML profiles, so
+ * this loader is the gateway that turns profile DATA into typed, validated input
+ * for the deterministic engine.
+ *
+ * Deterministic: pure parse + validate, no clock/random/network.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { Value } from "@sinclair/typebox/value";
+import { type EvalMatrix, EvalMatrixSchema } from "./contracts/types.ts";
+
+export interface ProfilePaths {
+  evalMatrix: string;
+  behaviorTree: string;
+  methodologyReview: string;
+}
+
+export function resolveProfilePaths(
+  subjectsRoot: string,
+  subject: string,
+): ProfilePaths {
+  const dir = join(subjectsRoot, subject);
+  return {
+    evalMatrix: join(dir, "eval-matrix.yaml"),
+    behaviorTree: join(dir, "behavior-tree.yaml"),
+    methodologyReview: join(dir, "methodology-review.yaml"),
+  };
+}
+
+export interface LoadedEvalMatrix {
+  matrix: EvalMatrix;
+  errors: string[];
+}
+
+/**
+ * Load + TypeBox-validate the eval-matrix. Returns structured errors (never a
+ * boolean-only verdict) so callers can fail-loud with all schema violations.
+ */
+export function loadEvalMatrix(path: string): LoadedEvalMatrix {
+  if (!existsSync(path)) {
+    throw new Error(`load-profile: eval-matrix not found: ${path}`);
+  }
+  const raw = readFileSync(path, "utf8");
+  const parsed = parseYaml(raw) as unknown;
+
+  const errors: string[] = [];
+  for (const err of Value.Errors(EvalMatrixSchema, parsed)) {
+    errors.push(`${err.path || "/"}: ${err.message}`);
+  }
+  // Even on schema errors we return the parsed value so a count assertion can
+  // still run; callers decide whether to proceed.
+  return { matrix: parsed as EvalMatrix, errors };
+}
+
+/** Raw YAML loader for the behavior-tree / methodology-review (judge-side). */
+export function loadYamlFile(path: string): unknown {
+  if (!existsSync(path)) {
+    throw new Error(`load-profile: file not found: ${path}`);
+  }
+  return parseYaml(readFileSync(path, "utf8")) as unknown;
+}
+
+/** Total criteria across all components — used by the 132-count acceptance. */
+export function countCriteria(matrix: EvalMatrix): number {
+  return matrix.components.reduce((n, c) => n + c.criteria.length, 0);
+}
+
+// ── CLI entrypoint ──────────────────────────────────────────────────────────
+declare const Bun: { argv: string[] } | undefined;
+function main(): void {
+  const argv =
+    typeof Bun !== "undefined" ? Bun.argv.slice(2) : process.argv.slice(2);
+  const path = argv[0];
+  if (!path) {
+    console.error("usage: load-profile.ts <eval-matrix.yaml>");
+    process.exit(2);
+  }
+  const { matrix, errors } = loadEvalMatrix(path);
+  console.info(
+    JSON.stringify(
+      {
+        subject: matrix.subject,
+        version: matrix.version,
+        components: matrix.components?.length ?? 0,
+        criteria: errors.length === 0 ? countCriteria(matrix) : "n/a",
+        schemaErrors: errors,
+      },
+      null,
+      2,
+    ),
+  );
+  process.exit(errors.length === 0 ? 0 : 1);
+}
+
+const isMain =
+  typeof import.meta !== "undefined" &&
+  (import.meta as unknown as { main?: boolean }).main === true;
+if (isMain) {
+  main();
+}