feat(release): formalize OSS release infrastructure + bstack CLI dispatcher (0.2.2)

[broomva]

Summary

Foundation PR for the 0.2.x → 0.3.0 series. Establishes proper OSS release tooling, a top-level bstack CLI dispatcher, and switches the update-check transport to the GitHub Releases API.

• Release docs: CONTRIBUTING.md (branch/PR shape, primitive-promotion rule, local validation) + RELEASE.md (semver policy for pre-1.0, release checklist via bstack release tag, retroactive-tag history, transport docs).
• CI workflows: .github/workflows/ci.yml (shellcheck + jq + bstack doctor lint) + .github/workflows/validate-release.yml (PR gate: VERSION ↔ CHANGELOG match, version monotonicity).
• CLI dispatcher: bin/bstack — top-level subcommand router (doctor, validate, repair, bootstrap, onboard, revamp, upgrade, config, update-check, wave, release tag, version). Existing sub-binaries remain callable directly — the dispatcher is additive.
• Update-check transport (bin/bstack-update-check): primary source is now GET /repos/broomva/bstack/releases/latest. Raw VERSION on main is the fallback. Dev-branch VERSION bumps no longer leak as available upgrades to downstream installs — only tagged releases do.
• Retroactive history: tagged v0.2.0 (322ba23) and v0.2.1 (9170dd3) + matching GitHub Releases pushed 2026-05-18.
• bstack release tag wraps the post-merge sequence: validates clean tree on main, reads VERSION, picks the matching ## X.Y.Z section out of CHANGELOG.md as release notes, tags + pushes + gh release create.

Why now

bstack had zero git tags, zero GitHub Releases, no CI, and no contribution/release docs. This blocks proper semver discipline and prevents downstream installs from discovering updates reliably. Without this foundation, the planned 0.2.3 (bstack repair merges hooks) and 0.3.0 (SessionStart auto-upgrade) wouldn't be properly tagged or releaseable.

Stack

This PR is PR 1 of 3 in the release-infra → repair-merges-hooks → SessionStart-auto-upgrade series:

1. 0.2.2 (this PR) — release infrastructure + CLI dispatcher
2. 0.2.3 (feat/repair-merge-hooks) — bstack repair idempotently merges missing hooks (closes the chicken-and-egg where 0.3.0's new SessionStart hook wouldn't reach existing installs)
3. 0.3.0 (feat/session-start-autoupdate) — SessionStart auto-upgrade hook + auto_upgrade=true default

Validation

• shellcheck --severity=warning --exclude=SC1091,SC2155 bin/* scripts/*.sh — clean
• jq -e . assets/templates/*.snippet — all valid
• bin/bstack --help — renders correctly
• Manual: pointed BSTACK_RELEASES_URL at the new releases endpoint, confirmed bstack update-check emits UP_TO_DATE 0.2.2 once tag lands

Test plan

• CI green (ci.yml + validate-release.yml)
• Reviewer confirms VERSION 0.2.2 + matching CHANGELOG section
• After merge: bstack release tag produces the v0.2.2 release

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added a unified bstack CLI dispatcher with integrated upgrade and release management capabilities.
  • Enhanced update-check mechanism to use GitHub Releases API as the primary source, with fallback support.

• Documentation

  • Added comprehensive contribution guide with branching, commit, and validation standards.
  • Added release process documentation including versioning rules and checklist.
  • Updated changelog for version 0.2.2 release.

• Chores

  • Added GitHub Actions workflows for CI linting and release validation.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 030988cf-9354-417d-ba93-f837d5ce29b0

📥 Commits

Reviewing files that changed from the base of the PR and between 82b6a9c and adf8f13.

📒 Files selected for processing (8)

• .github/workflows/ci.yml
• .github/workflows/validate-release.yml
• CHANGELOG.md
• CONTRIBUTING.md
• RELEASE.md
• VERSION
• bin/bstack
• bin/bstack-update-check

---

📝 Walkthrough

Walkthrough

This PR establishes a complete release infrastructure: new version bump to 0.2.2, automated validation workflows for version progression and changelog entries, a new bstack CLI dispatcher routing subcommands, GitHub Actions CI for linting and validation, GitHub Releases API integration for update detection, and comprehensive contribution and release documentation.

Changes

Release Infrastructure and CLI Dispatcher

Layer / File(s)	Summary
Release validation and versioning VERSION, CHANGELOG.md, .github/workflows/validate-release.yml	Version is incremented from 0.2.1 to 0.2.2, changelog documents new CLI/release tooling and update-check transport changes, and a new workflow enforces semver format and version progression on pull requests.
CI linting and validation workflow .github/workflows/ci.yml	New GitHub Actions workflow runs on push to main and pull requests, lint job detects and validates shell scripts via ShellCheck and JSON template snippets via jq, and doctor job stages templated fixtures and executes validation script.
CLI dispatcher and core commands bin/bstack	New entrypoint routes subcommands to co-located scripts and binaries; implements bstack upgrade flow with git stash/fetch/reset and vendored-install fallback; implements bstack release tag flow with git state validation, CHANGELOG extraction, tag creation, and optional GitHub Release via gh.
Update-check GitHub Releases API integration bin/bstack-update-check	Update-check now queries GitHub Releases latest API as primary version source via overridable BSTACK_RELEASES_URL, parses tag_name with jq or grep fallback, validates against semver pattern, and falls back to raw VERSION endpoint when parsing fails.
Contribution and release documentation CONTRIBUTING.md, RELEASE.md	Full contribution guide covering branch/PR conventions, commit standards, and procedures for adding primitives and skills; release guide defines pre-1.0 SemVer convention, release checklist tied to validation workflow, tagging/GitHub Release procedure, retroactive tag history, and update-check transport strategy.

Sequence Diagram

sequenceDiagram
  participant Developer
  participant bstack as bin/bstack
  participant UpdateCheck as bin/bstack-update-check
  participant Git
  participant GitHub as GitHub API
  participant User
  Developer->>bstack: bstack release tag
  bstack->>Git: validate clean main
  bstack->>Git: verify main matches origin/main
  bstack->>GitHub: create annotated tag
  bstack->>GitHub: create GitHub Release
  User->>bstack: bstack upgrade
  bstack->>UpdateCheck: bstack-update-check --force
  UpdateCheck->>GitHub: query Releases API
  GitHub-->>UpdateCheck: tag_name
  UpdateCheck->>Git: stash/fetch/reset

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• broomva/bstack#4: Adds governance template files (CLAUDE.md, AGENTS.md, .control/policy.yaml) from assets/templates/*.template that are staged and validated by the new doctor CI job.

Poem

🐰 A CLI dispatcher hops into place,
With GitHub Releases set at a faster pace,
Version checks dance in the CI embrace,
Release tags leap with grace and with space,
bstack now bounces through workflows with ease! 🐇

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/release-infra

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}