loki-mode 6.2.1 → 6.3.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.1
+# Loki Mode v6.3.1
 
 **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.1 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**
+**v6.3.1 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-6.2.1
+6.3.1

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"
@@ -6923,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 ""
@@ -6933,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}"
@@ -7038,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"
@@ -7047,6 +7060,23 @@ 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 result
             result=$(python3 -c "
@@ -7064,9 +7094,55 @@ else:
                 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}"
@@ -7209,6 +7285,9 @@ main() {
         cluster)
             cmd_cluster "$@"
             ;;
+        state)
+            cmd_state "$@"
+            ;;
         metrics)
             cmd_metrics "$@"
             ;;
@@ -7235,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/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "6.2.1"
+__version__ = "6.3.1"
 
 # 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,11 +2,11 @@
 
 The flagship product of [Autonomi](https://www.autonomi.dev/). Complete installation instructions for all platforms and use cases.
 
-**Version:** v6.2.1
+**Version:** v6.3.1
 
 ---
 
-## What's New in v6.2.1
+## What's New in v6.3.1
 
 ### Dual-Mode Architecture (v6.0.0)
 - `loki run` command for direct autonomous execution

package/mcp/__init__.py

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

package/package.json

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