--- description: yoi プロジェクトで child git worktree を作成・管理するための機械的手順。coder Pod に作らせず、orchestrator Pod が Orchestrator workspace/orchestration branch から実行する。 model_invokation: true user_invocable: true requires: [] --- # Worktree Workflow yoi プロジェクトで実装差分を root/original workspace から分離するため、記録済み implementation worktree root の `.worktree/` に child git worktree を作る。これは **worktree の扱い方だけ** を定める Workflow であり、ticket 選定、coder / reviewer sibling の起動、外部レビュー、orchestration branch への integration は `/multi-agent-workflow` 側で扱う。 yoi では Pod の write scope が排他的に委譲されるため、child Pod の write scope は child worktree に限定する。child worktree は Yoi project records marker として tracked `.yoi` records を含んでよいが、generated/personal memory root `.yoi/memory`、local override、runtime state、logs、locks、secret-like files は出さない。Orchestrator workspace or recorded Ticket backend remains the place for active orchestration progress, review evidence, integration records, and Ticket lifecycle updates. ## 適用範囲 この Workflow は親 Pod / 下位 orchestrator が Orchestrator workspace/orchestration branch から実行する。root/original workspace は read/write/validation/cleanup/git 操作の対象にしない。implementation worktree は記録済み implementation worktree root 配下に作る。 - coder Pod にこの Workflow を渡して worktree を作らせない。 - coder Pod は、orchestrator が作成済みの child worktree を受け取り、その中で実装・build・test・報告を行う。 - reviewer Pod は、coder Pod の子ではなく orchestrator 配下の sibling として、原則 read-only で child worktree と Orchestrator workspace の Ticket/context を読む。 - ticket 作成、active orchestration progress、review evidence、integration、Ticket lifecycle update は Orchestrator workspace または記録済み Ticket backend 側で扱う。 - branch-local artifacts / dossiers / docs/report / tracked `.yoi` project records は、実装対象に必要なら child worktree 内で扱ってよい。 ## 原則 - 1 ticket / 1 実装 task につき 1 worktree を作る。 - 複数 ticket を下位 orchestrator に任せる場合も、実装差分は ticket / bounded task ごとに worktree を分ける。 - worktree path は `/.worktree/`。 - branch 名は原則 `` と同じ kebab-case。 - child worktree には `.yoi` project records を出してよい。 - child worktree では `.yoi/memory`、local/runtime/log/lock/secret-like paths を sparse checkout で除外する。 - active orchestration progress、review evidence、integration、Ticket lifecycle update は Orchestrator workspace または記録済み Ticket backend 側で扱う。branch-local artifacts/dossiers は child worktree 内に置いてよい。 - push はしない。 ## 事前確認 作成前に以下を確認する。 1. 対象 ticket / task が決まっているか。 2. `` が branch / path 名に使える kebab-case か。 3. `git worktree add` を実行してよい許可があるか。 4. root/original workspace で実行しようとしていないか。 5. 同名 branch / worktree が既に存在しないか。 6. coder / reviewer を sibling として扱う orchestrator が誰か明確か。 同名 branch がある場合は、既存 branch を使うか、人間に確認する。`git worktree add -b` で上書きしない。 ## 作成手順 Orchestrator workspace で実行する。root/original workspace では実行しない。 ```bash git -C worktree add /.worktree/ -b HEAD git -C /.worktree/ sparse-checkout init --no-cone git -C /.worktree/ sparse-checkout set --no-cone \ '/*' \ '!/.yoi/memory/' \ '!/.yoi/memory/**' \ '!/.yoi/logs/' \ '!/.yoi/logs/**' \ '!/.yoi/_logs/' \ '!/.yoi/_logs/**' \ '!/.yoi/**/_logs/' \ '!/.yoi/**/_logs/**' \ '!/.yoi/locks/' \ '!/.yoi/locks/**' \ '!/.yoi/**/*.log' \ '!/.yoi/**/*.lock' \ '!/.yoi/**/.lock' \ '!/.yoi/override.local.toml' \ '!/.yoi/**/*.local' \ '!/.yoi/**/*.local.*' \ '!/.yoi/local/' \ '!/.yoi/local/**' \ '!/.yoi/runtime/' \ '!/.yoi/runtime/**' \ '!/.yoi/pods/' \ '!/.yoi/pods/**' \ '!/.yoi/sessions/' \ '!/.yoi/sessions/**' \ '!/.yoi/sockets/' \ '!/.yoi/sockets/**' \ '!/.yoi/tmp/' \ '!/.yoi/tmp/**' \ '!/.yoi/cache/' \ '!/.yoi/cache/**' \ '!/.yoi/secrets/' \ '!/.yoi/secrets/**' \ '!/.yoi/**/*.secret' \ '!/.yoi/**/*.secret.*' ``` この sparse-checkout は `.yoi` 自体を除外しない。`.yoi/memory` は generated/personal memory marker として child worktree から外し、generated log trees は root `_logs` だけでなく recursive `.yoi/**/_logs/**` も外す。memory root detection の実装変更はこの Workflow では扱わない。 確認する。 ```bash git -C /.worktree/ status --short --branch test ! -e /.worktree//.yoi/memory if test -d /.worktree//.yoi; then test ! -e /.worktree//.yoi/override.local.toml test -z "$(find /.worktree//.yoi \ \( -path '*/_logs' -o -path '*/logs' -o -path '*/locks' \ -o -path '*/local' -o -path '*/runtime' -o -path '*/pods' \ -o -path '*/sessions' -o -path '*/sockets' -o -path '*/tmp' \ -o -path '*/cache' -o -path '*/secrets' -o -name '*.log' \ -o -name '*.lock' -o -name '.lock' -o -name '*.local' \ -o -name '*.local.*' -o -name '*.secret' -o -name '*.secret.*' \) \ -print -quit)" fi ``` この確認は `.yoi` project records の存在を失敗扱いしない。`.yoi/memory` と local/runtime/log/lock/secret-like paths が出ていないことを確認する。 失敗した場合は、worktree / branch / lock の状態を確認し、勝手に cleanup せず人間へ報告する。 ## Pod へ渡す scope Pod を使う場合、coder Pod の SpawnPod `cwd` は child worktree に設定する。`cwd` は child process/tool default cwd だけを変え、runtime workspace root・project record root・scope/authority は変えないため、下の明示 scope は別途渡す。 coder Pod 推奨 scope: ```text read: /.worktree/ write: /.worktree/ ``` reviewer Pod 推奨 scope: ```text read: /.worktree/ read: # Ticket/intent/review context が必要な範囲に限定する ``` reviewer は原則 write scope を持たない。review artifact を書かせる必要がある場合だけ、ticket artifacts など限定 directory を write scope として渡す。 より狭く切れる場合は、coder の write scope を変更対象 crate / directory まで狭めてよい。ただし build / test に必要な生成物を書けることを確認する。 ## child worktree 内の禁止事項 - `.yoi/memory` を作らない / コピーしない / 復元しない。 - local overrides、runtime sockets/state、Pod session mirrors、cache/tmp、logs、locks、secret-like files を作らない / コピーしない / commit しない。 - root/original workspace の `TODO.md` / `tickets/` / `docs/report/` / `.yoi` を読まない・編集しない。 - active orchestration progress、review evidence、integration、Ticket lifecycle update を child worktree 内だけで完結させない。 - 実装対象に必要な tracked `.yoi` project records、branch-local artifacts / dossiers / docs/report は child worktree 内で扱ってよい。 - merge / push / branch deletion / worktree remove をしない。 - scope / permission / history persistence / prompt context 加工原則に関わる設計変更を無断で行わない。 ## 完了時の扱い worktree 作成 Workflow としては、完了時に integration しない。orchestration branch への integration、Ticket 完了、child worktree cleanup は `/multi-agent-workflow` 側で Orchestrator workspace に対して行う。root/original workspace は対象にしない。 coder Pod へ渡す完了報告項目の標準形: - worktree path - branch 名 - commit hash（coder Pod に commit を許可した場合） - 変更ファイル - 実装概要 - 実行した build / test / format - 未解決事項 - review に回せるか reviewer Pod へ渡す完了報告項目の標準形: - 読んだ ticket / intent packet / diff - 実際のコード変更の概念的説明 - intent / requirements / invariant との対応 - blocker / non-blocker / follow-up - validation の妥当性 - 親または上位 orchestrator が判断すべき残論点