shapeup-sdlc 1.6.3 → 3.0.0

package/{skills/tech-lead/scripts/gate-answers.mjs → kernel/gate.mjs}

@@ -1,21 +1,20 @@
 #!/usr/bin/env node
 // GATE ANSWER SET — cross a gate with a pre-recorded decision instead of a live human.
 //
-// WHY THIS EXISTS (measured, not theorized).
+// WHY THIS EXISTS (observed, not theorized).
 //
 // This harness pauses at every ⏸ gate for PO sign-off by default. That is the point of it. But
-// on the SDD harness benchmark it produced two distinct failures, both of which look like the
-// harness being slow or broken rather than the harness being safe:
+// unattended it produces two distinct failures, both of which look like the harness being slow or
+// broken rather than the harness being safe:
 //
-//   1. STALL → TIMEOUT. F3 (Sonnet 5): the run was killed at the declared 1800s cap having
-//      produced nothing scoreable, while the no-harness control finished the same feature in
-//      51 seconds. A run with no human at the keyboard sitting at a gate does not fail — it
-//      waits, and a wait is indistinguishable from work until the budget runs out.
+//   1. STALL → TIMEOUT. The run is killed at its time cap having produced nothing scoreable,
+//      on a feature that takes minutes to build by hand. A run with no human at the keyboard
+//      sitting at a gate does not fail — it waits, and a wait is indistinguishable from work
+//      until the budget runs out.
 //   2. CONSENT-BY-PROSE. The workaround was a paragraph of English in the prompt ("treat this
-//      message as advance sign-off for every gate"). On Sonnet that worked. On Haiku 4.5 the
-//      model read the paragraph, read the 450-line gate list, and narrated the pipeline instead
-//      of running it — 29% acceptance, n=5, zero variance. Consent carried in prose is consent
-//      that can be re-summarized instead of acted on.
+//      message as advance sign-off for every gate"). Some models act on it. Others read the
+//      paragraph, read the gate list, and narrate the pipeline instead of running it. Consent
+//      carried in prose is consent that can be re-summarized instead of acted on.
 //
 // The organising rule of this project is that every invariant that matters lives in the runtime,
 // not in a prompt. Gate sign-off was the last big one still living in a prompt. So it becomes a
@@ -33,10 +32,10 @@
 // pre-recorded answer") rather than a silent wait that gets reported as a slow harness.
 //
 // USAGE
-//   node gate-answers.mjs --init [--preset ci|guarded|interactive] [--out <path>] [--by "<name>"]
-//   node gate-answers.mjs --resolve <gate-id> [--file <path>|--preset <name>] [--slug <slug>]
-//   node gate-answers.mjs --list [--file <path>|--preset <name>]
-//   node gate-answers.mjs --verify [--file <path>|--preset <name>] [--auto-level unattended]
+//   node `harness gate` --init [--preset ci|guarded|interactive] [--out <path>] [--by "<name>"]
+//   node `harness gate` --resolve <gate-id> [--file <path>|--preset <name>] [--slug <slug>]
+//   node `harness gate` --list [--file <path>|--preset <name>]
+//   node `harness gate` --verify [--file <path>|--preset <name>] [--auto-level unattended]
 //
 // RESOLUTION ORDER for --resolve / --list / --verify, first hit wins:
 //   1. --file <path>
@@ -51,11 +50,10 @@
 //   5  no answer and on_missing=abort → the run aborts here, attributably
 //   2  usage / validation error
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
-import { isMain } from "./lib/is-main.mjs";
 import { runArgs } from "./lib/argv.mjs";
-import { gateAnswerCandidates, LOCAL } from "./lib/paths.mjs";
+import { gateAnswerCandidates, gates as gatesPath, LOCAL } from "./lib/paths.mjs";
 
 export const GATE_IDS = ["L0", "L1a", "L1a.5", "L1b", "L2", "L3", "QA", "H", "L4", "COACH-1"];
 
@@ -79,7 +77,7 @@ export const VALID_BY_GATE = {
 const CI_NOTE = "Pre-approved for a headless lane. No human is present; the decision is recorded here so the ledger still names a source.";
 
 export const PRESETS = {
-  // Everything pre-approved. The lane a CI step or a benchmark runs in.
+  // Everything pre-approved. The lane a CI step runs in.
   ci: {
     version: 1,
     preset: "ci",
@@ -205,6 +203,33 @@ export function resolve(set, gate, source) {
   };
 }
 
+/**
+ * Append one row to the per-slug gate-crossing ledger — `.shapeup/<slug>/gates.jsonl` ({@link
+ * gatesPath}, from `lib/paths.mjs`).
+ *
+ * WRITER RULE, same shape as {@link appendTrial} in `verify/t0.mjs` and the dispatch-receipt hook's
+ * ownership of `decisions.jsonl`: one small file, one writer, append-only JSONL so concurrent
+ * scopes crossing gates in the same round cannot clobber each other's row.
+ *
+ * Records every resolution that reached a real status — a crossing (`ok`), a recorded pause
+ * (`ask`), or an abort (`abort`) — because "the run stopped here" is exactly the kind of fact this
+ * ledger exists to hold. Best-effort: a ledger write that could fail a gate crossing would cost more
+ * than the row is worth, matching {@link appendTrial}'s own trade-off.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {object} row - The ledger row (gate, decision, source, note, round, status).
+ * @returns {boolean} True when the row was written.
+ */
+export function appendGateLedger(cwd, slug, row) {
+  try {
+    const p = gatesPath(cwd, slug);
+    mkdirSync(dirname(p), { recursive: true });
+    appendFileSync(p, JSON.stringify(row) + "\n");
+    return true;
+  } catch { return false; }
+}
+
 /** Gates this lane will actually hit — used by --verify to catch a set that stalls halfway. */
 export function requiredGates({ autoLevel = "unattended", tiny = false, qa = true } = {}) {
   if (tiny) return ["L0", "L4"];
@@ -240,9 +265,9 @@ export function discover({ cwd = process.cwd(), file = null, preset = null, slug
 
 /** The typed argv contract (see `./lib/argv.mjs`). */
 export const ARGV_SPEC = {
-  usage: "gate-answers.mjs (--init | --list | --verify | --resolve <gate-id>) [--preset <name>] " +
+  usage: "harness.mjs gate (--init | --list | --verify | --resolve <gate-id>) [--preset <name>] " +
          "[--file <path>] [--slug <slug>] [--cwd <dir>] [--out <path>] [--by <who>] " +
-         "[--auto-level <level>] [--tiny] [--no-qa]",
+         "[--auto-level <level>] [--tiny] [--no-qa] [--round <n>]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   cwd: { type: "path" },
   init: { type: "flag" },
@@ -257,6 +282,10 @@ export const ARGV_SPEC = {
   "auto-level": { type: "str" },
   tiny: { type: "flag" },
   "no-qa": { type: "flag" },
+  // The current BUILD round, when the caller has one — L2/L3 are crossed once per round, so the
+  // ledger row needs it to key a `GateDecision` node uniquely per crossing. Round-independent gates
+  // (L0, L1a, …) simply omit it and the row carries `round: null`.
+  round: { type: "int", min: 1 },
 };
 
 function out(obj, code = 0) {
@@ -268,8 +297,15 @@ function die(msg, code = 2) {
   process.exit(code);
 }
 
-export function main() {
-  const args = runArgs(ARGV_SPEC);
+/**
+ * Resolve, verify, list or initialise the gate answer set.
+ *
+ * @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 function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
   const cwd = args.cwd || process.cwd();
 
   if (args.init) {
@@ -328,11 +364,18 @@ export function main() {
 
   const r = resolve(found.set, gate, found.source);
   if (r.status === "error") die(r.reason);
+  // A gate with no `--slug` (e.g. `--file` used ad hoc, outside any run) has nowhere to file a
+  // per-run ledger row — the same reasoning `resolveRunId` uses for "no run is active": absence is
+  // the correct answer, not an error, so the write is skipped rather than guessing a location.
+  if (args.slug) {
+    appendGateLedger(cwd, args.slug, {
+      gate: r.gate, status: r.status, decision: r.decision ?? null,
+      source: r.source ?? found.source, note: r.note ?? r.reason ?? null,
+      round: args.round ?? null,
+    });
+  }
   if (r.status === "ask") out({ ...r, ok: false }, 4);
   if (r.status === "abort") out({ ...r, ok: false }, 5);
   out({ ...r, ok: true }, 0);
 }
 
-if (isMain(import.meta.url)) {
-  main();
-}

package/kernel/harness.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+// harness — the kernel's single entry point.
+//
+// WHAT THIS IS. Everything in the pipeline that must be DETERMINISTIC — measured rather than
+// claimed, single-writer rather than negotiated, an answer file rather than a vibe — is a
+// subcommand of this one script:
+//
+//     node ${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs <verb> [<action>] [flags]
+//
+// WHY ONE ENTRY POINT. A permission rule is matched against a command string. With one executable
+// the entire grant is two lines a person can read (`bin/lib/grant.mjs`); with twenty it is forty
+// rules that must be regenerated on every add, rename or removal — and a rule that silently
+// matches nothing is indistinguishable from a rule that works until the first dispatch fails.
+// Subcommands are free; entry points are not.
+//
+// WHO CALLS IT. Worker skills, from their own shells, and the hooks. The control plane — the
+// Workflow script — calls no shell at all: it branches on the structured return of an `agent()`
+// and never parses stdout.
+//
+// THE VERBS, and the invariant each one exists to keep:
+//
+//   verify   t0 · budget · envelope ·        Measured, not claimed. A model verifying itself is
+//            trace · spec · skills ·          claiming; these read artifacts and re-hash them.
+//            dispatch                         `skills` reads the roster off disk; `dispatch` reads
+//                                             the hook layer's evidence that a skill really resolved
+//                                             in this session — the half a file check cannot answer.
+//   reduce   ingest · hill · snapshot ·       Single writer. Shared state has exactly one author.
+//            ship · board · verdict · graph
+//   gate                                      An answer file with a source, not a vibe.
+//   probe    resume · t0 · stats · digest ·   Read-only queries over run state. `concurrency`
+//            concurrency · leg · eval          answers how many legs ran at once and what the
+//                                              fan-out bought, and refuses a figure the record set
+//                                              cannot support rather than printing a plausible one.
+//                                              `leg` answers whether a scope's work reached the
+//                                              board — a green T0 says its fixtures passed, not that
+//                                              its result was ever applied, and a leg that skipped
+//                                              its own ingest step is indistinguishable from one that
+//                                              did not until something reads the writer's own record.
+//                                              `eval` answers what an EVAL round's WorkResult
+//                                              actually said, mechanically — the round-loop branch
+//                                              reads this instead of trusting a dispatching agent's
+//                                              own end-of-turn summary of its own verdict.
+//   init     run · fit                        Opens a run, or refuses it (exit 3).
+//   report   export                           Projects the run's records as fact tables.
+//   compile                                   The WorkOrder: schema-valid or nothing is dispatched.
+//
+// EXIT CODES are the subcommand's own and are part of its contract: 0 success · 1 ran, answer is
+// no · 2 malformed input, nothing ran (`lib/argv.mjs`) · 3 `init run` refused to open · 4/5 gate
+// stop/abort · 6 budget tripped. This dispatcher adds exactly one of its own: 2 for an unknown
+// verb, which is the same "the input was malformed" case.
+
+import { isMain } from "./lib/argv.mjs";
+
+/**
+ * verb → action → module, the whole routing table.
+ *
+ * A verb whose value is a string takes no action word (`gate`, `compile`); a verb whose value is an
+ * object requires one, and `_default` names the action taken when it is omitted.
+ *
+ * Exported so the structural suite enumerates the subcommands from THIS table rather than from a
+ * hand-kept list beside it — a second copy of the routing is a second thing to forget.
+ */
+export const ROUTES = {
+  verify: {
+    t0: "./verify/t0.mjs", budget: "./verify/budget.mjs", envelope: "./verify/envelope.mjs",
+    trace: "./verify/trace.mjs", spec: "./verify/spec.mjs", skills: "./verify/skills.mjs",
+    dispatch: "./verify/dispatch.mjs",
+  },
+  reduce: {
+    ingest: "./reduce/ingest.mjs", hill: "./reduce/hill.mjs", snapshot: "./reduce/snapshot.mjs",
+    ship: "./reduce/ship.mjs", board: "./reduce/board.mjs", verdict: "./reduce/verdict.mjs",
+    graph: "./reduce/graph.mjs",
+  },
+  probe: {
+    resume: "./probe/resume.mjs", t0: "./probe/t0.mjs", stats: "./probe/stats.mjs",
+    digest: "./probe/digest.mjs", concurrency: "./probe/concurrency.mjs",
+    leg: "./probe/leg.mjs", eval: "./probe/eval.mjs",
+  },
+  init: { run: "./init/run.mjs", fit: "./init/fit.mjs" },
+  report: { export: "./report/export.mjs", _default: "export" },
+  gate: "./gate.mjs",
+  compile: "./compile.mjs",
+};
+
+/** Every `<verb> <action>` pair, for the usage text and the unknown-verb rejection. */
+function usage() {
+  const lines = [];
+  for (const [verb, target] of Object.entries(ROUTES)) {
+    if (typeof target === "string") lines.push(`  ${verb}`);
+    else lines.push(`  ${verb} ${Object.keys(target).filter((a) => a !== "_default").join(" | ")}`);
+  }
+  return `usage: harness.mjs <verb> [<action>] [flags]\n${lines.join("\n")}\n\nEvery subcommand accepts --help through its own argv spec.`;
+}
+
+/**
+ * Reject an invocation before anything runs, the same way `lib/argv.mjs` rejects a bad flag.
+ * @param {object} detail - Machine-readable rejection record.
+ * @returns {never} Exits 2.
+ */
+function reject(detail) {
+  process.stderr.write(JSON.stringify(detail) + "\n");
+  process.stderr.write(usage() + "\n");
+  process.exit(2);
+}
+
+/**
+ * Resolve `<verb> [<action>]` to a module path and the argv the subcommand should see.
+ *
+ * @param {string[]} argv - `process.argv.slice(2)`.
+ * @returns {{module: string, rest: string[]}} The module to import and its own arguments.
+ */
+export function route(argv) {
+  const [verb, ...rest] = argv;
+  if (!verb || verb === "--help" || verb === "-h") { process.stdout.write(usage() + "\n"); process.exit(0); }
+  const target = ROUTES[verb];
+  if (!target) reject({ error: "unknown_verb", verb, expected: Object.keys(ROUTES).join(" | ") });
+  if (typeof target === "string") return { module: target, rest };
+
+  const action = rest[0] && !rest[0].startsWith("-") ? rest[0] : target._default;
+  const module = action ? target[action] : null;
+  if (!module) {
+    reject({
+      error: action ? "unknown_action" : "missing_action", verb, action: action ?? null,
+      expected: Object.keys(target).filter((a) => a !== "_default").join(" | "),
+    });
+  }
+  return { module, rest: rest[0] === action ? rest.slice(1) : rest };
+}
+
+if (isMain(import.meta.url)) {
+  const { module, rest } = route(process.argv.slice(2));
+  const mod = await import(module);
+  await mod.cli(rest);
+}

package/{skills/tech-lead/scripts/fit-check.mjs → kernel/init/fit.mjs}

@@ -1,19 +1,19 @@
 #!/usr/bin/env node
 // GATE L0.3 — FIT CHECK. Which lane does this change belong in? Decided by measurement.
 //
-// WHY THIS EXISTS (measured, and it is the root cause the other three fixes did not touch).
+// WHY THIS EXISTS (and it is the root cause the other three fixes did not touch).
 //
-// On the SDD harness benchmark, F3 ("add a `summary` command" to a six-file CLI — one new module
-// plus one dispatcher wiring) was run through the full eleven-gate pipeline and never finished.
-// Not once, across four attempts. It was killed at the 1800s cap mid-build; then, with a
-// wall-clock breaker fitted, it reached ship-triage and was killed there; then it produced an
-// honest report saying its two must-haves were 0% started.
+// A change of the size "add a `summary` command to a six-file CLI" — one new module plus one
+// dispatcher wiring — run through the full eleven-gate pipeline does not finish. Not once, across
+// repeated attempts: killed at the time cap mid-build; then, with a wall-clock breaker fitted,
+// killed at ship-triage; then producing an honest report saying its two must-haves were 0%
+// started.
 //
 // Every one of those fixes made the FAILURE better. None of them made the RUN finish, because
 // none addressed why a three-file change was consuming half an hour: **the ceremony was not
 // sized to the change.**
 //
-// The harness already knew. In the pilot transcripts, tech-lead identified F1 at GATE L0 as
+// The harness already knew. In those transcripts tech-lead identified the change at GATE L0 as
 // "about as small as they come… squarely inside the --tiny lane" — and then ran the full pipeline
 // anyway, because the lane was a judgment the model was free to talk itself out of. That is the
 // same class of defect as narration and as prose consent: an invariant living somewhere a model
@@ -34,17 +34,16 @@
 // symmetric, and the tie goes to the gates.
 //
 // USAGE
-//   node fit-check.mjs --intake-file <path> [--cwd <root>] [--json]
-//   node fit-check.mjs --intake-text "<requirement>" [--cwd <root>]
+//   node `harness init fit` --intake-file <path> [--cwd <root>] [--json]
+//   node `harness init fit` --intake-text "<requirement>" [--cwd <root>]
 //
 // Exit 0 always — this informs a decision, it does not deny a tool call. The orchestrator reads
-// `lane` and acts on it; `init-run.mjs` records it in the receipt.
+// `lane` and acts on it; ``harness init run`` records it in the receipt.
 
 import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { isMain } from "./lib/is-main.mjs";
-import { LOCAL } from "./lib/paths.mjs";
-import { runArgs } from "./lib/argv.mjs";
+import { LOCAL } from "../lib/paths.mjs";
+import { runArgs } from "../lib/argv.mjs";
 
 /** Directories that are never part of "the tree being changed". */
 const IGNORE_DIRS = new Set([".git", "node_modules", LOCAL, "dist", "build", ".next", "coverage", ".claude"]);
@@ -121,7 +120,7 @@ export function decideLane({ intake, files }) {
   };
 
   // CONJUNCTIVE, and it must be. The first version asked "is there evidence this is BIG?" and
-  // defaulted to tiny when it found none — which classified all three benchmark features as tiny,
+  // defaulted to tiny when it found none — which classified every trial feature as tiny,
   // including the five-seam one that genuinely needs the pipeline and used two evaluation rounds
   // to pass. A router that confident and that wrong is worse than no router: it would skip review
   // on exactly the change that needed it.
@@ -152,7 +151,7 @@ export function decideLane({ intake, files }) {
     // Say it on every invocation rather than burying it in a doc. These thresholds are calibrated
     // against THREE features. That is enough to stop the router being obviously wrong and nowhere
     // near enough to trust it silently, so it recommends and never denies.
-    calibration: "advisory — thresholds fitted on 3 benchmark features (n=3); `full` is the default and the PO may override with --lane",
+    calibration: "advisory — thresholds are coarse and `full` is the default; the PO may override with --lane",
   };
 }
 
@@ -160,15 +159,22 @@ export function decideLane({ intake, files }) {
 
 /** The typed argv contract (see `./lib/argv.mjs`). */
 export const ARGV_SPEC = {
-  usage: 'fit-check.mjs (--intake-file <path> | --intake-text "<requirement>") [--cwd <dir>]',
+  usage: 'harness.mjs init fit (--intake-file <path> | --intake-text "<requirement>") [--cwd <dir>]',
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   cwd: { type: "path" },
   "intake-text": { type: "str" },
   "intake-file": { type: "path" },
 };
 
-export function main() {
-  const args = runArgs(ARGV_SPEC);
+/**
+ * Decide the lane (full or tiny) for an intake and the tree it will build in.
+ *
+ * @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 function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
   const cwd = args.cwd || process.cwd();
   let intake = args.intakeText ?? null;
   const f = args.intakeFile ?? null;
@@ -186,11 +192,8 @@ export function main() {
     ...result,
     // The sentence the orchestrator must act on, so the decision is not re-derived from the JSON.
     action: result.lane === "tiny"
-      ? "TINY LANE. Run: orient (light) → single-task board → build → T0 → ⏸ L4. Skip WIRE, scope contracts, spec tree, EVAL and QA. The full pipeline on a change this size is the measured cause of a benchmark run that never finished, four attempts running."
+      ? "TINY LANE. Run: orient (light) → single-task board → build → T0 → ⏸ L4. Skip WIRE, scope contracts, spec tree, EVAL and QA. The full pipeline on a change this size is why a run burns its whole clock without finishing."
       : "FULL LANE. Run the complete pipeline: ORIENT → WIRE → MAP SCOPES → BUILD → EVAL → QA → GATE H → L4.",
   }, null, 2));
 }
 
-if (isMain(import.meta.url)) {
-  main();
-}