release specx v0.4.0 execution results

Author: EvanAI0331

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "specx-codex-plugin",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Universal spec-driven agent governance and execution contract runtime for Codex.",
   "license": "MIT",
   "author": {
@@ -29,8 +29,8 @@
     "websiteURL": "https://github.com/BTCNAI/specx-codex-plugin",
     "defaultPrompt": [
       "Use SpecX init to create a governed v0.1 contract.",
-      "Use SpecX verify to fail closed on missing gates, evidence, or failure semantics.",
-      "Use SpecX to explain the execution contract before workflow execution."
+      "Use SpecX verify-result to check execution evidence against a contract.",
+      "Use SpecX verify to fail closed on missing gates, evidence, or failure semantics."
     ],
     "brandColor": "#2563EB"
   },

.github/workflows/test.yml

@@ -0,0 +1,36 @@
+name: test
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: python3 -m pip install -r requirements.txt pytest
+      - name: Run tests
+        run: python3 -m pytest
+      - name: Validate contract
+        run: python3 scripts/specx_cli.py validate templates/research.contract.json
+      - name: Compile contract
+        run: python3 scripts/specx_cli.py compile templates/research.contract.json
+      - name: Verify contract
+        run: python3 scripts/specx_cli.py verify templates/research.contract.json
+      - name: Verify passed execution result
+        run: python3 scripts/specx_cli.py verify-result examples/sample_execution_result_passed.json --contract templates/research.contract.json
+      - name: Verify failed execution result semantics
+        run: |
+          python3 scripts/specx_cli.py verify-result examples/sample_execution_result_failed.json --contract templates/research.contract.json > /tmp/specx_failed_result.json
+          python3 - <<'PY'
+          import json
+          from pathlib import Path
+          payload = json.loads(Path("/tmp/specx_failed_result.json").read_text())
+          assert payload["ok"] is True
+          assert payload["result"]["execution_status"] == "failed"
+          PY

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.4.0
+
+- Added Execution Result Schema v0.1 at `schemas/specx_execution_result_v0_1.schema.json`.
+- Added `specx verify-result` to verify execution results against their governing contract.
+- Added MCP `specx.verify_result` with the same implementation as CLI `verify-result`.
+- Added passed, failed, and blocked execution-result samples.
+- Added GitHub Actions CI for pytest, contract validation, compilation, verification, and result verification.
+- Added tests for execution-result schema and fail-closed result verification.
+
 ## 0.3.0
 
 - Added Contract Schema v0.1 at `schemas/specx_contract_v0_1.schema.json`.

README.md

@@ -17,7 +17,7 @@ codex plugin marketplace add BTCNAI/specx-codex-marketplace
 Or pin the stable release:
 
 ```bash
-codex plugin marketplace add https://github.com/BTCNAI/specx-codex-marketplace.git --ref v0.3.0
+codex plugin marketplace add https://github.com/BTCNAI/specx-codex-marketplace.git --ref v0.4.0
 ```
 
 ## What It Provides
@@ -46,6 +46,7 @@ python3 scripts/specx_cli.py init --template research --output ./specx.contract.
 python3 scripts/specx_cli.py init --template software_refactor --output ./specx.contract.json
 python3 scripts/specx_cli.py init --template content_pipeline --output ./specx.contract.json
 python3 scripts/specx_cli.py verify ./specx.contract.json
+python3 scripts/specx_cli.py verify-result ./specx.execution_result.json --contract ./specx.contract.json
 python3 scripts/specx_cli.py validate examples/demo_software_engineering_contract.json
 python3 scripts/specx_cli.py compile examples/demo_software_engineering_contract.json
 python3 scripts/specx_cli.py explain examples/demo_software_engineering_contract.json
@@ -56,6 +57,7 @@ Included MCP tools:
 - `specx.validate`
 - `specx.compile`
 - `specx.verify`
+- `specx.verify_result`
 - `specx.explain`
 - `specx.init`
 
@@ -88,6 +90,18 @@ Each gate must include `gate_id`, `condition`, `on_pass`, and `on_failure`. `fai
 
 If required evidence, tools, specs, gates, artifacts, or verification policy are missing, the workflow must return `ok=false` with `failure_state` and `details`. It must not claim success.
 
+## Execution Result Shape
+
+Contracts are pre-execution constraints. Execution results are post-execution acceptance records.
+
+`verify-result` checks that a result has matching `contract_id`, gate results for every contract gate, artifacts for every expected artifact, explicit status, failure semantics checks, and correct `failure_state` behavior.
+
+Execution statuses:
+
+- `passed`: every required gate and artifact is present; `failure_state` must be null or empty.
+- `failed`: execution failed; `failure_state` must be explicit.
+- `blocked`: execution stopped before completion; `failure_state` must be explicit.
+
 ## Demos
 
 Demo 1: Software engineering
@@ -116,13 +130,15 @@ Demo 3: Multi-agent system
 - `docs/comparison.md`
 - `docs/mcp-tools.md`
 - `docs/contract-schema-v0.1.md`
+- `docs/execution-result-v0.1.md`
 - `docs/cli.md`
 
 ## Roadmap
 
 P0:
 
 - Contract schema v0.1 adoption feedback.
+- Execution result adoption feedback.
 - MCP integration tests against real Codex marketplace install.
 
 P1:

docs/cli.md

@@ -22,6 +22,16 @@ python3 scripts/specx_cli.py verify ./specx.contract.json
 
 Failure returns `ok=false`, `failure_state`, and structured `details`.
 
+## specx verify-result
+
+Verify an execution result against the governing contract:
+
+```bash
+python3 scripts/specx_cli.py verify-result ./specx.execution_result.json --contract ./specx.contract.json
+```
+
+`verify-result` checks the execution result schema, contract id, expected artifacts, gate results, verification checks, and failure-state semantics. A complete `failed` or `blocked` result can pass protocol verification while still reporting `execution_status: failed` or `execution_status: blocked`.
+
 ## Other Commands
 
 ```bash

docs/execution-result-v0.1.md

@@ -0,0 +1,56 @@
+# Execution Result v0.1
+
+The contract is the pre-execution constraint. The execution result is the post-execution acceptance record.
+
+`verify-result` checks that an execution result is complete and aligned with its governing contract. It does not turn a failed or blocked workflow into success.
+
+## Required Fields
+
+- `result_id`
+- `schema_version`: must be `"0.1"`
+- `contract_id`
+- `status`: `passed`, `failed`, or `blocked`
+- `executed_agents`
+- `tool_calls`
+- `evidence_collected`
+- `gate_results`
+- `artifacts`
+- `verification_results`
+- `failure_state`
+- `risk_notes`
+
+## Gate Results
+
+Each `gate_results[]` item must include:
+
+- `gate_id`
+- `status`
+- `evidence`
+- `details`
+
+Every contract gate must have a matching gate result.
+
+## Status Semantics
+
+- `passed`: all required contract gates and artifacts are present; `failure_state` must be null or empty.
+- `failed`: execution failed; `failure_state` must be non-empty.
+- `blocked`: execution stopped because a required gate, evidence item, tool, or approval was unavailable; `failure_state` must be non-empty.
+
+## Fake Success Prevention
+
+`verify-result` prevents fake success by checking:
+
+- `contract_id` matches the contract.
+- Every contract gate has a result.
+- Every `expected_artifacts` item is represented.
+- `passed` results do not carry a failure state.
+- `failed` and `blocked` results have an explicit failure state.
+- `verification_results` includes `no_fake_success`, `no_silent_fallback`, and `explicit_failure_state`.
+
+## Samples
+
+- `examples/sample_execution_result_passed.json`
+- `examples/sample_execution_result_failed.json`
+- `examples/sample_execution_result_blocked.json`
+
+Samples are protocol fixtures. They are not proof of real external execution.

docs/mcp-tools.md

@@ -5,6 +5,7 @@ SpecX exposes four MCP tools:
 - `specx.validate`
 - `specx.compile`
 - `specx.verify`
+- `specx.verify_result`
 - `specx.explain`
 - `specx.init`
 
@@ -53,6 +54,10 @@ Compiles a valid contract into a governed execution plan with agents, tools, evi
 
 Fails closed when gates, expected artifacts, required agents, required tools, or `no_fake_success` / `no_silent_fallback` constraints are missing.
 
+### specx.verify_result
+
+Verifies a SpecX execution result against its governing contract. It checks `contract_id`, gate coverage, artifact coverage, verification checks, and status/failure-state semantics.
+
 ### specx.init
 
 Creates a verified Contract Schema v0.1 skeleton from `research`, `software_refactor`, or `content_pipeline`.

docs/quickstart.md

@@ -11,7 +11,7 @@ codex plugin marketplace add BTCNAI/specx-codex-marketplace
 Pinned install:
 
 ```bash
-codex plugin marketplace add https://github.com/BTCNAI/specx-codex-marketplace.git --ref v0.3.0
+codex plugin marketplace add https://github.com/BTCNAI/specx-codex-marketplace.git --ref v0.4.0
 ```
 
 ## Initialize A Contract
@@ -34,6 +34,12 @@ python3 scripts/specx_cli.py init --template content_pipeline --output ./specx.c
 python3 scripts/specx_cli.py verify ./specx.contract.json
 ```
 
+## Verify An Execution Result
+
+```bash
+python3 scripts/specx_cli.py verify-result examples/sample_execution_result_passed.json --contract templates/research.contract.json
+```
+
 Expected success:
 
 ```json
@@ -70,6 +76,7 @@ The current main branch exposes MCP tools:
 - `specx.validate`
 - `specx.compile`
 - `specx.verify`
+- `specx.verify_result`
 - `specx.explain`
 
 See `docs/mcp-tools.md`.

examples/sample_execution_result_blocked.json

@@ -0,0 +1,76 @@
+{
+  "result_id": "sample-result-blocked-001",
+  "schema_version": "0.1",
+  "contract_id": "research-contract-001",
+  "status": "blocked",
+  "executed_agents": [
+    {
+      "agent_id": "research_planner",
+      "status": "blocked"
+    },
+    {
+      "agent_id": "evidence_reviewer",
+      "status": "blocked"
+    }
+  ],
+  "tool_calls": [
+    {
+      "tool_id": "source_reader",
+      "status": "blocked"
+    },
+    {
+      "tool_id": "citation_tracker",
+      "status": "blocked"
+    },
+    {
+      "tool_id": "artifact_writer",
+      "status": "blocked"
+    }
+  ],
+  "evidence_collected": [
+    "source_list",
+    "claim_to_source_map",
+    "risk_register"
+  ],
+  "gate_results": [
+    {
+      "gate_id": "source_gate",
+      "status": "blocked",
+      "evidence": [
+        "source_list"
+      ],
+      "details": "Claim-to-source mapping was incomplete, so execution stopped at the source gate."
+    },
+    {
+      "gate_id": "decision_packet_gate",
+      "status": "blocked",
+      "evidence": [
+        "risk_register"
+      ],
+      "details": "Decision packet release remained blocked because the source gate did not pass."
+    }
+  ],
+  "artifacts": [
+    {
+      "artifact_id": "research_plan",
+      "status": "produced"
+    },
+    {
+      "artifact_id": "evidence_matrix",
+      "status": "blocked"
+    },
+    {
+      "artifact_id": "decision_packet",
+      "status": "blocked"
+    }
+  ],
+  "verification_results": {
+    "no_fake_success": true,
+    "no_silent_fallback": true,
+    "explicit_failure_state": true
+  },
+  "failure_state": "blocked_missing_claim_to_source_map",
+  "risk_notes": [
+    "Blocked result documents the missing evidence instead of silently falling back."
+  ]
+}