voratiq 0.1.0-beta.21 → 0.1.0-beta.22

package/dist/cli/operator-envelope.js

@@ -131,6 +131,8 @@ export function buildSpecOperatorEnvelope(options) {
     });
 }
 export function buildRunOperatorEnvelope(options) {
+    const target = buildRunEnvelopeTarget(options.specTarget);
+    const alerts = buildRunEnvelopeAlerts(options.specTarget);
     return buildOperatorEnvelope({
         operator: "run",
         status: normalizeTerminalStatus(options.status),
@@ -149,10 +151,12 @@ export function buildRunOperatorEnvelope(options) {
                 path: options.specPath,
             },
         ],
+        target,
+        alerts,
     });
 }
 export function buildVerifyOperatorEnvelope(options) {
-    const status = options.selection?.state === "unresolved"
+    const status = options.status === "unresolved" || options.selection?.state === "unresolved"
         ? "unresolved"
         : normalizeTerminalStatus(options.status);
     const ids = {
@@ -232,6 +236,9 @@ export function buildReduceOperatorEnvelope(options) {
     if (options.target.type === "reduce") {
         ids.reductionId = options.target.id;
     }
+    if (options.target.type === "message") {
+        ids.messageId = options.target.id;
+    }
     return buildOperatorEnvelope({
         operator: "reduce",
         status: normalizeTerminalStatus(options.status),
@@ -331,6 +338,59 @@ export function buildPruneOperatorEnvelope(options) {
             : [],
     });
 }
+function buildRunEnvelopeTarget(specTarget) {
+    if (specTarget?.kind === "spec") {
+        return {
+            kind: "spec",
+            sessionId: specTarget.sessionId,
+            ...(specTarget.provenance
+                ? buildRunEnvelopeProvenanceFields(specTarget.provenance)
+                : {}),
+        };
+    }
+    if (specTarget?.kind === "file" &&
+        specTarget.provenance?.source?.sessionId &&
+        specTarget.provenance.lineage === "invalid") {
+        return {
+            kind: "spec",
+            sessionId: specTarget.provenance.source.sessionId,
+            ...buildRunEnvelopeProvenanceFields(specTarget.provenance),
+        };
+    }
+    return undefined;
+}
+function buildRunEnvelopeAlerts(specTarget) {
+    if (specTarget?.provenance?.lineage !== "invalid") {
+        return undefined;
+    }
+    return [
+        {
+            level: "warn",
+            message: specTarget.provenance.issueCode === "stale_source"
+                ? "Run spec ancestry metadata referenced a stale or mismatched spec artifact."
+                : "Run spec ancestry metadata was malformed and was ignored.",
+        },
+    ];
+}
+function buildRunEnvelopeProvenanceFields(provenance) {
+    return {
+        lineage: provenance.lineage,
+        ...(provenance.lineage === "invalid"
+            ? { issueCode: provenance.issueCode }
+            : {}),
+        ...("currentContentHash" in provenance &&
+            typeof provenance.currentContentHash === "string"
+            ? { currentContentHash: provenance.currentContentHash }
+            : {}),
+        ...(provenance.source
+            ? {
+                source: {
+                    ...provenance.source,
+                },
+            }
+            : {}),
+    };
+}
 export function writeOperatorResultEnvelope(envelope, exitCode) {
     process.stdout.write(`${JSON.stringify(envelope)}\n`);
     if (typeof exitCode === "number") {

package/dist/cli/run.js

@@ -61,6 +61,7 @@ export async function runRunCommand(options) {
     const report = await executeRunCommand({
         root,
         runsFilePath: workspacePaths.runsFile,
+        specsFilePath: workspacePaths.specsFile,
         specAbsolutePath: absolutePath,
         specDisplayPath: displayPath,
         agentIds,
@@ -131,6 +132,7 @@ export function createRunCommand() {
             writeOperatorResultEnvelope(buildRunOperatorEnvelope({
                 runId: result.report.runId,
                 specPath: result.report.spec.path,
+                specTarget: result.report.spec.target,
                 status: result.report.status,
             }), result.exitCode);
             return;

package/dist/cli/verify.d.ts

@@ -22,7 +22,7 @@ export interface VerifyCommandOptions {
 }
 export interface VerifyCommandResult {
     verificationId: string;
-    status: VerificationRecord["status"];
+    status: VerificationRecord["status"] | "unresolved";
     target: VerificationRecord["target"];
     body: string;
     exitCode?: number;

package/dist/cli/verify.js

@@ -23,6 +23,22 @@ import { resolveWorkspacePath, VORATIQ_MESSAGE_FILE, VORATIQ_REDUCTION_FILE, VOR
 import { parseVerifyExecutionCommandOptions } from "./contract.js";
 import { buildVerifyOperatorEnvelope, createSilentCliWriter, writeOperatorResultEnvelope, } from "./operator-envelope.js";
 import { writeCommandOutput } from "./output.js";
+function resolveVerifyManualActionMessage(options) {
+    const { targetKind, status, selection, selectedSpecPath } = options;
+    if (status !== "succeeded") {
+        return undefined;
+    }
+    if (targetKind === "spec" && !selectedSpecPath) {
+        return "Verification did not select a spec path; manual review required.";
+    }
+    if (selection?.decision.state !== "unresolved") {
+        return undefined;
+    }
+    if (targetKind === "run") {
+        return "Verification did not produce a resolvable candidate; manual selection required.";
+    }
+    return "Verification did not produce a resolvable result; manual review required.";
+}
 export async function runVerifyCommand(options) {
     const { target, agentIds, agentOverrideFlag, profile, maxParallel, extraContext, json = false, suppressHint, stdout, stderr, writeOutput, } = options;
     const effectiveWriteOutput = json
@@ -97,10 +113,30 @@ export async function runVerifyCommand(options) {
         return undefined;
     });
     const selectionWarnings = (selection?.warnings ?? []).map((warning) => `Warning: ${warning}`);
+    const selectedSpecPath = execution.record.target.kind === "spec" &&
+        typeof execution.record.target.specPath === "string"
+        ? execution.record.target.specPath
+        : undefined;
+    const manualActionMessage = resolveVerifyManualActionMessage({
+        targetKind: execution.record.target.kind,
+        status: execution.record.status,
+        selection,
+        selectedSpecPath,
+    });
     const warningMessage = [
         ...selectionWarnings,
         ...(selectionPolicyWarning ? [selectionPolicyWarning] : []),
+        ...(manualActionMessage ? [manualActionMessage] : []),
     ].join("\n");
+    const displayStatus = selection?.decision.state === "unresolved"
+        ? "unresolved"
+        : execution.record.status;
+    if (displayStatus === "unresolved" && !json) {
+        renderer.complete("unresolved", {
+            startedAt: execution.record.startedAt,
+            completedAt: execution.record.completedAt,
+        });
+    }
     const recommendedRunAgent = execution.record.target.kind === "run" &&
         selection !== undefined &&
         selection.decision.state === "resolvable"
@@ -109,9 +145,10 @@ export async function runVerifyCommand(options) {
     const hintMessage = suppressHint ||
         selectionPolicyWarning ||
         execution.record.target.kind !== "run" ||
-        execution.record.status !== "succeeded"
+        execution.record.status !== "succeeded" ||
+        selection?.decision.state !== "resolvable"
         ? undefined
-        : `To apply a solution:\n  voratiq apply --run ${execution.record.target.sessionId} --agent ${recommendedRunAgent ?? "<agent-id>"}`;
+        : `To apply a solution:\n  voratiq apply --run ${execution.record.target.sessionId} --agent ${recommendedRunAgent}`;
     const outputPath = normalizePathForDisplay(relativeToRoot(root, resolveWorkspacePath(root, VORATIQ_VERIFICATION_SESSIONS_DIR, execution.verificationId)));
     const body = renderVerifyTranscript({
         verificationId: execution.verificationId,
@@ -123,7 +160,7 @@ export async function runVerifyCommand(options) {
         }) ?? "—",
         workspacePath: normalizePathForDisplay(relativeToRoot(root, resolveWorkspacePath(root, VORATIQ_VERIFICATION_SESSIONS_DIR, execution.verificationId))),
         target: execution.record.target,
-        status: execution.record.status,
+        status: displayStatus,
         methods: methodBlocks,
         suppressHint,
         ...(warningMessage ? { warningMessage } : {}),
@@ -133,15 +170,17 @@ export async function runVerifyCommand(options) {
     });
     return {
         verificationId: execution.verificationId,
-        status: execution.record.status,
+        status: displayStatus,
         target: execution.record.target,
         body,
-        exitCode: execution.record.status === "succeeded" ? 0 : 1,
+        exitCode: execution.record.status === "succeeded" &&
+            selection?.decision.state !== "unresolved" &&
+            !(execution.record.target.kind === "spec" &&
+                typeof selectedSpecPath !== "string")
+            ? 0
+            : 1,
         outputPath,
-        ...(execution.record.target.kind === "spec" &&
-            typeof execution.record.target.specPath === "string"
-            ? { selectedSpecPath: execution.record.target.specPath }
-            : {}),
+        ...(selectedSpecPath ? { selectedSpecPath } : {}),
         selection,
         ...(warningMessage ? { warningMessage } : {}),
     };

package/dist/commands/auto/command.d.ts

@@ -69,6 +69,7 @@ export interface AutoVerifyStageResult {
     selectedSpecPath?: string;
     selection?: SelectionDecision;
     selectionWarnings?: readonly string[];
+    warningMessage?: string;
 }
 export interface AutoApplyStageInput {
     runId: string;

package/dist/commands/auto/command.js

@@ -101,12 +101,7 @@ export async function executeAutoCommand(options, dependencies) {
                     stderr: specVerifyResult.stderr,
                     exitCode: specVerifyResult.exitCode,
                 });
-                if (specVerifyResult.exitCode === 1) {
-                    specStatus = "failed";
-                    specDetail = "One or more spec verifiers failed.";
-                    hardFailure = true;
-                }
-                else if (typeof specVerifyResult.selectedSpecPath === "string" &&
+                if (typeof specVerifyResult.selectedSpecPath === "string" &&
                     specVerifyResult.selectedSpecPath.trim().length > 0) {
                     resolvedSpecPath = specVerifyResult.selectedSpecPath;
                     specPath = specVerifyResult.selectedSpecPath;
@@ -117,7 +112,7 @@ export async function executeAutoCommand(options, dependencies) {
                         "Spec verification returned a resolvable selection without a selected spec path.";
                     hardFailure = true;
                 }
-                else {
+                else if (specVerifyResult.selection) {
                     const specSelectionDisposition = classifyAutoVerificationSelection({
                         targetKind: "spec",
                         selection: specVerifyResult.selection,
@@ -128,6 +123,13 @@ export async function executeAutoCommand(options, dependencies) {
                     specDetail = specSelectionDisposition.detail;
                     markActionRequired(specSelectionDisposition.detail);
                 }
+                else if (specVerifyResult.exitCode === 1) {
+                    specStatus = "failed";
+                    specDetail =
+                        specVerifyResult.warningMessage?.trim() ||
+                            "Spec verification did not produce any successful verifier results.";
+                    hardFailure = true;
+                }
             }
             catch (error) {
                 specStatus = "failed";
@@ -215,11 +217,6 @@ export async function executeAutoCommand(options, dependencies) {
             });
             verifyStatus = "succeeded";
             verifySelection = verifyResult.selection;
-            if (verifyResult.exitCode === 1) {
-                verifyStatus = "failed";
-                verifyDetail = "One or more verifiers failed.";
-                hardFailure = true;
-            }
             recordEvent({
                 kind: "body",
                 body: verifyResult.body,
@@ -234,6 +231,12 @@ export async function executeAutoCommand(options, dependencies) {
                     separateWithDivider: bodyOutputEmitted,
                 });
             }
+            if (options.apply === true &&
+                (verifyResult.selectionWarnings?.length ?? 0) > 0) {
+                const warningDetail = "Verification reported warnings for the selected candidate; automatic apply halted. Review the verify output and apply manually if appropriate.";
+                verifyDetail = warningDetail;
+                markActionRequired(warningDetail);
+            }
             if (verifySelection?.state === "unresolved") {
                 const verifySelectionDisposition = classifyAutoVerificationSelection({
                     targetKind: "run",
@@ -247,6 +250,13 @@ export async function executeAutoCommand(options, dependencies) {
                     },
                 });
             }
+            else if (verifyResult.exitCode === 1) {
+                verifyStatus = "failed";
+                verifyDetail =
+                    verifyResult.warningMessage?.trim() ||
+                        "Verification did not produce any successful verifier results.";
+                hardFailure = true;
+            }
         }
         catch (error) {
             verifyStatus = "failed";

package/dist/commands/auto/errors.js

@@ -12,7 +12,7 @@ export class AutoPreflightError extends CliError {
             }
         });
         super("Preflight failed. Aborting auto.", detailLines, [
-            "Run `voratiq init` from the repository root, then retry.",
+            "Run `voratiq doctor --fix` to repair workspace setup.",
         ]);
         this.name = "AutoPreflightError";
     }

package/dist/commands/doctor/agents.d.ts

@@ -0,0 +1,5 @@
+import { type AgentPreset } from "../../workspace/templates.js";
+import type { AgentInitSummary, DoctorBootstrapConfigureOptions } from "./fix-types.js";
+export declare const AGENTS_CONFIG_DISPLAY_PATH: string;
+export declare function bootstrapDoctorAgents(root: string, preset: AgentPreset, options: DoctorBootstrapConfigureOptions): Promise<AgentInitSummary>;
+export declare function reconcileManagedDoctorAgents(root: string): Promise<AgentInitSummary>;

package/dist/commands/{init → doctor}/agents.js

@@ -1,21 +1,35 @@
 import { getAgentDefaultId, getSupportedAgentDefaults, } from "../../configs/agents/defaults.js";
 import { readAgentsConfig } from "../../configs/agents/loader.js";
 import { detectBinary } from "../../utils/binaries.js";
-import { isDefaultYamlTemplate, loadYamlConfig, persistYamlConfig, } from "../../utils/yaml.js";
+import { isDefaultYamlTemplate, loadYamlConfig, writeConfigIfChanged, } from "../../utils/yaml.js";
+import { isManagedAgentsFingerprintMatch, readManagedState, } from "../../workspace/managed-state.js";
 import { formatWorkspacePath, resolveWorkspacePath, VORATIQ_AGENTS_FILE, } from "../../workspace/structure.js";
 import { buildDefaultAgentsTemplate, serializeAgentsConfigEntries, } from "../../workspace/templates.js";
 export const AGENTS_CONFIG_DISPLAY_PATH = formatWorkspacePath(VORATIQ_AGENTS_FILE);
-export async function configureAgents(root, preset, options) {
+export async function bootstrapDoctorAgents(root, preset, options) {
     void preset;
     void options;
-    const filePath = resolveWorkspacePath(root, VORATIQ_AGENTS_FILE);
     const defaultTemplate = buildDefaultAgentsTemplate();
+    return configureAgentsWithMode(root, defaultTemplate, "bootstrap");
+}
+export async function reconcileManagedDoctorAgents(root) {
+    const defaultTemplate = buildDefaultAgentsTemplate();
+    return configureAgentsWithMode(root, defaultTemplate, "reconcile");
+}
+async function configureAgentsWithMode(root, defaultTemplate, mode) {
+    const filePath = resolveWorkspacePath(root, VORATIQ_AGENTS_FILE);
     const loadResult = await loadYamlConfig(filePath, readAgentsConfig);
     const defaultStatus = isDefaultYamlTemplate(loadResult.snapshot, defaultTemplate);
     const configCreated = !loadResult.snapshot.exists;
-    const lifecycle = scanWorkspaceForAgentDefaults(loadResult.config, defaultStatus, getSupportedAgentDefaults());
+    const managedState = mode === "reconcile" ? await readManagedState(root) : undefined;
+    const managed = mode === "reconcile"
+        ? !loadResult.snapshot.exists ||
+            isManagedAgentsFingerprintMatch(managedState?.configs.agents, loadResult.snapshot.content) ||
+            defaultStatus
+        : defaultStatus;
+    const lifecycle = scanWorkspaceForAgentDefaults(loadResult.config, mode, getSupportedAgentDefaults());
     const detectedProviders = collectDetectedProviders(lifecycle.templates);
-    if (!defaultStatus && loadResult.snapshot.exists) {
+    if (!managed && loadResult.snapshot.exists) {
         return buildAgentSummary({
             entries: loadResult.config.agents,
             zeroDetections: detectedProviders.length === 0,
@@ -23,16 +37,14 @@ export async function configureAgents(root, preset, options) {
             providerEnablementPrompted: false,
             configCreated,
             configUpdated: false,
+            managed: false,
         });
     }
     const snapshotResult = finalizeAgentConfigSnapshot(lifecycle);
-    const updated = await persistYamlConfig({
-        filePath,
-        serialized: snapshotResult.serialized,
-        original: loadResult.snapshot,
-        defaultTemplate,
-        isDefaultTemplate: defaultStatus,
-    });
+    const previousNormalized = loadResult.snapshot.exists
+        ? loadResult.snapshot.normalized
+        : "__missing__";
+    const updated = await writeConfigIfChanged(filePath, snapshotResult.serialized, previousNormalized);
     return buildAgentSummary({
         entries: snapshotResult.entries,
         zeroDetections: lifecycle.zeroDetections,
@@ -40,9 +52,10 @@ export async function configureAgents(root, preset, options) {
         providerEnablementPrompted: false,
         configCreated,
         configUpdated: updated,
+        managed: true,
     });
 }
-function scanWorkspaceForAgentDefaults(config, isDefaultTemplate, templates) {
+function scanWorkspaceForAgentDefaults(config, mode, templates) {
     const templatesById = new Map();
     for (const entry of config.agents) {
         templatesById.set(entry.id, entry);
@@ -56,9 +69,7 @@ function scanWorkspaceForAgentDefaults(config, isDefaultTemplate, templates) {
     }));
     for (const { template, templateId } of templateEntries) {
         templateIds.add(templateId);
-        const existing = isDefaultTemplate
-            ? undefined
-            : templatesById.get(templateId);
+        const existing = templatesById.get(templateId);
         let detectedBinary = detectedBinaryByProvider.get(template.provider);
         if (!detectedBinaryByProvider.has(template.provider)) {
             detectedBinary = detectBinary(template.provider);
@@ -66,8 +77,14 @@ function scanWorkspaceForAgentDefaults(config, isDefaultTemplate, templates) {
         }
         const baseEntry = existing ?? buildEntryFromTemplate(template, templateId);
         const entry = cloneAgentEntry(baseEntry);
-        entry.binary = detectedBinary ?? "";
-        entry.enabled = entry.enabled !== false;
+        if (hasBinary(detectedBinary)) {
+            entry.binary = detectedBinary ?? "";
+            entry.enabled = true;
+        }
+        else if (!existing || mode === "bootstrap") {
+            entry.binary = "";
+            entry.enabled = false;
+        }
         templateStates.push({
             templateId,
             template,
@@ -142,7 +159,7 @@ function finalizeAgentConfigSnapshot(state) {
     return { entries, serialized };
 }
 function buildAgentSummary(options) {
-    const { entries, zeroDetections, detectedProviders, providerEnablementPrompted, configCreated, configUpdated, } = options;
+    const { entries, zeroDetections, detectedProviders, providerEnablementPrompted, configCreated, configUpdated, managed, } = options;
     const enabledAgents = entries
         .filter((entry) => entry.enabled !== false)
         .map((entry) => entry.id);
@@ -155,6 +172,7 @@ function buildAgentSummary(options) {
         providerEnablementPrompted,
         configCreated,
         configUpdated,
+        managed,
     };
 }
 function hasBinary(binary) {

package/dist/commands/doctor/command.d.ts

@@ -0,0 +1,22 @@
+import { executeDoctorBootstrap } from "./fix.js";
+import type { DoctorReconcileResult } from "./fix-types.js";
+export interface DoctorDiagnosisResult {
+    readonly healthy: boolean;
+    readonly issueLines: readonly string[];
+}
+export type DoctorFixMode = "bootstrap-workspace" | "repair-and-reconcile";
+export interface DoctorFixResult {
+    readonly mode: DoctorFixMode;
+    readonly reconcileResult?: DoctorReconcileResult;
+}
+export interface ExecuteDoctorDiagnosisInput {
+    readonly root: string;
+}
+export interface ExecuteDoctorFixInput {
+    readonly root: string;
+    readonly mode?: DoctorFixMode;
+    readonly bootstrapOptions?: Pick<Parameters<typeof executeDoctorBootstrap>[0], "preset" | "interactive" | "assumeYes" | "confirm" | "prompt">;
+}
+export declare function executeDoctorDiagnosis(input: ExecuteDoctorDiagnosisInput): Promise<DoctorDiagnosisResult>;
+export declare function resolveDoctorFixMode(root: string): Promise<DoctorFixMode>;
+export declare function executeDoctorFix(input: ExecuteDoctorFixInput): Promise<DoctorFixResult>;

package/dist/commands/doctor/command.js

@@ -0,0 +1,99 @@
+import { formatPreflightIssueLines } from "../../competition/shared/preflight.js";
+import { EnvironmentConfigParseError, MissingEnvironmentConfigError, } from "../../configs/environment/errors.js";
+import { loadEnvironmentConfig } from "../../configs/environment/loader.js";
+import { prepareConfiguredOperatorReadiness } from "../../preflight/operator.js";
+import { toErrorMessage } from "../../utils/errors.js";
+import { pathExists } from "../../utils/fs.js";
+import { WorkspaceError, WorkspaceMissingEntryError, } from "../../workspace/errors.js";
+import { repairWorkspaceStructure, validateWorkspace, } from "../../workspace/setup.js";
+import { formatWorkspacePath, resolveWorkspacePath, } from "../../workspace/structure.js";
+import { executeDoctorBootstrap } from "./fix.js";
+import { executeDoctorReconcile } from "./reconcile.js";
+const DOCTOR_PREFLIGHT_UNLABELED_AGENT_IDS = ["settings"];
+export async function executeDoctorDiagnosis(input) {
+    const { root } = input;
+    const issueLines = [];
+    const workspacePresent = await pathExists(resolveWorkspacePath(root));
+    if (!workspacePresent) {
+        const missingWorkspaceIssue = new WorkspaceMissingEntryError(`${formatWorkspacePath()}/`);
+        issueLines.push(`- ${missingWorkspaceIssue.headline}`);
+        return {
+            healthy: false,
+            issueLines,
+        };
+    }
+    try {
+        await validateWorkspace(root);
+    }
+    catch (error) {
+        issueLines.push(...formatDoctorIssueLines(error));
+        return {
+            healthy: false,
+            issueLines,
+        };
+    }
+    try {
+        const diagnostics = await prepareConfiguredOperatorReadiness({ root });
+        if (diagnostics.noAgentsEnabled) {
+            issueLines.push("- No agents are enabled in `agents.yaml`.");
+        }
+        issueLines.push(...formatPreflightIssueLines(diagnostics.issues, {
+            unlabeledAgentIds: DOCTOR_PREFLIGHT_UNLABELED_AGENT_IDS,
+        }));
+    }
+    catch (error) {
+        issueLines.push(...formatDoctorIssueLines(error));
+    }
+    try {
+        loadEnvironmentConfig({ root });
+    }
+    catch (error) {
+        if (error instanceof MissingEnvironmentConfigError) {
+            issueLines.push(`- ${error.headline}`);
+        }
+        else if (error instanceof EnvironmentConfigParseError) {
+            issueLines.push(`- ${error.headline}`);
+        }
+        else {
+            issueLines.push(`- ${toErrorMessage(error)}`);
+        }
+    }
+    return {
+        healthy: issueLines.length === 0,
+        issueLines,
+    };
+}
+export async function resolveDoctorFixMode(root) {
+    const workspacePresent = await pathExists(resolveWorkspacePath(root));
+    return workspacePresent ? "repair-and-reconcile" : "bootstrap-workspace";
+}
+export async function executeDoctorFix(input) {
+    const mode = input.mode ?? (await resolveDoctorFixMode(input.root));
+    if (mode === "bootstrap-workspace") {
+        const bootstrapOptions = input.bootstrapOptions;
+        await executeDoctorBootstrap({
+            root: input.root,
+            preset: bootstrapOptions?.preset ?? "pro",
+            interactive: bootstrapOptions?.interactive ?? false,
+            assumeYes: bootstrapOptions?.assumeYes,
+            confirm: bootstrapOptions?.confirm,
+            prompt: bootstrapOptions?.prompt,
+        });
+        return { mode };
+    }
+    await repairWorkspaceStructure(input.root);
+    const reconcileResult = await executeDoctorReconcile({ root: input.root });
+    return {
+        mode,
+        reconcileResult,
+    };
+}
+function formatDoctorIssueLines(error) {
+    if (error instanceof WorkspaceError) {
+        return [`- ${error.headline}`];
+    }
+    if (error instanceof Error && error.message.length > 0) {
+        return [`- ${error.message}`];
+    }
+    return [`- ${toErrorMessage(error)}`];
+}

package/dist/commands/doctor/environment.d.ts

@@ -0,0 +1,2 @@
+import type { DoctorBootstrapConfigureOptions, EnvironmentInitSummary } from "./fix-types.js";
+export declare function reconcileDoctorEnvironment(root: string, options: DoctorBootstrapConfigureOptions): Promise<EnvironmentInitSummary>;

package/dist/commands/{init → doctor}/environment.js

@@ -1,15 +1,16 @@
 import { detectEnvironmentConfig } from "../../configs/environment/detect.js";
+import { EnvironmentConfigParseError } from "../../configs/environment/errors.js";
 import { readEnvironmentConfig, serializeEnvironmentConfig, } from "../../configs/environment/loader.js";
 import { getNodeDependencyRoots, getPythonEnvironmentPath, isNodeEnvironmentDisabled, isPythonEnvironmentDisabled, } from "../../configs/environment/types.js";
-import { loadYamlConfig, persistYamlConfig } from "../../utils/yaml.js";
+import { persistYamlConfig, readConfigSnapshot } from "../../utils/yaml.js";
 import { formatWorkspacePath, resolveWorkspacePath, VORATIQ_ENVIRONMENT_FILE, } from "../../workspace/structure.js";
 import { buildDefaultEnvironmentTemplate } from "../../workspace/templates.js";
 const ENVIRONMENT_CONFIG_DISPLAY_PATH = formatWorkspacePath(VORATIQ_ENVIRONMENT_FILE);
-export async function configureEnvironment(root, options) {
+export async function reconcileDoctorEnvironment(root, options) {
     const filePath = resolveWorkspacePath(root, VORATIQ_ENVIRONMENT_FILE);
     const defaultTemplate = buildDefaultEnvironmentTemplate();
-    const loadResult = await loadYamlConfig(filePath, readEnvironmentConfig);
-    const existingConfig = loadResult.config;
+    const originalSnapshot = await readConfigSnapshot(filePath);
+    const existingConfig = resolveExistingConfig(originalSnapshot);
     const detection = await detectEnvironmentConfig({
         root,
         interactive: options.interactive,
@@ -20,17 +21,48 @@ export async function configureEnvironment(root, options) {
     const configUpdated = await persistYamlConfig({
         filePath,
         serialized: finalSerialized,
-        original: loadResult.snapshot,
+        original: shouldRewriteFromScratch(originalSnapshot)
+            ? { content: "", normalized: "", exists: false }
+            : originalSnapshot,
         defaultTemplate,
     });
     return {
         configPath: ENVIRONMENT_CONFIG_DISPLAY_PATH,
         detectedEntries: describeEnvironmentEntries(mergedConfig),
-        configCreated: !loadResult.snapshot.exists,
+        configCreated: !originalSnapshot.exists,
         configUpdated,
         config: mergedConfig,
     };
 }
+function resolveExistingConfig(snapshot) {
+    if (!snapshot.exists) {
+        return {};
+    }
+    try {
+        return readEnvironmentConfig(snapshot.content);
+    }
+    catch (error) {
+        if (error instanceof EnvironmentConfigParseError) {
+            return {};
+        }
+        throw error;
+    }
+}
+function shouldRewriteFromScratch(snapshot) {
+    if (!snapshot.exists) {
+        return false;
+    }
+    try {
+        readEnvironmentConfig(snapshot.content);
+        return false;
+    }
+    catch (error) {
+        if (error instanceof EnvironmentConfigParseError) {
+            return true;
+        }
+        throw error;
+    }
+}
 function mergeEnvironmentConfig(existing, detected) {
     const merged = { ...existing };
     if (!isNodeEnvironmentDisabled(merged)) {