shapeup-sdlc 1.6.3 → 3.0.0

package/{skills/tech-lead/scripts/t0-verify.mjs → kernel/verify/t0.mjs}

@@ -1,13 +1,13 @@
 #!/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.
+// Zero dependencies, zero network — same discipline as oracles/* and the GATE L2 block.
 //
 // THE PAWL (v1.5). This script also owns the ratchet's comparison and its history. The attempt
 // loop used to be a BUDGETED RETRY LOOP wearing a ratchet's shape: `computeVerdict` returned four
@@ -29,7 +29,7 @@
 // N+1 build on attempt N instead of restarting from unexplained code.
 //
 // Usage:
-//   node "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/t0-verify.mjs" <scope-contract.json> \
+//   node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" verify t0 <scope-contract.json> \
 //        --round N --attempt M [--cwd <dir>] [--out <dir>] [--seesaw-registry <path>] [--no-seesaw]
 //        [--no-ratchet]
 //
@@ -39,11 +39,28 @@ import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync, rea
 import { join, dirname } from "node:path";
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { digest } from "./aegis-digest.mjs";
-import { isMain } from "./lib/is-main.mjs";
-import { runArgs } from "./lib/argv.mjs";
-import { snapshot, restore, keptRef } from "./lib/ratchet-tree.mjs";
-import { readContract, SCOPE_CONTRACT } from "./lib/contract-md.mjs";
+import { digest } from "../probe/digest.mjs";
+import { runArgs } from "../lib/argv.mjs";
+import { snapshot, restore, keptRef } from "./ratchet-tree.mjs";
+import { readContract, SCOPE_CONTRACT } from "../lib/contract.mjs";
+import { runIdFromRoot, localRoot, SHARED } from "../lib/paths.mjs";
+
+/**
+ * The feature slug a scope contract belongs to, from its path.
+ *
+ * Scope contracts live at `<SHARED>/<slug>/scopes/<id>.md`, so the slug is the segment two levels
+ * above the file. Derived rather than flagged because every caller already names the contract, and
+ * a second way to say the same thing is a second thing to get wrong.
+ *
+ * @param {string} contractPath - Path to the scope contract, absolute or relative.
+ * @returns {string} The slug, or "" when the path does not have the expected shape — in which case
+ *   the caller's `--out` is the only sensible answer and its absence is a usage error.
+ */
+export function slugFromContractPath(contractPath) {
+  const parts = String(contractPath).split(/[/\\]/);
+  const i = parts.lastIndexOf("scopes");
+  return i > 0 ? parts[i - 1] : "";
+}
 
 /**
  * Run one shell command and capture its outcome (10-minute timeout).
@@ -71,7 +88,24 @@ function runCommand(cmd, cwd) {
  */
 export function runFixtures(fixtures, cwd) {
   const results = (fixtures || []).map((cmd) => runCommand(cmd, cwd));
-  return { pass: results.every((r) => r.pass), results };
+  // AN ABSENCE IS NOT A PASS, and this is the whole "measured, not claimed" invariant in one line.
+  //
+  // `[].every(...)` is `true`, so a scope whose contract declared no fixtures — or whose fixtures
+  // failed to PARSE, which is how it actually happened — scored `pass: true` and the verdict came
+  // back `overall: "green"`. Measured directly:
+  //
+  //     runFixtures(undefined)  ->  pass=true, results=0
+  //     computeVerdict(…)       ->  {"overall":"green"}
+  //
+  // Nothing ran, and the scope was certified. That is not a weaker version of the guarantee, it is
+  // the inverse of it: the one layer the evaluator is required to cite, green on zero evidence. The
+  // same reasoning the decision ledger states one directory over — "an absence proves nothing and
+  // must not sharpen the message".
+  //
+  // `ran` is reported rather than folded into `pass` so the two facts stay distinguishable: a scope
+  // with nothing to run is a contract that is not finished, which is different from a scope whose
+  // fixtures ran and failed, and the ratchet should be able to tell them apart.
+  return { pass: results.length > 0 && results.every((r) => r.pass), ran: results.length > 0, results };
 }
 
 /**
@@ -167,7 +201,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.
  *
@@ -183,9 +217,43 @@ export function better(next, current) {
   if (next.regressions !== current.regressions) return next.regressions < current.regressions;
   if (next.fixtures_passed !== current.fixtures_passed) return next.fixtures_passed > current.fixtures_passed;
   if (next.db_probe !== current.db_probe) return (next.db_probe ?? 0) > (current.db_probe ?? 0);
+  // EVERY COMPONENT TIES. What that means depends entirely on whether the incumbent was green.
+  //
+  // On a RED scope a tie is the sawtooth the pawl exists to stop, and it stays `false` — that is the
+  // case the rule above was written for and the case the guard fixtures assert (2/5 vs 2/5).
+  //
+  // On a GREEN scope there is no score left to win. Every further attempt ties BY CONSTRUCTION, so
+  // `false` restores the tree every time and the scope can never change again: the pawl stops being
+  // a pawl and becomes a weld. That is exactly the state a spec-conformance round is in. EVAL
+  // returns FAIL citing bugs T0's fixtures do not test — a bare stack trace, an error message that
+  // does not match the catalogue, validation ordered after a load — the next round's workers fix
+  // them, T0 scores 1/1 again because its fixtures never tested the prose, and the ratchet throws
+  // the fix away.
+  //
+  // Measured on a live run: round 2 produced six trials, 0 kept, 6 reverted, `bin/todo.js` byte-for-
+  // byte unchanged, and all three cited bugs reproducing. The FAIL → fix → re-evaluate loop — the
+  // harness's central promise — is inert for precisely the defects EVAL is best at finding.
+  //
+  // So: a green tie KEEPS. The tree may move when the score cannot, because by then the work being
+  // done is work T0 does not measure, and refusing it does not protect the scope — it freezes it.
+  if (isGreenScore(next) && isGreenScore(current)) return true;
   return false;
 }
 
+/**
+ * Is this score a clean pass — every fixture passing, none of them absent, no outstanding regression?
+ *
+ * `fixtures_total > 0` is load-bearing: a scope with no fixtures has nothing to be green ABOUT, and
+ * treating its empty score as a pass is the same absence-reads-as-success mistake `runFixtures`
+ * made one function above.
+ *
+ * @param {{regressions:number, fixtures_passed:number, fixtures_total:number}} s - A trial score.
+ * @returns {boolean} True when the score represents a real, complete pass.
+ */
+function isGreenScore(s) {
+  return s.regressions === 0 && s.fixtures_total > 0 && s.fixtures_passed === s.fixtures_total;
+}
+
 /**
  * The one rule that replaces the protocol's two red branches.
  *
@@ -322,12 +390,12 @@ 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
  * rather than a property of the store. `flag: "wx"` makes overwriting IMPOSSIBLE — the filesystem
- * refuses with EEXIST and the loop moves to the next ordinal. Same class of move as `lib/is-main.mjs`:
+ * refuses with EEXIST and the loop moves to the next ordinal. Same class of move as the entry-point guard:
  * replace a fragile comparison with one that cannot silently be wrong.
  *
  * The evaluator's citation contract is unaffected: it re-hashes whatever path it is handed, and
@@ -364,7 +432,7 @@ export function writeArtifact(outDir, round, attempt, verdictBody) {
 
 /** The typed argv contract (see `./lib/argv.mjs`). */
 export const ARGV_SPEC = {
-  usage: "t0-verify.mjs <scope-contract.json> --round N --attempt M [--cwd <dir>] [--out <dir>] " +
+  usage: "harness.mjs verify t0 <scope-contract.json> --round N --attempt M [--cwd <dir>] [--out <dir>] " +
          "[--seesaw-registry <path>] [--no-seesaw] [--no-ratchet]",
   _: { arity: 1, max: 1, name: "scope-contract.json" },
   round: { type: "int", min: 1, required: true },
@@ -377,25 +445,45 @@ export const ARGV_SPEC = {
 };
 
 /**
- * CLI entry: run a scope's fixtures + probe + seesaw, write the verdict artifact, print it, and
- * exit 0 (green) / 1 (red) / 2 (usage).
- * @returns {Promise<void>} Resolves after writing the artifact; the process exit code carries the verdict.
+ * Run the T0 evidence layer for one attempt and write the verdict artifact the judge cites.
+ *
+ * @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.
  */
-async function main() {
-  const args = runArgs(ARGV_SPEC);
+export async function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
   const contractPath = args._[0];
-  // Markdown first, legacy JSON second (ADR-0001, lib/contract-md.mjs).
+  // Markdown first, legacy JSON second (ADR-0001, lib/contract.mjs).
   const found = readContract(contractPath, SCOPE_CONTRACT);
   if (!found) { console.error(`t0-verify: no scope contract at ${contractPath} (.md or .json)`); process.exit(2); }
   const contract = found.contract;
   const cwd = args.cwd || process.cwd();
-  const outDir = args.out || dirname(dirname(contractPath)); // default: <slug>/ (parent of scopes/)
+  // WHERE THE VERDICT LANDS, and the one thing about this file that must not be derived from the
+  // contract's own location.
+  //
+  // This used to be `dirname(dirname(contractPath))` — "the parent of scopes/" — which was correct
+  // while scope contracts and the run trace shared a root. ADR-0001 split the tiers and moved scope
+  // contracts to COMMITTED `shapeup/<slug>/scopes/`, so the default silently followed them: every
+  // T0 verdict and trial row was written to `shapeup/<slug>/t0/` while `probe t0` — the ONLY reader,
+  // and the one the build round's confirm stage asks — resolves `verdictsDir()` to
+  // `.shapeup/<slug>/t0/`. AGENTS.md is unambiguous that T0 artifacts are LOCAL tier.
+  //
+  // Measured on a live run: six verdicts and six trial rows were written, `foundation` among them
+  // with `fixtures_passed: 2/2, status: kept` — a real green — and the round still reported ZERO
+  // green scopes, tripped the inner breaker and returned `gate_h`. The evidence existed, was
+  // correct, and was invisible to the only thing that reads it. That is the same silent disconnect
+  // `hooks/lib/decision.mjs` records in its own header, one directory over.
+  //
+  // `--out` still wins: `verify t0` is also called with an explicit run root, and that caller knows
+  // better than any derivation.
+  const outDir = args.out || localRoot(cwd, slugFromContractPath(contractPath));
   const round = args.round;
   const attempt = args.attempt;
 
   const fixtures = runFixtures(contract.e2e_verification_fixtures, cwd);
   const dbProbe = runDbProbe(contract.db_probe, cwd);
-  // --seesaw-registry is expected explicitly (tech-lead always passes it, delegation.md 3c);
+  // --seesaw-registry is expected explicitly (tech-lead always passes it, protocol.md 3c);
   // standalone CLI use without it simply skips the seesaw check rather than guessing a path.
   const seesawRegistry = args.noSeesaw ? null : args.seesawRegistry || null;
   const seesaw = args.noSeesaw || fixtures.pass === false
@@ -417,7 +505,13 @@ async function main() {
   const crashed = fixtures.results.some((r) => r.error) || !!dbProbe?.error;
   const { status, action } = decideStatus(verdictBetter, crashed);
 
+  // The run key, read from the receipt that lives in the run root this script was pointed at.
+  // `--out` IS that root, so identity comes from the receipt rather than from parsing a slug back
+  // out of a directory name; a caller that points `--out` somewhere else simply gets no key.
+  const runId = runIdFromRoot(outDir);
+
   const { path, sha256: hash, trial } = writeArtifact(outDir, round, attempt, {
+    ...(runId ? { run_id: runId } : {}),
     scope_id: contract.scope_id,
     fixtures: fixtures.results.map(({ cmd, exit, pass }) => ({ cmd, exit, pass })),
     db_probe: dbProbe && { cmd: dbProbe.cmd, exit: dbProbe.exit, pass: dbProbe.pass },
@@ -431,18 +525,37 @@ async function main() {
   // the pre-v1.5 behaviour, kept for standalone CLI use and for any caller managing its own tree.
   let tree = { ok: false, reason: "--no-ratchet" };
   if (!args.noRatchet) {
-    tree = action === "keep" ? snapshot(contract.scope_id, cwd) : restore(contract.scope_id, cwd);
+    // The revert is bounded by what this scope was allowed to write. Unbounded, it rolls back every
+    // other scope building alongside it — see `restore`.
+    const own = contract.allowed_file_substrate || [];
+    tree = action === "keep" ? snapshot(contract.scope_id, cwd) : restore(contract.scope_id, cwd, own);
     // First trial with nothing to restore to: there is no kept tree yet BY DEFINITION. Take one,
     // so trial 2 has a floor to fall back to instead of inheriting the "no revert at all" defect.
-    if (action === "restore" && !tree.ok) tree = { ...snapshot(contract.scope_id, cwd), fell_back_to: "snapshot" };
+    // Gated on `!baseline` (no prior kept/rebased trial exists at all), NOT on `!tree.ok` alone —
+    // a genuine restore failure with a real baseline to have restored to must NOT be silently
+    // promoted as the new kept tree; it stays `tree.ok === false` so the trial row records
+    // `tree_ref: null` and the failure stays visible instead of quietly becoming the baseline.
+    if (action === "restore" && !tree.ok && !baseline) tree = { ...snapshot(contract.scope_id, cwd), fell_back_to: "snapshot" };
   }
 
   // `baseline_trial` is the parent link — the experiment DAG (lineage, PARENT_OF and a genuine
   // SUPERSEDES edge) delivered as one field, with no graph store behind it.
-  const trialNo = readTrials(trialsPath).length + 1;
+  //
+  // COUNTED WITHIN THE SCOPE, NEVER ACROSS THE FILE. This used to be
+  // `readTrials(trialsPath).length + 1` — every row in the run, whoever wrote it — which is a
+  // read-modify-write counter over a file that concurrent scopes append to. Scopes build in
+  // parallel, so several `verify t0` processes reach this line at once, each reads the same length
+  // and each writes the same ordinal: four concurrent scopes produced ordinals [1,1,1,4] and
+  // [1,1,3,3]. The ordinal is only ever consumed WITHIN a scope — `baseline` is picked from
+  // `priorTrials`, which is already filtered by `scope_id`, and the ratchet report groups by scope
+  // before it sorts — so counting the scope's own prior trials is both the race-free answer and the
+  // one the readers actually want. Two attempts of the SAME scope cannot race: one worker leg owns
+  // a scope and runs its attempts in sequence.
+  const trialNo = priorTrials.length + 1;
   const row = {
     schema_version: 1,
     trial: trialNo,
+    ...(runId ? { run_id: runId } : {}),
     round, attempt,
     scope_id: contract.scope_id,
     at: new Date().toISOString(),
@@ -465,6 +578,3 @@ async function main() {
   process.exit(verdict.overall === "green" ? 0 : 1);
 }
 
-if (isMain(import.meta.url)) {
-  main();
-}

package/{skills/tech-lead/scripts/trace-lint.mjs → kernel/verify/trace.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:
 //
@@ -30,18 +30,17 @@
 // Writes  LOCAL  .shapeup/<slug>/trace/report.json       (regenerated each run)
 //         LOCAL  .shapeup/<slug>/trace/wiring.mmd         (Mermaid view of the checked graph)
 //
-// Zero dependencies, zero network — same discipline as t0-verify.mjs / compile-order.mjs.
+// Zero dependencies, zero network — same discipline as `harness verify t0` / `harness compile`.
 //
-// Usage:  node skills/tech-lead/scripts/trace-lint.mjs --slug <slug> [--cwd <dir>] [--gate] [--quiet]
+// Usage:  node kernel/harness.mjs verify trace --slug <slug> [--cwd <dir>] [--gate] [--quiet]
 // Exit:   advisory (default) → always 0. --gate → 1 when overall is red.
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync } from "node:fs";
 import { resolve, join, dirname, relative, isAbsolute } from "node:path";
-import { readBoard } from "./compile-order.mjs";
-import { isMain } from "./lib/is-main.mjs";
-import { runArgs } from "./lib/argv.mjs";
-import { sharedRoot, traceDir, relLocal } from "./lib/paths.mjs";
-import { readContract, unreadableReason, WIRING_MAP, PROJECT_PROFILE } from "./lib/contract-md.mjs";
+import { readBoard } from "../compile.mjs";
+import { runArgs } from "../lib/argv.mjs";
+import { sharedRoot, traceDir, relLocal } from "../lib/paths.mjs";
+import { readContract, unreadableReason, LEGACY_LAYOUT, WIRING_MAP, PROJECT_PROFILE } from "../lib/contract.mjs";
 
 // --- requirements.md registry parser -----------------------------------------
 // A committed markdown table: | REQ-id | clause (verbatim) | source | status | note |
@@ -260,7 +259,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.
@@ -273,6 +272,16 @@ export function traceLint(slug, { cwd, gate = false }) {
       skipped_reason: `wiring-map.md is present but unreadable (${wiringUnreadable}) — reachability cannot be claimed.` };
   }
 
+  // A map that parsed only through the migration reader still WORKS — but silence about that is
+  // how a temporary fallback becomes a permanent second format. Warn, so the next `wire` converges
+  // the file on the canonical table rather than the reader carrying the old shape indefinitely.
+  if (wiringMap && wiringMap[LEGACY_LAYOUT]) {
+    findings.push({ severity: "warn", code: "WIRING-LEGACY-LAYOUT", message:
+      "wiring-map.md is in the pre-canonical per-use-case layout (`### UC-xx` + a `| Field | Value |` table). " +
+      "It reads correctly through the migration reader, but the canonical form is one `## Wiring` table — " +
+      "re-run the wire operation to converge it, so this artifact stops having two shapes." });
+  }
+
   if (wiringMap) {
     let profileFound = null;
     try { profileFound = readContract(profilePath, PROJECT_PROFILE); }
@@ -329,7 +338,7 @@ export function traceLint(slug, { cwd, gate = false }) {
 // ---------------------------------------------------------------------------
 /** The typed argv contract (see `./lib/argv.mjs`). */
 export const ARGV_SPEC = {
-  usage: "trace-lint.mjs --slug <slug> [--cwd <dir>] [--gate] [--quiet]",
+  usage: "harness.mjs verify trace --slug <slug> [--cwd <dir>] [--gate] [--quiet]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   slug: { type: "str", required: true },
   cwd: { type: "path" },
@@ -337,9 +346,15 @@ export const ARGV_SPEC = {
   quiet: { type: "flag" },
 };
 
-const isMainModule = isMain(import.meta.url);
-if (isMainModule) {
-  const args = runArgs(ARGV_SPEC);
+/**
+ * Run the traceability oracle over the spine artifacts and write its report.
+ *
+ * @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 slug = args.slug;
   const gate = !!args.gate;

package/oracles/_shared.mjs

@@ -1,4 +1,4 @@
-// Shared helpers for evaluation-contract oracle runners (Stage G of the audit).
+// Shared helpers for evaluation-contract oracle runners.
 //
 // The `process` oracle (step 1–3) inlined these; the test/snapshot/http oracles (steps 4–5)
 // import them so the matching grammar is identical across the registry. Keeping one definition

package/oracles/http-oracle.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// `http` oracle for the evaluation contract (Stage G, step 5 of the audit).
+// `http` oracle for the evaluation contract.
 //
 // Deliverable: a service / API. The oracle starts the server, waits until it is reachable,
 // sends each criterion's request, and grades the OBSERVED response (status + body) — never the
@@ -34,7 +34,7 @@ import { spawn } from "node:child_process";
 import { createServer } from "node:net";
 import { readFileSync } from "node:fs";
 import { matchNum, toRegExp, formatReport } from "./_shared.mjs";
-import { isMain } from "../skills/tech-lead/scripts/lib/is-main.mjs";
+import { isMain } from "../kernel/lib/argv.mjs";
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 

package/oracles/index.mjs

@@ -1,4 +1,4 @@
-// Oracle registry for the evaluation contract (Stage G of the audit).
+// Oracle registry for the evaluation contract.
 //
 // The single entry point `spec-evaluator` dispatches through when a criterion / Test-Surface row
 // carries an `oracle:` tag. Adding a new oracle type = registering one runner here (the spec's

package/oracles/process-oracle.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Shared `process` oracle for the evaluation contract (Stage G of the audit).
+// Shared `process` oracle for the evaluation contract.
 //
 // This is the promoted, parameterized form of the todo-cli prototype: instead of hard-coding
 // criteria, it reads a *declarative contract* (a list of criteria, each with a `probe` and an
@@ -25,7 +25,7 @@ import { spawnSync } from "node:child_process";
 import { mkdtempSync, writeFileSync, rmSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { isMain } from "../skills/tech-lead/scripts/lib/is-main.mjs";
+import { isMain } from "../kernel/lib/argv.mjs";
 
 const CRASH_RE = /at\s+.*:\d+:\d+|Traceback|panic:|unhandled|Segmentation fault/i;
 

package/oracles/snapshot-oracle.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// `snapshot` oracle for the evaluation contract (Stage G, step 4b of the audit).
+// `snapshot` oracle for the evaluation contract.
 //
 // Deliverable: a generator or a pure refactor — something whose acceptance is "produces exactly
 // this output". The oracle runs the deliverable, captures its stdout, and diffs it against a
@@ -28,7 +28,7 @@ import { spawnSync } from "node:child_process";
 import { readFileSync, existsSync } from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
 import { CRASH_RE, formatReport } from "./_shared.mjs";
-import { isMain } from "../skills/tech-lead/scripts/lib/is-main.mjs";
+import { isMain } from "../kernel/lib/argv.mjs";
 
 // Normalize so trailing spaces and final-newline differences never cause a spurious FAIL.
 function normalize(s) {

package/oracles/test-oracle.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// `test` oracle for the evaluation contract (Stage G, step 4a of the audit).
+// `test` oracle for the evaluation contract.
 //
 // Deliverable: a library / module whose acceptance is "its own test suite is green".
 // The oracle runs the project's test command and grades the OBSERVED suite result —
@@ -31,7 +31,7 @@
 import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { matchNum, toRegExp, formatReport } from "./_shared.mjs";
-import { isMain } from "../skills/tech-lead/scripts/lib/is-main.mjs";
+import { isMain } from "../kernel/lib/argv.mjs";
 
 // Parse common test-runner output into { total, pass, fail, failing[] }.
 function parseSuite(out) {

package/package.json

@@ -1,22 +1,22 @@
 {
   "name": "shapeup-sdlc",
-  "version": "1.6.3",
-  "description": "Shape Up for coding agents — with gates the agent can't talk its way past. Harness for Claude Code, compiled to Cursor, Antigravity and Codex.",
+  "version": "3.0.0",
+  "description": "Shape Up for coding agents \u2014 with gates the agent can't talk its way past. Harness for Claude Code.",
   "bin": {
     "shapeup-sdlc": "bin/init.mjs"
   },
   "files": [
+    ".claude-plugin/",
+    ".claude/settings.local.example.json",
+    ".env.shapeup.example",
+    "AGENTS.md",
+    "SECURITY.md",
     "bin/",
-    "skills/",
-    "!skills/**/evals/**",
-    "hooks/",
     "commands/",
+    "hooks/",
+    "kernel/",
     "oracles/",
-    ".claude-plugin/",
-    "AGENTS.md",
-    ".env.shapeup.example",
-    ".claude/settings.local.example.json",
-    "SECURITY.md"
+    "skills/"
   ],
   "repository": {
     "type": "git",
@@ -35,13 +35,11 @@
   "scripts": {
     "test": "node tests/structural.mjs",
     "demo": "node tools/demo/record-demo.mjs",
-    "distribute": "node tools/distribute.js"
+    "test:grant": "node tests/grant/executing-grant.mjs"
   },
   "keywords": [
     "shapeup",
     "sdlc",
-    "cursor",
-    "antigravity",
     "claude-code"
   ],
   "author": "Liberty Nguyen",

package/skills/ba-pitch-analyzer/SKILL.md

@@ -24,16 +24,16 @@ Invoked as `--order <path>`. Fields you may rely on (absent = unknown; surface i
 
 | Field | What it is |
 |---|---|
-| `operation` | `analyze` (pitch → full spec tree + board) · `generate-board` (regenerate the LOCAL board from the committed spec) · `reconcile` (fold discovered-ledger items into the board + UC invariants) · `retrofit-surface` (append `## Test Surface` to a pre-surface spec) · `coverage` (extract atomic requirement clauses → the SHARED `requirements.md` registry) |
+| `operation` | `analyze` (pitch → full spec tree + board) · `reconcile` (fold discovered-ledger items into the board + UC invariants) · `retrofit-surface` (append `## Test Surface` to a pre-surface spec) · `coverage` (extract atomic requirement clauses → the SHARED `requirements.md` registry) |
 | `payload.pitch` | The pitch/PRD path (analyze) |
 | `payload.requirements` | (coverage) the REQ source to extract atomic clauses from — pitch / a customer-requirements doc / the use-case bodies. Absent → default to the pitch and record the choice in `assumptions[]` |
-| `payload.lens` | `lite` \| `standard` \| `cross-context`. Absent → judge it: LITE for ≤2-week appetite, no third-party, ≤3 user-facing actions; STANDARD for multi-team, third-party, or bigger appetite; genuinely unclear → one binary question / one `escalates[]` entry |
+| `payload.lens` | `lite` \| `standard` \| `cross-context`. Absent → judge it: LITE for ≤2-week appetite, no third-party, ≤3 user-facing actions; STANDARD for multi-team, third-party, or bigger appetite; genuinely unclear → one binary question, or `status: "escalated"` with the question in `deviations[]` |
 | `payload.orient_dir` | The Scout's artifacts — `code-surface.md` IS your codebase map (do not re-scan), `discovered-seed.md` seeds task gen, `spike-*.md` feeds feasibility |
 | `payload.spec_folder` / `payload.feature` | Where the committed tree lives / the slug |
 | `payload.discovered_ledger` | (reconcile) the ledger whose raw `[+]`/`~` lines you fold in |
 | `payload.kb_rules_path` | Team guidelines (read if present) — steering, never spec |
-| `substrate.allowed / append_only / frozen` | Your write contract for THIS operation. The old frozen-zone prose is now data the sandbox hook enforces: respect it, and when an operation genuinely needs a file outside it, ESCALATE — never widen |
-| `interaction.pause_gates` | Caller policy. `true` (standalone default): pause at the phase checkpoints below, max 2 questions each. `false`: run straight through, surfacing questions as `assumptions[]`/`escalates[]` instead |
+| `substrate.allowed / append_only / frozen` | Your write contract for THIS operation. The old frozen-zone prose is now data the sandbox hook enforces (reading the order's envelope): respect it, and when an operation genuinely needs a file outside it, ESCALATE — never widen |
+| `interaction.pause_gates` | Caller policy. `true` (standalone default): pause at the phase checkpoints below, max 2 questions each. `false`: run straight through, surfacing questions as `assumptions[]` (or `deviations[]` when they block) instead |
 
 ---
 
@@ -50,7 +50,7 @@ its phase; templates live in `assets/templates/`.
 2  DDD         bounded contexts, aggregates (new vs extended), value objects, domain events,
                repository interfaces → domain-model.md          [references/ddd-patterns.md]
 2b CONTRACTS   (standard lens) typed Request/Response/Error per repository; two-pass rule:
-               unresolvable at spec time → `⏳ TBD — verify in TASK-NNN-spike-…`, resolved
+               unresolvable at spec time → `⏳ TBD — verify in the [UC-x] spike`, resolved
                post-SPIKE with citation → contracts/            [references/contract-patterns.md]
 3  UX          per screen: state table (idle→loading→error→success), error cases with
                message+action, ASCII flows → ux-behavior.md     [references/ux-behavior-patterns.md]
@@ -64,10 +64,10 @@ its phase; templates live in `assets/templates/`.
 6  TASKS       atomic, ordered, executable → tasks/ (LOCAL root; the one uncommitted branch
                of the tree — regenerable, machine-local)        [references/task-generation.md]
 7  DERIVE+LINT mechanical, not yours to grade:
-               node "${CLAUDE_PLUGIN_ROOT}/skills/ba-pitch-analyzer/scripts/board-derive.mjs" --slug <slug> --write
+               node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" reduce board --slug <slug> --write
                  (unlocks = depends_on inverse; Σ hours; critical path; appetite arithmetic —
                   overflow is a fact you REPORT for the caller's HAMMER gate, never resolve)
-               node "${CLAUDE_PLUGIN_ROOT}/skills/ba-pitch-analyzer/scripts/spec-lint.mjs" --slug <slug>
+               node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" verify spec --slug <slug>
                  (structure, wikilinks, edge symmetry — fix reds, then re-run; you never
                   self-grade with a hand-walked checklist)
                → scope-summary.md + synthesis.md (traceability matrix, risk register,
@@ -94,15 +94,13 @@ second path to green.
 
 ---
 
-## The other four operations — same craft, different payload + whitelist
+## The other three operations — same craft, different payload + whitelist
 
 | Operation | Essence | Never |
 |---|---|---|
-| `generate-board` | Re-derive the full task set fresh from the committed `usecases/` + `domain-model.md` (+ scope contracts if present — tasks respect their substrates). Numbering restarts at TASK-001. Initialize `status` from committed mechanical truth at SCOPE granularity (a scope with hill shard FINISHED → its tasks start `done`) — never join on task id; ids renumber per machine, the scope is the stable key. Then board-derive `--write` + regenerate scope-summary.md | touch the committed spec docs (frozen in your substrate) |
-| `reconcile` | Verify `ledger.feature == payload.feature` (mismatch → STOP). Map each `[+]` Keep item → its owning UC; new task continues numbering (never renumber); `~`/Cut → synthesis "Hammered Out" row, no file. A Keep item asserting a new invariant → APPEND `[INV-NN]` + TS-INV row to that UC (append-only sections in your substrate). A new actor/action with no UC → `escalates[]` (spec-ambiguity): spawning a UC mid-cycle is silent re-shaping, the PO decides. Finish with board-derive (appetite overflow → report) + spec-lint | re-run phases 1–5; edit UC Steps; resolve the appetite HAMMER yourself |
+| `reconcile` | Verify `ledger.feature == payload.feature` (mismatch → STOP). Map each `[+]` Keep item → its owning UC; new task continues numbering (never renumber); `~`/Cut → synthesis "Hammered Out" row, no file. A Keep item asserting a new invariant → APPEND `[INV-NN]` + TS-INV row to that UC (append-only sections in your substrate). A new actor/action with no UC → `status: "escalated"` + a `deviations[]` spec-ambiguity entry: spawning a UC mid-cycle is silent re-shaping, the PO decides. Finish with board-derive (appetite overflow → report) + spec-lint | re-run phases 1–5; edit UC Steps; resolve the appetite HAMMER yourself |
 | `retrofit-surface` | Append `## Test Surface` (derived rows only, after Error Cases) to each UC of a pre-surface spec; an all-sources-empty UC gets the explicit empty-sources line | touch anything else — append-only substrate |
-| `coverage` | Extract **atomic** customer requirement clauses from `payload.requirements` (default: the pitch) and write the SHARED `shapeup/<slug>/requirements.md` registry: one `\| REQ-id \| clause (verbatim) \| source \| status \| note \|` row per clause. Split compound sentences into one testable clause each — the audit's dropped clauses ("side-step OR lure enemies into traps", "low-res world textures") were *lost inside* a bigger sentence. **Assign REQ-ids ONCE and freeze them** (they behave like scope_id, never TASK-NNN — every `covers:` link rots otherwise): re-running, append new clauses with fresh ids, mark a removed clause `CUT (PO-approved)`, never renumber or delete. Status starts `covered` (a live requirement); only the PO sets `CUT`. The REQ source itself is frozen — the registry is a separate derived file | edit the REQ source; renumber existing REQ-ids; delete a dropped clause instead of marking it CUT; invent a requirement not in the source |
-
+| `coverage` | Extract **atomic** customer requirement clauses from `payload.requirements` (default: the pitch) and write the SHARED `shapeup/<slug>/requirements.md` registry: one `\| REQ-id \| clause (verbatim) \| source \| status \| note \|` row per clause. Split compound sentences into one testable clause each — a clause lost *inside* a bigger sentence is a requirement nothing can be traced to. **Assign REQ-ids ONCE and freeze them** (they behave like scope_id, never TASK-NNN — every `covers:` link rots otherwise): re-running, append new clauses with fresh ids, mark a removed clause `CUT (PO-approved)`, never renumber or delete. Status starts `covered` (a live requirement); only the PO sets `CUT`. The REQ source itself is frozen — the registry is a separate derived file | edit the REQ source; renumber existing REQ-ids; delete a dropped clause instead of marking it CUT; invent a requirement not in the source |
 ---
 
 ## Anti-rationalization table
@@ -115,12 +113,19 @@ second path to green.
 | "My output looks complete, score it 92" | You don't grade yourself. spec-lint reports facts; the judge judges. |
 | "The appetite overflow is small, drop a nice-to-have myself" | Overflow is a HAMMER gate for the caller. You report the fact and the candidate cuts. |
 | "Re-scanning the codebase is safer than trusting orient" | code-surface.md IS the map. Re-scanning burns tokens and forks the truth. |
-| "unlocks is quick to fill in by hand" | Hand-authored unlocks produced 10 asymmetric edges (KB-BA-001). board-derive computes it. |
+| "unlocks is quick to fill in by hand" | Hand-authored unlocks drift asymmetric — observed, repeatedly. board-derive computes it. |
 
 ---
 
 ## Output contract — the WorkResult
 
+**Escalation rule.** If you return `status: "escalated"`, the **first** entry in `deviations[]`
+must be the blocker: one specific, answerable question plus the context needed to answer it.
+Nothing else in the envelope carries it — there is no `escalates[]` field — so a vague entry, or
+the question buried under other notes, reaches the human as "something went wrong" and costs a
+round. Write it so someone without your context can answer it in one reply.
+
+
 Domain artifacts land inside your substrate (the committed spec tree + the LOCAL board). Then
 write `.shapeup/<slug>/results/<order-suffix>.json`:
 
@@ -129,9 +134,8 @@ write `.shapeup/<slug>/results/<order-suffix>.json`:
   "schema_version": 1, "order_id": "<copied>", "worker": "ba-pitch-analyzer",
   "status": "done | partial | escalated",
   "artifacts": ["shapeup/<slug>/spec/domain-model.md", "…"],
-  "escalates": [ { "kind": "spec-ambiguity", "question": "New actor 'auditor' has no UC — add UC-07 or cut?" } ],
   "assumptions": ["lens=standard — third-party PSP present"],
-  "deviations": [],
+  "deviations": [ "ESCALATE spec-ambiguity — New actor 'auditor' has no UC — add UC-07 or cut?" ],
   "discoveries": [ { "marker": "+", "line": "appetite overflow 12h — candidate cuts: TASK-014, TASK-017" } ]
 }
 ```
@@ -161,15 +165,16 @@ status flips for built work (ingest's job), scope contracts (scope-architect's),
 /ba-pitch-analyzer --order .shapeup/checkout-vnpay/orders/analyze.json
 
 # Standalone — the preamble shim compiles the order (mode: standalone, pause_gates: true):
-#   node "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/compile-order.mjs" --operation analyze --slug <slug> \
+#   node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" compile --operation analyze --slug <slug> \
 #        --worker ba-pitch-analyzer --payload '{"pitch": "docs/pitch.md", "lens": "standard"}'
 /ba-pitch-analyzer docs/pitch.md                      # operation: analyze, lens judged
 /ba-pitch-analyzer --lens standard docs/pitch.md      # lens pinned
 ```
 
 Standalone keeps exactly two flags: the pitch input and `--lens`. Every retired flag is now
-caller context: `--tasks-only` → a generate-board order, `--from-discovered` → a reconcile
-order, `--surface-only` → a retrofit-surface order, `--remap`/`--split` → scope-architect
-orders, `--status` → read `spec-lint.mjs`/`board-derive.mjs` output (zero LLM tokens),
+caller context: `--tasks-only`/`--from-discovered` → a reconcile order, `--surface-only` → a
+retrofit-surface order, `--coverage` → a coverage order, `--remap`/`--split` → a
+scope-architect `map-scopes` order,
+`--status` → read `harness verify spec`/`harness reduce board` output (zero LLM tokens),
 `--auto`/`--skip-gate*` → `interaction.pause_gates`, `--upgrade` → an analyze order with the
 standard lens over an existing lite tree (reconciliation pass: extend, never overwrite Steps).

package/skills/ba-pitch-analyzer/assets/templates/_index.tmpl.md

@@ -64,7 +64,7 @@ audit_rules_version: "2.5"
 
 ## Audit Report
 
-*Generated from spec-lint.mjs output — do not edit manually.*
+*Generated from harness verify spec output — do not edit manually.*
 *skill_version: 2.1 | audit_rules_version: 2.1*
 
 ### Score Summary