@tekyzinc/gsd-t 5.11.30 → 5.11.32

package/CHANGELOG.md

@@ -2,6 +2,127 @@
 
 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
+
+A 492-finding scan of hilo-figma-atos was grouped by severity and ordered by
+discovery inside each group, so "fix the criticals in order" gave you a dead
+marketing page before the missing database access rules on 193 tenant tables.
+Run by hand over that register, an architect pass changed the answer enough to
+become a permanent stage:
+
+- The worst defect in the codebase was filed HIGH. Account credits that cover a
+  whole invoice are never marked used, so the same credit is given away again
+  every month, forever. It sat at position 127.
+- A typo in one text box silently routes every real card payment to the practice
+  gateway, where charges report success and no money moves. Filed MEDIUM.
+- Every school's signed legal agreements are downloadable by any other school.
+  Filed LOW.
+- A fabricated thunderstorm advisory for a named airport is shown to pilots on
+  every page. Filed MEDIUM.
+- 22 findings were confirmed unreachable code, carried as risk.
+
+And the work changed shape: 492 findings collapsed into 28 root causes, with 144
+of the 328 medium/low findings attaching to a root that already existed. The
+codebase does not have 492 problems; it has about 28, most repeated dozens of
+times. Scheduled individually, that produces dozens of half-fixes of one defect.
+
+**Four changes, all measured on that run:**
+
+**Architect stage** (`phase("Architect")`, after Synthesis, before ordering) —
+re-tiers by consequence, groups by root cause, ranks roots within tier and
+members within root, and marks confirmed dead code so it sinks below live
+findings. TD numbers are assigned AFTER it, so TD-1 is the most urgent thing in
+the codebase. Adds an EXTREME tier: leaves wrong data behind, crosses a tenant
+boundary, moves money wrongly, or touches safety — as against CRITICAL, where
+the feature merely does not work. Carries the dynamic-import warning that nearly
+cost a live credit-card form its rating, and halts if the ordering loses a
+finding.
+
+**Verification is batched, 10 findings per agent.** Measured head to head on the
+same 20 findings spanning all four severities: batched caught 1 false positive
+and 2 severity corrections against the individual arm's 0 and 1, for 71 fewer
+characters of evidence and no changed verdict. Severity is comparative — an agent
+seeing findings together can rank them, one seeing a single finding confirms
+whatever it was handed. 492 findings went from ~570 verifier agents to ~50.
+
+**Design-export snapshots are left out of slicing**, and named in the plan.
+`.figma-make-exports/` held 1,532 source files and 968,597 lines on that project
+— six near-identical copies of a design prototype, read by finders as if they
+were the product, for two findings that were both about the folder itself. That
+is roughly 19 slices of finder-and-verifier work.
+
+**One severity phrase per tier.** The plain-English companion labelled all 61
+criticals "fix before launch" for a system already serving customers, and had
+drifted to twelve phrasings for four tiers. An unmapped tier is now announced
+rather than silently labelled "review".
+
+- `templates/workflows/gsd-t-scan.workflow.js`: architect stage + schema, batched
+  verify, tier-derived labels, EXTREME throughout.
+- `bin/gsd-t-slice-budget.cjs`: snapshot-directory exclusion, reported by name.
+- `test/m112-architect-stage.test.js`, `test/m112-severity-labels.test.js`: 15 new
+  regressions; slice-budget and schema-tolerance suites extended.
+
+Two existing tests were pinned to variable names rather than behaviour and failed
+on a change that preserved what they protect; both now assert the property.
+
 ## [5.11.30] - 2026-08-11
 
 ### Fixed — the scan crashed before any finder ran: `slices is not defined`

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v5.11.30** - 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-slice-budget.cjs

@@ -59,6 +59,32 @@ const SKIP_DIRS = new Set([
   'coverage', 'out', '.turbo', '.venv', 'venv', 'Pods', 'vendor', '.gradle',
 ]);
 
+// [RULE] slice-budget-skips-design-export-snapshots
+//
+// hilo-figma-atos, 2026-08-11: `.figma-make-exports/` held 1,879 tracked files
+// and 57 MB of design-tool exports — six dated snapshots of a prototype, each a
+// near-copy of the last. They were measured, sliced, and read by finders as if
+// they were the application. Out of the whole scan, exactly TWO findings came
+// from them, and both were about the directory itself (it has no type-check
+// exclusion; the same key is committed six times) rather than about defects in
+// the product.
+//
+// These are recognised by NAME rather than by a project's own ignore rules,
+// because the project had no such rule — that absence was itself one of the two
+// findings. Matched as a path SEGMENT so a real source folder that merely
+// contains the word (say `src/exports/`) is untouched.
+const SNAPSHOT_DIR_PATTERNS = [
+  /^\.?figma-make-exports$/i,
+  /^\.?figma-exports$/i,
+  /^design-exports?$/i,
+  /^ui-snapshots?$/i,
+  /^__snapshots-export__$/i,
+];
+
+function isSnapshotExportDir(name) {
+  return SNAPSHOT_DIR_PATTERNS.some((re) => re.test(name));
+}
+
 /** Lines in one file. A file that cannot be read is reported, never counted as 0. */
 function countLines(file) {
   const text = fs.readFileSync(file, 'utf8');
@@ -72,7 +98,7 @@ function countLines(file) {
 }
 
 /** Every source file under a path, with its line count. */
-function measurePath(projectDir, rel, problems) {
+function measurePath(projectDir, rel, problems, skippedSnapshots) {
   const abs = path.resolve(projectDir, rel);
   const out = [];
 
@@ -107,6 +133,12 @@ function measurePath(projectDir, rel, problems) {
     for (const ent of entries) {
       if (ent.isDirectory()) {
         if (SKIP_DIRS.has(ent.name)) continue;
+        if (isSnapshotExportDir(ent.name)) {
+          // Reported, never silent: a directory this large vanishing from the
+          // measurement without a word is how a coverage hole hides.
+          skippedSnapshots.push(path.relative(projectDir, path.join(dir, ent.name)));
+          continue;
+        }
         walk(path.join(dir, ent.name));
         continue;
       }
@@ -178,6 +210,7 @@ function splitSlice(slice, files, min, max, oversizedFiles) {
 
 function plan(projectDir, slices, min, max) {
   const problems = [];
+  const skippedSnapshots = [];
   const oversizedFiles = [];
   const out = [];
   let measuredLines = 0;
@@ -188,7 +221,7 @@ function plan(projectDir, slices, min, max) {
     const files = [];
     const seen = new Set();
     for (const p of paths) {
-      for (const f of measurePath(projectDir, p, problems)) {
+      for (const f of measurePath(projectDir, p, problems, skippedSnapshots)) {
         // A file listed under two paths of one slice is one file, counted once.
         if (seen.has(f.file)) continue;
         seen.add(f.file);
@@ -232,6 +265,9 @@ function plan(projectDir, slices, min, max) {
       .sort((a, b) => b.lines - a.lines)
       .map((f) => ({ file: f.file, lines: f.lines })),
     problems,
+    // Design-tool export snapshots left out of the measurement, named so the
+    // omission is visible rather than inferred from a smaller total.
+    skippedSnapshots: Array.from(new Set(skippedSnapshots)).sort(),
     slices: out,
   };
 }

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.30",
-  "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

@@ -183,6 +183,55 @@ const VERIFY_SCHEMA = {
   },
 };
 
+// One verifier reads a BATCH of findings and returns a verdict for each.
+//
+// [RULE] verify-batched-not-one-agent-per-finding
+//
+// Measured on hilo-figma-atos, 2026-08-11 — the same 20 findings, spanning all
+// four severities, verified both ways against real code:
+//
+//                        one-agent-per-finding      batched (20 in one)
+//   false positives caught          0                       1
+//   severity corrections            1                       2
+//   mean evidence length          426 chars               355 chars
+//
+// Batching did not merely cost less — it judged BETTER, and both disagreements
+// were checked by hand and went the batch's way. An agent holding many findings
+// sees them in relation to each other, and severity is a comparative judgment:
+// "help articles leaking" is HIGH *next to* the cross-tenant student-record
+// leaks beside it. An agent handed one finding alone has no yardstick, so it
+// tends to confirm whatever it was given — which is what 20-of-20 confirmed,
+// zero false positives, looked like on the unbatched side.
+//
+// The cost is ~70 characters less evidence per finding, which changed no verdict.
+// The saving is the run: 492 findings went from ~570 verifier agents to ~50.
+const VERIFY_BATCH_SCHEMA = {
+  type: "object",
+  required: ["verdicts"],
+  additionalProperties: true,
+  properties: {
+    verdicts: {
+      type: "array",
+      minItems: 1,
+      items: {
+        type: "object",
+        required: ["index", "verdict"],
+        additionalProperties: true,
+        properties: {
+          // The finding's position in the batch it was given. Position rather
+          // than title: a title can be paraphrased back, an index cannot.
+          index:             { type: "integer" },
+          verdict:           { type: "string", enum: ["confirmed", "CONFIRMED", "Confirmed", "false-positive", "FALSE-POSITIVE", "False-positive", "needs-detail", "NEEDS-DETAIL", "Needs-detail"] },
+          confirmed:         { type: "boolean" },
+          note:              { type: "string" },
+          evidence:          { type: "string" },
+          correctedSeverity: { type: "string", enum: ["CRITICAL", "critical", "Critical", "HIGH", "high", "High", "MEDIUM", "medium", "Medium", "LOW", "low", "Low"] },
+        },
+      },
+    },
+  },
+};
+
 // M75: synthesis no longer writes the register via one agent (the Hilo Scan #14
 // synthesis stalled after 9 of 322 items typing a 466KB file). Instead: a bounded
 // dedup agent (inline DEDUP_SCHEMA, small input) decides merge groups; the
@@ -988,44 +1037,81 @@ async function scanSlice(slice) {
   if (verifyMode === "none" || finderResult.findings.length === 0) {
     return { slice: sliceKey, findings: finderResult.findings || [], failed: false };
   }
-  // Fan out ALL verifies for this slice — the global gate (not a per-slice limit)
-  // bounds total in-flight, so this is safe AND keeps every worker slot busy.
-  const verified = await parallel(
-    finderResult.findings.map((f) => async () => {
-      try {
-        const verifyPrompt = [
-          `You are a VERIFIER for one tech-debt finding in \`${projectDir}\`. Confirm it against the ACTUAL code (open the referenced files with Read) — do not trust the finder.`,
-          `Finding: ${JSON.stringify(f)}`,
-          `confirmed=true only if the defect genuinely exists. If misread → verdict="false-positive". If real but wrong severity → set correctedSeverity. If real but underspecified → verdict="needs-detail" (kept). Return JSON per the schema.`,
-          SHAPE_RULE,
-        ].join("\n");
-
-        // Verify had NO retry: one wrapped call and the finding went through
-        // unverified. Same escalation as the finder, one step shorter — a lost
-        // verdict costs one finding, not a whole slice.
-        let v = await gatedAgent(verifyPrompt, {
-          label: `verify:${sliceKey}`, phase: "Deep Scan", schema: VERIFY_SCHEMA, model: "sonnet",
-        });
-        if (!v) {
-          v = await gatedAgent(verifyPrompt + UNWRAP_HINT, {
-            label: `verify:${sliceKey} (retry on opus)`, phase: "Deep Scan",
-            schema: VERIFY_SCHEMA, model: "opus",
-          });
+  // Verify in BATCHES — see [RULE] verify-batched-not-one-agent-per-finding at
+  // VERIFY_BATCH_SCHEMA for the measurement that chose this over one agent per
+  // finding. Ten is small enough that every finding still gets its files opened,
+  // and large enough that the verifier can weigh them against each other, which
+  // is what severity judgment actually requires.
+  const VERIFY_BATCH_SIZE = 10;
+  const batches = [];
+  for (let i = 0; i < finderResult.findings.length; i += VERIFY_BATCH_SIZE) {
+    batches.push(finderResult.findings.slice(i, i + VERIFY_BATCH_SIZE));
+  }
+
+  const verifiedBatches = await parallel(
+    batches.map((batch, batchNo) => async () => {
+      const verifyPrompt = [
+        `You are a VERIFIER for ${batch.length} tech-debt finding(s) in \`${projectDir}\`. Confirm EACH against the ACTUAL code (open the referenced files with Read) — do not trust the finder.`,
+        ``,
+        `Findings, as a numbered list. Return one verdict per finding, using its \`index\`:`,
+        ...batch.map((f, i) => `[${i}] ${JSON.stringify(f)}`),
+        ``,
+        `For EACH finding: verdict="confirmed" only if the defect genuinely exists. If the finder misread the code → verdict="false-positive". If real but underspecified → verdict="needs-detail" (kept).`,
+        `Set correctedSeverity when the severity is wrong. You are seeing these findings TOGETHER — use that: severity is comparative, and a finding that looks alarming alone is often plainly lesser beside the others in this batch. Judge each one's consequence relative to the rest.`,
+        `Put the file and line you actually checked in \`evidence\`. A verdict with no evidence from the code is the failure this step exists to prevent.`,
+        `Return ONE object per finding, ${batch.length} in total, each carrying its \`index\`. Missing verdicts are treated as unverified.`,
+        SHAPE_RULE,
+      ].join("\n");
+
+      // Attempt 1 — sonnet. Attempt 2 names the likely mistake and escalates to
+      // the model that has never made it. Same shape as the finder escalation.
+      const attempt1 = await gatedAgent(verifyPrompt, {
+        label: `verify:${sliceKey}#${batchNo + 1}`, phase: "Deep Scan",
+        schema: VERIFY_BATCH_SCHEMA, model: "sonnet",
+      });
+      const v = (attempt1 && Array.isArray(attempt1.verdicts)) ? attempt1 : await gatedAgent(
+        verifyPrompt + UNWRAP_HINT,
+        {
+          label: `verify:${sliceKey}#${batchNo + 1} (retry on opus)`, phase: "Deep Scan",
+          schema: VERIFY_BATCH_SCHEMA, model: "opus",
         }
-        // Compared case-INSENSITIVELY: the schema now accepts "false-positive"
-        // in any casing, so an exact match would silently KEEP a finding the
+      );
+
+      const byIndex = new Map();
+      for (const r of ((v && Array.isArray(v.verdicts) && v.verdicts) || [])) {
+        if (Number.isInteger(r.index)) byIndex.set(r.index, r);
+      }
+
+      return batch.map((f, i) => {
+        const r = byIndex.get(i);
+        // No verdict came back for this finding. It is NOT dropped and NOT
+        // silently passed as verified — it is kept and MARKED, so a batch that
+        // answered for eight of ten cannot quietly delete the other two, and
+        // the register can show which findings nobody checked.
+        if (!r) return { ...f, _verify: "unverified" };
+
+        // Compared case-INSENSITIVELY: the schema accepts "false-positive" in
+        // any casing, so an exact match would silently KEEP a finding the
         // verifier had rejected.
-        const verdict = String(v && v.verdict || "").toLowerCase();
-        if (!v || verdict === "false-positive" || v.confirmed === false) return null;
-        // Severity is normalised to the shouted form here, once, so the report
+        const verdict = String(r.verdict || "").toLowerCase();
+        if (verdict === "false-positive" || r.confirmed === false) return null;
+
+        // Severity normalised to the shouted form here, once, so the report
         // reads consistently no matter how a finder typed it.
-        const sev = String(v.correctedSeverity || f.severity || "").toUpperCase();
-        return { ...f, severity: sev, _verify: verdict };
-      } catch (e) {
-        return { ...f, _verify: "verify-errored" };
-      }
+        const sev = String(r.correctedSeverity || f.severity || "").toUpperCase();
+        const out = { ...f, severity: sev, _verify: verdict || "confirmed" };
+        if (r.evidence) out._evidence = r.evidence;
+        return out;
+      });
     })
   );
+
+  // A batch whose agent died resolves to null; its findings are kept and marked
+  // rather than lost — losing a real defect is worse than carrying an unchecked
+  // one, and the mark is what stops it reading as verified.
+  const verified = verifiedBatches.flatMap((res, batchNo) =>
+    res === null ? batches[batchNo].map((f) => ({ ...f, _verify: "verify-errored" })) : res
+  );
   return { slice: sliceKey, findings: verified.filter(Boolean), failed: false };
 }
 
@@ -1181,7 +1267,9 @@ if (allFindings.length > 1) {
 }
 
 // (a)+(c) Deterministically merge dups, sort by severity, assign TD numbers, format.
-const SEV_ORDER = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3 };
+// EXTREME is the architect's tier for anything that leaves wrong data behind,
+// breaches a tenant boundary, moves money wrongly, or touches safety.
+const SEV_ORDER = { EXTREME: 0, CRITICAL: 1, HIGH: 2, MEDIUM: 3, LOW: 4 };
 const dropped = new Set();
 const merged = [];
 for (const group of mergeGroups) {
@@ -1208,6 +1296,156 @@ for (const f of finalFindings) {
 counts.total = finalFindings.length;
 
 
+const ARCHITECT_SCHEMA = {
+  type: "object",
+  required: ["placements"],
+  additionalProperties: true,
+  properties: {
+    roots: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["key", "name"],
+        additionalProperties: true,
+        properties: {
+          key:       { type: "string", description: "short id, e.g. R1" },
+          // 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", maxLength: 220, description: "ONE sentence: why this root outranks the ones below it in its tier." },
+        },
+      },
+    },
+    placements: {
+      type: "array",
+      minItems: 1,
+      items: {
+        type: "object",
+        required: ["index", "tier"],
+        additionalProperties: true,
+        properties: {
+          index:      { type: "integer", description: "the finding's index in the list given" },
+          tier:       { type: "string", enum: ["EXTREME", "CRITICAL", "HIGH", "MEDIUM", "LOW", "extreme", "critical", "high", "medium", "low"] },
+          rootKey:    { type: "string", description: "the root this belongs to, or omitted if standalone" },
+          rankInRoot: { type: "integer", description: "rank among that root's members, 1 = worst" },
+          alsoRoots:  { type: "array", items: { type: "string" }, description: "other roots that also cause this" },
+          deadCode:   { type: "boolean", description: "true ONLY when confirmed unreachable — say which checks in `note`" },
+          notADefect: { type: "boolean", description: "true when this is not a real defect" },
+          reason:     { type: "string", description: "one line, grounded in consequence" },
+          note:       { type: "string" },
+        },
+      },
+    },
+  },
+};
+
+// ─── Architect — re-tier by consequence, group by root cause, rank ──────────
+//
+// [RULE] architect-ranks-before-numbering
+//
+// Run by hand over the hilo-figma-atos register on 2026-08-11, and it changed
+// the answer enough to become a permanent stage:
+//
+//   · The worst finding in the codebase was filed HIGH. Account credits that
+//     cover a whole invoice are never marked used, so the same credit is given
+//     away again every month, forever. It sat at position 127.
+//   · A typo in one text box silently routes every real card payment to the
+//     practice gateway, where charges report success and no money moves. Filed
+//     MEDIUM.
+//   · Every school's signed legal agreements are downloadable by any other
+//     school. Filed LOW.
+//   · A fabricated thunderstorm advisory for a named airport is shown to pilots
+//     on every page. Filed MEDIUM.
+//   · 22 findings were genuinely unreachable code — carried as risk when they
+//     cannot execute.
+//
+// And the shape of the work changed: 492 findings collapsed into 28 root causes.
+// 144 of the 328 medium/low findings attached to a root that already existed,
+// and only 7 new causes were needed. The codebase does not have 492 problems; it
+// has about 28, most of them repeated dozens of times. Scheduling the findings
+// individually produces dozens of half-fixes of one defect.
+//
+// Two things make this stage worth its cost, and both were measured, not assumed:
+//   1. Severity assigned per-finding is unreliable, because severity is
+//      COMPARATIVE. An agent seeing findings together ranks them; an agent
+//      seeing one finding alone confirms whatever it was handed.
+//   2. TD numbers must be assigned AFTER this, or the register's numbering
+//      encodes the order slices happened to finish.
+async function architectPass(findings) {
+  if (!findings.length) return null;
+
+  // One agent per ~150 findings — the size that held its judgment in the manual
+  // run. More than that and the later findings get thinner treatment; fewer and
+  // the agent loses the comparison that makes ranking possible.
+  const ARCH_BATCH = 150;
+  const chunks = [];
+  for (let i = 0; i < findings.length; i += ARCH_BATCH) chunks.push(findings.slice(i, i + ARCH_BATCH));
+
+  log(`architect: ${findings.length} findings across ${chunks.length} pass(es) — re-tier by consequence, group by root cause, rank`);
+
+  const TIER_RULES = [
+    `TIERS ARE ABOUT CONSEQUENCE, NOT THE KIND OF BUG. The dividing question for every finding: DOES IT LEAVE WRONG DATA BEHIND, OR DOES IT JUST FAIL TO DO ANYTHING?`,
+    `  EXTREME  — breach, data loss, money wrong, or safety. Irreversible or legally reportable. Cross-tenant read OR write, missing database-level access rules, leaked credentials, remote code execution, privilege escalation — AND ALSO anything that CORRUPTS DATA or REPORTS SUCCESS WHILE WRITING NOTHING (money shown as moved but not moved; a record referenced elsewhere that was never created; a kill switch that reports "off" while the thing runs).`,
+    `  CRITICAL — the feature does not work; recoverable once fixed; NO bad data left behind. A page that never loads. An endpoint that fails and shows an empty list.`,
+    `  HIGH     — real, should be fixed, neither of the above.`,
+    `  MEDIUM / LOW — confirm as filed.`,
+    `  DEAD CODE is NOT a risk tier. Genuinely unreachable code cannot cause a problem — mark it dead and it moves to a cleanup list.`,
+    ``,
+    `⚠ AN EMPTY IMPORT LIST DOES NOT PROVE UNREACHABILITY. A page reached by dynamic import shows zero importers in the code graph and is still live and routed — this nearly cost a live credit-card form its EXTREME rating. Before calling anything dead: check the graph, search the name across the source tree, AND search for dynamic loading and the router file. Say which checks you ran.`,
+  ].join("\n");
+
+  const results = await parallel(chunks.map((chunk, ci) => async () => {
+    const listing = chunk.map((f, i) =>
+      `[${i}] severity=${f.severity} area=${ascii(f.area) || "?"} | ${ascii(f.title)} | at ${(f.files && f.files.join(", ")) || "?"} | ${ascii(f.description || "").slice(0, 400)}`
+    ).join("\n");
+
+    const prompt = [
+      `⛔ Work ONLY inside \`${projectDir}\`. Read real code with Read/Grep to settle any question; the code graph answers structural questions (\`gsd-t graph who-imports <file>\`, \`who-calls\`, \`blast-radius\`) and must be preferred over grep for those.`,
+      ``,
+      `You are the ARCHITECT for a completed tech-debt scan. ${chunk.length} findings, already verified against the code by an earlier pass. DO NOT re-verify them all. Your job is judgment about TIER, ROOT CAUSE and ORDER.`,
+      ``,
+      TIER_RULES,
+      ``,
+      `YOUR HIGHEST-VALUE OUTPUT IS FINDING THE MIS-FILED ONES. Severity as assigned is not reliable: in the run that created this stage, the single worst defect in the codebase (account credits re-spent every month, forever) was filed HIGH, and a payment misrouting that makes charges succeed while no money moves was filed MEDIUM. Hunt specifically for money, cross-tenant access, safety, and silent data corruption hiding at a low severity.`,
+      ``,
+      `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. 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.`,
+      SHAPE_RULE,
+    ].join("\n");
+
+    const r = await gatedAgent(prompt, {
+      label: `architect ${ci + 1}/${chunks.length}`, phase: "Architect",
+      schema: ARCHITECT_SCHEMA, model: "opus",
+    });
+    return (r && Array.isArray(r.placements)) ? r : null;
+  }));
+
+  const ok = results.filter(Boolean);
+  if (!ok.length) {
+    // Nothing to rank with. The register is still written, in its filed order —
+    // said out loud, because a register that looks ranked and is not is worse
+    // than one that never claimed to be.
+    log(`⚠ ARCHITECT PRODUCED NOTHING — the register keeps its filed severities and discovery order. It is NOT prioritised; treat its ordering as arbitrary.`);
+    return null;
+  }
+  if (ok.length < chunks.length) {
+    log(`⚠ architect: ${ok.length} of ${chunks.length} passes returned — findings in the missing pass(es) keep their filed severity and sit unranked at the end.`);
+  }
+  return { chunks, results: ok.length === chunks.length ? results : results, partial: ok.length < chunks.length };
+}
+
 // M75 chunked formatter: returns an ARRAY of markdown chunks, each ≤ ~30KB, so each
 // can be written through one bounded agent prompt WITHOUT truncation (a single write
 // of a 466KB register truncates at ~165KB — verified). Chunk 0 is the header+summary
@@ -1244,20 +1482,101 @@ function typeOf(f) {
   return "Other";
 }
 const TYPE_ORDER = ["Security / Vulnerability", "Dead Code", "Duplication", "Data Integrity / Concurrency", "Performance", "Contract Drift", "Testing", "Other"];
-const SEV_ORDER2 = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3 };
-// Stable sort: severity, then type, then original index. Computed ONCE; both consumers use it.
+const SEV_ORDER2 = { EXTREME: 0, CRITICAL: 1, HIGH: 2, MEDIUM: 3, LOW: 4 };
+
+// The architect runs HERE — before anything is numbered. Its output re-tiers the
+// findings and decides their order; TD numbers then follow that order, so TD-1 is
+// the most urgent thing in the codebase rather than whatever a slice finished
+// first. See [RULE] architect-ranks-before-numbering above.
+phase("Architect");
+const architect = await architectPass(finalFindings);
+
+// Apply the architect's tiers and grouping back onto the findings.
+if (architect) {
+  let retiered = 0, deadFound = 0, notDefect = 0;
+  architect.chunks.forEach((chunk, ci) => {
+    const res = architect.results[ci];
+    if (!res) return;                       // that pass returned nothing; its findings keep their filed severity
+    const roots = new Map();
+    for (const r of (res.roots || [])) if (r && r.key) roots.set(r.key, r);
+    for (const p of res.placements) {
+      const f = chunk[p.index];
+      if (!f) continue;                     // an index outside the batch is not a finding to place
+      const tier = String(p.tier || "").toUpperCase();
+      if (tier && tier !== f.severity) { f.severity = tier; retiered++; }
+      if (p.deadCode) { f._deadCode = true; deadFound++; }
+      if (p.notADefect) { f._notADefect = true; notDefect++; }
+      if (p.rootKey) {
+        const root = roots.get(p.rootKey);
+        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;
+      }
+      if (Array.isArray(p.alsoRoots) && p.alsoRoots.length) f._alsoRoots = p.alsoRoots;
+      if (p.reason) f._archReason = p.reason;
+    }
+  });
+  log(`architect: ${retiered} finding(s) re-tiered, ${deadFound} confirmed dead code, ${notDefect} judged not a defect`);
+
+  // Recount — the tiers just changed, so the header's numbers must follow.
+  counts.critical = 0; counts.high = 0; counts.medium = 0; counts.low = 0; counts.extreme = 0;
+  for (const f of finalFindings) {
+    const s = String(f.severity || "").toUpperCase();
+    if (s === "EXTREME") counts.extreme++;
+    else if (s === "CRITICAL") counts.critical++;
+    else if (s === "HIGH") counts.high++;
+    else if (s === "MEDIUM") counts.medium++;
+    else if (s === "LOW") counts.low++;
+  }
+}
+
+// Ordering — the single source of truth for both the register's TD numbering and
+// the consolidation stage's references.
+//
+// With an architect result: tier, then the root's rank within that tier, then the
+// finding's rank within its root — the order a person should work through them.
+// Confirmed dead code sinks below everything: it cannot cause a problem, so it
+// must not sit above things that can.
+//
+// Without one: the old severity-then-type-then-arrival order, which is arbitrary
+// inside a severity and was announced as such by architectPass().
 const orderedFindings = finalFindings
   .map((f, i) => ({ f, i, t: typeOf(f) }))
   .sort((a, b) => {
-    const sv = (SEV_ORDER2[a.f.severity] ?? 9) - (SEV_ORDER2[b.f.severity] ?? 9);
+    const deadA = a.f._deadCode ? 1 : 0, deadB = b.f._deadCode ? 1 : 0;
+    if (deadA !== deadB) return deadA - deadB;
+    const sv = (SEV_ORDER2[String(a.f.severity || "").toUpperCase()] ?? 9)
+             - (SEV_ORDER2[String(b.f.severity || "").toUpperCase()] ?? 9);
     if (sv !== 0) return sv;
-    const tv = TYPE_ORDER.indexOf(a.t) - TYPE_ORDER.indexOf(b.t);
-    if (tv !== 0) return tv;
+    if (architect) {
+      // A standalone finding ranks beside the roots, not after them: it is one
+      // item the architect chose not to group, not a lesser item.
+      const rr = (a.f._rootRank ?? 50) - (b.f._rootRank ?? 50);
+      if (rr !== 0) return rr;
+      const ri = (a.f._rankInRoot ?? 50) - (b.f._rankInRoot ?? 50);
+      if (ri !== 0) return ri;
+    } else {
+      const tv = TYPE_ORDER.indexOf(a.t) - TYPE_ORDER.indexOf(b.t);
+      if (tv !== 0) return tv;
+    }
     return a.i - b.i;
   });
 
+// Every finding must survive the ordering. A sort cannot lose one, but the
+// architect's placement loop can only be trusted if this is checked rather than
+// assumed — a merge in the same family reported full coverage while having
+// dropped two.
+if (orderedFindings.length !== finalFindings.length) {
+  log(`⚠ ORDERING LOST FINDINGS: ${finalFindings.length} in, ${orderedFindings.length} out — the register would under-report. Halting.`);
+  return { status: "failed", reason: "ordering-lost-findings", expected: finalFindings.length, got: orderedFindings.length };
+}
+
 function fmtChunks(today) {
-  const sevHead = { CRITICAL: "🔴 Critical", HIGH: "🟠 High", MEDIUM: "🟡 Medium", LOW: "🟢 Low" };
+  const sevHead = { EXTREME: "🔴 Extreme", CRITICAL: "🟠 Critical", HIGH: "🟡 High", MEDIUM: "🔵 Medium", LOW: "🟢 Low" };
   const head = [];
   head.push(`# Tech Debt Register - ${projectDir.split("/").pop()}`, "");
   if (scanNumber) head.push(`**Scan #${scanNumber}** - Deep codebase scan (runtime-native, ${coverageComplete ? "full coverage" : "PARTIAL coverage"})`);
@@ -1272,10 +1591,17 @@ function fmtChunks(today) {
   head.push(`> Effort estimates use GSD-T-native units (domain / wave / spawn / token-spend). Never human-hours.`);
   head.push(`> TD numbering continues from the prior register (if any, archived). This scan begins at **TD-${tdStart}**.`, "");
   if (!coverageComplete) head.push(`> ⚠️ **PARTIAL COVERAGE - ${failedSlices.length} of ${slices.length} codebase areas were NOT scanned this pass** (failed to return findings): ${ascii(failedSlices.join(", "))}. Findings UNDER-COUNT the real debt. Re-run (resume) for full coverage.`, "");
-  head.push(`## Summary`, "", `| Severity | Count |`, `|----------|-------|`,
-    `| 🔴 CRITICAL | ${counts.critical} |`, `| 🟠 HIGH | ${counts.high} |`,
-    `| 🟡 MEDIUM | ${counts.medium} |`, `| 🟢 LOW | ${counts.low} |`,
+  head.push(`## Summary`, "", `| Severity | Count |`, `|----------|-------|`);
+  // EXTREME only appears when the architect produced it. A row of zero on every
+  // register of a healthy project is noise, and an absent row hides no count.
+  if (counts.extreme) head.push(`| 🔴 EXTREME | ${counts.extreme} |`);
+  head.push(
+    `| 🟠 CRITICAL | ${counts.critical} |`, `| 🟡 HIGH | ${counts.high} |`,
+    `| 🔵 MEDIUM | ${counts.medium} |`, `| 🟢 LOW | ${counts.low} |`,
     `| **Total** | **${counts.total}** |`, "", "---", "");
+  if (counts.extreme) {
+    head.push(`> **EXTREME** means it leaves wrong data behind, crosses a tenant boundary, moves money wrongly, or touches safety. CRITICAL means the feature simply does not work, with nothing bad left behind.`, "");
+  }
 
   function itemMd(f, td) {
     const L = [`### TD-${td} - ${ascii(f.title) || "(untitled)"}`,
@@ -1291,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;
@@ -1557,7 +1900,25 @@ log(`document phase: ${docsOk.length}/${docTargets.length} written/merged${docsF
 // then ASSEMBLE deterministically with severity section headers, and chunk-write.
 phase("Plain-English");
 const peTarget = `${projectDir}/.gsd-t/techdebt_in_plain_english.md`; // internal fixed name (shared copy suffixed in share/)
-const sevLabel = { CRITICAL: "fix before launch", HIGH: "fix soon", MEDIUM: "schedule", LOW: "clean up eventually" };
+// [RULE] severity-label-never-assumes-unlaunched
+//
+// "fix before launch" was wrong on every scan of a system already serving
+// customers — which is most of them. A register handed to the owner of a live
+// product that dates its own advice to before go-live reads as boilerplate, and
+// boilerplate is skipped.
+//
+// One phrase per tier, defined here only. The plain-English companion took its
+// labels from this map and then drifted: the hilo-figma-atos file carried twelve
+// different phrasings for four tiers ("Worth scheduling" / "Worth scheduling
+// soon" / "Should be scheduled soon" / "Can be scheduled at normal priority"),
+// plus casing variants, and only 36 of 61 criticals were labelled at all.
+const sevLabel = {
+  EXTREME:  "immediate priority",
+  CRITICAL: "fix soon",
+  HIGH:     "schedule this cycle",
+  MEDIUM:   "clean up eventually",
+  LOW:      "clean up eventually",
+};
 // Attach the deterministic TD number (matches the register: severity-sorted, tdStart+).
 const peItems = finalFindings.map((f, i) => ({
   td: tdStart + i, severity: f.severity, title: ascii(f.title),
@@ -1577,12 +1938,23 @@ const peResults = await parallel(peBatches.map((batch, bi) => async () => {
     `**What it is.** <1-2 sentences, no jargon; define any unavoidable term in parentheses>`,
     `**Why it matters.** <business/user consequence>`,
     `**Real-world analogy.** <a concrete everyday comparison that genuinely maps to THIS issue>`,
-    `**Severity.** <the plain-urgency phrase given per item>`,
+    `**Severity.** <the item's \`severityPhrase\`, copied EXACTLY, capitalised, ending with a full stop — e.g. "Immediate priority.">`,
+    `Use that phrase VERBATIM. Do not reword it, do not add "soon"/"eventually"/"worth", do not invent a variant. Four phrases exist and no others: "Immediate priority.", "Fix soon.", "Schedule this cycle.", "Clean up eventually." A reader scanning for what to do next is reading the phrase, not the sentence around it, so a rewording makes two identical priorities look different.`,
+    `NEVER write "fix before launch" or any wording implying the system has not launched — most scanned systems are already live and serving customers.`,
     `Keep the td number EXACTLY. ASCII punctuation only (hyphens, straight quotes — NO em-dashes/smart-quotes/ellipsis). No preamble.`,
     ``,
     `Findings (batch ${bi + 1}/${peBatches.length}):`,
     "```json",
-    JSON.stringify(batch.map((it) => ({ ...it, severityPhrase: sevLabel[it.severity] || "review" }))),
+    // A severity with no phrase is a bug in the map, not a finding to label
+    // "review" — the old default quietly turned an unrecognised tier into a word
+    // that says nothing, and read as deliberate. Normalised for case first,
+    // because a finder that types "Critical" must not fall through.
+    JSON.stringify(batch.map((it) => {
+      const tier = String(it.severity || "").toUpperCase();
+      const phrase = sevLabel[tier];
+      if (!phrase) log(`⚠ severity "${it.severity}" has no label in sevLabel — ${it.title || "a finding"} will be labelled by its tier name`);
+      return { ...it, severityPhrase: phrase || tier.toLowerCase() || "unrated" };
+    })),
     "```",
   ].join("\n");
   try {