prometeu-studio/docs/packer/pull-requests/README.md

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 shipper 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.

Production Sequence

The current production track for the standalone prometeu-packer project is:

1. PR-01-packer-project-bootstrap-and-module-boundaries.md
2. PR-02-workspace-init-registry-and-identity-foundation.md
3. PR-03-asset-declaration-parsing-validation-and-details-contract.md
4. PR-04-workspace-scan-list-assets-and-studio-read-adapter.md
5. PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md
6. PR-06-doctor-diagnostics-and-safe-fix-baseline.md
7. PR-07-build-plan-determinism-and-cache-key-foundation.md
8. PR-08-assets-pa-and-companion-artifact-emission.md
9. PR-09-event-lane-progress-and-studio-operational-integration.md
10. PR-10-versioning-migration-trust-and-production-gates.md
11. PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md
12. PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md
13. PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md
14. PR-14-project-runtime-core-snapshot-model-and-lifecycle.md
15. PR-15-snapshot-backed-asset-query-services.md
16. PR-16-write-lane-command-completion-and-used-write-services.md
17. PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md
18. PR-18-legacy-service-retirement-and-regression-hardening.md
19. PR-19-api-surface-audit-model-separation-and-public-read-dtos.md
20. PR-20-asset-action-capabilities-and-register-first-delivery.md
21. PR-21-point-in-memory-snapshot-updates-after-write-commit.md
22. PR-22-delete-asset-action-confirmation-and-fs-first-manifest-removal.md
23. PR-23-move-asset-action-wizard-and-fs-first-relocation.md
24. PR-24-asset-file-cache-hydration-and-walker-reuse.md
25. PR-25-asset-cache-model-and-repository.md
26. PR-26-walker-cache-input-and-comparison-policy.md
27. PR-27-runtime-walkresult-and-cache-integration.md
28. PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md
29. PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md
30. PR-30-pack-wizard-summary-snapshot-query.md
31. PR-31-pack-wizard-validation-snapshot-gate.md
32. PR-32-palette-declarations-with-explicit-index-contract.md
33. PR-33-tile-bank-spec-propagation-and-runtime-contract-alignment.md
34. PR-34-tile-bank-diagnostics-and-validation-hardening.md
35. PR-35-packing-aware-walkers-and-runtime-materialization-preparation.md
36. PR-36-pack-workspace-execution-with-frozen-snapshot-and-staging.md

Current wave discipline from PR-11 onward:

• cleanup and active-surface reduction happen before runtime implementation;
• the wave is service-first and Studio-driven;
• doctor, build/pack, and background reconcile are explicitly deferred;
• code that is not used by the active service wave should be removed instead of preserved speculatively.

Recommended dependency chain:

PR-01 -> PR-02 -> PR-03 -> PR-04 -> PR-05 -> PR-06 -> PR-07 -> PR-08 -> PR-09 -> PR-10 -> PR-11 -> PR-12 -> PR-13 -> PR-14 -> PR-15 -> PR-16 -> PR-17 -> PR-18 -> PR-19 -> PR-20 -> PR-21 -> PR-22 -> PR-23 -> PR-24 -> PR-25 -> PR-26 -> PR-27 -> PR-28 -> PR-29 -> PR-30 -> PR-31 -> PR-32 -> PR-33 -> PR-34 -> PR-35 -> PR-36