{
  "markdown": "# Project Exodus: Graph-Guided, Agent-Assisted Legacy Code Migration Engine\n\n> **Autonomous Polyglot Migration Platform with Explicit Migration Debt Accounting & Verifiable Behavioral Parity**\n\n---\n\n## 1. Problem, Intended User & Value Proposition\n\n### Who is the Intended User?\n* **Enterprise Modernization & Platform Engineering Teams**: Organizations maintaining mission-critical legacy applications (Python, legacy JavaScript/TypeScript, Java) burdened by technical debt, security vulnerabilities, or performance bottlenecks, needing to modernize into high-performance, memory-safe target languages (Rust, modern Go, Zig, TypeScript).\n* **Software Architects & Migration Leads**: Engineers responsible for multi-package monorepos who need architectural visibility, topological scheduling, and guarantee of safety rather than black-box code dumps.\n\n### The Current Bottleneck\nWhen developers attempt automated migrations using raw LLMs (ChatGPT, Claude, Copilot) or naive ungrounded agents:\n1. **Context Blindness & Cycle Breakdown**: Unstructured single-file prompts cannot perceive cross-module dependency graphs, failing completely on circular dependencies, shared types, and bottom-up dependency ordering.\n2. **Hallucination & Silent Production Bugs**: When encountering unsupported dynamic constructs (e.g. `eval()`, runtime reflection, missing third-party C-bindings), raw LLMs hallucinate believable but non-functional dummy logic that passes superficial review but crashes in production.\n3. **Destructive Changes & Zero Safety Verification**: Traditional tools mutate the active working tree directly and lack in-loop verification. Without automated compiler and behavioral test gate checks (`cargo check`, `cargo test`, differential testing), generated code fails to compile or breaks behavioral parity over 60% of the time.\n\n### Why Solving It is Valuable in Practice\nProject Exodus eliminates the modernization bottleneck by turning code migration into an **evidence-backed, graph-guided, compiler-verified engineering discipline**:\n* **Topological Wave Scheduling**: Parses ASTs using Tree-sitter into an in-memory **Exodus Semantic Graph (ESG)** to detect cycles (Tarjan SCC) and migrate leaf libraries before callers.\n* **Non-Destructive Git Worktree Isolation**: All mutations and builds occur in isolated Git worktrees (`.exodus/worktrees/`) with automated lease tracking and crash recovery.\n* **Grounded Behavioral Contracts & Unit Verification**: Differential execution captures ground-truth runtime behavior from legacy code to verify target implementations before committing.\n* **Governed Migration Case Engine**: Failures are fingerprinted into cross-repository migration cases with bounded repair (maximum 3 iterations).\n* **Explicit Migration Debt Ledger**: Dynamic runtime constructs that cannot be statically mapped are emitted as explicit typed `todo!(\"Exodus Migration Debt: ...\")` stubs recorded in `.exodus/fallbacks.json` rather than fabricated dummy logic.\n* **Human-in-the-Loop Review**: Human approval gates are mandatory before breaking circular dependencies, approving plans, or executing high-impact transformations.\n\n---\n\n## 2. Improvement Changelog\n\nEvery iteration in Project Exodus is guided by empirical evidence and non-negotiable quality metrics:\n\n| Iteration | Hypothesis & What We Built | Empirical Evidence & Verification | Decision & Learning |\n|---|---|---|---|\n| **Baseline** | Naive direct translation: single-pass function mapping without dependency graph awareness, type mapping, or class state grouping. | Baseline achieved **0.0% outcome pass rate** on multi-file dependencies and cyclic structures (`.exodus/evaluation_scorecard.md`). | Direct prompting fails on multi-file topologies and class hierarchies; architectural graph modeling is mandatory. |\n| **Iteration 1: ESG & AST Engine** | Built Tree-sitter symbol extractor and the Exodus Semantic Graph (ESG) with Tarjan SCC cycle detection and wave planner (`exodus-parser`, `exodus-graph`, `exodus-planner`). | Correctly identified all cross-module imports and isolated cyclic clusters into human approval gates (`plan.json`). | **Kept**: Migrating dependencies in topological bottom-up order prevents cascading compiler breaks. |\n| **Iteration 2: Deterministic Mapping & Fallback Debt** | Implemented deterministic type transformations and explicit fallback stubs (`todo!`) with `MigrationDebt` ledger (`exodus-transform`, `exodus-fallback`). | Whole-fixture compilation rate increased to **63.6%**; untranslatable dynamic reflection (`eval()`) safely compiled without hallucinated logic. | **Kept**: Refusing to hallucinate business logic and recording explicit migration debt is strictly safer than fake code. |\n| **Iteration 3: Bounded In-Loop Repair** | Built bounded repair controller (`exodus-agent`) with maximum 3 auto-correction attempts per symbol against `rustc` JSON diagnostics. | Fixed common compiler diagnostics (missing mutability, missing derive traits, block scope scoping) within 1–2 iterations. | **Kept**: Bounding repairs to 3 iterations stops LLM runaway loops and prevents prompt token exhaustion. |\n| **Iteration 4: Worktree Isolation & Governed Case Engine** | Built isolated Git worktrees (`exodus-worktree`) and structural fingerprinting case engine (`exodus-case`). | Zero contamination of host repository; compiler failures automatically generated reusable migration cases without symbol leaks. | **Kept**: Worktree leasing guarantees safety; structural case fingerprints allow genuine cross-repo pattern reuse. |\n| **Iteration 5: Grounded Behavioral Unit Gate** | Implemented grounded unit verification contracts (`exodus-verifier`, `BehavioralContract`), differential Python capture, and atomic per-unit commits. | Verified 6 of 8 unit boundaries with honest classification (`Verified`, `Compatible`, `Degraded`, `Blocked`). | **Kept**: Unit-level contract execution catches functional regressions that whole-module compilation alone misses. |\n| **Iteration 6: Interactive Harness & Host Toolchain Scaffolding** | Built interactive REPL harness with host version manager integration (`.tool-versions`, `.mise.toml`, language version files, `git init`), target isolation, and human thought approval (`exodus-toolchain`, `exodus-cli`). | Full workspace test suite passes (100% across 13 crates); standalone and monorepo output directories cleanly isolated outside source root. | **Kept (Current State)**: Gives developers a familiar, safe, interactive CLI experience with complete host toolchain autonomy. |\n\n---\n\n## 3. Main Failure Mode & Our Hot Take\n\n### Observed Main Failure Mode\nWhen legacy code relies on dynamic runtime metaprogramming or runtime string evaluation (e.g. `eval(\"x + y\")`, dynamic `setattr` reflection, or unresolvable C-FFI pointer casting), static target compilation cannot guarantee equivalent behavior without embedding a full runtime interpreter. Naive AI coding tools hallucinate placeholder logic that silently passes tests but fails in production.\n\n### Our Hot Take\n> **\"An agent that refuses to lie and emits explicit, measurable migration debt is 10x more valuable in enterprise production than an agent that pretends to translate 100% of the code with silent runtime bugs.\"**\n\n---\n\n## 4. Clean Environment Reproduction Guide\n\n### Prerequisites\n* **Rust**: `1.80+` stable (`cargo`, `rustc`, `rustfmt`, `clippy`)\n* **Git**: `git` CLI (required for worktree isolation)\n* **Python 3**: Python 3.10+ (for running differential Python baseline or grounding fixture contracts)\n\n### Step 1: Clone & Verify Quality Gates\n```bash\ngit clone https://github.com/exodus-migration/exodus.git\ncd exodus\n\n# Run all workspace test suites across 13 crates (100% passing)\ncargo test --workspace\n\n# Check formatting and clippy lints\ncargo fmt --check\ncargo clippy --workspace --all-targets -- -D warnings\n```\n\n### Step 2: Build Release Binary\n```bash\ncargo build --release\n# Executable is located at ./target/release/exodus\n```\n\n### Step 3: Run Benchmark Suite (Exodus vs. Real Executed Baseline)\n```bash\n./target/release/exodus eval --fixtures fixtures --output .exodus\n```\n* **Expected Output**: Generates `.exodus/evaluation_scorecard.md`, `.csv`, and `.json` comparing Exodus against a real, executed non-graph baseline across whole-fixture and unit-level tiers.\n* **Approximate Runtime**: ~35–45 seconds (runs full `cargo check` and `cargo test` subprocesses on all 11 benchmark fixtures).\n* **Cost**: $0.00 USD (deterministic compiler and local AST analysis; $0 LLM cost in offline mode).\n\n### Step 4: Run Interactive Agent Harness\n```bash\n./target/release/exodus\n```\nInside the interactive REPL:\n```text\nexodus > /doctor                                     # Audit host toolchains (Node, Python, Go, Zig, Rust, Git)\nexodus > /analyze fixtures/01_typed_functions        # Extract AST & build Exodus Semantic Graph (ESG)\nexodus > /plan fixtures/01_typed_functions           # Compute dependency waves & approval checkpoints\nexodus > /approve .exodus/plan.json                  # Review and approve migration plan\n### Step 5: Self-Hosting & Dogfooding (Using Exodus as its Own Test Case)\nExodus can analyze and migrate its own workspace sub-crates as live test cases:\n```bash\n# Analyze an Exodus sub-crate\n./target/release/exodus /analyze crates/exodus-fallback\n\n# Plan migration for an Exodus sub-crate to Go or Zig\n./target/release/exodus /plan crates/exodus-fallback -t go\n\n# Execute migration of an Exodus sub-crate into an isolated target directory\n./target/release/exodus /migrate crates/exodus-fallback --to go --output target/exodus_dogfood_go\n```\n\n---\n\n## 5. Agent Instructions, Prompts & Safety Boundaries\n\nProject Exodus structures multi-agent coordination using strict role-based prompts and invariant contracts:\n\n### Non-Negotiable Invariants\n1. **Strict Metric Honesty**: Never fabricate verification statuses or benchmark baselines. All outcomes must derive from actual subprocess execution (`cargo check`, `cargo test`, diff execution).\n2. **Outcome Classification Tiers**:\n   * `Verified`: Passes compiler checks AND behavioral test contracts.\n   * `Compatible`: Compiles cleanly without stubs, awaiting test suite validation.\n   * `Degraded`: Relies on explicit `todo!` fallback stubs; recorded as `MigrationDebt`.\n   * `Blocked`: Fails compilation or transformation after bounded repair attempts.\n3. **Atomic Boundaries**: Classes and their methods group into a single verification unit.\n4. **Symbol-Agnostic Structural Hashing**: Case engine fingerprints hash graph topology and failure categories without symbol names.\n5. **Bounded Repair**: Maximum **3 iterations** per symbol before emitting fallback stubs.\n6. **Human Approval Gate**: Destructive actions, plan approvals, and cycle breaking require human authorization.\n\n---\n\n## 6. Submission Deliverables & Directory Structure\n\n* **`crates/`**: 19 modular, production-tested Rust crates (`exodus-core`, `exodus-parser`, `exodus-graph`, `exodus-planner`, `exodus-agent`, `exodus-transform`, `exodus-fallback`, `exodus-verifier`, `exodus-case`, `exodus-worktree`, `exodus-eval`, `exodus-kernel`, `exodus-toolchain`, `exodus-store`, `exodus-cost`, `exodus-cli`).\n* **`openwiki/`**: Complete Open Knowledge Format v0.2 wiki knowledge base (`openwiki/index.md`, `openwiki/human-approval-model.md`, `openwiki/user-and-migration-bottleneck.md`, etc.).\n* **`fixtures/`**: 11 synthetic and real-world legacy code fixtures with 100% grounded behavioral differential contracts.\n* **`REPRODUCTION.md`**: Clean environment reproduction guide.\n* **`VIDEO_SCRIPT.md`**: 5-minute storyboard and video walkthrough script.\n* **`TRAJECTORIES.md`**: Representative agent execution traces and tool interaction logs.\n\n",
  "bytes": 11732,
  "sha": "a8102e6705e3a245bae1e352c14825c544d11eaaabe8c30590916bab5d30c2f0",
  "repo_slug": "alikula-fadhili/exodus",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_alikula_fadhili_exodus_exodus_submission_ad0e0626/readme"
}