@kylecheng3146/agent-ops 0.5.2 → 0.5.3

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

@@ -228,6 +228,15 @@ fingerprint，因此兩個對話修改同一個 checkout 會互相作廢對方
   任一 task 無法完成時不會合併，錯誤訊息會指出是哪個 task。建立 subtask 時 session
   維持附著在 task 樹最上層，且每個 task 各自保留 review 紀錄，所以在同一份原始碼上
   review 的 parent 與 subtask 不會互相覆蓋。
+- 多個寫入型 subagent 各自在獨立 worktree 工作時，每個子 task 在編輯前以
+  `--intent` 記錄完整修改意圖，提交後進行局部 verify。協調者從主 checkout
+  經由與 review 相同的可信外層 host runner 執行
+  `agent-ops task advance --task <parent-id> --session <id> --yes`。
+  Advance 整合所有子 worktree 的程式與意圖，在同一候選版本重跑全部必要
+  verifier，並進行一次兩輪全樹 review。只有明確的 `NOT_RUN / scope-too-large`
+  會退回逐 task 雙輪 review；PASS 後在 `.git/agent-ops/receipts/` 保存完整
+  收據並呼叫 finish。Target 移動時最多重做一次最終門檻。仍有兄弟子 worktree
+  時，直接 finish 單一子 worktree 會被拒絕。
 - `agent-ops worktree finish <name>` 只以 fast-forward 合併，一次只執行一個
   finish。主 checkout 就在 target branch 上時，合併會更新它的檔案，所以那裡有未
   commit 的變更會擋住合併；主 checkout 在其他 branch 或 detached 時，只移動

package/docs/zh-TW/spec/acceptance-and-evidence.md

@@ -12,6 +12,16 @@ English source version: 2026-09-27. Revalidate: when the English specification c
 - Positive: `tests → npm test（354 個測試通過）`。
 - Negative: `看起來正確，所以不需要證據。`
 
+## EVIDENCE-INTENT-001
+
+每個子 worktree MUST 在編輯前記錄完整程式修改意圖。
+
+- Trigger: 子 agent 即將在自己的 worktree 編輯。
+- Action: 使用 `task create --intent <text>` 記錄使用者同意的行為、限制與整合點；協調者連同子 task 匯入意圖，並在整合候選版本重跑驗證。
+- Evidence: 子 task 與最終完成紀錄保留意圖，最終 verifier 證據綁定整合候選版本。
+- Positive: `子 agent 先記錄預定 API 修改、提交程式碼，最後完成紀錄包含該意圖與整合後驗證。`
+- Negative: `先修改程式碼，交付時才補寫一行事後意圖。`
+
 ## EVIDENCE-AGGREGATE-001
 
 驗證器 MUST 在條件缺少、重複、未知或證據為空時回傳 FAIL。

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

@@ -44,10 +44,10 @@ English source version: 2026-09-24. Revalidate: when the English specification c
 
 ## DELEGATE-ISOLATION-003
 
-同一個 session 中會寫入檔案的 subagent MUST 各自在自己的 agent-ops worktree 中工作，並各自擁有 task、驗證與 review。
+同一個 session 中會寫入檔案的 subagent MUST 各自在自己的 agent-ops worktree 中工作，並各自擁有 task、開工前修改意圖與局部驗證。
 
 - Trigger: `worktree.mode` 為 `auto`，且 subagent 寫入檔案。subagent 內的 hook 呼叫會在父對話的 `session_id` 之下帶有自己的 `agent_id`；沒有 `agent_id` 的 payload 視為該 session 的主執行緒。
-- Action: 第一次被擋下的寫入會配發一個屬於該 session 與該 agent 的 worktree；之後用絕對路徑在那裡編輯，因為 hook 的 `cwd` 不會跟著 `cd` 改變。subagent 在自己的 worktree 內 commit，並執行 `agent-ops verify` 與 `agent-ops review`。整個 repository 的所有 worktree 同時最多進行兩個 review，其餘排隊等待。協調者依序對每個 worktree 執行 `agent-ops worktree finish <name>`；只有該 session 的每個 worktree 都有已完成的 task，Stop 才會放行。
-- Evidence: `agent-ops worktree list` 為每個 subagent worktree 顯示一行 `agent:`，寫入其他 writer 的 worktree 會以 `WORKTREE_OWNED_BY_OTHER_AGENT` 被拒絕，且每次 finish 都回報 fast-forward 合併。
-- Positive: `兩個 subagent 在 .worktrees/session-ab12cd34-a9230363 與 .worktrees/session-ab12cd34-b1111111 各自實作獨立的 task；各自 review，協調者依序 finish。`
+- Action: 第一次被擋下的寫入會配發一個屬於該 session 與該 agent 的 worktree；之後用絕對路徑在那裡編輯，因為 hook 的 `cwd` 不會跟著 `cd` 改變。每個 subagent 編輯前用 `task create --intent` 記錄意圖，提交後在自己的 worktree 執行 `agent-ops verify --task`。協調者從主 checkout 執行 `agent-ops task advance --task <parent-id> --session <id> --yes`：整合子 worktree，在同一候選版本驗證所有 criteria、完成兩輪全樹 review、保存本地證據，再執行 finish。存在兄弟子 worktree 時，直接 finish 單一子 worktree 會被拒絕。
+- Evidence: `agent-ops worktree list` 為每個子 worktree 顯示 `agent:`；`.git/agent-ops/receipts/` 的最終收據保存整合後 task tree、意圖、驗證證據與 review 報告。
+- Positive: `兩個 subagent 各自提交並驗證；一次 task advance 整合兩者並完成最終證據門檻後 finish。`
 - Negative: `subagent 修改協調者的 worktree，或兩個 subagent 修改同一個 worktree，導致一次 review 涵蓋兩個 task 的變更。`

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

@@ -7,9 +7,9 @@ English source version: 2026-09-30. Revalidate: when the English specification c
 獨立審查者 MUST 只收到包含請求、條件、產物參照與證據要求的最小 packet。
 
 - Trigger: 多步驟變更到達審查 checkpoint。
-- Action: 排除實作理由、隱藏推理、原始 log 與憑證。
+- Action: 有記錄時在 request 帶入使用者同意的 task 意圖；排除隱藏推理、原始 log 與憑證。
 - Evidence: 可見 packet keys 與產物參照，且不含敏感內容。
-- Positive: `Packet 僅含條件、檔案與證據要求。`
+- Positive: `Packet 包含已記錄的 task 意圖、條件、檔案與證據要求。`
 - Negative: `轉送完整 session transcript 與環境。`
 
 ## REVIEW-RESULT-001
@@ -117,6 +117,28 @@ permission bypass。外部 host runner 不可用時，結果 MUST 保持 NOT_RUN
 - Positive: `NOT_RUN：unparseable-output；缺少一條 criterion。`
 - Negative: `因為模型的 JSON 格式錯誤就記錄一次失敗的審查。`
 
+## REVIEW-TREE-001
+
+`task advance` MUST 在呼叫 finish 前，讓同一個整合後候選版本通過 parent 與所有子 task 的 criteria。
+
+- Trigger: session 有 parent task 與一個以上由 subagent 擁有的子 worktree。
+- Action: 將各子 task 的開工前意圖及已提交程式碼匯入協調者候選 worktree。所有 task 的必要 verifier 使用相同最終 base 與 source fingerprint。執行 `review --task <parent-id> --tree --base <final-base> --yes`，把唯一化的 criteria 與意圖交給現有兩輪獨立 reviewer；每個 task 都保存指向完整全樹報告的 task-bound 證明。
+- Evidence: 最終收據包含完整 task tree、意圖、source fingerprint、驗證證據、兩份 reviewer 報告、review 模式與剩餘風險。
+- Positive: `parent 兩項、兩個子 task 各三項 criteria，在整合候選版本上由同一組兩輪 review 覆蓋全部八項。`
+- Negative: `只 review parent，就 finish 尚未在整合版本檢查 criteria 的子 worktree。`
+
+只有 `NOT_RUN / scope-too-large` 可以退回各 task 各自完整的兩輪 review。實質 FAIL、缺少驗證證據、reviewer 無法使用或其他 NOT_RUN 都阻擋 finish。Target 移動時，`task advance` 最多 rebase 並重做整套最終門檻一次。收據在目標分支移動前寫入主 checkout 的 `.git/agent-ops/receipts/` 並讀回檢查；保存失敗禁止合併。合併前晚到的 target 移動會被拒絕，以便重做最終證據。合併後清理失敗則回報為部分完成，不宣稱 finish 成功。
+
+## REVIEW-SHOW-001
+
+使用者 MUST 能從主 checkout 檢視最新候選版本已保存的兩輪 reviewer 報告，而不啟動新審查。
+
+- Trigger: 對 active 或 finished task 執行 `review show --task <id>`。
+- Action: 顯示完整、已遮蔽敏感資訊的結構化第一輪與第二輪報告，包括每項 criterion、finding、已檢查檔案與剩餘風險。全樹審查成功時只顯示一次共用報告；逐 task 退回時依 task 分組。Finished 收據必須對照 Git note digest 驗證。候選版本改變後，應明示目前版本尚未審查，不得顯示舊 verdict。失敗或未執行的輪次需明確指出缺少的報告。`task advance` 通過時摘要具體非阻擋發現與風險，失敗時顯示可取得的報告細節。
+- Evidence: 唯讀指令不呼叫 reviewer，輸出綁定 active fingerprint 或 finished 收據。
+- Positive: `finish 後從主 checkout 執行 review show，可看到最終候選版本的兩份完整報告與剩餘風險。`
+- Negative: `新增 commit 後仍將上一個候選版本的 PASS 顯示為目前結果。`
+
 ## REVIEW-BATCH-001
 
 批次審查 MUST 只涵蓋指定 parent 的 active 子 task 以及 parent 本身。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",

package/schemas/task.schema.json

@@ -15,6 +15,9 @@
     "title": {
       "$ref": "#/$defs/nonEmptyString"
     },
+    "intent": {
+      "$ref": "#/$defs/nonEmptyString"
+    },
     "parentTaskId": {
       "$ref": "#/$defs/id"
     },