/migrate-to-rust

name: migrate-to-rust
metadata:
  version: "1.0.0"
  category: ApplicationDevelopment
description: >-
  Clones, analyzes, plans, and migrates legacy codebases (C++, Fortran, Java,
  Python, C, Shell) from a GitHub URL or local directory to a modern,
  high-performance, deterministic, 100% Safe Rust architecture, tracking live
  telemetry across every task bucket, test failure/fix cycle, and
  Profile-Guided Optimization (PGO) stage, and producing a first-person AI
  storytelling report and interactive HTML infographic. Use when migrating a
  GitHub repository or local codebase to Rust, porting legacy C++, Fortran,
  Python, or Java workloads to memory-safe Rust, designing Struct-of-Arrays
  (SoA) or SIMD Rust architectures, or optimizing Rust ports with LLVM PGO.
  Don't use for unrelated non-Rust refactoring or single-line syntax questions.

Migrate Legacy Codebases to Safe Rust

Act as a Systems Architect, Performance Engineer, and Rust Specialist. Your goal is to migrate legacy codebases into 100% Safe, PGO-tuned Rust while recording measured telemetry and a first-person engineering narrative via [`scripts/telemetry.py`](scripts/telemetry.py).

Execution Contract & Portability

When migrating a repository or local directory (`{github_url}` or `{codebase_path}`), follow these execution rules across agentic harnesses:

1. **Stage 0 External Code Confirmation Gate**: After cloning an external repository and inspecting its build files, **present the resolved legacy build command, run command, and target directory to the user and obtain confirmation before compiling or executing cloned code**. (For local code that the user explicitly instructed you to run, or once Stage 0 confirmation is granted, proceed directly.) 2. **Continuous Stage 1 -> Stage 2 Progression**: Once Stage 0 baseline capture is complete, proceed directly from writing the Architectural Blueprint (Stage 1) into implementing and verifying the Rust workspace (Stage 2) without pausing between milestones, where the host environment permits autonomous tool execution. 3. **Bounded Automated Self-Healing (Max 5 Iterations)**: When tests, `clippy` lints, or A/B parity checks fail, log the failure via [`scripts/telemetry.py`](scripts/telemetry.py), diagnose and fix the root cause, and re-test automatically up to a budget of **5 self-healing iterations** (or 15 minutes per phase). If any test or seed still diverges after the budget is exhausted, record the partial state in `migration_telemetry.json` and document the remaining gap in the final report rather than looping indefinitely. 4. **Verification Targets & Definition of Done**:

• `#![forbid(unsafe_code)]` Rust crate compiles with a target of `0`

`cargo clippy` warnings (any unavoidable exception must be documented).

• Unit, integration, doc, and property-based (`proptest`) tests pass with

a target of `>= 95%` branch coverage (any unavoidable exception must be documented), with every run logged in `migration_telemetry.json`.

• A/B differential output parity is verified across `N` deterministic

seeds within a documented numerical epsilon (`--max-abs-error`), with any floating-point/FMA/PRNG divergence root-caused and logged.

• All 4 benchmark stages (`legacy_baseline`, `safe_rust`, `soa_simd`,

`pgo_lto`) are measured and logged (or omitted cleanly if a tool such as `llvm-profdata` is unavailable).

• The interactive HTML infographic (`migration_infographic.html`) is

rendered via `scripts/telemetry.py render-infographic`.

End-to-End Workflow Checklist

Copy this checklist to track progress across the three stages (detailed command recipes and architectural specifications are in [references/pgo_and_telemetry_guide.md](references/pgo_and_telemetry_guide.md)):

- [ ] Stage 0: Acquire repo, initialize `migration_telemetry.json` (`discovery` bucket), scan legacy codebase, confirm resolved build/run commands, and benchmark baseline
- [ ] Stage 1: Audit legacy code (`blueprint` bucket), log opportunities & latent legacy bugs, and generate 6-section Architectural Blueprint
- [ ] Stage 2.1: Scaffold `#![forbid(unsafe_code)]` Rust workspace & deterministic PRNG parity layer (`rewrite` bucket)
- [ ] Stage 2.2: Implement core domain types & SoA/SIMD kernels (<= 400 LOC/file target, full rustdoc) & benchmark `safe_rust` + `soa_simd`
- [ ] Stage 2.3: Run Verification Crucible (`test_heal` bucket, max 5 iterations) — log initial test failure % and each self-healing fix
- [ ] Stage 2.4: Run A/B differential parity harness (`parity` bucket, max 5 iterations) across N seeds within documented epsilon tolerance
- [ ] Stage 2.5: Run LLVM Profile-Guided Optimization (`pgo_bench` bucket), scan final Rust codebase, and render `migration_infographic.html`

--------------------------------------------------------------------------------

Stage 0: Repository Acquisition, Telemetry Init & Legacy Baseline

Resolve context parameters from the repository or directory:

Parameter | Placeholder | Resolution Strategy :-------------------------------- | :----------------------------------------- | :------------------ **Source Input** | `{codebase_path}` or `{github_url}` | Accept a GitHub URL (`https://github.com/...`) or a local filesystem path **Original Language / Framework** | `{legacy_language}` | Auto-detect from file extensions and build files (`CMakeLists.txt`, `Makefile`, `meson.build`, `pyproject.toml`, `pom.xml`, `*.f90`, `*.cpp`) **Baseline Run Command** | `{baseline_run_command}` | Identify from `README.md`, CI workflows (`.github/workflows/*.yml`), `Makefile`, or test scripts **Telemetry Ledger** | `{workspace_dir}/migration_telemetry.json` | Initialized via `scripts/te