container-superposition 0.1.7 → 0.1.9

package/docs/overlays.md

@@ -18,40 +18,44 @@ This document provides a comprehensive reference for all available overlays in c
 
 .NET 10 SDK with C# DevKit
 
-| Property     | Value                          |
-| ------------ | ------------------------------ |
-| **Category** | language                       |
-| **Tags**     | `language`, `dotnet`, `csharp` |
+| Property      | Value                                   |
+| ------------- | --------------------------------------- |
+| **Category**  | language                                |
+| **Conflicts** | `mysql`, `redpanda`, `otel-demo-nodejs` |
+| **Tags**      | `language`, `dotnet`, `csharp`          |
 
 ### Bun (`bun`)
 
 Bun runtime - faster JavaScript runtime and package manager
 
-| Property     | Value                                         |
-| ------------ | --------------------------------------------- |
-| **Category** | language                                      |
-| **Tags**     | `language`, `bun`, `javascript`, `typescript` |
-| **Ports**    | 3000, 8080                                    |
+| Property      | Value                                                            |
+| ------------- | ---------------------------------------------------------------- |
+| **Category**  | language                                                         |
+| **Conflicts** | `grafana`, `open-webui`, `mysql`, `redpanda`, `otel-demo-nodejs` |
+| **Tags**      | `language`, `bun`, `javascript`, `typescript`                    |
+| **Ports**     | 3000, 8080                                                       |
 
 ### Go (`go`)
 
 Go latest stable with gopls and delve debugger
 
-| Property     | Value                      |
-| ------------ | -------------------------- |
-| **Category** | language                   |
-| **Tags**     | `language`, `go`, `golang` |
-| **Ports**    | 8080, 8081                 |
+| Property      | Value                                                                  |
+| ------------- | ---------------------------------------------------------------------- |
+| **Category**  | language                                                               |
+| **Conflicts** | `mysql`, `redpanda`, `mongodb`, `otel-demo-nodejs`, `otel-demo-python` |
+| **Tags**      | `language`, `go`, `golang`                                             |
+| **Ports**     | 8080, 8081                                                             |
 
 ### Java (`java`)
 
 Eclipse Temurin JDK 21 with Maven and Gradle
 
-| Property     | Value                                 |
-| ------------ | ------------------------------------- |
-| **Category** | language                              |
-| **Tags**     | `language`, `java`, `maven`, `gradle` |
-| **Ports**    | 8080, 8081                            |
+| Property      | Value                                                                  |
+| ------------- | ---------------------------------------------------------------------- |
+| **Category**  | language                                                               |
+| **Conflicts** | `mysql`, `redpanda`, `mongodb`, `otel-demo-nodejs`, `otel-demo-python` |
+| **Tags**      | `language`, `java`, `maven`, `gradle`                                  |
+| **Ports**     | 8080, 8081                                                             |
 
 ### Jupyter (`jupyter`)
 
@@ -65,26 +69,15 @@ Jupyter notebook server for interactive computing and data science
 | **Tags**     | `language`, `jupyter`, `python`, `notebook`, `data-science` |
 | **Ports**    | 8888                                                        |
 
-### MkDocs (`mkdocs`)
-
-Material for MkDocs - professional documentation generator
-
-| Property      | Value                               |
-| ------------- | ----------------------------------- |
-| **Category**  | language                            |
-| **Requires**  | `python`                            |
-| **Conflicts** | `mkdocs2`                           |
-| **Tags**      | `documentation`, `mkdocs`, `python` |
-| **Ports**     | 8000                                |
-
 ### Node.js (`nodejs`)
 
 Node.js LTS with TypeScript and tooling
 
-| Property     | Value                                            |
-| ------------ | ------------------------------------------------ |
-| **Category** | language                                         |
-| **Tags**     | `language`, `nodejs`, `javascript`, `typescript` |
+| Property      | Value                                                            |
+| ------------- | ---------------------------------------------------------------- |
+| **Category**  | language                                                         |
+| **Conflicts** | `grafana`, `open-webui`, `mysql`, `redpanda`, `otel-demo-nodejs` |
+| **Tags**      | `language`, `nodejs`, `javascript`, `typescript`                 |
 
 ### PowerShell (`powershell`)
 
@@ -108,14 +101,27 @@ Python 3.12 with linting and formatting
 
 Rust stable with cargo, rustfmt, and clippy
 
-| Property     | Value                       |
-| ------------ | --------------------------- |
-| **Category** | language                    |
-| **Tags**     | `language`, `rust`, `cargo` |
-| **Ports**    | 8080, 3000                  |
+| Property      | Value                       |
+| ------------- | --------------------------- |
+| **Category**  | language                    |
+| **Conflicts** | `grafana`, `open-webui`     |
+| **Tags**      | `language`, `rust`, `cargo` |
+| **Ports**     | 8080, 3000                  |
 
 ## Database Overlays
 
+### Apache Jena Fuseki (`fuseki`)
+
+SPARQL 1.1 server and triplestore backed by Apache Jena TDB
+
+| Property     | Value                                                                             |
+| ------------ | --------------------------------------------------------------------------------- |
+| **Category** | database                                                                          |
+| **Supports** | compose                                                                           |
+| **Suggests** | `java`, `python`, `nodejs`                                                        |
+| **Tags**     | `database`, `rdf`, `sparql`, `triplestore`, `semantic-web`, `linked-data`, `jena` |
+| **Ports**    | 3030/http                                                                         |
+
 ### DuckDB (`duckdb`)
 
 In-process analytical database for OLAP workloads
@@ -130,67 +136,78 @@ In-process analytical database for OLAP workloads
 
 S3-compatible object storage with web console
 
-| Property     | Value                                                  |
-| ------------ | ------------------------------------------------------ |
-| **Category** | database                                               |
-| **Supports** | compose                                                |
-| **Tags**     | `database`, `storage`, `s3`, `object-storage`, `minio` |
-| **Ports**    | 9000, 9001                                             |
+| Property      | Value                                                  |
+| ------------- | ------------------------------------------------------ |
+| **Category**  | database                                               |
+| **Supports**  | compose                                                |
+| **Suggests**  | `prometheus`, `grafana`                                |
+| **Conflicts** | `localstack`                                           |
+| **Tags**      | `database`, `storage`, `s3`, `object-storage`, `minio` |
+| **Ports**     | 9000, 9001                                             |
 
 ### MongoDB (`mongodb`)
 
 MongoDB 8 with Mongo Express web UI
 
-| Property     | Value                                      |
-| ------------ | ------------------------------------------ |
-| **Category** | database                                   |
-| **Supports** | compose                                    |
-| **Tags**     | `database`, `nosql`, `mongodb`, `document` |
-| **Ports**    | [object Object], [object Object]           |
+| Property      | Value                                        |
+| ------------- | -------------------------------------------- |
+| **Category**  | database                                     |
+| **Supports**  | compose                                      |
+| **Suggests**  | `prometheus`, `grafana`                      |
+| **Conflicts** | `redpanda`, `otel-demo-python`, `go`, `java` |
+| **Tags**      | `database`, `nosql`, `mongodb`, `document`   |
+| **Ports**     | 27017/tcp, 8081/http                         |
 
 ### MySQL (`mysql`)
 
 MySQL 8 with phpMyAdmin web UI
 
-| Property     | Value                            |
-| ------------ | -------------------------------- |
-| **Category** | database                         |
-| **Supports** | compose                          |
-| **Tags**     | `database`, `sql`, `mysql`       |
-| **Ports**    | [object Object], [object Object] |
+| Property      | Value                                                                   |
+| ------------- | ----------------------------------------------------------------------- |
+| **Category**  | database                                                                |
+| **Supports**  | compose                                                                 |
+| **Suggests**  | `prometheus`, `grafana`                                                 |
+| **Conflicts** | `redpanda`, `nodejs`, `bun`, `go`, `java`, `dotnet`, `otel-demo-nodejs` |
+| **Tags**      | `database`, `sql`, `mysql`                                              |
+| **Ports**     | 3306/tcp, 8080/http                                                     |
 
-### NATS (`nats`)
+### pgvector (PostgreSQL + vector) (`pgvector`)
 
-Lightweight pub/sub messaging with JetStream
+PostgreSQL 16 with the pgvector extension for vector similarity search
 
-| Property     | Value                                                  |
-| ------------ | ------------------------------------------------------ |
-| **Category** | database                                               |
-| **Supports** | compose                                                |
-| **Tags**     | `database`, `messaging`, `pubsub`, `nats`, `jetstream` |
-| **Ports**    | [object Object], [object Object]                       |
+| Property      | Value                                                             |
+| ------------- | ----------------------------------------------------------------- |
+| **Category**  | database                                                          |
+| **Supports**  | compose                                                           |
+| **Suggests**  | `ollama`, `python`, `nodejs`, `prometheus`, `grafana`             |
+| **Conflicts** | `postgres`                                                        |
+| **Tags**      | `database`, `sql`, `vector`, `embeddings`, `postgres`, `pgvector` |
+| **Ports**     | 5432/tcp                                                          |
 
 ### PostgreSQL (`postgres`)
 
 PostgreSQL 16 database
 
-| Property     | Value                         |
-| ------------ | ----------------------------- |
-| **Category** | database                      |
-| **Supports** | compose                       |
-| **Tags**     | `database`, `sql`, `postgres` |
-| **Ports**    | [object Object]               |
+| Property      | Value                         |
+| ------------- | ----------------------------- |
+| **Category**  | database                      |
+| **Supports**  | compose                       |
+| **Suggests**  | `prometheus`, `grafana`       |
+| **Conflicts** | `pgvector`                    |
+| **Tags**      | `database`, `sql`, `postgres` |
+| **Ports**     | 5432/tcp                      |
 
-### RabbitMQ (`rabbitmq`)
+### Qdrant (`qdrant`)
 
-Message broker with AMQP protocol and management UI
+High-performance vector database for similarity search and embeddings
 
-| Property     | Value                                                |
-| ------------ | ---------------------------------------------------- |
-| **Category** | database                                             |
-| **Supports** | compose                                              |
-| **Tags**     | `database`, `messaging`, `queue`, `rabbitmq`, `amqp` |
-| **Ports**    | [object Object], [object Object]                     |
+| Property     | Value                                                                   |
+| ------------ | ----------------------------------------------------------------------- |
+| **Category** | database                                                                |
+| **Supports** | compose                                                                 |
+| **Suggests** | `ollama`, `python`, `nodejs`, `prometheus`, `grafana`, `otel-collector` |
+| **Tags**     | `database`, `vector`, `embeddings`, `search`, `qdrant`                  |
+| **Ports**    | 6333/http, 6334/grpc                                                    |
 
 ### Redis (`redis`)
 
@@ -200,19 +217,9 @@ Redis 7 cache
 | ------------ | ---------------------------- |
 | **Category** | database                     |
 | **Supports** | compose                      |
+| **Suggests** | `prometheus`, `grafana`      |
 | **Tags**     | `database`, `cache`, `redis` |
-| **Ports**    | [object Object]              |
-
-### Redpanda (`redpanda`)
-
-Kafka-compatible event streaming with web console
-
-| Property     | Value                                                     |
-| ------------ | --------------------------------------------------------- |
-| **Category** | database                                                  |
-| **Supports** | compose                                                   |
-| **Tags**     | `database`, `messaging`, `streaming`, `kafka`, `redpanda` |
-| **Ports**    | 9092, 8080, 8081, 8082, 9644                              |
+| **Ports**    | 6379/tcp                     |
 
 ### SQL Server (`sqlserver`)
 
@@ -222,7 +229,7 @@ SQL Server 2022 for Linux
 | ------------ | ------------------------------------------- |
 | **Category** | database                                    |
 | **Supports** | compose                                     |
-| **Suggests** | `dotnet`                                    |
+| **Suggests** | `dotnet`, `prometheus`, `grafana`           |
 | **Tags**     | `database`, `sql`, `sqlserver`, `microsoft` |
 | **Ports**    | 1433                                        |
 
@@ -242,13 +249,13 @@ SQLite with litecli and VS Code extensions
 
 Distributed tracing backend
 
-| Property      | Value                                             |
-| ------------- | ------------------------------------------------- |
-| **Category**  | observability                                     |
-| **Supports**  | compose                                           |
-| **Conflicts** | `tempo`                                           |
-| **Tags**      | `observability`, `tracing`, `jaeger`              |
-| **Ports**     | [object Object], [object Object], [object Object] |
+| Property      | Value                                |
+| ------------- | ------------------------------------ |
+| **Category**  | observability                        |
+| **Supports**  | compose                              |
+| **Conflicts** | `tempo`                              |
+| **Tags**      | `observability`, `tracing`, `jaeger` |
+| **Ports**     | 16686/http                           |
 
 ### Loki (`loki`)
 
@@ -260,7 +267,7 @@ Log aggregation system
 | **Supports** | compose                         |
 | **Suggests** | `promtail`                      |
 | **Tags**     | `observability`, `logs`, `loki` |
-| **Ports**    | [object Object]                 |
+| **Ports**    | 3100/http                       |
 
 ### Prometheus (`prometheus`)
 
@@ -272,7 +279,7 @@ Metrics collection and monitoring
 | **Supports** | compose                                  |
 | **Suggests** | `alertmanager`                           |
 | **Tags**     | `observability`, `metrics`, `prometheus` |
-| **Ports**    | [object Object]                          |
+| **Ports**    | 9090/http                                |
 
 ### Tempo (`tempo`)
 
@@ -326,40 +333,43 @@ Log shipping agent for Loki with Docker auto-discovery
 
 Observability visualization dashboard with auto-provisioning
 
-| Property     | Value                                  |
-| ------------ | -------------------------------------- |
-| **Category** | observability                          |
-| **Supports** | compose                                |
-| **Requires** | `prometheus`                           |
-| **Suggests** | `loki`, `jaeger`, `tempo`, `promtail`  |
-| **Tags**     | `observability`, `ui`, `visualization` |
-| **Ports**    | [object Object]                        |
+| Property      | Value                                  |
+| ------------- | -------------------------------------- |
+| **Category**  | observability                          |
+| **Supports**  | compose                                |
+| **Requires**  | `prometheus`                           |
+| **Suggests**  | `loki`, `jaeger`, `tempo`, `promtail`  |
+| **Conflicts** | `open-webui`, `nodejs`, `bun`, `rust`  |
+| **Tags**      | `observability`, `ui`, `visualization` |
+| **Ports**     | 3000/http                              |
 
 ### OTel Demo (Node.js) (`otel-demo-nodejs`)
 
 Sample Node.js app with OpenTelemetry instrumentation
 
-| Property     | Value                                              |
-| ------------ | -------------------------------------------------- |
-| **Category** | observability                                      |
-| **Supports** | compose                                            |
-| **Requires** | `otel-collector`                                   |
-| **Suggests** | `jaeger`, `tempo`, `prometheus`, `loki`, `grafana` |
-| **Tags**     | `observability`, `demo`, `nodejs`, `opentelemetry` |
-| **Ports**    | 8080                                               |
+| Property      | Value                                                        |
+| ------------- | ------------------------------------------------------------ |
+| **Category**  | observability                                                |
+| **Supports**  | compose                                                      |
+| **Requires**  | `otel-collector`                                             |
+| **Suggests**  | `jaeger`, `tempo`, `prometheus`, `loki`, `grafana`           |
+| **Conflicts** | `mysql`, `redpanda`, `nodejs`, `bun`, `go`, `java`, `dotnet` |
+| **Tags**      | `observability`, `demo`, `nodejs`, `opentelemetry`           |
+| **Ports**     | 8080                                                         |
 
 ### OTel Demo (Python) (`otel-demo-python`)
 
 Sample Python Flask app with OpenTelemetry instrumentation
 
-| Property     | Value                                              |
-| ------------ | -------------------------------------------------- |
-| **Category** | observability                                      |
-| **Supports** | compose                                            |
-| **Requires** | `otel-collector`                                   |
-| **Suggests** | `jaeger`, `tempo`, `prometheus`, `loki`, `grafana` |
-| **Tags**     | `observability`, `demo`, `python`, `opentelemetry` |
-| **Ports**    | 8081                                               |
+| Property      | Value                                              |
+| ------------- | -------------------------------------------------- |
+| **Category**  | observability                                      |
+| **Supports**  | compose                                            |
+| **Requires**  | `otel-collector`                                   |
+| **Suggests**  | `jaeger`, `tempo`, `prometheus`, `loki`, `grafana` |
+| **Conflicts** | `mongodb`, `redpanda`, `go`, `java`                |
+| **Tags**      | `observability`, `demo`, `python`, `opentelemetry` |
+| **Ports**     | 8081                                               |
 
 ## Cloud Tool Overlays
 
@@ -390,6 +400,18 @@ Google Cloud Platform command-line tools (gcloud, gsutil, bq)
 | **Category** | cloud                           |
 | **Tags**     | `cloud`, `gcp`, `google`, `cli` |
 
+### k3d (`k3d`)
+
+Lightweight local Kubernetes clusters using k3s in Docker
+
+| Property      | Value                                                 |
+| ------------- | ----------------------------------------------------- |
+| **Category**  | cloud                                                 |
+| **Requires**  | `docker-in-docker`                                    |
+| **Suggests**  | `kubectl-helm`                                        |
+| **Conflicts** | `kind`                                                |
+| **Tags**      | `cloud`, `kubernetes`, `k8s`, `k3d`, `k3s`, `testing` |
+
 ### kind (Kubernetes in Docker) (`kind`)
 
 Local Kubernetes cluster for development and testing
@@ -415,13 +437,14 @@ Kubernetes CLI and Helm package manager
 
 Local AWS cloud stack for development and testing
 
-| Property     | Value                                   |
-| ------------ | --------------------------------------- |
-| **Category** | cloud                                   |
-| **Supports** | compose                                 |
-| **Suggests** | `aws-cli`                               |
-| **Tags**     | `cloud`, `aws`, `testing`, `localstack` |
-| **Ports**    | 4566, 4571                              |
+| Property      | Value                                   |
+| ------------- | --------------------------------------- |
+| **Category**  | cloud                                   |
+| **Supports**  | compose                                 |
+| **Suggests**  | `aws-cli`                               |
+| **Conflicts** | `minio`                                 |
+| **Tags**      | `cloud`, `aws`, `testing`, `localstack` |
+| **Ports**     | 4566, 4571                              |
 
 ### Pulumi (`pulumi`)
 
@@ -503,6 +526,18 @@ OpenAI Codex CLI for AI-powered code generation and assistance
 | **Requires** | `nodejs`                       |
 | **Tags**     | `dev`, `ai`, `code-generation` |
 
+### ComfyUI (`comfyui`)
+
+Node-based image/video generation UI for Stable Diffusion and generative AI workflows
+
+| Property     | Value                                                          |
+| ------------ | -------------------------------------------------------------- |
+| **Category** | dev                                                            |
+| **Supports** | compose                                                        |
+| **Suggests** | `cuda`, `rocm`, `python`, `ollama`                             |
+| **Tags**     | `dev`, `ai`, `image-generation`, `stable-diffusion`, `comfyui` |
+| **Ports**    | 8188                                                           |
+
 ### Commitlint (`commitlint`)
 
 Conventional commits validation for automated releases
@@ -610,7 +645,7 @@ Open-source identity and access management (OIDC/OAuth2)
 | **Supports** | compose                                     |
 | **Requires** | `postgres`                                  |
 | **Tags**     | `dev`, `auth`, `oidc`, `oauth2`, `identity` |
-| **Ports**    | [object Object]                             |
+| **Ports**    | 8180/http                                   |
 
 ### Mailpit (`mailpit`)
 
@@ -621,7 +656,19 @@ Email testing tool with web UI and SMTP server
 | **Category** | dev                               |
 | **Supports** | compose                           |
 | **Tags**     | `dev`, `email`, `smtp`, `testing` |
-| **Ports**    | [object Object], [object Object]  |
+| **Ports**    | 8025/http, 1025/tcp               |
+
+### MkDocs (`mkdocs`)
+
+Material for MkDocs - professional documentation generator
+
+| Property      | Value                               |
+| ------------- | ----------------------------------- |
+| **Category**  | dev                                 |
+| **Requires**  | `python`                            |
+| **Conflicts** | `mkdocs2`                           |
+| **Tags**      | `documentation`, `mkdocs`, `python` |
+| **Ports**     | 8000                                |
 
 ### MkDocs 2 (`mkdocs2`)
 
@@ -655,6 +702,42 @@ Secure tunneling for webhook testing and external access
 | **Tags**      | `dev`, `tunneling`, `webhooks` |
 | **Ports**     | 4040                           |
 
+### Ollama (`ollama`)
+
+Local LLM inference server with OpenAI-compatible API
+
+| Property     | Value                                                                    |
+| ------------ | ------------------------------------------------------------------------ |
+| **Category** | dev                                                                      |
+| **Supports** | compose                                                                  |
+| **Requires** | `ollama-cli`                                                             |
+| **Suggests** | `codex`, `claude-code`, `amp`, `prometheus`, `grafana`, `otel-collector` |
+| **Tags**     | `dev`, `ai`, `llm`, `inference`, `ollama`                                |
+| **Ports**    | 11434                                                                    |
+
+### Ollama CLI (`ollama-cli`)
+
+Ollama command-line client for local or remote Ollama servers
+
+| Property     | Value                                   |
+| ------------ | --------------------------------------- |
+| **Category** | dev                                     |
+| **Suggests** | `ollama`, `codex`, `claude-code`, `amp` |
+| **Tags**     | `dev`, `ai`, `llm`, `ollama`, `cli`     |
+
+### Open WebUI (`open-webui`)
+
+Browser-based chat UI for Ollama and OpenAI-compatible LLM backends
+
+| Property      | Value                                         |
+| ------------- | --------------------------------------------- |
+| **Category**  | dev                                           |
+| **Supports**  | compose                                       |
+| **Suggests**  | `ollama`, `prometheus`, `otel-collector`      |
+| **Conflicts** | `grafana`, `nodejs`, `bun`, `rust`            |
+| **Tags**      | `dev`, `ai`, `llm`, `ui`, `chat`, `openwebui` |
+| **Ports**     | 3000/http                                     |
+
 ### OpenAPI Tools (`openapi-tools`)
 
 OpenAPI/Swagger tooling for API development and documentation
@@ -682,6 +765,7 @@ Browser automation and testing framework
 | Property     | Value                       |
 | ------------ | --------------------------- |
 | **Category** | dev                         |
+| **Requires** | `nodejs`                    |
 | **Tags**     | `dev`, `testing`, `browser` |
 
 ### Pre-commit Framework (`pre-commit`)
@@ -702,9 +786,21 @@ AMD ROCm libraries and GPU passthrough for containerized ML/inference workloads
 | Property      | Value                                          |
 | ------------- | ---------------------------------------------- |
 | **Category**  | dev                                            |
+| **Suggests**  | `comfyui`                                      |
 | **Conflicts** | `cuda`                                         |
 | **Tags**      | `dev`, `gpu`, `rocm`, `amd`, `ml`, `inference` |
 
+### Skaffold (`skaffold`)
+
+Continuous development and deployment pipeline for Kubernetes applications
+
+| Property      | Value                                                        |
+| ------------- | ------------------------------------------------------------ |
+| **Category**  | dev                                                          |
+| **Suggests**  | `kubectl-helm`, `kind`, `k3d`                                |
+| **Conflicts** | `tilt`                                                       |
+| **Tags**      | `dev`, `kubernetes`, `k8s`, `cicd`, `deployment`, `skaffold` |
+
 ### Tilt (`tilt`)
 
 Live update and orchestration for Kubernetes development

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

@@ -1,18 +1,11 @@
 # Feature Specification: Verbose Plan Graph
 
-**Feature Branch**: `001-verbose-plan-graph`  
+**Spec ID**: `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 Scenarios & Testing
 
 ### User Story 1 - Explain auto-included overlays (Priority: P1)
 
@@ -80,7 +73,7 @@ A user who only wants a quick summary should still be able to run the plan comma
 - 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)_
+## Requirements
 
 ### Functional Requirements
 
@@ -110,14 +103,14 @@ A user who only wants a quick summary should still be able to run the plan comma
 - 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)_
+## Dependencies & Impact
 
 - **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)_
+## Success Criteria
 
 ### Measurable Outcomes
 

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

@@ -1,6 +1,6 @@
 # Feature Specification: Project Configuration File
 
-**Feature Branch**: `002-superposition-config-file`  
+**Spec ID**: `002-superposition-config-file`
 **Created**: 2026-03-11  
 **Status**: Final  
 **Input**: Add a repository-root project config file so teams and automation can generate the same environment from committed declarative setup instead of reconstructing long CLI commands.
@@ -8,14 +8,7 @@
 > Use repo-relative Markdown links for repository files. The root `README.md`
 > is the only exception and may use package-friendly hosted URLs.
 
-## Review & Approval _(mandatory before implementation)_
-
-- **Spec Path**: `docs/specs/002-superposition-config-file/spec.md`
-- **Commit Status**: Committed
-- **Review Status**: Approved
-- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
-
-## User Scenarios & Testing _(mandatory)_
+## User Scenarios & Testing
 
 ### User Story 1 - Generate from committed project config (Priority: P1)
 
@@ -77,7 +70,7 @@ A contributor receives clear guidance when the project config file is invalid, i
 - How does the system handle `adopt --project-file` when a repository already contains a supported project config file? It reuses that file path, and it must still stop on dual-file ambiguity so the source of truth stays deterministic.
 - How does the system handle project-file or manifest discovery from outside the target repository? An explicit project-root option may redirect persisted-input discovery and relative output resolution to that repository root.
 
-## Requirements _(mandatory)_
+## Requirements
 
 ### Functional Requirements
 
@@ -110,7 +103,7 @@ A contributor receives clear guidance when the project config file is invalid, i
 - **Customization Input**: A supported user-configurable generation setting beyond basic stack and overlay selection, such as custom container definitions, environment-related settings, or additional generated features that alter the final output.
 - **Validation Result**: The user-facing outcome of checking the project config file, including syntax problems, unsupported entries, conflict findings, ambiguity conditions, and corrective guidance.
 
-## Dependencies & Impact _(mandatory)_
+## Dependencies & Impact
 
 - **Affected Areas**: Standard initialization workflow, clean-generation parity, supported customization handling, manifest-based regeneration boundaries, project-file based regeneration boundaries, CLI usage patterns, onboarding workflow, CI/CD workflow, user documentation
 - **Compatibility Impact**: Backward compatible
@@ -124,7 +117,7 @@ A contributor receives clear guidance when the project config file is invalid, i
 - `--from-project` and `--from-manifest` are mutually exclusive persisted-input modes rather than additive sources for one run.
 - A single repository should contain at most one supported project config file so the source of truth stays deterministic and easy to explain.
 
-## Success Criteria _(mandatory)_
+## Success Criteria
 
 ### Measurable Outcomes