ticket: clarify workitem migration scope

2026-05-28 03:49:21 +09:00 · 2026-05-28 03:49:21 +09:00 · 2820cbbe53
commit 2820cbbe53
parent 5c6df298aa
4 changed files with 111 additions and 298 deletions
--- 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)
--- a/docs/plan/maintainer-work-items.md
+++ 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-<slug>
+YYYYMMDD-HHMMSS-<short-rand>-<slug>
+```
+
+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`
--- a/tickets/maintainer-work-items.md
+++ b/tickets/maintainer-work-items.md
@ -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-<slug>
-YYYYMMDD-HHMMSS-<short-rand>-<slug>  # 同一秒衝突を避けたい場合
-```
-
-例:
-
-```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:<name>
- 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://<repo>/work-items`
- `file://<repo>/issues`
- `sqlite://<workspace>/.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/<id>/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`
--- 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 を自動生成する仕組み。