[refactor] /idd-all-chain cluster branch squash merge 對 multi-root 不友善 — 失去 Refs #N 軌跡與 bisect 精準度 (sister concern from #119)

[kiki830621]

Problem

從 #119 sister sweep 浮出: /idd-all-chain 設計把 N 個 root issue 共用 1 個 cluster branch + 1 個 review PR,期望最終 squash merge 進 main。當 N>1 且 roots 之間語意上是 parallel siblings(不是 ripple chain),squash merge 出問題:

1. Squash 摺成 1 commit message:14 個 unrelated changes 只有一條 commit message,git log 失去「哪個 commit 改了哪個 issue」的軌跡 — 違反 Refs #N 紀律
2. Revert 粒度 = 全部:某個 issue 後來發現要回退,squash 後只能整批 revert,炸到其他 13 個 issue
3. Bisect 失準:git bisect 找回歸 commit 時 N issue 都疊在一個 squash commit,bisect 結果只說「這 14 issue 中某個破事」沒辦法精準
4. Review cognitive load:reviewer 看 1 個 PR 含 14 個 unrelated 主題的 diff,容易漏 bug

替代方案考量:

• 改 merge strategy 為 --no-ff merge commit 保留 N 個原 commit → 但 PR 已 squash 默認,需專案 policy
• 切成 N 個 PR(回到 batch /idd-all 模式)→ 失去 cluster 的省 PR 開銷
• 中間方案:cluster branch 但 push N 個 commit 後 cherry-pick 拆 N 個 sub-PR? overhead 大

Type

refactor(merge strategy + cluster branch 設計問題)

Expected

/idd-all-chain 文件 / behavior 對「N roots merge 進 main 後續 git operations」有明確處理:

• 預設 merge strategy(squash vs merge commit)
• 警告 user 若 squash 預設與 multi-root 不相容
• 或 cluster mode 只允許 ripple chain(per /idd-all-chain 設計缺陷: hard-coded cap=10 / 無 multi-root vs ripple-chain pre-flight / cap 超過時 silent truncate #119 Facet B 收緊),不允許 multi-root → 從根本上避免 squash 問題

Actual

無明確 merge strategy 指引,user 跑 gh pr merge --squash 後遇到上述 4 個 git workflow 痛點。

Source

surfaced during /idd-issue #119 sister concern surfacing (Step 4.7)

---

Current Status

Phase: closed
Last updated: 2026-05-21 by idd-close
Closed at: 2026-05-21T03:55:16Z
Closing summary: comment-4504642552

Key Decisions

• Closed as absorbed-into-docs(per user decision 2026-05-21)
• Resolution path = doc reframing(commit 92e82c2 docs: introduce workflow path catalog + skill dimensions)not code fix
• 4 痛點已被 docs/workflows.md P-cluster-pr Risks 段落 + Anti-pattern A4 顯式 cover
• Distribution sync = not applicable(docs-only at repo root,不影響 plugin behavior)

Scope Changes

• (none — 原 issue scope 不變,但 disposition 從「code refactor 待做」改為「doc absorption 完成」)

Blocking

• (none)

Commits

• 92e82c2 docs: introduce workflow path catalog + skill dimensions
• e827bc7 docs: update cross-refs after migrating 6 IDD issues from marketplace

Closing Follow-ups Filed

• Skipped per user(closing summary 含 conditional hypothetical「若未來真要做 cluster default merge strategy refactor,將另開 follow-up issue」,not committed TODO)

[kiki830621]

After-reframing update — propose close (commit 92e82c2)

docs/workflows.md 把 P-cluster-pr 列為 named path,並 explicit document 其 risk:

Risks:cluster PR 內某 issue verify FAIL 影響整個 PR;close 階段需 per-issue closing summary

加上 Anti-pattern A4 守住誤用:

A4. P-cluster-pr 把不同根的 issue 強塞
idd-all #100 #200 #300 --pr(三個無關 issues)
Wrong:cluster PR 預期 issues 共享 review surface(同根問題、同檔案範圍)。不同根 → reviewer cognitive load 爆表;應分 3 個 P-atomic。

本 issue raised 的 squash merge 問題在合法 P-cluster-pr 使用(同根 issues)下殘留,但已從「skill bug」降級到「path 的 documented trade-off」。

Proposal: close

走 /idd-close #121,closing summary 寫:

Absorbed into docs/workflows.md P-cluster-pr (named path with documented risks)
+ Anti-pattern A4 (refuses misuse pattern). Squash merge limitations on
multi-root cluster are now path-level acceptance, not per-issue bug.

替代:keep open

若你認為 squash merge 紀律(Refs #N 軌跡保留 / bisect 精準度)仍值得獨立 refactor(例如改 cluster default 為 --no-ff merge commit),則保留 OPEN 並降 priority 為 P3。

待你決定:close(absorbed)還是 keep open(獨立 refactor)?

[kiki830621]

Closing Summary

Problem

/idd-all-chain cluster mode 把 N 個 root issues 共用 1 個 cluster branch + 1 個 PR,squash merge 進 main 後留下 4 個 git workflow 痛點:

1. Squash 摺成 1 commit message → 失去「哪個 commit 改了哪個 issue」軌跡
2. Revert 粒度 = 全部 → 某 issue 後悔只能整批 revert
3. Bisect 失準 → N 個 issue 疊一個 squash commit
4. Review cognitive load → reviewer 看 14 unrelated diffs

Root Cause

不是 IDD plugin 的 code bug — 是 cluster-PR path 在 N>1 root 用法下的inherent trade-off。原 framing 把它當 bug 處理,但 reframing(commit 92e82c2)後變成「path 設計選擇本身的代價」,不是缺陷。

Solution

Doc reframing 取代 code fix:

1. docs/workflows.md P-cluster-pr 把這條 path 命名 + 顯式列 risks(包含本 issue raise 的所有 4 痛點):

   Risks:cluster PR 內某 issue verify FAIL 影響整個 PR;close 階段需 per-issue closing summary

2. Anti-pattern A4 守住誤用 → 不允許「不同根 issues 強塞 cluster PR」這個會放大本 issue 痛點的 misuse:

   A4. P-cluster-pr 把不同根的 issue 強塞 — Wrong:cluster PR 預期 issues 共享 review surface;不同根 → reviewer cognitive load 爆表;應分 3 個 P-atomic

3. docs/skill-dimensions.md D6 Cluster axis(N issue + 1 PR)被 first-class 收進設計向度,後續加新 skill 時 explicit 對齊。

User 走 P-cluster-pr 前可看到 risks → discipline 在 path 選擇時 explicit,不是 silent bug。

Verification

• docs/workflows.md P-cluster-pr section 列出本 issue 提的 4 痛點(以 risk 形式)— path 文件化已 cover
• docs/workflows.md Anti-pattern A4 拒絕 misuse case — 誤用守住
• docs/skill-dimensions.md D6 把 Single/Batch/Cluster/Chain 4 種模式各自 trade-off 顯式列出 — 設計空間完整
• 兩文件 commit 92e82c2 已 land + push 到 origin

Changes

• 92e82c2 — docs: introduce workflow path catalog + skill dimensions(本 issue 的 doc absorption commit)
• e827bc7 — docs: update cross-refs after migrating 6 IDD issues from marketplace

Closing rationale

Close as absorbed-into-docs(per user decision 2026-05-21 after reframing)。若未來真要做 cluster default merge strategy 改 --no-ff 或別的 git workflow 紀律 refactor,將另開 follow-up issue,與本 issue scope 不同(本 issue 是 sister concern from #119 ripple-chain 設計討論,refactor 路線會是獨立的 git workflow 紀律 spec)。

Closing Follow-ups Filed (v2.45.0+ #527)

Skipped per user choice (conditional hypothetical: 「若未來真要做 cluster default merge strategy refactor,將另開 follow-up issue」 是 future-if-needed,not current TODO)

Residue Acknowledgement

no Diagnosis comment (sister concern from #119 sister sweep, never went through /idd-diagnose — no Residue section to acknowledge)

Distribution Sync

• Detected: plugin (matched issue-driven-dev plugin source)
• Choice: not applicable
• Outcome: docs-only change at repo root (commits 92e82c2 / e827bc7 touched docs/workflows.md + docs/skill-dimensions.md, not plugins/issue-driven-dev/). plugin.json not bumped — end user 'plugin update' would not see new content. No sync needed.
• At: 2026-05-21T03:59:08Z