slice-tournament-zoo 0.5.6

package/src/pressure.ts

@@ -0,0 +1,81 @@
+/**
+ * Selection pressure — the pressure log (F9, N12 vocabulary).
+ *
+ * Culled specimens' diffs + judge critiques + hack findings are persisted to
+ * `50-pressure/slice-NN/` as structured negative-exemplar context. If the
+ * failure-replan loop activates, the top-K=4 surviving summaries (PDR pattern)
+ * form the refinement context for the next round of specimens.
+ */
+import type { Advantage, HackFinding, SpecimenId } from "./types.js";
+import { mostInformative } from "./grpo.js";
+
+export const PDR_K = 4;
+
+export interface CulledSpecimen {
+  specimen: SpecimenId;
+  /** Why it was culled (gate-fail reason or judge rank). */
+  reason: string;
+  /** Unified diff of the specimen's attempt (negative exemplar). */
+  diff: string;
+  /** Judge critique prose, if it reached the judge. */
+  critique: string;
+  hackFindings: HackFinding[];
+}
+
+export interface PressureLog {
+  sliceId: string;
+  culled: CulledSpecimen[];
+}
+
+/** Render the pressure log as a markdown doc body for 50-pressure/slice-NN/. */
+export function renderPressureLog(log: PressureLog): string {
+  const parts: string[] = [`# Pressure log — ${log.sliceId}\n`];
+  for (const c of log.culled) {
+    parts.push(`## specimen-${c.specimen}`);
+    parts.push(`- **culled because:** ${c.reason}`);
+    if (c.hackFindings.length > 0) {
+      parts.push(
+        `- **hack findings:** ${c.hackFindings
+          .map((f) => `${f.pattern} @ ${f.location}`)
+          .join("; ")}`,
+      );
+    }
+    if (c.critique) parts.push(`- **judge critique:** ${c.critique}`);
+    parts.push("\n```diff\n" + c.diff.trim() + "\n```\n");
+  }
+  return parts.join("\n");
+}
+
+/**
+ * Build the PDR-style refinement context (F9): the top-K most informative
+ * surviving summaries to seed the next round of specimens. We rank culled
+ * specimens by |GRPO advantage| (most informative first) and take K.
+ */
+export function refinementContext(
+  log: PressureLog,
+  advantages: Advantage[],
+  k = PDR_K,
+): string {
+  const order = mostInformative(advantages);
+  const byName = new Map(log.culled.map((c) => [c.specimen, c]));
+  const picked: CulledSpecimen[] = [];
+  for (const s of order) {
+    const c = byName.get(s);
+    if (c) picked.push(c);
+    if (picked.length >= k) break;
+  }
+  // If fewer advantages than culled (e.g. all eliminated pre-judge), top up.
+  for (const c of log.culled) {
+    if (picked.length >= k) break;
+    if (!picked.includes(c)) picked.push(c);
+  }
+  return [
+    "# Refinement context (PDR top-K negative exemplars)",
+    ...picked.map(
+      (c, i) =>
+        `## ${i + 1}. specimen-${c.specimen} — avoid this failure mode\n${c.reason}\n${
+          c.hackFindings.map((f) => `- avoid: ${f.remediation}`).join("\n") || ""
+        }`,
+    ),
+  ].join("\n\n");
+}

package/src/project.ts

@@ -0,0 +1,335 @@
+/**
+ * Project-level driver state + DAG ordering (the multi-slice layer).
+ *
+ * STZ runs many slices through a dependency DAG. This module is the
+ * deterministic spine for that: the project manifest (declarative slice DAG),
+ * the project state (mutable phase + slice rollup), topological ordering, and
+ * the "next runnable slice" computation. It mirrors `state.ts` conventions.
+ *
+ * The authority rule (no drift): per-slice status is DERIVED from each slice's
+ * own `40-slices/<id>/state.json` via the existing per-slice helpers, never
+ * trusted from a project-level copy. So `project-status` writing nothing and
+ * re-deriving on every call IS the resume primitive.
+ */
+import { writeFile, readFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import {
+  PROJECT_PHASES,
+  STZ_ROLES,
+  type ProjectPhase,
+  type ProjectPhaseStatus,
+  type ProjectState,
+  type ProjectSliceEntry,
+  type SliceRunStatus,
+  type RunConfig,
+  type SlicingGranularity,
+  type MutationPolicy,
+  type ConventionStrictness,
+  type StzRole,
+} from "./types.js";
+import { STZ_DIR } from "./taxonomy.js";
+import { loadState, stateExists, isComplete } from "./state.js";
+import type { SliceState } from "./types.js";
+
+export function projectManifestPath(root: string): string {
+  return join(root, STZ_DIR, "00-intent", "project.json");
+}
+
+export function projectStatePath(root: string): string {
+  return join(root, STZ_DIR, "90-audit", "project-state.json");
+}
+
+/** Project phase → the `.stz/` tier its artifacts live under. */
+export const PROJECT_PHASE_TIER: Record<ProjectPhase, string> = {
+  elicitation: "00-intent",
+  research: "10-research",
+  "ground-truth": "10-research/internal",
+  standards: "20-standards",
+  "testing-conventions": "30-tests",
+  "slice-disaggregation": "40-slices",
+};
+
+export function freshProjectState(projectId: string): ProjectState {
+  const phaseStatus = Object.fromEntries(
+    PROJECT_PHASES.map((p) => [p, "pending" as ProjectPhaseStatus]),
+  ) as Record<ProjectPhase, ProjectPhaseStatus>;
+  return {
+    schemaVersion: 1,
+    projectId,
+    phaseStatus,
+    sliceStatus: {},
+    events: [],
+  };
+}
+
+export function appendProjectEvent(
+  state: ProjectState,
+  phase: ProjectPhase | "lifecycle" | "slice",
+  kind: string,
+  detail: string,
+): ProjectState {
+  state.events.push({ seq: state.events.length, phase, kind, detail });
+  return state;
+}
+
+export async function saveProjectState(root: string, state: ProjectState): Promise<void> {
+  const p = projectStatePath(root);
+  await mkdir(join(p, ".."), { recursive: true });
+  await writeFile(p, JSON.stringify(state, null, 2) + "\n", "utf8");
+}
+
+export async function loadProjectState(root: string): Promise<ProjectState> {
+  return JSON.parse(await readFile(projectStatePath(root), "utf8")) as ProjectState;
+}
+
+export function projectStateExists(root: string): boolean {
+  return existsSync(projectStatePath(root));
+}
+
+// ── topological ordering ────────────────────────────────────────────────────
+
+export type TopoResult =
+  | { ok: true; order: string[] }
+  | { ok: false; error: "cycle"; cycle: string[] }
+  | { ok: false; error: "dangling"; from: string; missing: string };
+
+/**
+ * Kahn's algorithm over the slice DAG. The ready frontier is sorted ascending
+ * by id at every step so the order is fully deterministic (N6). Detects
+ * dangling dependencies (a depends-on id not in the set) and cycles.
+ */
+export function topoOrder(slices: ProjectSliceEntry[]): TopoResult {
+  const ids = new Set(slices.map((s) => s.id));
+  for (const s of slices) {
+    for (const dep of s.dependsOn) {
+      if (!ids.has(dep)) return { ok: false, error: "dangling", from: s.id, missing: dep };
+    }
+  }
+  const indegree = new Map<string, number>();
+  const dependents = new Map<string, string[]>();
+  for (const s of slices) {
+    indegree.set(s.id, s.dependsOn.length);
+    for (const dep of s.dependsOn) {
+      const arr = dependents.get(dep) ?? [];
+      arr.push(s.id);
+      dependents.set(dep, arr);
+    }
+  }
+  const order: string[] = [];
+  let ready = [...indegree.entries()].filter(([, d]) => d === 0).map(([id]) => id).sort();
+  while (ready.length > 0) {
+    const id = ready.shift()!;
+    order.push(id);
+    for (const dependent of dependents.get(id) ?? []) {
+      const d = (indegree.get(dependent) ?? 0) - 1;
+      indegree.set(dependent, d);
+      if (d === 0) {
+        ready.push(dependent);
+        ready.sort();
+      }
+    }
+  }
+  if (order.length < slices.length) {
+    const cycle = slices.map((s) => s.id).filter((id) => !order.includes(id));
+    return { ok: false, error: "cycle", cycle };
+  }
+  return { ok: true, order };
+}
+
+// ── status derivation (the no-drift rule) ───────────────────────────────────
+
+/** Derive a slice's rollup status from its own per-slice state.json. */
+export async function deriveSliceStatus(root: string, sliceId: string): Promise<SliceRunStatus> {
+  if (!stateExists(root, sliceId)) return "pending";
+  let state: SliceState;
+  try {
+    state = await loadState(root, sliceId);
+  } catch {
+    return "pending";
+  }
+  if (state.escalation === "halted") return "halted";
+  if (isComplete(state)) return "done";
+  // "running" means the tournament half is actually in progress — not merely
+  // that the project-level early phases were pre-seeded done. So: any phase
+  // explicitly "running", OR any tournament-half phase already "done".
+  const anyRunning = Object.values(state.phaseStatus).some((s) => s === "running");
+  const tournamentHalf = ["test-authoring", "planning", "tournament", "judgment"] as const;
+  const tournamentStarted = tournamentHalf.some((p) => state.phaseStatus[p] === "done");
+  if (anyRunning || tournamentStarted) return "running";
+  return "pending";
+}
+
+export interface NextRunnable {
+  order: string[];
+  frontier: string[];
+  next: string | null;
+}
+
+/**
+ * Compute the runnable frontier and the single deterministic next slice.
+ * The frontier is every slice whose dependencies are all `done` and which is
+ * not itself `done`/`halted`/`running`. `next` is the id-sorted first of the
+ * frontier (a single pick). Returns empty/null on a non-ok topo order.
+ */
+export async function nextRunnable(
+  slices: ProjectSliceEntry[],
+  statusOf: (id: string) => Promise<SliceRunStatus>,
+): Promise<NextRunnable & { topo: TopoResult }> {
+  const topo = topoOrder(slices);
+  if (!topo.ok) return { order: [], frontier: [], next: null, topo };
+  const status = new Map<string, SliceRunStatus>();
+  for (const id of topo.order) status.set(id, await statusOf(id));
+  const byId = new Map(slices.map((s) => [s.id, s]));
+  const frontier = topo.order.filter((id) => {
+    const st = status.get(id);
+    if (st === "done" || st === "halted" || st === "running") return false;
+    const deps = byId.get(id)!.dependsOn;
+    return deps.every((d) => status.get(d) === "done");
+  });
+  return { order: topo.order, frontier, next: frontier[0] ?? null, topo };
+}
+
+// ── run configuration (0.3.0) ───────────────────────────────────────────────
+
+export function runConfigPath(root: string): string {
+  return join(root, STZ_DIR, "00-intent", "run-config.json");
+}
+
+export function runConfigExists(root: string): boolean {
+  return existsSync(runConfigPath(root));
+}
+
+/**
+ * Default run config — a balanced starting point used when the user never set
+ * one (every downstream consumer falls back to this, so the pipeline always has
+ * a complete config). Model values are spawn aliases so they drop straight into
+ * an Agent `model` override: a cheap model for high-volume research, the strong
+ * model for judging where quality matters most.
+ */
+export const DEFAULT_MODELS: Record<StzRole, string> = {
+  planning: "sonnet",
+  research: "haiku",
+  execution: "sonnet",
+  testing: "sonnet",
+  validation: "sonnet",
+  judging: "opus",
+};
+
+export function defaultRunConfig(): RunConfig {
+  return {
+    schemaVersion: 1,
+    granularity: "balanced",
+    fanout: 4,
+    models: { ...DEFAULT_MODELS },
+    strictness: {
+      coverageTarget: 0.9,
+      mutationPolicy: "standard",
+      conventions: "standard",
+    },
+    // Human-in-the-loop by default — a fully autonomous run is opt-in (0.4.0).
+    darkFactory: false,
+  };
+}
+
+const GRANULARITIES: readonly SlicingGranularity[] = ["coarse", "balanced", "fine"];
+const MUTATION_POLICIES: readonly MutationPolicy[] = ["off", "lenient", "standard", "strict"];
+const CONVENTION_STRICTNESS: readonly ConventionStrictness[] = ["relaxed", "standard", "strict"];
+
+/** Lower bound on specimen fan-out — a tournament needs at least a pair. */
+export const FANOUT_MIN = 2;
+/** Upper bound on specimen fan-out — the published RTV+PDR optimum for the
+ *  cloud/CI profile (N3/F6). Workstation runs typically use far fewer. */
+export const FANOUT_MAX = 16;
+
+/**
+ * Merge a partial config over the defaults and validate. Enum fields are
+ * rejected if present-but-invalid (a typo must not silently fall back); fanout
+ * is clamped to [FANOUT_MIN, FANOUT_MAX] and coverageTarget to [0, 1]. Model
+ * values stay free-form (the get-shit-done "Other" pattern) — any string passes.
+ */
+export function normalizeRunConfig(partial: Partial<RunConfig> | undefined): RunConfig {
+  const base = defaultRunConfig();
+  const p = partial ?? {};
+
+  if (p.granularity !== undefined && !GRANULARITIES.includes(p.granularity)) {
+    throw new Error(`invalid granularity: ${p.granularity} (expected ${GRANULARITIES.join("|")})`);
+  }
+  const granularity = p.granularity ?? base.granularity;
+
+  let fanout = base.fanout;
+  if (p.fanout !== undefined) {
+    const n = Math.round(Number(p.fanout));
+    if (!Number.isFinite(n)) throw new Error(`invalid fanout: ${p.fanout}`);
+    fanout = Math.max(FANOUT_MIN, Math.min(FANOUT_MAX, n));
+  }
+
+  const models: Record<StzRole, string> = { ...base.models };
+  if (p.models) {
+    for (const role of STZ_ROLES) {
+      const v = p.models[role];
+      if (v !== undefined && String(v).trim() !== "") models[role] = String(v).trim();
+    }
+  }
+
+  const s: Partial<RunConfig["strictness"]> = p.strictness ?? {};
+  if (s.mutationPolicy !== undefined && !MUTATION_POLICIES.includes(s.mutationPolicy)) {
+    throw new Error(`invalid mutationPolicy: ${s.mutationPolicy} (expected ${MUTATION_POLICIES.join("|")})`);
+  }
+  if (s.conventions !== undefined && !CONVENTION_STRICTNESS.includes(s.conventions)) {
+    throw new Error(`invalid conventions strictness: ${s.conventions} (expected ${CONVENTION_STRICTNESS.join("|")})`);
+  }
+  let coverageTarget = base.strictness.coverageTarget;
+  if (s.coverageTarget !== undefined) {
+    const c = Number(s.coverageTarget);
+    if (!Number.isFinite(c)) throw new Error(`invalid coverageTarget: ${s.coverageTarget}`);
+    coverageTarget = Math.max(0, Math.min(1, c));
+  }
+
+  // darkFactory is a plain boolean flag; accept the JSON literal or a stringy
+  // "true"/"false" (it can arrive from a CLI arg), default to the base value.
+  let darkFactory = base.darkFactory;
+  if (p.darkFactory !== undefined) {
+    darkFactory = p.darkFactory === true || String(p.darkFactory).trim().toLowerCase() === "true";
+  }
+
+  return {
+    schemaVersion: 1,
+    granularity,
+    fanout,
+    models,
+    strictness: {
+      coverageTarget,
+      mutationPolicy: s.mutationPolicy ?? base.strictness.mutationPolicy,
+      conventions: s.conventions ?? base.strictness.conventions,
+    },
+    darkFactory,
+  };
+}
+
+export async function saveRunConfig(root: string, config: RunConfig): Promise<void> {
+  const p = runConfigPath(root);
+  await mkdir(join(p, ".."), { recursive: true });
+  await writeFile(p, JSON.stringify(config, null, 2) + "\n", "utf8");
+}
+
+/** Load the persisted run config, or the default if none was ever set. */
+export async function loadRunConfig(root: string): Promise<RunConfig> {
+  if (!runConfigExists(root)) return defaultRunConfig();
+  const raw = JSON.parse(await readFile(runConfigPath(root), "utf8")) as Partial<RunConfig>;
+  return normalizeRunConfig(raw);
+}
+
+/**
+ * Flip dark-factory mode in place (0.4.0) without disturbing any other field.
+ * This is a LOAD-MODIFY-SAVE on the existing config — deliberately NOT routed
+ * through `normalizeRunConfig(partial)`, which merges over the *defaults* and
+ * would silently reset fanout/models/strictness mid-run. Returns the resolved
+ * config so the caller can echo it back.
+ */
+export async function setDarkFactory(root: string, enabled: boolean): Promise<RunConfig> {
+  const current = await loadRunConfig(root);
+  const next: RunConfig = { ...current, darkFactory: enabled };
+  await saveRunConfig(root, next);
+  return next;
+}

package/src/seal.ts

@@ -0,0 +1,182 @@
+/**
+ * Sealed held-out suite integrity (L1/F10).
+ *
+ * The held-out suite (and the test-author's reference implementation that proves
+ * it is satisfiable) is frozen BEFORE the tournament and must not change while
+ * specimens compete — otherwise the grader could be tuned to favour one. This
+ * module is the deterministic record of that freeze:
+ *
+ *   - `seal`        — hash every file under `30-tests/held-out/` into SEAL.json.
+ *   - `verifySeal`  — re-hash and report any drift (the gate before judging).
+ *   - `amendSeal`   — the ONLY sanctioned way to change a sealed file: records
+ *                     per-file from→to hashes + a reason into the manifest.
+ *
+ * The manifest is timestamp-free (N6 replayability); amendment append-order is
+ * the audit sequence. SEAL.json lives inside the directory it hashes and is
+ * excluded from its own manifest. File keys are POSIX-relative and sorted, so
+ * the manifest is byte-stable across runs and machines.
+ *
+ * Language-specific compile/run (the smoke gate that proves the suite is green
+ * against the reference before sealing) is the orchestrator's job, not this
+ * module's — the bridge owns only the deterministic hashing/verify/amend.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { stzPath } from "./taxonomy.js";
+
+const HELD_OUT_REL = join("30-tests", "held-out");
+export const SEAL_NAME = "SEAL.json";
+
+export interface SealAmendment {
+  reason: string;
+  changed: { file: string; from: string | null; to: string | null }[];
+}
+
+export interface SealManifest {
+  schemaVersion: 1;
+  /** POSIX-relative path → sha256 of the file's bytes, for every held-out file. */
+  files: Record<string, string>;
+  /** Audit log of sanctioned post-freeze changes, in application order. */
+  amendments: SealAmendment[];
+}
+
+export function heldOutDir(root: string): string {
+  return stzPath(root, HELD_OUT_REL);
+}
+export function sealPath(root: string): string {
+  return join(heldOutDir(root), SEAL_NAME);
+}
+
+const toPosix = (p: string): string => p.split(sep).join("/");
+const fromPosix = (p: string): string => p.split("/").join(sep);
+const sha256 = (buf: Buffer): string => createHash("sha256").update(buf).digest("hex");
+
+/** Every file under held-out (recursive), POSIX-relative, sorted, sans SEAL.json. */
+export function heldOutFiles(root: string): string[] {
+  const base = heldOutDir(root);
+  if (!existsSync(base)) return [];
+  const out: string[] = [];
+  const walk = (dir: string) => {
+    const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) =>
+      a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+    );
+    for (const ent of entries) {
+      const abs = join(dir, ent.name);
+      if (ent.isDirectory()) walk(abs);
+      else {
+        const rel = toPosix(relative(base, abs));
+        if (rel !== SEAL_NAME) out.push(rel);
+      }
+    }
+  };
+  walk(base);
+  return out.sort();
+}
+
+/** Current on-disk hashes, keyed by POSIX-relative path (sorted insertion). */
+export function computeHashes(root: string): Record<string, string> {
+  const base = heldOutDir(root);
+  const files: Record<string, string> = {};
+  for (const rel of heldOutFiles(root)) {
+    files[rel] = sha256(readFileSync(join(base, fromPosix(rel))));
+  }
+  return files;
+}
+
+export function readSeal(root: string): SealManifest | null {
+  if (!existsSync(sealPath(root))) return null;
+  return JSON.parse(readFileSync(sealPath(root), "utf8")) as SealManifest;
+}
+
+export async function writeSeal(root: string, manifest: SealManifest): Promise<void> {
+  await writeFile(sealPath(root), JSON.stringify(manifest, null, 2) + "\n", "utf8");
+}
+
+export type SealResult = {
+  sealed: boolean;
+  added: string[];
+  /** Already-sealed files whose bytes changed — NOT re-blessed; use amend. */
+  drifted: string[];
+  removed: string[];
+  total: number;
+};
+
+/**
+ * Freeze the held-out suite. On first run, hashes everything. On a later run
+ * (e.g. a new slice's suite was added) it ADDS the new files' hashes but
+ * refuses to silently re-bless an already-sealed file whose bytes changed —
+ * that is `amendSeal`'s job. Returns `sealed:false` when such drift blocks it.
+ */
+export async function seal(root: string): Promise<SealResult> {
+  const current = computeHashes(root);
+  const prior = readSeal(root);
+  if (!prior) {
+    await writeSeal(root, { schemaVersion: 1, files: current, amendments: [] });
+    return { sealed: true, added: Object.keys(current), drifted: [], removed: [], total: Object.keys(current).length };
+  }
+  const added: string[] = [];
+  const drifted: string[] = [];
+  for (const [f, h] of Object.entries(current)) {
+    if (!(f in prior.files)) added.push(f);
+    else if (prior.files[f] !== h) drifted.push(f);
+  }
+  const removed = Object.keys(prior.files).filter((f) => !(f in current));
+  if (drifted.length || removed.length) {
+    // A sealed file changed/vanished — refuse to launder it through `seal`.
+    return { sealed: false, added, drifted, removed, total: Object.keys(prior.files).length };
+  }
+  const files = { ...prior.files };
+  for (const f of added) files[f] = current[f]!;
+  await writeSeal(root, { schemaVersion: 1, files, amendments: prior.amendments });
+  return { sealed: true, added, drifted: [], removed: [], total: Object.keys(files).length };
+}
+
+export type DriftEntry = { file: string; status: "modified" | "added" | "removed" };
+export type VerifyResult = { sealed: boolean; ok: boolean; drift: DriftEntry[] };
+
+/** Re-hash the held-out dir against SEAL.json. `ok:false` on any drift. */
+export function verifySeal(root: string): VerifyResult {
+  const prior = readSeal(root);
+  if (!prior) return { sealed: false, ok: false, drift: [] };
+  const current = computeHashes(root);
+  const drift: DriftEntry[] = [];
+  for (const [f, h] of Object.entries(current)) {
+    if (!(f in prior.files)) drift.push({ file: f, status: "added" });
+    else if (prior.files[f] !== h) drift.push({ file: f, status: "modified" });
+  }
+  for (const f of Object.keys(prior.files)) {
+    if (!(f in current)) drift.push({ file: f, status: "removed" });
+  }
+  drift.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+  return { sealed: true, ok: drift.length === 0, drift };
+}
+
+/**
+ * The sanctioned post-freeze change: re-hash, record per-file from→to (null on
+ * add/remove) plus the reason into the manifest's amendment log, and re-freeze
+ * to the new hashes. After this, `verifySeal` passes again — so a silent edit
+ * (one that skipped amend) is exactly what `verifySeal` is left to catch.
+ */
+export async function amendSeal(root: string, reason: string): Promise<{ amended: boolean; changed: SealAmendment["changed"] }> {
+  const prior = readSeal(root);
+  if (!prior) return { amended: false, changed: [] };
+  const current = computeHashes(root);
+  const changed: SealAmendment["changed"] = [];
+  for (const [f, h] of Object.entries(current)) {
+    const from = prior.files[f] ?? null;
+    if (from !== h) changed.push({ file: f, from, to: h });
+  }
+  for (const f of Object.keys(prior.files)) {
+    if (!(f in current)) changed.push({ file: f, from: prior.files[f]!, to: null });
+  }
+  if (changed.length === 0) return { amended: false, changed: [] };
+  changed.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+  await writeSeal(root, {
+    schemaVersion: 1,
+    files: current,
+    amendments: [...prior.amendments, { reason, changed }],
+  });
+  return { amended: true, changed };
+}