Add opt-in PR stack support

[GrantBirki]

This pull request adds opt-in native PR stack support with enable_pr_stacks, which defaults to false while GitHub stacks are in public preview. It checks the selected PR and its unmerged lower PRs before deploying the exact checked commit. Ordinary PRs keep their existing deployment behavior without calling the preview stack API, even when the flag is enabled.

Related to #495.

[Copilot]

Pull request overview

Adds opt-in native GitHub pull request stack deployments while preserving existing behavior for ordinary PRs.

Changes:

• Adds enable_pr_stacks, stack discovery, ancestry validation, and exact-SHA deployment.
• Enforces checks and reviews across the selected stack prefix.
• Adds documentation, mocks, contract coverage, unit tests, and bundled runtime updates.

Reviewed changes

Copilot reviewed 25 out of 27 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
action.yml	Declares the opt-in stack input.
README.md	Documents the new input.
docs/pr-stacks.md	Explains stack deployment behavior.
src/action-io.ts	Registers the input key.
src/types.ts	Adds stack-related input and precheck types.
src/functions/inputs.ts	Parses the stack option.
src/functions/help.ts	Reports stack configuration in help.
src/functions/pr-stacks.ts	Resolves and validates stack snapshots.
src/functions/pr-stack-checks.ts	Loads required checks from branch policies.
src/functions/prechecks.ts	Applies checks across stack members.
src/functions/selected-ref-check.ts	Detects newly added stack membership.
src/functions/deployment-operation.ts	Revalidates stacks and deploys exact SHAs.
tools/acceptance/types.ts	Extends acceptance mock types.
tools/acceptance/mock-github.ts	Mocks stack and policy APIs.
dist/index.js	Updates the committed runtime bundle.
__tests__/types.test.ts	Updates typed input expectations.
__tests__/test-helpers.ts	Adds the default stack input.
__tests__/schemas/action.schema.yml	Extends action metadata validation.
__tests__/main.test.ts	Tests stack deployment orchestration.
__tests__/functions/selected-ref-check.test.ts	Tests membership rechecks.
__tests__/functions/prechecks.test.ts	Tests stack-wide policy enforcement.
__tests__/functions/pr-stacks.test.ts	Tests stack parsing and validation.
__tests__/functions/pr-stack-checks.test.ts	Tests required-check discovery.
__tests__/functions/help.test.ts	Tests stack help output.
__tests__/action-contract.test.ts	Verifies the public input contract.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[GrantBirki]

This was tested extensively on the following live pull requests seen below

---

Final tested SHA: 4dfe380063dcc54b5d2557b1cdb3436d8e10689e

GrantBirki/actions-sandbox

• Ordinary PR compatibility: #195
• Native stack deployments: #196, #197, #198
• Review requirements and required CI: #200, #201, #202
• Required status checks and PRs joining stacks: #204, #205
• Restacking, changed lower PRs, and partially merged stacks: #206, #207, #208, #210
• Cross-repository fork head movement: #214

birki-sandbox/actions-sandbox

• Same-repository fork head movement: #4
• A PR joining a native stack during deployment confirmation: #5, #6

Earlier testing and supporting PRs

These are historical context, not additional passing evidence for the final SHA.

• Initial stack testing: #181, #182, #183
• Earlier ordinary-PR and stack compatibility testing: #189, #190, #191, #192
• Workflow setup, fixes, and candidate updates: #180, #185, #187, #188
• Sandbox restoration: #186, #194
• Superseded fork test fixtures: GrantBirki #213, birki-sandbox #1, #2, #3