shapeup-sdlc 1.6.2 → 1.7.0

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

@@ -0,0 +1,381 @@
+#!/usr/bin/env node
+// run-workflow — a Bash-invoked control plane for Workflow-format orchestrator scripts.
+//
+// WHY THIS FILE EXISTS. The `Workflow` tool — the only lane for scoped specs — is denied in a
+// headless session with "Review dynamic workflow before running". Left to it, `shapeup-run.js`
+// executes zero times and the agent improvises the feature by hand instead; a session can reach
+// GATE L4 with a valid receipt while the lane never started. Bash HAS a path-scoped grantable
+// prefix, and `npx shapeup-sdlc init` already
+// writes exactly that rule (`Bash(node ${CLAUDE_PLUGIN_ROOT}/skills/<owner>/scripts/:*)` —
+// bin/init.mjs mergePipelinePermissions), so this file runs the SAME Workflow-format script through
+// a surface the install already grants.
+//
+// ⟐ ONE CORRECTION, from probing the permission layer rather than concluding from denials. It is
+// NOT true that no permission string can grant the tool: a bare `"Workflow"` entry in
+// `permissions.allow` grants it, and with that entry removed the same call is denied. So the tool
+// was never ungrantable — the installer simply never wrote the entry, because it writes Bash
+// prefixes only. The defect is real, and it is an INSTALLER defect: the plugin never granted the
+// permission its own lane needs.
+//
+// TWO THINGS SURVIVE THE CORRECTION, and they are the reason this file still exists rather than a
+// one-line change to `init`:
+//   1. THE GRANT CANNOT BE SCOPED. `Workflow(<path>)` and `Workflow(<script>)` are both denied —
+//      only the bare token works, which grants EVERY dynamic workflow script in the project,
+//      including one a model writes at runtime. A harness whose thesis is "gates the agent cannot
+//      talk its way past" should not ask for blanket dynamic-code execution. The Bash prefix is
+//      path-scoped to this directory.
+//   2. It costs no new grant at all: existing installs already allow it.
+// The one-line `"Workflow"` grant remains a legitimate alternative for anyone who prefers the
+// native runtime's resume/isolation, and the upgrade notes document it as such. It is a choice
+// with a real trade-off, which is why it is documented rather than silently taken.
+//
+// IT LIVES IN `scripts/` FOR A LOAD-BEARING REASON, not a filing one. The grant `init` already
+// writes is a PREFIX rule over this exact directory, so shipping the launcher here means every
+// install that ever ran `npx shapeup-sdlc init` can already start the lane — zero new permission
+// strings, zero migration for existing users. Putting it anywhere else would require a new grant
+// and reproduce the same denial one directory over. The structural suite asserts that the
+// documented call site is covered by a prefix `bin/init.mjs` actually writes.
+//
+// PROVENANCE: prototyped and proven before it shipped — a headless `acceptEdits` session runs the
+// lane through a granted Bash prefix with zero denials, this loader executes the unmodified
+// `shapeup-run.js`, and a real worker dispatches under `acceptEdits`.
+//
+// WHAT IT PROVIDES to the script — the Workflow runtime surface shapeup-run.js actually uses:
+//   args, agent(prompt, {label, phase, schema, model, effort}), parallel(thunks),
+//   pipeline(items, ...stages), phase(title), log(msg), budget, workflow() [stub — throws].
+// Scripts keep the Workflow tool's contract: `export const meta = {...}` + a bare top-level body
+// with top-level `await` and `return`. The loader rewrites the one export and wraps the body in an
+// AsyncFunction; nothing about the script format changes, which is the point — shapeup-run.js runs
+// through this file byte-identical to how it ships.
+//
+// HOW agent() DISPATCHES. Each call spawns a fresh headless CLI session:
+//   claude -p <prompt> --model <m> --output-format json --permission-mode acceptEdits
+// (detached process group, SIGTERM-then-SIGKILL escalation on timeout, so a hook grandchild can
+// never hold a dead worker's pipe open — without that, a time-capped session can outlive its cap
+// many times over). Workers are
+// stateless, craft-only, pipeline-blind (the envelope port) — fresh processes fit that contract
+// exactly; nothing here shares context between dispatches. `schema` is enforced by instruction +
+// parse + shallow validation + one retry; a worker that still fails returns null, which is the
+// Workflow tool's own documented behavior for a dead subagent and the case every shapeup-run.js
+// call site already survives (mechEnvelope).
+//
+// DIVERGENCES from the Workflow tool, stated rather than silent. None is reached by
+// `shapeup-run.js`, which is why this lane can carry it today; each is a real gap for any other
+// script, and a reader deciding whether to write one should read this list as a limit, not a note:
+//   - budget counts USD (summed from each worker envelope's total_cost_usd), not output tokens.
+//     Interface is identical: {total, spent(), remaining()}; total comes from --budget-usd.
+//   - Date.now()/Math.random() are NOT banned inside scripts. The tool bans them for replay-safe
+//     resume; this file journals every dispatch (journal.jsonl) but does not implement
+//     resume-from-journal. shapeup-run.js resumes from DISK state by design, not from the
+//     journal — which is why the lane's kill/resume story (`kill-resume-probe: PASS`, four
+//     assertions on a live SIGKILL) does not depend on this and survives the surface swap.
+//   - workflow() (child workflows) throws. shapeup-run.js inlines its round loop and never calls it.
+//   - isolation: 'worktree' throws. shapeup-run.js is sequential today (design doc D3).
+//   - schema validation is shallow (type + required keys + declared property types, one level).
+//
+// A RUN OUTLIVES A FOREGROUND TOOL CALL. A real pipeline runs for tens of minutes; every
+// foreground Bash call has a ceiling well below that. Launch it as a BACKGROUND Bash call and read
+// `<run-dir>/result.json`, which this file writes on completion with the same `{ok, result}` shape
+// stdout carries. Headless callers must also set `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0`, or the
+// wait is cut at 600 s and a truncated run is reported as a clean one.
+//
+// STDOUT DISCIPLINE: stdout carries exactly one JSON line — {ok, result} — because whatever
+// launched this process (a mech courier, an outer session, a test) reads stdout as data. All
+// narration goes to stderr.
+//
+// exit 0: script completed; stdout = {"ok":true,"result":...}
+// exit 1: script threw or the launch failed after parsing; stdout = {"ok":false,"error":...}
+// exit 2: argv rejected before anything ran (lib/argv.mjs) — nothing spawned, nothing written.
+
+import { spawn } from "node:child_process";
+import { readFileSync, writeFileSync, mkdirSync, appendFileSync } from "node:fs";
+import { resolve, basename } from "node:path";
+import process from "node:process";
+import { runArgs } from "./lib/argv.mjs";
+import { isMain } from "./lib/is-main.mjs";
+
+/**
+ * The typed argv boundary.
+ *
+ * FAILING CLOSED IS THE POINT HERE, not hygiene. The cost of a silent launch failure is not that the lane
+ * refused to start — it is that the refusal was quiet enough for an agent to route around, so a
+ * run that never happened reported like one that did. A launcher that accepts `--max-concurrency`
+ * with no value and proceeds on `NaN` is the same shape of defect: this rejects at exit 2 with a
+ * machine-readable reason before a single worker is spawned or a run directory created.
+ */
+export const ARGV_SPEC = {
+  usage: 'run-workflow.mjs <workflow-script.js> [--args <json> | --args-file <path>] ' +
+         "[--run-dir <dir>] [--worker-permission-mode <mode>] [--worker-cwd <dir>] " +
+         "[--max-concurrency <n>] [--agent-timeout-s <n>] [--budget-usd <n>]",
+  _: { arity: 1, name: "workflow-script.js" },
+  args: { type: "json" },
+  "args-file": { type: "path" },
+  "run-dir": { type: "path" },
+  "worker-permission-mode": { type: "enum", values: ["acceptEdits", "default", "plan", "bypassPermissions"] },
+  "worker-cwd": { type: "path" },
+  "max-concurrency": { type: "int", min: 1, max: 32 },
+  "agent-timeout-s": { type: "int", min: 1 },
+  "budget-usd": { type: "num", min: 0 },
+};
+
+/**
+ * Resolve parsed argv into the loader's configuration.
+ * @param {object} a - The object `runArgs(ARGV_SPEC)` returns.
+ * @returns {object} Fully defaulted, absolute-path configuration.
+ */
+export function configure(a) {
+  const script = resolve(a._[0]);
+  return {
+    script,
+    args: a.argsFile ? JSON.parse(readFileSync(a.argsFile, "utf8")) : (a.args ?? {}),
+    runDir: a.runDir
+      ? resolve(a.runDir)
+      : resolve(`.run-workflow-${basename(script).replace(/\.[^.]+$/, "")}-${process.pid}`),
+    workerPermissionMode: a.workerPermissionMode || "acceptEdits",
+    workerCwd: a.workerCwd ? resolve(a.workerCwd) : process.cwd(),
+    maxConcurrency: a.maxConcurrency ?? 4,
+    agentTimeoutS: a.agentTimeoutS ?? 900,
+    budgetUsd: a.budgetUsd ?? null,
+  };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Loader — the Workflow tool's script format, executed as-is. One rewrite (`export const meta`
+// -> `const meta`), then the whole body becomes an AsyncFunction so top-level `await` and
+// top-level `return` mean exactly what the tool defines them to mean.
+// ---------------------------------------------------------------------------------------------
+function loadWorkflow(path) {
+  let src = readFileSync(path, "utf8");
+  src = src.replace(/^export\s+const\s+meta\s*=/m, "const meta =");
+  if (/^export\s/m.test(src)) {
+    throw new Error(`${basename(path)}: unsupported export — Workflow scripts export only \`const meta\``);
+  }
+  const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
+  return new AsyncFunction(
+    "args", "agent", "parallel", "pipeline", "phase", "log", "budget", "workflow",
+    `"use strict";\n${src}`
+  );
+}
+
+// ---------------------------------------------------------------------------------------------
+// Concurrency — a plain semaphore; excess agent() calls queue, mirroring the tool's cap.
+// ---------------------------------------------------------------------------------------------
+function makeSemaphore(max) {
+  let active = 0; const queue = [];
+  const release = () => { active--; const next = queue.shift(); if (next) { active++; next(); } };
+  const acquire = () => new Promise((res) => {
+    if (active < max) { active++; res(); } else queue.push(res);
+  });
+  return { acquire, release };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Worker spawn — one headless CLI session per dispatch. Process-group kill on timeout
+// (hook grandchildren keep pipes open, so
+// signaling one pid is not a cap).
+// ---------------------------------------------------------------------------------------------
+const KILL_GRACE_MS = 10_000;
+
+function runClaude({ prompt, model, permissionMode, cwd, timeoutMs }) {
+  return new Promise((resolvePromise) => {
+    const child = spawn("claude", [
+      "-p", prompt,
+      "--model", model,
+      "--output-format", "json",
+      "--permission-mode", permissionMode,
+    ], { cwd, env: process.env, detached: true });
+
+    let stdout = "", stderr = "", settled = false, killed = false;
+    const settle = (r) => { if (!settled) { settled = true; clearTimeout(timer); clearTimeout(hardTimer); resolvePromise(r); } };
+
+    let hardTimer = null;
+    const timer = setTimeout(() => {
+      killed = true;
+      try { process.kill(-child.pid, "SIGTERM"); } catch { /* already gone */ }
+      hardTimer = setTimeout(() => { try { process.kill(-child.pid, "SIGKILL"); } catch { /* already gone */ } }, KILL_GRACE_MS);
+    }, timeoutMs);
+
+    child.stdout.on("data", (d) => { stdout += d; });
+    child.stderr.on("data", (d) => { stderr += d; });
+    child.on("error", (e) => settle({ ok: false, error: `cannot spawn claude: ${e.message}`, killed, stdout, stderr }));
+    child.on("close", (code) => {
+      let envelope = null;
+      try { envelope = JSON.parse(stdout.trim()); } catch { /* non-JSON stdout stays raw */ }
+      settle({ ok: code === 0 && envelope !== null && envelope.is_error !== true, code, killed, envelope, stdout, stderr });
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------------------------
+// Structured output — instruction + extraction + shallow validation + one retry.
+// Extraction is parseMechJson's balanced-scan (shapeup-run.js:176) — proven against couriers
+// that wrap clean JSON in commentary; the same failure mode applies to whole workers.
+// ---------------------------------------------------------------------------------------------
+function extractJson(text) {
+  if (typeof text !== "string") return null;
+  const s = text.trim();
+  try { return JSON.parse(s); } catch { /* fall through to extraction */ }
+  const start = s.search(/[{[]/);
+  if (start < 0) return null;
+  const open = s[start], close = open === "{" ? "}" : "]";
+  let depth = 0, inStr = false, esc = false;
+  for (let i = start; i < s.length; i++) {
+    const c = s[i];
+    if (inStr) {
+      if (esc) esc = false;
+      else if (c === "\\") esc = true;
+      else if (c === '"') inStr = false;
+      continue;
+    }
+    if (c === '"') { inStr = true; continue; }
+    if (c === open) depth++;
+    else if (c === close && --depth === 0) {
+      try { return JSON.parse(s.slice(start, i + 1)); } catch { return null; }
+    }
+  }
+  return null;
+}
+
+function shallowValidate(schema, value) {
+  const problems = [];
+  if (!schema || typeof schema !== "object") return problems;
+  if (schema.type === "object") {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      return [`expected object, got ${value === null ? "null" : Array.isArray(value) ? "array" : typeof value}`];
+    }
+    for (const k of schema.required || []) if (!(k in value)) problems.push(`missing required key "${k}"`);
+    for (const [k, sub] of Object.entries(schema.properties || {})) {
+      if (!(k in value) || !sub.type) continue;
+      const v = value[k];
+      const t = sub.type === "integer" ? (Number.isInteger(v) ? "integer" : typeof v)
+        : Array.isArray(v) ? "array" : typeof v;
+      if (t !== sub.type && !(sub.type === "number" && typeof v === "number")) {
+        problems.push(`key "${k}": expected ${sub.type}, got ${t}`);
+      }
+    }
+  } else if (schema.type === "array" && !Array.isArray(value)) {
+    problems.push(`expected array, got ${typeof value}`);
+  }
+  return problems;
+}
+
+const schemaInstruction = (schema) =>
+  "\n\n---\nSTRUCTURED OUTPUT REQUIRED. Your final reply must be ONLY a single JSON value that " +
+  "validates against this JSON Schema — no prose, no markdown fences, nothing before or after " +
+  `it:\n${JSON.stringify(schema)}`;
+
+// ---------------------------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------------------------
+async function main() {
+  const cli = configure(runArgs(ARGV_SPEC));
+  mkdirSync(cli.runDir, { recursive: true });
+  const journalPath = resolve(cli.runDir, "journal.jsonl");
+  const journal = (entry) => appendFileSync(journalPath, JSON.stringify(entry) + "\n");
+  const note = (m) => process.stderr.write(`[run-workflow] ${m}\n`);
+
+  const sem = makeSemaphore(cli.maxConcurrency);
+  let seq = 0, costAccum = 0, currentPhase = null;
+
+  const budget = {
+    total: cli.budgetUsd,
+    spent: () => costAccum,
+    remaining: () => (cli.budgetUsd == null ? Infinity : Math.max(0, cli.budgetUsd - costAccum)),
+  };
+
+  async function agent(prompt, opts = {}) {
+    const id = ++seq;
+    const label = opts.label || `agent-${id}`;
+    const model = opts.model || "sonnet";
+    const phaseName = opts.phase || currentPhase;
+    if (budget.total != null && budget.remaining() <= 0) {
+      throw new Error(`budget exhausted ($${costAccum.toFixed(3)} of $${budget.total}) before agent "${label}"`);
+    }
+    if (opts.isolation) throw new Error(`agent "${label}": isolation: 'worktree' is not implemented on this lane`);
+    await sem.acquire();
+    const startedAt = new Date().toISOString();
+    const t0 = process.hrtime.bigint();
+    try {
+      let fullPrompt = opts.schema ? prompt + schemaInstruction(opts.schema) : prompt;
+      let result = null, attempts = 0, sessions = [];
+      while (attempts < 2) {
+        attempts++;
+        note(`agent#${id} "${label}" attempt ${attempts} (model=${model}, mode=${cli.workerPermissionMode})`);
+        const r = await runClaude({
+          prompt: fullPrompt, model, permissionMode: cli.workerPermissionMode,
+          cwd: cli.workerCwd, timeoutMs: cli.agentTimeoutS * 1000,
+        });
+        const env = r.envelope || {};
+        sessions.push({ session_id: env.session_id ?? null, cost_usd: env.total_cost_usd ?? null, is_error: env.is_error ?? null, killed: r.killed });
+        if (typeof env.total_cost_usd === "number") costAccum += env.total_cost_usd;
+        if (!r.ok) { result = null; if (r.killed) break; continue; }
+        if (!opts.schema) { result = env.result ?? null; break; }
+        const parsed = extractJson(env.result);
+        const problems = parsed === null ? ["reply contained no parseable JSON"] : shallowValidate(opts.schema, parsed);
+        if (problems.length === 0) { result = parsed; break; }
+        note(`agent#${id} "${label}" schema problems: ${problems.join("; ")}`);
+        fullPrompt = prompt + schemaInstruction(opts.schema) +
+          `\n\nA previous attempt failed validation: ${problems.join("; ")}. Correct this.`;
+        result = null;
+      }
+      const wallMs = Number(process.hrtime.bigint() - t0) / 1e6;
+      journal({ seq: id, label, phase: phaseName, model, permission_mode: cli.workerPermissionMode,
+        started_at: startedAt, wall_ms: Math.round(wallMs), attempts, sessions, ok: result !== null, result });
+      return result;
+    } finally {
+      sem.release();
+    }
+  }
+
+  // Thunk errors resolve to null and the call never rejects — the Workflow tool's contract,
+  // which shapeup-run.js's call sites (mechEnvelope, dispatch guards) are written against.
+  const parallel = (thunks) => Promise.all(
+    thunks.map((t) => Promise.resolve().then(t).catch((e) => { note(`parallel thunk failed: ${e.message}`); return null; }))
+  );
+
+  // No barrier between stages; a stage that throws drops the item to null and skips the rest.
+  const pipeline = (items, ...stages) => Promise.all(
+    items.map(async (item, i) => {
+      let acc = item;
+      for (const stage of stages) {
+        try { acc = await stage(acc, item, i); }
+        catch (e) { note(`pipeline item ${i} failed: ${e.message}`); return null; }
+      }
+      return acc;
+    })
+  );
+
+  const phase = (title) => { currentPhase = title; note(`── phase: ${title}`); };
+  const log = (m) => note(String(m));
+  const workflow = () => { throw new Error("workflow() child workflows are not implemented on this lane"); };
+
+  const fn = loadWorkflow(cli.script);
+  note(`running ${basename(cli.script)} (run-dir ${cli.runDir})`);
+  const result = await fn(cli.args, agent, parallel, pipeline, phase, log, budget, workflow);
+
+  const summary = { ok: true, script: basename(cli.script), agents_dispatched: seq,
+    cost_usd: Number(costAccum.toFixed(6)), result };
+  writeFileSync(resolve(cli.runDir, "result.json"), JSON.stringify(summary, null, 2) + "\n");
+  process.stdout.write(JSON.stringify({ ok: true, result }) + "\n");
+  return cli.runDir;
+}
+
+if (isMain(import.meta.url)) {
+  main().catch((e) => {
+    // The failure is written where a background caller will look for it, not only to a stdout
+    // nobody is reading: a launch that dies silently is the exact shape this file exists to end.
+    process.stdout.write(JSON.stringify({ ok: false, error: e.message }) + "\n");
+    process.stderr.write(`[run-workflow] FATAL ${e.stack}\n`);
+    try {
+      const dir = process.argv.includes("--run-dir")
+        ? resolve(process.argv[process.argv.indexOf("--run-dir") + 1])
+        : null;
+      if (dir) {
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(resolve(dir, "result.json"),
+          JSON.stringify({ ok: false, error: e.message }, null, 2) + "\n");
+      }
+    } catch { /* the stdout line above is still the record */ }
+    process.exit(1);
+  });
+}

package/skills/tech-lead/scripts/ship-report.mjs

@@ -35,6 +35,7 @@ import {
   roundLedger, discoveryLedger, receipt as receiptPath, harnessRun, relShared,
 } from "./lib/paths.mjs";
 import { readTrials } from "./t0-verify.mjs";
+import { ratchetReport } from "./stats.mjs";
 
 /** @returns {string} Today as `YYYY-MM-DD` (UTC). */
 const today = () => new Date().toISOString().slice(0, 10);
@@ -164,7 +165,7 @@ export function section(md, heading) {
  */
 export function buildReport(facts) {
   const {
-    slug, at, verdict, qa, rounds, board, t0, artifacts,
+    slug, at, verdict, qa, rounds, board, t0, artifacts, ratchet,
     evalCriteria, evalBugs, qaFindings, decisions, discovered, intakeSha,
   } = facts;
 
@@ -202,6 +203,35 @@ export function buildReport(facts) {
     L.push("");
   }
 
+  // The ratchet aggregate is derived, ~10 scalars that do not grow with the run, which is why it
+  // can live in the committed tier while `metrics/` correctly stays gitignored (ADR-0001: a
+  // committed shard keyed on $HOSTNAME only grows). Without this the instrument existed and was
+  // never read — the trial ledger it reduces is harvested at SHIP or lost with the local tier.
+  if (ratchet && ratchet.trials > 0) {
+    L.push("## Ratchet", "");
+    L.push("Measured over this run's trial ledger. A monotone series is a ratchet working; a flat or",
+      "sawtooth series says the loop is still a budgeted retry loop wearing a ratchet's shape.", "");
+    L.push("| | |", "|---|---|");
+    L.push(`| Trials | ${ratchet.trials} across ${ratchet.scopes} scope(s), ${ratchet.scopes_multi_trial} with more than one attempt |`);
+    L.push(`| Improvement rate | ${ratchet.improvement_rate} — kept ÷ trials after the first |`);
+    L.push(`| Monotone rate | ${ratchet.monotone_rate} — multi-trial scopes whose score never decreased |`);
+    L.push(`| Sawtooth count | ${ratchet.sawtooth_count} — a revert immediately after a keep |`);
+    L.push(`| Mean trials to green | ${ratchet.mean_trials_to_green ?? "— (no scope reached green)"} |`);
+    const hist = Object.entries(ratchet.status_histogram).map(([k, v]) => `${k} ${v}`).join(", ");
+    L.push(`| Statuses | ${hist || "—"} |`);
+    L.push("");
+    // A zero improvement_rate means one of two opposite things, and the number alone cannot say
+    // which: the loop tried again and failed to improve, or nothing ever needed a second attempt.
+    // Measured on the first two real runs — every scope went green on attempt 1 — so the reading a
+    // reviewer meets by default is the degenerate one. `stats --ratchet` says so on the terminal;
+    // the committed report has to say it too, or a 0 here is read as "the ratchet did not work".
+    if (ratchet.scopes_multi_trial === 0) {
+      L.push("> No scope needed a second attempt, so the rates above are vacuous rather than bad:",
+        "> the ratchet was never asked to climb. The Day-1 question — does the loop measurably",
+        "> improve across attempts — needs a run where at least one scope retries.", "");
+    }
+  }
+
   if (evalCriteria) L.push("## Evaluation", "", evalCriteria, "");
   if (evalBugs) L.push("### Refuted criteria and bugs", "", evalBugs, "");
   if (qaFindings) L.push("## QA findings", "", qaFindings, "");
@@ -210,7 +240,7 @@ export function buildReport(facts) {
 
   L.push("---", "",
     "*Run state (board, orders, results, T0 artifacts, evaluation and QA reports) stays in the",
-    "gitignored local tier — see `docs/design/adr/0001-consumer-file-organization.md`. This report",
+    "gitignored local tier (ADR-0001). This report",
     "is the frozen conclusion of it.*", "");
   return L.join("\n");
 }
@@ -238,6 +268,7 @@ export function generate({ cwd, slug, verdict, qa }) {
     intakeSha: receipt.intake_sha256,
     board: boardCensus(cwd, slug),
     t0: t0Summary(cwd, slug),
+    ratchet: ratchetReport(readTrials(trials(cwd, slug))),
     artifacts: verdictArtifactCount(cwd, slug),
     evalCriteria: section(evalReport, /^#+\s.*criteria/i) || section(evalReport, /^#+\s*spec-conformance/i),
     evalBugs: section(evalReport, /^#+\s*Bugs?\b/i),

package/skills/tech-lead/scripts/stats.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-// Stats — the telemetry read-plane (v1.2, absorb-audit P3).
+// Stats — the telemetry read-plane (v1.2).
 //
-// SHIP S.6 has been writing fact rows to shapeup/metrics/<machine-id>.jsonl since
+// SHIP S.6 has been writing fact rows to .shapeup/metrics/<machine-id>.jsonl since
 // v0.x with exactly one documented reader: `cat *.jsonl`. This script is the missing
 // projection: rounds per pitch, hammer-cut rate, attempt-budget exhaustions, QA promotion
 // rate, and the round_count trend — the "is the KB flywheel actually working?" chart.
@@ -149,10 +149,10 @@ export function aggregate({ rows, pathologies, sources, rows_malformed }, { metr
 // they reduce over artifacts the harness already writes while doing its ordinary work.
 
 /**
- * `--ratchet` — DAY 1's exit criterion, measured.
+ * `--ratchet` — does the build loop actually ratchet?
  *
- * Every measurement in this project's record so far has been HARNESS VERSUS BARE AGENT — a
- * question already answered. This one is THE LOOP VERSUS ITS OWN FIRST ATTEMPT, and it cannot be
+ * The question harness-versus-bare-agent is already answered elsewhere. This one is THE LOOP
+ * VERSUS ITS OWN FIRST ATTEMPT, and it cannot be
  * won by a one-sentence control, because a one-sentence control has no second attempt to compare.
  *
  * A monotone series is a ratchet working. A flat or sawtooth series says the loop is still a
@@ -220,12 +220,11 @@ export function ratchetReport(trials) {
 }
 
 /**
- * `--hooks` — DAY 2's instrument.
+ * `--hooks` — do the enforcement points actually fire?
  *
- * Of the eight tools built against a MEASURED failure, several scores were previously unobtainable
- * because "never had to fire" and "never ran" produced the same evidence. With a decision row per
- * evaluation, `compact-snapshot` (0 PreCompact events across 1.2M tokens) and `gate-zerowork`
- * ("never had to fire after the fix") become SEPARABLE FACTS rather than the same blank.
+ * For a hook, "never had to fire" and "never ran" used to produce the same evidence: exit 0,
+ * empty stdout. With a decision row per evaluation, a hook that sat inert and a hook that
+ * inspected-and-permitted become SEPARABLE FACTS rather than the same blank.
  *
  * @param {Array<object>} decisions - Rows from `.shapeup/decisions.jsonl`.
  * @returns {{evaluations:number, hooks:number, per_hook:Array<object>}} Per-hook fire, allow, deny,

package/skills/tech-lead/scripts/t0-verify.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-// T0 mechanical verification layer (design spec v1.1 §3.5, Blueprint A/E).
+// T0 mechanical verification layer.
 //
 // Runs a scope's e2e fixtures + DB probe (zero LLM tokens), then — on green — the seesaw
 // regression check (re-runs every FINISHED scope's fixtures from the registry). Writes one
 // verdict artifact per attempt that spec-evaluator (T1) must cite; a verdict without it is
-// structurally invalid (PA4 countermeasure, DD-7). No agent can fabricate this file's contents
+// structurally invalid. No agent can fabricate this file's contents
 // because it is produced by actually running the commands.
 //
 // Zero dependencies, zero network — same discipline as oracles/* and gate-l2.mjs.
@@ -167,7 +167,7 @@ export function score({ fixtures, dbProbe, seesaw }) {
  *   • REGRESSIONS DOMINATE. Breaking a previously-finished scope is never an improvement, whatever
  *     the new scope's fixtures did. This is what lets the old seesaw branch collapse into the
  *     general rule rather than needing a special case.
- *   • DIFFERENT `fixtures_total` IS INCOMPARABLE, not worse. A scope split or remap changes the
+ *   • DIFFERENT `fixtures_total` IS INCOMPARABLE, not worse. A re-slice changes the
  *     denominator; comparing across it is a category error, so the ratchet treats it as a baseline
  *     reset (`rebased`) rather than issuing a false verdict.
  *
@@ -322,7 +322,7 @@ function sha256(text) {
  * the retry, so the artifact recording the regression was silently replaced by the one recording
  * the recovery, at the same path. Reproduced against the shipped script: two runs at
  * `--round 1 --attempt 2`, one red and one green, left ONE file — the red verdict was gone. This
- * is the same missing-identity-key defect the benchmark logged as its own #9, recurring on the one
+ * is the same missing-identity-key defect logged elsewhere in this codebase, recurring on the one
  * artifact the evaluator is structurally required to cite.
  *
  * An `existsSync` guard would be check-then-write: still racy, and still a policy expressed in code

package/skills/tech-lead/scripts/trace-lint.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Traceability oracle (spine v1.3, plan docs/internal/plan/ratchet-and-receipt-plan.md §1.4 + §2).
+// Traceability oracle (spine v1.3).
 //
 // ONE oracle, TWO mechanically-checkable assertions — nothing that merely *asserts* quality:
 //
@@ -260,7 +260,7 @@ export function traceLint(slug, { cwd, gate = false }) {
   }
   if (wiringFound) wiringMap = wiringFound.contract;
 
-  // HD-001. A map whose `## Wiring` table is under a heading the parser does not claim reads as
+  // A map whose `## Wiring` table is under a heading the parser does not claim reads as
   // zero entries, and the loop below then walks nothing and reports `0/0 engines reach <entry>` —
   // GREEN, for a committed file holding six correct rows. The gate whose entire purpose is that no
   // engine ships orphaned failing open, on a file that looks right to every human who reviews it.