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.