loki-mode 6.0.0 → 6.2.0

package/autonomy/loki

@@ -438,6 +438,7 @@ show_help() {
     echo "  --skip-memory    Skip loading memory context at startup"
     echo "  --compliance PRESET  Enable compliance mode (default|healthcare|fintech|government)"
     echo "  --budget USD     Set cost budget limit (display in dashboard/status)"
+    echo "  --bmad-project PATH  Use BMAD Method project artifacts as input"
     echo ""
     echo "Options for 'run' (v6.0.0):"
     echo "  --dry-run          Preview generated PRD without starting"
@@ -447,6 +448,12 @@ show_help() {
     echo "  --parallel         Enable parallel mode with git worktrees"
     echo "  --budget USD       Set cost budget limit"
     echo ""
+    echo "Progressive Isolation (for 'run'):"
+    echo "  --worktree, -w     Git worktree isolation (separate branch)"
+    echo "  --pr               Auto-create PR after completion (implies --worktree)"
+    echo "  --ship             Auto-merge after PR (implies --pr)"
+    echo "  --detach, -d       Run in background (implies --worktree)"
+    echo ""
     echo "Examples:"
     echo "  loki run 123                  # GitHub issue from current repo"
     echo "  loki run PROJ-456             # Jira issue"
@@ -473,6 +480,7 @@ cmd_start() {
     local args=()
     local prd_file=""
     local provider=""
+    local bmad_project_path=""
 
     while [[ $# -gt 0 ]]; do
         case "$1" in
@@ -496,6 +504,7 @@ cmd_start() {
                 echo "  --skip-memory         Skip loading memory context at startup"
                 echo "  --compliance PRESET   Enable compliance mode (default|healthcare|fintech|government)"
                 echo "  --budget USD          Cost budget limit (auto-pause when exceeded)"
+                echo "  --bmad-project PATH   Use BMAD Method project artifacts as input"
                 echo "  --yes, -y             Skip confirmation prompts (auto-confirm)"
                 echo ""
                 echo "Environment Variables:"
@@ -510,6 +519,7 @@ cmd_start() {
                 echo "  loki start ./prd.md             # Start with PRD file"
                 echo "  loki start ./prd.md --parallel  # Parallel mode with worktrees"
                 echo "  loki start --provider codex     # Use OpenAI Codex CLI"
+                echo "  loki start --bmad-project ./my-project  # Start from BMAD artifacts"
                 echo "  loki start --yes                # Skip confirmation prompt"
                 echo "  LOKI_PRD_FILE=./prd.md loki start  # PRD via env var"
                 exit 0
@@ -581,6 +591,19 @@ cmd_start() {
                 export LOKI_AUTO_CONFIRM=true
                 shift
                 ;;
+            --bmad-project)
+                if [[ -n "${2:-}" ]]; then
+                    bmad_project_path="$2"
+                    shift 2
+                else
+                    echo -e "${RED}--bmad-project requires a path to a BMAD project directory${NC}"
+                    exit 1
+                fi
+                ;;
+            --bmad-project=*)
+                bmad_project_path="${1#*=}"
+                shift
+                ;;
             --budget)
                 if [[ -n "${2:-}" ]]; then
                     if ! echo "$2" | grep -qE '^[0-9]+(\.[0-9]+)?$'; then
@@ -619,6 +642,67 @@ cmd_start() {
         prd_file="$LOKI_PRD_FILE"
     fi
 
+    # BMAD project validation and adapter execution
+    if [[ -n "$bmad_project_path" ]]; then
+        # Resolve to absolute path
+        if [[ ! "$bmad_project_path" = /* ]]; then
+            bmad_project_path="$(cd "$bmad_project_path" 2>/dev/null && pwd)" || {
+                echo -e "${RED}Error: BMAD project path does not exist: $bmad_project_path${NC}"
+                exit 1
+            }
+        fi
+
+        # Validate path is a directory
+        if [[ ! -d "$bmad_project_path" ]]; then
+            echo -e "${RED}Error: BMAD project path is not a directory: $bmad_project_path${NC}"
+            exit 1
+        fi
+
+        # Check for BMAD artifacts (_bmad-output/ or common BMAD markers)
+        if [[ ! -d "$bmad_project_path/_bmad-output" ]]; then
+            echo -e "${YELLOW}Warning: No _bmad-output/ directory found in $bmad_project_path${NC}"
+            echo "Expected a BMAD Method project with _bmad-output/ artifacts."
+            echo -e "Continue anyway? [y/N] \\c"
+            local _auto="${LOKI_AUTO_CONFIRM:-${CI:-false}}"
+            if [[ "$_auto" == "true" ]]; then
+                echo "y (auto-confirmed)"
+            else
+                read -r _bmad_confirm
+                if [[ ! "$_bmad_confirm" =~ ^[Yy] ]]; then
+                    echo "Aborted."
+                    exit 0
+                fi
+            fi
+        fi
+
+        # Export for run.sh to access
+        export BMAD_PROJECT_PATH="$bmad_project_path"
+
+        # Ensure .loki directory exists for adapter output
+        mkdir -p "$LOKI_DIR"
+
+        # Run the BMAD adapter to normalize artifacts
+        echo -e "${CYAN}Running BMAD adapter...${NC}"
+        local adapter_script="${SCRIPT_DIR:-$(dirname "$0")}/bmad-adapter.py"
+        if [[ ! -f "$adapter_script" ]]; then
+            echo -e "${RED}Error: BMAD adapter not found at $adapter_script${NC}"
+            echo "Please ensure autonomy/bmad-adapter.py exists."
+            exit 1
+        fi
+
+        if ! python3 "$adapter_script" "$bmad_project_path" --output-dir "$LOKI_DIR" --validate; then
+            echo -e "${RED}Error: BMAD adapter failed. Check the project artifacts.${NC}"
+            exit 1
+        fi
+        echo -e "${GREEN}BMAD artifacts normalized successfully.${NC}"
+
+        # If no explicit PRD was provided, use the normalized BMAD PRD
+        if [[ -z "$prd_file" ]] && [[ -f "$LOKI_DIR/bmad-prd-normalized.md" ]]; then
+            prd_file="$LOKI_DIR/bmad-prd-normalized.md"
+            echo -e "${CYAN}Using normalized BMAD PRD: $prd_file${NC}"
+        fi
+    fi
+
     if [ -n "$prd_file" ]; then
         args+=("$prd_file")
     else
@@ -2441,6 +2525,10 @@ cmd_run() {
     local start_args=()
     local no_start=false
     local provider_override=""
+    local use_worktree=false
+    local create_pr=false
+    local auto_merge=false
+    local run_detached=false
 
     # Parse arguments
     while [[ $# -gt 0 ]]; do
@@ -2473,6 +2561,14 @@ cmd_run() {
                 echo "  --sandbox          Run in Docker sandbox"
                 echo "  --budget USD       Set cost budget limit"
                 echo ""
+                echo "Progressive Isolation:"
+                echo "  --worktree, -w     Git worktree isolation (separate branch)"
+                echo "  --pr               Worktree + auto-create PR (implies --worktree)"
+                echo "  --ship             Worktree + PR + auto-merge (implies --pr)"
+                echo "  --detach, -d       Run in background (implies --worktree)"
+                echo ""
+                echo "  Cascade: --ship implies --pr implies --worktree"
+                echo ""
                 echo "Environment Variables:"
                 echo "  JIRA_API_TOKEN     Jira API token (for Jira issues)"
                 echo "  JIRA_URL           Jira base URL (for Jira issues)"
@@ -2485,6 +2581,10 @@ cmd_run() {
                 echo "  loki run https://gitlab.com/o/r/-/issues/42  # GitLab issue"
                 echo "  loki run 123 --dry-run                   # Preview PRD"
                 echo "  loki run 123 --parallel --provider codex # Parallel mode with Codex"
+                echo "  loki run 123 --worktree                  # Isolated branch"
+                echo "  loki run 123 --pr                        # Auto-create PR"
+                echo "  loki run 123 --ship                      # Full automation: PR + merge"
+                echo "  loki run 123 --ship -d                   # Background, full automation"
                 exit 0
                 ;;
             --dry-run)
@@ -2548,6 +2648,30 @@ cmd_run() {
                 start_args+=("--budget" "${1#*=}")
                 shift
                 ;;
+            --worktree|-w)
+                start_args+=("--parallel")
+                use_worktree=true
+                shift
+                ;;
+            --pr)
+                use_worktree=true
+                create_pr=true
+                start_args+=("--parallel")
+                shift
+                ;;
+            --ship)
+                use_worktree=true
+                create_pr=true
+                auto_merge=true
+                start_args+=("--parallel")
+                shift
+                ;;
+            --detach|-d)
+                use_worktree=true
+                run_detached=true
+                start_args+=("--parallel")
+                shift
+                ;;
             -*)
                 echo -e "${RED}Unknown option: $1${NC}"
                 echo "Run 'loki run --help' for usage."
@@ -2609,10 +2733,46 @@ cmd_run() {
     fi
     echo ""
 
+    # Progressive isolation: set up worktree branch naming
+    if $use_worktree; then
+        local branch_name="issue/${issue_provider}-${number:-$(date +%s)}"
+        log_info "Progressive isolation: branch $branch_name"
+        export LOKI_PARALLEL_MODE=true
+        export LOKI_WORKTREE_BRANCH="$branch_name"
+    fi
+
     # Generate PRD
     local prd_content
     prd_content=$(echo "$issue_json" | generate_prd_from_issue)
 
+    # Detached mode: fork to background
+    if $run_detached; then
+        local log_file="$LOKI_DIR/logs/run-${number:-$(date +%s)}.log"
+        mkdir -p "$(dirname "$log_file")"
+        echo -e "${GREEN}Running detached. Logs: $log_file${NC}"
+        echo -e "Check status: ${CYAN}loki status${NC}"
+
+        # Write PRD first so background process can use it
+        mkdir -p "$LOKI_DIR"
+        local prd_content_detach
+        prd_content_detach=$(echo "$issue_json" | generate_prd_from_issue)
+        local detach_prd="$LOKI_DIR/prd-issue-${number}.md"
+        echo "$prd_content_detach" > "$detach_prd"
+
+        nohup bash -c "
+            cd $(pwd)
+            export LOKI_DETACHED=true
+            export LOKI_PARALLEL_MODE=true
+            export LOKI_WORKTREE_BRANCH=\"$branch_name\"
+            $(command -v loki || echo "$0") start \"$detach_prd\" --parallel ${start_args[*]+"${start_args[*]}"}
+        " > "$log_file" 2>&1 &
+
+        local bg_pid=$!
+        echo "$bg_pid" > "$LOKI_DIR/run-${number:-detached}.pid"
+        echo "Background PID: $bg_pid"
+        return 0
+    fi
+
     # Handle dry-run
     if [[ "$dry_run" == "true" ]]; then
         echo -e "${BOLD}Generated PRD Preview:${NC}"
@@ -2650,6 +2810,75 @@ cmd_run() {
         echo ""
         echo -e "${GREEN}Starting Loki Mode with generated PRD...${NC}"
         cmd_start "$output_file" ${start_args[@]+"${start_args[@]}"}
+
+        # Progressive isolation: create PR
+        if $create_pr; then
+            echo ""
+            echo -e "${GREEN}Creating pull request...${NC}"
+            local pr_title="${title:-Implementation for issue ${issue_ref}}"
+            local pr_body="Implemented by Loki Mode (autonomous agent)
+
+Issue: ${issue_ref}
+Provider: ${issue_provider}
+
+## Changes
+$(git log --oneline "main..HEAD" 2>/dev/null || echo "See diff")"
+
+            case "${issue_provider:-github}" in
+                github)
+                    if command -v gh &>/dev/null; then
+                        local branch_current
+                        branch_current=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+                        if [[ -n "$branch_current" && "$branch_current" != "main" && "$branch_current" != "master" ]]; then
+                            git push origin "$branch_current" 2>/dev/null || true
+                            gh pr create --title "$pr_title" --body "$pr_body" --head "$branch_current" 2>/dev/null && \
+                                echo -e "${GREEN}PR created${NC}" || \
+                                echo -e "${YELLOW}PR creation failed${NC}"
+                        fi
+                    fi
+                    ;;
+                gitlab)
+                    if command -v glab &>/dev/null; then
+                        local branch_current
+                        branch_current=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+                        if [[ -n "$branch_current" && "$branch_current" != "main" && "$branch_current" != "master" ]]; then
+                            git push origin "$branch_current" 2>/dev/null || true
+                            glab mr create --title "$pr_title" --description "$pr_body" --source-branch "$branch_current" 2>/dev/null && \
+                                echo -e "${GREEN}MR created${NC}" || \
+                                echo -e "${YELLOW}MR creation failed${NC}"
+                        fi
+                    fi
+                    ;;
+                *)
+                    echo -e "${YELLOW}PR creation not supported for provider: $issue_provider${NC}"
+                    ;;
+            esac
+        fi
+
+        # Progressive isolation: auto-merge
+        if $auto_merge; then
+            echo -e "${GREEN}Auto-merging...${NC}"
+            case "${issue_provider:-github}" in
+                github)
+                    local branch_current
+                    branch_current=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+                    gh pr merge "$branch_current" --squash --delete-branch 2>/dev/null && \
+                        echo -e "${GREEN}PR merged and branch deleted${NC}" || \
+                        echo -e "${YELLOW}Auto-merge failed. PR remains open.${NC}"
+                    if [[ -n "${number:-}" ]]; then
+                        gh issue close "$number" --comment "Resolved by Loki Mode" 2>/dev/null || true
+                    fi
+                    ;;
+                gitlab)
+                    glab mr merge --squash --remove-source-branch 2>/dev/null && \
+                        echo -e "${GREEN}MR merged and branch deleted${NC}" || \
+                        echo -e "${YELLOW}Auto-merge failed. MR remains open.${NC}"
+                    ;;
+                *)
+                    echo -e "${YELLOW}Auto-merge not supported for provider: $issue_provider${NC}"
+                    ;;
+            esac
+        fi
     fi
 }
 
@@ -6661,6 +6890,167 @@ cmd_migrate() {
     cmd_migrate_start "$codebase_path" "$target" "$plan_only" "$phase" "$parallel" "$compliance" "$dry_run" "$do_resume" "$multi_repo" "$export_report" "$no_dashboard" "$no_docs"
 }
 
+#===============================================================================
+# loki cluster - Custom workflow templates (v6.2.0)
+#===============================================================================
+
+cmd_cluster() {
+    local subcmd="${1:-list}"
+    shift 2>/dev/null || true
+
+    case "$subcmd" in
+        --help|-h|help)
+            echo -e "${BOLD}loki cluster${NC} - Custom workflow templates (v6.2.0)"
+            echo ""
+            echo "Usage: loki cluster <command> [options]"
+            echo ""
+            echo "Commands:"
+            echo "  list               List available workflow templates"
+            echo "  validate <name>    Validate a cluster template"
+            echo "  run <name> [args]  Execute a cluster workflow"
+            echo "  info <name>        Show template details"
+            echo ""
+            echo "Examples:"
+            echo "  loki cluster list"
+            echo "  loki cluster validate security-review"
+            echo "  loki cluster info code-review"
+            ;;
+        list)
+            echo -e "${BOLD}Available Cluster Templates${NC}"
+            echo ""
+            local template_dir="$SKILL_DIR/templates/clusters"
+            if [[ ! -d "$template_dir" ]]; then
+                echo "No templates found at $template_dir"
+                return 1
+            fi
+            for f in "$template_dir"/*.json; do
+                [[ ! -f "$f" ]] && continue
+                local name
+                name=$(basename "$f" .json)
+                local desc
+                desc=$(python3 -c "
+import json, sys
+try:
+    with open(sys.argv[1]) as f:
+        d = json.load(f)
+    print(d.get('description', 'No description'))
+except: print('Error reading template')
+" "$f" 2>/dev/null || echo "")
+                local agent_count
+                agent_count=$(python3 -c "
+import json, sys
+try:
+    with open(sys.argv[1]) as f:
+        d = json.load(f)
+    print(len(d.get('agents', [])))
+except: print('?')
+" "$f" 2>/dev/null || echo "?")
+                printf "  %-20s %s agents  %s\n" "$name" "$agent_count" "$desc"
+            done
+            ;;
+        validate)
+            local template_name="${1:-}"
+            if [[ -z "$template_name" ]]; then
+                echo -e "${RED}Usage: loki cluster validate <template-name>${NC}"
+                return 1
+            fi
+            local template_file="$SKILL_DIR/templates/clusters/${template_name}.json"
+            if [[ ! -f "$template_file" ]]; then
+                echo -e "${RED}Template not found: $template_name${NC}"
+                echo "Run 'loki cluster list' to see available templates."
+                return 1
+            fi
+            echo -e "${CYAN}Validating: $template_name${NC}"
+            local errors
+            errors=$(python3 -c "
+import json, sys
+sys.path.insert(0, '$(dirname "$SKILL_DIR/swarm/")')
+sys.path.insert(0, '$SKILL_DIR')
+from swarm.patterns import TopologyValidator
+errors = TopologyValidator.validate_file(sys.argv[1])
+if errors:
+    for e in errors:
+        print(f'ERROR: {e}')
+else:
+    print('VALID')
+" "$template_file" 2>&1)
+            if echo "$errors" | grep -q "^VALID$"; then
+                echo -e "${GREEN}Template is valid${NC}"
+                return 0
+            else
+                echo -e "${RED}Validation errors:${NC}"
+                echo "$errors"
+                return 1
+            fi
+            ;;
+        info)
+            local template_name="${1:-}"
+            if [[ -z "$template_name" ]]; then
+                echo -e "${RED}Usage: loki cluster info <template-name>${NC}"
+                return 1
+            fi
+            local template_file="$SKILL_DIR/templates/clusters/${template_name}.json"
+            if [[ ! -f "$template_file" ]]; then
+                echo -e "${RED}Template not found: $template_name${NC}"
+                return 1
+            fi
+            python3 -c "
+import json, sys
+with open(sys.argv[1]) as f:
+    d = json.load(f)
+print(f\"Name:        {d.get('name', 'unknown')}\")
+print(f\"Description: {d.get('description', 'none')}\")
+print(f\"Version:     {d.get('version', 'unknown')}\")
+print(f\"Topology:    {d.get('topology', 'unknown')}\")
+print(f\"Agents:      {len(d.get('agents', []))}\")
+print()
+for a in d.get('agents', []):
+    subs = ', '.join(a.get('subscribes', []))
+    pubs = ', '.join(a.get('publishes', []))
+    print(f\"  [{a['id']}] ({a.get('type', '?')})\")
+    print(f\"    Role: {a.get('role', '?')}\")
+    print(f\"    Subscribes: {subs}\")
+    print(f\"    Publishes:  {pubs}\")
+    print()
+" "$template_file"
+            ;;
+        run)
+            local template_name="${1:-}"
+            if [[ -z "$template_name" ]]; then
+                echo -e "${RED}Usage: loki cluster run <template-name> [args]${NC}"
+                return 1
+            fi
+            local template_file="$SKILL_DIR/templates/clusters/${template_name}.json"
+            if [[ ! -f "$template_file" ]]; then
+                echo -e "${RED}Template not found: $template_name${NC}"
+                return 1
+            fi
+            # Validate first
+            local errors
+            errors=$(python3 -c "
+import json, sys
+sys.path.insert(0, '$SKILL_DIR')
+from swarm.patterns import TopologyValidator
+errors = TopologyValidator.validate_file(sys.argv[1])
+for e in errors: print(e)
+" "$template_file" 2>&1)
+            if [[ -n "$errors" ]]; then
+                echo -e "${RED}Template validation failed:${NC}"
+                echo "$errors"
+                return 1
+            fi
+            echo -e "${GREEN}Cluster template: $template_name${NC}"
+            echo -e "${YELLOW}Note: Cluster execution engine is planned for v6.3.0.${NC}"
+            echo -e "Template validated successfully. Use 'loki cluster info $template_name' for details."
+            ;;
+        *)
+            echo -e "${RED}Unknown cluster command: $subcmd${NC}"
+            echo "Run 'loki cluster --help' for usage."
+            return 1
+            ;;
+    esac
+}
+
 # Main command dispatcher
 main() {
     if [ $# -eq 0 ]; then
@@ -6791,6 +7181,9 @@ main() {
         migrate)
             cmd_migrate "$@"
             ;;
+        cluster)
+            cmd_cluster "$@"
+            ;;
         metrics)
             cmd_metrics "$@"
             ;;

package/autonomy/prd-analyzer.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""PRD Quality Analyzer for Loki Mode v5.44.0
+"""PRD Quality Analyzer for Loki Mode v6.1.0
 
 Analyzes PRD structure and completeness using regex-based heuristics.
 Writes observations to .loki/prd-observations.md with quality score,
@@ -10,6 +10,7 @@ Stdlib only - no pip dependencies required.
 Usage:
     python3 prd-analyzer.py path/to/prd.md --output .loki/prd-observations.md
     python3 prd-analyzer.py path/to/prd.md --output .loki/prd-observations.md --interactive
+    python3 prd-analyzer.py path/to/prd.md --architecture path/to/architecture.md
 """
 
 import argparse
@@ -28,10 +29,13 @@ DIMENSIONS = {
         "weight": 1.5,
         "heading_patterns": [
             r"(?i)#+\s.*(?:feature|requirement|scope|functional|capability)",
+            r"(?i)^##\s+Functional\s+Requirements",
+            r"(?i)^##\s+Product\s+Scope",
         ],
         "content_patterns": [
             r"^\s*[-*]\s+\S",
             r"^\s*\d+\.\s+\S",
+            r"(?i)^FR\d+:",
         ],
         "description": "Numbered or bulleted list of features/requirements",
     },
@@ -55,6 +59,7 @@ DIMENSIONS = {
         "weight": 1.0,
         "heading_patterns": [
             r"(?i)#+\s.*(?:user\s+(?:stor|flow|journey)|persona|use\s+case)",
+            r"(?i)^##\s+User\s+Journeys",
         ],
         "content_patterns": [
             r"(?i)\bas\s+a\s+\w+",
@@ -68,11 +73,13 @@ DIMENSIONS = {
         "weight": 1.0,
         "heading_patterns": [
             r"(?i)#+\s.*(?:acceptance|criteria|definition\s+of\s+done|done\s+when)",
+            r"(?i)^##\s+Success\s+Criteria",
         ],
         "content_patterns": [
             r"^\s*-\s*\[\s*[xX ]?\s*\]",
             r"(?i)\bgiven\b.*\bwhen\b.*\bthen\b",
             r"(?i)\bmust\s+(?:be|have|support|handle)\b",
+            r"(?i)^\s*\*\*Given\*\*",
         ],
         "description": "Measurable completion criteria or checklists",
     },
@@ -107,6 +114,7 @@ DIMENSIONS = {
         "weight": 0.75,
         "heading_patterns": [
             r"(?i)#+\s.*(?:deploy|hosting|infra|ci.?cd|environment)",
+            r"(?i)^##\s+Non-Functional\s+Requirements",
         ],
         "content_patterns": [
             r"(?i)\b(?:deploy|hosting|ci.?cd|pipeline|staging|production)\b",
@@ -131,6 +139,7 @@ DIMENSIONS = {
         "weight": 1.0,
         "heading_patterns": [
             r"(?i)#+\s.*(?:security|auth|permission|access\s+control)",
+            r"(?i)^##\s+Non-Functional\s+Requirements",
         ],
         "content_patterns": [
             r"(?i)\b(?:auth(?:entication|orization)?|oauth|jwt|token)\b",
@@ -153,8 +162,9 @@ SCOPE_THRESHOLDS = [
 class PrdAnalyzer:
     """Analyzes PRD quality and completeness."""
 
-    def __init__(self, prd_path):
+    def __init__(self, prd_path, architecture_path=None):
         self.prd_path = Path(prd_path)
+        self.architecture_path = Path(architecture_path) if architecture_path else None
         self.content = ""
         self.lines = []
         self.results = {}
@@ -163,13 +173,20 @@ class PrdAnalyzer:
         self.score = 0.0
 
     def load(self):
-        """Load and validate the PRD file."""
+        """Load and validate the PRD file, optionally appending architecture doc."""
         if not self.prd_path.exists():
             raise FileNotFoundError(f"PRD file not found: {self.prd_path}")
         self.content = self.prd_path.read_text(encoding="utf-8", errors="replace")
         if not self.content.strip():
             raise ValueError(f"PRD file is empty: {self.prd_path}")
         self.lines = self.content.splitlines()
+        # Append architecture document lines for pattern matching
+        if self.architecture_path:
+            if not self.architecture_path.exists():
+                raise FileNotFoundError(f"Architecture file not found: {self.architecture_path}")
+            arch_content = self.architecture_path.read_text(encoding="utf-8", errors="replace")
+            if arch_content.strip():
+                self.lines.extend(arch_content.splitlines())
 
     def analyze(self):
         """Run all analysis dimensions and compute score."""
@@ -420,6 +437,11 @@ def main():
         default=".loki/prd-observations.md",
         help="Output path for observations (default: .loki/prd-observations.md)",
     )
+    parser.add_argument(
+        "--architecture",
+        metavar="PATH",
+        help="Optional architecture document to include in analysis",
+    )
     parser.add_argument(
         "--interactive",
         action="store_true",
@@ -428,7 +450,7 @@ def main():
     args = parser.parse_args()
 
     try:
-        analyzer = PrdAnalyzer(args.prd_path)
+        analyzer = PrdAnalyzer(args.prd_path, architecture_path=args.architecture)
         analyzer.analyze()
         observations = analyzer.generate_observations()