@voybio/ace-swarm 0.1.0

package/assets/agent-state/AST_GREP_COMMANDS.md

@@ -0,0 +1,121 @@
+# AST_GREP_COMMANDS
+
+Purpose: keep discovery lightweight by using repeatable `ast-grep` queries instead of storing very large file maps in `agent-state/index.json`.
+
+Scope:
+- Run from workspace root.
+- Prefer targeted paths (`ace-mcp-server/src`, `engineering-state/src`) over `.` when possible.
+- Treat this as command playbook for orchestrator/research/spec workflows.
+
+## 1) Profile the codebase quickly
+
+```bash
+# Languages present (source files only)
+find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.py" -o -name "*.rs" -o -name "*.go" \) \
+  | grep -v "\.git\|node_modules\|dist\|target\|__pycache__" \
+  | sed 's/.*\.//' | sort | uniq -c | sort -rn
+
+# Entry-point candidates
+find . \( -name "index.ts" -o -name "main.py" -o -name "main.rs" -o -name "server.ts" -o -name "app.py" \) \
+  | grep -v "\.git\|node_modules\|dist\|target" | head -20
+```
+
+## 2) TypeScript/JavaScript API surface
+
+```bash
+# Exported functions (TS)
+ast-grep --pattern 'export function $NAME($$$ARGS): $RET { $$$BODY }' --lang ts ace-mcp-server/src --color never \
+  | grep -oE 'export function [A-Za-z0-9_]+' | awk '{print $3}' | sort -u
+
+# Exported classes (TS)
+ast-grep --pattern 'export class $NAME { $$$BODY }' --lang ts ace-mcp-server/src --color never \
+  | grep -oE 'export class [A-Za-z0-9_]+' | awk '{print $3}' | sort -u
+
+# Async functions (TS)
+ast-grep --pattern 'async function $NAME($$$ARGS)' --lang ts ace-mcp-server/src --color never
+```
+
+## 3) Python API surface
+
+```bash
+# Top-level function definitions
+ast-grep --pattern 'def $NAME($$$ARGS):' --lang python engineering-state/src --color never
+
+# Class definitions
+ast-grep --pattern 'class $NAME:' --lang python engineering-state/src --color never
+```
+
+## 4) Rust API surface
+
+```bash
+# Public functions
+ast-grep --pattern 'pub fn $NAME($$$ARGS)' --lang rust engineering-state/src --color never
+
+# Public structs
+ast-grep --pattern 'pub struct $NAME' --lang rust engineering-state/src --color never
+```
+
+## 5) Test and quality signals
+
+```bash
+# TS test blocks
+ast-grep --pattern "it('$DESC', $$$BODY)" --lang ts ace-mcp-server/src --color never
+ast-grep --pattern 'test("$DESC", $$$BODY)' --lang ts ace-mcp-server/src --color never
+
+# Python tests
+ast-grep --pattern 'def test_$NAME($$$ARGS):' --lang python engineering-state/src --color never
+
+# TODO/FIXME/HACK density
+grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" --include="*.rs" . \
+  | grep -v "\.git\|node_modules\|dist\|target"
+```
+
+## 6) Contract and handoff checks (ACE-specific)
+
+```bash
+# Find handoff schema references
+ast-grep --pattern '$X("SWARM_HANDOFF.$Y")' --lang ts ace-mcp-server/src --color never
+
+# Find route selection logic
+grep -rn "route_task\|routingMap\|ace-orchestrator" ace-mcp-server/src
+
+# Find index usage
+grep -rn "agent-state/index.json\|scanWorkspaceDelta" ace-mcp-server/src
+```
+
+## 7) `rep_astgrep.cxml` corpus mining (reference pack)
+
+Use when `rep_astgrep.cxml` exists and you need a structural map from the imported ast-grep reference corpus without loading the full XML into context.
+
+```bash
+# Source path inventory inside corpus
+rg -o "<source>[^<]+</source>" rep_astgrep.cxml \
+  | sed -E 's#</?source>##g' | sort | uniq > /tmp/rep_astgrep_sources.txt
+
+# Top-level directory distribution
+awk -F/ '{print $1}' /tmp/rep_astgrep_sources.txt | sort | uniq -c | sort -rn | head -30
+
+# Language distribution from referenced source paths
+sed -nE 's#.*\.([a-zA-Z0-9]+)$#\1#p' /tmp/rep_astgrep_sources.txt | sort | uniq -c | sort -rn
+
+# High-signal AST/CLI docs inside corpus
+rg -n "ast-grep|sg |playground|pattern|rewrite|rule|yaml|napi|pyo3|Cargo.toml" rep_astgrep.cxml | head -120
+```
+
+## 8) Output capture template
+
+When a scan is materially important, persist to `agent-state/EVIDENCE_LOG.md`:
+
+```bash
+{
+  date -u +"[%Y-%m-%dT%H:%M:%SZ] ast-grep scan: exported TS functions";
+  ast-grep --pattern 'export function $NAME($$$ARGS): $RET { $$$BODY }' --lang ts ace-mcp-server/src --color never \
+    | grep -oE 'export function [A-Za-z0-9_]+' | awk '{print $3}' | sort -u;
+} >> agent-state/EVIDENCE_LOG.md
+```
+
+## 9) Usage guidance
+
+- Use `agent-state/index.json` for lightweight map metadata (counts, directories, extensions, sampled entries).
+- Use this command pack for deep inspection and role-specific discovery.
+- Prefer narrow path scopes for speed and reduced noise.

package/assets/agent-state/AST_GREP_INDEX.json

@@ -0,0 +1,13 @@
+{
+  "generated_at": "2026-03-06T00:00:00Z",
+  "scope": ".",
+  "commands_used": [],
+  "language_profile": {},
+  "top_symbols": {},
+  "hotspots": [],
+  "quality_signals": {},
+  "notes": [
+    "Initialized placeholder discovery index.",
+    "Refresh via agent-state/AST_GREP_COMMANDS.md and persist evidence in EVIDENCE_LOG.md"
+  ]
+}

package/assets/agent-state/AST_GREP_INDEX.md

@@ -0,0 +1,15 @@
+# AST_GREP_INDEX
+
+Generated: 2026-03-06T00:00:00Z
+Scope: .
+
+## Status
+
+- Discovery artifact initialized.
+- Run commands from `agent-state/AST_GREP_COMMANDS.md` to refresh with live findings.
+- `agent-state/index.json` is metadata-only (`file_entry_cap: 0`).
+
+## Routing Hints
+
+- Use `agent-astgrep` + `astgrep-index` for symbol/hotspot discovery.
+- Use `agent-state/index.json` only for lightweight directory/extension metadata.

package/assets/agent-state/DECISIONS.md

@@ -0,0 +1,7 @@
+# DECISIONS
+
+Append-only tradeoff ledger.
+
+## Entries
+
+- 2026-03-03T00:00:00Z | `bootstrap` | Established 17-agent topology (4 swarm + 13 composable modules) and TEAL-based routing as default architecture.

package/assets/agent-state/EVIDENCE_LOG.md

@@ -0,0 +1,7 @@
+# EVIDENCE LOG
+
+Append-only chain-of-custody for checks, decisions, and execution proofs.
+
+## Entries
+
+- 2026-03-03T00:00:00Z | bootstrap initialized | evidence_ref: `EVIDENCE_LOG.md#ts:2026-03-03T00:00:00Z`

package/assets/agent-state/HANDOFF.json

@@ -0,0 +1,24 @@
+{
+  "meta": {
+    "timestamp": "2026-03-03T00:00:00Z",
+    "iteration": 1,
+    "session_id": "bootstrap-session",
+    "log_commit": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
+  },
+  "transition": {
+    "from": "capability-ops",
+    "to": "capability-skeptic",
+    "status": "READY",
+    "reason": "Bootstrap complete; quality gate definition is next"
+  },
+  "payload": {
+    "primary_artifact": "agent-state/TASK.md",
+    "interface_contract": "agent-state/MODULES/schemas/HANDOFF.agent-state.schema.json#1.0.0",
+    "evidence_pointer": "EVIDENCE_LOG.md#ts:2026-03-03T00:00:00Z",
+    "known_issues": []
+  },
+  "integrity": {
+    "checksum": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
+    "file_count": 0
+  }
+}

package/assets/agent-state/INTERFACE_REGISTRY.md

@@ -0,0 +1,75 @@
+# INTERFACE REGISTRY
+
+## Canonical Contracts
+
+- `MODULES/schemas/HANDOFF.agent-state.schema.json`
+- `MODULES/schemas/STATUS_EVENT.schema.json`
+- `MODULES/schemas/ARTIFACT_MANIFEST.schema.json`
+- `MODULES/schemas/SWARM_HANDOFF.schema.json`
+- `MODULES/schemas/ACE_RUNTIME_PROFILE.schema.json`
+- `MODULES/schemas/WORKSPACE_SESSION_REGISTRY.schema.json`
+- `MODULES/schemas/RUNTIME_TOOL_SPEC_REGISTRY.schema.json`
+- `MODULES/schemas/RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json`
+- `MODULES/schemas/TRACKER_SNAPSHOT.schema.json`
+- `MODULES/schemas/VERICIFY_BRIDGE_SNAPSHOT.schema.json`
+- `MODULES/schemas/VERICIFY_PROCESS_POST_LOG.schema.json`
+
+## Runtime Contract
+
+- `ACE_WORKFLOW.md` is the canonical workspace runtime profile artifact.
+- Its YAML front matter must validate against `MODULES/schemas/ACE_RUNTIME_PROFILE.schema.json`.
+- The markdown body after the closing front matter boundary is the active runtime prompt template.
+- The optional `continuity` block only budgets derived packet content; it must not redefine canonical ACE truth outside the existing state artifacts and sidecar-native stores.
+
+## Workspace Session Contract
+
+- `runtime-workspaces.json` is the canonical managed workspace/session registry.
+- It must validate against `MODULES/schemas/WORKSPACE_SESSION_REGISTRY.schema.json`.
+- Removal only applies to registry-backed managed workspace paths under the configured runtime root.
+
+## Runtime Tool Contract
+
+- `runtime-tool-specs.json` is the canonical runtime-configured external tool registry.
+- It must validate against `MODULES/schemas/RUNTIME_TOOL_SPEC_REGISTRY.schema.json`.
+- Unattended executor and direct runtime-tool execution must validate input/output payloads against the declared tool schemas.
+
+## Runtime Executor Contract
+
+- `runtime-executor-sessions.json` is the canonical unattended execution session registry.
+- It must validate against `MODULES/schemas/RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json`.
+- Session turns must record request/response paths, summaries, and tool-call outcomes without mutating existing HANDOFF or STATUS_EVENT schema versions.
+
+## Tracker Snapshot Contract
+
+- `tracker-snapshot.json` is the canonical normalized tracker snapshot artifact.
+- It must validate against `MODULES/schemas/TRACKER_SNAPSHOT.schema.json`.
+- Scheduler and future executor consumers must use normalized item/comment fields only; provider-specific detail belongs under `metadata`.
+
+## Vericify Sidecar Contract
+
+- `vericify/ace-bridge.json` is an optional sidecar bridge snapshot for Vericify-style read-model consumers.
+- It must validate against `MODULES/schemas/VERICIFY_BRIDGE_SNAPSHOT.schema.json`.
+- `vericify/process-posts.json` is an optional structured process-post log and must validate against `MODULES/schemas/VERICIFY_PROCESS_POST_LOG.schema.json`.
+- Vericify remains optional; ACE must not require the Vericify package to read or write these artifacts.
+
+## Public Surface Gate
+
+- `audit_public_surface` is the canonical TypeScript public-surface gate for MCP tools, resources, prompts, and registered event names.
+- `PUBLIC_SURFACE_REPORT.md` is the durable audit artifact written by that gate.
+- `MODULES/gates/gate-typescript-public-surface.json` is the executable gate manifest for CI or operator use.
+
+## Provenance Contract
+
+- `ARTIFACT_MANIFEST.json` is mandatory and must be schema-valid.
+- Each artifact entry must include `artifact_id`, `artifact_path`, `producer_module`, `spec_version`, `req_ids`, `checksum`, `confidence_level`, `evidence_ref`, and `timestamp`.
+- `PROVENANCE_LOG.md` must mirror manifest entries with append-only evidence-linked records.
+
+## Versioning Rules
+
+- additive changes: `minor`
+- breaking changes: `major`
+- bugfix/clarification: `patch`
+
+## Compatibility Requirement
+
+Producer and consumer compatibility must be documented before release.

package/assets/agent-state/MODULES/gates/gate-autonomy.json

@@ -0,0 +1,7 @@
+{
+  "id": "gate-autonomy",
+  "type": "artifact_scan",
+  "invariant": "Every execution cycle records objective, strategy, evidence, and next state",
+  "command": "",
+  "evidence_requirement": "STATUS + EVIDENCE_LOG + HANDOFF pointers"
+}

package/assets/agent-state/MODULES/gates/gate-completeness.json

@@ -0,0 +1,7 @@
+{
+  "id": "gate-completeness",
+  "type": "artifact_scan",
+  "invariant": "All required artifacts exist and are non-empty",
+  "command": "",
+  "evidence_requirement": "File presence and section completeness evidence"
+}

package/assets/agent-state/MODULES/gates/gate-correctness.json

@@ -0,0 +1,7 @@
+{
+  "id": "gate-correctness",
+  "type": "executable",
+  "invariant": "All required tests pass",
+  "command": "cd ace-mcp-server && npm test --silent",
+  "evidence_requirement": "Command output snippet with exit code 0"
+}

package/assets/agent-state/MODULES/gates/gate-evaluation.json

@@ -0,0 +1,7 @@
+{
+  "id": "gate-evaluation",
+  "type": "executable",
+  "invariant": "Core autonomy benchmark suites meet defined pass thresholds",
+  "command": "bash scripts/ace/eval-harness.sh",
+  "evidence_requirement": "EVAL_REPORT.md + command output"
+}

package/assets/agent-state/MODULES/gates/gate-operability.json

@@ -0,0 +1,7 @@
+{
+  "id": "gate-operability",
+  "type": "artifact_scan",
+  "invariant": "Runbooks, ownership, and incident routing are defined for release",
+  "command": "",
+  "evidence_requirement": "COMMUNICATION_CHANNELS.md + observability/release artifacts"
+}

package/assets/agent-state/MODULES/gates/gate-security.json

@@ -0,0 +1,7 @@
+{
+  "id": "gate-security",
+  "type": "manual_review",
+  "invariant": "No unmitigated high-severity security or policy risks",
+  "command": "",
+  "evidence_requirement": "SECURITY_REPORT.md with explicit mitigations or accepted residual risk"
+}

package/assets/agent-state/MODULES/gates/gate-typescript-public-surface.json

@@ -0,0 +1,7 @@
+{
+  "id": "gate-typescript-public-surface",
+  "type": "executable",
+  "invariant": "Exported MCP tools, resources, prompts, and public status events stay registered, described, schema-backed where required, and covered by the audit gate",
+  "command": "node --input-type=module -e \"import('./dist/public-surface.js').then(async (m) => { const result = await m.auditPublicSurface({ write_artifact: false }); if (!result.ok) { console.error(result.failures.join('\\n')); process.exit(1); } console.log(JSON.stringify(result.summary)); })\"",
+  "evidence_requirement": "PUBLIC_SURFACE_REPORT.md + passing public-surface audit"
+}

package/assets/agent-state/MODULES/registry.json

@@ -0,0 +1,41 @@
+{
+  "roles": [
+    "capability-astgrep",
+    "capability-skeptic",
+    "capability-ops",
+    "capability-research",
+    "capability-spec",
+    "capability-build",
+    "capability-qa",
+    "capability-docs",
+    "capability-memory",
+    "capability-security",
+    "capability-observability",
+    "capability-eval",
+    "capability-release",
+    "capability-safety",
+    "capability-framework",
+    "capability-git"
+  ],
+  "gates": [
+    "gate-completeness",
+    "gate-correctness",
+    "gate-autonomy",
+    "gate-security",
+    "gate-operability",
+    "gate-evaluation",
+    "gate-typescript-public-surface"
+  ],
+  "schemas": [
+    "STATUS_EVENT.schema.json",
+    "HANDOFF.schema.json",
+    "ARTIFACT_MANIFEST.schema.json",
+    "ACE_RUNTIME_PROFILE.schema.json",
+    "WORKSPACE_SESSION_REGISTRY.schema.json",
+    "RUNTIME_TOOL_SPEC_REGISTRY.schema.json",
+    "RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json",
+    "TRACKER_SNAPSHOT.schema.json",
+    "VERICIFY_BRIDGE_SNAPSHOT.schema.json",
+    "VERICIFY_PROCESS_POST_LOG.schema.json"
+  ]
+}

package/assets/agent-state/MODULES/roles/capability-astgrep.json

@@ -0,0 +1,49 @@
+{
+  "id": "capability-astgrep",
+  "version": "1.0.0",
+  "objective": "Generate compact structural discovery indexes using ast-grep command workflows",
+  "permissions": [
+    "allow_file_io",
+    "allow_shell_exec"
+  ],
+  "inputs": [
+    {
+      "file": "TASK.md",
+      "critical": true
+    },
+    {
+      "file": "SCOPE.md",
+      "critical": true
+    },
+    {
+      "file": "AST_GREP_COMMANDS.md",
+      "critical": true
+    }
+  ],
+  "outputs": [
+    {
+      "file": "AST_GREP_INDEX.md",
+      "validation_gate": "gate-completeness"
+    },
+    {
+      "file": "AST_GREP_INDEX.json",
+      "validation_gate": "gate-completeness"
+    }
+  ],
+  "events": {
+    "emits": [
+      "DISCOVERY_INDEX_READY",
+      "DISCOVERY_INDEX_STALE",
+      "DISCOVERY_SCOPE_BLOCKED"
+    ],
+    "consumes": [
+      "FIX_REQUIRED",
+      "SPEC_UPDATED",
+      "ARTIFACT_PRODUCED"
+    ]
+  },
+  "failure_routing": {
+    "missing_input": "BLOCK_AND_REQUEST_INFO",
+    "gate_failure": "ESCALATE_TO_OPS"
+  }
+}

package/assets/agent-state/MODULES/roles/capability-build.json

@@ -0,0 +1,39 @@
+{
+  "id": "capability-build",
+  "version": "1.0.0",
+  "objective": "Implement artifacts that satisfy spec contracts with provenance",
+  "permissions": [
+    "allow_file_io",
+    "allow_shell_exec"
+  ],
+  "inputs": [
+    {
+      "file": "SPEC_CONTRACT.json",
+      "critical": true
+    },
+    {
+      "file": "INTERFACE_DEFINITION.md",
+      "critical": true
+    }
+  ],
+  "outputs": [
+    {
+      "file": "ARTIFACT_MANIFEST.json",
+      "validation_gate": "gate-correctness"
+    }
+  ],
+  "events": {
+    "emits": [
+      "ARTIFACT_PRODUCED",
+      "BUILD_FAILED"
+    ],
+    "consumes": [
+      "SPEC_UPDATED",
+      "FIX_REQUIRED"
+    ]
+  },
+  "failure_routing": {
+    "missing_input": "BLOCK_AND_REQUEST_INFO",
+    "gate_failure": "REVERT_TO_PREVIOUS_ROLE"
+  }
+}

package/assets/agent-state/MODULES/roles/capability-docs.json

@@ -0,0 +1,38 @@
+{
+  "id": "capability-docs",
+  "version": "1.0.0",
+  "objective": "Keep documentation synchronized with actual system behavior",
+  "permissions": [
+    "allow_file_io"
+  ],
+  "inputs": [
+    {
+      "file": "VERIFICATION_REPORT.md",
+      "critical": true
+    },
+    {
+      "file": "SPEC_CONTRACT.json",
+      "critical": true
+    }
+  ],
+  "outputs": [
+    {
+      "file": "DOCS_CONSISTENCY_REPORT.md",
+      "validation_gate": "gate-completeness"
+    }
+  ],
+  "events": {
+    "emits": [
+      "DOCS_GENERATED",
+      "DOCS_INCONSISTENT"
+    ],
+    "consumes": [
+      "VERIFICATION_COMPLETE",
+      "SPEC_UPDATED"
+    ]
+  },
+  "failure_routing": {
+    "missing_input": "BLOCK_AND_REQUEST_INFO",
+    "gate_failure": "REVERT_TO_PREVIOUS_ROLE"
+  }
+}

package/assets/agent-state/MODULES/roles/capability-eval.json

@@ -0,0 +1,20 @@
+{
+  "id": "capability-eval",
+  "version": "1.0.0",
+  "objective": "Run autonomy benchmark suites and detect regressions before release",
+  "permissions": [
+    "allow_file_io",
+    "allow_shell_exec"
+  ],
+  "inputs": [
+    {"file": "SPEC_CONTRACT.json", "critical": false},
+    {"file": "EVIDENCE_LOG.md", "critical": true}
+  ],
+  "outputs": [
+    {"file": "EVAL_REPORT.md", "validation_gate": "gate-evaluation"}
+  ],
+  "failure_routing": {
+    "missing_input": "BLOCK_AND_REQUEST_INFO",
+    "gate_failure": "REVERT_TO_PREVIOUS_ROLE"
+  }
+}

package/assets/agent-state/MODULES/roles/capability-memory.json

@@ -0,0 +1,20 @@
+{
+  "id": "capability-memory",
+  "version": "1.0.0",
+  "objective": "Maintain durable, relevant, and non-contradictory system memory",
+  "permissions": [
+    "allow_file_io",
+    "allow_shell_exec"
+  ],
+  "inputs": [
+    {"file": "EVIDENCE_LOG.md", "critical": true},
+    {"file": "STATUS.md", "critical": true}
+  ],
+  "outputs": [
+    {"file": "MEMORY_INDEX.md", "validation_gate": "gate-completeness"}
+  ],
+  "failure_routing": {
+    "missing_input": "BLOCK_AND_REQUEST_INFO",
+    "gate_failure": "ROUTE_TO_CAPABILITY_OPS"
+  }
+}

package/assets/agent-state/MODULES/roles/capability-observability.json

@@ -0,0 +1,20 @@
+{
+  "id": "capability-observability",
+  "version": "1.0.0",
+  "objective": "Track health, latency, and failures for autonomous execution loops",
+  "permissions": [
+    "allow_file_io",
+    "allow_shell_exec"
+  ],
+  "inputs": [
+    {"file": "STATUS.md", "critical": true},
+    {"file": "EVIDENCE_LOG.md", "critical": true}
+  ],
+  "outputs": [
+    {"file": "OBSERVABILITY_REPORT.md", "validation_gate": "gate-operability"}
+  ],
+  "failure_routing": {
+    "missing_input": "BLOCK_AND_REQUEST_INFO",
+    "gate_failure": "ROUTE_TO_CAPABILITY_OPS"
+  }
+}

package/assets/agent-state/MODULES/roles/capability-ops.json

@@ -0,0 +1,45 @@
+{
+  "id": "capability-ops",
+  "version": "1.0.0",
+  "objective": "Orchestrate dependency-safe execution and manage circuit breakers",
+  "permissions": [
+    "allow_file_io",
+    "allow_shell_exec"
+  ],
+  "inputs": [
+    {
+      "file": "STATUS.md",
+      "critical": true
+    },
+    {
+      "file": "HANDOFF.json",
+      "critical": true
+    }
+  ],
+  "outputs": [
+    {
+      "file": "STATUS.md",
+      "validation_gate": "gate-completeness"
+    },
+    {
+      "file": "HANDOFF_HISTORY/*.json",
+      "validation_gate": "gate-completeness"
+    }
+  ],
+  "events": {
+    "emits": [
+      "FIX_REQUIRED",
+      "GATE_PASSED",
+      "ROUTE_UPDATED"
+    ],
+    "consumes": [
+      "GATE_FAILED",
+      "GATE_DECISION",
+      "VERIFICATION_COMPLETE"
+    ]
+  },
+  "failure_routing": {
+    "missing_input": "BLOCK_AND_REQUEST_INFO",
+    "gate_failure": "ESCALATE_TO_SKEPTIC"
+  }
+}

package/assets/agent-state/MODULES/roles/capability-qa.json

@@ -0,0 +1,40 @@
+{
+  "id": "capability-qa",
+  "version": "1.0.0",
+  "objective": "Validate artifacts against acceptance criteria and classify failures",
+  "permissions": [
+    "allow_file_io",
+    "allow_shell_exec"
+  ],
+  "inputs": [
+    {
+      "file": "SPEC_CONTRACT.json",
+      "critical": true
+    },
+    {
+      "file": "ARTIFACT_MANIFEST.json",
+      "critical": true
+    }
+  ],
+  "outputs": [
+    {
+      "file": "VERIFICATION_REPORT.md",
+      "validation_gate": "gate-correctness"
+    }
+  ],
+  "events": {
+    "emits": [
+      "VERIFICATION_COMPLETE",
+      "GATE_FAILED",
+      "GATE_PASSED"
+    ],
+    "consumes": [
+      "ARTIFACT_PRODUCED",
+      "SPEC_UPDATED"
+    ]
+  },
+  "failure_routing": {
+    "missing_input": "BLOCK_AND_REQUEST_INFO",
+    "gate_failure": "REVERT_TO_PREVIOUS_ROLE"
+  }
+}