shapeup-sdlc 1.6.2

package/skills/tech-lead/scripts/lib/paths.mjs

@@ -0,0 +1,278 @@
+// paths — the single source of truth for where the harness writes.
+//
+// WHY THIS FILE EXISTS (measured by grepping the shipped tree, not theorized).
+//
+// The two storage roots were hard-coded in ~90 files, in TWO syntaxes that no single search finds:
+//
+//     "docs/shapeup-sdlc/<slug>/scopes/..."            568 string literals
+//     join(cwd, "docs", "shapeup-sdlc", slug, ...)      48 segment-built sites
+//
+// A find/replace over the first set leaves the second silently pointing at the old root. That is
+// the failure mode this project keeps rediscovering: a change that appears complete, produces no
+// error, and is wrong — `lib/is-main.mjs` (a guard duplicated 18 times, inert under a symlink) and
+// `lib/argv.mjs` (`rNaN-a1.json` written with exit 0) are the same defect at different layers. The
+// remedy each time is to give the duplicated thing one home and add a test that no one may bypass
+// it (`tests/structural/45-paths.mjs`, mirroring #11a).
+//
+// It also removes a live ambiguity. `gate-answers.mjs` resolved three candidate paths and
+// `sandbox-guard.mjs` built a fourth independently; the same filename meant "my personal lane" at
+// one path and "team policy" at another, auto-discovered with no flag (ADR-0001 §Context).
+//
+// TIER DISCIPLINE, restated here because this is where it becomes mechanical:
+//   SHARED (committed) — prose a teammate reads: shaping, spec, contracts, requirements, report.
+//   LOCAL (gitignored) — run state, envelopes, verification artifacts, machine policy.
+// See docs/design/adr/0001-consumer-file-organization.md.
+//
+// Zero dependencies. Pure — every function takes `cwd` and returns a path; nothing here touches
+// the filesystem, so importing this module can never have a side effect.
+
+import { join } from "node:path";
+
+// ---------------------------------------------------------------------------
+// The two roots. Renaming a root is these two lines plus migration 0006.
+// ---------------------------------------------------------------------------
+
+// Both roots are POSIX strings, deliberately. They are used two ways — fed to `join()` (which
+// normalises separators on Windows) and interpolated into SUBSTRATE GLOBS, which are matched
+// against repo-relative POSIX paths by `sandbox-guard`. A backslash reaching a glob would silently
+// stop matching, so the canonical form is the one the globs need.
+
+/**
+ * Committed tier — the authored deliverable a teammate gets on `git pull`.
+ *
+ * Was `docs/shapeup-sdlc`. Moved out of `docs/` because many projects publish that directory
+ * through a static-site generator, which either publishes the spec tree by accident or fails the
+ * site build on it (ADR-0001).
+ */
+export const SHARED = "shapeup";
+
+/** Gitignored tier — run state for the machine that invoked the harness. Was `.shapeup-sdlc`. */
+export const LOCAL = ".shapeup";
+
+/**
+ * The pre-ADR-0001 roots. Migration `0006` moves a project from these to the pair above;
+ * `bin/init.mjs` writes ignore rules covering both so a half-migrated checkout cannot commit a
+ * run trace. Nothing else should read these.
+ */
+export const LEGACY = { shared: "docs/shapeup-sdlc", local: ".shapeup-sdlc" };
+
+// ---------------------------------------------------------------------------
+// Roots
+// ---------------------------------------------------------------------------
+
+/**
+ * The committed tier root.
+ * @param {string} cwd - Project root.
+ * @returns {string} `<cwd>/shapeup`.
+ */
+export const sharedDir = (cwd) => join(cwd, SHARED);
+
+/**
+ * The gitignored tier root.
+ * @param {string} cwd - Project root.
+ * @returns {string} `<cwd>/.shapeup`.
+ */
+export const localDir = (cwd) => join(cwd, LOCAL);
+
+/**
+ * A feature's committed root.
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {string} `<cwd>/shapeup/<slug>`.
+ */
+export const sharedRoot = (cwd, slug) => join(cwd, SHARED, slug);
+
+/**
+ * A feature's run-trace root.
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {string} `<cwd>/.shapeup/<slug>`.
+ */
+export const localRoot = (cwd, slug) => join(cwd, LOCAL, slug);
+
+// ---------------------------------------------------------------------------
+// SHARED — the deliverable
+// ---------------------------------------------------------------------------
+
+/** The committed spec tree — the evaluator's grading truth. */
+export const specDir = (cwd, slug) => join(sharedRoot(cwd, slug), "spec");
+/** Use-case directory inside the spec tree. */
+export const usecasesDir = (cwd, slug) => join(specDir(cwd, slug), "usecases");
+/** Shaping artifacts — pitch, framing, breadboard, baseline, glossary. */
+export const shapingDir = (cwd, slug) => join(sharedRoot(cwd, slug), "shaping");
+// The three contracts are markdown on disk and JSON on the wire (ADR-0001) — see
+// `lib/contract-md.mjs`. `readContract()` accepts either extension, so a project mid-migration
+// keeps working; these builders name the form the harness WRITES.
+
+/** Scope contracts, one markdown file per vertical slice. */
+export const scopesDir = (cwd, slug) => join(sharedRoot(cwd, slug), "scopes");
+/** One scope contract by id. */
+export const scopeContract = (cwd, slug, id) => join(scopesDir(cwd, slug), `${id}.md`);
+/** The wiring map — engine → seam → entry-point call site → affordance. */
+export const wiringMap = (cwd, slug) => join(sharedRoot(cwd, slug), "wiring-map.md");
+/** Archetype + entry_point; gates the reachability arm of trace-lint. */
+export const projectProfile = (cwd, slug) => join(sharedRoot(cwd, slug), "project-profile.md");
+/** The REQ clause registry that covers-closure checks against. */
+export const requirements = (cwd, slug) => join(sharedRoot(cwd, slug), "requirements.md");
+/** Hill shards — mechanical phase per scope. */
+export const hillDir = (cwd, slug) => join(sharedRoot(cwd, slug), "hill");
+/** The frozen ship report, written once at GATE L4. */
+export const report = (cwd, slug) => join(sharedRoot(cwd, slug), "REPORT.md");
+/** Team-shared coaching rules, read back by the three coachable workers. */
+export const knowledgeBaseDir = (cwd) => join(sharedDir(cwd), "knowledge-base");
+/** One worker's coaching file. */
+export const knowledgeBase = (cwd, skill) => join(knowledgeBaseDir(cwd), `${skill}.md`);
+/** Migration bookkeeping — committed by necessity (ADR-0001 exception 3). */
+export const harnessVersion = (cwd) => join(sharedDir(cwd), ".harness-version");
+/** Applied-migration record — committed by necessity (ADR-0001 exception 3). */
+export const harnessMigrations = (cwd) => join(sharedDir(cwd), ".harness-migrations");
+
+// ---------------------------------------------------------------------------
+// LOCAL — run state
+// ---------------------------------------------------------------------------
+
+/** The run receipt — the mechanical fact that a run started (GATE L0.1). */
+export const receipt = (cwd, slug) => join(localRoot(cwd, slug), "receipt.json");
+/** The intake, verbatim, next to its digest in the receipt. */
+export const intake = (cwd, slug) => join(localRoot(cwd, slug), "intake.md");
+/** The run ledger — rounds, decisions, status frontmatter. */
+export const harnessRun = (cwd, slug) => join(localRoot(cwd, slug), "harness-run.md");
+/** File-derived mid-run digest, frozen before compaction. */
+export const runSnapshot = (cwd, slug) => join(localRoot(cwd, slug), "run-snapshot.json");
+/** The task board directory. */
+export const tasksDir = (cwd, slug) => join(localRoot(cwd, slug), "tasks");
+/** The board index. */
+export const boardIndex = (cwd, slug) => join(tasksDir(cwd, slug), "_index.md");
+/** Compiled WorkOrders. */
+export const ordersDir = (cwd, slug) => join(localRoot(cwd, slug), "orders");
+/** Returned WorkResults. */
+export const resultsDir = (cwd, slug) => join(localRoot(cwd, slug), "results");
+/** T0 verification artifacts. */
+export const t0Dir = (cwd, slug) => join(localRoot(cwd, slug), "t0");
+/** Immutable per-attempt verdict artifacts the evaluator must cite. */
+export const verdictsDir = (cwd, slug) => join(t0Dir(cwd, slug), "verdicts");
+/** The append-only trial ledger the ratchet reduces over. */
+export const trials = (cwd, slug) => join(t0Dir(cwd, slug), "trials.jsonl");
+/** Finished-scope fixture registry for the seesaw regression check. */
+export const seesawRegistry = (cwd, slug) => join(localRoot(cwd, slug), "seesaw", "registry.json");
+/** Evaluator output — report, evidence, verdict ledger. */
+export const evaluationDir = (cwd, slug) => join(localRoot(cwd, slug), "evaluation");
+/** QA hunt output. */
+export const qaDir = (cwd, slug) => join(localRoot(cwd, slug), "qa");
+/** Scout recon — code-surface map, spikes, discovered seed. */
+export const orientDir = (cwd, slug) => join(localRoot(cwd, slug), "orient");
+/** Time-boxed spike workspace. */
+export const spikesDir = (cwd, slug) => join(localRoot(cwd, slug), "spikes");
+/** Covers-closure + reachability run trace. */
+export const traceDir = (cwd, slug) => join(localRoot(cwd, slug), "trace");
+/** The discovered-task ledger every discovery flow appends to. */
+export const discoveryLedger = (cwd, slug) => join(localRoot(cwd, slug), "discovery", "ledger.md");
+/** Queued worker escalations awaiting adjudication. */
+export const escalatesDir = (cwd, slug) => join(localRoot(cwd, slug), "escalates");
+/**
+ * Adjudicated decisions, read back by `compile-order` as binding precedent.
+ *
+ * LOCAL since ADR-0001. It was committed, and it is appended to DURING a build round — so a run
+ * left the working tree dirty in the deliverable tier while it was still building. Its
+ * conclusions reach the team in `REPORT.md` at GATE L4 instead, frozen once.
+ */
+export const roundLedger = (cwd, slug) => join(localRoot(cwd, slug), "round-ledger.md");
+
+/**
+ * Spec WORKING NOTES — analysis that informed the contract but is not the contract.
+ *
+ * `synthesis.md`, `assess-report.md`, `feedback.md`, `api-feasibility.md`, `integration.md`. The
+ * committed `spec/` keeps only what the evaluator grades against and a reviewer needs (ADR-0001
+ * "contract vs working artifact").
+ */
+export const workingDir = (cwd, slug) => join(localRoot(cwd, slug), "working");
+
+// --- checkout-wide ---------------------------------------------------------
+
+/** The pointer the sandbox guard reads to answer "which scope is checked out?". */
+export const activeScope = (cwd) => join(localDir(cwd), "active-scope");
+/** Hook receipts — one row per evaluation, so `allow` carries evidence. */
+export const decisions = (cwd) => join(localDir(cwd), "decisions.jsonl");
+/** Human-authored safety escape hatch. LOCAL so no PR can widen another machine's envelope. */
+export const safetyOverrides = (cwd) => join(localDir(cwd), "safety-overrides.json");
+/**
+ * Telemetry shards.
+ *
+ * LOCAL since ADR-0001. Committed, they put `process.env.HOSTNAME` — a person's laptop name —
+ * into the repository, and append-only JSONL in git only grows. The cost, stated plainly: with
+ * these local, `stats.mjs` becomes a personal tool and "is the KB flywheel working across the
+ * team?" is no longer answerable from the repo.
+ */
+export const metricsDir = (cwd) => join(localDir(cwd), "metrics");
+/** This machine's telemetry shard. */
+export const metricsShard = (cwd, id = process.env.HOSTNAME || "local") =>
+  join(metricsDir(cwd), `${id}.jsonl`);
+/** Archived pitches. */
+export const pitchArchiveDir = (cwd) => join(localDir(cwd), "pitch-archive");
+
+/**
+ * Gate answer sets, in resolution order (first hit wins).
+ *
+ * ONE TIER ONLY, since ADR-0001. There used to be a third candidate — a COMMITTED
+ * `gate-answers.json`, auto-discovered with no flag — so a file with `preset: ci` pre-approved
+ * GATE L4 ship sign-off for everyone who pulled the repo, and the same filename meant "my
+ * personal lane" at one path and "team policy" at another. Consent is now per-machine by
+ * construction: no committed file can cross a gate on another person's behalf.
+ *
+ * @param {string} cwd - Project root.
+ * @param {(string|null)} [slug] - Feature slug; adds the per-run candidate when given.
+ * @returns {string[]} Candidate paths, most specific first.
+ */
+export const gateAnswerCandidates = (cwd, slug = null) => [
+  ...(slug ? [join(localRoot(cwd, slug), "gate-answers.json")] : []),
+  join(localDir(cwd), "gate-answers.json"),
+];
+
+// ---------------------------------------------------------------------------
+// Relative forms — for messages, receipts and anything a human reads
+// ---------------------------------------------------------------------------
+
+/**
+ * A run-trace path relative to the project root, for display.
+ * @param {string} slug - Feature slug.
+ * @param {...string} parts - Path segments under the feature's local root.
+ * @returns {string} e.g. `.shapeup/checkout/t0/verdicts`.
+ */
+export const relLocal = (slug, ...parts) => join(LOCAL, slug, ...parts);
+
+/**
+ * A deliverable path relative to the project root, for display.
+ * @param {string} slug - Feature slug.
+ * @param {...string} parts - Path segments under the feature's shared root.
+ * @returns {string} e.g. `shapeup/checkout/spec`.
+ */
+export const relShared = (slug, ...parts) => join(SHARED, slug, ...parts);
+
+// ---------------------------------------------------------------------------
+// Glob forms — substrate whitelists, matched against repo-relative POSIX paths
+// ---------------------------------------------------------------------------
+
+/**
+ * A run-trace glob. Always POSIX-separated: `sandbox-guard` matches these against
+ * `path.relative()` output normalised to forward slashes, so a `join()` here would stop matching
+ * on Windows without any error to notice.
+ * @param {string} slug - Feature slug.
+ * @param {...string} parts - Glob segments under the feature's local root.
+ * @returns {string} e.g. `.shapeup-sdlc/checkout/tasks/**`.
+ */
+export const globLocal = (slug, ...parts) => [LOCAL, slug, ...parts].join("/");
+
+/**
+ * A deliverable glob, POSIX-separated for the same reason as {@link globLocal}.
+ * @param {string} slug - Feature slug.
+ * @param {...string} parts - Glob segments under the feature's shared root.
+ * @returns {string} e.g. `docs/shapeup-sdlc/checkout/scopes/*.json`.
+ */
+export const globShared = (slug, ...parts) => [SHARED, slug, ...parts].join("/");
+
+/**
+ * The coaching file a coachable worker reads, as a repo-relative path for the WorkOrder payload.
+ * @param {string} skill - Worker name (task-executor | ba-pitch-analyzer | qa-edge-hunter).
+ * @returns {string} e.g. `docs/shapeup-sdlc/knowledge-base/task-executor.md`.
+ */
+export const relKnowledgeBase = (skill) => [SHARED, "knowledge-base", `${skill}.md`].join("/");

package/skills/tech-lead/scripts/lib/ratchet-tree.mjs

@@ -0,0 +1,112 @@
+// ratchet-tree — `keep(commit)` and `revert(commit)` for the T0 attempt loop.
+//
+// WHY THIS FILE EXISTS.
+//
+// The attempt loop branched a red T0 two ways, and only one of them reverted anything:
+//
+//   • a SEESAW regression (a previously-finished scope broke) → `git stash push -u`;
+//   • a red on the scope's OWN fixtures → "loop to the next attempt", and no revert at all.
+//
+// So the failing tree stayed on the branch, and attempt N+1's fresh, zero-memory subagent began
+// from code it did not write, cannot see the history of, and is told about only through error
+// strings. The paper's `revert(commit)` is the MORE COMMON branch, and it was the absent one.
+//
+// Under a ratchet there is one rule for both (see `t0-verify.mjs` → `decideStatus`): keep the tree
+// when the score strictly improved, restore the last kept tree when it did not.
+//
+// NO COMMITS ON THE BRANCH UNDER TEST. The harness's standing convention is that it never writes
+// commits to the user's branch, so the snapshot is a `git stash create` object published under a
+// SHADOW REF — `refs/shapeup/<scope_id>/kept` — which is invisible to `git log`, `git status` and
+// every branch operation, and is reachable for `git restore` and for forensics afterwards.
+//
+// NON-REGRESSION (plan §7). Every operation here is best-effort: outside a git work tree, with no
+// `git` on PATH, or with no snapshot yet taken, the functions report `{ ok: false, reason }` and
+// the caller proceeds exactly as it does today. A ratchet that can break a build by failing to
+// take a snapshot would get the whole mechanism disabled, which costs more than it saves.
+
+import { spawnSync } from "node:child_process";
+
+/**
+ * Run one git subcommand, capturing its outcome. Never throws.
+ * @param {string[]} argv - Git arguments (without the leading "git").
+ * @param {string} cwd - Repository working directory.
+ * @returns {{ok:boolean, stdout:string, stderr:string, status:(number|null)}} Trimmed output and
+ *   the exit status; `ok` is true only on status 0.
+ */
+function git(argv, cwd) {
+  const r = spawnSync("git", argv, { cwd, encoding: "utf8", timeout: 60_000 });
+  return {
+    ok: r.status === 0,
+    stdout: (r.stdout || "").trim(),
+    stderr: (r.stderr || "").trim(),
+    status: r.status ?? null,
+  };
+}
+
+/**
+ * The shadow ref a scope's kept tree is published under.
+ * @param {string} scopeId - Scope id (e.g. "SC-02").
+ * @returns {string} The full ref name, with anything ref-unsafe in the id replaced by "-".
+ */
+export function keptRef(scopeId) {
+  return `refs/shapeup/${String(scopeId || "unscoped").replace(/[^\w.-]/g, "-")}/kept`;
+}
+
+/**
+ * Is `cwd` inside a git work tree with git available?
+ * @param {string} cwd - Directory to test.
+ * @returns {boolean} True when git can answer for this directory.
+ */
+export function isRepo(cwd) {
+  return git(["rev-parse", "--is-inside-work-tree"], cwd).stdout === "true";
+}
+
+/**
+ * `keep` — publish the current working tree (including untracked files) as this scope's kept tree.
+ *
+ * `git stash create` builds the stash commit WITHOUT touching the index, the working tree, or the
+ * stash list; `update-ref` then points the shadow ref at it. Nothing the user can see changes.
+ *
+ * @param {string} scopeId - Scope id the snapshot belongs to.
+ * @param {string} cwd - Repository working directory.
+ * @returns {{ok:boolean, ref?:string, sha?:string, reason?:string}} `ok:true` with the ref and the
+ *   snapshot commit sha; `ok:false` with a reason when git is unavailable, the directory is not a
+ *   repo, or there was nothing to snapshot (a clean tree — the caller has nothing to restore to
+ *   that HEAD does not already provide).
+ */
+export function snapshot(scopeId, cwd) {
+  if (!isRepo(cwd)) return { ok: false, reason: "not a git work tree" };
+  const created = git(["stash", "create", `shapeup: kept tree for ${scopeId}`], cwd);
+  if (!created.ok) return { ok: false, reason: created.stderr || "git stash create failed" };
+  // An empty stdout means the tree is clean relative to HEAD — a legitimate state, not an error.
+  const sha = created.stdout || git(["rev-parse", "HEAD"], cwd).stdout;
+  if (!sha) return { ok: false, reason: "no commit to snapshot" };
+  const ref = keptRef(scopeId);
+  const updated = git(["update-ref", ref, sha], cwd);
+  if (!updated.ok) return { ok: false, reason: updated.stderr || "git update-ref failed" };
+  return { ok: true, ref, sha };
+}
+
+/**
+ * `revert` — restore the working tree from this scope's last kept snapshot.
+ *
+ * Deliberately `git restore --source=<ref> --worktree -- .`: it rewrites tracked files back to the
+ * kept state and leaves the index and HEAD alone. It does NOT delete files created since the
+ * snapshot — removing a file the harness cannot prove it created is not a revert, it is data loss,
+ * and the attempt's own fixtures are what decide whether the leftover matters.
+ *
+ * @param {string} scopeId - Scope id whose kept tree should be restored.
+ * @param {string} cwd - Repository working directory.
+ * @returns {{ok:boolean, ref?:string, sha?:string, reason?:string}} `ok:true` when the tree was
+ *   restored; `ok:false` with a reason when there is no snapshot yet (the first trial, by
+ *   definition) or git refused.
+ */
+export function restore(scopeId, cwd) {
+  if (!isRepo(cwd)) return { ok: false, reason: "not a git work tree" };
+  const ref = keptRef(scopeId);
+  const resolved = git(["rev-parse", "--verify", "--quiet", ref], cwd);
+  if (!resolved.ok || !resolved.stdout) return { ok: false, reason: `no snapshot at ${ref}` };
+  const restored = git(["restore", `--source=${resolved.stdout}`, "--worktree", "--", "."], cwd);
+  if (!restored.ok) return { ok: false, reason: restored.stderr || "git restore failed" };
+  return { ok: true, ref, sha: resolved.stdout };
+}

package/skills/tech-lead/scripts/run-snapshot.mjs

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+// Run snapshot — the compaction-resilience derivation (v1.2, absorb-audit P4).
+//
+// Derives a RunSnapshot (domain.schema.json#/$defs/RunSnapshot) from FILES ONLY: the
+// active-scope pointer, harness-run.md frontmatter, board task frontmatter, t0/verdicts
+// filenames, and the orders/ vs results/ diff. Never from conversation memory — that is the
+// point: after a context compaction the summary may be lossy, but the files are not. The
+// danger this record exists to prevent is the orchestrator continuing on a degraded summary:
+// re-dispatching an already-ingested order, miscounting attempts (breaking the inner circuit
+// breaker), or "remembering" a hill phase instead of re-deriving it.
+//
+// Consumers (both in hooks/): compact-snapshot.mjs persists it before compaction (audit
+// anchor); session-rehydrate.mjs re-derives it fresh after compaction and injects the
+// rehydrate_hint as additionalContext.
+//
+// Output is self-validated against the registry before it is emitted — the same
+// refuse-to-emit-schema-drift discipline as compile-order.mjs.
+//
+// Usage: node run-snapshot.mjs [--cwd <dir>] [--format json|text] [--write]
+//   exit 0 with empty stdout when no run is active (fail-open), 1 on schema drift.
+
+import { readFileSync, readdirSync, existsSync, writeFileSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { validate } from "./validate-envelope.mjs";
+import { isMain } from "./lib/is-main.mjs";
+import { runArgs } from "./lib/argv.mjs";
+import { localDir, localRoot, relLocal, globLocal, runSnapshot as runSnapshotPath } from "./lib/paths.mjs";
+
+/**
+ * Read a JSON file, tolerating absence/parse errors.
+ * @param {string} p - Path to the JSON file.
+ * @returns {(*|null)} The parsed value, or null when the file is missing or not valid JSON.
+ */
+function readJSON(p) {
+  try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; }
+}
+
+/**
+ * Parse a Markdown frontmatter block into a flat scalar map.
+ * @param {string} text - Full document text ("" / null tolerated).
+ * @returns {Object<string,string>} Top-level `key: value` pairs (quotes stripped); {} when absent.
+ */
+function frontmatter(text) {
+  const m = /^---\n([\s\S]*?)\n---/.exec(text || "");
+  if (!m) return {};
+  const fm = {};
+  for (const line of m[1].split("\n")) {
+    const kv = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(line.trim());
+    if (kv) fm[kv[1]] = kv[2].replace(/^['"]|['"]$/g, "");
+  }
+  return fm;
+}
+
+const MID_RUN = new Set(["orienting", "mapping", "building", "evaluating"]);
+
+/**
+ * Is this run still open, per its own ledger? Fails CLOSED — a missing or unreadable
+ * `harness-run.md` cannot be evidence that a run is in progress.
+ * @param {string} root - The `.shapeup` directory.
+ * @param {string} slug - Run slug (a child directory of root).
+ * @returns {boolean} True when the run's frontmatter status is one of MID_RUN.
+ */
+function isMidRun(root, slug) {
+  const runPath = join(root, slug, "harness-run.md");
+  if (!existsSync(runPath)) return false;
+  try {
+    return MID_RUN.has(frontmatter(readFileSync(runPath, "utf8")).status);
+  } catch {
+    return false; // unreadable ledger → cannot claim the run is open
+  }
+}
+
+/**
+ * Find the active run from files alone — the active-scope pointer, else a mid-run harness-run.md.
+ * Either way the run must be OPEN per its own ledger; a pointer alone is not enough.
+ * @param {string} cwd - Working-directory root.
+ * @returns {({slug:string, scope_id?:string}|null)} The active run's slug (and scope when pointed
+ *   at one), or null when no run is in progress.
+ */
+function findRun(cwd) {
+  const root = localDir(cwd);
+  if (!existsSync(root)) return null;
+
+  // The pointer names the run the sandbox guard is scoping, NOT necessarily a run still open.
+  // `.shapeup/active-scope` has existed since v0.3 and nothing has ever cleared it, because
+  // its original reader (sandbox-guard) fails OPEN on a stale one — a pointer at a finished run
+  // simply stops matching any substrate. session-rehydrate is the opposite kind of reader: it
+  // turns a pointer into "a run is ALREADY OPEN in this workspace … do NOT open a new run", and
+  // it now fires on `startup`/`clear`. Following the pointer without checking the run's status
+  // therefore made every cold session in every repo that had EVER run the harness open with a
+  // false claim about its own workspace — including sessions with nothing to do with the harness,
+  // and including the case where the user's next act is to open the run the injection forbids.
+  // This function's own contract (and session-rehydrate's header) always said "a run only for an
+  // active-scope pointer or a mid-run harness-run.md"; the status check is what makes that true.
+  const pointer = readJSON(join(root, "active-scope"));
+  if (pointer?.slug && isMidRun(root, pointer.slug)) {
+    return { slug: pointer.slug, scope_id: pointer.scope_id };
+  }
+
+  for (const entry of readdirSync(root)) {
+    if (isMidRun(root, entry)) return { slug: entry };
+  }
+  return null;
+}
+
+/**
+ * Derive a RunSnapshot for the active run from FILES ONLY (never conversation memory).
+ * @param {string} cwd - Working-directory root.
+ * @returns {(object|null)} A RunSnapshot (domain.schema.json#/$defs/RunSnapshot): slug, optional
+ *   scope_id/status/rounds, latest T0 verdict, board done/total + unfinished, open escalates,
+ *   dispatched-not-ingested `pending_orders`, and a human `rehydrate_hint`. null when no run is active.
+ */
+export function deriveSnapshot(cwd) {
+  const run = findRun(cwd);
+  if (!run) return null;
+  const root = localRoot(cwd, run.slug);
+
+  const snapshot = {
+    schema_version: 1,
+    at: new Date().toISOString(),
+    slug: run.slug,
+  };
+  if (run.scope_id) snapshot.scope_id = run.scope_id;
+
+  const runPath = join(root, "harness-run.md");
+  if (existsSync(runPath)) {
+    try {
+      const fm = frontmatter(readFileSync(runPath, "utf8"));
+      if (MID_RUN.has(fm.status) || ["shipped", "escalated"].includes(fm.status)) snapshot.status = fm.status;
+      if (/^\d+$/.test(fm.rounds_used || "")) snapshot.rounds_used = Number(fm.rounds_used);
+      if (/^\d+$/.test(fm.max_rounds || "")) snapshot.max_rounds = Number(fm.max_rounds);
+      if (fm.auto_level) snapshot.auto_level = fm.auto_level;
+      if (fm.spec_folder) snapshot.spec_folder = fm.spec_folder;
+    } catch { /* run ledger unreadable → snapshot stays partial; the files still win */ }
+  }
+
+  const verdictsDir = join(root, "t0", "verdicts");
+  if (existsSync(verdictsDir)) {
+    let latest = null;
+    for (const f of readdirSync(verdictsDir)) {
+      const m = /^r(\d+)-a(\d+)\.json$/.exec(f);
+      if (!m) continue;
+      const round = Number(m[1]), attempt = Number(m[2]);
+      if (!latest || round > latest.round || (round === latest.round && attempt > latest.attempt)) {
+        latest = { round, attempt, file: f };
+      }
+    }
+    if (latest) {
+      snapshot.round = latest.round;
+      snapshot.attempt = latest.attempt;
+      const verdict = readJSON(join(verdictsDir, latest.file));
+      if (verdict?.overall === "green" || verdict?.overall === "red") {
+        snapshot.latest_t0 = {
+          path: relLocal(run.slug, "t0", "verdicts", latest.file),
+          overall: verdict.overall,
+          round: latest.round,
+          attempt: latest.attempt,
+        };
+      }
+    }
+  }
+  if (snapshot.round === undefined && snapshot.rounds_used !== undefined) snapshot.round = snapshot.rounds_used;
+
+  const tasksDir = join(root, "tasks");
+  if (existsSync(tasksDir)) {
+    const board = { total: 0, done: 0, unfinished: [] };
+    for (const f of readdirSync(tasksDir)) {
+      if (!/^TASK-.*\.md$/.test(f)) continue;
+      board.total++;
+      try {
+        const fm = frontmatter(readFileSync(join(tasksDir, f), "utf8"));
+        if (fm.status === "done") board.done++;
+        else if (board.unfinished.length < 10) board.unfinished.push(fm.id || f.replace(/\.md$/, ""));
+      } catch { /* unreadable task counts as unfinished-unknown; skip naming it */ }
+    }
+    if (board.total > 0) snapshot.board = board;
+  }
+
+  const escDir = join(root, "escalates");
+  snapshot.open_escalates = existsSync(escDir)
+    ? readdirSync(escDir).filter((f) => f.endsWith(".json")).length
+    : 0;
+
+  const ordersDir = join(root, "orders");
+  const resultsDir = join(root, "results");
+  const results = new Set(existsSync(resultsDir) ? readdirSync(resultsDir) : []);
+  snapshot.pending_orders = existsSync(ordersDir)
+    ? readdirSync(ordersDir).filter((f) => f.endsWith(".json") && !results.has(f))
+    : [];
+
+  snapshot.rehydrate_hint =
+    `mid-run harness state: slug "${snapshot.slug}"` +
+    (snapshot.scope_id ? `, scope "${snapshot.scope_id}"` : "") +
+    (snapshot.round !== undefined ? `, round ${snapshot.round}` : "") +
+    (snapshot.attempt !== undefined ? `, attempt ${snapshot.attempt}` : "") +
+    (snapshot.status ? `, status ${snapshot.status}` : "") +
+    (snapshot.board ? `, board ${snapshot.board.done}/${snapshot.board.total} done` : "") +
+    (snapshot.latest_t0 ? `, latest T0 ${snapshot.latest_t0.overall}` : "") +
+    (snapshot.pending_orders.length ? `, ${snapshot.pending_orders.length} dispatched-not-ingested order(s): ${snapshot.pending_orders.join(", ")}` : "") +
+    `. Re-read ${globLocal(snapshot.slug, "harness-run.md")} and the board before continuing — ` +
+    `trust the files, not the conversation summary. Never re-dispatch an order that already has a result; ` +
+    `re-derive round/attempt/hill from the files, never from memory.`;
+
+  return snapshot;
+}
+
+/**
+ * @param {string} cwd - Working-directory root.
+ * @param {string} slug - Feature slug.
+ * @returns {string} The LOCAL run-trace path `.shapeup/<slug>/run-snapshot.json`.
+ */
+export function snapshotPath(cwd, slug) {
+  return runSnapshotPath(cwd, slug);
+}
+
+/**
+ * Validate then persist a snapshot to its LOCAL run-trace home.
+ * @param {string} cwd - Working-directory root.
+ * @param {object} snapshot - The RunSnapshot to persist (its `slug` names the path).
+ * @returns {void} Side effect: writes the snapshot JSON.
+ * @throws {Error} If the snapshot drifts from domain.schema.json#/$defs/RunSnapshot.
+ */
+export function writeSnapshot(cwd, snapshot) {
+  assertValid(snapshot);
+  writeFileSync(snapshotPath(cwd, snapshot.slug), JSON.stringify(snapshot, null, 2) + "\n");
+}
+
+/**
+ * Assert a snapshot conforms to its registry definition.
+ * @param {object} snapshot - The RunSnapshot to check.
+ * @returns {void}
+ * @throws {Error} If it fails domain.schema.json#/$defs/RunSnapshot (message lists each error).
+ */
+function assertValid(snapshot) {
+  const { valid, errors } = validate(snapshot, { $ref: "domain.schema.json#/$defs/RunSnapshot" });
+  if (!valid) {
+    throw new Error(`run-snapshot drifted from domain.schema.json#/$defs/RunSnapshot:\n  ${errors.join("\n  ")}`);
+  }
+}
+
+// --- CLI -----------------------------------------------------------------------
+
+/** The typed argv contract (see `./lib/argv.mjs`). */
+export const ARGV_SPEC = {
+  usage: "run-snapshot.mjs [--cwd <dir>] [--format json|text] [--write]",
+  _: { arity: 0, max: 0, name: "(no positional operands)" },
+  cwd: { type: "path" },
+  format: { type: "enum", values: ["json", "text"], default: "json" },
+  write: { type: "flag" },
+};
+
+const isMainModule = isMain(import.meta.url);
+if (isMainModule) {
+  const args = runArgs(ARGV_SPEC);
+  const cwd = resolve(args.cwd || process.cwd());
+  const format = args.format;
+
+  const snapshot = deriveSnapshot(cwd);
+  if (!snapshot) process.exit(0); // no active run → nothing to say (fail-open)
+
+  try {
+    assertValid(snapshot);
+    if (args.write) writeSnapshot(cwd, snapshot);
+  } catch (e) {
+    console.error(`  ✗ ${e.message}`);
+    process.exit(1);
+  }
+  console.log(format === "text" ? snapshot.rehydrate_hint : JSON.stringify(snapshot, null, 2));
+}