migrate-to-rust

レガシーコードベースを安全な Rust に移行する

システムアーキテクト、パフォーマンスエンジニア、Rust スペシャリストとして作業します。目標は、レガシーコードベースを 100% Safe で PGO により最適化された Rust に移行し、計測したテレメトリと一人称のエンジニアリング記録を scripts/telemetry.py を通じて記録することです。

実行契約とポータビリティ

リポジトリまたはローカルディレクトリ（{github_url} または {codebase_path}）を移行する際は、エージェント型ハーネス全体で以下の実行ルールに従ってください。

1. ステージ 0 外部コード確認ゲート：外部リポジトリをクローンし、そのビルドファイルを調査した後、レガシーコードのコンパイルまたは実行の前に、解決したビルドコマンド、実行コマンド、および対象ディレクトリをユーザーに提示し、確認を得てください。（ユーザーが実行するよう明示的に指示したローカルコードの場合、またはステージ 0 の確認が得られた場合は、そのまま進めてください。）
2. ステージ 1 からステージ 2 への継続的な進行：ステージ 0 のベースライン取得が完了したら、ホスト環境で自律的なツール実行が可能な場合は、マイルストーンの間で中断せずに、アーキテクチャ設計書（ステージ 1）の作成から Rust ワークスペースの実装と検証（ステージ 2）へ直接進んでください。
3. 上限付き自動自己修復（最大 5 回）：テスト、clippy のリント、または A/B 同等性チェックが失敗した場合は、 scripts/telemetry.py を通じて失敗を記録し、根本原因を診断して修正したうえで、上限の 5 回の自己修復試行（またはフェーズごとに 15 分）まで自動で再テストしてください。上限に達してもテストまたはシードに差異が残る場合は、無限にループするのではなく、部分的な状態を migration_telemetry.json に記録し、最終レポートに残存する問題を記載してください。
4. 検証目標と完了の定義：
   • #![forbid(unsafe_code)] を指定した Rust クレートが、cargo clippy の警告 0 件を目標にコンパイルできること（回避できない例外がある場合は記録してください）。
   • ユニット、統合、ドキュメント、およびプロパティベース（proptest）のテストが、分岐カバレッジ >= 95% を目標にすべて成功すること（回避できない例外がある場合は記録してください）。実行のたびに migration_telemetry.json に記録してください。
   • 文書化された数値誤差範囲（--max-abs-error）内で、N 個の決定論的シードにわたる A/B 差分出力の同等性が検証されていること。浮動小数点数、FMA、または PRNG の差異があれば、根本原因を特定して記録してください。
   • 4 つのベンチマーク段階（legacy_baseline、safe_rust、soa_simd、pgo_lto）をすべて計測して記録すること（llvm-profdata などのツールが利用できない場合は、適切に省略してください）。
   • 対話型 HTML インフォグラフィック（migration_infographic.html）を scripts/telemetry.py render-infographic でレンダリングすること。

エンドツーエンドのワークフローチェックリスト

3 つのステージにわたる進捗を追跡するため、このチェックリストをコピーしてください（詳細なコマンド手順とアーキテクチャ仕様については、 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：リポジトリの取得、テレメトリの初期化、レガシーのベースライン

リポジトリまたはディレクトリからコンテキストパラメーターを解決します。

Parameter	Placeholder	Resolution Strategy
ソース入力	{codebase_path} or {github_url}	GitHub URL（https://github.com/...）またはローカルファイルシステムのパスを受け付けます
元の言語／フレームワーク	{legacy_language}	ファイル拡張子とビルドファイル（CMakeLists.txt、Makefile、meson.build、pyproject.toml、pom.xml、*.f90、*.cpp）から自動検出します
ベースライン実行コマンド	{baseline_run_command}	README.md、CI ワークフロー（.github/workflows/*.yml）、Makefile、またはテストスクリプトから特定します
テレメトリ台帳	{workspace_dir}/migration_telemetry.json	Stage 0 の開始時に scripts/telemetry.py init で初期化します

Stage 0 の実行手順

1. リポジトリをクローンする（GitHub URL の場合）：クリーンなローカルディレクトリを選択し （デフォルトは ~/rust_migrations/{repo_name}。または要望があれば現在のワークスペース内）、 git clone {github_url} ~/rust_migrations/{repo_name} を実行します。
2. テレメトリを初期化し、レガシーコードベースをスキャンする：scripts/telemetry.py init --telemetry "{workspace_dir}/migration_telemetry.json" --project-name "{project_name}" --legacy-lang "{legacy_language}" を実行します。discovery バケットを開始し、レガシーソースディレクトリに対して scripts/telemetry.py scan-codebase --phase before を実行して、ベースラインのファイル数、コードの LOC、コメント密度（%）、最大ファイル LOC、ネストの深さ、平均関数長、raw ポインター／メモリの危険性を記録します。
3. レガシーのベースラインを確認し、ベンチマークを実行する：クローンした外部リポジトリのビルドまたは実行コマンドを実行する前に、解決されたビルドコマンド、{baseline_run_command}、および作業ディレクトリを提示し、ユーザーの確認を得ます。確認後、レガシープロジェクトをリリースモード（-O3 / Release）でコンパイルし、決定論的なシードを使ってゴールデン参照出力を取得し、ベースラインの実行時間（ms）とピーク RSS（MB）を測定して、scripts/telemetry.py log-benchmark --stage legacy_baseline で Stage 1 を記録します。

---

Stage 1：詳細監査、改善機会の発見、アーキテクチャ設計書

blueprint タイマーバケット（scripts/telemetry.py start-bucket --bucket blueprint）を開始し、リポジトリを調査して、発見した改善機会と潜在的なレガシーバグをすべて記録し（scripts/telemetry.py log-opportunity）、references/pgo_and_telemetry_guide.md の Section 2 で定義されている6セクション構成の Markdown 設計書を作成します。

Stage 1 から Stage 2 への移行：設計書を保存し、そのまま Stage 2 に進みます（ユーザーが設計書のみの計画を明示的に要求した場合を除きます）。

---

Stage 2：段階的で安全な Rust 実装、自己修復、PGO、インフォグラフィック

各手順で references/pgo_and_telemetry_guide.md のコマンド例と中核となるエンジニアリング基準に従います。

Step 1：安全な Rust ワークスペースの作成とモジュールの移植（rewrite バケット）

1. rewrite タイマーバケット（scripts/telemetry.py start-bucket --bucket rewrite）を開始します。
2. src/lib.rs と src/main.rs に #![forbid(unsafe_code)] を指定して Rust ワークスペースを初期化します。
3. 依存関係の順序に従って、決定論的 PRNG ラッパー、ドメイン型、モジュールを実装します（ファイルあたりの目標は <= 400 LOC とし、実行可能なドキュメントテストを含む完全な //! および /// rustdoc を記述します）。
4. scripts/telemetry.py log-benchmark で Stage 2（safe_rust）と Stage 3（soa_simd）のベンチマークを実行し、記録します。

ステップ 2：検証のるつぼ — テスト、失敗、診断、修正（test_heal バケット）

1. test_heal タイマーバケットを開始します（scripts/telemetry.py start-bucket --bucket test_heal）。
2. ユニットテスト、実行可能なドキュメントテスト、proptest による境界値テストを作成します。
3. cargo test --all-targets、cargo test --doc、cargo clippy --all-targets を実行します。
4. すべての反復を記録します（最大 5 回）：実行 1 の後、および以降の各実行後に、テストの総数、成功数、失敗数、カバレッジ％、Clippy の警告数、診断の概要、適用した修正を指定して scripts/telemetry.py log-test-run を呼び出します。失敗が 0 件、警告が 0 件になるまで（または、避けられない例外を記録したうえで 5 回の反復上限に達するまで）反復します。

ステップ 3：A/B 差分出力の同等性（parity バケット）

1. parity タイマーバケットを開始します（scripts/telemetry.py start-bucket --bucket parity）。
2. ドキュメントに記載された許容誤差内で {baseline_run_command} と Rust バイナリを比較しながら、N 個の決定論的なシードを使って自動 A/B 差分ハーネスを実行します。
3. scripts/telemetry.py log-parity-run を使って各同等性チェックの反復を記録します。いずれかのシードで許容誤差を超える差異が生じた場合は、最初に差異が生じたステップを二分探索し、不一致を修正して再実行します（最大 5 回）。

ステップ 4：プロファイル誘導最適化（PGO）と最終ベンチマーク（pgo_bench バケット）

1. pgo_bench タイマーバケットを開始します（scripts/telemetry.py start-bucket --bucket pgo_bench）。
2. references/pgo_and_telemetry_guide.md に記載された LLVM PGO ワークフローを実行します。RUSTFLAGS="-Cprofile-generate=./pgo-data" を指定してビルドし、代表的なワークロードを実行して、llvm-profdata でプロファイルを統合します。その後、RUSTFLAGS="-Cprofile-use=./pgo-data/merged.profdata" と lto = "fat" を指定して再ビルドします（または、llvm-profdata が利用できない場合は、ドキュメントに記載された -Ctarget-cpu=native の代替手段を使用します）。
3. PGO バイナリでテストと A/B 同等性チェックが引き続き成功することを確認し、実行時間とピーク RSS を測定して、scripts/telemetry.py log-benchmark --stage pgo_lto でステージ 4（pgo_lto）を記録します。

ステップ 5：最終調査、AI の一人称ストーリー、ビジュアルインフォグラフィック

1. src/ を対象に scripts/telemetry.py scan-codebase --phase after を実行し、最終 LOC、<= 400 LOC の準拠状況、コメント／rustdoc の密度、実行可能なドキュメントテスト、ネストの深さ、unsafe ブロック数を記録します。

2. 変更前と変更後のコードスポットライトを記録し（scripts/telemetry.py log-spotlight）、一人称 AI ストーリーの各章を入力します（scripts/telemetry.py set-story）。

3. pgo_bench タイマーバケットを終了し、インタラクティブな HTML インフォグラフィックを生成します（{skill_dir} はこの SKILL.md を含むディレクトリです）。

   python3 "{skill_dir}/scripts/telemetry.py" render-infographic \
     --telemetry "{workspace_dir}/migration_telemetry.json" \
     --out "{output_dir}/migration_infographic.html" \
     --scope-summary "{short_summary_of_ported_modules}"
   

4. 生成された migration_infographic.html レポートと、測定した変更前後の主要な指標を参照する簡潔なエグゼクティブサマリーを出力します。

---

同梱リソース

• テレメトリとインフォグラフィックの CLI： scripts/telemetry.py
• エンジニアリング標準、ブループリント仕様、PGO とテレメトリのレシピ： references/pgo_and_telemetry_guide.md
• インタラクティブ HTML インフォグラフィックのテンプレート： references/infographic_template.html