heyspex 0.1.0 → 0.2.0

package/scripts/wip-ledger-health.mjs

@@ -0,0 +1,653 @@
+#!/usr/bin/env node
+/**
+ * wip-ledger-health — visibility + restore for the WIP hand-off ledger
+ * (`.heyspex/wip-state.json`) and its archive (`.heyspex/wip-archive/*.jsonl`).
+ *
+ * Why this exists: the ledger is a JSON object of `epic id -> entry` that only
+ * gets pruned/archived on a WRITE (a peer lane, [[HS-B8OK-PFMN]], is adding
+ * age-based archive/shrink rules to that write path). Nobody can see the
+ * ledger's health — line count against the 600-line budget, how many entries
+ * are aging toward archival, whether one entry is disproportionately large —
+ * without waiting for a write to warn about it. This module answers that
+ * read-only, and gives a way to pull an archived entry back onto the live
+ * ledger without hand-editing JSON.
+ *
+ * Three faces share this core (per the "capability = core → MCP + CLI" rule):
+ *   - hs CLI   `hs wip status` / `hs wip restore <id>`   (bin/hs.mjs → this file)
+ *   - `node scripts/wip-ledger-health.mjs status|restore …`  direct invocation
+ *
+ * Every exported function is pure w.r.t. process state — no `process.exit`
+ * anywhere outside `main()` (Windows + Node 24: an exit mid-request throws
+ * away the real exit code — this repo already removed ~150 such calls). Every
+ * function also takes `ledgerPath`/`archiveDir`/`now` as arguments, defaulting
+ * to the real `.heyspex/` paths and the real clock ONLY inside `main()`, so
+ * tests never touch the real vault and never depend on the wall clock.
+ *
+ * Run directly:
+ *   node scripts/wip-ledger-health.mjs status [--json]
+ *   node scripts/wip-ledger-health.mjs restore <id> [--json] [--force]
+ */
+import { readFileSync, writeFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { getAuthHeader, makeConsoleFetch } from "../vendor/heyspex-mcp/console-fetch.mjs";
+import { resolveConsoleUrl } from "./lib/console-url-resolver.mjs";
+import { resolveDevMode } from "./lib/dev-mode.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(__dirname, "..");
+
+export const BUDGET_LINES = 600;
+// Age tiers: fresh [0, FRESH_MAX_DAYS], aging (FRESH_MAX_DAYS, STALE_MIN_DAYS],
+// stale (STALE_MIN_DAYS, ∞) — boundaries are inclusive on the LOWER tier,
+// mirroring the write path's own `age > cutoff` comparisons exactly (an entry
+// sitting exactly ON a cutoff has not yet crossed it).
+//
+// These numbers MUST match the real cutoffs the write path enforces:
+// `WIP_COMPACT_AFTER_DAYS` (shrink window start) and `WIP_STALE_AFTER_DAYS`
+// (archive-out threshold) in spex-console/src/lib/wip-archive.ts — the write
+// path shrinks an entry in place for `age > compactAfterDays && age <=
+// staleAfterDays` and archives it out for `age > staleAfterDays`. This file
+// stays plain Node with no dependency on that TypeScript module, so the two
+// constant sets can't be imported into sync — if either cutoff there moves,
+// move FRESH_MAX_DAYS / STALE_MIN_DAYS here too, or this health report will
+// describe a different ledger than the one the write path is about to produce.
+export const FRESH_MAX_DAYS = 2;
+export const STALE_MIN_DAYS = 7;
+
+export const EXIT = { OK: 0, REFUSED: 1, NOT_FOUND: 1, BAD_INVOCATION: 2 };
+
+// ---- path defaults (real filesystem only reached from main()) -------------
+
+export function defaultVaultRoot() {
+  return process.env.HS_VAULT_ROOT || PKG_ROOT;
+}
+
+export function defaultLedgerPath(vaultRoot = defaultVaultRoot()) {
+  return path.join(vaultRoot, ".heyspex", "wip-state.json");
+}
+
+export function defaultArchiveDir(vaultRoot = defaultVaultRoot()) {
+  return path.join(vaultRoot, ".heyspex", "wip-archive");
+}
+
+// ---- age classification ----------------------------------------------------
+
+/**
+ * Classify an age in days into 'fresh' | 'aging' | 'stale'. Never touches the
+ * clock — callers compute `ageDays` via `ageDaysFrom` against an explicit `now`.
+ *
+ * Boundaries are `<=`, not `<`, to mirror the write path's own `age > cutoff`
+ * checks exactly: an entry sitting at exactly FRESH_MAX_DAYS has not yet
+ * crossed into the shrink window (write path leaves it alone), and one at
+ * exactly STALE_MIN_DAYS has not yet crossed into archive-out (write path
+ * still just shrinks it). See the constant comments above for where the real
+ * cutoffs live.
+ */
+export function classifyAge(ageDays) {
+  if (ageDays <= FRESH_MAX_DAYS) return "fresh";
+  if (ageDays <= STALE_MIN_DAYS) return "aging";
+  return "stale";
+}
+
+export function ageDaysFrom(updatedAtIso, now = new Date()) {
+  const nowMs = now instanceof Date ? now.getTime() : now;
+  const thenMs = new Date(updatedAtIso).getTime();
+  return (nowMs - thenMs) / (24 * 60 * 60 * 1000);
+}
+
+/** Count newline characters the way `wc -l` does (no off-by-one on a trailing newline). */
+export function countLines(raw) {
+  const matches = raw.match(/\n/g);
+  return matches ? matches.length : 0;
+}
+
+// ---- ledger read ------------------------------------------------------------
+
+/**
+ * Read + parse the live ledger. Never throws — every failure mode (missing
+ * file, unreadable, unparseable, wrong shape) comes back as `{ ok: false, error }`
+ * so callers can print a clear message instead of a stack trace.
+ */
+export function readLedger(ledgerPath) {
+  let raw;
+  try {
+    raw = readFileSync(ledgerPath, "utf8");
+  } catch (err) {
+    if (err && err.code === "ENOENT") {
+      return { ok: false, error: `ledger file not found: ${ledgerPath}` };
+    }
+    return {
+      ok: false,
+      error: `could not read ledger file ${ledgerPath}: ${err.message}`,
+    };
+  }
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (err) {
+    return {
+      ok: false,
+      error: `ledger file ${ledgerPath} is not valid JSON: ${err.message}`,
+    };
+  }
+  if (data === null || typeof data !== "object" || Array.isArray(data)) {
+    return {
+      ok: false,
+      error: `ledger file ${ledgerPath} does not contain a JSON object of entries`,
+    };
+  }
+  return { ok: true, data, raw, lineCount: countLines(raw) };
+}
+
+// ---- archive read -----------------------------------------------------------
+
+function listArchiveFiles(archiveDir) {
+  try {
+    return readdirSync(archiveDir)
+      .filter((f) => f.endsWith(".jsonl"))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+function readArchiveSummary(archiveDir) {
+  const files = listArchiveFiles(archiveDir);
+  let totalSizeBytes = 0;
+  for (const f of files) {
+    try {
+      totalSizeBytes += statSync(path.join(archiveDir, f)).size;
+    } catch {
+      // A file that vanished between readdir and stat doesn't count. Not an
+      // error worth surfacing in a health report.
+    }
+  }
+  return {
+    fileCount: files.length,
+    totalSizeBytes,
+    totalSizeKB: totalSizeBytes / 1024,
+  };
+}
+
+/**
+ * Scan every `.heyspex/wip-archive/*.jsonl` file for records `{ id, archivedAt,
+ * entry }` matching `id`, and return the one with the newest `archivedAt`
+ * (or null if `id` was never archived). Malformed lines/files are skipped,
+ * never thrown.
+ */
+function findNewestArchived(archiveDir, id) {
+  const files = listArchiveFiles(archiveDir);
+  let newest = null;
+  for (const file of files) {
+    const filePath = path.join(archiveDir, file);
+    let content;
+    try {
+      content = readFileSync(filePath, "utf8");
+    } catch {
+      continue;
+    }
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      let record;
+      try {
+        record = JSON.parse(trimmed);
+      } catch {
+        continue;
+      }
+      if (!record || record.id !== id) continue;
+      const ts = Date.parse(record.archivedAt);
+      const newestTs = newest ? Date.parse(newest.archivedAt) : -Infinity;
+      if (!newest || ts > newestTs) {
+        newest = {
+          archivedAt: record.archivedAt,
+          entry: record.entry,
+          sourceFile: file,
+        };
+      }
+    }
+  }
+  return newest;
+}
+
+// ---- status report ----------------------------------------------------------
+
+/**
+ * Build the `hs wip status` health report. Pure: takes `ledgerPath`,
+ * `archiveDir`, and `now` explicitly; never reads the wall clock itself.
+ */
+export function buildReport({
+  ledgerPath,
+  archiveDir,
+  now = new Date(),
+  budgetLines = BUDGET_LINES,
+}) {
+  const ledgerResult = readLedger(ledgerPath);
+  if (!ledgerResult.ok) {
+    return { ok: false, error: ledgerResult.error, ledgerPath };
+  }
+  const { data, lineCount } = ledgerResult;
+  const ids = Object.keys(data);
+
+  const tiers = { fresh: 0, aging: 0, stale: 0 };
+  let oldest = null;
+  let largest = null;
+
+  for (const id of ids) {
+    const entry = data[id] ?? {};
+    const ageDays = ageDaysFrom(entry.updatedAt, now);
+    tiers[classifyAge(ageDays)] += 1;
+
+    if (!oldest || ageDays > oldest.ageDays) {
+      oldest = { id, ageDays };
+    }
+
+    const sizeBytes = Buffer.byteLength(JSON.stringify(entry), "utf8");
+    if (!largest || sizeBytes > largest.sizeBytes) {
+      largest = { id, sizeBytes, sizeKB: sizeBytes / 1024 };
+    }
+  }
+
+  return {
+    ok: true,
+    ledgerPath,
+    lineCount,
+    budgetLines,
+    overBudget: lineCount > budgetLines,
+    overUnderLines: lineCount - budgetLines,
+    entryCount: ids.length,
+    tiers,
+    oldest: oldest ? { id: oldest.id, ageDays: oldest.ageDays } : null,
+    largest: largest
+      ? { id: largest.id, sizeKB: largest.sizeKB }
+      : null,
+    archive: readArchiveSummary(archiveDir),
+    checkedAt: (now instanceof Date ? now : new Date(now)).toISOString(),
+  };
+}
+
+export function formatHumanReport(report) {
+  if (!report.ok) {
+    return `wip status: ${report.error}`;
+  }
+  const overUnderWord = report.overBudget ? "over" : "under";
+  const overUnderCount = Math.abs(report.overUnderLines);
+  const lines = [
+    `ledger: ${report.ledgerPath}`,
+    `lines: ${report.lineCount} / ${report.budgetLines} budget (${overUnderCount} lines ${overUnderWord} budget)`,
+    `entries: ${report.entryCount}`,
+    `age tiers: fresh ${report.tiers.fresh} (<=${FRESH_MAX_DAYS}d), aging ${report.tiers.aging} (${FRESH_MAX_DAYS}-${STALE_MIN_DAYS}d), stale ${report.tiers.stale} (>${STALE_MIN_DAYS}d)`,
+    report.oldest
+      ? `oldest entry: ${report.oldest.id} (${report.oldest.ageDays.toFixed(1)} days old)`
+      : "oldest entry: (ledger is empty)",
+    report.largest
+      ? `largest entry: ${report.largest.id} (${report.largest.sizeKB.toFixed(1)} KB)`
+      : "largest entry: (ledger is empty)",
+    `archive: ${report.archive.fileCount} file(s), ${report.archive.totalSizeKB.toFixed(1)} KB total`,
+  ];
+  return lines.join("\n");
+}
+
+// ---- restore ------------------------------------------------------------
+
+/**
+ * Pull the newest archived record for `id` back onto the live ledger.
+ *   - Refuses (code 1) when `id` is already live, unless `force`.
+ *   - Not-found (code 1) when `id` was never archived.
+ *   - On success, writes the ledger back with the same 2-space formatting +
+ *     trailing newline the file already uses, so the diff is only the
+ *     restored entry.
+ */
+export function restoreEntry({
+  id,
+  ledgerPath,
+  archiveDir,
+  force = false,
+  now = new Date(),
+}) {
+  const ledgerResult = readLedger(ledgerPath);
+  if (!ledgerResult.ok) {
+    return { ok: false, code: 1, message: ledgerResult.error };
+  }
+  const { data } = ledgerResult;
+
+  const archived = findNewestArchived(archiveDir, id);
+  if (!archived) {
+    return {
+      ok: false,
+      code: 1,
+      message: `no archived entry found for ${id} under ${archiveDir}`,
+    };
+  }
+
+  const hadLive = Object.prototype.hasOwnProperty.call(data, id);
+  if (hadLive && !force) {
+    return {
+      ok: false,
+      code: 1,
+      message:
+        `refusing to overwrite live entry for ${id} — ` +
+        `live updatedAt=${data[id]?.updatedAt ?? "unknown"}, ` +
+        `archived updatedAt=${archived.entry?.updatedAt ?? "unknown"} ` +
+        `(archived ${archived.archivedAt} in ${archived.sourceFile}). ` +
+        `Pass --force to overwrite.`,
+    };
+  }
+
+  data[id] = archived.entry;
+  const newRaw = JSON.stringify(data, null, 2) + "\n";
+  writeFileSync(ledgerPath, newRaw, "utf8");
+
+  return {
+    ok: true,
+    code: 0,
+    id,
+    archivedAt: archived.archivedAt,
+    sourceFile: archived.sourceFile,
+    ledgerPath,
+    newLineCount: countLines(newRaw),
+    overwritten: hadLive,
+    checkedAt: (now instanceof Date ? now : new Date(now)).toISOString(),
+  };
+}
+
+export function formatHumanRestore(result) {
+  if (!result.ok) {
+    return `wip restore: ${result.message}`;
+  }
+  const verb = result.overwritten ? "restored (overwrote live entry)" : "restored";
+  return (
+    `${verb}: ${result.id}\n` +
+    `  archivedAt: ${result.archivedAt}\n` +
+    `  from: ${result.sourceFile}\n` +
+    `  ledger: ${result.ledgerPath} (now ${result.newLineCount} lines)`
+  );
+}
+
+// ---- cloud-mode dispatch ----------------------------------------------------
+//
+// `hs wip status`/`hs wip restore` used to be local-filesystem-only: no HTTP,
+// no cloud awareness, so either command against a cloud vault either read a
+// stale/absent local file or silently reported "not found" even though the
+// ledger actually lives in Neon (`wip_ledger` / `wip_ledger_archive` —
+// `spex-console/src/lib/wip-state.ts` + `wip-ledger-archive-neon.ts`). This
+// section detects cloud reliance and, when it is unambiguously configured,
+// dispatches to the console's HTTP API instead of touching the filesystem —
+// mirroring the transport `scripts/lib/hs-companion-settings.mjs`'s
+// `makeCompanionConsoleFetch` already uses (shared `resolveConsoleUrl` + the
+// shared MCP bearer ladder from `vendor/heyspex-mcp/console-fetch.mjs`; there
+// is no WIP-specific loopback token equivalent to `COMPANION_UI_TOKEN`, so the
+// ladder here is just the shared one).
+//
+// Reliance detection is deliberately conservative: `resolveDevMode`
+// (`scripts/lib/dev-mode.mjs`) defaults an UNCONFIGURED machine to
+// prod/cloud (cloud is the default reliance for a HeySpex customer; local is
+// opt-in for a HeySpex admin's own dev machine — see the repo's CLAUDE.md).
+// That default is exactly the case a hermetic test run or a CI box hits (no
+// `HEYSPEX_DEV_MODE` env, no `~/.heyspex/dev-mode.json`), and this file's own
+// existing tests assume LOCAL file behavior with nothing configured. So an
+// UNRESOLVED default is treated as local here — only an EXPLICITLY resolved
+// cloud reliance (`sources.reliance` naming an env override, a machine-local
+// `dev-mode.json` override, or a cloud account setting — anything but
+// "default") switches this CLI to the HTTP path. This keeps every existing
+// local-mode call site (including this file's own test suite) byte-identical
+// when nothing about dev/cloud mode has been configured.
+
+/** True only when reliance was EXPLICITLY resolved to "cloud" (never the unconfigured default — see the note above). */
+export function isCloudReliance({ env = process.env, homeDir } = {}) {
+  try {
+    const resolved = resolveDevMode(homeDir ? { env, homeDir } : { env });
+    if (resolved?.sources?.reliance === "default") return false;
+    return resolved?.reliance === "cloud";
+  } catch {
+    return false; // fail open to the historical local-file behavior.
+  }
+}
+
+/**
+ * The console fetch this command uses in cloud mode: vendor transport + the
+ * shared URL resolver + the shared MCP bearer ladder (`HEYSPEX_MCP_TOKEN` env
+ * → `~/.heyspex/credentials.yaml` `mcp_token`) — the same building blocks
+ * `makeCompanionConsoleFetch` in `scripts/lib/hs-companion-settings.mjs` uses.
+ */
+export function makeWipConsoleFetch({
+  url = null,
+  env = process.env,
+  homeDir,
+  vaultRoot,
+  fetchImpl,
+} = {}) {
+  const getConsoleUrl = () =>
+    (
+      url ??
+      resolveConsoleUrl({
+        repoRoot: vaultRoot ?? env.HS_VAULT_ROOT ?? process.cwd(),
+        env,
+        ...(homeDir ? { homeDir } : {}),
+      })
+    ).replace(/\/+$/, "");
+  return makeConsoleFetch({
+    getConsoleUrl,
+    ...(fetchImpl ? { fetchImpl } : {}),
+    getAuthHeader: () => getAuthHeader(homeDir ? { env, homeDir } : { env }),
+  }).consoleFetch;
+}
+
+/** One-line failure text for a non-ok transport result (vendor console-fetch shape). */
+function describeCloudFailure(result, verb = "GET") {
+  if (!result || result.status === 0) {
+    const detail = result?.error ? ` (${result.error})` : "";
+    return result?.authMessage ?? `console unreachable at ${result?.url ?? "?"}${detail}`;
+  }
+  const body = result.body;
+  const msg =
+    (body && typeof body === "object" && (body.message ?? body.error ?? body.raw)) ??
+    (typeof body === "string" ? body : JSON.stringify(body));
+  return `${verb} failed ${result.status}: ${msg}`;
+}
+
+/**
+ * Cloud-mode `hs wip restore <id>` — POSTs
+ * `/api/specs/:id/wip/restore` (`spex-console/src/app/api/specs/[id]/wip/restore/route.ts`)
+ * instead of touching a local file. The result shape is close enough to
+ * {@link restoreEntry}'s that {@link formatHumanCloudRestore} reads the same
+ * way; there is no `ledgerPath`/`sourceFile` in cloud mode, so `consoleUrl`
+ * stands in for both.
+ */
+export async function restoreEntryCloud({ id, force = false, consoleFetch }) {
+  const res = await consoleFetch(`/api/specs/${encodeURIComponent(id)}/wip/restore`, {
+    method: "POST",
+    body: { force },
+  });
+  if (res.ok) {
+    return {
+      ok: true,
+      code: 0,
+      id,
+      archivedAt: res.body?.archivedAt ?? null,
+      overwritten: res.body?.overwritten === true,
+      consoleUrl: res.url,
+    };
+  }
+  return {
+    ok: false,
+    code: 1,
+    message: describeCloudFailure(res, "POST"),
+  };
+}
+
+export function formatHumanCloudRestore(result) {
+  if (!result.ok) {
+    return `wip restore: ${result.message}`;
+  }
+  const verb = result.overwritten ? "restored (overwrote live entry)" : "restored";
+  return (
+    `${verb}: ${result.id}\n` +
+    `  archivedAt: ${result.archivedAt}\n` +
+    `  console: ${result.consoleUrl}`
+  );
+}
+
+/**
+ * Cloud-mode `hs wip status` — builds a report shaped closely enough to
+ * {@link buildReport}'s that {@link formatHumanCloudReport} reads the same
+ * way, from `GET /api/wip` (the whole ledger for the caller's vault) instead
+ * of a local file. There is no cloud route for an archive summary today, so
+ * `archive` is reported `null` rather than fabricated — the
+ * `/api/cron/wip-archive-purge` retention job is the only visibility into the
+ * cloud archive right now.
+ */
+export async function buildCloudReport({
+  consoleFetch,
+  now = new Date(),
+  budgetLines = BUDGET_LINES,
+}) {
+  const res = await consoleFetch("/api/wip");
+  if (!res.ok) {
+    return { ok: false, error: describeCloudFailure(res, "GET"), consoleUrl: res.url };
+  }
+  const state =
+    res.body?.wip_state && typeof res.body.wip_state === "object" ? res.body.wip_state : {};
+  const ids = Object.keys(state);
+
+  const tiers = { fresh: 0, aging: 0, stale: 0 };
+  let oldest = null;
+  let largest = null;
+  for (const id of ids) {
+    const entry = state[id] ?? {};
+    const ageDays = ageDaysFrom(entry.updatedAt, now);
+    tiers[classifyAge(ageDays)] += 1;
+    if (!oldest || ageDays > oldest.ageDays) oldest = { id, ageDays };
+    const sizeBytes = Buffer.byteLength(JSON.stringify(entry), "utf8");
+    if (!largest || sizeBytes > largest.sizeBytes) {
+      largest = { id, sizeBytes, sizeKB: sizeBytes / 1024 };
+    }
+  }
+
+  return {
+    ok: true,
+    consoleUrl: res.url,
+    budgetLines,
+    entryCount: ids.length,
+    tiers,
+    oldest: oldest ? { id: oldest.id, ageDays: oldest.ageDays } : null,
+    largest: largest ? { id: largest.id, sizeKB: largest.sizeKB } : null,
+    archive: null,
+    checkedAt: (now instanceof Date ? now : new Date(now)).toISOString(),
+  };
+}
+
+export function formatHumanCloudReport(report) {
+  if (!report.ok) return `wip status: ${report.error}`;
+  const lines = [
+    `console: ${report.consoleUrl}`,
+    `entries: ${report.entryCount}`,
+    `age tiers: fresh ${report.tiers.fresh} (<=${FRESH_MAX_DAYS}d), aging ${report.tiers.aging} (${FRESH_MAX_DAYS}-${STALE_MIN_DAYS}d), stale ${report.tiers.stale} (>${STALE_MIN_DAYS}d)`,
+    report.oldest
+      ? `oldest entry: ${report.oldest.id} (${report.oldest.ageDays.toFixed(1)} days old)`
+      : "oldest entry: (ledger is empty)",
+    report.largest
+      ? `largest entry: ${report.largest.id} (${report.largest.sizeKB.toFixed(1)} KB)`
+      : "largest entry: (ledger is empty)",
+    "archive: cloud archive summary not available from this CLI yet — see the wip-archive-purge cron for retention",
+  ];
+  return lines.join("\n");
+}
+
+// ---- CLI entrypoint ---------------------------------------------------------
+
+function usageText() {
+  return [
+    "hs wip — WIP ledger health + restore",
+    "",
+    "  hs wip status [--json]              Health report on the live ledger",
+    "  hs wip restore <id> [--json] [--force]  Restore an archived entry onto the live ledger",
+    "",
+    "  Against a cloud vault (explicitly configured cloud reliance), both",
+    "  subcommands talk to the console's HTTP API instead of the local file.",
+  ].join("\n");
+}
+
+export function main(argv = process.argv.slice(2)) {
+  const [sub, ...rest] = argv;
+  const asJson = rest.includes("--json");
+  const vaultRoot = defaultVaultRoot();
+  const ledgerPath = defaultLedgerPath(vaultRoot);
+  const archiveDir = defaultArchiveDir(vaultRoot);
+
+  const emit = (text, code) => {
+    const stream = code === 0 ? process.stdout : process.stderr;
+    stream.write(text.endsWith("\n") ? text : text + "\n");
+    process.exit(code);
+  };
+
+  const cloud = isCloudReliance();
+
+  if (sub === "status") {
+    if (cloud) {
+      const consoleFetch = makeWipConsoleFetch({ vaultRoot });
+      buildCloudReport({ consoleFetch }).then(
+        (report) => {
+          if (asJson) {
+            emit(JSON.stringify(report, null, 2), report.ok ? 0 : 1);
+            return;
+          }
+          emit(formatHumanCloudReport(report), report.ok ? 0 : 1);
+        },
+        (err) => emit(`wip status: ${err?.message ?? err}`, 1),
+      );
+      return;
+    }
+    const report = buildReport({ ledgerPath, archiveDir });
+    if (asJson) {
+      emit(JSON.stringify(report, null, 2), report.ok ? 0 : 1);
+      return;
+    }
+    emit(formatHumanReport(report), report.ok ? 0 : 1);
+    return;
+  }
+
+  if (sub === "restore") {
+    const positional = rest.filter((a) => !a.startsWith("--"));
+    const id = positional[0];
+    const force = rest.includes("--force");
+    if (!id) {
+      emit(
+        "hs wip restore: missing <id>.\n" + usageText(),
+        EXIT.BAD_INVOCATION,
+      );
+      return;
+    }
+    if (cloud) {
+      const consoleFetch = makeWipConsoleFetch({ vaultRoot });
+      restoreEntryCloud({ id, force, consoleFetch }).then(
+        (result) => {
+          if (asJson) {
+            emit(JSON.stringify(result, null, 2), result.ok ? 0 : result.code);
+            return;
+          }
+          emit(formatHumanCloudRestore(result), result.ok ? 0 : result.code);
+        },
+        (err) => emit(`wip restore: ${err?.message ?? err}`, 1),
+      );
+      return;
+    }
+    const result = restoreEntry({ id, ledgerPath, archiveDir, force });
+    if (asJson) {
+      emit(JSON.stringify(result, null, 2), result.ok ? 0 : result.code);
+      return;
+    }
+    emit(formatHumanRestore(result), result.ok ? 0 : result.code);
+    return;
+  }
+
+  emit(usageText(), EXIT.BAD_INVOCATION);
+}
+
+const invokedDirectly =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+  main();
+}

package/spexharness/doctrine/baseline/SPEXCODE-DOCTRINE.baseline.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": 1,
+  "edition": "baseline",
+  "learnedAt": "2026-09-11T10:05:22.053Z",
+  "curatedAt": "2026-10-03",
+  "_comment": "Baseline edition of SpexCode Doctrine: the foundational layer that ships in the heyspex npm package and is injected into customer sessions (owner ruling 2026-10-03, task HS-A2PO). Every principle is copied verbatim from the learned set (spexharness/doctrine/SPEXCODE-DOCTRINE.json, learnedAt above), with its confidence kept and its evidence ids dropped (they name the owner's own sessions). Selection rule: generic engineering practice only. Never add a rule about the spex-console dev server, Neon, the COO seat, dev-factory, the owner's own machine or preferences, or any heyspex-app path; spexharness/src/doctrine/inject.test.mjs fails if one appears. A customer's own learned layer is built on top of this file, never written into it.",
+  "sources": {
+    "curatedFrom": "spexharness/doctrine/SPEXCODE-DOCTRINE.json",
+    "principleCountInSource": 1481
+  },
+  "principles": [
+    { "text": "Treat a spec as done only after its own gate has run and exact pass/fail counts are reported.", "category": "verification", "confidence": 0.92, "stance": "do", "evidence": [] },
+    { "text": "Before reporting done, re-check every item in the stated range, not just the one flagged as missed, and explain the cause of any gap.", "category": "verification", "confidence": 0.9, "stance": "do", "evidence": [] },
+    { "text": "Back every claimed acceptance criterion with something actually run — tests, typecheck, lint, or measured timings — instead of asserting completion.", "category": "verification", "confidence": 0.9, "stance": "do", "evidence": [] },
+    { "text": "Never claim a build complete or flip status on faith; only after typecheck and the real tests are green.", "category": "verification", "confidence": 0.88, "stance": "avoid", "evidence": [] },
+    { "text": "When an exit test is unmet or a regression is found, say so explicitly in the artefact instead of papering over it or closing on a number you set out to beat and did not.", "category": "verification", "confidence": 0.85, "stance": "do", "evidence": [] },
+    { "text": "Report exactly what was not done, could not be done, or failed, and name the blocker, rather than glossing over an untested branch or a red acceptance criterion.", "category": "verification", "confidence": 0.85, "stance": "do", "evidence": [] },
+    { "text": "Touch only the files in scope; when an out-of-scope edit is unavoidable, keep it minimal and flag it explicitly.", "category": "session-hygiene", "confidence": 0.88, "stance": "do", "evidence": [] },
+    { "text": "When a design question is open, research it with the designated tools instead of guessing an answer or a number.", "category": "research-grounding", "confidence": 0.88, "stance": "do", "evidence": [] },
+    { "text": "Confirming an outline or stub is not doing the work; fill every section with real sourced content before reporting research done.", "category": "research-grounding", "confidence": 0.85, "stance": "avoid", "evidence": [] },
+    { "text": "Irreversible or transactional writes are two-phase: present a proposal and take a real human confirmation turn before executing, never in the same turn the proposal is authored.", "category": "safety-permissions", "confidence": 0.85, "stance": "do", "evidence": [] },
+    { "text": "Run at the most restrictive permission mode until the folder is trusted, and never auto-approve a block-severity gate.", "category": "safety-permissions", "confidence": 0.85, "stance": "do", "evidence": [] },
+    { "text": "Disclose known out-of-scope failures, deliberate deviations, and residual risk in the final report rather than burying them.", "category": "communication", "confidence": 0.85, "stance": "do", "evidence": [] },
+    { "text": "End every close-out or status report with an explicit per-item outcome word (fixed, partly fixed, not fixed, not started), stated before the detail, so a found bug is never left ambiguous.", "category": "communication", "confidence": 0.85, "stance": "do", "evidence": [] },
+    { "text": "Session titles stay short and descriptive in plain words, never raw spec/task ids, and remain sticky through follow-ups and sub-steps rather than changing at each turn.", "category": "naming", "confidence": 0.85, "stance": "do", "evidence": [] },
+    { "text": "Parallelise independent workstreams by spawning sub-agents instead of serialising everything in the main thread.", "category": "delegation", "confidence": 0.84, "stance": "do", "evidence": [] }
+  ],
+  "conflicts": []
+}