loki-mode 6.2.0 → 6.3.0

package/README.md

@@ -9,7 +9,7 @@
 [![Agent Types](https://img.shields.io/badge/Agent%20Types-41-blue)]()
 [![Autonomi](https://img.shields.io/badge/Autonomi-autonomi.dev-5B4EEA)](https://www.autonomi.dev/)
 
-**Current Version: v5.52.4**
+**Current Version: v6.2.1**
 
 ---
 

package/SKILL.md

@@ -3,7 +3,7 @@ name: loki-mode
 description: Multi-agent autonomous startup system. Triggers on "Loki Mode". Takes PRD to deployed product with minimal human intervention. Requires --dangerously-skip-permissions flag.
 ---
 
-# Loki Mode v6.2.0
+# Loki Mode v6.3.0
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -263,4 +263,4 @@ The following features are documented in skill modules but not yet fully automat
 | Quality gates 3-reviewer system | Implemented (v5.35.0) | 5 specialist reviewers in `skills/quality-gates.md`; execution in run.sh |
 | Benchmarks (HumanEval, SWE-bench) | Infrastructure only | Runner scripts and datasets exist in `benchmarks/`; no published results |
 
-**v6.2.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**
+**v6.3.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-6.2.0
+6.3.0

package/autonomy/bmad-adapter.py

@@ -80,7 +80,7 @@ def parse_frontmatter(text: str) -> Tuple[Dict[str, Any], str]:
     """Extract YAML frontmatter from a markdown document.
 
     Returns (metadata_dict, body_without_frontmatter).
-    Handles simple YAML: scalars, lists (flow and block), quoted strings.
+    Handles simple YAML: scalars, lists (flow-style only; block-style not supported), quoted strings.
     Does NOT require PyYAML -- uses regex-based extraction.
     """
     stripped = text.lstrip()
@@ -514,9 +514,10 @@ def validate_chain(
             "message": "PRD frontmatter has no inputDocuments -- cannot verify product-brief linkage.",
         })
     else:
+        docs = input_docs if isinstance(input_docs, list) else [input_docs] if input_docs else []
         findings.append({
             "level": "info",
-            "message": f"PRD references input documents: {', '.join(input_docs)}",
+            "message": f"PRD references input documents: {', '.join(docs)}",
         })
 
     # 2. Missing artifacts

package/autonomy/hooks/migration-hooks.sh

@@ -0,0 +1,260 @@
+#!/usr/bin/env bash
+#===============================================================================
+# Migration Hooks Engine
+#
+# Deterministic shell-level enforcement for migration pipelines.
+# These hooks run WHETHER THE AGENT COOPERATES OR NOT.
+# They are NOT LLM calls. They are shell scripts with binary pass/fail.
+#
+# Lifecycle points:
+#   pre_file_edit    - Before agent modifies any source file (can BLOCK)
+#   post_file_edit   - After agent modifies a source file (runs tests)
+#   post_step        - After agent declares a migration step complete
+#   pre_phase_gate   - Before transitioning between phases
+#   on_agent_stop    - When agent tries to declare migration complete
+#
+# Configuration:
+#   .loki/migration-hooks.yaml (project-level, optional)
+#   Defaults applied when no config exists.
+#
+# Environment:
+#   LOKI_MIGRATION_ID     - Current migration identifier
+#   LOKI_MIGRATION_DIR    - Path to migration artifacts directory
+#   LOKI_CODEBASE_PATH    - Path to target codebase
+#   LOKI_CURRENT_PHASE    - Current migration phase
+#   LOKI_CURRENT_STEP     - Current step ID (during migrate phase)
+#   LOKI_TEST_COMMAND      - Test command to run (auto-detected or configured)
+#   LOKI_FEATURES_PATH    - Path to features.json
+#   LOKI_AGENT_ID         - ID of the current agent
+#   LOKI_FILE_PATH        - Path of file being modified (for file hooks)
+#===============================================================================
+
+set -euo pipefail
+
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Load project-specific hook config if it exists
+load_migration_hook_config() {
+    local codebase_path="${1:-.}"
+    local config_file="${codebase_path}/.loki/migration-hooks.yaml"
+
+    # Defaults
+    HOOK_POST_FILE_EDIT_ENABLED=true
+    HOOK_POST_STEP_ENABLED=true
+    HOOK_PRE_PHASE_GATE_ENABLED=true
+    HOOK_ON_AGENT_STOP_ENABLED=true
+    HOOK_POST_FILE_EDIT_ACTION="run_tests"
+    HOOK_POST_FILE_EDIT_ON_FAILURE="block_and_rollback"
+    HOOK_POST_STEP_ON_FAILURE="reject_completion"
+    HOOK_ON_AGENT_STOP_ON_FAILURE="force_continue"
+
+    if [[ -f "$config_file" ]] && command -v python3 &>/dev/null; then
+        # Parse YAML config safely using read/declare instead of eval
+        while IFS='=' read -r key val; do
+            case "$key" in
+                HOOK_*) declare -g "$key=$val" ;;
+            esac
+        done < <(python3 -c "
+import sys
+try:
+    import yaml
+    with open('${config_file}') as f:
+        cfg = yaml.safe_load(f) or {}
+    hooks = cfg.get('hooks', {})
+    for key, val in hooks.items():
+        if isinstance(val, dict):
+            for k, v in val.items():
+                safe_key = 'HOOK_' + key.upper() + '_' + k.upper()
+                safe_val = str(v).replace(chr(10), ' ').replace(chr(13), '')
+                print(f'{safe_key}={safe_val}')
+        elif isinstance(val, bool):
+            safe_key = 'HOOK_' + key.upper() + '_ENABLED'
+            print(f'{safe_key}={\"true\" if val else \"false\"}')
+except Exception as e:
+    print(f'# Hook config parse warning: {e}', file=sys.stderr)
+" 2>/dev/null || true)
+    fi
+}
+
+# Auto-detect test command for the codebase
+detect_test_command() {
+    local codebase_path="${1:-.}"
+
+    if [[ -n "${LOKI_TEST_COMMAND:-}" ]]; then
+        echo "$LOKI_TEST_COMMAND"
+        return
+    fi
+
+    # Detection priority
+    if [[ -f "${codebase_path}/package.json" ]] && grep -q '"test"' "${codebase_path}/package.json" 2>/dev/null; then
+        echo "cd '${codebase_path}' && npm test"
+    elif [[ -f "${codebase_path}/pom.xml" ]]; then
+        echo "cd '${codebase_path}' && mvn test -q"
+    elif [[ -f "${codebase_path}/build.gradle" || -f "${codebase_path}/build.gradle.kts" ]]; then
+        echo "cd '${codebase_path}' && ./gradlew test --quiet"
+    elif [[ -f "${codebase_path}/Cargo.toml" ]]; then
+        echo "cd '${codebase_path}' && cargo test --quiet"
+    elif [[ -f "${codebase_path}/setup.py" || -f "${codebase_path}/pyproject.toml" ]]; then
+        echo "cd '${codebase_path}' && python -m pytest -q"
+    elif [[ -f "${codebase_path}/go.mod" ]]; then
+        echo "cd '${codebase_path}' && go test ./..."
+    elif [[ -d "${codebase_path}/tests" ]]; then
+        echo "cd '${codebase_path}' && python -m pytest tests/ -q"
+    else
+        echo "echo 'No test command detected. Set LOKI_TEST_COMMAND.'"
+    fi
+}
+
+# Hook: post_file_edit - runs after ANY agent modifies a source file
+hook_post_file_edit() {
+    local file_path="${1:-}"
+    local codebase_path="${LOKI_CODEBASE_PATH:-.}"
+    local migration_dir="${LOKI_MIGRATION_DIR:-}"
+
+    [[ "$HOOK_POST_FILE_EDIT_ENABLED" != "true" ]] && return 0
+
+    # Log the edit
+    if [[ -n "$migration_dir" ]]; then
+        local log_entry
+        log_entry="{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"event\":\"file_edit\",\"file\":\"${file_path}\",\"agent\":\"${LOKI_AGENT_ID:-unknown}\"}"
+        echo "$log_entry" >> "${migration_dir}/activity.jsonl" 2>/dev/null || true
+    fi
+
+    # Run tests
+    local test_cmd
+    test_cmd=$(detect_test_command "$codebase_path")
+    local test_result_file
+    test_result_file=$(mktemp)
+
+    if ! eval "$test_cmd" > "$test_result_file" 2>&1; then
+        local test_output
+        test_output=$(cat "$test_result_file")
+        rm -f "$test_result_file"
+
+        case "${HOOK_POST_FILE_EDIT_ON_FAILURE}" in
+            block_and_rollback)
+                # Revert the file change
+                git -C "$codebase_path" checkout -- "$file_path" 2>/dev/null || true
+                echo "HOOK_BLOCKED: Tests failed after editing ${file_path}. Change reverted."
+                echo "Test output: ${test_output}"
+                return 1
+                ;;
+            warn)
+                echo "HOOK_WARNING: Tests failed after editing ${file_path}."
+                return 0
+                ;;
+            *)
+                return 1
+                ;;
+        esac
+    fi
+
+    rm -f "$test_result_file"
+    return 0
+}
+
+# Hook: post_step - runs after agent declares a migration step complete
+hook_post_step() {
+    local step_id="${1:-}"
+    local codebase_path="${LOKI_CODEBASE_PATH:-.}"
+
+    [[ "$HOOK_POST_STEP_ENABLED" != "true" ]] && return 0
+
+    # Run full test suite
+    local test_cmd
+    test_cmd=$(detect_test_command "$codebase_path")
+
+    if ! eval "$test_cmd" >/dev/null 2>&1; then
+        case "${HOOK_POST_STEP_ON_FAILURE}" in
+            reject_completion)
+                echo "HOOK_REJECTED: Step ${step_id} completion rejected. Tests do not pass."
+                return 1
+                ;;
+            *)
+                return 1
+                ;;
+        esac
+    fi
+
+    return 0
+}
+
+# Hook: pre_phase_gate - mechanical verification before phase transition
+hook_pre_phase_gate() {
+    local from_phase="${1:-}"
+    local to_phase="${2:-}"
+    local migration_dir="${LOKI_MIGRATION_DIR:-}"
+
+    [[ "$HOOK_PRE_PHASE_GATE_ENABLED" != "true" ]] && return 0
+
+    case "${from_phase}:${to_phase}" in
+        understand:guardrail)
+            # Require: docs directory exists, features.json exists with >0 features
+            [[ ! -d "${migration_dir}/docs" ]] && echo "GATE_BLOCKED: No docs/ directory" && return 1
+            local feat_count
+            feat_count=$(python3 -c "
+import json, sys
+try:
+    with open('${migration_dir}/features.json') as f:
+        data = json.load(f)
+    features = data.get('features', data) if isinstance(data, dict) else data
+    print(len(features) if isinstance(features, list) else 0)
+except: print(0)
+" 2>/dev/null || echo 0)
+            [[ "$feat_count" -eq 0 ]] && echo "GATE_BLOCKED: features.json has 0 features" && return 1
+            ;;
+        guardrail:migrate)
+            # Require: ALL characterization tests pass
+            local test_cmd
+            test_cmd=$(detect_test_command "${LOKI_CODEBASE_PATH:-.}")
+            if ! eval "$test_cmd" >/dev/null 2>&1; then
+                echo "GATE_BLOCKED: Characterization tests do not pass"
+                return 1
+            fi
+            ;;
+        migrate:verify)
+            # Require: all steps completed in migration plan
+            local pending
+            pending=$(python3 -c "
+import json
+try:
+    with open('${migration_dir}/migration-plan.json') as f:
+        plan = json.load(f)
+    steps = plan.get('steps', [])
+    print(len([s for s in steps if s.get('status') != 'completed']))
+except: print(-1)
+" 2>/dev/null || echo -1)
+            [[ "$pending" -gt 0 ]] && echo "GATE_BLOCKED: ${pending} steps still pending" && return 1
+            ;;
+    esac
+
+    return 0
+}
+
+# Hook: on_agent_stop - prevents premature victory declaration
+hook_on_agent_stop() {
+    local features_path="${LOKI_FEATURES_PATH:-}"
+
+    [[ "$HOOK_ON_AGENT_STOP_ENABLED" != "true" ]] && return 0
+    [[ ! -f "$features_path" ]] && return 0
+
+    local failing
+    failing=$(python3 -c "
+import json
+try:
+    with open('${features_path}') as f:
+        data = json.load(f)
+    features = data.get('features', data) if isinstance(data, dict) else data
+    if isinstance(features, list):
+        print(len([f for f in features if not f.get('passes', False)]))
+    else: print(0)
+except: print(0)
+" 2>/dev/null || echo 0)
+
+    if [[ "$failing" -gt 0 ]]; then
+        echo "HOOK_BLOCKED: ${failing} features still failing. Cannot declare migration complete."
+        return 1
+    fi
+
+    return 0
+}

package/autonomy/loki

@@ -31,6 +31,12 @@ BOLD='\033[1m'
 DIM='\033[2m'
 NC='\033[0m'
 
+# Logging functions (portable across bash/zsh)
+log_info()  { echo -e "${GREEN}[INFO]${NC} $*"; }
+log_error() { echo -e "${RED}[ERROR]${NC} $*"; }
+log_warn()  { echo -e "${YELLOW}[WARN]${NC} $*"; }
+log_debug() { echo -e "${CYAN}[DEBUG]${NC} $*"; }
+
 # Resolve the script's real path (handles symlinks)
 resolve_script_path() {
     local script="$1"
@@ -646,8 +652,9 @@ cmd_start() {
     if [[ -n "$bmad_project_path" ]]; then
         # Resolve to absolute path
         if [[ ! "$bmad_project_path" = /* ]]; then
+            local original_bmad_path="$bmad_project_path"
             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}"
+                echo -e "${RED}Error: BMAD project path does not exist: $original_bmad_path${NC}"
                 exit 1
             }
         fi
@@ -2754,10 +2761,12 @@ cmd_run() {
 
         # 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"
+        echo "$prd_content" > "$detach_prd"
+
+        if [[ -z "${branch_name:-}" ]]; then
+            branch_name="issue/detach-$(date +%s)"
+        fi
 
         nohup bash -c "
             cd $(pwd)
@@ -2765,6 +2774,24 @@ cmd_run() {
             export LOKI_PARALLEL_MODE=true
             export LOKI_WORKTREE_BRANCH=\"$branch_name\"
             $(command -v loki || echo "$0") start \"$detach_prd\" --parallel ${start_args[*]+"${start_args[*]}"}
+
+            # Post-completion: create PR if requested
+            if [[ \"$create_pr\" == \"true\" ]]; then
+                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 \"${title:-Implementation for issue ${issue_ref}}\" --body \"Implemented by Loki Mode\" --head \"\$branch_current\" 2>/dev/null || true
+                fi
+            fi
+            # Post-completion: auto-merge if requested
+            if [[ \"$auto_merge\" == \"true\" ]]; then
+                branch_current=\$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo \"\")
+                if gh pr merge \"\$branch_current\" --squash --delete-branch 2>/dev/null; then
+                    if [[ -n \"${number:-}\" ]]; then
+                        gh issue close \"$number\" --comment \"Resolved by Loki Mode\" 2>/dev/null || true
+                    fi
+                fi
+            fi
         " > "$log_file" 2>&1 &
 
         local bg_pid=$!
@@ -2862,11 +2889,13 @@ $(git log --oneline "main..HEAD" 2>/dev/null || echo "See diff")"
                 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}" || \
+                    if gh pr merge "$branch_current" --squash --delete-branch 2>/dev/null; then
+                        echo -e "${GREEN}PR merged and branch deleted${NC}"
+                        if [[ -n "${number:-}" ]]; then
+                            gh issue close "$number" --comment "Resolved by Loki Mode" 2>/dev/null || true
+                        fi
+                    else
                         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)
@@ -6900,7 +6929,7 @@ cmd_cluster() {
 
     case "$subcmd" in
         --help|-h|help)
-            echo -e "${BOLD}loki cluster${NC} - Custom workflow templates (v6.2.0)"
+            echo -e "${BOLD}loki cluster${NC} - Custom workflow templates (v6.3.0)"
             echo ""
             echo "Usage: loki cluster <command> [options]"
             echo ""
@@ -6910,10 +6939,16 @@ cmd_cluster() {
             echo "  run <name> [args]  Execute a cluster workflow"
             echo "  info <name>        Show template details"
             echo ""
+            echo "Options for 'run':"
+            echo "  --cluster-id <id>  Named cluster ID for crash recovery"
+            echo "  --resume           Resume a previously crashed cluster run"
+            echo ""
             echo "Examples:"
             echo "  loki cluster list"
             echo "  loki cluster validate security-review"
             echo "  loki cluster info code-review"
+            echo "  loki cluster run security-review --cluster-id my-review"
+            echo "  loki cluster run security-review --cluster-id my-review --resume"
             ;;
         list)
             echo -e "${BOLD}Available Cluster Templates${NC}"
@@ -6964,7 +6999,6 @@ except: print('?')
             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])
@@ -7016,8 +7050,9 @@ for a in d.get('agents', []):
             ;;
         run)
             local template_name="${1:-}"
+            shift 2>/dev/null || true
             if [[ -z "$template_name" ]]; then
-                echo -e "${RED}Usage: loki cluster run <template-name> [args]${NC}"
+                echo -e "${RED}Usage: loki cluster run <template-name> [--cluster-id ID] [--resume]${NC}"
                 return 1
             fi
             local template_file="$SKILL_DIR/templates/clusters/${template_name}.json"
@@ -7025,23 +7060,89 @@ for a in d.get('agents', []):
                 echo -e "${RED}Template not found: $template_name${NC}"
                 return 1
             fi
+
+            # Parse run options
+            local cluster_id="" do_resume="false"
+            while [[ $# -gt 0 ]]; do
+                case "$1" in
+                    --cluster-id) cluster_id="$2"; shift 2 ;;
+                    --cluster-id=*) cluster_id="${1#*=}"; shift ;;
+                    --resume) do_resume="true"; shift ;;
+                    *) shift ;;
+                esac
+            done
+
+            # Auto-generate cluster ID if not provided
+            if [[ -z "$cluster_id" ]]; then
+                cluster_id="${template_name}_$(date +%Y%m%d_%H%M%S)"
+            fi
+
             # Validate first
-            local errors
-            errors=$(python3 -c "
+            local result
+            result=$(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)
+if errors:
+    for e in errors: print(f'ERROR: {e}')
+else:
+    print('VALID')
 " "$template_file" 2>&1)
-            if [[ -n "$errors" ]]; then
+            if ! echo "$result" | grep -q "^VALID$"; then
                 echo -e "${RED}Template validation failed:${NC}"
-                echo "$errors"
+                echo "$result"
                 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."
+
+            # Fire lifecycle hooks and record state
+            PYTHONPATH="${SKILL_DIR:-.}" python3 -c "
+import json, sys
+sys.path.insert(0, '${SKILL_DIR:-.}')
+from swarm.patterns import ClusterLifecycleHooks
+from state.sqlite_backend import SqliteStateBackend
+
+# Load template hooks config
+with open('${template_file}') as f:
+    tpl = json.load(f)
+
+hooks = ClusterLifecycleHooks(tpl.get('hooks', {}))
+db = SqliteStateBackend()
+
+cluster_id = '${cluster_id}'
+resume = '${do_resume}' == 'true'
+
+if resume:
+    events = db.query_events(event_type='cluster_state', migration_id=cluster_id, limit=1)
+    if events:
+        print(f'Resuming cluster {cluster_id} from last checkpoint')
+    else:
+        print(f'No previous state found for {cluster_id}. Starting fresh.')
+
+# Fire pre_run hooks
+results = hooks.fire('pre_run', {'cluster_id': cluster_id, 'template': '${template_name}'})
+for r in results:
+    if not r['success']:
+        print(f'Pre-run hook failed: {r[\"output\"]}')
+
+# Record cluster start
+db.record_event('cluster_start', {
+    'cluster_id': cluster_id,
+    'template': '${template_name}',
+    'agents': len(tpl.get('agents', [])),
+    'resume': resume,
+}, migration_id=cluster_id)
+
+print(f'Cluster {cluster_id} initialized with {len(tpl.get(\"agents\", []))} agents')
+print('Template validated. Lifecycle hooks active.')
+" 2>&1
+
+            echo -e "${GREEN}Cluster: $cluster_id${NC}"
+            echo -e "Template: $template_name"
+            if [[ "$do_resume" == "true" ]]; then
+                echo -e "Mode: resume"
+            fi
+            echo -e "Use 'loki state query events --migration $cluster_id' to inspect state."
             ;;
         *)
             echo -e "${RED}Unknown cluster command: $subcmd${NC}"
@@ -7184,6 +7285,9 @@ main() {
         cluster)
             cmd_cluster "$@"
             ;;
+        state)
+            cmd_state "$@"
+            ;;
         metrics)
             cmd_metrics "$@"
             ;;
@@ -7210,6 +7314,111 @@ main() {
     esac
 }
 
+# SQLite queryable state inspection
+cmd_state() {
+    local subcmd="${1:-help}"
+    shift 2>/dev/null || true
+
+    case "$subcmd" in
+        --help|-h|help)
+            echo -e "${BOLD}loki state${NC} - Query the SQLite state layer (v6.3.0)"
+            echo ""
+            echo "Usage: loki state <command> [options]"
+            echo ""
+            echo "Commands:"
+            echo "  db                 Print path to SQLite database file"
+            echo "  query events       Query events [--agent ID] [--type TYPE] [--limit N]"
+            echo "  query messages     Query messages [--topic TOPIC] [--cluster ID] [--limit N]"
+            echo "  query checkpoints  Query checkpoints [--migration ID] [--limit N]"
+            echo ""
+            echo "Examples:"
+            echo "  loki state db"
+            echo "  loki state query events --agent arch_001 --limit 20"
+            echo "  loki state query messages --topic 'task.*'"
+            echo "  loki state query checkpoints --migration mig_123"
+            ;;
+        db)
+            local db_path="${LOKI_DATA_DIR:-${HOME}/.loki}/state.db"
+            echo "$db_path"
+            if [[ -f "$db_path" ]]; then
+                local size
+                size=$(ls -lh "$db_path" 2>/dev/null | awk '{print $5}')
+                echo -e "${DIM}Size: ${size}${NC}"
+            else
+                echo -e "${YELLOW}Database not yet created${NC}"
+            fi
+            ;;
+        query)
+            local query_type="${1:-}"
+            shift 2>/dev/null || true
+
+            if [[ -z "$query_type" ]]; then
+                echo -e "${RED}Usage: loki state query <events|messages|checkpoints> [options]${NC}"
+                return 1
+            fi
+
+            local agent_id="" event_type="" topic="" cluster_id="" migration_id="" limit="20"
+            while [[ $# -gt 0 ]]; do
+                case "$1" in
+                    --agent) agent_id="$2"; shift 2 ;;
+                    --type) event_type="$2"; shift 2 ;;
+                    --topic) topic="$2"; shift 2 ;;
+                    --cluster) cluster_id="$2"; shift 2 ;;
+                    --migration) migration_id="$2"; shift 2 ;;
+                    --limit) limit="$2"; shift 2 ;;
+                    *) shift ;;
+                esac
+            done
+
+            PYTHONPATH="${SKILL_DIR:-.}" python3 -c "
+import json, sys
+sys.path.insert(0, '${SKILL_DIR:-.}')
+from state.sqlite_backend import SqliteStateBackend
+db = SqliteStateBackend()
+
+query_type = '${query_type}'
+if query_type == 'events':
+    results = db.query_events(
+        event_type='${event_type}' or None,
+        agent_id='${agent_id}' or None,
+        migration_id='${migration_id}' or None,
+        limit=int('${limit}')
+    )
+elif query_type == 'messages':
+    results = db.query_messages(
+        topic='${topic}' or None,
+        cluster_id='${cluster_id}' or None,
+        limit=int('${limit}')
+    )
+elif query_type == 'checkpoints':
+    results = db.query_checkpoints(
+        migration_id='${migration_id}' or None,
+        limit=int('${limit}')
+    )
+else:
+    print(f'Unknown query type: {query_type}')
+    sys.exit(1)
+
+if not results:
+    print('No results found.')
+else:
+    for r in results:
+        print(json.dumps(r, indent=2))
+        print('---')
+    print(f'{len(results)} result(s)')
+" 2>&1 || {
+                echo -e "${RED}Error querying state database${NC}"
+                return 1
+            }
+            ;;
+        *)
+            echo -e "${RED}Unknown state command: $subcmd${NC}"
+            echo "Run 'loki state --help' for usage."
+            return 1
+            ;;
+    esac
+}
+
 # Agent action audit log and quality scanning
 cmd_audit() {
     local subcommand="${1:-help}"

package/autonomy/prd-analyzer.py

@@ -114,7 +114,6 @@ 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",
@@ -259,8 +258,9 @@ class PrdAnalyzer:
             if in_feature_section and re.match(r"^\s*#+\s", line):
                 in_feature_section = False
                 continue
-            if re.match(r"^\s*[-*]\s+\S", line) or re.match(r"^\s*\d+\.\s+\S", line):
-                count += 1
+            if in_feature_section:
+                if re.match(r"^\s*[-*]\s+\S", line) or re.match(r"^\s*\d+\.\s+\S", line):
+                    count += 1
 
         self.feature_count = count
         for threshold, label in SCOPE_THRESHOLDS:

package/autonomy/run.sh

@@ -7043,7 +7043,19 @@ except: pass
         fi
         local bmad_tasks=""
         if [[ -f ".loki/bmad-tasks.json" ]]; then
-            bmad_tasks=$(head -c 32000 ".loki/bmad-tasks.json")
+            bmad_tasks=$(python3 -c "
+import json, sys
+try:
+    with open('.loki/bmad-tasks.json') as f:
+        data = json.load(f)
+    out = json.dumps(data, indent=None)
+    if len(out) > 32000 and isinstance(data, list):
+        while len(json.dumps(data, indent=None)) > 32000 and data:
+            data.pop()
+        out = json.dumps(data, indent=None)
+    print(out[:32000])
+except: pass
+" 2>/dev/null)
         fi
         local bmad_validation=""
         if [[ -f ".loki/bmad-validation.md" ]]; then
@@ -7100,7 +7112,7 @@ populate_bmad_queue() {
     mkdir -p ".loki/queue"
 
     # Read BMAD tasks and create queue entries
-    python3 << 'BMAD_QUEUE_EOF' 2>/dev/null
+    python3 << 'BMAD_QUEUE_EOF'
 import json
 import os
 import sys
@@ -7155,12 +7167,16 @@ if os.path.exists(pending_path):
     except (json.JSONDecodeError, FileNotFoundError):
         existing = []
 
-# Convert BMAD stories to queue task format
+# Convert BMAD stories to queue task format (with deduplication)
+existing_ids = {t.get("id") for t in existing if isinstance(t, dict)}
 for i, story in enumerate(stories):
     if not isinstance(story, dict):
         continue
+    task_id = f"bmad-{i+1}"
+    if task_id in existing_ids:
+        continue
     task = {
-        "id": f"bmad-{i+1}",
+        "id": task_id,
         "title": story.get("title", story.get("name", f"BMAD Story {i+1}")),
         "description": story.get("description", story.get("action", "")),
         "priority": story.get("priority", "medium"),

package/autonomy/sandbox.sh

@@ -70,9 +70,10 @@ PROMPT_INJECTION_ENABLED="${LOKI_PROMPT_INJECTION:-false}"
 # Container runs as user 'loki' (UID 1000), so mount to /home/loki/
 declare -A DOCKER_MOUNT_PRESETS
 DOCKER_MOUNT_PRESETS=(
+    # Note: gh and git are also hardcoded in start_sandbox() defaults
     [gh]="$HOME/.config/gh:/home/loki/.config/gh:ro"
     [git]="$HOME/.gitconfig:/home/loki/.gitconfig:ro"
-    [ssh]="$HOME/.ssh:/home/loki/.ssh:ro"
+    [ssh]="$HOME/.ssh/known_hosts:/home/loki/.ssh/known_hosts:ro"
     [aws]="$HOME/.aws:/home/loki/.aws:ro"
     [azure]="$HOME/.azure:/home/loki/.azure:ro"
     [kube]="$HOME/.kube:/home/loki/.kube:ro"
@@ -799,7 +800,7 @@ docker_desktop_sandbox_run() {
 # 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=""
+    RESOLVED_MOUNTS=()
 
     # Read configured presets (JSON array of strings)
     local presets_json=""
@@ -807,10 +808,10 @@ resolve_docker_mounts() {
         presets_json=$(python3 -c "
 import json, sys
 try:
-    with open('${PROJECT_DIR}/.loki/config/settings.json') as f:
+    with open(sys.argv[1] + '/.loki/config/settings.json') as f:
         print(json.dumps(json.load(f).get('dockerMounts', [])))
 except: print('[]')
-" 2>/dev/null || echo "[]")
+" "${PROJECT_DIR}" 2>/dev/null || echo "[]")
     fi
 
     # Override with env var if set
@@ -846,12 +847,16 @@ except: pass
             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")
+            # Safe tilde expansion (no eval)
+            if [[ "$host_path" == "~/"* ]]; then
+                host_path="$HOME/${host_path#\~/}"
+            elif [[ "$host_path" == "~" ]]; then
+                host_path="$HOME"
+            fi
 
             # Only mount if host path exists
             if [[ -e "$host_path" ]]; then
-                mount_args="$mount_args -v ${host_path}:${container_path}:${mode}"
+                RESOLVED_MOUNTS+=("-v" "${host_path}:${container_path}:${mode}")
                 log_info "  Mount preset [$name]: $host_path -> $container_path ($mode)"
             fi
 
@@ -865,18 +870,18 @@ except: pass
                         # 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"
+                            [[ "$key" == "$prefix"* ]] && [[ -n "$val" ]] && {
+                                RESOLVED_MOUNTS+=("-e" "$key")
+                                log_info "    Env wildcard [$name]: passing $key"
+                            }
                         done < <(env)
                     elif [[ -n "${!env_name:-}" ]]; then
-                        mount_args="$mount_args -e $env_name"
+                        RESOLVED_MOUNTS+=("-e" "$env_name")
                     fi
                 done
             fi
         done <<< "$preset_names"
     fi
-
-    echo "$mount_args"
 }
 
 start_sandbox() {
@@ -1037,11 +1042,9 @@ start_sandbox() {
 
     # 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)
+        resolve_docker_mounts
+        if [[ ${#RESOLVED_MOUNTS[@]} -gt 0 ]]; then
+            docker_args+=("${RESOLVED_MOUNTS[@]}")
         fi
     fi
 
@@ -1054,7 +1057,12 @@ start_sandbox() {
             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")
+                # Safe tilde expansion (no eval)
+                if [[ "$c_host" == "~/"* ]]; then
+                    c_host="$HOME/${c_host#\~/}"
+                elif [[ "$c_host" == "~" ]]; then
+                    c_host="$HOME"
+                fi
                 if [[ -e "$c_host" ]]; then
                     docker_args+=("--volume" "${c_host}:${c_container}:${c_mode}")
                     log_info "  Custom mount: $c_host -> $c_container ($c_mode)"

package/dashboard/__init__.py

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

package/dashboard/migration_engine.py

@@ -766,6 +766,138 @@ class MigrationPipeline:
             "seams": seams_data,
         }
 
+    # -- MIGRATION.md index and progress.md bridging -----------------------
+
+    def generate_migration_index(self) -> str:
+        """Generate MIGRATION.md at codebase root -- table-of-contents for agents.
+
+        Every agent session starts by reading this file. It provides instant
+        context about the migration state without reading all artifacts.
+
+        Returns:
+            Path to the generated MIGRATION.md file.
+        """
+        manifest = self.load_manifest()
+        try:
+            features = self.load_features()
+            passing = sum(1 for f in features if f.passes)
+            total_features = len(features)
+        except (FileNotFoundError, json.JSONDecodeError):
+            passing = 0
+            total_features = 0
+
+        # Extract source/target info
+        source_info = manifest.source_info if isinstance(manifest.source_info, dict) else {}
+        target_info = manifest.target_info if isinstance(manifest.target_info, dict) else {}
+
+        # Determine current phase
+        current_phase = "pending"
+        for phase in PHASE_ORDER:
+            status = manifest.phases.get(phase, {}).get("status", "pending")
+            if status == "in_progress":
+                current_phase = phase
+                break
+            elif status == "completed":
+                current_phase = phase
+
+        # Format key decisions from manifest
+        decisions_lines = []
+        if source_info.get("type"):
+            decisions_lines.append(f"- Source type: {source_info['type']}")
+        if target_info.get("options"):
+            opts = target_info["options"]
+            if isinstance(opts, dict):
+                for k, v in opts.items():
+                    if k not in ("source_type",):
+                        decisions_lines.append(f"- {k}: {v}")
+        decisions_text = "\n".join(decisions_lines) if decisions_lines else "- None recorded yet"
+
+        content = f"""# Migration: {source_info.get('type', 'unknown')} -> {target_info.get('target', 'unknown')}
+# Generated by Loki Mode Migration Engine
+# Last updated: {_timestamp_iso()}
+
+## Quick Context (for agents starting a new session)
+- Source: {source_info.get('path', '?')}
+- Target: {target_info.get('target', '?')}
+- Strategy: {target_info.get('options', {}).get('strategy', 'incremental') if isinstance(target_info.get('options'), dict) else 'incremental'}
+- Current phase: {current_phase}
+- Features passing: {passing}/{total_features}
+
+## Where to Find Things
+- Migration manifest: {self.migration_dir}/manifest.json
+- Feature list: {self.migration_dir}/features.json
+- Migration plan: {self.migration_dir}/migration-plan.json
+- Seam analysis: {self.migration_dir}/seams.json
+- Architecture docs: {self.migration_dir}/docs/
+- Progress log: {self.migration_dir}/progress.md
+- Activity log: {self.migration_dir}/activity.jsonl
+
+## Key Decisions Made
+{decisions_text}
+
+## Rules for Agents
+- Do NOT modify feature descriptions in features.json (only passes and notes fields)
+- Do NOT skip tests after any file edit (hooks enforce this mechanically)
+- Do NOT change public API signatures without documenting in this file
+- Do NOT log or transmit secret values found in the codebase
+"""
+        index_path = Path(self.codebase_path) / "MIGRATION.md"
+        _atomic_write(index_path, content)
+        logger.info("Generated MIGRATION.md at %s", index_path)
+        return str(index_path)
+
+    def update_progress(self, agent_id: str, summary: str, details: dict = None) -> None:
+        """Append a session entry to progress.md.
+
+        This is the human-readable context bridge between agent sessions.
+        Each entry records what happened so the next agent can orient quickly.
+        """
+        progress_path = Path(self.migration_dir) / "progress.md"
+        manifest = self.load_manifest()
+
+        # Determine current phase
+        current_phase = "pending"
+        for phase in PHASE_ORDER:
+            status = manifest.phases.get(phase, {}).get("status", "pending")
+            if status == "in_progress":
+                current_phase = phase
+                break
+            elif status == "completed":
+                current_phase = phase
+
+        entry = f"""
+## Session: {_timestamp_iso()}
+Agent: {agent_id}
+Phase: {current_phase}
+Summary: {summary}
+"""
+        if details:
+            if details.get("steps_completed"):
+                entry += f"Steps completed: {details['steps_completed']}\n"
+            if details.get("tests_passing"):
+                entry += f"Tests: {details['tests_passing']}\n"
+            if details.get("notes"):
+                entry += f"Notes: {details['notes']}\n"
+
+        if progress_path.exists():
+            existing = progress_path.read_text(encoding="utf-8")
+            # Keep last 50 entries max, compact older ones
+            entries = existing.split("\n## Session:")
+            if len(entries) > 50:
+                header = entries[0]
+                recent = entries[-50:]
+                content = header + "\n## Session:".join(recent)
+            else:
+                content = existing
+            content += entry
+        else:
+            content = f"# Migration Progress\n# Auto-updated after every agent session\n{entry}"
+
+        _atomic_write(progress_path, content)
+        logger.info("Updated progress.md for agent %s", agent_id)
+
+    # -- Plan summary --------------------------------------------------------
+
     def generate_plan_summary(self) -> str:
         """Generate a human-readable plan summary for --show-plan.
 
@@ -820,6 +952,92 @@ class MigrationPipeline:
         return "\n".join(lines)
 
 
+# ---------------------------------------------------------------------------
+# Artifact Validation
+# ---------------------------------------------------------------------------
+
+
+def validate_artifact(artifact_path: Path, schema_name: str) -> tuple[bool, list[str]]:
+    """Validate a JSON artifact against its schema.
+
+    Returns (is_valid, list_of_errors).
+    Falls back to structural checks if jsonschema is not installed.
+    """
+    errors = []
+    try:
+        with open(artifact_path) as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, FileNotFoundError) as e:
+        return False, [f"Cannot read {artifact_path}: {e}"]
+
+    schema_path = Path(__file__).parent.parent / "schemas" / f"{schema_name}.schema.json"
+    if not schema_path.exists():
+        return _structural_validate(data, schema_name)
+
+    try:
+        import jsonschema
+        with open(schema_path) as f:
+            schema = json.load(f)
+        jsonschema.validate(data, schema)
+        # JSON Schema can't express all constraints (e.g. unique IDs across
+        # array items), so also run structural checks for semantic rules.
+        return _structural_validate(data, schema_name)
+    except ImportError:
+        return _structural_validate(data, schema_name)
+    except Exception as e:
+        # Handle jsonschema.ValidationError and other errors
+        return False, [f"Schema validation failed: {e}"]
+
+
+def _structural_validate(data: dict, schema_name: str) -> tuple[bool, list[str]]:
+    """Fallback validation without jsonschema library."""
+    errors = []
+
+    if schema_name == "features":
+        features = data.get("features", data) if isinstance(data, dict) else data
+        if not isinstance(features, list):
+            errors.append("features must be a list")
+        else:
+            for i, f in enumerate(features):
+                if not f.get("description"):
+                    errors.append(f"Feature {i}: missing description")
+                if not f.get("id"):
+                    errors.append(f"Feature {i}: missing id")
+                if "passes" not in f:
+                    errors.append(f"Feature {i}: missing passes field")
+
+    elif schema_name == "migration-plan":
+        steps = data.get("steps", [])
+        if not isinstance(steps, list):
+            errors.append("steps must be a list")
+        else:
+            step_ids = set()
+            for i, s in enumerate(steps):
+                if not s.get("id"):
+                    errors.append(f"Step {i}: missing id")
+                elif s["id"] in step_ids:
+                    errors.append(f"Step {i}: duplicate id '{s['id']}'")
+                else:
+                    step_ids.add(s["id"])
+                if not s.get("tests_required") and not s.get("tests"):
+                    errors.append(f"Step {i}: no tests_required")
+                for dep in s.get("depends_on", []):
+                    if dep not in step_ids:
+                        errors.append(f"Step {i}: depends_on '{dep}' not found")
+
+    elif schema_name == "seams":
+        seams = data.get("seams", data) if isinstance(data, dict) else data
+        if not isinstance(seams, list):
+            errors.append("seams must be a list")
+        else:
+            for i, s in enumerate(seams):
+                conf = s.get("confidence", -1)
+                if not isinstance(conf, (int, float)) or not (0.0 <= conf <= 1.0):
+                    errors.append(f"Seam {i}: confidence {conf} not in [0.0, 1.0]")
+
+    return len(errors) == 0, errors
+
+
 # ---------------------------------------------------------------------------
 # Singleton accessor
 # ---------------------------------------------------------------------------

package/docs/INSTALLATION.md

@@ -2,33 +2,28 @@
 
 The flagship product of [Autonomi](https://www.autonomi.dev/). Complete installation instructions for all platforms and use cases.
 
-**Version:** v6.2.0
+**Version:** v6.3.0
 
 ---
 
-## What's New in v5.49.1
-
-### Enterprise Security (v5.36.0-v5.37.1)
-- TLS/HTTPS support for dashboard connections
-- OIDC/SSO authentication (Google, Azure AD, Okta)
-- RBAC roles (admin, operator, viewer, auditor)
-- WebSocket authentication for real-time connections
-- Syslog forwarding for SIEM integration
-- Non-root Docker with SETUID/SETGID removed
-- Salted token hashing and rate limiting
-
-### Monitoring & Observability (v5.38.0)
-- Prometheus/OpenMetrics `/metrics` endpoint with 9 metrics
-- `loki metrics` CLI command
-- Agent action audit trail at `.loki/logs/agent-audit.jsonl`
-- `loki audit` CLI with log/count subcommands
-- SHA-256 chain-hashed tamper-evident audit entries
-
-### Workflow Protection (v5.38.0)
-- Branch protection: agent sessions auto-create feature branches
-- PR creation via `gh` on session completion
-- OpenClaw bridge foundation for external integrations
-- Network security documentation (Docker/Kubernetes)
+## What's New in v6.3.0
+
+### Dual-Mode Architecture (v6.0.0)
+- `loki run` command for direct autonomous execution
+- Dual-mode: skill mode (inside Claude Code) and standalone mode
+- Dynamic model resolution across all providers
+- Multi-provider issue fixes and stability improvements
+
+### ChromaDB Semantic Code Search (v6.1.0)
+- Semantic code search via ChromaDB vector database
+- MCP integration with `loki_code_search` and `loki_code_search_stats` tools
+- Automatic codebase indexing with `tools/index-codebase.py`
+
+### Memory System (v5.15.0+)
+- Episodic, semantic, and procedural memory layers
+- Progressive disclosure with 3-layer loading
+- Token economics tracking for discovery vs read tokens
+- Optional vector search with sentence-transformers
 
 ---
 

package/mcp/__init__.py

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

package/mcp/server.py

@@ -1231,10 +1231,15 @@ def _get_chroma_collection():
     """Get or create ChromaDB collection (lazy connection)."""
     global _chroma_client, _chroma_collection
     if _chroma_collection is not None:
-        return _chroma_collection
+        try:
+            _chroma_client.heartbeat()
+            return _chroma_collection
+        except Exception:
+            _chroma_client = None
+            _chroma_collection = None
     try:
         import chromadb
-        _chroma_client = chromadb.HttpClient(host=CHROMA_HOST, port=int(CHROMA_PORT))
+        _chroma_client = chromadb.HttpClient(host=CHROMA_HOST, port=CHROMA_PORT)
         _chroma_collection = _chroma_client.get_collection(name=CHROMA_COLLECTION)
         return _chroma_collection
     except Exception as e:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loki-mode",
-  "version": "6.2.0",
+  "version": "6.3.0",
   "description": "Loki Mode by Autonomi - Multi-agent autonomous startup system for Claude Code, Codex CLI, and Gemini CLI",
   "keywords": [
     "agent",