Tighten tap validation workflow (#1)

* Tighten tap validation workflow

* Add tap review templates and release docs

Author: crimson-knight

.github/pull_request_template.md

@@ -0,0 +1,29 @@
+## Why
+
+- What problem does this change solve in the tap or formula workflow?
+- Why should we take it now?
+
+## What Changed
+
+- 
+
+## Decision Record
+
+- ADR updated: `none` / `docs/adr/XXXX-title.md`
+- Alternatives considered:
+- Why they were not chosen:
+
+## Release Impact
+
+- Formula behavior changed: `yes` / `no`
+- Release SOP updated: `yes` / `no` / `not needed`
+- Coordination needed with `amberframework/amber_cli`: `yes` / `no`
+
+## Verification
+
+- 
+
+## Risks And Rollback
+
+- Risk level:
+- Rollback plan:

.github/workflows/update-formula.yml

@@ -1,5 +1,8 @@
 name: Update Formula
 
+permissions:
+  contents: write
+
 on:
   repository_dispatch:
     types: [release-published]
@@ -10,7 +13,7 @@ jobs:
 
     steps:
     - name: Checkout tap
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
 
     - name: Get release info
       id: release

.github/workflows/validate-install.yml

@@ -43,6 +43,7 @@ jobs:
         fi
         brew tap amberframework/amber_cli
         brew install amber_cli
+        brew test amber_cli
         amber --version
         test -x "$(command -v amber-lsp)"
         crystal --version

docs/adr/0001-separate-homebrew-tap.md

@@ -0,0 +1,38 @@
+# ADR 0001: Keep Amber CLI Distribution In A Dedicated Tap During The Release-Candidate Phase
+
+## Context
+
+Amber v2 needs a trustworthy install path before the public announcement goes out. The immediate requirement is to verify the exact commands users will run:
+
+```bash
+brew tap amberframework/amber_cli
+brew install amber_cli
+amber new my_app
+```
+
+The CLI release process is still evolving, and the team wants to keep the tap formula, checksum updates, and smoke tests under direct control before pursuing `homebrew/core`.
+
+## Decision
+
+During the Amber v2 release-candidate phase:
+
+- the tap formula will point at released Amber CLI assets from `amberframework/amber_cli`
+- the tap will update itself from the CLI release workflow
+- tap CI will verify both `brew test amber_cli` and a scaffold smoke test on macOS and Ubuntu
+
+## Consequences
+
+### Positive
+
+- the actual end-user install path is under CI coverage
+- release regressions are caught before announcement posts go live
+- the tap can evolve quickly while the CLI and docs stabilize
+
+### Tradeoffs
+
+- the tap is one more repository to keep aligned
+- this is a stepping stone, not the final `homebrew/core` story
+
+### Follow-up
+
+Once the release process and scaffold stabilize, evaluate a source-built formula path for `homebrew/core`.

docs/adr/README.md

@@ -0,0 +1,16 @@
+# Architecture Decision Records
+
+This directory records the durable reasons behind how the Amber CLI Homebrew tap works.
+
+Add or update an ADR when a change affects:
+
+- formula distribution strategy
+- tap CI expectations
+- release handoff from `amberframework/amber_cli`
+- the verified install path users run on fresh machines
+
+Keep ADRs short:
+
+1. Context
+2. Decision
+3. Consequences

docs/release-handoff.md

@@ -0,0 +1,43 @@
+# Release Handoff
+
+This repository is the Homebrew distribution layer for `amberframework/amber_cli`.
+
+## Purpose
+
+The tap exists to make the Amber v2 install path real and testable before broader package distribution work begins.
+
+The path we care about is:
+
+```bash
+brew tap amberframework/amber_cli
+brew install amber_cli
+brew test amber_cli
+amber new my_app
+```
+
+## Responsibilities
+
+This repo is responsible for:
+
+- updating `Formula/amber_cli.rb` after a CLI release
+- keeping macOS and Ubuntu install smoke tests green
+- documenting any packaging decisions that affect users
+
+## PR Expectations
+
+Any PR that touches the formula or workflows should explain:
+
+- why the tap behavior is changing
+- whether coordination with `amberframework/amber_cli` is required
+- how the change was verified
+
+Use the repository PR template so this context is captured in review.
+
+## Release Verification
+
+After a CLI release:
+
+1. confirm the formula version and checksums updated
+2. confirm `Validate Install` passed on macOS
+3. confirm `Validate Install` passed on Ubuntu
+4. if the update fails, patch the formula manually and rerun the smoke workflow