From 57d0c85d84aafe7f0f6c4ba745bf13d18a6f8dc6 Mon Sep 17 00:00:00 2001 From: che cheng Date: Sat, 18 Jul 2026 15:57:16 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20README=20pins=20+=20docs=20catalog=20bac?= =?UTF-8?q?kfill=20to=20v2.99=20=E2=80=94=20drift-guards=20now=20cover=20R?= =?UTF-8?q?EADME/docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README carried THREE stale gpt-5.5 pins (skill table, dependency table, prerequisites) plus a stale 'vendored codex-call / three-tier degrade' claim — all outside model-generation-sync's scan net, which is exactly how they leaked past the #251/#264 zero-pin contract (the guard caught two of them only after its net was widened mid-fix). docs/workflows.md + skill-dimensions backfilled to v2.99 reality: P-find-lookup, P-ask-history, P-report-rollup, P-config-maintain, P-verify-file-profile paths; matrix rows for idd-find / idd-ask / idd-config (the last a pre-#122 legacy gap); D12 line gains the 4th member. Systemic prevention, both directions: model-generation-sync refutes now include README + both catalog docs (31 assertions), and a new docs-catalog-sync suite requires every skills/*/ directory name to appear in a catalog doc — the #122 root cause (no forcing function for backfill) is now test-detectable (RED caught idd-ask + idd-config). Sweep 38 suites 0 fail. Refs #267 --- docs/skill-dimensions.md | 5 +- docs/workflows.md | 46 ++++++++++++++++++- plugins/issue-driven-dev/README.md | 12 +++-- .../scripts/tests/docs-catalog-sync/test.sh | 38 +++++++++++++++ .../tests/model-generation-sync/test.sh | 11 +++++ 5 files changed, 105 insertions(+), 7 deletions(-) create mode 100644 plugins/issue-driven-dev/scripts/tests/docs-catalog-sync/test.sh diff --git a/docs/skill-dimensions.md b/docs/skill-dimensions.md index 52bd2b6..39e40a9 100644 --- a/docs/skill-dimensions.md +++ b/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 | diff --git a/docs/workflows.md b/docs/workflows.md index 8c2564e..30af9ae 100644 --- a/docs/workflows.md +++ b/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 ""` → 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 都列出來」)觸發 diff --git a/plugins/issue-driven-dev/README.md b/plugins/issue-driven-dev/README.md index 28993b1..a651b60 100644 --- a/plugins/issue-driven-dev/README.md +++ b/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 diff --git a/plugins/issue-driven-dev/scripts/tests/docs-catalog-sync/test.sh b/plugins/issue-driven-dev/scripts/tests/docs-catalog-sync/test.sh new file mode 100644 index 0000000..3fec094 --- /dev/null +++ b/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" diff --git a/plugins/issue-driven-dev/scripts/tests/model-generation-sync/test.sh b/plugins/issue-driven-dev/scripts/tests/model-generation-sync/test.sh index 0f0e550..a765dea 100644 --- a/plugins/issue-driven-dev/scripts/tests/model-generation-sync/test.sh +++ b/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"