container-superposition 0.1.7 → 0.1.9

package/dist/tool/commands/doctor.js

@@ -2,17 +2,23 @@
  * Doctor command - Environment validation and diagnostics
  */
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import * as net from 'net';
 import { execSync } from 'child_process';
 import chalk from 'chalk';
 import boxen from 'boxen';
+import * as yaml from 'js-yaml';
 import { loadOverlayManifest } from '../schema/overlay-loader.js';
 import { detectManifestVersion, isVersionSupported, needsMigration, migrateManifest, CURRENT_MANIFEST_VERSION, } from '../schema/manifest-migrations.js';
 import { MERGE_STRATEGY } from '../utils/merge.js';
 import { extractPorts } from '../utils/port-utils.js';
 import { composeDevContainer } from '../questionnaire/composer.js';
-import { loadProjectConfig } from '../schema/project-config.js';
+import { mergeAnswers } from '../questionnaire/answers.js';
+import { loadProjectConfig, buildAnswersFromProjectConfig, writeProjectConfig, } from '../schema/project-config.js';
+import { collectOverlayParameters, resolveParameters, findUnresolvedTokens, } from '../utils/parameters.js';
+import { applyPresetSelections } from '../questionnaire/presets.js';
+import { PRESETS_DIR } from '../questionnaire/questionnaire.js';
 // ─── Remediation registry ─────────────────────────────────────────────────
 const REMEDIATION_REGISTRY = new Map([
     [
@@ -77,6 +83,71 @@ const REMEDIATION_REGISTRY = new Map([
             ],
         },
     ],
+    [
+        'parameters-regen',
+        {
+            key: 'parameters-regen',
+            findingId: 'missing-required-parameters',
+            safetyClass: 'safe-unattended',
+            executionKind: 'regeneration',
+            preconditions: [
+                'Project file (.superposition.yml) must exist',
+                'All required parameters must have overlay defaults to fall back to',
+            ],
+            plannedChanges: [
+                'Add missing parameters with overlay defaults to project file',
+                'Regenerate devcontainer configuration from updated project file',
+            ],
+            manualFallback: [
+                'Add the missing parameters to the parameters: section in your project file',
+                'Run "cs regen" to regenerate with the updated configuration',
+            ],
+        },
+    ],
+    [
+        'dependency-fix',
+        {
+            key: 'dependency-fix',
+            findingId: 'missing-required-overlay',
+            safetyClass: 'safe-unattended',
+            executionKind: 'regeneration',
+            preconditions: ['Project file (.superposition.yml) must exist'],
+            plannedChanges: [
+                'Add missing required overlay(s) to project file',
+                'Regenerate devcontainer configuration from updated project file',
+            ],
+            manualFallback: [
+                'Add the missing required overlays to the overlays: list in your project file',
+                'Run "cs regen" to regenerate',
+            ],
+        },
+    ],
+    [
+        'env-example-regen',
+        {
+            key: 'env-example-regen',
+            findingId: 'env-example-drift',
+            safetyClass: 'safe-unattended',
+            executionKind: 'regeneration',
+            preconditions: ['Project file (.superposition.yml) must exist'],
+            plannedChanges: ['Regenerate .env.example from current overlay selection'],
+            manualFallback: [
+                'Run "cs regen" to regenerate .env.example from the current overlay selection',
+            ],
+        },
+    ],
+    [
+        'reproducibility-regen',
+        {
+            key: 'reproducibility-regen',
+            findingId: 'reproducibility',
+            safetyClass: 'safe-unattended',
+            executionKind: 'regeneration',
+            preconditions: ['Project file (.superposition.yml) must exist'],
+            plannedChanges: ['Regenerate devcontainer configuration from current project file'],
+            manualFallback: ['Run "cs regen" to regenerate the devcontainer configuration'],
+        },
+    ],
 ]);
 /**
  * Semantic version comparison helper
@@ -418,6 +489,52 @@ function validateOverlayManifest(overlayDir, overlayId) {
             };
         }
     }
+    // Validate compose_imports if present
+    if (manifest.compose_imports && manifest.compose_imports.length > 0) {
+        const overlaysDir = path.dirname(overlayDir);
+        const sharedBase = path.resolve(overlaysDir, '.shared');
+        const missingImports = [];
+        const invalidImports = [];
+        const traversalImports = [];
+        for (const importPath of manifest.compose_imports) {
+            if (!importPath.startsWith('.shared/')) {
+                traversalImports.push(`${importPath} (must begin with '.shared/')`);
+                continue;
+            }
+            const resolved = path.resolve(overlaysDir, importPath);
+            if (!resolved.startsWith(sharedBase + path.sep) && resolved !== sharedBase) {
+                traversalImports.push(`${importPath} (resolves outside '.shared/' directory)`);
+                continue;
+            }
+            const fullImportPath = path.join(overlaysDir, importPath);
+            if (!fs.existsSync(fullImportPath)) {
+                missingImports.push(importPath);
+                continue;
+            }
+            const ext = path.extname(importPath).toLowerCase();
+            if (!['.yaml', '.yml'].includes(ext)) {
+                invalidImports.push(`${importPath} (must be .yml or .yaml for compose_imports)`);
+            }
+        }
+        if (traversalImports.length > 0 || missingImports.length > 0 || invalidImports.length > 0) {
+            const details = [];
+            if (traversalImports.length > 0) {
+                details.push(`Path traversal rejected: ${traversalImports.join(', ')}`);
+            }
+            if (missingImports.length > 0) {
+                details.push(`Missing compose_imports: ${missingImports.join(', ')}`);
+            }
+            if (invalidImports.length > 0) {
+                details.push(`Invalid compose_imports: ${invalidImports.join(', ')}`);
+            }
+            return {
+                name: `Overlay: ${overlayId}`,
+                status: 'warn',
+                message: 'compose_import validation issues',
+                details,
+            };
+        }
+    }
     return {
         name: `Overlay: ${overlayId}`,
         status: 'pass',
@@ -737,95 +854,1090 @@ function checkMergeStrategy(outputPath) {
                     });
                 }
                 else {
-                    results.push({
-                        name: 'Port forwarding merge',
-                        status: 'pass',
-                        message: `${uniquePorts.size} unique ports forwarded`,
-                    });
+                    results.push({
+                        name: 'Port forwarding merge',
+                        status: 'pass',
+                        message: `${uniquePorts.size} unique ports forwarded`,
+                    });
+                }
+            }
+        }
+        catch (error) {
+            results.push({
+                name: 'DevContainer merge validation',
+                status: 'fail',
+                message: 'Unable to validate merge strategy',
+                details: [`Error: ${error instanceof Error ? error.message : String(error)}`],
+            });
+        }
+    }
+    // Check 3: Validate docker-compose.yml if it exists
+    const composePath = path.join(outputPath, 'docker-compose.yml');
+    if (fs.existsSync(composePath)) {
+        try {
+            const content = fs.readFileSync(composePath, 'utf8');
+            // Basic validation: check if it's parseable YAML
+            const yaml = require('js-yaml');
+            const compose = yaml.load(content);
+            if (compose.services) {
+                const serviceNames = Object.keys(compose.services);
+                results.push({
+                    name: 'Compose service merge',
+                    status: 'pass',
+                    message: `${serviceNames.length} services merged successfully`,
+                });
+                // Check depends_on references
+                let hasInvalidDependencies = false;
+                const serviceNameSet = new Set(serviceNames);
+                for (const [serviceName, service] of Object.entries(compose.services)) {
+                    if (service.depends_on) {
+                        const deps = Array.isArray(service.depends_on)
+                            ? service.depends_on
+                            : Object.keys(service.depends_on);
+                        for (const dep of deps) {
+                            if (!serviceNameSet.has(dep)) {
+                                hasInvalidDependencies = true;
+                                break;
+                            }
+                        }
+                    }
+                }
+                if (hasInvalidDependencies) {
+                    results.push({
+                        name: 'Service dependencies',
+                        status: 'warn',
+                        message: 'Invalid service dependencies detected',
+                        details: [
+                            'Some depends_on references point to non-existent services',
+                            'Dependencies should be filtered during merge',
+                        ],
+                    });
+                }
+                else {
+                    results.push({
+                        name: 'Service dependencies',
+                        status: 'pass',
+                        message: 'All service dependencies are valid',
+                    });
+                }
+            }
+        }
+        catch (error) {
+            results.push({
+                name: 'Compose merge validation',
+                status: 'warn',
+                message: 'Unable to validate docker-compose merge',
+                details: [`Error: ${error instanceof Error ? error.message : String(error)}`],
+            });
+        }
+    }
+    return results;
+}
+/**
+ * Check for drift between the project config file and the last generated manifest.
+ * Reports a warning when the overlay lists differ so users know to run `regen`.
+ */
+function checkProjectFileDrift(overlaysConfig, workingDir, manifestPath) {
+    // Load project config — skip silently if not present
+    let projectConfig;
+    try {
+        projectConfig = loadProjectConfig(overlaysConfig, workingDir);
+    }
+    catch {
+        return [];
+    }
+    if (!projectConfig) {
+        return [];
+    }
+    // Load manifest — if not present while the project file exists, report it informatively
+    if (!fs.existsSync(manifestPath)) {
+        return [
+            {
+                name: 'Project file drift',
+                status: 'warn',
+                message: 'Project file found but no generated manifest — run `cs regen` to generate',
+                fixEligibility: 'not-applicable',
+            },
+        ];
+    }
+    let manifest;
+    try {
+        const raw = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        manifest = needsMigration(raw) ? migrateManifest(raw) : raw;
+    }
+    catch {
+        return [];
+    }
+    // Compare overlay sets (order-independent).
+    // Exclude auto-resolved dependencies from the manifest side — the project file only
+    // stores user-selected overlays; auto-resolved ones are re-calculated at generation time.
+    const autoResolvedAdded = new Set(manifest.autoResolved?.added ?? []);
+    const projectOverlays = new Set(projectConfig.selection.overlays ?? []);
+    const manifestBaseOverlays = new Set((manifest.overlays ?? []).filter((o) => !autoResolvedAdded.has(o)));
+    const inProjectNotManifest = [...projectOverlays].filter((o) => !manifestBaseOverlays.has(o));
+    const inManifestNotProject = [...manifestBaseOverlays].filter((o) => !projectOverlays.has(o));
+    if (inProjectNotManifest.length === 0 && inManifestNotProject.length === 0) {
+        return [
+            {
+                name: 'Project file drift',
+                status: 'pass',
+                message: 'Project file and generated manifest are consistent',
+                fixEligibility: 'not-applicable',
+            },
+        ];
+    }
+    const details = [];
+    if (inProjectNotManifest.length > 0) {
+        details.push(`In project file but not in manifest: ${inProjectNotManifest.join(', ')}`);
+    }
+    if (inManifestNotProject.length > 0) {
+        details.push(`In manifest but not in project file: ${inManifestNotProject.join(', ')}`);
+    }
+    details.push('Run "cs regen" to regenerate with the current project file configuration');
+    return [
+        {
+            name: 'Project file drift',
+            status: 'warn',
+            message: 'Project file and generated manifest have diverged',
+            details,
+            fixEligibility: 'manual-only',
+        },
+    ];
+}
+/**
+ * Check overlay parameters: unresolved tokens, secret leakage, missing .env.example,
+ * stale project-file keys, and required parameters not supplied.
+ */
+function checkParameters(overlaysConfig, outputPath, workingDir) {
+    const results = [];
+    // Load the project config — skip silently if none present
+    let projectConfig;
+    try {
+        projectConfig = loadProjectConfig(overlaysConfig, workingDir);
+    }
+    catch {
+        return [];
+    }
+    if (!projectConfig) {
+        return [];
+    }
+    const selectedOverlays = projectConfig.selection.overlays ?? [];
+    const suppliedParams = projectConfig.selection.parameters ?? {};
+    // Collect all parameter declarations for selected overlays
+    const declared = collectOverlayParameters(selectedOverlays, overlaysConfig.overlays);
+    const declaredCount = Object.keys(declared).length;
+    // ── Check 1: Unresolved {{cs.*}} tokens in generated files ────────────────
+    const filesToScan = [
+        ['devcontainer.json', path.join(outputPath, 'devcontainer.json')],
+        ['docker-compose.yml', path.join(outputPath, 'docker-compose.yml')],
+        ['.env.example', path.join(outputPath, '.env.example')],
+    ];
+    const unresolvedByFile = [];
+    for (const [label, filePath] of filesToScan) {
+        if (!fs.existsSync(filePath))
+            continue;
+        const content = fs.readFileSync(filePath, 'utf8');
+        const tokens = findUnresolvedTokens(content);
+        if (tokens.length > 0) {
+            unresolvedByFile.push(`${label}: ${[...new Set(tokens)].join(', ')}`);
+        }
+    }
+    if (unresolvedByFile.length > 0) {
+        results.push({
+            name: 'Unresolved parameter tokens',
+            status: 'fail',
+            message: `Unsubstituted {{cs.*}} tokens found in generated files`,
+            details: [
+                ...unresolvedByFile,
+                'Run "cs regen" or add the missing parameters to your project file',
+            ],
+            fixEligibility: 'automatic',
+            remediationKey: 'parameters-regen',
+            fixable: true,
+        });
+    }
+    // ── Check 2: Sensitive params hardcoded in devcontainer.json remoteEnv ───
+    const devcontainerPath = path.join(outputPath, 'devcontainer.json');
+    if (fs.existsSync(devcontainerPath)) {
+        try {
+            const devcontainer = JSON.parse(fs.readFileSync(devcontainerPath, 'utf8'));
+            const remoteEnv = devcontainer.remoteEnv ?? {};
+            const leakedSecrets = [];
+            for (const [key, value] of Object.entries(remoteEnv)) {
+                if (declared[key]?.sensitive && value !== '' && !value.startsWith('${')) {
+                    leakedSecrets.push(key);
+                }
+            }
+            if (leakedSecrets.length > 0) {
+                results.push({
+                    name: 'Sensitive parameters in devcontainer',
+                    status: 'warn',
+                    message: `Secret parameter(s) appear as plain text in devcontainer.json remoteEnv: ${leakedSecrets.join(', ')}`,
+                    details: [
+                        'Sensitive values should be stored in .env and referenced as ${VAR:-default}',
+                        'Run "cs regen" to regenerate with proper secret handling',
+                    ],
+                    fixEligibility: 'automatic',
+                    remediationKey: 'parameters-regen',
+                    fixable: true,
+                });
+            }
+        }
+        catch {
+            // devcontainer.json parse errors are caught by checkManifest — skip here
+        }
+    }
+    // ── Check 3: Missing .env.example for compose stacks with parameters ─────
+    const manifest = (() => {
+        const mPath = path.join(outputPath, 'superposition.json');
+        if (!fs.existsSync(mPath))
+            return null;
+        try {
+            return JSON.parse(fs.readFileSync(mPath, 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    })();
+    const isCompose = manifest?.baseTemplate === 'compose';
+    if (isCompose && declaredCount > 0) {
+        const envExamplePath = path.join(outputPath, '.env.example');
+        if (!fs.existsSync(envExamplePath)) {
+            results.push({
+                name: 'Missing .env.example',
+                status: 'warn',
+                message: `Compose stack with ${declaredCount} parameter(s) has no .env.example`,
+                details: ['Run "cs regen" to generate the .env.example file'],
+                fixEligibility: 'automatic',
+                remediationKey: 'parameters-regen',
+                fixable: true,
+            });
+        }
+    }
+    // ── Check 4: Unknown parameters in project file ───────────────────────────
+    const unknownKeys = Object.keys(suppliedParams).filter((k) => !(k in declared));
+    if (unknownKeys.length > 0) {
+        results.push({
+            name: 'Unknown parameters in project file',
+            status: 'warn',
+            message: `parameters: contains ${unknownKeys.length} key(s) not declared by any selected overlay: ${unknownKeys.join(', ')}`,
+            details: [
+                'These may be stale entries from a removed overlay',
+                'Remove them from the parameters: section in your project file',
+            ],
+            fixEligibility: 'manual-only',
+        });
+    }
+    // ── Check 5: Required parameters missing from project file ───────────────
+    const { missingRequired } = resolveParameters(declared, suppliedParams);
+    if (missingRequired.length > 0) {
+        const declaringOverlays = missingRequired
+            .map((k) => `${k} (${declared[k]?.overlayId ?? 'unknown'})`)
+            .join(', ');
+        results.push({
+            name: 'Missing required parameters',
+            status: 'fail',
+            message: `${missingRequired.length} required parameter(s) have no value and no default: ${declaringOverlays}`,
+            details: [
+                'Add these to the parameters: section in your project file',
+                'Run "cs regen" (or doctor --fix) to apply defaults and regenerate',
+            ],
+            fixEligibility: 'automatic',
+            remediationKey: 'parameters-regen',
+            fixable: true,
+        });
+    }
+    // ── Pass: all parameters resolved ────────────────────────────────────────
+    if (results.length === 0 && declaredCount > 0) {
+        const { values } = resolveParameters(declared, suppliedParams);
+        const resolvedCount = Object.keys(values).length;
+        results.push({
+            name: 'Parameter resolution',
+            status: 'pass',
+            message: `${resolvedCount} parameter(s) resolved for ${selectedOverlays.length} overlay(s)`,
+            fixEligibility: 'not-applicable',
+        });
+    }
+    return results;
+}
+/**
+ * Check overlay dependency consistency: missing required overlays, unknown overlay IDs,
+ * and unsatisfied suggestions.
+ */
+function checkDependencies(overlaysConfig, workingDir) {
+    const overlayMap = new Map(overlaysConfig.overlays.map((o) => [o.id, o]));
+    // Read raw overlay list from YAML — loadProjectConfig throws for unknown IDs
+    let rawSelectedOverlays = [];
+    try {
+        const projectConfig = loadProjectConfig(overlaysConfig, workingDir);
+        if (!projectConfig)
+            return [];
+        rawSelectedOverlays = (projectConfig.selection.overlays ?? []);
+    }
+    catch {
+        for (const fileName of ['.superposition.yml', 'superposition.yml']) {
+            const filePath = path.join(workingDir, fileName);
+            if (!fs.existsSync(filePath))
+                continue;
+            try {
+                const raw = yaml.load(fs.readFileSync(filePath, 'utf8'));
+                if (Array.isArray(raw?.overlays)) {
+                    rawSelectedOverlays = raw.overlays
+                        .filter((v) => typeof v === 'string')
+                        .map((v) => v);
+                }
+                break;
+            }
+            catch {
+                return [];
+            }
+        }
+        if (rawSelectedOverlays.length === 0)
+            return [];
+    }
+    if (rawSelectedOverlays.length === 0) {
+        return [
+            {
+                name: 'Overlay dependencies',
+                status: 'pass',
+                message: 'No overlays selected',
+                fixEligibility: 'not-applicable',
+            },
+        ];
+    }
+    // The set of overlays explicitly listed in the project file (for requires check)
+    const projectFileSet = new Set(rawSelectedOverlays);
+    const results = [];
+    for (const id of rawSelectedOverlays) {
+        // Unknown overlay
+        if (!overlayMap.has(id)) {
+            results.push({
+                name: `Unknown overlay: ${id}`,
+                status: 'fail',
+                message: `Overlay "${id}" not found in registry — it may have been removed or misspelled`,
+                details: [`Edit .superposition.yml to correct the overlay ID`],
+                fixEligibility: 'manual-only',
+            });
+            continue;
+        }
+        const def = overlayMap.get(id);
+        // Missing required overlays — compare against project file, not auto-resolved set
+        for (const req of def.requires ?? []) {
+            if (!projectFileSet.has(req)) {
+                results.push({
+                    name: `Missing required overlay: ${req}`,
+                    status: 'fail',
+                    message: `Overlay "${id}" requires "${req}" which is not in your project file`,
+                    details: [
+                        `Add "${req}" to the overlays: list in .superposition.yml`,
+                        'Fixable with --fix flag',
+                    ],
+                    fixEligibility: 'automatic',
+                    remediationKey: 'dependency-fix',
+                    fixable: true,
+                });
+            }
+        }
+        // Suggested overlays — compare against project file
+        for (const sug of def.suggests ?? []) {
+            if (!projectFileSet.has(sug)) {
+                results.push({
+                    name: `Suggested overlay: ${sug}`,
+                    status: 'warn',
+                    message: `Overlay "${id}" suggests "${sug}" — consider adding it`,
+                    details: [
+                        `Add "${sug}" to the overlays: list in .superposition.yml for better functionality`,
+                    ],
+                    fixEligibility: 'not-applicable',
+                });
+            }
+        }
+    }
+    if (results.length === 0) {
+        results.push({
+            name: 'Overlay dependencies',
+            status: 'pass',
+            message: `${rawSelectedOverlays.length} overlay(s) selected; all dependencies satisfied`,
+            fixEligibility: 'not-applicable',
+        });
+    }
+    return results;
+}
+/**
+ * Execute the dependency-fix remediation: add missing required overlays then regenerate.
+ */
+async function executeDependencyFix(outputPath, overlaysConfig, overlaysDir, workingDir, silent = false) {
+    let projectConfig;
+    try {
+        projectConfig = loadProjectConfig(overlaysConfig, workingDir);
+    }
+    catch (err) {
+        return {
+            findingId: 'missing-required-overlay',
+            remediationKey: 'dependency-fix',
+            attempted: false,
+            outcome: 'requires-manual-action',
+            reason: `Failed to load project file: ${err instanceof Error ? err.message : String(err)}`,
+            rechecked: false,
+        };
+    }
+    if (!projectConfig) {
+        return {
+            findingId: 'missing-required-overlay',
+            remediationKey: 'dependency-fix',
+            attempted: false,
+            outcome: 'requires-manual-action',
+            reason: 'No project file (.superposition.yml) found',
+            rechecked: false,
+        };
+    }
+    const selectedOverlays = [...(projectConfig.selection.overlays ?? [])];
+    const overlayMap = new Map(overlaysConfig.overlays.map((o) => [o.id, o]));
+    // Collect missing required overlays
+    const toAdd = [];
+    const toProcess = [...selectedOverlays];
+    const processed = new Set();
+    const current = new Set(selectedOverlays);
+    while (toProcess.length > 0) {
+        const id = toProcess.shift();
+        if (processed.has(id))
+            continue;
+        processed.add(id);
+        const def = overlayMap.get(id);
+        if (!def?.requires)
+            continue;
+        for (const req of def.requires) {
+            if (!current.has(req)) {
+                current.add(req);
+                toAdd.push(req);
+                toProcess.push(req);
+            }
+        }
+    }
+    if (toAdd.length === 0) {
+        return {
+            findingId: 'missing-required-overlay',
+            remediationKey: 'dependency-fix',
+            attempted: false,
+            outcome: 'already-compliant',
+            reason: 'All required overlays are already present',
+            rechecked: false,
+        };
+    }
+    const updatedSelection = {
+        ...projectConfig.selection,
+        overlays: [...selectedOverlays, ...toAdd],
+    };
+    try {
+        writeProjectConfig(projectConfig.file.path, updatedSelection);
+    }
+    catch (err) {
+        return {
+            findingId: 'missing-required-overlay',
+            remediationKey: 'dependency-fix',
+            attempted: true,
+            outcome: 'requires-manual-action',
+            reason: `Failed to write project file: ${err instanceof Error ? err.message : String(err)}`,
+            rechecked: false,
+        };
+    }
+    let answers;
+    try {
+        const reloadedConfig = loadProjectConfig(overlaysConfig, workingDir);
+        if (!reloadedConfig)
+            throw new Error('Project file not found after write');
+        const baseAnswers = buildAnswersFromProjectConfig(reloadedConfig.selection, overlaysConfig);
+        const withPreset = await applyPresetSelections(baseAnswers, overlaysConfig, PRESETS_DIR);
+        answers = mergeAnswers(withPreset, { outputPath });
+    }
+    catch (err) {
+        return {
+            findingId: 'missing-required-overlay',
+            remediationKey: 'dependency-fix',
+            attempted: true,
+            outcome: 'requires-manual-action',
+            reason: `Failed to build answers for regeneration: ${err instanceof Error ? err.message : String(err)}`,
+            rechecked: false,
+        };
+    }
+    const originalLog = console.log;
+    if (silent)
+        console.log = () => { };
+    try {
+        await composeDevContainer(answers, overlaysDir, { isRegen: true });
+    }
+    catch (err) {
+        if (silent)
+            console.log = originalLog;
+        return {
+            findingId: 'missing-required-overlay',
+            remediationKey: 'dependency-fix',
+            attempted: true,
+            outcome: 'requires-manual-action',
+            reason: `Regeneration failed: ${err instanceof Error ? err.message : String(err)}`,
+            rechecked: false,
+        };
+    }
+    finally {
+        if (silent)
+            console.log = originalLog;
+    }
+    return {
+        findingId: 'missing-required-overlay',
+        remediationKey: 'dependency-fix',
+        attempted: true,
+        outcome: 'fixed',
+        reason: `Added missing required overlay(s): ${toAdd.join(', ')} and regenerated devcontainer`,
+        changedFiles: [projectConfig.file.path],
+        rechecked: true,
+    };
+}
+/**
+ * Normalise a ports: or forwardPorts: entry to the integer container-side port.
+ * Returns null for unparseable entries.
+ */
+function parseContainerPort(entry) {
+    if (typeof entry === 'number')
+        return entry > 0 ? entry : null;
+    if (typeof entry === 'object' && entry !== null) {
+        return typeof entry.target === 'number' && entry.target > 0 ? entry.target : null;
+    }
+    if (typeof entry !== 'string')
+        return null;
+    // Strip protocol suffix: "5432/tcp" → "5432"
+    const withoutProto = entry.replace(/\/[a-z]+$/i, '');
+    // Handle "host:container" and "ip:host:container" forms
+    const parts = withoutProto.split(':');
+    const portStr = parts[parts.length - 1] ?? '';
+    const port = parseInt(portStr, 10);
+    return Number.isFinite(port) && port > 0 ? port : null;
+}
+/**
+ * Cross-validate forwardPorts in devcontainer.json against ports exposed by compose services.
+ */
+function checkPortCrossValidation(outputPath) {
+    const composePath = path.join(outputPath, 'docker-compose.yml');
+    if (!fs.existsSync(composePath)) {
+        return [
+            {
+                name: 'Port cross-validation',
+                status: 'pass',
+                message: 'No compose stack — port cross-validation skipped',
+                fixEligibility: 'not-applicable',
+            },
+        ];
+    }
+    // Parse devcontainer.json forwardPorts
+    const devcontainerPath = path.join(outputPath, 'devcontainer.json');
+    let forwardedPorts = new Set();
+    if (fs.existsSync(devcontainerPath)) {
+        try {
+            const dc = JSON.parse(fs.readFileSync(devcontainerPath, 'utf8'));
+            for (const entry of dc.forwardPorts ?? []) {
+                const port = parseContainerPort(entry);
+                if (port !== null)
+                    forwardedPorts.add(port);
+            }
+        }
+        catch {
+            // parse errors handled by checkManifest
+        }
+    }
+    // Parse docker-compose.yml ports and expose blocks
+    let boundPorts = new Set();
+    let exposedPorts = new Set();
+    try {
+        const raw = fs.readFileSync(composePath, 'utf8');
+        const doc = yaml.load(raw);
+        const services = doc?.services ?? {};
+        for (const svc of Object.values(services)) {
+            const service = svc;
+            for (const entry of service.ports ?? []) {
+                const port = parseContainerPort(entry);
+                if (port !== null)
+                    boundPorts.add(port);
+            }
+            for (const entry of service.expose ?? []) {
+                const port = parseContainerPort(entry);
+                if (port !== null)
+                    exposedPorts.add(port);
+            }
+        }
+    }
+    catch {
+        return [
+            {
+                name: 'Port cross-validation',
+                status: 'fail',
+                message: 'Could not parse docker-compose.yml for port cross-validation — file may be malformed',
+                fixEligibility: 'manual-only',
+            },
+        ];
+    }
+    const allComposePorts = new Set([...boundPorts, ...exposedPorts]);
+    const results = [];
+    // forwardPorts entries with no backing compose service
+    for (const port of forwardedPorts) {
+        if (!allComposePorts.has(port)) {
+            results.push({
+                name: `Port ${port} not exposed by any service`,
+                status: 'fail',
+                message: `Port ${port} is listed in forwardPorts but is not exposed by any compose service`,
+                details: [`Remove port ${port} from forwardPorts or add it to a compose service`],
+                fixEligibility: 'manual-only',
+            });
+        }
+    }
+    // Bound compose ports not in forwardPorts
+    for (const port of boundPorts) {
+        if (!forwardedPorts.has(port)) {
+            results.push({
+                name: `Port ${port} not forwarded`,
+                status: 'warn',
+                message: `Port ${port} is bound by a compose service but is not in forwardPorts — it may be inaccessible from the host`,
+                details: [
+                    `Add ${port} to forwardPorts in your overlay's devcontainer.patch.json, then run cs regen`,
+                ],
+                fixEligibility: 'manual-only',
+            });
+        }
+    }
+    if (results.length === 0) {
+        results.push({
+            name: 'Port cross-validation',
+            status: 'pass',
+            message: `${forwardedPorts.size} forwarded port(s) all match compose service declarations`,
+            fixEligibility: 'not-applicable',
+        });
+    }
+    return results;
+}
+/**
+ * Check whether .env.example is in sync with the current overlay parameter declarations.
+ */
+function checkEnvExampleDrift(overlaysConfig, outputPath, workingDir) {
+    let projectConfig;
+    try {
+        projectConfig = loadProjectConfig(overlaysConfig, workingDir);
+    }
+    catch {
+        return [];
+    }
+    if (!projectConfig)
+        return [];
+    const envExamplePath = path.join(outputPath, '.env.example');
+    if (!fs.existsSync(envExamplePath)) {
+        return [
+            {
+                name: '.env.example drift',
+                status: 'pass',
+                message: 'No .env.example present — skipping drift check',
+                fixEligibility: 'not-applicable',
+            },
+        ];
+    }
+    const selectedOverlays = projectConfig.selection.overlays ?? [];
+    const declared = collectOverlayParameters(selectedOverlays, overlaysConfig.overlays);
+    const declaredKeys = new Set(Object.keys(declared));
+    // Parse .env.example keys (skip comments and blanks)
+    const envContent = fs.readFileSync(envExamplePath, 'utf8');
+    const exampleKeys = new Set();
+    for (const line of envContent.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const key = trimmed.split('=')[0]?.trim();
+        if (key)
+            exampleKeys.add(key);
+    }
+    const results = [];
+    // Keys declared by overlays but missing from .env.example
+    for (const [key, decl] of Object.entries(declared)) {
+        if (!exampleKeys.has(key)) {
+            results.push({
+                name: `Missing .env.example key: ${key}`,
+                status: 'fail',
+                message: `Parameter "${key}" declared by overlay "${decl.overlayId}" is missing from .env.example`,
+                details: [
+                    'Run cs regen or use --fix to regenerate .env.example',
+                    'Fixable with --fix flag',
+                ],
+                fixEligibility: 'automatic',
+                remediationKey: 'env-example-regen',
+                fixable: true,
+            });
+        }
+    }
+    // Keys in .env.example not declared by any overlay
+    for (const key of exampleKeys) {
+        if (!declaredKeys.has(key)) {
+            results.push({
+                name: `Stale .env.example key: ${key}`,
+                status: 'warn',
+                message: `Key "${key}" in .env.example is not declared by any selected overlay — it may be stale`,
+                details: [
+                    `Remove "${key}" from .env.example or run --fix to regenerate`,
+                    'Fixable with --fix flag',
+                ],
+                fixEligibility: 'automatic',
+                remediationKey: 'env-example-regen',
+                fixable: true,
+            });
+        }
+    }
+    if (results.length === 0) {
+        results.push({
+            name: '.env.example drift',
+            status: 'pass',
+            message: `.env.example is in sync with ${declaredKeys.size} declared parameter(s)`,
+            fixEligibility: 'not-applicable',
+        });
+    }
+    return results;
+}
+/**
+ * Execute the env-example-regen remediation: full regen which regenerates .env.example.
+ */
+async function executeEnvExampleRegen(outputPath, overlaysConfig, overlaysDir, workingDir, silent = false) {
+    let projectConfig;
+    try {
+        projectConfig = loadProjectConfig(overlaysConfig, workingDir);
+    }
+    catch (err) {
+        return {
+            findingId: 'env-example-drift',
+            remediationKey: 'env-example-regen',
+            attempted: false,
+            outcome: 'requires-manual-action',
+            reason: `Failed to load project file: ${err instanceof Error ? err.message : String(err)}`,
+            rechecked: false,
+        };
+    }
+    if (!projectConfig) {
+        return {
+            findingId: 'env-example-drift',
+            remediationKey: 'env-example-regen',
+            attempted: false,
+            outcome: 'requires-manual-action',
+            reason: 'No project file (.superposition.yml) found',
+            rechecked: false,
+        };
+    }
+    let answers;
+    try {
+        const baseAnswers = buildAnswersFromProjectConfig(projectConfig.selection, overlaysConfig);
+        const withPreset = await applyPresetSelections(baseAnswers, overlaysConfig, PRESETS_DIR);
+        answers = mergeAnswers(withPreset, { outputPath });
+    }
+    catch (err) {
+        return {
+            findingId: 'env-example-drift',
+            remediationKey: 'env-example-regen',
+            attempted: true,
+            outcome: 'requires-manual-action',
+            reason: `Failed to build answers: ${err instanceof Error ? err.message : String(err)}`,
+            rechecked: false,
+        };
+    }
+    const originalLog = console.log;
+    if (silent)
+        console.log = () => { };
+    try {
+        await composeDevContainer(answers, overlaysDir, { isRegen: true });
+    }
+    catch (err) {
+        if (silent)
+            console.log = originalLog;
+        return {
+            findingId: 'env-example-drift',
+            remediationKey: 'env-example-regen',
+            attempted: true,
+            outcome: 'requires-manual-action',
+            reason: `Regeneration failed: ${err instanceof Error ? err.message : String(err)}`,
+            rechecked: false,
+        };
+    }
+    finally {
+        if (silent)
+            console.log = originalLog;
+    }
+    return {
+        findingId: 'env-example-drift',
+        remediationKey: 'env-example-regen',
+        attempted: true,
+        outcome: 'fixed',
+        reason: 'Regenerated .env.example from current overlay selection',
+        changedFiles: [path.join(outputPath, '.env.example')],
+        rechecked: true,
+    };
+}
+/**
+ * Dry-compose the devcontainer to a temp directory and compare files against the output directory.
+ */
+async function checkReproducibility(overlaysConfig, outputPath, overlaysDir, workingDir) {
+    let projectConfig;
+    try {
+        projectConfig = loadProjectConfig(overlaysConfig, workingDir);
+    }
+    catch {
+        return [];
+    }
+    if (!projectConfig)
+        return [];
+    // Skip when output directory or devcontainer.json are absent — regen hasn't run yet,
+    // or the environment check surfaces the missing dir already.
+    if (!fs.existsSync(outputPath) || !fs.existsSync(path.join(outputPath, 'devcontainer.json'))) {
+        return [];
+    }
+    let tmpDir;
+    try {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cs-doctor-repro-'));
+        let answers;
+        try {
+            const baseAnswers = buildAnswersFromProjectConfig(projectConfig.selection, overlaysConfig);
+            const withPreset = await applyPresetSelections(baseAnswers, overlaysConfig, PRESETS_DIR);
+            answers = mergeAnswers(withPreset, { outputPath: tmpDir });
+        }
+        catch (err) {
+            return [
+                {
+                    name: 'Reproducibility',
+                    status: 'fail',
+                    message: `Failed to build answers for dry compose: ${err instanceof Error ? err.message : String(err)}`,
+                    fixEligibility: 'manual-only',
+                },
+            ];
+        }
+        const originalLog = console.log;
+        console.log = () => { };
+        try {
+            // Copy the existing custom/ directory to tmpDir so applyCustomPatches()
+            // inside composeDevContainer applies the same user patches that produced
+            // the current outputPath — without this, the dry-compose output would
+            // always differ whenever .devcontainer/custom/ contains any overrides.
+            const srcCustom = path.join(outputPath, 'custom');
+            if (fs.existsSync(srcCustom)) {
+                const destCustom = path.join(tmpDir, 'custom');
+                fs.cpSync(srcCustom, destCustom, { recursive: true });
+            }
+            await composeDevContainer(answers, overlaysDir, { isRegen: false });
+        }
+        catch (err) {
+            return [
+                {
+                    name: 'Reproducibility',
+                    status: 'fail',
+                    message: `Dry compose failed: ${err instanceof Error ? err.message : String(err)}`,
+                    fixEligibility: 'automatic',
+                    remediationKey: 'reproducibility-regen',
+                    fixable: true,
+                },
+            ];
+        }
+        finally {
+            console.log = originalLog;
+        }
+        const GENERATION_HEADERS = [
+            '# Generated by container-superposition',
+            '// Generated by container-superposition',
+        ];
+        function isGeneratedFile(filePath) {
+            try {
+                const firstLine = fs.readFileSync(filePath, 'utf8').split('\n')[0] ?? '';
+                return GENERATION_HEADERS.some((h) => firstLine.startsWith(h));
+            }
+            catch {
+                return false;
+            }
+        }
+        function listFiles(dir) {
+            const result = [];
+            if (!fs.existsSync(dir))
+                return result;
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                const full = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    result.push(...listFiles(full).map((f) => path.join(entry.name, f)));
+                }
+                else {
+                    result.push(entry.name);
                 }
             }
-        }
-        catch (error) {
-            results.push({
-                name: 'DevContainer merge validation',
-                status: 'fail',
-                message: 'Unable to validate merge strategy',
-                details: [`Error: ${error instanceof Error ? error.message : String(error)}`],
-            });
-        }
-    }
-    // Check 3: Validate docker-compose.yml if it exists
-    const composePath = path.join(outputPath, 'docker-compose.yml');
-    if (fs.existsSync(composePath)) {
-        try {
-            const content = fs.readFileSync(composePath, 'utf8');
-            // Basic validation: check if it's parseable YAML
-            const yaml = require('js-yaml');
-            const compose = yaml.load(content);
-            if (compose.services) {
-                const serviceNames = Object.keys(compose.services);
-                results.push({
-                    name: 'Compose service merge',
-                    status: 'pass',
-                    message: `${serviceNames.length} services merged successfully`,
-                });
-                // Check depends_on references
-                let hasInvalidDependencies = false;
-                const serviceNameSet = new Set(serviceNames);
-                for (const [serviceName, service] of Object.entries(compose.services)) {
-                    if (service.depends_on) {
-                        const deps = Array.isArray(service.depends_on)
-                            ? service.depends_on
-                            : Object.keys(service.depends_on);
-                        for (const dep of deps) {
-                            if (!serviceNameSet.has(dep)) {
-                                hasInvalidDependencies = true;
-                                break;
-                            }
-                        }
+            return result;
+        }
+        function normalise(content, rel) {
+            const normalised = content.replace(/\r\n/g, '\n');
+            if (rel === 'superposition.json') {
+                // Parse the manifest as JSON and strip the fields that legitimately
+                // differ between runs (wall-clock timestamp, output-path-dependent
+                // location) before re-serialising for a structural comparison.
+                try {
+                    const obj = JSON.parse(normalised);
+                    delete obj['generated'];
+                    if (obj['customizations'] && typeof obj['customizations'] === 'object') {
+                        delete obj['customizations']['location'];
                     }
+                    return JSON.stringify(obj, null, 4);
                 }
-                if (hasInvalidDependencies) {
-                    results.push({
-                        name: 'Service dependencies',
-                        status: 'warn',
-                        message: 'Invalid service dependencies detected',
-                        details: [
-                            'Some depends_on references point to non-existent services',
-                            'Dependencies should be filtered during merge',
-                        ],
-                    });
-                }
-                else {
-                    results.push({
-                        name: 'Service dependencies',
-                        status: 'pass',
-                        message: 'All service dependencies are valid',
-                    });
+                catch {
+                    // Unparseable JSON — fall through to character comparison
                 }
             }
+            return normalised;
+        }
+        const tmpFiles = new Set(listFiles(tmpDir));
+        const results = [];
+        // Files produced by regen but absent or different in outputPath
+        for (const rel of tmpFiles) {
+            const actual = path.join(outputPath, rel);
+            const expected = path.join(tmpDir, rel);
+            if (!fs.existsSync(actual)) {
+                results.push({
+                    name: `Missing generated file: ${rel}`,
+                    status: 'fail',
+                    message: `File "${rel}" would be created by cs regen but does not exist`,
+                    details: ['Run cs regen or use --fix to synchronise'],
+                    fixEligibility: 'automatic',
+                    remediationKey: 'reproducibility-regen',
+                    fixable: true,
+                });
+            }
+            else if (normalise(fs.readFileSync(actual, 'utf8'), rel) !==
+                normalise(fs.readFileSync(expected, 'utf8'), rel)) {
+                results.push({
+                    name: `Out-of-date generated file: ${rel}`,
+                    status: 'fail',
+                    message: `File "${rel}" differs from what cs regen would produce — it may have been manually edited or is out of date`,
+                    details: ['Run cs regen or use --fix to synchronise'],
+                    fixEligibility: 'automatic',
+                    remediationKey: 'reproducibility-regen',
+                    fixable: true,
+                });
+            }
         }
-        catch (error) {
+        // Generated files in outputPath that regen would not produce (stale)
+        for (const rel of listFiles(outputPath)) {
+            if (tmpFiles.has(rel))
+                continue;
+            const actualPath = path.join(outputPath, rel);
+            if (isGeneratedFile(actualPath)) {
+                results.push({
+                    name: `Stale generated file: ${rel}`,
+                    status: 'warn',
+                    message: `File "${rel}" exists but cs regen would not produce it — it may be stale`,
+                    fixEligibility: 'manual-only',
+                });
+            }
+        }
+        if (results.length === 0) {
             results.push({
-                name: 'Compose merge validation',
-                status: 'warn',
-                message: 'Unable to validate docker-compose merge',
-                details: [`Error: ${error instanceof Error ? error.message : String(error)}`],
+                name: 'Reproducibility',
+                status: 'pass',
+                message: 'Generated output matches current project configuration',
+                fixEligibility: 'not-applicable',
             });
         }
+        return results;
+    }
+    finally {
+        if (tmpDir) {
+            try {
+                fs.rmSync(tmpDir, { recursive: true, force: true });
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
     }
-    return results;
 }
 /**
- * Generate doctor report
+ * Execute the reproducibility-regen remediation: call composeDevContainer with isRegen: true.
  */
-function generateReport(environmentChecks, overlayChecks, manifestChecks, mergeChecks, portChecks) {
+async function executeReproducibilityRegen(outputPath, overlaysConfig, overlaysDir, workingDir, silent = false) {
+    let projectConfig;
+    try {
+        projectConfig = loadProjectConfig(overlaysConfig, workingDir);
+    }
+    catch (err) {
+        return {
+            findingId: 'reproducibility',
+            remediationKey: 'reproducibility-regen',
+            attempted: false,
+            outcome: 'requires-manual-action',
+            reason: `Failed to load project file: ${err instanceof Error ? err.message : String(err)}`,
+            rechecked: false,
+        };
+    }
+    if (!projectConfig) {
+        return {
+            findingId: 'reproducibility',
+            remediationKey: 'reproducibility-regen',
+            attempted: false,
+            outcome: 'requires-manual-action',
+            reason: 'No project file (.superposition.yml) found',
+            rechecked: false,
+        };
+    }
+    let answers;
+    try {
+        const baseAnswers = buildAnswersFromProjectConfig(projectConfig.selection, overlaysConfig);
+        const withPreset = await applyPresetSelections(baseAnswers, overlaysConfig, PRESETS_DIR);
+        answers = mergeAnswers(withPreset, { outputPath });
+    }
+    catch (err) {
+        return {
+            findingId: 'reproducibility',
+            remediationKey: 'reproducibility-regen',
+            attempted: true,
+            outcome: 'requires-manual-action',
+            reason: `Failed to build answers: ${err instanceof Error ? err.message : String(err)}`,
+            rechecked: false,
+        };
+    }
+    const originalLog = console.log;
+    if (silent)
+        console.log = () => { };
+    try {
+        await composeDevContainer(answers, overlaysDir, { isRegen: true });
+    }
+    catch (err) {
+        if (silent)
+            console.log = originalLog;
+        return {
+            findingId: 'reproducibility',
+            remediationKey: 'reproducibility-regen',
+            attempted: true,
+            outcome: 'requires-manual-action',
+            reason: `Regeneration failed: ${err instanceof Error ? err.message : String(err)}`,
+            rechecked: false,
+        };
+    }
+    finally {
+        if (silent)
+            console.log = originalLog;
+    }
+    return {
+        findingId: 'reproducibility',
+        remediationKey: 'reproducibility-regen',
+        attempted: true,
+        outcome: 'fixed',
+        reason: 'Regenerated devcontainer configuration from current project file',
+        rechecked: true,
+    };
+}
+function generateReport(environmentChecks, overlayChecks, manifestChecks, mergeChecks, portChecks, driftChecks = [], parametersChecks = [], dependenciesChecks = [], portCrossValidationChecks = [], envExampleDriftChecks = [], reproducibilityChecks = []) {
     const allChecks = [
         ...environmentChecks,
         ...overlayChecks,
         ...manifestChecks,
         ...mergeChecks,
         ...portChecks,
+        ...driftChecks,
+        ...parametersChecks,
+        ...dependenciesChecks,
+        ...portCrossValidationChecks,
+        ...envExampleDriftChecks,
+        ...reproducibilityChecks,
     ];
     const passed = allChecks.filter((c) => c.status === 'pass').length;
     const warnings = allChecks.filter((c) => c.status === 'warn').length;
@@ -837,6 +1949,12 @@ function generateReport(environmentChecks, overlayChecks, manifestChecks, mergeC
         manifest: manifestChecks,
         merge: mergeChecks,
         ports: portChecks,
+        drift: driftChecks,
+        parameters: parametersChecks,
+        dependencies: dependenciesChecks,
+        portCrossValidation: portCrossValidationChecks,
+        envExampleDrift: envExampleDriftChecks,
+        reproducibility: reproducibilityChecks,
         summary: {
             passed,
             warnings,
@@ -913,6 +2031,79 @@ function formatAsText(report) {
             lines.push(formatCheckResult(check));
         }
     }
+    // Drift section
+    if (report.drift.length > 0) {
+        const failedDrift = report.drift.filter((c) => c.status !== 'pass');
+        if (failedDrift.length > 0) {
+            lines.push(chalk.bold('\nProject File:'));
+            for (const check of failedDrift) {
+                lines.push(formatCheckResult(check));
+            }
+        }
+        else {
+            lines.push(chalk.bold('\nProject File:'));
+            lines.push(`  ${chalk.green('✓')} ${chalk.white('Project file and manifest are consistent')}`);
+        }
+    }
+    // Parameters section
+    if (report.parameters.length > 0) {
+        const failedParams = report.parameters.filter((c) => c.status !== 'pass');
+        if (failedParams.length > 0) {
+            lines.push(chalk.bold('\nParameters:'));
+            for (const check of failedParams) {
+                lines.push(formatCheckResult(check));
+            }
+        }
+        else {
+            lines.push(chalk.bold('\nParameters:'));
+            lines.push(`  ${chalk.green('✓')} ${chalk.white(report.parameters[0]?.message ?? 'All parameters resolved')}`);
+        }
+    }
+    // Dependencies section
+    if (report.dependencies.length > 0) {
+        const nonPass = report.dependencies.filter((c) => c.status !== 'pass');
+        const hasFail = nonPass.some((c) => c.status === 'fail');
+        lines.push(chalk.bold('\nDependencies:'));
+        if (nonPass.length > 0) {
+            for (const check of nonPass) {
+                lines.push(formatCheckResult(check));
+            }
+        }
+        if (!hasFail) {
+            const passCheck = report.dependencies.find((c) => c.status === 'pass');
+            lines.push(`  ${chalk.green('✓')} ${chalk.white(passCheck?.message ?? 'All overlay dependencies satisfied')}`);
+        }
+    }
+    // Port cross-validation section
+    if (report.portCrossValidation.length > 0) {
+        const failed = report.portCrossValidation.filter((c) => c.status !== 'pass');
+        if (failed.length > 0) {
+            lines.push(chalk.bold('\nPort Cross-Validation:'));
+            for (const check of failed) {
+                lines.push(formatCheckResult(check));
+            }
+        }
+    }
+    // .env.example drift section
+    if (report.envExampleDrift.length > 0) {
+        const failed = report.envExampleDrift.filter((c) => c.status !== 'pass');
+        if (failed.length > 0) {
+            lines.push(chalk.bold('\n.env.example Drift:'));
+            for (const check of failed) {
+                lines.push(formatCheckResult(check));
+            }
+        }
+    }
+    // Reproducibility section
+    if (report.reproducibility.length > 0) {
+        const failed = report.reproducibility.filter((c) => c.status !== 'pass');
+        if (failed.length > 0) {
+            lines.push(chalk.bold('\nReproducibility:'));
+            for (const check of failed) {
+                lines.push(formatCheckResult(check));
+            }
+        }
+    }
     // Summary
     lines.push(chalk.bold('\nSummary:'));
     lines.push(`  ${chalk.green('✓')} ${report.summary.passed} passed`);
@@ -960,6 +2151,12 @@ function reportToFindings(report) {
         ...checksToFindings(report.manifest, 'manifest', 'manifest'),
         ...checksToFindings(report.merge, 'merge', 'devcontainer'),
         ...checksToFindings(report.ports, 'ports', 'environment'),
+        ...checksToFindings(report.drift, 'manifest', 'manifest'),
+        ...checksToFindings(report.parameters, 'manifest', 'full'),
+        ...checksToFindings(report.dependencies, 'manifest', 'full'),
+        ...checksToFindings(report.portCrossValidation, 'ports', 'full'),
+        ...checksToFindings(report.envExampleDrift, 'manifest', 'full'),
+        ...checksToFindings(report.reproducibility, 'manifest', 'full'),
     ];
 }
 /**
@@ -969,8 +2166,12 @@ function orderFindingsForRemediation(findings) {
     const PRIORITY = {
         'manifest-migration': 1,
         'devcontainer-regeneration': 2,
-        'node-version-fix': 3,
-        'docker-repair': 4,
+        'dependency-fix': 3,
+        'parameters-regen': 4,
+        'env-example-regen': 5,
+        'reproducibility-regen': 6,
+        'node-version-fix': 7,
+        'docker-repair': 8,
     };
     return [...findings].sort((a, b) => {
         const pa = PRIORITY[a.remediationKey ?? ''] ?? 99;
@@ -1026,6 +2227,7 @@ function buildAnswersFromManifest(manifest, manifestDir, overlaysConfig) {
                 language.push(id);
                 break;
             case 'database':
+            case 'messaging':
                 database.push(id);
                 break;
             case 'observability':
@@ -1202,7 +2404,7 @@ async function executeRegeneration(outputPath, overlaysConfig, overlaysDir, sile
             rechecked: false,
         };
     }
-    const answers = buildAnswersFromManifest(manifest, outputPath, overlaysConfig);
+    const answers = mergeAnswers(buildAnswersFromManifest(manifest, outputPath, overlaysConfig));
     // Suppress console output during regeneration when in JSON mode
     const originalLog = console.log;
     if (silent) {
@@ -1362,15 +2564,163 @@ function executeNodeVersionFix() {
         rechecked: true,
     };
 }
+/**
+ * Execute parameters-regen fix: add missing parameter defaults to the project file
+ * then regenerate the devcontainer.
+ */
+async function executeParametersRegen(outputPath, overlaysConfig, overlaysDir, workingDir, silent = false) {
+    let projectConfig;
+    try {
+        projectConfig = loadProjectConfig(overlaysConfig, workingDir);
+    }
+    catch (err) {
+        return {
+            findingId: 'missing-required-parameters',
+            remediationKey: 'parameters-regen',
+            attempted: false,
+            outcome: 'requires-manual-action',
+            reason: `Failed to load project file: ${err instanceof Error ? err.message : String(err)}`,
+            rechecked: false,
+        };
+    }
+    if (!projectConfig) {
+        return {
+            findingId: 'missing-required-parameters',
+            remediationKey: 'parameters-regen',
+            attempted: false,
+            outcome: 'requires-manual-action',
+            reason: 'No project file (.superposition.yml) found — run "cs init" first',
+            rechecked: false,
+        };
+    }
+    const selectedOverlays = projectConfig.selection.overlays ?? [];
+    const declared = collectOverlayParameters(selectedOverlays, overlaysConfig.overlays);
+    const supplied = { ...(projectConfig.selection.parameters ?? {}) };
+    // Fill in defaults for missing required parameters
+    const { missingRequired } = resolveParameters(declared, supplied);
+    const needsManual = [];
+    for (const key of missingRequired) {
+        const def = declared[key];
+        if (def?.default !== undefined) {
+            supplied[key] = def.default;
+        }
+        else {
+            needsManual.push(key);
+        }
+    }
+    if (needsManual.length > 0) {
+        return {
+            findingId: 'missing-required-parameters',
+            remediationKey: 'parameters-regen',
+            attempted: false,
+            outcome: 'requires-manual-action',
+            reason: `Cannot auto-fix: ${needsManual.join(', ')} have no default value — add them manually to parameters: in your project file`,
+            rechecked: false,
+        };
+    }
+    // Write updated project file with filled-in parameters
+    const updatedSelection = { ...projectConfig.selection, parameters: supplied };
+    const projectFilePath = projectConfig.file.path;
+    try {
+        writeProjectConfig(projectFilePath, updatedSelection);
+    }
+    catch (err) {
+        return {
+            findingId: 'missing-required-parameters',
+            remediationKey: 'parameters-regen',
+            attempted: true,
+            outcome: 'requires-manual-action',
+            reason: `Failed to write project file: ${err instanceof Error ? err.message : String(err)}`,
+            rechecked: false,
+        };
+    }
+    // Rebuild answers from updated project file and regenerate
+    let answers;
+    try {
+        const reloadedConfig = loadProjectConfig(overlaysConfig, workingDir);
+        if (!reloadedConfig)
+            throw new Error('Project file not found after write');
+        const baseAnswers = buildAnswersFromProjectConfig(reloadedConfig.selection, overlaysConfig);
+        const withPreset = await applyPresetSelections(baseAnswers, overlaysConfig, PRESETS_DIR);
+        answers = mergeAnswers(withPreset, { outputPath });
+    }
+    catch (err) {
+        return {
+            findingId: 'missing-required-parameters',
+            remediationKey: 'parameters-regen',
+            attempted: true,
+            outcome: 'requires-manual-action',
+            reason: `Failed to build answers for regeneration: ${err instanceof Error ? err.message : String(err)}`,
+            rechecked: false,
+        };
+    }
+    const originalLog = console.log;
+    if (silent)
+        console.log = () => { };
+    try {
+        await composeDevContainer(answers, overlaysDir, { isRegen: true });
+    }
+    catch (err) {
+        if (silent)
+            console.log = originalLog;
+        return {
+            findingId: 'missing-required-parameters',
+            remediationKey: 'parameters-regen',
+            attempted: true,
+            outcome: 'requires-manual-action',
+            reason: `Regeneration failed: ${err instanceof Error ? err.message : String(err)}`,
+            rechecked: false,
+        };
+    }
+    finally {
+        if (silent)
+            console.log = originalLog;
+    }
+    // Re-check: ensure no unresolved tokens remain
+    const filesToScan = [
+        ['devcontainer.json', path.join(outputPath, 'devcontainer.json')],
+        ['docker-compose.yml', path.join(outputPath, 'docker-compose.yml')],
+        ['.env.example', path.join(outputPath, '.env.example')],
+    ];
+    const stillUnresolved = [];
+    for (const [, filePath] of filesToScan) {
+        if (!fs.existsSync(filePath))
+            continue;
+        const tokens = findUnresolvedTokens(fs.readFileSync(filePath, 'utf8'));
+        stillUnresolved.push(...tokens);
+    }
+    const addedKeys = Object.keys(supplied).filter((k) => !(projectConfig.selection.parameters ?? {})[k]);
+    return {
+        findingId: 'missing-required-parameters',
+        remediationKey: 'parameters-regen',
+        attempted: true,
+        outcome: stillUnresolved.length === 0 ? 'fixed' : 'requires-manual-action',
+        reason: stillUnresolved.length === 0
+            ? addedKeys.length > 0
+                ? `Added defaults for ${addedKeys.join(', ')} and regenerated devcontainer`
+                : 'Regenerated devcontainer from project file'
+            : `Regeneration ran but unresolved tokens remain: ${[...new Set(stillUnresolved)].join(', ')}`,
+        changedFiles: [projectFilePath],
+        rechecked: true,
+    };
+}
 /**
  * Execute a single remediation action and return its execution record.
  */
-async function executeSingleFix(finding, outputPath, overlaysConfig, overlaysDir, silent = false, explicitManifestPath) {
+async function executeSingleFix(finding, outputPath, overlaysConfig, overlaysDir, silent = false, explicitManifestPath, workingDir = process.cwd()) {
     switch (finding.remediationKey) {
         case 'manifest-migration':
             return executeManifestMigration(outputPath, explicitManifestPath);
         case 'devcontainer-regeneration':
             return executeRegeneration(outputPath, overlaysConfig, overlaysDir, silent, explicitManifestPath);
+        case 'parameters-regen':
+            return executeParametersRegen(outputPath, overlaysConfig, overlaysDir, workingDir, silent);
+        case 'dependency-fix':
+            return executeDependencyFix(outputPath, overlaysConfig, overlaysDir, workingDir, silent);
+        case 'env-example-regen':
+            return executeEnvExampleRegen(outputPath, overlaysConfig, overlaysDir, workingDir, silent);
+        case 'reproducibility-regen':
+            return executeReproducibilityRegen(outputPath, overlaysConfig, overlaysDir, workingDir, silent);
         case 'node-version-fix':
             return executeNodeVersionFix();
         case 'docker-repair': {
@@ -1439,7 +2789,7 @@ function determineExitDisposition(summary, finalFindings) {
 /**
  * Run the full fix flow: diagnose → narrate → remediate → re-check → summarise.
  */
-async function executeFixRun(report, outputPath, overlaysConfig, overlaysDir, requestedJson, explicitManifestPath) {
+async function executeFixRun(report, outputPath, overlaysConfig, overlaysDir, requestedJson, explicitManifestPath, workingDir = process.cwd()) {
     const initialFindings = reportToFindings(report);
     // Separate automatic and manual-only fixable findings
     const autoFixable = initialFindings.filter((f) => f.fixEligibility === 'automatic' && f.status !== 'pass');
@@ -1471,7 +2821,7 @@ async function executeFixRun(report, outputPath, overlaysConfig, overlaysDir, re
                 }
             }
         }
-        const execution = await executeSingleFix(finding, outputPath, overlaysConfig, overlaysDir, requestedJson, explicitManifestPath);
+        const execution = await executeSingleFix(finding, outputPath, overlaysConfig, overlaysDir, requestedJson, explicitManifestPath, workingDir);
         executions.push(execution);
         if (finding.remediationKey === 'manifest-migration' &&
             execution.outcome !== 'fixed' &&
@@ -1500,12 +2850,24 @@ async function executeFixRun(report, outputPath, overlaysConfig, overlaysDir, re
     const overlayChecks = checkOverlays(overlaysDir);
     const finalManifestPath = explicitManifestPath ?? path.join(outputPath, 'superposition.json');
     const portChecks = checkPorts(overlaysConfig, finalManifestPath);
+    const finalDriftChecks = checkProjectFileDrift(overlaysConfig, workingDir, finalManifestPath);
+    const finalParamChecks = checkParameters(overlaysConfig, outputPath, workingDir);
+    const finalDepChecks = checkDependencies(overlaysConfig, workingDir);
+    const finalPortCrossChecks = checkPortCrossValidation(outputPath);
+    const finalEnvDriftChecks = checkEnvExampleDrift(overlaysConfig, outputPath, workingDir);
+    const finalReproChecks = await checkReproducibility(overlaysConfig, outputPath, overlaysDir, workingDir);
     const finalFindings = [
         ...checksToFindings(envChecks, 'environment', 'environment'),
         ...checksToFindings(manifestChecks, 'manifest', 'manifest'),
         ...checksToFindings(mergeChecks, 'merge', 'devcontainer'),
         ...checksToFindings(overlayChecks, 'overlay', 'full'),
         ...checksToFindings(portChecks, 'ports', 'environment'),
+        ...checksToFindings(finalDriftChecks, 'manifest', 'manifest'),
+        ...checksToFindings(finalParamChecks, 'manifest', 'full'),
+        ...checksToFindings(finalDepChecks, 'manifest', 'full'),
+        ...checksToFindings(finalPortCrossChecks, 'ports', 'full'),
+        ...checksToFindings(finalEnvDriftChecks, 'manifest', 'full'),
+        ...checksToFindings(finalReproChecks, 'manifest', 'full'),
     ];
     const summary = buildOutcomeSummary(executions);
     const exitDisposition = determineExitDisposition(summary, finalFindings);
@@ -1671,6 +3033,11 @@ export async function doctorCommand(overlaysConfig, overlaysDir, options) {
                 borderStyle: 'round',
             }));
     }
+    // ── Validate --dry-run flag ───────────────────────────────────────────────
+    if (options.dryRun && !options.fix) {
+        console.error(chalk.red('✗ Error: --dry-run requires --fix. Use: cs doctor --fix --dry-run'));
+        process.exit(1);
+    }
     // Run all checks
     const environmentChecks = checkEnvironment(outputPath, explicitManifestPath);
     const overlayChecks = checkOverlays(overlaysDir);
@@ -1678,15 +3045,80 @@ export async function doctorCommand(overlaysConfig, overlaysDir, options) {
     const mergeChecks = checkMergeStrategy(outputPath);
     const manifestPath = explicitManifestPath ?? path.join(outputPath, 'superposition.json');
     const portChecks = checkPorts(overlaysConfig, manifestPath);
+    const driftChecks = checkProjectFileDrift(overlaysConfig, workingDir, manifestPath);
+    const parametersChecks = checkParameters(overlaysConfig, outputPath, workingDir);
+    const dependenciesChecks = checkDependencies(overlaysConfig, workingDir);
+    const portCrossValidationChecks = checkPortCrossValidation(outputPath);
+    const envExampleDriftChecks = checkEnvExampleDrift(overlaysConfig, outputPath, workingDir);
+    const reproducibilityChecks = await checkReproducibility(overlaysConfig, outputPath, overlaysDir, workingDir);
     // Generate report
-    const report = generateReport(environmentChecks, overlayChecks, manifestChecks, mergeChecks, portChecks);
+    const report = generateReport(environmentChecks, overlayChecks, manifestChecks, mergeChecks, portChecks, driftChecks, parametersChecks, dependenciesChecks, portCrossValidationChecks, envExampleDriftChecks, reproducibilityChecks);
     if (options.fix) {
         // ── Fix flow ──────────────────────────────────────────────────────────
         if (!options.json) {
             // Print diagnostic findings first (as normal)
             console.log(formatAsText(report));
         }
-        const fixRun = await executeFixRun(report, outputPath, overlaysConfig, overlaysDir, options.json ?? false, explicitManifestPath);
+        // ── Dry-run branch ────────────────────────────────────────────────────
+        if (options.dryRun) {
+            const allFindings = reportToFindings(report);
+            const autoFixable = allFindings.filter((f) => f.fixEligibility === 'automatic' && f.status !== 'pass');
+            const manualOnly = allFindings.filter((f) => f.fixEligibility === 'manual-only' && f.status !== 'pass');
+            if (options.json) {
+                const plannedActions = autoFixable.map((f) => {
+                    const action = REMEDIATION_REGISTRY.get(f.remediationKey ?? '');
+                    return {
+                        findingName: f.name,
+                        remediationKey: f.remediationKey ?? '',
+                        plannedChanges: action?.plannedChanges ?? [],
+                        safetyClass: action?.safetyClass ?? 'safe-unattended',
+                    };
+                });
+                console.log(JSON.stringify({
+                    dryRun: true,
+                    plannedActions,
+                    manualFindings: manualOnly.map((f) => ({
+                        name: f.name,
+                        message: f.message,
+                    })),
+                }, null, 2));
+            }
+            else {
+                if (autoFixable.length === 0) {
+                    console.log(chalk.green('\nDoctor dry-run — no auto-fixable findings. Nothing to apply.'));
+                }
+                else {
+                    console.log(chalk.bold('\nDoctor dry-run — changes that --fix would apply:'));
+                    console.log(chalk.dim('══════════════════════════════════════════════════'));
+                    autoFixable.forEach((f, i) => {
+                        const action = REMEDIATION_REGISTRY.get(f.remediationKey ?? '');
+                        console.log(`\n  [${i + 1}] ${chalk.cyan(f.remediationKey ?? '')} (${chalk.dim(action?.safetyClass ?? '')})`);
+                        console.log(`      Finding: ${chalk.white(`"${f.message}"`)}`);
+                        console.log(`      Would:`);
+                        for (const change of action?.plannedChanges ?? []) {
+                            console.log(`        ${chalk.dim('•')} ${chalk.dim(change)}`);
+                        }
+                    });
+                    console.log(chalk.dim('\n──────────────────────────────────────────────────'));
+                    console.log(`  ${chalk.yellow(`${autoFixable.length} fix action(s) would be applied.`)} Run without --dry-run to apply.`);
+                }
+                if (manualOnly.length > 0) {
+                    console.log(chalk.bold('\nFindings that require manual action (not auto-fixable):'));
+                    for (const f of manualOnly) {
+                        console.log(`  ${chalk.red('✗')} ${chalk.white(f.name)} — ${chalk.gray(f.message)}`);
+                        const action = REMEDIATION_REGISTRY.get(f.remediationKey ?? '');
+                        if (action?.manualFallback.length) {
+                            for (const step of action.manualFallback) {
+                                console.log(`    ${chalk.dim('→')} ${chalk.dim(step)}`);
+                            }
+                        }
+                    }
+                }
+            }
+            const hasAnyFindings = autoFixable.length > 0 || manualOnly.length > 0;
+            process.exit(hasAnyFindings ? 1 : 0);
+        }
+        const fixRun = await executeFixRun(report, outputPath, overlaysConfig, overlaysDir, options.json ?? false, explicitManifestPath, workingDir);
         if (options.json) {
             console.log(JSON.stringify(fixRun, null, 2));
         }