fix: README pins + docs catalog backfill — drift-guards extended to README/docs

docs/skill-dimensions.md

@@ -206,7 +206,7 @@ IDD plugin 已累積 14+ skills(`idd-issue` / `idd-diagnose` / `idd-implement` /
 
 下列 dimensions 是 AI agent 從 corpus distill 不出,但 user 可能已有的:
 
-- **D12**: **Surfacing vs Lifecycle**（#140 定義完成，v2.97.0）— surfacing-only primitive family：idd-list / idd-clarify / idd-find。canonical 定義（軸對照表、雙向鐵律、增員判準）見 [`plugins/issue-driven-dev/references/surfacing-primitives.md`](../plugins/issue-driven-dev/references/surfacing-primitives.md)
+- **D12**: **Surfacing vs Lifecycle**（#140 定義完成，v2.97.0）— surfacing-only primitive family：idd-list / idd-clarify / idd-find / idd-ask（#72，v2.99 第 4 員）。canonical 定義（軸對照表、雙向鐵律、增員判準）見 [`plugins/issue-driven-dev/references/surfacing-primitives.md`](../plugins/issue-driven-dev/references/surfacing-primitives.md)
 - **D12-alt**: ? (cost / token / time 維度?)
 - **D13**: ? (cross-repo / cross-skill 整合?)
 - **D14**: ? (retroactive vs forward-looking?)
@@ -235,6 +235,9 @@ IDD plugin 已累積 14+ skills(`idd-issue` / `idd-diagnose` / `idd-implement` /
 | `idd-edit` | Sep | Atom | Side | W | (任) | S / Batch | SHALL preview before write | Att-only | Sk | Cl-non |
 | `idd-list` | (n/a) | Atom | n/a | R | (查) | S | n/a | Unatt-capable | Sk + flags | Cl-non |
 | `idd-clarify` | Sep | Atom | Delib(surface-only) | W (annotation block) | Fwd | S | SHALL hard-gate consumer (diagnose Step 0.5) | Unatt (deferred-row 機制 #137) | Sk + flags | Cl-non |
+| `idd-find` | (n/a) | Atom | n/a | R | (查) | S | n/a | Unatt-capable | Sk + flags | Cl-non |
+| `idd-ask` | (n/a) | Atom | n/a | R | (查) | S | SHALL grounded (claim 必附引用) | Unatt (推題搜 + audit line) | Sk + flags | Cl-non |
+| `idd-config` | (n/a) | Atom | n/a | R (show/which) / W (init) | (n/a) | S | SHALL validate schema | Att | Sk + subcommands | Cl-non |
 | `idd-report` | Sep | Atom | Side | W | Bwd | S | SHALL aggregate | Att | Sk | Cl-non |
 | `idd-route` | (n/a) | Atom | n/a | R (recommend) / W (record) | (查) | S | n/a | Unatt-capable | Sk | Cl-non |
 | `idd-all` | **Auto (Hyb degraded)** ⚠ | Orch | (跨 D / E / Side) | W | (跨) | S / Batch (v2.83 conflict-class ordered) / Cluster | mostly SHALL but soft Phase 0.4 | Hyb | Sk + flags | Cl-non |

docs/workflows.md

@@ -262,6 +262,17 @@ idd-verify --pr 71
 - **Assumptions**:PR 已 reference 某 issue(`Refs #N` / `Closes #N`)
 - **Risk**:低 — verify 是 read-only verification,findings post 成 comment
 
+#### P-verify-file-profile — 非 code deliverable 驗證（#258，v2.97+）
+
+```
+idd-verify #N --profile prose --file report.md
+```
+
+`--profile`（code 預設不變 / prose / academic / config 自訂）切換 lens 四元組；`--file`/`--dir` 輸入源讓 git worktree optional（posting target 仍照 config 解析）。File-mode freshness gate = SHA-256 snapshot（#228 的非 git 等價物，不豁免）。
+
+- **Use case**：學術/臨床 prose、信件、報告的 ensemble 驗證；非 git workspace
+- **Risk**:低 — 同 P-pr-verify 的 read-only 性質；lens 品質見 `references/verify-profiles.md`
+
 #### P-pr-verify-then-merge
 
 ```
@@ -355,6 +366,34 @@ idd-edit comment:NNN --append --body "..."
 - **Use case**：issue body 用詞/語意精度審查；retroactive audit
 - **Risk**：low — 唯一副作用是 annotation block 寫入
 
+#### P-find-lookup — 語意查找（#139，v2.97+）
+
+`idd-find "<free-text query>"` → open+closed 全語料 GitHub relevance 排序 + phase / PR overlay。建案前查重、找舊案考古。surfacing-only、read-only；filter flags 拒收（導流 idd-list）；跨措辭限制每輪揭露（embedding 是 residue）。
+
+- **Use case**：「之前是不是處理過類似 X、在哪」
+- **Risk**：zero — 純讀
+
+#### P-ask-history — issue 知識庫問答（#72，v2.99+）
+
+`idd-ask "<自然語言問題>"` → decide-to-search gate → retrieval（delegate idd-find backend）→ top-N 全文（5／上限 10）→ grounded 合成答案（claim 必附引用、source priority、`### Referenced Issues`、查無誠實）。bug 貌問題**不觸發 diagnose**。
+
+- **Use case**：「當時為什麼這樣決定 / X 怎麼運作」— 還原 decision rationale
+- **Risk**：zero state / 中 token（top-N 全文是本質成本，有界）
+
+#### P-report-rollup — 跨 issue 人類 triage 視圖（#134，v2.97+）
+
+`idd-report --rollup` → 聚合各 issue 的 dashboard comment（#133 契約，marker 定位、O(1)/issue）→ 四分組（need-attention / in-progress / stalled>14d / recently-closed）。**Pull-only invariant**：不寫回、不通知。
+
+- **Use case**：「我這週該把注意力放哪」
+- **Risk**：zero — snapshot-only（invariant 在 drift-guard）
+
+#### P-config-maintain — config 生命週期（v2.31+）
+
+`idd-config show / init / validate / which` → `.claude/.idd/local.json` 檢視、初始化、predicate 驗證、cwd 落點 dry-run。非 lifecycle、無 issue 綁定。
+
+- **Use case**：首次設定、monorepo 路由除錯、「這個 cwd 會開到哪個 repo」
+- **Risk**：low — init/validate 只動 config 檔
+
 ### H. Unsupervised / autopilot paths(no human-in-loop)
 
 #### P-loop-autopilot
@@ -406,7 +445,10 @@ idd-edit comment:NNN --append --body "..."
 | `idd-edit` | | | | | | | ✓ batch | | | | ✓ standalone | |
 | `idd-list` | | | | | | | | | | | ✓ triage | ✓ cron |
 | `idd-clarify` | (issue 內 delegate) | | | | | | | | | | ✓ standalone audit | |
-| `idd-report` | | | | | | | | | | | ✓ aggregate | |
+| `idd-find` | (建案前查重) | | | | | | | | | | ✓ lookup | |
+| `idd-ask` | | | | | | | | | | | ✓ grounded QA | |
+| `idd-config` | | | | | | | | | | | ✓ maintain | |
+| `idd-report` | | | | | | | | | | | ✓ aggregate + `--rollup` | |
 | `idd-route` | | | | | | | | | | | ✓ recommend | |
 | `idd-all` | | | | ✓ all variants | ✓ cluster | | | | | | | ✓ loop |
 | `idd-all-chain` | | | | | | ✓ all variants | | | | | | ✓ rare |
@@ -504,6 +546,8 @@ Q1: 是 single issue 還是 multi issues?
 ## Provenance
 
 > **2026-07-17（#122 補完）**：catalog 由 skeleton 補至 v2.96 現實 — 新增 P-meeting（#57）、P-batch-drain（#182）、P-discussions-intake（#221）、P-clarify-audit（#135）；decision tree 補 meeting 分流 + #129 硬閘；matrix 補 idd-clarify 列。後續新 path 隨 feature 落地就地 iterate（使用者裁決：本檔可就地補、不另開 issue）。
+>
+> **2026-07-18（#267 回填 + 機制化）**：補至 v2.99 現實 — 新增 P-find-lookup（#139）、P-ask-history（#72）、P-report-rollup（#134）、P-config-maintain、P-verify-file-profile（#258）；matrix 補 idd-find / idd-ask / idd-config 列。**#122 的根因（catalog 無強制回填機制）獲得機制解**：`scripts/tests/docs-catalog-sync/` drift-guard 要求每個 `skills/*/` 目錄名出現在本檔或 skill-dimensions.md — 新 skill 落地忘記回填會直接紅。就地補裁決繼續有效；guard 只鎖「提及」，內容品質仍是人的判斷。
 
 
 - **首次版本**:2026-05-21 — AI agent skeleton,由 user 對 #122(原 marketplace#89,已 transfer 過來)提出 reframing(「不是強制,而是把所有可能 path 都列出來」)觸發

plugins/issue-driven-dev/README.md

@@ -59,11 +59,13 @@ idd-issue → idd-diagnose → idd-implement → idd-verify → idd-close
 | `idd-diagnose` | Find root cause (bug) or analyze requirements (feature/refactor) |
 | `idd-plan` | Plan tier approval gate using `EnterPlanMode` — presents Implementation Plan for user approval before TDD execution; sits between `Simple` direct-implement and `Spectra` spec-contract path (v2.36.0+) |
 | `idd-implement` | Scope-disciplined implementation with TDD |
-| `idd-verify` | Independent verification using Codex CLI (gpt-5.5) |
+| `idd-verify` | Independent verification — 5 Claude reviewer agents + cross-model Codex leg (gpt-5.x; executable from pai, governance from codex-pro per #264). `--profile code/prose/academic` + `--file`/`--dir` for non-code deliverables (#258, v2.97+) |
 | `idd-close` | Closing comment documenting problem, root cause, solution, verification |
 | `idd-clarify` | **Terminology / Semantic accuracy axis** (v2.72.0+, [#135](https://github.com/PsychQuant/issue-driven-development/issues/135)) — surfacing-only primitive that scans issue body for terminology mismatches / ambiguity / missing-context gaps, annotates via `### Clarity Surface` block. Standalone runnable for retroactive audit; delegated by `idd-issue` Step 4.6; gated by `idd-diagnose` Step 0.5. Third axis alongside IC_R010 Confidence + IC_R007 Verbatim. |
 | `idd-comment` / `idd-edit` | Add or amend issue comments with template guidance (decision / note / question) |
-| `idd-list` / `idd-update` / `idd-report` | List open issues by phase, sync issue body, generate progress reports |
+| `idd-list` / `idd-update` / `idd-report` | List open issues by phase, sync issue body, generate progress reports (`idd-report --rollup` = cross-issue human triage view over dashboard comments, #134 v2.97+) |
+| `idd-find` | **Semantic lookup** (v2.97+, [#139](https://github.com/PsychQuant/issue-driven-development/issues/139)) — surfacing-only search over the open+closed corpus (GitHub relevance + phase/PR overlay); answers "have we solved something like X, and where" |
+| `idd-ask` | **Grounded QA** (v2.99+, [#72](https://github.com/PsychQuant/issue-driven-development/issues/72)) — mirrors `/spectra-ask` for the issue corpus: full-text top-N read, every claim cited, source priority closed-with-PR > open, honest silence on corpus miss; answers "why did we decide that" |
 | `idd-config` | Manage `.claude/issue-driven-dev.local.json` lifecycle: `show` / `init` / `validate` / `which` (v2.31.0) |
 | `idd-all` | Orchestrator that drives the full pipeline (issue → close) end-to-end (v2.26.0; v2.28.0 unattended SDD chain) |
 | `idd-all-chain` | **Chain-solve mode** (v2.55.0+ single-root, v2.60.0+ multi-root + DFS/BFS) — root issue(s) + auto-emergent spawned issues (sister bug / verify follow-up / mid-plan tangential / sister concern) through ONE cluster branch + ONE review PR. Thin recursive shell over `idd-all` using `--in-chain` flag (4th mode tuple `(direct-commit, unattended)`). Multi-root invocation `#A #B #C` with `--bfs` opt-in (default DFS). Hard caps: per-root depth=3, global max-issues=10 (v2.60.0+, was 2/5). Eligibility: same-file OR same-skill OR sister-bug. Verify FAIL = per-root halt (other root subtrees continue). STOPs at verified — never auto-close |
@@ -236,9 +238,9 @@ IDD 遵循「**深度整合 >> hard-coded**」原則（#209/#214）：生態系
 | ------- | ------- | ---- | ------- |
 | `parallel-ai-agents`（`psychquant-claude-plugins`） | **Hard dependency** — `plugin.json` `dependencies` 安裝時自動安裝（#219；cross-marketplace，root marketplace 需 `allowCrossMarketplaceDependenciesOn` 增列） | `idd-verify` 的 canonical ensemble 引擎（4 lens + DA + Codex；≥2.18.0 STABLE contract） | 缺席/過舊 → 印一步安裝指令 + fall back **manual fan-out**（品質等價、較慢）；vendored fork 已刪（#207 Residue 成熟） |
 | `superpowers`（`claude-plugins-official`） | **Hard dependency** — `plugin.json` `dependencies` 安裝時自動安裝（#209） | TDD 執行（`idd-implement`）、系統性除錯（`idd-diagnose` bug RCA）、完成前驗證的 canonical process 紀律 | Delegation 點 **fail-fast abort** + 一步安裝指令；絕不 silent degrade |
-| `parallel-ai-agents`（pai） | **Canonical engine + 版本閘門 ≥ 2.18.0**（#207，STABLE external-consumer contract） | `idd-verify` 的 6-AI ensemble 引擎（4 lenses + Devil's Advocate + Codex 編排） | 三層 graceful degrade：canonical → frozen vendored fork → manual fan-out（每層印 notice） |
+| `parallel-ai-agents`（pai） | **Canonical engine + 版本閘門 ≥ 2.19.0**（#207/#264，STABLE external-consumer contract 含 codexModel/codexEffort） | `idd-verify` 的 6-AI ensemble 引擎（4 lenses + Devil's Advocate + Codex 編排）+ `bin/codex-call` executable（#264 起 IDD 不再 vendor） | 兩層 degrade：canonical → manual fan-out（每層印 notice；vendored fork 已刪 #219/#264） |
 | `ralph-loop`（`claude-plugins-official`） | Optional mode 依賴（#28） | `idd-verify --loop` / `idd-all (PR, unattended)` 的 verify-fix loop driver | `--loop` fail-fast + 安裝指引；`idd-all` graceful degrade 到 (direct-commit, attended) |
-| OpenAI Codex CLI（gpt-5.5） | Vendored `codex-call` HTTP wrapper（#147，非 subprocess） | Verify 的跨模型盲驗 lens | Fail-closed INFO finding「cross-model pass incomplete」，不靜默當 PASS |
+| `codex-pro`（codex-pro marketplace） | **Hard dependency**（#264）— codex 治理 single source（`defaults.json` + profile.yaml 契約，MIN 0.7.0） | Verify 跨模型盲驗 lens 的 model/effort/max-time 治理（gpt-5.x，世代 pin 只在 codex-pro 一處） | 缺席 **fail-fast abort** + 一步安裝指令；絕不靜默 fallback 舊 model |
 | `che-word-mcp` / `che-telegram-mcp` / `che-apple-mail-mcp` / `che-apple-notes-mcp` | Optional per source type（#27） | `idd-issue` 來源 adapter（docx / Telegram / Mail / Notes） | 該 source type **fail-fast** + 結構化安裝指引（見下方 Optional 表） |
 
 ## Requirements
@@ -247,7 +249,7 @@ IDD 遵循「**深度整合 >> hard-coded**」原則（#209/#214）：生態系
 
 - `gh` CLI authenticated with GitHub
 - [OpenAI Codex CLI](https://github.com/openai/codex) installed (for `idd-verify`)
-- ChatGPT Pro account (for Codex gpt-5.5)
+- ChatGPT Pro account (for the Codex cross-model lens, gpt-5.x — model governed by codex-pro's defaults.json)
 - `superpowers` plugin（`claude-plugins-official`）— **hard dependency（v2.90.0+ #209）**。安裝本 plugin 時 Claude Code 會經 `plugin.json` `dependencies` 自動安裝（需 Claude Code v2.1.110+；遞移 enable 需 v2.1.143+）。`idd-implement` 的 TDD 執行與完成前驗證、`idd-diagnose` 的 bug RCA 執行框架 delegate 給它；缺席時該路徑 **fail-fast abort** + 一步安裝指令，不做 fallback
 - **SessionStart hook（v2.91.0+ #214）**：plugin 啟用後每次 SessionStart 事件（startup / resume / clear / compact — 刻意含 compact，讓規則在 context 壓縮後存活）注入 ≤5 行 commit issue-reference 紀律（canonical：`rules/commit-issue-reference.md`）— 防 GitHub auto-close trap 於 skill 外的手動 commit
 

plugins/issue-driven-dev/scripts/tests/docs-catalog-sync/test.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# test.sh — drift-guard for the docs catalog completeness (#267, mechanizing #122).
+#
+# ROOT CAUSE THIS GUARDS: the path/skill catalogs (docs/workflows.md +
+# docs/skill-dimensions.md) had no forcing function — every release wave that
+# shipped a new skill without backfilling the docs drifted silently until a
+# human noticed (#122 fixed the content, this suite fixes the mechanism).
+# Contract: EVERY directory under plugins/issue-driven-dev/skills/ must be
+# mentioned by name in at least one of the two catalog docs. The guard asserts
+# MENTION, not quality — prose depth stays human judgment.
+#
+# Usage: bash test.sh   (exit 0 = all pass, 1 = any fail)
+
+set -u
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$HERE/../../.."
+REPO_ROOT="$PLUGIN_ROOT/../.."
+WORKFLOWS="$REPO_ROOT/docs/workflows.md"
+DIMENSIONS="$REPO_ROOT/docs/skill-dimensions.md"
+
+HELPERS="$HERE/../../lib/assert-helpers.sh"
+[ -f "$HELPERS" ] || { echo "✗ missing $HELPERS — cannot run suite" >&2; exit 1; }
+. "$HELPERS"
+
+assert_file_exists "docs/workflows.md exists" "$WORKFLOWS"
+assert_file_exists "docs/skill-dimensions.md exists" "$DIMENSIONS"
+
+for d in "$PLUGIN_ROOT"/skills/*/; do
+  n=$(basename "$d")
+  if grep -qF -- "$n" "$WORKFLOWS" || grep -qF -- "$n" "$DIMENSIONS"; then
+    pass "catalog mentions skill: $n"
+  else
+    fail "catalog mentions skill: $n" "neither docs/workflows.md nor docs/skill-dimensions.md mentions '$n' — backfill the catalog (the #122/#267 drift class)"
+  fi
+done
+
+print_summary "docs-catalog-sync"

plugins/issue-driven-dev/scripts/tests/model-generation-sync/test.sh

@@ -61,6 +61,17 @@ refute_output_grep "idd-verify: no hardcoded --model gpt-5 pin" '--model gpt-5'
 refute_output_grep "idd-diagnose: old candidate name gone"      "codex-gpt-5.5-xhigh" "$DIAGNOSE"
 assert_output_grep "idd-diagnose: codex-xhigh candidate"        "codex-xhigh"      "$DIAGNOSE"
 
+# ── README + repo docs: same zero-pin contract (#267 — the file class that leaked) ──
+README="$PLUGIN_ROOT/README.md"
+WORKFLOWS="$REPO_ROOT/docs/workflows.md"
+DIMENSIONS="$REPO_ROOT/docs/skill-dimensions.md"
+assert_file_exists "plugin README exists" "$README"
+assert_file_exists "docs/workflows.md exists" "$WORKFLOWS"
+assert_file_exists "docs/skill-dimensions.md exists" "$DIMENSIONS"
+refute_output_grep "README: no stale gpt-5.5 hard-pin"          "gpt-5.5"          "$README"
+refute_output_grep "workflows.md: no stale gpt-5.5 hard-pin"    "gpt-5.5"          "$WORKFLOWS"
+refute_output_grep "skill-dimensions.md: no stale gpt-5.5 hard-pin" "gpt-5.5"      "$DIMENSIONS"
+
 # ── references: same neutrality contract ──
 AGENT_ROUTING="$PLUGIN_ROOT/references/agent-routing.md"
 EXT_DELEG="$PLUGIN_ROOT/references/external-agent-delegation.md"