@kylecheng3146/agent-ops 0.11.1 → 0.11.3

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

@@ -208,3 +208,42 @@ Commit 前，verify、review、complete 使用預設 worktree scope。Commit 後
 這項機制強制的是 toolkit 的完成命令，無法阻止 host 直接用自然語言宣稱完成，也無法阻止具有相同檔案權限的 process 直接改寫 task／evidence 檔案；它不會鎖住 Git 或其他來源檔案寫入者。
 
 Project init/update 在所有 harness 與 profile 安裝 `.agent-ops/.gitignore`，忽略 `/tasks/` 與 `/reviews/`；若已有使用者自建的 `.agent-ops/.gitignore`，init/update 會回傳 `UNMANAGED_INSTALL_PATH`：先將原檔備份到其他位置，並將自訂規則移到根目錄 `.gitignore`（加上 `/.agent-ops/` 前綴），再重試。這些目錄若包含 index 中的檔案（即使 tracked 且未修改）或 staged 的 runtime 刪除，Git 範圍收集會回傳 `CHANGE_SURFACE_TRACKED_RUNTIME`。請先移出真正的程式來源、安裝 ignore 規則，再執行 `git rm -r --cached --ignore-unmatch -- .agent-ops/tasks/ .agent-ops/reviews/`，保留本機檔案並解除追蹤。若有 staged 刪除，先提交清理 commit，再重新產生 verify/review 證據。啟用的 completion Stop gate 也會以 `COMPLETION_GATE_TRACKED_RUNTIME` 阻擋此狀況並提供修復訊息。請從 Git repository 根目錄執行 verify/review；目前路徑與指紋收集不支援巢狀 project root。Uninstall 會移除 managed ignore 檔，但保留 runtime 輸出。
+
+## EVIDENCE-FOLLOWUP-001
+
+保留的非阻擋 finding 與自由文字剩餘風險必須（MUST）保留原始來源，不得（MUST NOT）因一般測試通過而視為已解決。
+
+- Trigger: 成功且有 receipt 的交付、本機歷史匯入或明確選取處理。
+- Action: 收集中繼資料、保留來源與處置，修復前先重驗目前原始碼。
+- Evidence: 結案綁定原始 finding、精確 commit、對應驗收，或有理由的 review-only 契約及兩次新鮮審查。
+- Positive: 選取的 PRESENT finding 啟動全新原生修復；對應紅轉綠與封存交付可解決該項目。
+- Negative: 只因一般測試通過、路徑變動或 run 完成，就在缺乏專屬證據時結案。
+
+- 一般 finish、原生執行最終交付與復原，在成功交付後，從驗證過的本機 receipt、Git note
+  摘要及完整封存報告自動收集。一般儲存庫 CLI 使用時會重試收集及修復結果對帳。
+  `agent-ops followup import`（別名 `sync`）回填歷史只處理中繼資料：不呼叫模型、
+  不重驗、不修復、不花 provider 額度。無效來源保守警告；收集為建議性功能，
+  失敗不影響已有效完成的交付（fail-open）。
+- 版本化私有狀態位於 Git common directory 的 `agent-ops/followup/`，所有連結 worktree
+  共用，不提交至 Git。以精確來源識別去重，重複匯入保留處置、重驗、修復連結與證據歷史。
+  舊 schema 1 receipt 保留明確的舊版契約來源限制，不改寫已完成的來源 task、run 或 receipt。
+- `followup list`、`show <followup-id>` 支援文字與 `--json`。具體 finding 是候選項；
+  文字風險是待釐清觀察。`clarify <followup-id> --finding-file <json> --reason <text>`
+  保留原始觀察並提供含位置與證據的非阻擋 ReviewFinding。`accept`、`defer` 必須有非空理由，
+  保留歷史，且不等於解決。`reopen` 保留既有證據；可再次選取 `process` 重新處理。
+- `followup process <followup-id> --host <claude|codex>` 明確授權針對目前原始碼重驗，
+  且只在確定 PRESENT 時啟動全新、有界的正式原生修復 run，不重複要求確認。
+  兩次獨立唯讀審查使用隔離的目前原始碼及不可變原始 finding。UNKNOWN（含 reviewer
+  失敗、無效輸出、逾時、原始碼或設定漂移、證據不足）不能啟動修復或結案。
+  指紋、路徑變動與檔案存在本身不能證明語意結論。
+- 原生啟動保留 macOS、乾淨主 checkout、已 checkout 目標分支、目前信任、run policy、
+  原生控制與 worktree 所有權。拒絕時保留項目與原始錯誤碼；不得繞過 nested-run 限制，
+  不重啟已完成的來源 run。私有互斥宣告與預留 run 身分避免重複啟動；中斷且結果未知時維持待處理。
+- ABSENT 結案需要 `--review-only-reason <text>` 的具體合理契約與兩次新鮮審查。
+  可重現錯誤仍需對應 behavioral 紅轉綠驗收。修復結案需驗證原始 finding 專屬的
+  `followup-resolution` criterion、baseline、目標、原始碼與設定、成對檢查或有理由的
+  review-only 契約、兩次新鮮封存審查、交付 receipt，以及精確 commit 與證據摘要。
+  一般測試 PASS、run 狀態、接受與延後都不能結案；過期或未連結的證據維持未解決。
+  清理與復原不得遺失連結。
+- `followup process` CLI 權限只隨 opt-in run profile 提供，並在一般 init/update 計畫中可見；
+  不授權修改信任或 policy。不新增 Office 寫入 UI、SessionStart 摘要、雲端服務或強制關卡。

package/docs/zh-TW/spec/loop-engineering.md

@@ -21,6 +21,7 @@
 - Coordinator 只能在綁定原始 repository trust、可執行 runtime、一小時有限授權期限的 run-scoped policy 下，評估新增固定且非危險的能力。不得繞過 native 或組織的明確拒絕。Policy 變更先停止所有 writer，保留固定交付，以 journal 記錄 contract 同步，再啟動新 generation；不授予永久 repository trust。Native decision 保存遮罩後的命令範圍與理由，provider 未提供的證據維持 UNKNOWN。
 - 執行中的 run 僅在原始 repository trust、config、可執行 runtime 與操作範圍完全相同時，自動續期過期的有限授權。續期以 digest 綁定前一版本並保留既有評估，拒絕無效／倒退時鐘；並行 stop、denial 或 scope 變更使續期失敗。權限已變更或撤銷時須沿既有 trust/resume 流程取得真正授權；續期不授予永久 trust，也不消除 denial。明確 resume 先核對不可變 renewal lineage，再同步 policy。回答問題也沿用相同恢復檢查；兩者皆不得復活已被明確拒絕的工作。
 - `run resume <id> --retry-approval <auth-event-id>` MAY 明確重試以額度不足 wrapper 失敗的 Codex 自動審批。每筆指定失敗 MUST 保有原始 private artifact、digest、worker identity 與 policy lineage；真正或未指定的拒絕仍阻擋。多筆失敗可重複旗標。成功確認會留存並在後續 resume 重新驗證；此操作不授予命令權限，原生審批必須重跑，既有 writer 死亡、checkout、trust 與預算檢查仍適用。
+- `run resume <id> --retry-delivery <task-id>` MAY 在修復 harness 原因後，明確重新排程一個被 `RUN_FINAL_PROOF_INTERRUPTED` 阻擋的 child。MUST 核對同一筆中斷 handoff、所有 writer 與 proof 已確認停止、所屬 checkout 乾淨及目前 trust/policy；保留 run、task、goal、baselines、commits、耗用與失敗歷史，記錄已確認的 attempt，並要求新 native generation 及正常交付驗證。MUST NOT 直接標記交付、解除其他阻擋或確認命令拒絕；approval retry 是獨立操作。一般 resume 保留 no-progress 阻擋。受控 proof 中斷 MUST 記錄有界且已遮蔽的 exit/signal、失敗階段與子程序診斷；無效輸出或非零退出的成功 envelope 不得視為證據。
 - 當次人工 resume 的初始恢復 MAY 忽略啟用前收到、且 native 更新秒數嚴格早於該次 resume 的本執行緒 Codex 額度快照。自動重啟、未知／同秒／未來時間、時鐘倒退，以及啟用開始後收到的所有額度事件仍有效。Native 啟用 MUST 確認 goal 為 active，才能啟動或轉向 turn。人工 resume 可解除衍生的 `RUN_POLICY_DISABLED` task 阻擋，但保留 ID、耗用、歷史及其他產品失敗。
 - 收斂判斷比較實際 per-check 狀態及未解除的 finding pins；source fingerprint、時間或診斷文字本身不能算進展。
 
@@ -33,6 +34,26 @@ instructions 會列出每個 child 的狀態與交付 commit。`jobs=1` 時，ch
 程序確認死亡後才執行。native 註冊、恢復與啟動 MUST 都限制最多 `jobs` 個 active
 agent；僅扣除 task slot 不足以符合。
 
+明確回答 pending run 問題後，MAY 在 child 全部完成前解除已確認停止的 coordinator
+wait。回答只消耗此 run 當前 generation 的等待，記錄 `RUN_COORDINATOR_RESPONSE_WAKE`，
+本身不啟動程序。正常 resume 仍須核對程序死亡、trust 與 policy，再於 job 限制內
+發出新 generation。一般 resume 或重播舊回答不得解除新的 wait。child 交付、失敗
+歷史與 policy binding 保持原樣；回答本身不授予額外 command capability。
+
+Run-level proof MUST 符合已保存的 proof PID、process group、程序啟動身分，以及
+目前 coordinator ID 與 generation。此 actor 可讀取 main root 與已註冊 worker
+checkout 的 run policy，包括整合時已交付的 child，且不需改寫其 worker 環境。
+Worker-local proof 仍限於自己的 checkout 與 worker 身分，其紀錄 MUST NOT 遮蔽
+獨立驗證通過的 run-level proof。一般 checkout record 與 integration ownership
+檢查仍有效。錯誤 actor、group、generation 或未註冊 checkout 回傳
+`RUN_WORKER_STALE`；身分核對後，inactive、disabled 或 awaiting-resume run 仍回傳
+`RUN_POLICY_DISABLED`。讀取 policy 不授予額外 capability，也不改動 config、trust、
+registration 或 delivery state。
+
+已知限制：內層 verification command 逾時可能終止共用的 proof 程序群組，使 evidence
+CLI 來不及輸出 JSON。本次 response 恢復沒有修復此程序隔離缺陷；可由既有
+coordinator policy 流程評估有界、僅限該 run 的 command timeout，並保留失敗紀錄。
+
 English source version: 2026-07-23. Revalidate: when the English specification changes.
 
 ## LOOP-START-001

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

@@ -1,20 +1,20 @@
 # 審查
 
-English source version: 2026-10-23. Revalidate: when the English specification changes.
+English source version: 2026-10-27. Revalidate: when the English specification changes.
 
 ## REVIEW-CRITERIA-001
 
 - Trigger: 正式 task 的 criteria 就緒、尚未開始實作。
 - Action: 等待一輪限定範圍的 advisory，由 writer 記錄採納或拒絕理由。
 - Evidence: 私人快照報告與安全 local 狀態／用量 log；不產生完成證明。
-- Positive: `修訂後顯示歷史建議；只有明確 rerun 才再花一輪。`
-- Negative: `每次 revise 都自動重審，或把建議當正式 PASS 證明。`
+- Positive: `依建議改寫 criterion；該次 revise 自動重跑一輪 advisory 並顯示新建議。`
+- Negative: `每次 revise（包含只改 surface）都重審，或把建議當正式 PASS 證明。`
 
 每個正式 task 建立入口（含 DEBUG、replan 新子任務及 native run root/child）MUST 在首次實作前等待一輪獨立 criteria advisory。使用設定的 independent-review target 與全新 session，優先選擇不同於 host 的 target；只提供原始 goal、指派 intent/covers、criteria 與 surface audit，並在空白暫存工作區執行。MUST NOT 掃描 repository 或跑測試。缺 goal 須明示資訊不足；子任務只對指派範圍判完整性。材料是否存在、是否載入產品程式留待實作驗證；有理由的 review-only 條件合法。
 
 advisory 不設 agent-ops 執行 deadline、stall cutoff 或 token budget。provider 限制、真正啟動／認證／輸出錯誤與人工取消仍有效。錯誤回報 NOT_RUN 後可繼續；人工取消保留 task 並 MUST 停止實作。native 審查程序仍受註冊與停止機制管理。一般 verify 與正式雙輪 review 的既有時間限制及 gate 保持有效。
 
-task 建立回應呈現建議與私人報告位置。writer 自行判斷採納，透過 task revise 記錄採納及拒絕理由（可用相同 criteria 修訂記錄拒絕建議）。需求歧義或擴大範圍才向使用者澄清。報告綁定 task／goal／criteria／surface 快照；輸入改變後 status 與 revise 顯示歷史報告已過期。修訂 MUST NOT 自動重審。重複初審請求重用第一次嘗試，包含 NOT_RUN；只有明確執行 `agent-ops review --criteria --task <id> --rerun --yes` 才開始新的一輪。省略 --rerun 時讀取／等待目前嘗試。
+task 建立回應呈現建議與私人報告位置。writer 自行判斷採納，透過 task revise 記錄採納及拒絕理由（可用相同 criteria 修訂記錄拒絕建議）。需求歧義或擴大範圍才向使用者澄清。報告綁定 task／goal／criteria／surface 快照，並記錄觸發來源（`create`、`rerun` 或 `revise`；舊報告沒有此欄位）。goal、intent、criteria 或指派範圍改變後，status 與 revise 顯示報告已過期；只改 surface 時報告仍視為最新。第一次讓目前報告過期的已儲存修訂，若該報告本身不是 revise 觸發，MUST 等待一輪自動的新審查（觸發來源 `revise`）並顯示建議；不論該輪完成、回報 NOT_RUN 或被取消，修訂都會保留。之後的修訂 MUST NOT 自動重審，直到明確 rerun 為止。重複初審請求重用第一次嘗試，包含 NOT_RUN；除了那一輪自動審查，只有明確執行 `agent-ops review --criteria --task <id> --rerun --yes` 才開始新的一輪。省略 --rerun 時讀取／等待目前嘗試。
 
 詳細報告經遮蔽後私存於 `.agent-ops/reviews/criteria-<task-id>*.json`；local log 只記狀態、耗時、數量、可得用量及報告參照。CLI 呼叫數與 provider 模型呼叫數分開，後者可能未回報。報告／log 故障 MUST NOT 回滾 task 或偽造證據。advisory 產物 MUST NOT 滿足 verify、正式 review 或 finish。
 
@@ -100,6 +100,26 @@ PASS MUST 交給第二個規劃的 target 嘗試反駁，且反駁成立時 MUST
 - Note: 只有一個設定 target 時，會在全新 session 再呼叫同一 target。FAIL 已是終局，不再複查。
 - Note: 有 surface 的 task，第二輪也會在 `surface-coverage` 下搜尋未列出的 surface 與情境：檢查五個固定情境維度，每個軸向最多可新增 3 個 `git grep -F` 查詢。第一輪重放記錄的查詢並閱讀每個列出的 `valueChanges` consumer；這是「不要普查 repository」唯一的例外。
 
+## REVIEW-ORIGIN-001
+
+不是本次變更造成的缺陷 MUST NOT 擋下變更；MUST 以 `origin: "pre-existing"`、`blocking: false` 回報，並流入 followup ledger。
+
+- Trigger: reviewer 在審查閱讀過程中碰到缺陷。
+- Action: 只有當缺陷在 base 以相同形式存在，且本次變更沒有引入、暴露、加劇或依賴它時，才標為 pre-existing。只回報正常閱讀路徑上碰到的缺陷；不主動搜尋舊問題。
+- Evidence: report validator 拒絕任何 severity（包含 critical）的 pre-existing finding 帶 `blocking: true`。沒有 `origin` 的 finding 視為 introduced，沿用原本的 severity 規則，因此既有 report 仍然有效。已交付 PASS 的 nonblocking finding 照舊進入 followup。
+- Positive: `未改動 helper 裡的 critical injection 標為 pre-existing、nonblocking，並收進 followup。`
+- Negative: `未改動檔案中的 caller 因本次變更而壞掉，卻因為那幾行沒被修改就標為 pre-existing。`
+
+## REVIEW-ROUNDS-001
+
+同一份 task contract 的 review 失敗三次後 MUST 停止，要求換方案，而不是再修一輪。
+
+- Trigger: 對某 task 執行 `review`（直接執行，或經由 `batch`、`task advance`、run），且該 task 在目前 task contract hash 下、最近一次 PASS 之後已有三份以上 FAIL report。
+- Action: 在解析 scope 或啟動任何 reviewer 之前回傳 NOT_RUN `round-cap`，並印出完整的 `task revise` 指令。重新檢討做法，附上理由修訂 criteria 或 intent，或詢問使用者。
+- Evidence: NOT_RUN report 不計入；每個 source fingerprint 只保留一份 report，所以對未改動的程式碼重跑不會增加次數；contract 修訂或較新的 PASS 會讓計數歸零。上限是常數，不是設定項。
+- Positive: `同一份 contract 第三次 FAIL；agent 把 intent 改成另一種設計後再審。`
+- Negative: `同一份 contract 審到第五次，仍然每個 finding 修一個 commit。`
+
 ## REVIEW-HOST-001
 
 Host 缺少 network 或 loopback 能力時，MUST 在任何 reviewer invocation 前

package/package.json

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

package/schemas/review-report.schema.json

@@ -41,7 +41,8 @@
         "locations": { "type": "array", "items": { "$ref": "#/$defs/location" } },
         "evidence": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/text" } },
         "recommendation": { "$ref": "#/$defs/text" },
-        "criterionIds": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/text" } }
+        "criterionIds": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/text" } },
+        "origin": { "enum": ["introduced", "pre-existing"] }
       }
     }
   }