container-superposition 0.1.4 → 0.1.5

package/docs/specs/002-superposition-config-file/research.md

@@ -0,0 +1,144 @@
+# Research: Project Configuration File
+
+## Decision 1: Treat project config as a partial-answer source in the existing init flow
+
+**Decision**: Load `.superposition.yml` or `superposition.yml` into the same
+partial-answer merge flow already used for direct command input and manifest
+translation.
+
+**Rationale**: The repository already has `QuestionnaireAnswers`,
+`buildAnswersFromCliArgs`, `buildAnswersFromManifest`, and `mergeAnswers`.
+Reusing that path keeps generation behavior aligned across interactive, CLI,
+manifest, and project-config inputs.
+
+**Alternatives considered**:
+
+- Build a separate config-only generation pipeline: rejected because it would
+  duplicate behavior and drift from the main generation path.
+- Translate project config into a manifest before generation: rejected because
+  the project config is intended to be the human-authored source of intent, not
+  a derived artifact.
+
+## Decision 2: Keep explicit manifest mode separate from project-config defaults
+
+**Decision**: Project config is the default persisted input source for standard
+initialization, but explicit manifest-based runs remain a separate mode and do
+not merge project-config values silently.
+
+**Rationale**: The feature spec explicitly preserves manifest-based regeneration
+as a separate path. Mixing the two persisted inputs would make source-of-truth
+selection ambiguous and weaken predictability.
+
+**Alternatives considered**:
+
+- Always merge project config into manifest-based runs: rejected because explicit
+  manifest input is a stronger per-run instruction.
+- Replace manifest workflows entirely: rejected because it would break existing
+  regeneration behavior and expand scope.
+
+## Decision 3: Support project-file based regeneration as a first-class persisted input mode
+
+**Decision**: `regen` supports the repository project file as a persisted input
+source, and it may use that source implicitly when no conflicting source or
+clean-generation selection flags are present.
+
+**Rationale**: The project file is now a version-controlled source of truth, so
+regeneration should not force teams back to a generated manifest when the
+project file already expresses the supported intent.
+
+**Alternatives considered**:
+
+- Keep `regen` manifest-only: rejected because it would create an arbitrary
+  split between initialization and regeneration for the same declared intent.
+- Require `--from-project` for every project-file based regen: rejected because
+  the default regen path should be able to use the repository source of truth
+  directly when no ambiguity exists.
+
+## Decision 4: Define parity in terms of supported clean-generation inputs
+
+**Decision**: “Full parity” means every currently supported clean-generation
+input that materially affects generated output can be declared in the project
+config file, including customization surfaces such as custom images,
+editor/minimal settings, preset glue, environment-related settings, and
+additional generated features already represented by the generation flow.
+
+**Rationale**: The user value is not just basic overlay selection; it is a
+declarative source of truth for the full supported generation surface. Limiting
+project config to a subset would force teams back to long commands for the most
+important customizations.
+
+**Alternatives considered**:
+
+- Support only stack and overlays first: rejected because it would not satisfy
+  the parity requirement in the approved spec.
+- Allow arbitrary raw devcontainer fragments in project config: rejected because
+  it would blur the boundary between supported generation inputs and unmanaged
+  custom output.
+
+## Decision 5: Restrict discovery to the repository root and fail on dual-file ambiguity
+
+**Decision**: Discover project config only in the current repository root and
+fail if both supported filenames exist.
+
+**Rationale**: The feature is explicitly project-level. Root-only discovery is
+predictable for local workflows and CI, and dual-file failure preserves a
+single visible source of truth.
+
+**Alternatives considered**:
+
+- Search parent directories: rejected because it risks binding nested work to
+  the wrong config.
+- Prefer one filename silently: rejected because ambiguity should be surfaced,
+  not hidden.
+
+## Decision 6: Validation must happen before generation and name the offending config entry
+
+**Decision**: Project-config validation fails before generation begins and
+reports syntax errors, unsupported keys, unsupported values, conflicts, missing
+required values, and ambiguity in terms of the file content or repository state
+the user must correct.
+
+**Rationale**: Declarative workflows are only trustworthy if failures point back
+to the committed source of truth rather than forcing users to infer hidden merge
+behavior.
+
+**Alternatives considered**:
+
+- Let composition fail later: rejected because it hides whether the problem is
+  config input or generation logic.
+- Ignore unknown keys: rejected because it would make committed config content
+  misleading.
+
+## Decision 7: Persisted-input source conflicts must fail before generation
+
+**Decision**: `--from-project` and `--from-manifest` are mutually exclusive,
+and persisted-input source modes fail fast when combined with clean-generation
+selection flags such as stack, overlays, or preset selection.
+
+**Rationale**: Source selection must stay explicit and predictable. Allowing
+multiple persisted-input sources or mixing source modes with structural
+generation selection flags would make the effective source of truth ambiguous.
+
+**Alternatives considered**:
+
+- Merge persisted-input sources in precedence order: rejected because it hides
+  which source actually defines the run.
+- Allow source modes plus structural overrides: rejected because it weakens the
+  contract of deliberate source selection.
+
+## Decision 8: Verification must include parity cases, not only happy-path loading
+
+**Decision**: Verification covers clean-generation parity for supported
+customization inputs in addition to discovery, precedence, and validation
+behavior.
+
+**Rationale**: The highest-risk regressions are cases where project config loads
+but silently loses part of the intended output surface, especially customization
+settings that teams expect to be declarative.
+
+**Alternatives considered**:
+
+- Test only project-config discovery: rejected because discovery alone does not
+  prove parity.
+- Rely on manual parity checks only: rejected because user-visible generation
+  behavior needs automated regression protection.

package/docs/specs/002-superposition-config-file/spec.md

@@ -0,0 +1,130 @@
+# Feature Specification: Project Configuration File
+
+**Feature Branch**: `002-superposition-config-file`  
+**Created**: 2026-03-11  
+**Status**: Final  
+**Input**: Add a repository-root project config file so teams and automation can generate the same environment from committed declarative setup instead of reconstructing long CLI commands.
+
+> Use repo-relative Markdown links for repository files. The root `README.md`
+> is the only exception and may use package-friendly hosted URLs.
+
+## Review & Approval _(mandatory before implementation)_
+
+- **Spec Path**: `docs/specs/002-superposition-config-file/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 - Generate from committed project config (Priority: P1)
+
+A project maintainer defines the desired development environment in a single repository-root config file so any teammate can generate the same stack, overlay set, output target, and supported customizations without reconstructing a long command.
+
+**Why this priority**: This is the core user value. It turns setup intent into a durable, reviewable project artifact instead of a one-off shell command.
+
+**Independent Test**: Place a valid `.superposition.yml` or `superposition.yml` in the repository root, run the generation flow without supplying the equivalent long-form options, and confirm the generated output matches the declared stack, overlay selection, output location, and supported customization settings.
+
+**Acceptance Scenarios**:
+
+1. **Given** a repository with a valid project config file in its root that defines stack, overlay selections, output location, and supported customization settings, **When** a maintainer runs the generation flow from that repository root, **Then** the tool uses those values as the starting configuration for generation.
+2. **Given** a repository with a committed project config file, **When** a teammate clones the repository and runs the same generation flow from a fresh checkout, **Then** they receive the same effective project setup without needing the original author’s shell history or copied command examples.
+
+---
+
+### User Story 2 - Use config-driven setup in automation (Priority: P2)
+
+A team uses the same committed project config file in CI or scripted workflows so environment generation is repeatable, unattended, and insulated from copied command examples.
+
+**Why this priority**: Declarative setup is most valuable when it works in unattended workflows and shared operational contexts.
+
+**Independent Test**: Run the generation flow in a non-interactive context from a repository that contains a valid project config file and confirm it completes with no prompt for values already defined in the file, while still allowing explicit per-run overrides.
+
+**Acceptance Scenarios**:
+
+1. **Given** a non-interactive workflow and a valid project config file, **When** the generation flow starts, **Then** it completes using the file-defined values without requiring interactive answers for those settings.
+2. **Given** a repository where the committed project config file is unchanged, **When** the automation workflow runs repeatedly, **Then** each run resolves the same requested configuration and any direct command overrides affect only that run.
+3. **Given** a repository with a valid project config file and no conflicting persisted-input flag or clean-generation selection flags, **When** a user runs `init --no-interactive` or `regen` in the default project-file mode, **Then** the tool uses the project file as the persisted input source without requiring `--from-project`.
+
+---
+
+### User Story 3 - Correct invalid or ambiguous config quickly (Priority: P3)
+
+A contributor receives clear guidance when the project config file is invalid, incomplete, or ambiguous so they can fix the committed source of truth instead of debugging generated output or hidden fallback behavior.
+
+**Why this priority**: Declarative workflows only improve team reliability if configuration problems are surfaced clearly and early.
+
+**Independent Test**: Introduce invalid entries, unsupported values, missing required selections for non-interactive use, or ambiguous file conditions and verify the tool stops before generation with actionable guidance tied to the file content or repository state.
+
+**Acceptance Scenarios**:
+
+1. **Given** a project config file with unsupported keys, unsupported values, or conflicting selections, **When** the generation flow validates the file, **Then** it stops before generating files and reports each issue in terms the contributor can correct.
+2. **Given** both supported project config filenames are present in the same repository, **When** the generation flow starts, **Then** it stops and instructs the user to keep only one project config file so the source of truth is unambiguous.
+
+### Edge Cases
+
+- What happens when no project config file exists? The current interactive and flag-driven flows remain available without behavior changes.
+- What happens when a project config file defines only part of the setup? The tool uses the provided values and continues to collect any still-required missing choices through the existing flow.
+- How does the system handle explicit command input that conflicts with the project config file? Explicit command input takes precedence for that run, and the user can still keep the file as the shared default.
+- How does the system handle an explicit manifest-based run? The explicit manifest remains the persisted input source for that run, and the project config file does not silently override it.
+- How does the system handle explicit project-file or manifest-source flags that are combined with each other or with clean-generation selection flags such as stack, overlay, or preset selection? It fails before generation and tells the user to choose exactly one persisted input source for that run.
+- How does the system handle `init --no-interactive` or `regen` when a valid project config file exists and no other persisted-input source or clean-generation selection flags are provided? It may use the project file implicitly as the persisted input source for that run.
+- How does the system handle supported customizations such as environment settings, custom container definitions, or additional generated features? Those values are treated as first-class generation inputs and must round-trip through the project config file without being dropped.
+- How does the system handle unsupported overlay IDs, invalid categories, or conflicting selections in the project config file? It fails validation before generation and explains the invalid entries.
+- How does the system handle both `.superposition.yml` and `superposition.yml` in one repository? It treats this as an error to avoid ambiguity.
+
+## Requirements _(mandatory)_
+
+### Functional Requirements
+
+- **FR-001**: The system MUST support exactly two project-level configuration filenames for this feature: `.superposition.yml` and `superposition.yml`.
+- **FR-002**: The system MUST look for the project config file only in the repository root from which the generation flow is run.
+- **FR-003**: The system MUST treat the project config file as the default persisted input source for standard initialization when an explicit manifest input is not provided.
+- **FR-004**: The system MUST read project config values into the same setup decisions already available through interactive answers and direct command input, including stack choice, overlay selections, preset selections, output location, and other generation options that materially affect the resulting setup.
+- **FR-005**: The system MUST allow every supported clean-generation input that materially affects generated output to be declared in `.superposition.yml` or `superposition.yml` instead of requiring a long command.
+- **FR-006**: The system MUST support declaring customization inputs in the project config file, including custom container definitions, environment-related settings, additional generated features, and other first-class generation customizations that affect the resulting devcontainer output.
+- **FR-007**: The system MUST preserve declared project-config customization inputs through generation so the resulting output reflects the same customization values selected for that run.
+- **FR-008**: Users MUST be able to generate a project environment from a valid project config file without re-entering values already defined in that file.
+- **FR-009**: The system MUST allow explicit command input supplied for a run to override conflicting values from the project config file for that run only.
+- **FR-010**: The system MUST preserve the current interactive and flag-driven behavior for users who do not provide a project config file.
+- **FR-011**: The system MUST validate the project config file before generating output and MUST report invalid YAML, unsupported keys, unsupported values, missing required values, or conflicting selections with actionable correction guidance.
+- **FR-012**: The system MUST stop and report an ambiguity error when both supported project config filenames are present in the same repository.
+- **FR-013**: The system MUST produce the same effective project setup from a project config file as it would from an equivalent set of direct user selections across the full supported declaration surface.
+- **FR-014**: The system MUST allow a partially defined project config file to act as shared defaults while still collecting any remaining required choices through the existing user flow.
+- **FR-015**: The system MUST keep explicit manifest-based runs as a separate persisted-input mode and MUST NOT silently merge project config values into a run that was explicitly started from a manifest.
+- **FR-016**: The system MUST support an explicit `--from-project` source-selection mode for both initialization and regeneration flows so users can deliberately choose the repository project file as the persisted input source for a run.
+- **FR-017**: The system MUST allow `init --no-interactive` and `regen` to use the repository project file implicitly when a valid project config file exists and no other persisted-input source flag or clean-generation selection flags are supplied.
+- **FR-018**: The system MUST reject conflicting persisted-input source combinations before generation, including `--from-project` with `--from-manifest` and either source-selection mode combined with clean-generation selection flags such as stack, overlay, or preset selection.
+- **FR-019**: The system MUST document how teams create, commit, validate, and use the project config file in local development, regeneration, and automation workflows, including how parity with clean generation applies to supported customization inputs and how source-selection conflicts are resolved.
+
+### Key Entities _(include if feature involves data)_
+
+- **Project Configuration File**: The committed repository-root definition of desired setup choices, including filename, declared setup values, supported customization inputs, and whether it is the only supported config file present.
+- **Generation Request**: The effective set of choices used for one generation run after combining defaults, project config values, any explicit command input, and, when explicitly requested, manifest-based input, including supported customization inputs.
+- **Customization Input**: A supported user-configurable generation setting beyond basic stack and overlay selection, such as custom container definitions, environment-related settings, or additional generated features that alter the final output.
+- **Validation Result**: The user-facing outcome of checking the project config file, including syntax problems, unsupported entries, conflict findings, ambiguity conditions, and corrective guidance.
+
+## Dependencies & Impact _(mandatory)_
+
+- **Affected Areas**: Standard initialization workflow, clean-generation parity, supported customization handling, manifest-based regeneration boundaries, project-file based regeneration boundaries, CLI usage patterns, onboarding workflow, CI/CD workflow, user documentation
+- **Compatibility Impact**: Backward compatible
+- **Required Documentation Updates**: README.md, workflow and examples documentation, quickstart guidance, CHANGELOG.md
+- **Verification Plan**: Unit tests for config resolution and validation, integration tests for config-driven generation, smoke tests for representative stacks, manual validation for onboarding and automation flows
+
+## Assumptions
+
+- The project config file becomes the team-readable source of truth for default setup intent, including supported customization inputs, but it does not remove support for current interactive, flag-driven, or explicit manifest-based flows.
+- Explicit command input remains the highest-precedence input for a single run so users can make temporary overrides without editing the shared config file.
+- `--from-project` and `--from-manifest` are mutually exclusive persisted-input modes rather than additive sources for one run.
+- A single repository should contain at most one supported project config file so the source of truth stays deterministic and easy to explain.
+
+## Success Criteria _(mandatory)_
+
+### Measurable Outcomes
+
+- **SC-001**: In validation testing, 95% of fresh repository checkouts that contain a valid project config file can generate the intended environment without requiring users to reconstruct setup options from prior command history.
+- **SC-002**: In representative automation tests, 100% of successful non-interactive generation runs complete without prompting for any value already defined in the project config file and without changing the committed project config file.
+- **SC-003**: In usability review, at least 90% of maintainers can define or update a project’s shared setup intent within 10 minutes using the documented config file workflow.
+- **SC-004**: In invalid-configuration tests, 90% of failures identify the problematic file condition or config entry and the required correction in the first error output seen by the user.
+- **SC-005**: In parity validation, every supported customization that can be expressed through the clean generation path can also be declared in the project config file and produces the same final generated output.
+- **SC-006**: In CLI validation tests, 100% of runs that combine conflicting persisted-input source flags or mix a persisted-input source with clean-generation selection flags fail before generation with a source-conflict error that identifies the invalid combination.

package/docs/specs/002-superposition-config-file/tasks.md

@@ -0,0 +1,213 @@
+# Tasks: Project Configuration File
+
+**Input**: Design documents from `docs/specs/002-superposition-config-file/`
+**Prerequisites**: [plan.md](plan.md), [spec.md](spec.md), [research.md](research.md), [data-model.md](data-model.md), [init-project-config.md](contracts/init-project-config.md), [quickstart.md](quickstart.md)
+
+**Tests**: Add automated coverage for config discovery, precedence, no-config fallback, explicit `--from-project`, implicit project-file regen, manifest isolation, source-conflict validation, validation failures, and customization parity in `tool/__tests__/commands.test.ts`, `tool/__tests__/composition.test.ts`, `tool/__tests__/manifest-only.test.ts`, and `tool/__tests__/minimal-and-editor.test.ts`, then run `npm test`, `npm run lint`, and `npm run test:smoke`.
+
+**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 repo-relative file paths in descriptions
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Record the approved spec gate and align the feature docs with the implementation baseline before code changes.
+
+- [x] T001 Confirm approved spec status and implementation gate in `docs/specs/002-superposition-config-file/spec.md`
+- [x] T002 Align implementation sequencing and verification scope in `docs/specs/002-superposition-config-file/plan.md`
+- [x] T003 Align parity examples and validation steps in `docs/specs/002-superposition-config-file/quickstart.md`
+- [x] T004 [P] Record supported project-config surface and customization parity expectations in `docs/specs/002-superposition-config-file/contracts/init-project-config.md`
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Add the shared project-config schema and merge-path support that every story depends on.
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+- [x] T005 Define project-config file discovery, parsed shape, and validation helpers in `tool/schema/project-config.ts`
+- [x] T006 Extend shared config types and `QuestionnaireAnswers` parity fields in `tool/schema/types.ts`
+- [x] T007 Update supported config schema entries for project-config parity in `tool/schema/config.schema.json`
+- [x] T008 Refactor answer-source merging to accept project-config defaults alongside manifest and CLI inputs in `scripts/init.ts`
+- [x] T009 Add foundational regression coverage for project-config discovery, merge precedence, and dual-file ambiguity in `tool/__tests__/commands.test.ts`
+- [x] T010 Add fixture coverage for supported customization parity inputs in `tool/__tests__/composition.test.ts`
+
+**Checkpoint**: Foundation ready - user story implementation can now begin in priority order
+
+---
+
+## Phase 3: User Story 1 - Generate from committed project config (Priority: P1) 🎯 MVP
+
+**Goal**: Let maintainers define the full supported generation intent, including supported customizations, in one repository-root config file and generate the same output as clean generation.
+
+**Independent Test**: Put a valid `.superposition.yml` in the repository root with stack, overlays, output path, and supported customization inputs such as custom container definitions, environment-related settings, and additional generated features, run `npm run init`, and confirm the generated output matches equivalent clean-generation input without re-entering declared values.
+
+### Verification for User Story 1
+
+- [x] T011 [US1] Add command regression coverage for valid project-config driven generation in `tool/__tests__/commands.test.ts`
+- [x] T012 [US1] Add composition parity coverage for project-config custom image and container definition inputs in `tool/__tests__/composition.test.ts`
+- [x] T013 [US1] Add parity coverage for environment-related settings and additional generated features in `tool/__tests__/minimal-and-editor.test.ts`
+
+### Implementation for User Story 1
+
+- [x] T014 [US1] Load repository-root `.superposition.yml` and `superposition.yml` defaults into the standard init flow in `scripts/init.ts`
+- [x] T015 [US1] Map project-config selections into the clean-generation answer model in `tool/schema/project-config.ts`
+- [x] T016 [US1] Preserve supported customization inputs through generation and summary rendering in `scripts/init.ts`
+- [x] T017 [US1] Ensure project-config driven answers produce the same composed output as equivalent clean-generation input in `tool/questionnaire/composer.ts`
+- [x] T018 [US1] Keep generated run summaries accurate for project-config sourced generation in `tool/utils/summary.ts`
+
+**Checkpoint**: User Story 1 should now be fully functional and testable on its own
+
+---
+
+## Phase 4: User Story 2 - Use config-driven setup in automation (Priority: P2)
+
+**Goal**: Let teams run unattended generation from a committed project config while preserving per-run overrides and explicit manifest isolation.
+
+**Independent Test**: Run `npm run init` in a non-interactive repository with a valid project config and confirm declared values are not prompted again, direct CLI flags override only that run, and `--from-manifest` remains isolated from project-config defaults.
+
+### Verification for User Story 2
+
+- [x] T019 [US2] Add non-interactive command regression coverage for project-config defaults and CLI override precedence in `tool/__tests__/commands.test.ts`
+- [x] T020 [US2] Add manifest-isolation regression coverage for project-config and `--from-manifest` interactions in `tool/__tests__/manifest-only.test.ts`
+- [x] T021 [US2] Add regression coverage for no-config fallback to current interactive and flag-driven behavior in `tool/__tests__/commands.test.ts`
+- [x] T022 [US2] Add regression coverage for partial project-config defaults that still require remaining answers in `tool/__tests__/commands.test.ts`
+
+### Implementation for User Story 2
+
+- [x] T023 [US2] Apply project-config values as default persisted input for standard init without prompting for already-declared values in `scripts/init.ts`
+- [x] T024 [US2] Preserve partial project-config values as shared defaults while collecting only unresolved required answers in `scripts/init.ts`
+- [x] T025 [US2] Preserve run-scoped CLI override precedence over project-config defaults in `scripts/init.ts`
+- [x] T026 [US2] Keep explicit manifest mode isolated from repository project-config defaults in `scripts/init.ts`
+
+**Checkpoint**: User Stories 1 and 2 should both work independently
+
+---
+
+## Phase 5: User Story 3 - Correct invalid or ambiguous config quickly (Priority: P3)
+
+**Goal**: Stop invalid, unsupported, conflicting, or ambiguous project-config input before generation and point users to the corrective action.
+
+**Independent Test**: Introduce invalid YAML, unsupported keys, unsupported customization values, conflicting selections, missing non-interactive requirements, and both supported filenames, then confirm generation stops before output with actionable guidance tied to the repository state or config entry.
+
+### Verification for User Story 3
+
+- [x] T027 [US3] Add command regression coverage for invalid YAML, unsupported keys, and unsupported values in `tool/__tests__/commands.test.ts`
+- [x] T028 [US3] Add regression coverage for conflicting selections, missing required non-interactive values, and dual-file ambiguity in `tool/__tests__/commands.test.ts`
+- [x] T029 [US3] Add regression coverage for unsupported customization declarations outside the clean-generation surface in `tool/__tests__/commands.test.ts`
+
+### Implementation for User Story 3
+
+- [x] T030 [US3] Validate project-config syntax, supported keys, supported values, and conflicting selections before generation in `tool/schema/project-config.ts`
+- [x] T031 [US3] Report repository-root ambiguity and non-interactive missing-value failures with actionable guidance in `scripts/init.ts`
+- [x] T032 [US3] Reject unsupported customization declarations that fall outside the supported clean-generation surface in `tool/schema/project-config.ts`
+
+**Checkpoint**: All user stories should now be independently functional
+
+---
+
+## Phase 6: Polish & Cross-Cutting Concerns
+
+**Purpose**: Finish documentation, changelog, and end-to-end verification for the declarative workflow.
+
+- [x] T033 [P] Document project-config usage, parity scope, and supported customization examples in `README.md`
+- [x] T034 [P] Document local and CI workflow examples for project config in `docs/workflows.md`
+- [x] T035 [P] Document project-config parity examples and customization cases in `docs/examples.md`
+- [x] T036 Update the user-visible project-config change summary in `CHANGELOG.md`
+- [x] T037 Run the maintainer workflow review for SC-003 and record the outcome in `docs/specs/002-superposition-config-file/quickstart.md`
+- [x] T038 Record final verification steps and observed outcomes in `docs/specs/002-superposition-config-file/quickstart.md`
+- [x] T039 Run `npm test`, `npm run lint`, and `npm run test:smoke`, then record the results in `docs/specs/002-superposition-config-file/quickstart.md`
+- [x] T040 Add explicit `--from-project` and implicit `regen` project-file regression coverage in `tool/__tests__/commands.test.ts`
+- [x] T041 Implement `--from-project`, implicit project-file `regen`, and source-conflict validation in `scripts/init.ts`
+- [x] T042 Update project-file regeneration and conflict-resolution documentation in `README.md`, `docs/workflows.md`, and `docs/examples.md`
+- [x] T043 Update the user-visible changelog entry to include `regen --from-project`, implicit project-file `regen`, and source-conflict validation in `CHANGELOG.md`
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: Starts immediately
+- **Foundational (Phase 2)**: Depends on Setup completion and blocks all user 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 answer-resolution path into unattended and manifest-sensitive flows
+- **User Story 3 (Phase 5)**: Depends on Foundational completion and should follow US1 and US2 because validation rules depend on the final supported project-config surface and precedence behavior
+- **Polish (Phase 6)**: Depends on the desired user stories being complete and now also covers explicit source-selection and regeneration workflow updates
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: No dependency on other stories after Phase 2
+- **User Story 2 (P2)**: Depends on the project-config merge path from US1 and extends it to automation, overrides, and manifest isolation
+- **User Story 3 (P3)**: Depends on the supported config surface from US1 and the precedence rules from US2 so failure behavior matches the completed feature
+
+### Within Each User Story
+
+- Add or update verification tasks before implementation for that story
+- Land project-config loading and normalization before parity-sensitive generation changes
+- Complete precedence and failure-handling behavior before final docs and smoke validation
+
+### Parallel Opportunities
+
+- `T003` and `T004` can run in parallel during Setup
+- `T009` and `T010` can run in parallel after the foundational schema shape is settled
+- `T012` and `T013` can run in parallel once project-config mapping is defined
+- `T033`, `T034`, and `T035` can run in parallel after behavior is stable
+- `T040`, `T042`, and `T043` can run in parallel after the source-selection behavior is stable
+
+---
+
+## Parallel Example: User Story 1
+
+```bash
+Task: "Add composition parity coverage for project-config custom image and container definition inputs in tool/__tests__/composition.test.ts"
+Task: "Add parity coverage for environment-related settings and additional generated features in tool/__tests__/minimal-and-editor.test.ts"
+```
+
+## Parallel Example: Polish
+
+```bash
+Task: "Document project-config usage, parity scope, and supported customization examples in README.md"
+Task: "Document local and CI workflow examples for project config in docs/workflows.md"
+Task: "Document project-config parity examples and customization cases in docs/examples.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 project-config driven generation against equivalent clean-generation output
+5. Stop for review before extending into unattended and failure-handling behavior
+
+### Incremental Delivery
+
+1. Land project-config discovery, typing, and merge foundations
+2. Deliver User Story 1 for repository-root config driven generation with customization parity
+3. Add User Story 2 for automation, CLI overrides, no-config fallback, and manifest isolation
+4. Add User Story 3 for validation, ambiguity handling, and corrective guidance
+5. Finish docs, changelog, and full verification
+6. Add explicit source-selection and project-file regeneration follow-through so spec, plan, tasks, and CLI behavior stay aligned
+
+### Parallel Team Strategy
+
+1. One developer completes Setup and Foundational work
+2. After the project-config schema and merge path are stable, one developer can drive US1 implementation while another prepares the parity-focused verification cases
+3. After US1 is stable, the same command owner should complete US2 and US3 because they concentrate in `scripts/init.ts` and shared validation helpers
+
+---
+
+## Notes
+
+- All tasks use the required checklist format with IDs, optional `[P]` markers, story labels for story phases, and exact repo-relative file paths
+- The approved spec gate is already satisfied; execution readiness now depends on completing implementation, verification, and documentation tasks cleanly
+- Favor command-level and composition-level regression tests because the risk is user-visible generation behavior and customization parity drift

package/docs/team-workflow.md

@@ -33,6 +33,31 @@ my-project/
 
 ## Step-by-Step Setup
 
+### 0. Migrating an Existing Devcontainer (Optional)
+
+If you already have a hand-crafted `.devcontainer/`, use `adopt` to create the
+initial manifest automatically instead of writing it by hand:
+
+```bash
+# See what would be detected and generated (nothing is written)
+npx container-superposition adopt --dry-run
+
+# Run the adoption (writes superposition.json and custom/ patches)
+npx container-superposition adopt
+```
+
+`adopt` reads every feature URI, VS Code extension, and Docker Compose service
+image in your existing configuration and maps them to overlays. Anything with
+no overlay equivalent (custom features, project-specific services, custom
+mounts, unmatched environment variables, …) is written to
+`.devcontainer/custom/` so it survives every subsequent `regen`.
+
+`superposition.json` is written to the **project root** (not inside
+`.devcontainer/`), so it can be committed alongside your application code and
+shared with the rest of the team — matching the standard team workflow.
+
+See the [Adopt Command guide](adopt.md) for full details.
+
 ### 1. Create the Team Manifest
 
 The team lead or maintainer creates the initial manifest:
@@ -51,7 +76,7 @@ This creates `superposition.json` in the current directory:
 ```json
 {
     "manifestVersion": "1",
-    "generatedBy": "0.1.2",
+    "generatedBy": "X.Y.Z",
     "generated": "2026-02-17T14:00:00.000Z",
     "baseTemplate": "compose",
     "baseImage": "bookworm",
@@ -535,6 +560,7 @@ code .
 
 ## See Also
 
+- [Adopt Command](adopt.md) - Migrate an existing devcontainer to the overlay-based workflow
 - [Quick Reference](quick-reference.md) - Common commands and flags
 - [Overlay Documentation](overlays.md) - Available overlays
 - [Custom Patches](../tool/README.md#custom-patches) - Custom patch format