Skip to main content

ADR-0023: Pull requests as architecture control points

  • Status: Accepted
  • Date: 2026-07-17
  • Deciders: Michel Gillet

Context​

AI-assisted development can generate, refactor, and validate routine implementation changes at high speed. That invites the claim that pull requests (PRs) — or merge requests — are obsolete. That claim is only partly true: it applies mainly to high-volume, low-architecture changes that tools can gate.

What does not go away is architectural control. A2C records ASRs and ADRs as first-class artifacts (ADR-0019, ADR-0020). Non-trivial ASR changes require ADRs; Accepted decisions evolve via amend or supersede (ADR-0021). Those events need a human review checkpoint.

Without an explicit role for PRs, teams either over-review every AI code tweak or under-review changes that alter architectural intent.

Decision​

  1. PRs remain the primary architecture control point in A2C-governed repositories (GitLab merge requests, GitHub pull requests, or equivalent).

  2. Highest-priority PRs are those that:

    • Add, amend, supersede, deprecate, or remove ASRs
    • Add, amend, supersede, reject, or deprecate ADRs
    • Change optional Specs/Contracts in ways that alter architectural intent
    • Ship implementation that realizes new or changed ASRs/ADRs (explicitly referencing those IDs)

  3. Review focus for architecture PRs: validity of the ASR/ADR, justification of the decision or amendment, and whether implementation respects the contracts — not line-by-line style on generated boilerplate when automated checks already cover it.

  4. ASR change rule (restated for PR practice): non-trivial ASR edits land in the same PR as the corresponding ADR (ADR-0019 / ADR-0021). No implementation-only PR may silently change architectural intent by editing ASRs without a decision record.

  5. Routine implementation PRs may be lighter-weight as AI and CI absorb mechanical work. That does not remove the need for architecture PRs; it concentrates human attention where drift risk is highest.

  6. Narrative detail for operators and AI agents belongs in the upcoming workflow note (docs/workflow/asr-adr-pr-governance.md, batch-intake-03). This ADR is the binding decision.

Consequences​

Positive​

  • Durable, defensible role for PRs in AI-assisted A2C workflows
  • Clear priority for reviewers and release gates
  • Reinforces ASR/ADR change control at the merge boundary
  • Reduces pressure to treat every micro-diff as equal review cost

Negative​

  • Teams must still define local review checklists and branch protection
  • Risk of labeling every PR “architecture” without substance — reviewers should insist on ASR/ADR IDs when intent changes
  • Workflow note and AI rules updates still needed for day-to-day prompting

References​

Amends​

  • (none)

Amended by​

  • (none)

Supersedes​

  • (none)

Superseded by​

  • (none)