fix: README gpt-5.5 pin + docs catalog drift (v2.97-2.99 backfill) — expand drift-guards to README/docs

[kiki830621]

Problem

v2.97–2.99 三版連發後，兩類 staleness + 一個 guard 覆蓋缺口：

1. README hard-pin 違規：plugins/issue-driven-dev/README.md:62「Independent verification using Codex CLI (gpt-5.5)」— idd-verify / idd-route / bin/codex-call 的 gpt-5.5 hardcode 落後 GPT 新世代（sister concern from codex-pro#3） #251/refactor: codex channel goes full-dependency — delete vendored codex-call; executable from pai, governance from codex-pro (superpowers-style) #264 立的 zero-pin 契約被 README 漏網，因為 model-generation-sync drift-guard 只掃 SKILL/references，不掃 README 與 docs/。同表也缺 idd-clarify / idd-find / idd-ask。
2. docs/ catalog 再次 drift（[IDD][design] Enforce strict separation: idd-issue → idd-diagnose → idd-all / idd-all-chain (no auto-swallow diagnose) #122 剛修完的同一 class）：docs/workflows.md 對 idd-find / idd-ask 零提及；docs/skill-dimensions.md 僅 D12 slot 一筆。v2.97–2.99 的新內容（find / ask / verify profiles / dashboard+rollup）未回填。bonus：idd-config 從未進過任一 docs（pre-[IDD][design] Enforce strict separation: idd-issue → idd-diagnose → idd-all / idd-all-chain (no auto-swallow diagnose) #122 legacy gap，[IDD][design] Enforce strict separation: idd-issue → idd-diagnose → idd-all / idd-all-chain (no auto-swallow diagnose) #122 亦漏）。
3. 根因（[IDD][design] Enforce strict separation: idd-issue → idd-diagnose → idd-all / idd-all-chain (no auto-swallow diagnose) #122 診斷已指出、本案再證）：catalog 無機制強制回填 — 靠人發現。

User Ruling（2026-07-18）

「都做，1+2 立案開修」— 含結構性防範（drift-guard 擴掃）。

Type

fix（staleness）+ infra（guard 覆蓋）

Expected

1. README：gpt-5.5 → 世代中立；skill 表補 surfacing family（clarify/find/ask）
2. docs/workflows.md：G 段補 P-find-lookup / P-ask-history、E 段補 verify file-profile 變體、G 段補 report-rollup；matrix 補 idd-find / idd-ask / idd-config 列；尾注記 2026-07-18 iteration
3. docs/skill-dimensions.md：matrix 補 idd-find / idd-ask / idd-config 列；skill 清單行更新
4. 結構性防範 A：model-generation-sync refute 清單擴及 README + docs/（pin 漏網即紅）
5. 結構性防範 B：新 drift-guard docs-catalog-sync — 每個 skills/*/ 目錄名必須出現在 docs 任一檔（[IDD][design] Enforce strict separation: idd-issue → idd-diagnose → idd-all / idd-all-chain (no auto-swallow diagnose) #122 class 從「靠人發現」變「靠測試發現」）

Actual

README 帶 stale pin；docs 缺 3 個 skill；兩者都不在任何 guard 的掃描範圍。

Impact

• zero-pin 契約閉環（下次換代 README/docs 不可能再漏）
• [IDD][design] Enforce strict separation: idd-issue → idd-diagnose → idd-all / idd-all-chain (no auto-swallow diagnose) #122 的根因獲得機制解 — 新 skill 落地忘記回填 docs 會直接紅
• 與 workflows.md 尾注「就地補不另開 issue」裁決的關係：本案 scope 超出就地補（pin 違規 + guard 基建），故立案；純 path 回填部分仍遵循該裁決精神一次收齊

---

Current Status

Phase: closed

[kiki830621]

Diagnosis

Root Cause

兩層：(1) 表層 — v2.97–2.99 三版連發，README/docs 的回填沒跟上（#122 class 復發）+ README 的 model 記載停在 #251 之前；(2) 根因 — 兩個 drift-guard 的掃描邊界都劃在 plugin 樹內（SKILL/references），README 與 repo 級 docs/ 從未入網。沒有 guard 的檔案必然 drift — #122 修 content 沒修 mechanism，本案補上 mechanism。

Strategy（= 2026-07-18 使用者已核可的三點方案）

• README：gpt-5.5 → 世代中立 + skill 表補 surfacing family
• docs 回填：workflows.md（P-find-lookup / P-ask-history / verify file-profile / report-rollup + matrix 三列 + 尾注）；skill-dimensions.md（matrix 三列 + 清單行）
• 防範 A：model-generation-sync refute 擴及 README + docs/
• 防範 B：新 suite docs-catalog-sync — skills/*/ 目錄名 ∈ docs 任一檔（機制解 [IDD][design] Enforce strict separation: idd-issue → idd-diagnose → idd-all / idd-all-chain (no auto-swallow diagnose) #122 根因）

Conflict Class

A_parallel_safe — 無其他 open issue 動這些檔。

Complexity

Plan via hard-gate

Hard-gate: triggered — 單一概念（docs/guard 同步）散佈 README + 2 docs + 2 test suites ≥ 5 檔。Plan 審批已由使用者裁決消化（2026-07-17 #122 尾注裁決確立就地補精神 + 本日「都做，1+2 立案開修」對三點方案的核可 = approved Implementation Plan），不重跑 EnterPlanMode 儀式 — 此判斷記入 audit trail。

Risks

• docs-catalog-sync 的字面比對可能誤紅（skill 名是其他詞的子字串？逐一檢視：idd-* 前綴唯一性足夠）；guard 只 assert 提及、不 assert 品質 — 品質仍靠人

Residue

docs/ 其他檔（design-patterns/ 等）不入掃描網 — 只鎖 workflows.md + skill-dimensions.md 兩個 catalog 檔（catalog 才有「全集完整性」語意）

Vagueness Pre-check

• V1: 1 — 三點方案已核可
• V4: 1 — 完成 = 兩 suite GREEN + sweep 0 fail
• Triggered: no

[Layer V: V1=1 V4=1, not triggered; attended]
Source: /idd-diagnose attended, 2026-07-18

[kiki830621]

Implementation Complete

PR: #268（idd/267-docs-pin-sync）

Checklist

• README：3 根 gpt-5.5 pin 世代中立化（skill 表 / dependency 表 / prerequisites）+ stale「Vendored codex-call / 三層 degrade」敘述修正（refactor: codex channel goes full-dependency — delete vendored codex-call; executable from pai, governance from codex-pro (superpowers-style) #264 現實：兩層 + pai executable + codex-pro 治理）+ surfacing family 補列
• docs/workflows.md：P-find-lookup / P-ask-history / P-report-rollup / P-config-maintain / P-verify-file-profile 五 path + matrix 三列 + 2026-07-18 尾注
• docs/skill-dimensions.md：matrix 補 idd-find / idd-ask / idd-config 列 + D12 行第 4 員
• 防範 A：model-generation-sync refute 網擴及 README + catalog docs（31 assertions；擴網後當場多抓到 2 根手掃漏掉的 pin）
• 防範 B：新 suite docs-catalog-sync（RED 抓到 idd-ask + idd-config → GREEN 19/19）— [IDD][design] Enforce strict separation: idd-issue → idd-diagnose → idd-all / idd-all-chain (no auto-swallow diagnose) #122 根因機制解
• 全 sweep 38 suites 0 fail

過程備註

Plan via hard-gate；Plan 審批由使用者 2026-07-18「都做，1+2 立案開修」對三點方案的核可消化（記於 Diagnosis）。

[kiki830621]

Closing Summary

Problem：v2.97–2.99 三版連發後 README 帶 stale gpt-5.5 pin（實為 3 根 + 一段 stale vendored 敘述）、docs catalog 缺 idd-find / idd-ask（+ pre-#122 的 idd-config legacy gap）。根因：兩個 drift-guard 的掃描邊界都不含 README 與 docs/ — 沒有 guard 的檔案必然 drift（#122 修了 content 沒修 mechanism）。

Solution（PR #268）：README 3 pin 世代中立化 + dependency 表同步 #264 現實；docs 回填至 v2.99（五 path + matrix 三列 + D12 第 4 員）；結構性防範雙向 — model-generation-sync refute 網擴及 README + catalog docs（31 assertions），新 suite docs-catalog-sync 要求每個 skills/*/ 目錄名出現在 catalog docs（#122 根因從「靠人發現」變 test-detectable）。

Verification：擴網後 guard 當場多抓 2 根手掃漏掉的 pin（機制自證）；docs-catalog-sync RED 精準抓 idd-ask + idd-config → GREEN 19/19；全 sweep 38 suites 0 fail；PR #268 review + merged。

Changes：README、docs/workflows.md、docs/skill-dimensions.md、兩個 test suite。

Residue：docs/ 其他檔（design-patterns/ 等）刻意不入掃描網 — 只有 catalog 檔有「全集完整性」語意（diagnosis 已記）。

Distribution sync：v2.99.1（本 session 隨後發版，patch — staleness fix）。

[kiki830621]

📊 For Reviewer / Collaborator

現在：README 3 pin 修正 + docs 回填至 v2.99 + 兩個 drift-guard 擴網（#122 根因機制解），PR #268 merged
Blocking：無
你該做什麼：無 — 已結案（詳見 Closing Summary）

last-updated by idd-close at closed, 2026-07-18