@kylecheng3146/agent-ops 0.11.1 → 0.11.2

package/docs/en/guides/task-debug.md

@@ -39,3 +39,39 @@ gone. `task debug` now fails with `TASK_DEBUG_REMOVED`.
 Older state still loads: tasks keep their `debug` tag, stored budget and
 hypothesis state is ignored, `originRequired` no longer blocks finish, and a
 config's `features.debug` is accepted and dropped by the next `update`.
+
+## Retained review followups
+
+After finish, inspect `agent-ops followup list` and `followup show <followup-id>`
+(add `--json` for agents). `followup import` / `followup sync` retries metadata-only local
+history collection without models or repairs. Ledger state is private in the
+Git common directory and shared by linked worktrees. Collection warnings leave
+original completion intact; retry after fixing the reported source/state problem.
+
+A free-text observation needs explicit clarification first:
+
+```sh
+agent-ops followup clarify <followup-id> --finding-file finding.json --reason 'Concrete claim and supporting source'
+agent-ops followup defer <followup-id> --reason 'Revisit after the dependency upgrade'
+agent-ops followup accept <followup-id> --reason 'Accepted tradeoff for this release'
+agent-ops followup reopen <followup-id>
+env -u CODEX_SANDBOX_NETWORK_DISABLED agent-ops followup process <followup-id> --host codex
+```
+
+`finding.json` is an ordinary nonblocking ReviewFinding: severity, blocking=false,
+title, details, locations (`path`, `line`), evidence, recommendation and criterionIds.
+Accept/defer require reasons and never mean resolved. Reopen and process again
+preserve source/proof history. Process is an explicit authorization for two fresh
+isolated read-only current-source reviews and, on conclusive PRESENT only, a new
+bounded production repair run. UNKNOWN, drift or reviewer errors stay unresolved.
+Native macOS/clean main/checked-out target/trust/run-policy controls remain; a
+refusal preserves its exact code and never triggers a nested-run workaround.
+
+Use the trusted outer host for process; `update --auto-run on` can propose scoped
+run-profile permissions. Do not modify trust or installed settings to bypass a
+refusal. A non-executable claim may use `--review-only-reason 'specific reason'`;
+ABSENT then needs two fresh reasoned reviews. Reproducible bugs need corresponding
+behavioral red-to-green checks. Repair closure uses the exact original finding,
+`followup-resolution` contract, delivered receipt, exact commit and evidence
+digests; generic suite PASS, changed paths or run completion alone cannot close it.
+This workflow adds no DEBUG investigation ceremony or SessionStart summary.

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

@@ -270,3 +270,57 @@ Before committing, use the default worktree scope for verify, review and complet
 This enforces the toolkit's completion command, not a host's natural-language completion claim. It does not prevent a process with the same filesystem authority from editing task/evidence files directly, and it does not lock Git or external source writers.
 
 Project init/update installs `.agent-ops/.gitignore` for `/tasks/` and `/reviews/` on every harness and profile. An existing user-owned `.agent-ops/.gitignore` blocks init/update with `UNMANAGED_INSTALL_PATH`: first back it up outside that path and move its custom rules to the root `.gitignore` (prefix them with `/.agent-ops/`), then retry. Git collection fails with `CHANGE_SURFACE_TRACKED_RUNTIME` if these directories contain indexed files (even clean tracked files), or staged runtime removals. Move any real source files out of the runtime directories, install ignore rules, then use `git rm -r --cached --ignore-unmatch -- .agent-ops/tasks/ .agent-ops/reviews/` to keep local files while removing them from the index. Commit any staged removals before producing fresh verification/review evidence. The active completion Stop gate also blocks this condition with `COMPLETION_GATE_TRACKED_RUNTIME` and the recovery message. Run verify/review from the Git repository root; nested project roots are not supported by the current path/fingerprint collector. Uninstall removes the managed ignore file but preserves runtime output.
+
+## EVIDENCE-FOLLOWUP-001
+
+Retained nonblocking findings and free-text residual risks MUST keep their original
+provenance and MUST NOT be treated as resolved by generic passing checks.
+
+- Trigger: Successful receipt-bound delivery, local history import or explicit selected processing.
+- Action: Collect metadata, preserve provenance/dispositions and assess the current source before any bounded repair.
+- Evidence: Resolution binds the original finding, exact commit and corresponding acceptance artifacts or a reasoned review-only contract with two fresh reviews.
+- Positive: A selected PRESENT finding starts a new native repair; its corresponding red-to-green proof and sealed delivery resolve the exact item.
+- Negative: A generic passing suite, changed path or completed run resolves a retained finding without its specific proof.
+
+- Successful ordinary finish, native final delivery and recovery collect from
+  authenticated local receipts, Git-note digests and full sealed reports. Ordinary
+  repository CLI use retries collection and linked-result reconciliation. Historical
+  `agent-ops followup import` (alias `sync`) is metadata-only: no model calls,
+  assessment, repair or provider quota. Invalid sources warn conservatively;
+  collection is advisory and fail-open after valid completion.
+- Versioned private state lives under the repository Git common directory at
+  `agent-ops/followup/`, shared by linked worktrees, never committed. Exact
+  provenance identities make repeated import idempotent; dispositions, assessment
+  links, repair runs and proof history survive retries. Schema 1 readable receipts
+  retain an explicit legacy contract provenance limit. Source tasks, runs and
+  receipts remain immutable.
+- `followup list` and `show <followup-id>` expose text or `--json` state. Concrete
+  findings are candidates; text risks are observations. `clarify <followup-id>
+  --finding-file <json> --reason <text>` retains the original observation and
+  supplies a concrete nonblocking ReviewFinding with locations and evidence.
+  `accept` and `defer` require nonempty reasons, retain history and are distinct
+  from resolution. `reopen` retains proof history; `process` may be selected again.
+- `followup process <followup-id> --host <claude|codex>` explicitly authorizes
+  current-source revalidation and, only on conclusive PRESENT, a fresh bounded
+  production native repair run without another confirmation. Two independent
+  read-only sessions inspect isolated current source and the immutable finding.
+  UNKNOWN (including reviewer failure, invalid output, timeout, source/config
+  drift or insufficient evidence) cannot launch repair or resolve. Fingerprints,
+  changed paths and path existence alone prove no semantic conclusion.
+- Native repair preserves macOS support, clean main checkout, checked-out target,
+  current trust, run policy, native controls and worktree ownership. Refusals
+  retain the item and exact code; there is no nested-run workaround or restart
+  of the completed source run. An exclusive private claim and reserved run
+  identity prevent duplicate starts; ambiguous interrupted startup stays pending.
+- ABSENT can resolve only under `--review-only-reason <text>` with a specific
+  justified contract and two fresh reviews. Reproducible bugs need corresponding
+  behavioral red-to-green acceptance. Completed repair closure validates the
+  exact original finding's `followup-resolution` criterion, baseline, target,
+  source/config, paired checks or reasoned review-only contract, two fresh sealed
+  reviews, delivered receipt and exact commit/evidence digests. Generic test PASS,
+  run status, acceptance or deferral cannot close it; stale/unlinked proof stays
+  unresolved. Cleanup recovery must retain links.
+- CLI permissions for `followup process` follow the opt-in run profile and appear
+  in normal init/update plans. They grant no trust/policy changes. No Office
+  write UI, SessionStart summary, cloud service or additional mandatory gate is
+  introduced.

package/docs/en/spec/loop-engineering.md

@@ -62,6 +62,17 @@
   Repeat the flag for multiple failures. Successful acknowledgements are audited
   and revalidated on later resumes. This grants no command permission: native
   approval runs again. Existing writer-death, checkout, trust and budget checks apply.
+  `run resume <id> --retry-delivery <task-id>` MAY explicitly requeue one child
+  blocked by `RUN_FINAL_PROOF_INTERRUPTED` after the harness cause is repaired.
+  It MUST require the matching interrupted handoff, confirmed stopped writers
+  and proof, clean owned checkouts and current trust/policy. It MUST preserve
+  run/task/goal/baselines/commits, accounting and failure history, record the
+  acknowledged attempt, and require a fresh native generation and normal proof.
+  It MUST NOT mark delivery, reset another blocker or acknowledge command denial;
+  approval retry is a separate control. Ordinary resume retains no-progress blocks.
+  Interrupted controlled proof MUST record bounded redacted exit/signal, result
+  failure stage and subprocess diagnostics without treating invalid output or a
+  nonzero successful envelope as proof.
   Initial recovery after a current manual resume MAY ignore an owned Codex limit
   snapshot received before activation whose native update second strictly predates
   that resume. Automatic restarts, unknown/equal/future timestamps, clock rollback,
@@ -83,6 +94,31 @@ status and delivered commit. With `jobs=1`, child execution MUST wait for that
 confirmed death. Native registration, recovery and start MUST enforce at most
 `jobs` active agents; changing task slot accounting alone is insufficient.
 
+An explicit answer to a pending run question MAY release a confirmed stopped
+coordinator wait before all children finish. The response consumes only this
+run's current-generation wait, records `RUN_COORDINATOR_RESPONSE_WAKE`, and starts
+no process. Normal resume still reconciles death, trust and policy, then issues a
+fresh generation within the job limit. Ordinary resume and replayed answers do
+not consume a new wait. Child delivery, failure history and policy bindings remain
+unchanged; an answer itself grants no additional command capability.
+
+A run-level proof MUST match its persisted proof PID, process group and process
+start identity, plus the current coordinator ID and generation. That actor may
+read the run policy for the main root and registered worker checkouts, including
+delivered children during integration, without changing its worker environment.
+Worker-local proof remains bound to its own checkout and worker identity; its
+record MUST NOT shadow an independently authenticated run-level proof. Ordinary
+checkout record checks and integration ownership checks remain authoritative.
+Invalid actor, group, generation or unregistered checkout claims return
+`RUN_WORKER_STALE`; an inactive, disabled or awaiting-resume run still returns
+`RUN_POLICY_DISABLED` after identity validation. Policy reads grant no additional
+capability and do not alter config, trust, registration or delivery state.
+
+Known limitation: an inner verification command timeout can terminate the shared
+proof process group before the evidence CLI emits JSON. Response recovery does
+not fix this process isolation defect; a bounded run-only command timeout may be
+assessed through the existing coordinator policy flow, with the failure retained.
+
 This module defines the bounded loop used to plan, implement, verify, and hand off work.
 
 ## LOOP-START-001

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

@@ -227,6 +227,9 @@ fingerprint，因此兩個對話修改同一個 checkout 會互相作廢對方
   `npx lint-staged` 的 allow 規則，讓 pre-commit hook 能寫入主 `.git`。`trust`、
   `allow-stop`、`init`、`update`、`uninstall` 永遠不會被預先授權。關閉 auto 模式或
   `uninstall` 會精確移除這些項目；同名但不是 agent-ops 寫的規則檔不會被動到。
+- opt-in `run` profile 另外在 Claude 與 Codex 授權 `agent-ops run` 與明確選取的
+  `agent-ops followup process`。一般 init/update 計畫會列出精確項目；移除 profile
+  會移除這些權限。中繼資料操作不授予原生執行權限，process 仍遵守目前儲存庫信任與所有原生啟動限制。
 - `review` 與 `doctor` 支援 `--output <file>`：JSON envelope 寫入該檔（權限 0600），
   並只印出一行摘要。請用它取代 shell 重導向；Codex 會把重導向包成 `zsh -lc`，只能
   以整串指令比對來放行。

package/docs/zh-TW/guides/task-debug.md

@@ -35,3 +35,34 @@ prompt hook 自動建立 DEBUG、DEBUG 專用 Stop 阻擋，以及 Codex `Interr
 `originRequired` 不再阻擋 finish，config 的 `features.debug` 仍被接受並在下次 `update` 時移除。
 
 完整說明見英文 [Task DEBUG](../../en/guides/task-debug.md)。
+
+## 保留的審查 followup
+
+finish 後以 `agent-ops followup list`、`followup show <followup-id>` 檢視，agent 可加
+`--json`。`followup import` / `followup sync` 只回填本機歷史中繼資料，不呼叫模型或修復。
+私有狀態在 Git common directory，所有連結 worktree 共用。收集警告不影響原始完成；
+修正來源或狀態問題後可重試。
+
+自由文字觀察需先明確釐清：
+
+```sh
+agent-ops followup clarify <followup-id> --finding-file finding.json --reason '具體主張與來源證據'
+agent-ops followup defer <followup-id> --reason '相依套件升級後再處理'
+agent-ops followup accept <followup-id> --reason '接受此版本的取捨'
+agent-ops followup reopen <followup-id>
+env -u CODEX_SANDBOX_NETWORK_DISABLED agent-ops followup process <followup-id> --host codex
+```
+
+`finding.json` 是一般非阻擋 ReviewFinding：severity、blocking=false、title、details、
+locations（path、line）、evidence、recommendation、criterionIds。接受與延後必須有理由，
+不等於結案；reopen 與再次 process 均保留來源及證據歷史。process 明確授權兩次隔離、
+唯讀、針對目前原始碼的新鮮審查，且只在確定 PRESENT 時啟動全新有界的正式原生修復 run。
+UNKNOWN、漂移與 reviewer 錯誤維持未解決。仍遵守 macOS、乾淨主 checkout、目標分支、
+信任與 run policy；拒絕保留原始碼，不繞過 nested-run 限制。
+
+process 必須透過可信任外層 host；`update --auto-run on` 可提出限定 run profile 權限。
+不可自行修改信任或已安裝設定繞過拒絕。無法用可執行檢查判定的主張可加
+`--review-only-reason '具體理由'`；ABSENT 仍需兩次新鮮且有理由的審查。
+可重現錯誤仍需對應 behavioral 紅轉綠。修復結案驗證原始 finding、`followup-resolution`
+契約、交付 receipt、精確 commit 與證據摘要；一般測試 PASS、路徑變動或 run 完成不能結案。
+本流程不新增 DEBUG 調查手續或 SessionStart 摘要。

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/package.json

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