@tekyzinc/gsd-t 5.11.31 → 5.11.32

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.11.32] - 2026-08-14
+
+### Fixed — a missing graph is now BUILT, and a "wired" claim has to prove itself
+
+A TimeTracking scan finished, reported success, and had done its whole deep
+analysis with grep. The graph was healthy, current, and the run even logged
+`graphWiringMode: WIRED` — but of 666 ledger events, every single one carried
+`consumer: "cli"`. Not one came from an analyst agent. The reports say it
+plainly in their own words: *"a repo-wide grep shows no caller anywhere."*
+Nothing failed, because nothing was watching for this.
+
+Three defects, one theme — **a check that cannot fail is not a check**:
+
+- **An absent graph left consumers blind instead of building it.** Every
+  FAIL-LOUD clause said: don't fall back to grep, then *proceed without the
+  structural slice*. That is a third bad outcome sitting between the two the
+  doctrine names — the agent answers "what calls this?" with no structural
+  knowledge at all. The clauses in `/quick`, `/debug`, `/design-build` and
+  `/test-sync` now BUILD the index and re-run the query; only a failed build
+  halts. This was already the contract's own rule (§FAIL-LOUD line 64,
+  "REPAIR IT, do not merely halt") — the command docs had been contradicting
+  it. `[RULE] graph-absent-builds-not-degrades`
+- **`/integrate` had a licensed exemption.** It printed `⚠ graph ABSENT —
+  structural wiring-check skipped (announced carve-out)`. A fresh worktree
+  carries no graph (it is gitignored), so the check did nothing on exactly the
+  runs it was written for. Announcing a skip does not stop it being a skip. It
+  now builds. The verify/integrate exception covers the HARD-FAIL only; it
+  never covered the build.
+- **The anti-grep lint aimed at the wrong target.** Being static, its only
+  failure mode is a code shape (`try graph → catch → grep`). A consumer that
+  never calls the graph has no catch block, so the lint reports clean while the
+  entire run uses text search.
+
+### Added — `gsd-t graph-use-gate` (runtime, `[RULE] wired-claim-requires-query-evidence`)
+
+`bin/gsd-t-graph-use-gate.cjs` reads the append-only ledger and fails any
+consumer that logged `WIRED` with zero `kind:"query"` events. It detects the
+**absence of use**, not the presence of a fallback — the thing a static lint
+structurally cannot see. `kind:"read"` (the Read-intercept hook) is never
+accepted as evidence, or it would mask the very failure being detected.
+
+Run against the two projects that prompted this, it flags both — confirming the
+defect is systemic, not a one-off. Wired into `gsd-t-verify-gate.cjs` as the
+FAIL-CLOSED `graph-use` check, propagated via `PROJECT_BIN_TOOLS` (it reads each
+project's own ledger), and covered by `test/m113-graph-use-gate.test.js` — whose
+leading test is the negative one, because a gate nobody has watched fail is a
+gate nobody knows works. Exit `0` clean · `4` violations · `64` bad input; a
+missing ledger is a *documented* no-op PASS under `--verify-mode`, tagged
+`noOpPass:true` so it stays distinguishable from wired-and-clean.
+
+**Still open:** none of this covers ordinary conversational code-reading, which
+is where the original complaint arose — an agent asked "what calls this?" in a
+worktree with no graph and grepped, with nothing objecting. That needs a
+PreToolUse hook on structural Grep/Read, and is deliberately left for its own
+milestone rather than bolted on here.
+
 ## [5.11.31] - 2026-08-11
 
 ### Added — the scanner now ranks its own findings before it numbers them

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v5.11.31** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v5.11.32** - 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-graph-use-gate.cjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-graph-use-gate.cjs
+ *
+ * Graph USE gate — proves a consumer that declared itself WIRED actually
+ * QUERIED the graph.
+ *
+ * [RULE] wired-claim-requires-query-evidence
+ * [RULE] use-gate-detects-absence-of-use-not-presence-of-fallback
+ *
+ * WHY THIS EXISTS (the gap it closes):
+ *   `gsd-t-graph-anti-grep-lint.cjs` is STATIC. It reads source files and looks
+ *   for a `try graph-query -> catch -> structural grep` fallback. That shape is
+ *   the only way it can fail.
+ *
+ *   A real scan failed a different way. Every analyst agent simply NEVER CALLED
+ *   the graph — so there was no catch block, no fallback branch, nothing for a
+ *   static scan to find. The lint passed, the run logged
+ *   `{"kind":"wiring","graphWiringMode":"WIRED"}`, and the whole scan ran on
+ *   text search anyway. A check whose only failure mode is a code shape cannot
+ *   see a consumer that never tried.
+ *
+ *   This gate reads the RUNTIME ledger instead. A consumer that stamped WIRED
+ *   and issued zero graph queries in that run is a violation, because "wired"
+ *   is a claim about behaviour and the ledger is the only record of behaviour.
+ *
+ * INPUT  : .gsd-t/graphDB/logs/graph-events-*.jsonl (append-only, JSONL)
+ * OUTPUT : {ok, violations:[{consumer, wiringMode, queryCount, firstWiringTs}], ...}
+ * EXIT   : 0 clean | 4 violations | 64 bad input (no ledger / unreadable)
+ *
+ * Unreadable input THROWS (LedgerUnavailable) rather than returning a value —
+ * a gate that hands back a result when it could not read its own evidence is
+ * the exact failure mode this file exists to remove.
+ *
+ * Node built-ins only (zero-dep invariant).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// A `kind:"read"` event is the Read-intercept hook, NOT a structural query — it
+// fires on ordinary file reads and would mask the exact failure this gate exists
+// to catch. Only `kind:"query"` counts as evidence that the graph was consulted.
+const EVIDENCE_KIND = 'query';
+const WIRING_KIND = 'wiring';
+
+// `cli` is the operator at a terminal, not a workflow consumer; it has no WIRED
+// claim to honour. Consumers are exempt ONLY by explicit name here.
+const NON_CONSUMER_IDS = new Set(['cli']);
+
+/** Thrown when the ledger cannot be located or read. Never swallowed internally. */
+class LedgerUnavailable extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'LedgerUnavailable';
+  }
+}
+
+function ledgerDir(projectDir) {
+  return path.join(projectDir, '.gsd-t', 'graphDB', 'logs');
+}
+
+/** Resolve every graph-events-*.jsonl file, oldest first. Throws if none. */
+function ledgerFiles(projectDir) {
+  const dir = ledgerDir(projectDir);
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch (err) {
+    throw new LedgerUnavailable(`graph event ledger not readable: ${dir} (${err.code || err.message})`);
+  }
+  const files = names
+    .filter((n) => /^graph-events-\d+\.jsonl$/.test(n))
+    .sort()
+    .map((n) => path.join(dir, n));
+  if (files.length === 0) {
+    throw new LedgerUnavailable(`no graph-events-*.jsonl in ${dir}`);
+  }
+  return files;
+}
+
+/**
+ * Parse the ledger into per-consumer counters.
+ * A malformed line is SKIPPED and COUNTED — it is never treated as a query,
+ * because counting an unparseable line as evidence would let a corrupt ledger
+ * satisfy the gate.
+ */
+function readLedger(files, sinceTs) {
+  const consumers = Object.create(null); // prototype-less: consumer ids come from a file
+  let malformed = 0;
+  let total = 0;
+
+  const ensure = (id) => {
+    if (!consumers[id]) {
+      consumers[id] = { consumer: id, queryCount: 0, wiringModes: [], firstWiringTs: null };
+    }
+    return consumers[id];
+  };
+
+  for (const file of files) {
+    let text;
+    try {
+      text = fs.readFileSync(file, 'utf8');
+    } catch (err) {
+      throw new LedgerUnavailable(`cannot read ${file}: ${err.code || err.message}`);
+    }
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      total++;
+      let ev;
+      try {
+        ev = JSON.parse(line);
+      } catch (err) {
+        malformed++;
+        continue;
+      }
+      if (sinceTs && typeof ev.ts === 'string' && ev.ts < sinceTs) continue;
+
+      const id = typeof ev.consumer === 'string' && ev.consumer ? ev.consumer : 'unknown';
+      const kind = String(ev.kind || '');
+
+      if (kind === EVIDENCE_KIND) {
+        ensure(id).queryCount++;
+      } else if (kind === WIRING_KIND) {
+        const c = ensure(id);
+        c.wiringModes.push(String(ev.graphWiringMode || ''));
+        if (!c.firstWiringTs && typeof ev.ts === 'string') c.firstWiringTs = ev.ts;
+      }
+    }
+  }
+  return { consumers, malformed, total };
+}
+
+/**
+ * A consumer violates the gate when it CLAIMED wired and issued ZERO queries.
+ * Claiming `fallback-announced` or `disabled` is not a violation here — those
+ * are honest declarations, and the anti-grep lint governs whether the fallback
+ * itself is permitted.
+ */
+function evaluate(consumers) {
+  const violations = [];
+  const checked = [];
+
+  for (const id of Object.keys(consumers)) {
+    if (NON_CONSUMER_IDS.has(id)) continue;
+    const c = consumers[id];
+    if (c.wiringModes.length === 0) continue; // never declared; nothing claimed, nothing to prove
+
+    const claimedWired = c.wiringModes.some((m) => m.toLowerCase() === 'wired');
+    checked.push({ consumer: id, wiringModes: c.wiringModes, queryCount: c.queryCount });
+
+    if (claimedWired && c.queryCount === 0) {
+      violations.push({
+        consumer: id,
+        wiringMode: 'WIRED',
+        queryCount: 0,
+        firstWiringTs: c.firstWiringTs,
+        evidence:
+          `consumer "${id}" logged graphWiringMode=WIRED but issued 0 graph queries ` +
+          `(kind:"query") in this window — a WIRED claim with no query evidence means ` +
+          `the structural question was answered some other way.`,
+      });
+    }
+  }
+  return { violations, checked };
+}
+
+/** Throws LedgerUnavailable when the evidence cannot be read. */
+function runGate(opts = {}) {
+  const projectDir = opts.projectDir || process.cwd();
+
+  // Test override: callers may inject parsed consumers directly.
+  if (opts.consumers) {
+    const { violations, checked } = evaluate(opts.consumers);
+    return { ok: violations.length === 0, violations, checked, malformed: 0, ledgerFiles: [] };
+  }
+
+  const files = ledgerFiles(projectDir);
+  const { consumers, malformed } = readLedger(files, opts.since || null);
+  const { violations, checked } = evaluate(consumers);
+  return { ok: violations.length === 0, violations, checked, malformed, ledgerFiles: files };
+}
+
+// ─── CLI entry point ─────────────────────────────────────────────────────────
+
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  const opts = { projectDir: process.cwd() };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--project' || argv[i] === '--repo') opts.projectDir = argv[++i];
+    else if (argv[i] === '--since') opts.since = argv[++i];
+    else if (argv[i] === '--verify-mode') opts.verifyMode = true;
+    else if (!argv[i].startsWith('-')) opts.projectDir = argv[i];
+  }
+
+  let result;
+  try {
+    result = runGate(opts);
+  } catch (err) {
+    if (err instanceof LedgerUnavailable) {
+      // No ledger means NO CONSUMER HAS RUN YET — nothing has been claimed, so
+      // there is nothing to disprove. That is a documented no-op PASS in
+      // --verify-mode, distinguishable in the JSON (`noOpPass:true`) from a
+      // wired-but-broken run. Invoked directly it is BAD INPUT (exit 64): an
+      // operator asking about evidence that does not exist deserves to be told,
+      // not handed a clean bill.
+      if (opts.verifyMode) {
+        process.stdout.write(JSON.stringify(
+          { ok: true, noOpPass: true, reason: 'no-graph-event-ledger', violations: [], checked: [] }, null, 2) + '\n');
+        process.stderr.write('[graph-use-gate] PASS (no-op): no graph event ledger — no consumer has claimed WIRED yet.\n');
+        process.exit(0);
+      }
+      process.stderr.write(`[graph-use-gate] ERROR: ${err.message}\n`);
+      process.stdout.write(JSON.stringify({ ok: false, violations: [], error: err.message }, null, 2) + '\n');
+      process.exit(64);
+    }
+    throw err;
+  }
+
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+
+  if (!result.ok) {
+    process.stderr.write(
+      `[graph-use-gate] FAIL: ${result.violations.length} consumer(s) claimed WIRED with zero graph queries.\n`
+    );
+    for (const v of result.violations) {
+      process.stderr.write(`  ${v.consumer}: ${v.evidence}\n`);
+    }
+    process.exit(4);
+  }
+  process.stderr.write(
+    `[graph-use-gate] PASS: ${result.checked.length} declaring consumer(s), all WIRED claims backed by queries.\n`
+  );
+  process.exit(0);
+}
+
+module.exports = { runGate, readLedger, evaluate, ledgerFiles, LedgerUnavailable, EVIDENCE_KIND, NON_CONSUMER_IDS };

package/bin/gsd-t-verify-gate.cjs

@@ -313,6 +313,8 @@ function _detectDefaultTrack2(projectDir, notes) {
 
   plan.push({ id: 'fallbacks', cmd: 'node', args: [path.join(__dirname, 'gsd-t-fallback-detect.cjs'), '--scan', '--project', projectDir, '--json'], timeoutMs: 120000 }); // M106: no unapproved continue-after-failure branch, FAIL-CLOSED (pre-existing ones excluded via .gsd-t/fallbacks-baseline.json)
 
+  plan.push({ id: 'graph-use', cmd: 'node', args: [path.join(__dirname, 'gsd-t-graph-use-gate.cjs'), '--project', projectDir, '--verify-mode'], timeoutMs: 30000 }); // M113: a consumer that logged graphWiringMode=WIRED must have issued >=1 graph query, FAIL-CLOSED (documented no-op PASS when no ledger exists yet). Catches what the STATIC anti-grep lint structurally cannot: a consumer that never queried at all.
+
   // secrets — gitleaks (PATH detection deferred to runtime)
   if (_hasOnPath('gitleaks')) {
     plan.push({

package/bin/gsd-t.js

@@ -3487,6 +3487,10 @@ const PROJECT_BIN_TOOLS = [
   // every Write/Edit is DENIED (the guard halts rather than allowing unchecked),
   // so this entry is load-bearing — [[project_global_bin_propagation_gap]].
   "gsd-t-fallback-detect.cjs",
+  // M113 — Graph USE gate. The verify gate dispatches to it by absolute path,
+  // and it reads the project's OWN .gsd-t/graphDB/logs ledger, so it must live
+  // in the project — [[project_global_bin_propagation_gap]].
+  "gsd-t-graph-use-gate.cjs",
   // M107 — Concise rewriter, invoked by the Stop hook.
   // M108 — Install self-check. Every project carries its own copy so it can
   // verify and repair itself even when the global install is what broke.

package/commands/gsd-t-debug.md

@@ -98,7 +98,7 @@ Debug applies the **WRITER pattern** from `graph-consumer-wiring-contract.md`:
 
 **WRITER half (re-index after fix):** After the fix lands, the workflow triggers a re-index of the edited files so downstream graph queries see fresh edges (`graph-freshness-contract.md` D4 surface — `freshness_check_on_query` over the touched set). `[RULE] debug-reader-and-writer-both`.
 
-**FAIL-LOUD on graph-unavailable:** On `{ok:false, reason:"graph-unavailable"}`, the debug workflow surfaces `"graph unavailable — fix it (gsd-t graph status)"` and halts the graph-query step. It does NOT fall back to grep for the structural question. The existing debug-loop logic (2-cycle cap, loop-ledger halt) is NOT disrupted — the graph query is additive, injected before the fix agent receives context.
+**BUILD-THEN-QUERY on graph-absent:** On `{ok:false, reason:"graph-unavailable"}` the debug workflow **builds the index right then** (`gsd-t graph index`) and re-runs the localization query. It does NOT fall back to grep for the structural question, and it does NOT skip the query. Only a **failed build** halts the graph-query step, with the build's own stderr surfaced. The existing debug-loop logic (2-cycle cap, loop-ledger halt) is NOT disrupted — the graph query is additive, injected before the fix agent receives context. `[RULE] graph-absent-builds-not-degrades`.
 
 ## Contract-Boundary Debugging
 

package/commands/gsd-t-design-build.md

@@ -10,7 +10,7 @@ Design-build applies the **WRITER pattern** from `graph-consumer-wiring-contract
 
 **WRITER half:** After each tier (elements → widgets → pages) generates files, the pipeline triggers a re-index of the generated files (`freshness_check_on_query` from `graph-freshness-contract.md` D4 surface) so the next tier's `who-imports` / `cluster` query sees the new edges from the generated components. `[RULE] design-build-writer-pattern`.
 
-**FAIL-LOUD on graph-unavailable:** On `{ok:false, reason:"graph-unavailable"}`, the structural query surfaces `"graph unavailable — fix it (gsd-t graph status)"` — the pipeline does NOT fall back to grep for the structural question. `[RULE] consumer-structural-grep-removed`.
+**BUILD-THEN-QUERY on graph-absent:** On `{ok:false, reason:"graph-unavailable"}` the pipeline **builds the index right then** (`gsd-t graph index`) and re-runs the structural query. It does NOT fall back to grep, and it does NOT proceed without the structural answer. Only a **failed build** halts, with the build's own stderr surfaced. `[RULE] consumer-structural-grep-removed`, `[RULE] graph-absent-builds-not-degrades`.
 
 ## Step 1: Launch the Orchestrator
 

package/commands/gsd-t-quick.md

@@ -182,7 +182,7 @@ Quick applies the **WRITER pattern** from `graph-consumer-wiring-contract.md`:
 
 **WRITER half:** After edits land, the workflow triggers a re-index of the touched files (`freshness_check_on_query` from `graph-freshness-contract.md` D4 surface) so downstream graph queries see fresh edges. `[RULE] quick-writer-pattern`.
 
-**FAIL-LOUD on graph-unavailable:** On `{ok:false, reason:"graph-unavailable"}`, the structural-impact query surfaces `"graph unavailable — fix it (gsd-t graph status)"` and the agent proceeds without the structural slice — it does NOT fall back to grep for the structural question. `[RULE] consumer-structural-grep-removed`.
+**BUILD-THEN-QUERY on graph-absent:** On `{ok:false, reason:"graph-unavailable"}` the workflow **builds the index right then** (`gsd-t graph index`) and re-runs the query. It does NOT fall back to grep, and it does NOT proceed without the structural slice — proceeding blind is a third failure mode, not a safe default. Only a **failed build** halts, with the build's own stderr surfaced. `[RULE] consumer-structural-grep-removed`, `[RULE] graph-absent-builds-not-degrades`.
 
 ## Step 1.5: Graph-Enhanced Scope Check
 

package/commands/gsd-t-test-sync.md

@@ -40,7 +40,7 @@ Test-sync applies the **WRITER pattern** from `graph-consumer-wiring-contract.md
 
 **WRITER half:** After writing or updating tests, trigger a re-index of the edited test files (`freshness_check_on_query` from `graph-freshness-contract.md` D4 surface) so the next `test-impl` query sees the updated call-site edges from the new test code. `[RULE] test-sync-uses-test-impl-verb`.
 
-**FAIL-LOUD on graph-unavailable:** On `{ok:false, reason:"graph-unavailable"}`, the test-impl query surfaces `"graph unavailable — fix it (gsd-t graph status)"` and the agent proceeds with filesystem discovery as announced fallback — it does NOT silently treat a missing graph as "no coverage". `[RULE] consumer-structural-grep-removed`.
+**BUILD-THEN-QUERY on graph-absent:** On `{ok:false, reason:"graph-unavailable"}` the workflow **builds the index right then** (`gsd-t graph index`) and re-runs the `test-impl` / `untested-impl` queries. Filesystem discovery is NOT an acceptable substitute — announcing a fallback does not stop it being one, and "which test exercises which impl" answered by filename convention is exactly the wrong-answer class the graph exists to remove. Only a **failed build** halts, with the build's own stderr surfaced. `[RULE] consumer-structural-grep-removed`, `[RULE] graph-absent-builds-not-degrades`.
 
 ## Step 1.5: Graph-Enhanced Test Discovery
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.11.31",
-  "description": "GSD-T: Contract-Driven Development for Claude Code \u2014 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",
+  "version": "5.11.32",
+  "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",
   "repository": {

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

@@ -79,6 +79,15 @@ async function classifyGraphFailure(projectDir, reason, detail, phaseName) {
   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
+// `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); }
 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`];
@@ -133,32 +142,54 @@ await persistWiringMode("Preflight");
 
 // M94-D10-T6: Graph Structural Slice — who-imports + blast-radius (ADDITIVE, announced-degradation)
 // [RULE] integrate-uses-graph-for-wiring-verification
-// [RULE] verify-integrate-graph-additive-announced-not-hard-fail — bootstrap carve-out:
-//   integrate degrades ANNOUNCED on graph-unavailable, does NOT hard-fail.
+// [RULE] verify-integrate-graph-additive-announced-not-hard-fail — integrate does NOT
+//   hard-fail on a graph it cannot use. It DOES build an ABSENT index first
+//   ([RULE] graph-absent-builds-not-degrades); only a BROKEN graph, or a build that
+//   itself fails, degrades announced.
 let _graphWhoImportsSlice = null;
 let _graphBlastRadiusSlice = null;
 let _graphIntegrateWarning = null;
 
 {
-  const wiResult = await runCli(
+  // [RULE] graph-absent-builds-not-degrades — an ABSENT graph is BUILT here, not
+  // skipped. The former "announced carve-out" skipped the structural wiring-check
+  // whenever the index had never been built — which is exactly when integrate most
+  // needs it, because a fresh worktree carries no graph (it is gitignored). The
+  // check therefore did nothing on the very runs it was written for. Announcing a
+  // skip does not stop it being a skip.
+  let wiEnv = (await runCli(
     projectDir, "graph who-imports", [], "gsd-t-graph-query-cli.cjs",
     "graph:who-imports", true, "Integrate"
-  );
-  const wiEnv = wiResult.envelope || {};
-  if (wiEnv.ok === true) {
-    _graphWhoImportsSlice = wiEnv;
-    log(`M94 graph who-imports: ${(wiEnv.results || []).length} result(s) (tier: ${wiEnv.tier || "?"})`);
-  } else if (wiEnv.ok === false) {
-    // [RULE] one-availability-classifier — distinguish ABSENT (announced skip) from BROKEN (LOUD).
+  )).envelope || {};
+
+  if (wiEnv.ok === false) {
+    // [RULE] one-availability-classifier — ONE classify call, ONE state, no re-derivation.
     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).`;
+    if (_state === "ABSENT") {
+      log("M94 graph who-imports: index ABSENT (never indexed) — building it now (gsd-t graph index)...");
+      if (await buildGraphIndex(projectDir, "Integrate")) {
+        wiEnv = (await runCli(
+          projectDir, "graph who-imports", [], "gsd-t-graph-query-cli.cjs",
+          "graph:who-imports", true, "Integrate"
+        )).envelope || {};
+        if (wiEnv.ok !== true) {
+          _graphIntegrateWarning = `⚠ graph built but who-imports still failed (reason=${wiEnv.reason || "?"}) — structural wiring-check skipped. FIX it (gsd-t graph status).`;
+        }
+      } else {
+        // A failed BUILD is loud, and distinct from a merely-missing index.
+        _graphIntegrateWarning = "⚠ graph ABSENT and `gsd-t graph index` FAILED — structural wiring-check cannot run. 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)";
+      _graphIntegrateWarning = `⚠ graph BROKEN (reason=${wiEnv.reason || "?"}) — structural wiring-check skipped. This is NOT merely un-indexed; FIX it (gsd-t graph status).`;
     }
-    log(`M94 graph who-imports: ${_graphIntegrateWarning}`);
-  } else {
+  } else if (wiEnv.ok !== true) {
     _graphIntegrateWarning = `⚠ graph who-imports query unexpected envelope (reason: ${wiEnv.reason || "?"}); structural wiring-check skipped`;
+  }
+
+  if (wiEnv.ok === true) {
+    _graphWhoImportsSlice = wiEnv;
+    log(`M94 graph who-imports: ${(wiEnv.results || []).length} result(s) (tier: ${wiEnv.tier || "?"})`);
+  } else {
     log(`M94 graph who-imports: ${_graphIntegrateWarning}`);
   }
 

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

@@ -1309,12 +1309,16 @@ const ARCHITECT_SCHEMA = {
         additionalProperties: true,
         properties: {
           key:       { type: "string", description: "short id, e.g. R1" },
-          name:      { type: "string", description: "plain-English name of the shared cause" },
-          why:       { type: "string", description: "why these are one cause, with code evidence" },
-          fix:       { type: "string", description: "the single fix that closes them" },
+          // Short by contract, not by request. The first architect run produced
+          // headings like "Doors that check who you are but never which flight
+          // school you belong to" over 250-word explanations; a reader scanning
+          // 28 roots for the one to fix next cannot skim that.
+          name:      { type: "string", maxLength: 40, description: "2-5 word noun phrase, e.g. 'Missing tenant scoping'. NOT a sentence." },
+          why:       { type: "string", maxLength: 320, description: "ONE sentence naming the shared mistake, plus the file:line citations that prove it. Keep every citation; compress the prose around them." },
+          fix:       { type: "string", maxLength: 200, description: "ONE sentence: the single change that closes them all." },
           tier:      { type: "string", enum: ["EXTREME", "CRITICAL", "HIGH", "MEDIUM", "LOW", "extreme", "critical", "high", "medium", "low"] },
           rank:      { type: "integer", description: "rank among roots of the same tier, 1 = worst" },
-          rankReason:{ type: "string" },
+          rankReason:{ type: "string", maxLength: 220, description: "ONE sentence: why this root outranks the ones below it in its tier." },
         },
       },
     },
@@ -1413,7 +1417,8 @@ async function architectPass(findings) {
       `FINDINGS:`,
       listing,
       ``,
-      `GROUP BY ROOT CAUSE. A root is one underlying cause where ONE fix closes several findings — e.g. many routes missing the same tenant check. For each root give a plain-English name, why they are one cause (with code evidence), the single fix, and its members by index. A root with ONE member is not a group; leave it standalone. A root's tier is the tier of its WORST member.`,
+      `GROUP BY ROOT CAUSE. A root is one underlying cause where ONE fix closes several findings — e.g. many routes missing the same tenant check. A root with ONE member is not a group; leave it standalone. A root's tier is the tier of its WORST member.`,
+      `WRITE IT SHORT. The name is a 2-5 word noun phrase ("Missing tenant scoping", "Silent write failures"), never a sentence. \`why\` and \`fix\` and \`rankReason\` are ONE sentence each. Someone scanning 28 roots to pick what to fix next cannot read a paragraph per root — but KEEP every file:line citation inside \`why\`, because those are what make the grouping checkable. Compress the prose, never the evidence.`,
       `Rank roots within their tier by worst consequence, and members within a root by consequence. RISK order, never the order the findings arrived.`,
       ``,
       `Return JSON per the schema. Every one of the ${chunk.length} findings must appear exactly once in \`placements\` — a finding you drop is a defect nobody will see again.`,
@@ -1506,6 +1511,8 @@ if (architect) {
         f._rootKey = p.rootKey;
         f._rootName = (root && root.name) || p.rootKey;
         f._rootFix = root && root.fix;
+        f._rootWhy = root && root.why;
+        f._rootRankReason = root && root.rankReason;
         f._rootRank = (root && Number.isInteger(root.rank)) ? root.rank : 99;
         f._rankInRoot = Number.isInteger(p.rankInRoot) ? p.rankInRoot : 99;
       }
@@ -1610,17 +1617,34 @@ function fmtChunks(today) {
 
   const CHUNK_MAX = 30000;
   const chunks = [head.join("\n")];
-  let buf = "", n = tdStart, lastSev = null, lastType = null;
+  let buf = "", n = tdStart, lastSev = null, lastType = null, lastRoot = null;
   const flush = () => { if (buf) { chunks.push(buf); buf = ""; } };
   // Consume the shared `orderedFindings` (severity → type → original-index) so the
   // TD numbers assigned here are IDENTICAL to those the consolidation stage references.
   for (const { f, t } of orderedFindings) {
     let piece = "";
-    if (f.severity !== lastSev) { piece += `\n## ${sevHead[f.severity] || f.severity} Priority\n\n`; lastSev = f.severity; lastType = null; }
+    if (f.severity !== lastSev) { piece += `\n## ${sevHead[f.severity] || f.severity} Priority\n\n`; lastSev = f.severity; lastType = null; lastRoot = null; }
     // Type sub-heading uses a bold marker line (NOT `###`) so it never collides with
     // the `### TD-N` item headings that downstream tools grep for. ASCII hyphens only
     // (M76: no em/en-dashes in fmtChunks literals).
-    if (t !== lastType) { piece += `**-- ${t} --**\n\n`; lastType = t; }
+    // Root grouping is the fix unit. When the architect grouped the findings, the
+    // register shows the root and its one-line cause/fix/rank above its members,
+    // because scheduling the members separately produces separate half-fixes of
+    // one defect. Bullets sit in <sub> so the eye lands on the finding titles.
+    // Without an architect result there are no roots, and the old type marker
+    // still separates the sections.
+    if (f._rootKey && f._rootKey !== lastRoot) {
+      piece += `\n### ${f._rootKey} - ${ascii(f._rootName) || f._rootKey}\n\n<sub>\n\n`;
+      if (f._rootWhy) piece += `- **Cause:** ${ascii(f._rootWhy)}\n`;
+      if (f._rootFix) piece += `- **Fix:** ${ascii(f._rootFix)}\n`;
+      if (f._rootRankReason) piece += `- **Rank:** ${ascii(f._rootRankReason)}\n`;
+      piece += `\n</sub>\n\n`;
+      lastRoot = f._rootKey; lastType = null;
+    } else if (!f._rootKey && lastRoot) {
+      piece += `\n### Standalone\n\n`;
+      lastRoot = null; lastType = null;
+    }
+    if (!f._rootKey && t !== lastType) { piece += `**-- ${t} --**\n\n`; lastType = t; }
     piece += itemMd(f, n++);
     if (buf.length + piece.length > CHUNK_MAX) flush();
     buf += piece;