docs(tickets): reportの運用・Workflowのディレクトリ位置修正

AGENTS.md

@@ -51,3 +51,7 @@ TODO.mdのリンクは完了後に切れるが、そのリンクを元にgitで
 `.review.md` にはレビューの指摘事項と判断結果を記載する。
 レビューはdiffの確認だけでなく、チケットはどのような前提・要件であり、それが達成されたかの確認まで含めて行う。
 常に、提出された実装で良いのか、コードベースを歪めていないか、不必要な実装ではないかを確認すること。
+
+---
+
+insomniaでinsomniaを開発している際、AI自身のフィードバックを元に改善を回すために `docs/report/`ディレクトリに感じた障壁や改善案等を書き残す形にした。 明確に力不足な点/ツールの問題があった場合や、ユーザーからの指示があった際に作ること。

CLAUDE.md

@@ -51,3 +51,7 @@ TODO.mdのリンクは完了後に切れるが、そのリンクを元にgitで
 `.review.md` にはレビューの指摘事項と判断結果を記載する。
 レビューはdiffの確認だけでなく、チケットはどのような前提・要件であり、それが達成されたかの確認まで含めて行う。
 常に、提出された実装で良いのか、コードベースを歪めていないか、不必要な実装ではないかを確認すること。
+
+---
+
+insomniaでinsomniaを開発している際、AI自身のフィードバックを元に改善を回すために `docs/report/`ディレクトリに感じた障壁や改善案等を書き残す形にした。 明確に力不足な点/ツールの問題があった場合や、ユーザーからの指示があった際に作ること。

TODO.md

@@ -1,5 +1,7 @@
 - Workflow / Skills
   - 内部 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 の物理配置を `.insomnia/workflow` に分離 → [tickets/workflow-directory-layout.md](tickets/workflow-directory-layout.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)

docs/report/2026-05-05-file-ticket-scope.md

@@ -0,0 +1,94 @@
+# ファイルベース Ticket と Scope 委譲の相性
+
+日付: 2026-05-05
+
+## 要旨
+
+insomnia を使って insomnia を開発する運用では、ファイルベースの ticket / review lifecycle と、Pod の write scope 委譲が衝突しやすい。特に「実装 Pod が worktree を書く」直後に「親 Pod または reviewer が同じ worktree の ticket review artifact を書く」流れでは、同じファイルツリーに複数主体が順番に書きたい一方、Scope は write 権限を排他的に委譲するため、自然なレビュー操作が詰まる。
+
+## 今回起きたこと
+
+`tickets/permission-extension-point.md` の実装で、worktree workflow に従って `.worktree/permission-extension-point` を作り、実装用 Pod を Spawn した。
+
+実装 Pod には worktree への write scope を渡したため、親 Pod から見るとその worktree は委譲中の領域になった。その後、同じ worktree に対して ticket review workflow を行い、`tickets/permission-extension-point.review.md` の作成と `tickets/permission-extension-point.md` の Review section 追記をしようとしたところ、親 Pod の `Write` tool は次のように拒否された。
+
+```text
+path is read-only in this scope: <repo>/.worktree/permission-extension-point/tickets/permission-extension-point.review.md
+```
+
+実装 Pod を `StopPod` して scope を回収した後に review artifact を書く必要があった。
+
+また、最初に SpawnPod した際、write scope を worktree のみに絞ると spawned Pod の cwd である `<repo>` が readable scope 外になり、起動に失敗した。実装用 Pod には worktree write に加えて親 project root の read scope も渡す必要があった。
+
+## 障壁
+
+### 1. Ticket lifecycle は同じファイルツリーへの複数主体の逐次書き込みを要求する
+
+このプロジェクトの ticket lifecycle は、実装後に以下のようなファイル操作を行う。
+
+- `tickets/<ticket>.md` を読む
+- `tickets/<ticket>.review.md` を作る
+- `tickets/<ticket>.md` に Review section を追記する
+- 完了時には ticket / review file を削除する
+
+つまり ticket は単なる入力仕様ではなく、実装・レビュー・完了状態を表す共有ファイルでもある。実装者 Pod、親 Pod、reviewer Pod のいずれも、同じ worktree 内の `tickets/` を書きたくなる。
+
+### 2. Scope は write ownership を安全側に排他的にする
+
+SpawnPod の scope 委譲は、子 Pod に渡した write 領域を親から切り離す安全モデルになっている。このモデル自体は正しい。子が作業中の worktree を親が同時に書けないため、意図しない競合や横取りを防げる。
+
+ただし file-based ticket workflow では、レビューを書く段階でも同じ worktree を書く必要がある。実装 Pod がまだ alive で write scope を保持していると、親が review artifact を書けない。reviewer Pod を別に Spawn する場合も、同じ write scope を同時に渡せない。
+
+### 3. Review のために実装 Pod を止めると対話継続性が落ちる
+
+今回の回避策は実装 Pod を停止して scope を回収することだった。これは review artifact を書くには有効だが、実装者 Pod に追加質問したり、レビュー指摘をそのまま反映させたりする流れとは相性が悪い。
+
+本来欲しい流れは以下に近い。
+
+1. 実装 Pod が worktree に実装する
+2. reviewer が同じ diff を見て review artifact を書く
+3. 実装 Pod に修正を依頼する
+4. reviewer が再レビューする
+
+現在の排他的 write scope では、2 と 3 の間で scope owner を何度も移す必要がある。
+
+## 影響
+
+- Ticket review が「実装 Pod を停止してからでないと書けない」運用になりやすい
+- 実装者 Pod と reviewer Pod の並行・往復がしにくい
+- file-based ticket が作業対象 worktree 内にあるため、コード変更と管理メタデータ変更が同じ scope boundary に巻き込まれる
+- 親 Pod が orchestration をしているのに、review artifact のような管理操作まで child scope に阻まれる
+
+## 暫定運用
+
+当面は次の運用が現実的。
+
+- 実装 Pod に worktree write scope を渡したら、レビュー artifact を親が書く前に実装 Pod を停止して scope を回収する
+- 実装 Pod に追加修正を依頼したい場合は、レビュー作成後に再 Spawn する
+- Spawn 時は worktree write scope だけでなく、Pod 起動 cwd や参照元 ticket を読める read scope も明示する
+
+この運用は安全だが、レビュー往復の体験は重い。
+
+## 改善案
+
+### A. Review artifact の書き込み場所を親側に逃がす
+
+review を worktree 内の `tickets/*.review.md` ではなく、親 session 側の report / review storage に書く案。Scope 衝突は避けられるが、現行の ticket lifecycle と git 上の履歴管理から外れるため、採用するなら ticket lifecycle 自体の再設計が必要。
+
+### B. Scope に「管理ファイルの親書き込み例外」を作る
+
+親 Pod が delegated worktree のうち `tickets/*.review.md` や `tickets/*.md` の Review section だけを書ける例外を作る案。実装はできるが、Scope の安全モデルに穴を開けるため慎重に扱う必要がある。パターンベース permission と似た問題になり、どのファイルを管理操作とみなすかの境界も曖昧になる。
+
+### C. Scope owner の handoff を明示操作にする
+
+`StopPod` より軽い「write scope を一時返却する / 再取得する」操作を protocol に作る案。実装 Pod の会話状態を保ったまま、reviewer / parent が短時間だけ同じ worktree に書ける。ただし停止していない Pod が後で再開した時の整合性、同時実行防止、失効した tool call の扱いを設計する必要がある。
+
+### D. Reviewer を同じ Pod に依頼する
+
+実装 Pod 自身に review artifact まで書かせる案。Scope 衝突は起きないが、実装者と reviewer の分離が弱くなる。ticket-reviewer の目的である独立レビューには向かない。
+
+## 現時点の判断
+
+短期的には「実装完了 → 実装 Pod 停止 → 親または reviewer が review artifact 作成」を標準手順として明記するのが良い。中期的には、Scope owner の handoff か、ticket/review artifact の置き場所を再検討する必要がある。
+
+今回の障壁はバグというより、insomnia の安全な scope 委譲モデルと、ファイルを状態機械として使う ticket lifecycle の設計上の摩擦である。

tickets/auto-maintain-workflow.md

@@ -0,0 +1,69 @@
+# 半自動開発運用 Workflow
+
+## 背景
+
+insomnia では insomnia 自身の開発を、ユーザーがタスクを投げ、設計相談をし、実装 Pod / reviewer Pod に分担させる形で進めている。既に Workflow / Skills、SpawnPod、Pod 間通信、scope 委譲、ticket / review lifecycle は揃っており、局所的な実装判断は AI に移譲できる余地が大きい。
+
+一方で、完全な unattended 自動開発にするには、永続ジョブキュー、git 書き込み権限、設計判断のエスカレーション基準など未整理の領域がある。初期段階では、常駐 scheduler ではなく、ユーザーが明示的に起動する「maintainer workflow」として、TODO / tickets を俯瞰し、実装・レビュー・修正依頼を orchestration し、設計境界や完了判断だけを人間に戻す運用を整備する。
+
+## 要件
+
+### Workflow の役割
+
+`/auto-maintain` 相当の Workflow を用意し、親 Pod が以下を実行できるようにする。
+
+- `TODO.md` と `tickets/` から着手候補を把握する
+- 既存方針・既存 ticket から実装方針が十分に導ける作業を選ぶ
+- 要件が曖昧、または設計判断が必要な場合は実装前に人間へ質問する
+- 実装 Pod を spawn し、適切な read / write scope を委譲する
+- 実装 Pod の完了報告と diff / build / test 結果を確認する
+- 必要に応じて reviewer Pod、または親 Pod 自身でレビューする
+- レビュー指摘があれば修正を依頼する
+- 最終的に「完了候補」として人間に報告する
+
+### エスカレーション基準
+
+Workflow は、少なくとも以下の場合に作業を止めて人間へ確認する。
+
+- ticket の要件から複数の設計方針が自然に導け、選択が将来の構造に影響する
+- scope / permission / history 永続化 / prompt context 加工原則など、システムの安全モデルに触れる
+- 新しい ticket の追加、既存 ticket の大幅な要件変更、ticket 完了削除を行う
+- git の commit / merge / push など書き込み操作が必要になる
+- テスト不能、再現不能、または作業範囲外の不具合に遭遇する
+
+### Pod orchestration 規約
+
+- 実装 Pod と reviewer Pod は原則分ける。ただし scope 衝突や作業粒度により、親 Pod がレビューしてもよい。
+- 実装 Pod に worktree write scope を渡す場合、review artifact を親または reviewer が書く前に実装 Pod を停止して scope を回収する。
+- spawn 時は、作業対象 worktree の write scope だけでなく、必要な参照元 ticket / project root の read scope も明示する。
+- 子 Pod の出力は `ReadPodOutput` で確認し、必要なら `SendToPod` で追加依頼する。
+- orphan 化した Pod や不要になった Pod は `StopPod` する。
+
+### 成果物
+
+- Workflow 本文、またはそれに準じる運用手順が workspace から呼び出せる形で追加される
+- Workflow が resident workflow として広告可能かどうかを判断し、必要なら `model_invokation` 設定を含める
+- 実際の insomnia 開発 ticket を 1 件以上試走し、実装 Pod / review / 人間確認の境界が機能することを確認する
+- 試走で見つかった不足（永続ジョブキュー、scope handoff、review artifact の置き場所等）は、本チケット内で解決せず、必要なら別 ticket として切り出す
+
+## 範囲外
+
+- 常駐 scheduler / daemon による unattended 実行
+- git commit / merge / push の自動化
+- ticket 完了削除の自動化
+- Workflow の状態機械化、永続ジョブキュー化、トランザクション管理
+- scope owner handoff など、Pod 権限モデル自体の変更
+
+## 完了条件
+
+- `/auto-maintain` 相当の半自動開発運用 Workflow が利用可能になっている
+- Workflow は TODO / tickets から作業を選び、実装 Pod / reviewer / 人間確認を使い分ける手順を明示している
+- エスカレーション基準により、設計判断・git 書き込み・ticket 完了判断が人間に戻る
+- 少なくとも 1 件の小さな実開発作業で試走し、結果と不足点が記録されている
+- 既存の Workflow / Skill / memory の設計方針、特に Workflow 自動生成禁止と history に commit されない context input 禁止に反していない
+
+## 参照
+
+- `docs/plan/workflow.md`
+- `docs/report/2026-05-05-file-ticket-scope.md`
+- `tickets/internal-worker-workflow.md`

tickets/workflow-directory-layout.md

@@ -0,0 +1,128 @@
+# Workflow の物理配置を `.insomnia/workflow` に分離する
+
+## 背景
+
+現行の Workflow は `<workspace>/.insomnia/memory/workflow/<slug>.md` に配置される。これは実装上 memory subsystem の loader / linter に載せていた名残だが、概念上は不自然になっている。
+
+Workflow は session-derived な記憶ではなく、人間が管理する手順・操作ポリシーである。一方で `.insomnia/memory/summary.md`、`decisions/`、`requests/`、`_staging/` は自動抽出・統合される memory state であり、ignore や書き込み禁止の扱いも異なる。
+
+この混在により、`.insomnia/.gitignore` で `memory` を ignore すると project-authored Workflow まで Git 管理から外れる。また、memory write tool が Workflow 書き込みを禁止するなど、「memory 配下にあるが memory ではない」ものとして扱う歪みが出ている。
+
+Knowledge は既に `.insomnia/knowledge/<slug>.md` として `memory/` の外にある。Workflow も同様に `.insomnia/workflow/<slug>.md` を canonical path とし、memory state から分離する。
+
+## 要件
+
+### canonical path の変更
+
+Workflow の標準配置を以下に変更する。
+
+```text
+<workspace>/.insomnia/workflow/<slug>.md
+```
+
+旧配置は以下。
+
+```text
+<workspace>/.insomnia/memory/workflow/<slug>.md
+```
+
+新規作成・ドキュメント・補完・resolver の説明は新配置を使う。
+
+### 互換読み取り
+
+移行期間のため、loader は当面旧配置も読む。
+
+- 新配置 `.insomnia/workflow/<slug>.md` を優先する
+- 旧配置 `.insomnia/memory/workflow/<slug>.md` も fallback として読む
+- 同じ slug が両方にある場合は新配置を採用する
+- 旧配置を読んだ場合、可能なら warning / notification / log のいずれかで migration hint を出す
+
+旧配置の完全廃止は本チケットでは行わない。廃止が必要になったら別 ticket とする。
+
+### linter / registry / completion
+
+- Workflow linter は新配置を検査できる
+- `requires` の Knowledge 参照検査は従来通り維持する
+- `WorkflowRegistry` は source path として新旧どちらも保持できる
+- `/<slug>` completion / invocation は新配置・旧配置の双方から読める
+- resident workflow (`model_invokation: true`) の広告も新配置を対象にする
+
+### memory state との分離
+
+`.insomnia/memory/` は generated / session-derived state として扱い、Workflow は含めない。
+
+推奨される layout:
+
+```text
+.insomnia/
+  manifest.toml
+  workflow/
+    auto-maintain.md
+    worktree-workflow.md
+  knowledge/
+    <slug>.md
+  memory/
+    summary.md
+    decisions/
+    requests/
+    _staging/
+```
+
+`.insomnia/.gitignore` は `memory` 丸ごと ignore ではなく、generated memory state のみを ignore する形にする。
+
+例:
+
+```gitignore
+/memory/_staging/
+/memory/summary.md
+/memory/decisions/
+/memory/requests/
+```
+
+### 既存ファイルの移行
+
+workspace に既存 Workflow がある場合、新配置へ移す。
+
+対象例:
+
+```text
+.insomnia/memory/workflow/auto-maintain.md
+.insomnia/memory/workflow/worktree-workflow.md
+```
+
+移行後:
+
+```text
+.insomnia/workflow/auto-maintain.md
+.insomnia/workflow/worktree-workflow.md
+```
+
+移行は Git 管理対象として扱えるようにする。
+
+## 範囲外
+
+- Workflow の自動生成ポリシー変更
+- Workflow frontmatter schema の大幅変更
+- Workflow DSL 化
+- 旧配置の即時廃止
+- memory tool で Workflow を書けるようにする変更
+- 内部 Worker Workflow 化そのもの（`tickets/internal-worker-workflow.md` の対象）
+
+## 完了条件
+
+- Workflow の canonical path が `.insomnia/workflow/<slug>.md` として実装・文書化されている
+- 既存の `.insomnia/memory/workflow/<slug>.md` も互換読み取りできる
+- 新旧両方に同じ slug がある場合、新配置が優先される
+- Workflow linter / loader / completion / invocation のテストが新配置をカバーしている
+- `.insomnia/.gitignore` が generated memory state のみを ignore し、`.insomnia/workflow/*.md` を Git 管理できる
+- この workspace の既存 Workflow が `.insomnia/workflow/` に移されている
+- `docs/plan/workflow.md` や関連コメントが新配置に更新されている
+
+## 参照
+
+- `docs/plan/workflow.md`
+- `crates/memory/src/workspace.rs`
+- `crates/memory/src/workflow.rs`
+- `crates/pod/src/workflow/mod.rs`
+- `tickets/auto-maintain-workflow.md`
+- `tickets/internal-worker-workflow.md`