fix(ci): require PR checks to pass

[pimlock]

Summary

Restore the guarantee that PRs cannot merge until the required CI checks have actually passed for the current PR head. This regressed when CI moved to nv-gha runners: the real checks now run from secure push events on copy-pr-bot mirror branches, so GitHub no longer has a direct PR-triggered required check proving those workflows ran.

Related Issue

N/A

Why This Is Needed

OpenShell uses copy-pr-bot mirror branches because workflows that check out and run contributor code must not run directly from arbitrary pull_request events on NVIDIA/self-hosted runners. The secure path is: a trusted reviewer or trusted commit flow causes copy-pr-bot to mirror the PR head to pull-request/<N>, and the real CI workflow runs from the trusted in-repo push event.

That security model creates a GitHub status gap: the checks that do the real work are triggered by push, so they are disconnected from the PR lifecycle. If copy-pr-bot does not mirror a PR, or the mirror branch is stale, the PR can appear to have green or non-blocking checks even though the required push workflow did not run for the current PR head.

Required CI Gates adds the missing link. It runs in PR context without checking out or executing PR code, inspects the trusted mirror branch and matching push workflow runs, then publishes required statuses on the PR head SHA.

Changes

• Added Required CI Gates, a pull_request_target / workflow_run workflow that publishes separate OpenShell / ... commit statuses for branch checks, E2E, GPU E2E, Kubernetes E2E, and Helm lint.
• Added pr-merge-base, a reusable composite action that resolves the merge-base needed to diff a pull-request/<N> mirror push against the PR base branch.
• Updated Helm Lint to always trigger on mirrored PR pushes, then use tj-actions/changed-files to skip expensive Helm jobs unless Helm inputs changed.
• Updated CI documentation, contribution docs, architecture notes, and the E2E label helper message so maintainers know branch protection should require the new gate statuses.

Gate Workflow

For each required workflow, Required CI Gates evaluates the PR head SHA and the copy-pr-bot mirror state:

• If the PR has no pull-request/<N> branch, publish pending with guidance to wait for or request copy-pr-bot mirroring via /ok to test <SHA>.
• If pull-request/<N> exists but points at a different SHA, publish the same pending status because the mirror still needs to be refreshed via /ok to test <SHA>.
• If the mirror matches but the workflow has not run yet, publish pending.
• If the latest event=push run for that SHA and mirror branch is still running, publish pending.
• If it completed unsuccessfully, publish failure.
• If it completed successfully, verify at least one non-metadata job succeeded, then publish success.
• For label-gated suites, publish success when the label is absent, and enforce the workflow only when the label is present.
• For path-gated suites like Helm Lint, keep changed-file detection inside the guarded workflow so the required gate only verifies workflow completion.

Rollout Follow-Up

After the new OpenShell / E2E, OpenShell / GPU E2E, and OpenShell / Kubernetes E2E statuses are required in the ruleset and verified on real PRs, remove the old E2E-only gate workflow in a follow-up PR.

Follow-up cleanup:

• Remove .github/workflows/e2e-gate.yml.
• Remove .github/workflows/e2e-gate-check.yml.
• Remove old E2E Gate references from CI.md.
• Confirm branch protection requires only the replacement OpenShell / ... E2E statuses.

Keep .github/workflows/e2e-label-help.yml; it still helps maintainers re-run the underlying label-gated push workflows after applying E2E labels.

Testing

• actionlint passed for modified workflows, ignoring the known custom linux-amd64-cpu8 runner label warning.
• Parsed .github/actions/pr-merge-base/action.yml as YAML.
• git diff --check passes.
• mise run pre-commit passes.

mise run pre-commit was attempted but is currently blocked by unrelated existing workspace issues: untracked test-policy.yaml is missing an SPDX header, and pre-existing ignored files under architecture/plans/ fail markdownlint.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)