marketing-shibata50/mergegate
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
mergegate/docs/dtp/reviews/round2-openclaw.md
林 駿甫 (Shunsuke Hayashi) 39a5180b8e [文書] DTP Playbook v2: 8 Phase → 3 Phase に圧縮 
miyabi-core 既存資産（7,654行）を最大活用する方針に転換。
v1 の 1,780行新規 → v2 の 1,000行新規（既存 DAG/GitHub/承認/並列を流用）。
推定時間: 1〜1.5時間 → 25〜35分。

Phase A: gate.rs + lock.rs + store.rs + protocol.rs（4ファイル新規）
Phase B: CLI サブコマンド追加（既存 main.rs に追加）
Phase C: GitHub Evidence + E2E テスト

Codex Round 2 レビュー 3件も保存。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-10 01:15:24 +09:00

418 lines
18 KiB
Markdown
Raw Blame History

# Review: OpenClaw Agent Integration for DTP
## Executive Summary
現状の `deterministic-task-protocol` は、OpenClaw `main` エージェントが自律的に `draft -> done` を回すにはまだ入口が足りません。最大の理由は 3 つです。
1. `dtp` バイナリに実用 CLI がまだなく、`src/main.rs` は単なる bootstrap 出力しか持っていません。[`src/main.rs:1`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/src/main.rs#L1)
2. protocol 実装は in-memory happy path に留まっており、GitHub 証跡検証、lease heartbeat、reconcile、event log、JSON 出力、終了コード、identity 付きの運用コマンドが未実装です。[`src/protocol.rs:53`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/src/protocol.rs#L53) [`src/store.rs:47`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/src/store.rs#L47)
3. repo 直下の `AGENTS.md` は Rust 開発ガイドとしては十分ですが、OpenClaw main がこの repo でどう振る舞うかは書かれていません。逆に `refs/AGENTS.md` と `refs/SOUL.md` は広すぎて、この repo 専用の実行契約になっていません。[`AGENTS.md:1`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/AGENTS.md#L1) [`refs/AGENTS.md:1`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/refs/AGENTS.md#L1) [`refs/SOUL.md:56`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/refs/SOUL.md#L56)
Playbook 側はかなり正しく、OpenClaw integration の要件もおおむね言語化できています。特に authority-aware sync、`awaiting_github_sync`、lease + heartbeat、escape hatch、CLI subcommands は妥当です。[`docs/PLAYBOOK.md:46`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/docs/PLAYBOOK.md#L46) [`docs/PLAYBOOK.md:456`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/docs/PLAYBOOK.md#L456) [`docs/PLAYBOOK.md:526`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/docs/PLAYBOOK.md#L526) [`docs/PLAYBOOK.md:747`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/docs/PLAYBOOK.md#L747) [`autorun/phase-7-cli/TASKS.md:8`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/autorun/phase-7-cli/TASKS.md#L8)
以下、質問ごとに整理します。
## 1. Can an OpenClaw agent (main) call the DTP CLI to execute the full protocol? What is missing?
### Short answer
まだできません。
### Why not
- `dtp` CLI が未実装です。`src/main.rs` は `"dtp: deterministic-task-protocol bootstrap"` を出すだけです。[`src/main.rs:1`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/src/main.rs#L1)
- protocol の public API は Rust から直接呼ぶ前提のメソッド群だけで、OpenClaw main が shell command として安全に使える interface になっていません。[`src/protocol.rs:62`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/src/protocol.rs#L62)
- `TaskStore::with_file()` はあるものの、protocol の `new()` は default in-memory store を使うだけで、CLI/daemon から永続ストアを注入する導線がありません。[`src/protocol.rs:54`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/src/protocol.rs#L54) [`src/store.rs:53`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/src/store.rs#L53)
- merge 検証は `record_merge(task_id, merge_commit)` に文字列を渡せば通る設計で、GitHub API からの出自検証がありません。OpenClaw agent が勝手に SHA を渡せてしまいます。[`src/protocol.rs:183`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/src/protocol.rs#L183) [`src/gate.rs:72`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/src/gate.rs#L72)
- lock は固定 TTL のみで heartbeat/lease renew がありません。cron から lease 維持もできません。[`src/types.rs:26`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/src/types.rs#L26) [`src/lock.rs:52`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/src/lock.rs#L52)
- state model がまだ `merged` / `awaiting_github_sync` / `manual` 系を持っていません。OpenClaw 運用ではここが重要です。[`src/types.rs:7`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/src/types.rs#L7) [`docs/PLAYBOOK.md:211`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/docs/PLAYBOOK.md#L211)
- output contract が未定義です。OpenClaw main が自律運転するには JSON 出力と機械判定可能な exit code が必須ですが、現状ありません。[`autorun/phase-7-cli/TASKS.md:28`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/autorun/phase-7-cli/TASKS.md#L28)
### Minimum missing pieces before OpenClaw can drive it
1. 実 CLI 実装
2. 永続 store path の指定
3. GitHub credentials / repo context の指定
4. JSON 出力
5. 明確な exit code
6. identity-aware lock ownership
7. heartbeat renew / stale sweep
8. GitHub evidence fetch + reconcile
9. manual/external completion path
10. audit hooks
## 2. How should `CLAUDE.md` and `AGENTS.md` be structured for this repo so agents know the rules?
### Current problem
- repo 直下 `AGENTS.md` は開発者向けで、OpenClaw/Codex/Claude がこの repo で何を守るべきかの運用契約が不足しています。[`AGENTS.md:16`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/AGENTS.md#L16)
- `refs/AGENTS.md` は openclaw-workspace 全体の map、`refs/SOUL.md` は OpenClaw main の人格/優先順位です。どちらも大事ですが、この repo 専用の「DTPをどう運転するか」までは書いていません。[`refs/AGENTS.md:6`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/refs/AGENTS.md#L6) [`refs/SOUL.md:58`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/refs/SOUL.md#L58)
- 現状 `.claude/` と `.codex/` にガイドファイルがありません。これは repo-specific behavior を agents に教える機会を逃しています。
### Recommended structure
#### `AGENTS.md` at repo root
役割: repo-local execution contract。全エージェント共通の「この repo ではどう動くか」を簡潔に書く。
入れるべき内容:
1. Repo mission
2. SSOT split
3. Mandatory startup reads
4. Allowed / forbidden transitions
5. Required commands before and after edits
6. DTP-specific invariants
7. CLI-first operation rules
8. Testing and verification contract
9. Links to `refs/AGENTS.md` / `refs/SOUL.md` / `docs/PLAYBOOK.md`
サンプル見出し:
- `Purpose`
- `Read First`
- `Fact vs Execution Ledger`
- `If You Modify Protocol`
- `If You Run as OpenClaw Main`
- `Required Verification`
- `Escape Hatches`
特に重要な文言:
- `GitHub is fact SSOT; local snapshot is execution ledger.`
- `No agent may mark a task done without GitHub evidence or an audited manual/external completion path.`
- `All automation must prefer dtp CLI over direct JSON edits.`
- `Heartbeat ownership must match agent@node.`
#### `CLAUDE.md`
役割: Claude Code / OpenClaw-style operator brief。対話型エージェントや main agent 向けに「どの順で読むか」「どう dispatch するか」を書く。
入れるべき内容:
1. Session startup for this repo
2. `docs/PLAYBOOK.md` is normative for implementation order
3. `autorun/*/TASKS.md` and `GATE.md` drive phase execution
4. When acting as OpenClaw main, prefer orchestration and delegation, not direct code hoarding
5. When acting on user message, direct answer still wins per `refs/SOUL.md`
6. Exact `dtp` commands for autonomous operation
7. Escalation points
推奨順序:
1. `refs/SOUL.md`
2. repo `AGENTS.md`
3. `docs/PLAYBOOK.md`
4. relevant `autorun/phase-*/TASKS.md`
5. relevant handoff note
### Concrete recommendation
- `AGENTS.md`: durable, cross-agent, repo-local invariant
- `CLAUDE.md`: runtime/operator workflow for Claude/OpenClaw style agents
- `refs/AGENTS.md` / `refs/SOUL.md`: inherited upstream context only
つまり、`refs/*` を読むだけでは不十分で、この repo 自身の `AGENTS.md` と `CLAUDE.md` に DTP運転ルールを持つべきです。
## 3. What is the minimal CLI interface needed for an agent to autonomously run draft-to-done?
### Truly minimal autonomous set
Playbook の一覧は広めですが、OpenClaw main が自律的に `draft -> done` を回すための最小集合はこれです。
1. `dtp register`
2. `dtp dispatchable`
3. `dtp impact`
4. `dtp approve`
5. `dtp assign`
6. `dtp heartbeat`
7. `dtp branch`
8. `dtp pr`
9. `dtp verify-merge`
10. `dtp confirm-done`
11. `dtp status --json`
### Why each is needed
- `register`: Issue と completion mode を固定する
- `dispatchable`: main が次に実行すべき task を判定する
- `impact`: GATE 3 を通す
- `approve`: HIGH/CRITICAL の人間承認を監査付きで残す
- `assign`: lock と owner identity を確定する
- `heartbeat`: 実装中 lease を維持する
- `branch`: 実在 branch を state と結びつける
- `pr`: PR identity を task に紐づける
- `verify-merge`: GitHub authority から merged 事実を pull する
- `confirm-done`: completion mode に応じて最終確定する
- `status --json`: orchestration loop が機械判定する
### Additional commands that are near-minimal in production
OpenClaw 運用まで考えると、次の 4 つも事実上必要です。
1. `dtp unlock --reason --operator`
2. `dtp reconcile`
3. `dtp sweep-leases`
4. `dtp events --json`
### Output contract
各コマンドに最低限必要な contract:
- `--json` support
- stable schema
- deterministic exit code
- no interactive prompt by default
推奨 exit code:
- `0`: success
- `1`: gate rejected
- `2`: invalid input
- `3`: conflict / lease lost
- `4`: GitHub unavailable / degraded
- `5`: invariant violation / bug
### Missing from current implementation
- `src/main.rs` に clap CLI なし
- `approve` コマンド相当なし
- `status` / `dispatchable` / `reconcile` / `sweep-leases` なし
- JSON output なし
- store path / repo context / operator identity flags なし
## 4. How should heartbeat/lease renewal work when called from a cron job?
### Current gap
現状は TTL だけで、lease renew 機構がありません。[`src/types.rs:33`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/src/types.rs#L33) [`src/lock.rs:52`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/src/lock.rs#L52)
Playbook は lease 300s + heartbeat 60s + missed heartbeats 2 を提案していて、これは妥当です。[`docs/PLAYBOOK.md:40`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/docs/PLAYBOOK.md#L40) [`docs/PLAYBOOK.md:467`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/docs/PLAYBOOK.md#L467)
### Recommended model
#### Lease data
`TaskLock` should carry:
- `locked_by`
- `locked_at`
- `lease_duration_sec`
- `heartbeat_interval_sec`
- `last_heartbeat`
- `fencing_token`
- `affected_files`
### Cron interaction model
cron からは 2 系統に分けるべきです。
1. owner cron: lease renew
2. janitor cron: stale lease sweep
#### Owner renew
コマンド例:
```bash
dtp heartbeat <task-id> --agent main --node mainmini --json
```
必要な gate:
- task exists
- task is in `implementing` or other active state
- lock exists
- lock owner matches `agent@node`
- lease is not already fenced off by newer owner
成功時:
- `last_heartbeat` 更新
- `lock_heartbeat` event 記録
- new `expires_at` を JSON 出力
失敗時:
- exit `3` if lock ownership lost
- exit `1` if task not heartbeat-eligible
- exit `4` if store or GitHub degraded path relevant
#### Janitor sweep
コマンド例:
```bash
dtp sweep-leases --json
```
責務:
- stale lease を検出
- forced release を event として記録
- task state を `blocked` or `pending_recovery` 相当に移す
- owner mismatch を報告
### Important rule
cron は「とりあえず更新」してはいけません。owner identity を必ず指定し、`main@mainmini` が保持する lock を `main@mainmini` の cron だけが renew できるようにすべきです。
### Recommended timings
- lease duration: 300s
- heartbeat interval: 60s
- stale after: 2 missed intervals
- janitor sweep: every 2-5 min
### Why cron needs both renew and sweep
OpenClaw main は long-running conversation とは限らず、cron や heartbeat runner に lease 維持を委譲する場面があります。そのため:
- active owner renews
- janitor reclaims abandoned leases
の二面構成が必要です。renew だけだと orphan lock が残り、sweep だけだと稼働中タスクを誤解放します。
## 5. What escape hatches are needed for production operation?
### Required escape hatches
1. `force-unlock`
2. `reconcile-from-github`
3. `manual-complete`
4. `external-op-complete`
5. `reopen`
6. `takeover-lock`
7. `mark-awaiting-github-sync`
8. `retry-github-sync`
9. `abandon-task`
10. `supersede-task`
### Why they are needed
- agent crash
- lock orphaning
- GitHub outage
- merge happened externally
- no-PR legitimate work
- human intervention in production
### Minimum audited fields for every escape hatch
- `operator`
- `reason`
- `approved_by`
- `timestamp`
- `previous_state`
- `new_state`
- `correlation_id`
### Specific recommendations
#### `force-unlock`
必要条件:
- operator required
- reason required
- current lock holder and age recorded
#### `manual-complete`
使いどころ:
- docs-only
- external ops
- emergency human completion
必要条件:
- `completion_mode in {manual, external-op}`
- human approval present
- audit event recorded
#### `reconcile-from-github`
使いどころ:
- PR merged externally
- issue closed externally
- webhook missed
これは production では特に重要です。OpenClaw main は drift 修正のために自律的に reconcile できる必要があります。
#### `takeover-lock`
クラッシュ復旧で重要です。`force-unlock` と `assign` を別々にやるより、
- old owner stale confirmed
- operator approves takeover
- new fencing token issued
を一発でやる方が安全です。
## Additional Findings
### A. Current `AGENTS.md` is too generic for autonomous agents
repo root の `AGENTS.md` は Rust 開発ガイドとしては問題ありませんが、agent execution protocol が不足しています。OpenClaw main はこの文書を読んでも、
- どの docs を先に読むべきか
- `refs/*` をどう扱うか
- `dtp` をどう叩くか
- いつ人間に escalate すべきか
が分かりません。[`AGENTS.md:63`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/AGENTS.md#L63)
### B. `refs/AGENTS.md` and `refs/SOUL.md` should remain references, not runtime-only truth
symlink 自体は良いです。upstream workspace のルールと main の人格を持ち込めます。[`refs/AGENTS.md:6`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/refs/AGENTS.md#L6) [`refs/SOUL.md:1`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/refs/SOUL.md#L1)
ただし、この repo の運用契約まで symlink 先に依存すべきではありません。repo local の `AGENTS.md` / `CLAUDE.md` で上書きすべきです。
### C. Playbook already implies the right CLI, but implementation lags far behind
Playbook と autorun task は、OpenClaw integration の設計書としてかなり使えます。特に:
- `heartbeat`
- `verify-merge`
- `confirm-done`
- `unlock`
- `reconcile`
- `run-e2e`
はそのまま CLI contract にすべきです。[`docs/PLAYBOOK.md:781`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/docs/PLAYBOOK.md#L781) [`autorun/phase-7-cli/TASKS.md:10`](/Users/shunsukehayashi/dev/platform/_core/miyabi-private/deterministic-task-protocol/autorun/phase-7-cli/TASKS.md#L10)
## Recommended Next Moves
1. Implement real `dtp` CLI in `src/main.rs` with clap and JSON output first.
2. Add repo-local `CLAUDE.md` focused on OpenClaw/Codex operation order.
3. Expand repo-local `AGENTS.md` from generic Rust guidance to execution contract.
4. Add persistent store path + identity flags to every mutating command.
5. Implement `heartbeat` and `sweep-leases` before trying autonomous OpenClaw runs.
6. Implement `verify-merge` and `reconcile` before allowing `confirm-done`.
7. Add audited escape hatches before production use.
## Direct Answers
### (1) Can OpenClaw main call the dtp CLI for the full protocol?
まだ無理です。`dtp` CLI 自体が未実装で、GitHub verification、heartbeat、JSON output、persistent store、escape hatch が足りません。
### (2) How should `CLAUDE.md` and `AGENTS.md` be structured?
- `AGENTS.md`: repo-local invariant and execution contract
- `CLAUDE.md`: runtime/operator workflow for Claude/OpenClaw style agents
- `refs/*`: inherited upstream context only
### (3) Minimal CLI for autonomous draft-to-done?
`register`, `dispatchable`, `impact`, `approve`, `assign`, `heartbeat`, `branch`, `pr`, `verify-merge`, `confirm-done`, `status --json` が最小です。運用上は `unlock`, `reconcile`, `sweep-leases`, `events --json` もほぼ必須です。
### (4) How should heartbeat/lease renewal work from cron?
owner cron による `heartbeat` と janitor cron による `sweep-leases` の二系統。identity match と fencing token が必要です。lease 300s / heartbeat 60s / stale after 2 misses を推奨します。
### (5) What escape hatches are needed?
`force-unlock`, `reconcile-from-github`, `manual-complete`, `external-op-complete`, `reopen`, `takeover-lock`, `mark-awaiting-github-sync`, `retry-github-sync`, `abandon-task`, `supersede-task` が必要です。全て audit fields 必須です。
Reference in a new issue View git blame Copy permalink