@tekyzinc/gsd-t 2.33.12 → 2.34.11

package/commands/gsd-t-partition.md

@@ -74,6 +74,78 @@ For each ambiguous item:
 
 ---
 
+## Step 1.6: Consumer Surface Identification (MANDATORY — complete before domain work)
+
+Before decomposing into domains, identify **every surface that will consume this system**. A surface is any client, app, or integration that calls your backend — web app, mobile app, CLI, external API, admin panel, background job, etc.
+
+Skipping this step leads to duplicated backend logic when a second consumer is added later.
+
+---
+
+### 1.6.1 — Enumerate Surfaces
+
+For each surface that will consume this system, capture:
+
+```markdown
+## Consumer Surfaces
+
+| Surface | Type | Operations Needed |
+|---------|------|------------------|
+| {Web App}    | web     | login, list-items, get-item, update-progress, search |
+| {Mobile App} | mobile  | login, list-items, get-item, update-progress, offline-sync |
+| {CLI}        | cli     | import-data, export-data, list-items |
+```
+
+**Surface types**: `web`, `mobile`, `cli`, `external-api`, `admin`, `background-worker`, `other`
+
+If only one surface exists → mark "Single consumer — SharedCore not needed" and proceed to Step 2.
+
+---
+
+### 1.6.2 — Identify Shared Operations
+
+Compare the "Operations Needed" column across all surfaces. Flag every operation that appears in 2 or more surfaces:
+
+```markdown
+## Shared Operations (candidates for SharedCore)
+
+| Operation        | Surfaces That Need It | Shared? |
+|------------------|-----------------------|---------|
+| login            | web, mobile           | ✅  |
+| list-items       | web, mobile, cli      | ✅  |
+| get-item         | web, mobile           | ✅  |
+| update-progress  | web, mobile           | ✅  |
+| offline-sync     | mobile only           | ❌  |
+| export-data      | cli only              | ❌  |
+```
+
+---
+
+### 1.6.3 — Auto-Suggest SharedCore Domain
+
+**If 3 or more shared operations exist:**
+
+> ⚠️ **SharedCore recommended** — {N} operations are needed by {M} consumer surfaces.
+> A `shared-core` domain will be added to own these functions.
+> Surfaces get thin adapter layers that call SharedCore — not duplicate implementations.
+
+Add `shared-core` to the domain list before running Step 2. The `shared-core` domain:
+- Owns: the shared operation implementations
+- Consumed by: all surface-specific adapter domains
+- Contract: `shared-services-contract.md` (use the template from `templates/shared-services-contract.md`)
+
+**If fewer than 3 shared operations exist:**
+
+> ℹ️ {N} shared operations found. Inline sharing is sufficient — no separate SharedCore domain needed. Document shared functions in the relevant domain's constraints.md.
+
+---
+
+### 1.6.4 — Write the Shared Services Contract
+
+If SharedCore was created, populate `.gsd-t/contracts/shared-services-contract.md` using the template from `templates/shared-services-contract.md`.
+
+---
+
 ## Step 2: Identify Domains
 
 Decompose the milestone into 2-5 independent domains. Each domain should:

package/commands/gsd-t-plan.md

@@ -52,6 +52,37 @@ For each domain, write `.gsd-t/domains/{domain-name}/tasks.md`:
 5. **Ordered**: Tasks within a domain are numbered in execution order
 6. **No implicit knowledge**: Don't assume the executing agent remembers previous tasks — reference contracts and files explicitly
 
+### Cross-Domain Duplicate Operation Scan
+
+After creating all domain task lists, scan for operations that appear in more than one domain.
+
+**Check for duplicate task descriptions, function names, or operation verbs** across all `tasks.md` files:
+
+```
+For each operation in each domain's task list:
+  Does this operation appear (by name or clear equivalent) in another domain's task list?
+  → YES → flag as duplicate candidate
+```
+
+**If duplicates found:**
+
+> ⚠️ **Duplicate operations detected** — the following operations appear in multiple domains:
+> - `{operation}` — found in: {domain-A} Task {N}, {domain-B} Task {N}
+> - `{operation}` — found in: {domain-A} Task {N}, {domain-C} Task {N}
+>
+> **Options:**
+> 1. If a `shared-core` domain exists → reassign these tasks to shared-core
+> 2. If no shared-core → extract to a new `shared-core` domain (go back to partition and add it)
+> 3. If the operations are truly surface-specific variants → document the distinction explicitly in each domain's constraints.md to prevent future confusion
+
+**Level 3 (Full Auto)**: If shared-core exists, move the duplicates there automatically. If not, add a task to the first affected domain's list: "Extract `{operation}` to shared-core — coordinate with {domain-B} before implementing".
+
+**If no duplicates found:**
+
+> ✅ No duplicate operations detected across domains.
+
+---
+
 ### REQ Traceability
 
 After creating task lists, append a traceability table to `docs/requirements.md`:

package/commands/gsd-t-scan.md

@@ -47,7 +47,9 @@ ALL TEAMMATES read first:
 - Teammate "security" (model: sonnet): Full security audit — auth, injection, exposure,
   dependencies. Write to .gsd-t/scan/security.md
 - Teammate "quality" (model: sonnet): Dead code, duplication, complexity, test gaps,
-  performance, stale deps. Write to .gsd-t/scan/quality.md
+  performance, stale deps. Also: identify reusability candidates — functions or modules
+  that appear in multiple places doing similar work, and consumer surfaces (web/mobile/CLI/etc.)
+  that call the same backend operations independently. Write to .gsd-t/scan/quality.md
 - Teammate "contracts" (model: haiku): Compare .gsd-t/contracts/ to actual implementation,
   find drift and undocumented interfaces. Write to .gsd-t/scan/contract-drift.md
   (skip if no contracts exist)
@@ -158,6 +160,7 @@ Produce: `.gsd-t/scan/security.md`
 Check for:
 - **Dead code**: Unused functions, unreachable branches, commented-out blocks
 - **Duplication**: Copy-pasted logic that should be abstracted
+- **Reusability / Shared Service Candidates**: Functions implementing the same operation in multiple modules; consumer surfaces (web, mobile, CLI) calling the same backend logic through separate implementations instead of a shared layer
 - **Complexity**: Functions with high cyclomatic complexity, deep nesting
 - **Error handling**: Missing try/catch, swallowed errors, inconsistent patterns
 - **Performance**: N+1 queries, missing indexes, unnecessary re-renders, large bundles
@@ -177,6 +180,27 @@ Produce: `.gsd-t/scan/quality.md`
 ## Duplication
 - {file-a} ↔ {file-b}: {description of duplicated logic}
 
+## Reusability Analysis
+
+### Consumer Surfaces Detected
+| Surface | Type | Operations Used |
+|---------|------|----------------|
+| {module/app} | {web/mobile/cli/other} | {list of backend operations it calls} |
+
+### Shared Service Candidates
+Operations implemented independently in 2+ places — candidates for extraction to a shared module:
+
+| Operation | Found In | Recommendation |
+|-----------|----------|----------------|
+| {operation} | {file-a}, {file-b} | Extract to shared-core |
+| {operation} | {file-a}, {file-b}, {file-c} | Extract to shared-core (high priority — 3 copies) |
+
+If none found: `✅ No shared service candidates detected.`
+
+> **Note**: These candidates should seed Step 1.6 (Consumer Surface Identification) the next
+> time `/user:gsd-t-partition` is run. Copy the "Consumer Surfaces Detected" table into
+> partition's Step 1.6.1 to skip re-research.
+
 ## Complexity Hotspots
 - {file}:{function} — complexity: {score/assessment} — {suggestion}
 
@@ -220,6 +244,21 @@ Produce: `.gsd-t/scan/contract-drift.md`
 - {endpoint/table/component}: {description}
 ```
 
+## Step 2.5: Schema Extraction
+
+Run schema extraction on the scanned project to detect ORM/database schema files and parse entity definitions. This data feeds the database schema diagram in Step 3.5.
+
+Using Bash tool:
+```
+node -e "const {extractSchema}=require('./bin/scan-schema.js'); const r=extractSchema(process.argv[1]); process.stdout.write(JSON.stringify(r))" "$SCANNED_PROJECT_ROOT"
+```
+
+Capture output as `schemaData`. Log:
+- Detected ORM type: `schemaData.ormType`
+- Entity count: `schemaData.entities.length`
+
+If `schemaData.detected === false`, note: "No ORM/schema files detected — database diagram will use placeholder."
+
 ## Step 3: Build Tech Debt Register
 
 Synthesize ALL findings into `.gsd-t/techdebt.md`:
@@ -302,6 +341,25 @@ Nice-to-haves and cleanup.
 - Last scan: {previous date or "first scan"}
 ```
 
+## Step 3.5: Diagram Generation
+
+Generate all 6 architectural diagrams using analysis data from Step 2 and schema data from Step 2.5.
+
+Using Bash tool:
+```
+node -e "
+const {generateDiagrams}=require('./bin/scan-diagrams.js');
+const analysisData=JSON.parse(process.argv[1]);
+const schemaData=JSON.parse(process.argv[2]);
+const r=generateDiagrams(analysisData, schemaData, {projectRoot: process.argv[3]});
+process.stdout.write(JSON.stringify(r.map(d=>({type:d.type,rendered:d.rendered,rendererUsed:d.rendererUsed}))));
+" "$ANALYSIS_JSON" "$SCHEMA_JSON" "$SCANNED_PROJECT_ROOT"
+```
+
+Capture the full array as `diagrams`. Log:
+- Diagrams rendered: count of `diagrams.filter(d => d.rendered).length` out of 6
+- Renderer used per diagram: `diagrams.map(d => d.type + ': ' + d.rendererUsed).join(', ')`
+
 ## Step 4: Suggest Milestone Promotions
 
 Review all items marked `Milestone candidate: YES` and group them into logical milestones:
@@ -323,6 +381,12 @@ Can be scheduled: AFTER current feature work
 Combines: TD-020, dependency table items with breaking=yes
 Estimated effort: {assessment}
 Can be scheduled: During next maintenance window
+
+### Suggested: Shared Service Extraction (if candidates found)
+Combines: all "Shared Service Candidates" from quality.md Reusability Analysis
+Estimated effort: {assessment}
+Should be prioritized: BEFORE adding new consumer surfaces to the system
+Note: Use `/user:gsd-t-partition` Step 1.6 to design the SharedCore domain
 ```
 
 ## Step 5: Update Living Documents
@@ -419,6 +483,29 @@ All detailed findings are in `.gsd-t/scan/` for review.
 
 Ask: "Want to promote any tech debt items to milestones? Or address the critical items first?"
 
+### HTML Report Generation
+
+After writing the text report to `.gsd-t/techdebt.md`, generate the self-contained HTML scan report:
+
+Using Bash tool:
+```
+node -e "
+const {collectScanData}=require('./bin/scan-data-collector.js');
+const {extractSchema}=require('./bin/scan-schema.js');
+const {generateDiagrams}=require('./bin/scan-diagrams.js');
+const {generateReport}=require('./bin/scan-report.js');
+const root=process.argv[1];
+const analysisData=collectScanData(root);
+const schemaData=extractSchema(root);
+const diagrams=generateDiagrams(analysisData, schemaData, {projectRoot:root});
+const r=generateReport(analysisData, schemaData, diagrams, {projectRoot:root});
+if (r.outputPath) console.log('HTML report:', r.outputPath, '| Diagrams rendered:', r.diagramsRendered + '/6');
+else console.error('Report generation failed:', r.error);
+" "$SCANNED_PROJECT_ROOT"
+```
+
+Report the HTML output path and diagram render count to the user.
+
 ## Document Ripple
 
 Scan produces analysis files and updates living documents (Step 5 already covers most updates). Verify:

package/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture — GSD-T Framework (@tekyzinc/gsd-t)
 
-## Last Updated: 2026-03-04 (M14 Complete — Execution Intelligence Layer)
+## Last Updated: 2026-03-09 (Scan #9, Post-M17)
 
 ## System Overview
 
@@ -23,7 +23,7 @@ The framework has no runtime — it is consumed entirely by Claude Code's slash
 ### Slash Commands (commands/*.md)
 - **Purpose**: Define the GSD-T methodology as executable workflows for Claude Code
 - **Location**: `commands/`
-- **Count**: 47 (43 GSD-T workflow + 4 utility: gsd, branch, checkin, Claude-md) — includes gsd-t-health and gsd-t-pause (M13), gsd-t-reflect (M14)
+- **Count**: 48 (44 GSD-T workflow + 4 utility: gsd, branch, checkin, Claude-md) — includes gsd-t-health, gsd-t-pause (M13), gsd-t-reflect (M14), gsd-t-visualize (M15), gsd-t-prd (M16)
 - **Format**: Pure markdown with step-numbered instructions, team mode blocks, document ripple sections, and $ARGUMENTS terminator
 
 ### Templates (templates/*.md)
@@ -47,6 +47,20 @@ The framework has no runtime — it is consumed entirely by Claude Code's slash
 - **Distillation step (complete-milestone Step 2.5)**: Scans `.gsd-t/events/*.jsonl` for patterns seen ≥3 times, proposes CLAUDE.md / constraints.md rule additions, user confirms before write.
 - **`commands/gsd-t-reflect.md`**: On-demand retrospective command (47th command). Reads current milestone events, generates `.gsd-t/retrospectives/YYYY-MM-DD-{milestone}.md` with sections: What Worked, What Failed, Patterns Found, Proposed Memory Updates.
 
+### Auto-Route + Auto-Update Hooks (M16 — complete)
+- **`scripts/gsd-t-auto-route.js`** (39 lines): UserPromptSubmit hook. Reads JSON from stdin (`{ prompt, cwd, session_id }`). If `.gsd-t/progress.md` does not exist in cwd → exits silently. If prompt starts with `/` → exits silently. If plain text in a GSD-T project → emits `[GSD-T AUTO-ROUTE]` signal to Claude's context, routing the message through `/user:gsd`. Catches all exceptions — never blocks the prompt.
+- **`scripts/gsd-t-update-check.js`** (79 lines): SessionStart hook. Reads `~/.claude/.gsd-t-version`. Reads/refreshes `~/.claude/.gsd-t-update-check` cache (1h TTL). If newer version available: runs `npm install -g @tekyzinc/gsd-t@{latest}` + `gsd-t update-all` via execSync. Outputs `[GSD-T AUTO-UPDATE]`, `[GSD-T UPDATE]`, or `[GSD-T]` banner. NOTE: No module.exports — untestable as module (TD-081). Version string not validated before execSync (SEC-N28).
+
+### Scan Visual Output (M17 — complete v2.34.10)
+- **`bin/scan-schema.js`** (77 lines): ORM detector + schema extractor. Detects 7 ORM types (Prisma, TypeORM, Drizzle, Mongoose, Sequelize, SQLAlchemy, raw-SQL). Delegates to scan-schema-parsers.js. Returns SchemaData: `{ detected, ormType, entities[], parseWarnings[] }`. Never throws.
+- **`bin/scan-schema-parsers.js`** (199 lines): 7 parser functions (parsePrisma, parseTypeOrm, parseDrizzle, parseMongoose, parseSequelize, parseSqlAlchemy, parseRawSql). Returns Entity[] for each ORM type.
+- **`bin/scan-diagrams.js`** (77 lines): Diagram orchestrator. Calls scan-diagrams-generators.js for each of 6 types. Calls scan-renderer.js to render Mermaid to SVG. Always returns exactly 6 DiagramResult objects. Failed diagrams get placeholder HTML.
+- **`bin/scan-diagrams-generators.js`** (102 lines): Mermaid DSL source generators for 6 types: genSystemArchitecture, genAppArchitecture, genWorkflow, genDataFlow, genSequence, genDatabaseSchema. Falls back to generic diagram if analysisData lacks specific fields.
+- **`bin/scan-renderer.js`** (92 lines): Sync render chain: tryMmdc() → tryD2() → placeholder. Also contains tryKroki() (async, currently dormant — never called in sync path). Uses execSync (not execFileSync — see TD-084/SEC-N30).
+- **`bin/scan-report.js`** (116 lines): Generates self-contained HTML scan report. No external CSS/JS (all inline). Output: `{projectRoot}/scan-report.html` (see TD-092 for placement issue). Exports: generateReport(), buildCss(), buildSidebar(), buildHtmlSkeleton() + section builders.
+- **`bin/scan-report-sections.js`** (74 lines): HTML section builders: buildMetricCards, buildDomainHealth, buildDiagramSection, buildTechDebt, buildFindings.
+- **`bin/scan-export.js`** (49 lines): Export subcommand — DOCX via pandoc, PDF via md-to-pdf. Checks tool availability before attempting. Uses execSync (not execFileSync — see TD-084/SEC-N29).
+
 ### Real-Time Agent Dashboard (M15 — complete v2.33.10)
 - **`scripts/gsd-t-dashboard-server.js`** (141 lines, zero external deps): Node.js SSE server watching `.gsd-t/events/*.jsonl`. Exports: `startServer(port, eventsDir, htmlPath)`, `tailEventsFile(filePath, callback)`, `readExistingEvents(eventsDir, maxEvents)`, `parseEventLine(line)`, `findEventsDir(projectDir)`. HTTP endpoints: `GET /` (serve dashboard HTML), `GET /events` (SSE stream, max 500 events on connect + tail for new), `GET /ping` (health check), `GET /stop` (graceful shutdown). CLI: `--port`, `--events`, `--detach` (writes PID to `.gsd-t/dashboard.pid`), `--stop` (kills running server). Symlink protection via `lstatSync` pattern. 23 unit tests in `test/dashboard-server.test.js`.
 - **`scripts/gsd-t-dashboard.html`** (194 lines): React 17 + React Flow v11.11.4 + Dagre via CDN (no build step, no npm deps). Dark theme (`#0d1117`). Renders agent hierarchy as directed graph from `parent_agent_id` relationships. Live event feed (max 200, outcome color-coded). Auto-reconnects on SSE disconnect. Port configurable via `?port=` URL param.

package/docs/infrastructure.md

@@ -1,6 +1,6 @@
 # Infrastructure — GSD-T Framework (@tekyzinc/gsd-t)
 
-## Last Updated: 2026-02-18 (Post-M13, Scan #6)
+## Last Updated: 2026-03-09 (Scan #9, Post-M17)
 
 ## Quick Reference
 
@@ -30,7 +30,7 @@ node bin/gsd-t.js status
 
 ### Testing
 ```bash
-# Run automated test suite (125 tests, zero dependencies)
+# Run automated test suite (205 tests, zero dependencies)
 npm test
 
 # Test CLI subcommands manually
@@ -40,12 +40,21 @@ node bin/gsd-t.js doctor
 node bin/gsd-t.js init test-project
 
 # Validate command files exist
-ls commands/*.md | wc -l  # Should be 45
+ls commands/*.md | wc -l  # Should be 48
 ls templates/*.md | wc -l  # Should be 9
 
 # Test new utility scripts
 node scripts/gsd-t-tools.js validate
 node scripts/gsd-t-tools.js git pre-commit-check
+
+# Test scan visual output
+node bin/gsd-t.js scan --export html
+# Output: scan-report.html (self-contained, no external deps)
+
+# Test dashboard server
+node scripts/gsd-t-dashboard-server.js --port 7433 --detach
+# Browser: http://localhost:7433
+node scripts/gsd-t-dashboard-server.js --stop
 ```
 
 ### Scripts
@@ -54,8 +63,16 @@ node scripts/gsd-t-tools.js git pre-commit-check
 | `scripts/gsd-t-heartbeat.js` | Claude Code hook event logger (JSONL output, secret scrubbing) |
 | `scripts/npm-update-check.js` | Background npm registry version checker (path-validated) |
 | `scripts/gsd-t-fetch-version.js` | Synchronous npm registry fetch (5s timeout, 1MB limit) |
-| `scripts/gsd-t-tools.js` | State utility CLI — state get/set, validate, list, git check, template read (NEW M13) |
-| `scripts/gsd-t-statusline.js` | Context usage bar + project state for Claude Code statusLine setting (NEW M13) |
+| `scripts/gsd-t-tools.js` | State utility CLI — state get/set, validate, list, git check, template read (M13) |
+| `scripts/gsd-t-statusline.js` | Context usage bar + project state for Claude Code statusLine setting (M13) |
+| `scripts/gsd-t-event-writer.js` | Structured JSONL event appender CLI — writes to .gsd-t/events/ (M14) |
+| `scripts/gsd-t-dashboard-server.js` | Zero-dep SSE server for real-time dashboard — port 7433 (M15) |
+| `scripts/gsd-t-auto-route.js` | UserPromptSubmit hook — auto-routes plain text via /gsd in GSD-T projects (M16) |
+| `scripts/gsd-t-update-check.js` | SessionStart hook — fetches latest npm version, auto-updates GSD-T (M16) |
+| `bin/scan-schema.js` | ORM/DB schema detector + extractor — 7 ORM types (M17) |
+| `bin/scan-diagrams.js` | Diagram orchestrator — 6 diagram types, renders to SVG or placeholder (M17) |
+| `bin/scan-report.js` | Self-contained HTML scan report generator (M17) |
+| `bin/scan-export.js` | Export subcommand — DOCX (pandoc) + PDF (md-to-pdf) stubs (M17) |
 
 ## Distribution
 
@@ -68,7 +85,7 @@ node scripts/gsd-t-tools.js git pre-commit-check
 ### Installed Locations
 | What | Where |
 |------|-------|
-| Slash commands (45 files) | `~/.claude/commands/` |
+| Slash commands (48 files) | `~/.claude/commands/` |
 | Global config | `~/.claude/CLAUDE.md` |
 | Heartbeat script | `~/.claude/scripts/gsd-t-heartbeat.js` |
 | State utility CLI | `~/.claude/scripts/gsd-t-tools.js` |

package/docs/requirements.md

@@ -1,6 +1,6 @@
 # Requirements — GSD-T Framework (@tekyzinc/gsd-t)
 
-## Last Updated: 2026-03-04 (M15 Complete — Real-Time Agent Dashboard v2.33.10)
+## Last Updated: 2026-03-09 (Scan #9 — M17 complete)
 
 ## Functional Requirements
 
@@ -29,6 +29,13 @@
 | REQ-021 | Milestone Distillation — complete-milestone runs a distillation step: scans the event stream for patterns found ≥3 times, proposes concrete constraints.md / CLAUDE.md rule additions, user confirms before write | P2 | complete (M14) | validated by use |
 | REQ-022 | gsd-t-reflect command — reads .gsd-t/events/*.jsonl for the current milestone, generates structured retrospective (what worked, what failed, patterns found, proposed memory updates), outputs to .gsd-t/retrospectives/YYYY-MM-DD-{milestone}.md | P2 | complete (M14) | validated by use |
 | REQ-023 | Real-Time Agent Dashboard — gsd-t-visualize command starts a zero-dependency SSE server watching .gsd-t/events/ and opens gsd-t-dashboard.html in the browser; dashboard renders agent hierarchy (React Flow + Dagre via CDN) with live event overlay; all 6 interaction patterns visualized (wave/execute, parallel domains, scan, brainstorm, debug, quick/error) | P2 | complete (M15) | test/dashboard-server.test.js (23 tests) |
+| REQ-024 | Scan Schema Extraction — gsd-t-scan detects and parses ORM/schema definition files (TypeORM entities, Prisma schema, Drizzle schema, Mongoose models, SQLAlchemy models, raw SQL migrations) to extract: entity names, field names and types, primary/foreign keys, and relationships; outputs structured schema data consumed by REQ-025 ER diagram generation | P1 | complete (M17) | test/scan.test.js + verify-gates.js |
+| REQ-025 | Scan Diagram Generation — gsd-t-scan generates Mermaid diagram definition files (.mmd) for 6 diagram types derived from codebase analysis: (1) System Architecture — C4-style context diagram of services, databases, queues, and external integrations; (2) Application Architecture — layered diagram showing framework layers (controllers/guards/services/repositories) and their boundaries; (3) Workflow Diagram — state machine derived from status enums and state transition logic; (4) Data Flow Diagram — flowchart tracing data from user input through validation, persistence, async queues, and workers; (5) Sequence Diagram — request/response flow for the most critical API endpoint detected; (6) Database Schema — ER diagram generated from REQ-024 schema extraction | P1 | complete (M17) | test/scan.test.js + verify-gates.js |
+| REQ-026 | Scan Diagram Rendering — diagram definitions from REQ-025 are rendered to SVG using the configured backend (REQ-028); rendered SVGs are embedded inline in the HTML report; rendering backend is selected in priority order: Mermaid CLI → D2 → Kroki HTTP; if all backends fail a graceful fallback generates a "diagram unavailable" placeholder without blocking the report | P1 | complete (M17) | test/scan.test.js + verify-gates.js |
+| REQ-027 | Scan HTML Report — gsd-t-scan generates a self-contained HTML report (scan-report.html) containing: (a) sidebar navigation with scrollspy; (b) summary metric cards (files scanned, LoC, tech debt count by severity, test coverage %, outdated deps, API endpoint count); (c) domain health cards with file inventory and health score; (d) 6 diagram sections (REQ-025/026) each with title, type badge, inline SVG, expand-to-fullscreen button with scroll-to-zoom, and descriptive note; (e) tech debt register table with severity badges; (f) key findings with actionable recommendations; report uses dark theme, no external CDN required after generation | P1 | complete (M17) | test/scan.test.js + verify-gates.js |
+| REQ-028 | Scan Document Export — scan output exportable to two additional formats: (a) DOCX via Pandoc (GPL v2+) — converts scan-report.md + embedded images to .docx; upload to Google Drive auto-converts to Google Docs; (b) PDF via md-to-pdf (MIT) + Puppeteer — renders markdown with CSS styling to print-quality PDF; both export formats are triggered by optional flags (--export=docx, --export=pdf) and are independent of HTML report generation | P2 | complete (M17) | test/scan.test.js + verify-gates.js |
+| REQ-029 | Diagram Rendering Toolchain — three rendering backends supported, each free and open source, selected automatically based on availability: (1) Primary — Mermaid CLI (mmdc, @mermaid-js/mermaid-cli, MIT, npm) renders .mmd files to SVG via headless Chromium; (2) Enhanced — D2 (MPL-2.0, terrastruct/d2, Go binary) as optional renderer for architecture and dataflow diagrams — uses dagre/ELK/neato layouts (TALA excluded, paid); (3) Fallback — Kroki HTTP API (MIT, yuzutech/kroki) renders any supported format via single HTTP POST to kroki.io (public free tier) or self-hosted Docker instance | P2 | complete (M17) | test/scan.test.js + verify-gates.js |
+| REQ-030 | MCP Diagram Server Support — gsd-t-scan supports optional MCP-based diagram generation when registered MCP servers are detected in Claude Code settings: diagram-bridge-mcp (MIT, tohachan) selects optimal format and renders via Kroki; C4Diagrammer (MIT, jonverrier) specialized for existing codebase → C4 architecture diagrams; mcp-mermaid (MIT, hustcc) for 22 Mermaid diagram types; MCP path is preferred over CLI when available | P3 | complete (M17) | test/scan.test.js + verify-gates.js |
 
 ## Technical Requirements
 
@@ -42,6 +49,11 @@
 | TECH-006 | Symlink protection on all file write operations | P1 | complete |
 | TECH-007 | Input validation on project names, versions, paths, session IDs | P1 | complete |
 | TECH-008 | prepublishOnly gate — `npm test` runs before `npm publish` | P1 | complete (M8) |
+| TECH-009 | Mermaid CLI (@mermaid-js/mermaid-cli, MIT) is the primary diagram renderer — requires Node.js (already required by GSD-T); installed on demand if absent; renders .mmd → SVG/PNG via headless Chromium (Puppeteer peer dependency) | P1 | complete (M17) |
+| TECH-010 | D2 diagram renderer (MPL-2.0, terrastruct/d2) is optional — detected by `which d2`; used in preference to Mermaid CLI for architecture and dataflow diagram types when present; free layouts only: dagre, ELK, neato | P2 | complete (M17) |
+| TECH-011 | Kroki HTTP API (MIT, yuzutech/kroki) is the zero-install fallback renderer — single HTTP POST, no local dependencies; defaults to public kroki.io; configurable to self-hosted instance via KROKI_URL env var | P2 | complete (M17) |
+| TECH-012 | Pandoc (GPL v2+) used for DOCX and HTML document export; detected by `which pandoc`; --export flags silently skip if absent with a warning in report output | P2 | complete (M17) |
+| TECH-013 | All diagram and export tooling must be free and open source (MIT, MPL-2.0, GPL, or equivalent OSI-approved license) with no paid tiers, subscriptions, or per-request API fees required for core functionality | P1 | complete (M17) |
 
 ## Non-Functional Requirements
 
@@ -52,6 +64,10 @@
 | NFR-003 | Command files are pure markdown (no frontmatter) | 100% compliance | complete |
 | NFR-004 | Heartbeat auto-cleanup prevents unbounded growth | 7-day TTL | complete |
 | NFR-005 | Update check is non-blocking after first run | background process | complete |
+| NFR-006 | Scan HTML report renders all diagrams in browser within 5 seconds of opening | < 5s render | complete (M17) |
+| NFR-007 | Scan HTML report is self-contained after generation — all SVG diagrams are embedded inline; no external CDN dependencies required to view the report | 100% offline-capable | complete (M17) |
+| NFR-008 | Diagram generation degrades gracefully — if the primary renderer is unavailable the next backend is tried automatically; the scan report is always produced even if all renderers fail (placeholder shown instead of diagram) | zero blocking failures | complete (M17) |
+| NFR-009 | Schema extraction completes within the scan time budget — ORM/schema file parsing adds no more than 10% to total scan duration | ≤ 10% overhead | complete (M17) |
 
 ## Test Coverage
 
@@ -75,11 +91,113 @@
 | REQ-022 | gsd-t-reflect command — retrospective from events/          | reflect       | Task 2, Task 3  | complete |
 | REQ-023 | Real-Time Agent Dashboard — SSE server + React Flow dashboard + gsd-t-visualize command | server, dashboard, command | server T1, dashboard T1, command T1, T2, T3 | complete (M15) |
 
+| REQ-024 | Scan Schema Extraction — ORM/schema parser → structured entity data       | scan-schema      | pending         | planned |
+| REQ-025 | Scan Diagram Generation — 6 diagram type .mmd files from codebase analysis | scan-diagrams    | pending         | planned |
+| REQ-026 | Scan Diagram Rendering — .mmd → SVG via Mermaid CLI / D2 / Kroki           | scan-diagrams    | pending         | planned |
+| REQ-027 | Scan HTML Report — self-contained report with inline SVGs + all sections    | scan-report      | pending         | planned |
+| REQ-028 | Scan Document Export — DOCX (Pandoc) + PDF (md-to-pdf) export flags        | scan-export      | pending         | planned |
+| REQ-029 | Diagram Rendering Toolchain — Mermaid CLI → D2 → Kroki fallback chain      | scan-diagrams    | pending         | planned |
+| REQ-030 | MCP Diagram Server Support — diagram-bridge-mcp / C4Diagrammer / mcp-mermaid | scan-diagrams  | pending         | planned |
+
 **Orphaned requirements**: REQ-001 through REQ-017 (all M1–M13 deliverables, complete — not mapped to M14 tasks by design).
 **Unanchored tasks**: command Task 2 (bin/gsd-t.js installer update) and Task 3 (4 reference files) are infrastructure supporting REQ-023 — implicitly mapped.
 
 ---
 
+## M17: Scan Visual Output — Feature Specification
+
+**Goal**: Transform `gsd-t-scan` from a text-only analysis tool into a rich visual report generator. Every scan produces a beautiful, self-contained HTML report with live diagrams, a tech debt register, and domain health scores — plus optional export to Google Docs via DOCX or PDF.
+
+### Scope
+
+| Area | Description |
+|------|-------------|
+| Schema extraction | Detect and parse ORM/schema files to extract entity relationships |
+| Diagram generation | Generate Mermaid (.mmd) diagram definitions for 6 diagram types |
+| Diagram rendering | Render .mmd → SVG using Mermaid CLI, D2, or Kroki (auto-fallback) |
+| HTML report | Self-contained dark-theme report with inline SVGs and expand-to-fullscreen |
+| Document export | DOCX (Pandoc → Google Docs) and PDF (md-to-pdf) export via --export flag |
+| MCP support | Optional MCP server integration when registered in Claude Code settings |
+
+### Diagram Types (REQ-025)
+
+| # | Diagram | Source Analysis | Mermaid Syntax |
+|---|---------|-----------------|----------------|
+| 1 | System Architecture | Config files, imports, env vars, API clients | `C4Context` or `graph TB` |
+| 2 | Application Architecture | Module/class structure, framework layers, routing | `graph TB` with subgraphs |
+| 3 | Workflow | Status enums, state transition methods, FSM patterns | `stateDiagram-v2` |
+| 4 | Data Flow | Request handlers, validation pipes, DB calls, queue producers | `flowchart TD` |
+| 5 | Sequence | Critical API endpoint: auth flow or primary resource creation | `sequenceDiagram` |
+| 6 | Database Schema | ORM entities / Prisma schema / SQL migrations (REQ-024) | `erDiagram` |
+
+### ORM Detection Matrix (REQ-024)
+
+| ORM / Tool | Detection Signal | Schema Source |
+|------------|-----------------|---------------|
+| TypeORM | `@Entity()`, `typeorm` import | `*.entity.ts` files |
+| Prisma | `prisma/schema.prisma` exists | `schema.prisma` |
+| Drizzle | `drizzle-orm` import | `schema.ts` / `*.schema.ts` |
+| Mongoose | `mongoose.Schema`, `new Schema` | `*.model.ts` / `*.schema.ts` |
+| Sequelize | `DataTypes`, `Model.init` | `*.model.js/ts` |
+| SQLAlchemy | `declarative_base`, `Column` | `models.py` / `*.model.py` |
+| Raw SQL | `CREATE TABLE` in `.sql` files | `migrations/*.sql` |
+
+### Rendering Toolchain (REQ-029)
+
+```
+RENDER REQUEST
+  ├── Is `mmdc` (Mermaid CLI) available?
+  │     YES → mmdc -i diagram.mmd -o diagram.svg -t dark   (primary)
+  │     NO  ↓
+  ├── Is `d2` available AND diagram type is arch/dataflow?
+  │     YES → d2 diagram.d2 diagram.svg --layout=dagre      (enhanced)
+  │     NO  ↓
+  ├── Is network available?
+  │     YES → POST diagram src to kroki.io → SVG response   (fallback)
+  │     NO  ↓
+  └── Embed "diagram unavailable" placeholder in report     (graceful degrade)
+```
+
+### HTML Report Structure (REQ-027)
+
+```
+scan-report.html
+  ├── Sidebar navigation (scrollspy, domain/diagram/analysis sections)
+  ├── Compact page header (project name, version, date, stack)
+  ├── Summary (metric cards: files, LoC, debt counts, coverage, deps, endpoints)
+  ├── Domains (health cards with file inventory and health % bar)
+  ├── Diagram sections × 6 (title bar + type badge + SVG + expand button + note)
+  ├── Tech Debt Register (table: severity badge, domain, issue, location, effort)
+  └── Key Findings (actionable cards: security, architecture, reliability, quality)
+```
+
+### Document Export (REQ-028)
+
+| Flag | Tool | Output | Google Docs Path |
+|------|------|--------|-----------------|
+| `--export=docx` | Pandoc (GPL) | `scan-report.docx` | Upload to Drive → Open with Google Docs |
+| `--export=pdf` | md-to-pdf (MIT) | `scan-report.pdf` | Upload to Drive → open directly |
+| _(none)_ | — | `scan-report.html` | Copy/paste markdown, or File → Import |
+
+### Free & Open Source Toolchain Confirmation
+
+| Tool | License | Free? | Paid Components |
+|------|---------|-------|-----------------|
+| Mermaid CLI (`@mermaid-js/mermaid-cli`) | MIT  | Yes | None |
+| D2 (terrastruct/d2) | MPL-2.0  | Yes | TALA layout only (excluded) |
+| Kroki (yuzutech/kroki) | MIT  | Yes | None (self-host or free kroki.io) |
+| diagram-bridge-mcp (tohachan) | MIT  | Yes | None |
+| C4Diagrammer (jonverrier) | MIT  | Yes | None |
+| mcp-mermaid (hustcc) | MIT  | Yes | None |
+| Pandoc | GPL v2+  | Yes | None |
+| md-to-pdf (simonhaenisch) | MIT  | Yes | None |
+
+### Mock Reference
+
+A reference implementation of the HTML report output is at `scan-report-mock.html` (project root). It demonstrates all 6 diagram types, the tech debt register, domain health cards, and the expand-to-fullscreen interaction. Use this as the visual specification for the HTML report (REQ-027).
+
+---
+
 ## Gaps Identified
 
 ### Open (Scan #6 — 2026-02-18, Post-M10-M13)

package/docs/workflows.md

@@ -1,6 +1,6 @@
 # Workflows — GSD-T Framework (@tekyzinc/gsd-t)
 
-## Last Updated: 2026-02-18 (Post-M13, Scan #6)
+## Last Updated: 2026-03-09 (Scan #9, Post-M17)
 
 ## User Workflows
 
@@ -158,3 +158,69 @@ Every commit must pass applicable checks:
 - **Trigger**: `gsd-t update-all` CLI command
 - **Flow**: Global update → iterate registered projects → inject Destructive Action Guard → create CHANGELOG → health check (Playwright, Swagger)
 - **Registry**: `~/.claude/.gsd-t-projects` (newline-separated absolute paths)
+
+### Real-Time Agent Dashboard (M14)
+
+**Launch workflow** (`/gsd-t-visualize`):
+1. Check if server is running: `GET http://localhost:7433/ping`
+2. If not running: spawn `gsd-t-dashboard-server.js --detach` as background process; write PID to `.gsd-t/dashboard.pid`
+3. Open browser to `http://localhost:7433`
+4. Dashboard connects to `GET /events` (Server-Sent Events stream)
+
+**Event stream flow**:
+1. Claude Code hook fires (any hook event)
+2. `gsd-t-event-writer.js` validates event fields and appends JSON line to `.gsd-t/events/YYYY-MM-DD.jsonl`
+3. Dashboard server (`gsd-t-dashboard-server.js`) detects file change via `fs.watchFile()`
+4. New event lines are broadcast as SSE: `data: {event-json}\n\n`
+5. Dashboard HTML (React app via CDN) renders event feed with agent hierarchy
+
+**Stop workflow**:
+1. User runs `/gsd-t-visualize stop` or `GET /stop`
+2. Server reads PID file, sends SIGTERM, deletes PID file
+
+**Note:** Server watches only the newest JSONL file at startup. Date rollover (midnight UTC) requires server restart to pick up new file (TD-085).
+
+### Auto-Update Workflow (M15)
+
+1. Claude Code SessionStart hook fires
+2. `gsd-t-update-check.js` reads `~/.claude/.gsd-t-version` (installed version)
+3. Reads cached version from `~/.claude/.gsd-t-update-check` (JSON: `{latest, timestamp}`)
+4. If cached version newer than installed: auto-runs `npm install -g @tekyzinc/gsd-t@{latest}` + `gsd-t update-all`
+5. Outputs `[GSD-T AUTO-UPDATE]`, `[GSD-T UPDATE]`, or `[GSD-T] v{ver}` to stdout
+6. Claude agent reads hook output from context and shows update status in first response
+
+**Cache TTL**: 1 hour. After TTL, background `npm-update-check.js` refreshes async.
+
+### Auto-Route Workflow (M16)
+
+1. User types plain text in Claude Code in a GSD-T project directory
+2. `gsd-t-auto-route.js` UserPromptSubmit hook fires
+3. Script checks if `.gsd-t/progress.md` exists in cwd
+4. If yes: injects `[GSD-T AUTO-ROUTE]` signal into prompt context
+5. Claude agent sees signal and routes the plain text message through `/user:gsd {message}`
+6. Smart router interprets intent and launches appropriate GSD-T command
+
+**Note:** Only fires in GSD-T projects (`.gsd-t/progress.md` must exist). Silently passes through in all other directories.
+
+### Scan Visual Output Workflow (M17)
+
+1. User runs `/gsd-t-scan` — scan subagent analyzes codebase (Steps 1-2)
+2. **Schema extraction** (Step 2.5): `bin/scan-schema.js` detects ORM/schema files
+   - Tries Prisma → TypeORM → Drizzle → Mongoose → Sequelize → SQLAlchemy → raw SQL
+   - Returns `SchemaData { detected, ormType, entities[], parseWarnings[] }`
+3. **Diagram generation** (Step 3.5): `bin/scan-diagrams.js` generates 6 Mermaid diagrams
+   - Types: system-architecture, app-architecture, workflow, data-flow, sequence, database-schema
+   - Renderer chain: mmdc (CLI) → d2 (CLI) → placeholder HTML
+4. **HTML report generation** (Step 8): `bin/scan-report.js` produces self-contained HTML
+   - Sidebar navigation with scrollspy, metric cards, domain health bars
+   - 6 diagram sections with expand-to-modal button
+   - Tech debt table, key findings
+   - Written to project root as `scan-report.html`
+5. **Export** (optional `--export` flag): `bin/scan-export.js` handles docx/pdf (stubs in v2.34.10)
+
+**No external dependencies**: HTML report is fully self-contained (no CDN). All CSS/JS inlined.
+
+### npm Pre-Publish Gate (Updated)
+- **Trigger**: `npm publish` (via `prepublishOnly`)
+- **Gate**: `npm test` runs 205 tests (8 files including verify-gates.js)
+- **Verify-gates checks**: file size compliance (all bin/*.js ≤ 200 lines), no CDN references in scan-report.html, has DOCTYPE, has 6 diagram sections, export format validation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.33.12",
+  "version": "2.34.11",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 48 slash commands with real-time agent dashboard, execution intelligence, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",