Document Homebrew bottle release process

.ai-context/STATUS.md

@@ -2,7 +2,7 @@
 
 ## Current Release
 
-Base `0.4.2` is the current published release. The repo-root `VERSION` file is
+Base `0.4.4` is the current published release. The repo-root `VERSION` file is
 updated only during release-prep PRs, not on every ordinary PR.
 
 ## Current Implemented Areas
@@ -27,9 +27,9 @@ The current command surface covers:
 
 ## Active Development Direction
 
-Current pre-1.0 work is tracked toward `v1.0.0`. The `0.4.2` patch release
-improves Bash startup recovery guidance when an existing shell still has a
-stale readonly `BASE_HOME` after a Homebrew upgrade.
+Current pre-1.0 work is tracked toward `v1.0.0`. The Homebrew upgrade contract
+remains open until supported macOS releases publish bottles and the bottled
+upgrade path passes the #526 rehearsal.
 
 Recent released work includes:
 
@@ -45,6 +45,8 @@ Recent released work includes:
 - Homebrew upgrade path preservation for explicit `BASE_HOME` and shell startup
   snippets
 - stale readonly `BASE_HOME` recovery guidance after Homebrew upgrades
+- Homebrew `basectl update` handoff and package-aware `basectl test base`
+- Base `0.4.4` release artifacts and Homebrew tap update
 
 ## Recent Merged Changes
 

.ai-context/WORKFLOWS.md

@@ -86,6 +86,10 @@ The `basectl release check|plan|notes` commands are read-only inspection
 commands. `basectl release publish` is guarded and creates the annotated tag and
 GitHub Release after checks pass. The Homebrew tap update happens in
 `codeforester/homebrew-base` after the Base tag and GitHub Release exist.
+Supported macOS tap releases should publish Homebrew bottles before the tap PR
+is merged: run the tap's `Build Base Bottles` workflow from the tap release
+branch, let it upload bottle assets to the tap release `base-vX.Y.Z`, and commit
+the generated `bottle do` stanza back to `Formula/base.rb`.
 
 ## AI Context Maintenance
 

CHANGELOG.md

@@ -7,6 +7,11 @@ and Base versions are tracked in the repo-root `VERSION` file.
 
 ## [Unreleased]
 
+### Changed
+
+- Updated the Homebrew release process to require bottle publishing for
+  supported macOS installs before accepting the 1.0 upgrade rehearsal.
+
 ## [0.4.4] - 2026-06-12
 
 ### Added

docs/homebrew-upgrade-rehearsal.md

@@ -24,6 +24,10 @@ upgrade without losing local Base state.
   brew doctor
   brew info codeforester/base/base
   ```
+- Confirm the target formula has bottles for the host or that
+  `brew install --force-bottle codeforester/base/base` succeeds on an equivalent
+  clean install. The release checklist owns bottle creation; this rehearsal
+  should prove an existing user can upgrade through that bottled formula path.
 
 Do not accept the rehearsal if Homebrew cannot install or upgrade packages on
 the host. Fix the host prerequisite first, then rerun the rehearsal.
@@ -105,6 +109,9 @@ shasum -a 256 "$TEST_ROOT/home/.base.d/config.yaml"
 Accept the rehearsal only when:
 
 - `brew upgrade codeforester/base/base` exits zero.
+- The upgrade uses a Homebrew bottle on supported macOS hosts, not a normal
+  source build. If Homebrew falls back to source, record why before accepting
+  the rehearsal.
 - The `~/.base.d/config.yaml` checksum is unchanged.
 - The Base virtual environment still exists and `basectl check` accepts it.
 - Fresh Bash and Zsh login shells resolve `basectl` to the Homebrew install.
@@ -216,3 +223,36 @@ Expected fixed behavior:
   Homebrew install path.
 - Fresh Bash and Zsh login shells no longer depend on a versioned Cellar path
   that `brew cleanup` can remove during the next upgrade.
+
+## 2026-06-12 Run Record
+
+Issue: #526, with bottle follow-up #608.
+
+Result: upgrade reached formula fetch and verification, then failed before Base
+install logic ran while Homebrew prepared its non-interactive source-build
+sandbox.
+
+Observed result:
+
+- `brew upgrade codeforester/base/base` attempted to upgrade Base from `0.4.3`
+  to `0.4.4`.
+- Homebrew fetched and verified the `0.4.4` formula archive.
+- Homebrew then failed in `Sandbox#path_filter` while denying reads under the
+  user's home directory:
+
+  ```text
+  Error: Invalid character '(' in path: /Users/sudha/Library/Logs/Skype Helper (Renderer)
+  /usr/local/Homebrew/Library/Homebrew/sandbox.rb:414:in `Sandbox#path_filter`
+  /usr/local/Homebrew/Library/Homebrew/formula_installer.rb:1145:in `FormulaInstaller#build`
+  ```
+
+- Removing that one directory exposed the same failure on another home-directory
+  path containing parentheses.
+
+Interpretation:
+
+This is not a single user cleanup issue. The failure happens before Base's
+formula install logic runs, so Base cannot recover inside the install step. The
+durable Base-side fix is to publish Homebrew bottles for supported macOS hosts
+so normal installs and upgrades do not depend on Homebrew's source-build
+sandbox. Track that release-process fix in #608 before accepting #526.

docs/release-process.md

@@ -13,12 +13,13 @@ The release spans two repositories:
 - `codeforester/base` owns Base source, release notes, `VERSION`, Git tags, and
   GitHub Releases.
 - `codeforester/homebrew-base` owns the Homebrew formula that installs published
-  Base releases.
+  Base releases, plus the Homebrew bottle artifacts for supported macOS hosts.
 
 The Homebrew tap update happens after the Base tag and GitHub Release exist.
 The formula points at a versioned tag archive and records that archive's
 `sha256`, so the archive must be available before the formula can be updated and
-validated.
+validated. Supported macOS installs should use Homebrew bottles; source builds
+remain a fallback for unsupported hosts or explicit source-build validation.
 
 ## Version Policy
 
@@ -101,38 +102,53 @@ Complete these steps in `codeforester/base`:
 
 9. Confirm the release tag and GitHub Release are visible on GitHub.
 
-## Homebrew Tap Checklist
+## Homebrew Tap And Bottle Checklist
 
 Complete these steps in `codeforester/homebrew-base` after the Base tag exists:
 
 1. Create a Homebrew tap update issue or PR for the new Base version.
-2. Update `Formula/base.rb`:
+2. Create a tap release branch. Do not run the bottle workflow from `master`;
+   it pushes the generated bottle stanza back to the branch that triggered it.
+3. Update `Formula/base.rb`:
    - `url` to the new Base tag archive
    - `sha256` to the checksum of that archive
    - `version` to the new Base version
-3. Compute the archive checksum from the published tag:
+4. Compute the archive checksum from the published tag:
 
    ```bash
    curl -fsSL https://github.com/codeforester/base/archive/refs/tags/vX.Y.Z.tar.gz | shasum -a 256
    ```
 
-4. Validate the formula from the tap repository:
+5. Validate the formula source-build path from the tap repository when the host
+   can run Homebrew source builds:
 
    ```bash
    brew install --build-from-source Formula/base.rb
    brew test codeforester/base
    brew audit --new --formula Formula/base.rb
    ```
 
-5. Open and merge the tap PR.
-6. Smoke-test the consumer upgrade path:
+6. Run the `Build Base Bottles` GitHub Actions workflow from the tap release
+   branch. The workflow builds bottles on supported macOS runners, uploads
+   bottle tarballs to the tap GitHub Release named `base-vX.Y.Z`, merges the
+   generated bottle JSON into `Formula/base.rb`, and pushes the bottle stanza
+   back to the branch.
+7. Confirm the tap PR includes a `bottle do` block for supported macOS targets
+   before merging. The bottle `root_url` should point at the tap release created
+   by the workflow.
+8. Open or update the tap PR, wait for checks, and merge it.
+9. Smoke-test the consumer bottle and upgrade paths:
 
    ```bash
    brew update
+   brew install --force-bottle codeforester/base/base
+   brew test codeforester/base
    brew upgrade codeforester/base/base
    ```
 
-7. Before 1.0.0, complete the
+   Use `brew reinstall --force-bottle codeforester/base/base` when Base is
+   already installed on the validation host.
+10. Before 1.0.0, complete the
    [Homebrew Upgrade Rehearsal](homebrew-upgrade-rehearsal.md) against a
    release candidate or equivalent test formula. Record the exact commands,
    host facts, pre-upgrade state, post-upgrade checks, and any follow-up issues.