원클릭으로
ci-validation-gates
// Defensive CI/CD patterns: semver validation, token checks, retry logic, draft detection — earned from v0.8.22
// Defensive CI/CD patterns: semver validation, token checks, retry logic, draft detection — earned from v0.8.22
| name | ci-validation-gates |
| description | Defensive CI/CD patterns: semver validation, token checks, retry logic, draft detection — earned from v0.8.22 |
| domain | ci-cd |
| confidence | high |
| source | extracted from Drucker and Trejo charters — earned knowledge from v0.8.22 release incident |
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.
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.
- 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 MUST be an Automation token, not a User token with 2FA:
npm registry uses eventual consistency. After npm publish succeeds, the package may not be immediately queryable.
- name: Verify package (with retry)
run: |
MAX_ATTEMPTS=5
WAIT_SECONDS=15
for attempt in $(seq 1 $MAX_ATTEMPTS); do
echo "Attempt $attempt/$MAX_ATTEMPTS: Checking $PACKAGE@$VERSION..."
if npm view "$PACKAGE@$VERSION" version > /dev/null 2>&1; then
echo "✅ Package verified"
exit 0
fi
[ $attempt -lt $MAX_ATTEMPTS ] && sleep $WAIT_SECONDS
done
echo "❌ Failed to verify after $MAX_ATTEMPTS attempts"
exit 1
Draft releases don't emit release: published event. Workflows MUST:
release: published (NOT created)Set SKIP_BUILD_BUMP=1 (or $env:SKIP_BUILD_BUMP = "1" on Windows) before ANY release build. bump-build.mjs is for dev builds ONLY — it silently mutates versions.
| # | What Happened | Root Cause | Prevention |
|---|---|---|---|
| 1 | 4-part version published, npm mangled it | No semver validation gate | npx semver check before every publish |
| 2 | CI failed 5+ times with EOTP | User token with 2FA | Automation token only |
| 3 | Verify returned false 404 | No retry logic for propagation | 5 attempts, 15s intervals |
| 4 | Workflow never triggered | Draft release doesn't emit event | Never create draft releases |
| 5 | Version mutated during release | bump-build.mjs ran in release | SKIP_BUILD_BUMP=1 |
How to handle natural language document requests—resolve friendly names to paths, then use appropriate tools for reading, searching, summarizing, or analyzing Word documents
Standard collaboration patterns for all squad agents — worktree awareness, decisions, cross-agent communication
Platform detection and adaptive spawning for CLI vs VS Code vs other surfaces
How to coordinate with squads on different machines using git as transport
Microsoft Style Guide + Squad-specific documentation patterns
Squad branching model: dev-first workflow with insiders preview channel