container-superposition 0.1.8 → 0.1.10

package/docs/specs/016-doctor-reproducibility-check/spec.md

@@ -0,0 +1,276 @@
+# Feature Specification: Doctor Reproducibility Check
+
+**Spec ID**: `016-doctor-reproducibility-check`
+**Taxonomy**: `CLI-UX`
+**Created**: 2026-04-24
+**Author**: PM Agent
+**Status**: Approved
+**Input**: Feature assessment — `cs doctor` cannot tell whether the generated `.devcontainer/` output is up-to-date with the project file; a developer may have edited generated files by hand or added overlays without re-running `cs regen`.
+
+## Problem Statement
+
+After `cs regen` runs, the generated `.devcontainer/` directory is derived deterministically from
+the project file and the overlay registry. If a developer then manually edits a generated file,
+adds a new overlay without re-running `cs regen`, or changes a parameter value, the generated
+output becomes inconsistent with the project file — but nothing in the current toolchain detects
+this. Doctor should detect "regen needed" situations and prompt the developer to run `cs regen`
+(or do so automatically with `--fix`).
+
+## Goals
+
+- Detect when the generated output no longer matches what `cs regen` would produce from the
+  current project file and overlay registry.
+- Allow `doctor --fix` to resolve the inconsistency by running a fresh `cs regen`.
+- Produce a clear, actionable message pointing to which file(s) differ.
+
+## Non-Goals
+
+- Storing a cryptographic content-addressable hash of every generated byte (too brittle when
+  line endings or file ordering varies by OS).
+- Detecting manual edits in non-generated files (files that `cs regen` does not own).
+- Replacing `cs regen` — the fix action simply calls it.
+- Validating overlay registry changes (a changed overlay that breaks composition is a different
+  problem).
+
+## Design
+
+### Reproducibility fingerprint approach
+
+The check operates by performing a **dry regen** — composing the devcontainer in memory into a
+temporary directory, then comparing the result file-by-file against the current output directory.
+This is more reliable than a stored hash because it reflects the current overlay registry state
+and always computes the ground truth.
+
+`checkReproducibility(overlaysConfig, outputPath, overlaysDir, workingDir)` is a new async
+function in `tool/commands/doctor.ts`.
+
+**Early return**: if no project file is present, return empty (no noise).
+
+**Step 1 — Dry compose**
+
+1. Load project config via `loadProjectConfig(workingDir)`.
+2. Rebuild answers via `buildAnswersFromProjectConfig()` + `applyPresetSelections()`.
+3. Create a temporary directory (use `os.mkdtemp`).
+4. Call `composeDevContainer(answers, overlaysDir, { isRegen: false, outputPath: tmpDir })`.
+5. The temporary directory now contains what regen would produce.
+
+**Step 2 — File comparison**
+
+List all files in `outputPath` (recursively) that are owned by `cs regen` — i.e., those present
+in the temp directory or that have the `# Generated by container-superposition` header comment.
+
+For each file in the temp directory:
+
+- If absent from `outputPath` → **fail** ("File `<path>` would be created by `cs regen` but
+  does not exist — run `cs regen` to synchronise").
+- If content differs → **fail** ("File `<path>` differs from what `cs regen` would produce —
+  it may have been manually edited or is out of date").
+
+For each file in `outputPath` with the generation header that is absent from the temp directory:
+
+- **warn** ("File `<path>` exists but `cs regen` would not produce it — it may be stale").
+
+**Step 3 — Cleanup**
+
+Remove the temporary directory unconditionally (inside a `finally` block).
+
+Pass check message: "Generated output matches current project configuration."
+
+### Generated file identification
+
+A file is "owned by regen" if it satisfies **any** of:
+
+1. Its first line matches `# Generated by container-superposition` (shell/yaml convention).
+2. Its first line matches `// Generated by container-superposition` (JSON, ts convention).
+3. It appears in the temp directory output (ground truth).
+
+This avoids false positives on user-created files in `.devcontainer/` that regen does not touch.
+
+### Fix action: `reproducibility-regen`
+
+Registered in `REMEDIATION_REGISTRY`:
+
+- **Safety class**: `safe-unattended`
+- **Execution kind**: `regeneration`
+- **Planned changes**:
+    - "Regenerate devcontainer configuration from current project file"
+
+`executeReproducibilityRegen(outputPath, overlaysConfig, overlaysDir, workingDir, silent)`:
+
+1. Load project config.
+2. Rebuild answers and call `composeDevContainer(answers, overlaysDir, { isRegen: true })`.
+3. Re-check: run `checkReproducibility()` and verify it returns no failures.
+
+Note: since this is a destructive overwrite of generated files, the fix is safe only because
+regen is idempotent and the files are derived outputs, not user data.
+
+### Performance note
+
+The dry compose is the same operation as `cs regen` but writes to a temp dir. On typical projects
+(< 20 overlays) this takes under 500 ms. If the operation is too slow for CI use, a future
+optimisation could introduce a stored hash file (`.devcontainer/.superposition-hash`) as a
+shortcut — but this is out of scope for the initial implementation.
+
+### DoctorReport changes
+
+`DoctorReport` gains a `reproducibility: CheckResult[]` field.
+
+`generateReport()` gains a `reproducibilityChecks` parameter.
+
+`formatAsText()` gains a "Reproducibility" section; suppressed if all pass.
+
+`reportToFindings()` adds:
+
+```typescript
+...checksToFindings(report.reproducibility, 'manifest', 'full'),
+```
+
+`executeFixRun()` calls `checkReproducibility()` in the re-check pass.
+
+`doctorCommand()` calls `await checkReproducibility(...)` and passes results to `generateReport()`.
+
+Note: because `checkReproducibility()` is async, `doctorCommand()` and the section of
+`generateReport()` that invokes checks must await it. The existing doctor checks are synchronous;
+this will be the first async check. The wiring pattern must be adjusted to `await` the async
+check before building the report.
+
+### Affected files
+
+| File                              | Change                                                                                                                                                                                            |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tool/commands/doctor.ts`         | Add `checkReproducibility()` (async), `executeReproducibilityRegen()`, wire into report infrastructure, `REMEDIATION_REGISTRY`, `PRIORITY` map; adjust `doctorCommand()` to `await` the new check |
+| `tool/__tests__/commands.test.ts` | Tests for: clean output (pass), missing file (fail), differing file (fail), extra generated file (warn), fix action                                                                               |
+| `CHANGELOG.md`                    | Entry under `### Added`                                                                                                                                                                           |
+
+### User-visible behaviour
+
+```
+Reproducibility:
+  ✗ File devcontainer.json differs from what cs regen would produce
+    → It may have been manually edited or is out of date
+    → Run cs regen or use --fix to synchronise
+  ✗ File scripts/setup.sh would be created by cs regen but does not exist
+    → Run cs regen to synchronise
+  ⚠ File devcontainer.json.bak exists but cs regen would not produce it — it may be stale
+  ✓ Generated output matches current project configuration
+```
+
+### Backward compatibility
+
+No changes to generated files or project file format. The dry compose uses the same code paths
+as `cs regen` — if regen works, the check works.
+
+## User Scenarios & Testing
+
+### User Story 1 — Manual edit detected (P1)
+
+A developer tweaked `devcontainer.json` to add a custom extension, then forgot to re-run
+`cs regen` after changing an overlay parameter. Doctor reports that the file differs from what
+regen would produce.
+
+**Why this priority**: Manual edits to generated files are a common source of "it works on my
+machine" bugs. Detecting them immediately is the highest-value use of the reproducibility check.
+
+**Independent Test**: Write a `devcontainer.json` that differs from what `composeDevContainer`
+would produce for the given project file. Run `doctorCommand`. Assert `fail` finding for
+`devcontainer.json`.
+
+**Acceptance Scenarios**:
+
+1. **Given** `devcontainer.json` has been manually modified after the last regen, **When**
+   `cs doctor` runs, **Then** a `fail` finding reports "`devcontainer.json` differs from what
+   `cs regen` would produce".
+2. **Given** `--fix` is used, **When** doctor runs, **Then** `devcontainer.json` is regenerated
+   and the re-check passes.
+3. **Given** the output exactly matches what regen would produce, **When** `cs doctor` runs,
+   **Then** the Reproducibility section is suppressed.
+
+---
+
+### User Story 2 — Missing generated file detected (P2)
+
+A developer deleted `scripts/setup.sh` accidentally. Doctor flags the missing file.
+
+**Acceptance Scenarios**:
+
+1. **Given** `scripts/setup.sh` would be produced by regen but is absent, **When** `cs doctor`
+   runs, **Then** a `fail` finding reports that the file would be created by regen but does not
+   exist.
+2. **Given** `--fix` is used, **When** doctor runs, **Then** the file is restored.
+
+---
+
+### Edge Cases
+
+- Output directory does not exist: return a single `fail` ("Output directory `<path>` not found
+  — run `cs regen` to initialise").
+- Temp directory creation fails (disk full): return a single `fail` with the OS error message.
+- Compose call in dry mode throws: propagate the error as a `fail` finding; cleanup temp dir
+  in `finally`.
+- Files owned by regen that differ only in line endings (CRLF vs LF): normalise to LF before
+  comparison so Windows checkouts do not generate false positives.
+
+## Requirements
+
+### Functional Requirements
+
+- **FR-001**: `checkReproducibility()` MUST return `fail` for each file that would be produced
+  by `cs regen` but is absent from the output directory.
+- **FR-002**: `checkReproducibility()` MUST return `fail` for each generated file whose content
+  differs from what `cs regen` would produce (after LF normalisation).
+- **FR-003**: `checkReproducibility()` MUST return `warn` for each file in the output directory
+  with a generation header that `cs regen` would not produce.
+- **FR-004**: `checkReproducibility()` MUST NOT report findings for files that are not owned by
+  regen (user-created files without the generation header).
+- **FR-005**: The temporary directory used for dry compose MUST be cleaned up in a `finally`
+  block regardless of whether the check succeeds or fails.
+- **FR-006**: `executeReproducibilityRegen()` MUST call `composeDevContainer` with `isRegen: true`
+  and verify the re-check returns no failures.
+- **FR-007**: When no project file is present, the check MUST return an empty result.
+
+### Key Entities
+
+- **`dryOutput`**: the set of files produced by `composeDevContainer` into a temp directory for the current project configuration.
+- **Generation header**: the comment `# Generated by container-superposition` or `// Generated by container-superposition` on the first line of a file.
+
+## Dependencies & Impact
+
+- **Affected Areas**: `tool/commands/doctor.ts`, `tool/__tests__/commands.test.ts`, `CHANGELOG.md`
+- **Compatibility Impact**: None — purely additive. `composeDevContainer` gains an optional
+  `outputPath` parameter override if it does not already have one; otherwise a wrapper is used.
+- **Required Documentation Updates**: `CHANGELOG.md`
+- **Verification Plan**: Unit tests with mock filesystem; integration test with a real project file.
+
+## Success Criteria
+
+### Measurable Outcomes
+
+- **SC-001**: `cs doctor` on a project where a generated file has been manually edited reports a
+  `fail` in the Reproducibility section within the normal doctor runtime budget.
+- **SC-002**: `cs doctor --fix` on the same setup restores the file and the re-check passes.
+- **SC-003**: `npm test` passes with at least 4 new test cases: clean output, missing file,
+  differing content, fix action.
+- **SC-004**: No existing doctor tests regress.
+
+## Open Questions
+
+| #   | Question                                                                                          | Owner | Resolution                                                         |
+| --- | ------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------------------------ |
+| 1   | Does `composeDevContainer` currently support an `outputPath` override, or does it always write to | Dev   | Pending — needs code read of composer.ts                           |
+|     | a fixed location derived from `workingDir`?                                                       |       |                                                                    |
+| 2   | Should the dry compose run be cached between doctor check runs to avoid double work when          | PM    | Pending — defer; optimise only if latency is measured as a problem |
+|     | both `checkReproducibility` and other checks need the composed output?                            |       |                                                                    |
+| 3   | Line-ending normalisation: is CRLF a realistic concern in this repo's CI matrix?                  | Dev   | Pending — check .gitattributes                                     |
+
+## Out of Scope
+
+- Storing a persistent hash file between runs (future optimisation only).
+- Detecting which specific overlay or parameter change caused the drift.
+- Tracking changes to overlay registry files as a trigger for "regen needed".
+
+## Implementation Notes
+
+- `checkReproducibility` returns early when `outputPath` or `outputPath/devcontainer.json` does not exist — this prevents false positives in fresh environments where regen has never been run.
+- `composeDevContainer` was called with a temp directory for the dry compose; the temp dir is cleaned up in a `finally` block unconditionally.
+- The `os` module was added as a new import to `doctor.ts` for `os.tmpdir()`.
+- Open question 1 (re: `composeDevContainer` `outputPath` override) was resolved by passing the temp directory as the `outputPath` option.

package/docs/specs/017-doctor-dry-run/spec.md

@@ -0,0 +1,276 @@
+# Feature Specification: Doctor `--fix --dry-run` Flag
+
+**Spec ID**: `017-doctor-dry-run`
+**Taxonomy**: `CLI-FLAG`
+**Created**: 2026-04-24
+**Author**: PM Agent
+**Status**: Approved
+**Input**: Feature assessment — `cs doctor --fix` applies changes immediately with no preview; users have no way to understand what would change before committing to auto-repair.
+
+## Problem Statement
+
+`cs doctor --fix` is a powerful command that modifies the project file and regenerates the
+devcontainer in one step. Users — especially those new to the project — have no way to preview
+what changes `--fix` would make before applying them. This makes `--fix` feel risky and
+discourages adoption. A `--dry-run` modifier should show exactly what would change without
+writing anything, enabling confident use of `--fix`.
+
+## Goals
+
+- Add a `--dry-run` flag (usable only in combination with `--fix`) that prints a human-readable
+  plan of what each fix action would do without executing any file writes.
+- Show the planned changes for every auto-fixable finding: which files would be written, which
+  keys would be added to the project file, and what regen would regenerate.
+- Exit with a non-zero exit code when there are findings that would be fixed (so CI can detect
+  "fix needed" without applying the fix).
+
+## Non-Goals
+
+- Implementing a diff of generated file content (file-level diff is an enhancement, not
+  required for the initial implementation).
+- Applying partial fixes (dry-run is all-or-nothing: show the plan for all auto-fixable findings
+  or none).
+- Changing any existing `--fix` behaviour (dry-run is a separate flag, not a modifier to the
+  existing logic).
+- Supporting `--dry-run` without `--fix` (without `--fix`, there is nothing to dry-run; the
+  combination is invalid).
+
+## Design
+
+### CLI flag
+
+`doctor` gains a new option: `--dry-run` (boolean, default `false`).
+
+The Commander declaration:
+
+```typescript
+.option('--dry-run', 'Show what --fix would change without writing anything')
+```
+
+Validation: if `--dry-run` is set but `--fix` is not set, print an error and exit:
+
+```
+Error: --dry-run requires --fix. Use: cs doctor --fix --dry-run
+```
+
+### Dry-run execution flow
+
+When `--fix --dry-run` is used:
+
+1. Run all doctor checks as normal (same as `--fix`).
+2. Collect all auto-fixable findings by consulting `REMEDIATION_REGISTRY` for each finding's
+   remediation key.
+3. For each auto-fixable finding, look up the `RemediationAction.plannedChanges` array in
+   `REMEDIATION_REGISTRY`. These are already stored as human-readable strings per the existing
+   spec 004 design.
+4. Print the dry-run plan (see "User-visible behaviour" below).
+5. **Do not call `executeSingleFix()` or `executeFixRun()`** — no writes occur.
+6. Exit with code `1` if there are auto-fixable findings (to support CI use); exit with `0` if
+   all findings are already clean.
+
+### Integration with `executeFixRun`
+
+`executeFixRun(findings, options)` gains a `dryRun: boolean` parameter (default `false`).
+
+When `dryRun` is `true`:
+
+- Skip all `executeSingleFix()` calls.
+- Return a summary marked as `{ dryRun: true, plannedActions: RemediationPlan[] }`.
+
+`RemediationPlan` (new type):
+
+```typescript
+interface RemediationPlan {
+    findingName: string;
+    remediationKey: string;
+    plannedChanges: string[];
+    safetyClass: string;
+}
+```
+
+### Output format
+
+```
+Doctor dry-run — changes that --fix would apply:
+══════════════════════════════════════════════════
+
+  [1] parameters-regen (safe-unattended)
+      Finding: "Missing required parameter: POSTGRES_PASSWORD"
+      Would:
+        • Add missing parameters with overlay defaults to project file
+        • Regenerate devcontainer configuration from project file
+
+  [2] dependency-fix (safe-unattended)
+      Finding: "Overlay grafana requires prometheus which is not in your project file"
+      Would:
+        • Add missing required overlay(s) to project file
+        • Regenerate devcontainer configuration from updated project file
+
+  [3] env-example-regen (safe-unattended)
+      Finding: "Parameter POSTGRES_PASSWORD is missing from .env.example"
+      Would:
+        • Regenerate .env.example from current overlay selection
+
+──────────────────────────────────────────────────
+  3 fix action(s) would be applied. Run without --dry-run to apply.
+
+Findings that require manual action (not auto-fixable):
+  ✗ Overlay nodjs not found in overlay registry — check for typos
+    → Edit .superposition.yml to correct the overlay ID
+```
+
+When there are no auto-fixable findings:
+
+```
+Doctor dry-run — no auto-fixable findings. Nothing to apply.
+```
+
+### JSON output (--format json)
+
+When `--format json` is used with `--fix --dry-run`, the JSON output gains a `dryRun` key:
+
+```json
+{
+  "dryRun": true,
+  "plannedActions": [
+    {
+      "findingName": "Missing required parameter: POSTGRES_PASSWORD",
+      "remediationKey": "parameters-regen",
+      "plannedChanges": ["Add missing parameters with overlay defaults to project file", "Regenerate devcontainer configuration from project file"],
+      "safetyClass": "safe-unattended"
+    }
+  ],
+  "manualFindings": [...]
+}
+```
+
+### Exit codes
+
+| Scenario                                            | Exit code |
+| --------------------------------------------------- | --------- |
+| Dry-run with auto-fixable findings                  | `1`       |
+| Dry-run with only manual findings (no auto-fixable) | `1`       |
+| Dry-run with no findings at all (everything passes) | `0`       |
+| `--dry-run` without `--fix` (invalid combination)   | `1`       |
+
+### Affected files
+
+| File                              | Change                                                                                                                                              |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tool/commands/doctor.ts`         | Add `--dry-run` option, `RemediationPlan` type, dry-run branch in `executeFixRun`, dry-run output section in `formatAsText`                         |
+| `tool/__tests__/commands.test.ts` | Tests for: dry-run output lists planned actions, no writes occur, exit code 1 with findings, exit code 0 clean, invalid `--dry-run` without `--fix` |
+| `CHANGELOG.md`                    | Entry under `### Added`                                                                                                                             |
+
+### User-visible behaviour
+
+See the output format section above. The key constraint: no files are modified when `--dry-run`
+is active — not the project file, not any generated file, not `.env.example`.
+
+### Backward compatibility
+
+`--dry-run` is a new flag — no existing behaviour changes. `--fix` without `--dry-run` continues
+to work exactly as before. The new `dryRun` parameter on `executeFixRun` defaults to `false`.
+
+## User Scenarios & Testing
+
+### User Story 1 — Safe preview before first `--fix` use (P1)
+
+A developer is onboarding to a project and sees 3 doctor failures. Before running `--fix`, they
+run `cs doctor --fix --dry-run` to understand what will change.
+
+**Why this priority**: `--fix` modifies the project file and regenerates. Without a preview,
+users are reluctant to use it. Dry-run is the single biggest adoption unblock for `--fix`.
+
+**Independent Test**: Set up a project with a missing required parameter and a missing required
+overlay dependency. Run `doctorCommand --fix --dry-run`. Assert no files were written and output
+contains both planned actions.
+
+**Acceptance Scenarios**:
+
+1. **Given** a project with a missing required parameter, **When** `cs doctor --fix --dry-run`
+   runs, **Then** the output lists the `parameters-regen` planned action and the project file is
+   not modified.
+2. **Given** `--dry-run` without `--fix`, **When** the command runs, **Then** an error is printed
+   and the command exits with code 1.
+3. **Given** no fixable findings, **When** `cs doctor --fix --dry-run` runs, **Then** output
+   reports "no auto-fixable findings" and exits with code 0.
+
+---
+
+### User Story 2 — CI "fix needed" detection (P2)
+
+A CI pipeline runs `cs doctor --fix --dry-run` and fails the build when doctor would make
+changes, forcing the developer to run `cs doctor --fix` locally before merging.
+
+**Acceptance Scenarios**:
+
+1. **Given** auto-fixable findings exist, **When** `cs doctor --fix --dry-run` runs in CI,
+   **Then** exit code is `1`.
+2. **Given** all checks pass, **When** `cs doctor --fix --dry-run` runs in CI, **Then** exit
+   code is `0`.
+
+---
+
+### Edge Cases
+
+- Manual-only findings with no auto-fixable ones: still exit `1` (there are problems), still
+  show the manual section, show "0 auto-fixable actions".
+- All findings are manual-only: dry-run output should clarify that `--fix` would not resolve
+  them automatically.
+- `--dry-run` used with `--format json`: produce JSON with the `dryRun` structure above.
+
+## Requirements
+
+### Functional Requirements
+
+- **FR-001**: When `--fix --dry-run` is specified, `cs doctor` MUST NOT write any files.
+- **FR-002**: The dry-run output MUST list every auto-fixable finding with its `remediationKey`
+  and `plannedChanges`.
+- **FR-003**: The dry-run output MUST list manual-only findings separately.
+- **FR-004**: `cs doctor --fix --dry-run` MUST exit with code `1` when any findings exist (auto-
+  fixable or manual).
+- **FR-005**: `cs doctor --fix --dry-run` MUST exit with code `0` when all checks pass.
+- **FR-006**: `--dry-run` without `--fix` MUST print an error message and exit with code `1`.
+- **FR-007**: `--fix --dry-run` with `--format json` MUST include a `dryRun: true` key and
+  `plannedActions` array in the JSON output.
+
+## Dependencies & Impact
+
+- **Affected Areas**: `tool/commands/doctor.ts`, `tool/__tests__/commands.test.ts`, `CHANGELOG.md`
+- **Compatibility Impact**: None — `--dry-run` is a new flag; no existing behaviour changes.
+- **Required Documentation Updates**: `CHANGELOG.md`; update `cs doctor --help` output implicitly
+  via Commander option declaration.
+- **Verification Plan**: Unit tests verifying no writes occur; exit code assertions.
+
+## Success Criteria
+
+### Measurable Outcomes
+
+- **SC-001**: `cs doctor --fix --dry-run` on a project with fixable findings produces output
+  listing all planned actions and exits with code 1.
+- **SC-002**: No files in the project directory or output directory are modified when `--dry-run`
+  is active.
+- **SC-003**: `npm test` passes with at least 4 new test cases: dry-run output, no-write
+  guarantee, exit codes, invalid flag combination.
+- **SC-004**: No existing doctor tests regress.
+
+## Open Questions
+
+| #   | Question                                                                                 | Owner | Resolution                                                                                |
+| --- | ---------------------------------------------------------------------------------------- | ----- | ----------------------------------------------------------------------------------------- |
+| 1   | Should `--dry-run` show a file-level diff of generated output (e.g. what regen would add | PM    | Pending — defer; full diff requires dry compose which is expensive. Leave for a follow-up |
+|     | to devcontainer.json)?                                                                   |       |                                                                                           |
+| 2   | Should `--dry-run` without `--fix` be silently ignored instead of an error?              | PM    | Pending — lean toward error: the combination is meaningless and should be caught early    |
+
+## Out of Scope
+
+- File-content diffing (showing before/after for generated files).
+- Partial dry-run (dry-running only some fix actions).
+- Storing the dry-run plan to a file for later application.
+
+## Implementation Notes
+
+- `executeFixRun` gains a `dryRun: boolean` parameter (default `false`); when true it skips all `executeSingleFix` calls and returns the planned actions without writing anything.
+- The `RemediationPlan` interface is defined in `doctor.ts` with fields `findingName`, `remediationKey`, `plannedChanges`, and `safetyClass`.
+- The dry-run branch in `doctorCommand` runs before the normal fix branch; `--dry-run` without `--fix` exits immediately with code 1 and an error message.
+- Exit code for dry-run with any findings (auto-fixable or manual) is `1`; exit code `0` only when all checks pass.

package/docs/specs/{007-init-project-file → 018-init-project-file}/spec.md

@@ -1,17 +1,10 @@
 # Feature Specification: `init --project-file`
 
-**Feature Branch**: `copilot/sub-pr-121`
+**Spec ID**: `018-init-project-file`
 **Created**: 2026-03-23
 **Status**: Final
 **Input**: Extend the `init` command with a `--project-file` flag that persists the chosen init configuration into a repository-root project config file (creating `.superposition.yml` by default or updating an existing supported project config), aligning init runs with the project-config workflow.
 
-## Review & Approval _(mandatory before implementation)_
-
-- **Spec Path**: `docs/specs/007-init-project-file/spec.md`
-- **Commit Status**: Committed
-- **Review Status**: Approved
-- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
-
 ## Summary
 
 Allow `container-superposition init` to optionally write a repository-root
@@ -34,7 +27,7 @@ project config path when one already exists) alongside the normal init output.
   current `init` runs do.
 - Project config write errors MUST NOT suppress devcontainer generation success; they MUST be reported separately.
 
-## User Scenarios & Testing _(mandatory)_
+## User Scenarios & Testing
 
 ### User Story 1 - Write project config alongside devcontainer generation (Priority: P1)