feat: add flow diagram directive to phase researcher agent (#2139) (#2147)

Architecture diagrams generated by gsd-phase-researcher now enforce
data-flow style (conceptual components with arrows) instead of
file-listing style. The directive is language-agnostic and applies
to all project types.

Changes:
- agents/gsd-phase-researcher.md: add System Architecture Diagram
  subsection in Architecture Patterns output template
- get-shit-done/templates/research.md: add matching directive in
  both architecture_patterns template sections
- tests/phase-researcher-flow-diagram.test.cjs: 8 tests validating
  directive presence, content, and ordering in agent and template

Closes #2139

CHANGELOG.md

@@ -9,6 +9,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Added
 
 - **`@gsd-build/sdk` — Phase 1 typed query foundation** — Registry-based `gsd-sdk query` command, classified errors (`GSDQueryError`), and unit-tested handlers under `sdk/src/query/` (state, roadmap, phase lifecycle, init, config, validation, and related domains). Implements incremental SDK-first migration scope approved in #2083; builds on validated work from #2007 / `feat/sdk-foundation` without migrating workflows or removing `gsd-tools.cjs` in this phase.
+- **Flow diagram directive for phase researcher** — `gsd-phase-researcher` now enforces data-flow architecture diagrams instead of file-listing diagrams. Language-agnostic directive added to agent prompt and research template. (#2139)
 
 ## [1.35.0] - 2026-04-10
 

agents/gsd-phase-researcher.md

@@ -312,6 +312,20 @@ Document the verified version and publish date. Training data versions may be mo
 
 ## Architecture Patterns
 
+### System Architecture Diagram
+
+Architecture diagrams MUST show data flow through conceptual components, not file listings.
+
+Requirements:
+- Show entry points (how data/requests enter the system)
+- Show processing stages (what transformations happen, in what order)
+- Show decision points and branching paths
+- Show external dependencies and service boundaries
+- Use arrows to indicate data flow direction
+- A reader should be able to trace the primary use case from input to output by following the arrows
+
+File-to-implementation mapping belongs in the Component Responsibilities table, not in the diagram.
+
 ### Recommended Project Structure
 \`\`\`
 src/

get-shit-done/templates/research.md

@@ -94,6 +94,20 @@ yarn add [packages]
 <architecture_patterns>
 ## Architecture Patterns
 
+### System Architecture Diagram
+
+Architecture diagrams MUST show data flow through conceptual components, not file listings.
+
+Requirements:
+- Show entry points (how data/requests enter the system)
+- Show processing stages (what transformations happen, in what order)
+- Show decision points and branching paths
+- Show external dependencies and service boundaries
+- Use arrows to indicate data flow direction
+- A reader should be able to trace the primary use case from input to output by following the arrows
+
+File-to-implementation mapping belongs in the Component Responsibilities table, not in the diagram.
+
 ### Recommended Project Structure
 ```
 src/
@@ -312,6 +326,20 @@ npm install three @react-three/fiber @react-three/drei @react-three/rapier zusta
 <architecture_patterns>
 ## Architecture Patterns
 
+### System Architecture Diagram
+
+Architecture diagrams MUST show data flow through conceptual components, not file listings.
+
+Requirements:
+- Show entry points (how data/requests enter the system)
+- Show processing stages (what transformations happen, in what order)
+- Show decision points and branching paths
+- Show external dependencies and service boundaries
+- Use arrows to indicate data flow direction
+- A reader should be able to trace the primary use case from input to output by following the arrows
+
+File-to-implementation mapping belongs in the Component Responsibilities table, not in the diagram.
+
 ### Recommended Project Structure
 ```
 src/

tests/phase-researcher-flow-diagram.test.cjs

@@ -0,0 +1,104 @@
+/**
+ * Phase Researcher Flow Diagram Tests (#2139)
+ *
+ * Validates that gsd-phase-researcher enforces data-flow architecture
+ * diagrams instead of file-listing diagrams. Also validates that the
+ * research template includes the matching directive.
+ */
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+
+const AGENTS_DIR = path.join(__dirname, '..', 'agents');
+const TEMPLATES_DIR = path.join(__dirname, '..', 'get-shit-done', 'templates');
+
+// ─── Phase Researcher: System Architecture Diagram Directive ─────────────────
+
+describe('phase-researcher: System Architecture Diagram directive', () => {
+  const researcherPath = path.join(AGENTS_DIR, 'gsd-phase-researcher.md');
+  const content = fs.readFileSync(researcherPath, 'utf-8');
+
+  test('contains System Architecture Diagram section', () => {
+    assert.ok(
+      content.includes('### System Architecture Diagram'),
+      'gsd-phase-researcher.md must contain "### System Architecture Diagram"'
+    );
+  });
+
+  test('requires data flow through conceptual components', () => {
+    assert.ok(
+      content.includes('data flow through conceptual components'),
+      'Directive must require "data flow through conceptual components"'
+    );
+  });
+
+  test('explicitly prohibits file listings in diagrams', () => {
+    assert.ok(
+      content.includes('not file listings'),
+      'Directive must explicitly state "not file listings"'
+    );
+  });
+
+  test('includes key requirements for flow diagrams', () => {
+    const requirements = [
+      'entry points',
+      'processing stages',
+      'decision points',
+      'external dependencies',
+      'arrows',
+    ];
+
+    for (const req of requirements) {
+      assert.ok(
+        content.toLowerCase().includes(req),
+        `Directive must mention "${req}"`
+      );
+    }
+  });
+
+  test('directs file-to-implementation mapping to Component Responsibilities table', () => {
+    assert.ok(
+      content.includes('Component Responsibilities table'),
+      'Directive must redirect file mapping to Component Responsibilities table'
+    );
+  });
+
+  test('diagram section comes before Recommended Project Structure', () => {
+    const diagramPos = content.indexOf('### System Architecture Diagram');
+    const structurePos = content.indexOf('### Recommended Project Structure');
+
+    assert.ok(diagramPos !== -1, 'System Architecture Diagram section must exist');
+    assert.ok(structurePos !== -1, 'Recommended Project Structure section must exist');
+    assert.ok(
+      diagramPos < structurePos,
+      'System Architecture Diagram must come before Recommended Project Structure'
+    );
+  });
+});
+
+// ─── Research Template: System Architecture Diagram Section ───────────────────
+
+describe('research template: System Architecture Diagram section', () => {
+  const templatePath = path.join(TEMPLATES_DIR, 'research.md');
+  const content = fs.readFileSync(templatePath, 'utf-8');
+
+  test('contains System Architecture Diagram section', () => {
+    assert.ok(
+      content.includes('### System Architecture Diagram'),
+      'Research template must contain "### System Architecture Diagram"'
+    );
+  });
+
+  test('includes flow diagram requirements', () => {
+    assert.ok(
+      content.includes('data flow through conceptual components'),
+      'Research template must include flow diagram directive'
+    );
+    assert.ok(
+      content.includes('not file listings'),
+      'Research template must prohibit file listings in diagrams'
+    );
+  });
+});