pythia-apply

PL/SQL の変更を適用する

開始時に告知: 「pythia-apply を使用します。まず変更をプレビューします。」

フェーズ: 確認 → 実行 — プレビューを伝えて承認を得てから、唯一の書き込み手段を開きます

Oracle の DDL は自動的にコミットされるため、pythia が書き込み前に取得する スナップショットが唯一の取り消し手段です。DML ではそれさえありません。このスキルでその手段を活用します。

鉄則

NO WRITE THE DEVELOPER HAS NOT SEEN AND APPROVED

すべての書き込みが対象です。新規オブジェクト、修正、復元、バッチ実行。例外はありません。 「些細な」変更でも、1 行の変更で 12 個の依存オブジェクトが無効になることがあります。

エージェントには 4 つの操作が禁止されており、pythia はそのすべてを強制します（CLI はターミナルなしでは拒否し、ツール実行前フックは最後の操作を拒否します）。

• --yes — これは開発者のフラグであり、エージェントが使うものではありません。
• 承認の発行。pythia approve <token> は開発者がコンソールで実行するコマンドです。エージェントは実行できません。エージェントが行うのは依頼することです（手順 3）。承認は開発者自身の回答からのみ発行されます。
• pythia policy set <group> でポリシーを緩和すること、および pythia autopilot on — これらは開発者が決めることです。開発者自身が実行できるよう、正確なコマンドを伝えてください。
• ゲートを迂回して書き込むこと — sqlplus、SQLcl の run-sql、ドライバースクリプト。

エージェントが実行できる操作は 1 つです。--confirm — Approve またはコンソールでの承認の後に限ります。 例外：有効な autopilot リース（pythia-autopilot）を開発者が承認している場合 — pythia apply <file> が対象のステートメントを適用し、プレビューには autopilot: applying under lease、または適用されない理由が表示されます。

変更を apply で適用できない場合

DBA またはリリースプロセスが実行する場合、あるいはポリシーでグループが拒否される場合でも、プレビューではライブバージョンのロールバックが .pythia/journal/<entry>/restore.sql に用意されています（pythia history <OBJECT>）。その旨を伝えてください。

ワークフロー

ステップ 1 の前に： このオブジェクトについて、この会話内で単独の影響分析が行われていない場合は、まず pythia-impact を実行してください。apply の impact: 行は、すでに把握している数値を確認するものです。

1. プレビューします。 pythia apply <file> は何も書き込みません。スナップショットを作成し、影響を計算して、差分、警告、Lint の検出結果、確認トークンを表示します。

2. プレビューをそのまま伝えます。 差分、impact: 行、すべての ! 警告を、表示されたとおりに伝えてください。開発者が承認するのは、あなたの言い換えではなく、実際に表示された内容です。

3. 承認を求めます — 最初に使える方法を選び、その次の方法は、先の方法が使えない場合にだけ試します。

   • Claude Code：AskUserQuestion — 独自のダイアログがすべてのクライアントに表示されます。pythia approve --card <token> はカードを出力します。質問文にはそのカードだけを使い、それ以外は何も加えないでください。前置きも、後に続ける翻訳も不要です。フックは質問文とカードを比較し、一致しない場合は何も発行しません。説明は選択肢の説明欄に記載してください。ヘッダーは pythia、選択肢は正確に Approve ／ Reject とし、1 回の呼び出しで最大 4 件のトークンを扱えます。answers は決して設定しないでください。フックが Reject 以外の理由で回答を無効とした場合は、すぐに次の方法へ進んでください。
   • 次に pythia_approve ツール（MCP。Codex はここから開始します）にトークンを渡します。これは pythia 独自のカードです。クライアントに表示されなかったと示された場合は、次の方法へ進んでください。
   • 最後に： 開発者のターミナル用に pythia approve <token> を伝えます。 Approve 以外は承認ではありません。停止して、何を変更すべきか尋ねてください。

4. pythia が出力した then the agent: 行をそのまま実行して適用します。ここで拒否されるのは通常のことで、どちらも不具合ではありません。

   • 「no developer approval is on file」 — 回答が Approve ではなかったか、フックがインストールされていません。その旨を伝えて待ってください。再試行しても承認は作成されません。
   • 「the confirmation token does not match」 — プレビュー後にファイルまたはデータベースが変更されました。ステップ 1 に戻り、「再試行」はしないでください。オブジェクトが pythia の管理外で変更されていれば、新しいプレビューが自動的に警告します。

5. 終了コードを読みます — それが判定結果です。パイプを通してはいけません。 apply … | tail は常に tail の 終了コードである 0 を返します。パイプを使わないか、${PIPESTATUS[0]} を使用してください。

   終了コード	意味	必ず行うこと
   0	適用済み。コンパイルに問題はなく、新たに INVALID になったものもありません	完了を報告し、復元 ID に言及します
   1	拒否（ポリシー、分類、古いトークン）	表示された理由とその修正方法を伝え、回避策を講じてはいけません
   3	書き込み済みですが、問題が発生しています — コンパイルエラー、または他のオブジェクトが新たに INVALID になりました	以下を参照してください

6. 終了コードが 3 の場合、成功を報告してはいけません。 変更が適用され、何かが壊れたことを明確に伝え、コンパイルエラー（行:列）と新たに INVALID になったオブジェクトを示し、To undo: コマンドを提示してください。開発者がこの状態を確認した後に限り、修正を続けることができます。

復元

pythia journal restore <id> 自体が書き込み操作です。同じ 6 つのステップと承認ゲートが適用されます。以前は存在しなかったオブジェクトを復元すると DROP になります。structural: deny のポリシーで拒否されますが、それが正しい動作です。

複数のステートメント

スクリプト、リリース、コメント付きのテーブルなどには pythia-deploy を使用します。すべてのステートメントを 1 回のプレビューで確認し、承認を 1 回得て、順番に実行し、終了コード 3 が最初に発生した時点で停止します。開発者の「もう確認を求めないで」は pythia-autopilot の依頼であり、ゲートを省略する理由にはなりません。

書き込み経路を決して迂回しない

SQLcl MCP の run-sql も、sqlplus も、ドライバースクリプトも使用してはいけません。スナップショットも、プレビューも、検証も、ジャーナルも行われません。拒否は開発者に伝えるべき情報であり、迂回すべき障害ではありません。

ロールバックは本当にできますか？正直に説明してください

グループ	ロールバックは本当にできますか？
plsql_source	はい、完全にできます。 ソースは ALL_SOURCE から復元できます。
comments	はい。 書き込みのたびに、以前のコメントがスナップショットとして保存されます。
data_dml	いいえ。 コミット後に残るのはフラッシュバッククエリだけで、UNDO 保持期間内に限られます。再検証で確認するのは書き込み前の行セットであり、取り消しではありません。
structural	ほとんどの場合、できません。 DROP COLUMN は元に戻せません。削除したテーブルはリサイクルビンに残っている場合があります。
grants	はい。ただし手動で行います。
session	不要です。

「いつでもロールバックできます」と決して約束しないでください。これは最初の行にしか当てはまらず、一般論として言うと、最も重要な場面で開発者を誤解させます。

data_dml は行を対象に再検証されます。プレビューと approve では、影響を受ける行数と最大 10 行が表示され、--confirm はその行セットに変更があった場合に実行を拒否します。MERGE や、影響を測定できない操作は推測で実行せず、拒否します。

危険信号 — こんな考えが浮かんだら作業を止めてください

考え	実際のところ
「小さな変更だから、プレビューは省略しよう」	小さな変更でも依存先は無効になります。プレビューしてください。
「開発者は以前、似たような内容を承認した」	承認はトピック単位ではなく、プレビューごとに必要です。もう一度確認してください。
「終了コードは 3 だけど、自分の部分はコンパイルできた。完了と報告しよう」	正常だったものが壊れています。それは完了ではありません。
「トークンが古くなったから、新しいものを使おう」	内容が変更されています。新しいプレビューを開発者に確認してもらう必要があります。
「apply が拒否したけど、run-sql なら実行できる」	拒否されるのは、製品が正しく動作している証拠です。そのことを伝えてください。
「ミスを片付けるため、こっそり復元しよう」	復元も書き込みです。同じゲートが適用され、同じように可視化されます。
「tail にパイプした後、$? は 0 だった」	それは tail の 0 です。pythia 自身の出力、またはパイプを通さない場合の終了コードを確認してください。
「自分で approve を実行して、この作業を進めよう」	それは開発者が行う操作です。コンソールの approve はあなたによる実行を拒否します。フックは開発者の返答からのみトークンを発行します。この仕組みを迂回させないために、このゲートがあります。
「カードの周りに自分の文を追加しよう」	一語でも追加すると無効になります。説明はオプションの説明欄に記載するか、pythia_approve ツールを使ってください。
「Lint で指摘されたけど、コンパイルは通る」	エラーはプレビューが開発者に届く前に修正されます。自動操縦では、エラーを残したまま反映することはありません。

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

• 読み取り → pythia-explore。影響範囲の調査 → pythia-impact（プレビューは確認を行うものであり、発見を行うものではありません）。複数のステートメント → pythia-deploy。

例では pythia ... を使用しています。pythia の出力には、このプロジェクトで実行する形式の次の手順が毎回表示されます。表示された内容を貼り付けることを優先してください。