container-superposition 0.1.13 → 0.1.14-pr.176.30348783452

package/README.md

@@ -50,11 +50,11 @@ npx container-superposition regen
 # Or select the project file explicitly
 npx container-superposition regen --from-project
 
-# Non-interactive CLI example
-npx container-superposition init --stack compose --language nodejs --database postgres
+# Reuse persisted project-file values without the questionnaire
+npx container-superposition init --from-project --no-interactive
 
 # Write only superposition.yml without generating .devcontainer/
-npx container-superposition init --stack compose --language nodejs --no-scaffold
+npx container-superposition init --stack compose --preset web-api --no-scaffold
 
 # Migrate a manifest-only repo to the project-file model
 npx container-superposition migrate
@@ -64,6 +64,7 @@ npx container-superposition migrate
 
 - Base templates: `plain` (single image) and `compose` (multi-service).
 - Overlays: add languages, databases, observability, cloud tools, dev tools.
+- Catalogs: mix the built-in catalog with project-pinned private catalogs declared in `superposition.yml`.
 - Composition: merges overlays into a standard `.devcontainer/` you can edit freely.
 - Compose defaults: tool-owned compose port bindings are hard-rendered to final numeric host ports; `.devcontainer/.env` and `.devcontainer/.env.example` are opt-in artifacts only via `--compose-env-files` / `composeEnvFiles: true`.
 - Project config: `superposition.yml` (or `.superposition.yml`) is the **canonical input** for all

package/docs/adr/README.md

@@ -1,5 +1,9 @@
 # ADR Index
 
+## Working conventions
+
+- New ADRs should start from `docs/adr/_adr_template.md`.
+
 | ADR                                                         | Title                                                        | Status   | Summary                                                                                                                                                                                                    |
 | ----------------------------------------------------------- | ------------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [001](adr001-project-file-first-replay-and-regeneration.md) | Project-file-first replay and regeneration workflow          | Proposed | Make repository project file canonical durable input for generation, replay, remediation, and migration workflows while keeping manifest as generated compatibility artifact.                              |

package/docs/adr/{_template.md → _adr_template.md}

@@ -32,7 +32,7 @@ relationships: {}
 
 <!--
 ## Create an ADR
-1. Copy `docs/adr/_template.md` to `docs/adr/adrXXX-my-decision.md` (assign ADR number when ready)
+1. Copy `docs/adr/_adr_template.md` to `docs/adr/adrXXX-my-decision.md` (assign ADR number when ready)
 1. Fill in the front matter YAML
 1. Keep the ADR focused on one architectural decision or one tightly-coupled decision set
 1. Read `docs/foundation.md` first and ensure the ADR aligns with or explicitly updates those baseline rules

package/docs/agent-evals/README.md

@@ -0,0 +1,10 @@
+# Agent / Skill Evals
+
+Store representative historical tasks, trigger tests, output assertions, and baseline comparisons here.
+
+Suggested contents:
+
+- task corpus references
+- per-skill eval notes
+- workflow replay summaries
+- keep / revise / delete decisions

package/docs/opportunities/README.md

@@ -1,40 +1,10 @@
 # Opportunity Backlog
 
-Last updated: 2026-07-23
+Last updated: 2026-07-28
 
 ## Prioritized
 
-### 1. Versioned private overlay and preset catalogs
-
-- **type**: feature
-- **status**: prioritized
-- **value summary**: Unlock the biggest strategic expansion path by letting platform teams publish, pin, and evolve private catalogs without forking the tool, while preserving deterministic project-file-driven replay.
-- **urgency**: Medium
-- **confidence**: Medium
-- **rough effort/risk**: High effort, High architecture/security risk
-- **evidence**:
-    - Draft spec exists: `docs/specs/029-versioned-private-catalogs/spec.md`.
-    - The spec identifies blocked platform-team outcomes today: central platform ownership, independent catalog release cadence, reproducible pinning, and explicit trust/upgrade workflows.
-    - The spec also identifies cross-command impact across `init`, `regen`, `doctor`, `list`, `explain`, and schema-aware authoring.
-    - The spec explicitly calls for a new ADR because the feature changes trust boundaries, registry resolution order, validation, and cache/materialization responsibilities.
-- **recommended next prompt or owner**: `/adr` for the catalog trust/resolution decision, then implementation planning against `docs/specs/029-versioned-private-catalogs/spec.md`.
-
-### 2. Broaden repeatable compose overlays beyond PostgreSQL
-
-- **type**: feature
-- **status**: prioritized
-- **value summary**: Expand real stack-building capability by making more infrastructure overlays repeatable through the now-final named-instance contract, increasing overlay availability and customization power for compose users.
-- **urgency**: High
-- **confidence**: Medium-High
-- **rough effort/risk**: Medium effort, Medium risk
-- **evidence**:
-    - `docs/specs/050-compose-overlay-instances/spec.md` is now `Final`, so the core object-form multi-instance contract is complete.
-    - `docs/specs/051-repeatable-compose-overlay-rollout/spec.md` already defines a phased rollout and approves Phase 1A candidates: `redis`, `fuseki`, `sqlserver`, and `nats`.
-    - The `051` audit explicitly separates low-risk Class A overlays from deferred dependency-bound or multi-service families.
-    - Recent BDD and plan-output hardening reduced regression risk for follow-on user-visible overlay work.
-- **recommended next prompt or owner**: `/spec` or implementation handoff for `docs/specs/051-repeatable-compose-overlay-rollout/spec.md`.
-
-### 3. Discovery surface clarity and canonical docs alignment
+### 1. Discovery surface clarity and canonical docs alignment
 
 - **type**: UX
 - **status**: prioritized
@@ -48,7 +18,7 @@ Last updated: 2026-07-23
     - `docs/roadmap.md` currently places this theme in `Now`.
 - **recommended next prompt or owner**: `/spec` or implementation handoff for `docs/specs/030-discovery-surface-and-docs-alignment/spec.md`.
 
-### 4. Preset-led onboarding for common jobs-to-be-done
+### 2. Preset-led onboarding for common jobs-to-be-done
 
 - **type**: feature
 - **status**: candidate
@@ -62,7 +32,7 @@ Last updated: 2026-07-23
     - `docs/roadmap.md` currently places this theme in `Next`.
 - **recommended next prompt or owner**: `/spec` or implementation handoff for `docs/specs/031-preset-led-onboarding-for-common-jobs/spec.md`.
 
-### 5. Portfolio refresh after recent workflow and overlay-contract wins
+### 3. Portfolio refresh after recent workflow and overlay-contract wins
 
 - **type**: process
 - **status**: candidate
@@ -84,10 +54,10 @@ Last updated: 2026-07-23
 2. Portfolio refresh after recent workflow and overlay-contract wins
 3. Preset-led onboarding for common jobs-to-be-done
 
-### Next big bets
+### Recently shipped / no longer active opportunities
 
-1. Versioned private overlay and preset catalogs
-2. Broaden repeatable compose overlays beyond PostgreSQL
+- Versioned private overlay and preset catalogs shipped through spec `029-versioned-private-catalogs`.
+- Repeatable compose-overlay rollout shipped through specs `050-compose-overlay-instances` and `051-repeatable-compose-overlay-rollout`.
 
 ### Longer-term options
 
@@ -99,7 +69,6 @@ Last updated: 2026-07-23
 
 - Ranking emphasizes expected value first because the current prioritization request explicitly deprioritized effort as a decision driver.
 - Confidence remains evidence-bound to repository docs/specs only; no telemetry, support volume, or market research was reviewed here.
-- `029` is ranked highest on upside, not on ease or certainty.
-- `051` is the strongest newly strengthened near-term capability opportunity because `050` is now final and `051` already narrows the rollout to audited overlay classes.
 - `030` remains the strongest broad UX/trust opportunity and is still the clearest low-risk shipping candidate.
+- Private catalogs and repeatable compose-overlay rollout moved out of the active backlog because shipped specs `029`, `050`, and `051` now cover that work.
 - Earlier repo-local Pi skill opportunities are no longer active backlog leaders because the relevant workflow/skill work has already shipped through specs `039` and `052`.

package/docs/roadmap.md

@@ -12,12 +12,13 @@ This roadmap is derived from the current opportunity backlog in `docs/opportunit
 - **Improve onboarding for common jobs-to-be-done** with stronger preset-led setup paths and less choice overload for first-time users.
 - **Make preview-first workflows more visible** so `plan`, `--verbose`, and `--diff` become an obvious safety step before generation and regeneration.
 
-## Later
+## Recently shipped
 
-- **Support versioned private overlay and preset catalogs** so platform teams can publish, pin, and evolve internal catalogs without forking the tool.
+- **Versioned private overlay and preset catalogs** now let platform teams publish, pin, and evolve internal catalogs without forking the tool.
+- **Repeatable compose-overlay rollout** now extends named-instance support beyond PostgreSQL to the audited `redis`, `fuseki`, `sqlserver`, and `nats` overlays.
 
 ## Assumptions and Dependencies
 
 - ADR `001` remains the authority for project-file-first generation, replay, and remediation.
 - Discovery and onboarding improvements depend on keeping user docs, CLI help, and generated reference docs aligned.
-- Private-catalog work is higher-risk architecture work and should continue to be driven through explicit specs and ADR review.
+- Future private-catalog extensions should continue to be driven through explicit specs and ADR review.

package/docs/specs/037-cli-command-modularization/spec.md

@@ -187,8 +187,7 @@ Validation should explicitly cover:
 
 ### Known repo gaps
 
-- `docs/foundation.md` is absent, so ADR `001` remains the architecture authority for this area.
-- Repo contains an empty `docs/specs/037-doctor-command-modularization/` directory, which is a numbering / workflow hygiene concern but does not block this draft.
+- `docs/foundation.md` and ADR `001` are the relevant architecture authorities for this area.
 
 ## Technical Design
 
@@ -411,7 +410,7 @@ Minimum implementation validation:
 
 aligned with current ADR authority
 
-This design stays within ADR `001` by preserving project-file-first authority, compatibility manifest writing, and generated-output-unchanged conversion semantics. No ADR amendment is required. The repo still lacks `docs/foundation.md`, so ADR `001` remains the controlling architecture reference for this work.
+This design stays within `docs/foundation.md` and ADR `001` by preserving project-file-first authority, compatibility manifest writing, and generated-output-unchanged conversion semantics. No ADR amendment is required.
 
 ## Open Questions
 

package/docs/specs/038-doctor-and-plan-command-modularization/spec.md

@@ -504,8 +504,7 @@ Validation should explicitly cover:
 
 ### Known repo gaps
 
-- `docs/foundation.md` is absent, so ADR `001` remains the relevant architecture authority.
-- Repo contains an empty `docs/specs/037-doctor-command-modularization/` directory, which is workflow hygiene noise but does not block this draft.
+- `docs/foundation.md` and ADR `001` are the relevant architecture authorities.
 
 ## Architecture Decision Impact
 

package/docs/specs/README.md

@@ -1,5 +1,11 @@
 # Specs Index
 
+## Working conventions
+
+- New work should use `docs/specs/_spec_template.md` for the outcome-focused spec and `docs/specs/_plan_template.md` for execution detail.
+- Keep implementation sequencing, affected files, validation strategy, and rollback thinking in `plan.md`, not in `spec.md`.
+- Existing historical specs without `plan.md` were preserved as-is during pi-kit setup; add `plan.md` only when those specs are actively revised or extended.
+
 | Spec                                                                                                                                       | Title                                                                                      | Status | Taxonomy                                  |
 | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | ------ | ----------------------------------------- |
 | [001-verbose-plan-graph](001-verbose-plan-graph/spec.md)                                                                                   | Verbose Plan Graph                                                                         | Final  | CLI-UX                                    |

package/docs/specs/_plan_template.md

@@ -0,0 +1,40 @@
+# Plan
+
+## Scope
+
+- Spec: `docs/specs/NNN-slug/spec.md`
+
+## Ordered Steps
+
+1. [step]
+2. [step]
+
+## Affected Areas
+
+- `path` — why it changes
+
+## Validation Surface and Strategy
+
+- Build/type/lint checks: [commands or reason not applicable]
+- Unit/integration/e2e/contract checks: [commands or reason not applicable]
+- Manual or exploratory checks: [method or reason not applicable]
+- Acceptance-criteria evidence plan: [how each AC ID will be verified]
+- Review gate: [SELF_CHECK / INDEPENDENT, with rationale]
+- Evidence provenance: [source revision, environment, timestamp, executor, exit code]
+- Skipped or deferred checks: [reason and residual risk]
+
+## Rollback / Containment
+
+- [how to revert or limit blast radius]
+
+## Open Questions
+
+- [question]
+
+## Risks / Dependencies
+
+- [important dependency, sequencing risk, migration concern, or coordination need]
+
+## Implementation Notes
+
+- Update this section when implementation diverges from the original plan.

package/docs/specs/_spec_template.md

@@ -0,0 +1,53 @@
+---
+spec: 'NNN-slug'
+title: '[Short descriptive title]'
+status: 'Draft'
+review_gate: ''
+owner: 'delivery-interrogator'
+created: 'YYYY-MM-DD'
+updated: 'YYYY-MM-DD'
+related_adrs: []
+related_foundation:
+    - 'docs/foundation.md'
+---
+
+# [Title]
+
+## Problem
+
+[What problem exists, for whom, and why it matters.]
+
+## Why now
+
+[Why this change matters now.]
+
+## Acceptance Criteria
+
+- [ ] AC1: [specific, testable criterion]
+- [ ] AC2: [specific, testable criterion]
+- [ ] AC3: [relevant quality, compatibility, documentation, validation, or changelog expectation]
+
+Keep acceptance-criterion IDs stable across spec revisions so plans, tests, evidence, and review findings can cite them.
+
+## Non-goals
+
+- [non-goal 1]
+- [non-goal 2]
+
+## Ambiguities / Open Questions
+
+- [question or ambiguity]
+
+## Evidence / References
+
+- [reference]
+- [reference]
+
+## Risks / Constraints
+
+- [risk, constraint, dependency, or rollout concern]
+
+## Notes
+
+- Keep implementation detail out of this file.
+- Put sequencing and file-level execution details in `plan.md`.

package/docs/specs/taxonomy.md

@@ -1,6 +1,6 @@
 # Feature Taxonomy
 
-This index maps all specs to their feature categories. Maintained by the `tool-pm` agent — update whenever a new spec is added.
+This index maps all specs to their feature categories. Update it whenever a new spec is added.
 
 ## Taxonomy categories
 
@@ -230,17 +230,17 @@ _No specs yet._
 
 ## PROJECT — Project-level configuration
 
-| Spec                                                                           | Title                                                        | Status                        |
-| ------------------------------------------------------------------------------ | ------------------------------------------------------------ | ----------------------------- |
-| [002-superposition-config-file](002-superposition-config-file/spec.md)         | Project Configuration File                                   | Final                         |
-| [008-project-file-canonical](008-project-file-canonical/spec.md)               | Make superposition.yml Canonical Input                       | Final                         |
-| [009-project-env](009-project-env/spec.md)                                     | Unified Project-Level Environment Variables                  | Final                         |
-| [018-init-project-file](018-init-project-file/spec.md)                         | `init --project-file`                                        | Final                         |
-| [019-project-mounts](019-project-mounts/spec.md)                               | First-Class Mounts Support                                   | Final                         |
-| [022-local-superposition-config](022-local-superposition-config/spec.md)       | Local Superposition Config                                   | Final                         |
-| [029-versioned-private-catalogs](029-versioned-private-catalogs/spec.md)       | Versioned Private Overlay and Preset Catalogs                | Implemented (QA: Needs Fixes) |
-| [041-local-port-conflict-overrides](041-local-port-conflict-overrides/spec.md) | Local Port Conflict Overrides in `superposition.local.yml`   | Final                         |
-| [042-global-default-configuration](042-global-default-configuration/spec.md)   | User-Scoped Global Defaults with Stack-Aware Local Templates | Final                         |
-| [043-compose-network-name](043-compose-network-name/spec.md)                   | Project-Specific Compose Network Names                       | Final                         |
-| [049-global-init-defaults-surface](049-global-init-defaults-surface/spec.md)   | Expand User-Scoped Global Init Defaults Surface              | Final                         |
-| [050-compose-overlay-instances](050-compose-overlay-instances/spec.md)         | Multi-Instance Compose Overlays with Instance Overrides      | Final                         |
+| Spec                                                                           | Title                                                        | Status |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------ | ------ |
+| [002-superposition-config-file](002-superposition-config-file/spec.md)         | Project Configuration File                                   | Final  |
+| [008-project-file-canonical](008-project-file-canonical/spec.md)               | Make superposition.yml Canonical Input                       | Final  |
+| [009-project-env](009-project-env/spec.md)                                     | Unified Project-Level Environment Variables                  | Final  |
+| [018-init-project-file](018-init-project-file/spec.md)                         | `init --project-file`                                        | Final  |
+| [019-project-mounts](019-project-mounts/spec.md)                               | First-Class Mounts Support                                   | Final  |
+| [022-local-superposition-config](022-local-superposition-config/spec.md)       | Local Superposition Config                                   | Final  |
+| [029-versioned-private-catalogs](029-versioned-private-catalogs/spec.md)       | Versioned Private Overlay and Preset Catalogs                | Final  |
+| [041-local-port-conflict-overrides](041-local-port-conflict-overrides/spec.md) | Local Port Conflict Overrides in `superposition.local.yml`   | Final  |
+| [042-global-default-configuration](042-global-default-configuration/spec.md)   | User-Scoped Global Defaults with Stack-Aware Local Templates | Final  |
+| [043-compose-network-name](043-compose-network-name/spec.md)                   | Project-Specific Compose Network Names                       | Final  |
+| [049-global-init-defaults-surface](049-global-init-defaults-surface/spec.md)   | Expand User-Scoped Global Init Defaults Surface              | Final  |
+| [050-compose-overlay-instances](050-compose-overlay-instances/spec.md)         | Multi-Instance Compose Overlays with Instance Overrides      | Final  |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "container-superposition",
-    "version": "0.1.13",
+    "version": "0.1.14-pr.176.30348783452",
     "description": "Solution-ready devcontainer templates and features with guided initialization",
     "type": "module",
     "main": "dist/scripts/init.js",

package/docs/specs/_template.md

@@ -1,206 +0,0 @@
----
-spec: 'NNN-slug'
-title: '[Short descriptive title]'
-status: 'Draft'
-qa_status: ''
-priority: 'P0'
-owner: 'pm'
-product_approval: ''
-architecture_review: ''
-ux_review: ''
-created: 'YYYY-MM-DD'
-updated: 'YYYY-MM-DD'
-related_adrs: []
-related_foundation:
-    - 'docs/foundation.md'
-related_specs: []
-normative_references: []
----
-
-# [Title]
-
-**Spec**: `NNN-slug`
-**Status**: Draft
-**Created**: YYYY-MM-DD
-**Priority**: P0 | P1 | P2 | P3
-**Product Approval**: pending | approved | not-needed
-**Architecture Review**: pending | approved | not-needed
-**UX Review**: pending | approved | not-needed
-
-> P0 = unusable without; P1 = core value, ship v1; P2 = post-launch; P3 = backlog
-
-## Description
-
-[Describe the problem, user need, and intended outcome.]
-
-## Evidence <!-- especially important for reverse-spec work -->
-
-- [path or source 1] — [why it matters]
-- [path or source 2] — [why it matters]
-
-## Problem Statement
-
-[What problem exists today, for whom, and why it matters.]
-
-## User Goals / Jobs To Be Done
-
-- [job or goal 1]
-- [job or goal 2]
-
-## Success Signals
-
-- [signal 1]
-- [signal 2]
-
-## Confidence <!-- optional, especially for reverse-spec work -->
-
-- Overall confidence: high | medium | low
-- Confidence notes: [what is directly evidenced vs inferred]
-
-## User Stories
-
-**US-1** As a user, I want ...
-
-## Goals
-
-- [goal 1]
-- [goal 2]
-
-## Non-Goals
-
-- [non-goal 1]
-- [non-goal 2]
-
-## Authority and References
-
-This spec must align with:
-
-- `docs/foundation.md`
-- relevant ADRs in `docs/adr/`
-- relevant project-context and normative-reference documents
-
-List the specific references for this spec:
-
-- [reference 1]
-- [reference 2]
-
-## Design
-
-### Observed Behavior <!-- optional for reverse-spec work -->
-
-[Describe observed current behavior from evidence.]
-
-### Likely Intent <!-- optional for reverse-spec work -->
-
-[Describe what the feature appears intended to accomplish.]
-
-### Product / Behavior
-
-[Describe the user-visible or system-visible behavior.]
-
-### Technical Notes
-
-[Describe technical expectations only when PM should make them explicit before architect handoff.]
-
-### UX Notes <!-- optional -->
-
-[Describe layout, interaction, wording, state, or navigation expectations when relevant.]
-
-## Constraints
-
-- [constraint 1]
-- [constraint 2]
-
-## Preferences / Tradeoffs <!-- optional -->
-
-- [preferred approach or tradeoff 1]
-- [preferred approach or tradeoff 2]
-
-## Risks <!-- optional -->
-
-- [risk 1]
-- [risk 2]
-
-## Implementation / Intent Mismatches <!-- optional, especially for reverse-spec work -->
-
-- [mismatch 1]
-- [mismatch 2]
-
-## Acceptance Criteria
-
-- [ ] [specific, testable criterion]
-- [ ] [specific, testable criterion]
-- [ ] All new or changed behavior is covered by automated tests at the appropriate level
-- [ ] Documentation and workflow artifacts are updated to match the implemented or reviewed state
-
-## Out of Scope
-
-- [out of scope 1]
-- [out of scope 2]
-
-## Assumptions <!-- optional -->
-
-- [assumption 1]
-
-## Open Questions <!-- optional -->
-
-- [question 1]
-
-## Definition of Done
-
-> Filled in progressively by each role. QA sets `Status: Final` only after verifying all gates.
-> Full standards in `docs/definition-of-done.md`.
-
-### Code
-
-- [ ] No lint errors
-- [ ] No type errors
-- [ ] No debug or uncommitted temporary code
-- [ ] Follows project conventions
-
-### Tests
-
-- [ ] Unit tests cover new pure logic
-- [ ] Integration tests cover system boundaries
-- [ ] All tests pass
-- [ ] No unjustified skipped tests
-- [ ] Failure and edge cases covered
-
-### Documentation
-
-- [ ] Public interfaces documented
-- [ ] All new documentation in Markdown
-- [ ] All diagrams in Mermaid
-- [ ] README updated if behavior or setup changed
-- [ ] Architecture docs updated if ownership or boundaries changed
-
-### Changelog
-
-- [ ] `CHANGELOG.md` updated under `[Unreleased]` for user-visible changes
-
-### Workflow artifacts
-
-- [ ] Acceptance criteria checked off (met only — unmet left unchecked with explanation)
-- [ ] `## Implementation Notes` written
-- [ ] Spec status and index synchronized
-- [ ] QA feedback rows marked `Done` where applicable
-
-### Architecture
-
-- [ ] No ADR or foundation rules silently violated
-- [ ] ADR created or amended if a standing decision was made or changed
-
-### QA verification
-
-- [ ] All above gates verified independently
-- [ ] Acceptance criteria classified: MET / CLAIMED BUT FAILED / OPEN / UNCHECKED
-- [ ] No regressions introduced
-- [ ] Spec set to `Final`
-
-## Implementation Notes <!-- developer-owned when implemented -->
-
-[Brief summary of what was built, deviations, or reviewer-relevant notes.]
-
-## QA Feedback <!-- QA-owned when needed -->
-
-[Present only when QA adds it.]