mergegate/docs/dtp/PLAYBOOK-v2.md

DTP Playbook v2 — miyabi-cli-standalone 統合版

v2: miyabi-core の既存資産を最大活用。DTP リポのゼロ実装を廃止。

---

North Star

LLM の揺らぎを許さない。GATE が許可し、GitHub が確定し、merge が不可逆にする。

---

方針転換の理由

miyabi-core に DAG (823行), GitHub (947行), 承認 (231行), 並列実行 (451行), ワークフロー (889行), セッション永続化 (466行), エラーポリシー (536行) が 既に Rust で実装済み。

DTP リポでゼロから書いていた Phase 2 (DAG), Phase 5 (GitHub), Phase 7 (CLI) の大部分は 不要。

---

既存資産マップ（miyabi-core）

ファイル	行数	DTP で使える API
dag.rs	823	TaskGraph, topological_sort, build_levels, TaskGraphBuilder
github.rs	467	GitHubClient, get_issue, get_pull_request, close_issue, create_issue
github_tools.rs	480	Tool registry, execute
orchestration.rs	451	Orchestrator, ParallelConfig, execute_sequential
agent/approval.rs	231	ApprovalCallback trait, AutoApproveAll, RejectHighRisk
workflow.rs	889	Workflow, StepResult, StepStatus, WorkflowManager
error_policy.rs	536	CircuitBreaker, FallbackStrategy
session.rs	466	SessionStorage (save/load/list) — tasks.json 永続化の参考
git.rs	211	find_git_root, get_current_branch, has_uncommitted_changes
openclaw.rs	354	OpenClawClient, get_agents
hooks.rs	862	HookEvent, HookManager, execute
tool.rs	1359	execute_dag, execute_parallel
config.rs	525	設定管理
合計	7654

---

新規追加するもの（4 ファイル / 約 400行）

crates/miyabi-core/src/
├── gate.rs      (~100行) NEW: GATE 検証関数
├── lock.rs      (~100行) NEW: ファイルロック (lease + heartbeat)
├── protocol.rs  (~150行) NEW: DeterministicExecutionProtocol
└── store.rs     (~50行)  NEW: tasks.json 永続化

---

Phase 構成（v1 の 8 Phase → v2 の 3 Phase に圧縮）

Phase A: GATE + Lock + Store（新規 4 ファイル）

やること:

• src/gate.rs を作成
  • ensure_issue(task) -> Result<()>: github_issue_number > 0
  • ensure_dependencies_done(task, done_ids) -> Result<()>: 全依存が done
  • ensure_impact(task, human_approved) -> Result<()>: impact 記録済 + HIGH→承認
  • ensure_branch_name(name) -> Result<()>: feature/issue-N-* 形式
  • ensure_pr_ready(task) -> Result<()>: branch + pr_number 存在
  • ensure_merge_commit(sha) -> Result<()>: 40文字 hex
• src/lock.rs を作成
  • FileLockManager: acquire_lock, release_lock, has_conflict, release_expired
  • lease_duration + last_heartbeat ベース
  • from_tasks() で既存タスクからロック状態を復元
• src/store.rs を作成
  • TaskStore: with_file(path), load, save (atomic rename), add_task, update_task, get_task
  • tasks.json スキーマ: version, tasks[], file_locks, dag_levels
  • session.rs の save/load パターンを参考に実装
• src/protocol.rs を作成
  • DeterministicExecutionProtocol: 全 GATE を統合
  • register_task → check_dependencies → record_impact → assign_and_lock → record_branch → record_pr → record_merge
  • 各メソッドで GATE 検証 → 状態遷移 → store 永続化
• src/lib.rs に pub mod gate; pub mod lock; pub mod protocol; pub mod store; を追加
• テスト: happy path (register → ... → done)
• テスト: GATE 拒否 (issue なし, impact なし, 不正 SHA, ロック競合)
• テスト: HIGH risk → 承認なし → 拒否
• cargo test GREEN
• cargo clippy --all-targets --all-features -- -D warnings GREEN

担当: Codex A (worktree) 依存: なし GATE: test GREEN + clippy GREEN + 8 テスト以上

参照ファイル:

• src/dag.rs — TaskGraph の API（DAG 操作のインターフェース確認）
• src/session.rs — SessionStorage の save/load パターン
• src/agent/approval.rs — ApprovalCallback の承認パターン
• src/error.rs — エラー型の定義パターン

---

Phase B: CLI サブコマンド追加

やること:

• src/main.rs（既存 CLI エントリ）に DTP サブコマンドを追加
  • miyabi-cli gate register --issue N --title T
  • miyabi-cli gate status [task-id]
  • miyabi-cli gate assign <task-id> --agent A --node N --files F
  • miyabi-cli gate impact <task-id> --risk R --symbols N
  • miyabi-cli gate branch <task-id> <name>
  • miyabi-cli gate pr <task-id> <number>
  • miyabi-cli gate merge <task-id> <sha>
  • miyabi-cli gate locks
  • miyabi-cli gate dag
  • miyabi-cli gate dispatchable
• --format json 対応（全コマンド）
• 終了コード: 0=成功, 1=GATE拒否, 2=入力不正
• --store-path オプション（tasks.json のパス指定）
• テスト: register → status で task 表示
• cargo test GREEN
• cargo clippy GREEN

担当: Codex B (worktree) 依存: Phase A GREEN GATE: register + status が動作 + JSON 出力

参照ファイル:

• src/main.rs（既存 CLI 構造）
• 既存のサブコマンド実装パターン

---

Phase C: GitHub Evidence + E2E

やること:

• src/github.rs の既存 get_pull_request() を使って merge 証跡を取得するラッパー追加
  • fetch_merge_evidence(pr_number) -> Result<MergeEvidence>
  • MergeEvidence { merge_commit_sha, merged_at, state, head_ref }
• protocol.rs に verify_merge() を追加（record_merge を置換）
  • GitHub API 経由で PR merged を検証
  • 障害時は AwaitingGithubSync 的なエラーを返す
• protocol.rs に escape hatch 追加
  • force_unlock(task_id, reason)
  • manual_complete(task_id, reason)
• E2E テスト:
  1. register → check_dependencies → record_impact → assign_and_lock
  2. record_branch → record_pr → verify_merge（mock）
  3. status → Done
• cargo test GREEN
• cargo clippy GREEN
• npx miyabi bus record-run --skill dtp --result success

担当: Claude Code (local) — GitHub API アクセスが必要 依存: Phase A + B GREEN GATE: E2E テスト GREEN + clippy GREEN

参照ファイル:

• src/github.rs — GitHubClient (既存)
• src/error_policy.rs — CircuitBreaker (障害時フォールバック)
• src/hooks.rs — HookEvent (audit hooks)

---

Phase DAG

Phase A (gate + lock + store + protocol)
    │
    ├──→ Phase B (CLI サブコマンド)
    │        │
    └────────┤
             ▼
         Phase C (GitHub Evidence + E2E)

Phase A と B は A 完了後に B 開始（直列）。 Phase C は A + B 完了後に開始。

---

時間見積もり

Phase	新規行	テスト行	時間
A	400	200	15分
B	150	50	10分
C	100	100	10分
合計	650	350	35分

Codex 並列なら A(15分) → B+C 並列(10分) = 約 25分。

---

v1 → v2 の差分

項目	v1 (8 Phase)	v2 (3 Phase)
新規コード量	1,780行	1,000行
Phase 数	8	3
DAG 実装	新規	不要（dag.rs 823行あり）
GitHub 実装	新規	不要（github.rs 947行あり）
承認実装	新規	不要（approval.rs 231行あり）
並列実行	新規	不要（orchestration.rs 451行あり）
CLI 構造	新規	不要（main.rs の既存構造に追加）
推定時間	1〜1.5時間	25〜35分

---

Codex レビュー反映状況

指摘	v2 での対応
R1-1: conditions 未評価	Phase A: gate.rs で検証関数を独立実装、protocol.rs が唯一の窓口
R1-3: 出自検証なし	Phase C: github.rs 経由で merge 証跡を検証
R1-5: TTL 固定	Phase A: lock.rs に lease_duration + last_heartbeat
R2-1: atomic write	Phase A: store.rs で atomic rename
R2-2: TOCTOU	Phase A: lock.rs の acquire で再チェック
R3-1: SSOT 昇格しすぎ	tasks.json は execution ledger、GitHub が authority
R3-4: merge commit 取得経路	Phase C: github.rs の get_pull_request() で merge_commit_sha 取得
R3-5: escape hatch	Phase C: force_unlock, manual_complete
Playbook R2: Phase 依存不完全	v2 で 3 Phase に圧縮、依存が明確
Playbook R2: Phase gate 不足	各 Phase に GATE (test + clippy) を明記

---

ロールバックポイント

Phase	タグ	戻り方
A 完了	v0.1-dtp-phase-a	git checkout v0.1-dtp-phase-a
B 完了	v0.2-dtp-phase-b	git checkout v0.2-dtp-phase-b
C 完了	v1.0-dtp-complete	git checkout v1.0-dtp-complete

---

引き継ぎ

Phase 間の引き継ぎは autorun/HANDOFF.md のプロシージャに従う。 v2 では Phase が 3 つだけなので、引き継ぎポイントは 2 箇所:

1. Phase A → Phase B: gate/lock/store/protocol が動く状態を確認
2. Phase B → Phase C: CLI が動く状態を確認

---

This is the single source of truth for DTP implementation in miyabi-cli-standalone. Do not start coding until this Playbook is approved.