diff --git a/openspec/changes/archive/2026-11-21-verify-stop-modes/.openspec.yaml b/openspec/changes/archive/2026-11-21-verify-stop-modes/.openspec.yaml new file mode 100644 index 00000000..dda1af20 --- /dev/null +++ b/openspec/changes/archive/2026-11-21-verify-stop-modes/.openspec.yaml @@ -0,0 +1,6 @@ +schema: spec-driven +created: 2026-11-21 +created_by: che cheng +created_with: claude +archived_by: che cheng +archived_at: 2026-11-21 diff --git a/openspec/changes/archive/2026-11-21-verify-stop-modes/design.md b/openspec/changes/archive/2026-11-21-verify-stop-modes/design.md new file mode 100644 index 00000000..90930097 --- /dev/null +++ b/openspec/changes/archive/2026-11-21-verify-stop-modes/design.md @@ -0,0 +1,113 @@ +## Context + +`/idd-all` 的 Phase 4(`plugins/issue-driven-dev/skills/idd-all/SKILL.md`)用 `MAX_ROUND = 2 if INTERACTION == "unattended" else 1` 決定 verify 跑幾輪;attended 不自動修。會不會合併由 `plugins/issue-driven-dev/scripts/close-stage.py` 決定:`gate` 子指令把最新的 verify 報告交給 `verify-gate.py`,回傳 `status`、`blocking`、`in_scope`、`low_in_scope` 等計數;`run` 子指令經 `gate_stop()` 只放行 `clean`。run-state(`.claude/.idd/state/idd-all-run-.json`)由 `cmd_init` 寫入,只有 path、interaction、branch、`--review`、`--in-chain` 等旗標與建立時間,沒有輪數;`load_state()` 拒絕超過 `STATE_TTL`(24 小時)的紀錄。 + +維護者 2026-11-21 在 #595 決定:停止條件做成三種可選模式,early stop 依收斂數、窮盡到沒有 Blocking、完全窮盡沒有上限;合併條件依模式;attended 也照設定。spectra-discuss 的五點建議都照原樣採用。 + +## Goals / Non-Goals + +**Goals:** + +- 三種停止模式,由 config 或 flag 選;沒有設定時行為逐字不變。 +- 要不要再跑一輪、停下時要不要合併,由 `close-stage.py` 依 run-state 的紀錄判斷,不靠 model 記得。 +- 沒有設定模式的 run,兩輪上限也由程式把關(#591)。 +- 回報寫明停止的原因。 + +**Non-Goals:** + +- 不改 verify 本身怎麼審(reviewer、席位、報告格式)。不重報已定的點是 #596。 +- 不改 `/idd-all-chain` 的 cluster 流程;`--in-chain` 的 run 照舊不合併。 +- 不處理沒有設定模式的 run 的 24 小時期限(#576 的其餘部分)。 +- 不加時間或額度上限。 + +## Decisions + +### 收斂數數的是要修的列 + +to-fix count = `blocking + in_scope - low_in_scope`,也就是這個迴圈本來就會去修的列。Follow-up 另開 issue、Rejected 直接停,都不在迴圈裡,所以不算。`--review`、`--in-chain` 的 run 只修 Blocking,to-fix count 就是 `blocking`。 + +替代方案:數全部的列(含 Follow-up),會把不在迴圈裡處理的列當成沒有收斂;依嚴重度加權,需要另外定權重,而 gate 只有三個計數。 + +### early stop 以嚴格下降判斷收斂 + +從第 2 輪起,to-fix count 沒有比上一輪少就停。列數是非負整數,嚴格下降的序列最多 `第一輪的數 + 1` 項,所以一定會停;這就是維護者要的「early stop 一定會停」。 + +替代方案:連續 k 輪不下降才停。k 是另一個要調的參數,而且失去「一定會停」的簡單上界。 + +### exhaustive-blocking 用連續兩輪不下降當保底 + +Blocking 為 0 就停;Blocking 連續兩輪沒有比前一輪少也停。給修正一次機會:修一個 Blocking 有時會暴露另一個。沒有保底的話,這一種和 exhaustive-all 一樣可能停不下來,差別只剩目標。 + +### exhaustive-all 沒有輪數上限 + +照維護者的決定。仍然會停的情況只有三種:歸零、遇到不自動修的 finding(安全漏洞)、使用者中斷。gate 讀不出報告或有 Rejected finding 時照舊停。 + +### 每輪的計數由 gate 寫進 run-state + +`close-stage.py gate` 讀到一份這次 run 還沒讀過的報告時,在 run-state 的 `rounds` 陣列加一筆:`round`、`sha`、`blocking`、`in_scope`、`low_in_scope`、`at`(寫入時間)。用報告的 comment id 判斷是不是讀過,同一份報告重讀不加一輪。 + +另外每判一個新的 commit、或同一個 commit 上讀到新的報告,gate 在 `attempts` 加一筆(`sha`、`report_id`、`at`);同一個 commit 重讀同一份報告不加。只看 commit 的話,修正沒有產生 commit 時輪數不會增加,迴圈沒有終點(修正輪複查指出)。沒有模式的 run 以 `attempts` 計輪數:報告沒貼出或讀不出的那一輪也算,和 #595 之前「迴圈跑了幾次」相同(spectra-verify W1 與 spectra-review #2 指出只數報告會讓這種輪次漏算、多跑一輪)。寫紀錄失敗時 gate 回 `unparseable`(exit 2),不讓一輪沒記到的結果被當成判過的一輪。寫在 gate 裡,因為每一輪本來就一定會呼叫 gate;另外加一個「記一輪」的指令,model 忘了呼叫就會少記。 + +### 要不要再跑一輪由 close-stage.py next 判斷 + +新子指令 `close-stage.py next --cwd --repo --issue`,讀 run-state 的模式與 `rounds`,印一行 JSON:`{"decision": "fix" | "stop", "merge": true | false, "reason": "...", "mode": "...", "rounds": [...]}`。Phase 4 的迴圈照 `decision` 走。判斷由 close-stage.py 提供,因為它已經擁有 run-state 與 gate;判定表本身是一個不讀 GitHub 的純函式,放在 `scripts/lib/stopmode.py`(close-stage.py 已超過 800 行,照 repo 的檔案大小慣例拆出;它和 `lib/workflows.py`、`lib/intent.py` 一樣只被 close-stage.py 使用)。 + +`next` 也處理沒有設定模式的 run:無人值守在第 2 輪後回 stop、attended 在第 1 輪後回 stop,與現在的 `MAX_ROUND` 相同。這樣 Phase 4 只有一條路,`MAX_ROUND` 只剩「沒有設定模式」那一列。 + +### 停止模式的合併也要求覆蓋率行與 reviewers 行完整 + +verify-gate.py 原本只在 PASS 時檢查覆蓋率行(`X / X requirements addressed`)與 reviewers 行;FAIL 的報告在那之前就回 `not_clean`。停止模式會合併 FAIL 的一輪,所以 verify-gate 對每種判定都輸出 `coverage_complete` 與 `reviewers_complete`,close-stage.py 的停止模式合併要求兩者都是 `true`(spectra-verify C1、spectra-review #1)。乾淨的合併照舊由 verify-gate 自己擋。 + +### 停下時合併的是最後一輪審過的 commit + +`next` 回 `merge: true` 時,`close-stage.py run` 放行那個結果,但仍要求 HEAD 就是最後一輪審過的 commit(gate 本來就以 `--sha` 綁定)。剩下的列合成一張 follow-up issue,做法與現在的 `low_in_scope` 相同。停下之後不再加修正,否則那些修正沒有人審過。 + +### 設了模式的 attended run 也自動修 + +照維護者的決定。attended 的差別只剩 sub-skill 照常可以問問題;不自動修的 finding(安全漏洞)停下交回。沒設模式的 attended run 不變。 + +### 設了模式的 run,期限從最後一輪算 + +`load_state()` 對有 `verify_stop` 模式的紀錄,以 `rounds` 最後一筆的 `at` 計算年齡;沒有 `rounds` 時用建立時間。沒有設定模式的 run 不變。 + +### config 值寫錯時當成沒有模式 + +`verify_stop.mode` 不是三個值之一時,當成沒有設定並印一行。沒有設定的行為比任何模式都保守(較少自動合併),所以寫錯不會放寬。`--stop` 是使用者這一次明確給的值,寫錯就在 Phase 1 之前停下,免得使用者以為照他說的模式在跑。 + +## Implementation Contract + +**行為** + +- `idd-all` 在模式解析時印出停止模式(或「沒有停止模式」),寫進 run-state 的 `verify_stop` 欄位(`null` 或三個值之一)。 +- 每一輪 verify 之後,Phase 4 跑 gate,再跑 `close-stage.py next`,照它的 `decision` 修或停。停下時 Phase 6 的回報有一行:模式、輪數、每輪的 to-fix count、`next` 的 `reason`。 +- `close-stage.py run` 合併的條件:沒有模式時與現在相同(`clean`,且沒有模式的無人值守 run 的 `rounds` 不超過 2 筆);有模式時是 `next` 對最後一輪回 `merge: true`,其餘 guardrail 照舊。 + +**資料形狀** + +- run-state 新欄位:`"verify_stop": null | "early" | "exhaustive-blocking" | "exhaustive-all"`、`"rounds": [{"round": 1, "sha": "<40 hex>", "status": "clean|not_clean|unparseable", "blocking": 0, "in_scope": 0, "low_in_scope": 0, "rejected": 0, "report_id": , "at": ""}]`、`"last_gate": {"status", "report_id", "sha", "reason", "at"}`(每次 gate 都更新,`next` 用它判斷最新的結果是不是最新的那一輪)。 +- `cmd_init` 多一個必填引數 `--stop `,與其他引數一樣不接受預設值。 +- config:`"verify_stop": {"mode": "early"}`,寫在 `references/config-protocol.md` 的新節。 + +**失敗模式** + +- `next` 讀不到 run-state、或 `rounds` 是空的:回 `stop`、`merge: false`,`reason` 寫明,結束碼非 0。不會因為讀不到而回 `fix`。 +- gate 結果是 `unparseable`:找到了報告(被編輯過、被隱藏、沒有 HTML、verify-gate 沒有輸出 JSON)時仍記一筆,計數為 `null`;找不到報告時不記一輪,但 `last_gate` 記下這次的結果。兩種情況 `next` 都回 `stop`、`merge: false`。 + +**驗收** + +- `plugins/issue-driven-dev/scripts/tests/close-stage/scenarios.sh` 對 spec 裡每一個 Scenario 有一個情境,用假的 run-state 與 gate 結果驗 `next` 的輸出與 `run` 是否放行。 +- 沒有設定模式時,現有 close-stage 測試全部通過、輸出不變。 +- `idd-all` 的 SKILL.md Phase 4 只剩一條由 `next` 驅動的迴圈;`MAX_ROUND` 這個名字不再出現。 + +**範圍** + +- 在範圍內:close-stage.py 的 `init`、`gate`、`next`、`run`、`load_state`;idd-all SKILL.md 的 Step 0.2、Step 0.7、Phase 4、Phase 5c 的表、Phase 6;config-protocol.md 的新欄位;close-stage 測試。 +- 不在範圍內:idd-verify、verify-gate.py 的判定、idd-all-chain、沒有模式的 run 的期限。 + +## Risks / Trade-offs + +- [設了模式的 run 會自動合併 verify 不乾淨的 commit] → 只合併最後一輪審過的 commit;剩下的列一定開成 follow-up issue;模式要明確設定才生效,預設不變。 +- [exhaustive-all 沒有上限,成本與時間沒有界線] → 回報每輪的數字,讓使用者看得出是否在空轉;使用者隨時可中斷。這是維護者接受的取捨。 +- [重報的列讓收斂數看起來沒下降,early 提早停] → #596 解決重報;在那之前,early 的行為偏保守(提早停),不會偏向多合併。 +- [自動修正越多輪,越容易為了消掉某一列改壞別處] → 每一輪仍經完整 verify;合併前的 guardrail 照舊。 +- [一份報告被編輯後重讀] → 以 comment id 判斷讀過與否,編輯過的報告不算新的一輪;gate 本來就不讀發出後才編輯的判定。 diff --git a/openspec/changes/archive/2026-11-21-verify-stop-modes/proposal.md b/openspec/changes/archive/2026-11-21-verify-stop-modes/proposal.md new file mode 100644 index 00000000..540f5f68 --- /dev/null +++ b/openspec/changes/archive/2026-11-21-verify-stop-modes/proposal.md @@ -0,0 +1,39 @@ +**GitHub-side tracker**: #595 + +## Why + +`/idd-all` 的 verify 什麼時候停只有一條寫死的規則:無人值守最多 2 輪(中間修一次)、attended 1 輪就交回使用者,而且只有 verify 判定乾淨才自動合併。還在收斂的 issue 因此被提早停下,要人回來接手;不收斂的 issue 則只能靠維護者每一批在對話裡另訂規則(#595)。這條上限也只寫在 SKILL.md,沒有程式把關,compaction 之後會被超過(#591)。 + +## What Changes + +- 新增可設定的停止模式:repo config 的 `verify_stop.mode` 設預設,`/idd-all --stop ` 覆蓋這一次。三種模式: + - `early`:依收斂數停。每一輪「要修的列」(Blocking 加上非 LOW/INFO/P3 的 In-scope fix)沒有比上一輪少就停。 + - `exhaustive-blocking`:修到 Blocking 為 0;Blocking 連續兩輪沒有下降時停。 + - `exhaustive-all`:修到 Blocking 與 In-scope fix(含 LOW)都是 0,沒有輪數上限。 +- 沒有設定時,行為與現在逐字相同(無人值守 2 輪、attended 1 輪、乾淨才合併)。 +- run-state 記錄每一輪 verify 的計數(輪次、`blocking`、`in_scope`、`low_in_scope`、審過的 commit),由 `close-stage.py gate` 在每一輪寫入。這同時做到 #591 要的程式把關:要不要再跑一輪由 `close-stage.py next` 依模式與這份紀錄回答,不靠 model 記得上限。 +- 合併條件依模式:`early` 與 `exhaustive-blocking` 停在 Blocking 為 0 時,合併最後一輪審過的 commit,沒修的列合成一張 follow-up issue;`exhaustive-all` 只在兩種列都歸零時合併。**BREAKING**(只對設了模式的 run):verify 不乾淨的 commit 也可能自動合併。 +- 設了模式的 attended run 也自動修、自動再驗;只有安全漏洞這類不自動修的 finding 才停下交回。沒設模式的 attended run 不變。 +- 設了模式的 run,run-state 的 24 小時期限從最後一輪 verify 算起,而不是從 run 開始(#576 的一部分)。 +- Phase 6 的回報寫明停止的原因:模式、輪數、每一輪要修的列數。 + +## Non-Goals (optional) + +## Capabilities + +### New Capabilities + +(無) + +### Modified Capabilities + +- `idd-pr-hitl-modes`:新增「停止模式決定修正迴圈何時停、停下後是否合併」;修改「Clean verify leads to merge and close」(依模式的合併條件、run-state 期限從最後一輪算起)與「Unattended fix loop covers in-scope findings with a two-round limit」(兩輪上限與 attended 不自動修只在沒有設定模式時成立)。 + +## Impact + +- Affected specs: `idd-pr-hitl-modes` +- Affected code: + - Modified: plugins/issue-driven-dev/scripts/close-stage.py, plugins/issue-driven-dev/skills/idd-all/SKILL.md, plugins/issue-driven-dev/references/config-protocol.md, plugins/issue-driven-dev/scripts/tests/close-stage/scenarios.sh + - New: test fixtures under plugins/issue-driven-dev/scripts/tests/close-stage/fixtures/ for the round record, `close-stage.py next` and the merge conditions + - Removed: none +- 相關 issue:#595(本 change)、#591(輪數由程式把關,本 change 一併做到)、#576(期限只改設了模式的 run)、#596(不重報已定的點,讓收斂數更可信;不在本 change)。 diff --git a/openspec/changes/archive/2026-11-21-verify-stop-modes/specs/idd-pr-hitl-modes/spec.md b/openspec/changes/archive/2026-11-21-verify-stop-modes/specs/idd-pr-hitl-modes/spec.md new file mode 100644 index 00000000..792f3864 --- /dev/null +++ b/openspec/changes/archive/2026-11-21-verify-stop-modes/specs/idd-pr-hitl-modes/spec.md @@ -0,0 +1,159 @@ +## ADDED Requirements + +### Requirement: A configured stop mode decides when the fix loop stops and whether the run merges + +A run has a stop mode when the `--stop ` flag of `idd-all`, or else the `verify_stop.mode` field of the resolved IDD config, names one of `early`, `exhaustive-blocking` or `exhaustive-all`. The flag takes precedence over the config. A flag with any other value SHALL stop `idd-all` before Phase 1 with a message naming the three values. A config value outside the three SHALL be treated as no stop mode, and `idd-all` SHALL print one line saying so. The resolved mode, or its absence, SHALL be written into the run-state record when the mode is resolved and SHALL be read from there afterwards. + +Each time `close-stage.py gate` reads a verify report that has not been read in this run, it SHALL append one round to the round record of the run-state record: the round number, the reviewed commit, and the counts `blocking`, `in_scope` and `low_in_scope`. Reading the same report again SHALL NOT add a round. The to-fix count of a round is `blocking + in_scope - low_in_scope`; for a run that carries `--review` or `--in-chain` it is `blocking`. + +After each round of a run with a stop mode, `idd-all` SHALL ask `close-stage.py next` whether to fix and verify again, and SHALL follow its answer; the model SHALL NOT decide this itself. `next` SHALL answer from the mode and the round record only: + +| Mode | Stops when | Merges on that stop | +|---|---|---| +| `early` | the to-fix count is 0, or, from round 2 on, it is not lower than the previous round's | when `blocking` is 0 | +| `exhaustive-blocking` | `blocking` is 0, or `blocking` was not lower than the previous round's in each of the last two rounds | when `blocking` is 0 | +| `exhaustive-all` | `blocking` is 0 and `in_scope` is 0, LOW findings included | always | + +In every mode `next` SHALL answer stop without merging when the latest gate result is `unparseable` or holds a Rejected finding, and `exhaustive-all` has no round limit. When a finding to be fixed is a security vulnerability, `idd-all` SHALL stop without merging instead of fixing it, as for a run without a stop mode. When the run stops with a merge and findings remain, `idd-all` SHALL NOT change the branch for them: the commit that merges is the commit the last round reviewed, and the remaining findings SHALL be filed together as one follow-up issue. A merge allowed by this table passes the same guardrails as a clean merge, including a complete coverage line and a complete reviewers line, which the verify gate SHALL read for every verdict; a run with `--review` or `--in-chain`, or of type `meeting`, never merges. + +With a stop mode, an attended run SHALL fix findings and verify again as an unattended run does, and SHALL ask the user only where a sub-skill asks in attended interaction; without a stop mode it hands the findings back as before. The run report SHALL state the stop mode, the number of rounds, the to-fix count of each round, and the reason `next` gave for stopping. + +#### Scenario: early stops when the count stops falling and merges with no Blocking + +- **GIVEN** a run with stop mode `early` +- **AND** rounds 1, 2 and 3 have to-fix counts 6, 4 and 4, and round 3 has 0 Blocking +- **WHEN** `close-stage.py next` runs after round 3 +- **THEN** it answers stop with merge, giving the reason that the to-fix count did not fall (4 → 4) +- **AND** `idd-all` merges the commit round 3 reviewed and files one follow-up issue listing the 4 findings + +#### Scenario: early stops with Blocking and does not merge + +- **GIVEN** a run with stop mode `early` +- **AND** rounds 1 and 2 have to-fix counts 3 and 3, and round 2 has 1 Blocking +- **WHEN** `close-stage.py next` runs after round 2 +- **THEN** it answers stop without merge, and the run stops at verified + +#### Scenario: exhaustive-blocking reaches zero Blocking + +- **GIVEN** a run with stop mode `exhaustive-blocking` +- **AND** rounds 1, 2 and 3 have `blocking` 2, 1 and 0, and round 3 has 3 In-scope fix findings +- **WHEN** `close-stage.py next` runs after round 3 +- **THEN** it answers stop with merge, and the 3 findings are filed as one follow-up issue + +#### Scenario: exhaustive-blocking stops when Blocking does not fall twice + +- **GIVEN** a run with stop mode `exhaustive-blocking` +- **AND** rounds 1, 2 and 3 have `blocking` 2, 2 and 2 +- **WHEN** `close-stage.py next` runs after round 3 +- **THEN** it answers stop without merge; after round 2 it had answered fix + +#### Scenario: exhaustive-all keeps going until nothing is left + +- **GIVEN** a run with stop mode `exhaustive-all` +- **AND** round 6 has 0 Blocking and 1 In-scope fix finding that is LOW +- **WHEN** `close-stage.py next` runs after round 6 +- **THEN** it answers fix +- **AND** when round 7 has 0 Blocking and 0 In-scope fix, it answers stop with merge + +#### Scenario: A stop-mode merge needs a complete coverage line + +- **GIVEN** a run with stop mode `early` whose rounds 1 and 2 each report 0 Blocking and 2 MEDIUM In-scope fix findings +- **AND** round 2's report says `3 / 5 requirements addressed` +- **WHEN** the close stage runs +- **THEN** it stops without merging, and the reason names the coverage line + +#### Scenario: The same report read twice is one round + +- **GIVEN** a run whose round record holds 2 rounds +- **WHEN** `close-stage.py gate` reads round 2's report again +- **THEN** the round record still holds 2 rounds + +#### Scenario: Flag over config, and values outside the three + +- **GIVEN** the config sets `verify_stop.mode` to `early` +- **WHEN** `idd-all` runs with `--stop exhaustive-all`, with `--stop fast`, and, in another repository whose config sets the mode to `fast`, with no flag +- **THEN** the first run has stop mode `exhaustive-all`; the second stops before Phase 1 and names `early`, `exhaustive-blocking` and `exhaustive-all`; the third prints one line and runs without a stop mode + +#### Scenario: An attended run with a stop mode fixes on its own + +- **GIVEN** resolved interaction is `attended` and stop mode `early` +- **AND** verify round 1 reports 1 Blocking finding that is not a security vulnerability +- **WHEN** Phase 4 evaluates the result +- **THEN** `idd-all` fixes the finding, runs verify round 2, and asks `close-stage.py next` again + +## MODIFIED Requirements + +### Requirement: Clean verify leads to merge and close + +After verify, `idd-all` SHALL ask the verify gate whether the latest verify round is clean. When the gate reports `clean` (for a run with a stop mode: when requirement "A configured stop mode decides when the fix loop stops and whether the run merges" allows the merge), the path is `PR`, and every merge guardrail passes, `idd-all` SHALL squash-merge the PR, fetch the remote default branch, and invoke `/idd-close #` with the orchestrated directive, without asking the user first. When the path is `direct-commit`, the push-then-close behaviour of the requirement "Direct-commit path stays on current branch and skips PR" applies. `idd-all` SHALL NOT merge or close when the run carries `--review`, when it runs with `--in-chain`, or when the issue type is `meeting`. Every check that guards the merge or the push SHALL run in the same process as the merge or the push, and the run's flags SHALL be read from a run-state record written when the mode is resolved, not from shell state or the model's memory. Every value in that record SHALL be given explicitly when it is written (a lost value is an error, never a default that allows merging); a missing or foreign record, or one more than 24 hours old, SHALL stop the close stage. The age is measured from the record's creation; for a run with a stop mode it is measured from the last verify round the record holds, so that a long run is not stopped by its own length. The close stage SHALL also stop when the run was downgraded from the PR path (a missing ralph-loop), when the issue's author or the last editor of its body lacks write access to the repository, when the fetch or push URL of the clone's `origin` is not `github.com/`, and when a workflow publishes on a push to the default branch. Publishing detection is a named limit (maintainer decision after verify round 7): it reads the workflow files for a list of known publishing steps and treats a trigger it cannot read as publishing, so a release path that is not on the list (a `make` target, `rsync`, a remote action, a script at the repository root) is not detected and the merge publishes. A repository whose merges publish in such a way SHALL be run with `--review`. + +#### Scenario: Clean verify on the PR path + +- **GIVEN** resolved path is `PR` +- **AND** the verify gate reports `clean` and all merge guardrails pass +- **WHEN** the close stage runs +- **THEN** `idd-all` runs `gh pr merge

--squash` with a subject and body it composed, runs `git fetch`, invokes `/idd-close #` with the orchestrated directive, and the run report starts with `Done:` + +#### Scenario: Only follow-up findings remain + +- **GIVEN** the latest verify round says PASS and has 0 Blocking, 0 In-scope fix, and 2 Follow-up findings +- **WHEN** the verify gate runs +- **THEN** it reports `clean`, the two follow-up issues are filed as before, and the run proceeds to merge and close + +#### Scenario: Review flag keeps the run at verified + +- **GIVEN** the run carries `--review` +- **AND** the verify gate reports `clean` +- **WHEN** Phase 6 runs +- **THEN** `idd-all` neither merges nor closes, and the report uses the "awaiting human acceptance" wording + +#### Scenario: Chain context never merges or closes + +- **GIVEN** the run carries `--in-chain` +- **WHEN** verify completes clean +- **THEN** `idd-all` neither merges nor closes, leaving the cluster PR to `/idd-all-chain` + +#### Scenario: A stop-mode run is not stopped by its own length + +- **GIVEN** a run with stop mode `exhaustive-all` whose run-state record was created 30 hours ago +- **AND** the record's last verify round was written 2 hours ago and the gate reports `clean` +- **WHEN** the close stage reads the record +- **THEN** the record's age is 2 hours and the close stage does not stop for age + +### Requirement: Unattended fix loop covers in-scope findings with a two-round limit + +This requirement applies to a run without a stop mode; a run with one follows requirement "A configured stop mode decides when the fix loop stops and whether the run merges". When the resolved interaction is `unattended` and the verify gate reports `not_clean`, `idd-all` SHALL fix every Blocking finding, and every In-scope fix finding unless the run carries `--review` or `--in-chain` (those runs never merge and keep the Blocking-only scope), in the same branch and run verify again, for at most 2 verify rounds in total (one fix pass between them). The number of rounds already run SHALL be read from the run-state record, not from the model's memory; every new commit the verify gate judged, and every new report on the same commit, counts as one round, also when its report was missing or could not be read or the fix pass made no commit. The close stage SHALL stop, without merging, an unattended run without a stop mode whose record holds more than 2 rounds, or whose newest verify report is not in the record. If the gate still reports `not_clean` after the second verify round, `idd-all` SHALL stop at verified without merging or closing. When the resolved interaction is `attended`, `idd-all` SHALL NOT fix findings automatically; it SHALL hand the findings back to the user, and merge and close only follow a later round that the gate reports `clean`. When the gate reports `clean` with `low_in_scope` above zero, `idd-all` SHALL NOT change the branch for those findings (the commit that merges is the commit the round reviewed); it SHALL file them together as one follow-up issue before the close stage. + +#### Scenario: Second round comes back clean + +- **GIVEN** resolved interaction is `unattended` +- **AND** verify round 1 reports 0 Blocking and 2 In-scope fix findings +- **WHEN** `idd-all` fixes both findings and runs verify round 2, which reports 0 Blocking and 0 In-scope fix +- **THEN** the gate reports `clean` and the run proceeds to merge and close + +#### Scenario: Second round still has an in-scope finding + +- **GIVEN** resolved interaction is `unattended` +- **AND** verify round 2 reports 0 Blocking and 1 In-scope fix finding +- **WHEN** the fix loop checks its round count +- **THEN** `idd-all` stops at verified, does not merge, and the run report lists the remaining finding under `Stopped:` + +#### Scenario: A clean round with LOW in-scope findings + +- **GIVEN** verify round 1 says PASS with 0 Blocking and 2 In-scope fix findings, both LOW +- **WHEN** Phase 4 reads the gate +- **THEN** the gate reports `clean` with `low_in_scope` 2, `idd-all` makes no fix commit, files one follow-up issue listing both findings, and proceeds to the close stage with the reviewed commit + +#### Scenario: Attended run with findings + +- **GIVEN** resolved interaction is `attended` +- **AND** verify reports 1 Blocking finding +- **WHEN** Phase 4 evaluates the result +- **THEN** `idd-all` reports the finding to the user and makes no automatic fix commit + +#### Scenario: A third round is caught by the close stage + +- **GIVEN** an unattended run without a stop mode whose round record holds 3 verify rounds +- **AND** the third round's gate result is `clean` +- **WHEN** the close stage runs +- **THEN** it stops without merging, and the reason names the two-round limit diff --git a/openspec/changes/archive/2026-11-21-verify-stop-modes/tasks.md b/openspec/changes/archive/2026-11-21-verify-stop-modes/tasks.md new file mode 100644 index 00000000..cd8adc85 --- /dev/null +++ b/openspec/changes/archive/2026-11-21-verify-stop-modes/tasks.md @@ -0,0 +1,36 @@ +## 1. 測試先寫(照 spec 的 Scenario,在改程式之前會失敗) + +- [x] 1.1 在 `plugins/issue-driven-dev/scripts/tests/close-stage/scenarios.sh` 為 requirement「A configured stop mode decides when the fix loop stops and whether the run merges」的八個 Scenario 各加一個情境:用 fixtures 準備 run-state(含 `verify_stop` 與 `rounds`)與 gate 結果,檢查 `close-stage.py next` 印出的 `decision`、`merge`、`reason`,以及 `gate` 重讀同一份報告時 `rounds` 的筆數不變。驗證:`plugins/issue-driven-dev/scripts/tests/close-stage/test.sh` 跑這些情境,改程式前全部失敗。 +- [x] 1.2 為 requirement「Clean verify leads to merge and close」新增的 Scenario(設了模式的 run 期限從最後一輪算)與 requirement「Unattended fix loop covers in-scope findings with a two-round limit」新增的 Scenario(沒有模式、`rounds` 有 3 筆時 `run` 停下並寫明兩輪上限)各加一個情境。驗證:同一支 test.sh,改程式前這兩個情境失敗,既有情境照舊通過。 + +## 2. run-state 的模式與每輪紀錄 + +- [x] 2.1 [after: 1.1] `close-stage.py init` 接受必填的 `--stop `,把模式寫進 run-state 的 `verify_stop`(`none` 寫成 `null`),缺少或其他值以結束碼 64(usage,與 init 其他引數相同)拒絕。驗證:test.sh 的 init 情境(缺 `--stop`、值錯、四個合法值)。 +- [x] 2.2 [after: 2.1] 每輪的計數由 gate 寫進 run-state:`close-stage.py gate` 讀到這次 run 還沒讀過的報告(以 comment id 判斷)時,在 `rounds` 加一筆 `round`、`sha`、`blocking`、`in_scope`、`low_in_scope`、`report_id`、`at`;`unparseable` 也記一筆、計數為 `null`;重讀同一份報告不加。gate 印出的 JSON 另帶 `round`。驗證:1.1 的「The same report read twice is one round」情境通過。 + +## 3. 由 close-stage.py next 判斷要不要再跑一輪 + +- [x] 3.1 [after: 2.2] 新增 `close-stage.py next`,依 design「要不要再跑一輪由 close-stage.py next 判斷」印出 `decision`、`merge`、`reason`、`mode`、`rounds`。實作三種模式的判定表:收斂數數的是要修的列(`blocking + in_scope - low_in_scope`,`--review`/`--in-chain` 只數 `blocking`)、early stop 以嚴格下降判斷收斂、exhaustive-blocking 用連續兩輪不下降當保底、exhaustive-all 沒有輪數上限;沒有模式時無人值守 2 輪、attended 1 輪後回 stop。讀不到 run-state 或 `rounds` 空的回 stop、`merge: false`、非 0 結束碼。驗證:1.1 的模式情境全部通過。 +- [x] 3.2 [after: 3.1] `close-stage.py run` 的合併條件:停下時合併的是最後一輪審過的 commit——有模式的 run 在 `next` 對最後一輪回 `merge: true` 時放行(HEAD 必須等於最後一筆 `rounds` 的 `sha`),沒有模式的 run 仍要求 `clean`,且無人值守 run 的 `rounds` 超過 2 筆時停下並寫明兩輪上限;`--review`、`--in-chain`、meeting 照舊不合併,其餘 guardrail 不變。驗證:1.1 的合併情境與 1.2 的兩輪上限情境通過,既有 merge 測試(`scripts/tests/merge-and-close-contract/`)照舊通過。 +- [x] 3.3 [after: 2.2] 設了模式的 run,期限從最後一輪算:`load_state()` 對 `verify_stop` 不是 `null` 的紀錄,以 `rounds` 最後一筆的 `at` 計算年齡(沒有 `rounds` 用建立時間);沒有模式的紀錄不變。驗證:1.2 的期限情境通過;沒有模式、建立超過 24 小時的既有情境照舊被擋。 + +## 4. idd-all 照 next 走 + +- [x] 4.1 [after: 2.1] idd-all SKILL.md Step 0.2 解析 `--stop`,值不在三個之內時在 Phase 1 之前停下並列出三個值;Step 0.7 照 config 值寫錯時當成沒有模式的規則解析 `verify_stop.mode`(印一行),把結果以 `--stop` 交給 `close-stage.py init`,並在模式通知那一行印出停止模式。驗證:內容審查 SKILL.md 的 Step 0.2 與 0.7,並以 1.1 的「Flag over config」情境的 init 部分對照。 +- [x] 4.2 [after: 3.1, 4.1] idd-all SKILL.md Phase 4 改成一條由 `close-stage.py next` 驅動的迴圈:每輪 verify → gate → next,照 `decision` 修或停;設了模式的 attended run 也自動修(安全漏洞仍停下交回);`MAX_ROUND` 這個名字從 SKILL.md 移除。驗證:`grep -c MAX_ROUND plugins/issue-driven-dev/skills/idd-all/SKILL.md` 為 0;內容審查 Phase 4 的 pseudocode 對照 spec 的判定表。 +- [x] 4.3 [after: 3.2, 4.2] idd-all SKILL.md Phase 5c 的兩張表與 Phase 6 的 Run report:寫明有模式時的合併條件、剩下的列合成一張 follow-up issue、回報列出模式、輪數、每輪的 to-fix count 與 `next` 的 `reason`。驗證:內容審查 Phase 5c 與 Phase 6,對照 requirement「A configured stop mode decides when the fix loop stops and whether the run merges」的最後一段。 + +## 5. 文件與回歸 + +- [x] 5.1 `plugins/issue-driven-dev/references/config-protocol.md` 新增 `verify_stop` 欄位一節:三個值、沒有設定時的行為、寫錯時當成沒有模式、`--stop` 優先於 config、各模式的合併條件與風險(不乾淨的 commit 可能自動合併)。驗證:內容審查,與 design 的「config 值寫錯時當成沒有模式」一致。 +- [x] 5.2 [after: 3.2, 3.3, 4.3, 5.1] 全部 close-stage 與 idd-all 相關測試通過,沒有設定模式時輸出與改動前相同。驗證:`plugins/issue-driven-dev/scripts/tests/close-stage/test.sh` 與 `plugins/issue-driven-dev/scripts/tests/merge-and-close-contract/` 的測試全部通過。 + +## 6. spectra-verify 與 spectra-review 之後的修正 + +- [x] 6.1 停止模式的合併也要求覆蓋率行與 reviewers 行完整:`verify-gate.py` 對每種判定輸出 `coverage_complete`、`reviewers_complete`,`close-stage.py` 的 `merge_gate` 在停止模式下要求兩者為 `true`。驗證:close-stage 的 `stop-run-cover`、`stop-run-noreviewers` 情境停下;拿掉這道檢查時 8 個斷言失敗。 +- [x] 6.2 沒有模式的 run 以 `attempts`(每個被判過的 commit 一筆)計輪數;`decide` 的沒有模式分支每個回答都帶 `round` 與 `limit`,Rejected 與 clean 留給 gate;`merge_gate` 擋下 Phase 4 沒判過的報告。驗證:close-stage 的沒有模式情境(缺報告的第 2 輪、第 1 輪有 Rejected、第 3 輪 clean、`stop-nomode-unseen`);改回只數報告時 3 個斷言失敗。 +- [x] 6.3 run-state 只有一種讀法(`read_state`,檢查形狀)與一種寫法(`write_state`,`mkstemp` 建暫存檔);gate 寫紀錄失敗時回 `unparseable`;`next` 出錯時的回答帶 `mode` 與 `rounds`;unparseable 那一輪不保留計數;`next` 的每一輪帶 `to_fix`。驗證:close-stage 的 `stop-gate-broken` 與 to-fix 列表情境。 +- [x] 6.4 idd-all SKILL.md:`--stop` 沒有值時中止;`verify_stop` 不是 object 時印一行;PR 正文在停止模式要合併時照實寫;停下並合併前檢查剩下的列有沒有安全漏洞;三處舊文字更新。驗證:Step 0.2 的停止模式解析在 bash 下實際跑過(zsh 下最後一個參數讀不到是既有的問題,另開 #598);內容審查 Phase 4、Phase 5、Failure Modes。 +- [x] 6.6 同一個 commit 上的新報告也算一輪:`record_round` 的 `attempts` 在 commit 換了、或讀到新報告時加一筆;Phase 5c guardrail 表第 1 列照程式改寫(數 `attempts`、覆蓋率與 reviewers 行)。驗證:close-stage 的「a new report on the same commit is a new attempt」斷言。 +- [x] 6.5 測試:`verify_comment` 可設 severity、覆蓋率行與 reviewers 行;補上 spec「The same report read twice is one round」的兩輪版本、停止模式的 Rejected、`run` 實際合併 MEDIUM 列的兩條路徑。驗證:close-stage 套件 624 項全過。 + diff --git a/openspec/specs/idd-pr-hitl-modes/spec.md b/openspec/specs/idd-pr-hitl-modes/spec.md index ca2e68d4..269315e4 100644 --- a/openspec/specs/idd-pr-hitl-modes/spec.md +++ b/openspec/specs/idd-pr-hitl-modes/spec.md @@ -342,7 +342,7 @@ In PR mode, `idd-all` SHALL run the existing-work check for each issue before Ph --- ### Requirement: Clean verify leads to merge and close -After verify, `idd-all` SHALL ask the verify gate whether the latest verify round is clean. When the gate reports `clean`, the path is `PR`, and every merge guardrail passes, `idd-all` SHALL squash-merge the PR, fetch the remote default branch, and invoke `/idd-close #` with the orchestrated directive, without asking the user first. When the path is `direct-commit`, the push-then-close behaviour of the requirement "Direct-commit path stays on current branch and skips PR" applies. `idd-all` SHALL NOT merge or close when the run carries `--review`, when it runs with `--in-chain`, or when the issue type is `meeting`. Every check that guards the merge or the push SHALL run in the same process as the merge or the push, and the run's flags SHALL be read from a run-state record written when the mode is resolved, not from shell state or the model's memory. Every value in that record SHALL be given explicitly when it is written (a lost value is an error, never a default that allows merging); a missing, foreign or more than 24-hour-old record SHALL stop the close stage. The close stage SHALL also stop when the run was downgraded from the PR path (a missing ralph-loop), when the issue's author or the last editor of its body lacks write access to the repository, when the fetch or push URL of the clone's `origin` is not `github.com/`, and when a workflow publishes on a push to the default branch. Publishing detection is a named limit (maintainer decision after verify round 7): it reads the workflow files for a list of known publishing steps and treats a trigger it cannot read as publishing, so a release path that is not on the list (a `make` target, `rsync`, a remote action, a script at the repository root) is not detected and the merge publishes. A repository whose merges publish in such a way SHALL be run with `--review`. +After verify, `idd-all` SHALL ask the verify gate whether the latest verify round is clean. When the gate reports `clean` (for a run with a stop mode: when requirement "A configured stop mode decides when the fix loop stops and whether the run merges" allows the merge), the path is `PR`, and every merge guardrail passes, `idd-all` SHALL squash-merge the PR, fetch the remote default branch, and invoke `/idd-close #` with the orchestrated directive, without asking the user first. When the path is `direct-commit`, the push-then-close behaviour of the requirement "Direct-commit path stays on current branch and skips PR" applies. `idd-all` SHALL NOT merge or close when the run carries `--review`, when it runs with `--in-chain`, or when the issue type is `meeting`. Every check that guards the merge or the push SHALL run in the same process as the merge or the push, and the run's flags SHALL be read from a run-state record written when the mode is resolved, not from shell state or the model's memory. Every value in that record SHALL be given explicitly when it is written (a lost value is an error, never a default that allows merging); a missing or foreign record, or one more than 24 hours old, SHALL stop the close stage. The age is measured from the record's creation; for a run with a stop mode it is measured from the last verify round the record holds, so that a long run is not stopped by its own length. The close stage SHALL also stop when the run was downgraded from the PR path (a missing ralph-loop), when the issue's author or the last editor of its body lacks write access to the repository, when the fetch or push URL of the clone's `origin` is not `github.com/`, and when a workflow publishes on a push to the default branch. Publishing detection is a named limit (maintainer decision after verify round 7): it reads the workflow files for a list of known publishing steps and treats a trigger it cannot read as publishing, so a release path that is not on the list (a `make` target, `rsync`, a remote action, a script at the repository root) is not detected and the merge publishes. A repository whose merges publish in such a way SHALL be run with `--review`. #### Scenario: Clean verify on the PR path @@ -370,6 +370,27 @@ After verify, `idd-all` SHALL ask the verify gate whether the latest verify roun - **WHEN** verify completes clean - **THEN** `idd-all` neither merges nor closes, leaving the cluster PR to `/idd-all-chain` +#### Scenario: A stop-mode run is not stopped by its own length + +- **GIVEN** a run with stop mode `exhaustive-all` whose run-state record was created 30 hours ago +- **AND** the record's last verify round was written 2 hours ago and the gate reports `clean` +- **WHEN** the close stage reads the record +- **THEN** the record's age is 2 hours and the close stage does not stop for age + + + + --- ### Requirement: The close stage merges only runs whose intent was confirmed @@ -503,7 +524,7 @@ The close stage SHALL stop at verified when any of these holds (a closed list). --- ### Requirement: Unattended fix loop covers in-scope findings with a two-round limit -When the resolved interaction is `unattended` and the verify gate reports `not_clean`, `idd-all` SHALL fix every Blocking finding, and every In-scope fix finding unless the run carries `--review` or `--in-chain` (those runs never merge and keep the Blocking-only scope), in the same branch and run verify again, for at most 2 verify rounds in total (one fix pass between them). If the gate still reports `not_clean` after the second verify round, `idd-all` SHALL stop at verified without merging or closing. When the resolved interaction is `attended`, `idd-all` SHALL NOT fix findings automatically; it SHALL hand the findings back to the user, and merge and close only follow a later round that the gate reports `clean`. When the gate reports `clean` with `low_in_scope` above zero, `idd-all` SHALL NOT change the branch for those findings (the commit that merges is the commit the round reviewed); it SHALL file them together as one follow-up issue before the close stage. +This requirement applies to a run without a stop mode; a run with one follows requirement "A configured stop mode decides when the fix loop stops and whether the run merges". When the resolved interaction is `unattended` and the verify gate reports `not_clean`, `idd-all` SHALL fix every Blocking finding, and every In-scope fix finding unless the run carries `--review` or `--in-chain` (those runs never merge and keep the Blocking-only scope), in the same branch and run verify again, for at most 2 verify rounds in total (one fix pass between them). The number of rounds already run SHALL be read from the run-state record, not from the model's memory; every new commit the verify gate judged, and every new report on the same commit, counts as one round, also when its report was missing or could not be read or the fix pass made no commit. The close stage SHALL stop, without merging, an unattended run without a stop mode whose record holds more than 2 rounds, or whose newest verify report is not in the record. If the gate still reports `not_clean` after the second verify round, `idd-all` SHALL stop at verified without merging or closing. When the resolved interaction is `attended`, `idd-all` SHALL NOT fix findings automatically; it SHALL hand the findings back to the user, and merge and close only follow a later round that the gate reports `clean`. When the gate reports `clean` with `low_in_scope` above zero, `idd-all` SHALL NOT change the branch for those findings (the commit that merges is the commit the round reviewed); it SHALL file them together as one follow-up issue before the close stage. #### Scenario: Second round comes back clean @@ -532,6 +553,27 @@ When the resolved interaction is `unattended` and the verify gate reports `not_c - **WHEN** Phase 4 evaluates the result - **THEN** `idd-all` reports the finding to the user and makes no automatic fix commit +#### Scenario: A third round is caught by the close stage + +- **GIVEN** an unattended run without a stop mode whose round record holds 3 verify rounds +- **AND** the third round's gate result is `clean` +- **WHEN** the close stage runs +- **THEN** it stops without merging, and the reason names the two-round limit + + + + --- ### Requirement: Merge guardrails gate every automatic merge @@ -783,3 +825,98 @@ When `idd-all` merges, pushes, or closes, its Phase 6 report SHALL start with `D | delete a branch, or push with `--force` | asks first | the overwritten commits are gone | | publish: `gh release`, a marketplace sync, a tag other than the baseline tag | asks first | it has reached users | | merge and close in a run that carries `--review` | a person does it | the flag means a person looks first | + +--- +### Requirement: A configured stop mode decides when the fix loop stops and whether the run merges + +A run has a stop mode when the `--stop ` flag of `idd-all`, or else the `verify_stop.mode` field of the resolved IDD config, names one of `early`, `exhaustive-blocking` or `exhaustive-all`. The flag takes precedence over the config. A flag with any other value SHALL stop `idd-all` before Phase 1 with a message naming the three values. A config value outside the three SHALL be treated as no stop mode, and `idd-all` SHALL print one line saying so. The resolved mode, or its absence, SHALL be written into the run-state record when the mode is resolved and SHALL be read from there afterwards. + +Each time `close-stage.py gate` reads a verify report that has not been read in this run, it SHALL append one round to the round record of the run-state record: the round number, the reviewed commit, and the counts `blocking`, `in_scope` and `low_in_scope`. Reading the same report again SHALL NOT add a round. The to-fix count of a round is `blocking + in_scope - low_in_scope`; for a run that carries `--review` or `--in-chain` it is `blocking`. + +After each round of a run with a stop mode, `idd-all` SHALL ask `close-stage.py next` whether to fix and verify again, and SHALL follow its answer; the model SHALL NOT decide this itself. `next` SHALL answer from the mode and the round record only: + +| Mode | Stops when | Merges on that stop | +|---|---|---| +| `early` | the to-fix count is 0, or, from round 2 on, it is not lower than the previous round's | when `blocking` is 0 | +| `exhaustive-blocking` | `blocking` is 0, or `blocking` was not lower than the previous round's in each of the last two rounds | when `blocking` is 0 | +| `exhaustive-all` | `blocking` is 0 and `in_scope` is 0, LOW findings included | always | + +In every mode `next` SHALL answer stop without merging when the latest gate result is `unparseable` or holds a Rejected finding, and `exhaustive-all` has no round limit. When a finding to be fixed is a security vulnerability, `idd-all` SHALL stop without merging instead of fixing it, as for a run without a stop mode. When the run stops with a merge and findings remain, `idd-all` SHALL NOT change the branch for them: the commit that merges is the commit the last round reviewed, and the remaining findings SHALL be filed together as one follow-up issue. A merge allowed by this table passes the same guardrails as a clean merge, including a complete coverage line and a complete reviewers line, which the verify gate SHALL read for every verdict; a run with `--review` or `--in-chain`, or of type `meeting`, never merges. + +With a stop mode, an attended run SHALL fix findings and verify again as an unattended run does, and SHALL ask the user only where a sub-skill asks in attended interaction; without a stop mode it hands the findings back as before. The run report SHALL state the stop mode, the number of rounds, the to-fix count of each round, and the reason `next` gave for stopping. + +#### Scenario: early stops when the count stops falling and merges with no Blocking + +- **GIVEN** a run with stop mode `early` +- **AND** rounds 1, 2 and 3 have to-fix counts 6, 4 and 4, and round 3 has 0 Blocking +- **WHEN** `close-stage.py next` runs after round 3 +- **THEN** it answers stop with merge, giving the reason that the to-fix count did not fall (4 → 4) +- **AND** `idd-all` merges the commit round 3 reviewed and files one follow-up issue listing the 4 findings + +#### Scenario: early stops with Blocking and does not merge + +- **GIVEN** a run with stop mode `early` +- **AND** rounds 1 and 2 have to-fix counts 3 and 3, and round 2 has 1 Blocking +- **WHEN** `close-stage.py next` runs after round 2 +- **THEN** it answers stop without merge, and the run stops at verified + +#### Scenario: exhaustive-blocking reaches zero Blocking + +- **GIVEN** a run with stop mode `exhaustive-blocking` +- **AND** rounds 1, 2 and 3 have `blocking` 2, 1 and 0, and round 3 has 3 In-scope fix findings +- **WHEN** `close-stage.py next` runs after round 3 +- **THEN** it answers stop with merge, and the 3 findings are filed as one follow-up issue + +#### Scenario: exhaustive-blocking stops when Blocking does not fall twice + +- **GIVEN** a run with stop mode `exhaustive-blocking` +- **AND** rounds 1, 2 and 3 have `blocking` 2, 2 and 2 +- **WHEN** `close-stage.py next` runs after round 3 +- **THEN** it answers stop without merge; after round 2 it had answered fix + +#### Scenario: exhaustive-all keeps going until nothing is left + +- **GIVEN** a run with stop mode `exhaustive-all` +- **AND** round 6 has 0 Blocking and 1 In-scope fix finding that is LOW +- **WHEN** `close-stage.py next` runs after round 6 +- **THEN** it answers fix +- **AND** when round 7 has 0 Blocking and 0 In-scope fix, it answers stop with merge + +#### Scenario: A stop-mode merge needs a complete coverage line + +- **GIVEN** a run with stop mode `early` whose rounds 1 and 2 each report 0 Blocking and 2 MEDIUM In-scope fix findings +- **AND** round 2's report says `3 / 5 requirements addressed` +- **WHEN** the close stage runs +- **THEN** it stops without merging, and the reason names the coverage line + +#### Scenario: The same report read twice is one round + +- **GIVEN** a run whose round record holds 2 rounds +- **WHEN** `close-stage.py gate` reads round 2's report again +- **THEN** the round record still holds 2 rounds + +#### Scenario: Flag over config, and values outside the three + +- **GIVEN** the config sets `verify_stop.mode` to `early` +- **WHEN** `idd-all` runs with `--stop exhaustive-all`, with `--stop fast`, and, in another repository whose config sets the mode to `fast`, with no flag +- **THEN** the first run has stop mode `exhaustive-all`; the second stops before Phase 1 and names `early`, `exhaustive-blocking` and `exhaustive-all`; the third prints one line and runs without a stop mode + +#### Scenario: An attended run with a stop mode fixes on its own + +- **GIVEN** resolved interaction is `attended` and stop mode `early` +- **AND** verify round 1 reports 1 Blocking finding that is not a security vulnerability +- **WHEN** Phase 4 evaluates the result +- **THEN** `idd-all` fixes the finding, runs verify round 2, and asks `close-stage.py next` again + + \ No newline at end of file diff --git a/plugins/issue-driven-dev/references/config-protocol.md b/plugins/issue-driven-dev/references/config-protocol.md index 427ddeaf..12ef82f7 100644 --- a/plugins/issue-driven-dev/references/config-protocol.md +++ b/plugins/issue-driven-dev/references/config-protocol.md @@ -571,6 +571,32 @@ An OPTIONAL string that shifts **where a complexity hard-gate hit escalates to** **Trade-off note(流程重量).** `sdd_bias: high` 買到的是「每個 gate-worthy 改動都有 spec 紀錄」,付出的是**流程重量** — 每次硬閘命中都走 proposal / design / spec / tasks 全套 artifacts,而不是單一 plan-mode approval。預設不翻轉:「over-trigger 成本高於 under-plan 殘餘風險」是 #129 的既有使用者裁決,本欄位是 opt-in 的團隊姿態(spec-first posture),不是新 baseline。 +### `verify_stop` field + +An OPTIONAL object choosing **when `/idd-all`'s verify-and-fix loop stops, and whether that stop merges** (#595; the decision table is `scripts/lib/stopmode.py`, the contract is the requirement "A configured stop mode decides when the fix loop stops and whether the run merges" of `openspec/specs/idd-pr-hitl-modes`): + +```json +{ + "verify_stop": { "mode": "early" } +} +``` + +| `mode` | Stops when | Merges on that stop | +|--------|-----------|---------------------| +| absent | unattended after 2 verify rounds, attended after 1 — the behavior before #595, unchanged | only a clean round | +| `"early"` | the to-fix count is 0, or, from round 2 on, it is not lower than the previous round's | when Blocking is 0 | +| `"exhaustive-blocking"` | Blocking is 0, or Blocking was not lower than the round before in each of the last two rounds | when Blocking is 0 | +| `"exhaustive-all"` | Blocking and In-scope fix (LOW included) are both 0 — **no round limit** | yes | +| anything else | treated as absent; `/idd-all` prints one line saying the value was ignored | — | + +The to-fix count is Blocking plus the In-scope fix findings above LOW/INFO/P3. A run with `--review` or `--in-chain` counts Blocking only and never merges. + +**Override.** `/idd-all --stop ` replaces the config value for that run. A `--stop` value outside the three stops `/idd-all` before Phase 1: it is the user's explicit request, mistyped. A bad config value only falls back to the absent behavior, which is the stricter one. + +**What a mode changes.** With a mode, attended runs fix and re-verify on their own as unattended runs do (a security vulnerability is still handed back), and the run-state record's 24-hour age counts from the last verify round instead of the run's start. + +**Trade-off note(自動合併不乾淨的 commit).** 有模式時,`early` 與 `exhaustive-blocking` 在 Blocking 為 0 時合併**最後一輪審過的 commit**,即使 verify 還有 In-scope fix 沒修;剩下的列合成一張 follow-up issue。這是把「只有乾淨才合併」(#392)換成「收斂了、沒有 Blocking 就合併」。`exhaustive-all` 沒有輪數上限,成本與時間沒有界線,靠回報裡每一輪的 to-fix count 看出是否在空轉。預設(不設)不變。 + ### `verify_profiles` field An OPTIONAL object registering **repo-local custom verification profiles** for `idd-verify --profile` (#258; profile semantics + built-in profiles in [`verify-profiles.md`](verify-profiles.md)): diff --git a/plugins/issue-driven-dev/scripts/close-stage.py b/plugins/issue-driven-dev/scripts/close-stage.py index 4fe3bf3d..c84bb344 100755 --- a/plugins/issue-driven-dev/scripts/close-stage.py +++ b/plugins/issue-driven-dev/scripts/close-stage.py @@ -12,7 +12,9 @@ Subcommands init --cwd C --repo O/R --issue N --path PR|direct-commit --requested-path PR|direct-commit --interaction attended|unattended --branch B --default D --review yes|no --in-chain yes|no - Step 0.7: record the run's flags in C/.claude/.idd/state/idd-all-run-N.json. + --stop none|early|exhaustive-blocking|exhaustive-all + Step 0.7: record the run's flags in C/.claude/.idd/state/idd-all-run-N.json, + with the stop mode (#595) and an empty round record. Every value is required: a value lost between tool calls is a usage error (64), never a silent "no" (#392 verify r2 #3). gate --cwd C --repo O/R --issue N --sha SHA [--base SHA] @@ -20,9 +22,16 @@ the run began, as GitHub renders it (body_html), and judge it with verify-gate.py --expect-sha [--expect-base]. The newest one must be a '## Verify: #N' report (a PR-mode report or pointer is not read here). - Prints the gate JSON plus comment_id / verify_url. + Prints the gate JSON plus comment_id / verify_url / round. + A report this run has not read yet is appended to the round record of the + run state (#595); reading the same report again adds nothing. Exit 0 clean, 1 not clean, 2 unparseable (including: no such report, any error), 64 usage. + next --cwd C --repo O/R --issue N + After each verify round (#595): fix and verify again, or stop, and whether + the stop merges — from the run state's stop mode and round record only + (scripts/lib/stopmode.py). Prints one JSON line. Exit 0 decided, 3 could + not decide (no run state, no round): the answer is then stop, no merge. run --cwd C --repo O/R --issue N [--ci-timeout S] [--ci-grace S] Phase 5c: every guardrail, then the squash merge (PR) or the push (direct-commit). The CI guardrail runs the local CI gate @@ -75,6 +84,7 @@ local_ci, now, gh_paginated, parse_iso, run_cmd, session_login, ts, first_line) from intent import (check_intent, check_issue_authors, check_meeting, check_others, # noqa: E402 check_pr_people, issue_meta) +from stopmode import MODES, decide # noqa: E402 scripts/lib/stopmode.py — when the fix loop stops (#595) WRITE_PERMS = {"WRITE", "MAINTAIN", "ADMIN"} STATE_TTL = 24 * 3600 @@ -145,7 +155,7 @@ def common_ok(a): def cmd_init(argv): keys = ["--cwd", "--repo", "--issue", "--path", "--requested-path", "--interaction", "--branch", - "--default", "--review", "--in-chain"] + "--default", "--review", "--in-chain", "--stop"] a = parse(argv, {k: "value" for k in keys}) if a is None or not common_ok(a) or any(k not in a for k in keys): return usage("init needs every one of: " + " ".join(keys) + " (each with a value)") @@ -155,6 +165,8 @@ def cmd_init(argv): return usage("--interaction must be attended or unattended") if a["--review"] not in ("yes", "no") or a["--in-chain"] not in ("yes", "no"): return usage("--review and --in-chain must be yes or no") + if a["--stop"] not in ("none",) + MODES: + return usage("--stop must be none, " + ", ".join(MODES)) cwd = os.path.realpath(a["--cwd"]) try: spath, rpath = state_path(cwd, a["--issue"]), result_path(cwd, a["--issue"]) @@ -166,11 +178,11 @@ def cmd_init(argv): "requested_path": a["--requested-path"], "interaction": a["--interaction"], "branch": a["--branch"], "default": a["--default"], "review": a["--review"] == "yes", "in_chain": a["--in-chain"] == "yes", + "verify_stop": None if a["--stop"] == "none" else a["--stop"], "rounds": [], "attempts": [], "last_gate": None, "created_at": iso(now()), } os.makedirs(os.path.dirname(spath), exist_ok=True) - with open(spath, "w", encoding="utf-8") as fh: - json.dump(state, fh) + write_state(cwd, a["--issue"], state) if os.path.exists(rpath): os.unlink(rpath) print(spath) @@ -227,18 +239,19 @@ def judge_report(repo, n, sha, base, since): "reason": f"the newest verify comment by this account{when} is '{other}', not a '## Verify: #{n}' report"} # A verdict changes only with a new verify round: a report edited after it was posted is not read (r5 #14), # nor one a maintainer hid as outdated or off-topic. + named = {"comment_id": report.get("id"), "verify_url": report.get("html_url")} if ts(report.get("updated_at")) != ts(report.get("created_at")): - return 2, {"status": "unparseable", "reason": "the verify report was edited after it was posted — run verify again"} + return 2, dict(named, status="unparseable", reason="the verify report was edited after it was posted — run verify again") if not report.get("node_id"): - return 2, {"status": "unparseable", "reason": "could not tell whether the verify report is hidden (no node id)"} + return 2, dict(named, status="unparseable", reason="could not tell whether the verify report is hidden (no node id)") q = "query($id:ID!){node(id:$id){... on IssueComment{isMinimized}}}" node = (gh_json(["api", "graphql", "-f", f"query={q}", "-f", f"id={report['node_id']}"], "whether the verify report is hidden").get("data") or {}).get("node") or {} if node.get("isMinimized"): - return 2, {"status": "unparseable", "reason": "the verify report is hidden on GitHub — a person set it aside"} + return 2, dict(named, status="unparseable", reason="the verify report is hidden on GitHub — a person set it aside") html = report.get("body_html") if not html: - return 2, {"status": "unparseable", "reason": "GitHub returned no rendered HTML for the verify report"} + return 2, dict(named, status="unparseable", reason="GitHub returned no rendered HTML for the verify report") with tempfile.NamedTemporaryFile("w", suffix=".html", delete=False, encoding="utf-8") as fh: fh.write(html) tmp = fh.name @@ -252,7 +265,7 @@ def judge_report(repo, n, sha, base, since): try: result = json.loads(out) except ValueError: - return 2, {"status": "unparseable", "reason": f"verify-gate.py gave no JSON (exit {rc})"} + return 2, dict(named, status="unparseable", reason=f"verify-gate.py gave no JSON (exit {rc})") result["comment_id"] = report.get("id") result["verify_url"] = report.get("html_url") result["report_author"] = report.get("login") @@ -260,10 +273,15 @@ def judge_report(repo, n, sha, base, since): def gate_stop(rc, gate): - """The one predicate every merge and push passes (r6 #1): clean, and nothing a person has to settle. - A clean result without these fields stops too.""" + """The one predicate every merge and push of a run without a stop mode passes (r6 #1): clean, and nothing + a person has to settle. A clean result without these fields stops too.""" if rc != 0: raise Stop(f"guardrail 1 (verify gate) — {gate.get('status')}: {gate.get('reason')}") + settled_stop(gate) + + +def settled_stop(gate): + """Nothing in the report that a person has to settle (shared by the clean merge and the stop-mode merge).""" for field in ("rejected", "high_follow_up", "process_gaps"): if field not in gate or gate[field] is None: raise Stop(f"guardrail 1 (verify gate) — the gate did not report {field}") @@ -297,24 +315,151 @@ def cmd_gate(argv): rc, result = 2, {"status": "unparseable", "reason": str(exc)} except Exception as exc: # fail closed: any surprise is unparseable, never "not clean" rc, result = 2, {"status": "unparseable", "reason": f"internal error: {exc.__class__.__name__}: {exc}"} + try: + record_round(a["--cwd"], a["--repo"], a["--issue"], result, a["--sha"]) + except Exception as exc: # fail closed: a round that was not recorded must not read as a judged round + rc, result = 2, {"status": "unparseable", "reason": f"the round record could not be written: " + f"{exc.__class__.__name__}: {exc}", "comment_id": result.get("comment_id")} print(json.dumps(result, ensure_ascii=False)) return rc -# ── run: shared checks ───────────────────────────────────────────────────── +def write_state(cwd, n, st): + """Replace the run state in one step: a crash halfway leaves the old record, never half of a new one. + The temporary file is created exclusively (mkstemp), so a planted symlink is never written through.""" + path = state_path(cwd, n) + fd, tmp = tempfile.mkstemp(prefix=os.path.basename(path) + ".", suffix=".tmp", dir=os.path.dirname(path)) + try: + with os.fdopen(fd, "w", encoding="utf-8") as fh: + json.dump(st, fh, ensure_ascii=False) + os.replace(tmp, path) + except BaseException: + if os.path.exists(tmp): + os.unlink(tmp) + raise -def load_state(cwd, repo, n): + +def read_state(cwd, repo, n): + """The run state as a dict with list-valued `rounds` and `attempts`, or Stop. One reader for gate, next and run.""" try: with open(state_path(cwd, n), encoding="utf-8") as fh: st = json.load(fh) - except (OSError, ValueError): - raise Stop("no run state for this issue (Step 0.7 did not record the run's flags) — not merging") + except OSError: + raise Stop("no run state for this issue") + except ValueError: + raise Stop("the run state is not valid JSON") + if not isinstance(st, dict): + raise Stop("the run state is not a JSON object") if st.get("repo") != repo or str(st.get("issue")) != str(n): - raise Stop("the run state names another repo or issue — not merging") + raise Stop("the run state names another repo or issue") + for key in ("rounds", "attempts"): + if not isinstance(st.get(key) or [], list) or not all(isinstance(r, dict) for r in st.get(key) or []): + raise Stop(f"the run state's {key} is not a list of records") + return st + + +def record_round(cwd, repo, n, result, sha): + """#595/#591: the latest gate result; one attempt per verify round — a new commit, or a new report on the same + commit (a round whose report is missing or unreadable still counts); and one round per verify report this run + has not read yet. An unparseable + report's counts are not kept. No run state (gate run outside /idd-all): nothing is recorded.""" + if not os.path.exists(state_path(cwd, n)): + return + st = read_state(cwd, repo, n) + rid = result.get("comment_id") + rounds, attempts = list(st.get("rounds") or []), list(st.get("attempts") or []) + at = iso(now()) + st["last_gate"] = {"status": result.get("status"), "report_id": rid, "sha": sha, "reason": result.get("reason"), + "at": at} + seen = [r.get("report_id") for r in rounds] + # An attempt is a verify round: a new commit, or a new report on the same commit (a fix pass that made no + # commit still counts, so the limit holds). Reading the same report again on the same commit adds nothing. + if not attempts or attempts[-1].get("sha") != sha or (rid is not None and rid not in seen): + attempts.append({"sha": sha, "report_id": rid, "at": at}) + if rid is not None and rid not in seen: + judged = result.get("status") != "unparseable" + rounds.append({"round": len(rounds) + 1, "sha": sha, "status": result.get("status"), + "blocking": result.get("blocking") if judged else None, + "in_scope": result.get("in_scope") if judged else None, + "low_in_scope": result.get("low_in_scope") if judged else None, + "rejected": result.get("rejected") if judged else None, + "report_id": rid, "at": at}) + seen.append(rid) + st["rounds"], st["attempts"] = rounds, attempts + if rid is not None: + result["round"] = seen.index(rid) + 1 + result["attempt"] = len(attempts) + write_state(cwd, n, st) + + +# ── next ─────────────────────────────────────────────────────────────────── + +def cmd_next(argv): + a = parse(argv, {"--cwd": "value", "--repo": "value", "--issue": "value"}) + if a is None or not common_ok(a): + return usage("next needs --cwd

--repo owner/repo --issue ") + unknown = {"decision": "stop", "merge": False, "mode": None, "rounds": [], "decided": False} + try: + answer = decide(read_state(a["--cwd"], a["--repo"], a["--issue"])) + except Stop as exc: + answer = dict(unknown, reason=f"no readable run state: {exc}") + except Exception as exc: # fail closed: a surprise is a stop without a merge, never "fix" + answer = dict(unknown, reason=f"internal error: {exc.__class__.__name__}: {exc}") + decided = answer.pop("decided", True) + print(json.dumps(answer, ensure_ascii=False)) + return 0 if decided else 3 + + +def merge_gate(st, rc, gate, sha): + """Guardrail 1 for every merge and push. Without a stop mode: a clean round, and no more than 2 recorded + rounds when unattended (#591). With one (#595): the newest report is the round `next` judged, and its + answer is stop with a merge.""" + mode = st.get("verify_stop") + rounds = st.get("rounds") or [] + if mode is None: + gate_stop(rc, gate) + attempts = st.get("attempts") or [] + if st.get("interaction") == "unattended" and len(attempts) > 2: + raise Stop(f"guardrail 1 (verify rounds) — {len(attempts)} verify rounds are recorded and a run without a stop " + "mode allows 2 verify rounds; a person reviews the fixes after the second") + if rounds and gate.get("comment_id") not in [r.get("report_id") for r in rounds]: + raise Stop("guardrail 1 (verify rounds) — the newest verify report was never judged in Phase 4 " + "(it is not in the round record)") + return + if rc == 2: + raise Stop(f"guardrail 1 (verify gate) — unparseable: {gate.get('reason')}") + if not rounds or rounds[-1].get("report_id") != gate.get("comment_id") or rounds[-1].get("sha") != sha: + raise Stop(f"guardrail 1 (stop mode {mode}) — the newest verify report is not the round the stop mode judged; " + "run close-stage.py gate and next again") + answer = decide(st) + if answer["decision"] != "stop" or not answer["merge"]: + raise Stop(f"guardrail 1 (stop mode {mode}) — {answer['reason']}; the stop mode does not merge this round " + f"(answer: {answer['decision']})") + settled_stop(gate) + # The clean merge requires a complete coverage line and reviewers line; verify-gate reads them for every verdict. + for field, what in (("coverage_complete", "a complete coverage line (X / X requirements addressed)"), + ("reviewers_complete", "a complete reviewers line (X / X reviewers completed)")): + if gate.get(field) is not True: + raise Stop(f"guardrail 1 (stop mode {mode}) — the report has no {what}; a merge needs it as a clean one does") + + +# ── run: shared checks ───────────────────────────────────────────────────── + +def load_state(cwd, repo, n): + try: + st = read_state(cwd, repo, n) + except Stop as exc: + raise Stop(f"{exc} (Step 0.7 records the run's flags) — not merging") try: age = now() - parse_iso(st["created_at"]) except (KeyError, ValueError, TypeError): raise Stop("the run state has no readable creation time — not merging") + # A run with a stop mode can run for long (#595): its age counts from the last verify round it recorded. + if st.get("verify_stop") and st.get("rounds"): + try: + age = now() - parse_iso(st["rounds"][-1]["at"]) + except (KeyError, ValueError, TypeError): + raise Stop("the run state has no readable time for its last verify round — not merging") if age > STATE_TTL or age < -300: raise Stop("the run state is older than 24 hours (an earlier run's) — not merging; rerun /idd-all") return st @@ -521,7 +666,7 @@ def run_pr(st, cwd, repo, n, timeout, grace, partial): since = parse_iso(st["created_at"]) rc, gate = judge_report(repo, n, sha, base, since) - gate_stop(rc, gate) + merge_gate(st, rc, gate, sha) # Local CI decides; remote checks are waited for only in remote mode. With a local pass they are read once, # right before the merge, and reported (capability local-ci-gate: they do not block the merge decision). @@ -546,14 +691,15 @@ def run_pr(st, cwd, repo, n, timeout, grace, partial): raise Stop("guardrail 3 (auto-close trap) — close keyword next to an issue reference in commit(s): " + ", ".join(hits)) subject = f"{pr.get('title') or ''} (#{pr['number']})" - body = f"Refs #{n}\n\nMerged by /idd-all after a clean verify: {gate.get('verify_url')}\n" + how = f"stop mode {st['verify_stop']}" if st.get("verify_stop") else "a clean verify" + body = f"Refs #{n}\n\nMerged by /idd-all after {how}: {gate.get('verify_url')}\n" if trap_hits(subject + "\n" + body): raise Stop(f"guardrail 4 (squash message) — close keyword next to an issue reference: {subject[:120]}") # The CI wait can take minutes: everything that can change meanwhile is read again right before the merge. base = pr_base(cwd, repo, default, sha) rc, gate = judge_report(repo, n, sha, base, since) - gate_stop(rc, gate) + merge_gate(st, rc, gate, sha) me = session_login() comments = issue_comments(repo, n) check_others(me, since, comments, issue_meta(repo, n)) @@ -627,7 +773,7 @@ def run_direct(st, cwd, repo, n, partial): if changed_ci: raise Stop(f"the change edits CI ({', '.join(changed_ci[:3])}) — workflow changes are pushed by a person") rc, gate = judge_report(repo, n, head, base, parse_iso(st["created_at"])) - gate_stop(rc, gate) + merge_gate(st, rc, gate, head) # Local CI before the push. In remote mode there is no remote result for commits that were never pushed, # so the push proceeds and remote CI runs after it (as before #465). local = ci_guardrail(cwd, head) @@ -635,7 +781,7 @@ def run_direct(st, cwd, repo, n, partial): # as the PR path does after its CI wait (verify r8 #1). since = parse_iso(st["created_at"]) rc, gate = judge_report(repo, n, head, base, since) - gate_stop(rc, gate) + merge_gate(st, rc, gate, head) check_others(session_login(), since, issue_comments(repo, n), issue_meta(repo, n)) # Everything below names `head`, never HEAD: another session can move HEAD # or switch the branch while the checks run (#392 verify r2 #1). @@ -832,9 +978,10 @@ def cmd_pr_check(argv): def main(argv): if not argv: - return usage("subcommand required: init | reset | gate | pr-check | run | confirm-close") + return usage("subcommand required: init | reset | gate | next | pr-check | run | confirm-close") sub, rest = argv[0], argv[1:] - handlers = {"init": cmd_init, "reset": cmd_reset, "gate": cmd_gate, "pr-check": cmd_pr_check, "run": cmd_run, + handlers = {"init": cmd_init, "reset": cmd_reset, "gate": cmd_gate, "next": cmd_next, "pr-check": cmd_pr_check, + "run": cmd_run, "confirm-close": cmd_confirm} if sub not in handlers: return usage(f"unknown subcommand '{sub}'") diff --git a/plugins/issue-driven-dev/scripts/lib/stopmode.py b/plugins/issue-driven-dev/scripts/lib/stopmode.py new file mode 100644 index 00000000..8cb17268 --- /dev/null +++ b/plugins/issue-driven-dev/scripts/lib/stopmode.py @@ -0,0 +1,119 @@ +"""stopmode.py — when /idd-all's fix loop stops, and whether that stop merges (#595). + +`decide(state)` reads only the run-state record that close-stage.py keeps: the stop +mode (`verify_stop`), the round record (`rounds`, one entry per verify report the +gate read) and the latest gate result (`last_gate`). It never asks GitHub and never +reads the model's memory, so the same record always gives the same answer. + +The table (openspec idd-pr-hitl-modes, "A configured stop mode decides when the fix +loop stops and whether the run merges"): + + early stop when the to-fix count is 0, or, from round 2 on, it is + not lower than the previous round's; merge when Blocking is 0 + exhaustive-blocking stop when Blocking is 0 (merge), or when Blocking was not lower + than the round before in each of the last two rounds (no merge) + exhaustive-all stop when Blocking and In-scope fix (LOW included) are 0; merge + no mode 2 rounds unattended, 1 attended (a round is a verify attempt, one per HEAD + the gate judged); merge only a clean round within the limit + +The to-fix count is what the loop fixes: Blocking plus the In-scope fix findings above +LOW. A run with --review or --in-chain fixes Blocking only and never merges, so its +count is Blocking. +""" + +MODES = ("early", "exhaustive-blocking", "exhaustive-all") +NO_MODE_ROUNDS = {"unattended": 2, "attended": 1} + + +def to_fix(r, blocking_only): + if blocking_only: + return r["blocking"] + return r["blocking"] + r["in_scope"] - (r.get("low_in_scope") or 0) + + +def _brief(r, blocking_only=False): + out = {k: r.get(k) for k in ("round", "sha", "status", "blocking", "in_scope", "low_in_scope", "report_id")} + out["to_fix"] = to_fix(r, blocking_only) if _counted(r) else None # Phase 6 lists it per round + return out + + +def _answer(decision, merge, reason, mode, rounds, blocking_only=False, **extra): + return dict({"decision": decision, "merge": merge, "reason": reason, "mode": mode, + "rounds": [_brief(r, blocking_only) for r in rounds]}, **extra) + + +def _counted(r): + return all(isinstance(r.get(k), int) for k in ("blocking", "in_scope")) + + +def _no_mode(st): + """Without a stop mode: the rules from before #595, with the round count read from the record (#591). + A round is a verify attempt — a new commit, or a new report on the same commit — so a round whose report was + missing or unreadable, or whose fix pass made no commit, still counts. Every answer carries `round` and `limit`. Rejected findings and the clean + test stay with the gate (close-stage.py gate_stop); only the limit is decided here.""" + rounds = st.get("rounds") or [] + interaction = st.get("interaction") or "unattended" + limit = NO_MODE_ROUNDS.get(interaction, 1) + k = len(st.get("attempts") or []) + status = (st.get("last_gate") or {}).get("status") + never_merges = bool(st.get("review") or st.get("in_chain")) + extra = {"round": k, "limit": limit} + if status == "clean": + if k > limit: + return _answer("stop", False, f"round {k} is clean, but a run without a stop mode allows {limit} " + "verify round(s)", None, rounds, **extra) + return _answer("stop", not never_merges, f"round {k} is clean", None, rounds, **extra) + if k >= limit: + return _answer("stop", False, f"no stop mode: {limit} verify round(s) for an {interaction} run, and round {k} " + f"is {status or 'not judged'}", None, rounds, **extra) + return _answer("fix", False, f"no stop mode: round {k} of {limit} is {status or 'not judged'}", None, rounds, **extra) + + +def decide(st): + """The answer for the newest recorded round. Anything that cannot be judged is a stop without a merge.""" + mode = st.get("verify_stop") + if mode is None: + return _no_mode(st) + rounds = st.get("rounds") or [] + last = st.get("last_gate") or {} + never_merges = bool(st.get("review") or st.get("in_chain")) + if not rounds: + return _answer("stop", False, "no verify round is recorded in the run state yet", mode, rounds, decided=False) + cur, k = rounds[-1], len(rounds) + if last.get("status") == "unparseable" or not _counted(cur): + return _answer("stop", False, f"the latest verify gate result is unparseable ({last.get('reason') or 'no counts'})", + mode, rounds, never_merges, round=k) + if last.get("report_id") != cur.get("report_id"): + return _answer("stop", False, "the latest gate result is not the newest recorded round", mode, rounds, + never_merges, round=k) + if cur.get("rejected"): + return _answer("stop", False, f"round {k} marks {cur['rejected']} finding(s) Rejected; a person decides", + mode, rounds, never_merges, round=k) + if mode not in MODES: + return _answer("stop", False, f"the run state names an unknown stop mode '{mode}'", mode, rounds, never_merges, round=k) + tf = to_fix(cur, never_merges) + prev = rounds[-2] if k >= 2 and _counted(rounds[-2]) else None + may_merge = not never_merges + if mode == "early": + if tf == 0: + return _answer("stop", may_merge and cur["blocking"] == 0, f"round {k} leaves nothing to fix", + mode, rounds, never_merges, round=k, to_fix=tf) + if prev is not None and tf >= to_fix(prev, never_merges): + p = to_fix(prev, never_merges) + return _answer("stop", may_merge and cur["blocking"] == 0, f"the to-fix count did not fall ({p} → {tf})", + mode, rounds, never_merges, round=k, to_fix=tf) + return _answer("fix", False, f"round {k} has {tf} finding(s) to fix", mode, rounds, never_merges, round=k, to_fix=tf) + if mode == "exhaustive-blocking": + if cur["blocking"] == 0: + return _answer("stop", may_merge, f"round {k} has no Blocking finding", mode, rounds, never_merges, round=k, to_fix=tf) + if k >= 3 and all(_counted(r) for r in rounds[-3:]): + a, b, c = (r["blocking"] for r in rounds[-3:]) + if c >= b and b >= a: + return _answer("stop", False, f"Blocking did not fall in the last two rounds ({a} → {b} → {c})", + mode, rounds, never_merges, round=k, to_fix=tf) + return _answer("fix", False, f"round {k} has {cur['blocking']} Blocking finding(s)", mode, rounds, never_merges, round=k, to_fix=tf) + # exhaustive-all: no round limit; LOW In-scope fix findings count too + left = cur["blocking"] + (0 if never_merges else cur["in_scope"]) + if left == 0: + return _answer("stop", may_merge, f"round {k} leaves no finding", mode, rounds, never_merges, round=k, to_fix=0) + return _answer("fix", False, f"round {k} leaves {left} finding(s)", mode, rounds, never_merges, round=k, to_fix=left) diff --git a/plugins/issue-driven-dev/scripts/tests/close-stage/scenarios.sh b/plugins/issue-driven-dev/scripts/tests/close-stage/scenarios.sh index 753b47c6..87c20103 100644 --- a/plugins/issue-driven-dev/scripts/tests/close-stage/scenarios.sh +++ b/plugins/issue-driven-dev/scripts/tests/close-stage/scenarios.sh @@ -51,14 +51,20 @@ import json, re, sys, html path, login, head, base, verdict, rows, heading = sys.argv[1:8] reviewed = f"{base}..{head}" if base != "-" else head pairs = [r.split(":", 1) for r in rows.split(";") if r] -md_rows = "".join(f"| {i} | LOW | {f} | codex | {c} |\n" for i, (c, f) in enumerate(pairs, 1)) -body = (f"{heading}\n\n6 / 6 reviewers completed\n\n### Aggregate\n{verdict}\n\n**Reviewed**: `{reviewed}`\n\n### 要求覆蓋率\n1 / 1 requirements addressed\n\n" +import os +sev = os.environ.get("SEV", "LOW") # #595: findings above LOW +cover = os.environ.get("COVER", "1 / 1") +revs = os.environ.get("REVIEWERS", "6 / 6") # empty: no reviewers line at all +rev_md = f"{revs} reviewers completed\n\n" if revs else "" +rev_html = f"

{revs} reviewers completed

\n" if revs else "" +md_rows = "".join(f"| {i} | {sev} | {f} | codex | {c} |\n" for i, (c, f) in enumerate(pairs, 1)) +body = (f"{heading}\n\n{rev_md}### Aggregate\n{verdict}\n\n**Reviewed**: `{reviewed}`\n\n### 要求覆蓋率\n{cover} requirements addressed\n\n" "### Findings(合併後)\n| # | Severity | Finding | Source | Action |\n|---|---|---|---|---|\n" + md_rows) strong = lambda t: re.sub(r"\*\*(.+?)\*\*", r"\1", html.escape(t, quote=False)) -html_rows = "".join(f"{i}LOW{html.escape(f)}codex{c}\n" +html_rows = "".join(f"{i}{sev}{html.escape(f)}codex{c}\n" for i, (c, f) in enumerate(pairs, 1)) -body_html = (f"

{html.escape(heading.lstrip('# '))}

\n

6 / 6 reviewers completed

\n

Aggregate

\n

{strong(verdict)}

\n" - f"

Reviewed: {reviewed}

\n

要求覆蓋率

\n

1 / 1 requirements addressed

\n" +body_html = (f"

{html.escape(heading.lstrip('# '))}

\n{rev_html}

Aggregate

\n

{strong(verdict)}

\n" + f"

Reviewed: {reviewed}

\n

要求覆蓋率

\n

{cover} requirements addressed

\n" "

Findings(合併後)

\n" "" f"\n{html_rows}
#SeverityFindingSourceAction
\n") @@ -91,11 +97,11 @@ pr_fixture() { # head-sha [title] echo '[{"name": "test", "bucket": "pass", "event": "pull_request"}]' > "$S/gh/checks-1.json" } -init_state() { # path [requested-path] [review] [in-chain] [interaction] - local path="$1" req="${2:-$1}" review="${3:-no}" chain="${4:-no}" inter="${5:-unattended}" +init_state() { # path [requested-path] [review] [in-chain] [interaction] [stop-mode] + local path="$1" req="${2:-$1}" review="${3:-no}" chain="${4:-no}" inter="${5:-unattended}" stop="${6:-none}" local branch=main; [ "$path" = PR ] && branch="idd/7-x" python3 "$CS" init --cwd "$C" --repo $REPO --issue $N --path "$path" --requested-path "$req" \ - --interaction "$inter" --branch "$branch" --default main --review "$review" --in-chain "$chain" >/dev/null + --interaction "$inter" --branch "$branch" --default main --review "$review" --in-chain "$chain" --stop "$stop" >/dev/null } run_stage() { # → OUT, RC @@ -630,11 +636,11 @@ assert_exit "gate: gh missing is unparseable, not 'not clean'" 2 "$RC" python3 "$CS" gate --cwd "$C" --repo $REPO --issue $N --sha abc >/dev/null 2>&1; assert_exit "gate: a short sha is a usage error" 64 $? python3 "$CS" run --cwd "$C" --repo "not a repo" --issue $N >/dev/null 2>&1; assert_exit "run: a malformed repo is a usage error" 64 $? python3 "$CS" run --cwd "$C" --repo $REPO --issue $N --ci-timeout nan >/dev/null 2>&1; assert_exit "run: a non-finite timeout is a usage error" 64 $? -python3 "$CS" init --cwd "$C" --repo $REPO --issue $N --path PR --requested-path PR --interaction unattended --branch b --default main --in-chain no >/dev/null 2>&1 +python3 "$CS" init --cwd "$C" --repo $REPO --issue $N --path PR --requested-path PR --interaction unattended --branch b --default main --in-chain no --stop none >/dev/null 2>&1 assert_exit "init: a missing --review is a usage error, not 'no'" 64 $? -python3 "$CS" init --cwd "$C" --repo $REPO --issue $N --path PR --requested-path PR --interaction unattended --branch b --default main --review "" --in-chain no >/dev/null 2>&1 +python3 "$CS" init --cwd "$C" --repo $REPO --issue $N --path PR --requested-path PR --interaction unattended --branch b --default main --review "" --in-chain no --stop none >/dev/null 2>&1 assert_exit "init: an empty --review (a lost variable) is a usage error" 64 $? -python3 "$CS" init --cwd "$C" --repo $REPO --issue $N --path sideways --requested-path PR --interaction unattended --branch b --default main --review no --in-chain no >/dev/null 2>&1 +python3 "$CS" init --cwd "$C" --repo $REPO --issue $N --path sideways --requested-path PR --interaction unattended --branch b --default main --review no --in-chain no --stop none >/dev/null 2>&1 assert_exit "init: an unknown path is a usage error" 64 $? BEFORE=$(wc -l < "$S/gh/calls.log") IDD_GH="$FAKE" FAKE_GH_DIR="$S/gh" IDD_CLOSE_STAGE_TEST=0 PATH=/nonexistent python3 "$CS" gate --cwd "$C" --repo $REPO --issue $N --sha "$SHA" >/dev/null 2>&1 @@ -726,4 +732,229 @@ new_scenario prc-nofetch; git -C "$C" remote set-url origin "$S/gone.git"; plain assert_eq "pr-check: the default branch cannot be fetched → ask" ask "$(printf '%s' "$PRC" | field status)" assert_grep "pr-check: the reason says the fetch failed" "could not fetch" "$(printf '%s' "$PRC" | field reason)" +echo "close-stage: stop modes (#595)" +# write_rounds mode interaction review "b,i,l;b,i,l" [last-gate-status] [attempts] [rejected-in-last-round] +# — a run-state with a stop mode and rounds. Each round gets report id 100+k and a 40-hex sha; last_gate repeats the +# newest round unless a status is given; attempts (one per commit the gate judged) default to one per round. +write_rounds() { + mkdir -p "$C/.claude/.idd/state" + python3 - "$C/.claude/.idd/state/idd-all-run-7.json" "$@" <<'EOF' +import json, sys, time +path, mode, inter, review, spec = sys.argv[1:6] +status = sys.argv[6] if len(sys.argv) > 6 else "not_clean" +n_attempts = int(sys.argv[7]) if len(sys.argv) > 7 and sys.argv[7] else None +rejected = int(sys.argv[8]) if len(sys.argv) > 8 else 0 +at = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()) +rounds = [] +for k, triple in enumerate([t for t in spec.split(";") if t], 1): + b, i, l = (int(x) for x in triple.split(",")) + rounds.append({"round": k, "sha": f"{k:040x}", "blocking": b, "in_scope": i, "low_in_scope": l, + "rejected": rejected if k == len(spec.split(";")) else 0, + "status": status if k == len(spec.split(";")) else "not_clean", + "report_id": 100 + k, "at": at}) +st = {"repo": "o/r", "issue": 7, "path": "PR", "requested_path": "PR", "interaction": inter, "branch": "idd/7-x", + "default": "main", "review": review == "yes", "in_chain": False, "created_at": at, + "verify_stop": None if mode == "none" else mode, "rounds": rounds, + "attempts": [{"sha": f"{k:040x}", "at": at} for k in range(1, (n_attempts if n_attempts is not None else len(rounds)) + 1)], + "last_gate": {"status": status, "report_id": rounds[-1]["report_id"] if rounds else None, + "sha": rounds[-1]["sha"] if rounds else None, "at": at}} +json.dump(st, open(path, "w")) +EOF +} +next_run() { NX=$(python3 "$CS" next --cwd "$C" --repo $REPO --issue $N 2>"$S/err"); RC=$?; } +nx() { printf '%s' "$NX" | field "$1"; } +rounds_len() { python3 -c 'import json,sys; print(len(json.load(open(sys.argv[1])).get("rounds") or []))' "$C/.claude/.idd/state/idd-all-run-7.json"; } +gate_run() { G=$(IDD_GH="$FAKE" FAKE_GH_DIR="$S/gh" python3 "$CS" gate --cwd "$C" --repo $REPO --issue $N --sha "$SHA" --base "$(base_of "$SHA")"); RC=$?; } + +# spec: early stops when the count stops falling and merges with no Blocking +new_scenario stop-early-converges; write_rounds early unattended no "0,6,0;0,4,0;0,4,0"; next_run +assert_eq "early 6,4,4: stop" stop "$(nx decision)" +assert_eq "early 6,4,4: merge" True "$(nx merge)" +assert_grep "early 6,4,4: the reason names 4 → 4" "4 → 4" "$(nx reason)" +assert_exit "early 6,4,4: next decided" 0 "$RC" +write_rounds early unattended no "0,6,0;0,4,0"; next_run +assert_eq "early 6,4: the count fell, fix again" fix "$(nx decision)" +write_rounds early unattended no "0,3,0"; next_run +assert_eq "early round 1 with findings: fix" fix "$(nx decision)" +write_rounds early unattended no "0,2,2"; next_run +assert_eq "early: only LOW in-scope findings is nothing to fix → stop" stop "$(nx decision)" +assert_eq "early: only LOW in-scope findings → merge" True "$(nx merge)" + +# spec: early stops with Blocking and does not merge +new_scenario stop-early-blocking; write_rounds early unattended no "1,2,0;1,2,0"; next_run +assert_eq "early 3,3 with 1 Blocking: stop" stop "$(nx decision)" +assert_eq "early 3,3 with 1 Blocking: no merge" False "$(nx merge)" + +# spec: exhaustive-blocking reaches zero Blocking +new_scenario stop-exb-zero; write_rounds exhaustive-blocking unattended no "2,0,0;1,0,0;0,3,0"; next_run +assert_eq "exhaustive-blocking 2,1,0: stop" stop "$(nx decision)" +assert_eq "exhaustive-blocking 2,1,0: merge with In-scope fix left" True "$(nx merge)" + +# spec: exhaustive-blocking stops when Blocking does not fall twice +new_scenario stop-exb-stuck; write_rounds exhaustive-blocking unattended no "2,0,0;2,0,0"; next_run +assert_eq "exhaustive-blocking 2,2: one round without progress, fix again" fix "$(nx decision)" +write_rounds exhaustive-blocking unattended no "2,0,0;2,0,0;2,0,0"; next_run +assert_eq "exhaustive-blocking 2,2,2: stop" stop "$(nx decision)" +assert_eq "exhaustive-blocking 2,2,2: no merge" False "$(nx merge)" +write_rounds exhaustive-blocking unattended no "3,0,0;2,0,0;2,0,0"; next_run +assert_eq "exhaustive-blocking 3,2,2: only one round without progress, fix again" fix "$(nx decision)" + +# spec: exhaustive-all keeps going until nothing is left +new_scenario stop-exall; write_rounds exhaustive-all unattended no "3,3,0;2,3,0;1,2,0;1,1,0;0,1,0;0,1,1"; next_run +assert_eq "exhaustive-all round 6 with one LOW in-scope finding: fix" fix "$(nx decision)" +write_rounds exhaustive-all unattended no "3,3,0;2,3,0;1,2,0;1,1,0;0,1,0;0,1,1;0,0,0"; next_run +assert_eq "exhaustive-all round 7 at zero: stop" stop "$(nx decision)" +assert_eq "exhaustive-all round 7 at zero: merge" True "$(nx merge)" +write_rounds exhaustive-all unattended no "5,0,0;5,0,0;5,0,0;5,0,0"; next_run +assert_eq "exhaustive-all has no round limit and no progress rule" fix "$(nx decision)" + +# spec: an attended run with a stop mode fixes on its own +new_scenario stop-attended; write_rounds early attended no "1,0,0"; next_run +assert_eq "attended early with 1 Blocking in round 1: fix" fix "$(nx decision)" + +# stop modes: what stops every mode, and runs that never merge +new_scenario stop-edges; write_rounds exhaustive-all unattended no "1,0,0" unparseable; next_run +assert_eq "an unparseable latest gate stops" stop "$(nx decision)" +assert_eq "an unparseable latest gate does not merge" False "$(nx merge)" +write_rounds early unattended yes "0,3,0"; next_run +assert_eq "--review counts Blocking only: nothing to fix → stop" stop "$(nx decision)" +assert_eq "--review never merges" False "$(nx merge)" +rm -f "$C/.claude/.idd/state/idd-all-run-7.json"; next_run +assert_exit "next without a run state cannot decide" 3 "$RC" +assert_eq "next without a run state answers stop" stop "$(nx decision)" +assert_eq "next without a run state does not merge" False "$(nx merge)" +write_rounds none unattended no "0,3,0"; next_run +assert_eq "no stop mode, unattended round 1: fix" fix "$(nx decision)" +write_rounds none unattended no "0,3,0;0,2,0"; next_run +assert_eq "no stop mode, unattended round 2: stop (two-round limit)" stop "$(nx decision)" +write_rounds none attended no "0,3,0"; next_run +assert_eq "no stop mode, attended round 1: stop" stop "$(nx decision)" +write_rounds none unattended no "1,0,0" unparseable; next_run +assert_eq "no stop mode, unparseable in round 1 of 2: rounds are left (Phase 4 reads the report itself)" fix "$(nx decision)" +assert_eq "no stop mode, unparseable: the answer still carries the round limit" 2 "$(nx limit)" +assert_eq "no stop mode, unparseable: and the round" 1 "$(nx round)" +write_rounds none unattended no "0,3,0" unparseable 2; next_run +assert_eq "no stop mode: a second attempt whose report was missing still counts → stop" stop "$(nx decision)" +assert_eq "no stop mode: the missing report's attempt is round 2" 2 "$(nx round)" +write_rounds none unattended no "1,0,0" not_clean "" 1; next_run +assert_eq "no stop mode, round 1 with a Rejected finding: fix as before #595" fix "$(nx decision)" +assert_eq "no stop mode, round 1 with a Rejected finding: the answer carries the limit" 2 "$(nx limit)" +write_rounds none unattended no "0,0,0" clean 3; next_run +assert_eq "no stop mode, a clean third round: no merge" False "$(nx merge)" +write_rounds early unattended no "0,3,0" not_clean "" 1; next_run +assert_eq "early, a round with a Rejected finding: stop" stop "$(nx decision)" +assert_eq "early, a round with a Rejected finding: no merge" False "$(nx merge)" +write_rounds early unattended no "0,6,0;0,4,0"; next_run +assert_eq "next lists the to-fix count of each round" "6 4" "$(printf '%s' "$NX" | python3 -c 'import json,sys; print(" ".join(str(r["to_fix"]) for r in json.load(sys.stdin)["rounds"]))')" + +# spec: the same report read twice is one round +pr_scenario stop-gate-rounds; init_state PR PR no no unattended early +gate_run; gate_run +assert_eq "gate: the same report read twice is one round" 1 "$(rounds_len)" +assert_eq "gate: prints the round number" 1 "$(printf '%s' "$G" | field round)" +verify_comment me "$SHA" "$(base_of "$SHA")" "$PASS_LINE"; gate_run +assert_eq "gate: a new report is a new round" 2 "$(rounds_len)" +gate_run +assert_eq "gate: reading round 2's report again keeps 2 rounds" 2 "$(rounds_len)" +attempts_len() { python3 -c 'import json,sys; print(len(json.load(open(sys.argv[1])).get("attempts") or []))' "$C/.claude/.idd/state/idd-all-run-7.json"; } +assert_eq "gate: a new report on the same commit is a new attempt (a fix pass that made no commit counts)" 2 "$(attempts_len)" + +# spec: flag over config, and values outside the three (the init half; the skill resolves flag and config) +new_scenario stop-init +python3 "$CS" init --cwd "$C" --repo $REPO --issue $N --path PR --requested-path PR --interaction unattended --branch b --default main --review no --in-chain no >/dev/null 2>&1 +assert_exit "init: a missing --stop is a usage error" 64 $? +python3 "$CS" init --cwd "$C" --repo $REPO --issue $N --path PR --requested-path PR --interaction unattended --branch b --default main --review no --in-chain no --stop fast >/dev/null 2>&1 +assert_exit "init: --stop fast is a usage error" 64 $? + for m in none early exhaustive-blocking exhaustive-all; do # indented: run_parallel.py starts a new scenario at a top-level for + python3 "$CS" init --cwd "$C" --repo $REPO --issue $N --path PR --requested-path PR --interaction unattended --branch b --default main --review no --in-chain no --stop "$m" >/dev/null + assert_eq "init: --stop $m is recorded" "$([ "$m" = none ] && echo None || echo "$m")" "$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1])).get("verify_stop", ""))' "$C/.claude/.idd/state/idd-all-run-7.json")" + done + +# spec: a stop-mode run merges a reviewed commit that is not clean +new_scenario stop-merge-notclean; git -C "$C" checkout -q -b idd/7-x; work_commit "feat: thing (#7)"; pr_fixture "$SHA" +verify_comment me "$SHA" "$(base_of "$SHA")" "**FAIL** — 0 blocking, 1 in-scope fix" "In-scope fix:a LOW leftover" +init_state PR PR no no unattended early; gate_run; run_stage +assert_eq "early, a FAIL round with nothing to fix: merged" merged "$(printf '%s' "$OUT" | field status)" +assert_exit "early, a FAIL round with nothing to fix: exit" 0 "$RC" + +new_scenario stop-merge-nomode; git -C "$C" checkout -q -b idd/7-x; work_commit "feat: thing (#7)"; pr_fixture "$SHA" +verify_comment me "$SHA" "$(base_of "$SHA")" "**FAIL** — 0 blocking, 1 in-scope fix" "In-scope fix:a LOW leftover" +init_state PR; gate_run; run_stage +stop_case "no stop mode, the same FAIL round" "verify gate" + +new_scenario stop-merge-blocking; git -C "$C" checkout -q -b idd/7-x; work_commit "feat: thing (#7)"; pr_fixture "$SHA" +verify_comment me "$SHA" "$(base_of "$SHA")" "**FAIL** — 1 blocking" "Blocking:a real problem" +init_state PR PR no no unattended early; gate_run; run_stage +stop_case "early, a round with Blocking" "stop mode early" + +new_scenario stop-merge-stale; git -C "$C" checkout -q -b idd/7-x; work_commit "feat: thing (#7)"; pr_fixture "$SHA" +verify_comment me "$SHA" "$(base_of "$SHA")" "**FAIL** — 0 blocking, 1 in-scope fix" "In-scope fix:a LOW leftover" +init_state PR PR no no unattended early; gate_run +verify_comment me "$SHA" "$(base_of "$SHA")" "**FAIL** — 0 blocking, 1 in-scope fix" "In-scope fix:a LOW leftover"; run_stage +stop_case "early, a report the round record has not seen" "not the round" + +# two rounds of one PR: round 1 on the first commit, round 2 on a fix commit +two_rounds() { # name mode "verdict1" "rows1" "verdict2" "rows2" + new_scenario "$1"; git -C "$C" checkout -q -b idd/7-x; work_commit "feat: thing (#7)"; pr_fixture "$SHA" + init_state PR PR no no unattended "$2" + verify_comment me "$SHA" "$(base_of "$SHA")" "$3" "$4"; gate_run + work_commit "fix: address verify finding (#7)"; pr_fixture "$SHA" + verify_comment me "$SHA" "$(base_of "$SHA")" "$5" "$6"; gate_run +} +# spec: early stops when the count stops falling and merges with no Blocking (the run itself, findings above LOW) +SEV=MEDIUM two_rounds stop-run-early-flat early "**FAIL** — 0 blocking, 2 in-scope fix" "In-scope fix:a;In-scope fix:b" \ + "**FAIL** — 0 blocking, 2 in-scope fix" "In-scope fix:c;In-scope fix:d"; run_stage +assert_eq "early 2 → 2 with MEDIUM findings: the run merges the reviewed commit" merged "$(printf '%s' "$OUT" | field status)" +assert_output_grep "early: the squash body names the stop mode" "after stop mode early" "$S/gh/calls.log" +# spec: exhaustive-blocking reaches zero Blocking (the run itself) +SEV=MEDIUM two_rounds stop-run-exb exhaustive-blocking "**FAIL** — 1 blocking, 3 in-scope fix" "Blocking:x;In-scope fix:a;In-scope fix:b;In-scope fix:c" \ + "**FAIL** — 0 blocking, 3 in-scope fix" "In-scope fix:a;In-scope fix:b;In-scope fix:c"; run_stage +assert_eq "exhaustive-blocking at 0 Blocking with 3 MEDIUM left: merged" merged "$(printf '%s' "$OUT" | field status)" +# spec: a stop-mode merge passes the clean merge's coverage and reviewers checks +COVER="3 / 5" SEV=MEDIUM two_rounds stop-run-cover early "**FAIL** — 0 blocking, 2 in-scope fix" "In-scope fix:a;In-scope fix:b" \ + "**FAIL** — 0 blocking, 2 in-scope fix" "In-scope fix:c;In-scope fix:d"; run_stage +stop_case "early, coverage 3 / 5" "coverage line" +REVIEWERS="" SEV=MEDIUM two_rounds stop-run-noreviewers early "**FAIL** — 0 blocking, 2 in-scope fix" "In-scope fix:a;In-scope fix:b" \ + "**FAIL** — 0 blocking, 2 in-scope fix" "In-scope fix:c;In-scope fix:d"; run_stage +stop_case "early, no reviewers line" "reviewers line" +# no stop mode: a report the round record never saw does not merge +pr_scenario stop-nomode-unseen; gate_run; verify_comment me "$SHA" "$(base_of "$SHA")" "$PASS_LINE"; run_stage +stop_case "no stop mode, a newer report Phase 4 never judged" "never judged" +# gate: a broken round record fails the gate closed +pr_scenario stop-gate-broken; echo '{"repo": "o/r", "issue": 7, "rounds": "x"}' > "$C/.claude/.idd/state/idd-all-run-7.json"; gate_run +assert_exit "gate: a round record that is not a list is unparseable" 2 "$RC" +assert_eq "gate: … and says so" unparseable "$(printf '%s' "$G" | field status)" + +# spec (Clean verify leads to merge and close): a stop-mode run is not stopped by its own length +age_state() { # created-hours-ago last-round-hours-ago + python3 - "$C/.claude/.idd/state/idd-all-run-7.json" "$1" "$2" <<'EOF' +import json, sys, time +path, created, last = sys.argv[1], float(sys.argv[2]), float(sys.argv[3]) +st = json.load(open(path)) +fmt = lambda h: time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(time.time() - h * 3600)) +st["created_at"] = fmt(created) +if st.get("rounds"): + st["rounds"][-1]["at"] = fmt(last) +json.dump(st, open(path, "w")) +EOF +} +pr_scenario stop-ttl-mode; init_state PR PR no no unattended exhaustive-all; gate_run; age_state 30 2; run_stage +assert_eq "exhaustive-all, created 30 h ago, last round 2 h ago: merged" merged "$(printf '%s' "$OUT" | field status)" +pr_scenario stop-ttl-old; init_state PR PR no no unattended exhaustive-all; gate_run; age_state 30 26; run_stage +stop_case "exhaustive-all, last round 26 h ago" "older than 24 hours" +pr_scenario stop-ttl-nomode; gate_run; age_state 30 2; run_stage +stop_case "no stop mode, created 30 h ago" "older than 24 hours" + +# spec (Unattended fix loop … two-round limit): a third round is caught by the close stage +pr_scenario stop-third-round; gate_run +python3 - "$C/.claude/.idd/state/idd-all-run-7.json" <<'EOF' +import json, sys +p = sys.argv[1]; st = json.load(open(p)); last = st["rounds"][-1] +st["rounds"] = [dict(last, round=1, report_id=-1), dict(last, round=2, report_id=-2), dict(last, round=3)] +st["attempts"] = [{"sha": "1" * 40, "at": last["at"]}, {"sha": "2" * 40, "at": last["at"]}, {"sha": last["sha"], "at": last["at"]}] +json.dump(st, open(p, "w")) +EOF +run_stage +stop_case "no stop mode, 3 rounds recorded" "2 verify rounds" + print_summary close-stage diff --git a/plugins/issue-driven-dev/scripts/verify-gate.py b/plugins/issue-driven-dev/scripts/verify-gate.py index b7264dad..2981cc11 100755 --- a/plugins/issue-driven-dev/scripts/verify-gate.py +++ b/plugins/issue-driven-dev/scripts/verify-gate.py @@ -107,6 +107,8 @@ def emit(status, reason, verdict=None, counts=None, extra=None): "low_in_scope": (extra or {}).get("low_in_scope"), "high_follow_up": (extra or {}).get("high_follow_up"), "process_gaps": (extra or {}).get("process_gaps"), + "coverage_complete": (extra or {}).get("coverage_complete"), + "reviewers_complete": (extra or {}).get("reviewers_complete"), "reason": reason, } print(json.dumps(out, ensure_ascii=False)) @@ -316,7 +318,14 @@ def judge(html, expect_sha=None, expect_base=None): reviewers = [m for m in (REVIEWERS_RE.match(t) for t in all_lines) if m] if any(int(m.group(1)) < int(m.group(2)) for m in reviewers): gaps = True - extra = {"high_follow_up": high_follow_up, "process_gaps": gaps, "low_in_scope": low_in_scope} + # Whether the coverage line and the reviewers line are complete, read for every verdict (#595): a stop mode + # can merge a FAIL round, and that merge passes the same coverage and reviewers checks as a clean one. + cover = [m for m in (COVERAGE_RE.match(t) for t in all_lines) if m] + coverage_complete = len(cover) == 1 and cover[0].group(1) == cover[0].group(2) + reviewers_complete = (len(reviewers) == 1 and int(reviewers[0].group(2)) > 0 + and int(reviewers[0].group(1)) == int(reviewers[0].group(2))) + extra = {"high_follow_up": high_follow_up, "process_gaps": gaps, "low_in_scope": low_in_scope, + "coverage_complete": coverage_complete, "reviewers_complete": reviewers_complete} pairs = [(k.lower(), int(v)) for v, k in COUNT_RE.findall(verdict_text)] stated = dict(pairs) diff --git a/plugins/issue-driven-dev/skills/idd-all/SKILL.md b/plugins/issue-driven-dev/skills/idd-all/SKILL.md index 61344d34..ec05e9fa 100644 --- a/plugins/issue-driven-dev/skills/idd-all/SKILL.md +++ b/plugins/issue-driven-dev/skills/idd-all/SKILL.md @@ -104,11 +104,11 @@ TaskCreate(name="preflight", description="Phase 0: 解析 args(含 --pr/--no-pr/ TaskCreate(name="parse_review_flag", description="Phase 0: 解析 --review flag → $REVIEW_FLAG (Phase 6 terminal report 切換 verify-gated default vs awaiting human acceptance; per #102 Foresay doctrine)") TaskCreate(name="resolve_mode", description="Phase 0.5: 從 pr_policy + flag + fork detection 解析 (path, interaction) tuple,印 notice line。PR mode 才檢查 git clean + on-default-branch + 建 feature branch;direct-commit mode 留在當前 branch。") TaskCreate(name="existing_work_check", description="Phase 0.5.1 (#366): 在建任何 branch 之前呼叫 scripts/check-existing-work.sh;blocked → attended 問三選項、unattended 停該張並記入 Phase 6 Action items;resume → 在該 PR/branch 上繼續;unknown → 印出並繼續") -TaskCreate(name="record_run", description="Step 0.7 (#392): close-stage.py init 把 path/interaction/branch/default/--review/--in-chain 寫進 run-state(from-scratch 在 Phase 1 之後)") +TaskCreate(name="record_run", description="Step 0.7 (#392): close-stage.py init 把 path/interaction/branch/default/--review/--in-chain/--stop(#595 停止模式)寫進 run-state(from-scratch 在 Phase 1 之後)") TaskCreate(name="ensure_issue", description="Phase 1: 若 from-scratch 則跑 idd-issue; from-issue 則 verify issue 存在") TaskCreate(name="diagnose", description="Phase 2: 跑 idd-diagnose,讀回 complexity 判定") TaskCreate(name="implement_or_sdd", description="Phase 3: type=meeting → attended 走 meeting 版 /idd-plan、unattended 跳過(#383,先跑 meeting unwind); Simple/Plan → idd-implement; Spectra → spectra-discuss → spectra-propose → spectra-apply。Args 含 UNATTENDED MODE 與否依 Phase 0.5 解析的 interaction 軸決定。") -TaskCreate(name="verify_loop", description="Phase 4: type=meeting → 跳過(#383); 每輪 idd-verify 後跑 scripts/verify-gate.py 讀這一輪新貼出的報告(#392); clean → 往下(low_in_scope 大於 0 時把那些列合成一張 follow-up issue,不為它們改 branch); unparseable → STOP_REASON; not_clean: unattended 修 Blocking 與 In-scope fix 後重跑(最多 2 輪 verify), attended 交回 user; follow-ups → 開新 issue") +TaskCreate(name="verify_loop", description="Phase 4: type=meeting → 跳過(#383); 每輪 idd-verify 後跑 close-stage.py gate 與 next(#595:要不要再修一輪、停下時合不合併由 next 依停止模式回答;沒有模式時是下面的規則); 每輪 idd-verify 後跑 scripts/verify-gate.py 讀這一輪新貼出的報告(#392); clean → 往下(low_in_scope 大於 0 時把那些列合成一張 follow-up issue,不為它們改 branch); unparseable → STOP_REASON; not_clean: unattended 修 Blocking 與 In-scope fix 後重跑(最多 2 輪 verify), attended 交回 user; follow-ups → 開新 issue") TaskCreate(name="ci_gate", description="Phase 4.5 (#465): type=meeting → 跳過; 對 HEAD 跑 scripts/idd-ci-gate.sh,紀錄貼到 issue;只有 exit 0 繼續、exit 10 改看遠端 CI;exit 3 attended 問指令、unattended 停下回報;exit 1/2/4 停下回報") TaskCreate(name="open_pr", description="Phase 5: type=meeting → 跳過、不 push(#383); PR mode → git push + 已有自家 open PR 就沿用並更新 body,否則 gh pr create(body 照 verify gate 結果寫,含 Refs #N, 不含 Closes); direct-commit mode → 不開 PR,進 Phase 5c") TaskCreate(name="close_stage", description="Phase 5c (#392): scripts/close-stage.py run(同一個 process,run_in_background):讀 Step 0.7 的 run-state,擋 --review/--in-chain/meeting/無寫入權限/run 開始後別人插手/意圖沒確認(tier 與沒人處理的 Proposed Corrections 不擋);gate 綁 HEAD SHA、只認本帳號的報告、讀 GitHub 渲染後的 HTML,有 Rejected finding 就停;CI 等完再重查預設 branch 與 PR 上的人;PR → 本機 CI 閘門 idd-ci-gate.sh(0 過、10 才等遠端 check:pending 最多 15 分鐘、有 pull_request workflow 就等 check 出現;其他結束碼停)、auto-close trap、squash message,全過才 gh pr merge --squash --match-head-commit 並確認 MERGED;direct-commit → 在預設 branch、每個要推的 commit 都引用 #N 才 push。merged/pushed 才以 ORCHESTRATED BY /idd-all 呼叫 /idd-close --repo,最後確認 CLOSED 且有 closing summary") @@ -149,6 +149,8 @@ REVIEW_FLAG="" # "" | "--review" — set by --review flag (v2.65+ #102) # #392: the same two opt-outs as explicit yes/no for Step 0.7. A lost variable must be an # error there, never a silent "no" that lets the close stage merge (#392 verify r2 #3). REVIEW_YN="no"; IN_CHAIN_YN="no" +STOP_FLAG="" # "" | early | exhaustive-blocking | exhaustive-all — set by --stop (#595) +STOP_GIVEN="" # "1" when --stop appeared at all: an empty value is a mistake, not "no flag" ARGS=("$@") for ((i=0; i<${#ARGS[@]}; i++)); do arg="${ARGS[i]}" @@ -174,8 +176,16 @@ for ((i=0; i<${#ARGS[@]}; i++)); do # change idd-all behavior, does NOT make idd-all wait. Per MANIFESTO # "Human-in-the-loop: IDD 即 Foresay Confirmation Protocol" doctrine. REVIEW_FLAG="--review"; REVIEW_YN="yes" ;; + --stop=*) STOP_GIVEN=1; STOP_FLAG="${arg#--stop=}" ;; + --stop) STOP_GIVEN=1; i=$((i+1)); STOP_FLAG="${ARGS[i]:-}" ;; esac done +# #595: a --stop value outside the three is the user's explicit request mistyped — stop before Phase 1 +case "$STOP_FLAG" in + early|exhaustive-blocking|exhaustive-all) ;; + '') [ -z "$STOP_GIVEN" ] || abort "--stop needs a value: early, exhaustive-blocking or exhaustive-all" ;; + *) abort "--stop must be early, exhaustive-blocking or exhaustive-all (got '$STOP_FLAG')" ;; +esac # 2. 確定 working tree 路徑 if [ -n "$CWD_FLAG" ]; then @@ -217,8 +227,29 @@ find_idd_config() { return 1 } CONFIG_PATH=$(find_idd_config "$CWD") # may be empty if no config found + +# 5. Stop mode (#595): --stop wins; else verify_stop.mode of the config. A config value outside the three is +# no stop mode — the stricter behaviour (fewer automatic merges), so a typo never loosens anything. +if [ -n "$STOP_FLAG" ]; then + STOP_MODE="$STOP_FLAG"; STOP_SRC="flag=--stop" +else + STOP_MODE="" + if [ -n "$CONFIG_PATH" ] && jq -e 'has("verify_stop")' "$CONFIG_PATH" >/dev/null 2>&1; then + # present: an object with a string mode, or else a value that is not understood (printed below) + STOP_MODE=$(jq -r 'if (.verify_stop | type) == "object" then (.verify_stop.mode // "(no mode)") else "(not an object)" end' "$CONFIG_PATH" 2>/dev/null || echo "(unreadable)") + fi + case "$STOP_MODE" in + early|exhaustive-blocking|exhaustive-all) STOP_SRC="config verify_stop.mode" ;; + '') STOP_MODE=none; STOP_SRC="no stop mode" ;; + *) echo "⚠ verify_stop.mode '$STOP_MODE' in $CONFIG_PATH is not early, exhaustive-blocking or exhaustive-all — running without a stop mode" + STOP_MODE=none; STOP_SRC="no stop mode (the config value was ignored)" ;; + esac +fi +echo "→ Stop mode: $STOP_MODE — $STOP_SRC" ``` +> **停止模式(#595)**:`none`(沒有設定)時 verify 迴圈與合併條件與 #595 之前相同。三種模式的判定表在 Phase 4,config 欄位在 [`references/config-protocol.md`](../../references/config-protocol.md) 的 `verify_stop` 一節。 + > **Why parse `--pr/--no-pr` here, not in Phase 0.5**: Phase 0.5 references `$PR_FLAG` and `$CONFIG_PATH` in its precedence chain. Both variables must be initialized before that chain runs. Conflict detection between `--pr` and `--no-pr` (Task: P1 finding 4) lands here at parse time so we abort early with a clear message. **為什麼需要 explicit `--cwd`**:Skill tool 呼叫繼承 Claude Code session-level cwd,不會跟著 mid-session `cd` 移動。跨 repo 工作(例如 thesis 在 repo A、要對 repo B 跑 idd-all)時,沒有 `--cwd` 就只能重啟 Claude Code session — 違反 unattended pipeline contract。 @@ -576,11 +607,12 @@ DEFAULT_BRANCH=$(gh repo view "$GITHUB_REPO" --json defaultBranchRef -q .default python3 "${CLAUDE_PLUGIN_ROOT}/scripts/close-stage.py" init --cwd "$CWD" --repo "$GITHUB_REPO" --issue "$N" \ --path "$PATH_AXIS" --requested-path "$REQUESTED_PATH" --interaction "$INTERACTION" \ --branch "$BRANCH" --default "$DEFAULT_BRANCH" --review "$REVIEW_YN" --in-chain "$IN_CHAIN_YN" \ + --stop "$STOP_MODE" \ || { echo "⚠ Step 0.7: the run state was not recorded — the run continues, and the close stage will stop at verified (it merges only with a run state)" python3 "${CLAUDE_PLUGIN_ROOT}/scripts/close-stage.py" reset --cwd "$CWD" --issue "$N"; } # a failed init leaves no run state ``` -每個值都必填:shell 變數跨 tool call 遺失時,init 會因為空值而報 usage error(exit 64),不會悄悄記成「沒有 `--review`」。run 照常往下走,close stage 因為沒有 run-state 而停在 verified:上一次 run 的狀態已在 Step 0.5.1 之後清掉,`||` 之後的 reset 再清一次,不沿用上一次 run 的旗標(verify r3 #17、r5 #36)。N 本身遺失時,上面的 FATAL 先中止這一段,同樣沒有舊狀態可讀。在新的 shell 重跑這一段時,`REVIEW_YN`/`IN_CHAIN_YN`/`REQUESTED_PATH` 要從這次 `/idd-all` 的原始參數與 Phase 0.5 印出的那兩行重新得出。 +每個值都必填:shell 變數跨 tool call 遺失時,init 會因為空值而報 usage error(exit 64),不會悄悄記成「沒有 `--review`」。run 照常往下走,close stage 因為沒有 run-state 而停在 verified:上一次 run 的狀態已在 Step 0.5.1 之後清掉,`||` 之後的 reset 再清一次,不沿用上一次 run 的旗標(verify r3 #17、r5 #36)。N 本身遺失時,上面的 FATAL 先中止這一段,同樣沒有舊狀態可讀。在新的 shell 重跑這一段時,`REVIEW_YN`/`IN_CHAIN_YN`/`REQUESTED_PATH` 要從這次 `/idd-all` 的原始參數與 Phase 0.5 印出的那兩行重新得出,`STOP_MODE` 照抄 Step 0.2 印出的 `→ Stop mode:` 那一行。 檔案在 `$CWD/.claude/.idd/state/`,與 unattended flag 同一個目錄;請確認目標 repo 的 ignore 規則涵蓋它(`scripts/git-ignore-block.sh`)。run-state 超過 24 小時就不算數;Phase 6 結束時刪掉。沒有這個檔,Phase 5c 一律不 merge、不 push。 @@ -1103,18 +1135,53 @@ BASE_SHA=$(git -C "$CWD" merge-base "origin/$DEFAULT_BRANCH" "$HEAD_SHA") GATE_BASE=(--base "$BASE_SHA") [ "$(jq -r 'if (.review or .in_chain) then "no" else "yes" end' "$CWD/.claude/.idd/state/idd-all-run-$N.json" 2>/dev/null)" = yes ] || GATE_BASE=() GATE_JSON=$(python3 "${CLAUDE_PLUGIN_ROOT}/scripts/close-stage.py" gate --cwd "$CWD" --repo "$GITHUB_REPO" --issue "$N" --sha "$HEAD_SHA" "${GATE_BASE[@]}") -echo "→ verify gate (round $ROUND, head $HEAD_SHA${GATE_BASE:+, range from $BASE_SHA}): $GATE_JSON" +echo "→ verify gate (head $HEAD_SHA${GATE_BASE:+, range from $BASE_SHA}): $GATE_JSON" +``` + +gate 讀到這次 run 還沒讀過的報告時,會把這一輪的計數記進 run-state(#595)。接著問 `next` 下一步,**在同一個回合、gate 之後立刻跑**: + +```bash +case "$N" in ''|*[!0-9]*) echo "FATAL: Phase 4: issue number is not numeric: $N" >&2; exit 1 ;; esac +NEXT_JSON=$(python3 "${CLAUDE_PLUGIN_ROOT}/scripts/close-stage.py" next --cwd "$CWD" --repo "$GITHUB_REPO" --issue "$N"); NEXT_RC=$? +echo "→ next (round $(printf '%s' "$NEXT_JSON" | jq -r '.round // "?"')): $NEXT_JSON" +[ "$NEXT_RC" -eq 0 ] || echo "⚠ next could not decide (exit $NEXT_RC) — the answer is stop without a merge" ``` ```python -MAX_ROUND = 2 if INTERACTION == "unattended" else 1 # verify rounds; at most one fix pass between them +# The loop's next step comes from close-stage.py next (#595/#591): it reads the run state's stop mode and the +# round record the gate wrote. The model does not count rounds and does not decide when a stop mode stops. # In-scope fix findings are fixed and re-verified only when this run can reach the close stage. # --review and --in-chain runs never merge, so they keep the earlier scope: fix Blocking only. FIX_IN_SCOPE = not REVIEW_FLAG and not IN_CHAIN # read the run-state file if the shell lost them +STOP_MODE = run_state["verify_stop"] # None, "early", "exhaustive-blocking" or "exhaustive-all" STOP_REASON = None -for ROUND in 1..MAX_ROUND: +while True: Skill(skill="issue-driven-dev:idd-verify", args=VERIFY_ARGS) - gate = verify_gate() # the bash block above → GATE_JSON + gate = verify_gate() # the gate block above → GATE_JSON (it records the round) + nxt = next_step() # the next block above → NEXT_JSON + + if STOP_MODE is not None: + # With a stop mode (#595), attended and unattended alike: next decides, the model only fixes. + if nxt.decision == "fix": + rows = report_rows(action="Blocking") + (report_rows(action="In-scope fix") if FIX_IN_SCOPE else []) + if any(is_security_vulnerability(r) for r in rows): + abort_with_message("a finding to fix is a security vulnerability; manual intervention needed") + attempt_auto_fix(rows) + continue + if nxt.merge and any(is_security_vulnerability(r) for r in report_rows(action="In-scope fix")): + abort_with_message("a finding left by the stop-mode merge is a security vulnerability; manual intervention needed") + if nxt.merge and report_rows(action="In-scope fix"): + # Stop with a merge and findings left: do NOT change the branch (the commit that merges is the one this + # round reviewed). File them together, like the low_in_scope rows of a clean round. + file_one_follow_up_issue(report_rows(action="In-scope fix")) + if not nxt.merge: + STOP_REASON = f"stop mode {STOP_MODE}: {nxt.reason}" + break # → Phase 5; Phase 5c merges only when next answered merge + + # No stop mode: the rules of #392. The round limit (2 unattended, 1 attended) is next's, not the model's. + # A round is a verify attempt: a new commit or a new report on the same commit, also when its report was missing + # or unreadable, or the fix pass made no commit. + # When next's answer has no round or no limit (no run state, e.g. Step 0.7's init failed), the limit is reached. if gate.status == "clean" or (gate.status == "not_clean" and gate.blocking == 0 and not FIX_IN_SCOPE): if gate.status == "clean" and gate.low_in_scope > 0: @@ -1132,7 +1199,7 @@ for ROUND in 1..MAX_ROUND: break # Phase 5 opens the PR with a "not clean" body; Phase 5c does not run if INTERACTION == "attended": report_findings_and_exit_to_user(); break - if ROUND == MAX_ROUND: + if nxt.round >= nxt.limit: abort_with_message("verify still has Blocking findings after the last round; manual intervention needed") attempt_auto_fix(report_rows(action="Blocking")); continue @@ -1144,11 +1211,11 @@ for ROUND in 1..MAX_ROUND: STOP_REASON = "verify gate: not_clean — findings handed back to the user" break - if ROUND == MAX_ROUND: + if nxt.decision == "stop": if gate.blocking > 0: - abort_with_message(f"verify still has Blocking findings after {MAX_ROUND} rounds; manual intervention needed") + abort_with_message(f"verify still has Blocking findings after {nxt.limit} rounds; manual intervention needed") # the abort report carries one line: Stopped: verify still has Blocking findings after round N (report URL) - STOP_REASON = f"verify gate: not_clean after {MAX_ROUND} rounds — {gate.in_scope} In-scope fix finding(s) remain" + STOP_REASON = f"verify gate: not_clean after {nxt.limit} rounds — {gate.in_scope} In-scope fix finding(s) remain" break # 0 Blocking: Phase 5 still opens the PR (its body says so); Phase 5c does not run # unattended: fix the rows of the verify report whose Action is Blocking @@ -1156,9 +1223,19 @@ for ROUND in 1..MAX_ROUND: attempt_auto_fix(report_rows(action="Blocking") + (report_rows(action="In-scope fix") if FIX_IN_SCOPE else [])) ``` -**`MAX_ROUND`**:unattended 2 輪 verify(中間最多修一次);attended 1 輪(讀出結果、交回使用者)。attended 的使用者在同一個 session 裡處理完 findings、說要繼續時,再跑一輪 verify(不限輪數,不自動修),乾淨了就照常進 Phase 5 與 Phase 5c;這是 attended 走到「某一輪乾淨才 merge 並 close」的路徑(spectra-discuss 結論 2,verify r3 #8)。`STOP_REASON` 不跨 Bash 呼叫存活:Phase 5 與 Phase 6 需要它時,重跑上面的 gate 區塊得到同一個結果(gate 只讀 GitHub 與 HEAD,結果可重現)。 +**輪數由 `next` 決定(#595、#591)**:沒有停止模式時,unattended 2 輪 verify(中間最多修一次)、attended 1 輪(讀出結果、交回使用者),與 #595 之前相同;輪數從 run-state 的紀錄讀(gate 每判一個新的 commit、或同一個 commit 上的新報告算一輪;報告沒貼出、讀不出,或修正沒有產生 commit,也算),所以 compaction 之後也不會被超過,close stage 也會擋下紀錄超過 2 輪的無人值守 run,以及 Phase 4 從沒判過的報告。`next` 的回答沒有 `round` 或 `limit` 時(沒有 run-state,例如 Step 0.7 的 init 失敗),當成已到上限。attended 的使用者在同一個 session 裡處理完 findings、說要繼續時,再跑一輪 verify(不限輪數,不自動修),乾淨了就照常進 Phase 5 與 Phase 5c;這是 attended 走到「某一輪乾淨才 merge 並 close」的路徑(spectra-discuss 結論 2,verify r3 #8)。 + +**停止模式(#595)**:設了模式時(Step 0.2 的 `→ Stop mode:` 不是 `none`),attended 與 unattended 都照 `next` 自動修、自動再驗;安全漏洞仍不自動修。to-fix count 是 Blocking 加上 LOW/INFO/P3 以外的 In-scope fix(`--review`、`--in-chain` 只數 Blocking)。判定表(`scripts/lib/stopmode.py`,規格 `idd-pr-hitl-modes` 的「A configured stop mode decides when the fix loop stops and whether the run merges」): + +| 模式 | 什麼時候停 | 停下時合併嗎 | +|---|---|---| +| `early` | to-fix count 是 0,或從第 2 輪起沒有比上一輪少 | Blocking 是 0 才合併 | +| `exhaustive-blocking` | Blocking 是 0;或最近兩輪 Blocking 都沒有比前一輪少 | Blocking 是 0 才合併 | +| `exhaustive-all` | Blocking 與 In-scope fix(含 LOW)都是 0;沒有輪數上限 | 合併 | + +每種模式在 gate 讀不出報告、或報告有 Rejected finding 時都停、不合併。停下時合併的是最後一輪審過的 commit,剩下的 In-scope fix 合成一張 follow-up issue,不再為它們改 branch;剩下的列裡有安全漏洞就 abort。這種合併跟乾淨的合併過同樣的 guardrail:覆蓋率行完整、reviewers 行完整、沒有降級、沒有嚴重的 Follow-up。`--review`、`--in-chain` 與 meeting 一樣從不合併。`STOP_REASON` 不跨 Bash 呼叫存活:Phase 5 與 Phase 6 需要它時,重跑上面的 gate 區塊得到同一個結果(gate 只讀 GitHub 與 HEAD,結果可重現)。 -**Auto-fix 策略**(unattended only — best-effort): +**Auto-fix 策略**(unattended,以及設了停止模式的 attended run — best-effort): 對每個要修的 finding(verify 報告 Findings 表裡 Action 為 Blocking,`FIX_IN_SCOPE` 時加上 In-scope fix 的列),讀其描述 + suggested action,套用 Edit/Write 修正: @@ -1260,7 +1337,13 @@ elif [ "$PATH_AXIS" = "PR" ]; then VERIFY_STATE=$(printf '%s' "$GATE_OUT" | jq -r '.status // "unparseable"') # A Rejected finding is a disagreement no person has settled: the close stage stops on it, so the body must not promise a merge [ "$VERIFY_STATE" = clean ] && [ "$(printf '%s' "$GATE_OUT" | jq -r '.rejected // 0')" != 0 ] && VERIFY_STATE="clean, with Rejected findings" - if [ "$VERIFY_STATE" != clean ]; then + # #595: with a stop mode, next decides whether this round merges, also when the gate is not clean + NEXT_OUT=$(python3 "${CLAUDE_PLUGIN_ROOT}/scripts/close-stage.py" next --cwd "$CWD" --repo "$GITHUB_REPO" --issue "$N" 2>/dev/null) + STOP_MODE_RUN=$(printf '%s' "$NEXT_OUT" | jq -r '.mode // "none"' 2>/dev/null || echo none) + STOP_MERGE=$(printf '%s' "$NEXT_OUT" | jq -r 'if .merge == true then "yes" else "no" end' 2>/dev/null || echo no) + if [ "$STOP_MODE_RUN" != none ] && [ "$STOP_MERGE" = yes ] && [ "$VERIFY_STATE" != clean ] && [ "$RUN_REVIEW" = no ]; then + VERIFY_BOX="[x]"; VERIFY_LINE="Verify gate: ${VERIFY_STATE}, and stop mode ${STOP_MODE_RUN} stops here with a merge (see the latest verify report on issue #${N}). /idd-all merges this PR next if CI and the close-stage guardrails pass; the findings left are listed in a follow-up issue." + elif [ "$VERIFY_STATE" != clean ]; then VERIFY_BOX="[ ]"; VERIFY_LINE="Verify gate: ${VERIFY_STATE} (see the latest verify report on issue #${N}). /idd-all will not merge this PR; a person decides." elif [ "$RUN_REVIEW" != no ]; then # --review, or the run state cannot be read: a person merges VERIFY_BOX="[x]"; VERIFY_LINE="Verify gate clean — ready to merge → after merge, run /idd-close to finalize this issue (this run carries --review: no automatic merge)." @@ -1328,7 +1411,7 @@ fi ### Phase 5c: Close stage — merge(或 push)並 `/idd-close`(#392) -verify 乾淨就收尾:PR mode squash-merge PR,direct-commit mode 在預設 branch 上 push,然後以 `ORCHESTRATED BY /idd-all` 指示呼叫 `/idd-close`。**不先問人**:merge 可以 revert、close 可以 reopen,依 Foresay 屬於 traceable 分支——做完必須在 Phase 6 回報實際做了什麼、怎麼復原(MANIFESTO〈auto-merge 的合法性與限制〉)。`/idd-all` 這個呼叫本身就是要它做完的請求;想先看過再 merge 的人帶 `--review`。 +verify 乾淨(有停止模式時:`next` 對最後一輪回 stop 並 merge,#595)就收尾:PR mode squash-merge PR,direct-commit mode 在預設 branch 上 push,然後以 `ORCHESTRATED BY /idd-all` 指示呼叫 `/idd-close`。**不先問人**:merge 可以 revert、close 可以 reopen,依 Foresay 屬於 traceable 分支——做完必須在 Phase 6 回報實際做了什麼、怎麼復原(MANIFESTO〈auto-merge 的合法性與限制〉)。`/idd-all` 這個呼叫本身就是要它做完的請求;想先看過再 merge 的人帶 `--review`。 **所有檢查與 merge/push 都在 `scripts/close-stage.py run` 這一個 process 裡**。檢查不能放在 skill 的 bash 區塊:每個區塊是一次獨立的 tool call,一個區塊判了 `Stopped` 再 `exit 0`,擋不住下一個區塊的 `gh pr merge`(#383 r2 #12,#392 verify r1 #9);shell 變數也不跨呼叫存活。helper 需要的值從 Step 0.7 寫下的 run-state 檔與 GitHub 讀,不從模型的記憶讀。 @@ -1343,7 +1426,7 @@ verify 乾淨就收尾:PR mode squash-merge PR,direct-commit mode 在預設 | issue 的作者或最後編輯正文的人沒有寫入權限 | helper | 停在 verified:issue 正文是 implement 照著做、verify 照著驗的規格,沒有人 merge 時它必須出自本來就能推這個改動的人 | | 意圖沒有確認過,封閉列舉,只有這四種:(1) 有 comment 出自沒有寫入權限的人(bot 除外);(2) issue 正文有還沒回答的釐清問題:任何一張表的 `Status` 欄以 `surfaced` 或 `deferred` 開頭的列,不論它在哪個標題下、是否收在 `
` 或引用裡,GitHub 沒畫成表格的那種列也算;(3) Phase 2 據以分派的那則 Diagnosis(最新一則有 `## Diagnosis` 行的受信任 comment)讀不出 tier;(4) 任何一則 comment 有 Layer V 延後或 choice-first 預設的紀錄(GitHub 顯示的 `- **Reason**:` 行),而之後沒有 Decision comment 回應它。**不在此列**(2026-11-10 的決定,#392 comment 6761657951、6761899504):tier 是哪一個(unattended run 做了 Plan、Spectra 或 SDD-warranted 的 issue 照樣 merge);沒有人處理的 Proposed Corrections(不擋,數量在結果的 `proposed_corrections`,回報裡寫明沒有套用) | helper | 停在 verified、PR 照開。Foresay 的 traceable 分支要求意圖清楚**且**可逆;unattended run 會自己略過意圖確認,comment 與附件也會帶進實作(#392 決定,comment 6566557673、6567272352)。unattended diagnose 自己做的 Stage 1 策略確認算是一次注意、不算略過(comment 6568180861:「ai的attention也算attention,只是人類的更稀少」) | | 這次 run 開始之後有別人插手:不是這個帳號、也不是 bot 的人在 issue 上留言或改了 comment、改了 issue 正文、加或拿掉 label、改標題、關掉或重開 issue,或刪了任何不是這個帳號的 comment;issue 已經不是 OPEN;PR 不是這個帳號開的、是 draft、changes requested,或有別人的 comment、review、label、標題或描述修改;這些紀錄多到一次讀不完 | helper | 停在 verified。run 開始時讀過的 issue 才是它照著做的意圖,之後進來的話它沒讀過(verify r4 #4、#15、#48;r5 #2、#6、#16、#33)。同事貼的 verify FAIL 也在這一列 | -| Phase 4 留下 `STOP_REASON` | helper 的 guardrail 1 再判一次 gate | `Stopped: guardrail 1 (verify gate) …` | +| Phase 4 留下 `STOP_REASON` | helper 的 guardrail 1 再判一次 gate(有停止模式時再問一次判定表) | `Stopped: guardrail 1 (verify gate) …` 或 `Stopped: guardrail 1 (stop mode ) …` | | Phase 4 或 Phase 5 已 abort | — | 照 abort 職責處理(見 Failure Modes) | 即使模型漏看上表直接呼叫 helper,前八種也會被 helper 自己擋下。 @@ -1362,9 +1445,9 @@ helper 依序檢查,第一道不過就停,印一行 JSON(`"status": "stopp | 道 | 檢查 | 過的條件 | |---|---|---| -| 0 | run 本身 | run-state 存在、是這個 repo 與 issue、不超過 24 小時;沒有 `--review`/`--in-chain`;沒有被降級;這個帳號對 repo 有 WRITE 以上的權限;clone 的 `origin` 的每個 fetch 與 push URL 都是 `github.com/`;最新受信任 Diagnosis 不是 meeting;issue 的作者與最後編輯者都有寫入權限;沒有別人插手、意圖確認過(上表「別人插手」與「意圖」兩列) | +| 0 | run 本身 | run-state 存在、是這個 repo 與 issue、不超過 24 小時(有停止模式時從最後一輪 verify 算起,#595);沒有 `--review`/`--in-chain`;沒有被降級;這個帳號對 repo 有 WRITE 以上的權限;clone 的 `origin` 的每個 fetch 與 push URL 都是 `github.com/`;最新受信任 Diagnosis 不是 meeting;issue 的作者與最後編輯者都有寫入權限;沒有別人插手、意圖確認過(上表「別人插手」與「意圖」兩列) | | 發佈 | 預設 branch 最新的 workflow | 沒有任何 workflow 在 push 到預設 branch(或 `workflow_run`)時發佈或部署(`gh release`、`npm publish`、`docker push`、`deploy-pages`、名稱帶 publish 或 deploy 的 action 之類,含它呼叫的本地 reusable workflow、composite action 與 `run:` 呼叫的本機 script);呼叫別的 repo 的 reusable workflow 一律當成會發佈;只由 tag 觸發的不算。trigger 讀不懂(加引號的鍵、list 寫法以外的形式、否定或方括號的 branch pattern)就當成會在 push 時跑(`scripts/lib/workflows.py`,r5 #1)。有的話,merge 或 push 本身就是發版,停下要人帶 `--review`。這次改動動到 `.github/workflows` 或 `.github/actions` 也停下:改 CI 的改動由人 merge | -| 1 | verify gate | 這次 run 開始之後、這個帳號貼的最新 verify comment 是 `## Verify: #N` 報告,貼出後沒有被編輯、沒有被藏起來,它的渲染結果經 `verify-gate.py --expect-sha --expect-base` 判定 `clean`(含完整的覆蓋率行),`**Reviewed**` 的範圍正好是要 merge(`merge-base(origin/, PR head)..PR head`)或要 push(`origin/..HEAD`)的那一段;報告裡沒有 `Rejected` 的 finding(被 run 自己判為不成立的意見,r4 #7)、沒有 Severity 是 CRITICAL/HIGH/P0/P1 的 Follow-up(嚴重的意見被歸為範圍外,r5 #4)、verify 沒有降級跑(報告任何地方都沒有 `Process Gaps` 字樣,reviewers 行是 `R / T` 且 R 等於 T;r5 #22、r7 #11、#14)。In-scope fix 只剩 LOW/INFO/P3 仍算 `clean`(`low_in_scope`) | +| 1 | verify gate | 這次 run 開始之後、這個帳號貼的最新 verify comment 是 `## Verify: #N` 報告,貼出後沒有被編輯、沒有被藏起來,它的渲染結果經 `verify-gate.py --expect-sha --expect-base` 判定 `clean`(含完整的覆蓋率行),`**Reviewed**` 的範圍正好是要 merge(`merge-base(origin/, PR head)..PR head`)或要 push(`origin/..HEAD`)的那一段;報告裡沒有 `Rejected` 的 finding(被 run 自己判為不成立的意見,r4 #7)、沒有 Severity 是 CRITICAL/HIGH/P0/P1 的 Follow-up(嚴重的意見被歸為範圍外,r5 #4)、verify 沒有降級跑(報告任何地方都沒有 `Process Gaps` 字樣,reviewers 行是 `R / T` 且 R 等於 T;r5 #22、r7 #11、#14)。In-scope fix 只剩 LOW/INFO/P3 仍算 `clean`(`low_in_scope`)。沒有停止模式時(#591),無人值守 run 記到的 verify 輪數(`attempts`:每個新的 commit 或同一個 commit 上的新報告算一輪)超過 2 也停,最新的報告不在 round 紀錄裡(Phase 4 沒判過)也停。**有停止模式時(#595)**不要求 `clean`:最新的報告必須就是 round 紀錄最後一筆(同一則 comment、同一個 commit),判定表對它回 stop 並 merge;覆蓋率行與 reviewers 行要完整,Rejected、嚴重的 Follow-up、降級照樣擋 | | 2 | CI | helper 在同一個 process 裡跑本機 CI 閘門 `idd-ci-gate.sh run --commit `(capability `local-ci-gate`,#465),照結束碼:**0**(pass)就過,PR 的遠端 check 在 merge 前讀一次、不等待,失敗或取消的列在結果的 `remote_ci_failed`、還在跑的列在 `remote_ci_pending`,都不擋 merge;**10**(`ci.mode` 是 `remote`)才照遠端 check 判定:`gh pr checks` 的每一項都是 `pass` 或 `skipping`,`pending` 時等待、總共最多 15 分鐘,`fail`、`cancel` 即停,repo 有一個對每個 `pull_request` 都會跑的 workflow(沒有 path 篩選)時要等到至少一個 `pull_request` 事件的 check 出現,check 的集合連續 90 秒沒有變化才接受;**其他結束碼**(1 fail、2 timeout、3 沒設定指令、4 error,或清單外的值)即停。direct-commit 推送前也跑這一道,10 時沒有遠端結果可看(commit 還沒推),照舊直接推 | | 3 | auto-close trap 與 commit 歸屬(PR) | 同 `idd-verify` Step 0.8 的兩個 source(idd-all 以 branch 模式呼叫 verify,Step 0.8 沒有跑):PR body 沒有 closing reference;每個 commit(從本機 git 讀完整範圍,`gh pr view --json commits` 有筆數上限)的 subject 與 body 沒有 close 類關鍵字接在 `#N`、`owner/repo#N` 或 issue/PR 網址前,而且都引用 `#N`(不是這次 run 的 commit 不 squash 進預設 branch,r5 #23)。連字號不豁免:GitHub 會把 `/idd-close #N` 拆開並關掉 issue(#173) | | 4 | squash message(PR) | subject(PR 標題加 `(#PR)`)與 body(`Refs #N` 加 verify 報告連結)同樣掃一次;標題來自 issue,外人寫得到 | @@ -1472,6 +1555,8 @@ Done: distribution sync: ${done | asked: | skipped — run | n/a} verify: ${ENGINE line of the verify report}; degraded: ${missing reviewers or "none"} left open: ${LOW} LOW in-scope finding(s) not fixed — listed in #${LOW_FOLLOWUP} (only when low_in_scope > 0) + stop mode: ${MODE} — ${K} round(s), to-fix ${COUNTS}; stopped because ${NEXT_REASON} (only with a stop mode; COUNTS like "6 → 4 → 4") + left open: ${F} in-scope finding(s) not fixed (stop mode) — listed in #${STOP_FOLLOWUP} (only when a stop-mode merge left findings) left open: ${PC} comment(s) list Proposed Corrections that were not applied (only when proposed_corrections > 0) remote CI: ${failed check names} failed while local CI passed (only when remote_ci_failed is not empty; "not readable" → say the remote checks could not be read; list remote_ci_pending as still running) Undo: @@ -1483,7 +1568,7 @@ Undo: merge 與 push 的欄位取自 `$CWD/.claude/.idd/state/idd-all-result-$N.json`(`pr`、`merge_sha`、`push_from`、`push_to`、`count`、`verify_url`,以及只在不是 0 或空的時候才列的 `low_in_scope`、`proposed_corrections`、`remote_ci_failed`、`remote_ci_pending`);closing summary 連結取自 5c.3 `confirm-close` 印出的 `summary_url`;follow-up 取自 Phase 4 開的 issue 加上 `/idd-close` 列出的;residue、distribution sync 取自 `/idd-close` 列出的預設。`changed` 取自 `git diff --shortstat ${MERGE_SHA}^ ${MERGE_SHA}`(direct-commit:`${PUSH_FROM} ${PUSH_TO}`);`verify` 照抄 verify 報告的 `### Engine` 那一行。Spectra tier 的 change 在 Step 3b.6 已經封存在 branch 上,merge 之後不需要再封存(#480)。 -停下時(gate 不乾淨、guardrail 沒過、push 被拒、`/idd-close` 停下、Phase 4 在最後一輪仍有 Blocking 而 abort),`Done:` 只列實際做到的步驟,接著一行 `Stopped:`,原因照抄 Phase 4 或 Phase 5c 印出的那一行: +停下時(gate 不乾淨、guardrail 沒過、push 被拒、`/idd-close` 停下、Phase 4 在最後一輪仍有 Blocking 而 abort、停止模式停下而不合併),`Done:` 只列實際做到的步驟,接著一行 `Stopped:`,原因照抄 Phase 4 或 Phase 5c 印出的那一行;有停止模式時另加上面那行 `stop mode:`: ``` ✓ idd-all #${N} — ${TITLE} (stopped) @@ -1666,7 +1751,8 @@ fi | spectra-propose 沒 emit `Change:` line | 同上 | | spectra-propose 遇到 unrecoverable validation error | Phase 3b abort,artifacts 保留,提示手動 `/spectra-propose` | | spectra-apply 留下 unfinished tasks | 不 abort — Phase 4 verify 會抓出來 | -| Verify 2 round 後仍 blocking | Phase 4 abort,留 branch 給 user 手動修 | +| Verify 2 round 後仍 blocking(沒有停止模式) | Phase 4 abort,留 branch 給 user 手動修 | +| 停止模式停下而不合併(#595) | 開 PR、寫明 `next` 的原因,Phase 5c 不 merge | | `gh pr create` fail | Phase 5 abort,branch 已 push,提示手動開 PR | | verify gate `unparseable`(報告讀不出來、沒有新報告、判定與表格矛盾) | 不修、不 merge、不 close;停在 verified,Phase 6 `Stopped:` 寫出 gate 的 reason(#392) | | Phase 5c 任一道 guardrail 沒過(CI 失敗或 15 分鐘仍 pending、auto-close trap、squash message) | 不 merge;PR 保留,Phase 6 `Stopped:` 寫出是哪一道與原因(#392) |