Merge pull request #5 from commandlayer/codex/align-documentation-for-protocol-commons-v1.1.0

Align docs: declare v1.1.0 as active in‑repo (pre‑release) and scope v1.0.0 as last pinned canonical release

Author: GsCommand

COMPLIANCE.md

@@ -23,7 +23,22 @@ Compliance covers semantics and schema integrity only—identity bindings are go
 
 ---
 
-## 2. Versioning & Immutability
+## 2. Version-Aware Compliance Status
+
+Compliance claims MUST identify the version they apply to.
+
+Current repository status:
+
+- **v1.1.0** — current in-repo schema family; CID publication still pending
+- **v1.0.0** — last fully pinned canonical release
+
+A system MAY claim **v1.1.0 schema compatibility** if it validates and enforces the published v1.1.0 schemas.
+
+A system MUST NOT claim **fully pinned canonical v1.1.0 release compliance** until the v1.1.0 CID and provenance record are published.
+
+---
+
+## 3. Versioning & Immutability
 
 For any directory `schemas/vX.Y.Z/`:
 
@@ -35,39 +50,39 @@ No in-place edits to:
 
 Any semantic change requires:
 - New version directory
-- Updated CIDs + checksums
+- Updated CIDs + checksums for canonical releases
 - Logged update in `RESOLUTION.md`
 - Governance approval
 
 Mutating a published version is **not compliant**.
 
 ---
 
-## 3. JSON Schema Requirements
+## 4. JSON Schema Requirements
 
 All Protocol-Commons schemas MUST:
 
 - Use JSON Schema Draft 2020-12
 - Validate under **Ajv strict mode**
 - Use deterministic HTTPS-resolvable `$id` values matching SPEC.md
-- Enforce verb-specific input + receipt contract
+- Enforce the version-specific input + receipt contract
 
 Loose validation or altered `$id` resolution is **not compliant**.
 
 ---
 
-## 4. CIDs & Checksums
+## 5. CIDs & Checksums
 
-Each release MUST:
+Each canonical release MUST:
 
 - Pin the entire version folder to IPFS
 - Provide SHA-256 checksums
 - Publish `manifest.json`
 
 Compliance requires:
 
-- `cl.cid.schemas` resolves to the correct CID
-- IPFS mirrors match HTTP mirrors exactly
+- Canonical TXT/CID bindings only for fully published releases
+- IPFS mirrors match HTTP mirrors exactly for pinned releases
 
 Consumers SHOULD verify `checksums.txt` against the published schema
 artifacts prior to use.
@@ -77,8 +92,11 @@ canonical compliance, and MUST reject mismatches.
 
 Mismatch = **integrity failure**
 
+For v1.1.0 specifically, the schemas and checksums can still be validated locally, but the release MUST be described as pre-release until its CID publication is complete.
+
+---
 
-## 5. Security & Privacy
+## 6. Security & Privacy
 
 Schemas are **semantic infrastructure**, not application output.
 
@@ -91,7 +109,7 @@ Security incidents MUST follow `SECURITY.md`.
 
 ---
 
-## 6. Governance Traceability
+## 7. Governance Traceability
 
 Every canonical change MUST be reflected in:
 - `RESOLUTION.md` (what + why + who)
@@ -101,18 +119,22 @@ An artifact **without a governance trail** is not canonical.
 
 ---
 
-## 7. Ecosystem Alignment
+## 8. Ecosystem Alignment
 
 Commons-compliant implementations SHOULD:
 
 - Support ERC-8004 discovery where relevant
-- Enforce canonical x402 envelope + trace rules
+- Apply only the requirements that are normative for the version they implement
+
+For v1.0.0 legacy implementations, that can include older `x402` envelope and `trace` requirements.
+
+For v1.1.0 implementations, those older `x402` and `trace` requirements are **not automatically normative** unless another layer explicitly adopts them outside the Commons schemas.
 
-Divergence is allowed — but **compliance claims then MUST NOT be made**.
+Divergence from the version-specific Commons contract means **compliance claims then MUST NOT be made**.
 
 ---
 
-## 8. Deviation Handling
+## 9. Deviation Handling
 
 If a deviation is found:
 
@@ -123,15 +145,16 @@ If a deviation is found:
 
 ---
 
-## 9. Compliance Checklist
+## 10. Compliance Checklist
 
-You may claim **Protocol-Commons compliant** if:
+You may claim **Protocol-Commons compliant** for a specific version if:
 
 - Strict Ajv validation enforced  
 - Version directories treated as immutable  
 - `$id` URLs resolve correctly  
-- CIDs and checksums match content  
+- CIDs and checksums match content when the version is claimed as canonical and pinned  
 - Changes logged and signed  
 - ENS TXT duties respected per SPEC.md  
+- Version status is described accurately as pinned canonical or pre-release  
 
 If uncertain → treat the implementation as **experimental**.

README.md

@@ -3,7 +3,7 @@
 **The canonical semantic contract for autonomous agents.**  
 *Verbs, schemas, and validation — or nothing interoperates.*
 
-[![Schemas](https://img.shields.io/badge/Schemas-Stable%20v1.1.0-brightgreen)](https://github.com/commandlayer/protocol-commons)
+[![Schemas](https://img.shields.io/badge/Schemas-v1.1.0%20candidate-yellow)](https://github.com/commandlayer/protocol-commons)
 [![NPM Version](https://img.shields.io/npm/v/@commandlayer/commons)](https://www.npmjs.com/package/@commandlayer/commons)
 [![CI Status](https://img.shields.io/github/actions/workflow/status/commandlayer/protocol-commons/validate.yml?branch=main&label=CI)](https://github.com/commandlayer/protocol-commons/actions/workflows/validate.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/commandlayer/protocol-commons/blob/main/LICENSE)
@@ -26,10 +26,11 @@ Protocol-Commons is the foundation for portable machine intent: a stable set of
 
 > **Integrity Notice — Protocol-Commons v1.1.0**
 >
-> Canonical schemas are pinned and immutable:
+> `schemas/v1.1.0/commons` is the current in-repo schema family, but its release CID is still pending:
 > `schemas/v1.1.0/commons` — CID: `TBD (pre-release)`
 >
-> Historical v1.0.0 artifacts remain in-repo for compatibility and verification.
+> `v1.0.0` remains the last fully pinned canonical release:
+> `schemas/v1.0.0/` — CID: `bafybeigvf6nkzws7dblos74dqqjkguwkrwn4a2c27ieygoxmgofyzdkz6m`
 >
 > Verify integrity locally:
 > ```bash
@@ -160,7 +161,9 @@ console.log(validate.errors ?? []);
 
 ## Commons v1.1.0
 
-Commons v1.1.0 introduces a simplified, flat schema surface for general-purpose agent actions.
+Commons v1.1.0 is the active schema family in this repository.
+
+It is ready for schema validation and local integration work, but its release provenance is still **pre-release** until a real CID is published.
 
 - Each request schema is standalone
 - Each receipt schema is standalone
@@ -349,10 +352,11 @@ Commons gives upper layers a stable meaning layer to build around.
 
 ## Status
 
-**Stable — v1.1.0 current**
+**v1.1.0 — active schema family, release CID pending**
 
-- `v1.1.0` is the current flat Commons layout
-- `v1.0.0` remains in-repo as a legacy schema family
+- `v1.1.0` is the current flat Commons layout in this repo
+- `v1.0.0` remains the last fully pinned canonical release
+- Do not describe `v1.1.0` provenance as fully canonical until pinning is complete
 
 ---
 

SCHEMAS.md

@@ -20,9 +20,20 @@ Once published, a version directory is immutable.
 
 ---
 
-## 2. Directory Layout
+## 2. Version Status
 
-### Current layout: v1.1.0
+This repository currently ships:
+
+- **v1.1.0** as the active in-repo schema family
+- **v1.0.0** as the historical and last fully pinned canonical release
+
+Because `manifest.json` still reports the v1.1.0 schema CID as pending, documentation MUST describe v1.1.0 as **pre-release for provenance/pinning status** until a real CID is published.
+
+---
+
+## 3. Directory Layout
+
+### Current in-repo layout: v1.1.0
 
 ```text
 schemas/v1.1.0/
@@ -32,7 +43,7 @@ schemas/v1.1.0/
         └── <verb>.receipt.schema.json
 ```
 
-### Legacy layout: v1.0.0
+### Historical pinned layout: v1.0.0
 
 ```text
 schemas/v1.0.0/
@@ -57,7 +68,7 @@ schemas/v1.0.0/
 
 ---
 
-## 3. Canonical Verb Set
+## 4. Canonical Verb Set
 
 | Verb | Purpose |
 |------|---------|
@@ -79,7 +90,7 @@ Each verb MUST define exactly:
 
 ---
 
-## 4. Deterministic `$id` Contract
+## 5. Deterministic `$id` Contract
 
 ### v1.1.0 request schemas
 
@@ -107,13 +118,13 @@ https://commandlayer.org/schemas/v1.1.0/commons/summarize/summarize.receipt.sche
 
 ### Legacy v1.0.0 note
 
-Legacy v1.0.0 schemas retain their older nested `$id` patterns and `_shared` references. Those patterns are not the v1.1.0 contract.
+Legacy v1.0.0 schemas retain their older nested `$id` patterns and `_shared` references. Those patterns are legacy-only and are not the v1.1.0 contract.
 
 All `$id` values MUST be fully qualified HTTPS URLs.
 
 ---
 
-## 5. v1.1.0 Request Contract
+## 6. v1.1.0 Request Contract
 
 Every v1.1.0 request MUST include:
 
@@ -130,7 +141,7 @@ v1.1.0 requests do not use nested request objects, `x402`, `trace`, or `actor` f
 
 ---
 
-## 6. v1.1.0 Receipt Contract
+## 7. v1.1.0 Receipt Contract
 
 Every v1.1.0 receipt MUST include:
 
@@ -159,21 +170,21 @@ The trust model is limited to signer attestation plus request/result hash refere
 
 ---
 
-## 7. Legacy v1.0.0 Scope
+## 8. Legacy v1.0.0 Scope
 
-v1.0.0 remains in-repo for compatibility and historical verification.
+v1.0.0 remains in-repo for compatibility, historical verification, and canonical pin auditing.
 
 Its schemas use:
 
 - `_shared` helper schemas
 - nested `requests/` and `receipts/` folders
-- older envelope conventions
+- older envelope conventions including `x402` and `trace`
 
-Documentation and tooling MUST distinguish that legacy structure from v1.1.0.
+Documentation and tooling MUST distinguish that legacy structure from v1.1.0 and MUST NOT present those legacy fields as universally normative.
 
 ---
 
-## 8. Versioning Rules
+## 9. Versioning Rules
 
 Once published under a version directory such as `schemas/v1.1.0/`, the following actions are prohibited:
 
@@ -186,7 +197,7 @@ Any change requires a new version directory.
 
 ---
 
-## 9. Validation Requirements
+## 10. Validation Requirements
 
 CI and local validation SHOULD enforce strict schema compilation behavior equivalent to:
 
@@ -210,7 +221,7 @@ All shipped valid and invalid examples MUST match the version-specific schema la
 
 ---
 
-## 10. Examples
+## 11. Examples
 
 Examples are maintained per version.
 
@@ -232,7 +243,7 @@ examples/v1.0.0/commons/<verb>/
 
 ---
 
-## 11. Provenance & Integrity
+## 12. Provenance & Integrity
 
 Integrity is tracked by:
 
@@ -245,13 +256,19 @@ Current v1.1.0 schema CID status:
 TBD (pre-release)
 ```
 
-Resolvers and auditors MUST reject mismatched artifacts.
+Last pinned canonical release CID:
+
+```text
+v1.0.0 → bafybeigvf6nkzws7dblos74dqqjkguwkrwn4a2c27ieygoxmgofyzdkz6m
+```
+
+Resolvers and auditors MUST reject mismatched artifacts and MUST distinguish between a shipped schema family and a fully pinned canonical release.
 
 ---
 
-## 12. Contact
+## 13. Contact
 
 - dev@commandlayer.org
 - PGP 5016 D496 9F38 22B2 C5A2 FA40 99A2 6950 197D AB0A
 
-**Status:** Stable `v1.1.0` current; `v1.0.0` legacy
+**Status:** v1.1.0 active in-repo schema family with pending CID; v1.0.0 retained as the historical pinned canonical release.