PlanGate

Harness Improvement Roadmap

Status: v1.2（Phase 0〜6 + Governance + Lightweight Plan Quality Checks すべて Done — EPIC #193 は CLOSED/COMPLETED 2026-05-17。本表は完了状態に同期済） Progress: Phase 0〜6 ✅ / Governance (#201, #202) ✅ / Lightweight Plan Quality Checks (#213) ✅ / 全子 PBI 12/12 CLOSED（EPIC #193 CLOSED） 関連: philosophy.md / eval-plan.md / eval-runner.md / metrics.md / metrics-privacy.md / issue-governance.md / eval-baselines/2026-05-04-baseline.md / model-profiles.md / prompt-assembly.md / tool-policy.md / hook-enforcement.md

1. 目的

PlanGate を「固定されたゲート型ワークフロー」ではなく、モデル差分・実利用データ・評価結果をもとに継続改善される AI ハーネス製品として育てる。

既存の PlanGate は、C-3 / C-4 ゲート、成果物永続化、検証、Model Profile、Prompt Assembly、Tool Policy、Hook Enforcement、Eval Runner を持つ。本ロードマップは、これらを土台に次の段階へ進めるための実装順序を定義する。

中心方針:

仮説 → ハーネス変更 → eval → 実利用シグナル計測 → 採用 / rollback → retrospective

2. 背景

AI コーディングエージェントの品質は、モデル単体だけでは決まらない。モデルに渡すコンテキスト、使わせるツール、編集インターフェース、承認境界、検証方法、失敗時の回復、実利用メトリクスによって大きく変わる。

PlanGate はこの外枠を担うハーネスである。したがって、PlanGate 自体も通常のソフトウェア製品と同じく、仮説、実験、測定、改善のループで育てる。

加えて、計画品質は実装後の eval / metrics だけではなく、実装前の段階で構造化できる。gstack 的な重い agent workflow を直接移植するのではなく、まずは Plan Check / Risk Check / Done Check によって、不足情報・リスク・前提・完了条件を軽量に見える化する。

3. 設計原則

原則 内容
Hard gate は残す C-3 / C-4 / scope / verification honesty / evidence は PlanGate の中核として維持する
補助輪は減らす モデルが自力で取得できる情報は、固定注入ではなく動的取得へ移す
モデル差分を明示する プロンプト全文 fork ではなく、Model Profile / adapter / tool interface preference で吸収する
感覚判断を禁止する Profile / prompt / workflow 変更は eval と実利用シグナルで判断する
成果物の残存を測る code だけでなく plan / test-cases / handoff の Keep Rate を見る
計画品質を先に構造化する 実装・QA・release の前に Missing Items / Risks / Assumptions / Done Criteria を抽出する
低リスクは軽く、高リスクは厳しく mode に応じて検証深度、context budget、strictness を変える

4. 現状ベースライン

PlanGate にはすでに以下が存在する。

領域 既存資産 次の伸びしろ
Workflow / Gate C-3 / C-4、WF-01〜WF-05、Orchestrator Gate 通過率 / 差し戻し率の計測
Model Profile reasoning_effort / verbosity / context budget / tool_policy / validation_bias 編集形式、retry strategy、provider capability の追加
Prompt Assembly base_contract + phase_contract + risk_mode_contract + model_adapter Context Engine との接続
Tool Policy phase 別 allowed tools + profile 射影 provider / model 別の tool interface preference
Hook Enforcement EH-1〜EH-7 / EHS-1〜EHS-3 violation を改善データとして集計
Eval 8 観点 + release blocker + bin/plangate eval 実利用シグナル、Keep Rate、session log parser 拡張
Plan Quality C-3 plan / test-cases / handoff Missing Items / Risks / Assumptions / Done Criteria の構造化

5. ロードマップ概要

v1.2 (2026-05-15 更新): Claude × Codex × Gemini の 5 ディスカッション（Steering Loop / 自己進化軸 / 外部知見照合 / Devil’s Advocate / 外部ユーザー視点）を経て、v8.7.0 主軸を OSS 整備（#226/#224/#225） に組み替え。自己進化機能は副・experimental 扱いに格下げ。ログ: docs/working/discussions/2026-05-14-*.md / 2026-05-15-external-user-codex.md

Phase 名称 目的 主な成果物 Status
0 Baseline alignment 既存 eval / hook / profile の現在地を固定する baseline report ✅ Done (v8.6.0 / #194)
1 Metrics v1 実利用シグナルを保存できるようにする event schema / metrics command ✅ Done (v8.6.0 / #195)
v8.7.0 主 段階的導入ガイド OSS 利用者の最大摩擦「どこまで使えばよいか不明」を解消する Level 1-5 導入レベル / docs ✅ Done (v8.7.0 / #226 / PR #264)
v8.7.0 主 Plugin 成熟化 配布の確実性を機能思想より先に固める 解決順 / prefix / 更新手順 ✅ Done (v8.7.0 / #224 / PR #266)
v8.7.0 主 バージョニング安定性ポリシー breaking vs additive を明文化、既存 artifact 互換を保証 versioning-policy.md ✅ Done (v8.7.0 / #225 / PR #263)
v8.7.0 副 Run Outcome Review v1 run 完了時の振り返りを軽量 markdown で標準化 outcome-review.md template ✅ Done (v8.7.0 / #228 / PR #259)
v8.7.0 副 Lightweight Plan Quality Checks 計画の不足・リスク・前提・完了条件を軽量に構造化する Plan Check / Risk Check / Done Check ✅ Done (v8.7.0 / #213 / PR #267)
v8.7.0 副 Harness Eval expansion eval-runner をハーネス変更判断に使いやすくする comparison / release gate 拡張 ✅ Done (v8.7.0 / #196 / PR #268)
v8.7.0 副 Tool Error Taxonomy hook/tool failure の分類軸 error taxonomy / recovery policy ✅ Done (v8.7.0 / #203 / PR #269)
v8.7.0 副 PlanGateBench Fixture 評価対象固定 fixture suite ✅ Done (v8.7.0 / #204 / PR #270)
v8.7.0 実験 Trace Timeline v1 (Experimental) 観測基盤の最小実装、quickstart 非掲載 schema 1.1 additive / timeline JSON ✅ Done (v8.7.0 / #229 / PR #260)
v8.8.0 Dogfooding Eval v1 PlanGate 自身を評価対象にする (single judge + human rationale) eval suite / fixture ✅ Done (v8.8.0 / #231 / PR #262)
v8.8.0 Gate Event Normalization gate_id / phase / status の語彙正規化 normalized schema ✅ Done (v8.8.0 / #230 / PR #261)
v8.8.0 Model Profile v2 モデルごとの実行特性を表現する edit interface / retry / capability ✅ Done (v8.8.0 / #197 / PR #271) ← v8.7.0 から押し出し
v8.8.0 Keep Rate AI 成果物が残ったかを測る code / plan / acceptance / handoff keep rate ✅ Done (v8.8.0 / #198 / PR #272)
v8.9.0 候補 Dynamic Context Engine 契約コンテキストと作業コンテキストを分離する context manifest / context command ✅ Done (v8.9.0 / #199 / PR #273)
v8.9.0 候補 Reporting & Retrospective スプリント改善に接続する metrics report / retrospective template ✅ Done (v8.9.0 / #200 / PR #274)
- Issue/Label/Milestone Governance Issue 運用ルール固定 issue-governance.md / Issue Form ✅ Done (v8.6.0 / #201)
- Metrics Privacy Policy metrics 公開・秘匿境界 metrics-privacy.md ✅ Done (v8.6.0 / #202)
v8.10.0 Codex CLI parity Claude Code / Codex CLI 間の Hook・Guard・Skill 強制等価を達成する .codex/hooks.json / eh-bridge.sh / codex-guarded.sh / settings-wiring-contract.md ✅ Done (v8.10.0 / EPIC #338)
v8.10.0 Hook/Guard 拡充 EH-9（plan-hash）・pre-push guard・check-tag-main-parity 等を追加し Hook enforcement を強化する scripts/hooks/*.sh / bin/plangate doctor 拡張 ✅ Done (v8.10.0 / TASK-0114/#360, TASK-0115, TASK-0116/#354)
v8.10.0 Skill/Agent 拡充 gh account pinning helper・CI review enhancement 等の Skill/Agent を整備する .claude/agents/*.md / .claude/skills/ ✅ Done (v8.10.0 / TASK-0120/#408)

注: v8.9.0 スコープは v8.8.0 完了後に確定（2026-05-17 v8.9.0 リリース完了・確認済）。v8.10.0 は EPIC #338 Codex CLI parity を中心に完遂（2026-05-26 完了確認済）。

6. Phase 0: Baseline alignment

目的

今後の改善を比較可能にするため、現行 PlanGate の baseline を固定する。

作業

成果物

docs/ai/eval-baselines/
  2026-XX-XX-baseline.md
  2026-XX-XX-baseline.json

完了条件

7. Phase 1: Metrics v1

目的

PlanGate の実利用イベントを append-only で記録し、改善判断に使える状態にする。

対象イベント

Event 意味
task_initialized working context 作成
plan_generated plan / todo / test-cases 生成
c3_decided C-3 の APPROVE / CONDITIONAL / REJECT
exec_started 実装開始
hook_violation EH / EHS 違反検知
v1_completed 受入検査結果
fix_loop_incremented V-1 fix loop 回数
external_review_completed V-3 結果
pr_created PR 作成
c4_decided C-4 の APPROVE / REQUEST CHANGES
handoff_completed handoff 完了

成果物

schemas/plangate-event.schema.json
scripts/metrics-collector.py
bin/plangate metrics <TASK-XXXX>
docs/ai/metrics.md
docs/working/_metrics/events.ndjson

最小スキーマ案

{
  "ts": "2026-05-03T00:00:00Z",
  "task_id": "TASK-XXXX",
  "event": "c3_decided",
  "phase": "plan",
  "mode": "standard",
  "model_profile": "gpt-5_5",
  "provider": "codex",
  "decision": "APPROVE",
  "metadata": {}
}

完了条件

8. Phase 2: Harness Eval expansion

目的

bin/plangate eval を、単発 TASK 評価だけでなく、ハーネス変更の採用判断に使えるようにする。

作業

成果物

schemas/eval-result.schema.json        # 必要なら拡張
scripts/eval-runner.py                 # comparison 拡張
docs/ai/eval-runner.md                 # 運用手順更新
docs/ai/eval-comparison-template.md    # metrics 列追加

追加したい列

列 内容
gate_bounce_rate C-3 / C-4 差し戻し率
hook_violation_count EH / EHS 違反数
v1_first_pass V-1 初回 PASS の有無
fix_loop_count 修正ループ回数
tool_call_count tool 呼び出し回数
rework_count AI 出力後の再修正数
plan_health_score Lightweight Plan Quality Checks による計画品質スコア
open_risk_assumption_count 未解決 risk / assumption の合計数（Lightweight Plan Quality Checks 出力）

完了条件

9. Phase 3: Model Profile v2

目的

モデルごとの「得意な実行形式」を Model Profile に明示する。

追加候補

edit_interface_preference:
  primary: patch
  fallback: string_replace
context_acquisition:
  strategy: dynamic_first
  initial_context_budget: standard
retry_strategy:
  on_edit_failure: reread_then_retry_small_diff
  on_test_failure: inspect_error_then_fix
provider_capabilities:
  supports_patch: true
  supports_string_replace: true
  supports_parallel_subagents: false
telemetry_tags:
  provider: openai
  generation: gpt-5.5

方針

成果物

schemas/model-profile.schema.json       # v2 拡張
docs/ai/model-profiles.yaml             # profile 更新
docs/ai/model-profiles.md               # 説明更新
docs/ai/adapters/*.md                   # 必要に応じて追加

完了条件

10. Support: Lightweight Plan Quality Checks

目的

gstack 的な重い agent workflow を直接移植せず、計画品質を上げる思想だけを PlanGate に軽量に取り込む。

PlanGate の初期価値は、AI が PR review / QA / release まで自動実行することではなく、計画の不足・リスク・暗黙の前提・完了条件を早い段階で明らかにすることにある。

この支援項目では、Plan Check / Risk Check / Done Check を定義し、AI の指摘を自由文ではなく Plan の状態として保存できるようにする。

Check types

Check 目的 主な出力
plan_check 計画の目的、対象、成功条件、スコープを確認する score, missing_items, summary
risk_check 失敗要因、依存関係、未決事項、暗黙の前提を確認する risks, assumptions, next_actions
done_check 完了条件、検証方法、リリース後確認を確認する done_criteria, validation_notes

成果物

schemas/plan-quality-check.schema.json
skills/plan-quality-check/SKILL.md
docs/ai/plan-quality-checks.md
bin/plangate

出力項目

項目 内容
Plan Health Score 計画品質の概算スコア
Missing Items 不足している情報
Risks 起きると困ること
Assumptions 正しい前提として置いていること
Done Criteria 完了条件
Next Actions 次に決める / 確認すること

完了条件

11. Phase 4: Keep Rate

目的

AI が作った成果物が、本当にチーム開発で採用・維持されたかを測る。

指標

指標 内容
Code Keep Rate AI が変更したコードが一定時間後も残っている割合
Plan Keep Rate C-3 承認済 plan の todo / 方針が handoff まで維持された割合
Acceptance Keep Rate test-cases.md の受入条件が V-1 / V-4 まで有効だった割合
Handoff Keep Rate handoff.md の既知課題 / V2 候補 / 妥協点が後続 PBI で参照された割合

測定タイミング

成果物

scripts/keep-rate.py
bin/plangate keep-rate <TASK-XXXX>
schemas/keep-rate-result.schema.json
docs/ai/keep-rate.md

完了条件

12. Phase 5: Dynamic Context Engine

目的

固定コンテキスト注入を減らし、phase / mode / model に応じて必要な情報を動的に組み立てる。

方針

種別 扱い
PBI / approved plan / test-cases / C-3 承認 (c3.json) 契約コンテキストとして固定
git status / diff / recent files / test failure 作業コンテキストとして動的取得
repo structure / coding rules 必要時取得
過去 handoff / 関連 PBI 必要時検索

Context Manifest 案

{
  "task_id": "TASK-XXXX",
  "contract_context": [
    "pbi-input.md",
    "plan.md",
    "test-cases.md",
    "approvals/c3.json"
  ],
  "dynamic_sources": [
    { "type": "git", "name": "git_status", "refresh": "before_execute" },
    { "type": "filesystem", "name": "recent_files", "refresh": "session_start" },
    { "type": "test", "name": "last_test_failure", "refresh": "after_test" }
  ]
}

成果物

schemas/context-manifest.schema.json
scripts/context-engine.py
bin/plangate context <TASK-XXXX> --phase execute --profile gpt-5_5
docs/ai/context-engine.md

完了条件

13. Phase 6: Reporting & Retrospective

目的

PlanGate の実利用シグナルを、スプリントレビュー / retrospective で使える形にする。

レポート項目

項目 意味
C-3 approval / conditional / reject plan 品質
C-4 approve / request changes exec 品質
V-1 first pass rate 実装・受入条件の一致度
fix loop count 自己修正効率
hook violation rate ガードレール違反傾向
Plan Health Score 計画品質の変化
Open Risk / Assumption Count 未解決 risk / assumption の傾向（open_risk_assumption_count 由来）
Keep Rate AI 成果物の実採用度
latency / cost 運用効率
model profile comparison profile ごとの費用対効果

成果物

bin/plangate report --from <date> --to <date>
docs/ai/reporting.md
docs/working/retrospective-template.md

レトロスペクティブで使う問い

今スプリントで AI が最も失敗した phase はどこか？
C-3 差し戻しは PBI の問題か、profile / prompt / context の問題か？
Plan Check で検出された不足情報は、実装中の手戻りを減らしたか？
Risk Check で検出された risk / assumption は、後続の失敗と対応していたか？
V-1 失敗は test-cases の弱さか、exec の弱さか？
どの Model Profile が最も費用対効果が良かったか？
次スプリントで 1 つだけハーネス改善するなら何か？

完了条件

13.5. Control Plane track（v1.2 追加）

位置づけ: Steering Loop A-F は新ロードマップではなく、既存 Phase 2〜6 に重ねる 横断 track。 議論経緯: docs/working/discussions/2026-05-14-steering-loop-codex.md / 2026-05-14-self-evolution-codex.md / 2026-05-14-self-evolution-gemini.md / 2026-05-14-devils-advocate-codex.md / 2026-05-15-external-user-codex.md

13.5.1 自己進化フレーム（MAPE-K mapping）

自己進化要素 PlanGate での担当 業界対応
Monitor (観測) events.ndjson / Trace Timeline v1 (Experimental) OpenTelemetry GenAI semconv (参考、準拠は v8.8.0 以降判断)
Analyze (評価) Dogfooding Eval v1 (v8.8.0) / C-3/C-4 / Run Outcome Review LLM-as-a-Judge（single judge + human rationale）
Plan/Execute (学習・制御) Playbook 昇格（v8.9.0 候補）/ Workflow Reflexion（短期）+ MAPE-K（長期）の二層
Knowledge (記憶) AGENTS.md / Skill / handoff / docs/ai Cognitive Architectures for LLM Agents

重要: Steering Loop は自己進化の 中心 ではなく 観測・再現基盤。中心は「評価 → 学習 → ガバナンス」。Steering Loop はこの 3 つを強化するが代替しない（Devil’s Advocate ラウンド検証済み）。

13.5.2 自己進化 15 軸の地図（実装計画ではなく参照地図）

Level 0 (制約・安全):   安全性 / ガバナンス / 経済性
Level 1 (見える化):     観測 / 記憶 / 外部環境適応
Level 2 (比較・説明):   再現性 / 自己評価 / 品質回帰 / 因果分析
Level 3 (改善候補生成): 学習 / 協調 / 標準化
Level 4 (改善最適化):   適応 / 探索最適化

実装計画に直結させると過大化するため、地図として残し、実装計画とは切り離す（Devil’s Advocate ラウンド推奨）。

13.5.3 段階的導入レベル（#226 で具体化）

外部 OSS 利用者は段階的に PlanGate を採用できる:

初回導線（quickstart）に自己進化機能を混ぜない。Level 5 の機能は experimental / advanced 扱い。

13.5.4 意図的に切り捨てる軸（明示）

以下は OSS 価値より維持費が勝つ ため切り捨てる:

13.5.5 Event schema policy

events.ndjson は schema_version: 1.1 へ additive bump:

注 (steering-loop ログとの整合): 2026-05-14-steering-loop-codex.md Round 2 の DoD 7 項目では trace_id を前提とした紐付け規則が記載されているが、Round 4 Devil’s Advocate ラウンドで「schema を広げすぎる罠」を考慮し、v8.7.0 では parent_event_id のみで紐付けを成立させる方針に 修正済み。trace_id の追加判断は v8.8.0 で再評価する。

13.5.6 OSS 価値整合（Round 5 確定）

機能 OSS としての価値 個人最適化リスク 判断
Trace Timeline 監査・再現・debug イベント粒度が作者運用に最適化されやすい v8.7.0 は experimental に格下げ
Run Outcome Review チームでも個人でも振り返り型 項目過多でメモ化 v8.7.0 の自己進化軸の主役
Dogfooding Eval ハーネス変更の退行検知 評価ケースが作者 repo 閉じ v8.8.0、外部 fixture 意識
events.ndjson 拡張 自動分析の材料 privacy / 互換負債 最小 additive のみ
自動学習 / skill 自動更新 将来価値 OSS では危険 延期

13.5.7 チーム導入で破綻する 5 箇所（要明文化）

3〜10 人チーム導入時に破綻する箇所（Round 5 で抽出）:

  1. Outcome Review の競合 → owner 1 名集約、複数人入力は別ファイル
  2. events.ndjson 共有 → v8.7.0 では共有 store を作らない（個人ローカル、summary だけ転記）
  3. handoff 作成責任 → 実装 owner、C-4 前 reviewer 確認、merge 後追記禁止
  4. Skill/Playbook 所有権 → 通常 PR と同じ扱い、自動更新禁止
  5. Mode 判定揺らぎ → decision table + 例外集を先に整備

14. 優先順位

最初に着手する順序は以下を推奨する。

  1. Phase 1: Metrics v1 — 実利用シグナルがないと以後の改善が感覚判断になる
  2. Phase 2: Harness Eval expansion — 既存 eval-runner を採用判断に使えるようにする
  3. Phase 3: Model Profile v2 — provider / model 差分を実行層に反映する
  4. Lightweight Plan Quality Checks — plan / risk / done の品質を構造化し、後続 metrics / eval / reporting の入力にする
  5. Phase 4: Keep Rate — 成果物が実際に残ったかを見る
  6. Phase 5: Dynamic Context Engine — context の肥大化を抑え、モデル性能向上に追随する
  7. Phase 6: Reporting & Retrospective — チーム改善サイクルに接続する

15. PBI 候補

PBI-HI-001: Metrics v1

As a PlanGate maintainer,
I want workflow events to be recorded as structured metrics,
So that harness improvements can be judged by real usage signals.

Acceptance Criteria:

PBI-HI-002: Eval comparison for harness changes

As a PlanGate maintainer,
I want eval results to compare harness changes against a baseline,
So that profile / prompt / workflow changes are not released by intuition.

Acceptance Criteria:

PBI-HI-003: Model Profile v2

As a PlanGate maintainer,
I want model profiles to include tool interface and retry preferences,
So that each provider can use the execution style it handles best.

Acceptance Criteria:

PBI-PQ-001: Lightweight Plan Quality Checks

As a PlanGate maintainer,
I want plans to be checked for missing information, risks, assumptions, and done criteria,
So that teams can improve plan quality without introducing heavy agent workflow automation.

Acceptance Criteria:

PBI-HI-004: Keep Rate v1

As a PlanGate maintainer,
I want to measure whether AI-generated artifacts remain useful,
So that PlanGate can optimize for accepted work, not just generated work.

Acceptance Criteria:

PBI-HI-005: Dynamic Context Engine v1

As a PlanGate maintainer,
I want context to be assembled dynamically by phase, mode, and profile,
So that agents receive enough information without excessive static context.

Acceptance Criteria:

16. Non-goals

本ロードマップでは以下を直接の目的にしない。

17. リスクと対策

リスク 対策
metrics が増えて運用が重くなる Phase 1 は opt-in / append-only / 最小 event から始める
LLM judge が誤判定する satisfaction signal は soft metric とし、release blocker にしない
Lightweight Plan Quality Checks が hard gate 化して重くなる 初期は手動実行可能な lightweight check とし、blocking 判定にしない（Plan / Risk / Done Check のいずれも非 blocking 維持）
Keep Rate 算出が不安定 unknown を許容し、honesty を優先する
context engine が複雑化する contract / dynamic の 2 分類から始める
profile v2 が provider 固有に寄りすぎる Core Contract / Gate / Artifact schema は共通維持する

18. 推奨する最初の着手

最初は PBI-HI-001: Metrics v1 から始める。

理由:

最初の実装単位:

1. schemas/plangate-event.schema.json
2. scripts/metrics-collector.py
3. bin/plangate metrics <TASK-XXXX>
4. docs/ai/metrics.md
5. hook violation / C-3 / V-1 / C-4 の最小集計

次に PBI-PQ-001: Lightweight Plan Quality Checks を進める。

理由:

This site is open source. Improve this page.