ticket: deprecate umbrella containers

2026-06-09 10:31:58 +09:00
parent 8db8d7d926
commit 1349a75350
6 changed files with 73 additions and 14 deletions
@@ -1,5 +1,5 @@
 ---
-description: worktree と sibling の coder / reviewer Pod を使い、下位 orchestrator が複数 ticket の実装・外部レビュー・修正・完了準備を管理する orchestration フロー
+description: worktree と sibling の coder / reviewer Pod を使い、下位 orchestrator が concrete Ticket 群の実装・外部レビュー・修正・完了準備を管理する orchestration フロー
 model_invokation: true
 user_invocable: true
 requires: []
@@ -20,7 +20,7 @@ worktree の機械的作成手順は `$user/worktree-workflow`、ユーザー依
 - orchestrator は coder / reviewer のやり取り、修正 loop、validation、merge-ready dossier 作成に責任を持つ。
 - 最上位 orchestrator は、コードを直接理解し切ることではなく、委譲した intent / 要件 / invariant に沿って下位 orchestrator が完了まで運んだかを acceptance する。

-## 階層モデル
+## Pod coordination model

 基本形は以下。

@@ -32,8 +32,8 @@ worktree の機械的作成手順は `$user/worktree-workflow`、ユーザー依
  - final merge / ticket close / main workspace validation を行う
  - 原則として line-by-line code review を主業務にしない

-下位 orchestrator Pod（area / epic / ticket-group coordinator）
-  - 連続した複数 ticket または大きめの ticket 群を完了状態まで運ぶ
+下位 orchestrator Pod（area / concrete-ticket-set coordinator）
+  - 連続した複数 concrete Ticket または大きめの concrete Ticket を完了状態まで運ぶ
  - worktree / branch / coder / reviewer / validation / 修正 loop を管理する
  - coder と reviewer を sibling として扱う
  - 親には merge-ready dossier と残論点だけを返す
@@ -50,13 +50,15 @@ reviewer Pod
  - intent / 要件 / invariant に反する blocker を分類して返す
 ```

-一段だけで足りる小さい ticket では、最上位 orchestrator が直接 coder / reviewer sibling を扱ってよい。複数 ticket や設計境界をまたぐ作業では、最上位の下に下位 orchestrator を挟む。
+一段だけで足りる小さい concrete Ticket では、最上位 orchestrator が直接 coder / reviewer sibling を扱ってよい。複数 concrete Ticket や設計境界をまたぐ作業では、最上位の下に下位 orchestrator を挟む。
+
+この Pod coordination model は runtime delegation の形であり、Ticket hierarchy を作る根拠ではない。複数 Ticket を扱う場合も各 Ticket は concrete work item として独立に実装・レビュー・検証・close できる必要がある。broad effort の進捗コンテナとして umbrella Ticket、parent/child Ticket、sub-ticket、part-of、contains などを作らない。中期的な目的や戦略は Objective context に置き、typed Ticket relations が利用可能な場合も dependency / related / blocking / replacement などの非階層メタデータに限る。

 ## 開始条件

 以下が揃っている時に使う。

- 対象 ticket または ticket 群が決まっている。
+- 対象 concrete Ticket または concrete Ticket 群が決まっている。
 - ticket の背景・意図・制約・受け入れ条件から、実装調査と局所 tactic 選択を coder に委ねても product / API / UX / authority / design-boundary decision を silently 固定しないと判断できる。
 - worktree 作成と git 書き込み操作について、人間の許可がある。
 - main workspace の unrelated dirty changes を把握している。
@@ -37,6 +37,8 @@ Intake は以下を行う。
 - 既存 Ticket を確認し、duplicate / related work を探す。
 - 必要に応じて関連 docs / code / workflow / history を読む。
 - 不足している要件を質問する。
+- 作成または refinement する Ticket が、実装・レビュー・検証・完了判断を単独で行える concrete work item であるか確認する。
+- 広い依頼を分割する場合は、進捗コンテナとしての umbrella Ticket ではなく、concrete Ticket / Objective context / split decision record に責務を分ける。
 - Ticket の title / slug / kind / priority / labels を提案する。
 - background / requirements / acceptance criteria / escalation conditions を整理する。
 - binding decisions / invariants と implementation latitude を分けて書く。
@@ -53,6 +55,8 @@ Intake は以下を行う。
 - implementation-ready でない Ticket を実装に投げない。
 - unattended scheduler として自動実行しない。
 - ユーザー合意なしに official Ticket を作らない。
+- broad effort の進捗を保持するためだけの long-lived umbrella / progress-container Ticket を作らない。
+- parent/child、sub-ticket、umbrella、part-of、contains などの hierarchy/container relation を split の代替として提案しない。
 - secrets / private context を Ticket body / thread / artifacts / diagnostics に保存しない。
 - arbitrary filesystem write で `work-items/` を編集しない。Ticket 操作は Ticket tools を使う。

@@ -92,11 +96,24 @@ Ticket tools が利用できない環境では、勝手に file write で代替

 - 同じ目的の open / pending Ticket がないか。
 - closed Ticket の判断・resolution と矛盾しないか。
- umbrella Ticket / follow-up Ticket が既にあるか。
- 既存 Ticket の refinement で足りるか、新規 Ticket が必要か。
+- 既存の umbrella/progress-container Ticket が、superseded/decomposed として退役できる状態か。
+- 既存 concrete follow-up Ticket や Objective context で足りるか、新規 concrete Ticket が必要か。

 既存 Ticket の更新で足りる場合、新規 Ticket を作らず、ユーザーに更新案を提示する。

+### 2.5. Broad request の split policy
+
+1つの依頼が複数の implementable work item を含む場合、Intake は以下を提案する。
+
+- broad effort を表す umbrella/progress-container Ticket は新規作成しない。
+- concrete slice ごとに、単独で実装・レビュー・検証・close できる Ticket を作る。
+- split した理由と残した範囲は、関連 Ticket の thread、必要なら Objective context に記録する。
+- Objective は中期的な目的・方針・success criteria を保持するために使う。Objective record の実装や schema 追加はこの workflow の責務ではない。
+- typed Ticket relation が利用可能になった場合も、dependency / related / blocking / replacement / supersedes などの非階層メタデータに限る。
+- parent/child、sub-ticket、part-of、contains のような hierarchy/container relation を作らない。
+
+ユーザーが「まず調査 Ticket」「設計 Ticket」「計画 Ticket」を concrete work item として求める場合は作成してよい。禁止されるのは、他の concrete Ticket の進捗を持つためだけに長期 open となる container Ticket である。
+
 ### 3. 要件を同期する

 最低限、以下を確認する。
@@ -43,6 +43,8 @@ Orchestrator は以下を行う。
 - queued notification を受けた場合も、Ticket と workspace state を再確認してから routing する。
 - next action を routing classification として決める。
 - routing decision を `TicketComment` で Ticket thread に記録する。
+- broad request や split/refinement では、long-lived umbrella/progress-container Ticket ではなく concrete implementable Ticket、Objective context、split decision record を使う。
+- 既存 umbrella/progress-container Ticket が concrete follow-up Ticket / Objective context で置き換え済みなら、superseded/decomposed として退役・close する routing を検討する。
 - implementation-ready の場合は `multi-agent-workflow` に渡す `IntentPacket` を作る。
 - implementation-ready かつ Ticket が `queued` の場合は、worktree 作成 / implementation Pod `SpawnPod` / coder routing などの side effect の前に、既存の typed Ticket backend/tool path で `queued -> inprogress` を記録する。
 - `ready` または `queued` に concrete missing decision / information がある場合だけ、typed state-change/routing event 付きで `planning` に戻す。その event/comment には missing item、checked context、implementation latitude では足りない理由、次の planning question/action を含める。
@@ -56,6 +58,8 @@ Orchestrator は以下を行う。
 - 設計境界の未決定を勝手に implementation-ready として固定しない。
 - merge / close / cleanup 権限を持たない場面で勝手に完了処理しない。
 - Ticket tools があるからといって arbitrary filesystem write を行わない。
+- broad multi-Ticket effort のために新しい umbrella/progress-container Ticket を作らない。
+- parent/child、sub-ticket、umbrella、part-of、contains などの hierarchy/container relation を split/refinement の代替として扱わない。
 - Notification だけを完了証拠にしない。Pod output / diff / validation / Ticket evidence を確認する。
 - 具体的な不足項目を言語化できない場合に、単に risky という理由だけで `planning` に戻さない。その場合は IntentPacket に escalation / reviewer focus を明記して進める。
 - risk flags / risky domain / authority-adjacent domain を automatic stop gate として扱わない。これらは bounded context lookup、IntentPacket invariant、reviewer focus、escalation condition に反映する signal である。
@@ -222,10 +226,12 @@ Action:
 - review / validation / merge / cleanup evidence が揃っている。
 - resolution を書ける。
 - close 権限がある。
+- 既存 umbrella/progress-container Ticket については、concrete follow-up Ticket と必要な Objective context が存在し、container role を superseded/decomposed として退役できる。

 Action:

 - `TicketClose` または既存 close workflow で resolution を記録する。
+- umbrella/progress-container Ticket を退役する close resolution では、関連作業がすべて完了したという意味ではなく container role を retired したことを明記し、完了済み concrete Ticket と残る follow-up Ticket / Objective を列挙する。
 - close 権限がない場合は merge-ready / close-ready dossier を親/人間に提出する。

 ### `defer_pending`
@@ -236,7 +242,7 @@ Action:

 - 優先度・タイミングの理由で後回し。
 - 依存はあるが active blocker として扱うほどではない。
- umbrella / roadmap 的に保持する。
+- broad request が concrete implementable Ticket に分解され、Objective context や split decision record の作成待ちである。

 Action:

@@ -389,7 +395,7 @@ IntentPacket が短く書けない場合、`implementation_ready` ではなく `
 - `review_needed` → reviewer Pod / review workflow
 - `blocked_action_required` → human / parent Orchestrator
 - `close_ready` → close workflow / maintainer decision
- `defer_pending` → pending / roadmap management
+- `defer_pending` → pending / Objective or split-decision follow-up management

 ## 完了条件

@@ -18,6 +18,8 @@ requires: []
 - `preflight` を workflow_state として扱う。
 - `preflight` vocabulary を current Ticket metadata として新規に書く。
 - 「リスクがある」だけで Ticket を戻す。
+- broad effort の進捗を保持するためだけの umbrella/progress-container Ticket を作る。
+- parent/child、sub-ticket、part-of、contains などの hierarchy/container relation を split/refinement の代替として設計する。
 - Coder / Reviewer / worktree mechanics を再設計する。

 ## 適用条件
@@ -25,6 +27,7 @@ requires: []
 次のいずれかを満たす場合に使う。

 - `planning` Ticket の要件・受け入れ条件・制約を明確化する。
+- ユーザーが concrete work item として求めた initial planning / design / investigation Ticket の scope と acceptance criteria を明確化する。
 - `ready` または `queued` Ticket について、Orchestrator が Ticket/thread/artifacts、関連 Ticket/plan、関連 workflow/docs/code、durable project context、workspace evidence の relevant subset を bounded に確認したうえで、実装開始前に concrete missing decision / information を特定した。
 - 既存 Ticket に obsolete state vocabulary が残っており、planning terminology へ整理する必要がある。

@@ -43,7 +46,7 @@ requires: []
 3. 不足している decision / information / acceptance condition を箇条書きで特定し、なぜ coder/reviewer の implementation latitude や escalation condition では足りないかを書く。
 4. `ready` または `queued` から戻す場合は、typed state change で `to = planning` を記録する。reason/body には concrete missing item、checked context、implementation latitude では足りない理由、次の planning question/action を含める。
 5. 既存の claimed live/restorable Intake/Planning Pod があり、利用可能な通知経路がある場合は、その Pod に同じ不足理由を通知する。実用的な経路が無い場合は follow-up として report する。
-6. Ticket body または thread に requirements sync 結果を残す。
+6. Ticket body または thread に requirements sync 結果を残す。広い依頼を分割する場合は、concrete follow-up Ticket / Objective context / split decision record へ責務を分け、umbrella container や hierarchy relation を作らないことを記録する。
 7. Ticket が queue 可能になったら `planning -> ready` を typed state change / `TicketIntakeReady` で記録する。

 ## 記録テンプレート