packer base structure

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/`.

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.

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.

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.

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.

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.