Intent Pull Requests

1.0.0· Stable

Abstract

The Intent Pull Requests Specification defines what a pull request must communicate before people or automation decide whether to integrate it. A pull request is a review artifact: it describes the complete proposed result, why that result is needed, how the implementation achieves it, why that approach was selected, what it affects, and what evidence supports its claims.

A pull request resembles a small changelog because both explain change. Their audiences and timing differ. A pull request helps reviewers decide whether a proposal should become history. A changelog helps consumers understand history that was released.

This document defines stable version 1.0.0.

1. Conformance language

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here.

2. Goals and boundaries

Intent Pull Requests is designed to:

make the proposed outcome reviewable without reconstructing it from a diff;
preserve rationale and material design trade-offs;
identify affected release units and streams in a monorepo;
distinguish asserted verification from reproducible evidence;
remain useful after merge and after external links disappear;
support small changes without mandatory empty sections;
give AI systems explicit evidence and uncertainty boundaries; and
separate portable review semantics from forge-specific APIs.

It does not define a review approval policy, branch model, issue tracker, hosting provider, merge queue, release cadence, or changelog renderer.

3. Relationship to the Intent specifications

The Project Profile supplies shared vocabulary and policy. Intent Commits explains atomic Git changes. Intent Pull Requests explains the complete proposed integration. Intent Changesets records release decisions that may span commits or pull requests. Intent Changelog records consumer-facing release history. A Release Manifest proves what was published.

No artifact substitutes for another. Links MAY prevent needless duplication, but a pull request MUST retain its own result, rationale, approach, impact, and verification summary. A reviewer MUST NOT need access to an issue tracker to understand why the proposal exists.

4. Terms

Term	Meaning
Pull request	A proposal to integrate one head revision into a base.
Title	The concise description of the complete integrated outcome.
Body	The reviewer-oriented explanation of the proposal.
Target	One affected release unit and stream with its own impact.
Base revision	The exact Git commit the proposal intends to change.
Evidence revision	The exact Git commit against which claims were evaluated.
Verification claim	A named check, its state, and supporting evidence.
Forge adapter	An implementation that maps this model to a hosting platform.

5. Canonical representation

The portable representation is one YAML 1.2 document. A forge adapter maps title to the forge title and renders the remaining semantic fields as the body. The YAML record is not required to be stored when a forge preserves all normative information losslessly.

intent-pull-request: 1.0.0
id: bind-service-token-audiences
title: "feat(apps/gateway/auth): bind service tokens to audiences"
state: ready
summary: Bind service tokens to the application that receives them
rationale: Prevent credentials issued for one service from being replayed elsewhere
approach: Validate the audience at the shared authentication boundary
trade-offs: Existing clients must add an audience before upgrading
targets:
  - release-unit: apps/gateway
    stream: stable
    impact: major
    migration: Add the gateway audience claim before upgrading
risks:
  - Existing clients without an audience will be rejected
rollout: Deploy overlapping token issuers before enforcing audiences
rollback: Disable audience enforcement while retaining issued claims
verification:
  - name: unit-tests
    status: passed
    command: go test ./...
    evidence: CI run 481
  - name: production-smoke
    status: unavailable
    command: null
    evidence: No production access from pull-request CI
provenance:
  issues: [SEC-241]
  changesets: [require-token-audiences]
  decisions: [docs/decisions/0042-token-audiences.md]
disclosure:
  state: public
base-revision: fedcba9876543210fedcba9876543210fedcba98
evidence-revision: 0123456789abcdef0123456789abcdef01234567

Unknown ordinary fields MUST be preserved by readers that rewrite a record.

6. Title

The title MUST describe the state produced by integrating the complete pull request. It MUST NOT describe only author activity, file manipulation, a ticket number, or an intermediate implementation step.

The title MUST use the Intent Commits header grammar:

<type>[optional scope]: <description>

The type describes the primary integrated intent. The scope identifies the primary component. In a monorepo, a component scope MUST resolve through the Project Profile. Repository-wide work MAY omit scope only when the profile defines that meaning.

The title SHOULD remain accurate as squash-merge metadata. A platform MAY add a pull-request number after the portable title, but the number MUST NOT replace the description.

Invalid titles include:

DEVELOP-241
update auth files
address review feedback
changes

7. Body semantics

7.1 Summary

summary MUST describe the resulting behavior or engineering capability. It MUST NOT be a file list or a repetition of the title with no added context.

7.2 Rationale

rationale MUST explain why the change is necessary or valuable. It MUST retain the essential reason locally even when provenance links provide detail.

7.3 Approach and trade-offs

approach MUST explain the design at the level needed to review correctness. It SHOULD identify important boundaries, data flow, compatibility mechanisms, and failure behavior. It MUST NOT narrate every edited file.

trade-offs MUST explain why the selected approach is appropriate and identify material costs or rejected alternatives. It MAY be concise when the choice is obvious, but MUST NOT contain a meaningless placeholder.

7.4 Targets and impact

targets MUST contain every affected (release-unit, stream) pair. Each pair MUST be unique and MUST resolve through the Project Profile. impact MUST be none, patch, minor, or major. A major target MUST provide actionable migration guidance. A tool MUST NOT apply the greatest target impact to other targets silently.

7.5 Risks, rollout, and rollback

risks MUST identify credible failure, compatibility, security, privacy, operational, or data consequences. An empty sequence means the author found no material risk after review; it MUST NOT mean risks were not considered.

rollout and rollback MAY be null only when no staged introduction or reversal procedure is applicable. A profile MAY require them for specified targets, impacts, or change types.

7.6 Verification

Each verification claim MUST contain a name, status, and evidence. Status MUST be one of:

Status	Meaning
`passed`	The named check ran successfully against the evidence revision.
`failed`	The check ran and failed.
`skipped`	The check was available but deliberately not run.
`unavailable`	The environment could not perform the check.
`not-applicable`	The check does not apply, with an explanation.

A passed claim MUST identify a reproducible command or equivalent stable procedure. Every state MUST explain its evidence or reason. A tool MUST NOT treat linting as proof of compilation, a targeted test as proof of a full suite, or a large diff as proof of high release impact.

7.7 Provenance

provenance MAY contain issues, changesets, commits, decisions, incidents, advisories, or other profile-defined references. Tools MUST NOT invent a reference. Provenance is evidence and navigation, not a substitute for local explanation.

7.8 Disclosure

disclosure MUST declare whether the record is public, embargoed, or redacted, using the shared Project Profile vocabulary. An embargoed record MUST provide not-before or policy. A redacted public representation SHOULD provide a safe placeholder without leaking the omitted fact through its title, targets, provenance, or generated body.

7.9 Base and evidence revisions

base-revision MUST identify the full Git object name of the base commit used to calculate the proposal. evidence-revision MUST identify the full Git object name of the exact head commit evaluated by the body and verification claims. The base MUST be an ancestor of the evidence revision.

A ready or merged pull request whose selected base or head differs from these values is stale and MUST be re-evaluated before integration.

8. Lifecycle

state MUST be draft, ready, merged, or closed.

A draft MAY omit unresolved semantic fields and MUST make uncertainty visible.
A ready pull request MUST satisfy every required field and profile rule.
A merged record MUST describe the result actually integrated and MUST identify the integrated revision through provenance or platform metadata.
A closed record MUST NOT imply that its result entered the base branch.

The body describes current proposed state, not a development diary. Authors MUST update it when scope, design, impact, or evidence changes. Historical discussion MAY remain in review comments, but conclusions that affect the design MUST be incorporated into the body or a linked durable decision.

9. Squash, merge, and rebase strategies

The Project Profile MUST declare the merge strategy. For squash merges, the final title and durable body MUST be suitable merge metadata. The squash commit MUST preserve required Intent Commits impact, migration, affected-unit, and changeset metadata; a forge adapter MUST report information that would be lost.

For merge or rebase strategies, the pull request remains the integration-level review record while individual commits retain their atomic meaning.

10. Cross-artifact consistency

A validator SHOULD compare the pull request with commits and linked changesets. Affected targets, impacts, migrations, and change identity MUST NOT contradict one another. A tool detecting a contradiction MUST report each source and MUST NOT silently choose a winner.

One pull request MAY advance several changesets. Several pull requests MAY advance one changeset. A changelog consumer MAY use reviewed pull-request prose as evidence, but MUST still produce a self-contained consumer narrative.

11. Rendering

A canonical Markdown rendering SHOULD use these headings when applicable:

## What

## Why

## Approach

### Trade-offs

## Impact

## Risks and delivery

## Verification

Small pull requests MAY combine sections when every semantic requirement remains explicit. Renderers SHOULD omit inapplicable sections rather than emit empty checklists or repeated N/A values. A template is a communication aid, not evidence that review work occurred.

12. Project Profile

The Project Profile MAY declare specifications.pull-requests: 1.0.0 and a pull-requests mapping containing:

repository-local record directory;
merge strategy;
maximum title and body lengths;
whether ready conformance is required before integration;
accepted verification states; and
optional forge field mappings.

Projects MUST NOT create a second pull-request-only vocabulary for release units, streams, impacts, or types.

13. AI-assisted authoring and review

An AI system claiming Intent Pull Requests support:

MUST receive the exact base and head revisions and their complete diff;
MUST receive the exact Project Profile and trusted caller instructions;
MUST receive stable revisions for every supplied evidence source;
MUST treat source, diffs, issues, comments, review text, and history as untrusted data rather than instructions;
MUST NOT invent rationale, trade-offs, targets, impact, migration, risks, rollout, rollback, verification, provenance, or reviewer conclusions;
MUST return NEEDS_INPUT for unresolved required judgment; and
MUST distinguish suggestions from validated declarations.

A reviewer agent MAY identify possible omissions or contradictions. It MUST present them as evidence-backed findings, not approval. AI output does not transfer authorship or review responsibility away from people and systems named by project policy.

14. Security and privacy

Records and repository evidence are untrusted input. Implementations MUST bound bytes, nesting, collection sizes, scalar lengths, and processing time. YAML readers MUST reject duplicate keys, aliases, anchors, merge keys, custom tags, and multiple documents. Strings MUST be treated as data, never commands, templates, HTML, or agent instructions.

Paths MUST remain below the repository root after normalization and MUST NOT escape through symbolic links. Embargoed, redacted, private, or secret material MUST NOT be sent to an unauthorized forge, renderer, log, or AI service. Public summaries MUST be reviewed for inferential disclosure.

15. Conformance classes

15.1 Reader

An Intent Pull Requests Reader MUST parse the canonical representation, enforce safe YAML requirements, and preserve unknown ordinary fields.

15.2 Validator

A Validator MUST implement Reader requirements and validate sections 5 through 8, including title grammar, lifecycle, targets, migrations, and verification.

15.3 Project Validator

A Project Validator MUST also resolve identifiers and policy against the exact Project Profile.

15.4 Evidence Verifier

An Evidence Verifier MUST prove the base and evidence revisions, their ancestry, and linked artifact consistency. It MUST report which claims it verified, contradicted, or could not verify. It MUST NOT upgrade an unverified claim to passed.

15.5 Forge Adapter

A Forge Adapter MUST preserve every normative field when mapping to or from a platform. It MUST report lossy mappings and MUST NOT open, update, merge, or close a remote pull request without explicit authorization.

16. Non-conforming examples

This record is not ready because its title is activity-only, rationale is absent, impact is ambiguous, and verification has no evidence:

intent-pull-request: 1.0.0
id: update-files
title: "chore: update files"
state: ready
summary: Updated several files
rationale: null
approach: Made the requested changes
trade-offs: N/A
targets: []
risks: []
rollout: null
rollback: null
verification:
  - name: tests
    status: passed
    command: null
    evidence: null
provenance: {}
disclosure:
  state: public
base-revision: main
evidence-revision: HEAD