ma-agents 3.5.0 → 3.5.2

package/_bmad-output/planning-artifacts/architecture.md

@@ -4,6 +4,9 @@ phase2StepsCompleted: ['step-02-context', 'step-04-decisions', 'step-05-patterns
 phase2CompletedAt: '2026-03-11'
 phase2cStepsCompleted: ['step-02-context', 'step-04-decisions', 'step-06-structure', 'step-07-validation', 'step-08-complete']
 phase2cCompletedAt: '2026-03-26'
+phase3EditHistory:
+  - date: '2026-04-07'
+    changes: 'Added Decision P3-1: BMAD Knowledge Graph (FR141-FR157, NFR38-NFR41). Three-layer design: (1) knowledge-graph.json with meta/files/nodes/edges structure — files table maps short file-ids to arbitrary pointers (relative path, absolute path, URL), nodes use file-id#anchor identity, edges carry 6 typed relationships including informed-by for non-hierarchical influence, full provenance (created_by, agent, created_at). (2) BMAD skill emission via read-modify-write emitToGraph() pattern — additive-only, 7 emitting skills tabulated with their edge types, heading-to-anchor slug algorithm documented, LLM-writability contract defined. (3) open-graph skill as new extension module skill — VSCode env detection, self-contained HTML renderer with inlined JS/CSS and embedded JSON data, SVG-based visualization, color-coded nodes, edge tooltips, filter controls, neighbor highlight, URL navigation for external files. Updated project structure tree (knowledge-graph.json/html in _bmad-output/, open-graph/ in extension module skills), skill count 44→45, requirements coverage tables, validation section.'
 phase2bEditHistory:
   - date: '2026-04-03'
     changes: 'Added P2-11: Unified Sprint-Status File Architecture — single sprint-status.yaml replaces 3-file model (backlog.yaml + sprints/sprint-N.yaml + sprint-status.yaml). Movement semantics, atomic operations, close-sprint lifecycle, done archival, Jira adapter pattern. Updated P2-5 to include close-sprint and remove-from-sprint workflows (6 extension workflows, up from 4). Updated extension module structure trees, skill counts (44, up from 42), project structure, FR coverage tables, and validation sections. Added prioritize-backlog to skill integration map (13 skills). Fixed FR count to 141. Fixed sprint-status.yaml canonical path to implementation-artifacts/. Marked P2-3 as superseded by P2-9.'
@@ -692,7 +695,7 @@ lib/bmad-extension/
         └── bmad-skill-manifest.yaml
 ```
 
-**Total skills in module:** 4 agents + 11 MIL-498 + 9 SRE + 6 DevOps + 8 Cyber + 6 extension workflows = **44 skills**
+**Total skills in module:** 4 agents + 11 MIL-498 + 9 SRE + 6 DevOps + 8 Cyber + 6 extension workflows + 1 open-graph = **45 skills**
 
 **`bmad-skill-manifest.yaml` patterns:**
 
@@ -1353,7 +1356,8 @@ ma-agents/
 │   │       ├── modify-sprint/               — update sprint metadata/items in unified file (FR70)
 │   │       ├── add-to-sprint/               — move items from backlog to sprint in unified file (FR69)
 │   │       ├── close-sprint/               — sprint close lifecycle: archive done, disposition remaining (P2-11)
-│   │       └── remove-from-sprint/         — move items from sprint back to backlog
+│   │       ├── remove-from-sprint/         — move items from sprint back to backlog
+│   │       └── open-graph/                 — generate knowledge-graph.html and open it (P3-1)
 │   └── bmad-customize/             — .customize.yaml for built-in BMM agents (deployed to _bmad/_config/agents/)
 │       ├── bmm-pm.customize.yaml            — critical_actions only
 │       ├── bmm-architect.customize.yaml
@@ -1388,6 +1392,8 @@ ma-agents/
 │   ├── implementation-artifacts/   — stories, specs
 │   │   ├── done/                   — archived done/canceled story files (P2-11 close-sprint)
 │   │   └── sprint-status.yaml      — unified sprint/backlog tracking (P2-11 — single source of truth)
+│   ├── knowledge-graph.json        — NEW: knowledge graph data (P3-1, version-controlled)
+│   └── knowledge-graph.html        — NEW: self-contained renderer (P3-1, generated by open-graph skill)
 │
 ├── docs/                           — generated project documentation
 │   ├── index.md                    — documentation master index
@@ -1504,6 +1510,7 @@ User Input → cli.js → installer.js → agents.js (path lookup) → file syst
 | Bug Management (FR60-64) | P2-5: extension workflow skill + `auto-bug-detection` skill | COVERED |
 | Sprint Management (FR65-71) | P2-5 + P2-11: 6 extension workflow skills (add/modify/add-to/remove-from/close sprint) operating on unified `sprint-status.yaml` | COVERED |
 | Agent Activity Dashboard (FR87-93) | Deferred to Phase 3 | N/A |
+| Knowledge Graph (FR141-157) | P3-1: JSON graph file, files table, skill emission, open-graph skill, self-contained renderer | COVERED |
 | Agent Conversion (FR94-97) | P2-9: agent skill folders with SKILL.md + bmad-skill-manifest.yaml | COVERED |
 | MIL-498 Workflow Conversion (FR98-100) | P2-9: Complex Workflow skills with prompts/ step files | COVERED |
 | SRE/DevOps/Cyber Conversion (FR101-103) | P2-9: skill packages with SKILL.md | COVERED |
@@ -1511,6 +1518,7 @@ User Input → cli.js → installer.js → agents.js (path lookup) → file syst
 | Upgrade Path (FR107-110) | P2-9: migration detection, backup, upgrade, merge, cleanup | COVERED |
 | Multi-Repo Layout (FR111-122) | P2-10: wizard, config, project-layout.yaml, path resolution | COVERED |
 | Bundled Install + Params (FR74-76, FR123-127) | P2-6 rev: buildBmadArgs(), explicit flags, --custom-content | COVERED |
+| Knowledge Graph (FR141-157) | P3-1: `lib/bmad-extension/skills/open-graph/`, `_bmad-output/knowledge-graph.json`, emitting BMAD skills | COVERED |
 | Developer Infrastructure (FR73) | Tests directory defined | COVERED |
 | Methodology Onboarding (FR72) | Bundled presentation deployment | COVERED |
 | Project Context (FR79-86) | P2-7: template-based generation, platform paths, critical_actions | COVERED |
@@ -1533,11 +1541,355 @@ User Input → cli.js → installer.js → agents.js (path lookup) → file syst
 | NFR32 (Output equivalence) | P2-9: same templates, same step files | COVERED |
 | NFR33 (Anti-zombie idempotency) | Depends on bmad-method setup skill behavior | MINOR GAP |
 | NFR34-37 (Multi-Repo) | P2-10: backward compat, air-gapped, deterministic, config-driven | COVERED |
+| NFR38-41 (Knowledge Graph) | P3-1: pre-computed layout + SVG, copy-pattern JSON, additive-only emission, inlined self-contained HTML | COVERED |
+
+### Decision P3-1: BMAD Knowledge Graph (FR141–FR157, NFR38–NFR41) (2026-04-07)
+
+**Decision:** Static JSON graph file with a central files table, BMAD-skill-side emission, and a self-contained HTML renderer delivered as a BMAD extension skill
+
+**Problem:** BMAD generates a rich chain of artifacts (PRD → Architecture → Epics → Stories) but the relationships between them exist only implicitly in document content. There is no machine-readable record of why a decision was made, what requirement drove an epic, or which UX design shaped an acceptance criterion. Existing solutions (traceability matrices, Jira links) are hierarchical, manually maintained, and opaque to agents. We need an any-to-any knowledge graph that:
+- Is built automatically as BMAD skills execute — no human curation
+- Supports non-hierarchical references (a story AC can reference the epic, an architecture section, and a UX design simultaneously)
+- Is not bound to files in the project repository — external documents (Confluence pages, remote URLs) must be first-class nodes
+- Is readable and writable by any LLM without a schema reference document
+- Renders as an interactive visual graph accessible from VSCode or browser
+
+**Architecture — Three-Layer Design:**
+
+```
+Layer 1: knowledge-graph.json        — the graph (data, version-controlled)
+Layer 2: BMAD skill emission hooks   — populate the graph as artifacts are produced
+Layer 3: knowledge-graph.html        — the renderer (self-contained, generated by open-graph skill)
+```
+
+**Layer 1: Graph File Schema**
+
+`_bmad-output/knowledge-graph.json` — single file, flat structure, no nesting beyond 2 levels:
+
+```json
+{
+  "meta": {
+    "schema_version": "1.0",
+    "project": "agents",
+    "generated": "2026-04-07T10:00:00Z",
+    "last_updated": "2026-04-07T10:00:00Z",
+    "file_count": 4,
+    "node_count": 127,
+    "edge_count": 89
+  },
+  "files": {
+    "prd": {
+      "pointer": "_bmad-output/planning-artifacts/prd.md",
+      "title": "PRD",
+      "pointer_type": "relative_path"
+    },
+    "arch": {
+      "pointer": "_bmad-output/planning-artifacts/architecture.md",
+      "title": "Architecture",
+      "pointer_type": "relative_path"
+    },
+    "ux-conf": {
+      "pointer": "https://confluence.example.com/display/PROJ/UX+Design",
+      "title": "UX Design (Confluence)",
+      "pointer_type": "url"
+    },
+    "epics": {
+      "pointer": "_bmad-output/planning-artifacts/epics.md",
+      "title": "Epics",
+      "pointer_type": "relative_path"
+    }
+  },
+  "nodes": [
+    {
+      "id": "prd#functional-requirements",
+      "file": "prd",
+      "anchor": "functional-requirements",
+      "title": "Functional Requirements",
+      "type": "requirement"
+    },
+    {
+      "id": "arch#decision-p3-1-bmad-knowledge-graph",
+      "file": "arch",
+      "anchor": "decision-p3-1-bmad-knowledge-graph",
+      "title": "Decision P3-1: BMAD Knowledge Graph",
+      "type": "architecture"
+    }
+  ],
+  "edges": [
+    {
+      "id": "e-arch-p3-1-prd-fr141",
+      "from": "arch#decision-p3-1-bmad-knowledge-graph",
+      "to": "prd#fr141",
+      "type": "implements",
+      "label": "implements knowledge graph data model requirement",
+      "created_by": "Alon",
+      "agent": "claude-code",
+      "created_at": "2026-04-07T10:00:00Z"
+    }
+  ]
+}
+```
+
+**Files table design rationale:**
+- `file-id` (e.g., `prd`, `arch`, `ux-conf`) is a short stable identifier chosen by the skill at registration time. Skills use kebab-case slugs derived from the document type or filename
+- `pointer_type` is one of `relative_path`, `absolute_path`, `url` — drives both navigation (how to open the file) and display (external icon for URLs)
+- `relative_path` pointers are relative to the project root (same root as `_bmad-output/`)
+- Once a `file-id` is registered, it is permanent — skills reference it in node and edge `from`/`to` fields. Renaming a file updates the `pointer` field only, not the `file-id`
+
+**Node and edge design rationale:**
+- Anchors are derived from Markdown heading text using GitHub slug rules: lowercase, spaces → hyphens, punctuation stripped. This matches VSCode's internal link resolution — the same anchor used in `[text](file.md#anchor)` links
+- Edge `type` vocabulary covers the full relationship space: `implements` (arch → req), `derives-from` (epic → req), `traces-to` (story → epic), `informed-by` (any cross-document influence without strict hierarchy), `validates` (review → artifact), `refines` (edit → earlier version)
+- `informed-by` is the key non-hierarchical type — it records influence without asserting derivation or implementation
+- Counts in `meta` are maintained by the writer. LLMs add the deltas after append; the counts enable quick integrity checks without array scanning
+
+**LLM-writability contract (NFR39):**
+The JSON is designed so that a model with no prior knowledge of the schema can correctly add an entry by observing the existing structure:
+1. Read the `files` object — copy the pattern to register a new file
+2. Read the `nodes` array — copy the pattern to add a new node
+3. Read the `edges` array — copy the pattern to add a new edge
+4. Update the three counts in `meta`
+
+No external schema, no JSONSchema validation, no reserved keywords beyond the field names visible in the file.
+
+**Layer 2: BMAD Skill Emission**
+
+Skills emit to the graph as a post-artifact step — after writing the document, before returning to the user.
+
+**Emission contract:**
+```
+1. Register source file in `files` if not present — assign file-id, set pointer and pointer_type
+2. Register target file(s) in `files` if not present (for upstream artifacts referenced as edge targets)
+3. For each heading in the produced artifact: add node if not already present (update title if exists)
+4. For each relationship to an upstream artifact: add edge if not present (update created_at, agent if exists)
+5. Update meta.file_count, meta.node_count, meta.edge_count, meta.last_updated
+6. Atomic write: read current JSON → apply additions → write back
+```
+
+**Read-modify-write atomicity (FR149):** Each skill emits in a single read-modify-write cycle:
+```javascript
+// In each emitting skill — pseudocode pattern
+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(), files: {}, nodes: [], edges: [] };
+
+  // Register files
+  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)
+  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)
+  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');
+}
+```
+
+**Skills that emit (and what they emit):**
+
+| Skill | Source Nodes | Target Nodes | Edge Types |
+|---|---|---|---|
+| `bmad-create-prd` | All PRD headings | — | — (seeds nodes only; upstream source) |
+| `bmad-create-architecture` | All architecture decision headings | Corresponding PRD requirement headings | `implements` |
+| `bmad-create-ux-design` | All UX section headings | Corresponding PRD requirement headings | `derives-from` |
+| `bmad-create-epics-and-stories` | All epic headings | PRD feature headings; architecture decision headings | `derives-from`, `informed-by` |
+| `bmad-create-story` | Story heading + AC headings | Epic heading; architecture section headings; UX section headings | `traces-to`, `informed-by` |
+| `bmad-dev-story` | Story implementation notes | Story spec heading | `refines` |
+| `bmad-validate-prd`, `bmad-code-review` | Validation report heading | Validated artifact heading | `validates` |
+
+**Heading → anchor resolution:**
+Skills derive anchors using the same slug algorithm as GitHub Markdown (lowercase, spaces → hyphens, strip non-alphanumeric except hyphens). This ensures `[text](file.md#anchor)` links constructed from graph data are valid clickable links in any Markdown renderer.
+
+```javascript
+function headingToAnchor(heading) {
+  return heading
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .trim();
+}
+// "Decision P3-1: BMAD Knowledge Graph" → "decision-p3-1-bmad-knowledge-graph"
+```
+
+**Non-hierarchical reference resolution:**
+When a skill produces a story, it inspects all documents it was given as input — the epic, the architecture doc, any UX spec referenced in the task context — and emits `informed-by` edges for each. The skill does not assume a single upstream parent; all documents that shaped the output become edge targets. This makes the graph genuinely any-to-any rather than a tree with `derives-from` edges.
+
+**Layer 3: open-graph Skill and Renderer**
+
+The `open-graph` skill is a new BMAD extension skill in `lib/bmad-extension/skills/open-graph/`:
+```
+lib/bmad-extension/skills/open-graph/
+├── SKILL.md                         — entrypoint: reads knowledge-graph.json, generates knowledge-graph.html, opens it
+└── bmad-skill-manifest.yaml         — type: skill
+```
+
+**Renderer generation (FR153):**
+The skill reads `_bmad-output/knowledge-graph.json` and generates `_bmad-output/knowledge-graph.html` — a fully self-contained single-file web application. All JavaScript and CSS are inlined (no `<script src>` or `<link href>` tags pointing to external resources). The graph visualization library (a lightweight force-simulation implementation, ~30KB minified) is embedded directly in the HTML.
+
+**VSCode detection and opening (FR153):**
+```javascript
+// In open-graph SKILL.md — detection logic
+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}"`);
+}
+```
+
+**Renderer features (FR154–FR156):**
+- **Graph canvas:** Nodes rendered as labeled circles, color-coded by `type` (6 colors: requirement=blue, architecture=orange, epic=purple, story=green, design=teal, test=red). Edges rendered as directed arrows with arrowheads indicating direction
+- **Click to navigate:** Clicking a node constructs a navigation action based on the file's `pointer_type`:
+  - `relative_path` / `absolute_path`: constructs `vscode://file/{absolute-path}#{anchor}` URI and navigates (VSCode opens directly to heading). Fallback: displays a copyable Markdown link `[title](file.md#anchor)`
+  - `url`: opens the registered URL in a new browser tab (Confluence pages, external docs)
+- **Edge tooltip (FR155):** Hovering over an edge line shows: type, label (if set), created_by, agent, created_at
+- **Filtering (FR156):** Checkboxes above canvas for node types and edge types. Selecting a node highlights its direct neighbors and their edges, dims all others
+- **Self-contained (FR157, NFR41):** No CDN dependencies, no `fetch()` calls, no WebSockets. The HTML file works identically offline, on an intranet, and in an air-gapped environment
+
+**Renderer HTML structure:**
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Knowledge Graph — {project}</title>
+  <style>/* all CSS inlined */</style>
+</head>
+<body>
+  <div id="controls"><!-- filter checkboxes --></div>
+  <svg id="graph"><!-- D3-lite force simulation, fully inlined --></svg>
+  <div id="tooltip"><!-- edge hover panel --></div>
+  <script>
+    const graphData = /* JSON.stringify(graph) embedded here at generation time */;
+    /* all graph rendering logic inlined */
+  </script>
+</body>
+</html>
+```
+
+The graph data is embedded as an inline JSON literal at generation time — not fetched at runtime. This makes the file fully portable: copy it anywhere and it renders correctly with no server.
+
+**Performance contract (NFR38):**
+Target: 500 nodes / 1000 edges render to first interactive frame in under 3 seconds. Achieved via:
+- Force simulation with initial layout pre-computed for the first 100 ticks before display (no janky startup animation)
+- Nodes and edges rendered as SVG elements (not Canvas) for interactive hit-testing without re-rendering
+- Filtering implemented by CSS `display: none` on filtered elements — no re-layout on filter change
+
+**Extension module integration:**
+The `open-graph` skill is registered in `lib/bmad-extension/module-help.csv` in the `anytime` phase. Total extension module skill count increases from 44 to 45:
+
+```
+lib/bmad-extension/skills/open-graph/   — new (graph visualization)
+```
+
+**`_bmad-output` additions:**
+```
+_bmad-output/
+├── knowledge-graph.json              — NEW: knowledge graph data (version-controlled)
+└── knowledge-graph.html              — NEW: renderer (generated artifact, can gitignore or commit)
+```
+
+`knowledge-graph.json` is version-controlled project knowledge — tracked like `prd.md` and `architecture.md`. `knowledge-graph.html` is a generated artifact from it — teams may choose to gitignore it (it can always be regenerated from the JSON) or commit it for quick access. This is a project-level convention, not enforced by the installer.
+
+**FR coverage for this decision:**
+
+| FR | Coverage |
+|---|---|
+| FR141 (nodes as file-id#anchor) | `nodes` array schema with `file`, `anchor`, `id` fields |
+| FR142 (edges with type + provenance) | `edges` array schema with all provenance fields; `informed-by` edge type added |
+| FR143 (bidirectional index) | Renderer builds forward + backward adjacency maps from flat edges array at load time — no separate index storage needed |
+| FR144 (meta/files/nodes/edges structure) | Top-level JSON structure |
+| FR145 (files table with pointer_type) | `files` object with `pointer`, `title`, `pointer_type` |
+| FR146 (node schema) | Node object fields |
+| FR147 (edge schema) | Edge object fields |
+| FR148 (meta schema with counts) | Meta object with `file_count`, `node_count`, `edge_count` |
+| FR149 (automatic emission, atomic write) | `emitToGraph()` pattern with read-modify-write |
+| FR150 (file registration, external URL support) | `files` table pre-registration in `emitToGraph()` |
+| FR151 (non-hierarchical multi-source emission) | Skills inspect all input docs; `informed-by` type for non-strict influence |
+| FR152 (no duplicates, provenance preservation) | Duplicate check in `emitToGraph()` — title updates allowed, provenance fields never overwritten on existing edges |
+| FR153 (open-graph skill, VSCode/browser) | VSCode env detection + platform-appropriate open command |
+| FR154 (interactive viz, node navigation) | Color-coded nodes, directed edges, VSCode URI navigation, URL tab opening |
+| FR155 (edge tooltip with provenance) | Hover tooltip with all edge fields |
+| FR156 (filtering, neighbor highlight) | Filter checkboxes + neighbor highlight |
+| FR157 (no external dependencies) | All JS/CSS inlined; graph data embedded at generation time |
+
+**NFR coverage:**
+
+| NFR | Coverage |
+|---|---|
+| NFR38 (≤3s for 500/1000) | Pre-computed initial layout, SVG hit-testing, CSS-based filtering |
+| NFR39 (LLM-writable without schema) | Flat structure with copy-the-pattern writability; examples embedded in meta and first entries |
+| NFR40 (additive-only emission) | `emitToGraph()` never deletes; updates only title (nodes) and created_at/agent (edges) |
+| NFR41 (air-gapped, no server) | Data embedded as JSON literal; no fetch/CDN/WebSocket |
+
+**Affects:**
+- `lib/bmad-extension/skills/open-graph/` (new skill — SKILL.md + bmad-skill-manifest.yaml)
+- `lib/bmad-extension/module-help.csv` (new entry for open-graph in `anytime` phase)
+- BMAD skills that emit: `bmad-create-architecture`, `bmad-create-epics-and-stories`, `bmad-create-story`, `bmad-dev-story`, `bmad-create-ux-design`, `bmad-validate-prd`, `bmad-code-review` (each gains an emit step in their workflow)
+- `_bmad-output/knowledge-graph.json` (new version-controlled file, created on first skill emission)
+- `_bmad-output/knowledge-graph.html` (new generated file, created/refreshed by open-graph skill)
+
+### Decision P3-2: Software Quality Assurance (SQA) Agent — Gad (FR158–FR171, NFR42–NFR43) (2026-04-08)
+
+**Problem:** The platform has no structured mechanism for auditing project quality across multiple dimensions (process compliance, traceability, standards conformance). Quality Engineers need purpose-built workflows to assess whether a project complies with its own planning artifacts and with recognized lifecycle standards such as IEEE/ISO/IEC 12207.
+
+**Decision:** Add a fifth specialized agent persona — Gad, the SQA Engineer — built on the existing BMAD 6.2.0 skill-based agent pattern established by Epic 15. Gad uses the `bmm-qa` BMAD agent persona as its host and delivers quality workflows as discrete BMAD extension skills. Two workflows are defined for the initial release:
+
+1. **Project Audit** (`sqa-audit`) — a five-dimension quality audit (code-to-story traceability, stories-to-architecture/PRD alignment, process compliance, sprint health, release state)
+2. **IEEE/ISO/IEC 12207 Compliance** (`sqa-ieee12207`) — a 23-process-area compliance assessment against the international software lifecycle standard
+
+**Architecture fit:**
+
+| Concern | Resolution |
+|---------|-----------|
+| Agent host | Binds to `bmm-qa` — the existing BMAD built-in QA persona. No new BMAD agent slot required; agent count stays at 11. Specialized agent count grows from 4 to 5 |
+| Skill structure | Follows P2-9 (BMAD 6.2.0 Agent Architecture Migration) — `lib/bmad-extension/skills/bmad-ma-agent-sqa/` (agent) + `lib/bmad-extension/skills/sqa-audit/` + `lib/bmad-extension/skills/sqa-ieee12207/` (workflows) |
+| Read pattern | Workflows are read-only against project artifacts — no new file structures introduced. Inputs: `prd.md`, `architecture.md`, `epics.md`, `sprint-status.yaml`, test files, git history |
+| Write pattern | Each workflow produces one markdown report in `{output_folder}` using the `sqa-{workflow}-report-{YYYY-MM-DD}.md` naming convention — consistent with other agent report outputs |
+| Gap remediation | After any compliance workflow, Gad offers to invoke `create-bug-story` for each P1 gap — reusing existing bug story infrastructure (FR171) |
+| Registration | Both workflow skills and the agent skill are registered in `module-help.csv` under the `ma-skills` module, consistent with the registration pattern for all other specialized agent skills |
+| Test coverage | `test/extension-module-restructure.test.js` tracks the new skills in `expectedSqaSkills` and updates skill and CSV entry counts |
+
+**Alternatives considered:**
+- *Add quality workflows to the existing `bmm-qa` built-in agent directly:* Rejected — built-in agent modifications require BMAD upstream PRs, violating the override-via-extension policy (feedback memory).
+- *Add audit capabilities to the existing Cyber agent (Yael):* Rejected — Cyber focuses on security threat modeling and hardening. SQA is a distinct discipline covering process compliance and traceability, warranting a dedicated persona.
+
+**IEEE/ISO/IEC 12207 coverage model:**
+The workflow embeds all process area definitions and rating criteria inline in `SKILL.md` (air-gapped, NFR43). It does not attempt to formally certify compliance — it produces a compliance posture report based on evidence available in project artifacts. Organization-scope processes (HR, infrastructure management) are flagged as such and not evaluated from artifacts alone.
+
+**Files affected:**
+- `lib/bmad-extension/skills/bmad-ma-agent-sqa/` (new — agent skill)
+- `lib/bmad-extension/skills/sqa-audit/` (new — Project Audit workflow skill)
+- `lib/bmad-extension/skills/sqa-ieee12207/` (new — IEEE 12207 compliance workflow skill)
+- `lib/bmad-extension/module-help.csv` (new entries: `bmad-ma-agent-sqa`, `sqa-audit`, `sqa-ieee12207`)
+- `test/extension-module-restructure.test.js` (updated skill counts: 58→61, CSV rows: 58→61, new `expectedSqaSkills` array)
+
+---
 
 ### Implementation Readiness Validation
 
 **Decision Completeness:** HIGH
 - 11 Phase 2 decisions documented (P2-1 through P2-11, with P2-3 superseded by P2-9)
+- 2 Phase 3 decisions documented (P3-1: BMAD Knowledge Graph — FR141-FR157, NFR38-NFR41; P3-2: SQA Agent — FR158-FR171, NFR42-NFR43)
 - P2-6 rev includes code example with full parameter mapping table
 - P2-9 includes verified module structure from CIS, manifest examples, migration detection code
 - P2-10 includes wizard flow, config storage format, cross-reference file schema