prometeu-studio/docs/specs/packer

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 packer normative content is maintained directly in this specs/ corpus.

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.

Current Corpus

The current packer core corpus is:

1. 1. Domain and Artifact Boundary Specification.md
2. 2. Workspace, Registry, and Asset Identity Specification.md
3. 3. Asset Declaration and Virtual Asset Contract Specification.md
4. 4. Build Artifacts and Deterministic Packing Specification.md
5. 5. Diagnostics, Operations, and Studio Integration Specification.md
6. 6. Versioning, Migration, and Trust Model Specification.md

Reading Order

Recommended order:

1. domain and artifact boundary;
2. workspace and identity;
3. asset declaration;
4. build artifacts;
5. diagnostics and Studio operation model;
6. versioning and trust.