feat: submodule support in IDD config — let parent config route submodule operations

[kiki830621]

Problem

Original suggestion (verbatim):
「我在想 idd 要能夠支持 submodule 的設定，可能最上層的 idd 設定可以用來調整 submodule 吧？」

When working inside a git submodule, IDD's walked-up config resolution (Step 0.5.B) finds the parent repo's .claude/issue-driven-dev.local.json and uses its github_repo field — which targets the parent repo, not the submodule. The submodule's own GitHub remote is silently ignored.

The user is asking for: the topmost (parent) IDD config could declare per-submodule routing, so a single parent config drives both parent-repo issues and submodule-repo issues without the user having to maintain a separate config file inside each submodule.

Type

feature / enhancement (config-protocol)

Concrete pain point (encountered 2026-05-26)

Setup:

• Parent repo: PsychQuant/IRT_variacne_bootstrapping_estimtor (code + sims)
• Submodule at manuscript/parametric_bootstrapping_se/ → remote kiki830621/PB-of-IRT-ability (manuscript)
• Parent config: article2_standard_error/.claude/issue-driven-dev.local.json → "github_repo": "PsychQuant/IRT_variacne_bootstrapping_estimtor"

Sequence:

1. cd manuscript/parametric_bootstrapping_se/05xx-2026/ (inside submodule)
2. /idd-issue ... for a manuscript-content change
3. Step 0.5.B walks up, hits parent config → GITHUB_REPO = PsychQuant/IRT_variacne_bootstrapping_estimtor (WRONG — should be kiki830621/PB-of-IRT-ability)
4. The submodule's own git remote get-url origin (which would derive the correct target) is ignored because Step 0.5.B's walked-up config wins over derivation
5. Workaround: manually create manuscript/parametric_bootstrapping_se/.claude/issue-driven-dev.local.json with "github_repo": "kiki830621/PB-of-IRT-ability"

Same friction applies to idd-diagnose / idd-implement / idd-verify / idd-close — every IDD skill walking-up from submodule cwd hits the wrong parent config.

Expected

A parent IDD config should be able to declare per-submodule routing in one of these forms (proposing two designs, not mutually exclusive):

Option A — Reuse existing candidates + path predicates (documentation pattern)

The candidates mechanism + path_contains predicate already handles this case; it's a discoverability gap, not a missing feature. Document the pattern explicitly:

{
  "github_repo": "PsychQuant/IRT_variacne_bootstrapping_estimtor",
  "candidates": [
    {
      "label": "Manuscript submodule",
      "github_repo": "kiki830621/PB-of-IRT-ability",
      "when": { "path_contains": "manuscript/parametric_bootstrapping_se" }
    }
  ]
}

Step 0.5.C predicate pre-resolve already picks the candidate when cwd matches the path. The friction is that users (incl. me today) don't know this pattern handles submodules — README and CLAUDE.md call candidates "monorepo sub-package" routing, not "submodule" routing. Fix could be docs-only.

Option B — Native submodule awareness (submodules field in config schema)

Add a first-class field that consumes the parent repo's .gitmodules and auto-routes:

{
  "github_repo": "PsychQuant/IRT_variacne_bootstrapping_estimtor",
  "submodules": {
    "manuscript/parametric_bootstrapping_se": {
      "github_repo": "kiki830621/PB-of-IRT-ability",
      "attachments_release": "attachments"
    }
  }
}

Or with auto-derive (parse .gitmodules, use submodule's git remote get-url origin):

{
  "github_repo": "PsychQuant/IRT_variacne_bootstrapping_estimtor",
  "submodules": "auto"
}

Resolution algorithm: Step 0.5 checks if cwd is inside a registered submodule path → use submodule's mapped github_repo; otherwise fall through to parent's github_repo. The submodule's .claude/ directory does NOT need its own config.

Actual (current behaviour)

The fallback chain in Step 0.5 (config-protocol six mechanisms):

1. --target flag (per-invocation override) — works but heavyweight
2. ask_each_time menu — only fires if config has candidates / groups
3. Predicate pre-resolve — works if candidates are set up (user has to know)
4. Cascading config (walk up) — finds parent config, uses parent's github_repo (silent wrong target)
5. git remote fallback — never reached because step 4 already resolved
6. Groups — orthogonal, doesn't help

Submodule users currently must either (a) pass --target ... every invocation, (b) set up candidates manually, or (c) duplicate config inside the submodule. None is discoverable from the failure mode (silent wrong-target).

Impact

• Affects any user with git subtree/git submodule workflow (e.g. manuscript + code projects, Overleaf-synced manuscripts, multi-repo monorepos)
• Particularly painful when the submodule's GitHub remote differs from parent's owner (cross-org submodules)
• Silent failure mode: target goes to wrong repo, user only notices after issue is filed in wrong place

Proposed scope (please confirm)

• Docs (Option A): README + CLAUDE.md section "Submodule support" showing candidates + path_contains pattern. Probably 1 commit, zero code changes.
• Native (Option B): submodules field in config schema + Step 0.5 resolution algorithm update + tests + docs. Larger; depends on whether maintainer prefers extending schema vs steering users to candidates.
• Fallback safety net: if Step 0.5.B's walked-up config exists but cwd is inside an UNregistered submodule (not in candidates, not in submodules), emit a warning citing the parent target + suggesting the candidates/submodules pattern — instead of silent wrong-target.

Related

• config-protocol.md Step 0.5 six-mechanism resolution (this issue proposes extension to mechanism 4)
• candidates + path_contains (existing, under-documented for submodule case)
• Pain point context: today's session converted manuscript/parametric_bootstrapping_se/ from git subtree → git submodule (per parent repo CLAUDE.md update 2026-05-26). The mode switch surfaced this gap.

---

Current Status

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

Key Decisions

• Complexity = Plan、A_parallel_safe
• 優先序：explicit candidates > submodule auto > parent github_repo；submodules: off 逃生口
• Verify PASS（fixture 8/8 + red-proof）；Next: merge PR 後 /idd-close feat: submodule support in IDD config — let parent config route submodule operations #162

[kiki830621]

Diagnosis

Type

feature（config-protocol — submodule 邊界的 repo 路由）

Root Cause / Analysis

現況機制其實已有 80% 解：candidates[].when.path_contains 可手動宣告「此路徑 → submodule remote」— pain point 的直接根因是 walked-up resolution 停在 parent config 且 parent 的 github_repo 靜默勝出，使用者不知道要（也不知道能）加 candidates 條目。

Gap 拆解：

1. 靜默錯 repo（核心 bug 面）：cwd 在 submodule 內時，resolution 應偵測 submodule 邊界（git rev-parse --show-superproject-working-tree 非空）並至少 surface「你在 submodule 內、目前路由到 parent repo」
2. 自動路由（feature 面）：submodule 自身 remote 作為隱含 candidate（優先序：explicit candidates > submodule 自動偵測 > parent github_repo），parent config 可用 submodules: auto|off 開關

Impact

• references/config-protocol.md（resolution 順序 + schema key）+ 各 skill 共用的 config 解析敘述
• 跨 skill 一致性：config-protocol 是 shared reference，改一處全 skill 受益

Strategy

• config-protocol.md：resolution 加 submodule 偵測步（自動 candidate + surface line）+ submodules key
• 預設 auto（submodule remote 優先）——使用者原話意圖「最上層設定調整 submodule」由 explicit candidates 覆蓋 auto 達成
• idd-config which 顯示 submodule 偵測結果
• 測試：submodule fixture（superproject + sub remote 分歧）

Conflict Class

A_parallel_safe — config-protocol.md + idd-config，queue 內無他案共享。

Complexity

Plan（Layer P：resolution 優先序是跨 skill 契約變更）
[Plan tier deliberation skipped under unattended mode]

Risks

• 既有 monorepo 使用者若依賴「submodule 內也路由 parent」的現行為 — submodules: off 逃生口 + CHANGELOG BREAKING 註記

Residue

Nested submodule（sub-in-sub）遞迴解析不做 — 單層覆蓋實戰案例。

Vagueness Pre-check

• V1: 2 — 意圖清楚；優先序細節由 diagnosis 定案
• V4: 2 — 完成 = resolution 更新 + 開關 + 測試
• Triggered: no

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

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

(none)

---

Source: /idd-all batch drain (unattended), 2026-07-06

[kiki830621]

Implementation Complete

Checklist (synced from TaskList)

• lib/resolve-submodule-route.sh：superproject 偵測 + submodules key（auto/off）+ owner/repo shape 驗證 + never-silent surface 契約 → d0d0193
• config-protocol.md：Mechanism 3.5 正式插入 priority list（explicit candidates 仍優先）+ backward-compat 註記（依賴舊行為者設 "submodules": "off" 一行）
• idd-config which 顯示 submodule 偵測結果
• Fixture 測試 8 斷言（auto 路由 / off 保持 parent / 非 submodule 靜默 / 無 origin fallback 警告）+ red-proof（弄壞 helper → 1 斷言 FAIL）

Sister Bugs Filed (mid-impl)

(none — nested submodule 遞迴為 diagnosis 已記 residue)

[kiki830621]

Verify (PASS)

Engine

Fixture + red-proof based（proportionate：新純函式 helper 全分支 fixture 覆蓋 + red-proof 證明測試有效。未動用 multi-agent ensemble — batch-mode 比例原則，如實揭露）

要求覆蓋率

2/2（silent-wrong-repo 關閉：surface 契約雙向；最上層設定調整 submodule：explicit candidates 覆蓋 auto 即為使用者原話的實現路徑）

Findings

#	Severity	Finding	Source	Action
1	LOW	預設 auto 對依賴舊行為者是 breaking	self	文件化 off 逃生口 + backward-compat 註記（diagnosis 已裁決方向）

驗證證據（fresh）

1. Fixture 8/8（真 git superproject + submodule）
2. Red-proof：helper 回錯值 → 測試抓到（1 FAIL）→ 還原 8/8
3. 四分支（auto/off/非sub/無origin）行為與 surface 契約逐一斷言

結論：ready to merge → /idd-close #162（user 觸發）

[kiki830621]

Closing Summary

Problem: cwd 在 submodule 內時 walk-up 找到 parent config，其 github_repo 靜默吃掉 submodule 操作。
Root Cause: resolution 無 submodule 邊界偵測；「靜默」是 bug class 本體。
Solution: Mechanism 3.5 + lib/resolve-submodule-route.sh（superproject 偵測、submodules: auto|off、owner/repo shape 驗證、雙向 never-silent surface）；explicit candidates 仍優先（使用者原話「最上層設定調整 submodule」的實現路徑）。
Verification: fixture 8/8（真 git super+sub）+ red-proof；merged main 綠。
Changes: d0d0193 → PR #235（merged）。
Residue: nested submodule 遞迴不做（單層覆蓋實戰案例）。