@kylecheng3146/agent-ops 0.4.0 → 0.5.0

package/docs/zh-TW/guides/configuration.md

@@ -204,11 +204,14 @@ fingerprint，因此兩個對話修改同一個 checkout 會互相作廢對方
   會把較舊的 matcher 回報為註冊漂移。
 - 當 `worktree.mode` 為 auto，`init` 與 `update` 也會預先授權 session 自己會執行的
   指令，並在你確認前先列在計畫裡：在 `.claude/settings.local.json` 寫入
-  `agent-ops task`、`verify`、`review`、`worktree`、`doctor` 的 `permissions.allow`，
-  以及 `agent-ops review` 的 `sandbox.excludedCommands`（你原有的項目會保留，計畫只
-  描述該檔案而不印出內容）；若 CLI 找得到 Codex 的 home（`CODEX_HOME`，否則
-  `~/.codex`），另寫入 `rules/agent-ops.rules`，內含 `agent-ops review` 與
-  `doctor --check-auth` 的 allow 規則（含與不含 `AGENT_OPS_HOST=`）。`trust`、
+  `agent-ops task`、`verify`、`review`、`worktree`、`doctor`，加上 `EnterWorktree`
+  （hook 仍會擋下 session 不擁有的路徑）與 `npx lint-staged` 的 `permissions.allow`，
+  以及 `agent-ops review`、`batch`、`worktree commit` 與 `npx lint-staged` 的
+  `sandbox.excludedCommands`（你原有的項目會保留，計畫只描述該檔案而不印出內容）；
+  若 CLI 找得到 Codex 的 home（`CODEX_HOME`，否則 `~/.codex`），另寫入
+  `rules/agent-ops.rules`，內含 `agent-ops review` 與 `doctor --check-auth` 的 allow
+  規則（含與不含 `AGENT_OPS_HOST=`），以及 `agent-ops worktree commit` 與
+  `npx lint-staged` 的 allow 規則，讓 pre-commit hook 能寫入主 `.git`。`trust`、
   `allow-stop`、`init`、`update`、`uninstall` 永遠不會被預先授權。關閉 auto 模式或
   `uninstall` 會精確移除這些項目；同名但不是 agent-ops 寫的規則檔不會被動到。
 - `review` 與 `doctor` 支援 `--output <file>`：JSON envelope 寫入該檔（權限 0600），

package/docs/zh-TW/spec/review.md

@@ -1,6 +1,6 @@
 # 審查
 
-English source version: 2026-07-23. Revalidate: when the English specification changes.
+English source version: 2026-09-30. Revalidate: when the English specification changes.
 
 ## REVIEW-INDEPENDENT-001
 
@@ -116,3 +116,73 @@ permission bypass。外部 host runner 不可用時，結果 MUST 保持 NOT_RUN
 - Evidence: 結果的 reason 能區分協議違規與判定結果。
 - Positive: `NOT_RUN：unparseable-output；缺少一條 criterion。`
 - Negative: `因為模型的 JSON 格式錯誤就記錄一次失敗的審查。`
+
+## REVIEW-BATCH-001
+
+批次審查 MUST 只涵蓋指定 parent 的 active 子 task 以及 parent 本身。
+
+- Trigger: 執行 `batch --parent <task-id>`。
+- Action: 依建立順序選出 parent 的 active 子 task，再加上 parent。排除 archived、已完成的 task 與屬於其他 parent 的 task。未知 parent 以 `BATCH_PARENT_NOT_FOUND` 拒絕，非 active 的以 `BATCH_PARENT_NOT_ACTIVE` 拒絕。
+- Evidence: `data.tasks` 依序列出的正是這些 task id。
+- Positive: `兩個 active 子 task 與 parent 被涵蓋；archived 的子 task 不在內。`
+- Negative: `不論 parent 為何，涵蓋 worktree 內所有 task。`
+
+## REVIEW-BATCH-002
+
+每個 task 的 base MUST 依序取自明確旗標、該 task 已記錄的 review base、worktree base。
+
+- Trigger: 決定批次中某個 task 驗證與審查所用的範圍。
+- Action: 子 task 用 `--base`，parent 用 `--parent-base`；否則用該 task 已記錄的 `reviewBase`；再否則用 worktree base。都沒有時回報 `BATCH_BASE_UNKNOWN`。
+- Evidence: `data.tasks[].base` 指出每個 task 使用的 base。
+- Positive: `重跑時沿用每個已 PASS task 記錄的 base，fingerprint 與 attestation 仍然吻合。`
+- Negative: `把 --base 套到 parent，或在不知道 base 時退回 HEAD。`
+
+## REVIEW-BATCH-003
+
+驗證 MUST 一次只跑一個 task，每個 task 的審查 MUST 在它自己的驗證通過後立刻開始，同時進行的審查 MUST NOT 超過 `--width`（預設 2）。
+
+- Trigger: 批次中的 task 需要驗證與審查。
+- Action: 已有 fresh PASS evidence 的 task 略過驗證，判斷方式與 review 預檢相同。其餘串行驗證。task 驗證通過後立刻開始它的審查。驗證失敗的 task 不開審查，其他 task 繼續。
+- Evidence: `data.tasks[].verify` 為 `skipped`、`PASS` 或 `FAIL`，驗證失敗的 task 沒有 review。
+- Positive: `task A 審查的同時驗證 task B。`
+- Negative: `同時跑每個 task 的完整測試。`
+
+## REVIEW-BATCH-004
+
+暫時性的 NOT_RUN MUST 讓其餘審查的 width 降為 1 並只重試一次，其他結果 MUST 為最終結果。
+
+- Trigger: 批次中的某個審查回傳 NOT_RUN。
+- Action: 原因為 `probe-failed`、`stalled`、`timeout`、`quota-exhausted` 或 `network-unreachable` 時，讓所有尚未開始的審查 width 降為 1，並在其餘審查結束後，單獨重試該 task 一次。其他原因不重試，不重試第二次，width 也不再升回。
+- Evidence: 被重試的 task `review.retried` 為 true，第二次暫時性 NOT_RUN 仍是 NOT_RUN。
+- Positive: `task A 的 probe-failed 使 width 降為 1，A 在其他 task 之後再跑一次。`
+- Negative: `對 host-sandboxed 不斷重試直到通過。`
+
+## REVIEW-BATCH-005
+
+來源變動或程序被中斷時，批次 MUST 停止。
+
+- Trigger: HEAD 或工作樹與批次開始時不同，或程序收到 SIGINT 或 SIGTERM。
+- Action: 開始前要求工作樹乾淨，每個步驟前檢查 HEAD 與工作樹。發現變動時，中止進行中的審查，不再開始新步驟，並把每個未完成的 task 回報為 `aborted`。訊號以 130 或 143 結束。
+- Evidence: 每個未完成的 task 其 `data.tasks[].aborted` 為 true。
+- Positive: `批次進行中發生 commit 就中止，未完成的 task 標示 aborted。`
+- Negative: `讓進行中的審查對已不吻合的 HEAD 跑完。`
+
+## REVIEW-BATCH-006
+
+批次 MUST 在探測成功時對每個審查 target 最多探測一次，且 MUST NOT 快取失敗的探測。
+
+- Trigger: 批次中的審查需要 target 預檢。
+- Action: 同時進行的審查共用進行中的探測，成功的答案在批次剩餘期間保留。失敗的答案丟棄，讓 task 的重試再探測一次。
+- Evidence: 多個審查的批次每個 target 只探測一次，失敗後的重試會產生新的探測。
+- Positive: `五個審查共用一次成功的 agy 探測。`
+- Negative: `快取 probe-failed 並拒絕其餘所有 task。`
+
+## REVIEW-BATCH-007
+
+批次結果 MUST 回報每個 task 的結果，且 MUST 僅在每個 task 都通過時以 0 結束。
+
+- Trigger: 批次結束。
+- Action: 回傳 `BATCH_RESULT`、`BATCH_FAILED` 或 `BATCH_NOT_RUN`，`data.tasks[]` 含每個 task 的 id、base、驗證狀態、審查狀態與原因、`reused`、`retried` 與 `aborted`，不含完整報告（報告留在 `.agent-ops/reviews/`）。全數通過以 0 結束，任一審查或驗證失敗以 1 結束，其餘以 2 結束。`batch` 的啟動方式與 `review` 相同：需要 `--yes` 與 trust，且適用 REVIEW-HOST-001。
+- Evidence: envelope code 與 exit code 與各 task 的結果一致。
+- Positive: `一個 FAIL 與一個 NOT_RUN 以 1 結束，先處理缺陷。`
+- Negative: `仍有 task 是 NOT_RUN 卻以 0 結束。`

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
   "repository": "github:kylecheng3146/agent-ops",
   "engines": {
     "node": ">=22.14.0"