loki-mode 5.53.0 → 5.55.0

package/autonomy/migration-agents.sh

@@ -0,0 +1,500 @@
+#!/usr/bin/env bash
+# shellcheck disable=SC2034  # Variables used by sourcing scripts
+# shellcheck disable=SC2155  # Declare and assign separately (acceptable in this codebase)
+#===============================================================================
+# Migration Agents - Shell-sourceable agent definitions for codebase migration
+#
+# Defines 5 specialized agents for safe, structured codebase migration:
+#   1. Codebase Archaeologist  - Read-only legacy code exploration
+#   2. Characterization Tester - Behavioral test generation
+#   3. Seam Detector           - Architecture seam identification
+#   4. Migration Planner       - Ordered migration plan generation
+#   5. Migration Reviewer      - Specialized migration review council member
+#
+# Usage:
+#   source autonomy/migration-agents.sh
+#   agent_codebase_archaeologist "/path/to/code" "/path/to/migration"
+#   agent_characterization_tester "/path/to/code" "/path/to/migration"
+#   migration_agent_dispatch "archaeologist" "/path/to/code" "/path/to/migration"
+#
+# Each function echoes a structured prompt suitable for claude/codex/gemini.
+# The migration directory stores all artifacts (docs/, tests/, seams.json, etc).
+#
+# Environment Variables:
+#   MIGRATION_STRATEGY   - "big-bang" (default) or "strangler-fig"
+#   MIGRATION_CONFIDENCE - Minimum confidence for auto-proceed (default: 0.8)
+#
+#===============================================================================
+
+MIGRATION_AGENTS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Strategy and confidence defaults
+MIGRATION_STRATEGY="${MIGRATION_STRATEGY:-big-bang}"
+MIGRATION_CONFIDENCE="${MIGRATION_CONFIDENCE:-0.8}"
+
+#===============================================================================
+# Base Prompts
+#
+# Each agent has a MIGRATION_AGENT_<NAME>_PROMPT variable containing its
+# core instructions. The agent functions compose these with runtime paths.
+#===============================================================================
+
+read -r -d '' MIGRATION_AGENT_ARCHAEOLOGIST_PROMPT << 'PROMPT_EOF' || true
+You are the Codebase Archaeologist -- a read-only exploration agent.
+
+Your mission is to thoroughly explore a legacy codebase and produce structured
+documentation that other migration agents will depend on. You must NOT modify
+any source files. Read-only access only.
+
+Tasks:
+1. Map all data flows (inputs, transformations, outputs, persistence)
+2. Identify error handling paths (try/catch, error codes, fallback logic)
+3. Catalog external dependencies (APIs, databases, file systems, services)
+4. Locate architectural seams (boundaries between modules, abstraction layers)
+5. Document implicit assumptions and conventions
+
+Output the following files in the migration docs/ directory:
+- architecture.md    -- High-level architecture with Mermaid diagrams
+- dependencies.md    -- External dependencies catalog with versions and usage
+- data-flows.md      -- Data flow documentation with Mermaid sequence diagrams
+- seams-initial.md   -- Initial identification of architectural seams
+
+Format requirements:
+- Use Mermaid diagram syntax for all visual documentation
+- Include file paths and line numbers for every finding
+- Mark confidence level (high/medium/low) for each architectural claim
+- List unknowns and areas requiring human clarification
+
+Constraints:
+- READ-ONLY: Do not create, modify, or delete any source files
+- Do not execute any code or tests
+- Do not install dependencies
+- Only create files within the migration docs/ directory
+PROMPT_EOF
+
+read -r -d '' MIGRATION_AGENT_CHARACTERIZATION_TESTER_PROMPT << 'PROMPT_EOF' || true
+You are the Characterization Tester -- a behavioral test generation agent.
+
+Your mission is to generate tests that capture WHAT the code currently does,
+not what it should do. These tests lock in existing behavior so that migration
+changes can be verified against the original implementation.
+
+Tasks:
+1. Read the archaeologist documentation for architecture understanding
+2. Generate characterization tests for every public interface
+3. Cover boundary values, failure modes, exact outputs, and side effects
+4. Run each test suite 3 times to detect flakiness
+5. Mark any flaky tests with a [FLAKY] annotation and exclusion flag
+
+Test coverage priorities (in order):
+- Public API endpoints and function signatures
+- Data transformation pipelines (exact input/output pairs)
+- Error handling paths (exception types, error messages, status codes)
+- Side effects (file writes, database mutations, API calls)
+- Edge cases (empty inputs, null values, max limits, unicode)
+
+Output:
+- tests/characterization/ directory with test files organized by module
+- features.json -- a JSON array of Feature objects matching this EXACT schema:
+
+  [
+    {
+      "id": "feat-001",
+      "category": "behavioral",
+      "description": "Login endpoint returns 401 for invalid credentials",
+      "verification_steps": ["Run test_login_invalid", "Check status code is 401"],
+      "passes": false,
+      "characterization_test": "tests/characterization/test_auth.py::test_login_invalid",
+      "risk": "medium",
+      "notes": "Also emits a warning log line"
+    }
+  ]
+
+  Field definitions:
+  - id (string, required): Unique identifier like "feat-001", "feat-002"
+  - category (string): One of "behavioral", "api", "data", "error-handling", "side-effect"
+  - description (string, required): What the code currently does (IS behavior)
+  - verification_steps (list of strings): Steps to verify this feature still works
+  - passes (boolean): Whether the characterization test passes (true/false)
+  - characterization_test (string): Path to the test that locks in this behavior
+  - risk (string): "low", "medium", or "high" -- risk if this behavior changes
+  - notes (string): Additional context, edge cases, or caveats
+
+  IMPORTANT: Do NOT use field names like "name", "file", "tests", "behavior",
+  or "flaky". Use ONLY the field names listed above.
+
+Constraints:
+- Tests must describe IS behavior, not SHOULD behavior
+- Never fix bugs in tests -- capture the bug as a test case
+- Each test must be deterministic (no timing-dependent assertions)
+- Use the project's existing test framework when available
+PROMPT_EOF
+
+read -r -d '' MIGRATION_AGENT_SEAM_DETECTOR_PROMPT << 'PROMPT_EOF' || true
+You are the Seam Detector -- an architecture seam identification agent.
+
+Your mission is to identify safe places in the codebase where interfaces,
+wrappers, or adapters can be introduced without changing behavior. These
+seams become the insertion points for migration changes.
+
+Tasks:
+1. Read archaeologist documentation (architecture.md, seams-initial.md)
+2. Read characterization test coverage (features.json)
+3. Identify function boundaries that can be wrapped
+4. Find interfaces with swappable implementations
+5. Detect config-driven behavior suitable for feature flags
+6. Locate feature flag candidates for gradual rollout
+
+For each seam, provide:
+- Location as a FLAT STRING like "src/auth.py:42:login_handler" (file:line:symbol)
+- Type: "wrapper" | "interface" | "config" | "feature-flag" | "adapter"
+- Confidence score (0.0 to 1.0)
+- Description of what can be changed at this seam
+- Suggested interface (how to abstract this seam)
+
+Confidence thresholds:
+- >= 0.8: Safe to auto-proceed with migration at this seam
+- 0.5 - 0.79: Requires human review before proceeding
+- < 0.5: High risk -- document but do not recommend for migration
+
+Output:
+- seams.json in the migration directory -- a JSON array of SeamInfo objects
+  matching this EXACT schema:
+
+  [
+    {
+      "id": "seam-001",
+      "type": "wrapper",
+      "location": "src/auth.py:42:login_handler",
+      "description": "Authentication handler can be wrapped with new provider",
+      "confidence": 0.85,
+      "suggested_interface": "AuthProvider interface with authenticate() method"
+    }
+  ]
+
+  Field definitions:
+  - id (string, required): Unique identifier like "seam-001", "seam-002"
+  - type (string, required): "wrapper", "interface", "config", "feature-flag", or "adapter"
+  - location (string, required): FLAT STRING as "file:line:symbol" -- NOT a nested object
+  - description (string, required): What can be changed at this seam
+  - confidence (float): 0.0 to 1.0
+  - suggested_interface (string): How to abstract this boundary
+
+  IMPORTANT: The "location" field MUST be a flat string like "src/foo.py:42",
+  NOT a nested dict like {"file": "...", "line": 42}. The engine will reject
+  nested location objects. Do NOT include "risk", "tests", or "auto_proceed"
+  fields -- these are not part of the SeamInfo schema.
+
+Constraints:
+- Every seam MUST have at least one characterization test covering it
+- Seams without test coverage get confidence capped at 0.3
+- Do not suggest seams that would require changing public API contracts
+PROMPT_EOF
+
+read -r -d '' MIGRATION_AGENT_PLANNER_PROMPT << 'PROMPT_EOF' || true
+You are the Migration Planner -- a plan generation agent.
+
+Your mission is to create a detailed, ordered migration plan based on the
+archaeologist documentation, characterization tests, and identified seams.
+The plan must be executable as a sequence of safe, reversible steps.
+
+Tasks:
+1. Read all migration artifacts (docs/, features.json, seams.json)
+2. Build a dependency graph between migration steps
+3. Order steps to minimize risk (independent changes first)
+4. Estimate token cost and risk level for each step
+5. Define rollback points at each step boundary
+
+Strategy selection:
+- "incremental": Gradual replacement with parallel old/new paths (default, safer)
+- "big_bang": All changes in one coordinated push (faster, riskier)
+
+Output:
+- migration-plan.json in the migration directory -- a MigrationPlan object
+  matching this EXACT schema:
+
+  {
+    "version": 1,
+    "strategy": "incremental",
+    "constraints": ["No downtime allowed", "Must preserve API compatibility"],
+    "steps": [
+      {
+        "id": "step-001",
+        "description": "Extract auth module behind interface",
+        "type": "refactor",
+        "files": ["src/auth.py", "src/login.py"],
+        "tests_required": ["tests/test_auth.py"],
+        "estimated_tokens": 5000,
+        "risk": "low",
+        "rollback_point": true,
+        "depends_on": [],
+        "assigned_agent": "",
+        "status": "pending"
+      }
+    ],
+    "rollback_strategy": "checkpoint",
+    "exit_criteria": {"all_tests_pass": true, "no_regressions": true}
+  }
+
+  MigrationPlan fields:
+  - version (integer): Plan version number, starts at 1
+  - strategy (string): "incremental" or "big_bang"
+  - constraints (list of strings): Migration constraints
+  - steps (list of MigrationStep): Ordered migration steps
+  - rollback_strategy (string): Overall rollback approach (e.g., "checkpoint")
+  - exit_criteria (dict): Conditions that must be met for migration to be complete
+
+  MigrationStep fields:
+  - id (string, required): Unique identifier like "step-001"
+  - description (string, required): What this step accomplishes
+  - type (string): "refactor", "rewrite", "config", or "test"
+  - files (list of strings): Files that will be modified -- NOT "files_affected"
+  - tests_required (list of strings): Tests that must pass after this step
+  - estimated_tokens (integer): Approximate token cost
+  - risk (string): "low", "medium", or "high" -- NOT "risk_level"
+  - rollback_point (boolean): true if a checkpoint should be created -- NOT a string
+  - depends_on (list of strings): Step IDs this step requires first
+  - assigned_agent (string): Agent assigned to execute this step (initially empty)
+  - status (string): "pending" (always start as pending)
+
+  IMPORTANT field name corrections:
+  - Use "files" NOT "files_affected"
+  - Use "risk" NOT "risk_level"
+  - "rollback_point" is a BOOLEAN (true/false), NOT a string
+  - Do NOT include "seams_used", "total_steps", "estimated_total_tokens",
+    or "risk_summary" -- these are not part of the schema
+
+Constraints:
+- Plan must be reviewed by the council before execution begins
+- Every step must have a rollback strategy
+- High-risk steps must be preceded by a checkpoint commit (rollback_point: true)
+- No step may affect files outside the declared files list
+PROMPT_EOF
+
+read -r -d '' MIGRATION_AGENT_REVIEWER_PROMPT << 'PROMPT_EOF' || true
+You are the Migration Reviewer -- a specialized council member for migration.
+
+Your mission is to review migration changes with a focus on behavioral
+equivalence that goes beyond simple test passing. You act as a devil's
+advocate, specifically looking for what tests might miss.
+
+Review checklist:
+1. Behavioral Equivalence
+   - Do outputs match for all input classes, not just tested inputs?
+   - Are error messages and error codes preserved exactly?
+   - Is timing behavior preserved (timeouts, retries, delays)?
+
+2. Performance Regression
+   - Are there new allocations in hot paths?
+   - Did data structure choices change (hash map vs tree, array vs linked list)?
+   - Are database query patterns preserved (N+1 queries, batch sizes)?
+
+3. API Contract Preservation
+   - Are all public function signatures identical?
+   - Are HTTP status codes, headers, and response shapes unchanged?
+   - Are error response formats preserved?
+
+4. Silent Behavior Changes
+   - Logging changes (format, level, destination)
+   - Metric emission changes (names, labels, values)
+   - Event ordering changes (race conditions introduced or removed)
+   - Default value changes (config, function parameters)
+
+5. What Tests Do Not Cover
+   - Concurrency behavior under load
+   - Resource cleanup (file handles, connections, locks)
+   - Initialization order dependencies
+   - Environment-specific behavior (OS, locale, timezone)
+
+Output:
+- Verdict: "approve" or "reject"
+- Rationale: Detailed explanation of the decision
+- Findings: List of specific issues found, each with:
+  - severity: "critical" | "high" | "medium" | "low"
+  - category: One of the 5 checklist areas above
+  - description: What was found
+  - location: File and line reference
+  - recommendation: How to address it
+
+Constraints:
+- Default stance is skeptical -- approve only when confident
+- A single critical finding means automatic rejection
+- High findings require explicit justification if approving
+- Must provide at least one observation per checklist category
+PROMPT_EOF
+
+#===============================================================================
+# Agent Functions
+#
+# Each function composes the base prompt with runtime context (paths,
+# strategy, configuration) and echoes the final prompt string.
+#===============================================================================
+
+# agent_codebase_archaeologist -- Read-only legacy code exploration
+#
+# Args:
+#   $1 - codebase_path: Path to the codebase to explore
+#   $2 - migration_dir: Path to the migration working directory
+agent_codebase_archaeologist() {
+    local codebase_path="${1:?Usage: agent_codebase_archaeologist <codebase_path> <migration_dir>}"
+    local migration_dir="${2:?Usage: agent_codebase_archaeologist <codebase_path> <migration_dir>}"
+
+    echo "$MIGRATION_AGENT_ARCHAEOLOGIST_PROMPT"
+    echo ""
+    echo "--- Runtime Context ---"
+    echo "Codebase path: $codebase_path"
+    echo "Migration directory: $migration_dir"
+    echo "Output directory: ${migration_dir}/docs/"
+    echo ""
+    cat <<'EOF'
+Begin by scanning the directory structure, then systematically explore
+each module. Start with entry points and trace outward.
+EOF
+}
+
+# agent_characterization_tester -- Behavioral test generation
+#
+# Args:
+#   $1 - codebase_path: Path to the codebase to test
+#   $2 - migration_dir: Path to the migration working directory
+agent_characterization_tester() {
+    local codebase_path="${1:?Usage: agent_characterization_tester <codebase_path> <migration_dir>}"
+    local migration_dir="${2:?Usage: agent_characterization_tester <codebase_path> <migration_dir>}"
+
+    echo "$MIGRATION_AGENT_CHARACTERIZATION_TESTER_PROMPT"
+    echo ""
+    echo "--- Runtime Context ---"
+    echo "Codebase path: $codebase_path"
+    echo "Migration directory: $migration_dir"
+    echo "Archaeologist docs: ${migration_dir}/docs/"
+    echo "Output directory: ${migration_dir}/tests/characterization/"
+    echo "Features manifest: ${migration_dir}/features.json"
+    echo ""
+    cat <<'EOF'
+Read the archaeologist documentation first, then generate tests
+module by module. Run each test file 3 times to detect flakiness.
+EOF
+}
+
+# agent_seam_detector -- Architecture seam identification
+#
+# Args:
+#   $1 - codebase_path: Path to the codebase to analyze
+#   $2 - migration_dir: Path to the migration working directory
+agent_seam_detector() {
+    local codebase_path="${1:?Usage: agent_seam_detector <codebase_path> <migration_dir>}"
+    local migration_dir="${2:?Usage: agent_seam_detector <codebase_path> <migration_dir>}"
+
+    echo "$MIGRATION_AGENT_SEAM_DETECTOR_PROMPT"
+    echo ""
+    echo "--- Runtime Context ---"
+    echo "Codebase path: $codebase_path"
+    echo "Migration directory: $migration_dir"
+    echo "Archaeologist docs: ${migration_dir}/docs/"
+    echo "Features manifest: ${migration_dir}/features.json"
+    echo "Auto-proceed threshold: ${MIGRATION_CONFIDENCE}"
+    echo "Output file: ${migration_dir}/seams.json"
+    echo ""
+    cat <<'EOF'
+Cross-reference every identified seam against the characterization
+test coverage in features.json. Cap confidence at 0.3 for untested seams.
+EOF
+}
+
+# agent_migration_planner -- Ordered migration plan generation
+#
+# Args:
+#   $1 - codebase_path: Path to the codebase to plan migration for
+#   $2 - migration_dir: Path to the migration working directory
+agent_migration_planner() {
+    local codebase_path="${1:?Usage: agent_migration_planner <codebase_path> <migration_dir>}"
+    local migration_dir="${2:?Usage: agent_migration_planner <codebase_path> <migration_dir>}"
+
+    echo "$MIGRATION_AGENT_PLANNER_PROMPT"
+    echo ""
+    echo "--- Runtime Context ---"
+    echo "Codebase path: $codebase_path"
+    echo "Migration directory: $migration_dir"
+    echo "Archaeologist docs: ${migration_dir}/docs/"
+    echo "Features manifest: ${migration_dir}/features.json"
+    echo "Seams file: ${migration_dir}/seams.json"
+    echo "Migration strategy: ${MIGRATION_STRATEGY}"
+    echo "Output file: ${migration_dir}/migration-plan.json"
+    echo ""
+    echo "Strategy \"${MIGRATION_STRATEGY}\" selected. Build the dependency graph,"
+    cat <<'EOF'
+then topologically sort steps for execution order.
+The plan must be reviewed by the council before any execution begins.
+EOF
+}
+
+# agent_migration_reviewer -- Specialized migration review council member
+#
+# Args:
+#   $1 - codebase_path: Path to the codebase under migration
+#   $2 - migration_dir: Path to the migration working directory
+agent_migration_reviewer() {
+    local codebase_path="${1:?Usage: agent_migration_reviewer <codebase_path> <migration_dir>}"
+    local migration_dir="${2:?Usage: agent_migration_reviewer <codebase_path> <migration_dir>}"
+
+    echo "$MIGRATION_AGENT_REVIEWER_PROMPT"
+    echo ""
+    echo "--- Runtime Context ---"
+    echo "Codebase path: $codebase_path"
+    echo "Migration directory: $migration_dir"
+    echo "Migration plan: ${migration_dir}/migration-plan.json"
+    echo "Features manifest: ${migration_dir}/features.json"
+    echo "Seams file: ${migration_dir}/seams.json"
+    echo "Characterization tests: ${migration_dir}/tests/characterization/"
+    echo ""
+    cat <<'EOF'
+Review the current migration state. Compare the codebase against the
+characterization tests and migration plan. Focus on what the tests
+do NOT cover and flag any silent behavior changes.
+EOF
+}
+
+#===============================================================================
+# Dispatcher
+#
+# migration_agent_dispatch(agent_type, codebase_path, migration_dir)
+#
+# Routes to the correct agent function by type name. Supports both
+# short names and full function names.
+#
+# Agent types:
+#   archaeologist | codebase-archaeologist
+#   tester        | characterization-tester
+#   seam          | seam-detector
+#   planner       | migration-planner
+#   reviewer      | migration-reviewer
+#===============================================================================
+
+migration_agent_dispatch() {
+    local agent_type="${1:?Usage: migration_agent_dispatch <agent_type> <codebase_path> <migration_dir>}"
+    local codebase_path="${2:?Usage: migration_agent_dispatch <agent_type> <codebase_path> <migration_dir>}"
+    local migration_dir="${3:?Usage: migration_agent_dispatch <agent_type> <codebase_path> <migration_dir>}"
+
+    case "$agent_type" in
+        archaeologist|codebase-archaeologist)
+            agent_codebase_archaeologist "$codebase_path" "$migration_dir"
+            ;;
+        tester|characterization-tester)
+            agent_characterization_tester "$codebase_path" "$migration_dir"
+            ;;
+        seam|seam-detector)
+            agent_seam_detector "$codebase_path" "$migration_dir"
+            ;;
+        planner|migration-planner)
+            agent_migration_planner "$codebase_path" "$migration_dir"
+            ;;
+        reviewer|migration-reviewer)
+            agent_migration_reviewer "$codebase_path" "$migration_dir"
+            ;;
+        *)
+            echo "ERROR: Unknown migration agent type: ${agent_type}" >&2
+            echo "Valid types: archaeologist, tester, seam, planner, reviewer" >&2
+            return 1
+            ;;
+    esac
+}

package/dashboard/__init__.py

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