[bug] idd-diagnose Step 0.5 Clarity gate greps '### Clarity Surface' without stripping code fences → false-positive REFUSE (sister concern from #178)

[kiki830621]

Problem

idd-diagnose Step 0.5 Clarity Surface gate 用裸 grep + awk 偵測 ### Clarity Surface annotation block，未先剝除 fenced code blocks：

if echo "$BODY" | grep -q '^### Clarity Surface'; then
  BLOCK=$(echo "$BODY" | awk '/^### Clarity Surface/{flag=1; print; next} flag && /^### /{flag=0} flag')
  SURFACED_COUNT=$(echo "$BLOCK" | grep -cE '\| surfaced \|')
  ...

當 issue body 在 ``` code fence 內示意一個 Clarity Surface block（例如一個討論 clarity 機制、或記錄 audit-block 結構的 issue），裸 grep 把示意 code 當成真的 annotation block → gate 誤判 → false-positive REFUSE，擋下一個本該 PROCEED 的 diagnose。

Type

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

Repro（實證 — dogfood catch）

1. Issue body 在 code fence 內含 ### Clarity Surface（示意，非真 annotation；body 內無真 surfaced/deferred 表格列）。
2. 跑 /idd-diagnose #N。
3. Step 0.5 gate 的 grep '^### Clarity Surface' 命中 fence 內那行 → 進 refuse 分支。

實證：診斷 #178 時親自撞到——#178（本 issue 的 parent）body line 10 的 ### Clarity Surface 在 code fence（line 7–14）內，是用來示意 idd-update 吃掉 audit block 的 bug，不是真 annotation。手動數 fence 數量（奇偶）才確認是 false positive、PROCEED；但 SKILL.md 的 gate prose 不做這個剝除，較不謹慎的執行者會被誤導 refuse。

Root cause（初判）

Step 0.5 的 grep/awk 是無語意感知的結構匹配——^### Clarity Surface 在 markdown 語境下，fence 內與 fence 外意義完全不同，但裸 grep 一視同仁。這跟 #178 同屬一個 class（idd-update 用 --- 當錨、本 gate 用 ### Clarity Surface 當錨，都缺 markdown-aware 前處理）。

Suggested fix（方向，待 diagnose 確認）

在 Step 0.5 grep/awk 之前先剝除 fenced code blocks，沿用 idd-list Step 3.5（#14）已驗證的 strip_fenced_code()：

FENCE_RE = ```[\s\S]*?```      # 同 idd-list references impl
BODY_STRIPPED = strip_fenced_code(BODY)
# 之後所有 grep '^### Clarity Surface' / surfaced-row count 改用 BODY_STRIPPED

idd-list Step 3.5 早就為完全相同的 false-positive class 加了 strip_fenced_code()（PR-ref scan 把 ```bash Refs #99 ``` 誤當真 ref）——本 gate 應 reuse 同一前處理。Inline code（`### Clarity Surface`）是否也剝可比照 idd-list 決策（idd-list 選擇不剝 inline，false-positive 較罕見）。

Impact

• 檔案：plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md（Step 0.5 gate bash block）。
• 影響流程：任何 body 在 code fence 內提及 ### Clarity Surface 的 issue（討論 clarity 機制本身、記錄 IDD body 結構、或像 [bug] idd-update Step 5 'replace below ---' 會誤刪 /idd-issue body 的 audit blocks (Clarity Surface / Linked-Context Siblings) #178 這種 meta issue）會被 gate 誤擋，使用者被迫先 dismiss 一個不存在的 surfaced row 才能 diagnose。
• 跨 skill 一致性：idd-list 已解、idd-diagnose 未解 → 同一 plugin 內前處理不一致。

Source: surfaced during /idd-diagnose #178 sister concern surfacing (Step 3.6)

---

Current Status

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

Key Decisions

• Step 0.5 Clarity gate 加 BODY_SCAN fence-stripper (awk), 3 scan sites use it. Mirrors idd-list [refactor] idd-list PR body parsing: ignore #N inside fenced code blocks (sister concern from #13) #14. d2a2607, v2.78.1.
• Falsifiable test 2 fixtures PASS (fence-only PROCEED / real table REFUSE). Simple.

Scope Changes

• (none)

Blocking

• (none)

Commits

• d2a2607 fix: strip fenced code in idd-diagnose Step 0.5 Clarity gate before scanning ([bug] idd-diagnose Step 0.5 Clarity gate greps '### Clarity Surface' without stripping code fences → false-positive REFUSE (sister concern from #178) #181)

Verification

• PASS (light) — closed with full summary; distribution sync (push + reload 2.78.1) executed. Closes the naive-structural-match sister pair with [bug] idd-update Step 5 'replace below ---' 會誤刪 /idd-issue body 的 audit blocks (Clarity Surface / Linked-Context Siblings) #178.

[kiki830621]

Diagnosis

Type

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

Root Cause（confirmed）

Step 0.5 Clarity gate（source line 92-142）對 $BODY 直接跑 grep -q '^### Clarity Surface' + awk row-count，未先剝 fenced code blocks。當 issue body 在 ``` fence 內示意 Clarity Surface（討論機制、記錄結構、或 meta issue 如 #178/#181），裸 grep 把示意 code 當真 annotation → false-positive REFUSE。同 #178（idd-update --- naive anchor）的「無語意感知結構匹配」class。

Dogfood 實證：診斷 #178 時親自撞到 —— 手動數 fence 奇偶才確認是 false positive。

Impact

• 檔案：idd-diagnose/SKILL.md Step 0.5 bash block（單檔）。
• 流程：任何 body 在 fence 內提及 ### Clarity Surface 的 issue 被誤擋，要先 dismiss 不存在的 row 才能 diagnose。

Strategy

• Step 0.5 在 grep/awk 之前先剝 fenced code → BODY_SCAN，後續 3 處（line 96 gate grep、102 BLOCK awk、141 backward-compat grep）改用 BODY_SCAN。
• Bash awk fence-stripper（非 Python，因 Step 0.5 是 bash）：awk '/^[[:space:]]*```/{infence=!infence;next} !infence{print}'。對齊 idd-list Step 3.5 strip_fenced_code()（[refactor] idd-list PR body parsing: ignore #N inside fenced code blocks (sister concern from #13) #14）的語意：剝 fenced、保 inline。
• Markdown-escaping 紀律：awk regex 內的 ``` 必須維持 mid-line（行首是 BODY_SCAN=）→ 不關閉外層 ```bash fence（同 idd-list line 131-135 做法）。
• 版本 patch bump + CHANGELOG；falsifiable test：構造「fence 內有 ### Clarity Surface、無真 row」body → gate PROCEED 非 REFUSE。

Complexity

Simple

• Layer 1 未直接命中（改 bash decision logic）但落 Simple：clear root cause + 單檔 self-contained + idd-list [refactor] idd-list PR body parsing: ignore #N inside fenced code blocks (sister concern from #13) #14 現成先例可抄 + fix 已 specced。
• 非 Plan：fix 已定（非 decision-heavy）；單檔；風險低（嚴格只「少誤擋」、不改 true-positive REFUSE 行為）。
• 非 Spectra：無新對外 surface。

Risks

• awk fence-toggle 邊界：未配對的孤立 ```（body 只開不關）→ infence 卡 true、吃掉後續真 annotation。但 idd-list 同款 stripper 已驗證；且 IDD body 由 skill 產、fence 配對良好。
• True-positive 不可退化：真 annotation block（markdown table，非 fenced）必須仍被掃到 → BODY_SCAN 保留非 fenced 內容，table 不受影響。

Residue

(none) — 完全可 operationalize：falsifiable test 明確（fence 內 row → PROCEED）。

Next: /idd-implement #181

[kiki830621]

Implementation Complete

Checklist (synced from TaskList)

• idd-diagnose/SKILL.md Step 0.5 — 加 BODY_SCAN（awk fence-stripper）+ 3 處改用（gate grep / BLOCK awk / backward-compat grep）→ d2a2607
• Markdown-escaping 紀律 — awk regex 內 ``` 維持 mid-line（行首 BODY_SCAN=），不關閉外層 ```bash fence（同 idd-list [refactor] idd-list PR body parsing: ignore #N inside fenced code blocks (sister concern from #13) #14 做法）
• 版本 2.78.0 → 2.78.1 + CHANGELOG ### Fixed → d2a2607
• falsifiable test — 兩 fixture 全 PASS（見 Verification）

idd-close 會 refuse 關任何 checklist 還有 - [ ] 的 issue。

Changes

• d2a2607: fix — strip fenced code in idd-diagnose Step 0.5 Clarity gate before scanning ([bug] idd-diagnose Step 0.5 Clarity gate greps '### Clarity Surface' without stripping code fences → false-positive REFUSE (sister concern from #178) #181)

Files Changed

 .claude-plugin/marketplace.json                     |  2 +-
 plugins/issue-driven-dev/.claude-plugin/plugin.json |  2 +-
 plugins/issue-driven-dev/CHANGELOG.md               |  6 ++++++
 plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md| 20 ++++++++++++++-----

Verification — falsifiable test (2 fixtures, both PASS)

直接跑 SKILL.md 的 awk fence-stripper：

• ✅ Fixture A（### Clarity Surface 只在 ``` fence 內，[bug] idd-update Step 5 'replace below ---' 會誤刪 /idd-issue body 的 audit blocks (Clarity Surface / Linked-Context Siblings) #178/[bug] idd-diagnose Step 0.5 Clarity gate greps '### Clarity Surface' without stripping code fences → false-positive REFUSE (sister concern from #178) #181 case）→ BODY_SCAN 0 個 ^### Clarity Surface + 0 假 row → gate PROCEED（false-positive 修掉）。
• ✅ Fixture B（真 annotation markdown table，非 fenced）→ BODY_SCAN 保留 ### Clarity Surface + surfaced row → gate REFUSE（true-positive 不退化）。

fix 正確區分「fence 示意」vs「真 annotation」，零 regression。

Scope Compliance

僅 idd-diagnose/SKILL.md Step 0.5 + 版本檔，全對應 strategy。嚴格只「少誤擋」、未改 true-positive REFUSE 行為。無 scope creep。

Distribution note

plugin SKILL.md 行為變更 → /idd-close Step 6.5 push + marketplace reload（2.78.1）。

Next: verification pending

[kiki830621]

Verify (PASS) — light

Mode: light（單檔 bash decision-logic fix，falsifiable test 已綠 → full ensemble dead weight）。Diff: d2a2607（idd-diagnose Step 0.5 + 版本檔）。

Acceptance

• ✅ Falsifiable test 兩 fixture：Fixture A（fence-only → PROCEED，假 row 剝掉）+ Fixture B（真 table → REFUSE，true-positive 保留）。
• ✅ Markdown 完整性：awk 內 ``` mid-line，未提早關閉 Step 0.5 的 ```bash fence（同 idd-list [refactor] idd-list PR body parsing: ignore #N inside fenced code blocks (sister concern from #13) #14）。
• ✅ Scope：3 處 scan（gate grep / BLOCK awk / backward-compat grep）一致改 BODY_SCAN；未動 REFUSE 訊息 / deferred 計數 / unattended 邏輯。
• ✅ JSON 雙檔 valid、3 檔版本一致 2.78.1。

Adversarial check — 孤立 fence 邊界

未配對 ```（body 只開不關）→ awk infence 卡 true、吃掉後續真 annotation。但：(a) IDD body 由 skill 產、fence 配對良好；(b) idd-list 同款 stripper 已產線驗證；(c) 退化方向是「PROCEED 而非誤 REFUSE」—— 對 gate 而言是 fail-soft（少擋）非 fail-dangerous。可接受。

Findings

無 blocking、無 non-blocking。

Result: PASS — fence-strip 正確區分示意 vs 真 annotation，true-positive 不退化，零 scope creep。同 #178 naive-structural-match class 收斂。

Next: /idd-close #181

[kiki830621]

Closing Summary

Problem

idd-diagnose Step 0.5 Clarity gate 對 raw issue body 直接 grep '^### Clarity Surface' + 數 | surfaced | row，未先剝 fenced code。當 ### Clarity Surface 只出現在 ``` fence 內（issue 在示意/記錄 annotation 格式，而非真帶 annotation block）→ false-positive REFUSE。

Root Cause

無語意感知的結構匹配 —— ^### Clarity Surface 在 markdown 語境下 fence 內外意義不同，但裸 grep 一視同仁。同 #178（idd-update --- naive anchor）的 class。Dogfood 實證：診斷 #178 時親自撞到（其 body 在 fence 內示意該格式）。

Solution

d2a2607：Step 0.5 在 grep/awk 前先剝 fenced code → BODY_SCAN（小 awk：toggle in/out fence，只印 out-of-fence 行），後續 3 處 scan 改用之。對齊 idd-list Step 3.5 strip_fenced_code()（#14）：剝 fenced、保 inline。awk 內 ``` 維持 mid-line 以免關閉外層 markdown fence。版本 2.78.0 → 2.78.1。

Verification

Falsifiable test 兩 fixture 全 PASS：(A) fence-only ### Clarity Surface → PROCEED（假 row 剝掉）；(B) 真 annotation markdown table → 仍 REFUSE（true-positive 不退化）。

Changes

• d2a2607: fix — strip fenced code in idd-diagnose Step 0.5 Clarity gate before scanning ([bug] idd-diagnose Step 0.5 Clarity gate greps '### Clarity Surface' without stripping code fences → false-positive REFUSE (sister concern from #178) #181)

Follow-ups / Residue

• (none) — 純機械 fence-strip，falsifiable test 明確。
• Class 收斂：[bug] idd-update Step 5 'replace below ---' 會誤刪 /idd-issue body 的 audit blocks (Clarity Surface / Linked-Context Siblings) #178（idd-update --- anchor）+ [bug] idd-diagnose Step 0.5 Clarity gate greps '### Clarity Surface' without stripping code fences → false-positive REFUSE (sister concern from #178) #181（gate ### Clarity Surface grep）這對「naive-structural-match without semantic awareness」sister bug 至此都修；idd-list [refactor] idd-list PR body parsing: ignore #N inside fenced code blocks (sister concern from #13) #14 是 prior art。