feat: selective auto-tag at idd-issue baseline + idd-verify PASS milestones

[kiki830621]

Problem

IDD lifecycle 目前沒有 git tag 自動化。當一條 issue 進入 implementation 後,如果需要:

• 回到 issue 開 issue 當下的 main HEAD(rollback baseline)
• 抓 verify PASS 那個 PR head snapshot(送 reviewer 看)

只能手動 git tag 或翻 gh pr view commit history。對長 cluster(例 7-phase rewrite)尤其麻煩。

Motivation(來自實戰案例)

PsychQuantHsu/psychophysical_representations#30 three-representation-redo workflow(2026-05-13 完成)做了 8 個 phase commit,手動為每個 phase 打 phase-N-done tag + push 後驗證價值:

• git checkout phase-3-done 切到該 phase snapshot 一秒完成,不用記 commit hash
• git diff phase-1-done phase-2-done 看單 phase diff
• 用 tag 當 stable handle 在 issue comment / PR description 引用

證實 git tag 是輕量 checkpoint 機制(git tag + git push --tags 接近零成本)。但只在 milestone point tag 才能避免 tag pollution — 若每個 IDD lifecycle step(diagnose / strategy / implement / verify / close)都 tag,長期累積會有上百個 stale tag,git tag -l 變雜訊。

Proposed Solution

Selective auto-tag,只在兩個高 value milestone 點打 tag:

1. idd-issue 開 issue 時 → tag idd-{N}-baseline 標 main HEAD(rollback anchor)

   • 命名建議:idd-{issue_number}-baseline,例 idd-30-baseline
   • 觸發點:Step 3 gh issue create 成功 + 拿到 $NUMBER 之後
   • Push:git tag idd-${NUMBER}-baseline && git push origin idd-${NUMBER}-baseline
   • Fork-aware:tag 打在當前 cwd 的 git repo(可能是 upstream 或 own fork,取決於 Step 0.5 解析結果)

2. idd-verify PASS 時 → tag idd-{N}-verified 標 PR head(review-ready snapshot)

   • 命名:idd-{issue_number}-verified
   • 觸發點:Step 3 master report overall verdict = PASS 後
   • Push 兩 repo(若是 cross-repo cluster,例 submodule + upper):各自 tag

中間 lifecycle step(idd-diagnose / idd-strategy / idd-implement)不 tag,因為 PR commit history 已是 timeline,且這些 step 不一定有對應 commit。

Cleanup strategy

idd-close 時:

• 保留 idd-{N}-verified(永久 marker,archive value)
• 可選刪 idd-{N}-baseline(rollback window 已過,issue 已 close)— 或一律保留,反正 tag 是 lightweight

Configuration

加入 .claude/issue-driven-dev.local.json 可選 schema:

{
  "auto_tag": {
    "enabled": true,
    "baseline_format": "idd-{N}-baseline",
    "verified_format": "idd-{N}-verified",
    "push_remote": "origin"
  }
}

auto_tag.enabled: false 對不想用 tag 的 user 完全 opt-out。

Tradeoffs

Pro	Con
接近零成本(git tag + push,< 1s)	Tag namespace 多了 baseline/verified pairs
跨 session stable handle(rollback / review snapshot 一秒可達)	Fork-aware tag 推到哪 remote 要明確(origin 預設應該對)
跟 gh issue 自然關聯(idd-{N}-* naming)	Tag 累積長期不清,但實際上是 feature 不是 bug(audit trail)
Opt-out 簡單(config flag)	多兩個 tag per issue,大 repo 跑久了 git tag -l 結果變多

Implementation notes

• idd-issue Step 0 Bootstrap Task List 新增 tag_baseline step
• idd-verify Step 3 master report PASS branch 結尾 + tag_verified step
• Tag 失敗(remote rejected / permission)不 abort workflow — warning + 繼續(per IDD warn-continue pattern in multi-finding mode)
• 兩 step 都 idempotent:tag 已存在 → skip + log

References

• 實戰 case:PsychQuantHsu/psychophysical_representations#30 — 8-phase rewrite 手動 tag 驗證 pattern
• Summary comment 展示 tag-based timeline:comment-4435926399
• 跟既有 idd-verify warn-continue pattern 一致

Discussion seed

• 命名 convention idd-{N}-baseline / idd-{N}-verified 是否會跟現有 IDD user 的 tag pattern 衝突?
• Fork-aware(Step 0.5 解析後)tag 是否要 push 到 upstream 還是 own fork?預設 origin
• 跨 repo cluster(submodule 模式)是否兩邊都 tag?或只 tag 上層 + cross-link?