loki-mode 6.0.0 → 6.2.0

package/autonomy/run.sh

@@ -7034,21 +7034,163 @@ except: pass
 " 2>/dev/null || true)
     fi
 
+    # BMAD context injection (if available)
+    local bmad_context=""
+    if [[ -f ".loki/bmad-metadata.json" ]]; then
+        local bmad_arch=""
+        if [[ -f ".loki/bmad-architecture-summary.md" ]]; then
+            bmad_arch=$(head -c 16000 ".loki/bmad-architecture-summary.md")
+        fi
+        local bmad_tasks=""
+        if [[ -f ".loki/bmad-tasks.json" ]]; then
+            bmad_tasks=$(head -c 32000 ".loki/bmad-tasks.json")
+        fi
+        local bmad_validation=""
+        if [[ -f ".loki/bmad-validation.md" ]]; then
+            bmad_validation=$(head -c 8000 ".loki/bmad-validation.md")
+        fi
+        bmad_context="BMAD_CONTEXT: This project uses BMAD Method structured artifacts. Architecture decisions and epic/story breakdown are provided below."
+        if [[ -n "$bmad_arch" ]]; then
+            bmad_context="$bmad_context ARCHITECTURE DECISIONS: $bmad_arch"
+        fi
+        if [[ -n "$bmad_tasks" ]]; then
+            bmad_context="$bmad_context EPIC/STORY TASKS (from BMAD): $bmad_tasks"
+        fi
+        if [[ -n "$bmad_validation" ]]; then
+            bmad_context="$bmad_context ARTIFACT VALIDATION: $bmad_validation"
+        fi
+    fi
+
     if [ $retry -eq 0 ]; then
         if [ -n "$prd" ]; then
-            echo "Loki Mode with PRD at $prd. $human_directive $queue_tasks $checklist_status $app_runner_info $playwright_info $memory_context_section $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
+            echo "Loki Mode with PRD at $prd. $human_directive $queue_tasks $bmad_context $checklist_status $app_runner_info $playwright_info $memory_context_section $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
         else
-            echo "Loki Mode. $human_directive $queue_tasks $checklist_status $app_runner_info $playwright_info $memory_context_section $analysis_instruction $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
+            echo "Loki Mode. $human_directive $queue_tasks $bmad_context $checklist_status $app_runner_info $playwright_info $memory_context_section $analysis_instruction $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
         fi
     else
         if [ -n "$prd" ]; then
-            echo "Loki Mode - Resume iteration #$iteration (retry #$retry). PRD: $prd. $human_directive $queue_tasks $checklist_status $app_runner_info $playwright_info $memory_context_section $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
+            echo "Loki Mode - Resume iteration #$iteration (retry #$retry). PRD: $prd. $human_directive $queue_tasks $bmad_context $checklist_status $app_runner_info $playwright_info $memory_context_section $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
         else
-            echo "Loki Mode - Resume iteration #$iteration (retry #$retry). $human_directive $queue_tasks $checklist_status $app_runner_info $playwright_info $memory_context_section Use .loki/generated-prd.md if exists. $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
+            echo "Loki Mode - Resume iteration #$iteration (retry #$retry). $human_directive $queue_tasks $bmad_context $checklist_status $app_runner_info $playwright_info $memory_context_section Use .loki/generated-prd.md if exists. $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
         fi
     fi
 }
 
+#===============================================================================
+# BMAD Task Queue Population
+#===============================================================================
+
+# Populate the task queue from BMAD epic/story artifacts
+# Only runs once -- skips if queue was already populated from BMAD
+populate_bmad_queue() {
+    # Skip if no BMAD tasks file
+    if [[ ! -f ".loki/bmad-tasks.json" ]]; then
+        return 0
+    fi
+
+    # Skip if already populated (marker file)
+    if [[ -f ".loki/queue/.bmad-populated" ]]; then
+        log_info "BMAD queue already populated, skipping"
+        return 0
+    fi
+
+    log_step "Populating task queue from BMAD stories..."
+
+    # Ensure queue directory exists
+    mkdir -p ".loki/queue"
+
+    # Read BMAD tasks and create queue entries
+    python3 << 'BMAD_QUEUE_EOF' 2>/dev/null
+import json
+import os
+import sys
+
+bmad_tasks_path = ".loki/bmad-tasks.json"
+pending_path = ".loki/queue/pending.json"
+
+try:
+    with open(bmad_tasks_path, "r") as f:
+        bmad_data = json.load(f)
+except (json.JSONDecodeError, FileNotFoundError) as e:
+    print(f"Warning: Could not read BMAD tasks: {e}", file=sys.stderr)
+    sys.exit(0)
+
+# Extract stories from BMAD structure
+# Supports both flat list and nested epic/story format
+stories = []
+if isinstance(bmad_data, list):
+    stories = bmad_data
+elif isinstance(bmad_data, dict):
+    # Handle {"epics": [...]} or {"tasks": [...]} formats
+    for key in ("epics", "tasks", "stories"):
+        if key in bmad_data:
+            items = bmad_data[key]
+            if isinstance(items, list):
+                for item in items:
+                    if isinstance(item, dict) and "stories" in item:
+                        # Epic with nested stories
+                        epic_name = item.get("title", item.get("name", ""))
+                        for story in item["stories"]:
+                            if isinstance(story, dict):
+                                story.setdefault("epic", epic_name)
+                                stories.append(story)
+                    else:
+                        stories.append(item)
+            break
+
+if not stories:
+    print("No BMAD stories found to queue", file=sys.stderr)
+    sys.exit(0)
+
+# Load existing pending tasks (if any)
+existing = []
+if os.path.exists(pending_path):
+    try:
+        with open(pending_path, "r") as f:
+            data = json.load(f)
+            if isinstance(data, list):
+                existing = data
+            elif isinstance(data, dict) and "tasks" in data:
+                existing = data["tasks"]
+    except (json.JSONDecodeError, FileNotFoundError):
+        existing = []
+
+# Convert BMAD stories to queue task format
+for i, story in enumerate(stories):
+    if not isinstance(story, dict):
+        continue
+    task = {
+        "id": f"bmad-{i+1}",
+        "title": story.get("title", story.get("name", f"BMAD Story {i+1}")),
+        "description": story.get("description", story.get("action", "")),
+        "priority": story.get("priority", "medium"),
+        "source": "bmad",
+    }
+    epic = story.get("epic", "")
+    if epic:
+        task["epic"] = epic
+    acceptance = story.get("acceptance_criteria", story.get("criteria", []))
+    if acceptance:
+        task["acceptance_criteria"] = acceptance
+    existing.append(task)
+
+# Write updated pending queue
+with open(pending_path, "w") as f:
+    json.dump(existing, f, indent=2)
+
+print(f"Added {len(stories)} BMAD stories to task queue")
+BMAD_QUEUE_EOF
+
+    if [[ $? -ne 0 ]]; then
+        log_warn "Failed to populate BMAD queue (python3 error)"
+        return 0
+    fi
+
+    # Mark as populated so we don't re-add on restart
+    touch ".loki/queue/.bmad-populated"
+    log_info "BMAD queue population complete"
+}
+
 #===============================================================================
 # Main Autonomous Loop
 #===============================================================================
@@ -7130,6 +7272,9 @@ run_autonomous() {
         fi
     fi
 
+    # Populate task queue from BMAD artifacts (if present, runs once)
+    populate_bmad_queue
+
     # Check max iterations before starting
     if check_max_iterations; then
         log_error "Max iterations already reached. Reset with: rm .loki/autonomy-state.json"

package/autonomy/sandbox.sh

@@ -62,6 +62,34 @@ DASHBOARD_PORT="${LOKI_DASHBOARD_PORT:-57374}"
 # Security: Prompt injection disabled by default for enterprise security
 PROMPT_INJECTION_ENABLED="${LOKI_PROMPT_INJECTION:-false}"
 
+#===============================================================================
+# Docker Credential Mount Presets
+#===============================================================================
+
+# Preset definitions: "host_path:container_path:mode"
+# Container runs as user 'loki' (UID 1000), so mount to /home/loki/
+declare -A DOCKER_MOUNT_PRESETS
+DOCKER_MOUNT_PRESETS=(
+    [gh]="$HOME/.config/gh:/home/loki/.config/gh:ro"
+    [git]="$HOME/.gitconfig:/home/loki/.gitconfig:ro"
+    [ssh]="$HOME/.ssh:/home/loki/.ssh:ro"
+    [aws]="$HOME/.aws:/home/loki/.aws:ro"
+    [azure]="$HOME/.azure:/home/loki/.azure:ro"
+    [kube]="$HOME/.kube:/home/loki/.kube:ro"
+    [terraform]="$HOME/.terraform.d:/home/loki/.terraform.d:ro"
+    [gcloud]="$HOME/.config/gcloud:/home/loki/.config/gcloud:ro"
+    [npm]="$HOME/.npmrc:/home/loki/.npmrc:ro"
+)
+
+# Environment variables auto-passed per preset (comma-separated)
+declare -A DOCKER_ENV_PRESETS
+DOCKER_ENV_PRESETS=(
+    [aws]="AWS_REGION,AWS_PROFILE,AWS_DEFAULT_REGION"
+    [azure]="AZURE_SUBSCRIPTION_ID,AZURE_TENANT_ID"
+    [gcloud]="GOOGLE_PROJECT,GOOGLE_REGION,GCLOUD_PROJECT"
+    [terraform]="TF_VAR_*"
+)
+
 #===============================================================================
 # Utility Functions
 #===============================================================================
@@ -767,9 +795,129 @@ docker_desktop_sandbox_run() {
 # Docker Container Sandbox (standard Docker - fallback from Docker Desktop)
 #===============================================================================
 
+# Resolve Docker credential mount presets
+# Reads from: .loki/config/settings.json dockerMounts, LOKI_DOCKER_MOUNTS env var
+# Returns: string of -v and -e flags for docker run
+resolve_docker_mounts() {
+    local mount_args=""
+
+    # Read configured presets (JSON array of strings)
+    local presets_json=""
+    if [[ -f "${PROJECT_DIR}/.loki/config/settings.json" ]]; then
+        presets_json=$(python3 -c "
+import json, sys
+try:
+    with open('${PROJECT_DIR}/.loki/config/settings.json') as f:
+        print(json.dumps(json.load(f).get('dockerMounts', [])))
+except: print('[]')
+" 2>/dev/null || echo "[]")
+    fi
+
+    # Override with env var if set
+    if [[ -n "${LOKI_DOCKER_MOUNTS:-}" ]]; then
+        presets_json="$LOKI_DOCKER_MOUNTS"
+    fi
+
+    # Parse and resolve
+    if [[ "$presets_json" != "[]" ]] && [[ "$presets_json" != "" ]]; then
+        local preset_names
+        preset_names=$(python3 -c "
+import json, sys
+try:
+    data = json.loads(sys.argv[1])
+    if isinstance(data, list):
+        for item in data:
+            print(item)
+except: pass
+" "$presets_json" 2>/dev/null || echo "")
+
+        local name
+        while IFS= read -r name; do
+            [[ -z "$name" ]] && continue
+
+            local preset_value="${DOCKER_MOUNT_PRESETS[$name]:-}"
+            if [[ -z "$preset_value" ]]; then
+                log_warn "Unknown Docker mount preset: $name"
+                continue
+            fi
+
+            IFS=':' read -ra parts <<< "$preset_value"
+            local host_path="${parts[0]}"
+            local container_path="${parts[1]}"
+            local mode="${parts[2]:-ro}"
+
+            # Expand ~ and $HOME
+            host_path=$(eval echo "$host_path" 2>/dev/null || echo "$host_path")
+
+            # Only mount if host path exists
+            if [[ -e "$host_path" ]]; then
+                mount_args="$mount_args -v ${host_path}:${container_path}:${mode}"
+                log_info "  Mount preset [$name]: $host_path -> $container_path ($mode)"
+            fi
+
+            # Add associated env vars
+            local env_list="${DOCKER_ENV_PRESETS[$name]:-}"
+            if [[ -n "$env_list" ]]; then
+                IFS=',' read -ra env_names <<< "$env_list"
+                local env_name
+                for env_name in "${env_names[@]}"; do
+                    if [[ "$env_name" == *"*" ]]; then
+                        # Wildcard: pass all matching env vars
+                        local prefix="${env_name%\*}"
+                        while IFS='=' read -r key val; do
+                            [[ "$key" == "$prefix"* ]] && [[ -n "$val" ]] && \
+                                mount_args="$mount_args -e $key"
+                        done < <(env)
+                    elif [[ -n "${!env_name:-}" ]]; then
+                        mount_args="$mount_args -e $env_name"
+                    fi
+                done
+            fi
+        done <<< "$preset_names"
+    fi
+
+    echo "$mount_args"
+}
+
 start_sandbox() {
-    local prd_path="${1:-}"
+    # Parse arguments: extract flags before positional args
+    local prd_path=""
     local provider="${LOKI_PROVIDER:-claude}"
+    local no_mounts=false
+    local -a custom_mounts=()
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --mount)
+                if [[ -n "${2:-}" ]]; then
+                    custom_mounts+=("$2")
+                    shift 2
+                else
+                    log_error "--mount requires HOST:CONTAINER:MODE argument"
+                    return 1
+                fi
+                ;;
+            --no-mounts)
+                no_mounts=true
+                shift
+                ;;
+            --provider)
+                if [[ -n "${2:-}" ]]; then
+                    provider="$2"
+                    shift 2
+                else
+                    shift
+                fi
+                ;;
+            *)
+                # First non-flag argument is the PRD path
+                if [[ -z "$prd_path" ]]; then
+                    prd_path="$1"
+                fi
+                shift
+                ;;
+        esac
+    done
 
     # Set up signal handler to cleanup on Ctrl+C
     trap cleanup_container INT TERM
@@ -887,6 +1035,38 @@ start_sandbox() {
         docker_args+=("--volume" "$HOME/.config/gh:/home/loki/.config/gh:ro")
     fi
 
+    # Apply Docker credential mount presets (additive on top of defaults above)
+    if [[ "$no_mounts" != "true" ]] && [[ "${LOKI_NO_DOCKER_MOUNTS:-}" != "true" ]]; then
+        local preset_mounts
+        preset_mounts=$(resolve_docker_mounts)
+        if [[ -n "$preset_mounts" ]]; then
+            # shellcheck disable=SC2206
+            docker_args+=($preset_mounts)
+        fi
+    fi
+
+    # Apply custom --mount arguments
+    local custom_mount
+    for custom_mount in "${custom_mounts[@]+"${custom_mounts[@]}"}"; do
+        if [[ -n "$custom_mount" ]]; then
+            IFS=':' read -ra mount_parts <<< "$custom_mount"
+            local c_host="${mount_parts[0]:-}"
+            local c_container="${mount_parts[1]:-}"
+            local c_mode="${mount_parts[2]:-ro}"
+            if [[ -n "$c_host" ]] && [[ -n "$c_container" ]]; then
+                c_host=$(eval echo "$c_host" 2>/dev/null || echo "$c_host")
+                if [[ -e "$c_host" ]]; then
+                    docker_args+=("--volume" "${c_host}:${c_container}:${c_mode}")
+                    log_info "  Custom mount: $c_host -> $c_container ($c_mode)"
+                else
+                    log_warn "Custom mount source does not exist: $c_host"
+                fi
+            else
+                log_warn "Invalid mount format: $custom_mount (expected HOST:CONTAINER[:MODE])"
+            fi
+        fi
+    done
+
     # Pass API keys as environment variables (more secure than mounting files)
     if [[ -n "${ANTHROPIC_API_KEY:-}" ]]; then
         docker_args+=("--env" "ANTHROPIC_API_KEY")

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "6.0.0"
+__version__ = "6.2.0"
 
 # Expose the control app for easy import
 try:

package/docs/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 The flagship product of [Autonomi](https://www.autonomi.dev/). Complete installation instructions for all platforms and use cases.
 
-**Version:** v6.0.0
+**Version:** v6.2.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.