Strengthen fixture coverage and simplify validation commands

ONBOARDING.md

@@ -81,6 +81,12 @@ Canonical definitions → `SPEC.md`.
 ```
 npm install
 npm run validate
+```
+
+Use the subcommands only when you need a narrower loop:
+
+```
+npm run validate:schemas
 npm run validate:examples
 ```
 5. Update `RESOLUTION.md`, provenance
@@ -96,6 +102,16 @@ Once approved → tagged + pinned.
 - Fully traceable governance + checksums
 - Deterministic $id + HTTP resolution
 
+## 5A. Fixture Rules
+
+When you touch `examples/`, keep the validation surface credible:
+
+- valid examples should be realistic, not cartoon placeholders
+- invalid examples should usually test one clear failure, not five at once
+- filenames should explain the scenario (`missing-input`, `invalid-version`, `extra-property`, etc.)
+- request examples must stay verb-aligned; do not copy an invalid fixture from one verb directory into another
+- valid receipts should use realistic `sha256:` digests and CID-shaped values
+
 Default assumption: **new version** for any semantic change.
 
 ## 6. Support

README.md

@@ -77,9 +77,9 @@ If agents cannot agree on what actions mean, interoperability breaks.
   "status": "ok",
   "timestamp": "2026-03-18T12:00:00Z",
   "agent": "summarizeagent.eth",
-  "request_hash": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
-  "result_hash": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
-  "result_cid": "bafybeisummarizereceiptokexample0001",
+  "request_hash": "sha256:4b87d90208e62430a5d8f577938fd26d02d646f092d137cee66216c0daac8243",
+  "result_hash": "sha256:8b5d2d4dfb4a8bb7d4d1ed436e78c5f4bcf6ca9714ec93a8db8e5ec6ed8b1b8d",
+  "result_cid": "bafybeif6h8j0l2n4p6r8t0v2x4z6b8d0f2h4j6l8n0p2r4t6v8x0z2bd",
   "summary": "Commons v1.1.0 makes requests smaller and receipts easier to verify while preserving stable verb semantics.",
   "signature": "sigAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
 }
@@ -107,13 +107,15 @@ Install Commons and AJV:
 npm install @commandlayer/commons ajv ajv-formats ajv-errors
 ```
 
-**Validate all schemas and examples with the repo's working commands**
+**Validate the full repo surface**
 
 ```bash
 npm install
 npm run validate
 ```
 
+`npm run validate` is the primary command: it compiles every schema and then checks that all shipped examples pass or fail exactly as intended.
+
 **Validate a specific example against the published schema using AJV**
 
 ```bash
@@ -384,7 +386,6 @@ Commons gives upper layers a stable meaning layer to build around.
 │           ├── <verb>.request.schema.json
 │           └── <verb>.receipt.schema.json
 └── scripts/
-    ├── ajv-run.mjs
     ├── validate-all.mjs
     └── validate-examples.mjs
 ```
@@ -421,15 +422,30 @@ Published version directories must not be edited in place.
 Available commands:
 
 ```bash
+npm run validate
 npm run validate:schemas
 npm run validate:examples
-npm run validate
 ```
 
-These commands compile schemas in strict Ajv mode and validate the shipped examples for both `v1.0.0` and `v1.1.0`.
+- `npm run validate` — the main contributor command. Compiles every schema, then validates every shipped example.
+- `npm run validate:schemas` — schema compilation only. Useful when changing schema files or Ajv configuration.
+- `npm run validate:examples` — fixture pass/fail verification only. Useful when editing examples or improving failure coverage.
+
+For `v1.1.0`, fixture discipline matters as much as schema compilation: valid examples must look operationally plausible, and invalid examples should usually fail for one clear reason that matches the filename.
 
 ---
 
+## Fixture discipline
+
+For `examples/v1.1.0/commons/`, contributors should treat fixtures as protocol evidence, not filler:
+
+- valid examples should look realistic enough that an implementer could model against them
+- invalid examples should usually exercise one clear failure mode
+- filenames should describe the exact failure being tested
+- request fixtures must stay aligned with the verb directory they live in; deliberate wrong-verb cases must be explicitly named
+- valid receipts should use realistic digest and CID-shaped values instead of toy placeholders
+
+
 ## License
 
 MIT.

examples/v1.1.0/commons/analyze/json/invalid/001-missing-verb.request.invalid.json

@@ -0,0 +1,5 @@
+{
+  "version": "1.1.0",
+  "input": "Find the hidden assumptions in this release checklist.",
+  "mode": "extract"
+}

examples/v1.1.0/commons/analyze/json/invalid/002-missing-input.request.invalid.json

@@ -0,0 +1,5 @@
+{
+  "verb": "analyze",
+  "version": "1.1.0",
+  "mode": "extract"
+}

examples/v1.1.0/commons/analyze/json/invalid/003-empty-input.request.invalid.json

@@ -0,0 +1,6 @@
+{
+  "verb": "analyze",
+  "version": "1.1.0",
+  "input": "",
+  "mode": "extract"
+}

examples/v1.1.0/commons/analyze/json/invalid/004-invalid-version.request.invalid.json

@@ -0,0 +1,6 @@
+{
+  "verb": "analyze",
+  "version": "1.1",
+  "input": "Review the incident summary.",
+  "mode": "extract"
+}

examples/v1.1.0/commons/analyze/json/invalid/005-extra-property.request.invalid.json

@@ -0,0 +1,7 @@
+{
+  "verb": "analyze",
+  "version": "1.1.0",
+  "input": "Review the incident summary.",
+  "mode": "extract",
+  "trace_id": "req_01"
+}

examples/v1.1.0/commons/analyze/json/invalid/006-invalid-mode.request.invalid.json

@@ -0,0 +1,6 @@
+{
+  "verb": "analyze",
+  "version": "1.1.0",
+  "input": "Review the incident summary.",
+  "mode": "bullet-points"
+}

examples/v1.1.0/commons/summarize/json/invalid/001-summarize.request.invalid.json → examples/v1.1.0/commons/analyze/json/invalid/007-wrong-input-type.request.invalid.json

@@ -4,5 +4,5 @@
   "input": {
     "text": "This should be a string."
   },
-  "mode": "tweet"
+  "mode": "extract"
 }

examples/v1.1.0/commons/analyze/json/invalid/008-wrong-verb-literal.request.invalid.json

@@ -0,0 +1,6 @@
+{
+  "verb": "summarize",
+  "version": "1.1.0",
+  "input": "Review the incident summary.",
+  "mode": "extract"
+}

examples/v1.1.0/commons/analyze/json/invalid/900-invalid-request-hash.receipt.invalid.json

@@ -0,0 +1,12 @@
+{
+  "verb": "analyze",
+  "version": "1.1.0",
+  "status": "ok",
+  "timestamp": "2026-03-18T12:00:00Z",
+  "agent": "analyzeagent.eth",
+  "request_hash": "sha256:not-a-real-digest",
+  "result_hash": "sha256:ab6d7cf38df79241b5f67fbe2718d1d58d7b0f3e131d0f1d8d4f7b7b6c4a2e19",
+  "result_cid": "bafybeigdyrzt5sfp7udm7hu76g2n6z4r6x2zjz6xj5l5w2z4g5i6k7l4mu",
+  "summary": "Core risks center on manual signer rotation, unproven indexer headroom, and the lack of a documented rollback path.",
+  "signature": "MEUCIGdY9f8wq2dL4rN6sT7uV1xY3zA5bC7dE9fG1hJ2kL3mAiEAzQ7wX9yB2cD4eF6gH8iJ0kL2mN4pQ6rS8tU0vW2xY4"
+}

examples/v1.1.0/commons/analyze/json/invalid/901-missing-error-on-error.receipt.invalid.json

@@ -0,0 +1,9 @@
+{
+  "verb": "analyze",
+  "version": "1.1.0",
+  "status": "error",
+  "timestamp": "2026-03-18T12:08:14Z",
+  "agent": "analyzeagent.eth",
+  "request_hash": "sha256:42fa6d1f884a8ef2ff4a6f43cf9d3d44ec9818d636eb54652a7ef7cb2b4f6a7c",
+  "signature": "MEQCIFf0nN8vR2sT4uV6wX8yZ1aB3cD5eF7gH9iJ1kL2mN4pAiAqS6uV8wY0zB2dD4fF6hH8jJ0lL2nP4rT6vX8zA1cC3e"
+}

examples/v1.1.0/commons/analyze/json/valid/001-minimal-extract.request.valid.json

@@ -0,0 +1,5 @@
+{
+  "verb": "analyze",
+  "version": "1.1.0",
+  "input": "Review the validator diff and extract the core security implications."
+}

examples/v1.1.0/commons/analyze/json/valid/002-risk-theme-extract.request.valid.json

@@ -0,0 +1,6 @@
+{
+  "verb": "analyze",
+  "version": "1.1.0",
+  "input": "Audit notes: signer rotation is manual, rollback is undocumented, and indexer capacity assumptions are untested before mainnet launch.",
+  "mode": "extract"
+}

examples/v1.1.0/commons/analyze/json/valid/900-ok.receipt.valid.json

@@ -0,0 +1,12 @@
+{
+  "verb": "analyze",
+  "version": "1.1.0",
+  "status": "ok",
+  "timestamp": "2026-03-18T12:00:00Z",
+  "agent": "analyzeagent.eth",
+  "request_hash": "sha256:8d8b0c9f7cc2c94b5f5d2e8f9bb7d38a74646d8f1f6f0de44d4a1f8be0c5b9d1",
+  "result_hash": "sha256:ab6d7cf38df79241b5f67fbe2718d1d58d7b0f3e131d0f1d8d4f7b7b6c4a2e19",
+  "result_cid": "bafybeigdyrzt5sfp7udm7hu76g2n6z4r6x2zjz6xj5l5w2z4g5i6k7l4mu",
+  "summary": "Core risks center on manual signer rotation, unproven indexer headroom, and the lack of a documented rollback path.",
+  "signature": "MEUCIGdY9f8wq2dL4rN6sT7uV1xY3zA5bC7dE9fG1hJ2kL3mAiEAzQ7wX9yB2cD4eF6gH8iJ0kL2mN4pQ6rS8tU0vW2xY4"
+}

examples/v1.1.0/commons/analyze/json/valid/901-error.receipt.valid.json

@@ -0,0 +1,10 @@
+{
+  "verb": "analyze",
+  "version": "1.1.0",
+  "status": "error",
+  "timestamp": "2026-03-18T12:08:14Z",
+  "agent": "analyzeagent.eth",
+  "request_hash": "sha256:42fa6d1f884a8ef2ff4a6f43cf9d3d44ec9818d636eb54652a7ef7cb2b4f6a7c",
+  "signature": "MEQCIFf0nN8vR2sT4uV6wX8yZ1aB3cD5eF7gH9iJ1kL2mN4pAiAqS6uV8wY0zB2dD4fF6hH8jJ0lL2nP4rT6vX8zA1cC3e",
+  "error": "The input exceeded the analyzer context window before a stable extraction could be produced."
+}

examples/v1.1.0/commons/classify/json/invalid/001-missing-verb.request.invalid.json

@@ -0,0 +1,5 @@
+{
+  "version": "1.1.0",
+  "input": "Classify this incident report.",
+  "mode": "single"
+}

examples/v1.1.0/commons/classify/json/invalid/002-missing-input.request.invalid.json

@@ -0,0 +1,5 @@
+{
+  "verb": "classify",
+  "version": "1.1.0",
+  "mode": "single"
+}

examples/v1.1.0/commons/classify/json/invalid/003-empty-input.request.invalid.json

@@ -0,0 +1,6 @@
+{
+  "verb": "classify",
+  "version": "1.1.0",
+  "input": "",
+  "mode": "single"
+}

examples/v1.1.0/commons/classify/json/invalid/004-invalid-version.request.invalid.json

@@ -0,0 +1,6 @@
+{
+  "verb": "classify",
+  "version": "1.1.1",
+  "input": "Classify this incident report.",
+  "mode": "single"
+}

examples/v1.1.0/commons/classify/json/invalid/005-extra-property.request.invalid.json

@@ -0,0 +1,9 @@
+{
+  "verb": "classify",
+  "version": "1.1.0",
+  "input": "Classify this incident report.",
+  "mode": "single",
+  "labels": [
+    "billing_issue"
+  ]
+}

examples/v1.1.0/commons/classify/json/invalid/006-invalid-mode.request.invalid.json

@@ -0,0 +1,6 @@
+{
+  "verb": "classify",
+  "version": "1.1.0",
+  "input": "Classify this incident report.",
+  "mode": "ordinal"
+}

examples/v1.1.0/commons/classify/json/invalid/007-wrong-input-type.request.invalid.json

@@ -0,0 +1,8 @@
+{
+  "verb": "classify",
+  "version": "1.1.0",
+  "input": [
+    "billing_issue"
+  ],
+  "mode": "single"
+}

examples/v1.1.0/commons/classify/json/invalid/008-wrong-verb-literal.request.invalid.json

@@ -0,0 +1,6 @@
+{
+  "verb": "analyze",
+  "version": "1.1.0",
+  "input": "Classify this incident report.",
+  "mode": "single"
+}

examples/v1.1.0/commons/classify/json/invalid/900-summary-wrong-type.receipt.invalid.json

@@ -0,0 +1,12 @@
+{
+  "verb": "classify",
+  "version": "1.1.0",
+  "status": "ok",
+  "timestamp": "2026-03-18T12:10:00Z",
+  "agent": "classifyagent.eth",
+  "request_hash": "sha256:3d5224e3ebc7f6ab9e9a6a2114a5f7d01c6847c8df0e3fd53c0e5d117f6ab9dd",
+  "summary": [
+    "billing_issue"
+  ],
+  "signature": "MEYCIQDf3h7kL9mN2pQ4rS6tU8vW0xY2zA4bC6dE8fG0hJ1kLwIhAO5pQ7rS9tU1vW3xY5zB7cD9eF1gH3iJ5kL7mN9pQ1"
+}

examples/v1.1.0/commons/classify/json/invalid/901-extra-property.receipt.invalid.json

@@ -0,0 +1,11 @@
+{
+  "verb": "classify",
+  "version": "1.1.0",
+  "status": "error",
+  "timestamp": "2026-03-18T12:10:21Z",
+  "agent": "classifyagent.eth",
+  "request_hash": "sha256:94c6c8e7224c96a1ad9438c5ce9f8a775ad9de5ec28d19e5f02b6f58f2ce87db",
+  "signature": "MEQCIC4dF6gH8iJ0kL2mN4pQ6rS8tU0vW2xY4zB6dD8fF0nAiB3cE5gH7iJ9kL1mN3pQ5rS7tU9vW1xY3zA5bC7dE9fG1",
+  "error": "The label taxonomy was unavailable, so no deterministic class assignment could be made.",
+  "debug": "extra"
+}

examples/v1.1.0/commons/classify/json/valid/001-classify.request.valid.json → examples/v1.1.0/commons/classify/json/valid/001-minimal.request.valid.json

@@ -1,6 +1,5 @@
 {
   "verb": "classify",
   "version": "1.1.0",
-  "input": "Payment failed after signature verification because the buyer wallet had insufficient balance.",
-  "mode": "single"
+  "input": "Payment failed after signature verification because the buyer wallet had insufficient balance."
 }

examples/v1.1.0/commons/classify/json/valid/002-multi-label.request.valid.json

@@ -0,0 +1,6 @@
+{
+  "verb": "classify",
+  "version": "1.1.0",
+  "input": "The RPC returned 429s during traffic spikes and the retry worker exhausted its queue budget.",
+  "mode": "multi"
+}

examples/v1.1.0/commons/classify/json/valid/900-ok.receipt.valid.json

@@ -0,0 +1,12 @@
+{
+  "verb": "classify",
+  "version": "1.1.0",
+  "status": "ok",
+  "timestamp": "2026-03-18T12:10:00Z",
+  "agent": "classifyagent.eth",
+  "request_hash": "sha256:3d5224e3ebc7f6ab9e9a6a2114a5f7d01c6847c8df0e3fd53c0e5d117f6ab9dd",
+  "result_hash": "sha256:8cb8de3bdca7cb09517e3a5a6aa3d34f429fba381a325f1ca2f94fdb7d59e831",
+  "result_cid": "bafybeibn6t7v5x3zk4m2w1q9p8r7s6u5t4v3w2x1y9z8a7b6c5d4e3f2ga",
+  "summary": "billing_issue",
+  "signature": "MEYCIQDf3h7kL9mN2pQ4rS6tU8vW0xY2zA4bC6dE8fG0hJ1kLwIhAO5pQ7rS9tU1vW3xY5zB7cD9eF1gH3iJ5kL7mN9pQ1"
+}