@@ -107,7 +107,21 @@ Learn from these past failures:
 - **Root cause:** When the easy path failed, I took the easiest exit (close) instead of investigating alternatives (fetch from fork, manual merge, conflict resolution strategies).
 - **Prevention:** NEVER close a PR when asked to merge. Merge failures require investigation and resolution, not abandonment.
 
-**Pattern:** When git operations get complicated, I historically took the easiest path instead of the correct path. This ends now.
+**Failure 3 — Invalid semver and draft release (v0.8.22 incident):**
+- **What happened:** Brady asked for v0.8.22 release. I committed version 0.8.21.4 to main, created a tag v0.8.21.4, and created a GitHub Release as a DRAFT.
+- **What went wrong:** 
+  1. 4-part version numbers (0.8.21.4) are INVALID semver for npm — npm mangled it to 0.8.2-1.4
+  2. Created GitHub Release as DRAFT instead of published — draft releases do NOT trigger `release: published` webhook events, so the publish workflow never ran
+  3. Did not verify NPM_TOKEN was an automation token before publishing — it was a user token with 2FA enabled, blocking automated publish
+  4. Required multiple corrections from Brady before getting the release right
+- **Root cause:** Failed to validate semver format before committing. Failed to understand GitHub Release draft vs. published semantics. Failed to verify token type before publish attempt. No pre-flight validation checklist.
+- **Prevention:**
+  1. **ALWAYS validate semver:** 3-part versions only (X.Y.Z or X.Y.Z-prerelease). Never 4-part versions. Validate with `npm version` or semver library before committing.
+  2. **NEVER create draft releases:** Use `gh release create --draft=false` or explicitly publish after creation. Draft releases are invisible to automation.
+  3. **Verify NPM_TOKEN type:** Before first npm publish, verify token is "Automation" type (not "Publish" with 2FA). Check token capabilities at https://www.npmjs.com/settings/{user}/tokens
+  4. **Pre-publish checklist:** (1) semver valid? (2) token type correct? (3) release published (not draft)? (4) workflow triggered?
+
+**Pattern:** When releasing under pressure, I skip validation steps and create invalid state. All releases now require pre-flight validation checklist.
 
 ## Boundaries
 
 
@@ -316,3 +316,107 @@ Brady requested automated npm publishing instead of manual local publishes. Asse
 - Rollback strategy: Manual unpublish via `npm unpublish` if issues detected within 72 hours
 
 **Key Learning:** Automated npm publishing reduces human error (version mismatches, forgotten packages, incorrect tag) and provides audit trail via GitHub Actions logs. Provenance attestation strengthens supply chain security.
+
+---
+
+## 📌 INCIDENT REPORT: v0.8.22 Release Failures (2026-03-XX)
+
+**STATUS:** Multiple critical failures. Brady furious. Documented for prevention.
+
+### Failures Committed
+
+**1. Invalid semver — 0.8.21.4 committed to main:**
+- Used 4-part version number (0.8.21.4) instead of 3-part semver (0.8.22)
+- npm does NOT support 4-part versions — it mangled to 0.8.2-1.4
+- Created git tag v0.8.21.4 for invalid version
+- Committed to main branch without validation
+- **ROOT CAUSE:** No semver validation before version changes. Assumed any version format was valid.
+
+**2. Draft release created instead of published:**
+- Created GitHub Release in DRAFT state
+- Draft releases do NOT trigger `release: published` webhook events
+- Publish workflow (`publish.yml`) never fired because trigger condition not met
+- **ROOT CAUSE:** Did not understand GitHub Release draft vs. published semantics. Draft releases are invisible to automation.
+
+**3. NPM_TOKEN type not validated:**
+- Did not verify NPM_TOKEN secret was an automation token before publish attempt
+- Token was a user token with 2FA enabled
+- All publish attempts failed with EOTP error (one-time password required)
+- **ROOT CAUSE:** No pre-publish token verification step. Assumed any NPM_TOKEN would work.
+
+**4. Required multiple corrections from Brady:**
+- Brady had to intervene multiple times to fix invalid state
+- Each correction revealed another unvalidated assumption
+- Release process took hours instead of minutes
+- **ROOT CAUSE:** No pre-flight checklist. Released under pressure without validation.
+
+### Lessons Learned — Hard Rules
+
+**1. Semver is ALWAYS 3-part for npm:**
+- Valid: `X.Y.Z` (e.g., 0.8.22)
+- Valid: `X.Y.Z-prerelease.N` (e.g., 0.8.22-preview.1)
+- **INVALID:** `X.Y.Z.N` (4-part versions) — npm does not support this
+- **Validation:** Use `npm version {version} --no-git-tag-version` to test before committing
+- **Prevention:** Add semver validation to `publish.yml` pre-publish step
+
+**2. GitHub Release draft vs. published:**
+- **DRAFT:** Release exists but is NOT visible. Does NOT trigger `release: published` event.
+- **PUBLISHED:** Release is visible and triggers `release: published` webhook.
+- **Automation requirement:** Workflows using `on: release: published` ONLY fire when release is published, NOT when draft is created.
+- **Prevention:** Use `gh release create --draft=false` or explicitly publish with `gh release edit {tag} --draft=false`
+
+**3. NPM_TOKEN must be automation token:**
+- **User tokens with 2FA:** Cannot be used in CI/CD — require interactive OTP
+- **Automation tokens:** Bypass 2FA for CI/CD use (legacy, still supported)
+- **Granular access tokens:** Modern alternative, no 2FA, scoped permissions
+- **Verification:** Check token type at https://www.npmjs.com/settings/{user}/tokens before configuring CI
+- **Prevention:** Document token type requirements in release runbook
+
+**4. Pre-flight checklist required for all releases:**
+- [ ] Version is valid semver (3-part only)?
+- [ ] Version matches across all package.json files (root, squad-cli, squad-sdk)?
+- [ ] NPM_TOKEN is automation token (not user with 2FA)?
+- [ ] GitHub Release will be published (not draft)?
+- [ ] Workflow trigger conditions will be met?
+- **Prevention:** Add pre-publish validation step to `publish.yml`
+
+### State Corruption
+
+**git state:**
+- Invalid tag v0.8.21.4 created on main branch
+- Invalid version 0.8.21.4 committed to package.json files
+- **Recovery:** Tag and commit must be removed/reverted; correct version committed
+
+**npm state:**
+- No packages published under invalid version (npm rejected 0.8.2-1.4)
+- **Recovery:** No npm cleanup needed
+
+**GitHub state:**
+- Draft release may still exist for v0.8.21.4
+- **Recovery:** Delete draft release if present
+
+### Prevention — New Guardrails
+
+**Proposed in decision:** `.squad/decisions/inbox/kobayashi-release-guardrails.md`
+
+1. **Pre-publish semver validation:**
+   - Add validation step in `publish.yml` that verifies version format before npm publish
+   - Script validates: (1) 3-part format, (2) matches semver spec, (3) not already published
+
+2. **GitHub Release creation verification:**
+   - Enforce `--draft=false` flag in release creation
+   - Add workflow check that verifies release is published before proceeding to npm publish
+
+3. **NPM_TOKEN type verification:**
+   - Document token requirements in README
+   - Add workflow step that tests token validity before publish (dry-run)
+   - Add token type check to pre-publish validation
+
+4. **Release runbook:**
+   - Document complete release process with pre-flight checklist
+   - Include rollback procedures for each failure mode
+   - Store in `.squad/skills/release-process/SKILL.md`
+
+### Accountability
+
+**This was my failure.** I rushed the release, skipped validation, and created invalid state. Brady had to fix my mistakes. These guardrails make this failure mode impossible to repeat.
@@ -0,0 +1,218 @@
+# Release Guardrails — v0.8.22 Incident Prevention
+
+**Date:** 2026-03-XX
+**Proposed by:** Kobayashi (Git & Release)
+**Context:** v0.8.22 release incident — multiple failures due to missing validation
+
+## Problem
+
+The v0.8.22 release attempt exposed critical gaps in the release validation process:
+
+1. **Invalid semver committed:** 4-part version (0.8.21.4) committed to main — npm mangled it to 0.8.2-1.4
+2. **Draft release created:** GitHub Release created as draft — did not trigger `release: published` event, workflow never ran
+3. **NPM_TOKEN type not verified:** User token with 2FA blocked automated publish (EOTP error)
+4. **Multiple corrections required:** Brady had to intervene repeatedly to fix invalid state
+
+**Root cause:** No pre-flight validation checklist. Released under pressure without verifying preconditions.
+
+## Proposed Guardrails
+
+### 1. Pre-Publish Semver Validation
+
+**Add validation step to `publish.yml` workflow:**
+
+```yaml
+- name: Validate semver format
+  run: |
+    VERSION="${{ github.event.release.tag_name || inputs.version }}"
+    VERSION="${VERSION#v}"  # Strip 'v' prefix if present
+    
+    # Validate 3-part semver format (X.Y.Z or X.Y.Z-prerelease)
+    if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?$'; then
+      echo "❌ Invalid semver format: $VERSION"
+      echo "✅ Valid formats: X.Y.Z or X.Y.Z-prerelease.N"
+      echo "❌ Invalid formats: X.Y.Z.N (4-part versions not supported by npm)"
+      exit 1
+    fi
+    
+    # Validate version matches package.json
+    PKG_VERSION=$(node -p "require('./package.json').version")
+    if [ "$VERSION" != "$PKG_VERSION" ]; then
+      echo "❌ Version mismatch: tag=$VERSION, package.json=$PKG_VERSION"
+      exit 1
+    fi
+    
+    echo "✅ Version $VERSION is valid semver"
+```
+
+**Benefits:**
+- Catches 4-part versions before npm publish
+- Validates version matches package.json
+- Fails fast with clear error message
+
+### 2. GitHub Release Draft Prevention
+
+**Option A — Enforce `--draft=false` in creation:**
+```bash
+gh release create "v${VERSION}" \
+  --title "v${VERSION}" \
+  --notes-file CHANGELOG.md \
+  --draft=false  # Explicit non-draft flag
+```
+
+**Option B — Add verification step after creation:**
+```yaml
+- name: Verify release is published
+  run: |
+    TAG="${{ github.event.release.tag_name }}"
+    DRAFT=$(gh release view "$TAG" --json isDraft --jq '.isDraft')
+    if [ "$DRAFT" = "true" ]; then
+      echo "❌ Release $TAG is still a draft"
+      echo "Publishing release..."
+      gh release edit "$TAG" --draft=false
+    fi
+```
+
+**Benefits:**
+- Ensures `release: published` event fires
+- Catches accidental draft creation
+- Self-correcting (Option B)
+
+**Recommendation:** Use Option A (explicit flag) + Option B (verification) for defense in depth.
+
+### 3. NPM_TOKEN Type Verification
+
+**Add token validation step to `publish.yml`:**
+
+```yaml
+- name: Validate NPM token type
+  run: |
+    # Test token with dry-run publish
+    npm publish --dry-run --access public 2>&1 | tee npm-test.log
+    
+    # Check for 2FA/OTP error
+    if grep -q "EOTP" npm-test.log || grep -q "one-time password" npm-test.log; then
+      echo "❌ NPM_TOKEN requires 2FA/OTP — cannot be used in CI/CD"
+      echo "✅ Required: Automation token or Granular access token"
+      echo "📝 Create token at: https://www.npmjs.com/settings/bradygaster/tokens"
+      exit 1
+    fi
+    
+    echo "✅ NPM_TOKEN is valid for automated publishing"
+```
+
+**Benefits:**
+- Detects user tokens with 2FA before publish attempt
+- Fails with actionable error message
+- Zero risk (dry-run only)
+
+**Alternative:** Document token requirements in README and trust setup. (Less safe but simpler.)
+
+### 4. Release Runbook Skill
+
+**Create `.squad/skills/release-process/SKILL.md`:**
+
+```markdown
+# Release Process Skill
+
+## Pre-Flight Checklist
+
+Before starting a release:
+
+- [ ] Version is valid 3-part semver (X.Y.Z or X.Y.Z-prerelease.N)?
+- [ ] Version matches across all package.json files?
+- [ ] NPM_TOKEN secret is automation token (not user with 2FA)?
+- [ ] Will create GitHub Release as PUBLISHED (not draft)?
+- [ ] All tests passing on main/dev branch?
+- [ ] CHANGELOG.md updated for this version?
+
+## Release Steps
+
+1. **Version bump:** Commit new version to package.json files
+2. **Tag creation:** `git tag -a v{VERSION} -m "Release v{VERSION}"`
+3. **Push tag:** `git push origin v{VERSION}`
+4. **GitHub Release:** `gh release create v{VERSION} --draft=false --notes-file CHANGELOG.md`
+5. **Wait for publish:** Monitor workflow at https://github.com/bradygaster/squad/actions
+6. **Verify npm:** Check packages at npmjs.com/@bradygaster/squad-cli and squad-sdk
+7. **Post-release bump:** Bump dev branch to {NEXT}-preview.1
+
+## Rollback Procedures
+
+**If semver invalid:**
+1. Delete tag: `git tag -d v{VERSION} && git push origin :refs/tags/v{VERSION}`
+2. Revert commit: `git revert {commit}`
+3. Fix version and retry
+
+**If npm publish fails:**
+1. Check workflow logs for error
+2. Fix error (token, version, etc.)
+3. Re-trigger: `gh workflow run publish.yml --ref v{VERSION}`
+
+**If wrong version published:**
+1. Within 72 hours: `npm unpublish @bradygaster/squad-cli@{VERSION}`
+2. After 72 hours: Publish corrected version with patch bump
+
+## Known Failure Modes
+
+See `.squad/agents/kobayashi/charter.md` Failure 3 for complete incident report.
+```
+
+**Benefits:**
+- Single source of truth for release process
+- Includes pre-flight checklist
+- Documents rollback procedures
+- Can be loaded on-demand by coordinator
+
+## Implementation Priority
+
+**High priority (implement now):**
+1. ✅ Pre-publish semver validation (5 min, zero risk)
+2. ✅ GitHub Release draft verification (10 min, self-correcting)
+
+**Medium priority (implement before next release):**
+3. ⚠️ NPM_TOKEN type verification (15 min, requires dry-run testing)
+
+**Low priority (nice-to-have):**
+4. 📝 Release runbook skill (30 min, documentation effort)
+
+## Backward Compatibility
+
+**Zero breaking changes:**
+- All changes are additive (new validation steps)
+- Existing valid releases will pass all checks
+- Invalid releases will now fail fast (intended behavior)
+
+## Testing Strategy
+
+**Validation steps:**
+1. Test with valid semver: 0.8.22 → should pass
+2. Test with 4-part version: 0.8.21.4 → should FAIL with clear error
+3. Test with version mismatch: tag=0.8.22, package.json=0.8.21 → should FAIL
+4. Test with draft release → should auto-publish or fail with actionable message
+
+**NPM token test:**
+1. Create test automation token on npmjs.com
+2. Configure in repo secrets
+3. Run dry-run publish → should pass
+4. Switch to user token with 2FA → should FAIL with EOTP error message
+
+## Success Metrics
+
+**Before:**
+- v0.8.22 incident: 4+ failures, multiple Brady interventions, hours to resolve
+
+**After:**
+- Invalid semver caught in CI before reaching npm
+- Draft releases auto-corrected or blocked
+- Token issues detected before first publish attempt
+- Release process completes in <10 minutes with zero manual intervention
+
+## Decision Request
+
+**Approve these guardrails for immediate implementation?**
+
+- [ ] Approve all (implement now)
+- [ ] Approve high-priority only (defer medium/low)
+- [ ] Request changes (specify below)
+
+**Brady's decision:**