PJR-6HF3 git hook から呼ぶスクリプトが devDependency に依存し、新規 worktree で失敗する
1. 課題内容
post-checkout hook が npm run build:if-stale を実行し、その実体は tsx src/build-if-stale.ts である。exec run --worktree が新規 worktree を作る時点では node_modules が無く、tsx を解決できずに hook が非ゼロ終了する。その結果 git worktree add が失敗し、checkpoint failed として claim がロールバックされる。build-if-stale.ts には linked worktree なら何もしない判定を入れてあるが、その判定へ到達する前に起動が失敗しており、ガードが自分の前提条件に依存する構造になっている。routine 経由の自動実行が claim と release を繰り返す状態になっている。
2. 影響範囲
| 観点 | 影響 |
|---|---|
| スコープ | worktree を新規作成する全タスク。exec run --worktree と routine 経由の exec cycle が該当する |
| スケジュール | 自動実行が claim と release を繰り返し、Ready タスクが進まない。実質的に自動実行が停止している |
| コスト | 追加の外部コストはなく、影響は復旧と再実行に要する作業時間 |
| 品質 | データ破損は起きない。ロールバックは正しく動作し、claim も解放されている |
| 関係者 | ARC（実装）。自動実行を利用する運用者 |
3. 対応方針
| 項目 | 内容 |
|---|---|
| 原因 | hook から呼ぶ入口が tsx に依存している。新規 worktree では node_modules が無く、TypeScript のガード（linked worktree なら何もしない）へ到達する前に起動が失敗する |
| 対応策 | Node 標準だけで動く plain JS の入口（tools/build-if-stale.mjs など）を追加し、linked worktree と依存未インストールを判定して即終了する。条件を満たす場合のみ既存の判定処理へ委譲する。prepare の node tools/install-lefthook.mjs と同じ方式に揃える |
| 依存事項 | なし。npx tsx へ切り替える案は、依存が無い環境ではレジストリ取得を試みるため採らない |
| 完了条件 | 新規 worktree の作成で hook が失敗しないこと。primary worktree でのブランチ切り替えでは従来どおり再ビルド判定が働くこと |
4. 対応結果
- Node 標準機能だけで起動する
tools/build-if-stale.mjsを追加した。.gitがファイルになる linked worktree ではnode_modulesを確認する前に終了コード 0 で終了する。 - primary worktree ではローカルの
tsxが存在する場合だけsrc/build-if-stale.tsへ委譲し、従来の鮮度判定と再ビルドを維持した。依存未インストール時や委譲失敗時も、best-effort の hook を止めず終了コード 0 とする。 lefthook.ymlのpost-merge/post-checkoutとpackage.jsonのbuild:if-staleを、依存不要な入口をnodeで直接実行する形へ変更した。- 回帰テスト
tests/tools/build-if-stale.test.tsを追加し、linked worktree、依存未インストールの primary worktree、既存実装への委譲、委譲失敗の各経路を確認した。
検討時に却下した案を記録する。
npx tsxへ切り替える: 新規 worktree では親ディレクトリを遡ってもnode_modulesが無く、npxはレジストリ取得を試みる。ネットワークの無い実行環境では失敗し、ある環境でも worktree 作成のたびに取得が走る。post-checkoutから外してpost-mergeだけにする: worktree 作成での失敗は消えるが、primary worktree でのブランチ切り替え後に dist が古いままになり、当初の目的を一部失う。
5. 関連ドキュメント
- hook を追加した項目: PJR-CMYX exec 実行が古い dist ビルドを使い設定済み parent_validations が実行されない
- 同種の見落とし: PJR-X3E8 テストの git 実行が環境を隔離せず、メインリポジトリを bare 化する
- 影響を受けた実行:
docs/ja/projects/prj-0001/execution/exec/events/のT-PLANNING-dct-index-010の claim と release - 変更対象:
tools/build-if-stale.mjs、tests/tools/build-if-stale.test.ts、lefthook.yml、package.jsonのbuild:if-stale - 同方式の前例:
tools/install-lefthook.mjs