feature: mechanism for sync archived Spectra spec deltas with subsequent capability extensions

[kiki830621]

Problem

Source: surfaced during /idd-verify #47 (codex P3 #6).

/idd-all-chain capability spec at openspec/specs/idd-all-chain/spec.md 是 archived from #44 (add-idd-all-chain-skill change)。但 #47 落地後 spec 沒同步更新 — Phase 0 描述仍是 4 道 gate (git/auth/issue OPEN/cluster branch),沒有第 5 道 diagnosis-readiness gate。

實務上 archived spec 是 frozen contract;後續 capability 擴展(#47 / 預期的 #46 multi-root)沒有清楚的 mechanism 把 delta 推回 archived spec。

Type

feature (process / infrastructure)

Expected

定義 archived spec sync mechanism。可能方向:

• a. 後續 change 用 MODIFIED 修改 archived spec(類似 spectra apply 的 spec delta,但 source 是 archived)
• b. 每次擴展都是新 capability(idd-all-chain-v2 / idd-all-chain-multi-root),不修 archived
• c. Archive 內維護 changelog appendix(spec.md + extensions.md),不動 frozen 部分

Priority

P3 (process improvement;不影響 #47 本身落地,但長期影響 spec discipline)

---

Current Status

Phase: diagnosed
Last updated: 2026-05-10 by idd-diagnose (batch)

Key Decisions

• Complexity = Spectra (Layer 2 + Layer 3a/b/c 都命中: published convention + spec authority + cross-archive ripple + architectural decision)
• Layer V triggered (V1=3 V4=4) — but proceed anyway default for V4=4; Spectra path 本來就會 converge ambiguity in spectra-discuss
• Lean Option b (new capability per extension) but needs spectra-discuss alignment

Blocking

• 等 user 跑 /spectra-discuss 對齊 Option a/b/c

[kiki830621]

Diagnosis

Type

feature (process / infrastructure — Spec lifecycle mechanism)

Analysis

Issue body 列了 3 個 design directions:

• a. MODIFIED archived spec — 後續 change 對 archived spec 用 MODIFIED delta(類似 spectra-apply 的 spec delta 但 source 是 archived)
• b. New capability per extension — idd-all-chain-v2 / idd-all-chain-multi-root 各自獨立,不修 archived
• c. Archive 內 changelog appendix — spec.md(frozen)+ extensions.md(累加 entries),不動 frozen 部分

Trade-off 評估

Option	Audit clarity	Implementation cost	Frozen-spec discipline	Cross-spec ripple risk
a. MODIFIED archived	High(single source)	Medium(改 spectra-apply 容許 archived path)	Broken(frozen 概念失效)	Low(spec authority centralized)
b. New capability	Medium(分散但各自完整)	Low(沿用既有 capability mechanism)	Preserved(archived 真 frozen)	High(每個擴展都要 cross-spec consistency check)
c. Changelog appendix	Medium(audit 在 appendix)	Medium(新檔案 convention)	Preserved partial	Medium

個人 lean:Option b — 跟 IDD 的 capability-version-evolution mental model 最 match:

• archived idd-all-chain v1.0 spec → frozen
• feature: /idd-all-chain Phase 0 pre-flight check for root issue diagnosis-readiness #47 ship → 新 capability idd-all-chain v1.1(diagnosis-readiness gate)— 但其實是同 capability 的 minor evolution
• 真 multi-root(feature: /idd-all-chain accept multiple root issues with DFS/BFS traversal (default DFS) #46)的話可以視為 v2.0 / new capability

但 issue 標題談的是「mechanism」,代表要先決定哪個 option,這本身就是 design discussion 不能在 diagnose 階段 unilateral 決。

Inherent Spectra-tier signal

本 issue 影響:

• 新 published convention for future spec lifecycle(tooling 與 reviewers 要 follow)
• 跨 capabilities ripple:每個 archived capability 都受影響
• Architectural decision with long-term maintenance implications:選 a/b/c 後 IDD 的 spec evolution culture 永遠跟著走

這 3 點滿足 Layer 2 + Layer 3 — Spectra tier。

Impact

• 影響的工作流:future spec evolution (idd-all-chain ext, idd-spawn-manifest ext, idd-orchestrator-modes ext, ...任何 archived capability 想擴展)
• 影響的檔案(per option):
  • Option a:spectra-app 改 spec delta source(third-party — 跨 plugin coordination)
  • Option b:無(既有 mechanism;只需 docs 約定 naming + cross-link)
  • Option c:新 reference doc + spectra-archive workflow extension
• 影響的使用者流程:設計 review 階段 author 要先決定 path(若 a/b/c 沒 docs 的話)

Strategy

(Spectra path — discuss first to converge,以下是 propose 階段預期 task list:)

• /spectra-discuss 收斂 a/b/c trade-off + pick(本 diagnose lean b 但需 user 確認)
• /spectra-propose 起草 proposal 含 mechanism doc + workflow examples
• design.md 含 case study:feature: /idd-all-chain Phase 0 pre-flight check for root issue diagnosis-readiness #47(diagnosis-readiness gate)如何 fit chosen mechanism
• 若選 b(無新 mechanism):docs 寫進 references/spec-evolution.md 或類似 location
• 若選 a:跨 plugin coordination + spectra-app contract refinement
• 若選 c:新 reference doc spec + spectra-archive workflow update

Complexity

Spectra (Layer 2 + Layer 3 都命中)

理由:

• Layer 2 命中:選 a/b/c 任一都 publishes new convention (tooling / reviewers / future authors 都要 follow)— is published API for "future callers" of spec lifecycle process
• Layer 3a 命中:spec.md per-capability 是既有 published spec — modify 規則改變影響每個 archived spec 的 normative behavior
• Layer 3b 命中:Cross-spec impact — 任何 capability 要擴展都觸到本 mechanism
• Layer 3c 命中:Architectural decision long-term implications — 改 IDD 的 spec evolution culture

Layer V — vagueness check:

• V1: 3 — what 清楚(define mechanism),但沒指定哪個 option
• V4: 4 — Acceptance 模糊 (沒 explicit "done when X" criteria for spec lifecycle decision)
• Triggered: yes (V4=4)

但 V4=4 default 是 proceed anyway per attribute-assessment.md anchors。Spectra path 本來就會在 spectra-discuss 階段 converge 這些 ambiguity,所以 proceed 合理。

Risks

• Decision avalanche:本 mechanism 一旦 ship,所有 archived spec 都受影響 — error 一次後續一連串 cascade
• Spectra-app upstream dependency (option a):若選 a,需協調 third-party plugin
• Verify 困難:mechanism design correctness 不好用 6-AI 自動 verify — 需要 case study 驗證(feature: /idd-all-chain Phase 0 pre-flight check for root issue diagnosis-readiness #47 適合作 reference)

Recommended Path

Spectra (default — discuss first) → /spectra-discuss。

理由:3 個 design options 沒 explicit 收斂的 winner;spectra-discuss 是 design alignment 的 safety net,在這種 architectural decision 不該 skip。