shapeup-sdlc 3.7.12 → 3.9.0

package/kernel/verify/t0.mjs

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
 // 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
+// Runs a scope's e2e fixtures and its DB probe (zero LLM tokens). Writes one
 // verdict artifact per attempt that spec-evaluator (T1) must cite; a verdict without it is
 // structurally invalid. No agent can fabricate this file's contents
 // because it is produced by actually running the commands.
@@ -30,7 +29,7 @@
 //
 // Usage:
 //   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]
+//        --round N --attempt M [--cwd <dir>] [--out <dir>]
 //        [--no-ratchet]
 //
 // Exit code: 0 = overall green, 1 = overall red (mirrors the oracle convention), 2 = bad argv.
@@ -185,80 +184,45 @@ export function runDbProbe(dbProbeCmd, cwd) {
 }
 
 /**
- * Re-run every FINISHED scope's fixtures from the seesaw registry (regression guard).
- * @param {(string|null)} registryPath - Path to the seesaw registry JSON (absent/unreadable → skipped).
- * @param {string} cwd - Working directory.
- * @returns {{ran:boolean, pass:boolean, scopes_checked:string[], failing:string[], error?:string}}
- *   ran=false/pass=true when skipped; otherwise pass=true iff no prior scope regressed, with the
- *   scope ids checked and those now failing.
- */
-export function seesawCheck(registryPath, cwd) {
-  if (!registryPath || !existsSync(registryPath)) {
-    // `pass: null`, not `pass: true`: a check that did not run has no result, and recording one as
-    // clean is how "not asked" came to read as "nothing regressed". The verdict below still treats
-    // an absent seesaw as non-blocking — that part is deliberate while the arm is unwired — but the
-    // artifact now says which of the two it was.
-    return { ran: false, pass: null, scopes_checked: [], failing: [] };
-  }
-  let registry;
-  try {
-    registry = JSON.parse(readFileSync(registryPath, "utf8"));
-  } catch {
-    return { ran: false, pass: null, scopes_checked: [], failing: [], error: "registry unparsable" };
-  }
-  const scopes = registry.scopes || [];
-  const failing = [];
-  for (const s of scopes) {
-    const { pass } = runFixtures(s.fixtures, cwd);
-    if (!pass) failing.push(s.scope_id);
-  }
-  return { ran: true, pass: failing.length === 0, scopes_checked: scopes.map((s) => s.scope_id), failing };
-}
-
-/**
- * Combine fixtures + DB probe + seesaw into the overall T0 verdict.
- * @param {{fixtures:{pass:boolean}, dbProbe:({pass:boolean}|null),
- *   seesaw:{ran:boolean,pass:boolean}}} parts - The three sub-results.
- * @returns {{fixtures_green:boolean, db_probe_green:boolean, seesaw_green:boolean,
- *   overall:("green"|"red"), regression:boolean}} Per-arm greens, the overall verdict (green iff
- *   all three), and `regression` = fixtures+db green but seesaw red (the rollback-and-retry case).
+ * Combine the fixtures and the DB probe into the overall T0 verdict.
+ *
+ * THE SEESAW ARM IS GONE (3.8.0), by a Betting Table decision rather than by neglect. It was
+ * declared in the schema, the docs and this function, and nothing ever wrote the registry it read,
+ * so it never ran once in any recorded run — while its absence held the hill's top phase shut:
+ * FINISHED required `seesaw.ran && seesaw.pass`, and the 38 committed hill shards across the live
+ * consumer's features contain no FINISHED at all. A cross-scope regression is still caught by the
+ * round build gate, which builds and launches the whole feature once per round; what the arm would
+ * have added is attribution and an earlier signal, at the price of re-running every finished
+ * scope's fixtures on every attempt — minutes per attempt on an eighteen-scope feature.
+ *
+ * @param {{fixtures:{pass:boolean}, dbProbe:({pass:boolean}|null)}} parts - The two sub-results.
+ * @returns {{fixtures_green:boolean, db_probe_green:boolean, overall:("green"|"red")}} Per-arm
+ *   greens and the overall verdict, green iff both.
  */
-export function computeVerdict({ fixtures, dbProbe, seesaw }) {
+export function computeVerdict({ fixtures, dbProbe }) {
   const fixturesGreen = fixtures.pass;
   const dbGreen = dbProbe === null || dbProbe.pass;
-  // A seesaw that did not run does not hold the verdict red — the arm is declared and unwired, and
-  // blocking every build on it would be a different defect. It does not make it green either: the
-  // hill requires `ran && pass` before a scope may reach FINISHED, and `seesaw_green` here means
-  // "nothing this check found is wrong", which is true of a check that found nothing because it
-  // never looked.
-  const seesawGreen = seesaw.ran ? seesaw.pass === true : true;
   return {
     fixtures_green: fixturesGreen,
     db_probe_green: dbGreen,
-    seesaw_green: seesawGreen,
-    overall: fixturesGreen && dbGreen && seesawGreen ? "green" : "red",
-    // A regression is specifically fixtures/db green but seesaw red — the case that should
-    // trigger rollback+retry (spec §3.5) rather than "go fix the new scope's own bug".
-    regression: fixturesGreen && dbGreen && !seesawGreen,
+    overall: fixturesGreen && dbGreen ? "green" : "red",
   };
 }
 
 /**
- * The comparable T0 outcome — a VECTOR, not a float, because the three arms are not fungible.
+ * The comparable T0 outcome — a VECTOR, not a float, because the arms are not fungible.
  *
  * Every number here is a reduce over data `writeArtifact` already persists (`fixtures:
  * [{cmd, exit, pass}]`). Nothing new is measured; a number that has always been on disk is
  * finally counted.
  *
- * @param {{fixtures:{results:Array<{pass:boolean}>}, dbProbe:({pass:boolean}|null),
- *   seesaw:{ran:boolean, failing:string[]}}} parts - The three T0 sub-results.
- * @returns {{regressions:number, fixtures_passed:number, fixtures_total:number,
- *   db_probe:(0|1|null)}} The score vector. `db_probe` is null when no probe is declared, which
- *   is never a failure — only an absence.
+ * @param {{fixtures:{results:Array<{pass:boolean}>}, dbProbe:({pass:boolean}|null)}} parts - The
+ *   two T0 sub-results.
+ * @returns {{fixtures_passed:number, fixtures_total:number, db_probe:(0|1|null)}} The score vector.
+ *   `db_probe` is null when no probe is declared, which is never a failure — only an absence.
  */
-export function score({ fixtures, dbProbe, seesaw }) {
+export function score({ fixtures, dbProbe }) {
   return {
-    regressions: seesaw?.ran ? (seesaw.failing || []).length : 0,
     fixtures_passed: fixtures.results.filter((r) => r.pass).length,
     fixtures_total: fixtures.results.length,
     db_probe: dbProbe === null || dbProbe === undefined ? null : (dbProbe.pass ? 1 : 0),
@@ -271,23 +235,19 @@ export function score({ fixtures, dbProbe, seesaw }) {
  * Three decisions worth defending:
  *   • A TIE IS NOT BETTER. A tie that counted as an improvement would make a sawtooth look like a
  *     ratchet, and the whole point of the Day-1 measurement is to tell those two apart.
- *   • 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 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.
  *
- * @param {{regressions:number, fixtures_passed:number, fixtures_total:number,
+ * @param {{fixtures_passed:number, fixtures_total:number,
  *   db_probe:(0|1|null)}} next - The candidate score.
- * @param {({regressions:number, fixtures_passed:number, fixtures_total:number,
+ * @param {({fixtures_passed:number, fixtures_total:number,
  *   db_probe:(0|1|null)}|null)} current - The incumbent score, or null for the first trial.
  * @returns {(boolean|null)} true = strictly better · false = not better · null = incomparable.
  */
 export function better(next, current) {
   if (current === null || current === undefined) return true; // baseline
   if (next.fixtures_total !== current.fixtures_total) return null; // the contract changed
-  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.
@@ -314,17 +274,17 @@ export function better(next, current) {
 }
 
 /**
- * Is this score a clean pass — every fixture passing, none of them absent, no outstanding regression?
+ * Is this score a clean pass — every fixture passing, and none of them absent?
  *
  * `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.
+ * @param {{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;
+  return s.fixtures_total > 0 && s.fixtures_passed === s.fixtures_total;
 }
 
 /**
@@ -352,7 +312,7 @@ export function decideStatus(verdict, crashed) {
  * Human-readable one-line summary of a score change, for the trial row's `delta` field.
  * @param {object} next - The candidate score.
  * @param {(object|null)} current - The incumbent score, or null.
- * @returns {string} e.g. "+2 fixtures", "+1 regression", "baseline", "no change".
+ * @returns {string} e.g. "+2 fixtures", "-1 db_probe", "baseline", "no change".
  */
 export function describeDelta(next, current) {
   if (!current) return "baseline";
@@ -360,10 +320,8 @@ export function describeDelta(next, current) {
     return `denominator ${current.fixtures_total} → ${next.fixtures_total}`;
   }
   const parts = [];
-  const dr = next.regressions - current.regressions;
   const df = next.fixtures_passed - current.fixtures_passed;
   const dp = (next.db_probe ?? 0) - (current.db_probe ?? 0);
-  if (dr) parts.push(`${dr > 0 ? "+" : ""}${dr} regression${Math.abs(dr) === 1 ? "" : "s"}`);
   if (df) parts.push(`${df > 0 ? "+" : ""}${df} fixture${Math.abs(df) === 1 ? "" : "s"}`);
   if (dp) parts.push(`${dp > 0 ? "+" : ""}${dp} db_probe`);
   return parts.length ? parts.join(", ") : "no change";
@@ -458,7 +416,7 @@ function sha256(text) {
  * every superseded object remains addressable).
  *
  * WHAT THIS REPLACED, and why the remedy is `wx` rather than a guard. The address used to be
- * `r<round>-a<attempt>.json`, written with a bare `writeFileSync` — and on a seesaw regression the
+ * `r<round>-a<attempt>.json`, written with a bare `writeFileSync` — and on a revert-and-retry the
  * protocol says stash, then RETRY THIS ATTEMPT, same attempt number. The address had no term for
  * 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
@@ -506,14 +464,12 @@ export function writeArtifact(outDir, round, attempt, verdictBody) {
 /** The typed argv contract (see `./lib/argv.mjs`). */
 export const ARGV_SPEC = {
   usage: "harness.mjs verify t0 <scope-contract.json> --round N --attempt M [--cwd <dir>] [--out <dir>] " +
-         "[--seesaw-registry <path>] [--no-seesaw] [--no-ratchet]",
+         "[--no-ratchet]",
   _: { arity: 1, max: 1, name: "scope-contract.json" },
   round: { type: "int", min: 1, required: true },
   attempt: { type: "int", min: 1, required: true },
   cwd: { type: "path" },
   out: { type: "path" },
-  "seesaw-registry": { type: "path" },
-  "no-seesaw": { type: "flag" },
   "no-ratchet": { type: "flag" },
 };
 
@@ -556,14 +512,7 @@ export async function cli(rawArgv) {
 
   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, 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
-    ? { ran: false, pass: true, scopes_checked: [], failing: [] } // don't seesaw on an already-red attempt
-    : seesawCheck(seesawRegistry, cwd);
-
-  const verdict = computeVerdict({ fixtures, dbProbe, seesaw });
+  const verdict = computeVerdict({ fixtures, dbProbe });
   const discovered = verdict.overall === "red" ? digestFailures({ fixtures, dbProbe }) : [];
 
   // ---- the ratchet ---------------------------------------------------------------------
@@ -573,7 +522,7 @@ export async function cli(rawArgv) {
   const trialsPath = join(outDir, "t0", "trials.jsonl");
   const priorTrials = readTrials(trialsPath).filter((t) => t.scope_id === contract.scope_id);
   const baseline = [...priorTrials].reverse().find((t) => t.status === "kept" || t.status === "rebased") || null;
-  const s = score({ fixtures, dbProbe, seesaw });
+  const s = score({ fixtures, dbProbe });
   const verdictBetter = better(s, baseline ? baseline.score : null);
   const crashed = fixtures.results.some((r) => r.error) || !!dbProbe?.error;
   const { status, action } = decideStatus(verdictBetter, crashed);
@@ -598,7 +547,6 @@ export async function cli(rawArgv) {
     // could not tell apart, and why `exit` still reads the way it always did.
     fixtures: fixtures.results.map((r) => commandEvidence(r)),
     db_probe: commandEvidence(dbProbe),
-    seesaw,
     ...verdict,
     score: s,
     discovered_tasks: discovered,
@@ -654,7 +602,7 @@ export async function cli(rawArgv) {
   appendTrial(trialsPath, row);
 
   console.log(JSON.stringify({
-    path, sha256: hash, trial, overall: verdict.overall, regression: verdict.regression,
+    path, sha256: hash, trial, overall: verdict.overall,
     score: s, status, baseline_trial: row.baseline_trial, delta: row.delta,
     tree_ref: row.tree_ref ?? keptRef(contract.scope_id),
   }, null, 2));

package/kernel/verify/trace.mjs

@@ -12,7 +12,11 @@
 //      `entry_point` via the import graph (0 import sites) is RED. This catches the *dead module*
 //      (631 lines, 26 passing tests, zero call sites), not a *dead data-path* (§2 honest boundary
 //      → §4.4). Entry point is PROFILE-GATED, never hardcoded (main.js for a game is not the seam
-//      for a web-service).
+//      for a web-service). It reports `checked: false` with a reason rather than a verdict when it
+//      cannot root the walk: an import it could not follow (the graph is missing edges, so nothing
+//      about a destination follows from not arriving there), or no reachable engine at all (with
+//      no positive control, an orphaned module and a wrong entry point are the same evidence —
+//      and a framework that registers screens by name produces the second on every run).
 //
 // Governing rule: if a script can't check it, it's decoration. This script checks a deletion and
 // an orphan — both provable from files, zero LLM tokens. What it deliberately does NOT assert:
@@ -39,8 +43,9 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSy
 import { resolve, join, dirname, relative, isAbsolute } from "node:path";
 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, reqId } from "../lib/contract.mjs";
+import { sharedRoot, traceDir, relLocal, scopesDir } from "../lib/paths.mjs";
+import { globToRegExp } from "./spec.mjs";
+import { readContract, readAllContracts, unreadableReason, LEGACY_LAYOUT, WIRING_MAP, PROJECT_PROFILE, SCOPE_CONTRACT, reqId } from "../lib/contract.mjs";
 
 // --- requirements.md registry parser -----------------------------------------
 // A committed markdown table: | REQ-id | clause (verbatim) | source | status | note |
@@ -97,37 +102,81 @@ export function coveredReqIds(board) {
 }
 
 // --- import-graph reachability -----------------------------------------------
-const SOURCE_EXTS = [".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx"];
+//
+// THE RESOLVER KNOWS ONE FAMILY OF LANGUAGES, AND IT MUST SAY SO. This list is the JS/TS family and
+// nothing else, which is correct for the stacks it was written against and silently wrong for any
+// other: a stack whose modules end in something else resolves no relative import at all, the walk
+// stops at the entry file, and every engine then looks "never imported from the entry point" — a
+// red verdict on every input, reported as a check that ran. Two things keep that from happening:
+// the extension set is widened from what the project actually declares (below), and a walk that
+// could not follow an edge reports itself unchecked instead of reporting the destination missing.
+const DEFAULT_SOURCE_EXTS = [".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx"];
 const IMPORT_RE = /(?:\bimport\b[^'"]*?from\s*|\bimport\s*|\bexport\b[^'"]*?from\s*|\brequire\s*\(\s*|\bimport\s*\()\s*['"]([^'"]+)['"]/g;
 
+/**
+ * The module extensions this project's import graph is walked with.
+ *
+ * Widened two ways, both from declarations rather than from a guess: the project profile may state
+ * `source_extensions` outright, and the entry point's own suffix is always a module extension of
+ * this project by construction — it is the one file the profile names and the walk starts from.
+ *
+ * @param {(object|null)} profile - The parsed ProjectProfile, or null.
+ * @param {(string|null)} entryPoint - The declared entry-point path, or null.
+ * @returns {{exts:string[], declared:string[], from_entry:(string|null)}} The extension set the
+ *   walk uses, plus what each widening contributed (reported, so a reader can see why it resolved).
+ */
+export function sourceExtensions(profile, entryPoint) {
+  const raw = profile?.source_extensions ?? profile?.module_extensions ?? null;
+  const list = Array.isArray(raw) ? raw : typeof raw === "string" ? raw.split(/[,\s]+/) : [];
+  const declared = list
+    .map((e) => String(e).trim())
+    .filter(Boolean)
+    .map((e) => (e.startsWith(".") ? e : "." + e));
+  const m = /(\.[A-Za-z0-9]+)$/.exec(entryPoint || "");
+  const fromEntry = m ? m[1] : null;
+  const exts = [...new Set([...DEFAULT_SOURCE_EXTS, ...declared, ...(fromEntry ? [fromEntry] : [])])];
+  return { exts, declared, from_entry: fromEntry };
+}
+
 /**
  * Resolve a relative import specifier to a repo-relative source file.
+ *
+ * The three answers are kept apart on purpose. A bare specifier is out of the app graph by design;
+ * a relative specifier carrying a non-module suffix (`./styles.css`, `./data.json`) is an asset,
+ * which imports nothing and can never be an engine; and a relative specifier that looks like a
+ * module but resolves to no file is an edge the walk could not follow — the one case that makes
+ * the resulting graph incomplete, and the caller has to be able to see it.
+ *
  * @param {string} fromFileAbs - Absolute path of the importing file.
  * @param {string} spec - The import specifier string.
  * @param {string} cwd - Repo root the result is made relative to.
- * @returns {(string|null)} The repo-relative source path (trying source extensions and `/index`),
- *   or null for a bare specifier (node_modules) or an unresolved path.
+ * @param {string[]} exts - The module extensions of this project (see `sourceExtensions`).
+ * @returns {{file:(string|null), kind:("bare"|"asset"|"resolved"|"unresolved")}} The repo-relative
+ *   source path when one was found, and which of the four answers this was.
  */
-function resolveSpecifier(fromFileAbs, spec, cwd) {
-  if (!spec.startsWith(".")) return null; // bare specifier → node_modules, out of the app graph
+function resolveSpecifier(fromFileAbs, spec, cwd, exts) {
+  if (!spec.startsWith(".")) return { file: null, kind: "bare" }; // node_modules, out of the app graph
+  const suffix = /(\.[A-Za-z0-9]+)$/.exec(spec);
   const baseAbs = resolve(dirname(fromFileAbs), spec);
-  const candidates = [baseAbs, ...SOURCE_EXTS.map((e) => baseAbs + e), ...SOURCE_EXTS.map((e) => join(baseAbs, "index" + e))];
+  const candidates = [baseAbs, ...exts.map((e) => baseAbs + e), ...exts.map((e) => join(baseAbs, "index" + e))];
   for (const c of candidates) {
-    if (existsSync(c) && statSync(c).isFile()) return relative(cwd, c).split("\\").join("/");
+    if (existsSync(c) && statSync(c).isFile()) return { file: relative(cwd, c).split("\\").join("/"), kind: "resolved" };
   }
-  return null;
+  if (suffix && !exts.includes(suffix[1])) return { file: null, kind: "asset" };
+  return { file: null, kind: "unresolved" };
 }
 
 /**
  * Normalize a declared path (entry_point / engine) to an existing repo-relative source file.
  * @param {string} p - The declared path (absolute or cwd-relative).
  * @param {string} cwd - Repo root the result is made relative to.
+ * @param {string[]} [exts] - The module extensions to try (defaults to the JS/TS family).
  * @returns {(string|null)} The repo-relative source path (trying source extensions and `/index`),
  *   or null when nothing on disk matches.
  */
-function resolveFile(p, cwd) {
+function resolveFile(p, cwd, exts = DEFAULT_SOURCE_EXTS) {
   const abs = isAbsolute(p) ? p : resolve(cwd, p);
-  const candidates = [abs, ...SOURCE_EXTS.map((e) => abs + e), ...SOURCE_EXTS.map((e) => join(abs, "index" + e))];
+  const candidates = [abs, ...exts.map((e) => abs + e), ...exts.map((e) => join(abs, "index" + e))];
   for (const c of candidates) {
     if (existsSync(c) && statSync(c).isFile()) return relative(cwd, c).split("\\").join("/");
   }
@@ -149,27 +198,37 @@ function importsOf(fileAbs) {
 
 /**
  * BFS the import graph from an entry point.
+ *
+ * Reports the edges it could NOT follow alongside the set it built. "This module is never imported"
+ * is only a supportable claim over a graph with every edge in it; over a graph missing edges it is
+ * indistinguishable from "the walker could not read this language", and the second must not be
+ * published as the first.
+ *
  * @param {string} entryRel - The entry-point path (declared form; resolved on disk).
  * @param {string} cwd - Repo root.
- * @returns {{reachable:Set<string>, entryResolved:(string|null)}} The set of repo-relative files
- *   reachable from the entry, and the resolved entry path (null when the entry is not on disk, in
- *   which case `reachable` is empty).
+ * @param {string[]} [exts] - The module extensions of this project (defaults to the JS/TS family).
+ * @returns {{reachable:Set<string>, entryResolved:(string|null), unresolved:Array<{from:string,
+ *   spec:string}>}} The set of repo-relative files reachable from the entry, the resolved entry
+ *   path (null when the entry is not on disk, in which case `reachable` is empty), and every
+ *   module-shaped relative specifier that resolved to no file.
  */
-export function reachableFrom(entryRel, cwd) {
+export function reachableFrom(entryRel, cwd, exts = DEFAULT_SOURCE_EXTS) {
   const reachable = new Set();
-  const start = resolveFile(entryRel, cwd);
-  if (!start) return { reachable, entryResolved: null };
+  const unresolved = [];
+  const start = resolveFile(entryRel, cwd, exts);
+  if (!start) return { reachable, entryResolved: null, unresolved };
   const queue = [start];
   reachable.add(start);
   while (queue.length) {
     const cur = queue.shift();
     const curAbs = resolve(cwd, cur);
     for (const spec of importsOf(curAbs)) {
-      const dep = resolveSpecifier(curAbs, spec, cwd);
+      const { file: dep, kind } = resolveSpecifier(curAbs, spec, cwd, exts);
+      if (kind === "unresolved") unresolved.push({ from: cur, spec });
       if (dep && !reachable.has(dep)) { reachable.add(dep); queue.push(dep); }
     }
   }
-  return { reachable, entryResolved: start };
+  return { reachable, entryResolved: start, unresolved };
 }
 
 // --- Mermaid view (a view of the checked graph, so it cannot drift — §2) ------
@@ -199,6 +258,76 @@ export function wiringMermaid(wiringMap, unreachableSet) {
   return lines.join("\n");
 }
 
+// --- per-scope reachability ---------------------------------------------------
+//
+// A SCOPE'S BUILD FIXTURE PROVES NOTHING UNTIL THE SCOPE'S CODE IS REACHABLE, and on a toolchain
+// that compiles only what the entry point reaches, the two come apart in the worst direction:
+// three scopes were T0-green on an assemble fixture while their own files did not compile at all,
+// and the errors surfaced only once a fourth scope — one that may not write those files — wired
+// the screens in. The fixture was honest about what it ran. Nothing asked whether what it ran
+// included the scope's work.
+//
+// This arm asks, and only ever warns. A scope legitimately owns resources, route maps, manifests,
+// tests and files a later scope will wire, so *some* of its substrate sitting outside the import
+// graph is the normal case and says nothing. What is worth a word is a scope with source files on
+// disk and NOT ONE of them reachable: everything that scope contributes is outside the running
+// app, which is the shape the defect had. Red would be wrong even then — the wiring may be the
+// next scope's job by design, which is a plan the PO made, not a defect the oracle found.
+const SKIP_DIRS = new Set([".git", "node_modules", "oh_modules", ".shapeup", "build", "dist", "out", ".idea", "coverage"]);
+
+/**
+ * List the repo-relative source files under a root, by module extension.
+ * @param {string} root - Repo root; results are relative to it.
+ * @param {string[]} exts - The module extensions that make a file a source file.
+ * @returns {string[]} Repo-relative paths, build and dependency directories skipped.
+ */
+function sourceFilesUnder(root, exts) {
+  const out = [];
+  /**
+   * Walk one directory, recursing into its subdirectories.
+   * @param {string} dir - Absolute directory to walk.
+   * @returns {void}
+   */
+  const walk = (dir) => {
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.name.startsWith(".") && e.name !== ".") { if (SKIP_DIRS.has(e.name)) continue; }
+      if (SKIP_DIRS.has(e.name)) continue;
+      const abs = join(dir, e.name);
+      if (e.isDirectory()) walk(abs);
+      else if (exts.some((x) => e.name.endsWith(x))) out.push(relative(root, abs).split("\\").join("/"));
+    }
+  };
+  walk(root);
+  return out;
+}
+
+/**
+ * For each scope contract, how much of its own source substrate the app actually reaches.
+ *
+ * @param {Array<{id?:string, contract?:object}>} contracts - Scope contracts as `readAllContracts`
+ *   returns them.
+ * @param {Set<string>} reachable - The repo-relative files reachable from the entry point.
+ * @param {string[]} sources - Every repo-relative source file on disk.
+ * @returns {Array<{scope_id:string, source_files:number, reachable_files:number}>} One row per
+ *   scope that owns at least one source file on disk; scopes owning none are left out entirely,
+ *   because a scope with nothing to reach is not a finding.
+ */
+export function scopeReachability(contracts, reachable, sources) {
+  const rows = [];
+  for (const found of contracts) {
+    const c = found?.contract || found || {};
+    const id = c.scope_id || found?.id;
+    const globs = (c.allowed_file_substrate || []).map(globToRegExp);
+    if (!globs.length) continue;
+    const owned = sources.filter((f) => globs.some((r) => r.test(f)));
+    if (!owned.length) continue;
+    rows.push({ scope_id: id, source_files: owned.length, reachable_files: owned.filter((f) => reachable.has(f)).length });
+  }
+  return rows;
+}
+
 // --- the oracle --------------------------------------------------------------
 /**
  * Run the covers-closure + reachability oracle for a slug.
@@ -262,6 +391,10 @@ export function traceLint(slug, { cwd, gate = false }) {
   const wiringPath = join(shared, "wiring-map.md");
   const profilePath = join(shared, "project-profile.md");
   let reachability = { checked: false, pass: true, unreachable: [], skipped_reason: "no wiring-map — reachability not applicable." };
+  // Hoisted so the per-scope arm below can reuse the walk this one already paid for. Both stay
+  // null unless reachability actually ran, which is what gates the second arm on the first.
+  let reachableSet = null;
+  let walkExts = null;
   let wiringMap = null;
 
   let wiringFound = null;
@@ -308,29 +441,95 @@ export function traceLint(slug, { cwd, gate = false }) {
       if (!entryPoint) {
         reachability = { checked: false, pass: true, unreachable: [], skipped_reason: "project-profile has no entry_point." };
       } else {
-        const { reachable, entryResolved } = reachableFrom(entryPoint, cwd);
+        const { exts, declared, from_entry: fromEntry } = sourceExtensions(profile, entryPoint);
+        const { reachable, entryResolved, unresolved } = reachableFrom(entryPoint, cwd, exts);
         if (!entryResolved) {
           reachability = { checked: false, pass: true, unreachable: [], entry_point: entryPoint,
             skipped_reason: `entry_point "${entryPoint}" does not resolve to a source file on disk — reachability skipped.` };
           findings.push({ severity: "warn", code: "ENTRY-MISSING", message: `project-profile.md entry_point "${entryPoint}" is not on disk — reachability cannot run.` });
+        } else if (unresolved.length) {
+          // AN INCOMPLETE GRAPH GRADES NOTHING. Every module-shaped relative import the walker could
+          // not follow is a missing edge, and a module is "unreachable" only in the sense that this
+          // walk did not get there. Publishing that as red produces a check that is red for every
+          // input on a stack the resolver cannot read, while reporting that it looked.
+          const sample = unresolved.slice(0, 3).map((u) => `${u.spec} (from ${u.from})`);
+          reachability = { checked: false, pass: true, unreachable: [], entry_point: entryPoint,
+            entry_resolved: entryResolved, reachable_files: reachable.size,
+            module_extensions: exts, unresolved_imports: unresolved.length, unresolved_sample: sample,
+            skipped_reason: `${unresolved.length} relative import(s) from the entry point resolve to no file with the extensions this project declares (${exts.join(", ")}) — the import graph is incomplete, so "never imported" is not a claim this walk can support.` };
+          findings.push({ severity: "warn", code: "GRAPH-INCOMPLETE", message:
+            `reachability did not run: ${unresolved.length} relative import(s) could not be resolved (e.g. ${sample.join("; ")}). ` +
+            `The walker tried ${exts.join(", ")}${declared.length ? "" : " — the project profile declares no `source_extensions`, so the set is the JS/TS family plus the entry point's own suffix" + (fromEntry ? ` (${fromEntry})` : "")}. ` +
+            "Declare `source_extensions` in project-profile.md to let this arm run." });
         } else {
+          const engines = wiringMap.entries || [];
           const unreachable = [];
-          for (const e of wiringMap.entries || []) {
-            const engResolved = resolveFile(e.engine, cwd);
-            const ok = engResolved ? reachable.has(engResolved) : false;
-            if (!ok) {
+          for (const e of engines) {
+            const engResolved = resolveFile(e.engine, cwd, exts);
+            if (!(engResolved && reachable.has(engResolved))) {
               unreachable.push({ use_case: e.use_case, engine: e.engine, reason: engResolved ? "not imported from the entry point" : "engine file not on disk" });
-              findings.push({ severity: "red", code: "UC-UNREACHABLE", uc: e.use_case,
-                message: `${e.use_case}: engine "${e.engine}" is ${engResolved ? "never imported from" : "missing under"} entry_point "${entryPoint}" — the module ships orphaned from the running app.` });
             }
           }
-          reachability = { checked: true, entry_point: entryPoint, entry_resolved: entryResolved,
-            reachable_files: reachable.size, engines_total: (wiringMap.entries || []).length, unreachable, pass: unreachable.length === 0 };
+          // THE ARM NEEDS ONE POSITIVE CONTROL, AND EVERY-ENGINE-ORPHANED IS NOT ONE. What this
+          // check was built to catch is the dead module: one engine with no call site among
+          // siblings that have them. When NO engine is reachable, nothing demonstrates that this
+          // entry point is the root the app actually runs from — and for whole archetypes it is
+          // not. A framework that registers screens declaratively reaches them by name at runtime
+          // (`loadContent("pages/Index")`, a route map, a manifest), so its entry file imports a
+          // handful of modules and no engine, and the import graph is complete and beside the
+          // point. "Every engine is dead" and "I am walking the wrong tree" produce identical
+          // evidence, so the arm reports that it could not check rather than picking one.
+          //
+          // THE COST, NAMED: a wiring map with a single engine can no longer red, because its only
+          // engine being unreachable is exactly the indistinguishable case. A genuinely orphaned
+          // module in a one-use-case feature is therefore reported as unchecked, not as dead. That
+          // is the price of never being red for every input on a stack this walk cannot root.
+          if (engines.length && unreachable.length === engines.length) {
+            reachability = { checked: false, pass: true, unreachable: [], entry_point: entryPoint,
+              entry_resolved: entryResolved, module_extensions: exts, reachable_files: reachable.size,
+              engines_total: engines.length, engines_reachable: 0,
+              skipped_reason: `no engine is reachable from entry_point "${entryPoint}", which reaches ${reachable.size} file(s) — with no reachable engine as a control this walk cannot tell an orphaned module from an entry point that is not the runtime root (declarative routing, a manifest, a string-loaded screen). Reachability skipped.` };
+            findings.push({ severity: "warn", code: "REACH-NO-CONTROL", message:
+              `reachability did not run: all ${engines.length} engine(s) are unreachable from entry_point "${entryPoint}", which reaches ${reachable.size} file(s). ` +
+              "Every engine orphaned is the one result this arm cannot distinguish from a wrong root — if this project wires its screens by name rather than by import, declare the module that does the wiring as the entry point." });
+          } else {
+            for (const u of unreachable) {
+              findings.push({ severity: "red", code: "UC-UNREACHABLE", uc: u.use_case,
+                message: `${u.use_case}: engine "${u.engine}" is ${u.reason === "engine file not on disk" ? "missing under" : "never imported from"} entry_point "${entryPoint}" — the module ships orphaned from the running app, while ${engines.length - unreachable.length} other engine(s) reach it.` });
+            }
+            reachableSet = reachable;
+            walkExts = exts;
+            reachability = { checked: true, entry_point: entryPoint, entry_resolved: entryResolved,
+              module_extensions: exts, reachable_files: reachable.size,
+              engines_total: engines.length, engines_reachable: engines.length - unreachable.length,
+              unreachable, pass: unreachable.length === 0 };
+          }
         }
       }
     }
   }
 
+  // --- per-scope reachability, gated on the first arm having actually run ---------------------
+  let scopeReach = { checked: false, scopes: [], orphaned: [],
+    skipped_reason: "reachability did not run, so there is no graph to measure a scope against." };
+  if (reachableSet) {
+    const contracts = readAllContracts(scopesDir(cwd, slug), SCOPE_CONTRACT);
+    if (!contracts.length) {
+      scopeReach = { checked: false, scopes: [], orphaned: [], skipped_reason: "no scope contracts on disk." };
+    } else {
+      const rows = scopeReachability(contracts, reachableSet, sourceFilesUnder(cwd, walkExts));
+      const orphaned = rows.filter((r) => r.reachable_files === 0);
+      scopeReach = { checked: true, scopes: rows, orphaned: orphaned.map((r) => r.scope_id) };
+      for (const r of orphaned) {
+        findings.push({ severity: "warn", code: "SCOPE-UNREACHABLE", scope: r.scope_id, message:
+          `scope ${r.scope_id}: none of its ${r.source_files} source file(s) is reached from the entry point. ` +
+          "A build fixture that compiles only what the entry point reaches can be green while this scope's own " +
+          "code never compiles — the errors then surface in whichever scope wires the screens in. Warn, not red: " +
+          "the wiring may legitimately be a later scope's job." });
+      }
+    }
+  }
+
   const overall = findings.some((f) => f.severity === "red") ? "red" : "green";
   const report = {
     schema_version: 1,
@@ -340,6 +539,7 @@ export function traceLint(slug, { cwd, gate = false }) {
     advisory: !gate,
     covers_closure: coversClosure,
     reachability,
+    scope_reachability: scopeReach,
     findings,
     overall,
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shapeup-sdlc",
-  "version": "3.7.12",
+  "version": "3.9.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"

package/skills/ba-pitch-analyzer/references/task-generation.md

@@ -614,7 +614,7 @@ or entirely `apps/api/**` with no cross-layer flow is the PA1 failure mode — r
 }
 ```
 `hill_phase` is always written `UPHILL_UNKNOWN` at generation time — it is derived later from
-mechanical T0/T1/seesaw facts, never declared by `ba`. `superseded_by` stays
+mechanical T0/T1 facts, never declared by `ba`. `superseded_by` stays
 `null` until a scope-architect `map-scopes` order retires this contract in favor of its replacements.
 
 **PA2 size lint:** a scope whose `allowed_file_substrate` glob set resolves to more than ~15