From 51afb12b394c26d08e68902a48c0ad5905f615d1 Mon Sep 17 00:00:00 2001 From: Greg Soucy Date: Thu, 19 Mar 2026 22:36:24 -0400 Subject: [PATCH] docs: tighten repo docs and validation entrypoints --- CHANGELOG.md | 6 +++++ CONTRIBUTING.md | 57 +++++++++++++++++++++++++++++++++++++++++++++ ONBOARDING.md | 21 +++++++---------- README.md | 55 +++++++++++++++++++++---------------------- package.json | 1 - scripts/ajv-run.mjs | 15 ------------ 6 files changed, 97 insertions(+), 58 deletions(-) create mode 100644 CONTRIBUTING.md delete mode 100644 scripts/ajv-run.mjs 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 3e729ea..06a1c52 100644 --- a/ONBOARDING.md +++ b/ONBOARDING.md @@ -72,21 +72,16 @@ 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 -npm run validate -npm run validate:examples -``` -5. Update `RESOLUTION.md`, provenance -6. Submit PR with version class (MAJOR/MINOR/PATCH) +Before changing schemas or examples: + +- 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 -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 57154e4..3aab3ac 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 @@ -194,7 +215,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": "", @@ -206,28 +227,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. @@ -384,7 +383,6 @@ Commons gives upper layers a stable meaning layer to build around. │ ├── .request.schema.json │ └── .receipt.schema.json └── scripts/ - ├── ajv-run.mjs ├── validate-all.mjs └── validate-examples.mjs ``` @@ -418,12 +416,11 @@ 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: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`. diff --git a/package.json b/package.json index ef14cde..235c2e7 100644 --- a/package.json +++ b/package.json @@ -49,7 +49,6 @@ "ajv-formats": "^3.0.1" }, "scripts": { - "validate:schema": "node scripts/ajv-run.mjs", "validate:schemas": "node scripts/validate-all.mjs", "validate:examples": "node scripts/validate-examples.mjs", "validate:all": "npm run validate:schemas && npm run validate:examples", diff --git a/scripts/ajv-run.mjs b/scripts/ajv-run.mjs deleted file mode 100644 index 462a1e6..0000000 --- a/scripts/ajv-run.mjs +++ /dev/null @@ -1,15 +0,0 @@ -#!/usr/bin/env node -/** - * ajv-run.mjs - * - * Convenience entrypoint for schema validation. - * Currently just delegates to validate-all.mjs so that: - * - * npm run validate:schema - * - * is equivalent to: - * - * npm run validate:schemas - */ - -import './validate-all.mjs';