container-superposition 0.1.4 → 0.1.5

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.

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

@@ -0,0 +1,223 @@
+# Tasks: Verbose Plan Graph
+
+**Input**: Design documents from `/docs/specs/001-verbose-plan-graph/`
+**Prerequisites**: [plan.md](plan.md), [spec.md](spec.md), [research.md](research.md), [data-model.md](data-model.md), [plan-verbose-output.md](contracts/plan-verbose-output.md), [quickstart.md](quickstart.md)
+
+**Tests**: Add automated command-level coverage in `tool/__tests__/commands.test.ts`, then run manual quickstart validation plus `npm test` and `npm run lint`.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g. `US1`, `US2`, `US3`)
+- Include exact file paths in descriptions
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Record the approved governance state and prepare the command surface for the expanded scope.
+
+- [x] T001 Record approved spec commit status and review gate in `docs/specs/001-verbose-plan-graph/spec.md`
+- [x] T002 Align implementation sequencing notes for the manifest-driven scope in `docs/specs/001-verbose-plan-graph/plan.md`
+- [x] T003 Update `plan` command option and argument wiring for manifest-driven verbose planning in `scripts/init.ts`
+- [x] T004 Record the revised implementation baseline and pending manifest validation in `docs/specs/001-verbose-plan-graph/quickstart.md`
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Build the shared request normalization and explanation model that every story depends on.
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+- [x] T005 Refactor plan request normalization to support overlay-list and manifest inputs in `tool/commands/plan.ts`
+- [x] T006 Define shared inclusion-reason and dependency-path helpers for all plan modes in `tool/commands/plan.ts`
+- [x] T007 Define shared verbose JSON payload shaping for overlay-list and manifest inputs in `tool/commands/plan.ts`
+- [x] T008 Add baseline regression coverage for request parsing and shared plan payload behavior in `tool/__tests__/commands.test.ts`
+- [x] T009 Add fixture support for manifest-driven command tests in `tool/__tests__/commands.test.ts`
+
+**Checkpoint**: Foundation ready - user story implementation can now begin following the documented story dependencies
+
+---
+
+## Phase 3: User Story 1 - Explain auto-included overlays (Priority: P1) 🎯 MVP
+
+**Goal**: Let users see why directly selected overlays and auto-added required dependencies appear in the final plan.
+
+**Independent Test**: Run `npm run init -- plan --stack compose --overlays grafana --verbose` and confirm the output explains `grafana` as directly selected and `prometheus` as required by `grafana`, without duplicate overlay entries.
+
+### Verification for User Story 1
+
+- [x] T010 [US1] Add verbose text-output regression coverage for direct selections and required dependencies in `tool/__tests__/commands.test.ts`
+- [x] T011 [US1] Add verbose JSON regression coverage for direct selections and required dependencies in `tool/__tests__/commands.test.ts`
+
+### Implementation for User Story 1
+
+- [x] T012 [US1] Implement direct-selection explanation records for overlay-list planning in `tool/commands/plan.ts`
+- [x] T013 [US1] Implement required-dependency explanation records for overlay-list planning in `tool/commands/plan.ts`
+- [x] T014 [US1] Render the verbose dependency narration section for direct overlay selection in `tool/commands/plan.ts`
+- [x] T015 [US1] Attach verbose inclusion-reason data to JSON plan output for direct overlay selection in `tool/commands/plan.ts`
+
+**Checkpoint**: User Story 1 should now be fully functional and testable on its own
+
+---
+
+## Phase 4: User Story 2 - Explain plans loaded from a manifest (Priority: P2)
+
+**Goal**: Let users run `plan --verbose` from an existing `superposition.json` manifest and receive the same explanation quality they get from direct overlay selection.
+
+**Independent Test**: Run `npm run init -- plan --from-manifest superposition.json --verbose` and confirm the explanation treats manifest-defined overlays as the root set while still explaining auto-added dependencies separately.
+
+### Verification for User Story 2
+
+- [x] T016 [US2] Add regression coverage for verbose text output from manifest-driven planning in `tool/__tests__/commands.test.ts`
+- [x] T017 [US2] Add regression coverage for verbose JSON output from manifest-driven planning in `tool/__tests__/commands.test.ts`
+- [x] T018 [US2] Add regression coverage for missing, invalid, and semantically broken manifests in `tool/__tests__/commands.test.ts`
+
+### Implementation for User Story 2
+
+- [x] T019 [US2] Load manifest-defined overlay roots into the shared plan request model in `tool/commands/plan.ts`
+- [x] T020 [US2] Implement manifest-root explanation records that distinguish saved configuration from dependency-driven inclusions in `tool/commands/plan.ts`
+- [x] T021 [US2] Prevent partial verbose output when manifest-driven planning fails in `tool/commands/plan.ts`
+- [x] T022 [US2] Render manifest-driven verbose narration using the shared explanation model in `tool/commands/plan.ts`
+- [x] T023 [US2] Attach manifest input metadata to verbose JSON plan output in `tool/commands/plan.ts`
+
+**Checkpoint**: User Stories 1 and 2 should both work independently
+
+---
+
+## Phase 5: User Story 3 - Trace the full dependency path (Priority: P3)
+
+**Goal**: Let users follow transitive dependency chains and shared-parent paths in both direct and manifest-driven planning without guessing how the final plan was assembled.
+
+**Independent Test**: Run `plan --verbose` for overlays that create transitive or shared-parent dependencies and confirm each included overlay appears once with traceable path information, regardless of whether the roots came from flags or a manifest.
+
+### Verification for User Story 3
+
+- [x] T024 [US3] Add regression coverage for transitive dependency path narration in `tool/__tests__/commands.test.ts`
+- [x] T025 [US3] Add regression coverage for shared-parent dependency explanations without duplicate overlay entries in `tool/__tests__/commands.test.ts`
+
+### Implementation for User Story 3
+
+- [x] T026 [US3] Extend inclusion-reason tracking for transitive dependency paths in `tool/commands/plan.ts`
+- [x] T027 [US3] Preserve multiple parent reasons while de-duplicating final overlay entries in `tool/commands/plan.ts`
+- [x] T028 [US3] Render ordered dependency paths in verbose text output for overlay-list and manifest inputs in `tool/commands/plan.ts`
+- [x] T029 [US3] Serialize transitive paths and multi-parent reasons in verbose JSON output in `tool/commands/plan.ts`
+
+**Checkpoint**: User Stories 1 through 3 should all be independently functional
+
+---
+
+## Phase 6: User Story 4 - Preserve concise output when not needed (Priority: P4)
+
+**Goal**: Keep the default plan experience concise while surfacing verbose failure context only when users explicitly request it.
+
+**Independent Test**: Compare `plan` output with and without `--verbose`, then run conflict, invalid-overlay, and stack-incompatible cases with `--verbose` and confirm concise mode is unchanged while verbose mode adds failure context.
+
+### Verification for User Story 4
+
+- [x] T030 [US4] Add regression coverage confirming non-verbose text and JSON output remain unchanged for overlay-list and manifest inputs in `tool/__tests__/commands.test.ts`
+- [x] T031 [US4] Add regression coverage for verbose conflict, invalid-overlay, and stack-incompatible skip context in `tool/__tests__/commands.test.ts`
+
+### Implementation for User Story 4
+
+- [x] T032 [US4] Gate verbose narration so it only renders when `--verbose` is present in `tool/commands/plan.ts`
+- [x] T033 [US4] Add verbose failure-boundary explanations for conflicts, invalid overlays, stack-incompatible skips, and manifest failures in `tool/commands/plan.ts`
+- [x] T034 [US4] Ensure concise summary and verbose explanation reuse the same resolved overlay set in `tool/commands/plan.ts`
+
+**Checkpoint**: All user stories should now be independently functional
+
+---
+
+## Phase 7: Polish & Cross-Cutting Concerns
+
+**Purpose**: Finish docs, changelog, and end-to-end verification for the expanded scope.
+
+- [x] T035 [P] Document direct-selection and manifest-driven `--verbose` examples in `README.md`
+- [x] T036 [P] Document manifest-driven verbose planning behavior and examples in `docs/discovery-commands.md`
+- [x] T037 Update the user-visible change summary for manifest-driven verbose planning in `CHANGELOG.md`
+- [x] T038 Update validation steps and outcomes for manifest-driven planning in `docs/specs/001-verbose-plan-graph/quickstart.md`
+- [x] T039 Run automated verification with `npm test` and `npm run lint`, then record the results in `docs/specs/001-verbose-plan-graph/quickstart.md`
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: Starts immediately
+- **Foundational (Phase 2)**: Depends on Setup completion and blocks all story work
+- **User Story 1 (Phase 3)**: Depends on Foundational completion
+- **User Story 2 (Phase 4)**: Depends on Foundational completion and should follow US1 because it extends the same command surface and explanation model to manifest inputs
+- **User Story 3 (Phase 5)**: Depends on Foundational completion and should follow US1 and US2 because it builds on the shared explanation records across both input modes
+- **User Story 4 (Phase 6)**: Depends on Foundational completion and should land after US1 through US3 because it validates backward compatibility and failure behavior across the full verbose path
+- **Polish (Phase 7)**: Depends on the desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: No dependency on other stories after Phase 2
+- **User Story 2 (P2)**: Depends on the shared explanation data from Phase 2 and should follow US1 once direct-selection verbose records are stable
+- **User Story 3 (P3)**: Depends on the verbose output path from US1 and the manifest-root model from US2
+- **User Story 4 (P4)**: Depends on the full verbose path from US1 through US3 so concise-mode and failure-boundary regressions are measured against the completed behavior
+
+### Within Each User Story
+
+- Add or update verification tasks before implementation for that story
+- Extend shared data capture before rendering output
+- Render text and JSON output after explanation data is available
+- Complete story-specific regression coverage before moving on
+
+### Parallel Opportunities
+
+- `T035` and `T036` can run in parallel once command behavior is stable
+- Within each user story, the work is intentionally sequential because the changes concentrate in `tool/commands/plan.ts` and `tool/__tests__/commands.test.ts`
+
+---
+
+## Parallel Example: User Story 2
+
+```bash
+No safe [P] tasks inside User Story 2 because manifest input handling, explanation rendering, and command regression coverage all update shared files.
+```
+
+## Parallel Example: Polish
+
+```bash
+Task: "Document direct-selection and manifest-driven --verbose examples in README.md"
+Task: "Document manifest-driven verbose planning behavior and examples in docs/discovery-commands.md"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational
+3. Complete Phase 3: User Story 1
+4. Validate `plan --verbose` for a direct dependency case
+5. Stop for review before expanding into manifest-driven planning
+
+### Incremental Delivery
+
+1. Ship the shared explanation foundation
+2. Deliver User Story 1 for direct plus required dependencies
+3. Add User Story 2 for manifest-driven verbose planning
+4. Add User Story 3 for transitive and shared-parent path tracing across both input modes
+5. Add User Story 4 to lock in concise-mode backward compatibility and verbose failure context
+6. Finish docs, changelog, and verification
+
+### Parallel Team Strategy
+
+1. One developer completes Setup and Foundational work
+2. After US1 lands, one developer can extend manifest input handling while another prepares the manifest-driven documentation examples
+3. After US2 lands, the same command owner should complete transitive-path and failure-context work because those changes remain concentrated in shared files
+
+---
+
+## Notes
+
+- All tasks use the required checklist format with IDs, optional `[P]` markers, story labels for story phases, and exact file paths
+- The approved spec gate is closed; execution readiness now depends on completing implementation, verification, and documentation tasks cleanly
+- Favor command-level regression tests in `tool/__tests__/commands.test.ts` because the risk is user-visible CLI behavior

package/docs/specs/002-superposition-config-file/checklists/requirements.md

@@ -0,0 +1,36 @@
+# Specification Quality Checklist: Project Configuration File
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-03-11
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Validation completed on 2026-03-11 and passed on the first review iteration.
+- The spec intentionally defines file names and precedence rules because they are part of the user-visible feature behavior and acceptance scope.
+- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`