Allow staged install step conversion

[MikeMcQuaid]

• Let formula steps run before a remaining post_install so tap migrations can move repeated statements without blocking on unrelated Ruby work.
• Keep the legacy conflict check as a TODO because side-by-side use is only a temporary conversion bridge.
• Make formula and cask DSL ordering reflect runtime order while the bridge exists.
• Record the final deprecation target and local tap verification workflow so follow-up tap PRs have a concrete success condition.

---

• Have you followed our Contributing guidelines?
• Have you checked for other open Pull Requests for the same change?
• Have you explained what your changes do? Performance claims (e.g. "this is faster") must include Hyperfine benchmarks.
• Have you explained why you'd like these changes included, not just what they do?
• For bug fixes, have you given step-by-step brew commands to reproduce the bug?
• Have you written new tests (excluding integration tests)? Here's an example.
• Have you successfully run brew lgtm (style, typechecking and tests) locally?

---

• AI was used to generate or assist with generating this PR.

OpenAI Codex 5.5 xhigh with local review and testing.

---

[Copilot]

Pull request overview

This PR updates Homebrew’s staged install-step “bridge” behavior so formula post_install_steps can run before a remaining legacy post_install, enabling incremental tap conversions without blocking on unrelated Ruby hook work. It also adjusts RuboCop and DSL ordering rules (formula + cask) to reflect the intended runtime/transition order, and documents the deprecation target and verification workflow.

Changes:

• Run formula post_install_steps (if defined) and then run legacy post_install (if defined), instead of treating them as mutually exclusive.
• Add/adjust RuboCop rules + tests to allow temporary coexistence while enforcing ordering (*_steps must appear before the matching legacy hook/stanza).
• Update documentation/planning notes to reflect the conversion bridge, ordering expectations, and deprecation goals.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
Library/Homebrew/test/rubocops/install_steps_spec.rb	Updates cop expectations to allow coexistence and adds an ordering offense test.
Library/Homebrew/test/rubocops/cask/stanza_order_spec.rb	Adds a test asserting *_steps stanzas should be ordered before legacy *flight stanzas.
Library/Homebrew/test/formula_spec.rb	Reworks formula expectations to track coexistence via “defined?” predicates rather than conflict.
Library/Homebrew/test/cmd/postinstall_spec.rb	Adds a regression test ensuring brew postinstall runs steps before legacy post_install.
Library/Homebrew/rubocops/install_steps.rb	Disables the conflict offense (temporarily) and adds an ordering offense for formula hooks.
Library/Homebrew/rubocops/cask/constants/stanza.rb	Reorders stanza groups so *_steps come before matching legacy *flight stanzas.
Library/Homebrew/json_api_postinstall_preflight_postflight_plan.md	Updates the plan to describe the temporary bridge, ordering rules, and end-state deprecation goals.
Library/Homebrew/formula.rb	Removes conflict/warning helpers now that coexistence is supported.
Library/Homebrew/formula_installer.rb	Changes install finishing to run post_install_steps and then post_install when both are defined.
Library/Homebrew/cmd/postinstall.rb	Updates brew postinstall to run steps first and only warn when neither legacy hook nor steps exist.
docs/Formula-Cookbook.md	Documents that coexistence is allowed during incremental conversions and clarifies runtime order.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[p-linnane]

I think this is a solid way of handling the transition.