ci-validation-gates

## Context CI workflows must be defensive. These patterns were learned from the v0.8.22 release disaster where invalid semver, wrong token types, missing retry logic, and draft releases caused a multi-hour outage. Both Drucker (CI/CD) and Trejo (Release Manager) carried this knowledge in their charters — now centralized here. ## Patterns ### Semver Validation Gate Every publish workflow MUST validate version format before `npm publish`. 4-part versions (e.g., 0.8.21.4) are NOT valid semver — npm mangles them. ```yaml - name: Validate semver run: | VERSION="${{ github.event.release.tag_name }}" VERSION="${VERSION#v}" if ! npx semver "$VERSION" > /dev/null 2>&1; then echo "❌ Invalid semver: $VERSION" echo "Only 3-part versions (X.Y.Z) or prerelease (X.Y.Z-tag.N) are valid." exit 1 fi echo "✅ Valid semver: $VERSION" ``` ### NPM Token Type Verification NPM_TOKEN MUST be an Automation token, not a User token with 2FA: - User tokens require OTP — CI can't provide it → EOTP error - Create Automation tokens at npmjs.com → Settings → Access Tokens → Automation - Verify before first publish in any workflow ### Retry Logic for npm Registry Propagation npm registry uses eventual consistency. After `npm publish` succeeds, the package may not be immediately queryable. - Propagation: typically 5-30s, up to 2min in rare cases - All verify steps: 5 attempts, 15-second intervals - Log each attempt: "Attempt 1/5: Checking package..." - Exit loop on ...