ma-agents 3.5.0 → 3.5.2

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

@@ -0,0 +1,259 @@
+# 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

package/_bmad-output/implementation-artifacts/19-7-llm-writability-validation-tests.md

@@ -0,0 +1,280 @@
+# Story 19.7: LLM-Writability Contract Validation and Integration Tests
+
+Status: ready-for-dev
+
+## Story
+
+As a **Chief Architect**,
+I want the knowledge graph JSON format validated against the LLM-writability contract and covered by integration tests,
+so that we can verify that any LLM can extend the graph by copying existing patterns, and that the additive-only semantics are enforced.
+
+## Acceptance Criteria
+
+1. **Given** a `knowledge-graph.json` file with one existing node and one existing edge
+   **When** an LLM is instructed to add a new node and a new edge by copying the existing patterns (no external schema provided)
+   **Then** the resulting JSON is valid and passes `emitToGraph()` ingestion without errors
+   **And** the existing node and edge are preserved unchanged (NFR40)
+
+2. **Given** `emitToGraph()` is called with a node id that already exists in `nodes`
+   **When** the function completes
+   **Then** `nodes` contains exactly one entry with that id (no duplicate)
+   **And** the original node's fields are unchanged (except `title` which may be updated)
+
+3. **Given** `emitToGraph()` is called with an edge `(from, to, type)` triple that already exists
+   **When** the function completes
+   **Then** `edges` contains exactly one entry with that triple (no duplicate)
+   **And** the original edge's provenance (created_by, agent) is unchanged
+
+4. **Given** a graph with 500 nodes and 1000 edges
+   **When** `emitToGraph()` adds one new node and one new edge
+   **Then** the operation completes in under 1 second
+
+5. **Given** the full emission sequence is run (all 7 skills emit in order)
+   **When** the resulting `knowledge-graph.json` is inspected
+   **Then** all emitted nodes are present
+   **And** all emitted edges are present with correct provenance
+   **And** `meta.file_count`, `meta.node_count`, `meta.edge_count` are accurate
+
+## Tasks / Subtasks
+
+### Task 1: Set up test directory structure (AC: 1–5)
+
+Story 19.7 integration tests follow the existing Node.js test runner pattern. Epic 7 (Test Suite) is on hold, so these tests use the existing Node.js test runner directly (no Jest, no Vitest — plain Node.js `assert` and test runner, or whichever lightweight pattern is already in use in the repo).
+
+- [ ] 1.1 Create directory `tests/knowledge-graph/`
+- [ ] 1.2 Create `tests/knowledge-graph/fixtures/` for test fixture files
+- [ ] 1.3 Check existing test files in the repo (e.g., `tests/` root) to identify the test runner pattern in use — do NOT introduce a new test framework; replicate the existing pattern exactly
+
+### Task 2: Test — additive-only semantics (AC: 1, 2, 3)
+
+- [ ] 2.1 Create `tests/knowledge-graph/emit.test.js`:
+  - **Test: first call creates valid structure**
+    - Use a temp directory; call `emitToGraph(tmpDir, minimalPayload)`
+    - Verify file is created, has `meta`, `files`, `nodes`, `edges` sections
+    - Verify `meta.node_count` and `meta.edge_count` match array lengths
+
+  - **Test: duplicate node is rejected (AC: 2)**
+    - Seed graph with node `{ id: "prd#test", ... }`
+    - Call `emitToGraph()` again with the same node id but different title
+    - Verify `nodes` has exactly 1 entry with that id
+    - Verify title is updated (expected behavior per Story 19.1: title updates are allowed)
+
+  - **Test: duplicate edge is rejected (AC: 3)**
+    - Seed graph with edge `{ from: "prd#a", to: "prd#b", type: "implements", created_by: "original", ... }`
+    - Call `emitToGraph()` again with same `(from, to, type)` but different `created_by`
+    - Verify `edges` has exactly 1 entry with that triple
+    - Verify `created_by` is unchanged (provenance preserved — only `created_at`/`agent` can update)
+
+  - **Test: existing entries preserved (AC: 1, 2, 3 — NFR40)**
+    - Seed graph with 3 nodes and 2 edges
+    - Call `emitToGraph()` with 2 new nodes and 1 new edge
+    - Verify total: 5 nodes, 3 edges
+    - Verify all original entries are byte-identical to their initial values
+
+### Task 3: Test — LLM-writability contract (AC: 1)
+
+- [ ] 3.1 Create `tests/knowledge-graph/fixtures/llm-seed.json` — a minimal valid `knowledge-graph.json` with exactly 1 node and 1 edge (following the exact schema structure from `architecture.md` Decision P3-1)
+- [ ] 3.2 Create `tests/knowledge-graph/llm-writability.test.js`:
+  - **Test: copy-pattern extension produces valid JSON**
+    - Load `fixtures/llm-seed.json`
+    - Programmatically "extend" it by copying the pattern (add a new node entry and new edge entry following the exact same field structure)
+    - Write the extended JSON back to a temp file
+    - Call `emitToGraph(tmpDir, emptyEmission)` on the extended file — verify no errors thrown
+    - Verify total node/edge counts are correct
+  - **Test: valid structure can be round-tripped**
+    - Read `fixtures/llm-seed.json`, parse, serialize as `JSON.stringify(graph, null, 2)`, parse again — verify no data loss
+
+### Task 4: Test — performance (AC: 4)
+
+- [ ] 4.1 Add to `tests/knowledge-graph/emit.test.js`:
+  - **Test: large graph performance**
+    - Generate a fixture graph with 500 nodes and 1000 edges programmatically (use a helper function, not a fixture file — 500-node JSON fixture would be large)
+    - Write to temp dir
+    - Measure time of `emitToGraph()` adding 1 node and 1 edge
+    - Assert elapsed < 1000ms (using `Date.now()` before/after)
+
+### Task 5: Test — full emission sequence (AC: 5)
+
+- [ ] 5.1 Create `tests/knowledge-graph/sequence.test.js`:
+  - **Test: sequential emission produces correct final graph**
+    - Simulate the 7-skill emission sequence using `emitToGraph()` directly (no actual skills invoked — just the payloads each skill would emit)
+    - Use representative payloads:
+      1. PRD seeding: 3 PRD nodes, 0 edges
+      2. Architecture: 2 arch nodes, 2 `implements` edges to PRD nodes
+      3. Epics: 2 epic nodes, 2 `derives-from` edges + 1 `informed-by` edge
+      4. Story: 1 story node, 1 `traces-to` edge + 1 `informed-by` edge
+      5. Validate-prd: 1 validation node, 1 `validates` edge
+      6. Dev-story: 1 `refines` edge (story → arch)
+      7. Sprint-planning: 1 sprint node, 1 `derives-from` edge
+    - Verify final graph:
+      - `meta.node_count == 9` (3+2+2+1+1)
+      - `meta.edge_count == 8` (2+3+2+1+1) (approximately — adjust to actual test payload)
+      - All emitted nodes present
+      - All emitted edges present with correct provenance fields
+
+### Task 6: Test — VSCode detection (AC — Story 19.5)
+
+- [ ] 6.1 Create `tests/knowledge-graph/vscode-detection.test.js`:
+  - **Test: VSCODE_PID env var triggers VSCode path**
+    - Set `process.env.VSCODE_PID = "12345"` before running detection logic
+    - Verify detection returns `true`
+    - Restore `process.env` after test
+  - **Test: TERM_PROGRAM=vscode triggers VSCode path**
+    - Set `process.env.TERM_PROGRAM = "vscode"`
+    - Verify detection returns `true`
+  - **Test: neither env var set returns false**
+    - Ensure both env vars are unset; verify detection returns `false`
+  - Extract detection logic from `lib/bmad-extension/skills/open-graph/SKILL.md` into a testable helper function `lib/bmad-extension/skills/open-graph/detect-env.js`
+
+## Dev Notes
+
+### CRITICAL: Test Framework — Use Existing Pattern
+
+Epic 7 (Test Suite Foundation) is on hold. Do NOT introduce Jest, Vitest, Mocha, or any new test framework. Check if any test files already exist in `tests/` and replicate their exact pattern.
+
+If no test infrastructure exists: use Node.js built-in `node:test` module (available from Node.js 18+) and `node:assert`. This requires no npm installation.
+
+Pattern to check first:
+- Look for any `*.test.js` files in the repo
+- Look for `test` script in `package.json`
+
+### Prerequisite: All of Stories 19.1–19.6 Must Be Complete
+
+This story validates the complete Epic 19 implementation. It depends on:
+- `lib/knowledge-graph/emit.js` (Story 19.1)
+- `lib/bmad-extension/skills/open-graph/` (Stories 19.5, 19.6)
+
+### Test Directory Convention
+
+Tests live in `tests/knowledge-graph/` following the expectation from the Epic 19 cross-epic notes. Temp directories for all file I/O in tests:
+```javascript
+import { mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+let tmpDir;
+setup(() => { tmpDir = mkdtempSync(join(tmpdir(), 'kg-test-')); });
+teardown(() => { rmSync(tmpDir, { recursive: true, force: true }); });
+```
+
+### LLM-Writability Fixture (Task 3)
+
+The fixture `tests/knowledge-graph/fixtures/llm-seed.json` must be a minimal but complete example:
+```json
+{
+  "meta": {
+    "schema_version": "1.0",
+    "project": "test-project",
+    "generated_at": "2026-04-07T10:00:00Z",
+    "last_updated": "2026-04-07T10:00:00Z",
+    "file_count": 1,
+    "node_count": 1,
+    "edge_count": 1
+  },
+  "files": {
+    "prd": {
+      "pointer": "_bmad-output/planning-artifacts/prd.md",
+      "title": "Product Requirements Document",
+      "pointer_type": "relative_path"
+    }
+  },
+  "nodes": [
+    {
+      "id": "prd#functional-requirements",
+      "file": "prd",
+      "anchor": "functional-requirements",
+      "title": "Functional Requirements",
+      "type": "prd"
+    }
+  ],
+  "edges": [
+    {
+      "from": "arch#decision-test",
+      "to": "prd#functional-requirements",
+      "type": "implements",
+      "label": "implements requirement",
+      "created_by": "test-user",
+      "agent": "test-agent",
+      "created_at": "2026-04-07T10:00:00Z"
+    }
+  ]
+}
+```
+
+This fixture is intentionally minimal so that an LLM reading it has exactly one example to copy.
+
+### Performance Test Helper (Task 4)
+
+Generate the 500-node / 1000-edge test graph programmatically:
+```javascript
+function generateLargeGraph(nodeCount, edgeCount) {
+  const nodes = Array.from({ length: nodeCount }, (_, i) => ({
+    id: `prd#node-${i}`, file: 'prd', anchor: `node-${i}`, title: `Node ${i}`, type: 'prd'
+  }));
+  const edges = Array.from({ length: edgeCount }, (_, i) => ({
+    from: `prd#node-${i % nodeCount}`,
+    to: `prd#node-${(i + 1) % nodeCount}`,
+    type: 'implements',
+    label: `edge ${i}`,
+    created_by: 'test', agent: 'test', created_at: new Date().toISOString()
+  }));
+  // ... build and write graph to temp dir
+}
+```
+
+### `detect-env.js` Extraction (Task 6)
+
+The VSCode detection logic from SKILL.md should be extracted to a testable Node.js module:
+```javascript
+// lib/bmad-extension/skills/open-graph/detect-env.js
+function detectVSCode() {
+  return process.env.TERM_PROGRAM === 'vscode' || process.env.VSCODE_PID !== undefined;
+}
+module.exports = { detectVSCode };
+```
+
+This makes it importable by tests without executing the `execSync` open command.
+
+### File Structure Created by This Story
+
+```
+tests/
+└── knowledge-graph/
+    ├── fixtures/
+    │   └── llm-seed.json              ← NEW (LLM-writability test fixture)
+    ├── emit.test.js                   ← NEW (additive semantics + performance tests)
+    ├── llm-writability.test.js        ← NEW (copy-pattern extension tests)
+    ├── sequence.test.js               ← NEW (full emission sequence test)
+    └── vscode-detection.test.js       ← NEW (env var detection tests)
+
+lib/bmad-extension/skills/open-graph/
+└── detect-env.js                      ← NEW (extracted detection logic for testability)
+```
+
+### Project Structure Notes
+
+- No SKILL.md files modified by this story.
+- No new skills registered.
+- The `detect-env.js` extraction from Story 19.5's SKILL.md is a minor refactor to enable testability.
+- If no `tests/` directory exists, create it. Add a `test` script to `package.json` if one does not exist: `"test": "node --test tests/**/*.test.js"` (Node.js 18+ built-in runner).
+
+### References
+
+- Story 19.1: `_bmad-output/implementation-artifacts/19-1-knowledge-graph-core-library.md` — `emitToGraph()` behavior under test
+- Architecture LLM-writability contract: `_bmad-output/planning-artifacts/architecture.md#llm-writability-contract-nfr39`
+- Architecture additive-only semantics: `_bmad-output/planning-artifacts/architecture.md#nfr40-additive-only-emission`
+- Epics cross-epic notes on testing: `_bmad-output/planning-artifacts/epics.md#epic-19--cross-epic-notes`
+- NFRs: NFR39 (LLM-writability), NFR40 (additive-only)
+- FR: FR152 (no duplicates, provenance preservation)
+
+## 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/sprint-status.yaml

@@ -1,5 +1,5 @@
 # generated: 2026-03-15
-# updated: 2026-04-04 — Epic 17 code rolled back; all Phase 2 stories (17.10-17.24) rewritten and reset to ready-for-dev.
+# updated: 2026-04-07 — All Epic 17 stories (17.9-17.24) implemented and marked done. Epic 19 (BMAD Knowledge Graph) added to backlog.
 # project: agents
 # project_key: NOKEY
 # tracking_system: file-system
@@ -16,7 +16,7 @@
 # Old Epic 17 stories (17.1-17.8) archived; replaced by 17.9-17.24.
 
 generated: 2026-03-15
-last_updated: 2026-04-06
+last_updated: 2026-04-07 — Epic 19 stories (19.1-19.7) story files created, marked ready-for-dev
 project: agents
 project_key: NOKEY
 tracking_system: file-system
@@ -34,23 +34,23 @@ development_status:
   # Epic 17: Sprint Management Model Rework — Unified sprint-status.yaml
   # Redesigned 2026-04-03: 16 new stories (17.9-17.24) replacing old 17.1-17.8.
   # Execution order: 17.9 → 17.15 → 17.10 → 17.16 → 17.11 → 17.12 → 17.13 → 17.14 → 17.17 → 17.18 → 17.19 → 17.20 → 17.24 → 17.21 → 17.22 → 17.23
-  epic-17: in-progress
+  epic-17: done
   17-9-unified-sprint-status-schema: done
-  17-10-rework-generate-backlog: ready-for-dev
-  17-11-rework-add-to-sprint: ready-for-dev
-  17-12-rework-remove-from-sprint: ready-for-dev
-  17-13-rework-sprint-status-view: ready-for-dev
-  17-14-rework-cleanup-done: ready-for-dev
-  17-15-rework-bmad-sprint-planning: ready-for-dev
-  17-16-rework-add-sprint: ready-for-dev
-  17-17-rework-modify-sprint: ready-for-dev
-  17-18-rework-bmad-dev-story: ready-for-dev
-  17-19-rework-story-status-lookup: ready-for-dev
-  17-20-rework-bmad-sprint-status: ready-for-dev
-  17-21-new-close-sprint: ready-for-dev
-  17-22-jira-adapter-pattern: review
-  17-23-migration-deprecation-old-files: ready-for-dev
-  17-24-rework-prioritize-backlog: ready-for-dev
+  17-10-rework-generate-backlog: done
+  17-11-rework-add-to-sprint: done
+  17-12-rework-remove-from-sprint: done
+  17-13-rework-sprint-status-view: done
+  17-14-rework-cleanup-done: done
+  17-15-rework-bmad-sprint-planning: done
+  17-16-rework-add-sprint: done
+  17-17-rework-modify-sprint: done
+  17-18-rework-bmad-dev-story: done
+  17-19-rework-story-status-lookup: done
+  17-20-rework-bmad-sprint-status: done
+  17-21-new-close-sprint: done
+  17-22-jira-adapter-pattern: done
+  17-23-migration-deprecation-old-files: done
+  17-24-rework-prioritize-backlog: done
   epic-17-retrospective: optional
 
   # ─── ON HOLD ──────────────────────────────────────────────────────────────────
@@ -71,6 +71,19 @@ development_status:
 
   # ─── BACKLOG ──────────────────────────────────────────────────────────────────
 
+  # Epic 19: BMAD Knowledge Graph (Phase 3)
+  # Dependencies: Epic 15 (extension module structure), Epic 17 (sprint skill structure settled)
+  # Execution order: 19.1 → 19.2+19.3+19.4 (parallel) → 19.5 → 19.6 → 19.7
+  epic-19: in-progress
+  19-1-knowledge-graph-core-library: ready-for-dev
+  19-2-graph-emission-create-prd: ready-for-dev
+  19-3-graph-emission-create-architecture-epics: ready-for-dev
+  19-4-graph-emission-create-story-remaining: ready-for-dev
+  19-5-open-graph-skill: ready-for-dev
+  19-6-interactive-visualization-renderer: ready-for-dev
+  19-7-llm-writability-validation-tests: ready-for-dev
+  epic-19-retrospective: optional
+
   # Epic 14: External Tooling Integration
   # Dependencies: Epic 12, Epic 10, Epic 13 | Analyst + Architect required
   # Stories 14.4, 14.5 blocked on Story 14.3 architecture approval