container-superposition 0.1.3 → 0.1.5

package/docs/specs/001-verbose-plan-graph/spec.md

@@ -0,0 +1,128 @@
+# Feature Specification: Verbose Plan Graph
+
+**Feature Branch**: `001-verbose-plan-graph`  
+**Created**: 2026-03-10  
+**Status**: Final  
+**Input**: User description: "Extend the plan command with a --verbose flag that narrates the dependency resolution graph — explaining why each overlay was included, not just what was included. The principle: nothing here is magic. Scope update: it should also be possible to run plan including --verbose on an existing manifest."
+
+## Review & Approval _(mandatory before implementation)_
+
+- **Spec Path**: `docs/specs/001-verbose-plan-graph/spec.md`
+- **Commit Status**: Committed
+- **Review Status**: APPROVED
+- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
+
+## User Scenarios & Testing _(mandatory)_
+
+### User Story 1 - Explain auto-included overlays (Priority: P1)
+
+A user previews a stack and wants to understand why extra overlays appear in the plan so they can trust the result before generating files.
+
+**Why this priority**: The plan command is a decision aid. If users cannot see why dependencies were added, they cannot confidently approve the generated setup.
+
+**Independent Test**: Can be fully tested by running `plan` with one overlay that causes at least one dependency to be included and confirming the verbose output explains each included overlay and its reason.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user requests a plan with an overlay that requires another overlay, **When** the user adds `--verbose`, **Then** the plan explains that the requested overlay was included by user choice and the dependency was included because it is required by that overlay.
+2. **Given** a dependency is included through more than one path, **When** the user adds `--verbose`, **Then** the plan shows all relevant parent reasons without duplicating the included overlay entry.
+
+---
+
+### User Story 2 - Explain plans loaded from a manifest (Priority: P2)
+
+A user reviews an existing `superposition.json` manifest and wants the same verbose dependency narration without re-entering overlay selections manually.
+
+**Why this priority**: Manifest-driven workflows are already part of the product. Verbose explanation should work there too, or users will get different levels of transparency depending on how they invoke the plan.
+
+**Independent Test**: Can be fully tested by running `plan` from an existing manifest with `--verbose` and confirming the explanation covers the manifest-defined overlays and any resolved dependencies.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user runs the plan from an existing manifest, **When** the user adds `--verbose`, **Then** the plan explains why each overlay in the manifest-driven result was included using the same reasoning model as direct overlay selection.
+2. **Given** the manifest includes overlays that produce required dependencies, **When** the user adds `--verbose`, **Then** the plan explains both the manifest-defined overlays and the auto-included dependencies without requiring duplicate manual input.
+
+---
+
+### User Story 3 - Trace the full dependency path (Priority: P3)
+
+A user wants to follow the dependency chain from requested overlays to transitive dependencies so they can review complex plans without guessing how the final set was derived.
+
+**Why this priority**: Complex overlay combinations are harder to validate by inspection. Showing the chain reduces confusion and makes the tool easier to audit.
+
+**Independent Test**: Can be fully tested by running `plan --verbose` with overlays that produce a multi-step dependency chain and verifying the explanation identifies each step in the chain.
+
+**Acceptance Scenarios**:
+
+1. **Given** a requested overlay leads to a transitive dependency chain, **When** the user adds `--verbose`, **Then** the plan narrates the chain in request-to-dependency order.
+2. **Given** multiple requested overlays are resolved in one plan, **When** the user adds `--verbose`, **Then** the explanation groups or orders the reasoning so a user can tell which requested overlays caused each dependency.
+
+---
+
+### User Story 4 - Preserve concise output when not needed (Priority: P4)
+
+A user who only wants a quick summary should still be able to run the plan command without additional explanation noise.
+
+**Why this priority**: The new explainability mode should add transparency without making the default workflow slower to scan.
+
+**Independent Test**: Can be fully tested by comparing plan output with and without `--verbose` and confirming that explanation content appears only when explicitly requested.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user runs the plan command without `--verbose`, **When** the plan is displayed, **Then** the command shows the existing summary output without dependency narration.
+2. **Given** a user consumes the plan in structured output mode, **When** `--verbose` is present, **Then** the inclusion reasons are available in the structured result in addition to the standard plan data.
+
+### Edge Cases
+
+- A requested overlay has no dependencies and should still be explained as user-selected when `--verbose` is used.
+- A dependency is required by multiple requested overlays and the explanation must show all contributing reasons without repeating the dependency as separate final selections.
+- Dependency resolution stops because of a conflict or unsupported combination and the verbose output must clearly identify the last successful inclusion and the reason resolution could not continue.
+- The user requests an invalid or unknown overlay and the plan must fail with a clear message instead of producing partial explanation data.
+- A user attempts to plan from a missing or invalid manifest and the command must fail with a clear message instead of producing incomplete verbose explanation output.
+
+## Requirements _(mandatory)_
+
+### Functional Requirements
+
+- **FR-001**: The plan command MUST accept a `--verbose` option that adds a narrative explanation of dependency resolution to the plan result.
+- **FR-002**: When `--verbose` is present, the plan MUST explain why every included overlay appears in the final plan, including whether it was requested directly or added as a dependency.
+- **FR-003**: When an included overlay was added because another overlay required it, the plan MUST identify the parent overlay or overlays that caused that inclusion.
+- **FR-004**: When dependency resolution includes transitive dependencies, the plan MUST present the explanation as a traceable chain from the user-requested overlays to each transitive inclusion.
+- **FR-005**: The plan MUST avoid duplicate final inclusion entries when the same dependency is reached through multiple paths while still preserving all relevant reasons for its inclusion.
+- **FR-006**: When dependency resolution cannot complete because of conflicts, unsupported combinations, or invalid overlay selections, the verbose output MUST explain the point of failure and the reason the plan cannot proceed.
+- **FR-007**: When the plan command is run from an existing `superposition.json` manifest, `--verbose` MUST provide the same dependency explanation coverage as overlay-list-driven planning.
+- **FR-008**: When manifest-driven planning fails because the manifest is missing, invalid, or references invalid overlays, the command MUST produce a clear failure message and MUST NOT produce misleading partial verbose results.
+- **FR-009**: When `--verbose` is not present, the plan command MUST preserve the existing concise behavior and must not require users to read dependency narration.
+- **FR-010**: When the plan is requested in structured output mode together with `--verbose`, the inclusion reasons MUST be available in the structured result in a form that distinguishes direct selections from dependency-driven selections.
+- **FR-011**: The explanation produced by `--verbose` MUST use the same resolved overlay set as the standard plan summary so users never see contradictory inclusion results between concise and verbose views.
+
+### Key Entities _(include if feature involves data)_
+
+- **Plan Request**: A user's preview request, including the chosen stack, selected overlays, and optional output flags that affect how the plan is presented.
+- **Manifest-Based Plan Request**: A preview request loaded from an existing `superposition.json` manifest instead of explicit overlay flags, while preserving the same user-visible planning semantics.
+- **Overlay Inclusion Reason**: A user-visible explanation describing why one overlay appears in the final plan, including whether it was directly requested, required by another overlay, or reached transitively through earlier inclusions.
+- **Dependency Path**: The ordered relationship from one or more user-requested overlays through intermediate requirements to a final included overlay.
+
+## Assumptions
+
+- Users expect `--verbose` to add explanation only, not to change dependency resolution rules or the final set of included overlays.
+- The same explainability data should be available to both human readers and scripted consumers when they explicitly request verbose output.
+- Existing conflict and validation behavior remains in scope; this feature only expands how the reasoning is presented.
+- Existing manifest-driven workflows should use the same explanation model as direct overlay selection rather than introducing a separate reasoning format.
+
+## Dependencies & Impact _(mandatory)_
+
+- **Affected Areas**: CLI command behavior, manifest-driven planning workflows, plan output, discovery documentation, CHANGELOG.md, automated tests
+- **Compatibility Impact**: Backward compatible
+- **Required Documentation Updates**: README.md, discovery command documentation, CHANGELOG.md
+- **Verification Plan**: Unit tests for inclusion-reason reporting, command-level tests for verbose and non-verbose output, manifest-driven planning validation, and manual validation with direct, transitive, duplicate-path, manifest, and failure scenarios
+
+## Success Criteria _(mandatory)_
+
+### Measurable Outcomes
+
+- **SC-001**: In review testing, 100% of overlays shown in a verbose plan include an explicit human-readable reason for inclusion.
+- **SC-002**: Users can run a verbose plan from an existing manifest and receive the same class of inclusion explanations as they do from direct overlay selection in 100% of acceptance scenarios.
+- **SC-003**: For plans with transitive dependencies, reviewers can identify the full inclusion chain for each dependency in under 30 seconds without consulting source code or overlay manifests.
+- **SC-004**: In acceptance testing across representative plan scenarios, at least 90% of users correctly distinguish direct selections from auto-included dependencies after reading a single verbose plan output.
+- **SC-005**: Running the plan command without `--verbose` continues to present the concise summary with no additional explanation sections in 100% of regression test cases.

package/docs/specs/001-verbose-plan-graph/tasks.md

@@ -0,0 +1,223 @@
+# Tasks: Verbose Plan Graph
+
+**Input**: Design documents from `/docs/specs/001-verbose-plan-graph/`
+**Prerequisites**: [plan.md](plan.md), [spec.md](spec.md), [research.md](research.md), [data-model.md](data-model.md), [plan-verbose-output.md](contracts/plan-verbose-output.md), [quickstart.md](quickstart.md)
+
+**Tests**: Add automated command-level coverage in `tool/__tests__/commands.test.ts`, then run manual quickstart validation plus `npm test` and `npm run lint`.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g. `US1`, `US2`, `US3`)
+- Include exact file paths in descriptions
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Record the approved governance state and prepare the command surface for the expanded scope.
+
+- [x] T001 Record approved spec commit status and review gate in `docs/specs/001-verbose-plan-graph/spec.md`
+- [x] T002 Align implementation sequencing notes for the manifest-driven scope in `docs/specs/001-verbose-plan-graph/plan.md`
+- [x] T003 Update `plan` command option and argument wiring for manifest-driven verbose planning in `scripts/init.ts`
+- [x] T004 Record the revised implementation baseline and pending manifest validation in `docs/specs/001-verbose-plan-graph/quickstart.md`
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Build the shared request normalization and explanation model that every story depends on.
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+- [x] T005 Refactor plan request normalization to support overlay-list and manifest inputs in `tool/commands/plan.ts`
+- [x] T006 Define shared inclusion-reason and dependency-path helpers for all plan modes in `tool/commands/plan.ts`
+- [x] T007 Define shared verbose JSON payload shaping for overlay-list and manifest inputs in `tool/commands/plan.ts`
+- [x] T008 Add baseline regression coverage for request parsing and shared plan payload behavior in `tool/__tests__/commands.test.ts`
+- [x] T009 Add fixture support for manifest-driven command tests in `tool/__tests__/commands.test.ts`
+
+**Checkpoint**: Foundation ready - user story implementation can now begin following the documented story dependencies
+
+---
+
+## Phase 3: User Story 1 - Explain auto-included overlays (Priority: P1) 🎯 MVP
+
+**Goal**: Let users see why directly selected overlays and auto-added required dependencies appear in the final plan.
+
+**Independent Test**: Run `npm run init -- plan --stack compose --overlays grafana --verbose` and confirm the output explains `grafana` as directly selected and `prometheus` as required by `grafana`, without duplicate overlay entries.
+
+### Verification for User Story 1
+
+- [x] T010 [US1] Add verbose text-output regression coverage for direct selections and required dependencies in `tool/__tests__/commands.test.ts`
+- [x] T011 [US1] Add verbose JSON regression coverage for direct selections and required dependencies in `tool/__tests__/commands.test.ts`
+
+### Implementation for User Story 1
+
+- [x] T012 [US1] Implement direct-selection explanation records for overlay-list planning in `tool/commands/plan.ts`
+- [x] T013 [US1] Implement required-dependency explanation records for overlay-list planning in `tool/commands/plan.ts`
+- [x] T014 [US1] Render the verbose dependency narration section for direct overlay selection in `tool/commands/plan.ts`
+- [x] T015 [US1] Attach verbose inclusion-reason data to JSON plan output for direct overlay selection in `tool/commands/plan.ts`
+
+**Checkpoint**: User Story 1 should now be fully functional and testable on its own
+
+---
+
+## Phase 4: User Story 2 - Explain plans loaded from a manifest (Priority: P2)
+
+**Goal**: Let users run `plan --verbose` from an existing `superposition.json` manifest and receive the same explanation quality they get from direct overlay selection.
+
+**Independent Test**: Run `npm run init -- plan --from-manifest superposition.json --verbose` and confirm the explanation treats manifest-defined overlays as the root set while still explaining auto-added dependencies separately.
+
+### Verification for User Story 2
+
+- [x] T016 [US2] Add regression coverage for verbose text output from manifest-driven planning in `tool/__tests__/commands.test.ts`
+- [x] T017 [US2] Add regression coverage for verbose JSON output from manifest-driven planning in `tool/__tests__/commands.test.ts`
+- [x] T018 [US2] Add regression coverage for missing, invalid, and semantically broken manifests in `tool/__tests__/commands.test.ts`
+
+### Implementation for User Story 2
+
+- [x] T019 [US2] Load manifest-defined overlay roots into the shared plan request model in `tool/commands/plan.ts`
+- [x] T020 [US2] Implement manifest-root explanation records that distinguish saved configuration from dependency-driven inclusions in `tool/commands/plan.ts`
+- [x] T021 [US2] Prevent partial verbose output when manifest-driven planning fails in `tool/commands/plan.ts`
+- [x] T022 [US2] Render manifest-driven verbose narration using the shared explanation model in `tool/commands/plan.ts`
+- [x] T023 [US2] Attach manifest input metadata to verbose JSON plan output in `tool/commands/plan.ts`
+
+**Checkpoint**: User Stories 1 and 2 should both work independently
+
+---
+
+## Phase 5: User Story 3 - Trace the full dependency path (Priority: P3)
+
+**Goal**: Let users follow transitive dependency chains and shared-parent paths in both direct and manifest-driven planning without guessing how the final plan was assembled.
+
+**Independent Test**: Run `plan --verbose` for overlays that create transitive or shared-parent dependencies and confirm each included overlay appears once with traceable path information, regardless of whether the roots came from flags or a manifest.
+
+### Verification for User Story 3
+
+- [x] T024 [US3] Add regression coverage for transitive dependency path narration in `tool/__tests__/commands.test.ts`
+- [x] T025 [US3] Add regression coverage for shared-parent dependency explanations without duplicate overlay entries in `tool/__tests__/commands.test.ts`
+
+### Implementation for User Story 3
+
+- [x] T026 [US3] Extend inclusion-reason tracking for transitive dependency paths in `tool/commands/plan.ts`
+- [x] T027 [US3] Preserve multiple parent reasons while de-duplicating final overlay entries in `tool/commands/plan.ts`
+- [x] T028 [US3] Render ordered dependency paths in verbose text output for overlay-list and manifest inputs in `tool/commands/plan.ts`
+- [x] T029 [US3] Serialize transitive paths and multi-parent reasons in verbose JSON output in `tool/commands/plan.ts`
+
+**Checkpoint**: User Stories 1 through 3 should all be independently functional
+
+---
+
+## Phase 6: User Story 4 - Preserve concise output when not needed (Priority: P4)
+
+**Goal**: Keep the default plan experience concise while surfacing verbose failure context only when users explicitly request it.
+
+**Independent Test**: Compare `plan` output with and without `--verbose`, then run conflict, invalid-overlay, and stack-incompatible cases with `--verbose` and confirm concise mode is unchanged while verbose mode adds failure context.
+
+### Verification for User Story 4
+
+- [x] T030 [US4] Add regression coverage confirming non-verbose text and JSON output remain unchanged for overlay-list and manifest inputs in `tool/__tests__/commands.test.ts`
+- [x] T031 [US4] Add regression coverage for verbose conflict, invalid-overlay, and stack-incompatible skip context in `tool/__tests__/commands.test.ts`
+
+### Implementation for User Story 4
+
+- [x] T032 [US4] Gate verbose narration so it only renders when `--verbose` is present in `tool/commands/plan.ts`
+- [x] T033 [US4] Add verbose failure-boundary explanations for conflicts, invalid overlays, stack-incompatible skips, and manifest failures in `tool/commands/plan.ts`
+- [x] T034 [US4] Ensure concise summary and verbose explanation reuse the same resolved overlay set in `tool/commands/plan.ts`
+
+**Checkpoint**: All user stories should now be independently functional
+
+---
+
+## Phase 7: Polish & Cross-Cutting Concerns
+
+**Purpose**: Finish docs, changelog, and end-to-end verification for the expanded scope.
+
+- [x] T035 [P] Document direct-selection and manifest-driven `--verbose` examples in `README.md`
+- [x] T036 [P] Document manifest-driven verbose planning behavior and examples in `docs/discovery-commands.md`
+- [x] T037 Update the user-visible change summary for manifest-driven verbose planning in `CHANGELOG.md`
+- [x] T038 Update validation steps and outcomes for manifest-driven planning in `docs/specs/001-verbose-plan-graph/quickstart.md`
+- [x] T039 Run automated verification with `npm test` and `npm run lint`, then record the results in `docs/specs/001-verbose-plan-graph/quickstart.md`
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: Starts immediately
+- **Foundational (Phase 2)**: Depends on Setup completion and blocks all story work
+- **User Story 1 (Phase 3)**: Depends on Foundational completion
+- **User Story 2 (Phase 4)**: Depends on Foundational completion and should follow US1 because it extends the same command surface and explanation model to manifest inputs
+- **User Story 3 (Phase 5)**: Depends on Foundational completion and should follow US1 and US2 because it builds on the shared explanation records across both input modes
+- **User Story 4 (Phase 6)**: Depends on Foundational completion and should land after US1 through US3 because it validates backward compatibility and failure behavior across the full verbose path
+- **Polish (Phase 7)**: Depends on the desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: No dependency on other stories after Phase 2
+- **User Story 2 (P2)**: Depends on the shared explanation data from Phase 2 and should follow US1 once direct-selection verbose records are stable
+- **User Story 3 (P3)**: Depends on the verbose output path from US1 and the manifest-root model from US2
+- **User Story 4 (P4)**: Depends on the full verbose path from US1 through US3 so concise-mode and failure-boundary regressions are measured against the completed behavior
+
+### Within Each User Story
+
+- Add or update verification tasks before implementation for that story
+- Extend shared data capture before rendering output
+- Render text and JSON output after explanation data is available
+- Complete story-specific regression coverage before moving on
+
+### Parallel Opportunities
+
+- `T035` and `T036` can run in parallel once command behavior is stable
+- Within each user story, the work is intentionally sequential because the changes concentrate in `tool/commands/plan.ts` and `tool/__tests__/commands.test.ts`
+
+---
+
+## Parallel Example: User Story 2
+
+```bash
+No safe [P] tasks inside User Story 2 because manifest input handling, explanation rendering, and command regression coverage all update shared files.
+```
+
+## Parallel Example: Polish
+
+```bash
+Task: "Document direct-selection and manifest-driven --verbose examples in README.md"
+Task: "Document manifest-driven verbose planning behavior and examples in docs/discovery-commands.md"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational
+3. Complete Phase 3: User Story 1
+4. Validate `plan --verbose` for a direct dependency case
+5. Stop for review before expanding into manifest-driven planning
+
+### Incremental Delivery
+
+1. Ship the shared explanation foundation
+2. Deliver User Story 1 for direct plus required dependencies
+3. Add User Story 2 for manifest-driven verbose planning
+4. Add User Story 3 for transitive and shared-parent path tracing across both input modes
+5. Add User Story 4 to lock in concise-mode backward compatibility and verbose failure context
+6. Finish docs, changelog, and verification
+
+### Parallel Team Strategy
+
+1. One developer completes Setup and Foundational work
+2. After US1 lands, one developer can extend manifest input handling while another prepares the manifest-driven documentation examples
+3. After US2 lands, the same command owner should complete transitive-path and failure-context work because those changes remain concentrated in shared files
+
+---
+
+## Notes
+
+- All tasks use the required checklist format with IDs, optional `[P]` markers, story labels for story phases, and exact file paths
+- The approved spec gate is closed; execution readiness now depends on completing implementation, verification, and documentation tasks cleanly
+- Favor command-level regression tests in `tool/__tests__/commands.test.ts` because the risk is user-visible CLI behavior

package/docs/specs/002-superposition-config-file/checklists/requirements.md

@@ -0,0 +1,36 @@
+# Specification Quality Checklist: Project Configuration File
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-03-11
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Validation completed on 2026-03-11 and passed on the first review iteration.
+- The spec intentionally defines file names and precedence rules because they are part of the user-visible feature behavior and acceptance scope.
+- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`

package/docs/specs/002-superposition-config-file/contracts/init-project-config.md

@@ -0,0 +1,98 @@
+# Contract: Init Project Config
+
+## Purpose
+
+Define the user-facing contract for repository-root project config input during
+`init` and `regen` runs.
+
+## Supported Files
+
+Exactly one of these files may be used at the repository root:
+
+- `.superposition.yml`
+- `superposition.yml`
+
+If both exist, initialization fails before generation.
+
+## Supported Declaration Surface
+
+The project config file may declare every supported clean-generation input that
+materially affects generated output, including:
+
+- stack selection
+- base image and custom image selection
+- container name
+- preset selection and preset parameters
+- overlay selections by category
+- output path
+- port offset
+- target environment
+- minimal/editor settings
+- supported customization inputs such as environment-related settings, custom
+  container definitions, preset glue values, and additional generated features
+
+## Resolution Rules
+
+### Standard Initialization
+
+1. Discover a supported project config file in the repository root.
+2. Validate the file and stop on any ambiguity or invalid entries.
+3. Apply project config values as the default persisted input source.
+4. Apply any direct command input as run-specific overrides.
+5. Collect only still-missing required values through the existing flow.
+
+### Explicit Project-File Source Selection
+
+1. `--from-project` selects the repository project file as the run's persisted
+   input source.
+2. The command fails before generation if no supported project file exists.
+3. `--from-project` may not be combined with `--from-manifest` or
+   clean-generation selection flags such as stack, overlays, or preset
+   selection.
+
+### Explicit Manifest Initialization
+
+1. Load the explicit manifest as the run’s persisted input source.
+2. Apply any direct command input as run-specific overrides.
+3. Do not silently merge repository project config values into that run.
+
+### Default Regeneration Source Selection
+
+1. `regen` first uses the repository project file when one exists and no other
+   persisted-input source has been selected.
+2. If no project file exists, `regen` falls back to manifest discovery in the
+   established manifest locations.
+3. Persisted-input source selection must be explicit and unambiguous before
+   generation starts.
+
+## Parity Requirement
+
+If a generation input is supported through the existing clean-generation path
+and materially affects generated output, it must be expressible through the
+project config file and yield the same final generated output.
+
+## Error Conditions
+
+Initialization must fail before generation when any of the following occur:
+
+- both supported project config filenames exist
+- the file cannot be parsed
+- unsupported keys or values are declared
+- conflicting selections are declared
+- `--from-project` and `--from-manifest` are used together
+- a persisted-input source mode is combined with clean-generation selection
+  flags such as stack, overlays, or preset selection
+- a required value is missing in a non-interactive context
+- a declared customization input is outside the supported clean-generation
+  surface
+
+## Verification Expectations
+
+- Valid project config yields the same output as equivalent direct user
+  selections.
+- Supported customization inputs round-trip through project config without
+  losing parity.
+- Missing project config preserves current interactive and flag-driven
+  behavior.
+- `regen` supports both explicit and implicit project-file source selection.
+- Explicit manifest runs remain isolated from project-config defaults.

package/docs/specs/002-superposition-config-file/data-model.md

@@ -0,0 +1,126 @@
+# Data Model: Project Configuration File
+
+## Entity: ProjectConfigFile
+
+**Purpose**: Represents the repository-root YAML document that declares shared
+generation intent for a project.
+
+**Fields**:
+
+- `path`: Absolute path to the discovered file.
+- `fileName`: `.superposition.yml` or `superposition.yml`.
+- `declaredValues`: Parsed user-authored generation inputs.
+- `status`: `missing`, `loaded`, `invalid`, or `ambiguous`.
+
+**Validation rules**:
+
+- At most one supported config filename may exist in the repository root.
+- The file must be valid YAML.
+- The file may declare only supported clean-generation inputs.
+
+## Entity: ProjectConfigSelection
+
+**Purpose**: Represents the set of supported generation inputs declared in the
+project config file.
+
+**Fields**:
+
+- `stack`
+- `baseImage`
+- `customImage`
+- `containerName`
+- `preset`
+- `presetChoices`
+- `language`
+- `database`
+- `observability`
+- `cloudTools`
+- `devTools`
+- `playwright`
+- `outputPath`
+- `portOffset`
+- `target`
+- `minimal`
+- `editor`
+- `customizationInputs`
+- `sourceMode`
+
+**Validation rules**:
+
+- Values must follow the same supported set as equivalent direct command or
+  interactive inputs.
+- Customization-related inputs must map to supported clean-generation behavior,
+  not unmanaged arbitrary output fragments.
+- Partial definitions are allowed, but unresolved required values must remain
+  completable through the existing flow.
+
+## Entity: CustomizationInput
+
+**Purpose**: Represents a supported non-basic generation setting that changes
+the final generated output beyond simple stack or overlay selection.
+
+**Fields**:
+
+- `kind`: category of customization input
+- `name`: user-facing identifier for the customization
+- `value`: declared value
+- `source`: `project-config`, `cli`, `manifest`, or `interactive`
+
+**Examples**:
+
+- custom container definition
+- environment-related setting
+- preset glue configuration
+- editor/minimal customization
+- additional generated feature setting
+
+**Validation rules**:
+
+- The customization must already be part of the supported clean-generation
+  surface.
+- The customization must round-trip through generation without being dropped or
+  silently rewritten to a different meaning.
+
+## Entity: EffectiveGenerationRequest
+
+**Purpose**: Represents the final resolved inputs for one generation run.
+
+**Fields**:
+
+- `sourceMode`: standard init, explicit project-file init, implicit project-file
+  regen, explicit manifest init, or standard init with direct overrides
+- `resolvedValues`: final merged `QuestionnaireAnswers`-equivalent values
+- `overrideSources`: per-field record of which source won precedence
+
+**Relationships**:
+
+- May derive from one `ProjectConfigSelection`
+- May derive from one explicit manifest input
+- May include many `CustomizationInput` values
+
+## Entity: ValidationIssue
+
+**Purpose**: Represents one user-facing problem found while loading the project
+config file.
+
+**Fields**:
+
+- `scope`: `discovery`, `syntax`, `field`, `selection`, `conflict`, `ambiguity`
+- `location`: file or config entry reference
+- `message`: user-facing description
+- `suggestedFix`: corrective action
+
+**State transitions**:
+
+- `detected` -> `reported`
+- `reported` -> `resolved by config edit`
+
+## Relationship Summary
+
+- One repository has zero or one `ProjectConfigFile`.
+- One `ProjectConfigFile` may contain one `ProjectConfigSelection`.
+- One `ProjectConfigSelection` may contain many `CustomizationInput` values.
+- One `EffectiveGenerationRequest` merges values from supported sources and
+  feeds generation plus manifest output.
+- One `EffectiveGenerationRequest` must resolve exactly one persisted-input
+  source mode before generation starts.