chore: git方針の変更とセマンティクス変更の計画の帳尻合わせ

2026-05-08 20:17:11 +09:00 · 2026-05-08 20:17:11 +09:00 · ed08ee1ce1
commit ed08ee1ce1
parent 12e7d27a08
5 changed files with 169 additions and 4 deletions
--- a/.insomnia/manifest.toml
+++ b/.insomnia/manifest.toml
@ -1,3 +1,9 @@
+[scope]
+allow = [
+    { target = ".", permission = "write", recursive = true },
+    { target = "/home/hare/ghq", permission = "read", recursive = true },
+]
+
 [memory]
 extract_threshold = 50000

--- a/AGENTS.md
+++ b/AGENTS.md
@ -4,21 +4,26 @@

 - プロンプトはすべて resources/promptsに集約している。管理効率の工場と同時に、ユーザーがオーバーライドする形式でもある。
 - E2E(実プロセスをスポーンさせてのテスト)は未設計。
+- 変更量を最小にするために設計を歪めたり、設計問題に対して不必要な後方互換性を作らない。長期的なメンテナンスと型安全性を追求すること。

 ### LLM コンテキストの加工原則

 LLM に投げる context への割り込みは、大きく2種類に分かれる。**前者は許されるが、後者は禁止**。

- **許される**: 既存 history から純粋に再現可能な変換器（pruning、compaction による要約、tool result の content 切り詰め、prompt cache anchor の付与等）。同じ history を入力すれば同じ結果が出る決定的な加工で、history そのものを書き換えるわけでもなく、外から新しい情報を持ち込まない。
- **禁止**: Pod の現在状態（受信した notification、active な内部キュー、time-of-day、外部イベント等）に基づいて、history に commit せずに context だけに新規 input を差し込むこと。これをやると LLM はそれに反応して history を変化させる一方、トリガーは worker.history に残らないため、次ターン以降「自分がなぜその発言/tool call をしたか」の根拠が消える。resume 時にはさらに露骨に再現不能になる。prompt cache の prefix も毎回ズレる。
+- **許される**: 既存 history から純粋に再現可能な変換器（pruning、tool result の content 切り詰め、prompt cache anchor の付与等）。同じ history を入力すれば同じ結果が出る決定的な加工で、history そのものを書き換えるわけでもなく、外から新しい情報を持ち込まない。
+- **禁止**: ターンを跨ぐことができない情報に基づいて、history に記録せずに context だけにコンテンツを差し込むこと。これをやると LLM はそれに反応して生成を行う一方、次以降のターンでhistoryに残らないため、「自分がなぜその発言/tool call をしたか」の根拠が消えるうえ、prompt cache のヒット率も低下させることになる。

 新しい input を context に乗せたいなら、必ず先に `worker.history` に append して commit すること。`history.json` への永続化はそこから自動的についてくる。Notify / PodEvent / `<system-reminder>` 系はこの原則で扱う（→ `tickets/notify-history-persist.md`）。
+また、キャッシュを破壊するタイミングは正確にコントロールされる必要があり、キャッシュ破壊とトークン消費のトレードオフに基づいて慎重に設計されるべきである。

 ---

-Gitは基本的にすべてユーザーが操作している。書き込みが必要な操作は明示的に許可されない限り行わないこと
+## Git操作

-外部の参考プロジェクトはghqでローカルでReadする運用をしている。
+Gitはpush以外のすべての操作が許可されている。
+基本はworktree上の一時的なブランチでコミットを重ね、メインブランチに取り込む運用をしている。
+
+外部の参考プロジェクトはghqでgetしており、必要に応じて`~/ghq`からReadすること。

 ---

--- a/TODO.md
+++ b/TODO.md
@ -2,6 +2,7 @@
  - 内部 Worker / 内部 Pod の Workflow 化 → [tickets/internal-worker-workflow.md](tickets/internal-worker-workflow.md)
  - 半自動開発運用 Workflow → [tickets/auto-maintain-workflow.md](tickets/auto-maintain-workflow.md)
  - Workflow を memory crate から独立させる → [tickets/workflow-crate-extraction.md](tickets/workflow-crate-extraction.md)
+  - Prompt / Workflow 評価メトリクスと改善 Offer → [tickets/prompt-eval-metrics.md](tickets/prompt-eval-metrics.md)
 - パーミッション: パターンベースのツール実行制御 → [tickets/permission-extension-point.md](tickets/permission-extension-point.md)
 - Pod CLI: マニフェスト関連フラグの整理 → [tickets/pod-cli-manifest-flags.md](tickets/pod-cli-manifest-flags.md)
 - Pod: 空応答ターン (Submit 後 AI 応答ゼロで Pause/Cancel) を自動巻き戻し → [tickets/pod-empty-turn-rollback.md](tickets/pod-empty-turn-rollback.md)
--- a/tickets/persistence-semantics.md
+++ b/tickets/persistence-semantics.md
@ -38,6 +38,11 @@
  - Pod が過去に辿った session / log の順序付き履歴をどこに持つべきか。
 - runtime state と persistent state の境界。
  - `history.json` / `status.json` / `spawned_pods.json` を永続正本として扱わない方針の確認。
+- session log の `pod.scope` extension entry を撤廃するか（要検討）。
+  - 現状: session log に `PodScopeSnapshot` を extension として append し、session 復元時に scope も復元できる。
+  - Pod 単位永続化（`tickets/pod-persistent-state.md`）が入ると、scope の正本を Pod state に持つほうが責務が明確で、session log との重複も解消できる。
+  - ただし scope は session 内で動的に変化し得るため、「最新 snapshot は Pod state 」「変化履歴は session log の event として残す」のような分割もあり得る。conversation timeline 上の scope 変化を session 単独で再現する必要があるかが論点。
+  - 撤廃の選択肢: (a) session log から完全に削除し Pod state を唯一の正本にする / (b) snapshot 保持責務だけ Pod state に寄せ、scope 変更 event は session log に残す / (c) 現状維持で Pod state は session への参照のみ。
 - DB backend を想定した場合のテーブル / relation 相当の構造。
  - append-only entry log
  - lineage / origin
--- a/tickets/prompt-eval-metrics.md
+++ b/tickets/prompt-eval-metrics.md
@ -0,0 +1,148 @@
+# Prompt / Workflow 評価メトリクスと改善 Offer
+
+## 背景
+
+mizchi の empirical-prompt-tuning は、agent-facing な指示（Skill / slash command / prompt 等）を新規 subagent に実行させ、実行者の自己申告と指示側メトリクスを突き合わせて反復改善する手法である。insomnia では Workflow / Skill ingest / Knowledge / memory consolidation / usage metrics / Pod orchestration があるため、この手法を単なる「手順」ではなく、**agent-facing instruction の品質観測 pipeline** として扱える。
+
+特に insomnia では以下をシステム側で観測できる。
+
+- evaluator Pod の session id / history
+- tool call / tool result
+- usage tokens
+- workflow / knowledge の明示 invoke 頻度（`tickets/memory-usage-metrics.md`）
+- `model_invokation` 常駐注入のコスト側指標
+- Phase 1 / Phase 2 memory consolidation による recurring pattern 抽出
+- Workflow 自動書き込み禁止に基づく improvement offer
+
+したがって、`/empirical-prompt-tuning` 相当の Workflow は、評価実行を orchestration するだけでなく、評価結果を構造化 event として残し、将来的に memory consolidation / usage metrics / Workflow improvement offer / `model_invokation` 判断へ接続するべきである。
+
+## 要件
+
+### `/empirical-prompt-tuning` Workflow
+
+`.insomnia/workflow/empirical-prompt-tuning.md` を追加し、Workflow / Skill / prompt / Knowledge を評価対象として扱える手順を用意する。
+
+Workflow は少なくとも以下を明示する。
+
+- 評価対象 target の固定
+  - kind: workflow / skill / prompt / knowledge
+  - slug または path
+  - git revision または content hash
+- Iteration 0: description / body consistency check
+- scenario set の作成
+  - median 1 件
+  - edge 1〜2 件
+  - requirements checklist 3〜7 項目
+  - `[critical]` 項目を最低 1 つ含める
+- evaluator Pod は毎回新規に spawn し、同じ evaluator を再利用しない
+- evaluator Pod は実装者ではなく評価者として動く
+- evaluator report は以下の構造にする
+  - Deliverable
+  - Requirement achievement
+  - Trace: Understanding / Planning / Execution / Formatting
+  - Unclear points: Issue / Cause / General Fix Rule
+  - Discretionary fill-ins
+  - Retries
+- 1 iteration 1 theme の最小修正を原則とする
+- Workflow / prompt の実ファイル書き換えは人間承認後に限る
+- Workflow 自動生成 / 自動更新は禁止し、必要な改善は offer として人間に戻す
+
+### 評価 event schema
+
+評価結果を、将来の system metrics / memory consolidation に流せる構造化 event として定義する。
+
+最低限の field:
+
+```text
+eval_run_id
+target_kind
+target_slug_or_path
+target_revision_or_hash
+scenario_id
+scenario_kind: median | edge | holdout
+evaluator_pod_name
+evaluator_session_id
+started_at / ended_at
+success: bool
+accuracy: number
+critical_passed: bool
+tool_call_count
+tool_call_count_by_tool
+input_tokens
+output_tokens
+cache_read_tokens / cache_write_tokens if available
+scope_error_count
+file_search_count
+escalation_count
+unclear_points[]
+  phase: Understanding | Planning | Execution | Formatting
+  issue
+  cause
+  general_fix_rule
+discretionary_fill_ins[]
+retries
+```
+
+初期実装で全 field が機械取得できない場合は、取得可能なものと evaluator self-report 由来のものを分ける。未取得 field は空にしてよいが、schema 上は将来埋められる形にする。
+
+### Metrics / memory consolidation との接続
+
+本チケットでは、評価 event を memory / metrics pipeline に接続する設計を明文化し、可能な最小実装を入れる。
+
+接続方針:
+
+- evaluator self-report は Phase 1 の活動抽出対象になる
+- repeated `General Fix Rule` は Phase 2 が recurring failure pattern として統合できる
+- recurring pattern は即 Knowledge 化せず、使用頻度メトリクス gate を通す
+- Workflow 改善は `.insomnia/workflow/*.md` へ自動書き込みせず、Notification / report / ticket などの offer に留める
+- `model_invokation` ON 判断では、明示 invoke 頻度と常駐コストに加えて、eval success rate / unclear point count / description-body consistency を判断材料にする
+
+### 評価指標の解釈
+
+Claude Code 版の `tool_uses` を、insomnia では tool 種別ごとの偏りとして解釈する。
+
+例:
+
+- Glob / Grep が突出: references / 探索方針が prompt 内で弱い
+- Read が突出: required context の入口が弱い
+- scope error が出る: permission / worktree / escalation 境界が弱い
+- SpawnPod / SendToPod が多い: orchestration の粒度や子 Pod 指示が曖昧
+- ticket / git write に向かう: escalation criteria が弱い
+
+定量指標は補助であり、Unclear points / Discretionary fill-ins / General Fix Rule を主指標とする。
+
+### Failure pattern ledger
+
+手書き台帳だけにせず、eval event から抽出可能な failure pattern として扱う。
+
+- `General Fix Rule` を class-level pattern として正規化する
+- 同じ pattern が複数 scenario / 複数 iteration / 複数 target で再発した場合、Phase 2 が decision / knowledge candidate / workflow improvement offer に統合できる
+- 同じ pattern が 3 回以上再発した場合、局所 patch ではなく target prompt の構造変更を提案する
+
+## 範囲外
+
+- Workflow の自動書き換え
+- Knowledge の即時自動作成
+- `model_invokation` ON/OFF の完全自動切替
+- evaluator Pod の永続ジョブキュー化
+- prompt DSL 化
+- LLM judge による主観的 A/B 比較の採用
+- すべての metrics field の初期実装での完全自動取得
+
+## 完了条件
+
+- `.insomnia/workflow/empirical-prompt-tuning.md` が追加され、insomnia の evaluator Pod / metrics / memory consolidation 前提で記述されている
+- Workflow は Iteration 0、scenario checklist、Trace、Issue / Cause / General Fix Rule、1 iteration 1 theme、人間承認 gate を明示している
+- 評価 event schema が docs または ticket 内で定義されている
+- eval event を memory consolidation / usage metrics / Workflow improvement offer / `model_invokation` 判断へ接続する方針が文書化されている
+- 既存の Workflow 自動生成禁止・history に commit されない context input 禁止・memory consolidation 方針に反していない
+- `/auto-maintain` または `/worktree-workflow` のどちらか 1 件を対象に、構造審査または小規模 evaluator Pod 試走を行い、結果を記録している
+
+## 参照
+
+- `docs/external/zenn-mizchi-empirical-prompt-tuning.md`
+- `/home/hare/ghq/github.com/mizchi/skills/empirical-prompt-tuning/SKILL.md`（外部参照。取り込み時は必要最小限に一般化する）
+- `docs/plan/workflow.md`
+- `docs/plan/memory.md`
+- `tickets/memory-usage-metrics.md`
+- `tickets/auto-maintain-workflow.md`