ln-831-oss-replacer

パス: ファイルパス（references/、../ln-*）は、このスキルディレクトリからの相対パスです。

ln-831-oss-replacer

タイプ: L3 ワーカー
カテゴリー: 8XX 最適化

ln-645-architecture-modernization-auditor の OSS 置き換え計画を実行します。実用可能な OSS の代替手段があるカスタムモジュールごとに、パッケージをインストールし、インポートを書き換え、検証を実行してから、変更を一括して保持または破棄します。

---

概要

項目	詳細
入力	監査結果の移行計画、または対象モジュール
出力	置き換え済みモジュールと、機械可読なモダナイゼーションの概要
連携先	ln-645-architecture-modernization-auditor が候補を特定し、ln-831 が実行します

---

ワークフロー

フェーズ: 事前確認 -> 計画の読み込み -> 優先順位付け -> 置き換えループ -> レポート

---

フェーズ 0：事前確認

確認項目	必須	不足している場合の対応
移行計画または対象モジュール	はい	置き換えをブロックします
テストインフラストラクチャ	はい	置き換えをブロックします
パッケージマネージャーの利用可否	はい	置き換えをブロックします
ワークスペースのベースラインが安全であること	はい	管理された実行ではコーディネーターがすでに準備しています。単独実行ではローカルで保護し、ロールバックできるようにします

必ず読み込むこと: テストの検出には references/ci_tool_detection.md を読み込みます。
ツールポリシー：ホストの AGENTS.md にある MCP の設定に従います。ホストのポリシーがない場合、または MCP の動作が不明確な場合に限り、references/mcp_tool_preferences.md と references/mcp_integration_patterns.md を読み込みます。

利用可能な場合は、ローカルコードの編集と読み取りに hex-line を最初に使い、ファイル間の参照チェックによって置き換えの安全性が大幅に向上する場合は、hex-graph を最初に使います。MCP が利用できない、サポートされていない、またはインデックス化されていない場合は、組み込みの Read/Grep/Glob/Bash を使って続行し、概要にフォールバックしたことを記載します。

実行時の連携

管理された実行では、ln-830 から決定的な runId と正確な summaryArtifactPath を受け取ります。
単独実行も引き続きサポートされます。実行時引数が省略された場合は、応答を返す前に単独実行用のスコープ付き成果物を生成します。

---

フェーズ 1：移行計画の読み込み

監査レポートから、次の項目を抽出します。

フィールド	説明
custom_module	カスタム実装へのパス
loc	カスタムモジュールのコード行数
oss_package	推奨される OSS の置き換え候補
confidence	HIGH、MEDIUM、または LOW
api_mapping	カスタム関数と OSS の同等機能との対応

監査レポートがない場合は、対象モジュールを分析し、Context7 または Ref を検索して実用可能な OSS の代替手段を探します。

必ず読み込むこと: references/research_tool_fallback.md を読み込みます。

---

フェーズ 2：置き換えの優先順位付け

優先度	条件
1	信頼度が HIGH で、200 LOC を超える
2	信頼度が HIGH で、100～200 LOC
3	信頼度が MEDIUM で、200 LOC を超える
4	信頼度が MEDIUM で、100～200 LOC
スキップ	信頼度が LOW

---

フェーズ 3：置き換えループ（保持／破棄）

モジュールごとのサイクル：

FOR each replacement candidate:
  1. INSTALL: add the OSS package
  2. REWRITE: update imports and call sites using api_mapping
  3. VERIFY: run tests
     IF tests fail -> DISCARD and revert all changes for this candidate
  4. KEEP: only after verification passes
  5. DELETE: remove old custom module after keep
  6. LOG: record result for the final report

停止条件：

条件	対応
すべての候補を処理済み	停止してレポートします
破棄が 3 回連続	警告し、手動レビューのため停止します
テストインフラストラクチャ自体が壊れる	停止し、最後に正常と確認された状態に戻します
信頼度のしきい値を超える候補がない	停止し、実用可能な置き換え候補がないことをレポートします

破棄時のアトミックなロールバック：

手順	ロールバック操作
パッケージをインストール済み	アンインストールします
ファイルを変更済み	モジュールファイルを復元します
ロックファイルが変更済み	ロックファイルを復元します

安全ルール：

ルール	説明
一度に 1 つのモジュール	複数のモジュールを同時に置き換えてはいけません
API シグネチャを変更しない	公開インターフェースとの互換性を維持する必要があります
テストが必須	リスクが不明確な場合、カバレッジのないモジュールはスキップします
信頼度のゲート	信頼度が LOW の置き換え候補はスキップします

---

フェーズ 4：結果の報告

フィールド	説明
source	監査レポートのパスまたは対象モジュール
candidates_total	置き換え候補の合計
replacements_applied	置き換えに成功したモジュール
replacements_discarded	理由を添えて失敗として破棄した置き換え
replacements_skipped	信頼度が低い、またはテストが不足しているためスキップした置き換え
loc_removed	削除したカスタムコードの行数の合計
packages_added	新たにインストールした OSS パッケージ
details[]	置き換えごとの概要
artifact_path	書き出した場合の、永続的なワーカーレポートのパス

---

設定

Options:
  audit_report: "docs/project/codebase_audit.md"
  target_module: ""
  min_confidence: "MEDIUM"
  run_tests: true
  require_test_coverage: true
  delete_old_module: true

---

エラー処理

エラー	原因	解決策
パッケージが見つからない	OSS パッケージ名が変更された	新しいパッケージ名を現在のドキュメントで検索する
API の不一致	マッピングが実際のライブラリ API と異なる	ドキュメントを確認し、修正方法が明確な場合に限り再試行する
循環依存	新しいパッケージが現在のアーキテクチャと競合する	スキップし、手動での対応が必要であることを報告する
テストカバレッジがない	自動置き換えのリスクが高すぎる	スキップして報告する

---

参考資料

• ../ln-645-architecture-modernization-auditor/SKILL.md
• references/ci_tool_detection.md
• references/research_tool_fallback.md
• references/epistemic_protocol.md

---

ランタイム概要アーティファクト

必ず読み込んでください： references/coordinator_summary_contract.md を読み込みます

modernization-worker のサマリーエンベロープを出力します。

マネージドモード：

• ln-830 は決定的な runId と正確な summaryArtifactPath を渡します
• サマリーを指定された summaryArtifactPath に書き込みます

スタンドアロンモード：

• runId と summaryArtifactPath は省略します
• .hex-skills/runtime-artifacts/runs/{run_id}/modernization-worker/ln-831--{identifier}.json に書き込みます

モニター（2.1.98+）： インストールとテストの検証ループに 30 秒を超える見込みがある場合は、Monitor を使用します。代替手段：Bash(run_in_background=true)。

完了の定義

• 移行計画を読み込むか、対象モジュールを分析済み
• 信頼度とコード削減効果に基づいて候補に優先順位を付与済み
• 各置き換えをアトミックに実行し、保持または破棄を検証済み
• 破棄した置き換えを完全にロールバック済み
• 保持する置き換えでは、検証の合格後にのみ古いカスタムコードを削除済み
• 適用、破棄、スキップした置き換えと削除した LOC をレポートに記録済み
• マネージドパスまたはスタンドアロンパスに modernization-worker のサマリーアーティファクトを書き込み済み

---

バージョン： 1.0.0 最終更新日： 2026-03-08