@kylecheng3146/agent-ops 0.1.3 → 0.1.5

package/dist/runtime/src/verify/evidence.js

@@ -1,32 +1,12 @@
 import { join } from "node:path";
-import { SCHEMA_VERSION } from "../contracts.js";
+import { EVIDENCE_SCHEMA_VERSION } from "../contracts.js";
 import { sha256 } from "../fs/hash.js";
 import { AgentOpsError } from "../fs/paths.js";
+import { calculateConfigHash } from "../config/hash.js";
+export { calculateConfigHash } from "../config/hash.js";
 import { validateEvidence } from "../schema/validate.js";
 import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
 import { redactSecrets } from "../security/redact.js";
-function canonicalJson(value) {
-    if (value === null ||
-        typeof value === "boolean" ||
-        typeof value === "number" ||
-        typeof value === "string") {
-        return JSON.stringify(value);
-    }
-    if (Array.isArray(value)) {
-        return `[${value.map(canonicalJson).join(",")}]`;
-    }
-    if (typeof value === "object") {
-        const record = value;
-        return `{${Object.keys(record)
-            .sort()
-            .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
-            .join(",")}}`;
-    }
-    throw new AgentOpsError("CONFIG_HASH_INVALID", "Configuration contains an unsupported value.");
-}
-export function calculateConfigHash(config) {
-    return sha256(canonicalJson(config));
-}
 function redactRecord(record) {
     return Object.fromEntries(Object.entries(record).map(([key, value]) => [
         redactSecrets(key),
@@ -43,7 +23,7 @@ function validateBuiltEvidence(value) {
 }
 export function buildVerificationEvidence(input) {
     return validateBuiltEvidence({
-        schemaVersion: SCHEMA_VERSION,
+        schemaVersion: EVIDENCE_SCHEMA_VERSION,
         taskId: input.taskId,
         criterionId: input.criterionId,
         commandId: input.command.id,

package/dist/runtime/src/verify/service.js

@@ -3,55 +3,11 @@ import { validateTaskAgainstConfig } from "../schema/validate.js";
 import { collectChangeSurface } from "./change-surface.js";
 import { buildVerificationEvidence } from "./evidence.js";
 import { createFailureFingerprint } from "./fingerprint.js";
+import { aggregateVerificationStatus, executeConfiguredCommand } from "./command-executor.js";
 import { selectVerificationScope } from "./scope.js";
-import { runVerificationCommand } from "./spawn.js";
-import { evaluateTestCount, parseTestCount } from "./test-count.js";
 function verificationError(code, message) {
     return new AgentOpsError(code, message);
 }
-function classifyTestCountCode(code) {
-    const classes = {
-        TEST_COUNT_BELOW_MINIMUM: "test-count-below-minimum",
-        TEST_COUNT_INVALID: "test-count-invalid",
-        TEST_COUNT_OK: "none",
-        TEST_COUNT_REQUIREMENT_INVALID: "test-count-requirement-invalid",
-        TEST_COUNT_UNPARSEABLE: "test-count-unparseable",
-        ZERO_TESTS: "zero-tests"
-    };
-    return classes[code];
-}
-function classifyResult(command, spawned) {
-    if (command.evidence.kind === "file") {
-        return {
-            status: spawned.status === "PASS" ? "UNKNOWN" : spawned.status,
-            failureClass: spawned.status === "PASS"
-                ? "file-evidence-unsupported"
-                : spawned.failureClass,
-            testCount: null
-        };
-    }
-    if (command.evidence.kind !== "test-count") {
-        return {
-            status: spawned.status,
-            failureClass: spawned.failureClass,
-            testCount: null
-        };
-    }
-    const testCount = parseTestCount(`${spawned.stdout}\n${spawned.stderr}`);
-    if (spawned.status !== "PASS") {
-        return {
-            status: spawned.status,
-            failureClass: spawned.failureClass,
-            testCount
-        };
-    }
-    const evaluation = evaluateTestCount(testCount, command.evidence.minimum);
-    return {
-        status: evaluation.status,
-        failureClass: classifyTestCountCode(evaluation.code),
-        testCount: evaluation.testCount
-    };
-}
 function exitCategory(result) {
     if (result.timedOut) {
         return "timeout";
@@ -64,17 +20,6 @@ function exitCategory(result) {
     }
     return result.exitCode === 0 ? "exit-zero" : "nonzero-exit";
 }
-function overallStatus(results) {
-    const required = results.filter((result) => result.required);
-    const gating = required.length > 0 ? required : results;
-    if (gating.some((result) => result.status === "FAIL")) {
-        return "FAIL";
-    }
-    if (gating.some((result) => result.status === "UNKNOWN")) {
-        return "UNKNOWN";
-    }
-    return "PASS";
-}
 function relevantCriteria(task, commandId) {
     return task.criteria.filter((criterion) => criterion.verifierIds.includes(commandId));
 }
@@ -85,9 +30,6 @@ function commandById(config, commandId) {
     }
     return command;
 }
-function diagnostics(spawned) {
-    return spawned.stderr || spawned.stdout || spawned.failureClass;
-}
 export class VerificationService {
     #options;
     constructor(options) {
@@ -120,51 +62,37 @@ export class VerificationService {
     }
     async #runCommand(task, command) {
         const startedAt = (this.#options.now ?? (() => new Date().toISOString()))();
-        const spawned = this.#options.trusted
-            ? await runVerificationCommand(command, {
-                cwd: await this.#commandCwd(command),
-                runner: this.#options.processRunner
-            })
-            : {
-                commandId: command.id,
-                status: "UNKNOWN",
-                failureClass: "repository-untrusted",
-                exitCode: null,
-                signal: null,
-                timedOut: false,
-                durationMs: 0,
-                stdout: "",
-                stderr: "",
-                stdoutTruncated: false,
-                stderrTruncated: false
-            };
-        const classified = classifyResult(command, spawned);
-        const fingerprint = classified.status === "PASS"
+        const result = await executeConfiguredCommand(command, {
+            cwd: await this.#commandCwd(command),
+            runner: this.#options.processRunner,
+            trusted: this.#options.trusted
+        });
+        const fingerprint = result.status === "PASS"
             ? null
             : createFailureFingerprint({
                 commandId: command.id,
-                failureClass: classified.failureClass,
-                exitCategory: spawned.timedOut
+                failureClass: result.failureClass,
+                exitCategory: result.timedOut
                     ? "timeout"
-                    : spawned.signal !== null
+                    : result.signal !== null
                         ? "signal-exit"
-                        : spawned.exitCode === null
+                        : result.exitCode === null
                             ? "no-exit"
-                            : spawned.exitCode === 0
+                            : result.exitCode === 0
                                 ? "exit-zero"
                                 : "nonzero-exit",
-                diagnostics: diagnostics(spawned)
+                diagnostics: result.diagnostic
             });
         const finishedAt = (this.#options.now ?? (() => new Date().toISOString()))();
-        const evidenceReferences = await this.#persistEvidence(task, command, startedAt, finishedAt, classified, spawned.exitCode);
+        const evidenceReferences = await this.#persistEvidence(task, command, startedAt, finishedAt, result, result.exitCode);
         return {
             commandId: command.id,
             required: command.required,
-            status: classified.status,
-            failureClass: classified.failureClass,
-            exitCode: spawned.exitCode,
-            timedOut: spawned.timedOut,
-            testCount: classified.testCount,
+            status: result.status,
+            failureClass: result.failureClass,
+            exitCode: result.exitCode,
+            timedOut: result.timedOut,
+            testCount: result.testCount,
             diagnostic: fingerprint?.diagnostics ?? "",
             evidenceReferences
         };
@@ -185,7 +113,7 @@ export class VerificationService {
         for (const commandId of selection.verifierIds) {
             results.push(await this.#runCommand(validation.value, commandById(this.#options.config, commandId)));
         }
-        const status = overallStatus(results);
+        const status = aggregateVerificationStatus(results);
         let signal = null;
         if (status === "PASS") {
             await this.#options.taskService.clearFailure(taskId);

package/dist/runtime/src/verify/spawn.js

@@ -138,6 +138,10 @@ export class NodeVerificationProcessRunner {
         const child = spawn(request.command, [...request.args], {
             cwd: request.cwd,
             detached: this.#platform !== "win32",
+            env: {
+                ...process.env,
+                ...(request.env ?? {})
+            },
             shell: request.shell,
             stdio: ["ignore", "pipe", "pipe"],
             windowsHide: true
@@ -258,7 +262,8 @@ export async function runVerificationCommand(command, options) {
             command: command.command,
             args: [...command.args],
             cwd: options.cwd,
-            shell: command.shell === true
+            shell: command.shell === true,
+            ...(options.env === undefined ? {} : { env: options.env })
         });
     }
     catch {

package/docs/en/guides/configuration.md

@@ -0,0 +1,83 @@
+# Configuration
+
+Keep project configuration explicit and layered. Choose scope, harness, and profile deliberately; do not infer trust or security exceptions from `--yes`.
+
+Use `--harness all` to select Codex, Claude Code, and opencode, or pass a
+comma-separated subset such as `codex,opencode`. `both` remains an input alias
+for the legacy Codex plus Claude selection.
+
+Project Codex and opencode installations share the managed supplemental
+`AGENTS.md` routing block and the `.agent-ops/AGENTS.md` rules artifact. The
+block loads the managed baseline while project-specific instructions remain
+authoritative. Claude uses the corresponding `CLAUDE.md` route and
+`.agent-ops/CLAUDE.md` artifact. Opencode additionally gets
+the agent-ops-owned `.opencode/plugins/agent-ops.js` file; `opencode.json` is
+never modified. The plugin is generated with the installed absolute runtime
+path, so update it through `agent-ops update` rather than editing it manually.
+
+At user scope, Codex and opencode keep separate routing files under `.codex/`
+and `.opencode/`; the global opencode plugin is placed under
+`.config/opencode/plugins/`, or under `$XDG_CONFIG_HOME/opencode/plugins/`
+when that variable points inside the managed user root. If OpenCode is
+configured with `$OPENCODE_CONFIG_DIR`, the plugin is placed under its
+`plugins/` directory instead. The installer discovers writable harness
+surfaces and applies the selected target policy; use
+`--hook-target <harness>=<surface-id>` when the managed default is not the
+intended surface. Project-local Claude settings require that explicit target.
+Advisory and guardrail hooks are registered only when the selected profile
+implies them. Advisory runs through the real SessionStart path and is
+fail-open. Claude and Codex lifecycle support is `supported`; OpenCode begins
+at app initialization and is honestly reported as `degraded`.
+
+`guardrails` installs command policy but does not enable Stop verification. Stop
+is a separate config-v2 feature and must be explicitly enabled with at least
+one confirmed command:
+
+```json
+{
+  "features": { "stopVerification": { "enabled": true } },
+  "verification": {
+    "commands": [
+      {
+        "id": "unit",
+        "command": "npm",
+        "args": ["test"],
+        "cwd": ".",
+        "required": true,
+        "evidence": { "kind": "test-count", "minimum": 1 }
+      }
+    ]
+  }
+}
+```
+
+Changing this feature changes native registration. Run:
+
+```bash
+agent-ops update
+agent-ops trust grant
+```
+
+Without `update`, doctor reports `UPDATE_REQUIRED`; without the new trust
+grant, trust-gated hooks remain stale. Stop is report-only: it continues the
+harness for `PASS`, `FAIL`, or `UNKNOWN`, emits only bounded command ID, exit
+code, test-count, config-hash, and timestamp evidence, and never completes a
+task. Config v1 migrates deterministically to v2 with Stop disabled; old
+binaries cannot read the migrated config, and the routing migration is
+one-way after it is applied.
+
+To narrow an existing installation, pass the desired list to `agent-ops update
+--harness`; shared paths remain managed while removed harness-owned artifacts,
+markers, and hooks are reconciled.
+
+Installations using the previous canonical routing wording are migrated by
+`agent-ops update`. If a managed block was edited, the command fails closed
+until the change is reviewed.
+
+Dry-run human and JSON plans omit raw harness settings content. They expose the
+expected hash, content hash, and a safe summary while the internal apply plan
+retains the complete merged settings. The manifest remains schema v2.
+
+Use the [acceptance and evidence rules](../spec/acceptance-and-evidence.md)
+when adding verification commands, and the [adapter rules](../spec/harness-adapters.md)
+when configuring Codex, Claude Code, or opencode behavior.

package/docs/en/guides/quickstart.md

@@ -0,0 +1,9 @@
+# Quickstart
+
+1. Define 2–5 acceptance criteria.
+2. Inspect the smallest relevant scope.
+3. Run a failing test before implementation.
+4. Implement the smallest change, then run typecheck and tests.
+5. Record evidence and request independent review before handoff.
+
+See the [normative loop](../spec/loop-engineering.md) and [review rules](../spec/review.md).

package/docs/en/guides/security.md

@@ -0,0 +1,5 @@
+# Security
+
+Treat commands, logs, configuration, and external input as untrusted. Redact credentials, block destructive commands by default, and keep local state out of tracked project paths.
+
+Read the [guardrails](../spec/guardrails.md), [judgment rules](../spec/judgment.md), and [maintenance rules](../spec/maintenance.md) before changing policy or hook files.

package/docs/en/spec/README.md

@@ -2,6 +2,15 @@
 
 This is the normative English specification for bounded, evidence-driven work.
 
+The harness adapter rules cover Codex, Claude Code, and opencode. The opencode
+integration is a generated local plugin; it does not manage `opencode.json`.
+
+Configuration is versioned independently from the manifest. Config v1 migrates
+to config v2 with Stop verification disabled; changing the capability requires
+`agent-ops update` followed by `agent-ops trust grant`. Stop verification is
+explicit, trusted, report-only, and never completes a task. Dry-run plans keep
+foreign settings opaque, and the routing migration is one-way once applied.
+
 - [Loop engineering](./loop-engineering.md)
 - [Acceptance and evidence](./acceptance-and-evidence.md)
 - [Judgment](./judgment.md)

package/docs/en/spec/harness-adapters.md

@@ -1,12 +1,19 @@
 # Harness Adapters
 
+OpenCode plugin behavior in this document was checked against the [official
+plugin documentation](https://opencode.ai/docs/plugins/) and [Bun shell
+documentation](https://bun.sh/docs/runtime/shell) on 2026-07-31. Revalidate:
+when either vendor reference changes.
+
 ## HARNESS-ADAPTER-001
 
-An adapter MUST preserve native harness semantics and MUST label unsupported behavior as UNKNOWN.
+An adapter MUST preserve native harness semantics and MUST declare each
+capability as supported, degraded, unsupported, or unknown.
 
 - Trigger: Mapping portable lifecycle or review behavior into a native harness.
 - Action: Keep ownership narrow, retain user configuration, and document limitations.
-- Evidence: Adapter tests cover existing configuration and unsupported outcomes.
+- Evidence: Adapter tests cover existing configuration, support declarations,
+  and native failure outcomes.
 - Positive: `A Codex blocking outcome remains UNKNOWN when native denial is unconfirmed.`
 - Negative: `Assume Claude exit semantics apply to Codex.`
 
@@ -19,3 +26,60 @@ An adapter MUST be idempotent and MUST avoid deleting user-owned handlers.
 - Evidence: Existing configuration fixtures remain intact after apply and uninstall.
 - Positive: `Managed handler updates while unrelated handlers remain byte-for-byte present.`
 - Negative: `Replace the complete settings file with toolkit defaults.`
+
+## HARNESS-ADAPTER-003
+
+A file-backed adapter MUST register only hooks implied by the active
+capabilities and MUST track generated source as one whole-file artifact.
+
+- Trigger: Installing or probing a harness whose extension point is a plugin file.
+- Action: For opencode, manage `.opencode/plugins/agent-ops.js` in a project or `.config/opencode/plugins/agent-ops.js` at user scope (`$XDG_CONFIG_HOME/opencode/plugins/agent-ops.js` when configured inside the managed user root, or `$OPENCODE_CONFIG_DIR/plugins/agent-ops.js` when that native config directory is configured), leave `opencode.json` untouched, and deduplicate a project `AGENTS.md` contribution by path.
+- Evidence: The manifest contains the plugin hash, the generated source contains only the selected hook registrations, and shared project markers occur once.
+- Positive: `codex,opencode` produces one project AGENTS route and one hashed opencode plugin.
+- Negative: `Add an opencode.json instructions entry or register a plugin for a core-only profile.`
+
+## HARNESS-ADAPTER-004
+
+The opencode shim MUST invoke the absolute runtime path from the selected
+project directory, MUST fail open for
+advisory events, and MUST fail closed for command-policy events when the
+runtime is unavailable.
+
+- Trigger: The generated plugin invokes `agent-ops` or receives an invalid runtime decision.
+- Action: Keep normalization and native output encoding in the runtime adapter,
+  throw the policy reason for a deny decision, and run lifecycle-summary through
+  the shared advisory implementation. App-scoped plugin initialization remains
+  degraded for per-session lifecycle fidelity.
+- Evidence: Shim import tests cover allow, deny, and missing-runtime behavior;
+  doctor reports OpenCode lifecycle support as `DEGRADED`.
+- Positive: `A missing runtime does not block SessionStart but blocks a bash tool before execution.`
+- Negative: `Fall back to a PATH-resolved agent-ops executable or claim app initialization is a per-session Stop-equivalent.`
+
+## HARNESS-ADAPTER-005
+
+Each descriptor MUST expose separate control and runtime adapters. The control
+adapter owns installation planning, routing, ownership, probes, and the
+in-memory capability registration matrix. The runtime adapter owns native input
+decoding, normalized events, native output encoding, and runtime-failure output.
+
+- Trigger: Adding a harness surface or a generic capability.
+- Action: Add the capability-to-native registration to the owning harness,
+  including its support level and runtime-failure mode; do not add native
+  events to a universal union.
+- Evidence: Every declared `supported` registration is exercised through the
+  real CLI hook process, and unsupported Stop/lifecycle registrations are not
+  reported as enforcement success.
+- Positive: `Claude command-policy reaches a native PreToolUse denial through runHookCommand.`
+- Negative: `Mark SessionStart supported while dispatchHookEvent has no advisory implementation.`
+
+The current registration matrix is intentionally asymmetric:
+
+| Capability | Codex | Claude Code | OpenCode |
+| --- | --- | --- | --- |
+| lifecycle-summary | supported | supported | degraded |
+| command-policy | unknown | supported | supported |
+| optional-stop-verify | unsupported | supported | degraded |
+
+Stop verification is explicit, trusted, report-only, and disabled by default.
+Every Stop result continues the native harness and may carry only bounded
+command evidence; it is never task-completion evidence.

package/docs/en/spec/maintenance.md

@@ -19,3 +19,14 @@ Volatile harness facts MUST live in adapter or research documentation and MUST i
 - Evidence: The document has a source and `Revalidate:` condition.
 - Positive: `Revalidate: when the vendor hook reference changes.`
 - Negative: `Treat a transient CLI flag as a permanent core rule.`
+
+## MAINTAIN-PLUGIN-001
+
+Generated harness plugins MUST be treated as managed artifacts and MUST NOT be
+hand-edited in place.
+
+- Trigger: Updating the runtime, capabilities, or a vendor plugin contract.
+- Action: Regenerate the opencode shim, verify its manifest hash, and revalidate the vendor behavior before release.
+- Evidence: The artifact hash and shim import tests pass; release documentation records the revalidation condition.
+- Positive: `agent-ops update` rewrites a changed plugin after ownership checks pass.
+- Negative: `Patch the opencode plugin manually and retain the old manifest hash.`

package/docs/en/spec/review.md

@@ -19,3 +19,14 @@ A review result MUST preserve PASS, FAIL, or NOT_RUN and MUST NOT convert NOT_RU
 - Evidence: The result states harness, configured model or limitation, effort, and reason.
 - Positive: `NOT_RUN: login required; prompt is copyable.`
 - Negative: `No reviewer ran, but mark the change PASS.`
+
+## REVIEW-HARNESS-001
+
+A review invocation MUST resolve to exactly one concrete harness, even when an
+installation supports multiple harnesses.
+
+- Trigger: Running `review` with a harness selection.
+- Action: Select one of `codex`, `claude`, or `opencode`; keep multi-harness installation separate from review execution.
+- Evidence: Argument parsing rejects `all`, `both`, and comma-separated multi-harness values for review.
+- Positive: `review --harness opencode` resolves one harness.
+- Negative: `Run one review invocation against every installed harness implicitly.`

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

@@ -0,0 +1,77 @@
+# 設定
+
+保持 project 設定明確且分層。請刻意選擇 scope、harness 與 profile；不要從 `--yes` 推論 trust 或安全例外。
+
+使用 `--harness all` 選取 Codex、Claude Code 與 opencode，或傳入
+`codex,opencode` 這類逗號分隔的子集。`both` 仍是 legacy Codex 加 Claude
+selection 的 input alias。
+
+Project Codex 與 opencode installation 共用 managed supplemental
+`AGENTS.md` routing block 與 `.agent-ops/AGENTS.md` rules artifact。該 block
+只載入 managed baseline，並保留 project-specific instructions 的權威性。
+Claude 使用對應的 `CLAUDE.md` route 與 `.agent-ops/CLAUDE.md` artifact。Opencode 另外取得
+agent-ops 擁有的 `.opencode/plugins/agent-ops.js`；不會修改 `opencode.json`。
+Plugin 使用安裝時的 absolute runtime path 產生，因此請透過
+`agent-ops update` 更新，不要手動編輯。
+
+User scope 下，Codex 與 opencode 的 routing file 分別位於 `.codex/` 與
+`.opencode/`；global opencode plugin 預設位於 `.config/opencode/plugins/`，
+若 `$XDG_CONFIG_HOME` 指向 managed user root 內的目錄，則改用
+`$XDG_CONFIG_HOME/opencode/plugins/`。若 OpenCode 設定了
+`$OPENCODE_CONFIG_DIR`，則 plugin 會放在其 `plugins/` 目錄。只有 profile
+有暗示時才會註冊 advisory 與 guardrail hook。Installer 會 discovery 可寫入的
+harness surface 並套用選定的 target policy；若不是 managed default，請使用
+`--hook-target <harness>=<surface-id>` 明確選擇。Project-local Claude settings
+必須明確指定 target。Advisory 會經由真正的 SessionStart path 執行並 fail-open；
+Claude 與 Codex lifecycle support 為 `supported`，OpenCode 從 app initialization
+開始，因此誠實標示為 `degraded`。
+
+`guardrails` 只安裝 command policy，不會啟用 Stop verification。Stop 是獨立的
+config v2 feature，必須明確啟用且至少提供一個已確認的 command：
+
+```json
+{
+  "features": { "stopVerification": { "enabled": true } },
+  "verification": {
+    "commands": [
+      {
+        "id": "unit",
+        "command": "npm",
+        "args": ["test"],
+        "cwd": ".",
+        "required": true,
+        "evidence": { "kind": "test-count", "minimum": 1 }
+      }
+    ]
+  }
+}
+```
+
+變更此 feature 會改變 native registration，請依序執行：
+
+```bash
+agent-ops update
+agent-ops trust grant
+```
+
+未執行 `update` 時，doctor 會回報 `UPDATE_REQUIRED`；未重新 grant trust
+時，trust-gated hook 仍會是 stale。Stop 是 report-only：`PASS`、`FAIL` 與
+`UNKNOWN` 都會讓 harness 繼續，只輸出有界的 command ID、exit code、test-count、
+config-hash 與 timestamp evidence，且永遠不會完成 task。Config v1 會決定性遷移
+為 Stop disabled 的 v2；舊 binary 無法讀取遷移後的 config，routing migration
+一旦套用即為單向，降版前請先閱讀 release notes。
+
+若要縮減既有 installation，請將目標清單傳給
+`agent-ops update --harness`；shared path 會繼續受管理，被移除 harness
+擁有的 artifact、marker 與 hook 則會被安全同步。
+
+使用舊版 canonical routing wording 的 installation 會由
+`agent-ops update` 遷移；若 managed block 曾被修改，指令會 fail closed，
+直到該變更被檢查。
+
+Dry-run 的 human 與 JSON plan 不會輸出原始 harness settings 內容，只提供
+expected hash、content hash 與安全摘要；internal apply plan 仍保留完整合併後的設定。
+Manifest 維持 schema v2。
+
+新增驗證命令時使用[驗收與證據規則](../../en/spec/acceptance-and-evidence.md)，
+設定 Codex、Claude Code 或 opencode 行為時使用[adapter 規則](../../en/spec/harness-adapters.md)。

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

@@ -0,0 +1,9 @@
+# 快速開始
+
+1. 定義 2–5 個驗收條件。
+2. 檢查最小相關範圍。
+3. 實作前先讓測試失敗。
+4. 做最小變更，再執行 typecheck 與測試。
+5. 記錄證據，交接前請求獨立審查。
+
+請參考[規範迴圈](../../en/spec/loop-engineering.md)與[審查規則](../../en/spec/review.md)。

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

@@ -0,0 +1,5 @@
+# 安全
+
+將命令、log、設定與外部輸入視為不可信。遮罩憑證、預設阻擋破壞性命令，並讓本機狀態留在 tracked project path 之外。
+
+修改政策或 hook 前，閱讀[防護規則](../../en/spec/guardrails.md)、[判斷規則](../../en/spec/judgment.md)與[維護規則](../../en/spec/maintenance.md)。

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

@@ -2,6 +2,15 @@
 
 此目錄是英文規範的繁體中文導讀；規範 rule ID 以英文版本為準。
 
+Harness adapter 規則涵蓋 Codex、Claude Code 與 opencode。opencode 整合是
+產生的 local plugin，不管理 `opencode.json`。
+
+Configuration 與 manifest 分開版本化。Config v1 會遷移為預設 disabled Stop
+verification 的 config v2；變更 capability 後必須先執行 `agent-ops update`，
+再執行 `agent-ops trust grant`。Stop verification 必須明確啟用、具備 trust、
+為 report-only，且永遠不會完成 task。Dry-run plan 會隱藏 foreign settings
+內容；routing migration 一旦套用即為單向。
+
 - [迴圈工程](./loop-engineering.md)
 - [驗收與證據](./acceptance-and-evidence.md)
 - [判斷](./judgment.md)

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

@@ -1,14 +1,17 @@
 # Harness Adapter
 
-English source version: 2026-07-23. Revalidate: when the English specification changes.
+English source version: 2026-07-31. Revalidate: when the English specification or either vendor reference changes.
+
+本文件所述 OpenCode plugin 行為已於 2026-07-31 依據[官方 plugin 文件](https://opencode.ai/docs/plugins/)與[Bun shell 文件](https://bun.sh/docs/runtime/shell)檢查。
 
 ## HARNESS-ADAPTER-001
 
-Adapter MUST 保留原生 harness 語意，並將未支援行為標示為 UNKNOWN。
+Adapter MUST 保留原生 harness 語意，並為每項 capability 宣告
+supported、degraded、unsupported 或 unknown。
 
 - Trigger: 將可攜 lifecycle 或 review 行為映射到原生 harness。
 - Action: 保持 ownership 狹窄、保留使用者設定並記錄限制。
-- Evidence: adapter 測試涵蓋既有設定與未支援結果。
+- Evidence: adapter 測試涵蓋既有設定、support 宣告與原生 failure 行為。
 - Positive: `Codex blocking outcome 未確認原生 denial 時保持 UNKNOWN。`
 - Negative: `假設 Claude exit semantics 適用 Codex。`
 
@@ -21,3 +24,54 @@ Adapter MUST 具備冪等性，且 MUST NOT 刪除使用者擁有的 handler。
 - Evidence: 既有設定 fixture 在 apply 與 uninstall 後保持完整。
 - Positive: `更新 managed handler，無關 handler 仍逐位元存在。`
 - Negative: `以 toolkit defaults 取代整份 settings。`
+
+## HARNESS-ADAPTER-003
+
+檔案型 adapter MUST 只註冊 active capabilities 所暗示的 hook，且 MUST 將產生的 source 當成一個 whole-file artifact 管理。
+
+- Trigger: 安裝或探測 extension point 是 plugin 檔案的 harness。
+- Action: 對 opencode 在 project 管理 `.opencode/plugins/agent-ops.js`、在 user scope 預設管理 `.config/opencode/plugins/agent-ops.js`（若 `$XDG_CONFIG_HOME` 指向 managed user root 內的目錄，則使用其下的 `opencode/plugins/agent-ops.js`；若設定原生 `$OPENCODE_CONFIG_DIR`，則使用其下的 `plugins/agent-ops.js`），不修改 `opencode.json`；project `AGENTS.md` 的 contribution 依 path 去重。
+- Evidence: manifest 含 plugin hash，產生的 source 只含選定的 hook，shared project marker 只出現一次。
+- Positive: `codex,opencode` 產生一個 project AGENTS route 與一個有 hash 的 opencode plugin。
+- Negative: `新增 opencode.json instructions entry，或在只有 core profile 時註冊 plugin。`
+
+## HARNESS-ADAPTER-004
+
+OpenCode shim MUST 從選定的 project directory 呼叫 absolute runtime path；runtime 不可用時，MUST 對 advisory event fail open，並對 command-policy event fail closed。
+
+- Trigger: 產生的 plugin 呼叫 `agent-ops`，或收到無效的 runtime decision。
+- Action: 將 normalization 與 native output encoding 留在 runtime adapter；deny
+  decision 要 throw policy reason；lifecycle-summary 經由 shared advisory
+  implementation 執行。Plugin initialization 仍是 app-scoped 而非 per-session，
+  因此 per-session lifecycle fidelity 仍為 degraded。
+- Evidence: shim import 測試涵蓋 allow、deny 與 missing-runtime；doctor 對
+  OpenCode lifecycle support 回報 `DEGRADED`。
+- Positive: `runtime 不可用時不阻擋 SessionStart，但會在 bash tool 執行前阻擋它。`
+- Negative: `退回 PATH-resolved 的 agent-ops executable，或宣稱 app initialization 等同於 per-session Stop。`
+
+## HARNESS-ADAPTER-005
+
+每個 descriptor MUST 分離 control 與 runtime adapter。control adapter 負責
+installation plan、routing、ownership、probe 與 in-memory capability
+registration matrix；runtime adapter 負責 native input decode、normalized
+event、native output encode 與 runtime-failure output。
+
+- Trigger: 新增 harness surface 或 generic capability。
+- Action: 在所屬 harness 加入 capability-to-native registration，包含 support
+  level 與 runtime-failure mode；不得將 native event 加入 universal union。
+- Evidence: 每個宣告為 `supported` 的 registration 都經由真實 CLI hook process
+  執行，未支援的 Stop/lifecycle registration 不得回報 enforcement success。
+- Positive: `Claude command-policy 經由 runHookCommand 抵達 native PreToolUse denial。`
+- Negative: `dispatchHookEvent 尚未提供 advisory implementation 卻將 SessionStart 標為 supported。`
+
+目前 registration matrix 刻意不對稱：
+
+| Capability | Codex | Claude Code | OpenCode |
+| --- | --- | --- | --- |
+| lifecycle-summary | supported | supported | degraded |
+| command-policy | unknown | supported | supported |
+| optional-stop-verify | unsupported | supported | degraded |
+
+Stop verification 必須明確啟用、具備 trust、為 report-only 且預設 disabled。
+每個 Stop 結果都會讓 native harness 繼續，最多攜帶有界 command evidence，永遠
+不是 task-completion evidence。