ssotize

真実がどこにあるのかを見つけ、統合計画の承認を得てから、1 つの正式な場所に集約します。

目標

Single Source of Truth（SSOT）を徹底します。1 つの事実には 1 つの場所だけを設け、それを必要とする他のすべての場所では、コピーせずにその場所を参照します。参照は乖離しませんが、コピーは乖離します。これは成果物を変更するため、慎重に行い、情報を失わないようにします。

ssotize は読み取り専用の監査から始まります。対象範囲の真実を特定し、あらゆるコピーを見つけ、正式な場所を選び、統合計画の詳細を報告します。成果物を変更するのは、ユーザーがその計画を承認した後だけです。

これを使って、SSOT を確立または修復します。対象は、整理されていない状態、レガシーな状態、新たに足場を構築した状態です。SSOT が確立したら、過剰に使わないでください。統合は一度限りの修復であり、継続的な維持作業ではありません。読み取り専用のチェッカーと変更を行う後続処理が、切り離せないワークフローになった場合は、チェッカーを統合処理に組み込み、承認ゲートを維持してください。確認のたびに処理を分けると、より安全な前半部分が省略されやすくなるだけです。

ワークフロー

1. 対象範囲の真実を特定します。追跡対象は、文書全体ではなく、具体的な事実、値、仕様、決定、ステータス、または定義です。
2. まず読み取り専用で監査し、指定された成果物とプラットフォーム全体にあるすべての出現箇所を列挙します。
3. 2 つ目の方法で再度列挙します。異なる検索語、類義語、またはツールを使い、最初の確認で見落とした出現箇所がないことを確かめます。
4. 各出現箇所を、完全なコピー、言い換え、一部のみ、古い情報、矛盾のいずれかに分類します。
5. 正式な場所を選びます。最も権威があり、最もよく保守され、事実が実際に変更される場所に最も近い場所を選びます。便利だからという理由だけで、弱いコピーを正式な場所に格上げしてはいけません。正式な場所が存在しない場合は、新たに抽出します。
6. 正式な場所以外の各出現箇所について、対応方針を決めます。重複排除（冗長なコピー）、参照（文書では正式な場所へのリンク、コードでは共有元の import／source／include、設定では保守対象の単一ファイルからの共有読み込み）、または調整（内容が一致せず、人による判断が必要）です。
7. 編集前に監査結果を報告します。出現箇所（場所 · 種類 · 対応方針）の表、1 行の理由を添えた正式な場所の案、そこに統合する必要がある固有の詳細、判断が必要な矛盾、および変更計画の詳細を含めます。
8. 変更計画を実行する明示的な承認を求めます。承認が得られない場合は、読み取り専用の報告までで停止します。
9. 正式な場所を完全かつ最新の状態に整えるか、新たに抽出します。コピーにしか存在しない固有の詳細もすべて取り込みます。統合によって情報を失ってはいけません。
10. まず正式な場所で矛盾を調整します。正しい値が曖昧な場合は、何かを置き換える前に確認します。
11. 各重複を、正式な場所への有効な参照に置き換えます。文書では、リンク、「を参照」などの記載、リンク付きの引用、またはプラットフォームが対応している場合はトランスクルードを使います。コードでは共有元の import／source／include を使い、設定では保守対象の単一ファイルから共有読み込みを使います。
12. 冗長になったコピーを削除します。削除によって読者が参照先を失う場合は、完全に削除するのではなく、1 行の参照先を残します。

ルール

• 統合すべき散在情報が見つからなかったパスでは、何も変更しません。
• 監査フェーズは読み取り専用です。ユーザーが変更計画を承認する前に、編集、移動、削除を行わないでください。
• 検出結果が空でも有効です。統合を正当化するために、情報のずれを捏造しないでください。
• 矛盾は単なる重複とは分けて扱ってください。どちらの値が「正しい」かを暗黙に決めてはいけません。
• 非正規のコピーにしか存在しない情報にはフラグを立ててください。そのコピーを削除する前に、情報を正規の置き場所へ統合する必要があります。
• 明示的な確認なしに、信頼／権限の境界（非公開 → 公開、顧客向け → 社内向け）を越えて統合しないでください。
• 編集は安全に行ってください。操作する前に置換対象が存在することを確認し（見つからない場合は何もせず、MISS と報告してください）、Unicode に対応した編集を行い（PYTHONUTF8=1）、一括置換ではなく、出現箇所ごとに処理してください。コードの構造的な移動には、言語を認識するツールまたはスクリプトによる AST／パーサー編集を使い、スクリプトによるテキストの書き換えは行わないでください。
• プラットフォームを考慮してください。可能であればトランスクルードし、そうでなければ読者がたどれる安定したアンカーにリンクしてください。プラットフォーム上でリンクして戻れない場合は、完全に削除するより参照を優先してください。
• 同じプロジェクトの事実が、読み取り専用の監査成果物と変更を伴う成果物に分かれており、監査成果物に独立した永続的な用途がない場合は、SSOT の散在として扱ってください。監査情報を変更を伴う成果物に統合することを提案し、承認後にのみ実行してください。

検証

完了する前に、以下を確認してください。

1. 読み取り専用で実施した場合を除き、変更前に監査内容を報告し、承認を受けていること。
2. 正規の置き場所だけで、完全かつ最新の情報が得られること。
3. 以前のすべてのコピーが正規の置き場所を参照し、その参照先に問題なくたどれること。
4. 固有の情報が失われておらず、参照先のない情報が残っていないこと。
5. 矛盾は一つの値に整合され、重複したまま残されていないこと。
6. 何を統合したか、正規の置き場所はどこか、何を監査のみ行ったか、どの点に人の判断がまだ必要かを報告すること。