Clarify release validation discipline

.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

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 <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
 

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",