# PBS Documentation

This directory contains the working and normative documentation for PBS.

## Tree

```text
docs/pbs/
├── agendas/
├── decisions/
├── pull-requests/
└── specs/
```

## Responsibilities

### `agendas/`

`agendas/` contains open topics.

Use it to:

- record unresolved questions,
- define scope, dependencies, and non-goals,
- structure discussion order,
- keep only active TODO topics visible.

An agenda is a discussion artifact, not a final normative document.
Once a topic is settled, it should leave this directory.

### `decisions/`

`decisions/` contains closed decision records between discussion and spec integration.

Use it to:

- record the adopted decision clearly,
- capture invariants and architectural constraints,
- state what was explicitly left undecided,
- identify which specs must be updated,
- preserve traceability without turning specs into debate logs.

Architecture and decisions come before implementation.

### `specs/`

`specs/` contains the normative PBS corpus.

Use it to:

- consolidate the official PBS contract,
- integrate already-closed decisions in normative language,
- define precedence, scope, rules, and exit criteria,
- provide the baseline for implementation, verification, and conformance.

`docs/pbs/specs` is language-specific.
Cross-language acceptance specs live in `docs/general/specs`.

Specs must not operate as discussion backlogs.
If a point is still disputed or underspecified, it belongs in `agendas/` or `decisions/`, not directly in `specs/`.

### `pull-requests/`

`pull-requests/` contains self-contained change proposals for review.

Use it to:

- package a proposed change across multiple documents,
- explain motivation, target, method, acceptance criteria, and tests,
- make the review surface explicit before final integration,
- keep architectural and decision-level review ahead of implementation work.

If implementation reveals an unresolved ambiguity, stop and ask the question explicitly.
Do not infer missing architectural decisions during implementation.

## Recommended Flow

The preferred pipeline is:

1. `agendas/`: open and discuss unresolved topics.
2. `decisions/`: record the decision and its constraints.
3. `specs/`: integrate the closed decision into normative text.
4. `pull-requests/`: use when a change should be reviewed as a self-contained proposal before merge.

## Practical Rule

- `agendas/` stores open questions.
- `decisions/` stores closed answers.
- `specs/` stores the PBS-specific normative contract.
- `pull-requests/` stores reviewable change packages.