release specx v0.3.0 schema init verify

Author: EvanAI0331

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "specx-codex-plugin",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Universal spec-driven agent governance and execution contract runtime for Codex.",
   "license": "MIT",
   "author": {
@@ -28,8 +28,8 @@
     ],
     "websiteURL": "https://github.com/BTCNAI/specx-codex-plugin",
     "defaultPrompt": [
-      "Use SpecX to compile this task into a governed execution contract.",
-      "Use SpecX to verify whether this workflow has agents, tools, evidence, gates, artifacts, and failure semantics.",
+      "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."
     ],
     "brandColor": "#2563EB"

CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.3.0
+
+- Added Contract Schema v0.1 at `schemas/specx_contract_v0_1.schema.json`.
+- Added verified templates for research, software refactor, and content pipeline contracts.
+- Added `specx init` CLI support through `scripts/specx_cli.py init`.
+- Upgraded `specx verify` to fail closed with `failure_state` and structured details.
+- Added MCP `specx.init` and aligned MCP behavior with CLI behavior.
+- Added tests for schema v0.1, init, verify, and MCP fail-closed behavior.
+
+## 0.2.2
+
+- Added real MCP tools for validate, compile, verify, and explain.

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.2.2
+codex plugin marketplace add https://github.com/BTCNAI/specx-codex-marketplace.git --ref v0.3.0
 ```
 
 ## What It Provides
@@ -42,9 +42,12 @@ Included skills:
 Included CLI:
 
 ```bash
+python3 scripts/specx_cli.py init --template research --output ./specx.contract.json
+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 validate examples/demo_software_engineering_contract.json
 python3 scripts/specx_cli.py compile examples/demo_software_engineering_contract.json
-python3 scripts/specx_cli.py verify examples/demo_software_engineering_contract.json
 python3 scripts/specx_cli.py explain examples/demo_software_engineering_contract.json
 ```
 
@@ -54,6 +57,7 @@ Included MCP tools:
 - `specx.compile`
 - `specx.verify`
 - `specx.explain`
+- `specx.init`
 
 Install MCP runtime dependencies before running MCP tools:
 
@@ -65,16 +69,24 @@ python3 -m pip install -r requirements.txt
 
 Every valid contract must define:
 
+- `contract_id`
+- `schema_version: "0.1"`
+- `objective`
+- `domain`
+- `task_type`
 - `required_agents`
 - `required_tools`
 - `required_evidence`
 - `gates`
 - `expected_artifacts`
 - `failure_semantics`
-- `execution_constraints.no_fake_success`
-- `execution_constraints.no_silent_fallback`
+- `execution_constraints`
+- `human_approval`
+- `verification_policy.required_checks`
 
-If required evidence, tools, specs, gates, or artifacts are missing, the workflow must return `blocked`, `failed`, or `unsupported`. It must not claim success.
+Each gate must include `gate_id`, `condition`, `on_pass`, and `on_failure`. `failure_semantics` must include `no_fake_success`, `no_silent_fallback`, and `explicit_failure_state`.
+
+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.
 
 ## Demos
 
@@ -103,12 +115,14 @@ Demo 3: Multi-agent system
 - `docs/use-cases.md`
 - `docs/comparison.md`
 - `docs/mcp-tools.md`
+- `docs/contract-schema-v0.1.md`
+- `docs/cli.md`
 
 ## Roadmap
 
 P0:
 
-- Contract schema v0.1 hardening.
+- Contract schema v0.1 adoption feedback.
 - MCP integration tests against real Codex marketplace install.
 
 P1:
@@ -127,6 +141,7 @@ specx-codex-plugin/
 ├── skills/
 ├── scripts/
 ├── schemas/
+├── templates/
 ├── examples/
 ├── tests/
 ├── README.md

docs/cli.md

@@ -0,0 +1,37 @@
+# CLI
+
+## specx init
+
+Create a verified Contract Schema v0.1 skeleton from a built-in template:
+
+```bash
+python3 scripts/specx_cli.py init --template research --output ./specx.contract.json
+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
+```
+
+`init` verifies the template before writing. If the template is invalid, no success is reported.
+
+## specx verify
+
+Verify a contract against schema v0.1 and governance checks:
+
+```bash
+python3 scripts/specx_cli.py verify ./specx.contract.json
+```
+
+Failure returns `ok=false`, `failure_state`, and structured `details`.
+
+## Other Commands
+
+```bash
+python3 scripts/specx_cli.py validate ./specx.contract.json
+python3 scripts/specx_cli.py compile ./specx.contract.json
+python3 scripts/specx_cli.py explain ./specx.contract.json
+```
+
+`validate` and `verify` are both fail-closed for v0.1 contracts. `compile` refuses invalid contracts.
+
+## CLI And MCP Consistency
+
+The MCP tools call the same implementation used by the CLI. MCP must not return a success state that the CLI would reject.

docs/contract-format.md

@@ -5,7 +5,7 @@ A SpecX contract is the execution boundary for an agent workflow.
 ## Required Fields
 
 - `contract_id`
-- `version`
+- `schema_version`
 - `objective`
 - `domain`
 - `task_type`
@@ -16,6 +16,8 @@ A SpecX contract is the execution boundary for an agent workflow.
 - `expected_artifacts`
 - `failure_semantics`
 - `execution_constraints`
+- `human_approval`
+- `verification_policy`
 
 ## Agent Specs
 
@@ -34,12 +36,19 @@ Each gate must define:
 
 - `gate_id`
 - `condition`
+- `on_pass`
 - `on_failure`
 
 Gate failure must return `blocked` or `failed`. It must not be converted into success.
 
 ## Failure Semantics
 
+`failure_semantics` must include:
+
+- `no_fake_success: true`
+- `no_silent_fallback: true`
+- `explicit_failure_state: true`
+
 Use explicit states:
 
 - `blocked`: required input, evidence, spec, approval, or gate is missing.
@@ -59,3 +68,7 @@ Use explicit states:
 ```
 
 Missing constraints should fail verification.
+
+## Verification Policy
+
+`verification_policy.required_checks` must be a non-empty array. Missing checks fail closed.

docs/contract-schema-v0.1.md

@@ -0,0 +1,66 @@
+# Contract Schema v0.1
+
+SpecX Contract Schema v0.1 is the required contract shape for governed workflows.
+
+## Required Fields
+
+- `contract_id`
+- `schema_version`: must be `"0.1"`
+- `objective`
+- `domain`
+- `task_type`
+- `required_agents`
+- `required_tools`
+- `required_evidence`
+- `gates`
+- `expected_artifacts`
+- `failure_semantics`
+- `execution_constraints`
+- `human_approval`
+- `verification_policy`
+
+## Gates
+
+Each gate must include:
+
+- `gate_id`
+- `condition`
+- `on_pass`
+- `on_failure`
+
+Missing or malformed gates fail closed.
+
+## Failure Semantics
+
+`failure_semantics` must include:
+
+- `no_fake_success: true`
+- `no_silent_fallback: true`
+- `explicit_failure_state: true`
+
+`execution_constraints` must include:
+
+- `no_fake_success: true`
+- `no_silent_fallback: true`
+- `no_hardcoded_fallback: true`
+
+## Verification Policy
+
+`verification_policy.required_checks` must be a non-empty array.
+
+## Fail Closed
+
+Invalid contracts return:
+
+```json
+{
+  "ok": false,
+  "failure_state": "failed_contract_verification",
+  "details": {
+    "missing_fields": [],
+    "invalid_gates": [],
+    "invalid_failure_semantics": [],
+    "invalid_verification_policy": []
+  }
+}
+```

docs/mcp-tools.md

@@ -6,8 +6,9 @@ SpecX exposes four MCP tools:
 - `specx.compile`
 - `specx.verify`
 - `specx.explain`
+- `specx.init`
 
-Each tool accepts a SpecX contract JSON object as `contract`.
+Contract tools accept a SpecX contract JSON object as `contract`. `specx.init` accepts `template` and `output`.
 
 ## Local Server
 
@@ -42,7 +43,7 @@ The MCP config starts the stdio server:
 
 ### specx.validate
 
-Validates required fields and array/object shapes. It does not execute the workflow.
+Validates Contract Schema v0.1 required fields, gate shape, failure semantics, execution constraints, and verification policy. It does not execute the workflow.
 
 ### specx.compile
 
@@ -52,10 +53,16 @@ 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.init
+
+Creates a verified Contract Schema v0.1 skeleton from `research`, `software_refactor`, or `content_pipeline`.
+
 ### specx.explain
 
 Returns a compact explanation with objective summary, domain, task type, counts, risk notes, and unsupported features.
 
 ## Failure Boundary
 
 If the MCP runtime is not installed, `scripts/launch_specx_mcp.py` exits non-zero and prints the missing-runtime error. It does not claim that MCP tools are available.
+
+CLI and MCP tools use the same implementation. MCP cannot return a success state that the CLI would reject.

docs/quickstart.md

@@ -11,10 +11,10 @@ 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.2.2
+codex plugin marketplace add https://github.com/BTCNAI/specx-codex-marketplace.git --ref v0.3.0
 ```
 
-## Validate A Contract
+## Initialize A Contract
 
 Install MCP runtime dependencies before using MCP tools:
 
@@ -23,7 +23,15 @@ python3 -m pip install -r requirements.txt
 ```
 
 ```bash
-python3 scripts/specx_cli.py validate examples/demo_software_engineering_contract.json
+python3 scripts/specx_cli.py init --template research --output ./specx.contract.json
+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
+```
+
+## Verify A Contract
+
+```bash
+python3 scripts/specx_cli.py verify ./specx.contract.json
 ```
 
 Expected success:
@@ -32,24 +40,24 @@ Expected success:
 {
   "ok": true,
   "result": {
-    "contract_id": "demo-software-engineering-001",
-    "status": "valid"
+    "schema_version": "0.1",
+    "status": "verified"
   }
 }
 ```
 
 ## Compile A Contract
 
 ```bash
-python3 scripts/specx_cli.py compile examples/demo_software_engineering_contract.json
+python3 scripts/specx_cli.py compile ./specx.contract.json
 ```
 
 Compilation produces an execution plan with agents, tools, evidence requirements, gates, artifact plan, verification plan, failure semantics, and constraints.
 
 ## Verify A Contract
 
 ```bash
-python3 scripts/specx_cli.py verify examples/demo_software_engineering_contract.json
+python3 scripts/specx_cli.py verify ./specx.contract.json
 ```
 
 Verification fails closed when gates, required agents, artifacts, failure semantics, or `no_fake_success` / `no_silent_fallback` constraints are missing.
@@ -58,6 +66,7 @@ Verification fails closed when gates, required agents, artifacts, failure semant
 
 The current main branch exposes MCP tools:
 
+- `specx.init`
 - `specx.validate`
 - `specx.compile`
 - `specx.verify`