test(academic): extract auto-iterate loop state machine to bin/ + tests

[kiki830621]

摘要

回應「多輪 apply-fix、focus-rotation、git-commit-per-round 這些 LLM 驅動的編排邏輯要怎麼測」—— 答案是：把迴圈拆層後它們大多不是 LLM 邏輯。Phase 5b 的 --auto-iterate 主迴圈約 80% 是確定性膠水（halt 判定、mode 交替、focus-rotation heuristic、commit），只有 apply_fixes 那一次 Edit 是真非確定。本 PR 把確定性核心抽成兩個 shipped script + 26 個新測試（Functional Core, Imperative Shell），未測表面縮到只剩 apply_fixes（eval 範疇）。

新增

檔案	內容	測試
bin/pai-iterate-decide（node，JSON in/out）	主迴圈轉移函式（純狀態機）：給定 {round, maxRounds, verdict, convergeOn, currentFocus, focusHistory, focusPool} → {halt, reason, applyFixes, nextRound, nextMode, nextFocus, rotated}	17 node
bin/pai-iter-commit（bash）	per-round checkpoint commit：標準 iter-N: 訊息 + 空輪防護（無變更不留空 commit）	9 bats

academic SKILL.md Phase 5b 主迴圈改寫成委派這兩個 script —— 迴圈剩「跑一輪 ensemble → parse verdict → 問 decider → （若 applyFixes）apply + commit → 依 decider 前進」，唯一非確定步驟是 apply_fixes。

測試涵蓋的語意（窮舉自 SKILL.md 原 pseudo-code）

• halt 兩態：verdict==convergeOn → converged（不套 fix）；nextRound > maxRounds → max-rounds（本輪 fix 照套 —— 原迴圈 break 只在 converge，這個微妙語意現在被測試鎖死）
• CONVERGED ≠ PERMANENT_CONVERGENCE（前者預設不 halt）；自訂 --converge-on 生效
• mode 奇偶：奇數輪 independent、偶數輪 hybrid
• focus-rotation：剛好末 3 筆「同 focus 且皆 CONVERGED」才輪替；2 筆／focus 不一致／含 NEEDS_ITER 都不輪替；pool 繞回（boundary-cases → method-section）；自訂 focus 不在 pool → 落 pool[0]；自訂 focusPool 生效
• max-rounds clamp [1,30]（0 → 1、1000 → 30，對齊 SKILL 的 --max-rounds clamp）
• commit：有變更才 commit、untracked 被 add -A 納入、空輪跳過不留空 commit、round 驗證（0/leading-zero/非數字/11 位溢位）、非 repo → exit 1
• 非法 round / 非法 JSON → exit 2

測試哲學（已寫進 test/README.md）

1. 抽 decider/parser 純函式 → 窮舉單元測（本 PR + pai-parse-verdict + pai-build-diff）
2. Mock 模型 seam → 測接線不測模型（ensemble-workflow.test.mjs）
3. Fixture 測 side-effect → 拋棄式 git repo 斷言 commit graph（本 PR 的 pai-iter-commit.bats）
4. 模型判斷品質 → eval / invariant assertion 範疇，不進每次 push 的 CI

驗證

$ ./test/run.sh
shellcheck(3) ✓ | py_compile ✓ | bats 59/59 ✓ | node 8/8 + 17/17 ✓

版本

2.15.0 → 2.16.0（plugin.json + marketplace.json 同步）。CHANGELOG 已補 [2.16.0]。

覆蓋現況（本 PR 後）

Surface	測試
diff 建構 pai-build-diff	bats 25
共用 harness ensemble-workflow.js	node 8
compose CSV pai-parse-lens-csv	bats 14
academic verdict pai-parse-verdict	bats 11
auto-iterate 狀態機 pai-iterate-decide	node 17
per-round commit pai-iter-commit	bats 9

唯一仍未單元測的：apply_fixes（真 LLM Edit）—— 屬 eval 範疇。