preflight-mutations

事前変更チェック

共有状態への書き込み前に、権限、現在の状態、依存関係、復旧方法を確認します。ここに判断記録を作成します。変更そのものは決して実行しません。この分離が重要です。

1. 変更バッチを定義する

同じ承認とガードを共有する項目を1つのバッチに記録します。対象、所有者、環境、可逆性、確認要件が異なるアクションは、別々のカードに分けます。

簡単なカードはインラインで表示します。複数ステップまたは複数バッチの実行では、このワークフローで書き込みがすでに承認されている既存の成果物にのみ保存します。事前チェックを保存するだけの目的で、ファイル、コメント、イシュー、その他の外部成果物を作成することはありません。

### Mutation card

- **Surface / environment:** <system and local | staging | production | shared>
- **Action:** <exact mutation verb and delta; no combined "update as needed" language>
- **Targets:** <stable IDs, URLs, refs, fields, recipients, or services>
- **Ownership policy:** <governing policy and owner/assignee/author/environment boundary>
- **Authorization source:** <user request or later explicit confirmation, quoted narrowly>
- **Current guards:** <state, base/head SHA, version, field, environment, or other compare-before-write facts>
- **Dependencies / consumers:** <direct dependencies; transitive consumers when destructive or history-rewriting>
- **Preview / exclusions:** <proposed delta, blast radius, and what will not change>
- **Reversibility:** reversible | compensating-only | irreversible
- **Recovery plan:** <undo, backup, compensation, or explicit absence>
- **Invalidators:** <facts that make this preflight stale>
- **Read-back plan:** <authoritative post-write query and expected result>
- **Batch items:** <stable item ID → pending | landed | failed | skipped | reconcile-required>
- **Verdict:** ready | confirmation-required | blocked
- **Next action:** <one action permitted by the verdict>

他のエージェントが推測によってより広範なリソースを選択できないよう、アクション、対象、環境、バッチ項目IDを正確に記載します。複数ステップまたは複数バッチのカードには、承認済みの永続的な保存先が必要です。これをゲートとして明記します。ゲート。 推測で選択できるものがなく、すべての複数ステップのカードに保存先があること。

Read-back planでは、すべての対象とガード対象の依存関係を安定IDで指定します。「すべての対象」や「利用者」など、対象を特定しない表現にまとめることは決してありません。

2. 権限と所有権を確認する

対象のサーフェスに適用される所有権ポリシーに従います。技術的な書き込みアクセスがあっても、ユーザーが求めた範囲が広がることはなく、担当者、作成者、リソース所有者、環境の境界を超える権限が与えられることもありません。

証拠から、技術的アクセスが承認済みの範囲を超えていると分かる場合は、Ownership policyにアクセスと権限の違いを明記します。

具体的なユーザーリクエストが承認するのは、指定されたアクションと対象の範囲内にある通常のreversible書き込みのみです。分割、グループ化、後継を伴うクローズ、依存関係のリベースなどの構造変更、本番データまたは本番運用、サービス停止、外部の宛先、適用される所有権の境界外にあるリソース、compensating-onlyまたはirreversibleのアクション、公開済みの履歴の書き換えまたは削除については、その都度、新たな明示的確認を必要とします。

あるアクションクラスへの承認を、別のクラスへの承認とは見なしません。カードに正確な承認元を記録します。

ゲート。 所有権が確認され、承認が正確なバッチを対象としていること。そうでなければ、判定をreadyにすることはできません。

3. ガード、依存関係、公開状態を確認する

バッチの直前に、信頼できるシステムから現在の状態を読み取ります。

• 通常の書き込みでは、直接の依存関係と、現在の比較前書き込みガードを確認します。
• 削除、クローズ、ベース変更、履歴の書き換えでは、スタックされたPR、依存ブランチ、リンクされたイシュー、ワークフロー、リリース、上位の記録、下流サービスなど、推移的な利用者までたどって確認します。
• Gitの履歴では、ローカルの参照をアップストリームおよび利用者と比較します。コミットまたは参照が公開済み、または利用中の場合は、追記のみの修正コミットまたは後継参照への切り替え案をPreview / exclusionsに記載し、その選択肢をNext actionに示します。参照を復元しても公開や下流での利用は取り消せないため、履歴の書き換えまたは削除は、少なくともcompensating-onlyに分類します。状態はconfirmation-requiredのままとします。
• 本番同等のUI操作または運用では、環境と記録の所有権を確認し、可能な場合は影響を受ける記録のスナップショットを保存して、取得した変更前の値と復元または補償の手順を明記します。プライマリレコードを復元しても下流の課金、利用資格、通知、監査への影響が残る場合、そのアクションはcompensating-onlyに分類します。
• 外部へのコピーでは、宛先、含まれる機密情報、保持期間、取り消しまたは削除の手段を確認します。

書き込みを保護するすべての変更可能な事実と、すべての対象の安定IDを、Current guardsとInvalidatorsに記載します。

ゲート。 必要な依存関係と利用者が、現在の証拠に基づいて列挙されていること。破壊的なアクションにおける依存関係が不明な場合は、blockedとします。

4. 影響範囲と復旧方法を事前確認する

曖昧な再構成、大量の変更、本番環境での操作、所有権の拡大、および compensating-only または irreversible に該当する操作の前に、ユーザーが確認できるプレビューを提示します。対象、変更案、除外項目、依存関係、影響範囲、復旧方法を含めます。

復旧可能性を次の3種類のいずれかに分類します。reversible は、直接取り消すことで記録済みの以前の状態に戻せることを意味します。compensating-only は、元のイベントは残りますが、後続の操作で実質的な影響を元に戻せることを意味します。irreversible は、確実に元の状態へ戻す方法がないことを意味します。

reversible の場合は、記録済みの以前の値または具体的な取り消し方法を特定します。compensating-only の場合は、Recovery plan に安定した ID と記録済みの以前の値を使って復旧対象をすべて明記し、そのうえで補償操作と残る痕跡を指定します。irreversible の場合は、恒久的に失われるものを明記します。復旧の根拠が不足している場合は、楽観的に分類せず blocked とします。

ゲート。 プレビューと復旧の根拠が、変更量、環境、曖昧さ、可逆性の分類に適合していること。

5. 判定を1つ割り当てる

• ready は、対象のバッチ、所有権、認可、最新のガード、依存関係の根拠、復旧方法、読み戻し計画がすべてゲートを満たしており、新たに確認が必要なカテゴリにも該当しないことを意味します。
• confirmation-required は、根拠とプレビューは揃っているものの、この種類の操作にはユーザーによる新たな明示的決定が必要であることを意味します。カードを提示して、その決定を求めます。変更は行いません。
• blocked は、必須の対象、所有権、認可、依存関係、復旧、またはガードの根拠が不足しているか、安全でないことを意味します。必要な根拠または権限を明示します。変更は行いません。

永続的な保存先がすでに認可されていない複数ステップまたは複数バッチの実行は、blocked です。Next action には、使用する既存のワークフロー成果物、または書き込みに必要な認可を明記します。このゲートを通過するためだけに永続化状態を作成することはありません。

新たな確認により Authorization source は更新されますが、ほかのゲートが免除されるわけではありません。確認後、判定を ready に変更する前に、無効化要因を再読み込みします。

Next action は、対象と具体的な操作を明記した、単独で意味が通じる指示として記述します。「この操作」や「上記」などの指示表現で内容を曖昧にしません。

6. 実行を引き継ぎ、部分状態を保持する

変更を実行するワークフローに ready カードを渡します。各書き込みの直前に、そのガード条件を照合します。対象、アクション、所有権、依存関係、ヘッド、公開状態、環境、承認のいずれかが変更されていれば、ready は無効になります。まだ実行していない残りの処理を停止し、改めて事前確認を行います。

すべての呼び出し元は、同じ結果の契約に従います。Verdict が ready で、Invalidators が引き続き一致する場合にのみ続行します。confirmation-required の場合はカードを提示し、指定された確認を待ちます。blocked の場合は変更を停止し、Next action を報告します。

実行の引き継ぎでは、サーフェスに条件付き書き込みの仕組みがある場合、それを使用する必要があります。たとえば、期待バージョン、比較交換トークン、正確な SHA のリース、冪等性キーなどです。公開済みの Git 履歴を復旧するためのプッシュも、再読み込みしたリモートヘッドに対するリースで保護する必要があります。

各項目の実行を試みた後、landed、failed、skipped、reconcile-required のいずれかを記録します。コマンドの結果と信頼できる読み戻しのどちらからも、書き込みが反映されたかを確認できない場合は reconcile-required を使用します。その項目を停止します。信頼できるクエリで状態が確定するまでは、再試行したり failed に分類したりしません。

中断、無効化、または reconcile-required が発生した場合は、項目の台帳を保持し、landed の全項目を信頼できる方法で再読み込みして、観測された部分的な外部状態を記録します。さらに、Targets が安全に処理できる pending の残りのみを対象とし、Batch items に landed、failed、skipped、未解決の reconcile-required の履歴と、それらの pending 項目を併記した新しいカードを作成します。

reconcile-required の項目は、新しいカードの書き込み対象からすべて除外します。その Next action には、該当項目の状態を確定するために必要な、具体的な信頼できるクエリを指定します。観測された結果のみが、その項目を landed、failed、または pending に移行できます。

状態がゼロだと仮定して、処理を最初からやり直すことは決してありません。書き込みの責任は実行ワークフローが担います。verify-claims は重要な書き込み後の主張を検証できます。また、最終完了ワークフローは受け入れサーフェスの判定を担当します。

完了。 カードに必要な情報が記入され、判定がゲートと一致し、このスキルによる共有状態の変更は行われていません。