mergegate/docs/dtp/reviews/round2-playbook.md

Auto Run Playbook Review Round 2

対象レビューの前提:

• 指定された docs/autorun/00〜08, docs/PLAYBOOK.md, docs/PLAN-v1.md はこのワークスペースでは見つかりませんでした。
• そのため、Phase 0〜8 と Codex 3-body 反映がまとまっている実質的な対象として [deterministic-protocol-playbook.md](/Users/shunsukehayashi/dev/ops/openclaw-workspace/docs/design/deterministic-protocol-playbook.md) を主レビュー対象にし、元草案として /Users/shunsukehayashi/.claude/plans/snuggly-bouncing-turtle.md、既存レビューとして KOTOWARI/reviews/102-104 を補助参照しました。
• 以下はその前提での detailed review です。

Findings

1. Critical: Phase dependency DAG が本文と矛盾しており、Phase 4 の依存が不足しています

• 依存関係表では Phase 4 は Phase 3 のみ依存です (deterministic-protocol-playbook.md:864-867)。
• しかし本文では Phase 4 の FileLockManager は EventStore と SnapshotStore に依存し (:473-478)、さらに Phase 1 で追加した TaskLock 型にも依存します (:177-184)。
• これは表で 4 | 3 と書かれているのが不完全で、実質は 4 | 1,3 です。
• 同様に Phase 5 も表では 3 のみ依存ですが (:866)、GitHubEvidence や CompletionMode は Phase 1 で入る型に依存しています (:196-209, :223-249)。

影響:

• 自動オーケストレータが依存表だけを見て実行すると、未定義型のまま Phase 4/5 を先行開始し得ます。
• 並列実行時の「着手可能判定」が誤るため、Playbook の DAG Integrity を損ねます。

推奨:

• 依存表を以下に修正してください。
  • Phase 4 → 1,3
  • Phase 5 → 1,3
  • Phase 6 → 1,2,3,4,5
• 依存 DAG は prose ではなく machine-readable にも持つべきです。少なくとも phase_id, depends_on, artifacts_produced, artifacts_required を JSON/YAML で定義した方がよいです。

2. Critical: approval gate が「Phase 遷移」を止める設計になっておらず、個別 API gate と Playbook gate が分離しています

• 文書全体では「Do not start coding until Phase 0 is GREEN」とありますが (deterministic-protocol-playbook.md:921)、Phase 1 以降を止める機械的 gate は Phase 完了条件の文章だけです (:163, :259, :364, :452, :522, :605, :777, :806, :844)。
• Phase 6 の GATE 群は task lifecycle 用であり (:627-762)、Playbook lifecycle 用ではありません。つまり registerTask や assignAndLock の gate はある一方、「Phase 3 が未完了なら Phase 4 の実装を開始できない」を enforce する仕組みが書かれていません。

影響:

• 自律エージェントが「コードを書き始める/次 Phase へ進む」判定を自然言語で行ってしまう
• Playbook の自律実行で premature transition が起きる

推奨:

• Phase ごとに明示的な approvalGate を追加してください。
• 最低限必要な gate:
  • phase0_gate: 全テスト GREEN と index fresh の実コマンド結果を保存済み
  • phaseN_exit_gate: 生成ファイル、テスト、レビュー項目、ログ記録が揃っている
  • phaseN_to_phaseN+1_gate: 前 Phase の exit gate artifact を検証済み
• これを CLI でも miyabi playbook phase-approve <phase> のように機械可読化するのが安全です。

3. High: retry 条件が failure mode 網羅になっていません

• 文書に retry が明示されるのは主に GitHub API degraded mode だけです (deterministic-protocol-playbook.md:580-590, :602-603, :775)。
• しかし failure mode はもっと多いです。

未定義または不十分な failure mode:

• CAS conflict 発生時の retry/backoff 方針がない (:433-437)
• flock 取得失敗・lock file 破損時の retry がない (:428-445, :480-488)
• event append 失敗時の retry / fail-fast 条件がない (:393-399)
• snapshot rebuild が壊れたときの fallback がない (:418-420, :844)
• stale lease 解放後に元エージェントが遅延 heartbeat を送った場合の fence token がない (:503-505, :692-695)
• GitHub evidence fetch は retry があるが、GraphQL の closingIssuesReferences 部分の partial failure 方針がない (:557-560)
• recordBranch, recordPR, verifyMerge, confirmDone で idempotency が定義されていない (:698-744)

推奨:

• 各 Phase に「retry matrix」を追加してください。
• 各 API で少なくとも次を定義:
  • retryable / non-retryable
  • max attempts
  • backoff
  • idempotency key
  • terminal state
• lock 系は heartbeat だけでなく fencing token を入れるべきです。lease を再取得した新オーナーより古い heartbeat は無効化できないと race が残ります。

4. High: Codex 3-body review 反映は前進しているが、未反映の運用タスクがまだあります

反映済み:

• soft deps を level から外す (deterministic-protocol-playbook.md:43-45, :357-360)
• event log + snapshot (:45, :368-452)
• GitHub evidence (:46-50, :536-560)
• completionMode (:50, :208-209, :738-740, :759-761)

未反映または不足:

• review source の traceability がない
  • R1/R2/R3 のどのレビュー文書・誰の判断に基づくかを artifact として残していない。表 (:34-50) だけでは実装後の監査に弱いです。
• single-writer fallback の実運用手順がない
  • Windows/SMB で advisory lock 非保証と書いているだけで (:899)、誰が writer になるか、フェイルオーバー手順、二重 writer 検出がありません。
• queue/lock 連携の migration task がない
  • 既存 agent-skill-bus と task-manager のどちらが lock authority になるか、切替手順がないです。これは earlier review の coordination 論点に対して未着手です。
• approval/audit hook の統合タスクがない
  • Phase 8 で record-run はありますが (:833)、Phase 単位のレビュー承認記録、human approval の永続化フロー、announce/notification は Playbook に未定義です。
• protocol bypass hardening task がない
  • 検証項目には「Protocol 以外の経路で applyTransition を呼ぶテスト」がありますが (:911)、実際に applyTransition を private 化・export しない・store 直書き禁止 lint を入れる等の implementation task が相当 Phase にありません。

5. High: autonomous execution にはまだ曖昧さが残っています

曖昧な点:

• 成果物の exact artifact が Phase ごとに固定されていない
  • 例えば Phase 2 は何ファイルが追加されれば done か曖昧です (:270-364)。
• 誰が human approval を出せるか不明
  • approvedBy はあるが authority が未定義です (:243-249, :671-675)。
• branch existence check の実行コンテキストが不明
  • git branch --list はどの repo/worktree で走るか未指定です (:700-703)。
• current HEAD / current file set の基準が曖昧
  • recordImpact() の gate が repo root / branch / worktree のどれを指すか不明です (:661-665)。
• GitHub linked issue 判定の repo 境界が不明
  • mono-repo / cross-repo PR の扱いが未定義です (:557-560, :736-740)。

結論:

• 現状のままでは「理解している人間」なら進められますが、「Playbook だけ読んだ agent が曖昧さなく自律実行」はまだ厳しいです。

Direct Answers

1. Are the Phase dependencies correct?

部分的には正しいですが、不完全です。

正しい点:

• Phase 6 が 2/3/4/5 の統合に依存するのは妥当です (deterministic-protocol-playbook.md:867)。
• Phase 7 → Phase 8 の流れも妥当です (:868-869)。

誤りまたは不足:

• Phase 4 は実質 1,3 依存です。
• Phase 5 は実質 1,3 依存です。
• 並列可能の記述「Phase 2 は Phase 3/4 と並行可能」は、Phase 6 で統合する前提では正しいものの、型変更が Phase 2/3/4 に跨るので merge coordination task が必要です (:888-890)。

2. Are the approval gates sufficient to prevent premature Phase transitions?

いいえ。task gate はあるが phase gate は足りません。

不足している gate:

• Phase start gate
• Phase exit artifact verification
• reviewer/human approval authority
• protocol bypass prevention before later phases start
• migration completion gate before switching authority from old queue/lock to new protocol

3. Are the retry conditions complete for each failure mode?

いいえ。不完全です。

特に不足:

• CAS conflict retry
• lock acquisition retry and fencing
• late heartbeat handling
• event append failure
• snapshot corruption/rebuild fallback
• GitHub partial evidence failure
• idempotent re-run of recordPR, verifyMerge, confirmDone

4. Is any Phase missing tasks that should be there based on the Codex 3-body reviews in docs/reviews/?

はい。少なくとも次が抜けています。

• Phase 2 or 3:
  • protocol bypass hardening task
  • transition API visibility restriction
• Phase 3 or 4:
  • single-writer / fallback writer election task
  • fence token implementation
• Phase 5:
  • legacy authority migration plan from existing queue/lock
  • GitHub evidence partial-failure handling
• Phase 8:
  • phase-level approval/audit recording
  • crash recovery / replay test
  • idempotent rerun test

補足:

• KOTOWARI/reviews/102-104 は直接この Playbook のレビューではありませんが、そこに共通している教訓は「SSOT 不明」「計画を止める gate が弱い」「CI/計測がないまま完了条件だけ測定可能として書かれている」です (KOTOWARI/reviews/102-storage-layer-review.md, KOTOWARI/reviews/103-testing-strategy-review.md, KOTOWARI/reviews/104-implementation-timeline-review.md)。この弱点は現 Playbook にも残っています。

5. Can an agent execute these Playbooks autonomously without ambiguity?

まだ完全には無理です。

理由:

• 依存が表と実装本文でずれる
• Phase gate が機械可読でない
• retry matrix が不足
• authority/operator の定義が不足
• repo/worktree/repo-owner 境界が曖昧

人間の伴走ありなら実行可能ですが、完全自律化には次が必要です。

Recommended Changes Before Auto Run

1. playbook.yaml を追加し、各 Phase に depends_on, inputs, outputs, approval_gate, retry_policy, owner, commands を持たせる。
2. 依存表を修正する。
   • Phase 4 → 1,3
   • Phase 5 → 1,3
   • Phase 6 → 1,2,3,4,5
3. Phase gate を CLI 化する。
   • 例: miyabi playbook check-phase 3, miyabi playbook approve-phase 3
4. retry matrix を各 API/Phase に追加する。
5. fence token と single-writer fallback を明文化する。
6. legacy queue/lock から新 protocol への authority cutover task を追加する。
7. crash recovery / replay / idempotent rerun を Phase 8 の必須テストにする。

Bottom Line

この Playbook は初回草案よりかなり改善されており、Codex 3-body review の主要論点は多く反映されています。
ただし「自律実行できる Auto Run Playbook」として見ると、まだ task gate の設計が中心で、phase orchestration gate・retry completeness・authority migration が不足しています。現状評価は「設計としては strong、Auto Run 用ハーネスとしては未完成」です。