Embedding Build Intent Checks into Pull‑Request Templates

The unchecked write

In many repositories agents have been granted push rights without a concrete gate between the moment an agent decides to make a change and the moment that change is merged. The result is a stream of commits that have never been examined for licensing compliance, for required build‑intent metadata, or for the invariants enforced by the MCP server. When a bot pushes directly to the default branch, the only safety net is a post‑hoc review that may already be too late: the change is live, the build may have already been triggered, and any breach of the licensing gate can propagate downstream. The failure mode is clear – the governance point is missing, not the model that suggested the change.

Why a build intent check belongs in the PR

The Build Intent gate is the single place where the library validates that a proposed write satisfies both the functional contract and the licensing invariants. The gate does not rely on any model output; it is a deterministic, repeatable check that either accepts the proposal and returns a terminal state, or rejects it with a clear reason. Embedding the same check into a pull‑request (PR) template forces every agent‑generated change to be pre‑approved. The PR becomes the visible manifestation of the gate: before a reviewer can even consider the diff, the template must contain a build‑intent token that the MCP server has already validated. This token is the proof that the licensing gate has been crossed and that the agent’s intent is known.

By treating the PR template as a gate, you also gain an audit trail. The build‑intent token is stored in the PR metadata, so later audits can verify that the exact same invariants were satisfied at the time of submission. The approach aligns with the guidance in the pillar article "Governing code agents at the Build Intent gate", which stresses that the gate should be the only place an agent can cross from intent to write.

Embedding the check in a PR template

The template needs only a single placeholder for the build‑intent token and a short instruction that the token must be generated via the MCP server before the PR is opened. A minimal example looks like this:

## Build Intent Verification

<!-- Replace the placeholder with the token returned by the MCP server -->
Build‑Intent‑Token: `{{BUILD_INTENT_TOKEN}}`

The token proves that the proposed change complies with the licensing gate and the repository’s invariants.

When an automation script creates a change, it first calls the MCP server (or the equivalent HTTP API) with the proposed diff. The server returns a terminal state and a token if the proposal passes. The script then populates the PR template with that token and opens the PR. Human reviewers see the token and can optionally verify it against the MCP server’s public endpoint, but the merge button is disabled by the CI pipeline until the token is present and matches the server’s record.

The CI step that enforces the presence of the token is tiny:

steps:
  - name: Verify Build Intent
    run: |
      token=$(git log -1 --pretty=%B | grep -oP 'Build‑Intent‑Token: `\K[^`]+')
      if ! curl -sSf "https://mcp.example.com/verify/$token" | grep -q 'VALID'; then
        echo "Missing or invalid Build Intent token"
        exit 1
      fi

If the token is missing or invalid, the pipeline fails, preventing the merge. The check is deterministic and repeatable; it does not depend on any AI model, only on the stored invariants and the licensing gate.

Rolling it out on Monday

Start by adding the template to the repository’s .github/PULL_REQUEST_TEMPLATE.md (or the equivalent location for your platform). Update your automation that generates agent‑driven changes to call the MCP endpoint before opening a PR and to inject the returned token into the template. Add the CI verification step to your existing pipeline, making it a required check for all PRs. Finally, communicate the new requirement to the team: “Every agent‑generated change must include a Build Intent token. The CI will reject any PR that does not comply.”

Within a single sprint you will have closed the gap between decision and write. The licensing gate will be enforced uniformly, and the build‑intent verification will become part of the normal code‑review workflow rather than a separate, optional step. The result is a concrete, repeatable control point that stops blind agent writes at the earliest possible moment.