@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/templates/ci/incidents.yml.template

@@ -0,0 +1,103 @@
+# Generated locally after review. Publish to activate record-only incident intake.
+# Optional dispatch requires an owner-provided executor accepting the four documented inputs.
+name: Build CI incidents
+on:
+  workflow_run:
+    workflows: ['REVIEWED_BACKGROUND_WORKFLOW']
+    types: [completed]
+  workflow_dispatch:
+    inputs:
+      incident_number:
+        required: true
+        type: string
+      expected_attempt:
+        required: true
+        type: string
+      executor_run_id:
+        required: true
+        type: string
+      outcome:
+        required: true
+        type: choice
+        options: [retry, needs-decision, candidate]
+      repair_pr:
+        required: false
+        type: string
+      repair_sha:
+        required: false
+        type: string
+permissions:
+  contents: read
+  actions: read
+  issues: write
+jobs:
+  intake:
+    if: github.event_name == 'workflow_run'
+    runs-on: ubuntu-latest
+    concurrency:
+      group: build-incident-dispatch
+      cancel-in-progress: false
+      queue: max
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444
+        with:
+          node-version: '24'
+      - run: node .build-project/ci/incident-intake.mjs intake
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+  reconcile:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
+      issues: write
+      pull-requests: read
+      checks: read
+    concurrency:
+      group: build-incident-dispatch
+      cancel-in-progress: false
+      queue: max
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444
+        with:
+          node-version: '24'
+      - run: node .build-project/ci/incident-intake.mjs reconcile
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          BUILD_REPAIR_WORKFLOW: ${{ vars.BUILD_REPAIR_WORKFLOW }}
+  dispatch:
+    needs: [intake, reconcile]
+    if: always() && (needs.intake.result == 'success' || needs.reconcile.result == 'success') && vars.BUILD_REPAIR_DISPATCH_ENABLED == 'true' && vars.BUILD_REPAIR_CALLBACK_CONFIGURED == 'true' && vars.BUILD_REPAIR_WORKFLOW != ''
+    runs-on: ubuntu-latest
+    # GitHub.com queues at most 100 waiting jobs; incident issues remain durable beyond this bound.
+    concurrency:
+      group: build-incident-dispatch
+      cancel-in-progress: false
+      queue: max
+    permissions:
+      contents: read
+      actions: write
+      issues: write
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444
+        with:
+          node-version: '24'
+      - run: node .build-project/ci/incident-intake.mjs dispatch
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          BUILD_REPAIR_DISPATCH_ENABLED: ${{ vars.BUILD_REPAIR_DISPATCH_ENABLED }}
+          BUILD_REPAIR_WORKFLOW: ${{ vars.BUILD_REPAIR_WORKFLOW }}
+          BUILD_REPAIR_CALLBACK_CONFIGURED: ${{ vars.BUILD_REPAIR_CALLBACK_CONFIGURED }}

package/templates/ci/node.yml.template

@@ -0,0 +1,17 @@
+name: Build CI
+on:
+  pull_request:
+  push:
+    branches: [__DEFAULT_BRANCH__]
+permissions:
+  contents: read
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+jobs:
+  validation:
+    name: Build CI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444

package/templates/ci/python.yml.template

@@ -0,0 +1,17 @@
+name: Build CI
+on:
+  pull_request:
+  push:
+    branches: [__DEFAULT_BRANCH__]
+permissions:
+  contents: read
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+jobs:
+  validation:
+    name: Build CI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1

package/templates/guard-kit/GUARD_SETUP.md.template

@@ -0,0 +1,258 @@
+# Build Guard setup playbook (kit version {{KIT_VERSION}})
+
+## What this is
+
+This file is the PATH; `build guard verify` is the GROUND TRUTH. Follow these
+steps, in order, until `build guard verify` reports `configured` (all local and
+GitHub criteria pass) or `proven-gated` (a live rejection was also witnessed).
+Re-run `build guard verify` after every step and let its scorecard — not this
+document — tell you what is still missing.
+
+This file is generated by Build. It is overwritten on every
+`build init --guardrails` install/upgrade/reinstall. It is NOT hash-tracked, so
+you may annotate it freely without tripping a tamper check, but your notes are
+lost on the next upgrade — keep durable notes elsewhere.
+
+## The criteria (C1..C7)
+
+`build guard verify` evaluates seven criteria, in order. Order is load-bearing:
+later criteria depend on earlier ones (C5/C6 need the check identity from C4 and
+the remote default branch from C2; C7 needs the identity from C4).
+
+| ID | Meaning (one line) |
+|----|--------------------|
+| C1 | Kit installed and untampered (`.build-project/guard/` present, hashes match the lock). |
+| C2 | Gate present on the remote default branch (`check.mjs` committed on `main`). |
+| C3 | Local gate actually gates (self-test: the committed `check.mjs` rejects a planted violation). |
+| C4 | A single gate-check identity is derivable from your workflows (one job, correct triggers, no `continue-on-error`). |
+| C5 | Green evidence for the current default-branch head or the merged PR that produced it. |
+| C6 | Branch protection (or a ruleset) REQUIRES that check context, ideally with up-to-date-branch strictness. |
+| C7 | Witnessed live rejection: a canary PR was actually blocked by the check (the proof). |
+
+### Verdict ladder
+
+- `not-gated` — a criterion in C1..C6 hard-FAILED, or a canary was NOT rejected
+  (C7 fail). `build guard verify` exits 1.
+- `partially-gated` — no hard failure, but at least one C1..C6 criterion is a
+  `gap` (could not be verified: missing `gh`, no network, opaque ruleset
+  semantics, or skipped via a flag). Exits 3.
+- `configured` — C1..C6 all pass. C7 may be a gap. This is the normal "the gate
+  is wired and required" target. Exits 0.
+- `proven-gated` — C1..C6 all pass AND C7 passes (a canary was witnessed being
+  rejected). The strongest verdict. Exits 0.
+
+A criterion that cannot be verified is a `gap`, never a `pass` — the scorecard
+fails closed. `configured` and `proven-gated` are unreachable while any C1..C6
+criterion is a gap (for example, an uninterpretable ruleset forces C6 to a gap).
+
+## Ordered steps
+
+Do these in order. Skipping ahead — especially requiring the check (C6) before
+it has ever reported green (C5) — deadlocks every PR.
+
+### Step 1 — Install the kit (C1)
+
+```bash
+build init --guardrails
+```
+
+This renders `.build-project/guard/` (`check.mjs`, `config.json`, `policy.json`,
+`checks.lock`, and this file). `policy.json` carries the repo's `git.attribution`
+mode; change it with `build config set git.attribution <allow|human-only>`
+followed by `build guard sync`, never by hand. In ordinary repositories it also installs one
+repo-local pre-commit wrapper that runs the built-in secret catalog against the
+staged index. Existing hooks are preserved as a sidecar. Build does not rewrite
+global, Husky-generated, or tracked repository hooks; those repositories keep
+their existing local hook policy and still use the hosted Guard.
+
+The local scan is a fast accident-prevention layer, not a replacement for a
+deeper scanner such as Gitleaks or TruffleHog. If Node is temporarily unavailable,
+use `SKIP_BUILD_GUARD_SECRET_SCAN=1 git commit ...`; `--no-verify` bypasses every
+pre-commit hook and should be reserved for recovery. Confirm C1:
+
+```bash
+build guard verify
+```
+
+C1 should read `OK: C1 Kit installed and untampered`. If it reports `absent`,
+run the install again; if `tampered`/`partial`, run
+`build init --guardrails --reinstall-guard`.
+
+### Step 2 — Commit the gate on a branch
+
+Create a normal working branch and commit the whole guard directory:
+
+```bash
+git checkout -b add-build-guard
+git add .build-project/guard
+git commit -m "Add Build guard kit"
+```
+
+The gate only works once `check.mjs` is COMMITTED — the CI trusted-base pattern
+reads it from the base branch's tree. A repo-wide `.build-project/` gitignore silently
+swallows it; make sure `.build-project/guard/check.mjs` is tracked.
+
+### Step 3 — Add the reference workflow (C4)
+
+Print the reference GitHub Actions workflow and save it:
+
+```bash
+build guard print-ci > .github/workflows/build-guard.yml
+```
+
+(You can also copy `build-guard.yml.template` from the kit and substitute the
+kit version yourself.) Adapt ONLY the CUSTOMIZE-FREELY regions marked in the
+file (runner label, timeout, optional path-filter additions). Do NOT change the
+MUST-NOT-CHANGE regions: `permissions: contents: read`, the trusted-base
+extraction, the `test -s` non-empty guard, `fetch-depth: 0`, both triggers
+(`pull_request_target` and `merge_group`), checkout of the base branch (do
+not set checkout `ref:` to the PR head), and the literal job
+`name: Build Guard` (that name is the required status-check context).
+Commit it alongside the gate.
+
+### Step 4 — Land the gate + workflow on the default branch (C2, C5)
+
+Open a PR from your branch and merge it into the default branch through your
+existing flow. This satisfies C2. The introducing PR cannot use a
+`pull_request_target` workflow absent from its base, and the reference workflow
+has no default-branch push trigger.
+
+### Step 5 — Confirm green evidence for the current default branch (C5)
+
+Use the next ordinary PR after installation: its base now contains the workflow.
+Wait for its "Build Guard" check to pass, then merge through the existing flow.
+A small verification PR can establish this first run if no ordinary change is
+ready. After that merge, run:
+
+```bash
+build guard verify
+```
+
+C5 accepts a successful check on the CURRENT default-branch head or on the
+merged PR that produced it. An unrelated historical green run is insufficient.
+If C5 reports no evidence, inspect the associated PR and workflow event; waiting
+alone does not create a missing run. Require the check only after C5 passes.
+
+For a PR head that remains "Expected — Waiting for status", diagnose the exact
+SHA without changing the C1..C7 verdict:
+
+```bash
+build guard verify --head-sha <40-character-head-sha>
+```
+
+The diagnostic distinguishes absent, queued, running, completed, and stale-head
+state. If an open PR still has no event or app-bound check after 15 minutes,
+close and reopen that PR to retrigger the native `pull_request_target`
+workflow on the same SHA. Do not publish a replacement check manually; the
+GitHub Actions-owned workflow remains the only attestation producer.
+
+### Step 6 — Require the check in branch protection (C6)
+
+ONLY after C5 is green. Requiring a check that has never reported deadlocks every
+PR ("Expected — Waiting for status" forever). Require the exact context string
+`Build Guard` with up-to-date-branch strictness.
+
+UI path: Repository Settings -> Branches (or Rules -> Rulesets) -> the default
+branch rule -> "Require status checks to pass before merging" -> add
+`Build Guard` -> also enable "Require branches to be up to date before merging".
+
+Add the context to the existing policy. Preserve all other required checks
+(including `Build Local CI`, if present), expected check sources, review
+requirements, push restrictions, and administrator policy. Select GitHub Actions
+as the expected source for `Build Guard` where the UI supports it. A full
+branch-protection replacement can remove those existing controls; use the
+additive UI procedure above.
+
+Strictness matters: without "up to date before merging" a PR can merge green
+against a stale base and break the gate on the new head (the stale-green-merge
+race). Re-run `build guard verify`; C6 should pass and the verdict should reach
+`configured`.
+
+### Step 7 — Optional live proof canary (C7)
+
+This upgrades `configured` to `proven-gated` by WITNESSING a real rejection.
+
+1. Branch: `git checkout -b build-guard-canary/<date>` (the
+   `build-guard-canary/` prefix lets `build guard verify` auto-discover it).
+2. Add a file whose path matches an artifact deny glob (see
+   `defaultDenyPaths` / `extraDenyPaths`; a path listed in `config.json`
+   `allowPaths` is exempt from the defaults) — for example a committed
+   `dist/` build output. NEVER use a secret-shaped string: push protection would
+   reject the push and page your security team, and the point is to test the
+   gate, not the platform.
+3. Open it as a DRAFT PR. Expect the "Build Guard" check to FAIL within
+   minutes. If it PASSES, your gate is broken — return to Step 3 and check the
+   workflow's trusted-base extraction and triggers.
+4. Close the PR UNMERGED (never merge a canary).
+5. Prove it:
+
+   ```bash
+   build guard verify --canary-pr <n>
+   ```
+
+   With C1..C6 already passing, C7 now passes and the verdict is `proven-gated`.
+
+## Exit-code contracts
+
+The gate (`check.mjs`, run in CI):
+
+- `0` — clean.
+- `1` — a HARD finding (secret in an added line, a denied artifact path, or AI
+  attribution under `human-only`). Blocks the merge.
+- `2` — ONLY guard-machinery changed under `.build-project/guard/` and no hard finding.
+  Softer than 1, but the reference workflow still blocks on it: it means "a human should review the
+  gate change." Legitimate kit-upgrade PRs are the expected exit-2 case. A hard
+  finding always dominates, so exit 1 wins when both are present. See the
+  [two-context/review alternative](#two-context-split-for-automerge-teams) before
+  choosing a different maintenance policy; human review alone does not override a
+  failing required check.
+
+`build guard verify` (the scorecard):
+
+- `0` — `configured` or `proven-gated`.
+- `3` — `partially-gated` (at least one unverifiable gap, no hard failure).
+- `1` — `not-gated` (a criterion failed, or a canary was not rejected).
+
+## Troubleshooting
+
+| Scorecard message (paraphrased) | Next action |
+|---------------------------------|-------------|
+| C1 state is `absent` | Run `build init --guardrails`. |
+| C1 state is `tampered`/`partial` | Run `build init --guardrails --reinstall-guard`; `config.json` is preserved. |
+| C2 gate not on the default branch | Merge the branch from Step 2 to the default branch (Step 4). |
+| C3 self-test could not run / skipped via `--no-selftest` | Run in a full checkout with Node >= 24; drop `--no-selftest`. |
+| C4 "no GitHub Actions workflows found" | Add the workflow from Step 3 (`build guard print-ci`). |
+| C4 flags `continue-on-error` / missing trigger / dead extraction | Fix the workflow's MUST-NOT-CHANGE regions; do not soften the gate. |
+| C5 "has never reported on the current default-branch head" | Complete the post-install PR flow in Step 5; do not require the check yet. |
+| C5 "not green ... latest conclusion: failure" | Investigate the failing run; the gate found a real problem or the workflow is misconfigured. |
+| C6 "does not require 'Build Guard'" | Require the context in branch protection / a ruleset (Step 6). |
+| C6 "strict ... enforcement is OFF" | Enable "Require branches to be up to date before merging" / `strict_required_status_checks_policy=true`. |
+| C6 "semantics could not be fully interpreted" | Inspect the ruleset with the `gh api` command shown; a merge-queue-only ruleset with no visible required checks reads as a gap. |
+| C7 "no canary proof recorded" | Run the Step 7 canary (an artifact-path violation, never a secret), or pass `--canary-pr <n>`. |
+| C7 "was merged — the gate did not block it" | The gate did not reject the canary: it is broken. Return to Step 3. |
+
+## Optional patterns
+
+### Two-context split for automerge teams
+
+If you want routine PRs to automerge but still block on gate-machinery changes,
+split the single check into two contexts: one required check that runs the gate
+and treats only hard findings (exit 1) as failing, and a second required check
+(or a `CODEOWNERS`-gated review) for guard-directory changes (exit 2). Require
+both; automation may merge when the hard-finding context is green while
+exit-2 PRs still wait for a human. Keep the trusted-base extraction in both.
+
+## Non-GitHub CI
+
+The trusted-base pattern is portable. On another CI platform, replicate the
+reference workflow's shell step: fail closed (`set -euo pipefail`), fetch the
+base branch, `git show base:.build-project/guard/check.mjs > "$PRIVATE_TMP/guard-check.mjs"`
+(use a private per-run temp path, never a predictable shared `/tmp` filename),
+`test -s` it, then run it with `BUILD_GUARD_DIR="$PWD/.build-project/guard"`. Enforce
+the equivalent of a required, up-to-date status check in your platform's
+merge-protection settings.
+
+Criteria C5, C6, and C7 use the GitHub API (via `gh`) and will report `gap` off
+GitHub, so `configured`/`proven-gated` are unreachable there — that is expected,
+not a failure. Rely on the local criteria (C1..C4) plus your platform's own
+equivalents of the green-run, required-check, and rejection-proof gates.

package/templates/guard-kit/build-guard.yml.template

@@ -0,0 +1,189 @@
+# Build Guard reference workflow (kit version {{KIT_VERSION}}).
+#
+# Emitted by `build guard print-ci`. This is NOT installed into your repo
+# automatically: copy it to .github/workflows/build-guard.yml, commit it on a
+# branch, land it on your default branch, confirm one green run, and only then
+# require the "Build Guard" check in branch protection. The ordered procedure
+# and the criteria this satisfies (C4..C7) live in .build-project/guard/GUARD_SETUP.md.
+#
+# ---------------------------------------------------------------------------
+# MUST NOT CHANGE (security-critical — editing these breaks the guarantee):
+#   * permissions: contents: read (least privilege; do not widen).
+#   * The trusted-base extraction: the gate is run from the BASE branch's copy
+#     of check.mjs, not the PR's copy. A PR could otherwise strip its own
+#     guard-integrity check before it runs. Keep the `git show ... > file`,
+#     the `test -s` non-empty guard, and `set -euo pipefail` exactly as-is.
+#   * fetch-depth: 0 (the gate needs history to find the merge base; a shallow
+#     clone makes it fail closed instead of passing silently).
+#   * Both triggers: pull_request_target AND merge_group. pull_request_target
+#     is what makes GitHub load THIS workflow file from the base/default
+#     branch; `on: pull_request` would load the PR's copy, so a PR could
+#     rewrite the YAML to skip the gate and still publish a green
+#     "Build Guard" context. A merge queue re-runs required checks in the
+#     queue; omitting merge_group leaves queued PRs unguarded / stuck.
+#   * Checkout the BASE / default branch (the pull_request_target default).
+#     Do NOT set checkout `ref:` to the PR head — that would make the
+#     workspace the untrusted tree used to run scripts. Fetch the PR head
+#     SHA only as a git object for the gate's diff.
+#   * The pull_request_target `types:` list must keep `edited`. Every check
+#     below is computed against the BASE branch, and the required status is
+#     bound to the head SHA — so retargeting a PR to a different base leaves
+#     the previous base's green result standing for an unexamined range.
+#     `edited` is the only event GitHub fires for a base change (with
+#     changes.base), and the default types (opened, synchronize, reopened)
+#     do not include it. Re-running on `edited` re-reports this context for
+#     the same head SHA against the new base. Title/body edits also fire it;
+#     a redundant re-run is the intended cost.
+#   * The job `name:` is the status-check CONTEXT you require in branch
+#     protection. Keep it a stable literal ("Build Guard") — never an
+#     expression, or the required context name changes per run and can never
+#     be satisfied.
+#
+# CUSTOMIZE FREELY (safe to adapt to your project):
+#   * runs-on: swap the runner label for a self-hosted/larger runner.
+#   * timeout-minutes: raise/lower for your repo size.
+#   * ADD paths-filters ONLY with care. Filtering a REQUIRED check means PRs
+#     that touch no matching path never report the check and sit forever
+#     "Expected — Waiting for status". Recommended: do NOT paths-filter this
+#     workflow. If your team wants automerge without the guard blocking on
+#     kit-upgrade PRs (exit 2), use the two-context split documented in
+#     GUARD_SETUP.md instead of a paths-filter.
+# ---------------------------------------------------------------------------
+
+name: Build Guard
+
+# All PRs (no branch filter) plus merge-queue runs. Do not add a branches
+# filter unless you deliberately want some PRs unguarded.
+#
+# pull_request_target loads this YAML from the base branch. `edited` is
+# load-bearing, not cosmetic: it is the event a base retarget fires, and
+# without it the head SHA keeps the green this gate published for its former
+# base. The other three are GitHub's defaults, restated because naming `types`
+# at all replaces them.
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened, edited]
+  merge_group:
+
+# Cancel superseded runs: a new push to the same PR obsoletes the in-flight
+# run, and the required status is bound to the new head SHA, so canceling the
+# stale run cannot wedge the current head's check.
+# pull_request_target sets github.ref to the BASE branch, so the group must
+# key on the PR number (not github.ref) or every PR targeting the same base
+# would share one slot and cancel each other.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+# Least privilege: the gate only reads the tree and git history.
+# pull_request_target's default token is write-capable — this block is what
+# pins it to read. Do not add pull-requests: write or secrets.
+permissions:
+  contents: read
+
+jobs:
+  build-guard:
+    # This literal is the status-check context you require in branch
+    # protection. Keep it stable and expression-free.
+    name: Build Guard
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      # SHA-pinned (supply-chain): a mutable tag on a security-critical gate's
+      # own actions would let a retagged action compromise the gate.
+      # pull_request_target default ref is the base/default branch. Do not set
+      # `ref:` to the PR head — the workspace must stay the trusted base tree.
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          # Full history so the gate can compute the merge base. A shallow
+          # clone makes the gate fail closed, not pass silently.
+          fetch-depth: 0
+
+      # check.mjs requires Node >= 24; the runner's ambient node may be older.
+      # Pin the runtime explicitly so the gate never depends on image defaults.
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+        with:
+          node-version: '24'
+
+      - name: Run Build Guard (trusted base copy)
+        # Fail closed on every error, unset variable, and pipe failure.
+        run: |
+          set -euo pipefail
+
+          # Resolve the base BRANCH name for both event types. Fail closed if
+          # it cannot be determined (a missing base must never empty the diff
+          # and skip every check).
+          if [ "${GITHUB_EVENT_NAME}" = "pull_request_target" ]; then
+            # pull_request_target exposes the base branch directly.
+            BASE_BRANCH="${GITHUB_BASE_REF:?Error: GITHUB_BASE_REF is empty on a pull_request_target event}"
+            PR_SHA="$(jq -r '.pull_request.head.sha // empty' "${GITHUB_EVENT_PATH}")"
+            if [ -z "${PR_SHA}" ]; then
+              echo "Error: could not resolve pull_request.head.sha from the event payload (fail closed)." >&2
+              exit 1
+            fi
+            PR_NUMBER="$(jq -r '.pull_request.number // empty' "${GITHUB_EVENT_PATH}")"
+            if [ -z "${PR_NUMBER}" ]; then
+              echo "Error: could not resolve pull_request.number from the event payload (fail closed)." >&2
+              exit 1
+            fi
+          elif [ "${GITHUB_EVENT_NAME}" = "merge_group" ]; then
+            # merge_group leaves GITHUB_BASE_REF empty; the base branch lives in
+            # the event payload as merge_group.base_ref (a full ref like
+            # refs/heads/main). Strip the refs/heads/ prefix.
+            BASE_REF_FULL="$(jq -r '.merge_group.base_ref // empty' "${GITHUB_EVENT_PATH}")"
+            if [ -z "${BASE_REF_FULL}" ]; then
+              echo "Error: could not resolve merge_group.base_ref from the event payload (fail closed)." >&2
+              exit 1
+            fi
+            BASE_BRANCH="${BASE_REF_FULL#refs/heads/}"
+          else
+            echo "Error: unsupported event '${GITHUB_EVENT_NAME}' for the Build Guard gate (fail closed)." >&2
+            exit 1
+          fi
+
+          if [ -z "${BASE_BRANCH}" ]; then
+            echo "Error: base branch resolved empty (fail closed)." >&2
+            exit 1
+          fi
+
+          # Fetch the base branch so origin/<base> is resolvable for the diff.
+          git fetch --no-tags origin "+refs/heads/${BASE_BRANCH}:refs/remotes/origin/${BASE_BRANCH}"
+
+          # pull_request_target workspace is the base tree. Fetch the PR head
+          # SHA as a git object only (GitHub's pull ref, including forks) and
+          # point HEAD at that object so the gate diffs against it. Do not
+          # checkout the PR — that would replace the trusted workspace.
+          if [ "${GITHUB_EVENT_NAME}" = "pull_request_target" ]; then
+            git fetch --no-tags origin "+refs/pull/${PR_NUMBER}/head:refs/build/pr-head"
+            FETCHED_SHA="$(git rev-parse --verify "refs/build/pr-head^{commit}")"
+            if [ "${FETCHED_SHA}" != "${PR_SHA}" ]; then
+              echo "Error: fetched PR head ${FETCHED_SHA} does not match event sha ${PR_SHA} (fail closed)." >&2
+              exit 1
+            fi
+            git update-ref --no-deref HEAD "${PR_SHA}"
+          fi
+
+          # TRUSTED BASE: run the gate from the BASE branch's committed copy of
+          # check.mjs, never the PR's copy. A PR cannot strip its own
+          # guard-integrity check this way. RUNNER_TEMP (per-job temp dir,
+          # always set on GitHub runners) avoids the predictable shared /tmp
+          # path a concurrent process on a persistent self-hosted runner could
+          # race or pre-create.
+          git show "origin/${BASE_BRANCH}:.build-project/guard/check.mjs" > "${RUNNER_TEMP}/guard-check.mjs"
+
+          # Non-empty guard: an empty file would run as a silent pass under node.
+          test -s "${RUNNER_TEMP}/guard-check.mjs"
+
+          # Point the extracted gate at the trusted workspace guard dir (config).
+          # The workspace is the BASE checkout, so config is not
+          # PR-controlled. The gate diffs git objects (HEAD = PR sha vs base).
+          # The gate's exit code passes straight through:
+          #   0  clean.
+          #   1  hard finding (secret / artifact path) -> blocks.
+          #   2  ONLY guard-machinery changed (exit 2) -> also blocks this check.
+          # Exit 2 is expected on legitimate kit-upgrade PRs and means "a human
+          # should review the gate change". Teams that want such PRs to
+          # automerge should split contexts per GUARD_SETUP.md rather than
+          # weaken this required check. Never mask the gate's exit code (no
+          # error suppression, no `|| true`).
+          BUILD_GUARD_DIR="$PWD/.build-project/guard" node "${RUNNER_TEMP}/guard-check.mjs"