From d95dfa296cf0c3664fb4777fad0fd9e8bfaa8e17 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Wed, 11 Mar 2026 05:26:15 +0000 Subject: [PATCH] packer base structure --- docs/packer/README.md | 116 ++++++++++++++++++++++++++++ docs/packer/agendas/README.md | 47 +++++++++++ docs/packer/decisions/README.md | 44 +++++++++++ docs/packer/learn/README.md | 47 +++++++++++ docs/packer/pull-requests/README.md | 57 ++++++++++++++ docs/packer/specs/README.md | 54 +++++++++++++ 6 files changed, 365 insertions(+) create mode 100644 docs/packer/README.md create mode 100644 docs/packer/agendas/README.md create mode 100644 docs/packer/decisions/README.md create mode 100644 docs/packer/learn/README.md create mode 100644 docs/packer/pull-requests/README.md create mode 100644 docs/packer/specs/README.md diff --git a/docs/packer/README.md b/docs/packer/README.md new file mode 100644 index 00000000..7b006cac --- /dev/null +++ b/docs/packer/README.md @@ -0,0 +1,116 @@ +# Packer Documentation + +This directory contains the working, planning, and normative documentation for the `packer` domain. + +`packer` is a standalone domain. It follows the same documentary cycle used elsewhere in the repository: + +`agendas -> decisions -> pull-requests -> specs -> learn` + +## Tree + +```text +docs/packer/ +├── agendas/ +├── decisions/ +├── learn/ +├── pull-requests/ +├── specs/ +├── Prometeu Packer.md +└── README.md +``` + +## Responsibilities + +### `Prometeu Packer.md` + +`Prometeu Packer.md` is the current bootstrap specification for the domain. + +Use it to: + +- understand the current packer scope, +- recover the initial architecture and terminology, +- seed the split into smaller normative specs under `specs/`. + +This document is useful as a draft source, but it should not become a permanent dumping ground for every future change. + +### `agendas/` + +`agendas/` contains open packer topics. + +Use it to: + +- frame unresolved problems, +- compare options and tradeoffs, +- define scope and non-goals, +- drive discussions toward a decision. + +An agenda is a discussion artifact, not a final contract. + +### `decisions/` + +`decisions/` contains closed packer decision records. + +Use it to: + +- record the chosen direction, +- capture constraints and invariants, +- state what remains intentionally out of scope, +- identify which specs, plans, or code paths must be updated. + +Decisions close debate. They are not brainstorming notes. + +### `pull-requests/` + +`pull-requests/` contains self-contained execution proposals. + +Use it to: + +- package a change for review, +- plan propagation across specs and implementation, +- define acceptance criteria, +- make tests and risks explicit before editing code or final specs. + +### `specs/` + +`specs/` contains the normative packer corpus. + +Use it to: + +- consolidate the official packer contract, +- split large draft material into stable chaptered specs, +- define behavior, constraints, interfaces, and conformance expectations. + +Specs should only absorb already-closed decisions. + +### `learn/` + +`learn/` contains didactic consolidation. + +Use it to: + +- explain why the packer works the way it does, +- preserve hard-won operational knowledge, +- teach future contributors the model, pitfalls, and expected workflows, +- reorganize accumulated knowledge into a cleaner learning surface. + +`learn/` is not an archive of old decisions. + +## Recommended Flow + +The preferred packer documentation flow is: + +1. `agendas/`: open and shape the unresolved topic. +2. `decisions/`: close the architectural choice. +3. `pull-requests/`: plan how the decision will be propagated. +4. `specs/`: integrate the decision into normative text. +5. `learn/`: consolidate the final knowledge in a didactic form. + +## Practical Rule + +- `agendas/` stores open questions. +- `decisions/` stores closed answers. +- `pull-requests/` stores execution plans. +- `specs/` stores the normative packer contract. +- `learn/` stores teaching-oriented consolidation. + +If implementation exposes a missing architectural choice, stop and return to `agendas/` or `decisions/`. diff --git a/docs/packer/agendas/README.md b/docs/packer/agendas/README.md new file mode 100644 index 00000000..45ba0cc8 --- /dev/null +++ b/docs/packer/agendas/README.md @@ -0,0 +1,47 @@ +# Packer Agendas + +This directory contains active packer discussion agendas. + +## Purpose + +An agenda exists to drive a decision. + +Use an agenda when: + +- the packer topic is still open, +- multiple options or tradeoffs must be evaluated, +- scope and non-goals need to be made explicit, +- the order of discussion matters, +- the team still needs a recommendation before committing direction. + +An agenda should help the reader converge, not just accumulate notes. + +## Expected Format + +A packer agenda should usually include: + +1. Title +2. Status +3. Purpose +4. Context +5. Options +6. Tradeoffs +7. Recommendation +8. Open Questions +9. Expected Follow-up + +## Writing Rules + +- Keep the document centered on unresolved questions. +- State the concrete decision the discussion is trying to produce. +- Prefer explicit tradeoffs over vague option lists. +- Avoid drafting large blocks of final normative spec text here. +- Be specific about packer scope: asset workspace, build artifacts, diagnostics, registry, builder boundary, and related contracts. + +## Exit Rule + +An agenda should leave the active set when: + +- the main tradeoffs are understood, +- a recommendation is clear enough to adopt, +- and the topic is ready to become a decision record. diff --git a/docs/packer/decisions/README.md b/docs/packer/decisions/README.md new file mode 100644 index 00000000..e07fbaaf --- /dev/null +++ b/docs/packer/decisions/README.md @@ -0,0 +1,44 @@ +# Packer Decisions + +This directory contains packer decision records. + +## Purpose + +A decision record is the bridge between packer discussion and packer execution. + +Use this directory to capture: + +- what was decided, +- why that direction was chosen, +- which constraints now apply, +- what remains intentionally undecided, +- which specs, plans, tests, or implementations must be updated. + +A decision should be stable enough that a spec or implementation worker can act on it without reconstructing the original debate. + +## Expected Format + +A packer decision should usually include: + +1. Title +2. Status +3. Date or Cycle +4. Context +5. Decision +6. Invariants and Constraints +7. Explicit Non-Decisions +8. Propagation Targets +9. Validation Notes or Examples + +## Writing Rules + +- State the adopted decision early and clearly. +- Write in stable language, not in exploratory tone. +- Capture architectural constraints explicitly. +- Record what is still not decided so later work does not guess. +- Point to the exact packer specs, PRs, or code areas that need propagation. + +## Implementation Rule + +If implementation work reveals a missing decision, do not infer it. +Return the issue to agenda or decision review. diff --git a/docs/packer/learn/README.md b/docs/packer/learn/README.md new file mode 100644 index 00000000..67de3f08 --- /dev/null +++ b/docs/packer/learn/README.md @@ -0,0 +1,47 @@ +# Packer Learn + +This directory contains didactic packer knowledge. + +## Purpose + +`learn/` exists to teach, not merely to store historical leftovers. + +Use it to: + +- explain packer architecture in a way new contributors can absorb quickly, +- consolidate conclusions from completed decisions and PRs, +- document common pitfalls and anti-patterns, +- connect normative specs to practical reasoning and implementation reality. + +## What Belongs Here + +A `learn` artifact should usually include: + +1. the original problem, +2. the decision that resolved it, +3. the implemented or specified final model, +4. practical examples, +5. common mistakes and warnings, +6. links to the relevant specs and PRs. + +Good `learn` material reduces onboarding time and prevents the same architectural confusion from repeating. + +## Writing Rules + +- Prefer didactic structure over chronological accumulation. +- Explain why the model exists, not only what it is. +- Keep terminology aligned with packer specs. +- Refactor older material when the directory starts feeling like a document graveyard. + +## Refactor Rule + +This directory should be periodically reorganized for better presentation. + +If content grows, prefer: + +- thematic grouping, +- overview documents, +- explicit learning paths, +- and consolidation of duplicated explanations. + +The goal is a maintainable learning surface, not a passive archive. diff --git a/docs/packer/pull-requests/README.md b/docs/packer/pull-requests/README.md new file mode 100644 index 00000000..76587e1c --- /dev/null +++ b/docs/packer/pull-requests/README.md @@ -0,0 +1,57 @@ +# Packer Pull Requests + +This directory contains self-contained packer change proposals for review. + +## Purpose + +A pull request document packages a packer change as an executable plan before final integration. + +Use this directory when a change: + +- touches multiple documents or code paths, +- changes packer architecture or semantics, +- needs explicit acceptance criteria, +- affects diagnostics, build outputs, registry rules, or builder boundaries, +- should be reviewed before editing the final normative corpus or implementation. + +## Required Properties + +Every pull request document must be self-contained. + +A reviewer should be able to understand: + +- the problem, +- the target state, +- the execution method, +- the acceptance bar, +- and the validation surface. + +## Required Sections + +Each packer pull request should include, at minimum: + +1. Briefing +2. Target +3. Method +4. Acceptance Criteria +5. Tests or Validation + +Recommended additional sections: + +6. Motivation +7. Scope +8. Non-Goals +9. Affected Documents +10. Open Questions + +## Writing Rules + +- Keep the proposal self-contained and reviewable. +- Separate architectural reasoning from implementation detail. +- Make packer outputs and contracts explicit. +- Do not smuggle unresolved product or architecture choices into implementation steps. +- If a required decision is missing, stop and raise it instead of guessing. + +## Review Rule + +A pull request may plan code and spec consequences, but it must not replace a missing decision record. diff --git a/docs/packer/specs/README.md b/docs/packer/specs/README.md new file mode 100644 index 00000000..b61cc6f2 --- /dev/null +++ b/docs/packer/specs/README.md @@ -0,0 +1,54 @@ +# 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.