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?

---

Current Status

Phase: closed
Last updated: 2026-07-10 by /idd-close (#85)

Key Decisions

• Complexity = Plan、C_shared（idd-verify/SKILL.md 與 [bug] /idd-verify Devil's Advocate Agent role socket crash — 2x consecutive timeouts in #119 round 2 (closing follow-up from #119) #130/parallel-ai-agents 深度整合：升格 install-time dependency（比照 superpowers #209 模式） #219；idd-issue 與 cluster）
• Next: 排 [bug] /idd-verify Devil's Advocate Agent role socket crash — 2x consecutive timeouts in #119 round 2 (closing follow-up from #119) #130 → parallel-ai-agents 深度整合：升格 install-time dependency（比照 superpowers #209 模式） #219 → feat: selective auto-tag at idd-issue baseline + idd-verify PASS milestones #85 相鄰序列

[kiki830621]

Diagnosis

Type

feature（selective git-tag 自動化 — 2 個 milestone 點）

Root Cause / Analysis

需求與反需求都已由 issue 定案：tag 的價值（stable handle、rollback anchor、phase diff）經 PsychQuantHsu#30 實戰驗證；tag pollution 的反面約束同時成立 → selective（僅 baseline + verify-PASS 兩點）是已裁決的平衡點。命名 idd-{N}-baseline / verify-PASS snapshot tag 由 issue 給定。

實作面：idd-issue Step（建案後 git tag idd-{N}-baseline main-HEAD + push --tags）與 idd-verify PASS 路徑（tag PR head）各加一小段；direct-commit/PR 兩 path 的 tag 對象語意需分別定義（PR path = branch head；direct-commit = 當前 HEAD）。

Impact

• skills/idd-issue/SKILL.md、skills/idd-verify/SKILL.md 各一小段 + config opt-out key（auto_tag: false）
• Repo 端：每 issue ≤2 tags

Strategy

• idd-issue：建案成功後 tag idd-{N}-baseline（config auto_tag 預設 on、可關）+ push
• idd-verify：Aggregate PASS 後 tag idd-{N}-verified（PR head 或 HEAD）+ push
• 冪等：tag 已存在 → skip with note（re-verify 場景不重打）
• config-protocol.md schema 增 auto_tag；README 慣例段
• 測試：tag 命名/冪等 fixture

Conflict Class

C_shared_module_coord — 共享資源：skills/idd-verify/SKILL.md（與 #130/#219 同檔）+ skills/idd-issue/SKILL.md（cluster branch 已動）；排 #130/#219 之後、cluster merge 之後。

Complexity

Plan

Layer P 命中：2+ 檔案 + 觸及 push 類 irreversible side effect（tag push）。
[Plan tier deliberation skipped under unattended mode]

Risks

• push --tags 對 fork/無 push 權限場景 fail — 包 graceful skip + note

Residue

Phase-level tag（PsychQuantHsu#30 的 per-phase 用法）刻意不自動化 — pollution 判準；留手動。

Vagueness Pre-check

• V1: 1 — 兩個 tag 點與命名由 issue 給定
• V4: 2 — 完成 = 兩接點 + opt-out + 冪等 + 測試
• Triggered: no

[Layer V: V1=1 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 Plan (Plan tier)

Selective git auto-tag at two IDD milestones. The SKILLs are prose (AI prompts), so this adds prose tag-steps + a config schema + a content drift-guard (consistent with every other IDD suite). TDD: the drift-guard is written first (RED — asserts prose that doesn't exist yet), then the prose lands (GREEN).

Files & Changes

• references/config-protocol.md — new ### auto_tag field under ## Schema (full, extended) (next to pr_policy / collaborators[]). Schema: { enabled, baseline_format, verified_format, push_remote } with defaults, opt-out semantics, and a one-line note that tag push is a repo-wide side effect. Defines the shape the two SKILLs reference — lands first.
• skills/idd-issue/SKILL.md — Step 0 bootstrap gains a tag_baseline step; after create_issue succeeds and $NUMBER is captured, tag idd-{N}-baseline at the local default-branch HEAD (the rollback anchor = "where main was when the issue opened") + push. Gated on auto_tag.enabled; idempotent (tag exists → skip + note); graceful-skip on push failure (warn + continue, never abort — per IDD warn-continue).
• skills/idd-verify/SKILL.md — Step 0 bootstrap gains a tag_verified step; after the master-report Aggregate PASS verdict, tag idd-{N}-verified at the PR head (PR mode) or current HEAD (local mode) + push. Same gate / idempotency / graceful-skip.
• scripts/tests/auto-tag/test.sh — new drift-guard (assert-helpers): idd-issue encodes the baseline tag step + auto_tag gate + idempotency + graceful-skip; idd-verify encodes the verified tag step on the PASS branch; config-protocol documents the auto_tag schema + all four keys. Written RED-first.
• README.md (plugin) — a short "auto-tag convention" note (naming idd-{N}-baseline / idd-{N}-verified, opt-out) so users discover it.

Sequencing & Dependencies

1. config-protocol.md schema (defines auto_tag shape). 2. auto-tag/test.sh RED (asserts the not-yet-written prose). 3. idd-issue + idd-verify prose (GREEN). 4. README note. Prereqs [bug] /idd-verify Devil's Advocate Agent role socket crash — 2x consecutive timeouts in #119 round 2 (closing follow-up from #119) #130/parallel-ai-agents 深度整合：升格 install-time dependency（比照 superpowers #209 模式） #219 already shipped; cluster feat: discussion-type issue metadata helper — assignee / label / milestone / native relationships auto-surface #141/bug-prevention: #141 discussion-metadata helper must verify label existence + surface UI cache-sync hint #142 merged — the C_shared coordination constraint is cleared.

Decision Points (your call at approval)

1. Config default — the one real design choice. The issue proposes auto_tag.enabled: true (default-ON, opt-out). I'd recommend default-OFF / opt-in instead: default-ON makes every IDD user's idd-issue silently git push tags to their remote — a repo-wide side effect they didn't ask for (and the issue's own framing is pollution-averse). Opt-in keeps zero surprise; the power of the feature is unchanged for anyone who sets enabled: true. Your call: keep default-ON per the issue, or flip to opt-in?
2. Path: pr_policy is unset. Recommend PR path (matches how the other features this session landed — clean review surface), but direct-commit is fine for this solo repo if you prefer speed.
3. Baseline tag target = local default-branch HEAD; verified tag = PR head (PR) / HEAD (local) — per the diagnosis. Flag if you'd rather baseline track the current branch instead.

Risks & Mitigations

• Irreversible side effect (tag push) — the reason this is Plan tier. Mitigated by: opt-out config, idempotent skip, and graceful-skip on any push failure (fork / no-permission / remote-reject → warn + continue, never abort the workflow).
• Tag namespace collision — idd-{N}-* is namespaced; idempotent skip if the tag already exists (re-verify never re-tags).

Test Plan

auto-tag/test.sh (prose drift-guard, RED→GREEN): baseline-step tokens in idd-issue, verified-step tokens in idd-verify (PASS branch), auto_tag schema + 4 keys in config-protocol, gate/idempotency/graceful-skip phrases present. This is the falsifiable form for prose SKILLs (same as collaborators-schema / discussion-metadata).

Out-of-scope (will NOT be touched)

• idd-close tag cleanup — the Strategy deliberately omits it; tags are lightweight, keep both, manual delete if ever wanted.
• Phase-level tags — deliberately manual (Residue: pollution criterion).
• Cross-repo cluster dual-tag (submodule mode) — Lean-v1 tags the cwd repo only; dual-tag across submodule + upper is deferred (documented, not done).
• Actual git tag execution tests — SKILLs are prose; the drift-guard asserts the prose, it doesn't run git.

Tangential Observations (filed mid-plan)

none surfaced — the diagnosis is tight and the scope is self-contained.

---

Approved 2026-07-09 (plan-mode) — resolved decisions: (1) auto_tag.enabled default ON (opt-out via enabled:false), per the issue; (2) PR path (idd/85-auto-tag → PR). Chaining to /idd-implement #85 --pr.

[kiki830621]

Implementation Complete

Checklist (synced from TaskList)

• references/config-protocol.md — ### auto_tag field schema (enabled default-on / baseline_format / verified_format / push_remote) + PII-style side-effect note → commit 32008b7
• scripts/tests/auto-tag/test.sh — drift-guard, 27 assertions, written RED-first (7 pass / 20 fail before prose) → GREEN after → commit 32008b7
• skills/idd-issue/SKILL.md — Step 3.6 tag_baseline: idd-{N}-baseline at local default-branch HEAD, auto_tag gate, idempotent, graceful-skip (never abort) → commit 32008b7
• skills/idd-verify/SKILL.md — Step 4.5 tag_verified: idd-{N}-verified at Aggregate-PASS snapshot (PR head / HEAD), cluster-aware, idempotent, graceful-skip → commit 32008b7
• README.md — "Selective auto-tag" convention note (default-on, opt-out, side-effect) → commit 32008b7

Legend: - [x] done · - [~] skipped · - [-] won't fix

Changes

• 32008b7: feat: selective git auto-tag at idd-issue baseline + idd-verify PASS (feat: selective auto-tag at idd-issue baseline + idd-verify PASS milestones #85)

Files Changed

5 files, +173 (config-protocol.md, idd-issue/SKILL.md, idd-verify/SKILL.md, README.md, tests/auto-tag/test.sh)

Resolved decisions (from the approved Plan)

• auto_tag.enabled default-ON (opt-out via enabled: false) — per the issue.
• PR path (idd/85-auto-tag).

Out-of-scope (as planned)

• idd-close tag cleanup, phase-level tags, cross-repo cluster dual-tag — all deferred/manual per the diagnosis Residue.

Verification

• auto-tag/test.sh 27/27 PASS (RED→GREEN); full plugin suite green, no regressions.

Next: verification pending — /idd-verify #85 --pr <N>

[kiki830621]

Closing Summary

Problem

IDD had no git-tag automation. When an issue enters implementation you often need to jump back to (a) main's HEAD at issue-open time (rollback baseline) or (b) the verify-PASS snapshot (to hand a reviewer) — which meant a manual git tag or digging through gh pr view history, especially painful on long clusters.

Root Cause / Need

No selective tag mechanism. A real case (PsychQuantHsu/psychophysical_representations#30, an 8-phase rewrite) proved git tag is a near-zero-cost checkpoint handle — but only if placed selectively at milestones, or a long-running repo accumulates hundreds of stale lifecycle tags.

Solution

Selective auto-tag at exactly two high-value milestones (Plan tier, approved default-ON + PR path):

• idd-issue → idd-{N}-baseline at the local default-branch HEAD (rollback anchor), after issue creation (Step 3.6).
• idd-verify → idd-{N}-verified at the Aggregate-PASS snapshot (review-ready), before restore_working_tree so HEAD is the PR head (Step 4.5); cluster-aware (tags each ref'd #N).
• Config auto_tag (enabled default-on + opt-out via enabled: false, baseline_format / verified_format / push_remote), documented with an explicit repo-wide-side-effect note.
• Idempotent (existing tag → skip; re-runs never re-tag) and graceful-skip on any push failure (fork / no-permission / rejected → warn + continue, never aborts the workflow). Intermediate steps (diagnose / plan / implement) are deliberately not tagged.

Verification

• Landed on main via PR feat: selective auto-tag at idd-issue baseline + idd-verify PASS milestones #250 (0aa17a5 feat + df99960 review-fix; rebase-merged, no 502).
• scripts/tests/auto-tag/test.sh — 27/27 PASS on main (drift-guard, written RED→GREEN); CI suites: SUCCESS; full plugin suite green, no regressions.
• Self-review caught + fixed two defects in-PR (not merge-then-followup): the idd-verify snippet used an undefined $CONFIG_PATH (idd-verify has no find_idd_config) → now resolves the walked-up config inline; and undefined+unnecessary $INPUT_SOURCE/$PR_HEAD_SHA → simplified to HEAD (correct, since tag_verified runs before restore_working_tree).

Residue Acknowledgement

Diagnosis residue — phase-level tags (the per-phase phase-N-done usage from PsychQuantHsu#30) are deliberately NOT automated (pollution criterion) — is acknowledged as-is: only the two milestone points are auto-tagged; phase-level tagging stays manual by design. No follow-up filed. (One accepted-by-spec behavior noted in review: a git tag that succeeds while git push fails leaves a local-only tag that the idempotent skip won't retry-push — the local tag still provides checkout value; this is the issue's own graceful-skip + idempotent-on-exists spec.)

Changes

• 0aa17a5 feat: selective git auto-tag at idd-issue baseline + idd-verify PASS — via PR feat: selective auto-tag at idd-issue baseline + idd-verify PASS milestones #250
• df99960 fix: correct idd-verify auto_tag snippet — walk-up config + snapshot=HEAD — via PR feat: selective auto-tag at idd-issue baseline + idd-verify PASS milestones #250