From 5ec24707f488b5bc85731c846ad7ef2037363600 Mon Sep 17 00:00:00 2001 From: Hare Date: Thu, 7 May 2026 23:34:00 +0900 Subject: [PATCH] =?UTF-8?q?docs(tickets):=20report=E3=81=AE=E9=81=8B?= =?UTF-8?q?=E7=94=A8=E3=83=BBWorkflow=E3=81=AE=E3=83=87=E3=82=A3=E3=83=AC?= =?UTF-8?q?=E3=82=AF=E3=83=88=E3=83=AA=E4=BD=8D=E7=BD=AE=E4=BF=AE=E6=AD=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 4 + TODO.md | 2 + docs/report/2026-05-05-file-ticket-scope.md | 94 ++++++++++++++ tickets/auto-maintain-workflow.md | 69 +++++++++++ tickets/workflow-directory-layout.md | 128 ++++++++++++++++++++ 5 files changed, 297 insertions(+) create mode 100644 docs/report/2026-05-05-file-ticket-scope.md create mode 100644 tickets/auto-maintain-workflow.md create mode 100644 tickets/workflow-directory-layout.md diff --git a/AGENTS.md b/AGENTS.md index cc94f18d..d909e385 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,3 +51,7 @@ TODO.mdのリンクは完了後に切れるが、そのリンクを元にgitで `.review.md` にはレビューの指摘事項と判断結果を記載する。 レビューはdiffの確認だけでなく、チケットはどのような前提・要件であり、それが達成されたかの確認まで含めて行う。 常に、提出された実装で良いのか、コードベースを歪めていないか、不必要な実装ではないかを確認すること。 + +--- + +insomniaでinsomniaを開発している際、AI自身のフィードバックを元に改善を回すために `docs/report/`ディレクトリに感じた障壁や改善案等を書き残す形にした。 明確に力不足な点/ツールの問題があった場合や、ユーザーからの指示があった際に作ること。 diff --git a/TODO.md b/TODO.md index 1a68838d..cedb63ed 100644 --- a/TODO.md +++ b/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) diff --git a/docs/report/2026-05-05-file-ticket-scope.md b/docs/report/2026-05-05-file-ticket-scope.md new file mode 100644 index 00000000..8fd1cda4 --- /dev/null +++ b/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: /home/hare/Projects/insomnia/.worktree/permission-extension-point/tickets/permission-extension-point.review.md +``` + +実装 Pod を `StopPod` して scope を回収した後に review artifact を書く必要があった。 + +また、最初に SpawnPod した際、write scope を worktree のみに絞ると spawned Pod の cwd である `/home/hare/Projects/insomnia` が readable scope 外になり、起動に失敗した。実装用 Pod には worktree write に加えて親 project root の read scope も渡す必要があった。 + +## 障壁 + +### 1. Ticket lifecycle は同じファイルツリーへの複数主体の逐次書き込みを要求する + +このプロジェクトの ticket lifecycle は、実装後に以下のようなファイル操作を行う。 + +- `tickets/.md` を読む +- `tickets/.review.md` を作る +- `tickets/.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 の設計上の摩擦である。 diff --git a/tickets/auto-maintain-workflow.md b/tickets/auto-maintain-workflow.md new file mode 100644 index 00000000..0b4d4a24 --- /dev/null +++ b/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` diff --git a/tickets/workflow-directory-layout.md b/tickets/workflow-directory-layout.md new file mode 100644 index 00000000..a8427569 --- /dev/null +++ b/tickets/workflow-directory-layout.md @@ -0,0 +1,128 @@ +# Workflow の物理配置を `.insomnia/workflow` に分離する + +## 背景 + +現行の Workflow は `/.insomnia/memory/workflow/.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/.md` として `memory/` の外にある。Workflow も同様に `.insomnia/workflow/.md` を canonical path とし、memory state から分離する。 + +## 要件 + +### canonical path の変更 + +Workflow の標準配置を以下に変更する。 + +```text +/.insomnia/workflow/.md +``` + +旧配置は以下。 + +```text +/.insomnia/memory/workflow/.md +``` + +新規作成・ドキュメント・補完・resolver の説明は新配置を使う。 + +### 互換読み取り + +移行期間のため、loader は当面旧配置も読む。 + +- 新配置 `.insomnia/workflow/.md` を優先する +- 旧配置 `.insomnia/memory/workflow/.md` も fallback として読む +- 同じ slug が両方にある場合は新配置を採用する +- 旧配置を読んだ場合、可能なら warning / notification / log のいずれかで migration hint を出す + +旧配置の完全廃止は本チケットでは行わない。廃止が必要になったら別 ticket とする。 + +### linter / registry / completion + +- Workflow linter は新配置を検査できる +- `requires` の Knowledge 参照検査は従来通り維持する +- `WorkflowRegistry` は source path として新旧どちらも保持できる +- `/` 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/ + .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/.md` として実装・文書化されている +- 既存の `.insomnia/memory/workflow/.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`