@interf/compiler 0.3.3 → 0.4.0

package/builtin-workflows/interf/use/query/SKILL.md

@@ -0,0 +1,28 @@
+# Manual Query Loop
+
+This file is the editable authoring source for the generated native local `interf-query` skill.
+
+Default loop:
+1. Read `home.md` first.
+2. Browse `knowledge/` before `raw/`.
+3. Use `summaries/` for source-grounded evidence.
+4. Use `raw/` for direct quotes, verification, exact table lookups, and chart-derived values.
+
+Answering rule:
+- do not modify files under `raw/`
+- when a number is chart-derived, say that explicitly
+- if the compiled layer already contains a bounded chart-derived read for the exact metric and year the user asked about, answer from that compiled read first
+- use `raw/` to confirm the source page, metric family, or provenance, not to replace a good compiled bounded read with a second incompatible range
+- when the compiled layer preserves a bounded chart-derived range, keep that bounded range in the answer instead of collapsing it to a midpoint or pseudo-exact single value
+- match the granularity of the visible axis labels or bands and do not invent finer precision than the chart supports
+- when reading charts, verify you are on the correct metric family and year before answering
+- keep historical annual charts separate from current-quarter snapshots, sector splits, or nearby lookalike panels
+- when a chart-derived value is approximate, use a bounded range instead of a pseudo-exact number.
+- keep the answer inside the visible tick band unless the chart supports a tighter bound.
+- use an upper-half or lower-half band only when the mark clearly sits there.
+- if a mark touches or nearly touches a labeled gridline, anchor the answer at that gridline or the immediately adjacent half-band.
+- do not widen a chart-derived range across multiple visible bands unless the chart genuinely supports that uncertainty.
+- if multiple compiled notes mention the same chart read, keep the answer consistent with the most focused workspace note rather than synthesizing a new midpoint or shifted band
+- when the compiled layer is insufficient, verify in `raw/` and then answer
+
+You can edit this file to bias manual question-answering behavior for this workspace.

package/builtin-workflows/interf/workflow.json

@@ -0,0 +1,120 @@
+{
+  "id": "interf",
+  "type": "workspace",
+  "compiler_api": {
+    "kind": "workspace",
+    "version": 1
+  },
+  "label": "Interf Compiler (Recommended)",
+  "hint": "Interf Compiler's default methodology: summarize source-grounded evidence, structure the cross-file layer, then shape the final workspace around its focus and saved truth checks.",
+  "stages": [
+    {
+      "id": "summarize",
+      "label": "Summarize",
+      "description": "Turn source files into per-file summaries.",
+      "contract_type": "workspace-file-evidence",
+      "skill_dir": "summarize",
+      "reads": [
+        "raw",
+        "runtime"
+      ],
+      "writes": [
+        "summaries"
+      ],
+      "acceptance": {
+        "artifacts_exist": [
+          ".interf/runtime/inventory.json"
+        ],
+        "state_truthy": [
+          "last_summarize",
+          "inventory_complete"
+        ],
+        "state_at_least_counts": {
+          "summarized": "expected_summary_total"
+        }
+      }
+    },
+    {
+      "id": "structure",
+      "label": "Structure",
+      "description": "Build the cross-file knowledge structure from the summaries.",
+      "contract_type": "workspace-knowledge-structure",
+      "skill_dir": "structure",
+      "reads": [
+        "summaries",
+        "runtime"
+      ],
+      "writes": [
+        "knowledge-entities",
+        "knowledge-claims",
+        "knowledge-indexes"
+      ],
+      "acceptance": {
+        "artifacts_exist": [
+          "knowledge/indexes"
+        ],
+        "state_truthy": [
+          "last_structure",
+          "inventory_complete"
+        ],
+        "state_at_least_counts": {
+          "structured": "summary_total"
+        }
+      }
+    },
+    {
+      "id": "shape",
+      "label": "Shape",
+      "description": "Shape the final workspace around the saved focus and truth checks.",
+      "contract_type": "workspace-query-shape",
+      "skill_dir": "shape",
+      "reads": [
+        "raw",
+        "summaries",
+        "knowledge-entities",
+        "knowledge-claims",
+        "knowledge-indexes",
+        "runtime"
+      ],
+      "writes": [
+        "knowledge-indexes",
+        "home"
+      ],
+      "acceptance": {
+        "artifacts_exist": [
+          "home.md"
+        ],
+        "state_truthy": [
+          "last_shape",
+          "inventory_complete"
+        ],
+        "state_at_least_counts": {
+          "shaped": "summary_total",
+          "compiled": "summary_total"
+        }
+      }
+    }
+  ],
+  "stage_policy_notes": {
+    "summarize": [
+      "Favor conservative, source-grounded summaries that preserve evidence tiers and leave broader synthesis for later stages.",
+      "For large reports or decks, capture scope, headline evidence, and chart/table routing in one light pass.",
+      "As soon as one report summary can state scope, headline metrics, and chart/table routing, stop reading and write the summary batch plus runtime artifacts immediately.",
+      "Keep scratch extraction commands single-purpose and non-destructive."
+    ],
+    "structure": [
+      "Bias structure toward canonical entities, claims, timelines, and stable indexes.",
+      "Use taxonomy and ontology only as means to improve retrieval, navigation, and evidence tracking.",
+      "For small datasets, prefer a minimal stable substrate over exhaustive graph sprawl.",
+      "When you add wikilinks, target real workspace notes by exact basename or explicit relative path. Do not invent title-style links unless that exact title is also a declared note label or alias.",
+      "For summary references, prefer explicit links like `[[summaries/<file-stem>]]` or plain code paths. For knowledge notes, prefer the final filename stem under `knowledge/`."
+    ],
+    "shape": [
+      "Use the workspace focus and saved truth checks to bias the final workspace toward the job it should be especially good at.",
+      "Do not copy expected answers into the final workspace just because the checks imply them.",
+      "If a saved truth check depends on chart-derived or table-derived values, verify the needed evidence in `raw/` while shaping and write focused notes that preserve bounded values plus provenance.",
+      "Prefer better routing, prioritization, and focused navigation over speculative synthesis.",
+      "Any wikilinks you add to `home.md` or indexes must resolve to real workspace note basenames or explicit relative paths."
+    ]
+  }
+}

package/builtin-workflows/interf/workspace.schema.json

@@ -0,0 +1,75 @@
+{
+  "kind": "workspace-schema",
+  "version": 1,
+  "target_type": "workspace",
+  "label": "Interf Compiler (Recommended) workspace schema",
+  "zones": [
+    {
+      "id": "raw",
+      "path": "raw",
+      "kind": "directory",
+      "required": true,
+      "owned_by": [],
+      "description": "Workspace-local raw snapshot copied from the dataset for direct evidence and verification."
+    },
+    {
+      "id": "summaries",
+      "path": "summaries",
+      "kind": "directory",
+      "required": true,
+      "owned_by": [
+        "summarize"
+      ],
+      "description": "Per-file evidence notes produced by file-evidence stages."
+    },
+    {
+      "id": "knowledge-entities",
+      "path": "knowledge/entities",
+      "kind": "directory",
+      "required": true,
+      "owned_by": [
+        "structure"
+      ],
+      "description": "Canonical entity notes produced by knowledge-structure stages."
+    },
+    {
+      "id": "knowledge-claims",
+      "path": "knowledge/claims",
+      "kind": "directory",
+      "required": true,
+      "owned_by": [
+        "structure"
+      ],
+      "description": "Claim notes produced by knowledge-structure stages."
+    },
+    {
+      "id": "knowledge-indexes",
+      "path": "knowledge/indexes",
+      "kind": "directory",
+      "required": true,
+      "owned_by": [
+        "structure",
+        "shape"
+      ],
+      "description": "Retrieval indexes and navigation notes produced by structure and shape stages."
+    },
+    {
+      "id": "home",
+      "path": "home.md",
+      "kind": "file",
+      "required": true,
+      "owned_by": [
+        "shape"
+      ],
+      "description": "Primary entrypoint note for agents using the compiled workspace."
+    },
+    {
+      "id": "runtime",
+      "path": ".interf/runtime",
+      "kind": "runtime",
+      "required": true,
+      "owned_by": [],
+      "description": "CLI-owned runtime state, health, stage contracts, and proof artifacts."
+    }
+  ]
+}

package/dist/bin.d.ts

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
 export {};
-//# sourceMappingURL=bin.d.ts.map

package/dist/bin.js

@@ -27,4 +27,3 @@ yargs(hideBin(process.argv))
     .help()
     .version()
     .parse();
-//# sourceMappingURL=bin.js.map

package/dist/commands/compile-controller.d.ts

@@ -0,0 +1,14 @@
+import type { WorkflowExecutionProfile, WorkflowExecutor } from "../lib/executors.js";
+import type { SourceWorkspaceConfig } from "../lib/schema.js";
+import type { StageShellRetentionMode } from "../lib/workflows.js";
+export declare function runConfiguredWorkspaceCompile(options: {
+    executor: WorkflowExecutor;
+    testExecutor?: WorkflowExecutor | null;
+    workspacePath: string;
+    sourcePath: string;
+    workspaceConfig: SourceWorkspaceConfig | null;
+    executionProfile?: WorkflowExecutionProfile;
+    maxAttemptsOverride: number | null;
+    maxLoopsOverride: number | null;
+    preserveStageShells?: StageShellRetentionMode;
+}): Promise<boolean>;

package/dist/commands/compile-controller.js

@@ -0,0 +1,409 @@
+import { cpSync, existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import chalk from "chalk";
+import { readInterfConfig } from "../lib/interf.js";
+import { resetWorkspaceGeneratedState } from "../lib/workspace-reset.js";
+import { formatActiveWorkspaceWorkflowStageStep, resolveWorkspaceWorkflowFromConfig, } from "../lib/workflow-definitions.js";
+import { resolveWorkspaceCompileMaxAttempts, resolveWorkspaceCompileMaxLoops, } from "../lib/source-config.js";
+import { runWorkflowImprovementLoop } from "../lib/workflow-improvement.js";
+import { stageExecutionShellsRoot, workflowPackagePathForWorkspace, } from "../lib/workspace-paths.js";
+import { compileWorkspaceWithReporter } from "./workspace-flow.js";
+import { printSavedTestOutcome, questionPassRate, runSavedWorkspaceTest, } from "./test-flow.js";
+function printCompileFailure(workspacePath, failedStage) {
+    const workflowId = resolveWorkspaceWorkflowFromConfig(readInterfConfig(workspacePath));
+    const failedStageLabel = formatActiveWorkspaceWorkflowStageStep(workspacePath, workflowId, failedStage ?? "compile");
+    console.log(chalk.red(`  ${failedStageLabel} failed.`));
+}
+function testScore(outcome) {
+    return (outcome.result.passedCases * 1000) + outcome.result.passedChecks;
+}
+const BEST_VARIATION_RESTORE_PATHS = [
+    "AGENTS.md",
+    "CLAUDE.md",
+    "home.md",
+    "summaries",
+    "knowledge",
+    ".claude",
+    ".codex",
+    ".agents",
+    ".cursor",
+    ".obsidian",
+    ".interf/interf.json",
+    ".interf/workflow",
+    ".interf/runtime/state.json",
+    ".interf/runtime/health.json",
+    ".interf/runtime/view-spec.json",
+    ".interf/runtime/inventory.json",
+    ".interf/runtime/run.json",
+    ".interf/runtime/raw-snapshot.json",
+    ".interf/runtime/stage-contract.json",
+    ".interf/runtime/summarize-targets.json",
+];
+function copyRelativePathIfPresent(sourceRoot, targetRoot, relativePath) {
+    const sourcePath = join(sourceRoot, relativePath);
+    if (!existsSync(sourcePath))
+        return;
+    const targetPath = join(targetRoot, relativePath);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    cpSync(sourcePath, targetPath, {
+        recursive: true,
+        force: true,
+        errorOnExist: false,
+    });
+}
+function snapshotWorkspaceBestState(workspacePath) {
+    const snapshotRoot = mkdtempSync(join(tmpdir(), "interf-compile-attempt-"));
+    const snapshotPath = join(snapshotRoot, "workspace");
+    for (const relativePath of BEST_VARIATION_RESTORE_PATHS) {
+        copyRelativePathIfPresent(workspacePath, snapshotPath, relativePath);
+    }
+    return snapshotPath;
+}
+function restoreWorkspaceBestState(snapshotPath, workspacePath) {
+    for (const relativePath of BEST_VARIATION_RESTORE_PATHS) {
+        rmSync(join(workspacePath, relativePath), { recursive: true, force: true });
+        copyRelativePathIfPresent(snapshotPath, workspacePath, relativePath);
+    }
+}
+async function runWorkflowVariation(options) {
+    let bestOutcome = null;
+    let bestSnapshotPath = null;
+    let bestAttempt = 0;
+    let attemptsRun = 0;
+    try {
+        for (let attempt = 1; attempt <= options.maxAttempts; attempt += 1) {
+            attemptsRun = attempt;
+            if (attempt > 1 || (attempt === 1 && options.resetBeforeFirstAttempt)) {
+                console.log();
+                const resetTarget = attempt > 1
+                    ? `attempt ${attempt}/${options.maxAttempts}`
+                    : options.variationLabel;
+                console.log(chalk.dim(`  Resetting generated workspace state before ${resetTarget}...`));
+                resetWorkspaceGeneratedState(options.workspacePath, "compile");
+            }
+            const result = await compileWorkspaceWithReporter(options.executor, options.workspacePath, {
+                heading: options.maxAttempts > 1
+                    ? `Building compiled workspace (${options.variationLabel}, attempt ${attempt}/${options.maxAttempts})...`
+                    : `Building compiled workspace (${options.variationLabel})...`,
+                successMessage: options.maxAttempts > 1
+                    ? `Compiled workspace ready for ${options.variationLabel}, attempt ${attempt}.`
+                    : `Compiled workspace ready for ${options.variationLabel}.`,
+                preserveStageShells: options.preserveStageShells,
+            });
+            if (!result.ok) {
+                printCompileFailure(options.workspacePath, result.failedStage);
+                printStageShellReviewHint(options.workspacePath, options.preserveStageShells);
+                if (attempt < options.maxAttempts) {
+                    console.log(chalk.yellow(`  ${options.variationLabel} attempt ${attempt}/${options.maxAttempts} failed. Retrying with a fresh compile.`));
+                    continue;
+                }
+                return {
+                    passed: false,
+                    attemptsRun,
+                    failedStage: result.failedStage,
+                    bestOutcome,
+                    bestSnapshotPath,
+                    bestAttempt,
+                    fatalError: null,
+                };
+            }
+            const outcome = await runSavedWorkspaceTest({
+                sourcePath: options.sourcePath,
+                workspaceConfig: options.workspaceConfig,
+                executor: options.testExecutor,
+                executionProfile: options.executionProfile,
+                workspacePath: options.workspacePath,
+                preserveSandboxes: options.preserveStageShells === "always" ? "always" : "on-failure",
+            });
+            if (!outcome) {
+                return {
+                    passed: false,
+                    attemptsRun,
+                    failedStage: null,
+                    bestOutcome,
+                    bestSnapshotPath,
+                    bestAttempt,
+                    fatalError: "Could not run the saved workspace test after compile.",
+                };
+            }
+            console.log();
+            printSavedTestOutcome(`${options.variationLabel} · attempt ${attempt}/${options.maxAttempts}`, outcome);
+            if (!bestOutcome || testScore(outcome) > testScore(bestOutcome)) {
+                if (bestSnapshotPath) {
+                    rmSync(bestSnapshotPath, { recursive: true, force: true });
+                }
+                bestOutcome = outcome;
+                bestSnapshotPath = snapshotWorkspaceBestState(options.workspacePath);
+                bestAttempt = attempt;
+            }
+            if (outcome.result.ok) {
+                console.log();
+                console.log(chalk.green(`  Workspace passed on ${options.variationLabel}, attempt ${attempt}/${options.maxAttempts}.`));
+                printStageShellReviewHint(options.workspacePath, options.preserveStageShells);
+                return {
+                    passed: true,
+                    attemptsRun,
+                    failedStage: null,
+                    bestOutcome,
+                    bestSnapshotPath,
+                    bestAttempt,
+                    fatalError: null,
+                };
+            }
+            if (attempt < options.maxAttempts) {
+                console.log();
+                console.log(chalk.yellow(`  ${options.variationLabel} attempt ${attempt}/${options.maxAttempts} did not pass. Retrying with the same workflow.`));
+            }
+        }
+        return {
+            passed: false,
+            attemptsRun,
+            failedStage: null,
+            bestOutcome,
+            bestSnapshotPath,
+            bestAttempt,
+            fatalError: null,
+        };
+    }
+    catch (error) {
+        return {
+            passed: false,
+            attemptsRun,
+            failedStage: null,
+            bestOutcome,
+            bestSnapshotPath,
+            bestAttempt,
+            fatalError: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function summarizeWorkflowVariation(options) {
+    const passedQuestions = options.result.bestOutcome?.result.passedCases ?? 0;
+    const totalQuestions = options.result.bestOutcome?.result.totalCases ?? options.defaultTotalQuestions;
+    const summary = options.result.passed
+        ? `Passed ${passedQuestions}/${totalQuestions} truth checks.`
+        : options.result.bestOutcome
+            ? `Best result: ${passedQuestions}/${totalQuestions} truth checks passed.`
+            : options.result.failedStage
+                ? `Compile failed at stage ${options.result.failedStage} before any test result.`
+                : "Workflow variation did not produce a passing result.";
+    return {
+        variation: options.variation,
+        kind: options.kind,
+        attempts_run: Math.max(1, options.result.attemptsRun),
+        passed: options.result.passed,
+        passed_questions: passedQuestions,
+        total_questions: totalQuestions,
+        ...(options.result.failedStage ? { failed_stage: options.result.failedStage } : {}),
+        ...(options.result.bestOutcome ? { test_run_path: options.result.bestOutcome.runPath } : {}),
+        ...(options.result.bestOutcome?.result.sandbox_path
+            ? { test_sandbox_path: options.result.bestOutcome.result.sandbox_path }
+            : {}),
+        summary,
+    };
+}
+function printStageShellReviewHint(workspacePath, preserveStageShells) {
+    const reviewRoot = stageExecutionShellsRoot(workspacePath);
+    if (preserveStageShells === "always") {
+        console.log(chalk.dim(`  Preserved stage shells: ${reviewRoot}`));
+        return;
+    }
+    console.log(chalk.dim(`  Failed stage shells remain under: ${reviewRoot}`));
+}
+function formatVariationQuestionSummary(summary) {
+    return `${summary.passed_questions}/${summary.total_questions}`;
+}
+function printWorkflowVariationSummary(summaries) {
+    if (summaries.length === 0)
+        return;
+    console.log();
+    console.log(chalk.bold("  Workflow variation summary"));
+    console.log();
+    console.log("  | Variation | Kind | Truth checks | Result |");
+    console.log("  | --- | --- | --- | --- |");
+    for (const summary of summaries) {
+        console.log(`  | ${summary.variation} | ${summary.kind} | \`${formatVariationQuestionSummary(summary)}\` | ${summary.passed ? "pass" : "fail"} |`);
+    }
+}
+function printWorkspaceLocalWorkflowOwnership(workspacePath, bestVariation) {
+    if (bestVariation <= 1)
+        return;
+    console.log();
+    console.log(chalk.dim(`  Best workflow variation now lives in: ${workflowPackagePathForWorkspace(workspacePath)}`));
+    console.log(chalk.dim("  Source-folder workflow selection was not changed automatically."));
+    console.log(chalk.dim("  Recompiling this existing workspace reuses that workspace-local workflow draft."));
+}
+export async function runConfiguredWorkspaceCompile(options) {
+    const preserveStageShells = options.preserveStageShells ?? "on-failure";
+    const configuredMaxAttempts = resolveWorkspaceCompileMaxAttempts(options.workspaceConfig ?? { max_attempts: undefined }, options.maxAttemptsOverride);
+    const maxLoops = resolveWorkspaceCompileMaxLoops(options.workspaceConfig ?? { max_loops: undefined }, options.maxLoopsOverride);
+    const maxAttempts = configuredMaxAttempts ?? (maxLoops != null ? 1 : null);
+    const loopEnabled = maxAttempts != null;
+    const checks = options.workspaceConfig?.checks ?? [];
+    if (loopEnabled && checks.length === 0) {
+        console.log(chalk.yellow("  Retry and self-improving modes need saved truth checks. Building once without those loops."));
+    }
+    else if (loopEnabled) {
+        if (maxAttempts > 1) {
+            console.log(chalk.dim(`  Retry mode: up to ${maxAttempts} compile attempts.`));
+            console.log(chalk.dim("  Interf Compiler will rerun the same workflow variation, test the workspace, and stop early if it passes."));
+        }
+        else {
+            console.log(chalk.dim("  Compile mode: 1 attempt per workflow variation."));
+        }
+        if (maxLoops != null) {
+            console.log(chalk.dim(`  Self-improving loops: up to ${maxLoops} workflow edits after retries fail.`));
+            console.log(chalk.dim("  Interf Compiler will review failed runs, edit the workflow package, and test new workflow variations."));
+        }
+    }
+    if (!loopEnabled || checks.length === 0) {
+        const result = await compileWorkspaceWithReporter(options.executor, options.workspacePath, {
+            preserveStageShells,
+        });
+        if (!result.ok) {
+            process.exitCode = 1;
+            printCompileFailure(options.workspacePath, result.failedStage);
+            printStageShellReviewHint(options.workspacePath, preserveStageShells);
+            return false;
+        }
+        printStageShellReviewHint(options.workspacePath, preserveStageShells);
+        return true;
+    }
+    let bestOutcome = null;
+    let bestSnapshotPath = null;
+    let bestAttempt = 0;
+    let bestVariation = 0;
+    const previousVariations = [];
+    const improvementRunId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+    try {
+        const workspaceConfig = options.workspaceConfig ?? {
+            name: readInterfConfig(options.workspacePath)?.name ?? "workspace",
+            checks: [],
+        };
+        const adoptVariationBest = (variation, result) => {
+            if (result.bestOutcome && result.bestSnapshotPath && (!bestOutcome || testScore(result.bestOutcome) > testScore(bestOutcome))) {
+                if (bestSnapshotPath) {
+                    rmSync(bestSnapshotPath, { recursive: true, force: true });
+                }
+                bestOutcome = result.bestOutcome;
+                bestSnapshotPath = result.bestSnapshotPath;
+                bestAttempt = result.bestAttempt;
+                bestVariation = variation;
+                result.bestSnapshotPath = null;
+            }
+            if (result.bestSnapshotPath) {
+                rmSync(result.bestSnapshotPath, { recursive: true, force: true });
+                result.bestSnapshotPath = null;
+            }
+        };
+        const baseline = await runWorkflowVariation({
+            executor: options.executor,
+            testExecutor: options.testExecutor,
+            workspacePath: options.workspacePath,
+            sourcePath: options.sourcePath,
+            workspaceConfig,
+            executionProfile: options.executionProfile,
+            preserveStageShells,
+            maxAttempts,
+            variationLabel: "baseline workflow",
+        });
+        if (baseline.fatalError) {
+            process.exitCode = 1;
+            console.log(chalk.red(`  ${baseline.fatalError}`));
+            return false;
+        }
+        adoptVariationBest(1, baseline);
+        previousVariations.push(summarizeWorkflowVariation({
+            variation: 1,
+            kind: "baseline",
+            result: baseline,
+            defaultTotalQuestions: checks.length,
+        }));
+        if (baseline.passed) {
+            printWorkflowVariationSummary(previousVariations);
+            return true;
+        }
+        if (maxLoops != null) {
+            for (let loopIndex = 1; loopIndex <= maxLoops; loopIndex += 1) {
+                console.log();
+                console.log(chalk.dim(`  Self-improving loop ${loopIndex}/${maxLoops}: reviewing failed runs and editing the workflow.`));
+                const improvement = await runWorkflowImprovementLoop({
+                    executor: options.executor,
+                    workspacePath: options.workspacePath,
+                    workflowId: resolveWorkspaceWorkflowFromConfig(readInterfConfig(options.workspacePath)),
+                    workspaceConfig,
+                    runId: improvementRunId,
+                    loopIndex,
+                    maxLoops,
+                    maxAttempts,
+                    previousVariations,
+                });
+                console.log(chalk.dim(`  Workflow improvement shell: ${improvement.shellPath}`));
+                if (improvement.status === "executor-failed") {
+                    process.exitCode = 1;
+                    console.log(chalk.red(`  ${improvement.summary}`));
+                    break;
+                }
+                if (improvement.status !== "updated") {
+                    console.log(chalk.yellow(`  ${improvement.summary}`));
+                    continue;
+                }
+                const variation = await runWorkflowVariation({
+                    executor: options.executor,
+                    testExecutor: options.testExecutor,
+                    workspacePath: options.workspacePath,
+                    sourcePath: options.sourcePath,
+                    workspaceConfig,
+                    executionProfile: options.executionProfile,
+                    preserveStageShells,
+                    maxAttempts,
+                    variationLabel: `workflow variation ${loopIndex + 1}`,
+                    resetBeforeFirstAttempt: true,
+                });
+                if (variation.fatalError) {
+                    process.exitCode = 1;
+                    console.log(chalk.red(`  ${variation.fatalError}`));
+                    return false;
+                }
+                adoptVariationBest(loopIndex + 1, variation);
+                previousVariations.push(summarizeWorkflowVariation({
+                    variation: loopIndex + 1,
+                    kind: "edited",
+                    result: variation,
+                    defaultTotalQuestions: checks.length,
+                }));
+                if (variation.passed) {
+                    printWorkflowVariationSummary(previousVariations);
+                    printWorkspaceLocalWorkflowOwnership(options.workspacePath, bestVariation);
+                    return true;
+                }
+            }
+        }
+        if (bestSnapshotPath && bestVariation > 0) {
+            restoreWorkspaceBestState(bestSnapshotPath, options.workspacePath);
+            console.log();
+            console.log(chalk.dim(`  Restored the best-performing compiled workspace from variation ${bestVariation}, attempt ${bestAttempt}.`));
+        }
+        process.exitCode = 1;
+        console.log();
+        printWorkflowVariationSummary(previousVariations);
+        printWorkspaceLocalWorkflowOwnership(options.workspacePath, bestVariation);
+        if (maxLoops != null) {
+            console.log(chalk.red(`  Workspace did not pass after ${maxAttempts} attempt${maxAttempts === 1 ? "" : "s"} per variation and ${maxLoops} workflow-improvement loop${maxLoops === 1 ? "" : "s"}.`));
+        }
+        else {
+            console.log(chalk.red(`  Workspace did not pass within ${maxAttempts} attempt${maxAttempts === 1 ? "" : "s"}.`));
+        }
+        if (bestOutcome) {
+            console.log(chalk.dim(`  Best attempt truth-check pass rate: ${questionPassRate(bestOutcome)}%.`));
+        }
+        printStageShellReviewHint(options.workspacePath, preserveStageShells);
+        return false;
+    }
+    finally {
+        if (bestSnapshotPath) {
+            rmSync(bestSnapshotPath, { recursive: true, force: true });
+        }
+    }
+}