@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/runtime/build/build-pipeline.js

@@ -0,0 +1,388 @@
+import { refreshContextGraphBootstrapGuidance, } from "../agents/lib/context-graph-bootstrap.js";
+import { validateBuildPlanPackage } from "../../build-plans/package/local-build-plans.js";
+import { reportValidationFailure, } from "../../build-plans/package/build-plan-helpers.js";
+import { validateContextGraph, } from "./validate.js";
+import { pruneStageExecutionShells, } from "../agents/lib/shells.js";
+import { reconcilePrunedStageExecutionSessions, } from "./stage-session.js";
+import { buildExecutionStages, resolveBuildContext, } from "./build-target.js";
+import { runBuildStage } from "./build-stage-runner.js";
+import { buildPlanPackagePathForContextGraph } from "./context-graph-paths.js";
+import { runSourceInventory } from "./source-inventory.js";
+import { stageReuseDecision } from "./stage-reuse.js";
+import { loadStageManifest, writeGraphManifest, } from "./stage-manifest.js";
+import { writeContextGraphInspectMap } from "./inspect-map.js";
+import { ensureSummaryCoverageIndex } from "./summary-coverage-index.js";
+import { createRunEventId, createRunEventTimestamp, } from "../execution/events.js";
+function pickStageExecutor(fallback, stage, resolve) {
+    if (!resolve)
+        return fallback;
+    const resolved = resolve(stage);
+    if (!resolved) {
+        throw new Error(`No executor resolved for Build Plan stage "${stage.id}" (role "${stage.role}").`);
+    }
+    return resolved;
+}
+function stageReadsSource(stage) {
+    if (stage.contractType === "build-file-evidence")
+        return true;
+    return stage.reads.includes("source");
+}
+function pickSourceInventoryExecutor(fallback, stages, resolve) {
+    const sourceReadingStage = stages.find(stageReadsSource) ?? stages[0];
+    if (!sourceReadingStage)
+        return fallback;
+    return pickStageExecutor(fallback, sourceReadingStage, resolve);
+}
+async function emitReusedStagePassed(options) {
+    if (!options.events || !options.runId)
+        return;
+    await options.events.emit({
+        type: "stage.started",
+        event_id: createRunEventId("event"),
+        run_id: options.runId,
+        timestamp: createRunEventTimestamp(),
+        stage_id: options.stageId,
+        ...(typeof options.stageIndex === "number" ? { stage_index: options.stageIndex } : {}),
+        ...(typeof options.stageTotal === "number" ? { stage_total: options.stageTotal } : {}),
+    });
+    await options.events.emit({
+        type: "stage.passed",
+        event_id: createRunEventId("event"),
+        run_id: options.runId,
+        timestamp: createRunEventTimestamp(),
+        stage_id: options.stageId,
+        summary: options.summary,
+    });
+}
+function reusedStageResult(summary = "reused (verified, unchanged)") {
+    return { ok: true, code: 0, summary };
+}
+/**
+ * Deterministic connectivity floor, applied after the stage agents have produced
+ * the graph but BEFORE readiness validation. Writes a managed coverage block into
+ * `home.md` (the entrypoint spine) wikilinking every summary the build produced,
+ * so every summary note has a guaranteed inbound edge no matter how the stage
+ * agent behaved. Best-effort: assembly is already complete, so a finalization
+ * error must never fail the build (the `graph_notes_connected` check still runs
+ * and will report any real gap).
+ */
+function finalizeGraphConnectivity(contextGraphPath) {
+    try {
+        ensureSummaryCoverageIndex(contextGraphPath);
+    }
+    catch {
+        // Never fail a built graph on the navigation-index write. The connectivity
+        // check runs next and is the source of truth on readiness.
+    }
+}
+export async function runBuildSummarize(options) {
+    const context = resolveBuildContext(options.contextGraphPath);
+    const stageDefinition = options.stageDefinition
+        ?? buildExecutionStages(context.buildPlanId, options.contextGraphPath).find((stage) => stage.id === "summarize");
+    if (!stageDefinition) {
+        return {
+            ok: false,
+            code: 1,
+            plan: { sourceCount: 0, summaryCount: 0, targetCount: 0 },
+            summary: "Build Plan does not declare a summarize stage.",
+        };
+    }
+    const sourceRuntime = await runSourceInventory({
+        executor: pickStageExecutor(options.executor, stageDefinition, options.resolveStageExecutor),
+        contextGraphPath: options.contextGraphPath,
+        project: context.contextGraphName,
+        projectIntent: context.projectIntent,
+        sourceLocator: context.sourcePath,
+        buildPlanId: context.buildPlanId,
+        stageIds: [stageDefinition.id],
+        stages: [stageDefinition],
+        runId: options.runId ?? null,
+        events: options.events,
+        maxAttempts: options.maxStageValidationAttempts,
+    });
+    if (!sourceRuntime.ok || !sourceRuntime.manifest) {
+        return {
+            ok: false,
+            code: 1,
+            plan: { sourceCount: 0, summaryCount: 0, targetCount: 0 },
+            summary: sourceRuntime.summary,
+        };
+    }
+    const sourceCount = sourceRuntime.manifest.source_total;
+    const reuse = stageReuseDecision({
+        contextGraphPath: options.contextGraphPath,
+        stageDefinition,
+    });
+    if (reuse.reuse && loadStageManifest(options.contextGraphPath, stageDefinition.id)) {
+        await emitReusedStagePassed({
+            events: options.events,
+            runId: options.runId,
+            stageId: stageDefinition.id,
+            stageIndex: 0,
+            stageTotal: 1,
+            summary: reuse.summary,
+        });
+        return {
+            ...reusedStageResult(reuse.summary),
+            plan: {
+                sourceCount,
+                summaryCount: 0,
+                targetCount: sourceCount,
+            },
+        };
+    }
+    const result = await runBuildStage({
+        executor: pickStageExecutor(options.executor, stageDefinition, options.resolveStageExecutor),
+        contextGraphPath: options.contextGraphPath,
+        reporter: options.reporter,
+        reportStep: options.reportStep,
+        stageDefinition,
+        runId: options.runId,
+        events: options.events,
+        maxValidationAttempts: options.maxStageValidationAttempts,
+    });
+    return {
+        ...result,
+        plan: {
+            sourceCount,
+            summaryCount: 0,
+            targetCount: sourceCount,
+        },
+    };
+}
+export async function runBuildStages(options) {
+    const preserveMode = options.preserveStageShells ?? "always";
+    if (preserveMode !== "always") {
+        pruneStageExecutionShells(options.contextGraphPath);
+    }
+    let lastResult = { ok: true, code: 0 };
+    try {
+        const context = resolveBuildContext(options.contextGraphPath);
+        const stages = buildExecutionStages(context.buildPlanId, options.contextGraphPath);
+        const sourceInventoryExecutor = pickSourceInventoryExecutor(options.executor, stages, options.resolveStageExecutor);
+        const sourceRuntime = await runSourceInventory({
+            executor: sourceInventoryExecutor,
+            contextGraphPath: options.contextGraphPath,
+            project: context.contextGraphName,
+            projectIntent: context.projectIntent,
+            sourceLocator: context.sourcePath,
+            buildPlanId: context.buildPlanId,
+            stageIds: stages.map((stage) => stage.id),
+            stages,
+            runId: options.runId ?? null,
+            events: options.events,
+            maxAttempts: options.maxStageValidationAttempts,
+        });
+        if (!sourceRuntime.ok)
+            return sourceRuntime;
+        let forceRunFromHere = false;
+        for (const [index, stageDefinition] of stages.entries()) {
+            if (!forceRunFromHere) {
+                const reuse = stageReuseDecision({
+                    contextGraphPath: options.contextGraphPath,
+                    stageDefinition,
+                });
+                if (reuse.reuse && loadStageManifest(options.contextGraphPath, stageDefinition.id)) {
+                    await emitReusedStagePassed({
+                        events: options.events,
+                        runId: options.runId,
+                        stageId: stageDefinition.id,
+                        stageIndex: index,
+                        stageTotal: stages.length,
+                        summary: reuse.summary,
+                    });
+                    lastResult = reusedStageResult(reuse.summary);
+                    continue;
+                }
+            }
+            forceRunFromHere = true;
+            const result = await runBuildStage({
+                executor: pickStageExecutor(options.executor, stageDefinition, options.resolveStageExecutor),
+                contextGraphPath: options.contextGraphPath,
+                reporter: options.reporter,
+                reportStep: options.reportStep,
+                stageDefinition,
+                runId: options.runId,
+                events: options.events,
+                stageIndex: index,
+                stageTotal: stages.length,
+                maxValidationAttempts: options.maxStageValidationAttempts,
+            });
+            lastResult = result;
+            if (!result.ok)
+                return result;
+        }
+        // Connectivity floor: link every summary into a deterministic navigation
+        // index before the GraphManifest rolls up coverage and connectivity metrics.
+        finalizeGraphConnectivity(options.contextGraphPath);
+        writeGraphManifest({
+            contextGraphPath: options.contextGraphPath,
+            projectId: context.contextGraphName,
+            buildPlanId: context.buildPlanId,
+            intent: context.projectIntent,
+            runId: options.runId ?? null,
+        });
+        // Refresh the developer/agent map of the built folder from already-recorded
+        // state. Best-effort: it never fails the build.
+        writeContextGraphInspectMap(options.contextGraphPath);
+        return lastResult;
+    }
+    finally {
+        if (preserveMode !== "always" && lastResult.ok) {
+            pruneStageExecutionShells(options.contextGraphPath);
+            // Pruning deleted the shells the sessions point at; downgrade those
+            // sessions so none dangles with replay_ready:true (F2).
+            reconcilePrunedStageExecutionSessions({ contextGraphPath: options.contextGraphPath });
+            // The in-try map render above reflected pre-reconcile sessions (shells the
+            // prune was about to delete). Re-render from the reconciled state so the
+            // map points only at shells still on disk (F1). Best-effort, never fails.
+            writeContextGraphInspectMap(options.contextGraphPath);
+        }
+    }
+}
+export async function buildContextGraph(options) {
+    const preserveMode = options.preserveStageShells ?? "always";
+    if (preserveMode !== "always") {
+        pruneStageExecutionShells(options.contextGraphPath);
+    }
+    let result = {
+        ok: true,
+        stageResults: {},
+        failedStage: null,
+    };
+    try {
+        refreshContextGraphBootstrapGuidance(options.contextGraphPath);
+        const buildPlanValidation = validateBuildPlanPackage(buildPlanPackagePathForContextGraph(options.contextGraphPath));
+        if (!buildPlanValidation.ok) {
+            reportValidationFailure(options.reporter, buildPlanValidation.summary, buildPlanValidation.errors);
+            return {
+                ...result,
+                ok: false,
+                failedStage: "build-plan",
+                stageResults: {
+                    ...result.stageResults,
+                    "build-plan": {
+                        ok: false,
+                        code: 1,
+                        summary: buildPlanValidation.summary,
+                    },
+                },
+            };
+        }
+        const context = resolveBuildContext(options.contextGraphPath);
+        const stages = buildExecutionStages(context.buildPlanId, options.contextGraphPath);
+        const sourceInventoryExecutor = pickSourceInventoryExecutor(options.executor, stages, options.resolveStageExecutor);
+        const sourceRuntime = await runSourceInventory({
+            executor: sourceInventoryExecutor,
+            contextGraphPath: options.contextGraphPath,
+            project: context.contextGraphName,
+            projectIntent: context.projectIntent,
+            sourceLocator: context.sourcePath,
+            buildPlanId: context.buildPlanId,
+            stageIds: stages.map((stage) => stage.id),
+            stages,
+            runId: options.runId ?? null,
+            events: options.events,
+            maxAttempts: options.maxStageValidationAttempts,
+        });
+        if (!sourceRuntime.ok) {
+            result.ok = false;
+            result.failedStage = "source-inventory";
+            result.stageResults["source-inventory"] = sourceRuntime;
+            return result;
+        }
+        let forceRunFromHere = false;
+        for (const [index, stageDefinition] of stages.entries()) {
+            if (!forceRunFromHere) {
+                const reuse = stageReuseDecision({
+                    contextGraphPath: options.contextGraphPath,
+                    stageDefinition,
+                });
+                if (reuse.reuse && loadStageManifest(options.contextGraphPath, stageDefinition.id)) {
+                    await emitReusedStagePassed({
+                        events: options.events,
+                        runId: options.runId,
+                        stageId: stageDefinition.id,
+                        stageIndex: index,
+                        stageTotal: stages.length,
+                        summary: reuse.summary,
+                    });
+                    result.stageResults[stageDefinition.id] = reusedStageResult(reuse.summary);
+                    continue;
+                }
+            }
+            forceRunFromHere = true;
+            const stageResult = await runBuildStage({
+                executor: pickStageExecutor(options.executor, stageDefinition, options.resolveStageExecutor),
+                contextGraphPath: options.contextGraphPath,
+                reporter: options.reporter,
+                reportStep: true,
+                stageDefinition,
+                runId: options.runId,
+                events: options.events,
+                stageIndex: index,
+                stageTotal: stages.length,
+                maxValidationAttempts: options.maxStageValidationAttempts,
+            });
+            result.stageResults[stageDefinition.id] = stageResult;
+            if (!stageResult.ok) {
+                result.ok = false;
+                result.failedStage = stageDefinition.id;
+                return result;
+            }
+        }
+        // Connectivity floor: ensure every produced summary is reachable through a
+        // deterministic navigation index BEFORE readiness is validated.
+        finalizeGraphConnectivity(options.contextGraphPath);
+        const buildPlanValidationResult = validateContextGraph(options.contextGraphPath);
+        result.ok = buildPlanValidationResult.ok;
+        result.failedStage = buildPlanValidationResult.ok ? null : buildPlanValidationResult.stage;
+        result.stageResults["context-graph"] = {
+            ok: buildPlanValidationResult.ok,
+            code: buildPlanValidationResult.ok ? 0 : 1,
+            summary: buildPlanValidationResult.summary,
+        };
+        if (buildPlanValidationResult.ok) {
+            try {
+                const graphManifest = writeGraphManifest({
+                    contextGraphPath: options.contextGraphPath,
+                    projectId: context.contextGraphName,
+                    buildPlanId: context.buildPlanId,
+                    intent: context.projectIntent,
+                    runId: options.runId ?? null,
+                });
+                result.stageResults["graph-manifest"] = {
+                    ok: true,
+                    code: 0,
+                    summary: `GraphManifest recorded ${graphManifest.resources.length} resource${graphManifest.resources.length === 1 ? "" : "s"} and ${graphManifest.graph_outputs.edges} graph edge${graphManifest.graph_outputs.edges === 1 ? "" : "s"}.`,
+                };
+                // Refresh the developer/agent map (.interf/INSPECT.md) of the built
+                // folder from already-recorded state. Best-effort: it never fails the
+                // build, so a render error does not flip a ready graph to failed.
+                writeContextGraphInspectMap(options.contextGraphPath);
+            }
+            catch (error) {
+                result.ok = false;
+                result.failedStage = "graph-manifest";
+                result.stageResults["graph-manifest"] = {
+                    ok: false,
+                    code: 1,
+                    summary: `Could not write GraphManifest: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+        }
+        return result;
+    }
+    finally {
+        if (preserveMode !== "always" && result.ok) {
+            pruneStageExecutionShells(options.contextGraphPath);
+            // Pruning deleted the shells the sessions point at; downgrade those
+            // sessions so none dangles with replay_ready:true (F2).
+            reconcilePrunedStageExecutionSessions({ contextGraphPath: options.contextGraphPath });
+            // The in-try map render above reflected pre-reconcile sessions (shells the
+            // prune was about to delete). Re-render from the reconciled state so the
+            // map points only at shells still on disk (F1). Best-effort, never fails.
+            writeContextGraphInspectMap(options.contextGraphPath);
+        }
+    }
+}

package/dist/packages/{engine → runtime}/build/build-plan-primitives.d.ts

@@ -1,2 +1,2 @@
-export declare const BUILD_PLAN_ARTIFACT_KINDS: readonly ["directory", "file", "runtime"];
+export declare const BUILD_PLAN_ARTIFACT_KINDS: readonly ["directory", "file"];
 export type BuildPlanArtifactKind = typeof BUILD_PLAN_ARTIFACT_KINDS[number];

package/dist/packages/{engine → runtime}/build/build-plan-primitives.js

@@ -1,5 +1,4 @@
 export const BUILD_PLAN_ARTIFACT_KINDS = [
     "directory",
     "file",
-    "runtime",
 ];

package/dist/packages/runtime/build/build-plan-runs.d.ts

@@ -0,0 +1,14 @@
+import { type InterfConfig } from "../../projects/interf-detect.js";
+export type { BuildPlanReporter } from "../../build-plans/package/build-plan-helpers.js";
+export type BuildCheck = "context-graph" | "stage";
+export interface DetectedInterfTarget {
+    path: string;
+    kind: "context-graph";
+    engineType: "build";
+    config: InterfConfig;
+}
+export declare function detectContextGraph(cwd: string): DetectedInterfTarget | null;
+export declare function createContextGraph(name: string, sourcePath: string, buildPlanId: string | undefined, sourceFolderPath: string): string;
+export declare function verifyBuildCheck(check: BuildCheck, contextGraphPath: string): import("./validate-context-graph.js").ContextGraphValidation;
+export { runBuildSummarize, runBuildStages, buildContextGraph, resolveBuildContext, buildExecutionStages, } from "./build-execution.js";
+export type { BuildSummarizeResult, BuildResult, BuildStageExecutionDefinition, StageShellRetentionMode, ResolveStageExecutor, } from "./build-execution.js";

package/dist/packages/runtime/build/build-plan-runs.js

@@ -0,0 +1,31 @@
+import { createContextGraph as createContextGraphScaffold, } from "../context-graph-scaffold.js";
+import { detectInterf } from "../../projects/interf-detect.js";
+import { validateBuildOutput, } from "./validate.js";
+import { DEFAULT_BUILD_PLAN_ID } from "../../build-plans/build-plan-resolution.js";
+export function detectContextGraph(cwd) {
+    const detected = detectInterf(cwd);
+    if (!detected)
+        return null;
+    return {
+        path: detected.path,
+        kind: "context-graph",
+        engineType: "build",
+        config: detected.config,
+    };
+}
+export function createContextGraph(name, sourcePath, buildPlanId, sourceFolderPath) {
+    return createContextGraphScaffold(name, sourcePath, buildPlanId ?? DEFAULT_BUILD_PLAN_ID, sourceFolderPath);
+}
+export function verifyBuildCheck(check, contextGraphPath) {
+    switch (check) {
+        case "context-graph":
+            return validateBuildOutput(contextGraphPath);
+        case "stage":
+            return validateBuildOutput(contextGraphPath);
+        default: {
+            const exhaustiveCheck = check;
+            throw new Error(`Unknown build check: ${exhaustiveCheck}`);
+        }
+    }
+}
+export { runBuildSummarize, runBuildStages, buildContextGraph, resolveBuildContext, buildExecutionStages, } from "./build-execution.js";

package/dist/packages/runtime/build/build-stage-plan.d.ts

@@ -0,0 +1,16 @@
+import { type RuntimeStageContractDraft } from "./runtime.js";
+import { type BuildPlanStageDefinition } from "../../build-plans/package/build-plan-definitions.js";
+import { resolveBuildContext, type BuildStageExecutionDefinition } from "./build-target.js";
+import type { RuntimeStageInstructions } from "./lib/schema.js";
+export declare function resolveStageContractArtifacts(contextGraphPath: string, stageDefinition: Pick<BuildPlanStageDefinition, "id" | "reads" | "writes">): {
+    reads: string[];
+    writes: string[];
+    writeContracts: RuntimeStageContractDraft["artifacts"]["write_contracts"];
+};
+export declare function buildStageCounts(contextGraphPath: string, stageDefinition: BuildPlanStageDefinition): Record<string, number>;
+export declare function buildStageContract(contextGraphPath: string, stageDefinition: BuildPlanStageDefinition, instructions: RuntimeStageInstructions): RuntimeStageContractDraft;
+export declare function buildBuildStageExecutionPlan(contextGraphPath: string, stageDefinition: BuildStageExecutionDefinition): {
+    context: ReturnType<typeof resolveBuildContext>;
+    contract: RuntimeStageContractDraft;
+    instructions: RuntimeStageInstructions;
+};

package/dist/packages/runtime/build/build-stage-plan.js

@@ -0,0 +1,101 @@
+import { join } from "node:path";
+import { buildRuntimeStageContract, } from "./runtime.js";
+import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
+import { contextGraphArtifactPath, contextGraphArtifactPathsForArtifactIds, findBuildPlanContextArtifact, readBuildPlanContextFile, } from "./context-graph-schema.js";
+import { buildLocalSkillContractExtension, buildStageInstructions, buildPlanStageDirectory, } from "../../build-plans/package/build-plan-helpers.js";
+import { loadContextGraphSourceManifest } from "./source-manifest.js";
+import { getActiveBuildPlan, getActiveBuildPlanStagePolicyNotes, } from "../../build-plans/package/build-plan-definitions.js";
+import { buildPlanPackagePathForContextGraph } from "./context-graph-paths.js";
+import { readInterfConfig } from "../../projects/interf-detect.js";
+import { resolveBuildContext, } from "./build-target.js";
+function artifactCount(contextGraphPath, artifactPath, kind) {
+    const absolutePath = join(contextGraphPath, artifactPath);
+    try {
+        if (kind === "file") {
+            return listFilesRecursive(absolutePath).length > 0 ? 1 : 0;
+        }
+    }
+    catch {
+        if (kind === "file")
+            return 0;
+    }
+    return listFilesRecursive(absolutePath).length;
+}
+export function resolveStageContractArtifacts(contextGraphPath, stageDefinition) {
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForContextGraph(contextGraphPath));
+    if (!schema) {
+        throw new Error(`Missing Build Plan schema for stage "${stageDefinition.id}" at ${buildPlanPackagePathForContextGraph(contextGraphPath)}.`);
+    }
+    return {
+        reads: contextGraphArtifactPathsForArtifactIds(schema, stageDefinition.reads),
+        writes: contextGraphArtifactPathsForArtifactIds(schema, stageDefinition.writes),
+        writeContracts: stageDefinition.writes.map((artifactId) => {
+            const artifact = schema.artifacts.find((candidate) => candidate.id === artifactId);
+            if (!artifact) {
+                throw new Error(`Build Plan schema is missing declared Artifact "${artifactId}".`);
+            }
+            const path = artifact.shape.kind === "path"
+                ? contextGraphArtifactPath({
+                    path: artifact.shape.path,
+                    kind: artifact.shape.artifact_kind,
+                })
+                : artifact.id;
+            return {
+                artifact_id: artifact.id,
+                path,
+                checks: artifact.checks ?? [],
+            };
+        }),
+    };
+}
+export function buildStageCounts(contextGraphPath, stageDefinition) {
+    const sourceTotal = loadContextGraphSourceManifest(contextGraphPath)?.source_total ?? 0;
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForContextGraph(contextGraphPath));
+    const artifactCounts = {};
+    if (schema) {
+        for (const artifactId of new Set([...stageDefinition.reads, ...stageDefinition.writes])) {
+            const artifact = findBuildPlanContextArtifact(schema, artifactId);
+            if (!artifact)
+                continue;
+            artifactCounts[artifactId] = artifactCount(contextGraphPath, artifact.path, artifact.kind);
+        }
+    }
+    return {
+        source_total: sourceTotal,
+        read_artifact_total: stageDefinition.reads.length,
+        write_artifact_total: stageDefinition.writes.length,
+        ...artifactCounts,
+    };
+}
+export function buildStageContract(contextGraphPath, stageDefinition, instructions) {
+    const config = readInterfConfig(contextGraphPath);
+    const stageArtifacts = resolveStageContractArtifacts(contextGraphPath, stageDefinition);
+    return buildRuntimeStageContract({
+        contextGraphName: config?.name ?? "context-graph",
+        project: resolveBuildContext(contextGraphPath).project,
+        stageId: stageDefinition.id,
+        stageLabel: stageDefinition.label,
+        counts: buildStageCounts(contextGraphPath, stageDefinition),
+        extraReadArtifacts: [
+            "runtime/source-manifest.json",
+            "runtime/stage-inputs.json",
+        ],
+        stageReadArtifacts: stageArtifacts.reads,
+        stageWriteArtifacts: stageArtifacts.writes,
+        stageWriteContracts: stageArtifacts.writeContracts,
+        contextChecks: getActiveBuildPlan(contextGraphPath).brief?.checks ?? [],
+        buildPlanNotes: getActiveBuildPlanStagePolicyNotes(contextGraphPath, stageDefinition.id),
+        localSkillDocs: instructions.local_docs,
+        instructions,
+    });
+}
+export function buildBuildStageExecutionPlan(contextGraphPath, stageDefinition) {
+    const context = resolveBuildContext(contextGraphPath);
+    const localSkills = buildLocalSkillContractExtension(contextGraphPath, [buildPlanStageDirectory(stageDefinition.skillDir)], "Use them to refine this Build Plan stage while still honoring the declared reads, writes, and evidence rules.");
+    const instructions = buildStageInstructions(stageDefinition.skillDir, localSkills);
+    return {
+        context,
+        instructions,
+        contract: buildStageContract(contextGraphPath, stageDefinition, instructions),
+    };
+}

package/dist/packages/{engine → runtime}/build/build-stage-runner.d.ts

@@ -4,7 +4,7 @@ import { type BuildStageExecutionDefinition } from "./build-target.js";
 import { type RunEventSink } from "../execution/events.js";
 export declare function runBuildStage(options: {
     executor: AgentExecutor;
-    verifiableContextPath: string;
+    contextGraphPath: string;
     reporter?: BuildPlanReporter;
     reportStep?: boolean;
     stageDefinition: BuildStageExecutionDefinition;
@@ -12,4 +12,5 @@ export declare function runBuildStage(options: {
     events?: RunEventSink;
     stageIndex?: number;
     stageTotal?: number;
+    maxValidationAttempts?: number;
 }): Promise<BuildPlanStageResult>;