docs(release): gate Homebrew availability claims

.changeset/tender-ravens-wait.md

@@ -0,0 +1,2 @@
+---
+---

skills/hunk-release/SKILL.md

@@ -193,7 +193,7 @@ Draft the final body from the released changelog and actual branch diff. Replace
 
 - Open with one short paragraph describing the release's product theme and user impact.
 - Group a small number of meaningful changes under descriptive headings. Explain what users can now do; do not restate commit titles or reproduce the changelog.
-- Include both upgrade and npm installation instructions using the exact release: `hunk update <version>` for existing managed installs and `npm install -g hunkdiff@<version>` for npm installs or first-time npm users. Add other installation-method-specific guidance only when relevant.
+- Include both upgrade and npm installation instructions using the exact release: `hunk update <version>` for npm- and curl-managed installs and `npm install -g hunkdiff@<version>` for npm installs or first-time npm users. Homebrew cannot select an exact version: tell its users to run plain `hunk update` only after the Homebrew readiness gate below passes, or label Homebrew propagation as pending.
 - Add a clearly labeled compatibility section for runtime requirements, changed CLI interpretation, extension API variants, migrations, or other upgrade risks.
 - Add a **Community contributors** section that names every external contributor in the release, links each relevant PR, and briefly describes their contribution. Derive this from the actual release diff; do not limit acknowledgment to first-time contributors and do not bury contributors in an autogenerated list.
 - Preserve a complete PR inventory inside a collapsed GitHub `<details>` block after the editorial sections. Use one concise bullet per merged PR with its author and link, include maintenance work there, and verify the list against the actual previous-tag comparison. The collapsed inventory is for completeness; it does not replace the curated highlights or contributor acknowledgments.
@@ -247,7 +247,55 @@ Open the public release in a browser and verify inline playback, final notes, an
 
 ## 6. Distribution channels
 
-Only stable releases that advance `latest` should propagate to Homebrew and mise. Let Homebrew Autobump update `Homebrew/homebrew-core`; use `brew bump-formula-pr` only if maintainers request it or Autobump stalls. Verify mise against fresh registry data:
+Only stable releases that advance `latest` should propagate to Homebrew and mise. Let Homebrew Autobump update `Homebrew/homebrew-core`; use `brew bump-formula-pr` only if maintainers request it or Autobump stalls.
+
+Treat Homebrew availability as an announcement check only. Never delay or fail the tag, npm publication, GitHub release, changelog, release notes, video, or other release completion work because Homebrew is pending. Homebrew detects the published release on its own schedule and merges a separate formula PR. Immediately before an external promotional announcement that names Homebrew or recommends `hunk update` without qualifying the install method, read the live formula API and require its stable version to match:
+
+```sh
+version=X.Y.Z
+formula_version=$(
+  curl -fsSL https://formulae.brew.sh/api/formula/hunk.json |
+    bun -e 'console.log(JSON.parse(await Bun.stdin.text()).versions.stable)'
+)
+printf 'Homebrew formula: %s (release: %s)\n' "$formula_version" "$version"
+test "$formula_version" = "$version"
+```
+
+If the check fails, still mark the software release complete, but hold the external promotional announcement unless it explicitly says that Homebrew is still propagating and offers npm or the install script meanwhile. Check for an open or merged Autobump PR:
+
+```sh
+gh api --method GET /search/issues \
+  -f q="repo:Homebrew/homebrew-core is:pr in:title \"hunk $version\"" \
+  --jq '.items[] | [.html_url, .state, .title] | @tsv'
+```
+
+Determine the next expected Autobump scan from Homebrew's live workflow rather than relying on a remembered cadence. This command prints the current cron expression and, while Homebrew retains its present three-hour schedule, the next nominal UTC scan. Scheduled GitHub Actions can start late, so report this as an estimate rather than an availability promise:
+
+```sh
+autobump_workflow=$(
+  gh api repos/Homebrew/homebrew-core/contents/.github/workflows/autobump.yml \
+    --jq .content | base64 --decode
+)
+autobump_cron=$(
+  printf '%s\n' "$autobump_workflow" |
+    awk -F'"' '/^[[:space:]]*- cron:/ { print $2; exit }'
+)
+printf 'Homebrew Autobump schedule: %s\n' "$autobump_cron"
+AUTOBUMP_CRON="$autobump_cron" bun -e '
+  const cron = process.env.AUTOBUMP_CRON;
+  if (cron !== "45 1-23/3 * * *") {
+    console.error("Homebrew changed its Autobump schedule; inspect the workflow before announcing.");
+    process.exit(1);
+  }
+  const next = new Date();
+  next.setUTCSeconds(0, 0);
+  do next.setUTCMinutes(next.getUTCMinutes() + 1);
+  while (next.getUTCMinutes() !== 45 || (next.getUTCHours() - 1) % 3 !== 0);
+  console.log(`Next nominal Homebrew Autobump scan: ${next.toISOString()}`);
+'
+```
+
+After the formula version matches, run `brew update`, verify `brew info hunk` reports the release, and only then describe Homebrew as available. Verify mise independently against fresh registry data:
 
 ```sh
 MISE_AQUA_BAKED_REGISTRY=false mise latest hunk