55 lines
1.5 KiB
Markdown
55 lines
1.5 KiB
Markdown
# Packer Specs
|
|
|
|
This directory contains the normative packer specification set.
|
|
|
|
## Purpose
|
|
|
|
Specs define the official packer contract.
|
|
|
|
They exist to make behavior, constraints, interfaces, and artifact guarantees stable across implementation and review.
|
|
|
|
The current domain also has a bootstrap draft in [`../Prometeu Packer.md`](../Prometeu%20Packer.md).
|
|
That draft can be used as source material, but long-term normative content should be decomposed into focused specs here.
|
|
|
|
## Expected Format
|
|
|
|
The exact structure may vary by document, but a packer 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:
|
|
|
|
- artifact schemas,
|
|
- invariants,
|
|
- diagnostic contracts,
|
|
- examples,
|
|
- migration notes,
|
|
- explicit TODO sections for tracked unresolved items.
|
|
|
|
## Writing Rules
|
|
|
|
- Write in normative language.
|
|
- Integrate only decisions that have already been closed.
|
|
- Keep debate history and option analysis out of the spec body.
|
|
- Preserve clear boundaries between adjacent packer 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. pull-request plans that define propagation,
|
|
4. then spec integration.
|
|
|
|
If a spec edit would require guessing an unresolved design choice, stop and surface the missing decision first.
|