add README files to improve documentation organization and structure

docs/pbs/README.md

@@ -0,0 +1,87 @@
+# 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.
+
+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 normative contract.
+- `pull-requests/` stores reviewable change packages.

docs/pbs/agendas/README.md

@@ -0,0 +1,46 @@
+# PBS Agendas
+
+This directory contains active PBS discussion agendas.
+
+## Purpose
+
+An agenda exists to drive a decision, not to serve as final normative text.
+
+Use an agenda when:
+
+- the topic is still open,
+- multiple options or tradeoffs must be evaluated,
+- the scope and non-goals need to be made explicit,
+- the order of discussion matters.
+
+Remove an agenda from this directory once the topic is no longer active.
+
+## Expected Format
+
+An agenda should usually include:
+
+1. Title
+2. Status
+3. Purpose
+4. Context
+5. Decisions to Produce
+6. Core Questions
+7. Expected Spec Material
+8. Non-Goals
+9. Inputs
+
+## Writing Rules
+
+- Keep the document oriented around unresolved questions.
+- Separate open questions from assumptions already fixed elsewhere.
+- Name the concrete decisions the discussion must produce.
+- Avoid drafting large blocks of final normative spec text here.
+- Prefer explicit non-goals to prevent scope drift.
+
+## Exit Rule
+
+An agenda should move out of the active set when:
+
+- the key questions have been answered,
+- the architectural direction is clear enough to record,
+- and the topic is ready to become a decision record and then a spec update.

docs/pbs/decisions/README.md

@@ -0,0 +1,44 @@
+# PBS Decisions
+
+This directory contains PBS decision records.
+
+## Purpose
+
+A decision record is the bridge between agenda discussion and normative spec text.
+
+Use this directory to capture:
+
+- what was decided,
+- why that direction was chosen,
+- which constraints now apply,
+- what remains intentionally out of scope,
+- which specs must be updated.
+
+Architecture and decisions must be resolved before implementation.
+
+## Expected Format
+
+A decision record should usually include:
+
+1. Title
+2. Status
+3. Date or Cycle
+4. Context
+5. Decision
+6. Invariants
+7. Explicit Non-Decisions
+8. Spec Impact
+9. Validation Notes or Examples
+
+## Writing Rules
+
+- Write in stable, reviewable language.
+- State the adopted decision first and clearly.
+- Capture architectural constraints and invariants explicitly.
+- Record what is still not decided so later implementation does not guess.
+- Point to the exact specs that need integration.
+
+## Implementation Rule
+
+If implementation work exposes a missing decision, do not infer it.
+Stop, surface the ambiguity, and return it to agenda or decision review.

docs/pbs/pull-requests/README.md

@@ -0,0 +1,78 @@
+# 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.

docs/pbs/specs/README.md

@@ -0,0 +1,48 @@
+# PBS Specs
+
+This directory contains the normative PBS specification set.
+
+## Purpose
+
+Specs define the official PBS contract.
+
+They exist to make behavior, constraints, and interfaces stable across implementations and reviews.
+
+## Expected Format
+
+The exact structure may vary by document, but a spec should usually contain:
+
+1. Title
+2. Status
+3. Scope or Applies To
+4. Purpose
+5. Authority and Precedence
+6. Normative Inputs
+7. Core Rules
+8. Non-Goals
+9. Exit Criteria
+
+Some specs may also include:
+
+- already-settled inputs,
+- initial section targets,
+- `TODO` sections for tracked unresolved items,
+- cross-references to adjacent specs.
+
+## Writing Rules
+
+- Write in normative language.
+- Integrate only decisions that have already been closed.
+- Keep debate history and exploratory alternatives out of the spec body.
+- Preserve clear boundaries between adjacent specs.
+- Use `TODO` only for explicitly tracked unresolved items, not as a substitute for agenda work.
+
+## Upstream Rule
+
+Specs should normally be fed by:
+
+1. agendas that frame the open topic,
+2. decisions that close the architectural question,
+3. then spec integration.
+
+If a spec edit would require guessing an unresolved design choice, the correct action is to stop and surface the missing decision first.