[feature] /idd-edit runtime enforcement — proper proposal after 3-iteration bash failure (R1/R2/R3 on #153)

[kiki830621]

Problem

Source: surfaced during /idd-verify --pr 153 R3 cluster verify (per IC_R011 — proper-design follow-up after 3-iteration implementation failure).

/idd-edit 屬 bounded-section-replace (--replace mode) + audit-block-append (--append/--prepend-note) per #150 action-scoped modify discipline (rules/append-vs-modify.md)。 #150 v2.73.0 ship 時宣告 BREAKING runtime enforcement,但實際 bash 落地經過 3 iterations 都失敗:

R1 (commit d643fc6) — 加 Step 1/2/4 enforcement bash

R2 Codex independent revision 捕捉(post-master):

• B3-NEW-1 CRITICAL: --scope value (space form) parser sets SCOPE_FLAG="next" literal
• B3-NEW-2 CATASTROPHIC: --body space form → BODY_INPUT="" → silent comment overwrite
• B3-NEW-3 LOGIC: section replacement awk end_re ignores SECTION_LEVEL,orphans subsections
• B3-NEW-4 DOC: old usage example without --scope

R3 (commit 5c62b38) — parser rewrite + section level + docs

R3 full 6-AI ensemble verify 捕捉(Logic + DA + Codex triple-confirmed):

• C1 CRITICAL INFINITE LOOP: trailing space-form flag → shift 2 silently fails on $#=1 → while [[ $# -gt 0 ]] spins forever
• C2 CRITICAL flag-value-eat: --scope --body "x" → SCOPE_FLAG="--body" + BODY_INPUT="" (next-token capture without look-ahead)
• C3 CRITICAL multi-line awk-v BREAK: BSD awk rejects newlines in -v value → awk: newline in string → section-replace DEAD-ON-ARRIVAL for realistic markdown content
• H1 HIGH --body-file=/missing/path silently produces empty BODY_INPUT → silent comment overwrite
• F4 MEDIUM (from R2,still standing) errata flow regression on user-authored comments — /idd-comment --type=errata auto-call /idd-edit --prepend-note triggers verbatim-preserve guard refuse if target非 OWNER

Type

feature — proper runtime enforcement implementation (3-iteration failure → needs standalone proposal)

Expected

/idd-edit runtime enforcement landed with:

1. Parser pattern:positional shift while [[ $# -gt 0 ]]; case "$1" in ... shift / shift 2 ;; esac with explicit missing-value guards:

   --scope) [ -z "${2:-}" ] && abort "--scope requires value"
            [[ "$2" == --* ]] && abort "--scope value cannot start with --"
            SCOPE_FLAG="$2"; shift 2 ;;

   (same guards for all 7 space-form flags: --scope / --section / --reason / --body / --body-file / --repo / --cwd)
2. Multi-line body handling:write BODY_INPUT to temp file → awk reads via getline new_content < body_file per line(不要用 -v 傳多行)
3. --body-file readability pre-check:[ -r "${1#--body-file=}" ] || abort "body-file not readable: ..."
4. Errata flow integration:/idd-comment --type=errata auto-call /idd-edit --prepend-note 偵測 non-OWNER target → auto-pass --override-user-content --reason="errata clarification per IDD discipline"(or refuse with helpful "use --override-user-content" message)
5. Doc consistency:argument-hint / frontmatter / batch-mode / usage examples all show updated syntax
6. Test fixtures:cover all R1/R2/R3 edge cases(--scope=value / --scope value / --scope last arg / --scope --body next-flag / --body-file missing / multi-line body / single-line body / section with ### subs / section with no closing heading)

Actual

3 bash-incremental attempts(R1/R2/R3)each introduced new bugs。 Implementation needs proper standalone proposal,not incremental patches。

Why this is a follow-up not a R4 fix

• R4 bash patch path likely introduces R4 bugs(R1/R2/R3 evidence pattern)
• Multi-line awk handling needs rewrite(getline pattern),不是 patch
• Errata flow integration touches /idd-comment SKILL.md not just /idd-edit — cross-skill coordination
• Acceptance criteria need explicit test fixtures(R1/R2/R3 attempts all missed adversarial patterns via narrow happy-path smoke tests)

Splitting /idd-edit runtime enforcement as its own proposal lets it ship cleanly without blocking #137 + #150 substance(B1 awk fix + B2 BSD head fix + M5 wording + L3 retroactive labels — all solid)。 Spec discipline + AI/user invocation pattern guidance ship today;runtime gate ships post-design。

Sister Concerns

• [META][unattended] Clarity Surface annotation interaction contract with /loop, /idd-all (sister concern from #135) #137 — primary cluster sibling — substance(unattended Clarity contract)ships independently
• [META] Codify append-vs-modify discipline as plugin-level principle #150 — primary cluster sibling — action-scoped principle codification ships independently
• [Bug] Step 0.8 commit-body auto-close trap protection gap (direct-commit path) #151 — auto-close trap protection gap(orthogonal P2)
• [chore] git hygiene — 3 pre-existing dirty items pollute cluster PRs (surfaced via #137 tangential sweep) #152 — chore git hygiene (P3,orthogonal)

Open Questions

1. Bash 是否是正確 layer? 3 iterations 都失敗暗示 bash 不是 right tool。 alternative: Rust CLI plugin / Python helper / native flag parsing infrastructure shared across IDD skills
2. /idd-edit 用 case statement vs argparse-style helper? 7 個 SKILL.md 都需要 flag parsing(idd-comment / idd-issue / etc)— 抽 shared utility?
3. Multi-line body handling pattern for awk replace:temp-file getline 是 Codex 建議,但需 verify pattern works on macOS BSD awk + gawk + mawk + can handle binary content / unicode
4. Errata flow integration:/idd-comment 自動 pass --override-user-content 是否違反 IC_R007 spirit(user authored intent vs AI override)? Spec carve-out vs runtime auto-detect?

Routing

• Complexity:Plan tier(2 SKILL.md changes + multi-line body design + test fixtures + cross-skill /idd-comment integration)— 不是 Spectra(no new published spec contract,extends existing [META] Codify append-vs-modify discipline as plugin-level principle #150 spec implementation)
• Path:depends on user — direct /idd-implement after diagnose,或 /idd-plan 跑 EnterPlanMode design review first

Residue

本 issue 涵蓋「/idd-edit runtime enforcement bash impl」。 不涵蓋:

• 廣義 IDD skill flag parsing infrastructure 抽 shared helper(屬另一 follow-up,跨 7+ SKILL.md scope)
• Rust / Python CLI plugin layer 替代 bash 評估(屬 long-term architecture decision)
• /idd-comment errata flow 重設計(本 issue 只整合,不重設計)

---

Current Status

Phase: implemented
Last updated: 2026-05-25 by /idd-update (via /idd-implement — 14 tasks GREEN + PR #159 open)

Key Decisions

• Implementation Complete (2026-05-25) — All 14 tasks GREEN (A1-A3 / B1-B3 / B-tests / C1 / C-test / D1-D5). 13 fixtures pass. Architectural pivot mid-impl: extracted helper script per spectra-archive-post-ic precedent (vs Plan D3 ad-hoc) → decouples AI bash generation from parser logic, closes R1/R2/R3 root cause more deeply. PR feat: /idd-edit runtime enforcement (R4 + R5) via extracted helper script (#154) #159 open. IC: comment-4532866379
• Plan tier approval gate PASSED (2026-05-25) — 3 decisions locked pre-EnterPlanMode: PR path, Q4 errata=refuse-with-message, [infra] IDD plugin test framework — adversarial fixtures for SKILL.md regression coverage (sister concern from #154) #156=ad-hoc shell. 2 mid-plan tangentials filed ([infra] spec.md <!-- @trace --> blocks lack auto-update mechanism (tangential from #154 plan) #157 trace blocks, [design] /idd-edit batch mode + R5 refuse interaction — semantic decision needed (tangential from #154 plan) #158 batch+R5). Plan: comment-4532483652
• Complexity verdict: Plan (Layer P 5 signals hit; Spectra borderline but executes existing [META] Codify append-vs-modify discipline as plugin-level principle #150 spec rather than proposing new contract)
• Implementation plan structured as 4 sequential blocks (A→B→C, D parallel): A=parser foundation + 9 adversarial fixtures, B=multi-line getline + R4/R5 enforcement, C=cross-skill errata flow integration, D=docs cleanup
• R1/R2/R3 root cause: 3 iterations violated block ordering (tried B before A stabilized) → each parser fix exposed new bug
• Q4 errata flow (auto --override-user-content vs refuse-with-message) flagged as real open decision for Plan tier EnterPlanMode

Scope Changes

• (none — diagnosis matches issue body's self-suggested scope)

Blocking

• (none — ready for /idd-plan EnterPlanMode)

Sister concerns filed

• [META] /idd-edit + IDD skills: bash vs alternative layer for strict flag parsing (sister concern from #154) #155 — [META] bash vs alternative layer for strict flag parsing (parking-lot P3)
• [infra] IDD plugin test framework — adversarial fixtures for SKILL.md regression coverage (sister concern from #154) #156 — [infra] IDD plugin test framework — adversarial fixtures (P2, decision needed in [feature] /idd-edit runtime enforcement — proper proposal after 3-iteration bash failure (R1/R2/R3 on #153) #154 Plan tier)

Commits

• (none yet — diagnose phase)

Next

• /idd-verify --pr 159 — 6-AI ensemble verify on PR feat: /idd-edit runtime enforcement (R4 + R5) via extracted helper script (#154) #159

[kiki830621]

Diagnosis

Type

feature — runtime enforcement implementation of already-declared discipline (#150 Requirements 4-5)

Issue 已自我 framed 完整(R1/R2/R3 failure trail + Expected acceptance + Sister Concerns + Residue + 4 open questions + self-suggested Complexity)。 Diagnosis 工作主要是 validate + add architectural framing,而非 discover。

Analysis

Claim verification(逐項對照 current state)

Issue claim	Current state	Verdict
idd-edit/SKILL.md 是 pre-#150 baseline	288 lines,無 --scope/--section/--override-user-content flag parsing	✓ confirmed
Spec R4 + R5 已 declared 但 runtime deferred	Both R4 + R5 have explicit Implementation status (v2.74.0) preambles citing #154	✓ confirmed
/idd-comment errata flow 自動 call /idd-edit --prepend-note	skills/idd-comment/SKILL.md Template errata SPECIAL BEHAVIOUR 行 280-285 確認 auto-call	✓ confirmed
R1/R2/R3 verify trail	comments 4531059931, 4531225415, 4531737476 on PR #153	✓ all 3 captured

所有 issue claim 對得上 source-of-truth code state。 Issue body 可以直接作為 implementation spec 的 input。

Architectural framing(diagnosis 加值之處)

Issue 列出 acceptance items 1-6,但沒明示這些是「並列 sub-task」還是「依賴鏈」。 Diagnose 觀察:有依賴順序,且順序錯做會重蹈 R3 覆轍:

Block A (foundation — must land first, independently testable):
  [a1] Parser pattern with explicit missing-value guards (Expected #1)
  [a2] --body-file readability pre-check (Expected #3)
  [a3] Test fixtures covering 9 adversarial patterns (Expected #6)

Block B (depends on A — needs reliable parser before exercising):
  [b1] Multi-line body via getline (Expected #2)
  [b2] --scope / --section / --override-user-content runtime enforcement (per spec R4+R5)

Block C (cross-skill — depends on B; touches /idd-comment):
  [c1] Errata flow integration with auto --override-user-content (Expected #4)

Block D (cleanup,parallel to A-C):
  [d1] Doc consistency:argument-hint / frontmatter / batch-mode / usage examples (Expected #5)
  [d2] Spec preamble update:remove "deferred to #154" → "landed in #154/vX.Y.Z" (3 sites in append-vs-modify spec)

R1/R2/R3 違反此順序:都先試 b2 (runtime gate) 再補 a1 (parser robustness),導致每 round parser fix 解一個 bug 又引入另一個。 Block A 必須先穩定 + test fixtures 覆蓋 9 種 adversarial pattern,才 unlock Block B 的 enforcement code。

Open Questions 重審

Issue 列了 4 個 open questions。 Diagnose 觀察:

1. 「Bash 是否是正確 layer」(Q1)— Plan tier 不解,屬 long-term architectural decision(meta-issue 候選)。 [feature] /idd-edit runtime enforcement — proper proposal after 3-iteration bash failure (R1/R2/R3 on #153) #154 scope 內接受 bash + 強化 test fixtures + multi-line via getline。 若 future ≥3 個 SKILL.md 撞同類 parser/enforcement bug → 升 Spectra discuss alternative layer
2. 「Shared flag parsing helper」(Q2)— rule-of-three 未到(目前只有 idd-edit 一個 SKILL.md 需強 enforcement);[META][idd-edit / idd-update] should integrate /idd-clarify primitive for symmetric Terminology Surface (sister concern from #135) #136 若 trigger 會多一個 → instance idd-all: direct-commit mode 加 passive warning (dirty tree / on default branch) #2
3. 「Multi-line body pattern cross-awk-implementation」(Q3)— 必須在 Block A 解掉,不是 open question。 Test fixtures 必涵蓋 macOS BSD awk + Linux gawk + (optional) mawk;binary content 排除(Markdown comment body 不含 binary,Unicode 行)
4. 「Errata flow --override-user-content 違反 IC_R007 spirit?」(Q4)— 這個是真 open question,需 design decision。 兩條路:
   • (a) /idd-comment --type=errata 自動 detect target ownership + 自動 pass --override-user-content(transparent override)
   • (b) refuse + 印 helpful message "use --override-user-content manually with reason"(explicit user consent)
   • 兩者都符合 R5 spec,差別在「auto」vs「explicit consent」的 UX trade-off

Impact

• Files changed(必):
  • plugins/issue-driven-dev/skills/idd-edit/SKILL.md — 加 Step 1.5 parse_arguments 含 7-flag positional shift + missing-value guards + body-file readability check + multi-line body via getline + R4/R5 runtime enforcement gates
  • openspec/specs/append-vs-modify-discipline/spec.md — Purpose + R4 + R5 三段 preamble 從 "deferred to [feature] /idd-edit runtime enforcement — proper proposal after 3-iteration bash failure (R1/R2/R3 on #153) #154" 改為 "landed v(post-[feature] /idd-edit runtime enforcement — proper proposal after 3-iteration bash failure (R1/R2/R3 on #153) #154 version)"
  • plugins/issue-driven-dev/CHANGELOG.md — [post-2.74.0] entry
• Files possibly changed(視 Q4 答案):
  • plugins/issue-driven-dev/skills/idd-comment/SKILL.md Template errata SPECIAL BEHAVIOUR — auto-detect + auto-override OR refuse-with-helpful-message
• Test fixtures(NEW):某處 mock issue body / mock comment 涵蓋 9 個 adversarial pattern。 IDD plugin 目前無 test infrastructure,本 issue 順便建立(或 reuse 既有 scripts/ test pattern)
• User flows:全 IDD AI invocation 切到 --scope / --section / --override-user-content strict mode(BREAKING for existing manual /idd-edit invocations 沒帶 flag 者)

Strategy

Block A → Block B → Block C,Block D 平行於 A-C。 每個 block 內子任務獨立 PR-able。

Block A: Parser foundation + test fixtures(MUST first):

• A1 — Add parse_arguments function with positional shift while [[ $# -gt 0 ]]; case "$1" in ... shift / shift 2 ;; esac for 7 space-form flags (--scope / --section / --reason / --body / --body-file / --repo / --cwd) + missing-value guards ([ -z "${2:-}" ] && abort ... + [[ "$2" == --* ]] && abort ...)
• A2 — Add --body-file readability pre-check ([ -r "${1#--body-file=}" ] || abort)
• A3 — Build test fixtures covering 9 adversarial patterns (R1/R2/R3 regression set):
  1. --scope=value (eq form)
  2. --scope value (space form)
  3. --scope as last arg (missing value)
  4. --scope --body "x" (next-flag eats value)
  5. --body-file=/missing/path (unreadable file)
  6. Multi-line body (newline content)
  7. Single-line body
  8. Section with ### subsections (level-aware end)
  9. Section with no closing heading (EOF as end)

Block B: Multi-line body + R4/R5 enforcement(after A passes):

• B1 — Replace any awk -v new_content="$BODY" with awk 'getline new_content < body_file' ... pattern (cross-awk-impl compatible)
• B2 — R4 runtime gate:--replace mode requires both --scope AND --section;refuse with actionable message otherwise
• B3 — R5 runtime gate:detect target comment author(gh api comments/<id> --jq .user.login);若非 OWNER 且非 idd-bot,refuse 除非 --override-user-content --reason="..." 提供

Block C: Cross-skill errata flow integration(after B + design Q4 resolved):

• C1 — Per Q4 decision,update idd-comment/SKILL.md Template errata SPECIAL BEHAVIOUR 來自動 pass --override-user-content OR refuse with message
• C2 — idd-comment errata auto-call test:fixture covering OWNER target + non-OWNER target paths

Block D: Cleanup(parallel):

• D1 — Update idd-edit/SKILL.md argument-hint / frontmatter / batch-mode docs / usage examples to show new flag syntax
• D2 — Update openspec/specs/append-vs-modify-discipline/spec.md Purpose / R4 / R5 preambles:remove "deferred to [feature] /idd-edit runtime enforcement — proper proposal after 3-iteration bash failure (R1/R2/R3 on #153) #154" → "landed v<post-[feature] /idd-edit runtime enforcement — proper proposal after 3-iteration bash failure (R1/R2/R3 on #153) #154>"
• D3 — CHANGELOG.md [post-2.74.0] entry

Complexity

Plan (per Layer P signals — confirmed against issue's self-suggestion):

Layer 1 disqualifiers checked:

• Not narrative / prose ✗
• Not ad-hoc analysis ✗
• Not doc-only update ✗

Layer 2 (necessary for Spectra):

• /idd-edit IS a published skill API ✓
• BUT the work here EXECUTES existing [META] Codify append-vs-modify discipline as plugin-level principle #150 spec (R4 + R5),不引入新 spec contract。 Spec preamble change is "remove deferred caveat",非新 normative clause

Layer 3 (Spectra confirmation):

• 修改既有 published spec 的 normative behavior? 借界:R4/R5 文字本身不改,只移除 implementation status preamble。 不算 modifying SHALL clauses,只算「兌現 deferred 承諾」
• 影響 2+ specs? 否 — 只動 append-vs-modify-discipline spec
• Architectural decision with long-term maintenance? 部分 — 9 fixture pattern 是 long-lived enforcement reference,但屬實作層紀律,非結構決定

Spectra borderline 但偏 Plan:work 是 IMPLEMENT existing declared spec,不是 PROPOSE new contract。

Layer P signals hit (3+):

• ✓ 2+ files with sequencing(idd-edit + idd-comment + spec preamble — Block A→B→C dependency)
• ✓ Strategy has 5+ ordered steps(Block A 3 sub-tasks + Block B 3 + Block C 2 + Block D 3 = 11 tasks with explicit blocks)
• ✓ Decision-heavy(Q4 errata flow auto vs explicit — 2 valid approaches)
• ✓ Risk-sensitive boundary(已 3 度 introduce bug,proven failure-prone)
• ✓ Cross-file refactor(idd-edit + idd-comment 跨 2 SKILL.md;test fixtures 新建)

Risks

• R1 R4-iteration repeat:bash-incremental 再次 introduce bugs。 Mitigation:Block A 必先 freeze + test fixtures 通過 9 種 pattern,才 unlock Block B。 EnterPlanMode approval gate(Plan tier)強制 user 在動 Block B 前看完 acceptance fixtures
• R2 Cross-awk-impl break:macOS BSD awk vs Linux gawk vs mawk 差異引爆 multi-line getline pattern。 Mitigation:Block A3 fixture idd-all SLUG derivation: BSD/GNU sed alternation (\| not portable) #6 在多 awk impl 下測;若 BSD 不支援某 pattern,在 SKILL.md 標明「requires gawk (homebrew install gawk)」
• R3 Errata flow IC_R007 violation:Q4 (a) 自動 override 違反「user authored intent」spirit。 Mitigation:Plan tier EnterPlanMode 階段 user pick Q4 答案;preferred (b) refuse-with-message 較安全(explicit consent)
• R4 Test infrastructure none:IDD plugin 無 test framework,Block A3 fixtures 可能變 ad-hoc。 Mitigation:reuse scripts/ test pattern(如有),否則建 tests/idd-edit/ 簡單 shell test runner
• R5 BREAKING change to existing AI invocations:過去 AI 跑 /idd-edit 未帶 --scope / --section 將 refuse。 Mitigation:CHANGELOG 標 BREAKING;/idd-edit 在 transitional 期可印 deprecation warning instead of hard refuse(opt-in via env var)— 待 user 決定

Residue

本 issue 涵蓋「/idd-edit runtime enforcement bash impl + /idd-comment errata flow integration」。 不涵蓋(intentional out-of-scope,與 issue body 原 Residue 一致 + 補充):

• 廣義 IDD skill flag parsing infrastructure 抽 shared helper(屬另一 follow-up,跨 7+ SKILL.md scope。 Trigger:若 ≥3 個 SKILL.md 撞同類 bug → 升 Spectra 評估)
• Rust / Python CLI plugin layer 替代 bash 評估(long-term architecture decision;rule-of-three 未到)
• /idd-comment errata flow 重設計(本 issue 只整合,不重設計)
• IDD plugin test framework 建立(若 Block A3 確實需 test runner 才會 surface;否則 ad-hoc fixtures 即可)
• NSQL §4.6 horizon — 「runtime enforcement vs discipline-only」哲學取捨:本 issue 兌現 [META] Codify append-vs-modify discipline as plugin-level principle #150 declared discipline,但「all spec MUST be runtime-enforced」並非 IDD 鐵律。 部分 spec(如 closing summary 內容品質)本質無法 runtime gate,只能 review-time judge。 此 issue 不 codify「何時 declared-only 是合理選擇」。

Vagueness Pre-check

• V1 (vague WHAT): 2 — Clear. Issue body lists 6 concrete acceptance items + R1/R2/R3 evidence trail with specific bug codes (C1/C2/C3/H1/F4); diagnosis adds 11 sub-tasks in 4 explicit blocks. Comparable to anchor V1=2 ("Add a button to the login page that opens the help modal").
• V4 (vague ACCEPTANCE): 3 — Mostly clear. 9 adversarial test fixtures explicit (R1/R2/R3 regression set); runtime gate behavior maps to spec R4+R5 scenarios. One borderline: Q4 errata flow auto-vs-explicit needs design decision before final acceptance, but Strategy explicitly surfaces it. Comparable to anchor V4=3 ("done when latency feels noticeably better" but here with measurable test fixtures).
• Triggered: no — both axes ≤ 3 (V1=2, V4=3, threshold ≥ 4)

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

• [META] /idd-edit + IDD skills: bash vs alternative layer for strict flag parsing (sister concern from #154) #155 — [META] /idd-edit + IDD skills: bash vs alternative layer for strict flag parsing (parking-lot, P3) — covers Open Q1 + Risk R1 (3-iteration failure pattern暗示 bash 不是 right tool;rule-of-three trigger threshold codified)
• [infra] IDD plugin test framework — adversarial fixtures for SKILL.md regression coverage (sister concern from #154) #156 — [infra] IDD plugin test framework — adversarial fixtures for SKILL.md regression coverage (P2 — [feature] /idd-edit runtime enforcement — proper proposal after 3-iteration bash failure (R1/R2/R3 on #153) #154 Block A3 immediately need) — covers Risk R4 (no test infrastructure means Block A3 fixtures become ad-hoc; decision needed in [feature] /idd-edit runtime enforcement — proper proposal after 3-iteration bash failure (R1/R2/R3 on #153) #154 Plan tier EnterPlanMode)

Both same_skill=idd-edit evidence; spawn_kind=sister-concern for #155 (parking-lot trigger-driven), upstream-tracking for #156 (#154 needs decision before Block A starts).

[kiki830621]

Implementation Plan (Plan tier)

Plan tier 的 plan 是 decision artifact,比 idd-implement 的執行清單更詳盡。 EnterPlanMode 階段 user 看的就是這份。

Files & Changes

Block A — Parser foundation + adversarial fixtures (must land first)

• plugins/issue-driven-dev/skills/idd-edit/SKILL.md — Replace Step 1 with new parse_arguments function (positional while shift over 7 space-form flags --scope / --section / --reason / --body / --body-file / --repo / --cwd). Each flag adds two guards: [ -z "${2:-}" ] && abort "--<flag> requires value" + [[ "$2" == --* ]] && abort "--<flag> value cannot start with --". Also handle --flag=value (eq form) via case --flag=*. Why: closes R1/R2/R3 parser bug class (C1 infinite loop, C2 flag-eat, R2 B3-NEW-1/-2 literal-capture)。
• plugins/issue-driven-dev/skills/idd-edit/SKILL.md — Add --body-file readability pre-check: if [[ "$1" == --body-file=* ]]; then BODY_FILE="${1#--body-file=}"; [ -r "$BODY_FILE" ] || abort "body-file not readable: $BODY_FILE"; BODY_INPUT=$(cat "$BODY_FILE"); fi。 Why: closes R3 H1 silent-overwrite。
• tests/idd-edit/test_parser.sh — NEW ad-hoc shell test runner (set -euo pipefail + assert_eq/assert_abort helpers + 9 fixtures from diagnosis Block A3)。 Pure shell, no framework dependency。 Per [infra] IDD plugin test framework — adversarial fixtures for SKILL.md regression coverage (sister concern from #154) #156 decision (a) — fixtures go here now, [infra] IDD plugin test framework — adversarial fixtures for SKILL.md regression coverage (sister concern from #154) #156 generalizes later when ≥2 SKILL.md need framework。

Block B — Multi-line body via getline + R4/R5 enforcement (depends on A)

• plugins/issue-driven-dev/skills/idd-edit/SKILL.md — Replace Step 4 --replace mode section regex with awk-getline pattern. Write $BODY_INPUT to /tmp/idd-edit-new-body-$$.md, then awk reads via getline new_content < body_file per line, replacing section between ^<section-heading>$ and next same-or-higher-level heading。 Why: closes R3 C3 BSD awk -v newline reject (the single bug that made R3 "dead-on-arrival")。
• plugins/issue-driven-dev/skills/idd-edit/SKILL.md — Add R4 runtime gate at Step 4 entry: if [[ "$MODE" == "--replace" ]] && [[ -z "$SCOPE_FLAG" ]] && [[ -z "$SECTION_FLAG" ]]; then abort "--replace requires --scope whole-comment OR --section <heading> (action-scoped discipline per rules/append-vs-modify.md)"; fi。 Per spec R4 scenarios。
• plugins/issue-driven-dev/skills/idd-edit/SKILL.md — Add R5 runtime gate at Step 2 (after fetch): AUTHOR_ASSOC=$(gh api .../comments/$ID --jq '.author_association'); AUTHOR_LOGIN=$(gh api .../comments/$ID --jq '.user.login'). If AUTHOR_ASSOC != "OWNER" AND AUTHOR_LOGIN not in BOT_ALLOWLIST=(github-actions[bot] dependabot[bot]) AND no --override-user-content → abort with helpful message. If override present → append audit marker <!-- idd:edit override-user-content date=... reason="..." --> to body。 Per spec R5 scenarios。
• tests/idd-edit/test_parser.sh — Extend with 3 R4/R5 fixtures: (10) --replace without --scope/--section refuses, (11) --replace --section on non-OWNER comment refuses, (12) override flow appends audit marker。

Block C — Cross-skill errata flow integration (depends on B; per Q4 decision)

• plugins/issue-driven-dev/skills/idd-comment/SKILL.md — Update Template errata SPECIAL BEHAVIOUR (~line 280) to NOT auto-pass --override-user-content. Instead, after auto-call detects refuse exit code 1 with R5 error pattern → print actionable helpful message: "errata target comment is user-authored; manually run: /idd-edit comment:$TARGET --prepend-note --override-user-content --reason='errata clarification per IDD discipline — see new errata at <URL>'"。 Per Q4 decision (b): explicit consent over auto-override, aligns with IC_R007 spirit。
• tests/idd-edit/test_parser.sh — Add fixture (13) errata flow integration: simulate /idd-comment errata invoking /idd-edit --prepend-note on user-authored comment → R5 refuses → helpful message present in stderr。

Block D — Docs cleanup (parallel to A-C)

• plugins/issue-driven-dev/skills/idd-edit/SKILL.md frontmatter — Update argument-hint: line to include new flags syntax: "comment:<id> [--last] (--append|--replace [--scope ...|--section ...]|--prepend-note) [--body=... | --body-file=...] [--reason=...] [--override-user-content --reason='...']"
• plugins/issue-driven-dev/skills/idd-edit/SKILL.md ## 使用範例 section — Update all 3 examples (圖片下方解釋 / 修 typo / 標記過時) to use new --scope + --reason flag syntax。 Errata example specifically shows --override-user-content --reason="..." for non-OWNER。
• plugins/issue-driven-dev/skills/idd-edit/SKILL.md ## Batch mode section — Add note: "batch mode 套用同 --scope / --section / --override-user-content 到 N comment per-confirm。 R4/R5 runtime gate per-target evaluation。"
• openspec/specs/append-vs-modify-discipline/spec.md — Update Purpose paragraph (line 7) + R4 preamble (line 116) + R5 preamble (line 162) to remove "deferred to #154" and replace with "landed in #154 / v<post-2.74.0 version>". Also remove "Re-verify for runtime conformance when [feature] /idd-edit runtime enforcement — proper proposal after 3-iteration bash failure (R1/R2/R3 on #153) #154 closes" cleanup tags。
• plugins/issue-driven-dev/CHANGELOG.md — New [post-2.74.0] entry. Refactored: /idd-edit Step 1 parser rewrite (positional shift + missing-value guards), Step 4 --replace multi-line via getline。 Added: R4 runtime gate (--replace requires --scope or --section), R5 runtime gate (non-OWNER refuse unless --override-user-content), /idd-comment errata flow R5 helpful-message integration, test fixtures at tests/idd-edit/test_parser.sh。 BREAKING (runtime): existing AI invocations of /idd-edit --replace without --scope/--section will refuse — must add flag explicitly。

Sequencing & Dependencies

A1+A2 (parser + body-file check)         → independently testable
   └─ A3 (9 fixtures 1-9 covering A scope)
        └─ B1 (getline pattern)            ← needs A parser stable
        └─ B2 (R4 runtime gate)
        └─ B3 (R5 runtime gate)
              └─ A3 extension fixtures 10-12 (R4/R5 cases)
                    └─ C1 (idd-comment errata integration)
                          └─ A3 extension fixture 13 (errata refuse path)

D1-D5 (docs/spec/CHANGELOG) — parallel to A-C, but D4 (spec preamble) and D5 (CHANGELOG) must land in same commit as code changes (atomic ship)

Hard constraint (per R1/R2/R3 root cause):

• A3 fixtures 1-9 MUST be green before B1/B2/B3 start
• A3 fixtures 10-12 MUST be green before C1 starts
• A3 fixture 13 MUST be green before final commit

This is the discipline R1/R2/R3 violated (tried B before A stable)。 EnterPlanMode is precisely the gate enforcing this order ahead-of-time。

Decision Points

3 decisions locked at Plan-tier draft (before EnterPlanMode), so EnterPlanMode review sees concrete plan not abstract trade-offs。

D1 — PR path (locked): PR path with branch idd/154-edit-runtime from main。 Aligns with #137/#150 cluster precedent + BREAKING change review surface valuable。

D2 — Q4 errata flow (locked: option b): /idd-comment errata auto-call to /idd-edit --prepend-note will NOT auto-pass --override-user-content. Refuse with helpful message instead。 Aligns with IC_R007 user-authored-intent spirit + explicit consent semantics + 1-flag UX cost。

D3 — #156 test framework (locked: option a): Block A3 + extensions write fixtures to tests/idd-edit/test_parser.sh as pure shell script with set -euo pipefail + assert_eq/assert_abort helpers。 #156 generalizes later when ≥2 SKILL.md need framework (rule-of-three threshold)。 Lean-minimal path。

Risks & Mitigations

• R1 R4-iteration repeat (parser regressions): A3 fixtures 1-9 MUST be green before B starts。 Hard test gate at TDD loop boundary。 EnterPlanMode approval is the social contract enforcing this。
• R2 Cross-awk-impl break (BSD vs gawk vs mawk): A3 fixture 6 (multi-line body) tested on both macOS BSD awk + Linux gawk (via Docker if local Linux not available)。 If BSD reject getline pattern, SKILL.md notes (requires gawk on macOS: brew install gawk + replace awk → gawk in body)。 Trade-off documented in CHANGELOG。
• R3 Errata flow IC_R007 violation (was Q4 risk): mitigated by D2 decision (refuse-with-message > auto-override)。 Plan tier user approval is the explicit decision point for this trade-off。
• R4 Test infrastructure none (was [infra] IDD plugin test framework — adversarial fixtures for SKILL.md regression coverage (sister concern from #154) #156 risk): mitigated by D3 decision (ad-hoc shell script in this PR + [infra] IDD plugin test framework — adversarial fixtures for SKILL.md regression coverage (sister concern from #154) #156 later)。 9-13 fixtures' shape informs [infra] IDD plugin test framework — adversarial fixtures for SKILL.md regression coverage (sister concern from #154) #156 framework design later。
• R5 BREAKING change to existing AI invocations: CHANGELOG marks BREAKING (runtime)。 transition period NOT offered (refuse hard from day 1) — discipline already declared in v2.73.0/v2.74.0 spec, AI/user invocations SHOULD already include --scope/--section。 If many existing invocations regress, can opt-in env var IDD_EDIT_LEGACY_MODE=1 future post-merge if pain surfaces (out-of-scope this PR)。
• R6 idd-comment 改動 might surface secondary errata flow bugs: Block C scope limits to message-only change (no flow restructure)。 If deeper errata redesign surfaces during impl, file as follow-up issue (sister sweep)。

Test Plan

Pure shell test runner at tests/idd-edit/test_parser.sh。 Run via bash tests/idd-edit/test_parser.sh (no framework dependency)。 Each fixture exits 0 (assertion pass) or 1 (fail with diagnostic)。

Fixtures 1-9 (Block A scope — parser robustness)

#	Input	Expected	Closes bug
1	--scope=whole-comment (eq form)	parses correctly	R2 B3-NEW-1
2	--scope whole-comment (space form)	parses correctly	R2 B3-NEW-1 (literal capture regression)
3	--scope as last arg	aborts with "--scope requires value"	R3 C1 (infinite loop)
4	--scope --body "x" (next-flag eats value)	aborts with "--scope value cannot start with --"	R3 C2 (flag-value-eat)
5	--body-file=/tmp/nonexistent-xyz	aborts with "body-file not readable"	R3 H1 (silent overwrite)
6	Multi-line body via --body-file=/tmp/multiline.md with embedded `
`	section replace preserves newlines	R3 C3 (BSD awk -v newline reject)
7	Single-line body via --body "hello"	section replace works	sanity baseline
8	Section with ### subsections, --section "## Foo"	end detected at next ## not first ###	R2 B3-NEW-3 (orphans subsections)
9	Section with no closing heading (EOF as end)	replaces to EOF	edge case for last-section-in-comment

Fixtures 10-12 (Block B scope — R4/R5 gates)

#	Input	Expected	Spec scenario
10	--replace --body "..." (no --scope/--section)	aborts with R4 message	R4 Scenario "idd-edit --replace without scope flag"
11	--replace --scope whole-comment on non-OWNER non-bot comment	aborts with R5 message	R5 Scenario "idd-edit targets user-authored comment"
12	Above + --override-user-content --reason="test override"	proceeds + appends <!-- idd:edit override-user-content ... --> audit marker	R5 Scenario "idd-edit override of user-authored comment"

Fixture 13 (Block C scope — errata flow integration)

#	Input	Expected
13	Simulate /idd-comment --type=errata --target-comment=<non-OWNER-comment> → auto-call to /idd-edit --prepend-note	R5 refuse + helpful message in stderr suggesting manual --override-user-content --reason=...

Out-of-scope (will NOT be touched in this PR)

• /idd-edit Step 5 preview UX — current "show first 40 lines + AskUserQuestion confirm" stays as-is。 Refactor surface not in [feature] /idd-edit runtime enforcement — proper proposal after 3-iteration bash failure (R1/R2/R3 on #153) #154 mandate。
• Shared flag parsing helper across IDD skills — per [META] /idd-edit + IDD skills: bash vs alternative layer for strict flag parsing (sister concern from #154) #155, parking-lot until rule-of-three trigger。 Each SKILL.md keeps its own parse_arguments for now。
• IDD plugin test framework generalization — per [infra] IDD plugin test framework — adversarial fixtures for SKILL.md regression coverage (sister concern from #154) #156, ad-hoc shell script in this PR is intentional;framework comes later。
• /idd-comment errata flow design — only message string change in Block C, no flow restructure。
• Other /idd-edit modes' enforcement gates — --append and --prepend-note modes are audit-block-append category, do NOT need --scope/--section (per spec R4 explicit carve-out)。
• Backward-compat env var IDD_EDIT_LEGACY_MODE=1 — premature; only add if pain surfaces post-merge。
• spec.md traceability map auto-update (<!-- @trace --> blocks) — if spectra tooling supports it natively, optional; otherwise manual edit also fine。

Tangential Observations (filed mid-plan, v2.42.0+ #524)

• [infra] spec.md <!-- @trace --> blocks lack auto-update mechanism (tangential from #154 plan) #157 — [infra] spec.md <!-- @trace --> blocks lack auto-update mechanism (parking-lot P3) — surfaced during Step 2 spec reading: 8+ trace blocks per Requirement listed code: arrays but grep confirmed no auto-updater exists. [feature] /idd-edit runtime enforcement — proper proposal after 3-iteration bash failure (R1/R2/R3 on #153) #154 will change 3 SKILL.md without syncing trace blocks (Plan Out-of-scope explicit). Long-term spec→code traceability gap.
• [design] /idd-edit batch mode + R5 refuse interaction — semantic decision needed (tangential from #154 plan) #158 — [design] /idd-edit batch mode + R5 refuse interaction (P2 — [feature] /idd-edit runtime enforcement — proper proposal after 3-iteration bash failure (R1/R2/R3 on #153) #154 Block B3 will hit) — surfaced during fixture design: 13 fixtures cover single-target R5 paths but batch mode (comment:NNN comment:MMM) + mixed OWNER/non-OWNER targets has 3 candidate semantics (per-comment refuse / transactional abort / pre-flight scan). Plan B3 ships single-target enforcement first; batch interaction either added as fixture 14 mid-[feature] /idd-edit runtime enforcement — proper proposal after 3-iteration bash failure (R1/R2/R3 on #153) #154 or follow-up.

Both same_skill=idd-edit evidence; spawn_kind=tangential per /idd-plan #154 Step 2.5 (per IC_R011 v2.72.0+ file-by-default).

Acceptance criteria

Per #154 body Expected + this plan locked decisions:

• All 13 fixtures pass bash tests/idd-edit/test_parser.sh
• Spec preambles updated (3 sites: Purpose / R4 / R5)
• CHANGELOG [post-2.74.0] entry present with BREAKING marker
• /idd-edit SKILL.md frontmatter argument-hint reflects new flags
• All 3 SKILL.md ## 使用範例 examples use new flag syntax
• /idd-comment SKILL.md errata Template SPECIAL BEHAVIOUR updated to refuse-with-message (no auto-override)
• idd-verify --pr 6-AI ensemble PASS without R1/R2/R3-style parser regressions

[kiki830621]

Implementation Complete

Checklist (synced from TaskList)

• A1: idd-edit-helper.sh parse-args (positional shift + 7 flag guards + eq-form + missing-value + --* prefix) → commit ce0adf4
• A2: --body-file readability pre-check (inline parse-args, both eq+space forms) → commit ce0adf4
• A3: 9 Block A fixtures GREEN (01-scope-eq / 02-scope-space / 03-scope-last-arg / 04-scope-eats-next-flag / 05-body-file-missing / 06-multi-line-body / 07-single-line-body / 08-section-with-subs / 09-section-no-closing-heading) → commit ce0adf4
• B1: section-replace subcommand uses awk-getline (BSD/gnu safe; closes R3 C3 multi-line newline reject) → commit ce0adf4
• B2: R4 runtime gate (--replace requires --scope or --section, exit 3 with actionable message) → commit ce0adf4
• B3: R5 runtime gate (validate-target: *[bot] allowlist + OWNER passthrough + override pathway, exit 4 with helpful message) → commit ce0adf4
• B-tests: fixtures 10-12 GREEN (R4 refuse / OVERRIDE default / override-reason pair guard) → commit ce0adf4
• C1: idd-comment errata Template SPECIAL BEHAVIOUR — refuse-with-helpful-message (NOT auto-override per D2 decision; IDD_CALLER env var + exit 4 hint) → commit ce0adf4
• C-test: fixture 13 GREEN (errata override+reason succeeds at parse-args layer) → commit ce0adf4
• D1: idd-edit frontmatter argument-hint reflects new flag syntax → commit ce0adf4
• D2: 3 使用範例 updated + 2 new (section-replace + errata override) + Batch mode [design] /idd-edit batch mode + R5 refuse interaction — semantic decision needed (tangential from #154 plan) #158 note → commit ce0adf4
• D3: spec.md 3 preambles (Purpose/R4/R5) "deferred to [feature] /idd-edit runtime enforcement — proper proposal after 3-iteration bash failure (R1/R2/R3 on #153) #154" → "landed via [feature] /idd-edit runtime enforcement — proper proposal after 3-iteration bash failure (R1/R2/R3 on #153) #154" + tested-by fixture refs → commit ce0adf4
• D4: CHANGELOG [2.75.0] entry with 8 Added + 6 Refactored + 2 BREAKING markers + 4 filed-issues → commit ce0adf4
• D5: plugin.json version 2.74.0 → 2.75.0 → commit ce0adf4

Legend: - [x] done · - [~] skipped (may revisit) · - [-] won't fix (scope)
idd-close will refuse to close if any - [ ] remains in this checklist.

Architectural pivot (mid-implementation)

Discovered .claude/scripts/tests/spectra-archive-post-ic/ precedent during impl — fixture-dir pattern with args.txt / expected_stdout.txt / expected_exit.txt / post_assert.txt testing extracted script at .claude/scripts/<name>.sh. Per D3 plan-locked decision (ad-hoc shell), but pivoted to follow precedent on user approval — solves R1/R2/R3 root cause more deeply: AI no longer generates parser bash inline, instead invokes bash $CLAUDE_PLUGIN_ROOT/scripts/idd-edit-helper.sh parse-args "$@" and evals the output. Helper is tested, AI just orchestrates。 This also partially pre-empts #156 (test framework) — same pattern now applies to 2 sites (spectra-archive-post-ic + idd-edit)。

Test gate proof (R1/R2/R3 regression coverage)

All 13 fixtures GREEN with bash .claude/scripts/tests/idd-edit/test.sh:

PASS   01-scope-eq                       (eq form)
PASS   02-scope-space                    (space form)
PASS   03-scope-last-arg                 (R3 C1: --scope as last arg → exit 2)
PASS   04-scope-eats-next-flag           (R3 C2: --scope --body → exit 2)
PASS   05-body-file-missing              (R3 H1: unreadable → exit 5)
PASS   06-multi-line-body                (R3 C3: BSD awk newline OK)
PASS   07-single-line-body
PASS   08-section-with-subs              (R2 B3-NEW-3: stop at next ## not ###)
PASS   09-section-no-closing-heading     (EOF as section end)
PASS   10-replace-no-scope               (R4 gate: exit 3)
PASS   11-non-owner-no-override          (OVERRIDE=false default)
PASS   12-non-owner-with-override        (override requires --reason → exit 2)
PASS   13-errata-refuse-message          (override+reason succeeds)

TDD-caught test runner bug

Mid-impl: initial grep -qF "$needle" in test.sh treated needles starting with -- as flags. Fixed via grep -qF -- "$needle" end-of-options separator. Exactly the kind of subtle bug R1/R2/R3 didn't have safety net for — TDD discipline (write fixtures first → run → see fail → fix) caught it on the way to "all green".

Changes

• commit ce0adf4: feat: /idd-edit runtime enforcement (R4 + R5) via extracted helper script

Files Changed (64 files, +833/-36)

 .claude/scripts/idd-edit-helper.sh                 | 373 +++++++++++++++++++++
 .claude/scripts/tests/idd-edit/{test.sh + 13 fixtures} | +446
 openspec/specs/append-vs-modify-discipline/spec.md |   6 +-
 plugins/issue-driven-dev/.claude-plugin/plugin.json|   4 +-
 plugins/issue-driven-dev/CHANGELOG.md              |  41 +++
 plugins/issue-driven-dev/skills/idd-comment/SKILL.md|  26 +-
 plugins/issue-driven-dev/skills/idd-edit/SKILL.md  | 166 +++++++--

Scope Compliance

✓ Per Plan Out-of-scope:

• /idd-edit Step 5 preview UX untouched ✓
• Shared flag parsing helper across IDD skills NOT extracted (per [META] /idd-edit + IDD skills: bash vs alternative layer for strict flag parsing (sister concern from #154) #155 parking-lot) ✓
• Generalized test framework NOT built (per [infra] IDD plugin test framework — adversarial fixtures for SKILL.md regression coverage (sister concern from #154) #156, partial pre-emption via precedent reuse) ✓
• /idd-comment errata flow design unchanged (only message string change) ✓
• --append/--prepend-note modes' --scope NOT required (spec R4 explicit carve-out) ✓
• IDD_EDIT_LEGACY_MODE=1 env var NOT added (premature; per Plan R3 mitigation) ✓
• spec.md <!-- @trace --> blocks NOT synced (per [infra] spec.md <!-- @trace --> blocks lack auto-update mechanism (tangential from #154 plan) #157) ✓
• /idd-edit batch mode + R5 full semantics NOT implemented (per [design] /idd-edit batch mode + R5 refuse interaction — semantic decision needed (tangential from #154 plan) #158; single-target enforcement shipped + Batch mode note added) ✓

Next: verification pending

/idd-verify --pr <PR-number>

Pre-merge gate: bash .claude/scripts/tests/idd-edit/test.sh must continue to pass。 If 6-AI ensemble verify introduces R4-style parser regression suggestion → escalate to #155 alternative-layer discussion (Plan R6 mitigation; not expected since impl now decouples parser bash from AI generation via extracted helper)。

---

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

Step 5.7 reproduction trace surfaced 2 same-skill candidates from this session:

• #160 — bug: spectra-archive-post-ic/test.sh likely has same grep -qF -- bug (parking-lot P3) — TDD-caught bug in /idd-edit/test.sh (mid-session fix) was inherited from precedent template; verify if precedent has same. Same-skill (test infrastructure) instance idd-all: direct-commit mode 加 passive warning (dirty tree / on default branch) #2.
• #161 — docs: IDD_CALLER env var registry codification (parking-lot P3) — PR feat: /idd-edit runtime enforcement (R4 + R5) via extracted helper script (#154) #159 added IDD_CALLER=idd-comment-errata as 6th value; no central docs of allowed values + semantics. Rule-of-three threshold passed.

Both same_skill=true evidence (IDD plugin infrastructure); spawn_kind=sister-bug (#160 same-pattern as #154 test runner fix) + upstream-tracking (#161 cross-cutting docs gap surfaced by adding 1 more instance).