feat(#1961): add bug-taxonomy classification + strategy routing to gsd-debugger (#2407)

* test(#1961): add failing-first bug-taxonomy routing contract tests Epic #1957 Phase 2B. Source-text-is-the-product contract tests (3 taxonomy classes, explicit class->technique routing table, Bohrbug->repro+SBFL+bisect, Heisenbug->record-replay/stability+SKIP-SBFL, Concurrency->atomicity/order/ deadlock checklist, bug_class in DEBUG Current Focus, supersede-not-append) plus a routing-table specification object pinning the documented decisions (SBFL forbidden on Heisenbug is the load-bearing 1B/2B seam). Failing-first: reference, Phase 1.75, and routing-table reframe do not yet exist. * feat(#1961): add bug-taxonomy classification + strategy routing to gsd-debugger Epic #1957 Phase 2B (reliability-critical). Adds Phase 1.75: classify the failure as Bohrbug / Heisenbug-Mandelbug / Concurrency, then route the investigation technique via an explicit class->technique table (Kernighan: no opaque heuristic). Bohrbug -> reproduction + SBFL (Phase 1.25) + git bisect; Heisenbug/Mandelbug -> record-replay (rr) + stability-stress + statistical sampling, with SBFL explicitly SKIPPED (a flaky spectrum poisons the Ochiai ranking — the load-bearing 1B/2B seam); Concurrency -> the atomicity/order/deadlock checklist first. Reframes (supersedes, not appends — Zawinski) the flat 'Technique Selection by situation' table into a class-routed table; the 11 techniques remain as routed targets. bug_class recorded in Current Focus (DEBUG template); common-bug- patterns catalog cross-referenced to the taxonomy. Full rules extracted to gsd-core/references/debugger-bug-taxonomy.md. INVENTORY + manifest + agent-size baseline + install-parity goldens + AGENTS.md updated. * fix(#1961): address orthogonal review (phase-name drift, General lane, revoke framing, row-scoped tests, bounding) - HIGH: reference said 'Phase 1B' (epic shorthand); corrected to the deployed 'Phase 1.25' (matches the agent + SBFL reference). - HIGH: 6 of 11 techniques (Rubber duck, Delta, Working backwards, Differential, Comment-out, Follow-the-indirection) were orphaned by the situation-table reframe. Added a 'General (any class, situation-cued)' lane to BOTH the reference routing table and the agent's Technique Selection table that re-homes them — supersede-not-append now holds. - MEDIUM: the SBFL-skip is structurally retroactive (Phase 1.25 runs before Phase 1.75 classification), so reframed the table column from 'Do NOT use' to 'Revoke if already run' + an explicit 'retroactive revocation, not proactive skip' note stating the ordering honestly. - MEDIUM: contract tests are now row-scoped (parse the table by class, assert per-row) instead of presence-only; added a guard that the previously- orphaned techniques now have a General-lane route. - LOW: pinned the canonical bug_class value form (lowercase-kebab: bohrbug|heisenbug-mandelbug|concurrency; prose may use title-case). - NIT: added a 'Bound the Heisenbug-chase runs' note (rr/stability/sampling timeouts) per the unbounded-subprocess gauntlet. * chore(#1961): backfill changeset pr number (PR #2407)
2026-07-18 14:42:29 -04:00
parent f8b16d1874
commit 6baa2a8182
46 changed files with 423 additions and 66 deletions
--- a/.changeset/1961-bug-taxonomy-routing.md
+++ b/.changeset/1961-bug-taxonomy-routing.md
@@ -0,0 +1,5 @@
+---
+type: Added
+pr: 2407
+---
+**`gsd-debugger` now classifies each failure by bug class and routes the investigation technique accordingly, replacing the flat 11-technique menu with selection-by-class** — at a new Phase 1.75 the debugger assigns a `bug_class` (Bohrbug / Heisenbug-Mandelbug / Concurrency) and consults an explicit, inspectable routing table: Bohrbugs route to deterministic reproduction + SBFL (Phase 1.25) + git bisect; Heisenbugs/Mandelbugs route to record-replay (`rr`) + stability-stress + statistical sampling and **explicitly skip SBFL** (a flaky spectrum poisons the ranking); Concurrency bugs surface the atomicity/order/deadlock checklist before general techniques. The 11 techniques remain as routed targets, not an undifferentiated list (supersede, not append). `bug_class` + chosen strategy are written to the debug file; the common-bug-patterns catalog is cross-referenced to the taxonomy. Full rules live in `gsd-core/references/debugger-bug-taxonomy.md`. (#1961)
--- a/agents/gsd-debugger.md
+++ b/agents/gsd-debugger.md
@@ -448,18 +448,21 @@ MISMATCH: Checker looks in wrong directory → hooks "not found" → reported as

 **The discipline:** Never assume a constructed path is correct. Resolve it to its actual value and verify the other side agrees. When two systems share a resource (file, directory, key), trace the full path in both.

-## Technique Selection
+## Technique Selection (routed by bug class)

-| Situation | Technique |
-|-----------|-----------|
-| Large codebase, many files | Binary search |
-| Confused about what's happening | Rubber duck, Observability first |
-| Complex system, many interactions | Minimal reproduction |
-| Know the desired output | Working backwards |
-| Used to work, now doesn't | Differential debugging, Git bisect |
-| Many possible causes | Comment out everything, Binary search |
-| Paths, URLs, keys constructed from variables | Follow the indirection |
-| Always | Observability first (before making changes) |
+Classify the failure first (Phase 1.75), then route by class — not by ad-hoc
+situation:
+
+@~/.claude/gsd-core/references/debugger-bug-taxonomy.md
+
+| bug_class | Route to | Revoke if already run |
+|---|---|---|
+| Bohrbug | deterministic reproduction → SBFL (Phase 1.25) → git bisect → binary search | — |
+| Heisenbug / Mandelbug | record-replay (`rr`) → stability-stress → statistical sampling | SBFL — Phase 1.25 runs before classification; if it ran, mark its Evidence entry revoked (flaky spectrum poisons the ranking) |
+| Concurrency | atomicity / order / deadlock checklist (see reference) FIRST | — |
+| General (any class) | Binary search, Working backwards, Differential, Delta debugging, Comment-out-everything, Follow-the-indirection, Rubber duck, Observability first (always, before changes) | — |
+
+The class rows pick the first move; the General lane holds situation-cued techniques that apply to any class. When the situation table and the class route disagree, the class route wins.

 ## Combining Techniques

@@ -1001,6 +1004,13 @@ At investigation decision points, apply structured reasoning:
 - Any matching patterns become hypothesis candidates for Phase 2
 - If no patterns match, proceed to open-ended hypothesis formation

+**Phase 1.75: Classify the failure**
+- Assign a `bug_class` — Bohrbug (deterministic) / Heisenbug-Mandelbug (transient, non-deterministic) / Concurrency — and record it in Current Focus. The class routes which investigation technique to use:
+
+@~/.claude/gsd-core/references/debugger-bug-taxonomy.md
+
+- Bohrbug → reproduction + SBFL + bisect; Heisenbug/Mandelbug → record-replay/stability (skip SBFL — flaky spectra poison it); Concurrency → the atomicity/order/deadlock checklist first
+
 **Phase 2: Form hypothesis**
 - Based on evidence AND common pattern matches, form SPECIFIC, FALSIFIABLE hypothesis
 - **Branch, don't chain** — at hypothesis formation (so it's done before the Phase 4 commit), enumerate candidate causes across ≥2 Ishikawa categories (code / config / environment / data) and answer the AND-gate check; `root_cause` may hold a set when the AND-gate fires:
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -403,6 +403,7 @@ runs its default whole-repo scan.
 - Runs a multi-signal fix-acceptance guardrail (mutation check, no-op/deletion detector, adjacent tests, revert-and-reconfirm) before accepting a fix; degrades gracefully when Stryker or a test suite is absent
 - Ranks suspect code by Ochiai suspiciousness from test pass/fail coverage (spectrum-based fault localization) before forming hypotheses; skips cleanly when no coverage exists
 - Branches root-cause analysis across ≥2 Ishikawa categories and applies an AND-gate check before committing root_cause (guards against 5-Whys single-cause bias); root_cause may hold a set when the AND-gate fires
+- Classifies each failure as Bohrbug / Heisenbug-Mandelbug / Concurrency at Phase 1.75 and routes the investigation technique accordingly (routes Bohrbugs to SBFL+bisect, Heisenbugs to record-replay/stability with SBFL skipped, Concurrency to the atomicity/order/deadlock checklist)
 - Appends to persistent knowledge base on resolution
 - Consults knowledge base on new sessions

--- a/docs/INVENTORY-MANIFEST.json
+++ b/docs/INVENTORY-MANIFEST.json
@@ -214,6 +214,7 @@
      "common-bug-patterns.md",
      "context-budget.md",
      "continuation-format.md",
+      "debugger-bug-taxonomy.md",
      "debugger-fix-acceptance.md",
      "debugger-philosophy.md",
      "debugger-rca-branching.md",
--- a/docs/INVENTORY.md
+++ b/docs/INVENTORY.md
@@ -297,6 +297,7 @@ Full roster at `gsd-core/references/*.md`. References are shared knowledge docum
 | `debugger-fix-acceptance.md` | Multi-signal fix-acceptance guardrail (anti-overfitting) loaded by `gsd-debugger`. |
 | `debugger-sbfl.md` | Spectrum-based fault localization (Ochiai) pre-filter loaded by `gsd-debugger`. |
 | `debugger-rca-branching.md` | RCA branching (fishbone + AND-gate) anti-single-cause discipline loaded by `gsd-debugger`. |
+| `debugger-bug-taxonomy.md` | Bug-taxonomy classification (Bohrbug/Heisenbug/Concurrency) + technique routing table loaded by `gsd-debugger`. |
 | `mandatory-initial-read.md` | Shared required-reading boilerplate injected into agent prompts. |
 | `agent-skills-bootstrap.md` | Shared agent_skills self-load contract (query + Read + dedup guard) injected into all 22 consumer agents. |
 | `project-skills-discovery.md` | Shared project-skills-discovery boilerplate injected into agent prompts. |
--- a/gsd-core/references/common-bug-patterns.md
+++ b/gsd-core/references/common-bug-patterns.md
@@ -97,6 +97,19 @@ Checklist of frequent bug patterns to scan before forming hypotheses. Ordered by
 3. **Each checked pattern is a hypothesis candidate** — verify or eliminate with evidence
 4. **If no pattern matches**, proceed to open-ended investigation

+### Pattern categories → bug taxonomy (Phase 1.75)
+
+The categories here feed bug-class classification (see `debugger-bug-taxonomy.md`):
+
+| Pattern category | Typical bug_class |
+|---|---|
+| Null / Undefined, Off-by-One, State, Import, Type, Regex, Error Handling, Scope | Bohrbug (deterministic) |
+| Async / Timing (intermittent, leaked timer, init order) | Heisenbug / Concurrency |
+| Environment / Config (works-here-not-there) | Heisenbug / Mandelbug (or config-as-root-cause) |
+| Data Shape / API Contract | Bohrbug (or Mandelbug if volume-dependent) |
+
+The taxonomy routes the investigation technique (SBFL + bisect for Bohrbugs; record-replay/stability for Heisenbugs; atomicity/order/deadlock checklist for Concurrency).
+
 ### Symptom-to-Category Quick Map

 | Symptom | Check First |
--- a/gsd-core/references/debugger-bug-taxonomy.md
+++ b/gsd-core/references/debugger-bug-taxonomy.md
@@ -0,0 +1,111 @@
+# Bug-Taxonomy Classification + Strategy Routing
+
+Loaded by `gsd-debugger` via `@-include` from Phase 1.75 (classify the failure)
+and the Technique Selection table. Classifies the failure early and **routes**
+which investigation technique to use, **replacing** (not appending to) the flat
+"pick something from the menu" habit with selection-by-class.
+
+## Why this exists
+
+The 11 investigation techniques are all still here — they are the *routed
+targets*, not an undifferentiated list. But picking the right technique ad hoc
+wastes cycles or actively misleads: a deterministic **Bohrbug** wants
+reproduction + fault localization + bisection; a **Heisenbug/Mandelbug** will
+*disappear or change* under naive repro-and-inspect and wants record-replay or
+stability-stress; a **concurrency** bug wants the atomicity/order/deadlock
+checklist before general techniques. Classification takes one sentence and
+routes the rest.
+
+## The taxonomy (Phase 1.75 — classify before forming hypotheses)
+
+Record `bug_class` in Current Focus (lowercase-kebab value: `bohrbug`,
+`heisenbug-mandelbug`, or `concurrency` — prose may use title-case for
+readability) as one of:
+
+- **Bohrbug** — solid, deterministic, always reproduces under the same inputs
+  (named for the Bohr atom: solid, localized, easy to pin down).
+- **Heisenbug / Mandelbug** — transient, non-deterministic, changes under
+  observation; **Mandelbug** specifically covers aging-related failures
+  (resource exhaustion, uptime-dependent state, slow accumulation) whose cause
+  is tangled with the system rather than purely timing.
+- **Concurrency** — atomicity-violation, order-violation, or deadlock (the Lu et
+  al. 2008 classification) arising from interleaved execution.
+
+If the class is genuinely unclear after one observation, gather one more piece
+of evidence (does it reproduce on immediate retry? does it depend on uptime?)
+rather than forcing a guess — but record the leading candidate as `bug_class`
+and revise it as evidence accumulates.
+
+## The routing table (explicit, inspectable — Kernighan: no opaque heuristic)
+
+| bug_class | Route to | Revoke if already run |
+|---|---|---|
+| **Bohrbug** | deterministic reproduction → **SBFL (Phase 1.25)** → git bisect → binary search | — |
+| **Heisenbug / Mandelbug** | record-replay (`rr`) → stability-stress → statistical sampling; for Mandelbug, look for resource-exhaustion / uptime-dependent patterns | **SBFL** — if Phase 1.25 already ran, **mark its Evidence entry revoked** (flaky spectrum poisons `failed(s)`) |
+| **Concurrency** | the atomicity / order / deadlock checklist (below) FIRST, then general techniques | — |
+| **General (any class — situation-cued)** | Binary search (large codebase), Working backwards (known desired output), Differential debugging (worked-before/works-elsewhere), Delta debugging (large change set), Comment out everything (many possible causes), Follow the indirection (constructed paths/URLs/keys), Rubber duck (confused), Observability first (always, before changes) | — |
+
+The class-routed rows decide which technique to reach for **first**. The
+General lane holds the situational techniques that apply regardless of class —
+they are not orphaned; they are the second move once the class-specific route
+has been exhausted or does not apply.
+
+### The SBFL rule is retroactive revocation, not proactive skip
+
+Note the ordering: Phase 1.25 (SBFL) runs **before** Phase 1.75 (classification),
+so for a Heisenbug the SBFL-skip cannot fire proactively — it fires as
+**retroactive revocation**. When the class later resolves to Heisenbug or
+Mandelbug, mark the prior SBFL Evidence entry as revoked (do not delete — see
+`debugger-sbfl.md`) and note why. A flaky "failing" test makes `failed(s)`
+unreliable, so the Ochiai ranking is noise on a Heisenbug spectrum.
+
+## The concurrency checklist (suspected Concurrency class)
+
+Run this BEFORE general techniques:
+
+1. **Atomicity** — is a read-modify-write non-atomic? (check-then-act without a
+   lock, missing compare-and-swap, a "get then set" across an await/yield)
+2. **Order** — can two operations legally interleave to produce the bad state?
+   (missing happens-before / synchronization; publish-before-init; init order
+   across async boundaries)
+3. **Deadlock** — circular wait on locks/resources? (hold-and-wait, no
+   preemption, mutual blocking on shared resources)
+
+If any branch hits, that becomes the leading hypothesis for Phase 2 (and feeds
+the RCA `candidate_causes` — concurrency bugs typically bridge code +
+environment, per `debugger-rca-branching.md`).
+
+## Relationship to the other disciplines
+
+- **SBFL (Phase 1.25)** is the go-to pre-filter for Bohrbugs; it is explicitly
+  not trusted on Heisenbug/Mandelbug spectra (retroactively revoked — see
+  above).
+- **RCA branching (Phase 2A)** still applies once the route lands you at a
+  hypothesis — concurrency bugs almost always AND-gate (code race +
+  environment/config amplification), so branch across categories.
+
+## Bound the Heisenbug-chase runs (CLAUDE.md gauntlet — unbounded subprocess)
+
+`rr record` on a real application, stability-stress runs, and statistical
+sampling (N repeated executions) can each run minutes-to-hours. Bound them:
+cap `rr record` and each stress/sampling loop (60s for npm-tier, scale with
+suite size; a fixed iteration count for sampling), and **degrade to a logged
+skip on timeout** — never let a Heisenbug chase hang the debug session. If a
+run is cut short, note how far it got in Evidence.
+
+## Supersede, not append (Zawinski's Law)
+
+This **replaces** the flat "Technique Selection by situation" habit with
+"Technique Selection by bug class." The 11 techniques remain available in
+`<investigation_techniques>` as the routed targets: the three class rows route
+the **first** move, and the General lane holds the situation-cued techniques
+that apply to any class. Where a class route and a situation-based hunch
+disagree, the class route wins (a situation table can't tell a Bohrbug from a
+Heisenbug; the class can).
+
+## Scope boundary
+
+Classification + one routing table + the concurrency checklist. Not a new
+subsystem, not a probability model, not an auto-classifier — the agent reads the
+symptoms and assigns the class by judgment, then the table routes. The chosen
+class and strategy are written to the debug file so the decision is inspectable.
--- a/gsd-core/templates/DEBUG.md
+++ b/gsd-core/templates/DEBUG.md
@@ -21,6 +21,7 @@ hypothesis: [current theory being tested]
 test: [how testing it]
 expecting: [what result means if true/false]
 next_action: [immediate next step — be specific, not "continue investigating"]
+bug_class: null  <!-- assigned at Phase 1.75 — bohrbug|heisenbug-mandelbug|concurrency — routes investigation technique (see gsd-core/references/debugger-bug-taxonomy.md) -->
 reasoning_checkpoint: null  <!-- populated before every fix attempt — see structured_returns -->
 tdd_checkpoint: null  <!-- populated when tdd_mode is active after root cause confirmed -->

--- a/tests/agent-size-baseline.json
+++ b/tests/agent-size-baseline.json
@@ -6,7 +6,7 @@
  "gsd-code-reviewer.md": 16870,
  "gsd-codebase-mapper.md": 21485,
  "gsd-debug-session-manager.md": 17012,
-  "gsd-debugger.md": 53893,
+  "gsd-debugger.md": 54886,
  "gsd-doc-classifier.md": 11717,
  "gsd-doc-synthesizer.md": 13154,
  "gsd-doc-verifier.md": 12403,
--- a/tests/debugger-bug-taxonomy.test.cjs
+++ b/tests/debugger-bug-taxonomy.test.cjs
@@ -0,0 +1,178 @@
+// allow-test-rule: source-text-is-the-product (see #1961)
+// Agent .md + reference .md + template .md files — their text IS what the
+// runtime loads. Testing text content tests the deployed bug-taxonomy routing
+// contract. The pure-JS routing-table specification below pins the key
+// routing decisions (Bohrbug->SBFL; Heisenbug->!SBFL; Concurrency->checklist).
+// Per CONTRIBUTING.md exception matrix. Covers epic #1957 Phase 2B (#1961).
+'use strict';
+
+const { describe, test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ROOT = process.cwd();
+const AGENT = path.join(ROOT, 'agents/gsd-debugger.md');
+const REFERENCE = path.join(ROOT, 'gsd-core/references/debugger-bug-taxonomy.md');
+const DEBUG_TEMPLATE = path.join(ROOT, 'gsd-core/templates/DEBUG.md');
+
+// The documented routing table, as a specification. The Tier-1 source-text
+// contract tests below carry the real enforcement that the reference's table
+// matches this; this object pins the key routing decisions a reviewer cares
+// about (the SBFL-on-flaky-skip is the load-bearing one — it's the 1B/2B seam).
+const ROUTING = {
+  bohrbug: {
+    recommended: ['deterministic reproduction', 'SBFL', 'git bisect', 'binary search'],
+    forbidden: [],
+  },
+  heisenbug: {
+    recommended: ['record-replay', 'stability-stress', 'statistical sampling'],
+    forbidden: ['SBFL'], // a flaky spectrum poisons failed(s) — SBFL must be skipped
+  },
+  concurrency: {
+    recommended: ['atomicity', 'order', 'deadlock'],
+    forbidden: [],
+  },
+};
+
+describe('bug-taxonomy classification + strategy routing (#1961, epic #1957 Phase 2B)', () => {
+  describe('reference extract exists and is wired in', () => {
+    test('gsd-core/references/debugger-bug-taxonomy.md exists', () => {
+      assert.ok(fs.existsSync(REFERENCE), 'debugger-bug-taxonomy.md reference must exist');
+    });
+
+    test('gsd-debugger.md @-includes the bug-taxonomy reference', () => {
+      const content = fs.readFileSync(AGENT, 'utf8');
+      assert.ok(
+        content.includes('@~/.claude/gsd-core/references/debugger-bug-taxonomy.md'),
+        'gsd-debugger.md must @-include the bug-taxonomy reference (from Phase 1.75 or the technique-selection table)'
+      );
+    });
+  });
+
+  describe('the taxonomy is documented (criterion: every session records a bug_class)', () => {
+    test('reference defines the three classes', () => {
+      const content = fs.readFileSync(REFERENCE, 'utf8');
+      assert.ok(/bohrbug/i.test(content), 'class: Bohrbug');
+      assert.ok(/heisenbug|mandelbug/i.test(content), 'class: Heisenbug/Mandelbug');
+      assert.ok(/concurrency/i.test(content), 'class: Concurrency');
+    });
+
+    test('DEBUG.md template Current Focus records bug_class', () => {
+      const content = fs.readFileSync(DEBUG_TEMPLATE, 'utf8');
+      assert.ok(/bug_class/.test(content), 'DEBUG.md Current Focus must carry a bug_class field');
+    });
+  });
+
+  describe('routing is an explicit, inspectable table (criterion 4)', () => {
+    // Row-scoped: parse the markdown table and assert per-row, so a substring
+    // appearing in the wrong cell (e.g. SBFL only in the Heisenbug revoke
+    // column) cannot satisfy the Bohrbug route assertion.
+
+    function tableRows() {
+      const content = fs.readFileSync(REFERENCE, 'utf8');
+      const rows = [];
+      for (const line of content.split(/\r?\n/)) {
+        if (/^\|/.test(line) && !/^\|[\s|-]+\|?$/.test(line) && (line.match(/\|/g) || []).length >= 3) {
+          rows.push(line.toLowerCase());
+        }
+      }
+      return rows;
+    }
+
+    function rowFor(cls) {
+      return tableRows().find((r) => r.includes(cls.toLowerCase())) || null;
+    }
+
+    test('there is a markdown table with class + route columns', () => {
+      const content = fs.readFileSync(REFERENCE, 'utf8');
+      assert.ok(/rout/i.test(content), 'the word route/routing must appear');
+      assert.ok(/\|.*\|.*\|/m.test(content), 'there must be a markdown table (inspectable)');
+      assert.ok(tableRows().length >= 3, 'routing table must have at least 3 class rows');
+    });
+
+    test('a Bohrbug row routes to reproduction + SBFL + bisection (criterion 2, row-scoped)', () => {
+      const row = rowFor('bohrbug');
+      assert.ok(row, 'there must be a Bohrbug row in the routing table');
+      assert.ok(/reproduc/.test(row), 'Bohrbug row must include reproduction');
+      assert.ok(/sbfl/.test(row), 'Bohrbug row must include SBFL (Phase 1.25, not the epic shorthand Phase 1B)');
+      assert.ok(/bisect/.test(row), 'Bohrbug row must include git bisect');
+    });
+
+    test('a Heisenbug row routes to record-replay/stability and revokes SBFL (row-scoped, load-bearing 1B/2B seam)', () => {
+      const row = rowFor('heisenbug');
+      assert.ok(row, 'there must be a Heisenbug/Mandelbug row in the routing table');
+      assert.ok(/record-replay|\brr\b|stability/.test(row),
+        'Heisenbug row must include record-replay (rr) and/or stability-stress');
+      assert.ok(/sbfl/.test(row), 'Heisenbug row must reference SBFL (in the revoke column)');
+      assert.ok(/revoke|revocat/.test(row),
+        'Heisenbug row must state SBFL is REVOKED if already run (Phase 1.25 precedes classification)');
+    });
+
+    test('a Concurrency row surfaces the atomicity/order/deadlock checklist (criterion 3, row-scoped)', () => {
+      const row = rowFor('concurrency');
+      assert.ok(row, 'there must be a Concurrency row in the routing table');
+      assert.ok(/atomicity/.test(row), 'Concurrency row must include atomicity');
+      assert.ok(/\border\b/.test(row), 'Concurrency row must include order');
+      assert.ok(/deadlock/.test(row), 'Concurrency row must include deadlock');
+    });
+  });
+
+  describe('supersede, not append — no technique is orphaned (criterion 4)', () => {
+    test('the previously-situational techniques now have a General-lane route', () => {
+      // These 6 were orphaned when the flat situation table was reframed; the
+      // General lane re-homes them. Guards against the "supersede" claim
+      // silently dropping them.
+      const ref = fs.readFileSync(REFERENCE, 'utf8').toLowerCase();
+      const previouslyOrphaned = [
+        'rubber duck', 'delta debugging', 'working backwards',
+        'differential', 'comment out everything', 'follow the indirection',
+      ];
+      for (const t of previouslyOrphaned) {
+        assert.ok(
+          ref.includes(t),
+          `technique "${t}" must appear in the bug-taxonomy reference (General lane) — was orphaned by the reframe`
+        );
+      }
+    });
+
+    test('the reference states the flat menu is superseded by class-routed selection', () => {
+      const content = fs.readFileSync(REFERENCE, 'utf8');
+      assert.ok(/replace|supersede|routed? selection|not.*append/i.test(content),
+        'must state the flat menu is replaced/superseded by class-routed selection (not merely appended)');
+    });
+  });
+
+  describe('routing-table specification (pins the documented decisions)', () => {
+    // Honest framing: this object is a SPEC of the reference's routing table,
+    // not production code. The Tier-1 source-text tests above enforce that the
+    // reference's table actually matches these decisions.
+
+    test('SBFL is recommended for Bohrbug', () => {
+      assert.ok(ROUTING.bohrbug.recommended.includes('SBFL'));
+      assert.ok(!ROUTING.bohrbug.forbidden.includes('SBFL'));
+    });
+
+    test('SBFL is FORBIDDEN for Heisenbug (flaky spectrum — the load-bearing 1B/2B constraint)', () => {
+      assert.ok(ROUTING.heisenbug.forbidden.includes('SBFL'),
+        'SBFL must not be used on a Heisenbug spectrum (poisons failed(s))');
+      assert.ok(!ROUTING.heisenbug.recommended.includes('SBFL'));
+    });
+
+    test('Concurrency route includes all three of atomicity/order/deadlock', () => {
+      for (const c of ['atomicity', 'order', 'deadlock']) {
+        assert.ok(ROUTING.concurrency.recommended.includes(c),
+          `concurrency route must include ${c}`);
+      }
+    });
+
+    test('no class both recommends AND forbids the same technique (internal consistency)', () => {
+      for (const cls of Object.keys(ROUTING)) {
+        for (const tech of ROUTING[cls].recommended) {
+          assert.ok(!ROUTING[cls].forbidden.includes(tech),
+            `${cls} both recommends and forbids ${tech} (contradiction)`);
+        }
+      }
+    });
+  });
+});
--- a/tests/fixtures/golden-install-parity/antigravity.json
+++ b/tests/fixtures/golden-install-parity/antigravity.json
@@ -8,7 +8,7 @@
  "agents/gsd-code-reviewer.md": "a700d295bbf110a9",
  "agents/gsd-codebase-mapper.md": "afdae82284cb21b4",
  "agents/gsd-debug-session-manager.md": "523f28a1ed8a4536",
-  "agents/gsd-debugger.md": "71beaf5bd92bac6e",
+  "agents/gsd-debugger.md": "22974289e08b0b90",
  "agents/gsd-doc-classifier.md": "fca19595590391df",
  "agents/gsd-doc-synthesizer.md": "0e5184bbcf0dca02",
  "agents/gsd-doc-verifier.md": "888c6ac870cb91a6",
@@ -57,9 +57,10 @@
  "gsd-core/references/artifact-types.md": "e176817364a7cbf4",
  "gsd-core/references/autonomous-smart-discuss.md": "efd80aca449032ad",
  "gsd-core/references/checkpoints.md": "509700508de43306",
-  "gsd-core/references/common-bug-patterns.md": "780145be56352626",
+  "gsd-core/references/common-bug-patterns.md": "a4cfea8954dede29",
  "gsd-core/references/context-budget.md": "177520ead2ae3a23",
  "gsd-core/references/continuation-format.md": "580287399ad3ba68",
+  "gsd-core/references/debugger-bug-taxonomy.md": "4c13da220b6a4261",
  "gsd-core/references/debugger-fix-acceptance.md": "87d367e4e864910e",
  "gsd-core/references/debugger-philosophy.md": "459a8ac647c4ce9c",
  "gsd-core/references/debugger-rca-branching.md": "7dcf3ddbe3591250",
@@ -154,7 +155,7 @@
  "gsd-core/references/worktree-branch-check.md": "21d9c31bf6542b93",
  "gsd-core/references/worktree-path-safety.md": "3c8d74756f9b16a8",
  "gsd-core/templates/AI-SPEC.md": "24df5fe5ba34e367",
-  "gsd-core/templates/DEBUG.md": "0df505199f1c248b",
+  "gsd-core/templates/DEBUG.md": "ec7ce6afab6a8a19",
  "gsd-core/templates/README.md": "28160dd8b0631652",
  "gsd-core/templates/SECURITY.md": "b628f7f1c6d2328f",
  "gsd-core/templates/UAT.md": "68d32d1fea14e184",
--- a/tests/fixtures/golden-install-parity/augment.json
+++ b/tests/fixtures/golden-install-parity/augment.json
@@ -8,7 +8,7 @@
  "agents/gsd-code-reviewer.md": "bc8a6f2e1f787ff5",
  "agents/gsd-codebase-mapper.md": "85ea778ad9cf7e66",
  "agents/gsd-debug-session-manager.md": "d2b983f774816e9a",
-  "agents/gsd-debugger.md": "10bc326f43c3ce13",
+  "agents/gsd-debugger.md": "9365383f87462d1b",
  "agents/gsd-doc-classifier.md": "262a94b947a4e2aa",
  "agents/gsd-doc-synthesizer.md": "01f90ea9b0d05d7d",
  "agents/gsd-doc-verifier.md": "b3433e0db51e1c60",
@@ -128,9 +128,10 @@
  "gsd-core/references/artifact-types.md": "a6d2e1f9453ffbf5",
  "gsd-core/references/autonomous-smart-discuss.md": "2fc710cde0ec7785",
  "gsd-core/references/checkpoints.md": "b1530628d693fc85",
-  "gsd-core/references/common-bug-patterns.md": "780145be56352626",
+  "gsd-core/references/common-bug-patterns.md": "a4cfea8954dede29",
  "gsd-core/references/context-budget.md": "f1ce57bf418824af",
  "gsd-core/references/continuation-format.md": "ce73e57d053ab8a7",
+  "gsd-core/references/debugger-bug-taxonomy.md": "78fb8c1711acc971",
  "gsd-core/references/debugger-fix-acceptance.md": "5616622f33e00436",
  "gsd-core/references/debugger-philosophy.md": "16f0cb55eb457f33",
  "gsd-core/references/debugger-rca-branching.md": "7dcf3ddbe3591250",
@@ -225,7 +226,7 @@
  "gsd-core/references/worktree-branch-check.md": "21d9c31bf6542b93",
  "gsd-core/references/worktree-path-safety.md": "3c8d74756f9b16a8",
  "gsd-core/templates/AI-SPEC.md": "efa1f8354bd3a24b",
-  "gsd-core/templates/DEBUG.md": "f85918715fef9743",
+  "gsd-core/templates/DEBUG.md": "bd6a1beccdae67dc",
  "gsd-core/templates/README.md": "93d3426fc64e2c12",
  "gsd-core/templates/SECURITY.md": "b628f7f1c6d2328f",
  "gsd-core/templates/UAT.md": "9e296471b97ebcec",
--- a/tests/fixtures/golden-install-parity/claude-local.json
+++ b/tests/fixtures/golden-install-parity/claude-local.json
@@ -7,7 +7,7 @@
  "agents/gsd-code-reviewer.md": "e2c45baa8c0b5f6d",
  "agents/gsd-codebase-mapper.md": "f96958e5f85b93fb",
  "agents/gsd-debug-session-manager.md": "11afaabc2a749f32",
-  "agents/gsd-debugger.md": "b3910b8cc38d167e",
+  "agents/gsd-debugger.md": "b4cf39ab7e1141d7",
  "agents/gsd-doc-classifier.md": "a76778bdde1c7f72",
  "agents/gsd-doc-synthesizer.md": "8b0b6fc187c9d353",
  "agents/gsd-doc-verifier.md": "4232dcf9076e3566",
@@ -127,9 +127,10 @@
  "gsd-core/references/artifact-types.md": "251040866a3a1818",
  "gsd-core/references/autonomous-smart-discuss.md": "2fc710cde0ec7785",
  "gsd-core/references/checkpoints.md": "b1530628d693fc85",
-  "gsd-core/references/common-bug-patterns.md": "780145be56352626",
+  "gsd-core/references/common-bug-patterns.md": "a4cfea8954dede29",
  "gsd-core/references/context-budget.md": "6bfac08025ea3106",
  "gsd-core/references/continuation-format.md": "580287399ad3ba68",
+  "gsd-core/references/debugger-bug-taxonomy.md": "78fb8c1711acc971",
  "gsd-core/references/debugger-fix-acceptance.md": "5616622f33e00436",
  "gsd-core/references/debugger-philosophy.md": "16f0cb55eb457f33",
  "gsd-core/references/debugger-rca-branching.md": "7dcf3ddbe3591250",
@@ -224,7 +225,7 @@
  "gsd-core/references/worktree-branch-check.md": "21d9c31bf6542b93",
  "gsd-core/references/worktree-path-safety.md": "3c8d74756f9b16a8",
  "gsd-core/templates/AI-SPEC.md": "24df5fe5ba34e367",
-  "gsd-core/templates/DEBUG.md": "ba1d879f05b7ee2e",
+  "gsd-core/templates/DEBUG.md": "0b37c2369be15266",
  "gsd-core/templates/README.md": "90d2617778373147",
  "gsd-core/templates/SECURITY.md": "b628f7f1c6d2328f",
  "gsd-core/templates/UAT.md": "68d32d1fea14e184",
--- a/tests/fixtures/golden-install-parity/claude.json
+++ b/tests/fixtures/golden-install-parity/claude.json
@@ -7,7 +7,7 @@
  "agents/gsd-code-reviewer.md": "d626a828e8de3648",
  "agents/gsd-codebase-mapper.md": "8c2e9f2ce3aedf78",
  "agents/gsd-debug-session-manager.md": "3a6614424653612b",
-  "agents/gsd-debugger.md": "bd5e2b010ca6bb0b",
+  "agents/gsd-debugger.md": "47d32e6f5124b26d",
  "agents/gsd-doc-classifier.md": "a636ae9594b25770",
  "agents/gsd-doc-synthesizer.md": "dfb95eedfb3789bf",
  "agents/gsd-doc-verifier.md": "4232dcf9076e3566",
@@ -56,9 +56,10 @@
  "gsd-core/references/artifact-types.md": "8bd01fd75a2ba70e",
  "gsd-core/references/autonomous-smart-discuss.md": "2fc710cde0ec7785",
  "gsd-core/references/checkpoints.md": "b1530628d693fc85",
-  "gsd-core/references/common-bug-patterns.md": "780145be56352626",
+  "gsd-core/references/common-bug-patterns.md": "a4cfea8954dede29",
  "gsd-core/references/context-budget.md": "533eae480bfc4bb8",
  "gsd-core/references/continuation-format.md": "580287399ad3ba68",
+  "gsd-core/references/debugger-bug-taxonomy.md": "78fb8c1711acc971",
  "gsd-core/references/debugger-fix-acceptance.md": "5616622f33e00436",
  "gsd-core/references/debugger-philosophy.md": "16f0cb55eb457f33",
  "gsd-core/references/debugger-rca-branching.md": "7dcf3ddbe3591250",
@@ -153,7 +154,7 @@
  "gsd-core/references/worktree-branch-check.md": "21d9c31bf6542b93",
  "gsd-core/references/worktree-path-safety.md": "3c8d74756f9b16a8",
  "gsd-core/templates/AI-SPEC.md": "24df5fe5ba34e367",
-  "gsd-core/templates/DEBUG.md": "ba1d879f05b7ee2e",
+  "gsd-core/templates/DEBUG.md": "0b37c2369be15266",
  "gsd-core/templates/README.md": "90d2617778373147",
  "gsd-core/templates/SECURITY.md": "b628f7f1c6d2328f",
  "gsd-core/templates/UAT.md": "68d32d1fea14e184",
--- a/tests/fixtures/golden-install-parity/cline.json
+++ b/tests/fixtures/golden-install-parity/cline.json
@@ -11,7 +11,7 @@
  "agents/gsd-code-reviewer.md": "e5ec12d4d409e800",
  "agents/gsd-codebase-mapper.md": "e5b7941bdda53c91",
  "agents/gsd-debug-session-manager.md": "55788b44fdfc4375",
-  "agents/gsd-debugger.md": "7773cd1a65b723bf",
+  "agents/gsd-debugger.md": "1d86b41ac95b2d5c",
  "agents/gsd-doc-classifier.md": "5011d7358d2b2848",
  "agents/gsd-doc-synthesizer.md": "e59cdd669876582d",
  "agents/gsd-doc-verifier.md": "b60290c9d9f6d8d2",
@@ -60,9 +60,10 @@
  "gsd-core/references/artifact-types.md": "a6d2e1f9453ffbf5",
  "gsd-core/references/autonomous-smart-discuss.md": "2fc710cde0ec7785",
  "gsd-core/references/checkpoints.md": "4919e8aa1130fb04",
-  "gsd-core/references/common-bug-patterns.md": "780145be56352626",
+  "gsd-core/references/common-bug-patterns.md": "a4cfea8954dede29",
  "gsd-core/references/context-budget.md": "c154ba00dbbf4477",
  "gsd-core/references/continuation-format.md": "ce73e57d053ab8a7",
+  "gsd-core/references/debugger-bug-taxonomy.md": "63521aea0206d4ac",
  "gsd-core/references/debugger-fix-acceptance.md": "1057d70f7f2d654a",
  "gsd-core/references/debugger-philosophy.md": "16f0cb55eb457f33",
  "gsd-core/references/debugger-rca-branching.md": "7dcf3ddbe3591250",
@@ -157,7 +158,7 @@
  "gsd-core/references/worktree-branch-check.md": "46882ad61f3f9075",
  "gsd-core/references/worktree-path-safety.md": "8e5b4d542d2d9853",
  "gsd-core/templates/AI-SPEC.md": "efa1f8354bd3a24b",
-  "gsd-core/templates/DEBUG.md": "f85918715fef9743",
+  "gsd-core/templates/DEBUG.md": "bd6a1beccdae67dc",
  "gsd-core/templates/README.md": "004c355d4b02b145",
  "gsd-core/templates/SECURITY.md": "b628f7f1c6d2328f",
  "gsd-core/templates/UAT.md": "9e296471b97ebcec",
--- a/tests/fixtures/golden-install-parity/codebuddy.json
+++ b/tests/fixtures/golden-install-parity/codebuddy.json
@@ -8,7 +8,7 @@
  "agents/gsd-code-reviewer.md": "5342fcc0da974696",
  "agents/gsd-codebase-mapper.md": "b995bf01af0193d2",
  "agents/gsd-debug-session-manager.md": "9f56455afb580275",
-  "agents/gsd-debugger.md": "dd19b31e62f3d052",
+  "agents/gsd-debugger.md": "eda03be2187625f8",
  "agents/gsd-doc-classifier.md": "c2bf59af9467810b",
  "agents/gsd-doc-synthesizer.md": "b2a179bf3c9bd636",
  "agents/gsd-doc-verifier.md": "e74d930905a782ea",
@@ -128,9 +128,10 @@
  "gsd-core/references/artifact-types.md": "a6d2e1f9453ffbf5",
  "gsd-core/references/autonomous-smart-discuss.md": "2fc710cde0ec7785",
  "gsd-core/references/checkpoints.md": "b1530628d693fc85",
-  "gsd-core/references/common-bug-patterns.md": "780145be56352626",
+  "gsd-core/references/common-bug-patterns.md": "a4cfea8954dede29",
  "gsd-core/references/context-budget.md": "f1ce57bf418824af",
  "gsd-core/references/continuation-format.md": "ce73e57d053ab8a7",
+  "gsd-core/references/debugger-bug-taxonomy.md": "78fb8c1711acc971",
  "gsd-core/references/debugger-fix-acceptance.md": "5616622f33e00436",
  "gsd-core/references/debugger-philosophy.md": "16f0cb55eb457f33",
  "gsd-core/references/debugger-rca-branching.md": "7dcf3ddbe3591250",
@@ -225,7 +226,7 @@
  "gsd-core/references/worktree-branch-check.md": "21d9c31bf6542b93",
  "gsd-core/references/worktree-path-safety.md": "3c8d74756f9b16a8",
  "gsd-core/templates/AI-SPEC.md": "efa1f8354bd3a24b",
-  "gsd-core/templates/DEBUG.md": "f85918715fef9743",
+  "gsd-core/templates/DEBUG.md": "bd6a1beccdae67dc",
  "gsd-core/templates/README.md": "93d3426fc64e2c12",
  "gsd-core/templates/SECURITY.md": "b628f7f1c6d2328f",
  "gsd-core/templates/UAT.md": "9e296471b97ebcec",
--- a/tests/fixtures/golden-install-parity/codex.json
+++ b/tests/fixtures/golden-install-parity/codex.json
@@ -86,8 +86,8 @@
  "agents/gsd-codebase-mapper.toml": "a4609f3ac66c2081",
  "agents/gsd-debug-session-manager.md": "c2b615fce5adc13e",
  "agents/gsd-debug-session-manager.toml": "4420cb596ad6b183",
-  "agents/gsd-debugger.md": "75dbb44988dc6c27",
-  "agents/gsd-debugger.toml": "793203a40a0c5a26",
+  "agents/gsd-debugger.md": "84fa297424a131a7",
+  "agents/gsd-debugger.toml": "03cc44fced234655",
  "agents/gsd-doc-classifier.md": "2745bc04d7b93666",
  "agents/gsd-doc-classifier.toml": "3fe5ec83f62b586e",
  "agents/gsd-doc-synthesizer.md": "4f545f2e916458ad",
@@ -163,9 +163,10 @@
  "gsd-core/references/artifact-types.md": "3218cafb0c92dc32",
  "gsd-core/references/autonomous-smart-discuss.md": "4156025334411073",
  "gsd-core/references/checkpoints.md": "afc6933d99f73358",
-  "gsd-core/references/common-bug-patterns.md": "780145be56352626",
+  "gsd-core/references/common-bug-patterns.md": "a4cfea8954dede29",
  "gsd-core/references/context-budget.md": "0b67ea1d5db4bc08",
  "gsd-core/references/continuation-format.md": "e64c0da2b3d0f2f0",
+  "gsd-core/references/debugger-bug-taxonomy.md": "49f94fe75cabba52",
  "gsd-core/references/debugger-fix-acceptance.md": "b2732420bdbcadcd",
  "gsd-core/references/debugger-philosophy.md": "459a8ac647c4ce9c",
  "gsd-core/references/debugger-rca-branching.md": "7dcf3ddbe3591250",
@@ -260,7 +261,7 @@
  "gsd-core/references/worktree-branch-check.md": "21d9c31bf6542b93",
  "gsd-core/references/worktree-path-safety.md": "3c8d74756f9b16a8",
  "gsd-core/templates/AI-SPEC.md": "6411a4789f481c15",
-  "gsd-core/templates/DEBUG.md": "f6d2f4365490e5ad",
+  "gsd-core/templates/DEBUG.md": "145201560e98f861",
  "gsd-core/templates/README.md": "dc13994dabe139a2",
  "gsd-core/templates/SECURITY.md": "b628f7f1c6d2328f",
  "gsd-core/templates/UAT.md": "59a3d4f6c4afbfc9",
--- a/tests/fixtures/golden-install-parity/copilot.json
+++ b/tests/fixtures/golden-install-parity/copilot.json
@@ -8,7 +8,7 @@
  "agents/gsd-code-reviewer.agent.md": "fa1e7c421c78eae1",
  "agents/gsd-codebase-mapper.agent.md": "949bc73f2a7ea44d",
  "agents/gsd-debug-session-manager.agent.md": "77ee029f0f81c09d",
-  "agents/gsd-debugger.agent.md": "e467c0235e5002f9",
+  "agents/gsd-debugger.agent.md": "4b3ec1a39e7179e0",
  "agents/gsd-doc-classifier.agent.md": "aea81c0ba00e06cf",
  "agents/gsd-doc-synthesizer.agent.md": "6ae32e4db005696d",
  "agents/gsd-doc-verifier.agent.md": "0230208ae7ab1a08",
@@ -58,9 +58,10 @@
  "gsd-core/references/artifact-types.md": "f992de8b2b1a4420",
  "gsd-core/references/autonomous-smart-discuss.md": "efd80aca449032ad",
  "gsd-core/references/checkpoints.md": "53ca1c205dda8b65",
-  "gsd-core/references/common-bug-patterns.md": "780145be56352626",
+  "gsd-core/references/common-bug-patterns.md": "a4cfea8954dede29",
  "gsd-core/references/context-budget.md": "435474d5e10be65a",
  "gsd-core/references/continuation-format.md": "580287399ad3ba68",
+  "gsd-core/references/debugger-bug-taxonomy.md": "ddfb2bbc1f3de50a",
  "gsd-core/references/debugger-fix-acceptance.md": "812922e2b5db9410",
  "gsd-core/references/debugger-philosophy.md": "459a8ac647c4ce9c",
  "gsd-core/references/debugger-rca-branching.md": "7dcf3ddbe3591250",
@@ -155,7 +156,7 @@
  "gsd-core/references/worktree-branch-check.md": "21d9c31bf6542b93",
  "gsd-core/references/worktree-path-safety.md": "3c8d74756f9b16a8",
  "gsd-core/templates/AI-SPEC.md": "24df5fe5ba34e367",
-  "gsd-core/templates/DEBUG.md": "0df505199f1c248b",
+  "gsd-core/templates/DEBUG.md": "ec7ce6afab6a8a19",
  "gsd-core/templates/README.md": "da29c64b438065b3",
  "gsd-core/templates/SECURITY.md": "b628f7f1c6d2328f",
  "gsd-core/templates/UAT.md": "68d32d1fea14e184",
--- a/tests/fixtures/golden-install-parity/cursor.json
+++ b/tests/fixtures/golden-install-parity/cursor.json
@@ -8,7 +8,7 @@
  "agents/gsd-code-reviewer.md": "f29d6edbac0a01b6",
  "agents/gsd-codebase-mapper.md": "d49c91fdab4efc70",
  "agents/gsd-debug-session-manager.md": "5e47d7b36e262219",
-  "agents/gsd-debugger.md": "8d3a21e3f8e3f059",
+  "agents/gsd-debugger.md": "5528c9f96fb43c30",
  "agents/gsd-doc-classifier.md": "a6ab02b8f45f9d0b",
  "agents/gsd-doc-synthesizer.md": "fd3c18addbc8265d",
  "agents/gsd-doc-verifier.md": "9934ec11845d41c3",
@@ -128,9 +128,10 @@
  "gsd-core/references/artifact-types.md": "8bd01fd75a2ba70e",
  "gsd-core/references/autonomous-smart-discuss.md": "273b371c5751f35a",
  "gsd-core/references/checkpoints.md": "f852c96c5fe25015",
-  "gsd-core/references/common-bug-patterns.md": "780145be56352626",
+  "gsd-core/references/common-bug-patterns.md": "a4cfea8954dede29",
  "gsd-core/references/context-budget.md": "304dcdab82a27623",
  "gsd-core/references/continuation-format.md": "580287399ad3ba68",
+  "gsd-core/references/debugger-bug-taxonomy.md": "63c03b8afbd21b8a",
  "gsd-core/references/debugger-fix-acceptance.md": "86b7cbde0171fafd",
  "gsd-core/references/debugger-philosophy.md": "16f0cb55eb457f33",
  "gsd-core/references/debugger-rca-branching.md": "7dcf3ddbe3591250",
@@ -225,7 +226,7 @@
  "gsd-core/references/worktree-branch-check.md": "ab004404d028cc0d",
  "gsd-core/references/worktree-path-safety.md": "66de0b35266c807d",
  "gsd-core/templates/AI-SPEC.md": "24df5fe5ba34e367",
-  "gsd-core/templates/DEBUG.md": "ba1d879f05b7ee2e",
+  "gsd-core/templates/DEBUG.md": "0b37c2369be15266",
  "gsd-core/templates/README.md": "83a3d5b593587e83",
  "gsd-core/templates/SECURITY.md": "b628f7f1c6d2328f",
  "gsd-core/templates/UAT.md": "68d32d1fea14e184",
--- a/tests/fixtures/golden-install-parity/hermes.json
+++ b/tests/fixtures/golden-install-parity/hermes.json
@@ -8,7 +8,7 @@
  "agents/gsd-code-reviewer.md": "5ef947ca5baed775",
  "agents/gsd-codebase-mapper.md": "feccaeeacd05e34b",
  "agents/gsd-debug-session-manager.md": "de03d1f43295518f",
-  "agents/gsd-debugger.md": "904b45639181d8cb",
+  "agents/gsd-debugger.md": "7a03521f338d9631",
  "agents/gsd-doc-classifier.md": "29b563a146c9d22c",
  "agents/gsd-doc-synthesizer.md": "652beb928e93fa1d",
  "agents/gsd-doc-verifier.md": "d3d8457bdd44bf10",
@@ -57,9 +57,10 @@
  "gsd-core/references/artifact-types.md": "8bd01fd75a2ba70e",
  "gsd-core/references/autonomous-smart-discuss.md": "2fc710cde0ec7785",
  "gsd-core/references/checkpoints.md": "36b2de4768b228af",
-  "gsd-core/references/common-bug-patterns.md": "780145be56352626",
+  "gsd-core/references/common-bug-patterns.md": "a4cfea8954dede29",
  "gsd-core/references/context-budget.md": "b93e9f47aa1b1753",
  "gsd-core/references/continuation-format.md": "580287399ad3ba68",
+  "gsd-core/references/debugger-bug-taxonomy.md": "fd9b10fffb3bd052",
  "gsd-core/references/debugger-fix-acceptance.md": "b04b913d5ea0ac90",
  "gsd-core/references/debugger-philosophy.md": "16f0cb55eb457f33",
  "gsd-core/references/debugger-rca-branching.md": "7dcf3ddbe3591250",
@@ -154,7 +155,7 @@
  "gsd-core/references/worktree-branch-check.md": "5d79e26e3b51d9ae",
  "gsd-core/references/worktree-path-safety.md": "fa79fcdff2aaa5f0",
  "gsd-core/templates/AI-SPEC.md": "24df5fe5ba34e367",
-  "gsd-core/templates/DEBUG.md": "ba1d879f05b7ee2e",
+  "gsd-core/templates/DEBUG.md": "0b37c2369be15266",
  "gsd-core/templates/README.md": "89560317a9097a05",
  "gsd-core/templates/SECURITY.md": "b628f7f1c6d2328f",
  "gsd-core/templates/UAT.md": "68d32d1fea14e184",
--- a/tests/fixtures/golden-install-parity/kilo.json
+++ b/tests/fixtures/golden-install-parity/kilo.json
@@ -8,7 +8,7 @@
  "agents/gsd-code-reviewer.md": "922c08885bc78662",
  "agents/gsd-codebase-mapper.md": "0ccbf6a685804979",
  "agents/gsd-debug-session-manager.md": "59191275e650f655",
-  "agents/gsd-debugger.md": "a661848ce5505080",
+  "agents/gsd-debugger.md": "2cd00d80a5b6a250",
  "agents/gsd-doc-classifier.md": "6256bbc0b887f60f",
  "agents/gsd-doc-synthesizer.md": "212aaf89a34b51d7",
  "agents/gsd-doc-verifier.md": "8016f792d0766b77",
@@ -128,9 +128,10 @@
  "gsd-core/references/artifact-types.md": "8bd01fd75a2ba70e",
  "gsd-core/references/autonomous-smart-discuss.md": "3986d58011bf9006",
  "gsd-core/references/checkpoints.md": "afc6933d99f73358",
-  "gsd-core/references/common-bug-patterns.md": "780145be56352626",
+  "gsd-core/references/common-bug-patterns.md": "a4cfea8954dede29",
  "gsd-core/references/context-budget.md": "533eae480bfc4bb8",
  "gsd-core/references/continuation-format.md": "580287399ad3ba68",
+  "gsd-core/references/debugger-bug-taxonomy.md": "49f94fe75cabba52",
  "gsd-core/references/debugger-fix-acceptance.md": "b2732420bdbcadcd",
  "gsd-core/references/debugger-philosophy.md": "459a8ac647c4ce9c",
  "gsd-core/references/debugger-rca-branching.md": "7dcf3ddbe3591250",
@@ -225,7 +226,7 @@
  "gsd-core/references/worktree-branch-check.md": "21d9c31bf6542b93",
  "gsd-core/references/worktree-path-safety.md": "3c8d74756f9b16a8",
  "gsd-core/templates/AI-SPEC.md": "24df5fe5ba34e367",
-  "gsd-core/templates/DEBUG.md": "0df505199f1c248b",
+  "gsd-core/templates/DEBUG.md": "ec7ce6afab6a8a19",
  "gsd-core/templates/README.md": "73d3c9689b6efbc9",
  "gsd-core/templates/SECURITY.md": "b628f7f1c6d2328f",
  "gsd-core/templates/UAT.md": "68d32d1fea14e184",
--- a/tests/fixtures/golden-install-parity/kimi.json
+++ b/tests/fixtures/golden-install-parity/kimi.json
@@ -45,7 +45,7 @@
  "agents/subagents/gsd-codebase-mapper.yaml": "bce1c6d15f55c477",
  "agents/subagents/gsd-debug-session-manager.md": "c71b4debebaa978e",
  "agents/subagents/gsd-debug-session-manager.yaml": "aab147717b5082e7",
-  "agents/subagents/gsd-debugger.md": "176aa5bfdde031e5",
+  "agents/subagents/gsd-debugger.md": "e76b525cd307a920",
  "agents/subagents/gsd-debugger.yaml": "6d02d7feb90cad43",
  "agents/subagents/gsd-doc-classifier.md": "632dc6c61bafa63e",
  "agents/subagents/gsd-doc-classifier.yaml": "a4e9cf7025b57503",
@@ -121,9 +121,10 @@
  "gsd-core/references/artifact-types.md": "a6d2e1f9453ffbf5",
  "gsd-core/references/autonomous-smart-discuss.md": "2fc710cde0ec7785",
  "gsd-core/references/checkpoints.md": "b1530628d693fc85",
-  "gsd-core/references/common-bug-patterns.md": "780145be56352626",
+  "gsd-core/references/common-bug-patterns.md": "a4cfea8954dede29",
  "gsd-core/references/context-budget.md": "f1ce57bf418824af",
  "gsd-core/references/continuation-format.md": "ce73e57d053ab8a7",
+  "gsd-core/references/debugger-bug-taxonomy.md": "78fb8c1711acc971",
  "gsd-core/references/debugger-fix-acceptance.md": "5616622f33e00436",
  "gsd-core/references/debugger-philosophy.md": "16f0cb55eb457f33",
  "gsd-core/references/debugger-rca-branching.md": "7dcf3ddbe3591250",
@@ -218,7 +219,7 @@
  "gsd-core/references/worktree-branch-check.md": "21d9c31bf6542b93",
  "gsd-core/references/worktree-path-safety.md": "3c8d74756f9b16a8",
  "gsd-core/templates/AI-SPEC.md": "efa1f8354bd3a24b",
-  "gsd-core/templates/DEBUG.md": "f85918715fef9743",
+  "gsd-core/templates/DEBUG.md": "bd6a1beccdae67dc",
  "gsd-core/templates/README.md": "93d3426fc64e2c12",
  "gsd-core/templates/SECURITY.md": "b628f7f1c6d2328f",
  "gsd-core/templates/UAT.md": "9e296471b97ebcec",
--- a/tests/fixtures/golden-install-parity/opencode.json
+++ b/tests/fixtures/golden-install-parity/opencode.json
@@ -8,7 +8,7 @@
  "agents/gsd-code-reviewer.md": "2249774416314c57",
  "agents/gsd-codebase-mapper.md": "948612acd505e87f",
  "agents/gsd-debug-session-manager.md": "b5a39dcf10210cbb",
-  "agents/gsd-debugger.md": "739bfe544f55f191",
+  "agents/gsd-debugger.md": "6b83960e1839edf7",
  "agents/gsd-doc-classifier.md": "fb776cfbb7e991b0",
  "agents/gsd-doc-synthesizer.md": "2389f388d291c2eb",
  "agents/gsd-doc-verifier.md": "65bbc2ae6b9ace29",
@@ -128,9 +128,10 @@
  "gsd-core/references/artifact-types.md": "218c55caf8aff6df",
  "gsd-core/references/autonomous-smart-discuss.md": "3986d58011bf9006",
  "gsd-core/references/checkpoints.md": "afc6933d99f73358",
-  "gsd-core/references/common-bug-patterns.md": "780145be56352626",
+  "gsd-core/references/common-bug-patterns.md": "a4cfea8954dede29",
  "gsd-core/references/context-budget.md": "355826e667f9ccd1",
  "gsd-core/references/continuation-format.md": "580287399ad3ba68",
+  "gsd-core/references/debugger-bug-taxonomy.md": "49f94fe75cabba52",
  "gsd-core/references/debugger-fix-acceptance.md": "b2732420bdbcadcd",
  "gsd-core/references/debugger-philosophy.md": "459a8ac647c4ce9c",
  "gsd-core/references/debugger-rca-branching.md": "7dcf3ddbe3591250",
@@ -225,7 +226,7 @@
  "gsd-core/references/worktree-branch-check.md": "21d9c31bf6542b93",
  "gsd-core/references/worktree-path-safety.md": "3c8d74756f9b16a8",
  "gsd-core/templates/AI-SPEC.md": "24df5fe5ba34e367",
-  "gsd-core/templates/DEBUG.md": "0df505199f1c248b",
+  "gsd-core/templates/DEBUG.md": "ec7ce6afab6a8a19",
  "gsd-core/templates/README.md": "73d3c9689b6efbc9",
  "gsd-core/templates/SECURITY.md": "b628f7f1c6d2328f",
  "gsd-core/templates/UAT.md": "68d32d1fea14e184",
--- a/tests/fixtures/golden-install-parity/pi.json
+++ b/tests/fixtures/golden-install-parity/pi.json
@@ -24,9 +24,10 @@
  "gsd-core/references/artifact-types.md": "a6d2e1f9453ffbf5",
  "gsd-core/references/autonomous-smart-discuss.md": "2fc710cde0ec7785",
  "gsd-core/references/checkpoints.md": "b1530628d693fc85",
-  "gsd-core/references/common-bug-patterns.md": "780145be56352626",
+  "gsd-core/references/common-bug-patterns.md": "a4cfea8954dede29",
  "gsd-core/references/context-budget.md": "f1ce57bf418824af",
  "gsd-core/references/continuation-format.md": "ce73e57d053ab8a7",
+  "gsd-core/references/debugger-bug-taxonomy.md": "78fb8c1711acc971",
  "gsd-core/references/debugger-fix-acceptance.md": "5616622f33e00436",
  "gsd-core/references/debugger-philosophy.md": "16f0cb55eb457f33",
  "gsd-core/references/debugger-rca-branching.md": "7dcf3ddbe3591250",
@@ -121,7 +122,7 @@
  "gsd-core/references/worktree-branch-check.md": "21d9c31bf6542b93",
  "gsd-core/references/worktree-path-safety.md": "3c8d74756f9b16a8",
  "gsd-core/templates/AI-SPEC.md": "efa1f8354bd3a24b",
-  "gsd-core/templates/DEBUG.md": "f85918715fef9743",
+  "gsd-core/templates/DEBUG.md": "bd6a1beccdae67dc",
  "gsd-core/templates/README.md": "93d3426fc64e2c12",
  "gsd-core/templates/SECURITY.md": "b628f7f1c6d2328f",
  "gsd-core/templates/UAT.md": "9e296471b97ebcec",
--- a/tests/fixtures/golden-install-parity/qwen.json
+++ b/tests/fixtures/golden-install-parity/qwen.json
@@ -8,7 +8,7 @@
  "agents/gsd-code-reviewer.md": "27eeeee6cb600e9b",
  "agents/gsd-codebase-mapper.md": "032ff8ac55466a74",
  "agents/gsd-debug-session-manager.md": "afe383b6483d4097",
-  "agents/gsd-debugger.md": "3500269dc9e4fd88",
+  "agents/gsd-debugger.md": "d1fcceb711b880e2",
  "agents/gsd-doc-classifier.md": "bdf3d54082424e76",
  "agents/gsd-doc-synthesizer.md": "96c383b74a60fbbe",
  "agents/gsd-doc-verifier.md": "da9ab6f3ec27778a",
@@ -57,9 +57,10 @@
  "gsd-core/references/artifact-types.md": "8bd01fd75a2ba70e",
  "gsd-core/references/autonomous-smart-discuss.md": "2fc710cde0ec7785",
  "gsd-core/references/checkpoints.md": "83c7ac100419e9e0",
-  "gsd-core/references/common-bug-patterns.md": "780145be56352626",
+  "gsd-core/references/common-bug-patterns.md": "a4cfea8954dede29",
  "gsd-core/references/context-budget.md": "a1351dd40ef8691f",
  "gsd-core/references/continuation-format.md": "580287399ad3ba68",
+  "gsd-core/references/debugger-bug-taxonomy.md": "47e7929972c06378",
  "gsd-core/references/debugger-fix-acceptance.md": "ab6a1cce253944f4",
  "gsd-core/references/debugger-philosophy.md": "16f0cb55eb457f33",
  "gsd-core/references/debugger-rca-branching.md": "7dcf3ddbe3591250",
@@ -154,7 +155,7 @@
  "gsd-core/references/worktree-branch-check.md": "3fc21ae9462c35c8",
  "gsd-core/references/worktree-path-safety.md": "b4111595eabec186",
  "gsd-core/templates/AI-SPEC.md": "24df5fe5ba34e367",
-  "gsd-core/templates/DEBUG.md": "ba1d879f05b7ee2e",
+  "gsd-core/templates/DEBUG.md": "0b37c2369be15266",
  "gsd-core/templates/README.md": "f4825d4fa594f2b1",
  "gsd-core/templates/SECURITY.md": "b628f7f1c6d2328f",
  "gsd-core/templates/UAT.md": "68d32d1fea14e184",
--- a/tests/fixtures/golden-install-parity/trae.json
+++ b/tests/fixtures/golden-install-parity/trae.json
@@ -8,7 +8,7 @@
  "agents/gsd-code-reviewer.md": "338c46ab59c4e45f",
  "agents/gsd-codebase-mapper.md": "8529d8a1ede8bbfb",
  "agents/gsd-debug-session-manager.md": "ada53877ba56d894",
-  "agents/gsd-debugger.md": "768876bab90cb1e1",
+  "agents/gsd-debugger.md": "90a8ebaea4eb6fc0",
  "agents/gsd-doc-classifier.md": "a6ab02b8f45f9d0b",
  "agents/gsd-doc-synthesizer.md": "fd3c18addbc8265d",
  "agents/gsd-doc-verifier.md": "e51e50892963ccc7",
@@ -57,9 +57,10 @@
  "gsd-core/references/artifact-types.md": "8bd01fd75a2ba70e",
  "gsd-core/references/autonomous-smart-discuss.md": "2fc710cde0ec7785",
  "gsd-core/references/checkpoints.md": "610690dba4d600c1",
-  "gsd-core/references/common-bug-patterns.md": "780145be56352626",
+  "gsd-core/references/common-bug-patterns.md": "a4cfea8954dede29",
  "gsd-core/references/context-budget.md": "b7e9640063775c98",
  "gsd-core/references/continuation-format.md": "580287399ad3ba68",
+  "gsd-core/references/debugger-bug-taxonomy.md": "d0458c690c4487c9",
  "gsd-core/references/debugger-fix-acceptance.md": "134f83886c343733",
  "gsd-core/references/debugger-philosophy.md": "16f0cb55eb457f33",
  "gsd-core/references/debugger-rca-branching.md": "7dcf3ddbe3591250",
@@ -154,7 +155,7 @@
  "gsd-core/references/worktree-branch-check.md": "8de8075d76ff71cd",
  "gsd-core/references/worktree-path-safety.md": "34689482908229bc",
  "gsd-core/templates/AI-SPEC.md": "24df5fe5ba34e367",
-  "gsd-core/templates/DEBUG.md": "ba1d879f05b7ee2e",
+  "gsd-core/templates/DEBUG.md": "0b37c2369be15266",
  "gsd-core/templates/README.md": "332f65072c3f03ae",
  "gsd-core/templates/SECURITY.md": "b628f7f1c6d2328f",
  "gsd-core/templates/UAT.md": "68d32d1fea14e184",
--- a/tests/fixtures/golden-install-parity/windsurf.json
+++ b/tests/fixtures/golden-install-parity/windsurf.json
@@ -8,7 +8,7 @@
  "agents/gsd-code-reviewer.md": "efc0d2dee321c654",
  "agents/gsd-codebase-mapper.md": "cfa2bbfaf264e1fd",
  "agents/gsd-debug-session-manager.md": "b7d57cd8ed9103d3",
-  "agents/gsd-debugger.md": "eff6469d58661c73",
+  "agents/gsd-debugger.md": "7623ba01a22d9280",
  "agents/gsd-doc-classifier.md": "a6ab02b8f45f9d0b",
  "agents/gsd-doc-synthesizer.md": "fd3c18addbc8265d",
  "agents/gsd-doc-verifier.md": "ede2f297b73b5a86",
@@ -57,9 +57,10 @@
  "gsd-core/references/artifact-types.md": "8bd01fd75a2ba70e",
  "gsd-core/references/autonomous-smart-discuss.md": "273b371c5751f35a",
  "gsd-core/references/checkpoints.md": "de9f3b7bd86a44ac",
-  "gsd-core/references/common-bug-patterns.md": "780145be56352626",
+  "gsd-core/references/common-bug-patterns.md": "a4cfea8954dede29",
  "gsd-core/references/context-budget.md": "ff843cd6139c8564",
  "gsd-core/references/continuation-format.md": "580287399ad3ba68",
+  "gsd-core/references/debugger-bug-taxonomy.md": "5d8c0a266a6d61f8",
  "gsd-core/references/debugger-fix-acceptance.md": "ddd00cbd78dd3fdf",
  "gsd-core/references/debugger-philosophy.md": "16f0cb55eb457f33",
  "gsd-core/references/debugger-rca-branching.md": "7dcf3ddbe3591250",
@@ -154,7 +155,7 @@
  "gsd-core/references/worktree-branch-check.md": "f6018dddf15bc1cb",
  "gsd-core/references/worktree-path-safety.md": "0e8a26b9b3424974",
  "gsd-core/templates/AI-SPEC.md": "24df5fe5ba34e367",
-  "gsd-core/templates/DEBUG.md": "ba1d879f05b7ee2e",
+  "gsd-core/templates/DEBUG.md": "0b37c2369be15266",
  "gsd-core/templates/README.md": "ee35799bf08677f3",
  "gsd-core/templates/SECURITY.md": "b628f7f1c6d2328f",
  "gsd-core/templates/UAT.md": "68d32d1fea14e184",
--- a/tests/fixtures/golden-install-parity/zcode.json
+++ b/tests/fixtures/golden-install-parity/zcode.json
@@ -8,7 +8,7 @@
  "agents/gsd-code-reviewer.md": "7d94fe8bfa6661aa",
  "agents/gsd-codebase-mapper.md": "7cc9d387f29c46e1",
  "agents/gsd-debug-session-manager.md": "baf23c3834eb36ba",
-  "agents/gsd-debugger.md": "113f31a0c3c1d075",
+  "agents/gsd-debugger.md": "125315243d5fc50a",
  "agents/gsd-doc-classifier.md": "146acf4d176134b5",
  "agents/gsd-doc-synthesizer.md": "b1f5e2eb28fa3659",
  "agents/gsd-doc-verifier.md": "7ed4d9611f678a95",
@@ -128,9 +128,10 @@
  "gsd-core/references/artifact-types.md": "a6d2e1f9453ffbf5",
  "gsd-core/references/autonomous-smart-discuss.md": "2fc710cde0ec7785",
  "gsd-core/references/checkpoints.md": "b1530628d693fc85",
-  "gsd-core/references/common-bug-patterns.md": "780145be56352626",
+  "gsd-core/references/common-bug-patterns.md": "a4cfea8954dede29",
  "gsd-core/references/context-budget.md": "f1ce57bf418824af",
  "gsd-core/references/continuation-format.md": "ce73e57d053ab8a7",
+  "gsd-core/references/debugger-bug-taxonomy.md": "78fb8c1711acc971",
  "gsd-core/references/debugger-fix-acceptance.md": "5616622f33e00436",
  "gsd-core/references/debugger-philosophy.md": "16f0cb55eb457f33",
  "gsd-core/references/debugger-rca-branching.md": "7dcf3ddbe3591250",
@@ -225,7 +226,7 @@
  "gsd-core/references/worktree-branch-check.md": "21d9c31bf6542b93",
  "gsd-core/references/worktree-path-safety.md": "3c8d74756f9b16a8",
  "gsd-core/templates/AI-SPEC.md": "efa1f8354bd3a24b",
-  "gsd-core/templates/DEBUG.md": "f85918715fef9743",
+  "gsd-core/templates/DEBUG.md": "bd6a1beccdae67dc",
  "gsd-core/templates/README.md": "93d3426fc64e2c12",
  "gsd-core/templates/SECURITY.md": "b628f7f1c6d2328f",
  "gsd-core/templates/UAT.md": "9e296471b97ebcec",
--- a/tests/fixtures/install-tree/antigravity.json
+++ b/tests/fixtures/install-tree/antigravity.json
@@ -60,6 +60,7 @@
  "gsd-core/references/common-bug-patterns.md",
  "gsd-core/references/context-budget.md",
  "gsd-core/references/continuation-format.md",
+  "gsd-core/references/debugger-bug-taxonomy.md",
  "gsd-core/references/debugger-fix-acceptance.md",
  "gsd-core/references/debugger-philosophy.md",
  "gsd-core/references/debugger-rca-branching.md",
--- a/tests/fixtures/install-tree/augment.json
+++ b/tests/fixtures/install-tree/augment.json
@@ -131,6 +131,7 @@
  "gsd-core/references/common-bug-patterns.md",
  "gsd-core/references/context-budget.md",
  "gsd-core/references/continuation-format.md",
+  "gsd-core/references/debugger-bug-taxonomy.md",
  "gsd-core/references/debugger-fix-acceptance.md",
  "gsd-core/references/debugger-philosophy.md",
  "gsd-core/references/debugger-rca-branching.md",
--- a/tests/fixtures/install-tree/claude-local.json
+++ b/tests/fixtures/install-tree/claude-local.json
@@ -130,6 +130,7 @@
  "gsd-core/references/common-bug-patterns.md",
  "gsd-core/references/context-budget.md",
  "gsd-core/references/continuation-format.md",
+  "gsd-core/references/debugger-bug-taxonomy.md",
  "gsd-core/references/debugger-fix-acceptance.md",
  "gsd-core/references/debugger-philosophy.md",
  "gsd-core/references/debugger-rca-branching.md",
--- a/tests/fixtures/install-tree/claude.json
+++ b/tests/fixtures/install-tree/claude.json
@@ -59,6 +59,7 @@
  "gsd-core/references/common-bug-patterns.md",
  "gsd-core/references/context-budget.md",
  "gsd-core/references/continuation-format.md",
+  "gsd-core/references/debugger-bug-taxonomy.md",
  "gsd-core/references/debugger-fix-acceptance.md",
  "gsd-core/references/debugger-philosophy.md",
  "gsd-core/references/debugger-rca-branching.md",
--- a/tests/fixtures/install-tree/cline.json
+++ b/tests/fixtures/install-tree/cline.json
@@ -63,6 +63,7 @@
  "gsd-core/references/common-bug-patterns.md",
  "gsd-core/references/context-budget.md",
  "gsd-core/references/continuation-format.md",
+  "gsd-core/references/debugger-bug-taxonomy.md",
  "gsd-core/references/debugger-fix-acceptance.md",
  "gsd-core/references/debugger-philosophy.md",
  "gsd-core/references/debugger-rca-branching.md",
--- a/tests/fixtures/install-tree/codebuddy.json
+++ b/tests/fixtures/install-tree/codebuddy.json
@@ -131,6 +131,7 @@
  "gsd-core/references/common-bug-patterns.md",
  "gsd-core/references/context-budget.md",
  "gsd-core/references/continuation-format.md",
+  "gsd-core/references/debugger-bug-taxonomy.md",
  "gsd-core/references/debugger-fix-acceptance.md",
  "gsd-core/references/debugger-philosophy.md",
  "gsd-core/references/debugger-rca-branching.md",
--- a/tests/fixtures/install-tree/codex.json
+++ b/tests/fixtures/install-tree/codex.json
@@ -166,6 +166,7 @@
  "gsd-core/references/common-bug-patterns.md",
  "gsd-core/references/context-budget.md",
  "gsd-core/references/continuation-format.md",
+  "gsd-core/references/debugger-bug-taxonomy.md",
  "gsd-core/references/debugger-fix-acceptance.md",
  "gsd-core/references/debugger-philosophy.md",
  "gsd-core/references/debugger-rca-branching.md",
--- a/tests/fixtures/install-tree/copilot.json
+++ b/tests/fixtures/install-tree/copilot.json
@@ -61,6 +61,7 @@
  "gsd-core/references/common-bug-patterns.md",
  "gsd-core/references/context-budget.md",
  "gsd-core/references/continuation-format.md",
+  "gsd-core/references/debugger-bug-taxonomy.md",
  "gsd-core/references/debugger-fix-acceptance.md",
  "gsd-core/references/debugger-philosophy.md",
  "gsd-core/references/debugger-rca-branching.md",
--- a/tests/fixtures/install-tree/cursor.json
+++ b/tests/fixtures/install-tree/cursor.json
@@ -131,6 +131,7 @@
  "gsd-core/references/common-bug-patterns.md",
  "gsd-core/references/context-budget.md",
  "gsd-core/references/continuation-format.md",
+  "gsd-core/references/debugger-bug-taxonomy.md",
  "gsd-core/references/debugger-fix-acceptance.md",
  "gsd-core/references/debugger-philosophy.md",
  "gsd-core/references/debugger-rca-branching.md",
--- a/tests/fixtures/install-tree/hermes.json
+++ b/tests/fixtures/install-tree/hermes.json
@@ -60,6 +60,7 @@
  "gsd-core/references/common-bug-patterns.md",
  "gsd-core/references/context-budget.md",
  "gsd-core/references/continuation-format.md",
+  "gsd-core/references/debugger-bug-taxonomy.md",
  "gsd-core/references/debugger-fix-acceptance.md",
  "gsd-core/references/debugger-philosophy.md",
  "gsd-core/references/debugger-rca-branching.md",
--- a/tests/fixtures/install-tree/kilo.json
+++ b/tests/fixtures/install-tree/kilo.json
@@ -131,6 +131,7 @@
  "gsd-core/references/common-bug-patterns.md",
  "gsd-core/references/context-budget.md",
  "gsd-core/references/continuation-format.md",
+  "gsd-core/references/debugger-bug-taxonomy.md",
  "gsd-core/references/debugger-fix-acceptance.md",
  "gsd-core/references/debugger-philosophy.md",
  "gsd-core/references/debugger-rca-branching.md",
--- a/tests/fixtures/install-tree/kimi.json
+++ b/tests/fixtures/install-tree/kimi.json
@@ -124,6 +124,7 @@
  "gsd-core/references/common-bug-patterns.md",
  "gsd-core/references/context-budget.md",
  "gsd-core/references/continuation-format.md",
+  "gsd-core/references/debugger-bug-taxonomy.md",
  "gsd-core/references/debugger-fix-acceptance.md",
  "gsd-core/references/debugger-philosophy.md",
  "gsd-core/references/debugger-rca-branching.md",
--- a/tests/fixtures/install-tree/opencode.json
+++ b/tests/fixtures/install-tree/opencode.json
@@ -131,6 +131,7 @@
  "gsd-core/references/common-bug-patterns.md",
  "gsd-core/references/context-budget.md",
  "gsd-core/references/continuation-format.md",
+  "gsd-core/references/debugger-bug-taxonomy.md",
  "gsd-core/references/debugger-fix-acceptance.md",
  "gsd-core/references/debugger-philosophy.md",
  "gsd-core/references/debugger-rca-branching.md",
--- a/tests/fixtures/install-tree/pi.json
+++ b/tests/fixtures/install-tree/pi.json
@@ -27,6 +27,7 @@
  "gsd-core/references/common-bug-patterns.md",
  "gsd-core/references/context-budget.md",
  "gsd-core/references/continuation-format.md",
+  "gsd-core/references/debugger-bug-taxonomy.md",
  "gsd-core/references/debugger-fix-acceptance.md",
  "gsd-core/references/debugger-philosophy.md",
  "gsd-core/references/debugger-rca-branching.md",
--- a/tests/fixtures/install-tree/qwen.json
+++ b/tests/fixtures/install-tree/qwen.json
@@ -60,6 +60,7 @@
  "gsd-core/references/common-bug-patterns.md",
  "gsd-core/references/context-budget.md",
  "gsd-core/references/continuation-format.md",
+  "gsd-core/references/debugger-bug-taxonomy.md",
  "gsd-core/references/debugger-fix-acceptance.md",
  "gsd-core/references/debugger-philosophy.md",
  "gsd-core/references/debugger-rca-branching.md",
--- a/tests/fixtures/install-tree/trae.json
+++ b/tests/fixtures/install-tree/trae.json
@@ -60,6 +60,7 @@
  "gsd-core/references/common-bug-patterns.md",
  "gsd-core/references/context-budget.md",
  "gsd-core/references/continuation-format.md",
+  "gsd-core/references/debugger-bug-taxonomy.md",
  "gsd-core/references/debugger-fix-acceptance.md",
  "gsd-core/references/debugger-philosophy.md",
  "gsd-core/references/debugger-rca-branching.md",
--- a/tests/fixtures/install-tree/windsurf.json
+++ b/tests/fixtures/install-tree/windsurf.json
@@ -60,6 +60,7 @@
  "gsd-core/references/common-bug-patterns.md",
  "gsd-core/references/context-budget.md",
  "gsd-core/references/continuation-format.md",
+  "gsd-core/references/debugger-bug-taxonomy.md",
  "gsd-core/references/debugger-fix-acceptance.md",
  "gsd-core/references/debugger-philosophy.md",
  "gsd-core/references/debugger-rca-branching.md",
--- a/tests/fixtures/install-tree/zcode.json
+++ b/tests/fixtures/install-tree/zcode.json
@@ -131,6 +131,7 @@
  "gsd-core/references/common-bug-patterns.md",
  "gsd-core/references/context-budget.md",
  "gsd-core/references/continuation-format.md",
+  "gsd-core/references/debugger-bug-taxonomy.md",
  "gsd-core/references/debugger-fix-acceptance.md",
  "gsd-core/references/debugger-philosophy.md",
  "gsd-core/references/debugger-rca-branching.md",