Merge pull request #17 from commandlayer/codex/harden-trust-and-coherence-of-commandlayer

Harden v1.1.0 trust posture and docs; realistic receipts and TOC move

Author: GsCommand

GOVERNANCE.md

@@ -1,7 +1,7 @@
 # Governance — Protocol Commons
 
 **Scope:** Protocol-Commons (primary), Agent-Cards (identity bindings)  
-**Status:** v1.0.0 — Historical Pinned Release; v1.1.0 — Current Canonical In-Repo Line  
+**Status:** v1.0.0 — Historical Pinned Release; v1.1.0 — Current Canonical Working Line  
 
 > This governance is **NORMATIVE, ENFORCEABLE, AND PERMANENT**.  
 > Control is custodial today and **designed to decentralize** as adoption grows.
@@ -99,7 +99,7 @@ Attempts to mutate semantics in place MUST be treated as **UNTRUSTED**.
 The current lock states are interpreted strictly:
 
 - **v1.0.0 historical pinned release** means the legacy release line with published CID, immutable checksums, and locked provenance
-- **v1.1.0 current canonical in-repo line** means the current repository contract and primary documentation target; CID publication remains pending in repository provenance metadata
+- **v1.1.0 current canonical working line** means the current repository contract and primary documentation target; CID publication remains pending in repository provenance metadata
 
 ---
 
@@ -154,7 +154,7 @@ Silent or undocumented changes are **STRICTLY FORBIDDEN.**
 
 Every semantic release MUST publish new CIDs + checksums.
 
-Until CID publication is complete, contributors MUST describe that version accurately as the current canonical in-repo line and MUST NOT misstate it as the historical pinned release.
+Until CID publication is complete, contributors MUST describe that version accurately as the current canonical working line and MUST NOT misstate it as the historical pinned release.
 
 ---
 
@@ -184,6 +184,6 @@ ONLY if:
 
 False claims REQUIRE public enforcement action.
 
-_Last updated: v1.0.0 retained as the historical pinned release; v1.1.0 documented as the current canonical in-repo line_  
-Signed: **`commandlayer.eth`**  
+_Last updated: v1.0.0 retained as the historical pinned release; v1.1.0 documented as the current canonical working line_  
+Steward declaration (plain-text repository statement, not a cryptographic signature): **`commandlayer.eth`**  
 *Founding Steward — CommandLayer Semantic Standards*

ONBOARDING.md

@@ -79,12 +79,14 @@ npm install
 npm run validate
 ```
 
-Use the subcommands only when you need a narrower loop:
+Use a subcommand only when you need a narrower loop after the aggregate pass:
 
 ```
 npm run validate:schemas
-npm run validate:examples
 ```
+
+`npm run validate` already includes `npm run validate:examples`. Run `validate:examples` separately only when you intentionally want an examples-only loop.
+
 5. Update `RESOLUTION.md`, provenance
 6. Submit PR with version class (MAJOR/MINOR/PATCH)
 
@@ -96,7 +98,7 @@ If you are preparing a contribution, follow `CONTRIBUTING.md`.
 - Schema + example alignment
 - No edits to existing version folders
 - Fully traceable governance + checksums
-- Deterministic $id + HTTP resolution
+- Deterministic canonical `$id` values, with live HTTP resolution added when publication is completed
 
 ## 5A. Fixture Rules
 
@@ -107,6 +109,7 @@ When you touch `examples/`, keep the validation surface credible:
 - 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
+- unless the repo ships the exact corresponding payload artifacts, treat example digests/signatures/CIDs as format-realistic illustrative evidence rather than independently verifiable production proofs
 
 Default assumption: **new version** for any semantic change.
 

README.md

@@ -10,56 +10,23 @@
 
 ---
 
-## Why Now
-
-Autonomous agents are finally leaving the lab — but without shared meaning, they fragment into isolated API silos.
-
-CommandLayer separates the stack into clear responsibilities:
-
-- **Protocol-Commons** defines the shared semantic layer
-- **Identity and discovery layers** can resolve who an agent is and where it can be reached
-- **Execution and payment layers** can transport, meter, or settle work around those semantics
-
-Protocol-Commons is the foundation for portable machine intent: a stable set of verbs plus strict JSON Schemas for requests and receipts.
-
----
-
 > **Integrity Notice — Protocol-Commons v1.1.0**
 >
-> `schemas/v1.1.0/commons` is the current canonical in-repo Commons line:
-> `schemas/v1.1.0/commons` — CID publication status: `PENDING`
+> `schemas/v1.1.0/commons` is the current canonical **working line in this repository**.
+> Its publication metadata still says `schemas_cid: PENDING`, so this line is **not yet the externally pinned canonical release**.
 >
-> `v1.0.0` is retained as the historical pinned release line:
+> `v1.0.0` remains the last **externally pinned canonical release**:
 > `schemas/v1.0.0/` — CID: `bafybeigvf6nkzws7dblos74dqqjkguwkrwn4a2c27ieygoxmgofyzdkz6m`
 >
-> Verify integrity locally:
+> Verify in-repo integrity locally:
 > ```bash
 > npm run checksums:verify
 > ```
 >
-> Any mismatch indicates modified artifacts.
-> New versions MUST use a new version directory and, once published, a new CID.
-
----
-
-Without a shared verb layer, ecosystems degrade into:
-
-- Ad-hoc verbs and incompatible dialects
-- Ambiguous receipts with inconsistent evidence
-- No cross-runtime interoperability
-- Closed vendor silos with fragile glue logic
-
-**Protocol-Commons** fixes this with a canonical action language:
-
-- Verbs + JSON Schemas + strict validation
-- Stable request envelopes
-- Signed receipts with hash-based verification evidence
-
-If agents cannot agree on what actions mean, interoperability breaks.
-
----
+> Any mismatch indicates modified artifacts. New versions MUST use a new version directory and, once published, a new CID.
 
 ## Table of Contents
+- [Why Now](#why-now)
 - [Real verbs. Real receipts.](#real-verbs-real-receipts)
 - [Quickstart](#quickstart)
 - [Commons v1.1.0](#commons-v110)
@@ -75,12 +42,44 @@ If agents cannot agree on what actions mean, interoperability breaks.
 - [Manifest](#manifest)
 - [Immutability & Checksums](#immutability--checksums)
 - [Validation](#validation)
+- [Fixture discipline](#fixture-discipline)
 - [License](#license)
 - [Next Layers](#next-layers)
 - [References](#references)
 
 ---
 
+## Why Now
+
+Autonomous agents are finally leaving the lab — but without shared meaning, they fragment into isolated API silos.
+
+CommandLayer separates the stack into clear responsibilities:
+
+- **Protocol-Commons** defines the shared semantic layer
+- **Identity and discovery layers** can resolve who an agent is and where it can be reached
+- **Execution and payment layers** can transport, meter, or settle work around those semantics
+
+Protocol-Commons is the foundation for portable machine intent: a stable set of verbs plus strict JSON Schemas for requests and receipts.
+
+---
+
+Without a shared verb layer, ecosystems degrade into:
+
+- Ad-hoc verbs and incompatible dialects
+- Ambiguous receipts with inconsistent evidence
+- No cross-runtime interoperability
+- Closed vendor silos with fragile glue logic
+
+**Protocol-Commons** fixes this with a canonical action language:
+
+- Verbs + JSON Schemas + strict validation
+- Stable request envelopes
+- Signed receipts with hash-based verification evidence
+
+If agents cannot agree on what actions mean, interoperability breaks.
+
+---
+
 ## Real verbs. Real receipts.
 
 ```jsonc
@@ -98,25 +97,22 @@ If agents cannot agree on what actions mean, interoperability breaks.
   "version": "1.1.0",
   "status": "ok",
   "timestamp": "2026-03-18T12:00:00Z",
-  "agent": "summarizeagent.eth",
   "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"
+  "signature": "MEUCID4fG6hJ8kL0mN2pQ4rS6tU8vW0xY2zA4bC6dE8fG0hAiEAzB1dD3fF5hH7jJ9lL1nP3rT5vX7zA9cC1eE3gH5iJ7"
 }
 ```
 
-Every v1.1.0 Commons receipt uses the same evidence-oriented spine:
+Every v1.1.0 Commons receipt shares the same required core evidence fields:
 
 - `status`
 - `timestamp`
 - `request_hash`
-- `summary` *(required on success)*
 - `signature`
-- `error` *(required on error)*
 
-`result_hash` and `result_cid` are optional evidence fields. `agent` is optional and may be included when the actor/provider identity needs to be surfaced.
+`summary` is required on success receipts. `error` is required on error receipts. `result_hash`, `result_cid`, and `agent` are optional evidence fields that may appear when the implementation can surface them honestly.
 
 ---
 
@@ -137,7 +133,7 @@ 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**
+**Validate a specific example against the shipped schema using AJV**
 
 ```bash
 node --input-type=module <<'EOF_NODE'
@@ -186,7 +182,7 @@ console.log(validate.errors ?? []);
 
 Commons v1.1.0 is the current canonical schema family in this repository.
 
-It is the primary documentation and validation target for Commons. The repository still records CID publication as pending, while `v1.0.0` is retained as the historical pinned release line.
+It is the primary documentation and validation target for Commons. The repository still records CID publication as pending, so `v1.1.0` should be treated as the active working line rather than the last externally pinned release. `v1.0.0` is retained as the historical pinned release line.
 
 - Each request schema is standalone
 - Each receipt schema is standalone
@@ -217,7 +213,6 @@ The receipt contract is proof-oriented rather than transport-oriented:
   "version": "1.1.0",
   "status": "ok | error",
   "timestamp": "<RFC 3339 date-time>",
-  "agent": "<optional stable signer identity>",
   "request_hash": "sha256:<64 lowercase hex chars>",
   "result_hash": "sha256:<64 lowercase hex chars>",
   "result_cid": "<optional content identifier>",
@@ -353,11 +348,11 @@ Commons gives upper layers a stable meaning layer to build around.
 
 ## Status
 
-**v1.1.0 — current canonical schema family**
+**v1.1.0 — current canonical working line**
 
 - `v1.1.0` is the current flat Commons layout in this repo
 - `v1.0.0` remains the historical pinned release line
-- Do not describe `v1.1.0` provenance as fully canonical until pinning is complete
+- Do not describe `v1.1.0` as externally pinned or historically locked until CID publication is complete
 
 ---
 
@@ -401,6 +396,8 @@ Commons gives upper layers a stable meaning layer to build around.
 - per-verb request and receipt schema paths
 - CID publication status (`PENDING` in `manifest.json` until published)
 
+Treat `schemas_cid: PENDING` as an explicit signal that the v1.1.0 line is still awaiting external publication/provenance, even though it is the repo's current schema target.
+
 ---
 
 ## Immutability & Checksums
@@ -443,6 +440,7 @@ For `examples/v1.1.0/commons/`, contributors should treat fixtures as protocol e
 - 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
+- unless the repo ships the exact corresponding payload artifacts, treat example digests/signatures/CIDs as format-realistic illustrative evidence rather than independently verifiable production proofs
 
 
 ## License

SPEC.md

@@ -33,7 +33,7 @@ Repository metadata still records v1.1.0 CID publication as pending. Implementer
 1. **Schema semantics** — what the v1.1.0 files require
 2. **Release provenance status** — whether a version has completed CID publication and canonical pinning
 
-This specification documents the v1.1.0 contract as the current canonical line while preserving v1.0.0 as the historical pinned release until v1.1.0 pinning is complete.
+This specification documents the v1.1.0 contract as the current canonical working line while preserving v1.0.0 as the historical pinned release until v1.1.0 pinning is complete.
 
 ---
 
@@ -147,7 +147,6 @@ A conforming success receipt shape is:
   "version": "1.1.0",
   "status": "ok",
   "timestamp": "<RFC 3339 date-time>",
-  "agent": "<stable signer identity>",
   "request_hash": "sha256:<64 lowercase hex chars>",
   "result_hash": "sha256:<64 lowercase hex chars>",
   "result_cid": "<optional content identifier>",
@@ -156,6 +155,8 @@ A conforming success receipt shape is:
 }
 ```
 
+`agent` MAY be added to either success or error receipts when the signer identity is being surfaced at the application layer.
+
 A conforming error receipt shape is:
 
 ```json
@@ -206,7 +207,9 @@ schemas/v1.0.0/commons/<verb>/receipts/<verb>.receipt.schema.json
 
 ## 7. Schema `$id` Rules
 
-Every v1.1.0 schema MUST use a resolvable HTTPS `$id` under this pattern.
+Every v1.1.0 schema MUST use the canonical HTTPS `$id` namespace under this pattern.
+
+Those `$id` values are stable schema identifiers inside the repository and validation tooling. They SHOULD resolve over live HTTPS once publication/hosting is completed, but live HTTPS resolution is not yet guaranteed by current v1.1.0 repository provenance metadata.
 
 ### Request
 
@@ -228,7 +231,7 @@ Legacy v1.0.0 `$id` layouts remain valid only for the legacy directory tree.
 
 Implementations claiming v1.1.0 schema compatibility MUST:
 
-1. Validate requests and receipts against the exact published schema files
+1. Validate requests and receipts against the exact schema files shipped for the version being claimed
 2. Use JSON Schema draft 2020-12 support
 3. Compile schemas in strict Ajv mode or equivalent
 4. Reject undeclared properties
@@ -283,7 +286,7 @@ Auditors and resolvers SHOULD:
 1. Fetch the versioned schemas
 2. Verify integrity locally
 3. Treat mismatched artifacts as untrusted
-4. Treat v1.1.0 as the current canonical in-repo line, distinct from the historical pinned release, until CID publication is complete
+4. Treat v1.1.0 as the current canonical working line, distinct from the historical pinned release, until CID publication is complete
 
 Integrity check command:
 
@@ -304,7 +307,7 @@ An implementation supporting Commons v1.1.0 MUST:
 5. Preserve receipt trust semantics as hashes plus signatures, without inventing unsupported guarantees
 6. Avoid representing v1.1.0 as the historical pinned release until CID publication is complete
 
-A system supporting any canonical verb MAY claim **Commons-Compatible** for that version, but provenance claims MUST accurately reflect whether the relevant version is the current canonical in-repo line or the historical pinned release.
+A system supporting any canonical verb MAY claim **Commons-Compatible** for that version, but provenance claims MUST accurately reflect whether the relevant version is the current canonical working line or the historical pinned release.
 
 ---
 

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

@@ -3,7 +3,6 @@
   "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/analyze/ts/valid/analyze.receipt.valid.1.ts

@@ -1,4 +1,4 @@
-// VALID analyze.receipt #1 — success receipt with signer identity and hashes
+// VALID analyze.receipt #1 — success receipt with realistic digest/CID-shaped evidence
 
 export interface AnalyzeReceipt {
   verb: "analyze";
@@ -20,9 +20,9 @@ export const analyzeReceiptValid1: AnalyzeReceipt = {
   "status": "ok",
   "timestamp": "2026-03-18T12:00:00Z",
   "agent": "analyzeagent.eth",
-  "request_hash": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
-  "result_hash": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
-  "result_cid": "bafybeianalyzereceiptokexample0001",
-  "summary": "Core risks center on signer key rotation gaps, unresolved indexer scaling assumptions, and an unstated rollback plan.",
-  "signature": "sigAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
+  "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/ts/valid/analyze.receipt.valid.2.ts

@@ -1,14 +1,13 @@
-// VALID analyze.receipt #2 — error receipt variant required by the schema
+// VALID analyze.receipt #2 — error receipt variant showing that `agent` is optional
 
 import type { AnalyzeReceipt } from "./analyze.receipt.valid.1";
 
 export const analyzeReceiptValid2: AnalyzeReceipt = {
   "verb": "analyze",
   "version": "1.1.0",
   "status": "error",
-  "timestamp": "2026-03-18T12:05:00Z",
-  "agent": "analyzeagent.eth",
-  "request_hash": "sha256:3333333333333333333333333333333333333333333333333333333333333333",
-  "signature": "sigBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
-  "error": "analyze execution failed because the input could not be processed in the requested mode."
+  "timestamp": "2026-03-18T12:08:14Z",
+  "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/valid/901-error.receipt.valid.json

@@ -3,7 +3,6 @@
   "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."