docs: memory effectiveness plan

TODO.md

@@ -27,6 +27,7 @@
 - Prune: 保護境界を turn 数から末尾 token budget に置き換え → [tickets/prune-token-budget.md](tickets/prune-token-budget.md)
 - メモリ機構
   - 使用頻度メトリクス + Knowledge 化候補レポート → [tickets/memory-usage-metrics.md](tickets/memory-usage-metrics.md)
+  - Prompt から project-specific ticket shadow policy を外す → [tickets/memory-prompts-remove-ticket-policy.md](tickets/memory-prompts-remove-ticket-policy.md)
 - セッション内 Task ツールの注意機構（無アクティビティで `<system-reminder>` ナッジ） → [tickets/session-todo-reminder.md](tickets/session-todo-reminder.md)
 - ワークスペースのメモリーをLintするヘッドレスCLI
 - system-reminder 注入機構の汎用化（2件目の利用者が出た時に検討。タグ形式 `<system-reminder>...</system-reminder>` の規約は session-todo-reminder で先行確立。注入された Item は worker.history に append する方針）

docs/plan/memory-effectiveness.md

@@ -0,0 +1,199 @@
+# Memory effectiveness improvement plan
+
+## Context
+
+`docs/plan/memory.md` で定義した永続化・検索・Phase 1 / Phase 2 の基盤は実装済みだが、現状の workspace memory を見る限り、実用上の効果はまだ弱い。
+
+現在の主要な症状:
+
+- `knowledge/*` が空で、通常 Pod が自発的に参照できる discovery 面がない
+- `memory/summary.md` は「Always-on サマリ」と設計されているが、通常 Pod の system prompt へ常駐注入されていない
+- Phase 2 は `KnowledgeCandidateReport::empty()` を受け取り、prompt 上も「候補レポートが空なら新規 Knowledge を作るな」としているため、Knowledge の cold-start が起きない
+- `decisions/*` と `requests/*` は記録としては残るが、description / resident injection を持たず、後続 turn で自然に読まれにくい
+- bundled prompt に INSOMNIA 開発固有の ticket / TODO 運用を前提にした shadow 禁止が入り、一般ユーザー workspace の管理文脈を過剰に落とす可能性がある
+
+この状態で usage metrics を先に実装しても、「使われていない / 発見されない memory」を測るだけになり、Knowledge 化候補や保護閾値の信号が十分に育たない。先に memory が読まれ、Knowledge が最低限生まれる経路を作る。
+
+## Proposal
+
+Usage metrics の前に、memory effectiveness の最小改善として以下を行う。
+
+1. `summary.md` を通常 Pod の resident context に入れる
+2. Knowledge の cold-start gate を緩める
+3. bundled memory prompts を project-management 手法に依存しない形へ汎用化する
+4. 明示参照 (`#<slug>`) の実用経路を整える
+5. 既存 decisions / requests から Knowledge へ昇格できる整理経路を用意する
+
+この順序により、metrics 実装時には「実際に読まれる対象」と「昇格候補になりうる Knowledge / memory record」が存在する状態になる。
+
+## 1. Summary resident injection
+
+### Problem
+
+`docs/plan/memory.md` では `memory/summary.md` を Always-on サマリとしている。しかし実装上、通常 Pod の system prompt に載るのは `model_invokation: true` の Knowledge description / Workflow description であり、summary は `MemoryRead(kind=summary)` しない限り読まれない。
+
+これは設計と実装のズレであり、memory の中心 record が通常 turn に効かない原因になっている。
+
+### Direction
+
+通常 Pod の system prompt trailing section に `summary.md` の本文または圧縮表示を載せる。
+
+- `[memory]` が有効で、`memory/summary.md` が存在する場合だけ注入する
+- Phase 2 / internal disposable Worker には注入しない
+- 既存の `Resident knowledge` とは別 section にする
+- summary の frontmatter は除外し、本文のみを載せる
+- summary 本文の linter 上限は 20,000 chars だが、resident 注入では別途 soft cap を持つか、当初は summary 自体を 1-5k tokens に保つ prompt 方針に依存する
+
+### Expected effect
+
+通常 Pod は少なくとも現在の project memory の要約を毎 turn 見られる。Knowledge が空でも memory subsystem の効果がゼロになりにくい。
+
+## 2. Knowledge cold-start gate
+
+### Problem
+
+現行 Phase 2 は `KnowledgeCandidateReport::empty()` を渡し、prompt も空レポート時の新規 Knowledge 作成を禁止している。これは usage metrics 完成後の gate としては妥当だが、cold-start では永久に Knowledge が生まれない。
+
+### Direction
+
+Knowledge 作成 gate と resident injection gate を分離する。
+
+- 新規 Knowledge 作成:
+  - Phase 2 が high-confidence に再利用価値を判断できる場合は許可する
+  - default は `model_invokation: false`
+  - `description` は「本文要約」ではなく「何の知識で、いつ読むべきか」を書かせる
+- `model_invokation: true` への昇格:
+  - usage metrics / 人間判断 / 将来の評価指標に基づく
+  - cold-start 自動作成時には原則 ON にしない
+- GC / drop 保護:
+  - 引き続き usage metrics の明示 invoke frequency を使う
+
+つまり、metrics が無い間も Knowledge は蓄積できるが、system prompt 常駐コストを増やす判断は保守的にする。
+
+### Expected effect
+
+Knowledge が空のまま固定される問題を避ける。metrics 実装前でも、検索可能な reusable knowledge が増える。
+
+## 3. Prompt generalization
+
+### Problem
+
+bundled memory prompts は、INSOMNIA 自身の ticket / TODO / worktree 運用を一般ユーザーへ押し付けている。ticket はこのプロジェクトの管理手法であり、ユーザー workspace の正本や作業管理の形は project ごとに異なる。
+
+### Direction
+
+Default prompt では特定の管理手法名を禁止対象として列挙しない。
+
+残すべき一般原則:
+
+- 既存の authoritative record を逐語的に mirror しない
+- ファイル操作ログや VCS 履歴そのものを memory に再保存しない
+- ただし、将来の作業判断に効く project-management 上の制約・優先順位理由・プロセス決定・ recurring pattern は抽象化して保存してよい
+- INSOMNIA 自身の ticket shadow 回避は bundled default ではなく workspace / user prompt override で表現する
+
+### Expected effect
+
+Memory extraction / consolidation が、ユーザー workspace の管理文脈を過剰に捨てなくなる。
+
+## 4. Explicit slug invocation path
+
+### Problem
+
+設計上は `#<slug>` で Knowledge を参照するが、現状は LLM が `KnowledgeQuery` / `MemoryRead` を自発的に呼ぶことに寄っている。ユーザーが明示的に `#slug` を書いても、専用の展開経路が弱い。
+
+### Direction
+
+段階的に実装する。
+
+1. user input から `#<slug>` を検出する
+2. exact slug で `knowledge/<slug>.md` を解決する
+3. 解決できた本文を user turn の context として history に append してから LLM に渡す
+4. 解決失敗は system-reminder / synthetic note ではなく、history に残る通常の input artifact として扱う
+
+この実装では、プロジェクト指示の「history に残らない context input 禁止」に従い、展開結果を必ず `worker.history` に commit する。context だけへの差し込みはしない。
+
+### Expected effect
+
+ユーザーが必要な Knowledge を明示参照でき、metrics 実装後の明示 invoke 計測点にもなる。
+
+## 5. Existing record promotion
+
+### Problem
+
+現状の memory には decisions と requests があるが、いくつかは reusable knowledge に近い。これらが decisions のままだと resident discovery や KnowledgeQuery の対象になりにくい。
+
+### Direction
+
+Phase 2 の tidy / consolidation に、既存 `decisions/*` / `requests/*` を Knowledge へ昇格する経路を追加する。
+
+- 同一内容を copy するのではなく、Knowledge として再利用可能な抽象に rewrite する
+- 元 decision は必要なら残す。Knowledge 側には `last_sources` として直近 source を持つ
+- 新規 Knowledge 作成は §2 の cold-start gate に従う
+- decision の「判断履歴」と Knowledge の「再利用可能な運用知識」を混同しない
+
+### Expected effect
+
+既存 memory の価値を引き出し、metrics 前に検索対象を増やせる。
+
+## Ordering
+
+推奨順序:
+
+1. Prompt generalization
+   - 既に `tickets/memory-prompts-remove-ticket-policy.md` として起票済み
+   - prompt が不要に情報を捨てる状態を先に止める
+2. Summary resident injection
+   - 既存 `summary.md` が即座に通常 Pod へ効く
+3. Knowledge cold-start gate
+   - Phase 2 が Knowledge を生めるようにする
+4. Existing record promotion
+   - 既存 decisions / requests から Knowledge を立ち上げる
+5. Explicit slug invocation path
+   - Knowledge が存在する状態で明示参照経路を整える
+6. Usage metrics
+   - 明示 invoke / resident cost / protection threshold / Knowledge candidate report を実装する
+
+## Interaction with usage metrics
+
+Usage metrics は不要ではない。役割を以下に限定すると妥当性が高い。
+
+- `model_invokation: true` へ昇格する判断材料
+- resident injection cost と使われ率の観測
+- tidy / GC での drop / 大幅圧縮保護
+- Knowledge candidate report の補助信号
+
+一方、metrics を Knowledge 作成そのものの唯一 gate にすると cold-start が壊れる。Knowledge 作成は high-confidence agent judgement、resident 化と保護は metrics、という分担にする。
+
+## Risks / open questions
+
+### Summary injection cost
+
+`summary.md` を常駐させると system prompt budget を消費する。summary が肥大化した場合に備え、以下のどちらかを選ぶ必要がある。
+
+- linter / Phase 2 prompt で summary を 1-5k tokens に保つ運用を先行する
+- resident injection 側に hard truncation / warning を入れる
+
+初期は前者でよいが、truncation されるなら LLM に明示した方がよい。
+
+### Knowledge noise
+
+cold-start gate を緩めると Knowledge が増えすぎる可能性がある。対策として、新規作成時の `model_invokation: false` default、update 優先、description 品質指示、tidy phase の noisy 分類を使う。
+
+### Prompt override boundary
+
+INSOMNIA 自身の ticket shadow 回避を完全に消すと、この repository の memory は作業ログ寄りに戻る可能性がある。これは bundled default ではなく workspace prompt override で解くべきで、default prompt の責務ではない。
+
+### `#<slug>` history representation
+
+明示参照展開をどの Item / Segment として history に残すかは別途詰める必要がある。原則は「LLM が見たものは history に残す」。context-only injection は使わない。
+
+## Validation criteria
+
+この計画が妥当かは、以下で判断する。
+
+- 新規 workspace で Knowledge が 0 件のまま固定されない
+- 通常 Pod が `summary.md` の内容を tool call なしで参照できる
+- bundled prompts が ticket / TODO / worktree 等の特定管理手法を前提にしない
+- Knowledge の `description` が discovery 面として機能する
+- `model_invokation: true` は uncontrolled に増えない
+- usage metrics 実装時に、計測対象となる明示参照 / resident cost / Knowledge records が存在する

tickets/memory-prompts-remove-ticket-policy.md

@@ -0,0 +1,46 @@
+# Memory prompts: project-specific ticket shadow policy を外す
+
+## 背景
+
+現在の bundled memory prompts は、INSOMNIA 自身の開発運用に由来する「ticket / TODO / worktree / commit は git が正本なので memory に記録しない」という規則を、一般ユーザーの workspace にも適用している。
+
+特に `resources/prompts/internal/memory_extract_system.md` と `resources/prompts/internal/memory_consolidation_system.md` には、ticket file 作成・編集、TODO 更新、ticket 名、worker Pod spawn for ticket などを memory から落とす指示が明示されている。しかし ticket はこのプロジェクト固有の管理手法であり、insomnia の利用者に押し付けるほど汎用的・成熟した概念ではない。
+
+このため、memory がユーザー workspace の実際の管理対象や作業文脈を過剰に捨てる可能性がある。デフォルト prompt は、INSOMNIA リポジトリ固有の ticket 運用ではなく、より一般的な「既存の正本をそのまま重複保存しない」程度の方針に留めるべきである。
+
+## 要件
+
+- bundled memory prompts から、INSOMNIA プロジェクト固有の ticket / TODO 運用を前提にした禁止文言を削除する
+  - `ticket-file creation / edit`
+  - `TODO updates`
+  - `ticket Y was created`
+  - `ticket file names`
+  - `worker Pod was spawned for Z` が ticket 前提で語られている箇所
+- `git is authoritative` の扱いを、一般ユーザーに押し付けない表現へ弱める
+  - git / VCS に残る単なるファイル操作ログを memory が逐語的に shadow しない、という原則は残してよい
+  - ただし project management 上の出来事や管理ファイルの内容が、将来の作業判断に効くなら memory へ抽象化して残せる余地を残す
+- Phase 1 extract prompt と Phase 2 consolidation prompt の両方を整合させる
+- 必要なら `docs/plan/memory-prompts.md` または `docs/plan/memory.md` に、default prompt は特定プロジェクトの ticket 運用を前提にしないことを明記する
+- INSOMNIA 自身の運用で ticket shadow を避けたい場合は、bundled default ではなく workspace/user prompt override 側で表現できる状態にする
+
+## 範囲外
+
+- memory の file format / linter / Phase 1 / Phase 2 実行機構の変更
+- 使用頻度メトリクスや Knowledge 化 gate の実装
+- INSOMNIA プロジェクト自身の ticket 運用の再設計
+- prompt override 機構そのものの変更
+
+## 完了条件
+
+- `resources/prompts/internal/memory_extract_system.md` から ticket / TODO 固有の shadow 禁止が消えている
+- `resources/prompts/internal/memory_consolidation_system.md` から ticket / TODO 固有の shadow 禁止が消えている
+- 代替文言が、特定管理手法ではなく「既存の正本と重複しない」「将来の判断に効く抽象だけ残す」という一般原則になっている
+- default prompt が、ユーザー workspace の project management 手法を固定しない
+- 既存テスト / prompt catalog 検査が通る
+
+## 参照
+
+- `resources/prompts/internal/memory_extract_system.md`
+- `resources/prompts/internal/memory_consolidation_system.md`
+- `docs/plan/memory-prompts.md`
+- `docs/plan/memory.md`