diff --git a/CHANGELOG.md b/CHANGELOG.md index b3d4a07..e5bce7a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,3 +10,9 @@ - Established Commons v1.1.0 as the active in-repo schema surface for new integrations - Retained v1.0.0 as the last pinned canonical release until v1.1.0 pinning is completed - Preserved earlier schema versions for compatibility and historical reference + +## 1.0.0 + +- Initial Protocol-Commons release with versioned Commons schemas, shared primitives, and example vectors under `schemas/v1.0.0` and `examples/v1.0.0` +- Introduced the canonical Commons verb set and request/receipt validation model for cross-runtime interoperability +- Established the historical pinned release line that `v1.1.0` now extends as the current in-repo schema family diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2c1df2a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,57 @@ +# Contributing — Protocol Commons + +Protocol-Commons contributions must be small, traceable, and validation-complete. + +## Pull Request Spine + +Every PR should: + +1. Open from a focused branch for one change set +2. Explain the semantic, schema, or documentation impact +3. Include schema/example updates together when contracts change +4. Pass the required validation commands before review +5. Update release notes when the visible contract changes + +## Commit Convention + +Use a clear imperative subject line. Prefer conventional-style prefixes when they fit, for example: + +- `docs: tighten README contract language` +- `feat: add new commons verb schema family` +- `fix: correct receipt validation example` + +## Required Checks + +Run the canonical validation command before opening a PR: + +```bash +npm install +npm run validate +``` + +Run additional checks when packaging behavior changes: + +```bash +npm run test:smoke:import +npm run test:smoke:pack +``` + +## When Schemas Change + +If you change a schema or semantic contract, you must also: + +- Add or update matching examples/tests +- Preserve immutability of published version directories unless the change is explicitly historical documentation only +- Review `SCHEMAS.md` and `SPEC.md` for versioning implications +- Update `CHANGELOG.md` when the externally visible contract changes +- Update `RESOLUTION.md`, provenance, or checksum artifacts if the release process requires it + +## Versioning Expectations + +- Treat published release lines as append-only history +- Use a new version directory for semantic changes +- Keep `v1.1.0` documented as the current in-repo line until a newer line is intentionally introduced + +## Review Standard + +A contribution is ready for review when a maintainer can understand the intent quickly, reproduce validation locally, and see exact schema/example/doc alignment without extra interpretation. diff --git a/ONBOARDING.md b/ONBOARDING.md index 21cb772..6743258 100644 --- a/ONBOARDING.md +++ b/ONBOARDING.md @@ -72,11 +72,7 @@ If a change is not reflected here → **not canonical.** Protocol-Commons governs TXT keys that resolve schema semantics. Canonical definitions → `SPEC.md`. -## 4. Contribution Flow -1. Open an Issue describing context + verb(s) -2. Design change per `SCHEMAS.md` -3. Update schemas + examples -4. Validate: +## 4. Working Norms ``` npm install @@ -92,7 +88,7 @@ npm run validate:examples 5. Update `RESOLUTION.md`, provenance 6. Submit PR with version class (MAJOR/MINOR/PATCH) -Once approved → tagged + pinned. +If you are preparing a contribution, follow `CONTRIBUTING.md`. ## 5. What “Good” Looks Like diff --git a/README.md b/README.md index 6d1b2e3..c6872a3 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,28 @@ If agents cannot agree on what actions mean, interoperability breaks. --- +## Table of Contents +- [Real verbs. Real receipts.](#real-verbs-real-receipts) +- [Quickstart](#quickstart) +- [Commons v1.1.0](#commons-v110) +- [What Commons enables](#what-commons-enables) +- [Why this exists](#why-this-exists) +- [Canonical Verbs](#canonical-verbs) +- [Overview](#overview) +- [Key Principles](#key-principles) +- [This is not…](#this-is-not) +- [CommandLayer Protocol Stack](#commandlayer-protocol-stack) +- [Status](#status) +- [Repository Structure](#repository-structure) +- [Manifest](#manifest) +- [Immutability & Checksums](#immutability--checksums) +- [Validation](#validation) +- [License](#license) +- [Next Layers](#next-layers) +- [References](#references) + +--- + ## Real verbs. Real receipts. ```jsonc @@ -89,14 +111,13 @@ Every v1.1.0 Commons receipt uses the same evidence-oriented spine: - `status` - `timestamp` -- `agent` - `request_hash` -- `result_hash` *(optional)* -- `result_cid` *(optional)* - `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. + --- ## Quickstart @@ -196,7 +217,7 @@ The receipt contract is proof-oriented rather than transport-oriented: "version": "1.1.0", "status": "ok | error", "timestamp": "", - "agent": "", + "agent": "", "request_hash": "sha256:<64 lowercase hex chars>", "result_hash": "sha256:<64 lowercase hex chars>", "result_cid": "", @@ -208,28 +229,6 @@ The receipt contract is proof-oriented rather than transport-oriented: These fields let consumers verify that a signer attested to a specific request hash and, when present, a specific result hash or result CID. Commons does not define transport settlement, execution proofs beyond these fields, or any x402-specific wrapping. -## Table of Contents -- [Real verbs. Real receipts.](#real-verbs-real-receipts) -- [Quickstart](#quickstart) -- [Commons v1.1.0](#commons-v110) -- [What Commons enables](#what-commons-enables) -- [Why this exists](#why-this-exists) -- [Canonical Verbs](#canonical-verbs) -- [Overview](#overview) -- [Key Principles](#key-principles) -- [This is not…](#this-is-not) -- [CommandLayer Protocol Stack](#commandlayer-protocol-stack) -- [Status](#status) -- [Repository Structure](#repository-structure) -- [Manifest](#manifest) -- [Immutability & Checksums](#immutability--checksums) -- [Validation](#validation) -- [License](#license) -- [Next Layers](#next-layers) -- [References](#references) - ---- - ## Why this exists Fragmented agents create isolated ecosystems and brittle automation. @@ -419,7 +418,7 @@ Published version directories must not be edited in place. ## Validation -Available commands: +Use `npm run validate` as the canonical repo-wide validation command. For targeted checks, the repo also exposes: ```bash npm run validate