@tekyzinc/gsd-t 5.0.12 → 5.0.13

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.0.13] - 2026-07-12
+
+### Fixed — a BROKEN graph now HALTS instead of silently falling back to grep
+
+Until now a broken code graph (CLI crash on a missing dependency, corrupt store) and an absent graph (never indexed) both collapsed to `reason:"graph-unavailable"`, and every consumer silently fell back to grep — the exact silent degradation that hid the 12-day resolver break. Now the two are distinguished and routed oppositely: **BROKEN → HALT and demand a fix; ABSENT → auto-build the index once, then continue.** Designed via a `/gsd-t-architect` Six-Stage Pass (reuse-first: no new halt system, envelope, or build path — all existing machinery reused).
+
+- `bin/gsd-t-graph-availability.cjs` (NEW): single `classifyGraphFailure(reason)` helper — `graph-broken`→HALT, `graph-absent`→auto-build, any unknown/legacy reason→**BROKEN (fail-closed)**. `isTransient()` guard retries once on `SQLITE_BUSY`/timeout so a slow/locked query never wrongly halts. Added to `PROJECT_BIN_TOOLS` so it ships. Has a `classify` CLI arm for the sandboxed workflows.
+- `bin/gsd-t-graph-query-cli.cjs`: producer edge emits the split reason codes (absent vs broken + `detail`).
+- `bin/gsd-t.js`: delegation edge (`_graphQueryCli`) now classifies a process crash (exit≠0 + `MODULE_NOT_FOUND`) as `graph-broken` instead of fabricating `graph-unavailable`.
+- `bin/gsd-t-file-disjointness.cjs` + `bin/gsd-t-parallel.cjs`: route through the classifier; ABSENT auto-builds once then re-checks; BROKEN halts (`gsd-t parallel` exits 3 with a loud message, no empty-plan fallback). Announced escape: `--disjointness-fallback=touches-only`.
+- 8 workflows route graph failures through the classifier (via the sandboxed `runCli` helper — no require added; m71 lint stays green). scan/verify/integrate keep their announced ABSENT carve-out but name BROKEN loudly.
+- `.gsd-t/contracts/graph-consumer-wiring-contract.md`: new §Broken-vs-Absent + 6 `[RULE]`s.
+- `test/broken-graph-halts.test.js` (NEW, 15 tests) + `.gsd-t/pseudocode/PseudoCode-BrokenGraphHalts.md`.
+
 ## [5.0.12] - 2026-07-12
 
 ### Fixed — graph require-chain shipped incomplete → every project's graph silently dead

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v5.0.12** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v5.0.13** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
 
 **Eliminates context rot** — task-level fresh dispatch (one subagent per task, ~10-20% context each) means compaction never triggers.
 **Compaction-proof debug loops** — `gsd-t headless --debug-loop` runs test-fix-retest cycles as separate `claude -p` sessions. A JSONL debug ledger persists all hypothesis/fix/learning history across fresh sessions. Anti-repetition preamble injection prevents retrying failed hypotheses. Escalation tiers (sonnet → opus → human) and a hard iteration ceiling enforced externally.

package/bin/gsd-t-file-disjointness.cjs

@@ -47,6 +47,9 @@
 const fs = require("node:fs");
 const path = require("node:path");
 const { execSync } = require("node:child_process");
+// Broken-Graph-Halts: the ONE shared availability classifier (absent→auto-build,
+// broken→HALT). Never re-implement the string check here. [RULE] one-availability-classifier
+const { classifyGraphFailure, isTransient } = require("./gsd-t-graph-availability.cjs");
 
 // ─── Event writer (append-only JSONL) ────────────────────────────────────
 
@@ -220,33 +223,57 @@ function queryBlastRadius(projectDir, filePath) {
   }
 
   let raw;
+  let execErr = null;
   try {
     raw = execSync(`node "${queryCliPath}" blast-radius "${filePath}"`, {
       cwd: projectDir,
       encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
+      stdio: ["ignore", "pipe", "pipe"],
       timeout: 10000,
     });
-  } catch {
-    // CLI present but query failed (graph index broken / parse error).
-    return { blastRadius: [], graphAvailable: false, cliPresent: true };
+  } catch (e) {
+    // The CLI's fail() exits 1 while STILL emitting a granular envelope on stdout —
+    // execSync throws on the non-zero exit, but e.stdout carries the envelope. A true
+    // crash (missing require) leaves stdout empty and stderr populated → BROKEN.
+    execErr = e;
+    raw = (e && e.stdout) ? e.stdout : "";
   }
-  try {
-    const envelope = JSON.parse((raw || "").trim());
-    if (!envelope.ok && envelope.reason === "graph-unavailable") {
-      // CLI present but graph index not built yet.
-      return { blastRadius: [], graphAvailable: false, cliPresent: true };
-    }
-    if (envelope.ok && Array.isArray(envelope.results)) {
-      const files = envelope.results.map((r) =>
-        typeof r === "string" ? r : (r && (r.file || r.path || ""))
-      ).filter(Boolean);
-      return { blastRadius: files, graphAvailable: true, cliPresent: true };
+  const trimmed = (raw || "").trim();
+  // Parse the envelope FIRST (trust the producer's granular reason) — even on a
+  // non-zero exit, a valid envelope means the producer classified it (absent/broken).
+  if (trimmed) {
+    try {
+      const envelope = JSON.parse(trimmed);
+      if (!envelope.ok) {
+        // Route the producer's reason through the ONE classifier.
+        // [RULE] one-availability-classifier [RULE] crash-classified-not-fabricated
+        const c = classifyGraphFailure(envelope.reason);
+        return {
+          blastRadius: [], graphAvailable: false, cliPresent: true,
+          state: c.state, reason: envelope.reason,
+          transient: isTransient(envelope.detail),
+        };
+      }
+      if (Array.isArray(envelope.results)) {
+        const files = envelope.results.map((r) =>
+          typeof r === "string" ? r : (r && (r.file || r.path || ""))
+        ).filter(Boolean);
+        return { blastRadius: files, graphAvailable: true, cliPresent: true, state: "OK" };
+      }
+      // ok:true but no results array — unexpected shape → BROKEN (fail-closed).
+      return { blastRadius: [], graphAvailable: false, cliPresent: true, state: "BROKEN", reason: "graph-broken" };
+    } catch {
+      // stdout present but not JSON → CLI printed garbage → BROKEN.
+      return { blastRadius: [], graphAvailable: false, cliPresent: true, state: "BROKEN", reason: "graph-broken" };
     }
-    return { blastRadius: [], graphAvailable: false, cliPresent: true };
-  } catch {
-    return { blastRadius: [], graphAvailable: false, cliPresent: true };
   }
+  // No envelope on stdout at all. A crash (empty stdout + throw) → BROKEN, unless the
+  // failure looks transient (lock/timeout), in which case the caller retries once.
+  const detail = execErr && (execErr.stderr || execErr.message);
+  return {
+    blastRadius: [], graphAvailable: false, cliPresent: true,
+    state: "BROKEN", reason: "graph-broken", transient: isTransient(detail),
+  };
 }
 
 /**
@@ -266,6 +293,33 @@ function queryBlastRadius(projectDir, filePath) {
  * [RULE] execute-disjointness-graph-aware-dependency-overlap
  * [RULE] execute-disjointness-output-flips-on-graph-edge
  */
+// [RULE] absent-graph-auto-builds-once — build the index ONCE via the existing
+// `gsd-t graph index` path when the graph is ABSENT (never indexed). Returns true on
+// a successful build. Never throws.
+function autoBuildGraphIndex(projectDir) {
+  try {
+    execSync(`node "${path.join(projectDir, "bin", "gsd-t-graph-index.cjs")}" build --repo "${projectDir}"`, {
+      cwd: projectDir,
+      encoding: "utf8",
+      stdio: ["ignore", "ignore", "pipe"],
+      timeout: 300000,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// [RULE] false-broken-guarded — retry ONCE on a transient failure (DB lock / timeout)
+// so a slow/locked query does not wrongly HALT fan-out.
+function queryBlastRadiusRetrying(projectDir, filePath) {
+  let r = queryBlastRadius(projectDir, filePath);
+  if (!r.graphAvailable && r.cliPresent && r.transient) {
+    r = queryBlastRadius(projectDir, filePath);
+  }
+  return r;
+}
+
 function graphAwareDisjointCheck(projectDir, touchesA, touchesB) {
   // Fast path: literal Touches overlap — already know they're non-disjoint.
   if (haveOverlap(touchesA, touchesB)) {
@@ -276,14 +330,16 @@ function graphAwareDisjointCheck(projectDir, touchesA, touchesB) {
   let graphAvailableConfirmed = false;
 
   for (const fileA of touchesA.slice(0, 5)) {
-    const { blastRadius, graphAvailable, cliPresent } = queryBlastRadius(projectDir, fileA);
+    const { blastRadius, graphAvailable, cliPresent, state } = queryBlastRadiusRetrying(projectDir, fileA);
     if (!cliPresent) {
       // No local graph CLI in this project — skip graph check entirely.
       return { verdict: "no-cli" };
     }
     if (!graphAvailable) {
-      // CLI present but index missing/broken → FAIL LOUD.
-      return { verdict: "graph-unavailable", reason: "GRAPH_UNAVAILABLE" };
+      // CLI present but graph absent (never indexed) or broken (corrupt/crash).
+      // Carry the classified state up so the caller can auto-build ABSENT vs HALT BROKEN.
+      // [RULE] one-availability-classifier
+      return { verdict: "graph-unavailable", reason: "GRAPH_UNAVAILABLE", state: state || "BROKEN" };
     }
     graphAvailableConfirmed = true;
     const setBtouch = new Set(touchesB);
@@ -299,7 +355,7 @@ function graphAwareDisjointCheck(projectDir, touchesA, touchesB) {
   }
 
   for (const fileB of touchesB.slice(0, 5)) {
-    const { blastRadius, graphAvailable, cliPresent } = queryBlastRadius(projectDir, fileB);
+    const { blastRadius, graphAvailable, cliPresent, state } = queryBlastRadiusRetrying(projectDir, fileB);
     if (!cliPresent) {
       if (!graphAvailableConfirmed) {
         return { verdict: "no-cli" };
@@ -308,8 +364,8 @@ function graphAwareDisjointCheck(projectDir, touchesA, touchesB) {
     }
     if (!graphAvailable) {
       if (!graphAvailableConfirmed) {
-        // CLI present but index missing/broken → FAIL LOUD.
-        return { verdict: "graph-unavailable", reason: "GRAPH_UNAVAILABLE" };
+        // CLI present but graph absent/broken → carry classified state up.
+        return { verdict: "graph-unavailable", reason: "GRAPH_UNAVAILABLE", state: state || "BROKEN" };
       }
       continue; // Transient error on B after A confirmed available — skip
     }
@@ -356,10 +412,26 @@ function groupByOverlapGraphAware(items, projectDir, fallbackToTouchesOnly) {
   const union = (i, j) => { const a = find(i), b = find(j); if (a !== b) parent[a] = b; };
 
   let graphUnavailable = false;
+  let graphBuilt = false; // [RULE] absent-graph-auto-builds-once — build at most once
 
   for (let i = 0; i < n; i++) {
     for (let j = i + 1; j < n; j++) {
-      const result = graphAwareDisjointCheck(projectDir, items[i].touches, items[j].touches);
+      let result = graphAwareDisjointCheck(projectDir, items[i].touches, items[j].touches);
+      // ABSENT (never indexed) → auto-build ONCE, then re-check this pair. A second
+      // consecutive absent (build failed or still absent) = BROKEN infra.
+      // [RULE] absent-graph-auto-builds-once
+      if (result.verdict === "graph-unavailable" && result.state === "ABSENT" && !graphBuilt) {
+        graphBuilt = true;
+        process.stderr.write(`[gsd-t disjointness] graph ABSENT — building index once (gsd-t graph index)...\n`);
+        const ok = autoBuildGraphIndex(projectDir);
+        if (ok) {
+          result = graphAwareDisjointCheck(projectDir, items[i].touches, items[j].touches);
+        }
+        // If still absent after the build, treat as BROKEN (build infra failing).
+        if (result.verdict === "graph-unavailable" && result.state === "ABSENT") {
+          result = { verdict: "graph-unavailable", reason: "GRAPH_UNAVAILABLE", state: "BROKEN" };
+        }
+      }
       if (result.verdict === "no-cli") {
         // No local graph CLI in this project → skip graph check for all pairs.
         // Fall through to Touches-only for this pair (NOT FAIL LOUD — this is "no graph").
@@ -368,14 +440,17 @@ function groupByOverlapGraphAware(items, projectDir, fallbackToTouchesOnly) {
         }
       } else if (result.verdict === "graph-unavailable") {
         graphUnavailable = true;
+        // BROKEN graph → HALT (never grep-guess). The bootstrap escape hatch is the
+        // ONLY sanctioned continue, and it is loudly announced.
+        // [RULE] broken-graph-halts-never-greps
         if (fallbackToTouchesOnly) {
           // Bootstrap escape hatch: ANNOUNCED WARNING, degrade to literal-Touches.
           // NEVER silent. NEVER applied to graph-says-non-disjoint verdicts.
           process.stderr.write(
-            `[gsd-t disjointness] WARNING: graph unavailable — falling back to ` +
+            `[gsd-t disjointness] WARNING: graph BROKEN — falling back to ` +
             `literal-Touches-only check (--disjointness-fallback=touches-only). ` +
             `Transitive dependency overlaps will NOT be detected. ` +
-            `Fix the graph index (gsd-t graph build) before the next parallel execute.\n`
+            `Fix the graph (gsd-t graph status) before the next parallel execute.\n`
           );
           if (haveOverlap(items[i].touches, items[j].touches)) {
             union(i, j);

package/bin/gsd-t-graph-availability.cjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * gsd-t-graph-availability.cjs — the ONE shared graph-availability classifier.
+ *
+ * Splits a graph-query failure into ABSENT (never indexed → auto-build then continue)
+ * vs BROKEN (missing dep / corrupt store / crash → HALT, demand a fix). Every consumer
+ * (the 8 workflows + file-disjointness) routes its `ok:false` envelope's `reason` through
+ * this ONE helper instead of re-implementing the string check.
+ *
+ * Reason codes (produced at the two seams — gsd-t-graph-query-cli.cjs + gsd-t.js
+ * _graphQueryCli):
+ *   "graph-absent"  → no store on disk yet (never indexed)          → ABSENT
+ *   "graph-broken"  → store present-but-unreadable / CLI crash / corrupt → BROKEN
+ *
+ * [RULE] one-availability-classifier — the absent-vs-broken decision lives HERE, once.
+ * [RULE] unknown-reason-fails-closed-to-broken — any unrecognised reason (incl. the
+ *   legacy "graph-unavailable") classifies as BROKEN/HALT, never ABSENT/continue.
+ * [RULE] false-broken-guarded — a transient failure (SQLITE_BUSY / timeout) is
+ *   retry-eligible; callers retry ONCE before classifying BROKEN.
+ */
+
+const ABSENT = { state: "ABSENT", action: "auto-build-then-continue" };
+const BROKEN = { state: "BROKEN", action: "HALT-demand-fix" };
+
+/**
+ * classifyGraphFailure(reason) → { state, action }.
+ * Fail-closed: anything that is not exactly "graph-absent" is BROKEN.
+ *
+ * @param {string} reason  the `reason` field of an `ok:false` graph envelope
+ * @returns {{ state: "ABSENT"|"BROKEN", action: string }}
+ */
+function classifyGraphFailure(reason) {
+  if (reason === "graph-absent") return { ...ABSENT };
+  if (reason === "graph-broken") return { ...BROKEN };
+  // [RULE] unknown-reason-fails-closed-to-broken — legacy "graph-unavailable" and
+  // any unknown reason HALT rather than silently continue.
+  return { ...BROKEN };
+}
+
+/**
+ * isTransient(detail) → boolean.
+ * A transient failure (DB lock / timeout) may resolve on a retry, so a slow or
+ * locked query must not wrongly HALT all work. Callers retry ONCE, then classify.
+ * [RULE] false-broken-guarded
+ *
+ * @param {string} detail  the `detail` field of the failing envelope (or stderr)
+ * @returns {boolean}
+ */
+function isTransient(detail) {
+  if (!detail || typeof detail !== "string") return false;
+  return /SQLITE_BUSY|database is locked|ETIMEDOUT|timed?\s*out|timeout/i.test(detail);
+}
+
+module.exports = { classifyGraphFailure, isTransient };
+
+// ─── CLI arm (Bash-invokable — the sandboxed workflows call this, not require) ───
+// Usage: node bin/gsd-t-graph-availability.cjs classify <reason> [detail]
+// Prints a JSON envelope: { ok:true, state, action, transient }
+if (require.main === module) {
+  const [, , sub, reason, detail] = process.argv;
+  if (sub === "classify") {
+    const c = classifyGraphFailure(reason);
+    const out = { ok: true, reason: reason || null, state: c.state, action: c.action, transient: isTransient(detail) };
+    process.stdout.write(JSON.stringify(out) + "\n");
+    process.exit(0);
+  }
+  process.stdout.write(JSON.stringify({ ok: false, reason: "unknown-subcommand", usage: "classify <reason> [detail]" }) + "\n");
+  process.exit(1);
+}

package/bin/gsd-t-graph-query-cli.cjs

@@ -474,7 +474,8 @@ function loadSqliteStore(dbPath) {
 }
 
 function loadStore(storePath) {
-  if (!storePath) return { ok: false, reason: "graph-unavailable" };
+  // ABSENT: no store file anywhere on disk (never indexed). [RULE] one-availability-classifier
+  if (!storePath) return { ok: false, reason: "graph-absent" };
 
   // SQLite is the PICKED store (K1) — read it first; fall back to JSONL baseline.
   // Sibling-db fallback uses resolver (not a raw path.join). [RULE] one-resolver-only
@@ -484,7 +485,8 @@ function loadStore(storePath) {
   })();
   const loaded = (storePath.endsWith(".db") ? loadSqliteStore(storePath) : loadJsonlStore(storePath))
     || loadJsonlStore(storePath) || (_siblingDb && fs.existsSync(_siblingDb) ? loadSqliteStore(_siblingDb) : null);
-  if (!loaded) return { ok: false, reason: "graph-unavailable" };
+  // BROKEN: a store file exists but could not be read/parsed (corrupt). NOT absent.
+  if (!loaded) return { ok: false, reason: "graph-broken", detail: "store present but unreadable" };
 
   try {
     // Load skipped files (best-effort — never fails the store load)
@@ -492,7 +494,8 @@ function loadStore(storePath) {
     const index = buildIndex(loaded.records, skippedFiles);
     return { ok: true, index };
   } catch (_e) {
-    return { ok: false, reason: "graph-unavailable" };
+    // Store loaded but buildIndex threw on corrupt records → BROKEN, name the cause.
+    return { ok: false, reason: "graph-broken", detail: _e && _e.code ? _e.code : "buildIndex-failed" };
   }
 }
 
@@ -527,8 +530,9 @@ function loadFreshnessModule() {
 function runFreshnessCheck(storePath) {
   const freshnessModule = loadFreshnessModule();
   if (!freshnessModule) {
-    // D4 not yet built — fail-loud per [RULE] parser-fail-disables-loud-never-silent
-    return { ok: false, reason: "graph-unavailable" };
+    // D4 not yet built / unloadable — this is BROKEN infra (a missing require), not an
+    // un-indexed repo. Fail-loud per [RULE] parser-fail-disables-loud-never-silent.
+    return { ok: false, reason: "graph-broken", detail: "freshness module unavailable" };
   }
 
   try {
@@ -545,7 +549,8 @@ function runFreshnessCheck(storePath) {
     // (Without this, a fake/non-existent storePath yields projectRoot="/" and
     //  compute_touched_files walks the entire filesystem → OOM. [RULE]
     //  parser-fail-disables-loud-never-silent: absent store = graph-unavailable.)
-    if (!db) return { ok: false, reason: "graph-unavailable" };
+    // No real store at this root → ABSENT (never indexed), not broken.
+    if (!db) return { ok: false, reason: "graph-absent" };
     const touched = freshnessModule.compute_touched_files(db, projectRoot);
     // parse_and_put (from D3) lets freshness re-index stale files; pass it when
     // available so an edited file is refreshed before the answer.
@@ -565,7 +570,8 @@ function runFreshnessCheck(storePath) {
       reindexedFiles: Array.isArray(t.edits) ? t.edits.slice(0, 20) : [],
     };
   } catch (_e) {
-    return { ok: false, reason: "graph-unavailable" };
+    // Parse/corrupt/other freshness error → BROKEN, carry the cause code.
+    return { ok: false, reason: "graph-broken", detail: _e && _e.code ? _e.code : "freshness-failed" };
   }
 }
 
@@ -1344,13 +1350,16 @@ if (require.main === module) {
     };
   } catch { /* fail-open */ }
   if (!freshnessResult.ok) {
-    fail({ ok: false, reason: "graph-unavailable" });
+    // Propagate the granular reason (graph-absent / graph-broken) so the consumer's
+    // classifier can route ABSENT→auto-build vs BROKEN→HALT. Never collapse to a
+    // single "graph-unavailable" here. [RULE] one-availability-classifier
+    fail({ ok: false, reason: freshnessResult.reason || "graph-broken", detail: freshnessResult.detail });
   }
 
   // ── Step 2: Load store (fail-loud if missing or corrupt) ──
   const storeResult = loadStore(storePath);
   if (!storeResult.ok) {
-    fail({ ok: false, reason: "graph-unavailable" });
+    fail({ ok: false, reason: storeResult.reason || "graph-broken", detail: storeResult.detail });
   }
 
   const index = storeResult.index;

package/bin/gsd-t-parallel.cjs

@@ -145,6 +145,10 @@ function parseArgv(argv) {
     else if (a.startsWith("--domain=")) out.domain = a.slice("--domain=".length);
     else if (a === "--command") out.command = argv[++i] || null;
     else if (a.startsWith("--command=")) out.command = a.slice("--command=".length);
+    // Broken-Graph-Halts bootstrap escape hatch — degrade to literal-Touches (announced)
+    // when the graph is BROKEN, instead of HALTing. Off by default (HALT is the default).
+    else if (a === "--disjointness-fallback") out.disjointnessFallback = argv[++i] || null;
+    else if (a.startsWith("--disjointness-fallback=")) out.disjointnessFallback = a.slice("--disjointness-fallback=".length);
     else if (a === "--max-workers") out.maxWorkers = parseInt(argv[++i], 10);
     else if (a.startsWith("--max-workers=")) out.maxWorkers = parseInt(a.slice("--max-workers=".length), 10);
     else if (a === "--stagger") out.stagger = parseInt(argv[++i], 10);
@@ -236,7 +240,21 @@ function runParallel(opts) {
   }
 
   // ── D5 disjointness gate ──
-  const disj = proveDisjointness({ tasks: depReady, projectDir });
+  const disjointnessFallback = (opts && opts.disjointnessFallback) || null;
+  const disj = proveDisjointness({ tasks: depReady, projectDir, disjointnessFallback });
+  // Broken-Graph-Halts: a BROKEN graph (missing dep / corrupt / crash) makes the
+  // transitive-overlap check unprovable. HALT loudly — do NOT silently emit an empty
+  // parallel plan (that would be a silent grep-equivalent fallback).
+  // [RULE] broken-graph-halts-never-greps
+  if (disj.graphUnavailable) {
+    process.stderr.write(
+      `[gsd-t parallel] HALT: graph BROKEN — file-disjointness is unprovable, so a safe ` +
+      `parallel plan cannot be built. Fix the graph (gsd-t graph status), or re-run with ` +
+      `--disjointness-fallback=touches-only to degrade to literal-Touches (announced). ` +
+      `Refusing to fan out on an unprovable plan.\n`
+    );
+    process.exit(3);
+  }
   const disjointTaskIds = new Set();
   for (const group of disj.parallel || []) {
     for (const t of group) disjointTaskIds.add(t.id);

package/bin/gsd-t.js

@@ -2993,6 +2993,12 @@ const PROJECT_BIN_TOOLS = [
   // copied tool finds the engine from the GSD-T global package, not the project's
   // own (usually absent) node_modules. Fail-loud with remediation if all miss.
   "gsd-t-require-store.cjs",
+  // Broken-Graph-Halts — the ONE shared availability classifier (graph-absent vs
+  // graph-broken → ABSENT/auto-build vs BROKEN/HALT). The sandboxed workflows invoke
+  // it via Bash (`node bin/gsd-t-graph-availability.cjs classify <reason>`), so it MUST
+  // ship to every project or the consumers can't classify. Same propagation class as
+  // gsd-t-graph-store-resolver.cjs above. [[project_global_bin_propagation_gap]]
+  "gsd-t-graph-availability.cjs",
 ];
 
 // Files that older versions of this installer copied into project bin/ but
@@ -3910,6 +3916,35 @@ function doChangelog() {
  *
  * [RULE] graph-status-live — NEVER hits the dead M20–M21 "No graph index found" path.
  */
+// Broken-graph seam (delegation edge): classify a spawnSync result into a graph
+// envelope. STOPS discarding result.status/result.stderr. A crash (missing require →
+// exit≠0, empty stdout, MODULE_NOT_FOUND on stderr) means the CLI itself is BROKEN —
+// surface it so the consumer HALTs, never fabricate a collapsed "graph-unavailable"
+// that hides the crash. Extracted (pure) so it is unit-testable with a simulated result.
+// [RULE] crash-classified-not-fabricated
+function _classifyGraphSpawnResult(result) {
+  const stdout = (result.stdout || "").trim();
+  // Trust a valid JSON envelope on stdout — the producer already classified the reason
+  // (graph-absent / graph-broken / a real answer). Parse FIRST so a non-zero exit that
+  // still emitted an envelope (fail() exits 1) keeps the producer's granular reason.
+  if (stdout) {
+    try {
+      return JSON.parse(stdout);
+    } catch {
+      // stdout present but not JSON → the CLI printed garbage → BROKEN.
+      return { ok: false, reason: "graph-broken", detail: stdout };
+    }
+  }
+  // No valid envelope on stdout. If the process crashed (spawn error, or non-zero
+  // exit with empty stdout), the CLI is BROKEN.
+  if (result.error) {
+    return { ok: false, reason: "graph-broken", detail: result.error.message };
+  }
+  // exit != 0 with no envelope, OR exit 0 with empty stdout (shouldn't happen) →
+  // treat as BROKEN defensively.
+  return { ok: false, reason: "graph-broken", detail: result.stderr || `exit ${result.status}, no output` };
+}
+
 function _graphQueryCli(verbAndArgs) {
   const { spawnSync } = require("child_process");
   const cliPath = require("path").join(__dirname, "gsd-t-graph-query-cli.cjs");
@@ -3918,18 +3953,7 @@ function _graphQueryCli(verbAndArgs) {
     cwd: process.cwd(),
     timeout: 30000,
   });
-  if (result.error) {
-    return { ok: false, reason: "graph-unavailable", detail: result.error.message };
-  }
-  const stdout = (result.stdout || "").trim();
-  if (!stdout) {
-    return { ok: false, reason: "graph-unavailable", detail: result.stderr || "no output" };
-  }
-  try {
-    return JSON.parse(stdout);
-  } catch {
-    return { ok: false, reason: "graph-unavailable", detail: stdout };
-  }
+  return _classifyGraphSpawnResult(result);
 }
 
 /**
@@ -4920,6 +4944,7 @@ module.exports = {
   copyFile,
   copyBinToolsToProject,
   PROJECT_BIN_TOOLS,
+  _classifyGraphSpawnResult,
   hasPlaywright,
   hasSwagger,
   hasApi,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.0.12",
+  "version": "5.0.13",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/templates/workflows/gsd-t-debug.workflow.js

@@ -85,6 +85,27 @@ async function generateBrief(projectDir, { kind = "execute", milestone, domain,
   const r = await runCli(projectDir, "brief", argv, "gsd-t-context-brief.cjs", label, false, phaseName);
   return { ok: r.ok, briefPath: `${projectDir}/.gsd-t/briefs/${id}.json`, via: r.via };
 }
+// Broken-Graph-Halts: route a failing graph envelope's reason through the ONE shared
+// classifier via Bash (sandbox bans require). Returns "ABSENT" | "BROKEN" (fail-closed).
+// [RULE] one-availability-classifier [RULE] unknown-reason-fails-closed-to-broken
+async function classifyGraphFailure(projectDir, reason, detail, phaseName) {
+  const r = await runCli(
+    projectDir, "graph-availability",
+    ["classify", String(reason || ""), String(detail || "")],
+    "gsd-t-graph-availability.cjs", "graph-classify", true, phaseName
+  ).catch(() => null);
+  const env = r && r.envelope;
+  if (env && (env.state === "ABSENT" || env.state === "BROKEN")) return env.state;
+  return "BROKEN";
+}
+// [RULE] absent-graph-auto-builds-once — build the index once via the existing path.
+async function buildGraphIndex(projectDir, phaseName) {
+  const r = await runCli(
+    projectDir, "graph index", ["build", "--repo", projectDir],
+    "gsd-t-graph-index.cjs", "graph-index", false, phaseName
+  ).catch(() => null);
+  return !!(r && r.ok);
+}
 
 const projectDir = _args.projectDir || ".";
 const symptom = _args.symptom || null;
@@ -317,11 +338,11 @@ async function runResearchForClaim(projectDir, claimText, artifactPath, phaseNam
 // the structural slice — the fail-loud requirement is met by the logged message;
 // the agent is NOT given a grep fallback to find the call chain).
 // [RULE] debug-reader-and-writer-both
-async function queryGraphForDebug(projectDir, symptom, phaseName) {
+async function queryGraphForDebug(projectDir, symptom, phaseName, _rebuilt) {
   // Derive a plausible target hint from the symptom text (the file or function name)
   // to pass to blast-radius. This is heuristic — the agent reads the full slice.
   const targetHint = (symptom || "").slice(0, 80).replace(/['"]/g, "").trim();
-  if (!targetHint) return null;
+  if (!targetHint) return { line: null, halt: false };
 
   const blastResult = await runCli(
     projectDir,
@@ -333,15 +354,22 @@ async function queryGraphForDebug(projectDir, symptom, phaseName) {
     phaseName
   );
   const env = blastResult.envelope;
-  if (!env) return null;
-  if (!env.ok && env.reason === "graph-unavailable") {
-    log(`M94-D11 READER: graph unavailable — fix it (gsd-t graph status). Debug proceeds without structural slice.`);
-    return null; // Fail-loud logged; no grep fallback
+  if (!env) return { line: null, halt: false };
+  if (!env.ok) {
+    const state = await classifyGraphFailure(projectDir, env.reason, env.detail, phaseName);
+    if (state === "ABSENT" && !_rebuilt) {
+      log(`M94-D11 READER: graph ABSENT — building index once, then re-querying.`);
+      await buildGraphIndex(projectDir, phaseName);
+      return queryGraphForDebug(projectDir, symptom, phaseName, true);
+    }
+    const haltMessage = `graph BROKEN (reason=${env.reason || "?"}) — debug HALTED. Fix it: run gsd-t graph status. No grep fallback.`;
+    log(`M94-D11 READER: ${haltMessage}`);
+    return { line: null, halt: true, haltMessage };
   }
-  if (env.ok && Array.isArray(env.results)) {
-    return `## Graph structural slice (blast-radius for "${targetHint}"):\n${JSON.stringify(env.results.slice(0, 20), null, 2)}`;
+  if (Array.isArray(env.results)) {
+    return { line: `## Graph structural slice (blast-radius for "${targetHint}"):\n${JSON.stringify(env.results.slice(0, 20), null, 2)}`, halt: false };
   }
-  return null;
+  return { line: null, halt: false };
 }
 
 // M94-D11 §WRITER: Trigger a freshness pass over the touched set after the fix lands.
@@ -381,7 +409,12 @@ await persistWiringMode("Preflight");
 
 // M94-D11 §READER: query graph ONCE before cycles (the structural slice is the same
 // for all cycles — same symptom). Injected into each cycle's prompt.
-const _graphSliceLine = await queryGraphForDebug(projectDir, symptom, "Preflight") || "";
+// [RULE] broken-graph-halts-never-greps — a BROKEN graph HALTS debug (no grep fallback).
+const _graphRead = await queryGraphForDebug(projectDir, symptom, "Preflight");
+if (_graphRead && _graphRead.halt) {
+  return { status: "blocked-needs-human", reason: "graph-broken", detail: _graphRead.haltMessage };
+}
+const _graphSliceLine = (_graphRead && _graphRead.line) || "";
 
 let lastResult = null;
 // M90 §3 (fix-cycle: gate lifecycle) — track THIS run's per-signature cycle counts so the

package/templates/workflows/gsd-t-integrate.workflow.js

@@ -39,6 +39,20 @@ async function runCli(projectDir, subcmd, argv, localBin, label, parseJson = tru
   return r || { ok: false, exitCode: -1, envelope: null, via: "error" };
 }
 async function runPreflight(projectDir, label = "preflight", phaseName) { return runCli(projectDir, "preflight", ["--json"], "cli-preflight.cjs", label, true, phaseName); }
+// Broken-Graph-Halts (EXEMPT carve-out): integrate is additive/announced — it does not
+// hard-fail on an unavailable graph. But it MUST DISTINGUISH absent from broken and name
+// BROKEN loudly, never silently continue as if merely un-indexed.
+// [RULE] one-availability-classifier [RULE] broken-graph-halts-never-greps (carve-out: name BROKEN loudly)
+async function classifyGraphFailure(projectDir, reason, detail, phaseName) {
+  const r = await runCli(
+    projectDir, "graph-availability",
+    ["classify", String(reason || ""), String(detail || "")],
+    "gsd-t-graph-availability.cjs", "graph-classify", true, phaseName
+  ).catch(() => null);
+  const env = r && r.envelope;
+  if (env && (env.state === "ABSENT" || env.state === "BROKEN")) return env.state;
+  return "BROKEN";
+}
 async function runVerifyGate(projectDir, label = "verify-gate", phaseName) { return runCli(projectDir, "verify-gate", ["--json"], "gsd-t-verify-gate.cjs", label, true, phaseName); }
 async function generateBrief(projectDir, { kind = "execute", milestone, domain, id, label = "brief", phaseName } = {}) {
   const argv = ["--kind", kind, "--spawn-id", id, "--out", `${projectDir}/.gsd-t/briefs/${id}.json`];
@@ -108,8 +122,14 @@ let _graphIntegrateWarning = null;
   if (wiEnv.ok === true) {
     _graphWhoImportsSlice = wiEnv;
     log(`M94 graph who-imports: ${(wiEnv.results || []).length} result(s) (tier: ${wiEnv.tier || "?"})`);
-  } else if (wiEnv.reason === "graph-unavailable") {
-    _graphIntegrateWarning = "⚠ graph unavailable — structural wiring-check skipped, fix it (gsd-t graph status)";
+  } else if (wiEnv.ok === false) {
+    // [RULE] one-availability-classifier — distinguish ABSENT (announced skip) from BROKEN (LOUD).
+    const _state = await classifyGraphFailure(projectDir, wiEnv.reason, wiEnv.detail, "Integrate");
+    if (_state === "BROKEN") {
+      _graphIntegrateWarning = `⚠ graph BROKEN (reason=${wiEnv.reason || "?"}) — structural wiring-check skipped. This is NOT merely un-indexed; FIX it (gsd-t graph status).`;
+    } else {
+      _graphIntegrateWarning = "⚠ graph ABSENT (never indexed) — structural wiring-check skipped (announced carve-out; build with gsd-t graph index)";
+    }
     log(`M94 graph who-imports: ${_graphIntegrateWarning}`);
   } else {
     _graphIntegrateWarning = `⚠ graph who-imports query unexpected envelope (reason: ${wiEnv.reason || "?"}); structural wiring-check skipped`;

package/templates/workflows/gsd-t-phase.workflow.js

@@ -120,6 +120,27 @@ async function runCli(projectDir, subcmd, argv, localBin, label, parseJson = tru
   return r || { ok: false, exitCode: -1, envelope: null, via: "error" };
 }
 async function runPreflight(projectDir, label = "preflight", phaseNameOpt) { return runCli(projectDir, "preflight", ["--json"], "cli-preflight.cjs", label, true, phaseNameOpt); }
+// Broken-Graph-Halts: route a failing graph reason through the ONE shared classifier
+// via Bash (sandbox bans require). Returns "ABSENT" | "BROKEN" (fail-closed).
+// [RULE] one-availability-classifier [RULE] unknown-reason-fails-closed-to-broken
+async function classifyGraphFailure(projectDir, reason, detail, phaseNameOpt) {
+  const r = await runCli(
+    projectDir, "graph-availability",
+    ["classify", String(reason || ""), String(detail || "")],
+    "gsd-t-graph-availability.cjs", "graph-classify", true, phaseNameOpt
+  ).catch(() => null);
+  const env = r && r.envelope;
+  if (env && (env.state === "ABSENT" || env.state === "BROKEN")) return env.state;
+  return "BROKEN";
+}
+// [RULE] absent-graph-auto-builds-once — build the index once via the existing path.
+async function buildGraphIndex(projectDir, phaseNameOpt) {
+  const r = await runCli(
+    projectDir, "graph index", ["build", "--repo", projectDir],
+    "gsd-t-graph-index.cjs", "graph-index", false, phaseNameOpt
+  ).catch(() => null);
+  return !!(r && r.ok);
+}
 // M83: the deterministic plan-hardening gate. Returns the parsed envelope
 // ({ ok, exitCode, violations, ... }); ok:false means ≥1 untraceable AC.
 async function runTraceabilityGate(projectDir, milestone, label = "traceability-gate", phaseNameOpt) {
@@ -176,11 +197,11 @@ const PHASE_GRAPH_VERB_MAP = {
  * [RULE] phase-workflow-fail-loud-no-grep — on graph-unavailable, surface the loud
  * message and NEVER fall back to grep for the structural question.
  */
-async function queryStructuralSlice(projectDir, phaseName, phaseNameOpt) {
+async function queryStructuralSlice(projectDir, phaseName, phaseNameOpt, _rebuilt) {
   const verb = PHASE_GRAPH_VERB_MAP[phaseName];
   if (!verb) {
     // Phase has no mapped structural verb (milestone/discuss/design-decompose/doc-ripple) — no-op.
-    return { ok: true, verb: null, slice: null, graphUnavailable: false, loudMessage: null };
+    return { ok: true, verb: null, slice: null, graphUnavailable: false, graphBroken: false, loudMessage: null };
   }
   // The graph query uses gsd-t-graph-query-cli.cjs (local) or `gsd-t graph <verb>` (global).
   // argv: only the verb (no target) for phase-level queries that return a global set
@@ -190,20 +211,28 @@ async function queryStructuralSlice(projectDir, phaseName, phaseNameOpt) {
     `graph:${verb}`, true, phaseNameOpt
   );
   const env = r.envelope || {};
-  if (env.ok === false && env.reason === "graph-unavailable") {
-    // [RULE] phase-workflow-fail-loud-no-grep: surface LOUD, no grep fallback.
-    const loudMessage = `⚠ graph unavailable — structural ${verb} slice NOT injected (fix it: gsd-t graph status). NO grep fallback — structural question unanswered.`;
+  if (env.ok === false) {
+    // [RULE] one-availability-classifier — route the reason through the shared classifier.
+    const state = await classifyGraphFailure(projectDir, env.reason, env.detail, phaseNameOpt);
+    if (state === "ABSENT" && !_rebuilt) {
+      log(`M94 graph-slice: graph ABSENT — building index once, then re-querying ${verb}.`);
+      await buildGraphIndex(projectDir, phaseNameOpt);
+      return queryStructuralSlice(projectDir, phaseName, phaseNameOpt, true);
+    }
+    // BROKEN (or still-absent after one build) → HALT the phase. No grep fallback.
+    // [RULE] broken-graph-halts-never-greps [RULE] phase-workflow-fail-loud-no-grep
+    const loudMessage = `⚠ graph BROKEN (reason=${env.reason || "?"}) — structural ${verb} slice NOT injected. Phase HALTED — fix it: run gsd-t graph status. NO grep fallback.`;
     log(`M94 graph-slice: ${loudMessage}`);
-    return { ok: false, verb, slice: null, graphUnavailable: true, loudMessage };
+    return { ok: false, verb, slice: null, graphUnavailable: true, graphBroken: true, loudMessage };
   }
   if (env.ok === true) {
     log(`M94 graph-slice: ${phaseName} → ${verb} → ${(env.results || []).length} result(s) (tier: ${env.tier || "?"})`);
-    return { ok: true, verb, slice: env, graphUnavailable: false, loudMessage: null };
+    return { ok: true, verb, slice: env, graphUnavailable: false, graphBroken: false, loudMessage: null };
   }
-  // Unexpected envelope (graph returned ok:false for a non-unavailable reason).
-  const loudMessage = `⚠ graph ${verb} query returned unexpected envelope (ok=${env.ok}, reason=${env.reason || "?"}). Structural slice NOT injected.`;
+  // Unexpected envelope (no ok field at all) → fail-closed to BROKEN.
+  const loudMessage = `⚠ graph ${verb} query returned unexpected envelope (ok=${env.ok}, reason=${env.reason || "?"}). Treated as BROKEN — structural slice NOT injected.`;
   log(`M94 graph-slice: ${loudMessage}`);
-  return { ok: false, verb, slice: null, graphUnavailable: false, loudMessage };
+  return { ok: false, verb, slice: null, graphUnavailable: true, graphBroken: true, loudMessage };
 }
 
 // M82: run the deterministic selection oracle over a candidate-set spec. The spec
@@ -857,6 +886,10 @@ const briefLine = `**Brief (REQUIRED):** ${brief.briefPath || "(no brief — re-
 // the pre-computed structural answer and has no reason to grep for structure.
 // [RULE] phase-workflow-injects-structural-slice
 const _graphSliceResult = await queryStructuralSlice(projectDir, phaseName, "Phase");
+// [RULE] broken-graph-halts-never-greps — a BROKEN graph HALTS the phase (no grep fallback).
+if (_graphSliceResult.graphBroken) {
+  return { status: "blocked-needs-human", reason: "graph-broken", detail: _graphSliceResult.loudMessage };
+}
 const _graphSliceLine = _graphSliceResult.ok && _graphSliceResult.slice
   ? `\n**Structural Graph Slice (${_graphSliceResult.verb}):** ${JSON.stringify(_graphSliceResult.slice)}\nUse this pre-computed graph slice to answer structural questions — do NOT grep for ${_graphSliceResult.verb} answers.`
   : _graphSliceResult.loudMessage

package/templates/workflows/gsd-t-quick.workflow.js

@@ -71,6 +71,28 @@ async function runCli(projectDir, subcmd, argv, localBin, label, parseJson = tru
 async function runPreflight(projectDir, label = "preflight", phaseName) {
   return runCli(projectDir, "preflight", ["--json"], "cli-preflight.cjs", label, true, phaseName);
 }
+// Broken-Graph-Halts: route a failing graph envelope's reason through the ONE shared
+// classifier (sandbox bans require → call it via Bash). Returns "ABSENT" | "BROKEN".
+// [RULE] one-availability-classifier [RULE] unknown-reason-fails-closed-to-broken
+async function classifyGraphFailure(projectDir, reason, detail, phaseName) {
+  const r = await runCli(
+    projectDir, "graph-availability",
+    ["classify", String(reason || ""), String(detail || "")],
+    "gsd-t-graph-availability.cjs", "graph-classify", true, phaseName
+  ).catch(() => null);
+  const env = r && r.envelope;
+  if (env && (env.state === "ABSENT" || env.state === "BROKEN")) return env.state;
+  return "BROKEN"; // fail-closed if the classifier itself is unreachable
+}
+// [RULE] absent-graph-auto-builds-once — build the index once via the existing
+// `gsd-t graph index` path (local bin: gsd-t-graph-index.cjs build --repo <dir>).
+async function buildGraphIndex(projectDir, phaseName) {
+  const r = await runCli(
+    projectDir, "graph index", ["build", "--repo", projectDir],
+    "gsd-t-graph-index.cjs", "graph-index", false, phaseName
+  ).catch(() => null);
+  return !!(r && r.ok);
+}
 async function runVerifyGate(projectDir, label = "verify-gate", phaseName) {
   return runCli(projectDir, "verify-gate", ["--json"], "gsd-t-verify-gate.cjs", label, true, phaseName);
 }
@@ -184,15 +206,16 @@ const RESEARCH_RESULT_SCHEMA = {
 };
 
 // M94-D11 §READER: Query blast-radius / who-imports for structural impact before editing.
-// Returns a short text snippet injected into the Execute phase agent prompt.
-// On graph-unavailable: logs the fail-loud message and returns null (no grep fallback).
-// [RULE] quick-writer-pattern
-async function queryGraphForQuick(projectDir, task, phaseName) {
+// Returns { line, halt, haltMessage }:
+//   BROKEN graph → { halt:true, haltMessage } (HALT the workflow — never grep-fallback)
+//   ABSENT graph → auto-build once, re-query; still absent → BROKEN → halt
+// [RULE] quick-writer-pattern [RULE] broken-graph-halts-never-greps
+async function queryGraphForQuick(projectDir, task, phaseName, _rebuilt) {
   // Extract a plausible target hint from the task description (first word-token that
   // looks like a file or function name). Heuristic — the agent uses the full slice.
   const words = (task || "").split(/\s+/).filter(Boolean);
   const targetHint = words.find((w) => w.includes("/") || w.includes(".") || w.includes("#")) || words[0] || "";
-  if (!targetHint || targetHint.length < 2) return null;
+  if (!targetHint || targetHint.length < 2) return { line: null, halt: false };
 
   const r = await runCli(
     projectDir,
@@ -205,15 +228,23 @@ async function queryGraphForQuick(projectDir, task, phaseName) {
   ).catch(() => ({ ok: false, exitCode: -1, envelope: null }));
 
   const env = r && r.envelope;
-  if (!env) return null;
-  if (!env.ok && env.reason === "graph-unavailable") {
-    log(`M94-D11 READER: graph unavailable — fix it (gsd-t graph status). Quick proceeds without structural slice.`);
-    return null; // Fail-loud logged; no grep fallback [RULE consumer-structural-grep-removed]
+  if (!env) return { line: null, halt: false };
+  if (!env.ok) {
+    const state = await classifyGraphFailure(projectDir, env.reason, env.detail, phaseName);
+    if (state === "ABSENT" && !_rebuilt) {
+      log(`M94-D11 READER: graph ABSENT — building index once, then re-querying.`);
+      await buildGraphIndex(projectDir, phaseName);
+      return queryGraphForQuick(projectDir, task, phaseName, true);
+    }
+    // BROKEN (or still-absent after one build) → HALT. NO grep fallback.
+    const haltMessage = `graph BROKEN (reason=${env.reason || "?"}) — quick HALTED. Fix it: run gsd-t graph status. No grep fallback.`;
+    log(`M94-D11 READER: ${haltMessage}`);
+    return { line: null, halt: true, haltMessage };
   }
-  if (env.ok && Array.isArray(env.results)) {
-    return `## Graph structural slice (blast-radius for "${targetHint}"):\n${JSON.stringify(env.results.slice(0, 20), null, 2)}`;
+  if (Array.isArray(env.results)) {
+    return { line: `## Graph structural slice (blast-radius for "${targetHint}"):\n${JSON.stringify(env.results.slice(0, 20), null, 2)}`, halt: false };
   }
-  return null;
+  return { line: null, halt: false };
 }
 
 // M94-D11 §WRITER: Trigger a freshness pass over the touched set after edits.
@@ -249,8 +280,12 @@ const brief = await generateBrief(projectDir, { kind: "execute", id: "quick-brie
 await persistWiringMode("Preflight");
 
 // M94-D11 §READER: query graph for structural impact before the Execute agent reasons
-// [RULE] quick-writer-pattern
-const _graphSliceLine = await queryGraphForQuick(projectDir, task, "Preflight") || "";
+// [RULE] quick-writer-pattern [RULE] broken-graph-halts-never-greps
+const _graphRead = await queryGraphForQuick(projectDir, task, "Preflight");
+if (_graphRead && _graphRead.halt) {
+  return { status: "blocked-needs-human", reason: "graph-broken", detail: _graphRead.haltMessage };
+}
+const _graphSliceLine = (_graphRead && _graphRead.line) || "";
 
 phase("Execute");
 const result = await agent(

package/templates/workflows/gsd-t-scan.workflow.js

@@ -312,6 +312,24 @@ async function runCliBuild() {
   return r || { ok: false, reason: "build-failed" };
 }
 
+// Broken-Graph-Halts (EXEMPT carve-out): scan continues in announced grep-mode when the
+// graph is unavailable, but it MUST DISTINGUISH absent from broken. On ABSENT it builds
+// once (below); on BROKEN it must name BROKEN loudly, not treat it as merely un-indexed.
+// Routes the reason through the ONE shared classifier via Bash.
+// [RULE] one-availability-classifier [RULE] unknown-reason-fails-closed-to-broken
+async function classifyGraphFailure(reason, detail) {
+  const r = await agent(
+    [
+      `Classify a GSD-T graph-availability failure for the project at \`${projectDir}\`. Steps:`,
+      `1. If \`${projectDir}/bin/gsd-t-graph-availability.cjs\` exists, run: \`node ${projectDir}/bin/gsd-t-graph-availability.cjs classify '${String(reason || "").replace(/'/g, "'\\''")}' '${String(detail || "").replace(/'/g, "'\\''")}'\` (via="local"). Otherwise run: \`gsd-t graph-availability classify '${String(reason || "")}' '${String(detail || "")}'\` (via="global"). cwd \`${projectDir}\`.`,
+      `2. The command prints ONE JSON envelope with a "state" field ("ABSENT" or "BROKEN"). Copy "state" up to the top level of your reply.`,
+      `Do NOT do any other work.`,
+    ].join("\n"),
+    { label: "graph:classify", phase: "Graph-Wiring", model: "haiku", schema: { type: "object", required: ["state"], additionalProperties: true, properties: { state: { type: "string" } } } }
+  ).catch(() => null);
+  return (r && (r.state === "ABSENT" || r.state === "BROKEN")) ? r.state : "BROKEN";
+}
+
 // M99 D2: persist a kind:'wiring' ledger line for this workflow.
 // M81 sandbox: all I/O through agent() Bash; no require/fs in the sandbox.
 // Uses the `gsd-t graph wiring-log` CLI shim (avoids embedding require() in strings).
@@ -413,20 +431,32 @@ if (graphMode === "disabled") {
   // every project lacking a pre-built index (hilo-figma-atos 2026-06-30).
   // [RULE] scan-builds-index-when-absent
   if (!statusResult || !statusResult.ok) {
-    log(`graph-wiring: index not queryable (${(statusResult && statusResult.reason) || "graph-unavailable"}) — building it now (gsd-t graph index)...`);
-    const buildResult = await runCliBuild();
-    if (buildResult && buildResult.ok) {
-      log(`graph-wiring: index build OK — re-probing status.`);
-      statusResult = await runCli("status", null, "status");
+    // [RULE] one-availability-classifier — distinguish ABSENT (build once) from BROKEN (name it).
+    const _reason = (statusResult && statusResult.reason) || "graph-broken";
+    const _state = await classifyGraphFailure(_reason, statusResult && statusResult.detail);
+    if (_state === "ABSENT") {
+      // [RULE] absent-graph-auto-builds-once / [RULE] scan-builds-index-when-absent
+      log(`graph-wiring: index ABSENT (${_reason}) — building it now (gsd-t graph index)...`);
+      const buildResult = await runCliBuild();
+      if (buildResult && buildResult.ok) {
+        log(`graph-wiring: index build OK — re-probing status.`);
+        statusResult = await runCli("status", null, "status");
+      } else {
+        log(`graph-wiring: index build FAILED [${(buildResult && buildResult.reason) || "build-failed"}] — graph now BROKEN (build infra failing).`);
+      }
     } else {
-      log(`graph-wiring: index build FAILED [${(buildResult && buildResult.reason) || "build-failed"}] — falling back to grep-mode.`);
+      // BROKEN — do NOT waste a build; name it loudly (announced carve-out continues grep-mode).
+      log(`graph-wiring: graph BROKEN (${_reason}) — NOT merely un-indexed; a build won't fix it. Fix it: gsd-t graph status.`);
     }
   }
   if (!statusResult || !statusResult.ok) {
-    // Graph still unavailable after a build attempt — announce fallback, continue
-    // with intact grep-mode scan. [RULE] parser-fail-disables-loud-never-silent
+    // Graph still unavailable — classify for an honest ABSENT-vs-BROKEN message, then
+    // announce fallback and continue with intact grep-mode scan (exempt carve-out).
+    // [RULE] parser-fail-disables-loud-never-silent [RULE] broken-graph-halts-never-greps (carve-out: name BROKEN loudly)
     graphWiringMode = "fallback-announced";
-    log(`⚠ GRAPH-FALLBACK (ANNOUNCED): graph unavailable after build attempt [reason=${(statusResult && statusResult.reason) || "graph-unavailable"}, via=${(statusResult && statusResult.via) || "?"}] — scan continues in full grep-mode (today's architecture, intact). Structural findings from LLM reconstruction only.`);
+    const _finReason = (statusResult && statusResult.reason) || "graph-broken";
+    const _finState = await classifyGraphFailure(_finReason, statusResult && statusResult.detail);
+    log(`⚠ GRAPH-FALLBACK (ANNOUNCED): graph ${_finState} [reason=${_finReason}, via=${(statusResult && statusResult.via) || "?"}] — scan continues in full grep-mode (today's architecture, intact). Structural findings from LLM reconstruction only.${_finState === "BROKEN" ? " NOTE: graph is BROKEN, not merely absent — fix it (gsd-t graph status)." : ""}`);
     await persistWiringMode("fallback-announced"); // M99 D2 [RULE] wiring-mode-three-states
   } else {
     // Step 2: query the structural slice (dead-code + dangling + clusters).

package/templates/workflows/gsd-t-verify.workflow.js

@@ -77,6 +77,20 @@ async function runCli(projectDir, subcmd, argv, localBin, label, parseJson = tru
   return r || { ok: false, exitCode: -1, envelope: null, via: "error" };
 }
 async function runPreflight(projectDir, label = "preflight", phaseName) { return runCli(projectDir, "preflight", ["--json"], "cli-preflight.cjs", label, true, phaseName); }
+// Broken-Graph-Halts (EXEMPT carve-out): verify's graph slice is additive/announced — it
+// does not hard-fail on an unavailable graph. But it MUST DISTINGUISH absent from broken and
+// name BROKEN loudly, never silently continue as if merely un-indexed.
+// [RULE] one-availability-classifier [RULE] broken-graph-halts-never-greps (carve-out: name BROKEN loudly)
+async function classifyGraphFailure(projectDir, reason, detail, phaseName) {
+  const r = await runCli(
+    projectDir, "graph-availability",
+    ["classify", String(reason || ""), String(detail || "")],
+    "gsd-t-graph-availability.cjs", "graph-classify", true, phaseName
+  ).catch(() => null);
+  const env = r && r.envelope;
+  if (env && (env.state === "ABSENT" || env.state === "BROKEN")) return env.state;
+  return "BROKEN";
+}
 async function runVerifyGate(projectDir, label = "verify-gate", phaseName) { return runCli(projectDir, "verify-gate", ["--json"], "gsd-t-verify-gate.cjs", label, true, phaseName); }
 // M92 D2 (keystone) — the deterministic shrink-metric. Computes the milestone diff's
 // net size from `git diff --numstat <range>` via the shared runCli helper (M71-clean:
@@ -295,8 +309,14 @@ let _graphVerifyWarning = null;
   if (dcEnv.ok === true) {
     _graphDeadCodeSlice = dcEnv;
     log(`M94 graph dead-code: ${(dcEnv.results || []).length} dead-code result(s) (tier: ${dcEnv.tier || "?"})`);
-  } else if (dcEnv.reason === "graph-unavailable") {
-    _graphVerifyWarning = "⚠ graph unavailable — structural gate skipped, fix it (gsd-t graph status)";
+  } else if (dcEnv.ok === false) {
+    // [RULE] one-availability-classifier — distinguish ABSENT (announced skip) from BROKEN (LOUD).
+    const _state = await classifyGraphFailure(projectDir, dcEnv.reason, dcEnv.detail, "Verify-Gate");
+    if (_state === "BROKEN") {
+      _graphVerifyWarning = `⚠ graph BROKEN (reason=${dcEnv.reason || "?"}) — structural gate skipped. This is NOT merely un-indexed; FIX it (gsd-t graph status).`;
+    } else {
+      _graphVerifyWarning = "⚠ graph ABSENT (never indexed) — structural gate skipped (announced carve-out; build with gsd-t graph index)";
+    }
     log(`M94 graph dead-code: ${_graphVerifyWarning}`);
   } else {
     _graphVerifyWarning = `⚠ graph dead-code query unexpected envelope (reason: ${dcEnv.reason || "?"}); structural gate skipped`;