feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索

[kiki830621]

Problem

Original text (user chat, /idd-issue, 2026-05-07):
「接著我在想的是,有些流程我覺得需要仰賴 ralph-loop,可能要內建,不然中間會停下來」

issue-driven-dev 已有多個流程事實上仰賴 ralph-loop,但 plugin.json 沒宣告 dependency、README 也沒列出,使用者不裝 ralph-loop 跑這些流程會「中間停下來」(unattended 模式失去 driver、--loop flag 直接無法用)。

grep 確認以下硬依賴:

Skill / Mode	ralph-loop 角色	不裝會發生什麼
idd-verify --loop	直接驅動驗證-修復迴圈(skill SKILL.md line 81 + 628)	--loop flag 完全無作用
idd-all (PR, unattended) (v2.40.0+ default)	外圈 driver:verify 完發現 blocking findings → 自動觸發下一輪 implement → verify	sub-skill 抑制 AskUserQuestion 後沒人續跑,流程半路停滯;v2.40.0 description 多次提及「/loop friendly」「v2.40.0 既有 caller(如 /loop)的 default 行為」(idd-all SKILL.md line 29, 80, 187, 190)
idd-all unattended 自動修復 max 2 round	bootstrap task verify_loop 預期被 /loop 重新 invoke 才能跑滿 round	1 輪後就停,不像 attended 有 user 續推

目前狀態:

• plugins/issue-driven-dev/.claude-plugin/plugin.json 沒有 dependencies field(看起來 Claude Code plugin schema 也沒原生 inter-plugin dependency 機制)
• 頂層 README.md 0 hits for "ralph-loop" / "loop"
• plugins/issue-driven-dev/README.md 只在 line 69/100 提到自己內部「TDD loop」/「looped sequentially」,沒提外部 ralph-loop plugin
• skill 內部沒 fail-fast 偵測 — 跑 idd-verify --loop 但沒裝 ralph-loop 應該明確報錯,目前不確定行為(可能 silent no-op / 可能 obscure error)

Type

feature + documentation(雙面)

Expected

三層改善(用戶選了全部三項 scope):

Layer 1: README docs gap(同 #26 套路)

兩份 README 加 "Required dependencies for unattended / loop modes" 段落:

Mode	Required plugin	Install 指令
idd-verify --loop	ralph-loop	claude plugin install ralph-loop@<marketplace>
idd-all unattended (PR mode default)	ralph-loop	同上
idd-all direct-commit + attended	(none)	n/a — user 在 keyboard
Single-skill calls (idd-issue / idd-diagnose / idd-implement / idd-verify / idd-close 不帶 flag)	(none)	n/a

Layer 2: Skill 內部 auto-detect + fail-fast 提示

idd-verify Step 0 / idd-all Phase 0.5 在進 unattended path 前:

# Pseudo
if mode == "unattended" || flag == "--loop"; then
  if ! command -v ralph-loop &>/dev/null && ! check_ralph_loop_skill_present; then
    echo "✗ unattended / --loop mode 需要 ralph-loop plugin"
    echo "  Install: claude plugin install ralph-loop@<marketplace>"
    echo "  或改跑 attended: /idd-all #N --no-pr"
    exit 1
  fi
fi

涵蓋 idd-verify --loop 和 idd-all (PR, unattended)default。

Layer 3:「內建」依賴宣告(探索性 — 可能受限於 Claude Code plugin 系統能力)

考慮以下選項(diagnose phase 評估可行性):

(a) plugin.json 加 dependencies / requires field — 即使 Claude Code 目前不消費此 field,寫了至少有 forward compat + 自我文件
(b) Marketplace dependencies 機制 — 在 .claude-plugin/marketplace.json 標 issue-driven-dev requires ralph-loop for unattended,讓未來 marketplace tooling 可以掃
(c) Bundle install hint — README install 指令改成:

# Recommended (full features incl. unattended):
claude plugin install issue-driven-dev@issue-driven-development
claude plugin install ralph-loop@<marketplace>

# Minimal (attended-only):
claude plugin install issue-driven-dev@issue-driven-development

(d) idd-all session-start hook — 第一次跑 unattended 時 echo warning「ralph-loop not detected, --no-pr fallback」

這層需要 diagnose 確認 Claude Code plugin 有哪些 native 機制可用,可能 spawn 出 sister issue。

Actual

• README 隻字不提 ralph-loop
• plugin.json description 多次描述「/loop friendly」「/loop 既有 caller」但沒任何 install / dependency 標註
• skill 內部沒 detect logic — 直接呼叫如果失敗,error 訊息不會引導使用者
• 使用者只能從 SKILL.md 內文 grep 才能發現「噢原來要裝 ralph-loop」

Impact

• Onboarding 卡點:新使用者看 README 裝 issue-driven-dev,以為「裝完就完整」,跑 /idd-all 結果 unattended 流程半路停 → 誤以為 IDD 有 bug
• Silent degradation:跟 docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 同類失敗模式,但這個更嚴重 — /loop 無聲卡死比 .docx 讀不到還難 debug
• Marketing mismatch:plugin.json 主打 /loop friendly 是 v2.40.0 賣點,但實際 /loop 來自外部 plugin,使用者不知道

Related

• docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 — 也是 README dependencies gap,但聚焦 source-type MCP plugin
• bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 — silent-degrade 報錯模式,本 issue 的 Layer 2 是同類解法

Scope confirmation (per /idd-issue clarification)

• Layer 1: README docs gap (README.md + plugins/issue-driven-dev/README.md)
• Layer 2: Skill auto-detect + install 提示 (idd-verify Step 0 + idd-all Phase 0.5)
• Layer 3:「內建」依賴宣告(探索 plugin.json / marketplace.json / install bundle)

Priority: P2

Linked-Context Siblings Filed (v2.48.0+ #529)

(none — primary concern already split across 3 explicit Layers within this issue;related #26 / #27 cross-linked above)

Current Status

Phase: closed
Last updated: 2026-05-07 by idd-close

Resolution

• PR feat+docs: ralph-loop dependency declaration + runtime detect (Plan tier) #36 squash-merged → main 6aec214
• 8 commits (5 implement + 3 round-2 fix from 6-AI verify findings)
• Plugin version bumped 2.52.0 → 2.53.0
• Layer 3 reverted to README-only (per F1 schema validate-fail)
• All Layer 1 + 2 outcomes preserved + hardened

Critical catches by 6-AI verify

• F1 (P0, Codex): plugin.json dependencies field validate-fail → reverted entirely
• F2 (P1, Devils-Advocate NEW): Phase 0.6 BRANCH bug → unwind logic added
• F3 (P1, logic+security+Codex consensus): HOME-with-spaces glob → bash array + nullglob
• F4 (P2): bypass silent → stderr warning
• F5 (P3): version mismatch → bumped

PR

• feat+docs: ralph-loop dependency declaration + runtime detect (Plan tier) #36 (merged)

Follow-ups (carried)

• docs: track upstream gap — Claude Code plugin schema 缺 inter-plugin dependency 機制 (sister from #28) #29 upstream Claude Code schema gap (P3 tracking)
• refactor: 抽出 generic plugin-presence detector helper (tangential from #28 plan) #34 generic plugin-presence helper (P3, mid-plan tangential)
• tracking: Claude Code plugin cache path schema 變動 watch-list (tangential from #28) #35 cache path schema watch-list (P3 — schema brittleness was prescient,round-2 hit similar issue)

[kiki830621]

Diagnosis

Type

feature + documentation (cross-cutting: docs + skill behavior + plugin metadata exploration)

Analysis

Confirmed evidence chain (grep + filesystem probe):

1. idd-verify --loop 直接呼叫 ralph-loop (plugins/issue-driven-dev/skills/idd-verify/SKILL.md line 81 + 628):

   idd-verify #42 --loop → 驗證 + ralph-loop 自動修復迴圈
   「加上 `--loop` 後,用 ralph-loop 驅動驗證-修復迴圈」

2. idd-all (PR, unattended) 是 v2.40.0 default (line 187): pr_policy absent → (PR, unattended) [v2.40.0 backward-compat default],且 9 處 reference「/loop friendly」/「v2.40.0 既有 caller(如 /loop) 的 default 行為」(lines 29, 80, 187, 190, 246 等)

3. ralph-loop 確實裝在 claude-plugins-official/ralph-loop (Anthropic 官方 marketplace),不是 PsychQuant 自家 plugin

4. Plugin schema 探查 (marketplace.json 用 https://anthropic.com/claude-code/marketplace.schema.json、plugin.json 無 dependencies field):Claude Code plugin schema 目前不支援 inter-plugin dependency 宣告。Layer 3 (a)/(b) 屬「forward-compat 自我文件」,無 runtime enforcement;只有 (c)/(d) 是今天可作用的方案

5. 無既有 fail-fast logic:idd-verify Step 0 / idd-all Phase 0.5 都沒 command -v ralph-loop 或 plugin presence check。實際失敗模式不確定,需 implement 階段先驗證(可能是 obscure error,可能是 silent loop-of-1)

Crucial overlap discovery (與 #26 共用 landing spot):

• 兩 issue 都需要修 plugins/issue-driven-dev/README.md ## Requirements section + 頂層 README.md 加 ## Requirements
• 若 docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 / feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 各自 implement 會 step on each other(merge conflict in ## Requirements)
• Implement order recommendation: docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 先 land(較單純的 Optional matrix),feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 再 land(在 docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 結構上加 Required-for-mode rows + skill auto-detect code)

Impact

檔案範圍 (4 files,跨 docs + skill behavior):

檔案	改動類型	與 #26 重疊?
README.md (頂層)	加 ## Requirements summary	✅ 同一 section
plugins/issue-driven-dev/README.md	擴 ## Requirements 加「Required for unattended/--loop」row	✅ 同 section,但 #26 是 Optional MCP rows,#28 是 mode-required row
plugins/issue-driven-dev/skills/idd-verify/SKILL.md	Step 0 加 ralph-loop detect + fail-fast	❌ 獨立
plugins/issue-driven-dev/skills/idd-all/SKILL.md	Phase 0.5 進 unattended path 前同樣 detect	❌ 獨立
plugin.json (optional, Layer 3a)	加 dependencies field 為 forward-compat	❌ 獨立,但 schema 不支援

使用者流程衝擊:

• 新使用者裝 issue-driven-dev 後跑 /idd-verify #N --loop → 沒裝 ralph-loop 會發生什麼? 未驗證,需 implement 階段先 reproduce(這是 Step 1 RCA 的 prerequisite,目前以「skill 沒 detect logic」為觀察證據,實際失敗模式仍未確認)
• /idd-all 預設 PR mode → unattended → 一輪 verify 後 blocking findings → 沒 /loop driver → 流程半途停滯但無錯誤訊息

Strategy

3-layer plan (依 issue body Scope confirmation,user 已確認三 layer 全做):

Layer 1: README docs (cross-link to #26)

• A1. 等 docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 先 land(避免 ## Requirements section conflict)
• A2. 在 docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 重組過的 ## Requirements 結構上,加新 row group「Required for specific modes」:
  • idd-verify --loop → ralph-loop (claude-plugins-official)
  • idd-all (PR, unattended) → ralph-loop
  • idd-all --no-pr (direct-commit, attended) → (none)
• A3. 在 plugin README install section 加 "Recommended bundle" snippet:

  claude plugin install issue-driven-dev@issue-driven-development
  claude plugin install ralph-loop@claude-plugins-official  # for unattended/--loop modes

Layer 2: Skill auto-detect + fail-fast

• B1. 先 reproduce:跑 /idd-verify #X --loop 在沒有 ralph-loop 的環境(用 --plugin-dir 隔離),確認當前失敗模式;這決定 fail-fast 訊息該抓哪個 trigger
• B2. 抽 helper scripts/check-ralph-loop.sh:檢查 ① ~/.claude/plugins/cache/claude-plugins-official/ralph-loop/ 是否存在 ② command -v 不適用(ralph-loop 是 plugin skill 不是 CLI binary,所以 command -v 偵測會錯) → 真正的 detect 應該是 plugin install 路徑或 skill registration
• B3. idd-verify Step 0 在 --loop flag 時 invoke helper,缺失則 fail-fast + 給 install command + suggest --no-pr fallback
• B4. idd-all Phase 0.5 在 mode resolution 為 (PR, unattended) 後同樣 invoke helper,缺失則:Decision needed — abort vs warning + degrade to (direct-commit, attended)?

Layer 3: 「內建」依賴宣告(探索 + decision)

• C1. 可行性已確認:plugin schema 不支援 dependencies field → Layer 3(a)/(b) 純 forward-compat 文件功能,無 runtime enforcement
• C2. 實際採用:
  • (c) Bundle install hint 採用(已併入 A3)
  • (d) Session-start hook 採用:加 hooks/session-start.sh echo warning if user has unattended-default config but ralph-loop missing
  • (a) plugin.json 加 dependencies field with comment「forward-compat,not yet consumed by Claude Code」採用(自我文件 + 未來 schema 升級就免重做)
  • (b) Marketplace 同上但較少必要(plugin.json 已涵蓋)— 暫不

Complexity

Plan

Layer 1 (Simple disqualifiers) 不命中 — 雖然有 docs 改動,主 deliverable 含 skill behavior 改動 (B3/B4) 和 plugin.json schema 改動 (C2),不純粹是 prose update。

Layer V: V1 = 2 (清楚:三層拆解明確), V4 = 3 (中等:每層有 checkbox 但 B4 有 open decision「abort vs degrade」需 implement 階段確認) — not triggered (max=3 < 4)。

Layer 2 + Layer 3 (Spectra):不命中 — 沒 expose new published API / protocol / skill / tool surface 給 future callers(--loop flag 已 published,本 issue 只加 detect,沒改其 contract)。fail-fast 訊息也不是「contract」屬性。

Layer P (Plan):多項命中,觸發 Plan tier:

• ✅ 2+ 檔案有順序依賴 — README 改動 (A1/A2) 必須等 docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 先 land,idd-verify 和 idd-all 共用 helper script (B2),修改順序影響整體
• ✅ Decision-heavy with 2+ valid approaches — Layer 3 有 4 個 sub-option (a/b/c/d) 各有 trade-off;B4 「unattended fail-fast 該 abort 還是 degrade」是行為層 trade-off
• ✅ Strategy 有 5+ ordered steps — A1→A2→A3→B1→B2→B3→B4→C1→C2 共 9 step
• ✅ 觸及 risk-sensitive 邊界 — Layer 2 fail-fast 邏輯改動 unattended pipeline 行為;誤判(false positive)會 block 既有 caller(/loop-driven workflows)。idd-all pr_policy absent → unattended default 是 v2.40.0 既有契約,Layer 2 一不小心就 break 此契約

→ Plan path 在 implement 之前需要 EnterPlanMode approval gate,讓 user review:

1. helper script 的 detect 機制(filesystem probe vs config probe vs runtime probe)
2. B4 decision (abort vs warning-degrade)
3. C2 是否真要動 plugin.json schema(forward-compat 的價值 vs 文件 noise)

Risks

• High: Layer 2 false positive 破壞 v2.40.0 契約 — pr_policy absent → unattended 是既有 default。若 detect logic 誤判 ralph-loop missing,既有 /loop caller workflow 全部 break。Mitigation: B1 reproduce 後再寫 detect,B2 helper 用 strict check (filesystem path exists),B3/B4 加 --skip-ralph-check escape hatch
• Medium: detect 機制未來變動 — Claude Code 將來改 plugin install path schema → detect logic 失效。Mitigation: 用 claude plugin list CLI 而非 hardcode path(若 CLI 提供)
• Medium: Bundle install hint 寫死 marketplace name — 同 docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 風險,claude-plugins-official 是 Anthropic 官方,變動機率低於 community marketplaces。Mitigation: 用 placeholder 但附 reference URL
• Low: Layer 3(a) plugin.json dependencies field 被 Claude Code schema 拒絕 — 若 schema validation strict,加非標 field 可能 warn/error。Mitigation: 先看 schema validation 行為再決定是否加

Related

• docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 — 共用 ## Requirements landing spot,implement 必須先 docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 land 再 feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28
• bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 — Layer 2 同類解法(Source Type Adapter fail-fast),implement 時可參考其 helper pattern,可能浮出共用 abstraction(generic plugin-presence checker)

Vagueness Pre-check

• V1: 2 — three Layers explicit; each layer has concrete A/B/C task list referencing exact files (idd-verify Step 0 / idd-all Phase 0.5 / plugin.json); user already confirmed all 3 layers in /idd-issue scope checkbox
• V4: 3 — most steps have binary checkboxes, but B4 carries an open decision (abort vs degrade) that needs implement-time confirmation; not enough to push V4 ≥ 4 ("Make the API response cleaner" anchor)
• Triggered: no — both axes ≤ 3

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

Filed: #29 (upstream gap tracking — Claude Code plugin schema lacks inter-plugin dependency mechanism)

Skipped per user choice (1 item: shared plugin-presence checker abstraction between #27/#28 — to be discovered naturally during implement; no formal issue needed)

[kiki830621]

Implementation Plan (Plan tier)

Files & Changes

Layer 1: README docs (build on #26 structure)

• plugins/issue-driven-dev/README.md — 在 ## Requirements 內 ### Optional (per source type) matrix 之後、### Sister plugins 之前插入新 sub-section ### Required for specific modes,內含 4-row matrix:

  | Mode | Required plugin | Marketplace | Why |
  |------|-----------------|-------------|-----|
  | `idd-verify --loop` | `ralph-loop` | `claude-plugins-official` | outer driver for verify-fix loop |
  | `idd-all` (PR, unattended) (default) | `ralph-loop` | 同上 | unattended mode 在 verify findings 後需 driver 觸發下一輪 |
  | `idd-all --no-pr` (direct-commit, attended) | (none) | n/a | user 在 keyboard 自然推進 |
  | Single-skill calls (no `--loop`) | (none) | n/a | atomic skill 自完成 |
  

  • 移除 line 205 既有 Note(因為新 sub-section 已涵蓋)
• README.md (頂層) — 已含 ralph-loop bullet (post-docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 merge),不改 — 細節留在 plugin README 維持 single source of truth

Layer 2: Skill auto-detect + fail-fast

• plugins/issue-driven-dev/scripts/check-ralph-loop.sh (NEW) — POSIX-portable detector,檢查 ~/.claude/plugins/cache/claude-plugins-official/ralph-loop/.claude-plugin/ 存在;exit 0 if present, exit 1 if missing。不用 command -v ralph-loop (ralph-loop 是 plugin skill 不是 CLI binary)
• plugins/issue-driven-dev/skills/idd-verify/SKILL.md — 在 Step 0 (Bootstrap) 之前加 Step 0a:當 invocation 含 --loop flag → invoke helper → if missing,fail-fast abort with structured message + suggest --no-pr fallback
• plugins/issue-driven-dev/skills/idd-all/SKILL.md — Phase 0.5 PR mode resolution 之後加 Step 0.6 mode-degrade gate:當 resolved tuple 是 (PR, unattended) 且 ralph-loop missing → degrade to (direct-commit, attended) + warning 而非 abort(B4 decision,見下方 Decision Points)
• plugins/issue-driven-dev/skills/idd-all/SKILL.md — Examples 加新 Trace 4 「(PR, unattended) + ralph-loop missing → graceful degrade」 demo

Layer 3: Self-documenting plugin.json (forward-compat)

• plugins/issue-driven-dev/.claude-plugin/plugin.json — 加 top-level dependencies field with comment 標明 forward-compat:

  "dependencies": {
    "_comment": "Forward-compat declaration. Claude Code plugin schema does not yet consume this field — see #29. When schema upgrade lands, this becomes machine-enforced.",
    "optional_for_modes": {
      "ralph-loop": {
        "marketplace": "claude-plugins-official",
        "required-for": ["idd-verify --loop", "idd-all (PR, unattended) mode"],
        "graceful-degrade": "idd-all degrades to (direct-commit, attended) per #28 B4 design"
      }
    }
  }

Sequencing & Dependencies

Layer 1 (README) ──┐
                   ├──> all 3 layers parallel-safe (no inter-file dep)
Layer 2 (helper + 2 skills) ──┤
                              │
Layer 3 (plugin.json) ────────┘

但 commit 順序建議:Layer 1 → Layer 2 → Layer 3(由 user-facing 程度由高到低)。每層 1-2 commits,共 5-6 commits。

Decision Points

B4 — unattended fail-fast: abort vs degrade? → 選 degrade

理由:

• idd-all 既有 caller(如 /loop)的 v2.40.0 default 是 (PR, unattended)。abort 會 break 既有 callers,違反 backward compat
• ralph-loop missing 不是 IDD 邏輯錯誤,是依賴缺失 — IDD 仍能跑 attended mode 給 user 繼續
• Degrade trigger:print warning「ralph-loop missing → degraded to (direct-commit, attended)」並提示 install,user 看到 warning 可選擇 abort + install + retry
• idd-verify --loop 不同:它是 user explicit 要 --loop,沒裝 ralph-loop 就 abort + install hint(無 attended fallback 因 --loop 是 explicit feature request)

Layer 3 (a)/(b)/(c)/(d) sub-option selection:

• (a) plugin.json dependencies field — ✅ 採用(forward-compat 自我文件)
• (b) marketplace.json — ❌ 不採用(plugin.json 已涵蓋,marketplace.json 額外加 noise 無 benefit)
• (c) Bundle install hint — ✅ 已在 docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26/docs: README install 指令的 <your-marketplace> placeholder 缺 lookup hint (sister from #26) #31 README 達成(無需另做)
• (d) Session-start hook — ❌ 暫不採用(scope creep,本 issue 已含 README docs + skill auto-detect 兩條 detect path,session-start 是第三層 detect 邊際效益低)

Risks & Mitigations

• High: Layer 2 false positive 破壞 v2.40.0 contract — 若 helper script 誤判 ralph-loop missing(例:cache path 改變),所有 (PR, unattended) callers degrade。Mitigation:
  • helper 加 --skip-ralph-check escape hatch (env var IDD_SKIP_RALPH_CHECK=1)
  • helper exit 1 時印出明確 detect path 讓 user debug
  • PR 之前 manual test:臨時 rename ralph-loop dir → 跑 /idd-all #X 確認 degrade + warning 而非 crash
• Medium: cache path schema 未來改動 — ~/.claude/plugins/cache/claude-plugins-official/ralph-loop/ 是當前 path,Anthropic 升級可能改。Mitigation:helper 內標明「detect path 依 Claude Code 2025-Q4 plugin cache schema,若失效查 docs: track upstream gap — Claude Code plugin schema 缺 inter-plugin dependency 機制 (sister from #28) #29 upstream tracking」
• Low: plugin.json dependencies field 被 schema validation 拒絕 — 若 Claude Code strict schema validator 拒絕未知 field,plugin.json 無法 parse。Mitigation:先測(claude plugin update issue-driven-dev 後檢查 plugin loadable),若 reject 退到只在 README 標明 dependency

Test Plan

• Layer 1: visual render check + grep 確認 4-row matrix 正確 + 既有 > **Note**: line 已移除
• Layer 2:
  • scripts/check-ralph-loop.sh 兩個 case: ralph-loop 存在 → exit 0;rename 後 → exit 1
  • idd-verify --loop 在 ralph-loop missing 環境下跑 → 應 abort with structured message
  • idd-all 在 ralph-loop missing 下跑 → 應 degrade + warning,不 abort,sub-skill 接續 attended
• Layer 3: claude plugin update issue-driven-dev 後 plugin 仍 loadable;gh api query plugin.json content 含 dependencies field

Out-of-scope (will NOT be touched)

• idd-implement / idd-diagnose / idd-issue / idd-close:都不依賴 ralph-loop,本 issue 不改
• bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 (Source Type Adapter fail-fast):同類 detect logic,但 source-type detect 跟 mode-required detect 不同 trigger context,共用 abstraction 由 bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 implement 時決定是否 refactor 出 helper(本 issue diagnose Sister 已 skip,留給 bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 自然 emergence)
• plugin.json dependencies.required (hard):本 issue 只加 optional_for_modes,不宣告 hard dependency(因為 IDD core 仍可跑無依賴)
• Anthropic upstream lobby:docs: track upstream gap — Claude Code plugin schema 缺 inter-plugin dependency 機制 (sister from #28) #29 已追蹤,本 issue 不重複 push upstream

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

Tangential Observations: filed #34 (shared plugin-presence helper), #35 (cache path schema watch-list)

[kiki830621]

Implementation Complete

Checklist (synced from TaskList)

Layer 1: README docs

• A1. plugins/issue-driven-dev/README.md 加 ### Required for specific modes → commit c384b2e
  • 4-row matrix: idd-verify --loop / idd-all (PR, unattended) / idd-all --no-pr / single-skill
  • 標明 fail-fast vs graceful-degrade behavior
  • 移除舊 > **Note**: 一行(已被新 sub-section 涵蓋)
• [-] A2. 頂層 README.md — won't fix: 已含 ralph-loop bullet (post-docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 merge),細節留 plugin README 維持 single source of truth

Layer 2: Skill auto-detect + fail-fast / graceful degrade

• B1. scripts/check-ralph-loop.sh (NEW) → commit c659c25
  • POSIX-portable bash detector with glob path matching
  • IDD_SKIP_RALPH_CHECK=1 env var escape hatch
  • Critical fix during smoke test: 初版 detect path 漏掉 <version>/ segment(actual: ralph-loop/1.0.0/.claude-plugin/)→ 改用 */.claude-plugin/plugin.json glob (tracking: Claude Code plugin cache path schema 變動 watch-list (tangential from #28) #35 watch-list 紀錄了 path schema brittleness)
  • 3-case smoke test PASS:present (exit 0) / missing (exit 1) / env-var-bypass (exit 0)
• B2. idd-verify Step 0a fail-fast → commit b870aa0
  • --loop flag 觸發 detect → missing 則 abort + structured install hint
  • 對比 idd-all graceful degrade 的設計理由寫進 SKILL.md
• B3. idd-all Phase 0.6 graceful degrade gate → commit caf3820
  • (PR, unattended) resolved tuple → detect → missing 則 degrade to (direct-commit, attended) + warning
  • REASON 串接 + ralph-loop missing → graceful degrade (#28) 寫入 audit trail
  • 加 Trace 4 example demo degrade flow
• [-] B4. unattended fail-fast: abort vs degrade — design decision: degrade(plan-tier approval gate 確認)

Layer 3: Self-documenting plugin.json

• C1. plugin.json dependencies field → commit 94c5396
  • JSON validation PASS (jq . clean)
  • optional_for_modes.ralph-loop 含 marketplace / required_for / graceful_degrade / detect_runtime
  • _comment 標明 forward-compat,not yet machine-enforced (per docs: track upstream gap — Claude Code plugin schema 缺 inter-plugin dependency 機制 (sister from #28) #29 upstream tracking)
• [-] C2. (a) plugin.json + (c) bundle hint — adopted (見 C1 + docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26/docs: README install 指令的 <your-marketplace> placeholder 缺 lookup hint (sister from #26) #31 已達成)
• [-] C3. (b) marketplace.json / (d) session-start hook — won't fix: scope creep,Layer 1+2 已充分 cover

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

Changes

• c384b2e docs: 加 ### Required for specific modes matrix (ralph-loop)
• c659c25 feat: add scripts/check-ralph-loop.sh detector with version-glob path + escape hatch
• b870aa0 feat: idd-verify --loop 加 Step 0a ralph-loop fail-fast gate
• caf3820 feat: idd-all 加 Phase 0.6 ralph-loop graceful degrade gate + Trace 4 example
• 94c5396 feat: plugin.json 加 forward-compat dependencies field

Files Changed

 .../issue-driven-dev/.claude-plugin/plugin.json    | 13 +++++-
 plugins/issue-driven-dev/README.md                 | 15 ++++++-
 .../issue-driven-dev/scripts/check-ralph-loop.sh   | 45 ++++++++++++++++++++
 plugins/issue-driven-dev/skills/idd-all/SKILL.md   | 49 ++++++++++++++++++++++
 .../issue-driven-dev/skills/idd-verify/SKILL.md    | 14 +++++++
 5 files changed, 133 insertions(+), 3 deletions(-)

Scope Compliance

• ✅ 所有改動對齊 plan-approved 3 layers
• ✅ Plan tier approval gate (EnterPlanMode) 已 user-approved
• ✅ B4 design decision (degrade > abort) 在 plan deliberation 階段拍板
• ✅ Cache path schema brittleness 已 file 為 tracking: Claude Code plugin cache path schema 變動 watch-list (tangential from #28) #35 follow-up,不在本 PR scope
• ✅ Generic plugin-presence helper refactor 已 file 為 refactor: 抽出 generic plugin-presence detector helper (tangential from #28 plan) #34 follow-up

Tangential Observations Filed (mid-plan)

• refactor: 抽出 generic plugin-presence detector helper (tangential from #28 plan) #34 — refactor: 抽出 generic plugin-presence detector helper
• tracking: Claude Code plugin cache path schema 變動 watch-list (tangential from #28) #35 — tracking: Claude Code plugin cache path schema 變動 watch-list

Critical Verify Catch

Layer 2 helper script 初版 path schema 錯誤 — smoke test 發現 ~/.claude/plugins/cache/<marketplace>/<plugin>/.claude-plugin/ 不對,實際是 <plugin>/<version>/.claude-plugin/。改用 glob */.claude-plugin/plugin.json。這正驗證了 plan 階段 Risk「cache path schema brittle」的判斷,#35 watch-list 已在 plan 階段先行 file。

Next: verification pending

[kiki830621]

Verify (via PR #36)

Result: FAIL — 1 P0 + 2 P1 blocking, cross-AI consensus

Full report: #36 (comment)

This issue's findings:

• F1 (P0): plugin.json dependencies validate-fail
• F2 (P1): Phase 0.6 BRANCH bug (commits to dangling feature branch on degrade)
• F3 (P1): HOME-with-spaces glob bug breaks v2.40.0 backward-compat
• F4 (P2): silent IDD_SKIP_RALPH_CHECK bypass + missing docs
• F5 (P3): manifest version 2.52.0 vs new content tagged v2.53+

PR not merged — needs round-2 fixes per recommended list in master report.