feat: add one-command upgrades for stable tagged source checkouts #2598

Goal

Provide a safe, deterministic one-command upgrade path for a stable source checkout pinned to a published Base release tag.

Problem

The stable source-install recipe deliberately checks out an immutable release ref such as v1.10.5. That checkout is detached, while the current basectl update source path requires the selected repository to be on its default branch before it pulls.

As a result, a consumer who installed Base from a stable source tag does not have the same simple upgrade experience as:

• a Homebrew consumer using basectl update; or
• a mutable main checkout using basectl update.

The current install.sh path updates an existing checkout with git pull --ff-only; its --branch option selects the branch only for a new clone. It does not provide a clear, safe in-place release-tag transition.

Required behavior

Design and implement a supported one-command upgrade contract for stable tagged source checkouts. The command may be basectl update with an explicit release/channel option or another clearly named Base command, but the target-selection behavior must be deterministic and documented.

The implementation must:

• identify a stable tagged source checkout separately from a mutable development checkout;
• define how the target release is selected, avoiding an accidental move to an unintended release line;
• preserve safety for tracked changes, untracked files, detached state, and unrelated local files;
• never reset or discard user changes implicitly;
• move the checkout to the selected published release ref using a verified Git object/ref;
• run the required Base setup and reconcile declared test requirements after the ref change;
• preserve or explicitly migrate Base-managed local state and shell integration;
• report the old and new Base identities clearly;
• provide actionable recovery when the target ref is unavailable, the checkout is dirty, or setup fails;
• make manifest/test-requirement trust changes visible so the user knows when review and re-approval are required.

Acceptance criteria

• A stable tagged source checkout can upgrade from one published release to a selected later published release through one documented command.
• The command has deterministic target selection and does not silently follow main or cross a release policy boundary.
• Dirty and unsafe checkouts fail before Git or environment mutation with recovery guidance.
• The checkout revision, basectl version, managed runtime requirements, and basectl check --verify-project-runtime agree after a successful upgrade.
• Setup failure leaves the checkout recoverable and reports the exact next action.
• A manifest or declared test-requirements change produces the expected trust-review guidance before basectl test.
• Tests cover successful tagged upgrades, already-current releases, unavailable targets, dirty worktrees, and setup failure.
• The command is documented by docs: document the Base upgrade contract across Homebrew and source installs #2597 and does not regress the existing Homebrew or mutable-source update paths.

Non-goals

• Do not change Homebrew upgrade behavior; see bug: Homebrew Base upgrade can leave a stale base-cli in the managed venv #2596.
• Do not automatically update every consumer project in the workspace.
• Do not make basectl check mutate the checkout or environment.