126 lines
6.1 KiB
Markdown
126 lines
6.1 KiB
Markdown
---
|
||
title: 'Panel Queue時にdevとOrchestrator worktreeを同期する'
|
||
state: 'closed'
|
||
created_at: '2026-06-12T01:16:39Z'
|
||
updated_at: '2026-06-12T12:26:26Z'
|
||
assignee: null
|
||
queued_by: 'yoi ticket'
|
||
queued_at: '2026-06-12T02:39:25Z'
|
||
---
|
||
|
||
## 背景
|
||
|
||
Orchestrator 用 dedicated worktree を分離したことで、Panel が操作する root workspace と Orchestrator が Ticket tools で見る worktree は別 checkout になった。
|
||
|
||
```text
|
||
root workspace / dev
|
||
Panel / human が Ticket を操作する場所
|
||
|
||
orchestration worktree / orchestration branch
|
||
Orchestrator Pod の cwd
|
||
Orchestrator の Ticket tools が見る `.yoi/tickets` backend
|
||
```
|
||
|
||
Ticket tools は Pod の cwd を基準に動作するべきであり、Orchestrator は orchestration worktree 側の `.yoi/tickets` を見る。そのため、Panel の Queue action で root/dev 側の Ticket を `ready -> queued` にするだけでは、Orchestrator が最新 Ticket state を見られない。
|
||
|
||
Queue は Orchestrator への durable handoff point なので、Orchestrator を kick する前に、root/dev 側の queued Ticket commit が orchestration worktree 側にも反映されている必要がある。
|
||
|
||
## ゴール
|
||
|
||
Panel の Queue action を、単なる Ticket state mutation ではなく、次の invariant を満たす安全な handoff として扱う。
|
||
|
||
1. root workspace の dev 側で対象 Ticket が `ready -> queued` になっている。
|
||
2. その変更が dev に commit されている。
|
||
3. orchestration worktree / branch がその commit を取り込んでいる。
|
||
4. Orchestrator は sync 済みの Ticket backend を見た状態で notify / restore / kick される。
|
||
|
||
## 要件
|
||
|
||
### Queue 実行前チェック
|
||
|
||
Panel の Queue action は、Ticket mutation 前に次の read-only check をすべて行う。ここに書いた条件以外を暗黙に判定しない。
|
||
|
||
- root workspace の canonical Git top-level が Panel の workspace root と一致する。
|
||
- orchestration worktree の canonical Git top-level が Panel が作成・記録した orchestration worktree path と一致する。
|
||
- root workspace と orchestration worktree の `git rev-parse --git-common-dir` が同じ repository を指す。
|
||
- root workspace の current branch が Panel の merge target branch（この repository では `develop`）と一致する。
|
||
- orchestration worktree の current branch が Panel の orchestration branch と一致する。
|
||
- root workspace の `git status --porcelain` が空である。
|
||
- orchestration worktree の `git status --porcelain` が空である。
|
||
- root workspace 側 Ticket backend で対象 Ticket が `ready` として読める。
|
||
- `git merge-base --is-ancestor <orchestration_head> <root_head>` が成功し、orchestration branch が root branch へ fast-forward 可能である。
|
||
|
||
いずれかが失敗した場合、Panel は Ticket mutation、commit、branch sync、Orchestrator notify/kick を行わず、失敗した check 名と対象 path / branch / Ticket id を表示する。
|
||
|
||
### Queue commit
|
||
|
||
Panel が Queue を実行する場合、root workspace 側で次の順序を守る。
|
||
|
||
1. 対象 Ticket を `ready -> queued` に遷移する。
|
||
2. `git status --porcelain` の差分が対象 Ticket record だけであることを確認する。
|
||
3. 対象 Ticket record だけを stage する。
|
||
4. dev 上に Queue commit を作る。
|
||
5. 作成した commit sha を記録する。
|
||
|
||
commit message は機械的でよいが、対象 Ticket id が分かるものにする。
|
||
|
||
Queue commit は Ticket handoff の authority であり、Orchestrator kick より前に完了している必要がある。
|
||
|
||
### dev -> orchestration sync
|
||
|
||
Queue commit 後、Panel は orchestration worktree を Queue commit へ fast-forward する。
|
||
|
||
自動同期で許可する操作は次だけに限定する。
|
||
|
||
```text
|
||
git -C <orchestration_worktree> merge --ff-only <queue_commit_sha>
|
||
```
|
||
|
||
この操作が失敗した場合、Panel は Queue を完了扱いにせず、Orchestrator notify/kick もしない。Panel は `orchestration branch cannot fast-forward to queue commit` と commit sha を表示する。
|
||
|
||
自動同期では merge commit、rebase、stash、patch apply、conflict resolution、dirty worktree cleanup を行わない。
|
||
|
||
### Orchestrator kick ordering
|
||
|
||
Orchestrator notify / restore / kick は、次を確認した後にだけ行う。
|
||
|
||
- root/dev 側の Queue commit sha が分かっている。
|
||
- orchestration worktree 側 HEAD がその commit を含んでいる。
|
||
- orchestration worktree 側の Ticket backend で対象 Ticket が `queued` として読める。
|
||
|
||
### Panel feedback
|
||
|
||
成功時は、Panel に次を表示する。
|
||
|
||
- queued Ticket id。
|
||
- dev 側 Queue commit sha。
|
||
- orchestration worktree sync 結果。
|
||
- Orchestrator notify/kick の有無。
|
||
|
||
失敗時は、どの条件で止まったかを具体的に表示する。
|
||
|
||
例:
|
||
|
||
- root workspace has uncommitted changes。
|
||
- orchestration worktree is dirty。
|
||
- orchestration branch cannot fast-forward to dev。
|
||
- orchestration worktree does not contain queued commit。
|
||
|
||
## 非目標
|
||
|
||
- dirty root workspace の変更を自動 stash / patch / commit すること。
|
||
- dirty orchestration worktree を自動修復すること。
|
||
- dev と orchestration branch の merge conflict を Panel が解決すること。
|
||
- Queue されていない Ticket を自動開始すること。
|
||
- Queue action で Orchestrator の routing / acceptance を代行すること。
|
||
|
||
## 受け入れ条件
|
||
|
||
- Panel Queue action が、Ticket `ready -> queued` を dev に commit してから orchestration worktree に同期する。
|
||
- sync 後、orchestration worktree 側 Ticket backend で対象 Ticket が `queued` として確認できる。
|
||
- Orchestrator notify / restore / kick は、orchestration worktree が Queue commit を含むことを確認してから行われる。
|
||
- root dirty / orchestration dirty / branch divergence / non-ff sync required の場合、Queue は block され、理由が Panel に表示される。
|
||
- Panel が自動 conflict resolution や stash を行わない。
|
||
- Ticket tools が cwd 基準で動く設計を前提に、workspace_root と cwd の分離を崩さない。
|
||
- `nix build .#yoi` が通る。
|