pythia-deploy

リリースのデプロイ

開始時に告知：「pythia-deploy を使用します。リリース内のすべてのステートメントを事前にプレビューします。」

フェーズ： 確認 → 実行 — 順序付けられた一連のステートメント全体を一度にプレビューして承認を得てから、1つずつ実行します

sqlplus @release.sql で実行したリリーススクリプトには、スナップショットも、プレビューも、検証もなく、212行目で失敗するまでに何が反映されたかの記録もありません。 pythia deploy は同じファイルをステートメントごとに書き込みパスで実行するため、失敗時にはそこで確実に停止し、反映された内容と取り消し方法を正確に一覧表示します。

絶対原則

A RELEASE RUNS IN ORDER, AS PREVIEWED, AND STOPS AT THE FIRST BROKEN STEP

スクリプトの読み取り方法

• SQL は ; ごとに1つのステートメントとして扱います。PL/SQL の単位（CREATE ... PROCEDURE / FUNCTION / PACKAGE / TRIGGER / TYPE）は、/ のみが記された行で終了します。 リテラルやコメント内の ; や / はテキストとして扱います。
• SQL*Plus ディレクティブ（SET、PROMPT、SPOOL、SHOW ERRORS、WHENEVER、 DEFINE、…）はデータベース上で何も実行しません。スキップされ、一覧表示されます。
• @file / @@file によるインクルードは拒否されます。ファイルを一覧にしてください。 deploy は、誰も確認していないパスを実行しません。
• スキップせず、拒否するもの：無名の BEGIN ... END; ブロック（apply と同様）、 EXEC / HOST / CONNECT、および ALTER SESSION — これらは後続のすべてのステートメントの実行方法を 気づかれないまま変更するため、どのプレビューでも示せません。
• ファイルは指定された順序で実行されます。ディレクトリ内のすべてのファイルに番号が付いている場合（1_、02_、10_、Flyway の V3__）は自然な名前順で実行され、それ以外の場合は各ファイルが作成するものの順序（テーブル、インデックス、コメント、型、ビュー、仕様、プロシージャ、ボディ、トリガー、権限、データ）で実行されます。どの順序になるかはプレビューに表示されます。

ワークフロー

1. 準備 — 実行する順序でファイルをそろえます。リリースで変更する既存オブジェクトすべてについて、影響分析（pythia-impact）を実施します。
2. Lint — 対象一式に対して pythia lint <files> を実行します。エラーはプレビューの前に修正し、後回しにしません。
3. プレビュー — pythia deploy <files> を実行します。何も書き込まれません。内容をそのまま伝えます。各ステートメントのグループ、オブジェクト、変更行、影響、! DESTRUCTIVE と lint の行、差分を伝えます。ポリシーによる拒否は何も実行される前に表示されます。拒否内容を伝え、開発者に判断を委ねます。
4. 一度だけ確認を求める — プレビューにはデプロイトークン（16進数10桁）が表示されます。開発者は最初に利用できる方法で承認します。Claude Code では pythia approve --card <token> がそのまま記された AskUserQuestion、Codex が利用可能な環境では pythia_approve ツール、または開発者のターミナルで pythia approve <token> を使用します。いずれかが失敗したら、まだ確認に使用していない次の方法に進みます。
5. 実行 — 同じファイル一覧で pythia deploy <files> --confirm <token> を実行します。各ステートメントは、個別のジャーナルエントリーを伴って、スナップショット → 適用 → 検証の順に処理されます。終了コードをパイプせずに確認します。0 はすべて反映済み · 1 は拒否（その後は何も実行されていません） · 3 は書き込まれたが不具合あり（そこで停止しました）。
6. 報告 — すべてのステートメントの結果を報告します。停止した場合、反映済みの変更はそのまま残ります（DDL は自動的にコミットされます）。承認の残りは取り消され、出力には新しい順に取り消しコマンド、取り消し手段のない反映済みステートメント、再開に使う --from N が一覧表示されます。先に進めて修正するか、復元するかは開発者が判断します。

すべてのステートメントを対象とする自動操縦リース（pythia-autopilot）のもとでは、ステップ3でリリースがそのまま反映されます。対象外のステートメントが1つでもある場合、リリース全体がプレビューに切り替わり、出力に対象外のステートメントとその理由が表示されます。

停止後の再実行

停止前のステートメントはデータベースに反映されています。CREATE TABLE、ALTER TABLE ADD、挿入は2回実行できません。失敗したステートメントを修正し、pythia deploy <files> --from <N> を実行します。残りのステートメントについて、新しいプレビューと承認が必要です。同じリリース内で先に追加するカラムを必要とするバックフィルは、DDL が存在する前には測定できません。まず DDL をデプロイし、次に --from でデータ部分をデプロイしてください。

危険信号 — こう考えていることに気づいたら、作業を止めてください

考え	実際のところ
「sqlplus で実行するほうが速い」	スナップショットも、検証も、どこで止まったかの記録もありません。フックによって実行も拒否されます。
「ステートメント 7 が失敗したけれど、飛ばして続けよう」	残りはそれを前提に順序付けられています。止めて報告し、開発者に判断を委ねてください。
「インクルードは問題ない、自分で書いたから」	デプロイでは、一覧表示されプレビューされたものが実行されます。一覧に含めてください。
「リリース全体の承認を得たから、ファイルを編集して再実行してもよい」	トークンはプレビューされた内容に紐付けられています。編集した場合は、もう一度プレビューしてください。
「最後のステートメントで終了コード 3 が出たけれど、ほかはすべて問題ない」	書き込まれていますが、壊れています。取り消し手順の一覧とともに、壊れていると報告してください。

このスキルを使わない場合

• 1 つのファイルに 1 つのステートメント → pythia-apply。
• リリース内のテーブルやパッケージを設計する場合 → pythia-table、 pythia-package。このスキルは、それらを反映するだけです。