slice-tournament-zoo 0.5.7 → 0.7.1

package/README.md

@@ -28,6 +28,7 @@
 
 - [Requirements](#requirements)
 - [Install](#install)
+- [Updating](#updating)
 - [Use](#use)
 - [Example commands and workflows](#example-commands-and-workflows)
 - [Uninstall](#uninstall)
@@ -43,6 +44,16 @@
 - No database, no vector service, no API keys beyond what Claude Code already
   uses for its subagents.
 
+> **Token cost.** A tournament is deliberately redundant: every slice runs *N*
+> specimens in parallel, a judge casts multiple votes per pair, and a multi-slice
+> GRPO project repeats that across the DAG. That buys selection pressure and an
+> auditable trail — but it is **token-intensive**, far more than a single-agent
+> run. Budget accordingly (tune `n`, `votesPerPair`, and `traceTier` down for
+> cheaper runs), and consider installing token-efficiency companion plugins
+> alongside STZ: **Caveman** (compressed responses), **RTK** (token-optimized CLI
+> proxy), **Headroom**, and **CodeSight**. They reduce the per-call overhead the
+> tournament multiplies.
+
 ## Install
 
 STZ installs two ways: as a global CLI via **npm**, or as a **Claude Code
@@ -89,6 +100,44 @@ needed (Node.js 20+ is the only requirement; the bundled copy fetches `tsx` via
 > Developing STZ itself, or running the engine without Claude Code? See
 > [`docs/development/local-and-testing.md`](https://github.com/dr-robert-li/slice-tournament-zoo/blob/main/docs/development/local-and-testing.md).
 
+## Updating
+
+STZ ships through two channels that update independently — the **npm CLI** and
+the **Claude Code plugin**. Keep them on the same version so the `/stz:*`
+commands and the `stz` you call by hand agree.
+
+```bash
+stz --version          # what you have
+stz update             # check npm for a newer release + plugin/CLI drift
+stz update --check     # same, as JSON (CI-friendly; exits non-zero if action needed)
+```
+
+`stz update` does not self-install (it never runs `npm`/`/plugin` behind your
+back); it checks the npm registry, compares against your installed version, and
+prints the exact commands to run. When a plugin manifest is reachable — i.e.
+`CLAUDE_PLUGIN_ROOT` is set (as in a Claude Code session) or you run from a repo
+checkout — it also reports **drift** between the CLI and the plugin's bundled
+engine:
+
+```bash
+npm i -g slice-tournament-zoo@latest      # update the CLI
+/plugin update stz                        # update the plugin (inside Claude Code)
+```
+
+After updating the engine, bring an **existing project's `.stz/` tree** up to the
+current taxonomy schema. Engine updates never touch a scaffolded project on their
+own, so a tree created by an older STZ can fall behind:
+
+```bash
+stz migrate            # additive + backed-up; no-op if already current
+```
+
+`migrate` is safe by construction: it only *creates* missing tiers (never
+deletes or renames), and copies the prior tree to a `.stz.bak-schema<N>/` sibling
+before any change. Each `.stz/` carries a `manifest.json` stamped with the STZ
+version and schema version so drift is detectable. Pass `--no-backup` to skip the
+copy.
+
 ## Use
 
 ### Scaffold a project
@@ -350,7 +399,8 @@ For contributors and anyone going past day-to-day operation:
 - **Sealed-suite integrity** — the guide-vs-sensor contract behind the frozen
   held-out suite: [`docs/development/sealed-suite.md`](https://github.com/dr-robert-li/slice-tournament-zoo/blob/main/docs/development/sealed-suite.md).
 - **Requirement-to-test mapping** — [`docs/TESTPLAN.md`](https://github.com/dr-robert-li/slice-tournament-zoo/blob/main/docs/TESTPLAN.md).
-- **What is real versus deferred** — [`docs/AS-BUILT.md`](https://github.com/dr-robert-li/slice-tournament-zoo/blob/main/docs/AS-BUILT.md).
+- **Roadmap — what is built, deferred, and planned next** —
+  [`docs/ROADMAP.md`](https://github.com/dr-robert-li/slice-tournament-zoo/blob/main/docs/ROADMAP.md).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slice-tournament-zoo",
-  "version": "0.5.7",
+  "version": "0.7.1",
   "description": "STZ: a contract-bounded slice pipeline that implements each slice adversarially via an N-specimen tournament with frozen sealed tests, GRPO-style selection, layered anti-reward-hacking, and a replayable markdown audit trail.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/dr-robert-li/slice-tournament-zoo#readme",

package/src/README.md

@@ -14,6 +14,6 @@ the production path — see [`mock/`](https://github.com/dr-robert-li/slice-tour
 ## Further reading
 
 - The requirement-to-test mapping is in [`docs/TESTPLAN.md`](https://github.com/dr-robert-li/slice-tournament-zoo/blob/main/docs/TESTPLAN.md).
-- What is real versus deferred is in [`docs/AS-BUILT.md`](https://github.com/dr-robert-li/slice-tournament-zoo/blob/main/docs/AS-BUILT.md).
+- What is built, deferred, and planned next is in [`docs/ROADMAP.md`](https://github.com/dr-robert-li/slice-tournament-zoo/blob/main/docs/ROADMAP.md).
 - Running the engine locally / in CI: [`docs/development/local-and-testing.md`](https://github.com/dr-robert-li/slice-tournament-zoo/blob/main/docs/development/local-and-testing.md).
 - The deterministic bridge CLI: [`docs/development/bridge-cli.md`](https://github.com/dr-robert-li/slice-tournament-zoo/blob/main/docs/development/bridge-cli.md).

package/src/bridge.ts

@@ -33,6 +33,7 @@ import type {
   ProjectPhase,
   ProjectSliceEntry,
   RunConfig,
+  SpecimenId,
 } from "./types.js";
 import { PROJECT_PHASES } from "./types.js";
 import { scaffold, writeDoc, readDoc, stzPath } from "./taxonomy.js";
@@ -56,6 +57,8 @@ import {
   defaultRunConfig,
 } from "./project.js";
 import { detectHacks } from "./hack-detector.js";
+import { STZ_VERSION, SCHEMA_VERSION, PACKAGE_NAME } from "./version.js";
+import { onNoPassers, type EscalationState } from "./escalation.js";
 import { evalGate, select, pairings } from "./selection.js";
 import { diffSpecs, renderSpecDiff, isFaithful, unmatchedIntentIds, mismatchedAsBuiltIds, type Spec } from "./specdiff.js";
 import { seal, verifySeal, amendSeal, heldOutFiles } from "./seal.js";
@@ -95,6 +98,16 @@ function print(obj: unknown): void {
   process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
 }
 
+/**
+ * Report the bundled engine's identity (F19). The `/stz:*` commands and a
+ * SessionStart hook call this to compare the plugin's engine against a global
+ * `stz` CLI and surface channel drift deterministically (no version parsing
+ * from prose).
+ */
+function versionCmd(): void {
+  print({ version: STZ_VERSION, schemaVersion: SCHEMA_VERSION, packageName: PACKAGE_NAME });
+}
+
 // ── paths within a slice ────────────────────────────────────────────────────
 
 const sliceRel = (id: string) => join("40-slices", id);
@@ -236,10 +249,136 @@ function gate(args: Record<string, string>): void {
   const { root, slice } = args as { root: string; slice: string };
   const evals = loadEvals(root, slice);
   const { passers, eliminated } = evalGate(evals);
-  // Emit the pairing schedule the command must drive with judge agents.
+  // Emit the pairing schedule the command must drive with judge agents. `gate`
+  // is a pure read — it never advances escalation. When `passers` is empty the
+  // command calls `escalate` (below), which owns the state transition; keeping
+  // them separate means a re-run of `gate` can't double-advance the FSM.
   print({ passers, eliminated, pairings: pairings(passers) });
 }
 
+/** Build the pressure-log entries: every specimen that is not the winner is a
+ *  negative exemplar (F9). `winner` is null for a no-passers round (all culled). */
+function culledFromEvals(
+  root: string,
+  slice: string,
+  evals: EvalResult[],
+  winner: SpecimenId | null,
+): CulledSpecimen[] {
+  return evals
+    .filter((e) => e.specimen !== winner)
+    .map((e) => ({
+      specimen: e.specimen,
+      reason: e.hackFindings.length
+        ? `hack: ${e.hackFindings.map((f) => f.pattern).join(",")}`
+        : `gate testPassRate=${e.testPassRate.toFixed(2)}`,
+      diff: Object.entries(readSpecimenFiles(root, slice, e.specimen))
+        .map(([p, c]) => `+++ ${p}\n${c}`)
+        .join("\n"),
+      critique: "",
+      hackFindings: e.hackFindings,
+    }));
+}
+
+/**
+ * Bounded cross-round escalation (F14), driven from the command-level `/stz:run`
+ * loop. Call this ONCE after a gate that yielded zero passers. It is the single
+ * deterministic owner of "are we allowed another round?": it advances the
+ * escalation FSM over `state.json`, persists the new counts, and on retry/replan
+ * writes the PDR refinement context the next round's specimens consume — exactly
+ * the path the mock orchestrator drives internally, now exposed to the real
+ * command so it is not the LLM deciding when to stop.
+ *
+ * The sealed suite is NOT touched here: retry/replan re-enter the tournament with
+ * the SAME frozen suite (the command re-runs `seal-verify` each round). Re-using
+ * the FSM's hard ceiling (≤1 retry, ≤1 replan) means even a stray double-call is
+ * fail-safe — it halts early, it never loops.
+ */
+async function escalateCmd(args: Record<string, string>): Promise<void> {
+  const { root, slice } = args as { root: string; slice: string };
+  const evals = loadEvals(root, slice);
+  let state = await loadState(root, slice);
+
+  const cur: EscalationState = {
+    stage: state.escalation,
+    retryCount: state.retryCount,
+    replanCount: state.replanCount,
+  };
+  // The round that just failed (1-based): rounds already consumed + this one.
+  const failedRound = cur.retryCount + cur.replanCount + 1;
+  const { next, action } = onNoPassers(cur);
+  state.escalation = next.stage;
+  state.retryCount = next.retryCount;
+  state.replanCount = next.replanCount;
+  state = appendEvent(state, "judgment", `escalation-${action.type}`, action.note);
+
+  // The whole field is culled this round (no winner). Persist the pressure log so
+  // the negative exemplars are auditable regardless of what comes next (F9).
+  const culled = culledFromEvals(root, slice, evals, null);
+  await writeDoc(root, join("50-pressure", slice, "pressure.md"), {
+    frontmatter: { summary: `Pressure log ${slice}: round ${failedRound}, ${culled.length} culled (no passers).` },
+    body: renderPressureLog({ sliceId: slice, culled }),
+  });
+
+  if (action.type === "halt") {
+    const report =
+      `# Failure report — ${slice}\n\n` +
+      `No specimen passed the sealed-suite gate after ${failedRound} round(s) ` +
+      `(${next.retryCount} retry, ${next.replanCount} replan). The bounded-escalation ` +
+      `budget (≤1 retry, ≤1 replan) is exhausted; halting per F14.\n\n` +
+      `## Per-specimen gate outcomes (final round)\n` +
+      evals
+        .map((e) => {
+          const why = e.hackFindings.length
+            ? `disqualified — hack: ${e.hackFindings.map((f) => f.pattern).join(", ")}`
+            : `gate fail — testPassRate=${e.testPassRate.toFixed(2)}, coverage=${e.coverage.toFixed(2)}, mutation=${e.mutationScore.toFixed(2)}`;
+          return `- specimen-${e.specimen}: ${why}`;
+        })
+        .join("\n") +
+      "\n";
+    state.failureReport = report;
+    state = setPhaseStatus(state, "judgment", "failed");
+    await writeDoc(root, join(sliceRel(slice), "failure-report.md"), {
+      frontmatter: { summary: `Halt: no passers after ${failedRound} round(s).` },
+      body: report,
+    });
+    await saveState(root, state);
+    print({
+      action: "halt",
+      note: action.note,
+      round: failedRound,
+      escalation: state.escalation,
+      retryCount: state.retryCount,
+      replanCount: state.replanCount,
+      failureReportPath: stzPath(root, join(sliceRel(slice), "failure-report.md")),
+    });
+    return;
+  }
+
+  // retry or replan → build the PDR refinement context (F9) from this round's
+  // group-relative advantages (no votes: GRPO over the eval rewards alone), the
+  // same computation the mock uses (orchestrator select(evals, [])).
+  const advantages = select(evals, []).judgment.advantages;
+  await writeDoc(root, join("50-pressure", slice, "refinement.md"), {
+    frontmatter: { summary: `PDR refinement for ${slice} after round ${failedRound} (${action.type}).` },
+    body: refinementContext({ sliceId: slice, culled }, advantages),
+  });
+  if (action.type === "replan") {
+    // Re-enter planning: the command rewrites intent.json before re-spawning.
+    state = setPhaseStatus(state, "planning", "running");
+  }
+  await saveState(root, state);
+  print({
+    action: action.type,
+    note: action.note,
+    round: failedRound,
+    nextRound: failedRound + 1,
+    escalation: state.escalation,
+    retryCount: state.retryCount,
+    replanCount: state.replanCount,
+    refinementPath: stzPath(root, join("50-pressure", slice, "refinement.md")),
+  });
+}
+
 function recordVotes(args: Record<string, string>): void {
   const { root, slice } = args as { root: string; slice: string };
   const votes = readJSON<PairwiseVote[]>(args.votes!);
@@ -282,19 +421,7 @@ async function finalize(args: Record<string, string>): Promise<void> {
     : { ranking: [], winner: null, advantages: [], votes: [] };
 
   // Pressure log: every non-winning specimen is a negative exemplar (F9).
-  const culled: CulledSpecimen[] = evals
-    .filter((e) => e.specimen !== judgment.winner)
-    .map((e) => ({
-      specimen: e.specimen,
-      reason: e.hackFindings.length
-        ? `hack: ${e.hackFindings.map((f) => f.pattern).join(",")}`
-        : `gate testPassRate=${e.testPassRate.toFixed(2)}`,
-      diff: Object.entries(readSpecimenFiles(root, slice, e.specimen))
-        .map(([p, c]) => `+++ ${p}\n${c}`)
-        .join("\n"),
-      critique: "",
-      hackFindings: e.hackFindings,
-    }));
+  const culled = culledFromEvals(root, slice, evals, judgment.winner);
   await writeDoc(root, join("50-pressure", slice, "pressure.md"), {
     frontmatter: { summary: `Pressure log ${slice}: ${culled.length} culled.` },
     body: renderPressureLog({ sliceId: slice, culled }),
@@ -916,10 +1043,12 @@ export async function runBridge(argv: string[]): Promise<void> {
   const [sub, ...rest] = argv;
   const args = parseArgs(rest);
   switch (sub) {
+    case "version": versionCmd(); break;
     case "begin": await begin(args); break;
     case "record-eval": recordEval(args); break;
     case "eval": evalCmd(args); break;
     case "gate": gate(args); break;
+    case "escalate": await escalateCmd(args); break;
     case "record-votes": recordVotes(args); break;
     case "select": await selectCmd(args); break;
     case "finalize": await finalize(args); break;

package/src/cli.ts

@@ -3,16 +3,22 @@
  *
  *   stz init [dir]        scaffold the .stz/ taxonomy + AGENTS.md
  *   stz run  [dir]        run the bundled demo slice through the mock pipeline
+ *   stz update            check npm for a newer release + channel drift (F19)
+ *   stz migrate [dir]     bring an existing .stz/ tree up to the current schema (F19)
+ *   stz --version
  *   stz help
  */
 import { join } from "node:path";
-import { writeFile } from "node:fs/promises";
+import { writeFile, readFile } 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";
+import { STZ_VERSION } from "./version.js";
+import { checkLatest, buildVerdict, formatVerdict } from "./update.js";
+import { writeManifest, migrate } from "./migrate.js";
 
 const AGENTS_MD = `# AGENTS.md — STZ table of contents
 
@@ -51,6 +57,7 @@ const DEMO_MANIFEST: SliceManifest = {
 
 async function cmdInit(dir: string): Promise<void> {
   const created = await scaffold(dir);
+  await writeManifest(dir); // F19: stamp the tree so `stz migrate` can detect drift later
   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)." },
@@ -59,6 +66,63 @@ async function cmdInit(dir: string): Promise<void> {
   console.log(`Scaffolded ${STZ_DIR}/ (${TIERS.length} tiers, ${created.length} created) + AGENTS.md at ${dir}`);
 }
 
+/**
+ * Discover the Claude Code plugin's bundled engine version, for drift detection
+ * (F19). The plugin sets `CLAUDE_PLUGIN_ROOT`; fall back to a manifest in cwd so
+ * a developer running inside the repo still sees drift. Returns null when no
+ * plugin manifest is reachable (a pure npm-CLI user has no second channel).
+ */
+async function readPluginVersion(dir: string): Promise<string | null> {
+  const roots = [process.env.CLAUDE_PLUGIN_ROOT, dir].filter(Boolean) as string[];
+  for (const root of roots) {
+    const p = join(root, ".claude-plugin", "plugin.json");
+    if (!existsSync(p)) continue;
+    try {
+      const manifest = JSON.parse(await readFile(p, "utf8")) as { version?: unknown };
+      if (typeof manifest.version === "string") return manifest.version;
+    } catch {
+      // Unreadable/malformed manifest -> treat as "no plugin info", not a crash.
+    }
+  }
+  return null;
+}
+
+async function cmdUpdate(): Promise<void> {
+  const asJson = process.argv.includes("--check") || process.argv.includes("--json");
+  const latest = await checkLatest();
+  // Plugin discovery uses the working directory (and CLAUDE_PLUGIN_ROOT), not a
+  // positional — `update` takes flags, not a dir, so the operator's cwd is the
+  // right place to look for a co-located plugin manifest.
+  const pluginVersion = await readPluginVersion(process.cwd());
+  const verdict = buildVerdict({
+    installed: STZ_VERSION,
+    latest: latest.version,
+    pluginVersion,
+    reason: latest.ok ? undefined : latest.reason,
+  });
+  if (asJson) {
+    console.log(JSON.stringify(verdict, null, 2));
+  } else {
+    console.log(formatVerdict(verdict));
+  }
+  // Exit non-zero when action is required, so scripts/CI can gate on it.
+  if (verdict.stale || verdict.drift) process.exitCode = 1;
+}
+
+async function cmdMigrate(dir: string): Promise<void> {
+  const noBackup = process.argv.includes("--no-backup");
+  const report = await migrate(dir, { backup: !noBackup });
+  if (report.upToDate) {
+    console.log(`${STZ_DIR}/ already at schema ${report.toSchema} — nothing to migrate.`);
+    return;
+  }
+  console.log(
+    `Migrated ${STZ_DIR}/ schema ${report.fromSchema} → ${report.toSchema} ` +
+      `(${report.created.length} tier(s) created).`,
+  );
+  if (report.backedUpTo) console.log(`Backup of the prior tree: ${report.backedUpTo}`);
+}
+
 async function cmdRun(dir: string): Promise<void> {
   if (!existsSync(join(dir, STZ_DIR))) await scaffold(dir);
   const model = new MockModelLayer(defaultMockConfig());
@@ -86,7 +150,10 @@ function cmdHelp(): void {
 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 update [--check] check npm for a newer release + plugin/CLI drift
+  stz migrate [dir]    bring an existing .stz/ tree up to the current schema
   stz bridge <cmd>     deterministic orchestration bridge (used by the /stz:* commands)
+  stz --version        print the installed version
   stz help             show this help
 
 In Claude Code, install the plugin and drive the full pipeline with /stz:new,
@@ -104,6 +171,17 @@ async function main(): Promise<void> {
     case "run":
       await cmdRun(dir);
       break;
+    case "update":
+      await cmdUpdate();
+      break;
+    case "migrate":
+      await cmdMigrate(dir);
+      break;
+    case "--version":
+    case "-v":
+    case "version":
+      console.log(STZ_VERSION);
+      break;
     case "bridge":
       // Deterministic orchestration bridge called by the /stz:run command
       // between Task-subagent spawns. Everything after "bridge" is its argv.

package/src/migrate.ts

@@ -0,0 +1,130 @@
+/**
+ * Project-scaffold migration (F19, the "B" half of the update pathway).
+ *
+ * Updating the *engine* (npm CLI / plugin) does not touch a project's on-disk
+ * `.stz/` tree. When a new STZ release changes the taxonomy (adds a tier, a
+ * manifest field), existing projects silently fall behind. This module stamps
+ * every scaffold with a manifest carrying `{stzVersion, schemaVersion}` and
+ * provides an **additive, backed-up** migration so an old tree can be brought
+ * current without losing anything.
+ *
+ * Safety contract: migration only ever *creates* missing tiers (it reuses the
+ * idempotent `scaffold`, which never deletes) and always copies the prior tree
+ * to a sibling backup first. A destructive change (renamed/removed tier) is out
+ * of scope by construction — there is no code path here that removes a file.
+ */
+import { writeFile, readFile, cp } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { STZ_DIR, TIERS, scaffold } from "./taxonomy.js";
+import { STZ_VERSION, SCHEMA_VERSION } from "./version.js";
+
+/** The on-disk manifest stamped at the root of a `.stz/` tree. */
+export interface StzManifest {
+  stzVersion: string;
+  schemaVersion: number;
+  tiers: string[];
+}
+
+const MANIFEST_REL = "manifest.json";
+
+/** Absolute path to a project's `.stz/manifest.json`. */
+export function manifestPath(root: string): string {
+  return join(root, STZ_DIR, MANIFEST_REL);
+}
+
+/** Write (or overwrite) the manifest for the current STZ + schema version. */
+export async function writeManifest(root: string): Promise<StzManifest> {
+  const manifest: StzManifest = {
+    stzVersion: STZ_VERSION,
+    schemaVersion: SCHEMA_VERSION,
+    tiers: [...TIERS],
+  };
+  await writeFile(manifestPath(root), JSON.stringify(manifest, null, 2) + "\n", "utf8");
+  return manifest;
+}
+
+/**
+ * Read the manifest if present. Returns null for a pre-manifest project (an
+ * `.stz/` tree scaffolded before F19) so callers can treat it as schema 0.
+ */
+export async function readManifest(root: string): Promise<StzManifest | null> {
+  const p = manifestPath(root);
+  if (!existsSync(p)) return null;
+  const parsed = JSON.parse(await readFile(p, "utf8")) as Partial<StzManifest>;
+  return {
+    stzVersion: typeof parsed.stzVersion === "string" ? parsed.stzVersion : "0.0.0",
+    schemaVersion: typeof parsed.schemaVersion === "number" ? parsed.schemaVersion : 0,
+    tiers: Array.isArray(parsed.tiers) ? parsed.tiers : [],
+  };
+}
+
+/** What `migrate` did, for the CLI to report and `--check` to emit as JSON. */
+export interface MigrateReport {
+  root: string;
+  fromSchema: number;
+  toSchema: number;
+  /** True when nothing needed doing (already current, all tiers present). */
+  upToDate: boolean;
+  /** Tiers created by this migration (additive only). */
+  created: string[];
+  /** Sibling path the prior tree was copied to, or null when no change. */
+  backedUpTo: string | null;
+}
+
+/** True when every current tier directory already exists under `.stz/`. */
+function allTiersPresent(root: string): boolean {
+  return TIERS.every((t) => existsSync(join(root, STZ_DIR, t)));
+}
+
+/**
+ * Bring an existing `.stz/` tree up to the current schema. Idempotent: a second
+ * run on an already-current tree is a no-op (`upToDate: true`, no backup).
+ *
+ * @throws if there is no `.stz/` tree to migrate (use `stz init` first).
+ */
+export async function migrate(
+  root: string,
+  opts: { backup?: boolean } = {},
+): Promise<MigrateReport> {
+  const backup = opts.backup ?? true;
+  if (!existsSync(join(root, STZ_DIR))) {
+    throw new Error(`no ${STZ_DIR}/ tree at ${root} — run \`stz init\` first`);
+  }
+  const current = await readManifest(root);
+  const fromSchema = current?.schemaVersion ?? 0;
+
+  // Already current AND structurally complete -> nothing to do. (We still
+  // rewrite a missing manifest below if the schema matched but the stamp was
+  // absent, so a pre-manifest tree at the same layout still gets stamped.)
+  if (fromSchema === SCHEMA_VERSION && current !== null && allTiersPresent(root)) {
+    return {
+      root,
+      fromSchema,
+      toSchema: SCHEMA_VERSION,
+      upToDate: true,
+      created: [],
+      backedUpTo: null,
+    };
+  }
+
+  // Back up the prior tree before any additive change.
+  let backedUpTo: string | null = null;
+  if (backup) {
+    backedUpTo = join(root, `${STZ_DIR}.bak-schema${fromSchema}`);
+    await cp(join(root, STZ_DIR), backedUpTo, { recursive: true });
+  }
+
+  // Additive only: scaffold creates missing tiers, never removes.
+  const created = await scaffold(root);
+  await writeManifest(root);
+
+  return {
+    root,
+    fromSchema,
+    toSchema: SCHEMA_VERSION,
+    upToDate: false,
+    created,
+    backedUpTo,
+  };
+}

package/src/mock/orchestrator.ts

@@ -8,7 +8,7 @@
  * The model layer is injected (ModelLayer), so this runs identically against
  * the deterministic mock and a future live Claude Code / Codex implementation.
  *
- * STUBBED vs the full design (logged via the `log` sink, surfaced in AS-BUILT):
+ * STUBBED vs the full design (logged via the `log` sink, surfaced in ROADMAP):
  *   - git worktrees per specimen → prototypes/specimen-X/ directories instead.
  *   - per-worktree ephemeral observability stacks → not spun up.
  *   - live Python eval drivers / mutation / PBT → mock EvalRunner.

package/src/update.ts

@@ -0,0 +1,207 @@
+/**
+ * Update pathway (F19): tell the operator whether their STZ is current, and
+ * print the exact command(s) to fix it. Two distribution channels mean two
+ * things can be stale independently:
+ *
+ *   - the **npm CLI** (`slice-tournament-zoo` on PATH), and
+ *   - the **Claude Code plugin** (the bundled `stz bridge` the `/stz:*`
+ *     commands call via `${CLAUDE_PLUGIN_ROOT}`).
+ *
+ * A "sustainable" pathway therefore does three things: detect a newer npm
+ * release, detect *drift* between the two channels, and emit deterministic
+ * remediation commands. The registry fetch is **injectable** so the pure verdict
+ * logic is unit-tested offline (STZ's no-network test ethos) while the real CLI
+ * uses global `fetch`.
+ */
+import { PACKAGE_NAME, registryLatestUrl } from "./version.js";
+
+/** Result of an npm latest-version check. Structured, never prose-parsed. */
+export interface LatestResult {
+  ok: boolean;
+  version: string | null;
+  /** Machine-readable reason on failure (network, parse, http, …). */
+  reason: string;
+}
+
+/** The verdict the CLI renders and `--check` emits as JSON. */
+export interface UpdateVerdict {
+  packageName: string;
+  installed: string;
+  latest: string | null;
+  /** A newer npm release exists. */
+  stale: boolean;
+  /** Installed is ahead of npm latest (local/dev build). */
+  ahead: boolean;
+  /** Plugin bundled engine differs from the installed CLI, when known. */
+  drift: boolean;
+  /** Plugin engine version if discoverable, else null. */
+  pluginVersion: string | null;
+  /** Exact remediation commands, in order. Empty when fully up to date. */
+  commands: string[];
+  /** Why the check could not complete, if `latest` is null. */
+  reason?: string;
+}
+
+// ── semver compare (the subset STZ versions actually use) ────────────────────
+
+interface Semver {
+  major: number;
+  minor: number;
+  patch: number;
+  /** Pre-release identifiers (e.g. `rc.1` -> ["rc", 1]); empty for releases. */
+  pre: Array<string | number>;
+}
+
+/** Parse `MAJOR.MINOR.PATCH[-pre]`. Throws on a non-semver string. */
+export function parseSemver(v: string): Semver {
+  const m = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(v.trim());
+  if (!m) throw new Error(`not a semver: ${v}`);
+  const pre = m[4]
+    ? m[4].split(".").map((id) => (/^\d+$/.test(id) ? Number(id) : id))
+    : [];
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]), pre };
+}
+
+/**
+ * Compare two semvers. Returns -1 if a<b, 0 if equal, 1 if a>b. Implements the
+ * precedence rule that a pre-release is *lower* than its release (1.0.0-rc < 1.0.0).
+ */
+export function compareSemver(a: string, b: string): -1 | 0 | 1 {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  for (const k of ["major", "minor", "patch"] as const) {
+    if (pa[k] !== pb[k]) return pa[k] < pb[k] ? -1 : 1;
+  }
+  // Equal core. A release outranks any pre-release of the same core.
+  if (pa.pre.length === 0 && pb.pre.length === 0) return 0;
+  if (pa.pre.length === 0) return 1; // a is release, b is pre
+  if (pb.pre.length === 0) return -1; // a is pre, b is release
+  const n = Math.min(pa.pre.length, pb.pre.length);
+  for (let i = 0; i < n; i++) {
+    const x = pa.pre[i];
+    const y = pb.pre[i];
+    if (x === y) continue;
+    // Numeric identifiers rank lower than alphanumeric; otherwise compare in kind.
+    const xn = typeof x === "number";
+    const yn = typeof y === "number";
+    if (xn && yn) return (x as number) < (y as number) ? -1 : 1;
+    if (xn !== yn) return xn ? -1 : 1;
+    return (x as string) < (y as string) ? -1 : 1;
+  }
+  if (pa.pre.length === pb.pre.length) return 0;
+  return pa.pre.length < pb.pre.length ? -1 : 1;
+}
+
+// ── verdict ──────────────────────────────────────────────────────────────────
+
+/** Inputs to {@link buildVerdict}; all version strings, no I/O. */
+export interface VerdictInput {
+  installed: string;
+  latest: string | null;
+  pluginVersion?: string | null;
+  reason?: string;
+}
+
+/**
+ * Pure: turn (installed, latest, pluginVersion) into a verdict + remediation
+ * commands. No network, no filesystem — this is the unit under test.
+ */
+export function buildVerdict(input: VerdictInput): UpdateVerdict {
+  const { installed, latest } = input;
+  const pluginVersion = input.pluginVersion ?? null;
+
+  const stale = latest != null && compareSemver(installed, latest) < 0;
+  const ahead = latest != null && compareSemver(installed, latest) > 0;
+  const drift = pluginVersion != null && compareSemver(installed, pluginVersion) !== 0;
+
+  const commands: string[] = [];
+  if (stale) commands.push(`npm i -g ${PACKAGE_NAME}@latest`);
+  // The plugin updates through Claude Code's plugin manager, not npm. Surface it
+  // whenever a newer release exists OR the two channels have drifted apart.
+  if (stale || drift) commands.push("/plugin update stz");
+
+  return {
+    packageName: PACKAGE_NAME,
+    installed,
+    latest,
+    stale,
+    ahead,
+    drift,
+    pluginVersion,
+    commands,
+    ...(input.reason ? { reason: input.reason } : {}),
+  };
+}
+
+// ── registry check (injectable fetch) ────────────────────────────────────────
+
+/** A minimal fetch signature so tests inject a fake without a network. */
+export type FetchLike = (url: string) => Promise<{
+  ok: boolean;
+  status: number;
+  json: () => Promise<unknown>;
+}>;
+
+/**
+ * Query npm for the latest published version. Network failures, non-200s, and
+ * malformed bodies all collapse to `{ok:false, reason}` rather than throwing,
+ * so the CLI degrades to "couldn't check" instead of crashing.
+ */
+export async function checkLatest(
+  fetchImpl: FetchLike = globalThis.fetch as unknown as FetchLike,
+): Promise<LatestResult> {
+  if (typeof fetchImpl !== "function") {
+    return { ok: false, version: null, reason: "no_fetch_available" };
+  }
+  let res: Awaited<ReturnType<FetchLike>>;
+  try {
+    res = await fetchImpl(registryLatestUrl());
+  } catch {
+    return { ok: false, version: null, reason: "network_error" };
+  }
+  if (!res.ok) {
+    return { ok: false, version: null, reason: `http_${res.status}` };
+  }
+  let body: unknown;
+  try {
+    body = await res.json();
+  } catch {
+    return { ok: false, version: null, reason: "invalid_json" };
+  }
+  const version = (body as { version?: unknown })?.version;
+  if (typeof version !== "string") {
+    return { ok: false, version: null, reason: "missing_version_field" };
+  }
+  try {
+    parseSemver(version);
+  } catch {
+    return { ok: false, version: null, reason: "unparseable_version" };
+  }
+  return { ok: true, version, reason: "ok" };
+}
+
+/** Human-readable summary for the `stz update` (non-`--check`) path. */
+export function formatVerdict(v: UpdateVerdict): string {
+  const lines: string[] = [];
+  lines.push(`STZ ${v.installed} (${v.packageName})`);
+  if (v.latest == null) {
+    lines.push(`Couldn't check npm for updates (reason: ${v.reason ?? "unknown"}).`);
+    lines.push(`To update manually: npm i -g ${v.packageName}@latest`);
+    return lines.join("\n");
+  }
+  if (v.stale) lines.push(`Update available: ${v.latest} (you have ${v.installed}).`);
+  else if (v.ahead) lines.push(`You're ahead of npm latest (${v.latest}) — local/dev build.`);
+  else lines.push(`Up to date with npm latest (${v.latest}).`);
+  if (v.drift) {
+    lines.push(
+      `⚠ Channel drift: plugin engine ${v.pluginVersion} ≠ CLI ${v.installed}. ` +
+        `The /stz:* commands may use a different version than the CLI.`,
+    );
+  }
+  if (v.commands.length) {
+    lines.push("");
+    lines.push("Run:");
+    for (const c of v.commands) lines.push(`  ${c}`);
+  }
+  return lines.join("\n");
+}

package/src/version.ts

@@ -0,0 +1,51 @@
+/**
+ * Single version-identity seam (F19 update pathway).
+ *
+ * One place owns "what version am I, what package am I, what npm endpoint do I
+ * check". Every other module imports from here rather than re-typing a literal.
+ * Two hard-won lessons from prior-art update mechanisms are baked in:
+ *
+ *  - The **package name is a code constant**, never an LLM/runtime free choice.
+ *    A model-driven update path that "decides" the npm name at execution time
+ *    mistypes it (`@stz/cli`, `slice-tournament`, a typosquat) and queries the
+ *    wrong package. Pinning it here closes that gap.
+ *  - The **CLI version is read from package.json**, never hardcoded into a `.ts`
+ *    string, so a release bump can never leave the reported version stale.
+ *
+ * `SCHEMA_VERSION` is independent of the package version: it tracks the shape of
+ * the on-disk `.stz/` taxonomy and only bumps when the tier layout changes, so
+ * `stz migrate` knows whether an existing project tree needs additive upgrade.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+/** The npm package name. A code constant — see file header. */
+export const PACKAGE_NAME = "slice-tournament-zoo";
+
+/**
+ * Schema version of the `.stz/` taxonomy tree. Bump when `TIERS` (or the
+ * manifest shape) changes so `stz migrate` can detect an out-of-date project.
+ */
+export const SCHEMA_VERSION = 1;
+
+/** Read the package version from the shipped package.json (never hardcoded). */
+function readPackageVersion(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  // src/version.ts -> ../package.json. npm always ships package.json, and the
+  // source-available repo has it at the root, so this resolves in both modes.
+  const pkgPath = join(here, "..", "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { version?: string };
+  if (!pkg.version) throw new Error(`package.json at ${pkgPath} has no version`);
+  return pkg.version;
+}
+
+/** The installed STZ version, sourced from package.json. */
+export const STZ_VERSION = readPackageVersion();
+
+/** The npm registry endpoint that resolves the latest published version. */
+export function registryLatestUrl(pkg: string = PACKAGE_NAME): string {
+  // The `latest` dist-tag document is small and CORS-free; `.version` is the
+  // published latest. Encode the name defensively though it is a constant.
+  return `https://registry.npmjs.org/${encodeURIComponent(pkg)}/latest`;
+}