[refactor] 整合 #166 ↔ #167 的兩套 worktree 隔離公約

[kiki830621]

Problem

#166（concurrent-session isolation for PR-path branch acquisition）和 #167（parallel IDD via worktree）幾乎同時 landed，各自定義了一套 git worktree 公約，兩者 diverge：

面向	#166（references/pr-flow.md → "Concurrent-session isolation"）	#167（scripts/idd-worktree.sh + references/worktree-isolation.md）
Worktree location	$(git rev-parse --git-dir)/idd-worktrees/${BRANCH##*/}（在 .git 下）	.claude/worktrees/idd-<N>/（working tree 內、gitignored）
命名 key	branch name	issue number
生命週期	ad-hoc inline snippet（手動 worktree add / worktree remove）	managed helper（create / cleanup / list + idd-close auto-GC）
觸發點	idd-implement PR-path branch acquisition	多視窗平行 IDD（Case B）

Why this matters

兩套公約在 idd-implement/SKILL.md 的 Phase 0.5 note 已被我臨時 prose 橋接（PR #168 rebase 時），標為「same convention at different ergonomic tiers」。但實際 location / 命名不同 → 若使用者照 #166 snippet 手動建 worktree，跟 #167 helper 建的不在同一個地方，idd-worktree.sh list / idd-close GC 看不到。這本身就是 #167 要解的「平行 session 各自為政」問題的一個實例。

Proposed direction（待 diagnose）

1. 統一 location — 讓 docs: concurrent-session isolation rule (worktree-default + don't-yank) (#165) #166 的 pr-flow snippet 改用 .claude/worktrees/idd-<N>/（或反之），單一 source of truth。
2. docs: concurrent-session isolation rule (worktree-default + don't-yank) (#165) #166 snippet → 呼叫 idd-worktree.sh — pr-flow 的 ad-hoc worktree add 改成 idd-worktree.sh create，讓 managed lifecycle 涵蓋 PR-path branch acquisition 場景。
3. 釐清 branch-key vs issue-key 命名在兩場景的對應。

Out of scope

• 不重做 [exploration] 平行執行多個 IDD 的隔離機制 — worktree vs branch 防衝突（#164 子問題） #167 已 ship 的 helper；這是把 docs: concurrent-session isolation rule (worktree-default + don't-yank) (#165) #166 的 ad-hoc 路徑收進 [exploration] 平行執行多個 IDD 的隔離機制 — worktree vs branch 防衝突（#164 子問題） #167 的 managed 公約。

---

Source: surfaced during /idd-close #167（PR #168 rebase 撞到 #166 merge，發現兩套 worktree 公約）。Sister concern from #167.

---

Current Status

Phase: diagnosed
Last updated: 2026-05-31 by /idd-diagnose

Key Decisions

• Complexity = Plan → next: /idd-plan #169

Blocking

• (none) — diagnosed, awaiting pickup

Commits

• (none yet)

[kiki830621]

Diagnosis

Type

refactor（convention reconciliation）

Analysis

#166（pr-flow concurrent-session isolation）和 #167（idd-worktree-isolation）各自定義了一套 git worktree 公約，三軸 diverge：location（$(git-dir)/idd-worktrees/${BRANCH##*/} vs .claude/worktrees/idd-<N>/）、命名 key（branch vs issue number）、lifecycle（ad-hoc inline vs managed helper）。PR #168 rebase 時我在 idd-implement/SKILL.md Phase 0.5 用 prose 橋接（「same convention at different ergonomic tiers」），但底層 location 不同 → 照 #166 snippet 手動建的 worktree，idd-worktree.sh list / idd-close GC 看不到。

Impact

• plugins/issue-driven-dev/references/pr-flow.md（docs: concurrent-session isolation rule (worktree-default + don't-yank) (#165) #166 的 ad-hoc snippet）
• plugins/issue-driven-dev/skills/idd-implement/SKILL.md（Phase 0.5 prose bridge）
• 可能 references/worktree-isolation.md / openspec/specs/idd-worktree-isolation/spec.md（若 canonical location 改動觸及 spec normative）

Strategy

• 決定 canonical location — 建議 .claude/worktrees/idd-<N>/（已 spec'd、gitignored、idd-close GC + idd-worktree.sh list 都認得；.git/ 內的 worktree 較難被工具枚舉）
• 把 pr-flow.md 的 ad-hoc git worktree add snippet 改成呼叫 idd-worktree.sh create（或至少改用同一 location），讓 managed lifecycle 涵蓋 PR-path branch acquisition
• idd-implement Phase 0.5 的 prose bridge 從「two tiers」升級為指向單一 helper
• 確認是否需在 idd-worktree-isolation spec 加註「PR-path branch acquisition 也走此 helper」

Complexity

Plan

Layer P 信號：

• Decision-heavy — canonical location 是真實 open question（docs: concurrent-session isolation rule (worktree-default + don't-yank) (#165) #166 .git/idd-worktrees/ vs [exploration] 平行執行多個 IDD 的隔離機制 — worktree vs branch 防衝突（#164 子問題） #167 .claude/worktrees/，各有 rationale）
• Cross-file 有順序依賴 — 先定 location → 才能改 pr-flow snippet + idd-implement bridge
• Risk-sensitive boundary — concurrency / worktree（這正是兩 issue 的主題）

→ approval gate 適合鎖「哪套公約是 canonical」這個決定。若 planning 發現要改 published spec 的 SHALL clause → escalate Spectra。

Risks

改 pr-flow snippet 影響 #166 既有路徑；若 location 變動，已存在的 .git/idd-worktrees/ worktree 需 migration 考量（或文件註明僅對新建生效）。

Residue

(none) — 完全 operationalizable。