ma-agents 3.6.2 → 3.9.0

package/_bmad-output/implementation-artifacts/19-4-graph-emission-create-story-remaining.md

@@ -1,190 +0,0 @@
-# Story 19.4: Graph Emission — `create-story`, `validate-prd`, `dev-story`, `bmad-sprint-planning`
-
-Status: ready-for-dev
-
-## Story
-
-As a **Developer** and **QA Engineer**,
-I want individual story files and validation artifacts to emit traceability edges automatically,
-so that the knowledge graph captures the full SDLC chain from PRD through architecture through epics through stories through implementation.
-
-## Acceptance Criteria
-
-1. **Given** the `create-story` skill generates a story file (e.g., `_bmad-output/implementation-artifacts/17-9-unified-sprint-status-schema.md`)
-   **When** emission runs
-   **Then** the story file is registered in the `files` table with `pointer_type: "relative_path"` and a file-id derived from the story number (e.g., `story-17-9`)
-   **And** a node is emitted for the story root heading (type: `story`)
-   **And** a `traces-to` edge is emitted from the story node to its parent epic node: `{ from: "story-<epic>-<num>#<story-slug>", to: "epics#epic-<N>-<name>", type: "traces-to", ... }`
-   **And** if the story's technical notes reference architecture decisions (e.g., `Decision P3-1`, `arch#`), `informed-by` edges are emitted from the story node to the relevant architecture nodes
-
-2. **Given** the `validate-prd` skill completes a validation report
-   **When** emission runs
-   **Then** the validation report file is registered with file-id `validation-<date>` (e.g., `validation-2026-04-07`)
-   **And** a `validates` edge is emitted from the validation report node to `prd#functional-requirements`: `{ type: "validates", label: "PRD validation report <date>", created_by: <user>, agent: "bmad-validate-prd", created_at: <timestamp> }`
-
-3. **Given** `dev-story` completes implementation guidance for a story
-   **When** emission runs
-   **Then** a `refines` edge is emitted from the story node to `arch#implementation-notes` (or the most relevant architecture section found by scanning the dev-story output)
-   **And** if no architecture section is identifiable, the edge target defaults to the story's own epic node
-
-4. **Given** `bmad-sprint-planning` completes sprint plan generation
-   **When** emission runs
-   **Then** sprint plan nodes are emitted with `type: "sprint"`
-   **And** `derives-from` edges connect sprint nodes to the relevant epic nodes referenced in the sprint plan
-
-5. **Given** any of the 4 skills runs a second time on the same project
-   **When** emission runs
-   **Then** all emissions are idempotent — no duplicate nodes or edges added
-
-## Tasks / Subtasks
-
-### Task 1: Add emission to `create-story` (AC: 1, 5)
-
-Both IDE skill and BMAD extension skill must be updated.
-
-- [ ] 1.1 Locate: `skills/bmad-create-story/SKILL.md` and `lib/bmad-extension/skills/bmad-create-story/SKILL.md`
-- [ ] 1.2 Add final silent step after story file write:
-  - Derive `storyFileId` from the story key: `story-<epic_num>-<story_num>` (e.g., `story-19-1`)
-  - Register story file in `files`: `{ pointer: "_bmad-output/implementation-artifacts/<filename>.md", title: "<story title>", pointer_type: "relative_path" }`
-  - Emit story root node: `{ id: "<storyFileId>#<story-heading-anchor>", file: "<storyFileId>", anchor: "<story-heading-anchor>", title: "<story title>", type: "story" }`
-  - Emit `traces-to` edge to parent epic node: `{ from: "<storyFileId>#<story-heading-anchor>", to: "epics#<epic-slug>", type: "traces-to", label: "implements epic", ... }`
-  - Scan story's Dev Notes section for `Decision P\d+-\d+` or `arch#` patterns; emit `informed-by` edges to matched architecture nodes
-- [ ] 1.3 Epic node slug derivation: scan `epics.md` for `## Epic <N>:` heading and apply `headingToAnchor()` to get the target anchor. Or construct `"epic-<N>-<name>"` from the epic title in the story key.
-
-### Task 2: Add emission to `validate-prd` (AC: 2, 5)
-
-- [ ] 2.1 Locate: `skills/bmad-validate-prd/SKILL.md` and `lib/bmad-extension/skills/bmad-validate-prd/SKILL.md`
-- [ ] 2.2 Add final silent step after validation report write:
-  - Derive date string from current date (ISO format, date portion only): e.g., `2026-04-07`
-  - File-id: `validation-<date>`
-  - Infer the validation report path from the skill's output path (typically `_bmad-output/planning-artifacts/validation-report-prd-<date>.md`)
-  - Emit `validates` edge: `{ from: "validation-<date>#validation-summary", to: "prd#functional-requirements", type: "validates", label: "PRD validation report <date>", created_by: <user>, agent: "bmad-validate-prd", created_at: <timestamp> }`
-
-### Task 3: Add emission to `dev-story` (AC: 3, 5)
-
-- [ ] 3.1 Locate: `skills/bmad-dev-story/SKILL.md` and `lib/bmad-extension/skills/bmad-dev-story/SKILL.md`
-- [ ] 3.2 Add final silent step after dev notes written:
-  - Identify the story being worked on (story key from context)
-  - The story node should already exist in the graph from `create-story` (Story 19.1 step). Re-emit is safe (idempotent).
-  - Scan the dev-story output for architecture section references; prefer the most specific match
-  - Emit `refines` edge: `{ from: "<storyFileId>#<story-heading-anchor>", to: "arch#<best-arch-section>", type: "refines", label: "dev implementation of story", created_by: <user>, agent: "bmad-dev-story", created_at: <timestamp> }`
-  - If no architecture section identifiable, use the epic node as fallback target
-
-### Task 4: Add emission to `bmad-sprint-planning` (AC: 4, 5)
-
-- [ ] 4.1 Locate: `skills/bmad-sprint-planning/SKILL.md` and `lib/bmad-extension/skills/bmad-sprint-planning/SKILL.md`
-- [ ] 4.2 Add final silent step after sprint plan output:
-  - Sprint plan file-id: `sprint-plan-<sprint-number>` (e.g., `sprint-plan-1`)
-  - Emit sprint plan node: `{ id: "sprint-plan-<N>#sprint-plan", file: "sprint-plan-<N>", anchor: "sprint-plan", title: "Sprint <N> Plan", type: "sprint" }`
-  - For each epic referenced in the sprint plan, emit `derives-from` edge: `{ from: "sprint-plan-<N>#sprint-plan", to: "epics#<epic-slug>", type: "derives-from", label: "sprint covers epic", ... }`
-
-### Task 5: Verify all 4 skills emit correctly (AC: 1–5)
-
-- [ ] 5.1 Trace through a full emission sequence: create-prd → create-architecture → create-epics-and-stories → create-story → validate-prd → dev-story → bmad-sprint-planning
-- [ ] 5.2 Verify the resulting `knowledge-graph.json` has no duplicate nodes or edges
-- [ ] 5.3 Verify `meta` counts match actual array/object sizes
-
-## Dev Notes
-
-### CRITICAL: Two Deployment Pipelines (Same Pattern as 19.2, 19.3)
-
-For each of the 4 skills, update BOTH:
-1. `skills/<skill-name>/SKILL.md` — IDE source
-2. `lib/bmad-extension/skills/<skill-name>/SKILL.md` — BMAD extension source
-
-Do NOT edit installed copies at `.claude/skills/` or `_bmad/extensions/ma-agents-skills/skills/`.
-
-### Prerequisite: Story 19.1 Must Be Complete
-
-Stories 19.2, 19.3, and 19.4 can proceed in parallel once 19.1 is done. This story does NOT depend on 19.2 or 19.3 completing first — they all independently wire in to the same `emitToGraph()` utility.
-
-### The 7 Emitting Skills — Full Inventory
-
-| Skill | Story | Edge Types Emitted |
-|-------|-------|--------------------|
-| `bmad-create-prd` | 19.2 | (none — seeds nodes only) |
-| `bmad-create-architecture` | 19.3 | `implements` |
-| `bmad-create-epics-and-stories` | 19.3 | `derives-from`, `informed-by` |
-| `bmad-create-story` | **19.4** | `traces-to`, `informed-by` |
-| `bmad-validate-prd` | **19.4** | `validates` |
-| `bmad-dev-story` | **19.4** | `refines` |
-| `bmad-sprint-planning` | **19.4** | `derives-from` |
-
-### Story File-ID Convention
-
-File-id format: `story-<epic_num>-<story_num>`
-- Story key `19-1-knowledge-graph-core-library` → file-id `story-19-1`
-- Story key `17-9-unified-sprint-status-schema` → file-id `story-17-9`
-
-This is derived directly from the story file path: `_bmad-output/implementation-artifacts/<epic_num>-<story_num>-*.md`
-
-### Story Heading Anchor
-
-The story root heading is `# Story <epic>.<story_num>: <title>`. Apply `headingToAnchor()`:
-- `"Story 19.1: Knowledge Graph Core Library (emitToGraph)"` → `"story-191-knowledge-graph-core-library-emittograph"`
-
-Use the file-id as the node's `file` field, not `story`.
-
-### Epic Slug Lookup
-
-To construct the `traces-to` edge target `"epics#<epic-slug>"`, apply `headingToAnchor()` to the epic heading from `epics.md` (e.g., `"Epic 19: BMAD Knowledge Graph (Phase 3)"` → `"epic-19-bmad-knowledge-graph-phase-3"`).
-
-The story's epic number is known from its story key (first number). Scan `epics.md` for `## Epic <N>:` to find the exact heading text and derive the anchor.
-
-### Validation Report File Path
-
-The `validate-prd` skill outputs files like `_bmad-output/planning-artifacts/validation-report-prd-<date>.md`. The file-id `validation-<date>` is derived from the output path. Anchor for the validation node: `headingToAnchor("Validation Summary")` → `"validation-summary"` (or the actual first `##` heading in the report).
-
-### `refines` Edge for dev-story
-
-The `refines` edge captures that a dev-story execution added implementation guidance to the story's context. The source is the story node (already exists from `create-story` emission). The target is the most relevant architecture section. If none found, use the epic node as fallback.
-
-### Sprint Plan Node Registration
-
-`bmad-sprint-planning` does not write a persistent sprint plan file in the current architecture (it writes to `sprint-status.yaml`). For graph emission, use `sprint-status.yaml` as the sprint plan file:
-- File-id: `sprint-status`
-- Pointer: `_bmad-output/implementation-artifacts/sprint-status.yaml`
-- Emit one `sprint` node per sprint entry found in `sprint-status.yaml`
-- Emit `derives-from` edges for epics covered by active/current sprint
-
-### Error Handling
-
-Same as Stories 19.2/19.3: wrap all `emitToGraph()` calls in try/catch. Emission failures are non-critical — log to stderr, do not abort the skill or show error to user.
-
-### File Structure Reference
-
-```
-skills/
-├── bmad-create-story/SKILL.md          ← MODIFY
-├── bmad-validate-prd/SKILL.md          ← MODIFY
-├── bmad-dev-story/SKILL.md             ← MODIFY
-└── bmad-sprint-planning/SKILL.md       ← MODIFY
-
-lib/bmad-extension/skills/
-├── bmad-create-story/SKILL.md          ← MODIFY
-├── bmad-validate-prd/SKILL.md          ← MODIFY
-├── bmad-dev-story/SKILL.md             ← MODIFY
-└── bmad-sprint-planning/SKILL.md       ← MODIFY
-```
-
-No new files created (8 existing SKILL.md files modified).
-
-### References
-
-- Story 19.1: `_bmad-output/implementation-artifacts/19-1-knowledge-graph-core-library.md`
-- Architecture skill emission table: `_bmad-output/planning-artifacts/architecture.md#skills-that-emit-and-what-they-emit`
-- Architecture Decision P3-1: `_bmad-output/planning-artifacts/architecture.md#decision-p3-1-bmad-knowledge-graph`
-- Epic 19 cross-epic notes: `_bmad-output/planning-artifacts/epics.md#epic-19--cross-epic-notes`
-- FRs: FR149, FR150, FR151, FR152
-
-## Dev Agent Record
-
-### Agent Model Used
-
-_to be filled by dev agent_
-
-### Debug Log References
-
-### Completion Notes List
-
-### File List

package/_bmad-output/implementation-artifacts/19-5-open-graph-skill.md

@@ -1,213 +0,0 @@
-# Story 19.5: `open-graph` Skill
-
-Status: ready-for-dev
-
-## Story
-
-As an **Engineer**,
-I want to run `/open-graph` in any BMAD agent,
-so that the knowledge graph visualization opens in VSCode (as a webview) or in my default browser when outside VSCode — without any additional configuration.
-
-## Acceptance Criteria
-
-1. **Given** `open-graph` is invoked inside VSCode (detected via `process.env.TERM_PROGRAM === 'vscode'` or `process.env.VSCODE_PID !== undefined`)
-   **When** the skill runs
-   **Then** it generates `_bmad-output/knowledge-graph.html` (if not already current) from the JSON data
-   **And** opens the HTML file using `code "<htmlPath>"` command (opens in VSCode Simple Browser / Live Preview)
-
-2. **Given** `open-graph` is invoked outside VSCode (standard terminal)
-   **When** the skill runs
-   **Then** it generates `knowledge-graph.html` from the current JSON data
-   **And** opens it using the platform-appropriate command: `start` (Windows), `open` (macOS), `xdg-open` (Linux)
-
-3. **Given** `_bmad-output/knowledge-graph.json` does not exist
-   **When** `open-graph` is invoked
-   **Then** the skill informs the user that no knowledge graph data has been generated yet
-   **And** suggests running a BMAD planning skill (e.g., `create-prd`) to seed the graph
-
-4. **Given** `knowledge-graph.html` already exists and is newer than `knowledge-graph.json`
-   **When** `open-graph` is invoked
-   **Then** the skill skips regeneration and opens the existing HTML directly
-
-5. **Given** `open-graph` is invoked from a BMAD agent
-   **When** it runs
-   **Then** it is available as an `anytime` phase skill (not restricted to a specific workflow phase)
-   **And** it appears in the BMAD module help output
-
-## Tasks / Subtasks
-
-### Task 1: Create BMAD extension skill directory and files (AC: 1, 2, 3, 4, 5)
-
-- [ ] 1.1 Create directory: `lib/bmad-extension/skills/open-graph/`
-- [ ] 1.2 Create `lib/bmad-extension/skills/open-graph/bmad-skill-manifest.yaml`:
-  ```yaml
-  type: skill
-  name: open-graph
-  module: ma-skills
-  ```
-- [ ] 1.3 Create `lib/bmad-extension/skills/open-graph/SKILL.md` with the complete skill workflow (see Task 3)
-- [ ] 1.4 Register in `lib/bmad-extension/module-help.csv` — add row:
-  ```
-  ma-skills,anytime,Open Knowledge Graph,open-graph,,skill:open-graph,open-graph,false,,,Open the BMAD knowledge graph visualization in VSCode or browser.,_bmad-output,knowledge-graph.json,
-  ```
-
-### Task 2: Create the IDE skill source files (AC: 1, 2, 3, 4)
-
-- [ ] 2.1 Create `skills/open-graph/skill.json`:
-  ```json
-  {
-    "name": "open-graph",
-    "version": "1.0.0",
-    "description": "Open the BMAD knowledge graph visualization in VSCode or default browser",
-    "category": "workflow",
-    "tags": ["knowledge-graph", "visualization", "graph"]
-  }
-  ```
-  Note: `always_load: false` — on-demand skill, not loaded for every task.
-- [ ] 2.2 Create `skills/open-graph/SKILL.md` with the same core workflow as the BMAD extension version (may have minor phrasing differences for IDE context; logic must be identical)
-
-### Task 3: Implement `SKILL.md` workflow content (AC: 1, 2, 3, 4)
-
-Both SKILL.md files must implement the following logic:
-
-- [ ] 3.1 **Step 1 — Locate graph data:**
-  - Resolve `graphJsonPath = <projectRoot>/_bmad-output/knowledge-graph.json`
-  - If file does not exist: output `"No knowledge graph data found. Run a BMAD planning skill (e.g., create-prd, create-architecture) to generate the graph first."` and exit (AC: 3)
-
-- [ ] 3.2 **Step 2 — Check if regeneration needed:**
-  - Resolve `graphHtmlPath = <projectRoot>/_bmad-output/knowledge-graph.html`
-  - Compare mtime of `knowledge-graph.html` vs `knowledge-graph.json`:
-    - If HTML exists AND `html.mtime > json.mtime`: skip regeneration, proceed to Step 3 (AC: 4)
-    - Otherwise: call `generate-html.js` to regenerate HTML from JSON
-
-- [ ] 3.3 **Step 3 — Generate HTML (if needed):**
-  - Run `node lib/bmad-extension/skills/open-graph/generate-html.js <graphJsonPath> <graphHtmlPath>`
-  - (The `generate-html.js` script is created in Story 19.6 — this story creates a placeholder that outputs a basic diagnostic page)
-
-- [ ] 3.4 **Step 4 — Open in appropriate viewer:**
-  ```javascript
-  const isVSCode = process.env.TERM_PROGRAM === 'vscode' || process.env.VSCODE_PID !== undefined;
-  if (isVSCode) {
-    execSync(`code "${htmlPath}"`);  // opens in VSCode Simple Browser / Live Preview
-  } else {
-    const openCmd = process.platform === 'win32' ? 'start' :
-                    process.platform === 'darwin' ? 'open' : 'xdg-open';
-    execSync(`${openCmd} "${htmlPath}"`);
-  }
-  ```
-
-### Task 4: Create `generate-html.js` placeholder (AC: 1, 2 — basic version)
-
-Story 19.6 implements the full renderer. This story creates a functional placeholder so the skill works end-to-end:
-
-- [ ] 4.1 Create `lib/bmad-extension/skills/open-graph/generate-html.js` as a Node.js script that:
-  - Accepts arguments: `node generate-html.js <jsonPath> <htmlPath>`
-  - Reads `knowledge-graph.json`
-  - Writes a minimal HTML page that displays `meta.node_count`, `meta.edge_count`, and a `<pre>` dump of the JSON data
-  - This placeholder will be replaced by the full renderer in Story 19.6
-
-### Task 5: Verify deployment pipeline integration (AC: 5)
-
-- [ ] 5.1 Run `npx ma-agents` (or `node lib/cli.js`) to trigger the installer
-- [ ] 5.2 Verify IDE skill appears in installed MANIFEST.yaml (e.g., `.claude/skills/MANIFEST.yaml` includes `open-graph`)
-- [ ] 5.3 Verify BMAD extension copy exists at `_bmad/extensions/ma-agents-skills/skills/open-graph/` after BMAD install
-- [ ] 5.4 Verify `open-graph` appears in the BMAD module help output (`anytime` phase)
-
-## Dev Notes
-
-### CRITICAL: Two Deployment Pipelines
-
-This story creates files in BOTH pipelines:
-1. **IDE skill source:** `skills/open-graph/skill.json` + `skills/open-graph/SKILL.md`
-   - Deployed by `lib/installer.js` to all agent directories
-2. **BMAD extension skill source:** `lib/bmad-extension/skills/open-graph/SKILL.md` + `bmad-skill-manifest.yaml`
-   - Deployed by `lib/bmad.js` to `_bmad/extensions/ma-agents-skills/`
-
-**Reference skill for IDE pipeline:** `skills/story-status-lookup/` (working `skill.json` + `SKILL.md`)
-**Reference skill for BMAD extension:** `lib/bmad-extension/skills/add-to-sprint/` (working `SKILL.md` + `bmad-skill-manifest.yaml`)
-
-### Prerequisite: Story 19.1 Must Be Complete (for `generate-html.js`)
-
-This story creates a `generate-html.js` placeholder (Task 4) that becomes the integration point for Story 19.6. The `generate-html.js` interface must be stable: `node generate-html.js <jsonPath> <htmlPath>`.
-
-### VSCode Detection Logic (Architecture-Authoritative)
-
-```javascript
-const isVSCode = process.env.TERM_PROGRAM === 'vscode' || process.env.VSCODE_PID !== undefined;
-if (isVSCode) {
-  execSync(`code "${htmlPath}"`);
-} else {
-  const openCmd = process.platform === 'win32' ? 'start' :
-                  process.platform === 'darwin' ? 'open' : 'xdg-open';
-  execSync(`${openCmd} "${htmlPath}"`);
-}
-```
-
-This exact pattern is specified in architecture Decision P3-1. Do NOT use a different detection mechanism.
-
-### Skill Count Impact
-
-This story increases the BMAD extension module skill count from 44 to 45. The `module-help.csv` row must use phase `anytime` (not a specific workflow phase). Verify the final count in `lib/bmad-extension/module-help.csv` after adding the row.
-
-### `generate-html.js` Interface Contract
-
-The interface between SKILL.md and `generate-html.js` is:
-```
-node lib/bmad-extension/skills/open-graph/generate-html.js <jsonPath> <htmlPath>
-```
-
-Arguments:
-- `<jsonPath>`: absolute path to `knowledge-graph.json`
-- `<htmlPath>`: absolute path where `knowledge-graph.html` should be written
-
-Story 19.6 replaces the placeholder with the full interactive renderer, keeping the same interface.
-
-### `always_load: false`
-
-This is an on-demand skill. The `skill.json` must NOT include `always_load: true`. Omitting the key defaults to `false`.
-
-### File Structure Created by This Story
-
-```
-skills/
-└── open-graph/
-    ├── skill.json                 ← NEW
-    └── SKILL.md                   ← NEW
-
-lib/
-└── bmad-extension/
-    └── skills/
-        └── open-graph/
-            ├── SKILL.md           ← NEW
-            ├── bmad-skill-manifest.yaml  ← NEW
-            └── generate-html.js   ← NEW (placeholder; replaced by Story 19.6)
-```
-
-**Modified:**
-- `lib/bmad-extension/module-help.csv` ← add `open-graph` row
-
-### Project Structure Notes
-
-- Skill location `lib/bmad-extension/skills/open-graph/` follows the same pattern as all other extension skills (e.g., `lib/bmad-extension/skills/add-to-sprint/`)
-- Epic 19 cross-epic notes: `open-graph` skill requires Epic 15 (BMAD 6.2.1 module structure) to be complete. Epic 15 is done as of this writing.
-
-### References
-
-- Architecture Decision P3-1 — Layer 3: `_bmad-output/planning-artifacts/architecture.md#layer-3-open-graph-skill-and-renderer`
-- Reference IDE skill: `skills/story-status-lookup/`
-- Reference BMAD extension skill: `lib/bmad-extension/skills/add-to-sprint/`
-- `lib/bmad-extension/module-help.csv` — for phase registration pattern
-- FR: FR153 (open-graph skill, VSCode/browser detection)
-- Story 19.6: `_bmad-output/implementation-artifacts/19-6-interactive-visualization-renderer.md` — replaces `generate-html.js` placeholder
-
-## Dev Agent Record
-
-### Agent Model Used
-
-_to be filled by dev agent_
-
-### Debug Log References
-
-### Completion Notes List
-
-### File List

package/_bmad-output/implementation-artifacts/19-6-interactive-visualization-renderer.md

@@ -1,259 +0,0 @@
-# Story 19.6: Interactive Visualization Renderer
-
-Status: ready-for-dev
-
-## Story
-
-As an **Engineer**,
-I want the knowledge graph HTML file to render an interactive, navigable visualization of all project artifacts and their relationships,
-so that I can explore cross-document traceability visually and jump directly to any document section from the graph.
-
-## Acceptance Criteria
-
-1. **Given** `knowledge-graph.html` is opened in a browser or VSCode webview
-   **When** the graph renders
-   **Then** each node appears as a circle color-coded by document type:
-   - `prd` → blue
-   - `architecture` → orange
-   - `epic` → green
-   - `story` → teal
-   - `decision` → purple
-   - `validation` → red
-   **And** directed edges are rendered as arrows with the edge type as a label
-   **And** the initial render completes within 3 seconds for graphs up to 500 nodes and 1000 edges (NFR38)
-
-2. **Given** the user clicks a node
-   **When** the click handler fires
-   **Then** the node's source document opens at the specific heading anchor via the IDE's file protocol or a browser file URL
-   - For `relative_path` / `absolute_path` pointer types: construct `vscode://file/{absolute-path}#{anchor}` URI and navigate; fallback: display a copyable Markdown link `[title](file.md#anchor)`
-   - For `url` pointer type: open the registered URL in a new browser tab
-
-3. **Given** the user hovers over an edge
-   **When** the tooltip renders
-   **Then** it displays: edge type, label (if set), created_by, agent, created_at (FR155)
-
-4. **Given** the user selects a node
-   **When** the selection occurs
-   **Then** the immediate neighbors (one hop in either direction) are highlighted
-   **And** non-neighbor nodes and edges are dimmed (FR156)
-
-5. **Given** the user uses the filter controls
-   **When** a node type or edge type is deselected
-   **Then** nodes and edges of that type are hidden from the visualization
-   **And** re-selecting them restores visibility (FR156)
-
-6. **Given** the HTML file is opened in an air-gapped environment with no network access
-   **When** the page loads
-   **Then** the graph renders identically to a connected environment — no CDN requests, no external fonts, no script fetches (FR157, NFR41)
-
-## Tasks / Subtasks
-
-### Task 1: Replace `generate-html.js` placeholder with full renderer generator (AC: 1–6)
-
-Story 19.5 created `lib/bmad-extension/skills/open-graph/generate-html.js` as a placeholder. This story replaces it with the full implementation. **Interface is unchanged:** `node generate-html.js <jsonPath> <htmlPath>`.
-
-- [ ] 1.1 Read the existing placeholder at `lib/bmad-extension/skills/open-graph/generate-html.js`
-- [ ] 1.2 Overwrite with the full renderer generator script:
-  - Read `knowledge-graph.json` from `<jsonPath>`
-  - Generate the complete self-contained HTML with:
-    - All CSS inlined in `<style>` block
-    - Graph data embedded as `const GRAPH_DATA = <JSON literal>;`
-    - All JS inlined in `<script>` block
-  - Write complete HTML to `<htmlPath>`
-
-### Task 2: Implement SVG-based force-directed layout (AC: 1, 4 — performance/NFR38)
-
-- [ ] 2.1 Implement force-directed simulation in vanilla JS (NO external libraries, NO bundler):
-  - **Coulomb repulsion:** each pair of nodes repels with force ∝ 1/distance²
-  - **Spring attraction:** edges attract connected nodes with Hooke's law spring force
-  - **Pre-compute first 100 ticks** at HTML generation time in `generate-html.js` — embed final positions as `cx`, `cy` attributes in the generated HTML (no startup animation jitter, renders immediately)
-- [ ] 2.2 Node rendering: SVG `<circle>` elements, radius 12px, color from the node `type` field (see color map in AC1), with `<text>` label below
-- [ ] 2.3 Edge rendering: SVG `<line>` elements with arrowhead markers (`<marker>` element), edge type label as SVG `<text>` at midpoint
-- [ ] 2.4 Performance target: 500 nodes / 1000 edges render to first interactive frame in ≤3 seconds. Pre-computed layout achieves this by eliminating runtime physics startup.
-
-### Task 3: Implement node click-to-navigate (AC: 2)
-
-- [ ] 3.1 On node click, look up `files[node.file]` to get pointer and pointer_type
-- [ ] 3.2 For `relative_path`: construct path relative to HTML file location; try `vscode://file/<absolute-path>#<anchor>` first; fallback to showing a copyable `[title](file.md#anchor)` link in a panel
-- [ ] 3.3 For `absolute_path`: use the absolute path directly
-- [ ] 3.4 For `url`: `window.open(files[node.file].pointer + '#' + node.anchor, '_blank')`
-
-### Task 4: Implement edge tooltip (AC: 3)
-
-- [ ] 4.1 On `mouseover` of edge line, show a floating `<div id="tooltip">` with:
-  ```
-  Type: <edge.type>
-  Label: <edge.label || "—">
-  Created by: <edge.created_by>
-  Agent: <edge.agent>
-  Date: <edge.created_at formatted as YYYY-MM-DD HH:MM>
-  ```
-- [ ] 4.2 Position tooltip near the cursor (mouse position + offset)
-- [ ] 4.3 On `mouseout`, hide the tooltip
-
-### Task 5: Implement neighbor highlight and filter controls (AC: 4, 5)
-
-- [ ] 5.1 **Neighbor highlight on node select:**
-  - On node click/select: build forward + backward adjacency sets for the selected node
-  - Highlight selected node (brighter fill) and all directly connected nodes (slightly brighter)
-  - Dim all other nodes and edges (opacity: 0.1)
-  - Click on background to deselect and restore full opacity
-  - Implementation: CSS class toggle on SVG elements; no re-layout needed
-
-- [ ] 5.2 **Filter checkboxes:**
-  - Create `<div id="controls">` above the SVG canvas with:
-    - One checkbox per node type (prd, architecture, epic, story, decision, validation)
-    - One checkbox per edge type (implements, derives-from, traces-to, informed-by, validates, refines)
-  - On checkbox toggle: use CSS `display: none` to hide/show matching elements — no re-layout
-  - All checkboxes checked by default (all visible)
-
-### Task 6: Verify self-containment (AC: 6)
-
-- [ ] 6.1 Open the generated HTML in a browser with network connectivity disabled (Chrome DevTools → Network → Offline)
-- [ ] 6.2 Verify the graph renders identically
-- [ ] 6.3 Confirm no CDN requests appear in the Network tab
-- [ ] 6.4 Search the generated HTML for `http://`, `https://`, `<script src`, `<link href` — none should be present
-
-## Dev Notes
-
-### CRITICAL: This Story Replaces a Placeholder (Story 19.5)
-
-Story 19.5 created `lib/bmad-extension/skills/open-graph/generate-html.js` as a placeholder diagnostic page. This story **replaces** that file with the full renderer. The interface is unchanged:
-```
-node lib/bmad-extension/skills/open-graph/generate-html.js <jsonPath> <htmlPath>
-```
-
-### No External Libraries — Vanilla JS Only (FR157, NFR41)
-
-This is a hard constraint from the architecture. Do NOT use:
-- D3.js (even inlined)
-- React, Vue, or any framework
-- Any `import` or `require` for third-party packages
-- CDN scripts or stylesheets
-
-The renderer must be approximately 300–500 lines of vanilla JS. If it grows larger, review for verbosity.
-
-### Pre-Computed Layout (NFR38 Performance)
-
-The key to achieving ≤3 second initial render for 500 nodes / 1000 edges is **pre-computing the layout at generation time** in `generate-html.js`. The force simulation runs server-side (Node.js) and final positions are baked into the HTML. The browser only renders — no physics calculation at runtime.
-
-Implementation strategy in `generate-html.js`:
-1. Build adjacency graph from `GRAPH_DATA.edges`
-2. Initialize node positions randomly
-3. Run force simulation loop for 100 iterations
-4. Embed final `{ id, cx, cy }` positions in the HTML as a separate `const POSITIONS = [...]` literal
-
-### HTML Structure (Architecture-Authoritative)
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <meta charset="utf-8">
-  <title>Knowledge Graph — {project}</title>
-  <style>/* all CSS inlined — no external stylesheets */</style>
-</head>
-<body>
-  <div id="controls"><!-- filter checkboxes --></div>
-  <svg id="graph" width="100%" height="90vh">
-    <!-- nodes and edges rendered here as SVG elements -->
-  </svg>
-  <div id="tooltip" style="display:none; position:fixed"><!-- edge hover panel --></div>
-  <script>
-    const GRAPH_DATA = /* full JSON embedded at generation time */;
-    const POSITIONS = /* pre-computed layout positions */;
-    /* all rendering, interaction, and filter logic inlined */
-  </script>
-</body>
-</html>
-```
-
-### Node Color Map
-
-| Node type | Color |
-|-----------|-------|
-| `prd` | `#4A90D9` (blue) |
-| `architecture` | `#E8A838` (orange) |
-| `epic` | `#5CB85C` (green) |
-| `story` | `#5BC0DE` (teal) |
-| `decision` | `#9B59B6` (purple) |
-| `validation` | `#E74C3C` (red) |
-| (unknown) | `#95A5A6` (gray — fallback) |
-
-Note: architecture.md specifies `requirement=blue, architecture=orange, epic=purple, story=green, design=teal, test=red`. The epics.md specifies `prd=blue, architecture=orange, epic=green, story=teal, decision=purple, validation=red`. Use the epics.md definitions (they are more specific to actual node types emitted). The color map above reflects this.
-
-### SVG Arrowhead Marker
-
-Standard SVG `<defs>` marker for directed edges:
-```svg
-<defs>
-  <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="10" refY="3.5" orient="auto">
-    <polygon points="0 0, 10 3.5, 0 7" fill="#666" />
-  </marker>
-</defs>
-```
-Apply with `marker-end="url(#arrowhead)"` on edge `<line>` elements.
-
-### Bidirectional Adjacency Map
-
-Build in-browser at render time (from GRAPH_DATA):
-```javascript
-const forward = {};  // nodeId → [nodeId, ...]
-const backward = {}; // nodeId → [nodeId, ...]
-GRAPH_DATA.edges.forEach(e => {
-  (forward[e.from] = forward[e.from] || []).push(e.to);
-  (backward[e.to] = backward[e.to] || []).push(e.from);
-});
-```
-Used for neighbor highlight (AC: 4). NFR38 / FR143 (bidirectional index).
-
-### CSS-Based Filtering (No Re-Layout)
-
-Filtering by type should use CSS class toggling for performance:
-```javascript
-// Add data-type attribute to each SVG element at render time
-// e.g., <circle data-node-type="prd" ...>
-// On filter toggle:
-document.querySelectorAll('[data-node-type="prd"]').forEach(el => {
-  el.style.display = checked ? '' : 'none';
-});
-```
-This avoids re-running the physics simulation or rebuilding the SVG on filter change.
-
-### File Only Changed by This Story
-
-```
-lib/
-└── bmad-extension/
-    └── skills/
-        └── open-graph/
-            └── generate-html.js    ← REPLACE placeholder with full renderer
-```
-
-No other files are created or modified by this story. The installer automatically picks up the updated file on next deployment.
-
-### Project Structure Notes
-
-- This story modifies exactly one file: `lib/bmad-extension/skills/open-graph/generate-html.js`
-- No new skill registration needed (registered in Story 19.5)
-- No module-help.csv changes
-
-### References
-
-- Architecture Decision P3-1 — Renderer features (FR154–FR157): `_bmad-output/planning-artifacts/architecture.md#renderer-features-fr154fr156`
-- Architecture Decision P3-1 — Performance contract (NFR38): `_bmad-output/planning-artifacts/architecture.md#performance-contract-nfr38`
-- Story 19.5: `_bmad-output/implementation-artifacts/19-5-open-graph-skill.md` — creates the placeholder
-- FRs: FR154 (interactive viz, node navigation), FR155 (edge tooltip), FR156 (filtering, neighbor highlight), FR157 (no external dependencies)
-- NFRs: NFR38 (≤3s for 500/1000), NFR41 (air-gapped)
-
-## Dev Agent Record
-
-### Agent Model Used
-
-_to be filled by dev agent_
-
-### Debug Log References
-
-### Completion Notes List
-
-### File List