# PBS Pull Requests

This directory contains self-contained PBS change proposals for review.

## Purpose

A pull request document packages a proposed change so it can be reviewed as a coherent unit before final integration.

Use this directory when a change:

- touches multiple documents,
- changes architecture or semantics,
- needs explicit review criteria,
- or should be assessed before editing the final normative corpus.

Architecture and decisions come before implementation.

## Required Properties

Every pull request document must be self-contained.

A reviewer should be able to understand the proposal without reconstructing context from chat history or scattered notes.

## Required Sections

Each pull request should include, at minimum:

1. Briefing
2. Target
3. Method
4. Acceptance Criteria
5. Tests, when needed

Recommended additional sections:

6. Motivation
7. Scope
8. Non-Goals
9. Affected Documents
10. Open Questions

## Section Expectations

### Briefing

Summarize the problem and the proposed change in a short, readable form.

### Target

State exactly what documents, behaviors, or contracts the proposal changes.

### Method

Explain the architectural and editorial approach.
If the proposal depends on prior decisions, name them explicitly.

### Acceptance Criteria

List the conditions that must be true for the proposal to be accepted.
These should be specific and reviewable.

### Tests

Include tests when the change affects executable behavior, conformance, verification, lowering, or observable runtime semantics.

If tests are not necessary, say why.

## Writing Rules

- Keep the proposal self-contained.
- Prefer explicit architectural reasoning over implementation detail.
- Do not bury acceptance criteria inside prose.
- Do not assume unresolved details.
- If a required decision is missing, stop and raise the question instead of inferring an answer.

## Review Rule

A pull request may propose implementation consequences, but it must not smuggle in unresolved architectural choices as implementation details.