@kylecheng3146/agent-ops 0.3.3 → 0.3.5

package/docs/en/guides/configuration.md

@@ -92,6 +92,18 @@ would consume the following flag instead. It deliberately does not pass
 `--dangerously-skip-permissions`, which overrides the permission boundary, or
 `--disable-slash-commands`, which disables plan-mode behavior.
 
+Agy can end its one `--print` turn without answering: print mode has nobody to
+confirm a tool call, so it refuses the call and the turn stops with an empty
+`response` and no `structured_output`. The refused tools are listed in the
+envelope's `denied_actions` and named in the diagnostic. agent-ops first resumes
+that same conversation once (`--conversation`) and asks for the answer without
+tools, then falls back to one fresh session. The lost turn's `agy.log` and
+`stdout.json` are kept under `.agent-ops/reviews/lost-turns/<sessionId>/`
+(local, git-ignored, never cleaned up automatically). If the denied tool is an
+MCP tool from your own agy configuration, disabling that server for agy
+(`agy mcp disable <name>`) removes the trigger; agent-ops does not change your
+agy configuration.
+
 Host network or loopback restrictions return `REVIEW_NOT_RUN` before any
 reviewer is started. The managed instructions require a trusted outer host
 runner to start the exact same command with both capabilities on its first
@@ -164,9 +176,15 @@ evidence. Give each editing conversation its own worktree instead:
   fails, the denial says why and falls back to the manual `worktree add`.
   Run `agent-ops update` once so the PreToolUse hook gets the 600-second
   timeout setup needs.
-- `add` creates `.worktrees/<name>` on branch `agent-ops/<name>` from the main
-  checkout's HEAD and excludes `/.worktrees/` through `.git/info/exclude`,
-  never `.gitignore`. It copies the ignored files agent-ops installed and any
+- `add` creates `.worktrees/<name>` on branch `agent-ops/<name>` and excludes
+  `/.worktrees/` through `.git/info/exclude`, never `.gitignore`. Its base and
+  its merge target are the branch the main checkout was on when the session
+  began: SessionStart records that branch once per session (resume, compact and
+  clear never overwrite it; nothing is recorded on a detached HEAD or from
+  inside a worktree), so switching branches mid-session does not retarget the
+  work. Without a record it reads the main checkout's HEAD at add time, an
+  explicit `--target-branch` or `--from` outranks the record, and a recorded
+  branch that no longer exists is an error naming `--target-branch`. It copies the ignored files agent-ops installed and any
   file matched by a root `.worktreeinclude` (gitignore syntax, for example
   `.env` or `local.properties`); a file Git already checked out is never
   overwritten. Trust is inherited only when the main checkout is trusted and
@@ -188,7 +206,11 @@ evidence. Give each editing conversation its own worktree instead:
   each task keeps its own review record, so a parent and a subtask reviewed
   on the same source do not overwrite each other.
 - `agent-ops worktree finish <name>` merges by fast-forward only, one finish
-  at a time. If the target moved, it rebases; a clean rebase whose own patch
+  at a time. When the main checkout is on the target branch the merge updates
+  its files, so uncommitted changes there block it. When the main checkout is
+  on another branch or detached, only the target's ref moves: the checkout, its
+  files and its uncommitted changes are left alone. A target checked out in
+  another worktree is refused, naming that path. If the target moved, it rebases; a clean rebase whose own patch
   is unchanged is re-verified before merging, and a conflict is reported with
   the `refs/notes/agent-ops` intent of the work that landed first. The note
   records every task of the worktree, subtasks indented under their parent.

package/docs/en/spec/acceptance-and-evidence.md

@@ -33,10 +33,14 @@ The verifier MUST return FAIL when a criterion is missing, duplicated, unknown,
 - Every criterion needs at least one required verifier and current PASS evidence for every required verifier it names. Verify always includes those task-required commands, even when path mappings select a narrower set. Supply the evidence file references produced by `agent-ops verify --task <id>`, not command strings or a written assertion of PASS.
 - The task's config baseline and evidence must match the current effective config and source fingerprint in the selected scope. Outstanding verification failures block completion. A newer failing result cannot be replaced by an older PASS; contradictory results at the same timestamp fail closed.
 - Run `agent-ops review --task <id> --yes` for the whole task. Completion requires its current, task-bound PASS attestation; generic reviews and partial-criterion reviews do not satisfy it.
-- Starting an authorized review invalidates the previous attestation for that source fingerprint. If the reviewer cannot run or does not pass, run a fresh successful whole-task review before completion.
+- An unchanged task, source, criteria and config may reuse its recorded PASS review after fresh verification. Starting a fresh authorized review (`--rerun`) invalidates the previous attestation for that source fingerprint. If the reviewer cannot run or does not pass, run a fresh successful whole-task review before completion.
 - All subtasks and descendants must have completed without an outstanding failure. Archiving unfinished work does not satisfy this requirement. A completed or archived parent cannot accept new subtasks. If a subtask is abandoned, recreate the parent task without that cancelled branch and verify/review the new task tree.
 - Evidence, source and config validation run outside the task store lock. After rechecking source and config, completion briefly locks state, rejects a changed task snapshot (`TASK_COMPLETION_STATE_CHANGED`), rechecks descendants, and writes completion atomically. Slow validation does not block task reads or other task mutations; a concurrent mutation remains intact when completion is rejected.
 
+`test-count.minimum` counts explicitly passed tests, excluding skipped, todo, expected failures and discovery totals. Zero passed tests fail even with minimum zero; an unrecognizable passed summary is UNKNOWN. Explicit failed, error or cancelled outcomes fail even when the process exits zero. Exit-code verifiers retain their existing behavior. Task verify returns `VERIFICATION_UNKNOWN`, names uncovered criteria and runs no verifier commands when any criterion lacks a required verifier; optional-only results cannot establish formal task verification.
+
+New verification evidence uses schema 3. Schema 2 remains readable and its exit-code evidence remains valid; schema 2 test-count evidence cannot establish PASS and requires fresh verification. Old references are retained. A completed task may append fresh verification only for its original source, criteria and config, preserving completedAt and review references. Its entire state snapshot is compared atomically before appending and clearing failure; concurrent changes are preserved and rejected. Fresh FAIL or UNKNOWN blocks completion until resolved; archived tasks remain immutable. Source or config changes require a new task.
+
 Existing task files remain readable without migration. Legacy tasks without a config baseline, arbitrary evidence references, or unfinished archived children must be recreated and verified/reviewed before completion. Repeating completion also revalidates the evidence; an old completed status alone is insufficient. Runtime callers must supply `TaskServiceOptions.completion`; omitting this repository context fails closed for completion while leaving read-only task operations available.
 
 Before committing, use the default worktree scope for verify, review and completion. After committing, use the same `--base <git-ref>` on all three commands to produce fresh proof for that committed range; `TaskServiceOptions.completion.base` selects it for runtime callers. Base mode requires a clean worktree. Without a worktree change surface or an explicit base, completion returns `TASK_COMPLETION_SCOPE_REQUIRED`. The agy Stop gate still checks worktree-scoped proof: complete and stop before committing, or use its user-approved one-time permit after inspecting a completed base-scoped task.

package/docs/en/spec/delegation.md

@@ -35,7 +35,7 @@ Concurrent delegated writers MUST NOT share one working tree.
 Parallel editing conversations in one repository MUST each work in their own agent-ops worktree.
 
 - Trigger: `worktree.mode` is `auto`, or a second conversation will edit the repository while another is still open.
-- Action: Run `agent-ops worktree add <name> --session <id>` from the main checkout before the first edit, work only in the printed path, and merge with `agent-ops worktree finish <name>` after the task completes against the printed `--base`.
+- Action: Run `agent-ops worktree add <name> --session <id>` from the main checkout before the first edit, work only in the printed path, and merge with `agent-ops worktree finish <name>` after the task completes against the printed `--base`. The merge lands on the branch the main checkout was on when the session began, wherever that checkout is now.
 - Evidence: `agent-ops worktree list` shows one worktree per editing session, and each finish reports a fast-forward merge.
 - Positive: `Two conversations edit .worktrees/login and .worktrees/cart; each verifies, reviews and finishes on its own.`
 - Negative: `Two conversations edit the main checkout at once, so each one's verification and review is voided by the other's writes.`

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

@@ -81,6 +81,15 @@ Agy 的 prompt 會直接作為 `--print` 的值；裸用 `-p` 會誤吞下一個
 agent-ops 刻意不傳會繞過權限邊界的 `--dangerously-skip-permissions`，也不傳會
 使 plan mode 失效的 `--disable-slash-commands`。
 
+Agy 可能在唯一一輪 `--print` 中沒有回答就結束：print mode 沒有人可以確認工具呼叫，
+會拒絕該次呼叫並停止，`response` 為空且沒有 `structured_output`。被拒的工具列在
+信封的 `denied_actions`，並寫進診斷訊息。agent-ops 會先在同一個對話續問一次
+（`--conversation`，要求不用工具直接回答），失敗才退回一個全新的 session。lost turn 的
+`agy.log` 與 `stdout.json` 會保留在 `.agent-ops/reviews/lost-turns/<sessionId>/`
+（僅本機、被 git 忽略、不會自動清理）。若被拒的是你自己 agy 設定的 MCP 工具，
+對 agy 停用該 server（`agy mcp disable <name>`）即可移除觸發原因；agent-ops 不會
+更動你的 agy 設定。
+
 Host 缺少 network 或 loopback 權限時，會在啟動任何 reviewer 前回傳
 `REVIEW_NOT_RUN`。Managed 規則要求可信任的外部 host runner 在第一次呼叫時
 就用兩項權限啟動同一個完整指令；不要先在原 sandbox 執行再重試，因為那不算
@@ -145,9 +154,13 @@ fingerprint，因此兩個對話修改同一個 checkout 會互相作廢對方
   則作為每條命令的工作目錄）；同一 session 之後被拒絕時會重用它。
   建立失敗時，拒絕訊息會說明原因並退回手動 `worktree add`。需先執行一次
   `agent-ops update`，讓 PreToolUse hook 取得 setup 所需的 600 秒逾時。
-- `add` 從主 checkout 的 HEAD 建立 `.worktrees/<name>` 與 branch
-  `agent-ops/<name>`，並透過 `.git/info/exclude`（而非 `.gitignore`）排除
-  `/.worktrees/`。它會複製 agent-ops 安裝的 ignored 檔案，以及根目錄
+- `add` 建立 `.worktrees/<name>` 與 branch `agent-ops/<name>`，並透過
+  `.git/info/exclude`（而非 `.gitignore`）排除 `/.worktrees/`。它的 base 與合併
+  目標是 session 開始時主 checkout 所在的 branch：SessionStart 會為每個 session
+  記錄該 branch 一次（resume、compact、clear 都不會覆寫；detached HEAD 或在
+  worktree 內觸發時不記錄），所以中途切換 branch 不會改變工作的目標。沒有記錄時
+  會在 add 當下讀取主 checkout 的 HEAD；明確的 `--target-branch` 或 `--from`
+  優先於記錄；記錄的 branch 已不存在時會報錯，並提示使用 `--target-branch`。它會複製 agent-ops 安裝的 ignored 檔案，以及根目錄
   `.worktreeinclude`（gitignore 語法，例如 `.env` 或 `local.properties`）比對到
   的檔案；Git 已 checkout 的檔案一律不覆寫。只有主 checkout 已 trusted 且
   worktree 的 effective config 完全相同時才繼承 trust。
@@ -165,7 +178,10 @@ fingerprint，因此兩個對話修改同一個 checkout 會互相作廢對方
   維持附著在 task 樹最上層，且每個 task 各自保留 review 紀錄，所以在同一份原始碼上
   review 的 parent 與 subtask 不會互相覆蓋。
 - `agent-ops worktree finish <name>` 只以 fast-forward 合併，一次只執行一個
-  finish。Target 若已前進會先 rebase；沒有衝突且自身 patch 不變的 rebase 會先
+  finish。主 checkout 就在 target branch 上時，合併會更新它的檔案，所以那裡有未
+  commit 的變更會擋住合併；主 checkout 在其他 branch 或 detached 時，只移動
+  target 的 ref，checkout、檔案與未 commit 的變更都不會被動到。Target 若被其他
+  worktree checkout 則拒絕，並指出該路徑。Target 若已前進會先 rebase；沒有衝突且自身 patch 不變的 rebase 會先
   重新驗證再合併；衝突則連同先合併那份工作在 `refs/notes/agent-ops` 的意圖一起
   回報。Note 會記錄 worktree 的每個 task，subtask 縮排在其 parent 之下。
 - `worktree list`、`resume <name> --session <id>` 與 `remove <name>` 管理剩下的

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

@@ -1,6 +1,6 @@
 # 驗收與證據
 
-English source version: 2026-09-07. Revalidate: when the English specification changes.
+English source version: 2026-09-27. Revalidate: when the English specification changes.
 
 ## EVIDENCE-CRITERION-001
 
@@ -35,10 +35,14 @@ English source version: 2026-09-07. Revalidate: when the English specification c
 - 每項 criterion 至少需要一個 required verifier，且其列出的每個 required verifier 都要有目前有效的 PASS evidence。即使 path mapping 選出較小範圍，verify 也會包含 task 明列的 required 命令。請提供 `agent-ops verify --task <id>` 產生的證據檔參照，不能只填命令文字或自行宣稱 PASS。
 - 任務的 config baseline、evidence 必須符合目前有效設定與所選 scope 的來源指紋。尚未解決的驗證失敗會阻擋完成；舊 PASS 不能蓋過較新的失敗，同時間戳的矛盾結果也會阻擋。
 - 使用 `agent-ops review --task <id> --yes` 審查整個任務。完成時必須有目前有效且綁定該 task 的 PASS attestation；generic review 與只涵蓋部分 criterion 的 review 不算。
-- 開始一次已授權的 review 會撤銷該來源指紋先前的 attestation。若 reviewer 未能執行或未通過，完成前必須重新取得成功的全任務 review。
+- task、來源、criteria 與 config 不變時，重新驗證後可沿用原 PASS review。開始新的已授權 review（`--rerun`）才會撤銷該來源指紋先前的 attestation。若 reviewer 未能執行或未通過，完成前必須重新取得成功的全任務 review。
 - 所有子任務與後代任務都必須已完成，且沒有尚未解決的失敗。封存未完成工作不算完成；已完成或封存的 parent 不能新增子任務。若放棄某個 subtask，請重建不含該取消分支的 parent task，並重新驗證與審查新的 task tree。
 - 證據、來源與設定檢查在 task store 鎖外執行。再次確認來源與設定後，完成操作才短暫鎖住狀態，比對 task 快照（改變時回傳 `TASK_COMPLETION_STATE_CHANGED`）、重查後代任務並原子寫入。慢速檢查不會阻擋 task 讀取或其他修改；完成被拒絕時，併發修改仍會保留。
 
+`test-count.minimum` 只計明確 passed 的測試，排除 skipped、todo、預期失敗與 discovery total。零 passed 即使 minimum 為零也會 FAIL；無法辨識 passed 摘要時為 UNKNOWN。摘要有 failed、error 或 cancelled，即使 process exit code 為零也會 FAIL。exit-code verifier 保留既有行為。任一 criterion 缺少 required verifier 時，task verify 回傳 `VERIFICATION_UNKNOWN`、列出缺少 coverage 的 criterion，且不執行 verifier 命令；只有 optional 結果不能建立正式 task 的驗證 PASS。
+
+新 verification evidence 使用 schema 3。Schema 2 仍可讀取，其 exit-code 證據仍有效；schema 2 test-count 證據不能建立 PASS，必須重新驗證。舊參照會保留。Completed task 只可為原來源、criteria 與 config 追加 fresh verification，保留 completedAt 與 review 參照。追加與清除 failure 前，會原子比對完整狀態快照；併發修改保留並拒絕本次追加。Fresh FAIL 或 UNKNOWN 在修正前阻擋完成；archived task 不可修改。來源或 config 改變時必須建立新 task。
+
 既有 task 檔案仍可直接讀取，不需資料格式遷移。缺少 config baseline、使用任意文字證據，或含有未完成但已封存子任務的舊任務，必須重建並完成驗證與審查。重複執行 complete 也會重新驗證證據；舊的 completed 狀態本身不夠。Runtime 呼叫端必須提供 `TaskServiceOptions.completion`；缺少此 repository context 時，complete 會拒絕執行，但仍可讀取任務。
 
 Commit 前，verify、review、complete 使用預設 worktree scope。Commit 後，三個命令都使用相同的 `--base <git-ref>`，為已提交範圍重新產生證據；runtime 呼叫端使用 `TaskServiceOptions.completion.base`。Base 模式要求 worktree 乾淨。沒有 worktree 變更又未指定 base 時，complete 會回傳 `TASK_COMPLETION_SCOPE_REQUIRED`。agy Stop gate 仍檢查 worktree scope 的證據：請在 commit 前完成並停止，或由使用者檢查已完成的 base-scope 任務後，核准一次性的 Stop permit。

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

@@ -37,7 +37,7 @@ English source version: 2026-09-24. Revalidate: when the English specification c
 同一個 repository 中並行修改檔案的對話 MUST 各自在自己的 agent-ops worktree 中工作。
 
 - Trigger: `worktree.mode` 為 `auto`，或另一個對話仍開著時，第二個對話也要修改這個 repository。
-- Action: 第一次修改前，在主 checkout 執行 `agent-ops worktree add <name> --session <id>`，只在印出的路徑中工作；task 以印出的 `--base` 完成後，用 `agent-ops worktree finish <name>` 合併。
+- Action: 第一次修改前，在主 checkout 執行 `agent-ops worktree add <name> --session <id>`，只在印出的路徑中工作；task 以印出的 `--base` 完成後，用 `agent-ops worktree finish <name>` 合併。合併目標是 session 開始時主 checkout 所在的 branch，不論該 checkout 現在在哪裡。
 - Evidence: `agent-ops worktree list` 顯示每個修改中的 session 各有一個 worktree，且每次 finish 都回報 fast-forward 合併。
 - Positive: `兩個對話分別修改 .worktrees/login 與 .worktrees/cart；各自驗證、review 並 finish。`
 - Negative: `兩個對話同時修改主 checkout，彼此的寫入讓對方的驗證與 review 全部作廢。`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
   "license": "MIT",

package/schemas/evidence.schema.json

@@ -24,7 +24,7 @@
   ],
   "properties": {
     "schemaVersion": {
-      "const": 2
+      "enum": [2, 3]
     },
     "taskId": {
       "$ref": "#/$defs/id"