ECC/skills/github-ops/references/ecc-release-checklist.md

ECC Signed Patch Release Checklist

Use this when releasing affaan-m/ECC, especially for ECC-031 or any follow-up where the Git tag identity, npm provenance, GitHub Release, and announcement evidence all need to align.

Milestone And Contract

• Milestone: M0 in the ECC 2.2 release train.
• Contract: ship one exact, verified artifact, keep ECC authority over release evidence and canonical state, and do not blur current shipped behavior with future plans.
• Current gate: close the unsigned v2.2.0 exception by releasing a new signed 2.2.x patch from exact green main.

Non-Negotiable Invariants

• Never move, recreate, or reuse v2.2.0.
• The new patch tag must be a signed annotated tag on exact green origin/main.
• Publish only the archive packed and verified by the release workflow.
• Treat any non-E404 npm lookup failure as blocking.
• Do not manually promote latest, replace release assets, or publish different bytes under the same version.
• Keep Itô and Nasiko wording bounded to shipped behavior only.

ECC-031 State To Refresh Before Mutating

As of 2026-08-31:

• v2.2.0 is live and latest, but git tag -v v2.2.0 returns error: no signature found.
• main currently points at a104765bf20fd1480a3dd30f514f18f73ca80b8a.
• Exact-main CI run 33429642769 is green.
• Exact-main CodeQL run 33429641766 is green.
• No remote tag, GitHub Release, or npm publication exists for 2.2.1.
• package.json on main still declares 2.2.0, so a reviewed version-prep change must land before the signed tag can be pushed.

Refresh those facts before mutating:

git fetch origin main --tags
git rev-parse origin/main
gh run view 33429642769 --repo affaan-m/ECC --json status,conclusion,url
gh run view 33429641766 --repo affaan-m/ECC --json status,conclusion,url
gh release view v2.2.0 --repo affaan-m/ECC --json tagName,targetCommitish,publishedAt,url
git ls-remote --tags origin 'refs/tags/v2.2.0*'
git tag -v v2.2.0
npm view ecc-universal dist-tags --json

Checklist

1. Reconfirm The Release Surface

• Verify the release commit you intend to tag is exact origin/main.
• Verify required hosted checks on that exact main commit are green.
• Verify no overlapping release-surface PR or hotfix needs to land first.
• Record the exact main SHA you are about to build from.

gh pr list --repo affaan-m/ECC --state open --limit 20
gh run list --repo affaan-m/ECC --branch main --limit 10
git fetch origin main --tags
git switch main
git pull --ff-only origin main
git status --short
git rev-parse HEAD
git rev-parse origin/main

Stop if:

• HEAD differs from origin/main;
• any required main run is red or still pending;
• a new release-surface merge materially changes the patch contents.

2. Choose The Patch Version And Confirm It Is Unused

Expected next version is 2.2.1 unless it already exists.

VERSION=2.2.1
git ls-remote --tags origin "refs/tags/v${VERSION}*"
gh release view "v${VERSION}" --repo affaan-m/ECC
npm view "ecc-universal@${VERSION}" version

Expected:

• no remote tag;
• no GitHub Release;
• npm returns E404.

3. Prepare The Patch-Release PR

• Branch from exact current main.
• Update release metadata to the new patch version.
• Add reviewed release notes under docs/releases/<version>/release-notes.md.
• Add a patch runbook under docs/releases/<version>/launch-runbook.md.
• Open and merge that prep PR.
• Wait for fresh main CI and CodeQL on the merged prep commit.

Important:

• Do not use scripts/release.sh as-is for ECC-031.
• That script still commits, tags, and pushes in one shot, which bypasses the required merge -> exact main CI green -> signed tag push boundary.
• PAT-backed GitHub access is not enough. The release operator also needs a locally available signing identity before creating the tag.

Minimum prep checks:

node tests/plugin-manifest.test.js
node tests/scripts/build-opencode.test.js
node tests/ci/release-packed-artifact-workflow.test.js

4. Wait For Exact Main To Turn Green Again

After the prep PR merges, the new main commit becomes the only commit you may tag.

gh run list --repo affaan-m/ECC --branch main --limit 10
gh run view RUN_ID --repo affaan-m/ECC --json status,conclusion,url
git fetch origin main --tags
git switch main
git pull --ff-only origin main
git rev-parse HEAD
git rev-parse origin/main

5. Create And Push The Signed Tag

From a clean main checkout on the exact green commit:

VERSION=2.2.1
git fetch origin main --tags
git switch main
git pull --ff-only origin main
git status --short
git rev-parse HEAD
git rev-parse origin/main
git tag -s "v${VERSION}" -m "ECC ${VERSION}" HEAD
git tag -v "v${VERSION}"
git push origin "refs/tags/v${VERSION}"

Required proof:

• clean worktree;
• HEAD == origin/main;
• git tag -v succeeds locally before push.

6. Watch The Release Workflow

The tag push should trigger .github/workflows/release.yml, which must:

1. prove the tag commit equals origin/main;
2. validate version and manifests;
3. run IOC and payload checks;
4. pack one archive and record its SHA-256;
5. verify that exact archive on Linux, macOS, and Windows;
6. publish to npm under staged with provenance;
7. read back dist.integrity and compare it to the tested archive;
8. promote the verified version to latest;
9. create the GitHub Release from reviewed notes.

7. Perform Mandatory Public Readback And Canaries

After the workflow succeeds:

VERSION=2.2.1
npm view ecc-universal dist-tags --json
npm view "ecc-universal@${VERSION}" name version dist.integrity --json
gh release view "v${VERSION}" --repo affaan-m/ECC \
  --json tagName,name,isDraft,isPrerelease,publishedAt,url
gh api repos/affaan-m/ECC/releases/latest --jq .tag_name
npx --yes "ecc-universal@${VERSION}" setup --help
npx --yes ecc-universal@latest setup --help

Also run the clean install, doctor, repair, uninstall, and rollback canaries required by the checked-in runbook, and verify the native Claude marketplace path remains installable:

/plugin marketplace add https://github.com/affaan-m/ECC
/plugin install ecc@ecc

8. Verify Announcement Delivery

• One Announcements Discussion exists for the new tag.
• It uses the GitHub Release body and URL.
• Discord delivery is evidenced by the workflow receipt.
• No duplicate Discussion or Discord message was created.

9. Record Evidence And Close Out ECC-031

• Complete the release evidence record with actual SHAs, workflow URLs, release URLs, npm integrity, and announcement state.
• Update the dashboard ticket and release docs with the final patch tag and proof URLs.
• Keep v2.2.0 documented as the historical unsigned exception.
• Mark ECC-031 resolved only after the signed patch release is public and every required gate above is backed by evidence.