shapeup-sdlc 3.18.2 → 4.0.0

package/kernel/reduce/snapshot.mjs

@@ -1,291 +0,0 @@
-#!/usr/bin/env node
-// Run snapshot — the compaction-resilience derivation (v1.2).
-//
-// 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: `--write` persists it as an audit anchor; `--format text` prints the rehydrate_hint
-// for whoever asks. Nothing fires it automatically — the orchestrator re-derives after a context
-// loss by running it, which answers whenever the question is asked rather than only at the two
-// moments a lifecycle hook happened to see.
-//
-// Output is self-validated against the registry before it is emitted — the same
-// refuse-to-emit-schema-drift discipline as `harness compile`.
-//
-// Usage: node `harness reduce snapshot` [--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 "../verify/envelope.mjs";
-import { runArgs } from "../lib/argv.mjs";
-import { localDir, localRoot, relLocal, globLocal, runSnapshot as runSnapshotPath } from "../lib/paths.mjs";
-import { deriveRounds } from "../probe/rounds.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. `harness reduce graph --subgraph run` 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 `harness reduce graph --subgraph run`'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"));
-      // The terminal allowlist mirrors kernel/probe/resume.mjs's TERMINAL_STATUSES, not just the two
-      // members it used to carry — a schema/allowlist that disagrees with RUN_STATUSES is silent on
-      // both sides here (findRun only ever surfaces a MID_RUN run today, so this whole branch is
-      // unreachable in practice), but is exactly the divergence class this file's own imports exist
-      // to close elsewhere (deriveRounds, above). "aborted" is a real RUN_STATUSES member.
-      if (MID_RUN.has(fm.status) || ["shipped", "escalated", "aborted"].includes(fm.status)) snapshot.status = fm.status;
-      // MIGRATED to the same mechanical derivation `reduce ship` and `report export` already use
-      // (kernel/probe/rounds.mjs), rather than reading `harness-run.md`'s `rounds_used` literally.
-      // That frontmatter line is written ONCE, as 0, by `init run`, and nothing in the round loop
-      // ever rewrites it — so the third mechanical reader of "how many rounds did this run build"
-      // was the one still reporting the pre-fix number. Measured on a two-round, no-EVAL fixture:
-      // this line alone reported `rounds_used: 0` beside its own `round: 2` a few lines below,
-      // the exact disagreement `deriveRounds` exists to close. `fm.rounds_used` still travels in as
-      // the fallback for a run neither this fix nor deriveRounds can see evidence for (a `--tiny`
-      // lane, or a run from before any of these artifacts existed).
-      const derivedRounds = deriveRounds(cwd, run.slug, fm.rounds_used);
-      if (Number.isFinite(Number(derivedRounds.rounds_used))) snapshot.rounds_used = Number(derivedRounds.rounds_used);
-      // Kept as its OWN field, never folded into rounds_used — a round built is not a round judged,
-      // and collapsing the two into one number is exactly the ambiguity this migration removes.
-      // null (no EVAL result on disk yet) is a real answer and is not written at all, the same
-      // optional-field discipline every other snapshot field here follows.
-      if (Number.isFinite(derivedRounds.rounds_judged)) snapshot.rounds_judged = derivedRounds.rounds_judged;
-      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 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: "harness.mjs reduce snapshot [--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" },
-};
-
-/**
- * Derive the file-based run snapshot, and optionally freeze it to disk.
- *
- * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
- * @returns {(Promise<void>|void)} Settles when the subcommand has written its output; most paths
- *   call `process.exit()` with the subcommand's documented code rather than returning.
- */
-export async function cli(rawArgv) {
-  const args = runArgs(ARGV_SPEC, rawArgv);
-  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));
-}

package/kernel/reduce/verdict.mjs

@@ -1,172 +0,0 @@
-#!/usr/bin/env node
-// Verdict-ledger reference implementation — spec-evaluator's own skill-local
-// reference impl (ships beside SKILL.md; not invoked at runtime).
-//
-// The `spec-evaluator` skill performs verdict re-probe / confidence / flip-detection as a
-// self-contained procedure (`references/verdict-ledger.md`) using its own file tools — it does NOT
-// call this file. This is the executable proof that the documented grammar is well-defined and
-// actually discriminates an unstable judge from a stable one, the same way oracles/*
-// prove the probing grammar. Structural test #15 exercises it.
-//
-// Ledger line shape (one per criterion per run), see verdict-ledger.md:
-//   { run, task, dimension, criterion, verdict:"PASS"|"FAIL", confidence, reprobed, flip, evidence, at }
-//
-// Library use:
-//   import { reconcile, detectFlips, stability } from "kernel/reduce/verdict.mjs";
-//   const { records, summary } = reconcile(priorLines, currentRecords);
-
-// Most recent prior line for a (dimension, criterion), by highest run number.
-import { runArgs } from "../lib/argv.mjs";
-
-/**
- * Find the most recent prior ledger line for a record's (dimension, criterion), by highest run.
- * @param {Array<{dimension:string, criterion:string, run:number, verdict:string}>} priorLines - Prior lines.
- * @param {{dimension:string, criterion:string}} rec - The record to match.
- * @returns {(object|null)} The highest-run matching prior line, or null when none exists.
- */
-function priorFor(priorLines, rec) {
-  let best = null;
-  for (const p of priorLines) {
-    if (p.criterion !== rec.criterion || p.dimension !== rec.dimension) continue;
-    if (best === null || p.run > best.run) best = p;
-  }
-  return best;
-}
-
-// Reconcile this run's records against the prior ledger: a verdict change vs the most recent prior
-// line for the same criterion sets flip=true and FORCES confidence="low" (a flip means the oracle
-// is unstable on that row, regardless of what confidence the judge proposed). Returns augmented
-// records + a summary. Pure: no I/O, no clock (caller stamps `at`).
-/**
- * Reconcile this run's records against the prior ledger — a verdict change vs the most recent
- * prior line for the same criterion sets flip=true and FORCES confidence="low". Pure: no I/O, no clock.
- * @param {Array<object>} priorLines - Previously recorded ledger lines.
- * @param {Array<{criterion:string, dimension:string, verdict:string, confidence:string}>}
- *   currentRecords - This run's per-criterion records.
- * @returns {{records:Array<object>, summary:{total:number, flipped:number, stable:number,
- *   flips:Array<{criterion:string, dimension:string, to:string}>}}} The records augmented with
- *   `flip` (+ forced-low confidence) and a run summary.
- */
-export function reconcile(priorLines, currentRecords) {
-  const records = currentRecords.map((rec) => {
-    const prior = priorFor(priorLines, rec);
-    const flip = !!prior && prior.verdict !== rec.verdict;
-    return { ...rec, flip, confidence: flip ? "low" : rec.confidence };
-  });
-  const flipped = records.filter((r) => r.flip);
-  return {
-    records,
-    summary: {
-      total: records.length,
-      flipped: flipped.length,
-      stable: records.length - flipped.length,
-      flips: flipped.map((r) => ({ criterion: r.criterion, dimension: r.dimension, to: r.verdict })),
-    },
-  };
-}
-
-// Walk the full ledger in run order; return every criterion whose verdict changed at any step,
-// with the run pair and direction. Used for the report's stability block / audit of a whole task.
-/**
- * Walk the full ledger in run order and report every verdict change.
- * @param {Array<{dimension:string, criterion:string, run:number, verdict:string}>} allLines - Every ledger line.
- * @returns {Array<{criterion:string, dimension:string, from:string, to:string, runs:[number,number]}>}
- *   One entry per step where a criterion's verdict changed.
- */
-export function detectFlips(allLines) {
-  const byKey = new Map();
-  for (const l of [...allLines].sort((a, b) => a.run - b.run)) {
-    const key = `${l.dimension}::${l.criterion}`;
-    const seq = byKey.get(key) || [];
-    seq.push(l);
-    byKey.set(key, seq);
-  }
-  const flips = [];
-  for (const [key, seq] of byKey) {
-    for (let i = 1; i < seq.length; i++) {
-      if (seq[i].verdict !== seq[i - 1].verdict) {
-        flips.push({
-          criterion: seq[i].criterion,
-          dimension: seq[i].dimension,
-          from: seq[i - 1].verdict,
-          to: seq[i].verdict,
-          runs: [seq[i - 1].run, seq[i].run],
-        });
-      }
-    }
-  }
-  return flips;
-}
-
-// Stability of the latest run vs the run before it: fraction of the latest run's criteria whose
-// verdict matches their immediately-prior line. 1.0 when there is only one run (nothing to contradict).
-/**
- * Measure stability of the latest run vs the run before it.
- * @param {Array<{run:number, dimension:string, criterion:string, verdict:string}>} allLines - Every ledger line.
- * @returns {{runs:number, stable:number, total:number, ratio:number}} The max run number, how many
- *   of the latest run's criteria match their prior verdict (new criteria count as stable), the
- *   latest run's criterion count, and their ratio (1.0 when there is only one run).
- */
-export function stability(allLines) {
-  if (allLines.length === 0) return { runs: 0, stable: 0, total: 0, ratio: 1 };
-  const maxRun = Math.max(...allLines.map((l) => l.run));
-  const latest = allLines.filter((l) => l.run === maxRun);
-  if (maxRun === 1) return { runs: 1, stable: latest.length, total: latest.length, ratio: 1 };
-  const prior = allLines.filter((l) => l.run < maxRun);
-  let stable = 0;
-  for (const rec of latest) {
-    const p = priorFor(prior, rec);
-    if (p && p.verdict === rec.verdict) stable++;
-    else if (!p) stable++; // a brand-new criterion can't have flipped
-  }
-  return { runs: maxRun, stable, total: latest.length, ratio: latest.length ? stable / latest.length : 1 };
-}
-
-// Parse a .jsonl ledger string into records (blank lines ignored).
-/**
- * Parse a `.jsonl` verdict ledger into records.
- * @param {string} text - The ledger file contents ("" / null → []).
- * @returns {Array<object>} One parsed object per non-blank line.
- * @throws {SyntaxError} If a non-blank line is not valid JSON.
- */
-export function parseLedger(text) {
-  return (text || "")
-    .split(/\r?\n/)
-    .map((l) => l.trim())
-    .filter(Boolean)
-    .map((l) => JSON.parse(l));
-}
-
-// --- CLI entry: summarize a ledger file -------------------------------------
-/** The typed argv contract (see `kernel/lib/argv.mjs`). */
-export const ARGV_SPEC = {
-  usage: "harness.mjs reduce verdict <.verdicts-TASK.jsonl>",
-  _: { arity: 1, max: 1, name: ".verdicts-TASK.jsonl" },
-};
-
-/**
- * Reconcile a verdict ledger and report its flips and stability.
- *
- * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
- * @returns {(Promise<void>|void)} Settles when the subcommand has written its output; most paths
- *   call `process.exit()` with the subcommand's documented code rather than returning.
- */
-export async function cli(rawArgv) {
-  const { readFileSync } = await import("node:fs");
-  const path = runArgs(ARGV_SPEC, rawArgv)._[0];
-  let lines;
-  try { lines = parseLedger(readFileSync(path, "utf8")); }
-  catch (e) { console.error(`cannot read ledger ${path}: ${e.message}`); process.exit(2); }
-  const flips = detectFlips(lines);
-  const s = stability(lines);
-  console.log(`ledger: ${lines.length} records over ${s.runs} run(s)`);
-  console.log(`stability (latest vs prior): ${s.stable}/${s.total} stable`);
-  if (flips.length) {
-    console.log(`⚠ ${flips.length} flip(s):`);
-    for (const f of flips) console.log(`  ${f.dimension}/${f.criterion}: ${f.from}→${f.to} (runs ${f.runs.join("→")})`);
-    process.exit(1);
-  } else {
-    console.log("✅ no verdict flips");
-    process.exit(0);
-  }
-}