Release & CI/CD Hardening Plan for v0.5.0 #62

Summary

Comprehensive CI/CD audit and release hardening plan for v0.5.0. All workflows reviewed, gaps identified, release checklist proposed. This is a planning issue — no code changes yet.

🔍 Full Audit Findings

✅ What's Solid

1. 10 workflows deployed and mirrored

   • .github/workflows/ ↔ templates/workflows/ — verified byte-perfect mirrors
   • All 10 workflows: ci, docs, heartbeat, issue-assign, label-enforce, main-guard, preview, release, triage, sync-labels

2. Guard workflow is robust

   • squad-main-guard.yml blocks .ai-team/** and team-docs/** from main/preview
   • Pagination support (handles PRs with >100 files)
   • Actionable error messages with fix commands
   • Allows removals (deleting forbidden files is fine)

3. Test suite coverage

   • 45 passing tests (mcp-config, plugin-marketplace, workflows)
   • Tests validate workflow template mirroring
   • State integrity validated (upgrade doesn't corrupt .ai-team/)

4. Release workflow is idempotent

   • squad-release.yml checks for existing tags before creating
   • Prevents duplicate releases
   • Uses gh CLI for GitHub Release creation (no PAT needed)

5. Documentation deployment is independent

   • squad-docs.yml has manual trigger (workflow_dispatch)
   • Deploys from preview branch when docs/** changes
   • Brady's requirement met: docs can be updated without cutting a release

6. Team workflows are isolated

   • 6 team workflows (heartbeat, triage, issue-assign, label-enforce, sync-labels) don't depend on releases
   • Read .ai-team/team.md which is excluded from main/preview by guard
   • No risk of state corruption during release

7. Three-layer state protection

   • .gitignore excludes .ai-team/ locally
   • package.json files array excludes .ai-team/ from distribution
   • squad-main-guard.yml blocks .ai-team/ PRs to main/preview

⚠️ Gaps and Risks

1. No formal release checklist

• Gap: Process documented in docs/scenarios/release-process.md but no step-by-step checklist with STOP gates
• Risk: Human error during releases (wrong version, missing CHANGELOG entry, skipped validation)
• Impact: Medium — increases likelihood of botched releases

2. No patch release workflow

• Gap: Bug fixes (0.4.1, 0.4.2) require manual process
• Risk: Patch releases bypass CI validation
• Impact: Medium — hotfixes could ship without proper testing

3. Version field in package.json is stale

• Current: 0.4.0 in package.json
• CHANGELOG.md: Documents features for future releases (0.4.0 already shipped per history.md)
• Risk: Could ship next release with wrong version number
• Impact: High — version mismatch would break npx github:bradygaster/squad#v{version} pinning

4. No CI validation of version consistency

• Gap: CI doesn't check that package.json version matches CHANGELOG.md
• Risk: Could tag v0.5.0 but ship 0.4.0 in package.json
• Impact: High — users would get wrong version

5. No automated preview→main workflow

• Gap: Human must manually merge preview to main after validation
• Risk: Merge conflicts, human forgets to merge, manual errors
• Impact: Low — manual merge is safer until process is battle-tested

6. Branch protection rules not documented

• Gap: Workflows enforce constraints but repo settings are opaque
• Risk: Someone with admin access could push directly to main, bypassing guard
• Impact: Medium — direct pushes could corrupt state

7. Guard only runs on PRs, not direct pushes

• Gap: If branch protection rules aren't set, direct push to main bypasses guard
• Risk: Admin could accidentally push .ai-team/ directly to main
• Impact: Medium — would corrupt distribution

📋 Proposed Release Checklist

Create docs/release-checklist.md with three release types:

Patch Release (0.4.1)

When: Bug fixes only, no new features

Human steps:

1. ✋ STOP: Verify only bug fixes in this release (no "Added" or "Changed" in CHANGELOG.md)
2. Update CHANGELOG.md with ## [0.4.X] — YYYY-MM-DD and "### Fixed" section
3. Update version in package.json to 0.4.X
4. Commit to dev: git commit -m "chore: prepare patch release v0.4.X"
5. Push to dev: git push origin dev
6. Run tests on dev: gh workflow run squad-ci.yml --ref dev
7. ✋ STOP: Verify CI passes
8. Checkout main: git checkout main && git pull origin main
9. Cherry-pick commit: git cherry-pick <commit-sha> OR merge: git merge --no-ff dev
10. Push to main: git push origin main
11. ✋ STOP: Verify release workflow succeeds
12. Tag release: git tag -a v0.4.X -m "Release v0.4.X: <summary>"
13. Push tag: git push origin v0.4.X
14. ✋ STOP: Verify GitHub Release created

Kobayashi MUST refuse if:

• CHANGELOG.md has "Added" or "Changed" sections (not a patch)
• Version in package.json doesn't match tag
• Tests fail on dev or main

Minor Release (0.5.0)

When: New features, breaking changes OK before v1

Human steps:

1. ✋ STOP: Verify features documented in CHANGELOG.md under "### Added" or "### Changed"
2. Update CHANGELOG.md with ## [0.5.0] — YYYY-MM-DD
3. Update version in package.json to 0.5.0
4. Commit to dev: git commit -m "chore: prepare release v0.5.0"
5. Push to dev: git push origin dev
6. Run tests on dev: gh workflow run squad-ci.yml --ref dev
7. ✋ STOP: Verify CI passes on dev
8. Create preview branch: git checkout -b release/preview OR reset existing: git checkout release/preview && git reset --hard dev
9. Remove forbidden files: git rm --cached -r .ai-team/ 2>/dev/null; git rm --cached -r team-docs/ 2>/dev/null
10. Commit removal: git commit -m "chore: remove forbidden paths for preview" 2>/dev/null (OK if nothing to remove)
11. Push preview: git push -f origin release/preview
12. ✋ STOP: Verify guard workflow passes on preview branch
13. ✋ STOP: Verify preview validation workflow passes
14. Create PR to main: gh pr create --base main --head release/preview --title "Release v0.5.0" --body "Full release. Guard enforces file restrictions."
15. ✋ STOP: Human reviews PR and approves
16. Merge PR to main: gh pr merge --merge --auto
17. ✋ STOP: Verify release workflow succeeds (auto-creates tag and GitHub Release)
18. Sync back to dev: git checkout dev && git merge main --no-ff && git push origin dev

Kobayashi MUST refuse if:

• Version in package.json doesn't match intended release
• CHANGELOG.md doesn't have entry for this version
• Guard workflow fails on preview
• Tests fail on preview
• Human hasn't confirmed "go for release"

Major Release (1.0.0)

When: Breaking changes after v1, or first stable release

Human steps:

1. All steps from Minor Release above
2. ✋ STOP: Verify CHANGELOG.md has "### Breaking Changes" section if applicable
3. ✋ STOP: Verify migration guide exists if breaking changes present
4. Post community announcement (Discussions, blog post, social)

Kobayashi MUST refuse if:

• Any Minor Release STOP gate fails
• Breaking changes documented but no migration guide exists

🔧 Proposed Changes

Priority 0 (block v0.5.0)

1. Create release checklist

• Create docs/release-checklist.md with content above
• Link from docs/scenarios/release-process.md

2. Fix package.json version field

• Immediate action: Set to next planned version (0.5.0 or 0.4.1)
• Question for Brady: What's the next release number?

3. Add version validation to CI

• Add step to squad-preview.yml:

- name: Validate version consistency
  run: |
    VERSION=$(node -e "console.log(require('./package.json').version)")
    CHANGELOG_VERSION=$(grep -m1 "## \[$VERSION\]" CHANGELOG.md || echo "")
    if [ -z "$CHANGELOG_VERSION" ]; then
      echo "::error::Version $VERSION not found in CHANGELOG.md"
      exit 1
    fi
    echo "✅ Version $VERSION validated in CHANGELOG.md"

• Add same step to squad-release.yml before creating tag

Priority 1 (ship with v0.5.0)

4. Document branch protection rules

Add section to docs/scenarios/release-process.md:

Required branch protection settings:

• main:

  • ✅ Require pull request before merging (1 approval)
  • ✅ Require status checks to pass: Squad CI, Squad Protected Branch Guard
  • ✅ Require branches to be up to date
  • ❌ Do not allow force pushes
  • ❌ Do not allow deletions

• preview:

  • ✅ Require status checks to pass: Squad Protected Branch Guard, Squad Preview Validation
  • ✅ Require branches to be up to date
  • ❌ Do not allow force pushes
  • ❌ Do not allow deletions

• dev:

  • No restrictions (team works freely)

5. Create patch release workflow

Option A: Add input to existing squad-release.yml:

on:
  push:
    branches: [main]
  workflow_dispatch:
    inputs:
      release_type:
        description: 'Release type'
        required: true
        default: 'minor'
        type: choice
        options:
          - patch
          - minor
          - major

Option B: Create separate squad-patch-release.yml (cleaner separation)

Validation in patch workflow:

• Check CHANGELOG.md has "### Fixed" section for this version
• Check CHANGELOG.md has NO "### Added" or "### Changed" sections
• Fail if features detected in patch release

Priority 2 (future)

6. Automated preview→main merge

• Add workflow_dispatch input to squad-release.yml to trigger preview→main merge
• Requires human approval via GitHub UI (button click, not CLI)

7. Version auto-increment

• Add CLI subcommand: squad version bump patch|minor|major
• Updates package.json, creates CHANGELOG.md entry stub
• Commits changes to dev

❓ Questions for Community

1. Patch release strategy: Should hotfixes branch off main (hotfix/0.4.1) or always come from latest dev?

   • Option A (safer): Hotfix branches off main, cherry-picked back to dev
   • Option B (simpler): Always patch from dev, merge to main

2. Preview branch lifespan: Should preview be deleted after merge to main, or kept as permanent staging?

   • Option A (cleaner): Delete after merge, recreate for next release
   • Option B (persistent): Keep as permanent staging branch

3. Automated merge: Should release workflow auto-merge preview→main after guard passes, or require human approval?

   • Option A (faster): Auto-merge if guard + CI pass
   • Option B (safer): Human must approve PR

4. Version bumping: Should Kobayashi auto-increment version in package.json during release, or require human to update beforehand?

   • Option A (automated): Workflow reads current version, increments, commits
   • Option B (manual): Human updates package.json before triggering release

5. Release notes: Should GitHub Release notes be auto-generated (--generate-notes) or pulled from CHANGELOG.md?

   • Current: Auto-generated
   • Option B: Parse CHANGELOG.md and use that version's content

6. Branch protection enforcement: Should we add a CI check that verifies branch protection rules are set correctly?

   • Why: Prevents admin from accidentally disabling protections

🎯 Risk Assessment

📦 Implementation Plan

Phase 1 (before v0.5.0):

1. Create release checklist document
2. Fix package.json version
3. Add version validation to preview and release workflows

Phase 2 (ship with v0.5.0):

1. Document branch protection rules
2. Create patch release workflow
3. Test entire release process with v0.5.0

Phase 3 (v0.6.0+):

1. Automated preview→main merge
2. Version auto-increment CLI command
3. CHANGELOG.md parsing for release notes

🚀 Next Steps

1. Community discussion on questions above
2. Brady approval on priority and scope
3. Implementation by Kobayashi (or delegate to squad)
4. Test run with v0.5.0 release

Filed by: Kobayashi (Git & Release Engineer)
Filed on: 2026-02-15
Status: Awaiting community feedback

cc @bradygaster