slice-tournament-zoo 0.5.6

package/src/budget.ts

@@ -0,0 +1,78 @@
+/**
+ * Adaptive complexity-based budgeting (F15, N5).
+ *
+ * Elicitation emits a complexity score 1..5 per slice. The orchestrator
+ * allocates token + wall-clock budget from a project pool against complexity.
+ * Actuals feed back into a calibration table so future estimates improve.
+ */
+import type { Budget } from "./types.js";
+
+export interface BudgetConfig {
+  /** Project-level token pool to draw from. */
+  poolTokens: number;
+  /** Base tokens for a complexity-1 slice. */
+  baseTokens: number;
+  /** Multiplier applied per complexity step above 1. */
+  perComplexity: number;
+  /** Base wall-clock per slice (ms). Default 30 min (N4). */
+  baseWallClockMs: number;
+}
+
+export const DEFAULT_BUDGET_CONFIG: BudgetConfig = {
+  poolTokens: 5_000_000,
+  baseTokens: 200_000,
+  perComplexity: 1.6,
+  baseWallClockMs: 30 * 60_000,
+};
+
+export function clampComplexity(c: number): number {
+  if (Number.isNaN(c)) return 1;
+  return Math.max(1, Math.min(5, Math.round(c)));
+}
+
+/**
+ * Allocate a per-slice budget. Token cap grows geometrically with complexity
+ * but is never allowed to exceed the remaining pool.
+ */
+export function allocateBudget(
+  complexity: number,
+  poolRemaining: number,
+  cfg: BudgetConfig = DEFAULT_BUDGET_CONFIG,
+): Budget {
+  const c = clampComplexity(complexity);
+  const raw = Math.round(cfg.baseTokens * cfg.perComplexity ** (c - 1));
+  const tokenCap = Math.min(raw, Math.max(0, poolRemaining));
+  return {
+    tokenCap,
+    wallClockMs: cfg.baseWallClockMs * (1 + 0.5 * (c - 1)),
+    tokensSpent: 0,
+  };
+}
+
+/** A calibration table entry: estimated vs actual token spend at a complexity. */
+export interface CalibrationEntry {
+  complexity: number;
+  estimated: number;
+  actual: number;
+}
+
+/**
+ * Update the per-complexity calibration multiplier from observed actuals.
+ * Returns a corrected `perComplexity`-style scalar centred on observed ratios.
+ * Simple mean-of-ratios estimator (transparent, auditable).
+ */
+export function calibrate(entries: CalibrationEntry[], cfg = DEFAULT_BUDGET_CONFIG): BudgetConfig {
+  if (entries.length === 0) return cfg;
+  const ratios = entries
+    .filter((e) => e.estimated > 0)
+    .map((e) => e.actual / e.estimated);
+  if (ratios.length === 0) return cfg;
+  const meanRatio = ratios.reduce((a, b) => a + b, 0) / ratios.length;
+  // Nudge baseTokens by the observed ratio so next estimates track actuals.
+  return { ...cfg, baseTokens: Math.round(cfg.baseTokens * meanRatio) };
+}
+
+/** True if spending `add` more tokens would breach the slice cap (N5 hard cap). */
+export function wouldExceed(budget: Budget, add: number): boolean {
+  return budget.tokensSpent + add > budget.tokenCap;
+}

package/src/cli.ts

@@ -0,0 +1,126 @@
+/**
+ * STZ CLI (F17). `npx stz <command>`.
+ *
+ *   stz init [dir]        scaffold the .stz/ taxonomy + AGENTS.md
+ *   stz run  [dir]        run the bundled demo slice through the mock pipeline
+ *   stz help
+ */
+import { join } from "node:path";
+import { writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { scaffold, writeDoc, STZ_DIR, TIERS } from "./taxonomy.js";
+import { runSlice } from "./mock/orchestrator.js";
+import { runBridge } from "./bridge.js";
+import { MockModelLayer, defaultMockConfig } from "./mock/mock.js";
+import type { SliceManifest } from "./types.js";
+
+const AGENTS_MD = `# AGENTS.md — STZ table of contents
+
+This repo is managed by **slice-tournament-zoo (STZ)**. Progressive disclosure:
+load the tier summary you need, fetch full bodies only on named-anchor reference.
+
+| Tier | Purpose |
+|------|---------|
+| \`.stz/00-intent/\`    | elicitation transcript, questionnaire, done-predicates |
+| \`.stz/10-research/\`  | external/internal research, validated claims, spikes |
+| \`.stz/20-standards/\` | conventions (versioned), architecture decisions |
+| \`.stz/30-tests/\`     | test plan, rubric, **sealed held-out suite** (read-only) |
+| \`.stz/40-slices/\`    | per-slice manifest, plan, prototypes, tournament, spec-diff |
+| \`.stz/50-pressure/\`  | culled specimens' diffs + critiques (the pressure log) |
+| \`.stz/90-audit/\`     | journal, call ledger, cost, state.json |
+
+Vocabulary (the zoo metaphor): *specimens* = agents, *environment* = eval
+suite + conventions, *propagation* = winner's pattern carried forward,
+*selection pressure* = the culling mechanism, *pressure log* = the artifact.
+`;
+
+const DEMO_MANIFEST: SliceManifest = {
+  id: "slice-01",
+  name: "demo-slice",
+  contract: "export function run(input: Request): Result",
+  donePredicates: [
+    { id: "schema", expr: "returns_schema(Result)", kind: "schema" },
+    { id: "latency", expr: "p95_latency_ms < 200", kind: "metric" },
+  ],
+  traceTier: "minimal",
+  complexity: 2,
+  dependsOn: [],
+  judge: { votesPerPair: 8 },
+  summary: "Demo slice exercising the full STZ pipeline against the mock model layer.",
+};
+
+async function cmdInit(dir: string): Promise<void> {
+  const created = await scaffold(dir);
+  await writeFile(join(dir, "AGENTS.md"), AGENTS_MD, "utf8");
+  await writeDoc(dir, join("00-intent", "bootstrap.md"), {
+    frontmatter: { summary: "Bootstrap (slice-00): hand-written minimal kernel; STZ produces itself from slice-01 (R7/F18)." },
+    body: "# Bootstrap\n\nSlice-00 is this kernel. STZ dogfoods from slice-01 onward.\n",
+  });
+  console.log(`Scaffolded ${STZ_DIR}/ (${TIERS.length} tiers, ${created.length} created) + AGENTS.md at ${dir}`);
+}
+
+async function cmdRun(dir: string): Promise<void> {
+  if (!existsSync(join(dir, STZ_DIR))) await scaffold(dir);
+  const model = new MockModelLayer(defaultMockConfig());
+  const result = await runSlice({ root: dir, manifest: DEMO_MANIFEST, model, n: 4, log: console.log });
+  console.log("\n── result ──");
+  console.log(`winner: ${result.winner ? "specimen-" + result.winner : "none (halted)"}`);
+  console.log(`faithful (no planned-but-missing): ${result.faithful}`);
+  console.log(`rounds: ${result.rounds}`);
+  console.log(`artifacts: ${result.artifacts.length} under ${STZ_DIR}/`);
+}
+
+const LOGO = String.raw`
+  ██████╗  ████████╗ ███████╗
+ ██╔════╝  ╚══██╔══╝ ╚══███╔╝
+ ╚█████╗      ██║      ███╔╝
+  ╚═══██╗     ██║     ███╔╝
+ ██████╔╝     ██║    ███████╗
+ ╚═════╝      ╚═╝    ╚══════╝
+`;
+
+function cmdHelp(): void {
+  console.log(LOGO);
+  console.log(`slice-tournament-zoo: adversarial slice tournaments with a replayable audit trail
+
+Usage:
+  stz init [dir]       scaffold the .stz/ taxonomy + AGENTS.md (default: cwd)
+  stz run  [dir]       run the bundled demo slice through the mock pipeline
+  stz bridge <cmd>     deterministic orchestration bridge (used by the /stz:* commands)
+  stz help             show this help
+
+In Claude Code, install the plugin and drive the full pipeline with /stz:new,
+/stz:research, /stz:slice, /stz:pipeline, and friends. See the README.
+`);
+}
+
+async function main(): Promise<void> {
+  const [cmd, dirArg] = process.argv.slice(2);
+  const dir = dirArg ?? process.cwd();
+  switch (cmd) {
+    case "init":
+      await cmdInit(dir);
+      break;
+    case "run":
+      await cmdRun(dir);
+      break;
+    case "bridge":
+      // Deterministic orchestration bridge called by the /stz:run command
+      // between Task-subagent spawns. Everything after "bridge" is its argv.
+      await runBridge(process.argv.slice(3));
+      break;
+    case "help":
+    case undefined:
+      cmdHelp();
+      break;
+    default:
+      console.error(`unknown command: ${cmd}\n`);
+      cmdHelp();
+      process.exitCode = 1;
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exitCode = 1;
+});

package/src/cost-tracker.ts

@@ -0,0 +1,59 @@
+/**
+ * Cost / token tracker (N5 cost governance, N6 replay).
+ *
+ * Middleware around every Anthropic/OpenAI SDK call. Persists each call as a
+ * JSONL record under `90-audit/calls/` and aggregates spend into `state.json`.
+ * A replay command can reconstruct any decision from these records.
+ */
+import type { CallRecord, Phase } from "./types.js";
+
+export class CostTracker {
+  private seq = 0;
+  private records: CallRecord[] = [];
+
+  /** Record one call. Returns the persisted record (with assigned seq). */
+  record(input: Omit<CallRecord, "seq">): CallRecord {
+    const rec: CallRecord = { ...input, seq: this.seq++ };
+    this.records.push(rec);
+    return rec;
+  }
+
+  all(): CallRecord[] {
+    return [...this.records];
+  }
+
+  /** Total tokens (prompt + completion) across all recorded calls. */
+  totalTokens(): number {
+    return this.records.reduce(
+      (a, r) => a + r.promptTokens + r.completionTokens,
+      0,
+    );
+  }
+
+  tokensForPhase(phase: Phase): number {
+    return this.records
+      .filter((r) => r.phase === phase)
+      .reduce((a, r) => a + r.promptTokens + r.completionTokens, 0);
+  }
+
+  count(): number {
+    return this.records.length;
+  }
+
+  /** Serialize the ledger as JSONL for 90-audit/calls/*.jsonl. */
+  toJSONL(): string {
+    return this.records.map((r) => JSON.stringify(r)).join("\n");
+  }
+
+  /** Rebuild a tracker from persisted JSONL (replay/recovery). */
+  static fromJSONL(jsonl: string): CostTracker {
+    const t = new CostTracker();
+    const lines = jsonl.split("\n").filter((l) => l.trim().length > 0);
+    for (const line of lines) {
+      const rec = JSON.parse(line) as CallRecord;
+      t.records.push(rec);
+      t.seq = Math.max(t.seq, rec.seq + 1);
+    }
+    return t;
+  }
+}

package/src/escalation.ts

@@ -0,0 +1,89 @@
+/**
+ * Bounded failure escalation (F14, R1 mitigation).
+ *
+ *   no passers → 1 GRPO retry round (losers' pressure log as negative context)
+ *             → 1 replanning loop (failure analysis fed back into planning)
+ *             → halt with a structured failure report.
+ *
+ * Hard ceiling. This FSM is the single source of truth for "are we allowed to
+ * try again?" — the orchestrator must consult it and never loop on its own.
+ * The ceiling is exactly: at most 1 retry and at most 1 replan, ever.
+ */
+import type { EscalationStage } from "./types.js";
+
+export interface EscalationState {
+  stage: EscalationStage;
+  retryCount: number;
+  replanCount: number;
+}
+
+export const MAX_RETRIES = 1;
+export const MAX_REPLANS = 1;
+
+export function initialEscalation(): EscalationState {
+  return { stage: "normal", retryCount: 0, replanCount: 0 };
+}
+
+export type EscalationAction =
+  | { type: "retry"; note: string }
+  | { type: "replan"; note: string }
+  | { type: "halt"; note: string };
+
+/**
+ * Given the current escalation state after a tournament produced no gate-passers,
+ * decide the next action and return the advanced state. Pure function: same
+ * input → same output (N6).
+ */
+export function onNoPassers(s: EscalationState): {
+  next: EscalationState;
+  action: EscalationAction;
+} {
+  if (s.retryCount < MAX_RETRIES) {
+    return {
+      next: { stage: "grpo-retry", retryCount: s.retryCount + 1, replanCount: s.replanCount },
+      action: {
+        type: "retry",
+        note: "Re-running tournament with pressure log + K=4 surviving summaries as PDR refinement context.",
+      },
+    };
+  }
+  if (s.replanCount < MAX_REPLANS) {
+    return {
+      next: { stage: "replan", retryCount: s.retryCount, replanCount: s.replanCount + 1 },
+      action: {
+        type: "replan",
+        note: "Re-entering planning phase with failure analysis from the prior round.",
+      },
+    };
+  }
+  return {
+    next: { stage: "halted", retryCount: s.retryCount, replanCount: s.replanCount },
+    action: {
+      type: "halt",
+      note: "Retry and replan budgets exhausted. Emitting structured failure report.",
+    },
+  };
+}
+
+/** True once no further attempts are permitted. */
+export function isHalted(s: EscalationState): boolean {
+  return s.stage === "halted";
+}
+
+/**
+ * Drive the FSM to terminal state from a given start, recording the action
+ * sequence. Used to prove the ceiling holds (test) and to dry-run the path.
+ */
+export function escalationTrace(start = initialEscalation()): EscalationAction[] {
+  const actions: EscalationAction[] = [];
+  let s = start;
+  // Bound the loop independently as a belt-and-suspenders guard; the FSM must
+  // terminate in at most MAX_RETRIES + MAX_REPLANS + 1 steps.
+  for (let guard = 0; guard < MAX_RETRIES + MAX_REPLANS + 5; guard++) {
+    const { next, action } = onNoPassers(s);
+    actions.push(action);
+    s = next;
+    if (action.type === "halt") return actions;
+  }
+  throw new Error("escalation FSM failed to terminate — ceiling violated");
+}

package/src/eval-runner.ts

@@ -0,0 +1,220 @@
+/**
+ * Real eval runner (F7/F11) — un-stubs the metrics the bridge used to take on
+ * trust. Everything here is genuinely executed, with no test/coverage/mutation
+ * library dependency (N10 minimal toolchain):
+ *
+ *   testPassRate  — run the sealed harness against the specimen, parse its
+ *                   final JSON line {passed,total,passRate}.
+ *   coverage      — run under NODE_V8_COVERAGE and measure the fraction of the
+ *                   specimen file's bytes that V8 marked executed.
+ *   mutationScore — apply a small set of source mutators to the specimen,
+ *                   re-run the sealed harness against each mutant, and report
+ *                   the SURVIVAL rate (mutants the suite failed to kill). Lower
+ *                   is better; this is the eval signal that separates a thorough
+ *                   suite from a shallow one.
+ *
+ * The sealed harness contract: `node <sealed.mjs> <absolute-impl-path>` prints a
+ * final line `{"passed":n,"total":m,"passRate":r}` and exits 0 iff r===1. The
+ * runner resolves impl paths to absolute itself (the relative-path bug that bit
+ * the first live run must never reach a user).
+ */
+import { spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync, mkdtempSync, rmSync, readdirSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { resolve, join } from "node:path";
+
+export interface SealedResult {
+  passed: number;
+  total: number;
+  passRate: number;
+}
+
+const RUN_TIMEOUT_MS = 20_000;
+
+/** Run the sealed harness against one implementation file. */
+export function runSealed(sealedPath: string, implPath: string, covDir?: string): SealedResult {
+  const abs = resolve(implPath);
+  const env = covDir ? { ...process.env, NODE_V8_COVERAGE: covDir } : process.env;
+  const r = spawnSync("node", [resolve(sealedPath), abs], {
+    encoding: "utf8",
+    timeout: RUN_TIMEOUT_MS,
+    env,
+  });
+  const out = (r.stdout ?? "").trim().split("\n").filter(Boolean);
+  const last = out[out.length - 1] ?? "";
+  try {
+    const parsed = JSON.parse(last) as SealedResult;
+    if (typeof parsed.passRate === "number") return parsed;
+  } catch {
+    /* fall through to a zeroed result */
+  }
+  return { passed: 0, total: 1, passRate: 0 };
+}
+
+export type CrossStatus = "both-pass" | "divergent" | "both-fail";
+
+export interface CrossReferenceResult {
+  /** Sealed-suite result for the primary (test-author's) reference. */
+  a: SealedResult;
+  /** Sealed-suite result for the independently-authored cross-family reference. */
+  b: SealedResult;
+  /** Both independent references satisfy the suite — the wanted green state. */
+  bothPass: boolean;
+  /** Exactly one passes — the suite encodes a reference-specific assumption. */
+  divergent: boolean;
+  /** Neither passes — the suite is unsatisfiable for both (a gate failure). */
+  bothFail: boolean;
+  status: CrossStatus;
+}
+
+/**
+ * Cross-family reference check (F10-adjacent / R2 "cross-family quorum"). The
+ * single smoke-gate reference is authored by the same agent as the suite, so it
+ * shares the author's blind spots: a fragile invariant (e.g. identity keyed on
+ * mutable position) goes green against it and still ships. A SECOND,
+ * independently-authored reference — different model family or a human — that is
+ * run against the SAME sealed suite catches exactly that class: if the two
+ * references disagree, the suite encodes an assumption one author didn't share.
+ *
+ * This primitive only REPORTS the divergence; it deliberately does not verdict.
+ * A B-fails-A-passes split is ambiguous — either the suite over-fits A (the
+ * blind spot we want to surface) OR reference B is simply wrong — and aggregate
+ * pass counts cannot tell them apart. Classification is the orchestrator's job,
+ * consistent with the guide/sensor split in `sealed-suite.md`: divergence is a
+ * GUIDE-class signal for human adjudication (amend + strengthen authoring
+ * guidance, or discard a buggy B), not a sensor-style auto-rewrite trigger.
+ */
+export function crossReference(sealedPath: string, refAPath: string, refBPath: string): CrossReferenceResult {
+  const a = runSealed(sealedPath, refAPath);
+  const b = runSealed(sealedPath, refBPath);
+  const aPass = a.passRate === 1;
+  const bPass = b.passRate === 1;
+  const bothPass = aPass && bPass;
+  const bothFail = !aPass && !bPass;
+  const divergent = aPass !== bPass;
+  const status: CrossStatus = bothPass ? "both-pass" : divergent ? "divergent" : "both-fail";
+  return { a, b, bothPass, divergent, bothFail, status };
+}
+
+/** Real coverage: fraction of the impl file's bytes V8 recorded as executed. */
+export function measureCoverage(sealedPath: string, implPath: string): number {
+  const abs = resolve(implPath);
+  const covDir = mkdtempSync(join(tmpdir(), "stz-cov-"));
+  try {
+    runSealed(sealedPath, abs, covDir);
+    const fileLen = readFileSync(abs, "utf8").length;
+    if (fileLen === 0) return 0;
+    let covered = 0;
+    for (const f of readdirSync(covDir)) {
+      const data = JSON.parse(readFileSync(join(covDir, f), "utf8")) as {
+        result: { url: string; functions: { ranges: { startOffset: number; endOffset: number; count: number }[] }[] }[];
+      };
+      const entry = data.result.find((e) => e.url.includes(abs) || abs.includes(e.url.replace("file://", "")));
+      if (!entry) continue;
+      // Union of executed character ranges across all functions.
+      const marks = new Uint8Array(fileLen);
+      for (const fn of entry.functions) {
+        for (const rng of fn.ranges) {
+          if (rng.count > 0) {
+            for (let i = rng.startOffset; i < Math.min(rng.endOffset, fileLen); i++) marks[i] = 1;
+          }
+        }
+      }
+      covered = marks.reduce((a, b) => a + b, 0);
+      break;
+    }
+    return Math.min(1, covered / fileLen);
+  } finally {
+    rmSync(covDir, { recursive: true, force: true });
+  }
+}
+
+/** Source-level mutators. Each returns a mutated copy or null if inapplicable. */
+const MUTATORS: { name: string; apply: (s: string) => string | null }[] = [
+  { name: "lt→lte", apply: (s) => mutateFirst(s, /([^<>=])<([^<=])/, "$1<=$2") },
+  { name: "gt→gte", apply: (s) => mutateFirst(s, /([^<>=])>([^>=])/, "$1>=$2") },
+  { name: "lte→lt", apply: (s) => mutateFirst(s, /<=/, "<") },
+  { name: "gte→gt", apply: (s) => mutateFirst(s, />=/, ">") },
+  { name: "plus→minus", apply: (s) => mutateFirst(s, /([\w)])\s\+\s([\w(])/, "$1 - $2") },
+  { name: "min→max", apply: (s) => mutateFirst(s, /Math\.min/, "Math.max") },
+  { name: "max→min", apply: (s) => mutateFirst(s, /Math\.max/, "Math.min") },
+  { name: "swap-cmp-lo-hi", apply: (s) => mutateFirst(s, /\blo\b/, "hi") },
+];
+
+function mutateFirst(src: string, re: RegExp, repl: string): string | null {
+  const out = src.replace(re, repl);
+  return out === src ? null : out;
+}
+
+/** Remove block and line comments so mutators only touch executable code. */
+function stripComments(src: string): string {
+  return src
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/(^|[^:])\/\/.*$/gm, "$1");
+}
+
+/**
+ * Real mutation testing: produce mutants, re-run the sealed suite on each, and
+ * report SURVIVAL rate (1 = nothing killed, 0 = every mutant killed). Mutants
+ * that don't change the source or fail to load count as not-applicable and are
+ * skipped. Returns 1 (worst) when no mutant could be applied so a degenerate
+ * file is never rewarded.
+ */
+export function measureMutation(sealedPath: string, implPath: string): { mutationScore: number; mutants: number; survivors: number } {
+  const abs = resolve(implPath);
+  // Mutate executable code, not comments. A `Math.min` inside a doc comment
+  // would otherwise yield a behaviour-identical mutant that always "survives"
+  // and silently inflates the survival rate.
+  const src = stripComments(readFileSync(abs, "utf8"));
+  const dir = mkdtempSync(join(tmpdir(), "stz-mut-"));
+  let mutants = 0;
+  let survivors = 0;
+  try {
+    for (const m of MUTATORS) {
+      const mutated = m.apply(src);
+      if (mutated === null) continue;
+      mutants++;
+      const mutPath = join(dir, `mutant-${m.name}.mjs`);
+      writeFileSync(mutPath, mutated, "utf8");
+      const res = runSealed(sealedPath, mutPath);
+      // A surviving mutant still passes the suite (suite failed to catch it).
+      if (res.passRate === 1) survivors++;
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+  const mutationScore = mutants === 0 ? 1 : survivors / mutants;
+  return { mutationScore, mutants, survivors };
+}
+
+export interface FullEval {
+  testPassRate: number;
+  coverage: number;
+  mutationScore: number;
+  passed: number;
+  total: number;
+  mutants: number;
+  survivors: number;
+}
+
+/** Run all three real measurements for one specimen implementation. */
+export function fullEval(sealedPath: string, implPath: string): FullEval {
+  const sealed = runSealed(sealedPath, implPath);
+  const coverage = measureCoverage(sealedPath, implPath);
+  const mutation = measureMutation(sealedPath, implPath);
+  return {
+    testPassRate: sealed.passRate,
+    coverage,
+    mutationScore: mutation.mutationScore,
+    passed: sealed.passed,
+    total: sealed.total,
+    mutants: mutation.mutants,
+    survivors: mutation.survivors,
+  };
+}
+
+/** Write a metrics.json the bridge `record-eval` consumes. */
+export function writeMetrics(path: string, e: FullEval): void {
+  mkdirSync(join(path, ".."), { recursive: true });
+  writeFileSync(path, JSON.stringify({ testPassRate: e.testPassRate, coverage: e.coverage, mutationScore: e.mutationScore }, null, 2), "utf8");
+}

package/src/grpo.ts

@@ -0,0 +1,54 @@
+/**
+ * GRPO group-relative advantage (F8).
+ *
+ *   advantage_i = (reward_i − group_mean) / (group_std + ε)
+ *
+ * Adopted at the harness selection layer (DeepSeekMath / verl formulation).
+ * Used both to pick the winner and to weight which losers' diffs are the most
+ * informative forward signal for the pressure log (F9).
+ */
+import type { Advantage, SpecimenId } from "./types.js";
+
+export const GRPO_EPSILON = 1e-8;
+
+export function mean(xs: number[]): number {
+  if (xs.length === 0) return 0;
+  return xs.reduce((a, b) => a + b, 0) / xs.length;
+}
+
+/** Population standard deviation (divide by N, matching the GRPO group stat). */
+export function stddev(xs: number[], mu = mean(xs)): number {
+  if (xs.length === 0) return 0;
+  const variance = xs.reduce((a, x) => a + (x - mu) ** 2, 0) / xs.length;
+  return Math.sqrt(variance);
+}
+
+/**
+ * Compute group-relative advantages across a slice's specimen group.
+ * The ε guard means an all-equal-rewards group yields all-zero advantages
+ * (no division by zero), which is the correct "no signal" outcome.
+ */
+export function groupRelativeAdvantage(
+  rewards: { specimen: SpecimenId; reward: number }[],
+  epsilon = GRPO_EPSILON,
+): Advantage[] {
+  const values = rewards.map((r) => r.reward);
+  const mu = mean(values);
+  const sigma = stddev(values, mu);
+  return rewards.map(({ specimen, reward }) => ({
+    specimen,
+    reward,
+    advantage: (reward - mu) / (sigma + epsilon),
+  }));
+}
+
+/**
+ * Rank specimens whose diffs are most informative as negative exemplars (F9):
+ * the largest-magnitude advantages carry the most signal. Returns specimen ids
+ * sorted by |advantage| descending.
+ */
+export function mostInformative(advantages: Advantage[]): SpecimenId[] {
+  return [...advantages]
+    .sort((x, y) => Math.abs(y.advantage) - Math.abs(x.advantage))
+    .map((a) => a.specimen);
+}