[infra P2] SKILL.md↔helper integration test layer for /idd-edit (gap exposed by #154 R1/R2)

[kiki830621]

Problem

Source: surfaced during /idd-verify --pr 159 Round 2 (M-R2-4 + DA Probe 7 + Codex Bug 3 — independently flagged by 3 reviewers)

/idd-edit skill has 19→23 test fixtures (R1→R3 series of #154) but all fixtures invoke the helper script directly, bypassing the SKILL.md orchestration layer. The integration layer between SKILL.md (prose bash for AI to follow) and idd-edit-helper.sh (extracted parser/validator) has zero test coverage.

Evidence

R2 verify findings that originated in SKILL.md↔helper integration layer (NOT helper standalone):

• R1 B1: $APPEND_BODY undefined — SKILL.md heredoc used wrong variable name vs helper's BODY_INPUT export. Fixtures didn't catch (helper alone is fine; integration was broken).
• R1 B2: $REPO vs $GITHUB_REPO — same pattern. Helper exports REPO; SKILL.md Step 6/7 referenced undefined GITHUB_REPO.
• R2 H7: SKILL.md Step 1 for-loop closed BEFORE Steps 1.5-7 → batch mode silently processed only LAST target. Pure SKILL.md prose structure bug; helper has nothing to do with it.

All 3 were "silently passing tests, broken in production" failures. The fixture gap is structural — current fixtures test helper in isolation, but the actual user-facing surface is helper-through-SKILL.md.

Open questions

1. What's the test layer? SKILL.md is prose for AI to follow, not executable bash. Options:

   • (a) Extract SKILL.md orchestration into sourceable idd-edit-orchestrate.sh that AI invokes; helper subcommands become its primitives. Fixture tests orchestrate end-to-end with mock gh.
   • (b) Generate runnable bash from SKILL.md prose (parse fenced bash blocks, dry-run them with mocked gh/git).
   • (c) Property-based testing: spec the expected variable bindings + invariants; static check SKILL.md prose against spec.
   • (d) Live integration: a "smoke test" that runs /idd-edit end-to-end via Claude Code automation against a test repo. Most accurate but heaviest infrastructure.

2. Which variables are part of the SKILL.md↔helper contract?

   • Helper exports: MODE / SCOPE_FLAG / SECTION_FLAG / REASON / BODY_INPUT / BODY_FILE / REPO / CWD / LAST / OVERRIDE_USER_CONTENT / TARGETS / RESOLVED_COMMENT_IDS
   • SKILL.md consumes: same names (must stay in sync)
   • Need a contract spec doc to prevent drift

3. Granularity:

   • Per-step integration (Step 1 → Step 1.5 → Step 2 → ...)?
   • Per-mode integration (--append / --replace / --prepend-note end-to-end)?
   • Per-flag integration?

Type

infrastructure / test framework

Priority

P2 — pattern proven 3x (R1 B1/B2 + R2 H7) and #154 still has latent integration bugs likely post-R3 since fixture gap unchanged. Until this lands, future SKILL.md edits remain vulnerable to "tests green but production broken" regression.

Trigger conditions

• Immediate: as part of [infra] IDD plugin test framework — adversarial fixtures for SKILL.md regression coverage (sister concern from #154) #156 (test framework generalization) decision OR as standalone P2 follow-up
• Or: next time SKILL.md↔helper integration breaks in production

Related

• [infra] IDD plugin test framework — adversarial fixtures for SKILL.md regression coverage (sister concern from #154) #156 — IDD plugin test framework (P2; reuse same infrastructure)
• [feature] /idd-edit runtime enforcement — proper proposal after 3-iteration bash failure (R1/R2/R3 on #153) #154 — root of R3 fix loop that exposed this gap
• [META] /idd-edit + IDD skills: bash vs alternative layer for strict flag parsing (sister concern from #154) #155 — bash vs alternative layer (orthogonal but related: if [META] /idd-edit + IDD skills: bash vs alternative layer for strict flag parsing (sister concern from #154) #155 picks Rust/Python layer, integration test pattern changes anyway)

Refs #154 #156

---

Current Status

Phase: closed
Last updated: 2026-07-06 by /idd-diagnose (via /idd-all batch drain)

Key Decisions

• Complexity = Plan（decision-heavy：4 選項架構決策）→ 移入 batch discussion list
• 推薦：(c) 靜態契約檢查先行 + (a) 觸發式升級；等使用者裁決
• Blocked on: 使用者裁決測試層形狀

[kiki830621]

Diagnosis

Type

infrastructure / test framework（決策型 — issue 自帶 3 組 open questions）

Root Cause / Analysis

Fixture gap 是結構性的：23 個 fixtures 全部直呼 idd-edit-helper.py，SKILL.md（AI 追隨的 prose bash）↔ helper 的整合層零覆蓋。三個實證 failure 分兩類：

• 變數名 drift（R1 B1 $APPEND_BODY≠BODY_INPUT、R1 B2 $REPO≠$GITHUB_REPO）— 契約兩端名稱不同步
• Prose 結構 bug（R2 H7 for-loop 提早閉合）— 純 SKILL.md 敘事結構問題

兩類的可測性不同：drift 可用靜態契約檢查（選項 c）機械抓；結構 bug 只有執行式方案（a/b/d）能抓。

四選項評估（unattended 推薦，供使用者裁決）：

選項	抓得到	成本/風險
(a) 抽 orchestrate.sh	drift + 結構	改變 plugin runtime 形狀，為所有 skill 立架構先例 — 影響最大
(b) prose 生成 bash dry-run	drift + 部分結構	SKILL.md 混 pseudocode，生成層 brittle → false confidence 風險
(c) 靜態契約檢查	drift（3 例中 2 例）	最小：spec 檔 + linter script，零 runtime 變動
(d) live smoke via automation	全部	基礎設施最重，flaky 面大

推薦：兩階段 — (c) 先行（契約 spec：helper exports 清單 ↔ SKILL.md 引用掃描，drift 類即刻鎖死；掛進 #217 的套件）；(a) 僅在結構類 bug 再犯時升級。理由：3 例中 2 例屬 drift、(c) 零架構風險；H7 類已由 R3 修復且屬低頻。

Impact

（依裁決而定）(c)：新 spec 檔 + linter + 測試；(a)：idd-edit 運行時重構 + 全 skill 先例

Strategy

• 使用者裁決測試層形狀（推薦 (c) 先行、(a) 觸發式升級）
• 裁決後實作；контract spec 覆蓋 issue 列的 12 個 helper exports

Conflict Class

D_diagnose_first → 重評為決策型；實作階段 (c) 為 A_parallel_safe。

Complexity

Plan

Layer P 命中：decision-heavy（4 valid approaches、影響 code shape 與全 plugin 測試先例）。
Unattended batch 處置：架構先例決策 → 移入 discussion list（與 #111 同理由 — AI 不單方定調 skill-authoring 架構），diagnosis 已附推薦供快速裁決。

Risks

• (c) 的靜態掃描對 prose 中非典型引用形式（heredoc 內、註解內）有 false positive/negative — spec 需定義掃描邊界

Residue

「#154 仍可能有 latent integration bugs」的全面清查不在本 issue scope — 測試層 land 後自然浮現。

Vagueness Pre-check

• V1: 3 — 目標清楚（補整合層覆蓋）但形狀四選一未定，issue 自標 open questions
• V4: 3 — 完成邊界依選項而異
• Triggered: no（max=3）

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

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

(none — 契約 spec 需求即本 issue Q2，不另開)

---

Source: /idd-all batch drain (unattended), 2026-07-06 — 移入 discussion list 待使用者裁決測試層形狀

[kiki830621]

Implementation Plan (Plan tier)

決策採納（diagnosis 推薦）：(c) contract 靜態檢查先行、(a) 觸發式升級。理由：B1/B2 class（SKILL 引用 helper 沒 emit 的變數）可被機械偵測且零 infra 成本；(a) 的 orchestrate.sh 抽取是大重構，等靜態層抓不到的 bug 出現才升級。

Files & Changes

• 新 suite scripts/tests/idd-edit-contract/test.sh（內嵌 python3 checker）：
  • EMITTED 機械導出自 helper 源碼（emit_assignment("NAME" 呼叫 + TARGETS=( array print）— helper 即 source of truth，不建第三份變數清單（反複製判準）
  • CONSUMED/DEFINED 解析 SKILL.md fenced bash blocks：大寫 $VAR/${VAR} 引用 vs block 內賦值
  • 不變量：consumed − defined − EMITTED − allowlist（環境變數如 CLAUDE_PLUGIN_ROOT/HOME）= ∅ — 即「SKILL 引用的變數必有出處」，精準覆蓋 R1 B1（$APPEND_BODY）/ B2（$GITHUB_REPO）class
  • Emit-surface freeze：helper 的 11 個 emit 名必須存在（刪 emit 破壞 SKILL 消費者 → 紅）
  • Checker 自證（RED 等價物）：內嵌 seeded-violation fixture（引用 $UNDEFINED_VAR 的壞 SKILL 片段）→ checker 必須抓到，證明偵測力非空
• SKILL.md 新 ## SKILL↔helper Contract 短節：契約機制 + 掃描邊界（只掃 fenced bash；single-quote 不展開的 false positive 用 allowlist 消化）+ 引用 suite — 不內嵌變數清單
• (a) 升級 trigger 記錄：issue 留 comment — 下次出現靜態層抓不到的 integration bug 即升級 (a)

邊界（依 diagnosis Risk）

• 掃描限 fenced ```bash blocks（heredoc 含在內 — B1 就住在 heredoc）；prose 內非典型引用不掃、明文記於 SKILL 契約節
• H7 class（loop 結構 bug）不在本層 — 既有 idd-edit suite fixture 14 的 prose 契約已覆蓋該 class；本層只鎖 variable-binding class

Out-of-scope

(a)/(b)/(d) 三形狀；#154 latent bugs 全面清查（測試層 land 後自然浮現，diagnosis Residue）。

Verification

checker 自證 fixture 必偵測 + 真 SKILL/helper 檢查 GREEN + 全 sweep 0 fail。

Tangential Observations (filed mid-plan)

none surfaced

[kiki830621]

Implementation Complete

PR: #270（idd/163-edit-contract-layer）
Commit: 8be146c
Plan: 已核准（形狀 (c) 靜態檢查先行）

Checklist

• 新 suite idd-edit-contract：EMITTED 機械導出自 helper（single source，無第三份清單）、不變量 CONSUMED − DEFINED − EMITTED − ALLOWLIST = ∅、emit-surface freeze（11 名）、checker seeded-violation 自證
• 首跑抓到 IDD_CALLER → 出處歸類（[docs] IDD_CALLER env var registry — codify allowed values + semantics (sister from #154) #161 跨 skill env 契約，allowlist 附理由；GITHUB_REPO 刻意排除 — 那正是 B2）
• SKILL 新 ## SKILL↔helper Contract 節（機制 + 掃描邊界；H7 structural class 明文留 fixture 14）
• Suite 17/17 GREEN；全 sweep 39 suites 0 fail

(a) 升級 trigger（照 plan 記錄）

下次出現靜態層抓不到的 SKILL↔helper integration bug → 升級形狀 (a)（抽 idd-edit-orchestrate.sh + end-to-end fixture with mock gh）。在那之前 (c) 是本層的完成態。

過程備註

實作途中遇 shared working-tree 競態（另一 session 開了 idd/269-comment-reply-type）— commit 一度落在對方 branch，已以 branch -f 修復自身 ref、未動對方 checked-out branch；詳見 session 報告。

[kiki830621]

Closing Summary

Problem：/idd-edit 的 23 個 fixture 全部直呼 helper、繞過 SKILL.md 編排層 — 「SKILL 引用 helper 沒 emit 的變數」的 bug 三次帶著綠燈出貨（#154 R1 B1 $APPEND_BODY、R1 B2 $GITHUB_REPO、R2 H7；3 位 reviewer 獨立標記）。

Decision（Plan 核准，2026-07-18）：形狀 (c) contract 靜態檢查先行、(a) orchestrate.sh 抽取觸發式升級。

Solution（PR #270，8be146c）：新 suite idd-edit-contract — EMITTED 機械導出自 helper 源碼（single source，不建第三份變數清單）；不變量 CONSUMED − DEFINED − EMITTED − ALLOWLIST = ∅ 封殺 unsourced-reference class；emit-surface freeze（11 名）；checker 以 seeded 三違規 fixture 自證偵測力。SKILL 新 Contract 節（機制 + 掃描邊界；H7 structural class 明文留 fixture 14）。首跑即抓到 IDD_CALLER 並逼出出處歸類（#161 env 契約 → allowlist 附理由）。

Verification：suite 17/17；merge 後 main 全 sweep 39 suites 0 fail；PR #270 review + merged。

(a) 升級 trigger（residue，已記於 IC comment）：下次出現靜態層抓不到的 integration bug 即升級。

過程備註：實作途中遇共用 working-tree 競態（並行 session 的 #269 branch）— commit 一度落錯 branch，以 branch -f 修復自身 ref、未動對方 checkout；#183 tree-lock 的教訓再次成立（本 session 的 git 操作未先 acquire lock）。

Distribution sync：v2.100.0 隨 PR #271 統一落地（該 branch 已 bump plugin.json 2.100.0 且含本案 commit 的 ancestry）— 本次 close 不另發版，避免版號雙包。

[kiki830621]

📊 For Reviewer / Collaborator

現在：/idd-edit SKILL↔helper contract 靜態層落地（形狀 c；unsourced-reference class 從此測試可偵測），PR #270 merged
Blocking：無
你該做什麼：無 — 已結案；v2.100.0 發版隨 PR #271 統一落地

last-updated by idd-close at closed, 2026-07-19