slice-tournament-zoo 0.5.6 → 0.6.0

package/README.md

@@ -12,8 +12,8 @@
 </pre>
 
 [![CI](https://github.com/dr-robert-li/slice-tournament-zoo/actions/workflows/ci.yml/badge.svg)](https://github.com/dr-robert-li/slice-tournament-zoo/actions/workflows/ci.yml)
-[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
-[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](./package.json)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/dr-robert-li/slice-tournament-zoo/blob/main/LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://github.com/dr-robert-li/slice-tournament-zoo/blob/main/package.json)
 
 </div>
 
@@ -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
@@ -87,7 +98,45 @@ needed (Node.js 20+ is the only requirement; the bundled copy fetches `tsx` via
 `npx` on first use, so that first call needs network).
 
 > Developing STZ itself, or running the engine without Claude Code? See
-> [`docs/development/local-and-testing.md`](./docs/development/local-and-testing.md).
+> [`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
 
@@ -174,7 +223,7 @@ stz bridge project-dark-factory --root . --on    # engage; --off to disengage
 The toggle only flips the `darkFactory` flag in the run config — it never resets
 your fan-out / models / strictness. `project-status` hoists the flag to the top
 level, so engaging it between phases takes effect immediately. See
-[`docs/development/dark-factory.md`](docs/development/dark-factory.md) for the full
+[`docs/development/dark-factory.md`](https://github.com/dr-robert-li/slice-tournament-zoo/blob/main/docs/development/dark-factory.md) for the full
 contract.
 
 The DAG ordering and per-slice seeding are backed by the deterministic
@@ -187,7 +236,7 @@ any slice runs. When `/stz:slice` seeds the DAG, each slice inherits those early
 phases as done, leaving only the tournament half for `/stz:run`. Project status
 is derived from each slice's own `state.json`, so an interrupted pipeline resumes
 by re-reading state. A worked run of the front phases (a `slugify` library) lives
-in [`examples/full-pipeline/`](./examples/full-pipeline).
+in [`examples/full-pipeline/`](https://github.com/dr-robert-li/slice-tournament-zoo/tree/main/examples/full-pipeline).
 
 ### Run a slice as a tournament (in Claude Code)
 
@@ -341,17 +390,17 @@ split above is the real in-session flow.
 For contributors and anyone going past day-to-day operation:
 
 - **Contributing** — setup, the architecture rule, the quality bar:
-  [`CONTRIBUTING.md`](./CONTRIBUTING.md).
-- **Source layout** — the `src/` module map: [`src/README.md`](./src/README.md).
+  [`CONTRIBUTING.md`](https://github.com/dr-robert-li/slice-tournament-zoo/blob/main/CONTRIBUTING.md).
+- **Source layout** — the `src/` module map: [`src/README.md`](https://github.com/dr-robert-li/slice-tournament-zoo/blob/main/src/README.md).
 - **Local development & testing** — run the engine without Claude Code, the mock
-  pipeline, CI checks: [`docs/development/local-and-testing.md`](./docs/development/local-and-testing.md).
+  pipeline, CI checks: [`docs/development/local-and-testing.md`](https://github.com/dr-robert-li/slice-tournament-zoo/blob/main/docs/development/local-and-testing.md).
 - **The bridge CLI** — the deterministic `stz bridge` subcommands:
-  [`docs/development/bridge-cli.md`](./docs/development/bridge-cli.md).
+  [`docs/development/bridge-cli.md`](https://github.com/dr-robert-li/slice-tournament-zoo/blob/main/docs/development/bridge-cli.md).
 - **Sealed-suite integrity** — the guide-vs-sensor contract behind the frozen
-  held-out suite: [`docs/development/sealed-suite.md`](./docs/development/sealed-suite.md).
-- **Requirement-to-test mapping** — [`docs/TESTPLAN.md`](./docs/TESTPLAN.md).
-- **What is real versus deferred** — [`docs/AS-BUILT.md`](./docs/AS-BUILT.md).
+  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).
 
 ## License
 
-[Apache-2.0](./LICENSE).
+[Apache-2.0](https://github.com/dr-robert-li/slice-tournament-zoo/blob/main/LICENSE).

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "slice-tournament-zoo",
-  "version": "0.5.6",
+  "version": "0.6.0",
   "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dr-robert-li/slice-tournament-zoo.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dr-robert-li/slice-tournament-zoo/issues"
+  },
   "type": "module",
   "bin": {
     "stz": "bin/stz.mjs"

package/src/README.md

@@ -9,11 +9,11 @@ per-slice and project subcommands).
 
 The `mock/` subfolder is the no-network testing harness (the `stz run` demo):
 its orchestrator, the model-layer seam, and the deterministic mock. Not part of
-the production path — see [`mock/`](./mock).
+the production path — see [`mock/`](https://github.com/dr-robert-li/slice-tournament-zoo/tree/main/src/mock).
 
 ## Further reading
 
-- The requirement-to-test mapping is in [`docs/TESTPLAN.md`](../docs/TESTPLAN.md).
-- What is real versus deferred is in [`docs/AS-BUILT.md`](../docs/AS-BUILT.md).
-- Running the engine locally / in CI: [`docs/development/local-and-testing.md`](../docs/development/local-and-testing.md).
-- The deterministic bridge CLI: [`docs/development/bridge-cli.md`](../docs/development/bridge-cli.md).
+- 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).
+- 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

@@ -56,6 +56,7 @@ import {
   defaultRunConfig,
 } from "./project.js";
 import { detectHacks } from "./hack-detector.js";
+import { STZ_VERSION, SCHEMA_VERSION, PACKAGE_NAME } from "./version.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 +96,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);
@@ -916,6 +927,7 @@ 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;

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/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`;
+}