shapeup-sdlc 3.8.0 → 3.9.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "shapeup-sdlc-plugin",
   "displayName": "ShapeUp SDLC Plugin",
-  "version": "3.8.0",
+  "version": "3.9.1",
   "description": "Shape Up SDLC harness for Claude Code: shaping, intake, orient, scope-mapping, building (T0-verified, sandboxed, scope-contracted), evaluation and QA skills orchestrated by a tech-lead.",
   "author": {
     "name": "Liberty Nguyen",

package/README.md

@@ -139,7 +139,7 @@ rest of this README after this table and nothing will be a surprise.
 | **hill / hill phase** | How much of a scope is still *unknown* versus merely *unfinished*. Derived from T0 facts — never self-reported. |
 | **gate (L0–L4)** | A numbered checkpoint in a run. Most pause for you; GATE L2 is the one a hook observes and reports on. |
 | **covers-closure** | Every requirement clause has at least one task claiming to cover it. Nothing silently drops. |
-| **wiring reachability** | Every engine has a call site reachable from the app's real entry point. Catches "built, but never wired up". |
+| **wiring reachability** | Every engine has a call site reachable from the app's real entry point. Catches "built, but never wired up". Reports itself unchecked, with a reason, when the import walk cannot be rooted — an unfollowable import, or no reachable engine to control it. |
 | **discovery ledger** | The one file everything found mid-run gets written to, so nothing is lost between rounds. |
 
 A longer version, including the internals, is in [docs/glossary.md](docs/glossary.md).
@@ -316,7 +316,10 @@ These hold across the harness and are the reason it stays predictable:
   `harness reduce ingest`; workers return data and never touch shared state.
 - **Traceability is oracle-checked, opt-in** — `harness verify trace` verifies covers-closure and
   wiring reachability from the committed spine artifacts; it ships advisory (warn-only) and every
-  arm is skipped when its artifact is absent, so older specs are non-regressed.
+  arm is skipped when its artifact is absent, so older specs are non-regressed. Reachability also
+  skips when it cannot root its walk — an import it cannot follow, or no reachable engine to
+  control the result — because "every engine is orphaned" and "this is the wrong entry point" are
+  the same evidence, and a check that cannot tell them apart must say so rather than pick.
 
 ## Known rough edges
 

package/kernel/schemas/domain.schema.json

@@ -2287,6 +2287,11 @@
           "type": "string",
           "description": "Optional context on the archetype/entry-point choice."
         },
+        "source_extensions": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "OPTIONAL — the file extensions this project's modules use, for the import walk that reachability runs. Absent means the JS/TS family plus the entry point's own suffix, which is right for most stacks and wrong for any stack whose engines end in something the entry point does not. Declare it when they differ (e.g. [\".ets\"] for ArkTS, [\".vue\", \".ts\"] for a Vue app): a walk that cannot follow an edge reports itself unchecked rather than reporting every engine orphaned, so the cost of leaving this absent is a skipped arm, never a false red."
+        },
         "build_probe": {
           "type": "string",
           "description": "OPTIONAL — a command that asserts the BUILT ARTIFACT, not the build's exit code, and exits 0 only when it holds. Exists because a green build is not proof the feature compiled: some toolchains compile only the files reachable from an entry point, so a scope's new files can sit outside the compiled set while the build stays green (measured: an app package holding 3 compiled files, 58 errors once the rest became reachable). Archetype-specific by construction — e.g. 'the compiled source map lists every file under each scope's substrate'. Run by harness verify build after run_cmd, once per round before EVAL; absent = no such step, never a failure."

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,83 @@ 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) {
+  // One spelling, the one the schema declares. A silent alias is a field nobody documented and
+  // nobody can be told to write.
+  const raw = profile?.source_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 +200,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 +260,75 @@ 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 (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.
@@ -206,8 +336,10 @@ export function wiringMermaid(wiringMap, unreachableSet) {
  * @param {{cwd:string, gate?:boolean}} opts - cwd (root the SHARED/LOCAL paths resolve against),
  *   gate (records mode; the CLI, not this function, turns gate+red into a non-zero exit).
  * @returns {{report:object, mermaid:(string|null)}} The trace report (covers_closure, reachability,
- *   findings[], overall "green"|"red") and a Mermaid view when a wiring map exists. Each arm
- *   self-skips (checked=false) when its artifact is absent — non-regression on pre-spine specs.
+ *   scope_reachability, findings[], overall "green"|"red") and a Mermaid view when a wiring map
+ *   exists. Each arm self-skips (checked=false) when its artifact is absent — non-regression on
+ *   pre-spine specs — and reachability also self-skips when it cannot root its walk, which is what
+ *   skips the per-scope arm with it.
  */
 export function traceLint(slug, { cwd, gate = false }) {
   const shared = sharedRoot(cwd, slug);
@@ -262,6 +394,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 +444,96 @@ 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 some module does compose the app, declare that one as the entry point. " +
+              "If the screens are registered in a manifest instead — a route map, a plugin table — then no entry point roots this walk and unchecked is the correct end state for this project, not a profile to fix." });
+          } 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 +543,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.8.0",
+  "version": "3.9.1",
   "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/tech-lead/references/gates.md

@@ -220,10 +220,19 @@ Do NOT enter MAP SCOPES until Orient is accepted.
 
 ```
 1. PROFILE (you write it at L0 — compile-order stays pipeline-blind): SHARED project-profile.md
-   = {schema_version:1, archetype, entry_point, build_probe?, launch_probe?}. archetype ∈
-   {client-only-game|web-service|mobile|library|data-pipeline}; entry_point is the reachability
-   seam (a game's main.js is NOT a service's src/server.ts). Validate the enum — a typo must fail,
-   not silently disable the check. The two probes feed the round build gate (`harness verify
+   = {schema_version:1, archetype, entry_point, source_extensions?, build_probe?, launch_probe?}.
+   archetype ∈ {client-only-game|web-service|mobile|library|data-pipeline}; entry_point is the
+   reachability seam (a game's main.js is NOT a service's src/server.ts). Validate the enum — a
+   typo must fail, not silently disable the check. entry_point is also the root reachability walks
+   the import graph from, so where some module does compose the app, name that one rather than the
+   file the platform happens to start. Where the screens are registered in a MANIFEST instead (a
+   route map, a plugin table, a string-loaded page), no entry point roots an import walk at all —
+   measured on a real ArkTS app, where the navigation host imports nothing and every screen arrives
+   through route_map.json. The arm then reports that it could not check, and that is the correct
+   end state for such a project rather than a profile to keep re-declaring.
+   source_extensions is optional and only needed when the project's modules end in something the
+   entry point does not (e.g. [".ets"] when the entry is a .ts file); leaving it out costs a
+   skipped arm, never a false red. The two probes feed the round build gate (`harness verify
    build`, every round before EVAL): build_probe asserts the BUILT ARTIFACT covers what the run
    wrote (a green exit code is not proof the feature compiled when the toolchain compiles only what
    an entry point reaches); launch_probe installs, starts and asserts the first screen. A `mobile`
@@ -241,7 +250,14 @@ Do NOT enter MAP SCOPES until Orient is accepted.
    requirements.md registry (atomic REQ clauses, frozen ids).
 4. trace-lint — node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" verify trace --slug <slug>. ADVISORY at L1b:
    covers-closure (every covered REQ named by ≥1 AC's covers:) + reachability (every UC engine
-   reaches entry_point). Promote to --gate only once covers: is populated.
+   reaches entry_point). Promote to --gate only once covers: is populated. Reachability reports
+   checked:false with a reason rather than a verdict in two cases, both warns: an import it could
+   not follow (the graph is incomplete) and no engine reachable at all (nothing controls the walk,
+   so an orphan and a wrong root look identical). Read either as "re-declare the profile", never
+   as a clean arm. When it does run it also reports, per scope, how many of that scope's own source
+   files the app reaches, and warns (SCOPE-UNREACHABLE) on a scope it reaches none of — a scope's
+   build fixture can be green while its code never compiles, on any toolchain that compiles only
+   what the entry point reaches. Warn only: the wiring may be a later scope's job by design.
 ```
 
 ---

package/skills/tech-lead/workflows/shapeup-run.js

@@ -1800,6 +1800,13 @@ while (verdict !== "pass" && round <= maxRounds) {
         `${gate.detail ? `: ${gate.detail}` : ""}). Treated as undeclared, not as green.`);
   }
 
+  // Trace-lint runs a SECOND time here, and this is the pass that can see anything. At L1b the
+  // scopes' files do not exist yet, so per-scope reachability measures an empty set and its warning
+  // cannot fire. After the round's build gate the code is on disk, which is exactly when "this
+  // scope's fixture is green and none of its code is in the compiled set" becomes a checkable fact
+  // — the shape that once left three scopes green while their files never compiled. Advisory, like
+  // the L1b pass: it overwrites the same projection with a later and better-informed one.
+  await advisory(`verify trace --slug ${slug} --quiet`, "Build", `trace-lint:r${round}`);
   await advisory(`reduce hill --slug ${slug}`, "Build", "hill-derive");
   {
     const g = await crossGate("L2", "Build", ["proceed", "ask", "abort"],