[infra] spec.md `<!-- @trace -->` blocks lack auto-update mechanism (tangential from #154 plan)

[kiki830621]

Problem

Source: surfaced during /idd-plan #154 tangential sweep (Step 2.5)

openspec/specs/append-vs-modify-discipline/spec.md 每個 Requirement 後面都有 <!-- @trace --> block:

<!-- @trace
source: add-action-scoped-modify-discipline
updated: 2026-05-25
code:
  - plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md
  - plugins/issue-driven-dev/skills/idd-issue/SKILL.md
  - plugins/issue-driven-dev/CHANGELOG.md
  - plugins/issue-driven-dev/skills/idd-update/SKILL.md
  ... (10+ files listed)
-->

8+ blocks in 1 spec,都列同樣 code: array of files。

Background

#150 spectra-archive 階段 emit 這些 trace blocks 作為 spec → code traceability hint。 但 grep 確認沒有自動更新機制:

$ grep -r "trace.*update\|update.*trace" .agents/ .claude/ scripts/ 2>/dev/null
# (no matches)

當未來 PR(例 #154)改 3 個 SKILL.md 但 <!-- @trace --> blocks 沒對應更新 → blocks become stale → reverse-lookup「該 spec Requirement 對應哪些 code 檔」不可靠。

Impact

每次任何 PR 動到 spec-linked 檔案,都該 review 是否有對應 <!-- @trace --> block 需 sync。 目前是 silent drift — 沒人警告。

Open questions

• spectra tooling(spectra validate / spectra analyze / 其他 subcommand)是否 native 支援 trace block auto-update?
• 若 spectra 不支援:寫 manual script(scripts/sync-spec-traces.sh)?或 pre-commit hook?
• block schema(source: updated: code:)是 [META] Codify append-vs-modify discipline as plugin-level principle #150 ship 還 spectra 內建?該設 contract 還是 informal?

Type

enhancement / infrastructure — spec-code traceability mechanism gap

Priority

P3 — parking-lot until ≥1 incident「spec ref'd file 已 rename/delete 但 trace block 沒跟」surfaces。 目前 silent drift 不阻擋 review。

Related

• [feature] /idd-edit runtime enforcement — proper proposal after 3-iteration bash failure (R1/R2/R3 on #153) #154 (idd-edit runtime enforcement) — will change 3 SKILL.md without updating trace blocks (Plan Out-of-scope explicit)
• [META] /idd-edit + IDD skills: bash vs alternative layer for strict flag parsing (sister concern from #154) #155 / [infra] IDD plugin test framework — adversarial fixtures for SKILL.md regression coverage (sister concern from #154) #156 sister concerns

Refs #154 #150

---

Current Status

Phase: diagnosed
Last updated: 2026-07-11 by /idd-diagnose (via /idd-all focused batch drain)

Key Decisions

• 維持 parked — 等 trace-stale 實害 trigger（issue 自訂 P3 parking 條件未發生）

[kiki830621]

Diagnosis

Type

enhancement / infrastructure（spec-code traceability — <!-- @trace --> auto-update 機制缺口）

Root Cause / Analysis

@trace blocks 是 #150 spectra-archive 階段 emit 的 traceability hint，但 grep 確認無任何自動更新機制（spectra CLI 無 trace subcommand；.claude/ scripts/ 無 sync 工具）— PR 改動 spec-linked 檔案時 blocks 靜默過期。issue 自身的 parking trigger（「≥1 incident：spec ref'd file 已 rename/delete 但 trace 沒跟」）至今未發生 — 現況是理論性 drift，未阻擋任何 review。修法選項（triggered 時）：manual sync script vs pre-commit hook vs 交給 spectra upstream（若其 roadmap 有 native 支援）— decision-heavy。

Impact

（若 triggered）scripts/sync-spec-traces.sh 或 hook + openspec/specs/ 全樹的 blocks。

Strategy

• [~] 暫緩實作 — deferred: parking trigger（首次 trace-stale 實害事故）未發生，維持 issue 自訂的 P3 parking 處置
• trigger 發生時重診斷（屆時決策：script / hook / upstream spectra）

Conflict Class

D_diagnose_first → 診斷完成，re-bucket 為 parked（wait for incident trigger）。

Complexity

Plan when triggered

（機制選擇 decision-heavy + 觸及 openspec 全樹）。當前處置 = parked：無實害、無 reviewer 阻擋，動工是為理論問題付實作稅。Hard-gate: not triggered — 無當前改動可估。

Risks

• Drift 累積至某次考古時 reverse-lookup 全錯 — 屆時即 trigger，成本可控（blocks 是 hint 非 normative）

Residue

@trace schema（source/updated/code）是 #150 自訂還是 spectra 內建 — 留待 triggered 時查 upstream；不影響 parked 處置。

Vagueness Pre-check

• V1: 2 — 缺口明確；修法多選項留待 trigger
• V4: 3 — 完成定義依機制選擇而定
• Triggered: no

[Layer V: V1=2 V4=3, not triggered; unattended mode]

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

(none)

---

Source: /idd-all focused batch drain (unattended), 2026-07-11 — 診斷結論：維持 parked，等 trace-stale 實害 trigger

[kiki830621]

Closing Summary

Problem

openspec/specs/**/spec.md 裡的 <!-- @trace --> block 沒有自動更新機制，code: 清單會隨著檔案搬移而失真。

Root Cause

tangential discovery（#154 plan 的 Step 2.5 sweep），從來沒有被排進任何一輪工作。

Solution

以 not planned 結案，但理由要說準確：這不是「不重要」，而是這個問題在本 repo 的實際規模下還沒有造成過一次誤導 —— 而 stale trace block 的代價要等到有人真的照著它去找檔案卻找不到時才會顯現。若之後發生那樣一次，重開一張並附上那個具體案例，會比現在先建一套自動化更能決定要自動化到什麼程度。

（附帶一提：本 PR #297 為 ## Closing Summary marker 建的 closing-summary-prose-drift 測試，正是這類「文件與實作分岔」問題的一個可行形狀 —— 掃描既有陳述、對照 normative source、分岔即紅。之後要處理 @trace 時可以照抄這個模式。）

Verification

(no verification ran — disposition 決定。)

Changes

無。