protocol: add conformance verification gate

.github/workflows/verify.yml

@@ -0,0 +1,22 @@
+name: Verify
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  verify:
+    runs-on: macos-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Show tool versions
+        run: |
+          node --version
+          swift --version
+
+      - name: Run local verification gate
+        run: bash scripts/verify-local.sh

AGENTS.md

@@ -120,13 +120,21 @@ Project-local coordination notes are ignored by Git and are not project source-o
 Run from the repository root when touching runtime or protocol behavior:
 
 ```bash
+bash scripts/verify-local.sh
+```
+
+The expanded core commands are:
+
+```bash
+node scripts/verify-protocol-conformance.mjs
 swiftc -typecheck runtimes/desktop-gui/src/action_executor.swift
 swiftc -typecheck runtimes/desktop-gui/src/scene_runner.swift
 swiftc -typecheck runtimes/desktop-gui/src/task_flow.swift
 bash runtimes/desktop-gui/scripts/smoke.sh
 ```
 
 Expected smoke success: `SMOKE_OK`.
+Pull requests run the same local gate through `.github/workflows/verify.yml`.
 
 ## Spec Checkpoint
 

README.md

@@ -117,10 +117,19 @@ as adapters or forked projects.
 Run from the repository root:
 
 ```bash
+bash scripts/verify-local.sh
+```
+
+The script runs the protocol conformance checks, adapter syntax checks, desktop GUI runtime
+typechecks, shell syntax checks, and smoke test. The expanded core commands are:
+
+```bash
+node scripts/verify-protocol-conformance.mjs
 swiftc -typecheck runtimes/desktop-gui/src/action_executor.swift
 swiftc -typecheck runtimes/desktop-gui/src/scene_runner.swift
 swiftc -typecheck runtimes/desktop-gui/src/task_flow.swift
 bash runtimes/desktop-gui/scripts/smoke.sh
 ```
 
 Expected smoke result: `SMOKE_OK`.
+Pull requests run the same local gate through `.github/workflows/verify.yml`.

README.zh-CN.md

@@ -99,10 +99,19 @@ P0 定义为：
 在仓库根目录运行：
 
 ```bash
+bash scripts/verify-local.sh
+```
+
+这个脚本会执行协议 conformance、适配器语法检查、desktop GUI runtime typecheck、shell
+语法检查和 smoke。展开后的核心命令是：
+
+```bash
+node scripts/verify-protocol-conformance.mjs
 swiftc -typecheck runtimes/desktop-gui/src/action_executor.swift
 swiftc -typecheck runtimes/desktop-gui/src/scene_runner.swift
 swiftc -typecheck runtimes/desktop-gui/src/task_flow.swift
 bash runtimes/desktop-gui/scripts/smoke.sh
 ```
 
 期望 smoke 输出：`SMOKE_OK`。
+Pull Request 会通过 `.github/workflows/verify.yml` 运行同一个本地 gate。

protocol/README.md

@@ -29,6 +29,10 @@ documents:
     L1: protocol/L1-runtime-capability-manual.md
     L2: protocol/L2-surface-manual.md
     L3: protocol/L3-scenario-requirements.md
+  machine_verifiable_contracts:
+    schemas: protocol/schemas/
+    fixtures: protocol/fixtures/
+    local_check: node scripts/verify-protocol-conformance.mjs
   integration: integration/host-embedding.md
 runtime:
   desktop_gui_reference:
@@ -232,6 +236,19 @@ host_integration:
   Capabilities: { command: "action_executor capabilities", defined_in: "INT section 7" }
 ```
 
+Machine-verifiable schemas currently cover the first stable wire slice:
+
+- `protocol/schemas/action-plan.schema.json`
+- `protocol/schemas/action-result.schema.json`
+- `protocol/schemas/error-envelope.schema.json`
+- `protocol/schemas/scenario-manifest.schema.json`
+
+Fixtures under `protocol/fixtures/` provide one valid and one intentionally invalid example per
+object. Run `node scripts/verify-protocol-conformance.mjs` to check the fixtures, the current
+desktop GUI reference manifest, and runtime-backed negative cases for stable error-envelope
+reasons. These schemas verify current wire shapes; the prose protocol files remain authoritative
+for semantics, layer boundaries, and future extension rules.
+
 ## 5. Cross-Cutting Invariants
 
 These invariants bind the root contract, current reference specs, and runtime files.
@@ -313,6 +330,9 @@ playbooks:
       - "no model calls or task-success judgement entered runtime/adapters"
       - "binding-block citations still point to valid sections"
   run_checks:
+    local_gate: "bash scripts/verify-local.sh"
+    ci_gate: ".github/workflows/verify.yml"
+    conformance: "node scripts/verify-protocol-conformance.mjs"
     typecheck:
       - "swiftc -typecheck runtimes/desktop-gui/src/action_executor.swift"
       - "swiftc -typecheck runtimes/desktop-gui/src/scene_runner.swift"

protocol/fixtures/action-plan.invalid.json

@@ -0,0 +1,6 @@
+{
+  "schemaVersion": 1,
+  "kind": "action_plan",
+  "dryRun": true,
+  "actions": []
+}

protocol/fixtures/action-plan.valid.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": 1,
+  "kind": "action_plan",
+  "wireFormat": "openai_computer_call_compatible",
+  "call_id": "fixture_action_plan_valid",
+  "pending_safety_checks": [],
+  "confirmationStatus": "not_required",
+  "dryRun": true,
+  "allowNegativeWindowOrigin": false,
+  "actions": [
+    { "type": "keypress", "keys": ["ESC"], "mode": "hid" },
+    { "type": "wait", "durationMs": 1 }
+  ]
+}

protocol/fixtures/action-result.invalid.json

@@ -0,0 +1,7 @@
+{
+  "ok": false,
+  "kind": "action_result",
+  "results": [
+    { "ok": true, "type": "wait", "dryRun": true }
+  ]
+}

protocol/fixtures/action-result.valid.json

@@ -0,0 +1,11 @@
+{
+  "ok": true,
+  "kind": "action_result",
+  "wireFormat": "openai_computer_call_result_compatible",
+  "call_id": "fixture_action_plan_valid",
+  "dryRun": true,
+  "results": [
+    { "index": 0, "ok": true, "type": "keypress", "dryRun": true, "appLabel": "target app" },
+    { "index": 1, "ok": true, "type": "wait", "dryRun": true, "appLabel": "target app" }
+  ]
+}

protocol/fixtures/error-envelope.invalid.json

@@ -0,0 +1,6 @@
+{
+  "ok": false,
+  "kind": "error",
+  "reason": "PendingSafetyApproval",
+  "message": ""
+}

protocol/fixtures/error-envelope.valid.json

@@ -0,0 +1,8 @@
+{
+  "ok": false,
+  "kind": "error",
+  "reason": "pending_safety_approval",
+  "message": "pending_safety_checks require confirmationStatus=approved",
+  "call_id": "fixture_safety_gate",
+  "pendingSafetyCheckCount": 1
+}

protocol/fixtures/scenario-manifest.invalid.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "scene": "fixture-surface",
+  "profile": {},
+  "intents": {
+    "closeOverlay": {
+      "required": [],
+      "steps": []
+    }
+  }
+}

protocol/fixtures/scenario-manifest.valid.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": 1,
+  "scene": "fixture-surface",
+  "profile": {
+    "bundleID": "com.example.placeholder",
+    "ownerNames": ["PlaceholderApp"],
+    "appLabel": "PlaceholderApp"
+  },
+  "intents": {
+    "closeOverlay": {
+      "required": [],
+      "defaults": { "mode": "hid", "dryRun": true },
+      "steps": [
+        { "type": "keypress", "fields": { "keys": ["ESC"], "mode": "${mode}" } }
+      ]
+    }
+  }
+}

protocol/schemas/action-plan.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cloudsbeyond.github.io/visual-agent/protocol/schemas/action-plan.schema.json",
+  "title": "ActionPlan",
+  "description": "L1 ActionPlan consumed by the runtime capability executor.",
+  "type": "object",
+  "required": ["schemaVersion", "kind", "actions"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "action_plan" },
+    "wireFormat": { "type": "string" },
+    "call_id": { "type": "string", "minLength": 1 },
+    "status": { "type": "string" },
+    "pending_safety_checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string" },
+          "code": { "type": "string" },
+          "message": { "type": "string" }
+        }
+      }
+    },
+    "confirmationStatus": {
+      "type": "string",
+      "enum": ["not_required", "pending", "approved", "denied"]
+    },
+    "dryRun": { "type": "boolean" },
+    "bundleID": { "type": "string" },
+    "ownerNames": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "appLabel": { "type": "string" },
+    "allowNegativeWindowOrigin": { "type": "boolean" },
+    "actions": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/action" }
+    }
+  },
+  "$defs": {
+    "action": {
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["click", "scroll", "keypress", "wait", "screenshot", "type", "drag", "move", "double_click"]
+        },
+        "x": { "type": "number" },
+        "y": { "type": "number" },
+        "width": { "type": "number", "minimum": 0 },
+        "height": { "type": "number", "minimum": 0 },
+        "scrollX": { "type": "number" },
+        "scrollY": { "type": "number" },
+        "times": { "type": "integer", "minimum": 1 },
+        "button": { "type": "string" },
+        "keys": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "durationMs": { "type": "integer", "minimum": 0 },
+        "output": { "type": "string", "minLength": 1 },
+        "maxEdge": { "type": "integer", "minimum": 1 },
+        "mode": { "type": "string", "enum": ["cliclick", "hid", "pid"] },
+        "coordinateSpace": {
+          "type": "string",
+          "enum": ["windowTopLeft", "windowBottomLeft", "screenTopLeft", "screenBottomLeft"]
+        },
+        "restoreMouse": { "type": "boolean" },
+        "dryRun": { "type": "boolean" },
+        "allowNegativeWindowOrigin": { "type": "boolean" }
+      }
+    }
+  }
+}

protocol/schemas/action-result.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cloudsbeyond.github.io/visual-agent/protocol/schemas/action-result.schema.json",
+  "title": "ActionResult",
+  "description": "L1 runtime result. ok:true means runtime dispatch/completion only, never task success.",
+  "type": "object",
+  "required": ["ok", "kind", "results"],
+  "properties": {
+    "ok": { "const": true },
+    "kind": { "const": "action_result" },
+    "wireFormat": { "type": "string" },
+    "call_id": { "type": "string" },
+    "dryRun": { "type": "boolean" },
+    "results": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["index", "ok", "type", "dryRun"],
+        "properties": {
+          "index": { "type": "integer", "minimum": 0 },
+          "ok": { "type": "boolean" },
+          "type": { "type": "string", "minLength": 1 },
+          "dryRun": { "type": "boolean" },
+          "appLabel": { "type": "string" },
+          "resolved": { "type": "object" },
+          "message": { "type": "string" }
+        }
+      }
+    }
+  }
+}

protocol/schemas/error-envelope.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cloudsbeyond.github.io/visual-agent/protocol/schemas/error-envelope.schema.json",
+  "title": "ErrorEnvelope",
+  "description": "Machine-readable failure envelope emitted by runtime entry points and adapters.",
+  "type": "object",
+  "required": ["ok", "kind", "reason", "message"],
+  "properties": {
+    "ok": { "const": false },
+    "kind": { "const": "error" },
+    "reason": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$"
+    },
+    "message": {
+      "type": "string",
+      "minLength": 1
+    },
+    "call_id": { "type": "string" },
+    "pendingSafetyCheckCount": { "type": "integer", "minimum": 0 }
+  }
+}