Merge branch 'main' into codex/move-readme-table-of-contents-to-top

Author: GsCommand

ONBOARDING.md

@@ -74,12 +74,19 @@ Canonical definitions → `SPEC.md`.
 
 ## 4. Working Norms
 
-Before changing schemas or examples:
+```
+npm install
+npm run validate
+```
 
-- Read `SCHEMAS.md` for layout and versioning rules
-- Read `SPEC.md` for the contract you are changing
-- Treat published version folders as immutable unless governance explicitly opens a new release line
-- Use `npm run validate` as the default repo-wide verification command
+Use the subcommands only when you need a narrower loop:
+
+```
+npm run validate:schemas
+npm run validate:examples
+```
+5. Update `RESOLUTION.md`, provenance
+6. Submit PR with version class (MAJOR/MINOR/PATCH)
 
 If you are preparing a contribution, follow `CONTRIBUTING.md`.
 
@@ -91,6 +98,16 @@ If you are preparing a contribution, follow `CONTRIBUTING.md`.
 - 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

@@ -99,9 +99,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"
 }
@@ -128,13 +128,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
@@ -419,14 +421,30 @@ Published version directories must not be edited in place.
 Use `npm run validate` as the canonical repo-wide validation command. For targeted checks, the repo also exposes:
 
 ```bash
+npm run validate
 npm run validate:schemas
 npm run validate:examples
 ```
 
-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.

checksums.txt

@@ -24,7 +24,7 @@ b451b0c05cb77f7ad66906f351b560400447de136c1ad2ce27c63fc3bcaf0d9a  schemas/v1.0.0
 ccb7f20562d2e34dff73a17794aabcf98f25f659e83a790e42cf9a31e97460b3  schemas/v1.0.0/commons/summarize/receipts/summarize.receipt.schema.json
 be565b5a72dc03a1517a9c2ea0a0842c86def2e58e8471f81e3cac6262bffb68  schemas/v1.0.0/commons/summarize/requests/summarize.request.schema.json
 4760c15bc2985b35be8a333859e0b2e97617735be0d0222722b162de47caf940  schemas/v1.1.0/commons/analyze/analyze.receipt.schema.json
-28571a5750590c256b9318ecb1cfb60e39614df82cee0b3b2a921980100e447c  schemas/v1.1.0/commons/analyze/analyze.request.schema.json
+7f3c2254410e5a552905810a5a4e564af97b82bd7122d92af7d5ca9c43438caa  schemas/v1.1.0/commons/analyze/analyze.request.schema.json
 6aeb33050633f712dfcaabc8e57ba058275e44653407bb766f0417cb5bfd8c2b  schemas/v1.1.0/commons/classify/classify.receipt.schema.json
 476253e821ff4e7dfa441e5604c6efc29d12729bcb50e8a02db86fbd121240ab  schemas/v1.1.0/commons/classify/classify.request.schema.json
 13a2f4d9083e1e5ed6bd6b98e05736e7791bfd62b109b4090ab4abff75572ad5  schemas/v1.1.0/commons/clean/clean.receipt.schema.json

examples/v1.1.0/commons/analyze/json/invalid/001-analyze.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/001-missing-verb.request.invalid.json

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

examples/v1.1.0/commons/analyze/json/invalid/002-missing-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/003-empty-input.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/004-invalid-version.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/005-extra-property.request.invalid.json

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