From 70efc1172ea6b119b176f8754a5615ab15c0ae04 Mon Sep 17 00:00:00 2001 From: che cheng Date: Sat, 15 Aug 2026 01:13:45 +0800 Subject: [PATCH 1/6] =?UTF-8?q?feat:=20Complexity=20=E5=80=BC=E5=9F=9F?= =?UTF-8?q?=E5=B0=81=E9=96=89=E5=8C=96=20+=20=E5=9B=9B=20consumer=20?= =?UTF-8?q?=E5=85=B1=E7=94=A8=20actionability=20gate=20(#316)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `### Complexity` 從沒宣告過封閉值域，也沒有 unparseable 契約 —— 而結構相同的姊妹欄位 `### Conflict Class` 兩者都有。於是 producer 寫出 `Simple when triggered` 不違反任何明文 規則，三個 consumer 各自發明互不相容的窄化：idd-list 靜默截成 `Simple`、idd-all 與 idd-implement 得到非法字串。2026-08-10 實測本 repo 的 22-issue backlog，11 個 diagnosed 裡 8 個 parked/deferred 被判成「Actionable now」，其中兩個帶著使用者親自下的 defer 裁決。 根因不是 parser 太窄，是**把會變的狀態存進不可變的 artifact**。Complexity 活在 append-only 的 Diagnosis comment，parked 卻會變（trigger 成立就該解除）。#136 的 comment 寫 bare `Spectra`、body 寫 `Spectra when triggered (parking lot)` —— 狀態改不動就自己漂到別處。 IDD 早就知道正確做法：`### Blocking` 正因為會變才放在 body 由 idd-update 維護。 - tier 值域收斂為封閉四值（可帶既有 ` via <來源>` 後綴），延期狀態遷至 parking-lot label - 三訊號 gate（域外值 / label / Blocking 區塊），放行需三者皆不成立 - 解析與判定抽成 scripts/lib/actionability.sh，四個 consumer 全部改為引用 + fail-loud guard —— 沒有 guard 的話，「找不到就自己想辦法」的 consumer 會把三方分歧原封帶回來 三個刻意的取捨： Strategy 的 `- [~]` **不進 gate**。它的既有 consumer 是 idd-close 的 checklist gate，語意是 per-item 的 close-time disposition；拿它回答 per-issue 的 routing 問題會撞壞既有語意。 migration **只貼 label、不改寫歷史**。回填既有 Diagnosis comment 會 modify-in-place 一個 append-only artifact；而且不必要 —— legacy 值走 unparseable 路徑得到的正是「not-actionable + surface 原值」，對那批 parked issue 就是正確結果。實測當前 open backlog 域外值 0 筆。 producer **不自動貼 label**。限定詞是 diagnose 當下的判斷，label 是人的裁決，兩者會分岔 （11 筆實測只有 5 筆一致）。由前者推導後者，等於取消「人可以事後 park 一個 tier 明確的 issue」這條路徑。 顯示層仍分兩組：reason 僅為 blocking 者維持 #84 既有的 Blocked 分組（標題／banner／footer 逐字不變），其餘進 Parked 組。gate 統一不等於顯示統一。 ic-r011 的 `blocker:infeasible` / `blocker:waiting` 一併退役 —— 0 個 issue 在用、無任何 consumer 讀，(b)/(c) 的區分保留在 audit 字串（那是說明性資訊，不是機械判定用）。 47/47 suites 綠（新增 actionability-gate 66 條，fixture 含 2026-08-10 事故快照， 斷言 9 筆中只有 #37 為 actionable）。 Refs #298, #310, #317 --- .../add-actionability-gate/.openspec.yaml | 4 + .../changes/add-actionability-gate/design.md | 141 +++++++++++ .../add-actionability-gate/proposal.md | 54 +++++ .../specs/actionability-gate/spec.md | 119 +++++++++ .../changes/add-actionability-gate/tasks.md | 33 +++ .../references/actionability-gate.md | 152 ++++++++++++ .../references/ic-r011-checkpoint.md | 20 +- .../scripts/lib/actionability.sh | 155 ++++++++++++ .../fixtures/parked-routing.json | 229 ++++++++++++++++++ .../scripts/tests/actionability-gate/test.sh | 158 ++++++++++++ .../issue-driven-dev/skills/idd-all/SKILL.md | 41 ++-- .../skills/idd-diagnose/SKILL.md | 19 +- .../skills/idd-implement/SKILL.md | 48 ++-- .../issue-driven-dev/skills/idd-list/SKILL.md | 16 +- .../issue-driven-dev/skills/idd-plan/SKILL.md | 40 ++- 15 files changed, 1181 insertions(+), 48 deletions(-) create mode 100644 openspec/changes/add-actionability-gate/.openspec.yaml create mode 100644 openspec/changes/add-actionability-gate/design.md create mode 100644 openspec/changes/add-actionability-gate/proposal.md create mode 100644 openspec/changes/add-actionability-gate/specs/actionability-gate/spec.md create mode 100644 openspec/changes/add-actionability-gate/tasks.md create mode 100644 plugins/issue-driven-dev/references/actionability-gate.md create mode 100644 plugins/issue-driven-dev/scripts/lib/actionability.sh create mode 100644 plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/parked-routing.json create mode 100755 plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh diff --git a/openspec/changes/add-actionability-gate/.openspec.yaml b/openspec/changes/add-actionability-gate/.openspec.yaml new file mode 100644 index 0000000..6fec2ce --- /dev/null +++ b/openspec/changes/add-actionability-gate/.openspec.yaml @@ -0,0 +1,4 @@ +schema: spec-driven +created: 2026-08-14 +created_by: che cheng +created_with: claude diff --git a/openspec/changes/add-actionability-gate/design.md b/openspec/changes/add-actionability-gate/design.md new file mode 100644 index 0000000..c742b9c --- /dev/null +++ b/openspec/changes/add-actionability-gate/design.md @@ -0,0 +1,141 @@ +## Context + +`/idd-list` 與 `/idd-all` 的 routing 需要回答一個問題：**這個 issue 現在可不可以動？** 目前四個候選訊號中只有一個有 routing consumer： + +| 訊號 | 位置 | 生命週期 | 現況 | +|---|---|---|---| +| `### Complexity` 的限定詞 | Diagnosis comment（append-only）| 凍結 | 被三個 consumer 各自窄化，互不相容 | +| `parking-lot` label | Issue labels | 可變 | 無 producer、無 consumer | +| `### Blocking` 區塊 | Issue body（`idd-update` 維護）| 可變 | 有 consumer（#84）| +| Strategy `[~] 暫緩` | Diagnosis comment | 凍結 | 有 consumer，但屬 `idd-close` 的 close-time disposition | + +2026-08-10 實測：22-issue backlog、11 個 diagnosed，routing 判對 1 個、判錯 8 個。`#131` 與 `#200` 帶有使用者親自下的 defer 裁決，routing 仍建議執行。 + +實測另一項數據推翻了「限定詞與 label 資訊重複」的假設：11 個 issue 中兩者**一致的只有 5 個**。`#37` 是 bare `Spectra` 加 `parking-lot` label（人事後 park）；`#131` 與 `#200` 是有限定詞、無 label（diagnose 判 parked 但無人貼 label）；`#136` 的 comment 與 body 甚至彼此分岔。兩者不是同一資訊的兩種寫法，而是**兩個會分岔的訊號**。 + +約束：`rules/append-vs-modify.md` 規定 Diagnosis comment 是 append-only 審計軌跡。既有的 `### Conflict Class` 契約（openspec/specs/parallel-orchestration/spec.md）已示範了正確形狀 —— 封閉值域、absent 或 unparseable 時保守預設、且必須 surface —— 本設計以之為對照模型。 + +## Goals / Non-Goals + +**Goals:** + +- 讓 routing 能區分「diagnosed 且現在可動」與「diagnosed 但在等 trigger」 +- 把 parked 這個**會變的狀態**從不可變的 artifact 遷到可變的 metadata +- 消除三個 consumer 各自窄化 `### Complexity` 的分岔 +- 保留 #84 既有的 Blocked 分組輸出行為，不退化 +- 建立可被未來新欄位繼承的通則：被 routing 消費的欄位必須宣告封閉值域與 unparseable 契約 + +**Non-Goals:** + +- **不 parse diagnosis 散文抽取 trigger 條件**。trigger 是關於未來世界狀態的散文命題（「等 ≥3 instances」「首次 trace-stale 實害事故」），其成立與否需要人對世界的觀察，不在 repo 內。這是認識論邊界，非本設計的遺漏。 +- **不新增 `### Park Trigger` 結構化欄位**。 +- **不讓 producer 自動貼 `parking-lot` label**（理由見決策「parked label 維持人工裁決」）。 +- **不把 Strategy `[~] 暫緩` 納入 gate**（理由見決策「gate 採三訊號」）。 +- **不做 parked issue 的回訪／staleness 機制** —— 已獨立為 #310。本變更會把 parked 藏得更乾淨、放大該問題，但兩者範圍分離。 +- **不改寫既有 Diagnosis comment 的歷史內容**（理由見決策「migration 只貼 label」）。 +- **不退役 `SDD-warranted`** —— 它是 `Spectra` 的既有 backward-compat alias，留在封閉值域內。 + +## Decisions + +### Complexity 回歸純封閉值域，parked 遷出至 label + +`### Complexity` 的合法值僅四個 tier（`Simple` / `Plan` / `Spectra` / `SDD-warranted`），各自可帶既有的 ` via <來源>` 後綴慣例。parked 狀態改由 `parking-lot` label 單獨承載。 + +理由：根因不是 parser 太窄，而是**把會變的狀態存進不可變的 artifact**。Diagnosis comment 是 append-only，parked 卻會變（trigger 成立就該 unpark）。`#136` 的 comment 與 body 分岔，正是狀態被凍住後自行漂移的自然實驗。IDD 已經知道正確做法 —— `### Blocking` 正因為會變才放在 body 由 `idd-update` 維護。 + +替代方案：(a) 讓 `when triggered` 成為合法後綴，兩訊號並存 —— 但實測已證明兩者會分岔，並存就必須定義優先序，而該優先序沒有非任意的答案；(b) 只加寬三個 parser —— 會讓三個 consumer 一致地讀到一個會分岔的訊號，一致地錯比不一致地錯更難發現。 + +### gate 採三訊號，Strategy 暫緩標記排除在外 + +actionability gate 的輸入是三個訊號：`### Complexity` 非合法值、`parking-lot` label 存在、`### Blocking` 區塊非空。放行需三者皆不成立。Strategy 的 `[~] 暫緩` **不納入**。 + +理由：`[~]` 的既有 consumer 是 `idd-close` 的 checklist gate，語意是「close 時這個 checklist item 刻意跳過」—— 那是 per-item 的 close-time disposition，不是 per-issue 的「現在可不可以動」。把它拉進 routing gate 等於用回答 A 問題的訊號去回答 B 問題，且會與 `idd-close` 的既有語意衝突。 + +### unparseable 的保守處置為 not-actionable 並強制 surface + +`### Complexity` 值不在封閉值域內時，gate 判定 not-actionable，且**必須顯示原始值**供人判讀，絕不靜默截斷。完全缺少 `### Complexity` 區段時同樣 not-actionable，理由標為 missing。 + +理由：完全對稱於 `### Conflict Class` 的 `D_diagnose_first` 契約 —— 保守預設加強制 surface。既有 `idd-all` 的 `UNKNOWN` 安全網只覆蓋「regex 完全沒 match」，結構上接不住「match 到但值非法」，本決策把兩種失敗都納入。 + +替代方案：降級為 `Plan` —— 否決，`Plan` 仍是可動 tier，仍會把 parked issue 送進 `/idd-plan`；中斷整個 `idd-list` —— 否決，對 surfacing-only 工具過重，一筆壞資料會堵死全部輸出。 + +### 解析與判定抽為共用 helper + +`### Complexity` 的解析與 actionability 判定抽成單一 shell helper，四個 skill 引用同一份實作，不各自內嵌。 + +理由：`.claude/rules/deep-integration-over-hardcode.md` 的反複製判準 —— 同構機件兩處維護等於同一個 bug 要修多次，本 issue 正是該失敗模式的實例（三處實作、三種行為）。 + +### migration 只貼 label，不改寫歷史 + +既有 9 筆帶限定詞的 Diagnosis comment **維持原狀不改寫**。migration 的動作只有兩種：對應 issue 補上 `parking-lot` label（若缺），以及 `#128` 由人重新判斷。 + +理由：改寫既有 Diagnosis comment 的 `### Complexity` 是 modify-in-place 一個 append-only 審計 artifact，違反 `rules/append-vs-modify.md`。而且**不需要改寫** —— legacy 限定詞值在新契約下落入 unparseable 路徑，判定為 not-actionable 並顯示原值，對那 8 個 parked issue 而言正是正確結果。封閉值域約束的是**新產出的** diagnosis；歷史值由 unparseable 路徑正確承接。 + +替代方案：回填改寫 —— 否決，違反 append-only 且無必要；永久放寬值域容忍 legacy —— 否決，會讓封閉值域名存實亡。 + +### parked label 維持人工裁決，producer 不自動貼 + +`idd-diagnose` **不**自動貼 `parking-lot` label。 + +理由：限定詞是 diagnose 當下的 AI 判斷，label 是人的裁決，兩者語意不同。`#37` 是 bare `Spectra` 加 label —— diagnose 當時（2026-05-19）判的是可動，label 是 2026-08-10 由人 re-park 時貼上。若讓 producer 從限定詞推導 label，就等於宣告 parked 只能在 diagnose 當下決定，這條事後裁決路徑會消失。 + +### 顯示分兩組以保留 #84 既有輸出 + +gate 產出 verdict 加 reason 清單；顯示層依 reason 分兩組 —— reason 為 blocking 者維持 #84 既有的 Blocked 分組與其 banner、footer 計數逐字不變；reason 為 parking label 或 complexity 相關者進新的 Parked 分組。 + +理由：gate 統一不等於顯示統一。把兩者合併成單一分組會構成 #84 的輸出退化，而 #84 的 anti-anxiety surface 是使用者依賴的既有行為。分組拆分讓「統一判定」與「不退化」同時成立。 + +### parking 慣例收斂為 parking-lot + +`references/ic-r011-checkpoint.md` 中 `blocker:infeasible` 與 `blocker:waiting` 的敘述改為 `parking-lot`，或明記兩者分工。 + +理由：vocabulary drift —— 文件寫的兩個 label 目前各 0 個 issue 在用，實際在用的 `parking-lot` 有 6 個。該檔同時宣稱存在一個「periodic backlog grooming」機制去 grep 那兩個 label；該機制不存在且會掃到空集合（已獨立為 #310）。本變更只收斂 label 名稱，不實作 grooming。 + +## Implementation Contract + +**Behavior** — 跑 `/idd-list` 時，被 gate 判為 not-actionable 的 issue 不再出現在 Suggested next 的可動清單，改列於 Blocked 或 Parked 分組並附判定理由；`### Complexity` 值非法時，該值原文顯示於輸出中。`/idd-all`、`/idd-implement`、`/idd-plan` 拿到非法 Complexity 值時停止 routing 並回報原值，不再落入未定義行為。 + +**Interface** — 共用 helper 提供兩個函式： + +- `idd_parse_complexity`：輸入為 Diagnosis comment 全文，stdout 為 canonical tier（四個合法值之一）。exit 0 表示合法（bare tier 或帶 ` via <來源>` 後綴）；exit 3 表示區段存在但值不在封閉值域，stderr 輸出 `unparseable-complexity: <原始值>`；exit 4 表示缺少 `### Complexity` 區段，stderr 輸出 `missing-complexity`。 +- `idd_actionability_verdict`：輸入為前一函式的 exit code、是否帶 `parking-lot` label、`### Blocking` 是否非空。stdout 為 `actionable`，或 `not-actionable: [; ...]`；exit 0 為 actionable、exit 1 為 not-actionable。 + +**Reason 值域**（封閉列舉，四個）：`complexity-unparseable`、`complexity-missing`、`parking-lot-label`、`blocking-nonempty`。 + +**Failure modes** — 非法 Complexity 值一律 surface，絕不靜默截斷或降級為合法 tier。helper 本身不可用（檔案缺失）時，呼叫端 fail-loud 並指出缺失路徑，不 silent degrade 回舊行為。gate 不對「trigger 條件是否已成立」做任何判斷，該問題明確在範圍外。 + +**Acceptance criteria** + +- 新增測試以既有慣例落在 `plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh`，並登錄進 `plugins/issue-driven-dev/scripts/run-all-tests.sh`。 +- fixture 為靜態對照表，記錄 issue 號、Complexity 原始值、labels、期望 verdict，覆蓋 2026-08-10 快照的 9 筆 diagnosed 路由，斷言其中只有 `#37` 為 actionable。fixture 不查詢 live GitHub。 +- 三個代表性 legacy 值（`Simple when triggered`、`Spectra when triggered (parking lot)`、`#128` 的散文值）經 `idd_parse_complexity` 皆回 exit 3 並在 stderr 顯示原值。 +- 兩個既有的合法後綴值（`Plan via Layer V`、`Spectra via hard-gate (sdd_bias)`）經 `idd_parse_complexity` 回 exit 0 且 canonical tier 分別為 `Plan` 與 `Spectra`。 +- #84 既有行為回歸測試：帶非空 `### Blocking` 的 issue 仍列於 Blocked 分組，該分組標題、全 blocked banner 文案、footer 計數與變更前逐字相同。 + +**Scope boundaries** + +- 範圍內：Complexity 值域契約、三訊號 gate、共用 helper、四個 skill 的引用改寫、`ic-r011-checkpoint.md` 的 label 名稱收斂、測試與 fixture、9 筆 issue 的 label migration。 +- 範圍外：parked 回訪／staleness 機制（#310）、`--limit` 排序缺陷（#299）、trigger 條件的機械判定、`idd-close` 對 Strategy `[~]` 的既有處理、grooming 機制的實作。 + +## Risks / Trade-offs + +- **#84 行為退化** → 顯示層分兩組而非合併，Blocked 分組的標題、banner、footer 計數列入回歸測試逐字比對。 +- **四個 skill 改寫不同步，只修一處等於沒修** → 抽共用 helper，並在測試中對四個引用點各驗一次；只修 `idd-list` 會讓 `idd-all` 的未定義行為留存。 +- **與 #299 同檔衝突** → 兩者都修改 `plugins/issue-driven-dev/skills/idd-list/SKILL.md`，需序列化或合併為同一 PR；conflict class 已判為需序列化。 +- **legacy 值走 unparseable 路徑，verdict 對但 reason 不精確** → reason 會標為 `complexity-unparseable`（資料問題）而非 parked。緩解：surface 原始值，人看到 `Simple when triggered` 即可理解實情。這是不改寫歷史所付的已知代價。 +- **本變更讓 parked 藏得更乾淨，放大無回訪機制的問題** → 已獨立為 #310 並在 Non-Goals 明記；本變更不因此擴大範圍。 + +## Migration Plan + +1. helper 與新 reference 落地，四個 skill 改為引用共用實作。 +2. 測試與 fixture 落地並登錄進 test runner。 +3. 對 8 個既有 parked issue 補齊 `parking-lot` label（`#131`、`#200` 目前有限定詞但缺 label；其餘已有）。**不改寫任何 Diagnosis comment。** +4. `#128` 交由人重新判斷 —— 其 Complexity 值為散文（tier 後接未決 UX 軸的敘述），需決定該 issue 是 parked 或可動，再決定是否貼 label。 +5. `ic-r011-checkpoint.md` 的 label 名稱收斂。 + +Rollback：本變更為 skill 文件、helper script 與 label 的變更，無資料遷移。回退方式為 revert commit 加撕除步驟 3 補上的 label；既有 Diagnosis comment 全程未被修改，無不可逆狀態。 + +## Open Questions + +- `#128` 的正確處置需人判斷，migration 步驟 4 才能完成。其值為「tier 後接未決 UX 軸」的散文，無法機械判定該 issue 是 parked 還是可動。 +- `ic-r011-checkpoint.md` 的兩個 `blocker:*` label 是「退役」還是「與 parking-lot 分工」，需在該檔改寫時定案。目前 0 使用，傾向退役，但若原設計意圖是區分 infeasible 與 waiting 兩種 parked 成因，則應保留並明記與 `parking-lot` 的關係。 diff --git a/openspec/changes/add-actionability-gate/proposal.md b/openspec/changes/add-actionability-gate/proposal.md new file mode 100644 index 0000000..25d9859 --- /dev/null +++ b/openspec/changes/add-actionability-gate/proposal.md @@ -0,0 +1,54 @@ +## Why + +> **Re-scope note（2026-08-14）**：本 change 於 #298 仍 open 時提出。走完 discuss → propose、進入 apply 時發現 **#298 已由 PR #309 / #306 修掉並 close** —— 但修正**只落在 `idd-list`**，另三個 consumer（`idd-all` / `idd-implement` / `idd-plan`）未動，且 `idd-list` 自身 Step 5 仍文載會截斷的 regex，與新增的 Step 3.7 直接矛盾。本 change 遂 re-scope 為**承接剩餘缺口**，追蹤於 **#316**；已完成的共用 helper、canonical 契約與回歸測試（全新檔、與已 merge 內容零衝突）原樣保留。Migration 相關 task 因目標 issue 全數 close 而 moot。 + + +2026-08-10 對本 repo 真實的 22-issue backlog 跑 `/idd-list`，routing 把 **8 個 parked/deferred/blocked issue 判成「Actionable now」**（11 個 diagnosed 裡只有 1 個判對）。其中 #131 與 #200 帶有使用者 2026-07-07 親自下的 defer 裁決 —— 照 routing 執行等於自動推翻已記錄的人為決策。失敗是**靜默的**：輸出的表格語法正確、格式正常、沒有任何 warning。 + +`/idd-diagnose #298` 的 root cause：**`### Complexity` 的值域從未被定義為封閉列舉，也沒有「unparseable → 保守 + surface」契約** —— 而結構相同的姊妹欄位 `### Conflict Class` 兩者都有（見 openspec/specs/parallel-orchestration/spec.md）。producer 寫出 `Simple when triggered` 並未違反任何明文規則，於是三個 consumer 各自發明了互不相容的窄化方式：`idd-list` 靜默截斷成 `Simple`；`idd-all` 與 `idd-implement` 得到非法字串，既不匹配任何 dispatch row 也不是 `UNKNOWN`，落入未定義行為（既有的 `UNKNOWN` 安全網只在 regex 完全沒 match 時觸發，結構上接不住此案例）。 + +更深一層：**把會變的狀態存進不可變的 artifact**。`### Complexity` 活在 append-only 的 Diagnosis comment 裡，但 parked 是會變的狀態（trigger 一成立就該 unpark）。#136 的 comment 寫 bare `Spectra`、body 寫 `Spectra when triggered (parking lot)`，正是狀態被凍住後自己漂移出去的自然實驗。IDD 其實已經知道正確做法 —— `### Blocking` 正因為會變才放在 body 由 `idd-update` 維護。 + +## What Changes + +- **`### Complexity` 回歸純封閉值域** —— 合法值僅 `Simple` / `Plan` / `Spectra` / `SDD-warranted`，各自可帶既有的 ` via <來源>` 後綴慣例。`when triggered` 這類限定詞不再寫進此欄位。**BREAKING**：既有 9 筆帶限定詞的 diagnosis 值在新契約下為非法，需 migration。 +- **parked 狀態改由 `parking-lot` label 單獨承載** —— 人可貼可撕，成為唯一 source of truth。實測 11 個 issue 中限定詞與 label 只有 5 個一致，證明兩者不是重複而是會分岔的兩個訊號。 +- **新增 actionability gate** —— 三訊號 OR 判定，放行需三者皆不成立：`### Complexity` 非合法值、`parking-lot` label 存在、`### Blocking` 區塊非空。 +- **default-on-unparseable = not-actionable + surface** —— 對稱於 `### Conflict Class` 的 `D_diagnose_first` 契約：不放行、必須顯示原始值、絕不靜默。 +- **三個 consumer 的 Complexity 解析統一** —— `idd-list`、`idd-all`、`idd-implement`（含 `idd-plan` 的 tier 確認）改用共用 helper，消除各自窄化。 +- **`### Blocking` 抽取重構為 gate 的 input** —— #84 既有的 Blocked 分組輸出行為不得退化。 +- **`idd-diagnose` producer 端宣告封閉值域** —— 明訂限定詞不得寫入，parked 意圖改以 label 表達。 +- **既有 9 筆 diagnosis migration** —— 8 筆機械處理（剝限定詞、必要時補 label）、#128 需人重新判斷（其值為散文，非 tier 加限定詞結構）。 +- **`references/ic-r011-checkpoint.md` 的 parking 慣例收斂** —— 該檔宣稱的 `blocker:infeasible` 與 `blocker:waiting` 目前 0 個 issue 在用，實際在用的是 `parking-lot`（6 個）。 + +## Capabilities + +### New Capabilities + +- `actionability-gate`: 定義 `### Complexity` 的封閉值域、parked 狀態的歸屬（label 而非 comment）、三訊號 actionability gate 的判定規則，以及 unparseable 時的保守處置與強制 surface。 + +### Modified Capabilities + +(none) + +為何無 modified capability：硬閘與 Layer V 這兩份既有 spec 所產出的帶後綴 verdict（形如 tier 後接 " via " 再接來源）在新封閉值域下**仍為合法值**，其 requirement 不需修改；conflict-class 規範對 Complexity 欄位的正交性敘述同樣維持成立。 + +## Impact + +- Affected specs: 新增 `actionability-gate` +- Affected code: + - New: + - `plugins/issue-driven-dev/references/actionability-gate.md` + - `plugins/issue-driven-dev/scripts/lib/actionability.sh` + - `plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh` + - `plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/parked-routing.json` + - Modified: + - `plugins/issue-driven-dev/skills/idd-list/SKILL.md` + - `plugins/issue-driven-dev/skills/idd-all/SKILL.md` + - `plugins/issue-driven-dev/skills/idd-implement/SKILL.md` + - `plugins/issue-driven-dev/skills/idd-plan/SKILL.md` + - `plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md` + - `plugins/issue-driven-dev/references/ic-r011-checkpoint.md` + - Removed: (none) +- 同檔衝突：#299（`--limit` 先於排序生效）同樣修改 `plugins/issue-driven-dev/skills/idd-list/SKILL.md`，兩者需序列化或合併處理。 +- 配套 issue：#310（parked issue 無回訪機制）—— 本變更把 parked 藏得更乾淨，會放大該問題，但不在本次範圍內。 diff --git a/openspec/changes/add-actionability-gate/specs/actionability-gate/spec.md b/openspec/changes/add-actionability-gate/specs/actionability-gate/spec.md new file mode 100644 index 0000000..d45c621 --- /dev/null +++ b/openspec/changes/add-actionability-gate/specs/actionability-gate/spec.md @@ -0,0 +1,119 @@ +## ADDED Requirements + +### Requirement: Closed value domain for the Complexity field + +The `### Complexity` field emitted by `idd-diagnose` SHALL carry exactly one of four tier values: `Simple`, `Plan`, `Spectra`, or `SDD-warranted`. A tier value SHALL also be accepted when followed by the existing ` via ` provenance suffix, in which case the canonical tier SHALL be the text preceding the first ` via ` separator. Qualifiers that express deferral state, such as `when triggered` or `(parking lot)`, SHALL NOT be written into this field; deferral state belongs to the `parking-lot` label instead. Consumers SHALL treat any other value as outside the domain. + +#### Scenario: Bare tier is accepted + +- **WHEN** a Diagnosis comment contains a `### Complexity` section whose value is `Spectra` +- **THEN** the canonical tier resolves to `Spectra` +- **AND** the value is inside the closed domain + +#### Scenario: Provenance suffix is accepted and stripped + +- **WHEN** a Diagnosis comment contains a `### Complexity` section whose value is `Plan via Layer V` +- **THEN** the canonical tier resolves to `Plan` +- **AND** the value is inside the closed domain + +#### Scenario: Deferral qualifier is outside the domain + +- **WHEN** a Diagnosis comment contains a `### Complexity` section whose value is `Simple when triggered` +- **THEN** the value is reported as outside the closed domain +- **AND** the canonical tier is not resolved to `Simple` + +### Requirement: Actionability gate evaluates three signals disjunctively + +The system SHALL determine whether a diagnosed issue is actionable by evaluating exactly three signals: whether the `### Complexity` value is outside the closed domain or absent, whether the `parking-lot` label is present on the issue, and whether the `### Blocking` section of the issue body is non-empty. The issue SHALL be reported as actionable only when none of the three signals holds. The `- [~]` disposition marker inside a Diagnosis `### Strategy` checklist SHALL NOT be an input to this gate, because that marker is a close-time per-item disposition consumed by `idd-close` rather than a per-issue actionability signal. + +#### Scenario: All three signals clear + +- **WHEN** an issue has a `### Complexity` value inside the closed domain, carries no `parking-lot` label, and has an empty `### Blocking` section +- **THEN** the gate reports the issue as actionable + +#### Scenario: Parking label alone withholds the issue + +- **WHEN** an issue has a `### Complexity` value of `Spectra`, carries the `parking-lot` label, and has an empty `### Blocking` section +- **THEN** the gate reports the issue as not actionable +- **AND** the reported reason includes `parking-lot-label` + +#### Scenario: Strategy skip marker does not withhold the issue + +- **WHEN** an issue has all three gate signals clear and its Diagnosis `### Strategy` checklist contains a `- [~]` item +- **THEN** the gate reports the issue as actionable + +### Requirement: Conservative verdict and mandatory surfacing on non-domain Complexity + +When the `### Complexity` value is outside the closed domain, the system SHALL report the issue as not actionable and SHALL surface the original unmodified value to the operator. When the `### Complexity` section is absent entirely, the system SHALL report the issue as not actionable with a distinct reason. The system SHALL NOT silently truncate a non-domain value to a tier prefix, SHALL NOT downgrade it to any tier, and SHALL NOT abort the enclosing listing operation. + +#### Scenario: Non-domain value surfaces verbatim + +- **WHEN** the gate evaluates an issue whose `### Complexity` value is `Spectra when triggered (parking lot)` +- **THEN** the issue is reported as not actionable with reason `complexity-unparseable` +- **AND** the string `Spectra when triggered (parking lot)` appears in the operator-facing output + +#### Scenario: Missing section is distinguished from non-domain value + +- **WHEN** the gate evaluates a Diagnosis comment that contains no `### Complexity` section +- **THEN** the issue is reported as not actionable with reason `complexity-missing` + +#### Scenario: One bad value does not suppress other issues + +- **WHEN** a listing contains one issue with a non-domain `### Complexity` value and other issues with valid values +- **THEN** the listing reports every issue +- **AND** the listing operation does not abort + +### Requirement: Single shared implementation of parsing and verdict + +Complexity parsing and actionability verdict logic SHALL exist as one shared implementation. Every consumer that routes on `### Complexity` — `idd-list`, `idd-all`, `idd-implement`, and `idd-plan` — SHALL invoke that shared implementation rather than embedding its own parsing. The verdict reason vocabulary SHALL be the closed set `complexity-unparseable`, `complexity-missing`, `parking-lot-label`, `blocking-nonempty`. When the shared implementation is unavailable, a consumer SHALL fail loudly and name the missing path rather than degrade to a private parsing path. + +#### Scenario: All routing consumers agree on the same input + +- **WHEN** the same Diagnosis comment containing `Simple when triggered` is evaluated by each routing consumer +- **THEN** every consumer reports the value as outside the closed domain +- **AND** no consumer resolves a canonical tier from it + +#### Scenario: Missing helper fails loudly + +- **WHEN** a consumer invokes the shared implementation and the implementation file is absent +- **THEN** the consumer reports an error naming the missing path +- **AND** the consumer does not fall back to a private parsing path + +### Requirement: Blocked-state output is preserved as a distinct display group + +The gate SHALL produce a verdict together with its reason list, and the display layer SHALL group not-actionable issues by reason. Issues whose only reason is `blocking-nonempty` SHALL continue to appear under the existing blocked-state grouping, with its group heading, its all-blocked banner text, and its footer counts unchanged from the behavior established for blocked-state awareness. Issues whose reasons include `parking-lot-label`, `complexity-unparseable`, or `complexity-missing` SHALL appear under a separate parked grouping. + +#### Scenario: Blocking-only issue keeps existing grouping + +- **WHEN** an issue is not actionable with reason `blocking-nonempty` alone +- **THEN** the issue appears under the existing blocked-state group +- **AND** the group heading, banner text, and footer counts match the pre-change behavior + +#### Scenario: Parked issue appears in the parked group + +- **WHEN** an issue is not actionable with reason `parking-lot-label` +- **THEN** the issue appears under the parked group rather than the blocked-state group + +### Requirement: Parked label is authored by a human and never derived by the producer + +`idd-diagnose` SHALL NOT apply, remove, or derive the `parking-lot` label. The label SHALL remain a human-authored decision that is settable and removable after the diagnosis was written. + +#### Scenario: Diagnosis run leaves labels untouched + +- **WHEN** `idd-diagnose` completes and emits a Diagnosis comment +- **THEN** the issue's `parking-lot` label state is unchanged by that run + +#### Scenario: Human parks an issue whose tier is inside the domain + +- **WHEN** an issue carries a `### Complexity` value of `Spectra` and a human applies the `parking-lot` label afterwards +- **THEN** the gate reports the issue as not actionable with reason `parking-lot-label` + +### Requirement: Legacy Diagnosis values are handled without rewriting history + +Existing Diagnosis comments that carry deferral qualifiers in `### Complexity` SHALL NOT be rewritten to satisfy the closed value domain. The closed value domain SHALL constrain newly emitted diagnoses, and legacy values SHALL be carried by the non-domain path, which yields a not-actionable verdict with the original value surfaced. Migration SHALL be limited to applying the `parking-lot` label where it is absent. + +#### Scenario: Legacy value yields the correct verdict without edit + +- **WHEN** the gate evaluates an issue whose Diagnosis comment still reads `Simple when triggered` and which carries no `parking-lot` label +- **THEN** the issue is reported as not actionable +- **AND** the Diagnosis comment content is unchanged diff --git a/openspec/changes/add-actionability-gate/tasks.md b/openspec/changes/add-actionability-gate/tasks.md new file mode 100644 index 0000000..aa1f5b4 --- /dev/null +++ b/openspec/changes/add-actionability-gate/tasks.md @@ -0,0 +1,33 @@ +## 1. 共用 helper（TDD） + +- [x] 1.1 建立 fixture 與失敗測試（RED）。fixture 為靜態對照表，記錄 issue 號、`### Complexity` 原始值、labels、期望 verdict 與期望 reason，覆蓋 2026-08-10 快照的 9 筆 diagnosed 路由，並額外含兩個合法後綴值（`Plan via Layer V`、`Spectra via hard-gate (sdd_bias)`）與缺少 `### Complexity` 區段的案例。fixture 不查詢 live GitHub。行為契約：測試斷言 9 筆中只有 `#37` 為 actionable。驗證：執行 plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh 全部案例失敗且訊息指出 helper 尚未存在。檔案：`plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/parked-routing.json`、`plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh` 涵蓋需求：Closed value domain for the Complexity field、Actionability gate evaluates three signals disjunctively、Conservative verdict and mandatory surfacing on non-domain Complexity。 + +- [x] 1.2 實作共用 helper 至測試通過（GREEN），落實決策「解析與判定抽為共用 helper」、「unparseable 的保守處置為 not-actionable 並強制 surface」與「gate 採三訊號，Strategy 暫緩標記排除在外」。行為契約：`idd_parse_complexity` 對 bare tier 與帶 ` via <來源>` 後綴回 exit 0 並輸出 canonical tier；對域外值回 exit 3 並於 stderr 輸出原值；對缺區段回 exit 4。`idd_actionability_verdict` 依三訊號回 `actionable` 或 `not-actionable: `，reason 限於四個封閉值。驗證：1.1 的測試全數轉綠。檔案：`plugins/issue-driven-dev/scripts/lib/actionability.sh` 涵蓋需求：Single shared implementation of parsing and verdict。 + +- [x] 1.3 確認新測試被 test runner 納入。行為契約：全套測試執行時涵蓋 actionability-gate 套件。**runner 以 glob 自動探索 `scripts/tests/*/test.sh`，無需手動登錄** —— 本項為驗證而非編輯，`run-all-tests.sh` 不應被修改。驗證：執行 plugins/issue-driven-dev/scripts/run-all-tests.sh 的輸出包含 actionability-gate 套件且回報通過，且該檔在本 change 中維持未修改。 + +## 2. 契約文件 + +- [x] 2.1 撰寫 actionability gate 的 canonical reference，內容涵蓋封閉值域、三訊號 gate、reason 封閉值域、unparseable 的保守處置與強制 surface，並明記與 `### Conflict Class` 契約的對稱關係。行為契約：四個 consumer skill 引用此檔而非各自敘述規則。驗證：內容審查確認四項規則皆有明文，且封閉性以「僅此四值、不得類推」形式書寫。檔案：`plugins/issue-driven-dev/references/actionability-gate.md` + +## 3. Consumer 改寫 + +- [x] 3.1 消除 `idd-list` 內部矛盾：Step 5 的 Complexity 解析改為引用共用 helper，落實決策「顯示分兩組以保留 #84 既有輸出」。**背景（2026-08-14 re-scope）**：#298 的修正已由 PR #309 merge 進 Step 3.7，但同檔 Step 5 仍文載會截斷的 regex `([A-Za-z-]+)` —— 與 Step 3.7 明文禁止的截斷直接衝突。本 task **不重做 Step 3.7 的行為**，只讓 Step 5 停止規定一個矛盾的解析。行為契約：Step 5 不再出現任何私有 Complexity regex，改為引用 `references/actionability-gate.md` 與共用 helper；Step 3.7 既有的 Blocked 分組輸出不變。驗證：grep 確認該截斷 regex 在 `skills/idd-list/SKILL.md` 內**不再有 prescriptive 用法**（僅得出現在 `>` rationale blockquote 內作為反例引用 —— 把失敗史留在文件裡是刻意的，否則後人會覺得這條規則囉嗦而改回去）；且 `git diff` 確認 Step 3.7 段落零刪除行。檔案：`plugins/issue-driven-dev/skills/idd-list/SKILL.md` 涵蓋需求：Blocked-state output is preserved as a distinct display group。 + +- [x] 3.2 [P] 改寫 `idd-all` 使用共用 helper，補上域外值的 dispatch 處置。行為契約：Complexity 值域外時停止 routing 並回報原值，不再落入既有 dispatch table 無匹配 row 的未定義行為；既有的缺區段 abort 行為以 `complexity-missing` reason 表達。驗證：測試以 `Simple when triggered` 為輸入，斷言回報原值且未解析出任何 canonical tier。檔案：`plugins/issue-driven-dev/skills/idd-all/SKILL.md` + +- [x] 3.3 [P] 改寫 `idd-implement` 使用共用 helper。行為契約：Complexity 值域外時停止並回報原值，不再自行以字串切割推導 tier。驗證：測試斷言該 skill 的解析路徑呼叫共用 helper 且對域外值不產生 canonical tier。檔案：`plugins/issue-driven-dev/skills/idd-implement/SKILL.md` + +- [x] 3.4 [P] 改寫 `idd-plan` 的 tier 確認步驟使用共用 helper。行為契約：確認 Complexity 為 `Plan` 的步驟改以共用 helper 的 canonical tier 判定，域外值時停止並回報原值。驗證：測試斷言帶 ` via Layer V` 後綴的值仍被認定為 `Plan`，而域外值不被認定為任何 tier。檔案：`plugins/issue-driven-dev/skills/idd-plan/SKILL.md` + +## 4. Producer 與既有文件 + +- [x] 4.1 於 `idd-diagnose` 的 verdict 寫入段宣告封閉值域，並落實決策「Complexity 回歸純封閉值域，parked 遷出至 label」與「parked label 維持人工裁決，producer 不自動貼」。行為契約：該 skill 明文規定 `### Complexity` 僅得寫四個 tier（可帶 ` via <來源>` 後綴）、限定詞改以 `parking-lot` label 表達，且該 skill 不得貼除既有 type label 以外的 `parking-lot` label。驗證：內容審查確認封閉宣告與「producer 不貼 label」兩條皆成文；並確認既有的 Layer V 與硬閘出口所產生的後綴值在新宣告下仍為合法。檔案：`plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md` 涵蓋需求：Parked label is authored by a human and never derived by the producer。 + +- [x] 4.2 [P] 收斂 parking 慣例敘述，落實決策「parking 慣例收斂為 parking-lot」。行為契約：該檔不再宣稱以 `blocker:infeasible` 或 `blocker:waiting` 進行 parking 標記，改為 `parking-lot`，或明記兩者分工；同時移除對不存在的 periodic backlog grooming 機制的宣稱，改為誠實敘述並指向 #310。驗證：逐行分類檔內每個 `blocker:*` 出現處，確認**全部位於 `>` blockquote**（歷史引用／收斂理由），無任何 prescriptive 用法；且 grooming 敘述與現實一致。檔案：`plugins/issue-driven-dev/references/ic-r011-checkpoint.md` + +## 5. Migration + +- [~] 5.1 對既有 parked issue 補齊 `parking-lot` label —— **moot（2026-08-14）**：migration 目標 `#131` / `#200` / `#128` 在 2026-08-10 之後全部被 close（backlog 已清，非 park）。決策「migration 只貼 label，不改寫歷史」仍然成立且已由 helper 的 unparseable 路徑承接 —— legacy 值判為 not-actionable 並 surface 原值，無需回填。驗證（2026-08-14 實測）：載入共用 helper，對**當前全部 open issue** 逐一跑 `idd_parse_complexity` —— **域外值（exit 3）數量為 0**，需補 `parking-lot` label 的 open issue 數為 0。整個 migration 類別在 live backlog 中為空集合，非僅原列三筆已 close。同時這也是 helper 對真實資料的 end-to-end 驗證。 涵蓋需求：Legacy Diagnosis values are handled without rewriting history。 + +- [~] 5.2 由人重新判斷 `#128` 的處置 —— **moot（2026-08-14）**：`#128` 已 CLOSED，處置已由 backlog 清理決定，無待判事項。原內容：行為契約：`#128` 的 `### Complexity` 值為散文（tier 後接未決 UX 軸敘述），需由人決定該 issue 為 parked 或可動，並據以決定是否貼 `parking-lot` label。驗證：`#128` 的裁決結果以 `/idd-comment --type decision` 記錄於該 issue，且 label 狀態與裁決一致。 diff --git a/plugins/issue-driven-dev/references/actionability-gate.md b/plugins/issue-driven-dev/references/actionability-gate.md new file mode 100644 index 0000000..bd9e0fd --- /dev/null +++ b/plugins/issue-driven-dev/references/actionability-gate.md @@ -0,0 +1,152 @@ +# Actionability Gate + +> The contract that answers **「這個 issue 現在可不可以動？」** — the closed value domain of the `### Complexity` Diagnosis field, where deferral state lives, and the three-signal gate that `idd-list` / `idd-all` / `idd-implement` / `idd-plan` all consume. This file is the single source of truth; the four skills cite it and MUST NOT restate the rules in their own words. +> +> **Source**: `add-actionability-gate` Spectra change (capability `actionability-gate`). Origin: issue-driven-development#298, surfaced from real dogfooding (2026-08-10 backlog routing). + +## The incident this exists to prevent + +On 2026-08-10 a real 22-issue backlog was routed by `/idd-list`. Of the 11 diagnosed issues, **8 parked/deferred/blocked ones were reported as "Actionable now"**. Two of them (#131, #200) carried a defer ruling the user had personally made on 2026-07-07 — following the routing would have re-opened work the user had decided to park. + +The failure was **silent**. The table was syntactically correct, well-formatted, and carried no warning. + +## Root cause — mutable state in an immutable artifact + +`### Complexity` lives in a Diagnosis comment, and Diagnosis comments are **append-only** (see [`rules/append-vs-modify.md`](../rules/append-vs-modify.md)). But "is this issue parked?" is **mutable** — a trigger firing should un-park it. Writing deferral qualifiers (`Simple when triggered`, `Spectra when triggered (parking lot)`) into a frozen field created a value that could never be corrected in place. + +Two consequences followed: + +1. **The field carried two kinds of information** (tier + deferral) while every consumer's parser assumed one. Three consumers each invented an incompatible narrowing, and they disagreed: + + | Consumer | private narrowing | result on `Simple when triggered` | + |---|---|---| + | `idd-list` | `([A-Za-z-]+)` | silently truncated to `Simple` → routed a parked issue to `/idd-implement` | + | `idd-all` | `(.+?)` + via-split | non-tier string; matched no dispatch row **and** was not `UNKNOWN` | + | `idd-implement` | same | same | + + `idd-all`'s `UNKNOWN → abort` safety net structurally could not catch this: it fires only when the regex fails entirely, never when it matches an out-of-domain value. + +2. **The frozen state drifted elsewhere.** #136's Diagnosis comment read bare `Spectra` while its body read `Spectra when triggered (parking lot)` — state that cannot be corrected in place migrates to wherever it can be edited. + +IDD already knew the right shape: `### Blocking` is mutable, so it lives in the issue **body** and is maintained by `idd-update`. This contract applies the same reasoning to deferral. + +## Closed value domain — `### Complexity` + +**The legal values are exactly these four. This is a CLOSED enumeration — do NOT extend it by analogy, and do NOT infer a fifth value from resemblance to an existing one:** + +1. `Simple` +2. `Plan` +3. `Spectra` +4. `SDD-warranted` — legacy alias of `Spectra`, retained for backward compatibility + +A value MAY carry the provenance suffix ` via ` (established v2.50). The canonical tier is the text preceding the **first** ` via ` separator. Both existing producers of suffixed values remain legal: `Plan via Layer V` (Layer V escalation) and `Spectra via hard-gate (sdd_bias)` (hard-gate exit). + +**Deferral qualifiers SHALL NOT be written into this field.** `when triggered`, `(parking lot)`, and any prose describing why the issue is on hold belong to the `parking-lot` label, not here. A tier field that carries deferral state is the defect this contract closes. + +### Where deferral state lives instead + +| State | Home | Mutable? | Maintained by | +|---|---|---|---| +| Complexity tier | `### Complexity` in the Diagnosis comment | no (append-only) | `idd-diagnose` | +| Deferral / parked | `parking-lot` label | **yes** | **a human** — see below | +| External blocker | `### Blocking` in the issue body | yes | `idd-update` | + +**`idd-diagnose` SHALL NOT apply, remove, or derive the `parking-lot` label.** The label is a human ruling, and it is settable *after* the diagnosis was written. Empirically the two signals disagree: of 11 diagnosed issues sampled on 2026-08-10, only 5 had the qualifier and the label in agreement. #37 was bare `Spectra` with the label applied later by a human; #131 and #200 had the qualifier with no label. They are not two spellings of one fact — they are two facts, and deriving one from the other would delete the human's ability to park an issue whose tier is perfectly clear. + +## The three-signal gate + +An issue is **actionable** only when all three signals are clear. Any one of them withholds it. + +``` + ### Complexity outside the closed domain, or absent ─┐ + parking-lot label present ─┼─→ not actionable + ### Blocking section non-empty ─┘ + + actionable ⟺ none of the three holds +``` + +### Reason vocabulary — also a CLOSED enumeration + +**Exactly four values. Do NOT add a fifth by analogy:** + +| Reason | Fires when | +|---|---| +| `complexity-unparseable` | `### Complexity` section present, value outside the closed domain | +| `complexity-missing` | no `### Complexity` section at all | +| `parking-lot-label` | the issue carries the `parking-lot` label | +| `blocking-nonempty` | the `### Blocking` section of the body is non-empty | + +### What is deliberately NOT a signal + +**The `- [~]` disposition marker inside a Diagnosis `### Strategy` checklist is NOT an input to this gate.** It has an existing consumer — `idd-close`'s checklist gate, where it means "this checklist item was deliberately skipped at close time". That is a *per-item, close-time* disposition. This gate asks a *per-issue, routing-time* question. Feeding one into the other answers a different question than the one being asked, and would collide with `idd-close`'s established semantics. + +> ⚠ Anyone editing `- [~]` handling must check `idd-close` first. Treating it as unused because routing ignores it will break the close gate. + +## Default on absent or unparseable — conservative, and always surfaced + +A consumer parsing a `### Complexity` value outside the closed domain SHALL report the issue as **not actionable** and SHALL **surface the original unmodified value** to the operator. A missing section gets the same verdict under a distinct reason. + +Three things are forbidden: + +- **SHALL NOT** silently truncate a non-domain value to its tier prefix. That truncation is the 2026-08-10 incident. +- **SHALL NOT** downgrade a non-domain value to any tier, including `Plan`. `Plan` is still actionable; downgrading routes a parked issue into `/idd-plan`. +- **SHALL NOT** abort the enclosing listing operation. One bad value must not suppress the other issues — a surfacing tool that dies on one malformed row is worse than one that flags it. + +This mirrors the `### Conflict Class` contract in [`parallel-orchestration.md`](parallel-orchestration.md), which defaults an absent or unparseable value to `D_diagnose_first` and requires the fallback be printed. The two fields are orthogonal (one classifies physical resources touched, the other routing tier) but share one discipline: **conservative default plus mandatory surfacing, never silent.** + +## Display grouping — the gate is unified, the display is not + +The gate emits a verdict together with its reason list. The display layer groups by reason: + +| Reasons | Group | +|---|---| +| `blocking-nonempty` **alone** | the existing blocked-state group (#84) — heading, all-blocked banner text, and footer counts unchanged | +| anything else, including any mix | the parked group | + +Unifying the *judgment* does not mean unifying the *presentation*. #84's blocked-state surface is user-facing behavior people rely on; merging it into one undifferentiated bucket would be a regression dressed as a simplification. + +## Consumer contract + +The four routing consumers SHALL invoke the shared implementation at `scripts/lib/actionability.sh` and MUST NOT embed a private parse: + +```bash +. "$CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh" + +tier=$(idd_parse_complexity "$diagnosis_body"); cexit=$? +verdict=$(idd_actionability_verdict \ + --complexity-exit "$cexit" \ + --parking-label "$has_parking_lot_label" \ + --blocking-section "$blocking_section_nonempty") +``` + +| Function | stdout | exit | +|---|---|---| +| `idd_parse_complexity ` | canonical tier | `0` in domain · `3` out of domain (stderr: `unparseable-complexity: `) · `4` no section (stderr: `missing-complexity`) | +| `idd_actionability_verdict …` | `actionable` / `not-actionable: [; …]` | `0` actionable · `1` not actionable · `2` bad usage | +| `idd_actionability_group ` | `blocked` / `parked` | `0` | + +**Malformed invocation fails loud (exit 2), never defaults to actionable.** An unanswered signal treated as "clear" would re-open the exact hole this contract closes. + +**When the shared implementation is missing, a consumer SHALL fail loudly and name the path** — never fall back to a private parse. A silent fallback would restore the three-way divergence this file exists to prevent. + +## Adversary discipline (audit lenses) + +Per [`.claude/rules/attribute-assessment.md`](../../../.claude/rules/attribute-assessment.md), evaluate this interface through three lenses: + +| Lens | Risk | Mitigation | +|---|---|---| +| **Scoundrel** | Write `Simple via when triggered` so the via-split yields a legal tier and the issue passes the gate | The provenance suffix only affects the *tier* channel. Deferral is asserted through the label, which the gate reads independently — a scoundrel who wants the issue withheld cannot express that through Complexity anyway, and one who wants it actionable has simply declared it actionable, which is a claim the audit trail records under their name | +| **Lazy Developer** | Skip a signal argument and let the gate assume "clear" | Every argument is required and validated; missing or non-boolean input returns exit 2 with a named cause. The cheap path is not the unsafe path | +| **Confused Developer** | Answer "does this issue block others?" when asked "is this issue blocked?" | The flag is named `--blocking-section`, pointing at the artifact section being read rather than at a relationship. The axis is **what the `### Blocking` section contains**, never who blocks whom | + +## Out of scope + +- **Evaluating whether a trigger condition has fired.** Trigger conditions are prose propositions about future world state (「等 ≥3 instances」「首次 trace-stale 實害事故」). Deciding whether one has come true requires a human observing the world; it is not derivable from the repo. This gate knows only that *someone declared the issue parked*, never whether the parking is still warranted. That is an epistemic boundary, not a missing feature. +- **Bringing parked issues back into view.** Nothing here re-surfaces an issue whose trigger has fired — tracked separately as **#310**. This contract makes parked issues *more* thoroughly hidden, which makes that gap more urgent, not less. +- **`- [~]` handling** — belongs to `idd-close`, see above. + +## See also + +- [`parallel-orchestration.md`](parallel-orchestration.md) — the `### Conflict Class` contract this one mirrors; orthogonal field, same discipline +- [`rules/append-vs-modify.md`](../rules/append-vs-modify.md) — why a Diagnosis comment cannot hold mutable state +- **Why both enumerations above are written as closed lists with explicit no-analogy clauses** rather than as summarizing criteria: a criterion plus illustrative examples is two specifications that will not be updated together, and the criterion's literal reach eventually exceeds the set of cases its author had in mind. The divergence is silent — the prose still reads fine, it just answers a boundary question nobody agreed to. Naming the members and forbidding extension-by-resemblance is what makes a boundary auditable. (This mirrors a maintainer-side writing discipline that is not part of the plugin distribution, so no link is given here.) diff --git a/plugins/issue-driven-dev/references/ic-r011-checkpoint.md b/plugins/issue-driven-dev/references/ic-r011-checkpoint.md index 293bd3c..82775e7 100644 --- a/plugins/issue-driven-dev/references/ic-r011-checkpoint.md +++ b/plugins/issue-driven-dev/references/ic-r011-checkpoint.md @@ -68,11 +68,17 @@ When the user requests to skip one or more candidates, the skill SHALL present a | Category | Meaning | Action | |----------|---------|--------| | **(a) unactionable observation** | Pure observation with no actionable form (e.g. "AI hallucinates is a statistical fact") | Real skip — NO `gh issue create`. Audit: `Skipped: (a) unactionable observation` | -| **(b) infeasible but understood** | Technically infeasible at this point but understood (e.g. "Need 100x budget to reproduce") | **Still files** as P3 with `blocker:infeasible` label. Audit: `Skipped: (b) infeasible — filed as #NNN with blocker:infeasible label` | -| **(c) blocked on external state** | Waiting on external state that will likely change (e.g. "Wait for GitHub Actions API to add X") | **Still files** as P3 with `blocker:waiting` label. Audit: `Skipped: (c) blocked-on-external — filed as #NNN with blocker:waiting label` | +| **(b) infeasible but understood** | Technically infeasible at this point but understood (e.g. "Need 100x budget to reproduce") | **Still files** as P3 with the `parking-lot` label. Audit: `Skipped: (b) infeasible — filed as #NNN with parking-lot label` | +| **(c) blocked on external state** | Waiting on external state that will likely change (e.g. "Wait for GitHub Actions API to add X") | **Still files** as P3 with the `parking-lot` label. Audit: `Skipped: (c) blocked-on-external — filed as #NNN with parking-lot label` | **Net effect**: only (a) avoids filing. (b) and (c) preserve the parking lot. +> **Label 慣例已收斂為 `parking-lot`（#298 → #316，2026-08-14）**：(b) 與 (c) 原本各自規定貼 `blocker:infeasible` / `blocker:waiting`。實測本 repo：**這兩個 label 一次都沒有被建立過、0 個 issue 在用**，而且**沒有任何 consumer 讀它們** —— `/idd-list --parked` 與 actionability gate 讀的都是 `parking-lot`。一個被文件規定、卻無人貼也無人讀的 label，只會讓「已標記」的錯覺蓋過「沒被追蹤」的事實。 +> +> 兩類合併到同一個 label，**(b) / (c) 的區分保留在 audit 字串裡**（`Skipped: (b) infeasible — …` / `Skipped: (c) blocked-on-external — …`）。理由：那個區分是**說明性**的（為什麼擱著），不是**機械判定**用的 —— gate 只問「是否 parked」，成因由人讀 audit 行。用兩個 label 承載一個布林加一段說明，是把可讀的東西塞進不可讀的通道。 +> +> 完整值域契約見 [`actionability-gate.md`](actionability-gate.md)。 + > **關於「periodic backlog grooming」（#310，2026-08-14 更正）**：本段原本寫著 grooming「可以 grep `blocker:infeasible` / `blocker:waiting` 來回訪」。實測本 repo：**這兩個 label 一次都沒有被建立過**，而且**沒有任何 periodic grooming 機制存在** —— 沒有排程、沒有 CI、沒有任何 skill 會主動回頭看 parked issue。 > > 這件事重要，因為 parked issue 的 trigger 條件全是**關於未來世界狀態的散文命題**（「等 ≥3 instances」「首次 trace-stale 實害事故」）。這類條件成立時**不會發出事件** —— 沒有 webhook、沒有訊號、沒有任何東西會通知 repo。唯一能發現「trigger 已成立」的路徑是**人主動回頭讀**。 @@ -89,9 +95,9 @@ options: - label: "(a) unactionable observation" description: "Real skip — no issue created. Pure observation with no actionable form." - label: "(b) infeasible but understood" - description: "Still files as P3 with blocker:infeasible label. Parking lot — revisit when feasibility changes." + description: "Still files as P3 with the parking-lot label. Parked — revisit when feasibility changes." - label: "(c) blocked on external state" - description: "Still files as P3 with blocker:waiting label. Parking lot — revisit when external state changes." + description: "Still files as P3 with the parking-lot label. Parked — revisit when external state changes." ``` ### 1.6 Legacy 3-option ask (close-tier only + bypass paths) @@ -179,8 +185,8 @@ For each result of the checkpoint, write ONE of these lines (literal text matter |---------|---------------------------| | Default file path — N items filed | `Filed: #NNN, #MMM, #PPP` | | Skip (a) — unactionable | `Skipped: (a) unactionable observation` | -| Skip (b) — infeasible | `Skipped: (b) infeasible — filed as #NNN with blocker:infeasible label` | -| Skip (c) — blocked-on-external | `Skipped: (c) blocked-on-external — filed as #NNN with blocker:waiting label` | +| Skip (b) — infeasible | `Skipped: (b) infeasible — filed as #NNN with parking-lot label` | +| Skip (c) — blocked-on-external | `Skipped: (c) blocked-on-external — filed as #NNN with parking-lot label` | | Empty surface | `(none surfaced)` | | Env var bypass — user chose skip in reverted ask | `Skipped (AI_LOW_BAR_ISSUE_FILING=false — reverted to 3-option ask, user chose skip)` | | Unattended mode bypass | `Skipped (unattended mode + AI_LOW_BAR_ISSUE_FILING=false → implicit (a) skip)` | @@ -195,7 +201,7 @@ When a default-file invocation surfaces 5 candidates and user skips 2 with mixed ``` Filed: #N1, #N2, #N3 Skipped: (a) unactionable observation (candidate #4: "AI race condition is statistical") -Skipped: (c) blocked-on-external — filed as #N5 with blocker:waiting label (candidate #5: "wait for new GitHub API") +Skipped: (c) blocked-on-external — filed as #N5 with parking-lot label (candidate #5: "wait for new GitHub API") ``` Each filed / skipped item gets its own audit line. Multi-line audit block is preferred over compressed single-line for readability. diff --git a/plugins/issue-driven-dev/scripts/lib/actionability.sh b/plugins/issue-driven-dev/scripts/lib/actionability.sh new file mode 100644 index 0000000..c95e163 --- /dev/null +++ b/plugins/issue-driven-dev/scripts/lib/actionability.sh @@ -0,0 +1,155 @@ +#!/usr/bin/env bash +# actionability.sh — the single shared implementation of "can this issue be +# worked on right now?" (PsychQuant/issue-driven-development#298) +# +# Source this from a skill or test runner: +# . "$(dirname "${BASH_SOURCE[0]}")/actionability.sh" +# +# WHY THIS FILE EXISTS +# Before #298 there were three private narrowings of the `### Complexity` field +# and they disagreed. idd-list truncated `Simple when triggered` to `Simple` and +# routed a parked issue to /idd-implement; idd-all and idd-implement produced a +# non-tier string that matched no dispatch row and was not `UNKNOWN` either, so +# the existing abort net could not catch it. One implementation, four consumers, +# no private parsing — that is the whole point of this file. Do not re-inline a +# regex in a SKILL.md; extend here instead. +# +# CLOSED DOMAINS (both are closed — do NOT extend by analogy) +# tier : Simple | Plan | Spectra | SDD-warranted +# optionally followed by " via " (provenance suffix, v2.50+) +# reason : complexity-unparseable | complexity-missing +# parking-lot-label | blocking-nonempty +# +# Deferral state does NOT live in the tier field. It lives in the `parking-lot` +# label, because deferral is mutable (a trigger firing should un-park an issue) +# and a Diagnosis comment is append-only. Storing mutable state in an immutable +# artifact is the root cause #298 diagnosed; keeping tier pure is the fix. + +# ── contract 1: parse the Complexity field ─────────────────────────────────── +# +# idd_parse_complexity +# stdout : canonical tier, when the value is inside the closed domain +# exit 0 : in domain +# exit 3 : section present, value outside the domain +# → stderr: "unparseable-complexity: " +# exit 4 : no `### Complexity` section at all +# → stderr: "missing-complexity" +# +# The raw value is ALWAYS surfaced on the exit-3 path. Never truncate a +# non-domain value down to its tier prefix — that silent narrowing is the +# incident this file prevents. +idd_parse_complexity() { + local body="${1-}" + local raw + + # First non-blank line under the `### Complexity` heading. Anchored at line + # start so a mention inside prose ("the ### Complexity field") cannot match. + raw=$(printf '%s\n' "$body" | awk ' + /^###[[:space:]]+Complexity[[:space:]]*$/ { grab = 1; next } + grab && /^###[[:space:]]/ { exit } + grab && NF { print; exit } + ') + + if [ -z "$raw" ]; then + printf 'missing-complexity\n' >&2 + return 4 + fi + + # Strip markdown bold/italic/code decoration around the value. Diagnoses in + # the wild wrote `**Spectra**`; the decoration is presentation, not value. + local val="$raw" + val="${val#"${val%%[![:space:]]*}"}" # ltrim + val="${val%"${val##*[![:space:]]}"}" # rtrim + val="$(printf '%s' "$val" | sed -E 's/^[*`_]+//; s/[*`_]+$//')" + val="${val#"${val%%[![:space:]]*}"}" + val="${val%"${val##*[![:space:]]}"}" + + # Provenance suffix: everything from the first " via " onward is source + # attribution, not part of the tier. `Plan via Layer V` → `Plan`. + local tier="${val%% via *}" + tier="${tier%"${tier##*[![:space:]]}"}" + + case "$tier" in + Simple|Plan|Spectra|SDD-warranted) + printf '%s\n' "$tier" + return 0 + ;; + *) + # Surface the ORIGINAL line, not the decoration-stripped form — the + # operator needs to see exactly what the artifact says. + printf 'unparseable-complexity: %s\n' "$raw" >&2 + return 3 + ;; + esac +} + +# ── contract 2: the three-signal gate ──────────────────────────────────────── +# +# idd_actionability_verdict --complexity-exit N --parking-label yes|no --blocking-section yes|no +# stdout : "actionable" +# "not-actionable: [; ...]" +# exit 0 : actionable exit 1 : not actionable exit 2 : bad usage +# +# Pass requires ALL THREE signals clear. The `- [~]` Strategy skip marker is NOT +# an input: it is a close-time per-item disposition owned by idd-close, and +# reusing it here would answer a different question than the one being asked. +idd_actionability_verdict() { + local cexit="" label="" blocking="" + + while [ $# -gt 0 ]; do + case "$1" in + --complexity-exit) cexit="${2-}"; shift 2 ;; + --parking-label) label="${2-}"; shift 2 ;; + --blocking-section) blocking="${2-}"; shift 2 ;; + *) printf 'idd_actionability_verdict: unknown argument: %s\n' "$1" >&2; return 2 ;; + esac + done + + # Fail loud on missing or malformed input. A gate that silently treats an + # unanswered signal as "clear" would re-open the exact hole #298 closed — + # this is the Lazy Developer lens: the cheap path must not be the unsafe one. + case "$cexit" in + 0|3|4) ;; + *) printf 'idd_actionability_verdict: --complexity-exit must be 0, 3 or 4 (got: %s)\n' "${cexit:-}" >&2; return 2 ;; + esac + case "$label" in + yes|no) ;; + *) printf 'idd_actionability_verdict: --parking-label must be yes or no (got: %s)\n' "${label:-}" >&2; return 2 ;; + esac + case "$blocking" in + yes|no) ;; + *) printf 'idd_actionability_verdict: --blocking-section must be yes or no (got: %s)\n' "${blocking:-}" >&2; return 2 ;; + esac + + local reasons=() + [ "$cexit" = "3" ] && reasons+=("complexity-unparseable") + [ "$cexit" = "4" ] && reasons+=("complexity-missing") + [ "$label" = "yes" ] && reasons+=("parking-lot-label") + [ "$blocking" = "yes" ] && reasons+=("blocking-nonempty") + + if [ ${#reasons[@]} -eq 0 ]; then + printf 'actionable\n' + return 0 + fi + + local joined + joined=$(printf '%s; ' "${reasons[@]}") + printf 'not-actionable: %s\n' "${joined%; }" + return 1 +} + +# ── display helper: which group does a not-actionable issue belong to? ─────── +# +# idd_actionability_group +# stdout : "blocked" | "parked" +# +# Reason `blocking-nonempty` ALONE keeps the pre-#298 blocked-state grouping +# (#84) intact — its heading, banner and footer counts are user-facing behavior +# that must not regress. Everything else lands in the parked group. +idd_actionability_group() { + local reasons="${1-}" + case "$reasons" in + "blocking-nonempty") printf 'blocked\n' ;; + *) printf 'parked\n' ;; + esac +} diff --git a/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/parked-routing.json b/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/parked-routing.json new file mode 100644 index 0000000..7f0ad66 --- /dev/null +++ b/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/parked-routing.json @@ -0,0 +1,229 @@ +[ + { + "number": 37, + "snapshot": true, + "note": "2026-08-10 snapshot, taken at the moment of the misroute (morning). Bare tier, no parking-lot label yet — this is the one issue the routing judged correctly that day. The label was applied later the same day when the issue was re-parked; recording that later state here would destroy the fixture's value as a regression of the actual incident.", + "complexity_raw": "Spectra", + "labels": [ + "enhancement" + ], + "expect_parse_exit": 0, + "expect_tier": "Spectra", + "expect_verdict": "actionable", + "expect_reasons": [] + }, + { + "number": 131, + "snapshot": true, + "note": "2026-08-10 snapshot. Deferral qualifier present, label absent — the exact shape that produced the silent misroute.", + "complexity_raw": "Simple when triggered", + "labels": [ + "enhancement" + ], + "expect_parse_exit": 3, + "expect_tier": null, + "expect_verdict": "not-actionable", + "expect_reasons": [ + "complexity-unparseable" + ] + }, + { + "number": 146, + "snapshot": true, + "note": "2026-08-10 snapshot. Qualifier and label agree.", + "complexity_raw": "Simple when triggered (parking lot)", + "labels": [ + "enhancement", + "parking-lot" + ], + "expect_parse_exit": 3, + "expect_tier": null, + "expect_verdict": "not-actionable", + "expect_reasons": [ + "complexity-unparseable", + "parking-lot-label" + ] + }, + { + "number": 157, + "snapshot": true, + "note": "2026-08-10 snapshot. Plan tier with deferral qualifier.", + "complexity_raw": "Plan when triggered", + "labels": [ + "enhancement", + "parking-lot" + ], + "expect_parse_exit": 3, + "expect_tier": null, + "expect_verdict": "not-actionable", + "expect_reasons": [ + "complexity-unparseable", + "parking-lot-label" + ] + }, + { + "number": 128, + "snapshot": true, + "note": "2026-08-10 snapshot. Free prose, not tier-plus-qualifier. Migration task 5.2 needs a human ruling on this one; the gate only has to withhold it.", + "complexity_raw": "Plan（觸發表）+ 未決 UX 軸 → **移入 discussion list**", + "labels": [ + "enhancement" + ], + "expect_parse_exit": 3, + "expect_tier": null, + "expect_verdict": "not-actionable", + "expect_reasons": [ + "complexity-unparseable" + ] + }, + { + "number": 200, + "snapshot": true, + "note": "2026-08-10 snapshot. Qualifier present, label absent — carries a user defer ruling dated 2026-07-07.", + "complexity_raw": "Spectra when triggered", + "labels": [ + "enhancement" + ], + "expect_parse_exit": 3, + "expect_tier": null, + "expect_verdict": "not-actionable", + "expect_reasons": [ + "complexity-unparseable" + ] + }, + { + "number": 143, + "snapshot": true, + "note": "2026-08-10 snapshot.", + "complexity_raw": "Spectra when triggered (parking lot)", + "labels": [ + "enhancement", + "parking-lot" + ], + "expect_parse_exit": 3, + "expect_tier": null, + "expect_verdict": "not-actionable", + "expect_reasons": [ + "complexity-unparseable", + "parking-lot-label" + ] + }, + { + "number": 144, + "snapshot": true, + "note": "2026-08-10 snapshot.", + "complexity_raw": "Spectra when triggered (parking lot)", + "labels": [ + "enhancement", + "parking-lot" + ], + "expect_parse_exit": 3, + "expect_tier": null, + "expect_verdict": "not-actionable", + "expect_reasons": [ + "complexity-unparseable", + "parking-lot-label" + ] + }, + { + "number": 145, + "snapshot": true, + "note": "2026-08-10 snapshot.", + "complexity_raw": "Spectra when triggered (parking lot)", + "labels": [ + "enhancement", + "parking-lot" + ], + "expect_parse_exit": 3, + "expect_tier": null, + "expect_verdict": "not-actionable", + "expect_reasons": [ + "complexity-unparseable", + "parking-lot-label" + ] + }, + { + "number": 900, + "snapshot": false, + "note": "Synthetic. Provenance suffix from Layer V — inside the closed domain, nothing else withholds it.", + "complexity_raw": "Plan via Layer V", + "labels": [ + "enhancement" + ], + "expect_parse_exit": 0, + "expect_tier": "Plan", + "expect_verdict": "actionable", + "expect_reasons": [] + }, + { + "number": 901, + "snapshot": false, + "note": "Synthetic. Provenance suffix from the hard gate, including parentheses in the source token.", + "complexity_raw": "Spectra via hard-gate (sdd_bias)", + "labels": [ + "enhancement" + ], + "expect_parse_exit": 0, + "expect_tier": "Spectra", + "expect_verdict": "actionable", + "expect_reasons": [] + }, + { + "number": 902, + "snapshot": false, + "note": "Synthetic. No ### Complexity section at all — distinct reason from a non-domain value.", + "complexity_raw": null, + "labels": [ + "enhancement" + ], + "expect_parse_exit": 4, + "expect_tier": null, + "expect_verdict": "not-actionable", + "expect_reasons": [ + "complexity-missing" + ] + }, + { + "number": 903, + "snapshot": false, + "note": "Synthetic. Legacy alias inside the closed domain.", + "complexity_raw": "SDD-warranted", + "labels": [ + "enhancement" + ], + "expect_parse_exit": 0, + "expect_tier": "SDD-warranted", + "expect_verdict": "actionable", + "expect_reasons": [] + }, + { + "number": 904, + "snapshot": false, + "note": "Synthetic. Blocking section non-empty is the third gate signal; it must land in the blocked group, not the parked group.", + "complexity_raw": "Spectra", + "labels": [ + "enhancement" + ], + "blocking": "- 等 /spectra-discuss 對齊 acceptance metric proxy", + "expect_parse_exit": 0, + "expect_tier": "Spectra", + "expect_verdict": "not-actionable", + "expect_reasons": [ + "blocking-nonempty" + ] + }, + { + "number": 905, + "snapshot": false, + "note": "Synthetic. A Strategy checklist skip marker MUST NOT withhold the issue — that marker belongs to idd-close, not to routing.", + "complexity_raw": "Simple", + "labels": [ + "enhancement" + ], + "strategy_has_skip_marker": true, + "expect_parse_exit": 0, + "expect_tier": "Simple", + "expect_verdict": "actionable", + "expect_reasons": [] + } +] diff --git a/plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh b/plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh new file mode 100755 index 0000000..f9f0bf9 --- /dev/null +++ b/plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh @@ -0,0 +1,158 @@ +#!/usr/bin/env bash +# Test: the actionability gate — does routing know whether an issue can be worked +# on right now? (PsychQuant/issue-driven-development#298) +# +# The incident this fixture reproduces: on 2026-08-10 a real 22-issue backlog was +# routed by /idd-list. Of the 11 diagnosed issues, 8 parked/deferred/blocked ones +# were reported as "Actionable now". Two of them (#131, #200) carried a defer +# ruling the user had personally made on 2026-07-07. The failure was silent — the +# table looked syntactically correct and carried no warning. +# +# Root cause: `### Complexity` never declared a closed value domain and had no +# unparseable contract, so a producer could legally write `Simple when triggered` +# and three consumers each invented an incompatible narrowing: +# - idd-list `([A-Za-z-]+)` → silently truncated to `Simple` +# - idd-all `(.+?)` + via-split → non-tier string, matched no dispatch row +# - idd-implement same → same +# idd-all's `UNKNOWN → abort` net does NOT catch this: it only fires when the +# regex fails entirely, not when it matches an out-of-domain value. +# +# TWO CONTRACTS under test (design.md → Implementation Contract): +# idd_parse_complexity +# stdout : canonical tier — Simple | Plan | Spectra | SDD-warranted +# exit 0 : in domain (bare tier, or tier + " via ") +# exit 3 : section present, value out of domain → stderr names the raw value +# exit 4 : no `### Complexity` section at all +# idd_actionability_verdict --complexity-exit N --parking-label yes|no --blocking-section yes|no +# stdout : "actionable" | "not-actionable: [; ...]" +# exit 0 : actionable exit 1 : not actionable +# reason vocabulary is CLOSED (four values): +# complexity-unparseable | complexity-missing | parking-lot-label | blocking-nonempty +# +# The `- [~]` Strategy skip marker is deliberately NOT a gate input — it is a +# close-time per-item disposition owned by idd-close. Row 905 pins that. +# +# Usage: bash test.sh (exit 0 = pass, 1 = fail) + +set -u + +HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +LIBDIR="$(cd "$HERE/../../lib" && pwd)" +. "$LIBDIR/assert-helpers.sh" + +LIB="$LIBDIR/actionability.sh" +FIXTURE="$HERE/fixtures/parked-routing.json" + +command -v jq >/dev/null 2>&1 || { echo "jq is required for this suite" >&2; exit 1; } +[ -f "$FIXTURE" ] || { echo "fixture missing: $FIXTURE" >&2; exit 1; } + +HELPER_PRESENT=0 +if [ -f "$LIB" ]; then + # shellcheck disable=SC1090 + . "$LIB" + HELPER_PRESENT=1 +fi + +# Build a Diagnosis comment body from a fixture row's complexity value. +# `null` means the row has no `### Complexity` section at all. +synth_body() { # raw_or_NULL + if [ "$1" = "__NULL__" ]; then + printf '## Diagnosis\n\n### Type\n\nbug\n\n### Risks\n\n- none\n' + else + printf '## Diagnosis\n\n### Type\n\nbug\n\n### Complexity\n\n%s\n\n### Risks\n\n- none\n' "$1" + fi +} + +missing_helper_note="helper not implemented yet: $LIB" + +ACTIONABLE_SNAPSHOT=() + +ROWS=$(jq -c '.[]' "$FIXTURE") +while IFS= read -r row; do + num=$(jq -r '.number' <<<"$row") + snapshot=$(jq -r '.snapshot' <<<"$row") + raw=$(jq -r 'if .complexity_raw == null then "__NULL__" else .complexity_raw end' <<<"$row") + exp_exit=$(jq -r '.expect_parse_exit' <<<"$row") + exp_tier=$(jq -r 'if .expect_tier == null then "" else .expect_tier end' <<<"$row") + exp_verdict=$(jq -r '.expect_verdict' <<<"$row") + exp_reasons=$(jq -r '.expect_reasons | sort | join(";")' <<<"$row") + has_label=$(jq -r 'if (.labels | index("parking-lot")) then "yes" else "no" end' <<<"$row") + has_blocking=$(jq -r 'if (.blocking // "") == "" then "no" else "yes" end' <<<"$row") + + body=$(synth_body "$raw") + + if [ "$HELPER_PRESENT" -eq 0 ]; then + fail "#$num parse exit" "$missing_helper_note" + fail "#$num verdict" "$missing_helper_note" + fail "#$num reasons" "$missing_helper_note" + [ "$exp_verdict" = "actionable" ] && [ "$snapshot" = "true" ] && ACTIONABLE_SNAPSHOT+=("$num") + continue + fi + + # ── contract 1: parse ── + tier=$(idd_parse_complexity "$body" 2>/dev/null); act_exit=$? + assert_eq "#$num parse exit" "$exp_exit" "$act_exit" + + if [ "$exp_exit" = "0" ]; then + assert_eq "#$num canonical tier" "$exp_tier" "$tier" + else + # out-of-domain / missing MUST surface the raw value on stderr, never a tier + err=$(idd_parse_complexity "$body" 2>&1 >/dev/null) + if [ "$raw" = "__NULL__" ]; then + assert_grep "#$num stderr names missing section" "missing-complexity" "$err" + else + assert_grep "#$num stderr surfaces raw value" "$raw" "$err" + fi + fi + + # ── contract 2: verdict ── + out=$(idd_actionability_verdict \ + --complexity-exit "$act_exit" \ + --parking-label "$has_label" \ + --blocking-section "$has_blocking" 2>/dev/null) + verdict="${out%%:*}" + verdict="${verdict// /}" + assert_eq "#$num verdict" "$exp_verdict" "$verdict" + + if [ "$exp_verdict" = "not-actionable" ]; then + got_reasons=$(printf '%s' "${out#*: }" | tr ';' '\n' | sed 's/^ *//; s/ *$//' | sort | paste -sd';' -) + assert_eq "#$num reasons" "$exp_reasons" "$got_reasons" + fi + + [ "$exp_verdict" = "actionable" ] && [ "$snapshot" = "true" ] && ACTIONABLE_SNAPSHOT+=("$num") +done <<<"$ROWS" + +# ── audit discipline: the cheap path must not be the unsafe one ────────────── +# A gate that treated an unanswered signal as "clear" would re-open the hole +# #298 closed, so every malformed invocation fails loud (exit 2) instead of +# defaulting to actionable. +if [ "$HELPER_PRESENT" -eq 1 ]; then + idd_actionability_verdict --complexity-exit 0 --parking-label no 2>/dev/null + assert_exit "missing --blocking-section fails loud" "2" "$?" + + idd_actionability_verdict --complexity-exit "" --parking-label no --blocking-section no 2>/dev/null + assert_exit "empty --complexity-exit fails loud" "2" "$?" + + idd_actionability_verdict --complexity-exit 0 --parking-label maybe --blocking-section no 2>/dev/null + assert_exit "non-boolean --parking-label fails loud" "2" "$?" + + idd_actionability_verdict --complexity-exit 9 --parking-label no --blocking-section no 2>/dev/null + assert_exit "out-of-range --complexity-exit fails loud" "2" "$?" + + idd_actionability_verdict --bogus-flag yes 2>/dev/null + assert_exit "unknown flag fails loud" "2" "$?" + + # display grouping: blocking-only keeps the #84 blocked group; anything else parks + assert_eq "blocking-only → blocked group" "blocked" "$(idd_actionability_group 'blocking-nonempty')" + assert_eq "parking label → parked group" "parked" "$(idd_actionability_group 'parking-lot-label')" + assert_eq "unparseable → parked group" "parked" "$(idd_actionability_group 'complexity-unparseable')" + assert_eq "mixed reasons → parked group" "parked" "$(idd_actionability_group 'complexity-unparseable; blocking-nonempty')" +fi + +# ── acceptance criterion (design.md): among the nine 2026-08-10 snapshot rows, +# exactly #37 is actionable. This is the regression of the actual incident. ── +snap_count=$(jq '[.[] | select(.snapshot)] | length' "$FIXTURE") +assert_eq "fixture carries the 9 snapshot rows" "9" "$snap_count" +assert_eq "only #37 actionable among snapshot" "37" "$(printf '%s' "${ACTIONABLE_SNAPSHOT[*]:-}")" + +print_summary "actionability-gate" diff --git a/plugins/issue-driven-dev/skills/idd-all/SKILL.md b/plugins/issue-driven-dev/skills/idd-all/SKILL.md index 1907d9e..574be20 100644 --- a/plugins/issue-driven-dev/skills/idd-all/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-all/SKILL.md @@ -511,32 +511,40 @@ idd-all 必須把 `--cwd "$CWD"` 傳給 idd-diagnose,否則 sub-skill 會在 Cla Skill(skill="issue-driven-dev:idd-diagnose", args="#$N --cwd $CWD") ``` -**讀回 complexity**:idd-diagnose 結束後 fetch issue comments,grep 最新 `## Diagnosis` 區塊的 `### Complexity` 欄位: +**讀回 complexity**:idd-diagnose 結束後 fetch issue comments,取最新 `## Diagnosis` 區塊的 body,**值域判定不在此處自行寫 regex**,改呼叫 [`references/actionability-gate.md`](../../references/actionability-gate.md) 契約下的共用實作: ```bash -COMPLEXITY=$(gh issue view "$N" --json comments \ +LATEST_DIAGNOSIS=$(gh issue view "$N" --json comments \ | python3 -c " import json, sys, re d = json.load(sys.stdin) diagnosis_comments = [c for c in d['comments'] if re.search(r'(?m)^## Diagnosis', c['body'])] # v2.68.0+ #59 — line-anchored regex avoids quoted/inline false-positives (mirrors check-diagnosis-readiness.sh) -if not diagnosis_comments: - print('UNKNOWN'); exit(0) -latest = diagnosis_comments[-1]['body'] -m = re.search(r'### Complexity\n(.+?)\n', latest) -print(m.group(1).strip() if m else 'UNKNOWN') +print(diagnosis_comments[-1]['body'] if diagnosis_comments else '') ") + +# 缺 helper 一律 fail loud + 指名 path,禁止 fallback 到私有 regex(契約 §Consumer contract) +. "$CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh" || { + echo "FATAL: missing $CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh — 不得改用私有 regex" >&2 + exit 1 +} + +TIER=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>/dev/null); CEXIT=$? +COMPLEXITY_ERR=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>&1 >/dev/null) # cexit≠0 時的 `unparseable-complexity: ` / `missing-complexity` ``` -| Complexity 值 | 下一步 | +Dispatch 以 `(CEXIT, TIER)` 為鍵,**四列 exit 0 的 tier 是封閉值域,不得依相似性外推第五個**: + +| `CEXIT` · `TIER` | 下一步 | |--------------|--------| -| `Simple` | Phase 3a: idd-implement | -| `Plan` | **attended → Phase 3p: `/idd-plan`**（該 skill 擁有 `EnterPlanMode` 閘門，approve 後自己 chain 到 idd-implement）;**unattended → Phase 3a: idd-implement**，並在 final report 標記 `[Plan tier deliberation skipped under unattended mode]` | -| `Plan via Layer V` (v2.50+) | 視同 `Plan` 處理 — verdict 是 user 在 idd-diagnose Step 3.4 選 escalate 觸發,routing 行為跟 bare `Plan` 一致 | -| `Spectra` | Phase 3b: spectra-discuss → spectra-propose → spectra-apply(unattended → 一輪收斂;attended → multi-turn 對話自然進行) | -| `SDD-warranted` (legacy alias) | 視同 `Spectra` 處理(v2.36.0+ backward compat) | -| `UNKNOWN` | **abort** — diagnose 沒判定 complexity,user 需手動釐清 | +| `0` · `Simple` | Phase 3a: idd-implement | +| `0` · `Plan` | **attended → Phase 3p: `/idd-plan`**（該 skill 擁有 `EnterPlanMode` 閘門，approve 後自己 chain 到 idd-implement）;**unattended → Phase 3a: idd-implement**，並在 final report 標記 `[Plan tier deliberation skipped under unattended mode]` | +| `0` · `Plan`（原值 `Plan via Layer V`,v2.50+）| 同上 — helper 已剝除 ` via <來源>` 後綴,verdict 是 user 在 idd-diagnose Step 3.4 選 escalate 觸發,routing 行為跟 bare `Plan` 一致 | +| `0` · `Spectra` | Phase 3b: spectra-discuss → spectra-propose → spectra-apply(unattended → 一輪收斂;attended → multi-turn 對話自然進行) | +| `0` · `SDD-warranted` (legacy alias) | 視同 `Spectra` 處理(v2.36.0+ backward compat) | +| `4` — 無 `### Complexity` 區段（含完全沒有 `## Diagnosis` comment）| **abort** — diagnose 沒判定 complexity,user 需手動釐清（即舊表的 `UNKNOWN` 列,語意不變）| +| `3` — 值落在封閉值域外（如 `Simple when triggered`）| **abort** — 印出 `$COMPLEXITY_ERR` 的 `unparseable-complexity: ` **原值**,要求 user 修正 Diagnosis,或把延期狀態改掛 `parking-lot` label。**禁止**截斷成 tier 前綴、**禁止**降級成 `Plan` 或任何其他 tier | -**Parser 對 `Plan via Layer V` 的處理**(v2.50+):上面 grep 抓 `### Complexity\n(.+?)\n` 會抓到整行 `Plan via Layer V`,在 routing dispatch 時必須提取 canonical tier。實作:`canonical_tier = COMPLEXITY.split(' via ')[0].strip()`,得 `Plan`,routing 同 bare `Plan`。Backward compat:bare `Plan` / `Simple` / `Spectra` / `SDD-warranted` 都不含 ` via `,split 後仍是原值。 +> **為何不在此處寫 regex（#298 → #316）**：本段原本就地用一條 `(.+?)` 窄化抓 `### Complexity` 標題下的整行，再自行 `split(' via ')` 取 canonical tier。那條 regex 對 `Simple when triggered` 這類**帶延期修飾語**的值會**匹配成功**，回傳一個非 tier 字串——它對不上任何 dispatch 列，卻也不是 `UNKNOWN`。舊表的 `UNKNOWN → abort` 安全網結構上接不住它：`UNKNOWN` 只在 regex **完全匹配失敗**時才產生（`if m else` 分支），值域外的**成功**匹配永遠落不進那一格，routing 因此進入未定義行為。修法不是把 regex 寫得更嚴——那只會讓第四份私有窄化加入既有的三方分歧——而是讓值域判定只剩一份實作：` via <來源>` 後綴剝除、封閉值域檢查、原值 surface 全在 `scripts/lib/actionability.sh`，本 skill 只讀它的 exit code。「不得截斷、不得降級、不得靜默」的規定見 [`references/actionability-gate.md`](../../references/actionability-gate.md)。 > **Layer V under (PR, unattended) — v2.50+**: Layer V Vagueness Pre-check (idd-diagnose Step 3.4) 在 unattended 仍評分 + 寫 audit trail,但 trigger 時自動 apply `proceed anyway` 不跳 AskUserQuestion。final report 應 surface `idd-diagnose` audit trail 中含 `[Layer V: V1=N V4=M, clarify-default skipped under unattended mode, defaulting to proceed]` 的 issue,讓 user 後續可以手動重 route。 > @@ -1017,7 +1025,8 @@ fi | gh auth 沒設定 | Phase 0.3 abort,提示 gh auth login | | Issue #N 不存在 / CLOSED | Phase 0 abort | | Branch 已存在 | Phase 0 AskUserQuestion(checkout / -2 suffix / abort) | -| Diagnose 判定 UNKNOWN complexity | Phase 2 abort,提示手動跑 idd-diagnose | +| Diagnosis 缺 `### Complexity` 區段(helper cexit=4) | Phase 2 abort,提示手動跑 idd-diagnose | +| `### Complexity` 值落在封閉值域外(helper cexit=3) | Phase 2 abort,印出 `unparseable-complexity: ` 原值;不截斷、不降級成任何 tier | | spectra-discuss 沒 emit `Conclusion:` line(unattended hint 失敗)| Re-prompt 一次;再失敗 abort,branch 保留 | | spectra-propose 沒 emit `Change:` line | 同上 | | spectra-propose 遇到 unrecoverable validation error | Phase 3b abort,artifacts 保留,提示手動 `/spectra-propose` | diff --git a/plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md b/plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md index ff5fe5e..326960c 100644 --- a/plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md @@ -601,13 +601,30 @@ Diagnosis 完成 + Step 3.4 Vagueness Pre-check 結束後（`type=meeting` 已 ``` ### Complexity -{Simple / Plan / Spectra} +{Simple / Plan / Spectra / SDD-warranted} {對 Simple：列出哪個 Layer 1 命中、或 Layer 2/P 都沒命中的說明} {對 Plan：列出觸發的 Layer P 信號} {對 Spectra：列出 Layer 2 + Layer 3 觸發項} ``` +##### 值域是封閉的（#298 → #316） + +**`### Complexity` 的第一個非空行只得是下列四個值之一 —— 這是封閉列舉，不得依相似性類推出第五個值：** + +1. `Simple` +2. `Plan` +3. `Spectra` +4. `SDD-warranted`（`Spectra` 的既有 backward-compat alias） + +該值**得**後接 ` via <來源>` provenance 後綴（v2.50 起的既有慣例）—— `Plan via Layer V`（Layer V escalate）與 `Spectra via hard-gate (sdd_bias)`（硬閘出口）皆為合法。canonical tier 是第一個 ` via ` 之前的文字。 + +**延期修飾語 SHALL NOT 寫進這個欄位。** `when triggered`、`(parking lot)`、`(deferred pending #N)`、以及任何說明「為什麼先擱著」的散文，都屬於 `parking-lot` label，不屬於這裡。理由是生命週期不同：Diagnosis comment 是 **append-only** 審計軌跡（見 [`rules/append-vs-modify.md`](../../rules/append-vs-modify.md)），而「是否 parked」**會變**（trigger 成立就該解除）。把可變狀態凍進不可變的 artifact，正是 #298 診斷出的根因 —— 實例：`#136` 的 comment 寫 bare `Spectra`、body 卻寫 `Spectra when triggered (parking lot)`，狀態改不動就自己漂到別處去了。 + +**本 skill SHALL NOT 貼、移除或推導 `parking-lot` label。** 該 label 是**人的裁決**，且可以在 diagnosis 寫完**之後**才下。實測 2026-08-10 的 11 筆 diagnosed issue，限定詞與 label 一致的只有 5 筆：`#37` 是 bare `Spectra` 而 label 由人事後貼上；`#131` / `#200` 則有限定詞卻無 label。兩者不是同一件事的兩種寫法 —— 由 producer 從限定詞推導 label，等於取消「人可以事後 park 一個 tier 明確的 issue」這條路徑。 + +> 完整契約（含 consumer 端的保守處置與 surface 規定）見 [`references/actionability-gate.md`](../../references/actionability-gate.md)。想表達「這件事先擱著」時，寫清楚 tier、然後貼 label。 + #### 各 verdict 的 Next Step | Verdict | Next Step | Flow | diff --git a/plugins/issue-driven-dev/skills/idd-implement/SKILL.md b/plugins/issue-driven-dev/skills/idd-implement/SKILL.md index 7ad09f6..001d13b 100644 --- a/plugins/issue-driven-dev/skills/idd-implement/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-implement/SKILL.md @@ -364,25 +364,41 @@ bash "$CLAUDE_PLUGIN_ROOT/scripts/gh-egress.sh" comment $NUMBER --repo $GITHUB_R ### Step 2.5: Bootstrap TodoList（non-Spectra case） -**判斷 Complexity routing**：讀最新的 diagnosis comment 的 `### Complexity` 欄位（v2.36.0+ 三路；v2.50+ 加 Layer V variant）： +**判斷 Complexity routing**：讀最新 `## Diagnosis` comment 的 `### Complexity` 欄位（v2.36.0+ 三路；v2.50+ 加 Layer V variant）。**值域判定不在此處自行寫 parser**，改呼叫 [`references/actionability-gate.md`](../../references/actionability-gate.md) 契約下的共用實作： -> **v2.50+ Parser 規則**：verdict 文字可能含 ` via X` 後綴(例如 `Plan via Layer V`),parser 必須提取 canonical tier。實作: -> -> ```python -> raw_complexity = match_group_after("### Complexity\n").strip() -> canonical_tier = raw_complexity.split(" via ")[0].strip() # "Plan via Layer V" → "Plan" -> # bare "Plan" / "Simple" / "Spectra" / "SDD-warranted" 都不含 " via ",backward compat 保留 -> ``` -> -> 對應 spec Requirement: Routing parsers SHALL recognize Plan via Layer V verdict。 +```bash +LATEST_DIAGNOSIS=$(gh issue view "$NUMBER" --repo "$GITHUB_REPO" --json comments \ + | python3 -c " +import json, sys, re +d = json.load(sys.stdin) +diagnosis_comments = [c for c in d['comments'] if re.search(r'(?m)^## Diagnosis', c['body'])] +print(diagnosis_comments[-1]['body'] if diagnosis_comments else '') +") + +# 缺 helper 一律 fail loud + 指名 path，禁止 fallback 到私有 parser（契約 §Consumer contract） +. "$CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh" || { + echo "FATAL: missing $CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh — 不得改用私有 parser" >&2 + exit 1 +} + +TIER=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>/dev/null); CEXIT=$? +COMPLEXITY_ERR=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>&1 >/dev/null) # cexit≠0 時的 `unparseable-complexity: ` / `missing-complexity` +``` + +` via <來源>` 後綴（例如 `Plan via Layer V`）由 helper 剝除，本 skill 拿到的 `$TIER` 已是 canonical tier — 對應 spec Requirement: Routing parsers SHALL recognize Plan via Layer V verdict。 + +Routing 以 `(CEXIT, TIER)` 為鍵，**exit 0 的四個 tier 是封閉值域，不得依相似性外推第五個**： -| Canonical tier | 行為 | +| `CEXIT` · `TIER` | 行為 | |-----------|------| -| `Simple` | ✅ 本 step 啟動 TaskList 追蹤每個 checklist item | -| `Plan` (含 `Plan via Layer V`) | ✅ 同 Simple — TaskList 啟動。**注意**：使用者通常透過 `/idd-plan #NNN` 呼叫進來，approval gate 已在 idd-plan 處理完，本 skill 直接走 TDD loop。若使用者直接呼叫 `/idd-implement` 而 Complexity=Plan，**先提示**「Complexity 判定為 Plan，建議改走 `/idd-plan #NNN` 進入 approval gate；繼續直接 implement 等於跳過 Plan tier 的 deliberation 價值」並用 AskUserQuestion 確認 continue/abort。`Plan via Layer V` 同樣行為(routing 一致),只是 verdict 標記提示這是 Layer V 觸發 | -| `Spectra` | ⏭ 跳過本 step（由 `spectra-apply` 管 `openspec/changes//tasks.md`）| -| `SDD-warranted` (legacy alias) | ⏭ 跳過本 step — 視同 `Spectra` 處理（v2.36.0+ backward compat）| -| _(missing / unclear)_ | ✅ 預設當 Simple，啟動 TaskList（保守作法）| +| `0` · `Simple` | ✅ 本 step 啟動 TaskList 追蹤每個 checklist item | +| `0` · `Plan`（原值可能是 `Plan via Layer V`）| ✅ 同 Simple — TaskList 啟動。**注意**：使用者通常透過 `/idd-plan #NNN` 呼叫進來，approval gate 已在 idd-plan 處理完，本 skill 直接走 TDD loop。若使用者直接呼叫 `/idd-implement` 而 Complexity=Plan，**先提示**「Complexity 判定為 Plan，建議改走 `/idd-plan #NNN` 進入 approval gate；繼續直接 implement 等於跳過 Plan tier 的 deliberation 價值」並用 AskUserQuestion 確認 continue/abort。`Plan via Layer V` 同樣行為(routing 一致),只是 verdict 標記提示這是 Layer V 觸發 | +| `0` · `Spectra` | ⏭ 跳過本 step（由 `spectra-apply` 管 `openspec/changes//tasks.md`）| +| `0` · `SDD-warranted` (legacy alias) | ⏭ 跳過本 step — 視同 `Spectra` 處理（v2.36.0+ backward compat）| +| `3` — 值落在封閉值域外（如 `Simple when triggered`）| 🛑 **停止實作** — 印出 `$COMPLEXITY_ERR` 的 `unparseable-complexity: ` **原值**，要求 user 修正 Diagnosis，或把延期狀態改掛 `parking-lot` label。**禁止**截斷成 tier 前綴、**禁止**降級成 `Simple` / `Plan` 或任何其他 tier、**禁止**沿用舊的「不確定就當 Simple」預設 | +| `4` — 無 `### Complexity` 區段（含完全沒有 `## Diagnosis` comment）| 🛑 **停止實作** — 印出 `missing-complexity`，提示先跑 `/idd-diagnose #$NUMBER` 判定 complexity。同樣不得代 user 挑一個 tier | + +> **為何不在此處自己解析（#298 → #316）**：本段原本規定就地取 `### Complexity` 標題底下那一行的原文，再以 ` via ` 分隔符切出前半當 canonical tier。那個做法對 `Simple when triggered` 這類**帶延期修飾語**的值會**成功產出**一個非 tier 字串——它對不上任何 routing 列，卻也不是「解析失敗」，只能落進舊表最後一列的 catch-all `_(missing / unclear)_ → 預設當 Simple`，把一個被人裁決延期的 issue 直接送進 TDD loop。「不確定就當 Simple」在 tier 已被寫壞時不是保守，是**代 user 挑了一個 tier**——契約明文禁止截斷、禁止降級、禁止靜默，所以該列已改為上表的 `3` / `4` 兩個停止列。修法不是把 parser 寫得更嚴——那只會讓第四份私有窄化加入既有的三方分歧——而是讓值域判定只剩一份實作：後綴剝除、封閉值域檢查、原值 surface 全在 `scripts/lib/actionability.sh`，本 skill 只讀它的 exit code。完整規定見 [`references/actionability-gate.md`](../../references/actionability-gate.md)。 **Simple / Plan case 執行**： diff --git a/plugins/issue-driven-dev/skills/idd-list/SKILL.md b/plugins/issue-driven-dev/skills/idd-list/SKILL.md index 6212919..12c495c 100644 --- a/plugins/issue-driven-dev/skills/idd-list/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-list/SKILL.md @@ -524,7 +524,21 @@ Suggested next: | `Spectra` (含 alias `SDD-warranted`) | `/spectra-discuss` (default) 或 `/spectra-propose` (opt-out) | | 推不出 | `/idd-implement #N` (保守 default) | -**Complexity 解析**：對 phase=`diagnosed` 的 issue，掃最新 `## Diagnosis` comment 的 `### Complexity` 行（regex `### Complexity\n([A-Za-z-]+)`），取第一個 token。`SDD-warranted` 視同 `Spectra`。Verdict 後綴(如 `Plan via Layer V`,v2.50.0+)用 `split(' via ')[0]` 取 canonical tier。 +**Complexity 解析**：**不要在此處自行寫 regex。** 依 [`references/actionability-gate.md`](../../references/actionability-gate.md) 的封閉值域契約，呼叫共用實作： + +```bash +. "$CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh" || { + echo "FATAL: missing $CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh — 不得改用私有 regex" >&2 + exit 1 +} +tier=$(idd_parse_complexity "$latest_diagnosis_body"); cexit=$? +``` + +**helper 缺失必須 fail loud**（契約要求）：silent fallback 回私有解析，正是本次要消滅的東西 —— 一個「找不到就自己想辦法」的 consumer 會把三方分歧原封不動地帶回來。 + +`cexit=0` → `$tier` 是 canonical tier（`SDD-warranted` 視同 `Spectra`；` via <來源>` 後綴已剝除），依上表 routing。**`cexit=3`（值在封閉值域外）或 `cexit=4`（缺區段）→ 不給任何 lifecycle 命令**，改依 Step 3.7 歸入 Parked 組並 surface 原值。 + +> **為何不在這裡寫 regex（#298 → #316）**：本行原本規定 `### Complexity\n([A-Za-z-]+)`「取第一個 token」—— 那個 regex 在第一個空白處停止，`Simple when triggered` 被截成 `Simple`，正是 Step 3.7 明文禁止的截斷。同一份 SKILL.md 裡一段禁止截斷、另一段規定截斷，實作者照哪段做行為就不同。解析規則現在只有一份，住在共用 helper 裡。 ## 鐵律 diff --git a/plugins/issue-driven-dev/skills/idd-plan/SKILL.md b/plugins/issue-driven-dev/skills/idd-plan/SKILL.md index 33915e6..eb2bb5a 100644 --- a/plugins/issue-driven-dev/skills/idd-plan/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-plan/SKILL.md @@ -39,7 +39,7 @@ description: | ``` TaskCreate(name="resolve_pr_path", description="Phase 0.5: --pr/--no-pr flag → fork detection → pr_policy config → ask. 若 PR path: 建 feature branch") -TaskCreate(name="read_issue_and_diagnosis", description="gh issue view + 確認最新 diagnosis comment 的 Strategy + Complexity == Plan/Simple") +TaskCreate(name="read_issue_and_diagnosis", description="gh issue view + 讀最新 diagnosis comment 的 Strategy;Complexity 值域判定一律走 scripts/lib/actionability.sh 的 idd_parse_complexity,不自行比對字串") TaskCreate(name="draft_implementation_plan", description="依 Strategy 起草 Implementation Plan（5 段：files + reasoning + tests + risks + sequence）並 comment 到 issue") TaskCreate(name="tangential_sweep", description="Step 2.5: review session log from Step 1 to here, identify mid-plan tangential discoveries (sister bugs / unrelated quality issues / user-mentioned sub-concerns); AskUserQuestion to file as follow-up issues; append filed list to plan body before ExitPlanMode (per IC_R011 #524)") TaskCreate(name="enter_plan_mode_for_approval", description="Step 4: EnterPlanMode → 呈現 full Implementation Plan → ExitPlanMode 等 user approve / revise / abort") @@ -56,14 +56,40 @@ TaskCreate(name="auto_update_body", description="Step 7: idd-update phase → pl gh issue view $NUMBER --repo $GITHUB_REPO --json title,body,labels,comments ``` -確認最新的 `## Diagnosis` comment 存在且 `### Complexity` 是 `Plan`（或 `Simple`，user 主動 deliberate）。 +**Complexity 值域判定不在此處自行比對字串**，改呼叫 [`references/actionability-gate.md`](../../references/actionability-gate.md) 契約下的共用實作： -| Complexity | 行為 | +```bash +LATEST_DIAGNOSIS=$(gh issue view "$NUMBER" --repo "$GITHUB_REPO" --json comments \ + | python3 -c " +import json, sys, re +d = json.load(sys.stdin) +diagnosis_comments = [c for c in d['comments'] if re.search(r'(?m)^## Diagnosis', c['body'])] # line-anchored,避免引述/inline 誤判 +print(diagnosis_comments[-1]['body'] if diagnosis_comments else '') +") + +# 缺 helper 一律 fail loud + 指名 path,禁止 fallback 到私有檢查(契約 §Consumer contract) +. "$CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh" || { + echo "FATAL: missing $CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh — 不得改用私有 Complexity 檢查" >&2 + exit 1 +} + +TIER=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>/dev/null); CEXIT=$? +COMPLEXITY_ERR=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>&1 >/dev/null) # cexit≠0 時的 `unparseable-complexity: ` / `missing-complexity` +``` + +以 `(CEXIT, TIER)` 為鍵決定行為。**exit 0 的四個 tier 是封閉值域,不得依相似性外推第五個**： + +| `CEXIT` · `TIER` | 行為 | |-----------|------| -| `Plan` | ✅ 預期 — 繼續 | -| `Simple` | ⚠️ 詢問 user：「Complexity 判定為 Simple，確定要走 Plan tier 多一道 approval gate 嗎？」 | -| `Spectra` (含 alias `SDD-warranted`) | ⛔ 提示「Spectra 應走 `/spectra-discuss`，Plan tier 不會產出 spec/proposal/tasks artifacts」，AskUserQuestion abort 或 continue（continue 等於 user 自願降級到 Plan tier） | -| _(missing)_ | ⛔ 提示「找不到 diagnosis，先跑 `/idd-diagnose #NNN`」並 abort | +| `0` · `Plan` | ✅ 預期 — 繼續 Step 2 | +| `0` · `Plan`（原值 `Plan via Layer V`）| 同上 — helper 已剝除 ` via <來源>` 後綴,canonical tier 即 `Plan`,行為與 bare `Plan` 完全一致 | +| `0` · `Simple` | ⚠️ 詢問 user：「Complexity 判定為 Simple，確定要走 Plan tier 多一道 approval gate 嗎？」（行為不變 — user 主動要 deliberate 是允許的）| +| `0` · `Spectra` | ⛔ 提示「Spectra 應走 `/spectra-discuss`，Plan tier 不會產出 spec/proposal/tasks artifacts」，AskUserQuestion abort 或 continue（continue 等於 user 自願降級到 Plan tier）— 行為不變 | +| `0` · `SDD-warranted`（legacy alias）| 視同 `Spectra` 處理 — 行為不變 | +| `3` — 值落在封閉值域外（如 `Plan when triggered`）| ⛔ **abort** — 印出 `$COMPLEXITY_ERR` 的 `unparseable-complexity: ` **原值**，要求 user 修正 Diagnosis，或把延期狀態改掛 `parking-lot` label。**禁止**截斷成 tier 前綴、**禁止**降級成 `Plan` 或任何其他 tier、**禁止**當成 `Simple` 問過 user 就繼續 | +| `4` — 無 `### Complexity` 區段（含完全沒有 `## Diagnosis` comment）| ⛔ **abort** — 提示「找不到 diagnosis / Complexity 判定，先跑 `/idd-diagnose #NNN`」（即舊表的 _(missing)_ 列，語意不變）| + +> **為何不在此處自行認定 tier（#298 → #316）**：本 step 原本用一句散文自行認定「`### Complexity` 是 `Plan`（或 `Simple`）」，值域外的值沒有任何定義行為。像 `Plan when triggered` 這種**帶延期修飾語**的歷史寫法，字面以 `Plan` 開頭、讀起來像 Plan tier，很容易被直接放行進 approval gate —— 但它真正的意思是「這件事被人為延期了」。`### Complexity` 的值域是**封閉的四個 tier**（可帶 ` via <來源>` 後綴），延期狀態屬於 `parking-lot` label，不屬於這個欄位。修法不是把散文判準寫得更嚴 —— 那只會讓第 N 份私有窄化加入既有的多方分歧 —— 而是讓值域判定只剩一份實作：後綴剝除、封閉值域檢查、原值 surface 全在 `scripts/lib/actionability.sh`，本 skill 只讀它的 exit code。「不得截斷、不得降級、不得靜默」的規定見 [`references/actionability-gate.md`](../../references/actionability-gate.md)。 ### Step 2: Draft Implementation Plan From dbadd382bc822f8b3a7e66b66173b692f2eb127f Mon Sep 17 00:00:00 2001 From: che cheng Date: Mon, 7 Sep 2026 14:07:45 +0900 Subject: [PATCH 2/6] =?UTF-8?q?docs:=20add-actionability-gate=20=E7=AC=AC?= =?UTF-8?q?=202=20=E8=BC=AA=20re-baseline=20=E2=80=94=E2=80=94=20=E5=80=BC?= =?UTF-8?q?=E5=9F=9F=E8=A6=8F=E5=89=87=E6=94=B9=E4=BB=A5=20159=20=E7=AD=86?= =?UTF-8?q?=20corpus=20=E5=AE=9A=E5=BD=A2=20(#316)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 第 1 輪的封閉值域被 /idd-verify --pr 318 CRITICAL-2 證偽：90 筆真實 diagnosis 有 38 筆 落在值域外，其中只有 9 筆是延期修飾語，22 筆是「tier + 同行理由」的正常寫法。分界畫錯了 位置 —— 不在「後面有沒有字」，而在「那些字是否表達延期」。 /idd-reorganize #316 裁定：design D1/D3/D5、spec R1/R3/R7 redo；D2/D4/D6/D7/D8 still-valid。 /idd-diagnose #316 第 2 輪以完整 corpus（225 issue 中 159 筆有 Diagnosis）重新定規則： 剝裝飾 → 取 tier prefix → 對整個值掃延期語彙。158/158，0 false positive。 本 commit 只動 Spectra artifact（ingest 產物），不動 code： - design.md：三個決策重寫並留「前版為何被推翻」註記；新增「風險姿態：label 為主、 語彙為輔」——延期語彙是開放列舉，漏抓有 label 兜底、誤抓會硬停正常工作，所以取高精度 - spec.md：R1/R3/R7 重寫，延期偵測獨立成 requirement（7 → 8 條）；reason 值域 4 → 5， 新增 complexity-deferral-marker —— 與 unparseable 分離，因為人的處置不同（前者確認 label、後者修 diagnosis） - proposal.md：BREAKING 敘述移除。「9 筆需 migration」是從有偏樣本推的；新規則對既有 全部語料都對，migration 為零 - tasks.md：保留 10 [x] + 2 [~]，新增第 6–9 組共 10 個 task。7.1 明寫「只換 parser 不 呼叫 verdict 等於沒修」—— 第 1 輪 gate 完整實作、66 測試全綠、零 consumer 呼叫 Refs #298, #310 --- .../.idd/attachments/issue-316/_manifest.json | 6 + .../changes/add-actionability-gate/design.md | 127 +++++++++++++----- .../add-actionability-gate/proposal.md | 17 ++- .../specs/actionability-gate/spec.md | 104 +++++++++----- .../changes/add-actionability-gate/tasks.md | 30 +++++ 5 files changed, 211 insertions(+), 73 deletions(-) create mode 100644 .claude/.idd/attachments/issue-316/_manifest.json diff --git a/.claude/.idd/attachments/issue-316/_manifest.json b/.claude/.idd/attachments/issue-316/_manifest.json new file mode 100644 index 0000000..8dd8164 --- /dev/null +++ b/.claude/.idd/attachments/issue-316/_manifest.json @@ -0,0 +1,6 @@ +{ + "issue": 316, + "fetched_at": "2026-08-15T10:08:39Z", + "fetched_by": "idd-diagnose", + "files": [] +} diff --git a/openspec/changes/add-actionability-gate/design.md b/openspec/changes/add-actionability-gate/design.md index c742b9c..53e3d4f 100644 --- a/openspec/changes/add-actionability-gate/design.md +++ b/openspec/changes/add-actionability-gate/design.md @@ -13,7 +13,7 @@ 實測另一項數據推翻了「限定詞與 label 資訊重複」的假設：11 個 issue 中兩者**一致的只有 5 個**。`#37` 是 bare `Spectra` 加 `parking-lot` label（人事後 park）；`#131` 與 `#200` 是有限定詞、無 label（diagnose 判 parked 但無人貼 label）；`#136` 的 comment 與 body 甚至彼此分岔。兩者不是同一資訊的兩種寫法，而是**兩個會分岔的訊號**。 -約束：`rules/append-vs-modify.md` 規定 Diagnosis comment 是 append-only 審計軌跡。既有的 `### Conflict Class` 契約（openspec/specs/parallel-orchestration/spec.md）已示範了正確形狀 —— 封閉值域、absent 或 unparseable 時保守預設、且必須 surface —— 本設計以之為對照模型。 +約束：`rules/append-vs-modify.md` 規定 Diagnosis comment 是 append-only 審計軌跡。既有的 `### Conflict Class` 契約（openspec/specs/parallel-orchestration/spec.md）示範了**保守預設 + 強制 surface**這一半的正確形狀，本設計沿用；但它的**封閉值域**那一半不可照搬 —— Conflict Class 由 `idd-diagnose` 以五個固定 key 寫入，`### Complexity` 的實際產出卻是自由散文（159 筆語料中 93% 帶理由或裝飾）。同一個 producer、兩種欄位紀律，這正是前版誤植的來源。 ## Goals / Non-Goals @@ -23,7 +23,7 @@ - 把 parked 這個**會變的狀態**從不可變的 artifact 遷到可變的 metadata - 消除三個 consumer 各自窄化 `### Complexity` 的分岔 - 保留 #84 既有的 Blocked 分組輸出行為，不退化 -- 建立可被未來新欄位繼承的通則：被 routing 消費的欄位必須宣告封閉值域與 unparseable 契約 +- 建立可被未來新欄位繼承的通則：**被 routing 消費的欄位，其判準必須以真實語料驗證**，不得從有偏樣本推導 **Non-Goals:** @@ -32,18 +32,51 @@ - **不讓 producer 自動貼 `parking-lot` label**（理由見決策「parked label 維持人工裁決」）。 - **不把 Strategy `[~] 暫緩` 納入 gate**（理由見決策「gate 採三訊號」）。 - **不做 parked issue 的回訪／staleness 機制** —— 已獨立為 #310。本變更會把 parked 藏得更乾淨、放大該問題，但兩者範圍分離。 -- **不改寫既有 Diagnosis comment 的歷史內容**（理由見決策「migration 只貼 label」）。 -- **不退役 `SDD-warranted`** —— 它是 `Spectra` 的既有 backward-compat alias，留在封閉值域內。 +- **不改寫既有 Diagnosis comment 的歷史內容**（理由見決策「零 migration」）。 +- **不退役 `SDD-warranted`** —— 它是 `Spectra` 的既有 backward-compat alias，仍是合法 tier。 +- **不把延期語彙清單當成封閉列舉**。它是高精度的經驗規則，不是定義；漏抓由 `parking-lot` label 兜底。 ## Decisions -### Complexity 回歸純封閉值域，parked 遷出至 label +### tier 以 prefix 抽取，延期以語彙偵測，parked 主訊號在 label -`### Complexity` 的合法值僅四個 tier（`Simple` / `Plan` / `Spectra` / `SDD-warranted`），各自可帶既有的 ` via <來源>` 後綴慣例。parked 狀態改由 `parking-lot` label 單獨承載。 +> **本決策於 2026-08-15 重寫**（前版：「Complexity 回歸純封閉值域」）。前版把「tier 後接文字」等同於「延期修飾語」，被 `/idd-verify --pr 318` CRITICAL-2 以真實語料證偽。原文保留於 git history。 -理由：根因不是 parser 太窄，而是**把會變的狀態存進不可變的 artifact**。Diagnosis comment 是 append-only，parked 卻會變（trigger 成立就該 unpark）。`#136` 的 comment 與 body 分岔，正是狀態被凍住後自行漂移的自然實驗。IDD 已經知道正確做法 —— `### Blocking` 正因為會變才放在 body 由 `idd-update` 維護。 +`idd_parse_complexity` 依序：**(1)** 剝除前後 markdown 裝飾 → **(2)** 取 tier prefix（第一個 ` via ` 之前；tier 須為 `Simple` / `Plan` / `Spectra` / `SDD-warranted` 之一）→ **(3)** 對**整個值**掃延期語彙，命中則不路由。 -替代方案：(a) 讓 `when triggered` 成為合法後綴，兩訊號並存 —— 但實測已證明兩者會分岔，並存就必須定義優先序，而該優先序沒有非任意的答案；(b) 只加寬三個 parser —— 會讓三個 consumer 一致地讀到一個會分岔的訊號，一致地錯比不一致地錯更難發現。 +tier 之後的其餘文字（同行理由、括號說明）**是合法的**，不影響 tier 抽取。 + +**理由（159 筆 corpus 實證）**：本 repo 全部 225 個 issue 中 159 筆有 Diagnosis。形狀分佈： + +| 形狀 | 數量 | 佔比 | +|---|---|---| +| tier + 同行理由 | 66 | 41.5% | +| bare tier | 45 | 28.3% | +| bare tier + markdown 裝飾 | 37 | 23.3% | +| tier + ` via <來源>` | 1 | 0.6% | +| **tier + 延期語彙** | **9** | **5.7%** | +| 無區段 | 1 | 0.6% | + +**分界不在「後面有沒有字」，而在「那些字是否表達延期」。** 前版的分界把 93.1% 的正常寫法與 5.7% 的延期寫法切在同一邊，導致 66 筆本該路由的 issue 變成 hard abort。 + +本規則在完整 corpus 上：**149 筆正確路由 + 9 筆正確擋下 = 158/158，0 false positive。** + +延期語彙目前為 `when triggered` / `parking lot` / `deferred` / `暫緩`。偵測必須掃**整個值**而非只掃 tier 之後 —— `#136` 的 tier 是 bare `Spectra`，延期語彙藏在括號理由內。 + +替代方案：(a) 前版的純封閉值域 —— 已被 corpus 證偽（42% 誤判率）；(b) 維持舊的 `([A-Za-z-]+)` 截斷 —— 對裝飾值（37 筆）完全不匹配、對延期值（9 筆）誤判可動，錯誤率 29%；(c) 只認 tier prefix 不做延期偵測 —— 那 9 筆延期會被誤判可動，等同回到 #298 的原始 bug。 + +### 風險姿態：label 為主、語彙為輔 + +延期語彙是**開放列舉**（新措辭隨時可能出現），因此失敗方向必須明確界定： + +| 失敗 | 後果 | 兜底 | 可見性 | +|---|---|---|---| +| **漏抓**延期 | 退回 pre-#298 行為（以 tier 路由）| `parking-lot` label | label 在 | +| **誤抓**延期 | 正常 issue 被擋下 | 無 | 原值有 surface，人一眼可辨 | + +因此：**`parking-lot` label 是 parked 的主要訊號**（人為裁決、可變、無歧義）；Complexity 的延期語彙是**次要安全網**，覆蓋 legacy 與未貼 label 的情形。語彙清單取**高精度、容忍低召回** —— 漏抓有 label 兜底，誤抓會擋住正常工作。 + +這與前版的姿態相反：前版讓 Complexity 欄位做主要判定，於是任何解析不確定都變成硬停。 ### gate 採三訊號，Strategy 暫緩標記排除在外 @@ -51,13 +84,29 @@ actionability gate 的輸入是三個訊號：`### Complexity` 非合法值、`p 理由：`[~]` 的既有 consumer 是 `idd-close` 的 checklist gate，語意是「close 時這個 checklist item 刻意跳過」—— 那是 per-item 的 close-time disposition，不是 per-issue 的「現在可不可以動」。把它拉進 routing gate 等於用回答 A 問題的訊號去回答 B 問題，且會與 `idd-close` 的既有語意衝突。 -### unparseable 的保守處置為 not-actionable 並強制 surface +### 三種不可路由狀態各有獨立 reason 並一律 surface -`### Complexity` 值不在封閉值域內時，gate 判定 not-actionable，且**必須顯示原始值**供人判讀，絕不靜默截斷。完全缺少 `### Complexity` 區段時同樣 not-actionable，理由標為 missing。 +> **本決策於 2026-08-15 重寫**（前版：「unparseable 的保守處置」）。「不得靜默截斷 / 不得降級 / 不得中斷 listing」三條**未被推翻、原樣保留**；被推翻的是「什麼算不可路由」的定義。 -理由：完全對稱於 `### Conflict Class` 的 `D_diagnose_first` 契約 —— 保守預設加強制 surface。既有 `idd-all` 的 `UNKNOWN` 安全網只覆蓋「regex 完全沒 match」，結構上接不住「match 到但值非法」，本決策把兩種失敗都納入。 +`idd_parse_complexity` 的非零出口分成**三種**，各有獨立 reason： -替代方案：降級為 `Plan` —— 否決，`Plan` 仍是可動 tier，仍會把 parked issue 送進 `/idd-plan`；中斷整個 `idd-list` —— 否決，對 surfacing-only 工具過重，一筆壞資料會堵死全部輸出。 +| 狀況 | exit | reason | stderr | +|---|---|---|---| +| tier prefix 不是四值之一 | 3 | `complexity-unparseable` | `unparseable-complexity: <原值>` | +| 缺 `### Complexity` 區段 | 4 | `complexity-missing` | `missing-complexity` | +| **tier 合法但值含延期語彙** | **5** | **`complexity-deferral-marker`** | **`deferral-marker: <原值>`** | + +三者一律**顯示原始值**供人判讀。 + +**為何延期要獨立於 unparseable**：兩者的**人工處置完全不同**。`complexity-unparseable` 是**資料錯誤**（diagnosis 寫壞了，該修 diagnosis）；`complexity-deferral-marker` 是**正常狀態**（這件事確實被延期了，該做的是確認 label、不是修 diagnosis）。用同一個 reason 表達會讓 `/idd-list` 的 Parked 分組把「壞資料」和「正常延期」混在一起，人看不出哪些需要動手修。 + +三條不變的禁令（前版保留）： + +- **SHALL NOT** 靜默截斷成 tier prefix —— 那是 2026-08-10 事故本身 +- **SHALL NOT** 降級為任何 tier（含 `Plan`）—— `Plan` 仍是可動 tier +- **SHALL NOT** 中斷整個 listing —— 一筆壞資料不得壓掉其餘 issue + +對稱於 `### Conflict Class` 的 `D_diagnose_first` 契約：保守預設 + 強制 surface。 ### 解析與判定抽為共用 helper @@ -65,13 +114,19 @@ actionability gate 的輸入是三個訊號：`### Complexity` 非合法值、`p 理由：`.claude/rules/deep-integration-over-hardcode.md` 的反複製判準 —— 同構機件兩處維護等於同一個 bug 要修多次，本 issue 正是該失敗模式的實例（三處實作、三種行為）。 -### migration 只貼 label，不改寫歷史 +### 零 migration —— 新規則對既有全部語料都給正確結果 -既有 9 筆帶限定詞的 Diagnosis comment **維持原狀不改寫**。migration 的動作只有兩種：對應 issue 補上 `parking-lot` label（若缺），以及 `#128` 由人重新判斷。 +> **本決策於 2026-08-15 重寫**（前版：「migration 只貼 label，不改寫歷史」，且宣稱「9 筆需 migration」）。前版的論證是「legacy 值走 unparseable 路徑得到的正是正確結果」—— 對 `Spectra（opt-out → 直接 propose）` 而言那是**錯的**（該 issue 可動），論證基礎已崩解。 -理由：改寫既有 Diagnosis comment 的 `### Complexity` 是 modify-in-place 一個 append-only 審計 artifact，違反 `rules/append-vs-modify.md`。而且**不需要改寫** —— legacy 限定詞值在新契約下落入 unparseable 路徑，判定為 not-actionable 並顯示原值，對那 8 個 parked issue 而言正是正確結果。封閉值域約束的是**新產出的** diagnosis；歷史值由 unparseable 路徑正確承接。 +**migration 動作為零。** 既有 Diagnosis comment 一律不改寫，也不需要補任何 label 來讓 gate 給出正確答案。 -替代方案：回填改寫 —— 否決，違反 append-only 且無必要；永久放寬值域容忍 legacy —— 否決，會讓封閉值域名存實亡。 +理由：新規則在 159 筆 corpus 上**158/158 全對** —— 149 筆正確路由、9 筆正確擋下。既有語料完全不需要調整就能被正確解讀。前版所謂「9 筆需 migration」是從封閉值域的錯誤前提推出的；真實需求是 **0 筆**。 + +append-only 紀律仍然成立且更容易守：既然不需要改寫任何歷史 comment，也就不存在違反 `rules/append-vs-modify.md` 的誘因。 + +**與 `parking-lot` label 的關係**：label 仍是 parked 的主要訊號（見「風險姿態」決策），但它的價值在**未來**（人事後 park 一個 tier 明確的 issue、以及延期語彙漏抓時的兜底），不是在補救歷史。既有那 9 筆 parked issue 由延期語彙正確擋下，貼不貼 label 都不影響 verdict。 + +替代方案：仍補 label 以求「雙保險」—— 否決，那會把 0-migration 變成 9-migration 而不改變任何 verdict，是無收益的動作，且與「label 表達人的裁決」的語意相衝（替一個工具已判定的事後補人為標記，等於偽造裁決紀錄）。 ### parked label 維持人工裁決，producer 不自動貼 @@ -97,45 +152,53 @@ gate 產出 verdict 加 reason 清單；顯示層依 reason 分兩組 —— rea **Interface** — 共用 helper 提供兩個函式： -- `idd_parse_complexity`：輸入為 Diagnosis comment 全文，stdout 為 canonical tier（四個合法值之一）。exit 0 表示合法（bare tier 或帶 ` via <來源>` 後綴）；exit 3 表示區段存在但值不在封閉值域，stderr 輸出 `unparseable-complexity: <原始值>`；exit 4 表示缺少 `### Complexity` 區段，stderr 輸出 `missing-complexity`。 +- `idd_parse_complexity`：輸入為 Diagnosis comment 全文，stdout 為 canonical tier。exit 0 = tier prefix 為四值之一且值內無延期語彙（後接理由 / 裝飾 / ` via <來源>` 皆合法）；exit 3 = tier prefix 非四值之一，stderr `unparseable-complexity: <原始值>`；exit 4 = 缺 `### Complexity` 區段，stderr `missing-complexity`；**exit 5 = tier 合法但值含延期語彙**，stderr `deferral-marker: <原始值>`。三個非零出口一律 surface 原值。 - `idd_actionability_verdict`：輸入為前一函式的 exit code、是否帶 `parking-lot` label、`### Blocking` 是否非空。stdout 為 `actionable`，或 `not-actionable: [; ...]`；exit 0 為 actionable、exit 1 為 not-actionable。 -**Reason 值域**（封閉列舉，四個）：`complexity-unparseable`、`complexity-missing`、`parking-lot-label`、`blocking-nonempty`。 +**Reason 值域**（封閉列舉，**五個**）：`complexity-unparseable`、`complexity-missing`、**`complexity-deferral-marker`**、`parking-lot-label`、`blocking-nonempty`。 **Failure modes** — 非法 Complexity 值一律 surface，絕不靜默截斷或降級為合法 tier。helper 本身不可用（檔案缺失）時，呼叫端 fail-loud 並指出缺失路徑，不 silent degrade 回舊行為。gate 不對「trigger 條件是否已成立」做任何判斷，該問題明確在範圍外。 **Acceptance criteria** - 新增測試以既有慣例落在 `plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh`，並登錄進 `plugins/issue-driven-dev/scripts/run-all-tests.sh`。 -- fixture 為靜態對照表，記錄 issue 號、Complexity 原始值、labels、期望 verdict，覆蓋 2026-08-10 快照的 9 筆 diagnosed 路由，斷言其中只有 `#37` 為 actionable。fixture 不查詢 live GitHub。 -- 三個代表性 legacy 值（`Simple when triggered`、`Spectra when triggered (parking lot)`、`#128` 的散文值）經 `idd_parse_complexity` 皆回 exit 3 並在 stderr 顯示原值。 +- fixture 為靜態對照表，記錄 issue 號、Complexity 原始值、labels、期望 verdict。**必須覆蓋 corpus 的四種真實形狀各至少 3 筆**：bare tier、tier + 同行理由（`Spectra（opt-out → 直接 propose）` 類）、markdown 裝飾（`**Spectra**`）、延期語彙。fixture 不查詢 live GitHub，且**不得只收錄為驗證假設而挑的樣本**（前版 fixture 15 筆中 9 筆刻意選延期形狀，是本次失敗的成因之一）。 +- 全 corpus 回歸：對 159 筆真實 diagnosis 跑 `idd_parse_complexity`，斷言 **149 筆 exit 0 且 tier 正確、9 筆 exit 5、1 筆 exit 4、0 筆 exit 3**。 +- 三個代表性延期值（`Simple when triggered`、`Spectra when triggered (parking lot)`、`**Spectra**(Layer 2 + Layer 3 if/when triggered)`）皆回 exit 5 並顯示原值。 +- 三個代表性正常值（`Spectra（opt-out → 直接 propose）`、`Plan（Layer P：…）`、`Simple — 單檔、2 個 1-token 補丁…`）皆回 exit 0 且 tier 分別為 `Spectra` / `Plan` / `Simple`。 - 兩個既有的合法後綴值（`Plan via Layer V`、`Spectra via hard-gate (sdd_bias)`）經 `idd_parse_complexity` 回 exit 0 且 canonical tier 分別為 `Plan` 與 `Spectra`。 - #84 既有行為回歸測試：帶非空 `### Blocking` 的 issue 仍列於 Blocked 分組，該分組標題、全 blocked banner 文案、footer 計數與變更前逐字相同。 **Scope boundaries** -- 範圍內：Complexity 值域契約、三訊號 gate、共用 helper、四個 skill 的引用改寫、`ic-r011-checkpoint.md` 的 label 名稱收斂、測試與 fixture、9 筆 issue 的 label migration。 +- 範圍內：Complexity 解析契約（prefix + 裝飾剝除 + 延期語彙）、三訊號 gate **及其在四個 consumer 的實際接線**、共用 helper、`ic-r011-checkpoint.md` 的 label 名稱收斂、測試與 fixture、verify #318 的 2 CRITICAL + 21 HIGH findings。 - 範圍外：parked 回訪／staleness 機制（#310）、`--limit` 排序缺陷（#299）、trigger 條件的機械判定、`idd-close` 對 Strategy `[~]` 的既有處理、grooming 機制的實作。 ## Risks / Trade-offs - **#84 行為退化** → 顯示層分兩組而非合併，Blocked 分組的標題、banner、footer 計數列入回歸測試逐字比對。 -- **四個 skill 改寫不同步，只修一處等於沒修** → 抽共用 helper，並在測試中對四個引用點各驗一次；只修 `idd-list` 會讓 `idd-all` 的未定義行為留存。 -- **與 #299 同檔衝突** → 兩者都修改 `plugins/issue-driven-dev/skills/idd-list/SKILL.md`，需序列化或合併為同一 PR；conflict class 已判為需序列化。 -- **legacy 值走 unparseable 路徑，verdict 對但 reason 不精確** → reason 會標為 `complexity-unparseable`（資料問題）而非 parked。緩解：surface 原始值，人看到 `Simple when triggered` 即可理解實情。這是不改寫歷史所付的已知代價。 -- **本變更讓 parked 藏得更乾淨，放大無回訪機制的問題** → 已獨立為 #310 並在 Non-Goals 明記；本變更不因此擴大範圍。 +- **gate 實作了卻沒接上**（verify #318 CRITICAL-1 的實際發生）→ `idd_actionability_verdict` 在前一輪完整實作、66 個測試全綠，但四個 consumer 一個都沒呼叫它，`parking-lot` 與 `### Blocking` 照樣被繞過。緩解：驗收條件明列「四個引用點各驗一次**呼叫了 verdict**」，而不只驗「helper 自身行為正確」——測 helper 不等於測它被使用。 +- **四個 skill 改寫不同步，只修一處等於沒修** → 抽共用 helper，並在測試中對四個引用點各驗一次。 +- **延期語彙漏抓**（開放列舉的固有代價）→ 退化成 pre-#298 行為，由 `parking-lot` label 兜底；不是新失敗。 +- **延期語彙誤抓** → 正常 issue 被擋下。目前 corpus 零誤中，但語料會成長。緩解：語彙清單保守；原值一律 surface；出現誤抓時的正確修法是**收窄語彙**，不是放寬 gate。 +- **與 #299 同檔衝突** → 兩者都修改 `plugins/issue-driven-dev/skills/idd-list/SKILL.md`，需序列化或合併為同一 PR。 +- **本變更讓 parked 藏得更乾淨，放大無回訪機制的問題** → 已獨立為 #310 並在 Non-Goals 明記。 ## Migration Plan -1. helper 與新 reference 落地，四個 skill 改為引用共用實作。 -2. 測試與 fixture 落地並登錄進 test runner。 -3. 對 8 個既有 parked issue 補齊 `parking-lot` label（`#131`、`#200` 目前有限定詞但缺 label；其餘已有）。**不改寫任何 Diagnosis comment。** -4. `#128` 交由人重新判斷 —— 其 Complexity 值為散文（tier 後接未決 UX 軸的敘述），需決定該 issue 是 parked 或可動，再決定是否貼 label。 +**無資料 migration。** 新規則對既有 159 筆語料 158/158 全對，不需要回填 label、不需要改寫任何 Diagnosis comment。 + +實作順序（非 migration，是落地順序）： + +1. helper 的解析規則改寫（prefix + 裝飾剝除 + 延期語彙 + exit 5），並修 verify 指出的 HIGH findings（`shift 2` 無限迴圈、`set -e` command-substitution 提前中止、awk code-fence 感知、` via ` 後綴的延期夾帶）。 +2. fixture 重建為 corpus 抽樣 + 全 corpus 回歸測試。 +3. 四個 consumer 改寫：不只換 parser，**要真的呼叫 `idd_actionability_verdict`**（讀 labels + `### Blocking`）。 +4. `idd-diagnose` producer 宣告改寫（不再宣告封閉值域，改為「延期意圖請貼 label、不要寫進本欄」）。 5. `ic-r011-checkpoint.md` 的 label 名稱收斂。 -Rollback：本變更為 skill 文件、helper script 與 label 的變更，無資料遷移。回退方式為 revert commit 加撕除步驟 3 補上的 label；既有 Diagnosis comment 全程未被修改，無不可逆狀態。 +Rollback：本變更為 skill 文件與 helper script 的變更，零資料遷移、零 label 異動。回退方式為 revert commit，無不可逆狀態。 ## Open Questions -- `#128` 的正確處置需人判斷，migration 步驟 4 才能完成。其值為「tier 後接未決 UX 軸」的散文，無法機械判定該 issue 是 parked 還是可動。 -- `ic-r011-checkpoint.md` 的兩個 `blocker:*` label 是「退役」還是「與 parking-lot 分工」，需在該檔改寫時定案。目前 0 使用，傾向退役，但若原設計意圖是區分 infeasible 與 waiting 兩種 parked 成因，則應保留並明記與 `parking-lot` 的關係。 +- **延期語彙清單的擴充機制未定。** 目前四個語彙由 159 筆 corpus 歸納而得。語料成長後若出現新措辭，是誰、依什麼判準把它加進清單？本變更不解決；先記錄為已知缺口。 +- `ic-r011-checkpoint.md` 的兩個 `blocker:*` label 是「退役」還是「與 parking-lot 分工」，需在該檔改寫時定案。目前 0 使用，傾向退役。 diff --git a/openspec/changes/add-actionability-gate/proposal.md b/openspec/changes/add-actionability-gate/proposal.md index 25d9859..caf60e7 100644 --- a/openspec/changes/add-actionability-gate/proposal.md +++ b/openspec/changes/add-actionability-gate/proposal.md @@ -1,5 +1,7 @@ ## Why +> **第 2 輪 re-baseline（2026-08-15）**：`/idd-verify --pr 318` FAIL（2 CRITICAL / 21 HIGH）。CRITICAL-2 以 90 筆真實語料證偽第 1 輪的封閉值域前提；`/idd-reorganize #316` 完成裁定；`/idd-diagnose #316` 第 2 輪以 **159 筆完整 corpus** 重新定出值域規則（158/158，0 false positive）。本 proposal 的 What Changes / Impact 已依該結論重寫；design D1/D3/D5 與 spec R1/R3/R7 同步重寫，其餘決策經裁定為 still-valid 而保留。 +> > **Re-scope note（2026-08-14）**：本 change 於 #298 仍 open 時提出。走完 discuss → propose、進入 apply 時發現 **#298 已由 PR #309 / #306 修掉並 close** —— 但修正**只落在 `idd-list`**，另三個 consumer（`idd-all` / `idd-implement` / `idd-plan`）未動，且 `idd-list` 自身 Step 5 仍文載會截斷的 regex，與新增的 Step 3.7 直接矛盾。本 change 遂 re-scope 為**承接剩餘缺口**，追蹤於 **#316**；已完成的共用 helper、canonical 契約與回歸測試（全新檔、與已 merge 內容零衝突）原樣保留。Migration 相關 task 因目標 issue 全數 close 而 moot。 @@ -11,15 +13,15 @@ ## What Changes -- **`### Complexity` 回歸純封閉值域** —— 合法值僅 `Simple` / `Plan` / `Spectra` / `SDD-warranted`，各自可帶既有的 ` via <來源>` 後綴慣例。`when triggered` 這類限定詞不再寫進此欄位。**BREAKING**：既有 9 筆帶限定詞的 diagnosis 值在新契約下為非法，需 migration。 -- **parked 狀態改由 `parking-lot` label 單獨承載** —— 人可貼可撕，成為唯一 source of truth。實測 11 個 issue 中限定詞與 label 只有 5 個一致，證明兩者不是重複而是會分岔的兩個訊號。 -- **新增 actionability gate** —— 三訊號 OR 判定，放行需三者皆不成立：`### Complexity` 非合法值、`parking-lot` label 存在、`### Blocking` 區塊非空。 -- **default-on-unparseable = not-actionable + surface** —— 對稱於 `### Conflict Class` 的 `D_diagnose_first` 契約：不放行、必須顯示原始值、絕不靜默。 +- **`### Complexity` 的 tier 以 prefix 抽取，容許同行理由** —— 剝裝飾 → 取 ` via ` 之前的 tier prefix → tier 須為 `Simple` / `Plan` / `Spectra` / `SDD-warranted` 之一。tier 之後的理由、括號說明、provenance 後綴**皆為合法**，不影響抽取。 +- **延期以語彙偵測，並有獨立 reason** —— 對**整個值**掃 `when triggered` / `parking lot` / `deferred` / `暫緩`，命中則不路由，reason 為 `complexity-deferral-marker`（與 `complexity-unparseable` 分離 —— 前者是正常狀態、後者是資料錯誤，人的處置不同）。 +- **`parking-lot` label 是 parked 的主要訊號**，延期語彙是次要安全網。語彙清單取高精度、容忍低召回。 +- **新增 actionability gate** —— 三訊號 OR 判定（Complexity 不可路由、`parking-lot` label、`### Blocking` 非空），放行需三者皆不成立，**且四個 consumer 必須實際呼叫它**。 - **三個 consumer 的 Complexity 解析統一** —— `idd-list`、`idd-all`、`idd-implement`（含 `idd-plan` 的 tier 確認）改用共用 helper，消除各自窄化。 - **`### Blocking` 抽取重構為 gate 的 input** —— #84 既有的 Blocked 分組輸出行為不得退化。 -- **`idd-diagnose` producer 端宣告封閉值域** —— 明訂限定詞不得寫入，parked 意圖改以 label 表達。 -- **既有 9 筆 diagnosis migration** —— 8 筆機械處理（剝限定詞、必要時補 label）、#128 需人重新判斷（其值為散文，非 tier 加限定詞結構）。 -- **`references/ic-r011-checkpoint.md` 的 parking 慣例收斂** —— 該檔宣稱的 `blocker:infeasible` 與 `blocker:waiting` 目前 0 個 issue 在用，實際在用的是 `parking-lot`（6 個）。 +- **`idd-diagnose` producer 端明訂延期意圖走 label** —— 不再宣告封閉值域；改為「tier 寫清楚、延期貼 label、不要把延期寫進本欄」。 +- **零 migration** —— 新規則對既有 159 筆語料 158/158 全對，不需回填 label、不需改寫任何 Diagnosis comment。 +- **`references/ic-r011-checkpoint.md` 的 parking 慣例收斂** —— `blocker:infeasible` / `blocker:waiting` 目前 0 個 issue 在用，實際在用的是 `parking-lot`。 ## Capabilities @@ -51,4 +53,5 @@ - `plugins/issue-driven-dev/references/ic-r011-checkpoint.md` - Removed: (none) - 同檔衝突：#299（`--limit` 先於排序生效）同樣修改 `plugins/issue-driven-dev/skills/idd-list/SKILL.md`，兩者需序列化或合併處理。 +- 追蹤 issue 由 #298 改為 **#316**（#298 已由 PR #309 / #306 修掉並 close，只涵蓋 `idd-list`）。 - 配套 issue：#310（parked issue 無回訪機制）—— 本變更把 parked 藏得更乾淨，會放大該問題，但不在本次範圍內。 diff --git a/openspec/changes/add-actionability-gate/specs/actionability-gate/spec.md b/openspec/changes/add-actionability-gate/specs/actionability-gate/spec.md index d45c621..fef3004 100644 --- a/openspec/changes/add-actionability-gate/specs/actionability-gate/spec.md +++ b/openspec/changes/add-actionability-gate/specs/actionability-gate/spec.md @@ -1,34 +1,43 @@ ## ADDED Requirements -### Requirement: Closed value domain for the Complexity field +### Requirement: Complexity tier extraction tolerates trailing rationale -The `### Complexity` field emitted by `idd-diagnose` SHALL carry exactly one of four tier values: `Simple`, `Plan`, `Spectra`, or `SDD-warranted`. A tier value SHALL also be accepted when followed by the existing ` via ` provenance suffix, in which case the canonical tier SHALL be the text preceding the first ` via ` separator. Qualifiers that express deferral state, such as `when triggered` or `(parking lot)`, SHALL NOT be written into this field; deferral state belongs to the `parking-lot` label instead. Consumers SHALL treat any other value as outside the domain. +The system SHALL extract the routing tier from the `### Complexity` field by (1) stripping leading and trailing markdown decoration, (2) taking the tier prefix — the text preceding the first ` via ` separator — and (3) requiring that prefix to be exactly one of `Simple`, `Plan`, `Spectra`, or `SDD-warranted`. Any further text on the value line — same-line rationale, parenthetical explanation, or a ` via ` provenance suffix — SHALL NOT prevent tier extraction. Trailing rationale is the producer's normal writing style: in a corpus of 159 real diagnoses in this repository, 93.1% of values carry decoration, rationale, or a provenance suffix, and only 5.7% express deferral. -#### Scenario: Bare tier is accepted +#### Scenario: Bare tier is extracted -- **WHEN** a Diagnosis comment contains a `### Complexity` section whose value is `Spectra` -- **THEN** the canonical tier resolves to `Spectra` -- **AND** the value is inside the closed domain +- **WHEN** the value is `Spectra` +- **THEN** the extracted tier is `Spectra` -#### Scenario: Provenance suffix is accepted and stripped +#### Scenario: Same-line rationale does not block extraction -- **WHEN** a Diagnosis comment contains a `### Complexity` section whose value is `Plan via Layer V` -- **THEN** the canonical tier resolves to `Plan` -- **AND** the value is inside the closed domain +- **WHEN** the value is `Spectra（opt-out → 直接 propose）` +- **THEN** the extracted tier is `Spectra` +- **AND** the value is treated as routable -#### Scenario: Deferral qualifier is outside the domain +#### Scenario: Markdown decoration is stripped -- **WHEN** a Diagnosis comment contains a `### Complexity` section whose value is `Simple when triggered` -- **THEN** the value is reported as outside the closed domain -- **AND** the canonical tier is not resolved to `Simple` +- **WHEN** the value is `**Plan**` +- **THEN** the extracted tier is `Plan` + +#### Scenario: Provenance suffix is stripped + +- **WHEN** the value is `Plan via Layer V` +- **THEN** the extracted tier is `Plan` + +#### Scenario: Non-tier prefix is not routable + +- **WHEN** the value is `移入 discussion list` +- **THEN** no tier is extracted +- **AND** the reason reported is `complexity-unparseable` ### Requirement: Actionability gate evaluates three signals disjunctively -The system SHALL determine whether a diagnosed issue is actionable by evaluating exactly three signals: whether the `### Complexity` value is outside the closed domain or absent, whether the `parking-lot` label is present on the issue, and whether the `### Blocking` section of the issue body is non-empty. The issue SHALL be reported as actionable only when none of the three signals holds. The `- [~]` disposition marker inside a Diagnosis `### Strategy` checklist SHALL NOT be an input to this gate, because that marker is a close-time per-item disposition consumed by `idd-close` rather than a per-issue actionability signal. +The system SHALL determine whether a diagnosed issue is actionable by evaluating exactly three signals: whether the `### Complexity` value is non-routable for any reason (unparseable prefix, absent section, or deferral vocabulary), whether the `parking-lot` label is present on the issue, and whether the `### Blocking` section of the issue body is non-empty. The issue SHALL be reported as actionable only when none of the three signals holds. The `- [~]` disposition marker inside a Diagnosis `### Strategy` checklist SHALL NOT be an input to this gate, because that marker is a close-time per-item disposition consumed by `idd-close` rather than a per-issue actionability signal. #### Scenario: All three signals clear -- **WHEN** an issue has a `### Complexity` value inside the closed domain, carries no `parking-lot` label, and has an empty `### Blocking` section +- **WHEN** an issue has a routable `### Complexity` value, carries no `parking-lot` label, and has an empty `### Blocking` section - **THEN** the gate reports the issue as actionable #### Scenario: Parking label alone withholds the issue @@ -42,36 +51,57 @@ The system SHALL determine whether a diagnosed issue is actionable by evaluating - **WHEN** an issue has all three gate signals clear and its Diagnosis `### Strategy` checklist contains a `- [~]` item - **THEN** the gate reports the issue as actionable -### Requirement: Conservative verdict and mandatory surfacing on non-domain Complexity +### Requirement: Deferral vocabulary withholds routing under its own reason + +The system SHALL scan the **entire** `### Complexity` value — not only the text following the tier — for deferral vocabulary, and SHALL withhold the issue from routing when any is found, even though the tier prefix is valid. This condition SHALL carry the distinct reason `complexity-deferral-marker`, separate from `complexity-unparseable` and `complexity-missing`, because the three call for different human responses: an unparseable value is a data defect to correct, a missing section is a diagnosis that never ran, and a deferral marker is a legitimate state requiring no repair. The deferral vocabulary SHALL NOT be treated as a closed enumeration — it is a high-precision heuristic, and the `parking-lot` label remains the primary parked signal. + +#### Scenario: Deferral vocabulary withholds a valid tier + +- **WHEN** the value is `Simple when triggered` +- **THEN** the issue is reported as not actionable with reason `complexity-deferral-marker` +- **AND** the string `Simple when triggered` appears in the operator-facing output -When the `### Complexity` value is outside the closed domain, the system SHALL report the issue as not actionable and SHALL surface the original unmodified value to the operator. When the `### Complexity` section is absent entirely, the system SHALL report the issue as not actionable with a distinct reason. The system SHALL NOT silently truncate a non-domain value to a tier prefix, SHALL NOT downgrade it to any tier, and SHALL NOT abort the enclosing listing operation. +#### Scenario: Deferral vocabulary inside a parenthetical is still detected -#### Scenario: Non-domain value surfaces verbatim +- **WHEN** the value is `**Spectra**(Layer 2 + Layer 3 if/when triggered)` +- **THEN** the issue is reported as not actionable with reason `complexity-deferral-marker` -- **WHEN** the gate evaluates an issue whose `### Complexity` value is `Spectra when triggered (parking lot)` -- **THEN** the issue is reported as not actionable with reason `complexity-unparseable` -- **AND** the string `Spectra when triggered (parking lot)` appears in the operator-facing output +#### Scenario: Deferral reason is distinct from unparseable -#### Scenario: Missing section is distinguished from non-domain value +- **WHEN** one issue has the value `Plan when triggered` and another has the value `移入 discussion list` +- **THEN** the first reports reason `complexity-deferral-marker` +- **AND** the second reports reason `complexity-unparseable` -- **WHEN** the gate evaluates a Diagnosis comment that contains no `### Complexity` section +### Requirement: Conservative verdict and mandatory surfacing on non-routable Complexity + +When a `### Complexity` value cannot be routed for any reason, the system SHALL report the issue as not actionable and SHALL surface the original unmodified value to the operator. A missing `### Complexity` section SHALL report reason `complexity-missing`. The system SHALL NOT silently truncate a non-routable value to a tier prefix, SHALL NOT downgrade it to any tier, and SHALL NOT abort the enclosing listing operation. + +#### Scenario: Missing section is distinguished from a non-routable value + +- **WHEN** a Diagnosis comment contains no `### Complexity` section - **THEN** the issue is reported as not actionable with reason `complexity-missing` #### Scenario: One bad value does not suppress other issues -- **WHEN** a listing contains one issue with a non-domain `### Complexity` value and other issues with valid values +- **WHEN** a listing contains one issue with a non-routable `### Complexity` value and other issues with routable values - **THEN** the listing reports every issue - **AND** the listing operation does not abort +#### Scenario: No downgrade to a routable tier + +- **WHEN** a value is reported as not actionable for any complexity reason +- **THEN** no tier is emitted for routing +- **AND** the issue is not dispatched to any lifecycle command + ### Requirement: Single shared implementation of parsing and verdict -Complexity parsing and actionability verdict logic SHALL exist as one shared implementation. Every consumer that routes on `### Complexity` — `idd-list`, `idd-all`, `idd-implement`, and `idd-plan` — SHALL invoke that shared implementation rather than embedding its own parsing. The verdict reason vocabulary SHALL be the closed set `complexity-unparseable`, `complexity-missing`, `parking-lot-label`, `blocking-nonempty`. When the shared implementation is unavailable, a consumer SHALL fail loudly and name the missing path rather than degrade to a private parsing path. +Complexity parsing and actionability verdict logic SHALL exist as one shared implementation. Every consumer that routes on `### Complexity` — `idd-list`, `idd-all`, `idd-implement`, and `idd-plan` — SHALL invoke that shared implementation rather than embedding its own parsing. The verdict reason vocabulary SHALL be the closed set `complexity-unparseable`, `complexity-missing`, `complexity-deferral-marker`, `parking-lot-label`, `blocking-nonempty`. When the shared implementation is unavailable, a consumer SHALL fail loudly and name the missing path rather than degrade to a private parsing path. #### Scenario: All routing consumers agree on the same input - **WHEN** the same Diagnosis comment containing `Simple when triggered` is evaluated by each routing consumer -- **THEN** every consumer reports the value as outside the closed domain -- **AND** no consumer resolves a canonical tier from it +- **THEN** every consumer reports the value as non-routable under reason `complexity-deferral-marker` +- **AND** no consumer dispatches the issue to a lifecycle command, even though the tier prefix `Simple` is itself well-formed #### Scenario: Missing helper fails loudly @@ -108,12 +138,18 @@ The gate SHALL produce a verdict together with its reason list, and the display - **WHEN** an issue carries a `### Complexity` value of `Spectra` and a human applies the `parking-lot` label afterwards - **THEN** the gate reports the issue as not actionable with reason `parking-lot-label` -### Requirement: Legacy Diagnosis values are handled without rewriting history +### Requirement: Existing diagnoses require no migration + +Existing Diagnosis comments SHALL NOT be rewritten, and no label SHALL be backfilled, in order for the gate to produce correct verdicts on them. The extraction and deferral rules SHALL be validated against the repository's full diagnosis corpus, and that validation SHALL be a regression test rather than a one-off check. + +#### Scenario: Full corpus produces correct verdicts unmodified -Existing Diagnosis comments that carry deferral qualifiers in `### Complexity` SHALL NOT be rewritten to satisfy the closed value domain. The closed value domain SHALL constrain newly emitted diagnoses, and legacy values SHALL be carried by the non-domain path, which yields a not-actionable verdict with the original value surfaced. Migration SHALL be limited to applying the `parking-lot` label where it is absent. +- **WHEN** the gate evaluates every existing Diagnosis comment in the repository +- **THEN** every value carrying a valid tier without deferral vocabulary yields that tier +- **AND** every value carrying deferral vocabulary is withheld with reason `complexity-deferral-marker` +- **AND** no Diagnosis comment content is modified -#### Scenario: Legacy value yields the correct verdict without edit +#### Scenario: Fixture reflects real shapes rather than a hypothesis-confirming sample -- **WHEN** the gate evaluates an issue whose Diagnosis comment still reads `Simple when triggered` and which carries no `parking-lot` label -- **THEN** the issue is reported as not actionable -- **AND** the Diagnosis comment content is unchanged +- **WHEN** the regression fixture is reviewed +- **THEN** it contains at least three cases each of bare tier, tier with same-line rationale, decorated tier, and deferral vocabulary diff --git a/openspec/changes/add-actionability-gate/tasks.md b/openspec/changes/add-actionability-gate/tasks.md index aa1f5b4..a22186e 100644 --- a/openspec/changes/add-actionability-gate/tasks.md +++ b/openspec/changes/add-actionability-gate/tasks.md @@ -31,3 +31,33 @@ - [~] 5.1 對既有 parked issue 補齊 `parking-lot` label —— **moot（2026-08-14）**：migration 目標 `#131` / `#200` / `#128` 在 2026-08-10 之後全部被 close（backlog 已清，非 park）。決策「migration 只貼 label，不改寫歷史」仍然成立且已由 helper 的 unparseable 路徑承接 —— legacy 值判為 not-actionable 並 surface 原值，無需回填。驗證（2026-08-14 實測）：載入共用 helper，對**當前全部 open issue** 逐一跑 `idd_parse_complexity` —— **域外值（exit 3）數量為 0**，需補 `parking-lot` label 的 open issue 數為 0。整個 migration 類別在 live backlog 中為空集合，非僅原列三筆已 close。同時這也是 helper 對真實資料的 end-to-end 驗證。 涵蓋需求：Legacy Diagnosis values are handled without rewriting history。 - [~] 5.2 由人重新判斷 `#128` 的處置 —— **moot（2026-08-14）**：`#128` 已 CLOSED，處置已由 backlog 清理決定，無待判事項。原內容：行為契約：`#128` 的 `### Complexity` 值為散文（tier 後接未決 UX 軸敘述），需由人決定該 issue 為 parked 或可動，並據以決定是否貼 `parking-lot` label。驗證：`#128` 的裁決結果以 `/idd-comment --type decision` 記錄於該 issue，且 label 狀態與裁決一致。 + +## 6. 值域規則重寫（第 2 輪 — post re-baseline） + +> 前 5 組的 `[x]` 為第 1 輪成果，**不回退**：helper 骨架、契約文件、四個 consumer 的引用點與 fail-loud guard、producer 段落位置、`blocker:*` 收斂皆仍有效。本組修的是**判準本身**與第 1 輪漏掉的接線。 + +- [ ] 6.1 重寫 `idd_parse_complexity` 的 tier 判定，落實決策「tier 以 prefix 抽取，延期以語彙偵測，parked 主訊號在 label」。行為契約：剝裝飾 → 取 ` via ` 前的 tier prefix → 對**整個值**掃延期語彙。exit 0 = 可路由；exit 3 = tier prefix 非四值之一；exit 4 = 缺區段；**exit 5 = tier 合法但含延期語彙**，stderr `deferral-marker: <原值>`。驗證：三個代表性正常值（`Spectra（opt-out → 直接 propose）` / `Plan（Layer P：…）` / `Simple — 單檔、2 個 1-token 補丁…`）回 exit 0 且 tier 正確；三個代表性延期值（`Simple when triggered` / `Spectra when triggered (parking lot)` / `**Spectra**(Layer 2 + Layer 3 if/when triggered)`）回 exit 5。檔案：`plugins/issue-driven-dev/scripts/lib/actionability.sh` 涵蓋需求：Complexity tier extraction tolerates trailing rationale、Deferral vocabulary withholds routing under its own reason。 + +- [ ] 6.2 reason 值域擴為五值，新增 `complexity-deferral-marker`，落實決策「三種不可路由狀態各有獨立 reason 並一律 surface」。行為契約：`idd_actionability_verdict` 接受 `--complexity-exit 0|3|4|5`；exit 5 → reason `complexity-deferral-marker`。`idd_actionability_group` 對該 reason 回 `parked`。驗證：測試斷言 `Plan when triggered` 得 `complexity-deferral-marker` 而 `移入 discussion list` 得 `complexity-unparseable`，兩者 reason 不同。檔案：`plugins/issue-driven-dev/scripts/lib/actionability.sh` 涵蓋需求：Conservative verdict and mandatory surfacing on non-routable Complexity。 + +- [ ] 6.3 [P] 修 verify #318 的 HIGH findings（helper 側）。行為契約：(a) option 缺 value 時回 exit 2 具名錯誤，不再因 `shift 2` 失敗而無限迴圈；(b) awk 追蹤 ``` 與 ~~~ code fence 並忽略其內 heading，且在同級或更高級 heading 結束；(c) ` via ` 後綴內的延期語彙同樣被偵測（不得成為逃生孔）。驗證：三類各補負向測試（value-less flag ×3、fenced-example body、`Simple via when triggered`）。檔案：`plugins/issue-driven-dev/scripts/lib/actionability.sh` + +- [ ] 6.4 [P] 修 verify #318 的 HIGH finding（consumer 側 `set -e` 相容）。行為契約：contract 範例與四個 SKILL.md 的呼叫形狀改為條件位置捕捉（`if TIER=$(...); then CEXIT=0; else CEXIT=$?; fi`），使 exit 3/4/5 與 verdict 的 exit 1 不會在 `set -euo pipefail` 下終止 caller。驗證：新增 `set -euo pipefail` 的整合測試，斷言一筆不可路由的 issue 不會中斷整個 listing。檔案：`plugins/issue-driven-dev/references/actionability-gate.md`、四個 consumer SKILL.md + +## 7. 接上三訊號 gate（verify CRITICAL-1） + +- [ ] 7.1 四個 consumer 實際呼叫 `idd_actionability_verdict`。行為契約：每個 consumer 讀該 issue 的 labels 與 body 的 `### Blocking` 區塊，連同 `idd_parse_complexity` 的 exit code 一併送進 verdict，並依其 exit 0/1/2 分支（2 = API 誤用，不得與 not-actionable 混同）。**只換 parser 不呼叫 verdict 等於沒修** —— 第 1 輪即是如此：gate 完整實作、66 測試全綠、零 consumer 呼叫。驗證：測試對四個引用點各驗一次「verdict 被呼叫且 labels/Blocking 有被讀取」，而非只驗 helper 自身行為。檔案：`plugins/issue-driven-dev/skills/idd-list/SKILL.md`、`skills/idd-all/SKILL.md`、`skills/idd-implement/SKILL.md`、`skills/idd-plan/SKILL.md` 涵蓋需求：Actionability gate evaluates three signals disjunctively、Single shared implementation of parsing and verdict。 + +- [ ] 7.2 `idd-list` 顯示層依 reason 分兩組。行為契約：reason 僅 `blocking-nonempty` → 維持 #84 既有 Blocked 分組；其餘（含 `complexity-deferral-marker`）→ Parked 分組並顯示原值。驗證：測試斷言 #84 的分組標題、全 blocked banner 文案、footer 計數與變更前逐字相同。檔案：`plugins/issue-driven-dev/skills/idd-list/SKILL.md` 涵蓋需求：Blocked-state output is preserved as a distinct display group。 + +## 8. 測試重建 + +- [ ] 8.1 fixture 重建為 corpus 抽樣。行為契約：四種真實形狀各至少 3 筆（bare tier / tier + 同行理由 / markdown 裝飾 / 延期語彙），逐字取自真實 diagnosis，不得只收錄為驗證假設而挑的樣本。驗證：內容審查確認四類數量達標且每筆標註來源 issue 號。檔案：`plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/parked-routing.json` 涵蓋需求：Existing diagnoses require no migration。落實決策「零 migration —— 新規則對既有全部語料都給正確結果」——fixture 的存在意義正是把這個宣稱變成可回歸的斷言，而非一次性檢查。 + +- [ ] 8.2 新增全 corpus 回歸測試。行為契約：對 159 筆真實 diagnosis 跑 `idd_parse_complexity`，斷言 149 筆 exit 0 且 tier 正確、9 筆 exit 5、1 筆 exit 4、**0 筆 exit 3**。corpus 快照存為 fixture，不查詢 live GitHub。驗證：執行 plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh 該項通過。檔案：`plugins/issue-driven-dev/scripts/tests/actionability-gate/` + +## 9. 文件同步（第 2 輪） + +- [ ] 9.1 `references/actionability-gate.md` 依新規則重寫。行為契約：封閉值域段改為「tier prefix 抽取 + 延期語彙」；reason 值域 4 → 5；新增「風險姿態：label 為主、語彙為輔」段並說明漏抓/誤抓的不對稱處置。驗證：內容審查確認不再出現「合法值域為封閉四值」的宣稱，且 corpus 數據（159 筆 / 158-158）有明文引用。檔案：`plugins/issue-driven-dev/references/actionability-gate.md` + +- [ ] 9.2 [P] `idd-diagnose` producer 宣告改寫。行為契約：移除封閉值域宣告，改為「tier 寫清楚；延期意圖貼 `parking-lot` label，不要寫進 `### Complexity`」，並保留「producer 不自動貼 label」一條。驗證：內容審查確認不再宣告封閉值域，且 159 筆語料的常態寫法（tier + 同行理由）未被規定為違規。檔案：`plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md` From 6e5003b8c9461e941b1f5232bc80c117f16624c0 Mon Sep 17 00:00:00 2001 From: che cheng Date: Mon, 7 Sep 2026 14:18:08 +0900 Subject: [PATCH 3/6] =?UTF-8?q?docs:=20task=207.1=20=E8=A3=9C=20comments?= =?UTF-8?q?=20=E6=88=AA=E6=96=B7=E7=B4=84=E6=9D=9F=20=E2=80=94=E2=80=94=20?= =?UTF-8?q?consumer=20=E6=8A=93=20latest=20Diagnosis=20=E9=A0=88=20--pagin?= =?UTF-8?q?ate=20(#316)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit rebase onto main 3.0.0 後重看 pending task：main 於 2026-08-15 post-merge audit 為 idd-list 記下 `--json comments` 硬截最舊 100 則的問題，並明寫「不得只在其中一個 consumer 修」。 本 change 的三個 consumer snippet 有同一個洞 —— latest Diagnosis 正是 >100 則時被丟掉的 那則，helper 會誤回 complexity-missing。修法沿用 check-closed-without-summary.sh 的現成實作。 Refs #335 --- openspec/changes/add-actionability-gate/tasks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openspec/changes/add-actionability-gate/tasks.md b/openspec/changes/add-actionability-gate/tasks.md index a22186e..a8f6bbe 100644 --- a/openspec/changes/add-actionability-gate/tasks.md +++ b/openspec/changes/add-actionability-gate/tasks.md @@ -46,7 +46,7 @@ ## 7. 接上三訊號 gate（verify CRITICAL-1） -- [ ] 7.1 四個 consumer 實際呼叫 `idd_actionability_verdict`。行為契約：每個 consumer 讀該 issue 的 labels 與 body 的 `### Blocking` 區塊，連同 `idd_parse_complexity` 的 exit code 一併送進 verdict，並依其 exit 0/1/2 分支（2 = API 誤用，不得與 not-actionable 混同）。**只換 parser 不呼叫 verdict 等於沒修** —— 第 1 輪即是如此：gate 完整實作、66 測試全綠、零 consumer 呼叫。驗證：測試對四個引用點各驗一次「verdict 被呼叫且 labels/Blocking 有被讀取」，而非只驗 helper 自身行為。檔案：`plugins/issue-driven-dev/skills/idd-list/SKILL.md`、`skills/idd-all/SKILL.md`、`skills/idd-implement/SKILL.md`、`skills/idd-plan/SKILL.md` 涵蓋需求：Actionability gate evaluates three signals disjunctively、Single shared implementation of parsing and verdict。 +- [ ] 7.1 四個 consumer 實際呼叫 `idd_actionability_verdict`。行為契約：每個 consumer 讀該 issue 的 labels 與 body 的 `### Blocking` 區塊，連同 `idd_parse_complexity` 的 exit code 一併送進 verdict，並依其 exit 0/1/2 分支（2 = API 誤用，不得與 not-actionable 混同）。**只換 parser 不呼叫 verdict 等於沒修** —— 第 1 輪即是如此：gate 完整實作、66 測試全綠、零 consumer 呼叫。**另（2026-09-07 rebase 後補記）**：四個 consumer 抓 latest Diagnosis 時**不得**用 `gh issue view --json comments` —— 它把巢狀 connection 解成 `comments(first: 100)`，硬截成**最舊** 100 則；超過 100 則 comment 的 issue，最新 Diagnosis 正是被丟掉的那則，helper 會誤回 exit 4 `complexity-missing`。改用 `gh api repos/:o/:r/issues/N/comments --paginate --jq '[.[]|{body}]' | jq -s add`（main `idd-list` Step 2 於 2026-08-15 post-merge audit 已規定同款修法，且明寫「不得只在其中一個 consumer 修」；`scripts/check-closed-without-summary.sh` 已有現成實作可抄）。驗證：測試對四個引用點各驗一次「verdict 被呼叫且 labels/Blocking 有被讀取」，而非只驗 helper 自身行為；另 grep 四份 SKILL.md 確認抓 comments 的路徑皆為 `--paginate`，無殘留 `--json comments`。檔案：`plugins/issue-driven-dev/skills/idd-list/SKILL.md`、`skills/idd-all/SKILL.md`、`skills/idd-implement/SKILL.md`、`skills/idd-plan/SKILL.md` 涵蓋需求：Actionability gate evaluates three signals disjunctively、Single shared implementation of parsing and verdict。 - [ ] 7.2 `idd-list` 顯示層依 reason 分兩組。行為契約：reason 僅 `blocking-nonempty` → 維持 #84 既有 Blocked 分組；其餘（含 `complexity-deferral-marker`）→ Parked 分組並顯示原值。驗證：測試斷言 #84 的分組標題、全 blocked banner 文案、footer 計數與變更前逐字相同。檔案：`plugins/issue-driven-dev/skills/idd-list/SKILL.md` 涵蓋需求：Blocked-state output is preserved as a distinct display group。 From 0a250fc73949cdf5420a7db57890c44bf9e1ce1c Mon Sep 17 00:00:00 2001 From: che cheng Date: Mon, 7 Sep 2026 14:55:10 +0900 Subject: [PATCH 4/6] =?UTF-8?q?feat:=20actionability=20gate=20round=202=20?= =?UTF-8?q?=E2=80=94=20prefix=20tier,=20deferral=20vocabulary,=20gate=20wi?= =?UTF-8?q?red=20into=20all=20four=20consumers?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refs #316 (round-2 re-baseline of PR #318) Round 1 declared a closed value domain for `### Complexity` and shipped a three-signal gate that no consumer called; /idd-verify --pr 318 returned FAIL (CRITICAL-1 unwired, CRITICAL-2 domain refuted by the 159-diagnosis corpus: 66 real values wrongly refused). Helper (scripts/lib/actionability.sh) - tier = leading whole word among Simple|Plan|Spectra|SDD-warranted after decoration strip; rationale / parenthetical / ` via` suffix are legal - whole first line scanned for deferral vocabulary -> exit 5, stderr `deferral-marker: `, no stdout (tier prefix never routable) - reason vocabulary 4 -> 5 (`complexity-deferral-marker`, group = parked) - new idd_blocking_section (idd-update's `- (none)` placeholder is empty) - shared fence-aware section extractor (``` / ~~~; same-or-higher heading ends) - value-less flag -> named exit 2 (was an infinite loop) Consumers (idd-list / idd-all / idd-implement / idd-plan) - actually call idd_actionability_verdict with all three signals - paginate the Diagnosis fetch (gh issue view --json comments = oldest 100) - set -euo pipefail-safe conditional capture; exit 2 is FATAL, not withheld - idd-list: Parked group added; #84 blocked heading/banner/footer verbatim Tests (225 assertions) - fixture rows now verbatim Diagnosis comment values; corpus-sampled shapes >=3 each; #128 pinned as the designed prose-deferral miss - frozen 159-issue corpus regression: 149 / 9 / 1 / 0 - strict-mode integration test; consumer-wiring drift guard Docs: references/actionability-gate.md rewritten (risk posture, corpus table, canonical call shape); idd-diagnose producer declaration rewritten; CHANGELOG 3.1.0; version 3.0.0 -> 3.1.0. --- .claude-plugin/marketplace.json | 4 +- .../changes/add-actionability-gate/design.md | 4 +- .../add-actionability-gate/proposal.md | 6 +- .../specs/actionability-gate/spec.md | 2 +- .../changes/add-actionability-gate/tasks.md | 20 +- .../.claude-plugin/plugin.json | 2 +- plugins/issue-driven-dev/CHANGELOG.md | 89 ++ .../references/actionability-gate.md | 205 ++- .../scripts/lib/actionability.sh | 204 ++- .../fixtures/corpus-complexity.json | 1118 +++++++++++++++++ .../fixtures/parked-routing.json | 280 ++++- .../scripts/tests/actionability-gate/test.sh | 286 ++++- .../issue-driven-dev/skills/idd-all/SKILL.md | 60 +- .../skills/idd-diagnose/SKILL.md | 17 +- .../skills/idd-implement/SKILL.md | 55 +- .../issue-driven-dev/skills/idd-list/SKILL.md | 103 +- .../issue-driven-dev/skills/idd-plan/SKILL.md | 55 +- 17 files changed, 2197 insertions(+), 313 deletions(-) create mode 100644 plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/corpus-complexity.json diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index f1b1f1f..d32a45a 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -15,8 +15,8 @@ "plugins": [ { "name": "issue-driven-dev", - "version": "3.0.0", - "description": "v3.0.0 (BREAKING): the closing-summary helper may VETO and may never PERMIT. After twelve verify rounds failing in one direction — a real summary the recogniser could not follow classified `missing`, and `missing` being the sole authorisation for `/idd-close --retroactive` to post a duplicate — the power was split along the direction that is sound. \"A marker IS here\" is an observation; \"a marker is NOT here\" is an inference from a failure to recognise, and no matcher over source bytes can answer a question about rendered output in the negative. Gate exit codes are now 1 (recognised) / 2 (undeterminable) / 10 (nothing recognised — NOT permission); there is no exit 0 in gate mode, deliberately, so a caller still reading `rc == 0 means go` breaks loudly. Gate class `missing` → `unrecognised`, every reply carries authorises:false, and a fifth class `mentioned` names the state the tool can actually observe. `--retroactive` loses its unattended path: the skill must read the comment set itself and obtain human confirmation that cannot be disabled. Classification now asks who wrote the comment, so a commenter can no longer move an issue between classes. Also: three more exit-0 parser paths, markup counted as content three layers deep, a quotation reaching `compliant`, the mention gate passing on zero iterations by three routes, untrusted prose reaching a shell command line, and #317 criterion (c) answered correctly for the first time in five attempts. Ten guards were mutation-proven vacuous and rebuilt.", + "version": "3.1.0", + "description": "v3.1.0: the actionability gate, round 2. Round 1 read `### Complexity` against a closed value domain that the repository's own 159 diagnoses refuted (66 real values wrongly refused) and shipped a three-signal gate no consumer called. Now the tier is the leading whole word (rationale, decoration and ` via` suffixes are legal), the whole line is scanned for a small deferral vocabulary (exit 5, reason `complexity-deferral-marker` — a parked state, not a defect), `### Blocking` is read by a shared fence-aware helper, and idd-list / idd-all / idd-implement / idd-plan actually call the verdict with all three signals in a paginated, `set -e`-safe shape pinned by a drift test. A frozen 159-issue corpus fixture makes 'zero migration' falsifiable: 149 routable, 9 deferral, 1 missing, 0 unparseable. idd-list gains a Parked group; the #84 blocked surface is preserved verbatim.", "author": { "name": "Che Cheng" }, diff --git a/openspec/changes/add-actionability-gate/design.md b/openspec/changes/add-actionability-gate/design.md index 53e3d4f..49875d6 100644 --- a/openspec/changes/add-actionability-gate/design.md +++ b/openspec/changes/add-actionability-gate/design.md @@ -42,7 +42,7 @@ > **本決策於 2026-08-15 重寫**（前版：「Complexity 回歸純封閉值域」）。前版把「tier 後接文字」等同於「延期修飾語」，被 `/idd-verify --pr 318` CRITICAL-2 以真實語料證偽。原文保留於 git history。 -`idd_parse_complexity` 依序：**(1)** 剝除前後 markdown 裝飾 → **(2)** 取 tier prefix（第一個 ` via ` 之前；tier 須為 `Simple` / `Plan` / `Spectra` / `SDD-warranted` 之一）→ **(3)** 對**整個值**掃延期語彙，命中則不路由。 +`idd_parse_complexity` 依序：**(1)** 剝除前後 markdown 裝飾 → **(2)** 值須**以** `Simple` / `Plan` / `Spectra` / `SDD-warranted` 之一**開頭**（最長匹配優先），該開頭即為 tier；其後的一切 —— 理由、括號、` via <來源>` —— 皆不參與 tier 判定→ **(3)** 對**整個值**掃延期語彙，命中則不路由。 tier 之後的其餘文字（同行理由、括號說明）**是合法的**，不影響 tier 抽取。 @@ -120,7 +120,7 @@ actionability gate 的輸入是三個訊號：`### Complexity` 非合法值、`p **migration 動作為零。** 既有 Diagnosis comment 一律不改寫，也不需要補任何 label 來讓 gate 給出正確答案。 -理由：新規則在 159 筆 corpus 上**158/158 全對** —— 149 筆正確路由、9 筆正確擋下。既有語料完全不需要調整就能被正確解讀。前版所謂「9 筆需 migration」是從封閉值域的錯誤前提推出的；真實需求是 **0 筆**。 +理由：新規則在 159 筆 corpus 上**159/159 全對** —— 149 筆正確路由、9 筆正確擋下（exit 5）、1 筆正確報缺區段（exit 4）、0 筆 unparseable；已凍結為回歸 fixture `corpus-complexity.json`。既有語料完全不需要調整就能被正確解讀。前版所謂「9 筆需 migration」是從封閉值域的錯誤前提推出的；真實需求是 **0 筆**。 append-only 紀律仍然成立且更容易守：既然不需要改寫任何歷史 comment，也就不存在違反 `rules/append-vs-modify.md` 的誘因。 diff --git a/openspec/changes/add-actionability-gate/proposal.md b/openspec/changes/add-actionability-gate/proposal.md index caf60e7..0e955f1 100644 --- a/openspec/changes/add-actionability-gate/proposal.md +++ b/openspec/changes/add-actionability-gate/proposal.md @@ -13,7 +13,7 @@ ## What Changes -- **`### Complexity` 的 tier 以 prefix 抽取，容許同行理由** —— 剝裝飾 → 取 ` via ` 之前的 tier prefix → tier 須為 `Simple` / `Plan` / `Spectra` / `SDD-warranted` 之一。tier 之後的理由、括號說明、provenance 後綴**皆為合法**，不影響抽取。 +- **`### Complexity` 的 tier 以 prefix 抽取，容許同行理由** —— 剝裝飾 → 值須**以** `Simple` / `Plan` / `Spectra` / `SDD-warranted` 之一**開頭**（最長匹配優先、整詞匹配），該開頭即為 tier。tier 之後的理由、括號說明、provenance 後綴**皆為合法**，不影響抽取。 - **延期以語彙偵測，並有獨立 reason** —— 對**整個值**掃 `when triggered` / `parking lot` / `deferred` / `暫緩`，命中則不路由，reason 為 `complexity-deferral-marker`（與 `complexity-unparseable` 分離 —— 前者是正常狀態、後者是資料錯誤，人的處置不同）。 - **`parking-lot` label 是 parked 的主要訊號**，延期語彙是次要安全網。語彙清單取高精度、容忍低召回。 - **新增 actionability gate** —— 三訊號 OR 判定（Complexity 不可路由、`parking-lot` label、`### Blocking` 非空），放行需三者皆不成立，**且四個 consumer 必須實際呼叫它**。 @@ -27,13 +27,13 @@ ### New Capabilities -- `actionability-gate`: 定義 `### Complexity` 的封閉值域、parked 狀態的歸屬（label 而非 comment）、三訊號 actionability gate 的判定規則，以及 unparseable 時的保守處置與強制 surface。 +- `actionability-gate`: 定義 `### Complexity` 的 tier 抽取規則（以 tier 開頭、其後理由合法）與延期語彙偵測、parked 狀態的歸屬（label 而非 comment）、三訊號 actionability gate 的判定規則，以及不可路由時的保守處置與強制 surface。 ### Modified Capabilities (none) -為何無 modified capability：硬閘與 Layer V 這兩份既有 spec 所產出的帶後綴 verdict（形如 tier 後接 " via " 再接來源）在新封閉值域下**仍為合法值**，其 requirement 不需修改；conflict-class 規範對 Complexity 欄位的正交性敘述同樣維持成立。 +為何無 modified capability：硬閘與 Layer V 這兩份既有 spec 所產出的帶後綴 verdict（形如 tier 後接 " via " 再接來源）在新抽取規則下**仍為合法值**（tier 開頭、` via ` 後綴不參與 tier 判定），其 requirement 不需修改；conflict-class 規範對 Complexity 欄位的正交性敘述同樣維持成立。 ## Impact diff --git a/openspec/changes/add-actionability-gate/specs/actionability-gate/spec.md b/openspec/changes/add-actionability-gate/specs/actionability-gate/spec.md index fef3004..5952aaa 100644 --- a/openspec/changes/add-actionability-gate/specs/actionability-gate/spec.md +++ b/openspec/changes/add-actionability-gate/specs/actionability-gate/spec.md @@ -2,7 +2,7 @@ ### Requirement: Complexity tier extraction tolerates trailing rationale -The system SHALL extract the routing tier from the `### Complexity` field by (1) stripping leading and trailing markdown decoration, (2) taking the tier prefix — the text preceding the first ` via ` separator — and (3) requiring that prefix to be exactly one of `Simple`, `Plan`, `Spectra`, or `SDD-warranted`. Any further text on the value line — same-line rationale, parenthetical explanation, or a ` via ` provenance suffix — SHALL NOT prevent tier extraction. Trailing rationale is the producer's normal writing style: in a corpus of 159 real diagnoses in this repository, 93.1% of values carry decoration, rationale, or a provenance suffix, and only 5.7% express deferral. +The system SHALL extract the routing tier from the `### Complexity` field by (1) stripping leading and trailing markdown decoration, (2) requiring the stripped value to **begin with** one of `Simple`, `Plan`, `Spectra`, or `SDD-warranted` (longest match first, so `SDD-warranted` is not read as a non-tier), and (3) taking that leading tier as the extracted value. Any further text on the value line — same-line rationale, parenthetical explanation, or a ` via ` provenance suffix — SHALL NOT prevent tier extraction. Trailing rationale is the producer's normal writing style: in a corpus of 159 real diagnoses in this repository, 71.7% of values are not a bare tier (23.3% decorated, 41.5% carry same-line rationale, 0.6% a provenance suffix) and only 5.7% express deferral; a closed domain would have wrongly refused 41.5% of them (66 of 159). #### Scenario: Bare tier is extracted diff --git a/openspec/changes/add-actionability-gate/tasks.md b/openspec/changes/add-actionability-gate/tasks.md index a8f6bbe..8e38359 100644 --- a/openspec/changes/add-actionability-gate/tasks.md +++ b/openspec/changes/add-actionability-gate/tasks.md @@ -36,28 +36,28 @@ > 前 5 組的 `[x]` 為第 1 輪成果，**不回退**：helper 骨架、契約文件、四個 consumer 的引用點與 fail-loud guard、producer 段落位置、`blocker:*` 收斂皆仍有效。本組修的是**判準本身**與第 1 輪漏掉的接線。 -- [ ] 6.1 重寫 `idd_parse_complexity` 的 tier 判定，落實決策「tier 以 prefix 抽取，延期以語彙偵測，parked 主訊號在 label」。行為契約：剝裝飾 → 取 ` via ` 前的 tier prefix → 對**整個值**掃延期語彙。exit 0 = 可路由；exit 3 = tier prefix 非四值之一；exit 4 = 缺區段；**exit 5 = tier 合法但含延期語彙**，stderr `deferral-marker: <原值>`。驗證：三個代表性正常值（`Spectra（opt-out → 直接 propose）` / `Plan（Layer P：…）` / `Simple — 單檔、2 個 1-token 補丁…`）回 exit 0 且 tier 正確；三個代表性延期值（`Simple when triggered` / `Spectra when triggered (parking lot)` / `**Spectra**(Layer 2 + Layer 3 if/when triggered)`）回 exit 5。檔案：`plugins/issue-driven-dev/scripts/lib/actionability.sh` 涵蓋需求：Complexity tier extraction tolerates trailing rationale、Deferral vocabulary withholds routing under its own reason。 +- [x] 6.1 重寫 `idd_parse_complexity` 的 tier 判定，落實決策「tier 以 prefix 抽取，延期以語彙偵測，parked 主訊號在 label」。行為契約：剝裝飾 → 取 ` via ` 前的 tier prefix → 對**整個值**掃延期語彙。exit 0 = 可路由；exit 3 = tier prefix 非四值之一；exit 4 = 缺區段；**exit 5 = tier 合法但含延期語彙**，stderr `deferral-marker: <原值>`。驗證：三個代表性正常值（`Spectra（opt-out → 直接 propose）` / `Plan（Layer P：…）` / `Simple — 單檔、2 個 1-token 補丁…`）回 exit 0 且 tier 正確；三個代表性延期值（`Simple when triggered` / `Spectra when triggered (parking lot)` / `**Spectra**(Layer 2 + Layer 3 if/when triggered)`）回 exit 5。檔案：`plugins/issue-driven-dev/scripts/lib/actionability.sh` 涵蓋需求：Complexity tier extraction tolerates trailing rationale、Deferral vocabulary withholds routing under its own reason。 -- [ ] 6.2 reason 值域擴為五值，新增 `complexity-deferral-marker`，落實決策「三種不可路由狀態各有獨立 reason 並一律 surface」。行為契約：`idd_actionability_verdict` 接受 `--complexity-exit 0|3|4|5`；exit 5 → reason `complexity-deferral-marker`。`idd_actionability_group` 對該 reason 回 `parked`。驗證：測試斷言 `Plan when triggered` 得 `complexity-deferral-marker` 而 `移入 discussion list` 得 `complexity-unparseable`，兩者 reason 不同。檔案：`plugins/issue-driven-dev/scripts/lib/actionability.sh` 涵蓋需求：Conservative verdict and mandatory surfacing on non-routable Complexity。 +- [x] 6.2 reason 值域擴為五值，新增 `complexity-deferral-marker`，落實決策「三種不可路由狀態各有獨立 reason 並一律 surface」。行為契約：`idd_actionability_verdict` 接受 `--complexity-exit 0|3|4|5`；exit 5 → reason `complexity-deferral-marker`。`idd_actionability_group` 對該 reason 回 `parked`。驗證：測試斷言 `Plan when triggered` 得 `complexity-deferral-marker` 而 `移入 discussion list` 得 `complexity-unparseable`，兩者 reason 不同。檔案：`plugins/issue-driven-dev/scripts/lib/actionability.sh` 涵蓋需求：Conservative verdict and mandatory surfacing on non-routable Complexity。 -- [ ] 6.3 [P] 修 verify #318 的 HIGH findings（helper 側）。行為契約：(a) option 缺 value 時回 exit 2 具名錯誤，不再因 `shift 2` 失敗而無限迴圈；(b) awk 追蹤 ``` 與 ~~~ code fence 並忽略其內 heading，且在同級或更高級 heading 結束；(c) ` via ` 後綴內的延期語彙同樣被偵測（不得成為逃生孔）。驗證：三類各補負向測試（value-less flag ×3、fenced-example body、`Simple via when triggered`）。檔案：`plugins/issue-driven-dev/scripts/lib/actionability.sh` +- [x] 6.3 [P] 修 verify #318 的 HIGH findings（helper 側）。行為契約：(a) option 缺 value 時回 exit 2 具名錯誤，不再因 `shift 2` 失敗而無限迴圈；(b) awk 追蹤 ``` 與 ~~~ code fence 並忽略其內 heading，且在同級或更高級 heading 結束；(c) ` via ` 後綴內的延期語彙同樣被偵測（不得成為逃生孔）。驗證：三類各補負向測試（value-less flag ×3、fenced-example body、`Simple via when triggered`）。檔案：`plugins/issue-driven-dev/scripts/lib/actionability.sh` -- [ ] 6.4 [P] 修 verify #318 的 HIGH finding（consumer 側 `set -e` 相容）。行為契約：contract 範例與四個 SKILL.md 的呼叫形狀改為條件位置捕捉（`if TIER=$(...); then CEXIT=0; else CEXIT=$?; fi`），使 exit 3/4/5 與 verdict 的 exit 1 不會在 `set -euo pipefail` 下終止 caller。驗證：新增 `set -euo pipefail` 的整合測試，斷言一筆不可路由的 issue 不會中斷整個 listing。檔案：`plugins/issue-driven-dev/references/actionability-gate.md`、四個 consumer SKILL.md +- [x] 6.4 [P] 修 verify #318 的 HIGH finding（consumer 側 `set -e` 相容）。行為契約：contract 範例與四個 SKILL.md 的呼叫形狀改為條件位置捕捉（`if TIER=$(...); then CEXIT=0; else CEXIT=$?; fi`），使 exit 3/4/5 與 verdict 的 exit 1 不會在 `set -euo pipefail` 下終止 caller。驗證：新增 `set -euo pipefail` 的整合測試，斷言一筆不可路由的 issue 不會中斷整個 listing。檔案：`plugins/issue-driven-dev/references/actionability-gate.md`、四個 consumer SKILL.md ## 7. 接上三訊號 gate（verify CRITICAL-1） -- [ ] 7.1 四個 consumer 實際呼叫 `idd_actionability_verdict`。行為契約：每個 consumer 讀該 issue 的 labels 與 body 的 `### Blocking` 區塊，連同 `idd_parse_complexity` 的 exit code 一併送進 verdict，並依其 exit 0/1/2 分支（2 = API 誤用，不得與 not-actionable 混同）。**只換 parser 不呼叫 verdict 等於沒修** —— 第 1 輪即是如此：gate 完整實作、66 測試全綠、零 consumer 呼叫。**另（2026-09-07 rebase 後補記）**：四個 consumer 抓 latest Diagnosis 時**不得**用 `gh issue view --json comments` —— 它把巢狀 connection 解成 `comments(first: 100)`，硬截成**最舊** 100 則；超過 100 則 comment 的 issue，最新 Diagnosis 正是被丟掉的那則，helper 會誤回 exit 4 `complexity-missing`。改用 `gh api repos/:o/:r/issues/N/comments --paginate --jq '[.[]|{body}]' | jq -s add`（main `idd-list` Step 2 於 2026-08-15 post-merge audit 已規定同款修法，且明寫「不得只在其中一個 consumer 修」；`scripts/check-closed-without-summary.sh` 已有現成實作可抄）。驗證：測試對四個引用點各驗一次「verdict 被呼叫且 labels/Blocking 有被讀取」，而非只驗 helper 自身行為；另 grep 四份 SKILL.md 確認抓 comments 的路徑皆為 `--paginate`，無殘留 `--json comments`。檔案：`plugins/issue-driven-dev/skills/idd-list/SKILL.md`、`skills/idd-all/SKILL.md`、`skills/idd-implement/SKILL.md`、`skills/idd-plan/SKILL.md` 涵蓋需求：Actionability gate evaluates three signals disjunctively、Single shared implementation of parsing and verdict。 +- [x] 7.1 四個 consumer 實際呼叫 `idd_actionability_verdict`。行為契約：每個 consumer 讀該 issue 的 labels 與 body 的 `### Blocking` 區塊，連同 `idd_parse_complexity` 的 exit code 一併送進 verdict，並依其 exit 0/1/2 分支（2 = API 誤用，不得與 not-actionable 混同）。**只換 parser 不呼叫 verdict 等於沒修** —— 第 1 輪即是如此：gate 完整實作、66 測試全綠、零 consumer 呼叫。**另（2026-09-07 rebase 後補記）**：四個 consumer 抓 latest Diagnosis 時**不得**用 `gh issue view --json comments` —— 它把巢狀 connection 解成 `comments(first: 100)`，硬截成**最舊** 100 則；超過 100 則 comment 的 issue，最新 Diagnosis 正是被丟掉的那則，helper 會誤回 exit 4 `complexity-missing`。改用 `gh api repos/:o/:r/issues/N/comments --paginate --jq '[.[]|{body}]' | jq -s add`（main `idd-list` Step 2 於 2026-08-15 post-merge audit 已規定同款修法，且明寫「不得只在其中一個 consumer 修」；`scripts/check-closed-without-summary.sh` 已有現成實作可抄）。驗證：測試對四個引用點各驗一次「verdict 被呼叫且 labels/Blocking 有被讀取」，而非只驗 helper 自身行為；另 grep 四份 SKILL.md 確認抓 comments 的路徑皆為 `--paginate`，無殘留 `--json comments`。檔案：`plugins/issue-driven-dev/skills/idd-list/SKILL.md`、`skills/idd-all/SKILL.md`、`skills/idd-implement/SKILL.md`、`skills/idd-plan/SKILL.md` 涵蓋需求：Actionability gate evaluates three signals disjunctively、Single shared implementation of parsing and verdict。 -- [ ] 7.2 `idd-list` 顯示層依 reason 分兩組。行為契約：reason 僅 `blocking-nonempty` → 維持 #84 既有 Blocked 分組；其餘（含 `complexity-deferral-marker`）→ Parked 分組並顯示原值。驗證：測試斷言 #84 的分組標題、全 blocked banner 文案、footer 計數與變更前逐字相同。檔案：`plugins/issue-driven-dev/skills/idd-list/SKILL.md` 涵蓋需求：Blocked-state output is preserved as a distinct display group。 +- [x] 7.2 `idd-list` 顯示層依 reason 分兩組。行為契約：reason 僅 `blocking-nonempty` → 維持 #84 既有 Blocked 分組；其餘（含 `complexity-deferral-marker`）→ Parked 分組並顯示原值。驗證：測試斷言 #84 的分組標題、全 blocked banner 文案、footer 計數與變更前逐字相同。檔案：`plugins/issue-driven-dev/skills/idd-list/SKILL.md` 涵蓋需求：Blocked-state output is preserved as a distinct display group。 ## 8. 測試重建 -- [ ] 8.1 fixture 重建為 corpus 抽樣。行為契約：四種真實形狀各至少 3 筆（bare tier / tier + 同行理由 / markdown 裝飾 / 延期語彙），逐字取自真實 diagnosis，不得只收錄為驗證假設而挑的樣本。驗證：內容審查確認四類數量達標且每筆標註來源 issue 號。檔案：`plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/parked-routing.json` 涵蓋需求：Existing diagnoses require no migration。落實決策「零 migration —— 新規則對既有全部語料都給正確結果」——fixture 的存在意義正是把這個宣稱變成可回歸的斷言，而非一次性檢查。 +- [x] 8.1 fixture 重建為 corpus 抽樣。行為契約：四種真實形狀各至少 3 筆（bare tier / tier + 同行理由 / markdown 裝飾 / 延期語彙），逐字取自真實 diagnosis，不得只收錄為驗證假設而挑的樣本。驗證：內容審查確認四類數量達標且每筆標註來源 issue 號。檔案：`plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/parked-routing.json` 涵蓋需求：Existing diagnoses require no migration。落實決策「零 migration —— 新規則對既有全部語料都給正確結果」——fixture 的存在意義正是把這個宣稱變成可回歸的斷言，而非一次性檢查。 -- [ ] 8.2 新增全 corpus 回歸測試。行為契約：對 159 筆真實 diagnosis 跑 `idd_parse_complexity`，斷言 149 筆 exit 0 且 tier 正確、9 筆 exit 5、1 筆 exit 4、**0 筆 exit 3**。corpus 快照存為 fixture，不查詢 live GitHub。驗證：執行 plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh 該項通過。檔案：`plugins/issue-driven-dev/scripts/tests/actionability-gate/` +- [x] 8.2 新增全 corpus 回歸測試。行為契約：對 159 筆真實 diagnosis 跑 `idd_parse_complexity`，斷言 149 筆 exit 0 且 tier 正確、9 筆 exit 5、1 筆 exit 4、**0 筆 exit 3**。corpus 快照存為 fixture，不查詢 live GitHub。驗證：執行 plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh 該項通過。檔案：`plugins/issue-driven-dev/scripts/tests/actionability-gate/` ## 9. 文件同步（第 2 輪） -- [ ] 9.1 `references/actionability-gate.md` 依新規則重寫。行為契約：封閉值域段改為「tier prefix 抽取 + 延期語彙」；reason 值域 4 → 5；新增「風險姿態：label 為主、語彙為輔」段並說明漏抓/誤抓的不對稱處置。驗證：內容審查確認不再出現「合法值域為封閉四值」的宣稱，且 corpus 數據（159 筆 / 158-158）有明文引用。檔案：`plugins/issue-driven-dev/references/actionability-gate.md` +- [x] 9.1 `references/actionability-gate.md` 依新規則重寫。行為契約：封閉值域段改為「tier prefix 抽取 + 延期語彙」；reason 值域 4 → 5；新增「風險姿態：label 為主、語彙為輔」段並說明漏抓/誤抓的不對稱處置。驗證：內容審查確認不再出現「合法值域為封閉四值」的宣稱，且 corpus 數據（159 筆 / 158-158）有明文引用。檔案：`plugins/issue-driven-dev/references/actionability-gate.md` -- [ ] 9.2 [P] `idd-diagnose` producer 宣告改寫。行為契約：移除封閉值域宣告，改為「tier 寫清楚；延期意圖貼 `parking-lot` label，不要寫進 `### Complexity`」，並保留「producer 不自動貼 label」一條。驗證：內容審查確認不再宣告封閉值域，且 159 筆語料的常態寫法（tier + 同行理由）未被規定為違規。檔案：`plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md` +- [x] 9.2 [P] `idd-diagnose` producer 宣告改寫。行為契約：移除封閉值域宣告，改為「tier 寫清楚；延期意圖貼 `parking-lot` label，不要寫進 `### Complexity`」，並保留「producer 不自動貼 label」一條。驗證：內容審查確認不再宣告封閉值域，且 159 筆語料的常態寫法（tier + 同行理由）未被規定為違規。檔案：`plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md` diff --git a/plugins/issue-driven-dev/.claude-plugin/plugin.json b/plugins/issue-driven-dev/.claude-plugin/plugin.json index 3d36f06..a97213e 100644 --- a/plugins/issue-driven-dev/.claude-plugin/plugin.json +++ b/plugins/issue-driven-dev/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "issue-driven-dev", "description": "v3.0.0 (BREAKING): the closing-summary helper may VETO and may never PERMIT. After twelve verify rounds failing in one direction — a real summary the recogniser could not follow classified `missing`, and `missing` being the sole authorisation for `/idd-close --retroactive` to post a duplicate — the power was split along the direction that is sound. \"A marker IS here\" is an observation; \"a marker is NOT here\" is an inference from a failure to recognise, and no matcher over source bytes can answer a question about rendered output in the negative. Gate exit codes are now 1 (recognised) / 2 (undeterminable) / 10 (nothing recognised — NOT permission); there is no exit 0 in gate mode, deliberately, so a caller still reading `rc == 0 means go` breaks loudly. Gate class `missing` → `unrecognised`, every reply carries authorises:false, and a fifth class `mentioned` names the state the tool can actually observe. `--retroactive` loses its unattended path: the skill must read the comment set itself and obtain human confirmation that cannot be disabled. Classification now asks who wrote the comment, so a commenter can no longer move an issue between classes. Also: three more exit-0 parser paths, markup counted as content three layers deep, a quotation reaching `compliant`, the mention gate passing on zero iterations by three routes, untrusted prose reaching a shell command line, and #317 criterion (c) answered correctly for the first time in five attempts. Ten guards were mutation-proven vacuous and rebuilt.", - "version": "3.0.0", + "version": "3.1.0", "author": { "name": "Che Cheng" }, diff --git a/plugins/issue-driven-dev/CHANGELOG.md b/plugins/issue-driven-dev/CHANGELOG.md index 4a9124e..b08e2a7 100644 --- a/plugins/issue-driven-dev/CHANGELOG.md +++ b/plugins/issue-driven-dev/CHANGELOG.md @@ -5,6 +5,95 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [3.1.0] - 2026-09-07 + +Round 2 of the actionability gate (#298 → #316, PR #318). Round 1 shipped a shared +`### Complexity` parser with a **closed value domain** — exactly `Simple` / `Plan` / +`Spectra` / `SDD-warranted`, optionally ` via ` — plus a three-signal gate that +**no consumer called**. `/idd-verify --pr 318` returned FAIL with two CRITICALs: the gate +was unwired (CRITICAL-1), and the closed domain, checked against the repository's own +diagnosis corpus, would have wrongly refused **66 of 159** real values (CRITICAL-2) — a +41.5 % rejection rate, worse than the 29 % misroute rate of the truncating regex it +replaced. The producer's normal style is `**Plan** (decision-heavy at Finding 1)` and +`Spectra（opt-out → 直接 propose）`; only 28 % of values are a bare tier. + +### Changed — `### Complexity` is read by prefix, deferral by vocabulary + +- `idd_parse_complexity` now strips markdown decoration, requires the value to **begin + with** a tier as a whole word (longest match first, so `Simpler` is not `Simple` and + `SDD-warranted` is not a non-tier), and takes that word as the tier. Same-line rationale, + parentheticals, em-dash notes and ` via ` suffixes are legal and ignored. +- The **entire first line** is then scanned for deferral vocabulary — `when triggered`, + `parking lot`, `deferred`, `暫緩` (case-insensitive, hyphen/underscore tolerant). A hit + is **exit 5** with stderr `deferral-marker: `; nothing is written to stdout, so the + well-formed tier prefix cannot be routed on. `Simple via when triggered` — the suffix as + an escape hatch (verify H3) — is caught. Only the first line is scanned: scanning the + section would add two false positives on the corpus (#154 "remove *deferred* caveat", + #137 "reuse `deferred` enum") and catch nothing. +- The reason vocabulary grows from four to **five**: `complexity-deferral-marker` is + distinct from `complexity-unparseable` because the human response differs — a deferral + is a legitimate state with nothing to repair; an unparseable value is a data defect. + `idd_actionability_verdict` accepts `--complexity-exit 5`; the display group is *parked*. +- **Risk posture is stated, not implied**: the `parking-lot` label is the primary parked + signal; the vocabulary is a high-precision, low-recall net kept deliberately small. A + miss falls back to pre-#298 behaviour (label is the backstop); a false positive is a hard + stop on real work. Adding a term requires corpus evidence of zero false positives. + The vocabulary is explicitly **not** a closed enumeration — round 1 showed what happens + when a heuristic is dressed as a domain. + +### Added — the gate is wired, and the third signal has a reader + +- `idd-list`, `idd-all`, `idd-implement`, `idd-plan` now **actually call** + `idd_actionability_verdict` with all three signals, in one canonical shape documented in + `references/actionability-gate.md`: paginated fetch of the latest Diagnosis comment, + labels via `jq`, `### Blocking` via the helper, `set -euo pipefail`-safe conditional + capture, and a verdict branch in which exit 2 (API misuse) is a FATAL in the consumer — + never "not actionable". A drift-guard test greps all four SKILL.md files for that shape. +- New `idd_blocking_section ` — first non-blank line of `### Blocking`, empty + when the section is absent or holds idd-update's `- (none)` placeholder (also `none`, + `n/a`, `-`, decorated). The fourth private awk that would otherwise have appeared. +- Shared, fence-aware section extractor: ``` and ~~~ fences are not sections (a template + example quoted in prose no longer yields a value — verify H4); a section ends at the + next same-or-higher heading; a deeper `####` line is never taken as the value. +- `idd-list` Step 5 gains a **Parked (not routable now)** group. The #84 blocked-state + group — heading `Blocked (waiting on external):`, the all-blocked banner, the + `X actionable, Y blocked` footer — is preserved verbatim and pinned by test; `, Z parked` + is appended only when Z > 0. +- **Full-corpus regression**: `fixtures/corpus-complexity.json` freezes the first + `### Complexity` line of all 159 diagnosed issues (snapshot 2026-08-15) with reviewed + expectations — 149 routable (Plan 69 / Simple 41 / Spectra 39), 9 deferral, 1 missing + (#273), 0 unparseable. "Zero migration" is now a falsifiable assertion, not a claim. + +### Fixed — verify #318 HIGH findings + +- `idd_actionability_verdict` with a value-less flag (`--parking-label` as the last arg) + spun forever: `shift 2` on one remaining argument fails without shifting. Now a named + exit-2 error; the test bounds every such call with a bash-only timeout so a regression + reads as a failure, not a hung suite. +- Consumer snippets fetched the latest Diagnosis with `gh issue view --json comments`, + which returns only the **oldest 100** — on a long issue the latest diagnosis is exactly + the one dropped (#295's family). All four now paginate through the REST endpoint. +- Consumer snippets used bare `TIER=$(idd_parse_complexity …)`, which under `set -e` + aborts the whole listing on the first non-routable issue — the contract's own "SHALL + NOT abort the enclosing listing" broken by its own example. Conditional capture + throughout; an integration test runs the shape under `bash -euo pipefail`. +- `idd-diagnose` no longer declares a closed value domain for the field; it now says + "write the tier clearly, rationale welcome; deferral goes on the label". + +### Honest residue + +- **#128 is a designed miss.** Its deferral ("blocked-by #86") lives only in Strategy + prose — no marker, no label, empty Blocking. The gate routes it as `Plan`, and the + incident fixture pins it as *actionable* rather than pretending a marker exists. + Withholding it is a human's label to apply. +- The fixture's 2026-08-10 snapshot rows were corrected to the **verbatim** Diagnosis + comment values (`**Spectra**`, `**Spectra when triggered**(Layer 2: …)`); round 1 had + recorded the issue-body mirror forms, and had itself been misled by its own truncating + regex into calling #136's comment "bare `Spectra`". The body-mirror form is kept as a + separately-labelled row. +- `plan-routing-consistency` fails on a developer checkout with gitignored + `.spectra/snapshots/` present and passes on a clean worktree — #335, not touched here. + ## [3.0.0] - 2026-09-01 23 commits since 2.112.0, across four `/idd-verify` ensembles. **The major bump is for one diff --git a/plugins/issue-driven-dev/references/actionability-gate.md b/plugins/issue-driven-dev/references/actionability-gate.md index bd9e0fd..f476f22 100644 --- a/plugins/issue-driven-dev/references/actionability-gate.md +++ b/plugins/issue-driven-dev/references/actionability-gate.md @@ -1,8 +1,8 @@ # Actionability Gate -> The contract that answers **「這個 issue 現在可不可以動？」** — the closed value domain of the `### Complexity` Diagnosis field, where deferral state lives, and the three-signal gate that `idd-list` / `idd-all` / `idd-implement` / `idd-plan` all consume. This file is the single source of truth; the four skills cite it and MUST NOT restate the rules in their own words. +> The contract that answers **「這個 issue 現在可不可以動？」** — how the routing tier is extracted from the `### Complexity` Diagnosis field, how deferral is detected, where parked state lives, and the three-signal gate that `idd-list` / `idd-all` / `idd-implement` / `idd-plan` all consume. This file is the single source of truth; the four skills cite it and MUST NOT restate the rules in their own words. > -> **Source**: `add-actionability-gate` Spectra change (capability `actionability-gate`). Origin: issue-driven-development#298, surfaced from real dogfooding (2026-08-10 backlog routing). +> **Source**: `add-actionability-gate` Spectra change (capability `actionability-gate`). Origin: issue-driven-development#298 → #316, surfaced from real dogfooding (2026-08-10 backlog routing). **Round 2** (2026-08-15): `/idd-verify --pr 318` falsified round 1's closed value domain against the real diagnosis corpus; the extraction rule below is the corrected one, validated on all 159 diagnoses in this repository. ## The incident this exists to prevent @@ -10,40 +10,90 @@ On 2026-08-10 a real 22-issue backlog was routed by `/idd-list`. Of the 11 diagn The failure was **silent**. The table was syntactically correct, well-formatted, and carried no warning. -## Root cause — mutable state in an immutable artifact +## Root cause, in two layers -`### Complexity` lives in a Diagnosis comment, and Diagnosis comments are **append-only** (see [`rules/append-vs-modify.md`](../rules/append-vs-modify.md)). But "is this issue parked?" is **mutable** — a trigger firing should un-park it. Writing deferral qualifiers (`Simple when triggered`, `Spectra when triggered (parking lot)`) into a frozen field created a value that could never be corrected in place. +### 1. Mutable state in an immutable artifact -Two consequences followed: +`### Complexity` lives in a Diagnosis comment, and Diagnosis comments are **append-only** (see [`rules/append-vs-modify.md`](../rules/append-vs-modify.md)). But "is this issue parked?" is **mutable** — a trigger firing should un-park it. Writing deferral qualifiers (`Simple when triggered`, `**Spectra when triggered**(Layer 2: …)`) into a frozen field created a value that could never be corrected in place, and every consumer's parser assumed the field carried one kind of information. Three consumers each invented an incompatible narrowing: -1. **The field carried two kinds of information** (tier + deferral) while every consumer's parser assumed one. Three consumers each invented an incompatible narrowing, and they disagreed: +| Consumer | private narrowing | result on `Simple when triggered` | +|---|---|---| +| `idd-list` | `([A-Za-z-]+)` | silently truncated to `Simple` → routed a parked issue to `/idd-implement` | +| `idd-all` | `(.+?)` + via-split | non-tier string; matched no dispatch row **and** was not `UNKNOWN` | +| `idd-implement` | same | same | + +`idd-all`'s `UNKNOWN → abort` safety net structurally could not catch this: it fires only when the regex fails entirely, never when it matches an out-of-domain value. - | Consumer | private narrowing | result on `Simple when triggered` | - |---|---|---| - | `idd-list` | `([A-Za-z-]+)` | silently truncated to `Simple` → routed a parked issue to `/idd-implement` | - | `idd-all` | `(.+?)` + via-split | non-tier string; matched no dispatch row **and** was not `UNKNOWN` | - | `idd-implement` | same | same | +IDD already knew the right shape: `### Blocking` is mutable, so it lives in the issue **body** and is maintained by `idd-update`. This contract applies the same reasoning to deferral. - `idd-all`'s `UNKNOWN → abort` safety net structurally could not catch this: it fires only when the regex fails entirely, never when it matches an out-of-domain value. +> **Correction to the round-1 narrative.** Round 1 claimed #136's Diagnosis comment read bare `Spectra` while its body read `Spectra when triggered (parking lot)`. The "bare `Spectra`" was the truncating regex talking: the comment actually reads `**Spectra**(Layer 2 + Layer 3 if/when triggered):…` — the deferral was hiding inside the parenthetical, exactly where a suffix-only scan would miss it. The two-signals-drift argument still stands (#37, #131, #200), but #136 is evidence for scanning the *whole* value, not for state drift. -2. **The frozen state drifted elsewhere.** #136's Diagnosis comment read bare `Spectra` while its body read `Spectra when triggered (parking lot)` — state that cannot be corrected in place migrates to wherever it can be edited. +### 2. The round-1 fix over-corrected -IDD already knew the right shape: `### Blocking` is mutable, so it lives in the issue **body** and is maintained by `idd-update`. This contract applies the same reasoning to deferral. +Round 1 declared a **closed value domain**: the value had to be exactly one of the four tiers, optionally followed by ` via `. That rejected the producer's normal writing style. On the real corpus of **159 diagnoses** in this repository: + +| Shape (mutually exclusive, first line of the value) | Count | Share | +|---|---|---| +| bare tier (`Plan`) | 45 | 28.3 % | +| decorated bare tier (`**Plan**`) | 37 | 23.3 % | +| decorated tier + same-line rationale (`**Spectra** — Layer 2（…）`) | 41 | 25.8 % | +| plain tier + same-line rationale (`Spectra（opt-out → 直接 propose）`) | 25 | 15.7 % | +| tier + ` via ` (`Plan via hard-gate`) | 1 | 0.6 % | +| deferral vocabulary present | 9 | 5.7 % | +| no `### Complexity` section | 1 | 0.6 % | + +71.7 % of values are not a bare tier. Round 1 stripped decoration before matching, so it would still have refused every rationale-bearing value: **66 of 159 (41.5 %)** wrongly withheld — worse than the 29 % misroute rate of the truncating regex it replaced (37 decorated values unmatched + 9 deferral values passed). Both figures are reproducible from the frozen fixture. That was verify finding CRITICAL-2 on PR #318, and it is why round 2 exists. The counts above are reproducible from the frozen fixture, not from memory. -## Closed value domain — `### Complexity` +## The extraction rule — prefix tier, whole-line deferral scan -**The legal values are exactly these four. This is a CLOSED enumeration — do NOT extend it by analogy, and do NOT infer a fifth value from resemblance to an existing one:** +`idd_parse_complexity` applies these steps, in this order: -1. `Simple` -2. `Plan` -3. `Spectra` -4. `SDD-warranted` — legacy alias of `Spectra`, retained for backward compatibility +1. **Take the first non-blank line** under the `### Complexity` heading. The heading is anchored at line start; a ``` or ~~~ fence is not a section; the section ends at the next heading of the same or higher level; a deeper `####` line is skipped. +2. **Strip leading and trailing markdown decoration** (`**`, `` ` ``, `_`). Decoration is presentation, not value. +3. **The stripped value must begin with one of `Simple`, `Plan`, `Spectra`, `SDD-warranted`** as a whole word — longest match first, so `SDD-warranted` is tried before anything that could be its prefix, and a word boundary keeps `Simpler` from reading as `Simple`. That leading word **is the tier**. Everything after it — same-line rationale, a parenthetical, an em-dash note, a ` via ` provenance suffix (`Plan via Layer V`, `Spectra via hard-gate (sdd_bias)`) — is **legal and ignored** for tier extraction. +4. **Scan the entire first line** — not only the text after the tier — for deferral vocabulary: `when triggered`, `parking lot`, `deferred`, `暫緩` (case-insensitive; space, hyphen and underscore tolerant, so `Parking-Lot` and `if/when triggered` both count). A hit withholds the issue under its own reason, **even though the tier prefix is valid**. -A value MAY carry the provenance suffix ` via ` (established v2.50). The canonical tier is the text preceding the **first** ` via ` separator. Both existing producers of suffixed values remain legal: `Plan via Layer V` (Layer V escalation) and `Spectra via hard-gate (sdd_bias)` (hard-gate exit). +| Outcome | exit | stdout | stderr | +|---|---|---|---| +| routable | `0` | the leading tier | — | +| value does not begin with a tier (`移入 discussion list`) | `3` | — | `unparseable-complexity: ` | +| no `### Complexity` section | `4` | — | `missing-complexity` | +| tier valid, deferral vocabulary present (`Plan when triggered`) | `5` | — | `deferral-marker: ` | + +Two ordering consequences are deliberate: + +- **Tier check precedes the deferral scan.** `移入 discussion list（暫緩）` is exit 3, not 5 — a value with no tier is a data defect first, whatever else it says. +- **Only the first line is scanned.** Scanning the whole section would add two false positives on the corpus (#154 "remove *deferred* caveat", #137 "reuse existing `deferred` enum") and catch nothing new. The producer's deferral intent, when written into this field at all, sits on the value line. + +On every non-zero path **nothing is written to stdout**. A consumer that captured a tier there could route on it — which is the incident. -**Deferral qualifiers SHALL NOT be written into this field.** `when triggered`, `(parking lot)`, and any prose describing why the issue is on hold belong to the `parking-lot` label, not here. A tier field that carries deferral state is the defect this contract closes. +### Corpus validation — the regression that keeps this honest + +The rule was derived from and validated against every diagnosed issue in this repository (snapshot 2026-08-15, 225 issues fetched, 159 with a `## Diagnosis` comment), and that validation is a **frozen regression test**, not a one-off check: `scripts/tests/actionability-gate/fixtures/corpus-complexity.json`, asserted by `scripts/tests/actionability-gate/test.sh`. + +| exit | count | issues | +|---|---|---| +| `0` routable | 149 | Plan 69 · Simple 41 · Spectra 39 | +| `5` deferral | 9 | #131 #136 #140 #143 #144 #145 #146 #157 #200 | +| `4` missing | 1 | #273 | +| `3` unparseable | 0 | — | -### Where deferral state lives instead +Every one of the 159 routes as hand-reviewed; **0 false positives**. No Diagnosis comment was rewritten and no label was backfilled to get there — **zero migration** is a claim about this corpus, and the test is what makes it falsifiable. + +## Risk posture — the label is primary, the vocabulary is a net + +Deferral vocabulary is a **high-precision, low-recall heuristic**. It is NOT a closed enumeration and MUST NOT be "completed" by analogy — but it must not grow casually either. The two failure directions are asymmetric: + +| Failure | Consequence | Posture | +|---|---|---| +| **miss** (deferral written in words the scan does not know) | the issue looks actionable — the pre-#298 behaviour, no worse | acceptable; the `parking-lot` label is the human backstop | +| **false positive** (routable issue withheld) | a hard stop on real work, with a reason that reads as authoritative | unacceptable; keep the vocabulary conservative | + +So the rule for adding a term: **corpus evidence of zero false positives**, recorded in the regression fixture. Resemblance to an existing term is not evidence. + +**A documented miss, kept honest.** #128's Diagnosis reads `Plan（觸發表）+ 未決 UX 軸 → **移入 discussion list**`; its deferral ("blocked-by #86") lives only in Strategy prose. Under this rule it routes as `Plan`. That is the designed outcome — the gate does not parse prose — and the fixture pins #128 as *actionable* rather than pretending a marker exists. If it should be withheld, a human applies the label. + +## Where deferral state lives | State | Home | Mutable? | Maintained by | |---|---|---|---| @@ -51,30 +101,35 @@ A value MAY carry the provenance suffix ` via ` (established v2.50). The | Deferral / parked | `parking-lot` label | **yes** | **a human** — see below | | External blocker | `### Blocking` in the issue body | yes | `idd-update` | -**`idd-diagnose` SHALL NOT apply, remove, or derive the `parking-lot` label.** The label is a human ruling, and it is settable *after* the diagnosis was written. Empirically the two signals disagree: of 11 diagnosed issues sampled on 2026-08-10, only 5 had the qualifier and the label in agreement. #37 was bare `Spectra` with the label applied later by a human; #131 and #200 had the qualifier with no label. They are not two spellings of one fact — they are two facts, and deriving one from the other would delete the human's ability to park an issue whose tier is perfectly clear. +**`idd-diagnose` SHALL NOT apply, remove, or derive the `parking-lot` label.** The label is a human ruling, and it is settable *after* the diagnosis was written. Empirically the two signals disagree: of 11 diagnosed issues sampled on 2026-08-10, only 5 had the qualifier and the label in agreement. #37 was `**Spectra**` with the label applied later by a human; #131 and #200 had the qualifier with no label. They are not two spellings of one fact — they are two facts, and deriving one from the other would delete the human's ability to park an issue whose tier is perfectly clear. + +**The producer's rule is therefore simple**: write the tier clearly, rationale welcome; if the issue is on hold, say so with the label, not in this field. The vocabulary scan exists for the 159-issue past, not as an invitation. ## The three-signal gate An issue is **actionable** only when all three signals are clear. Any one of them withholds it. ``` - ### Complexity outside the closed domain, or absent ─┐ - parking-lot label present ─┼─→ not actionable - ### Blocking section non-empty ─┘ + ### Complexity non-routable (exit 3 / 4 / 5) ─┐ + parking-lot label present ─┼─→ not actionable + ### Blocking section non-empty ─┘ actionable ⟺ none of the three holds ``` -### Reason vocabulary — also a CLOSED enumeration +### Reason vocabulary — a CLOSED enumeration -**Exactly four values. Do NOT add a fifth by analogy:** +**Exactly five values. Do NOT add a sixth by analogy:** -| Reason | Fires when | -|---|---| -| `complexity-unparseable` | `### Complexity` section present, value outside the closed domain | -| `complexity-missing` | no `### Complexity` section at all | -| `parking-lot-label` | the issue carries the `parking-lot` label | -| `blocking-nonempty` | the `### Blocking` section of the body is non-empty | +| Reason | Fires when | What it asks of a human | +|---|---|---| +| `complexity-unparseable` | section present, value does not begin with a tier | fix the Diagnosis — this is a data defect | +| `complexity-missing` | no `### Complexity` section | run `/idd-diagnose` — the diagnosis never judged complexity | +| `complexity-deferral-marker` | tier valid, deferral vocabulary present | nothing to repair — this is a legitimate parked state; apply the label if it is not already there | +| `parking-lot-label` | the issue carries the `parking-lot` label | nothing — a human parked it | +| `blocking-nonempty` | the `### Blocking` section of the body is non-empty | wait, or clear the blocker via `idd-update` | + +The three complexity reasons are kept distinct **because the human response differs**. Collapsing them into one would tell the operator to "fix" a value that is not broken. ### What is deliberately NOT a signal @@ -82,15 +137,15 @@ An issue is **actionable** only when all three signals are clear. Any one of the > ⚠ Anyone editing `- [~]` handling must check `idd-close` first. Treating it as unused because routing ignores it will break the close gate. -## Default on absent or unparseable — conservative, and always surfaced +## Default on non-routable Complexity — conservative, and always surfaced -A consumer parsing a `### Complexity` value outside the closed domain SHALL report the issue as **not actionable** and SHALL **surface the original unmodified value** to the operator. A missing section gets the same verdict under a distinct reason. +A consumer whose `### Complexity` value is non-routable **for any reason** SHALL report the issue as **not actionable** and SHALL **surface the original unmodified line** to the operator. Three things are forbidden: -- **SHALL NOT** silently truncate a non-domain value to its tier prefix. That truncation is the 2026-08-10 incident. -- **SHALL NOT** downgrade a non-domain value to any tier, including `Plan`. `Plan` is still actionable; downgrading routes a parked issue into `/idd-plan`. -- **SHALL NOT** abort the enclosing listing operation. One bad value must not suppress the other issues — a surfacing tool that dies on one malformed row is worse than one that flags it. +- **SHALL NOT** silently truncate a non-routable value to its tier prefix. That truncation is the 2026-08-10 incident — and on exit 5 the prefix is *right there*, well-formed, which is exactly why the helper refuses to print it. +- **SHALL NOT** downgrade a non-routable value to any tier, including `Plan`. `Plan` is still actionable; downgrading routes a parked issue into `/idd-plan`. +- **SHALL NOT** abort the enclosing listing operation. One bad value must not suppress the other issues — a surfacing tool that dies on one malformed row is worse than one that flags it. (The `set -e` call shape below is what makes this hold in practice.) This mirrors the `### Conflict Class` contract in [`parallel-orchestration.md`](parallel-orchestration.md), which defaults an absent or unparseable value to `D_diagnose_first` and requires the fallback be printed. The two fields are orthogonal (one classifies physical resources touched, the other routing tier) but share one discipline: **conservative default plus mandatory surfacing, never silent.** @@ -101,31 +156,65 @@ The gate emits a verdict together with its reason list. The display layer groups | Reasons | Group | |---|---| | `blocking-nonempty` **alone** | the existing blocked-state group (#84) — heading, all-blocked banner text, and footer counts unchanged | -| anything else, including any mix | the parked group | +| anything else, including any mix | the parked group — each row shows the raw `### Complexity` line (from the helper's stderr) or the label, so the operator sees *why* | Unifying the *judgment* does not mean unifying the *presentation*. #84's blocked-state surface is user-facing behavior people rely on; merging it into one undifferentiated bucket would be a regression dressed as a simplification. ## Consumer contract -The four routing consumers SHALL invoke the shared implementation at `scripts/lib/actionability.sh` and MUST NOT embed a private parse: +The four routing consumers SHALL invoke the shared implementation at `scripts/lib/actionability.sh` and MUST NOT embed a private parse — of `### Complexity` **or** of `### Blocking`. The canonical call shape, in full, is: ```bash -. "$CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh" - -tier=$(idd_parse_complexity "$diagnosis_body"); cexit=$? -verdict=$(idd_actionability_verdict \ - --complexity-exit "$cexit" \ - --parking-label "$has_parking_lot_label" \ - --blocking-section "$blocking_section_nonempty") +# 0. Missing helper → fail loud, name the path. Never fall back to a private regex. +. "$CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh" || { + echo "FATAL: missing $CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh — 不得改用私有 regex" >&2 + exit 1 +} + +# 1. Latest Diagnosis comment — PAGINATE. `gh issue view --json comments` returns +# only the OLDEST 100 comments, so on a long issue the latest diagnosis is +# exactly the one that gets dropped. (`--paginate --jq` emits one array per +# page; `jq -s add` folds them.) +LATEST_DIAGNOSIS=$(gh api "repos/$GITHUB_REPO/issues/$N/comments" --paginate --jq '[.[] | {body}]' \ + | jq -s 'add // []' \ + | python3 -c ' +import json, sys, re +cs = json.load(sys.stdin) +ds = [c for c in cs if re.search(r"(?m)^## Diagnosis", c["body"])] # line-anchored: quoted/inline mentions do not count +print(ds[-1]["body"] if ds else "")') + +# 2. The other two signals — labels, and the body's ### Blocking section (via the helper). +ISSUE_JSON=$(gh issue view "$N" --repo "$GITHUB_REPO" --json labels,body) +HAS_PARKING=$(jq -r 'if any(.labels[]; .name == "parking-lot") then "yes" else "no" end' <<<"$ISSUE_JSON") +BLOCK_LINE=$(idd_blocking_section "$(jq -r '.body // ""' <<<"$ISSUE_JSON")") +if [ -n "$BLOCK_LINE" ]; then BLOCKING=yes; else BLOCKING=no; fi + +# 3. Conditional capture — the only shape that survives `set -euo pipefail`. +# A bare TIER=$(idd_parse_complexity …) aborts the caller on exit 3/4/5 and +# takes the whole listing down with it. +if TIER=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>/dev/null); then CEXIT=0; else CEXIT=$?; fi +COMPLEXITY_ERR=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>&1 >/dev/null) || true # raw line on 3/5, `missing-complexity` on 4 + +# 4. The gate — actually call it. Exit 2 is API misuse (a bug in THIS consumer), +# never "not actionable"; do not fold it into the withheld branch. +if VERDICT=$(idd_actionability_verdict --complexity-exit "$CEXIT" --parking-label "$HAS_PARKING" --blocking-section "$BLOCKING" 2>&1); then VEXIT=0; else VEXIT=$?; fi +case "$VEXIT" in + 0) ;; # actionable → dispatch on "$TIER" + 1) REASONS="${VERDICT#not-actionable: }" ;; # withheld → surface "$REASONS" + "$COMPLEXITY_ERR" / "$BLOCK_LINE"; no lifecycle command + *) echo "FATAL: idd_actionability_verdict misuse — $VERDICT" >&2; exit 1 ;; +esac ``` | Function | stdout | exit | |---|---|---| -| `idd_parse_complexity ` | canonical tier | `0` in domain · `3` out of domain (stderr: `unparseable-complexity: `) · `4` no section (stderr: `missing-complexity`) | -| `idd_actionability_verdict …` | `actionable` / `not-actionable: [; …]` | `0` actionable · `1` not actionable · `2` bad usage | +| `idd_parse_complexity ` | the leading tier (exit 0 only) | `0` routable · `3` no tier prefix (stderr `unparseable-complexity: `) · `4` no section (stderr `missing-complexity`) · `5` deferral vocabulary (stderr `deferral-marker: `) | +| `idd_blocking_section ` | first non-blank line of `### Blocking`, empty when absent or a `(none)` placeholder | `0` | +| `idd_actionability_verdict --complexity-exit 0|3|4|5 --parking-label yes|no --blocking-section yes|no` | `actionable` / `not-actionable: [; …]` | `0` actionable · `1` not actionable · `2` bad usage (missing value, non-boolean, unknown flag) | | `idd_actionability_group ` | `blocked` / `parked` | `0` | -**Malformed invocation fails loud (exit 2), never defaults to actionable.** An unanswered signal treated as "clear" would re-open the exact hole this contract closes. +**Only replacing the parser is not a fix.** Round 1 shipped a complete gate, 66 green assertions, and zero consumers calling `idd_actionability_verdict` (verify CRITICAL-1 on PR #318). A consumer that reads `$TIER` and never asks the gate has re-created the incident with a nicer parser. + +**Malformed invocation fails loud (exit 2), never defaults to actionable.** An unanswered signal treated as "clear" would re-open the exact hole this contract closes. A flag with no value is a named exit-2 error, not an infinite loop (verify H1). **When the shared implementation is missing, a consumer SHALL fail loudly and name the path** — never fall back to a private parse. A silent fallback would restore the three-way divergence this file exists to prevent. @@ -135,18 +224,20 @@ Per [`.claude/rules/attribute-assessment.md`](../../../.claude/rules/attribute-a | Lens | Risk | Mitigation | |---|---|---| -| **Scoundrel** | Write `Simple via when triggered` so the via-split yields a legal tier and the issue passes the gate | The provenance suffix only affects the *tier* channel. Deferral is asserted through the label, which the gate reads independently — a scoundrel who wants the issue withheld cannot express that through Complexity anyway, and one who wants it actionable has simply declared it actionable, which is a claim the audit trail records under their name | -| **Lazy Developer** | Skip a signal argument and let the gate assume "clear" | Every argument is required and validated; missing or non-boolean input returns exit 2 with a named cause. The cheap path is not the unsafe path | -| **Confused Developer** | Answer "does this issue block others?" when asked "is this issue blocked?" | The flag is named `--blocking-section`, pointing at the artifact section being read rather than at a relationship. The axis is **what the `### Blocking` section contains**, never who blocks whom | +| **Scoundrel** | Smuggle deferral vocabulary after the ` via ` separator (`Simple via when triggered`) so a suffix-stripping parser yields a legal tier | The scan covers the whole line; the suffix is not an escape hatch (fixture row 906). And in the other direction — a scoundrel who wants an issue *actionable* has simply declared it so under their own name in the audit trail; the label, which the gate reads independently, is the human's veto | +| **Lazy Developer** | Skip a signal argument and let the gate assume "clear"; or read `$TIER` and skip the verdict | Every argument is required and validated; missing or non-boolean input returns exit 2 with a named cause. The consumer contract above makes the verdict call part of the canonical shape, and the #318 verify history is the reminder of what happens without it | +| **Confused Developer** | Answer "does this issue block others?" when asked "is this issue blocked?"; or treat exit 5 as a value to correct | The flag is named `--blocking-section`, pointing at the artifact section being read rather than at a relationship. The three complexity reasons are distinct precisely so that `complexity-deferral-marker` reads as "parked", not "broken" | ## Out of scope - **Evaluating whether a trigger condition has fired.** Trigger conditions are prose propositions about future world state (「等 ≥3 instances」「首次 trace-stale 實害事故」). Deciding whether one has come true requires a human observing the world; it is not derivable from the repo. This gate knows only that *someone declared the issue parked*, never whether the parking is still warranted. That is an epistemic boundary, not a missing feature. -- **Bringing parked issues back into view.** Nothing here re-surfaces an issue whose trigger has fired — tracked separately as **#310**. This contract makes parked issues *more* thoroughly hidden, which makes that gap more urgent, not less. +- **Bringing parked issues back into view.** Nothing here re-surfaces an issue whose trigger has fired — tracked separately as **#310** (`idd-list --parked` is the manual review path). This contract makes parked issues *more* thoroughly hidden, which makes that gap more urgent, not less. +- **Deferral expressed only in prose** (Strategy bullets, Blocking rationale, comments) — see #128 above. The label is the mechanism for that. - **`- [~]` handling** — belongs to `idd-close`, see above. ## See also - [`parallel-orchestration.md`](parallel-orchestration.md) — the `### Conflict Class` contract this one mirrors; orthogonal field, same discipline - [`rules/append-vs-modify.md`](../rules/append-vs-modify.md) — why a Diagnosis comment cannot hold mutable state -- **Why both enumerations above are written as closed lists with explicit no-analogy clauses** rather than as summarizing criteria: a criterion plus illustrative examples is two specifications that will not be updated together, and the criterion's literal reach eventually exceeds the set of cases its author had in mind. The divergence is silent — the prose still reads fine, it just answers a boundary question nobody agreed to. Naming the members and forbidding extension-by-resemblance is what makes a boundary auditable. (This mirrors a maintainer-side writing discipline that is not part of the plugin distribution, so no link is given here.) +- `scripts/tests/actionability-gate/` — the incident fixture (`parked-routing.json`, verbatim 2026-08-10 rows plus corpus-sampled shapes) and the frozen corpus (`corpus-complexity.json`) +- **On enumerations.** The *reason* vocabulary is written as a closed list with an explicit no-analogy clause because it is one: a summarizing criterion plus examples is two specifications that drift apart silently. The *deferral* vocabulary is deliberately **not** presented that way — it is a heuristic with a stated add-criterion (corpus evidence, zero false positives) — because round 1 showed what happens when a heuristic is dressed up as a domain: it rejects the data it was meant to describe. diff --git a/plugins/issue-driven-dev/scripts/lib/actionability.sh b/plugins/issue-driven-dev/scripts/lib/actionability.sh index c95e163..666eb7f 100644 --- a/plugins/issue-driven-dev/scripts/lib/actionability.sh +++ b/plugins/issue-driven-dev/scripts/lib/actionability.sh @@ -1,9 +1,10 @@ #!/usr/bin/env bash # actionability.sh — the single shared implementation of "can this issue be -# worked on right now?" (PsychQuant/issue-driven-development#298) +# worked on right now?" (PsychQuant/issue-driven-development#298 → #316) # # Source this from a skill or test runner: -# . "$(dirname "${BASH_SOURCE[0]}")/actionability.sh" +# . "$CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh" \ +# || { echo "FATAL: missing $CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh" >&2; exit 1; } # # WHY THIS FILE EXISTS # Before #298 there were three private narrowings of the `### Complexity` field @@ -14,41 +15,87 @@ # no private parsing — that is the whole point of this file. Do not re-inline a # regex in a SKILL.md; extend here instead. # -# CLOSED DOMAINS (both are closed — do NOT extend by analogy) -# tier : Simple | Plan | Spectra | SDD-warranted -# optionally followed by " via " (provenance suffix, v2.50+) -# reason : complexity-unparseable | complexity-missing -# parking-lot-label | blocking-nonempty +# THE RULE (round 2, validated on all 159 real diagnoses in this repo: 158/158 +# correct, 0 false positives — see /idd-diagnose #316) +# 1. strip leading/trailing markdown decoration (`**`, `` ` ``, `_`) +# 2. the value must BEGIN WITH one of Simple | Plan | Spectra | SDD-warranted +# (whole word; longest match first). That leading word IS the tier. +# Everything after it — same-line rationale, a parenthetical, an em-dash +# note, a ` via ` provenance suffix — is legal and ignored for +# tier extraction. 93% of the corpus writes the tier this way; a closed +# value domain (round 1, PR #318) would have rejected 42% of it. +# 3. scan the ENTIRE value (not just the part after the tier) for deferral +# vocabulary: when triggered | parking lot | deferred | 暫緩 +# (case-insensitive; hyphen/underscore/space tolerant). A hit withholds +# the issue under its own reason, because a deferral is a legitimate +# state — not a data defect to repair. # -# Deferral state does NOT live in the tier field. It lives in the `parking-lot` -# label, because deferral is mutable (a trigger firing should un-park an issue) -# and a Diagnosis comment is append-only. Storing mutable state in an immutable -# artifact is the root cause #298 diagnosed; keeping tier pure is the fix. +# RISK POSTURE +# The `parking-lot` label is the PRIMARY parked signal (human-authored, +# mutable, removable). Deferral vocabulary is a SECONDARY high-precision net: +# a miss falls back to pre-#298 behaviour, a false positive is a hard stop — +# so the vocabulary stays conservative. It is a heuristic, NOT a closed +# enumeration; do not "complete" it by analogy. +# +# REASON VOCABULARY (this one IS closed — five values) +# complexity-unparseable | complexity-missing | complexity-deferral-marker +# parking-lot-label | blocking-nonempty + +# ── section extraction (shared by both readers below) ──────────────────────── +# +# _idd_section_first_line +# stdout : first non-blank, non-subheading line under `### `; +# empty when the section is absent or empty +# +# - heading anchored at line start, so prose mentioning "### Complexity" +# cannot match +# - ``` and ~~~ fences are tracked: a template example quoted inside a +# fence is not a section (verify #318 H4) +# - the section ends at the next heading of the same or higher level; +# a deeper `####` line is skipped, never taken as the value +_idd_section_first_line() { + local body="${1-}" heading="${2-}" + printf '%s\n' "$body" | awk -v h="$heading" ' + { + if (fence != "") { + if (fence == "`" && $0 ~ /^[[:space:]]*```/) fence = "" + else if (fence == "~" && $0 ~ /^[[:space:]]*~~~/) fence = "" + next + } + if ($0 ~ /^[[:space:]]*```/) { fence = "`"; next } + if ($0 ~ /^[[:space:]]*~~~/) { fence = "~"; next } + } + !grab && $0 ~ ("^###[[:space:]]+" h "[[:space:]]*$") { grab = 1; next } + grab && /^(#|##|###)[[:space:]]/ { exit } + grab && /^####/ { next } + grab && NF { print; exit } + ' +} # ── contract 1: parse the Complexity field ─────────────────────────────────── # # idd_parse_complexity -# stdout : canonical tier, when the value is inside the closed domain -# exit 0 : in domain -# exit 3 : section present, value outside the domain +# stdout : the leading tier — only on exit 0 +# exit 0 : routable +# exit 3 : section present, value does not begin with a tier # → stderr: "unparseable-complexity: " # exit 4 : no `### Complexity` section at all # → stderr: "missing-complexity" +# exit 5 : tier is well-formed but deferral vocabulary is present +# → stderr: "deferral-marker: " +# +# On every non-zero path NOTHING is written to stdout — a consumer that +# captured a tier there could route on it, which is exactly the incident. +# The raw (undecorated) line is surfaced on 3 and 5 so the operator sees what +# the artifact actually says. # -# The raw value is ALWAYS surfaced on the exit-3 path. Never truncate a -# non-domain value down to its tier prefix — that silent narrowing is the -# incident this file prevents. +# Callers under `set -e` MUST use the conditional-capture shape: +# if TIER=$(idd_parse_complexity "$BODY" 2>"$err"); then CEXIT=0; else CEXIT=$?; fi idd_parse_complexity() { local body="${1-}" local raw - # First non-blank line under the `### Complexity` heading. Anchored at line - # start so a mention inside prose ("the ### Complexity field") cannot match. - raw=$(printf '%s\n' "$body" | awk ' - /^###[[:space:]]+Complexity[[:space:]]*$/ { grab = 1; next } - grab && /^###[[:space:]]/ { exit } - grab && NF { print; exit } - ') + raw=$(_idd_section_first_line "$body" Complexity) if [ -z "$raw" ]; then printf 'missing-complexity\n' >&2 @@ -56,7 +103,7 @@ idd_parse_complexity() { fi # Strip markdown bold/italic/code decoration around the value. Diagnoses in - # the wild wrote `**Spectra**`; the decoration is presentation, not value. + # the wild write `**Spectra**`; the decoration is presentation, not value. local val="$raw" val="${val#"${val%%[![:space:]]*}"}" # ltrim val="${val%"${val##*[![:space:]]}"}" # rtrim @@ -64,23 +111,32 @@ idd_parse_complexity() { val="${val#"${val%%[![:space:]]*}"}" val="${val%"${val##*[![:space:]]}"}" - # Provenance suffix: everything from the first " via " onward is source - # attribution, not part of the tier. `Plan via Layer V` → `Plan`. - local tier="${val%% via *}" - tier="${tier%"${tier##*[![:space:]]}"}" - - case "$tier" in - Simple|Plan|Spectra|SDD-warranted) - printf '%s\n' "$tier" - return 0 - ;; - *) - # Surface the ORIGINAL line, not the decoration-stripped form — the - # operator needs to see exactly what the artifact says. - printf 'unparseable-complexity: %s\n' "$raw" >&2 - return 3 - ;; - esac + # Tier = leading whole word. Longest first so `SDD-warranted` is tried before + # anything that could be its prefix; the boundary class keeps `Simpler` + # from reading as `Simple` while letting `Spectra（…）` / `Plan — …` / + # `Spectra**(…)` / `Plan via …` all through. + local tier="" t + for t in SDD-warranted Spectra Simple Plan; do + case "$val" in + "$t"|"$t"[!A-Za-z0-9]*) tier="$t"; break ;; + esac + done + + if [ -z "$tier" ]; then + printf 'unparseable-complexity: %s\n' "$raw" >&2 + return 3 + fi + + # Deferral vocabulary anywhere in the value — including inside a + # parenthetical or after a ` via ` suffix (verify #318 H3). Conservative on + # purpose: see RISK POSTURE above before adding a term. + if printf '%s\n' "$val" | grep -qiE 'when[[:space:]_-]+triggered|parking[[:space:]_-]*lot|deferred|暫緩'; then + printf 'deferral-marker: %s\n' "$raw" >&2 + return 5 + fi + + printf '%s\n' "$tier" + return 0 } # ── contract 2: the three-signal gate ──────────────────────────────────────── @@ -93,15 +149,34 @@ idd_parse_complexity() { # Pass requires ALL THREE signals clear. The `- [~]` Strategy skip marker is NOT # an input: it is a close-time per-item disposition owned by idd-close, and # reusing it here would answer a different question than the one being asked. +# +# Exit 2 is API misuse and MUST NOT be conflated with "not actionable" by a +# consumer — it means the consumer fed the gate garbage, not that the issue is +# parked. idd_actionability_verdict() { local cexit="" label="" blocking="" while [ $# -gt 0 ]; do case "$1" in - --complexity-exit) cexit="${2-}"; shift 2 ;; - --parking-label) label="${2-}"; shift 2 ;; - --blocking-section) blocking="${2-}"; shift 2 ;; - *) printf 'idd_actionability_verdict: unknown argument: %s\n' "$1" >&2; return 2 ;; + --complexity-exit|--parking-label|--blocking-section) + # A value-less flag must be a named error, not an infinite loop + # (verify #318 H1: `shift 2` on a single remaining arg fails + # without shifting, so the loop never advanced). + if [ $# -lt 2 ]; then + printf 'idd_actionability_verdict: %s requires a value\n' "$1" >&2 + return 2 + fi + case "$1" in + --complexity-exit) cexit="$2" ;; + --parking-label) label="$2" ;; + --blocking-section) blocking="$2" ;; + esac + shift 2 + ;; + *) + printf 'idd_actionability_verdict: unknown argument: %s\n' "$1" >&2 + return 2 + ;; esac done @@ -109,8 +184,8 @@ idd_actionability_verdict() { # unanswered signal as "clear" would re-open the exact hole #298 closed — # this is the Lazy Developer lens: the cheap path must not be the unsafe one. case "$cexit" in - 0|3|4) ;; - *) printf 'idd_actionability_verdict: --complexity-exit must be 0, 3 or 4 (got: %s)\n' "${cexit:-}" >&2; return 2 ;; + 0|3|4|5) ;; + *) printf 'idd_actionability_verdict: --complexity-exit must be 0, 3, 4 or 5 (got: %s)\n' "${cexit:-}" >&2; return 2 ;; esac case "$label" in yes|no) ;; @@ -122,9 +197,10 @@ idd_actionability_verdict() { esac local reasons=() - [ "$cexit" = "3" ] && reasons+=("complexity-unparseable") - [ "$cexit" = "4" ] && reasons+=("complexity-missing") - [ "$label" = "yes" ] && reasons+=("parking-lot-label") + [ "$cexit" = "3" ] && reasons+=("complexity-unparseable") + [ "$cexit" = "4" ] && reasons+=("complexity-missing") + [ "$cexit" = "5" ] && reasons+=("complexity-deferral-marker") + [ "$label" = "yes" ] && reasons+=("parking-lot-label") [ "$blocking" = "yes" ] && reasons+=("blocking-nonempty") if [ ${#reasons[@]} -eq 0 ]; then @@ -138,6 +214,28 @@ idd_actionability_verdict() { return 1 } +# ── contract 3: the third signal — `### Blocking` in the issue body ────────── +# +# idd_blocking_section +# stdout : the first non-blank line of the `### Blocking` section when it +# holds a real blocker; empty otherwise +# exit 0 : always +# +# idd-update writes `- (none)` into an empty section, so "non-empty" means +# "holds something other than a none-placeholder". Recognised placeholders, +# optionally bulleted and decorated, any case: (none) · none · n/a · - +# Consumers feed the result to the gate as +# --blocking-section "$([ -n "$BLOCK_LINE" ] && echo yes || echo no)" +# and may show $BLOCK_LINE as the blocked reason (#84 behaviour preserved). +idd_blocking_section() { + local body="${1-}" first + first=$(_idd_section_first_line "$body" Blocking) + if printf '%s\n' "$first" | grep -qiE '^[[:space:]]*([-*][[:space:]]+)?[_*`]*(\(none\)|none|n/a|-)?[_*`]*[[:space:]]*$'; then + return 0 + fi + printf '%s\n' "$first" +} + # ── display helper: which group does a not-actionable issue belong to? ─────── # # idd_actionability_group @@ -145,7 +243,9 @@ idd_actionability_verdict() { # # Reason `blocking-nonempty` ALONE keeps the pre-#298 blocked-state grouping # (#84) intact — its heading, banner and footer counts are user-facing behavior -# that must not regress. Everything else lands in the parked group. +# that must not regress. Everything else — parking-lot-label, any of the three +# complexity reasons, or a mix that includes blocking — lands in the parked +# group, where the raw Complexity value is shown alongside the reason. idd_actionability_group() { local reasons="${1-}" case "$reasons" in diff --git a/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/corpus-complexity.json b/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/corpus-complexity.json new file mode 100644 index 0000000..effb699 --- /dev/null +++ b/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/corpus-complexity.json @@ -0,0 +1,1118 @@ +{ + "_provenance": "Verbatim first line of `### Complexity` from the LATEST `## Diagnosis` comment of every diagnosed issue in PsychQuant/issue-driven-development, snapshot 2026-08-15 (225 issues fetched, 159 diagnosed). Expectations are the round-2 rule from /idd-diagnose #316 — hand-reviewed: 149 routable, 9 deferral-marker, 1 missing section (#273), 0 unparseable. Do NOT regenerate from live GitHub; this is a frozen regression baseline.", + "rows": [ + { + "number": 1, + "state": "CLOSED", + "complexity_raw": "**Spectra**", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 11, + "state": "CLOSED", + "complexity_raw": "**Simple**", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 12, + "state": "CLOSED", + "complexity_raw": "**Spectra**", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 13, + "state": "CLOSED", + "complexity_raw": "**Plan**", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 26, + "state": "CLOSED", + "complexity_raw": "**Simple**", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 27, + "state": "CLOSED", + "complexity_raw": "**Plan**", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 28, + "state": "CLOSED", + "complexity_raw": "**Plan**", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 31, + "state": "CLOSED", + "complexity_raw": "**Simple**", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 34, + "state": "CLOSED", + "complexity_raw": "**Plan**", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 37, + "state": "CLOSED", + "complexity_raw": "**Spectra**", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 44, + "state": "CLOSED", + "complexity_raw": "**Spectra** (Layer 2 + Layer 3 都命中)", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 45, + "state": "CLOSED", + "complexity_raw": "**Plan** (Layer P 命中)", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 46, + "state": "CLOSED", + "complexity_raw": "**Spectra** (Layer 2 + Layer 3 都命中)", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 47, + "state": "CLOSED", + "complexity_raw": "**Plan** (Layer P 命中)", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 48, + "state": "CLOSED", + "complexity_raw": "**Spectra**", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 49, + "state": "CLOSED", + "complexity_raw": "**Simple** (Layer 1 disqualifier 命中:純 docs 改動)", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 51, + "state": "CLOSED", + "complexity_raw": "**Plan** (Layer P 命中)", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 52, + "state": "CLOSED", + "complexity_raw": "**Plan** (Layer P 命中)", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 53, + "state": "CLOSED", + "complexity_raw": "**Simple** (Layer 1 not triggered + Layer 2 / Layer P 都不命中)", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 54, + "state": "CLOSED", + "complexity_raw": "**Spectra** (Layer 2 + Layer 3 都命中)", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 55, + "state": "CLOSED", + "complexity_raw": "**Plan** (Layer P 命中)", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 56, + "state": "CLOSED", + "complexity_raw": "**Spectra** (Layer 2 + Layer 3 都命中)", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 57, + "state": "CLOSED", + "complexity_raw": "Spectra", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 59, + "state": "CLOSED", + "complexity_raw": "**Plan** (cross-file refactor with no external contract change)", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 60, + "state": "CLOSED", + "complexity_raw": "**Simple**", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 61, + "state": "CLOSED", + "complexity_raw": "**Plan** (5+ ordered steps + new infrastructure)", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 62, + "state": "CLOSED", + "complexity_raw": "**Simple**", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 63, + "state": "CLOSED", + "complexity_raw": "**Simple**", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 64, + "state": "CLOSED", + "complexity_raw": "**Simple** (single-line regex fix with clear root cause + self-contained)", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 65, + "state": "CLOSED", + "complexity_raw": "**Plan** (decision-heavy — Approach A vs Approach B)", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 66, + "state": "CLOSED", + "complexity_raw": "**Simple** (pure research/verification task — read 2 docs, compare, report)", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 68, + "state": "CLOSED", + "complexity_raw": "**Plan** (decision-heavy at disambiguation algorithm choice)", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 72, + "state": "CLOSED", + "complexity_raw": "Spectra（opt-out → 直接 propose）", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 74, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 75, + "state": "CLOSED", + "complexity_raw": "**Plan** (decision-heavy + risk-sensitive boundary)", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 76, + "state": "CLOSED", + "complexity_raw": "**Plan** (risk-sensitive boundary — irreversible side effects)", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 77, + "state": "CLOSED", + "complexity_raw": "**Plan** (5+ ordered steps + decision-heavy at Gap 6)", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 78, + "state": "CLOSED", + "complexity_raw": "**Simple**", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 79, + "state": "CLOSED", + "complexity_raw": "**Plan** (decision-heavy + spec contract dependencies)", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 80, + "state": "CLOSED", + "complexity_raw": "**Plan** (decision-heavy — heuristic constants + scoring normalization choice)", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 84, + "state": "CLOSED", + "complexity_raw": "Plan（Layer P：輸出契約變更 + blocked 判定 heuristic 的 decision 已定案）", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 85, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 86, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 87, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 88, + "state": "CLOSED", + "complexity_raw": "**Plan** (multi-site fix + write-time + read-time consistency)", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 89, + "state": "CLOSED", + "complexity_raw": "Simple — see #74 (handled in the cluster fix).", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 90, + "state": "CLOSED", + "complexity_raw": "**Simple**", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 91, + "state": "CLOSED", + "complexity_raw": "**Simple**", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 93, + "state": "CLOSED", + "complexity_raw": "**Plan** (decision-heavy investigation + multi-file resolution + drift prevention)", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 95, + "state": "CLOSED", + "complexity_raw": "**Simple** (single-file line-ending normalization with clear root cause + self-contained fix)", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 96, + "state": "CLOSED", + "complexity_raw": "**Plan**", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 97, + "state": "CLOSED", + "complexity_raw": "`Plan` —— Layer P 命中以下三項:", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 100, + "state": "CLOSED", + "complexity_raw": "**Plan** (decision-heavy at Finding 1 + risk-sensitive boundary)", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 102, + "state": "CLOSED", + "complexity_raw": "**Spectra**", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 103, + "state": "CLOSED", + "complexity_raw": "**Spectra**", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 105, + "state": "CLOSED", + "complexity_raw": "**Plan** — triggered by Layer P signals:", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 106, + "state": "CLOSED", + "complexity_raw": "**Simple** (pure research/verification task — read 1 doc, compare, report)", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 107, + "state": "CLOSED", + "complexity_raw": "**Simple** — triggers Layer 1 disqualifier:", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 108, + "state": "CLOSED", + "complexity_raw": "**Plan** — triggered by Layer P signals:", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 111, + "state": "CLOSED", + "complexity_raw": "Spectra", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 112, + "state": "CLOSED", + "complexity_raw": "**Plan** (multi-touch in same skill + decision-heavy on staging path / cleanup / failure handling)", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 116, + "state": "CLOSED", + "complexity_raw": "**Spectra**", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 117, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 119, + "state": "CLOSED", + "complexity_raw": "**Spectra**", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 120, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 122, + "state": "CLOSED", + "complexity_raw": "Simple", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 123, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 124, + "state": "CLOSED", + "complexity_raw": "**Simple** — 單檔修改（`idd-close/SKILL.md`），新增 supersession rule + 一段文件，沒有 refactor，沒有跨 skill 依賴。", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 125, + "state": "CLOSED", + "complexity_raw": "**Simple**（非 SDD-warranted）", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 128, + "state": "CLOSED", + "complexity_raw": "Plan（觸發表）+ 未決 UX 軸 → **移入 discussion list**（使用者原話即開放問題；unattended 不代答）", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 130, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 131, + "state": "CLOSED", + "complexity_raw": "Simple when triggered", + "expect_parse_exit": 5, + "expect_tier": null + }, + { + "number": 133, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 134, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 135, + "state": "CLOSED", + "complexity_raw": "**Spectra**(SDD-warranted per Layer 2 + Layer 3)", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 136, + "state": "CLOSED", + "complexity_raw": "**Spectra**(Layer 2 + Layer 3 if/when triggered):若實作,會修改既有 published `idd-edit` SKILL.md normative behavior,且新增 cross-skill protocol contract。**但目前狀態 = parking lot,Spectra 不立即 trigger。**", + "expect_parse_exit": 5, + "expect_tier": null + }, + { + "number": 137, + "state": "CLOSED", + "complexity_raw": "**Plan**(Layer P:**4 個 signal 命中**)", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 138, + "state": "CLOSED", + "complexity_raw": "Simple", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 139, + "state": "CLOSED", + "complexity_raw": "Spectra（default — 先 discuss；分岔 A/C 是 user 決策）", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 140, + "state": "CLOSED", + "complexity_raw": "Simple when triggered", + "expect_parse_exit": 5, + "expect_tier": null + }, + { + "number": 141, + "state": "CLOSED", + "complexity_raw": "Plan（Layer P：多 metadata 面 + outward-facing 邊界）", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 142, + "state": "CLOSED", + "complexity_raw": "Simple（規格已由 issue 完整給定，實作依附 #141）", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 143, + "state": "CLOSED", + "complexity_raw": "**Spectra when triggered**(Layer 2:plugin-level extension protocol = published API for future callers;Layer 3:architectural decision with long-term maintenance implications)。**但目前 = parking lot,wait for trigger。**", + "expect_parse_exit": 5, + "expect_tier": null + }, + { + "number": 144, + "state": "CLOSED", + "complexity_raw": "**Spectra when triggered**(MANIFESTO 是 plugin-level published contract,影響所有 user;架構性質決定 design 必走 Spectra discuss)。**但目前 = parking lot,wait for instance #2 + #3。**", + "expect_parse_exit": 5, + "expect_tier": null + }, + { + "number": 145, + "state": "CLOSED", + "complexity_raw": "**Spectra when triggered** — governance policy 是 plugin-level published contract,影響 cross-plugin coordination。**但目前 = parking lot。**", + "expect_parse_exit": 5, + "expect_tier": null + }, + { + "number": 146, + "state": "CLOSED", + "complexity_raw": "**Simple when triggered**(Layer 1 disqualifier:probably just \"add Note to /idd-clarify SKILL.md saying 'if ambiguity row 指向 self plugin docs gap, file IDD issue' \" — 純 docs update,no normative change)。", + "expect_parse_exit": 5, + "expect_tier": null + }, + { + "number": 147, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 148, + "state": "CLOSED", + "complexity_raw": "**Spectra**(Layer 2 + Layer 3 雙命中)", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 150, + "state": "CLOSED", + "complexity_raw": "**Spectra**(Layer 2 + Layer 3 全命中)", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 151, + "state": "CLOSED", + "complexity_raw": "**Plan**", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 152, + "state": "CLOSED", + "complexity_raw": "Simple", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 154, + "state": "CLOSED", + "complexity_raw": "**Plan** (per Layer P signals — confirmed against issue's self-suggestion):", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 156, + "state": "CLOSED", + "complexity_raw": "Plan（design-heavy：lint 機制、是否建 lib、遷移範圍、framework choice 都是 decision；新 shared abstraction 給未來 test runner 用）—— 但 **scope 需先 clarify**（A/B/C 差異巨大），故先 AskUserQuestion 再進 plan。", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 157, + "state": "CLOSED", + "complexity_raw": "Plan when triggered", + "expect_parse_exit": 5, + "expect_tier": null + }, + { + "number": 158, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 160, + "state": "CLOSED", + "complexity_raw": "Simple — 單檔、2 個 1-token 補丁、clear、#154 已立 fix 範本；非 decision-heavy、風險近零（有 test 覆蓋）。", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 161, + "state": "CLOSED", + "complexity_raw": "Simple", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 162, + "state": "CLOSED", + "complexity_raw": "Plan（Layer P：resolution 優先序是跨 skill 契約變更）", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 163, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 164, + "state": "CLOSED", + "complexity_raw": "**Spectra**（Layer 2 + Layer 3 皆命中）：", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 167, + "state": "CLOSED", + "complexity_raw": "**Spectra**", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 169, + "state": "CLOSED", + "complexity_raw": "**Plan**", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 170, + "state": "CLOSED", + "complexity_raw": "**Simple**", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 172, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 176, + "state": "CLOSED", + "complexity_raw": "**Plan**", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 178, + "state": "CLOSED", + "complexity_raw": "Simple", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 179, + "state": "CLOSED", + "complexity_raw": "Spectra（discuss-first）—— Layer 2 命中（新 IDD convention/SOP 給 future callers，該寫成 documented contract）；且有真實 open design questions（#83 關係、unification scope）+ cross-issue 協調需要對齊。**但**最小版本偏 SOP-doc + 小 idd-list 改，若 user 方向已定可降到 Plan。", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 180, + "state": "CLOSED", + "complexity_raw": "Simple", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 181, + "state": "CLOSED", + "complexity_raw": "Simple", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 183, + "state": "CLOSED", + "complexity_raw": "**Spectra**", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 184, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 186, + "state": "CLOSED", + "complexity_raw": "**Simple**", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 187, + "state": "CLOSED", + "complexity_raw": "Simple", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 188, + "state": "CLOSED", + "complexity_raw": "Simple", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 189, + "state": "CLOSED", + "complexity_raw": "**Simple**", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 190, + "state": "CLOSED", + "complexity_raw": "**Spectra** — Layer 2（修改 published skill surface 給 future callers）+ Layer 3（normative 行為變更、影響 2+ specs〔idd-clarify + idd-diagnose-clarity-gate〕、是會被 future maintainer 繼承的 cross-cutting UX 原則決定）。", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 192, + "state": "CLOSED", + "complexity_raw": "**Spectra**", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 199, + "state": "CLOSED", + "complexity_raw": "Simple", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 200, + "state": "CLOSED", + "complexity_raw": "Spectra when triggered", + "expect_parse_exit": 5, + "expect_tier": null + }, + { + "number": 202, + "state": "CLOSED", + "complexity_raw": "Spectra", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 203, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 205, + "state": "CLOSED", + "complexity_raw": "Spectra — 觸及 living spec（idd-verify MODIFIED）+ 跨 skill/workflow/reference 三面；本 repo 為 Spectra-governed。", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 207, + "state": "CLOSED", + "complexity_raw": "Spectra", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 209, + "state": "CLOSED", + "complexity_raw": "Spectra", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 210, + "state": "CLOSED", + "complexity_raw": "Plan（analysis-heavy；判準機械可依）", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 211, + "state": "CLOSED", + "complexity_raw": "Plan（gate 位置與強度的設計已由 #209 D2 前例 + #210 audit 定案）", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 212, + "state": "CLOSED", + "complexity_raw": "Simple", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 214, + "state": "CLOSED", + "complexity_raw": "Spectra", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 215, + "state": "CLOSED", + "complexity_raw": "Plan（Layer P：cross-file 一致性 + 判準應用的 judgment 邊界）", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 216, + "state": "CLOSED", + "complexity_raw": "Simple", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 217, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 219, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 220, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 221, + "state": "CLOSED", + "complexity_raw": "Spectra（opt-out → 直接 propose）", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 222, + "state": "CLOSED", + "complexity_raw": "Simple（單 detector 替換，contract 由 #123 提供）", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 224, + "state": "CLOSED", + "complexity_raw": "Simple（單檔機械修正、修法已定案、驗收可機械化）", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 225, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 226, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 227, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 228, + "state": "CLOSED", + "complexity_raw": "Simple", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 251, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 252, + "state": "CLOSED", + "complexity_raw": "Spectra（default — 先 discuss）", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 258, + "state": "CLOSED", + "complexity_raw": "Spectra（opt-out → 直接 propose）", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 264, + "state": "CLOSED", + "complexity_raw": "Spectra（opt-out → 直接 propose）", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 267, + "state": "CLOSED", + "complexity_raw": "Plan via hard-gate", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 269, + "state": "CLOSED", + "complexity_raw": "Spectra", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 272, + "state": "CLOSED", + "complexity_raw": "Spectra", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 273, + "state": "CLOSED", + "complexity_raw": null, + "expect_parse_exit": 4, + "expect_tier": null + }, + { + "number": 275, + "state": "CLOSED", + "complexity_raw": "Simple — 單一 script 的 guard + fixtures，修法由 issue Expected 定形，唯一修正是 exit code 歸帶。", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 276, + "state": "CLOSED", + "complexity_raw": "**Plan**", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 277, + "state": "CLOSED", + "complexity_raw": "Plan（decision-heavy — 3 valid approaches，方向拍板屬 maintainer；issue 明文「哪一個都行，寫下來就好」→ 拍板後執行是 Simple-tier docs+pointer）", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 278, + "state": "CLOSED", + "complexity_raw": "Simple — Layer 1 disqualifier 命中（primary deliverable 是 docs/prose）；2 檔、判準由 issue 三問 + 既有機制（comment/update/prepend-note）組合定形，零新機件。", + "expect_parse_exit": 0, + "expect_tier": "Simple" + }, + { + "number": 289, + "state": "CLOSED", + "complexity_raw": "**Plan**", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 290, + "state": "CLOSED", + "complexity_raw": "**Spectra**", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 292, + "state": "CLOSED", + "complexity_raw": "Plan", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 293, + "state": "CLOSED", + "complexity_raw": "Plan —— 七個呼叫點互相依賴同一個述詞，且要新增一個時序檢查；不是單檔 fix。", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 295, + "state": "CLOSED", + "complexity_raw": "**Plan**", + "expect_parse_exit": 0, + "expect_tier": "Plan" + }, + { + "number": 298, + "state": "CLOSED", + "complexity_raw": "**Spectra**", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + }, + { + "number": 302, + "state": "CLOSED", + "complexity_raw": "**Spectra**", + "expect_parse_exit": 0, + "expect_tier": "Spectra" + } + ] +} diff --git a/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/parked-routing.json b/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/parked-routing.json index 7f0ad66..7476fed 100644 --- a/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/parked-routing.json +++ b/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/parked-routing.json @@ -2,8 +2,8 @@ { "number": 37, "snapshot": true, - "note": "2026-08-10 snapshot, taken at the moment of the misroute (morning). Bare tier, no parking-lot label yet — this is the one issue the routing judged correctly that day. The label was applied later the same day when the issue was re-parked; recording that later state here would destroy the fixture's value as a regression of the actual incident.", - "complexity_raw": "Spectra", + "note": "2026-08-10 snapshot, taken at the moment of the misroute (morning). Decorated bare tier `**Spectra**` verbatim from the latest Diagnosis comment; no parking-lot label yet — the one issue the routing judged correctly that day. The label was applied later the same day when the issue was re-parked; recording that later state here would destroy the fixture's value as a regression of the actual incident.", + "complexity_raw": "**Spectra**", "labels": [ "enhancement" ], @@ -15,130 +15,128 @@ { "number": 131, "snapshot": true, - "note": "2026-08-10 snapshot. Deferral qualifier present, label absent — the exact shape that produced the silent misroute.", + "note": "2026-08-10 snapshot. Deferral qualifier present, label absent — the exact shape that produced the silent misroute. Verbatim from the Diagnosis comment.", "complexity_raw": "Simple when triggered", "labels": [ "enhancement" ], - "expect_parse_exit": 3, + "expect_parse_exit": 5, "expect_tier": null, "expect_verdict": "not-actionable", "expect_reasons": [ - "complexity-unparseable" + "complexity-deferral-marker" ] }, { "number": 146, "snapshot": true, - "note": "2026-08-10 snapshot. Qualifier and label agree.", - "complexity_raw": "Simple when triggered (parking lot)", + "note": "2026-08-10 snapshot. Decorated tier + deferral qualifier + parenthetical rationale, verbatim from the Diagnosis comment. The issue body's Current Status mirrored it as `Simple when triggered (parking lot)` (see row 909). Qualifier and label agree.", + "complexity_raw": "**Simple when triggered**(Layer 1 disqualifier:probably just \"add Note to /idd-clarify SKILL.md saying 'if ambiguity row 指向 self plugin docs gap, file IDD issue' \" — 純 docs update,no normative change)。", "labels": [ "enhancement", "parking-lot" ], - "expect_parse_exit": 3, + "expect_parse_exit": 5, "expect_tier": null, "expect_verdict": "not-actionable", "expect_reasons": [ - "complexity-unparseable", + "complexity-deferral-marker", "parking-lot-label" ] }, { "number": 157, "snapshot": true, - "note": "2026-08-10 snapshot. Plan tier with deferral qualifier.", + "note": "2026-08-10 snapshot. Plan tier with deferral qualifier, verbatim.", "complexity_raw": "Plan when triggered", "labels": [ "enhancement", "parking-lot" ], - "expect_parse_exit": 3, + "expect_parse_exit": 5, "expect_tier": null, "expect_verdict": "not-actionable", "expect_reasons": [ - "complexity-unparseable", + "complexity-deferral-marker", "parking-lot-label" ] }, { "number": 128, "snapshot": true, - "note": "2026-08-10 snapshot. Free prose, not tier-plus-qualifier. Migration task 5.2 needs a human ruling on this one; the gate only has to withhold it.", - "complexity_raw": "Plan（觸發表）+ 未決 UX 軸 → **移入 discussion list**", + "note": "2026-08-10 snapshot. Tier prefix `Plan` + free-prose rationale; the deferral (\"blocked-by #86\") lived ONLY in Strategy prose — no marker vocabulary, no parking-lot label, empty ### Blocking. Under the round-2 rule this routes as Plan. That is the DESIGNED false-negative (deferral-in-prose → label is the backstop); encoding it as exit 5 would falsify the corpus. Kept honest.", + "complexity_raw": "Plan（觸發表）+ 未決 UX 軸 → **移入 discussion list**（使用者原話即開放問題；unattended 不代答）", "labels": [ "enhancement" ], - "expect_parse_exit": 3, - "expect_tier": null, - "expect_verdict": "not-actionable", - "expect_reasons": [ - "complexity-unparseable" - ] + "expect_parse_exit": 0, + "expect_tier": "Plan", + "expect_verdict": "actionable", + "expect_reasons": [] }, { "number": 200, "snapshot": true, - "note": "2026-08-10 snapshot. Qualifier present, label absent — carries a user defer ruling dated 2026-07-07.", + "note": "2026-08-10 snapshot. Qualifier present, label absent — carries a user defer ruling dated 2026-07-07. Verbatim.", "complexity_raw": "Spectra when triggered", "labels": [ "enhancement" ], - "expect_parse_exit": 3, + "expect_parse_exit": 5, "expect_tier": null, "expect_verdict": "not-actionable", "expect_reasons": [ - "complexity-unparseable" + "complexity-deferral-marker" ] }, { "number": 143, "snapshot": true, - "note": "2026-08-10 snapshot.", - "complexity_raw": "Spectra when triggered (parking lot)", + "note": "2026-08-10 snapshot. Decorated tier + qualifier + long parenthetical rationale, verbatim from the Diagnosis comment (body mirror was `Spectra when triggered (parking lot)`).", + "complexity_raw": "**Spectra when triggered**(Layer 2:plugin-level extension protocol = published API for future callers;Layer 3:architectural decision with long-term maintenance implications)。**但目前 = parking lot,wait for trigger。**", "labels": [ "enhancement", "parking-lot" ], - "expect_parse_exit": 3, + "expect_parse_exit": 5, "expect_tier": null, "expect_verdict": "not-actionable", "expect_reasons": [ - "complexity-unparseable", + "complexity-deferral-marker", "parking-lot-label" ] }, { "number": 144, "snapshot": true, - "note": "2026-08-10 snapshot.", - "complexity_raw": "Spectra when triggered (parking lot)", + "note": "2026-08-10 snapshot. Same shape as #143, verbatim.", + "complexity_raw": "**Spectra when triggered**(MANIFESTO 是 plugin-level published contract,影響所有 user;架構性質決定 design 必走 Spectra discuss)。**但目前 = parking lot,wait for instance #2 + #3。**", "labels": [ "enhancement", "parking-lot" ], - "expect_parse_exit": 3, + "expect_parse_exit": 5, "expect_tier": null, "expect_verdict": "not-actionable", "expect_reasons": [ - "complexity-unparseable", + "complexity-deferral-marker", "parking-lot-label" ] }, { "number": 145, "snapshot": true, - "note": "2026-08-10 snapshot.", - "complexity_raw": "Spectra when triggered (parking lot)", + "note": "2026-08-10 snapshot. Decorated tier + qualifier + em-dash rationale, verbatim.", + "complexity_raw": "**Spectra when triggered** — governance policy 是 plugin-level published contract,影響 cross-plugin coordination。**但目前 = parking lot。**", "labels": [ "enhancement", "parking-lot" ], - "expect_parse_exit": 3, + "expect_parse_exit": 5, "expect_tier": null, "expect_verdict": "not-actionable", "expect_reasons": [ - "complexity-unparseable", + "complexity-deferral-marker", "parking-lot-label" ] }, @@ -225,5 +223,217 @@ "expect_tier": "Simple", "expect_verdict": "actionable", "expect_reasons": [] + }, + { + "number": 264, + "snapshot": false, + "note": "Real corpus value. Tier + parenthetical routing note — the single most common non-bare shape.", + "complexity_raw": "Spectra（opt-out → 直接 propose）", + "labels": [ + "enhancement" + ], + "expect_parse_exit": 0, + "expect_tier": "Spectra", + "expect_verdict": "actionable", + "expect_reasons": [] + }, + { + "number": 215, + "snapshot": false, + "note": "Real corpus value. Tier + parenthetical Layer P rationale.", + "complexity_raw": "Plan（Layer P：cross-file 一致性 + 判準應用的 judgment 邊界）", + "labels": [ + "enhancement" + ], + "expect_parse_exit": 0, + "expect_tier": "Plan", + "expect_verdict": "actionable", + "expect_reasons": [] + }, + { + "number": 160, + "snapshot": false, + "note": "Real corpus value. Tier + em-dash rationale.", + "complexity_raw": "Simple — 單檔、2 個 1-token 補丁、clear、#154 已立 fix 範本；非 decision-heavy", + "labels": [ + "enhancement" + ], + "expect_parse_exit": 0, + "expect_tier": "Simple", + "expect_verdict": "actionable", + "expect_reasons": [] + }, + { + "number": 136, + "snapshot": false, + "note": "Real corpus value. Bare-looking tier, deferral vocabulary hidden inside the parenthetical — scanning only the suffix after the tier would MISS this.", + "complexity_raw": "**Spectra**(Layer 2 + Layer 3 if/when triggered):若實作,會修改既有 published `idd-edit` SKILL.md", + "labels": [ + "enhancement", + "parking-lot" + ], + "expect_parse_exit": 5, + "expect_tier": null, + "expect_verdict": "not-actionable", + "expect_reasons": [ + "complexity-deferral-marker", + "parking-lot-label" + ] + }, + { + "number": 906, + "snapshot": false, + "note": "Synthetic (verify #318 H3). Deferral vocabulary smuggled AFTER the ` via ` separator. The provenance suffix must not be an escape hatch.", + "complexity_raw": "Simple via when triggered", + "labels": [ + "enhancement" + ], + "expect_parse_exit": 5, + "expect_tier": null, + "expect_verdict": "not-actionable", + "expect_reasons": [ + "complexity-deferral-marker" + ] + }, + { + "number": 907, + "snapshot": false, + "note": "Synthetic (verify #318 H4). No real section; a fenced example of the template appears in prose. The fence must be skipped, yielding complexity-missing.", + "complexity_raw": null, + "labels": [ + "enhancement" + ], + "expect_parse_exit": 4, + "expect_tier": null, + "expect_verdict": "not-actionable", + "expect_reasons": [ + "complexity-missing" + ], + "fenced_example": true + }, + { + "number": 908, + "snapshot": false, + "note": "Synthetic. Value is neither a tier nor deferral — genuine data defect.", + "complexity_raw": "移入 discussion list", + "labels": [ + "enhancement" + ], + "expect_parse_exit": 3, + "expect_tier": null, + "expect_verdict": "not-actionable", + "expect_reasons": [ + "complexity-unparseable" + ] + }, + { + "number": 292, + "snapshot": false, + "note": "Real corpus value (#292). Bare tier, undecorated.", + "complexity_raw": "Plan", + "labels": [ + "enhancement" + ], + "expect_parse_exit": 0, + "expect_tier": "Plan", + "expect_verdict": "actionable", + "expect_reasons": [] + }, + { + "number": 272, + "snapshot": false, + "note": "Real corpus value (#272). Bare tier, undecorated.", + "complexity_raw": "Spectra", + "labels": [ + "enhancement" + ], + "expect_parse_exit": 0, + "expect_tier": "Spectra", + "expect_verdict": "actionable", + "expect_reasons": [] + }, + { + "number": 228, + "snapshot": false, + "note": "Real corpus value (#228). Bare tier, undecorated.", + "complexity_raw": "Simple", + "labels": [ + "enhancement" + ], + "expect_parse_exit": 0, + "expect_tier": "Simple", + "expect_verdict": "actionable", + "expect_reasons": [] + }, + { + "number": 267, + "snapshot": false, + "note": "Real corpus value (#267). Provenance suffix from the hard gate — the only real ` via ` value in the corpus.", + "complexity_raw": "Plan via hard-gate", + "labels": [ + "enhancement" + ], + "expect_parse_exit": 0, + "expect_tier": "Plan", + "expect_verdict": "actionable", + "expect_reasons": [] + }, + { + "number": 97, + "snapshot": false, + "note": "Real corpus value (#97). Backtick decoration + em-dash rationale — decoration is not only `**`.", + "complexity_raw": "`Plan` —— Layer P 命中以下三項:", + "labels": [ + "enhancement" + ], + "expect_parse_exit": 0, + "expect_tier": "Plan", + "expect_verdict": "actionable", + "expect_reasons": [] + }, + { + "number": 190, + "snapshot": false, + "note": "Real corpus value (#190). Bold decoration + em-dash rationale.", + "complexity_raw": "**Spectra** — Layer 2（修改 published skill surface 給 future callers）+ Layer 3（normative 行為變更、影響 2+ specs〔idd-clarify + idd-diagnose-clarity-gate〕、是會被 future maintainer 繼承的 cross-cutting UX 原則決定）。", + "labels": [ + "enhancement" + ], + "expect_parse_exit": 0, + "expect_tier": "Spectra", + "expect_verdict": "actionable", + "expect_reasons": [] + }, + { + "number": 140, + "snapshot": false, + "note": "Real corpus value (#140). Bare deferral qualifier; not part of the 2026-08-10 snapshot but the same shape as #131.", + "complexity_raw": "Simple when triggered", + "labels": [ + "enhancement" + ], + "expect_parse_exit": 5, + "expect_tier": null, + "expect_verdict": "not-actionable", + "expect_reasons": [ + "complexity-deferral-marker" + ] + }, + { + "number": 909, + "snapshot": false, + "note": "Real value, different SOURCE: the `### Complexity` line idd-update mirrored into the issue BODY (Current Status) of #143–#146 on 2026-08-10. Consumers parse the comment, not the body, but this is the form that carries the `parking lot` vocabulary verbatim.", + "complexity_raw": "Spectra when triggered (parking lot)", + "labels": [ + "enhancement", + "parking-lot" + ], + "expect_parse_exit": 5, + "expect_tier": null, + "expect_verdict": "not-actionable", + "expect_reasons": [ + "complexity-deferral-marker", + "parking-lot-label" + ] } ] diff --git a/plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh b/plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh index f9f0bf9..2c89a81 100755 --- a/plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh +++ b/plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash # Test: the actionability gate — does routing know whether an issue can be worked -# on right now? (PsychQuant/issue-driven-development#298) +# on right now? (PsychQuant/issue-driven-development#298 → #316) # # The incident this fixture reproduces: on 2026-08-10 a real 22-issue backlog was # routed by /idd-list. Of the 11 diagnosed issues, 8 parked/deferred/blocked ones @@ -8,26 +8,31 @@ # ruling the user had personally made on 2026-07-07. The failure was silent — the # table looked syntactically correct and carried no warning. # -# Root cause: `### Complexity` never declared a closed value domain and had no -# unparseable contract, so a producer could legally write `Simple when triggered` -# and three consumers each invented an incompatible narrowing: -# - idd-list `([A-Za-z-]+)` → silently truncated to `Simple` -# - idd-all `(.+?)` + via-split → non-tier string, matched no dispatch row -# - idd-implement same → same -# idd-all's `UNKNOWN → abort` net does NOT catch this: it only fires when the -# regex fails entirely, not when it matches an out-of-domain value. +# Round 1 (PR #318) framed the fix as a CLOSED value domain for `### Complexity`. +# /idd-verify falsified that with the real corpus: 93% of the 159 diagnoses in +# this repo write the tier followed by same-line rationale, so a closed domain +# would have rejected 42% of them. Round 2 (/idd-diagnose #316, corpus 158/158, +# 0 false positives) replaced it with the rule under test here: # -# TWO CONTRACTS under test (design.md → Implementation Contract): # idd_parse_complexity -# stdout : canonical tier — Simple | Plan | Spectra | SDD-warranted -# exit 0 : in domain (bare tier, or tier + " via ") -# exit 3 : section present, value out of domain → stderr names the raw value -# exit 4 : no `### Complexity` section at all +# strip markdown decoration → value must BEGIN WITH one of +# Simple | Plan | Spectra | SDD-warranted (longest match first) +# then scan the ENTIRE value for deferral vocabulary +# when triggered | parking lot | deferred | 暫緩 (case-insensitive) +# stdout : the leading tier (exit 0 only) +# exit 0 : routable +# exit 3 : section present, value does not begin with a tier +# → stderr "unparseable-complexity: " +# exit 4 : no `### Complexity` section (code fences are NOT sections) +# → stderr "missing-complexity" +# exit 5 : tier is valid but deferral vocabulary is present +# → stderr "deferral-marker: " # idd_actionability_verdict --complexity-exit N --parking-label yes|no --blocking-section yes|no # stdout : "actionable" | "not-actionable: [; ...]" -# exit 0 : actionable exit 1 : not actionable -# reason vocabulary is CLOSED (four values): -# complexity-unparseable | complexity-missing | parking-lot-label | blocking-nonempty +# exit 0 : actionable exit 1 : not actionable exit 2 : bad usage +# reason vocabulary is CLOSED (five values): +# complexity-unparseable | complexity-missing | complexity-deferral-marker +# parking-lot-label | blocking-nonempty # # The `- [~]` Strategy skip marker is deliberately NOT a gate input — it is a # close-time per-item disposition owned by idd-close. Row 905 pins that. @@ -53,13 +58,31 @@ if [ -f "$LIB" ]; then HELPER_PRESENT=1 fi -# Build a Diagnosis comment body from a fixture row's complexity value. -# `null` means the row has no `### Complexity` section at all. -synth_body() { # raw_or_NULL - if [ "$1" = "__NULL__" ]; then +# Run a function with a wall-clock bound, bash-only (no coreutils `timeout`). +# A hung call is killed and reports 143, which reads as a plain assertion +# failure instead of wedging the whole suite. Needed because verify #318 H1 +# found the verdict arg loop spins forever on a value-less flag. +run_bounded() { # secs fn args... + local secs="$1"; shift + ( "$@" ) & local pid=$! + ( sleep "$secs"; kill "$pid" 2>/dev/null ) 2>/dev/null & local killer=$! + wait "$pid" 2>/dev/null; local rc=$? + kill "$killer" 2>/dev/null; wait "$killer" 2>/dev/null + return "$rc" +} + +# Build a Diagnosis comment body from a fixture row. +# __NULL__ → no `### Complexity` section at all +# fenced=1 → no real section either, but a fenced example of the template +# sits in prose (a non-fence-aware extractor would grab it) +synth_body() { # raw_or_NULL fenced + local raw="$1" fenced="${2:-0}" + if [ "$fenced" = "1" ]; then + printf '## Diagnosis\n\n### Type\n\nbug\n\n### Notes\n\nThe template looks like this:\n\n```markdown\n### Complexity\n\nSimple\n```\n\nand also:\n\n~~~\n### Complexity\n\nPlan when triggered\n~~~\n\n### Risks\n\n- none\n' + elif [ "$raw" = "__NULL__" ]; then printf '## Diagnosis\n\n### Type\n\nbug\n\n### Risks\n\n- none\n' else - printf '## Diagnosis\n\n### Type\n\nbug\n\n### Complexity\n\n%s\n\n### Risks\n\n- none\n' "$1" + printf '## Diagnosis\n\n### Type\n\nbug\n\n### Complexity\n\n%s\n\n### Risks\n\n- none\n' "$raw" fi } @@ -72,14 +95,15 @@ while IFS= read -r row; do num=$(jq -r '.number' <<<"$row") snapshot=$(jq -r '.snapshot' <<<"$row") raw=$(jq -r 'if .complexity_raw == null then "__NULL__" else .complexity_raw end' <<<"$row") + fenced=$(jq -r 'if .fenced_example == true then "1" else "0" end' <<<"$row") exp_exit=$(jq -r '.expect_parse_exit' <<<"$row") exp_tier=$(jq -r 'if .expect_tier == null then "" else .expect_tier end' <<<"$row") exp_verdict=$(jq -r '.expect_verdict' <<<"$row") exp_reasons=$(jq -r '.expect_reasons | sort | join(";")' <<<"$row") has_label=$(jq -r 'if (.labels | index("parking-lot")) then "yes" else "no" end' <<<"$row") - has_blocking=$(jq -r 'if (.blocking // "") == "" then "no" else "yes" end' <<<"$row") + blocking_src=$(jq -r '.blocking // "- (none)"' <<<"$row") - body=$(synth_body "$raw") + body=$(synth_body "$raw" "$fenced") if [ "$HELPER_PRESENT" -eq 0 ]; then fail "#$num parse exit" "$missing_helper_note" @@ -93,17 +117,35 @@ while IFS= read -r row; do tier=$(idd_parse_complexity "$body" 2>/dev/null); act_exit=$? assert_eq "#$num parse exit" "$exp_exit" "$act_exit" - if [ "$exp_exit" = "0" ]; then - assert_eq "#$num canonical tier" "$exp_tier" "$tier" - else - # out-of-domain / missing MUST surface the raw value on stderr, never a tier - err=$(idd_parse_complexity "$body" 2>&1 >/dev/null) - if [ "$raw" = "__NULL__" ]; then + err=$(idd_parse_complexity "$body" 2>&1 >/dev/null) + case "$exp_exit" in + 0) + assert_eq "#$num leading tier" "$exp_tier" "$tier" + ;; + 3) + assert_eq "#$num no tier emitted" "" "$tier" + assert_grep "#$num stderr says unparseable" "unparseable-complexity" "$err" + assert_grep "#$num stderr surfaces raw value" "$raw" "$err" + ;; + 4) + assert_eq "#$num no tier emitted" "" "$tier" assert_grep "#$num stderr names missing section" "missing-complexity" "$err" - else + ;; + 5) + # The tier prefix is well-formed here; the ONLY reason it is withheld is + # deferral vocabulary. Emitting the tier would let a consumer route on it. + assert_eq "#$num no tier emitted" "" "$tier" + assert_grep "#$num stderr says deferral" "deferral-marker" "$err" assert_grep "#$num stderr surfaces raw value" "$raw" "$err" - fi - fi + ;; + esac + + # ── contract 3: the Blocking signal is read through the helper, never by + # a private awk — a missing section and idd-update's `- (none)` placeholder + # are both "no" ── + issue_body=$(printf '## Current Status\n\n### Phase\n\ndiagnosed\n\n### Blocking\n%s\n\n### Tasks\n\n- [ ] x\n' "$blocking_src") + block_line=$(idd_blocking_section "$issue_body") + if [ -n "$block_line" ]; then has_blocking=yes; else has_blocking=no; fi # ── contract 2: verdict ── out=$(idd_actionability_verdict \ @@ -122,11 +164,59 @@ while IFS= read -r row; do [ "$exp_verdict" = "actionable" ] && [ "$snapshot" = "true" ] && ACTIONABLE_SNAPSHOT+=("$num") done <<<"$ROWS" -# ── audit discipline: the cheap path must not be the unsafe one ────────────── -# A gate that treated an unanswered signal as "clear" would re-open the hole -# #298 closed, so every malformed invocation fails loud (exit 2) instead of -# defaulting to actionable. if [ "$HELPER_PRESENT" -eq 1 ]; then + # ── section extraction: fences and heading levels ────────────────────────── + # A real section followed by a fenced copy of the template: the real one wins, + # and the deferral vocabulary inside the fence must not leak into the scan. + body=$'## Diagnosis\n\n### Complexity\n\nPlan\n\n### Notes\n\n```\n### Complexity\n\nSimple when triggered\n```\n' + tier=$(idd_parse_complexity "$body" 2>/dev/null); rc=$? + assert_exit "real section beats fenced copy (exit)" "0" "$rc" + assert_eq "real section beats fenced copy (tier)" "Plan" "$tier" + + # A higher-level heading ends the section, so deferral text in the NEXT + # section is not attributed to Complexity. + body=$'## Diagnosis\n\n### Complexity\n\nSpectra\n\n## Next steps\n\nRevisit when triggered.\n' + tier=$(idd_parse_complexity "$body" 2>/dev/null); rc=$? + assert_exit "higher heading ends section (exit)" "0" "$rc" + assert_eq "higher heading ends section (tier)" "Spectra" "$tier" + + # Longest match first: `SDD-warranted` must not be read as a non-tier because + # no shorter tier is its prefix — and `Simple` must not match `Simpler`. + body=$'### Complexity\n\nSDD-warranted（legacy alias）\n' + tier=$(idd_parse_complexity "$body" 2>/dev/null); rc=$? + assert_exit "legacy alias with rationale (exit)" "0" "$rc" + assert_eq "legacy alias with rationale (tier)" "SDD-warranted" "$tier" + + body=$'### Complexity\n\nSimpler than it looks\n' + idd_parse_complexity "$body" 2>/dev/null >/dev/null + assert_exit "tier must be a whole word (Simpler ≠ Simple)" "3" "$?" + + # Deferral scan is case-insensitive and tolerant of `parking-lot` / `Parking Lot`. + body=$'### Complexity\n\nPlan — Parking-Lot until #310 lands\n' + idd_parse_complexity "$body" 2>/dev/null >/dev/null + assert_exit "deferral vocab is case/hyphen-insensitive" "5" "$?" + + body=$'### Complexity\n\nSimple（暫緩：等 #86）\n' + idd_parse_complexity "$body" 2>/dev/null >/dev/null + assert_exit "CJK deferral marker detected" "5" "$?" + + # ── contract 3: ### Blocking reader ──────────────────────────────────────── + assert_eq "blocking: real blocker → first line" "- 等 /spectra-discuss 對齊 acceptance metric proxy" \ + "$(idd_blocking_section $'## Current Status\n\n### Blocking\n- 等 /spectra-discuss 對齊 acceptance metric proxy\n- second line\n\n### Tasks\n- [ ] x')" + assert_eq "blocking: idd-update placeholder is empty" "" "$(idd_blocking_section $'### Blocking\n- (none)\n')" + assert_eq "blocking: bare (none) is empty" "" "$(idd_blocking_section $'### Blocking\n\n(none)\n')" + assert_eq "blocking: decorated none is empty" "" "$(idd_blocking_section $'### Blocking\n_none_\n')" + assert_eq "blocking: N/A is empty" "" "$(idd_blocking_section $'### Blocking\nN/A\n')" + assert_eq "blocking: absent section is empty" "" "$(idd_blocking_section $'### Type\nbug\n')" + assert_eq "blocking: fenced copy is not a section" "" "$(idd_blocking_section $'### Notes\n```\n### Blocking\n- real\n```\n')" + assert_eq "blocking: higher heading ends section" "" "$(idd_blocking_section $'### Blocking\n\n## Next\n- not a blocker\n')" + assert_eq "blocking: 'none' inside a real blocker is kept" "- none of the reviewers replied yet" \ + "$(idd_blocking_section $'### Blocking\n- none of the reviewers replied yet\n')" + + # ── audit discipline: the cheap path must not be the unsafe one ──────────── + # A gate that treated an unanswered signal as "clear" would re-open the hole + # #298 closed, so every malformed invocation fails loud (exit 2) instead of + # defaulting to actionable. idd_actionability_verdict --complexity-exit 0 --parking-label no 2>/dev/null assert_exit "missing --blocking-section fails loud" "2" "$?" @@ -139,20 +229,130 @@ if [ "$HELPER_PRESENT" -eq 1 ]; then idd_actionability_verdict --complexity-exit 9 --parking-label no --blocking-section no 2>/dev/null assert_exit "out-of-range --complexity-exit fails loud" "2" "$?" + idd_actionability_verdict --complexity-exit 5 --parking-label no --blocking-section no >/dev/null 2>&1 + assert_exit "exit 5 is an accepted --complexity-exit" "1" "$?" + idd_actionability_verdict --bogus-flag yes 2>/dev/null assert_exit "unknown flag fails loud" "2" "$?" + # verify #318 H1: a flag with no value must be a named exit-2 error, not an + # infinite loop. Each call is wall-clock bounded; a hang reports 143. + run_bounded 5 idd_actionability_verdict --parking-label no --blocking-section no --complexity-exit 2>/dev/null + assert_exit "value-less --complexity-exit fails loud (no hang)" "2" "$?" + run_bounded 5 idd_actionability_verdict --complexity-exit 0 --blocking-section no --parking-label 2>/dev/null + assert_exit "value-less --parking-label fails loud (no hang)" "2" "$?" + run_bounded 5 idd_actionability_verdict --complexity-exit 0 --parking-label no --blocking-section 2>/dev/null + assert_exit "value-less --blocking-section fails loud (no hang)" "2" "$?" + err=$(run_bounded 5 idd_actionability_verdict --complexity-exit 0 --parking-label no --blocking-section 2>&1 >/dev/null) + assert_grep "value-less flag error names the flag" "blocking-section" "$err" + # display grouping: blocking-only keeps the #84 blocked group; anything else parks - assert_eq "blocking-only → blocked group" "blocked" "$(idd_actionability_group 'blocking-nonempty')" - assert_eq "parking label → parked group" "parked" "$(idd_actionability_group 'parking-lot-label')" - assert_eq "unparseable → parked group" "parked" "$(idd_actionability_group 'complexity-unparseable')" - assert_eq "mixed reasons → parked group" "parked" "$(idd_actionability_group 'complexity-unparseable; blocking-nonempty')" + assert_eq "blocking-only → blocked group" "blocked" "$(idd_actionability_group 'blocking-nonempty')" + assert_eq "parking label → parked group" "parked" "$(idd_actionability_group 'parking-lot-label')" + assert_eq "unparseable → parked group" "parked" "$(idd_actionability_group 'complexity-unparseable')" + assert_eq "missing → parked group" "parked" "$(idd_actionability_group 'complexity-missing')" + assert_eq "deferral marker → parked group" "parked" "$(idd_actionability_group 'complexity-deferral-marker')" + assert_eq "mixed reasons → parked group" "parked" "$(idd_actionability_group 'complexity-unparseable; blocking-nonempty')" + + # ── task 6.4: the documented call shape survives `set -euo pipefail` ─────── + # Consumers run under strict mode. A bare `TIER=$(idd_parse_complexity …)` + # would abort the whole listing on the first non-routable issue; the + # conditional-capture shape must instead yield the exit code as data. + strict_out=$(bash -euo pipefail -c ' + . "$1" + body=$(printf "### Complexity\n\nSimple when triggered\n") + if TIER=$(idd_parse_complexity "$body" 2>/dev/null); then CEXIT=0; else CEXIT=$?; fi + if VERDICT=$(idd_actionability_verdict --complexity-exit "$CEXIT" --parking-label no --blocking-section no 2>/dev/null); then VEXIT=0; else VEXIT=$?; fi + printf "%s|%s|%s|%s\n" "$CEXIT" "${TIER:-}" "$VEXIT" "$VERDICT" + echo still-running + ' _ "$LIB" 2>/dev/null); strict_rc=$? + assert_exit "strict-mode caller is not aborted" "0" "$strict_rc" + assert_eq "strict-mode capture yields exit 5 as data" "5||1|not-actionable: complexity-deferral-marker" "$(printf '%s' "$strict_out" | head -1)" + assert_grep "strict-mode caller continues past the gate" "still-running" "$strict_out" +fi + +# ── consumer wiring drift guard (tasks 6.4 / 7.1 / 7.2 / 9.1 / 9.2) ───────── +# Round 1 shipped a green gate that no consumer called. These greps pin the +# canonical call shape into the four SKILL.md files so it cannot silently +# regress, and pin the #84 display strings idd-list must keep verbatim. +SKILLS="$HERE/../../../skills" +REF="$HERE/../../../references/actionability-gate.md" +for c in idd-list idd-all idd-implement idd-plan; do + f="$SKILLS/$c/SKILL.md" + assert_output_grep "$c: sources the shared helper" 'scripts/lib/actionability.sh' "$f" + assert_output_grep "$c: fails loud when helper is missing" 'FATAL: missing $CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh' "$f" + assert_output_grep "$c: actually calls the verdict" 'idd_actionability_verdict --complexity-exit "$CEXIT" --parking-label "$HAS_PARKING" --blocking-section "$BLOCKING"' "$f" + assert_output_grep "$c: reads ### Blocking through the helper" 'idd_blocking_section' "$f" + assert_output_grep "$c: set -e safe conditional capture" 'if TIER=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>/dev/null); then CEXIT=0; else CEXIT=$?; fi' "$f" + assert_output_grep "$c: paginates the comments fetch" '/comments" --paginate --jq' "$f" + refute_output_grep "$c: no truncating --json comments fetch for the diagnosis" 'LATEST_DIAGNOSIS=$(gh issue view' "$f" + refute_output_grep "$c: no closed-domain wording for the tier field" '封閉值域外' "$f" + refute_output_grep "$c: no 'closed domain, no fifth value' tier claim" '不得依相似性外推第五個' "$f" +done +# #84 surface preserved verbatim (spec R6) +L="$SKILLS/idd-list/SKILL.md" +assert_output_grep "idd-list: #84 blocked group heading verbatim" 'Blocked (waiting on external):' "$L" +assert_output_grep "idd-list: #84 all-blocked banner verbatim" '✋ 所有可控事項已完成 — N 個 open issue 全部等待外部回應（詳見上表 blocker）。' "$L" +assert_output_grep "idd-list: #84 footer count verbatim" '`X actionable, Y blocked`' "$L" +assert_output_grep "idd-list: parked group present" 'Parked (not routable now):' "$L" +assert_output_grep "idd-list: groups via the helper" 'idd_actionability_group "$REASONS"' "$L" +# reference + producer (9.1 / 9.2) +assert_output_grep "reference: cites the 159-diagnosis corpus" '159' "$REF" +assert_output_grep "reference: five-value reason vocabulary" 'complexity-deferral-marker' "$REF" +assert_output_grep "reference: exit 5 documented" 'deferral-marker: /dev/null); rc=$? + case "$rc" in 0) c0=$((c0 + 1)) ;; 3) c3=$((c3 + 1)) ;; 4) c4=$((c4 + 1)) ;; 5) c5=$((c5 + 1)) ;; esac + if [ "$rc" = "$exp_exit" ] && [ "$tier" = "$exp_tier" ]; then + c_ok=$((c_ok + 1)) + else + fail "corpus #$num" "expected exit $exp_exit tier '$exp_tier'; got exit $rc tier '$tier' — raw: $raw" + fi + done < <(jq -c '.rows[]' "$CORPUS") + assert_eq "corpus: every diagnosis routes as reviewed ($c_ok/$c_total)" "$c_total" "$c_ok" + assert_eq "corpus: 159 diagnoses in the frozen snapshot" "159" "$c_total" + assert_eq "corpus: exit distribution routable/unparseable/missing/deferral" "149/0/1/9" "$c0/$c3/$c4/$c5" +elif [ "$HELPER_PRESENT" -eq 1 ]; then + fail "corpus regression" "fixture missing: $CORPUS" fi # ── acceptance criterion (design.md): among the nine 2026-08-10 snapshot rows, -# exactly #37 is actionable. This is the regression of the actual incident. ── +# #37 is actionable — and so is #128, whose deferral lived only in Strategy +# prose (no marker, no label, no Blocking). #128 is the DESIGNED miss: the +# gate does not parse prose, and the parking-lot label is the human backstop. +# Pinning it here keeps the fixture honest instead of hypothesis-confirming. ── snap_count=$(jq '[.[] | select(.snapshot)] | length' "$FIXTURE") assert_eq "fixture carries the 9 snapshot rows" "9" "$snap_count" -assert_eq "only #37 actionable among snapshot" "37" "$(printf '%s' "${ACTIONABLE_SNAPSHOT[*]:-}")" +assert_eq "snapshot actionable = #37 + #128 (documented prose-deferral miss)" "37 128" "$(printf '%s' "${ACTIONABLE_SNAPSHOT[*]:-}")" + +# spec R8 scenario: the fixture reflects real shapes, ≥3 each. Shape is judged +# on the raw value; deferral rows are counted by expected exit. +n_bare=$(jq '[.[] | select(.complexity_raw != null) | select(.complexity_raw | test("^(Simple|Plan|Spectra|SDD-warranted)$"))] | length' "$FIXTURE") +n_deco=$(jq '[.[] | select(.complexity_raw != null) | select(.complexity_raw | test("^[*`_]"))] | length' "$FIXTURE") +n_rat=$(jq '[.[] | select(.complexity_raw != null) | select(.expect_parse_exit == 0) | select(.complexity_raw | test("^(Simple|Plan|Spectra|SDD-warranted)$") | not) | select(.complexity_raw | test("^[*`_]") | not)] | length' "$FIXTURE") +n_def=$(jq '[.[] | select(.expect_parse_exit == 5)] | length' "$FIXTURE") +assert_true "≥3 bare-tier rows ($n_bare)" "[ $n_bare -ge 3 ]" +assert_true "≥3 decorated-tier rows ($n_deco)" "[ $n_deco -ge 3 ]" +assert_true "≥3 tier+rationale rows ($n_rat)" "[ $n_rat -ge 3 ]" +assert_true "≥3 deferral-vocabulary rows ($n_def)" "[ $n_def -ge 3 ]" print_summary "actionability-gate" diff --git a/plugins/issue-driven-dev/skills/idd-all/SKILL.md b/plugins/issue-driven-dev/skills/idd-all/SKILL.md index 574be20..266ee4e 100644 --- a/plugins/issue-driven-dev/skills/idd-all/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-all/SKILL.md @@ -511,40 +511,59 @@ idd-all 必須把 `--cwd "$CWD"` 傳給 idd-diagnose,否則 sub-skill 會在 Cla Skill(skill="issue-driven-dev:idd-diagnose", args="#$N --cwd $CWD") ``` -**讀回 complexity**:idd-diagnose 結束後 fetch issue comments,取最新 `## Diagnosis` 區塊的 body,**值域判定不在此處自行寫 regex**,改呼叫 [`references/actionability-gate.md`](../../references/actionability-gate.md) 契約下的共用實作: +**讀回 complexity 並過 actionability gate**:idd-diagnose 結束後抓最新 `## Diagnosis` comment、labels 與 body 的 `### Blocking`,**tier 抽取與可動性判定都不在此處自行寫**,改呼叫 [`references/actionability-gate.md`](../../references/actionability-gate.md) 契約下的共用實作: ```bash -LATEST_DIAGNOSIS=$(gh issue view "$N" --json comments \ - | python3 -c " -import json, sys, re -d = json.load(sys.stdin) -diagnosis_comments = [c for c in d['comments'] if re.search(r'(?m)^## Diagnosis', c['body'])] # v2.68.0+ #59 — line-anchored regex avoids quoted/inline false-positives (mirrors check-diagnosis-readiness.sh) -print(diagnosis_comments[-1]['body'] if diagnosis_comments else '') -") - -# 缺 helper 一律 fail loud + 指名 path,禁止 fallback 到私有 regex(契約 §Consumer contract) +# 缺 helper 一律 fail loud + 指名 path，禁止 fallback 到私有 regex（契約 §Consumer contract） . "$CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh" || { echo "FATAL: missing $CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh — 不得改用私有 regex" >&2 exit 1 } -TIER=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>/dev/null); CEXIT=$? -COMPLEXITY_ERR=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>&1 >/dev/null) # cexit≠0 時的 `unparseable-complexity: ` / `missing-complexity` +# 1. 最新 Diagnosis comment —— 必須分頁。`gh issue view --json comments` 只回最舊的 100 則， +# issue 一長，最新的 diagnosis 正好是被丟掉的那一則（#295 同族；`--paginate --jq` 每頁一個 array，`jq -s add` 收攏）。 +LATEST_DIAGNOSIS=$(gh api "repos/$GITHUB_REPO/issues/$N/comments" --paginate --jq '[.[] | {body}]' \ + | jq -s 'add // []' \ + | python3 -c ' +import json, sys, re +cs = json.load(sys.stdin) +ds = [c for c in cs if re.search(r"(?m)^## Diagnosis", c["body"])] # line-anchored，引述/inline 不算（v2.68.0+ #59） +print(ds[-1]["body"] if ds else "")') + +# 2. 另外兩個訊號：labels，與 body 的 ### Blocking（經 helper 讀；idd-update 的 `- (none)` placeholder 算空） +ISSUE_JSON=$(gh issue view "$N" --repo "$GITHUB_REPO" --json labels,body) +HAS_PARKING=$(jq -r 'if any(.labels[]; .name == "parking-lot") then "yes" else "no" end' <<<"$ISSUE_JSON") +BLOCK_LINE=$(idd_blocking_section "$(jq -r '.body // ""' <<<"$ISSUE_JSON")") +if [ -n "$BLOCK_LINE" ]; then BLOCKING=yes; else BLOCKING=no; fi + +# 3. 條件式捕捉 —— `set -euo pipefail` 下唯一不會被 exit 3/4/5 終止的寫法（verify #318 HIGH） +if TIER=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>/dev/null); then CEXIT=0; else CEXIT=$?; fi +COMPLEXITY_ERR=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>&1 >/dev/null) || true # 3/5 回 `: <原值>`、4 回 `missing-complexity` + +# 4. 真的呼叫 gate。exit 2 是 API 誤用（本 skill 的 bug），不得與 not-actionable 混同 +if VERDICT=$(idd_actionability_verdict --complexity-exit "$CEXIT" --parking-label "$HAS_PARKING" --blocking-section "$BLOCKING" 2>&1); then VEXIT=0; else VEXIT=$?; fi +case "$VEXIT" in + 0) ;; # actionable → 依下表以 $TIER 分派 + 1) REASONS="${VERDICT#not-actionable: }" ;; # withheld → 下表 `VEXIT=1` 各列；不給任何 lifecycle 命令 + *) echo "FATAL: idd_actionability_verdict misuse — $VERDICT" >&2; exit 1 ;; +esac ``` -Dispatch 以 `(CEXIT, TIER)` 為鍵,**四列 exit 0 的 tier 是封閉值域,不得依相似性外推第五個**: +Dispatch **先看 `$VEXIT`**(gate 判定),`0` 才依 `$TIER` 分派。tier 只有四個(`SDD-warranted` 視同 `Spectra`);`### Complexity` 開頭以外的同行理由、裝飾、` via <來源>` 後綴都不影響 `$TIER`: | `CEXIT` · `TIER` | 下一步 | |--------------|--------| | `0` · `Simple` | Phase 3a: idd-implement | | `0` · `Plan` | **attended → Phase 3p: `/idd-plan`**（該 skill 擁有 `EnterPlanMode` 閘門，approve 後自己 chain 到 idd-implement）;**unattended → Phase 3a: idd-implement**，並在 final report 標記 `[Plan tier deliberation skipped under unattended mode]` | -| `0` · `Plan`（原值 `Plan via Layer V`,v2.50+）| 同上 — helper 已剝除 ` via <來源>` 後綴,verdict 是 user 在 idd-diagnose Step 3.4 選 escalate 觸發,routing 行為跟 bare `Plan` 一致 | +| `0` · `Plan`（原值 `Plan via Layer V`,v2.50+）| 同上 — helper 只取開頭的 tier,` via <來源>` 後綴與同行理由皆不影響;verdict 是 user 在 idd-diagnose Step 3.4 選 escalate 觸發,routing 行為跟 bare `Plan` 一致 | | `0` · `Spectra` | Phase 3b: spectra-discuss → spectra-propose → spectra-apply(unattended → 一輪收斂;attended → multi-turn 對話自然進行) | | `0` · `SDD-warranted` (legacy alias) | 視同 `Spectra` 處理(v2.36.0+ backward compat) | -| `4` — 無 `### Complexity` 區段（含完全沒有 `## Diagnosis` comment）| **abort** — diagnose 沒判定 complexity,user 需手動釐清（即舊表的 `UNKNOWN` 列,語意不變）| -| `3` — 值落在封閉值域外（如 `Simple when triggered`）| **abort** — 印出 `$COMPLEXITY_ERR` 的 `unparseable-complexity: ` **原值**,要求 user 修正 Diagnosis,或把延期狀態改掛 `parking-lot` label。**禁止**截斷成 tier 前綴、**禁止**降級成 `Plan` 或任何其他 tier | +| `VEXIT=1` · `$REASONS` 含 `complexity-deferral-marker`(如 `Simple when triggered`、`**Spectra**(… if/when triggered)`)或 `parking-lot-label` | **abort(parked)** — 印出 `$REASONS` 與原文(`$COMPLEXITY_ERR` 的 `deferral-marker: <原值>`,或 label 名)。這是**合法的延期狀態,不是資料錯誤**:不要求 user「修正」Diagnosis;要動它,先由人移除 label 或重新 diagnose。**禁止**截斷成 tier 前綴、**禁止**降級成任何 tier、**禁止**因為 tier 前綴合法就分派 | +| `VEXIT=1` · `$REASONS` 含 `blocking-nonempty` | **abort(blocked)** — 印出 `$BLOCK_LINE`;等 blocker 解除(`idd-update` 清 `### Blocking`)| +| `VEXIT=1` · `complexity-unparseable`(值不以 tier 開頭,如 `移入 discussion list`)| **abort** — 印出 `$COMPLEXITY_ERR` 的 `unparseable-complexity: <原值>`,要求 user 修正 Diagnosis(這才是資料錯誤)| +| `VEXIT=1` · `complexity-missing`(無 `### Complexity` 區段,含完全沒有 `## Diagnosis` comment)| **abort** — diagnose 沒判定 complexity,user 需手動釐清(即舊表的 `UNKNOWN` 列,語意不變)| -> **為何不在此處寫 regex（#298 → #316）**：本段原本就地用一條 `(.+?)` 窄化抓 `### Complexity` 標題下的整行，再自行 `split(' via ')` 取 canonical tier。那條 regex 對 `Simple when triggered` 這類**帶延期修飾語**的值會**匹配成功**，回傳一個非 tier 字串——它對不上任何 dispatch 列，卻也不是 `UNKNOWN`。舊表的 `UNKNOWN → abort` 安全網結構上接不住它：`UNKNOWN` 只在 regex **完全匹配失敗**時才產生（`if m else` 分支），值域外的**成功**匹配永遠落不進那一格，routing 因此進入未定義行為。修法不是把 regex 寫得更嚴——那只會讓第四份私有窄化加入既有的三方分歧——而是讓值域判定只剩一份實作：` via <來源>` 後綴剝除、封閉值域檢查、原值 surface 全在 `scripts/lib/actionability.sh`，本 skill 只讀它的 exit code。「不得截斷、不得降級、不得靜默」的規定見 [`references/actionability-gate.md`](../../references/actionability-gate.md)。 +> **為何不在此處寫 regex（#298 → #316）**：本段原本就地用一條 `(.+?)` 窄化抓 `### Complexity` 標題下的整行，再自行 `split(' via ')` 取 canonical tier。那條 regex 對 `Simple when triggered` 這類**帶延期修飾語**的值會**匹配成功**，回傳一個非 tier 字串——它對不上任何 dispatch 列，卻也不是 `UNKNOWN`。舊表的 `UNKNOWN → abort` 安全網結構上接不住它：`UNKNOWN` 只在 regex **完全匹配失敗**時才產生（`if m else` 分支），值域外的**成功**匹配永遠落不進那一格，routing 因此進入未定義行為。修法不是把 regex 寫得更嚴——那只會讓第四份私有窄化加入既有的三方分歧——而是讓判定只剩一份實作：tier 前綴抽取、延期語彙偵測、`### Blocking` 讀取、三訊號 gate、原值 surface 全在 `scripts/lib/actionability.sh`，本 skill 只讀它的 exit code。**只換 parser 不呼叫 verdict 等於沒修**——第 1 輪（PR #318）正是如此：gate 完整、66 測試全綠、零 consumer 呼叫（verify CRITICAL-1）。「不得截斷、不得降級、不得靜默」的規定見 [`references/actionability-gate.md`](../../references/actionability-gate.md)。 > **Layer V under (PR, unattended) — v2.50+**: Layer V Vagueness Pre-check (idd-diagnose Step 3.4) 在 unattended 仍評分 + 寫 audit trail,但 trigger 時自動 apply `proceed anyway` 不跳 AskUserQuestion。final report 應 surface `idd-diagnose` audit trail 中含 `[Layer V: V1=N V4=M, clarify-default skipped under unattended mode, defaulting to proceed]` 的 issue,讓 user 後續可以手動重 route。 > @@ -619,10 +638,7 @@ command -v spectra >/dev/null 2>&1 || abort "Spectra tier routed but spectra CLI ```bash ISSUE_TITLE=$(gh issue view "$N" --repo "$GITHUB_REPO" --json title -q .title) ISSUE_BODY=$(gh issue view "$N" --repo "$GITHUB_REPO" --json body -q .body | head -50) -DIAGNOSIS=$(gh issue view "$N" --repo "$GITHUB_REPO" --json comments \ - | python3 -c "import json,sys,re; cs=json.load(sys.stdin)['comments']; \ - ds=[c for c in cs if re.search(r'(?m)^## Diagnosis', c['body'])]; \ - print(ds[-1]['body'] if ds else '')") # v2.68.0+ #59 — line-anchored regex avoids quoted/inline false-positives +DIAGNOSIS="$LATEST_DIAGNOSIS" # Phase 2 已分頁抓過最新 Diagnosis（`--json comments` 只回最舊 100 則,不得在此重抓） ``` #### Step 3b.2: Discuss @@ -1026,7 +1042,7 @@ fi | Issue #N 不存在 / CLOSED | Phase 0 abort | | Branch 已存在 | Phase 0 AskUserQuestion(checkout / -2 suffix / abort) | | Diagnosis 缺 `### Complexity` 區段(helper cexit=4) | Phase 2 abort,提示手動跑 idd-diagnose | -| `### Complexity` 值落在封閉值域外(helper cexit=3) | Phase 2 abort,印出 `unparseable-complexity: ` 原值;不截斷、不降級成任何 tier | +| actionability gate 判 not-actionable(`VEXIT=1`:`### Complexity` 不可路由 exit 3/4/5、`parking-lot` label、`### Blocking` 非空)| Phase 2 abort,印出 `$REASONS` 與原文(`$COMPLEXITY_ERR` / label 名 / `$BLOCK_LINE`);不截斷、不降級成任何 tier;`complexity-deferral-marker` / `parking-lot-label` 是合法延期狀態,不要求「修正」| | spectra-discuss 沒 emit `Conclusion:` line(unattended hint 失敗)| Re-prompt 一次;再失敗 abort,branch 保留 | | spectra-propose 沒 emit `Change:` line | 同上 | | spectra-propose 遇到 unrecoverable validation error | Phase 3b abort,artifacts 保留,提示手動 `/spectra-propose` | diff --git a/plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md b/plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md index 326960c..ed5bfb4 100644 --- a/plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md @@ -608,22 +608,15 @@ Diagnosis 完成 + Step 3.4 Vagueness Pre-check 結束後（`type=meeting` 已 {對 Spectra：列出 Layer 2 + Layer 3 觸發項} ``` -##### 值域是封閉的（#298 → #316） +##### 寫法：tier 寫清楚、延期貼 label（#298 → #316，第 2 輪修訂） -**`### Complexity` 的第一個非空行只得是下列四個值之一 —— 這是封閉列舉，不得依相似性類推出第五個值：** +**第一個非空行必須以四個 tier 之一開頭** —— `Simple` / `Plan` / `Spectra` / `SDD-warranted`（`Spectra` 的 backward-compat alias）。開頭那個字就是 consumer 讀到的 tier；**其後的同行理由、括號說明、markdown 裝飾、` via <來源>` provenance 後綴（`Plan via Layer V`、`Spectra via hard-gate (sdd_bias)`）皆為合法**，consumer 不會因此拒絕。本 repo 159 筆真實 diagnosis 有 71.7% 不是裸 tier —— 那是常態寫法，不是違規；第 1 輪曾把它們宣告為「封閉值域外」而全數擋下（PR #318 verify CRITICAL-2，66 筆本該路由的 issue 變 hard abort），已撤回。 -1. `Simple` -2. `Plan` -3. `Spectra` -4. `SDD-warranted`（`Spectra` 的既有 backward-compat alias） +**延期意圖不要寫進這個欄位，改貼 `parking-lot` label。** consumer 會對整行掃 `when triggered` / `parking lot` / `deferred` / `暫緩` 這組保守語彙，命中即以 `complexity-deferral-marker` 擋下 —— 這是為 159 筆歷史語料留的安全網（9 筆命中、0 誤報），不是給新 diagnosis 用的表達方式；漏抓時 label 是兜底，誤抓則是對可動 issue 的 hard stop，所以語彙刻意保守。理由是生命週期不同：Diagnosis comment 是 **append-only** 審計軌跡（見 [`rules/append-vs-modify.md`](../../rules/append-vs-modify.md)），而「是否 parked」**會變**（trigger 成立就該解除）；把可變狀態凍進不可變的 artifact 正是 #298 診斷出的根因。要表達「這件事先擱著」：tier 照常寫、然後貼 label；park 的理由與 trigger 條件寫在 issue body（`idd-list --parked` 會把它印出來，#310）。 -該值**得**後接 ` via <來源>` provenance 後綴（v2.50 起的既有慣例）—— `Plan via Layer V`（Layer V escalate）與 `Spectra via hard-gate (sdd_bias)`（硬閘出口）皆為合法。canonical tier 是第一個 ` via ` 之前的文字。 +**本 skill SHALL NOT 貼、移除或推導 `parking-lot` label。** 該 label 是**人的裁決**，且可以在 diagnosis 寫完**之後**才下。實測 2026-08-10 的 11 筆 diagnosed issue，限定詞與 label 一致的只有 5 筆：`#37` 的 comment 是 `**Spectra**` 而 label 由人事後貼上；`#131` / `#200` 則有限定詞卻無 label。兩者不是同一件事的兩種寫法 —— 由 producer 從限定詞推導 label，等於取消「人可以事後 park 一個 tier 明確的 issue」這條路徑。 -**延期修飾語 SHALL NOT 寫進這個欄位。** `when triggered`、`(parking lot)`、`(deferred pending #N)`、以及任何說明「為什麼先擱著」的散文，都屬於 `parking-lot` label，不屬於這裡。理由是生命週期不同：Diagnosis comment 是 **append-only** 審計軌跡（見 [`rules/append-vs-modify.md`](../../rules/append-vs-modify.md)），而「是否 parked」**會變**（trigger 成立就該解除）。把可變狀態凍進不可變的 artifact，正是 #298 診斷出的根因 —— 實例：`#136` 的 comment 寫 bare `Spectra`、body 卻寫 `Spectra when triggered (parking lot)`，狀態改不動就自己漂到別處去了。 - -**本 skill SHALL NOT 貼、移除或推導 `parking-lot` label。** 該 label 是**人的裁決**，且可以在 diagnosis 寫完**之後**才下。實測 2026-08-10 的 11 筆 diagnosed issue，限定詞與 label 一致的只有 5 筆：`#37` 是 bare `Spectra` 而 label 由人事後貼上；`#131` / `#200` 則有限定詞卻無 label。兩者不是同一件事的兩種寫法 —— 由 producer 從限定詞推導 label，等於取消「人可以事後 park 一個 tier 明確的 issue」這條路徑。 - -> 完整契約（含 consumer 端的保守處置與 surface 規定）見 [`references/actionability-gate.md`](../../references/actionability-gate.md)。想表達「這件事先擱著」時，寫清楚 tier、然後貼 label。 +> 完整契約（抽取規則、exit code、五值 reason 值域、consumer 端的保守處置與 surface 規定、159 筆 corpus 回歸）見 [`references/actionability-gate.md`](../../references/actionability-gate.md)。 #### 各 verdict 的 Next Step diff --git a/plugins/issue-driven-dev/skills/idd-implement/SKILL.md b/plugins/issue-driven-dev/skills/idd-implement/SKILL.md index 001d13b..425922f 100644 --- a/plugins/issue-driven-dev/skills/idd-implement/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-implement/SKILL.md @@ -364,30 +364,47 @@ bash "$CLAUDE_PLUGIN_ROOT/scripts/gh-egress.sh" comment $NUMBER --repo $GITHUB_R ### Step 2.5: Bootstrap TodoList（non-Spectra case） -**判斷 Complexity routing**：讀最新 `## Diagnosis` comment 的 `### Complexity` 欄位（v2.36.0+ 三路；v2.50+ 加 Layer V variant）。**值域判定不在此處自行寫 parser**，改呼叫 [`references/actionability-gate.md`](../../references/actionability-gate.md) 契約下的共用實作： +**判斷 Complexity routing**：讀最新 `## Diagnosis` comment 的 `### Complexity` 欄位（v2.36.0+ 三路；v2.50+ 加 Layer V variant）。**tier 抽取與 actionability 判定都不在此處自行寫 parser**，改呼叫 [`references/actionability-gate.md`](../../references/actionability-gate.md) 契約下的共用實作： ```bash -LATEST_DIAGNOSIS=$(gh issue view "$NUMBER" --repo "$GITHUB_REPO" --json comments \ - | python3 -c " -import json, sys, re -d = json.load(sys.stdin) -diagnosis_comments = [c for c in d['comments'] if re.search(r'(?m)^## Diagnosis', c['body'])] -print(diagnosis_comments[-1]['body'] if diagnosis_comments else '') -") - -# 缺 helper 一律 fail loud + 指名 path，禁止 fallback 到私有 parser（契約 §Consumer contract） +# 缺 helper 一律 fail loud + 指名 path，禁止 fallback 到私有 regex（契約 §Consumer contract） . "$CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh" || { - echo "FATAL: missing $CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh — 不得改用私有 parser" >&2 + echo "FATAL: missing $CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh — 不得改用私有 regex" >&2 exit 1 } -TIER=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>/dev/null); CEXIT=$? -COMPLEXITY_ERR=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>&1 >/dev/null) # cexit≠0 時的 `unparseable-complexity: ` / `missing-complexity` +# 1. 最新 Diagnosis comment —— 必須分頁。`gh issue view --json comments` 只回最舊的 100 則， +# issue 一長，最新的 diagnosis 正好是被丟掉的那一則（#295 同族；`--paginate --jq` 每頁一個 array，`jq -s add` 收攏）。 +LATEST_DIAGNOSIS=$(gh api "repos/$GITHUB_REPO/issues/$NUMBER/comments" --paginate --jq '[.[] | {body}]' \ + | jq -s 'add // []' \ + | python3 -c ' +import json, sys, re +cs = json.load(sys.stdin) +ds = [c for c in cs if re.search(r"(?m)^## Diagnosis", c["body"])] # line-anchored，引述/inline 不算（v2.68.0+ #59） +print(ds[-1]["body"] if ds else "")') + +# 2. 另外兩個訊號：labels，與 body 的 ### Blocking（經 helper 讀；idd-update 的 `- (none)` placeholder 算空） +ISSUE_JSON=$(gh issue view "$NUMBER" --repo "$GITHUB_REPO" --json labels,body) +HAS_PARKING=$(jq -r 'if any(.labels[]; .name == "parking-lot") then "yes" else "no" end' <<<"$ISSUE_JSON") +BLOCK_LINE=$(idd_blocking_section "$(jq -r '.body // ""' <<<"$ISSUE_JSON")") +if [ -n "$BLOCK_LINE" ]; then BLOCKING=yes; else BLOCKING=no; fi + +# 3. 條件式捕捉 —— `set -euo pipefail` 下唯一不會被 exit 3/4/5 終止的寫法（verify #318 HIGH） +if TIER=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>/dev/null); then CEXIT=0; else CEXIT=$?; fi +COMPLEXITY_ERR=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>&1 >/dev/null) || true # 3/5 回 `: <原值>`、4 回 `missing-complexity` + +# 4. 真的呼叫 gate。exit 2 是 API 誤用（本 skill 的 bug），不得與 not-actionable 混同 +if VERDICT=$(idd_actionability_verdict --complexity-exit "$CEXIT" --parking-label "$HAS_PARKING" --blocking-section "$BLOCKING" 2>&1); then VEXIT=0; else VEXIT=$?; fi +case "$VEXIT" in + 0) ;; # actionable → 依下表以 $TIER 分派 + 1) REASONS="${VERDICT#not-actionable: }" ;; # withheld → 下表 `VEXIT=1` 各列；不給任何 lifecycle 命令 + *) echo "FATAL: idd_actionability_verdict misuse — $VERDICT" >&2; exit 1 ;; +esac ``` -` via <來源>` 後綴（例如 `Plan via Layer V`）由 helper 剝除，本 skill 拿到的 `$TIER` 已是 canonical tier — 對應 spec Requirement: Routing parsers SHALL recognize Plan via Layer V verdict。 +helper 只取開頭的 tier：` via <來源>` 後綴（例如 `Plan via Layer V`）、同行理由、markdown 裝飾都不影響，本 skill 拿到的 `$TIER` 已是 canonical tier — 對應 spec Requirement: Routing parsers SHALL recognize Plan via Layer V verdict。 -Routing 以 `(CEXIT, TIER)` 為鍵，**exit 0 的四個 tier 是封閉值域，不得依相似性外推第五個**： +Routing **先看 `$VEXIT`**（gate 判定），`0` 才依 `$TIER` 決定行為。tier 只有四個： | `CEXIT` · `TIER` | 行為 | |-----------|------| @@ -395,10 +412,12 @@ Routing 以 `(CEXIT, TIER)` 為鍵，**exit 0 的四個 tier 是封閉值域， | `0` · `Plan`（原值可能是 `Plan via Layer V`）| ✅ 同 Simple — TaskList 啟動。**注意**：使用者通常透過 `/idd-plan #NNN` 呼叫進來，approval gate 已在 idd-plan 處理完，本 skill 直接走 TDD loop。若使用者直接呼叫 `/idd-implement` 而 Complexity=Plan，**先提示**「Complexity 判定為 Plan，建議改走 `/idd-plan #NNN` 進入 approval gate；繼續直接 implement 等於跳過 Plan tier 的 deliberation 價值」並用 AskUserQuestion 確認 continue/abort。`Plan via Layer V` 同樣行為(routing 一致),只是 verdict 標記提示這是 Layer V 觸發 | | `0` · `Spectra` | ⏭ 跳過本 step（由 `spectra-apply` 管 `openspec/changes//tasks.md`）| | `0` · `SDD-warranted` (legacy alias) | ⏭ 跳過本 step — 視同 `Spectra` 處理（v2.36.0+ backward compat）| -| `3` — 值落在封閉值域外（如 `Simple when triggered`）| 🛑 **停止實作** — 印出 `$COMPLEXITY_ERR` 的 `unparseable-complexity: ` **原值**，要求 user 修正 Diagnosis，或把延期狀態改掛 `parking-lot` label。**禁止**截斷成 tier 前綴、**禁止**降級成 `Simple` / `Plan` 或任何其他 tier、**禁止**沿用舊的「不確定就當 Simple」預設 | -| `4` — 無 `### Complexity` 區段（含完全沒有 `## Diagnosis` comment）| 🛑 **停止實作** — 印出 `missing-complexity`，提示先跑 `/idd-diagnose #$NUMBER` 判定 complexity。同樣不得代 user 挑一個 tier | +| `VEXIT=1` · `$REASONS` 含 `complexity-deferral-marker`（如 `Simple when triggered`）或 `parking-lot-label` | 🛑 **停止實作（parked）** — 印出 `$REASONS` 與原文（`$COMPLEXITY_ERR` 的 `deferral-marker: <原值>`，或 label 名）。這是**合法的延期狀態，不是資料錯誤**；要動它，先由人移除 label 或重新 diagnose。**禁止**截斷成 tier 前綴、**禁止**降級成 `Simple` / `Plan` 或任何其他 tier、**禁止**沿用舊的「不確定就當 Simple」預設 | +| `VEXIT=1` · `$REASONS` 含 `blocking-nonempty` | 🛑 **停止實作（blocked）** — 印出 `$BLOCK_LINE`；等 blocker 解除（`idd-update` 清 `### Blocking`）| +| `VEXIT=1` · `complexity-unparseable`（值不以 tier 開頭）| 🛑 **停止實作** — 印出 `$COMPLEXITY_ERR` 的 `unparseable-complexity: <原值>`，要求 user 修正 Diagnosis（這才是資料錯誤）| +| `VEXIT=1` · `complexity-missing`（無 `### Complexity` 區段，含完全沒有 `## Diagnosis` comment）| 🛑 **停止實作** — 印出 `missing-complexity`，提示先跑 `/idd-diagnose #$NUMBER` 判定 complexity。同樣不得代 user 挑一個 tier | -> **為何不在此處自己解析（#298 → #316）**：本段原本規定就地取 `### Complexity` 標題底下那一行的原文，再以 ` via ` 分隔符切出前半當 canonical tier。那個做法對 `Simple when triggered` 這類**帶延期修飾語**的值會**成功產出**一個非 tier 字串——它對不上任何 routing 列，卻也不是「解析失敗」，只能落進舊表最後一列的 catch-all `_(missing / unclear)_ → 預設當 Simple`，把一個被人裁決延期的 issue 直接送進 TDD loop。「不確定就當 Simple」在 tier 已被寫壞時不是保守，是**代 user 挑了一個 tier**——契約明文禁止截斷、禁止降級、禁止靜默，所以該列已改為上表的 `3` / `4` 兩個停止列。修法不是把 parser 寫得更嚴——那只會讓第四份私有窄化加入既有的三方分歧——而是讓值域判定只剩一份實作：後綴剝除、封閉值域檢查、原值 surface 全在 `scripts/lib/actionability.sh`，本 skill 只讀它的 exit code。完整規定見 [`references/actionability-gate.md`](../../references/actionability-gate.md)。 +> **為何不在此處自己解析（#298 → #316）**：本段原本規定就地取 `### Complexity` 標題底下那一行的原文，再以 ` via ` 分隔符切出前半當 canonical tier。那個做法對 `Simple when triggered` 這類**帶延期修飾語**的值會**成功產出**一個非 tier 字串——它對不上任何 routing 列，卻也不是「解析失敗」，只能落進舊表最後一列的 catch-all `_(missing / unclear)_ → 預設當 Simple`，把一個被人裁決延期的 issue 直接送進 TDD loop。「不確定就當 Simple」在 tier 已被寫壞時不是保守，是**代 user 挑了一個 tier**——契約明文禁止截斷、禁止降級、禁止靜默，所以該列已改為上表的 `3` / `4` 兩個停止列。修法不是把 parser 寫得更嚴——那只會讓第四份私有窄化加入既有的三方分歧——而是讓判定只剩一份實作：tier 前綴抽取（其後理由、裝飾、` via <來源>` 後綴皆合法）、延期語彙偵測、`### Blocking` 讀取、三訊號 gate、原值 surface 全在 `scripts/lib/actionability.sh`，本 skill 只讀它的 exit code。**只換 parser 不呼叫 verdict 等於沒修**（PR #318 verify CRITICAL-1）。完整規定見 [`references/actionability-gate.md`](../../references/actionability-gate.md)。 **Simple / Plan case 執行**： diff --git a/plugins/issue-driven-dev/skills/idd-list/SKILL.md b/plugins/issue-driven-dev/skills/idd-list/SKILL.md index 12c495c..edfdf8c 100644 --- a/plugins/issue-driven-dev/skills/idd-list/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-list/SKILL.md @@ -48,9 +48,9 @@ TaskCreate(name="fetch_open_prs", description="Step 2.5 (v2.51+): gh pr list --s TaskCreate(name="fetch_discussions", description="Step 2.7 (v2.95+, #221): 僅當 --discussions flag — probe hasDiscussionsEnabled（false → 一行 skip note）→ GraphQL 抓 open discussions（first 50）→ filter（Q&A/Ideas ∧ answerChosenAt null）→ dedup（issue body 含該 URL 者剔除）→ Discussions (actionable) 區塊。query 失敗降級 skip note，絕不 abort。無 flag 時 no-op") TaskCreate(name="extract_phase", description="從每個 issue body 的 Current Status → **Phase**: 抽出 phase；fallback 掃 comments 標題推斷") TaskCreate(name="build_issue_pr_index", description="Step 3.5 (v2.51+): client-side regex `#(\d{1,7})\b` scan PR body 找 issue refs (cap digits ≤7,過濾 #0),反向建 issue→PR map + cluster detection (refs ≥ 2 → cluster,leader = min(refs);若同 issue 被多 PR ref,sort by PR number asc 確保 deterministic order;cluster_members 寫入 pr_info 僅當 len ≥ 2)") -TaskCreate(name="extract_blocked_state", description="Step 3.7 (v2.92+, #84; #298 擴充): 抽四個「現在可不可以動」訊號 —— Blocking 區塊 / blocked label / **parking-lot label** / **### Complexity 的 when-triggered 限定詞**（非裸 tier token → 保守歸 Blocked 且印出限定詞原文，不得截斷）→ blocked_reason 掛 entry") +TaskCreate(name="extract_blocked_state", description="Step 3.7 (v2.92+, #84; #298→#316 三訊號 gate): 每個 issue 呼叫共用 helper —— idd_parse_complexity（最新 Diagnosis，**分頁抓**）+ parking-lot label + idd_blocking_section（body ### Blocking）→ idd_actionability_verdict；verdict / reasons / 原值掛 entry。blocked label 是 idd-list 額外的顯示訊號，不進 gate") TaskCreate(name="format_output", description="組 #N [phase] title 表格;有 PR 加 └─ 子行 (cluster leader 顯示 cluster: #X #Y / member 顯示 → see PR #N) + footer 統計含 PR/cluster 數") -TaskCreate(name="report_and_suggest_next", description="輸出 table 並列出 Suggested next（phase × PR state matrix）；#84 分 Actionable/Blocked 兩組 + 全 blocked banner + footer 計數") +TaskCreate(name="report_and_suggest_next", description="輸出 table 並列出 Suggested next（phase × PR state matrix）；依 reason 分 Actionable / Blocked（#84，逐字保留）/ Parked（#316）三組 + 全 blocked banner + footer 計數") TaskCreate(name="audit_closes_marker", description="Step 4 (v2.75.2+, #151; 分類契約 #295): 若 --audit-closes,對 state=CLOSED 的 issue 依 scripts/check-closed-without-summary.sh 的 CLASSIFY（compliant / casing / present / mentioned / missing）分類。判準不解析 markdown：missing = 所有 comment 的原始文字裡都找不到 closing-summary heading、正規化後也找不到那兩個字（引述、fence 內、非 canonical 一律算「有」）。missing / present / mentioned 帶 ⚠（分別是：找不到 / 有 heading 但沒有 comment 以它開頭 / 有那個詞但沒認出 heading — 第三類混合了「純散文提及」與「認不出的 heading 形狀」，本工具不區分）;**只有 missing 提 --retroactive**;casing 不帶 ⚠。reuse Step 3 comment scan,不重 fetch") ``` @@ -67,7 +67,7 @@ TaskCreate(name="audit_closes_marker", description="Step 4 (v2.75.2+, #151; 分 | `--limit` | `20` | 最多顯示筆數 | | `--repo` | _(from config)_ | 覆寫 config 的 repo | | `--audit-closes` | off | 旗標：把 **CLOSED** 的 issue 依其 `## Closing Summary` marker 分類（`compliant` / `casing` / `present` / `mentioned` / `missing`，#295 + round 12）。`missing` = **所有 comment 的原始文字裡都找不到**該 heading，可能是被 commit / PR-body close keyword auto-close 繞過 `/idd-close` gate 的受害者（#151）；`present` 未經驗證、同樣帶 ⚠；`mentioned` = 找得到那兩個字但沒認出 heading（純散文提及與認不出的 heading 形狀混在一起，本工具不區分），同樣帶 ⚠；**只有 `missing` 提 `--retroactive`**，且那個提示現在只是「去讀 comment」的邀請 —— helper 已經不能批准任何事（見 `idd-close` 的「許可由讀者供給」）。`--state` 仍是預設 `open` 時隱含切到 `closed`。底層 primitive：`scripts/check-closed-without-summary.sh`（standalone / cron 可直接呼叫）| -| `--parked` | off | **回訪模式（#310）**：只列被移出視線的 issue，並把**各自的 trigger 條件原文**一併印出。三個來源：`parking-lot` label、`### Complexity` 的 `when triggered` 限定詞、`### Blocking` 區塊非空。輸出每列為 `#N title` + 縮排一行 `⏸ trigger: <原文>`；`--state` 隱含 `open`。**這不是自動化** —— parked 的 trigger 是關於未來世界狀態的散文命題，成立時不會發出任何事件，所以唯一的路徑是人回頭讀；本 flag 只是把那件事變便宜 | +| `--parked` | off | **回訪模式（#310）**：只列被移出視線的 issue，並把**各自的 trigger 條件原文**一併印出。三個來源：`parking-lot` label、`### Complexity` 帶延期語彙（helper exit 5，reason `complexity-deferral-marker`）、`### Blocking` 區塊非空。輸出每列為 `#N title` + 縮排一行 `⏸ trigger: <原文>`；`--state` 隱含 `open`。**這不是自動化** —— parked 的 trigger 是關於未來世界狀態的散文命題，成立時不會發出任何事件，所以唯一的路徑是人回頭讀；本 flag 只是把那件事變便宜 | | `--discussions` | off | **Opt-in**（#221）：同場 surface GitHub Discussions 的 actionable 項（Q&A/Ideas、未答、未被任何 issue 引用）。契約 + GraphQL 見 [`references/discussions-intake.md`](../../references/discussions-intake.md) | ### Step 2: Fetch Issues @@ -261,41 +261,70 @@ def get_leader(refs_list, body, rule): **`cluster_members` 寫入規則**:寫進 `pr_info` 僅當 `len(refs) >= 2`(single-PR 為 None)。Step 4 判定 cluster 一律以 `pr_info['cluster_members'] is not None` 為 single source of truth,避免 single-PR 判定條件有歧義(per L12 finding)。 -### Step 3.7: Blocked-state extraction（v2.92+, #84；#298 擴充為四訊號） +### Step 3.7: Actionability gate（v2.92+, #84；#298 → #316 三訊號） -對每個 issue 抽「現在可不可以動」的信號（**依 body 記錄判定，不宣稱即時**）。#84 只接上四個訊號中的一個，其餘三個 routing 讀不到 —— 實測本 repo 的 22-issue backlog，**9 條路由裡 8 條錯**，而且錯得完全看不出來（表格語法正確、格式正常、零 warning）。其中 #131 與 #200 帶著使用者親自下的 defer 裁決，照 routing 執行等於自動推翻已記錄的人為決策。 +對每個 issue 回答「現在可不可以動」（**依 body / comment 記錄判定，不宣稱即時**）。#84 只接上其中一個訊號，其餘 routing 讀不到 —— 實測本 repo 的 22-issue backlog，**9 條路由裡 8 條錯**，而且錯得完全看不出來（表格語法正確、格式正常、零 warning）。其中 #131 與 #200 帶著使用者親自下的 defer 裁決，照 routing 執行等於自動推翻已記錄的人為決策。 -**四個訊號，全部要讀（#298）**： +**三個訊號進 gate，任一成立即不可動；判定與抽取全部走共用 helper，本 skill 不自行解析任何欄位**（完整契約見 [`references/actionability-gate.md`](../../references/actionability-gate.md)）： -| 訊號 | 位置 | 判定 | -|---|---|---| -| `### Blocking` 區塊非空 | body `## Current Status` | blocked（#84 已 ship）| -| `blocked` label | labels | blocked | -| **`parking-lot` label** | labels | **parked —— first-class gate，不得路由成 actionable** | -| **`### Complexity` 帶限定詞** | 最新 Diagnosis comment | **見下** | +| 訊號 | 位置 | 讀法 | reason | +|---|---|---|---| +| `### Complexity` 不可路由 | 最新 Diagnosis comment（**分頁抓**，`--json comments` 只回最舊 100 則）| `idd_parse_complexity` exit 3 / 4 / 5 | `complexity-unparseable` / `complexity-missing` / `complexity-deferral-marker` | +| `parking-lot` label | labels | `jq` | `parking-lot-label` | +| `### Blocking` 區塊非空 | body `## Current Status` | `idd_blocking_section`（`- (none)` placeholder 算空）| `blocking-nonempty` | -**`### Complexity` 的限定詞不得被截斷**：值若不是已知 tier 的**裸 token**（`Simple` / `Plan` / `Spectra`），而是帶條件的形式 —— `Simple when triggered`、`Spectra when triggered (parking lot)`、`Plan (deferred pending #86)` —— 則： +`blocked` label（若 repo 有此慣例）與「Suggested-next 屬 wait 類」是 **idd-list 自己的顯示訊號**，只影響 Blocked 組歸類，不進 gate。 -1. **保守處置**：歸入 Blocked/Parked 組，**不**給 `→ /idd-implement` 之類的 actionable 建議； -2. **必須 surface**：在該列印出限定詞原文（如 `⏸ when triggered: ≥3 instances (目前 #1)`），不得靜默截成 tier。 +每個 issue 跑一次（`$n` 為 issue 號；本 skill 在 `set -euo pipefail` 下跑，**必須**用條件式捕捉，一筆壞值不得中斷整份 listing）： -這與 `### Conflict Class` 的既有規則對稱：值無法 parse 成已知 token 時預設最保守的類別**並把 fallback 印出來**。差別只在本欄過去連 parse 都沒做 —— 它直接取第一個像 tier 的字。 +```bash +# 缺 helper 一律 fail loud + 指名 path，禁止 fallback 到私有 regex（契約 §Consumer contract） +. "$CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh" || { + echo "FATAL: missing $CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh — 不得改用私有 regex" >&2 + exit 1 +} -> **本規則的實證來源**：2026-08-14 的 backlog 清理逐一讀了這些 issue 的**歷史**（誰在什麼脈絡下決定了什麼），才判斷得出 #131/#146/#157/#143/#145/#136 該關、#200 該留。那個判斷需要的訊息不在 label 也不在 complexity 欄位裡 —— 這正是 #37（bulk-solve autopilot）被 re-park 的理由，也是本 step 只做到「擋下誤路由」而不做「自動決定處置」的原因。 +# 1. 最新 Diagnosis comment —— 必須分頁。`gh issue view --json comments` 只回最舊的 100 則， +# issue 一長，最新的 diagnosis 正好是被丟掉的那一則（#295 同族；`--paginate --jq` 每頁一個 array，`jq -s add` 收攏）。 +LATEST_DIAGNOSIS=$(gh api "repos/$GITHUB_REPO/issues/$n/comments" --paginate --jq '[.[] | {body}]' \ + | jq -s 'add // []' \ + | python3 -c ' +import json, sys, re +cs = json.load(sys.stdin) +ds = [c for c in cs if re.search(r"(?m)^## Diagnosis", c["body"])] # line-anchored，引述/inline 不算（v2.68.0+ #59） +print(ds[-1]["body"] if ds else "")') + +# 2. 另外兩個訊號：labels，與 body 的 ### Blocking（經 helper 讀；idd-update 的 `- (none)` placeholder 算空） +ISSUE_JSON=$(gh issue view "$n" --repo "$GITHUB_REPO" --json labels,body) +HAS_PARKING=$(jq -r 'if any(.labels[]; .name == "parking-lot") then "yes" else "no" end' <<<"$ISSUE_JSON") +BLOCK_LINE=$(idd_blocking_section "$(jq -r '.body // ""' <<<"$ISSUE_JSON")") +if [ -n "$BLOCK_LINE" ]; then BLOCKING=yes; else BLOCKING=no; fi + +# 3. 條件式捕捉 —— `set -euo pipefail` 下唯一不會被 exit 3/4/5 終止的寫法（verify #318 HIGH） +if TIER=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>/dev/null); then CEXIT=0; else CEXIT=$?; fi +COMPLEXITY_ERR=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>&1 >/dev/null) || true # 3/5 回 `: <原值>`、4 回 `missing-complexity` + +# 4. 真的呼叫 gate。exit 2 是 API 誤用（本 skill 的 bug），不得與 not-actionable 混同； +# listing 語境下不 exit，改印 FATAL 行並把該 issue 標為 `(gate error)` 繼續 +if VERDICT=$(idd_actionability_verdict --complexity-exit "$CEXIT" --parking-label "$HAS_PARKING" --blocking-section "$BLOCKING" 2>&1); then VEXIT=0; else VEXIT=$?; fi +case "$VEXIT" in + 0) GROUP=actionable ;; + 1) REASONS="${VERDICT#not-actionable: }"; GROUP=$(idd_actionability_group "$REASONS") ;; # blocked | parked + *) echo "FATAL: idd_actionability_verdict misuse on #$n — $VERDICT" >&2; GROUP=error ;; +esac +``` -對每個 issue 抽 blocked 信號（**依 body 記錄判定，不宣稱即時**）： +掛到 issue entry：`group`（`actionable` / `blocked` / `parked` / `error`）、`reasons`、`tier`（僅 `VEXIT=0`）、以及要 surface 的原文 —— `$COMPLEXITY_ERR`（exit 3/5 的 `: <原值>` 整行、exit 4 的 `missing-complexity`）、`$BLOCK_LINE`（#84 的 `blocked_reason`，語意不變）、或 label 名。 -1. body `## Current Status` 的 `### Blocking` 區塊非空（首選 — idd-update 維護） -2. `blocked` label（若 repo 有此慣例） -3. Suggested-next 屬 wait 類（cluster UNKNOWN wait / 等 collaborator reply 樣式） +**不得截斷、不得降級、不得靜默**：`Simple when triggered` 的 tier 前綴 `Simple` 是合法的，helper 正因此**拒絕**在 exit 5 印出它 —— 本 skill 拿不到 tier，就不可能路由。原文一律印在該列（如 `⏸ deferral-marker: Simple when triggered`），這與 `### Conflict Class` 的既有規則對稱：值無法安全解讀時取最保守的處置**並把 fallback 印出來**。 -抽出 `blocked_reason`（Blocking 區塊首行或 label 名），掛到 issue entry。 +> **本規則的實證來源**：2026-08-14 的 backlog 清理逐一讀了這些 issue 的**歷史**（誰在什麼脈絡下決定了什麼），才判斷得出 #131/#146/#157/#143/#145/#136 該關、#200 該留。那個判斷需要的訊息不在 label 也不在 complexity 欄位裡 —— 這正是 #37（bulk-solve autopilot）被 re-park 的理由，也是本 step 只做到「擋下誤路由」而不做「自動決定處置」的原因。**#128 是設計上接受的漏抓**：它的延期只寫在 Strategy 散文，無 marker、無 label、Blocking 為空，gate 判 `Plan` 可動 —— 要擋它，由人貼 label。 ### Step 3.9: Parked review（`--parked`，v2.106+，#310） **僅當 `--parked`** 才執行；無 flag 完全 no-op。 -IDD 有三個機制會把 issue 移出視線，**沒有任何機制會把它移回來**：`parking-lot` label、`### Blocking` 區塊、`### Complexity` 的 `when triggered` 限定詞。`references/ic-r011-checkpoint.md` 原本宣稱 periodic grooming 可以 grep `blocker:*` label 來回訪 —— 實測那兩個 label **從來沒有被建立過**，而且沒有任何 periodic 機制存在（#310）。 +IDD 有三個機制會把 issue 移出視線，**沒有任何機制會把它移回來**：`parking-lot` label、`### Blocking` 區塊、`### Complexity` 帶延期語彙（Step 3.7 的 exit 5）。`references/ic-r011-checkpoint.md` 原本宣稱 periodic grooming 可以 grep `blocker:*` label 來回訪 —— 實測那兩個 label **從來沒有被建立過**，而且沒有任何 periodic 機制存在（#310）。 流程： @@ -303,7 +332,7 @@ IDD 有三個機制會把 issue 移出視線，**沒有任何機制會把它移 2. 挑出符合任一來源者 3. **抽出 trigger 條件原文**（不摘要、不改寫 —— 判斷 trigger 是否成立要看原話）： - `parking-lot` → 找 body 或 diagnosis 裡說明 park 理由的句子；找不到就印 `(no trigger recorded)`，那本身就是要修的東西 - - `when triggered` → 印限定詞括號內的全文 + - 延期語彙（exit 5）→ 印 `$COMPLEXITY_ERR` 的 `deferral-marker: <原值>` 整行（不摘要；括號內的 trigger 條件就在原值裡） - `### Blocking` → 印該區塊內容 4. render： @@ -433,7 +462,7 @@ Repo: PsychQuant/issue-driven-development (state: open, limit: 20) Footer 之後列出每個 issue 的建議下一步。**v2.51.0+ phase × PR state matrix**:依 issue phase 和 Step 3.5 抓到的 PR state 組合決定 next action。 -**v2.92+ #84 blocked-state 分組（anti-anxiety surfacing）**：Suggested next 依 Step 3.7 分兩組輸出： +**v2.92+ #84 blocked-state 分組（anti-anxiety surfacing）；#316 加 Parked 組**：Suggested next 依 Step 3.7 的 `group` 分組輸出。**Blocked 組（reason 僅 `blocking-nonempty`，或 idd-list 自己的 blocked-label / wait 類訊號）的標題、全 blocked banner 文案、footer 計數與 #84 逐字相同** —— 統一的是判定，不是呈現： ``` Actionable now: @@ -442,8 +471,16 @@ Actionable now: Blocked (waiting on external): #16 [diagnosed] → ⏳ waiting: Hsu Path 1/2 clarify（依 body Blocking 記錄） #17 [diagnosed] → ⏳ waiting: Theorem 1 generalization confirm + +Parked (not routable now): + #131 [diagnosed] → ⏸ deferral-marker: Simple when triggered + #146 [diagnosed] → ⏸ parking-lot label · deferral-marker: **Simple when triggered**(Layer 1 disqualifier:…) + #273 [diagnosed] → ⏸ missing-complexity — 先跑 /idd-diagnose #273 + #908 [diagnosed] → ⏸ unparseable-complexity: 移入 discussion list — 修正 Diagnosis ``` +Parked 組的歸類規則（`idd_actionability_group`）：reason **只有** `blocking-nonempty` → Blocked；其餘任何 reason 或混合（含 `complexity-deferral-marker` + `blocking-nonempty`）→ Parked。每列印出 `$REASONS` 與原文（`$COMPLEXITY_ERR` / label 名 / `$BLOCK_LINE`），**不給任何 lifecycle 命令**；`complexity-unparseable` / `complexity-missing` 才附「修正 Diagnosis / 先跑 diagnose」提示 —— `complexity-deferral-marker` 與 `parking-lot-label` 是合法狀態，不是要修的東西。`group=error`（gate API 誤用）單獨一列印 `⚠ gate error`，那是本 skill 的 bug。 + **全 blocked banner**：當 Actionable now 為空且 Blocked 非空： ``` @@ -451,7 +488,7 @@ Blocked (waiting on external): 這不是 throughput 問題；下次回來先檢查 blocker 是否解除。 ``` -Footer 統計行加 blocked 計數：`X actionable, Y blocked`。理由（#84 原始觀察）：「等」的狀態被顯式 surface 後，「沒進度」焦慮與「漏掉了什麼」反向搜尋都消失 — 資訊本體是聚合判斷，不是 per-issue 列表。 +Footer 統計行加 blocked 計數：`X actionable, Y blocked`（#84 原樣）；Parked 非空時**在其後**追加 `, Z parked`（Z=0 時不印，footer 與 #84 逐字相同）。全 blocked banner 的觸發條件不變（Actionable now 為空且 Blocked 非空）；若同時有 Parked，banner 文案原樣印出後另起一行 ` 另有 Z 個 parked（見 Parked 組；回訪用 --parked）`，不改動 banner 本身。理由（#84 原始觀察）：「等」的狀態被顯式 surface 後，「沒進度」焦慮與「漏掉了什麼」反向搜尋都消失 — 資訊本體是聚合判斷，不是 per-issue 列表。 ``` Suggested next: @@ -524,21 +561,13 @@ Suggested next: | `Spectra` (含 alias `SDD-warranted`) | `/spectra-discuss` (default) 或 `/spectra-propose` (opt-out) | | 推不出 | `/idd-implement #N` (保守 default) | -**Complexity 解析**：**不要在此處自行寫 regex。** 依 [`references/actionability-gate.md`](../../references/actionability-gate.md) 的封閉值域契約，呼叫共用實作： - -```bash -. "$CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh" || { - echo "FATAL: missing $CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh — 不得改用私有 regex" >&2 - exit 1 -} -tier=$(idd_parse_complexity "$latest_diagnosis_body"); cexit=$? -``` +**Complexity 解析與可動性判定**：**不要在此處自行寫 regex。** Step 3.7 已對每個 issue 呼叫共用實作並掛上 `group` / `tier` / `reasons`（契約見 [`references/actionability-gate.md`](../../references/actionability-gate.md)）；本表**只對 `group=actionable` 的 issue** 依 `$TIER` 套用。`tier` 只在 gate 放行時存在 —— `Simple when triggered` 的前綴 `Simple` 合法，但 helper 在 exit 5 **不會**印出它，所以這裡拿不到、也不可能誤路由。 **helper 缺失必須 fail loud**（契約要求）：silent fallback 回私有解析，正是本次要消滅的東西 —— 一個「找不到就自己想辦法」的 consumer 會把三方分歧原封不動地帶回來。 -`cexit=0` → `$tier` 是 canonical tier（`SDD-warranted` 視同 `Spectra`；` via <來源>` 後綴已剝除），依上表 routing。**`cexit=3`（值在封閉值域外）或 `cexit=4`（缺區段）→ 不給任何 lifecycle 命令**，改依 Step 3.7 歸入 Parked 組並 surface 原值。 +`group=blocked` / `parked` / `error` 的 issue **不進本表**，依 Step 5 分組並 surface 原值。 -> **為何不在這裡寫 regex（#298 → #316）**：本行原本規定 `### Complexity\n([A-Za-z-]+)`「取第一個 token」—— 那個 regex 在第一個空白處停止，`Simple when triggered` 被截成 `Simple`，正是 Step 3.7 明文禁止的截斷。同一份 SKILL.md 裡一段禁止截斷、另一段規定截斷，實作者照哪段做行為就不同。解析規則現在只有一份，住在共用 helper 裡。 +> **為何不在這裡寫 regex（#298 → #316）**：本行原本規定 `### Complexity\n([A-Za-z-]+)`「取第一個 token」—— 那個 regex 在第一個空白處停止，`Simple when triggered` 被截成 `Simple`，正是 Step 3.7 明文禁止的截斷。同一份 SKILL.md 裡一段禁止截斷、另一段規定截斷，實作者照哪段做行為就不同。解析規則現在只有一份，住在共用 helper 裡；第 1 輪（PR #318）換了 parser 卻沒讓任何 consumer 呼叫 `idd_actionability_verdict`（verify CRITICAL-1），所以 Step 3.7 的 gate 呼叫是本表的前提，不是可選項。 ## 鐵律 diff --git a/plugins/issue-driven-dev/skills/idd-plan/SKILL.md b/plugins/issue-driven-dev/skills/idd-plan/SKILL.md index eb2bb5a..d49373d 100644 --- a/plugins/issue-driven-dev/skills/idd-plan/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-plan/SKILL.md @@ -56,40 +56,59 @@ TaskCreate(name="auto_update_body", description="Step 7: idd-update phase → pl gh issue view $NUMBER --repo $GITHUB_REPO --json title,body,labels,comments ``` -**Complexity 值域判定不在此處自行比對字串**，改呼叫 [`references/actionability-gate.md`](../../references/actionability-gate.md) 契約下的共用實作： +**Complexity 的 tier 抽取與 actionability 判定不在此處自行比對字串**，改呼叫 [`references/actionability-gate.md`](../../references/actionability-gate.md) 契約下的共用實作： ```bash -LATEST_DIAGNOSIS=$(gh issue view "$NUMBER" --repo "$GITHUB_REPO" --json comments \ - | python3 -c " -import json, sys, re -d = json.load(sys.stdin) -diagnosis_comments = [c for c in d['comments'] if re.search(r'(?m)^## Diagnosis', c['body'])] # line-anchored,避免引述/inline 誤判 -print(diagnosis_comments[-1]['body'] if diagnosis_comments else '') -") - -# 缺 helper 一律 fail loud + 指名 path,禁止 fallback 到私有檢查(契約 §Consumer contract) +# 缺 helper 一律 fail loud + 指名 path，禁止 fallback 到私有 regex（契約 §Consumer contract） . "$CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh" || { - echo "FATAL: missing $CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh — 不得改用私有 Complexity 檢查" >&2 + echo "FATAL: missing $CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh — 不得改用私有 regex" >&2 exit 1 } -TIER=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>/dev/null); CEXIT=$? -COMPLEXITY_ERR=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>&1 >/dev/null) # cexit≠0 時的 `unparseable-complexity: ` / `missing-complexity` +# 1. 最新 Diagnosis comment —— 必須分頁。`gh issue view --json comments` 只回最舊的 100 則， +# issue 一長，最新的 diagnosis 正好是被丟掉的那一則（#295 同族；`--paginate --jq` 每頁一個 array，`jq -s add` 收攏）。 +LATEST_DIAGNOSIS=$(gh api "repos/$GITHUB_REPO/issues/$NUMBER/comments" --paginate --jq '[.[] | {body}]' \ + | jq -s 'add // []' \ + | python3 -c ' +import json, sys, re +cs = json.load(sys.stdin) +ds = [c for c in cs if re.search(r"(?m)^## Diagnosis", c["body"])] # line-anchored，引述/inline 不算（v2.68.0+ #59） +print(ds[-1]["body"] if ds else "")') + +# 2. 另外兩個訊號：labels，與 body 的 ### Blocking（經 helper 讀；idd-update 的 `- (none)` placeholder 算空） +ISSUE_JSON=$(gh issue view "$NUMBER" --repo "$GITHUB_REPO" --json labels,body) +HAS_PARKING=$(jq -r 'if any(.labels[]; .name == "parking-lot") then "yes" else "no" end' <<<"$ISSUE_JSON") +BLOCK_LINE=$(idd_blocking_section "$(jq -r '.body // ""' <<<"$ISSUE_JSON")") +if [ -n "$BLOCK_LINE" ]; then BLOCKING=yes; else BLOCKING=no; fi + +# 3. 條件式捕捉 —— `set -euo pipefail` 下唯一不會被 exit 3/4/5 終止的寫法（verify #318 HIGH） +if TIER=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>/dev/null); then CEXIT=0; else CEXIT=$?; fi +COMPLEXITY_ERR=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>&1 >/dev/null) || true # 3/5 回 `: <原值>`、4 回 `missing-complexity` + +# 4. 真的呼叫 gate。exit 2 是 API 誤用（本 skill 的 bug），不得與 not-actionable 混同 +if VERDICT=$(idd_actionability_verdict --complexity-exit "$CEXIT" --parking-label "$HAS_PARKING" --blocking-section "$BLOCKING" 2>&1); then VEXIT=0; else VEXIT=$?; fi +case "$VEXIT" in + 0) ;; # actionable → 依下表以 $TIER 分派 + 1) REASONS="${VERDICT#not-actionable: }" ;; # withheld → 下表 `VEXIT=1` 各列；不給任何 lifecycle 命令 + *) echo "FATAL: idd_actionability_verdict misuse — $VERDICT" >&2; exit 1 ;; +esac ``` -以 `(CEXIT, TIER)` 為鍵決定行為。**exit 0 的四個 tier 是封閉值域,不得依相似性外推第五個**： +**先看 `$VEXIT`**（gate 判定），`0` 才依 `$TIER` 決定行為。tier 只有四個；`### Complexity` 開頭以外的同行理由、裝飾、` via <來源>` 後綴都不影響 `$TIER`： | `CEXIT` · `TIER` | 行為 | |-----------|------| | `0` · `Plan` | ✅ 預期 — 繼續 Step 2 | -| `0` · `Plan`（原值 `Plan via Layer V`）| 同上 — helper 已剝除 ` via <來源>` 後綴,canonical tier 即 `Plan`,行為與 bare `Plan` 完全一致 | +| `0` · `Plan`（原值 `Plan via Layer V`、`**Plan**(Layer P:…)` 等）| 同上 — helper 只取開頭的 tier,後綴與同行理由皆不影響,行為與 bare `Plan` 完全一致 | | `0` · `Simple` | ⚠️ 詢問 user：「Complexity 判定為 Simple，確定要走 Plan tier 多一道 approval gate 嗎？」（行為不變 — user 主動要 deliberate 是允許的）| | `0` · `Spectra` | ⛔ 提示「Spectra 應走 `/spectra-discuss`，Plan tier 不會產出 spec/proposal/tasks artifacts」，AskUserQuestion abort 或 continue（continue 等於 user 自願降級到 Plan tier）— 行為不變 | | `0` · `SDD-warranted`（legacy alias）| 視同 `Spectra` 處理 — 行為不變 | -| `3` — 值落在封閉值域外（如 `Plan when triggered`）| ⛔ **abort** — 印出 `$COMPLEXITY_ERR` 的 `unparseable-complexity: ` **原值**，要求 user 修正 Diagnosis，或把延期狀態改掛 `parking-lot` label。**禁止**截斷成 tier 前綴、**禁止**降級成 `Plan` 或任何其他 tier、**禁止**當成 `Simple` 問過 user 就繼續 | -| `4` — 無 `### Complexity` 區段（含完全沒有 `## Diagnosis` comment）| ⛔ **abort** — 提示「找不到 diagnosis / Complexity 判定，先跑 `/idd-diagnose #NNN`」（即舊表的 _(missing)_ 列，語意不變）| +| `VEXIT=1` · `$REASONS` 含 `complexity-deferral-marker`（如 `Plan when triggered`）或 `parking-lot-label` | ⛔ **abort（parked）** — 印出 `$REASONS` 與原文（`$COMPLEXITY_ERR` 的 `deferral-marker: <原值>`，或 label 名）。這是**合法的延期狀態，不是資料錯誤**；要動它，先由人移除 label 或重新 diagnose。**禁止**截斷成 tier 前綴、**禁止**降級成 `Plan` 或任何其他 tier、**禁止**因為前綴是 `Plan` 就放進 approval gate、**禁止**當成 `Simple` 問過 user 就繼續 | +| `VEXIT=1` · `$REASONS` 含 `blocking-nonempty` | ⛔ **abort（blocked）** — 印出 `$BLOCK_LINE`；等 blocker 解除（`idd-update` 清 `### Blocking`）| +| `VEXIT=1` · `complexity-unparseable`（值不以 tier 開頭）| ⛔ **abort** — 印出 `$COMPLEXITY_ERR` 的 `unparseable-complexity: <原值>`，要求 user 修正 Diagnosis（這才是資料錯誤）| +| `VEXIT=1` · `complexity-missing`（無 `### Complexity` 區段，含完全沒有 `## Diagnosis` comment）| ⛔ **abort** — 提示「找不到 diagnosis / Complexity 判定，先跑 `/idd-diagnose #NNN`」（即舊表的 _(missing)_ 列，語意不變）| -> **為何不在此處自行認定 tier（#298 → #316）**：本 step 原本用一句散文自行認定「`### Complexity` 是 `Plan`（或 `Simple`）」，值域外的值沒有任何定義行為。像 `Plan when triggered` 這種**帶延期修飾語**的歷史寫法，字面以 `Plan` 開頭、讀起來像 Plan tier，很容易被直接放行進 approval gate —— 但它真正的意思是「這件事被人為延期了」。`### Complexity` 的值域是**封閉的四個 tier**（可帶 ` via <來源>` 後綴），延期狀態屬於 `parking-lot` label，不屬於這個欄位。修法不是把散文判準寫得更嚴 —— 那只會讓第 N 份私有窄化加入既有的多方分歧 —— 而是讓值域判定只剩一份實作：後綴剝除、封閉值域檢查、原值 surface 全在 `scripts/lib/actionability.sh`，本 skill 只讀它的 exit code。「不得截斷、不得降級、不得靜默」的規定見 [`references/actionability-gate.md`](../../references/actionability-gate.md)。 +> **為何不在此處自行認定 tier（#298 → #316）**：本 step 原本用一句散文自行認定「`### Complexity` 是 `Plan`（或 `Simple`）」，值域外的值沒有任何定義行為。像 `Plan when triggered` 這種**帶延期修飾語**的歷史寫法，字面以 `Plan` 開頭、讀起來像 Plan tier，很容易被直接放行進 approval gate —— 但它真正的意思是「這件事被人為延期了」。`### Complexity` 只要求**以四個 tier 之一開頭**（其後理由、裝飾、` via <來源>` 後綴皆合法 —— 本 repo 159 筆 diagnosis 有 71.7% 不是裸 tier），延期狀態屬於 `parking-lot` label；歷史上寫進欄位的延期語彙由 helper 以 `complexity-deferral-marker` 擋下。修法不是把散文判準寫得更嚴 —— 那只會讓第 N 份私有窄化加入既有的多方分歧 —— 而是讓判定只剩一份實作：tier 前綴抽取、延期語彙偵測、`### Blocking` 讀取、三訊號 gate、原值 surface 全在 `scripts/lib/actionability.sh`，本 skill 只讀它的 exit code。**只換 parser 不呼叫 verdict 等於沒修**（PR #318 verify CRITICAL-1）。「不得截斷、不得降級、不得靜默」的規定見 [`references/actionability-gate.md`](../../references/actionability-gate.md)。 ### Step 2: Draft Implementation Plan From 343e8077931bd9a19384e7d32b45bf41c75d862c Mon Sep 17 00:00:00 2001 From: che cheng Date: Mon, 7 Sep 2026 16:09:47 +0900 Subject: [PATCH 5/6] =?UTF-8?q?feat:=20actionability=20gate=20round=203=20?= =?UTF-8?q?=E2=80=94=20per-bullet=20Blocking=20reader,=20undiagnosed=20gro?= =?UTF-8?q?up,=20gate=20before=20egress?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refs #316 (round-3 repairs for the /idd-verify --pr 318 round-2 FAIL: 6 blocking + 10 in-scope) Helper (scripts/lib/actionability.sh) - idd_blocking_section reads the section PER BULLET (any non-placeholder bullet is a blocker; continuation lines belong to the bullet above) and recognises a placeholder by its LEADING TOKEN (none / n/a / 無, optionally bulleted, decorated, parenthesised, then EOL / ')' / separator). Round 2 anchored the whole line and withheld 31 of 47 empty sections, including #316's own `- (none — 可動)`. - trailing CR stripped before either section reader judges a line (GitHub web textarea submits CRLF) - idd_actionability_group gains `undiagnosed` (complexity-missing alone) - new frozen fixture corpus-blocking.json: all 55 `### Blocking` sections in this repo's issue bodies, hand-reviewed (47 empty / 8 non-empty), 0 FP / 0 FN; two rival rules measured there and rejected (documented in the helper) Consumers - idd-implement: gate moved to Step 0.35, ahead of tree-lock, branch creation and the Implementation Plan comment; test pins the line order - idd-list: Needs-diagnosis group keeps `→ /idd-diagnose #N`; Parked is now exactly the --parked set; labels/body/comments taken from the Step 2 bulk fetch (paginate only at >= 100 comments); open-state guard; per-row fetch failure marks the row instead of aborting; REASONS reset; C0 stripped - all four: issue number digit-checked before the REST path; Diagnosis comments trusted only from OWNER/MEMBER/COLLABORATOR; jq/python3 in allowed-tools; table header VEXIT · CEXIT · TIER - idd-all: Layer V sub-issue scan and Phase 3b.1 fallback paginate Contract / producer - references/actionability-gate.md: signal-3 risk posture, undiagnosed group, corpus denominator (66/225 never diagnosed), scoped producer prohibition, hardened canonical snippet, "gate SHALL precede any egress or branch" - idd-diagnose: prohibition scoped to the issue under diagnosis - idd-issue + spec delta idd-ic-r011-checkpoint: blocker:* retired for parking-lot - rules/sdd-integration.md: parallel bare-token parse narrative removed Tests (285 assertions): blocking corpus 55/55; CRLF both readers; per-bullet cases incl. `- none of the reviewers replied yet`; row 905 really emits a `- [~]` Strategy item; drift guard pins verdict capture shape, REASONS branch, FATAL branch, digit check, author filter, allowed-tools, gate-before-branch and gate-before-egress order, no `=$(gh issue view … --json comments)` left. Spec: R6 three groups, R7 scoped, new R9 (blocking signal per bullet, frozen corpus); design round-3 decisions + open question (#336); tasks 10.x. Follow-ups filed from the verify: #336 #337 #338 #339. --- .claude-plugin/marketplace.json | 2 +- .../changes/add-actionability-gate/design.md | 23 +- .../add-actionability-gate/proposal.md | 11 +- .../specs/actionability-gate/spec.md | 41 +- .../specs/idd-ic-r011-checkpoint/spec.md | 33 ++ .../changes/add-actionability-gate/tasks.md | 11 + .../.claude-plugin/plugin.json | 2 +- plugins/issue-driven-dev/CHANGELOG.md | 47 ++ .../references/actionability-gate.md | 51 +- .../issue-driven-dev/rules/sdd-integration.md | 8 +- .../scripts/lib/actionability.sh | 107 +++- .../fixtures/corpus-blocking.json | 505 ++++++++++++++++++ .../fixtures/parked-routing.json | 9 +- .../scripts/tests/actionability-gate/test.sh | 130 ++++- .../issue-driven-dev/skills/idd-all/SKILL.md | 22 +- .../skills/idd-diagnose/SKILL.md | 2 +- .../skills/idd-implement/SKILL.md | 86 +-- .../skills/idd-issue/SKILL.md | 2 +- .../issue-driven-dev/skills/idd-list/SKILL.md | 48 +- .../issue-driven-dev/skills/idd-plan/SKILL.md | 11 +- 20 files changed, 1005 insertions(+), 146 deletions(-) create mode 100644 openspec/changes/add-actionability-gate/specs/idd-ic-r011-checkpoint/spec.md create mode 100644 plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/corpus-blocking.json diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index d32a45a..41fdb45 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -16,7 +16,7 @@ { "name": "issue-driven-dev", "version": "3.1.0", - "description": "v3.1.0: the actionability gate, round 2. Round 1 read `### Complexity` against a closed value domain that the repository's own 159 diagnoses refuted (66 real values wrongly refused) and shipped a three-signal gate no consumer called. Now the tier is the leading whole word (rationale, decoration and ` via` suffixes are legal), the whole line is scanned for a small deferral vocabulary (exit 5, reason `complexity-deferral-marker` — a parked state, not a defect), `### Blocking` is read by a shared fence-aware helper, and idd-list / idd-all / idd-implement / idd-plan actually call the verdict with all three signals in a paginated, `set -e`-safe shape pinned by a drift test. A frozen 159-issue corpus fixture makes 'zero migration' falsifiable: 149 routable, 9 deferral, 1 missing, 0 unparseable. idd-list gains a Parked group; the #84 blocked surface is preserved verbatim.", + "description": "v3.1.0: the actionability gate, rounds 2 and 3. Round 1 read `### Complexity` against a closed value domain that the repository's own 159 diagnoses refuted (66 real values wrongly refused) and shipped a three-signal gate no consumer called. Now the tier is the leading whole word (rationale, decoration and ` via` suffixes are legal), the whole line is scanned for a small deferral vocabulary (exit 5, reason `complexity-deferral-marker` — a parked state, not a defect), `### Blocking` is read by a shared fence-aware helper, and idd-list / idd-all / idd-implement / idd-plan actually call the verdict with all three signals in a paginated, `set -e`-safe shape pinned by a drift test. A frozen 159-issue corpus fixture makes 'zero migration' falsifiable: 149 routable, 9 deferral, 1 missing, 0 unparseable. idd-list gains Parked and Needs-diagnosis groups; the #84 blocked surface is preserved verbatim. Round 3 read `### Blocking` per bullet with a leading-token placeholder rule frozen against the repo's 55 real sections (round 2 had withheld 31 of the 47 empty ones, including #316 itself), moved idd-implement's gate ahead of any branch or comment, and retired `blocker:*`.", "author": { "name": "Che Cheng" }, diff --git a/openspec/changes/add-actionability-gate/design.md b/openspec/changes/add-actionability-gate/design.md index 49875d6..0e501f8 100644 --- a/openspec/changes/add-actionability-gate/design.md +++ b/openspec/changes/add-actionability-gate/design.md @@ -59,7 +59,7 @@ tier 之後的其餘文字（同行理由、括號說明）**是合法的**， **分界不在「後面有沒有字」，而在「那些字是否表達延期」。** 前版的分界把 93.1% 的正常寫法與 5.7% 的延期寫法切在同一邊，導致 66 筆本該路由的 issue 變成 hard abort。 -本規則在完整 corpus 上：**149 筆正確路由 + 9 筆正確擋下 = 158/158，0 false positive。** +本規則在完整 corpus 上：**149 筆正確路由 + 9 筆正確擋下 + 1 筆正確報缺區段 = 159/159，0 false positive。** 延期語彙目前為 `when triggered` / `parking lot` / `deferred` / `暫緩`。偵測必須掃**整個值**而非只掃 tier 之後 —— `#136` 的 tier 是 bare `Spectra`，延期語彙藏在括號理由內。 @@ -146,6 +146,22 @@ gate 產出 verdict 加 reason 清單；顯示層依 reason 分兩組 —— rea 理由：vocabulary drift —— 文件寫的兩個 label 目前各 0 個 issue 在用，實際在用的 `parking-lot` 有 6 個。該檔同時宣稱存在一個「periodic backlog grooming」機制去 grep 那兩個 label；該機制不存在且會掃到空集合（已獨立為 #310）。本變更只收斂 label 名稱，不實作 grooming。 +### 第 3 輪（2026-09-07）：訊號 3 逐 bullet 讀、未診斷不是 parked、gate 先於副作用 + +> `/idd-verify --pr 318` 第 2 輪 FAIL（6 blocking）。四個 lens 與 DA 各自對 238 筆 issue 實測，結論一致：第 2 輪在**第三個訊號**上重犯了 CRITICAL-2 的形狀 —— `idd_blocking_section` 依「idd-update 寫 `- (none)`」這個未經語料驗證的假設寫成整行比對，本 repo 55 個 `### Blocking` 區段裡 48 個語意為空、31 個被判成 blocker，**含 #316 自己**（`- (none — 可動)`）。DA 另外對 14 個 open issue 實跑 gate：2 actionable / 1 blocked（誤判）/ **11 parked** —— 那 11 筆只是還沒診斷。 + +**決策 1 — `### Blocking` 是清單欄位，逐 bullet 判、placeholder 看開頭 token。** `### Complexity` 是純量、讀第一行是定義；`### Blocking` 的模板就是 bullet list，讀第一行等於把 list 當 head(list)。規則：任一 bullet 非 placeholder 即非空；placeholder = `none` / `n/a` / `無` 開頭（可帶 bullet、裝飾、括號），後接行尾、右括號或分隔符；非 bullet 起始的行是上一個 bullet 的續行。對 55 筆凍結語料（`corpus-blocking.json`）0 FP / 0 FN；另兩個候選規則在同一語料上各自失敗（一個把 7 筆真 blocker 全清空、一個留 20 個 FP），記在 helper 註解裡當反例。接受的漏抓：token 後接子句（`- (none) but actually blocked by #86`）讀成空 —— 語料 0 筆，明文記錄。**這個欄位該不該被 regex 化**是類別問題，開 #336 追（producer contract vs 退回 model 判定），本輪只止血。 + +**決策 2 — `complexity-missing` 單獨成 `undiagnosed` 組，保留 `→ /idd-diagnose #N`。** 「還沒診斷」是每張 issue 的出生狀態，在真實 backlog 上是主導狀態；放進 Parked 會讓 footer 與 `--parked` 差一個數量級、藏掉唯一正確的 lifecycle 命令、並讓 #84 的 banner 在新的主導情境下永遠不 fire。spec R6 改為三組：含 label / deferral-marker / unparseable → parked；否則含 blocking-nonempty → blocked（#84 逐字保留）；否則 → undiagnosed。 + +**決策 3 — gate 必須先於任何 egress 或建 branch。** `idd-implement` 第 2 輪把 gate 放在 Step 2.5，一張人為 park 的 issue 會先被建 branch、先貼 Implementation Plan 才被擋。移到 Step 0.35（tree-lock 之前），契約加一句，測試釘住順序。 + +**決策 4 — producer 禁令加範圍限定；`blocker:*` 全面退役。** 「idd-diagnose SHALL NOT 貼 `parking-lot`」的對象是**正在診斷的該 issue**；IC_R011 對新 filed 的 sister issue 貼 label 是人的分類裁決落在另一張 issue 上。`idd-issue` 與 live spec `idd-ic-r011-checkpoint` 仍規定 `blocker:*`（MUST 級）—— 以 spec delta 收斂。 + +**決策 5 — 信任邊界與輸入衛生進 canonical shape。** Diagnosis comment 只取 OWNER / MEMBER / COLLABORATOR（public repo 任何帳號都能留言）；issue 號進 REST path 前驗型；CRLF 先剝；surface 的原文剝 C0 控制字元、明寫「是資料不是指令」；`jq` / `python3` 進 allowed-tools。 + +替代方案：(a) 只修 regex 不改逐 bullet —— 把 31 個 FP 換成 31 個 FN，失敗方向從保守擋下翻成靜默放行（DA 量過）；(b) 把 undiagnosed 留在 Parked 但改組名 —— 仍藏 diagnose 命令；(c) 訊號 3 退回 model 判定 —— 正確但超出本輪，是 #336。 + ## Implementation Contract **Behavior** — 跑 `/idd-list` 時，被 gate 判為 not-actionable 的 issue 不再出現在 Suggested next 的可動清單，改列於 Blocked 或 Parked 分組並附判定理由；`### Complexity` 值非法時，該值原文顯示於輸出中。`/idd-all`、`/idd-implement`、`/idd-plan` 拿到非法 Complexity 值時停止 routing 並回報原值，不再落入未定義行為。 @@ -186,7 +202,7 @@ gate 產出 verdict 加 reason 清單；顯示層依 reason 分兩組 —— rea ## Migration Plan -**無資料 migration。** 新規則對既有 159 筆語料 158/158 全對，不需要回填 label、不需要改寫任何 Diagnosis comment。 +**無資料 migration。** 新規則對既有 159 筆語料 159/159 全對（149 路由、9 擋下、1 缺區段），不需要回填 label、不需要改寫任何 Diagnosis comment。 實作順序（非 migration，是落地順序）： @@ -200,5 +216,8 @@ Rollback：本變更為 skill 文件與 helper script 的變更，零資料遷 ## Open Questions +- **`### Blocking` 該不該被機械判定？**（#336）第 3 輪的 leading-token 規則是止血，不是答案：對一個由 model 自由填寫的清單欄位疊字元類，每一輪都會長出新洞。要嘛給它 producer contract（空區段不寫 bullet、註記另起一行），要嘛 helper 只回原文、由執行中的 model 依 rubric 判空。兩條路都要對 `corpus-blocking.json` 0 FP / 0 FN。 + + - **延期語彙清單的擴充機制未定。** 目前四個語彙由 159 筆 corpus 歸納而得。語料成長後若出現新措辭，是誰、依什麼判準把它加進清單？本變更不解決；先記錄為已知缺口。 - `ic-r011-checkpoint.md` 的兩個 `blocker:*` label 是「退役」還是「與 parking-lot 分工」，需在該檔改寫時定案。目前 0 使用，傾向退役。 diff --git a/openspec/changes/add-actionability-gate/proposal.md b/openspec/changes/add-actionability-gate/proposal.md index 0e955f1..65e39d8 100644 --- a/openspec/changes/add-actionability-gate/proposal.md +++ b/openspec/changes/add-actionability-gate/proposal.md @@ -18,9 +18,9 @@ - **`parking-lot` label 是 parked 的主要訊號**，延期語彙是次要安全網。語彙清單取高精度、容忍低召回。 - **新增 actionability gate** —— 三訊號 OR 判定（Complexity 不可路由、`parking-lot` label、`### Blocking` 非空），放行需三者皆不成立，**且四個 consumer 必須實際呼叫它**。 - **三個 consumer 的 Complexity 解析統一** —— `idd-list`、`idd-all`、`idd-implement`（含 `idd-plan` 的 tier 確認）改用共用 helper，消除各自窄化。 -- **`### Blocking` 抽取重構為 gate 的 input** —— #84 既有的 Blocked 分組輸出行為不得退化。 +- **`### Blocking` 抽取重構為 gate 的 input** —— 共用 helper 逐 bullet 讀、placeholder 看開頭 token，對 55 筆凍結語料 0 誤判（第 3 輪；第 2 輪的整行比對誤判 31 筆、含 #316 自己）。#84 既有的 Blocked 分組輸出行為不得退化；未診斷的 issue 另成 `undiagnosed` 組並保留 `/idd-diagnose` 命令。 - **`idd-diagnose` producer 端明訂延期意圖走 label** —— 不再宣告封閉值域；改為「tier 寫清楚、延期貼 label、不要把延期寫進本欄」。 -- **零 migration** —— 新規則對既有 159 筆語料 158/158 全對，不需回填 label、不需改寫任何 Diagnosis comment。 +- **零 migration** —— 新規則對既有 159 筆語料 159/159 全對（149 路由、9 擋下、1 缺區段），不需回填 label、不需改寫任何 Diagnosis comment。**零 migration 指「既有 diagnosis 不需改寫」，不是「backlog 可動性分佈不變」** —— 225 筆裡 66 筆從未 diagnose，全部 exit 4，顯示層以 `undiagnosed` 組承接（第 3 輪）。 - **`references/ic-r011-checkpoint.md` 的 parking 慣例收斂** —— `blocker:infeasible` / `blocker:waiting` 目前 0 個 issue 在用，實際在用的是 `parking-lot`。 ## Capabilities @@ -31,7 +31,7 @@ ### Modified Capabilities -(none) +- `idd-ic-r011-checkpoint`：skip path 的 (b)/(c) 分類改以 `parking-lot` label 立案（原 `blocker:infeasible` / `blocker:waiting` 從未建立過；`parking-lot` 自 3.1.0 起是 gate 的一級訊號）。delta 見 `specs/idd-ic-r011-checkpoint/spec.md`。 為何無 modified capability：硬閘與 Layer V 這兩份既有 spec 所產出的帶後綴 verdict（形如 tier 後接 " via " 再接來源）在新抽取規則下**仍為合法值**（tier 開頭、` via ` 後綴不參與 tier 判定），其 requirement 不需修改；conflict-class 規範對 Complexity 欄位的正交性敘述同樣維持成立。 @@ -44,6 +44,8 @@ - `plugins/issue-driven-dev/scripts/lib/actionability.sh` - `plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh` - `plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/parked-routing.json` + - `plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/corpus-complexity.json`（159 筆凍結 Complexity 語料） + - `plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/corpus-blocking.json`（55 筆凍結 Blocking 語料，第 3 輪） - Modified: - `plugins/issue-driven-dev/skills/idd-list/SKILL.md` - `plugins/issue-driven-dev/skills/idd-all/SKILL.md` @@ -51,6 +53,9 @@ - `plugins/issue-driven-dev/skills/idd-plan/SKILL.md` - `plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md` - `plugins/issue-driven-dev/references/ic-r011-checkpoint.md` + - `plugins/issue-driven-dev/skills/idd-issue/SKILL.md`（`blocker:*` → `parking-lot`，第 3 輪） + - `plugins/issue-driven-dev/rules/sdd-integration.md`（移除平行的 Complexity 解析敘述，第 3 輪） + - `plugins/issue-driven-dev/CHANGELOG.md`、`.claude-plugin/plugin.json`、`.claude-plugin/marketplace.json`（3.1.0） - Removed: (none) - 同檔衝突：#299（`--limit` 先於排序生效）同樣修改 `plugins/issue-driven-dev/skills/idd-list/SKILL.md`，兩者需序列化或合併處理。 - 追蹤 issue 由 #298 改為 **#316**（#298 已由 PR #309 / #306 修掉並 close，只涵蓋 `idd-list`）。 diff --git a/openspec/changes/add-actionability-gate/specs/actionability-gate/spec.md b/openspec/changes/add-actionability-gate/specs/actionability-gate/spec.md index 5952aaa..e91c96c 100644 --- a/openspec/changes/add-actionability-gate/specs/actionability-gate/spec.md +++ b/openspec/changes/add-actionability-gate/specs/actionability-gate/spec.md @@ -111,7 +111,7 @@ Complexity parsing and actionability verdict logic SHALL exist as one shared imp ### Requirement: Blocked-state output is preserved as a distinct display group -The gate SHALL produce a verdict together with its reason list, and the display layer SHALL group not-actionable issues by reason. Issues whose only reason is `blocking-nonempty` SHALL continue to appear under the existing blocked-state grouping, with its group heading, its all-blocked banner text, and its footer counts unchanged from the behavior established for blocked-state awareness. Issues whose reasons include `parking-lot-label`, `complexity-unparseable`, or `complexity-missing` SHALL appear under a separate parked grouping. +The gate SHALL produce a verdict together with its reason list, and the display layer SHALL group not-actionable issues by reason into exactly three groups. Issues whose reasons include any of `parking-lot-label`, `complexity-deferral-marker`, or `complexity-unparseable` SHALL appear under a parked grouping — the same set the parked-review flag lists. Otherwise, issues whose reasons include `blocking-nonempty` SHALL appear under the existing blocked-state grouping, with its group heading, its all-blocked banner text, and its footer counts unchanged from the behavior established for blocked-state awareness. Otherwise — reason `complexity-missing` alone — the issue SHALL appear under an undiagnosed grouping that retains the diagnose lifecycle command, because an issue that has never been diagnosed is in its birth state, not a parked state; on the 2026-09-07 open backlog that state held 11 of 14 issues, and filing it as parked hid the only correct next action and made the footer disagree with the parked-review flag by an order of magnitude. #### Scenario: Blocking-only issue keeps existing grouping @@ -124,9 +124,20 @@ The gate SHALL produce a verdict together with its reason list, and the display - **WHEN** an issue is not actionable with reason `parking-lot-label` - **THEN** the issue appears under the parked group rather than the blocked-state group +#### Scenario: Undiagnosed issue keeps its diagnose command + +- **WHEN** an issue is not actionable with reason `complexity-missing` alone +- **THEN** the issue appears under the undiagnosed group, not the parked group +- **AND** its row still offers the diagnose lifecycle command + +#### Scenario: Missing diagnosis with a real blocker is blocked + +- **WHEN** an issue is not actionable with reasons `complexity-missing` and `blocking-nonempty` +- **THEN** the issue appears under the blocked-state group + ### Requirement: Parked label is authored by a human and never derived by the producer -`idd-diagnose` SHALL NOT apply, remove, or derive the `parking-lot` label. The label SHALL remain a human-authored decision that is settable and removable after the diagnosis was written. +`idd-diagnose` SHALL NOT apply, remove, or derive the `parking-lot` label on the issue it is diagnosing. The label SHALL remain a human-authored decision that is settable and removable after the diagnosis was written. This prohibition is scoped to the issue under diagnosis: the IC_R011 checkpoint that runs inside `idd-diagnose` MAY attach `parking-lot` to a newly filed sister issue when the user classifies that candidate as infeasible or blocked-on-external, because that is a human classification landing on a different issue. #### Scenario: Diagnosis run leaves labels untouched @@ -152,4 +163,28 @@ Existing Diagnosis comments SHALL NOT be rewritten, and no label SHALL be backfi #### Scenario: Fixture reflects real shapes rather than a hypothesis-confirming sample - **WHEN** the regression fixture is reviewed -- **THEN** it contains at least three cases each of bare tier, tier with same-line rationale, decorated tier, and deferral vocabulary +- **THEN** it contains at least three real-corpus cases each of bare tier, tier with same-line rationale, decorated tier, and deferral vocabulary + +### Requirement: The blocking signal is read per bullet against a frozen corpus + +The `### Blocking` section SHALL be read as a list: the section is non-empty when any bullet is not a none-placeholder, and a placeholder SHALL be recognised by its leading token (`none`, `n/a`, `無`, optionally bulleted, decorated, or parenthesised, followed by end of line, a closing paren, or a separator) so that an annotated placeholder such as `- (none — 可動)` is empty while a bullet whose first word merely happens to be `none` is not. Lines that do not begin a bullet SHALL be treated as continuations of the bullet above. A trailing carriage return SHALL be stripped before either section reader judges a line. The rule SHALL be validated against every `### Blocking` section in the repository's issue bodies as a frozen regression fixture, because the first implementation was written against an assumed producer shape and withheld 31 of the 47 empty sections in that corpus, including the tracking issue of this change. + +#### Scenario: Annotated placeholder is empty + +- **WHEN** the section reads `- (none — 可動)` +- **THEN** the blocking signal is clear + +#### Scenario: Placeholder followed by a real bullet is non-empty + +- **WHEN** the section reads `- (none)` on one bullet and `- 等 upstream #310 merge` on the next +- **THEN** the blocking signal reports the second bullet + +#### Scenario: A blocker that starts with the token is kept + +- **WHEN** the section reads `- none of the reviewers replied yet` +- **THEN** the blocking signal reports that line + +#### Scenario: CRLF does not change either reader's verdict + +- **WHEN** an issue body or Diagnosis comment uses CRLF line endings +- **THEN** `### Complexity` and `### Blocking` are judged exactly as their LF equivalents diff --git a/openspec/changes/add-actionability-gate/specs/idd-ic-r011-checkpoint/spec.md b/openspec/changes/add-actionability-gate/specs/idd-ic-r011-checkpoint/spec.md new file mode 100644 index 0000000..f0f9d6d --- /dev/null +++ b/openspec/changes/add-actionability-gate/specs/idd-ic-r011-checkpoint/spec.md @@ -0,0 +1,33 @@ +## MODIFIED Requirements + +### Requirement: Skip path SHALL require explicit 3-category taxonomy disambiguation + +When the user requests to skip filing one or more candidates (via explicit user prompt, env var bypass, or `# Disable IC_R011` flag), the skill SHALL present a second-level `AskUserQuestion` for each skip-candidate forcing selection among three categories: `(a) unactionable observation`, `(b) infeasible but understood`, or `(c) blocked on external state`. Selecting `(a)` SHALL skip filing and record `Skipped: (a) unactionable observation` in the audit trail. Selecting `(b)` or `(c)` SHALL still file the candidate via `gh issue create` with an added repository label of `parking-lot` or `parking-lot` respectively, and SHALL record `Skipped: (b) infeasible — filed as #NNN with `parking-lot` label` (or the `(c)` equivalent). + +#### Scenario: user skips one of three candidates with category (a) + +- **WHEN** the user invokes skip for 1 out of 3 surfaced candidates and selects `(a) unactionable observation` from the second-level picker +- **THEN** the skill MUST file the other 2 candidates via `gh issue create` AND MUST NOT file the skipped candidate AND MUST record the skip reason in the audit trail with the literal string `Skipped: (a) unactionable observation` + +#### Scenario: user skips with category (b) + +- **WHEN** the user selects `(b) infeasible but understood` for a candidate +- **THEN** the skill MUST still call `gh issue create` for that candidate AND MUST attach the label `parking-lot` via the `--label` flag AND MUST record `Skipped: (b) infeasible — filed as # with `parking-lot` label` in the audit trail + +##### Example: skip-and-file audit trail entries + +- **GIVEN** 3 candidates [X, Y, Z], user skips Z with category (c) +- **WHEN** the skill executes +- **THEN** the audit trail contains both `Filed: #X-num, #Y-num` and `Skipped: (c) blocked-on-external — filed as #Z-num with `parking-lot` label` + + + + +--- + +> Modified by `add-actionability-gate` (#316 round 3): the (b) / (c) skip categories file the candidate with the `parking-lot` label instead of `blocker:infeasible` / `blocker:waiting`. Those two labels were never created in any repository using IDD, while `parking-lot` is in use and — since 3.1.0 — is the primary parked signal of the actionability gate, so a sister issue filed under (b) / (c) is born parked and stays out of routing until a human removes the label. The reference (`ic-r011-checkpoint.md`), `idd-issue`, and `idd-diagnose` were converged in the same change; this delta brings the live spec's MUST into agreement. diff --git a/openspec/changes/add-actionability-gate/tasks.md b/openspec/changes/add-actionability-gate/tasks.md index 8e38359..b66c902 100644 --- a/openspec/changes/add-actionability-gate/tasks.md +++ b/openspec/changes/add-actionability-gate/tasks.md @@ -61,3 +61,14 @@ - [x] 9.1 `references/actionability-gate.md` 依新規則重寫。行為契約：封閉值域段改為「tier prefix 抽取 + 延期語彙」；reason 值域 4 → 5；新增「風險姿態：label 為主、語彙為輔」段並說明漏抓/誤抓的不對稱處置。驗證：內容審查確認不再出現「合法值域為封閉四值」的宣稱，且 corpus 數據（159 筆 / 158-158）有明文引用。檔案：`plugins/issue-driven-dev/references/actionability-gate.md` - [x] 9.2 [P] `idd-diagnose` producer 宣告改寫。行為契約：移除封閉值域宣告，改為「tier 寫清楚；延期意圖貼 `parking-lot` label，不要寫進 `### Complexity`」，並保留「producer 不自動貼 label」一條。驗證：內容審查確認不再宣告封閉值域，且 159 筆語料的常態寫法（tier + 同行理由）未被規定為違規。檔案：`plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md` + +## 10. 第 3 輪（`/idd-verify --pr 318` 第 2 輪 FAIL 的 6 blocking + 10 in-scope） + +- [x] 10.1 `idd_blocking_section` 改為逐 bullet 讀、placeholder 以開頭 token 判定；CRLF 先剝；凍結 55 筆 `corpus-blocking.json`（47 空 / 8 非空，人工審）並加回歸。驗證：語料 55/55、`- (none — 可動)` 空、`- (none)` 後接 `- 等 …` 回真 blocker、`- none of the reviewers replied yet` 非空、CRLF 兩向皆正確。檔案：`scripts/lib/actionability.sh`、`fixtures/corpus-blocking.json`、`test.sh` 涵蓋需求：The blocking signal is read per bullet against a frozen corpus。 +- [x] 10.2 `idd_actionability_group` 增 `undiagnosed`；`idd-list` Step 5 增 `Needs diagnosis (N):` 組並保留 `→ /idd-diagnose #N`；Step 3.9 `--parked` 明文排除 missing / unparseable；spec R6 改三組。驗證：group 測試三組正確、drift guard 釘住組名與命令。涵蓋需求：Blocked-state output is preserved as a distinct display group。 +- [x] 10.3 `idd-implement` gate 移至 Step 0.35（tree-lock、建 branch、任何 egress 之前）；contract 加「gate SHALL precede any egress or branch creation」；測試釘住 gate 行號 < `git checkout -b` < 首個 `gh-egress.sh" comment`。 +- [x] 10.4 producer 禁令加範圍限定（正在診斷的該 issue）；`idd-issue` 與 live spec `idd-ic-r011-checkpoint`（spec delta）收斂為 `parking-lot`；測試 refute `blocker:infeasible`。 +- [x] 10.5 drift guard 補釘：verdict 條件式捕捉外殼、`REASONS=` 分支、`FATAL … misuse` 分支、issue 號驗型、author filter、allowed-tools `jq`/`python3`、`=$(gh issue view … --json comments` 全檔 refute。 +- [x] 10.6 in-scope 修正：`idd-all:1007` 分頁 + 3b.1 分頁 fallback；`idd-list` Step 3.7 取 Step 2 資料、≥100 才分頁、`|| …continue`、state guard、`REASONS` 重設、C0 剝除；`rules/sdd-integration.md` 移除平行解析敘述；row 905 真的帶 `- [~]`；fixture #160/#136 逐字；≥3 計數只算真實列；表頭 `VEXIT · CEXIT · TIER`；reference 增訊號 3 風險姿態、分母揭露、mention class、前置需求；158/158 → 159/159。 +- [~] 10.7 訊號 3 的 producer contract 或退回 model 判定 —— deferred to #336（超出本 change；第 3 輪為止血）。 + diff --git a/plugins/issue-driven-dev/.claude-plugin/plugin.json b/plugins/issue-driven-dev/.claude-plugin/plugin.json index a97213e..f9da844 100644 --- a/plugins/issue-driven-dev/.claude-plugin/plugin.json +++ b/plugins/issue-driven-dev/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "issue-driven-dev", - "description": "v3.0.0 (BREAKING): the closing-summary helper may VETO and may never PERMIT. After twelve verify rounds failing in one direction — a real summary the recogniser could not follow classified `missing`, and `missing` being the sole authorisation for `/idd-close --retroactive` to post a duplicate — the power was split along the direction that is sound. \"A marker IS here\" is an observation; \"a marker is NOT here\" is an inference from a failure to recognise, and no matcher over source bytes can answer a question about rendered output in the negative. Gate exit codes are now 1 (recognised) / 2 (undeterminable) / 10 (nothing recognised — NOT permission); there is no exit 0 in gate mode, deliberately, so a caller still reading `rc == 0 means go` breaks loudly. Gate class `missing` → `unrecognised`, every reply carries authorises:false, and a fifth class `mentioned` names the state the tool can actually observe. `--retroactive` loses its unattended path: the skill must read the comment set itself and obtain human confirmation that cannot be disabled. Classification now asks who wrote the comment, so a commenter can no longer move an issue between classes. Also: three more exit-0 parser paths, markup counted as content three layers deep, a quotation reaching `compliant`, the mention gate passing on zero iterations by three routes, untrusted prose reaching a shell command line, and #317 criterion (c) answered correctly for the first time in five attempts. Ten guards were mutation-proven vacuous and rebuilt.", + "description": "v3.1.0: the actionability gate, rounds 2 and 3. Round 1 read `### Complexity` against a closed value domain that the repository's own 159 diagnoses refuted (66 real values wrongly refused) and shipped a three-signal gate no consumer called. Now the tier is the leading whole word (rationale, decoration and ` via` suffixes are legal), the whole line is scanned for a small deferral vocabulary (exit 5, reason `complexity-deferral-marker` — a parked state, not a defect), `### Blocking` is read by a shared fence-aware helper, and idd-list / idd-all / idd-implement / idd-plan actually call the verdict with all three signals in a paginated, `set -e`-safe shape pinned by a drift test. A frozen 159-issue corpus fixture makes 'zero migration' falsifiable: 149 routable, 9 deferral, 1 missing, 0 unparseable. idd-list gains Parked and Needs-diagnosis groups; the #84 blocked surface is preserved verbatim. Round 3 read `### Blocking` per bullet with a leading-token placeholder rule frozen against the repo's 55 real sections (round 2 had withheld 31 of the 47 empty ones, including #316 itself), moved idd-implement's gate ahead of any branch or comment, and retired `blocker:*`.", "version": "3.1.0", "author": { "name": "Che Cheng" diff --git a/plugins/issue-driven-dev/CHANGELOG.md b/plugins/issue-driven-dev/CHANGELOG.md index b08e2a7..edfabbc 100644 --- a/plugins/issue-driven-dev/CHANGELOG.md +++ b/plugins/issue-driven-dev/CHANGELOG.md @@ -80,8 +80,55 @@ replaced. The producer's normal style is `**Plan** (decision-heavy at Finding 1) - `idd-diagnose` no longer declares a closed value domain for the field; it now says "write the tier clearly, rationale welcome; deferral goes on the label". +### Round 3 — the same failure shape, caught on the third signal + +`/idd-verify --pr 318` on round 2 returned FAIL (6 blocking). Every lens measured the new +`idd_blocking_section` against the repository's real issue bodies and got the same number: +of 55 `### Blocking` sections, 48 are semantically empty and **31 were judged live +blockers** — the reader anchored the none-placeholder to the whole line while the producer's +style is `- (none — 可動)`, `- (none) — closed`, `（無）`. The one open issue carrying the +section was **#316 itself**, so the change could not have been applied to its own tracking +issue. The Devil's Advocate additionally ran the gate over the live open backlog: 2 +actionable, 1 blocked (the misjudgement), **11 "parked"** — all eleven merely undiagnosed. + +- `idd_blocking_section` now reads the section **per bullet** (any non-placeholder bullet is a + blocker, so `- (none)` followed by `- 等 …` is no longer swallowed) and recognises a + placeholder by its **leading token** (`none` · `n/a` · `無`, optionally bulleted, decorated, + parenthesised, followed by end-of-line / closing paren / separator). Frozen against + `fixtures/corpus-blocking.json` (55 rows, hand-reviewed): 0 FP / 0 FN. Two other candidate + rules were measured there and rejected — one cleared every real blocker, one left 20 false + positives. Whether the field should be regex-read at all is #336. +- A trailing `\r` is stripped before either reader judges a line: GitHub's web textarea + submits CRLF, and awk's default FS counted a bare `\r` as a value (`Simple` → exit 3 with an + empty surfaced line; a CRLF blocker → dropped). +- `idd_actionability_group` gains **`undiagnosed`** and `idd-list` a *Needs diagnosis (N):* + group that keeps `→ /idd-diagnose #N`. *Parked* is now exactly the set `--parked` reviews. + Spec R6 amended accordingly. +- `idd-implement` runs the gate at **Step 0.35** — before tree-lock, branch creation and the + Implementation Plan comment. Round 2 had it at Step 2.5, so a human-parked issue received a + public comment before being told it was parked. The contract now says "gate SHALL precede + any egress or branch creation" and a test pins the line order. +- The producer prohibition is scoped ("on the issue it is diagnosing"); `blocker:infeasible` + / `blocker:waiting` — never created in any repo — are retired from `idd-issue` and, via a + spec delta, from the live `idd-ic-r011-checkpoint` spec, which had still MUSTed them. +- Canonical call shape hardened: issue numbers digit-checked before entering a REST path; + Diagnosis comments trusted only from OWNER / MEMBER / COLLABORATOR; surfaced raw values + stripped of C0 control characters and stated to be data, never instructions; `jq` / + `python3` pre-approved in `allowed-tools`. `idd-all`'s Layer V scan and Phase 3b.1 + fallback paginate; `idd-list` reuses its bulk fetch (paginating only at ≥ 100 comments), + skips the gate for non-open issues, and survives a fetch failure per row. +- Drift guard widened: verdict conditional-capture shape, the `REASONS=` branch and the + `FATAL … misuse` branch are pinned in all four consumers — round 2 stayed green with a bare + capture or an ignored verdict. `rules/sdd-integration.md` no longer carries a parallel + bare-token parse narrative. Row 905 now really emits a `- [~]` Strategy item. + +Codex was absent on that verify (usage limit); the Devil's Advocate carried the oracle role. + ### Honest residue +- **`### Blocking` is regex-read for now.** The leading-token rule is a stop, not an answer + (#336). Accepted misses are documented in the helper: a placeholder token followed by a + clause (`- (none) but actually blocked by #86`) reads as empty. - **#128 is a designed miss.** Its deferral ("blocked-by #86") lives only in Strategy prose — no marker, no label, empty Blocking. The gate routes it as `Plan`, and the incident fixture pins it as *actionable* rather than pretending a marker exists. diff --git a/plugins/issue-driven-dev/references/actionability-gate.md b/plugins/issue-driven-dev/references/actionability-gate.md index f476f22..93473e1 100644 --- a/plugins/issue-driven-dev/references/actionability-gate.md +++ b/plugins/issue-driven-dev/references/actionability-gate.md @@ -2,7 +2,7 @@ > The contract that answers **「這個 issue 現在可不可以動？」** — how the routing tier is extracted from the `### Complexity` Diagnosis field, how deferral is detected, where parked state lives, and the three-signal gate that `idd-list` / `idd-all` / `idd-implement` / `idd-plan` all consume. This file is the single source of truth; the four skills cite it and MUST NOT restate the rules in their own words. > -> **Source**: `add-actionability-gate` Spectra change (capability `actionability-gate`). Origin: issue-driven-development#298 → #316, surfaced from real dogfooding (2026-08-10 backlog routing). **Round 2** (2026-08-15): `/idd-verify --pr 318` falsified round 1's closed value domain against the real diagnosis corpus; the extraction rule below is the corrected one, validated on all 159 diagnoses in this repository. +> **Source**: `add-actionability-gate` Spectra change (capability `actionability-gate`). Origin: issue-driven-development#298 → #316, surfaced from real dogfooding (2026-08-10 backlog routing). **Round 2** (2026-08-15): `/idd-verify --pr 318` falsified round 1's closed value domain against the real diagnosis corpus; the extraction rule below is the corrected one, validated on all 159 diagnoses in this repository. **Round 3** (2026-09-07): the round-2 verify found the same failure shape on the third signal — the `### Blocking` reader had been written against an unvalidated producer assumption — and found that filing not-yet-diagnosed issues under *Parked* misdescribed 11 of 14 open issues. Both are corrected below, each with its own frozen corpus or live-backlog measurement. ## The incident this exists to prevent @@ -78,7 +78,11 @@ The rule was derived from and validated against every diagnosed issue in this re | `4` missing | 1 | #273 | | `3` unparseable | 0 | — | -Every one of the 159 routes as hand-reviewed; **0 false positives**. No Diagnosis comment was rewritten and no label was backfilled to get there — **zero migration** is a claim about this corpus, and the test is what makes it falsifiable. +| — no `## Diagnosis` comment at all | 66 of 225 | every one is exit 4 (`complexity-missing`) — see the *undiagnosed* group below | + +Every one of the 159 routes as hand-reviewed; **0 false positives**. No Diagnosis comment was rewritten and no label was backfilled to get there — **zero migration** is a claim about this corpus, and the test is what makes it falsifiable. Read it for what it says: *no existing diagnosis needs rewriting*. It does **not** say the backlog's actionability distribution is unchanged — on the 2026-09-07 open backlog only 2 of 14 issues were routable, because 11 had never been diagnosed. That is why the display distinguishes *undiagnosed* from *parked*. + +**Signal 3 has its own frozen corpus**: `scripts/tests/actionability-gate/fixtures/corpus-blocking.json` — every `### Blocking` section in the bodies of all 238 issues (55 sections, hand-reviewed: 47 empty, 8 non-empty). Round 2 shipped `idd_blocking_section` without this and withheld 31 of the 47 — including #316's own `- (none — 可動)`. The rule that is 0 FP / 0 FN on it is in the helper's comments; two other candidates were measured there and rejected (one cleared every real blocker, one left 20 false positives). ## Risk posture — the label is primary, the vocabulary is a net @@ -91,6 +95,10 @@ Deferral vocabulary is a **high-precision, low-recall heuristic**. It is NOT a c So the rule for adding a term: **corpus evidence of zero false positives**, recorded in the regression fixture. Resemblance to an existing term is not evidence. +**Signal 3 (`### Blocking`) has a different posture, and the difference matters.** It is a **list** field written by `idd-update`'s template `- {blocker 1, or "(none)"}`, model-filled, with 35+ spellings for "no blocker" in the wild. The reader therefore (a) judges **each bullet** — any non-placeholder bullet makes the section non-empty, so `- (none)` followed by `- 等 …` is a blocker — and (b) recognises a placeholder by its **leading token** (`none` · `n/a` · `無`, optionally bulleted, decorated or parenthesised, followed by end of line, a closing paren or a separator), so `- (none — 可動)` is empty while `- none of the reviewers replied yet` is not. Its failure directions are **not** symmetric with signal 1's: a miss here is not "pre-#298 behaviour", it is a regression of #84's blocked-state surfacing; a false positive is the hard stop the table above calls unacceptable. Accepted misses, documented: a placeholder token followed by a *clause* (`- (none) but actually blocked by #86`, `- n/a — blocked by #99`) reads as empty — the token wins. The corpus has none of these. Whether this field should be regex-read at all, or given a producer contract / returned to model judgement, is **#336**. + +**Mentions are not declarations — and the scan cannot tell them apart.** `Plan（把 parking lot 的文件敘述收斂）` and `Simple, no longer deferred` both trip the deferral scan. The corpus has zero such values, and negation logic would open a new miss surface, so the vocabulary is left as is; the operator sees the raw line and the remedy for this class is to keep meta-discussion out of the value line. + **A documented miss, kept honest.** #128's Diagnosis reads `Plan（觸發表）+ 未決 UX 軸 → **移入 discussion list**`; its deferral ("blocked-by #86") lives only in Strategy prose. Under this rule it routes as `Plan`. That is the designed outcome — the gate does not parse prose — and the fixture pins #128 as *actionable* rather than pretending a marker exists. If it should be withheld, a human applies the label. ## Where deferral state lives @@ -101,7 +109,7 @@ So the rule for adding a term: **corpus evidence of zero false positives**, reco | Deferral / parked | `parking-lot` label | **yes** | **a human** — see below | | External blocker | `### Blocking` in the issue body | yes | `idd-update` | -**`idd-diagnose` SHALL NOT apply, remove, or derive the `parking-lot` label.** The label is a human ruling, and it is settable *after* the diagnosis was written. Empirically the two signals disagree: of 11 diagnosed issues sampled on 2026-08-10, only 5 had the qualifier and the label in agreement. #37 was `**Spectra**` with the label applied later by a human; #131 and #200 had the qualifier with no label. They are not two spellings of one fact — they are two facts, and deriving one from the other would delete the human's ability to park an issue whose tier is perfectly clear. +**`idd-diagnose` SHALL NOT apply, remove, or derive the `parking-lot` label on the issue it is diagnosing.** The label is a human ruling, and it is settable *after* the diagnosis was written. (Scope: the IC_R011 checkpoint that idd-diagnose runs in Step 3.6 may attach `parking-lot` to a *newly filed sister issue* when the user classifies it (b) infeasible / (c) blocked-on-external — that is a human classification landing on a different issue, and since 3.1.0 it means the new issue is born parked. `blocker:infeasible` / `blocker:waiting` were never created in any repo and are retired everywhere IC_R011 is stated.) Empirically the two signals disagree: of 11 diagnosed issues sampled on 2026-08-10, only 5 had the qualifier and the label in agreement. #37 was `**Spectra**` with the label applied later by a human; #131 and #200 had the qualifier with no label. They are not two spellings of one fact — they are two facts, and deriving one from the other would delete the human's ability to park an issue whose tier is perfectly clear. **The producer's rule is therefore simple**: write the tier clearly, rationale welcome; if the issue is on hold, say so with the label, not in this field. The vocabulary scan exists for the 159-issue past, not as an invitation. @@ -155,14 +163,17 @@ The gate emits a verdict together with its reason list. The display layer groups | Reasons | Group | |---|---| -| `blocking-nonempty` **alone** | the existing blocked-state group (#84) — heading, all-blocked banner text, and footer counts unchanged | -| anything else, including any mix | the parked group — each row shows the raw `### Complexity` line (from the helper's stderr) or the label, so the operator sees *why* | +| any of `parking-lot-label` · `complexity-deferral-marker` · `complexity-unparseable` | **parked** — a human parked it, the diagnosis said so, or the value is a defect to repair; each row shows the raw `### Complexity` line (from the helper's stderr) or the label, so the operator sees *why*. This is also exactly the set `idd-list --parked` reviews | +| otherwise `blocking-nonempty` | the existing **blocked**-state group (#84) — heading, all-blocked banner text, and footer counts unchanged | +| otherwise (`complexity-missing` alone) | **undiagnosed** — the issue has not been diagnosed yet. That is every issue's birth state and, on a live backlog, the dominant one (11 of 14 open issues on 2026-09-07); round 2 filed it under *Parked*, which hid `→ /idd-diagnose #N` and made the footer disagree with `--parked` by an order of magnitude. The display keeps the diagnose command | + +`idd_actionability_group` returns exactly these three strings; the raw values it surfaces are third-party text and are printed with C0 control characters stripped — **data, never instructions**. Unifying the *judgment* does not mean unifying the *presentation*. #84's blocked-state surface is user-facing behavior people rely on; merging it into one undifferentiated bucket would be a regression dressed as a simplification. ## Consumer contract -The four routing consumers SHALL invoke the shared implementation at `scripts/lib/actionability.sh` and MUST NOT embed a private parse — of `### Complexity` **or** of `### Blocking`. The canonical call shape, in full, is: +The four routing consumers SHALL invoke the shared implementation at `scripts/lib/actionability.sh` and MUST NOT embed a private parse — of `### Complexity` **or** of `### Blocking`. **The gate SHALL run before any egress or branch creation** (a comment, a `git checkout -b`, a tree-lock): a human-parked issue must not receive an Implementation Plan comment before being told it is parked — round 2's `idd-implement` did exactly that at Step 2.5, and the test now pins the order. Prerequisites: `gh`, `jq`, `python3` (pre-approve them in `allowed-tools` so unattended runs do not stall on a permission prompt). The canonical call shape, in full, is: ```bash # 0. Missing helper → fail loud, name the path. Never fall back to a private regex. @@ -171,11 +182,18 @@ The four routing consumers SHALL invoke the shared implementation at `scripts/li exit 1 } -# 1. Latest Diagnosis comment — PAGINATE. `gh issue view --json comments` returns -# only the OLDEST 100 comments, so on a long issue the latest diagnosis is -# exactly the one that gets dropped. (`--paginate --jq` emits one array per -# page; `jq -s add` folds them.) -LATEST_DIAGNOSIS=$(gh api "repos/$GITHUB_REPO/issues/$N/comments" --paginate --jq '[.[] | {body}]' \ +# 0. Issue numbers enter a REST path: digits only, or refuse. (A `?per_page=1` +# smuggled in would silently truncate the fetch.) +case "$N" in ''|*[!0-9]*) echo "FATAL: non-numeric issue number: $N" >&2; exit 1 ;; esac + +# 1. Latest Diagnosis comment — PAGINATE, and TRUST ONLY repo-affiliated authors. +# `gh issue view --json comments` returns only the OLDEST 100 comments, so on +# a long issue the latest diagnosis is exactly the one that gets dropped +# (`--paginate --jq` emits one array per page; `jq -s add` folds them). On a +# public repo any account can append a `## Diagnosis`; without the author +# filter that comment would become signal 1. +LATEST_DIAGNOSIS=$(gh api "repos/$GITHUB_REPO/issues/$N/comments" --paginate \ + --jq '[.[] | select(.author_association == "OWNER" or .author_association == "MEMBER" or .author_association == "COLLABORATOR") | {body}]' \ | jq -s 'add // []' \ | python3 -c ' import json, sys, re @@ -201,16 +219,18 @@ if VERDICT=$(idd_actionability_verdict --complexity-exit "$CEXIT" --parking-labe case "$VEXIT" in 0) ;; # actionable → dispatch on "$TIER" 1) REASONS="${VERDICT#not-actionable: }" ;; # withheld → surface "$REASONS" + "$COMPLEXITY_ERR" / "$BLOCK_LINE"; no lifecycle command - *) echo "FATAL: idd_actionability_verdict misuse — $VERDICT" >&2; exit 1 ;; + *) echo "FATAL: idd_actionability_verdict misuse — $VERDICT" >&2; exit 1 ;; # a LISTING consumer prints this and marks the row `(gate error)` instead of exiting esac ``` +`idd-list` deviates in three documented ways: it takes labels/body/comments from its bulk fetch and paginates only when the comment array is ≥ 100 (its own anti-N+1 rule), it skips the gate for non-open issues, and every fetch failure marks the row rather than exiting — "one bad value does not suppress the other issues" applies to API errors too. + | Function | stdout | exit | |---|---|---| | `idd_parse_complexity ` | the leading tier (exit 0 only) | `0` routable · `3` no tier prefix (stderr `unparseable-complexity: `) · `4` no section (stderr `missing-complexity`) · `5` deferral vocabulary (stderr `deferral-marker: `) | -| `idd_blocking_section ` | first non-blank line of `### Blocking`, empty when absent or a `(none)` placeholder | `0` | +| `idd_blocking_section ` | the first **bullet** of `### Blocking` that is not a none-placeholder (leading-token rule); empty when the section is absent or every bullet is a placeholder | `0` | | `idd_actionability_verdict --complexity-exit 0|3|4|5 --parking-label yes|no --blocking-section yes|no` | `actionable` / `not-actionable: [; …]` | `0` actionable · `1` not actionable · `2` bad usage (missing value, non-boolean, unknown flag) | -| `idd_actionability_group ` | `blocked` / `parked` | `0` | +| `idd_actionability_group ` | `parked` / `blocked` / `undiagnosed` | `0` | **Only replacing the parser is not a fix.** Round 1 shipped a complete gate, 66 green assertions, and zero consumers calling `idd_actionability_verdict` (verify CRITICAL-1 on PR #318). A consumer that reads `$TIER` and never asks the gate has re-created the incident with a nicer parser. @@ -239,5 +259,6 @@ Per [`.claude/rules/attribute-assessment.md`](../../../.claude/rules/attribute-a - [`parallel-orchestration.md`](parallel-orchestration.md) — the `### Conflict Class` contract this one mirrors; orthogonal field, same discipline - [`rules/append-vs-modify.md`](../rules/append-vs-modify.md) — why a Diagnosis comment cannot hold mutable state -- `scripts/tests/actionability-gate/` — the incident fixture (`parked-routing.json`, verbatim 2026-08-10 rows plus corpus-sampled shapes) and the frozen corpus (`corpus-complexity.json`) +- `scripts/tests/actionability-gate/` — the incident fixture (`parked-routing.json`, verbatim 2026-08-10 rows plus corpus-sampled shapes), the frozen Complexity corpus (`corpus-complexity.json`, 159 rows) and the frozen Blocking corpus (`corpus-blocking.json`, 55 rows) +- **#336** — whether `### Blocking` should be regex-read at all (producer contract vs model judgement); **#337** — #84's `blocked`-label / wait-class display signals, retired from the gate path in 3.1.0 - **On enumerations.** The *reason* vocabulary is written as a closed list with an explicit no-analogy clause because it is one: a summarizing criterion plus examples is two specifications that drift apart silently. The *deferral* vocabulary is deliberately **not** presented that way — it is a heuristic with a stated add-criterion (corpus evidence, zero false positives) — because round 1 showed what happens when a heuristic is dressed up as a domain: it rejects the data it was meant to describe. diff --git a/plugins/issue-driven-dev/rules/sdd-integration.md b/plugins/issue-driven-dev/rules/sdd-integration.md index f234fc6..81d118c 100644 --- a/plugins/issue-driven-dev/rules/sdd-integration.md +++ b/plugins/issue-driven-dev/rules/sdd-integration.md @@ -233,13 +233,7 @@ If even one of these fails, keep `spectra-discuss` in the flow. ## Backward compat: `SDD-warranted` alias -For diagnosis comments written before v2.36.0: - -- `### Complexity\nSDD-warranted` → parse as `Spectra` -- `### Complexity\nSimple` → parse as `Simple` -- `### Complexity\nPlan` → only appears in v2.36.0+ comments - -Skills that read `### Complexity` (idd-all Phase 3, idd-implement Step 2.5) MUST treat `SDD-warranted` and `Spectra` as identical for routing. +`SDD-warranted` (diagnosis comments written before v2.36.0) is a backward-compat alias of `Spectra`: every routing consumer MUST treat the two as identical. **How the tier is extracted from `### Complexity` is not described here** — the single rule (leading tier, trailing rationale legal, deferral vocabulary, exit codes) lives in [`references/actionability-gate.md`](../references/actionability-gate.md) and its shared helper; do not restate it in this rule. New diagnosis comments (v2.36.0+) MUST emit `Spectra` — `SDD-warranted` is read-only legacy. diff --git a/plugins/issue-driven-dev/scripts/lib/actionability.sh b/plugins/issue-driven-dev/scripts/lib/actionability.sh index 666eb7f..07d7492 100644 --- a/plugins/issue-driven-dev/scripts/lib/actionability.sh +++ b/plugins/issue-driven-dev/scripts/lib/actionability.sh @@ -15,8 +15,9 @@ # no private parsing — that is the whole point of this file. Do not re-inline a # regex in a SKILL.md; extend here instead. # -# THE RULE (round 2, validated on all 159 real diagnoses in this repo: 158/158 -# correct, 0 false positives — see /idd-diagnose #316) +# THE RULE (round 2, validated on all 159 real diagnoses in this repo: 159/159 +# as hand-reviewed — 149 routable, 9 deferral, 1 correctly reported missing; +# 0 false positives — see /idd-diagnose #316 and the frozen corpus fixture) # 1. strip leading/trailing markdown decoration (`**`, `` ` ``, `_`) # 2. the value must BEGIN WITH one of Simple | Plan | Spectra | SDD-warranted # (whole word; longest match first). That leading word IS the tier. @@ -43,19 +44,25 @@ # ── section extraction (shared by both readers below) ──────────────────────── # +# _idd_section_lines +# stdout : every non-blank, non-subheading line under `### `, +# in order; empty when the section is absent or empty # _idd_section_first_line -# stdout : first non-blank, non-subheading line under `### `; -# empty when the section is absent or empty +# stdout : the first of those lines (the scalar-field reader) # +# - a trailing CR is stripped first: GitHub's web textarea submits CRLF, and +# awk's default FS does not treat `\r` as blank, so a CRLF "empty line" has +# NF=1 and would be taken as the value (verify #318 round-2 HIGH) # - heading anchored at line start, so prose mentioning "### Complexity" # cannot match # - ``` and ~~~ fences are tracked: a template example quoted inside a # fence is not a section (verify #318 H4) # - the section ends at the next heading of the same or higher level; -# a deeper `####` line is skipped, never taken as the value -_idd_section_first_line() { +# a deeper `####` line is skipped, never taken as a value +_idd_section_lines() { local body="${1-}" heading="${2-}" printf '%s\n' "$body" | awk -v h="$heading" ' + { sub(/\r$/, "") } { if (fence != "") { if (fence == "`" && $0 ~ /^[[:space:]]*```/) fence = "" @@ -68,9 +75,12 @@ _idd_section_first_line() { !grab && $0 ~ ("^###[[:space:]]+" h "[[:space:]]*$") { grab = 1; next } grab && /^(#|##|###)[[:space:]]/ { exit } grab && /^####/ { next } - grab && NF { print; exit } + grab && NF { print } ' } +_idd_section_first_line() { + _idd_section_lines "$1" "$2" | head -n 1 +} # ── contract 1: parse the Complexity field ─────────────────────────────────── # @@ -217,39 +227,78 @@ idd_actionability_verdict() { # ── contract 3: the third signal — `### Blocking` in the issue body ────────── # # idd_blocking_section -# stdout : the first non-blank line of the `### Blocking` section when it -# holds a real blocker; empty otherwise +# stdout : the first line of the `### Blocking` section that states a real +# blocker; empty when the section is absent or every bullet is a +# none-placeholder # exit 0 : always # -# idd-update writes `- (none)` into an empty section, so "non-empty" means -# "holds something other than a none-placeholder". Recognised placeholders, -# optionally bulleted and decorated, any case: (none) · none · n/a · - -# Consumers feed the result to the gate as -# --blocking-section "$([ -n "$BLOCK_LINE" ] && echo yes || echo no)" -# and may show $BLOCK_LINE as the blocked reason (#84 behaviour preserved). +# `### Blocking` is a LIST field (idd-update's template is a bullet list), so +# unlike `### Complexity` it is read per bullet: any bullet that is not a +# placeholder makes the section non-empty. Round 2 read only the first line — +# `- (none)` followed by a real `- 等 …` bullet came back empty (verify #318 +# round-2, logic HIGH-1). Lines that do not start a bullet are continuations +# of the bullet above and are not judged on their own. +# +# A placeholder is judged on its LEADING TOKEN, because the producer's real +# style is "placeholder + annotation": of the 55 `### Blocking` sections in +# this repo, 48 are semantically empty and 31 of those carry text after the +# token (`- (none — 可動)`, `- (none) — closed`, `（無）`). Round 2 anchored the +# match to the whole line and withheld all 31 — including #316 itself. The rule +# below is 0 FP / 0 FN on the hand-reviewed corpus frozen in +# scripts/tests/actionability-gate/fixtures/corpus-blocking.json; two other +# candidate rules were tested there and rejected (one cleared every real +# blocker, one left 20 false positives). +# +# Recognised token, any case, optionally bulleted / decorated / parenthesised: +# none · n/a · 無 followed by end of line, a closing paren, or a separator +# (— – - , 、 : ： ;). A bare bullet or bare decoration is also empty. +# Accepted misses (documented, not in the corpus): `- (none) but actually +# blocked by #86`, `- n/a — blocked by #99` read as empty; the token wins. +# A real blocker that happens to START with the token (`- none of the +# reviewers replied yet`) is NOT a placeholder because the token is followed by +# a word, not a terminator — that case is pinned by test. +_idd_is_none_placeholder() { # line + printf '%s\n' "$1" | grep -qiE '^[[:space:]]*([-*][[:space:]]+)?[_*`]*[（(]?[[:space:]]*(none|n/a|無)[_*`]*[[:space:]]*([)）]|$|[—–,、:：;-])' \ + || printf '%s\n' "$1" | grep -qE '^[[:space:]]*[-*]?[_*`]*[[:space:]]*$' +} idd_blocking_section() { - local body="${1-}" first - first=$(_idd_section_first_line "$body" Blocking) - if printf '%s\n' "$first" | grep -qiE '^[[:space:]]*([-*][[:space:]]+)?[_*`]*(\(none\)|none|n/a|-)?[_*`]*[[:space:]]*$'; then - return 0 - fi - printf '%s\n' "$first" + local body="${1-}" line first=1 + while IFS= read -r line; do + if [ "$first" = 1 ] || printf '%s\n' "$line" | grep -qE '^[[:space:]]*[-*][[:space:]]'; then + first=0 + if ! _idd_is_none_placeholder "$line"; then + printf '%s\n' "$line" + return 0 + fi + fi + done < <(_idd_section_lines "$body" Blocking) + return 0 } # ── display helper: which group does a not-actionable issue belong to? ─────── # # idd_actionability_group -# stdout : "blocked" | "parked" +# stdout : "blocked" | "parked" | "undiagnosed" # -# Reason `blocking-nonempty` ALONE keeps the pre-#298 blocked-state grouping -# (#84) intact — its heading, banner and footer counts are user-facing behavior -# that must not regress. Everything else — parking-lot-label, any of the three -# complexity reasons, or a mix that includes blocking — lands in the parked -# group, where the raw Complexity value is shown alongside the reason. +# parked — any of parking-lot-label / complexity-deferral-marker / +# complexity-unparseable is present (a human parked it, the +# diagnosis said so, or the value is a defect to repair) +# blocked — otherwise, blocking-nonempty is present: reason +# `blocking-nonempty` ALONE keeps the pre-#298 blocked-state +# grouping (#84) intact — heading, banner and footer counts are +# user-facing behavior that must not regress +# undiagnosed — otherwise (complexity-missing alone): the issue has simply +# not been diagnosed yet. That is every issue's birth state, not +# a parked state — on the live backlog it is the DOMINANT state +# (11 of 14 open issues on 2026-09-07), and filing it under +# "Parked" hid `→ /idd-diagnose #N` from the operator (verify +# #318 round-2 DA-CRIT-1). The display keeps that command. idd_actionability_group() { local reasons="${1-}" case "$reasons" in - "blocking-nonempty") printf 'blocked\n' ;; - *) printf 'parked\n' ;; + *parking-lot-label*|*complexity-deferral-marker*|*complexity-unparseable*) printf 'parked\n' ;; + *blocking-nonempty*) printf 'blocked\n' ;; + *complexity-missing*) printf 'undiagnosed\n' ;; + *) printf 'parked\n' ;; esac } diff --git a/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/corpus-blocking.json b/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/corpus-blocking.json new file mode 100644 index 0000000..6273d2e --- /dev/null +++ b/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/corpus-blocking.json @@ -0,0 +1,505 @@ +{ + "_provenance": "Every `### Blocking` section found in the BODY of the 238 issues of PsychQuant/issue-driven-development (snapshot 2026-09-07, `gh issue list --state all --limit 400`): 55 sections, hand-reviewed — 47 semantically empty (a none-placeholder, with or without annotation), 8 non-empty (7 real blockers that all begin with `- 等 …`, plus #1 whose second bullet is a note read as non-empty by the per-bullet rule — accepted, see its note). Rows carry every non-blank line of the section verbatim. Frozen regression baseline for `idd_blocking_section`; do NOT regenerate from live GitHub.", + "rows": [ + { + "number": 1, + "state": "CLOSED", + "section": [ + "- (none) — 所有 27 spec tasks done;3 P0 + 5 P1 round-1 blockers closed via 5fc39fc;AC #5/#6 closed via smoke test", + "- 12 個 P2/P3 follow-up 整合為 9 個 focused issue (#2-#10),全部 ref Related: #1" + ], + "expect_empty": false, + "expect_first_blocker": "- 12 個 P2/P3 follow-up 整合為 9 個 focused issue (#2-#10),全部 ref Related: #1", + "note": "Second bullet is an informational note, not a blocker — the per-bullet rule reads it as non-empty. Accepted 1/55 false positive on a CLOSED issue; the structural fix is #336 (producer contract)." + }, + { + "number": 12, + "state": "CLOSED", + "section": [ + "- (none — closed)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 13, + "state": "CLOSED", + "section": [ + "- 等 re-verify 確認 13 fixes 全 effective,verdict PASS" + ], + "expect_empty": false, + "expect_first_blocker": "- 等 re-verify 確認 13 fixes 全 effective,verdict PASS" + }, + { + "number": 26, + "state": "CLOSED", + "section": [ + "- (none — closed)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 37, + "state": "CLOSED", + "section": [ + "- 等 re-park trigger 之一成立（見 2026-08-10 decision comment「Re-park 的 trigger 條件」）：", + " (1) #298 落地後 triage 準確率可接受 /", + " (2) 出現 actionable-Simple-tier 子集 ≥3 的 backlog /", + " (3) 自動化 caller 卡 Phase 6 產生既有 `/idd-all #a #b #c` 無法解決的實際痛點" + ], + "expect_empty": false, + "expect_first_blocker": "- 等 re-park trigger 之一成立（見 2026-08-10 decision comment「Re-park 的 trigger 條件」）：" + }, + { + "number": 44, + "state": "CLOSED", + "section": [ + "- (none — closed via /idd-close 2026-05-10 with retroactive Implementation Complete supersession)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 45, + "state": "CLOSED", + "section": [ + "- 等 user 確認 diagnosis 後跑 `/idd-plan #45` 進 EnterPlanMode approval gate" + ], + "expect_empty": false, + "expect_first_blocker": "- 等 user 確認 diagnosis 後跑 `/idd-plan #45` 進 EnterPlanMode approval gate" + }, + { + "number": 46, + "state": "CLOSED", + "section": [ + "- (none)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 47, + "state": "CLOSED", + "section": [ + "- (none — closed via PR #50 squash merge + retroactive closing summary)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 48, + "state": "CLOSED", + "section": [ + "- (none — closed)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 49, + "state": "CLOSED", + "section": [ + "- 等 user 跑 /idd-verify --pr 58 (cluster-PR mode 6-AI ensemble)" + ], + "expect_empty": false, + "expect_first_blocker": "- 等 user 跑 /idd-verify --pr 58 (cluster-PR mode 6-AI ensemble)" + }, + { + "number": 51, + "state": "CLOSED", + "section": [ + "- 等 user 跑 /idd-plan #51 進 EnterPlanMode 對齊 signature" + ], + "expect_empty": false, + "expect_first_blocker": "- 等 user 跑 /idd-plan #51 進 EnterPlanMode 對齊 signature" + }, + { + "number": 52, + "state": "CLOSED", + "section": [ + "- (none — issue closed)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 53, + "state": "CLOSED", + "section": [ + "- 等 user 跑 /idd-verify --pr 58 (cluster-PR mode 6-AI ensemble)" + ], + "expect_empty": false, + "expect_first_blocker": "- 等 user 跑 /idd-verify --pr 58 (cluster-PR mode 6-AI ensemble)" + }, + { + "number": 54, + "state": "CLOSED", + "section": [ + "- (none)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 55, + "state": "CLOSED", + "section": [ + "- (none — issue closed)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 102, + "state": "CLOSED", + "section": [ + "- (none — Implementation Plan approved, ready for `/idd-implement #102`)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 103, + "state": "CLOSED", + "section": [ + "- (none — PR #104 ready for merge → `/idd-close #103`)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 105, + "state": "CLOSED", + "section": [ + "- (none — ready for /idd-plan #105 (per chain shell unattended, idd-plan EnterPlanMode auto-applies))" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 107, + "state": "CLOSED", + "section": [ + "- (none — ready for /idd-implement #107)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 108, + "state": "CLOSED", + "section": [ + "- (none — ready for /idd-plan #108 (per chain shell unattended, idd-plan EnterPlanMode auto-applies))" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 116, + "state": "CLOSED", + "section": [ + "- 等 `/spectra-discuss` 對齊以下 open questions: acceptance metric proxy 怎麼定?jsonl schema(`verify-runs/.jsonl`)欄位?phase 1/2/3 是否一次走完還是逐 phase ship?" + ], + "expect_empty": false, + "expect_first_blocker": "- 等 `/spectra-discuss` 對齊以下 open questions: acceptance metric proxy 怎麼定?jsonl schema(`verify-runs/.jsonl`)欄位?phase 1/2/3 是否一次走完還是逐 phase ship?" + }, + { + "number": 119, + "state": "CLOSED", + "section": [ + "- (none)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 121, + "state": "CLOSED", + "section": [ + "- (none)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 125, + "state": "CLOSED", + "section": [ + "- (none) — closed" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 137, + "state": "CLOSED", + "section": [ + "- (none — issue closed)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 147, + "state": "CLOSED", + "section": [ + "- (none)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 150, + "state": "CLOSED", + "section": [ + "- (none — issue closed; #154 inherits runtime enforcement work)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 151, + "state": "CLOSED", + "section": [ + "- (none — closed)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 152, + "state": "CLOSED", + "section": [ + "- (none)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 154, + "state": "CLOSED", + "section": [ + "- (none)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 155, + "state": "CLOSED", + "section": [ + "- (none — was the blocker for #154; #154 now unblocked)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 156, + "state": "CLOSED", + "section": [ + "- (none)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 160, + "state": "CLOSED", + "section": [ + "- (none)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 164, + "state": "CLOSED", + "section": [ + "- (none) — 原「等 user 自行執行 `/spectra-propose`」為 stale 記錄：該 propose 已於 2026-06-01 消化（見 comment「Propose → parked change created」）；2026-07-18 user 確認不再為剩餘小項開新 propose" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 167, + "state": "CLOSED", + "section": [ + "- (none) — closed via PR #168 (squash b11b65d). Spectra change archived. Follow-ups: #169 (convention reconciliation), #170 (post-IC detection)." + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 169, + "state": "CLOSED", + "section": [ + "- (none) — diagnosed, awaiting pickup" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 170, + "state": "CLOSED", + "section": [ + "- (none) — closed via PR #171 (squash 4b79694). Follow-ups: #172 (membership semantics), #173 (template auto-close trap)." + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 173, + "state": "CLOSED", + "section": [ + "- (none — closed)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 176, + "state": "CLOSED", + "section": [ + "- (none — closed)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 178, + "state": "CLOSED", + "section": [ + "- (none)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 179, + "state": "CLOSED", + "section": [ + "- (none)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 180, + "state": "CLOSED", + "section": [ + "- (none)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 181, + "state": "CLOSED", + "section": [ + "- (none)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 183, + "state": "CLOSED", + "section": [ + "- (none)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 186, + "state": "CLOSED", + "section": [ + "- (none)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 189, + "state": "CLOSED", + "section": [ + "- (none)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 209, + "state": "CLOSED", + "section": [ + "- (none) — closed" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 214, + "state": "CLOSED", + "section": [ + "- (none) — closed；4 commits 已 push；residue acknowledged as-is；distribution chain 進行中" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 276, + "state": "CLOSED", + "section": [ + "- (none) —— Phase 1 待 maintainer review draft PR #279；Phase 2 未開工，不阻塞 Phase 1" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 289, + "state": "CLOSED", + "section": [ + "- (none)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 290, + "state": "CLOSED", + "section": [ + "- (none) — 已結案。" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 295, + "state": "CLOSED", + "section": [ + "（無）" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 298, + "state": "CLOSED", + "section": [ + "- (none — 可動)" + ], + "expect_empty": true, + "expect_first_blocker": null + }, + { + "number": 316, + "state": "OPEN", + "section": [ + "- (none — 可動)" + ], + "expect_empty": true, + "expect_first_blocker": null + } + ] +} diff --git a/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/parked-routing.json b/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/parked-routing.json index 7476fed..8631119 100644 --- a/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/parked-routing.json +++ b/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/parked-routing.json @@ -213,7 +213,7 @@ { "number": 905, "snapshot": false, - "note": "Synthetic. A Strategy checklist skip marker MUST NOT withhold the issue — that marker belongs to idd-close, not to routing.", + "note": "Synthetic. A Strategy checklist skip marker MUST NOT withhold the issue — that marker belongs to idd-close, not to routing. The `strategy` field makes the test actually emit a `### Strategy` section containing `- [~]` (round 2 only claimed to).", "complexity_raw": "Simple", "labels": [ "enhancement" @@ -222,7 +222,8 @@ "expect_parse_exit": 0, "expect_tier": "Simple", "expect_verdict": "actionable", - "expect_reasons": [] + "expect_reasons": [], + "strategy": "- [~] Add Redis cache layer — deferred: waiting on infra team's Redis rollout" }, { "number": 264, @@ -254,7 +255,7 @@ "number": 160, "snapshot": false, "note": "Real corpus value. Tier + em-dash rationale.", - "complexity_raw": "Simple — 單檔、2 個 1-token 補丁、clear、#154 已立 fix 範本；非 decision-heavy", + "complexity_raw": "Simple — 單檔、2 個 1-token 補丁、clear、#154 已立 fix 範本；非 decision-heavy、風險近零（有 test 覆蓋）。", "labels": [ "enhancement" ], @@ -267,7 +268,7 @@ "number": 136, "snapshot": false, "note": "Real corpus value. Bare-looking tier, deferral vocabulary hidden inside the parenthetical — scanning only the suffix after the tier would MISS this.", - "complexity_raw": "**Spectra**(Layer 2 + Layer 3 if/when triggered):若實作,會修改既有 published `idd-edit` SKILL.md", + "complexity_raw": "**Spectra**(Layer 2 + Layer 3 if/when triggered):若實作,會修改既有 published `idd-edit` SKILL.md normative behavior,且新增 cross-skill protocol contract。**但目前狀態 = parking lot,Spectra 不立即 trigger。**", "labels": [ "enhancement", "parking-lot" diff --git a/plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh b/plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh index 2c89a81..a24c69f 100755 --- a/plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh +++ b/plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh @@ -37,6 +37,11 @@ # The `- [~]` Strategy skip marker is deliberately NOT a gate input — it is a # close-time per-item disposition owned by idd-close. Row 905 pins that. # +# Round 3 (verify #318 round 2) adds: per-bullet `### Blocking` reader with a +# leading-token placeholder rule frozen against corpus-blocking.json, CRLF +# handling, the `undiagnosed` display group, and drift guards that pin the +# consumers' verdict capture shape, branch/egress ordering and input hygiene. +# # Usage: bash test.sh (exit 0 = pass, 1 = fail) set -u @@ -75,7 +80,12 @@ run_bounded() { # secs fn args... # __NULL__ → no `### Complexity` section at all # fenced=1 → no real section either, but a fenced example of the template # sits in prose (a non-fence-aware extractor would grab it) -synth_body() { # raw_or_NULL fenced +synth_body() { # raw_or_NULL fenced [strategy-line] + local raw="$1" fenced="${2:-0}" strategy="${3:-}" + { synth_body_core "$raw" "$fenced" + [ -n "$strategy" ] && printf '\n### Strategy\n\n- [x] done item\n%s\n- [ ] open item\n' "$strategy"; } +} +synth_body_core() { # raw_or_NULL fenced local raw="$1" fenced="${2:-0}" if [ "$fenced" = "1" ]; then printf '## Diagnosis\n\n### Type\n\nbug\n\n### Notes\n\nThe template looks like this:\n\n```markdown\n### Complexity\n\nSimple\n```\n\nand also:\n\n~~~\n### Complexity\n\nPlan when triggered\n~~~\n\n### Risks\n\n- none\n' @@ -96,6 +106,7 @@ while IFS= read -r row; do snapshot=$(jq -r '.snapshot' <<<"$row") raw=$(jq -r 'if .complexity_raw == null then "__NULL__" else .complexity_raw end' <<<"$row") fenced=$(jq -r 'if .fenced_example == true then "1" else "0" end' <<<"$row") + strategy=$(jq -r '.strategy // ""' <<<"$row") exp_exit=$(jq -r '.expect_parse_exit' <<<"$row") exp_tier=$(jq -r 'if .expect_tier == null then "" else .expect_tier end' <<<"$row") exp_verdict=$(jq -r '.expect_verdict' <<<"$row") @@ -103,7 +114,7 @@ while IFS= read -r row; do has_label=$(jq -r 'if (.labels | index("parking-lot")) then "yes" else "no" end' <<<"$row") blocking_src=$(jq -r '.blocking // "- (none)"' <<<"$row") - body=$(synth_body "$raw" "$fenced") + body=$(synth_body "$raw" "$fenced" "$strategy") if [ "$HELPER_PRESENT" -eq 0 ]; then fail "#$num parse exit" "$missing_helper_note" @@ -200,18 +211,76 @@ if [ "$HELPER_PRESENT" -eq 1 ]; then idd_parse_complexity "$body" 2>/dev/null >/dev/null assert_exit "CJK deferral marker detected" "5" "$?" - # ── contract 3: ### Blocking reader ──────────────────────────────────────── + # ── contract 3: ### Blocking reader (per bullet, leading-token placeholder) ── assert_eq "blocking: real blocker → first line" "- 等 /spectra-discuss 對齊 acceptance metric proxy" \ "$(idd_blocking_section $'## Current Status\n\n### Blocking\n- 等 /spectra-discuss 對齊 acceptance metric proxy\n- second line\n\n### Tasks\n- [ ] x')" - assert_eq "blocking: idd-update placeholder is empty" "" "$(idd_blocking_section $'### Blocking\n- (none)\n')" - assert_eq "blocking: bare (none) is empty" "" "$(idd_blocking_section $'### Blocking\n\n(none)\n')" - assert_eq "blocking: decorated none is empty" "" "$(idd_blocking_section $'### Blocking\n_none_\n')" - assert_eq "blocking: N/A is empty" "" "$(idd_blocking_section $'### Blocking\nN/A\n')" - assert_eq "blocking: absent section is empty" "" "$(idd_blocking_section $'### Type\nbug\n')" - assert_eq "blocking: fenced copy is not a section" "" "$(idd_blocking_section $'### Notes\n```\n### Blocking\n- real\n```\n')" - assert_eq "blocking: higher heading ends section" "" "$(idd_blocking_section $'### Blocking\n\n## Next\n- not a blocker\n')" + assert_eq "blocking: idd-update placeholder is empty" "" "$(idd_blocking_section $'### Blocking\n- (none)\n')" + assert_eq "blocking: annotated placeholder is empty (#316's own body)" "" "$(idd_blocking_section $'### Blocking\n- (none — 可動)\n')" + assert_eq "blocking: placeholder + dash annotation is empty" "" "$(idd_blocking_section $'### Blocking\n- (none) — diagnosed, awaiting pickup\n')" + assert_eq "blocking: bare (none) is empty" "" "$(idd_blocking_section $'### Blocking\n\n(none)\n')" + assert_eq "blocking: CJK placeholder is empty" "" "$(idd_blocking_section $'### Blocking\n（無）\n')" + assert_eq "blocking: decorated none is empty" "" "$(idd_blocking_section $'### Blocking\n_none_\n')" + assert_eq "blocking: N/A is empty" "" "$(idd_blocking_section $'### Blocking\nN/A\n')" + assert_eq "blocking: bare bullet is empty" "" "$(idd_blocking_section $'### Blocking\n-\n')" + assert_eq "blocking: absent section is empty" "" "$(idd_blocking_section $'### Type\nbug\n')" + assert_eq "blocking: fenced copy is not a section" "" "$(idd_blocking_section $'### Notes\n```\n### Blocking\n- real\n```\n')" + assert_eq "blocking: higher heading ends section" "" "$(idd_blocking_section $'### Blocking\n\n## Next\n- not a blocker\n')" + # per-bullet: a placeholder does not short-circuit the bullets after it + assert_eq "blocking: placeholder then real bullet → the real bullet" "- 等 upstream #310 merge" \ + "$(idd_blocking_section $'### Blocking\n- (none)\n- 等 upstream #310 merge\n')" + assert_eq "blocking: annotated placeholder then real bullet → the real bullet" "- 等 collaborator 回信" \ + "$(idd_blocking_section $'### Blocking\n- (none — closed)\n- 等 collaborator 回信\n')" + assert_eq "blocking: continuation line under a placeholder is not a bullet" "" \ + "$(idd_blocking_section $'### Blocking\n- (none — closed)\n see the closing summary for details\n')" + assert_eq "blocking: continuation line under a blocker keeps the blocker" "- 等 re-park trigger 之一成立：" \ + "$(idd_blocking_section $'### Blocking\n- 等 re-park trigger 之一成立：\n (1) #298 落地後 triage 準確率可接受\n')" + # token followed by a WORD is a blocker, not a placeholder assert_eq "blocking: 'none' inside a real blocker is kept" "- none of the reviewers replied yet" \ "$(idd_blocking_section $'### Blocking\n- none of the reviewers replied yet\n')" + assert_eq "blocking: 'None yet, but …' is kept" "- None yet, but waiting on X" \ + "$(idd_blocking_section $'### Blocking\n- None yet, but waiting on X\n')" + # documented accepted misses: the leading token wins over a trailing clause + assert_eq "blocking: DOCUMENTED MISS — '(none) but actually blocked by' reads empty" "" \ + "$(idd_blocking_section $'### Blocking\n- (none) but actually blocked by #86\n')" + # CRLF (GitHub web textarea): both directions + assert_eq "blocking: CRLF real blocker is kept" "- 等 upstream #310" "$(idd_blocking_section $'### Blocking\r\n\r\n- 等 upstream #310\r\n')" + assert_eq "blocking: CRLF placeholder is empty" "" "$(idd_blocking_section $'### Blocking\r\n- (none)\r\n')" + tier=$(idd_parse_complexity $'### Complexity\r\n\r\nSimple\r\n' 2>/dev/null); rc=$? + assert_exit "complexity: CRLF bare tier routes (exit)" "0" "$rc" + assert_eq "complexity: CRLF bare tier routes (tier)" "Simple" "$tier" + idd_parse_complexity $'### Complexity\r\n\r\nSimple when triggered\r\n' 2>/dev/null >/dev/null + assert_exit "complexity: CRLF deferral is exit 5, not 3" "5" "$?" + # deeper heading inside the section is skipped, never taken as the value + tier=$(idd_parse_complexity $'### Complexity\n#### tier\nPlan\n' 2>/dev/null); rc=$? + assert_exit "complexity: #### line is skipped (exit)" "0" "$rc" + assert_eq "complexity: #### line is skipped (tier)" "Plan" "$tier" + + # ── corpus regression for signal 3 (verify #318 round-2 CRITICAL): every real + # `### Blocking` section in this repo, hand-reviewed. 47 empty / 8 non-empty. + # Round 2 withheld 31 of the 47. ── + BCORPUS="$HERE/fixtures/corpus-blocking.json" + if [ -f "$BCORPUS" ]; then + b_ok=0; b_total=0; b_empty=0; b_block=0 + while IFS= read -r row; do + b_total=$((b_total + 1)) + num=$(jq -r '.number' <<<"$row") + exp_empty=$(jq -r '.expect_empty' <<<"$row") + exp_first=$(jq -r '.expect_first_blocker // ""' <<<"$row") + sec=$(jq -r '.section | join("\n")' <<<"$row") + got=$(idd_blocking_section "$(printf '## Current Status\n\n### Phase\n\nx\n\n### Blocking\n%s\n\n### Tasks\n\n- [ ] x\n' "$sec")") + if [ "$exp_empty" = "true" ]; then + b_empty=$((b_empty + 1)) + if [ -z "$got" ]; then b_ok=$((b_ok + 1)); else fail "blocking corpus #$num" "expected empty, got: $got"; fi + else + b_block=$((b_block + 1)) + if [ "$got" = "$exp_first" ]; then b_ok=$((b_ok + 1)); else fail "blocking corpus #$num" "expected '$exp_first', got '$got'"; fi + fi + done < <(jq -c '.rows[]' "$BCORPUS") + assert_eq "blocking corpus: every section judged as reviewed ($b_ok/$b_total)" "$b_total" "$b_ok" + assert_eq "blocking corpus: 55 sections, 47 empty / 8 non-empty" "55/47/8" "$b_total/$b_empty/$b_block" + else + fail "blocking corpus" "fixture missing: $BCORPUS" + fi # ── audit discipline: the cheap path must not be the unsafe one ──────────── # A gate that treated an unanswered signal as "clear" would re-open the hole @@ -250,7 +319,9 @@ if [ "$HELPER_PRESENT" -eq 1 ]; then assert_eq "blocking-only → blocked group" "blocked" "$(idd_actionability_group 'blocking-nonempty')" assert_eq "parking label → parked group" "parked" "$(idd_actionability_group 'parking-lot-label')" assert_eq "unparseable → parked group" "parked" "$(idd_actionability_group 'complexity-unparseable')" - assert_eq "missing → parked group" "parked" "$(idd_actionability_group 'complexity-missing')" + assert_eq "missing alone → undiagnosed group" "undiagnosed" "$(idd_actionability_group 'complexity-missing')" + assert_eq "missing + blocking → blocked group" "blocked" "$(idd_actionability_group 'complexity-missing; blocking-nonempty')" + assert_eq "deferral + blocking → parked group" "parked" "$(idd_actionability_group 'complexity-deferral-marker; blocking-nonempty')" assert_eq "deferral marker → parked group" "parked" "$(idd_actionability_group 'complexity-deferral-marker')" assert_eq "mixed reasons → parked group" "parked" "$(idd_actionability_group 'complexity-unparseable; blocking-nonempty')" @@ -286,15 +357,36 @@ for c in idd-list idd-all idd-implement idd-plan; do assert_output_grep "$c: set -e safe conditional capture" 'if TIER=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>/dev/null); then CEXIT=0; else CEXIT=$?; fi' "$f" assert_output_grep "$c: paginates the comments fetch" '/comments" --paginate --jq' "$f" refute_output_grep "$c: no truncating --json comments fetch for the diagnosis" 'LATEST_DIAGNOSIS=$(gh issue view' "$f" + refute_grep_re "$c: no oldest-100 --json comments connection anywhere" '=\$\(gh issue view[^)]*--json comments' "$(cat "$f")" + assert_output_grep "$c: set -e safe verdict capture" 'if VERDICT=$(idd_actionability_verdict --complexity-exit "$CEXIT" --parking-label "$HAS_PARKING" --blocking-section "$BLOCKING" 2>&1); then VEXIT=0; else VEXIT=$?; fi' "$f" + assert_output_grep "$c: branches on the verdict" 'REASONS="${VERDICT#not-actionable: }"' "$f" + assert_output_grep "$c: exit 2 is a consumer FATAL" 'FATAL: idd_actionability_verdict misuse' "$f" + assert_output_grep "$c: issue number is digit-checked before the REST path" "*[!0-9]*) " "$f" + assert_output_grep "$c: Diagnosis author is trusted-only" 'author_association' "$f" refute_output_grep "$c: no closed-domain wording for the tier field" '封閉值域外' "$f" refute_output_grep "$c: no 'closed domain, no fifth value' tier claim" '不得依相似性外推第五個' "$f" done +for c in idd-list idd-all idd-implement; do + f="$SKILLS/$c/SKILL.md" + assert_output_grep "$c: allowed-tools pre-approves jq" 'Bash(jq:*)' "$f" + assert_output_grep "$c: allowed-tools pre-approves python3" 'Bash(python3:*)' "$f" +done +# gate SHALL precede any egress or branch creation (verify #318 round-2 HIGH: idd-implement) +IMPL="$SKILLS/idd-implement/SKILL.md" +gate_ln=$(grep -n 'if VERDICT=$(idd_actionability_verdict' "$IMPL" | head -1 | cut -d: -f1) +branch_ln=$(grep -nE '^[[:space:]]*git checkout -b' "$IMPL" | head -1 | cut -d: -f1) # the command line, not a prose mention +egress_ln=$(grep -n 'gh-egress.sh" comment' "$IMPL" | head -1 | cut -d: -f1) +assert_true "idd-implement: gate precedes branch creation (gate@${gate_ln:-?} < branch@${branch_ln:-?})" "[ -n '$gate_ln' ] && [ -n '$branch_ln' ] && [ '$gate_ln' -lt '$branch_ln' ]" +assert_true "idd-implement: gate precedes first egress (gate@${gate_ln:-?} < egress@${egress_ln:-?})" "[ -n '$gate_ln' ] && [ -n '$egress_ln' ] && [ '$gate_ln' -lt '$egress_ln' ]" # #84 surface preserved verbatim (spec R6) L="$SKILLS/idd-list/SKILL.md" assert_output_grep "idd-list: #84 blocked group heading verbatim" 'Blocked (waiting on external):' "$L" assert_output_grep "idd-list: #84 all-blocked banner verbatim" '✋ 所有可控事項已完成 — N 個 open issue 全部等待外部回應（詳見上表 blocker）。' "$L" assert_output_grep "idd-list: #84 footer count verbatim" '`X actionable, Y blocked`' "$L" assert_output_grep "idd-list: parked group present" 'Parked (not routable now):' "$L" +assert_output_grep "idd-list: undiagnosed group present" 'Needs diagnosis (' "$L" +assert_output_grep "idd-list: undiagnosed rows keep the diagnose command" '→ /idd-diagnose #' "$L" +assert_output_grep "idd-list: state guard before the gate" '"$STATE" = "open"' "$L" assert_output_grep "idd-list: groups via the helper" 'idd_actionability_group "$REASONS"' "$L" # reference + producer (9.1 / 9.2) assert_output_grep "reference: cites the 159-diagnosis corpus" '159' "$REF" @@ -304,7 +396,11 @@ refute_output_grep "reference: no closed tier domain claim" 'The legal va D="$SKILLS/idd-diagnose/SKILL.md" refute_output_grep "idd-diagnose: no closed-enumeration tier claim" '只得是下列四個值之一' "$D" assert_output_grep "idd-diagnose: tier-prefix rule stated" '必須以四個 tier 之一開頭' "$D" -assert_output_grep "idd-diagnose: producer never derives the label" 'SHALL NOT 貼、移除或推導 `parking-lot` label' "$D" +assert_output_grep "idd-diagnose: producer never derives the label — scoped to the issue under diagnosis" 'SHALL NOT 對**正在診斷的該 issue**貼、移除或推導 `parking-lot` label' "$D" +refute_output_grep "idd-issue: no blocker:* label mandate left" 'blocker:infeasible' "$SKILLS/idd-issue/SKILL.md" +refute_output_grep "sdd-integration: no parallel Complexity parse narrative" '→ parse as `Simple`' "$HERE/../../../rules/sdd-integration.md" +assert_output_grep "reference: signal-3 risk posture present" 'Signal 3 (`### Blocking`)' "$REF" +assert_output_grep "reference: undiagnosed group documented" 'undiagnosed' "$REF" # ── task 8.2 / spec R8: full-corpus regression. Every diagnosed issue in this # repo (159, frozen 2026-08-15) must route exactly as hand-reviewed: @@ -346,11 +442,11 @@ assert_eq "snapshot actionable = #37 + #128 (documented prose-deferral miss)" "3 # spec R8 scenario: the fixture reflects real shapes, ≥3 each. Shape is judged # on the raw value; deferral rows are counted by expected exit. -n_bare=$(jq '[.[] | select(.complexity_raw != null) | select(.complexity_raw | test("^(Simple|Plan|Spectra|SDD-warranted)$"))] | length' "$FIXTURE") -n_deco=$(jq '[.[] | select(.complexity_raw != null) | select(.complexity_raw | test("^[*`_]"))] | length' "$FIXTURE") -n_rat=$(jq '[.[] | select(.complexity_raw != null) | select(.expect_parse_exit == 0) | select(.complexity_raw | test("^(Simple|Plan|Spectra|SDD-warranted)$") | not) | select(.complexity_raw | test("^[*`_]") | not)] | length' "$FIXTURE") -n_def=$(jq '[.[] | select(.expect_parse_exit == 5)] | length' "$FIXTURE") -assert_true "≥3 bare-tier rows ($n_bare)" "[ $n_bare -ge 3 ]" +n_bare=$(jq '[.[] | select(.number < 900) | select(.complexity_raw != null) | select(.complexity_raw | test("^(Simple|Plan|Spectra|SDD-warranted)$"))] | length' "$FIXTURE") +n_deco=$(jq '[.[] | select(.number < 900) | select(.complexity_raw != null) | select(.complexity_raw | test("^[*`_]"))] | length' "$FIXTURE") +n_rat=$(jq '[.[] | select(.number < 900) | select(.complexity_raw != null) | select(.expect_parse_exit == 0) | select(.complexity_raw | test("^(Simple|Plan|Spectra|SDD-warranted)$") | not) | select(.complexity_raw | test("^[*`_]") | not)] | length' "$FIXTURE") +n_def=$(jq '[.[] | select(.number < 900) | select(.expect_parse_exit == 5)] | length' "$FIXTURE") +assert_true "≥3 REAL bare-tier rows ($n_bare)" "[ $n_bare -ge 3 ]" assert_true "≥3 decorated-tier rows ($n_deco)" "[ $n_deco -ge 3 ]" assert_true "≥3 tier+rationale rows ($n_rat)" "[ $n_rat -ge 3 ]" assert_true "≥3 deferral-vocabulary rows ($n_def)" "[ $n_def -ge 3 ]" diff --git a/plugins/issue-driven-dev/skills/idd-all/SKILL.md b/plugins/issue-driven-dev/skills/idd-all/SKILL.md index 266ee4e..5137ccf 100644 --- a/plugins/issue-driven-dev/skills/idd-all/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-all/SKILL.md @@ -9,6 +9,8 @@ allowed-tools: - Bash(gh:*) - Bash(git:*) - Bash(grep:*) + - Bash(jq:*) + - Bash(python3:*) - Bash(find:*) - Read - Glob @@ -520,9 +522,12 @@ Skill(skill="issue-driven-dev:idd-diagnose", args="#$N --cwd $CWD") exit 1 } -# 1. 最新 Diagnosis comment —— 必須分頁。`gh issue view --json comments` 只回最舊的 100 則， +# 0. issue 號進 REST path 前先驗型 +case "$N" in ''|*[!0-9]*) echo "FATAL: non-numeric issue number: $N" >&2; exit 1 ;; esac + +# 1. 最新 Diagnosis comment —— 只信任 OWNER / MEMBER / COLLABORATOR 寫的（public repo 任何帳號都能留言）；必須分頁。`gh issue view --json comments` 只回最舊的 100 則， # issue 一長，最新的 diagnosis 正好是被丟掉的那一則（#295 同族；`--paginate --jq` 每頁一個 array，`jq -s add` 收攏）。 -LATEST_DIAGNOSIS=$(gh api "repos/$GITHUB_REPO/issues/$N/comments" --paginate --jq '[.[] | {body}]' \ +LATEST_DIAGNOSIS=$(gh api "repos/$GITHUB_REPO/issues/$N/comments" --paginate --jq '[.[] | select(.author_association == "OWNER" or .author_association == "MEMBER" or .author_association == "COLLABORATOR") | {body}]' \ | jq -s 'add // []' \ | python3 -c ' import json, sys, re @@ -551,9 +556,9 @@ esac Dispatch **先看 `$VEXIT`**(gate 判定),`0` 才依 `$TIER` 分派。tier 只有四個(`SDD-warranted` 視同 `Spectra`);`### Complexity` 開頭以外的同行理由、裝飾、` via <來源>` 後綴都不影響 `$TIER`: -| `CEXIT` · `TIER` | 下一步 | +| `VEXIT` · `CEXIT` · `TIER` | 下一步 | |--------------|--------| -| `0` · `Simple` | Phase 3a: idd-implement | +| `0` · `0` · `Simple` | Phase 3a: idd-implement | | `0` · `Plan` | **attended → Phase 3p: `/idd-plan`**（該 skill 擁有 `EnterPlanMode` 閘門，approve 後自己 chain 到 idd-implement）;**unattended → Phase 3a: idd-implement**，並在 final report 標記 `[Plan tier deliberation skipped under unattended mode]` | | `0` · `Plan`（原值 `Plan via Layer V`,v2.50+）| 同上 — helper 只取開頭的 tier,` via <來源>` 後綴與同行理由皆不影響;verdict 是 user 在 idd-diagnose Step 3.4 選 escalate 觸發,routing 行為跟 bare `Plan` 一致 | | `0` · `Spectra` | Phase 3b: spectra-discuss → spectra-propose → spectra-apply(unattended → 一輪收斂;attended → multi-turn 對話自然進行) | @@ -638,7 +643,12 @@ command -v spectra >/dev/null 2>&1 || abort "Spectra tier routed but spectra CLI ```bash ISSUE_TITLE=$(gh issue view "$N" --repo "$GITHUB_REPO" --json title -q .title) ISSUE_BODY=$(gh issue view "$N" --repo "$GITHUB_REPO" --json body -q .body | head -50) -DIAGNOSIS="$LATEST_DIAGNOSIS" # Phase 2 已分頁抓過最新 Diagnosis（`--json comments` 只回最舊 100 則,不得在此重抓） +# Phase 2 已分頁抓過最新 Diagnosis；跨 Bash 區塊 shell 變數不保證存活,所以缺值時**用同一種分頁方式**重抓 +# （不得改用 `--json comments` —— 那只回最舊 100 則）。 +DIAGNOSIS="${LATEST_DIAGNOSIS:-}" +[ -n "$DIAGNOSIS" ] || DIAGNOSIS=$(gh api "repos/$GITHUB_REPO/issues/$N/comments" --paginate \ + --jq '[.[] | select(.author_association == "OWNER" or .author_association == "MEMBER" or .author_association == "COLLABORATOR") | {body}]' \ + | jq -s 'add // []' | python3 -c 'import json,sys,re; cs=json.load(sys.stdin); ds=[c for c in cs if re.search(r"(?m)^## Diagnosis", c["body"])]; print(ds[-1]["body"] if ds else "")') ``` #### Step 3b.2: Discuss @@ -1004,7 +1014,7 @@ for sub_n in "$ROOT_N" "${SPAWNED_ISSUES[@]:-}"; do ACTION_ITEMS+=$'\n'"- #${sub_n}: ${AUTO_DEFERRED_COUNT} row(s) auto-deferred at /idd-clarify Step 4.8 (unattended mode) — resolve via /idd-clarify #${sub_n} --status resolved=," fi # #120 (v2.97.0+): Layer V deferred records live in Diagnosis COMMENTS (not body) - SUB_COMMENTS=$(gh issue view "$sub_n" --repo "$GITHUB_REPO" --json comments --jq '[.comments[].body] | join("\n---\n")' 2>/dev/null) + SUB_COMMENTS=$(gh api "repos/$GITHUB_REPO/issues/$sub_n/comments" --paginate --jq '[.[] | .body]' 2>/dev/null | jq -s 'add // []' | jq -r 'join("\n---\n")') # 分頁：`--json comments` 只回最舊 100 則（#316 第 3 輪） LAYERV_DEFERRED_COUNT=$(echo "$SUB_COMMENTS" \ | grep -cE 'unattended-auto-Step-3\.4-layerV-deferred') if [ "$LAYERV_DEFERRED_COUNT" -gt 0 ]; then diff --git a/plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md b/plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md index ed5bfb4..676521f 100644 --- a/plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md @@ -614,7 +614,7 @@ Diagnosis 完成 + Step 3.4 Vagueness Pre-check 結束後（`type=meeting` 已 **延期意圖不要寫進這個欄位，改貼 `parking-lot` label。** consumer 會對整行掃 `when triggered` / `parking lot` / `deferred` / `暫緩` 這組保守語彙，命中即以 `complexity-deferral-marker` 擋下 —— 這是為 159 筆歷史語料留的安全網（9 筆命中、0 誤報），不是給新 diagnosis 用的表達方式；漏抓時 label 是兜底，誤抓則是對可動 issue 的 hard stop，所以語彙刻意保守。理由是生命週期不同：Diagnosis comment 是 **append-only** 審計軌跡（見 [`rules/append-vs-modify.md`](../../rules/append-vs-modify.md)），而「是否 parked」**會變**（trigger 成立就該解除）；把可變狀態凍進不可變的 artifact 正是 #298 診斷出的根因。要表達「這件事先擱著」：tier 照常寫、然後貼 label；park 的理由與 trigger 條件寫在 issue body（`idd-list --parked` 會把它印出來，#310）。 -**本 skill SHALL NOT 貼、移除或推導 `parking-lot` label。** 該 label 是**人的裁決**，且可以在 diagnosis 寫完**之後**才下。實測 2026-08-10 的 11 筆 diagnosed issue，限定詞與 label 一致的只有 5 筆：`#37` 的 comment 是 `**Spectra**` 而 label 由人事後貼上；`#131` / `#200` 則有限定詞卻無 label。兩者不是同一件事的兩種寫法 —— 由 producer 從限定詞推導 label，等於取消「人可以事後 park 一個 tier 明確的 issue」這條路徑。 +**本 skill SHALL NOT 對**正在診斷的該 issue**貼、移除或推導 `parking-lot` label。** 該 label 是**人的裁決**，且可以在 diagnosis 寫完**之後**才下。（範圍限定：Step 3.6 的 IC_R011 checkpoint 對**新 filed 的 sister issue** 依 user 在 AskUserQuestion 選的 (b)/(c) 分類貼 `parking-lot`，那是人的分類裁決落在另一張 issue 上，不在本禁令內 —— 但要知道那個 label 現在是 gate 的一級訊號，貼了就等於把新 issue 直接 park。）實測 2026-08-10 的 11 筆 diagnosed issue，限定詞與 label 一致的只有 5 筆：`#37` 的 comment 是 `**Spectra**` 而 label 由人事後貼上；`#131` / `#200` 則有限定詞卻無 label。兩者不是同一件事的兩種寫法 —— 由 producer 從限定詞推導 label，等於取消「人可以事後 park 一個 tier 明確的 issue」這條路徑。 > 完整契約（抽取規則、exit code、五值 reason 值域、consumer 端的保守處置與 surface 規定、159 筆 corpus 回歸）見 [`references/actionability-gate.md`](../../references/actionability-gate.md)。 diff --git a/plugins/issue-driven-dev/skills/idd-implement/SKILL.md b/plugins/issue-driven-dev/skills/idd-implement/SKILL.md index 425922f..1e68829 100644 --- a/plugins/issue-driven-dev/skills/idd-implement/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-implement/SKILL.md @@ -10,6 +10,8 @@ argument-hint: "#issue [#issue ...] [--pr | --no-pr] [--cwd /path/to/clone] [--w allowed-tools: - Bash(gh:*) - Bash(git:*) + - Bash(jq:*) + - Bash(python3:*) - Read - Write - Edit @@ -94,6 +96,51 @@ TaskCreate(name="sister_bug_sweep", description="Step 5.7: review session log + --- +### Step 0.35: Actionability gate — 先於 tree-lock、建 branch、任何 egress（#316 第 3 輪） + +在動任何有副作用的事（Step 0.4 tree-lock、Step 0.5 `git checkout -b`、Step 2 的 Implementation Plan comment）**之前**，先問「這張 issue 現在可不可以動」。第 2 輪把 gate 放在 Step 2.5，結果一張人為 park 的 issue 會先被建 branch、先被貼一則公開的 Implementation Plan，才被告知「停止實作」—— 對一個「人已決定先擱著」的 issue 產生不可撤回的外部寫入，正是 #316 要防的事。`idd-plan`（Step 1）與 `idd-all`（Phase 2）本來就在副作用之前；本 skill 對齊它們。契約：[`references/actionability-gate.md`](../../references/actionability-gate.md) §Consumer contract「gate SHALL precede any egress or branch creation」。 + +```bash +# 缺 helper 一律 fail loud + 指名 path，禁止 fallback 到私有 regex（契約 §Consumer contract） +. "$CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh" || { + echo "FATAL: missing $CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh — 不得改用私有 regex" >&2 + exit 1 +} + +# 0. issue 號進 REST path 前先驗型 +case "$NUMBER" in ''|*[!0-9]*) echo "FATAL: non-numeric issue number: $NUMBER" >&2; exit 1 ;; esac + +# 1. 最新 Diagnosis comment —— 只信任 OWNER / MEMBER / COLLABORATOR 寫的（public repo 任何帳號都能留言）；必須分頁。`gh issue view --json comments` 只回最舊的 100 則， +# issue 一長，最新的 diagnosis 正好是被丟掉的那一則（#295 同族；`--paginate --jq` 每頁一個 array，`jq -s add` 收攏）。 +LATEST_DIAGNOSIS=$(gh api "repos/$GITHUB_REPO/issues/$NUMBER/comments" --paginate --jq '[.[] | select(.author_association == "OWNER" or .author_association == "MEMBER" or .author_association == "COLLABORATOR") | {body}]' \ + | jq -s 'add // []' \ + | python3 -c ' +import json, sys, re +cs = json.load(sys.stdin) +ds = [c for c in cs if re.search(r"(?m)^## Diagnosis", c["body"])] # line-anchored，引述/inline 不算（v2.68.0+ #59） +print(ds[-1]["body"] if ds else "")') + +# 2. 另外兩個訊號：labels，與 body 的 ### Blocking（經 helper 讀；idd-update 的 `- (none)` placeholder 算空） +ISSUE_JSON=$(gh issue view "$NUMBER" --repo "$GITHUB_REPO" --json labels,body) +HAS_PARKING=$(jq -r 'if any(.labels[]; .name == "parking-lot") then "yes" else "no" end' <<<"$ISSUE_JSON") +BLOCK_LINE=$(idd_blocking_section "$(jq -r '.body // ""' <<<"$ISSUE_JSON")") +if [ -n "$BLOCK_LINE" ]; then BLOCKING=yes; else BLOCKING=no; fi + +# 3. 條件式捕捉 —— `set -euo pipefail` 下唯一不會被 exit 3/4/5 終止的寫法（verify #318 HIGH） +if TIER=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>/dev/null); then CEXIT=0; else CEXIT=$?; fi +COMPLEXITY_ERR=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>&1 >/dev/null) || true # 3/5 回 `: <原值>`、4 回 `missing-complexity` + +# 4. 真的呼叫 gate。exit 2 是 API 誤用（本 skill 的 bug），不得與 not-actionable 混同 +if VERDICT=$(idd_actionability_verdict --complexity-exit "$CEXIT" --parking-label "$HAS_PARKING" --blocking-section "$BLOCKING" 2>&1); then VEXIT=0; else VEXIT=$?; fi +case "$VEXIT" in + 0) ;; # actionable → 依下表以 $TIER 分派 + 1) REASONS="${VERDICT#not-actionable: }" ;; # withheld → 下表 `VEXIT=1` 各列；不給任何 lifecycle 命令 + *) echo "FATAL: idd_actionability_verdict misuse — $VERDICT" >&2; exit 1 ;; +esac +``` + +`VEXIT=1` → 依 Step 2.5 的表**立即停止**（印 `$REASONS` 與原文），不進 Step 0.4 以後任何一步；`VEXIT=0` → 帶著 `$TIER` 繼續。 + ### Step 0.4: Tree-lock acquire / asymmetric escalation（v2.85.0+, #183） **在 Step 0.5 path resolution 之前**，先嘗試取得 shared working-tree lock。這把 line 210 的 advisory「prefer a worktree」變成 **normative 機制**：第一個 session 免費持有 main tree（direct-commit 零稅），後到的 session 偵測到 live holder 就**自己** escalate 進 worktree —— 沒有 session 需要預測未來或事後搬 tree（converged Option D，#183 discuss 2026-06-03）。 @@ -366,49 +413,16 @@ bash "$CLAUDE_PLUGIN_ROOT/scripts/gh-egress.sh" comment $NUMBER --repo $GITHUB_R **判斷 Complexity routing**：讀最新 `## Diagnosis` comment 的 `### Complexity` 欄位（v2.36.0+ 三路；v2.50+ 加 Layer V variant）。**tier 抽取與 actionability 判定都不在此處自行寫 parser**，改呼叫 [`references/actionability-gate.md`](../../references/actionability-gate.md) 契約下的共用實作： -```bash -# 缺 helper 一律 fail loud + 指名 path，禁止 fallback 到私有 regex（契約 §Consumer contract） -. "$CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh" || { - echo "FATAL: missing $CLAUDE_PLUGIN_ROOT/scripts/lib/actionability.sh — 不得改用私有 regex" >&2 - exit 1 -} - -# 1. 最新 Diagnosis comment —— 必須分頁。`gh issue view --json comments` 只回最舊的 100 則， -# issue 一長，最新的 diagnosis 正好是被丟掉的那一則（#295 同族；`--paginate --jq` 每頁一個 array，`jq -s add` 收攏）。 -LATEST_DIAGNOSIS=$(gh api "repos/$GITHUB_REPO/issues/$NUMBER/comments" --paginate --jq '[.[] | {body}]' \ - | jq -s 'add // []' \ - | python3 -c ' -import json, sys, re -cs = json.load(sys.stdin) -ds = [c for c in cs if re.search(r"(?m)^## Diagnosis", c["body"])] # line-anchored，引述/inline 不算（v2.68.0+ #59） -print(ds[-1]["body"] if ds else "")') +> **gate 已於 Step 0.35 執行**（第 3 輪，verify #318：gate 必須先於建 branch 與任何 egress）。本 step 只消費 Step 0.35 留下的 `$VEXIT` / `$TIER` / `$REASONS` / `$COMPLEXITY_ERR` / `$BLOCK_LINE`；不得在此重跑。 -# 2. 另外兩個訊號：labels，與 body 的 ### Blocking（經 helper 讀；idd-update 的 `- (none)` placeholder 算空） -ISSUE_JSON=$(gh issue view "$NUMBER" --repo "$GITHUB_REPO" --json labels,body) -HAS_PARKING=$(jq -r 'if any(.labels[]; .name == "parking-lot") then "yes" else "no" end' <<<"$ISSUE_JSON") -BLOCK_LINE=$(idd_blocking_section "$(jq -r '.body // ""' <<<"$ISSUE_JSON")") -if [ -n "$BLOCK_LINE" ]; then BLOCKING=yes; else BLOCKING=no; fi - -# 3. 條件式捕捉 —— `set -euo pipefail` 下唯一不會被 exit 3/4/5 終止的寫法（verify #318 HIGH） -if TIER=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>/dev/null); then CEXIT=0; else CEXIT=$?; fi -COMPLEXITY_ERR=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>&1 >/dev/null) || true # 3/5 回 `: <原值>`、4 回 `missing-complexity` - -# 4. 真的呼叫 gate。exit 2 是 API 誤用（本 skill 的 bug），不得與 not-actionable 混同 -if VERDICT=$(idd_actionability_verdict --complexity-exit "$CEXIT" --parking-label "$HAS_PARKING" --blocking-section "$BLOCKING" 2>&1); then VEXIT=0; else VEXIT=$?; fi -case "$VEXIT" in - 0) ;; # actionable → 依下表以 $TIER 分派 - 1) REASONS="${VERDICT#not-actionable: }" ;; # withheld → 下表 `VEXIT=1` 各列；不給任何 lifecycle 命令 - *) echo "FATAL: idd_actionability_verdict misuse — $VERDICT" >&2; exit 1 ;; -esac -``` helper 只取開頭的 tier：` via <來源>` 後綴（例如 `Plan via Layer V`）、同行理由、markdown 裝飾都不影響，本 skill 拿到的 `$TIER` 已是 canonical tier — 對應 spec Requirement: Routing parsers SHALL recognize Plan via Layer V verdict。 Routing **先看 `$VEXIT`**（gate 判定），`0` 才依 `$TIER` 決定行為。tier 只有四個： -| `CEXIT` · `TIER` | 行為 | +| `VEXIT` · `CEXIT` · `TIER` | 行為 | |-----------|------| -| `0` · `Simple` | ✅ 本 step 啟動 TaskList 追蹤每個 checklist item | +| `0` · `0` · `Simple` | ✅ 本 step 啟動 TaskList 追蹤每個 checklist item | | `0` · `Plan`（原值可能是 `Plan via Layer V`）| ✅ 同 Simple — TaskList 啟動。**注意**：使用者通常透過 `/idd-plan #NNN` 呼叫進來，approval gate 已在 idd-plan 處理完，本 skill 直接走 TDD loop。若使用者直接呼叫 `/idd-implement` 而 Complexity=Plan，**先提示**「Complexity 判定為 Plan，建議改走 `/idd-plan #NNN` 進入 approval gate；繼續直接 implement 等於跳過 Plan tier 的 deliberation 價值」並用 AskUserQuestion 確認 continue/abort。`Plan via Layer V` 同樣行為(routing 一致),只是 verdict 標記提示這是 Layer V 觸發 | | `0` · `Spectra` | ⏭ 跳過本 step（由 `spectra-apply` 管 `openspec/changes//tasks.md`）| | `0` · `SDD-warranted` (legacy alias) | ⏭ 跳過本 step — 視同 `Spectra` 處理（v2.36.0+ backward compat）| diff --git a/plugins/issue-driven-dev/skills/idd-issue/SKILL.md b/plugins/issue-driven-dev/skills/idd-issue/SKILL.md index daf6905..da5932f 100644 --- a/plugins/issue-driven-dev/skills/idd-issue/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-issue/SKILL.md @@ -1236,7 +1236,7 @@ Empty surface list = legitimate silent no-op(per canonical §4 `(none surfaced)` - **Audit trail target**:`### Linked-Context Siblings Filed (v2.48.0+ #529)` PATCHed into the just-created issue body(per canonical §4.1 heading conventions table)。 `(category: audit-block-append, scope: "### Linked-Context Siblings Filed")` per [`rules/append-vs-modify.md`](../../rules/append-vs-modify.md)。 - **Non-blocking** — user skip / empty list 都不阻擋 Step 5 報告完成。 -**Default behavior (v2.72.0+)**: File by default per canonical §1.1。Skip requires 3-category taxonomy per canonical §1.4((a) unactionable / (b) infeasible → filed with `blocker:infeasible` / (c) blocked-on-external → filed with `blocker:waiting`)。Escape hatch(`AI_LOW_BAR_ISSUE_FILING=false` env var / `# Disable IC_R011` CLAUDE.md flag)reverts to legacy 3-option ask per canonical §5。 +**Default behavior (v2.72.0+)**: File by default per canonical §1.1。Skip requires 3-category taxonomy per canonical §1.4((a) unactionable / (b) infeasible / (c) blocked-on-external → filed with `parking-lot`（#316 收斂：`blocker:*` 從未建立過；`parking-lot` 是 actionability gate 的一級訊號，貼了即 parked）)。Escape hatch(`AI_LOW_BAR_ISSUE_FILING=false` env var / `# Disable IC_R011` CLAUDE.md flag)reverts to legacy 3-option ask per canonical §5。 > **Why light-touch deviation**: per canonical §6 eligibility table, `/idd-issue` is SHALL-tier but light-touch(filing-active moment) — default file still applies, but heuristic gating prevents double-prompt friction on clean single-issue invocations。 diff --git a/plugins/issue-driven-dev/skills/idd-list/SKILL.md b/plugins/issue-driven-dev/skills/idd-list/SKILL.md index edfdf8c..cc7067d 100644 --- a/plugins/issue-driven-dev/skills/idd-list/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-list/SKILL.md @@ -9,6 +9,8 @@ argument-hint: "[--state open|closed|all] [--label ] [--limit N] [--target allowed-tools: - Bash(gh:*) - Bash(git:*) + - Bash(jq:*) + - Bash(python3:*) - Read --- @@ -275,7 +277,7 @@ def get_leader(refs_list, body, rule): `blocked` label（若 repo 有此慣例）與「Suggested-next 屬 wait 類」是 **idd-list 自己的顯示訊號**，只影響 Blocked 組歸類，不進 gate。 -每個 issue 跑一次（`$n` 為 issue 號；本 skill 在 `set -euo pipefail` 下跑，**必須**用條件式捕捉，一筆壞值不得中斷整份 listing）： +每個 **open** issue 跑一次（`$n` 為 issue 號；本 skill 在 `set -euo pipefail` 下跑，**必須**用條件式捕捉，一筆壞值或一次 API 失敗都不得中斷整份 listing）。`--state closed` / `--audit-closes` 語境下**不跑 gate**——對已關閉的 issue 問「現在可不可以動」沒有意義。labels 與 body **直接取自 Step 2 的 `$ISSUES_JSON`**（Step 2.5 的反 N+1 規定），comments 只在 Step 2 抓回的陣列長度 ≥ 100（可能被截斷）時才逐一分頁補抓： ```bash # 缺 helper 一律 fail loud + 指名 path，禁止 fallback 到私有 regex（契約 §Consumer contract） @@ -284,18 +286,27 @@ def get_leader(refs_list, body, rule): exit 1 } -# 1. 最新 Diagnosis comment —— 必須分頁。`gh issue view --json comments` 只回最舊的 100 則， -# issue 一長，最新的 diagnosis 正好是被丟掉的那一則（#295 同族；`--paginate --jq` 每頁一個 array，`jq -s add` 收攏）。 -LATEST_DIAGNOSIS=$(gh api "repos/$GITHUB_REPO/issues/$n/comments" --paginate --jq '[.[] | {body}]' \ - | jq -s 'add // []' \ - | python3 -c ' +# 0. 只對 open issue 跑；issue 號進 REST path 前先驗型（同檔 --audit-closes 段的規定） +[ "$STATE" = "open" ] || { GROUP=skipped; continue; } +case "$n" in ''|*[!0-9]*) echo "FATAL: non-numeric issue number: $n" >&2; GROUP=error; continue ;; esac +ISSUE_JSON=$(jq -c --argjson n "$n" '.[] | select(.number == $n)' <<<"$ISSUES_JSON") # labels / body / comments 已在 Step 2 抓回，不重抓 + +# 1. 最新 Diagnosis comment —— 只信任 OWNER / MEMBER / COLLABORATOR 寫的（public repo 任何帳號都能留言， +# 否則一則外人貼的 `## Diagnosis` 就能改寫訊號 1）。Step 2 的 comments 陣列只含最舊的 100 則， +# 長度 ≥ 100 才逐一分頁補抓（`--paginate --jq` 每頁一個 array，`jq -s add` 收攏）；抓取失敗 → 該列標 error，listing 繼續。 +if [ "$(jq '.comments | length' <<<"$ISSUE_JSON")" -ge 100 ]; then + COMMENTS_JSON=$(gh api "repos/$GITHUB_REPO/issues/$n/comments" --paginate --jq '[.[] | select(.author_association == "OWNER" or .author_association == "MEMBER" or .author_association == "COLLABORATOR") | {body}]' \ + | jq -s 'add // []') || { echo "⚠ #$n: comment fetch failed — gate not evaluated" >&2; GROUP=error; continue; } +else + COMMENTS_JSON=$(jq -c '[.comments[] | select(.authorAssociation == "OWNER" or .authorAssociation == "MEMBER" or .authorAssociation == "COLLABORATOR") | {body}]' <<<"$ISSUE_JSON") +fi +LATEST_DIAGNOSIS=$(python3 -c ' import json, sys, re cs = json.load(sys.stdin) ds = [c for c in cs if re.search(r"(?m)^## Diagnosis", c["body"])] # line-anchored，引述/inline 不算（v2.68.0+ #59） -print(ds[-1]["body"] if ds else "")') +print(ds[-1]["body"] if ds else "")' <<<"$COMMENTS_JSON") || { echo "⚠ #$n: diagnosis parse failed" >&2; GROUP=error; continue; } -# 2. 另外兩個訊號：labels，與 body 的 ### Blocking（經 helper 讀；idd-update 的 `- (none)` placeholder 算空） -ISSUE_JSON=$(gh issue view "$n" --repo "$GITHUB_REPO" --json labels,body) +# 2. 另外兩個訊號：labels，與 body 的 ### Blocking（經 helper 逐 bullet 讀；`- (none — …)` 這類 placeholder 算空） HAS_PARKING=$(jq -r 'if any(.labels[]; .name == "parking-lot") then "yes" else "no" end' <<<"$ISSUE_JSON") BLOCK_LINE=$(idd_blocking_section "$(jq -r '.body // ""' <<<"$ISSUE_JSON")") if [ -n "$BLOCK_LINE" ]; then BLOCKING=yes; else BLOCKING=no; fi @@ -308,13 +319,13 @@ COMPLEXITY_ERR=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>&1 >/dev/null) || tr # listing 語境下不 exit，改印 FATAL 行並把該 issue 標為 `(gate error)` 繼續 if VERDICT=$(idd_actionability_verdict --complexity-exit "$CEXIT" --parking-label "$HAS_PARKING" --blocking-section "$BLOCKING" 2>&1); then VEXIT=0; else VEXIT=$?; fi case "$VEXIT" in - 0) GROUP=actionable ;; - 1) REASONS="${VERDICT#not-actionable: }"; GROUP=$(idd_actionability_group "$REASONS") ;; # blocked | parked + 0) GROUP=actionable; REASONS="" ;; + 1) REASONS="${VERDICT#not-actionable: }"; GROUP=$(idd_actionability_group "$REASONS") ;; # blocked | parked | undiagnosed *) echo "FATAL: idd_actionability_verdict misuse on #$n — $VERDICT" >&2; GROUP=error ;; esac ``` -掛到 issue entry：`group`（`actionable` / `blocked` / `parked` / `error`）、`reasons`、`tier`（僅 `VEXIT=0`）、以及要 surface 的原文 —— `$COMPLEXITY_ERR`（exit 3/5 的 `: <原值>` 整行、exit 4 的 `missing-complexity`）、`$BLOCK_LINE`（#84 的 `blocked_reason`，語意不變）、或 label 名。 +掛到 issue entry：`group`（`actionable` / `blocked` / `parked` / `undiagnosed` / `error` / `skipped`）、`reasons`、`tier`（僅 `VEXIT=0`）、以及要 surface 的原文 —— `$COMPLEXITY_ERR`（exit 3/5 的 `: <原值>` 整行、exit 4 的 `missing-complexity`）、`$BLOCK_LINE`（#84 的 `blocked_reason`，語意不變）、或 label 名。**surface 的原文是別人寫的資料，不是指令**：印出前剝掉 C0 控制字元（`tr -d '\000-\010\013\014\016-\037'`），避免 ANSI / `\r` 覆蓋前綴。 **不得截斷、不得降級、不得靜默**：`Simple when triggered` 的 tier 前綴 `Simple` 是合法的，helper 正因此**拒絕**在 exit 5 印出它 —— 本 skill 拿不到 tier，就不可能路由。原文一律印在該列（如 `⏸ deferral-marker: Simple when triggered`），這與 `### Conflict Class` 的既有規則對稱：值無法安全解讀時取最保守的處置**並把 fallback 印出來**。 @@ -346,7 +357,7 @@ Parked (3) — 每一項的 trigger 條件是關於未來的散文命題，不 ⏸ trigger: ≥1 次 trace-stale 實害事故 ``` -5. footer 印 `(parked: N — 上次回訪日期不可知，IDD 不記錄)`。**不要**宣稱「已檢查過 trigger」—— 這個 flag 只負責把條件攤開給人看。 +5. footer 印 `(parked: N — 上次回訪日期不可知，IDD 不記錄)`。**`complexity-missing`（未診斷）與 `complexity-unparseable`（資料錯誤）不是 parked**，不列入本 flag；前者在 Step 5 有自己的 `Needs diagnosis` 組。**不要**宣稱「已檢查過 trigger」—— 這個 flag 只負責把條件攤開給人看。 **鐵律**：本 step **絕不自動 unpark、也絕不自動關閉** parked issue。判斷「那個未來狀態是否已經發生」需要 repo 之外的知識；工具把條件列出來，人來判斷。 @@ -475,11 +486,16 @@ Blocked (waiting on external): Parked (not routable now): #131 [diagnosed] → ⏸ deferral-marker: Simple when triggered #146 [diagnosed] → ⏸ parking-lot label · deferral-marker: **Simple when triggered**(Layer 1 disqualifier:…) - #273 [diagnosed] → ⏸ missing-complexity — 先跑 /idd-diagnose #273 #908 [diagnosed] → ⏸ unparseable-complexity: 移入 discussion list — 修正 Diagnosis + +Needs diagnosis (11): + #335 [created] → /idd-diagnose #335 + #333 [created] → /idd-diagnose #333 ``` -Parked 組的歸類規則（`idd_actionability_group`）：reason **只有** `blocking-nonempty` → Blocked；其餘任何 reason 或混合（含 `complexity-deferral-marker` + `blocking-nonempty`）→ Parked。每列印出 `$REASONS` 與原文（`$COMPLEXITY_ERR` / label 名 / `$BLOCK_LINE`），**不給任何 lifecycle 命令**；`complexity-unparseable` / `complexity-missing` 才附「修正 Diagnosis / 先跑 diagnose」提示 —— `complexity-deferral-marker` 與 `parking-lot-label` 是合法狀態，不是要修的東西。`group=error`（gate API 誤用）單獨一列印 `⚠ gate error`，那是本 skill 的 bug。 +**`Needs diagnosis` 組（`group=undiagnosed`，#316 第 3 輪）**：reason 只有 `complexity-missing` 的 issue —— 也就是**還沒被 diagnose**。這是每一張 issue 的出生狀態，不是 parked；實測 2026-09-07 的 14 個 open issue 有 11 個在這一組，把它們放進 Parked 會讓 `--parked` 與 footer 的數字差一個數量級、並把 `→ /idd-diagnose #N` 這個唯一正確的 lifecycle 命令藏起來。本組**保留**該命令（與 `created` / `clarified` phase 的 matrix 一致）；全 blocked banner 的觸發條件不變（Actionable now 為空且 Blocked 非空），undiagnosed 不影響它。 + +歸類規則（`idd_actionability_group`）：含 `parking-lot-label` / `complexity-deferral-marker` / `complexity-unparseable` 任一 → Parked；否則含 `blocking-nonempty` → Blocked（#84 逐字保留）；否則只有 `complexity-missing` → Needs diagnosis。每列印出 `$REASONS` 與原文（`$COMPLEXITY_ERR` / label 名 / `$BLOCK_LINE`），**不給任何 lifecycle 命令**；`complexity-unparseable` / `complexity-missing` 才附「修正 Diagnosis / 先跑 diagnose」提示 —— `complexity-deferral-marker` 與 `parking-lot-label` 是合法狀態，不是要修的東西。`group=error`（gate API 誤用）單獨一列印 `⚠ gate error`，那是本 skill 的 bug。 **全 blocked banner**：當 Actionable now 為空且 Blocked 非空： @@ -488,7 +504,7 @@ Parked 組的歸類規則（`idd_actionability_group`）：reason **只有** `bl 這不是 throughput 問題；下次回來先檢查 blocker 是否解除。 ``` -Footer 統計行加 blocked 計數：`X actionable, Y blocked`（#84 原樣）；Parked 非空時**在其後**追加 `, Z parked`（Z=0 時不印，footer 與 #84 逐字相同）。全 blocked banner 的觸發條件不變（Actionable now 為空且 Blocked 非空）；若同時有 Parked，banner 文案原樣印出後另起一行 ` 另有 Z 個 parked（見 Parked 組；回訪用 --parked）`，不改動 banner 本身。理由（#84 原始觀察）：「等」的狀態被顯式 surface 後，「沒進度」焦慮與「漏掉了什麼」反向搜尋都消失 — 資訊本體是聚合判斷，不是 per-issue 列表。 +Footer 統計行加 blocked 計數：`X actionable, Y blocked`（#84 原樣）；Parked 非空時**在其後**追加 `, Z parked`，Needs diagnosis 非空時再追加 `, W undiagnosed`（各自為 0 時不印，footer 與 #84 逐字相同）。全 blocked banner 的觸發條件不變（Actionable now 為空且 Blocked 非空）；若同時有 Parked，banner 文案原樣印出後另起一行 ` 另有 Z 個 parked（見 Parked 組；回訪用 --parked）`，不改動 banner 本身。理由（#84 原始觀察）：「等」的狀態被顯式 surface 後，「沒進度」焦慮與「漏掉了什麼」反向搜尋都消失 — 資訊本體是聚合判斷，不是 per-issue 列表。 ``` Suggested next: diff --git a/plugins/issue-driven-dev/skills/idd-plan/SKILL.md b/plugins/issue-driven-dev/skills/idd-plan/SKILL.md index d49373d..298cf2f 100644 --- a/plugins/issue-driven-dev/skills/idd-plan/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-plan/SKILL.md @@ -65,9 +65,12 @@ gh issue view $NUMBER --repo $GITHUB_REPO --json title,body,labels,comments exit 1 } -# 1. 最新 Diagnosis comment —— 必須分頁。`gh issue view --json comments` 只回最舊的 100 則， +# 0. issue 號進 REST path 前先驗型 +case "$NUMBER" in ''|*[!0-9]*) echo "FATAL: non-numeric issue number: $NUMBER" >&2; exit 1 ;; esac + +# 1. 最新 Diagnosis comment —— 只信任 OWNER / MEMBER / COLLABORATOR 寫的（public repo 任何帳號都能留言）；必須分頁。`gh issue view --json comments` 只回最舊的 100 則， # issue 一長，最新的 diagnosis 正好是被丟掉的那一則（#295 同族；`--paginate --jq` 每頁一個 array，`jq -s add` 收攏）。 -LATEST_DIAGNOSIS=$(gh api "repos/$GITHUB_REPO/issues/$NUMBER/comments" --paginate --jq '[.[] | {body}]' \ +LATEST_DIAGNOSIS=$(gh api "repos/$GITHUB_REPO/issues/$NUMBER/comments" --paginate --jq '[.[] | select(.author_association == "OWNER" or .author_association == "MEMBER" or .author_association == "COLLABORATOR") | {body}]' \ | jq -s 'add // []' \ | python3 -c ' import json, sys, re @@ -96,9 +99,9 @@ esac **先看 `$VEXIT`**（gate 判定），`0` 才依 `$TIER` 決定行為。tier 只有四個；`### Complexity` 開頭以外的同行理由、裝飾、` via <來源>` 後綴都不影響 `$TIER`： -| `CEXIT` · `TIER` | 行為 | +| `VEXIT` · `CEXIT` · `TIER` | 行為 | |-----------|------| -| `0` · `Plan` | ✅ 預期 — 繼續 Step 2 | +| `0` · `0` · `Plan` | ✅ 預期 — 繼續 Step 2 | | `0` · `Plan`（原值 `Plan via Layer V`、`**Plan**(Layer P:…)` 等）| 同上 — helper 只取開頭的 tier,後綴與同行理由皆不影響,行為與 bare `Plan` 完全一致 | | `0` · `Simple` | ⚠️ 詢問 user：「Complexity 判定為 Simple，確定要走 Plan tier 多一道 approval gate 嗎？」（行為不變 — user 主動要 deliberate 是允許的）| | `0` · `Spectra` | ⛔ 提示「Spectra 應走 `/spectra-discuss`，Plan tier 不會產出 spec/proposal/tasks artifacts」，AskUserQuestion abort 或 continue（continue 等於 user 自願降級到 Plan tier）— 行為不變 | From 703ad3bb74ecfd298d01ae7d138f90e93394b682 Mon Sep 17 00:00:00 2001 From: che cheng Date: Mon, 7 Sep 2026 19:20:09 +0900 Subject: [PATCH 6/6] =?UTF-8?q?feat:=20actionability=20gate=20round=204=20?= =?UTF-8?q?=E2=80=94=20repair=20round-3=20regressions,=20print=20the=20ver?= =?UTF-8?q?dict,=20claims=20down=20to=20evidence?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refs #316 (round-4 repairs for the /idd-verify --pr 318 round-3 FAIL: 6 blocking + 11 in-scope) Regressions repaired - idd-implement Step 2.5 consumed gate variables across Bash calls and forbade re-running; now checks ${VEXIT:-} and re-runs the Step 0.35 block with the same helper (the shape idd-all 3b.1 already had) - idd-list state guard used the listing --state flag (--state all skipped every issue, Suggested-next vanished); now per-issue .state == "OPEN", and `skipped` rows keep the phase x PR matrix - placeholder rule was locale-dependent (multibyte separators in a bracket expression flipped both directions under LC_ALL=C; the suite itself failed 3 assertions); rewritten as alternations, suite also run under LC_ALL=C - an unclosed code fence swallowed every later section (live #290); unbalanced fences now disable fence tracking for that body Observability / hygiene - the gate block prints `gate #N: VEXIT=… TIER=… REASONS=… | …` in all four consumers and the canonical shape (a silent exit 0 was indistinguishable from actionable to the executing model) - C0/DEL scrubbed at the helper's outputs (round 3 only described it, and the described set omitted \r); idd_actionability_group "" is exit 2 - REASONS reset on the actionable path; routing table rows carry all three keys; idd-plan gains allowed-tools and drops the bare --json comments fetch; idd-all Layer-V sub-issue scan digit-checks + author-filters; _idd_section_first_line no longer pipes into head (SIGPIPE under pipefail) Claims brought down to the evidence - corpus-blocking.json rows carry the original body so the extractor is exercised; provenance: 54/55 agree with hand review, #1 an accepted FP, 54/55 CLOSED issues the gate never evaluates (signal 3's live effect on 2026-09-07 was one issue) - accepted misses stated as a rule in both directions; the two rejected placeholder regexes recorded with FP/FN counts; "parked group == --parked set" claim deleted from spec R6 and the reference; cluster-path coverage gap (first issue only, pre-existing) stated and tracked in #340 - spec delta: `respectively` residue, nested backticks and a mis-attributed @trace removed; design/proposal/tasks/CHANGELOG synced; #336 acceptance bar is the semantic truth, not the fixture Tests: 318 assertions (LC_ALL=C probes, unclosed-fence probes, scrub probes, extractor-through-corpus, verdict-printed / REASONS-reset / re-run-fallback / per-issue-state / skipped-rule / sub-issue-hygiene drift guards). Follow-ups: #340 filed; reader-semantics items handed to #336. --- .claude-plugin/marketplace.json | 2 +- .../changes/add-actionability-gate/design.md | 8 +- .../add-actionability-gate/proposal.md | 8 +- .../specs/actionability-gate/spec.md | 15 +- .../specs/idd-ic-r011-checkpoint/spec.md | 14 +- .../changes/add-actionability-gate/tasks.md | 3 +- .../.claude-plugin/plugin.json | 2 +- plugins/issue-driven-dev/CHANGELOG.md | 35 ++++ .../references/actionability-gate.md | 15 +- .../scripts/lib/actionability.sh | 108 ++++++++--- .../fixtures/corpus-blocking.json | 167 ++++++++++++------ .../scripts/tests/actionability-gate/test.sh | 52 +++++- .../issue-driven-dev/skills/idd-all/SKILL.md | 15 +- .../skills/idd-implement/SKILL.md | 16 +- .../issue-driven-dev/skills/idd-list/SKILL.md | 26 +-- .../issue-driven-dev/skills/idd-plan/SKILL.md | 17 +- 16 files changed, 364 insertions(+), 139 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 41fdb45..f7787f6 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -16,7 +16,7 @@ { "name": "issue-driven-dev", "version": "3.1.0", - "description": "v3.1.0: the actionability gate, rounds 2 and 3. Round 1 read `### Complexity` against a closed value domain that the repository's own 159 diagnoses refuted (66 real values wrongly refused) and shipped a three-signal gate no consumer called. Now the tier is the leading whole word (rationale, decoration and ` via` suffixes are legal), the whole line is scanned for a small deferral vocabulary (exit 5, reason `complexity-deferral-marker` — a parked state, not a defect), `### Blocking` is read by a shared fence-aware helper, and idd-list / idd-all / idd-implement / idd-plan actually call the verdict with all three signals in a paginated, `set -e`-safe shape pinned by a drift test. A frozen 159-issue corpus fixture makes 'zero migration' falsifiable: 149 routable, 9 deferral, 1 missing, 0 unparseable. idd-list gains Parked and Needs-diagnosis groups; the #84 blocked surface is preserved verbatim. Round 3 read `### Blocking` per bullet with a leading-token placeholder rule frozen against the repo's 55 real sections (round 2 had withheld 31 of the 47 empty ones, including #316 itself), moved idd-implement's gate ahead of any branch or comment, and retired `blocker:*`.", + "description": "v3.1.0: the actionability gate, rounds 2 to 4. Round 1 read `### Complexity` against a closed value domain that the repository's own 159 diagnoses refuted (66 real values wrongly refused) and shipped a three-signal gate no consumer called. Now the tier is the leading whole word (rationale, decoration and ` via` suffixes are legal), the whole line is scanned for a small deferral vocabulary (exit 5, reason `complexity-deferral-marker` — a parked state, not a defect), `### Blocking` is read by a shared fence-aware helper, and idd-list / idd-all / idd-implement / idd-plan actually call the verdict with all three signals in a paginated, `set -e`-safe shape pinned by a drift test. A frozen 159-issue corpus fixture makes 'zero migration' falsifiable: 149 routable, 9 deferral, 1 missing, 0 unparseable. idd-list gains Parked and Needs-diagnosis groups; the #84 blocked surface is preserved verbatim. Round 3 read `### Blocking` per bullet with a leading-token placeholder rule frozen against the repo's 55 real sections (54/55 agree with hand review; round 2 had withheld 31 of the 48 empty ones, including #316 itself), moved idd-implement's gate ahead of any branch or comment, and retired `blocker:*`. Round 4 repaired round 3's regressions (cross-Bash-block gate variables, a listing-level state guard, a locale-dependent rule, an unclosed-fence fail-open), made the gate print its verdict, and brought every corpus claim down to what it proves.", "author": { "name": "Che Cheng" }, diff --git a/openspec/changes/add-actionability-gate/design.md b/openspec/changes/add-actionability-gate/design.md index 0e501f8..7570ac0 100644 --- a/openspec/changes/add-actionability-gate/design.md +++ b/openspec/changes/add-actionability-gate/design.md @@ -150,7 +150,7 @@ gate 產出 verdict 加 reason 清單；顯示層依 reason 分兩組 —— rea > `/idd-verify --pr 318` 第 2 輪 FAIL（6 blocking）。四個 lens 與 DA 各自對 238 筆 issue 實測，結論一致：第 2 輪在**第三個訊號**上重犯了 CRITICAL-2 的形狀 —— `idd_blocking_section` 依「idd-update 寫 `- (none)`」這個未經語料驗證的假設寫成整行比對，本 repo 55 個 `### Blocking` 區段裡 48 個語意為空、31 個被判成 blocker，**含 #316 自己**（`- (none — 可動)`）。DA 另外對 14 個 open issue 實跑 gate：2 actionable / 1 blocked（誤判）/ **11 parked** —— 那 11 筆只是還沒診斷。 -**決策 1 — `### Blocking` 是清單欄位，逐 bullet 判、placeholder 看開頭 token。** `### Complexity` 是純量、讀第一行是定義；`### Blocking` 的模板就是 bullet list，讀第一行等於把 list 當 head(list)。規則：任一 bullet 非 placeholder 即非空；placeholder = `none` / `n/a` / `無` 開頭（可帶 bullet、裝飾、括號），後接行尾、右括號或分隔符；非 bullet 起始的行是上一個 bullet 的續行。對 55 筆凍結語料（`corpus-blocking.json`）0 FP / 0 FN；另兩個候選規則在同一語料上各自失敗（一個把 7 筆真 blocker 全清空、一個留 20 個 FP），記在 helper 註解裡當反例。接受的漏抓：token 後接子句（`- (none) but actually blocked by #86`）讀成空 —— 語料 0 筆，明文記錄。**這個欄位該不該被 regex 化**是類別問題，開 #336 追（producer contract vs 退回 model 判定），本輪只止血。 +**決策 1 — `### Blocking` 是清單欄位，逐 bullet 判、placeholder 看開頭 token。** `### Complexity` 是純量、讀第一行是定義；`### Blocking` 的模板就是 bullet list，讀第一行等於把 list 當 head(list)。規則：任一 bullet 非 placeholder 即非空；placeholder = `none` / `n/a` / `無` 開頭（可帶 bullet、裝飾、括號），後接行尾、右括號或分隔符；非 bullet 起始的行是上一個 bullet 的續行。對 55 筆凍結語料（`corpus-blocking.json`，含原始 body，走共用 extractor）與人工標註 54/55 一致（#1 為明文接受的 1 筆 FP）；語料 54/55 是 CLOSED issue，gate 不評；另兩個候選規則在同一語料上各自失敗（一個把 7 筆真 blocker 全清空、一個留 20 個 FP），記在 helper 註解裡當反例。接受的漏抓：token 後接子句（`- (none) but actually blocked by #86`）讀成空 —— 語料 0 筆，明文記錄。**這個欄位該不該被 regex 化**是類別問題，開 #336 追（producer contract vs 退回 model 判定），本輪只止血。 **決策 2 — `complexity-missing` 單獨成 `undiagnosed` 組，保留 `→ /idd-diagnose #N`。** 「還沒診斷」是每張 issue 的出生狀態，在真實 backlog 上是主導狀態；放進 Parked 會讓 footer 與 `--parked` 差一個數量級、藏掉唯一正確的 lifecycle 命令、並讓 #84 的 banner 在新的主導情境下永遠不 fire。spec R6 改為三組：含 label / deferral-marker / unparseable → parked；否則含 blocking-nonempty → blocked（#84 逐字保留）；否則 → undiagnosed。 @@ -216,8 +216,12 @@ Rollback：本變更為 skill 文件與 helper script 的變更，零資料遷 ## Open Questions -- **`### Blocking` 該不該被機械判定？**（#336）第 3 輪的 leading-token 規則是止血，不是答案：對一個由 model 自由填寫的清單欄位疊字元類，每一輪都會長出新洞。要嘛給它 producer contract（空區段不寫 bullet、註記另起一行），要嘛 helper 只回原文、由執行中的 model 依 rubric 判空。兩條路都要對 `corpus-blocking.json` 0 FP / 0 FN。 +- **`### Blocking` 該不該被機械判定？**（#336）第 3 輪的 leading-token 規則是止血，不是答案：對一個由 model 自由填寫的清單欄位疊字元類，每一輪都會長出新洞。要嘛給它 producer contract（空區段不寫 bullet、註記另起一行），要嘛 helper 只回原文、由執行中的 model 依 rubric 判空。兩條路都要對語料的**語意真值**（48 空 / 7 真 blocker）與 open backlog 驗證，不是對 fixture 的 `expect_empty`（它含 1 筆規則接受的 FP）。 - **延期語彙清單的擴充機制未定。** 目前四個語彙由 159 筆 corpus 歸納而得。語料成長後若出現新措辭，是誰、依什麼判準把它加進清單？本變更不解決；先記錄為已知缺口。 - `ic-r011-checkpoint.md` 的兩個 `blocker:*` label 是「退役」還是「與 parking-lot 分工」，需在該檔改寫時定案。目前 0 使用，傾向退役。 + +### 第 4 輪（2026-09-07）：修回歸與誠實，不修涵蓋率 + +> `/idd-verify --pr 318` 第 3 輪 FAIL（6 blocking）。DA 的裁決：round 3 在往 #336 的 rabbit hole 走（三輪各疊一層字元類、各長出新洞）；第 4 輪只做「正確性與誠實」——修 round 3 引入的回歸（idd-implement 跨 Bash 區塊消費 gate 變數且禁止重跑、idd-list state guard 用 listing 旗標）、關掉一行能關的 fail-open（未閉合 fence、locale 相依）、讓 verdict 可觀測（gate 區塊印出判定）、把宣稱降到與證據齊平（「0 FP / 0 FN」→「54/55、1 筆明文 FP、54/55 CLOSED、extractor 已由原始 body 覆蓋」）、把 Accepted misses 從兩個例子改寫成雙向規則。**不擴 bullet class、不把訊號 3 降回顯示訊號** —— 前者擴大 fail-closed 面、後者是 verify 中途對 #84 的 scope change；兩者都留給 #336 從容決定。cluster 路徑只 gate 第一張是 round 2 前就存在的缺口，開 #340 追蹤並在契約明記。 diff --git a/openspec/changes/add-actionability-gate/proposal.md b/openspec/changes/add-actionability-gate/proposal.md index 65e39d8..aa7bd5f 100644 --- a/openspec/changes/add-actionability-gate/proposal.md +++ b/openspec/changes/add-actionability-gate/proposal.md @@ -1,6 +1,6 @@ ## Why -> **第 2 輪 re-baseline（2026-08-15）**：`/idd-verify --pr 318` FAIL（2 CRITICAL / 21 HIGH）。CRITICAL-2 以 90 筆真實語料證偽第 1 輪的封閉值域前提；`/idd-reorganize #316` 完成裁定；`/idd-diagnose #316` 第 2 輪以 **159 筆完整 corpus** 重新定出值域規則（158/158，0 false positive）。本 proposal 的 What Changes / Impact 已依該結論重寫；design D1/D3/D5 與 spec R1/R3/R7 同步重寫，其餘決策經裁定為 still-valid 而保留。 +> **第 2 輪 re-baseline（2026-08-15）**：`/idd-verify --pr 318` FAIL（2 CRITICAL / 21 HIGH）。CRITICAL-2 以 90 筆真實語料證偽第 1 輪的封閉值域前提；`/idd-reorganize #316` 完成裁定；`/idd-diagnose #316` 第 2 輪以 **159 筆完整 corpus** 重新定出值域規則（159/159，0 false positive）。本 proposal 的 What Changes / Impact 已依該結論重寫；design D1/D3/D5 與 spec R1/R3/R7 同步重寫，其餘決策經裁定為 still-valid 而保留。 > > **Re-scope note（2026-08-14）**：本 change 於 #298 仍 open 時提出。走完 discuss → propose、進入 apply 時發現 **#298 已由 PR #309 / #306 修掉並 close** —— 但修正**只落在 `idd-list`**，另三個 consumer（`idd-all` / `idd-implement` / `idd-plan`）未動，且 `idd-list` 自身 Step 5 仍文載會截斷的 regex，與新增的 Step 3.7 直接矛盾。本 change 遂 re-scope 為**承接剩餘缺口**，追蹤於 **#316**；已完成的共用 helper、canonical 契約與回歸測試（全新檔、與已 merge 內容零衝突）原樣保留。Migration 相關 task 因目標 issue 全數 close 而 moot。 @@ -18,7 +18,7 @@ - **`parking-lot` label 是 parked 的主要訊號**，延期語彙是次要安全網。語彙清單取高精度、容忍低召回。 - **新增 actionability gate** —— 三訊號 OR 判定（Complexity 不可路由、`parking-lot` label、`### Blocking` 非空），放行需三者皆不成立，**且四個 consumer 必須實際呼叫它**。 - **三個 consumer 的 Complexity 解析統一** —— `idd-list`、`idd-all`、`idd-implement`（含 `idd-plan` 的 tier 確認）改用共用 helper，消除各自窄化。 -- **`### Blocking` 抽取重構為 gate 的 input** —— 共用 helper 逐 bullet 讀、placeholder 看開頭 token，對 55 筆凍結語料 0 誤判（第 3 輪；第 2 輪的整行比對誤判 31 筆、含 #316 自己）。#84 既有的 Blocked 分組輸出行為不得退化；未診斷的 issue 另成 `undiagnosed` 組並保留 `/idd-diagnose` 命令。 +- **`### Blocking` 抽取重構為 gate 的 input** —— 共用 helper 逐 bullet 讀、placeholder 看開頭 token，對 55 筆凍結語料與人工標註 54/55 一致（#1 為明文接受的 FP；第 2 輪的整行比對誤判 31 筆、含 #316 自己；語料 54/55 為 CLOSED，見 design 第 4 輪）。#84 既有的 Blocked 分組輸出行為不得退化；未診斷的 issue 另成 `undiagnosed` 組並保留 `/idd-diagnose` 命令。 - **`idd-diagnose` producer 端明訂延期意圖走 label** —— 不再宣告封閉值域；改為「tier 寫清楚、延期貼 label、不要把延期寫進本欄」。 - **零 migration** —— 新規則對既有 159 筆語料 159/159 全對（149 路由、9 擋下、1 缺區段），不需回填 label、不需改寫任何 Diagnosis comment。**零 migration 指「既有 diagnosis 不需改寫」，不是「backlog 可動性分佈不變」** —— 225 筆裡 66 筆從未 diagnose，全部 exit 4，顯示層以 `undiagnosed` 組承接（第 3 輪）。 - **`references/ic-r011-checkpoint.md` 的 parking 慣例收斂** —— `blocker:infeasible` / `blocker:waiting` 目前 0 個 issue 在用，實際在用的是 `parking-lot`。 @@ -33,11 +33,11 @@ - `idd-ic-r011-checkpoint`：skip path 的 (b)/(c) 分類改以 `parking-lot` label 立案（原 `blocker:infeasible` / `blocker:waiting` 從未建立過；`parking-lot` 自 3.1.0 起是 gate 的一級訊號）。delta 見 `specs/idd-ic-r011-checkpoint/spec.md`。 -為何無 modified capability：硬閘與 Layer V 這兩份既有 spec 所產出的帶後綴 verdict（形如 tier 後接 " via " 再接來源）在新抽取規則下**仍為合法值**（tier 開頭、` via ` 後綴不參與 tier 判定），其 requirement 不需修改；conflict-class 規範對 Complexity 欄位的正交性敘述同樣維持成立。 +其餘既有 spec 為何不需修改：硬閘與 Layer V 這兩份既有 spec 所產出的帶後綴 verdict（形如 tier 後接 " via " 再接來源）在新抽取規則下**仍為合法值**（tier 開頭、` via ` 後綴不參與 tier 判定），其 requirement 不需修改；conflict-class 規範對 Complexity 欄位的正交性敘述同樣維持成立。 ## Impact -- Affected specs: 新增 `actionability-gate` +- Affected specs: 新增 `actionability-gate`；修改 `idd-ic-r011-checkpoint`（(b)/(c) 立案 label → `parking-lot`） - Affected code: - New: - `plugins/issue-driven-dev/references/actionability-gate.md` diff --git a/openspec/changes/add-actionability-gate/specs/actionability-gate/spec.md b/openspec/changes/add-actionability-gate/specs/actionability-gate/spec.md index e91c96c..79a52eb 100644 --- a/openspec/changes/add-actionability-gate/specs/actionability-gate/spec.md +++ b/openspec/changes/add-actionability-gate/specs/actionability-gate/spec.md @@ -111,7 +111,7 @@ Complexity parsing and actionability verdict logic SHALL exist as one shared imp ### Requirement: Blocked-state output is preserved as a distinct display group -The gate SHALL produce a verdict together with its reason list, and the display layer SHALL group not-actionable issues by reason into exactly three groups. Issues whose reasons include any of `parking-lot-label`, `complexity-deferral-marker`, or `complexity-unparseable` SHALL appear under a parked grouping — the same set the parked-review flag lists. Otherwise, issues whose reasons include `blocking-nonempty` SHALL appear under the existing blocked-state grouping, with its group heading, its all-blocked banner text, and its footer counts unchanged from the behavior established for blocked-state awareness. Otherwise — reason `complexity-missing` alone — the issue SHALL appear under an undiagnosed grouping that retains the diagnose lifecycle command, because an issue that has never been diagnosed is in its birth state, not a parked state; on the 2026-09-07 open backlog that state held 11 of 14 issues, and filing it as parked hid the only correct next action and made the footer disagree with the parked-review flag by an order of magnitude. +The gate SHALL produce a verdict together with its reason list, and the display layer SHALL group not-actionable issues by reason into exactly three groups. Issues whose reasons include any of `parking-lot-label`, `complexity-deferral-marker`, or `complexity-unparseable` SHALL appear under a parked grouping. Otherwise, issues whose reasons include `blocking-nonempty` SHALL appear under the existing blocked-state grouping, with its group heading, its all-blocked banner text, and its footer counts unchanged from the behavior established for blocked-state awareness. Otherwise — reason `complexity-missing` alone — the issue SHALL appear under an undiagnosed grouping that retains the diagnose lifecycle command, because an issue that has never been diagnosed is in its birth state, not a parked state; on the 2026-09-07 open backlog that state held 11 of 14 issues, and filing it as parked hid the only correct next action and made the footer disagree with the parked-review flag by an order of magnitude. #### Scenario: Blocking-only issue keeps existing grouping @@ -167,7 +167,7 @@ Existing Diagnosis comments SHALL NOT be rewritten, and no label SHALL be backfi ### Requirement: The blocking signal is read per bullet against a frozen corpus -The `### Blocking` section SHALL be read as a list: the section is non-empty when any bullet is not a none-placeholder, and a placeholder SHALL be recognised by its leading token (`none`, `n/a`, `無`, optionally bulleted, decorated, or parenthesised, followed by end of line, a closing paren, or a separator) so that an annotated placeholder such as `- (none — 可動)` is empty while a bullet whose first word merely happens to be `none` is not. Lines that do not begin a bullet SHALL be treated as continuations of the bullet above. A trailing carriage return SHALL be stripped before either section reader judges a line. The rule SHALL be validated against every `### Blocking` section in the repository's issue bodies as a frozen regression fixture, because the first implementation was written against an assumed producer shape and withheld 31 of the 47 empty sections in that corpus, including the tracking issue of this change. +The `### Blocking` section SHALL be read as a list: the section is non-empty when any bullet is not a none-placeholder, and a placeholder SHALL be recognised by its leading token (`none`, `n/a`, `無`, optionally bulleted, decorated, or parenthesised, followed by end of line, a closing paren, or a separator) so that an annotated placeholder such as `- (none — 可動)` is empty while a bullet whose first word merely happens to be `none` is not. Lines that do not begin a `-` or `*` bullet SHALL be treated as continuations of the bullet above, and the accepted consequences SHALL be stated as a rule in both failure directions rather than as examples. A trailing carriage return SHALL be stripped before either section reader judges a line, the rule SHALL NOT depend on the process locale, an unbalanced code fence SHALL NOT hide a section below it, and control characters SHALL be removed from every value the helper surfaces. The rule SHALL be validated against every `### Blocking` section in the repository's issue bodies as a frozen regression fixture, because the first implementation was written against an assumed producer shape and withheld 31 of the 47 empty sections in that corpus, including the tracking issue of this change. #### Scenario: Annotated placeholder is empty @@ -184,6 +184,17 @@ The `### Blocking` section SHALL be read as a list: the section is non-empty whe - **WHEN** the section reads `- none of the reviewers replied yet` - **THEN** the blocking signal reports that line +#### Scenario: Locale does not change the verdict + +- **WHEN** the reader runs under `LC_ALL=C` +- **THEN** `- none ぁ x` is still reported as a blocker +- **AND** `（無）` is still empty + +#### Scenario: An unclosed fence does not hide the section + +- **WHEN** a body contains an unclosed code fence above `### Blocking` +- **THEN** the section is still read + #### Scenario: CRLF does not change either reader's verdict - **WHEN** an issue body or Diagnosis comment uses CRLF line endings diff --git a/openspec/changes/add-actionability-gate/specs/idd-ic-r011-checkpoint/spec.md b/openspec/changes/add-actionability-gate/specs/idd-ic-r011-checkpoint/spec.md index f0f9d6d..4e66b1f 100644 --- a/openspec/changes/add-actionability-gate/specs/idd-ic-r011-checkpoint/spec.md +++ b/openspec/changes/add-actionability-gate/specs/idd-ic-r011-checkpoint/spec.md @@ -2,7 +2,7 @@ ### Requirement: Skip path SHALL require explicit 3-category taxonomy disambiguation -When the user requests to skip filing one or more candidates (via explicit user prompt, env var bypass, or `# Disable IC_R011` flag), the skill SHALL present a second-level `AskUserQuestion` for each skip-candidate forcing selection among three categories: `(a) unactionable observation`, `(b) infeasible but understood`, or `(c) blocked on external state`. Selecting `(a)` SHALL skip filing and record `Skipped: (a) unactionable observation` in the audit trail. Selecting `(b)` or `(c)` SHALL still file the candidate via `gh issue create` with an added repository label of `parking-lot` or `parking-lot` respectively, and SHALL record `Skipped: (b) infeasible — filed as #NNN with `parking-lot` label` (or the `(c)` equivalent). +When the user requests to skip filing one or more candidates (via explicit user prompt, env var bypass, or `# Disable IC_R011` flag), the skill SHALL present a second-level `AskUserQuestion` for each skip-candidate forcing selection among three categories: `(a) unactionable observation`, `(b) infeasible but understood`, or `(c) blocked on external state`. Selecting `(a)` SHALL skip filing and record `Skipped: (a) unactionable observation` in the audit trail. Selecting `(b)` or `(c)` SHALL still file the candidate via `gh issue create` with an added repository label of `parking-lot` in both cases (the category survives only in the audit-trail string), and SHALL record `Skipped: (b) infeasible — filed as #NNN with parking-lot label` (or the `(c)` equivalent). #### Scenario: user skips one of three candidates with category (a) @@ -12,22 +12,14 @@ When the user requests to skip filing one or more candidates (via explicit user #### Scenario: user skips with category (b) - **WHEN** the user selects `(b) infeasible but understood` for a candidate -- **THEN** the skill MUST still call `gh issue create` for that candidate AND MUST attach the label `parking-lot` via the `--label` flag AND MUST record `Skipped: (b) infeasible — filed as # with `parking-lot` label` in the audit trail +- **THEN** the skill MUST still call `gh issue create` for that candidate AND MUST attach the label `parking-lot` via the `--label` flag AND MUST record `Skipped: (b) infeasible — filed as # with parking-lot label` in the audit trail ##### Example: skip-and-file audit trail entries - **GIVEN** 3 candidates [X, Y, Z], user skips Z with category (c) - **WHEN** the skill executes -- **THEN** the audit trail contains both `Filed: #X-num, #Y-num` and `Skipped: (c) blocked-on-external — filed as #Z-num with `parking-lot` label` +- **THEN** the audit trail contains both `Filed: #X-num, #Y-num` and `Skipped: (c) blocked-on-external — filed as #Z-num with parking-lot label` - - ---- > Modified by `add-actionability-gate` (#316 round 3): the (b) / (c) skip categories file the candidate with the `parking-lot` label instead of `blocker:infeasible` / `blocker:waiting`. Those two labels were never created in any repository using IDD, while `parking-lot` is in use and — since 3.1.0 — is the primary parked signal of the actionability gate, so a sister issue filed under (b) / (c) is born parked and stays out of routing until a human removes the label. The reference (`ic-r011-checkpoint.md`), `idd-issue`, and `idd-diagnose` were converged in the same change; this delta brings the live spec's MUST into agreement. diff --git a/openspec/changes/add-actionability-gate/tasks.md b/openspec/changes/add-actionability-gate/tasks.md index b66c902..7e388f7 100644 --- a/openspec/changes/add-actionability-gate/tasks.md +++ b/openspec/changes/add-actionability-gate/tasks.md @@ -58,7 +58,7 @@ ## 9. 文件同步（第 2 輪） -- [x] 9.1 `references/actionability-gate.md` 依新規則重寫。行為契約：封閉值域段改為「tier prefix 抽取 + 延期語彙」；reason 值域 4 → 5；新增「風險姿態：label 為主、語彙為輔」段並說明漏抓/誤抓的不對稱處置。驗證：內容審查確認不再出現「合法值域為封閉四值」的宣稱，且 corpus 數據（159 筆 / 158-158）有明文引用。檔案：`plugins/issue-driven-dev/references/actionability-gate.md` +- [x] 9.1 `references/actionability-gate.md` 依新規則重寫。行為契約：封閉值域段改為「tier prefix 抽取 + 延期語彙」；reason 值域 4 → 5；新增「風險姿態：label 為主、語彙為輔」段並說明漏抓/誤抓的不對稱處置。驗證：內容審查確認不再出現「合法值域為封閉四值」的宣稱，且 corpus 數據（159 筆 / 159/159）有明文引用。檔案：`plugins/issue-driven-dev/references/actionability-gate.md` - [x] 9.2 [P] `idd-diagnose` producer 宣告改寫。行為契約：移除封閉值域宣告，改為「tier 寫清楚；延期意圖貼 `parking-lot` label，不要寫進 `### Complexity`」，並保留「producer 不自動貼 label」一條。驗證：內容審查確認不再宣告封閉值域，且 159 筆語料的常態寫法（tier + 同行理由）未被規定為違規。檔案：`plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md` @@ -71,4 +71,5 @@ - [x] 10.5 drift guard 補釘：verdict 條件式捕捉外殼、`REASONS=` 分支、`FATAL … misuse` 分支、issue 號驗型、author filter、allowed-tools `jq`/`python3`、`=$(gh issue view … --json comments` 全檔 refute。 - [x] 10.6 in-scope 修正：`idd-all:1007` 分頁 + 3b.1 分頁 fallback；`idd-list` Step 3.7 取 Step 2 資料、≥100 才分頁、`|| …continue`、state guard、`REASONS` 重設、C0 剝除；`rules/sdd-integration.md` 移除平行解析敘述；row 905 真的帶 `- [~]`；fixture #160/#136 逐字；≥3 計數只算真實列；表頭 `VEXIT · CEXIT · TIER`；reference 增訊號 3 風險姿態、分母揭露、mention class、前置需求；158/158 → 159/159。 - [~] 10.7 訊號 3 的 producer contract 或退回 model 判定 —— deferred to #336（超出本 change；第 3 輪為止血）。 +- [x] 10.8 第 4 輪（verify #318 第 3 輪 FAIL）：idd-implement Step 2.5 缺值時以同 helper 重跑 gate；四個 consumer 與 canonical shape 印出 verdict；idd-list 改 per-issue state 並定義 `skipped`；placeholder 規則改為 locale 無關的交替式並在 `LC_ALL=C` 下測；未閉合 fence 停用 fence 追蹤；helper 輸出端剝 C0；`idd_actionability_group` 空值 exit 2；corpus-blocking 每列帶原始 body 走 extractor、宣稱改為 54/55 與 54/55 CLOSED；Accepted misses 改寫為雙向規則、兩條被否決的 regex 入庫；idd-plan 補 allowed-tools 與 Step 1 fetch；idd-all sub-issue 驗型 + author filter；表格列補三鍵；spec delta 去 `respectively` / 巢狀反引號 / `@trace`；cluster 路徑覆蓋缺口記入契約並開 #340。 diff --git a/plugins/issue-driven-dev/.claude-plugin/plugin.json b/plugins/issue-driven-dev/.claude-plugin/plugin.json index f9da844..1034f07 100644 --- a/plugins/issue-driven-dev/.claude-plugin/plugin.json +++ b/plugins/issue-driven-dev/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "issue-driven-dev", - "description": "v3.1.0: the actionability gate, rounds 2 and 3. Round 1 read `### Complexity` against a closed value domain that the repository's own 159 diagnoses refuted (66 real values wrongly refused) and shipped a three-signal gate no consumer called. Now the tier is the leading whole word (rationale, decoration and ` via` suffixes are legal), the whole line is scanned for a small deferral vocabulary (exit 5, reason `complexity-deferral-marker` — a parked state, not a defect), `### Blocking` is read by a shared fence-aware helper, and idd-list / idd-all / idd-implement / idd-plan actually call the verdict with all three signals in a paginated, `set -e`-safe shape pinned by a drift test. A frozen 159-issue corpus fixture makes 'zero migration' falsifiable: 149 routable, 9 deferral, 1 missing, 0 unparseable. idd-list gains Parked and Needs-diagnosis groups; the #84 blocked surface is preserved verbatim. Round 3 read `### Blocking` per bullet with a leading-token placeholder rule frozen against the repo's 55 real sections (round 2 had withheld 31 of the 47 empty ones, including #316 itself), moved idd-implement's gate ahead of any branch or comment, and retired `blocker:*`.", + "description": "v3.1.0: the actionability gate, rounds 2 to 4. Round 1 read `### Complexity` against a closed value domain that the repository's own 159 diagnoses refuted (66 real values wrongly refused) and shipped a three-signal gate no consumer called. Now the tier is the leading whole word (rationale, decoration and ` via` suffixes are legal), the whole line is scanned for a small deferral vocabulary (exit 5, reason `complexity-deferral-marker` — a parked state, not a defect), `### Blocking` is read by a shared fence-aware helper, and idd-list / idd-all / idd-implement / idd-plan actually call the verdict with all three signals in a paginated, `set -e`-safe shape pinned by a drift test. A frozen 159-issue corpus fixture makes 'zero migration' falsifiable: 149 routable, 9 deferral, 1 missing, 0 unparseable. idd-list gains Parked and Needs-diagnosis groups; the #84 blocked surface is preserved verbatim. Round 3 read `### Blocking` per bullet with a leading-token placeholder rule frozen against the repo's 55 real sections (54/55 agree with hand review; round 2 had withheld 31 of the 48 empty ones, including #316 itself), moved idd-implement's gate ahead of any branch or comment, and retired `blocker:*`. Round 4 repaired round 3's regressions (cross-Bash-block gate variables, a listing-level state guard, a locale-dependent rule, an unclosed-fence fail-open), made the gate print its verdict, and brought every corpus claim down to what it proves.", "version": "3.1.0", "author": { "name": "Che Cheng" diff --git a/plugins/issue-driven-dev/CHANGELOG.md b/plugins/issue-driven-dev/CHANGELOG.md index edfabbc..0f075d4 100644 --- a/plugins/issue-driven-dev/CHANGELOG.md +++ b/plugins/issue-driven-dev/CHANGELOG.md @@ -124,6 +124,41 @@ actionable, 1 blocked (the misjudgement), **11 "parked"** — all eleven merely Codex was absent on that verify (usage limit); the Devil's Advocate carried the oracle role. +### Round 4 — repair the regressions, bring the claims down to the evidence + +The round-3 verify (again 5-of-6; Codex still rate-limited) returned FAIL. Round 3's six +repairs are real — every lens re-measured them live — but round 3 had introduced its own +regressions and over-claimed what the new corpus proved. The Devil's Advocate's ruling, +followed here: fix correctness and honesty, not coverage; do not add another character class, +do not demote the signal mid-verify. + +- **idd-implement** Step 2.5 consumed the gate's variables set ~280 lines and several Bash + calls earlier and forbade re-running — the same cross-block break the same commit had fixed + in idd-all. It now checks `${VEXIT:-}` and re-runs the Step 0.35 block with the same helper. +- **The gate prints its verdict** in all four consumers and the canonical shape. A block that + only assigned `$VEXIT` showed a parked issue to the executing model as a clean, silent exit 0. +- **idd-list** guarded with the listing-wide `--state` flag, so `--state all` marked every + issue `skipped` and Suggested-next vanished (a regression against `main`). Now per-issue + `.state == "OPEN"`; `skipped` rows keep the phase × PR matrix. +- **Locale**: the placeholder rule had multibyte separators inside a bracket expression; under + `LC_ALL=C` it flipped both directions and the suite itself failed three assertions. Rewritten + as alternations; the test runs it under `LC_ALL=C`. +- **Unclosed fence**: one stray ``` above `### Blocking` swallowed the section (live #290), + which would read a real blocker as "none". Unbalanced fences now disable fence tracking for + that body; balanced fenced examples are still skipped. +- **C0 / DEL scrubbing** lives in the helper's outputs (round 3 only described it, and the + described set omitted `\r`); `idd_actionability_group ""` is exit 2, not a quiet *parked*. +- **Claims**: "0 FP / 0 FN on 55 frozen sections" is now "54/55 agree with the hand review, + #1 an accepted false positive, 54/55 CLOSED issues the gate never evaluates, extractor + covered because each row carries its original body". #336's acceptance bar is the semantic + truth (48 / 7), not the fixture. The accepted-miss list is a rule in both directions; the + two rejected placeholder regexes are recorded with their FP/FN counts. +- Hygiene from the report: idd-plan gains `allowed-tools`; idd-all's Layer-V sub-issue scan + digit-checks and author-filters; routing tables' rows carry all three keys; `REASONS` reset + on the actionable path; spec delta loses its `respectively`, nested backticks and a + mis-attributed `@trace`; cluster-path coverage (first issue only — pre-existing) is stated + in the contract and tracked in #340. + ### Honest residue - **`### Blocking` is regex-read for now.** The leading-token rule is a stop, not an answer diff --git a/plugins/issue-driven-dev/references/actionability-gate.md b/plugins/issue-driven-dev/references/actionability-gate.md index 93473e1..94c8ec1 100644 --- a/plugins/issue-driven-dev/references/actionability-gate.md +++ b/plugins/issue-driven-dev/references/actionability-gate.md @@ -82,7 +82,7 @@ The rule was derived from and validated against every diagnosed issue in this re Every one of the 159 routes as hand-reviewed; **0 false positives**. No Diagnosis comment was rewritten and no label was backfilled to get there — **zero migration** is a claim about this corpus, and the test is what makes it falsifiable. Read it for what it says: *no existing diagnosis needs rewriting*. It does **not** say the backlog's actionability distribution is unchanged — on the 2026-09-07 open backlog only 2 of 14 issues were routable, because 11 had never been diagnosed. That is why the display distinguishes *undiagnosed* from *parked*. -**Signal 3 has its own frozen corpus**: `scripts/tests/actionability-gate/fixtures/corpus-blocking.json` — every `### Blocking` section in the bodies of all 238 issues (55 sections, hand-reviewed: 47 empty, 8 non-empty). Round 2 shipped `idd_blocking_section` without this and withheld 31 of the 47 — including #316's own `- (none — 可動)`. The rule that is 0 FP / 0 FN on it is in the helper's comments; two other candidates were measured there and rejected (one cleared every real blocker, one left 20 false positives). +**Signal 3 has its own frozen corpus — read it for what it proves.** `scripts/tests/actionability-gate/fixtures/corpus-blocking.json` holds every `### Blocking` section in the bodies of all 238 issues (55 sections, first section per issue; hand review: 48 empty, 7 real blockers), each row with its **original body** so the shared extractor is exercised, not bypassed. The reader agrees with the hand review on **54 of the 55**; row #1 is an accepted false positive (an informational second bullet). **54 of the 55 issues are CLOSED**, which the gate never evaluates — on the 2026-09-07 open backlog signal 3 decided one issue (#316 itself). So the corpus is a legitimate sample of producer style and a regression baseline; it is *not* proof of gate correctness on the live backlog, and #336's acceptance bar is the semantic truth (48 / 7), not the fixture's expectations. Round 2 shipped `idd_blocking_section` without any of this and withheld 31 of the 48 — including #316's own `- (none — 可動)`. Two rival rules were measured on the same rows and rejected; their text and FP/FN counts are recorded in the helper. The rule is locale-independent (multibyte separators as alternations, never inside a bracket expression — under `LC_ALL=C` the round-3 rule flipped both directions) and the test runs it under `LC_ALL=C`. ## Risk posture — the label is primary, the vocabulary is a net @@ -95,7 +95,7 @@ Deferral vocabulary is a **high-precision, low-recall heuristic**. It is NOT a c So the rule for adding a term: **corpus evidence of zero false positives**, recorded in the regression fixture. Resemblance to an existing term is not evidence. -**Signal 3 (`### Blocking`) has a different posture, and the difference matters.** It is a **list** field written by `idd-update`'s template `- {blocker 1, or "(none)"}`, model-filled, with 35+ spellings for "no blocker" in the wild. The reader therefore (a) judges **each bullet** — any non-placeholder bullet makes the section non-empty, so `- (none)` followed by `- 等 …` is a blocker — and (b) recognises a placeholder by its **leading token** (`none` · `n/a` · `無`, optionally bulleted, decorated or parenthesised, followed by end of line, a closing paren or a separator), so `- (none — 可動)` is empty while `- none of the reviewers replied yet` is not. Its failure directions are **not** symmetric with signal 1's: a miss here is not "pre-#298 behaviour", it is a regression of #84's blocked-state surfacing; a false positive is the hard stop the table above calls unacceptable. Accepted misses, documented: a placeholder token followed by a *clause* (`- (none) but actually blocked by #86`, `- n/a — blocked by #99`) reads as empty — the token wins. The corpus has none of these. Whether this field should be regex-read at all, or given a producer contract / returned to model judgement, is **#336**. +**Signal 3 (`### Blocking`) has a different posture, and the difference matters.** It is a **list** field written by `idd-update`'s template `- {blocker 1, or "(none)"}`, model-filled, with 35+ spellings for "no blocker" in the wild. The reader therefore (a) judges **each bullet** — any non-placeholder bullet makes the section non-empty, so `- (none)` followed by `- 等 …` is a blocker — and (b) recognises a placeholder by its **leading token** (`none` · `n/a` · `無`, optionally bulleted, decorated or parenthesised, followed by end of line, a closing paren or a separator), so `- (none — 可動)` is empty while `- none of the reviewers replied yet` is not. Its failure directions are **not** symmetric with signal 1's: a miss here is not "pre-#298 behaviour", it is a regression of #84's blocked-state surfacing; a false positive is the hard stop the table above calls unacceptable. **The rule for misses, stated as a rule** (both directions accepted, documented, pinned by test): *the leading token decides the bullet, and only `-` / `*` bullets or the section's first line are judged*. Fail-open: a placeholder token followed by a clause (`- (none) but actually blocked by #86`) reads as empty, and a real blocker written after a placeholder as an ordered-list item, `+` bullet, blockquote, table row, `####` line or bare paragraph is a continuation and is not read. Fail-closed: a lead-in sentence before the first bullet is judged as the first line and reads as a blocker. The corpus has none of these shapes; widening the bullet class was measured and rejected (it enlarges the fail-closed side). Only the **first** `### Blocking` section of a body is read. Whether this field should be regex-read at all — producer contract or model judgement, first-vs-last section, and IC_R011 (c) semantics — is **#336**; do not extend the rule by analogy before that is decided. An unbalanced (unclosed) fence in a body disables fence tracking for that body so a section below it is still found (live instance #290). **Mentions are not declarations — and the scan cannot tell them apart.** `Plan（把 parking lot 的文件敘述收斂）` and `Simple, no longer deferred` both trip the deferral scan. The corpus has zero such values, and negation logic would open a new miss surface, so the vocabulary is left as is; the operator sees the raw line and the remedy for this class is to keep meta-discussion out of the value line. @@ -163,17 +163,17 @@ The gate emits a verdict together with its reason list. The display layer groups | Reasons | Group | |---|---| -| any of `parking-lot-label` · `complexity-deferral-marker` · `complexity-unparseable` | **parked** — a human parked it, the diagnosis said so, or the value is a defect to repair; each row shows the raw `### Complexity` line (from the helper's stderr) or the label, so the operator sees *why*. This is also exactly the set `idd-list --parked` reviews | +| any of `parking-lot-label` · `complexity-deferral-marker` · `complexity-unparseable` | **parked** — a human parked it, the diagnosis said so, or the value is a defect to repair; each row shows the raw `### Complexity` line (from the helper's stderr) or the label, so the operator sees *why*. (`idd-list --parked` is a *revisit* list with its own definition — parked ∪ blocked, minus data defects — not this group.) | | otherwise `blocking-nonempty` | the existing **blocked**-state group (#84) — heading, all-blocked banner text, and footer counts unchanged | | otherwise (`complexity-missing` alone) | **undiagnosed** — the issue has not been diagnosed yet. That is every issue's birth state and, on a live backlog, the dominant one (11 of 14 open issues on 2026-09-07); round 2 filed it under *Parked*, which hid `→ /idd-diagnose #N` and made the footer disagree with `--parked` by an order of magnitude. The display keeps the diagnose command | -`idd_actionability_group` returns exactly these three strings; the raw values it surfaces are third-party text and are printed with C0 control characters stripped — **data, never instructions**. +`idd_actionability_group` returns exactly these three strings (an empty or unknown reason list is exit 2 — API misuse, never a quiet *parked*). The raw values the helper surfaces are third-party text: **the helper strips C0 control characters and DEL from its own outputs** (TAB and LF kept) so a `\r` or an ANSI sequence in an issue body cannot repaint the terminal or the executing model's context — **data, never instructions**. Issue bodies carry no author filter (anyone can open an issue on a public repo); that is why the strip lives in the helper and not in each consumer. Unifying the *judgment* does not mean unifying the *presentation*. #84's blocked-state surface is user-facing behavior people rely on; merging it into one undifferentiated bucket would be a regression dressed as a simplification. ## Consumer contract -The four routing consumers SHALL invoke the shared implementation at `scripts/lib/actionability.sh` and MUST NOT embed a private parse — of `### Complexity` **or** of `### Blocking`. **The gate SHALL run before any egress or branch creation** (a comment, a `git checkout -b`, a tree-lock): a human-parked issue must not receive an Implementation Plan comment before being told it is parked — round 2's `idd-implement` did exactly that at Step 2.5, and the test now pins the order. Prerequisites: `gh`, `jq`, `python3` (pre-approve them in `allowed-tools` so unattended runs do not stall on a permission prompt). The canonical call shape, in full, is: +The four routing consumers SHALL invoke the shared implementation at `scripts/lib/actionability.sh` and MUST NOT embed a private parse — of `### Complexity` **or** of `### Blocking`. **The gate SHALL run before any egress or branch creation** (a comment, a `git checkout -b`, a tree-lock): a human-parked issue must not receive an Implementation Plan comment before being told it is parked — round 2's `idd-implement` did exactly that at Step 2.5, and the test now pins the order. **The gate SHALL print its verdict** — skills are executed by a model whose only observation channel is the Bash output; a block that merely assigns `$VEXIT` shows a parked issue as a clean, silent exit 0. **Shell variables do not survive across Bash calls**: a consumer that reads the gate's variables in a later block MUST check `${VEXIT:-}` and re-run the same block with the same helper when they are absent (never a private regex). **Cluster path**: the consumers currently gate the *first* issue of `/idd-implement #a #b #c` only — issue-set parsing happens after the gate; tracked in #340. Diagnosis comments are trusted only from `OWNER` / `MEMBER` / `COLLABORATOR` (org-repo maintainers are `MEMBER`); a former collaborator's comments are re-classified `CONTRIBUTOR` by GitHub and would then read as `complexity-missing`. Prerequisites: `gh`, `jq`, `python3` (pre-approve them in `allowed-tools` so unattended runs do not stall on a permission prompt). The canonical call shape, in full, is: ```bash # 0. Missing helper → fail loud, name the path. Never fall back to a private regex. @@ -217,10 +217,13 @@ COMPLEXITY_ERR=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>&1 >/dev/null) || tr # never "not actionable"; do not fold it into the withheld branch. if VERDICT=$(idd_actionability_verdict --complexity-exit "$CEXIT" --parking-label "$HAS_PARKING" --blocking-section "$BLOCKING" 2>&1); then VEXIT=0; else VEXIT=$?; fi case "$VEXIT" in - 0) ;; # actionable → dispatch on "$TIER" + 0) REASONS="" ;; # actionable → dispatch on "$TIER" (reset: a cluster loop must not carry the previous issue's reasons) 1) REASONS="${VERDICT#not-actionable: }" ;; # withheld → surface "$REASONS" + "$COMPLEXITY_ERR" / "$BLOCK_LINE"; no lifecycle command *) echo "FATAL: idd_actionability_verdict misuse — $VERDICT" >&2; exit 1 ;; # a LISTING consumer prints this and marks the row `(gate error)` instead of exiting esac +# 5. Print the verdict. The executing model sees only this output; an unprinted +# withheld verdict is indistinguishable from an actionable issue. +printf 'gate #%s: VEXIT=%s TIER=%s REASONS=%s | %s%s\n' "$N" "$VEXIT" "${TIER:-}" "${REASONS:-}" "${COMPLEXITY_ERR:-}" "${BLOCK_LINE:-}" ``` `idd-list` deviates in three documented ways: it takes labels/body/comments from its bulk fetch and paginates only when the comment array is ≥ 100 (its own anti-N+1 rule), it skips the gate for non-open issues, and every fetch failure marks the row rather than exiting — "one bad value does not suppress the other issues" applies to API errors too. diff --git a/plugins/issue-driven-dev/scripts/lib/actionability.sh b/plugins/issue-driven-dev/scripts/lib/actionability.sh index 07d7492..11dcf6d 100644 --- a/plugins/issue-driven-dev/scripts/lib/actionability.sh +++ b/plugins/issue-driven-dev/scripts/lib/actionability.sh @@ -31,6 +31,17 @@ # the issue under its own reason, because a deferral is a legitimate # state — not a data defect to repair. # +# WHAT THE FROZEN BLOCKING CORPUS DOES AND DOES NOT PROVE (verify #318 round 3) +# scripts/tests/actionability-gate/fixtures/corpus-blocking.json holds every +# `### Blocking` section in this repo's issue bodies (55; 54 of them CLOSED +# issues the gate never evaluates — signal 3's live effect on 2026-09-07 was +# one issue, #316 itself). The reader agrees with the hand review on 54/55; +# row #1 is an accepted false positive (an informational second bullet). Each +# row now carries the original body, so the shared extractor — fences, +# headings, CR — is exercised by the corpus, not bypassed by a synthesised +# body. The corpus is a legitimate sample of producer style; it is NOT proof +# of gate correctness on the live backlog. +# # RISK POSTURE # The `parking-lot` label is the PRIMARY parked signal (human-authored, # mutable, removable). Deferral vocabulary is a SECONDARY high-precision net: @@ -60,10 +71,19 @@ # - the section ends at the next heading of the same or higher level; # a deeper `####` line is skipped, never taken as a value _idd_section_lines() { - local body="${1-}" heading="${2-}" - printf '%s\n' "$body" | awk -v h="$heading" ' + local body="${1-}" heading="${2-}" nfence nofence=0 + # An UNCLOSED fence would otherwise swallow every later section (live + # instance #290: one ``` at line 8, `### Blocking` at line 39 → empty → + # a real blocker below it would read as "no blocker"). Fence tracking is + # only trustworthy when fences are balanced; with an odd count it is + # disabled for that body. A balanced fenced template example is still + # skipped (verify #318 H4). + nfence=$(printf '%s\n' "$body" | grep -cE '^[[:space:]]*(```|~~~)' || true) + [ $((nfence % 2)) -eq 1 ] && nofence=1 + printf '%s\n' "$body" | awk -v h="$heading" -v nofence="$nofence" ' { sub(/\r$/, "") } - { + nofence == 1 { } + nofence == 0 { if (fence != "") { if (fence == "`" && $0 ~ /^[[:space:]]*```/) fence = "" else if (fence == "~" && $0 ~ /^[[:space:]]*~~~/) fence = "" @@ -79,7 +99,19 @@ _idd_section_lines() { ' } _idd_section_first_line() { - _idd_section_lines "$1" "$2" | head -n 1 + # No `| head -n 1`: closing the pipe early makes the upstream awk exit 141 + # under `pipefail`. Capture, then take the first line. + local all + all=$(_idd_section_lines "$1" "$2") + printf '%s\n' "${all%%$'\n'*}" +} + +# Third-party text leaves this file with C0 control characters (and DEL) +# removed — TAB and LF kept — so a `\r` or an ANSI sequence inside an issue +# body cannot repaint the operator's terminal or the executing model's prompt. +# Surfaced values are DATA, never instructions. +_idd_scrub() { + LC_ALL=C tr -d '\000-\010\013-\037\177' } # ── contract 1: parse the Complexity field ─────────────────────────────────── @@ -133,7 +165,7 @@ idd_parse_complexity() { done if [ -z "$tier" ]; then - printf 'unparseable-complexity: %s\n' "$raw" >&2 + printf 'unparseable-complexity: %s\n' "$raw" | _idd_scrub >&2 return 3 fi @@ -141,7 +173,7 @@ idd_parse_complexity() { # parenthetical or after a ` via ` suffix (verify #318 H3). Conservative on # purpose: see RISK POSTURE above before adding a term. if printf '%s\n' "$val" | grep -qiE 'when[[:space:]_-]+triggered|parking[[:space:]_-]*lot|deferred|暫緩'; then - printf 'deferral-marker: %s\n' "$raw" >&2 + printf 'deferral-marker: %s\n' "$raw" | _idd_scrub >&2 return 5 fi @@ -244,21 +276,50 @@ idd_actionability_verdict() { # this repo, 48 are semantically empty and 31 of those carry text after the # token (`- (none — 可動)`, `- (none) — closed`, `（無）`). Round 2 anchored the # match to the whole line and withheld all 31 — including #316 itself. The rule -# below is 0 FP / 0 FN on the hand-reviewed corpus frozen in +# below agrees with the hand review on 54 of the 55 rows frozen in # scripts/tests/actionability-gate/fixtures/corpus-blocking.json; two other # candidate rules were tested there and rejected (one cleared every real # blocker, one left 20 false positives). # # Recognised token, any case, optionally bulleted / decorated / parenthesised: -# none · n/a · 無 followed by end of line, a closing paren, or a separator -# (— – - , 、 : ： ;). A bare bullet or bare decoration is also empty. -# Accepted misses (documented, not in the corpus): `- (none) but actually -# blocked by #86`, `- n/a — blocked by #99` read as empty; the token wins. -# A real blocker that happens to START with the token (`- none of the -# reviewers replied yet`) is NOT a placeholder because the token is followed by -# a word, not a terminator — that case is pinned by test. +# none · n/a · 無 followed by end of line, a closing paren, a full stop, +# or a separator (— – - , 、 : ： ;). A bare bullet or bare decoration is +# also empty. +# +# THE RULE FOR MISSES, stated as a rule (not as examples — see +# common-spec-prose-enumeration): the leading token decides the bullet. Both +# directions follow from that and are accepted, documented, and pinned by test: +# fail-open : a placeholder token followed by a clause (`- (none) but +# actually blocked by #86`, `- n/a — blocked by #99`) reads as +# EMPTY; a real blocker written as an ordered-list item, a `+` +# bullet, a blockquote, a table row, a `####` line or a bare +# paragraph AFTER a placeholder bullet is a continuation and is +# NOT read (only `-` / `*` bullets, or the section's first +# line, are judged); +# fail-closed: a lead-in sentence before the first bullet (`目前阻塞如下：` +# then `- (none)`) is judged as the first line and reads as a +# BLOCKER. +# The live corpus has zero cases of either shape. Widening the bullet class +# was measured and rejected in verify #318 round 3 — it enlarges the +# fail-closed side, and whether this field should be regex-read at all is +# #336. Do not extend this by analogy; change #336 first. +# +# Multibyte characters are written as alternations, never inside a bracket +# expression: under LC_ALL=C a bracket splits into bytes and `— – 、 ：` +# turned every kana / CJK-punctuation lead byte into a separator (both +# directions flipped; the suite itself failed 3 assertions). The rule below is +# locale-independent and the test runs it under LC_ALL=C. +# +# Rejected candidate rules (measured on the same 55 rows; kept so nobody +# re-derives them): +# '^[[:space:]]*([-*][[:space:]]+)?[_*`（(]*[[:space:]]*(none|n/a|無|-)([^[:alnum:]]|$)' +# → 0 FP but 7 FN: the optional bullet group lets `-` in the token set +# eat the bullet dash, so every `- 等 …` bullet read as empty. +# '^[[:space:]]*([-*][[:space:]]+)?[_*`]*[(（]?[[:space:]]*(none|n/a|無)[[:space:]]*([)）]|$)' +# → 20 FP: requires `)` or EOL right after the token, so `- (none — 可動)` +# (#316 itself) still read as a blocker. _idd_is_none_placeholder() { # line - printf '%s\n' "$1" | grep -qiE '^[[:space:]]*([-*][[:space:]]+)?[_*`]*[（(]?[[:space:]]*(none|n/a|無)[_*`]*[[:space:]]*([)）]|$|[—–,、:：;-])' \ + printf '%s\n' "$1" | grep -qiE '^[[:space:]]*([-*][[:space:]]+)?[_*`]*(（|\()?[[:space:]]*[_*`]*(none|n/a|無)[_*`]*[[:space:]]*(\)|）|$|\.|。|[,:;-]|—|–|、|：)' \ || printf '%s\n' "$1" | grep -qE '^[[:space:]]*[-*]?[_*`]*[[:space:]]*$' } idd_blocking_section() { @@ -267,7 +328,7 @@ idd_blocking_section() { if [ "$first" = 1 ] || printf '%s\n' "$line" | grep -qE '^[[:space:]]*[-*][[:space:]]'; then first=0 if ! _idd_is_none_placeholder "$line"; then - printf '%s\n' "$line" + printf '%s\n' "$line" | _idd_scrub return 0 fi fi @@ -278,15 +339,15 @@ idd_blocking_section() { # ── display helper: which group does a not-actionable issue belong to? ─────── # # idd_actionability_group -# stdout : "blocked" | "parked" | "undiagnosed" +# stdout : "blocked" | "parked" | "undiagnosed" exit 2 : empty/unknown reasons # # parked — any of parking-lot-label / complexity-deferral-marker / # complexity-unparseable is present (a human parked it, the # diagnosis said so, or the value is a defect to repair) -# blocked — otherwise, blocking-nonempty is present: reason -# `blocking-nonempty` ALONE keeps the pre-#298 blocked-state -# grouping (#84) intact — heading, banner and footer counts are -# user-facing behavior that must not regress +# blocked — otherwise, blocking-nonempty is present (alone, or together +# with complexity-missing — spec R6 "Missing diagnosis with a +# real blocker is blocked"): the pre-#298 blocked-state grouping +# (#84) — heading, banner and footer counts — must not regress # undiagnosed — otherwise (complexity-missing alone): the issue has simply # not been diagnosed yet. That is every issue's birth state, not # a parked state — on the live backlog it is the DOMINANT state @@ -299,6 +360,9 @@ idd_actionability_group() { *parking-lot-label*|*complexity-deferral-marker*|*complexity-unparseable*) printf 'parked\n' ;; *blocking-nonempty*) printf 'blocked\n' ;; *complexity-missing*) printf 'undiagnosed\n' ;; - *) printf 'parked\n' ;; + *) # an empty or unknown reason list is API misuse (called on an + # actionable issue?) — fail loud like the verdict does, never + # quietly park a routable issue + printf 'idd_actionability_group: empty or unknown reason list (got: %s)\n' "${reasons:-}" >&2; return 2 ;; esac } diff --git a/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/corpus-blocking.json b/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/corpus-blocking.json index 6273d2e..9b8a0bc 100644 --- a/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/corpus-blocking.json +++ b/plugins/issue-driven-dev/scripts/tests/actionability-gate/fixtures/corpus-blocking.json @@ -1,5 +1,5 @@ { - "_provenance": "Every `### Blocking` section found in the BODY of the 238 issues of PsychQuant/issue-driven-development (snapshot 2026-09-07, `gh issue list --state all --limit 400`): 55 sections, hand-reviewed — 47 semantically empty (a none-placeholder, with or without annotation), 8 non-empty (7 real blockers that all begin with `- 等 …`, plus #1 whose second bullet is a note read as non-empty by the per-bullet rule — accepted, see its note). Rows carry every non-blank line of the section verbatim. Frozen regression baseline for `idd_blocking_section`; do NOT regenerate from live GitHub.", + "_provenance": "Every `### Blocking` section found in the BODY of the 238 issues of PsychQuant/issue-driven-development (snapshot 2026-09-07, `gh issue list --state all --limit 400`): 55 sections in 55 issues (first section per issue; #102 has four and #103 two — later ones are not rows). Hand-reviewed: 48 semantically empty, 7 real blockers (all begin `- 等 …`). `expect_empty` is the RULE's expected verdict, which agrees with the hand review on 54/55 — row #1 is an accepted false positive (its second bullet is an informational note). 54 of the 55 issues are CLOSED, which the gate never evaluates; on the 2026-09-07 open backlog signal 3 decided one issue (#316). Each row carries the ORIGINAL issue body so the test feeds the shared extractor (fences, headings, CR), not a synthesised section; #290's body has an unclosed fence. Frozen regression baseline for `idd_blocking_section`; do NOT regenerate from live GitHub.", "rows": [ { "number": 1, @@ -10,7 +10,8 @@ ], "expect_empty": false, "expect_first_blocker": "- 12 個 P2/P3 follow-up 整合為 9 個 focused issue (#2-#10),全部 ref Related: #1", - "note": "Second bullet is an informational note, not a blocker — the per-bullet rule reads it as non-empty. Accepted 1/55 false positive on a CLOSED issue; the structural fix is #336 (producer contract)." + "note": "Second bullet is an informational note, not a blocker — the per-bullet rule reads it as non-empty. Accepted 1/55 false positive on a CLOSED issue; the structural fix is #336 (producer contract).", + "body": "## Problem\n\n> **Original request (使用者於 thesis project session 中提出，2026-05-03)**:\n> 「idd-all 我想要有一種是直接 commit 的方案，因為 PR 不一定很方便，我其實是在旁邊，這樣的 all 中間還是可以問我問題，總之 all 可以分成 human-in-the-loop 跟不是的情況」\n\n當前 `idd-all` v2.40.0 強制走 PR path 且強制 unattended（所有 sub-skill 的 AskUserQuestion 都被 suppress）。這個設計對「fire-and-forget orchestration」很合適，但對「使用者就在旁邊、想監控進度也想被諮詢」的常見場景反而是 friction：\n\n1. **PR 對小型 / 個人 repo 是 overhead** — 沒有 review 流程的 solo project，每個 issue 開 feature branch + PR 是純 ceremony\n2. **Sub-skill 的 attended 預設被一律 override** — 像 `spectra-discuss` 的多輪對話、`spectra-propose` 的 Park/Apply 抉擇、`idd-implement` 的 plan-tier approval gate，全被靜默跳過。當使用者就在旁邊時，這些 checkpoint 反而是它們存在的意義\n\n## Type\nfeature / enhancement\n\n## Proposed design (待 diagnose 細化)\n\n### 兩種模式\n\n| Mode | Path | Sub-skill questions | Stop point | Use case |\n|------|------|--------------------|-----------:|---------|\n| **Unattended** (current v2.40.0) | PR (forced) | All suppressed | Verify → stop | Background automation, scheduled cron, /loop |\n| **Attended (HITL)** (NEW) | Direct-commit (current branch) | Allowed at natural points | TBD: verify-stop or full-cycle? | 使用者就在旁邊、想被諮詢 |\n\n### Open design questions (留給 diagnose)\n\n1. **Flag 設計** — `--hitl` / `--attended` / `--no-pr`？要不要乾脆把預設改成 attended（因為直接從 CLI 喊的用例多半是現場互動），unattended 變成 opt-in via `--unattended`？\n2. **Branch 策略** — Attended 模式還要不要強制 feature branch？還是允許在當前 branch 直接 commit？若使用者已經在 feature branch（例如自己手動切過去），維持當前 branch 是合理的；若在 main，仍然應該建 feature branch（保險）？\n3. **Verify 之後** — Attended 模式既然使用者就在旁邊，要不要直接連 `idd-close` 也跑？還是維持「verify 後停下、由人決定 close」？\n4. **Spectra path interaction** — Attended 模式的 sub-skill suppress hint 整個拿掉？還是仍然保留某些 checkpoint suppress（例如 `spectra-propose` Step 10 Park/Apply）？「都讓 sub-skill 自己決定」是最乾淨的，但要 audit 每個 sub-skill 的 attended 預設是否合理。\n5. **混用情境** — Attended 模式中途使用者可能離開 keyboard，sub-skill 卡在 AskUserQuestion 等不到回應 — 是否需要 timeout fallback？或者明確記錄 attended 模式假設「使用者全程在線」？\n6. **Backward compat** — 現有 `idd-all #N --pr` 的 caller（包含 /loop 自動化）期望 unattended 行為。若預設改成 attended，需要 deprecation 期 + warning。\n7. **與 `idd-implement --no-pr` 的關係** — `idd-implement` 已經透過 `pr_policy` config 支援 PR / direct-commit / ask 三選一。Attended idd-all 是不是直接用 `pr_policy` 而不是新增 flag？這樣 config 介面比較一致。\n\n## Impact\n\n- 新使用者第一次跑 idd-all 會比較直覺（不用先理解「為什麼一定要開 PR」）\n- 解放 sub-skill 的 attended 設計（spectra-discuss 多輪對話、Plan tier EnterPlanMode 等）— 讓 unattended override 變成 opt-in 而不是 default\n- 對 solo repo / personal project 的 friction 大幅降低\n\n## Acceptance criteria（draft，待 diagnose 確認）\n\n- [x] `idd-all --no-pr #N` 走 direct-commit + 允許 sub-skill AskUserQuestion — naming chosen as `--no-pr` (reuse idd-implement vocab); SKILL.md Step 0.2/Phase 0.5; smoke test Case B\n- [x] 既有 `idd-all #N --pr` 行為不變（unattended PR path）— smoke test Cases A + H + F (absent config /loop default); regression reviewer round-1 confirmed byte-equivalent v2.40.0 behavior\n- [x] Documentation 清楚說明兩種模式的契約差異 + 何時用哪個 — SKILL.md frontmatter + 核心原則 + 2 example traces; pr-flow.md \"idd-all path resolution\" section; usecase-routing.md row 11+11b; CLAUDE.md skill summary\n- [x] Sub-skill args 的 unattended hint 機制改成 opt-in（不是 always-on）— Phase 3a/3b/4 conditional `if [ \"$INTERACTION\" = \"unattended\" ]` guards; spectra-apply attended branch SHALL NOT inject any directive (round-2 fix)\n- [x] 新增 / 修改的測試或 dry-run trace 證明兩種模式都按設計走 — `openspec/changes/idd-all-hitl-mode/smoke-test.sh` (28/28 assertions PASS); `smoke-test-trace.txt` captured\n- [x] 至少一個 sample run 在每個模式各跑通一個 issue — smoke test Cases A/H (PR mode) + Case B (direct-commit mode) executes resolution + sub-skill arg construction end-to-end with deterministic assertions\n\n## Related\n\n- 當前 idd-all skill: `plugins/issue-driven-dev/skills/idd-all/SKILL.md` (v2.40.0)\n- Sub-skill 的 attended 預設文件: `plugins/issue-driven-dev/references/pr-flow.md`\n- v2.40.0 release notes: cross-repo `--cwd` 支援（先前 milestone）\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-04 by idd-close\n\n### Key Decisions\n- Closing summary posted: https://github.com/PsychQuant/issue-driven-development/issues/1#issuecomment-4367464627\n- Round-1 verify FAIL → fix → Round-2 verify PASS → smoke test 28/28 PASS — full audit chain\n- 設計重構為**兩軸正交化**（path × interaction 從 `pr_policy` + `--pr/--no-pr` 同源推導），不引入新 `--hitl` flag\n- `pr_policy` 缺省 → `idd-all` 默認 `(PR, unattended)` (v2.40.0 backward compat); 顯式 `pr_policy: ask` 才走 AskUserQuestion — **idd-implement vs idd-all 在缺省時刻意 diverge** (intentional, documented in pr-flow.md)\n- **不**自動 close — `idd-all` 兩 mode 都停在 verified;closing summary 由人寫(本 closing comment 即實踐)\n- HITL mode **不加 silent timeout**;明示「attended assumes user in session」\n- Backward compat: `/loop` 等顯式 `--pr` caller 零受影響;新缺省規則保護無 config 的 caller 不 hang\n\n### Scope Changes\n- direct-commit mode 容許 dirty working tree (verify 標 P2 scope creep) → 已開 #2 follow-up\n- spec.md 加入兩個 backward-compat scenarios (no-flag-no-config, explicit-ask) 對齊 round-2 implementation\n\n### Blocking\n- (none) — 所有 27 spec tasks done;3 P0 + 5 P1 round-1 blockers closed via 5fc39fc;AC #5/#6 closed via smoke test\n- 12 個 P2/P3 follow-up 整合為 9 個 focused issue (#2-#10),全部 ref Related: #1\n\n### Commits\n- `f7230b8` test: idd-all Phase 0.5 smoke test — 28/28 assertions PASS, AC #5/#6 PASSED (Refs #1)\n- `5fc39fc` fix: idd-all HITL mode — close P0/P1 verify FAIL blockers (Refs #1)\n- `98b7a71` feat: idd-all HITL mode — Phase 0.5 (path, interaction) tuple resolution (Refs #1)\n" }, { "number": 12, @@ -19,7 +20,8 @@ "- (none — closed)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Original text** (使用者口述,2026-05-04):\n> 「判斷要走 simple, plan, spectra 的情況下,vagueness 應該是重要的判斷標準,但現在好像沒有」\n> — Source: `/idd-issue` invocation arguments\n\n### 解讀\n\n現行 `idd-diagnose` 的 Complexity 判定(`rules/sdd-integration.md`)用 4 層 gate:\n\n| Layer | 衡量什麼 |\n|-------|---------|\n| **Layer 1**(Simple disqualifier) | 交付物形態(narrative / ad-hoc analysis / 多檔獨立) |\n| **Layer 2**(Spectra necessary) | 是否有 published API/protocol/skill/tool surface |\n| **Layer 3**(Spectra confirmation) | 是否動到 spec normative 行為、跨 2+ specs、架構決策 |\n| **Layer P**(Plan signals) | 檔案互依、5+ ordered steps、decision-heavy diagnosis、risk-sensitive boundary、cross-file refactor |\n\n**全部都在量「改動的形狀」(scope / surface / risk),沒有一條在量「需求本身的清晰度」。**\n\n唯一沾到邊的:\n- Layer P 的 `Decision-heavy with multiple valid approaches` —— 但前提是 **diagnosis 已經列出 2+ 策略**,代表 diagnosis 已經做完且收斂。對「issue body 本身就含糊到 diagnose 都做不下去」的情境沒覆蓋。\n- `Why spectra-discuss is the default for Spectra` rationale 提到「AI 常常高估 diagnosis 完整度」 —— 但這是 **Spectra path 內** 的安全網,不是把 vagueness **拉前到 routing 決策本身**。\n\n## Type\n\nrefactor(改進既有 routing 規則)\n\n## Why vagueness 應該是一階信號\n\nIssue 的 vagueness 跟改動的 scope 是 **正交** 的兩個維度:\n\n```\n Scope: 小 Scope: 大\n ┌─────────────────────────────────┬─────────────────────────────────┐\nVague needs: │ A. 「menu 感覺怪怪的,改一下」 │ B. 「整個 onboarding 流程要重做」 │\n │ 一檔可能就改完,但不知道要改 │ 範圍大,且方向也不清楚 │\n │ 什麼 → 現在會被判 Simple │ → 現在大機率判 Spectra(對) │\n ├─────────────────────────────────┼─────────────────────────────────┤\nClear needs: │ C. 「這行 typo,改 'recieve' → │ D. 「把 5 個 walker 抽出 visitor │\n │ 'receive'」 │ protocol,介面設計如附圖」 │\n │ → Simple(對) │ → 現在判 Plan(對) │\n └─────────────────────────────────┴─────────────────────────────────┘\n```\n\n**問題集中在 quadrant A**:scope 小 + 需求模糊 → 現行邏輯判 Simple → AI 直接進 TDD loop → pattern-match 一個方向就動手 → 改完才發現「不是這個意思」。\n\n這正是 `spectra-discuss` 想防的失敗模式,但 Simple path **完全沒有對應的 alignment gate**。Plan path 的 EnterPlanMode 雖然能擋,但前提是先被路由到 Plan;vagueness 沒進入 routing 信號的話,quadrant A 永遠不會被路到 Plan。\n\n## Expected\n\n`rules/sdd-integration.md` 應該把 **Vagueness Layer** 加進 4 層 gate,作為 routing 決策的一階信號。可能的 shape(待 diagnose):\n\n1. **新增 Layer V (Vagueness signals)** —— 與 Layer P 並列,任一命中就升級到 Plan(或 Spectra,看程度)\n - Issue body 含 hedge 語(「感覺」「好像」「之類的」「順便」「之類」「something like」「somehow」)\n - 缺 expected/actual(bug type)或缺 acceptance criteria(feature type)\n - 含 open question(「該用 X 還是 Y?」「要不要也包含 Z?」)\n - 比較性訴求無基準(「改得好一點」「比較順」「更符合直覺」)\n - 多個並列名詞模糊指涉(「相關的東西」「類似的地方」)\n\n2. **Layer 2 reformulation** —— Spectra 不只看「有沒有 published API」,也看「需求是否需要先對齊才能定 contract」。Vague Spectra-shaped issue → spectra-discuss(本來就是 default,但這次 routing 應該主動點出 vagueness 是觸發因素)\n\n3. **新增 disqualifier 反向**:即使 Layer 1 命中(narrative / ad-hoc),如果 vagueness 同時很高,可能要 escalate 到 Plan 而不是 Simple —— 例如「abstract 重寫,但風格、長度、目標讀者都沒講」應該先 Plan-mode 對齊再寫。\n\n## Actual\n\n目前的 4 層 gate 完全沒有 vagueness 軸。所以:\n\n- Quadrant A(small + vague)→ 一律 Simple → AI 直接動手 → 高機率改錯方向\n- 即使 issue body 含「感覺怪怪的」「之類的」「再順便處理 X」這種 obvious hedge,也不會升級\n- 唯一補救是 user 主動指定 `--complexity Plan` 或寫超詳細的 issue —— 但這就是把責任推給 user\n\n## Impact\n\n- **失敗模式**:Quadrant A issue 走 Simple path → AI 改完 → user「這不是我要的」→ revert/重做 → 多一輪\n- **頻率**:高。日常很多 ad-hoc 改善請求(「這個 UI 有點怪」「reports 看起來不太對」)都落在 quadrant A\n- **目前的 workaround**:user 自己升級到 Plan,或在 issue body 一開始就寫死 acceptance criteria —— 但 IDD 的 promise 是 routing 由 skill 判定,不是讓 user 預先 self-route\n\n## 關聯設計線索\n\n- `rules/sdd-integration.md` \"Why spectra-discuss is the default for Spectra\" —— 已承認 vagueness 存在,但只在 Spectra 內部處理\n- `idd-diagnose` Step 3.5 是判定點,新增 Layer V 應該在這裡\n- `MANIFESTO.md` 5-axis bug-fix model —— 可能要新增「alignment axis」對應 vagueness\n- 與 `linked-context sister sweep`(IC_R011)正交:那個是「漏抓 sibling」,這個是「主軸本身就模糊」\n\n## Next Step\n\n`/issue-driven-dev:idd-diagnose #NNN`(實際 issue # 由建立後填入)\n\n### Linked-Context Siblings Filed (v2.48.0+ #529)\n\n(none — no orphan sibling mentions in linked context)\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-04 by idd-close\n\n### Key Decisions\n- Verdict = **Spectra** → spectra-discuss → propose → apply → archive 完整 lifecycle\n- Approach C 選定 (Step 3.4 in idd-diagnose,不新增獨立 skill,維持 6-skill plugin surface)\n- Heuristic = AI Likert 6-point per-axis (V1, V4),trigger threshold per-axis ≥ 4 — 不用 keyword matching\n- Hybrid 3-option (clarify / proceed / escalate) default 隨 max score 變\n- Meta-rule `屬性評分用 Likert,不用 keyword` 抽到 `.claude/rules/attribute-assessment.md`,session-wide via `@import`\n- 5-axis bug-fix model → 6-axis (新增 Alignment quality,evidence = Layer V)\n\n### Scope Changes\n- 比原 issue 描述新增:meta-rule 抽出獨立檔(超越 vagueness 適用範圍);MANIFESTO 6-axis 擴充\n\n### Blocking\n- (none — closed)\n\n### Commits\n- `b2899e6` feat: Layer V Vagueness Pre-check for complexity routing (#12)\n\n### Spectra Change\n- `add-vagueness-layer-routing` archived to `openspec/changes/archive/2026-05-04-add-vagueness-layer-routing/`\n- Main spec at `openspec/specs/routing-vagueness-layer/spec.md` (9 normative requirements)\n" }, { "number": 13, @@ -28,7 +30,8 @@ "- 等 re-verify 確認 13 fixes 全 effective,verdict PASS" ], "expect_empty": false, - "expect_first_blocker": "- 等 re-verify 確認 13 fixes 全 effective,verdict PASS" + "expect_first_blocker": "- 等 re-verify 確認 13 fixes 全 effective,verdict PASS", + "body": "## Problem\n\n> **Original text** (使用者口述,2026-05-04):\n> 「idd-list 應該顯示引用 issue 的 open PR 資訊 — 目前只列 issue phase / next action,看不到對應的 open PR(尤其重要:cluster-PR mode 多個 issue 共用一個 PR 時更看不出來)」\n> — Source: `/idd-issue` invocation arguments\n\n### 解讀\n\n`idd-list` 目前列 issue 的 phase(created / diagnosed / implemented / verified / needs-fix / closed)+ next action(下一個應跑的 idd-* skill),但**完全沒提**該 issue 對應的 open PR 狀態。\n\n特別痛點:**cluster-PR mode**(`idd-implement #34 #36 #38` 等 multi-issue 共用 1 feature branch + 1 PR 的場景)從 issue list 看不出來「這 3 個 issue 是 bundle 在 PR #N 等 merge」 — 每個 issue 各自看像「卡在 implemented」,但實際是 PR 路徑。\n\n## Type\n\nfeature(idd-list 新增資訊欄位 / 新區段)\n\n## Expected\n\n`idd-list` 輸出對每個 issue 額外顯示:\n\n- **Open PRs ref'ing this issue**:列 PR number + title + draft/ready status + mergeable state\n- **Cluster-PR detection**:若多個 issue 共用同一 PR(從 PR body 的 `Refs #N1 #N2 #N3` 偵測),group 顯示而非每個 issue 重複列\n\n可能的呈現方式(待 diagnose):\n\n```\n#42 [implemented] feat: ...\n └─ PR #99 (ready, mergeable) — bundles #42 #43 #44\n Next: gh pr review 99 → idd-close #42 #43 #44\n\n#43 [implemented] feat: ...\n └─ → see PR #99 above (cluster)\n\n#43 [implemented] feat: ... ← single-issue PR\n └─ PR #100 (draft, mergeable) — solo\n Next: mark ready → review → idd-close #43\n\n#44 [verified] fix: ... ← direct-commit path,無 PR\n Next: idd-close #44\n```\n\n## Actual\n\n目前 `idd-list` 只顯示 phase + next action。看不到 PR 資訊就有以下盲點:\n\n- Cluster-PR 是哪個 issue 是「bundle leader」、哪些是同 PR 的 sibling — 看不出來\n- Issue phase = `implemented` 但 PR 還在 draft — 看不出來「在等 mark ready」\n- Issue phase = `implemented` 但 PR 已 merged — 看不出來「應該回去 close 了」(idd-close 會偵測 unmerged PR refuse,但 list 階段就該提示)\n- PR mergeable=CONFLICTING — 看不出來「需要先解 conflict 才能繼續」\n\n要查 PR 狀態目前要另跑 `gh pr list --search \"#$N\"` 對每個 issue 一次,沒整合進日常 workflow。\n\n## Impact\n\n- **影響流程**:user 用 `/idd-list` 是想拿到「all open issues 的 actionable next step」,缺 PR info 等於少一半 next step 資訊\n- **頻率**:高。`idd-list` 是日常 entry skill,每次想知道「目前在做什麼、卡哪裡」都會跑\n- **特別嚴重情境**:cluster-PR(7 issues → 2 themed PRs 那種 workflow)幾乎完全失明 — `idd-list` 看不出 cluster 結構\n- **目前 workaround**:`gh pr list --search \"in:body \\\"#${N}\\\"\"` per issue,7 個 issue = 7 個 query,慢且不集成\n\n## 設計線索\n\n- `idd-list` 既有的 phase detection 已經會掃 comments,加 PR query 不增加 N+1 問題:可以 batch `gh pr list --json number,body,title,isDraft,mergeable,refs` 一次抓所有 open PR,client 端 cross-reference issue numbers\n- PR body 提取 issue refs 的 regex 已在 `references/external-agent-delegation.md`(`gh pr view --json body | grep -oE 'Refs? #[0-9]+'`)有先例\n- Cluster grouping 顯示策略需設計(每個 issue 重複列 PR 資訊 vs leader/sibling 區分)\n- 直接 commit path(無 PR)的 issue 不該有 PR 區段(空白/省略)\n\n## 關聯\n\n- Cluster-PR mode contract: `references/batch-and-cluster.md`\n- PR path contract: `references/pr-flow.md`\n- External-agent PR detection: `references/external-agent-delegation.md`(同 query 邏輯可重用)\n\n## Next Step\n\n`/issue-driven-dev:idd-diagnose #NNN`(實際 issue # 由建立後填入)\n\n### Linked-Context Siblings Filed (v2.48.0+ #529)\n\n(none — no orphan sibling mentions in linked context)\n---\n\n## Current Status\n\n**Phase**: implemented\n**Last updated**: 2026-05-05 by idd-implement (round 2 fixes)\n\n### Key Decisions\n- Round 2 fix:7 blocking (P1+HIGH) + 6 in-scope MEDIUM/LOW/P3 全修,單檔 idd-list/SKILL.md +77 -38\n- Cluster member dangling-leader fallback (DA-3) 加 surrogate-leader display 機制\n- Footer trigger 條件明綁 `len(issue_to_prs) > 0`(per DA-2)\n- Step 5 matrix 擴充覆蓋 UNKNOWN state + verified+draft + needs-fix expansion(per Logic P1)\n- Step 0 TaskCreate description 對齊 Step 3.5 spec(per DA-1 v2.18.0+ 鐵律)\n- Regex 從 `#(\\d+)\\b` 強化到 `#(\\d{1,7})\\b` + filter #0(per DA-7+L8)\n\n### Scope Changes\n- (none — round 2 完全在 idd-list/SKILL.md 內)\n\n### Blocking\n- 等 re-verify 確認 13 fixes 全 effective,verdict PASS\n\n### Sister Issues / Follow-ups\n- #14 markdown-aware PR body parser (R1, P3, original)\n- #15 cluster_leader config (R3, P3, original)\n- #16 needs-fix matrix expansion (DA-4, partially addressed inline)\n- #17 planning stale PR detection (DA-5, partially addressed inline)\n- #18 manual smoke test scenarios 2-5 (DA-6)\n- #19 regex digit cap + #0 filter (DA-7+L8, partially addressed inline)\n- #20 footer direct-commit count (Logic P3#10, addressed inline)\n\n### Commits\n- `1c60c1c` feat(idd-list): show open PRs ref'ing each issue + cluster detection (#13)\n- `2564d6f` fix(idd-list): 7 blocking + 6 in-scope verify findings (#13)\n" }, { "number": 26, @@ -37,7 +40,8 @@ "- (none — closed)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Original text** (user chat, /idd-issue, 2026-05-07):\n> 「我覺得 readme 上要寫說仰賴哪些 plugin 吧？」\n\n兩份 README 都沒列出 `issue-driven-dev` 實際用到的外部 plugin / MCP server,使用者裝完只看 README 不會知道哪些來源類型(`.docx` / Telegram / Apple Mail / Apple Notes)需要額外裝什麼才會 work。\n\n`grep` 確認 `idd-issue` skill 直接呼叫以下 MCP tools:\n\n| MCP Plugin | 用途 | 觸發時機 |\n|------------|------|---------|\n| `che-word-mcp` | 讀 `.docx` 文字 + 抽圖 (`get_document_text` / `list_images` / `export_image`) | source 是 `.docx` / `.doc` |\n| `che-telegram-mcp` (`telegram-all`) | 讀 chat history (`get_chat_history`) | source 是 Telegram chat range |\n| `che-apple-mail-mcp` (`mail`) | 讀 email + attachments (`get_email`) | source 是 Apple Mail message |\n| `che-apple-notes-mcp` (`notes`) | 讀 note + 抽圖 (`get_note`) | source 是 Apple Notes |\n\n頂層 README 也已列出 `idd-route` 為 sister plugin (coming soon),但沒說明它跟 `issue-driven-dev` 的依賴關係(它需要 `idd-route-swift` binary,且是被 `issue-driven-dev` 內部選擇性使用)。\n\n## Type\n\ndocumentation\n\n## Expected\n\n兩份 README 應該各有一段 \"Dependencies\" / \"Optional integrations\" / \"Source-type adapters\" 章節,清楚說明:\n\n1. **核心使用零依賴** — 純 chat / 直接貼文字 / `.md` 來源不需要任何外部 plugin\n2. **依來源類型可選裝**(matrix 表格,key 在「為什麼裝這個」+「不裝會發生什麼事」):\n - `.docx` / `.doc` → `che-word-mcp`\n - Telegram → `che-telegram-mcp` (telegram-all server)\n - Apple Mail → `che-apple-mail-mcp`\n - Apple Notes → `che-apple-notes-mcp`\n3. **Sister plugins**(`idd-route`)說明它是 enrichment,非必要\n\n## Actual\n\n- 頂層 `README.md`:只寫 install 指令 + migration,沒提任何 dependency\n- `plugins/issue-driven-dev/README.md`(line 158 提到 `idd-route` install,但散落在內文,沒有統一 dependencies 章節)\n\n## Impact\n\n- **Onboarding 卡點**:新使用者拿 `.docx` 餵 `/idd-issue` 失敗(`mcp__che-word-mcp__get_document_text` 不存在),不知道要裝什麼\n- **Discoverability**:不知道 IDD 設計上支援多種 source type,以為只能貼純文字\n- **預設無聲降級**:Source-type adapter Step 1 在 MCP 不存在時不會明確報錯,只會 fallback 到請使用者手動處理,使用者誤以為「IDD 不支援這格式」\n\n## Suggested fix (non-blocking)\n\n兩份 README 加 \"Plugin dependencies\" / \"Source-type adapters\" 章節,用 matrix 呈現 + 註明 install 指令(`claude plugin install @`)。\n\n## Scope (per /idd-issue clarification)\n\n- [ ] 頂層 `README.md`\n- [ ] `plugins/issue-driven-dev/README.md`\n\nPriority: **P2**\n\n### Linked-Context Siblings Filed (v2.48.0+ #529)\n\nFiled sibling issues: #27 (idd-issue Step 1 silent-degrade UX bug)\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-07 by idd-close (auto via idd-update)\n\n### Key Decisions\n- 用既有 `plugins/issue-driven-dev/README.md ## Requirements` 為 landing spot,重組為 Required / Optional / Sister 三節 (Strategy A, commit `78dbc15`)\n- 頂層 README 加簡短 `## Requirements` 指向 plugin README (Strategy B, commit `be4931b`)\n- 加 KEEP IN SYNC HTML comment 防 source type adapter ↔ README matrix drift (Strategy C, commit `6997e3f`)\n- 替 #28 預留 `### Required for specific modes` 插入空間,但不直接寫 ralph-loop row (avoid scope creep)\n- Complexity = Simple (Layer 1)\n- Vagueness Pre-check: V1=1, V4=2 (not triggered)\n- PR #30 squash-merged → main (`0e9bb99`)\n\n### Scope Changes\n- (none)\n\n### Blocking\n- (none — closed)\n\n### Commits (squashed via PR #30)\n- `78dbc15` docs: 擴充 plugin README `## Requirements` (Required + Optional + Sister)\n- `be4931b` docs: 頂層 README 加 `## Requirements` summary + link to plugin README\n- `6997e3f` docs: 加 KEEP IN SYNC comment 防 source type adapter ↔ README matrix drift\n- `0e9bb99` docs: README 列出 issue-driven-dev 仰賴的外部 plugin / MCP server (#30) — squash on main\n\n### PR\n- #30 (merged)\n\n### Sister Concerns\n- Diagnose: skipped (1: SKILL/README sync — covered as Strategy mitigation)\n- Implement: filed #31 (marketplace placeholder UX), #32 (refine #27 fail-fast format)\n- Close: (none — no orphan mentions)\n\n### Follow-ups\n- #28 (ralph-loop dependency, blocked by this issue, now unblocked)\n- #27 (source-type adapter fail-fast)\n- #29 (upstream Claude Code schema gap)\n- #31, #32 (sisters from implement)\n" }, { "number": 37, @@ -49,7 +53,8 @@ " (3) 自動化 caller 卡 Phase 6 產生既有 `/idd-all #a #b #c` 無法解決的實際痛點" ], "expect_empty": false, - "expect_first_blocker": "- 等 re-park trigger 之一成立（見 2026-08-10 decision comment「Re-park 的 trigger 條件」）：" + "expect_first_blocker": "- 等 re-park trigger 之一成立（見 2026-08-10 decision comment「Re-park 的 trigger 條件」）：", + "body": "## Problem\n\n> **Original text** (user chat, /idd-issue, 2026-05-07):\n> 「用idd方法照妳覺得的順序跟bundle把所有的issue都解完 我嘗試這個還不錯，我在想如果我用「/idd-all」什麼都不指定的話就是用這樣的功能」\n\n使用者觀察到「逐一手動跑 /idd-all #N」雖可行但繁瑣,提議讓 `/idd-all` (無參數) 變成 **bulk-solve mode** — AI 自行排序所有 open issue,以 bundle 紀律一口氣跑完整 IDD pipeline。\n\n## Type\n\nfeature (orchestrator extension)\n\n## Expected\n\n`/idd-all` (無 arg + 不在 interactive mode) 觸發新 `bulk-solve mode`:\n\n1. **Preflight**: `gh issue list --state open` 抓全部 open issues\n2. **Triage**: 每個 issue 判斷 actionable 程度:\n - actionable (有 diagnose / 有 strategy) → 進 bundle\n - tracking-only / wontfix → 提示使用者考慮 close\n - blocked-by 其他 open issue → 排在依賴後\n3. **AI sequencing**: 依 (a) blocking deps (b) complexity (Simple → Plan → Spectra) (c) shared file overlap (cluster-PR friendly grouping) 自動排序\n4. **AskUserQuestion confirmation**: 列出 proposed sequence + bundle plan,使用者 approve/edit/abort 才開始\n5. **Sequential execution**: 對每個 issue / cluster 跑 idd-all (PR, unattended) 或 cluster-PR mode\n6. **Mid-batch checkpoints**: 每 N issue 跑完 stop + 印 progress;遇到 verify FAIL 自動 abort 不繼續(避免雪崩)\n7. **Final aggregate report**: 列出 N succeeded / M failed / K skipped,各自 PR / commits / verify summary\n\n## Actual\n\n- 目前 `/idd-all` (無 arg) → interactive mode,問 from-scratch vs from-issue\n- 沒有 bulk 模式:使用者要逐一打 `/idd-all #N` × N 次\n- 沒有 AI 自動 sequencing,使用者要自己判斷依賴順序\n\n## Impact\n\n- **Onboarding 卡點**:新使用者面對 14 個 open issue 不知從哪開始\n- **手動 sequencing 易錯**:漏掉依賴(本 session 已踩過 #28 blocked by #26 但沒抓到 → idd-all #31 abort)\n- **Cluster-PR 機會浪費**:多個 issue 改同檔案,本可一個 PR 解決,但手動模式逐一開 PR 變 N 個 PR\n\n## Design considerations\n\n- **Safety gate**:bulk mode 必須 PR mode + unattended,**禁止** direct-commit(風險太大)\n- **Concurrency**:不平行(避免 6-AI verify 互相干擾),嚴格 sequential\n- **Failure mode**:任一 issue verify FAIL → halt batch,印剩餘 unprocessed list 給使用者\n- **Triage transparency**:每個 issue 為什麼放進這個位置(reason),寫進 final report\n- **Out-of-scope**:`/idd-all` (無 arg) 仍保留 interactive fallback(若使用者明確選 \"create new issue\"),不取代 — 加新 sub-mode\n\n## Related\n\n- #28 (本 session 走 PR-tier full pipeline, 證明 Plan tier 路徑能跑)\n- #11 (umbrella split flow — 同類紀律,issue 拆分後也需要 sequential 處理)\n- 既有 cluster-PR mode (`#34 #36 #38`) 是手動 batch — 本 issue 的 bulk-solve 是 bigger automation\n\nPriority: **P2** (DX 改善 — 可顯著減少 multi-issue session 的手動操作)\n\n\n\n---\n\n## Current Status\n\n**Phase**: diagnosed — **re-parked 2026-08-10**\n**Last updated**: 2026-08-10 by /spectra-discuss（decision comment 見下方）\n\n### Complexity\n\nSpectra when triggered (parking lot) — 見下方 re-park trigger\n\n### Blocking\n\n- 等 re-park trigger 之一成立（見 2026-08-10 decision comment「Re-park 的 trigger 條件」）：\n (1) #298 落地後 triage 準確率可接受 /\n (2) 出現 actionable-Simple-tier 子集 ≥3 的 backlog /\n (3) 自動化 caller 卡 Phase 6 產生既有 `/idd-all #a #b #c` 無法解決的實際痛點\n\n### Next\n\n**無 lifecycle 動作** — parked。carve-out 的 triage 訊號在 #298。\n\n### History\n\n- 2026-05-07 — filed via `/idd-issue`；parked-closed same session（evidence deferred，3 reopen criteria set）\n- 2026-05-19 — reopened（2/3 reopen criteria met：28-issue stable backlog + repeated user feedback）\n- 2026-05-19 — diagnosed (Spectra)，hard dependency on #102\n- 2026-07-?? — #102 closed，doctrine `verify-gated` + `--review` ship，auto-merge mechanic 正式交棒本 issue\n- **2026-08-10 — `/spectra-discuss` 執行 → re-scope：triage 訊號 carve out 至 #298，autopilot 本體 re-parked**\n" }, { "number": 44, @@ -58,7 +63,8 @@ "- (none — closed via /idd-close 2026-05-10 with retroactive Implementation Complete supersession)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "> **Errata** (2026-05-10, post-discuss/propose/apply):\n> 此 issue 的 `## Expected` 段所述 `/idd-all #N --chain` flag + `chain_policy: off/auto/ask` config schema 在 `/spectra:discuss` 階段被 reject(過 default-dilemma checklist 全 yes;詳見 `docs/design-patterns/default-dilemma.md`)。\n> **最終實作**為獨立 `/idd-all-chain` skill + `--in-chain` flag(`/idd-all` 加 4th mode tuple `(direct-commit, unattended)`)。請以 `openspec/changes/add-idd-all-chain-skill/` 的 `proposal.md` + `design.md` 為準。\n> Spectra change 進度:25/32 tasks done(spawn manifest infra ✓ / 4 sub-skill conformance ✓ / `idd-all --in-chain` flag ✓ / `idd-all-chain/SKILL.md` ✓ / plugin metadata ✓);6.3 e2e validation deferred 到 first-real-use,7.x 本 comment 即是其中一項。\n\n---\n\n## Problem\n\n> **Original text** (user chat, /idd-issue, 2026-05-08):\n> 「我現在在想 /idd-all 這個技能,他是不是可以有一個做法是自動繼續把衍生的 issue 都一併解完,然後最後用整個 PR 來 review」\n\n當前 `/idd-all #N` 跑單 issue lifecycle (issue → diagnose → implement → verify),verify / sister sweep / mid-plan tangential 觸發到的 follow-up issue 會被 file 為新 issue **但 idd-all 不會繼續解**。使用者必須手動再跑 `/idd-all #M` 處理每個衍生 issue,且各自開獨立 PR。\n\nUser 提議:**chain-solve mode** — 跑 `/idd-all #N` 衍生出 #M / #K 時,自動接著解,**全部 commit 到同一 feature branch + 同一 PR**,最後 user 對整顆改動樹做 1 次 review/merge/close。\n\n跟現有 mechanism 比較:\n\n| 機制 | 觸發 | Issue 範圍 | PR | 跨 issue |\n|------|------|-----------|-----|---------|\n| 既有 `/idd-all #N` | 單 issue | 1 issue lifecycle | 1 PR | 衍生 → 新 issue,user 手動接 |\n| Cluster-PR (`/idd-implement #N #M --pr`) | User 預先指定多 issue | N pre-known issues | 1 PR | User 預先決定 cluster |\n| #37 bulk-solve (parked) | 無 args 從 backlog 掃所有 open | 所有 open issues | N PRs (per issue) | Cold-start,無依賴推導 |\n| **本 issue: chain-solve** | 跑 #N **過程中** spawn 出來的 #M | hot-chain (1 → N+) | **1 PR** for 全鏈 | Auto-emergent,跟 spawning 同步 |\n\n## Type\n\nfeature (orchestrator extension) — `/idd-all` 新模式\n\n## Expected\n\n新增 `/idd-all #N --chain` flag(or default-on if `chain_policy: auto` in config):\n\n### Behavior\n\n1. **Phase 1-4 跟現有相同**:跑 #N 完整 lifecycle 到 verified\n2. **Phase 4.5 NEW — chain detection**:\n - 掃本 invocation 衍生的 follow-up issues:\n - idd-implement Step 5.7 sister bug sweep filed\n - idd-verify Phase 4 P3 follow-up findings filed\n - idd-plan Step 2.5 tangential observations filed\n - idd-diagnose Step 3.6 sister concerns filed\n - 排除 issue:**已在另一個 branch / 已 closed / out-of-repo**\n3. **Phase 4.6 NEW — recursive chain-solve loop**:\n - 對每個 spawned issue:\n - 在**同一 feature branch** 上跑 mini-pipeline (diagnose → implement → verify)\n - Commit 用 `Refs #M` (cluster-PR commit convention)\n - Verify findings 若再 spawn → continue chain (depth limit 預設 2,可 config)\n - 每個 chained issue 各自 idd-update phase → verified\n4. **Phase 5 NEW — single review PR**:\n - PR body 列出 root #N + chained #M, #K, ... 全部\n - Title prefix `chain:` (跟 `cluster:` 區別)\n - 每個 issue 各自 verify report (inline links to PR comments)\n5. **Phase 6 — stop at verified, user reviews 整顆 PR**:\n - User merge 後跑 `/idd-close #N #M #K` 一次關全部(各自 closing summary,每個 issue 一份)\n\n### Config schema (proposed)\n\n```json\n{\n \"chain_policy\": \"off\" | \"auto\" | \"ask\",\n \"chain_max_depth\": 2,\n \"chain_max_issues\": 5\n}\n```\n\n- `off` (default for v1) — 跟現有行為一致,不 chain\n- `auto` — 衍生 follow-up 自動 chain solve\n- `ask` — 衍生時用 AskUserQuestion 問是否 chain\n\n## Actual\n\n- `/idd-all #N` 衍生 follow-up 後就停下,user 看到「filed #M, #K」report 然後手動 `/idd-all #M`\n- 每個 spawned issue 各自開 PR,造成 **PR 碎片化**:本 session 有 PR #30 (#26) → 衍生 PR #33 (#31) → 衍生 PR #36 (#28) → 衍生 PR #39 (#27+#34) → 衍生 PR #42 (#41) — 都是同一個 source-type fail-fast 主題,但因為 IDD discipline 切成 5 個 PR,review effort × 5\n\n## Impact\n\n- **Review fragmentation**:相關改動分散多 PR,reviewer 失去 holistic view\n- **Atomicity loss**:multi-issue refactor 應該 atomic,split 成 N PR 增加 partial-merge 風險\n- **Manual orchestration burden**:user 要記得追蹤所有 spawned issue,handover 期間易遺漏\n- **Audit trail dilution**:close summary 各自寫,無法看「整個改動樹解了什麼問題」\n\n## Design considerations / open questions\n\n1. **Depth limit**:衍生 → 又衍生 → 雪崩風險。Default `chain_max_depth=2` 合理嗎?\n2. **Verify discipline preserved**:每個 chained issue 仍跑 idd-verify (or 共用 PR 末端 verify)?後者省 cost 但失 per-issue verify rigor\n3. **PR body 結構**:N issues 的 PR body 怎麼組織才不會變成超長 wall of text?\n4. **Failure mode**:中途某 chained issue verify FAIL,整顆 chain abort 還是 partial commit?per-issue verify 模式下,FAIL 應只 abort 該 issue 不影響其他\n5. **Close orchestration**:`/idd-close #N #M #K` 已支援 cluster-PR mode,chain mode 會直接 reuse 這個還是新 mode?\n6. **Edge case — chain 跨 branch 不可**:衍生 issue 若觸及完全不相關 file (e.g. #28 衍生 #34 doc + #41 trust docs vs. 另一個 #50 unrelated bug fix),user 心中可能不想 cluster — 需要 heuristic 或 prompt\n7. **Cross-cutting refactor 才適合 chain**:同一 helper / 同一 module 的多 issue → chain;independent fixes → 分 PR 還是對的\n\n## 與 #37 (parked bulk-solve) 的差異\n\n| 特性 | #37 bulk-solve | This (chain-solve) |\n|------|---------------|-------------------|\n| Trigger | `/idd-all` 無 args (cold start) | `/idd-all #N` 衍生時 (hot chain) |\n| Issue source | 既存 backlog | This invocation spawned |\n| Sequencing | AI 自動排序所有 backlog | 自然 emergence (DFS) |\n| PR | N PRs per cluster | 1 PR for 整鏈 |\n| Use case | \"Inbox zero session\" | \"解決 1 root issue 連帶 ripple\" |\n\n兩者 orthogonal,可獨立或組合(chain-solve mode 嵌入 bulk-solve 的每個 cluster 內)。\n\n## Real example from this session\n\n- Root: #28 (ralph-loop dependency)\n- Spawned during round-2 verify: #29 (upstream tracking), #34 (helper refactor), #35 (path watch), #40 (degrade regression), #41 (trust model docs)\n- Actual flow: split into PR #36 (#28) → PR #39 (#27+#34) → PR #42 (#41) → PR #43 (#14+#15) — 4 PRs across multiple sessions\n- **With chain-solve**: 可能 1 個 PR 含 #28 + #34 + #41,以及這個 PR 自己再 spawn 出 #14/#15 cluster-PR (depth 2 stop)\n\n## Related\n\n- #37 (parked bulk-solve mode — orthogonal feature)\n- #11 (umbrella split SOP — spawning 紀律的相關 process)\n\nPriority: **P2** (DX 大改善,但需要謹慎設計避免 chain 雪崩 / verify discipline regression)\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-10 by idd-close (Spectra change archived + retroactive Implementation Complete + Closing Summary posted)\n\n### Key Decisions\n- Complexity = **Spectra** (Layer 2 + Layer 3 全 3 個都命中)\n - Layer 2: 跨 sub-skill implicit contract(spawn manifest schema)\n - Layer 3a: 修 5 個既有 spec(idd-all + 4 sub-skills)\n - Layer 3b: 跨 reference doc cross-spec impact\n - Layer 3c: Architectural shift(single-issue → emergent multi-issue lifecycle)\n- **Implementation 路線**:`--chain` flag 路線 reject;改成獨立 `/idd-all-chain` skill + `--in-chain` flag(過 default-dilemma checklist)\n- Strategy: 7 phases — spawn manifest infra → 4 sub-skill conformance → `idd-all --in-chain` flag → `/idd-all-chain` skill → plugin metadata → verification → GitHub alignment\n- Vagueness Pre-check: V1=2, V4=3 (not triggered)\n\n### Scope Changes\n- 2026-05-08:`--chain` flag 路線 reject(discuss),改採獨立 `/idd-all-chain` skill\n- 2026-05-10:Spectra change `add-idd-all-chain-skill` 合併 ingest #44 issue body context;tasks.md 加 group 7 對齊 GitHub-side tracker\n\n### Tasks (Spectra change `add-idd-all-chain-skill`)\n- [x] 1.x Spawn manifest infra (3/3)\n- [x] 2.x Sub-skill manifest write conformance (5/5)\n- [x] 3.x `idd-all --in-chain` flag (5/5)\n- [x] 4.x `/idd-all-chain` skill creation (8/8 — 含 chain-flow.md reference)\n- [x] 5.x Plugin metadata (4/4 — CLAUDE.md / plugin.json / marketplace.json / usecase-routing.md)\n- [x] 6.1, 6.2, 6.4 verification 通過(structural + smoke);6.3 e2e deferred to first-real-use\n- [x] 7.x GitHub Issue #44 alignment(本 update + errata + link comment)\n\n### Blocking\n- (none — closed via /idd-close 2026-05-10 with retroactive Implementation Complete supersession)\n\n### Sister Concerns\n- Skipped (1: spawn manifest as internal Phase 1, kept inside #44)\n\n" }, { "number": 45, @@ -67,7 +73,8 @@ "- 等 user 確認 diagnosis 後跑 `/idd-plan #45` 進 EnterPlanMode approval gate" ], "expect_empty": false, - "expect_first_blocker": "- 等 user 確認 diagnosis 後跑 `/idd-plan #45` 進 EnterPlanMode approval gate" + "expect_first_blocker": "- 等 user 確認 diagnosis 後跑 `/idd-plan #45` 進 EnterPlanMode approval gate", + "body": "## Problem\n\n`/idd-close` 是 IDD lifecycle 的終點:寫 closing summary + close issue + auto-update phase=closed。但對於 **distributed-via-plugin / MCP / CLI binary** 的 issue,closing 後仍有最後一哩 — 把 fix 同步到 user-facing distribution channel(plugin marketplace / MCP wrapper / CLI release)。\n\n目前流程:\n\n```\n/idd-close #N ← end of lifecycle from IDD's POV\n ↓ (gap — user 容易忘)\n/plugin-update X ← 才讓使用者實際拿到新版\n```\n\n如果忘了第二步,fix 已合進 main 但 marketplace 仍指向舊版 → 使用者跑 `/plugin update` 拉不到新東西,看似「修了卻沒修」。歷史上已經多次踩過這坑(Global rule `common-release-flow.md` 就是為了這個 mandate marketplace-sync,但 trigger 是「release 後」,不是「issue close 後」 — 兩者不總一致)。\n\n## Type\nfeature\n\n## Expected\n\n`/idd-close #N` 在 close 成功後(Step 6 auto-update 之後、Step 7 final report 之前),做 distribution-aware chain detection:\n\n1. **Detect** issue + repo 是不是 distributed via:\n - Claude Code plugin marketplace (`.claude-plugin/marketplace.json` 含此 repo)\n - MCP binary (repo 有 `bin/*-wrapper.sh` 引用 GitHub Release)\n - CLI binary (相似 wrapper / `~/bin` reference)\n\n2. **AskUserQuestion 3-option**(per IC_R011 canonical pattern):\n - `chain to plugin-update / mcp-update / cli-update now` — 直接 invoke 對應 skill\n - `skip — I'll sync manually later` — 不 chain,但**寫進 closing comment audit trail**(`### Distribution Sync Pending`)讓三個月後考古能找到 dropped step\n - `not applicable — this issue doesn't ship` — confirm + 不再問(內部 refactor、docs、test 等)\n\n3. **Audit trail**(任一選擇都寫):\n - PATCH closing comment append `### Distribution Sync` section\n - \"chained\" → record skill + outcome\n - \"skip\" → record reason + provide command for later use\n - \"n/a\" → record + close\n\n## Actual\n\n目前 `/idd-close` 結束就是結束。Distribution sync **完全靠使用者記得**,沒有任何 mechanical checkpoint。\n\n歷史踩坑(從 `che-claude-config/rules/common-release-flow.md` 摘):\n\n> 跳過這步驟讓 `marketplace.json` 過時。使用者跑 `/plugin update` 看到舊版本,拿不到新 binary — 即使 GitHub release 存在。**Release 只有半成 unless marketplace sync lands**.\n\n但 `common-release-flow.md` 是 release-side trigger,假設 release 跟 issue close 順序一致。實務上很多 issue 是 fix-via-PR,merge 後 close issue 但還沒 cut release;或者 cut release 後忘了 close issue。**`idd-close` 是更早 + 更可靠的 chain anchor**(因為 close 是 lifecycle 必經點)。\n\n## Impact\n\n### 影響的工作流\n- 任何 `idd-close` 收尾的 issue,若 repo 是 plugin / MCP / CLI distribution\n- 對純內部 refactor / docs / spec 改動 → 不影響(Step 1 detection 過濾掉)\n\n### 影響的檔案(實作面)\n- `Sources/.../skills/idd-close/SKILL.md` — 加 Step 6.5 (Distribution Sync chain)\n- 可能新增 `references/distribution-detection.md` — detect 邏輯抽出來給其他 skill reuse(`idd-implement` 在 implement 完成時也該有類似 prompt?)\n\n### 跨 skill 影響\n- `plugin-tools/skills/plugin-update` — 改成可以接收 `--source-issue #N` flag,把 issue ref 寫進 commit message\n- `mcp-tools/skills/mcp-deploy` — 同上\n- `cli-tools/skills/cli-deploy` — 同上(若存在)\n\n## 推測 detection 邏輯\n\n```bash\n# Heuristic: this repo is distributed if any of:\nis_plugin_marketplace_member() {\n # Walk-up parent dirs for .claude-plugin/marketplace.json that lists this repo\n # Or check if cwd is direct subdir of a known marketplace repo\n ...\n}\n\nhas_binary_wrapper() {\n # Look for bin/*.sh that curls from GitHub Release\n ls \"$REPO_ROOT/bin\" 2>/dev/null | xargs grep -l \"gh release download\\|curl.*github.com.*releases\" 2>/dev/null\n}\n\nDISTRIBUTION_TYPE=\"\"\nif is_plugin_marketplace_member \"$REPO\"; then DISTRIBUTION_TYPE=\"plugin\"; fi\nif has_binary_wrapper \"$REPO_ROOT\"; then DISTRIBUTION_TYPE=\"${DISTRIBUTION_TYPE:+$DISTRIBUTION_TYPE+}mcp_or_cli\"; fi\n```\n\nFalse-positive case:repo 在 marketplace 但本次 issue 沒影響 user-facing surface(內部 test infra fix)— 由 `not applicable` option cover。\n\n## 推測 Step 6.5 placement\n\n```\nStep 4: gh issue close ✓\nStep 5: report\nStep 6: auto-update body phase=closed ✓\nStep 6.5: ★ NEW — Distribution Sync detection + AskUserQuestion + chain\nStep 7: batch close special rules\n```\n\n放在 phase=closed 之後是因為:closing summary 是 audit trail,distribution sync 是 follow-up action。Phase 應該在 audit 完成那刻就 lock,不該 hold 著等 sync 才 close。\n\n## Acceptance criteria\n\n- [ ] `/idd-close #N` 對 plugin/MCP/CLI repo 觸發 detection + AskUserQuestion\n- [ ] 三選項都有對應 audit trail entry 寫進 closing comment\n- [ ] 對純內部 refactor / docs issue → silent skip(detection returns \"n/a\")\n- [ ] Backward compat:既有 `idd-close` 用法不受影響(detection 找不到 distribution type 就 silent)\n- [ ] 寫入 `references/distribution-detection.md`(若抽 helper)+ test fixture\n\n## Out-of-scope (本 issue 不處理)\n\n- ✗ `idd-implement` 在 implement 完成時也提示(可能是 follow-up:在 fix 還沒 ship 前先 surface 一次)\n- ✗ Auto-detect issue 影響 user-facing surface vs 純內部(留 user 用 `not applicable` 表態)\n- ✗ Release tag 自動 cut(那是 release flow 的職責,不是 close 的職責)\n\n## Relation to existing rules\n\n- `che-claude-config/rules/common-release-flow.md` — release-tier trigger;本 proposal 是 close-tier trigger,**互補不衝突**(一個 release 對多個 close,一個 close 對 0-1 個 release)\n- IC_R011 canonical pattern — Distribution Sync prompt 沿用 3-option AskUserQuestion + audit trail 結構\n\n## Trigger context\n\n提此 proposal 的當下 session 剛 close `che-apple-mail-mcp#72`(`get_email` base64 bug fix),PR #75 merged 為 commit `5fda74d`。但 marketplace.json 還沒 bump,使用者 `/plugin update che-apple-mail-mcp` 拉到的是舊 v2.16.0 binary,不會包含 fix。User 觀察到此 gap,提出建議。\n\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-10 by idd-close (#67 merged 566741c)\n\n### Key Decisions\n- Complexity = **Plan** (Layer P 命中: ordered Strategy 6 steps, decision-heavy detection heuristics, risk-sensitive — close-tier surface)\n- Layer V untriggered (V1=2, V4=3) — both axes ≤ 3\n- Step 6.5 placement: between current Step 6 (auto-update phase=closed) and Step 7 (batch close special rules) — explicit per issue body\n- Cross-repo callers (`plugin-update` / `mcp-deploy` / `cli-deploy`) `--source-issue` flag deferred to sister issue in `psychquant-claude-plugins`\n- Per Step 4.7 scope clarification: this change limited to `idd-close` SKILL.md + `references/distribution-detection.md` in this repo\n\n### Scope Changes\n- 2026-05-10: scope narrowed by user pre-emptively (Step 4.7 comment) — single repo only\n\n### Blocking\n- 等 user 確認 diagnosis 後跑 `/idd-plan #45` 進 EnterPlanMode approval gate\n\n### Sister Concerns\n- (none surfaced; Strategy 已 explicit 把 cross-repo work 列為 Step 6 sister issue,不另外 file)" }, { "number": 46, @@ -76,7 +83,8 @@ "- (none)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Original text** (user chat, /idd-issue, 2026-05-10):\n> 「我也要有複數個，這樣就是用DFS或BFS把全部都解掉，預設是用DFS」\n\n當前 `/idd-all-chain #N` 只接受**單一 root issue**(Step 0.1 在拿到 ≥2 個 `#NNN` 時 abort,訊息是「`/idd-all-chain accepts exactly 1 root issue`」)。但實務上常碰到場景:\n\n- backlog 上有 N 個相關但無 emergent dependency 的 issue 想一氣呵成解掉\n- 已知 N 個 issue 共享同一主題(如 #44 chain-solve + #45 distribution-aware close 都是 IDD orchestrator 演化),想用一個 cluster PR review\n- 跑完 #44 後想直接接 #45,但 chain 設計上不允許 multi-root\n\n當前替代:\n- 跑 N 次 `/idd-all-chain #N` → N 個 cluster PR、N 次 review,fragmentation\n- 用 cluster-PR mode `/idd-implement #34 #36 #38 --pr` → 但不會自動接 spawned sister bug,失去 chain 的核心價值\n\n需要新模式:**multi-root chain** — 接受 ≥2 個 root issue,用 DFS / BFS 遍歷整個 emergent forest(每個 root 的 subtree),全部 commit 到同一 cluster branch + 一個 cluster PR。\n\n## Type\n\nfeature (orchestrator extension to `idd-all-chain` — single-root → multi-root traversal)\n\n## Expected\n\n新增 multi-root invocation:\n\n```bash\n# DFS (default):root #44 完全解完(含 spawn)再開始 #45\n/idd-all-chain #44 #45 #50\n\n# BFS:round-robin — 先跑 #44 / #45 / #50 各自 depth=0,再各自 depth=1\n/idd-all-chain #44 #45 #50 --bfs\n```\n\n### DFS 行為(default)\n\n對每個 root,**完全 chain-solve 完該 root 的 subtree** 再移到下一個 root:\n\n```\nforest = [#44, #45, #50]\nDFS(forest):\n for each root in forest:\n process_chain_subtree(root) # 用既有 chain-eligible 規則展開 + 解\n```\n\n優點:每個 root 的 cognitive scope 完整(reviewer 看 PR 時可逐 root 區段 review);失敗 halt 點清晰(halt 時知道是哪個 root 的 subtree 出問題)。\n\n### BFS 行為(`--bfs` flag)\n\nRound-robin 處理 frontier:\n\n```\nqueue = [#44, #45, #50] # depth 0 of each root\nwhile queue non-empty:\n current = queue.pop_front()\n process(current)\n enqueue eligible spawns # 加到 queue 末尾,自然 BFS\n```\n\n優點:當 max-issues cap=5 即將達到時,確保所有 root 都至少跑過 depth=0(不會因為 #44 spawn 4 個就把 budget 全吃掉,#45 / #50 沒機會跑)。\n\n### Schema 影響\n\n**Spawn manifest** 從 single root_issue 改 multi-root:\n\n```json\n{\n \"schema_version\": 2, // 從 1 → 2 (breaking change)\n \"session_id\": \"\",\n \"root_issues\": [44, 45, 50], // 從 root_issue: → root_issues: [...]\n \"traversal\": \"dfs\", // \"dfs\" | \"bfs\"\n \"spawned\": [...]\n}\n```\n\nBackward compat:\n- Sub-skill manifest writer (`scripts/manifest-append.sh`) 偵測 `schema_version` mismatch abort — 跑 v2 chain 時 v1 sub-skill 會 abort,有清楚錯誤訊息\n- 或 dual-schema 同時 accept v1 + v2(複雜度↑,但無 breaking)\n\n### Cluster branch 命名\n\n```\n# Single root:idd/chain-44-\n# Multi-root:\nidd/chain-44-45-50 # 列前 N 個 issue number\nidd/chain-multi- # hash + label,適合 root 數多時\n```\n\n### Cluster PR title\n\n```\nchain: + 2 more\nchain (multi-root): <semantic label>\n```\n\n### Hard caps 互動\n\n當前 `chain_max_issues=5` 含 root 自己。multi-root:\n- 選 1:**total budget**(N roots + spawned ≤ 5;3 roots 只剩 2 spawn budget)\n- 選 2:**per-root budget**(每 root + spawn ≤ 5;3 roots 最多 15 issues)\n- 選 3:**scaled budget**(N roots → cap = 5N,但保護 multi-root 不會無限膨脹)\n\n推薦選 1 — IDD 紀律是 cluster PR 不該太大,total budget 直接限制 review surface。\n\n### Failure halt scope\n\n當前單 root:任一 chained verify FAIL → halt 整個 chain。multi-root:\n- 選 A:halt 整個 chain(含其他 root 的 subtree),保守\n- 選 B:halt 該 root 的 subtree,其他 root 繼續跑\n- 選 C:halt 該 root 的 subtree,**最後**列 abort report 說明哪些 root 沒 halt 哪些 halt\n\n推薦選 A(保守) — multi-root chain 的 cluster PR 是 atomic review surface,partial 成功的 cluster PR 對 reviewer 是 cognitive 負擔。\n\n## Actual\n\n- Step 0.1 在見到 ≥2 個 `\\#[0-9]*` arg 時 abort:\n ```\n /idd-all-chain accepts exactly 1 root issue (got '$ROOT_ISSUE' and '$arg').\n For multi-issue cluster, use /idd-implement #N #M --pr.\n ```\n- abort 訊息把使用者導向 cluster-PR mode,但兩者語意不同:cluster-PR mode 是 user-pre-known N issues,不會自動接 spawned;chain mode 是 auto-emergent。沒有「multi-root + auto-emergent」的選項。\n\n## Impact\n\n### 影響的工作流\n\n- 任何想對 backlog 上 N 個相關 issue 跑 chain 的場景\n- IDD lifecycle 的 cluster-PR 審查方式延伸(從 pre-known N → multi-root + emergent)\n\n### 影響的檔案\n\n- `plugins/issue-driven-dev/skills/idd-all-chain/SKILL.md`:\n - Step 0.1 arg parsing(allow ≥2 roots)\n - Phase 0.4 cluster branch naming\n - Phase 1 chain state init(queue 改 forest 或 multi-source queue)\n - Phase 2 traversal logic(DFS / BFS 切換)\n - Phase 3 cluster PR(title + body 含多 root 區段)\n - Phase 4 final report(per-root summary)\n- `plugins/issue-driven-dev/scripts/manifest-append.sh`:schema_version=2 偵測 + 適配\n- `plugins/issue-driven-dev/references/spawn-manifest.md`:schema v2 spec\n- `plugins/issue-driven-dev/references/chain-flow.md`:traversal algorithm 補章\n- `plugins/issue-driven-dev/skills/idd-all/SKILL.md`:`--in-chain` 不變(sub-/idd-all 仍是單 issue)\n- 4 個 sub-skill (idd-implement / idd-verify / idd-plan / idd-diagnose):若採 schema v2 breaking,manifest writer 需更新\n\n### 跨 issue / spec 影響\n\n- 與 `idd-orchestrator-modes` spec 第 4 種 tuple `(direct-commit, unattended)` 完全相容\n- 與 `idd-spawn-manifest` spec 不相容(schema v1 → v2 breaking change)\n- 與 #44 (`add-idd-all-chain-skill` change) 是 superset:#44 是 single-root 基礎,本 issue 在其上擴 multi-root\n\n## Open Questions(diagnose 時須收斂)\n\n1. **Schema v1 vs v2**:dual-accept(複雜)還是 hard breaking(乾淨但需要協調 sub-skill 升級)?\n2. **DFS halt fairness**:DFS 跑到第 1 個 root 的 subtree 用完 max-issues budget → 第 2/3 root 完全沒機會跑。是 feature(rich subtree 優先)還是 bug(skipped roots invisible)?\n3. **`--bfs` flag vs `--dfs` flag**:default DFS 已決定,但 BFS 是 explicit opt-in flag (`--bfs`) 還是 config (`chain_traversal: dfs|bfs`)?推 flag(per-invocation control,不污染 config)\n4. **Per-root verify fail handling**:halt 整個 chain (A) / halt subtree only (B) / 收集後 final report (C) — 推薦 A 但 trade-off?\n5. **Cluster branch 命名**:列 N issue number `idd/chain-44-45-50-<slug>` vs hash-based `idd/chain-multi-<hash>`?N 變大時 length 失控\n6. **PR title format**:`chain: <title #1> + N more` vs `chain (multi-root): <semantic label>`(後者需要 user 提供 label)\n7. **TaskList stage representation**:single-root chain 在 Phase 2 main loop 一次處理一個 issue;multi-root forest 怎麼 visualize 進度給 user 看?\n\n## 推測 design 方向(待 diagnose 確認)\n\n- DFS default + `--bfs` flag(opt-in BFS)\n- Total budget(`chain_max_issues=5` 涵蓋 N roots + spawn,不 scale)\n- Halt 整個 chain on any verify FAIL (option A,保守)\n- Cluster branch:`idd/chain-multi-<root_hash_8>-<slug>`(N>1 時),`idd/chain-<N>-<slug>`(N=1 backward compat)\n- Schema v2 hard breaking + helper script 偵測 schema mismatch abort(已有的 mechanism)\n- Verify discipline:per-issue verify 不省略(同 single-root)\n- PR body schema:增加 `## Roots` 區段列出全部 N root,每 root 有自己的 collapsed details\n\n## Priority\n\n**P2**:current single-root chain 已能滿足 ~80% 場景;multi-root 是延伸,非 blocker。但**對 backlog clean-up 場景 ROI 高**(N 個相關 issue 一次 PR 解掉),值得做。\n\n## Sister concerns(filed separately)\n\n- 上一輪 chain run #45 halted on first-real-use(因為 #45 spec 不完整),不是本 issue 的範疇但跟 chain ergonomics 相關\n- chain pre-flight 應該檢查 root issue 是否有 diagnosis comment(若無,prompt 跑 diagnose 先)— 待另開 issue 追蹤\n\n### Linked-Context Siblings Filed (v2.48.0+ #529)\n\nFiled sibling issues during /idd-issue Step 4.7 linked-context sister sweep:\n- **#47** — feature: /idd-all-chain Phase 0 pre-flight check for root issue diagnosis-readiness (P3, advisory enhancement triggered by halted #45 chain run)\n\n\n---\n\n## Clarification (added during diagnose, 2026-05-10)\n\n### Q1: Schema v1 → v2 升級策略\n\n**A**: **Hard breaking** — bump `EXPECTED_SCHEMA_VERSION=2`,同 PR ship `manifest-append.sh` + 4 個 sub-skill 的更新。理由:manifest 是 chain shell 內部 transient state,無 in-the-wild v1 client 需 backward compat。\n\n### Q2: Cap 機制重新設計 (新 decision)\n\n**A**: 把 default cap 從 `max-issues=5` **改成 `max-depth=3`**。\n\n意涵:\n- Cap mechanism shifts from **issue-count** to **depth** as primary budget\n- 每 root 可獨立發展 subtree 到 depth=3,不再因為 issue-count budget 互相搶\n- 自動解決原 Q2 (DFS budget fairness) 問題:depth-bounded per root 沒有 cross-root contention\n- depth=3 比現行 `chain_max_depth=2` 多 1 層,允許 root → spawn → spawn-of-spawn → spawn-of-spawn-of-spawn 共 4 層\n- ⚠️ **這是 #44 既有 chain 的 default 改變**(從 depth=2,issues=5 變成 depth=3,issues=??)— 影響不只 #46 multi-root,**single-root chain 行為也會改**。需在 design 階段釐清:\n - max-issues 還保留嗎(safety net)?還是純依 max-depth?\n - 純 max-depth 在惡性 spawn 的場景無上限(理論上單 root depth=3 可 spawn 出無數 issues),這可接受?\n - 推測 design 方向:**保留 max-issues 但放寬到 N=10 作為 safety net**,主 cap 用 max-depth=3\n\n### Q4: Verify FAIL halt scope\n\n**A**: **Option C — collect-then-report**:halt 該 root subtree(其他 root 的 subtree 繼續處理),最後 final report 列全部 root 狀態(passed / halted / skipped)讓 user 一次判斷。\n\n意涵:\n- 原 issue body 推 option A(halt all),user 否決 — 改 option C\n- 比 option B (halt subtree only) 多一層 audit:final report 顯式列出 partial 狀態\n- 影響 Phase 2 main loop:不再 `exit 1` on first FAIL,改 `continue` 跳到下個 root\n- 影響 Phase 4 final report:per-root status 是 first-class output(不是 footer 補充)\n\n### 更新後的設計總覽\n\n| Decision | Original recommendation | User choice | Effect |\n|---|---|---|---|\n| Schema | Hard breaking | ✅ Hard breaking | unchanged |\n| Cap | `max-issues=5` (multi-root total budget) | **`max-depth=3` per root** | major redesign — affects #44 too |\n| Halt scope | Option A (halt all) | Option C (collect-then-report) | per-root halt + aggregated report |\n\nQ3, Q5, Q6, Q7 留給 spectra-discuss 收斂。\n\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-18 by idd-close → idd-update\n\n### Key Decisions\n- Multi-root invocation `/idd-all-chain #A #B #C [--bfs]` shipped — DFS default, BFS opt-in flag\n- Spawn manifest schema v1 → v2 BREAKING (root_issues array + traversal + per-spawn root_id)\n- Caps redesign: per-root chain_max_depth 2 → 3, global chain_max_issues 5 → 10\n- Per-root verify FAIL halt (D4 Option C) — failing subtree halts + same-root QUEUE purge; other root subtrees continue\n- Branch naming: N=1 `idd/chain-<N>-<slug>`; N>1 `idd/chain-multi-<hash8>-<root1-slug>` (hash16 collision fallback)\n- PR title dispatch: N=1 `chain: <title>`; N>1 `chain (multi-root): N issues — <root#1 title>`\n- Phase 4 forest tree printout — per-root subtree icons + summary + filed-only list\n- Plugin bump v2.59.0 → v2.60.0\n\n### Scope Changes\n- Initial scope: only multi-root + DFS/BFS traversal\n- Post-clarification (2026-05-10): expanded to include cap mechanism redesign (depth-bounded vs issue-bounded) — affects #44 archived behavior\n- Verify FAIL halt scope: original recommend Option A → user chose Option C (per-root collect-then-report)\n\n### Blocking\n- (none)\n\n### Commits\n- `a83b884` spectra(archive): multi-root-traversal-idd-all-chain → 2026-05-18 (Refs #46)\n- `f688b18` feat(idd-all-chain): multi-root + DFS/BFS traversal + per-root halt + schema v2 (#82, Refs #46)\n\n### Resolution\n- PR #82 squash-merged 2026-05-18T07:57:16Z (commit `f688b18`)\n- Verify: PASS-WITH-FOLLOWUP — 4 P1 fixed in-scope (commit 583928f); P2/P3 deferred to follow-ups\n- Spectra archive: `openspec/changes/archive/2026-05-18-multi-root-traversal-idd-all-chain/` — 6 modified + 1 added requirement merged into main spec across idd-all-chain + idd-spawn-manifest capabilities\n- Closing summary: https://github.com/PsychQuant/issue-driven-development/issues/46#issuecomment-4475615951\n- Smoke tests 7.1/7.2 marked `[~]` — first-real-use validation track (next `/idd-all-chain #A #B` invocation is smoke gate)\n" }, { "number": 47, @@ -85,7 +93,8 @@ "- (none — closed via PR #50 squash merge + retroactive closing summary)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Source**: surfaced during /idd-issue #46 linked-context sister sweep (Step 4.7). Triggered by 2026-05-10 halted `/idd-all-chain #45` run — chain fired without checking #45 had a diagnosis comment, then we paused at Phase 2 because spec was incomplete.\n\n`/idd-all-chain #N` 當前 Phase 0 pre-flight 只檢查:\n- Working tree clean\n- 在 default branch\n- gh auth + issue OPEN\n\n**沒檢查** root issue 是不是有 `## Diagnosis` comment(代表 design 已收斂、有 Strategy / Complexity 判定)。後果:\n\n- 跑 chain 進 Phase 2 → invoke `/idd-all #N --in-chain` → 第一步是 idd-diagnose(因為 issue 沒 diagnosed)\n- idd-diagnose unattended 跑(`--in-chain` 推 unattended directive)→ Layer V vagueness 若 trigger 自動 `proceed anyway`\n- idd-diagnose 判 Spectra → 進 spectra-discuss → propose → apply,但 spec 還是 vague — implement 階段做出基於 partial spec 的 design 猜測\n- 6-AI verify 抓不到根本問題(因為 reviewers 也只看到 partial spec)\n- chain commit 出 user 不想要的 implementation\n\n實際撞到的案例:`/idd-all-chain #45` 在 first-real-use(deferred 6.3 e2e validation)halt 在 Phase 2 進入點,user 主動選擇 manual diagnose first 才發現:\n- #45 phase=created (沒 diagnosis comment)\n- body 的 detection logic 是 pseudocode shell,還沒 spec'd\n- Layer V 的 V4 (acceptance) 預估 ≥ 4 — 該 trigger 但 unattended 自動 proceed\n- multi-skill cross-cutting impact (idd-close + plugin-update + mcp-deploy + cli-deploy 共 4 個 skill)沒 design alignment\n\n## Type\n\nfeature (orchestrator pre-flight enhancement)\n\n## Expected\n\nPhase 0 加 `Step 0.6` Diagnosis-readiness check:\n\n```bash\n# 0.6: Root issue diagnosis-readiness check\nHAS_DIAGNOSIS=$(gh issue view \"$ROOT_ISSUE\" --repo \"$GITHUB_REPO\" --json comments \\\n | jq -r '[.comments[] | select(.body | contains(\"## Diagnosis\"))] | length')\n\nif [ \"$HAS_DIAGNOSIS\" = \"0\" ]; then\n # AskUserQuestion 3-option (per IC_R011 canonical pattern):\n # 1) \"Run /idd-diagnose first\" → halt chain, prompt manual diagnose\n # Cluster branch + manifest preserved (no rebase / revert)\n # 2) \"Proceed anyway\" → continue (current default behavior)\n # Audit trail in issue: `### Chain pre-flight: diagnosis bypassed`\n # 3) \"Cancel chain\" → halt + clean up cluster branch + manifest\n # (use case: user changed mind, wants to abort cleanly)\n AskUserQuestion(question=\"Issue #${ROOT_ISSUE} 沒有 diagnosis comment. ...\", ...)\nfi\n```\n\n### 為什麼 ASK 而非 BLOCK\n\n- 有些場景 user explicit 要 chain solve a fresh issue(快速 iterate),halt 太強硬\n- 但 default 走 chain 不 check 是踩坑 default — 觀察了 #45 案例後信心夠了\n\n### 與既有 mechanism 的關係\n\n- 與 idd-diagnose Step 3.4 Layer V Vagueness Pre-check 互補:Layer V 在 diagnose 內部,本 check 在 chain 外部(更早)\n- 與 chain failure mode (halt + preserve)一致:halt 時 cluster branch 跟 manifest 保留,user 隨時可手動 diagnose 後 re-run\n\n## Actual\n\n- Phase 0.3 universal pre-flight 只看 git 與 gh,不看 issue maturity\n- Phase 0.4 cluster branch 直接建,未做 spec readiness gating\n\n## Impact\n\n### 影響的工作流\n\n- Multi-root chain (見 #46) 也需要這個 check — 每個 root 都該 ready\n- 任何 first-real-use chain run\n\n### 影響的檔案\n\n- `plugins/issue-driven-dev/skills/idd-all-chain/SKILL.md`:Phase 0 加 Step 0.6\n- `plugins/issue-driven-dev/references/chain-flow.md`:更新 Phase 0 章節\n- 可能新增 `references/chain-preflight.md`(若 check 邏輯複雜)\n\n### 跨 skill 影響\n\n- `/idd-all #N` (without `--in-chain`) 也該套相同 check?可能需要,但 scope 在本 issue 不擴大 — 留 follow-up\n\n## 推測 design 方向\n\n- Default 1: AskUserQuestion 3-option (見上)\n- Default 2: BLOCK with clear instruction(`abort: run /idd-diagnose #N first`)+ 提供 escape hatch flag (`--skip-readiness-check`)\n- 推 default 1 — 與 IC_R011 canonical 3-option 一致,user 有 explicit override\n\n## Priority\n\n**P3**(advisory,non-blocking)— current chain 仍能跑(只是會撞 vague spec);此 enhancement 是 ergonomics 改善,user 已有 \"halt now, manual diagnose first\" mental model 可手動規避\n\n## Acceptance criteria\n\n1. Phase 0 多一個 Step 0.6,執行 `gh issue view --json comments` + `jq` filter for `## Diagnosis`\n2. 找到 → 繼續(silent pass)\n3. 沒找到 → AskUserQuestion 3-option,user 選擇:run-diagnose / proceed / cancel\n4. \"proceed\" 選項在 issue body 加 audit trail(下次讀 #N 的人看得到 chain 是 bypass diagnosis 跑的)\n5. unattended invocation(從 `/loop` 等 caller — 雖然 chain 設計上不該被 `/loop` 直接呼叫,但 sanity check)→ default `proceed`(同 Layer V unattended 的 \"proceed anyway\"),audit trail 記錄\n\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-10 by idd-close (PR #50 merged → squash a244ee9 → retroactive closing summary)\n\n### Key Decisions\n- Complexity = **Plan** (Layer P 命中: risk-sensitive chain pre-flight, 2+ ordered steps, decision-heavy on minor design points)\n- Layer V untriggered (V1=2, V4=2) — explicit Step 0.6 with bash + 5-item acceptance criteria\n- Cancel handler: abort + print cleanup commands (don't proactively delete branch / manifest, respect user judgment)\n- Detection: scan `comments[*].body` for `## Diagnosis` (精準 — 避免 issue body 內文誤判)\n- 與 #46 multi-root 互動:設計上保留擴展(helper function 接受 N 個 issue),具體 per-root readiness handling 在 #46 ship 時收斂\n\n### Scope Changes\n- (none — scope narrow as drafted)\n\n### Blocking\n- (none — closed via PR #50 squash merge + retroactive closing summary)\n\n### Sister Concerns\n- (none — #47 自身已是 sister concern from #45/#46;Risks 段已 explicit 涵蓋 implementation edge cases)\n\n\n\n\n\n" }, { "number": 48, @@ -94,7 +103,8 @@ "- (none — closed)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Original (user, 2026-05-10 session)**:\n> 「idd-issue 有沒有「不另外建立issue但就update」的可能性」\n>\n> 對話脈絡：\n> 「我發現根據逐字稿其實可以放idd-issue 或idd-update」\n> 「這個改動我覺得要納入idd的方法論」\n\n讀 transcript / source document / 老師回饋之類的多 finding 來源時，**有些 findings 該開新 issue、有些該 update 既存 issue**。目前的 IDD 工具集要求使用者**事先 triage 每個 finding**：\n\n- 對應到 existing #N 是新資訊／補充細節 → `/idd-comment #N`\n- 對應到 existing #N 但要覆寫假設或 strategy → `/idd-edit #N`\n- 對應到 existing #N 但只是進度推進 → `/idd-update #N`\n- 是全新主題 → `/idd-issue`\n\n問題：使用者必須**先讀完 source 並分類**才知道要呼叫哪個 skill；有時讀到一半才發現某 finding 其實對應到 #N 而非新主題；或是 finding 之間互相影響該 split / merge。\n\n## Why it matters\n\n實務情境（本 session 的 Lesley research project 就是案例）：\n\n- 09:48 開始的 session 處理 04-14 transcript → 直接用 `/idd-issue` 建 #1-#11（all new）\n- 10:05 處理 05-03 transcript → 接續建 #12-#22（mix of new + amendments to #6/#8 etc.）\n- 15:32 amend session 用 `gh api PATCH` 手動 update #6 #8 #12 #14 #17（**因為 idd-issue 不支援 update**）\n- 接下來 05-09 transcript 還有更多 findings 等處理\n\n當 source 跨多個既存 issue + 新主題時，使用者需要在腦中維護「finding → 哪個 skill」的 dispatch table。**這個 cognitive overhead 讓 transcript-driven workflow 反覆中斷**。\n\n## Type\n\nenhancement (methodology-level)\n\n## Suggested approaches\n\n三個方向，從輕到重：\n\n### 方向 A: 新增 `idd-triage` skill（推薦 first step）\n\n新建 `/idd-triage <source-file-or-text>` skill，職責：\n\n1. 讀 source（transcript / docx / pasted text）\n2. `gh issue list --state all --limit 50` 抓 repo 既存 issues 摘要\n3. AI 對每個 finding 提案分配：\n ```\n Finding 1 → /idd-comment #15 (Schultz 量表細節補充)\n Finding 2 → /idd-edit #14 (推翻原 hypothesis)\n Finding 3 → /idd-issue 新建 (transcript 提的 reputation 新概念)\n Finding 4 → /idd-update #17 (conjoint 進度推進)\n Finding 5 → ambiguous（list of options）\n ```\n4. AskUserQuestion confirm 每個 finding 的 routing\n5. 使用者 confirm 後**批次**執行對應 skill 呼叫\n\n這個 skill 是 **orchestrator pattern**（同 `idd-all`），不取代 atomic skills，而是包它們。\n\n### 方向 B: 在 idd-issue 加 `--or-update` flag\n\n```bash\n/idd-issue --or-update \"...transcript chunk...\"\n```\n\n行為：先掃 existing issues，若 finding 強匹配某 #N → AskUserQuestion 要新建還是 update（轉呼叫 idd-comment / idd-edit）。\n\n**缺點**：把「create」skill 和「update」skill 的邊界模糊化，違反 single-purpose 設計（current working 哲學是「每個 skill 對應一個明確 audit footprint」）。\n\n### 方向 C: 純文件化（references/ 新增 canonical pattern）\n\n不加新 skill / flag，只在 `references/transcript-driven-workflow.md` 寫清楚：\n\n> 處理 multi-finding source 時，先 read → triage（per-finding 分類）→ 用對應 skill。建議流程：...\n\n**優點**：成本最低、不擴張 skill 表面。\n**缺點**：使用者每次都要重新走一次 mental triage，沒解決 cognitive overhead。\n\n## Recommendation\n\n走 A → 比 C 更實用，比 B 更乾淨。先 ship `idd-triage` 試水溫，若使用者 retention 高再考慮 vs C 文件化的 dual delivery。\n\n關鍵設計問題（diagnose 階段要決定）：\n\n1. `idd-triage` 是否該自己寫 finding 出 issue，還是只 print「建議呼叫的 skill 序列」讓使用者 copy-paste？\n2. AI 的 finding extraction 失準率（漏掉、重複、誤分類）容忍度？需要 vs `idd-issue` 的 attachments / sister sweep 機制等同的 audit trail？\n3. 與 existing `idd-all` orchestrator 關係 — 是否合併？還是兩個 orchestrator 各管不同 trigger？\n4. 跟 `idd-list`（v2.51.0 新加的 issue listing skill）的 reuse opportunity — 那個 skill 已有 PR/cluster detection 的 issue 摘要能力。\n\n## Impact\n\n| 沒這個 feature | 有這個 feature |\n|--------------|--------------|\n| Multi-finding source 必須手動分 N 次 triage + invoke | 一次 `/idd-triage` → batch routing |\n| 使用者偶爾把該 update 的 finding 誤建為新 issue（後來才 close 重複）| AI 預先掃 existing issue 降低誤判 |\n| 「我之前是不是已經建過類似 issue」這個問題 → 手動翻 GitHub | AI 自動匹配並提示 |\n\n## Related\n\n- 本 session 對話（2026-05-10 17:xx Lesley research）\n- 2026-05-09 amend session 手動跑 `gh api PATCH` 5 次的 friction\n- v2.51.0 新增的 `idd-list` skill（reuse 機會）\n- `idd-all` orchestrator pattern（同類設計參考）\n\n\n## Case study: Lesley project transcript-driven workflow（2026-05-09 / 05-10）\n\n實際 friction trace：\n\n| 時點 | Action | Skill 用對了嗎 | Notes |\n|------|--------|---------------|-------|\n| 2026-05-09 09:48 | 04-14 transcript → `/idd-issue` 建 #1-#11 | ✅ all-new — `idd-issue` 適用 | Greenfield issue creation |\n| 2026-05-09 10:05 | 05-03 transcript → `/idd-issue` 建 epic #12 + children #13-#22 | ⚠️ partial — 其中部分 finding 應該是 amend #6/#8 而非新建 | 但當時手動分流 finding 太累，全部當新主題 |\n| 2026-05-09 15:32 | Amend #12 #17 #6 #8 #14 — **手動跑 `gh api PATCH`** 5 次 | ❌ 沒有現成 skill 可用 | `idd-edit` 可以但要 5 次 invoke + 各自 audit；`gh api PATCH` 直接寫但失去 audit trail |\n| 2026-05-09 17:00 | 0509 transcript 處理 → 此時 ask `idd-issue 有沒有 update 模式` | ❌ 已感受到 cognitive overhead | This issue 誕生 |\n| 2026-05-10 ongoing | 0509 transcript 還沒處理 | TBD | 等本 enhancement 進 backlog |\n\n**Concrete waste**：amend session 5 次 PATCH 各約 30 秒 = 2.5 分鐘 + 失去 idd-edit 的 audit trail（comment timeline 看不到 `## Implementation Plan` 結構化記錄）。隨 transcript 數量增加 amplify。\n\n**為什麼不直接用 idd-edit 5 次？** 當時 invocation chain 已經很深（idd-all → idd-implement → idd-verify → idd-close），加 5 個 idd-edit 會破壞 IDD pipeline 的 single-issue focus。`idd-triage` 的設計值就在「pre-pipeline batch 處理 multi-finding source」這個 phase。\n\n## Implementation sketch（/idd-triage SKILL.md outline）\n\n非正式 spec — diagnose 階段再 firmup。\n\n```\n# /idd-triage — Multi-finding source triage\n\n## 核心原則\n> 多 finding source 的 routing decision 是 batch 工作，不該每筆 invoke 一次 atomic skill。\n\n## Configuration\n同既有 IDD plugins（target resolution, walked-up config）\n\n## Execution\n\n### Step 0: Bootstrap stage TaskList（強制）\n\n### Step 0.5: Target repo resolution（reuse idd-issue Step 0.5）\n\n### Step 1: Read source\n- Source adapter（reuse idd-issue Step 1 source-type matrix）\n- Output: list of \"raw findings\"（AI extract，每筆 1-3 句描述 + 對應原文 quote）\n\n### Step 2: Fetch existing issues\n- gh issue list --state open --limit 50\n- gh issue list --state closed --limit 30 (recent 30 days, optional)\n- Build issue summary index: { #N → {title, body[:300], labels, state, last_activity} }\n\n### Step 3: AI per-finding triage\n對每個 finding，AI 提案：\n\n- match_type ∈ {NEW, COMMENT_TO #N, EDIT #N, UPDATE #N, AMBIGUOUS}\n- target_issue: #N or null\n- confidence: HIGH / MEDIUM / LOW\n- reasoning: 為什麼匹配到 #N（keyword overlap / topic match / explicit reference）\n- proposed_action: gh issue create / gh issue comment / gh issue edit / Skill(idd-update) call\n\nOutput: structured triage table\n\n### Step 4: AskUserQuestion confirm（batch）\n顯示完整 triage table，AskUserQuestion 4-option per finding：\n1. apply as proposed\n2. change routing（new sub-question per finding）\n3. skip this finding\n4. merge with another finding\n\n支援 bulk apply（如「全部 confidence=HIGH 的照辦」）\n\n### Step 5: Dispatch\n- NEW → Skill(idd-issue) per finding\n- COMMENT_TO #N → gh issue comment\n- EDIT #N → gh issue edit (with PATCH-and-preserve semantics)\n- UPDATE #N → Skill(idd-update)\n\n### Step 6: Audit trail report\nprint 完整 dispatch result + 每個 action 的 URL + 預期下一步（idd-diagnose / idd-close 等）\n\n## 與既有 skill 的關係\n- 不取代 idd-issue / idd-comment / idd-edit / idd-update\n- Orchestrator pattern（同 idd-all）\n- 失敗時 fallback 是「列出 routing table 讓使用者手動 invoke」\n```\n\n**關鍵 design 決定（延到 diagnose 階段）**：\n\n1. AI extract findings 的 granularity — 一段話 1 finding？還是 1 sentence 1 finding？太細 = 噪音，太粗 = 漏東西\n2. Existing-issue match 的 confidence threshold — HIGH 自動 dispatch / MEDIUM 問 / LOW 改建新？\n3. Audit trail 的 source-of-truth — triage report 寫到哪裡？建立一個「meta-issue」追蹤本次 triage？還是只在 dispatched 各 issue 加 comment？\n4. 跟 `idd-list`（v2.51.0）的 reuse — 那個 skill 已能 fetch + format issue list with PR/cluster info，可以當 Step 2 的 building block\n\n<!-- idd:enhancement date=2026-05-10 -->\n\n### Linked-Context Siblings Filed (v2.48.0+ #529)\n\n(none — body draft + recent session conversation 無 orphan sibling markers; 4 design questions in body 已 explicit 列為 in-scope diagnose follow-ups)\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-12 by idd-close\n\n### Key Decisions\n- Strategy B Realignment (2026-05-10): instead of new `/idd-triage` skill (Strategy A), implemented multi-finding mode directly in `idd-issue` to minimise published API surface\n- 7 architectural decisions converged via spectra-discuss before code: D1 user-route, D2 hybrid audit trail, D3 top-3 AI candidates, D4 batch preview + warn-continue, D5 merge = inline sub-prompt, D6 auto-detect trigger, D7 mutual-exclusion gate vs --bundle-mode\n- SDD path (spectra-discuss → spectra-propose → spectra-apply): spec frozen before implementation\n\n### Scope Changes\n- Original scope: new `/idd-triage` orchestrator skill (Strategy A)\n- Delivered scope: multi-finding source mode added to `idd-issue` (additive, no breaking change); cross-reference updates to idd-comment, idd-edit, idd-update SKILL.md\n\n### Blocking\n- (none — closed)\n\n### Follow-ups Filed\n- #75 (security/sanitization conflicts), #76 (run_id collision), #77 (spec gaps), #78 (backward compat docs), #79 (audit trail completeness), #80 (Stage 1 reproducibility + scoring)\n\n### Commits\n- `38c72f2` feat(idd-issue): multi-finding source mode (#48)" }, { "number": 49, @@ -103,7 +113,8 @@ "- 等 user 跑 /idd-verify --pr 58 (cluster-PR mode 6-AI ensemble)" ], "expect_empty": false, - "expect_first_blocker": "- 等 user 跑 /idd-verify --pr 58 (cluster-PR mode 6-AI ensemble)" + "expect_first_blocker": "- 等 user 跑 /idd-verify --pr 58 (cluster-PR mode 6-AI ensemble)", + "body": "## Problem\n\n> **Source**: surfaced during /idd-diagnose #48 sister concern surfacing (Step 3.6) — https://github.com/PsychQuant/issue-driven-development/issues/48#issuecomment-4413850520\n\n#48 diagnosis 在 Related issues / cluster context 段落提到：\n\n> **#37 (CLOSED)** `/idd-all (無參數) bulk-solve mode` — prior art，需查 close reason 確認是否 superseded by #44 chain\n\n但 #37 為何 close 沒留下明確 link。若是 superseded by #44 (chain-solve mode) → `references/usecase-routing.md` 應 explicit 寫「無參數 bulk-solve 用 chain-solve」。若是其他原因（如 won't fix / 重新設計）→ 也該記錄供 future 維護者參考，避免重複 propose。\n\n## Why it matters\n\n未來有人要做 IDD orchestration 演化（包括 #44 / #46 / #47 / #48）時，#37 的 decision rationale 是 prior art。沒明文連結會：\n- 重複 propose 同樣的 idea（已被 evaluated 過的）\n- IDD 自己的 decision archaeology 出 gap\n\n## Type\n\ndocs\n\n## Priority\n\nP3 — 純 archaeology 整理，不 blocker\n\n## Scope\n\n- 讀 #37 close reason / closing comment\n- 若 superseded → `references/usecase-routing.md` 加 row 連到 #44 / #46\n- 若其他 reason → 同上 doc 加 brief note\n\n## Related\n\n#48 (parent diagnosis) — surfaced during Step 3.6 sister concern surfacing\n#37 (target of investigation)\n#44 #46 #47 (likely supersession candidates)\n\n<!-- idd:docs date=2026-05-10 -->\n\n---\n\n## Current Status\n\n\\*\\*Phase\\*\\*: closed\n**Last updated**: 2026-05-10 by idd-close (cluster #49+#53)\n\n### Key Decisions\n- Complexity = **Simple** (Layer 1 disqualifier: pure docs)\n- Layer V untriggered\n- #37 確認 parked 不 superseded;#44 chain-solve 跟 #37 bulk-solve orthogonal — docs 加 cross-link 即可\n\n### Blocking\n- 等 user 跑 /idd-verify --pr 58 (cluster-PR mode 6-AI ensemble)" }, { "number": 51, @@ -112,7 +123,8 @@ "- 等 user 跑 /idd-plan #51 進 EnterPlanMode 對齊 signature" ], "expect_empty": false, - "expect_first_blocker": "- 等 user 跑 /idd-plan #51 進 EnterPlanMode 對齊 signature" + "expect_first_blocker": "- 等 user 跑 /idd-plan #51 進 EnterPlanMode 對齊 signature", + "body": "## Problem\n\n> **Source**: surfaced during /idd-verify #47 (codex P3 #7).\n\n`/idd-all-chain` Step 0.4 (NEW in #47) 文宣中 `references/chain-flow.md` 寫:\n\n> Future #46 multi-root extension: helper function design preserves N-arg shape (`check_diagnosis_readiness(issue_numbers...) → [ready_list, not_ready_list]`)\n\n但實際 implementation 是 inline bash,沒有 named function。這是「prose claim」而非「實際 code」,#46 multi-root 落地時無法直接 reuse。\n\n## Type\nfeature (refactor + future-proofing)\n\n## Expected\n\n把 #47 Step 0.4 的 inline bash logic 抽成 named function:\n\n```bash\ncheck_diagnosis_readiness() {\n local issue_numbers=(\"$@\")\n local ready=()\n local not_ready=()\n for n in \"${issue_numbers[@]}\"; do\n local has=$(gh issue view \"$n\" -R \"$GITHUB_REPO\" --json comments \\\n | jq -r '[.comments[] | select(.body | contains(\"## Diagnosis\"))] | length')\n if [ \"$has\" = \"0\" ]; then\n not_ready+=(\"$n\")\n else\n ready+=(\"$n\")\n fi\n done\n # Return as JSON for parsing\n jq -n --argjson ready \"$(printf '%s\n' \"${ready[@]}\" | jq -R . | jq -s .)\" \\\n --argjson not_ready \"$(printf '%s\n' \"${not_ready[@]}\" | jq -R . | jq -s .)\" \\\n '{ready: $ready, not_ready: $not_ready}'\n}\n```\n\n或寫成 helper script `scripts/check-diagnosis-readiness.sh`。\n\n## Priority\nP3 (#46 落地時會撞到;先有 #47 落地驗證單 root,再 refactor 為 N-arg 也可)\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-11 by idd-close (#69 merged a7ff5f2)\n\n### Key Decisions\n- Complexity = **Plan** (Layer P 命中: 2+ files coupled, decision-heavy Path A vs B, risk-sensitive helper signature for #46 reuse)\n- Layer V untriggered (V1=2 V4=3)\n- 推 Path B ( per manifest-append.sh precedent)\n\n### Blocking\n- 等 user 跑 /idd-plan #51 進 EnterPlanMode 對齊 signature" }, { "number": 52, @@ -121,7 +133,8 @@ "- (none — issue closed)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Source**: surfaced during /idd-verify #47 process gap (5-Claude ensemble failed).\n\n執行 `/idd-verify #47` 時 spawn 5 Claude reviewer agents 結果**無一產出 findings**,只有 1 個 Codex CLI 出 report。Root cause 三層:\n\n1. **`subagent_type=Explore` 沒 Write tool** — Explore agent 是 read-only(per Agent tool docs: \"Tools: All tools except Agent, ExitPlanMode, Edit, Write, NotebookEdit\"),無法 `Write findings to /tmp/verify_47_findings_<role>.md`\n2. **Idle/wake cycle 後 context 流失** — 第二次 SendMessage 重新 prompt 時,agents 已經 idle 過,original review 工作沒留 context,新 message 看不出做了什麼\n3. **`SendMessage` reply 沒被觸發** — agents 收到 message 後 idle without sending response,因為 prompt 沒 explicit 說「reply via SendMessage」\n\n實際 effective coverage:1-AI (Codex) 而非 6-AI (5 Claude + 1 Codex)。雖然 Codex 仍抓到 3 P1 blocking,但 4 個 reviewer perspective 完全 missed,verify discipline 退化。\n\n## Type\nfeature (process — verify orchestration playbook)\n\n## Expected\n\n新 reference doc `references/verify-orchestration.md` 或在 `idd-verify/SKILL.md` Step 2 加 explicit guidance:\n\n### A. Spawn options trade-off\n\n| Option | Tools | Output mechanism | Pros | Cons |\n|---|---|---|---|---|\n| `subagent_type=Explore` (read-only) | Read/Grep/Glob/Bash | Must use SendMessage reply (no Write) | Lightweight | Easy to lose findings if prompt unclear |\n| `subagent_type=general-purpose` | All tools incl. Write | File write at `/tmp/verify_<NUMBER>_findings_<role>.md` | Skill spec compatible | Heavier context |\n| `Bash codex exec --full-auto` background | Independent | Output file via `-o /tmp/codex-verify-<NUMBER>.md` | Truly independent (different model family) | No interactive feedback |\n\n### B. Explicit prompt requirements\n\nFor every spawned reviewer:\n1. 明示 output mechanism (file write OR SendMessage reply)\n2. 明示「不要 idle without producing output」\n3. Idle 後 SendMessage retry 必須**重 paste 全部 context**(原 prompt + diff path + issue path)— agent 不持久 hold 之前 turn 的 context\n\n### C. Recovery protocol\n\nIf agent idles without findings:\n- Step 1: Check exists 對應 output file → if exists, proceed\n- Step 2: SendMessage retry **with full context re-paste** (not assume context preserved)\n- Step 3: If second idle without output, fall back to coordinator self-review for that role + document as process gap in verify report\n\n## Priority\nP2 (impacts verify reliability — 一個未防範的 process gap 會讓未來 verify 退化成 1-AI without obvious failure mode)\n\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-12 by idd-close (via /idd-update)\n\n### Key Decisions\n- Plan tier D1-D5 implemented: TeamCreate → 5 standalone Agent(subagent_type=general-purpose) calls + Recovery Protocol with sentinel-based DA timeout detection + pre-spawn prompt persistence + coordinator self-review fallback\n- D3 inline (no separate references/verify-orchestration.md) — ~150 lines additions, below extraction threshold\n- D5 Devil's Advocate polling-on-files (max 30 iter × 5s) replaces TeamCreate wait_for_idle; sentinel marker `[STAGE 2.5 RECOVERY: DEVILS_ADVOCATE_TIMEOUT_<n>/4]` distinguishes timeout-skip from valid review\n- Side benefit: #70 (TeamDelete cleanup gap) structurally resolved — no team → no cleanup gap\n- Complexity = Plan (Layer P); Layer V untriggered (V1=2 V4=3)\n\n### Scope Changes\n- (none — pure in-scope refactor; sister sweep + tangential sweep both empty)\n\n### Blocking\n- (none — issue closed)\n\n### Commits\n- `c31b097` feat: idd-verify orchestration playbook (5 Agents + Recovery Protocol) (#73) — squash of 3 PR commits\n- Squashed PR commits: `63d2474` + `d149b81` + `c3fcfb4`\n\n### Closing\n- Closing summary: https://github.com/PsychQuant/issue-driven-development/issues/52#issuecomment-4425811791\n- Master verify report: https://github.com/PsychQuant/issue-driven-development/pull/73#issuecomment-4421606190\n- Cross-resolves: #70 (separate /idd-close cycle to follow)\n\n### Process Gap Caveat\nThis PR's verify was conducted under codex-only degraded mode (Anthropic API rate-limit). The NEW 5-Agent + Codex orchestration this PR introduces has NOT been exercised in production yet (since the verify itself couldn't use the new mechanism). **First-real-use validation deferred** to next `/idd-verify` invocation in fresh session.\n" }, { "number": 53, @@ -130,7 +143,8 @@ "- 等 user 跑 /idd-verify --pr 58 (cluster-PR mode 6-AI ensemble)" ], "expect_empty": false, - "expect_first_blocker": "- 等 user 跑 /idd-verify --pr 58 (cluster-PR mode 6-AI ensemble)" + "expect_first_blocker": "- 等 user 跑 /idd-verify --pr 58 (cluster-PR mode 6-AI ensemble)", + "body": "## Problem\n\n> **Source**: surfaced during /idd-verify #47 (codex P3 #9).\n\n`/idd-all-chain` Step 0.4 (#47) 用:\n\n```bash\nHAS_DIAGNOSIS=$(gh issue view \"$ROOT_ISSUE\" -R \"$GITHUB_REPO\" --json comments \\\n | jq -r '[.comments[] | select(.body | contains(\"## Diagnosis\"))] | length')\n```\n\n`contains(\"## Diagnosis\")` substring match — 可能 false-positive on:\n- Comment body 內 quoted history (`> ## Diagnosis ...`)\n- 討論 diagnosis 概念但不是真 diagnosis comment\n- 程式碼或 docs 範例裡寫 `## Diagnosis`\n\n## Type\nbug\n\n## Expected\n\n改用 anchor regex match,只認 line-start 的 `## Diagnosis`:\n\n```bash\n| jq -r '[.comments[] | select(.body | test(\"(?m)^## Diagnosis\"))] | length'\n```\n\n`(?m)` flag 讓 `^` 對 each line。\n\n## Priority\nP3 (#47 base case 仍 work,只在 corner case false-positive;#47 fix-immediate 後加進 follow-up batch)\n\n---\n\n## Current Status\n\n\\*\\*Phase\\*\\*: closed\n**Last updated**: 2026-05-10 by idd-close (cluster #49+#53)\n\n### Key Decisions\n- Complexity = **Simple** (Layer 1 not triggered, Layer 2/P 都不命中)\n- Layer V untriggered (V1=2 V4=2)\n- Single-file 1-line jq filter change → /idd-implement next\n\n### Blocking\n- 等 user 跑 /idd-verify --pr 58 (cluster-PR mode 6-AI ensemble)" }, { "number": 54, @@ -139,7 +153,8 @@ "- (none)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Source**: surfaced during /idd-verify #47 (codex P3 #6).\n\n`/idd-all-chain` capability spec at `openspec/specs/idd-all-chain/spec.md` 是 archived from #44 (`add-idd-all-chain-skill` change)。但 #47 落地後 spec 沒同步更新 — Phase 0 描述仍是 4 道 gate (git/auth/issue OPEN/cluster branch),沒有第 5 道 diagnosis-readiness gate。\n\n實務上 archived spec 是 frozen contract;後續 capability 擴展(#47 / 預期的 #46 multi-root)沒有清楚的 mechanism 把 delta 推回 archived spec。\n\n## Type\nfeature (process / infrastructure)\n\n## Expected\n\n定義 archived spec sync mechanism。可能方向:\n- a. 後續 change 用 MODIFIED 修改 archived spec(類似 spectra apply 的 spec delta,但 source 是 archived)\n- b. 每次擴展都是新 capability(`idd-all-chain-v2` / `idd-all-chain-multi-root`),不修 archived\n- c. Archive 內維護 changelog appendix(`spec.md` + `extensions.md`),不動 frozen 部分\n\n## Priority\nP3 (process improvement;不影響 #47 本身落地,但長期影響 spec discipline)\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-18 by idd-close → idd-update\n\n### Key Decisions\n- Closed as **won't-fix** (premise obsoleted on inspection)\n- `spectra archive` already applies spec deltas to canonical main spec — Option (a) in issue body IS the existing mechanism\n- Vocabulary drift surfaced: issue body's \"archived spec\" conflated main spec with change snapshot\n\n### Scope Changes\n- (none — no implementation)\n\n### Blocking\n- (none)\n\n### Resolution\n- `/spectra-discuss #54` (2026-05-18) — 4 assumptions confirmed\n- Diagnosis comment Strategy items: `- [ ]` → `- [-]` with won't-fix reason\n- Closing summary: https://github.com/PsychQuant/issue-driven-development/issues/54#issuecomment-4475734419\n- Validated live by #46 archive run (`Specs applied: idd-all-chain, idd-spawn-manifest (added: 1, modified: 6)`)\n\n### Commits\n- (none — no code shipped)\n" }, { "number": 55, @@ -148,7 +163,8 @@ "- (none — issue closed)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Source**: surfaced during /idd-issue multi-finding mode dogfood (kiki830621/teaching_lesley 0509 transcript), 2026-05-10\n\nSpec contract D2(`idd-issue-multi-finding-source` Requirement: \\\"JSONL run log SHALL be committed to git by default\\\")要求 `.claude/.idd/issue-runs/<run_id>.jsonl` 進 git。\n\n但 Lesley project `.gitignore:6` 是 `.claude/` — 把整個 `.claude/` 目錄全部 gitignore(這是常見的 IDE-config gitignore pattern,因為 `.claude/` 通常含 cache、attachments、local config 等不該 commit 的東西)。\n\n實際 dogfood 結果:\n- jsonl 寫入 `.claude/.idd/issue-runs/2026-05-10T05:29:26.jsonl` ✓\n- `git status` 不顯示 untracked(被 `.claude/` 阻擋)\n- D2 spec contract 「commit jsonl by default」**violated**\n\n## Type\n\nbug (spec gap surfaced by real-world dogfood)\n\n## Impact\n\n- Cross-machine continuity 假設失效:user 移到別 machine 看不到先前 run log\n- D2 spec contract violated\n- 任何 repo `.gitignore` 含 `.claude/` 都遇到同問題\n\n## Proposed fix\n\nStage 4.5 加 pre-flight gate:\n\n```bash\n# Check if .claude/.idd/issue-runs/ is gitignored\nif git check-ignore -q .claude/.idd/issue-runs/2026-05-10T00:00:00.jsonl 2>/dev/null; then\n AskUserQuestion(\n question = \"repo .gitignore 阻擋 .claude/.idd/issue-runs/ — multi-finding jsonl 無法進 git。怎麼處理?\",\n options = [\n \"Add exception 到 .gitignore\" → append `!.claude/.idd/issue-runs/`\n \"Skip commit (jsonl 本地存但不進 git)\" → 接受 cross-machine continuity 失效\n \"Abort\" → 退出 dispatch\n ]\n )\nfi\n```\n\n或者改 jsonl 預設 path 到 non-`.claude/` location(e.g. `idd-runs/` at repo root)— 但 break 既有 `.claude/.idd/` 統一 convention。\n\n## Related\n\n- #48 (parent — multi-finding mode change)\n- D2 contract violation\n\n<!-- idd:bug from-dogfood date=2026-05-10 -->\n\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-11 by idd-close (via /idd-update)\n\n### Key Decisions\n- Plan tier D3 evolved through 3 revisions: v1 single-line exception (broken per git docs) → v2 4-line carve-out (broken under stacked sources) → v3 **universal 5-line with `!.claude` parent re-include** (final)\n- IS_NESTED_GITIGNORE classification → AskUserQuestion 2-option Case B when nested (root rewrite cannot override per-directory ignore)\n- Idempotency check evolved: marker-only (R5 found stale-block bug) → marker + `!.claude` content presence (R7 final) with awk state machine upgrade path\n- Complexity = Plan (Layer P 命中)；Layer V untriggered (V1=2 V4=3)\n- Sister sweep + tangential sweep both empty (Plan D3 revision 已涵蓋全部 scope)\n\n### Scope Changes\n- (none — pure in-scope D3 revisions; no scope creep across 7 verify rounds)\n\n### Blocking\n- (none — issue closed)\n\n### Commits\n- `c342aa2` fix(idd-issue): Stage 4.5 jsonl gitignore pre-flight gate (#55) (#71) — squash of 9 PR commits\n\n### Closing\n- Closing summary: https://github.com/PsychQuant/issue-driven-development/issues/55#issuecomment-4421150527\n- Master verify report: https://github.com/PsychQuant/issue-driven-development/pull/71#issuecomment-4421108494\n" }, { "number": 102, @@ -157,7 +173,8 @@ "- (none — Implementation Plan approved, ready for `/idd-implement #102`)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Original text** (使用者於 2026-05-19 #96-backlog triage session 提出,反思剛把 PR #101 的 review 委派給 AI 之後):\n> 「其實我現在都不 review,人不 review 是不是也要有人不 review 的做法」\n\nIDD 的 mode model 目前是一個 2-tuple:**`(path, interaction)`** — `PR / direct-commit` × `attended / unattended`(見 `references/pr-flow.md`、`idd-all` Phase 0.5)。但這個 tuple 沒有涵蓋一個獨立的維度:**acceptance review** —— merge 前「誰簽核接受這個改動」。\n\nIDD 裡其實有**兩層 review,只 model 了一層**:\n\n1. **`idd-verify`** = AI *correctness* 驗證(6-AI ensemble)。強制、機械式、可證偽。回答「code 有沒有滿足 issue 的要求」。\n2. **merge-time acceptance review** = owner 的「我們要不要這個 / 現在 / 這樣做」判斷。**目前完全沒 model** —— `idd-all` / `idd-all-chain` 「停在 verified」,然後 informally 提示「human review → merge → close」。\n\n實務上使用者回報:他**根本不做** human acceptance review。所以 `(PR, unattended)` mode 產出一個 `idd-verify` 通過的 PR,然後……就直接 merge 了。IDD 設計上假設存在的「human review」那一步被無聲跳過。\n\n**核心問題**:如果「人不 review」是實際的運作模式,IDD 應該對它有一個**設計過的做法** —— 命名它、明確化它、決定(若有)什麼東西替代那個 acceptance 判斷 —— 而不是留成一個 informal gap 讓使用者默默繞過。\n\n### 三個已觀察到的 acceptance-review 值\n\n同一個 backlog-triage session 內,acceptance review 實際出現了 3 種不同行為:\n\n| 值 | session 內何處 | 獨立性 |\n|---|---|---|\n| **human review** | #96 → PR #99,使用者自己看、自己 merge | ✅ 獨立 |\n| **AI-delegated review** | PR #101「你可以幫我 review」→ 實作 AI 做 mergeable / auto-close-trap-scan / verify-history 檢查後 merge | ⚠️ 弱 |\n| **no review** | `idd-verify` PASS 即 merge(使用者自述的常態) | ❌ 無 |\n\n### 關鍵風險:委派回實作 AI 會塌掉獨立性\n\n`idd-verify` 的 6-AI 之所以有效,是因為「Claude 修、**獨立** AI 群驗」—— reviewer ≠ implementer。當 acceptance review 委派回**實作的 AI 本身**(PR #101 的情況),那層獨立性就消失了 —— 變成實作者審自己的 acceptance。PR #101 還算安全(純 docs、6-AI 已驗、做的是機械檢查),但**當預設**就危險。\n\n所以更精準的問題不是「要不要人 review」,而是 **「acceptance 的獨立判斷從哪來」**:`idd-verify` 給獨立的 *correctness*;merge review 本該再加一層獨立的 *acceptance*;委派回實作 AI = 省事但獨立性沒了。\n\n## Type\n\nenhancement(IDD methodology / mode model 設計)\n\n## Expected\n\nIDD 對「acceptance review」這個維度有明確的設計立場。候選方向(待 `idd-diagnose` 決定,此處僅列出不預判):\n\n- **A. 升級為 3-tuple `(path, interaction, acceptance)`** —— `acceptance ∈ {human-required, AI-delegated, none}`,在 `pr-flow.md` / `idd-all` Phase 0.5 明文解析,跟現有兩軸從同一 source 推導。\n- **B. 不擴 tuple,但讓 verified→merge 的收尾明確問一次**「這個 merge 誰簽?」—— 把隱性步驟升成 explicit checkpoint(類似 `idd-close` 的 human-checkpoint 哲學)。\n- **C. 維持現狀但文件化** —— 承認 `idd-all` 停在 verified 之後的 acceptance 是 informal,明文寫「IDD 不負責 acceptance gate,使用者自負」,至少讓缺口從隱性變顯性。\n- 不論哪個方向,都要處理「AI-delegated review 會塌掉獨立性」這個 risk —— 例如若允許 AI 代理 acceptance,是否應由**非實作的**獨立 AI 做(借 `idd-verify` 既有的獨立性設計),而不是實作 AI 自審。\n\n## Actual\n\n- IDD mode model 只有 `(path, interaction)` 2-tuple;acceptance review 不是 first-class 概念。\n- `idd-all` / `idd-all-chain` 「停在 verified」+ informally 提示 human review —— 沒有 enforce、沒有 model、沒有紀錄「這個 merge 由誰 accept」。\n- 使用者實務上跳過 human acceptance review;IDD 沒攔、也沒提供替代設計。\n- PR #101 出現了第三種未命名的 mode(AI 代理 acceptance review),IDD 完全沒有它的契約。\n\n## Impact\n\n- 影響的檔案:`references/pr-flow.md`(mode resolution canonical 演算法)、`skills/idd-all/SKILL.md` + `skills/idd-all-chain/SKILL.md`(Phase 0.5 mode tuple、收尾 stop-at-verified)、`skills/idd-verify/SKILL.md`(verify 是 correctness 層,需與 acceptance 層明確區分)、`skills/idd-close/SKILL.md`(close 的 human-checkpoint 哲學與 acceptance review 高度相關)、`CLAUDE.md`(mode 文件)、可能 `MANIFESTO.md`(IDD 的 closure axis 論述應納入 acceptance 維度)。\n- 影響的使用者流程:所有走 PR path 的 IDD 工作 —— verified 之後的 acceptance 目前是 undefined behavior。\n\n## Notes\n\n由 2026-05-19 的 #96-backlog triage session 浮現 —— 使用者在該 session 把 cluster-PR #101 的 review 委派給 AI,事後反思「人不 review」其實是常態,於是發現 IDD 的 mode model 缺了 acceptance 這個維度。屬於「用 IDD 的過程中浮現的 IDD 設計缺口」,本身就值得一個 issue。\n\n相關脈絡:同 session 的 #96(cluster-PR vs direct-commit path 衝突)也是 mode model 的設計議題 —— 兩者都指向 `pr-flow.md` 的 mode resolution 需要更完整的維度模型。---\n\n## Current Status\n\n**Phase**: planning\n**Last updated**: 2026-05-20 by idd-plan\n\n### Key Decisions\n- Plan tier approval gate passed (EnterPlanMode → ExitPlanMode approved 2026-05-20). Implementation Plan posted at [issue-comment-4493125984](https://github.com/PsychQuant/issue-driven-development/issues/102#issuecomment-4493125984).\n- Branch `idd/102-acceptance-review-doctrine` cut from main at `db25514`. PR path. Chain to `/idd-implement #102`.\n- Plan-tier scope = MANIFESTO doctrine + `idd-all`/`idd-all-chain` Phase 6/4 messaging swap + per-invocation `--review` flag. 6 files (5 plugin + branch). Plugin will bump 2.64.0 → 2.65.0.\n- Mid-plan tangential filed: **#108** (4-template PR-body checklist consistency family — `idd-implement` Step 5.5 / `idd-all` Phase 5 / `pr-flow.md` canonical stale wording; sync post-merge).\n- Plan re-routed Spectra → Plan via `/spectra-discuss` (2026-05-19 conclusion at [issue-comment-4486107094](https://github.com/PsychQuant/issue-driven-development/issues/102#issuecomment-4486107094)).\n- Direction A (3-tuple `(path, interaction, acceptance)`) and most of Direction B (merge-time gate) killed by discuss; what ships is doctrine + thin flag.\n- IDD's human-in-the-loop is the NSQL Confirmation Protocol; `verify-gated` is the terminal default disposition; `--review` is opt-in re-open, NOT a quality gate.\n\n### Scope Changes\n- (none — Plan tier ships exactly what the discuss conclusion specified)\n\n### Blocking\n- (none — Implementation Plan approved, ready for `/idd-implement #102`)\n\n### Commits\n- (none yet — Implementation Plan approved, awaiting `/idd-implement #102`)---\n\n## Current Status\n\n**Phase**: implemented\n**Last updated**: 2026-05-20 by idd-implement\n\n### Key Decisions\n- Implementation complete on branch `idd/102-acceptance-review-doctrine` → PR **[#109](https://github.com/PsychQuant/issue-driven-development/pull/109)** (4 commits, +123/−12 across 5 files); plugin bumped to v2.65.0\n- Implementation Plan approved via EnterPlanMode 2026-05-20; ([Implementation Complete](https://github.com/PsychQuant/issue-driven-development/issues/102#issuecomment-4493184518))\n- Step 5.7 sister sweep extended **#108** to 5-template family — surfaced `references/chain-flow.md:254` carrying the same stale `Pending: human review of cluster PR` wording (not in original 4-template list)\n- 4 commits land: `4aef425` MANIFESTO doctrine · `1fdcba0` idd-all --review + Phase 6 swap · `11a99e0` idd-all-chain --review propagation + PR-body conditional · `8a41ee7` v2.65.0 bump\n- Mid-plan tangential **#108** filed (4→5-template PR-body checklist consistency family — `idd-implement` Step 5.5 / `idd-all` Phase 5 / `pr-flow.md`:135 / `chain-flow.md`:254 stale wording; sync post-merge)\n- Plan re-routed Spectra → Plan via `/spectra-discuss` (2026-05-19 conclusion at [issue-comment-4486107094](https://github.com/PsychQuant/issue-driven-development/issues/102#issuecomment-4486107094))\n- Direction A (3-tuple `(path, interaction, acceptance)`) and most of Direction B (merge-time gate) killed by discuss; what ships is doctrine + thin flag\n- IDD's human-in-the-loop is the NSQL Confirmation Protocol; `verify-gated` is the terminal default disposition; `--review` is opt-in re-open, NOT a quality gate\n\n### Scope Changes\n- (none — implementation ships exactly what the discuss conclusion + Implementation Plan specified)\n\n### Blocking\n- (none — PR #109 ready for `/idd-verify --pr 109`)\n\n### Commits\n- `8a41ee7` chore: bump issue-driven-dev to v2.65.0 (Refs #102)\n- `11a99e0` feat(idd-all-chain): add --review flag propagation + Phase 4/PR body conditional wording (Refs #102)\n- `1fdcba0` feat(idd-all): add --review flag + Phase 6 verify-gated terminal wording (Refs #102)\n- `4aef425` feat(MANIFESTO): add Human-in-the-loop / NSQL Confirmation Protocol doctrine (Refs #102)---\n\n## Current Status\n\n**Phase**: verified\n**Last updated**: 2026-05-20 by idd-verify\n\n### Key Decisions\n- 6-AI verify on PR #109 → **PASS post-fix** — 1 HIGH blocking (F1 `${VAR:-word}` mutex bug) caught by 3 of 6 reviewers convergent (regression / DA / Codex); fixed in-PR `dc61ffb`. Master verify: [pull/109#issuecomment-4493323648](https://github.com/PsychQuant/issue-driven-development/pull/109#issuecomment-4493323648)\n- In-PR polish committed `dc61ffb` — F1 mutex fix (explicit if/else builds `$REVIEW_CHECKLIST_LINE` before heredoc; empirically validated) + DA1 MANIFESTO `/loop` external-caller clarification + F2 CHANGELOG Notes 4→5-template scope + section heading `## Pending review` → `## Review status`\n- Pre-merge gates Step 0.7/0.8 clean — `Refs #102` trailer at line 1, `closingIssuesReferences` empty, per-commit trap regex 0 hits across 5 commits\n- Deferred findings → **#108** scope extended (F3 Phase 4 stdout `--review`-aware + Trace 1 example refresh + DA3 wording precision)\n- Implementation complete on `idd/102-acceptance-review-doctrine` → PR **[#109](https://github.com/PsychQuant/issue-driven-development/pull/109)** (5 commits, +140/−14 across 5 files); plugin bumped to v2.65.0\n- Implementation Plan approved via EnterPlanMode 2026-05-20; ([Implementation Complete](https://github.com/PsychQuant/issue-driven-development/issues/102#issuecomment-4493184518))\n- Plan re-routed Spectra → Plan via `/spectra-discuss` (2026-05-19 conclusion at [issue-comment-4486107094](https://github.com/PsychQuant/issue-driven-development/issues/102#issuecomment-4486107094))\n- Direction A (3-tuple `(path, interaction, acceptance)`) and most of Direction B (merge-time gate) killed by discuss; what ships is doctrine + thin flag\n- IDD's human-in-the-loop is the NSQL Confirmation Protocol; `verify-gated` is the terminal default disposition; `--review` is opt-in re-open, NOT a quality gate\n\n### Scope Changes\n- (none — implementation ships exactly what the discuss conclusion + Implementation Plan specified)\n\n### Blocking\n- (none — PR #109 ready for merge → `/idd-close #102`)\n\n### Commits\n- `dc61ffb` fix(idd-all-chain): ${VAR:-word} mutex bug + doctrine /loop clarification + CHANGELOG chain-flow.md note (Refs #102)\n- `8a41ee7` chore: bump issue-driven-dev to v2.65.0 (Refs #102)\n- `11a99e0` feat(idd-all-chain): add --review flag propagation + Phase 4/PR body conditional wording (Refs #102)\n- `1fdcba0` feat(idd-all): add --review flag + Phase 6 verify-gated terminal wording (Refs #102)\n- `4aef425` feat(MANIFESTO): add Human-in-the-loop / NSQL Confirmation Protocol doctrine (Refs #102)---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-20 by idd-close\n\n### Key Decisions\n- PR #109 squash-merged to main as `030fe7c` (5 commits collapsed; 5 plugin files +140/−14); plugin v2.65.0 lands in main\n- Closing summary posted [#issuecomment-4493811388](https://github.com/PsychQuant/issue-driven-development/issues/102#issuecomment-4493811388) — 5-section format (Problem / Root Cause / Solution / Verification / Changes)\n- 6-AI verify on PR #109 → PASS post-fix (1 HIGH F1 mutex bug caught by 3-source convergence; fixed in-PR `dc61ffb`); pre-merge gates Step 0.7/0.8 clean\n- In-PR polish `dc61ffb` — F1 mutex fix (explicit if/else) + DA1 MANIFESTO `/loop` external-caller clarification + F2 CHANGELOG 5-template scope + section heading `Pending review` → `Review status`\n- Sister consistency family **#108** extended to 5-template + 3 satellite items (F3 / Trace 1 / DA3) — covers `idd-implement`/`idd-all`/`pr-flow.md`/`chain-flow.md` + `idd-all-chain` Phase 4 stdout + idd-all `Trace 1` example + DA3 wording precision\n- Plan re-routed Spectra → Plan via `/spectra-discuss` (Direction A killed; doctrine + thin flag remained)\n- IDD's human-in-the-loop is the NSQL Confirmation Protocol; `verify-gated` is the terminal default disposition; `--review` is opt-in re-open, NOT a quality gate\n- Autopilot auto-merge mechanics → **#37** (this PR ships the doctrine; #37 ships the mechanic)\n\n### Scope Changes\n- (none — closing scope matches discuss conclusion + Implementation Plan)\n\n### Blocking\n- (none — closed)\n\n### Commits\n- `030fe7c` [enhancement] acceptance-review 缺在 IDD mode model — 「人不 review」需要 first-class 做法 (#109) [squash of `4aef425` + `1fdcba0` + `11a99e0` + `8a41ee7` + `dc61ffb`]" }, { "number": 103, @@ -166,7 +183,8 @@ "- (none — PR #104 ready for merge → `/idd-close #103`)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Original directive** (Che, 2026-05-19): 「根據這個新的專案來更新 idd」 —— 具體為「IDD 裡面的 human in the loop 應該要符合 NSQL 的原則」。\n\nNSQL ([kiki830621/NSQL](https://github.com/kiki830621/NSQL), now v4.1.0 — registered as a reference project in this repo's `CLAUDE.md`) is the Human-AI Confirmation Protocol that IDD's human-in-the-loop should conform to.\n\nNSQL v4.1.0's model: a request triggers a **dryrun** — the AI renders \"what I would do\" without committing — which branches on two properties of that dryrun:\n\n- **clarity** — exactly one interpretation?\n- **reversible** — is a mistake recoverable?\n\n```\nclear and reversible -> run, then report (\"traceable\")\nclear and not-reversible -> confirm\nnot-clear -> disambiguate\n```\n\nNSQL principles: **P1** Read-Only for Humans (humans confirm/correct, never write), **P2** Explicit over Implicit, **P3** Dynamic Confirmation Loop.\n\nAn audit of IDD's human-in-the-loop touchpoints against NSQL (2026-05-19) found IDD is **~80% already conformant** — `idd-plan` EnterPlanMode and the AskUserQuestion checkpoints (Layer V 3-option, sister-concern, IC_R011) are textbook \"AI renders -> human confirms / picks\".\n\n## Type\n\nfeature (IDD methodology)\n\n## Expected\n\nIDD's human-in-the-loop touchpoints are explicitly reconciled to NSQL's confirmation protocol — the conformant ones documented as such, the non-conformant ones fixed. A **surgical reconciliation, not a redesign**: IDD *contains* an NSQL-shaped confirmation loop (its front half — `issue` + `idd-diagnose` + complexity routing), it is not itself an NSQL extension.\n\n## Actual\n\nIDD has never been audited against NSQL's protocol. Known non-conformances for `idd-diagnose` to verify and scope:\n\n1. **`idd-issue` has no dryrun / confirm step** — it renders the structured issue and creates it without showing the rendering for the human to confirm or correct (violates P3 confirm-before-commit; should at least dryrun -> disambiguate-if-unclear -> report).\n2. **`idd-diagnose` Layer V \"clarify now\" makes the human write** free-text answers — NSQL P1 says the AI should render candidate interpretations and the human picks / corrects.\n3. **IDD diagnosis has no `residue` concept** — the part of an issue's intent that cannot be operationalized (its horizon / purpose) is never explicitly marked (NSQL section 4.6).\n4. **IDD complexity routing (Simple / Plan / Spectra) gates on clarity-of-complexity, not on reversibility** — NSQL's traceability gate says an irreversible change should confirm regardless of how \"Simple\" it looks; Layer P \"risk-sensitive boundary\" only partially covers this.\n\n## Impact\n\n- Affected surfaces: `skills/idd-issue/`, `skills/idd-diagnose/` (Layer V), the complexity-routing rule (`rules/sdd-integration.md`), possibly `MANIFESTO.md`.\n- Related: #102 (acceptance-review / verify-gated — already established IDD's human-in-the-loop maps to the NSQL confirmation loop).\n- Reference protocol: [kiki830621/NSQL](https://github.com/kiki830621/NSQL) — see `CLAUDE.md` \"Reference Projects\".---\n\n## Current Status\n\n**Phase**: verified\n**Last updated**: 2026-05-20 by idd-verify\n\n### Key Decisions\n- 6-AI verify on PR #104 → PASS (0 blocking; 2 LOW polish + 4 INFO follow-ups); pre-merge gates Step 0.7/0.8 clean — see [verify master](https://github.com/PsychQuant/issue-driven-development/pull/104#issuecomment-4490290903)\n- In-PR polish committed `bcdb3a0` — Layer V option description (idd-diagnose:281 + sdd-integration.md:64) realigned to candidate-render handler; Residue `(none)` requirement promoted to `>` paragraph\n- 3 follow-up issues filed: #105 (idd-close Residue acknowledgement) #106 (plugin.json description chain via plugin-update) #107 (idd-issue Step 5 echo CI/loop warning)\n- Implemented F1–F4 on branch `idd/103-nsql-conformance` → PR #104; plugin bumped to v2.64.0\n- Implementation Plan approved via EnterPlanMode; Complexity re-routed Spectra → Plan\n- F1 = report-echo (not a gate); F2 = Layer V renders candidates; F3 = residue field; F4 = Layer P wording\n- #102 owns the MANIFESTO doctrine; #103 references it\n\n### Scope Changes\n- (none)\n\n### Blocking\n- (none — PR #104 ready for merge → `/idd-close #103`)\n\n### Commits\n- `bcdb3a0` fix: align Layer V option description + Residue (none) emphasis (Refs #103)\n- `71d1044` chore: bump issue-driven-dev to v2.64.0 (#103)\n- `a747c34` feat: reconcile IDD human-in-the-loop touchpoints to NSQL (#103)---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-20 by idd-close\n\n### Key Decisions\n- PR #104 squash-merged to main as `675d7ba` (3 commits collapsed; 5 plugin files +27/−10); plugin v2.64.0 lands in main\n- Closing summary posted [#issuecomment-4490409449](https://github.com/PsychQuant/issue-driven-development/issues/103#issuecomment-4490409449) — 5-section format (Problem / Root Cause / Solution / Verification / Changes) per IDD discipline\n- 6-AI verify on PR #104 → PASS (0 blocking; 2 LOW polish + 4 INFO follow-ups); pre-merge gates Step 0.7/0.8 clean — [verify master](https://github.com/PsychQuant/issue-driven-development/pull/104#issuecomment-4490290903)\n- In-PR polish `bcdb3a0` — Layer V option description (idd-diagnose:281 + sdd-integration.md:64) realigned to candidate-render handler; Residue `(none)` requirement promoted to `>` paragraph\n- 3 follow-up issues filed: #105 (idd-close Residue acknowledgement) #106 (plugin.json description chain via plugin-update) #107 (idd-issue Step 5 echo CI/loop warning)\n- Implementation Plan approved via EnterPlanMode; Complexity re-routed Spectra → Plan\n- F1 = report-echo (not a gate); F2 = Layer V renders candidates; F3 = residue field; F4 = Layer P wording\n- #102 owns the MANIFESTO doctrine; #103 references it\n\n### Scope Changes\n- (none)\n\n### Blocking\n- (none — closed)\n\n### Commits\n- `675d7ba` IDD human-in-the-loop should conform to the NSQL confirmation protocol (v4.1.0) (#104) [squash of `a747c34` + `71d1044` + `bcdb3a0`]" }, { "number": 105, @@ -175,7 +193,8 @@ "- (none — ready for /idd-plan #105 (per chain shell unattended, idd-plan EnterPlanMode auto-applies))" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Source**: surfaced during `/idd-verify --pr 104` Devil's Advocate review of #103 (Finding D2, INFO severity).\n> Full verify report: https://github.com/PsychQuant/issue-driven-development/pull/104#issuecomment-4490290903\n\n#103 added `### Residue` to the Diagnosis report template (NSQL §4.6 — non-operationalizable intent / horizon). Producer: `idd-diagnose` Step 3 template. **Consumer: nobody**.\n\nVerified via grep of `skills/idd-*/SKILL.md` — `idd-implement` / `idd-verify` / `idd-close` / `idd-list` / `idd-update` / `idd-all` all read other Diagnosis sections (Strategy / Risks / Complexity / Implementation Complete) but none read `### Residue`.\n\nIn v2.64.0, Residue is **write-only**: AI writes it during diagnose, nobody reads it during implement/verify/close.\n\n## Type\n\nenhancement (latent ritual-drift risk)\n\n## Expected\n\nResidue has a downstream consumer that pressures it to stay honest. Specifically: `idd-close` reads `### Residue` from the latest Diagnosis comment and prompts the user — *\"Did any residue become operationalizable during this work? If so, file as new issue.\"*\n\nThis closes the loop: residue declared at diagnosis time becomes either (a) acknowledged still-residue at close, or (b) a follow-up issue filed because the work surfaced an angle for it.\n\n## Actual\n\n`### Residue` is declared at diagnosis and silently buried. No skill ever asks \"what happened to it?\". A future maintainer reading a closed issue can't tell whether the residue was deliberately deferred or just forgotten.\n\n## Impact\n\n- Affected surfaces: `skills/idd-close/` (new prompt at close time)\n- Related: PR #104 closes #103 with this gap acknowledged\n- Reference: NSQL §4.6 (kiki830621/NSQL)\n- Devil's Advocate's exact phrasing: \"latent capacity for the section to drift into ritual filler with no consumer pressure to keep it honest\"\n\nNot blocking #103's close. SHOULD-tier add: residue acknowledgement at close-time.\n---\n\n## Current Status\n\n**Phase**: diagnosed\n**Last updated**: 2026-05-20 by idd-diagnose\n\n### Key Decisions\n- Complexity = **Plan** (Layer V: V≤3, untriggered)\n- Strategy: 6 bullets covering new idd-close step + AskUserQuestion + audit trail\n- Plan-tier triggers: decision-heavy (4 design questions), close-time deliberation boundary, 2+ file sequence dependency\n- Sister concerns: none surfaced\n- Residue: per-issue residue granularity question (out of #105 scope)\n\n### Scope Changes\n- (none — diagnosed scope matches issue body)\n\n### Blocking\n- (none — ready for /idd-plan #105 (per chain shell unattended, idd-plan EnterPlanMode auto-applies))\n\n### Commits\n- (none yet)" }, { "number": 107, @@ -184,7 +203,8 @@ "- (none — ready for /idd-implement #107)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Source**: surfaced during `/idd-verify --pr 104` Codex review of #103 (regression note, INFO severity).\n> Full verify report: https://github.com/PsychQuant/issue-driven-development/pull/104#issuecomment-4490290903\n\n#103 PR #104 expanded `idd-issue` Step 5 prose: previously only output `issue number / URL / labels / type` metadata; now also echoes the AI-rendered `## Type` / `## Expected` / `## Actual` + plain-language interpretation (per F1 NSQL `run → report`).\n\nFor human readers this is strictly better — misparse is catchable without opening the issue URL.\n\nFor CI / `/loop` scripts that hard-parse Step 5 terminal prose, this is a silent surface change.\n\n`idd-issue` already has one CI-caller warning (v2.55.0 multi-finding auto-trigger): `skills/idd-issue/SKILL.md:994` warns \"`automated / CI / /loop` callers expecting the pre-v2.55.0 always-single-issue behavior of `idd-issue source.docx` MUST pass `--no-multi-finding` explicitly\". The v2.64.0 Step 5 echo expansion lacks an analogous warning.\n\n## Type\n\ndocumentation\n\n## Expected\n\n`skills/idd-issue/SKILL.md` Step 5 has a ⚠️ note for CI/loop callers, mirroring the v2.55.0 multi-finding warning shape:\n\n```\n> ⚠️ **CI / `/loop` callers (v2.64.0+)**: Step 5 terminal output expanded from\n> metadata-only (`number / URL / labels / type`) to also echoing the rendered\n> `## Type` / `## Expected` / `## Actual` + plain-language interpretation.\n> If your script hard-parses Step 5 output for the metadata fields only,\n> add a `-m 1` / first-N-lines guard or grep specifically for the\n> `issue.*#NNN.*created` line — the new echo paragraphs follow it.\n```\n\n## Actual\n\nNo warning. CI/loop scripts that did `idd-issue ... | grep '^Issue #'` or similar still work (the metadata line is preserved at the top); but scripts that did `idd-issue ... | tail -1` or naively parse the full output will see the new echo content mixed in.\n\nThe likelihood of breakage is low — most CI parsers anchor on the URL line. The cost of adding the warning is one paragraph. Defensive documentation, mirroring an existing precedent.\n\n## Impact\n\n- Affected surfaces: `skills/idd-issue/SKILL.md` Step 5 (one ⚠️ block addition)\n- Reference: existing precedent at `skills/idd-issue/SKILL.md:994` (the v2.55.0 multi-finding CI warning)\n- Verification: regression-test `idd-all` and `idd-all-chain` parsers — neither should rely on Step 5 prose (both consume the issue number from the URL line).\n\nNot blocking #103's close. Doc-polish follow-up.\n---\n\n## Current Status\n\n**Phase**: diagnosed\n**Last updated**: 2026-05-20 by idd-diagnose\n\n### Key Decisions\n- Complexity = **Simple** (Layer V: V≤3, untriggered)\n- Strategy: 1 bullet (insert ⚠️ paragraph in idd-issue Step 5 with verbatim wording from issue body)\n- Layer 1 disqualifier hit: primary deliverable is updating existing prose without changing behavior\n- Sister concerns: none surfaced\n- Residue: (none)\n\n### Scope Changes\n- (none — diagnosed scope matches issue body)\n\n### Blocking\n- (none — ready for /idd-implement #107)\n\n### Commits\n- (none yet)" }, { "number": 108, @@ -193,7 +213,8 @@ "- (none — ready for /idd-plan #108 (per chain shell unattended, idd-plan EnterPlanMode auto-applies))" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Source**: surfaced during `/idd-plan #102` Step 2.5 tangential sweep (PR will be on branch `idd/102-acceptance-review-doctrine` once filed).\n> Tracks the consistency family that the #102 narrow scope deliberately does not unify.\n\n#102 ships the NSQL Confirmation Protocol doctrine: **`verify-gated` is the terminal default disposition** — a clean 6/6 verify PASS is sufficient to merge; `--review` is an opt-in to re-open the confirmation loop, not a quality gate.\n\nPer the doctrine, the user-facing PR-body checklist line currently reading `- [ ] **Pending: human review of this PR + /idd-close after merge**` should become `- [x] **Verify-gated**: cluster/PR verify PASS — ready to merge` by default, with `--review` flipping it to `- [ ] **Pending: human acceptance review** (per --review flag)`.\n\n#102 only updates this for **idd-all-chain** Phase 5 (line 553). Three sister files keep the old wording:\n\n| File | Line | Status |\n|------|------|--------|\n| `plugins/issue-driven-dev/skills/idd-implement/SKILL.md` | 503 | OLD wording |\n| `plugins/issue-driven-dev/skills/idd-all/SKILL.md` | 746 | OLD wording |\n| `plugins/issue-driven-dev/references/pr-flow.md` | 135 | OLD wording |\n\nResult: post-#102, 4 PR-body templates that *should* all read the same now have a 1-vs-3 split. Doctrine is unified, surface is not.\n\n## Type\n\ndocumentation (template family consistency)\n\n## Expected\n\nAfter this issue ships, all 4 PR-body templates use the same doctrine-aligned wording — default = `Verify-gated PASS — ready to merge`, with `--review` opt-in flipping to `Pending: human acceptance review (per --review flag)`.\n\n`idd-implement` is special: it does not currently accept `--review` (the flag lives on `idd-all` and `idd-all-chain`). Decision for this issue:\n\n- **Option A**: only the *default* wording changes for `idd-implement` (the `--review` opt-in only meaningful when invoked via orchestrator).\n- **Option B**: `idd-implement` also accepts `--review` and threads it into PR body template. Slightly larger surface but symmetric.\n\nRecommend **Option A** unless there's a need to invoke `idd-implement` directly with `--review`.\n\n## Actual\n\n- `idd-all-chain` Phase 5 PR body checklist: doctrine-aligned wording (conditional on `--review`).\n- `idd-implement` Step 5.5 PR body checklist: old wording (`Pending: human review`).\n- `idd-all` Phase 5 PR body checklist: old wording (`Pending: human review`).\n- `references/pr-flow.md` canonical: old wording (`Pending: human review`).\n\n## Impact\n\n- Affected surfaces: 3 templates (`idd-implement/SKILL.md` line 503, `idd-all/SKILL.md` line 746, `references/pr-flow.md` line 135).\n- Affected users: anyone who reads PR descriptions assumes the checklist wording reflects IDD's actual review doctrine. Stale wording invites confusion: \"Is human review still pending? But verify already passed.\"\n- Related: #102 (doctrine source), #37 (autopilot auto-merge mechanics).\n\n## Notes\n\nNot blocking #102 merge — the 1-vs-3 split is documented as a known follow-up in #102's Implementation Plan Out-of-scope section. Issue exists to make sure the cleanup actually happens.\n\n## Step 5.7 sister sweep update (added 2026-05-20 during /idd-implement #102)\n\nA 4th file in the consistency family surfaced during the implementation sweep:\n\n| File | Line | Status |\n|------|------|--------|\n| `plugins/issue-driven-dev/references/chain-flow.md` | 254 | OLD wording (`Pending: human review of cluster PR`) |\n\n`chain-flow.md` is the canonical contract reference for the chain shell algorithm — its PR body template should follow the same NSQL doctrine wording as the other 3 files. Scope of this issue updated **4-template → 5-template** consistency family.\n\nSource: surfaced during `/idd-implement #102` Step 5.7 sweep (PR #109).\n\n## /idd-verify --pr 109 follow-up additions (added 2026-05-20)\n\nThe 6-AI verify of PR #109 (which ships the #102 doctrine that motivates this issue) surfaced additional consistency items worth grouping into this same family follow-up rather than opening separate issues:\n\n### F3 — idd-all-chain Phase 4 final report stdout text\n\n- **Source**: regression review (LOW); also surfaced by Devil's Advocate adversarial angle 2 (\"messaging-only\" claim audit)\n- **Where**: `plugins/issue-driven-dev/skills/idd-all-chain/SKILL.md` Phase 4 final report block (the forest-tree printout + STOP message rendered to the chain orchestrator's terminal, distinct from the PR-body checklist that #102 PR #109 already made `--review`-aware in commit `dc61ffb`)\n- **What**: Phase 4's stdout report (forest tree + \"STOP — ...\" message) is currently not conditional on `$REVIEW_FLAG`. It still emits the same text under both default and `--review` invocations. PR-body is the audit artifact and is fixed; stdout is for the human watching the chain run.\n- **Action**: dispatch Phase 4 final-report text on `$REVIEW_FLAG` the same way Phase 6 of `/idd-all` does (`verify-gated PASS across cluster, ready to merge` default vs `verify-gated PASS — awaiting human acceptance (per --review)` variant)\n\n### Req cosmetic — stale Trace 1 example block in idd-all/SKILL.md\n\n- **Source**: requirements review (LOW cosmetic)\n- **Where**: `plugins/issue-driven-dev/skills/idd-all/SKILL.md` around lines 893-901 (`Trace 1` example documentation block)\n- **What**: example block still demonstrates the pre-v2.65 `Verify: PASS` + `Next: review PR, merge` wording. Functional Phase 6 report logic was swapped in `1fdcba0`, but the example narrative in the doc was not updated to match.\n- **Action**: refresh `Trace 1` example to show the new `Verify: verify-gated PASS` + `Next: merge` default + `--review` variant\n\n### DA3 — \"messaging-only\" wording precision\n\n- **Source**: Devil's Advocate review (INFO)\n- **Where**: idd-all + idd-all-chain Phase 0 args parsing comments (both files), and MANIFESTO Human-in-the-loop section\n- **What**: The phrase \"messaging-only\" is true at the orchestrator scope (the flag doesn't change skill execution or make the orchestrator wait), but humans + CI parsers downstream can react to the changed text differently — so it isn't messaging-only in the strict end-to-end sense.\n- **Action**: optional refinement to \"orchestrator-scope messaging-only\" or similar tightening — purely a clarity improvement, not a behavior fix\n\n### Updated scope of this issue\n\nOriginally: 4-template PR-body checklist wording sync.\nAfter Step 5.7: 5-template (added chain-flow.md:254).\nAfter this PR #109 verify: **5-template + 3 satellite follow-ups (F3 / Trace 1 example / DA3 wording)** — all share the theme \"NSQL doctrine consistency across the IDD documentation family\".\n\n(DA2 from PR #109 verify — logic reviewer's bash analysis process improvement — is intentionally NOT added here. It's a process observation about the verify reviewer pool itself, not a code fix.)\n---\n\n## Current Status\n\n**Phase**: diagnosed\n**Last updated**: 2026-05-20 by idd-diagnose\n\n### Key Decisions\n- Complexity = **Plan** (Layer V: V≤3, untriggered)\n- Strategy: 5 PR-body wording sync + 3 satellite items (F3 / Trace 1 / DA3) = 8 edit sites across 6 files\n- Plan-tier triggers: 2+ files sequence dependency, decision-heavy (Option A vs B + version bump strategy + Trace 1 rewrite scope), cross-file refactor without external contract change\n- Sister concerns: none surfaced\n- Residue: deeper Spectra-tier question — should PR-body fragment be factored into shared template? (out of #108 scope)\n\n### Scope Changes\n- (none — diagnosed scope matches issue body)\n\n### Blocking\n- (none — ready for /idd-plan #108 (per chain shell unattended, idd-plan EnterPlanMode auto-applies))\n\n### Commits\n- (none yet)" }, { "number": 116, @@ -202,7 +223,8 @@ "- 等 `/spectra-discuss` 對齊以下 open questions: acceptance metric proxy 怎麼定?jsonl schema(`verify-runs/<run_id>.jsonl`)欄位?phase 1/2/3 是否一次走完還是逐 phase ship?" ], "expect_empty": false, - "expect_first_blocker": "- 等 `/spectra-discuss` 對齊以下 open questions: acceptance metric proxy 怎麼定?jsonl schema(`verify-runs/<run_id>.jsonl`)欄位?phase 1/2/3 是否一次走完還是逐 phase ship?" + "expect_first_blocker": "- 等 `/spectra-discuss` 對齊以下 open questions: acceptance metric proxy 怎麼定?jsonl schema(`verify-runs/<run_id>.jsonl`)欄位?phase 1/2/3 是否一次走完還是逐 phase ship?", + "body": "## Problem\n\n> **Original text** (User report):\n> 「有人反映說會有大量的通知很annoying」\n>\n> **Follow-up design idea**:\n> 「我在想每一個issue都要分成human, ai 看的，只有human看的要發通知？這可以做到嗎」\n> — Source: /idd-issue clarifying dialog, 2026-05-20\n\nIDD workflow 在單一 issue 上會 post 大量 comment(diagnose / verify / update / sister sweep / linked-context / close summary…),每個 comment 都會觸發 GitHub notification(issue 訂閱者、被 @mention 的人、assignee)。實際使用者反映這個量級到「annoying」的程度 — 訂閱者收到一堆「AI 跟 AI 之間互看」的 comment,human 沒有 actionable 意圖。\n\n使用者提出的 design proposal:\n- 把 issue 上的 comment 分流成「給 human 看的」vs「給 AI 看的」\n- **只有給 human 看的**才觸發 GitHub notification\n- 給 AI 看的 (process / audit trail) 留在 issue 但 mute\n\n## Type\n\nfeature(含 open design question:技術上能否做到 selective notification)\n\n## Expected\n\n- 使用者訂閱 issue 後,只收到對 human 有 decision value 的 notification(例:`idd-diagnose` 完成等待 review、`idd-verify` 發現 blocker、closing summary)\n- AI 之間的 process comment(每個 verify agent 的 raw output、idempotency check 紀錄、sister sweep 報告)仍寫進 issue 做 audit trail,但**不**觸發 notification\n\n## Actual\n\n目前每個 IDD skill post 的 comment 都會走 GitHub 預設 notification 機制 — 所有 issue 訂閱者、被 ref 的 user、assignee 都會被 ping,無差別。一個 issue 跑完 `/idd-all` 可能產生 5-15 個 comment,全部都會推給 human。\n\n## Open question(待 diagnose 階段釐清)\n\n1. **GitHub 端是否支援 selective mute**?可能方案:\n - 用 hidden HTML comment 或特殊 marker → user 自己設 notification filter\n - 改用 `gh api` 直接 PATCH issue body 取代 `gh issue comment`(edit 不發 notification,但失去時間軸)\n - AI process log 改寫到 separate place(`.claude/.idd/issue-runs/*.jsonl` 已有 audit trail,issue 上只留 human-facing summary)\n - GitHub native: subscription type / mention pattern 控制\n2. **哪些 comment 該分成「AI-only」**?需要 inventory 各個 idd-* skill 的 comment pattern\n\n## Impact\n\n- **Adoption blocker**:notification fatigue 會讓使用者直接 unsubscribe issue 或關掉 IDD,等於放棄 audit trail\n- **Collaboration cost**:被 `@mention` 拉進 issue 的 collaborator 體驗更差(他們對 AI 流程沒有 context)\n\n## Priority\n\nP1 — 本週\n\n## Vagueness assessment\n\n- V1 (vague WHAT) = 3 — 改善方向清楚(減少非必要通知),但具體拆分標準未定\n- V4 (vague ACCEPTANCE) = 4 — done criteria 還沒明確;需要 diagnose 階段先回答 open question 1 才能寫出 testable acceptance\n\n### Linked-Context Siblings Filed (v2.48.0+ #529)\n\n(none — no orphan sibling mentions in linked context)\n\n---\n\n## Current Status\n\n**Phase**: diagnosed\n**Last updated**: 2026-05-21 by idd-diagnose\n\n### Key Decisions\n\n- 開放問題 1 已解答:GitHub **不**支援 author-side selective mute,但 author-side **reduce** 完全可行(`gh issue edit --body` PATCH 不觸發 notification、`gh api PATCH /issues/comments/:id` 不觸發 notification、jsonl 落地完全離 issue)\n- Receiver 分類標準已定:human-facing = Diagnosis Report 完成 / final verify verdict / closing summary / user-initiated comment;AI-only = `idd-verify` raw agent output / audit trail PATCH / sister concern surfacing 記錄\n- Strategy 採 3-phase rollout: Phase 1 `idd-verify` consolidation(highest leverage,獨立可上)→ Phase 2 全 skill comment-vs-body PATCH 紀律 audit + `notification-discipline.md` rule → Phase 3 measurement + opt-out env var\n- Complexity verdict = **Spectra**(Layer 2 published skill API + Layer 3 cross-spec impact + architectural decision 同時命中)\n- Routing 決定: 走 spectra-discuss(default)先對齊 acceptance metric / jsonl schema / rollout 順序\n\n### Scope Changes\n\n- Sister concerns filed #117(@mention audit gap in AI-generated comments,latent bug)+ #118(issue body archival 策略,QoL refactor)— 不納入 #116 scope\n\n### Blocking\n\n- 等 `/spectra-discuss` 對齊以下 open questions: acceptance metric proxy 怎麼定?jsonl schema(`verify-runs/<run_id>.jsonl`)欄位?phase 1/2/3 是否一次走完還是逐 phase ship?\n\n### Commits\n\n- (none)\n" }, { "number": 119, @@ -211,7 +233,8 @@ "- (none)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Original report** (paste from Claude Code session, 2026-05-21):\n>\n> ```\n> ❯ /issue-driven-dev:idd-all-chain 14 個 issues\n>\n> ⏺ /idd-all-chain 的 args 是「14 個 issues」(非 #NNN tokens)。讓我先建 stage task list,\n> 然後跟你確認 — 因為這裡有幾個重要的 design constraint 需要先處理。\n>\n> ⏺ Phase 0 解析:/idd-all-chain \"14 個 issues\" 沒帶 explicit #NNN tokens。\n> 我推測你想 chain 剛剛建的 14 個(#795-#808)。\n>\n> 但這裡有 3 個 design constraint 嚴重不適合一次 chain 跑完,我必須先停下確認:\n>\n> ⚠ 不適合直接跑的理由\n>\n> 1. Hard cap 衝突: chain_max_issues = 10 (global), 你有 14 roots\n>\n> skill 文件明示 cap 是 hard-coded constant,not config-driven(see \"Configuration\" 區段)。\n> 跑下去會發生:14 個 roots seed 到 QUEUE,但 Phase 2 loop 在處理到第 10 個 root 時\n> trigger chain_max_issues=$CHAIN_MAX_ISSUES reached,剩下 4 個 roots(可能是 #805-#808)\n> 會被 \"filed only, not chained\" — 它們在 chain 開始時已經 OPEN 但根本不會被 chain 處理。\n>\n> 2. 14 個 roots 沒 diagnosis: Phase 0.4 預期會擋\n>\n> /idd-issue 剛建好的 14 個 issue 都還沒有 ## Diagnosis comment。Phase 0.4\n> check-diagnosis-readiness.sh 會回 not_ready=14,觸發 AskUserQuestion 3-option。\n>\n> 如果選 proceed anyway:14 個 issue body 都會被 PATCH 加「diagnosis bypassed」audit 區塊,\n> 然後 chain 跑時 sub /idd-all 內部會 unattended /idd-diagnose → Layer V 自動 proceed,\n> 完全跳過老師的人工 review/裁決。對這份文件這種「客戶建議 + 部分 supersede 既存\n> #406/#407」的情境,自動 diagnose 風險高(很可能會把 #804/#805 當獨立問題實作,沒考慮\n> 跟 #406/#407 的 supersede 關係)。\n>\n> 3. 5 個 P1 + 跨模組 BrandEdge/InsightForge/funnel — 不是同一 root 的 ripple\n>\n> /idd-all-chain 設計初衷是「root + 該 root 衍生的 sister bugs / spawn issues」單一 root\n> 的子樹。14 個 roots 彼此語意上是平行 sibling(都是同一份文件的不同要點),\n> 不是 ripple chain。塞進 multi-root chain 會產生:\n> - 多個 unrelated diff 在同一 PR(reviewer cognitive load 爆表)\n> - 一個 root verify FAIL → 該 root subtree halt,但其他 13 root 繼續 → 部分成功狀態,\n> squash merge 變棘手\n>\n> User answered: 先 batch /idd-diagnose 14 個，再決定下一步\n> ```\n\n— Source: user-pasted Claude Code session transcript, 2026-05-21\n\n實際 incident:user 對 14 個剛建的 sibling issues 跑 `/idd-all-chain`,被 skill 偵測 3 個 design constraint violations 攔下。三個面向都暴露 chain orchestration 設計問題,**不是** user 錯用 (sibling concerns are reasonable invocation pattern user expected to work)。\n\n## Type\n\nrefactor(含 bug-class silent behavior;主問題是 skill 設計缺陷,需重新評估 chain 機制的 invariants)\n\n## Three distinct facets(同 root cause:chain mental model 與實際 use case 對不上)\n\n### Facet A: `chain_max_issues = 10` hard-coded(不能 config override)\n\n- 現況: cap 寫死成 constant,user 即使知道工作量有 14 也不能放寬\n- 痛點: 第 11-14 個 root 進 QUEUE 但被 silent truncate 成 \"filed only, not chained\" — 等於用 skill 但只完成 70% 工作\n- 設計問題: cap 是 safety guard 還是 hard invariant?如果是 safety guard 應該 config-driven;如果是 invariant(防止 chain 過大導致 cluster branch 不可 review)應該在 Phase 0 就 reject 不是 silent truncate\n\n### Facet B: Multi-root 與 ripple-chain 混淆無 pre-flight 警告\n\n- 現況: skill 設計初衷是 ripple chain (root + sister bugs from same subtree),但介面允許 N 個 unrelated roots 一起傳入\n- 痛點: User 自然會把「我有 14 個相關 issue」當成 chain 的合理 input,但實際語意是 N parallel batches 而非 1 chain → 同 PR 出現 14 個 unrelated diff\n- 設計問題: 缺 pre-flight 偵測 — 應該掃 input roots 看是否有 cross-reference / sister-spawn relation,沒 ripple structure 就 AskUserQuestion 警告「這些看起來不是同一 root subtree,建議用 batch /idd-all 而非 /idd-all-chain」\n\n### Facet C: Cap 超過時 silent \"filed only, not chained\" 行為\n\n- 現況: Phase 2 loop 處理到第 N=cap 個 root 時 break,剩下 roots 仍 OPEN 但不被 chain 處理\n- 痛點: User 從 skill output 看不出第 11-14 個沒被處理(silent truncate);需 grep 文件才知道 cap 機制存在\n- 設計問題: silent truncate 是「irreversible side effect」failure mode(per #103 F4 Layer P vocabulary)— 應該在 Phase 0 就 fail-fast,印 `✗ refuse: N roots exceeds chain_max_issues=10, narrow scope or split chain`\n\n## Expected\n\n1. cap 是 config-driven (例如 `chain_max_issues` 進 `.claude/issue-driven-dev.local.json`),user 可放寬到 work 範圍\n2. Phase 0 pre-flight 偵測 multi-root(N≥2)且 roots 缺 cross-reference 時 AskUserQuestion 警告,提供 `proceed anyway` / `switch to batch /idd-all` / `abort` 3-option\n3. Cap 超過時 **fail-fast refuse**,不 silent truncate;error message 列出哪些 roots 會被排除 + 提示如何 split\n\n## Actual\n\n1. Cap hard-coded,user 無覆寫機制\n2. Pre-flight 只擋 diagnosis-readiness(Phase 0.4),不擋 multi-root semantic misuse\n3. Cap 超過時 silent truncate,user 不知 #11-14 沒被 chain\n\n## Impact\n\n- **Today-blocker**: 14-issue batch 無法走 chain,user 退回手動 batch `/idd-diagnose` + 一個個 implement\n- **Silent data loss UX**:user 信任 skill 跑完代表 14 個都處理了,實際只處理 10 個 — 4 個被丟在 OPEN 狀態,後續需手動補\n- **Mental model 漂移**:user 把「ripple chain」誤用為「batch executor」,設計者意圖跟使用情境長期不對齊,設計沒人 update 對應的 use case\n- **PR review 爆表**:若 user 沒被擋,14 unrelated diffs 在同 PR,reviewer cognitive load 嚴重\n\n## Priority\n\nP1 — 本週(實際工作流被擋,workaround 手動 batch 很痛)\n\n## Vagueness assessment\n\n- V1 (vague WHAT) = 2 — 3 facets 都明確;改動方向具體(config-driven cap / pre-flight check / fail-fast)\n- V4 (vague ACCEPTANCE) = 3 — 大方向清楚但具體 cap default 值(10? 30? 50?)、pre-flight rule 細節(怎麼判定 \"ripple structure\")需 design 階段釐清\n\n### Linked-Context Siblings Filed (v2.48.0+ #529)\n\nFiled sibling issues: #120, #121\n\n- #120 — Layer V Vagueness Pre-check 在 /idd-all unattended mode silent skip(latent bug,影響所有 unattended chain 不只本 issue)\n- #121 — Cluster branch squash merge 對 multi-root 不友善(git workflow refactor,正交於 chain orchestration)\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-21 by idd-close\n**Closed at**: 2026-05-21T12:15:18Z\n**Closing summary**: [comment-4508164558](https://github.com/PsychQuant/issue-driven-development/issues/119#issuecomment-4508164558)\n\n**Lifecycle**:\n- Implementation Plan: [comment-4504690667](https://github.com/PsychQuant/issue-driven-development/issues/119#issuecomment-4504690667)\n- Implementation Complete: [comment-4504792852](https://github.com/PsychQuant/issue-driven-development/issues/119#issuecomment-4504792852)\n- Verify R1 (FAIL): [comment-4504873746](https://github.com/PsychQuant/issue-driven-development/issues/119#issuecomment-4504873746)\n- Verify R2 (PASS): [comment-4507191109](https://github.com/PsychQuant/issue-driven-development/issues/119#issuecomment-4507191109)\n- Closing summary: [comment-4508164558](https://github.com/PsychQuant/issue-driven-development/issues/119#issuecomment-4508164558)\n\n### Key Decisions\n\n- **Closed as shipped**: 2 commits (cb96579 + 7aa11ea) deliver Phase 0.4.5 fail-fast preflight + workflows.md A3 cite + Configuration cap guardrail wording + Failure mode table row\n- 完整 lifecycle: created → diagnosed → planning → implemented → needs-fix → implemented (re-fix) → verified → closed\n- Round-1 verify FAIL caught Phase 0.4.5 placebo gate (F1+F2+F3); fix commit 7aa11ea resolved all 3\n- Round-2 verify PASS 6-AI consensus (with DA self-review fallback due to socket crashes — Process Gap noted, surfaced #130)\n- Distribution sync: chain to /plugin-tools:plugin-update issue-driven-dev (user-facing skill behavior change)\n\n### Scope Changes\n\n- (none — strict adherence across 2 commits)\n\n### Blocking\n\n- (none)\n\n### Commits\n\n- `cb96579` — refactor(idd-all-chain): Phase 0.4.5 fail-fast cap-exceeded preflight + A3 cite (#119) [shipped F1+F2+F3 bugs]\n- `7aa11ea` — fix(idd-all-chain): Phase 0.4.5 use ROOT_ISSUES_SORTED + hoist CHAIN_MAX_ISSUES + abort (#119) [resolves R1 F1+F2+F3]\n\n### Closing Follow-ups Filed\n\n- **#130** — /idd-verify DA Agent role 2x socket crashes (round-2 verify process gap)\n- **#131** — Cognitive-load proxy metric for A3 anti-pattern effectiveness measurement (residue item 1)\n- **#132** — Phase 2 silent-truncate backward compat deprecation policy (residue item 2,likely moot)\n\n### Distribution Sync\n\n- chain to `/plugin-tools:plugin-update issue-driven-dev`(invoked)\n" }, { "number": 121, @@ -220,7 +243,8 @@ "- (none)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n從 #119 sister sweep 浮出: `/idd-all-chain` 設計把 N 個 root issue 共用 **1 個 cluster branch + 1 個 review PR**,期望最終 squash merge 進 main。當 N>1 且 roots 之間語意上是 parallel siblings(不是 ripple chain),squash merge 出問題:\n\n1. **Squash 摺成 1 commit message**:14 個 unrelated changes 只有一條 commit message,git log 失去「哪個 commit 改了哪個 issue」的軌跡 — 違反 `Refs #N` 紀律\n2. **Revert 粒度 = 全部**:某個 issue 後來發現要回退,squash 後只能整批 revert,炸到其他 13 個 issue\n3. **Bisect 失準**:`git bisect` 找回歸 commit 時 N issue 都疊在一個 squash commit,bisect 結果只說「這 14 issue 中某個破事」沒辦法精準\n4. **Review cognitive load**:reviewer 看 1 個 PR 含 14 個 unrelated 主題的 diff,容易漏 bug\n\n替代方案考量:\n- 改 merge strategy 為 `--no-ff` merge commit 保留 N 個原 commit → 但 PR 已 squash 默認,需專案 policy\n- 切成 N 個 PR(回到 batch /idd-all 模式)→ 失去 cluster 的省 PR 開銷\n- 中間方案:cluster branch 但 push N 個 commit 後 cherry-pick 拆 N 個 sub-PR? overhead 大\n\n## Type\nrefactor(merge strategy + cluster branch 設計問題)\n\n## Expected\n\n`/idd-all-chain` 文件 / behavior 對「N roots merge 進 main 後續 git operations」有明確處理:\n- 預設 merge strategy(squash vs merge commit)\n- 警告 user 若 squash 預設與 multi-root 不相容\n- 或 cluster mode 只允許 ripple chain(per #119 Facet B 收緊),不允許 multi-root → 從根本上避免 squash 問題\n\n## Actual\n\n無明確 merge strategy 指引,user 跑 `gh pr merge --squash` 後遇到上述 4 個 git workflow 痛點。\n\n## Source\n\nsurfaced during /idd-issue #119 sister concern surfacing (Step 4.7)\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-21 by idd-close\n**Closed at**: 2026-05-21T03:55:16Z\n**Closing summary**: [comment-4504642552](https://github.com/PsychQuant/issue-driven-development/issues/121#issuecomment-4504642552)\n\n### Key Decisions\n\n- Closed as **absorbed-into-docs**(per user decision 2026-05-21)\n- Resolution path = doc reframing(commit 92e82c2 `docs: introduce workflow path catalog + skill dimensions`)not code fix\n- 4 痛點已被 `docs/workflows.md` P-cluster-pr Risks 段落 + Anti-pattern A4 顯式 cover\n- Distribution sync = not applicable(docs-only at repo root,不影響 plugin behavior)\n\n### Scope Changes\n\n- (none — 原 issue scope 不變,但 disposition 從「code refactor 待做」改為「doc absorption 完成」)\n\n### Blocking\n\n- (none)\n\n### Commits\n\n- `92e82c2` docs: introduce workflow path catalog + skill dimensions\n- `e827bc7` docs: update cross-refs after migrating 6 IDD issues from marketplace\n\n### Closing Follow-ups Filed\n\n- Skipped per user(closing summary 含 conditional hypothetical「若未來真要做 cluster default merge strategy refactor,將另開 follow-up issue」,not committed TODO)\n" }, { "number": 125, @@ -229,7 +253,8 @@ "- (none) — closed" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Original observation** (conversation with Claude on 2026-04-16)：\n> 「idd 應該要用 TaskCreate 來保證所有事情都要做到，是不是漏掉了」\n\nIDD plugin 裡的 skill 有個核心紀律：**Step 0 Bootstrap Stage Task List — 用 `TaskCreate` 把每個 sub-step 建進 todo，確保沒有靜默跳過**。\n\n但 audit 發現 10 個 idd-* skill 裡 **5 個完全沒有 Step 0 Bootstrap**。這導致它們的步驟沒被追蹤，容易被跳過：\n\n| Skill | Steps | TaskCreate Bootstrap | 狀態 |\n|-------|-------|----------------------|------|\n| idd-close | 0-7 | ✓ 6 tasks | 剛在 2.18.1 補好 |\n| idd-issue | 0-5 | ✓ 6 tasks | ✓ |\n| idd-diagnose | 0-4 | ✓ 5 tasks | ✓ |\n| idd-implement | 0-5 | ✓ 6 tasks | ✓ |\n| idd-verify | 0-5 | ✓ 7 tasks | ✓ |\n| **idd-comment** | 1-5 | **✗ 無** | 🔴 缺 |\n| **idd-edit** | 1-7 | **✗ 無** | 🔴 缺 |\n| **idd-list** | 1-5 | **✗ 無** | 🔴 缺 |\n| **idd-report** | 1-9 | **✗ 無** | 🔴 缺 |\n| **idd-update** | 1-6 | **✗ 無** | 🔴 缺（最諷刺：它 Step 6 就叫「靜默完成」） |\n\n特別諷刺的是 `idd-update`：它自己被 `idd-close` Auto-Update 步驟呼叫，且 `idd-close` 2.18.1 剛把 Auto-Update 升格為強制 Step 6，但 `idd-update` 本身的執行步驟沒 TaskCreate 追蹤 — 所以即使被呼叫了，它裡面的 6 個 step 仍可能靜默跳過某步。\n\n## Type\n\nrefactor\n\n## Expected\n\n5 個 skill（idd-comment, idd-edit, idd-list, idd-report, idd-update）都加上 `### Step 0: Bootstrap Stage Task List（強制)` 區段，涵蓋該 skill 所有 documented steps：\n\n```\nTaskCreate(name=\"<step_1_name>\", description=\"<Step 1 做什麼>\")\nTaskCreate(name=\"<step_2_name>\", description=\"<Step 2 做什麼>\")\n...\n```\n\n並在該 Step 0 後加固定結尾：\n> 完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。\n\n每個 skill 的 Step 0 TaskCreate 清單必須**涵蓋該 skill 所有 documented steps**，遺漏 = bug。\n\n## Actual\n\n5 個 skill 目前直接從 Step 1 開始，沒有 bootstrap。跑這些 skill 時 Claude 不會建 task list，所以：\n\n- 不會有 UI 顯示步驟進度\n- 跳過某步不會被系統發現\n- 使用者要盯著每一步做沒做\n\n這違反了 IDD 自己的設計原則（「用 TaskCreate 強制追蹤」），屬於 plugin 自己沒 dogfood 自己的紀律。\n\n## Impact\n\n- **5 個 skill 的 SKILL.md** 各需新增 Step 0 區段\n- `plugins/issue-driven-dev/.claude-plugin/plugin.json`：2.18.1 → 2.19.0（minor，因為是一致性與紀律補強，不算 bug fix）\n- `.claude-plugin/marketplace.json`：同步版本號\n- 估計 ~50 行新增（每個 skill 平均 10 行）\n\n實際影響層面：\n- 所有使用 idd-comment / idd-edit / idd-list / idd-report / idd-update 的流程都多一層 task tracking（UI 可見性 +）\n- 沒有 breaking change：既有行為不變，只是多了 bootstrap 層\n\n## Design considerations（給 diagnose 階段參考）\n\n### A. TaskCreate 名稱規則\n\n參考 idd-close 2.18.1 已有的命名（snake_case，簡短動詞_名詞），每個 Step 對應一個 task：\n- Step 1 → 通常命名為 `parse_args`, `read_issue`, `fetch_body` 等\n- Step 2 → 驗證/收集類命名\n- 最後一步 → `report_and_stop` 或類似\n\n### B. 要不要加入「審計測試」？\n\n為避免以後新增 skill 又漏寫 Step 0，考慮在 CI 或 pre-commit 加一個簡單腳本：\n```bash\n# 檢查 plugins/issue-driven-dev/skills/*/SKILL.md 有沒有 ### Step 0: Bootstrap\n```\n\n這是 **nice-to-have**，不屬於本 issue 必做項，但應該在 diagnose 階段討論要不要順便做。\n\n### C. Step 0 vs Step 0.5 命名\n\n- idd-close 用 `Step 0.5`（因為 Step 0 是 Checklist Gate Check）\n- idd-issue / idd-diagnose / idd-implement 用 `Step 0`\n\n兩種都合理，看 skill 有沒有先於 bootstrap 的 gate step：\n- 有 gate → Step 0 是 gate，Step 0.5 是 bootstrap\n- 沒 gate → Step 0 直接是 bootstrap\n\n本次 5 個 skill 都沒有 gate，統一用 **Step 0**。\n\n### D. Complexity\n\n**Not SDD-warranted**（可直接實作）：\n- 只是 5 個 SKILL.md 加區段，無架構改動\n- 無 spec 影響（IDD 沒有 openspec/）\n- 無 API 改動\n- 各 skill 可獨立改、獨立測\n\n但**值得走 IDD 流程**（dogfood）：\n- diagnose 確認每個 skill 的 TaskCreate 清單正確覆蓋其 steps\n- implement 時一次改 5 個 skill + bump 版本 + deploy\n- verify 時重跑一次 audit 腳本確認 5 個都修好\n\n## Related\n\n- 這個 issue 是 idd-close 2.18.1 fix（commit `4762e64`）的 follow-up。\n- 2.18.1 fix 了 idd-close 自己的 Auto-Update Step 6 被漏掉問題\n- 這個 issue 把同樣的紀律紅利推廣到其他 5 個 skill\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-04-16 by idd-close (Step 6 Auto-Update — manual enforcement, session cached 2.18.0 doesn't have Step 6 yet)\n\n### Key Decisions\n- Scope B expansion confirmed: include idd-diagnose Auto-Update upgrade\n- Verify FAIL → Fix → Re-verify PASS cycle completed（6-AI panel round 1 + Codex round 2）\n- 2 HIGH findings convergent across 3 Claude reviewers + Codex — proved panel value\n- idd-close gate check surfaced 3rd-order flaw: stale draft checklist blocks close even when Implementation Complete is synced. Mitigated by batch-marking 35 checkboxes as [-] superseded\n\n### Scope Final\n- 5 skill bootstrap補齊 ✓\n- idd-diagnose Step 5 升格 ✓\n- audit script + hardening ✓\n- version 2.18.1 → 2.19.0 → 2.19.1 ✓\n\n### Blocking\n- (none) — closed\n\n### Commits\n- `5ed5c4e` refactor(idd): 補齊 5 skill 的 Step 0 Bootstrap + 升 idd-diagnose Auto-Update 為 Step 5 (#27)\n- `d84b1c1` chore: add audit_step0_bootstrap.sh to prevent regression (#27)\n- `9bacff8` fix(idd): PsychQuant/issue-driven-development#125 verify findings — idd-update Step 6 sync + audit regex hardening\n" }, { "number": 137, @@ -238,7 +263,8 @@ "- (none — issue closed)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Source\n\nsurfaced during /idd-diagnose #135 sister concern surfacing (Step 3.6)\n\n#135 diagnosis Risks table:\n> '/idd-all unattended mode 跟 Step 4.8 auto-invoke 衝突 | LOW | Step 4.8 emit annotation block(non-blocking),不 fire AskUserQuestion;unattended 自然繼續'\n\n#135 v3 design 的 unattended-mode interaction 仍有 open question:\n\n## Open questions\n\n- Unattended mode 下 `/idd-clarify` Step 4.8 auto-invoke 寫 `### Clarity Surface` block 用 status=`surfaced`(未 resolve)→ `idd-diagnose` Step 0.5 gate 看到 unresolved → refuse → unattended chain 中斷?\n- 或 unattended 應該自動 dismiss 所有 surfaced rows + 寫 audit `auto-dismissed (unattended)`?\n- /loop / /idd-all-chain 等 cluster caller 對 partial-block 容錯?(一個 issue 卡住 surface,整個 cluster 是否該繼續?)\n- 與 IC_R010 / IC_R011 unattended fallback pattern 一致性\n\n## Type\nbug / meta — unattended-mode contract gap\n\n## Priority\nP2 — 必須在 #135 v3 implementation 期間同步 design 決定(否則 unattended caller 會 silent break)\n\nRefs #135\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-25 by /idd-update (via /idd-close)\n\n### Key Decisions\n- Path D adopted: reuse existing `deferred` enum + strict reason literal `unattended-auto-Step-4.6-deferred` cited from `rules/append-vs-modify.md` Reason pattern registry (single source of truth)\n- 3 SKILL.md cite registry (idd-clarify Step 4.8.A, idd-diagnose Step 0.5, idd-all Phase 6) — char-equal by construction\n- Non-BREAKING (legacy `deferred` rows behavior unchanged)\n- Cluster PR #153 (with #150)\n\n### Scope Changes\n- (none — Path D matches diagnose Plan tier scope; spectra-apply covered all 19 atomic tasks)\n\n### Blocking\n- (none — issue closed)\n\n### Commits\n- `b788a73` feat: #137 unattended Clarity auto-defer + #150 action-scoped modify discipline (cluster) — squash-merged from PR #153\n- PR commit chain (pre-squash): `5e3e263` initial impl → `d643fc6` R1 fixes → `5c62b38` R3 parser rewrite → `6749d57` Path c revert → `5965db7` R5 cleanup\n\n### Closing\n- Closing Summary: https://github.com/PsychQuant/issue-driven-development/issues/137#issuecomment-4531813260\n- Verify R6 PASS: https://github.com/PsychQuant/issue-driven-development/pull/153#issuecomment-4531737476 (Codex independent)\n- Follow-up #154 filed (idd-edit BREAKING runtime enforcement, deferred per Path c)\n" }, { "number": 147, @@ -247,7 +273,8 @@ "- (none)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n`idd-verify` 的 Codex reviewer 目前用 `codex exec --full-auto` subprocess 呼叫 Codex CLI:\n\n```bash\ncodex exec --full-auto -c 'model=\"gpt-5.5\"' -c 'model_reasoning_effort=\"xhigh\"' \\\n -c 'service_tier=\"fast\"' -o /tmp/codex-verify-$NUMBER.md \"...\"\n```\n\n姊妹 plugin `parallel-ai-agents`(v2.4.0+)已經把同樣的 codex 呼叫**從 subprocess 改寫成直接 HTTP wrapper** `bin/codex-call`,理由是 `codex exec` subprocess 偶爾會 hang(stdin/stdout pipe 互鎖、tty 問題),要等到 timeout 才能繼續。\n\n## Type\nrefactor\n\n## 現狀 vs 目標\n\n| 面向 | `codex exec`(idd-verify 現用) | `codex-call`(parallel-ai-agents 已用) |\n|------|------------------------------|--------------------------------------|\n| 執行模型 | Spawn `codex` CLI subprocess,stdin/stdout pipe 通訊 | Direct HTTPS POST 到 `chatgpt.com/backend-api/codex/responses` |\n| Hang 風險 | ⚠ pipe 互鎖 / tty 問題偶發 hang,等 10min timeout | 無 subprocess → 無 pipe 問題 |\n| `--max-time` 硬性保證 | ❌ CLI 不一定守 | ✅ HTTP timeout 強制 |\n| OAuth token refresh race | CLI 無 file lock,ensemble 平行 spawn 會 race | wrapper 有 `~/.codex/.token-refresh.lock` |\n| 產物 | `-o <path>` | `--output <path>` |\n\n## Expected\n\n`idd-verify` 的 Step 2b Codex invocation 改用 `codex-call`:\n- 把 `bin/codex-call`(Swift script)從 parallel-ai-agents 引入(copy / symlink / 共用安裝)\n- 改 `idd-verify/SKILL.md` 的 codex invocation block:`codex exec ...` → `codex-call --output ... --model gpt-5.5 --effort xhigh --service-tier fast --max-time 600`\n- OAuth 共用 `~/.codex/auth.json`(兩個 wrapper 同一份 token store)\n\n## Actual\n\n`idd-verify` 仍用 `codex exec` subprocess。實測中(2026-05-22 一次 `/idd-verify #31` run)Codex 那次沒 hang,但 subprocess 模型的 hang 是已知偶發風險,parallel-ai-agents 就是為此重寫的。\n\n## Impact\n\n- 影響檔案:`plugins/issue-driven-dev/skills/idd-verify/SKILL.md`(codex invocation block)+ 可能需要引入 `bin/codex-call`\n- 影響使用者流程:`/idd-verify` 的 6-AI ensemble 第 6 個 reviewer(Codex)更穩定,不會偶發卡 10 分鐘\n- 跨 plugin 協調:`codex-call` 的 source-of-truth 在 `parallel-ai-agents`,要決定 idd-verify 是 copy 一份、symlink、還是抽成共用 dependency\n- Priority: P3 — 現狀能跑,只是偶發 hang 風險;有空再做\n\n## Open questions\n\n- `codex-call` 要不要抽成獨立可共用的東西(避免兩個 plugin 各維護一份 Swift script)?\n- idd-verify 是否也想要 parallel-ai-agents 的 file-lock OAuth refresh(ensemble 平行跑多個 codex 時才有意義 — idd-verify 一次只跑 1 個 codex,race 風險較低)?\n\n---\n\n**Source**: surfaced during /idd-issue kiki830621/che-cheng-website#27 linked-context sister sweep (Step 4.7) — orphan mention from a 2026-05-22 Claude Code session discussing how parallel-ai-agents invokes Codex.\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-06-01 by idd-close\n\n### Key Decisions\n- Plan tier (Option A vendor, EnterPlanMode-approved): codex-call vendored into bin/ + 3 call sites migrated codex-exec→HTTP. Config drift unified. Latent empty-diff bug fixed. `24870cd` + verify-fix `d66d800`. v2.78.0.\n- Live-verify happy-path PASS (real Codex review in 19s). Verify-found path-resolution gap fixed same-round.\n\n### Scope Changes\n- (none)\n\n### Blocking\n- (none)\n\n### Commits\n- `24870cd` feat: migrate idd-verify Codex codex-exec → vendored codex-call HTTP wrapper (#147)\n- `d66d800` fix: thread skill-resolved absolute codex-call path + quote-safe (#147)\n\n### Verification\n- **PASS** (focused + live-verify) — distribution sync (push + marketplace reload 2.78.0) executed. Residue: hang is intermittent, acceptance anchored on \"migrated to HTTP path\".\n" }, { "number": 150, @@ -256,7 +283,8 @@ "- (none — issue closed; #154 inherits runtime enforcement work)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Original text** (from `/spectra-discuss` session 2026-05-25,user 切到 append-vs-modify 議題後 explicit pivot):\n> 「我最近開始思考的是,不斷 append 會不會不比直接修改內容好」\n> — Source: spectra-discuss session conversation (本對話即時 capture)\n\nIDD 內部其實已經是 hybrid append + modify(不是純 append),但 hybrid 規則 implicit、case-by-case 演化、從未被 codify。每次遇到「AI 想表達新狀態但不能直接編老 AI-authored 內容」就加 supersession workaround,workaround 數量正在增加。本 issue 是強迫 explicit 決定該不該把 implicit 規則升上 first-class principle。\n\n## Type\n\nrefactor — META / plugin design principle codification(類比 #144 IC_R011 「AI design over-abstract」 的 plugin-level principle file pattern)\n\n## Expected\n\n- Explicit `Append vs Modify` discipline 文檔化為 plugin-level rule(可能落地形式:`plugins/issue-driven-dev/rules/append-vs-modify.md` 或併入既有 manifesto)\n- 提供 mapping table:artifact type → modify / append / hybrid 行為對照\n- 解決痛點:Strategy/Plan checkbox supersession 改走 gate-logic「only-look-at-latest」(Path C)還是允許 AI 直接 PATCH 老 AI output(Path B);決定 IC_R007 與 「AI self-edit」 的 boundary\n\n## Actual\n\n- Discipline 是 implicit,scatter across 7+ sites(comments / issue body / CHANGELOG / canonical ref / SKILL.md / tasks.md / supersession layer)\n- 每個新 IDD feature 都在加 ad-hoc supersession workaround(#515 / #148 / #149 retroactive summary / IC_R011 audit trail accumulation),沒人問 root rule\n- 新人 / 3 個月後讀者要 archaeology 多個 comment 才能 reconstruct current state\n\n## 現狀證據(7+ sites,本 session 親自觀察)\n\n| Artifact | 行為 | 證據 |\n|----------|------|------|\n| Comments | 純 append + 內部 PATCH | diagnose 後續 PATCH audit blocks(Layer V + Sister + Distribution Sync)|\n| Issue body 上半(Problem/Type/Expected/Actual)| Immutable(IC_R007 verbatim preserve)| `/idd-issue` Step 3 contract |\n| Issue body 下半(Current Status)| Modify(REPLACE below `---`)| `/idd-update` Step 5 |\n| CHANGELOG.md | 純 append | `[2.72.0]` 加在 `[2.70.0]` 上方 |\n| Canonical ref `.md` | Modify(in-place rewrite)| `ic-r011-checkpoint.md` 301→397 是 Write-replace(本 session 親手做)|\n| SKILL.md | Modify(refactor in-place)| 6 SKILL.md 從 inline ~50 行 → cite ~15 行(本 session 親手做)|\n| tasks.md | Modify(checkbox flip)| `[ ]` → `[x]` via `spectra task done` |\n| Strategy/Plan checkboxes in 老 comments | **Append-only with supersession hack** | #515 fix:post 新 `## Implementation Complete` override 老 Strategy/Plan |\n| Closing summary 內 cross-link | Modify(Step 3.5 inline replace BEFORE publish)| `/idd-close` Step 3.5 |\n| Spec archive | Hybrid(delta promote to main + snapshot keep)| `spectra archive` 預設 sync delta → main |\n\n## 隱性原則(從上表反推)\n\n```\nhuman-authored content → never modify (IC_R007 verbatim preserve)\nAI-authored decision → append (decision history matters)\nmachine-readable state → modify (only current state matters)\nAI-authored stale state → supersession hack (post newer to override older) ← 痛點所在\n```\n\n## 痛點具體 evidence(本 session)\n\n1. **#515 fix**:`idd-close` Step 0 gate 一直誤判 Strategy/Plan 老 checkboxes 為「未完成」→ 加 supersession bridge(`Implementation Complete > Checklist` 全 `[x]` 視為 canonical state of truth,跳過 Strategy/Plan scan)。\n2. **#148 closing remediation**:本 session 必須手動 post 一個 synthetic `## Implementation Complete` comment 才能觸發 #515 supersession → gate 通過 → close。\n3. **#149 retroactive closing summary**:被 commit-body trap auto-close,事後 post 「(retroactive — auto-closed via commit-body trap)」標記的 Closing Summary。Audit trail 同時有早期 auto-close 跟事後 summary,讀者要自己分辨哪個是 final state。\n4. **IC_R011 audit trail accumulation**:`### Sister Concerns Filed` / `### Closing Follow-ups Filed` / `### Distribution Sync` / `### Residue Acknowledgement` 都 append 到同一 comment,而非 REPLACE 一個 \"Final Audit\" structured section。Comment 不斷膨脹;3 個月後讀者要分辨「這 4 個 block 是真的 final 還是還會繼續長」。\n5. **Canonical ref 文件 growth**:`ic-r011-checkpoint.md` 在本次 spectra change 從 301 → 397 行 append 上去(Section 7、8 新增)。**這個是 modify-friendly artifact**,所以沒 friction,但證明 IDD 在 docs / SKILL.md 已經是 free-modify;痛點集中在 GitHub-side comments / issue body。\n\n## 3 個 candidate path(spectra-discuss 結論)\n\n| Path | 機制 | 代價 |\n|------|------|------|\n| **A: Status quo(append + supersession)**| 老 comment 留著 + 新 comment override | 讀者 archaeology;3 個月後翻舊 issue 像考古;history 完整但「current state 在哪」不明確 |\n| **B: AI may modify AI's prior output** | `idd-implement` 結束時直接 PATCH 老 `## Implementation Plan` checkbox 為 `[x]`,或 PATCH 老 Strategy 加 `~~strikethrough~~` + 「(superseded by #NEW comment)」 | 失去「decision-at-time」history;但 single source of truth;需要明確的 IC_R007 vs AI-self-edit boundary |\n| **C: Refactor gate semantic** | 把 Strategy/Plan checkbox 設計成「初始 snapshot,not gate source」;gate 永遠從新 `Implementation Complete` 讀(#515 已部分實作) | 不改文件 mutability,改 gate logic 預設 only-look-at-latest;最小破壞;但仍留 archaeology cost |\n\n**spectra-discuss tentative inclination**:**C 加部分 B**(C 解 90% 痛點 + B 用於明確「AI retract self」case)— 留給本 issue 的 diagnose / propose 階段正式 decide。\n\n## Sister Concerns\n\n- **#144**(codify「AI design over-abstract」as plugin-level principle)— **同 pattern**:implicit AI behavior → user explicit surface → codify as plugin principle。本 issue 是 instance #2 of this meta-pattern。\n- **#515**(supersession bridge fix)— 本 issue 是 root-cause-level codification,#515 是 surface fix。本 issue 可能 retroactive 改變 #515 的 mechanism choice。\n- **#137**(unattended-mode Clarity Surface contract)— **被 deprioritized 切到本 issue**(user 在 spectra-discuss 中 explicit pivot):「(2) 先 file 這個 append-vs-modify 議題 → 再回 #137」。本 issue ship 後 resume #137 discussion。\n\n## Open Questions(deferred — 留給 diagnose/discuss 決定)\n\n1. **AI 可不可以 modify AI 自己的舊 output?**(Path B)若可,要什麼 boundary?(只 PATCH checkbox? 還是可以加 `~~strikethrough~~` + supersession note?)\n2. **跟 IC_R007 「human content verbatim preserve」的 boundary 怎麼界定?** AI 引用 human content 後 AI render 的詮釋是 AI-authored,可被 AI 自己 modify 嗎?\n3. **保留 append-only,改 gate logic「only look at latest」?**(Path C)`idd-close` gate 預設只看最新 `## Implementation Complete > ### Checklist`(#515 部分實作)— generalize 到所有 gate(`idd-verify` / `idd-update`)?\n4. **IC_R011 audit trail blocks 是否該收斂成 single Final Audit section + REPLACE,而非各自 append?**\n5. **idd-edit 已經 modifies content** — 它跟 append-vs-modify discipline 的關係?是 escape hatch 還是該被 discipline 約束?\n6. **直接 file 為 plugin principle**(類比 IC_R010 / IC_R011)還是 codify 為 manifesto 一節?\n\n## 為什麼 file 這個 issue(meta-justification)\n\n第 4 條 supersession workaround 數量已經 ≥ 5(從本 session 親身證據)。每個新 IDD feature 都在加 workaround,而沒人在問「這條 implicit rule 該不該升上 explicit principle」。本 issue 的目的是強迫做這個決定,而不是繼續在每個新 friction 加 ad-hoc bridge。\n\n## Residue\n\n> **NSQL §4.6 residue**(由 idd-issue 自我聲明,後續 diagnose 階段補充):\n> 本 issue 涵蓋「IDD 內部 append vs modify discipline」這個 decision space,但**不**涵蓋:\n> - IDD 與其他 plugin 的 cross-plugin append/modify policy(本 issue scope 限 IDD 自己)\n> - 過去已 ship 的 supersession workaround(#515 等)是否該 retrofit(留給 implement 階段 decision,本 issue 只 codify principle)\n> - 跨 session 的 comment 累積最佳實踐(屬於 GitHub UX 議題,不是 IDD 設計議題)\n> - 本對話即時討論的 Path A/B/C trade-off 細節(diagnose 階段重新評估)\n\n(本 issue 是 META/principle 議題,不是 single behavior change — 屬 Spectra-tier candidate per IC routing,但最終 routing 由 `/idd-diagnose` 決定。預期 verdict: Spectra(Layer 2 published principle + Layer 3 修改既有 spec normative behavior 多處)。)\n\n### Clarity Surface (dismissed)\n\n| Type | Source | Suggested canonical | Status |\n|---|---|---|---|\n| (dismissed) | Step 4.6 was deferred initially (META-recursion: issue body uses IDD plugin's own canonical terms supersession / IC_R011 / append / modify / audit trail / IC_R007 that user explicitly defined in immediately-prior /spectra-discuss session 2026-05-25). Step 0.5 gate at /idd-diagnose triggered hard-refuse on deferred row; dismissed with canonical §1.4(a) unactionable-observation reason: META-issue about IDD's own discipline, no domain-vocab mismatch exists to clarify. Reviewed body: 0 mismatches found. | n/a | dismissed |\n\n> **Audit dance**: deferred at /idd-issue Step 4.6 → REFUSE at /idd-diagnose Step 0.5 → dismissed with §1.4(a) reason → gate passes. This is the canonical \"deferred-with-reason → gate-refusal → explicit-dismiss\" loop the spec designed for.\n\n### Linked-Context Siblings Filed (v2.48.0+ #529, per IC_R011 v2.72.0+ default-flip)\n\n| Filed | Title | Source | Disposition |\n|---|---|---|---|\n| #151 | [Bug] Step 0.8 commit-body auto-close trap protection gap | /idd-close cluster #148 #149 session 2026-05-25 (#149 被 `closes #149` body trap auto-close) | filed per canonical §1.1 file-by-default — user explicit confirm in Step 4.7 picker |\n\n> **Sweep scope**: body draft + recent session conversation (~hours of /spectra-discuss + batch diagnose). #151 is structurally orthogonal to this META principle issue but informationally adjacent (Path B remediation choice depends on #150's principle decision).\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-25 by /idd-update (via /idd-close)\n\n### Key Decisions\n- Action-scoped reframe (user reject actor-based exemption): 7-category taxonomy (state-field-update / bounded-section-replace / audit-block-append / inline-replace-before-publish / verbatim-preserve / append-only / free-rewrite)\n- Spec discipline declared in v2.73.0 + v2.74.0 (8 SHALL + 16 scenarios); `/idd-edit` BREAKING runtime enforcement DEFERRED to #154 per R4 Path (c) decision after 3 verify iterations exposed bash-incremental impl introduces new bugs each pass\n- Path C `authoritative_source` gate-logic generalization across 4 sites (idd-close Step 0 / idd-verify checklist scan / idd-update body sync / idd-implement Step 5 Checklist Sync)\n- Reason pattern registry section added to rule (cited by #137 work)\n- Cluster PR #153 (with #137)\n\n### Scope Changes\n- DROPPED from spectra-apply tasks 3.1+3.2+3.3 (idd-edit BREAKING runtime enforcement) → moved to #154\n\n### Blocking\n- (none — issue closed; #154 inherits runtime enforcement work)\n\n### Commits\n- `b788a73` cluster merge commit (same as #137; both issues co-shipped in PR #153)\n\n### Closing\n- Closing Summary: https://github.com/PsychQuant/issue-driven-development/issues/150#issuecomment-4531813340\n- Spectra archive: `openspec/changes/archive/2026-05-25-add-action-scoped-modify-discipline/`\n- Follow-up #154 filed (idd-edit runtime enforcement with R1/R2/R3 evidence + design requirements)\n" }, { "number": 151, @@ -265,7 +293,8 @@ "- (none — closed)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Original observation** (from /spectra-discuss + /idd-close cluster session 2026-05-25):\n> 「#149 was auto-closed by commit body trap. My commit `e5e05e1` contained literal text \"closes #149\" in the body explaining the side-effect fix. GitHub's context-blind parser auto-closed #149, bypassing /idd-close gate. Fixed by posting retroactive Closing Summary marked \"(retroactive — auto-closed via commit-body trap)\". **Step 0.8 PR-only gate doesn't protect direct commits — noted as gap.**」\n> — Source: /idd-close cluster #148 #149 closing remediation, session 2026-05-25\n>\n> **Cross-link**: surfaced during `/idd-issue #150` Step 4.7 Linked-Context Sister Sweep (per IC_R011 canonical file-by-default §1.1, v2.72.0+).\n\nGitHub auto-close 機制(`closes`/`fixes`/`resolves` keyword in commit / PR body)是 context-blind:不分辨 keyword 是「真的要 close」還是「在 prose 中引用 keyword 解釋」。當 commit body 為了 audit 紀錄需要寫 `closes #N` 時(例如 explain side-effect fix / 引用前次 commit message),GitHub 會把對應 issue auto-close,**完全繞過** IDD `/idd-close` gate(checklist gate / PR gate / semantic gate / IC_R011 sister sweep / residue ack / distribution sync)。\n\n## Type\n\nbug — protection gap\n\n## Expected\n\n`/idd-close` gate 應該 100% cover「issue close 行為」:不論 close 來自 explicit `/idd-close` 呼叫、PR merge 含 close keyword、direct commit 含 close keyword,都應該 enforce IDD discipline。\n\n## Actual\n\n- **Step 0.8 PR-only protection**:現行 protection 只 hook 在 PR mode(`idd-close` Step 1.5 PR Gate Check / `idd-create-pr` 寫 body 時 strip close keyword)\n- **Direct-commit path 漏網**:當 commit 直接 push 到 default branch(無 PR)+ body 含 `closes #N`,GitHub 立即 close issue。沒有 plugin-side 攔截點。\n- **觀察證據**(本 session 親身遇到):\n - Commit `e5e05e1`(2026-05-25)在 body 中為了 audit 解釋 side-effect 引用 `closes #149`\n - GitHub 立即 auto-close #149\n - 必須 post retroactive Closing Summary,標記「(retroactive — auto-closed via commit-body trap)」補救\n - Closing Summary 同時失去:checklist gate 驗證 / sister sweep / residue ack / distribution sync — 雖然事後可手動補,但 audit trail 不完整(原 auto-close 仍留在 timeline)\n\n## Impact\n\n- IDD discipline 在 direct-commit workflow 失效(僅 PR workflow 完整)\n- Audit trail 可能漏 sister concerns / residue / distribution sync(這 4 個 gate 在 retroactive remediation 時容易被遺忘)\n- User 心智模型 friction:「我以為 `/idd-close` 是唯一 close path,結果 commit body 也會 close」\n\n## 3 個 candidate path(待 diagnose)\n\n| Path | 機制 | 代價 |\n|------|------|------|\n| **A: Client-side git hook** | `pre-push` hook scan commit bodies for `closes/fixes/resolves #N` → refuse OR force `/idd-close` invocation | Per-user setup;不會 cover CI 直接 push 的情況 |\n| **B: Retroactive detection + auto-remediation** | `/idd-list` 或 cron skill 偵測「issue closed without `## Closing Summary` comment」→ AskUserQuestion 補救 | 需 daemon / hook;reactive 不是 preventive |\n| **C: Educational + documentation** | 在 SKILL.md / manifesto 明確警告「commit body 內 close keyword = 繞過 gate」,提供 audit-safe 寫法(`refs #N` 而非 `closes #N`)| 純文檔,依賴 user discipline;最低成本但效果有限 |\n| **D: GitHub API workaround** | GitHub Action(repo-side)監聽 issue close event → 若無對應 Closing Summary 則重新 open + 提示 | Server-side enforcement;但需要 repo admin 部署,跨 repo 推廣困難 |\n\n**Inclination**:C(low-cost preventive 文檔)+ B(retroactive safety net)組合;A 留給 power user opt-in;D 列為長期 enterprise option。\n\n## Sister Concerns(this issue 的 sister 也需追蹤)\n\n- **#150**(append-vs-modify META principle)— 本 issue 的 retroactive remediation 行為(post retroactive Closing Summary)是 #150 「AI-authored stale state supersession」第 4 條痛點的具體 instance #6。本 issue 的 Path B 機制設計**直接受 #150 principle 決定影響**。\n- **#149**(本 issue 直接觸發案例)— 已 retroactive close,本 issue 是 root-cause-level fix。\n\n## Residue\n\n> **NSQL §4.6 residue**:\n> 本 issue 涵蓋「commit/PR body keyword auto-close trap」這個 bug class,但**不**涵蓋:\n> - GitHub UI 點按 \"Close issue\" button 的直接 close(non-keyword path,不在本 issue scope)\n> - 跨 repo close(`closes owner/repo#N` keyword)— 邊緣 case,待真實 evidence 才處理\n> - retroactive remediation tooling(屬 separate issue,若 Path B 採用會自然 spawn)\n\n(本 issue 屬 bug + protection-gap,routing 由 `/idd-diagnose` 決定;預期 verdict: Plan(Layer P:multi-file 改動 + 風險敏感 hook / git internals + 2+ valid approach)。)\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-06-01 by /idd-close\n\n### Key Decisions\n- Shipped Path C (docs) + Path B-lite (idd-list audit + helper); A/D deferred; v2.75.2\n- 6-AI verify (PR #175): PASS, 5 non-blocking findings all fixed in-PR (Codex uniquely caught a git diff --check CRLF regression)\n- Squash-merged to main (ed78d2d); issue stayed OPEN post-merge → auto-close did NOT fire (end-to-end proof)\n- Closed via /idd-close (the manual gate this issue exists to protect)\n- Residue: filed #176 (retroactive-remediation tooling — the item B-lite's detection enabled); UI-close + cross-repo remain await-evidence residue\n\n### Scope Changes\n- (none)\n\n### Blocking\n- (none — closed)\n\n### Commits\n- `ed78d2d` (squash on main) fix: close the direct-commit half of the auto-close trap (#151)\n" }, { "number": 152, @@ -274,7 +303,8 @@ "- (none)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Original observation** (surfaced during /idd-plan #137 tangential sweep, Step 2.5):\n> 在準備 #137 + #150 cluster PR(branch `idd/137-150-action-scoped-cluster`)時,git status 顯示 3 個 pre-existing dirty 項目跟本 session 工作無關:\n> - `.agents/skills/spectra-archive/SKILL.md` — 121 lines DELETED(working tree only,未 commit)\n> - `.claude/skills/spectra-archive/SKILL.md` — 119 lines DELETED(working tree only,未 commit)\n> - `.claude/.idd/state/chain-spawned-issues.json` — untracked,timestamp 2026-05-20\n>\n> 來自 prior session(last related commit `f5afb93` multi-root chain 2026-05-20),never staged。 若不處理 → 會被 sweep 進 cluster PR(scope pollution)或留在 working tree 永久 dirty。\n\n> **Cross-link**: surfaced during `/idd-plan #137` Step 2.5 Tangential Observations Sweep (per IC_R011 v2.72.0+ file-by-default §1.1).\n\n## Type\n\nchore — git hygiene\n\n## Expected\n\nWorking tree clean(無 unstaged 改動);3 個 dirty 項目都有明確 disposition:\n- 兩個 spectra-archive SKILL.md deletions → 確認是 intentional refactor(commit on appropriate branch)或 unintended drift(`git checkout`)\n- chain-spawned-issues.json → 確認是 needed state(commit + 加入 spec)或 stale ephemeral(`.gitignore`)\n\n## Actual\n\n3 個 dirty 項目 5 天以上未處理(2026-05-20 → 2026-05-25 +)。 每次 git commit 都要 selective `git add` 避免 sweep 進不相關 PR;cluster PR scope review 噪音增加。\n\n## Impact\n\n- **本 cluster PR (#137 + #150)** 必須 selective `git add` 排除 3 項,否則 PR diff 含 unrelated -237 lines + 1 untracked state file → reviewer 失焦\n- 未來每個 PR 都需重複 selective add → high friction\n- 真實情況不明:可能該 commit、可能該 revert、可能該 gitignore\n\n## Open Questions\n\n1. `.agents/spectra-archive` 跟 `.claude/spectra-archive` 為什麼 -237 lines?(原本是 refactor 還是意外 truncate?)\n2. `chain-spawned-issues.json` 是 manifest helper 該 commit 還是 ephemeral per-run state?\n3. 整個 `.claude/.idd/state/` 應該 git-ignored 還是 git-tracked?\n\n## Sister Concerns\n\n- #150 (action-scoped modify discipline,本 cluster PR sibling) — orthogonal;本 chore 不依賴 #150 principle\n- 無其他直接 sister\n\n## Residue\n\n> **NSQL §4.6 residue**:本 issue 限「working tree dirty 項目 disposition」。 **不**涵蓋:\n> - 廣義 git-hygiene CI rule(`pre-commit hook` 阻擋 dirty merge 等)— 屬 future enhancement\n> - 整個 `.idd/.claude/state/` directory 的 schema codification — 屬 separate proposal\n\n(本 issue 屬 chore tier — routing 預期 Simple,3 個 disposition decisions 屬 single-session triage,non-deliberation。)\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-06-01 by idd-close\n\n### Key Decisions\n- Diagnosed against *current* tree: #152 原 item 1+2（spectra-archive −237）**已 resolved**；剩 2 項 = `.claude/.idd/state/`（ephemeral session state → **gitignore**）+ `openspec/specs/idd-ic-r011-checkpoint/`（promoted-but-never-committed spec, TBD Purpose → **commit with real Purpose**）\n- Complexity = **Simple**（independent .gitignore + commit changes）\n- #180 overlap scope-split：#152 commit idd-ic-r011-checkpoint spec（含真 Purpose），#180 修剩 3 個 tracked stub\n\n### Blocking\n- (none)\n\n### Commits\n- `a545b32` gitignore .claude/.idd/state\n- `de73444` commit idd-ic-r011-checkpoint spec + real Purpose\n\n\n\n" }, { "number": 154, @@ -283,7 +313,8 @@ "- (none)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Source**: surfaced during /idd-verify --pr 153 R3 cluster verify (per IC_R011 — proper-design follow-up after 3-iteration implementation failure).\n\n`/idd-edit` 屬 `bounded-section-replace` (`--replace` mode) + `audit-block-append` (`--append`/`--prepend-note`) per #150 action-scoped modify discipline (`rules/append-vs-modify.md`)。 #150 v2.73.0 ship 時宣告 BREAKING runtime enforcement,但實際 bash 落地經過 3 iterations 都失敗:\n\n### R1 (commit `d643fc6`) — 加 Step 1/2/4 enforcement bash\n\n**R2 Codex independent revision 捕捉**(post-master):\n- B3-NEW-1 CRITICAL: `--scope value` (space form) parser sets SCOPE_FLAG=\"next\" literal\n- B3-NEW-2 CATASTROPHIC: `--body` space form → BODY_INPUT=\"\" → silent comment overwrite\n- B3-NEW-3 LOGIC: section replacement awk end_re ignores SECTION_LEVEL,orphans subsections\n- B3-NEW-4 DOC: old usage example without --scope\n\n### R3 (commit `5c62b38`) — parser rewrite + section level + docs\n\n**R3 full 6-AI ensemble verify 捕捉**(Logic + DA + Codex triple-confirmed):\n- C1 CRITICAL INFINITE LOOP: trailing space-form flag → `shift 2` silently fails on `$#=1` → `while [[ $# -gt 0 ]]` spins forever\n- C2 CRITICAL flag-value-eat: `--scope --body \"x\"` → SCOPE_FLAG=\"--body\" + BODY_INPUT=\"\" (next-token capture without look-ahead)\n- C3 CRITICAL multi-line awk-v BREAK: BSD awk rejects newlines in `-v` value → `awk: newline in string` → section-replace **DEAD-ON-ARRIVAL** for realistic markdown content\n- H1 HIGH `--body-file=/missing/path` silently produces empty BODY_INPUT → silent comment overwrite\n- F4 MEDIUM (from R2,still standing) errata flow regression on user-authored comments — `/idd-comment --type=errata` auto-call `/idd-edit --prepend-note` triggers verbatim-preserve guard refuse if target非 OWNER\n\n## Type\n\nfeature — proper runtime enforcement implementation (3-iteration failure → needs standalone proposal)\n\n## Expected\n\n`/idd-edit` runtime enforcement landed with:\n\n1. **Parser pattern**:positional shift `while [[ $# -gt 0 ]]; case \"$1\" in ... shift / shift 2 ;; esac` with **explicit missing-value guards**:\n ```bash\n --scope) [ -z \"${2:-}\" ] && abort \"--scope requires value\"\n [[ \"$2\" == --* ]] && abort \"--scope value cannot start with --\"\n SCOPE_FLAG=\"$2\"; shift 2 ;;\n ```\n (same guards for all 7 space-form flags: --scope / --section / --reason / --body / --body-file / --repo / --cwd)\n2. **Multi-line body handling**:write `BODY_INPUT` to temp file → awk reads via `getline new_content < body_file` per line(不要用 `-v` 傳多行)\n3. **`--body-file` readability pre-check**:`[ -r \"${1#--body-file=}\" ] || abort \"body-file not readable: ...\"`\n4. **Errata flow integration**:`/idd-comment --type=errata` auto-call `/idd-edit --prepend-note` 偵測 non-OWNER target → auto-pass `--override-user-content --reason=\"errata clarification per IDD discipline\"`(or refuse with helpful \"use --override-user-content\" message)\n5. **Doc consistency**:argument-hint / frontmatter / batch-mode / usage examples all show updated syntax\n6. **Test fixtures**:cover all R1/R2/R3 edge cases(`--scope=value` / `--scope value` / `--scope` last arg / `--scope --body` next-flag / `--body-file` missing / multi-line body / single-line body / section with `###` subs / section with no closing heading)\n\n## Actual\n\n3 bash-incremental attempts(R1/R2/R3)each introduced new bugs。 Implementation needs proper standalone proposal,not incremental patches。\n\n## Why this is a follow-up not a R4 fix\n\n- R4 bash patch path likely introduces R4 bugs(R1/R2/R3 evidence pattern)\n- Multi-line awk handling needs **rewrite**(getline pattern),不是 patch\n- Errata flow integration touches `/idd-comment` SKILL.md not just `/idd-edit` — cross-skill coordination\n- Acceptance criteria need explicit test fixtures(R1/R2/R3 attempts all missed adversarial patterns via narrow happy-path smoke tests)\n\nSplitting `/idd-edit` runtime enforcement as its own proposal lets it ship cleanly without blocking #137 + #150 substance(B1 awk fix + B2 BSD head fix + M5 wording + L3 retroactive labels — all solid)。 Spec discipline + AI/user invocation pattern guidance ship today;runtime gate ships post-design。\n\n## Sister Concerns\n\n- **#137** — primary cluster sibling — substance(unattended Clarity contract)ships independently\n- **#150** — primary cluster sibling — action-scoped principle codification ships independently\n- **#151** — auto-close trap protection gap(orthogonal P2)\n- **#152** — chore git hygiene (P3,orthogonal)\n\n## Open Questions\n\n1. **Bash 是否是正確 layer?** 3 iterations 都失敗暗示 bash 不是 right tool。 alternative: Rust CLI plugin / Python helper / native flag parsing infrastructure shared across IDD skills\n2. **`/idd-edit` 用 case statement vs argparse-style helper?** 7 個 SKILL.md 都需要 flag parsing(idd-comment / idd-issue / etc)— 抽 shared utility?\n3. **Multi-line body handling pattern** for awk replace:temp-file getline 是 Codex 建議,但需 verify pattern works on macOS BSD awk + gawk + mawk + can handle binary content / unicode\n4. **Errata flow integration**:`/idd-comment` 自動 pass `--override-user-content` 是否違反 IC_R007 spirit(user authored intent vs AI override)? Spec carve-out vs runtime auto-detect?\n\n## Routing\n\n- Complexity:Plan tier(2 SKILL.md changes + multi-line body design + test fixtures + cross-skill /idd-comment integration)— **不是** Spectra(no new published spec contract,extends existing #150 spec implementation)\n- Path:depends on user — direct `/idd-implement` after diagnose,或 `/idd-plan` 跑 EnterPlanMode design review first\n\n## Residue\n\n> 本 issue 涵蓋「/idd-edit runtime enforcement bash impl」。 不涵蓋:\n> - 廣義 IDD skill flag parsing infrastructure 抽 shared helper(屬另一 follow-up,跨 7+ SKILL.md scope)\n> - Rust / Python CLI plugin layer 替代 bash 評估(屬 long-term architecture decision)\n> - `/idd-comment` errata flow 重設計(本 issue 只整合,不重設計)\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-06-01 by idd-close\n\n### Key Decisions\n- Saga complete: #155 built the Python helper layer (23 fixtures green); #154 wired it into idd-edit/idd-comment SKILL.md + errata flow + fixed a stale FALSE path-safety claim. `9197f3b`, v2.81.0.\n- Runtime gates (R4 scope / R5 author / body-file path-safety) now enforced via idd-edit-helper.py. SKILL->helper contract smoke-tested.\n\n### Scope Changes\n- Parser/enforcement moved inline-bash -> Python helper (#155); #154 = wiring.\n### Blocking\n- (none)\n### Commits\n- `8243417` (#155) Python helper layer; `9197f3b` (#154) SKILL.md wiring + errata + v2.81.0\n### Verification\n- **PASS** (focused) — contract smoke-test + 23 fixtures + #156 lint green. Distribution sync (push + reload 2.81.0) executed. #158 (batch R5 full semantics) remains the only deferred follow-up.\n" }, { "number": 155, @@ -292,7 +323,8 @@ "- (none — was the blocker for #154; #154 now unblocked)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n**Source**: surfaced during /idd-diagnose #154 sister concern surfacing (Step 3.6)\n\n`/idd-edit` runtime enforcement (#154) 是第 1 個 SKILL.md 嘗試在 bash 落地 strict flag parsing + multi-line body handling 的 case。 3 iterations(R1/R2/R3 on PR #153)都 introduce new bugs:\n\n- R1 awk range collapse + BSD `head -n -1` 不存在\n- R2 Codex 捕捉 4 個 parser bugs (`--scope value` literal,`--body` empty silent overwrite)\n- R3 全 6-AI ensemble 捕捉 3 NEW CRITICAL (infinite loop on `shift 2`,flag-value-eat,BSD awk -v 多行 break)\n\n**Pattern**:bash-incremental 修一個 parser bug 暴露另一個。 暗示「bash 不是 right layer for strict enforcement」。\n\n#154 diagnosis Open Q1 + Risk R1 mention 此問題,但本 issue scope 限「bash impl 兌現 #150 declared discipline」。 **此 issue 紀錄替代 layer 評估的 long-term 議題,等 rule-of-three trigger。**\n\n## Type\n\nenhancement / long-term architectural decision\n\n## Trigger conditions (parking-lot)\n\n明確 trigger 任一:\n\n- ≥3 個 SKILL.md(目前 idd-edit = instance #1)獨立撞同類「bash 強 enforcement → introduce bugs」pattern\n- #136 (`/idd-edit` + `/idd-update` integrate `/idd-clarify`) trigger 後實作,若 parser 整合再次 introduce bug → instance #2\n- 任一 IDD AI 跑 `/idd-edit` 因 bash subtle bug 誤刪 user content(catastrophic failure)→ instance #1 即夠\n- Maintainer 願 invest design budget 評估 alternative(non-trivial)\n\n## Candidate alternatives(未來 design 時評估,本 issue 暫不選)\n\n| Layer | Pros | Cons |\n|-------|------|------|\n| **Bash + sourced helper** (`source $CLAUDE_PLUGIN_ROOT/scripts/parse-flags.sh`) | 無新 runtime 依賴;cross-skill reusable | 仍 bash semantics fragile(test fixtures 仍需) |\n| **Python helper** (`python3 $CLAUDE_PLUGIN_ROOT/scripts/idd-skill-helper.py`) | argparse + 良好 stdlib;cross-platform | 加 python 依賴(macOS 內建,Linux 一般有);啟動慢於 bash |\n| **Rust CLI plugin**(同 `agent-browser` model) | 強型別 + 一次寫 cross-skill 用;啟動快 | 新 build artifact + version sync 複雜度;rule-of-three 才合理 |\n| **Plugin framework primitive**(Claude Code 自身提供 flag parsing?)| 0 maintenance | 取決於 Claude Code roadmap |\n\n## Type\nenhancement / long-term architectural decision\n\n## Priority\nP3 — parking lot until trigger fires (rule-of-three 或 catastrophic failure)\n\nRefs #154 #150 #136\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-06-01 by idd-close\n\n### Key Decisions\n- Layer ratified: Python helper. idd-edit-helper.py (stdlib-only) eliminates all 6 R1-R3 bug classes by-construction (realpath path-safety, deterministic parser, html escape, TEST_MODE-gated mock). 23/23 fixtures green. `8243417`, v2.80.0.\n- Scope = layer only; #154 wires it into SKILL.md (now unblocked).\n\n### Scope Changes\n- (none)\n### Blocking\n- (none — was the blocker for #154; #154 now unblocked)\n### Commits\n- `8243417` feat: idd-edit runtime-enforcement helper as Python layer, 23 adversarial fixtures green (#155)\n### Verification\n- **PASS** (focused + security) — 23/0 independently re-run + adversarial path-bypass sweep. Distribution sync (push + reload 2.80.0) executed.\n" }, { "number": 156, @@ -301,7 +333,8 @@ "- (none)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n**Source**: surfaced during /idd-diagnose #154 sister concern surfacing (Step 3.6)\n\nIDD plugin 目前**無 systematic test framework**。 每個 SKILL.md 有 dogfood scenario(README-style)但**沒 executable test runner**。 #154 diagnosis Block A3 需 build 9 adversarial test fixtures(R1/R2/R3 regression set)來確保 parser 不再 introduce bugs:\n\n1. `--scope=value` (eq form)\n2. `--scope value` (space form)\n3. `--scope` as last arg (missing value)\n4. `--scope --body \"x\"` (next-flag eats value)\n5. `--body-file=/missing/path` (unreadable file)\n6. Multi-line body (newline content)\n7. Single-line body\n8. Section with `###` subsections (level-aware end)\n9. Section with no closing heading (EOF as end)\n\n**問題**:這 9 fixtures 無 framework → 寫 ad-hoc shell script 跑一次 → 之後 regression 無法自動 catch。 R1/R2/R3 verify 之所以失敗 = AI 寫了「應該 work」的 happy-path smoke test,沒 adversarial coverage。\n\n## Type\n\nenhancement / infrastructure\n\n## Background\n\nIDD plugin 既有 testing surface:\n- `idd-verify` 是 **runtime** verification (issue → diagnose → impl → verify 6-AI ensemble) — catches implementation regression\n- 每個 SKILL.md 有 README 風格 dogfood example — manual one-off\n- 沒有 `tests/idd-edit/test_parser.sh` 之類 unit-level CI-able test\n\n**Closest precedent**:`scripts/process-attachments.sh` 是 IDD helper script,但無對應 test。\n\n## Open questions\n\n- **Test framework choice**:bats(bash test framework)/ plain `set -e` shell script / Python pytest wrapping bash?\n- **Trigger**:single SKILL.md needs it → 順便建?或等 ≥3 SKILL.md surface 同需求?\n- **Scope**:\n - (a) idd-edit-only fixtures(本 issue 範疇)\n - (b) IDD plugin-level test infrastructure(generalizable to all SKILL.md)\n- **CI integration**:GitHub Actions runs on PR?或 pre-commit hook?(plugin distribution model 對 CI 期望低)\n\n## Trigger conditions (parking-lot — but lower threshold than #154 layer issue)\n\n- **Immediate**:#154 implementation Block A3 開工 → 必然需 framework choice。 可在 #154 Plan tier EnterPlanMode 階段決定 fixture 是 ad-hoc vs framework\n- **Threshold**:≥2 SKILL.md 都需 adversarial fixtures → 升 instance #2\n\n## Type\nenhancement / infrastructure\n\n## Priority\nP2 — higher than typical parking-lot (#154 implementation immediately need),但本身仍 follow-up scope\n\nRefs #154 #150\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-06-01 by idd-close\n\n### Key Decisions\n- Scope B (class closure): assert-helpers.sh (assert_grep bakes in --) + lint-grep-separator.sh. Migrated idd-worktree + check-closed; pr-body got -- hardening (scanner, not assertion runner). `9b0e160`, v2.79.0.\n- grep-`--` class structurally closed (#154 + #160 + #156). 9 idd-edit fixtures = #154 Block A3 (deferred, can now source the lib).\n\n### Scope Changes\n- (none)\n### Blocking\n- (none)\n### Commits\n- `9b0e160` feat: shared assert-lib + grep-separator lint to close the grep var-needle bug class (#156)\n### Verification\n- **PASS** (focused) — 3 suites 零 regression + lint falsifiable (caught a ROOT precedence bug). Distribution sync (push + reload 2.79.0) executed.\n" }, { "number": 160, @@ -310,7 +343,8 @@ "- (none)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n**Source**: surfaced during /idd-implement #154 reproduction (Step 5.7)\n\n`.claude/scripts/tests/spectra-archive-post-ic/test.sh` 可能含同類 bug:`grep -qF \"$needle\"` 不加 `--` 結尾選項分隔符,當 `needle` 以 `--` 開頭時被 grep 誤判為 flag → silent failure or warning instead of pattern match。\n\n## Background\n\n`/idd-implement #154` 期間我從 `spectra-archive-post-ic/test.sh` 抄了 fixture-dir test runner 模式做 `idd-edit/test.sh`。 抄完跑第一次,fixtures 03/04/05 全 FAIL 並印出:\n\n```\ngrep: unrecognized option `--scope requires value'\nusage: grep [-abcdDEFGHhIiJLlMmnOopqRSsUVvwXxZz] [-A num] [-B num] [-C[num]]\n...\n```\n\n修法:`grep -qF \"$needle\"` → `grep -qF -- \"$needle\"`。 `--` 告訴 grep「options 結束,後面是 pattern」。\n\n**問題**:抄自 spectra-archive-post-ic/test.sh,所以 **該 test runner 也可能有同 bug**。 若 spectra archive fixtures 的 expected_stdout / expected_stderr needles 沒 `--` 開頭,bug 不會 trigger → silent 不知道存在。\n\n## Reproduction (untested,需 verify)\n\n1. `cd .claude/scripts/tests/spectra-archive-post-ic`\n2. 加 fixture with `expected_stdout.txt` containing `--some-flag-error-string`\n3. 跑 `bash test.sh`\n4. 預期:該 fixture FAIL with `grep: unrecognized option` warning\n\n## Impact\n\n- **不會立即壞**:現有 spectra-archive-post-ic fixtures 可能都沒 `--` prefixed needles,所以 bug 未 trigger\n- **未來 risk**:加新 fixture 含 `--flag` 預期值會 silent 失敗(看 PASS 但實際 grep 沒匹配)\n- **Same-skill instance**:`#154` 是 instance #1,本 issue verify 後可能升 instance #2 → 整合進 #156 framework 設計時 batch fix\n\n## Type\n\nbug / test infrastructure\n\n## Strategy\n\n1. Verify reproduction(寫 1-2 個 `--` prefixed expected fixture 跑看看)\n2. 若 trigger → 套同 fix:`grep -qF \"$needle\"` → `grep -qF -- \"$needle\"` in spectra-archive-post-ic/test.sh\n3. 若同時 #156 trigger generalize → 抽 shared assertion lib `.claude/scripts/lib/assert-helpers.sh`\n\n## Priority\n\nP3 — silent until new `--` prefixed fixture added。 file 是為了 audit + 未來 #156 generalize 時 batch fix。\n\nRefs #154 #156\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-06-01 by idd-close\n\n### Key Decisions\n- Hypothesis (test.sh has grep -qF -- bug) FALSIFIED: test.sh uses [ = ] exact-match, 14/0 green. Audit found 2 non-exploitable in-area instances in spectra-archive-post-ic.sh → defensive `--` hardening. `eaaae7c`.\n- No live bug. Value = audit + uniform `--` discipline. 2 out-of-area regex greps left to #156 (systemic != blanket).\n\n### Scope Changes\n- (none)\n### Blocking\n- (none)\n### Commits\n- `eaaae7c` fix: add `--` separator to grep var-needle calls in spectra-archive-post-ic.sh (#160)\n### Verification\n- **PASS** (light) — 14 fixtures green + `--` falsifiable proof. Project-level script: no plugin bump / no distribution sync.\n" }, { "number": 164, @@ -319,7 +353,8 @@ "- (none) — 原「等 user 自行執行 `/spectra-propose`」為 stale 記錄：該 propose 已於 2026-06-01 消化（見 comment「Propose → parked change created」）；2026-07-18 user 確認不再為剩餘小項開新 propose" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Original text**:\n> 「我之後要看怎麼搭配agent teams」\n> — Source: pasted text, /idd-issue invocation 2026-05-29\n\n**Plain-language interpretation**: 一條 parking-lot 探索種子 — 之後要研究 IDD workflow 如何與 **agent teams**（多 agent 協作編排）搭配。現階段是 capture-the-thought,scope 尚未定形,留待 pick-up 時細化。\n\n## Type\n\nfeature / exploration（種子,非具體需求）\n\n## Priority\n\nP3 —「之後要看」明確是低優先 someday/maybe。不阻擋當前 critical-path（#155 idd-edit alt-layer）。\n\n## Background / 為什麼值得記\n\nIDD 已經在跑 multi-agent,但**沒有 first-class 的「agent teams」整合策略**:\n\n- `/idd-verify` spawn 5 個 parallel `Agent(subagent_type=general-purpose)` + 1 Codex = 6-AI ensemble。 但這是**手動 fan-out**,不是 team 抽象。\n- [#52](https://github.com/PsychQuant/issue-driven-development/issues/52) 把 idd-verify **從 TeamCreate model 遷出**(改成 standalone Agent calls),因為 TeamCreate 的 `wait_for_idle` 在 idle/wake cycle 後 context 流失 + teammate 需顯式列 Write tool。\n- [#70](https://github.com/PsychQuant/issue-driven-development/issues/70) 是 TeamCreate cleanup gap(TeamDelete fails on idle-but-active reviewers)— 遷出 team model 後 structurally 消解。\n- `/idd-all` / `/idd-all-chain` 是 sequential orchestration,沒有 team-parallel。\n\n所以「搭配 agent teams」這個探索有真實的張力:IDD 剛**離開** TeamCreate,但 ensemble verify 本質上**就是**一個 team。 問題是:正確的 team 抽象長什麼樣?\n\n## 候選探索線索（給未來的自己,非結論）\n\n開工時這些是起點,不是已選方向:\n\n1. **Verify ensemble 形式化** — 目前 6-AI 是每次手刻 prompt + file-based output + polling。 是否值得抽成可重用的「review team」primitive？（但要避開 #52 遷出的 TeamCreate 痛點）\n2. **idd-all-chain × team-parallel** — chain 目前 sequential 解 root + spawn。 多個 independent spawn 能否 team-parallel 跑？\n3. **Claude Code 原生 agent teams** — 平台若有 agent-teams 機制（vs 手動 Agent fan-out），IDD 該不該採用？這需要先確認平台現況。\n4. **跨 skill 的 reviewer pool** — verify 的 5 reviewer 角色（requirements/logic/security/regression/DA）能否被其他 skill（如 spectra-verify、code-review）共用？\n\n## Out of scope（明確不在此 issue）\n\n- 不重啟 TeamCreate（#52 已有充分理由遷出;除非探索發現新證據）\n- 不改當前 idd-verify 行為（這是探索,不是 refactor proposal）\n\n## Next（when picked up）\n\n先 `/idd-clarify #THIS` resolve「agent teams 指什麼」的 referent 歧義（見下方 Clarity Surface），再 `/idd-diagnose` 評 complexity。 探索性質大概率 `/spectra-discuss`（多個 valid 方向 + 影響 published skill 編排契約）。\n\n\n---\n\n### Clarity Surface\n\n> Authored inline at creation (proportionate to a terse exploration seed; run full `/idd-clarify #164` when picked up for the complete three-class scan).\n\n| Type | Source phrase | Suggested canonical | Status |\n|------|---------------|---------------------|--------|\n| terminology / missing-context | 「agent teams」 | **Resolved**: within-window parallel sub-agent / orchestration primitives (per comment 2, 2026-05-30, citing #167) — concretely the `Agent` tool fan-out, the experimental Agent Teams (`TeamCreate`), and (newly available as of 2026-06) the `Workflow` tool (dynamic workflows). NOT generic multi-agent. Candidates (a)/(b)/(c) collapse into this family; (d) cross-skill reviewer pool is an orthogonal downstream question, not the referent. | resolved |\n\n> **Gate note (resolved 2026-06-01)**: per `/idd-diagnose` Step 0.5, this row was `surfaced` and would have refused diagnose. Referent was pinned in comment 2 (2026-05-30) and re-confirmed during `/idd-diagnose` 2026-06-01: \"agent teams\" = within-window orchestration primitive family. The 2026-06 arrival of the `Workflow` tool (dynamic workflows) is a new member of that same family, fully compatible with comment 2's definition — it does not re-open the referent, it expands the option set the diagnosis must weigh. Row flipped `surfaced → resolved` to keep the audit trail consistent with the already-existing clarification.\n\n### Linked-Context Siblings Filed\n\n(none surfaced — clean single-seed invocation, no linked attachments / no orphan session mentions beyond the #155 alt-layer work already tracked)\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-07-18 by /idd-update（manual — stale-status sync）\n\n### Key Decisions\n- **Phase 1 shipped & ungated**：`formalize-idd-verify-ensemble` propose → apply → archive（2026-06-01）；v2.77.0 gated 引入 → **v2.77.1 ungate 成預設 backend**（`7d88bf9`）；inaugural `idd-verify` spec 落地（5 requirements、real Purpose）\n- **Phase 2 正式放棄**（2026-06-01 re-eval comment）：idd-all-chain 踩滿 workflow 四項 hard limit（stateful FS/shell、mid-run user input、共用 branch 只能 sequential、workflow 不可巢狀呼叫 workflow-verify）→ chain 維持 sequential skill-orchestration，不 port 到 workflow primitive\n- 剩餘小項（非 Spectra 級、不阻塞）：severity-vocab unification（workflow `CRITICAL/HIGH` vs manual `P1/P2`）、post-fix re-verify、optional discovery-phase experiment（chain 的 read-only 平行 discovery 子步驟）\n- **2026-07-18 user 裁決**：不為剩餘小項開新 propose；本次僅同步 status、清除 stale Blocking\n- Complexity = **Spectra** (Layer 2 published skill 編排契約 + Layer 3 architectural；影響 idd-verify + idd-all-chain)\n- 釘定 referent：「agent teams」= within-window orchestration primitive family，2026-06 新增成員 `Workflow` tool (dynamic workflows)\n- 推薦 **hybrid split**：workflow 擁有 deterministic「fan-out → DA verify → merge」core；skill 保留 gates + GitHub 發文 + triage + verify-fix loop\n- workflows.md canonical use case 逐字 = IDD verify ensemble（adversarial cross-review）；候選線索①「reusable review-team primitive」答案 = saved workflow\n- Routing → **spectra-discuss DONE**（2026-06-01 converged）→ next **/spectra-propose**。Conclusion 落定：scope 含 verify ensemble + idd-all-chain（兩 site，分期 verify-first）；Codex 包進 workflow + Phase 0 spike；新 spec **`idd-verify`**（inaugural，reference idd-pr-hitl-modes，名字 reject 掉 redundant `-ensemble` / mechanism-leaking `-workflow`）\n\n### Scope Changes\n- Phase 2（idd-all-chain workflow 化）自 scope 移除 — pre-build symmetry ≠ build justification，不對稱（stateful / sequential / gated / nesting）在 Phase 1 建完後才顯形\n- Clarity Surface row「agent teams」referent：`surfaced → resolved`（回寫 comment 2 釘定 + 新成員 Workflow tool）\n- (side-product) naming/Purpose lesson 落地：rename `idd-orchestrator-modes → idd-pr-hitl-modes` + 填 Purpose（`b6fd718`, v2.76.1）；4 個同類 TBD-stub spec backlog → #180；Spectra 上游缺口（no capability-rename + Purpose stub）以 inquiry 問上游 → kaochenlong/spectra-app#100（注：`spectra feedback` CLI 是 local echo + 死 URL，真 repo 是 `kaochenlong/spectra-app`）\n\n### Blocking\n- (none) — 原「等 user 自行執行 `/spectra-propose`」為 stale 記錄：該 propose 已於 2026-06-01 消化（見 comment「Propose → parked change created」）；2026-07-18 user 確認不再為剩餘小項開新 propose\n\n### Commits\n- `7d88bf9` fix(idd-verify): ungate dynamic-workflow backend (now default) + 3 self-dogfood bug fixes; v2.77.1\n- `4c860cd` chore(spectra): archive formalize-idd-verify-ensemble; idd-verify spec materialized + Purpose-gap confirmed live\n- `e78adce` feat(idd-verify): v2.77.0 — dynamic-workflow backend (gated, component-verified) + CHANGELOG\n- `2c8b56c` feat(idd-verify): 3.1 findings normalization — both backends share the master-report table\n- `3f8b385` chore(idd-verify): mark tasks 3.2/3.3 done — verified by construction\n- `6987d3a` fix(idd-verify): workflow args may arrive JSON-stringified — defensive parse; live-verified ensemble catches planted findings\n- `f6af489` wip(idd-verify): dynamic-workflow backend — spike + schema + script + skill section, hardened\n- `b6fd718` refactor(spec): rename idd-orchestrator-modes to idd-pr-hitl-modes + fill Purpose\n\n" }, { "number": 167, @@ -328,7 +363,8 @@ "- (none) — closed via PR #168 (squash b11b65d). Spectra change archived. Follow-ups: #169 (convention reconciliation), #170 (post-IC detection)." ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Original text**:\n> 「要能夠平行做很哆idd才可以，不然現在在agent teams的時候會衝突，這是很重要的，可能不能只用branch還要用worktree才可以吧？要考慮怎麼讓多個idd不會彼此衝突的方法」\n> — Source: 直接貼文字（/idd-issue 對話）\n\n要在 agent teams 場景下**平行執行多個 IDD pipeline**。目前多個 IDD 同時跑會互相衝突 —— 它們共享同一個 git working tree / branch / 暫存檔。使用者推測單靠 branch 隔離不夠，可能需要 git worktree 才能讓每個 IDD 有獨立工作目錄。核心需求：設計一套讓多個 IDD 不彼此衝突的隔離機制。\n\n## Type\nenhancement（architecture / exploration seed）\n\n## Priority\n使用者明確標示「這是很重要的」—— importance 高，是 #164 agent-teams 探索能否落地的**前置 blocker**（沒有隔離機制，平行化無從談起）。但仍屬 exploration，等 trigger 才 implement。\n\n## 為什麼這是 #164 的具體子問題\n\n#164 問的是「IDD 如何搭配 agent teams（verify ensemble / orchestration）」這個大方向。本 issue 從中切出**最硬的工程約束**：\n\n- agent teams 的價值來自平行 → 但 IDD 的 stateful 操作（branch checkout、working-tree edit、commit、`.claude/.idd/` 暫存、attachment staging）預設都假設**單一序列執行者**。\n- 兩個 IDD 同時 `git checkout` 不同 branch → 後者覆蓋前者的 working tree。\n- 兩個 IDD 同時寫 attachment staging / run-log → race。\n\n## 兩個 case（user clarified 2026-05-30）\n\n> **User clarification (verbatim)**:\n> 「#167 的確我要分成兩個case，就是一個claude code視窗呼叫agent teams；另外一個是多個視窗每一個視窗可以跑一個idd」\n\n平行的真正軸線是**執行拓樸（execution topology）**，不是 pipeline 粒度（原 Clarity Surface 候選 a/b/c 軸選錯，已 resolved）。兩個 case 隔離難度不同：\n\n### Case A — 單一 Claude Code 視窗 → 呼叫 agent teams（within-window 平行）\n\n- 平行單位 = 同一 session 內的 sub-agents（`Agent` tool / `superpowers:dispatching-parallel-agents` / TeamCreate）。\n- 它們共享**同一 process + 同一 cwd + 同一 working tree** → 隔離最硬：不能靠「不同視窗不同目錄」。\n- 可能解：每個 agent 用 `Agent(isolation: \"worktree\")`（harness 原生支援 per-agent worktree，跑完未變更會自動清除）；或限制平行只在 read-heavy phase（diagnose / verify 不碰 working tree），write phase（implement / commit）序列化。\n- Orchestrator = 主 session，負責分派 + 收斂 + 臨界區守門。\n\n### Case B — 多個 Claude Code 視窗 → 每視窗跑一個 IDD（across-window 平行）\n\n- 平行單位 = 獨立 Claude Code session（不同視窗），各自獨立 process。\n- 但若多視窗指向**同一 repo 目錄** → 仍 working-tree 互相覆蓋。\n- 可能解：每視窗開在自己的 git worktree（`.claude/worktrees/idd-<N>/`）或獨立 clone；`EnterWorktree` / `idd-implement --cwd` 直接適用。\n- 比 Case A 容易：視窗本就獨立 process，只要目錄分開、無共享 in-process 狀態。\n\n> 兩 case 共用下方衝突面，但 severity 不同：Case A 連 `.claude/.idd/` in-process staging 都共享、最硬；Case B 只要目錄隔離就解大半。\n\n## 衝突面盤點（待 diagnose 時細化）\n\n| 衝突資源 | 單序列下 | 平行下風險 | Case A | Case B |\n|---------|---------|-----------|--------|--------|\n| Git working tree | ✅ 安全 | 🔴 checkout 互相覆蓋 | 🔴 | 🔴（同目錄時）|\n| Branch HEAD | ✅ 安全 | 🔴 各自 commit 到同 branch | 🔴 | 🔴（同目錄時）|\n| `.claude/.idd/` 暫存 | ⚠ ms-nonce 部分緩解（#76）| 🟡 staging dir race | 🔴 in-process 共享 | 🟢 目錄分開即解 |\n| Attachment release upload | ✅ 安全 | 🟡 `--clobber` 同名互蓋 | 🟡 | 🟡 |\n| GitHub issue/PR state | ✅ 安全 | 🟢 GitHub 端 atomic，低風險 | 🟢 | 🟢 |\n\n## 候選方向（不預設答案，留 diagnose）\n\n1. **git worktree per IDD** — 每個 IDD 在 `.claude/worktrees/idd-<N>/` 有獨立 working tree + branch。對應現有 `superpowers:using-git-worktrees` skill + `idd-implement --cwd` flag。（Case B 主力解；Case A 用 per-agent worktree 變體）\n2. **isolation 改 process/container 層** — 各 IDD 跑在獨立 sandbox（重，但徹底）。\n3. **orchestrator 序列化臨界區** — read-heavy（diagnose/verify）平行，write-heavy（implement/commit）走 lock / queue。（Case A 主力解）\n4. **混合** — read 階段平行、write 階段隔離 worktree。\n\n## 既有 prior art（diagnose 起點）\n\n- `Agent(isolation: \"worktree\")`：harness 原生 per-agent worktree 隔離 —— **直接對著 Case A**。\n- `EnterWorktree` harness tool：Claude Code 原生支援 `.claude/worktrees/` 隔離 —— 對著 Case B。\n- `idd-implement --cwd` / `idd-verify --cwd`：已支援在指定 local clone 上操作（`references/cross-repo-cwd.md` 的 substitution rule）。worktree 隔離可視為「同 repo 多 clone」特例。\n- `idd-all-chain`：已做「ONE cluster branch + ONE review PR」的 spawn-manifest orchestration —— 但那是**單序列遞迴**，不是平行。\n\n## Out of scope\n- 不在此 issue 解 #164 的其他面向（verify ensemble 的 agent 數量、orchestration topology）。\n- 不實作 —— exploration seed，等 trigger（真的要開始 agent-teams 平行化）才 `/idd-diagnose`。\n\n---\n\n### Clarity Surface\n\n| Type | Term | Concern | Candidates | Status |\n|------|------|---------|-----------|--------|\n| ambiguity | 「平行做很多 idd」 | 平行的粒度未定 | (a) 平行整條 pipeline（issue→close）/ (b) 只平行 read-heavy phase（diagnose/verify）/ (c) 平行不同 root issue 的 idd-all-chain | **resolved @ 2026-05-30** — user 校正：軸選錯，真正軸是**執行拓樸**（Case A within-window agent teams / Case B across-window 多視窗）。原 a/b/c 是次級子問題。見「兩個 case」section |\n| missing-context | 「agent teams」 | 指 Claude Code TeamCreate/SendMessage 原語，還是泛指多 agent？沿用 #164 同一 ambiguity | 見 #164 candidates | **resolved @ 2026-05-30** — Case A 把「agent teams」定義為**單視窗內呼叫的平行 sub-agent 原語**（Agent tool / dispatching-parallel-agents / TeamCreate），非泛指。同步釐清 #164 該 row |\n\n### Linked-Context Siblings\nParent: #164（本 issue 是其工程約束子問題）\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-30 by /idd-diagnose\n\n### Key Decisions\n- 平行軸 = 執行拓樸（Case A within-window agent teams / Case B across-window 多視窗），非 pipeline 粒度（/idd-clarify 校正）\n- Complexity = **Spectra**（Layer 2 新 published surface + Layer 3 cross-spec impact + architectural decision）\n- 關鍵發現：git worktree 同時解 working-tree + `.claude/.idd/` staging 兩衝突面；硬點轉移到「收斂」（N worktree branch 的 merge-back）\n- Case B 先做（CP 值高、reuse 現有原語）；Case A 後做（orchestrator 收斂協定難）\n\n### Scope Changes\n- (none)\n\n### Blocking\n- (none) — closed via PR #168 (squash b11b65d). Spectra change archived. Follow-ups: #169 (convention reconciliation), #170 (post-IC detection).\n\n### Commits\n- (none — exploration seed, no implementation)\n\n\n" }, { "number": 169, @@ -337,7 +373,8 @@ "- (none) — diagnosed, awaiting pickup" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n#166（concurrent-session isolation for PR-path branch acquisition）和 #167（parallel IDD via worktree）**幾乎同時** landed，各自定義了一套 git worktree 公約，兩者 diverge：\n\n| 面向 | #166（`references/pr-flow.md` → \"Concurrent-session isolation\"） | #167（`scripts/idd-worktree.sh` + `references/worktree-isolation.md`） |\n|------|------|------|\n| Worktree location | `$(git rev-parse --git-dir)/idd-worktrees/${BRANCH##*/}`（在 `.git` 下） | `.claude/worktrees/idd-<N>/`（working tree 內、gitignored） |\n| 命名 key | branch name | issue number |\n| 生命週期 | ad-hoc inline snippet（手動 `worktree add` / `worktree remove`） | managed helper（create / cleanup / list + idd-close auto-GC） |\n| 觸發點 | idd-implement PR-path branch acquisition | 多視窗平行 IDD（Case B）|\n\n## Why this matters\n\n兩套公約在 `idd-implement/SKILL.md` 的 Phase 0.5 note 已被我**臨時 prose 橋接**（PR #168 rebase 時），標為「same convention at different ergonomic tiers」。但實際 location / 命名不同 → 若使用者照 #166 snippet 手動建 worktree，跟 #167 helper 建的不在同一個地方，`idd-worktree.sh list` / `idd-close` GC 看不到。這本身就是 #167 要解的「平行 session 各自為政」問題的一個實例。\n\n## Proposed direction（待 diagnose）\n\n1. **統一 location** — 讓 #166 的 pr-flow snippet 改用 `.claude/worktrees/idd-<N>/`（或反之），單一 source of truth。\n2. **#166 snippet → 呼叫 idd-worktree.sh** — pr-flow 的 ad-hoc `worktree add` 改成 `idd-worktree.sh create`，讓 managed lifecycle 涵蓋 PR-path branch acquisition 場景。\n3. 釐清 branch-key vs issue-key 命名在兩場景的對應。\n\n## Out of scope\n- 不重做 #167 已 ship 的 helper；這是把 #166 的 ad-hoc 路徑收進 #167 的 managed 公約。\n\n---\n**Source**: surfaced during /idd-close #167（PR #168 rebase 撞到 #166 merge，發現兩套 worktree 公約）。Sister concern from #167.\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-31 by /idd-diagnose\n\n### Key Decisions\n- Complexity = **Plan** → next: `/idd-plan #169`\n\n### Blocking\n- (none) — diagnosed, awaiting pickup\n\n### Commits\n- (none yet)\n\n" }, { "number": 170, @@ -346,7 +383,8 @@ "- (none) — closed via PR #171 (squash 4b79694). Follow-ups: #172 (membership semantics), #173 (template auto-close trap)." ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n`/spectra-archive` Step 7（`spectra-archive-post-ic.sh`，#56）負責 post `## Implementation Complete` 到 linked GitHub issue，觸發 `/idd-close` 的 supersession gate。但對 `idd-worktree-isolation` change 它回 `(none — no linked issue detected)`，雖然該 change 全程關聯 #167。\n\n## Root Cause（推測，待 diagnose 確認）\n\nhelper 的 linked-issue 偵測掃 archived `tasks.md` 找 **explicit marker** 或 `Refs #N` 形式。但 `/spectra-propose` 產出的 tasks.md 把 issue 號寫在 **prose**（例如 \"referencing issue #167\"），不是 `Refs #N` trailer 形式 → 偵測 miss。`--linked-issue 167` 也被拒（\"not in candidate set\"，因 candidate set 為空）。\n\n## Impact\n\n- Spectra-path issue 的 IC 沒自動 post → `/idd-close` gate 會 fall back 掃 diagnosis Strategy `- [ ]` → 誤 refuse，或需手動補 IC（本次 #167 就是手動補的）。\n- 破壞 #56 「Spectra-path 自動觸發 supersession」的設計目的。\n\n## Proposed Solution（待 diagnose）\n\n1. **擴大偵測來源** — 除 tasks.md 外也掃 `proposal.md`（IDD proposal 慣例會寫 issue link）。\n2. **或 spectra-propose 埋 marker** — 在 tasks.md 或 .openspec.yaml 寫一個 canonical `linked-issue: #N` 欄位，post-ic 直接讀。\n3. 修 `--linked-issue` override：candidate set 為空時應允許明確指定（目前空集合 → 拒所有）。\n\n## Workaround（已用於 #167）\n手動 compose `## Implementation Complete` comment + `gh issue comment`。\n\n---\n**Source**: surfaced during /idd-close #167（spectra-archive Step 7 對 idd-worktree-isolation 回 no-linked-issue）。Sister concern from #167.\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-31 by /idd-diagnose\n\n### Key Decisions\n- Complexity = **Simple** → next: `/idd-implement #170`\n\n### Blocking\n- (none) — closed via PR #171 (squash 4b79694). Follow-ups: #172 (membership semantics), #173 (template auto-close trap).\n\n### Commits\n- `203aeb1` fix: linked-issue escape hatch + prose detection (#170)" }, { "number": 173, @@ -355,7 +393,8 @@ "- (none — closed)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\nThe `idd-implement` Step 5.5 PR_BODY template emits:\n```\n- [x] **Verify-gated**: post-verify PASS = ready to merge → /idd-close #${NUMBER} after merge\n```\nGitHub's `closingIssuesReferences` (the authoritative parser the verify Step 0.8 **Source 1** relies on) parses `close #N` out of `/idd-close #N` — hyphen-splitting `idd-close` into the keyword `close`. So a PR opened by `idd-implement` on the PR path is **linked to auto-close its own issue on merge**, bypassing the `/idd-close` checklist gate + closing summary — the exact failure class #87/#97/#11/#13 fought.\n\n## Evidence (dogfooded this session)\n\nPR #171 (for #170) was opened with a body containing `/idd-close #170 after merge`. `gh pr view 171 --json closingIssuesReferences` returned `.../issues/170` (would auto-close). After rewriting the line to `run the idd-close skill manually on the issue` (no `close` adjacent to `#<digit>`), `closingIssuesReferences` went empty. So `/idd-close #170` was the trigger.\n\n## Contradicted assumption\n\n`idd-verify` Step 0.8 explicitly claims: *\\\"`/idd-close #N` 這類 skill invocation 在 Source 1 天然零誤判（不出現在 closingIssuesReferences）\\\"*. **Empirically false** — Source 1 (GitHub) applies no hyphen-prefix guard; only the plugin's own Source 2 regex (`[^-/[:alnum:]]` prefix) excludes it. The two sources genuinely disagree on `idd-close`, and Source 1 (the authority) flags it.\n\n## Impact\n- Every `idd-implement` PR-path PR (and likely `idd-all` / `idd-all-chain` using the same template) silently links to auto-close on merge → `/idd-close` gate bypassed unless the human notices or `idd-verify` Step 0.8 runs + the user heeds the warning.\n- This session's PR #167 (PR #168) likely had the same trap — it was squash-merged with a controlled message, so the body trap may or may not have fired; worth auditing.\n\n## Proposed fix (待 diagnose)\n- Change the idd-implement / idd-all / idd-all-chain / pr-flow.md PR_BODY templates to avoid `close`/`fix`/`resolve` immediately before `#<digit>`. E.g. `→ run the idd-close skill on this issue after merge (no auto-close trailer)`, or use literal-letter `#N`.\n- Update `idd-verify` Step 0.8's documented claim about Source 1 + `idd-close` (it is NOT zero-false-positive there).\n\n## Out of scope\n- The verify gate (Step 0.8) already CATCHES this at verify time (it warned on PR #171, which is how this was found) — the gate works. This is about the upstream **template** that creates the trap in the first place.\n\n---\n**Source**: surfaced during /idd-verify #170 --pr 171 Step 0.8 auto-close detection (the gate caught the plugin's own template on PR #171). Sister concern from #170.\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-05-31 by /idd-close\n\n### Key Decisions\n- Complexity = **Simple**; fixed 5 PR-body template instances + 2 stale idd-verify false claims + regression guard; v2.75.1\n- 6-AI verify (PR #174): PASS, 0 blocking; 4 non-blocking findings (DA MEDIUM + Codex HIGH) all fixed in-PR (5596453)\n- Squash-merged to main (870ce14); issue remained OPEN post-merge → auto-close did NOT fire (end-to-end proof of the fix)\n- Closed via /idd-close (the manual gate this change exists to protect)\n\n### Scope Changes\n- (none)\n\n### Blocking\n- (none — closed)\n\n### Commits\n- `870ce14` (squash on main) fix: PR-body templates no longer emit GitHub auto-close trap (#173)\n" }, { "number": 176, @@ -364,7 +403,8 @@ "- (none — closed)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n`/idd-list --audit-closes` + `scripts/check-closed-without-summary.sh` (shipped in #151, v2.75.2) **detect** issues that were auto-closed by a commit / PR-body close keyword without a `## Closing Summary` — i.e. they bypassed the `/idd-close` gate. But **remediation is still fully manual**: the user must read each flagged issue, reconstruct Problem / Root Cause / Solution / Verification, and hand-post a retroactive `## Closing Summary (retroactive — …)` comment.\n\nThis is the **retroactive-remediation tooling** that #151's diagnose-time Residue (NSQL §4.6) predicted Path B would \"naturally spawn if adopted\". The detection layer shipped; remediation is the natural next layer.\n\n## Type\nenhancement (builds on #151 Path B-lite)\n\n## Proposed direction (待 diagnose)\nA skill / helper that takes a flagged issue (from `--audit-closes`) and:\n- reconstructs a closing-summary draft from the issue's commits (`git log --grep #N`) + its Diagnosis / Implementation Complete comments\n- posts a `## Closing Summary (retroactive — auto-closed via <channel>)` comment (the existing remediation heading convention)\n- runs the post-hoc tail it still can (body Current Status → closed; distribution-sync prompt) — the issue is already CLOSED, so this is comment + body-sync remediation, not a re-close\n\nOpen questions for diagnose: semi-auto (draft + human confirm) vs fully-auto; per-issue vs batch over the `--audit-closes` set; how much of the `/idd-close` gate can meaningfully run after the fact.\n\n## Out of scope\n- The DETECTION layer (done in #151).\n- Preventive Path A (pre-push hook) / Path D (GitHub Action) — separate, still deferred from #151.\n\n---\n**Source**: residue from #151 at /idd-close time (Step 3.6)\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-06-01 by /idd-close\n\n### Key Decisions\n- Shipped `idd-close --retroactive` (Approach A); reuses Step 2/4/6 minus gate minus close; semi-auto, batch, idempotent; v2.76.0\n- 6-AI verify (PR #177): PASS; 5 non-blocking findings fixed in-PR; headline DA-1 → Verification-honesty 鐵律 (no fabrication)\n- Codex degraded this round (process gap); squash-merged (e6b1b3c); issue stayed OPEN post-merge → no auto-close\n- Residue: A/D + UI-close/cross-repo all already tracked in #151 (still residue, not re-filed)\n- Live remediation of #165 done as the falsifiable proof\n\n### Scope Changes\n- (none)\n\n### Blocking\n- (none — closed)\n\n### Commits\n- `e6b1b3c` (squash on main) feat: idd-close --retroactive remediation mode (#176)\n" }, { "number": 178, @@ -373,7 +413,8 @@ "- (none)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n`idd-update` Step 5 描述 managed-zone 的方式是「將原始 body 的 `---` 分隔線（含）以下替換為新的 Current Status」。這個規則錨在 **第一個 `---`**，假設「`---` 以下 == Current Status managed zone」。\n\n但 `/idd-issue` 產出的 body（尤其 parking-lot seed）在第一個 `---` **以下**放的是 **audit blocks**，不是 Current Status：\n\n```\n[original record: Problem / Type / ...]\n---\n### Clarity Surface\n| ... | surfaced/resolved |\n### Linked-Context Siblings Filed\n(...)\n```\n\n照 Step 5 字面「replace below first `---`」執行 → **靜默刪掉 Clarity Surface + Linked-Context Siblings audit blocks**。這是 silent data loss：clarity 解析、linked-context 紀錄全沒了，且 caller 收到的只有「✓ status updated」，不會發現 audit 被吃掉。\n\n## Repro\n\n1. 任何用 `/idd-issue` 建的 issue，body 在 `---` 下有 `### Clarity Surface`（無 `## Current Status`）。\n2. 跑 `/idd-update #N`（或被 `idd-diagnose` Step 5 自動呼叫）。\n3. 若照 Step 5 字面 replace-below-`---` → audit blocks 消失。\n\n實證：本 issue 由 `/idd-diagnose #164` 的 Step 5 自動呼叫 idd-update 時撞到（#164 body 在 `---` 下有剛 resolve 的 Clarity Surface）。當下手動改走 append 分支才沒刪到，但 skill text 會誤導較不謹慎的執行者。\n\n## Type\n\nbug（spec gap / footgun in published skill）\n\n## Root cause（初判）\n\nStep 5 的兩個分支沒涵蓋「有 `---` 但 `---` 下不是 Current Status」這個 case：\n- branch 1：有 `---` + Current Status → replace below `---`\n- branch 2：無 `---` 且無 Current Status → append\n- **未涵蓋**：有 `---`、下方是 audit blocks、無 `## Current Status` → 字面落入 branch 1 → 誤刪\n\n## Suggested fix（方向，待 diagnose 確認）\n\n把 managed zone 錨在 **`## Current Status` heading** 而非第一個 `---`：\n\n- 若 body 含 `## Current Status` → 從該 heading（含其上緊鄰的 `---`，若有）到 body 結尾替換。\n- 若 body 無 `## Current Status` → **append** 到結尾（保留所有既有內容，不論有幾個 `---`）。\n\n`---` 在 IDD body 裡語意不唯一（既分隔 original/audit，也可能分隔 audit/status），不能當 managed-zone 的唯一錨。\n\n## Impact\n\n- 影響的 skill：`idd-update`（被 idd-diagnose / idd-plan / idd-implement / idd-verify / idd-close 的 Step N Auto-Update 自動呼叫 → blast radius 大）。\n- 影響的 issue 類型：所有 `/idd-issue` 產的、`---` 下有 audit blocks 而無 Current Status 的 body（parking-lot seeds、含 Clarity Surface / Linked-Context Siblings 的 issue）。\n\n**Source**: surfaced during /idd-diagnose #164 Step 5 (idd-update auto-call) — dogfood catch on plugin's own repo\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-06-01 by idd-close\n\n### Key Decisions\n- RCA: idd-update Step 5 anchored managed-zone on first `---`, not `## Current Status` heading. Fixed all 4 prose spots (Branch A replace-from-heading / Branch B append-preserve-all). Strictly backward-safe. `66ac7b9`, v2.77.2.\n- Verify: light (prose-only) PASS — dogfood ×4 on this issue's own body (diagnose B / implement A / verify A / close A).\n\n### Scope Changes\n- (none)\n\n### Blocking\n- (none)\n\n### Related\n- Sister bug **#181** filed (idd-diagnose Step 0.5 same naive-grep class).\n\n### Commits\n- `66ac7b9` fix: anchor idd-update managed-zone on `## Current Status` heading not first `---` (#178); bump 2.77.1 → 2.77.2\n\n### Verification\n- **PASS** (light) — closed with full closing summary; distribution sync (push + marketplace reload 2.77.2) executed.\n" }, { "number": 179, @@ -382,7 +423,8 @@ "- (none)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Original observation** (user, dogfood session 2026-06-01, repo `PsychQuant/che-transport-mcp`):\n> 「我發現多個 stage 的事情不會在 idd 這個 plugin 做特別的處理，這應該是要有一個 issue 和 sub-issue 來處理的吧」\n>\n> — Source: 建立 che-transport-mcp 的「(B) 大眾運輸路由引擎」北極星時，自然分成 Stage 1 / 2 / 3。IDD 沒有 first-class 機制處理這種多階段結構，只能手動把 `che-transport-mcp#7` 當成「north-star epic + Stage 1」混在同一個 issue，Stage 2 / 3 用 prose 註記為「future issues」。\n\nIDD 目前有兩個多-issue 結構機制，但**都無法表達「漸進式、有序的多階段路線圖（north-star）」**：\n\n| 機制 | 形狀 | 為什麼不適合多-stage 路線圖 |\n|------|------|------------------------------|\n| `--bundle-mode ordered/unordered`（idd-issue）| epic + **全部 children 一次建好** | 後期 stage 在前期 stage 出貨**之前還沒設計**，無法 upfront 建。`--bundle-mode` 要求一次列出所有 children。 |\n| Milestone-first（#83）| **扁平**分組 cross-cluster | 沒有「順序」與「stage 隨時間浮現」語意。Milestone 把現存的一群 issue 群組起來，不表達 Stage N+1 在 Stage N 之後才設計。 |\n\n**多-stage（north-star）路線圖的特徵**，現有機制都沒覆蓋：\n\n1. **漸進浮現** — Stage 2 的設計發生在 Stage 1 **出貨之後**（無法、也不該 upfront 建所有 stage-issue）。\n2. **有序依賴** — Stage N+1 build on / depends on Stage N。\n3. **Epic 跨多個完整 cycle 持續存在** — 每個 stage 各自跑完整 diagnose → propose → apply → archive。Epic 本身不是 single deliverable（同 #83 觀察到的「Epic issue 沒有 lifecycle phase」mismatch）。\n\n## Type\nfeature\n\n## Expected\n\nIDD 對「漸進式多階段（north-star）epic」有 first-class 慣例或機制，例如：\n\n- 一個 persistent 的 north-star tracker（issue 或 milestone）記錄完整 roadmap（Stage 1..N），其中**未來 stage 只是 roadmap 條目、尚未 file 成 issue**。\n- 每個 stage 在**開始時**才 file 成它自己的 issue（走完整 IDD lifecycle），並 link 回 north-star tracker。\n- `idd-list` 對 north-star tracker 不顯示 `(no phase)` 噪音（同 #83 的 phase mismatch）。\n- 可能的 flag/SOP：例如 `idd-issue --stage-of <tracker> \"Stage N: ...\"` 或 north-star tracker body 的 roadmap-checklist 慣例（已 file 的 stage 勾選 + link，未 file 的留 roadmap bullet）。\n\n具體機制（新 flag vs SOP vs 擴充 milestone-first）留給 diagnose / discuss 決定。\n\n## Actual\n\n- `--bundle-mode` 只能 upfront 建全部 children → 對「stage 隨時間浮現」不適用。\n- Milestone-first（#83）扁平分組 → 無 ordering、無「stage 之後才浮現」。\n- 結果：ad-hoc。che-transport-mcp#7 被迫把「north-star epic」與「Stage 1」混在一個 issue，Stage 2/3 只能 prose 註記，沒有結構化追蹤。\n\n## Impact\n\n- 影響的 IDD 面：`idd-issue`（bundle-mode 的邊界）、`idd-list`（epic/tracker 的 phase 顯示）、可能 `idd-all-chain`（#81）。\n- **Related（maintainer 請評估是否合併）**：\n - **#83**（milestone-first for cross-cluster）— 本 issue 是其「**有序、漸進式 staged**」變體；若認定 milestone-first + 一個 ordering 慣例已足夠覆蓋，可關此 issue 併入 #83。\n - **#81**（bundle / chain mental-model unification）— 相鄰；chain 處理「已衍生的 sub-issue 全解掉」，本 issue 處理「stage 尚未浮現」的前段。\n- Motivating real case：`PsychQuant/che-transport-mcp#7`（(B) 路由引擎北極星，Stage 1 已 ship v0.6.0，Stage 2/3 待 file）。\n\n## Open design questions（for diagnose / discuss）\n\n1. Milestone-first（#83）+ 一個 ordering 慣例，是否已足夠？還是需要獨立機制？\n2. Persistent north-star tracker 與「per-stage 漸進 file」之間如何 link？\n3. 「Sub-issue 之後才浮現」如何避免 `--bundle-mode` 的 upfront 限制 — 是新 flag、新 skill、還是純 SOP？\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-06-03 by idd-close\n\n### Key Decisions\n- Full Spectra cycle: diagnose → discuss (minimal SOP, not flag/skill; complementary to #83/#81) → propose → apply → archive → close. `c0f9313` + `df2b3c1`, v2.82.0.\n- Deliverables: references/north-star-tracker.md SOP + idd-list tracker-phase display (shared with #83) + bundle-flags cross-ref. Spectra capability `north-star-tracker` in openspec/specs/.\n\n### Scope Changes\n- (none)\n### Blocking\n- (none)\n### Commits\n- `c0f9313` feat: north-star tracker SOP + shared idd-list tracker-phase display (#179)\n- `df2b3c1` chore: archive + materialize spec with Purpose (#179)\n### Verification\n- **PASS** (light) — implementation matches spec 3 requirements + examples; verify-found example-gap fixed same-change. Distribution sync (push + reload 2.82.0) executed.\n" }, { "number": 180, @@ -391,7 +433,8 @@ "- (none)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n4 specs in `openspec/specs/` still carry the literal Spectra archive-stub Purpose:\n\n> TBD - created by archiving change '<X>'. Update Purpose after archive.\n\nThis is the exact opacity bug just fixed for `idd-orchestrator-modes` (renamed → `idd-pr-hitl-modes` + real Purpose; commit `b6fd718`, v2.76.1). The stub is opaque on sight — a reader cannot tell what the spec governs (\"modes of *what*?\").\n\n| Spec | Stub origin (source change) |\n|---|---|\n| `idd-all-chain` | add-idd-all-chain-skill |\n| `idd-ic-r011-checkpoint` | idd-ic-r011-default-file |\n| `idd-spawn-manifest` | add-idd-all-chain-skill |\n| `idd-worktree-isolation` | idd-worktree-isolation |\n\nAudit note: `append-vs-modify-discipline` showed up in the grep but is a **false positive** — its Purpose is real (\"Defines the action-scoped modify discipline…\"); the word \"TBD\" just appears in the body. NOT in scope.\n\n## Root Cause\n\nSpectra archive materializes a new capability from a delta that has no `## Purpose` (Purpose is not in the delta schema), so it writes the `TBD … Update Purpose after archive` stub and relies on a human to fill it later — with zero enforcement. Nobody filled these 4.\n\n## Proposed Solution\n\nMechanical, doc-only, zero behavior change — same move as the `idd-pr-hitl-modes` fix: give each of the 4 specs a real, intent-revealing one-sentence Purpose stating what the capability governs. Direct edit of each `openspec/specs/<name>/spec.md` Purpose section (the delta model cannot express a pure Purpose-fill — see Prevention).\n\n## Scope boundary (this is NOT \"spec every skill\")\n\n**Purpose-quality only, NOT spec-coverage.** We are explicitly NOT speccing every idd skill — that is over-spec (per `idd-diagnose` Step 3.5 Layer 1: Plan/Spectra is dead weight for prose / no-external-contract skills). Skills like `idd-comment` / `idd-config` / `idd-report` / `idd-edit` being prose-only is correct, not a gap. This issue touches ONLY the Purpose text of specs that already exist.\n\n## Prevention (structural pairing)\n\nThis issue is the **backlog** (pre-existing stubs). The **structural prevention** (have archive/validate lint/flag any spec whose Purpose is still the TBD-stub, so promoted specs cannot silently ship opaque) was raised upstream as an **inquiry** to the Spectra maintainers: **kaochenlong/spectra-app#100** — framed as questions, since Spectra is a closed app and this is a behavioral observation against spectra 2.3.1, not verified against source. (Note: the in-app `spectra feedback` CLI turned out to be a local echo pointing to a dead URL; the live repo is `kaochenlong/spectra-app`, not the `kaochenlong/Spectra` the binary prints.) If/when such a lint lands, no new stubs can appear; these 4 are the pre-lint backlog.\n\n## Success Criteria\n\n- All 4 specs above have a real Purpose (no `TBD … Update Purpose after archive` string remains in any `openspec/specs/*/spec.md`).\n- `grep -rl \"Update Purpose after archive\" openspec/specs/` returns empty.\n- No behavior change; no requirement deltas.\n\n**Source**: surfaced during /idd-diagnose #164 + /spectra-discuss (naming + Purpose lesson; sister of the idd-orchestrator-modes → idd-pr-hitl-modes rename, commit b6fd718)\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-06-01 by idd-close\n\n### Key Decisions\n- Filled TBD-stub Purpose for 3 specs (idd-all-chain / idd-spawn-manifest / idd-worktree-isolation) — intent-revealing one-paragraph Purpose naming capability + key Requirements. `d7ea0a9`.\n- Scope收斂 4 → 3（idd-ic-r011-checkpoint folded via #152）→ 全 repo TBD-stub backlog 清空（0 殘留）.\n- Complexity: Simple (doc-only). Verify: light PASS.\n\n### Scope Changes\n- (none)\n\n### Blocking\n- (none)\n\n### Commits\n- `d7ea0a9` chore: fill TBD-stub Purpose for 3 specs (#180)\n\n### Verification\n- **PASS** (light) — grep 0 residual stub; zero normative drift. Closed with full closing summary. Root-cause prevention is upstream (kaochenlong/spectra-app#100).\n" }, { "number": 181, @@ -400,7 +443,8 @@ "- (none)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n`idd-diagnose` Step 0.5 Clarity Surface gate 用裸 grep + awk 偵測 `### Clarity Surface` annotation block，**未先剝除 fenced code blocks**：\n\n```bash\nif echo \"$BODY\" | grep -q '^### Clarity Surface'; then\n BLOCK=$(echo \"$BODY\" | awk '/^### Clarity Surface/{flag=1; print; next} flag && /^### /{flag=0} flag')\n SURFACED_COUNT=$(echo \"$BLOCK\" | grep -cE '\\| surfaced \\|')\n ...\n```\n\n當 issue body 在 ` ``` ` code fence 內**示意**一個 Clarity Surface block（例如一個討論 clarity 機制、或記錄 audit-block 結構的 issue），裸 grep 把示意 code 當成**真的** annotation block → gate 誤判 → **false-positive REFUSE**，擋下一個本該 PROCEED 的 diagnose。\n\n## Type\n\nbug（spec gap / footgun in published skill — `idd-diagnose` SKILL.md Step 0.5）\n\n## Repro（實證 — dogfood catch）\n\n1. Issue body 在 code fence 內含 `### Clarity Surface`（示意，非真 annotation；body 內無真 surfaced/deferred 表格列）。\n2. 跑 `/idd-diagnose #N`。\n3. Step 0.5 gate 的 `grep '^### Clarity Surface'` 命中 fence 內那行 → 進 refuse 分支。\n\n**實證**：診斷 #178 時親自撞到——#178（本 issue 的 parent）body line 10 的 `### Clarity Surface` 在 code fence（line 7–14）內，是用來**示意** idd-update 吃掉 audit block 的 bug，不是真 annotation。手動數 fence 數量（奇偶）才確認是 false positive、PROCEED；但 SKILL.md 的 gate prose 不做這個剝除，較不謹慎的執行者會被誤導 refuse。\n\n## Root cause（初判）\n\nStep 0.5 的 grep/awk 是**無語意感知的結構匹配**——`^### Clarity Surface` 在 markdown 語境下，fence 內與 fence 外意義完全不同，但裸 grep 一視同仁。這跟 #178 同屬一個 class（idd-update 用 `---` 當錨、本 gate 用 `### Clarity Surface` 當錨，都缺 markdown-aware 前處理）。\n\n## Suggested fix（方向，待 diagnose 確認）\n\n在 Step 0.5 grep/awk **之前**先剝除 fenced code blocks，沿用 `idd-list` Step 3.5（#14）已驗證的 `strip_fenced_code()`：\n\n```\nFENCE_RE = ```[\\s\\S]*?``` # 同 idd-list references impl\nBODY_STRIPPED = strip_fenced_code(BODY)\n# 之後所有 grep '^### Clarity Surface' / surfaced-row count 改用 BODY_STRIPPED\n```\n\n`idd-list` Step 3.5 早就為**完全相同**的 false-positive class 加了 `strip_fenced_code()`（PR-ref scan 把 ` ```bash Refs #99 ``` ` 誤當真 ref）——本 gate 應 reuse 同一前處理。Inline code（`` `### Clarity Surface` ``）是否也剝可比照 idd-list 決策（idd-list 選擇不剝 inline，false-positive 較罕見）。\n\n## Impact\n\n- **檔案**：`plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md`（Step 0.5 gate bash block）。\n- **影響流程**：任何 body 在 code fence 內提及 `### Clarity Surface` 的 issue（討論 clarity 機制本身、記錄 IDD body 結構、或像 #178 這種 meta issue）會被 gate 誤擋，使用者被迫先 dismiss 一個不存在的 surfaced row 才能 diagnose。\n- **跨 skill 一致性**：idd-list 已解、idd-diagnose 未解 → 同一 plugin 內前處理不一致。\n\n**Source**: surfaced during /idd-diagnose #178 sister concern surfacing (Step 3.6)\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-06-01 by idd-close\n\n### Key Decisions\n- Step 0.5 Clarity gate 加 BODY_SCAN fence-stripper (awk), 3 scan sites use it. Mirrors idd-list #14. `d2a2607`, v2.78.1.\n- Falsifiable test 2 fixtures PASS (fence-only PROCEED / real table REFUSE). Simple.\n\n### Scope Changes\n- (none)\n### Blocking\n- (none)\n### Commits\n- `d2a2607` fix: strip fenced code in idd-diagnose Step 0.5 Clarity gate before scanning (#181)\n### Verification\n- **PASS** (light) — closed with full summary; distribution sync (push + reload 2.78.1) executed. Closes the naive-structural-match sister pair with #178.\n" }, { "number": 183, @@ -409,7 +453,8 @@ "- (none)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n多個 IDD agent session 並行對**同一個 repo**跑 `idd-implement` 的 **direct-commit-on-main** 路徑時，它們共用**同一個 working tree**，互相踩踏。\n\n> **Original (user, 2026-06-03)**：\n> 「可以在 idd 裡面開問題嗎？像你發現會撞，我覺得就是預設沒開 worktree 的結果，或者你覺得有什麼更好的方法嗎」\n\n## Type\nenhancement（design FR：並行 session 的 working-tree 隔離策略）\n\n## Evidence（real incident，2026-06-03，`ai_martech_global_scripts` 上連續 ~3 個並行 agent session）\n\n碰到的具體症狀：\n\n1. **main tree 被別 session parked 在它的 feature branch**：我（session A）在 `main` 上 commit #1059；稍後另一 session 在**同一個 main working tree** checkout 了 `idd/cluster-...` branch → 我回來時 `git status` 跟前一次檢查**結果不同**（檔案在兩次 `git status` 間出現/消失）。\n2. **兩個 session 改同一個檔案**：`union_production_test.R` 同時有我的 #1059 footer hunk（line ~600）和別 session 的 #1067 default-product-line hunk（line ~429）。`git add <file>` 會把對方未完成的 hunk 一起 commit → 我被迫用 `git add -p` 外科式只 stage 自己的 hunk（leak check 確認 #1067 沒混進去）。\n3. **orphaned commit（最毒）**：#1066 的 crash fix commit 在 cluster branch（`c2cc7b5`），但 PR #1076 merge 的是**不含它的版本** → 一個 live Shiny crash（positionKFE AI 按鈕 `object 'ns' not found`）留在 main 上沒被發現，直到我用 `git cherry -v origin/main <branch>` patch-id 比對才抓到 orphan。\n\n## Root Cause（兩個正交的失敗模式）\n\n**FM-1 — 共享 working tree 並行碰撞**：direct-commit-on-main 路徑（many repos / 慣例如此）**沒有預設 worktree 隔離**，N 個並行 session 共用一個 tree → branch parking、同檔 WIP 混合、`git status` race。**這正是 user 的 hypothesis。**\n\n**FM-2 — orphan commit**：branch 上的 commit 沒進 main（PR merge 了 partial 版本 / branch 分歧）。**worktree 救不了 FM-2** —— 反而 branch-per-issue 工作流（worktree 鼓勵的）放大了它：每條 branch 都要 merge 回去，merge 不完整就 orphan。\n\n## Design options\n\n### FM-1（並行碰撞）\n\n| 選項 | 做法 | Trade-off |\n|------|------|-----------|\n| **A. 無條件 worktree-default** | 每個 `idd-implement` 都 `idd-worktree.sh create #N`，在自己的 worktree 工作 | 結構解，但每 session 一份 checkout（~200-500ms + disk）；**跟 direct-commit-on-main 慣例衝突**（worktree 各自要 branch → 失去「直接 commit main」的簡單性，且每條都要 merge 回去 → **放大 FM-2**） |\n| **B. 條件式 worktree（偵測並行才隔離）** | solo session 維持輕量 direct-commit；偵測到 ≥2 active IDD worktree/session（或 lock）時，**才**強制 worktree 隔離 | best-of-both：solo 不被課稅，並行才付隔離成本。需要可靠的 concurrency-detect signal（worktree registry / lock file / process scan） |\n| **C. 共享樹 lock/guard** | pre-commit / pre-checkout guard 偵測「另一 IDD session 正在這個 tree 活動」→ refuse/warn before parking branch 或 staging 進 dirty shared tree | 最輕，但不解結構問題，只 surface |\n\n### FM-2（orphan commit）—— 獨立 fix，跟 worktree 正交\n\n**merge-completeness gate**：在 `idd-close`（或 PR-merge 後）跑 `git cherry -v origin/main <branch>`（patch-id 比對），確認 branch 每個 commit 的 content 都到了 main 才算 done。`+`（patch-id 不在 origin）的 commit 須逐一驗證 content 已在 origin（merge context 造成 sha 不同的 false-positive）或 genuinely orphan。**這會抓到 #1066。** 成本低、跟 worktree 決策無關、價值高。\n\n## Recommendation（我的「更好方法」）\n\n- **FM-1 → 選 B（條件式 worktree）**，不是 A。無條件 worktree-default 對 solo session 是 dead-weight 且跟 direct-commit 慣例打架；只在偵測到並行時強制隔離，兩全。\n- **FM-2 → 加 merge-completeness gate 到 idd-close**，獨立於 worktree 決策。這是這次 incident 真正救命的東西（FM-1 只是讓人不舒服，FM-2 是 live customer crash 漏到 main）。\n\n## Impact\n- `idd-implement`（Step 0.5 PR/direct-commit path resolution + worktree acquisition）\n- `idd-worktree.sh` / `references/worktree-isolation.md`（concurrency-detect signal）\n- `idd-close`（新增 merge-completeness gate — FM-2）\n- 影響所有用 IDD 的 repo，不只 ai_martech\n\n## Decision points（留給 diagnose / discuss）\n- FM-1 走 A / B / C？（我推 B）\n- B 的 concurrency-detect signal 怎麼定義（worktree count / lock / process scan）？\n- FM-2 的 gate 放 idd-close 還是也放 idd-verify（PR mode）？\n- FM-1 + FM-2 是否拆兩個 change / 兩條 PR（建議：是，正交）\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-06-10 by idd-close\n\n### Key Decisions\n- Verify R1 FAIL → rescope：lock 記 `$PPID`（持久）非 `$$`（ephemeral，會讓 lock 變 no-op）；scope = cross-terminal，同 instance 並行留 Case A\n- 收斂 Option D（lock-based 非對稱 escalation）：先到者免費持 main tree，後到者偵測 live holder 自己 escalate 進 worktree\n- Complexity = Spectra；change `concurrent-session-tree-lock`（8/8 tasks，archived 2026-06-10）\n- FM-2 orphan gate 拆 #184（已於 v2.84.0 先行 shipped）\n\n### Scope Changes\n- (none — FM-1 only，per diagnosis split)\n\n### Blocking\n- (none)\n\n### Commits\n- `82af476` feat: concurrent-session tree-lock — asymmetric escalation\n- `a0f91a1` chore: archive spectra change\n" }, { "number": 186, @@ -418,7 +463,8 @@ "- (none)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Spec (idd-diagnose SKILL.md Step 1.5)**:\n> 「`0` — 下載完成(或 issue 無 attachment,empty manifest 已寫)」\n> 「**沒有 attachment** → script 寫空 manifest 後 exit 0,Diagnosis Report 標明「issue 無 attachment」。」\n\n實際行為（v2.84.0，2026-06-10，於 kiki830621/collaboration_su_ying_huang#26 diagnose 過程觀察）：\n\n```\n$ IDD_CALLER=idd-diagnose bash .../scripts/process-attachments.sh download 26\nexit=1\n# stdout/stderr 皆空\n# .claude/.idd/attachments/issue-26/ 目錄建立但無 _manifest.json\n```\n\nIssue #26 body 無任何 attachment URL（GitHub release asset / user-attachments），預期走「無 attachment → 空 manifest + exit 0」路徑。\n\n## Type\nbug\n\n## Expected\n- exit 0\n- `.claude/.idd/attachments/issue-26/_manifest.json` 寫入空 manifest\n- caller（idd-diagnose）可直接在 report 標明「issue 無 attachment」\n\n## Actual\n- exit 1（語意 = 「部分檔案下載失敗」，誤導 caller）\n- 無 manifest 檔\n- 無任何錯誤訊息（silent failure，違反「禁止靜默」原則）\n\n## Impact\nidd-diagnose / idd-implement 的 attachment check 對零附件 issue 一律收到 false-negative exit code；下游「manifest 缺漏 → 警告重跑 diagnose」邏輯被誤觸發。\n\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-06-10 by idd-close\n\n### Key Decisions\n- 修 `detect_urls()` single point（三 call site 同修）；顯式 `|| return 2`（$() 不繼承 errexit — fixture f5 抓到 set-e-based 修法會吞 gh 故障）\n- 6-AI verify PASS（首次完整 ensemble 含 Codex）；Codex MEDIUM 經 DA 實證仲裁 reject\n- #185 duplicate 併入（RCA 證據保留）；sisters: #188（assert-helpers eval 陷阱）、#189（corrupt manifest silent PASS）\n- Complexity = Simple；Conflict Class = A_parallel_safe\n\n### Blocking\n- (none)\n\n### Commits\n- `989e117` fix: process-attachments zero-attachment silent death\n- `3b3765f` docs: exit-2 fetch-failure + test comment de-drift\n" }, { "number": 189, @@ -427,7 +473,8 @@ "- (none)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n`process-attachments.sh` 的 `check` 與 `verify` 對 **corrupt `_manifest.json`**（無效 JSON）都 **silent PASS exit 0**：\n\n- `check`：`KNOWN=$(jq -r '.files[].url' \"$MANIFEST\" 2>/dev/null | sort -u || true)` — jq parse 失敗被 `2>/dev/null || true` 吞掉 → `KNOWN` 空 → 與 `CURRENT` 比對照常進行 → 實測輸出 `✓ Manifest up-to-date ( files)` exit 0（注意 file count 是空字串）\n- `verify`：manifest-listed files 的迴圈經 process substitution 讀 jq 輸出 — jq 失敗時 substitution 的 exit **永不傳播** → 迴圈零次執行 → 實測輸出 `✓ All attachments present` exit 0\n\n**而 `verify` 是 `idd-close` Step 1.4 的 gate** — corrupt manifest 會讓 close gate 拿到 false PASS。\n\n## Type\nbug\n\n## Reachability（非理論）\n\n`_manifest.json` 是 **git-tracked**（deliberate design，`.claude/.idd/attachments/` 不在 gitignore）→ merge conflict markers（`<<<<<<<`）是真實的 corruption path。實測 `NOT VALID JSON` 內容 → check/verify 雙雙 exit 0。\n\n## Expected\n\ncorrupt / unparseable manifest → 非零 exit + 可見錯誤（建議語意：同 #186 後的 exit 2 = 資料層失敗），引導使用者重跑 `download` 重建 manifest。不得 silent PASS — 這正是 #186 同款「失敗被吞成正常」class，只是位置從 detect_urls 移到 manifest 讀取端。\n\n## Refs\n\n#186 verify Devil's Advocate Task 4 發現（實測重現含輸出）；同 class 前例 #186（detect_urls）\n\n**Source**: surfaced during /idd-verify #186 follow-up triage (Step 5b)\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-06-15 by idd-close\n\n### Key Decisions\n- `assert_manifest_valid` shape-check（type==object and .files==array）在 check+verify 守 corrupt manifest → exit 2 loud\n- verify Q3 in-scope fix（0-byte/schemaless 同 (a') class，guard 升級非 over-engineer）\n- verify 是 idd-close gate；三個 caller exit-code 表補 exit-2 row\n- 同 #186 swallow-failure-into-success class 第三個位置（fetch → parse → shape）\n- Complexity = Simple；無 sister bug\n\n### Blocking\n- (none)\n\n### Commits\n- `be6f798` fix: corrupt-manifest silent PASS (assert_manifest_valid)\n- `e61b111` fix: manifest guard validates shape not just parseability (verify Q3)\n" }, { "number": 209, @@ -436,7 +483,8 @@ "- (none) — closed" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Original text**:\n> 「我在想深度整合的事情，有一個主要的rule是深度整合>>hard coded，你可以寫進 .claude/rules 裡面，像是我有綁其他套件，現在我想要跟superpower做深度整合」\n> — Source: user prompt（2026-07-02，/idd-issue invocation）\n\n使用者要確立一條專案級原則：**「深度整合 >> hard-coded」** — 當 IDD 需要某種能力、而生態系已有對應套件（plugin / skill）時，優先與該套件深度整合，而不是在 IDD 內部 hard-code 一份等價邏輯。具體包含兩個部分：\n\n1. **原則文件化**：把「深度整合 >> hard-coded」寫進 `.claude/rules/`（成為 repo 內 Claude session 的常駐 rule，與既有 `attribute-assessment.md` 同層）。內容應涵蓋：適用範圍、判準（什麼時候整合、什麼時候例外允許 hard-code）、反例。\n2. **首個應用對象 = superpowers plugin**：盤點 IDD skills 與 superpowers skills（`brainstorming` / `test-driven-development` / `systematic-debugging` / `verification-before-completion` / `writing-plans` 等）的重疊與銜接點，設計深度整合方式（哪些 IDD 步驟 delegate 給 superpowers、哪些保留在 IDD 內部）。\n\n先例 context：IDD 已有「綁其他套件」的整合模式（如 idd-issue Step 1 source adapters 綁 `che-word-mcp` / `che-telegram-mcp` / `che-apple-mail-mcp`）。本 issue 是把這個既有實踐升格為明文原則，並延伸到 process-discipline 層（superpowers）。\n\n## Type\nfeature\n\n## Priority\nP1（本週）— filing 時 AskUserQuestion 60s 無回應，依「現在我想要跟 superpowers 做深度整合」的語氣以 best-judgment 預設；如不符請回覆修正。\n\n## Expected\n\n- `.claude/rules/` 新增一條 rule，明文化「深度整合 >> hard-coded」原則（適用範圍、判準、例外條件、反例）\n- IDD × superpowers 的整合點被盤點並落地：重疊的 process 紀律（TDD、debugging、brainstorming、verification）有明確的 delegate-or-keep 決策與實作\n\n## Actual\n\n- 原則目前只存在於使用者腦中，未文件化；未來擴充時「自己寫 vs 整合既有套件」的決策靠隱性判斷，容易漂移\n- IDD 與 superpowers 各自獨立運作：IDD 內部自帶 TDD / verify 紀律，superpowers 也有同類 skills，兩套 process 紀律在同一 session 並存但互不銜接\n\n## Impact\n\n- 無明文 rule → 重複造輪子且與生態系脫節的風險持續累積\n- superpowers 是 session 常駐 plugin（using-superpowers 強制 skill-first）；IDD 不整合會出現兩套紀律互相競爭（例如 idd-implement 的 TDD loop vs `superpowers:test-driven-development`），使用者需自行仲裁\n\n### Clarity Surface(idd-clarify run 2026-07-02T09:16:51Z, unattended)\n\n| Type | Source | Suggested canonical | Status | Reason |\n|---|---|---|---|---|\n| ambiguity | \"現在我想要跟superpower做深度整合\" | 「深度整合」的具體形態未指明 — 候選:(a) detect-and-delegate（soft integration，缺 superpowers 時 fallback 到 IDD 內建邏輯）(b) hard dependency（IDD 步驟直接要求 superpowers 存在）(c) 僅文件層 cross-reference。IDD 是對外發佈的 plugin，此選擇影響所有安裝者 | resolved @ 2026-07-02T11:44:19Z (reason: 使用者:「我覺得要hard，保證品質」→ hard dependency，IDD 直接要求 superpowers 存在，不做 soft fallback) | unattended-auto-Step-4.6-deferred |\n| ambiguity | \"像是我有綁其他套件\" | 「其他套件」未列舉 — 推測指 idd-issue Step 1 source adapters（che-word-mcp / che-telegram-mcp / che-apple-mail-mcp / che-apple-notes-mcp），但先例集合待使用者確認 | resolved @ 2026-07-02T11:44:19Z (reason: 使用者:「pai-parallel 這個」→ 既有綁定先例 = parallel-ai-agents（pai-ensemble），非 source adapters) | unattended-auto-Step-4.6-deferred |\n| missing-context | \"你可以寫進 .claude/rules 裡面\" | rule 的載體/scope 未指定 — 專案 `.claude/rules/`（僅本 repo session 生效，plugin 安裝者拿不到）vs `plugins/issue-driven-dev/rules/`（隨 plugin 發佈給所有使用者）vs 全域 `~/.claude/CLAUDE.md`。同 attribute-assessment.md 已明文記錄的 trade-off，rule 放哪決定誰受約束 | resolved @ 2026-07-02T11:44:19Z (reason: 使用者:「不用一起上傳，是我開發要用的而已」→ rule 放專案 .claude/rules/ 即可，不隨 plugin 發佈) | unattended-auto-Step-4.6-deferred |\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-07-03 by idd-close (via idd-update)\n\n### Key Decisions\n- Closed with full audit trail：Closing Summary + 兩輪 6-AI verify（R1 FAIL→fix→R2 PASS）\n- 版本 2.90.0（BREAKING 標記，維持 repo 2.x 慣例 — close 時決定，不升 major）\n- D1–D5 全數落地；residue acknowledged as still residue（maintainer judgment 留權）\n- 深度整合形態 = hard dependency；rule 常駐（CLAUDE.md @-import）；先例 = pai-ensemble\n\n### Scope Changes\n- R3 安裝期依賴 bootstrap（diagnose 時追加）；sister #210 / follow-ups #211 #212 分出\n\n### Blocking\n- (none) — closed\n\n### Commits\n- `1e66b28` / `8ddc113` / `d8a1b3d`（已 push origin/main）" }, { "number": 214, @@ -445,7 +493,8 @@ "- (none) — closed；4 commits 已 push；residue acknowledged as-is；distribution chain 進行中" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **Original text**:\n> 「我發現有一個rule是我想要注入使用者的，有一些是我自己開發要用的，好像兩個要分開」\n> — Source: user prompt（2026-07-03，/idd-all invocation）\n\n目前 repo 的 rules 散在兩層、但邊界未明文：\n\n| 層 | 位置 | 生效範圍 | 現有內容 |\n|---|---|---|---|\n| **dev-only** | `.claude/rules/` + 專案 CLAUDE.md @-import | 只約束本 repo 的開發 session | attribute-assessment、deep-integration-over-hardcode（#209）、commit-issue-reference（#213） |\n| **隨 plugin 發佈** | `plugins/issue-driven-dev/rules/` | skill 執行時被 SKILL.md 引用（僅 skill-scope，非 ambient） | tagging-collaborators、privacy-scrubbing、append-vs-modify、sdd-integration、process-attachments 等 |\n\n使用者發現至少一條 rule 屬「想注入使用者」性質，另一些純屬自己開發用 — 兩類該分開。已知結構性 gap：**plugin 無法 ambient 注入使用者 session**（plugin-root CLAUDE.md 不載入 project context，`claude plugin validate` 明示警告），所以「注入使用者」需要機制決定，不只是搬檔案。\n\n## Type\nrefactor\n\n## Priority\nP1 — pipeline 進行中的 active work line；如不符請修正。\n\n## Expected\n\n- 兩層 rules 的**分層判準**明文化（什麼隨 plugin 發佈給使用者、什麼留 dev-only）\n- 既有 rules 依判準盤點歸位\n- 「注入使用者」的 rule 有實際可達使用者 session 的**機制**\n\n## Actual\n\n- 分層事實上存在但判準只在隱性實踐（#209 Clarity row 3 裁過一次 dev-only，但通用判準未寫下）\n- 使用者端沒有 ambient rule 注入機制；plugin rules 只在 skill 執行時生效\n### Clarity Surface(idd-clarify run 2026-07-02T20:27:48Z, attended-with-timeout)\n\n| Type | Source | Suggested canonical | Status | Reason |\n|---|---|---|---|---|\n| ambiguity | \"有一個rule是我想要注入使用者的\" | 未指名哪條 — 候選 commit-issue-reference / deep-integration-over-hardcode / attribute-assessment | resolved @ 2026-07-02T20:27:48Z (reason: user AFK 60s，best-judgment 取 commit-issue-reference — trap 咬所有 IDD 使用者、canonical 已隨 plugin ship 但對使用者不 ambient；deep-integration 經 #209 row 3 裁 dev-only；attribute-assessment 自述未達 rule-of-three promote 門檻。可推翻) | — |\n| missing-context | 「注入使用者」的機制未指定 | plugin 無法 ambient 載入 project context（validate 警告）— 候選：SessionStart hook / skill-scope 引用強化 / README 教學 / 並用 | deferred | unattended-auto-Step-4.6-deferred |\n| ambiguity | scope — 只搬一條還是全面盤點兩層 rules | 全面盤點 vs 最小切 | resolved @ 2026-07-02T20:27:48Z (reason: user AFK 60s，best-judgment 取最小切 — 寫判準 + 只處理 commit-issue-reference；全面盤點歸位另開 follow-up，且與 #210 audit sweep 精神相近可併議。可推翻) | — |\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-07-03 by idd-close (via idd-update)\n\n### Key Decisions\n- Verify R2 = PASS（0 blocking）；R1 = FAIL（1 HIGH wiring 硬鎖 + 10 in-scope）已全修，mutation-test 證明 drift-guard 有效\n- A1–A5 全落地：判準檔（受益者軸）+ canonical 升格 + SessionStart hook（≤5 行、無 matcher 刻意、22-assertion drift guard）+ skill-scope 指向 + 2.91.0\n- CRLF churn 重切為宣告式 chore commit（blame 乾淨）\n\n### Scope Changes\n- Sister #215（全面盤點歸位）；follow-ups #216-#217 類（.gitattributes、suite 自動執行 — 見 R2 report）\n\n### Blocking\n- (none) — closed；4 commits 已 push；residue acknowledged as-is；distribution chain 進行中\n\n### Commits\n- `512c73f` chore line-endings / `588e6da` feat 主體 / `e96c50e` fix R1 / +1 docs R2（未 push）" }, { "number": 276, @@ -454,7 +503,8 @@ "- (none) —— Phase 1 待 maintainer review draft PR #279；Phase 2 未開工，不阻塞 Phase 1" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n使用者文件沒有寫清楚 `idd-plan` 與 `idd-diagnose` 的關係與先後順序。結果是：使用者問了三次仍不確定，**使用者的 AI 自行推斷出「不用 diagnose，直接用 plan」**（與設計相反），而 maintainer 在同一段對話裡給出了**兩種互斥的說法**。\n\n> **Original text**（Telegram 私訊，2026-07-08 15:00–15:25。對話對象為 IDD 早期使用者，以 `K` 代稱 — 見文末 Privacy note）：\n>\n> **15:00 K**：`issue>plan>deep research>verify>report>close`\n> **15:00 K**：過程中`>comment`\n> **15:00 K**：那如果我想研究問題，這樣可以嗎\n> **15:01 Che**：issue後面我通常會先 /diagonose\n> **15:01 Che**：diagonose之後你要補deepresearch都可以\n> **15:01 K**：那不用plan嗎\n> **15:02 Che**：diagnose 會判斷需不需要plan\n> **15:03 K**：好的\n> **15:06 K**：他之前說deep research就好，然後AI現在就跟我說不用diagnose, 直接用plan\n> **15:08 Che**：看起來是我說明沒寫完整\n> **15:08 Che**：你照著她做我想應該也是可以\n> **15:08 Che**：plan可以取代diagonoe\n> **15:25 K**：像我剛剛提出的問題老師覺得有哪些需要開issue嗎\n> **15:25 Che**：就是要寫清楚plan, diagonose的關係，要讓使用者清楚知道順序 之類的\n\n（同一使用者在 07-05 另有 `report(收斂)` 的功能詢問，經確認是 AI 幻想出來的 skill 名稱 — 見文末 sibling 說明，同屬「說明不完整 → AI 自行補完」這個 class。）\n\n## Type\n\ndocs\n\n## Expected\n\n使用者只讀 `plugins/issue-driven-dev/README.md` 就能回答三個問題：\n\n1. `idd-plan` 在 pipeline 的哪個位置？\n2. 誰決定要不要跑 `idd-plan` — 使用者自己選，還是 `idd-diagnose` 判定？\n3. 可不可以跳過 `idd-diagnose` 直接叫 `/idd-plan`？代價是什麼？\n\n## Actual\n\n三個問題目前都答不出來：\n\n| 位置 | 現況 | 問題 |\n|------|------|------|\n| `README.md:52` canonical pipeline 圖 | `idd-issue → idd-diagnose → idd-implement → idd-verify → idd-close`（5 格編號 ①–⑤） | **完全沒有 `idd-plan`**。使用者看圖不會知道它存在於流程何處 |\n| `README.md:60` skill 表格 | 「Plan tier approval gate ... sits between `Simple` direct-implement and `Spectra` spec-contract path」 | 用的是**內部 routing tier 語彙**。「sits between Simple and Spectra」回答的是「複雜度光譜上的位置」，不是使用者問的「執行順序上的位置」 |\n| `references/usecase-routing.md:49`（row 9） | ``idd-diagnose` 判 Plan → `idd-plan` → `idd-implement`` | ✅ 這是正確答案，但**埋在 reference 文件第 49 行**，README 沒有從 pipeline 圖指過來 |\n| `references/usecase-routing.md:15` 決策樹 | 「看 Implementation Plan 給人 approve（Plan tier） → `idd-plan`」 | ⚠️ 這行單獨讀反而**支持錯誤解讀**：「我想要 plan → 叫 idd-plan」。沒說 diagnose 必須先跑 |\n| 全 plugin 文件 | grep `取代 diagnose` / `skip diagnose` / `跳過 diagnose` → **0 命中** | 「plan 能不能取代 diagnose」這個問題在文件裡**根本沒被回答過**。所以 15:08 的口頭答覆「plan可以取代diagonoe」既無文件依據，也與 row 9 的設計矛盾 |\n\n三個獨立的失敗證據：\n\n1. **使用者連問兩次**（15:01「那不用plan嗎」、15:06 重提）\n2. **使用者的 AI 給出與設計相反的建議**：「不用 diagnose, 直接用 plan」。這不是 AI 亂講 — 在現有文件下，`idd-plan` 看起來就是一個和 diagnose 平行的 stage\n3. **maintainer 自己給出互斥的兩種說法**：15:02「diagnose 會判斷需不需要plan」（diagnose 是上游 router，tier 是它的輸出）vs 15:08「plan可以取代diagonoe」（peer，可互換）。這兩句不可能同時為真\n\n## Impact\n\n- `idd-diagnose` 是 IDD 的 router（Layer 1 disqualifier → Layer V vagueness → Layer 2 Spectra → complexity hard gate → Layer P）。**跳過 diagnose 直接 plan，等於繞過整個 routing 機制**：Layer V 的模糊度把關、[#129](https://github.com/PsychQuant/issue-driven-development/issues/129) 的 complexity hard gate、meeting-type 分流全部不會執行\n- 新使用者的第一手心智模型會定型在錯的形狀上，之後很難改\n- MANIFESTO 的核心主張是「Every issue is diagnosed before implementation — no guessing」（`README.md:13`）。文件容許使用者推論出「可以跳過 diagnose」，直接侵蝕這條主張\n\n## Suggested scope（供 diagnose 參考，非定案）\n\n1. README pipeline 圖旁補一行標示 Plan/Spectra 是 **diagnose 的輸出 tier**，不是平行 stage\n2. skill 表格 `idd-plan` 那列改用使用者語彙（誰觸發、何時觸發），不用 tier 光譜語彙\n3. 明文回答「能否跳過 diagnose 直接 plan」— 不論答案是可以或不可以，寫下來 + 寫代價\n4. `usecase-routing.md:15` 決策樹那行補上 diagnose 前置條件，避免單獨被讀成 entry point\n\n## 補充：實作層其實已有明確答案（建立本 issue 後查證）\n\n`plugins/issue-driven-dev/skills/idd-plan/SKILL.md` Step 1 的 diagnosis lookup table（**第 62 行**）已經明文規定：\n\n| Complexity | 行為 |\n|-----------|------|\n| `Plan` | ✅ 預期 — 繼續 |\n| `Simple` | ⚠️ 詢問 user |\n| `Spectra`（含 alias `SDD-warranted`） | ⛔ 提示改走 `/spectra-discuss` |\n| **_(missing)_** | **⛔ 提示「找不到 diagnosis，先跑 `/idd-diagnose #NNN`」並 abort** |\n\n也就是說 **shipped 實作的答案是明確的：`/idd-plan` 無法取代 `/idd-diagnose`** — 沒有 `## Diagnosis` comment 時它會 hard abort，連跑都跑不起來。同一份 SKILL.md 第 17 行也寫「由 `idd-diagnose` Step 3.5 的 Complexity verdict 決定」，`Simple` / `Plan` / `Spectra` 三個 tier 是 **diagnose 的輸出**。\n\n這把本 issue 的性質從「需要做決定」改成「**答案已經存在，但只存在於 skill 內部，沒有進到任何使用者面向的文件**」，而且產生兩個更尖的問題：\n\n1. **maintainer 的口頭答覆與 shipped 行為矛盾** — 2026-07-08 15:08「plan可以取代diagonoe」與 `SKILL.md:62` 的 hard abort 直接衝突。需確認是口誤，還是實作應該放寬\n2. **使用者的 AI 給的建議會在 runtime 直接失敗** — 「不用 diagnose, 直接用 plan」照做會撞 abort。使用者原本會得到一個看不懂的錯誤，而不是一個能理解的說明\n\n修正後的 Expected 因此收斂為：**把 `SKILL.md:62` 已經編碼的規則搬到使用者讀得到的地方**（README pipeline 圖 + skill 表格），並確認口頭答覆與實作何者為準。不需要重新設計任何機制。\n\n### Clarity Surface(idd-clarify run 2026-07-26T00:00:00Z)\n\n| Type | Source | Suggested canonical | Status |\n|---|---|---|---|\n| ambiguity | 「那不用plan嗎」/「plan可以取代diagonoe」 | 來源的「plan」有兩個所指：(a) `/idd-plan` **skill**；(b) `idd-diagnose` Step 3.5 輸出的 `Plan` **complexity verdict / tier**。「plan 能否取代 diagnose」的答案依所指而異 —— (a) 不能（`SKILL.md:62` hard abort）；(b) 問題不成立（tier 是 diagnose 的產物，無法取代產生它的東西）。文件修正時兩個意思必須用不同詞面 | resolved @ 2026-07-25T16:08:23Z (reason: 兩個所指已在 body 補充段釐清，並升格為修正需求：文件須用不同詞面區分 `/idd-plan`(skill) 與 `Plan`(tier)) |\n| missing-context | 「你照著她做我想應該也是可以」/「plan可以取代diagonoe」 | maintainer 的 live 答覆與 shipped 實作（`skills/idd-plan/SKILL.md:62`）衝突。**待 maintainer 裁決**：是實作該放寬（允許無 diagnosis 直接 plan），還是口頭答覆為口誤（文件照實作寫）。此為 diagnose 前必要輸入 | resolved @ 2026-07-25T16:08:23Z (reason: maintainer 2026-07-26 授權裁決，採實作為準 — SKILL.md:62 hard abort 是規則，07-08 口頭答覆為口誤；修正範圍純文件+生成器，零 gate 邏輯改動) |\n| terminology | 「diagonose」/「deepresearch」/「皆在diagonose上」/「家入research」 | 來源為即時通訊輸入，含 typo：`diagonose`→`diagnose`、`皆在`→`接在`、`家入`→`加入`。逐字原文依 IC_R007 保留不改，本列僅供 downstream 讀者對照 | dismissed @ 2026-07-25T16:08:23Z (reason: 來源 typo 依 IC_R007 刻意逐字保留，僅供 downstream 對照，無行動項) |\n\n### Linked-Context Siblings Filed\n\n本 issue 來源（單一 Telegram 對話串，2026-07-04 至 2026-07-13）掃出 5 個 sibling concern。Filed 3、surfaced-but-not-filed 2：\n\n| # | Concern | 處置 |\n|---|---------|------|\n| 1 | `idd-plan` ↔ `idd-diagnose` 關係與順序未寫清楚 | **本 issue**（maintainer 2026-07-08 15:25 明確指定要開） |\n| 2 | Claude Deep Research 未整合進 IDD、無 documented 接法 | filed → [#277](https://github.com/PsychQuant/issue-driven-development/issues/277) |\n| 3 | issue 已 closed 但事情還要做，缺 reopen / resume-implement 路徑 | filed → [#278](https://github.com/PsychQuant/issue-driven-development/issues/278) |\n| 4 | AI 幻想出不存在的 IDD skill（使用者 2026-07-05 問「`report(收斂)` > 你有寫這個功能嗎」，經 maintainer 確認為 AI 幻覺） | **不另開** — 與本 issue 同一 root cause（使用者文件不完整 → AI 自行補完），已作為佐證寫入本 issue Problem 段。若日後出現形狀不同的第二個幻覺案例再獨立 file |\n| 5 | 「AI 有能省力就省力的傾向」（使用者 2026-07-13 觀察） | **不 file** — IC_R011 category (a) unactionable。maintainer 當下回覆「要看是哪一個模型 不然這樣會有困難」，即缺 model / repro 資訊時無法轉成可行動 issue。本 repo 已有 `.claude/rules/attribute-assessment.md` 的 Lazy Developer adversary lens 涵蓋同一 class。取得具體 repro（哪個 skill、哪個 gate 被跳過、哪個 model）後再 file |\n\n（`/idd-issue` Step 4.6 clarity surface + Step 4.7 IC_R011 light-touch sister sweep）\n---\n\n### Privacy note\n\n原始來源為第三方 Telegram 私訊。逐字內容原樣保留（IC_R007），但對話對象的真名以 `K` 代稱 — 本 repo 為 public，第三方真名不必要地進入公開 issue 不符 privacy-scrubbing 紀律。若 maintainer 認為應具名，可自行 edit 補回。\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-07-26 by idd-plan\n\n### Key Decisions\n- Phase 1 已實作並開 draft PR #279；本 issue **不因該 PR 結案**（Phase 2 尚未開工）\n- 實測 17 個 skill：不符 house pattern 的是 **5 個**不是 1 個，5 個併入 Phase 1 同修（#129 契約 / #44 教訓）\n- A4 assertion 用明列 allowlist 而非機械推導 —— 推導式會誤傷 `idd-close` 的 meeting fallback 字串\n- 新 description 附「改跑 `/idd-diagnose #N`」的補救指示而非純警告，避免反向嚇阻 AI 永不選 idd-plan\n- drift-guard 自述只驗「有沒有」不驗「寫得好不好」，品質仍留給 review 人判斷（同 docs-catalog-sync 立場）\n- Root cause 定位於 `skills/idd-plan/SKILL.md` frontmatter `description` 未載明 diagnosis 前置 —— 該處是 AI 選 skill 時唯一可見的表面，且 idd-plan 是唯一同缺 `Use when:` 與 `防止的失敗:` 的 lifecycle skill\n- 採「以實作為準」：保留 `SKILL.md:62` 的 hard abort，**不**放寬讓 plan 獨立跑（maintainer 2026-07-26 授權裁決）\n- wiki 流程圖頁由 `docs/workflows.md` **自動生成**，不手寫、不建雙 source of truth（maintainer 2026-07-26 選定）\n- Complexity = **Plan**（Layer P：generator 解析契約 decision-heavy／檔案順序依賴／跨 repo 寫入 wiki 屬 irreversible side effect）\n- 交付分兩階段：Phase 1（description + drift-guard，可獨立出貨）／Phase 2（generator + wiki + README 指路）\n\n### Scope Changes\n- Phase 1 實際觸及 8 檔（5 個 `SKILL.md` + 新 drift-guard suite + README + CHANGELOG），超出 diagnosis 預估的 1 檔\n- 由原本的「補文件說明順序」擴大為三軸：機器面向 description 修正 + 人面向自動生成流程圖 + drift-guard 結構性防再犯\n- drift-guard assertion 涵蓋範圍由「lifecycle skill」擴大為「所有 IDD skill」（sister sweep 發現 `idd-clarify` 同屬 house-pattern 缺漏，併入 Phase 1，不另開 issue）\n\n### Blocking\n- (none) —— Phase 1 待 maintainer review draft PR #279；Phase 2 未開工，不阻塞 Phase 1\n\n### Commits\n- `1e46698` fix(skills): name the diagnosis precondition in idd-plan's description\n\n" }, { "number": 289, @@ -463,7 +513,8 @@ "- (none)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n`idd-comment --type=reply` hands a rules path to perspective-writer by **reconstructing it itself**:\n\n> `skills/idd-comment/SKILL.md` (R4 段)\n> 轉交：resolved `--mention` login + target repo `.claude/rules/correspondence-<person>.md` 路徑（若存在）\n\nperspective-writer 3.0.0 changed that contract. A subject's rules are no longer a single file at a fixed path — they are a resolved location: a subject directory holding a genre-independent `core.md` plus on-demand genre facets, under a dot-prefixed namespace. The old path may now hold a redirect placeholder rather than rules.\n\n## Why this is silent\n\nThe reconstructed path is tested for existence before handover. In a workspace that has migrated:\n\n1. IDD builds the old path and tests it.\n2. It finds a redirect placeholder there — so the existence test **passes**, and the old path is handed over.\n3. perspective-writer's resolve follows the placeholder and returns the subject's current rules.\n\nSo the placeholder shipped in 3.0.0 keeps this working **today**. The failure mode appears when the placeholder is absent — a workspace that adopted the new layout directly without migrating from a legacy file, or one that later cleaned up placeholders. Then step 2 fails, no path is handed over, and calibration falls back to a generic register.\n\nThat fallback is **silent by design on both sides**: perspective-writer returns `status=generic` rather than erroring (it never guesses intimacy), and IDD's R4 integration is graceful-degrade. The reply still posts. It just does not sound like the writer, and nothing says so.\n\n## Ask\n\nTwo changes, the second cheaper and independently useful:\n\n1. **Follow the resolution order instead of reconstructing a single path.** The contract is published at `plugins/perspective-writer/references/rules-resolution.md` in the perspective-writer repo; the consumer-facing summary is the EXTERNAL-CONSUMER CONTRACT section of that repo's README. `MIN_PW_CONTRACT` moves to `3.0.0`.\n\n2. **Surface `status=generic` to the user.** The return header already carries the outcome (`<!-- pw:calibrate v1 status=generic -->`). R4 currently handles plugin-absence with a visible message but does not appear to check this field. One line — \"reply posted without recipient calibration\" — converts the quietest failure mode into a visible one.\n\n## Notes\n\n- Not urgent while placeholders exist; filing now so the coupling is recorded rather than rediscovered.\n- The observability half of this is tracked upstream as a gap in the contract itself (perspective-writer#6): the contract defines the degradation signal but does not state any consumer obligation to act on it. Point 2 above is what that obligation would look like in practice.\n\n---\n\n**Source**: filed from perspective-writer's `subject-genre-rules-contract` change (task 5.3), which redefined the artifact-path contract this consumer depends on.\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-08-07 by idd-close\n\n### Key Decisions\n- **缺口是活的**：實測提報者 workspace 已改用 skill-packaged 規則，R4 找的 legacy 路徑不存在 → 校準完全失效\n- **診斷發現 Ask 第 1 點照字面做會複製上游剛消除的漂移** → 改採 B（上游自行解析），`perspective-writer#8` v4.2.0 先行\n- `MIN_PW_CONTRACT=4.2.0` ＋ `sort -V`；自測 `4.10.0` 正確判為 ≥ 4.2.0\n- 版本不足 degrade 而非拒絕 —— soft integration 的姿態不因版本變硬\n\n### Residue\n- `status=generic` 無法區分「本來就沒有規則」與「有但沒拿到」（上游 #6 known residual）。**但上游當初判「成因碼 premature」的前提已被本 issue 消掉**——現在有 consumer 讀該欄位了，可回頭重議\n\n### Blocking\n- (none)\n\n### Commits\n- perspective-writer `ae47e84`（v4.2.0，前置）\n- issue-driven-development `8d0ec33`（v2.103.0）\n" }, { "number": 290, @@ -472,7 +523,8 @@ "- (none) — 已結案。" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Type\nbug\n\n## Problem\n\n`idd-close` Step 0 的 checklist gate 用 authoritative-source 優先序決定掃哪些 checkbox：\n\n```\nauthoritative_source = first_exists([\n \"## Implementation Complete > ### Checklist\", # idd-implement Step 5 寫回\n \"\n\n---\n\n### Clarity Surface（idd-clarify run 2026-08-05T02:30:00Z）\n\n| Type | Source | Suggested canonical | Status |\n|---|---|---|---|\n| missing-context | 「`authoritative_source = first_exists([...])`」 | **`exists` 的判準未定義**。canonical rule（`rules/append-vs-modify.md`）零次提及 `len` / non-empty；四個消費端只有 `idd-close` Step 0 寫出 `len(impl_complete.items) > 0`，且**只對 priority 1**。`idd-verify` / `idd-update` 只引 `first_exists([...])` 無條件。實作前必須先定義：`exists` ＝「heading 在」還是「heading 在且 ≥1 個可解析項目」 | **resolved @ 2026-08-05T02:32:00Z**（裁決：採「heading 在且 ≥1 個可解析項目」，並寫進 canonical rule 使三個 consumer 一致。依據：`idd-close` 既有實作已如此、且是唯一既有實作——這是讓文件追上程式碼，不是新決定）|\n| ambiguity | 「無來源時 `### Tasks` 該省略還是寫**空節**」（診斷的未決點 2） | 「空節」有兩種且對 `first_exists` 意義不同：(a) 只有 heading 無任何 row；(b) heading ＋ `(none)` marker row。**且若沿用 `idd-close` 的 `len > 0`，兩者都不會 resolve** → 診斷裡寫的「gate 什麼都不掃」風險**不存在**。該未決點很可能是我沒查判準就下的判斷，而非真的分岔 | **dismissed @ 2026-08-05T02:32:00Z**（已由 `idd-close` 的 `len(items) > 0` 與其 edge-case 表「存在但 0 items → 視同不存在 → Legacy fallback」回答。原診斷寫的放寬風險不存在——那是我未查判準的誤判）|\n| terminology | 「四個 gate site（`idd-close` / `idd-verify` / `idd-update` / `idd-implement`）」 | `idd-implement` 實際是 **producer 不是 consumer**——它 Step 5a 只**寫** priority 1，不執行 resolution（該檔內 `authoritative_source` 僅出現在說明散文）。用詞不精確會讓人以為修 producer 需同步改四處 gate 邏輯；實際是「1 producer ＋ 3 consumer」 | **resolved @ 2026-08-05T02:32:00Z**（裁決：canonical rule 改稱「1 producer（`idd-implement` Step 5a）＋ 3 consumer（`idd-close` / `idd-verify` / `idd-update`）」。依據：`idd-implement` 檔內 `authoritative_source` 僅出現於說明散文，不執行 resolution）|\n\n---\n\n## Current Status\n\n**Phase**: closed\n**Last updated**: 2026-08-05 by /idd-close\n\n### Key Decisions\n- **結案**：PR #291 已 merge（merge commit `dc2601f`）。全套件 43 suite / 0 失敗。\n- 根因比 issue 描述更根本：priority 2 **沒有任何 producer**，chain 實務上塌縮成「只有 priority 1」，而它只有 `idd-implement` 產生。\n- 裁決 A/B/C′/D 由使用者授權判斷；C 經 discuss 修正為「向 CLI **查**路徑而非組路徑」，並加 **toplevel 圍籬**（實測 registry 會回傳 sibling worktree 路徑）。\n- cross-model verify 抓到兩個嚴重缺陷：修法**在自己的 pipeline 裡活不過一步**（整段替換會抹掉剛寫入的 `### Tasks`）、圍籬 **fail-open**（`TOP=\"\"` → pattern `/*`）。\n\n### Scope Changes\n- 從「修 idd-close 的 gate」擴成「補上契約 priority 2 的 producer」——修法位置移到 `idd-update`，影響面從一個 gate 變成整個 resolution。\n\n### Blocking\n- (none) — 已結案。\n\n### Tasks\n\n*本小節由 `idd-update --tasks-file openspec/changes/add-authoritative-source-producer/tasks.md` 產生——**這是本次新增機制的第一次實際使用**。圍籬已套用（路徑在當前 toplevel 內），14 個可解析項目 > 0 故 resolve，Strategy 依 canonical 規則視為 superseded snapshot。*\n\n- [x] 1.1 寫出**會失敗**的 fixture 測試（`plugins/issue-driven-dev/scripts/tests/authoritative-source-pr\n- [x] 1.2 同檔加 drift-lock：斷言 `rules/append-vs-modify.md` 含 `exists` 的判準文字與「1 producer ＋ 3 consum\n- [x] 1.3 同檔加**圍籬測試**：用 `git worktree add` 建**真的**第二個工作樹（不是只換字串的假 fixture——實際遇到的情形正是同 repo 跨 wo\n- [x] 2.1 `idd-update/SKILL.md` 新增 `--tasks-file <path>` 的參數說明與 Step 4 模板的 `### Tasks` 小節：內容為來源\n- [x] 2.2 同檔寫入圍籬規範：路徑解析為絕對路徑後必須以 `git -C \"$CWD\" rev-parse --show-toplevel` 為前綴，否則**拒絕**、印出兩個路徑、\n- [x] 2.3 同檔寫明三種不 emit 的情形：flag 缺席、檔案不存在（警告不中止）、檔案零個 checkbox 行。並說明「不 emit」而非「emit 空節」的理由（不製造需要\n- [x] 2.4 `idd-all/SKILL.md` 的 Spectra 分支在收尾呼叫 `idd-update` 時附上 `--tasks-file`，路徑取自對外部工具 CLI 的*\n- [x] 3.1 `rules/append-vs-modify.md` 的 resolution 段落定義 `exists` ＝ heading 在**且**至少一個可解析項目，並註明此\n- [x] 3.2 同檔把「4 個 gate site」改為具名的「1 producer（`idd-implement` Step 5a）＋ 3 consumer（`idd-close` S\n- [x] 3.3 同檔新增不變式：**優先序的每一層都必須指名 producer**；沒有 producer 的層無法 resolve，會讓優先序靜默塌縮。註明本不變式無法被測試強制（它約\n- [x] 3.4 `idd-close/SKILL.md` Step 0 的 `exists` 敘述與新的 canonical 定義對齊（它原本只對第一層寫 `len(items) > 0\n- [x] 4.1 確認第一層行為**逐字未變**：以 `git diff` 確認 `idd-implement/SKILL.md` 的 Step 5a 敘述未被修改，且 `rules/ap\n- [x] 4.2 確認**未硬編外部佈局**：`grep -rn 'openspec/changes' plugins/issue-driven-dev/skills/ plugins/i\n- [x] 4.3 跑既有測試 runner，全數通過；記錄變更前後的測試數量。驗證目標：runner 全綠，新測試出現在清單中。\n\n### Commits\n- PR **#291**（merge commit `dc2601f`）：`b692d9d` producer ＋ exists 判準 · `58a51b9` cross-model verify round 1\n- 另含兩個與本 issue 無關的清理 commit（`7e3c87a` / `d1041f3`），成因與更正見 PR pointer comment" }, { "number": 295, @@ -481,7 +533,8 @@ "（無）" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n`--audit-closes`（`/idd-list` Step 4）與 `scripts/check-closed-without-summary.sh` 判定「closed 但缺 `## Closing Summary`」用的是：\n\n> comments 中**沒有任何一則以** `## Closing Summary` **開頭**（startswith prefix-match，case-sensitive）\n\n在一個真實 repo（`PsychQuant/plaud-mcp-connector`，43 張 closed issue）上量測，這個 marker **對 11 張誤報，全部都有實質 summary**：\n\n| 形狀 | 數量 | 實際內容 |\n|---|---:|---|\n| `## Closing summary`（小寫 s） | **10** | 1.0k–2.4k 字元，各 4+ 個具名小節 |\n| summary 併在 `## Implementation Complete` 同一則 comment（`---` 分隔） | **1** | 完整五段式 |\n| 真的缺 | **0** | — |\n\n**假陽性率 26%（11/43）。**\n\n## Type\n\nbug\n\n## 為什麼這比「稽核不準」嚴重\n\n**1. 假警報會蓋掉真警報。** 一個四分之一會誤報的旗標，人會學會忽略它 —— 而忽略本身就是損害：十一個假警報會蓋掉第十二個真的。這正是 `--audit-closes` 存在的理由被抵銷。\n\n**2. `--retroactive` 的 precondition 共用同一個 marker，所以誤報會變成破壞性動作。**\n\n`/idd-close --retroactive` 的 precondition 寫的是：\n\n> `state == CLOSED` **且**無**以 `## Closing Summary` 開頭**的 comment（**startswith prefix-match**，同 #151 偵測契約）\n\n也就是說：那 10 張「小寫 s」的 issue **會通過 precondition**（字面上確實沒有以 `## Closing Summary` 開頭的 comment），於是 retroactive mode 會照著跑，**在每一張已經有完整 summary 的 issue 上再貼一份重複的 retroactive summary**。\n\n實際發生過：本次是操作者在 draft 前手動核對 comment 內容才攔下來的。契約本身沒有任何一層會擋。\n\n> **這是 detector 假陽性升級成不可逆 side effect 的路徑** —— 與 #76 把 run_id 碰撞列進 Layer P「irreversible side effect」詞彙的同一類問題。\n\n## 根因不是「有人打錯字」\n\n`idd-close` Step 2 的模板寫的是 `## Closing Summary`，但**寫入端沒有任何 enforcement**：heading 是 LLM 依模板生成的自由文字。跨 session、跨模型、跨語言 prompt 之下，`summary` / `Summary` 的漂移是**預期行為，不是例外**。\n\n同理，「summary 併進 IC 那則 comment」也不是失誤 —— `idd-close` 在 `Implementation Complete` 之後緊接著產 closing summary，把兩者寫成同一則是很自然的組裝方式，而契約從未在寫入端要求它自成一則。\n\n**偵測端是 exact prefix，寫入端是自由文字。** 兩端不對稱，漂移就會累積，而且只在稽核時才顯形。\n\n## Expected\n\n至少要能區分「欠工作」與「marker 不合」。實作過一版四類分類器（純函式 + 11 條單元測試，`gh` 只在 CLI 層），在同一個 repo 上跑出 43/43 conforming（修完之後）：\n\n```\nown-comment 自成一則 comment 且 canonical 大小寫 → 合規\ncasing 自成一則，heading 大小寫不同 → 內容在，1 個字元的修法\nmid-comment heading 在，但不在 comment 開頭 → 內容在，需拆 comment\nmissing 完全找不到 → 唯一欠工作的一類\n```\n\n可能的處置（不預設哪個對，這是 IDD 該拍板的）：\n\n1. **偵測端放寬**：`(?mi)^[ \\t]*##\\s*closing\\s+summary`，並把 verdict 拆成上面四類。`--retroactive` 的 precondition 只在 `missing` 時放行。\n2. **寫入端正規化**：`idd-close` Step 4 dispatch 前把 heading 正規化成 canonical 形式（治本，但只對未來的 issue 有效）。\n3. **兩者都做**：寫入端正規化止血，偵測端四類處理存量。\n\n若決定維持 exact prefix，那 **`--retroactive` 的 precondition 必須改成語意判定**（不能與稽核 marker 共用），否則上面第 2 點的破壞路徑仍在。\n\n## Actual\n\n`--audit-closes` 對 11/43 誤報；`--retroactive` 會在那 11 張上貼重複 summary，而契約沒有任何一層會擋。\n\n## 不在範圍\n\n- **不主張 canonical heading 該改成什麼** —— `## Closing Summary` 作為模板沒有問題，問題在兩端不對稱。\n- **不主張要不要保留 `--audit-closes`** —— 它的價值在這次量測裡是成立的（它確實逼出了一次全面核對），要修的是判定粒度。\n\n## 附帶一個實作細節（給採用方案 1 的人）\n\n放寬 regex 時**不要**在 `summary` 後面加 `\\b`。`_` 是 word character，所以 `## closing summary_v2` 這種改版標題會匹配失敗、被判成 `missing`，而 summary 就在那裡。這條是 acid test 抓到的：該 boundary 原本沒有任何測試覆蓋，細看之下方向還是錯的。\n\n---\n\n**Source**: surfaced while running `/idd-close --retroactive` on 10 issues in a downstream repo — the batch was aborted at the precondition check when manual inspection showed all 10 already had summaries.\n\n\n---\n\n## Current Status\n\n**Phase**: planning\n\n### Tasks\n\n- [x] Diagnosis — root cause 確認（marker 同時服務 advisory 稽核與破壞性 precondition；產生端無 normalization）\n- [x] Plan — family-wide scope 必須涵蓋 4 個 consumer 位置（#129 硬閘產出契約）\n- [ ] Implement + acid\n- [ ] Verify\n- [ ] Close\n\n### Blocking\n\n（無）\n\n" }, { "number": 298, @@ -490,7 +543,8 @@ "- (none — 可動)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n> **原始需求（逐字）**：\n> 「把 triage 訊號抽成一個獨立的小 deliverable 先做掉（它今天就在傷人），bulk-solve autopilot 本體則依假設 2 的證據 re-park」\n>\n> — Source: `/spectra-discuss` #37「goal-driven Simple-tier bulk-solve」，2026-08-10。使用者裁決「應該OK，照你說的」。\n\n`/idd-list` 的 Suggested-next routing（以及 `/idd-all` 的 complexity dispatch）**讀不到「這個 issue 現在可不可以動」**。四個現成訊號沒有任何一個被當成 routing gate：\n\n| 訊號 | 位置 | 現況 |\n|---|---|---|\n| `### Complexity` 的 `when triggered` 限定詞 | Diagnosis comment | **被截掉** — parser 只取 tier token |\n| `parking-lot` label | Issue labels | **完全沒被讀** — 沒有任何 consumer |\n| Strategy 的 `[~] 暫緩` 標記 | Diagnosis comment | **完全沒被讀** |\n| `### Blocking` 區塊 | Body Current Status | ✅ 有讀（#84 已 ship）— 四個裡唯一接上的 |\n\n### 實測失敗（2026-08-10）\n\n對本 repo 真實的 22-issue backlog 跑 `/idd-list`，routing 把 **8 個 parked/deferred/blocked issue 判成「Actionable now」**：\n\n| Issue | routing 給的建議 | 實際處置 | 觸發條件 |\n|---|---|---|---|\n| #131 | `/idd-implement` | deferred（使用者 2026-07-07 H-cluster 裁決）| 實證失效訊號（未發生）|\n| #146 | `/idd-implement` | parking lot | 首次 self-audit recursion 實例（未發生）|\n| #157 | `/idd-plan` | parked | ≥1 次 trace-stale 實害事故（未發生）|\n| #128 | `/idd-plan` | blocked-by #86 | #86 collaborator config（未 merge）|\n| #200 | `/spectra-discuss` | deferred（使用者 2026-07-07 H-cluster 裁決）| ≥2 次實際 cascade（未發生）|\n| #143 | `/spectra-discuss` | parking lot | ≥1 plugin 要求 terminology extension |\n| #144 | `/spectra-discuss` | parking lot | ≥3 instances（目前 #1）|\n| #145 | `/spectra-discuss` | parking lot | 首次 cross-plugin reuse request |\n| #136 | `/spectra-discuss` | parking lot | #135 v3 完成 + ≥1 drift 案例 |\n\n9 條路由裡 8 條錯。其中 **#131 與 #200 帶有使用者親自下的 defer 裁決** —— 照 routing 執行等於自動推翻已記錄的人為決策。\n\n**失敗是靜默的**：產出的表格語法正確、格式正常、看起來完全可信。沒有任何 warning。\n\n## Type\n\nbug\n\n## Expected\n\nRouting 要能區分「diagnosed 且現在可動」與「diagnosed 但在等 trigger」。具體：\n\n1. **`### Complexity` 解析保留完整語意**，並套用與 `### Conflict Class` 對稱的規則 —— 值不是已知 tier 的裸 token（如 `Simple when triggered`、`Spectra when triggered (parking lot)`）時，**保守處置 + 必須 surface**，不得靜默截斷成 tier。\n2. **`parking-lot` label 成為 first-class routing 訊號** —— 該 label 的 description 自己就寫著「Diagnosed but deferred until trigger condition fires. **`/idd-list` filter candidate.**」。規格已經寫下來，只是沒接上。\n3. **Suggested-next 對 parked issue 不給 lifecycle 命令**，改顯示 parked 狀態 + trigger 條件（沿用 #84 已建立的 Blocked 分組呈現）。\n4. **四個**訊號任一成立即視為 not-actionable —— **放行需四者皆不成立**，而非任一成立才擋。（原寫「三個」，2026-08-10 裁決更正為四個：`### Blocking` 一併納入同一 gate，#84 既有的 Blocking 抽取改為本 gate 的 input，不另立平行機制。）\n\n## Actual\n\n- `### Complexity` 的 parser 只取 tier，限定詞落地即消失\n- `parking-lot` label（本 repo 6 個 open issue 帶著）沒有任何 consumer\n- Strategy `[~] 暫緩` 沒有任何 consumer\n- 結果：parked issue 與 actionable issue 在 Suggested-next 裡**無法區分**\n\n## Impact\n\n| 面向 | 影響 |\n|---|---|\n| `/idd-list` Step 5 | Suggested-next 對 parked issue 給出錯誤的 lifecycle 命令 |\n| `/idd-all` complexity dispatch | `Simple when triggered` 不匹配任何已知 tier，dispatch 行為未定義 |\n| `references/parallel-orchestration.md` | `### Conflict Class` 的 default-on-absence 規則是現成的正確樣板，`### Complexity` 應對稱 |\n| **#37 bulk-solve** | 這是 #37 triage 步驟的前置條件。#37 的 autopilot 若建在會誤判 8/9 的 triage 上，會把錯誤自動放大到 auto-merge |\n| 人為決策 | 最嚴重的一項：routing 會建議執行使用者已明確 defer 的工作 |\n\n## Vocabulary drift\n\n本 repo 有**兩套並存、互相打架的 parking 慣例**：\n\n| 慣例 | 文件出處 | 實際使用 |\n|---|---|---|\n| `blocker:infeasible` / `blocker:waiting` | `references/ic-r011-checkpoint.md` | **0 個 issue** |\n| `parking-lot` | 無文件（只有 label description）| **6 個 open issue** |\n\n文件寫的那套沒人用，實際在用的那套沒寫進文件。需要擇一收斂，或明確記錄兩者的分工。\n\n## Acceptance criteria\n\n> 依 2026-08-10 Clarity Surface 四項裁決收斂（裁決全文見下方 Clarity Surface 的 resolved 欄）。\n\n**Gate 行為**\n\n- [ ] `### Complexity` 值非裸 tier（`Simple when triggered` / `Spectra when triggered (parking lot)` 等）時，標為 not-actionable 且**顯示原始值**；不降級為 `Plan`、不 abort\n- [ ] `parking-lot` label 被讀取並影響 Suggested-next 分組\n- [ ] Strategy `[~] 暫緩` 被讀取（裁決：納入，非排除）\n- [ ] **四個訊號收斂成單一 gate**，放行需四者皆不成立\n- [ ] **#84 既有的 `### Blocking` 抽取重構為此 gate 的 input**，repo 內不存在第二條平行的 not-actionable 判定路徑（scope 增量 — 2026-08-10 裁決）\n- [ ] #84 既有的 Blocked 分組輸出行為不退化（重構不是改行為）\n\n**顯示**\n\n- [ ] parked issue 有 `### Blocking` 區塊 → 顯示其首行；無 → 只標 parked + diagnosis 連結\n- [ ] **不**新增 `### Park Trigger` 欄位、**不** parse diagnosis 散文抽 trigger（明確 out of scope）\n\n**測試**\n\n- [ ] fixture 形式為 **issue 號 + 期望 verdict 對照表**（如 `fixtures/parked-routing.yaml`），訊號的最小重現片段寫死在表內，不依賴 live issue\n- [ ] 該 fixture 覆蓋 2026-08-10 的 9 條 diagnosed 路由，斷言只有 #37 為 actionable\n\n**文件**\n\n- [ ] 訊號解析規則寫進 reference，與 `parallel-orchestration.md` 的 Conflict Class 契約對稱\n- [ ] 兩套 parking 慣例（`parking-lot` vs `blocker:infeasible`/`blocker:waiting`）擇一收斂，或明確記錄分工\n\n## Source\n\nCarved out from `/spectra-discuss` #37（2026-08-10）。#37 本體維持 open 但 re-park —— 該場 discuss 的完整結論記在 #37 的 decision comment。\n\n本 issue 是 #84（`/idd-list` blocked-state awareness）的延伸：#84 建立了「把非可動狀態顯式 surface」的模式，但只覆蓋 `### Blocking` 一個訊號。\n\nRefs #37, #84\n\n\n---\n\n### Clarity Surface（idd-clarify run 2026-08-10T10:29:50Z）\n\n| Type | Source | Suggested canonical | Status |\n|---|---|---|---|\n| ambiguity | 「值不是已知 tier 的裸 token（…）時，**保守處置 + 必須 surface**」 | 「保守處置」的具體值未指定。對照組 `### Conflict Class` 的保守值是明確的 `D_diagnose_first`；`### Complexity` 的對應值是什麼？候選：(a) 一律視為 not-actionable、(b) 降級為 `Plan`、(c) 拒絕 routing 並要求人工判讀 | resolved @ 2026-08-10T11:15:09Z（裁決：標為 not-actionable + surface —— 完全對稱於 `### Conflict Class` 的 `D_diagnose_first`：不放行、但必須顯示原始 Complexity 值供人判讀；list 照常輸出，issue 進 Parked 分組。**不**降級為 Plan（Plan 仍是可動 tier），**不** abort） |\n| ambiguity | 「三個訊號任一成立即視為 not-actionable」（Expected 第 4 點） | Problem 表列的是**四個**訊號（Complexity 限定詞 / parking-lot label / Strategy `[~] 暫緩` / `### Blocking`）。「三個」推測是排除已 ship 的 `### Blocking`，但未明示。需確認納入 gate 的確切集合 | resolved @ 2026-08-10T11:15:09Z（裁決：**四個統一進同一個 gate**。#84 的 `### Blocking` 抽取改為此 gate 的其中一個 input，不在旁邊另立平行機制 —— 否則等於把本 issue 控訴的「訊號散落」重現一次。代價：需動到 #84 已 ship 的程式） |\n| ambiguity | 「改顯示 parked 狀態 + trigger 條件」（Expected 第 3 點） | trigger 條件目前只存在於 diagnosis 的散文（如「等 ≥3 instances」「首次 trace-stale 實害事故」），無結構化欄位。本 issue 是否包含「讓 trigger 條件可機械抽取」？若否，顯示的 trigger 條件從何而來 | resolved @ 2026-08-10T11:15:09Z（裁決：**只顯示已結構化的**。有 `### Blocking` 區塊就顯示首行（#84 已能做到）；無則只標 parked + 附 diagnosis 連結。**不**新增 `### Park Trigger` 欄位、**不**嘗試 parse 散文 —— 那是獨立問題，不納入本 issue） |\n| missing-context | 「用 2026-08-10 的 22-issue backlog 當 fixture 回歸測試」（Acceptance criteria） | fixture 來源未指定。live backlog 會變動（issue 會被 close／編輯／重新 diagnose），2026-08-10 的狀態不會自動保存。需指定快照方式：(a) 提交靜態 JSON fixture、(b) 記錄 issue 號 + 期望 verdict 的對照表、(c) 其他 | resolved @ 2026-08-10T11:15:09Z（裁決：**issue 號 + 期望 verdict 對照表**（如 `fixtures/parked-routing.yaml`），訊號的最小重現片段一併寫死在表裡，不依賴 live issue。**不**存完整 JSON 快照（肥大且 embed 大量散文）、**不**跑 live query（issue 一被 unpark 測試就無故轉紅）） |\n\n\n### Linked-Context Siblings Filed\n\n| Issue | Concern | 為何不併入本 issue |\n|---|---|---|\n| #299 | `/idd-list --limit` 在 server 端先於 `updatedAt` 排序生效，截掉的不是最舊的那幾筆 | 同屬 `/idd-list` 但**機制不同** — 本 issue 是訊號解析（讀不懂 issue 狀態），#299 是抓取排序（拿錯 issue 集合）。修法、測試、驗收都不重疊 |\n\n（`/idd-issue` Step 4.7 linked-context sweep，2026-08-10）\n\n\n\n## Current Status\n\n**Phase**: diagnosed\n**Last updated**: 2026-08-10 by /idd-diagnose (attended)\n\n### Complexity\n\nSpectra\n\n（7-step routing 於 step 4 命中：Layer 2 ✓ field contract for future callers；Layer 3 三項全中。Hard-gate 未評估 —— Spectra precedes。詳見 Diagnosis comment）\n\n### Blocking\n\n- (none — 可動)\n\n### Next\n\n`/spectra-discuss` — topic「`### Complexity` 欄位契約 + 四訊號 actionability gate」。\ndiscuss 前段須先拍板 Diagnosis 的 **Open questions 1-2**（legacy 值 migration、producer 是否自動貼 `parking-lot`）—— 後者會實質改變訊號集大小。\n\n### Related\n\n- carved out from #37（該 issue 已 re-parked）\n- #299 同檔（`skills/idd-list/SKILL.md`）→ 需序列化或 bundle\n- #84 既有 Blocking 路徑進入 scope（裁決 2）\n" }, { "number": 316, @@ -499,7 +553,8 @@ "- (none — 可動)" ], "expect_empty": true, - "expect_first_blocker": null + "expect_first_blocker": null, + "body": "## Problem\n\n#298 的修正（PR #309 / #306）**只落在 `idd-list`**。`### Complexity` 的另外三個 routing consumer 完全沒動，各自的私有解析仍在，且與 `idd-list` 的新規則不一致。\n\n### 1. `idd-list` 自身前後矛盾\n\n同一個 `skills/idd-list/SKILL.md`：\n\n| 位置 | 內容 |\n|---|---|\n| Step 3.7（#298 修正）| 「值若不是已知 tier 的**裸 token**…**必須 surface**…**不得靜默截成 tier**」 |\n| Step 5 Complexity 解析（未動）| 「regex `### Complexity\\n([A-Za-z-]+)`，**取第一個 token**」 |\n\n`([A-Za-z-]+)` 在第一個空白處停止 —— 那正是 Step 3.7 明文禁止的截斷。實作者照哪一段做，行為就不同。\n\n### 2. `idd-all` 的安全網結構上接不住非法值\n\n`skills/idd-all/SKILL.md` 的解析與 dispatch table 維持原狀：\n\n```\nm = re.search(r'### Complexity\\n(.+?)\\n', latest)\nprint(m.group(1).strip() if m else 'UNKNOWN')\n```\n\ndispatch table 有 `Simple` / `Plan` / `Plan via Layer V` / `Spectra` / `SDD-warranted` / `UNKNOWN` 六個 row。`UNKNOWN` 只在 **regex 完全沒 match** 時產生（`if m else`）。一個 `Simple when triggered` 會讓 regex **match 成功**、回傳非法字串 —— 它既不匹配任何 row，也不是 `UNKNOWN`，落入**未定義行為**。\n\n### 3. `idd-implement` / `idd-plan` 各自 inline\n\n`idd-implement` 自行 `split(\" via \")[0]`；`idd-plan` 自行確認 tier 是否為 `Plan`。兩者都沒有域外值的處置。\n\n### 4. `blocker:*` vs `parking-lot` 的 vocabulary drift 未收斂\n\n`references/ic-r011-checkpoint.md` 已於 2026-08-14 誠實更正「periodic backlog grooming 不存在」（#310），但同檔 71 / 72 / 92 / 94 / 182 行**仍規定 filing 時要貼 `blocker:infeasible` / `blocker:waiting`** —— 這兩個 label 在本 repo **一次都沒有被建立過**，0 個 issue 在用；實際在用的是 `parking-lot`。文件現在誠實地說「沒有機制會回頭讀這些 label」，卻仍叫人繼續貼它們。\n\n## Type\n\nbug\n\n## Expected\n\n> **⚠ 本段已於 2026-08-15 re-baseline 修正**（見下方 `## Re-baseline` comment）。原版規定「合法值域為封閉四值」—— 該前提被 `/idd-verify --pr 318` 的 CRITICAL-2 以 90 筆真實 diagnosis 語料證偽：38 筆域外值中只有 9 筆是延期修飾語，22 筆是 tier 後接同行理由的**正常**寫法。原文保留於本 comment 串以供追溯。\n\n四個 consumer 共用**單一實作**，且對「無法路由的值」有一致處置：\n\n- **`### Complexity` 的正確值域形狀待重新判定**（重做起點）。已知的資料約束：\n - producer 的常態寫法是「tier + 同行理由」（`Spectra（opt-out → 直接 propose）`、`Plan（Layer P：…）`、`Simple — 單檔、2 個 1-token 補丁…`），這類**必須**能正確解出 tier\n - 真正該擋下的是延期語彙（`when triggered` / `parking lot` / `deferred pending #N`）\n - 兩者的分界不是「有沒有後綴文字」，而是「後綴文字是否表達延期」\n- 無法路由的值 → not-actionable + **surface 原值**；缺區段 → 另一個 reason（此三條不受前提修正影響）\n- `idd-all` dispatch table 補上「解析成功但無法路由」的 row\n- `idd-list` Step 5 與 Step 3.7 不再互相矛盾\n- **三訊號 gate 必須真的被四個 consumer 呼叫** —— verify CRITICAL-1：gate 已實作但零 consumer，`parking-lot` 與 `### Blocking` 在三個 skill 仍被繞過\n- `blocker:*` 與 `parking-lot` 擇一收斂，或明記分工\n\n## Actual\n\n- 規則以散文形式只寫在 `idd-list`，其餘三個 consumer 讀不到\n- `idd-list` 內部兩段規則互相矛盾\n- `idd-all` 對非法值行為未定義\n- 兩套 parking label 慣例並存，其中一套零使用卻仍被文件規定\n\n## Impact\n\n| 檔案 | 影響 |\n|---|---|\n| `plugins/issue-driven-dev/skills/idd-list/SKILL.md` | Step 5 的截斷 regex 與 Step 3.7 矛盾 |\n| `plugins/issue-driven-dev/skills/idd-all/SKILL.md` | 解析 + dispatch table 缺非法值處置 |\n| `plugins/issue-driven-dev/skills/idd-implement/SKILL.md` | 私有 inline 解析 |\n| `plugins/issue-driven-dev/skills/idd-plan/SKILL.md` | 私有 tier 確認 |\n| `plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md` | producer 端未宣告封閉值域 |\n| `plugins/issue-driven-dev/references/ic-r011-checkpoint.md` | label 慣例未收斂 |\n\n## Acceptance criteria\n\n- [ ] **`### Complexity` 的值域形狀重新判定**，並以真實語料（closed corpus，非 open backlog）驗證\n- [ ] 四個 consumer 皆引用單一共用實作，無私有 inline 解析\n- [ ] **三訊號 gate 真的被四個 consumer 呼叫**（讀 labels + `### Blocking` 並送進 verdict）\n- [ ] `idd-all` dispatch table 涵蓋「regex match 到但值不在封閉值域」\n- [ ] `idd-list` Step 5 與 Step 3.7 一致（不再有截斷 regex）\n- [ ] `idd-diagnose` 明文宣告封閉值域，且明訂不自動貼 `parking-lot` label\n- [ ] `blocker:*` 與 `parking-lot` 擇一收斂或明記分工\n- [ ] 回歸測試覆蓋 2026-08-10 事故快照，斷言 9 筆中只有 #37 為 actionable\n- [ ] **回歸測試另須涵蓋 closed corpus 的常態寫法**（至少 `Spectra（opt-out → …）` / `Plan（Layer P：…）` / `Simple — <理由>` 三種形狀必須解出正確 tier）—— fixture 不得只收錄為驗證假設而挑的樣本\n\n## Source\n\nSurfaced during `/spectra-apply add-actionability-gate`（2026-08-14）。該 change 於 #298 close 前提出，走完 discuss → propose 後 apply 時才發現 #298 已由 PR #309 / #306 修掉 —— 但只修了 `idd-list`。本 issue 承接剩餘缺口。\n\n已就緒、可直接接上的產物（該 change 的 Group 1–2，全新檔、與已 merge 的內容零衝突）：\n\n- `plugins/issue-driven-dev/scripts/lib/actionability.sh` —— 共用 helper\n- `plugins/issue-driven-dev/references/actionability-gate.md` —— canonical 契約\n- `plugins/issue-driven-dev/scripts/tests/actionability-gate/` —— 66 個斷言、15-row fixture（含事故快照），全綠\n\nRefs #298, #310\n\n\n---\n\n## Current Status\n\n**Phase**: diagnosed（第 2 輪 — post re-baseline）\n**Last updated**: 2026-08-15 by /idd-diagnose\n\n### Complexity\n\nSpectra\n\n（Layer 2 ✓ field contract for future callers；Layer 3 三項全中。Hard-gate 未評估 —— Spectra precedes。）\n\n### Blocking\n\n- (none — 可動)\n\n### Next\n\n**`/spectra-ingest add-actionability-gate`** —— 不是 `/spectra-discuss`。\n\n該 Spectra change 已存在且四份 artifact 俱全；本輪 diagnosis 產出的是「修正既有 change 的外部 context」（corpus 分析 + verify findings），不是一個新方向 —— 方向已由 159 筆 corpus 定死（158/158，0 false positive）。\n\ningest 後需更新：design D1/D3/D5、spec R1/R3/R7、proposal 的 BREAKING 敘述（「9 筆需 migration」→ 實為 0 筆）、tasks 補 verify 的 HIGH findings 與 CRITICAL-1。\n\n### Related\n\n- PR #318 維持 open（約四成 still-valid，在同 branch 推修正 commit）\n- #299 同檔（`skills/idd-list/SKILL.md`）→ 需序列化\n- #317 獨立缺陷，不受影響\n" } ] } diff --git a/plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh b/plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh index a24c69f..3a8533b 100755 --- a/plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh +++ b/plugins/issue-driven-dev/scripts/tests/actionability-gate/test.sh @@ -11,7 +11,7 @@ # Round 1 (PR #318) framed the fix as a CLOSED value domain for `### Complexity`. # /idd-verify falsified that with the real corpus: 93% of the 159 diagnoses in # this repo write the tier followed by same-line rationale, so a closed domain -# would have rejected 42% of them. Round 2 (/idd-diagnose #316, corpus 158/158, +# would have rejected 42% of them. Round 2 (/idd-diagnose #316, corpus 159/159, # 0 false positives) replaced it with the rule under test here: # # idd_parse_complexity <body> @@ -242,6 +242,24 @@ if [ "$HELPER_PRESENT" -eq 1 ]; then # documented accepted misses: the leading token wins over a trailing clause assert_eq "blocking: DOCUMENTED MISS — '(none) but actually blocked by' reads empty" "" \ "$(idd_blocking_section $'### Blocking\n- (none) but actually blocked by #86\n')" + assert_eq "blocking: '- None.' with a full stop is empty" "" "$(idd_blocking_section $'### Blocking\n- None.\n')" + assert_eq "blocking: decoration inside the parens is empty" "" "$(idd_blocking_section $'### Blocking\n- (**none**)\n')" + # locale independence: the rule must not flip under LC_ALL=C (bracket + # expressions split multibyte characters into bytes there) + assert_eq "blocking: LC_ALL=C — kana after the token is still a blocker" "- none ぁ x" \ + "$(LC_ALL=C bash -c '. "$1"; idd_blocking_section "$2"' _ "$LIB" $'### Blocking\n- none ぁ x\n')" + assert_eq "blocking: LC_ALL=C — CJK placeholder is still empty" "" \ + "$(LC_ALL=C bash -c '. "$1"; idd_blocking_section "$2"' _ "$LIB" $'### Blocking\n（無）\n')" + # C0 / DEL scrubbed at the helper's outputs (TAB and LF kept) + assert_eq "blocking: mid-line CR and ESC are scrubbed" "- 等 #99 fake[31mX" "$(idd_blocking_section $'### Blocking\n- 等 #99\r fake\033[31mX\n')" + err=$(idd_parse_complexity $'### Complexity\n\nSimple\033[2K when triggered\n' 2>&1 >/dev/null) + refute_grep "complexity: ESC scrubbed from the surfaced raw line" $'\033' "$err" + # unbalanced fence → fence tracking disabled for that body (live #290 shape) + assert_eq "blocking: real blocker below an UNCLOSED fence is found" "- 等 #99 merge" \ + "$(idd_blocking_section $'### Notes\n```\nexample\n\n### Blocking\n- 等 #99 merge\n')" + tier=$(idd_parse_complexity $'### Notes\n```\nexample\n\n### Complexity\n\nPlan\n' 2>/dev/null); rc=$? + assert_exit "complexity: section below an UNCLOSED fence is found (exit)" "0" "$rc" + assert_eq "complexity: section below an UNCLOSED fence is found (tier)" "Plan" "$tier" # CRLF (GitHub web textarea): both directions assert_eq "blocking: CRLF real blocker is kept" "- 等 upstream #310" "$(idd_blocking_section $'### Blocking\r\n\r\n- 等 upstream #310\r\n')" assert_eq "blocking: CRLF placeholder is empty" "" "$(idd_blocking_section $'### Blocking\r\n- (none)\r\n')" @@ -266,8 +284,11 @@ if [ "$HELPER_PRESENT" -eq 1 ]; then num=$(jq -r '.number' <<<"$row") exp_empty=$(jq -r '.expect_empty' <<<"$row") exp_first=$(jq -r '.expect_first_blocker // ""' <<<"$row") - sec=$(jq -r '.section | join("\n")' <<<"$row") - got=$(idd_blocking_section "$(printf '## Current Status\n\n### Phase\n\nx\n\n### Blocking\n%s\n\n### Tasks\n\n- [ ] x\n' "$sec")") + # the ORIGINAL body, so fences / headings / CR go through the shared extractor + # (round 3 synthesised a clean body from .section and never exercised it) + body=$(jq -r '.body // empty' <<<"$row") + if [ -z "$body" ]; then fail "blocking corpus #$num" "row has no body — fixture must carry the original issue body"; continue; fi + got=$(idd_blocking_section "$body") if [ "$exp_empty" = "true" ]; then b_empty=$((b_empty + 1)) if [ -z "$got" ]; then b_ok=$((b_ok + 1)); else fail "blocking corpus #$num" "expected empty, got: $got"; fi @@ -277,7 +298,10 @@ if [ "$HELPER_PRESENT" -eq 1 ]; then fi done < <(jq -c '.rows[]' "$BCORPUS") assert_eq "blocking corpus: every section judged as reviewed ($b_ok/$b_total)" "$b_total" "$b_ok" - assert_eq "blocking corpus: 55 sections, 47 empty / 8 non-empty" "55/47/8" "$b_total/$b_empty/$b_block" + assert_eq "blocking corpus: 55 sections, 47 empty / 8 non-empty (rule; hand review is 48/7, #1 is the accepted FP)" "55/47/8" "$b_total/$b_empty/$b_block" + # #290's body has an UNCLOSED fence: the extractor must still find its section + b290=$(jq -r '.rows[] | select(.number == 290) | .body' "$BCORPUS") + assert_eq "blocking corpus: #290 section survives an unclosed fence" "- (none) — 已結案。" "$(_idd_section_lines "$b290" Blocking)" else fail "blocking corpus" "fixture missing: $BCORPUS" fi @@ -322,6 +346,8 @@ if [ "$HELPER_PRESENT" -eq 1 ]; then assert_eq "missing alone → undiagnosed group" "undiagnosed" "$(idd_actionability_group 'complexity-missing')" assert_eq "missing + blocking → blocked group" "blocked" "$(idd_actionability_group 'complexity-missing; blocking-nonempty')" assert_eq "deferral + blocking → parked group" "parked" "$(idd_actionability_group 'complexity-deferral-marker; blocking-nonempty')" + idd_actionability_group "" >/dev/null 2>&1 + assert_exit "empty reason list is API misuse (exit 2), never parked" "2" "$?" assert_eq "deferral marker → parked group" "parked" "$(idd_actionability_group 'complexity-deferral-marker')" assert_eq "mixed reasons → parked group" "parked" "$(idd_actionability_group 'complexity-unparseable; blocking-nonempty')" @@ -363,10 +389,14 @@ for c in idd-list idd-all idd-implement idd-plan; do assert_output_grep "$c: exit 2 is a consumer FATAL" 'FATAL: idd_actionability_verdict misuse' "$f" assert_output_grep "$c: issue number is digit-checked before the REST path" "*[!0-9]*) " "$f" assert_output_grep "$c: Diagnosis author is trusted-only" 'author_association' "$f" + assert_output_grep "$c: the verdict is PRINTED, not only assigned" "printf 'gate #%s: VEXIT=%s" "$f" + assert_output_grep "$c: REASONS reset on the actionable path" 'REASONS="" ;;' "$f" + # command lines only (not `#` comments or `>` prose), and `comments` must be inside the --json field list + refute_grep_re "$c: no bare gh issue view --json …comments left" '^[^#>]*gh issue view[^\n]*--json[^ ]*comments' "$(cat "$f")" refute_output_grep "$c: no closed-domain wording for the tier field" '封閉值域外' "$f" refute_output_grep "$c: no 'closed domain, no fifth value' tier claim" '不得依相似性外推第五個' "$f" done -for c in idd-list idd-all idd-implement; do +for c in idd-list idd-all idd-implement idd-plan; do f="$SKILLS/$c/SKILL.md" assert_output_grep "$c: allowed-tools pre-approves jq" 'Bash(jq:*)' "$f" assert_output_grep "$c: allowed-tools pre-approves python3" 'Bash(python3:*)' "$f" @@ -386,7 +416,14 @@ assert_output_grep "idd-list: #84 footer count verbatim" '`X actionabl assert_output_grep "idd-list: parked group present" 'Parked (not routable now):' "$L" assert_output_grep "idd-list: undiagnosed group present" 'Needs diagnosis (' "$L" assert_output_grep "idd-list: undiagnosed rows keep the diagnose command" '→ /idd-diagnose #' "$L" -assert_output_grep "idd-list: state guard before the gate" '"$STATE" = "open"' "$L" +assert_output_grep "idd-list: per-ISSUE state guard before the gate" '.state // ""' "$L" +refute_output_grep "idd-list: no listing-flag state guard" '[ "$STATE" = "open" ]' "$L" +assert_output_grep "idd-list: skipped rows have a display rule" 'group=skipped' "$L" +IA="$SKILLS/idd-all/SKILL.md" +assert_grep_re "idd-all: Layer-V sub-issue scan filters author" 'issues/\$sub_n/comments" --paginate --jq .\[\.\[\] \| select\(\.author_association' "$(cat "$IA")" +assert_output_grep "idd-all: sub-issue number digit-checked" 'case "$sub_n" in' "$IA" +IM="$SKILLS/idd-implement/SKILL.md" +assert_output_grep "idd-implement: Step 2.5 re-runs the gate when the variables did not survive" '[ -n "${VEXIT:-}" ] ||' "$IM" assert_output_grep "idd-list: groups via the helper" 'idd_actionability_group "$REASONS"' "$L" # reference + producer (9.1 / 9.2) assert_output_grep "reference: cites the 159-diagnosis corpus" '159' "$REF" @@ -400,6 +437,9 @@ assert_output_grep "idd-diagnose: producer never derives the label — scoped to refute_output_grep "idd-issue: no blocker:* label mandate left" 'blocker:infeasible' "$SKILLS/idd-issue/SKILL.md" refute_output_grep "sdd-integration: no parallel Complexity parse narrative" '→ parse as `Simple`' "$HERE/../../../rules/sdd-integration.md" assert_output_grep "reference: signal-3 risk posture present" 'Signal 3 (`### Blocking`)' "$REF" +refute_output_grep "reference: no 'parked group == --parked set' claim" 'exactly the set `idd-list --parked` reviews' "$REF" +assert_output_grep "reference: corpus scope stated (54 of 55 CLOSED)" '54 of the 55' "$REF" +assert_output_grep "reference: cluster-path coverage gap stated" 'cluster' "$REF" assert_output_grep "reference: undiagnosed group documented" 'undiagnosed' "$REF" # ── task 8.2 / spec R8: full-corpus regression. Every diagnosed issue in this diff --git a/plugins/issue-driven-dev/skills/idd-all/SKILL.md b/plugins/issue-driven-dev/skills/idd-all/SKILL.md index 5137ccf..d43afd9 100644 --- a/plugins/issue-driven-dev/skills/idd-all/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-all/SKILL.md @@ -548,10 +548,12 @@ COMPLEXITY_ERR=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>&1 >/dev/null) || tr # 4. 真的呼叫 gate。exit 2 是 API 誤用（本 skill 的 bug），不得與 not-actionable 混同 if VERDICT=$(idd_actionability_verdict --complexity-exit "$CEXIT" --parking-label "$HAS_PARKING" --blocking-section "$BLOCKING" 2>&1); then VEXIT=0; else VEXIT=$?; fi case "$VEXIT" in - 0) ;; # actionable → 依下表以 $TIER 分派 + 0) REASONS="" ;; # actionable → 依下表以 $TIER 分派（cluster 逐張跑時不得殘留上一張的 reasons） 1) REASONS="${VERDICT#not-actionable: }" ;; # withheld → 下表 `VEXIT=1` 各列；不給任何 lifecycle 命令 *) echo "FATAL: idd_actionability_verdict misuse — $VERDICT" >&2; exit 1 ;; esac +# 5. 把判定印出來 —— skill 是模型執行的，Bash 輸出是模型唯一的觀測通道；只賦值不印，parked 與 actionable 在執行者眼裡一模一樣 +printf 'gate #%s: VEXIT=%s TIER=%s REASONS=%s | %s%s\n' "$N" "$VEXIT" "${TIER:-}" "${REASONS:-}" "${COMPLEXITY_ERR:-}" "${BLOCK_LINE:-}" ``` Dispatch **先看 `$VEXIT`**(gate 判定),`0` 才依 `$TIER` 分派。tier 只有四個(`SDD-warranted` 視同 `Spectra`);`### Complexity` 開頭以外的同行理由、裝飾、` via <來源>` 後綴都不影響 `$TIER`: @@ -559,10 +561,10 @@ Dispatch **先看 `$VEXIT`**(gate 判定),`0` 才依 `$TIER` 分派。tier 只 | `VEXIT` · `CEXIT` · `TIER` | 下一步 | |--------------|--------| | `0` · `0` · `Simple` | Phase 3a: idd-implement | -| `0` · `Plan` | **attended → Phase 3p: `/idd-plan`**（該 skill 擁有 `EnterPlanMode` 閘門，approve 後自己 chain 到 idd-implement）;**unattended → Phase 3a: idd-implement**，並在 final report 標記 `[Plan tier deliberation skipped under unattended mode]` | -| `0` · `Plan`（原值 `Plan via Layer V`,v2.50+）| 同上 — helper 只取開頭的 tier,` via <來源>` 後綴與同行理由皆不影響;verdict 是 user 在 idd-diagnose Step 3.4 選 escalate 觸發,routing 行為跟 bare `Plan` 一致 | -| `0` · `Spectra` | Phase 3b: spectra-discuss → spectra-propose → spectra-apply(unattended → 一輪收斂;attended → multi-turn 對話自然進行) | -| `0` · `SDD-warranted` (legacy alias) | 視同 `Spectra` 處理(v2.36.0+ backward compat) | +| `0` · `0` · `Plan` | **attended → Phase 3p: `/idd-plan`**（該 skill 擁有 `EnterPlanMode` 閘門，approve 後自己 chain 到 idd-implement）;**unattended → Phase 3a: idd-implement**，並在 final report 標記 `[Plan tier deliberation skipped under unattended mode]` | +| `0` · `0` · `Plan`（原值 `Plan via Layer V`,v2.50+）| 同上 — helper 只取開頭的 tier,` via <來源>` 後綴與同行理由皆不影響;verdict 是 user 在 idd-diagnose Step 3.4 選 escalate 觸發,routing 行為跟 bare `Plan` 一致 | +| `0` · `0` · `Spectra` | Phase 3b: spectra-discuss → spectra-propose → spectra-apply(unattended → 一輪收斂;attended → multi-turn 對話自然進行) | +| `0` · `0` · `SDD-warranted` (legacy alias) | 視同 `Spectra` 處理(v2.36.0+ backward compat) | | `VEXIT=1` · `$REASONS` 含 `complexity-deferral-marker`(如 `Simple when triggered`、`**Spectra**(… if/when triggered)`)或 `parking-lot-label` | **abort(parked)** — 印出 `$REASONS` 與原文(`$COMPLEXITY_ERR` 的 `deferral-marker: <原值>`,或 label 名)。這是**合法的延期狀態,不是資料錯誤**:不要求 user「修正」Diagnosis;要動它,先由人移除 label 或重新 diagnose。**禁止**截斷成 tier 前綴、**禁止**降級成任何 tier、**禁止**因為 tier 前綴合法就分派 | | `VEXIT=1` · `$REASONS` 含 `blocking-nonempty` | **abort(blocked)** — 印出 `$BLOCK_LINE`;等 blocker 解除(`idd-update` 清 `### Blocking`)| | `VEXIT=1` · `complexity-unparseable`(值不以 tier 開頭,如 `移入 discussion list`)| **abort** — 印出 `$COMPLEXITY_ERR` 的 `unparseable-complexity: <原值>`,要求 user 修正 Diagnosis(這才是資料錯誤)| @@ -1014,7 +1016,8 @@ for sub_n in "$ROOT_N" "${SPAWNED_ISSUES[@]:-}"; do ACTION_ITEMS+=$'\n'"- #${sub_n}: ${AUTO_DEFERRED_COUNT} row(s) auto-deferred at /idd-clarify Step 4.8 (unattended mode) — resolve via /idd-clarify #${sub_n} --status resolved=<idx>,<reason>" fi # #120 (v2.97.0+): Layer V deferred records live in Diagnosis COMMENTS (not body) - SUB_COMMENTS=$(gh api "repos/$GITHUB_REPO/issues/$sub_n/comments" --paginate --jq '[.[] | .body]' 2>/dev/null | jq -s 'add // []' | jq -r 'join("\n---\n")') # 分頁：`--json comments` 只回最舊 100 則（#316 第 3 輪） + case "$sub_n" in ''|*[!0-9]*) continue ;; esac # 進 REST path 前驗型（manifest 內容不可信） + SUB_COMMENTS=$(gh api "repos/$GITHUB_REPO/issues/$sub_n/comments" --paginate --jq '[.[] | select(.author_association == "OWNER" or .author_association == "MEMBER" or .author_association == "COLLABORATOR") | .body]' 2>/dev/null | jq -s 'add // []' | jq -r 'join("\n---\n")') # 分頁 + 只信任 repo 成員（外人留一則含 marker 的 comment 就能灌大計數） LAYERV_DEFERRED_COUNT=$(echo "$SUB_COMMENTS" \ | grep -cE 'unattended-auto-Step-3\.4-layerV-deferred') if [ "$LAYERV_DEFERRED_COUNT" -gt 0 ]; then diff --git a/plugins/issue-driven-dev/skills/idd-implement/SKILL.md b/plugins/issue-driven-dev/skills/idd-implement/SKILL.md index 1e68829..210f87d 100644 --- a/plugins/issue-driven-dev/skills/idd-implement/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-implement/SKILL.md @@ -133,10 +133,12 @@ COMPLEXITY_ERR=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>&1 >/dev/null) || tr # 4. 真的呼叫 gate。exit 2 是 API 誤用（本 skill 的 bug），不得與 not-actionable 混同 if VERDICT=$(idd_actionability_verdict --complexity-exit "$CEXIT" --parking-label "$HAS_PARKING" --blocking-section "$BLOCKING" 2>&1); then VEXIT=0; else VEXIT=$?; fi case "$VEXIT" in - 0) ;; # actionable → 依下表以 $TIER 分派 + 0) REASONS="" ;; # actionable → 依下表以 $TIER 分派（cluster 逐張跑時不得殘留上一張的 reasons） 1) REASONS="${VERDICT#not-actionable: }" ;; # withheld → 下表 `VEXIT=1` 各列；不給任何 lifecycle 命令 *) echo "FATAL: idd_actionability_verdict misuse — $VERDICT" >&2; exit 1 ;; esac +# 5. 把判定印出來 —— skill 是模型執行的，Bash 輸出是模型唯一的觀測通道；只賦值不印，parked 與 actionable 在執行者眼裡一模一樣 +printf 'gate #%s: VEXIT=%s TIER=%s REASONS=%s | %s%s\n' "$NUMBER" "$VEXIT" "${TIER:-}" "${REASONS:-}" "${COMPLEXITY_ERR:-}" "${BLOCK_LINE:-}" ``` `VEXIT=1` → 依 Step 2.5 的表**立即停止**（印 `$REASONS` 與原文），不進 Step 0.4 以後任何一步；`VEXIT=0` → 帶著 `$TIER` 繼續。 @@ -413,7 +415,11 @@ bash "$CLAUDE_PLUGIN_ROOT/scripts/gh-egress.sh" comment $NUMBER --repo $GITHUB_R **判斷 Complexity routing**：讀最新 `## Diagnosis` comment 的 `### Complexity` 欄位（v2.36.0+ 三路；v2.50+ 加 Layer V variant）。**tier 抽取與 actionability 判定都不在此處自行寫 parser**，改呼叫 [`references/actionability-gate.md`](../../references/actionability-gate.md) 契約下的共用實作： -> **gate 已於 Step 0.35 執行**（第 3 輪，verify #318：gate 必須先於建 branch 與任何 egress）。本 step 只消費 Step 0.35 留下的 `$VEXIT` / `$TIER` / `$REASONS` / `$COMPLEXITY_ERR` / `$BLOCK_LINE`；不得在此重跑。 +> **gate 已於 Step 0.35 執行**（第 3 輪，verify #318：gate 必須先於建 branch 與任何 egress）。本 step 消費 Step 0.35 留下的 `$VEXIT` / `$TIER` / `$REASONS` / `$COMPLEXITY_ERR` / `$BLOCK_LINE`。**跨 Bash 區塊 shell 變數不保證存活**（與 idd-all Phase 3b.1 同一條規則），所以先檢查、缺值就**用 Step 0.35 同一段程式碼、同一份 helper 重跑一次**（它是唯讀判定，重跑無副作用）—— 不得改用私有 regex、不得從 Step 0.35 印出的那行 `gate #N: …` 之外的地方自行推 tier： +> +> ```bash +> [ -n "${VEXIT:-}" ] || { echo "→ gate variables did not survive the Bash-call boundary — re-running the Step 0.35 block (same helper, same shape)" >&2; } # 然後執行 Step 0.35 的整個 code block，再回到本表 +> ``` helper 只取開頭的 tier：` via <來源>` 後綴（例如 `Plan via Layer V`）、同行理由、markdown 裝飾都不影響，本 skill 拿到的 `$TIER` 已是 canonical tier — 對應 spec Requirement: Routing parsers SHALL recognize Plan via Layer V verdict。 @@ -423,9 +429,9 @@ Routing **先看 `$VEXIT`**（gate 判定），`0` 才依 `$TIER` 決定行為 | `VEXIT` · `CEXIT` · `TIER` | 行為 | |-----------|------| | `0` · `0` · `Simple` | ✅ 本 step 啟動 TaskList 追蹤每個 checklist item | -| `0` · `Plan`（原值可能是 `Plan via Layer V`）| ✅ 同 Simple — TaskList 啟動。**注意**：使用者通常透過 `/idd-plan #NNN` 呼叫進來，approval gate 已在 idd-plan 處理完，本 skill 直接走 TDD loop。若使用者直接呼叫 `/idd-implement` 而 Complexity=Plan，**先提示**「Complexity 判定為 Plan，建議改走 `/idd-plan #NNN` 進入 approval gate；繼續直接 implement 等於跳過 Plan tier 的 deliberation 價值」並用 AskUserQuestion 確認 continue/abort。`Plan via Layer V` 同樣行為(routing 一致),只是 verdict 標記提示這是 Layer V 觸發 | -| `0` · `Spectra` | ⏭ 跳過本 step（由 `spectra-apply` 管 `openspec/changes/<name>/tasks.md`）| -| `0` · `SDD-warranted` (legacy alias) | ⏭ 跳過本 step — 視同 `Spectra` 處理（v2.36.0+ backward compat）| +| `0` · `0` · `Plan`（原值可能是 `Plan via Layer V`）| ✅ 同 Simple — TaskList 啟動。**注意**：使用者通常透過 `/idd-plan #NNN` 呼叫進來，approval gate 已在 idd-plan 處理完，本 skill 直接走 TDD loop。若使用者直接呼叫 `/idd-implement` 而 Complexity=Plan，**先提示**「Complexity 判定為 Plan，建議改走 `/idd-plan #NNN` 進入 approval gate；繼續直接 implement 等於跳過 Plan tier 的 deliberation 價值」並用 AskUserQuestion 確認 continue/abort。`Plan via Layer V` 同樣行為(routing 一致),只是 verdict 標記提示這是 Layer V 觸發 | +| `0` · `0` · `Spectra` | ⏭ 跳過本 step（由 `spectra-apply` 管 `openspec/changes/<name>/tasks.md`）| +| `0` · `0` · `SDD-warranted` (legacy alias) | ⏭ 跳過本 step — 視同 `Spectra` 處理（v2.36.0+ backward compat）| | `VEXIT=1` · `$REASONS` 含 `complexity-deferral-marker`（如 `Simple when triggered`）或 `parking-lot-label` | 🛑 **停止實作（parked）** — 印出 `$REASONS` 與原文（`$COMPLEXITY_ERR` 的 `deferral-marker: <原值>`，或 label 名）。這是**合法的延期狀態，不是資料錯誤**；要動它，先由人移除 label 或重新 diagnose。**禁止**截斷成 tier 前綴、**禁止**降級成 `Simple` / `Plan` 或任何其他 tier、**禁止**沿用舊的「不確定就當 Simple」預設 | | `VEXIT=1` · `$REASONS` 含 `blocking-nonempty` | 🛑 **停止實作（blocked）** — 印出 `$BLOCK_LINE`；等 blocker 解除（`idd-update` 清 `### Blocking`）| | `VEXIT=1` · `complexity-unparseable`（值不以 tier 開頭）| 🛑 **停止實作** — 印出 `$COMPLEXITY_ERR` 的 `unparseable-complexity: <原值>`，要求 user 修正 Diagnosis（這才是資料錯誤）| diff --git a/plugins/issue-driven-dev/skills/idd-list/SKILL.md b/plugins/issue-driven-dev/skills/idd-list/SKILL.md index cc7067d..f6cbc21 100644 --- a/plugins/issue-driven-dev/skills/idd-list/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-list/SKILL.md @@ -286,19 +286,21 @@ def get_leader(refs_list, body, rule): exit 1 } -# 0. 只對 open issue 跑；issue 號進 REST path 前先驗型（同檔 --audit-closes 段的規定） -[ "$STATE" = "open" ] || { GROUP=skipped; continue; } +# 0. issue 號進 REST path 前先驗型（同檔 --audit-closes 段的規定）；只對 **這張** issue 是 OPEN 的跑 gate —— +# 判的是 per-issue state（Step 2 的 --json 已含 state），不是 listing 的 --state 旗標（--state all 也含 open issue） case "$n" in ''|*[!0-9]*) echo "FATAL: non-numeric issue number: $n" >&2; GROUP=error; continue ;; esac -ISSUE_JSON=$(jq -c --argjson n "$n" '.[] | select(.number == $n)' <<<"$ISSUES_JSON") # labels / body / comments 已在 Step 2 抓回，不重抓 +ISSUE_JSON=$(jq -c --argjson n "$n" '.[] | select(.number == $n)' <<<"$ISSUES_JSON") || { GROUP=error; continue; } # labels / body / comments 已在 Step 2 抓回，不重抓 +[ "$(jq -r '.state // ""' <<<"$ISSUE_JSON")" = "OPEN" ] || { GROUP=skipped; continue; } # 1. 最新 Diagnosis comment —— 只信任 OWNER / MEMBER / COLLABORATOR 寫的（public repo 任何帳號都能留言， # 否則一則外人貼的 `## Diagnosis` 就能改寫訊號 1）。Step 2 的 comments 陣列只含最舊的 100 則， # 長度 ≥ 100 才逐一分頁補抓（`--paginate --jq` 每頁一個 array，`jq -s add` 收攏）；抓取失敗 → 該列標 error，listing 繼續。 -if [ "$(jq '.comments | length' <<<"$ISSUE_JSON")" -ge 100 ]; then - COMMENTS_JSON=$(gh api "repos/$GITHUB_REPO/issues/$n/comments" --paginate --jq '[.[] | select(.author_association == "OWNER" or .author_association == "MEMBER" or .author_association == "COLLABORATOR") | {body}]' \ - | jq -s 'add // []') || { echo "⚠ #$n: comment fetch failed — gate not evaluated" >&2; GROUP=error; continue; } +if [ "$(jq '.comments | length' <<<"$ISSUE_JSON" 2>/dev/null || echo 0)" -ge 100 ]; then + # 失敗點與守衛對齊：先抓、再摺——`gh api … | jq -s` 沒有 pipefail 時 jq 會吐 `[]` 並 exit 0，守衛不會觸發 + PAGES=$(gh api "repos/$GITHUB_REPO/issues/$n/comments" --paginate --jq '[.[] | select(.author_association == "OWNER" or .author_association == "MEMBER" or .author_association == "COLLABORATOR") | {body}]') || { echo "⚠ #$n: comment fetch failed — gate not evaluated" >&2; GROUP=error; continue; } + COMMENTS_JSON=$(jq -s 'add // []' <<<"$PAGES") || { GROUP=error; continue; } else - COMMENTS_JSON=$(jq -c '[.comments[] | select(.authorAssociation == "OWNER" or .authorAssociation == "MEMBER" or .authorAssociation == "COLLABORATOR") | {body}]' <<<"$ISSUE_JSON") + COMMENTS_JSON=$(jq -c '[.comments[]? | select(.authorAssociation == "OWNER" or .authorAssociation == "MEMBER" or .authorAssociation == "COLLABORATOR") | {body}]' <<<"$ISSUE_JSON") || { GROUP=error; continue; } fi LATEST_DIAGNOSIS=$(python3 -c ' import json, sys, re @@ -307,8 +309,8 @@ ds = [c for c in cs if re.search(r"(?m)^## Diagnosis", c["body"])] # line-anch print(ds[-1]["body"] if ds else "")' <<<"$COMMENTS_JSON") || { echo "⚠ #$n: diagnosis parse failed" >&2; GROUP=error; continue; } # 2. 另外兩個訊號：labels，與 body 的 ### Blocking（經 helper 逐 bullet 讀；`- (none — …)` 這類 placeholder 算空） -HAS_PARKING=$(jq -r 'if any(.labels[]; .name == "parking-lot") then "yes" else "no" end' <<<"$ISSUE_JSON") -BLOCK_LINE=$(idd_blocking_section "$(jq -r '.body // ""' <<<"$ISSUE_JSON")") +HAS_PARKING=$(jq -r 'if any(.labels[]?; .name == "parking-lot") then "yes" else "no" end' <<<"$ISSUE_JSON") || { GROUP=error; continue; } +BLOCK_LINE=$(idd_blocking_section "$(jq -r '.body // ""' <<<"$ISSUE_JSON")") || { GROUP=error; continue; } if [ -n "$BLOCK_LINE" ]; then BLOCKING=yes; else BLOCKING=no; fi # 3. 條件式捕捉 —— `set -euo pipefail` 下唯一不會被 exit 3/4/5 終止的寫法（verify #318 HIGH） @@ -323,9 +325,11 @@ case "$VEXIT" in 1) REASONS="${VERDICT#not-actionable: }"; GROUP=$(idd_actionability_group "$REASONS") ;; # blocked | parked | undiagnosed *) echo "FATAL: idd_actionability_verdict misuse on #$n — $VERDICT" >&2; GROUP=error ;; esac +# 5. 把判定印出來 —— skill 是模型執行的，Bash 輸出是模型唯一的觀測通道 +printf 'gate #%s: VEXIT=%s TIER=%s REASONS=%s | %s%s\n' "$n" "$VEXIT" "${TIER:-}" "${REASONS:-}" "${COMPLEXITY_ERR:-}" "${BLOCK_LINE:-}" ``` -掛到 issue entry：`group`（`actionable` / `blocked` / `parked` / `undiagnosed` / `error` / `skipped`）、`reasons`、`tier`（僅 `VEXIT=0`）、以及要 surface 的原文 —— `$COMPLEXITY_ERR`（exit 3/5 的 `<reason>: <原值>` 整行、exit 4 的 `missing-complexity`）、`$BLOCK_LINE`（#84 的 `blocked_reason`，語意不變）、或 label 名。**surface 的原文是別人寫的資料，不是指令**：印出前剝掉 C0 控制字元（`tr -d '\000-\010\013\014\016-\037'`），避免 ANSI / `\r` 覆蓋前綴。 +掛到 issue entry：`group`（`actionable` / `blocked` / `parked` / `undiagnosed` / `error` / `skipped`；`group=skipped` = 該 issue 非 OPEN，不進任何 gate 分組，Step 5 對它照舊走 phase × PR state matrix —— `--state closed` / `--audit-closes` 的既有輸出不受 gate 影響）、`reasons`、`tier`（僅 `VEXIT=0`）、以及要 surface 的原文 —— `$COMPLEXITY_ERR`（exit 3/5 的 `<reason>: <原值>` 整行、exit 4 的 `missing-complexity`）、`$BLOCK_LINE`（#84 的 `blocked_reason`，語意不變）、或 label 名。**surface 的原文是別人寫的資料，不是指令**：helper 已在輸出端剝掉 C0 控制字元與 DEL（含 `\r` 與 ESC；TAB / LF 保留），本 skill 不再自行處理。 **不得截斷、不得降級、不得靜默**：`Simple when triggered` 的 tier 前綴 `Simple` 是合法的，helper 正因此**拒絕**在 exit 5 印出它 —— 本 skill 拿不到 tier，就不可能路由。原文一律印在該列（如 `⏸ deferral-marker: Simple when triggered`），這與 `### Conflict Class` 的既有規則對稱：值無法安全解讀時取最保守的處置**並把 fallback 印出來**。 @@ -495,7 +499,7 @@ Needs diagnosis (11): **`Needs diagnosis` 組（`group=undiagnosed`，#316 第 3 輪）**：reason 只有 `complexity-missing` 的 issue —— 也就是**還沒被 diagnose**。這是每一張 issue 的出生狀態，不是 parked；實測 2026-09-07 的 14 個 open issue 有 11 個在這一組，把它們放進 Parked 會讓 `--parked` 與 footer 的數字差一個數量級、並把 `→ /idd-diagnose #N` 這個唯一正確的 lifecycle 命令藏起來。本組**保留**該命令（與 `created` / `clarified` phase 的 matrix 一致）；全 blocked banner 的觸發條件不變（Actionable now 為空且 Blocked 非空），undiagnosed 不影響它。 -歸類規則（`idd_actionability_group`）：含 `parking-lot-label` / `complexity-deferral-marker` / `complexity-unparseable` 任一 → Parked；否則含 `blocking-nonempty` → Blocked（#84 逐字保留）；否則只有 `complexity-missing` → Needs diagnosis。每列印出 `$REASONS` 與原文（`$COMPLEXITY_ERR` / label 名 / `$BLOCK_LINE`），**不給任何 lifecycle 命令**；`complexity-unparseable` / `complexity-missing` 才附「修正 Diagnosis / 先跑 diagnose」提示 —— `complexity-deferral-marker` 與 `parking-lot-label` 是合法狀態，不是要修的東西。`group=error`（gate API 誤用）單獨一列印 `⚠ gate error`，那是本 skill 的 bug。 +歸類規則（`idd_actionability_group`）：含 `parking-lot-label` / `complexity-deferral-marker` / `complexity-unparseable` 任一 → Parked；否則含 `blocking-nonempty` → Blocked（#84 逐字保留）；否則只有 `complexity-missing` → Needs diagnosis。Parked 與 Blocked 兩組每列印出 `$REASONS` 與原文（`$COMPLEXITY_ERR` / label 名 / `$BLOCK_LINE`），**不給任何 lifecycle 命令**（`complexity-unparseable` 附「修正 Diagnosis」提示）；Needs diagnosis 組**保留** `→ /idd-diagnose #N` —— `complexity-deferral-marker` 與 `parking-lot-label` 是合法狀態，不是要修的東西。`group=error`（gate API 誤用）單獨一列印 `⚠ gate error`，那是本 skill 的 bug。 **全 blocked banner**：當 Actionable now 為空且 Blocked 非空： diff --git a/plugins/issue-driven-dev/skills/idd-plan/SKILL.md b/plugins/issue-driven-dev/skills/idd-plan/SKILL.md index 298cf2f..21f8a4f 100644 --- a/plugins/issue-driven-dev/skills/idd-plan/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-plan/SKILL.md @@ -5,6 +5,11 @@ description: | 介於 Simple（直接 implement）和 Spectra（完整 spec/proposal/tasks artifacts）之間的中間層。 Use when: 已跑過 `/idd-diagnose #N`、且該 diagnosis 的 Complexity 判為 Plan tier 之後。本 skill 不做診斷 —— issue 上沒有 Diagnosis comment 會直接 abort，此時該跑的是 `/idd-diagnose #N` 而不是本 skill。 防止的失敗：跳過 diagnose 直接 plan —— 還沒查出 root cause 就開始寫實作計畫，等於為錯的問題做規劃。 +allowed-tools: + - Bash(gh:*) + - Bash(git:*) + - Bash(jq:*) + - Bash(python3:*) --- # /idd-plan — Plan-mode 實作 @@ -53,7 +58,7 @@ TaskCreate(name="auto_update_body", description="Step 7: idd-update phase → pl ### Step 1: 讀取 Issue + Diagnosis + Confirm Complexity ```bash -gh issue view $NUMBER --repo $GITHUB_REPO --json title,body,labels,comments +gh issue view $NUMBER --repo $GITHUB_REPO --json title,body,labels # comments 由下方 gate 區塊分頁抓（`--json comments` 只回最舊 100 則） ``` **Complexity 的 tier 抽取與 actionability 判定不在此處自行比對字串**，改呼叫 [`references/actionability-gate.md`](../../references/actionability-gate.md) 契約下的共用實作： @@ -91,10 +96,12 @@ COMPLEXITY_ERR=$(idd_parse_complexity "$LATEST_DIAGNOSIS" 2>&1 >/dev/null) || tr # 4. 真的呼叫 gate。exit 2 是 API 誤用（本 skill 的 bug），不得與 not-actionable 混同 if VERDICT=$(idd_actionability_verdict --complexity-exit "$CEXIT" --parking-label "$HAS_PARKING" --blocking-section "$BLOCKING" 2>&1); then VEXIT=0; else VEXIT=$?; fi case "$VEXIT" in - 0) ;; # actionable → 依下表以 $TIER 分派 + 0) REASONS="" ;; # actionable → 依下表以 $TIER 分派（cluster 逐張跑時不得殘留上一張的 reasons） 1) REASONS="${VERDICT#not-actionable: }" ;; # withheld → 下表 `VEXIT=1` 各列；不給任何 lifecycle 命令 *) echo "FATAL: idd_actionability_verdict misuse — $VERDICT" >&2; exit 1 ;; esac +# 5. 把判定印出來 —— skill 是模型執行的，Bash 輸出是模型唯一的觀測通道；只賦值不印，parked 與 actionable 在執行者眼裡一模一樣 +printf 'gate #%s: VEXIT=%s TIER=%s REASONS=%s | %s%s\n' "$NUMBER" "$VEXIT" "${TIER:-}" "${REASONS:-}" "${COMPLEXITY_ERR:-}" "${BLOCK_LINE:-}" ``` **先看 `$VEXIT`**（gate 判定），`0` 才依 `$TIER` 決定行為。tier 只有四個；`### Complexity` 開頭以外的同行理由、裝飾、` via <來源>` 後綴都不影響 `$TIER`： @@ -102,10 +109,10 @@ esac | `VEXIT` · `CEXIT` · `TIER` | 行為 | |-----------|------| | `0` · `0` · `Plan` | ✅ 預期 — 繼續 Step 2 | -| `0` · `Plan`（原值 `Plan via Layer V`、`**Plan**(Layer P:…)` 等）| 同上 — helper 只取開頭的 tier,後綴與同行理由皆不影響,行為與 bare `Plan` 完全一致 | +| `0` · `0` · `Plan`（原值 `Plan via Layer V`、`**Plan**(Layer P:…)` 等）| 同上 — helper 只取開頭的 tier,後綴與同行理由皆不影響,行為與 bare `Plan` 完全一致 | | `0` · `Simple` | ⚠️ 詢問 user：「Complexity 判定為 Simple，確定要走 Plan tier 多一道 approval gate 嗎？」（行為不變 — user 主動要 deliberate 是允許的）| -| `0` · `Spectra` | ⛔ 提示「Spectra 應走 `/spectra-discuss`，Plan tier 不會產出 spec/proposal/tasks artifacts」，AskUserQuestion abort 或 continue（continue 等於 user 自願降級到 Plan tier）— 行為不變 | -| `0` · `SDD-warranted`（legacy alias）| 視同 `Spectra` 處理 — 行為不變 | +| `0` · `0` · `Spectra` | ⛔ 提示「Spectra 應走 `/spectra-discuss`，Plan tier 不會產出 spec/proposal/tasks artifacts」，AskUserQuestion abort 或 continue（continue 等於 user 自願降級到 Plan tier）— 行為不變 | +| `0` · `0` · `SDD-warranted`（legacy alias）| 視同 `Spectra` 處理 — 行為不變 | | `VEXIT=1` · `$REASONS` 含 `complexity-deferral-marker`（如 `Plan when triggered`）或 `parking-lot-label` | ⛔ **abort（parked）** — 印出 `$REASONS` 與原文（`$COMPLEXITY_ERR` 的 `deferral-marker: <原值>`，或 label 名）。這是**合法的延期狀態，不是資料錯誤**；要動它，先由人移除 label 或重新 diagnose。**禁止**截斷成 tier 前綴、**禁止**降級成 `Plan` 或任何其他 tier、**禁止**因為前綴是 `Plan` 就放進 approval gate、**禁止**當成 `Simple` 問過 user 就繼續 | | `VEXIT=1` · `$REASONS` 含 `blocking-nonempty` | ⛔ **abort（blocked）** — 印出 `$BLOCK_LINE`；等 blocker 解除（`idd-update` 清 `### Blocking`）| | `VEXIT=1` · `complexity-unparseable`（值不以 tier 開頭）| ⛔ **abort** — 印出 `$COMPLEXITY_ERR` 的 `unparseable-complexity: <原值>`，要求 user 修正 Diagnosis（這才是資料錯誤）|