container-superposition 0.1.4 → 0.1.6

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.

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

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