@mutagent/helix 0.1.0-alpha.14

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/scripts/cli/methodology-review.ts

@@ -0,0 +1,122 @@
+/**
+ * scripts/cli/methodology-review.ts — Mode C entrypoint.
+ * ---------------------------------------------------------------------------
+ * Mode C emits process self-feedback: is the methodology the RIGHT/efficient
+ * choice + how to rearrange (advisory, NOT pass/fail). §1.5 family / MR-1..9.
+ *
+ * MATURITY — functional seam, not fully wired:
+ *   The deterministic spine here is REAL: it loads the subject's behavior-tree +
+ *   methodology-review rubric, loads the run-bundle, and assembles the JUDGE
+ *   PROMPT CONTEXT (the behavior-tree nodes + the run trajectory + the MR rubric)
+ *   that the methodology-critic lens consumes. The actual fitness REASONING
+ *   (decision-tree fitness · data-flow efficiency · ranked self-feedback) is a
+ *   PINNED-JUDGE SEAM — it requires the pinned model running the
+ *   lenses/methodology-critic-lens.md prompt. This CLI prepares + emits the
+ *   judge context (so the judge has a complete, deterministic input) and marks
+ *   the seam; it never fabricates fitness verdicts.
+ *
+ *   methodology-review.ts <runId> --subject <name> [--bundle-dir <dir>]
+ *                         [--subjects-root <dir>]
+ */
+import { writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveProfilePaths, loadYamlFile } from "../load-profile.ts";
+import { loadBundle } from "../load-bundle.ts";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = join(HERE, "..", "..");
+
+interface Args {
+  runId: string;
+  subject: string;
+  bundleDir: string;
+  subjectsRoot: string;
+  out?: string;
+}
+
+function parseArgs(argv: string[]): Args {
+  const positional: string[] = [];
+  const flags: Record<string, string> = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      flags[a.slice(2)] = argv[i + 1] ?? "";
+      i++;
+    } else positional.push(a);
+  }
+  if (!positional[0] || !flags.subject) {
+    throw new Error(
+      "usage: methodology-review.ts <runId> --subject <name> [--bundle-dir <dir>] [--subjects-root <dir>] [--out <file>]",
+    );
+  }
+  return {
+    runId: positional[0],
+    subject: flags.subject,
+    bundleDir:
+      flags["bundle-dir"] ||
+      join(process.cwd(), ".mutagent/diagnostics", positional[0]),
+    subjectsRoot: flags["subjects-root"] || join(PKG_ROOT, "subjects"),
+    out: flags.out || undefined,
+  };
+}
+
+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 paths = resolveProfilePaths(args.subjectsRoot, args.subject);
+  const behaviorTree = loadYamlFile(paths.behaviorTree);
+  const mrRubric = loadYamlFile(paths.methodologyReview);
+  const { bundle } = loadBundle(args.bundleDir, args.runId);
+
+  // Assemble the COMPLETE, deterministic judge context. The judge (the pinned
+  // model running the methodology-critic lens) consumes exactly this.
+  const judgeContext = {
+    subject: args.subject,
+    runId: bundle.runId,
+    behaviorTree,
+    methodologyRubric: mrRubric,
+    runTrajectory: {
+      runMeta: bundle.data.runMeta ?? null,
+      renderInput: bundle.data.renderInput ?? null,
+      evidence: bundle.data.evidence ?? null,
+    },
+    seam: "PINNED-JUDGE: the fitness reasoning (decision-tree fitness, data-flow efficiency, ranked self-feedback) is produced by the pinned model running lenses/methodology-critic-lens.md over this context. This CLI emits the context; it does not fabricate fitness verdicts.",
+  };
+
+  const json = JSON.stringify(judgeContext, null, 2);
+  if (args.out) writeFileSync(args.out, json + "\n");
+
+  console.info(
+    JSON.stringify(
+      {
+        subject: args.subject,
+        runId: bundle.runId,
+        behaviorTreeNodes: Array.isArray(
+          (behaviorTree as { nodes?: unknown[] })?.nodes,
+        )
+          ? (behaviorTree as { nodes: unknown[] }).nodes.length
+          : 0,
+        mrItems: Array.isArray((mrRubric as { items?: unknown[] })?.items)
+          ? (mrRubric as { items: unknown[] }).items.length
+          : 0,
+        judgeContextOut: args.out ?? "(stdout only)",
+        seam: judgeContext.seam,
+      },
+      null,
+      2,
+    ),
+  );
+  return 0;
+}
+
+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/cli/prep.ts

@@ -0,0 +1,295 @@
+/**
+ * scripts/cli/prep.ts — the PREP entrypoint for the agent-dispatch engine.
+ * ---------------------------------------------------------------------------
+ * Emits the task-spec files the parent session dispatches to eval-judge /
+ * error-analyst subagents (references/workflows/orchestrator-protocol.md). This
+ * is the I/O shell over the TESTED PREP cores (scripts/prep-tasks.ts); it calls
+ * NO LLM and NO provider — it only writes the EXACT prompts to be judged on the
+ * host runtime, keyed by content hash.
+ *
+ *   prep.ts --stage determiner --traces <handover.jsonl|.gz> --task-dir <dir> --model <pinned>
+ *           [--profile <vocab.json|.yaml>]  # operator-supplied SubjectVocab (EV-049)
+ *           [--source <name>]               # SELECTION override — pick a source by name
+ *   prep.ts --stage judge      --traces <f> --criteria <criteria.json> \
+ *           --verdict-dir <discover-verdicts> --task-dir <dir> --model <pinned>
+ *
+ * SOURCE SELECTION (--source): when `global.sources[]` has >1 entry and none is
+ * `default:true`, the run-start config surfaces a `needs-selection` state; the
+ * PARENT session then ASKS the operator to pick one (AskUserQuestion / chat
+ * multi-choice) and re-invokes with `--source <name>`. When >1 entry has exactly
+ * one `default:true`, the config surfaces `confirm-default` (F2) — the PARENT
+ * CONFIRMS the preselected default (a yes/no ask; distinct from the open pick)
+ * before it is used. A single source or an explicit `--source` skips the prompt.
+ *
+ * MODEL INTENT SACRED: --model is the pinned host model (temperature pinned 0,
+ * C-PIN); it is carried verbatim on every task spec for the subagent to honor —
+ * never swapped. The `judge` stage REQUIRES the determiner verdict files
+ * (--verdict-dir) already collected (Stage A done) — see the protocol.
+ */
+import { execSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parseUnitfJsonl } from "../read-unitf-traces.ts";
+import { prepDeterminerTasks, prepJudgeTasks } from "../prep-tasks.ts";
+import { selectColdStartSuite, type ColdStartMeta } from "../cold-start-project.ts";
+import { profileSubject } from "../profile-subject.ts";
+import { loadProfileVocab } from "../load-profile-vocab.ts";
+import { buildMatrixPacket, writeMatrixPacket, packetFileName } from "../matrix-judge.ts";
+import { configPathFor, loadEvaluatorConfig, type SourceBinding } from "../config/load.ts";
+import { readMemoryDir, renderRecallContext } from "../memory/read.ts";
+import type { ContextLink } from "../config/schema.ts";
+import type { JudgeTaskSpec, PinnedEnvelope } from "../agent-dispatch.ts";
+import type { PipelineOptions } from "../run-pipeline.ts";
+import type { DiscoveredCriterion } from "../contracts/eval-types.ts";
+import type { MatrixCriterion } from "../contracts/eval-matrix.ts";
+import { SubjectKind } from "../route-failures.ts";
+
+function flag(argv: string[], name: string): string | undefined {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined;
+}
+
+/**
+ * Surface the SELECTION contract's source-binding state so the PARENT session can
+ * wire the run-start ASK. prep runs in a subagent-context I/O shell that CANNOT
+ * invoke AskUserQuestion — so it prints the binding + candidate names; the parent
+ * (which owns the ask mechanism: AskUserQuestion on Claude Code / chat multi-choice
+ * elsewhere) does the actual PROMPT. `bound` (single · `default:true` · `--source`)
+ * ⇒ silent, no prompt. `needs-selection` is NON-fatal for gating (the source EXISTS;
+ * only DISCOVER needs a pick — code/dataset runs need no source at all).
+ */
+function surfaceSourceBinding(binding: SourceBinding): void {
+  switch (binding.kind) {
+    case "confirm-default": {
+      // F2 — a preselected default among many: surface a CONFIRM ask (yes/no),
+      // distinct from the open needs-selection pick. NON-fatal: the default is usable
+      // as-is on accept / non-interactive / --source.
+      const names = binding.sources.map((s) => s.name).join(", ");
+      process.stdout.write(
+        `prep: source CONFIRM-DEFAULT — ${binding.sources.length} sources, default is ` +
+          `'${binding.source.name}'. PARENT: confirm the default via the platform ask ` +
+          `mechanism (AskUserQuestion / chat multi-choice; '${binding.source.name}' PRESELECTED, ` +
+          `operator may override), or accept it non-interactively (--source <name> / CI). ` +
+          `Candidates: ${names}\n`,
+      );
+      break;
+    }
+    case "needs-selection": {
+      const names = binding.sources.map((s) => s.name).join(", ");
+      process.stdout.write(
+        `prep: source SELECTION required — ${binding.sources.length} sources, none default. ` +
+          `PARENT: ask the operator to pick one via the platform ask mechanism ` +
+          `(AskUserQuestion / chat multi-choice), then re-run with --source <name>. ` +
+          `Candidates: ${names}\n`,
+      );
+      break;
+    }
+    case "multiple-defaults": {
+      const names = binding.sources.filter((s) => s.default === true).map((s) => s.name).join(", ");
+      process.stderr.write(
+        `prep: ambiguous config — >1 source marked default:true (${names}). ` +
+          `Fix the config (exactly one default) or pass --source <name>.\n`,
+      );
+      break;
+    }
+    case "unknown-name":
+      process.stderr.write(
+        `prep: --source "${binding.name}" matched no source in global.sources[].\n`,
+      );
+      break;
+    // `bound` (silent — nothing to ask) / `none` (no source; code/dataset runs are fine): no output.
+    case "bound":
+    case "none":
+      break;
+  }
+}
+
+/**
+ * Config → flag precedence for the pinned judge model. The `--model` FLAG WINS;
+ * the unified `.mutagent/config.yaml` (`global.models.{judge_model,default}`)
+ * fills the gap. Model-intent-sacred: no silent swap — this only supplies a
+ * DEFAULT when the operator gave no `--model`. Also reads AutoMemory + context
+ * links at run start (additive; an absent config is a no-op). `--project-root`
+ * (default cwd) locates the LOCAL `.mutagent/`. Returns the resolved model (or
+ * undefined) + a compact run-start context banner (recall + context links).
+ */
+function resolveRunStartConfig(argv: string[]): {
+  modelFromConfig: string | undefined;
+  startContext: string;
+} {
+  const projectRoot = resolve(flag(argv, "project-root") ?? process.cwd());
+  // SELECTION contract: `--source <name>` is the explicit run-time source override
+  // (WINS over `default:true` / auto-bind); absent ⇒ default precedence.
+  const selectSourceName = flag(argv, "source");
+  const cfg = loadEvaluatorConfig(configPathFor(projectRoot), { selectSourceName });
+
+  let modelFromConfig: string | undefined;
+  const contextLinks: ContextLink[] = [];
+  if (cfg.status === "migration-required") {
+    // Fork B — surface the migration directive; do NOT parse the old shape.
+    process.stderr.write(`prep: ${cfg.error}\n`);
+  } else if (cfg.status === "ok") {
+    if (cfg.config.judgeModel.kind === "resolved") modelFromConfig = cfg.config.judgeModel.model;
+    // PHASE 4 — load global.context[] (every run) + lifecycle.evaluator.context[].
+    contextLinks.push(...cfg.config.globalContext, ...cfg.config.evaluatorContext);
+    // SELECTION — surface the source-binding state so the PARENT session can wire
+    // the run-start ASK (prep is a subagent-context I/O shell — it cannot invoke
+    // AskUserQuestion; it SURFACES the state + candidate names, the parent prompts).
+    surfaceSourceBinding(cfg.config.source);
+  }
+
+  // PHASE 3 — read AutoMemory at run start, filtered to {evaluate, general}.
+  const memory = readMemoryDir(join(projectRoot, ".mutagent", "memory"));
+  const parts: string[] = [];
+  const recall = renderRecallContext(memory.entries);
+  if (recall !== "") parts.push(recall);
+  if (contextLinks.length > 0) {
+    parts.push(
+      "Context links:\n" +
+        contextLinks.map((c) => `- ${c.path} — ${c.what} (why: ${c.why}; when: ${c.when})`).join("\n"),
+    );
+  }
+  return { modelFromConfig, startContext: parts.join("\n\n") };
+}
+
+/**
+ * Load the handed-over UniTF trace file as text (`mutagent-cli trace fetch
+ * --export` writes one `UnifiedTrace` record per line). `.gz` → gunzip | jq -c;
+ * else read text. `parseUnitfJsonl` projects each UniTF record → EvalTrace. The
+ * skill NEVER fetches — Helix runs `mutagent-cli trace fetch` before dispatch.
+ */
+function loadNdjson(file: string, limit?: number): string {
+  const headN = limit !== undefined ? ` | head -n ${limit}` : "";
+  if (file.endsWith(".gz")) {
+    return execSync(`gunzip -c ${JSON.stringify(file)} | jq -c '.'${headN}`, {
+      maxBuffer: 1024 * 1024 * 512,
+      encoding: "utf8",
+    });
+  }
+  const text = readFileSync(file, "utf8");
+  if (limit === undefined) return text;
+  return text.split("\n").slice(0, limit).join("\n");
+}
+
+/**
+ * Write a manifest of emitted task keys → verdict files (what the parent must
+ * dispatch + collect). When the determiner (cold discover) stage subsamples via
+ * the cold-start sampler, its `coldStart` block rides along so a thin-negative
+ * cold suite is surfaced to the parent as LOW-CONFIDENCE (the report metadata).
+ */
+function writeManifest(taskDir: string, specs: JudgeTaskSpec[], coldStart?: ColdStartMeta): void {
+  const manifest = {
+    count: specs.length,
+    tasks: specs.map((s) => ({ key: s.key, unit: s.unit, taskFile: `${s.key}.task.json`, verdictFile: s.verdictFile })),
+    ...(coldStart !== undefined ? { coldStart } : {}),
+  };
+  writeFileSync(join(taskDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+}
+
+async function main(): Promise<void> {
+  const argv = process.argv.slice(2);
+  const stage = flag(argv, "stage");
+  const tracesFile = flag(argv, "traces");
+  const taskDir = flag(argv, "task-dir");
+  const limit = flag(argv, "limit");
+
+  // Config → flag precedence: --model WINS; the unified config supplies the
+  // default (global.models.judge_model/default). Also reads AutoMemory + context
+  // links at run start (additive — absent config/memory is a no-op).
+  const { modelFromConfig, startContext } = resolveRunStartConfig(argv);
+  const model = flag(argv, "model") ?? modelFromConfig;
+
+  if (tracesFile === undefined || taskDir === undefined || model === undefined) {
+    throw new Error(
+      "prep: --traces <f>, --task-dir <dir> and a pinned model are required " +
+        "(--model <pinned> OR global.models.judge_model/default in .mutagent/config.yaml)",
+    );
+  }
+  if (startContext !== "") process.stdout.write(`prep: run-start context —\n${startContext}\n`);
+  const pin: PinnedEnvelope = { model, temperature: 0 };
+  const ndjson = loadNdjson(tracesFile, limit !== undefined ? Number.parseInt(limit, 10) : undefined);
+  const { traces } = parseUnitfJsonl(ndjson);
+
+  // DEFAULT *evaluate PREP — one eval-matrix packet per trajectory (the headline cell).
+  if (stage === "matrix") {
+    const criteriaFile = flag(argv, "criteria");
+    if (criteriaFile === undefined) {
+      throw new Error("prep --stage matrix: --criteria <matrix.json> is required");
+    }
+    const matrix = JSON.parse(readFileSync(criteriaFile, "utf8")) as MatrixCriterion[];
+    const subjectName = traces[0]?.name ?? "unknown-subject";
+    const ids = traces.map((trace) => writeMatrixPacket(taskDir, buildMatrixPacket(subjectName, trace, matrix, pin)));
+    writeFileSync(
+      join(taskDir, "manifest.json"),
+      JSON.stringify({ count: ids.length, packets: ids.map((id) => ({ trajectoryId: id, packetFile: packetFileName(id) })) }, null, 2),
+    );
+    process.stdout.write(`prep: stage=matrix emitted ${ids.length} trajectory packet(s) → ${taskDir}\n`);
+    return;
+  }
+
+  let specs: JudgeTaskSpec[];
+  let coldStartMeta: ColdStartMeta | undefined;
+  if (stage === "determiner") {
+    // The determiner reads its subject vocab off the profile (EV-002 / EV-049).
+    // The profiler auto-infers a best-effort vocab; the SEMANTIC fields it can't
+    // infer (sendTool / recoveryTools / guardCounterAttr) stay empty → the engine
+    // reports those signals as UNKNOWN (honest-null). An operator may supply them
+    // via `--profile <f>` (JSON/YAML), which OVERLAYS the inferred-vocab base —
+    // e.g. `{"sendTool":"sendMessage"}` for a sample subject — with NO subject
+    // name hardcoded in the engine.
+    const inferred = profileSubject(traces).vocab;
+    const profileFile = flag(argv, "profile");
+    const vocab =
+      profileFile !== undefined ? loadProfileVocab(profileFile, inferred) : inferred;
+    // EV-5.3 COLD-START SUBSAMPLE (the SAFE call site) — the determiner IS the cold
+    // discover front-door: there is NO suite/judge yet, so we balance a ✓/✗ bootstrap
+    // from mechanical labels FIRST, then hand the SELECTED traces to the untouched
+    // `prepDeterminerTasks` (which still emits exactly one determiner task per
+    // selected trace). `--cold-size` caps the suite; absent ⇒ the incoming trace
+    // count, a PASS-THROUGH that only subsamples when an explicit cap is given (its
+    // own ✓/✗ imbalance still flags low-confidence). Cold path ONLY — the warm
+    // (suite-present) judge stage below NEVER touches the sampler.
+    const coldSizeFlag = flag(argv, "cold-size");
+    const coldSize = coldSizeFlag !== undefined ? Number.parseInt(coldSizeFlag, 10) : traces.length;
+    const cold = selectColdStartSuite(traces, { size: coldSize });
+    coldStartMeta = cold.meta;
+    specs = prepDeterminerTasks(cold.selected, { dir: taskDir, pin, vocab });
+  } else if (stage === "judge") {
+    const criteriaFile = flag(argv, "criteria");
+    const verdictDir = flag(argv, "verdict-dir");
+    if (criteriaFile === undefined || verdictDir === undefined) {
+      throw new Error("prep --stage judge: --criteria <f> and --verdict-dir <discover-verdicts> are required");
+    }
+    const criteria = JSON.parse(readFileSync(criteriaFile, "utf8")) as DiscoveredCriterion[];
+    const subjectName = traces[0]?.name ?? "unknown-subject";
+    const pipeline: PipelineOptions = {
+      criteria,
+      pin: { modelId: model, temperature: 0 },
+      subject: { kind: SubjectKind.Agent, name: subjectName, path: `subjects/${subjectName}` },
+      producedBy: "mutagent-evaluator/prep",
+      producedAt: "1970-01-01T00:00:00Z", // PREP-only stamp — judge prompts don't depend on it
+    };
+    specs = await prepJudgeTasks(traces, { verdictDir, taskDir, pin, pipeline });
+  } else {
+    throw new Error("prep: --stage must be 'matrix' (default *evaluate), 'determiner', or 'judge'");
+  }
+
+  writeManifest(taskDir, specs, coldStartMeta);
+  process.stdout.write(
+    `prep: stage=${stage} emitted ${specs.length} task-spec(s) → ${taskDir} ` +
+      `(unique by content key: ${new Set(specs.map((s) => s.key)).size})\n`,
+  );
+  if (coldStartMeta !== undefined) {
+    process.stdout.write(
+      `prep: cold-start suite ${coldStartMeta.selected}/${coldStartMeta.input} traces ` +
+        `(✓${coldStartMeta.passCount} ✗${coldStartMeta.failCount}` +
+        `${coldStartMeta.minBothHeld ? "" : ", MIN-BOTH BROKEN"})` +
+        `${coldStartMeta.lowConfidence ? " — LOW-CONFIDENCE (thin negatives; re-balance after real verdicts)" : ""}\n`,
+    );
+  }
+}
+
+main().catch((err: unknown) => {
+  process.stderr.write(`prep FAILED: ${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+});

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/scripts/cli/profile-subject.ts

@@ -0,0 +1,165 @@
+/**
+ * scripts/cli/profile-subject.ts — Mode B entrypoint.
+ * ---------------------------------------------------------------------------
+ * Mode B GENERATES a subject profile (subjects/<name>/{eval-matrix,behavior-tree,
+ * methodology-review}.yaml) from a skill/agent definition + traces. This is how
+ * the matrix is BORN — generated, not embedded in the agent.
+ *
+ * MATURITY — functional seam, not fully wired:
+ *   The deterministic spine here is REAL: it (a) validates inputs exist, (b)
+ *   scaffolds the subjects/<name>/ directory, and (c) writes schema-conformant
+ *   SEED YAML files (empty-but-valid frames carrying subject/version/generatedAt
+ *   + the 12 design principles + the MR-1..9 rubric skeleton) that pass the
+ *   shape contracts. The criteria-DERIVATION step (reading the def + traces and
+ *   proposing component x dimension x checkMethod rows + an interesting-dataset
+ *   shortlist) is a PINNED-JUDGE SEAM — it requires the pinned model reasoning
+ *   over the subject's source + traces. The agent card's Mode-B workflow + the
+ *   audit workflow dispatch that judge. This CLI writes the SEED + marks the
+ *   seam; it never fabricates derived criteria silently.
+ *
+ *   profile-subject.ts <defPath> <tracesPath> --name <subject>
+ *                      [--subjects-root <dir>] [--generated-at <iso>]
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { stringify as stringifyYaml } from "yaml";
+import { DEFAULT_GENERATED_AT } from "./audit-run.ts";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = join(HERE, "..", "..");
+
+const MR_RUBRIC_SKELETON = [
+  { id: "MR-1", title: "Decision-tree fitness", reads: "behavior-tree + run outcomes", how: "judge reasons over each fork vs what the run needed", family: "decision-tree-fitness", advisory: true },
+  { id: "MR-2", title: "Data-flow efficiency", reads: "pipeline trace", how: "scan for redundant/recomputed transforms, collapsible stages", family: "data-flow-efficiency", advisory: true },
+  { id: "MR-3", title: "Methodology fitness given findings", reads: "run trajectory + findings", how: "did depth/breadth match the need?", family: "methodology-fitness", advisory: true },
+  { id: "MR-4", title: "Sequence soundness", reads: "transcript trajectory", how: "does later work invalidate earlier work?", family: "sequence-soundness", advisory: true },
+  { id: "MR-5", title: "Process self-feedback", reads: "all of the above", how: "ranked rearrange/improve proposals", family: "process-self-feedback", advisory: true },
+  { id: "MR-6", title: "Followed != Right", reads: "matrix (Tab-1) vs this (Tab-4)", how: "separate conformance from fitness", family: "conformance-vs-fitness", advisory: true },
+  { id: "MR-7", title: "Signal/failure-mode selection", reads: "tier0 -> awareness -> deep-read chain", how: "was the primary signal grounded in the right evidence tier?", family: "signal-selection", advisory: true },
+  { id: "MR-8", title: "Confidence derivation", reads: "coverageConfidence vs deep-read sample", how: "does the confidence FOLLOW from the LLM-trace evidence?", family: "confidence-derivation", advisory: true },
+  { id: "MR-9", title: "Focus determination -> search-shaping", reads: "scope/focus decision + examined traces", how: "expected-focus vs observed-focus given brief + tier-0 signals", family: "focus-determination", advisory: true },
+];
+
+const DESIGN_PRINCIPLES_SEED = [
+  "Determinism-before-judgment: prefer deterministic-script / typebox-schema / gate; reserve llm-judge + trajectory-diff for genuinely behavioral rows.",
+  "Severity by variance-impact, not code size.",
+  "Three-dimension MECE coverage per component (operation-correctness / data-correctness / operational-deviation).",
+  "Full-dereference-surface gate principle (C-GATE).",
+  "Pin-and-record every stochastic/environmental variable (C-PIN), honoring model-intent-sacred.",
+  "Byte-identity masking contract as the determinism acceptance test.",
+  "Scope-locus attribution for every criterion (MECE SKILL/AGENT/COMMAND).",
+  "Existing-coverage honesty: covered/partial/none against the actual test+gate inventory.",
+  "No-filler rule: every criterion grounded in a cited intended behavior or observed deviation.",
+];
+
+interface Args {
+  defPath: string;
+  tracesPath: string;
+  name: string;
+  subjectsRoot: string;
+  generatedAt: string;
+}
+
+function parseArgs(argv: string[]): Args {
+  const positional: string[] = [];
+  const flags: Record<string, string> = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      flags[a.slice(2)] = argv[i + 1] ?? "";
+      i++;
+    } else positional.push(a);
+  }
+  if (positional.length < 2 || !flags.name) {
+    throw new Error(
+      "usage: profile-subject.ts <defPath> <tracesPath> --name <subject> [--subjects-root <dir>] [--generated-at <iso>]",
+    );
+  }
+  return {
+    defPath: positional[0],
+    tracesPath: positional[1],
+    name: flags.name,
+    subjectsRoot: flags["subjects-root"] || join(PKG_ROOT, "subjects"),
+    generatedAt: flags["generated-at"] || DEFAULT_GENERATED_AT,
+  };
+}
+
+export function main(argvIn?: string[]): number {
+  const argv =
+    argvIn ??
+    (typeof Bun !== "undefined" ? Bun.argv.slice(2) : process.argv.slice(2));
+  const args = parseArgs(argv);
+
+  if (!existsSync(args.defPath)) {
+    console.error(`profile-subject: definition not found: ${args.defPath}`);
+    return 2;
+  }
+  if (!existsSync(args.tracesPath)) {
+    console.error(`profile-subject: traces not found: ${args.tracesPath}`);
+    return 2;
+  }
+
+  const dir = join(args.subjectsRoot, args.name);
+  mkdirSync(dir, { recursive: true });
+
+  // SEED frames — schema-conformant, empty components/nodes awaiting the judge.
+  const evalMatrixSeed = {
+    subject: args.name,
+    version: "v1",
+    generatedAt: args.generatedAt,
+    designPrinciples: DESIGN_PRINCIPLES_SEED,
+    components: [] as unknown[],
+  };
+  const behaviorTreeSeed = {
+    subject: args.name,
+    version: "v1",
+    generatedAt: args.generatedAt,
+    root: "ROOT",
+    nodes: [] as unknown[],
+  };
+  const methodologyReviewSeed = {
+    subject: args.name,
+    version: "v1",
+    generatedAt: args.generatedAt,
+    items: MR_RUBRIC_SKELETON,
+  };
+
+  writeFileSync(
+    join(dir, "eval-matrix.yaml"),
+    "# SEED profile — components[] derived by the Mode-B pinned-judge seam.\n" +
+      stringifyYaml(evalMatrixSeed),
+  );
+  writeFileSync(
+    join(dir, "behavior-tree.yaml"),
+    "# SEED behavior-tree — nodes[] derived by the Mode-B pinned-judge seam.\n" +
+      stringifyYaml(behaviorTreeSeed),
+  );
+  writeFileSync(
+    join(dir, "methodology-review.yaml"),
+    "# MR rubric — MR-1..9 skeleton (generic, reused per subject).\n" +
+      stringifyYaml(methodologyReviewSeed),
+  );
+
+  console.info(
+    JSON.stringify(
+      {
+        subject: args.name,
+        seededAt: dir,
+        files: ["eval-matrix.yaml", "behavior-tree.yaml", "methodology-review.yaml"],
+        seam: "PINNED-JUDGE: criteria + behavior-tree nodes + interesting-dataset shortlist are derived by the Mode-B judge reading the def + traces. SEED frames written; derived rows NOT fabricated.",
+      },
+      null,
+      2,
+    ),
+  );
+  return 0;
+}
+
+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/cli/run.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# scripts/cli/run.sh — bun -> pnpm-tsx -> npx-tsx fallback selector + .sh dispatch.
+# Usage: scripts/cli/run.sh <script-path.{ts|sh}> [args...]
+#        scripts/cli/run.sh --selftest
+#
+# All engine invocations go through this wrapper so the package stays portable
+# across bun/pnpm/npm hosts with zero Bun.* API dependence.
+#
+# Platform matrix — which tier fires when:
+#   Tier 1 (bun)      : bun is on PATH
+#   Tier 2 (pnpm-tsx) : bun absent, pnpm on PATH
+#   Tier 3 (npx-tsx)  : bun + pnpm absent, npx on PATH
+#   Tier 4 (error)    : none of the above — exits 1 with install guidance
+
+set -e
+
+SCRIPT="$1"
+
+if [ "$SCRIPT" = "--selftest" ]; then
+  if command -v bun >/dev/null 2>&1; then
+    echo "run.sh selftest: tier=1 runtime=bun version=$(bun --version 2>/dev/null || echo unknown)"
+  elif command -v pnpm >/dev/null 2>&1; then
+    echo "run.sh selftest: tier=2 runtime=pnpm-tsx version=$(pnpm --version 2>/dev/null || echo unknown)"
+  elif command -v npx >/dev/null 2>&1; then
+    echo "run.sh selftest: tier=3 runtime=npx-tsx version=$(node --version 2>/dev/null || echo unknown)"
+  else
+    echo "run.sh selftest: tier=4 runtime=none (install bun: curl -fsSL https://bun.sh/install | bash)"
+    exit 1
+  fi
+  exit 0
+fi
+
+shift || true
+
+if [ -z "$SCRIPT" ]; then
+  echo "ERROR: no script path provided" >&2
+  echo "Usage: run.sh <script.{ts|sh}> [args...]" >&2
+  echo "       run.sh --selftest" >&2
+  exit 1
+fi
+
+case "$SCRIPT" in
+  *.sh) exec bash "$SCRIPT" "$@" ;;
+esac
+
+if command -v bun >/dev/null 2>&1; then
+  exec bun run "$SCRIPT" "$@"
+elif command -v pnpm >/dev/null 2>&1; then
+  exec pnpm exec tsx "$SCRIPT" "$@"
+elif command -v npx >/dev/null 2>&1; then
+  exec npx tsx "$SCRIPT" "$@"
+else
+  echo "ERROR: mutagent-evaluator requires bun, pnpm, or npm/npx to run TypeScript scripts" >&2
+  echo "Install bun: curl -fsSL https://bun.sh/install | bash" >&2
+  exit 1
+fi