@kylecheng3146/agent-ops 0.1.6 → 0.1.8

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

@@ -27,6 +27,66 @@ harness surface 並套用選定的 target policy；若不是 managed default，
 Claude 與 Codex lifecycle support 為 `supported`，OpenCode 從 app initialization
 開始，因此誠實標示為 `degraded`。
 
+### 外部 review 目標
+
+`agent-ops review` 可以呼叫另一個 agent CLI 來審查你的工作。預設關閉 ——
+缺少 `reviewRoles` 欄位、缺少 `--review-target` 旗標、互動式問題的預設值，
+三者都代表關閉。在 `agent-ops init` 時啟用，或手動設定：
+
+```json
+{
+  "reviewRoles": [
+    { "role": "independent-review", "targets": ["claude"] }
+  ]
+}
+```
+
+`targets` 是**有序的後備鏈**。每次 review 都鎖定 staged／unstaged／untracked
+變更（或乾淨的 `--base <ref>...HEAD`），並要求必要驗證的最新 PASS evidence；
+完整原生 schema report 會顯示給人看，但不會持久化。
+
+每次嘗試都從新的暫存 cwd 與最小環境啟動。目前只有 Claude 具備完整的
+context-isolation 合約，能自動執行：
+
+| 目標 | 呼叫方式 | 唯讀 |
+| --- | --- | --- |
+| `codex` | `codex exec` | 保留設定；`capability-unavailable` |
+| `agy`（Antigravity）| `agy -p` | 保留設定；`capability-unavailable` |
+| `claude` | `claude -p` | `--permission-mode plan --safe-mode` |
+
+`opencode` **不是** review 目標，即使它是支援的 harness。它的 `--agent plan`
+會被判定為 subagent 而遭拒，並靜默退回可寫入的 agent，因此無法滿足唯讀前置
+條件。沒有唯讀旗標的目標會被跳過，不會在無沙箱狀態下執行。
+
+只有在「根本沒審到」時才換下一家 —— 執行檔不存在、spawn 失敗、或逾時
+（每個目標預設 120 秒，可用 `timeoutMs` 覆寫）。`FAIL` 判定是**終局**：
+拿到真實判定後絕不再試下一家，否則就變成自動化的 review shopping。
+無法解析的輸出同樣終局，因為那代表 prompt 約定或 CLI 版本不合，該浮出來修。
+
+若 host 是 Claude Code（`CLAUDECODE` 已設定），`claude` 會被移到鏈尾。
+當它是唯一設定的目標時仍會執行，並附上 `reviewer == host` 警告。
+
+criterion 描述來自當前 session 綁定的 task，所以 review 需要已附加、且建立時的
+policy 設定仍相同的 task；`--criterion` 用來篩選 id。請先執行
+`agent-ops verify`：必要 evidence 若失敗、過期或來源不符，review 會在 model 呼叫前停止。
+僅 compact PASS evidence 會以 `review:<target>:` 附加；完整人類可讀 report 是暫存的。
+已完成的 task 絕不改寫。
+
+每次執行 review 仍需 `--yes`：init 的勾選決定「允許哪些目標」，
+`--yes` 決定「現在是否要花錢」。
+
+因為不從 stderr 嗅探認證狀態，未登入的 CLI 會表現為一次 review 失敗。
+用以下指令診斷：
+
+```bash
+agent-ops doctor              # 只驗執行檔存在：零 token、零網路
+agent-ops doctor --check-auth # 每個目標一次真實 print 呼叫
+```
+
+`--check-auth` 是專屬旗標；`--yes` 對 doctor 維持惰性。doctor 只回報該做什麼，
+不會代為修復：所有目標都經由互動式 OAuth 認證，因此沒有 `--fix`。
+請自行執行 `<target> login`。
+
 ### Project-local loop profile
 
 `--profile loop` 是明確 opt-in 的 project-scope profile。請選擇 `codex`、

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

@@ -24,10 +24,40 @@ English source version: 2026-07-23. Revalidate: when the English specification c
 
 ## REVIEW-HARNESS-001
 
-即使 installation 支援多個 harness，一次 review invocation MUST 解析成恰好一個 concrete harness。
+即使 installation 支援多個 harness，一次 review invocation MUST 解析成恰好一個 concrete review target。
 
 - Trigger: 使用 harness selection 執行 `review`。
-- Action: 從 `codex`、`claude` 或 `opencode` 中選一個；multi-harness installation 與 review execution 分開處理。
+- Action: 從 `codex`、`agy` 或 `claude` 中選一個；multi-harness installation 與 review execution 分開處理。
 - Evidence: argument parsing 會拒絕 review 使用 `all`、`both` 或逗號分隔的多 harness 值。
-- Positive: `review --harness opencode` 解析成一個 harness。
+- Positive: `review --harness claude` 解析成一個 target。
 - Negative: `讓一次 review invocation 隱式跑過所有已安裝 harness。`
+
+## REVIEW-READONLY-001
+
+review target MUST 以其自身的唯讀機制啟動；沒有唯讀機制的 target MUST 被跳過，而非在無沙箱狀態下執行。
+
+- Trigger: 為已設定的 target 組建 review invocation。
+- Action: 傳入 `-s read-only`（codex）、`--sandbox --mode plan`（agy）或 `--permission-mode plan`（claude）；其餘 target 視為不合格。
+- Evidence: spawn 出的 argv 含該 target 的唯讀旗標。
+- Positive: `opencode 不是 review target：--agent plan 會靜默退回可寫入的 agent。`
+- Negative: `信任 prompt 能阻止審查者修改檔案。`
+
+## REVIEW-CHAIN-001
+
+已設定的 targets 組成有序後備鏈，MUST 僅在「沒有審到」時換下一家，且 MUST NOT 在取得判定後繼續往下試。
+
+- Trigger: 某個已設定的 target 不存在、spawn 失敗或逾時。
+- Action: 試下一個 target；遇到 PASS、FAIL 或無法解析的輸出即停止並回報該結果。
+- Evidence: spawn 次數等於判定之前的失敗次數。
+- Positive: `codex 的 FAIL 是終局；不會再問 agy 第二意見。`
+- Negative: `FAIL 之後改試其他 target，直到有人回報 PASS。`
+
+## REVIEW-CONTRACT-001
+
+違反回覆約定的回應 MUST 回報為 NOT_RUN，而非 FAIL。
+
+- Trigger: 審查者遺漏、重複或憑空新增 criterion，或給出空白 evidence。
+- Action: 以 reason `unparseable-output` 回報 `NOT_RUN`，不寫入任何 evidence，並保留 FAIL 表示「經審查判定不合格」。
+- Evidence: 結果的 reason 能區分協議違規與判定結果。
+- Positive: `NOT_RUN：unparseable-output；缺少一條 criterion。`
+- Negative: `因為模型的 JSON 格式錯誤就記錄一次失敗的審查。`

package/package.json

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

package/schemas/config.schema.json

@@ -23,6 +23,35 @@
         "enum": ["core", "advisory", "guardrails", "loop"]
       }
     },
+    "reviewRoles": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["role", "targets"],
+        "properties": {
+          "role": {
+            "enum": [
+              "mechanical",
+              "implementation",
+              "deep-reasoning",
+              "independent-review"
+            ]
+          },
+          "targets": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": {
+              "enum": ["codex", "agy", "claude"]
+            }
+          },
+          "model": { "type": "string", "minLength": 1 },
+          "effort": { "type": "string", "minLength": 1 },
+          "timeoutMs": { "type": "integer", "minimum": 1 }
+        }
+      }
+    },
     "verification": {
       "type": "object",
       "additionalProperties": false,

package/schemas/evidence.schema.json

@@ -15,13 +15,16 @@
     "startedAt",
     "finishedAt",
     "exitCode",
+    "status",
+    "failureClass",
+    "sourceFingerprint",
     "testCount",
     "toolVersions",
     "configHash"
   ],
   "properties": {
     "schemaVersion": {
-      "const": 1
+      "const": 2
     },
     "taskId": {
       "$ref": "#/$defs/id"
@@ -62,6 +65,18 @@
       "minimum": 0,
       "maximum": 9007199254740991
     },
+    "status": {
+      "enum": ["PASS", "FAIL", "UNKNOWN"]
+    },
+    "failureClass": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "pattern": "^[^\\u0000]*$"
+    },
+    "sourceFingerprint": {
+      "$ref": "#/$defs/hash"
+    },
     "toolVersions": {
       "type": "object",
       "additionalProperties": {

package/schemas/review-report.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/kylecheng3146/agent-ops/schemas/review-report.schema.json",
+  "title": "Agent Ops detailed independent review report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["summary", "results", "findings", "residualRisks", "changedFilesInspected", "supportingFilesInspected"],
+  "properties": {
+    "summary": { "$ref": "#/$defs/text" },
+    "results": { "type": "array", "items": { "$ref": "#/$defs/result" } },
+    "findings": { "type": "array", "items": { "$ref": "#/$defs/finding" } },
+    "residualRisks": { "type": "array", "items": { "$ref": "#/$defs/text" } },
+    "changedFilesInspected": { "type": "array", "items": { "$ref": "#/$defs/path" }, "uniqueItems": true },
+    "supportingFilesInspected": { "type": "array", "items": { "$ref": "#/$defs/path" }, "uniqueItems": true }
+  },
+  "$defs": {
+    "text": { "type": "string", "minLength": 1, "maxLength": 16384, "pattern": "[^\\s\\u0000]" },
+    "path": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "^(?!/)(?!.*\\\\)(?!.*(?:^|/)\\.\\.(?:/|$))[A-Za-z0-9._/-]+$" },
+    "result": {
+      "type": "object", "additionalProperties": false,
+      "required": ["criterionId", "status", "summary", "evidence"],
+      "properties": {
+        "criterionId": { "$ref": "#/$defs/text" },
+        "status": { "enum": ["PASS", "FAIL"] },
+        "summary": { "$ref": "#/$defs/text" },
+        "evidence": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/text" } }
+      }
+    },
+    "location": {
+      "type": "object", "additionalProperties": false, "required": ["path"],
+      "properties": { "path": { "$ref": "#/$defs/path" }, "line": { "type": "integer", "minimum": 1 } }
+    },
+    "finding": {
+      "type": "object", "additionalProperties": false,
+      "required": ["severity", "blocking", "title", "details", "locations", "evidence", "recommendation", "criterionIds"],
+      "properties": {
+        "severity": { "enum": ["critical", "important", "minor"] },
+        "blocking": { "type": "boolean" },
+        "title": { "$ref": "#/$defs/text" },
+        "details": { "$ref": "#/$defs/text" },
+        "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" } }
+      }
+    }
+  }
+}