Document safe Homebrew publication and migration operations

[brandonpayton]

Why

The Homebrew migration now has a working public-by-default package path and completed zlib/bzip2 cutover pilots, but the authoritative runbook still described those pilots as pending. It also omitted the exact reusable-workflow pin rotation and immutable-upload recovery procedures that operators have needed during the catalog rollout, and its documented cargo xtask validation command does not exist in this repository configuration.

That stale and incomplete guidance puts maintainers at risk of restoring the retired PAT profile, rerunning an old workflow pin, overwriting an occupied bottle identity, deleting migration controls before a fresh inventory, or claiming third-party/default-shell acceptance before the required runtime evidence exists.

What changed

• Document the supported public-by-default transport: repository-rooted GHCR packages and the caller repository's built-in GITHUB_TOKEN, with no production package PAT or visibility mutation.
• Define the exact three-caller workflow-pin rotation, matching trust constant, historical constants that must remain unchanged, expected candidate/base trust signals, and fresh-dispatch rule.
• Define the first-party rollout policy: one Formula per write dispatch, at most eight active writes, dependency-ready scheduling, and no Actions reruns after a failure.
• Define evidence-driven recovery when a failed run has already occupied an immutable public child, including the temporary next-rebuild reservation and finalizer handoff.
• Record the successful zlib and bzip2 production gates and preserve deletion as a separate explicitly authorized package-admin operation with fresh pre-delete checks.
• Keep external federated M4 publication and schema-2 default-shell acceptance explicitly pending, with the exact failed runs and acceptance criteria.
• Replace non-existent cargo xtask examples with the repo-supported host-targeted cargo run -p xtask path through scripts/dev-shell.sh.
• Link the checked-in tap template to the authoritative pin, dispatch, retry, and cleanup procedures instead of duplicating them.

Validation

• git diff --check
• Markdown fence-balance check for all three changed files
• Executed the newly documented host-target discovery and homebrew-validate command through scripts/dev-shell.sh
• Clean live-tap validation: homebrew-validate: ok (packages=44, bottles=50, link_manifests=50, provenance_reports=50)
• Credential-free complete-index imports for current public homebrew-tap-core/zlib and homebrew-tap-core/bzip2
• GitHub package API inspection: both production packages are public and linked to kandelo-dev/homebrew-tap-core; both legacy private package timestamps still match their recorded baselines
• Exact job audit: zlib run 29731335304 and bzip2 run 29701320996 completed every required publication job successfully
• Live namespace scan: no active old-root URL outside historical reports

Boundaries

This is documentation and checked-in template documentation only. It does not change publisher behavior, Formulae, shared support, package visibility, registry objects, Node/browser behavior, or the ABI. Runtime suites were not run. External M4 and first-party default-shell end-to-end acceptance remain open evidence gates and are documented as such.

[brandonpayton]

Superseded by #1022, which rebases this three-file runbook work onto current main and updates the live migration status while keeping #1019 explicitly pending. Closing the conflicting older review so there is one authoritative docs PR; no implementation PR is merged by this action.