@kylecheng3146/agent-ops 0.5.3 → 0.7.0

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

@@ -1,6 +1,26 @@
 # 驗收與證據
 
-English source version: 2026-09-27. Revalidate: when the English specification changes.
+## EVIDENCE-CONTRACT-001
+
+可執行驗收 MUST 將目前契約綁定到不可變的 replay 證據。
+
+- Trigger: 驗證或完成 typed 驗收契約。
+- Action: 在固定 baseline 與目前 candidate replay 授權 checks，再取得 fresh review。
+- Evidence: 綁定摘要的 phase results 與目前 coverage 進入兩輪 reviewer packet。
+- Positive: baseline 斷言 FAIL、candidate PASS 證明 behavioral check。
+- Negative: 把 fixture error 算 red，或用舊 review 證明修訂後 criteria。
+
+- `behavioral`：指定 red checks 在 baseline 都因斷言失敗，candidate 的必要 checks 全部通過。`invariant`：candidate 的必要 checks 通過，baseline 原本 PASS 有效。`review-only`：兩輪 fresh review 對照原始目標驗收，不宣稱機械證明。
+- repo 授權的 `verification.acceptanceRunners` 定義 argv、setup、產品與 test build。task 提供穩定 check IDs 與明列且已 commit 的 test／fixture／helper；兩側各自安裝並 build 其版本，再覆蓋 candidate 材料。task 不能改 runner 命令。
+- fixture、collection、build、timeout、取消、輸出截斷、缺少或重複 ID、retry、skip MUST NOT 算 red 或 green。完整 execution artifacts 以摘要綁定契約、材料與 commits。
+- 原生 Jest JSON 與 Vitest task errors 無法完整區分 test-call 斷言與 hook／fixture cleanup。除非已 review 的 repo collector 提供明確斷言分類，失敗列 MUST 保持 UNKNOWN；AssertionError 名稱、matcher 資料與 pass 的 hook 狀態都不足。green 需要明確的單次 attempt 證據：attempts、Jest invocations，或 Vitest retryCount 與 repeatCount 兩者。原生 Vitest JSON 省略這些 counters，不能單獨提供機械證明。pytest 每個 nodeid 必須有一組依序的 setup／call／teardown；Rust protocol 必須提供 attempts。缺 metadata MUST NOT 預設為一次成功。
+- baseline 固定為建立 commit；finding pin 使用被 FAIL 的 candidate。revise／replan 保留原始目標、全部映射要求與先前契約／證據。新契約必須重新取證並取得兩輪 fresh review。
+- `task pin-finding` 驗證已保存 report 的 digest／index 來源。recurrence 明確引用既有 pin。第六條回傳 replan 義務且不修改狀態；映射後必須保留 pin 與全部要求。
+- reviewer packet 包含原始目標、修訂歷史、coverage 與 verifier 材料，審查斷言本身與明確的 fallback 理由。機械 green 不會省略必要 policy commands 或任一 fresh review。
+
+task state 寫入 version 2、讀取 version 1；evidence version 4 讀取舊證據，attestation version 3 綁定契約與 coverage。legacy criteria 維持下列 verifier 規則；typed／revised 契約不能沿用舊 review。coverage 分列機械證明、review-only、legacy；runner 綁定本身不算證明。明確 no-change proof 列出固定 candidate 上已 commit 的 regular source files；整合時重新解析支持路徑。一般 empty-diff review 與 empty-branch direct finish 仍拒絕。
+
+English source version: 2026-10-06. Revalidate: when the English specification changes.
 
 ## EVIDENCE-CRITERION-001
 

package/docs/zh-TW/spec/harness-adapters.md

@@ -1,6 +1,6 @@
 # Harness Adapter
 
-English source version: 2026-08-03. Revalidate: when the English specification or any vendor reference changes.
+English source version: 2026-10-07. Revalidate: when the English specification or any vendor reference changes.
 
 本文件所述 OpenCode plugin 行為已於 2026-07-31 依據[官方 plugin 文件](https://opencode.ai/docs/plugins/)與[Bun shell 文件](https://bun.sh/docs/runtime/shell)檢查；Codex 與 Claude Code loop-hook 行為已於 2026-08-03 依據 [Codex hook 文件](https://developers.openai.com/codex/config-advanced#hooks) 與 [Claude Code hook 文件](https://code.claude.com/docs/en/hooks) 檢查；agy hook 行為已於 2026-08-28 依據[官方 Antigravity hook 文件](https://antigravity.google/docs/hooks) 檢查。任何 vendor 參考變更時都必須重新驗證。
 
@@ -90,6 +90,7 @@ script，也不得改變一般 permission request。
 
 | Capability | agy | Codex | Claude Code | OpenCode |
 | --- | --- | --- | --- | --- |
+| office-presence (Preview) | degraded | degraded | supported | degraded |
 | lifecycle-summary | degraded | supported | supported | degraded |
 | command-policy | supported | unknown | supported | supported |
 | completion-gate | supported | unsupported | unsupported | unsupported |
@@ -118,3 +119,94 @@ Stop verification 必須明確啟用、具備 trust、為 report-only 且預設
 event metadata、回傳有界且 redacted 的 session context，並在 update 或 uninstall
 時保留 local goal、state、telemetry 與 Codex TOML file。既有 Codex configuration
 中清楚解析出的 `[features]` / `hooks = false` MUST 在任何 write 前拒絕 loop planning。
+
+## HARNESS-ADAPTER-007
+
+`run` profile MUST 是 opt-in，會一併選取 `core` 與 `loop`，且只新增 `auto-run`
+capability。啟用後，Claude Code 與 Codex 的 managed rules 會將需要超過五項
+acceptance criteria 的變更交給 `agent-ops run`；五項以內仍留在 session 中處理。
+agy rules，以及所有未含 `auto-run` 的 rule file，MUST 與未啟用此 profile 時
+byte-identical。
+
+- Trigger: Project 選擇 `run`，且 Claude Code 或 Codex session 遇到需要超過五項
+  acceptance criteria 的變更。
+- Action: Agent 在 main checkout、且在任何 `task create` 之前，將使用者 prompt
+  原文與其提議的 acceptance criteria（標示為提議）寫入已 gitignore 的
+  `.agent-ops/state/run-goal.md`，再以 background shell command 啟動
+  `agent-ops run --goal-file .agent-ops/state/run-goal.md --host <claude|codex> --wait`。
+  Codex 的啟動方式與 review 相同：outer request 使用
+  `sandbox_permissions: "require_escalated"` 與
+  `env -u CODEX_SANDBOX_NETWORK_DISABLED`。Awaiting-input 結果會轉達給使用者，並以
+  `agent-ops run respond` 回覆。啟動遭 `RUN_TARGET_REQUIRED`、
+  `RUN_BACKGROUND_UNSUPPORTED`、`RUN_TARGET_DIRTY` 或 `WORKTREE_NESTED` 拒絕時，以
+  一行說明該 code，並退回 subtask flow；`RUN_REPO_UNTRUSTED` 則停止並詢問使用者。
+  未完成即結束的 run（blocked、budget exhausted、stopped、review 失敗）須回報其
+  `run status` state 與 code、最後的 `run logs` event，以及確切的
+  `agent-ops run resume <id>` 與 `agent-ops run stop <id>` command，且永不自動
+  resume 或由 session 接手。在 worktree auto mode 下，Claude `PreToolUse`
+  worktree guard 允許在 main checkout 寫入恰為 `.agent-ops/state/run-goal.md`
+  的路徑，且不建立 worktree。確認後的 init/update 會預先授權 `agent-ops run`：
+  Claude Code 為 `Bash(agent-ops run *)`，Codex 為
+  `env -u CODEX_SANDBOX_NETWORK_DISABLED agent-ops run` 的 escalated prefix rule。
+- Evidence: Profile、managed-rule digest、pre-authorization 與 worktree-guard
+  test 涵蓋解析後的 profile、未變更的 rules、新增的 entry，以及唯一豁免的路徑。
+- Positive: `啟用 run profile 的 Claude Code session 在 main checkout 寫入 .agent-ops/state/run-goal.md，並在 background 啟動 agent-ops run --host claude --wait。`
+- Negative: `run profile 啟用時仍將八項 criteria 的變更拆成 subtask、在 GEMINI.md 加入 auto-run 文字，或未經使用者即 resume blocked run。`
+
+## HARNESS-ADAPTER-008
+
+`agent-ops office`（Preview）MUST 只依據 agent-ops state 以 read-only 方式呈現進度。
+Supervisor 在確定性的轉換點記錄每個 run 與 worker 的 optional phase
+（`planning`、`implementing`、`verifying`、`reviewing`、`integrating`），以及每個
+task 最近一次 verify 與 review 結果與通過/總數 criteria。Phase 出現前寫入的 run
+state MUST 仍能通過驗證，並顯示為 `unknown`。變更檔案來自各 worktree 自身相對
+base 的 `git diff`；旁白只使用路徑（`docs/**` 為「writing docs」、`tests/**` 為
+「writing tests」，其他為「editing <file>」）。Office MUST NOT 讀取 Claude 或 Codex
+的 native transcript 或檔案內容。
+
+- Office Preview 透過 `features.office.enabled` 明確啟用。Init MUST 提供預設關閉
+  的選項；互動式 update MUST 以既有選擇為預設。非互動式 update MUST 保留選擇，
+  除非傳入 `--office on|off`。即使只選 core，啟用 Office 也 MUST 安裝 presence
+  hook，但 MUST NOT 同時啟用 command policy、Stop verification 或 lifecycle
+  summary。Office-only OpenCode 的 runtime 失敗 MUST fail-open；與 command
+  policy 同時啟用時 MUST 保留原有拒絕與 runtime unavailable 行為。Agy 啟動事件
+  以 invocation 為單位，OpenCode 以 app 為單位，部分 Codex 模式沒有 Stop；過期
+  presence 依有界限的 hook 活動逾時處理。舊設定可省略此欄位，省略代表關閉；features 維持
+  原有的整個物件 layer 優先順序。關閉時 hook MUST NOT 記錄 Office presence、
+  啟動 server 或開啟瀏覽器，明確的 office 指令 MUST 說明啟用方法。運行中的
+  server MUST 在下一次 15 秒生命週期檢查觀察到關閉選擇後結束。
+- Trigger: 啟用後，Managed 一般 session 啟動或回報活動，或使用者執行
+  `agent-ops office`、`agent-ops run start` 或 `agent-ops run status`。
+- Action: Command 重用記錄於 `<git common dir>/agent-ops/office.json` 的 live
+  server，否則啟動一個，並印出 URL。一般 session hook 也會自動啟動或重用
+  Office，包含尚未建立 task 或 worktree 的 session。只有成功取得新 server
+  所有權的 process 開啟瀏覽器，後續 session 共用同一個 Office。Session metadata
+  只記錄有界限的識別資訊、已知工作狀態與活動時間，不包含 native transcript、
+  prompt、tool 或檔案內容。啟動與活動觀察失敗均為 advisory。
+  Server 綁定 127.0.0.1 的隨機 port，要求 URL 中不可猜測的 token，拒絕該位址與
+  port 以外的 Host，所有非 GET 回應 405，並在 run 與一般 session 都沒有活動
+  10 分鐘後結束。唯一的 inline page 使用奶油白、淺木與鼠尾草綠的程式內 16 色
+  場景 sprite，沒有圖片 asset。32×48 人物各自使用固定的膚色、髮色與服裝色盤，
+  支援四方向走路，並顯示本地化的職責文字。使用者標籤在中文顯示「你」、英文顯示「You」，總覽大小與
+  最大房間的成員一致。總覽填滿頂部工具列下方的單一
+  viewport，同時呈現全部有家具的工作房間，必要時自動縮小且不捲動頁面。
+  房間以共用走廊連接；使用者可以用方向鍵或 WASD 操控本機 Supervisor 角色，
+  走進每間房並返回總覽，不會呼叫模型或透過網路修改狀態。每個 run 團隊共用一間房，
+  每個一般 session 各有一間，執行中的 review 也保持可見。點房間進入放大的
+  詳細畫面，並可返回總覽。每間房包含規劃、開發、驗證、審查與整合區。角色依
+  已知 phase 移動與播放輕量動作，並有簡短名牌與狀態；不從對話推測未知狀態。
+  白板顯示 criteria 進度、verify/review 結果與待回覆問題，`!` 標示未回答的問題。
+  點白板或進度板開啟房間工作清單，點工位或階段區查看該階段的已知工作。
+  點待回覆標記查看完整問題與現有可複製指令；同一套分頁視窗也可用
+  `L`（工作清單）、`1–5`（階段）與 `Q`（問題）開啟。
+  點角色開啟有界限且分頁的 status 詳情，包含可複製的 command。完成房間移到
+  最近完成，最多保留兩小時。支援中英文切換並記住選擇、鍵盤操作與 reduced
+  motion。一般 session 的存活狀態依 hook 活動判定，30 分鐘沒有事件就會移除
+  過期的 presence，不會讀取 native host process。Office 啟動失敗絕不使
+  hook、`run start` 或 `run status` 失敗。
+- Evidence: Phase、snapshot、server、scene 與 CLI test 涵蓋 legacy state、彙整與
+  旁白、一般 session 登記與只開啟一次、完成後兩小時的邊界、token/Host/method
+  防護、重用與 injected clock 的 idle 結束、viewport 與房間切換、中英文，以及
+  印出的 URL。Browser read-back 檢查實際渲染的單頁布局。
+- Positive: `一般 session 自動開啟共用 Office，尚未建立 worktree 就能看到自己的房間；進入團隊房時看到 coordinator 在驗證桌旁，白板顯示 6 項 criteria 已通過 2 項。`
+- Negative: `在 0.0.0.0 提供 office、接受 POST、讀取 worker transcript 來產生旁白，或打包 PNG sprite sheet。`

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

@@ -1,5 +1,27 @@
 # 迴圈工程
 
+## LOOP-RUN-001
+
+`run` MUST 保留原始使用者目標，並要求目前有效的 agent-ops 證據。
+
+- Trigger: 啟動、修復或恢復 native goal run。
+- Action: writer 綁定目前 lease，並要求最終 verify、雙 review 與 receipt 證據。
+- Evidence: run ledger 與封存 receipt 綁定目前 candidate 及原始目標。
+- Positive: 恢復未完成清理時，保留 target 與已保存的 final proof。
+- Negative: 只因 native goal completion 就把 run 標為 complete。
+
+- macOS supervisor 在啟動 goal 前保存 Claude／Codex native 身份。同 host writers 使用獨立 worktrees 與目前 generation lease；coordinator 計入最多兩個 writer。依賴以固定交付提供，child baseline 在依賴 commits 進入 checkout 後建立。
+- 預設 60 分鐘預算計算 active intervals 聯集，包含 setup、verify、review、整合。resume 保留時間與 usage epochs；缺少計數維持 UNKNOWN，partial usage 不算完整成本。
+- 實質疑問暫停並要求明確回答。修復保留目標與失敗紀錄；連續兩次相同失敗且無進展停止該 worker 及其依賴，獨立 task 仍可執行。review findings 在下次 final gate 前必須有回歸 pin 或記錄 review-only fallback。
+- native completion 僅是觀察。完成必須有必要驗證、兩輪 fresh review、完成的 task state、綁定 target 的 receipt。整合在移動 target 前封存 candidate，記錄 task、receipt、note、cleanup 進度；恢復驗證封存證據，不重做成功的 target mutation。不一致的 target 維持 blocked。
+- Stop 先保存禁止續跑，再確認受管 process group 死亡。crash recovery 不得取代仍存活或身份不明的 writer。dirty checkout、版本漂移、restart storm 保留現場。重開機／login 改變必須明確 resume；不修改全域 host policy。
+- Native handshake 前先保存啟動程序身份；尚未開啟的 Codex session 必須證明程序死亡，才可在新 lease 重新初始化。
+
+- Setup 與 native agent 發起的 local proof MUST 先登記 dormant process group 再執行；Stop 也要取消子程序。中斷的 setup 必須明確 resume，保留 checkout 與失敗 artifact。
+- Coordinator 只能在綁定原始 repository trust、可執行 runtime、剩餘預算的 run-scoped policy 下，評估新增固定且非危險的能力。不得繞過 native 或組織的明確拒絕。Policy 變更先停止所有 writer，保留固定交付，以 journal 記錄 contract 同步，再啟動新 generation；不授予永久 repository trust。Native decision 保存遮罩後的命令範圍與理由，provider 未提供的證據維持 UNKNOWN。
+- 明確 resume 從剩餘預算續期過期授權，並先核對不可變 renewal lineage，再同步 policy。回答問題也沿用相同恢復檢查；兩者皆不得復活已被明確拒絕的工作。
+- 收斂判斷比較實際 per-check 狀態及未解除的 finding pins；source fingerprint、時間或診斷文字本身不能算進展。
+
 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.5.3",
+  "version": "0.7.0",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",

package/schemas/config.schema.json

@@ -20,7 +20,13 @@
       "type": "array",
       "uniqueItems": true,
       "items": {
-        "enum": ["core", "advisory", "guardrails", "loop"]
+        "enum": [
+          "core",
+          "advisory",
+          "guardrails",
+          "loop",
+          "run"
+        ]
       }
     },
     "reviewRoles": {
@@ -28,7 +34,10 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["role", "targets"],
+        "required": [
+          "role",
+          "targets"
+        ],
         "properties": {
           "role": {
             "enum": [
@@ -43,19 +52,34 @@
             "minItems": 1,
             "uniqueItems": true,
             "items": {
-              "enum": ["codex", "agy", "claude"]
+              "enum": [
+                "codex",
+                "agy",
+                "claude"
+              ]
             }
           },
-          "model": { "type": "string", "minLength": 1 },
-          "effort": { "type": "string", "minLength": 1 },
-          "timeoutMs": { "type": "integer", "minimum": 1 }
+          "model": {
+            "type": "string",
+            "minLength": 1
+          },
+          "effort": {
+            "type": "string",
+            "minLength": 1
+          },
+          "timeoutMs": {
+            "type": "integer",
+            "minimum": 1
+          }
         }
       }
     },
     "verification": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["commands"],
+      "required": [
+        "commands"
+      ],
       "properties": {
         "commands": {
           "type": "array",
@@ -69,18 +93,171 @@
               }
             ]
           }
+        },
+        "acceptanceRunners": {
+          "type": "array",
+          "maxItems": 128,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "command",
+              "args",
+              "cwd",
+              "adapter"
+            ],
+            "properties": {
+              "id": {
+                "$ref": "#/$defs/id"
+              },
+              "command": {
+                "type": "string",
+                "minLength": 1
+              },
+              "args": {
+                "type": "array",
+                "maxItems": 512,
+                "items": {
+                  "type": "string"
+                }
+              },
+              "cwd": {
+                "type": "string",
+                "minLength": 1
+              },
+              "adapter": {
+                "enum": [
+                  "generic",
+                  "node",
+                  "jest",
+                  "vitest",
+                  "pytest",
+                  "rust"
+                ]
+              },
+              "timeoutMs": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 3600000
+              },
+              "setup": {
+                "type": "array",
+                "maxItems": 64,
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "command",
+                    "args"
+                  ],
+                  "properties": {
+                    "command": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "args": {
+                      "type": "array",
+                      "maxItems": 512,
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "timeoutMs": {
+                      "type": "integer",
+                      "minimum": 1,
+                      "maximum": 3600000
+                    }
+                  }
+                }
+              },
+              "build": {
+                "type": "array",
+                "maxItems": 64,
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "command",
+                    "args"
+                  ],
+                  "properties": {
+                    "command": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "args": {
+                      "type": "array",
+                      "maxItems": 512,
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "timeoutMs": {
+                      "type": "integer",
+                      "minimum": 1,
+                      "maximum": 3600000
+                    }
+                  }
+                }
+              },
+              "testBuild": {
+                "type": "array",
+                "maxItems": 64,
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "command",
+                    "args"
+                  ],
+                  "properties": {
+                    "command": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "args": {
+                      "type": "array",
+                      "maxItems": 512,
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "timeoutMs": {
+                      "type": "integer",
+                      "minimum": 1,
+                      "maximum": 3600000
+                    }
+                  }
+                }
+              }
+            }
+          }
         }
       }
     },
     "features": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["completionGate", "stopVerification"],
+      "required": [
+        "completionGate",
+        "stopVerification"
+      ],
       "properties": {
-        "completionGate": {
+        "office": {
           "type": "object",
           "additionalProperties": false,
           "required": ["enabled"],
+          "properties": {
+            "enabled": { "type": "boolean" }
+          }
+        },
+        "completionGate": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "enabled"
+          ],
           "properties": {
             "enabled": {
               "type": "boolean"
@@ -90,7 +267,9 @@
         "stopVerification": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["enabled"],
+          "required": [
+            "enabled"
+          ],
           "properties": {
             "enabled": {
               "type": "boolean"
@@ -104,7 +283,10 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["path", "verifierIds"],
+        "required": [
+          "path",
+          "verifierIds"
+        ],
         "properties": {
           "path": {
             "$ref": "#/$defs/relativePath"
@@ -122,17 +304,25 @@
     "worktree": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["mode"],
+      "required": [
+        "mode"
+      ],
       "properties": {
         "mode": {
-          "enum": ["auto", "off"]
+          "enum": [
+            "auto",
+            "off"
+          ]
         },
         "setup": {
           "type": "array",
           "items": {
             "type": "object",
             "additionalProperties": false,
-            "required": ["command", "args"],
+            "required": [
+              "command",
+              "args"
+            ],
             "properties": {
               "command": {
                 "$ref": "#/$defs/nonEmptyString"
@@ -159,7 +349,12 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["ruleId", "scope", "expiresAt", "reason"],
+        "required": [
+          "ruleId",
+          "scope",
+          "expiresAt",
+          "reason"
+        ],
         "properties": {
           "ruleId": {
             "$ref": "#/$defs/id"
@@ -259,10 +454,16 @@
     "evidence": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["kind"],
+      "required": [
+        "kind"
+      ],
       "properties": {
         "kind": {
-          "enum": ["exit-code", "test-count", "file"]
+          "enum": [
+            "exit-code",
+            "test-count",
+            "file"
+          ]
         },
         "minimum": {
           "type": "integer",
@@ -273,7 +474,14 @@
     },
     "commandFields": {
       "type": "object",
-      "required": ["id", "command", "args", "cwd", "required", "evidence"],
+      "required": [
+        "id",
+        "command",
+        "args",
+        "cwd",
+        "required",
+        "evidence"
+      ],
       "properties": {
         "id": {
           "$ref": "#/$defs/id"
@@ -335,7 +543,10 @@
         {
           "type": "object",
           "additionalProperties": false,
-          "required": ["shell", "acknowledgeRisk"],
+          "required": [
+            "shell",
+            "acknowledgeRisk"
+          ],
           "properties": {
             "id": true,
             "command": true,