loki-mode 6.0.0 → 6.1.0

package/docs/architecture/bmad-integration-epic.md

@@ -0,0 +1,271 @@
+# BMAD Integration -- Epic and Story Breakdown
+
+**Date:** 2026-02-25
+**Scope:** Epic 1 only (P0 -- BMAD Artifact Pipeline)
+**Version Target:** v6.1.0
+
+Epics 2 (Engine Embedding) and 3 (Voice Agent Layer) are documented as future work
+but explicitly deferred pending P0 value validation.
+
+---
+
+## Epic 1: BMAD Artifact Pipeline (P0 -- Must Have)
+
+**Goal:** Enable Loki Mode to consume BMAD Method output artifacts as structured input,
+producing higher-quality analysis scores and richer execution context than freeform PRDs.
+
+**Success Metric:** `loki start --bmad-project <path>` discovers, parses, and loads BMAD
+artifacts with zero regression on existing non-BMAD workflows.
+
+---
+
+### Story 1.1: BMAD PRD Format Adapter
+
+**Size:** M
+**Dependencies:** None
+**Files to create:** `autonomy/bmad-adapter.py`
+
+**Description:**
+Create a standalone Python module (stdlib only) that discovers BMAD output artifacts,
+parses their YAML frontmatter, normalizes heading structure, extracts project classification
+metadata, and produces a normalized PRD document suitable for prd-analyzer.py.
+
+**Acceptance Criteria:**
+
+- **Given** a directory containing `_bmad-output/planning-artifacts/prd-*.md`
+  **When** bmad-adapter.py is invoked with the project path
+  **Then** it discovers the PRD file automatically
+
+- **Given** a BMAD PRD with YAML frontmatter (`stepsCompleted`, `inputDocuments`, `workflowType`)
+  **When** the adapter parses it
+  **Then** frontmatter is extracted as metadata and stripped from the document body
+
+- **Given** a BMAD PRD with sections like `## Executive Summary`, `## Project Classification`
+  **When** the adapter normalizes headings
+  **Then** sections are preserved as-is (no destructive remapping)
+
+- **Given** a BMAD project with `architecture.md` alongside the PRD
+  **When** the adapter runs
+  **Then** architecture content is appended as supplementary context
+
+- **Given** a BMAD project with `epics.md`
+  **When** the adapter runs
+  **Then** epic/story data is extracted into a structured task list (JSON)
+
+- **Given** a non-BMAD project directory (no `_bmad-output/`)
+  **When** the adapter is invoked
+  **Then** it exits with a clear error message and non-zero exit code
+
+- **Given** a BMAD project with incomplete workflow state (`stepsCompleted` missing entries)
+  **When** the adapter runs
+  **Then** it warns about incomplete artifacts but processes what exists
+
+---
+
+### Story 1.2: Enhanced PRD Analyzer for BMAD Documents
+
+**Size:** S
+**Dependencies:** Story 1.1 (adapter output format)
+**Files to modify:** `autonomy/prd-analyzer.py`
+
+**Description:**
+Add BMAD-specific heading patterns and content patterns to the existing dimension system.
+Add an optional `--architecture` flag to score an architecture document alongside the PRD.
+Maintain full backward compatibility with freeform PRDs.
+
+**Acceptance Criteria:**
+
+- **Given** a BMAD PRD with `## Executive Summary`
+  **When** prd-analyzer.py scores it
+  **Then** the section is recognized (new heading pattern in `feature_list` or new dimension)
+
+- **Given** a BMAD PRD with `## Functional Requirements` containing `FR1:` items
+  **When** prd-analyzer.py scores it
+  **Then** `feature_list` dimension scores HIGH
+
+- **Given** a BMAD PRD with `## Non-Functional Requirements` > `### Security`, `### Performance`
+  **When** prd-analyzer.py scores it
+  **Then** `security` and `deployment` dimensions score at least PARTIAL
+
+- **Given** the `--architecture path/to/architecture.md` flag
+  **When** prd-analyzer.py runs
+  **Then** tech_stack, data_model, and api_spec dimensions are also scored from architecture.md
+
+- **Given** a freeform PRD (no BMAD structure)
+  **When** prd-analyzer.py scores it
+  **Then** results are identical to the current version (zero regression)
+
+- **Given** a BMAD PRD and a freeform PRD of equivalent completeness
+  **When** both are scored
+  **Then** BMAD PRD scores equal or higher (structured methodology bonus not required but allowed)
+
+---
+
+### Story 1.3: `--bmad-project` CLI Flag
+
+**Size:** M
+**Dependencies:** Story 1.1 (adapter), Story 1.2 (enhanced analyzer)
+**Files to modify:** `autonomy/loki`, `autonomy/run.sh`
+
+**Description:**
+Add a `--bmad-project <path>` flag to `loki start`. When provided, the CLI runs
+bmad-adapter.py to discover and parse BMAD artifacts, then feeds the normalized output
+into the standard PRD analysis pipeline. BMAD context (architecture decisions, epic list)
+is injected into build_prompt() as a supplementary context block.
+
+**Acceptance Criteria:**
+
+- **Given** `loki start --bmad-project ./my-project`
+  **When** `./my-project/_bmad-output/` exists with BMAD artifacts
+  **Then** artifacts are discovered, parsed, and loaded into `.loki/` state
+
+- **Given** `loki start --bmad-project ./my-project`
+  **When** `./my-project/_bmad-output/` does NOT exist
+  **Then** CLI prints error and exits with non-zero code
+
+- **Given** BMAD artifacts are loaded
+  **When** build_prompt() constructs the iteration prompt
+  **Then** a `BMAD_CONTEXT` block is injected with architecture summary and active epic
+
+- **Given** BMAD epics are loaded
+  **When** the task queue is populated
+  **Then** each BMAD story becomes a `.loki/queue/` task with priority and acceptance criteria
+
+- **Given** `loki start ./prd.md` (no --bmad-project flag)
+  **When** the CLI runs
+  **Then** behavior is identical to current version (zero regression)
+
+- **Given** `loki start --bmad-project ./my-project --prd ./override.md`
+  **When** both flags are provided
+  **Then** the explicit PRD takes precedence; BMAD artifacts provide supplementary context only
+
+- **Given** the `--bmad-project` flag
+  **When** `loki help start` is run
+  **Then** the flag appears in help text with usage description
+
+---
+
+### Story 1.4: BMAD Artifact Chain Validator
+
+**Size:** S
+**Dependencies:** Story 1.1 (adapter)
+**Files to create:** Validation logic within `autonomy/bmad-adapter.py`
+
+**Description:**
+Validate that BMAD artifacts form a consistent chain: product-brief references are
+reflected in PRD, PRD requirements trace to architecture decisions, architecture maps
+to epics. Report consistency gaps as warnings (not blockers).
+
+**Acceptance Criteria:**
+
+- **Given** a BMAD project with product-brief, PRD, architecture, and epics
+  **When** the validator runs
+  **Then** it checks that PRD references product-brief themes
+
+- **Given** a BMAD PRD with 20 Functional Requirements and epics.md
+  **When** the validator runs
+  **Then** it reports how many FRs are covered by at least one epic story
+
+- **Given** a BMAD project missing architecture.md
+  **When** the validator runs
+  **Then** it warns about the missing artifact but does not block processing
+
+- **Given** an inconsistency (FR in PRD with no matching story in epics)
+  **When** the validator runs
+  **Then** the gap is reported as a warning in the adapter output
+
+---
+
+### Story 1.5: BMAD Integration Tests
+
+**Size:** M
+**Dependencies:** Stories 1.1-1.4
+**Files to create:** `tests/test-bmad-integration.sh`, `tests/fixtures/bmad/`
+
+**Description:**
+Comprehensive test suite covering BMAD adapter parsing, analyzer scoring, CLI flag
+behavior, artifact chain validation, and backward compatibility. Test fixtures created
+from BMAD's own templates populated with realistic data.
+
+**Acceptance Criteria:**
+
+- **Given** test fixtures in `tests/fixtures/bmad/` with realistic BMAD output
+  **When** `bash tests/test-bmad-integration.sh` runs
+  **Then** all tests pass with zero failures
+
+- **Given** a fixture with a well-formed BMAD PRD
+  **When** the adapter and analyzer are run on it
+  **Then** quality score is >= 7.0/10
+
+- **Given** a fixture with a freeform PRD (non-BMAD)
+  **When** the analyzer scores it before and after the Story 1.2 changes
+  **Then** scores are identical (backward compatibility)
+
+- **Given** a fixture with malformed BMAD artifacts (missing frontmatter, partial steps)
+  **When** the adapter processes it
+  **Then** it handles gracefully with warnings, no crashes
+
+- **Given** a fixture with incomplete artifact chain (PRD but no architecture)
+  **When** the adapter and validator run
+  **Then** processing succeeds with chain-gap warnings
+
+- **Given** the `--bmad-project` CLI flag
+  **When** tested against fixtures
+  **Then** discovery, loading, and prompt injection all work correctly
+
+- **Given** the test suite
+  **When** run after any code change
+  **Then** execution completes in under 30 seconds
+
+---
+
+## Epic 2: BMAD Engine Embedding (P1 -- Deferred)
+
+**Goal:** Programmatically execute BMAD step-file workflows within Loki Mode, enabling
+interactive requirements elicitation without requiring a separate BMAD-aware LLM session.
+
+**Status:** Deferred. Requires P0 success validation first.
+
+### Planned Stories (not detailed)
+
+- Story 2.1: BMAD agent YAML parser
+- Story 2.2: Step-file processor (execute BMAD workflows programmatically)
+- Story 2.3: Session state manager (track step progress, partial artifacts)
+- Story 2.4: Dashboard "Elicitation" panel
+- Story 2.5: Party Mode adapter (multi-agent collaboration)
+
+---
+
+## Epic 3: Voice Agent Layer (P2 -- Deferred)
+
+**Goal:** Transform voice.sh from simple transcription to a structured dialogue system
+that can facilitate BMAD requirements elicitation conversations.
+
+**Status:** Deferred. Highest risk. Requires both P0 and P1 success validation.
+
+### Planned Stories (not detailed)
+
+- Story 3.1: Structured dialogue manager
+- Story 3.2: BMAD step-to-voice mapper
+- Story 3.3: Technical term correction loop
+- Story 3.4: Voice session persistence
+- Story 3.5: Dual-mode interface (voice for elicitation, visual for review)
+
+---
+
+## Dependency Graph
+
+```
+Story 1.1 (Adapter) -----> Story 1.2 (Analyzer Enhancement)
+     |                           |
+     |                           v
+     +---> Story 1.4 (Validator) ---> Story 1.3 (CLI Flag)
+                                           |
+                                           v
+                                      Story 1.5 (Tests)
+```
+
+Stories 1.1 and 1.2 can be developed in parallel.
+Story 1.3 depends on both 1.1 and 1.2.
+Story 1.4 is part of 1.1 but can be developed in parallel.
+Story 1.5 depends on all other stories but fixture creation can start immediately.

package/docs/architecture/bmad-integration-review.md

@@ -0,0 +1,86 @@
+# BMAD Integration Adversarial Review
+
+**Date:** 2026-02-25
+**Methodology:** BMAD-style adversarial review (zero findings = failure, re-analyze)
+**Reviewers:** 3 blind Opus agents + Devil's Advocate pass
+
+## Review Process
+
+Three independent reviewers analyzed the full BMAD integration diff across 5 files.
+Combined: 48 unique findings (2 CRITICAL, 12 HIGH, 21 MEDIUM, 13 LOW).
+
+After triage: 1 CRITICAL and 5 HIGH findings were fixed before this report.
+
+## Findings Fixed (Pre-Merge)
+
+| # | Severity | File | Issue | Fix Applied |
+|---|----------|------|-------|-------------|
+| 1 | CRITICAL | bmad-adapter.py:136-140 | Path traversal via config.json outputDir | Added resolve() + project root boundary check |
+| 2 | HIGH | bmad-adapter.py:266,294,419 | Missing errors="replace" on read_text | Replaced all read_text with _safe_read() helper (size limit + encoding safety) |
+| 3 | HIGH | bmad-adapter.py:576-607 | Non-atomic file writes | Added _write_atomic() using tempfile + os.replace pattern |
+| 4 | HIGH | run.sh:7042-7050 | Unbounded BMAD content in prompt | Added head -c size limits (16K arch, 32K tasks, 8K validation) |
+| 5 | HIGH | run.sh:7066-7074 | BMAD context before human_directive in prompt | Moved bmad_context after human_directive and queue_tasks |
+| 6 | HIGH | test-bmad-integration.sh:37,126,163,248 | Trap quoting + inline Python injection | Fixed trap quoting, replaced open('$var') with sys.argv[1] |
+
+## Findings Accepted (Known Limitations)
+
+| # | Severity | Issue | Rationale for Accepting |
+|---|----------|-------|------------------------|
+| 1 | MEDIUM | Regex YAML parser does not handle block-style lists | BMAD fixtures use flow-style. Block-style support is a future enhancement. Documented in code. |
+| 2 | MEDIUM | populate_bmad_queue() has no standalone test | Function tested indirectly through full integration. Standalone test is a future improvement. |
+| 3 | MEDIUM | prd-analyzer scope estimation includes architecture lines | Conservative choice -- slightly inflated feature count is better than missing features. |
+| 4 | MEDIUM | BMAD_PROJECT_PATH exported but unused by run.sh | Intentionally kept for future provider scripts. Added comment. |
+| 5 | LOW | Error messages show full filesystem paths | Acceptable for CLI tool aimed at developers. Not a production web service. |
+| 6 | LOW | mkdir uses default umask | Standard Python behavior, consistent with rest of codebase. |
+
+## Adversarial Scenarios Tested
+
+### What happens when BMAD output format changes in V7?
+
+The adapter uses loose pattern matching (regex on headings, not exact schema validation).
+Section headings like "## Functional Requirements" and "FR1:" patterns are generic enough
+to survive minor format changes. The frontmatter parser handles unknown keys gracefully.
+**Risk: LOW.** The adapter degrades gracefully -- fewer dimensions matched means lower
+score, not a crash.
+
+### What happens with malformed BMAD artifacts?
+
+Tested with incomplete fixture (partial workflow state). Adapter:
+- Reports workflow completion percentage
+- Warns about missing artifacts
+- Processes what exists without crashing
+- Uses errors="replace" for encoding safety
+- Has 10MB file size limit
+
+**Risk: LOW.** Graceful degradation verified.
+
+### What happens when _bmad-output/ contains partial workflow state?
+
+Tested with `stepsCompleted: [init, discovery, vision]` (30% complete).
+Adapter reports completion percentage and warns. Does not block processing.
+**Risk: LOW.** User gets informed about incomplete state.
+
+### What happens if someone passes --bmad-project to a non-BMAD project?
+
+Clear error message and non-zero exit code:
+```
+ERROR: BMAD output directory not found: _bmad-output/planning-artifacts
+This does not appear to be a BMAD project.
+```
+**Risk: NONE.** Clean failure.
+
+### What about backward compatibility for non-BMAD projects?
+
+All BMAD code paths are guarded:
+- CLI: only activated by explicit --bmad-project flag
+- run.sh: checks for .loki/bmad-metadata.json existence
+- prd-analyzer.py: new patterns only ADD to existing ones, never replace
+
+Freeform PRD test confirms identical scoring (5.0/10) before and after changes.
+**Risk: NONE.** Verified by test.
+
+## Recommendation
+
+**PASS.** All CRITICAL and HIGH findings fixed. Remaining MEDIUM/LOW findings are
+acceptable known limitations with documented rationale. Backward compatibility verified.
+Integration is clean, additive, and well-guarded.

package/docs/architecture/bmad-integration-validation.md

@@ -0,0 +1,249 @@
+# BMAD Integration Validation Report
+
+**Date:** 2026-02-25
+**Validator:** Automated analysis against Loki Mode v6.0.0 codebase
+**BMAD Version:** Latest main (cloned 2026-02-25)
+
+## Decision: GO (Phase 0 / Epic 1 only)
+
+Phase 0 (BMAD Artifact Pipeline) is low-risk, additive, and achievable with the current
+codebase. Phases 1-2 are deferred pending P0 value validation.
+
+---
+
+## 1. Compatibility Matrix
+
+| Integration Point | Status | Notes |
+|---|---|---|
+| PRD format parsing | Compatible (minor gaps) | 7/9 analyzer dimensions match BMAD headings directly |
+| Artifact chain discovery | New capability needed | Adapter must find `_bmad-output/planning-artifacts/` |
+| Agent personas | Complementary | BMAD pre-dev agents + Loki execution agents = full coverage |
+| Voice capabilities | Insufficient for P2 | voice.sh only does 4-section dictation, not structured dialogue |
+| Context budget | Safe | ~8-15K tokens per iteration (step files load one-at-a-time) |
+| License | MIT -- fully compatible | No restrictions on integration or redistribution |
+| Event bus integration | Ready | `.loki/events/pending/` accepts BMAD artifact events |
+| Memory system | Ready | BMAD artifacts can be stored as episodic memory |
+| CLI integration | Straightforward | `--bmad-project` flag pattern matches existing CLI architecture |
+| Dashboard | Deferred (P1) | Would need new "Elicitation" panel |
+
+## 2. PRD Format Gap Analysis
+
+### BMAD PRD Section Headings vs Loki Analyzer Dimensions
+
+| BMAD PRD Section | Loki Dimension | Match Type |
+|---|---|---|
+| `## Executive Summary` | -- | NO MATCH (no heading pattern covers "executive summary") |
+| `## Project Classification` | -- | NO MATCH |
+| `## Success Criteria` | `acceptance_criteria` | PARTIAL (heading pattern matches "criteria" keyword) |
+| `## Product Scope` | `feature_list` | MATCH (heading pattern matches "scope") |
+| `## User Journeys` | `user_stories` | MATCH (heading pattern matches "user.*journey") |
+| `## Domain-Specific Requirements` | -- | NO MATCH |
+| `## Innovation & Novel Patterns` | -- | NO MATCH |
+| `## [ProjectType] Specific Requirements` | `feature_list` | PARTIAL (matches "requirement") |
+| `## Project Scoping & Phased Development` | `feature_list` | PARTIAL (matches "scope") |
+| `## Functional Requirements` | `feature_list` | MATCH (matches "functional" and "requirement") |
+| `## Non-Functional Requirements` | Multiple | MATCH (content patterns for security, deployment, error handling) |
+
+### Content Pattern Matches
+
+| BMAD Content Pattern | Loki Content Pattern | Match? |
+|---|---|---|
+| `FR{N}: [Actor] can [capability]` | `user can/should/will` in `user_stories` | YES |
+| `Given/When/Then` (in epics) | `given.*when.*then` in `acceptance_criteria` | YES |
+| `As a {role}, I want {action}` (stories) | `as a \w+` in `user_stories` | YES |
+| Tech stack mentions in architecture.md | Tech keyword patterns in `tech_stack` | YES |
+| `### Performance`, `### Security` (NFRs) | Security/deployment heading patterns | YES |
+
+### Gaps Requiring Adapter Work
+
+1. **Executive Summary** -- BMAD's most prominent section has no matching Loki dimension.
+   Adapter should map this to a "project_overview" meta-dimension.
+
+2. **Project Classification** -- BMAD includes project type, domain, complexity.
+   No Loki equivalent. Adapter should extract and pass as metadata.
+
+3. **Domain-Specific Requirements** -- Healthcare, fintech, govtech compliance sections.
+   No Loki dimension covers domain compliance. Consider adding as optional dimension.
+
+4. **Innovation & Novel Patterns** -- BMAD-specific section.
+   Not needed for scoring; pass through as supplementary context.
+
+5. **Frontmatter parsing** -- BMAD documents have YAML frontmatter with `stepsCompleted`,
+   `inputDocuments`, `workflowType`. Loki's prd-analyzer.py ignores frontmatter entirely.
+   Adapter must strip frontmatter before passing to analyzer OR extend analyzer.
+
+### Scoring Impact
+
+A well-formed BMAD PRD would score approximately **7.5-8.5/10** on the current analyzer
+without any changes:
+- `feature_list`: HIGH (## Functional Requirements + bullet lists)
+- `user_stories`: HIGH (## User Journeys + "As a..." stories in epics)
+- `acceptance_criteria`: HIGH (Given/When/Then in epics)
+- `tech_stack`: PARTIAL-HIGH (architecture.md has tech details, PRD may not)
+- `security`: PARTIAL (## Non-Functional Requirements > ### Security)
+- `deployment`: PARTIAL (may be in architecture.md, not PRD)
+- `data_model`: NONE-PARTIAL (usually in architecture.md, not PRD)
+- `api_spec`: NONE-PARTIAL (usually in architecture.md, not PRD)
+- `error_handling`: PARTIAL (## Non-Functional Requirements may cover this)
+
+With an adapter that also feeds architecture.md into the analyzer, score would be **9-10/10**.
+
+## 3. Agent Overlap Analysis
+
+### BMAD Agents (8) vs Loki Agent Types (41)
+
+| BMAD Agent | Role | Loki Equivalent(s) | Relationship |
+|---|---|---|---|
+| Mary (Analyst) | Business analysis, research | `prod-pm` (partial) | Complementary -- BMAD analyst is pre-development |
+| John (PM) | PRD creation, validation | `prod-pm`, `orch-planner` | Overlapping -- Loki PM focuses on execution planning |
+| Winston (Architect) | Architecture design | `eng-infra`, `orch-planner` | Complementary -- BMAD architect is pre-code |
+| Sally (UX Designer) | UX specification | `prod-design` | Complementary -- BMAD UX is spec, Loki is implementation |
+| Amelia (Developer) | Code implementation | `eng-*` (8 agents) | Superseded -- Loki has specialized dev agents |
+| Bob (Scrum Master) | Sprint planning | `orch-coordinator` | Overlapping -- different abstraction level |
+| Quinn (QA) | E2E test generation | `eng-qa` | Overlapping -- both generate tests |
+| Barry (Quick Flow) | Solo rapid dev | No equivalent | Unique to BMAD |
+
+### Assessment
+
+- **Zero conflict.** BMAD agents operate in the pre-development space (requirements, planning,
+  architecture). Loki agents operate in the execution space (coding, testing, deploying).
+- **Clear handoff point:** BMAD produces artifacts (PRD, architecture, epics). Loki consumes
+  them. The adapter bridges the format gap.
+- **Party Mode** (multi-agent collaboration) is a BMAD concept that could enrich Loki's
+  council-based review in future phases.
+
+## 4. Voice Compatibility Assessment
+
+### Current Capabilities (voice.sh)
+
+| Capability | Status |
+|---|---|
+| STT (Speech-to-Text) | Whisper API, local Whisper, macOS dictation |
+| TTS (Text-to-Speech) | macOS `say`, Linux espeak/festival |
+| Audio recording | sox, ffmpeg, arecord |
+| Guided dictation | 4-section template only (name, overview, requirements, tech stack) |
+| Structured dialogue | NOT SUPPORTED |
+| Agent handoff | NOT SUPPORTED |
+| Session persistence | NOT SUPPORTED |
+| Technical term correction | NOT SUPPORTED |
+
+### What BMAD Voice Integration (P2) Would Require
+
+| Requirement | Effort | Description |
+|---|---|---|
+| Step-file-to-question mapper | Large | Convert BMAD step instructions to conversational prompts |
+| Multi-turn dialogue manager | Large | Track conversation state, handle clarifications, backtracking |
+| Agent persona injection | Medium | Voice TTS uses agent voice characteristics |
+| Technical term correction loop | Medium | Confirm jargon transcription ("Did you say React or Preact?") |
+| Session persistence | Medium | Resume BMAD workflows across voice sessions |
+| Dual-mode interface | Large | Voice for elicitation, visual for review |
+
+### Assessment
+
+Voice integration (P2) is the highest-risk phase. The current voice.sh is a thin wrapper
+around STT/TTS tools. Transforming it into a structured dialogue system requires:
+- New conversation state machine (not just record-transcribe-write)
+- BMAD step-file interpreter (convert markdown instructions to conversational flow)
+- Feedback loop for transcription accuracy (critical for technical terms)
+
+**Recommendation:** Defer P2 entirely. P0 (artifact pipeline) delivers value without voice.
+Voice integration can be revisited after P0 proves the BMAD artifact format is stable and useful.
+
+## 5. Context Budget Analysis
+
+### Per-Iteration Context Cost (P0 Only)
+
+| Component | Tokens | Source |
+|---|---|---|
+| Loki SKILL.md | ~2,750 | Always loaded |
+| RARV instructions | ~1,500 | build_prompt() |
+| SDLC phases + rules | ~1,000 | build_prompt() |
+| Memory context | ~2,000-5,000 | Memory retrieval |
+| PRD content | ~5,000-12,000 | BMAD PRD document |
+| PRD observations | ~500-1,000 | prd-analyzer output |
+| **BMAD adapter metadata** | **~500-1,000** | **Project classification, artifact chain info** |
+| **BMAD architecture summary** | **~2,000-4,000** | **Condensed architecture decisions** |
+| **BMAD epic summary** | **~1,000-3,000** | **Active epic/story context** |
+| Checklist status | ~500-1,000 | verification-results.json |
+| Queue tasks | ~500-2,000 | .loki/queue/ |
+| **TOTAL** | **~17,250-32,250** | **Well under 150K ceiling** |
+
+### Verdict
+
+At worst case (~32K tokens), BMAD integration uses ~21% of a 150K context window.
+This leaves ample room for code context, tool outputs, and conversation history.
+No context pressure risk.
+
+## 6. Risk Register
+
+| Risk | Severity | Likelihood | Mitigation |
+|---|---|---|---|
+| BMAD output format changes in future versions | Medium | Medium | Adapter uses loose pattern matching, not exact schema; version-pin BMAD reference |
+| Malformed BMAD artifacts (partial workflow state) | Low | Medium | Adapter validates artifact completeness; falls back to freeform PRD path |
+| BMAD `_bmad-output/` not found | Low | Low | Clear error message; `--bmad-project` flag is explicit, not auto-detected |
+| prd-analyzer regression on freeform PRDs | High | Low | Test suite includes both BMAD and freeform PRD fixtures; backward compatibility gate |
+| Context budget exceeded with very large BMAD PRDs | Low | Low | PRD content is truncated at 12K tokens; architecture summary is condensed |
+| BMAD trademark concerns | Low | Low | MIT license permits code use; trademark applies to branding, not API integration |
+| Scope creep into P1/P2 during P0 implementation | Medium | Medium | Strict phase gates; P1/P2 deferred until P0 ships and proves value |
+
+## 7. Integration Architecture (P0)
+
+```
+User's BMAD project
+  _bmad-output/
+    planning-artifacts/
+      product-brief-*.md
+      prd-*.md              <-- Primary input
+      architecture.md       <-- Secondary input
+      epics.md              <-- Story/task source
+    implementation-artifacts/
+      sprint-status.yaml
+      *.story.md
+
+                    |
+                    v
+
+  autonomy/bmad-adapter.py
+    - Discover _bmad-output/ structure
+    - Parse BMAD frontmatter (stepsCompleted, workflowType)
+    - Strip frontmatter, normalize headings
+    - Extract project classification metadata
+    - Feed normalized PRD to prd-analyzer.py
+    - Map epics to .loki/queue/ task format
+
+                    |
+                    v
+
+  autonomy/prd-analyzer.py (enhanced)
+    - New heading patterns for BMAD sections
+    - Architecture.md scoring support
+    - BMAD quality bonus (structured methodology)
+    - Backward-compatible with freeform PRDs
+
+                    |
+                    v
+
+  autonomy/loki --bmad-project <path>
+    - Discovery: find _bmad-output/ in project
+    - Load: run bmad-adapter.py, then prd-analyzer.py
+    - Inject: BMAD metadata into build_prompt()
+    - Queue: BMAD epics/stories into .loki/queue/
+
+                    |
+                    v
+
+  autonomy/run.sh (build_prompt)
+    - BMAD context block injected alongside PRD
+    - Architecture decisions as supplementary context
+    - Epic/story tracking in checklist system
+```
+
+## 8. Recommendations
+
+1. **Proceed with P0 (Epic 1) only.** BMAD Artifact Pipeline.
+2. **Do not embed BMAD engine.** Read BMAD outputs, do not execute BMAD workflows.
+3. **Do not implement voice integration.** Defer to separate initiative.
+4. **Create adapter as standalone Python module.** `autonomy/bmad-adapter.py` -- stdlib only.
+5. **Enhance prd-analyzer.py conservatively.** Add patterns, do not restructure.
+6. **Test with real BMAD output fixtures.** Create test fixtures from BMAD's own templates.
+7. **Gate P1 on P0 success metrics:** At least 5 real projects use `--bmad-project` flag.

package/docs/architecture/bmad-loki-voice-agent-council-analysis.md

@@ -0,0 +1,61 @@
+# BMAD Method x Loki Mode Voice Agent -- Council Analysis
+
+**Date:** 2026-02-25
+**Council:** 3 Opus reviewers (blind review)
+**Verdict:** Unanimous YES with phased approach
+
+## Proposal Summary
+
+Integrate the BMAD Method (https://github.com/bmad-code-org/BMAD-METHOD) with Loki Mode
+to create a structured requirements elicitation pipeline. BMAD provides a 4-phase
+workflow (Analysis, Planning, Solutioning, Implementation) with agent personas, step-file
+architecture, and adversarial review -- complementing Loki Mode's autonomous execution engine.
+
+## Council Findings
+
+### Reviewer 1: Architecture Focus
+
+**Vote:** YES (phased)
+
+- BMAD's step-file architecture aligns with Loki's progressive disclosure model
+- BMAD artifacts (product-brief, PRD, architecture, epics) map cleanly to Loki's SDLC phases
+- Context budget is manageable: BMAD step files load one-at-a-time (~3K tokens each)
+- Integration surface is well-defined: `.loki/queue/`, `build_prompt()`, event bus
+- Risk: BMAD is an external dependency that may change format without notice
+
+### Reviewer 2: Integration Feasibility
+
+**Vote:** YES (phased)
+
+- BMAD PRD output sections (Functional Requirements, Success Criteria, User Journeys)
+  match most of prd-analyzer.py's existing dimension patterns
+- Agent overlap is complementary, not conflicting: BMAD covers pre-development, Loki covers execution
+- Voice.sh needs significant extension for structured dialogue (currently only 4-section dictation)
+- MIT license is fully compatible with Loki Mode's distribution
+- Risk: Voice agent layer (Phase 3) has highest uncertainty; STT reliability for technical terms
+
+### Reviewer 3: Risk and Quality
+
+**Vote:** YES (phased, with gates)
+
+- Backward compatibility is achievable: BMAD integration is additive (new flag, new adapter)
+- Existing non-BMAD projects are untouched unless `--bmad-project` is explicitly used
+- Quality gates apply to all new code: 3-reviewer blind review, anti-sycophancy, test coverage
+- BMAD's adversarial review methodology strengthens Loki's existing quality gate system
+- Risk: Scope creep from Epic 2 (engine embedding) and Epic 3 (voice agent) -- phase gates essential
+
+## Recommended Phased Approach
+
+| Phase | Epic | Priority | Risk |
+|-------|-------|----------|------|
+| P0 | BMAD Artifact Pipeline (parse, score, load) | Must-have | Low |
+| P1 | BMAD Engine Embedding (agent YAML parser, step processor) | Should-have | Medium |
+| P2 | Voice Agent Layer (structured dialogue, BMAD-to-voice) | Nice-to-have | High |
+
+## Key Constraints
+
+1. P0 must ship independently and prove value before P1/P2 begin
+2. No runtime dependency on BMAD repo -- adapter reads BMAD output artifacts only
+3. Zero regression on existing non-BMAD workflows
+4. All code must pass existing 9-gate quality system
+5. Context budget: BMAD additions must stay under 15K tokens per iteration

package/mcp/__init__.py

@@ -57,4 +57,4 @@ try:
 except ImportError:
     __all__ = ['mcp']
 
-__version__ = '6.0.0'
+__version__ = '6.1.0'

package/mcp/requirements.txt

@@ -1 +1,2 @@
 mcp>=1.0.0
+chromadb>=1.0.0