agentweaver 0.1.18 → 0.1.20

package/dist/pipeline/auto-flow-resolver.js

@@ -0,0 +1,830 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { flowConfigYamlFile, resolvedFlowJsonFile, resolvedFlowSummaryJsonFile, } from "../artifacts.js";
+import { TaskRunnerError } from "../errors.js";
+import { getBuiltInAutoFlowBlockDefinition } from "./auto-flow-blocks.js";
+import { getBuiltInAutoFlowPreset, getBuiltInAutoFlowPresetByFileName, } from "./auto-flow-presets.js";
+import { AUTO_FLOW_SLOT_NAMES, loadAutoFlowConfigByName, normalizeAutoFlowConfigYaml, } from "./auto-flow-config.js";
+import { AUTO_FLOW_SLOT_IDS, } from "./auto-flow-types.js";
+import { loadDeclarativeFlowFromSpec, resolveNamedDeclarativeFlowRef, } from "./declarative-flows.js";
+import { loadBuiltInFlowSpecSync, loadFlowSpecSync } from "./spec-loader.js";
+const BLOCK_REGISTRY = {
+    "review.design-loop": {
+        label: "design-review loop",
+        defaultMaxIterations: 3,
+        builtInFlowFileName: "design-review-loop.json",
+        builtInSpecName: "design-review-loop.json",
+    },
+    "checks.go.linter": {
+        label: "Go linter loop",
+        defaultMaxIterations: 5,
+        builtInFlowFileName: "run-go-linter-loop.json",
+        builtInSpecName: "run-go-linter-loop.json",
+    },
+    "checks.go.tests": {
+        label: "Go tests loop",
+        defaultMaxIterations: 5,
+        builtInFlowFileName: "run-go-tests-loop.json",
+        builtInSpecName: "run-go-tests-loop.json",
+    },
+    "review.loop": {
+        label: "review loop",
+        defaultMaxIterations: 5,
+        builtInFlowFileName: "review-loop.json",
+        builtInSpecName: "review-loop.json",
+    },
+};
+const DEFAULT_BLOCKS = {
+    simple: {
+        designReview: [],
+        postImplementationChecks: [],
+        review: ["review.loop"],
+        final: [],
+    },
+    standard: {
+        designReview: ["review.design-loop"],
+        postImplementationChecks: [],
+        review: ["review.loop"],
+        final: [],
+    },
+};
+const slotOrder = new Map(AUTO_FLOW_SLOT_IDS.map((slot, index) => [slot, index]));
+function selectedCommandForPreset(preset) {
+    return preset === "standard" ? "auto-common" : "auto-simple";
+}
+function builtInSpecFileForPreset(preset) {
+    return preset === "standard" ? "auto-common.json" : "auto-simple.json";
+}
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function stableJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableJson(item)).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function isAutoFlowSlotId(value) {
+    return AUTO_FLOW_SLOT_IDS.includes(value);
+}
+function createSummary(presetId) {
+    return {
+        presetId,
+        enabled: [],
+        disabled: [],
+        skipped: [],
+        autoDisabled: [],
+        invalid: [],
+    };
+}
+function addDiagnostic(diagnostics, code, message, details = {}) {
+    diagnostics.push({ code, message, ...details });
+}
+function decisionFromDiagnostic(diagnostic) {
+    const decision = {
+        status: "invalid",
+        blockId: diagnostic.blockId ?? "flow",
+        reason: diagnostic.message,
+        diagnosticCode: diagnostic.code,
+    };
+    if (diagnostic.slotId && isAutoFlowSlotId(diagnostic.slotId)) {
+        decision.slotId = diagnostic.slotId;
+    }
+    return decision;
+}
+function defaultParamsForPlacement(placement) {
+    const definition = getBuiltInAutoFlowBlockDefinition(placement.blockId);
+    const params = {};
+    if (definition?.params) {
+        for (const [name, paramDefinition] of Object.entries(definition.params)) {
+            params[name] = paramDefinition.default;
+        }
+    }
+    return {
+        ...params,
+        ...(placement.params ?? {}),
+    };
+}
+function workingPlacementsForPreset(preset, override) {
+    const sourcePlacements = override?.placements ?? preset.blocks;
+    return sourcePlacements.map((placement, index) => {
+        const presetPlacement = preset.blocks.find((candidate) => candidate.blockId === placement.blockId);
+        const defaultParams = presetPlacement ? defaultParamsForPlacement(presetPlacement) : {};
+        return {
+            blockId: placement.blockId,
+            slot: placement.slot,
+            enabled: "enabled" in placement ? placement.enabled !== false : true,
+            params: {
+                ...defaultParams,
+                ...(placement.params ?? {}),
+                ...(override?.blockParams?.[placement.blockId] ?? {}),
+            },
+            index,
+        };
+    });
+}
+function sortedPlacements(placements) {
+    return [...placements].sort((left, right) => {
+        const leftSlot = slotOrder.get(left.slot) ?? Number.MAX_SAFE_INTEGER;
+        const rightSlot = slotOrder.get(right.slot) ?? Number.MAX_SAFE_INTEGER;
+        if (leftSlot !== rightSlot) {
+            return leftSlot - rightSlot;
+        }
+        return left.index - right.index;
+    });
+}
+function validateDisabledBlocks(preset, placements, disabledBlocks, summary, diagnostics) {
+    const activePlacements = [];
+    for (const placement of placements) {
+        const definition = getBuiltInAutoFlowBlockDefinition(placement.blockId);
+        if (!definition) {
+            addDiagnostic(diagnostics, "unknown-block", `Unknown auto-flow block '${placement.blockId}'.`, { blockId: placement.blockId });
+            continue;
+        }
+        const disabled = disabledBlocks.has(placement.blockId) || !placement.enabled;
+        if (!disabled) {
+            activePlacements.push(placement);
+            continue;
+        }
+        if (definition.locked || preset.blocks.some((candidate) => candidate.blockId === placement.blockId && candidate.locked)) {
+            continue;
+        }
+        summary.disabled.push({
+            status: "disabled",
+            blockId: placement.blockId,
+            ...(isAutoFlowSlotId(placement.slot) ? { slotId: placement.slot } : {}),
+            reason: `Optional block '${placement.blockId}' was explicitly disabled.`,
+        });
+    }
+    for (const blockId of disabledBlocks) {
+        const definition = getBuiltInAutoFlowBlockDefinition(blockId);
+        if (!definition) {
+            addDiagnostic(diagnostics, "unknown-block", `Unknown auto-flow block '${blockId}' cannot be disabled.`, { blockId });
+            continue;
+        }
+        if (definition.locked
+            && !placements.some((placement) => placement.blockId === blockId && disabledBlocks.has(placement.blockId))) {
+            addDiagnostic(diagnostics, "locked-block-disabled", `Locked auto-flow block '${blockId}' cannot be disabled.`, { blockId });
+        }
+    }
+    return activePlacements;
+}
+function validateLockedPresetBlocks(preset, placements, disabledBlocks, diagnostics) {
+    for (const presetPlacement of preset.blocks) {
+        const definition = getBuiltInAutoFlowBlockDefinition(presetPlacement.blockId);
+        if (!definition?.locked && !presetPlacement.locked) {
+            continue;
+        }
+        const matchingPlacement = placements.find((placement) => placement.blockId === presetPlacement.blockId);
+        if (!matchingPlacement) {
+            addDiagnostic(diagnostics, "locked-block-removed", `Locked auto-flow block '${presetPlacement.blockId}' cannot be removed.`, { blockId: presetPlacement.blockId, slotId: presetPlacement.slot });
+            continue;
+        }
+        if (!matchingPlacement.enabled || disabledBlocks.has(matchingPlacement.blockId)) {
+            addDiagnostic(diagnostics, "locked-block-disabled", `Locked auto-flow block '${presetPlacement.blockId}' cannot be disabled.`, { blockId: presetPlacement.blockId, slotId: matchingPlacement.slot });
+        }
+    }
+}
+function validatePlacements(placements, diagnostics) {
+    const seen = new Set();
+    for (const placement of placements) {
+        const definition = getBuiltInAutoFlowBlockDefinition(placement.blockId);
+        if (!definition) {
+            continue;
+        }
+        if (seen.has(placement.blockId)) {
+            addDiagnostic(diagnostics, "duplicate-block", `Auto-flow block '${placement.blockId}' is placed more than once.`, { blockId: placement.blockId, slotId: placement.slot });
+        }
+        seen.add(placement.blockId);
+        if (!definition.allowedSlots.includes(placement.slot)) {
+            addDiagnostic(diagnostics, "invalid-slot", `Auto-flow block '${placement.blockId}' cannot be placed in slot '${placement.slot}'. Allowed slots: ${definition.allowedSlots.join(", ")}.`, {
+                blockId: placement.blockId,
+                slotId: placement.slot,
+                allowedSlots: definition.allowedSlots,
+            });
+        }
+    }
+}
+function formatValue(value) {
+    if (typeof value === "string") {
+        return `'${value}'`;
+    }
+    return JSON.stringify(value);
+}
+function fingerprint(value) {
+    return `sha256:${createHash("sha256").update(stableJson(value)).digest("hex")}`;
+}
+function defaultConfigForPreset(preset) {
+    return {
+        kind: "auto-flow-config",
+        version: 1,
+        name: `preset-${preset}`,
+        basePreset: preset,
+    };
+}
+function sourceForPreset(preset) {
+    return { type: "preset", preset };
+}
+function sourceForLoadedConfig(loaded) {
+    return {
+        type: loaded.source.type === "project" ? "project-config" : "user-config",
+        configName: loaded.config.name,
+        path: loaded.source.path,
+        ...(loaded.source.shadowedUserPath ? { shadowedUserPath: loaded.source.shadowedUserPath } : {}),
+    };
+}
+function resolveSlot(preset, config, slot) {
+    const defaults = DEFAULT_BLOCKS[preset][slot];
+    const override = config.slots?.[slot];
+    const configuredBlocks = override?.blocks;
+    const rawBlocks = configuredBlocks ?? defaults.map((id) => ({ id, enabled: "auto" }));
+    const decisions = [];
+    for (const block of rawBlocks) {
+        const registry = BLOCK_REGISTRY[block.id];
+        const enabled = block.enabled ?? "auto";
+        const included = enabled !== false;
+        const maxIterations = block.maxIterations ?? registry.defaultMaxIterations;
+        decisions.push({
+            slot,
+            blockId: block.id,
+            enabled,
+            included,
+            reason: included
+                ? configuredBlocks
+                    ? "included by saved config"
+                    : "included by preset default"
+                : "disabled by saved config",
+            ...(maxIterations !== undefined ? { maxIterations } : {}),
+            ...(registry.defaultMaxIterations !== undefined ? { defaultMaxIterations: registry.defaultMaxIterations } : {}),
+            ...(registry.builtInFlowFileName ? { flowFileName: registry.builtInFlowFileName } : {}),
+        });
+    }
+    if (configuredBlocks) {
+        const configuredIds = new Set(configuredBlocks.map((block) => block.id));
+        for (const defaultBlockId of defaults) {
+            if (configuredIds.has(defaultBlockId)) {
+                continue;
+            }
+            const registry = BLOCK_REGISTRY[defaultBlockId];
+            decisions.push({
+                slot,
+                blockId: defaultBlockId,
+                enabled: false,
+                included: false,
+                reason: "skipped because the slot override omitted this preset default block",
+                ...(registry.defaultMaxIterations !== undefined ? { defaultMaxIterations: registry.defaultMaxIterations } : {}),
+                ...(registry.defaultMaxIterations !== undefined ? { maxIterations: registry.defaultMaxIterations } : {}),
+                ...(registry.builtInFlowFileName ? { flowFileName: registry.builtInFlowFileName } : {}),
+            });
+        }
+    }
+    return {
+        decisions,
+        included: decisions.filter((decision) => decision.included),
+    };
+}
+function resolveAllSlots(config) {
+    const includedBySlot = {
+        designReview: [],
+        postImplementationChecks: [],
+        review: [],
+        final: [],
+    };
+    const decisions = [];
+    for (const slot of AUTO_FLOW_SLOT_NAMES) {
+        const resolution = resolveSlot(config.basePreset, config, slot);
+        decisions.push(...resolution.decisions);
+        includedBySlot[slot] = resolution.included;
+    }
+    return { decisions, includedBySlot };
+}
+function usesBuiltInShape(preset, includedBySlot) {
+    for (const slot of AUTO_FLOW_SLOT_NAMES) {
+        const defaults = DEFAULT_BLOCKS[preset][slot];
+        const included = includedBySlot[slot];
+        if (included.length !== defaults.length) {
+            return false;
+        }
+        for (let index = 0; index < defaults.length; index += 1) {
+            const decision = included[index];
+            if (!decision || decision.blockId !== defaults[index]) {
+                return false;
+            }
+            const defaultMax = BLOCK_REGISTRY[decision.blockId].defaultMaxIterations;
+            if (decision.maxIterations !== undefined && defaultMax !== undefined && decision.maxIterations !== defaultMax) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+function builtInPhase(spec, id) {
+    const phase = spec.phases.find((item) => !("repeat" in item) && item.id === id);
+    if (!phase) {
+        throw new TaskRunnerError(`Built-in auto flow phase '${id}' was not found.`);
+    }
+    return cloneJson(phase);
+}
+function phaseLabel(id) {
+    switch (id) {
+        case "source":
+            return "source";
+        case "normalize":
+            return "normalize";
+        case "plan":
+            return "planning";
+        case "design_review_loop":
+            return "design review";
+        case "implement":
+            return "implementation";
+        case "review-loop":
+            return "review";
+        case "post_go_linter_loop":
+            return "post-implementation Go linter";
+        case "post_go_tests_loop":
+            return "post-implementation Go tests";
+        case "final_go_linter_loop":
+            return "final Go linter";
+        case "final_go_tests_loop":
+            return "final Go tests";
+        default:
+            return id;
+    }
+}
+function resolvedPhase(id, decision) {
+    return {
+        id,
+        label: phaseLabel(id),
+        ...(decision ? { blockId: decision.blockId, slot: decision.slot } : {}),
+    };
+}
+function setFirstFlowRunFileName(phase, fileName) {
+    const next = cloneJson(phase);
+    const step = next.steps.find((candidate) => candidate.node === "flow-run");
+    if (!step) {
+        throw new TaskRunnerError(`Phase '${phase.id}' does not contain a flow-run step.`);
+    }
+    step.params = {
+        ...(step.params ?? {}),
+        fileName: { const: fileName },
+    };
+    return next;
+}
+function valueRef(ref) {
+    return { ref };
+}
+function valueConst(value) {
+    return { const: value };
+}
+function checkPhaseId(slot, blockId) {
+    const prefix = slot === "final" ? "final" : "post";
+    if (blockId === "checks.go.linter") {
+        return `${prefix}_go_linter_loop`;
+    }
+    if (blockId === "checks.go.tests") {
+        return `${prefix}_go_tests_loop`;
+    }
+    throw new TaskRunnerError(`Block '${blockId}' cannot be rendered as a check phase.`);
+}
+function checkPhase(decision, fileName) {
+    const isLinter = decision.blockId === "checks.go.linter";
+    return {
+        id: checkPhaseId(decision.slot, decision.blockId),
+        steps: [
+            {
+                id: isLinter ? "run_go_linter_loop" : "run_go_tests_loop",
+                node: "flow-run",
+                params: {
+                    fileName: valueConst(fileName),
+                    labelText: valueConst(isLinter ? "Running Go linter loop" : "Running Go tests loop"),
+                    taskKey: valueRef("params.taskKey"),
+                    workspaceDir: valueRef("params.workspaceDir"),
+                    extraPrompt: valueRef("params.extraPrompt"),
+                    llmExecutor: valueRef("params.llmExecutor"),
+                    llmModel: valueRef("params.llmModel"),
+                    ...(isLinter
+                        ? {
+                            runGoLinterScript: valueRef("params.runGoLinterScript"),
+                            runGoLinterIteration: valueRef("params.runGoLinterIteration"),
+                        }
+                        : {
+                            runGoTestsScript: valueRef("params.runGoTestsScript"),
+                            runGoTestsIteration: valueRef("params.runGoTestsIteration"),
+                        }),
+                },
+            },
+        ],
+    };
+}
+function replaceOldMax(value, oldMax, newMax) {
+    if (Array.isArray(value)) {
+        return value.map((item) => replaceOldMax(item, oldMax, newMax));
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            replaceOldMax(item, oldMax, newMax),
+        ]));
+    }
+    if (typeof value === "number" && value === oldMax) {
+        return newMax;
+    }
+    if (typeof value === "string") {
+        return value
+            .replaceAll(String(oldMax), String(newMax))
+            .replaceAll(`_${oldMax}`, `_${newMax}`);
+    }
+    return value;
+}
+function isRepeatPhase(item) {
+    return "repeat" in item;
+}
+function withMaxIterations(spec, oldMax, newMax) {
+    if (newMax === oldMax) {
+        return cloneJson(spec);
+    }
+    const next = replaceOldMax(cloneJson(spec), oldMax, newMax);
+    const phases = [];
+    for (const item of next.phases) {
+        if (!isRepeatPhase(item)) {
+            phases.push(item);
+            continue;
+        }
+        if (item.repeat.to !== newMax) {
+            phases.push(item);
+            continue;
+        }
+        if (newMax < item.repeat.from) {
+            continue;
+        }
+        phases.push(item);
+    }
+    next.phases = phases;
+    return next;
+}
+function loadNamedBuiltInSpec(name, cwd) {
+    const ref = resolveNamedDeclarativeFlowRef(name, cwd);
+    return ref.source === "built-in"
+        ? loadFlowSpecSync({ source: "built-in", fileName: ref.fileName })
+        : loadFlowSpecSync(ref);
+}
+function generatedNestedFileName(blockId, maxIterations) {
+    return `generated-${blockId.replaceAll(".", "-")}-${maxIterations}.json`;
+}
+async function resolveNestedFlowName(decision, cwd, inMemoryFlows, nestedFlowSpecs) {
+    const registry = BLOCK_REGISTRY[decision.blockId];
+    if (!registry.builtInFlowFileName || !registry.builtInSpecName || !registry.defaultMaxIterations) {
+        throw new TaskRunnerError(`Block '${decision.blockId}' does not have a runnable flow template.`);
+    }
+    const maxIterations = decision.maxIterations ?? registry.defaultMaxIterations;
+    if (maxIterations === registry.defaultMaxIterations) {
+        return registry.builtInFlowFileName;
+    }
+    const fileName = generatedNestedFileName(decision.blockId, maxIterations);
+    if (!inMemoryFlows[fileName]) {
+        const baseSpec = loadNamedBuiltInSpec(registry.builtInSpecName, cwd);
+        const generatedSpec = withMaxIterations(baseSpec, registry.defaultMaxIterations, maxIterations);
+        nestedFlowSpecs[fileName] = generatedSpec;
+        inMemoryFlows[fileName] = await loadDeclarativeFlowFromSpec(generatedSpec, { fileName }, {
+            cwd,
+            inMemoryFlows,
+        });
+    }
+    return fileName;
+}
+async function buildGeneratedFlow(config, includedBySlot, cwd) {
+    const baseSpec = loadBuiltInFlowSpecSync(builtInSpecFileForPreset(config.basePreset));
+    const commonSpec = loadBuiltInFlowSpecSync("auto-common.json");
+    const phases = [
+        builtInPhase(baseSpec, "source"),
+        builtInPhase(baseSpec, "normalize"),
+        builtInPhase(baseSpec, "plan"),
+    ];
+    const resolvedPhases = [
+        resolvedPhase("source"),
+        resolvedPhase("normalize"),
+        resolvedPhase("plan"),
+    ];
+    const inMemoryFlows = {};
+    const nestedFlowSpecs = {};
+    for (const decision of includedBySlot.designReview) {
+        if (decision.blockId !== "review.design-loop") {
+            continue;
+        }
+        const fileName = await resolveNestedFlowName(decision, cwd, inMemoryFlows, nestedFlowSpecs);
+        phases.push(setFirstFlowRunFileName(builtInPhase(commonSpec, "design_review_loop"), fileName));
+        resolvedPhases.push(resolvedPhase("design_review_loop", decision));
+    }
+    phases.push(builtInPhase(baseSpec, "implement"));
+    resolvedPhases.push(resolvedPhase("implement"));
+    for (const decision of includedBySlot.postImplementationChecks) {
+        if (decision.blockId !== "checks.go.linter" && decision.blockId !== "checks.go.tests") {
+            continue;
+        }
+        const fileName = await resolveNestedFlowName(decision, cwd, inMemoryFlows, nestedFlowSpecs);
+        phases.push(checkPhase(decision, fileName));
+        resolvedPhases.push(resolvedPhase(checkPhaseId(decision.slot, decision.blockId), decision));
+    }
+    for (const decision of includedBySlot.review) {
+        if (decision.blockId !== "review.loop") {
+            continue;
+        }
+        const fileName = await resolveNestedFlowName(decision, cwd, inMemoryFlows, nestedFlowSpecs);
+        phases.push(setFirstFlowRunFileName(builtInPhase(baseSpec, "review-loop"), fileName));
+        resolvedPhases.push(resolvedPhase("review-loop", decision));
+    }
+    for (const decision of includedBySlot.final) {
+        if (decision.blockId !== "checks.go.linter" && decision.blockId !== "checks.go.tests") {
+            continue;
+        }
+        const fileName = await resolveNestedFlowName(decision, cwd, inMemoryFlows, nestedFlowSpecs);
+        phases.push(checkPhase(decision, fileName));
+        resolvedPhases.push(resolvedPhase(checkPhaseId(decision.slot, decision.blockId), decision));
+    }
+    const flowSpec = {
+        kind: "auto-flow",
+        version: 1,
+        description: `Generated configurable auto flow from the ${config.basePreset} preset.`,
+        phases,
+    };
+    const flow = await loadDeclarativeFlowFromSpec(flowSpec, { fileName: "resolved-auto-flow.json" }, {
+        cwd,
+        inMemoryFlows,
+    });
+    return { flow, inMemoryFlows, flowSpec, nestedFlowSpecs, phases: resolvedPhases };
+}
+function artifactPolicy(scopeKey) {
+    return {
+        dryRunFlowWritesArtifacts: false,
+        nonDryRunWritesArtifacts: true,
+        ...(scopeKey
+            ? {
+                artifactPaths: {
+                    flowConfigYaml: flowConfigYamlFile(scopeKey),
+                    resolvedFlowJson: resolvedFlowJsonFile(scopeKey),
+                    resolvedFlowSummaryJson: resolvedFlowSummaryJsonFile(scopeKey),
+                },
+            }
+            : {}),
+    };
+}
+function buildSummary(document) {
+    return {
+        schemaVersion: 1,
+        source: document.source,
+        basePreset: document.basePreset,
+        selectedCommand: document.selectedCommand,
+        phaseOrder: document.phases.map((phase) => phase.label),
+        includedBlocks: document.blockDecisions.filter((decision) => decision.included),
+        skippedBlocks: document.blockDecisions.filter((decision) => !decision.included),
+        executionTarget: document.executionTarget.kind,
+        artifactPolicy: document.artifactPolicy,
+        fingerprint: document.fingerprint,
+    };
+}
+export async function resolveAutoFlow(selection, options = {}) {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const loadedConfig = selection.kind === "config" ? loadAutoFlowConfigByName(selection.name, cwd) : null;
+    const config = loadedConfig?.config ?? defaultConfigForPreset(selection.kind === "preset" ? selection.preset : "standard");
+    const normalizedConfigYaml = loadedConfig?.normalizedYaml ?? normalizeAutoFlowConfigYaml(config);
+    const source = loadedConfig ? sourceForLoadedConfig(loadedConfig) : sourceForPreset(config.basePreset);
+    const selectedCommand = selectedCommandForPreset(config.basePreset);
+    const { decisions, includedBySlot } = resolveAllSlots(config);
+    const policy = artifactPolicy(options.scopeKey);
+    let execution;
+    let phases;
+    let executionTarget;
+    if (usesBuiltInShape(config.basePreset, includedBySlot)) {
+        const specFile = builtInSpecFileForPreset(config.basePreset);
+        phases = config.basePreset === "standard"
+            ? [
+                resolvedPhase("source"),
+                resolvedPhase("normalize"),
+                resolvedPhase("plan"),
+                resolvedPhase("design_review_loop", includedBySlot.designReview[0]),
+                resolvedPhase("implement"),
+                resolvedPhase("review-loop", includedBySlot.review[0]),
+            ]
+            : [
+                resolvedPhase("source"),
+                resolvedPhase("normalize"),
+                resolvedPhase("plan"),
+                resolvedPhase("implement"),
+                resolvedPhase("review-loop", includedBySlot.review[0]),
+            ];
+        execution = { kind: "built-in", specFile };
+        executionTarget = { kind: "built-in", specFile };
+    }
+    else {
+        const generated = await buildGeneratedFlow(config, includedBySlot, cwd);
+        phases = generated.phases;
+        execution = {
+            kind: "generated",
+            flow: generated.flow,
+            inMemoryFlows: generated.inMemoryFlows,
+        };
+        executionTarget = {
+            kind: "generated",
+            fileName: generated.flow.fileName,
+            nestedFlowFiles: Object.keys(generated.inMemoryFlows).sort((left, right) => left.localeCompare(right)),
+            flowSpec: generated.flowSpec,
+            nestedFlowSpecs: Object.fromEntries(Object.entries(generated.nestedFlowSpecs).sort(([left], [right]) => left.localeCompare(right))),
+        };
+    }
+    const documentWithoutFingerprint = {
+        schemaVersion: 1,
+        source,
+        requested: selection,
+        basePreset: config.basePreset,
+        selectedCommand,
+        phases,
+        blockDecisions: decisions,
+        artifactPolicy: policy,
+        executionTarget,
+        validationDiagnostics: [],
+    };
+    const document = {
+        ...documentWithoutFingerprint,
+        fingerprint: fingerprint(documentWithoutFingerprint),
+    };
+    return {
+        config,
+        normalizedConfigYaml,
+        document,
+        summary: buildSummary(document),
+        execution,
+    };
+}
+export function formatAutoFlowDryRunPreview(resolved) {
+    const lines = [
+        "Auto flow dry-run preview",
+        `Source: ${resolved.document.source.type}`,
+    ];
+    if (resolved.document.source.type === "preset") {
+        lines.push(`Preset: ${resolved.document.source.preset}`);
+    }
+    else {
+        lines.push(`Config: ${resolved.document.source.configName}`);
+        lines.push(`Config path: ${resolved.document.source.path}`);
+        if (resolved.document.source.shadowedUserPath) {
+            lines.push(`Precedence: project config selected; user config shadowed at ${resolved.document.source.shadowedUserPath}`);
+        }
+    }
+    lines.push(`Base preset: ${resolved.document.basePreset}`);
+    lines.push(`Execution target: ${resolved.document.executionTarget.kind}`);
+    lines.push("", "Phases:");
+    resolved.document.phases.forEach((phase, index) => {
+        lines.push(`  ${index + 1}. ${phase.label} (${phase.id})`);
+    });
+    lines.push("", "Blocks:");
+    for (const decision of resolved.document.blockDecisions) {
+        const state = decision.included ? "included" : "skipped";
+        const iterationText = decision.maxIterations ? `, maxIterations=${decision.maxIterations}` : "";
+        lines.push(`  - ${decision.slot}/${decision.blockId}: ${state} (${decision.reason}${iterationText})`);
+    }
+    lines.push("", "Artifact policy:", "  - --dry-run-flow writes no resolver artifacts.", "  - Non-dry configurable auto runs write flow-config.yaml, resolved-flow.json, and resolved-flow-summary.json.", "", "No workflow steps were run.");
+    return `${lines.join("\n")}\n`;
+}
+function writeTextAtomic(filePath, content) {
+    mkdirSync(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tempPath, content, "utf8");
+    renameSync(tempPath, filePath);
+}
+export function persistResolvedAutoFlowArtifacts(scopeKey, resolved) {
+    writeTextAtomic(flowConfigYamlFile(scopeKey), resolved.normalizedConfigYaml);
+    writeTextAtomic(resolvedFlowJsonFile(scopeKey), `${JSON.stringify(resolved.document, null, 2)}\n`);
+    writeTextAtomic(resolvedFlowSummaryJsonFile(scopeKey), `${JSON.stringify(resolved.summary, null, 2)}\n`);
+}
+function validateParameters(placements, diagnostics) {
+    for (const placement of placements) {
+        const definition = getBuiltInAutoFlowBlockDefinition(placement.blockId);
+        if (!definition) {
+            continue;
+        }
+        const paramDefinitions = definition.params ?? {};
+        for (const paramName of Object.keys(placement.params)) {
+            if (!paramDefinitions[paramName]) {
+                addDiagnostic(diagnostics, "unknown-parameter", `Auto-flow block '${placement.blockId}' does not support parameter '${paramName}'.`, { blockId: placement.blockId, slotId: placement.slot, paramName });
+            }
+        }
+        for (const [paramName, paramDefinition] of Object.entries(paramDefinitions)) {
+            const value = Object.prototype.hasOwnProperty.call(placement.params, paramName)
+                ? placement.params[paramName]
+                : paramDefinition.default;
+            if (!Number.isInteger(value)) {
+                addDiagnostic(diagnostics, "invalid-parameter-type", `Auto-flow block '${placement.blockId}' parameter '${paramName}' must be an integer; received ${formatValue(value)}.`, { blockId: placement.blockId, slotId: placement.slot, paramName, value });
+                continue;
+            }
+            const numericValue = value;
+            if (numericValue < paramDefinition.min || numericValue > paramDefinition.max) {
+                addDiagnostic(diagnostics, "parameter-out-of-range", `Auto-flow block '${placement.blockId}' parameter '${paramName}' must be between ${paramDefinition.min} and ${paramDefinition.max}; received ${numericValue}.`, { blockId: placement.blockId, slotId: placement.slot, paramName, value: numericValue });
+                continue;
+            }
+            if (!paramDefinition.supportedExecutableValues.includes(numericValue)) {
+                addDiagnostic(diagnostics, "unsupported-override", `Auto-flow block '${placement.blockId}' parameter '${paramName}' value ${numericValue} is not executable in this implementation; supported executable values: ${paramDefinition.supportedExecutableValues.join(", ")}.`, { blockId: placement.blockId, slotId: placement.slot, paramName, value: numericValue });
+            }
+        }
+    }
+}
+function validateOverrideBlockParams(override, diagnostics) {
+    if (!override?.blockParams) {
+        return;
+    }
+    for (const blockId of Object.keys(override.blockParams)) {
+        if (!getBuiltInAutoFlowBlockDefinition(blockId)) {
+            addDiagnostic(diagnostics, "unknown-block", `Unknown auto-flow block '${blockId}' has parameter overrides.`, { blockId });
+        }
+    }
+}
+function validateDependencies(placements, diagnostics) {
+    const provided = new Set();
+    for (const placement of sortedPlacements(placements)) {
+        const definition = getBuiltInAutoFlowBlockDefinition(placement.blockId);
+        if (!definition) {
+            continue;
+        }
+        const missing = definition.requires.filter((contract) => !provided.has(contract));
+        for (const contract of missing) {
+            addDiagnostic(diagnostics, "missing-dependency", `Auto-flow block '${placement.blockId}' requires contract '${contract}' before slot '${placement.slot}'.`, {
+                blockId: placement.blockId,
+                slotId: placement.slot,
+                missingContract: contract,
+            });
+        }
+        if (missing.length === 0) {
+            for (const contract of definition.provides) {
+                provided.add(contract);
+            }
+        }
+    }
+}
+function buildSpec(preset, placements) {
+    return {
+        kind: preset.kind,
+        version: preset.version,
+        description: preset.description,
+        phases: sortedPlacements(placements).map((placement) => {
+            const definition = getBuiltInAutoFlowBlockDefinition(placement.blockId);
+            if (!definition || !isAutoFlowSlotId(placement.slot)) {
+                throw new TaskRunnerError(`Cannot generate phase for invalid auto-flow block '${placement.blockId}'.`);
+            }
+            return definition.createPhase({
+                presetId: preset.id,
+                blockId: placement.blockId,
+                slotId: placement.slot,
+                params: placement.params,
+            });
+        }),
+    };
+}
+export function resolveAutoFlowPreset(presetOrId, override) {
+    const preset = typeof presetOrId === "string" ? getBuiltInAutoFlowPreset(presetOrId) : presetOrId;
+    const summary = createSummary(preset.id);
+    const diagnostics = [];
+    const disabledBlocks = new Set(override?.disabledBlocks ?? []);
+    const placements = workingPlacementsForPreset(preset, override);
+    validateOverrideBlockParams(override, diagnostics);
+    validateLockedPresetBlocks(preset, placements, disabledBlocks, diagnostics);
+    const activePlacements = validateDisabledBlocks(preset, placements, disabledBlocks, summary, diagnostics);
+    validatePlacements(activePlacements, diagnostics);
+    validateParameters(activePlacements, diagnostics);
+    validateDependencies(activePlacements, diagnostics);
+    summary.invalid.push(...diagnostics.map(decisionFromDiagnostic));
+    if (diagnostics.length > 0) {
+        return { preset, summary, diagnostics };
+    }
+    for (const placement of sortedPlacements(activePlacements)) {
+        summary.enabled.push({
+            status: "enabled",
+            blockId: placement.blockId,
+            slotId: placement.slot,
+            reason: `Block '${placement.blockId}' is enabled.`,
+        });
+    }
+    return {
+        preset,
+        summary,
+        diagnostics,
+        spec: buildSpec(preset, activePlacements),
+    };
+}
+export function resolveBuiltInAutoFlowSpecByFileName(fileName) {
+    const preset = getBuiltInAutoFlowPresetByFileName(fileName);
+    if (!preset) {
+        return null;
+    }
+    const result = resolveAutoFlowPreset(preset);
+    if (!result.spec) {
+        const details = result.diagnostics.map((diagnostic) => diagnostic.message).join("\n");
+        throw new TaskRunnerError(`Failed to resolve built-in auto-flow '${fileName}'.\n${details}`);
+    }
+    return result.spec;
+}