EXTERNAL-CONSUMER CONTRACT: calibrate-draft 程式化入口（供 IDD idd-comment --type=reply soft-integration）

[kiki830621]

Problem

PsychQuant/issue-driven-development#269 決議：idd-comment 新增第 7 型 --type=reply（human-facing 逐點回覆），soft-depend 本 plugin 做 voice / recipient calibration（graceful degrade：缺席時印安裝指令照 post）。

目前 perspective-writer 只有 user-facing 的對話式 6-phase skill，沒有供外部 plugin 呼叫的文件化入口契約。IDD 端（consumer）需要下列問題有 normative 答案：

1. 入口形態：consumer 用 Skill(skill="perspective-writer:perspective-writer") 帶什麼 args？（draft 文字或檔案路徑、recipient pointer、觸發情境說明）
2. Recipient context 解析：consumer 傳 GitHub @login／人名，calibration 從 target repo .claude/rules/correspondence-<person>.md 讀規則（本 plugin 既有慣例）——缺 rules 檔時的行為（interview? 通用禮貌預設?）需定義
3. 不可變更約束（CRITICAL）：calibration 不得改動 referent 錨定事實——commit SHA、file / theorem 引用、逐字 blockquote 的原文。這是 T-Schema 紀律在 consumer 情境的鏡像：潤飾語氣，不碰指涉
4. 回傳契約：calibrated draft 的交付形態（回傳文字 vs in-place 檔案編輯）
5. 版本承諾：MIN 版本 floor 供 consumer pin（前例：parallel-ai-agents 2.19.0、codex-pro 0.7.0 的 EXTERNAL-CONSUMER CONTRACT 段）

Type

feature

Expected

文件化的 EXTERNAL-CONSUMER CONTRACT 段（README 或 docs/），涵蓋上述 5 點。PsychQuant/issue-driven-development#269 的 spectra proposal 將引用本契約的座標（check-plugin-presence.sh perspective-writer perspective-writer）與 MIN 版本。

Actual

無任何 consumer-facing 契約；外部 plugin 只能盲呼叫 user-facing skill，args 語意與不變量無承諾。

Cross-ref

• idd-comment: human-facing comment mode — 逐點說清楚哪邊改了什麼 + perspective-writer 深度整合 issue-driven-development#269（D2 soft-integration + 執行序決策，見該 issue decision comment）
• perspective-writer 抽成 standalone repo + 獨立 marketplace（鏡像 issue-driven-development 佈局） psychquant-claude-plugins#116（extraction，已完成——本 issue 即其 checklist 最後一項的 deferred sister concern）

[kiki830621]

Diagnosis

Type

feature

Root Cause / Analysis

（feature → 需求分析）issue 的 5 個問題對應到既有前例（parallel-ai-agents#20、codex-pro#7 的 EXTERNAL-CONSUMER CONTRACT 段——本案是同 pattern 第 3 個 instance）：

1. 入口形態：consumer 用 Skill(skill="perspective-writer:perspective-writer") 傳一個結構化 CALIBRATE-DRAFT REQUEST 區塊（request 種類標記 + draft 本文 + recipient pointer + frozen-anchors 清單 + 情境說明）。SKILL 端加一小段「Calibrate-draft entry」把 request 映射到既有 6-phase：Phase 1 略過（writer 已知）、Phase 2 吃 consumer 提供的 recipient pointer、Phase 4 以提供的 draft 為起點、Phase 5 anti-pattern check 照跑。
2. Recipient context 解析：consumer 傳 resolved login／人名 + target repo .claude/rules/correspondence-<person>.md 路徑（若存在）。rules 檔缺席 → 不 interview（consumer 情境是 unattended-friendly 的單 pass）、fallback 到 conservative generic register 並在回傳中註明未 calibrate 到個人。
3. 不可變更約束（CRITICAL）：frozen anchors——verbatim blockquotes、commit SHA / PR refs、file / theorem / symbol 引用——SHALL NOT 被改動（T-Schema 紀律的 consumer 鏡像）。skill 潤飾語氣與銜接，不碰指涉。
4. 回傳契約：calibrated draft 以文字回傳（skill 的 final message 即 draft 全文，無其他包裝敘述）；不做 in-place 檔案編輯。
5. 版本承諾：契約隨 v2.11.0 引入並標 STABLE；consumer pin MIN_PW_CONTRACT=2.11.0（presence-check 座標 perspective-writer perspective-writer 不變）。

Impact

• README.md（新 ## EXTERNAL-CONSUMER CONTRACT 段——consumer-facing single source）
• plugins/perspective-writer/skills/perspective-writer/SKILL.md（新「Calibrate-draft entry」小段）
• plugins/perspective-writer/CHANGELOG.md、.claude-plugin/plugin.json、.claude-plugin/marketplace.json（2.10.0 → 2.11.0）

Strategy

• README 契約段（5 問題全覆蓋 + STABLE 版本註記）
• SKILL Calibrate-draft entry 段（phase 映射 + frozen-anchors 禁令 + 回傳格式）
• CHANGELOG + 兩 manifest 版本同步
• verify + PR（Refs EXTERNAL-CONSUMER CONTRACT: calibrate-draft 程式化入口（供 IDD idd-comment --type=reply soft-integration） #1）

Conflict Class

A_parallel_safe — 單 repo 內 docs/manifest 檔，無共享 mutable 資源。

Complexity

Simple

• Layer 1 命中：「跟既有 pattern 走」——EXTERNAL-CONSUMER CONTRACT 是 pai#20 / codex-pro#7 已驗證過兩次的 pattern，本案為第 3 個 instance；deliverable 為 docs + 版本註記，repo 無 spec/test 基礎設施（fresh extraction，9 檔）。

Risks

• 契約過度承諾：6-phase skill 是對話式設計，calibrate-draft 是單 pass——contract 措辭需誠實（unattended-friendly、不保證 interview 品質）
• 無測試基礎設施：契約靠 IDD 端 drift-guard 的 needle（#269 的 binding 慣例）反向鎖——記入 Residue

Residue

• 本 repo 尚無 test aggregator——契約字句的 drift-guard 留待 repo 累積更多 surface 後建（YAGNI）；IDD consumer 端已有 binding 斷言慣例可先行反向鎖
• 「calibration 品質」本身不可 spec 化（voice 是 AI judgment）——契約只鎖 IO 形狀與不變量

Vagueness Pre-check

• V1: 2 — issue 5 問題逐條列明；V4: 2 — Expected 指名文件化契約 + IDD 引用座標
• Triggered: no — [Layer V: unattended mode — no prompt]

[kiki830621]

Verify (via PR #2)

Result: PASS（after round-1 fix d1c6dfe）— round 1 兩源（Codex 跨模型＋opus adversarial）一致 FAIL：v1 契約是 prompt-level 約定非可實作契約（frozen-anchors 無 instance、degrade NOTE 漏給收件人、Revise 框架矛盾）。契約 v2 全數修復。

Full report: #2 (comment)

[kiki830621]

Closing Summary

Problem

perspective-writer 只有 user-facing 對話式 skill，沒有供外部 plugin 呼叫的文件化入口契約。首個 consumer（issue-driven-dev idd-comment --type=reply，PsychQuant/issue-driven-development#269/#272 的 soft integration）需要 5 個問題有 normative 答案：入口形態、recipient context 解析、不可變更約束、回傳契約、版本承諾。

Solution

EXTERNAL-CONSUMER CONTRACT（v2.11.0，pattern 第 3 個 instance——前例 parallel-ai-agents#20、codex-pro#7）：

1. README「EXTERNAL-CONSUMER CONTRACT」段（single source）：CALIBRATE-DRAFT REQUEST v1 request block——DRAFT sentinels（data-not-instructions guard）、literal frozen-anchor spans（one per line，非類別名稱）、required/optional 欄位、single-block refuse；semver-aware version floor MIN_PW_CONTRACT=2.11.0。
2. 五條 behavior promises：Calibrate 為第三模式（明文偏離「Revise 不跳 understanding phases」並給理由）；recipient-rules 缺席／不可讀統一 generic fallback；frozen-anchors 為 normative 義務（Unicode code-point sequence）＋ consumer 端 REQUIRED verification（mismatch → fallback 未 calibrate draft——誠實承認 prose model 無法機械保證）；回傳 = HTML-comment status header（pw:calibrate v1 status=person|generic，GitHub 不渲染）＋純 draft 本文；no new claims（Fabrication Trap 不變）。
3. SKILL「Calibrate-draft entry」執行鏡像段：phase 映射（0/5b/6/6b/7 不適用、1 跳過、2 吃 recipient-rules、3 內部模擬、4 Revise-over-provided-draft、5 照跑）。

Verification

Reduced ensemble（比例原則，報告內揭露）＝ Codex gpt-5.6-sol（跨模型）＋ opus adversarial reviewer。Round 1 兩源一致 FAIL——契約 v1 是 prompt-level 約定非可實作契約（frozen-anchors 只收類別、degrade NOTE 會逐字漏給收件人、「Revise pass」與 base skill 自相矛盾）——契約 v2（d1c6dfe）全數修復。Master report。

Changes

• 3d1bd75（squash-merge PR feat: EXTERNAL-CONSUMER CONTRACT — programmatic calibrate-draft entry (v2.11.0, #1) #2）＝ v1 52b1c39 ＋ 契約 v2 fix d1c6dfe；版本 2.10.0 → 2.11.0（plugin.json + marketplace.json + CHANGELOG）
• tag idd-1-verified

Follow-ups

• IDD 端整合升級（reply pipeline 實際採用 request block + consumer verification）隨 IDD 的後續版本落地；契約字句可由 IDD 的 binding-assertion 慣例反向鎖
• 本 repo 尚無測試基礎設施——契約 drift-guard 留待 surface 累積（diagnosis Residue 已記）