container-superposition 0.1.4 → 0.1.6

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.