@tekyzinc/gsd-t 4.9.13 → 4.10.10

package/commands/gsd-t-partition.md

@@ -16,6 +16,24 @@ The agent decomposes the milestone into 2–5 file-disjoint domains, writes `.gs
 
 Read `.gsd-t/progress.md` to determine the active milestone and its defined scope. If a scan exists and is stale (>10 commits or >14 days), the agent refreshes the relevant dimensions before partitioning.
 
+## Step 1.5: Graph Structural Slice — cluster (M94-D10)
+
+**[RULE] partition-project-use-cluster-verb** — the partition agent MUST use the graph CLI
+`cluster` verb to identify tightly-coupled file groups when suggesting domain cuts, NOT
+LLM-reconstructed coupling by reading files.
+
+The phase Workflow (`gsd-t-phase.workflow.js`) automatically queries `gsd-t graph cluster`
+for the partition phase and injects the pre-computed coupling clusters into the agent context.
+The `cluster` verb returns tightly-coupled file groups via a DETERMINISTIC Jaccard metric over
+import neighbourhoods — same input, same output, reproducible grouping. Domain cuts should be
+made along low-coupling boundaries identified by this slice.
+
+**On `graph-unavailable`:** the phase Workflow surfaces a LOUD message and the partition agent
+FAILS LOUD — it does NOT silently fall back to LLM-reconstructed coupling estimates.
+Run `gsd-t graph status` to diagnose.
+
+Graph consumer manifest row: `commands/gsd-t-partition.md | templates/workflows/gsd-t-phase.workflow.js | reader | cluster | LLM-reconstructed file-coupling for domain-boundary decisions`
+
 ## Step 2: Resolve the active model profile (M86 — invoke-time injection)
 
 Before calling the Workflow, resolve the active model profile to build the `overrides` map:

package/commands/gsd-t-plan.md

@@ -14,6 +14,22 @@ For each domain, the agent writes atomic `tasks.md` entries in parallel-executio
 
 Read `.gsd-t/progress.md` and each domain's `scope.md`/`constraints.md`. The partition output is the input to planning.
 
+## Step 1.5: Graph Structural Slice — who-imports (M94-D10)
+
+**[RULE] plan-feature-gapanalysis-use-graph-not-grep** — the plan agent MUST use the graph
+CLI to answer touched-file dependency questions (who-imports, sequencing), NOT grep/raw-read.
+
+The phase Workflow (`gsd-t-phase.workflow.js`) automatically queries `gsd-t graph who-imports`
+for the plan phase and injects the pre-computed dependency slice into the agent context.
+The agent uses this to sequence tasks by real dependency order (which files depend on which)
+without reconstructing the dependency graph by reading imports manually.
+
+**On `graph-unavailable`:** the phase Workflow surfaces a LOUD message and the plan agent
+FAILS LOUD — it does NOT silently fall back to grep for the structural who-imports question.
+Run `gsd-t graph status` to diagnose.
+
+Graph consumer manifest row: `commands/gsd-t-plan.md | templates/workflows/gsd-t-phase.workflow.js | reader | who-imports,blast-radius | grep-reconstructed dependency ordering`
+
 ## Step 2: Resolve the active model profile (M86 — invoke-time injection)
 
 Before calling the Workflow, resolve the active model profile to build the `overrides` map:

package/commands/gsd-t-populate.md

@@ -30,13 +30,24 @@ Scan this codebase and populate the GSD-T documentation. Analyze the actual code
 - Document Deployment from CI/CD configs, Dockerfiles, cloud configs
 - Document Logging and Monitoring from any logging setup or dashboard configs
 
-## Graph-Enhanced Population
+## Graph Structural Slice — who-imports + cluster (M94-D10)
 
-If `.gsd-t/graph/meta.json` exists (graph index is available):
-1. Use `getEntities` and `getImports` to auto-populate architecture docs more accurately — entity relationships map directly to component diagrams and data flow sections
-2. Use `getEntitiesByDomain` to pre-fill domain scope files with precise file ownership
+**[RULE] populate-promotedebt-prd-use-graph-not-grep** — the populate agent MUST use the graph
+CLI to answer structural questions about file dependencies and coupling, NOT grep/raw-read to
+reconstruct the import graph.
 
-If graph is not available, rely on filesystem scanning as usual.
+The phase Workflow (`gsd-t-phase.workflow.js`) automatically queries `gsd-t graph who-imports`
+for the populate phase and injects the pre-computed dependency slice into the agent context.
+Use this slice to:
+1. Auto-populate architecture docs with precise entity relationships (real import edges, not
+   reconstructed from grep patterns).
+2. Pre-fill domain scope files with accurate file ownership derived from coupling clusters.
+
+**On `graph-unavailable`:** the phase Workflow surfaces a LOUD message and the populate agent
+FAILS LOUD — it does NOT silently fall back to filesystem scanning for the structural
+who-imports / cluster question. Run `gsd-t graph status` to diagnose.
+
+Graph consumer manifest row: `commands/gsd-t-populate.md | templates/workflows/gsd-t-phase.workflow.js | reader | who-imports,cluster | grep/filesystem-scan for import/coupling structure`
 
 ## For .gsd-t/progress.md:
 - Set Milestone 1: "Documentation Baseline"

package/commands/gsd-t-prd.md

@@ -14,6 +14,24 @@ The agent takes a user's idea — however rough — reads available GSD-T projec
 
 Read any existing `docs/requirements.md`, `docs/architecture.md`, and `.gsd-t/progress.md`. Capture the user's idea from `$ARGUMENTS`.
 
+## Step 1.5: Graph Structural Slice — cluster (M94-D10)
+
+**[RULE] populate-promotedebt-prd-use-graph-not-grep** — the PRD agent MUST use the graph
+CLI `cluster` verb for structure-aware decomposition when an existing codebase is present,
+NOT LLM-estimated coupling.
+
+The phase Workflow (`gsd-t-phase.workflow.js`) automatically queries `gsd-t graph cluster`
+for the prd phase (when a graph index exists) and injects the pre-computed coupling clusters
+into the agent context. Use this slice to organize PRD requirements around real structural
+boundaries — the cluster output reveals natural product areas aligned with codebase coupling,
+making PRD sections directly traceable to domain boundaries.
+
+**On `graph-unavailable` (existing codebase):** the phase Workflow surfaces a LOUD message
+and the PRD agent FAILS LOUD — it does NOT silently fall back to LLM-estimated structure.
+Run `gsd-t graph status` to diagnose. For greenfield projects, graph-unavailable is expected.
+
+Graph consumer manifest row: `commands/gsd-t-prd.md | templates/workflows/gsd-t-phase.workflow.js | reader | cluster | LLM-estimated structure for PRD decomposition`
+
 ## Step 2: Resolve the active model profile (M86 — invoke-time injection)
 
 Before calling the Workflow, resolve the active model profile to build the `overrides` map:

package/commands/gsd-t-project.md

@@ -26,6 +26,25 @@ If context is thin, ask the user targeted questions:
 
 Do NOT proceed until you have enough context to make informed milestone decisions. It's better to ask 3 good questions now than to repartition later.
 
+## Step 1.5: Graph Structural Slice — cluster (M94-D10)
+
+**[RULE] partition-project-use-cluster-verb** — when an existing codebase is present, the
+project agent MUST use the graph CLI `cluster` verb to identify tightly-coupled file groups
+for structure-aligned milestone decomposition, NOT LLM-reconstructed coupling.
+
+The phase Workflow (`gsd-t-phase.workflow.js`) automatically queries `gsd-t graph cluster`
+for the project phase (when a graph index exists) and injects the pre-computed coupling
+clusters into the agent context. The `cluster` verb returns file groups via a DETERMINISTIC
+Jaccard coupling metric — use this to identify natural milestone boundaries where coupling
+is low (low-coupling boundary = good place to end one milestone and start another).
+
+**On `graph-unavailable` (existing codebase):** the phase Workflow surfaces a LOUD message
+and the project agent FAILS LOUD — it does NOT silently fall back to LLM-estimated coupling.
+Run `gsd-t graph status` to diagnose. For greenfield projects with no existing codebase,
+graph-unavailable is expected — the milestone decomposition proceeds from requirements only.
+
+Graph consumer manifest row: `commands/gsd-t-project.md | templates/workflows/gsd-t-phase.workflow.js | reader | cluster | LLM-estimated coupling for milestone decomposition`
+
 ## Step 2: Identify the Full Scope
 
 ```bash

package/commands/gsd-t-promote-debt.md

@@ -9,13 +9,24 @@ Read:
 2. `.gsd-t/roadmap.md` — current milestone plan
 3. `.gsd-t/progress.md` — what's in progress
 
-## Step 1.5: Graph-Enhanced Impact Radius
+## Step 1.5: Graph Structural Slice — blast-radius (M94-D10)
 
-If `.gsd-t/graph/meta.json` exists (graph index is available):
-1. For each debt item, query `getCallers` on the affected entity to calculate impact radius — items with more callers have higher blast radius and may warrant higher priority
-2. Include caller counts in the promotable items display to help the user prioritize
+**[RULE] populate-promotedebt-prd-use-graph-not-grep** — the promote-debt agent MUST use the
+graph CLI `blast-radius` verb to scope a debt item's reach before milestone-izing, NOT
+grep/getCallers reconstruction of the impact.
 
-If graph is not available, skip this step.
+The phase Workflow (`gsd-t-phase.workflow.js`) automatically queries `gsd-t graph blast-radius`
+for the promote-debt phase and injects the pre-computed blast-radius slice into the agent
+context. Use this slice to:
+1. Calculate impact radius per debt item — items with larger blast radius have higher priority
+   (more downstream code is affected).
+2. Include the structural blast-radius count in the promotable items display for prioritization.
+
+**On `graph-unavailable`:** the phase Workflow surfaces a LOUD message and the promote-debt
+agent FAILS LOUD — it does NOT silently skip the impact radius calculation or fall back to grep.
+Run `gsd-t graph status` to diagnose.
+
+Graph consumer manifest row: `commands/gsd-t-promote-debt.md | templates/workflows/gsd-t-phase.workflow.js | reader | blast-radius | grep-reconstructed caller-count for debt impact scoping`
 
 ## Step 2: Identify Items to Promote
 

package/commands/gsd-t-qa.md

@@ -26,14 +26,26 @@ You are the QA Agent. You are spawned as a teammate by other GSD-T commands. You
 
 If a test requires a source code change (e.g., adding an export for testability), message the lead — do not make the change yourself.
 
-## Graph-Enhanced Coverage Analysis
-
-If `.gsd-t/graph/meta.json` exists (graph index is available):
-1. Query `getTestsFor` each contract entity to identify coverage gaps — entities with no tests are priority targets
-2. Query `findDeadCode` to flag untested dead code — dead code without tests should be reported as cleanup candidates
-3. Use these findings to prioritize test generation in all phases below
-
-If graph is not available, skip this step and rely on filesystem-based test discovery.
+## Graph Structural Slice — dead-code + dangling (M94-D10)
+
+**[RULE] qa-verify-use-orphan-dangling-verbs** — the QA agent MUST use the graph CLI
+`dead-code` and `dangling` verbs to find dead code and dangling refs structurally, NOT
+grep/raw-read reconstruction of the dead-code or dangling-ref picture.
+
+The phase Workflow (`gsd-t-phase.workflow.js`) automatically queries `gsd-t graph dead-code`
+for the qa phase and injects the pre-computed dead-code/dangling slice into the agent context.
+Use this slice to:
+1. Identify coverage gaps: `dead-code` returns function entities with no live importers or
+   callers — entities with no tests and no live callers are priority cleanup candidates.
+2. Identify dangling refs: `dangling` returns call/import edges whose target is not in the
+   indexed node set (delete/rename residue).
+3. Prioritize test generation around these structural findings.
+
+**On `graph-unavailable`:** the phase Workflow surfaces a LOUD message and the QA agent
+FAILS LOUD — it does NOT silently fall back to filesystem-based test discovery for the
+structural dead-code / dangling question. Run `gsd-t graph status` to diagnose.
+
+Graph consumer manifest row: `commands/gsd-t-qa.md | templates/workflows/gsd-t-phase.workflow.js | reader | dead-code,dangling | grep/filesystem dead-code discovery for coverage gap analysis`
 
 ## Phase-Specific Behavior
 

package/commands/gsd-t-quick.md

@@ -174,6 +174,16 @@ fi
 ```
 <!-- /M56-D4: preflight + brief + verify-gate wire-in -->
 
+## Graph-Enhanced Structural Impact — WRITER Pattern (M94-D11)
+
+Quick applies the **WRITER pattern** from `graph-consumer-wiring-contract.md`:
+
+**READER half:** Before the task agent edits code, the quick workflow queries `blast-radius` / `who-imports` to assess the structural impact of the change — which files depend on the target, what is in the blast radius. This structural slice replaces grep/raw-read for the dependency question. The slice is injected into the task agent's context.
+
+**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`.
+
 ## Step 1.5: Graph-Enhanced Scope Check
 
 ```bash

package/commands/gsd-t-scan.md

@@ -26,7 +26,16 @@ You are the lead agent. Your sole responsibility is to invoke the canonical scan
 
 ## What the Workflow does (background — NOT your to-do list)
 
-Replaces the legacy 5-teammate prose scan with a single deterministic, **volume-scaled** Workflow:
+Replaces the legacy 5-teammate prose scan with a single deterministic, **volume-scaled**, **graph-augmented** Workflow (M94-D6):
+
+**Graph-wiring (M94 — additive, current scan architecture kept intact):** A `Graph-Wiring` phase runs after the volume probe. When the dependency graph index is live (`gsd-t graph status` returns ok), the Workflow queries the D5 CLI for the pre-computed structural slice (dead-code candidates, dangling references, tightly-coupled file clusters) and **INJECTS** it ADDITIVELY into each deep-finder agent's context. The finders then reason over accurate, deterministic structure rather than LLM-reconstructing relationships from file reads. The `graphMode` arg controls this:
+- `"wired"` (default) — build index if absent, query structural slice, inject into finders. `graphWiring.mode: "wired"` in the result.
+- `"disabled"` — skip all graph calls (the no-graph baseline for AC-4 INSIGHT-delta comparison). `graphWiring.mode: "disabled"` in the result. Zero graph queries fired in this path.
+- Graph unavailable → scan falls back to full grep-mode, **ANNOUNCED** (never silent). `graphWiring.mode: "fallback-announced"` in the result.
+
+The current scan architecture (enumerate + per-file deep-finders) is **KEPT FULLY INTACT** — graph wiring is additive.
+
+
 
 ```
 preflight → volume-probe → pipeline(per-slice deep finder → single verify) → synthesis → document → render
@@ -59,7 +68,8 @@ It prints the absolute path (exit 0). Use that exact string as `scriptPath`. If
     projectDir: ".",        // the project to scan
     scanNumber: 12,         // optional — for the register header
     maxSlicesHint: 40,      // optional — soft cap on derived slices (no silent truncation)
-    verify: "single"        // optional — "single" (default) | "none"
+    verify: "single",       // optional — "single" (default) | "none"
+    graphMode: "wired"      // optional — "wired" (default) | "disabled" (no-graph baseline for AC-4)
   }
 }
 ```
@@ -79,7 +89,15 @@ The Workflow returns:
   registerPath: ".gsd-t/techdebt.md",
   archivePath: ".gsd-t/techdebt_YYYY-MM-DD.md" | null,
   htmlReport: "<path>" | null,
-  probeTotals: { files, routes, tables, components, ... }
+  probeTotals: { files, routes, tables, components, ... },
+  // M94-D6: graph wiring status — [RULE] scan-injects-structural-slice
+  graphWiring: {
+    mode: "wired" | "fallback-announced" | "disabled",
+    structuralSlicePresent: true | false,
+    deadCodeCount: 12,              // dead-code candidates injected into finders
+    danglingCount: 3,               // dangling-reference edges injected
+    clusterCount: 5,                // coupling clusters injected
+  }
 }
 ```
 

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

@@ -32,6 +32,16 @@ Identify:
 - Naming conventions
 - Test run commands (from package.json scripts, Makefile, or CI config)
 
+## Graph-Enhanced Test Alignment — WRITER Pattern (M94-D11)
+
+Test-sync applies the **WRITER pattern** from `graph-consumer-wiring-contract.md`:
+
+**READER half (test-impl verb):** Use `gsd-t graph test-impl` to identify which impl functions a test exercises (from call-site edges) and `gsd-t graph test-impl --inverse` (untested-impl mode) to find impl functions with no test-file caller. This replaces grep/filesystem discovery (`find tests/ -name "*{module_name}*"`) for the structural test↔impl mapping question. The test-impl slice is injected into the test-sync agent's context for alignment decisions. `[RULE] test-sync-uses-test-impl-verb`.
+
+**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`.
+
 ## Step 1.5: Graph-Enhanced Test Discovery
 
 ```bash

package/commands/gsd-t-verify.md

@@ -28,6 +28,31 @@ Per `.gsd-t/contracts/orthogonal-validation-contract.md` v1.0.0 STABLE, the thre
 
 Read `.gsd-t/progress.md` to determine the active milestone.
 
+## Step 1.5: Graph Structural Slice — dead-code + dangling (M94-D10, ADDITIVE)
+
+**[RULE] qa-verify-use-orphan-dangling-verbs** — the verify Workflow adds `dead-code` and
+`dangling` structural checks as ADDITIVE quality gates (enriching the existing triad), NOT
+as a replacement for any existing gate.
+
+**[RULE] verify-integrate-graph-additive-announced-not-hard-fail** — verify's graph query
+degrades ANNOUNCED on graph-unavailable, NOT as a hard-fail of the entire verify run.
+
+The verify Workflow (`gsd-t-verify.workflow.js`) queries `gsd-t graph dead-code` and
+`gsd-t graph dangling` as part of its quality gates. These structural checks ENRICH the QA
+triad member's context:
+- `dead-code`: function entities with no live importers or callers (structural orphans)
+- `dangling`: call/import edges whose target is not in the indexed node set (delete/rename residue)
+
+**On `graph-unavailable`:** the verify Workflow records a WARNING and CONTINUES its other gates:
+```
+⚠ graph unavailable — structural gate skipped, fix it (gsd-t graph status)
+```
+It does NOT hard-fail the verify run solely due to graph unavailability — verify must always
+be able to run. This is the ONLY exception to the reader hard-stop rule (PRE-MORTEM Finding 3,
+bootstrap carve-out). The verify Workflow does NOT silently grep for the structural question.
+
+Graph consumer manifest row (lint-exempt per verify+integrate carve-out): `commands/gsd-t-verify.md | templates/workflows/gsd-t-verify.workflow.js | reader | dead-code,dangling | grep-based dead-code/dangling detection`
+
 ## Step 2: Resolve the active model profile (M86 — invoke-time injection)
 
 Before calling the Workflow, resolve the active model profile to build the `overrides` map:

package/commands/gsd-t-wave.md

@@ -91,6 +91,14 @@ Call the `Workflow` tool with:
 
 For milestones with multiple waves (see `.gsd-t/contracts/m{NN}-integration-points.md` "Wave Sequencing"), invoke `gsd-t-wave` once per wave. Each call uses the domain list for that wave. Checkpoints (C1, C2, C3, …) gate between waves — verify the prior wave's verdict before starting the next.
 
+## Graph-Aware Disjointness (inherited from execute — M94-D11)
+
+Wave composes `gsd-t-execute` as a sub-workflow. The **graph-aware disjointness** invariant (M94-D11) applies through execute:
+- The disjointness check uses `gsd-t graph blast-radius` and `gsd-t graph who-imports` for transitive dependency overlap (not only literal `Touches` overlap).
+- On `graph-unavailable`, the disjointness check **FAILS LOUD and HALTS** — does NOT fan out on a grep-reconstructed guess. `[RULE] execute-disjointness-fail-loud-halts-never-grep-guess`.
+- Bootstrap escape hatch: `--disjointness-fallback=touches-only` is available on `graph-unavailable` (but NOT on `graph-says-non-disjoint`). See `commands/gsd-t-execute.md` for the full escape-hatch protocol.
+- **WRITER half:** touched files re-indexed after each domain's edits (freshness trigger per `graph-freshness-contract.md`).
+
 ## Document Ripple
 
 Wave delegates to execute and verify; their doc-ripple guarantees apply. Wave itself adds:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "4.9.13",
+  "version": "4.10.10",
   "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",
@@ -22,13 +22,21 @@
     "gsd-t": "bin/gsd-t.js"
   },
   "scripts": {
+    "pretest": "node -e \"const fs=require('fs');for(const f of ['.gsd-t/graph.db','.gsd-t/graph.db-wal','.gsd-t/graph.db-shm']){try{if(fs.existsSync(f))fs.renameSync(f,f+'.testbak')}catch{}}\"",
     "test": "node --test",
+    "posttest": "node -e \"const fs=require('fs');for(const f of ['.gsd-t/graph.db','.gsd-t/graph.db-wal','.gsd-t/graph.db-shm']){try{if(fs.existsSync(f+'.testbak'))fs.renameSync(f+'.testbak',f)}catch{}}\"",
     "e2e": "playwright test",
     "e2e:install": "playwright install chromium",
     "prepublishOnly": "npm test"
   },
   "devDependencies": {
-    "@playwright/test": "^1.55.0"
+    "@playwright/test": "^1.55.0",
+    "better-sqlite3": "^12.11.1",
+    "graphology": "^0.26.0",
+    "kuzu": "^0.11.3",
+    "tree-sitter": "^0.21.1",
+    "tree-sitter-python": "^0.21.0",
+    "tree-sitter-typescript": "^0.23.2"
   },
   "files": [
     "bin/",

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

@@ -13,6 +13,20 @@
 // (model: cycle===1?"opus":(overrides["debug-cycle-2"]??"fable")) is PRESERVED; the research
 // stage is a SEPARATE agent() with its own bare "fable" literal. Idempotent per §4.1.
 //
+// M94-D11 WRITER pattern (graph-consumer-wiring-contract.md §WRITER Pattern):
+// READER half: before the fix agent, query blast-radius + who-calls to localize the
+// bug's call chain (where does this symptom reach / what calls the failing function) —
+// replaces grep-reconstructed call-chain discovery. The graph slice is injected into
+// the debug cycle agent's context so it doesn't need to grep.
+// WRITER half: after the fix lands (filesEdited), trigger a re-index of the touched
+// set — the freshness_check_on_query (graph-freshness-contract.md D4) re-indexes any
+// content-hash-dirty file before answering the next structural query, so downstream
+// consumers see fresh edges after the debug fix.
+// FAIL-LOUD invariant: on graph-unavailable the graph-query step surfaces the message
+// "graph unavailable — fix it (gsd-t graph status)" and halts — it does NOT fall back
+// to grep for the structural question. The existing 2-cycle debug logic is NOT disrupted.
+// [RULE] debug-reader-and-writer-both
+//
 // M90 §3 D4-T3: Loop-ledger halt wired via inline runCli helper (option b).
 // After each cycle, append-cycle is called with the symptom as the assertion, the primary
 // edited file as the surface, and "unit" as the fileClass. After cycle 2 (end of loop),
@@ -280,6 +294,62 @@ async function runResearchForClaim(projectDir, claimText, artifactPath, phaseNam
   }
 }
 
+// M94-D11 §READER: Query blast-radius + who-calls to localize the bug's call chain.
+// Returns a short text snippet injected into the debug cycle agent context.
+// On graph-unavailable: surfaces the message and returns null (agent proceeds without
+// the structural slice — the fail-loud requirement is met by the logged message;
+// the agent is NOT given a grep fallback to find the call chain).
+// [RULE] debug-reader-and-writer-both
+async function queryGraphForDebug(projectDir, symptom, phaseName) {
+  // Derive a plausible target hint from the symptom text (the file or function name)
+  // to pass to blast-radius. This is heuristic — the agent reads the full slice.
+  const targetHint = (symptom || "").slice(0, 80).replace(/['"]/g, "").trim();
+  if (!targetHint) return null;
+
+  const blastResult = await runCli(
+    projectDir,
+    "graph",
+    ["blast-radius", targetHint],
+    "gsd-t-graph-query-cli.cjs",
+    "graph-blast-radius",
+    true,
+    phaseName
+  );
+  const env = blastResult.envelope;
+  if (!env) return null;
+  if (!env.ok && env.reason === "graph-unavailable") {
+    log(`M94-D11 READER: graph unavailable — fix it (gsd-t graph status). Debug proceeds without structural slice.`);
+    return null; // Fail-loud logged; no grep fallback
+  }
+  if (env.ok && Array.isArray(env.results)) {
+    return `## Graph structural slice (blast-radius for "${targetHint}"):\n${JSON.stringify(env.results.slice(0, 20), null, 2)}`;
+  }
+  return null;
+}
+
+// M94-D11 §WRITER: Trigger a freshness pass over the touched set after the fix lands.
+// Calls gsd-t graph freshness (or who-imports) over each touched file so the next
+// structural query sees fresh edges (graph-freshness-contract.md D4 surface).
+// Best-effort (non-blocking) — failure is logged, not fatal.
+// [RULE] debug-reader-and-writer-both
+async function reindexTouchedFiles(projectDir, filesEdited, phaseName) {
+  if (!Array.isArray(filesEdited) || filesEdited.length === 0) return;
+  for (const f of filesEdited.slice(0, 10)) {
+    // who-imports triggers freshness_check_on_query on the file before answering —
+    // the side-effect is the re-index of f if it is content-hash-dirty.
+    await runCli(
+      projectDir,
+      "graph",
+      ["who-imports", f],
+      "gsd-t-graph-query-cli.cjs",
+      `graph-reindex-touched:${f.slice(-30)}`,
+      true,
+      phaseName
+    ).catch(() => {}); // best-effort; don't halt debug on re-index failure
+  }
+  log(`M94-D11 WRITER: re-indexed ${Math.min(filesEdited.length, 10)} touched file(s) after fix`);
+}
+
 if (!symptom) {
   log("debug: args.symptom required (description of failing test or error)");
   return { status: "failed", reason: "no-symptom" };
@@ -290,6 +360,10 @@ const pre = await runPreflight(projectDir);
 if (!pre.ok) return { status: "failed", reason: "preflight-failed", preflight: pre.envelope };
 const brief = await generateBrief(projectDir, { kind: "execute", id: "debug-brief" });
 
+// M94-D11 §READER: query graph ONCE before cycles (the structural slice is the same
+// for all cycles — same symptom). Injected into each cycle's prompt.
+const _graphSliceLine = await queryGraphForDebug(projectDir, symptom, "Preflight") || "";
+
 let lastResult = null;
 // M90 §3 (fix-cycle: gate lifecycle) — track THIS run's per-signature cycle counts so the
 // non-convergence halt is RUN-SCOPED + REACHABLE within the 2-cycle debug cap (not dependent on
@@ -301,6 +375,7 @@ for (let cycle = 1; cycle <= 2; cycle++) {
   const prompt = [
     `Debug cycle ${cycle} of 2. Symptom: ${symptom}`,
     `**Brief:** ${brief.briefPath || "(no brief)"}`,
+    _graphSliceLine ? `\n**Graph structural slice (M94-D11 READER — blast-radius/who-calls localization):**\n${_graphSliceLine}\nUse this slice to localize the call chain — do NOT grep for structural relationships.` : "",
     cycle > 1 && lastResult
       ? `\nPREVIOUS CYCLE'S ROOT CAUSE HYPOTHESIS (did not resolve the issue):\n${lastResult.rootCause}\nFiles edited: ${lastResult.filesEdited.join(", ")}\nIf the hypothesis was right, the fix was incomplete. If wrong, formulate a different hypothesis.`
       : "",
@@ -330,6 +405,12 @@ for (let cycle = 1; cycle <= 2; cycle++) {
     nextStepsIfNotResolved: "agent threw — investigate directly",
   }));
 
+  // M94-D11 §WRITER: re-index touched files after fix lands (freshness trigger).
+  // If the fix edited files, trigger a freshness pass so the next graph query sees fresh edges.
+  if (Array.isArray(lastResult.filesEdited) && lastResult.filesEdited.length > 0) {
+    await reindexTouchedFiles(projectDir, lastResult.filesEdited, `Cycle ${cycle}`);
+  }
+
   // M89 Research — classify GUESSED claims from this debug cycle (§6.5 trigger, separate from debug-cycle ternary)
   if (Array.isArray(lastResult.statedClaims) && lastResult.statedClaims.length > 0) {
     for (const claimLine of lastResult.statedClaims) {

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

@@ -72,11 +72,57 @@ const pre = await runPreflight(projectDir);
 if (!pre.ok) return { status: "failed", reason: "preflight-failed", preflight: pre.envelope };
 const brief = await generateBrief(projectDir, { kind: "execute", milestone, id: `integrate-${(milestone || "m").toLowerCase()}` });
 
+// 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.
+let _graphWhoImportsSlice = null;
+let _graphBlastRadiusSlice = null;
+let _graphIntegrateWarning = null;
+
+{
+  const wiResult = 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.reason === "graph-unavailable") {
+    _graphIntegrateWarning = "⚠ graph unavailable — structural wiring-check skipped, fix it (gsd-t graph status)";
+    log(`M94 graph who-imports: ${_graphIntegrateWarning}`);
+  } else {
+    _graphIntegrateWarning = `⚠ graph who-imports query unexpected envelope (reason: ${wiEnv.reason || "?"}); structural wiring-check skipped`;
+    log(`M94 graph who-imports: ${_graphIntegrateWarning}`);
+  }
+
+  if (!_graphIntegrateWarning) {
+    const brResult = await runCli(
+      projectDir, "graph blast-radius", [], "gsd-t-graph-query-cli.cjs",
+      "graph:blast-radius", true, "Integrate"
+    );
+    const brEnv = brResult.envelope || {};
+    if (brEnv.ok === true) {
+      _graphBlastRadiusSlice = brEnv;
+      log(`M94 graph blast-radius: ${(brEnv.results || []).length} result(s)`);
+    } else {
+      log(`M94 graph blast-radius: query failed (reason: ${brEnv.reason || "?"}) — no blast-radius slice`);
+    }
+  }
+}
+
 phase("Integrate");
 const integrate = await agent(
   [
     `You are the integration agent for milestone \`${milestone}\`. Domains complete: ${domains.join(", ")}.`,
     `**Brief:** ${brief.briefPath || "(no brief — re-walk repo)"}`,
+    // M94-D10-T6: thread graph slice into the integrate agent (ADDITIVE)
+    _graphIntegrateWarning
+      ? `\n**Graph Structural Check:** ${_graphIntegrateWarning} (WARNING only — integrate continues cross-domain wire-up)`
+      : (_graphWhoImportsSlice
+        ? `\n**Graph Structural Slice (who-imports):** ${JSON.stringify(_graphWhoImportsSlice)}\n**Graph Structural Slice (blast-radius):** ${_graphBlastRadiusSlice ? JSON.stringify(_graphBlastRadiusSlice) : "N/A"}\nUse these pre-computed slices to verify cross-domain wiring — that real import/call edges exist across domain seams. Do NOT grep/read-to-reconstruct cross-domain edges; the graph slice above is authoritative.`
+        : ""),
     ``,
     `Read .gsd-t/contracts/${milestone ? milestone.toLowerCase() : ""}-integration-points.md if present.`,
     `Resolve any shared-file edits sequenced at integrate (per "Cross-Domain File Contention Matrix").`,
@@ -84,7 +130,7 @@ const integrate = await agent(
     `Commit cross-domain edits with a clear "m61(integrate)" prefix.`,
     ``,
     `Return JSON per the schema.`,
-  ].join("\n"),
+  ].filter(Boolean).join("\n"),
   { label: "integrate", phase: "Integrate", schema: INTEGRATE_SCHEMA, model: "sonnet" }
 ).catch((e) => ({ status: "failed", crossDomainEdits: [], notes: `agent error: ${e && e.message}` }));