diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 3b0b86d..38c2ac9 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -5,9 +5,17 @@ on: branches: ["main"] pull_request: branches: ["main"] + workflow_dispatch: + inputs: + require_mirrors: + description: "Also require commandlayer.org mirror resolution (publish-time check)" + required: false + default: false + type: boolean jobs: - validate-current-release: + validate-release-readiness: + name: Validate current release readiness runs-on: ubuntu-latest steps: - name: Checkout @@ -22,19 +30,21 @@ jobs: - name: Install dependencies run: npm ci - - name: Validate current-line schema and card integrity - run: npm run validate:current + - name: Standard local release gate (`npm run validate`) + run: npm run validate - - name: Verify release checksums - run: npm run validate:checksums - - - name: Validate release reproducibility and external bindings + - name: Release-grade gate (`npm run validate:release`) run: npm run validate:release - # Mirror enforcement stays explicit because publish-time mirror availability can lag normal CI. - # Run `npm run validate:release -- --require-mirrors` when commandlayer.org mirrors are expected to be live. + - name: Publish-time mirror gate (`npm run validate:release -- --require-mirrors`) + if: ${{ github.event_name == 'workflow_dispatch' && inputs.require_mirrors }} + run: npm run validate:release -- --require-mirrors + + # Mirror enforcement is intentionally opt-in for normal CI because publish-time mirror availability can lag routine validation. + # Use the manual workflow_dispatch input once mirrors are expected to be live for the tag being pushed. validate-legacy-compatibility: + name: Validate legacy compatibility line runs-on: ubuntu-latest steps: - name: Checkout diff --git a/README.md b/README.md index e87cad3..6c329a3 100644 --- a/README.md +++ b/README.md @@ -83,13 +83,13 @@ For `v1.1.0`: ## Validation -Run standard validation: +Run the canonical local gate: ```bash npm run validate ``` -Run release-level validation (URLs + bundle integrity): +Run the canonical release gate: ```bash npm run validate:release @@ -163,15 +163,15 @@ agent-cards/ } ``` -- `npm run validate` — standard local validation for canonical v1.1.0 cards, discovery descriptors, manifest alignment, and `checksums.txt` +- `npm run validate` — the canonical local validation entrypoint for canonical v1.1.0 cards, discovery descriptors, manifest alignment, and `checksums.txt` - `node scripts/build-dist-pin.mjs` — rebuild the committed derivative publish bundle from canonical root files -- `npm run validate:release` — release-scoped validation that: +- `npm run validate:release` — the canonical release validation entrypoint; it runs `npm run validate` first and then: - confirms `meta/manifest.json` matches every current card binding - confirms `dist-pin/agent-cards/v1.1.0/` matches a freshly generated derivative bundle - resolves every upstream tagged schema URL over the network - optionally resolves mirrors when run with `--require-mirrors` -Routine CI runs `npm run validate` and `npm run validate:release`. Mirror resolution remains explicit and optional in routine CI; enforce it with `npm run validate:release -- --require-mirrors` when the published mirrors are expected to be live. +Routine CI shows both gates explicitly: `npm run validate` for the local release gate, then `npm run validate:release` for the release-grade gate. Mirror resolution remains explicit and opt-in in routine CI; enforce it with `npm run validate:release -- --require-mirrors` once the published mirrors are expected to be live for the exact tag being pushed. ## Release and publication model @@ -188,14 +188,32 @@ The current release review checks: ## Release procedure +Use one clean ceremony from "ready" to public release. Do not substitute alternate wrappers or partial checks. + 1. Edit only the canonical root artifacts for the current `v1.1.0` line. -2. Rebuild the committed derivative bundle with `node scripts/build-dist-pin.mjs`. +2. Rebuild the committed derivative bundle with `npm run generate:dist-pin`. 3. Regenerate root integrity digests with `node scripts/generate-checksums.mjs`. -4. Run `npm run validate` and `npm run validate:release`. -5. Publish the reviewed snapshot from the exact commit you validated. The release snapshot is defined by the tagged commit together with `checksums.txt`. -6. Create or move the release tag only after the repository state above has been reviewed and published. This repository does not claim that a new tag already exists. +4. Run the canonical local gate: `npm run validate`. +5. Run the canonical release gate: `npm run validate:release`. +6. Verify the checksum file you are about to publish is the one you just validated (`checksums.txt` must remain unchanged between steps 4-5 and tagging). +7. Create the release tag from that exact validated commit. +8. Push the commit and tag. +9. Run the final public verification: `npm run validate:release -- --require-mirrors` only after upstream tags and `commandlayer.org` mirrors are expected to be live. +10. Confirm the public release artifacts resolve from the pushed tag, published checksum set, upstream schema tags, and mirrors before announcing completion. + +Recommended command order for maintainers: + +```bash +npm run generate:dist-pin +node scripts/generate-checksums.mjs +npm run validate +npm run validate:release +git tag +git push origin main --follow-tags +npm run validate:release -- --require-mirrors +``` -This keeps the trust story narrow: root artifacts are canonical, `dist-pin/` is a committed derivative publish bundle, `.well-known/` remains discovery-only, and the tag plus checksums identify the release snapshot. +This keeps the trust story narrow: root artifacts are canonical, `dist-pin/` is a committed derivative publish bundle, `.well-known/` remains discovery-only, checksum verification is explicit, and the pushed tag plus checksums identify the release snapshot. If external publish surfaces are not live yet, the release is not fully verified; do not hide that state. ## Release surfaces diff --git a/package.json b/package.json index 0b5a088..ba86a23 100644 --- a/package.json +++ b/package.json @@ -40,13 +40,12 @@ "README.md" ], "scripts": { + "validate": "npm run validate:current && npm run validate:checksums", "validate:current": "node scripts/validate-cards.mjs --mode=current", "validate:legacy": "node scripts/validate-cards.mjs --mode=legacy", "validate:checksums": "node scripts/generate-checksums.mjs --verify", - "validate": "npm run validate:cards && npm run validate:checksums", - "generate:dist-pin": "node scripts/build-dist-pin.mjs", - "validate:release": "node scripts/validate-release.mjs", - "validate:cards": "node scripts/validate-cards.mjs --mode=release" + "validate:release": "npm run validate && node scripts/validate-release.mjs", + "generate:dist-pin": "node scripts/build-dist-pin.mjs" }, "devDependencies": { "ajv": "^8.17.1",