docs: relax implementation readiness wording

This commit is contained in:
Keisuke Hirata 2026-06-08 08:22:35 +09:00
parent c83fecd057
commit 1e2d1d8545
No known key found for this signature in database
5 changed files with 99 additions and 60 deletions

View File

@ -10,7 +10,7 @@ yoi を yoi で開発する際の、worktree + coder Pod + 外部 reviewer Pod +
worktree の機械的作成手順は `$user/worktree-workflow`、ユーザー依頼の Ticket 化は `$user/ticket-intake-workflow`、Ticket の next action 分類は `$user/ticket-orchestrator-routing`、実装前の要件同期・反証 preflight は `$user/ticket-preflight-workflow` に分ける。 worktree の機械的作成手順は `$user/worktree-workflow`、ユーザー依頼の Ticket 化は `$user/ticket-intake-workflow`、Ticket の next action 分類は `$user/ticket-orchestrator-routing`、実装前の要件同期・反証 preflight は `$user/ticket-preflight-workflow` に分ける。
この Workflow は、対象 ticket が implementation-ready であることを前提にする。設計境界・仕様・authority boundary が未同期の場合は、worktree 作成や coder Pod 起動の前に `ticket-preflight-workflow` を通す。 この Workflow は、対象 ticket が implementation-ready であることを前提にする。implementation-ready は full implementation plan ではなく、recorded intent / constraints / acceptance criteria / explicit decisions / escalation conditions に基づいて coder が bounded investigation を進め、reviewer が判断できる状態を指す。設計境界・仕様・authority boundary が未同期の場合は、worktree 作成や coder Pod 起動の前に `ticket-preflight-workflow` を通す。
## 目的 ## 目的
@ -57,13 +57,13 @@ reviewer Pod
以下が揃っている時に使う。 以下が揃っている時に使う。
- 対象 ticket または ticket 群が決まっている。 - 対象 ticket または ticket 群が決まっている。
- ticket の背景・要件・完了条件から実装方針が概ね導ける。 - ticket の背景・意図・制約・受け入れ条件から、実装調査と局所 tactic 選択を coder に委ねても product / API / UX / authority / design-boundary decision を silently 固定しないと判断できる。
- worktree 作成と git 書き込み操作について、人間の許可がある。 - worktree 作成と git 書き込み操作について、人間の許可がある。
- main workspace の unrelated dirty changes を把握している。 - main workspace の unrelated dirty changes を把握している。
- 下位 orchestrator に渡す intent / invariant / non-goals / escalation 条件を短く書ける。 - 下位 orchestrator に渡す binding decisions / invariants、implementation latitude、non-goals、escalation conditions を短く書ける。
- 設計境界・仕様・authority boundary に不確定要素がある場合、`ticket-preflight-workflow` の結果が ticket thread に記録されている。 - 設計境界・仕様・authority boundary に不確定要素がある場合、`ticket-preflight-workflow` の結果が ticket thread に記録されている。
設計方針が複数自然に導ける場合、protocol / scope / permission / history persistence に触れる場合、ticket 自体の再定義が必要な場合は、実装委譲前に `ticket-preflight-workflow` を通し、必要なら人間へ戻す。ただし下位 orchestrator に探索だけを委譲することはできる product / API / UX / authority / design-boundary 方針が複数自然に導ける場合、protocol / scope / permission / history persistence に触れる場合、ticket 自体の再定義が必要な場合は、実装委譲前に `ticket-preflight-workflow` を通し、必要なら人間へ戻す。実装ファイルの探索、既存コード読解、局所的な構成選択のような bounded implementation uncertainty は、intent / constraints / acceptance criteria / escalation conditions が明確なら coder に委ねてよい
## Intent packet ## Intent packet
@ -75,24 +75,31 @@ reviewer Pod
Intent: Intent:
- 何を実現するか。 - 何を実現するか。
Requirements: Binding decisions / invariants:
- 完了時に満たすべき observable な要件。 - 人間/Orchestrator/Ticket に記録済みで coder / reviewer が従うべき decision。
- 壊してはいけない設計境界、authority boundary、明示制約。
Invariants:
- 壊してはいけない設計境界。
- 残してはいけない旧概念や互換層。 - 残してはいけない旧概念や互換層。
Non-goals: Requirements / acceptance criteria:
- 今回やらないこと。 - 完了時に満たすべき observable な要件と reviewer が判断できる基準。
Implementation latitude:
- Coder が調査しながら選んでよい local tactic / file-local organization / bounded uncertainty。
Non-goals / constraints:
- 今回やらないこと、触ってはいけない場所。
Escalate if: Escalate if:
- 親へ戻すべき判断条件。 - 親へ戻すべき判断条件。特に product / API / UX / authority boundary / explicit design constraint を変える必要が出た場合。
Validation: Validation:
- 実行すべき format / build / test / doctor。 - 実行すべき format / build / test / doctor。
Reviewer focus:
- reviewer が確認すべき critical risks。
``` ```
reviewer には coder の実装方針ではなく、この intent packet と diff を中心に読ませる。 reviewer には coder の実装方針ではなく、この intent packet と diff を中心に読ませる。reviewer は recorded intent / constraints / acceptance criteria / explicit decisions に照らして判断し、不記録の preferred tactic を基準にしない。
## orchestrator の責務 ## orchestrator の責務
@ -159,9 +166,10 @@ reviewer には coder の実装方針ではなく、この intent packet と dif
- main workspace の管理ファイルを書かない。 - main workspace の管理ファイルを書かない。
- child worktree 内の tracked `.yoi` project records は ticket 要件に必要な branch-local artifact/dossier として扱ってよい。 - child worktree 内の tracked `.yoi` project records は ticket 要件に必要な branch-local artifact/dossier として扱ってよい。
- `.yoi/memory`、local/runtime state、logs、locks、secret-like files を child worktree に作らない。 - `.yoi/memory`、local/runtime state、logs、locks、secret-like files を child worktree に作らない。
- intent / requirements / invariants / non-goals を読んでから実装する。 - intent / requirements / acceptance criteria / binding decisions / invariants / non-goals / implementation latitude を読んでから実装する。
- 実装ファイルの探索、既存コード読解、局所的な tactic 選択は、intent packet の implementation latitude 内で行ってよい。
- 指定された build / test / format を実行する。 - 指定された build / test / format を実行する。
- ticket 要件外の設計変更、依存関係追加、scope / permission / history persistence / prompt context 加工原則に触れる変更が必要なら止めて orchestrator に報告する。 - ticket 要件外または binding decisions/invariants 外の設計変更、依存関係追加、scope / permission / history persistence / prompt context 加工原則に触れる変更が必要なら止めて orchestrator に報告する。
- 完了時に以下を報告する。 - 完了時に以下を報告する。
- worktree path / branch - worktree path / branch
- commit hashcommit した場合) - commit hashcommit した場合)
@ -180,8 +188,8 @@ reviewer は coder の subordinate ではない。orchestrator 配下の sibling
- 実際のコード変更が概念的に何を変えたかを説明する。 - 実際のコード変更が概念的に何を変えたかを説明する。
- 親や上位 orchestrator が line-by-line diff を読まずに判断できるよう、以下を整理する。 - 親や上位 orchestrator が line-by-line diff を読まずに判断できるよう、以下を整理する。
- 変更の概念モデル - 変更の概念モデル
- intent / requirements との対応 - recorded intent / constraints / acceptance criteria / explicit decisions との対応
- invariant 違反の有無 - binding decisions / invariants 違反の有無
- 旧概念・禁止語彙・不要な互換層の残存 - 旧概念・禁止語彙・不要な互換層の残存
- validation の妥当性 - validation の妥当性
- blocker / non-blocker / follow-up - blocker / non-blocker / follow-up

View File

@ -8,7 +8,7 @@ requires: []
Yoi の multi-agent 運用で、ユーザーの依頼をいきなり実装委譲せず、まず **合意済み Ticket** に変換するための Workflow。 Yoi の multi-agent 運用で、ユーザーの依頼をいきなり実装委譲せず、まず **合意済み Ticket** に変換するための Workflow。
Intake の目的は、ユーザーの意図・要件・受け入れ条件・未決定点を明確にし、Orchestrator が次の routing を判断できる Ticket を作ることである。Intake は scheduler ではなく、coder / reviewer Pod を起動しない。 Intake の目的は、ユーザーの意図・要件・制約・受け入れ条件・未決定点を明確にし、Orchestrator が次の routing を判断できる Ticket を作ることである。Intake は scheduler ではなく、coder / reviewer Pod を起動しない。
## 位置づけ ## 位置づけ
@ -25,6 +25,10 @@ User request / conversation
- `Assignment` は Orchestrator から coder / reviewer / investigator Pod への具体的委譲。 - `Assignment` は Orchestrator から coder / reviewer / investigator Pod への具体的委譲。
- `IntentPacket` は Ticket から抽出して Assignment に渡す短い実装・レビュー契約。 - `IntentPacket` は Ticket から抽出して Assignment に渡す短い実装・レビュー契約。
Intake は、要件同期と Ticket 化を担当する。実装の起動・worktree 作成・review 委譲・merge 判断は Orchestrator 側の責務である。`ready` は Orchestrator が routing できる状態を意味し、実装戦術がすべて事前固定されていることを意味しない。
Ticket に残す内容は、binding decisions / invariants、implementation latitude、escalation conditions を区別する。Coder が調査しながら局所的な実装手段を選べる余地は残してよいが、product / API / UX / authority boundary / explicit design constraint を silently 決める余地を残してはならない。
## Intake の責務 ## Intake の責務
Intake は以下を行う。 Intake は以下を行う。
@ -35,6 +39,7 @@ Intake は以下を行う。
- 不足している要件を質問する。 - 不足している要件を質問する。
- Ticket の title / slug / kind / priority / labels を提案する。 - Ticket の title / slug / kind / priority / labels を提案する。
- background / requirements / acceptance criteria / non-goals / escalation conditions を整理する。 - background / requirements / acceptance criteria / non-goals / escalation conditions を整理する。
- binding decisions / invariants と implementation latitude を分けて書く。
- readiness / needs_preflight / risk flags を明示する。 - readiness / needs_preflight / risk flags を明示する。
- ユーザー合意後に Ticket を作成する。 - ユーザー合意後に Ticket を作成する。
- 既存 Ticket の refinement を求められた場合は、TicketComment で経緯を残す。 - 既存 Ticket の refinement を求められた場合は、TicketComment で経緯を残す。
@ -112,8 +117,9 @@ Ticket 作成または更新前に、readiness を明示する。
```text ```text
implementation_ready: implementation_ready:
- 要件・受け入れ条件・non-goals / invariants が明確。 - 意図・制約・受け入れ条件・non-goals / invariants が明確。
- 実装方針が一意または十分絞れている。 - Reviewer が判断できる基準と escalation conditions が明確。
- 実装調査や局所的な tactic 選択は残っていてよいが、product / API / UX / authority boundary / explicit design constraint を coder が silently 決める余地はない。
- validation が書ける。 - validation が書ける。
requirements_sync_needed: requirements_sync_needed:
@ -142,7 +148,7 @@ unspecified:
- 複数の自然な設計方針があるもの。 - 複数の自然な設計方針があるもの。
- reviewer が diff だけでは見落としやすい設計リスク。 - reviewer が diff だけでは見落としやすい設計リスク。
risk flags は短い語でよい。 risk flags は短い語でよい。`needs_preflight: true` と risk flags は強い signal だが、missing boundary がすでに人間/Orchestrator の Ticket-recorded decision で補われている場合は、その decision を根拠に Orchestrator が routing できる。preflight は、実装が product / API / UX / authority boundary / explicit design constraint を silently 決める場合には mandatory のままである。
例: 例:
@ -198,7 +204,7 @@ Related tickets/docs:
- `TicketCreate` を使う。 - `TicketCreate` を使う。
- title / slug / kind / priority / labels / body を指定する。 - title / slug / kind / priority / labels / body を指定する。
- body に readiness / needs_preflight / risk flags を Markdown で明記する。 - body に readiness / needs_preflight / risk flags と、binding decisions / invariants、implementation latitude、escalation conditions を Markdown で明記する。
既存 Ticket refinement の場合: 既存 Ticket refinement の場合:
@ -227,7 +233,11 @@ Intake はここで止まる。implementation / worktree / coder / reviewer 起
## Acceptance criteria ## Acceptance criteria
## Non-goals ## Binding decisions / invariants
## Implementation latitude
## Non-goals / constraints
## Readiness ## Readiness

View File

@ -12,6 +12,8 @@ Yoi の multi-agent 運用で、Intake や人間が作成した Ticket を Orche
Panel Queue / queued notification は、人間が Orchestrator に routing を開始してよいと許可した signal であり、unattended scheduler ではない。implementation side effect に進む場合は、Orchestrator が Ticket と workspace state を再確認し、unblocked と判断してから `queued -> inprogress` を記録する必要がある。 Panel Queue / queued notification は、人間が Orchestrator に routing を開始してよいと許可した signal であり、unattended scheduler ではない。implementation side effect に進む場合は、Orchestrator が Ticket と workspace state を再確認し、unblocked と判断してから `queued -> inprogress` を記録する必要がある。
`ready` は Orchestrator routing に十分な状態であり、実装戦術が事前にすべて固定されている状態ではない。Orchestrator は、recorded intent / constraints / acceptance criteria / explicit decisions / escalation conditions が揃っていれば、bounded implementation uncertainty を残したまま implementation-ready と判断してよい。
## 位置づけ ## 位置づけ
```text ```text
@ -111,9 +113,9 @@ Action:
- profile / manifest / scope / permission / session / history / Pod metadata / prompt context に触れる。 - profile / manifest / scope / permission / session / history / Pod metadata / prompt context に触れる。
- public API / plugin / feature boundary / storage migration / security / secrets に触れる。 - public API / plugin / feature boundary / storage migration / security / secrets に触れる。
- 複数の自然な実装方針がある - 複数の自然な product / API / UX / authority / design-boundary 方針があり、human / Orchestrator decision なしでは固定できない
- implementation-ready に見えるが、reviewer が diff だけでは見落としやすい設計リスクがある。 - implementation-ready に見えるが、reviewer が diff だけでは見落としやすい設計リスクがある。
- `needs_preflight: true` または同等の記述が Ticket にある。 - `needs_preflight: true` または同等の記述が Ticket にある。ただし、missing boundary がすでに Ticket/thread の explicit human/Orchestrator decision で補われている場合は、その decision を binding として扱い、残る不確実性が実装 tactic に閉じているかを確認して routing できる。
Action: Action:
@ -145,10 +147,12 @@ Action:
条件: 条件:
- background / requirements / acceptance criteria が明確。 - intent / constraints / acceptance criteria が明確。
- non-goals / invariants / escalation conditions が必要十分。 - binding decisions / invariants と implementation latitude が区別されている。
- reviewer が判断する basis と escalation conditions が明確。
- validation が書ける。 - validation が書ける。
- design / authority boundary の未決定がない、または preflight 済み。 - design / authority boundary の未決定がない、または preflight / human decision で補われている。
- 残る不確実性が bounded implementation investigation / local tactic selection に閉じている。
- IntentPacket を短く書ける。 - IntentPacket を短く書ける。
Action: Action:
@ -170,6 +174,7 @@ Action:
Action: Action:
- reviewer Pod 起動または追加 validation を提案する。 - reviewer Pod 起動または追加 validation を提案する。
- reviewer は recorded intent / constraints / acceptance criteria / explicit decisions に照らして判断する。不記録の好みや Orchestrator の未共有 preferred tactic を基準にしない。
- `TicketComment` に review target と確認観点を記録する。 - `TicketComment` に review target と確認観点を記録する。
- blocker 未解決のまま merge-ready としない。 - blocker 未解決のまま merge-ready としない。
@ -268,7 +273,7 @@ Action:
例: 例:
- implementation-ready だが authority boundary に触れる → `preflight_needed` - implementation-ready に見えるが authority boundary の explicit decision がない → `preflight_needed`; explicit decision が Ticket/thread にあるなら binding として IntentPacket に載せる。
- 実装済みだが review がない → `review_needed` - 実装済みだが review がない → `review_needed`
- 要件が曖昧で spike も必要そう → `requirements_sync_needed` を優先し、調査問いを明確化する - 要件が曖昧で spike も必要そう → `requirements_sync_needed` を優先し、調査問いを明確化する
- 完了しているが close 権限がない → `close_ready` として dossier を返す - 完了しているが close 権限がない → `close_ready` として dossier を返す
@ -306,17 +311,20 @@ Escalate if:
Intent: Intent:
- 何を実現するか。 - 何を実現するか。
Requirements: Binding decisions / invariants:
- 完了時に満たす observable な要件 - 人間/Orchestrator/Ticket に記録済みで coder / reviewer が従うべき decision と、壊してはいけない design / authority boundary
Invariants: Requirements / acceptance criteria:
- 壊してはいけない design / authority boundary - 完了時に満たす observable な要件と reviewer が判断できる基準
Non-goals: Implementation latitude:
- 今回やらないこと。 - Coder が調査しながら選んでよい local tactic / file-local organization / bounded uncertainty。
Non-goals / constraints:
- 今回やらないこと、触ってはいけない場所。
Escalate if: Escalate if:
- 親/人間に戻す判断条件。 - 親/人間に戻す判断条件。特に product / API / UX / authority boundary / explicit design constraint を変える必要が出た場合。
Validation: Validation:
- 実行すべき format / build / test / doctor。 - 実行すべき format / build / test / doctor。
@ -324,8 +332,8 @@ Validation:
Current code map: Current code map:
- 実装対象と触ってはいけない場所。 - 実装対象と触ってはいけない場所。
Critical risks: Critical risks / reviewer focus:
- reviewer にも見てほしい失敗パターン。 - reviewer にも見てほしい失敗パターン。reviewer は recorded intent / constraints / acceptance criteria / explicit decisions に照らして判断し、不記録の preferred tactic を基準にしない。
``` ```
IntentPacket が短く書けない場合、`implementation_ready` ではなく `preflight_needed` または `requirements_sync_needed` に戻す。 IntentPacket が短く書けない場合、`implementation_ready` ではなく `preflight_needed` または `requirements_sync_needed` に戻す。

View File

@ -8,20 +8,20 @@ requires: []
yoi プロジェクトで ticket を実装に渡す前に、要件・前提・設計境界・反証観点を同期するための Workflow。これは **実装前の gate** であり、worktree 作成や coder / reviewer Pod の起動は `multi-agent-workflow` / `worktree-workflow` 側で扱う。 yoi プロジェクトで ticket を実装に渡す前に、要件・前提・設計境界・反証観点を同期するための Workflow。これは **実装前の gate** であり、worktree 作成や coder / reviewer Pod の起動は `multi-agent-workflow` / `worktree-workflow` 側で扱う。
目的は「ticket があるから実装する」状態を避け、ticket が **実装可能な仕様** なのか、**調査 ticket** なのか、**人間との仕様同期が必要な未決定 ticket** なのかを明確にすることである。 目的は「ticket があるから実装する」状態を避け、ticket が **実装可能な intent / constraints / acceptance criteria** を持つのか、**調査 ticket** なのか、**人間との仕様同期が必要な未決定 ticket** なのかを明確にすることである。実装 tactic をすべて事前固定する必要はないが、product / API / UX / authority boundary / explicit design constraint を coder が silently 決める余地は残さない。
## 適用する場面 ## 適用する場面
以下のいずれかに当てはまる ticket は、実装委譲前にこの Workflow を通す。 以下のいずれかに当てはまる ticket は、実装委譲前にこの Workflow を通す。
- profile / manifest / scope / permission / session / history / pod-store / prompt context など authority boundary に触れる。 - profile / manifest / scope / permission / session / history / pod-store / prompt context など authority boundary に触れる。
- ticket の文面から複数の自然な設計方針が導ける - ticket の文面から複数の自然な product / API / UX / authority / design-boundary 方針が導け、人間/Orchestrator decision なしでは固定できない
- 「どう実装するか」以前に「何を仕様とするか」が曖昧である。 - 「どう実装するか」以前に「何を仕様とするか」が曖昧である。
- 既存 implementation plan があるが、抽象化・責務境界・ユーザー体験に疑問がある。 - 既存 implementation plan があるが、抽象化・責務境界・ユーザー体験に疑問がある。
- 過去 decision / memory / docs / ticket thread と矛盾しそうである。 - 過去 decision / memory / docs / ticket thread と矛盾しそうである。
- coder Pod に渡す intent packet を短く書けない。 - coder Pod に渡す intent packet で、binding decisions / invariants、implementation latitude、escalation conditions 区別して短く書けない。
小さなバグ修正や仕様が明確な局所変更では、この Workflow は省略してよい。ただし省略理由が曖昧な場合は preflight する。 小さなバグ修正や仕様が明確な局所変更では、この Workflow は省略してよい。ただし省略理由が曖昧な場合は preflight する。`needs_preflight: true` や risk flags は強い signal だが、missing boundary がすでに Ticket/thread の explicit human/Orchestrator decision で補われている場合は、その decision を binding として扱い、残る不確実性が実装 tactic に閉じているかを確認して実装へ進められる。
## Ticket 記録方針 ## Ticket 記録方針
@ -52,7 +52,11 @@ yoi プロジェクトで ticket を実装に渡す前に、要件・前提・
```text ```text
implementation-ready: implementation-ready:
- 要件・受け入れ条件・invariant が明確で、実装方針が一意または十分絞れている。 - intent / constraints / acceptance criteria / reviewer judgment basis が明確。
- binding decisions / invariants と implementation latitude が区別されている。
- bounded implementation investigation や local tactic 選択は残っていてよい。
- product / API / UX / authority boundary / explicit design constraint を coder が silently 決める余地がない。
- validation と escalation conditions が明確。
requirements-sync-needed: requirements-sync-needed:
- ticket の目的は見えているが、仕様・用語・責務境界・ユーザー体験の同期が必要。 - ticket の目的は見えているが、仕様・用語・責務境界・ユーザー体験の同期が必要。
@ -64,7 +68,7 @@ blocked-needs-human-decision:
- 複数方針があり、AI が勝手に決めると設計境界や product API を固定してしまう。 - 複数方針があり、AI が勝手に決めると設計境界や product API を固定してしまう。
``` ```
`implementation-ready` 以外は、coder Pod に実装を委譲しない。 `implementation-ready` 以外は、coder Pod に実装を委譲しない。`implementation-ready` は full implementation plan ではなく、Orchestrator / coder / reviewer が同じ recorded intent と制約に基づいて判断できる状態である。
### 3. 要件同期 ### 3. 要件同期
@ -95,7 +99,7 @@ Current code map:
### 5. 批判的 preflight ### 5. 批判的 preflight
実装方針を一度疑う。以下の問いに答える。 実装戦術の候補を一度疑う。以下の問いに答える。目的は tactic の固定ではなく、実装が product/API/authority/design-boundary decision を隠れて固定しないことを確認することである。
- この ticket は本当に実装 ticket か、それとも仕様同期 ticket か。 - この ticket は本当に実装 ticket か、それとも仕様同期 ticket か。
- 最も自然に見える実装が失敗するとしたらどこか。 - 最も自然に見える実装が失敗するとしたらどこか。
@ -116,17 +120,20 @@ Current code map:
Intent: Intent:
- 何を実現するか。 - 何を実現するか。
Requirements: Binding decisions / invariants:
- observable な完了条件 - 人間/Orchestrator/Ticket に記録済みで coder / reviewer が従うべき decision と、壊してはいけない authority boundary / design boundary
Invariants: Requirements / acceptance criteria:
- 壊してはいけない authority boundary / design boundary - observable な完了条件と reviewer が判断できる基準
Non-goals: Implementation latitude:
- 今回やらないこと。 - Coder が調査しながら選んでよい local tactic / file-local organization / bounded uncertainty。
Non-goals / constraints:
- 今回やらないこと、触ってはいけない場所。
Escalate if: Escalate if:
- 親/人間に戻す判断条件。 - 親/人間に戻す判断条件。特に product / API / UX / authority boundary / explicit design constraint を変える必要が出た場合。
Validation: Validation:
- focused test / broader check / doctor / docs 更新。 - focused test / broader check / doctor / docs 更新。
@ -134,15 +141,15 @@ Validation:
Current code map: Current code map:
- 実装対象と触ってはいけない場所。 - 実装対象と触ってはいけない場所。
Critical risks: Critical risks / reviewer focus:
- reviewer にも見てほしい失敗パターン。 - reviewer にも見てほしい失敗パターン。reviewer は recorded intent / constraints / acceptance criteria / explicit decisions に照らして判断し、不記録の preferred tactic を基準にしない。
``` ```
この intent packet が短く書けない場合は、実装委譲せず requirements-sync-needed とする。 この intent packet が短く書けない場合は、実装委譲せず requirements-sync-needed とする。
## review への引き継ぎ ## review への引き継ぎ
preflight で出た critical risks は reviewer Pod にも渡す。reviewer は diff だけでなく、ticket の前提・要件・invariant と preflight の反証観点を読む preflight で出た critical risks は reviewer Pod にも渡す。reviewer は diff だけでなく、ticket の recorded intent / constraints / acceptance criteria / explicit decisions と preflight の反証観点を読む。reviewer は不記録の preferred tactic ではなく、記録済みの意図・制約・受け入れ条件・binding decisions に対して実装が十分かを判断する
reviewer に期待すること: reviewer に期待すること:

View File

@ -550,8 +550,8 @@ fn append_orchestrator_agent_routing_guidance(out: &mut String) {
out.push_str("- Create worktrees or spawn coder/reviewer Pods only after `workflow_state = inprogress` is already recorded and accepted. If the Ticket is still queued and unblocked, record `queued -> inprogress` before any worktree/SpawnPod side effect.\n"); out.push_str("- Create worktrees or spawn coder/reviewer Pods only after `workflow_state = inprogress` is already recorded and accepted. If the Ticket is still queued and unblocked, record `queued -> inprogress` before any worktree/SpawnPod side effect.\n");
out.push_str("- Use `worktree-workflow` for the mechanical worktree plan: create `.worktree/<task-name>`, keep tracked `.yoi` project records visible in the child worktree, exclude `.yoi/memory` plus local/runtime/log/lock/secret-like `.yoi` paths, and keep active orchestration progress plus final review/approval/close in the main workspace unless explicitly designed otherwise.\n"); out.push_str("- Use `worktree-workflow` for the mechanical worktree plan: create `.worktree/<task-name>`, keep tracked `.yoi` project records visible in the child worktree, exclude `.yoi/memory` plus local/runtime/log/lock/secret-like `.yoi` paths, and keep active orchestration progress plus final review/approval/close in the main workspace unless explicitly designed otherwise.\n");
out.push_str("- Use `multi-agent-workflow` for the sibling loop: coder and reviewer are siblings under this Orchestrator; coder gets narrow write scope to the child worktree; reviewer is read-only by default.\n"); out.push_str("- Use `multi-agent-workflow` for the sibling loop: coder and reviewer are siblings under this Orchestrator; coder gets narrow write scope to the child worktree; reviewer is read-only by default.\n");
out.push_str("- Give the coder an intent packet, child worktree/branch, validation commands, and report expectations; require Bash commands to `cd` into the child worktree, prohibit editing main-workspace `.yoi`/Ticket/workflow/docs records, and prohibit creating generated memory/local/runtime/secret-like files in the child worktree.\n"); out.push_str("- Give the coder an intent packet that distinguishes binding decisions/invariants, implementation latitude, escalation conditions, child worktree/branch, validation commands, and report expectations; require Bash commands to `cd` into the child worktree, prohibit editing main-workspace `.yoi`/Ticket/workflow/docs records, and prohibit creating generated memory/local/runtime/secret-like files in the child worktree.\n");
out.push_str("- Give the reviewer the Ticket intent, diff/commits, validation evidence, and blocker/non-blocker criteria; keep branch-local reviewer verdicts in the review report or merge-ready dossier rather than recording them as final main-branch Ticket approval.\n"); out.push_str("- Give the reviewer the recorded Ticket intent, constraints, acceptance criteria, explicit decisions, diff/commits, validation evidence, and blocker/non-blocker criteria; reviewer judgment is against recorded requirements and decisions, not unrecorded preferred tactics. Keep branch-local reviewer verdicts in the review report or merge-ready dossier rather than recording them as final main-branch Ticket approval.\n");
out.push_str("- Ticket thread progress may record worktree plan, coder delegated/completed/blocked, reviewer delegated, blocker/fix-loop summaries, and merge-ready dossier pointer; do not merge, close, or record final main approval in this routing/branch-review phase.\n"); out.push_str("- Ticket thread progress may record worktree plan, coder delegated/completed/blocked, reviewer delegated, blocker/fix-loop summaries, and merge-ready dossier pointer; do not merge, close, or record final main approval in this routing/branch-review phase.\n");
out.push_str("- Stop at a merge-ready dossier for `orchestrator-merge-completion` containing Ticket id/slug, branch/worktree, commits, intent/invariant check, implementation summary, coder/reviewer Pods, blockers fixed or rejected findings with reasons, validation performed, residual risks, dirty state, and parent/human decision needs if any.\n"); out.push_str("- Stop at a merge-ready dossier for `orchestrator-merge-completion` containing Ticket id/slug, branch/worktree, commits, intent/invariant check, implementation summary, coder/reviewer Pods, blockers fixed or rejected findings with reasons, validation performed, residual risks, dirty state, and parent/human decision needs if any.\n");
@ -569,14 +569,14 @@ fn append_coder_agent_routing_guidance(out: &mut String) {
out.push_str("\nCoder worktree routing guidance:\n"); out.push_str("\nCoder worktree routing guidance:\n");
out.push_str("- Implement only in the provided child worktree/branch. Use `cd <worktree>` before Bash commands and do not edit main-workspace `.yoi`, Ticket, workflow, docs, or memory records; child-worktree `.yoi` project records may be visible when they are part of the branch.\n"); out.push_str("- Implement only in the provided child worktree/branch. Use `cd <worktree>` before Bash commands and do not edit main-workspace `.yoi`, Ticket, workflow, docs, or memory records; child-worktree `.yoi` project records may be visible when they are part of the branch.\n");
out.push_str("- Do not create `.yoi/memory`, local/runtime state, logs, locks, caches, sockets, or secret-like files in the child worktree.\n"); out.push_str("- Do not create `.yoi/memory`, local/runtime state, logs, locks, caches, sockets, or secret-like files in the child worktree.\n");
out.push_str("- Treat the intent packet, invariants, non-goals, validation expectations, and report expectations as the contract. Escalate to Orchestrator rather than expanding scope when design, permission, history, prompt-context, dependency, or Ticket-boundary questions appear.\n"); out.push_str("- Treat the intent packet, binding decisions/invariants, constraints/non-goals, implementation latitude, validation expectations, and report expectations as the contract. Investigate and choose local tactics only within the recorded implementation latitude; escalate to Orchestrator rather than expanding scope when design, permission, history, prompt-context, dependency, or Ticket-boundary questions appear.\n");
out.push_str("- Report worktree path, branch, commits/status, changed files, implementation summary, validation run, unresolved notes, and whether the branch is ready for external review. Do not merge, push, close Tickets, or delete worktrees.\n"); out.push_str("- Report worktree path, branch, commits/status, changed files, implementation summary, validation run, unresolved notes, and whether the branch is ready for external review. Do not merge, push, close Tickets, or delete worktrees.\n");
} }
fn append_reviewer_agent_routing_guidance(out: &mut String) { fn append_reviewer_agent_routing_guidance(out: &mut String) {
out.push_str("\nReviewer worktree routing guidance:\n"); out.push_str("\nReviewer worktree routing guidance:\n");
out.push_str("- Review as a sibling of the coder under Orchestrator, read-only by default. Read the Ticket/intent packet, branch diff or commits, and validation evidence before judging.\n"); out.push_str("- Review as a sibling of the coder under Orchestrator, read-only by default. Read the Ticket/intent packet, branch diff or commits, and validation evidence before judging. Judge implementation against recorded intent, constraints, acceptance criteria, and explicit decisions, not unrecorded preferred tactics.\n");
out.push_str("- Classify findings as blockers, non-blocking follow-ups, or parent-decision items against the intent, requirements, invariants, and non-goals; include concrete file/line evidence where useful.\n"); out.push_str("- Classify findings as blockers, non-blocking follow-ups, or parent-decision items against the recorded intent, constraints, acceptance criteria, binding decisions/invariants, and non-goals; include concrete file/line evidence where useful.\n");
out.push_str("- Keep the branch-local reviewer verdict in the review report for the Orchestrator merge-ready dossier. Do not record final main-branch Ticket approval, merge, close, push, or instruct the coder directly.\n"); out.push_str("- Keep the branch-local reviewer verdict in the review report for the Orchestrator merge-ready dossier. Do not record final main-branch Ticket approval, merge, close, push, or instruct the coder directly.\n");
} }
@ -1087,6 +1087,8 @@ workflow = "ticket-review-workflow"
assert!(orchestrator_text.contains("multi-agent-workflow")); assert!(orchestrator_text.contains("multi-agent-workflow"));
assert!(orchestrator_text.contains("coder and reviewer are siblings")); assert!(orchestrator_text.contains("coder and reviewer are siblings"));
assert!(orchestrator_text.contains("branch-local reviewer verdicts")); assert!(orchestrator_text.contains("branch-local reviewer verdicts"));
assert!(orchestrator_text.contains("binding decisions/invariants"));
assert!(orchestrator_text.contains("not unrecorded preferred tactics"));
assert!(orchestrator_text.contains("merge-ready dossier")); assert!(orchestrator_text.contains("merge-ready dossier"));
assert!(orchestrator_text.contains("do not merge, close, or record final main approval")); assert!(orchestrator_text.contains("do not merge, close, or record final main approval"));
@ -1106,6 +1108,8 @@ workflow = "ticket-review-workflow"
assert!(coder_text.contains("do not edit main-workspace `.yoi`")); assert!(coder_text.contains("do not edit main-workspace `.yoi`"));
assert!(coder_text.contains("child-worktree `.yoi` project records may be visible")); assert!(coder_text.contains("child-worktree `.yoi` project records may be visible"));
assert!(coder_text.contains("Do not create `.yoi/memory`")); assert!(coder_text.contains("Do not create `.yoi/memory`"));
assert!(coder_text.contains("implementation latitude"));
assert!(coder_text.contains("choose local tactics"));
assert!(coder_text.contains("Do not merge, push, close Tickets, or delete worktrees")); assert!(coder_text.contains("Do not merge, push, close Tickets, or delete worktrees"));
let mut reviewer = TicketRoleLaunchContext::new(temp.path(), TicketRole::Reviewer); let mut reviewer = TicketRoleLaunchContext::new(temp.path(), TicketRole::Reviewer);
@ -1120,6 +1124,8 @@ workflow = "ticket-review-workflow"
assert!(reviewer_text.contains("branch: work/ticket-role-pod-launcher")); assert!(reviewer_text.contains("branch: work/ticket-role-pod-launcher"));
assert!(reviewer_text.contains("approve or request changes")); assert!(reviewer_text.contains("approve or request changes"));
assert!(reviewer_text.contains("read-only by default")); assert!(reviewer_text.contains("read-only by default"));
assert!(reviewer_text.contains("recorded intent, constraints, acceptance criteria"));
assert!(reviewer_text.contains("not unrecorded preferred tactics"));
assert!(reviewer_text.contains("branch-local reviewer verdict")); assert!(reviewer_text.contains("branch-local reviewer verdict"));
assert!(reviewer_text.contains("Do not record final main-branch Ticket approval")); assert!(reviewer_text.contains("Do not record final main-branch Ticket approval"));
} }