[bug] idd-update Step 5 'replace below ---' 會誤刪 /idd-issue body 的 audit blocks (Clarity Surface / Linked-Context Siblings)

[kiki830621]

Problem

idd-update Step 5 描述 managed-zone 的方式是「將原始 body 的 --- 分隔線（含）以下替換為新的 Current Status」。這個規則錨在 第一個 ---，假設「--- 以下 == Current Status managed zone」。

但 /idd-issue 產出的 body（尤其 parking-lot seed）在第一個 --- 以下放的是 audit blocks，不是 Current Status：

[original record: Problem / Type / ...]
---
### Clarity Surface
| ... | surfaced/resolved |
### Linked-Context Siblings Filed
(...)

照 Step 5 字面「replace below first ---」執行 → 靜默刪掉 Clarity Surface + Linked-Context Siblings audit blocks。這是 silent data loss：clarity 解析、linked-context 紀錄全沒了，且 caller 收到的只有「✓ status updated」，不會發現 audit 被吃掉。

Repro

1. 任何用 /idd-issue 建的 issue，body 在 --- 下有 ### Clarity Surface（無 ## Current Status）。
2. 跑 /idd-update #N（或被 idd-diagnose Step 5 自動呼叫）。
3. 若照 Step 5 字面 replace-below---- → audit blocks 消失。

實證：本 issue 由 /idd-diagnose #164 的 Step 5 自動呼叫 idd-update 時撞到（#164 body 在 --- 下有剛 resolve 的 Clarity Surface）。當下手動改走 append 分支才沒刪到，但 skill text 會誤導較不謹慎的執行者。

Type

bug（spec gap / footgun in published skill）

Root cause（初判）

Step 5 的兩個分支沒涵蓋「有 --- 但 --- 下不是 Current Status」這個 case：

• branch 1：有 --- + Current Status → replace below ---
• branch 2：無 --- 且無 Current Status → append
• 未涵蓋：有 ---、下方是 audit blocks、無 ## Current Status → 字面落入 branch 1 → 誤刪

Suggested fix（方向，待 diagnose 確認）

把 managed zone 錨在 ## Current Status heading 而非第一個 ---：

• 若 body 含 ## Current Status → 從該 heading（含其上緊鄰的 ---，若有）到 body 結尾替換。
• 若 body 無 ## Current Status → append 到結尾（保留所有既有內容，不論有幾個 ---）。

--- 在 IDD body 裡語意不唯一（既分隔 original/audit，也可能分隔 audit/status），不能當 managed-zone 的唯一錨。

Impact

• 影響的 skill：idd-update（被 idd-diagnose / idd-plan / idd-implement / idd-verify / idd-close 的 Step N Auto-Update 自動呼叫 → blast radius 大）。
• 影響的 issue 類型：所有 /idd-issue 產的、--- 下有 audit blocks 而無 Current Status 的 body（parking-lot seeds、含 Clarity Surface / Linked-Context Siblings 的 issue）。

Source: surfaced during /idd-diagnose #164 Step 5 (idd-update auto-call) — dogfood catch on plugin's own repo

---

Current Status

Phase: closed
Last updated: 2026-06-01 by idd-close

Key Decisions

• RCA: idd-update Step 5 anchored managed-zone on first ---, not ## Current Status heading. Fixed all 4 prose spots (Branch A replace-from-heading / Branch B append-preserve-all). Strictly backward-safe. 66ac7b9, v2.77.2.
• Verify: light (prose-only) PASS — dogfood ×4 on this issue's own body (diagnose B / implement A / verify A / close A).

Scope Changes

• (none)

Blocking

• (none)

Related

• Sister bug [bug] idd-diagnose Step 0.5 Clarity gate greps '### Clarity Surface' without stripping code fences → false-positive REFUSE (sister concern from #178) #181 filed (idd-diagnose Step 0.5 same naive-grep class).

Commits

• 66ac7b9 fix: anchor idd-update managed-zone on ## Current Status heading not first --- ([bug] idd-update Step 5 'replace below ---' 會誤刪 /idd-issue body 的 audit blocks (Clarity Surface / Linked-Context Siblings) #178); bump 2.77.1 → 2.77.2

Verification

• PASS (light) — closed with full closing summary; distribution sync (push + marketplace reload 2.77.2) executed.

[kiki830621]

Diagnosis

Type

bug（spec gap / footgun in published skill — idd-update SKILL.md）

Root Cause（confirmed against cached plugin v2.75.1）

idd-update/SKILL.md Step 5（line 187–189）把 managed-zone 錨在 第一個 ---：

line 187: 將原始 body 的 --- 分隔線（含）以下替換為新的 Current Status。
line 189: 如果原始 body 沒有 --- 分隔線和 Current Status 區塊，在 body 尾部新增。

兩個分支（has---- → replace / no---- → append）漏掉第三 case：有 ---、其下是 audit blocks（### Clarity Surface / ### Linked-Context Siblings）、無 ## Current Status → 字面落入 branch 1 → 靜默刪掉 audit blocks。caller 只收到「✓ status updated」，不會發現 audit 被吃。

關鍵新證據 — skill 自相矛盾：同一份 SKILL.md 的 Step 0 bootstrap task（line 90）早已宣告正確錨點：

TaskCreate(name="update_body", description="... (category: bounded-section-replace, scope: "## Current Status")")

scope: "## Current Status"（對齊 rules/append-vs-modify.md 的 bounded-section-replace category）才是正確意圖——但它自己的 prose（「替換 --- 以下內容」）與 line 187 Step 5 prose、line 67 設計段（「--- 以上=永遠不改，以下=每次重寫」）、line 246 鐵律（「永遠不改 --- 以上」）全部仍錨在 ---。所以這不是「設計錯」，是 prose 沒跟上自己已宣告的 ## Current Status scope——4 處 ----anchored 文字 vs 1 處正確的 category annotation。

--- 在 IDD body 裡語意不唯一（既分隔 original/audit，也分隔 audit/status），本就不能當 managed-zone 的唯一錨。

Impact

• 檔案：plugins/issue-driven-dev/skills/idd-update/SKILL.md（4 處需對齊：line 67 設計段、line 90 Step 0 task prose、line 187–189 Step 5、line 246 鐵律）
• Blast radius 大：idd-update 被 idd-diagnose / idd-plan / idd-implement / idd-verify / idd-close 的 Step N Auto-Update 自動呼叫。
• 受影響 body：所有 /idd-issue 產的、--- 下有 audit blocks 而無 Current Status 的 body（parking-lot seeds、含 Clarity Surface / Linked-Context Siblings 者）。

Strategy

• 重寫 Step 5（line 187–189）為 ## Current Status heading 錨定的 3-branch 邏輯：
  • 有 ## Current Status → 從該 heading（含其上緊鄰的 ---，若有）到 body 結尾替換；
  • 無 ## Current Status → append 到結尾，保留所有既有內容（不論有幾個 ---）。
• 對齊 line 67 設計段、line 90 Step 0 task prose、line 246 鐵律 → 一致改用「## Current Status managed zone」語言（不再用「--- 以上/以下」當邊界）。
• 不改 line 90 的 (category: bounded-section-replace, scope: "## Current Status") annotation —— 它本來就對，是其餘 prose 要向它對齊。

Complexity

Simple

• Layer 1 未命中（非 narrative；改 SKILL.md decision logic = behavior fix）但落在 Simple：clear root cause + self-contained 單檔（idd-update/SKILL.md）+ body 已釘死 fix + 遵循既有 append-vs-modify contract（無新抽象、無新對外 surface）。
• Layer 2 未滿足：不暴露新 published API 給 future callers——是把既有 prose 對齊既有 append-vs-modify.md contract，非 freeze 新 contract。
• Layer P 未命中：單檔、fix 已指定（非 decision-heavy）；backward-compat 嚴格更安全（見 Risks），非 risk-sensitive 兩難。
• Blast radius 大是 impact 不是 complexity——fix 本身 bounded，verify 階段確認等價性即可。

Risks

• Backward-compat（核心）：既有「--- 緊鄰 ## Current Status」的 body，新 heading-anchor 與舊 ----anchor 產出同結果（替換同一段）。只有「多個 ---、audit 在中間」的 body 行為改變——而那正是 bug 要修的（舊邏輯誤刪、新邏輯保留）。故 fix strictly safer：只會保留更多、不會刪更多。
• Edge：body 有 ## Current Status 但其上無 ---（理論上不會發生，因 Step 4 line 164–166 寫入時固定加 ---\n\n## Current Status）；replace 時錨 heading 仍正確。

Residue

(none) — 完全可 operationalize：錨點語意明確、3-branch 窮舉、backward-compat 可驗。

---

RCA 對照 cached plugin 2.75.1/skills/idd-update/SKILL.md。Dogfood origin：本 issue 由 /idd-diagnose #164 Step 5 auto-call idd-update 時撞到。### Vagueness Pre-check (Layer V)

• V1 (vague WHAT): 1 — body line 37–44 釘死修法（錨 ## Current Status heading + 3-branch 窮舉），等同「把 line 187–189 改成 X」級別的明確。
• V4 (vague ACCEPTANCE): 2 — Repro（body line 18–22）給可證偽驗收：構造「--- 下有 audit blocks 無 Current Status」body → 跑 idd-update → audit blocks 保留。
• Triggered: no — 兩軸皆 ≤ 3（max=2）。Routing 進 Layer 2/3/P 評估，判定 Simple。### Sister Concerns Filed (mid-diagnose, v2.47.0+ #528)

Filed: #181 — idd-diagnose Step 0.5 Clarity gate greps ### Clarity Surface without stripping code fences (same naive-structural-match class as this issue; idd-list #14 already solved it via strip_fenced_code()). Surfaced when this very diagnosis's gate check false-matched #178's in-fence illustration.

[kiki830621]

Implementation Plan

Path: direct-commit（pr_policy=ask，但本 repo 是 marketplace 本體、solo；沿用本 session #152 的 direct-commit 模式）。單一概念性修復（managed-zone 錨點 --- → ## Current Status heading）套用到 SKILL.md 4 處 + 版本傳播。

• idd-update/SKILL.md line 67（設計段）— managed zone 錨在 ## Current Status heading，加 [bug] idd-update Step 5 'replace below ---' 會誤刪 /idd-issue body 的 audit blocks (Clarity Surface / Linked-Context Siblings) #178 footgun 註記
• idd-update/SKILL.md line 90（Step 0 task prose）— 對齊 heading-anchor（保留已正確的 scope:"## Current Status" category annotation）
• idd-update/SKILL.md line 185–189（Step 5 — 核心）— 改寫成 heading-anchored 2-branch（A: 有 Current Status → 從 heading 含其上緊鄰 --- 替換；B: 無 → append 保留全部）+ [bug] idd-update Step 5 'replace below ---' 會誤刪 /idd-issue body 的 audit blocks (Clarity Surface / Linked-Context Siblings) #178 rationale + backward-compat 說明
• idd-update/SKILL.md line 246（鐵律）— 「不改 --- 以上」→「不改 ## Current Status managed zone 以外」
• 版本傳播：plugin.json + marketplace.json 2.77.1 → 2.77.2（patch；bug fix）+ CHANGELOG entry
• 結構一致性驗收：grep 確認 SKILL.md 無殘留「第一個 --- / --- 以下」當 managed-zone 錨的語言

驗收（prose deliverable，無 unit test）

SKILL.md 是 Claude 執行的 skill 指令、非可執行 script → 無 formal test。驗收 = (a) 4 處一致 heading-anchored、(b) 結構 grep 無殘留 ----anchor、(c) idd-verify ensemble 讀 prose 確認邏輯正確 + backward-compat 成立。

Scope

僅 idd-update/SKILL.md + 版本檔。不動 #181（sister bug，獨立處理）。

[kiki830621]

Implementation Complete

Checklist (synced from TaskList)

• idd-update/SKILL.md line 67 設計段 — managed zone 錨 ## Current Status heading + [bug] idd-update Step 5 'replace below ---' 會誤刪 /idd-issue body 的 audit blocks (Clarity Surface / Linked-Context Siblings) #178 footgun 警語 → 66ac7b9
• idd-update/SKILL.md line 90 Step 0 task prose — 對齊 heading-anchor（保留已正確的 scope:"## Current Status" annotation）→ 66ac7b9
• idd-update/SKILL.md Step 5（核心）— heading-anchored 2-branch（A: replace-from-heading 含緊鄰 --- / B: append-preserve-all）+ [bug] idd-update Step 5 'replace below ---' 會誤刪 /idd-issue body 的 audit blocks (Clarity Surface / Linked-Context Siblings) #178 rationale + backward-compat → 66ac7b9
• idd-update/SKILL.md 鐵律 — 「不改 --- 以上」→「不改 ## Current Status managed zone 以外」→ 66ac7b9
• 版本傳播 plugin.json + marketplace.json 2.77.1 → 2.77.2 + CHANGELOG ### Fixed entry → 66ac7b9
• 結構一致性驗收 — grep：0 殘留 affirmative --- anchor、7 處 heading-anchor 標記、JSON 雙檔合法

Legend: - [x] done · - [~] skipped · - [-] won't fix
idd-close 會 refuse 關任何 checklist 還有 - [ ] 的 issue。

Changes

• 66ac7b9: fix — anchor idd-update managed-zone on ## Current Status heading not first --- ([bug] idd-update Step 5 'replace below ---' 會誤刪 /idd-issue body 的 audit blocks (Clarity Surface / Linked-Context Siblings) #178)

Files Changed

 .claude-plugin/marketplace.json                     |  2 +-
 plugins/issue-driven-dev/.claude-plugin/plugin.json |  2 +-
 plugins/issue-driven-dev/CHANGELOG.md               |  7 +++++++
 plugins/issue-driven-dev/skills/idd-update/SKILL.md | 18 +++++++++++++-----

Verification（prose deliverable — 無 unit test）

SKILL.md 是 Claude 執行的 skill 指令、非可執行 script → 無 formal test。靜態驗收三項全綠：(a) 4 處一致 heading-anchored；(b) grep 確認 0 殘留「第一個 --- / --- 以下」當 managed-zone 錨；(c) JSON 雙檔 jq empty valid。行為等價性（backward-compat + audit 保留）留待 /idd-verify ensemble 讀 prose 確認。

Sister Bugs Filed (mid-impl, v2.44.0+ #526)

本 implement 階段無新 sister bug。#181（idd-diagnose Step 0.5 同 naive-grep class）已於 diagnose 階段 Step 3.6 file，不重複。

Scope Compliance

僅動 idd-update/SKILL.md + 3 個版本檔，全部對應 #178 strategy。無 scope creep。未動 #181（獨立 issue）。

Distribution note

此為 plugin SKILL.md 行為變更 → marketplace reload 需在 /idd-close Step 6.5 distribution-sync 執行（marketplace.json 已 bump 2.77.2；cached runtime 仍 2.75.1，reload 後生效）。

Next: verification pending

[kiki830621]

Verify (PASS) — light

Mode: light verify（prose-only SKILL.md 改動、無 code/test → full 6-AI ensemble 為 dead weight，per Layer 1 + #152 先例）。Diff scope: 4 檔（idd-update/SKILL.md +18/-7 + 3 版本檔）。

Acceptance（靜態三項，全綠）

• ✅ (a) 4 處一致 heading-anchored：grep 0 殘留 affirmative ----anchor 語句；7 處 heading-anchor 標記（line 67 設計段 / 90 Step 0 task / Step 5 Branch A+B / 鐵律）。
• ✅ (b) JSON 雙檔合法：jq empty plugin.json + marketplace.json 皆 valid。
• ✅ (c) 版本一致：plugin.json = marketplace.json = CHANGELOG = 2.77.2。

Adversarial check — backward-compat（唯一有風險的宣稱）

逐 case 驗 Branch A/B vs 舊「replace below first ---（含）」：

• Common case（body = original + 1 個 --- + Current Status）：舊邏輯從該 ---（含）到尾替換；新 Branch A 從 Current Status heading 含緊鄰 --- 到尾替換 → 同一 span，結果等價 ✅。
• Bug case 1（parking-lot seed：--- 下是 audit、無 Current Status）：舊邏輯刪 audit；新 Branch B append 保全部 → FIXED ✅。
• Bug case 2（多 ---、audit 夾在 first---- 與 Current Status 之間）：舊邏輯從 first --- 砍掉 audit；新 Branch A 錨 Current Status heading 保上方 audit → FIXED ✅。

結論：fix strictly safer —— 只保留更多、永不刪更多。無 case 產生 regression。

Executable proof — dogfood ×2（本 issue 自己的 body）

#178 body 自身含 fence 內 ^---（line 9），正是 bug 觸發條件。本 session 對 #178 跑了兩次 idd-update，兩次都實測到新邏輯：

• diagnose 階段 → Branch B：[bug] idd-update Step 5 'replace below ---' 會誤刪 /idd-issue body 的 audit blocks (Clarity Surface / Linked-Context Siblings) #178 當時無 Current Status → append，diff 證實原 52 行逐字不變（含 fence 內 ---）。
• implement 階段 → Branch A：[bug] idd-update Step 5 'replace below ---' 會誤刪 /idd-issue body 的 audit blocks (Clarity Surface / Linked-Context Siblings) #178 已有 Current Status + 多 --- → 錨 heading replace，diff 證實只動 Current Status 區（53–78 行），上方原始記錄 + fence 內容全保留。

兩 branch 都在真實 body 上正確執行 = 比 unit test 更強的行為證明（plugin 自身 repo dogfood）。

Scope creep

無。僅 idd-update/SKILL.md + 3 版本檔，全對應 strategy。#181（sister bug）獨立、未在本 commit 觸碰。

Findings

無 blocking。無 non-blocking。

Result: PASS — 4 spots 一致 heading-anchored、backward-compat 逐 case 成立、dogfood ×2 實證、零 scope creep。

Next: /idd-close #178

[kiki830621]

Closing Summary

Problem

idd-update Step 5 把 managed-zone 錨在第一個 ---。但 /idd-issue parking-lot seed 在第一個 --- 下放的是 audit blocks（### Clarity Surface / ### Linked-Context Siblings）而非 Current Status —— 照字面「replace below first ---」執行會靜默刪掉這些 audit，caller 只看到「✓ status updated」。被 idd-diagnose / idd-plan / idd-implement / idd-verify / idd-close 的 Step N Auto-Update 自動呼叫 → blast radius 大。

Root Cause

Step 5 兩分支（has---- → replace / no---- → append）漏掉第三 case：有 ---、其下是 audit、無 ## Current Status → 字面落入 replace 分支。--- 在 IDD body 語意不唯一（既分隔 original/audit，也分隔 audit/status），不能當 managed-zone 唯一錨。自相矛盾鐵證：同檔 Step 0 task（line 90）的 (category: bounded-section-replace, scope: "## Current Status") annotation 早已宣告正確錨點，但 4 處 prose（line 67/90/187–189/246）仍寫 --- —— prose 沒跟上自己宣告的 scope。

Solution

66ac7b9：把全部 4 處 prose 對齊成 ## Current Status heading 錨定：

• Branch A（有 Current Status）→ 從該 heading 含其上緊鄰 --- 到結尾替換，上方逐字保留。
• Branch B（無 Current Status）→ append 到結尾，保留所有既有內容，不論幾個 ---。
  Strictly backward-safe：common case（--- 緊鄰 Current Status）與舊邏輯等價；只有「多 ---、audit 夾中間」case 行為改變 —— 那正是修復。版本 bump 2.77.1 → 2.77.2。

Verification

Light verify（prose-only，full ensemble = dead weight per Layer 1）。靜態三項全綠（0 殘留 ----anchor、JSON valid、3 檔版本一致 2.77.2）；backward-compat 逐 case 對照成立；executable proof = dogfood ×3 on this issue's own body（#178 body 含 fence 內 ^---，正是 bug 觸發條件）：diagnose 走 Branch B（append 保 52 行）、implement 走 Branch A、verify 走 Branch A —— 三次都在真實 body 上正確執行，無一誤刪。

Changes

• 66ac7b9: fix — anchor idd-update managed-zone on ## Current Status heading not first --- ([bug] idd-update Step 5 'replace below ---' 會誤刪 /idd-issue body 的 audit blocks (Clarity Surface / Linked-Context Siblings) #178); idd-update/SKILL.md 4 spots + plugin.json/marketplace.json/CHANGELOG 2.77.2

Follow-ups / Residue

• Sister bug [bug] idd-diagnose Step 0.5 Clarity gate greps '### Clarity Surface' without stripping code fences → false-positive REFUSE (sister concern from #178) #181（idd-diagnose Step 0.5 clarity gate 同 naive-grep class，未剝 code fence）已 file，獨立處理。
• Distribution sync：plugin SKILL.md 行為變更 → push + marketplace reload（2.77.2）隨本 close 執行。