feat(idd-issue): bundle flags — --parent / --blocked-by / --bundle-mode for ordered/unordered issue bundles

[kiki830621]

Problem

idd-issue v2.51.0 已支援文件來源批次建 issue + 自動 milestone(Step 4.5)、跨 repo groups 機制(primary + tracking + cross-link)、sister sweep(Step 4.7),但同 repo 內的 parent-child + ordering 沒有 first-class 支援。

當 N 個 issue 之間存在 dependency(schema 在 API 之前、phase 1 在 phase 2 之前),目前要手動兩步:先建 children → 再建 parent + 編 task list + 逐個加 Blocked-by 標註。失敗模式三:

1. 漏連結 — children 建好後忘了寫進 parent task list
2. 漏 dependency — Blocked-by 標註要逐個手動加
3. 使用者放棄 epic — 結果 N 個 issue 變孤兒

Type

feature(enhancement)

Solution

新增 3 個 flag 到 idd-issue(v2.52.0):

• --parent <N>:child 建完後 PATCH parent #N body 加進 task list(idempotent via #N reference scan)
• --blocked-by <M>[,<M2>...]:三層 fallback chain(GraphQL native dep + body blockquote + parent annotation)
• --bundle-mode <ordered|unordered>:單次 invocation 建 1 epic + N children,ordered 加 Blocked-by 鏈

加 ## Ordered Bundle Pattern 段落到 SKILL.md;加 canonical reference references/bundle-flags.md。

正交於既有 milestone / group / sister sweep 機制,backward compatible。

Spectra Change

完整設計、specs、tasks 在 openspec/changes/add-bundle-flags-to-idd-issue/(本 issue 的 anchor)。

Acceptance

• 三個 flag 行為符合 spec(openspec/changes/add-bundle-flags-to-idd-issue/specs/idd-issue-bundle/spec.md)
• Idempotency: --parent 重複呼叫不重複加 entry
• Graceful degradation: GraphQL 失敗 → warning + body blockquote 仍存在
• Cross-repo refuse: --parent <N> 跨 repo → abort + 指引 groups
• Mutual exclusion: --bundle-mode + group mode 同時 set → refuse
• Backward compat: 不帶 flag 的 invocation 行為完全不變

[kiki830621]

Implementation Complete

Spectra change: `add-bundle-flags-to-idd-issue` — 25/25 tasks done(see `openspec/changes/add-bundle-flags-to-idd-issue/tasks.md`)

Plugin version: v2.51.0 → v2.52.0(committed in faec1d9, marketplace synced, cache updated)

Solution

NEW `idd-issue` flag interface for ordered/unordered issue bundles:

• `--parent ` — child 建完後 PATCH parent #N body 加 task list entry。Idempotent via `#N` reference scan(重跑 no-op),fallback `## Children` anchor 段落
• `--blocked-by [,...]` — 三層 fallback chain 全部執行:Layer 1 GraphQL `addBlockedByDependency`(嘗試,失敗 → warning + continue 不 abort)+ Layer 2 child body `> Blocked by #M` blockquote(無條件,markdown 永遠可讀)+ Layer 3 parent task list `(blocked by #M)` 註解(僅 `--parent` co-used 時)
• `--bundle-mode <ordered|unordered>` — 單次 invocation 建 1 epic + N children。`ordered` 加嚴格 `child[i] blocked by child[i-1]` 鏈、`unordered` 純 task list 無 dependency

Pre-flight gates:cross-repo refuse(parent 在不同 repo → abort + 指引 `groups`)、bundle-mode 與 group-mode 互斥(refuse if both)。

Files Changed

• NEW `plugins/issue-driven-dev/references/bundle-flags.md` — canonical reference
• MOD `plugins/issue-driven-dev/skills/idd-issue/SKILL.md` — Step 0 bootstrap + Step 3.B handler + `## Ordered Bundle Pattern` section
• MOD `plugins/issue-driven-dev/.claude-plugin/plugin.json` — v2.52.0 + description
• MOD `plugins/issue-driven-dev/CHANGELOG.md` — v2.52.0 entry
• MOD `plugins/issue-driven-dev/CLAUDE.md` — skills table updated
• MOD `.claude-plugin/marketplace.json` — v2.50.0 → v2.52.0
• NEW `openspec/changes/add-bundle-flags-to-idd-issue/` — proposal / design / spec / tasks

Dogfood Verification

#	Scenario	Result
5.1	Epic + 3 children + task list + Blocked-by chain(test issues #22 epic, #23-#25 children,已 close)	✓
5.2	GitHub renders `- [ ] #N` task list entries as sub-issues with progress bar	✓(epic #22 body confirmed)
5.3	Layer 1 GraphQL `addBlockedByDependency` 失敗(repo 未 enable / API not available)→ Layer 2 body blockquote 持續存在,child 仍建立成功	✓(graceful degradation 驗證)
5.4	Idempotency:scan #N references shows exactly 1 entry, re-PATCH would no-op	✓
5.5	Cross-repo refuse via 404 detection(`gh issue view` returns non-zero on missing parent)	✓
5.6	Orthogonality with Step 4.5 milestone	✓ structural(Step 4.5 runs AFTER Step 3.B unchanged;bundle children/epic 進入既有 milestone 流程,no code path interaction)

Verification Coverage

• Spec contract:`openspec/changes/add-bundle-flags-to-idd-issue/specs/idd-issue-bundle/spec.md`(4 ADDED Requirements,全部對應 dogfood scenario 或 structural guarantee)
• Spectra analyze:Coverage / Consistency / Ambiguity / Gaps 4 dimensions all Clean(0 findings)
• Spectra validate:✓ valid

Backward Compatibility

不帶 flag 的 `idd-issue` invocation 行為完全不變。所有新 flag 都是 additive,既有 milestone 自動化(Step 4.5)、sister sweep(Step 4.7)、group 機制保持原樣。

Next

Issue #21 ready to close after final review。Spectra change 接下來會 archive 到 `openspec/specs/idd-issue-bundle/`。

[kiki830621]

Closing — Spectra change archived.

Final State

• Plugin v2.52.0 released:faec1d9 feat commit + 7c42e36 archive commit,both pushed to origin/main
• Spec contract:openspec/specs/idd-issue-bundle/spec.md(4 Requirements,frozen for future callers)
• Archive:openspec/changes/archive/2026-05-05-add-bundle-flags-to-idd-issue/(proposal / design / spec / tasks 完整保留)
• Marketplace:synced v2.50.0 → v2.52.0,cache updated
• Audit trail:Implementation Complete comment 在本 issue 上方,含 25/25 tasks done + 6/6 dogfood scenarios verified

Deferred(明確 Non-Goal,留給後續 proposal)

• Layer 3 runtime hint(Step 4.6) — 等實際使用 v2.52.0 flag 累積 dogfood pattern 後,再依使用 pattern 設計啟發式評分。本 change 只做 Layer 1 docs + Layer 2 flags

See

• Apply audit trail:本 issue 上方 Implementation Complete comment
• Reference doc:plugins/issue-driven-dev/references/bundle-flags.md
• Skill section:plugins/issue-driven-dev/skills/idd-issue/SKILL.md § Ordered Bundle Pattern(Step 5 之後)
• Frozen spec:openspec/specs/idd-issue-bundle/spec.md