multi-finding mode: jsonl run log 被 repo .gitignore 阻擋(.claude/ 是常見 gitignore pattern,衝突 D2 commit 默認)

[kiki830621]

Problem

Source: surfaced during /idd-issue multi-finding mode dogfood (kiki830621/teaching_lesley 0509 transcript), 2026-05-10

Spec contract D2(idd-issue-multi-finding-source Requirement: "JSONL run log SHALL be committed to git by default")要求 .claude/.idd/issue-runs/<run_id>.jsonl 進 git。

但 Lesley project .gitignore:6 是 .claude/ — 把整個 .claude/ 目錄全部 gitignore(這是常見的 IDE-config gitignore pattern,因為 .claude/ 通常含 cache、attachments、local config 等不該 commit 的東西)。

實際 dogfood 結果:

• jsonl 寫入 .claude/.idd/issue-runs/2026-05-10T05:29:26.jsonl ✓
• git status 不顯示 untracked(被 .claude/ 阻擋)
• D2 spec contract 「commit jsonl by default」violated

Type

bug (spec gap surfaced by real-world dogfood)

Impact

• Cross-machine continuity 假設失效:user 移到別 machine 看不到先前 run log
• D2 spec contract violated
• 任何 repo .gitignore 含 .claude/ 都遇到同問題

Proposed fix

Stage 4.5 加 pre-flight gate:

# Check if .claude/.idd/issue-runs/ is gitignored
if git check-ignore -q .claude/.idd/issue-runs/2026-05-10T00:00:00.jsonl 2>/dev/null; then
  AskUserQuestion(
    question = "repo .gitignore 阻擋 .claude/.idd/issue-runs/ — multi-finding jsonl 無法進 git。怎麼處理?",
    options = [
      "Add exception 到 .gitignore"  → append `!.claude/.idd/issue-runs/`
      "Skip commit (jsonl 本地存但不進 git)"  → 接受 cross-machine continuity 失效
      "Abort"  → 退出 dispatch
    ]
  )
fi

或者改 jsonl 預設 path 到 non-.claude/ location(e.g. idd-runs/ at repo root)— 但 break 既有 .claude/.idd/ 統一 convention。

Related

• idd-issue: 加入 multi-finding source 的 triage 機制（避免每筆 finding 手動分 create/update/comment/edit） #48 (parent — multi-finding mode change)
• D2 contract violation

---

Current Status

Phase: diagnosed
Last updated: 2026-05-10 by idd-diagnose (batch)

Key Decisions

• Complexity = Plan (Layer P 命中: risk-sensitive .gitignore 改動 + decision-heavy fix path)
• Layer V untriggered (V1=2 V4=3)
• 推 pre-flight gate at Stage 4.5(不 break .claude/.idd/ namespace)

Blocking

• 等 user 跑 /idd-plan multi-finding mode: jsonl run log 被 repo .gitignore 阻擋(.claude/ 是常見 gitignore pattern,衝突 D2 commit 默認) #55

[kiki830621]

Diagnosis

Type

bug (D2 spec contract violation surfaced by real-world dogfood)

Analysis

idd-issue-multi-finding-source D2 contract: 「JSONL run log SHALL be committed to git by default」。但 .claude/.idd/issue-runs/<run_id>.jsonl 在 repo .gitignore 含 .claude/ 這個常見 pattern 時被阻擋。Default 行為 silent fail — D2 violated 但 user 無 surface。

Issue body 已提兩個 fix direction:

• Pre-flight gate at Stage 4.5(idd-issue dispatch 期間)— git check-ignore -q 偵測 + AskUserQuestion 3-option (add exception / skip commit / abort)
• Move default path out of .claude/.idd/issue-runs/ to non-gitignored location (e.g. repo root idd-runs/)

兩個 trade-off:

• Pre-flight gate 保留 .claude/.idd/ namespace convention,但每個 dispatch 多一個 gate
• Move path break 既有 .claude/.idd/ convention,但解 root cause(default path 不衝突)

推 pre-flight gate:.claude/.idd/ namespace 是 v2.35.0+ migration 後的 IDD convention,break 影響更大;gate 加一次 (idempotent — 加完 .gitignore exception 之後不再 fire)。

Impact

• 影響的工作流:/idd-issue multi-finding mode(Stage 4.5 dispatch with jsonl run log)
• 影響的檔案:
  • plugins/issue-driven-dev/skills/idd-issue/SKILL.md Stage 4.5 加 pre-flight git check-ignore
  • 可能新增 references/multi-finding-mode.md doc(若 need explicit gate spec)
• Backward compat:既有 repo 已 ignore .claude/ 的會 fire AskUserQuestion;非 ignore repo 完全不受影響

Strategy

• Stage 4.5(jsonl 寫入前)偵測 git check-ignore -q "$JSONL_PATH" 是否 true(被 ignore)
• 若被 ignore → AskUserQuestion 3-option:
  • Add exception 到 .gitignore → append !.claude/.idd/issue-runs/ to .gitignore,commit .gitignore 改動 + jsonl
  • Skip commit (jsonl 本地存但不進 git) → 寫 jsonl 但不 git add,在 dispatch summary 標明 cross-machine continuity 失效
  • Abort → exit dispatch,不寫 jsonl
• 若沒被 ignore → silent pass(現行行為)
• (out of scope) idd-update / idd-list 等讀 jsonl 的 skill 加 cross-machine continuity check
• Audit trail entry 寫進 idd-issue dispatch summary report

Complexity

Plan (Layer P 命中)

理由:

• Risk-sensitive boundary:.gitignore 改動是 user-facing 行為改變(append !.claude/.idd/issue-runs/)— 風險中等,動手前該 explicit Implementation Plan 讓 user 看
• Decision-heavy:default option (Add exception) 需要 user 接受改 .gitignore;若 user 不想動 .gitignore 必須 explicit fall back 到 skip
• 跨 file:SKILL.md + 可能 reference doc + dispatch summary template
• 不符 Spectra:沒對外暴露新 API surface,純 internal pre-flight enhancement

Layer V — vagueness check:

• V1: 2 — fix explicit (3-option AskUserQuestion + git check-ignore detection)
• V4: 3 — Acceptance criteria 隱含但 clear (D2 contract restored,user gets surface)
• Triggered: no

Risks

• .gitignore exception 順序:!.claude/.idd/issue-runs/ 必須在 .claude/ ignore 之後出現才 work(git ignore parsing 是 line-order)。Mitigation:Stage 4.5 用 printf '\n%s\n' '!.claude/.idd/issue-runs/' >> .gitignore append at end,不插中間
• .claude/ 沒被 ignore 但 sub-pattern 被 ignore 的 repo(罕見):pre-flight 仍 fire,user 困惑為何 prompt。Mitigation:AskUserQuestion 描述明確標出 detected ignore source line
• Multi-machine continuity 失效:若 user 選 skip,cross-machine 無法 resume run。Mitigation:dispatch summary 顯眼標明 + 提供 manual export command

Recommended Path

Plan → /idd-plan #55(EnterPlanMode 對齊 .gitignore 改動授權)。

不走 Spectra:no public API contract change,internal 行為改進。