diff --git a/TODO.md b/TODO.md index b7868b55..ec1900b8 100644 --- a/TODO.md +++ b/TODO.md @@ -1,7 +1,6 @@ - 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) - - AI maintainer 用 WorkItem / Thread 抽象 → [tickets/maintainer-work-items.md](tickets/maintainer-work-items.md) - tickets.sh による WorkItem / Thread MVP → [tickets/tickets-sh-workitem-thread-mvp.md](tickets/tickets-sh-workitem-thread-mvp.md) - Prompt / Workflow 評価メトリクスと改善 Offer → [tickets/prompt-eval-metrics.md](tickets/prompt-eval-metrics.md) - Permission: allow-all 既定 policy への整理 → [tickets/permission-default-policy.md](tickets/permission-default-policy.md) diff --git a/docs/plan/maintainer-work-items.md b/docs/plan/maintainer-work-items.md new file mode 100644 index 00000000..11bd7632 --- /dev/null +++ b/docs/plan/maintainer-work-items.md @@ -0,0 +1,76 @@ +# AI maintainer 用 WorkItem / Thread 抽象メモ + +## 位置づけ + +AI maintainer が単なる coding agent ではなく、作業の発見・分解・実装委譲・review・完了判断まで扱うには、現在の `TODO.md` / `tickets/*.md` だけでは足りない。必要なのは、個々の file path ではなく「作業単位」と「その会話・判断・成果物」を扱う抽象である。 + +このメモは実装 ticket ではなく、将来こういうものが必要になるという設計メモとして置く。具体的な最初の実装は `tickets.sh` / `work-items/` の MVP で試す。 + +## 必要になりそうな概念 + +- WorkItem + - 作業単位。title / status / kind / priority / labels / acceptance criteria / links を持つ。 +- Thread + - WorkItem に紐づく append-only な会話・判断・review・実装報告の流れ。 +- Event + - comment / plan / decision / implementation_report / review / status_change など。 +- Artifact + - review log、test log、設計メモ、branch / commit / worktree への link など。 +- Lease / Run + - どの Pod / agent がどの worktree / scope で作業中かを表す runtime coordination 情報。 + +## 配置の分担 + +repo-managed な project-visible 領域には、作業の正本として人間が読める coordination data を置く。 + +```text +repo/ + work-items/ # WorkItem / Thread / Artifact + tickets/ # 当面の既存 ticket。将来 WorkItem view に寄せる候補 + docs/ # plan / report +``` + +`.insomnia` は local runtime state として扱い、project coordination の正本にはしない。 + +```text +.insomnia/ + memory/ + workflow/ + maintainer/ + leases/ + runs/ + inbox/ +``` + +## ID と backend の考え方 + +WorkItem ID は中央 `SEQUENCE` にしない。複数 branch / worktree / Pod が同時に作業を作ると conflict しやすいため、timestamp + slug などの衝突しにくい ID にする。 + +```text +YYYYMMDD-HHMMSS- +YYYYMMDD-HHMMSS-- +``` + +backend は最初は repo 内 file backend でよいが、抽象としては Git directory 固定にしない。将来、remote maintainer hub や GitHub Issues などへ移る可能性を潰さない。 + +## 移行イメージ + +1. 既存の `TODO.md` / `tickets/` 運用は維持する。 +2. `tickets.sh` MVP で `work-items/` の file backend と thread 操作を試す。 +3. 既存 `TODO.md` / `tickets/` を手動で `work-items/` に寄せ、`doctor` が通る状態にする。 +4. その運用が安定したら、`TODO.md` を generated view にするか、廃止するかを判断する。 +5. 必要になった段階で Rust crate / Store interface / LeaseStore / remote backend を検討する。 + +## 当面やらないこと + +- remote maintainer hub の実装。 +- SQLite / index / search daemon の導入。 +- Pod lifecycle / completion tracking の完全実装。 +- LeaseStore の本格実装。 +- TUI 統合。 + +## 参照 + +- `tickets/tickets-sh-workitem-thread-mvp.md` +- `docs/plan/ai-maintainer.md` +- `tickets/auto-maintain-workflow.md` diff --git a/tickets/maintainer-work-items.md b/tickets/maintainer-work-items.md deleted file mode 100644 index 36a0c819..00000000 --- a/tickets/maintainer-work-items.md +++ /dev/null @@ -1,284 +0,0 @@ -# AI maintainer 用 WorkItem / Thread 抽象 - -## 背景 - -現在の開発運用は `TODO.md` と `tickets/*.md` を中心に回している。これは Git 履歴で要件と完了条件を追うには十分だが、AI maintainer が単なる Coding Agent を超えて運用を担うには弱い。 - -特に、設計相談、実装 Pod の作業報告、review 指摘、修正依頼、完了判断、Pod run、lease、artifact が ticket file / review file / 会話 / git log に分散し、thread として扱いづらい。 - -repository-managed issue directory example の `issues/` directory のように、repository 内に issue / work item を置く運用は参考になる。一方で、同 repository の owner も指摘している通り、中央の `SEQUENCE` ファイルによる連番採番は並列 branch / worktree で conflict しやすい。将来的な network 越し workspace / remote coordination も想定すると、最初から Git directory や中央採番前提で API を固めるべきではない。 - -本チケットでは、`tickets/` を直ちに置き換えるのではなく、AI maintainer が扱う上位の **WorkItem / Thread / Event / Lease / Artifact** 抽象を設計し、最小 file backend を導入できる状態にする。 - -## 方針 - -- WorkItem / Thread の正本は `.insomnia` ではなく、project-visible な repo-managed 領域に置く -- `.insomnia` は local runtime state / memory / workflow / Pod run / lease cache の領域として分離する -- API / domain model は Git に依存しない形にする -- WorkItem ID は中央 `SEQUENCE` 連番ではなく、作成時刻ベースの衝突しにくい ID にする -- 初期 backend は repo 内 directory（例: `work-items/` または `issues/`）でよい -- network 越し workspace / remote hub は後回しにするが、将来差し替え可能な interface を先に切る -- 既存 `tickets/` は当面維持し、WorkItem から link するか、file backend の一 view として扱えるようにする - -## データ配置 - -初期設計では以下の分離を前提にする。 - -```text -repo/ - work-items/ or issues/ # project-visible, git-managed coordination data - tickets/ # 当面の既存 ticket - docs/ # 設計・report - .insomnia/ # local agent/runtime state - memory/ - workflow/ - maintainer/ - leases/ - runs/ - inbox/ -``` - -### repo-managed に置くもの - -- WorkItem description -- acceptance criteria -- discussion thread -- design decision -- review comment -- status history -- linked branch / worktree / commit -- durable artifact metadata - -### `.insomnia` に置くもの - -- Pod run state -- lease の local cache -- SpawnedPod polling cursor -- temporary inbox -- local-only trial log -- model / role runtime state - -## WorkItem ID - -WorkItem ID は identity のためだけに使い、priority や処理順序を背負わせない。`SEQUENCE` のような中央連番ファイルは、複数 branch / worktree / Pod が同時に WorkItem を作ると conflict しやすいため採用しない。 - -初期 file backend では、directory name を immutable ID として扱う。 - -```text -YYYYMMDD-HHMMSS- -YYYYMMDD-HHMMSS-- # 同一秒衝突を避けたい場合 -``` - -例: - -```text -20260510-184233-maintainer-work-items -20260510-184233-a1b2-maintainer-work-items -``` - -要件: - -- lexical sort で概ね作成順になる -- 中央採番ファイルを更新しない -- collision 時は backend が短い random suffix や retry で解決する -- human-visible `slug` / `title` と immutable `id` を分ける -- priority / status / scheduling は `id` ではなく metadata で表す -- 将来 remote backend に移る場合も ID 生成責務は backend 側に閉じ込める - -## WorkItem model - -最低限、以下の概念を持つ。 - -```text -WorkItem -- id -- slug -- title -- status -- kind: feature | bug | refactor | design | ops | investigation -- priority / labels -- owner / assignee / current lease summary -- acceptance criteria -- linked ticket / docs / branches / worktrees / commits -- thread events -- artifacts -``` - -```text -ThreadEvent -- id -- work_item_id -- occurred_at -- author: human | orchestrator | pod: -- role: comment | plan | decision | implementation_report | review | status_change | escalation | artifact -- reply_to? -- body -- links -``` - -```text -Lease -- id -- work_item_id -- holder -- scope hint -- worktree path -- expires_at -- status: active | released | expired -``` - -Lease はリアルタイム coordination に近いため、Git-managed thread の正本とは分ける。file backend 初期実装では `.insomnia/maintainer/leases/` か local DB を使ってよい。 - -## backend interface - -AI maintainer / `/auto-maintain` は file path を直接前提にせず、概念上は store interface を通す。 - -```text -WorkItemStore -- list(filter) -- get(id) -- create(item) -- append_event(id, event) -- update_status(id, status) -- attach_artifact(id, artifact) -``` - -```text -LeaseStore -- acquire(work_item_id, holder, scope, ttl) -- refresh(lease_id) -- release(lease_id) -- list_active(filter) -``` - -初期 backend 候補: - -- `file:///work-items` -- `file:///issues` -- `sqlite:///.insomnia/maintainer/work-items.db` - -将来 backend 候補: - -- `http://maintainer-hub/...` -- `github://owner/repo/issues` - -## Query / listing - -初期 file backend の list / query は、index や DB を作らず全 `item.md` frontmatter scan で行う。 - -対象: - -```text -work-items/{open,pending,closed}/*/item.md -``` - -`item.md` の frontmatter に query 用 metadata を集約する。 - -```yaml ---- -id: 20260510-184233-a1b2-maintainer-work-items -slug: maintainer-work-items -title: AI maintainer 用 WorkItem / Thread 抽象 -status: open -kind: design -priority: P2 -labels: [maintainer, workflow] -created_at: 2026-05-10T18:42:33Z -updated_at: 2026-05-10T19:10:00Z -assignee: null ---- -``` - -`WorkItemStore::list` / `query` は frontmatter だけを読み、summary を返す。 - -- status / kind / labels / priority / assignee で filter する -- title / slug / description excerpt の軽い substring query を提供する -- sort は priority / updated_at / created_at を metadata で行う -- `thread.jsonl` は一覧では読まず、`get(id)` / thread read 時だけ読む -- `updated_at` は item metadata として持ち、必要なら thread append 時に更新する - -当面の件数では全件 scan で十分であり、AI に directory を探索させて候補を推測させない。index / SQLite / search daemon は件数増加、全文検索、remote backend 同期が必要になった時点で検討する。 - -### status の二重管理 - -file backend では directory と frontmatter の両方に status が出る。 - -```text -work-items/open//item.md -frontmatter: status: open -``` - -これは人間の `ls` と backend abstraction の両方を成立させるため許容する。ただし linter / doctor で一致確認する。 - -- `work-items/open/*/item.md` は `status: open` -- `work-items/pending/*/item.md` は `status: pending` -- `work-items/closed/*/item.md` は `status: closed` - -不一致は warning ではなく error とする。 - -## 初期 file backend 案 - -```text -work-items/ - open/ - 20260510-184233-maintainer-work-items/ - item.md - thread.jsonl - artifacts/ - review.md - test-log.txt - pending/ - 20260510-190102-transport-parameter-api/ - item.md - thread.jsonl - artifacts/ - closed/ - 20260510-201522-anthropic-burst-bundling/ - item.md - thread.jsonl - resolution.md - artifacts/ -``` - -`item.md` は human-readable な issue 本文（背景、根拠、完了条件、非目標など）を持つ。`thread.jsonl` は append-only を基本にし、AI maintainer が conversation / decision / review / status change を追いやすい形にする。`resolution.md` は close 時の解決方法や検証結果を、人間が読みやすい形でまとめる任意ファイルとする。 - -## `/auto-maintain` との関係 - -`/auto-maintain` は当面 `TODO.md` / `tickets/` を読むが、将来的には WorkItemStore を入口にする。 - -移行方針: - -1. 既存 `tickets/` は維持 -2. WorkItem 抽象と file backend schema を設計する -3. 新しい設計相談・並列作業・長い thread が必要な作業だけ WorkItem 化する -4. ticket は WorkItem の linked artifact として扱う -5. `work-items/open/` が安定したら、`TODO.md` は generated view または廃止候補にする -6. 十分に安定したら `tickets/` を WorkItem backend の view に寄せる - -## 範囲外 - -- remote maintainer hub の実装 -- index / SQLite / search daemon による query 最適化 -- 既存 `tickets/` の即時移行 -- 常駐 scheduler -- Pod lifecycle / completion tracking の完全実装 -- scope owner handoff の再設計 - -## 完了条件 - -- WorkItem / Thread / Event / Lease / Artifact の domain model が docs に定義されている -- repo-managed coordination data と `.insomnia` local runtime state の分担が明文化されている -- `WorkItemStore` / `LeaseStore` 相当の interface 方針が決まっている -- list / query は初期実装では全 `item.md` frontmatter scan で行う方針になっている -- `thread.jsonl` は一覧では読まず、詳細 read 時だけ読む方針になっている -- directory status と frontmatter status の一致を linter / doctor で確認する方針になっている -- WorkItem ID scheme が中央連番ではなく timestamp-based になっている -- 初期 file backend の directory schema が決まっている -- `/auto-maintain` / AI maintainer が将来 WorkItemStore を入口にできる移行方針が書かれている -- network 越し workspace / remote hub は後回しにしつつ、backend 差し替え可能性を潰していない - -## 参照 - -- `docs/plan/ai-maintainer.md` -- `tickets/auto-maintain-workflow.md` -- `docs/report/2026-05-10-ticket-lifecycle-branch-placement.md` diff --git a/tickets/tickets-sh-workitem-thread-mvp.md b/tickets/tickets-sh-workitem-thread-mvp.md index 7f9c498b..038039f0 100644 --- a/tickets/tickets-sh-workitem-thread-mvp.md +++ b/tickets/tickets-sh-workitem-thread-mvp.md @@ -8,23 +8,26 @@ Git は履歴の保存層として有用だが、人間や AI maintainer が毎回 file move / delete / review file 作成 / git log 探索を直接操作するのは低級すぎる。repository 内の file backend を正本にしつつ、`tickets.sh` で create / list / show / comment / review / close などの意味的操作を提供する。 -この ticket は `maintainer-work-items.md` の大きな WorkItemStore 設計の前段として、shell script による最小 MVP を実装する。 +この ticket は `docs/plan/maintainer-work-items.md` の抽象メモを踏まえた最小実装である。既存 `TODO.md` / `tickets/` を併用したまま新規領域を試すのではなく、今回の MVP では既存 `TODO.md` / `tickets/*.md` を手動で `work-items/` に移し、`tickets.sh doctor` が通る状態までをゴールにする。 ## 方針 -- 既存 `tickets/` / `TODO.md` はすぐに置き換えない。 -- 新しい thread 型作業だけ `work-items/` に置く。 +- 新しい正本は repo root の `work-items/` に置く。 +- 既存 `TODO.md` / `tickets/*.md` は手動 migration の入力として扱う。 +- migration 完了後、`TODO.md` は残す場合でも legacy / generated view 相当の最小内容にする。少なくとも未完了 item の正本を `tickets/*.md` に残さない。 - `tickets.sh` は Git を内部保存層として前提にしてよいが、操作単位は file path ではなく WorkItem 操作にする。 - 初期実装では自動 commit しない。 - `tickets.sh` は file 操作まで。 - - `git add/commit` は利用者または workflow が明示的に行う。 -- `--help` だけで基本操作が分かるようにする。 + - `git add/commit` は利用者または追加指示に任せる。 +- `--help` だけで基本操作と migration 方針が分かるようにする。 - shell script なので依存は POSIX shell + 基本 Unix tool に寄せる。`jq` 必須にはしない。 +- 既存 `tickets/*.review.md` がある場合は、対象 WorkItem の `thread.md` に review event として手動で移す。 -## 初期 backend schema +## backend schema ```text work-items/ + README.md open/ 20260526-123456-short-slug/ item.md @@ -52,6 +55,7 @@ labels: [maintainer, workflow] created_at: 2026-05-26T12:34:56Z updated_at: 2026-05-26T12:34:56Z assignee: null +legacy_ticket: tickets/foo.md --- ## Background @@ -63,6 +67,8 @@ assignee: null - ... ``` +`legacy_ticket` は migration 直後の追跡用 metadata とする。移行元 file は Git history で参照できるため、migration commit 後に `tickets/foo.md` を残し続けない。 + `thread.md` は append-only Markdown event log とする。JSONL より人間が読みやすいことを優先する。 ```md @@ -136,35 +142,51 @@ assignee: null - directory status と frontmatter `status` の一致を検査する。 - `item.md` / `thread.md` / `artifacts/` の存在を検査する。 - duplicate slug / duplicate id を検査する。 +- `TODO.md` / `tickets/*.md` に未移行の未完了 ticket が残っていないことを検査する。 +- `tickets/*.review.md` が残っていないことを検査する。 +- work-items 配下の markdown frontmatter に必須 field があることを検査する。 - error は非ゼロ exit。 +## 手動 migration 要件 + +この ticket の作業には既存運用からの手動 migration を含める。 + +- 現在 `TODO.md` に載っている未完了 ticket を `work-items/open/` に移す。 +- 各 `tickets/*.md` の本文を対応する `item.md` に移す。 +- 既存 `tickets/*.review.md` があれば対応する `thread.md` に review event として移す。 +- 移行元 ticket path は `legacy_ticket` metadata または本文の参照欄に残す。 +- migration commit 後、未完了 work item の正本として `tickets/*.md` を残さない。 +- `TODO.md` は legacy notice / generated view 相当の最小内容に更新する。 +- `tickets.sh doctor` が repository の移行状態まで含めて 0 になることをゴールにする。 + ## 要件 -- `tickets.sh --help` で使い方が分かる。 +- `tickets.sh --help` で使い方と migration 後の配置が分かる。 - `create/list/show/comment/review/status/close/doctor` が動く。 - WorkItem ID は timestamp-based で、central sequence file を使わない。 - close しても削除せず `work-items/closed/` に移動する。 - review は `.review.md` ではなく thread event として append できる。 - `doctor` が directory status と frontmatter status の不一致を検出する。 -- script は main repository の既存 `tickets/` を破壊しない。 +- `doctor` が未移行 `TODO.md` / `tickets/*.md` / `tickets/*.review.md` を検出する。 - 初期実装では自動 git commit しない。 -- README 相当の usage は `--help` に含める。 +- README 相当の usage は `--help` または `work-items/README.md` に含める。 ## 完了条件 - repo root に `tickets.sh` が追加される。 -- `work-items/` schema の minimal docs が script help または `work-items/README.md` にある。 +- `work-items/README.md` で schema / migration 後の運用が説明される。 - `tickets.sh create` で WorkItem を作成できる。 - `tickets.sh comment` / `tickets.sh review` で thread event を append できる。 - `tickets.sh close` で closed に移動できる。 -- `tickets.sh doctor` が正常ケースで 0、不整合ケースで非ゼロになる。 +- 既存 `TODO.md` / `tickets/*.md` / `tickets/*.review.md` が手動で `work-items/` に移行される。 +- migration 後、`tickets.sh doctor` が repository 全体の状態に対して 0 になる。 +- 不整合 fixture または smoke test で `doctor` が非ゼロになることを確認する。 - shellcheck が利用可能なら通る。無い場合は少なくとも focused smoke test を実行する。 ## 範囲外 -- 既存 `tickets/` の移行。 -- TODO.md の generated view 化。 - Rust crate / DB / remote backend 実装。 - LeaseStore / Pod run tracking の実装。 - Git commit の自動化。 - TUI 統合。 +- WorkItem から TODO.md を自動生成する仕組み。