[exploration] 平行執行多個 IDD 的隔離機制 — worktree vs branch 防衝突（#164 子問題）

[kiki830621]

Problem

Original text:
「要能夠平行做很哆idd才可以，不然現在在agent teams的時候會衝突，這是很重要的，可能不能只用branch還要用worktree才可以吧？要考慮怎麼讓多個idd不會彼此衝突的方法」
— Source: 直接貼文字（/idd-issue 對話）

要在 agent teams 場景下平行執行多個 IDD pipeline。目前多個 IDD 同時跑會互相衝突 —— 它們共享同一個 git working tree / branch / 暫存檔。使用者推測單靠 branch 隔離不夠，可能需要 git worktree 才能讓每個 IDD 有獨立工作目錄。核心需求：設計一套讓多個 IDD 不彼此衝突的隔離機制。

Type

enhancement（architecture / exploration seed）

Priority

使用者明確標示「這是很重要的」—— importance 高，是 #164 agent-teams 探索能否落地的前置 blocker（沒有隔離機制，平行化無從談起）。但仍屬 exploration，等 trigger 才 implement。

為什麼這是 #164 的具體子問題

#164 問的是「IDD 如何搭配 agent teams（verify ensemble / orchestration）」這個大方向。本 issue 從中切出最硬的工程約束：

• agent teams 的價值來自平行 → 但 IDD 的 stateful 操作（branch checkout、working-tree edit、commit、.claude/.idd/ 暫存、attachment staging）預設都假設單一序列執行者。
• 兩個 IDD 同時 git checkout 不同 branch → 後者覆蓋前者的 working tree。
• 兩個 IDD 同時寫 attachment staging / run-log → race。

兩個 case（user clarified 2026-05-30）

User clarification (verbatim):
「#167 的確我要分成兩個case，就是一個claude code視窗呼叫agent teams；另外一個是多個視窗每一個視窗可以跑一個idd」

平行的真正軸線是執行拓樸（execution topology），不是 pipeline 粒度（原 Clarity Surface 候選 a/b/c 軸選錯，已 resolved）。兩個 case 隔離難度不同：

Case A — 單一 Claude Code 視窗 → 呼叫 agent teams（within-window 平行）

• 平行單位 = 同一 session 內的 sub-agents（Agent tool / superpowers:dispatching-parallel-agents / TeamCreate）。
• 它們共享同一 process + 同一 cwd + 同一 working tree → 隔離最硬：不能靠「不同視窗不同目錄」。
• 可能解：每個 agent 用 Agent(isolation: "worktree")（harness 原生支援 per-agent worktree，跑完未變更會自動清除）；或限制平行只在 read-heavy phase（diagnose / verify 不碰 working tree），write phase（implement / commit）序列化。
• Orchestrator = 主 session，負責分派 + 收斂 + 臨界區守門。

Case B — 多個 Claude Code 視窗 → 每視窗跑一個 IDD（across-window 平行）

• 平行單位 = 獨立 Claude Code session（不同視窗），各自獨立 process。
• 但若多視窗指向同一 repo 目錄 → 仍 working-tree 互相覆蓋。
• 可能解：每視窗開在自己的 git worktree（.claude/worktrees/idd-<N>/）或獨立 clone；EnterWorktree / idd-implement --cwd 直接適用。
• 比 Case A 容易：視窗本就獨立 process，只要目錄分開、無共享 in-process 狀態。

兩 case 共用下方衝突面，但 severity 不同：Case A 連 .claude/.idd/ in-process staging 都共享、最硬；Case B 只要目錄隔離就解大半。

衝突面盤點（待 diagnose 時細化）

衝突資源	單序列下	平行下風險	Case A	Case B
Git working tree	✅ 安全	🔴 checkout 互相覆蓋	🔴	🔴（同目錄時）
Branch HEAD	✅ 安全	🔴 各自 commit 到同 branch	🔴	🔴（同目錄時）
.claude/.idd/ 暫存	⚠ ms-nonce 部分緩解（#76）	🟡 staging dir race	🔴 in-process 共享	🟢 目錄分開即解
Attachment release upload	✅ 安全	🟡 --clobber 同名互蓋	🟡	🟡
GitHub issue/PR state	✅ 安全	🟢 GitHub 端 atomic，低風險	🟢	🟢

候選方向（不預設答案，留 diagnose）

1. git worktree per IDD — 每個 IDD 在 .claude/worktrees/idd-<N>/ 有獨立 working tree + branch。對應現有 superpowers:using-git-worktrees skill + idd-implement --cwd flag。（Case B 主力解；Case A 用 per-agent worktree 變體）
2. isolation 改 process/container 層 — 各 IDD 跑在獨立 sandbox（重，但徹底）。
3. orchestrator 序列化臨界區 — read-heavy（diagnose/verify）平行，write-heavy（implement/commit）走 lock / queue。（Case A 主力解）
4. 混合 — read 階段平行、write 階段隔離 worktree。

既有 prior art（diagnose 起點）

• Agent(isolation: "worktree")：harness 原生 per-agent worktree 隔離 —— 直接對著 Case A。
• EnterWorktree harness tool：Claude Code 原生支援 .claude/worktrees/ 隔離 —— 對著 Case B。
• idd-implement --cwd / idd-verify --cwd：已支援在指定 local clone 上操作（references/cross-repo-cwd.md 的 substitution rule）。worktree 隔離可視為「同 repo 多 clone」特例。
• idd-all-chain：已做「ONE cluster branch + ONE review PR」的 spawn-manifest orchestration —— 但那是單序列遞迴，不是平行。

Out of scope

• 不在此 issue 解 [exploration] 探索 IDD workflow 如何搭配 agent teams (verify ensemble / orchestration) #164 的其他面向（verify ensemble 的 agent 數量、orchestration topology）。
• 不實作 —— exploration seed，等 trigger（真的要開始 agent-teams 平行化）才 /idd-diagnose。

---

Clarity Surface

Type	Term	Concern	Candidates	Status
ambiguity	「平行做很多 idd」	平行的粒度未定	(a) 平行整條 pipeline（issue→close）/ (b) 只平行 read-heavy phase（diagnose/verify）/ (c) 平行不同 root issue 的 idd-all-chain	resolved @ 2026-05-30 — user 校正：軸選錯，真正軸是執行拓樸（Case A within-window agent teams / Case B across-window 多視窗）。原 a/b/c 是次級子問題。見「兩個 case」section
missing-context	「agent teams」	指 Claude Code TeamCreate/SendMessage 原語，還是泛指多 agent？沿用 #164 同一 ambiguity	見 #164 candidates	resolved @ 2026-05-30 — Case A 把「agent teams」定義為單視窗內呼叫的平行 sub-agent 原語（Agent tool / dispatching-parallel-agents / TeamCreate），非泛指。同步釐清 #164 該 row

Linked-Context Siblings

Parent: #164（本 issue 是其工程約束子問題）

Current Status

Phase: closed
Last updated: 2026-05-30 by /idd-diagnose

Key Decisions

• 平行軸 = 執行拓樸（Case A within-window agent teams / Case B across-window 多視窗），非 pipeline 粒度（/idd-clarify 校正）
• Complexity = Spectra（Layer 2 新 published surface + Layer 3 cross-spec impact + architectural decision）
• 關鍵發現：git worktree 同時解 working-tree + .claude/.idd/ staging 兩衝突面；硬點轉移到「收斂」（N worktree branch 的 merge-back）
• Case B 先做（CP 值高、reuse 現有原語）；Case A 後做（orchestrator 收斂協定難）

Scope Changes

• (none)

Blocking

• (none) — closed via PR feat: parallel IDD via git worktree isolation (#167) #168 (squash b11b65d). Spectra change archived. Follow-ups: [refactor] 整合 #166 ↔ #167 的兩套 worktree 隔離公約 #169 (convention reconciliation), [bug] spectra-archive-post-ic 漏偵 prose-only #N reference #170 (post-IC detection).

Commits

• (none — exploration seed, no implementation)

[kiki830621]

Diagnosis

Type

feature / architecture（exploration seed）

Analysis（架構分析）

問題沿著 user 釐清的執行拓樸軸乾淨拆解。兩個 contention class：

1. Filesystem / git state（working tree、branch HEAD、.claude/.idd/ staging）—— 硬的那一半
2. Remote state（GitHub issue / PR）—— GitHub 端 atomic，低風險，本 diagnose 不深究

關鍵發現：worktree 一招解兩個衝突面

git worktree 有自己的 working directory（獨立 checkout），只共享 .git object store。因為 .claude/.idd/ 是 repo-relative path、住在 working dir 裡，所以每個 worktree 的 .claude/.idd/ 自動隔離。→ worktree 同時解掉 working-tree 覆蓋 和 staging-dir race 兩個衝突面，不需要分別處理。

這把問題從「設計隔離機制」重新定義成「隔離（已有現成原語）+ 收斂（真正的設計工作）」。

Case A — 單視窗 → agent teams（within-window 平行）

• 共享 process + cwd，但 harness 已有原語：Agent(isolation: "worktree") 給每個平行 sub-agent 自己的 worktree（跑完未變更自動清除）→ working tree + staging 都隔離。
• 真正的硬點是收斂：N 個 sub-agent 各在自己 worktree、各一條 branch，誰負責 merge 回 cluster branch？idd-all-chain 的「ONE cluster branch + ONE PR」模型假設單序列遞迴，不支援 N 條平行 branch 的 collection + merge-back。
• 次要：overlapping-file 的 merge conflict（兩個 agent 改同一檔）需要 orchestrator 仲裁。

Case B — 多視窗 → 每視窗一個 IDD（across-window 平行）

• 獨立 process，只需目錄隔離：每視窗開自己的 worktree（.claude/worktrees/idd-<N>/）或獨立 clone。EnterWorktree / idd-implement --cwd 直接適用，幾乎零新設計。
• 收斂由人仲裁（不同視窗各自開 PR、人決定 merge 順序）→ 比 Case A 容易一個量級。
• 設計工作主要是：一個「為 issue #N 起一個 IDD worktree」的 convention/helper + cleanup。

兩 case 共用的 cross-cutting 殘留衝突

共享資源	平行下狀態	評估
Attachments release --clobber	命名含 issue N（issue_<N>_*）	🟢 不同 issue 不撞；同 issue 平行處理才撞（罕見）
~/.cache/idd-route/stats.jsonl 全域 append	concurrent append 可能 interleave	🟡 小寫通常 line-atomic，但無保證
.claude/.idd/issue-runs/<run_id>.jsonl	#76 已加 ms-precision + nonce + noclobber	🟢 已處理

Impact

• 影響 skills/specs：idd-implement（branch/worktree）、idd-verify（working tree checkout + restore）、idd-all-chain（orchestration 模型）、idd-issue（staging）、references/cross-repo-cwd.md
• 影響 user flow：任何平行跑 IDD 的人（agent teams 或 multi-window）

Strategy

分兩條設計 track，共用 worktree 隔離地基：

• 定義 worktree-per-IDD convention（.claude/worktrees/idd-<N>/）+ lifecycle（create / cleanup / stale GC）
• Case B（先做，CP 值高）：helper/skill「為 #N 起 IDD worktree per 視窗」+ --cwd wiring。大部分 reuse 現有原語
• Case A（後做，難）：orchestrator 協定 —— read phase（diagnose/verify）平行、write phase 每 agent 一 worktree、branch collection + merge-back 進 cluster branch
• Audit 共享全域 state（attachments 命名、routing stats append）的平行安全性
• 把隔離契約（flags / 命名 / 收斂協定）spec 成 frozen surface 給 future callers

Complexity

Spectra

• Layer 2（necessary）命中：改動會對外暴露新 published surface —— 隔離 flags + 收斂協定，future callers（平行跑 IDD 的人 / orchestrator）依賴，behavior contract 應寫成 documented spec。
• Layer 3（confirmation）命中 ≥1：
  • 影響 2+ 既有 specs 需 consistency（idd-implement / idd-verify / idd-all-chain / cross-repo-cwd 都要協調更新）
  • Architectural decision with long-term maintenance implications（隔離拓樸是 future engineers 繼承的結構性決定）

→ 非單檔 fix（不是 Simple）、非純內部 refactor（加新 surface + cross-spec impact，超過 Plan）。Spectra 正確。

Risks

• git .git 共享鎖競爭：worktree 各有獨立 index（.git/worktrees/<name>/index），但 ref 更新 / packed-refs 仍共享 —— concurrent commit 更新 branch ref 可能罕見 contend。需實測驗證，不能假設零競爭。
• Worktree 增生 / cleanup leak（stale .claude/worktrees/ 堆積）。
• Case A merge-back conflict：N 個平行 agent 改 overlapping 檔。
• Over-engineering 風險：若真實使用幾乎都是 Case B（多視窗、人驅動），Case A 的 orchestrator 協定可能 premature。建議 Spectra discuss 時先確認 Case A 的真實需求強度再決定要不要做。

Residue

issue 更深的意圖 —— 「讓 IDD 成為 agent-team 平行化的 first-class citizen」（#164 的 horizon）—— 超出機械隔離，延伸到 orchestration 拓樸 + verify-ensemble 設計，那部分住在 #164、不在本 issue scope。本 diagnose 只 operationalize 了「隔離 + 收斂機制」這一 slice。

---

Vagueness Pre-check

• V1（vague WHAT）: 3 — Mostly clear。/idd-clarify 已把核心 ambiguity（平行的軸）resolve 成兩個明確 case（Case A within-window / Case B across-window），衝突面也列舉完整。剩下的開放是「選哪個隔離策略」—— 那是 HOW（Layer P / Spectra 處理），不是 WHAT vagueness。
• V4（vague ACCEPTANCE）: 3 — Mostly clear（for an exploration seed）。issue body Out-of-scope 明確標「不實作 — exploration seed」，完成定義 = 「每個 case 有 recommended 隔離策略 + 識別 prior-art 原語」，可 route 到 Spectra。非「done when done」。
• Triggered: no — both axes ≤ 3（clarify 步驟已移除真正的 vagueness）

Sister Concerns Filed (mid-diagnose, v2.47.0+ #528)

(none surfaced) — 所有衝突面（working tree / branch / staging / attachment clobber / routing-stats append）都是 #167 本身 scope 內的 sub-surface，不是獨立 sister concern。.claude/.idd/issue-runs 的 run_id collision 已由 #76 處理（既有，非新）。無需另開 issue。

[kiki830621]

Spectra change proposed + parked

/idd-diagnose → /spectra-discuss → /spectra-propose complete. Spectra change idd-worktree-isolation is created, validated, and parked.

Scope locked (v1):

• Case B (multi-window) isolation via a .claude/worktrees/idd-<N>/ worktree convention + thin idd-worktree.sh helper (create/cleanup/list), layered on existing --cwd.
• Convergence = N branches → N PRs (no merge-back); single-cluster-PR work stays on sequential /idd-all-chain.
• idd-implement Phase 0.5 gains a slug-agnostic idd/<N>-* worktree-branch acceptance clause; idd-close gains best-effort worktree GC.
• Case A (within-window agent teams, merge-back) explicitly deferred — recorded as the next boundary in the reference doc.

Artifacts: proposal / design / specs/idd-worktree-isolation / tasks (10 tasks). Analyzer clean, spectra validate ✓.

Next: /spectra-apply idd-worktree-isolation (auto-unparks) when ready to implement.

[kiki830621]

Verify: #167 (commit 1f34fcc)

Engine

5 general-purpose Agents (Requirements / Logic / Security / Regression / Devil's Advocate) + Codex (gpt-5.5, xhigh) — 6 independent AI, 2 model families. Test suite re-run independently by 2 reviewers: 30/30 GREEN.

Requirements coverage

7/7 addressed — 5 FULLY, 2 PARTIALLY (R1 create, R6 idd-close GC) per Codex's fixtures (both have a concrete fix, below).

Findings (merged, deduped, severity = max across sources)

#	Sev	Finding	Source	Action
1	P2	idd-close GC anchors on wrong root: cleanup "$NUMBER" passes no --repo-root; from inside/against a linked worktree, the helper's --show-toplevel returns the worktree (not the main checkout where .claude/worktrees/ lives) → silent no-op, actual worktree not removed	codex (fixture)	In-scope fix
2	P2	create wrong-branch idempotency: canonical idd-<N>/ registered but on a non-idd/<N> branch → create N still exits 0 + prints path (caller believes #N worktree correct, but wrong branch)	codex + agents:logic (cross-confirmed)	In-scope fix
3	P3	idd-implement Phase 0.5 acceptance not gated to --cwd context — any cwd on idd/<N>-* skips default-branch precondition (mild scope expansion; consistent with existing "resume on feature branch" behavior)	codex	In-scope fix (clarify intent)
4	P3	.gitignore idempotency guards on the path line, not literally a "marker comment" as spec wording says (functionally correct)	codex	In-scope fix (align spec wording)
5	LOW	ensure_gitignore >> follows a symlinked .gitignore (requires pre-existing repo write access — same trust boundary)	agents:security	In-scope fix (symlink guard)
6	LOW(doc)	design.md rationale over-claims "deletes that entire problem" — same-file parallel edits still git-conflict at 2nd PR merge; the spec SHALL is honest, only the prose over-reaches	agents:devils-advocate (fixture)	In-scope fix (clarify)
7	INFO	list test assertions grep '12'/'34' don't isolate the N column; stale-registration cleanup relies on a swallowed git fatal (benign)	agents:logic+DA	Noted (tighten tests)

Scope check

Clean — exactly 13 files, all map to #167's proposal Impact. The stashed spectra-archive WIP did not leak in. Versions consistent at 2.75.0.

Verdict

No hard-blocking findings, but the two P2s are genuine correctness gaps in the feature's own parallel scenario. Per same-PR-fix discipline, fixing #1–#6 in this PR before merge, then re-running the suite. Cross-model value confirmed: Codex's #1 was missed by all 5 same-family reviewers.

[kiki830621]

Verify findings resolved (commit 114f384)

All 6 actionable findings from the 6-AI round fixed in-PR before merge:

#	Sev	Fix
1	P2	Helper anchors repo-root on the main worktree (git worktree list first entry) → idd-close GC no longer silent-no-ops under --cwd. idd-close also passes --repo-root explicitly. + regression test (cleanup from a linked worktree still removes the target).
2	P2	create on a canonical path registered on a wrong branch → exit 4 (was misleading exit 0). + regression test.
3	P3	idd-implement note clarifies the acceptance clause is intentionally not --cwd-gated (consistent with existing resume-on-feature-branch behavior).
4	P3	spec .gitignore wording aligned to the line-presence guard.
5	LOW	ensure_gitignore refuses to append through a symlinked .gitignore.
6	doc	design.md rationale no longer over-claims "deletes that entire problem" (same-file parallel edits still conflict at 2nd PR merge; the spec SHALL was already honest).

Tests: 30 → 34 assertions, all GREEN. spectra validate clean. bash -n clean.

Cross-model value this round: Codex (gpt-5.5) constructed a fixture proving finding #1 that all 5 same-family reviewers rated FULLY — the different model caught the worktree-anchoring bug.

Phase: verified (no remaining blocking or in-scope findings).

[kiki830621]

Implementation Complete

Spectra change idd-worktree-isolation applied + archived → openspec/changes/archive/2026-05-31-idd-worktree-isolation/; 7 SHALL requirements synced to openspec/specs/idd-worktree-isolation/spec.md.

Checklist (synced from spectra tasks.md — 10/10)

• 1.1 Fixture-dir test harness (RED)
• 1.2 create subcommand (idd-worktree.sh)
• 1.3 cleanup subcommand
• 1.4 list subcommand
• 1.5 Test suite GREEN
• 2.1 references/worktree-isolation.md convention contract
• 2.2 idd-implement Phase 0.5 slug-agnostic worktree-branch acceptance
• 2.3 idd-close Step 6.7 best-effort worktree GC
• 2.4 cross-repo-cwd.md cross-ref
• 3.1 CHANGELOG + plugin.json 2.74.0 → 2.75.0

Legend: - [x] done. Case A (within-window agent teams, merge-back) was explicitly deferred at design time (D2) — out of v1 scope, recorded as the next boundary in worktree-isolation.md. It is a scope decision, not - [ ] debt.

Changes

• 1f34fcc feat + 03b2b17 verify-fix → squash-merged as PR feat: parallel IDD via git worktree isolation (#167) #168 (rebased onto docs: concurrent-session isolation rule (worktree-default + don't-yank) (#165) #166, reconciling the two worktree conventions).

Verification

6-AI ensemble (5 Claude reviewers + Codex gpt-5.5 xhigh) → 0 hard-blocking; 2 P2 + 4 minor → all fixed in-PR + regression-tested. 34/34 tests GREEN. spectra validate clean.

Spec

New capability idd-worktree-isolation (7 SHALL requirements) now lives in openspec/specs/.

---

Posted manually — spectra-archive-post-ic detected no Refs #N marker in the archived tasks.md (#167 referenced in prose only). #167 is the linked issue. This supersedes the diagnosis Strategy snapshot for the /idd-close gate.

[kiki830621]

Closing Summary

Problem

IDD 的每個 stateful 操作（branch checkout、working-tree edit、commit、.claude/.idd/ staging）都假設單一序列執行者。要平行跑多個 IDD（agent teams / 多視窗）會在共享 working tree 上互相覆蓋。

Root Cause / Background

這是 feature，不是 bug。需求源於 #164（IDD × agent teams）的最硬前置約束。/idd-clarify 校正了關鍵軸：平行的真正維度是執行拓樸（Case A 單視窗 agent teams / Case B 多視窗各一 IDD），非 pipeline 粒度。/idd-diagnose 的關鍵發現：git worktree 有自己的 working dir，一招同時隔離 working-tree + branch + repo-relative .claude/.idd/ staging。/spectra-discuss 的 YAGNI 收斂：N branches → N PRs（無 merge-back），把 Case A 的收斂協定整個 defer 掉。

Solution

Spectra change idd-worktree-isolation（v1 = Case B）：

• scripts/idd-worktree.sh（create / cleanup / list），worktree 在 .claude/worktrees/idd-<N>/，騎在既有 --cwd plumbing 上。
• references/worktree-isolation.md 公約契約 + 明標 Case A 為 deferred boundary。
• idd-implement Phase 0.5 slug-agnostic idd/<N>-* worktree-branch acceptance；idd-close Step 6.7 best-effort worktree GC（永不阻擋 close）。
• 7 SHALL requirements synced 進 openspec/specs/idd-worktree-isolation/。

Verification

6-AI ensemble（5 Claude reviewers + Codex gpt-5.5 xhigh）→ 0 hard-blocking。Codex（跨模型）抓到 idd-close GC 在 --cwd 下 silent-no-op 的 P2（5 個同模型 reviewer 全漏）—— root cause 是 linked worktree 的 rev-parse --show-toplevel 回 worktree 而非 main checkout。2 個 P2 + 4 個 minor 全在 PR 內修掉 + regression-tested。34/34 tests GREEN。

Changes

• PR feat: parallel IDD via git worktree isolation (#167) #168（squash b11b65d）— feat + verify-fix，rebased onto docs: concurrent-session isolation rule (worktree-default + don't-yank) (#165) #166（reconciling 兩套 worktree 公約）。
• Spectra change archived → openspec/changes/archive/2026-05-31-idd-worktree-isolation/。

Residue Acknowledgement

Diagnose 時宣告的 residue —— 「讓 IDD 成為 agent-team 平行化的 first-class citizen」（#164 的 horizon，延伸到 orchestration 拓樸 + verify-ensemble）—— 仍是 residue，as-is acknowledged：它住在 #164，本 issue 只 operationalize 了「隔離 + 收斂機制」這一 slice。Case A（within-window merge-back）已在 worktree-isolation.md 標為 deferred boundary。

Closing Follow-ups Filed

• [refactor] 整合 #166 ↔ #167 的兩套 worktree 隔離公約 #169 — 整合 docs: concurrent-session isolation rule (worktree-default + don't-yank) (#165) #166 ↔ [exploration] 平行執行多個 IDD 的隔離機制 — worktree vs branch 防衝突（#164 子問題） #167 的兩套 worktree 隔離公約（rebase 撞到 docs: concurrent-session isolation rule (worktree-default + don't-yank) (#165) #166 merge 發現的 convention divergence）
• [bug] spectra-archive-post-ic 漏偵 prose-only #N reference #170 — spectra-archive-post-ic 漏偵 prose-only #N reference（本次 IC 是手動補的）

Distribution Sync

• Detected: plugin (self-marketplace issue-driven-development)
• Choice: chain /plugin-update now
• Outcome: marketplace.json bumped 2.74.0 → 2.75.0 (commit c14d5e0, pushed); claude plugin marketplace update + claude plugin update → installed plugin now at 2.75.0, enabled.
• At: 2026-05-31T05:24:20Z