feat(upgrade,canary): Phase 6 — vendored upgrade + canary suite (0.9.0)#37
Merged
Conversation
Implements §6 Phase 6 of substrate completion spec (BRO-1158 under
epic BRO-1148). Closes two v1.0 blockers: §4.3.2 (vendored installs
can't auto-upgrade) and §4.6.2 (no canary suite verifying substrate
invariants on fresh installs).
# Vendored upgrade path
bstack upgrade for installs without .git (the npx skills add path)
now downloads a release tarball + sha256, verifies, and atomically
swaps into ~/.agents/skills/bstack.
bin/bstack: new bstack_upgrade_vendored function
1. curl bstack-vX.Y.Z.tar.gz + .sha256 from GitHub Release
2. Verify sha256 (mandatory — no --skip flag, fail-closed)
3. tar -xzf into temp dir
4. mv current → .bak, mv new → install (atomic swap)
5. Restore .bak on swap failure
6. Write ~/.bstack/just-upgraded-from for JUST_UPGRADED next session
7. Structured log at ~/.bstack/auto-upgrade.log
.github/workflows/release.yml: new packaging step
- Builds bstack-vX.Y.Z.tar.gz from in-repo skill payload
- Excludes .git, .github, tests, worktree dirs
- tar --sort=name for byte-deterministic sha256
- Uploads tarball + sha256 sidecar via gh release upload
Falls back to manual 'npx skills add -g broomva/bstack' guidance if
the tarball is missing (pre-0.9.0 releases without the new job).
# Canary suite
Four canary tests verify load-bearing substrate contracts on a fresh
install (no companion skills, no workspace state, no prior bstack
state). Each canary covers one phase's deliverables:
tests/canary/01-fresh-bootstrap.test.sh (Plant Contract)
- bootstrap.sh exits 0
- governance files scaffold (CLAUDE, AGENTS, .control/policy.yaml)
- .claude/settings.json wires SessionStart + Stop + PreToolUse
- doctor produces expected summary + exits 0 (HC-1: never block)
(10 assertions)
tests/canary/02-metrics-pipeline.test.sh (Phase 1 v0.4.0)
- collect produces valid JSON with ≥4 setpoints
- latest.json on disk with generated_at timestamp
- observe single setpoint returns id-matched JSON
(3 assertions)
tests/canary/03-status-surface.test.sh (Phase 2 v0.5.0)
- 7 core sections render in text mode
- --json shape: bstack_version + workspace + profile + setpoints + summary
- --setpoint S11 --json returns id-matched deep view
- --aggregate exits 3 (Phase 8 placeholder)
(4 assertions)
tests/canary/04-schemas-validate.test.sh (Phase 3 v0.6.0)
- 4 schemas valid draft-07
- primitives.yaml validates against primitives.v1.json (20 entries)
- companion-skills.yaml validates against companion-skills.v1.json (31)
- policy.yaml.template structural shape + flat-schema parts valid
(4 assertions)
Total: 21 assertions across 4 canary tests, ~5s combined runtime.
.github/workflows/ci.yml: new 'canary' job gated on lint + doctor;
installs jq + jsonschema + PyYAML; runs tests/canary/*.test.sh.
# Out of scope (deferred to v0.9.1)
- Cosign signature verification (sha256 covers principal integrity;
cosign adds publisher identity proof — staged for v0.9.1)
- bstack reproduce subcommand (drift detection vs fresh-install ref)
- Canary tests 05-08 (skills install, gates audit, release pipeline E2E)
— ship as Phase 4-6 deliverables stabilize further
# Validation
Local lint: shellcheck OK (bin/bstack + 4 canaries)
Local canary suite: 21/21 assertions pass
Tarball packaging: tested via dry-run path; CI publishes on next bump
# SLO targets (introduced)
bstack upgrade --self (vendored, cold network): p50 < 30s, p99 < 60s
Canary suite (4 tests, sequential): p99 < 30s
Linear: BRO-1158 (Phase 6, parent epic BRO-1148).
Spec: §6 Phase 6 of specs/2026-05-18-substrate-completion.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (10)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
The original portable T1 fix (PR #36 commit a2bd9b9) was orphaned in the v0.8.0 squash merge — same race condition that lost the v0.2.2 SC2034 exclude. CI's Ubuntu strips '# ' from --help via GNU sed; macOS keeps it via BSD sed. The grep '^# Usage:' anchor passes locally and fails in CI. Asserting the un-prefixed 'Usage:' token works on both. Including in Phase 6 PR since CI was blocking on it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 6 of substrate completion (BRO-1158 under epic BRO-1148). Closes two v1.0 blockers: §4.3.2 (vendored installs can't auto-upgrade) and §4.6.2 (no canary suite verifying substrate invariants on fresh installs).
Vendored upgrade path
bstack upgrade --selffor installs without.git(thenpx skills addpath) now downloads a release tarball + sha256, verifies, and atomically swaps into~/.agents/skills/bstack.curl bstack-vX.Y.Z.tar.gz+.sha256from GitHub Release--skip-sha256flag (fail-closed)tar -xzfinto temp dirmv current → .bak,mv new → install(atomic swap).bakon swap failure~/.bstack/just-upgraded-fromforJUST_UPGRADEDnext session~/.bstack/auto-upgrade.logTarball publishing is a new step in
release.yml(built from in-repo skill payload, excludes.git/.github/tests/worktree dirs,tar --sort=namefor byte-deterministic sha256, uploads viagh release upload --clobber).BSTACK_DRY_RUN=1env override prints the upgrade plan without writing. Falls back to manualnpx skills addguidance if the tarball is missing (pre-0.9.0 releases).Canary suite
Four canary tests verify load-bearing substrate contracts on a fresh install. 21 assertions total, ~5s combined runtime.
01-fresh-bootstrap02-metrics-pipeline03-status-surface04-schemas-validate.github/workflows/ci.ymlgains a newcanaryjob (gated onlint+doctor), installs jq + jsonschema + PyYAML, runstests/canary/*.test.sh.Files
bin/bstack(+ ~110 LOC) —bstack_upgrade_vendoredfunction.github/workflows/release.yml— packaging + tarball upload step.github/workflows/ci.yml— newcanaryjobtests/canary/01-fresh-bootstrap.test.shtests/canary/02-metrics-pipeline.test.shtests/canary/03-status-surface.test.shtests/canary/04-schemas-validate.test.shVERSION→0.9.0CHANGELOG.mdLocal validation (all green)
Out of scope (deferred to v0.9.1)
bstack reproducesubcommand — drift detection vs fresh-install reference (Phase 6.1)SLO targets (introduced)
bstack upgrade --self(vendored, cold network): p50 < 30s, p99 < 60sSelf-validation note
This release's
release.ymljob will be the first to publish the tarball + sha256 for v0.9.0. After merge, downstream vendored installs runningbstack upgrade --selfagainst v0.9.0 will exercise the full path end-to-end. Future v0.9.1+ releases use the same machinery.Stack position
PR 10 of N in substrate completion arc. Spec: §6 Phase 6.
🤖 Generated with Claude Code