docs: ADR-016 (長時間コマンド実行戦略) + ADR-017 (takt バージョン固定方針)

CLAUDE.md

@@ -17,6 +17,8 @@
 - [ADR-013: Merge Pipeline — PR マージ + ローカル同期](docs/adr/adr-013-merge-pipeline.md)
 - [ADR-014: Post-Merge Feedback — マージ後のフィードバックループによる再発防止](docs/adr/adr-014-post-merge-feedback.md) *(試験運用)*
 - [ADR-015: Push Pipeline を takt ベースの push-runner に移行](docs/adr/adr-015-push-runner-takt-migration.md) *(Supersedes ADR-008 の push 前パイプライン部分)*
+- [ADR-016: Claude Code Bash ツールでの長時間コマンド実行戦略](docs/adr/adr-016-long-running-command-strategy.md)
+- [ADR-017: takt バージョン固定と検証環境の維持](docs/adr/adr-017-takt-version-pinning.md)
 
 ## Build
 

docs/adr/adr-016-long-running-command-strategy.md

@@ -0,0 +1,71 @@
+# ADR-016: Claude Code Bash ツールでの長時間コマンド実行戦略
+
+## ステータス
+
+承認済み (2026-04-14)
+
+## コンテキスト
+
+ADR-015 で takt ベースの push-runner を導入した際、Claude Code の Bash ツールでの実行中にパイプラインが痕跡なく消える問題が発生した。
+
+### 問題
+
+1. Bash ツールのデフォルトタイムアウトは 120 秒
+2. takt AI レビューは 2〜10 分かかる
+3. タイムアウト時、Bash ツールはプロセスツリーごと kill する
+4. kill されたプロセスはログにも state file にも痕跡を残さない
+5. 調査者からは「パイプラインが実行中のまま進捗がない」ように見える
+
+### 影響を受けるコマンド
+
+| コマンド | 典型的な実行時間 | デフォルトで安全か |
+|---------|----------------|-----------------|
+| `pnpm push` (takt レビューあり) | 2〜10 分 | 不安全 |
+| `pnpm push` (takt レビューなし/clean path) | 2〜3 分 | 不安全 |
+| `pnpm create-pr` + monitor daemon 起動 | 10〜30 秒 | 安全 |
+| `pnpm merge-pr` | 10〜30 秒 | 安全 |
+| `cargo build --release` (単体) | 5〜15 秒 | 安全 |
+| `pnpm build:all` (全 exe 一括) | 1〜2 分 | 境界的 |
+
+## 決定
+
+### 長時間コマンドは `timeout: 600000` + `run_in_background: true` で実行する
+
+Claude Code の Bash ツールには以下の制御パラメータがある:
+
+- `timeout`: 最大 600000ms (10 分)。デフォルト 120000ms (2 分)
+- `run_in_background`: true にするとバックグラウンド実行。完了時に通知を受け取れる
+
+`pnpm push` のように takt AI レビューを含むコマンドは、必ず以下の設定で実行する:
+
+```yaml
+timeout: 600000
+run_in_background: true
+```
+
+> **注意: タイムアウトの階層**
+> Bash ツールの `timeout` はプロセス全体 (`pnpm push`) にかかる。一方、push-runner 内部の
+> `push.timeout` (デフォルト 300s) は `jj git push` コマンド単体のタイムアウトである。
+> 両者は異なるレイヤーの制約であり、Bash ツール側を 600s に設定しても push-runner 内部の
+> 個別コマンドタイムアウトには影響しない。パイプライン全体の実行時間は主に takt AI レビューに依存する。
+
+### バックグラウンド実行の利点
+
+1. タイムアウトが 10 分に延長される
+2. 実行中に他の作業が可能
+3. 完了通知で結果を確認できる
+4. レートリミット消費を抑制できる (ポーリング不要)
+
+### パイプライン変更時のブートストラップ問題
+
+push パイプライン自体を変更する場合、中間コミットではパイプラインが壊れる可能性がある。
+
+- コミット 1 (Rust crate のみ) を push → 古いパイプラインが動き takt 未導入で失敗
+- コミット 3 (統合) まで揃って初めて新パイプラインが動く
+
+**対策**: パイプライン変更コミットは squash して 1 回でアトミックに push する。
+
+## 影響
+
+- `pnpm push` を Claude Code から実行する際の標準手順が確立される
+- hooks や skills の中で長時間コマンドを呼ぶ際の指針になる

docs/adr/adr-017-takt-version-pinning.md

@@ -0,0 +1,52 @@
+# ADR-017: takt バージョン固定と検証環境の維持
+
+## ステータス
+
+承認済み (2026-04-14)
+
+## コンテキスト
+
+PR #33 で takt 0.35.4 (Agent SDK 0.2.105) を導入した際、Windows 環境で Claude CLI の呼び出しが失敗した。
+
+### 障害の詳細
+
+- **エラー**: `Claude CLI failed (1): コマンドまたはファイル名が正しくありません` (Shift-JIS)
+- **原因**: takt 0.35.4 が Windows での Claude CLI spawn に失敗
+- **影響**: takt の Phase 1 (execute) が 0.25 秒で異常終了し、AI レビューが一切実行されない
+- **解決**: takt 0.35.3 へのダウングレードで正常動作を確認
+
+### 根本原因の推定
+
+takt 0.35.3 → 0.35.4 の間の変更が Windows のプロセス spawn 互換性を破壊した。なお、Agent SDK のバージョンは takt が `^0.2.71` で依存しているため、takt のバージョンによらず pnpm-lock.yaml で解決されたバージョン (本プロジェクトでは 0.2.105) が使われる。したがって原因は Agent SDK のバージョン差ではなく、takt 本体のコード変更にあると推定される。
+
+## 決定
+
+### 1. キャレットなしでバージョンを固定する
+
+```json
+{
+  "devDependencies": {
+    "takt": "0.35.3"
+  }
+}
+```
+
+`^0.35.3` ではなく `0.35.3` とすることで、`pnpm update` による意図しないアップグレードを防止する。
+
+### 2. takt-test-vc を検証環境 (staging) として位置づける
+
+バージョンアップ手順:
+
+1. `E:\work\takt-test-vc` で新バージョンの takt をインストール
+2. `pnpm push:runner` でフルパイプライン実行を検証
+3. Windows 環境での Claude CLI 呼び出しが正常であることを確認
+4. 確認後、このプロジェクトの package.json を更新
+
+### 3. Agent SDK のバージョンは pnpm-lock.yaml で管理される
+
+takt は `@anthropic-ai/claude-agent-sdk` を `^0.2.71` で依存しているため、takt のバージョンを固定しても Agent SDK は semver 範囲内で更新される。実際に takt 0.35.3 のインストールでも SDK 0.2.105 が解決されている。pnpm-lock.yaml が実質的なロックであり、SDK のバージョンアップも takt-test-vc で事前検証すべき対象に含まれる。
+
+## 影響
+
+- takt のバージョンアップには必ず takt-test-vc での事前検証が必要
+- 派生プロジェクトへの deploy 時も同じバージョンの takt を使用すること