Rehearse the Homebrew upgrade contract for 1.0.0

[codeforester]

Problem

Issue #516 documented the Homebrew tap release update process, but 1.0.0 also needs a proven consumer upgrade contract. Existing users will expect brew upgrade codeforester/base/base to preserve their ~/.base.d state, keep shell profile behavior sane, and leave basectl usable without manual repair.

Desired outcome

Before 1.0.0, run and document a repeatable Homebrew upgrade rehearsal from an existing released Base version to a 1.0.0 release candidate or equivalent test formula.

Scope

• Start from a machine or test account with an existing Homebrew Base install.
• Run basectl setup so local Base state and shell integration exist before the upgrade.
• Upgrade through the Homebrew tap path.
• Verify BASE_HOME, shell profile integration, Base venv state, and project discovery still work.
• Verify at least one Base-managed project can run basectl check, basectl doctor, and basectl test after upgrade.
• Record the exact rehearsal commands and observed results in the release checklist or a linked validation note.

Non-goals

• Do not replace the Homebrew tap release process already documented in Document Homebrew tap release update process #516.
• Do not require automated installation of Homebrew itself in this issue.
• Do not broaden this into full Linux or clean-install validation; those are covered by separate work.

Acceptance criteria

• brew upgrade codeforester/base/base succeeds from an existing released install to the candidate under test.
• Existing ~/.base.d project state is preserved.
• Shell startup still points at the upgraded Base installation.
• A Base-managed project can run setup/check/doctor/test successfully after the upgrade.
• Any breakage found during the rehearsal is either fixed or filed as a blocking follow-up before 1.0.0.

Validation

Use the release process in docs/release-process.md as the starting point, then add the concrete upgrade rehearsal evidence for the 1.0.0 candidate.

Demo impact

This closes the gap between a documented release ceremony and a trustworthy user-facing upgrade experience.

[codeforester]

Homebrew upgrade rehearsal update from 2026-06-09:

• I prepared a temporary HOME/workspace and local base-demo clone for the rehearsal.
• brew install codeforester/base/base was blocked before Base installed because Homebrew reports the host Command Line Tools are too outdated.
• brew install --ignore-dependencies codeforester/base/base hit the same CLT gate, so this was not a Base formula/runtime failure.
• Host evidence: macOS 26.5.1 x86_64, Homebrew 5.1.15-211-ge294979, Xcode 26.5, CLT reported by Homebrew as 11.3.1.
• PR Document Homebrew upgrade rehearsal blocker #537 records the repeatable rehearsal checklist and this blocked run.

Keeping this issue open until the actual brew upgrade codeforester/base/base path and post-upgrade Base/base-demo checks pass on a qualified host.

[codeforester]

Attempted the Homebrew upgrade rehearsal again from /Users/rameshhp/work/base on 2026-06-10.

Result: still blocked before Base can be installed through Homebrew, so the upgrade rehearsal cannot yet reach basectl setup, brew upgrade codeforester/base/base, or post-upgrade project checks.

Host facts from this attempt:

• macOS: 26.5.1 x86_64
• Homebrew: 5.1.15-219-gd580bc6
• Homebrew prefix: /usr/local
• CLT: 11.3.1
• Xcode: 26.5
• Formula state: codeforester/base/base stable 0.3.0, not installed
• Existing basectl on PATH: /Users/rameshhp/work/base/bin/basectl

Commands run:

brew doctor
brew config
brew info codeforester/base/base
brew install codeforester/base/base

Observed install failure:

Error: Your Command Line Tools are too outdated.
Update them from Software Update in System Settings.

If that doesn't show you any updates, run:
  sudo rm -rf /Library/Developer/CommandLineTools
  sudo xcode-select --install

Alternatively, manually download them from:
  https://developer.apple.com/download/all/.
You should download the Command Line Tools for Xcode 26.3.

Keeping this issue open. The next action is to update Command Line Tools on this Intel Mac or rerun the checklist on a qualified macOS host where brew install codeforester/base/base can complete.

[codeforester]

Implementation strategy

Use #526 as a manual release rehearsal, not a Base code feature.

Recommended path:

1. Qualify the host first.

   • Do not start the rehearsal until brew doctor is clean enough to install and upgrade packages.
   • The 2026-06-09 run is correctly blocked by the outdated Command Line Tools state, not by Base behavior.

2. Start from the current released Homebrew formula.

   • Install codeforester/base/base from the public tap.
   • Run basectl setup and basectl update-profile under the isolated TEST_ROOT/test HOME described in docs/homebrew-upgrade-rehearsal.md.
   • Record brew --prefix, command -v basectl, type -a basectl, basectl version, project discovery output, and the ~/.base.d/config.yaml checksum.

3. Prepare a candidate Homebrew tap branch, but do not merge it yet.

   • In codeforester/homebrew-base, create a release-candidate branch that updates Formula/base.rb to the candidate Base tag/archive and checksum.
   • Use the real tap formula path so the rehearsal exercises Homebrew behavior, not a bespoke install path.

4. Point the local tap checkout at the candidate branch and run the real upgrade command.

   • Use TAP_REPO="$(brew --repo codeforester/base)".
   • Fetch and check out the candidate tap branch in that tap checkout.
   • Run brew update if appropriate for the host, then brew upgrade codeforester/base/base.

5. Run the post-upgrade checks from docs/homebrew-upgrade-rehearsal.md.

   • Verify fresh Bash and Zsh shells resolve basectl to the Homebrew install.
   • Verify basectl check, basectl doctor, basectl setup <project>, basectl check <project>, basectl doctor <project>, and basectl test <project>.
   • Verify the config checksum is unchanged and the Base venv remains usable.

6. Close Rehearse the Homebrew upgrade contract for 1.0.0 #526 only after the real brew upgrade codeforester/base/base command and post-upgrade project checks pass on a qualified host.

   • If Base-specific breakage appears, file or fix it as a blocking 1.0 follow-up.
   • If the host blocks Homebrew package operations, record that as host qualification evidence and rerun on a qualified host.

This keeps #526 focused on proving the consumer upgrade contract while leaving the normal Homebrew tap release process unchanged.