Replace Strategy

Replace Strategy

「仕様を変えずにアプリケーションをリプレイスする」作業の入口を担う。現行の挙動を証拠として固定し、別実装で再現し、差分ゼロを検証するループの最初の戦略判断を、推測ではなく実測に基づいて行わせる。

自分では実装しない。 測定し、戦略を決めさせ、機能に分解し、姉妹スキルへ振り分ける役割に徹する。

使い方

replace-strategy setup
replace-strategy issues [--feature <slug>...]
replace-strategy status

• issues は --feature <slug>... で対象機能を選択できる。省略時は未起票の機能から対話選択する
• モード未指定時はどのモードかをユーザーに確認する（setup 未完了なら setup を提案する）
• 自然文でも発動する:「リプレイス戦略を立てて」「リプレイスを始めたい」「現行アプリを測定して」

前提

• ツール: gh（GitHub CLI）, git
• 前提スキル: issue-create（issues モードの起票委譲先）、browser-test（現行アプリのブラウザ操作の作法）、 current-environment-bootstrap（現行環境の由来が「受領資産からの再構築」のときだけ。委譲先。下記「setup モード」の手順 2・4）
• MCP: chrome-devtools MCP（セマンティクス測定に必須）
• 固定の技術スタック前提（スキル群共通。ここに列挙したもの以外は固定しない）:
  • 新側フロントエンド・バックエンド: TypeScript
  • パリティスイート: Playwright（TypeScript）
  • golden-dataset の投入ツール: TypeScript（SQL 可）
  • テキスト成果物: Git
  • Issue・PR・委譲先: GitHub（gh）
• 利用者が選ぶもの（設定・references で受け取る。スキル本体に固有名を書かない）: 新側アプリの骨格（下記）、生成先リポジトリのコーディング規約（生成物ごとに引き先が変わる。常に新側とは限らない）、新 UI コンポーネントライブラリと design token、現行・新の DB とその型・意味論の差、 検証コマンド一式（静的解析・テスト。全体走査の full と差分限定の diff の 2 列）、実行対象環境（targets）、環境変数の用意方法。現行アプリのスタックは測定で把握する
• 新側アーキテクチャは本スキル群の対象外（フレームワーク・バックエンド構成・ORM・レイヤ／ディレクトリ構成・API 設計方針・ホスティング／リリース構成・実行基盤と利用マネージドサービス）。 言語は上記のとおり TypeScript 固定であり、骨格はその上の選択（言語まで利用者が選べる意味ではない）。 事前に決定済みで、新側リポジトリは骨格がスキャフォールド済みである前提に立つ。 骨格は現行アプリの測定からは決まらず（組織の制約・運用・既存資産・人員で決まる）、スキルが決めれば「測定できなければ停止する」規律が崩れるため、 setup は決定の確認と記録だけを行う（new.stack / references.architecture。正本は references/project-config.md の「新側アーキテクチャ」）
• IaC / CI-CD パイプラインはスキル群の必須要件ではない。 新側は side: new のローカル target 1 つ（start ＋ check_urls で起動・稼働確認できる環境）だけで全工程が成立する。 配信型 target（develop / preview 等、デプロイで更新される環境）を targets に登録する場合にだけ、そのパイプラインが動いていることが前提になる（commit_check / on_diff はその環境のための任意キー）。 パイプライン・IaC の新規構築は対象外（事前条件）で、区分の正本は references/scope.md「スキルが行う作業の範囲」

厳守の制約（禁止事項）

• 測定せずに戦略を語らない。 測れない場合は戦略へ進まず停止する。推測は「未測定」と明記する
• 仕様確認は十分な証拠が得られる最小コストの経路から始める。 選択した現行 target から取得し、対象版・採取時点・条件を追跡できる実行ログ／観測記録 → 現行ソースコード → API の実動作 → UI の実動作の順に調べ、 下位の証拠だけでは挙動を確定できない場合に限って次へ上げる。これは調査コストが実行ログ／観測記録 < ソースコード < API 操作 < UI 操作の順に高くなるためで、必要な証拠が得られた時点で止め、API／UI 操作は不足する場合だけ行う。 設計書・仕様書・受領ログを含む受領資料は調査候補の抽出に使ってよいが、現行挙動の確定根拠にはしない。UI 固有の表示・操作は UI で確定し、安価な経路で代用しない
• 現行テスト環境が無いまま測定へ進まない。 現行環境の由来（current.origin）が「受領資産からの再構築」なら、current-environment-bootstrap の引き渡し完了（.replace/bootstrap/metadata.json の status: handed-off）まで測定・戦略へ進まない。再構築を自分で代行しない（推測で建てた環境を正解の基準にすると、以降の全比較がその誤りを追認する）
• LLM に「差分があるか」を聞かない。 差分の検出は決定論的ツールの仕事、LLM の仕事は分類（要対応／許容／環境ノイズ）
• モデルの主観（「同じに見えます」）を収束根拠にしない。 収束判定は決定論的ツールが行う
• 振る舞い保存と品質改善を同じフェーズで狙わない。 忠実な移植は良い性質も悪い性質も等しく運ぶ
• id・name を比較のアンカーにしない。 原則は role ＋アクセシブルネーム
• カタログサイト・部品ベンダーの機能一覧を比較の正解にしない。 どちらも「確認すべき状態の網羅リスト」の生成源であり、正解は動いている現行アプリ
• 現行アプリを変更しない。 比較のために現行アプリのコード変更（ログ挿入・SMTP 迂回・プロキシ挿入など）が必要なもの、または比較自体が現実的でないものはスコープ外とし、gaps に「手動検証が必要」として記録する（確認済みにしない）
• 対応範囲を推測で決めない。また一覧を各所へ転記しない。 対象・対象外・条件付きの一覧は references/scope.md が正本で、各スキル・各 references は実行時の行動だけを持つ。 同ファイルは比較・検証の範囲（現・新を比較して合否を出すか）とスキルが行う作業の範囲（スキルが行うか事前条件か）の 2 一覧を持ち、軸が違うため混同しない。 判断に迷ったら同ファイルで引き、読めない環境では対象外と断定せず gaps に未検証として残す
• 依存の判断基準を、リポジトリに無い土台の存在を前提に組まない。 ライセンス拒否リスト・供給網ポリシー・バンドルサイズ上限などは、あればそれに従い、無ければ方針の要否をユーザーに確認する（スキル既定の拒否リスト・閾値・待機日数を持ち込まない）
• シークレットの値をログ・標準出力・成果物・設定ファイルに出さない。 設定ファイルには環境変数名だけを持つ。ユーザーが値を提示してきた場合も復唱しない（コマンド例にも埋め込まず、環境変数名で置き換える）

プロジェクト設定の解決

現・新のリポジトリ、実行対象環境（targets。環境名で複数定義し --target で選択）、DB 接続の環境変数名、成果物の保存方針、意図的差異レジストリ、references（利用者が選ぶ知識の注入）はリポジトリごとに異なる。 設定ファイル .config/skills/shoji9x9/skills.yml の skills.replace-strategy のスキーマと解決手順は references/project-config.md を参照する。

設定は対象プロジェクトに 1 つで全スキルが読めるため、下流スキル（姉妹スキル）はこのキーを直接読む（転記しない）。

setup モード

依存確認 → 現行環境の由来の確認 → 対話セットアップ → 現行環境の再構築（必要時のみ）→ 測定 → 戦略決定 → レジストリ作成 → 機能インベントリ → 共通部品の依存決定、の順に進める。

1. 依存の確認: 前提スキル（issue-create / browser-test）のインストール状況と chrome-devtools MCP の有効性を確認する。未導入・無効なら導入手順（gh skill install shoji9x9/skills <name>、MCP の設定）を示す。MCP が無いままでは測定できないため、手順を示したうえで停止する
2. 現行環境の由来の確認: 測定対象になる現行テスト環境が次のどちらかを確認し、current.origin へ記録する（意味論の正本は references/project-config.md の「現行環境の由来」）。 由来を推測で決めない——現行アプリの URL が設定に書けることは、その環境が動いていることの証拠ではない
   • managed（既存の管理済みテスト環境）: 自社で管理している動作可能な環境がある。以降は従来どおり進める（手順 4 は行わない）
   • received-assets（受領資産から自社で再構築する）: 先方から受領した資産だけがあり、比較基準になる環境をこれから建てる。 受領資産の置き場所を current.received_assets（1 つ以上のパス）に記録し、current-environment-bootstrap のインストール状況をここで確認する （未導入なら gh skill install shoji9x9/skills current-environment-bootstrap を示して停止する。再構築を代行しない）
3. 対話セットアップ: 次を対話で確認し設定ファイルへ保存する。技術スタックはスキル本体に書かず、設定で受け取る。 シークレットの扱いは references/project-config.md の「シークレットの扱い」に従い、接続確認を最初に行い、繋がらなければ早期に失敗する
   • 現・新のリポジトリ、起動ラッパー
   • 新側アーキテクチャの確認と記録: 事前に決定済みの骨格を確認し、スタックの列挙を new.stack に、決定記録のドキュメントのパスを references.architecture に記録する。 骨格を決めず、下書きも生成しない（未決なら決定を促し、references.architecture は空値の枠だけを残す。正本は references/project-config.md の「新側アーキテクチャ」）
   • 実行対象環境（targets）: 現側は測定対象のテスト環境、新側は local-dev / develop 等。環境ごとに side（必須）・url・ url_command（URL が実行ごとに決まる環境で url の代わりに）・api_url（UI と API が別 origin のときだけ）・ DB（環境変数名と投入してよいかの seedable）・認証（ロールごとの環境変数名のみ）・禁止操作・pre_commands / start / check_urls・commit_check（start を持たない配信型環境で稼働中コミットを確認するコマンド）・ 側ごとの default（current / new で 1 つずつ）・on_diff を確認する。スキーマ不変条件は references/project-config.md「実行対象環境」、選択規則は同節の「選択規則」に従う。 先に「新側は当面ローカルのみか、配信型環境（develop / preview 等）も使うか」を確認する——ローカルのみなら commit_check / on_diff は確認せず、 配信型環境が要求する CI/CD パイプラインの前提もかからない（前提の条件は上記「前提」）。後から配信型環境を足せるので、この時点で無理に決めさせない
   • ゴールデンデータセットの実体（dataset_mode）: DB なら db（既定）、リポジトリ内の静的データなら static を選び、static では投入ツールが生成・削除してよい dataset_static_paths を確定する。 seedable と dataset_static_paths は投入の設定由来ゲートであり、既定は deny（書かなければ投入されない）。実データを持つ環境は seedable を付けずに読み取り専用として登録する。正本は references/project-config.md の「データセットの実体」
   • ファイルストレージ（uses_storage / targets[].storage）: アップロード先・ファイル出力先のストレージを使うかを確認し（dataset_mode とは直交する別軸——dataset_mode に第 3 の値を足さない）、 使うなら環境ごとに接続の環境変数名・書き込み範囲（パスまたは <bucket>/<prefix>）・アップロード経路（direct / presigned）を確認する。 投入ゲート（storage.seedable）は既定 deny で、ストレージ実体へのゴールデンデータ投入は v1 スコープ外（宣言だけを残し、ストレージ依存の検証は gaps に未検証として記録させる）。正本は references/project-config.md の「ファイルストレージ」
   • 検証コマンド（verification_commands）: 完了前に実行する静的解析・テスト等を、走る範囲で full（全体走査）と diff（変更ファイルだけ）の 2 列に分けて確定する （環境準備・起動は含めない。それらは target の pre_commands / start）。full は parity-replace の完了判定に必須のため、無いままにしない。 full は生成先リポジトリの必須 CI から導出する。 対象ブランチに有効な ruleset は gh api --paginate で全ページ・全 rule type を取得し、classic branch protection も読み、 必須 status check と ruleset の必須 workflow を漏れなく棚卸しする。workflow の job と、その job が呼ぶ script / reusable workflow の実行コマンドまで辿って突き合わせ、取得不能・未知の強制 rule・対応不明・説明の無い差があれば確定しない。 status check の context は文字列から job 名を推測せず、実在 PR / commit の check run name から workflow / job へ辿る。同名 job・matrix 展開・check run 未生成などで一意に対応できなければ確定しない。 推奨は、必須 CI job と full が同じリポジトリ内の全体検証コマンド 1 本を呼ぶ形である。畳めない場合は、必須 CI と full の対応・対象外理由を記録し、 どちらかの変更で落ちるプロジェクト側の乖離検査を必須 CI に含める。setup 時点の目視比較だけでは、その後の CI 変更を検出できないため完了にしない。詳細は references/project-config.md「必須 CI との整合」。 full はフック設定を見るだけで埋めない——コミット前フックが同じツールを差分限定で回していることは多く、スクリプト側が引数をどう使うかまで読まないと全体走査か判別できない。 判別できないコマンドは全体走査の起動形をここで確認し、全体走査の起動形が無いツールは full に入れず未検査として .replace/strategy.md の「未検証領域の扱い」へ記録する。 どちらの列にも auto-fix 付きの起動形（フォーマッタの書き込みモード・リンタの --fix）を置かない——対象を黙って直したうえで必ず成功するため、ゲートにならない。 差分があれば非ゼロで終わるチェック形を確認し、チェック形かどうかは 1 回通した後に作業ツリーの差分が増えないことを実測して確かめる（--check の有無で判断しない）。 詳細は references/project-config.md「走る範囲」。 golden-dataset の投入ツール（dataset_tool_dir）と parity-suite のスイート（parity_suite_dir）もこの列で検証されるため、 それらのパスを検査対象に含めるかをここでユーザーに確認する（含めない選択も可。下流は範囲を勝手に広げず「含まれていない」と記録するだけなので、ここで決めないと恒久的に未検査になる）
   • 規約の機械検査の仕分け: references.coding_conventions の規約項目を、verification_commands.full で落ちるものと落ちないものに分け、未検査の項目を記録する。 判定は「規約に対応するルール設定があるか」ではなく「その規約を破った入力が full で落ちるか」で行う。 未検査のままだと、規約に従ったつもりの箇所が parity-replace の敵対的レビューやユーザー指摘で初めて出て、機能ごとに「指摘を受けてから検査を足す」を繰り返す。 ルール・フォーマッタ設定で表現できる項目はここで整備を促し、足した検査は full へ載せる。残った未検査の項目は .replace/strategy.md の「未検証領域の扱い」へ記録する（parity-replace の敵対的レビューが人で見る観点になる）。正本は references/project-config.md「コーディング規約」
   • on_diff のドキュメント: 内容はプロジェクトが持つものだが、references と同様に setup が下書きを生成し、人間がレビューして確定する（既定挙動で足りる環境には作らない）
   • references（知識の注入）: パス型キー（architecture / coding_conventions / ui_library / db_semantics / env_setup）をキーごと生成する。この時点でパスが決まらないキーも省略せず空値で置き、「どのスキルがいつ読むか」をコメントで添える。 未整備で下流が停止するのは正しい挙動であり、枠を作るのは停止を避けるためではなく不足を setup 時点で見えるようにするため（キーごと無いと、下流のスキルが停止して初めて不足が分かる）。 dependency_policy だけは空値で生成しない——キーの有無自体が「未確認」を表す三値のため、空値の枠を置くと下流の確認が発火しなくなる （手順 10 の確認結果としてパスか none を書き、確認まで至らなければキーごと書かない）。正本は references/project-config.md の「references（知識の注入）」
4. 現行環境の再構築（current.origin: received-assets のときだけ）: current-environment-bootstrap へ委譲する。 引き渡し完了（.replace/bootstrap/metadata.json の status: handed-off）まで測定へ進まない（blocked なら質問票の回答・追加資産を待ち、--resume での再開を案内して停止する）。 引き渡し後は、再構築された target が測定・特性化の対象になる。managed の場合は本手順を飛ばす（従来フローは変わらない）
5. 測定: すべて実測する。手順は references/measurement.md。 セマンティクス測定（同梱の scripts/role-probe.mjs を使用）・DB 復元可否・現行コードの入手性・副作用の棚卸し・ファイル入出力の到達性（画面駆動の捕捉可否・バッチ出力のファイルシステム到達性・ストレージ）・既存テストの評価を行い、 .replace/survey.md に記録する。測れない場合はここで停止する
6. 戦略の提示とユーザー承認: 測定結果から、パリティスイート戦略・ゴールデンデータセットの作り方・フロント／バックの非対称設計（バックエンドは現行コードからの直接移植、フロントエンドはパリティスイート＋ベースライン駆動）・未検証領域の扱いを提示し、承認を得て .replace/strategy.md に記録する
7. 成果物の扱いの決定（設定ファイルへ）: 保持方針（ワークツリーは最新のみ。履歴は Git が持つ）・保存先（local（既定・コミットしない）／git／git-lfs に限る。それ以外の外部保管は対象外とし、選ぶ場合はポインタ記録のみで検証しないことを明示する）・容量閾値を決める。ここで決めるのは既定値であり、機能ごとに上書きできる
8. 意図的差異レジストリの作成（設定ファイルへ）: 「変えない」「変えてよい」「保留（測定結果で決める）」の 3 分類。references（ui_library / db_semantics）から注入された差（例: 空文字と NULL の扱い、collation による並び順）もレジストリに落とし込む。references の下書き（architecture を除く）は DDL・測定結果・技術スタックから生成し、人間がレビューして確定する。 db_semantics の下書きは移植時の点検項目（NULL の並び順・暗黙の型変換と失敗時の値・照合順序・連結時の NULL・書式のロケール依存）を節として立て、現行 DB／新 DB の既定を埋める形にする—— このキーは parity-replace が実装前に読む点検表でもあり、節が無い項目は「差が無い」ではなく「誰も見ていない」になる。正本は references/project-config.md の「DB 意味論」
9. 機能インベントリ: 現アプリを機能単位に分解し、各機能のページ・API・テーブル・副作用出力、横断 API の fan-out と参照テーブル、slug を .replace/features.md に記録する。 機能は画面内の表示セクションではなく、利用者目的・データ境界・依存関係・副作用の所有者で分解する（複数ページの機能は 1 行）。 併せて**ページ一覧（ページ × そのページに乗る機能）**を記録する——機能単位に分けた裏返しとして、同じページに乗る別機能のセクションが丸ごと欠けてもどのスイートも赤くならないため、parity-suite が在席チェックの根拠に使う。規則は references/features-issues.md。 ページ一覧を書いたら、そのページの可視要素が漏れなくどれかの slug に帰属しているかを確かめ、どの機能行のセクションにも収まらない要素を「ページ要素の帰属」表へ記録して配置の所有者を決める—— 機能一覧が所有者を持つのはテーブル・API・副作用出力だけで、スコープ外と決めた要素にも場所を占めるものがあり、誰も配置しなければ実装後の parity-diff まで「説明できない差分」として現れない。 帰属の無い要素が残るなら、候補 slug を添えて着手前にユーザーへ確認し、確定するまで所有者は空欄のまま残す（暫定値で埋めない）（規則は同 references/features-issues.md）。 4 種（ゴールデンデータセット／横断 API／機能／バッチ）に還元できない作業（例: テーブルをまたぐ新側スキーマの前倒し設計）は「その他の Issue（4 種以外）」表に置き、記録先が無いことを理由にヘッダへ独自項目を足したり記録を諦めたりしない current.origin: received-assets の場合は、採番した slug を .replace/bootstrap/semantics.md の「対象機能」列へ非破壊で書き戻す—— 同ファイルは .replace/features.md が存在しない時点で書かれるため機能の呼び名しか持てず、書き戻さないと golden-dataset / parity-suite が確認待ちの意味論を slug で引けない （正本は current-environment-bootstrap の references/data-semantics.md）
10. 共通部品の依存決定: 複数機能で使う部品（UI ライブラリ・フォント・状態管理・日付処理等）を洗い出し、自前で書くか／どのパッケージを使うかを実装が始まる前に決めて .replace/dependencies.md に記録する。 判断材料・確認手段・決める順序は references/dependency-selection.md。 ライセンス方針・供給網ポリシーの有無はリポジトリごとに違うため、あればそれに従い、未確認なら方針の要否そのものをユーザーに確認して結果を設定（references.dependency_policy）へ記録する（none ＝確認済みで方針なしは再確認しない）。 機能固有の部品は parity-replace が実装フェーズ前に同じ基準で決める（ここで全部を洗い出そうとしない）

issues モード

.replace/features.md の未起票の機能・横断 API リソース・バッチから対象を選択し、Issue を起票して Issue 番号をインベントリへ書き戻す。 手順・Issue 種類（ゴールデンデータセット／横断 API／機能／バッチの 4 種と、**4 種に還元できない作業のための「その他 Issue」**の計 5 種）・本文構成は references/features-issues.md を参照する。

• .replace/features.md が無い（setup 未完了）場合は起票せず停止し、setup の実行を促す
• .replace/features.md の更新は非破壊——テンプレートは初期生成の雛形であって更新時の項目の上限ではない。変える行・列だけを書き換え、テンプレートに無いヘッダ項目・節・列・行を書き直しで削除しない。4 種に当てはまらない Issue は「その他の Issue（4 種以外）」表へ置く（正本は references/features-issues.md）
• 起票は issue-create スキルへ委譲する。候補・依存関係・各 Issue の本文ドラフトを提示して明示承認を得てから 1 件ずつ委譲する（issue-create は 1 件ずつ承認を得る設計のため、本モードで先にまとめて承認を得る）
• 同じページに乗る機能はページ一覧から束ねて連続順を提案し、着手前に slug ごとの再実行回数・束の合計・最後にマスクが外れる全面比較を示す（実依存を逆転させない。数え方は references/features-issues.md）
• 明示承認が得られない場合——利用者が不在（非対話実行）・無応答・応答が承認以外——は起票せず停止する（gh issue create も issue-create への委譲も行わない）
• 重複チェックはページネーションに留意する（既定件数で打ち切らない）

status モード

自前の状態を持たず、GitHub Issue の状態とリポジトリ内の成果物から毎回導出する（ブランチのマージ後でも動くようにするため）。手順は references/status.md を参照する。

• .replace/features.md が無ければ setup 未実施と報告し、setup の実行を案内する
• Issue の状態は features.md に記録された番号を個別取得する。番号を列挙できない取得はページネーションを処理する（指定件数で打ち切らない）
• 状態の根拠はトラッカーへの問い合わせだけ。features.md は番号だけを持ち（旧版テンプレート由来の「状態」列があっても読まない）、取得できなかった番号は 判定不能 として示す（open / closed のどちらにも倒さない）
• 機能ごとのパリティスイートの有無・強度・データセットバージョンの陳腐化・未検証領域（gaps）を導出する
• 横断 API に変更があった場合の影響範囲（利用側の機能一覧）を fan-out から導出する
• 「その他の Issue（4 種以外）」表の各行は Issue 状態と依存順・影響範囲を報告する（.replace/parity/<slug>/ の成果物を持たないため、スイート強度・ベースライン・フェーズ B・差分は「対象外」として未着手と区別する）

成果物

すべて対象プロジェクト側に置く。成果物スキーマの正本は生産側スキルが定義する——本スキルは設定・survey.md・strategy.md・features.md・dependencies.md の正本を定義し（テンプレート: assets/）、 下流スキルの成果物（.replace/parity/<slug>/ や .replace/dataset/、.replace/bootstrap/ の形式）は各スキルが定義する。同じ形式を複数スキルで重複定義しない。

姉妹スキルと依存順

全体の依存順: replace-strategy（setup の由来確認）→ 必要時のみ current-environment-bootstrap → replace-strategy（測定・戦略・機能インベントリ） → golden-dataset（フェーズ A）→ 各機能で〔parity-suite → parity-replace → golden-dataset（フェーズ B）→ parity-diff（parity-replace と往復）〕。横断 API Issue は機能 Issue より先。

姉妹スキルが未インストールでも本スキル（測定・戦略・起票）は動くが、起票した Issue の実施には必要になる。issues モードの完了時に案内する。 例外は current-environment-bootstrap——current.origin: received-assets のときは測定の前提そのものが揃わないため、未インストールなら導入手順を示して停止する（手順 2）。