エージェントハーネス設計 v3 — oh-my-beads / eval-loop 統合
2026-08-14 起草。v2（2026-07-13-agent-harness-design-v2.md）を全面改訂し、
プラグイン oh-my-beads 0.3.1（beads 運用の規律・hook・検査）と
eval-loop（成果物の品質ループ）を統合する。正典の優先順位は不変:
ユーザー指示 > AGENTS.md > 本設計 > プラグイン既定。
0. 診断で確定した現状（2026-08-14 実測）
| 項目 |
実測 |
含意 |
| bd |
1.1.2（サポート版）・.beads = メインリポジトリ共有 |
✓ |
export.auto |
false（1.1.2 の既定） |
.beads/issues.jsonl の passive backup が 1.1.2 更新以降止まっている（AGENTS.md の前提と乖離） |
dolt.auto-commit |
on |
flush 手当不要（batch 化しない限り） |
| dolt remote |
登録済み（git+https）だが remote に refs/dolt/data 不在 |
DB は単機運用・push 実績なし。全ワークツリー + スケジュールセッションが同一ローカル DB を共有するため、単機の限り sync は不要 |
| SessionStart |
この worktree の .claude/settings.json に bd prime hook |
oh-my-beads の SessionStart hook と二重注入（次セッションから ≈5k tokens/回 の無駄） |
1. レイヤ構造（v3 の全体像）
┌ 正典層 AGENTS.md（不変条件・verify ゲート）/ CLAUDE.md（薄いラッパ）
├ 記憶層 bd issue graph（構造的記憶・oh-my-beads 規律）
│ + file memory（セッション横断の長期知見・従来どおり）
│ + docs/superpowers/{specs,plans}（設計成果物・従来どおり）
├ 規律層 oh-my-beads ref 群（bootstrap 分解 / sharp-writing 起票 /
│ dynamic 記録チャネル / idea=wisp→decision gate / session 引継ぎ）
├ 自動化層 orca スケジュール ①-⑧ + oh-my-beads hook（claim provenance・
│ LEARN 自動 note・破壊コマンド deny）+ Seed/リリースの既存 CI
└ 品質層 機械ゲート（pnpm verify・docker proof・ミューテーション = 従来・不変)
+ eval-loop（**文書系成果物のみ**のスコアループ = 新設）
2. 裁定表（oh-my-beads 既定 × waste-link 既存規約）
| # |
論点 |
OMB 既定 |
waste-link 既存 |
裁定 |
| 1 |
bd remember |
原則禁止・唯一の例外 = 並走 agent への短期共有（TTL 1 日・--key 明示・裸キー禁止） |
全面禁止 |
OMB 準拠へ精緻化: 原則禁止は不変。orca スケジュールセッションとの短期共有に限り --key 付きで許可（長期知見は従来どおり file memory）。実質は既存方針の例外条項化 |
| 2 |
TodoWrite / TaskCreate |
不使用（PRIME 絶対ルール） |
1 セッション内の短手順は併用可 |
waste-link 上書き維持。PRIME v3 の上書き節に明記（hook は deny しないことを確認済み — deny は bd init 等の物理系のみ） |
| 3 |
markdown plans |
task tracking に使わない |
docs/superpowers/plans は設計成果物として温存 |
温存（従来の論理そのまま） |
| 4 |
PRIME.md |
テンプレを「常に同期」で上書き |
waste-link 手書き版（3 上書き + verify ゲート） |
マージ版 = PRIME v3: OMB テンプレを本文の base にし、末尾に <!-- waste-link overrides --> 節（本表の裁定 + verify ゲート + Notion/Linear 分担 + 実測事実）を追補。plugin 更新時の再同期手順: テンプレ部だけ差し替え → 上書き節を再追補（手順を PRIME 冒頭に明記） |
| 5 |
SessionStart 注入 |
plugin hook（全 worktree 共通・グローバル） |
worktree ごとに bd setup claude で hook 設置 |
plugin へ一本化: 各 worktree の bd prime hook を除去（run-setup-beads Phase 5 の jq 手順・要承認）。子 worktree 新設時の bd setup claude 手順は廃止（AGENTS.md 該当記述を更新） |
| 6 |
claim 作法 |
bd update <id> --claim を素のコマンド単独で（パイプ・連結・リダイレクトは hook が deny）・claim_session 自動付与 |
チェーン内で --claim 2>&1 \| tail 等 |
OMB 準拠: コーディネーターの自動化チェーンから claim を独立ステップへ分離。bd ready --claim 不使用 |
| 7 |
起票品質 |
ref-beads-sharp-writing（RCT 検証済み文言・逐語適用）+ ref-beads-bootstrap（粒度・依存配線） |
acceptance に verify ゲートを書く運用 |
両立採用: 起票時は sharp-writing 逐語 + acceptance の verify ゲート必須は従来どおり。epic 級の分解は起票前に bootstrap を読み、必要なら eval-loop × assign-sharp-issue-evaluator で品質ループ 1 周 |
| 8 |
未確定アイデア |
wisp → 実装が依存する時点で decision gate へ promote・blocks+defer |
「ユーザーに聞く」を都度セッションで実施 |
採用: ユーザー判断待ちを decision issue + defer で構造化（「聞き忘れて実装が進む」事故の機械的防止）。人間の回答は comment・結論は note |
| 9 |
dolt sync |
claim 直後 push / 終了時 push |
push は人間ゲート |
単機運用の間は push 不要（全セッション同一 DB）。export.auto=true へ復旧して jsonl backup を再開（要承認・git tracked のため export.git-add=true）。複数マシン化する時に初めて配線（Phase 4 手順・人間承認） |
| 10 |
記録チャネル |
note/comment/create/dep/metadata の使い分け（ref-beads-dynamic）・LEARN: 行の自動 note・metadata は 4 キーのみ |
notes 中心の自由記述 |
採用: 特に「学び = LEARN: 行で Stop hook が claim 中 issue へ自動 note」を標準化（file memory との分担: issue 固有=bd / プロジェクト横断=file memory） |
| 11 |
eval-loop の適用 |
汎用（コードにも使える建て付け） |
機械ゲート（verify/proof/ミューテーション） |
文書系成果物に限定: コード品質は従来の機械ゲートが正典で、スコアループで置換しない（ゲートは boolean・スコアは補助）。適用対象は §3 のマップに列挙 |
3. eval-loop 適用マップ（品質層の新設分）
| 成果物 |
generator |
evaluator |
発動 |
| epic 分解・大型スライスの issue セット |
私（bootstrap+sharp-writing 準拠で起票草案） |
oh-my-beads:assign-sharp-issue-evaluator（blind rubric） |
大型機能の着手時（例: 標準EDI S1 の子起票）。閾値到達で bd create 実行 |
| スペック / ADR / PRD 起草 |
既定 generator |
debate evaluator（assign-debate-evaluator） |
prod-critical 設計・方式転換級のみ（乱用しない） |
| 週次レポート / ロードマップ見直し下書き |
既定 |
既定 evaluator（意図忠実度・構造） |
orca ②③⑧ のプロンプトに「品質ループ 1 周（fork 版）」を追記（メイン履歴を汚さない run-eval-loop-fork） |
| 操作手順書・docs ページ |
既定 |
既定 |
新規ページ作成時のみ（既存ページの微修正は不要） |
| コード・migration・proof |
— |
— |
適用しない（pnpm verify / docker proof / ミューテーション実証が正典） |
運用原則: eval-loop は fork 版を既定（履歴の肥大防止）・スコア閾値は 8/10 目安・
2 周で頭打ちなら人間に提示（無限ループしない）。
4. 配線変更（承認後に実施する具体作業）
- PRIME v3 の作成: OMB テンプレ + waste-link 上書き節 →
.beads/PRIME.md
（旧版は .bak 退避）。AGENTS.md の beads 節・CLAUDE.md の Beads ブロック上書き節を
v3 整合へ更新（bd setup claude 手順の廃止・claim 作法・LEARN 行・wisp/decision gate）
- 二重注入の解消: wastelink-coordinator（+ 他 worktree にあれば）の
.claude/settings.json から bd prime SessionStart hook を jq 手順で除去
- jsonl backup 復旧:
bd config set export.auto true + export.git-add true +
.gitattributes に .beads/*.jsonl merge=union（メインリポジトリ）
- orca プロンプト更新: ②③⑧ に fork 品質ループ 1 周、⑦（月次 HK）に
run-beads-lint + run-beads-orphan-check + run-beads-recall 棚卸しを追加
→ 📅 ページ §5 を更新し、ユーザーに orca 側の登録差し替えを依頼
- コーディネーター行動規約の更新（file memory）: claim 独立ステップ化・
起票前 sharp-writing/bootstrap・ユーザー判断待ちの decision+defer 化・LEARN 行
- 検証: run-beads-lint / orphan-check を初回実行し規約適合を確認。
次セッションで SessionStart が plugin 単独発火（PRIME v3 が注入される）ことを確認
5. 変えないもの（明示）
- AGENTS.md の不変条件・verify ゲート・prod-critical/human-reviewed の人間ゲート
- Routing（設計/レビュー=Claude・実装=codex・敵対レビュー=Claude+ミューテーション）
- file memory / docs/superpowers/{specs,plans} / Notion 2 層 / 週次ベロシティ C 方式
- リリース二段階・Seed ワークフロー・運営カレンダーの時刻設計
- 機械ゲートの絶対性（eval-loop のスコアで verify/proof を代替しない）
6. 既知のリスクと緩和
- plugin 更新で PRIME テンプレが変わる → 再同期手順を PRIME 冒頭に明記・
月次 HK（⑦）で
run-setup-beads --dry-run 診断を回して乖離検知
- hook deny による既存自動化の破壊（claim のパイプ等）→ §4-5 の作法変更で回避・
初週は deny 遭遇時に都度 ref-beads/safety.md を参照して調整
- eval-loop のトークンコスト → fork 既定・適用対象の限定・2 周上限で抑制
- スケジュールセッションとの並走（今夜から実働）→ OMB の claim provenance と
session 紐付け（ref-beads-session）がまさにこの衝突を防ぐ層。手動セッション側は
「他 session の claim 中 issue に触らない」を PRIME 絶対ルールとして継承