Tighten v1.1.0 release and fixture discipline by GsCommand · Pull Request #14 · commandlayer/protocol-commons · GitHub

GsCommand · 2026-03-20T02:37:29Z

Motivation

Make v1.1.0 the authoritative in-repo machine-artifact line by eliminating the legacy silent-default behavior and aligning public-facing $id URLs with actual repository artifact layout.
Remove misleading placeholder authority (fake CIDs / pseudo-signatures / implied tags) and make manifest/docs honest about unreleased state.
Restore trust in example fixtures by fixing systematic copy/paste contamination so each invalid fixture targets its own verb and fails for a single, obvious reason.
Simplify and clarify the validation/release surface so developer UX and release discipline are unambiguous.

Description

Retargeted checksum generation: scripts/generate-checksums.sh now defaults to schemas/v1.1.0 and emits an explicit message when no args are provided.
Made v1.1.0 schema $id values resolvable by switching them to the repository-backed raw GitHub URLs under https://raw.githubusercontent.com/commandlayer/protocol-commons/main/schemas/v1.1.0/... and updated scripts/validate-examples.mjs to use the same IDs.
Removed redundant wrapper scripts/ajv-run.mjs and the validate:schema script entry, consolidating validation to scripts/validate-all.mjs / scripts/validate-examples.mjs and keeping npm run validate as the single developer entrypoint.
Hardened manifest.json provenance: removed the `

Copilot

Pull request overview

This PR tightens the v1.1.0 release surface by making schema identifiers resolvable from the repo artifact layout, removing placeholder provenance claims, consolidating validation entrypoints, and cleaning up fixtures so invalid examples fail for a single targeted reason.

Changes:

Switched v1.1.0 schema $id (and example validation IDs) to resolvable raw.githubusercontent.com/.../schemas/v1.1.0/... URLs.
Retargeted checksum generation defaults to schemas/v1.1.0 and updated release/provenance docs + manifest to remove placeholder CID/tag authority.
Removed the redundant Ajv wrapper script and updated fixtures/examples across v1.1.0 (and some v1.0.0 invalid vectors) for better discipline.

Reviewed changes

Copilot reviewed 104 out of 105 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
SPEC.md	Updates v1.1.0 status/provenance language and documents new resolvable `$id` URL pattern.
SECURITY_PROVENANCE.md	Rewords provenance claims to distinguish pinned releases vs current in-repo line; removes v1.1.0 placeholder CID.
SCHEMAS.md	Aligns documented v1.1.0 `$id` URLs and CID-status wording with new release discipline.
README.md	Adds ToC, updates integrity notice, and refreshes examples/snippets to avoid placeholder authority.
CHANGELOG.md	Clarifies v1.1.0 summary and adds a v1.0.0 section.
ONBOARDING.md	Updates onboarding guidance and references CONTRIBUTING; removes outdated validation step.
GOVERNANCE.md	Adjusts steward responsibilities/phase trigger text and removes “Signed:” claim.
CONTRIBUTING.md	Adds contributor workflow, validation commands, and fixture discipline guidance.
manifest.json	Removes placeholder CID/tag claims; adds explicit release-state fields and public base URL.
package.json	Removes `validate:schema`, changes checksum generation invocation, pins Ajv deps, and ships CONTRIBUTING.
package-lock.json	Locks Ajv dependency versions to match package.json.
scripts/validate-examples.mjs	Updates v1.1.0 schema ID base to match new `$id` URLs.
scripts/generate-checksums.sh	Defaults checksum generation to `schemas/v1.1.0` and prints an explicit no-args message.
scripts/ajv-run.mjs	Deleted redundant wrapper entrypoint.
checksums.txt	Regenerated checksums (now only for v1.1.0 schema set).
schemas/v1.1.0/commons/analyze/analyze.request.schema.json	Updates `$id`; tightens `mode` enum.
schemas/v1.1.0/commons/analyze/analyze.receipt.schema.json	Updates `$id`.
schemas/v1.1.0/commons/classify/classify.request.schema.json	Updates `$id`.
schemas/v1.1.0/commons/classify/classify.receipt.schema.json	Updates `$id`.
schemas/v1.1.0/commons/clean/clean.request.schema.json	Updates `$id`.
schemas/v1.1.0/commons/clean/clean.receipt.schema.json	Updates `$id`.
schemas/v1.1.0/commons/convert/convert.request.schema.json	Updates `$id`.
schemas/v1.1.0/commons/convert/convert.receipt.schema.json	Updates `$id`.
schemas/v1.1.0/commons/describe/describe.request.schema.json	Updates `$id`.
schemas/v1.1.0/commons/describe/describe.receipt.schema.json	Updates `$id`.
schemas/v1.1.0/commons/explain/explain.request.schema.json	Updates `$id`.
schemas/v1.1.0/commons/explain/explain.receipt.schema.json	Updates `$id`.
schemas/v1.1.0/commons/fetch/fetch.request.schema.json	Updates `$id`.
schemas/v1.1.0/commons/fetch/fetch.receipt.schema.json	Updates `$id`.
schemas/v1.1.0/commons/format/format.request.schema.json	Updates `$id`.
schemas/v1.1.0/commons/format/format.receipt.schema.json	Updates `$id`.
schemas/v1.1.0/commons/parse/parse.request.schema.json	Updates `$id`.
schemas/v1.1.0/commons/parse/parse.receipt.schema.json	Updates `$id`.
schemas/v1.1.0/commons/summarize/summarize.request.schema.json	Updates `$id`.
schemas/v1.1.0/commons/summarize/summarize.receipt.schema.json	Updates `$id`.
examples/v1.1.0/commons/analyze/ts/valid/analyze.request.valid.1.ts	Aligns TS mode type to schema change.
examples/v1.1.0/commons/analyze/ts/valid/analyze.receipt.valid.1.ts	Replaces placeholder hashes/CID/signature with well-formed values.
examples/v1.1.0/commons/analyze/ts/valid/analyze.receipt.valid.2.ts	Replaces placeholder hashes/signature with well-formed values.
examples/v1.1.0/commons/analyze/ts/invalid/analyze.request.invalid.1.ts	Fixes verb contamination; targets a single invalid condition.
examples/v1.1.0/commons/analyze/json/valid/900-analyze.receipt.valid.json	Replaces placeholder hashes/CID/signature with well-formed values.
examples/v1.1.0/commons/analyze/json/invalid/001-analyze.request.invalid.json	Fixes verb contamination; targets a single invalid condition.
examples/v1.1.0/commons/classify/ts/valid/classify.receipt.valid.1.ts	Replaces placeholder hashes/CID/signature with well-formed values.
examples/v1.1.0/commons/classify/ts/invalid/classify.request.invalid.1.ts	Fixes verb contamination; targets a single invalid condition.
examples/v1.1.0/commons/classify/json/valid/900-classify.receipt.valid.json	Replaces placeholder hashes/CID/signature with well-formed values.
examples/v1.1.0/commons/classify/json/invalid/001-classify.request.invalid.json	Fixes verb contamination; targets a single invalid condition.
examples/v1.1.0/commons/clean/ts/valid/clean.receipt.valid.1.ts	Replaces placeholder hashes/CID/signature with well-formed values.
examples/v1.1.0/commons/clean/ts/valid/clean.receipt.valid.2.ts	Replaces placeholder hashes/signature with well-formed values.
examples/v1.1.0/commons/clean/ts/invalid/clean.request.invalid.1.ts	Fixes verb contamination; targets a single invalid condition.
examples/v1.1.0/commons/clean/json/valid/900-clean.receipt.valid.json	Replaces placeholder hashes/CID/signature with well-formed values.
examples/v1.1.0/commons/clean/json/invalid/001-clean.request.invalid.json	Fixes verb contamination; targets a single invalid condition.
examples/v1.1.0/commons/convert/ts/valid/convert.receipt.valid.1.ts	Replaces placeholder hashes/CID/signature with well-formed values.
examples/v1.1.0/commons/convert/ts/valid/convert.receipt.valid.2.ts	Replaces placeholder hashes/signature with well-formed values.
examples/v1.1.0/commons/convert/ts/invalid/convert.request.invalid.1.ts	Fixes verb contamination; targets a single invalid condition.
examples/v1.1.0/commons/convert/json/valid/900-convert.receipt.valid.json	Replaces placeholder hashes/CID/signature with well-formed values.
examples/v1.1.0/commons/convert/json/invalid/001-convert.request.invalid.json	Fixes verb contamination; targets a single invalid condition.
examples/v1.1.0/commons/describe/ts/valid/describe.receipt.valid.1.ts	Replaces placeholder hashes/CID/signature with well-formed values.
examples/v1.1.0/commons/describe/ts/valid/describe.receipt.valid.2.ts	Replaces placeholder hashes/signature with well-formed values.
examples/v1.1.0/commons/describe/ts/invalid/describe.request.invalid.1.ts	Fixes verb contamination; targets a single invalid condition.
examples/v1.1.0/commons/describe/json/valid/900-describe.receipt.valid.json	Replaces placeholder hashes/CID/signature with well-formed values.
examples/v1.1.0/commons/describe/json/invalid/001-describe.request.invalid.json	Fixes verb contamination; targets a single invalid condition.
examples/v1.1.0/commons/explain/ts/valid/explain.receipt.valid.1.ts	Replaces placeholder hashes/CID/signature with well-formed values.
examples/v1.1.0/commons/explain/ts/valid/explain.receipt.valid.2.ts	Replaces placeholder hashes/signature with well-formed values.
examples/v1.1.0/commons/explain/ts/invalid/explain.request.invalid.1.ts	Fixes verb contamination; targets a single invalid condition.
examples/v1.1.0/commons/explain/json/valid/900-explain.receipt.valid.json	Replaces placeholder hashes/CID/signature with well-formed values.
examples/v1.1.0/commons/explain/json/invalid/001-explain.request.invalid.json	Fixes verb contamination; targets a single invalid condition.
examples/v1.1.0/commons/fetch/ts/valid/fetch.receipt.valid.1.ts	Replaces placeholder hashes/CID/signature with well-formed values.
examples/v1.1.0/commons/fetch/ts/valid/fetch.receipt.valid.2.ts	Replaces placeholder hashes/signature with well-formed values.
examples/v1.1.0/commons/fetch/ts/invalid/fetch.request.invalid.1.ts	Fixes verb contamination; targets a single invalid condition.
examples/v1.1.0/commons/fetch/json/valid/900-fetch.receipt.valid.json	Replaces placeholder hashes/CID/signature with well-formed values.
examples/v1.1.0/commons/fetch/json/invalid/001-fetch.request.invalid.json	Fixes verb contamination; targets a single invalid condition.
examples/v1.1.0/commons/format/ts/valid/format.receipt.valid.1.ts	Replaces placeholder hashes/CID/signature with well-formed values.
examples/v1.1.0/commons/format/ts/valid/format.receipt.valid.2.ts	Replaces placeholder hashes/signature with well-formed values.
examples/v1.1.0/commons/format/ts/invalid/format.request.invalid.1.ts	Fixes verb contamination; targets a single invalid condition.
examples/v1.1.0/commons/format/json/valid/900-format.receipt.valid.json	Replaces placeholder hashes/CID/signature with well-formed values.
examples/v1.1.0/commons/format/json/invalid/001-format.request.invalid.json	Fixes verb contamination; targets a single invalid condition.
examples/v1.1.0/commons/parse/ts/valid/parse.receipt.valid.1.ts	Replaces placeholder hashes/CID/signature with well-formed values.
examples/v1.1.0/commons/parse/ts/valid/parse.receipt.valid.2.ts	Replaces placeholder hashes/signature with well-formed values.
examples/v1.1.0/commons/parse/ts/invalid/parse.request.invalid.1.ts	Fixes verb contamination; targets a single invalid condition.
examples/v1.1.0/commons/parse/json/valid/900-parse.receipt.valid.json	Replaces placeholder hashes/CID/signature with well-formed values.
examples/v1.1.0/commons/parse/json/invalid/001-parse.request.invalid.json	Fixes verb contamination; targets a single invalid condition.
examples/v1.1.0/commons/summarize/ts/valid/summarize.receipt.valid.1.ts	Replaces placeholder hashes/CID/signature with well-formed values.
examples/v1.1.0/commons/summarize/ts/valid/summarize.receipt.valid.2.ts	Replaces placeholder hashes/signature with well-formed values.
examples/v1.1.0/commons/summarize/ts/summarize.receipt.examples.ts	Refreshes receipt examples; keeps invalid example invalid for targeted reasons.
examples/v1.1.0/commons/summarize/ts/invalid/summarize.request.invalid.ts	Clarifies invalid fixture intent in header comment.
examples/v1.1.0/commons/summarize/ts/invalid/summarize.request.invalid.1.ts	Fixes verb/mode contamination; targets a single invalid condition.
examples/v1.1.0/commons/summarize/json/valid/900-summarize.receipt.valid.json	Replaces placeholder hashes/CID/signature with well-formed values.
examples/v1.1.0/commons/summarize/json/invalid/001-summarize.request.invalid.json	Fixes verb/mode contamination; targets a single invalid condition.
examples/v1.0.0/commons/analyze/ts/invalid/analyze.request.invalid.1.ts	Fixes verb contamination in historical invalid fixture.
examples/v1.0.0/commons/analyze/invalid/001-analyze.request.invalid.json	Fixes verb contamination in historical invalid fixture.
examples/v1.0.0/commons/classify/ts/invalid/classify.request.invalid.1.ts	Fixes verb contamination in historical invalid fixture.
examples/v1.0.0/commons/classify/invalid/001-classify.request.invalid.json	Fixes verb contamination in historical invalid fixture.
examples/v1.0.0/commons/clean/ts/invalid/clean.request.invalid.1.ts	Fixes verb contamination in historical invalid fixture.
examples/v1.0.0/commons/clean/invalid/001-clean.request.invalid.json	Fixes verb contamination in historical invalid fixture.
examples/v1.0.0/commons/convert/ts/invalid/convert.request.invalid.1.ts	Fixes verb contamination in historical invalid fixture.
examples/v1.0.0/commons/convert/invalid/001-convert.request.invalid.json	Fixes verb contamination in historical invalid fixture.
examples/v1.0.0/commons/describe/ts/invalid/describe.request.invalid.1.ts	Fixes verb contamination in historical invalid fixture.
examples/v1.0.0/commons/describe/invalid/001-describe.request.invalid.json	Fixes verb contamination in historical invalid fixture.
examples/v1.0.0/commons/explain/ts/invalid/explain.request.invalid.1.ts	Fixes verb contamination in historical invalid fixture.
examples/v1.0.0/commons/explain/invalid/001-explain.request.invalid.json	Fixes verb contamination in historical invalid fixture.
examples/v1.0.0/commons/fetch/ts/invalid/fetch.request.invalid.1.ts	Fixes verb contamination in historical invalid fixture.
examples/v1.0.0/commons/fetch/invalid/001-fetch.request.invalid.json	Fixes verb contamination in historical invalid fixture.
examples/v1.0.0/commons/format/ts/invalid/format.request.invalid.1.ts	Fixes verb contamination in historical invalid fixture.
examples/v1.0.0/commons/format/invalid/001-format.request.invalid.json	Fixes verb contamination in historical invalid fixture.
examples/v1.0.0/commons/parse/ts/invalid/parse.request.invalid.1.ts	Fixes verb contamination in historical invalid fixture.
examples/v1.0.0/commons/parse/invalid/001-parse.request.invalid.json	Fixes verb contamination in historical invalid fixture.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-20T02:44:40Z

+ROOT="${1:-schemas/v1.1.0}"
 OUT="${2:-checksums.txt}"


schemas_root now defaults to schemas/v1.1.0, and checksums:gen is invoked with no args, which means checksums.txt no longer covers the shipped schemas/v1.0.0 artifacts. Since the package still publishes schemas/ (including v1.0.0), this weakens npm run checksums:verify as an integrity check for the historical pinned release. Consider generating checksums for schemas/ by default (or maintaining per-version checksum files and verifying both).

Copilot · 2026-03-20T02:44:40Z

    "validate:all": "npm run validate:schemas && npm run validate:examples",
    "validate": "npm run validate:all",
-    "checksums:gen": "bash scripts/generate-checksums.sh schemas checksums.txt",
+    "checksums:gen": "bash scripts/generate-checksums.sh",


checksums:gen now runs generate-checksums.sh with no args, which will regenerate checksums.txt for only schemas/v1.1.0 given the new default. If the intent is for npm run checksums:verify to validate all published artifacts in schemas/ (including v1.0.0), this should pass explicit args (e.g., schemas) or add a separate verification step for legacy folders.

Copilot · 2026-03-20T02:44:41Z

+99f35b0dd3d147b0ef53f61486b39d5daf13026a439c5e416a4786ee22468d00  schemas/v1.1.0/commons/analyze/analyze.receipt.schema.json
+dcae0af9e0cc54fc68a00a6ca46b6db247a901c22dfe17990fa67aaaeaaf0c34  schemas/v1.1.0/commons/analyze/analyze.request.schema.json
+452030e1475664012a57478a7004ac061a401792c12f01508345f74c112f1804  schemas/v1.1.0/commons/classify/classify.receipt.schema.json
+aad6708bd8be3f48cfbc800d563c1e27d04643360d31fc4fb88929626410a943  schemas/v1.1.0/commons/classify/classify.request.schema.json
+29623e25098a2054aa72595d2548e59940ba69aec5deb3eeb4ad52c82d783e5c  schemas/v1.1.0/commons/clean/clean.receipt.schema.json


checksums.txt now contains only schemas/v1.1.0/... entries, so sha256sum -c checksums.txt will not detect tampering/mutation of the historical schemas/v1.0.0 tree that is still distributed in the package. Either restore v1.0.0 entries, generate checksums for the full schemas/ directory, or split checksum files per version and verify both.

Copilot · 2026-03-20T02:44:41Z


 ```text
-https://commandlayer.org/schemas/v1.1.0/commons/<verb>/<verb>.request.schema.json
+https://raw.githubusercontent.com/commandlayer/protocol-commons/main/schemas/v1.1.0/commons/<verb>/<verb>.request.schema.json


The normative $id pattern is now tied to a mutable branch URL (raw.githubusercontent.com/.../main/...). This undermines the “immutable version directory” guarantees because the identifier resolves through a moving ref even if content is intended to be stable. Prefer a tag- or commit-SHA-based URL for $id (and derive it from manifest.json), then update docs/scripts accordingly when the release tag is created.

Copilot · 2026-03-20T02:44:41Z

+    requestSchemaId: (verb) => `https://raw.githubusercontent.com/commandlayer/protocol-commons/main/schemas/v1.1.0/commons/${verb}/${verb}.request.schema.json`,
+    receiptSchemaId: (verb) => `https://raw.githubusercontent.com/commandlayer/protocol-commons/main/schemas/v1.1.0/commons/${verb}/${verb}.receipt.schema.json`,
    validDir: (verb) => path.join(ROOT, "examples", "v1.1.0", "commons", verb, "json", "valid"),
    invalidDir: (verb) => path.join(ROOT, "examples", "v1.1.0", "commons", verb, "json", "invalid")


requestSchemaId/receiptSchemaId hardcode the v1.1.0 public base URL even though manifest.json now records schema_public_base_url. To avoid drift (especially if switching from /main/ to a release tag later), consider loading the base URL from manifest.json and composing the per-verb schema IDs from it.

Copilot · 2026-03-20T02:44:41Z

+  "schema_public_base_url": "https://raw.githubusercontent.com/commandlayer/protocol-commons/main/schemas/v1.1.0",
+  "schemas_cid_status": "not-generated-in-repo",
+  "release_tag": "commons-schemas-v1.1.0",
+  "release_tag_status": "pending-creation"


schemas_cid_status / release_tag / release_tag_status are duplicated both under active_release and again as top-level fields. This duplication is easy to let drift over time; consider keeping release-state fields in a single canonical location in the manifest (or making one section clearly derived from the other).

Tighten v1.1.0 release and fixture discipline

7423523

GsCommand added the codex label Mar 20, 2026 — with ChatGPT Codex Connector

GsCommand requested a review from Copilot March 20, 2026 02:38

Copilot started reviewing on behalf of GsCommand March 20, 2026 02:39 View session

Copilot AI reviewed Mar 20, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Tighten v1.1.0 release and fixture discipline#14

Tighten v1.1.0 release and fixture discipline#14
GsCommand wants to merge 1 commit intomainfrom
codex/fix-repository-issues-for-protocol-grade-compliance

GsCommand commented Mar 20, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 20, 2026

Uh oh!

Copilot AI Mar 20, 2026

Uh oh!

Copilot AI Mar 20, 2026

Uh oh!

Copilot AI Mar 20, 2026

Uh oh!

Copilot AI Mar 20, 2026

Uh oh!

Copilot AI Mar 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		ROOT="${1:-schemas/v1.1.0}"
		OUT="${2:-checksums.txt}"

Conversation

GsCommand commented Mar 20, 2026

Motivation

Description

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants