ma-agents 3.4.9 → 3.5.1

package/_bmad-output/implementation-artifacts/19-1-knowledge-graph-core-library.md

@@ -0,0 +1,239 @@
+# Story 19.1: Knowledge Graph Core Library (`emitToGraph`)
+
+Status: ready-for-dev
+
+## Story
+
+As a **Chief Architect**,
+I want a shared `emitToGraph()` utility function in the BMAD extension module,
+so that all BMAD skills can emit nodes and edges to the knowledge graph using a single consistent API without duplicating file I/O logic.
+
+## Acceptance Criteria
+
+1. **Given** the function `emitToGraph(projectRoot, emission)` is called with a valid emission payload
+   **When** `_bmad-output/knowledge-graph.json` does not yet exist
+   **Then** the function creates the file with a valid four-section structure: `meta`, `files`, `nodes`, `edges`
+   **And** `meta` contains `schema_version: "1.0"`, `generated_at` (ISO timestamp), `project` (derived from package.json name or directory name), `file_count: 0`, `node_count: 0`, `edge_count: 0`
+   **And** `files`, `nodes`, `edges` are initialized as empty object, empty array, empty array respectively
+
+2. **Given** `knowledge-graph.json` already exists with prior content
+   **When** `emitToGraph()` is called
+   **Then** it reads the existing file, appends new files/nodes/edges, updates counts in `meta`, and writes the result back atomically
+   **And** no existing nodes, edges, or file registrations are deleted or overwritten
+
+3. **Given** an emission payload includes a `files` entry with `pointer_type: "relative_path"`
+   **When** that file-id does not yet exist in the `files` table
+   **Then** the file is registered: `files[file-id] = { pointer, title, pointer_type }`
+   **And** if the file-id already exists, registration is skipped (first-write-wins)
+
+4. **Given** an emission payload includes a node with id `file-id#heading-anchor`
+   **When** a node with that id already exists in `nodes`
+   **Then** the node is not duplicated (title update is allowed; all other fields preserved)
+
+5. **Given** an emission payload includes an edge with `(from, to, type)` triple
+   **When** an edge with the same `(from, to, type)` already exists in `edges`
+   **Then** the edge is not duplicated (provenance of the first edge is preserved; `created_at`/`agent` fields may be updated)
+
+6. **Given** the function writes the updated graph
+   **When** the write operation completes
+   **Then** `meta.file_count`, `meta.node_count`, `meta.edge_count` reflect the total counts in the file
+   **And** `meta.last_updated` is set to the current ISO-8601 timestamp
+
+## Tasks / Subtasks
+
+### Task 1: Create the `lib/knowledge-graph/` module (AC: 1, 2, 3, 4, 5, 6)
+
+- [ ] 1.1 Create directory `lib/knowledge-graph/`
+- [ ] 1.2 Create `lib/knowledge-graph/emit.js` implementing `emitToGraph(projectRoot, emission)`:
+  - Initialize graph if `knowledge-graph.json` does not exist: `{ meta: initMeta(projectRoot), files: {}, nodes: [], edges: [] }`
+  - Read and parse existing JSON if file exists
+  - Apply emission: register files (first-write-wins), add nodes (no duplicate by `id`; title update allowed), add edges (no duplicate by `from+to+type`; created_at/agent update allowed)
+  - Update `meta.file_count`, `meta.node_count`, `meta.edge_count`, `meta.last_updated`
+  - Write result as `JSON.stringify(graph, null, 2)` to `path.join(projectRoot, '_bmad-output', 'knowledge-graph.json')`
+  - Use synchronous I/O: `fs.existsSync`, `fs.readFileSync`, `fs.writeFileSync`
+- [ ] 1.3 Implement `initMeta(projectRoot)` helper:
+  - Reads `package.json` name if present at `projectRoot`; falls back to `path.basename(projectRoot)`
+  - Returns `{ schema_version: "1.0", project: <name>, generated_at: <ISO>, last_updated: <ISO>, file_count: 0, node_count: 0, edge_count: 0 }`
+- [ ] 1.4 Implement and export `headingToAnchor(heading)` utility function (used by all emitting skills):
+  ```javascript
+  function headingToAnchor(heading) {
+    return heading
+      .toLowerCase()
+      .replace(/[^\w\s-]/g, '')
+      .replace(/\s+/g, '-')
+      .replace(/-+/g, '-')
+      .trim();
+  }
+  ```
+- [ ] 1.5 Export both functions: `module.exports = { emitToGraph, headingToAnchor }`
+
+### Task 2: Verify the emission data contract (AC: 1–6)
+
+- [ ] 2.1 Manually verify (or write a quick smoke test in `tests/knowledge-graph/smoke.test.js`) that:
+  - First call creates a valid JSON file with the four sections
+  - Second call with the same payload is idempotent (counts unchanged)
+  - Second call with new nodes/edges appends correctly
+  - Counts in `meta` always match actual array/object sizes
+
+### Task 3: Verify module is importable by other skills (AC: none — integration readiness)
+
+- [ ] 3.1 Confirm the module path `../../lib/knowledge-graph/emit.js` (relative from a skill like `lib/bmad-extension/skills/open-graph/`) resolves correctly
+- [ ] 3.2 Confirm no circular dependencies are introduced
+
+## Dev Notes
+
+### CRITICAL: Two Deployment Pipelines — Where This Module Lives
+
+This story creates a **shared utility module** in `lib/knowledge-graph/`, NOT a skill. It is NOT deployed by the installer and NOT a BMAD extension skill. It is a Node.js module imported by other skills at runtime.
+
+**Module location:** `lib/knowledge-graph/emit.js`
+**Imported by:** All 7 emitting skills (Stories 19.2–19.4 wire them in)
+
+### Graph File Location
+
+Always: `path.join(projectRoot, '_bmad-output', 'knowledge-graph.json')`
+
+The `projectRoot` parameter is passed by each skill. Skills can derive `projectRoot` from their own `__dirname` by traversing up to the repo root, or from the BMAD config `_bmad/bmm/config.yaml`.
+
+### JSON Schema — Four-Section Structure
+
+```json
+{
+  "meta": {
+    "schema_version": "1.0",
+    "project": "<name>",
+    "generated_at": "<ISO>",
+    "last_updated": "<ISO>",
+    "file_count": 4,
+    "node_count": 127,
+    "edge_count": 89
+  },
+  "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-p3-1-bmad-knowledge-graph",
+      "to": "prd#functional-requirements",
+      "type": "implements",
+      "label": "implements knowledge graph data model requirement",
+      "created_by": "Alon",
+      "agent": "claude-code",
+      "created_at": "2026-04-07T10:00:00Z"
+    }
+  ]
+}
+```
+
+### Heading Anchor Algorithm
+
+GitHub slug algorithm (same as VSCode internal link resolution):
+```javascript
+heading.toLowerCase().replace(/[^\w\s-]/g, '').replace(/\s+/g, '-').replace(/-+/g, '-').trim()
+```
+Example: `"Decision P3-1: BMAD Knowledge Graph"` → `"decision-p3-1-bmad-knowledge-graph"`
+
+### emitToGraph() Pseudocode (Architecture-Authoritative)
+
+```javascript
+async function emitToGraph(projectRoot, emission) {
+  const graphPath = path.join(projectRoot, '_bmad-output', 'knowledge-graph.json');
+  const graph = fs.existsSync(graphPath)
+    ? JSON.parse(fs.readFileSync(graphPath, 'utf8'))
+    : { meta: initMeta(projectRoot), files: {}, nodes: [], edges: [] };
+
+  // Register files (first-write-wins for pointer_type; pointer/title always update)
+  for (const [fileId, fileEntry] of Object.entries(emission.files || {})) {
+    if (!graph.files[fileId]) graph.files[fileId] = fileEntry;
+    else { graph.files[fileId].pointer = fileEntry.pointer; graph.files[fileId].title = fileEntry.title; }
+  }
+  // Add nodes (no duplicates by id; title update allowed)
+  for (const node of (emission.nodes || [])) {
+    const existing = graph.nodes.find(n => n.id === node.id);
+    if (!existing) graph.nodes.push(node);
+    else existing.title = node.title;
+  }
+  // Add edges (no duplicates by from+to+type; created_at/agent update allowed)
+  for (const edge of (emission.edges || [])) {
+    const existing = graph.edges.find(e => e.from === edge.from && e.to === edge.to && e.type === edge.type);
+    if (!existing) graph.edges.push(edge);
+    else { existing.created_at = edge.created_at; existing.agent = edge.agent; }
+  }
+  // Update counts
+  graph.meta.file_count = Object.keys(graph.files).length;
+  graph.meta.node_count = graph.nodes.length;
+  graph.meta.edge_count = graph.edges.length;
+  graph.meta.last_updated = new Date().toISOString();
+
+  fs.writeFileSync(graphPath, JSON.stringify(graph, null, 2), 'utf8');
+}
+```
+
+### I/O Choice: Synchronous
+
+Use synchronous `fs` APIs (`readFileSync`, `writeFileSync`, `existsSync`). Graph updates occur as a post-artifact step — not in any hot path. Synchronous I/O is simpler and avoids async coordination between concurrent skill calls (not a concern since skills run sequentially under a single agent session).
+
+### Edge Type Vocabulary
+
+| Type | Usage |
+|------|-------|
+| `implements` | arch decision → PRD requirement |
+| `derives-from` | epic → PRD requirement |
+| `traces-to` | story → epic |
+| `informed-by` | any cross-document influence (non-hierarchical) |
+| `validates` | review/validation report → artifact |
+| `refines` | dev-story implementation notes → story spec |
+
+### LLM-Writability Contract (NFR39)
+
+The flat structure is deliberately copy-pattern-friendly. A model with no prior schema knowledge can correctly extend the graph by observing the first entry in `files`, `nodes`, and `edges` and copying the pattern. Do NOT add nesting beyond 2 levels. Do NOT introduce computed or derived fields inside the JSON.
+
+### File Structure Reference
+
+```
+lib/
+└── knowledge-graph/
+    └── emit.js    ← NEW: emitToGraph() + headingToAnchor() exports
+```
+
+### Dependencies
+
+No new npm packages required. Uses only Node.js built-ins: `fs`, `path`.
+
+### Project Structure Notes
+
+- `lib/knowledge-graph/` is a new directory under `lib/` alongside `lib/bmad-extension/`, `lib/installer.js`, etc.
+- This module is NOT registered in `module-help.csv` — it is a utility, not a skill.
+- No `skill.json`, no `SKILL.md` — plain Node.js module.
+
+### References
+
+- Architecture Decision P3-1: `_bmad-output/planning-artifacts/architecture.md#decision-p3-1-bmad-knowledge-graph`
+- FRs: FR141–FR148 — node/edge/file/meta schema definitions
+- NFR39 (LLM-writability), NFR40 (additive-only)
+- Downstream stories that wire in emission: 19.2, 19.3, 19.4 (require this module to exist first)
+
+## 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-2-graph-emission-create-prd.md

@@ -0,0 +1,171 @@
+# Story 19.2: Graph Emission — `create-prd` (Graph Seed)
+
+Status: ready-for-dev
+
+## Story
+
+As a **Product Manager**,
+I want the `create-prd` skill to automatically seed the knowledge graph when a PRD is generated,
+so that the PRD becomes the root of the project knowledge graph without any user action.
+
+## Acceptance Criteria
+
+1. **Given** the `create-prd` skill completes generation of `_bmad-output/planning-artifacts/prd.md`
+   **When** the artifact write step finishes
+   **Then** `emitToGraph()` is called silently as the final step — no user prompt, no output message
+   **And** the PRD file is registered in the `files` table as `{ pointer: "_bmad-output/planning-artifacts/prd.md", title: "Product Requirements Document", pointer_type: "relative_path" }` with file-id `prd`
+
+2. **Given** the PRD contains top-level `##` headings (e.g., `## Executive Summary`, `## Functional Requirements`)
+   **When** emission runs
+   **Then** one node is emitted per `##` heading: `{ id: "prd#<anchor>", file: "prd", anchor: "<anchor>", title: "<heading text>", type: "prd" }`
+
+3. **Given** the graph is seeded from a new PRD
+   **When** the `knowledge-graph.json` file is inspected
+   **Then** it contains no edges (PRD is the root — it does not reference other documents yet)
+   **And** `meta.node_count` equals the number of `##` headings in the PRD
+
+4. **Given** `create-prd` runs on a project where `knowledge-graph.json` already exists
+   **When** emission runs
+   **Then** only new headings (not yet present as nodes) are added — re-runs are idempotent
+
+## Tasks / Subtasks
+
+### Task 1: Add emission call to `create-prd` workflow (AC: 1, 2, 3, 4)
+
+**IMPORTANT:** The `create-prd` skill exists in TWO locations — IDE skill and BMAD extension skill (see Dev Notes). Both must be updated.
+
+- [ ] 1.1 Locate the IDE skill source: `skills/bmad-create-prd/SKILL.md`
+- [ ] 1.2 Locate the BMAD extension skill source: `lib/bmad-extension/skills/bmad-create-prd/SKILL.md`
+- [ ] 1.3 In both SKILL.md files, add a final step after the artifact write:
+  - **Step: Silent graph emission** (no user output)
+  - Scan the generated PRD markdown for `## ` lines (level-2 headings only)
+  - For each heading, derive anchor using `headingToAnchor()` from `lib/knowledge-graph/emit.js`
+  - Build emission payload:
+    ```javascript
+    const emission = {
+      files: {
+        prd: {
+          pointer: "_bmad-output/planning-artifacts/prd.md",
+          title: "Product Requirements Document",
+          pointer_type: "relative_path"
+        }
+      },
+      nodes: headings.map(h => ({
+        id: `prd#${headingToAnchor(h)}`,
+        file: "prd",
+        anchor: headingToAnchor(h),
+        title: h,
+        type: "prd"
+      })),
+      edges: []  // PRD seeding emits no edges — it is the root
+    };
+    ```
+  - Call `emitToGraph(projectRoot, emission)` silently (no output to user)
+- [ ] 1.4 Determine `projectRoot` in each skill context:
+  - For BMAD extension skill: derive from `_bmad/bmm/config.yaml` path or `process.cwd()`
+  - For IDE skill: use `process.cwd()` (the project root where the skill is invoked)
+
+### Task 2: Verify idempotency (AC: 4)
+
+- [ ] 2.1 After implementing, manually verify that invoking `create-prd` twice on the same project results in the same node count (no duplicates)
+- [ ] 2.2 Confirm `meta.node_count` equals the actual number of nodes in the `nodes` array
+
+### Task 3: Verify emission is truly silent (AC: 1)
+
+- [ ] 3.1 Confirm no `console.log`, no output to user, no prompt is added for the emission step
+- [ ] 3.2 Confirm error from `emitToGraph()` (e.g., write permission failure) does not propagate to the user as a skill failure — log to stderr at most, do not abort the skill
+
+## Dev Notes
+
+### CRITICAL: Two Deployment Pipelines
+
+The `create-prd` skill (like all BMAD skills in this project) exists in two locations:
+1. **IDE skill source:** `skills/bmad-create-prd/SKILL.md` — deployed by `lib/installer.js` to all IDE agent directories
+2. **BMAD extension skill source:** `lib/bmad-extension/skills/bmad-create-prd/SKILL.md` — deployed by `lib/bmad.js` to `_bmad/extensions/ma-agents-skills/`
+
+**Both files must be updated.** Do NOT edit installed copies at `.claude/skills/bmad-create-prd/` or `_bmad/extensions/ma-agents-skills/skills/bmad-create-prd/`.
+
+### Prerequisite: Story 19.1 Must Be Complete
+
+This story requires `lib/knowledge-graph/emit.js` to exist (created in Story 19.1). Do NOT begin implementation until Story 19.1 is done.
+
+### Heading Extraction — Level-2 Only
+
+Extract only `## ` (two hashes + space) headings from the PRD. Level-3+ headings (`###`, `####`) create noise without adding navigation value. The regex pattern:
+```javascript
+const headings = content.match(/^## (.+)$/gm)?.map(line => line.replace(/^## /, '')) || [];
+```
+
+### PRD is the Only Emission With Zero Edges
+
+This is the only skill in the 7-skill emission chain that emits zero edges. All other skills emit edges pointing back to PRD nodes. The knowledge graph is a directed graph rooted at the PRD.
+
+### Emission Payload Shape
+
+```javascript
+{
+  files: {
+    "prd": { pointer: "_bmad-output/planning-artifacts/prd.md", title: "Product Requirements Document", pointer_type: "relative_path" }
+  },
+  nodes: [
+    { id: "prd#executive-summary", file: "prd", anchor: "executive-summary", title: "Executive Summary", type: "prd" },
+    { id: "prd#functional-requirements", file: "prd", anchor: "functional-requirements", title: "Functional Requirements", type: "prd" }
+    // ... one per ## heading
+  ],
+  edges: []
+}
+```
+
+### Silent Emission Contract
+
+The emission step MUST be silent:
+- No output to user (no `console.log`, no markdown output in SKILL.md steps)
+- Emission failures (e.g., disk write error) must NOT abort the skill — the PRD is already written; a graph update failure is non-critical
+- Wrap the `emitToGraph()` call in try/catch; log to stderr on failure, do not re-throw
+
+### Idempotency
+
+The `emitToGraph()` function from Story 19.1 already handles idempotency (no duplicate nodes by id). However, the skill must also ensure it does not re-extract headings if the PRD content is the same. Since `emitToGraph` is idempotent, calling it twice with the same payload is always safe.
+
+### File Structure Reference
+
+```
+skills/
+└── bmad-create-prd/
+    └── SKILL.md    ← MODIFY: add emission step at end
+
+lib/
+└── bmad-extension/
+    └── skills/
+        └── bmad-create-prd/
+            └── SKILL.md    ← MODIFY: add emission step at end
+
+lib/
+└── knowledge-graph/
+    └── emit.js    ← IMPORT from here (Story 19.1 output)
+```
+
+### Project Structure Notes
+
+- No new files are created by this story — only modifications to existing SKILL.md files.
+- The `lib/knowledge-graph/emit.js` module (Story 19.1) must be importable from both SKILL.md contexts.
+- For BMAD extension skills (SKILL.md workflow files): the emission call is expressed as a workflow instruction in markdown, not literal JavaScript. The dev agent executes the instruction. The `lib/knowledge-graph/emit.js` code is what actually runs when a JavaScript execution context is available. In pure markdown SKILL.md context (no JS runtime), document the emission payload and call as a clear instruction.
+
+### References
+
+- Story 19.1: `_bmad-output/implementation-artifacts/19-1-knowledge-graph-core-library.md` — `emitToGraph()` implementation
+- Architecture Decision P3-1: `_bmad-output/planning-artifacts/architecture.md#decision-p3-1-bmad-knowledge-graph`
+- Epics source: `_bmad-output/planning-artifacts/epics.md#story-192-graph-emission--create-prd-graph-seed`
+- FRs: FR149 (automatic emission), FR150 (file registration), FR152 (additive-only, no duplicates)
+
+## 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-3-graph-emission-create-architecture-epics.md

@@ -0,0 +1,179 @@
+# Story 19.3: Graph Emission — `create-architecture` and `create-epics-and-stories`
+
+Status: ready-for-dev
+
+## Story
+
+As a **Chief Architect** and **Product Manager**,
+I want the `create-architecture` and `create-epics-and-stories` skills to emit traceability edges to the knowledge graph automatically,
+so that every architectural decision and every epic traces back to the PRD sections that motivated it.
+
+## Acceptance Criteria
+
+1. **Given** the `create-architecture` skill completes generation of `_bmad-output/planning-artifacts/architecture.md`
+   **When** emission runs
+   **Then** the architecture file is registered as file-id `arch` with `pointer_type: "relative_path"`
+   **And** one node is emitted per `##` heading in architecture.md (type: `architecture`)
+   **And** for each architecture decision section (headings matching `## Decision` or `## P[0-9]` patterns), an `implements` edge is emitted: `{ from: "arch#<decision-slug>", to: "prd#relevant-fr-section", type: "implements", label: "implements PRD requirement", created_by: <user>, agent: <agent-id>, created_at: <timestamp> }`
+
+2. **Given** the `create-architecture` skill is run when PRD nodes do not yet exist in the graph
+   **When** an edge references a PRD node that is not yet in `nodes`
+   **Then** a stub node is emitted for the referenced PRD heading so the edge is not orphaned
+   **And** the stub node carries `type: "prd"` and the correct `file` and `anchor` fields
+
+3. **Given** the `create-epics-and-stories` skill completes updating `_bmad-output/planning-artifacts/epics.md`
+   **When** emission runs
+   **Then** the epics file is registered as file-id `epics` with `pointer_type: "relative_path"`
+   **And** one node is emitted per epic heading (type: `epic`) — headings matching `## Epic [0-9]+:` pattern
+   **And** for each epic, a `derives-from` edge is emitted to the PRD Functional Requirements node: `{ from: "epics#epic-N-name", to: "prd#functional-requirements", type: "derives-from", ... }`
+   **And** where an epic was informed by an architecture decision, an `informed-by` edge is also emitted: `{ from: "epics#epic-N-name", to: "arch#<decision-slug>", type: "informed-by", ... }`
+
+4. **Given** emission runs for `create-architecture` or `create-epics-and-stories`
+   **When** the same skill runs a second time (re-run)
+   **Then** all emissions are idempotent — no duplicate nodes or edges are added
+
+## Tasks / Subtasks
+
+### Task 1: Add emission to `create-architecture` (AC: 1, 2, 4)
+
+Both the IDE skill and BMAD extension skill must be updated (see Dev Notes on two pipelines).
+
+- [ ] 1.1 Locate: `skills/bmad-create-architecture/SKILL.md` and `lib/bmad-extension/skills/bmad-create-architecture/SKILL.md`
+- [ ] 1.2 Add final silent step after artifact write:
+  - Scan `architecture.md` for `## ` headings; derive anchors with `headingToAnchor()`
+  - Identify decision headings: match `^## Decision` or `^## P\d+-\d+` (e.g., `## P3-1: BMAD Knowledge Graph`)
+  - For each decision heading, infer the target PRD FR section. Strategy:
+    - If the decision section body contains explicit FR references (e.g., `FR141`), map to `prd#functional-requirements` (the broad FR section as the canonical target)
+    - If no explicit FR found, still emit to `prd#functional-requirements` as default
+  - Build emission: all architecture nodes + `implements` edges for decision nodes + stub PRD nodes if PRD nodes are absent
+- [ ] 1.3 Stub node format (when PRD node does not yet exist):
+  ```javascript
+  { id: "prd#functional-requirements", file: "prd", anchor: "functional-requirements", title: "Functional Requirements", type: "prd" }
+  ```
+- [ ] 1.4 Edge format for architecture decisions:
+  ```javascript
+  {
+    from: "arch#<decision-slug>",
+    to: "prd#functional-requirements",
+    type: "implements",
+    label: "implements PRD requirement",
+    created_by: "<user from config>",
+    agent: "bmad-create-architecture",
+    created_at: new Date().toISOString()
+  }
+  ```
+
+### Task 2: Add emission to `create-epics-and-stories` (AC: 3, 4)
+
+Both the IDE skill and BMAD extension skill must be updated.
+
+- [ ] 2.1 Locate: `skills/bmad-create-epics-and-stories/SKILL.md` and `lib/bmad-extension/skills/bmad-create-epics-and-stories/SKILL.md`
+- [ ] 2.2 Add final silent step after artifact write:
+  - Scan `epics.md` for epic headings matching `^## Epic [0-9]+:` pattern
+  - For each epic heading, derive anchor; emit node with `type: "epic"`
+  - Emit `derives-from` edge to `prd#functional-requirements` for each epic
+  - For epics that reference architecture decisions (scan epic body for `Decision P\d+-\d+` or `arch#` patterns), emit `informed-by` edges to the relevant `arch#<decision-slug>` node
+- [ ] 2.3 Edge formats:
+  ```javascript
+  // derives-from edge
+  { from: "epics#<epic-slug>", to: "prd#functional-requirements", type: "derives-from", label: "derives from PRD requirements", created_by: "<user>", agent: "bmad-create-epics-and-stories", created_at: <timestamp> }
+  // informed-by edge (only when architecture decision referenced in epic body)
+  { from: "epics#<epic-slug>", to: "arch#<decision-slug>", type: "informed-by", label: "informed by architecture decision", created_by: "<user>", agent: "bmad-create-epics-and-stories", created_at: <timestamp> }
+  ```
+
+### Task 3: Verify idempotency and stub node correctness (AC: 2, 4)
+
+- [ ] 3.1 Run emission twice; confirm node/edge counts are identical on both runs
+- [ ] 3.2 Verify stub PRD nodes created by this skill are accepted (not duplicated) when Story 19.2 later emits the real PRD nodes (they share the same `id`; `emitToGraph` deduplicates by id with title update allowed)
+
+## Dev Notes
+
+### CRITICAL: Two Deployment Pipelines
+
+Same constraint as Story 19.2. For each skill, 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.
+
+### Prerequisite: Story 19.1 Must Be Complete
+
+Requires `lib/knowledge-graph/emit.js`. Do not begin until Story 19.1 is done. Stories 19.2, 19.3, and 19.4 can proceed in parallel once 19.1 is done.
+
+### Decision Heading Detection
+
+The architecture document uses two patterns for decision headings:
+- `## Decision P3-1: BMAD Knowledge Graph` — matches `^## .*P\d+-\d+` or `^## Decision`
+- Both patterns should be detected for forward compatibility
+
+Current architecture decisions in the file:
+- `P2-1` through `P2-11`, `P3-1` — use pattern `## Decision P[0-9]+-[0-9]+:` or abbreviated `## P[0-9]+-[0-9]+:`
+
+Scan for both `^## Decision` and `^## P\d` to be safe.
+
+### Epic Heading Detection
+
+The epics file uses: `^## Epic [0-9]+:` (e.g., `## Epic 19: BMAD Knowledge Graph (Phase 3)`)
+
+For each matched heading, `headingToAnchor()` produces the node anchor:
+- `"Epic 19: BMAD Knowledge Graph (Phase 3)"` → `"epic-19-bmad-knowledge-graph-phase-3"`
+
+### Stub Nodes for Orphan Edge Prevention (AC: 2)
+
+When an `implements` or `informed-by` edge references a node that does not yet exist (e.g., PRD not yet emitted, or architecture not yet emitted), the emitting skill adds a stub node. The `emitToGraph()` function from Story 19.1 handles this naturally — just include the stub in the `nodes` array of the emission payload. If the real node is later emitted by its own skill, the `title` field is updated (Story 19.1 allows title updates on existing nodes).
+
+### `informed-by` Edge — The Non-Hierarchical Edge
+
+`informed-by` is the key non-hierarchical edge type. It records influence without asserting derivation or implementation. An epic can be simultaneously `derives-from` a PRD requirement AND `informed-by` an architecture decision — both edges are valid and coexist.
+
+Detection strategy for `informed-by` edges in epics:
+- Scan epic section body (from heading to next `##` heading) for architecture decision references
+- Patterns to match: `Decision P\d+-\d+`, `arch#`, or explicit architecture decision names
+
+### User Identity for Provenance
+
+Read `created_by` from BMAD config `_bmad/bmm/config.yaml` field `user_name`, or fall back to `"unknown"`. The `agent` field is a static string identifying the skill: `"bmad-create-architecture"` or `"bmad-create-epics-and-stories"`.
+
+### File Structure Reference
+
+```
+skills/
+├── bmad-create-architecture/
+│   └── SKILL.md    ← MODIFY
+└── bmad-create-epics-and-stories/
+    └── SKILL.md    ← MODIFY
+
+lib/bmad-extension/skills/
+├── bmad-create-architecture/
+│   └── SKILL.md    ← MODIFY
+└── bmad-create-epics-and-stories/
+    └── SKILL.md    ← MODIFY
+```
+
+No new files are created by this story.
+
+### Project Structure Notes
+
+- This story touches 4 SKILL.md files (2 skills × 2 pipelines).
+- No new skills, no new directories, no module-help.csv changes.
+- Emission logic added as a silent final step in each skill's workflow.
+
+### References
+
+- Story 19.1: `_bmad-output/implementation-artifacts/19-1-knowledge-graph-core-library.md`
+- Architecture Decision P3-1: `_bmad-output/planning-artifacts/architecture.md#decision-p3-1-bmad-knowledge-graph`
+- Skill emission table in architecture: architecture.md section "Skills that emit (and what they emit)"
+- FRs: FR149, FR150, FR151, FR152
+- Edge type vocabulary: `implements`, `derives-from`, `informed-by`
+
+## Dev Agent Record
+
+### Agent Model Used
+
+_to be filled by dev agent_
+
+### Debug Log References
+
+### Completion Notes List
+
+### File List