container-superposition 0.1.3 → 0.1.5

package/docs/specs/001-verbose-plan-graph/contracts/plan-verbose-output.md

@@ -0,0 +1,96 @@
+# Contract: Plan Verbose Output
+
+## Scope
+
+This contract defines the user-visible behavior of the `plan` command when `--verbose` is requested. It covers terminal output and structured JSON output for the normal planning path.
+
+## Command Surface
+
+### New Option
+
+- `--verbose`: Include dependency-resolution narration that explains why each overlay appears in the final plan.
+
+### Existing Manifest Input
+
+- Manifest-driven planning must support the existing manifest workflow and apply `--verbose` when overlays are loaded from `superposition.json`.
+
+### Compatibility Rules
+
+- `plan` without `--verbose` keeps the existing concise output contract.
+- `plan --json --verbose` returns the standard plan data plus structured explanation data.
+- `plan` run from an existing manifest with `--verbose` uses the same explanation structure as overlay-list-driven planning.
+- `plan --diff` remains a separate mode; verbose planning must not silently change diff semantics.
+
+## Text Output Contract
+
+When `--verbose` is present and the command completes normal planning:
+
+1. The standard summary remains visible:
+    - stack
+    - overlays selected
+    - auto-added dependencies
+    - conflicts, if any
+    - port mappings
+    - files to create/modify
+2. A dedicated explanation section appears after the overlay summary.
+3. The explanation section must:
+    - identify each included overlay exactly once
+    - state whether it was selected directly or added automatically
+    - treat manifest-defined overlays as the explicit root configuration when planning is loaded from a manifest
+    - name the parent overlay or overlays that required it
+    - show transitive chains in request-to-dependency order
+    - call out failure boundaries when conflicts or invalid selections prevent successful completion
+
+### Example Shape
+
+```text
+Dependency Resolution:
+  nodejs
+    selected directly by the user
+  grafana
+    selected directly by the user
+  prometheus
+    required by grafana
+    path: grafana -> prometheus
+```
+
+The wording may vary, but the content requirements above are mandatory.
+
+## JSON Output Contract
+
+When `--json --verbose` is present, the result must include:
+
+- the existing standard plan fields
+- an additional explanation payload that:
+    - records whether the plan input came from explicit overlays or a manifest
+    - lists each included overlay once
+    - distinguishes direct selections from dependency-driven inclusions
+    - records one or more parent reasons for dependencies with shared ancestry
+    - includes ordered dependency paths for transitive inclusions
+    - optionally records failure context when planning cannot complete normally
+
+### Minimum Field Expectations
+
+The verbose payload must support these questions without requiring text parsing:
+
+- Was this overlay selected by the user or added automatically?
+- Which overlay or overlays caused this inclusion?
+- What dependency path led to this overlay?
+- Did resolution stop or skip anything, and why?
+
+## Error and Failure Contract
+
+- Unknown overlay IDs remain hard failures.
+- Missing or invalid manifests remain hard failures for manifest-driven planning.
+- Conflicts remain visible in both concise and verbose modes.
+- Verbose mode adds context about the dependency path and failure boundary; it does not suppress or soften existing error behavior.
+
+## Documentation Contract
+
+The command reference and examples must show:
+
+- one direct-selection example
+- one manifest-driven verbose example
+- one auto-added dependency example
+- one transitive or multi-parent explanation example
+- one note confirming that default `plan` output stays concise without `--verbose`

package/docs/specs/001-verbose-plan-graph/data-model.md

@@ -0,0 +1,111 @@
+# Data Model: Verbose Plan Graph
+
+## Entity: PlanRequest
+
+**Purpose**: Describes a single `plan` invocation and the presentation options that shape the response.
+
+**Fields**:
+
+- `stack`: requested base template type
+- `selectedOverlayIds`: user-provided overlay IDs after trimming and de-duplication
+- `manifestPath`: optional path to an existing `superposition.json` manifest
+- `manifestOverlayIds`: overlays loaded from a manifest when manifest-driven planning is used
+- `portOffset`: optional numeric port offset
+- `jsonRequested`: whether structured output is requested
+- `diffRequested`: whether diff mode is requested
+- `verboseRequested`: whether dependency narration is requested
+- `outputPath`: optional comparison target for diff mode
+
+**Validation rules**:
+
+- `stack` must be present and valid for the command
+- `selectedOverlayIds` must contain only known overlay IDs
+- duplicate overlay IDs are normalized before planning
+- manifest-driven requests must resolve to a valid manifest before explanation data is generated
+- `verboseRequested` must not change resolution behavior, only presentation and additional metadata
+
+## Entity: IncludedOverlay
+
+**Purpose**: Represents one overlay that appears in the resolved final plan.
+
+**Fields**:
+
+- `id`: stable overlay identifier
+- `displayName`: human-readable overlay name if available
+- `selectionKind`: `direct` or `dependency` based on how the overlay first entered the resolved set
+- `selectionSource`: `command-line`, `manifest`, or `dependency`
+- `reasons`: one or more inclusion reasons attached to this overlay
+- `dependencyPaths`: one or more ordered paths from a direct selection to this overlay
+- `compatibleWithStack`: whether the overlay remains in the final stack-specific plan
+
+**Validation rules**:
+
+- each included overlay appears only once in the final resolved set
+- `reasons` must contain at least one entry
+- `dependencyPaths` may have multiple entries when multiple parents lead to the same overlay
+- if `selectionKind` is `direct`, at least one reason must identify the user request as the source
+- if `selectionSource` is `manifest`, at least one reason must identify the manifest-defined root set as the source
+
+## Entity: InclusionReason
+
+**Purpose**: Explains why a single overlay was kept in the plan.
+
+**Fields**:
+
+- `kind`: `selected`, `required`, `transitive`, or `skipped`
+- `origin`: `command-line` or `manifest`
+- `sourceOverlayId`: the overlay that directly caused this reason, if applicable
+- `rootOverlayId`: the original user-selected overlay at the start of the path
+- `message`: user-facing explanation text
+- `depth`: number of dependency edges between the root selection and the included overlay
+
+**Validation rules**:
+
+- direct selections use `kind: selected` and `depth: 0`
+- manifest-defined root overlays also use `kind: selected` and `depth: 0`
+- dependency-driven inclusions must include `sourceOverlayId`
+- transitive reasons must include both `sourceOverlayId` and `rootOverlayId`
+- failure or skip reasons must remain attached to the affected overlay or attempted overlay so users can identify the boundary condition
+
+## Entity: DependencyPath
+
+**Purpose**: Captures the ordered chain from a requested overlay to an included dependency.
+
+**Fields**:
+
+- `rootOverlayId`: directly selected starting overlay
+- `segments`: ordered overlay IDs showing the path from root to final overlay
+- `finalOverlayId`: included overlay reached by the path
+
+**Validation rules**:
+
+- `segments[0]` must match `rootOverlayId`
+- `segments[segments.length - 1]` must match `finalOverlayId`
+- repeated paths for the same overlay should be de-duplicated before output
+
+## Entity: VerbosePlanOutput
+
+**Purpose**: Extends the standard plan result with explanation data when verbose mode is requested.
+
+**Fields**:
+
+- `standardPlan`: the existing plan summary data
+- `includedOverlays`: ordered list of `IncludedOverlay` records for human and JSON rendering
+- `resolutionSummary`: concise summary of how many overlays were selected directly vs added automatically
+- `failureContext`: optional description of the point where planning stopped or skipped overlays
+- `inputMode`: `overlay-list` or `manifest`
+
+**Relationships**:
+
+- one `PlanRequest` produces one `VerbosePlanOutput`
+- one `PlanRequest` may be sourced from explicit overlay flags or a manifest
+- one `VerbosePlanOutput` contains many `IncludedOverlay` records
+- one `IncludedOverlay` contains many `InclusionReason` records and zero or more `DependencyPath` records
+
+## State Notes
+
+- Resolution begins with the user-selected overlays.
+- Resolution begins with either the user-selected overlays or the manifest-defined overlay roots.
+- Dependencies are added recursively as required relationships are traversed.
+- Stack compatibility filtering may remove overlays from the final renderable set after dependency discovery.
+- Conflict detection runs against the resolved compatible set and may attach failure context to the verbose result.

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

@@ -0,0 +1,127 @@
+# Implementation Plan: Verbose Plan Graph
+
+**Branch**: `001-verbose-plan-graph` | **Date**: 2026-03-10 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `/docs/specs/001-verbose-plan-graph/spec.md`
+
+## Summary
+
+Extend the `plan` command so `--verbose` explains dependency resolution for both direct overlay selection and manifest-driven planning from an existing `superposition.json`. The design must keep one shared resolution and explanation model so text output, JSON output, and manifest-based workflows stay consistent.
+
+## Technical Context
+
+**Language/Version**: TypeScript 5.3.3 on Node.js 20+  
+**Primary Dependencies**: Commander, chalk, boxen, js-yaml, ora, Inquirer  
+**Storage**: Filesystem-based overlay manifests, project `superposition.json` 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**: Preserve the current fast interactive feel of the `plan` command for typical overlay selections and avoid introducing noticeable delay when verbose explanation is enabled  
+**Constraints**: Preserve current concise output unless `--verbose` is requested; preserve source/dist path compatibility patterns; keep manifest-driven and overlay-list-driven planning aligned to one resolved overlay set; keep JSON and text views consistent  
+**Scale/Scope**: Single command enhancement affecting `scripts/init.ts`, `tool/commands/plan.ts`, command tests, user-facing docs, and manifest-driven planning behavior
+
+## Constitution Check
+
+_GATE: Must pass before Phase 0 research. Re-check after Phase 1 design and before implementation._
+
+- [x] Spec exists at `docs/specs/001-verbose-plan-graph/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.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+docs/specs/001-verbose-plan-graph/
+├── plan.md
+├── research.md
+├── data-model.md
+├── quickstart.md
+├── contracts/
+│   └── plan-verbose-output.md
+└── tasks.md
+```
+
+### Source Code (repository root)
+
+```text
+scripts/
+└── init.ts
+
+tool/
+├── commands/
+│   └── plan.ts
+├── __tests__/
+│   └── commands.test.ts
+├── schema/
+└── utils/
+
+docs/
+├── discovery-commands.md
+└── specs/
+
+README.md
+CHANGELOG.md
+```
+
+**Structure Decision**: Keep the existing CLI structure centered on `scripts/init.ts` for command options and manifest-loading hooks, and `tool/commands/plan.ts` for shared planning logic. Keep verification concentrated in `tool/__tests__/commands.test.ts`, with documentation updates in `README.md` and `docs/discovery-commands.md`.
+
+## Phase 0: Research
+
+### Research Goals
+
+- Confirm the simplest way to reuse the verbose explanation model for manifest-driven planning.
+- Decide how manifest-loaded overlays should appear in explanation data relative to directly requested overlays.
+- Confirm failure behavior for missing or invalid manifests in verbose mode.
+
+### Research Outputs
+
+- [research.md](research.md)
+
+## Phase 1: Design
+
+### Data Model
+
+- [data-model.md](data-model.md)
+
+### Contracts
+
+- [plan-verbose-output.md](contracts/plan-verbose-output.md)
+
+### Quickstart
+
+- [quickstart.md](quickstart.md)
+
+## Implementation Approach
+
+1. Extend `plan` input handling so it can build the same verbose explanation model whether overlays come from explicit flags or an existing manifest.
+2. Reuse one dependency-resolution and explanation path inside `tool/commands/plan.ts` for concise, verbose, JSON, and manifest-driven planning.
+3. Define manifest-aware explanation semantics so manifest-defined overlays remain distinguishable from auto-added dependencies without inventing a separate output format.
+4. Add regression tests for manifest-driven verbose text output, verbose JSON output, and manifest failure paths.
+5. Update README, discovery docs, quickstart guidance, and changelog entries to document manifest-driven verbose planning.
+
+## Verification Strategy
+
+- Add or update command tests in `tool/__tests__/commands.test.ts` for:
+    - verbose text output from direct overlay selection
+    - verbose text output from an existing manifest
+    - verbose JSON output from an existing manifest
+    - manifest failure behavior when the manifest is missing, invalid, or contains invalid overlays
+    - non-verbose output remaining unchanged
+- Run `npm test` for automated coverage.
+- Run `npm run lint` to verify TypeScript and formatting constraints.
+- Perform targeted manual validation using the commands documented in `quickstart.md`, including manifest-driven scenarios.
+
+## Post-Design Constitution Check
+
+- [x] Design still preserves spec-first workflow and traces directly to the approved spec.
+- [x] The planned change preserves overlay contract integrity by extending the existing planning model rather than creating a parallel manifest-only explanation path.
+- [x] Verification remains proportional to risk: command tests plus documentation updates are planned before merge.
+- [x] Documentation synchronization is explicitly included: `README.md`, `docs/discovery-commands.md`, `quickstart.md`, and `CHANGELOG.md`.
+- [x] Simplicity and compatibility remain intact: verbose mode stays opt-in and manifest-driven planning uses the same reasoning model as direct selection.
+
+## Complexity Tracking
+
+No constitution violations require a design exception.

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

@@ -0,0 +1,106 @@
+# Quickstart: Verbose Plan Graph
+
+## Goal
+
+Validate that the `plan` command can explain dependency inclusion reasons for both direct overlay selection and existing manifest workflows without changing its default concise behavior.
+
+## Prerequisites
+
+- Repository dependencies installed
+- Working tree on branch `001-verbose-plan-graph`
+
+## Validation Steps
+
+1. Run the existing concise plan and confirm no narration appears:
+
+```bash
+npm run init -- plan --stack compose --overlays grafana
+```
+
+Expected result:
+
+- Standard plan summary appears
+- `Auto-Added Dependencies` includes `prometheus`
+- No dependency narration section is shown
+
+2. Run the verbose text plan for a direct dependency:
+
+```bash
+npm run init -- plan --stack compose --overlays grafana --verbose
+```
+
+Expected result:
+
+- Standard summary still appears
+- A dependency narration section explains:
+    - `grafana` was selected directly
+    - `prometheus` was included because `grafana` requires it
+
+3. Run the verbose JSON plan and inspect explanation data:
+
+```bash
+npm run init -- plan --stack compose --overlays grafana --json --verbose
+```
+
+Expected result:
+
+- JSON remains valid
+- Standard plan fields are still present
+- Structured explanation data identifies direct vs dependency-driven inclusions
+
+4. Run the verbose plan from an existing manifest:
+
+```bash
+npm run init -- --from-manifest .devcontainer/superposition.json --no-interactive
+npm run init -- plan --from-manifest .devcontainer/superposition.json --verbose
+```
+
+Expected result:
+
+- The plan loads overlays from the manifest without re-entering them manually
+- The verbose explanation treats manifest-defined overlays as the explicit root set
+- Auto-added dependencies are still explained separately from manifest-defined overlays
+
+5. Run the automated regression suite:
+
+```bash
+npm test
+npm run lint
+```
+
+Expected result:
+
+- Updated command tests pass
+- TypeScript and formatting checks pass
+
+## Manual Edge Checks
+
+- Multi-parent dependency case: choose overlays that share a required dependency and confirm the dependency appears once with multiple reasons.
+- Stack-incompatible case: run a compose-only overlay against `--stack plain` with `--verbose` and confirm the skip reason and dependency path are shown.
+- Manifest case: run a verbose plan from an existing `superposition.json` and confirm the explanation covers both manifest-defined overlays and auto-added dependencies.
+- Conflict case: run a known conflicting pair with `--verbose` and confirm the failure context explains why the command cannot proceed.
+
+## Validation Log
+
+Validated on 2026-03-10:
+
+- `npm run init -- plan --stack compose --overlays grafana`
+    - Confirmed the concise plan output remains unchanged and still auto-adds `prometheus`
+- `npm run init -- plan --stack compose --overlays grafana --verbose`
+    - Confirmed verbose output adds a `Dependency Resolution` section with direct-selection and required-dependency reasons
+- `npm run init -- plan --stack compose --overlays grafana --json --verbose`
+    - Confirmed JSON output remains valid and adds a `verbose` object with inclusion reasons and summary counts
+- `npm run init -- plan --from-manifest .devcontainer/superposition.json --verbose`
+    - Confirmed manifest-driven verbose output treats manifest overlays as the root set and still explains manifest-triggered dependencies like `codex -> nodejs`
+- `npm run init -- plan --from-manifest .devcontainer/superposition.json --json --verbose`
+    - Confirmed JSON output records `inputMode: "manifest"` and marks manifest-defined overlays with `selectionSource: "manifest"`
+- `npm run init -- plan --stack compose --overlays docker-in-docker,docker-sock --verbose`
+    - Confirmed verbose output adds `Resolution Notes` for the conflict boundary before the command exits with the existing conflict failure
+- `npm run init -- plan --stack plain --overlays grafana --verbose`
+    - Confirmed verbose output reports stack-incompatible skip reasons for both `grafana` and its required dependency `prometheus`
+- `npm test -- tool/__tests__/commands.test.ts`
+    - Passed after adding verbose coverage for direct, transitive, multi-parent, conflict, and invalid-selection behavior
+- `npm test`
+    - Passed across the full Vitest suite after the verbose plan changes and documentation updates
+- `npm run lint`
+    - Passed after formatting the remaining repository files that were part of the active verification surface

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

@@ -0,0 +1,100 @@
+# Research: Verbose Plan Graph
+
+## Decision 1: Attach explanation data to the existing dependency resolver
+
+**Decision**: Extend the current `plan` dependency-resolution flow so it records inclusion reasons while producing the same resolved overlay set used by normal text and JSON output.
+
+**Rationale**: `tool/commands/plan.ts` already resolves dependencies and feeds both text and JSON views. Reusing that path avoids divergence where verbose mode could explain a different result than the standard plan.
+
+**Alternatives considered**:
+
+- Build a separate explanation pass after resolution: rejected because it duplicates traversal logic and risks drifting from the actual resolver.
+- Infer reasons only from `autoAddedOverlays`: rejected because it cannot represent transitive chains or multi-parent dependencies clearly enough.
+
+## Decision 2: Model overlay inclusion as one final entry with one or more reasons
+
+**Decision**: Represent each included overlay once, with attached reason records that indicate whether it was directly selected, required by another overlay, or reached through a transitive chain.
+
+**Rationale**: The spec requires no duplicate final inclusion entries, even when a dependency is reached by multiple parents. A single overlay record with multiple reasons meets that requirement and keeps both text and JSON outputs easy to consume.
+
+**Alternatives considered**:
+
+- Emit one explanation row per path: rejected because the same overlay would appear multiple times and make the final resolved set harder to read.
+- Keep only the first discovered reason: rejected because it hides valid parent relationships when multiple overlays require the same dependency.
+
+## Decision 3: Keep verbose output opt-in and additive
+
+**Decision**: Show the new explanation section only when `--verbose` is present, while leaving default text output unchanged.
+
+**Rationale**: The existing `plan` command is a concise preview tool, and the spec explicitly requires backward-compatible default behavior. Opt-in narration preserves scanability for current users.
+
+**Alternatives considered**:
+
+- Always show inclusion reasons: rejected because it would alter the established command output and add noise to the common case.
+- Replace the existing auto-added summary with verbose narration: rejected because it would collapse the quick summary and the detailed explanation into one harder-to-scan format.
+
+## Decision 4: Expose explanation data in JSON only when verbose mode is requested
+
+**Decision**: Add structured inclusion-reason data to the JSON plan payload when `--json` and `--verbose` are both present; preserve the existing JSON shape otherwise.
+
+**Rationale**: Scripted consumers need access to the same reasoning as human readers, but existing JSON users should not be forced to adapt to new fields unless they explicitly request verbose mode.
+
+**Alternatives considered**:
+
+- Always add explanation fields to JSON: rejected because it changes the default contract for existing automation.
+- Omit explanation data from JSON entirely: rejected because the spec requires structured verbose output for scripted consumers.
+
+## Decision 5: Treat conflicts and invalid input as explanation boundaries, not silent failures
+
+**Decision**: When resolution fails due to conflicts, unsupported overlays, or invalid overlay IDs, verbose mode should explain the last valid inclusion context and then identify the reason the plan cannot proceed.
+
+**Rationale**: The feature principle is that nothing should feel magical. Users need to know where resolution stopped and why, especially when the command refuses to proceed.
+
+**Alternatives considered**:
+
+- Fall back to the existing failure messages without verbose context: rejected because it leaves the explanation incomplete in the scenarios where users most need it.
+- Produce partial verbose output without marking the failure boundary: rejected because it could imply that the plan completed successfully.
+
+## Decision 6: Verification should focus on command behavior, not only the helper function
+
+**Decision**: Cover the new mode primarily with `planCommand` tests in `tool/__tests__/commands.test.ts`, supported by existing unit-level confidence around the command module.
+
+**Rationale**: The user-visible risk is in the final text/JSON behavior and backward compatibility of the command surface. Command-level tests exercise option handling, output shaping, and failure behavior together.
+
+**Alternatives considered**:
+
+- Test only low-level resolver helpers: rejected because it would miss regressions in the rendered CLI and JSON contracts.
+- Rely on manual validation alone: rejected because the change is user-visible and should be guarded by repeatable regression tests.
+
+## Decision 7: Manifest-driven planning should reuse the same explanation model
+
+**Decision**: When `plan` is run from an existing `superposition.json` manifest, verbose output should use the same inclusion-reason model and rendering rules as overlay-list-driven planning.
+
+**Rationale**: Users should not receive different explanations depending on whether overlays were provided as flags or loaded from a manifest. One model keeps the output easier to reason about and reduces the risk of semantic drift.
+
+**Alternatives considered**:
+
+- Create a manifest-specific explanation mode: rejected because it would duplicate logic and force users to learn two explanation formats.
+- Treat manifest-defined overlays as opaque input with no per-overlay reasoning: rejected because it violates the “nothing here is magic” principle.
+
+## Decision 8: Manifest-defined overlays should be explained as the explicit starting set
+
+**Decision**: In manifest-driven verbose planning, overlays loaded from the manifest should be treated as the explicit root selection set for explanation purposes, while still distinguishing auto-added dependencies from those roots.
+
+**Rationale**: The user did not type the overlays on the current command line, but they are still part of an explicit saved configuration. Treating them as the root set preserves explainability without forcing users to re-enter them.
+
+**Alternatives considered**:
+
+- Label manifest overlays as dependencies: rejected because it misstates user intent and blurs the line between saved configuration and auto-resolved requirements.
+- Add a third top-level selection mode with separate rendering rules: rejected because it adds conceptual weight without improving user value.
+
+## Decision 9: Manifest failure should stop explanation before partial output is emitted
+
+**Decision**: Missing, invalid, or semantically broken manifests should fail before verbose explanation output is produced, with a clear message explaining why planning cannot continue.
+
+**Rationale**: A broken manifest means the plan has no trustworthy starting configuration. Producing partial verbose output in that state would make the command feel unreliable.
+
+**Alternatives considered**:
+
+- Emit partial verbose output for valid fragments of the manifest: rejected because partial planning from invalid input is misleading.
+- Reconstruct overlays heuristically when the manifest is malformed: rejected because it adds hidden behavior and weakens trust.