共有作業ツリーから本番 Apps Script を巻き戻さずに部分 push する（overlay push）

問題

• 複数の AI セッション／人が同じ作業ツリーで GAS（clasp 管理）を触ると、ローカルには「他人が既に push 済みのものより古いファイル」や「未完成のファイル」が混ざる。
• この状態で clasp push -f すると rootDir 配下を丸ごと上書きするため、他人の新しい本番コードを古い版に巻き戻す。
• AI エージェントの安全判定（auto mode classifier 等）は、cd && clasp push -f | 出力捨て のような一括コマンドを「差分を見せない本番上書き（Blind Apply）」として拒否しやすい。

解決: 本番を正としてファイル単位で重ねる 1 コマンドツール

node tools/gas-overlay-push.mjs --project <.clasp.jsonのあるdir> --files <rootDir相対,カンマ区切り> [--dry-run] [--deploy <deploymentId>|--deploy-webapp] [--description <text>]

処理順:

1. <project>/.clasp.json（と .claspignore）を OS の一時ディレクトリにコピー。
2. 一時ディレクトリで clasp pull ＝ 本番の現物を取得。
3. --files に指定したファイルだけ、ローカル <project>/<rootDir>/ から一時ディレクトリへ上書きコピー（他ファイルは本番のまま）。
4. 各ファイルについて pull 版との差分（追加/削除行数と unified diff 先頭 80 行）を表示。全ファイル差分ゼロなら push しない。
5. --dry-run ならここで終了（人/AI が差分を確認する）。
6. 一時ディレクトリで clasp push -f。
7. read-back: 別の一時ディレクトリに再度 clasp pull し、指定ファイルがローカルと一致するか（CRLF 差は無視）検証。不一致なら exit 1、デプロイしない。
8. --deploy <id> なら clasp deploy -i <id> -d <description>。--deploy-webapp は clasp deployments から @HEAD 以外のデプロイが 1 つだけのときに自動選択（複数なら一覧を出してエラー）。
9. 最後に {"ok":true,"pushed":[...],"unchanged":[...],"readBack":"ok","deployed":"<id|null>"} を 1 行 JSON で出力。

実装の要点:

• 依存パッケージなし（Node 標準 child_process.spawnSync を shell:false で。Windows は clasp.cmd の実体 JS を解決して node で起動）。
• clasp 呼び出しは注入可能な runner 関数に切り出し、テストでモックする。
• --files は ..・絶対パス・.clasp.json を拒否。一時ディレクトリ削除前に tmpdir 配下であることを確認。
• 差分は自前の簡易 LCS で十分。

運用ルール

• GAS の反映はこのツールだけで行う（clasp push を作業ツリーから直接打たない）。
• まず --dry-run で差分が自分の変更だけか確認 → 本実行。
• エージェントの許可リストに node <path>/gas-overlay-push.mjs:* を登録すると、一括コマンド扱いの拒否が起きにくい。

テスト観点（node:test）

• 指定ファイルだけが pull 版に重なり、他は pull 版のまま push される
• 変更なし／dry-run では push しない
• read-back 不一致で exit 1・デプロイしない
• --deploy-webapp で候補が複数／ゼロならエラー
• pull/push/deploy 失敗時も一時ディレクトリを掃除する