container-superposition 0.1.8 → 0.1.9

package/docs/specs/014-doctor-compose-port-cross-validation/spec.md

@@ -0,0 +1,276 @@
+# Feature Specification: Doctor Compose / Port Cross-Validation
+
+**Spec ID**: `014-doctor-compose-port-cross-validation`
+**Taxonomy**: `CLI-UX`
+**Created**: 2026-04-24
+**Author**: PM Agent
+**Status**: Approved
+**Input**: Feature assessment — `cs doctor` does not cross-check that ports declared in `devcontainer.json` `forwardPorts` match ports actually exposed by Docker Compose services, nor that compose service ports are accessible through the devcontainer configuration.
+
+## Problem Statement
+
+`cs doctor` already checks that individual overlay port declarations do not collide, but it never
+verifies cross-file consistency: a port that is `EXPOSE`d or bound in `docker-compose.yml` may be
+absent from `devcontainer.json` `forwardPorts` (making it inaccessible from the host), or
+`forwardPorts` may list a port that no compose service actually exposes (dead entry). These
+mismatches are invisible until the developer tries to connect to a service and finds it
+unreachable or wonders why a port they never requested is being forwarded.
+
+## Goals
+
+- Detect ports in `devcontainer.json` `forwardPorts` that do not correspond to any exposed port
+  across the compose services in `docker-compose.yml`.
+- Detect ports exposed by compose services that are absent from `forwardPorts` (informational
+  warning, not a hard failure — some ports are intentionally internal).
+- Operate on the generated output files, not the overlay sources, so the check reflects the
+  actual composed result.
+
+## Non-Goals
+
+- Checking that ports are not in use on the host machine at doctor-run time (that is a runtime
+  concern, not a configuration concern).
+- Modifying the port allocation algorithm in `composer.ts`.
+- Detecting intra-container port conflicts between services (already handled by the port
+  uniqueness check during composition).
+- Auto-fixing missing `forwardPorts` entries — the right fix is a `cs regen` once overlays are
+  corrected; port additions require overlay-level decisions.
+
+## Design
+
+### Port cross-validation check
+
+`checkPortCrossValidation(outputPath)` is a new synchronous function in
+`tool/commands/doctor.ts`. It operates on the generated output directory and returns
+`CheckResult[]`.
+
+**Early return**: if there is no `docker-compose.yml` in `outputPath` (plain devcontainer stack),
+return a single pass ("No compose stack — port cross-validation skipped").
+
+**Step 1 — Collect forwarded ports**
+
+Parse `devcontainer.json` from `outputPath`. Extract `forwardPorts` array. Each entry may be a
+bare port number, a `"host:container"` string, or a `"container/proto"` string. Normalise to the
+integer container port. If `devcontainer.json` has no `forwardPorts` key, treat as empty array.
+
+**Step 2 — Collect exposed compose ports**
+
+Parse `docker-compose.yml` from `outputPath`. For each service, collect:
+
+- `ports:` entries (short form `"host:container"`, `"container"`, `"host:container/proto"`; long
+  form object with `target`). Normalise to the integer container (target) port.
+- `expose:` entries (container-internal; not host-forwarded but still reachable within the
+  devcontainer network).
+
+Build two sets:
+
+- `boundPorts` — ports present in `ports:` (host-forwarded)
+- `exposedPorts` — ports present in `expose:` only (container-internal)
+
+**Step 3 — Cross-check**
+
+1. For each port in `forwardPorts`: if it is not in `boundPorts ∪ exposedPorts` →
+   **fail** ("Port `<N>` is listed in `forwardPorts` but is not exposed by any compose service").
+2. For each port in `boundPorts` that is not in `forwardPorts` →
+   **warn** ("Port `<N>` is bound by a compose service but is not in `forwardPorts` — it may be
+   inaccessible from the host").
+3. `exposedPorts`-only entries that are absent from `forwardPorts` are **not** reported (internal
+   communication is intentional).
+
+Pass check message: "`N` forwarded port(s) all match compose service declarations."
+
+### Fix eligibility
+
+Port cross-validation findings are **not auto-fixable** (`manual-only`). The correct resolution
+is to edit the overlay's `devcontainer.patch.json` or run `cs regen` after fixing the overlay.
+Both unknown forwarded ports (typos) and missing `forwardPorts` (coverage gaps) require the
+developer to make an intentional decision.
+
+### DoctorReport changes
+
+`DoctorReport` gains a `portCrossValidation: CheckResult[]` field.
+
+`generateReport()` gains a `portCrossValidationChecks` parameter.
+
+`formatAsText()` gains a "Port Cross-Validation" section that shows only failures and warnings;
+the section is suppressed entirely if all checks pass (matching the conventions for the
+`dependencies` and `parameters` sections).
+
+`reportToFindings()` adds:
+
+```typescript
+...checksToFindings(report.portCrossValidation, 'ports', 'full'),
+```
+
+`executeFixRun()` calls `checkPortCrossValidation()` in the re-check pass.
+
+`doctorCommand()` calls `checkPortCrossValidation(outputPath)` and passes results to
+`generateReport()`.
+
+### Port normalisation rules
+
+The normalisation helper `parseContainerPort(entry: string | number): number | null` extracts
+the container-side port from any `ports:` or `forwardPorts:` entry format:
+
+| Input                 | Result |
+| --------------------- | ------ |
+| `5432`                | `5432` |
+| `"5432"`              | `5432` |
+| `"5432/tcp"`          | `5432` |
+| `"5433:5432"`         | `5432` |
+| `"5433:5432/tcp"`     | `5432` |
+| `{ target: 5432 }`    | `5432` |
+| `"0.0.0.0:5433:5432"` | `5432` |
+
+Returns `null` for unparseable entries (log a warning, skip the entry).
+
+### Affected files
+
+| File                              | Change                                                                                                                      |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `tool/commands/doctor.ts`         | Add `checkPortCrossValidation()`, `parseContainerPort()`, wire into report infrastructure, `PRIORITY` map                   |
+| `tool/__tests__/commands.test.ts` | Tests for: no compose stack (skip), matching ports (pass), forward-only port (fail), bound-only port (warn), mixed scenario |
+| `CHANGELOG.md`                    | Entry under `### Added`                                                                                                     |
+
+### User-visible behaviour
+
+```
+Port Cross-Validation:
+  ✗ Port 9090 is listed in forwardPorts but is not exposed by any compose service
+    → Remove port 9090 from forwardPorts or add it to a compose service
+  ⚠ Port 5432 is bound by postgres service but is not in forwardPorts — it may be inaccessible
+    → Add 5432 to forwardPorts in your overlay's devcontainer.patch.json, then run cs regen
+  ✓ Port 6379 (redis): forwarded and exposed — OK
+```
+
+### Backward compatibility
+
+No changes to generated files or project file format. Purely additive check on existing output.
+
+## User Scenarios & Testing
+
+### User Story 1 — Stale `forwardPorts` entry caught (P1)
+
+A developer removed the `prometheus` overlay from their project but `forwardPorts` retained
+port `9090`. Doctor now flags the orphaned entry instead of silently forwarding a port to
+nowhere.
+
+**Why this priority**: A `forwardPorts` entry with no backing service is confusing and indicates
+an inconsistent configuration. It is the clearest actionable signal.
+
+**Independent Test**: Write a `devcontainer.json` with `forwardPorts: [9090]` and a
+`docker-compose.yml` with no service exposing 9090. Run `doctorCommand`. Assert `fail` finding
+mentioning port 9090 not exposed by any service.
+
+**Acceptance Scenarios**:
+
+1. **Given** `forwardPorts: [9090]` and no compose service exposes 9090, **When** `cs doctor`
+   runs, **Then** a `fail` finding reports "Port 9090 is listed in forwardPorts but is not
+   exposed by any compose service".
+2. **Given** `forwardPorts: [5432]` and postgres exposes `5432`, **When** `cs doctor` runs,
+   **Then** no failure is reported for port 5432.
+
+---
+
+### User Story 2 — Silently inaccessible compose port flagged (P2)
+
+A developer composed `redis` and `postgres` but their devcontainer patch never added the postgres
+port to `forwardPorts`. Doctor warns them that port 5432 is bound but not forwarded.
+
+**Why this priority**: Missing `forwardPorts` is easy to overlook and causes "connection refused"
+errors that are hard to diagnose without knowing about `forwardPorts`.
+
+**Independent Test**: Write a `docker-compose.yml` with postgres exposing port `5432` on the
+host. Write a `devcontainer.json` with `forwardPorts: [6379]`. Run `doctorCommand`. Assert
+a `warn` finding for port 5432.
+
+**Acceptance Scenarios**:
+
+1. **Given** postgres exposes host port 5432 and `forwardPorts` does not include 5432, **When**
+   `cs doctor` runs, **Then** a `warn` finding reports port 5432 not in `forwardPorts`.
+2. **Given** all compose ports are also in `forwardPorts`, **When** `cs doctor` runs, **Then**
+   the port cross-validation section is suppressed (all pass).
+
+---
+
+### User Story 3 — Plain devcontainer stack skipped (P3)
+
+A developer uses a plain devcontainer (no Docker Compose). Doctor skips port cross-validation
+gracefully.
+
+**Acceptance Scenarios**:
+
+1. **Given** no `docker-compose.yml` in the output directory, **When** `cs doctor` runs, **Then**
+   port cross-validation returns a single pass and the section is suppressed in text output.
+
+---
+
+### Edge Cases
+
+- `forwardPorts` absent from `devcontainer.json`: treated as empty — warn for every bound port.
+- Compose service with only `expose:` (not `ports:`): not warned if absent from `forwardPorts`
+  (intentionally container-internal).
+- Port `0` or invalid port entries: skip with a debug trace, do not report as a failure.
+- Compose file not parseable: return a single `fail` ("Could not parse docker-compose.yml for
+  port cross-validation — file may be malformed").
+
+## Requirements
+
+### Functional Requirements
+
+- **FR-001**: `checkPortCrossValidation()` MUST return `fail` for each port in `forwardPorts`
+  that is not in the set of ports declared in the compose `ports:` or `expose:` blocks.
+- **FR-002**: `checkPortCrossValidation()` MUST return `warn` for each port in compose `ports:`
+  blocks that is absent from `forwardPorts`.
+- **FR-003**: Ports present only in compose `expose:` blocks (not `ports:`) MUST NOT generate
+  a warning if absent from `forwardPorts`.
+- **FR-004**: When no `docker-compose.yml` is present in the output directory, the check MUST
+  return a single pass and generate no findings.
+- **FR-005**: The check MUST support all `ports:` entry formats (short string, long object,
+  IP-prefixed) using `parseContainerPort()`.
+- **FR-006**: Findings MUST be marked `manual-only` (no auto-fix).
+
+### Key Entities
+
+- **`boundPorts`**: set of integer container ports declared in compose `ports:` blocks (host-accessible).
+- **`exposedPorts`**: set of integer container ports declared in compose `expose:` blocks only.
+- **`forwardedPorts`**: set of integer ports from `devcontainer.json` `forwardPorts`.
+
+## Dependencies & Impact
+
+- **Affected Areas**: `tool/commands/doctor.ts`, `tool/__tests__/commands.test.ts`, `CHANGELOG.md`
+- **Compatibility Impact**: None — purely additive check category.
+- **Required Documentation Updates**: `CHANGELOG.md`
+- **Verification Plan**: Unit tests in `commands.test.ts`; manual test with a real compose-based
+  project file.
+
+## Success Criteria
+
+### Measurable Outcomes
+
+- **SC-001**: `cs doctor` on an output directory where `forwardPorts` contains a port not in any
+  compose service reports a `fail` within the Port Cross-Validation section.
+- **SC-002**: `cs doctor` on a plain devcontainer (no `docker-compose.yml`) produces no output
+  in the Port Cross-Validation section.
+- **SC-003**: `npm test` passes with at least 3 new test cases covering: no compose stack, stale
+  forwarded port, missing forwarded port.
+- **SC-004**: No existing doctor tests regress.
+
+## Open Questions
+
+| #   | Question                                                                              | Owner | Resolution                                              |
+| --- | ------------------------------------------------------------------------------------- | ----- | ------------------------------------------------------- |
+| 1   | Should bound-but-not-forwarded ports be `warn` or `info`? Both options are defensible | PM    | Pending — lean toward `warn` to surface it visibly      |
+| 2   | Should `--fix` add missing `forwardPorts` entries by patching the project file?       | PM    | Pending — deferred; unclear which overlay owns the port |
+
+## Out of Scope
+
+- Checking host-side port availability at runtime.
+- Modifying how `composer.ts` generates `forwardPorts`.
+- Validating that overlay-level port declarations match compose file declarations (that is the
+  overlay-reviewer agent's job).
+
+## Implementation Notes
+
+- `parseContainerPort` strips protocol suffixes (`/tcp`, `/udp`) and range notation (`8080-8090`), returning the numeric port or `null` for non-numeric values.
+- The check skips early when `docker-compose.yml` is absent in the output path (compose-only feature).
+- `js-yaml` is imported statically at the top of `doctor.ts` (was previously a dynamic import in `checkPortCrossValidation`, which caused an `await` in a synchronous function — fixed by moving to a top-level static import).

package/docs/specs/015-doctor-env-example-drift/spec.md

@@ -0,0 +1,248 @@
+# Feature Specification: Doctor `.env.example` Drift Detection
+
+**Spec ID**: `015-doctor-env-example-drift`
+**Taxonomy**: `CLI-UX`
+**Created**: 2026-04-24
+**Author**: PM Agent
+**Status**: Approved
+**Input**: Feature assessment — `cs doctor` does not detect when `.env.example` is stale: missing keys for parameters added by new overlays, or keys left over from overlays that were removed.
+
+## Problem Statement
+
+When a developer adds or removes overlays and runs `cs regen`, the generated `docker-compose.yml`
+and `devcontainer.json` are updated, but `.env.example` may drift from the actual parameter set
+in use. A key missing from `.env.example` means a new team member who onboards by copying the
+file will silently omit a required secret. A stale key left behind from a removed overlay
+creates confusion about which variables are needed. Doctor should detect both directions of drift
+and offer a `--fix` that regenerates `.env.example` to match the current overlay selection.
+
+## Goals
+
+- Detect parameter keys referenced in the current overlay selection that are absent from the
+  generated `.env.example`.
+- Detect keys present in `.env.example` that are no longer declared by any selected overlay.
+- Allow `doctor --fix` to regenerate `.env.example` from the current project configuration.
+
+## Non-Goals
+
+- Validating the actual values in `.env` (the user's runtime secrets file — not committed).
+- Checking whether `.env` is gitignored (separate concern).
+- Modifying the parameter schema or the `.env.example` generation logic in `composer.ts`.
+- Generating `.env.example` from scratch when it does not exist (that is covered by spec 012 /
+  the existing parameters check in spec implemented for the parameter doctor feature).
+
+## Design
+
+### Env example drift check
+
+`checkEnvExampleDrift(overlaysConfig, outputPath, workingDir)` is a new synchronous function in
+`tool/commands/doctor.ts`. It returns `CheckResult[]`.
+
+**Early return**: if no project file is present, return empty (no noise). If the output
+directory has no `.env.example`, return a single pass ("No `.env.example` present — skipping
+drift check") — the missing-file case is handled by the parameters check (spec 012).
+
+**Step 1 — Collect declared parameter keys**
+
+Call `collectOverlayParameters(overlaysConfig, selection.overlays)` where `selection` comes from
+`loadProjectConfig(workingDir)`. This returns the full `ParameterDeclaration[]` for the selected
+overlay set. Extract the set of unique `key` strings: `declaredKeys`.
+
+**Step 2 — Parse `.env.example`**
+
+Read `outputPath/.env.example`. Parse each non-comment, non-blank line as `KEY=...` (or
+`KEY` alone). Extract the set of keys: `exampleKeys`. Lines starting with `#` are skipped.
+Section header comments (`# --- Service ---`) are also skipped.
+
+**Step 3 — Diff**
+
+- `missingFromExample = declaredKeys − exampleKeys`: keys declared by overlays but absent from
+  `.env.example` → **fail** ("Parameter `<KEY>` declared by overlay `<id>` is missing from
+  `.env.example`").
+- `staleInExample = exampleKeys − declaredKeys`: keys in `.env.example` not declared by any
+  selected overlay → **warn** ("Key `<KEY>` in `.env.example` is not declared by any selected
+  overlay — it may be stale").
+
+Pass check message: "`.env.example` is in sync with `N` declared parameter(s)."
+
+### Fix action: `env-example-regen`
+
+Registered in `REMEDIATION_REGISTRY`:
+
+- **Safety class**: `safe-unattended`
+- **Execution kind**: `regeneration`
+- **Planned changes**:
+    - "Regenerate `.env.example` from current overlay selection"
+
+`executeEnvExampleRegen(outputPath, overlaysConfig, overlaysDir, workingDir, silent)`:
+
+1. Load project config.
+2. Rebuild answers via `buildAnswersFromProjectConfig()` + `applyPresetSelections()`.
+3. Call `composeDevContainer(answers, overlaysDir, { isRegen: true })` — the composer already
+   regenerates `.env.example` as part of a full regen.
+4. Re-check: verify drift findings are resolved.
+
+Unknown stale keys are regenerated away (the composer rewrites `.env.example` from scratch). This
+is safe because `.env.example` is a committed template, not a secrets file.
+
+### DoctorReport changes
+
+`DoctorReport` gains an `envExampleDrift: CheckResult[]` field.
+
+`generateReport()` gains an `envExampleDriftChecks` parameter.
+
+`formatAsText()` gains a ".env.example Drift" section; suppressed if all pass.
+
+`reportToFindings()` adds:
+
+```typescript
+...checksToFindings(report.envExampleDrift, 'manifest', 'full'),
+```
+
+`executeFixRun()` calls `checkEnvExampleDrift()` in the re-check pass.
+
+### Affected files
+
+| File                              | Change                                                                                                                            |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `tool/commands/doctor.ts`         | Add `checkEnvExampleDrift()`, `executeEnvExampleRegen()`, wire into report infrastructure, `REMEDIATION_REGISTRY`, `PRIORITY` map |
+| `tool/__tests__/commands.test.ts` | Tests for: missing key (fail), stale key (warn), in-sync (pass), fix action                                                       |
+| `CHANGELOG.md`                    | Entry under `### Added`                                                                                                           |
+
+### User-visible behaviour
+
+```
+.env.example Drift:
+  ✗ Parameter POSTGRES_PASSWORD declared by postgres is missing from .env.example
+    → Run cs regen or use --fix to regenerate .env.example
+    → Fixable with --fix flag
+  ⚠ Key OLD_API_KEY in .env.example is not declared by any selected overlay — it may be stale
+    → Remove OLD_API_KEY from .env.example or run --fix to regenerate
+    → Fixable with --fix flag
+  ✓ .env.example is in sync with 5 declared parameter(s)
+```
+
+### Backward compatibility
+
+No changes to existing generated files or project file format. Purely additive check.
+
+## User Scenarios & Testing
+
+### User Story 1 — Missing key caught after overlay addition (P1)
+
+A developer adds the `vault` overlay (which declares `VAULT_TOKEN`) to their project and runs
+`cs regen`. Due to a bug or partial regen, `.env.example` is not updated. Doctor detects the
+missing key immediately.
+
+**Why this priority**: A missing key in `.env.example` silently breaks onboarding for every
+future team member who copies the file as their starting `.env`.
+
+**Independent Test**: Write a `.superposition.yml` selecting `postgres`. Write a `.env.example`
+that lacks `POSTGRES_PASSWORD`. Run `doctorCommand`. Assert `fail` finding for
+`POSTGRES_PASSWORD`.
+
+**Acceptance Scenarios**:
+
+1. **Given** `.superposition.yml` selects `postgres` (declares `POSTGRES_PASSWORD`) and
+   `.env.example` does not contain `POSTGRES_PASSWORD`, **When** `cs doctor` runs, **Then** a
+   `fail` finding reports "`POSTGRES_PASSWORD` declared by `postgres` is missing from
+   `.env.example`".
+2. **Given** the same setup with `--fix`, **When** doctor runs, **Then** `.env.example` is
+   regenerated containing `POSTGRES_PASSWORD` and the re-check passes.
+3. **Given** `.env.example` contains all keys for the current overlay selection, **When**
+   `cs doctor` runs, **Then** the `.env.example Drift` section is suppressed.
+
+---
+
+### User Story 2 — Stale key caught after overlay removal (P2)
+
+A developer removes `redis` from their project but forgets to re-run regen. `.env.example`
+still contains `REDIS_PASSWORD`. Doctor warns them it is stale.
+
+**Why this priority**: Stale `.env.example` keys cause confusion about required configuration and
+may expose unneeded credentials to documentation reviewers.
+
+**Independent Test**: Write a `.superposition.yml` without `redis`. Write a `.env.example` that
+contains `REDIS_PASSWORD`. Run `doctorCommand`. Assert `warn` finding for `REDIS_PASSWORD`.
+
+**Acceptance Scenarios**:
+
+1. **Given** `.env.example` contains `REDIS_PASSWORD` but no selected overlay declares it,
+   **When** `cs doctor` runs, **Then** a `warn` finding reports "`REDIS_PASSWORD` in `.env.example`
+   is not declared by any selected overlay".
+2. **Given** `--fix` is used, **When** doctor runs, **Then** `.env.example` is regenerated without
+   `REDIS_PASSWORD`.
+
+---
+
+### Edge Cases
+
+- `.env.example` with only comments and blank lines: treated as having zero keys; any declared
+  parameters generate `fail` findings.
+- Overlay with parameters but none sensitive: still checked for drift (drift check is not
+  limited to sensitive parameters).
+- `.env.example` present but empty (zero bytes): treated the same as all-comment case.
+- No project file: return empty result (no noise).
+- Compose `${VAR:-default}` references in docker-compose.yml but not in overlay `parameters:`:
+  not flagged — the drift check only compares declared overlay parameters, not raw compose
+  variable references.
+
+## Requirements
+
+### Functional Requirements
+
+- **FR-001**: `checkEnvExampleDrift()` MUST return `fail` for each parameter key declared by a
+  selected overlay that is absent from `.env.example`.
+- **FR-002**: `checkEnvExampleDrift()` MUST return `warn` for each key in `.env.example` not
+  declared by any selected overlay.
+- **FR-003**: When `.env.example` is absent, the check MUST return a single pass (the missing-file
+  scenario is handled by the parameters check in `checkParameters()`).
+- **FR-004**: `executeEnvExampleRegen()` MUST regenerate `.env.example` via a full `composeDevContainer`
+  call and MUST NOT leave stale keys behind.
+- **FR-005**: Comment lines and blank lines in `.env.example` MUST NOT be counted as parameter keys.
+- **FR-006**: When no project file is present, the check MUST return an empty result.
+
+### Key Entities
+
+- **`declaredKeys`**: set of parameter key strings from `collectOverlayParameters()` for the current overlay selection.
+- **`exampleKeys`**: set of key strings parsed from non-comment, non-blank lines in `.env.example`.
+
+## Dependencies & Impact
+
+- **Affected Areas**: `tool/commands/doctor.ts`, `tool/__tests__/commands.test.ts`, `CHANGELOG.md`
+- **Compatibility Impact**: None — purely additive check category.
+- **Required Documentation Updates**: `CHANGELOG.md`
+- **Verification Plan**: Unit tests in `commands.test.ts`; manual test after adding then removing
+  an overlay from a real project file.
+
+## Success Criteria
+
+### Measurable Outcomes
+
+- **SC-001**: `cs doctor` on a project where `.env.example` is missing a declared parameter
+  reports a `fail` in the `.env.example Drift` section.
+- **SC-002**: `cs doctor --fix` on the same setup regenerates `.env.example` and the re-check
+  passes with no drift findings.
+- **SC-003**: `npm test` passes with at least 3 new test cases covering: missing key, stale key,
+  and fix action.
+- **SC-004**: No existing doctor tests regress.
+
+## Open Questions
+
+| #   | Question                                                                                  | Owner | Resolution                                                                           |
+| --- | ----------------------------------------------------------------------------------------- | ----- | ------------------------------------------------------------------------------------ |
+| 1   | Should missing `.env.example` keys be `fail` or `warn`? Missing required params are fail; | PM    | Pending — lean toward `fail` for keys with no default, `warn` for keys with defaults |
+|     | but all parameters already have defaults (required-without-default is a separate check)   |       |                                                                                      |
+| 2   | Should section header comments be preserved when regenerating `.env.example`?             | PM    | The composer already handles this; not a new concern                                 |
+
+## Out of Scope
+
+- Validating values in the user's runtime `.env` file.
+- Checking whether `.env` is listed in `.gitignore`.
+- Detecting drift in `devcontainer.json` `remoteEnv` (that is covered by the parameters check).
+
+## Implementation Notes
+
+- `checkEnvExampleDrift` uses `collectOverlayParameters` to get the declared parameter set for the selected overlays, then diffs against lines parsed from the existing `.env.example`.
+- The check returns early (no findings) when `.env.example` is absent — the parameters check is responsible for detecting its absence when required.
+- `executeEnvExampleRegen` calls `composeDevContainer` with `isRegen: false` writing only to the output path, then re-reads `.env.example` to verify the file was produced.