shapeup-sdlc 1.7.0 → 3.0.0

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

@@ -7,7 +7,7 @@
 // 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 };
 }
 
 /**
@@ -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.
  *
@@ -327,7 +395,7 @@ function sha256(text) {
  *
  * 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}

@@ -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 |
@@ -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/http-oracle.mjs

@@ -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/process-oracle.mjs

@@ -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

@@ -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

@@ -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,21 +1,22 @@
 {
   "name": "shapeup-sdlc",
-  "version": "1.7.0",
+  "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/",
-    "hooks/",
     "commands/",
+    "hooks/",
+    "kernel/",
     "oracles/",
-    ".claude-plugin/",
-    "AGENTS.md",
-    ".env.shapeup.example",
-    ".claude/settings.local.example.json",
-    "SECURITY.md"
+    "skills/"
   ],
   "repository": {
     "type": "git",
@@ -33,7 +34,8 @@
   },
   "scripts": {
     "test": "node tests/structural.mjs",
-    "demo": "node tools/demo/record-demo.mjs"
+    "demo": "node tools/demo/record-demo.mjs",
+    "test:grant": "node tests/grant/executing-grant.mjs"
   },
   "keywords": [
     "shapeup",

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

@@ -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,
@@ -165,7 +165,7 @@ 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
@@ -175,6 +175,6 @@ Standalone keeps exactly two flags: the pitch input and `--lens`. Every retired
 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 `spec-lint.mjs`/`board-derive.mjs` output (zero LLM tokens),
+`--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

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

@@ -14,9 +14,12 @@ dependent implementation tasks can proceed.*
 
 ## Detected Third-Party Dependencies
 
-| # | Service | Capability Claimed | Status | SPIKE Task |
-|---|---------|-------------------|--------|------------|
-| API-01 | [ServiceName] | [What pitch claims this API can do] | ❓ UNVERIFIED | [[TASK-001-spike-[api]]] |
+| # | Service | Capability Claimed | Status | Spike |
+|---|---------|-------------------|--------|-------|
+| API-01 | [ServiceName] | [What pitch claims this API can do] | ❓ UNVERIFIED | ⏳ open |
+
+<!-- The Spike column records STATUS (⏳ open / ✅ done / — none), never a task id.
+     This document is committed; the board is not, and its ids renumber per machine. -->
 
 ---
 
@@ -49,10 +52,12 @@ Specifically: [quote or paraphrase relevant pitch sentence].
 | Partially supported | [Describe workaround] | +[N]h |
 | Not supported | [Describe alternative or de-scope] | [TBD with PO] |
 
-**Dependent Tasks:**
-<!-- List all tasks blocked until this investigation is complete -->
-- [[TASK-NNN]] — [reason blocked]
-- [[TASK-NNN]] — [reason blocked]
+**Blocked Use Cases:**
+<!-- What cannot be built until this investigation resolves. Name the committed UC, never
+     a task id: this doc is committed and task ids are machine-local. The tasks are found
+     by inverting use_case_refs over the LOCAL board. -->
+- [[usecases/UC-Name]] — [reason blocked]
+- [[usecases/UC-Name]] — [reason blocked]
 
 **Decision Gate:**
 - All questions answered + capability confirmed → update `contracts/[repo].contract.md`, remove ⏳ TBD fields, notify SPIKE complete

package/skills/ba-pitch-analyzer/assets/templates/contracts/third-party-api.contract.tmpl.md

@@ -5,7 +5,9 @@ feature: "[feature-slug]"
 repository: "[RepoName]"
 service: "[ServiceName]"
 feasibility_ref: "API-[NN]"
-spike_task: "[[TASK-NNN-spike-[api]]]"
+spike_status: open       # open | done — STATUS, never a task id: this contract is
+                         # committed and board ids renumber per machine. The spike is
+                         # reached through feasibility_ref above.
 status: speculative      # → confirmed after SPIKE done
 skill_version: "2.3"
 ---
@@ -14,13 +16,14 @@ skill_version: "2.3"
 
 ## Source Type: `third-party-api`
 ## Service: [ServiceName] ([REST API / SDK])
-## Feasibility: ⏳ UNVERIFIED → see [[api-feasibility#API-NN]] + [[TASK-NNN-spike-[api]]]
+## Feasibility: ⏳ UNVERIFIED → see [[api-feasibility#API-NN]]
 
 ---
 
 > ⚠️ **SPECULATIVE CONTRACT**
 > Fields marked `⏳ TBD` are derived from pitch assumptions and community references.
-> All `⏳ TBD` entries MUST be confirmed and replaced during [[TASK-NNN-spike-[api]]].
+> All `⏳ TBD` entries MUST be confirmed and replaced by the spike tracked at
+> [[api-feasibility#API-NN]].
 > Implementation tasks depending on this repository are **blocked** until no `⏳ TBD` remains.
 
 ---

package/skills/ba-pitch-analyzer/assets/templates/cross-context/migration-plan.tmpl.md

@@ -13,7 +13,8 @@ status: draft
 # Migration Plan: FEATURE TITLE
 
 > Generated only when feature modifies existing production schema.
-> Each migration task maps to a TASK-M0N in tasks/_index.md.
+> Each migration step anchors to a committed use case; the tasks that carry it are found
+> by inverting `use_case_refs` over the LOCAL board, never linked from here.
 
 ---
 
@@ -31,7 +32,7 @@ status: draft
 
 ## Migration Tasks
 
-### TASK-M01 — [description, e.g. Add nullable columns]
+### STEP-1 — [description, e.g. Add nullable columns]
 
 ```sql
 -- UP
@@ -46,7 +47,7 @@ Safe to run: during deploy / after deploy / off-hours only
 
 ---
 
-### TASK-M02 — [description, e.g. Backfill existing rows]
+### STEP-2 — [description, e.g. Backfill existing rows]
 
 ```sql
 -- UP (run in batches of 1000 to avoid lock escalation)
@@ -66,7 +67,7 @@ Estimated rows: ~N | Estimated time: ~Ns | Lock: none
 
 ---
 
-### TASK-M03 — [description, e.g. Enforce NOT NULL constraint]
+### STEP-3 — [description, e.g. Enforce NOT NULL constraint]
 
 ```sql
 -- UP — only run after M02 verified

package/skills/ba-pitch-analyzer/assets/templates/cross-context/team-handoff.tmpl.md

@@ -21,19 +21,29 @@ status: draft
 
 | From Team | To Team | Artifact | Ready When | Blocker Risk |
 |-----------|---------|----------|-----------|-------------|
-| [Team A] (API) | [Team B] (Mobile) | [[contracts/[repo].contract.md]] | TASK-00N done | 🔴 blocks Mobile TASK-00N |
-| [Team B] (API) | [Team A] (API) | `EventName` schema | TASK-00N done | 🟡 blocks integration test |
-| [Team B] (Mobile) | QA | E2E test cases | TASK-00N done | 🟡 blocks QA sprint entry |
+| [Team A] (API) | [Team B] (Mobile) | [[contracts/[repo].contract.md]] | [[usecases/UC-Name]] green | 🔴 blocks Mobile [[usecases/UC-Name]] |
+| [Team B] (API) | [Team A] (API) | `EventName` schema | [[usecases/UC-Name]] green | 🟡 blocks integration test |
+| [Team B] (Mobile) | QA | E2E test cases | [[usecases/UC-Name]] green | 🟡 blocks QA sprint entry |
+
+<!-- Readiness is stated against a committed UC (or a scope_id), never a task id: this
+     register is committed and shared across teams, and board ids are per-machine. -->
 
 ---
 
 ## Blocking Dependencies
 
+<!--
+  Key every row on a USE CASE or a scope_id, never a task id. This document is committed and
+  crosses a team boundary; board ids live in the gitignored tier and each team's board numbers
+  its own, so one board id names a different piece of work on every machine that reads this.
+  spec-lint reds a board id anywhere in the committed tree (TIER-DIRECTION).
+-->
+
 ```
-[Team B] CANNOT start TASK-00N ([description])
-  until [Team A] completes TASK-00N ([description])
+[Team B] CANNOT start [UC-x] ([description])
+  until [Team A] completes [UC-y] ([description])
   Mitigation: use contract stub from [[contracts/[repo].contract.md]]
-  Stub ready: TASK-00N (unblocked — no dependency)
+  Ready now: [UC-z] (unblocked — no dependency)
 
 [Team C] CANNOT start integration tests
   until [Team A] EventName schema is stable
@@ -46,12 +56,12 @@ status: draft
 
 ```
 Wave 1 — No cross-team dependencies (start immediately):
-  [Team A]: TASK-001, TASK-002, TASK-003
-  [Team B]: TASK-004, TASK-005 (using contract stub)
+  [Team A]: [UC-a], [UC-b], [UC-c]
+  [Team B]: [UC-d], [UC-e] (using contract stub)
 
-Wave 2 — After Team A TASK-003 done:
-  [Team B]: TASK-006 (replace stub with real contract)
-  [Team C]: TASK-007 (integration tests — real contract available)
+Wave 2 — After Team A [UC-c] done:
+  [Team B]: [UC-f] (replace stub with real contract)
+  [Team C]: integration tests (real contract available)
 
 Wave 3 — After Wave 2 complete:
   QA: E2E test suite
@@ -64,7 +74,7 @@ Wave 3 — After Wave 2 complete:
 | Trigger | Owner | Notify | Channel |
 |---------|-------|--------|---------|
 | Contract changes after stub distributed | [Team A] | [Team B], QA | [channel] |
-| TASK-00N delayed > 1 day | [Team A] | [Team B] | [channel] |
+| A wave-1 use case delayed > 1 day | [Team A] | [Team B] | [channel] |
 | Schema breaking change detected | Any | All teams | [channel] |
 
 ---
@@ -72,7 +82,7 @@ Wave 3 — After Wave 2 complete:
 ## Definition of Done (Cross-Context)
 
 Feature is complete when ALL of the following are true:
-- [ ] All TASK-MNN migrations run and verified in staging
+- [ ] Every migration STEP run and verified in staging
 - [ ] All contracts have no remaining ⏳ TBD fields
 - [ ] Event choreography happy path verified end-to-end
 - [ ] All dead-letter scenarios have runbooks