[docs] IDD_CALLER env var registry — codify allowed values + semantics (sister from #154) #161

Problem

Source: surfaced during /idd-implement #154 reproduction (Step 5.7)

IDD_CALLER=<value> env var 慣例在 5+ IDD scripts 散布使用,無中央註冊表 docs 列出 allowed values + semantics。 PR #159 (#154 impl) 又新增 IDD_CALLER=idd-comment-errata → 第 6+ value。 Drift 風險穩定累積。

Current usage (sampled via grep)

plugins/issue-driven-dev/skills/idd-close/SKILL.md:    IDD_CALLER=idd-close
plugins/issue-driven-dev/skills/idd-verify/SKILL.md:   IDD_CALLER=idd-verify
plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md: IDD_CALLER=idd-diagnose
plugins/issue-driven-dev/skills/idd-implement/SKILL.md:IDD_CALLER=idd-implement
plugins/issue-driven-dev/skills/idd-comment/SKILL.md (post #154): IDD_CALLER=idd-comment-errata

加上 scripts/process-attachments.sh 讀取它記錄到 manifest fetched_by field — 是 cross-skill contract,但 contract 沒 doc。

Open questions

• Allowed values:該限制到 skill name 集合(idd-*)?或允許子 mode(idd-comment-errata 風格)?
• Semantics:env var 用途是什麼?audit trail(記誰呼叫 helper)?conditional behavior(helper 根據 caller 調整 output)?兩者皆是?
• 註冊地點:docs/idd-caller-registry.md?還是 inline 在 references/ 已有檔案?
• Validation:script 要驗 IDD_CALLER 在 allowed list 否則 warn?或保留 informal?
• Default behavior when unset(目前似乎是 empty string + 一些 scripts 對 empty 有 fallback,但行為不一致)

Impact

No immediate bug — 現在 5 個 SKILL.md + 1 helper script 用得相容。 但:

• 新 IDD_CALLER value 加入時無 review surface(本 PR 加 idd-comment-errata 就是 silent)
• helper script 若想 conditional 行為(e.g. validate-target 對 errata flow 改 message),沒明文 contract
• 未來 IDD plugin user 寫 plug-in helper 時不知該用什麼 IDD_CALLER value

Type

documentation / convention codification

Trigger conditions (parking-lot)

• ≥1 new IDD_CALLER value 加入(本 PR 已 trigger 一次,所以 rule-of-three 已過)
• ≥1 helper script 想對 specific caller 行為差異化 → 需 documented contract
• 任一 IDD plugin user 開 issue 問「我 own script 該設什麼 IDD_CALLER」

Strategy

1. 集中 grep IDD_CALLER= 列出 current values + usages
2. 寫 plugins/issue-driven-dev/references/idd-caller-registry.md 或 similar
3. Schema:每個 value 列出 (a) which skill emits it (b) which helper reads it (c) semantic intent
4. Helper scripts 可選擇 validate(warn if unknown caller)或不 validate(informal)
5. SKILL.md 寫 IDD_CALLER 處 cross-link 到 registry

Priority

P3 — parking-lot until friction surfaces。 文件性 follow-up,non-blocking。

Refs #154

Current Status

Phase: closed
Last updated: 2026-07-11 by /idd-close

Key Decisions

• Complexity = Simple（docs registry；rule-of-three 已 trigger）— 本輪 drain 內 implement