container-superposition 0.1.4 → 0.1.6

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

@@ -0,0 +1,213 @@
+# Implementation Plan: Project Configuration File
+
+**Branch**: `002-superposition-config-file` | **Date**: 2026-03-11 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `docs/specs/002-superposition-config-file/spec.md`
+
+**Note**: This plan follows the approved spec and constitution gates for the
+active feature branch.
+
+## Summary
+
+Add repository-root project config support so `init` and `regen` can load a
+committed `.superposition.yml` or `superposition.yml` as a persisted source of
+truth for supported generation flows, with full parity to supported generation
+inputs, including customization surfaces such as custom container definitions,
+environment-related settings, preset glue, and additional generated features.
+The design extends the existing answer-merging flow instead of creating a second
+generation pipeline, introduces an explicit `--from-project` mode, allows
+implicit project-file use for `init --no-interactive` and default `regen` when
+no conflicting source or selection flags are supplied, and keeps explicit
+manifest-based regeneration as a separate persisted-input mode. The same schema
+must also be writable from `adopt --project-file` so migration from an existing
+`.devcontainer/` can produce a repository-root project config without inventing
+a parallel declaration format. Persisted-input workflows must also support an
+explicit repository-root override so users can run `init` or `regen` against a
+different repository without first changing their shell working directory.
+
+## Technical Context
+
+**Language/Version**: TypeScript 5.3.3 on Node.js 20+  
+**Primary Dependencies**: Commander, chalk, boxen, js-yaml, ora, Inquirer  
+**Storage**: Filesystem-based project YAML config, `superposition.json`
+manifests, overlay manifests, templates, and generated devcontainer artifacts  
+**Testing**: Vitest unit and command tests, shell-based smoke tests, TypeScript
+compile checks  
+**Target Platform**: Node.js CLI on Linux, macOS, and Windows developer
+environments  
+**Project Type**: CLI scaffolding tool  
+**Performance Goals**: Keep project-config discovery plus validation under 200
+ms in representative repositories so initialization remains dominated by the
+existing generation work rather than config loading  
+**Constraints**: Preserve backward compatibility for interactive, flag-driven,
+explicit project-file, and explicit manifest-based flows; preserve source/dist
+path compatibility with candidate-path resolution; maintain full parity between
+supported clean generation inputs and project-config declarations; reject
+conflicting persisted-input source combinations before generation; keep
+ambiguity and validation failures user-facing and deterministic  
+**Scale/Scope**: Single feature spanning `scripts/init.ts`, shared schema/types,
+config-loading helpers, command and composition tests, documentation, and
+generation parity for supported customization inputs
+
+## Constitution Check
+
+_GATE: Must pass before Phase 0 research. Re-check after Phase 1 design and
+before implementation._
+
+- [x] Spec exists at `docs/specs/002-superposition-config-file/spec.md`.
+- [x] Spec is committed and reviewed before implementation tasks or code begin.
+- [x] Plan scope, compatibility impact, and complexity notes match the approved
+      spec.
+- [x] Verification scope covers tests, smoke checks, and documentation updates
+      needed for the change.
+- [x] User-visible changes include documentation updates and an `[Unreleased]`
+      `CHANGELOG.md` entry.
+
+Gate status: Pass. Planning may proceed.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+docs/specs/002-superposition-config-file/
+├── plan.md
+├── research.md
+├── data-model.md
+├── quickstart.md
+├── contracts/
+│   └── init-project-config.md
+└── tasks.md
+```
+
+### Source Code (repository root)
+
+```text
+scripts/
+└── init.ts
+
+tool/
+├── __tests__/
+│   ├── commands.test.ts
+│   ├── composition.test.ts
+│   ├── manifest-only.test.ts
+│   ├── minimal-and-editor.test.ts
+│   └── summary.test.ts
+├── questionnaire/
+│   └── composer.ts
+├── schema/
+│   ├── config.schema.json
+│   ├── project-config.ts
+│   └── types.ts
+└── utils/
+    └── summary.ts
+
+docs/
+├── examples.md
+├── workflows.md
+└── specs/
+
+README.md
+CHANGELOG.md
+```
+
+**Structure Decision**: Keep the feature centered on `scripts/init.ts`, because
+input discovery, CLI parsing, manifest handling, and answer merging already
+converge there. Add one focused schema/helper module for project-config
+discovery and validation, extend existing shared types for parity with clean
+generation inputs, and keep verification concentrated in existing command and
+composition test suites.
+
+## Phase 0: Research
+
+### Research Goals
+
+- Confirm the correct precedence between project config, direct command input,
+  interactive completion, explicit `--from-project`, implicit project-file
+  source selection, and explicit manifest mode.
+- Define what “full parity to clean generation” means for supported
+  customization inputs without introducing a second generation model.
+- Confirm discovery, ambiguity handling, and validation boundaries for a
+  repository-root YAML config.
+
+### Research Outputs
+
+- [research.md](research.md)
+
+## Phase 1: Design
+
+### Data Model
+
+- [data-model.md](data-model.md)
+
+### Contracts
+
+- [init-project-config.md](contracts/init-project-config.md)
+
+### Quickstart
+
+- [quickstart.md](quickstart.md)
+
+## Implementation Approach
+
+1. Add repository-root project-config discovery and validation to the standard
+   `init` flow and to `regen`, while keeping explicit manifest-based
+   regeneration behavior available as a separate mode.
+2. Model project config as another partial-answer source that feeds the existing
+   `QuestionnaireAnswers` merge path.
+3. Extend the supported config shape so it can declare every supported
+   clean-generation input, including customization surfaces already represented
+   in the current answer and generation flow.
+4. Add explicit source-selection validation so `--from-project` and
+   `--from-manifest` remain mutually exclusive and cannot be combined with
+   clean-generation selection flags such as stack, overlays, or preset choices.
+5. Preserve parity by ensuring project-config declarations yield the same final
+   generated output as equivalent direct user selections.
+6. Add regression coverage for no-config fallback, override precedence,
+   project-file based regen, explicit `--from-project`, manifest isolation,
+   source-conflict validation, invalid config handling, ambiguity detection, and
+   customization parity.
+7. Update docs and changelog entries so the declarative workflow, source
+   selection modes, and conflict rules are user-visible and auditable.
+
+## Verification Strategy
+
+- Add or update automated coverage for:
+    - repository-root project-config discovery
+    - no-config fallback behavior
+    - CLI-over-project-config precedence
+    - explicit `--from-project` behavior for `init` and `regen`
+    - implicit project-file selection for `init --no-interactive` and default
+      `regen`
+    - explicit manifest isolation from project-config defaults
+    - persisted-input source conflict validation (`--from-project`,
+      `--from-manifest`, and clean-generation selection flags)
+    - partial config completion through the existing questionnaire flow
+    - invalid YAML, unsupported keys or values, conflicts, and dual-file
+      ambiguity
+    - parity for supported customization inputs such as custom images, preset
+      glue, editor/minimal settings, environment-related settings, and additional
+      generated features
+- Run `npm test`.
+- Run `npm run lint`.
+- Run `npm run test:smoke` when generation behavior changes across representative
+  stacks.
+- Manually validate the scenarios in [quickstart.md](quickstart.md).
+
+## Post-Design Constitution Check
+
+- [x] Design preserves spec-first workflow and traces directly to the approved
+      spec.
+- [x] Design preserves overlay contract integrity by extending the existing
+      answer and generation pipeline rather than inventing a parallel path.
+- [x] Verification remains proportional to risk: automated tests, smoke
+      validation where applicable, and documentation updates are planned before
+      merge.
+- [x] Documentation synchronization is explicit: `README.md`,
+      `docs/workflows.md`, `docs/examples.md`, `quickstart.md`, and `CHANGELOG.md`.
+- [x] Simplicity and compatibility remain intact: project config is a default
+      persisted input source, explicit `--from-project` and explicit manifest
+      modes remain separate, and candidate-path compatibility stays required.
+
+## Complexity Tracking
+
+No constitution violations require a design exception.

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

@@ -0,0 +1,140 @@
+# Quickstart: Project Configuration File
+
+## Goal
+
+Use a committed repository-root config file to declare the same supported setup
+intent that users would otherwise provide through clean generation commands.
+
+## 1. Add one project config file at the repository root
+
+Choose exactly one:
+
+- `.superposition.yml`
+- `superposition.yml`
+
+Do not keep both in the same repository.
+
+## 2. Declare the intended environment
+
+Define the supported clean-generation inputs your project needs, such as:
+
+- stack
+- overlays
+- presets and preset parameters
+- output path
+- custom image or container definition
+- environment-related settings
+- additional generated features and other supported customization inputs
+
+## 3. Run standard initialization
+
+```bash
+npm run init
+```
+
+Expected result:
+
+- the project config file supplies default generation intent
+- only still-missing required values are collected interactively
+- the generated output matches the declared setup and supported customization
+  settings
+
+## 4. Override a value for one run
+
+```bash
+npm run init -- --output ./tmp-devcontainer
+```
+
+Expected result:
+
+- the direct command value wins for that run only
+- the committed project config remains the default source of truth
+
+## 5. Use the same config in automation
+
+Run initialization from CI or another scripted workflow in a repository that
+contains the committed project config.
+
+Expected result:
+
+- non-interactive runs use declared defaults without prompting for already
+  declared values
+- repeated runs resolve the same configuration
+
+## 6. Regenerate from the project file
+
+```bash
+npm run init -- regen
+```
+
+Expected result:
+
+- `regen` uses the repository project file when one exists
+- the command does not require `--from-project` in that default case
+- the generated output matches the project file's declared intent
+
+## 7. Preserve explicit manifest regeneration
+
+```bash
+npm run init -- --from-manifest ./.devcontainer/superposition.json --no-interactive
+```
+
+Expected result:
+
+- the manifest remains the persisted input source for that run
+- repository project config does not silently override it
+
+## 8. Reject conflicting source modes early
+
+```bash
+npm run init -- init --from-project --stack compose
+```
+
+Expected result:
+
+- the command fails before generation
+- the error explains that persisted-input source flags cannot be mixed with
+  clean-generation selection flags
+
+## 9. Validate parity for supported customization inputs
+
+For any supported customization input that can be expressed through the existing
+clean-generation path:
+
+- declare it in the project config file
+- run generation
+- confirm the final generated output matches the equivalent clean-generation
+  result
+
+Examples of parity checks:
+
+- custom image or container definition
+- environment-related settings
+- preset glue values
+- additional generated features
+
+## 10. Maintainer workflow review
+
+Review result for `SC-003`:
+
+- a maintainer can create or update `.superposition.yml`, run `npm run init -- --no-interactive`, and inspect the generated output without reconstructing a long command
+- the documented workflow keeps the committed project config as the source of truth while still allowing one-run CLI overrides
+
+## 11. Verification record
+
+Validated during implementation:
+
+- targeted regression tests for project-config discovery, precedence, manifest isolation, no-config fallback, and customization parity
+- targeted regression tests for explicit `--from-project`, implicit project-file
+  `regen`, and source-conflict validation
+- `npm test`
+- `npm run lint`
+- `npm run test:smoke`
+
+Observed outcomes:
+
+- valid project-config driven runs generated the expected manifest and devcontainer output
+- `regen` used the repository project file by default when present and still
+  allowed explicit manifest-based regeneration
+- `--no-interactive` now works with a repository-root project config and still fails without any persisted input source
+- explicit `--from-manifest` runs ignored repository project-config defaults as required

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,136 @@
+# 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.
+3. **Given** a repository with an existing hand-crafted `.devcontainer/`, **When** a maintainer runs `adopt --project-file`, **Then** the tool writes a repository-root project config that captures the inferred stack, overlay selections, output path, and supported customization inputs from the adopted setup.
+4. **Given** a maintainer is working outside the target repository, **When** they run `init --from-project --project-root <path>` or `regen --project-root <path>`, **Then** the tool resolves the project file and relative output paths from that selected repository root.
+
+---
+
+### 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.
+- How does the system handle `adopt --project-file` when a repository already contains a supported project config file? It reuses that file path, and it must still stop on dual-file ambiguity so the source of truth stays deterministic.
+- How does the system handle project-file or manifest discovery from outside the target repository? An explicit project-root option may redirect persisted-input discovery and relative output resolution to that repository root.
+
+## 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.
+- **FR-020**: The system MUST allow `adopt --project-file` to write a repository-root project config that represents the inferred adopted setup using the same supported declaration surface as other project-config workflows.
+- **FR-021**: The system MUST allow `init` and `regen` to resolve project-file and manifest discovery from an explicitly selected repository root so users can run persisted-input workflows without changing their shell working directory first.
+
+### 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.