@interf/compiler 0.21.0 → 0.22.2

package/dist/packages/{methods/authoring/method-edit-session.js → build-plans/authoring/build-plan-edit-session.js}

@@ -1,11 +1,11 @@
 import { appendFileSync, existsSync, realpathSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { copyDirectory, directoriesMatch, } from "./lib/method-edit-utils.js";
-export async function runMethodEditSession(options) {
-    const editableMethodPath = join(options.shell.rootPath, "method");
-    copyDirectory(options.methodPath, options.shell.methodBeforePath);
-    if (!existsSync(editableMethodPath)) {
-        copyDirectory(options.methodPath, editableMethodPath);
+import { copyDirectory, directoriesMatch, } from "./lib/build-plan-edit-utils.js";
+export async function runBuildPlanEditSession(options) {
+    const editableBuildPlanPath = join(options.shell.rootPath, "build-plan");
+    copyDirectory(options.buildPlanPath, options.shell.buildPlanBeforePath);
+    if (!existsSync(editableBuildPlanPath)) {
+        copyDirectory(options.buildPlanPath, editableBuildPlanPath);
     }
     writeFileSync(options.shell.promptLogPath, `${options.prompt}\n`);
     const maxValidationRepairAttempts = options.maxValidationRepairAttempts ?? 0;
@@ -19,9 +19,9 @@ export async function runMethodEditSession(options) {
                 statusLogPath: options.shell.statusLogPath,
                 completionCheck: () => {
                     try {
-                        if (directoriesMatch(options.shell.methodBeforePath, editableMethodPath))
+                        if (directoriesMatch(options.shell.buildPlanBeforePath, editableBuildPlanPath))
                             return false;
-                        return options.validate(editableMethodPath).ok;
+                        return options.validate(editableBuildPlanPath).ok;
                     }
                     catch {
                         return false;
@@ -33,84 +33,84 @@ export async function runMethodEditSession(options) {
         catch (error) {
             executeError = error instanceof Error ? error.message : String(error);
         }
-        copyDirectory(editableMethodPath, options.shell.methodAfterPath);
-        const changed = !directoriesMatch(options.shell.methodBeforePath, options.shell.methodAfterPath);
+        copyDirectory(editableBuildPlanPath, options.shell.buildPlanAfterPath);
+        const changed = !directoriesMatch(options.shell.buildPlanBeforePath, options.shell.buildPlanAfterPath);
         if (executeError) {
-            copyDirectory(options.shell.methodBeforePath, options.methodPath);
-            copyDirectory(options.shell.methodBeforePath, editableMethodPath);
+            copyDirectory(options.shell.buildPlanBeforePath, options.buildPlanPath);
+            copyDirectory(options.shell.buildPlanBeforePath, editableBuildPlanPath);
             return {
                 status: "executor-failed",
                 changed,
                 validation: null,
-                summary: `Method editor failed before completing: ${executeError}`,
+                summary: `Build Plan editor failed before completing: ${executeError}`,
             };
         }
         if (code !== 0) {
-            copyDirectory(options.shell.methodBeforePath, options.methodPath);
-            copyDirectory(options.shell.methodBeforePath, editableMethodPath);
+            copyDirectory(options.shell.buildPlanBeforePath, options.buildPlanPath);
+            copyDirectory(options.shell.buildPlanBeforePath, editableBuildPlanPath);
             return {
                 status: "executor-failed",
                 changed,
                 validation: null,
-                summary: `Method editor exited with code ${code}.`,
+                summary: `Build Plan editor exited with code ${code}.`,
             };
         }
-        const validation = options.validate(editableMethodPath);
+        const validation = options.validate(editableBuildPlanPath);
         if (validation.ok) {
-            if (!sameRealPath(editableMethodPath, options.methodPath)) {
-                copyDirectory(editableMethodPath, options.methodPath);
+            if (!sameRealPath(editableBuildPlanPath, options.buildPlanPath)) {
+                copyDirectory(editableBuildPlanPath, options.buildPlanPath);
             }
             return {
                 status: changed ? "updated" : "no-change",
                 changed,
                 validation,
                 summary: changed
-                    ? "Method package updated and validated."
-                    : "Method package is valid without additional edits.",
+                    ? "Build Plan package updated and validated."
+                    : "Build Plan package is valid without additional edits.",
             };
         }
         const details = validation.errors.length > 0
             ? `: ${validation.errors.slice(0, 6).join("; ")}`
             : "";
         if (!changed || attempt >= maxValidationRepairAttempts) {
-            copyDirectory(options.shell.methodBeforePath, options.methodPath);
-            copyDirectory(options.shell.methodBeforePath, editableMethodPath);
+            copyDirectory(options.shell.buildPlanBeforePath, options.buildPlanPath);
+            copyDirectory(options.shell.buildPlanBeforePath, editableBuildPlanPath);
             return {
                 status: "invalid",
                 changed,
                 validation,
                 summary: changed
-                    ? `Method package failed validation: ${validation.summary}${details}`
-                    : `Method package is invalid without any Method edits: ${validation.summary}${details}`,
+                    ? `Build Plan package failed validation: ${validation.summary}${details}`
+                    : `Build Plan package is invalid without any Build Plan edits: ${validation.summary}${details}`,
             };
         }
         prompt = [
-            "This is an automated Interf Method validation-repair pass.",
+            "This is an automated Interf Build Plan validation-repair pass.",
             "The previous edit did not pass package validation.",
-            "Fix only the validation errors below. Do not redesign the Method.",
+            "Fix only the validation errors below. Do not redesign the Build Plan.",
             "",
             "Validation errors:",
             ...validation.errors.slice(0, 12).map((error) => `- ${error}`),
             "",
             "Rules:",
-            "- Edit only files under `method/`.",
+            "- Edit only files under `build-plan/`.",
             "- Use kebab-case ids everywhere: stage ids, skill_dir values, Artifact ids, reads/writes values, and package ids. Never use underscores.",
-            "- Keep every stage `skill_dir` matched by `method/compile/stages/<skill_dir>/SKILL.md`.",
-            "- Keep `method.schema.json` Artifact paths unique and non-overlapping.",
+            "- Keep every stage `skill_dir` matched by `build-plan/build/stages/<skill_dir>/SKILL.md`.",
+            "- Keep `build-plan.schema.json` Artifact paths unique and non-overlapping.",
             "- Put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks.",
             "- Use only CheckKind values listed in `runtime/authoring-context.json`; replace invented aliases with valid kinds.",
-            "- If the Method writes an agent entrypoint, keep it declared as an Artifact owned by the producing stage.",
+            "- If the Build Plan writes an agent entrypoint, keep it declared as an Artifact owned by the producing stage.",
             "- Stop as soon as the package should validate.",
         ].join("\n");
         appendFileSync(options.shell.promptLogPath, `\n\n---\n\n${prompt}\n`);
     }
-    copyDirectory(options.shell.methodBeforePath, options.methodPath);
-    copyDirectory(options.shell.methodBeforePath, editableMethodPath);
+    copyDirectory(options.shell.buildPlanBeforePath, options.buildPlanPath);
+    copyDirectory(options.shell.buildPlanBeforePath, editableBuildPlanPath);
     return {
         status: "invalid",
         changed: true,
         validation: null,
-        summary: "Method package failed validation.",
+        summary: "Build Plan package failed validation.",
     };
 }
 function sameRealPath(leftPath, rightPath) {

package/dist/packages/build-plans/authoring/build-plan-improvement.d.ts

@@ -0,0 +1,23 @@
+import type { AgentExecutor } from "../../engine/agents/lib/executors.js";
+import { type BuildPlanValidationResult } from "../package/local-build-plans.js";
+import type { SourcePreparationConfig } from "../../project/lib/schema.js";
+import type { BuildPlanImprovementLoopSummary } from "../../engine/build/lib/schema.js";
+export interface BuildPlanImprovementRunResult {
+    status: "updated" | "no-change" | "invalid" | "executor-failed";
+    changed: boolean;
+    validation: BuildPlanValidationResult | null;
+    summary: string;
+    shellPath: string;
+    loopRootPath: string;
+}
+export declare function runBuildPlanImprovementLoop(options: {
+    executor: AgentExecutor;
+    verifiableContextPath: string;
+    buildPlanId: string;
+    verifiableContextConfig: Pick<SourcePreparationConfig, "checks">;
+    runId: string;
+    loopIndex: number;
+    maxLoops: number;
+    maxAttempts: number;
+    previousVariations: BuildPlanImprovementLoopSummary[];
+}): Promise<BuildPlanImprovementRunResult>;

package/dist/packages/build-plans/authoring/build-plan-improvement.js

@@ -0,0 +1,216 @@
+import { appendFileSync, existsSync, mkdirSync, writeFileSync, } from "node:fs";
+import { join, relative } from "node:path";
+import { createBuildPlanImprovementShell, freezeBuildPlanImprovementShell, } from "../../engine/agents/lib/shells.js";
+import { validateBuildPlanPackage } from "../package/local-build-plans.js";
+import { CONTEXT_INTERFACE_FILE } from "../package/context-interface.js";
+import { readJsonFileWithSchema } from "../../contracts/utils/parse.js";
+import { resolveBuildPlanImprovementReviewPaths } from "../package/build-plan-review-paths.js";
+import { targetTestRunsRootForVerifiableContext, targetTestSandboxesRootForVerifiableContext, buildPlanImprovementRunRoot, buildPlanPackagePathForVerifiableContext, } from "../../engine/build/verifiable-context-paths.js";
+import { readInterfConfig } from "../../project/interf.js";
+import { saveVerifiableContextInterfConfig } from "../../project/source-config.js";
+import { BuildPlanImprovementRunLedgerSchema, } from "../../engine/build/lib/schema.js";
+import { runBuildPlanEditSession } from "./build-plan-edit-session.js";
+import { ensureStageRoles } from "./build-plan-authoring.js";
+function toShellArtifactPath(absolutePath, sourceRoot, shellRoot) {
+    if (!absolutePath)
+        return null;
+    const normalizedSourceRoot = `${sourceRoot}/`;
+    if (absolutePath !== sourceRoot && !absolutePath.startsWith(normalizedSourceRoot)) {
+        return null;
+    }
+    const relativePath = relative(sourceRoot, absolutePath);
+    return join(shellRoot, relativePath);
+}
+function mapLoopSummaryForShell(summary, verifiableContextPath) {
+    const shellTestRunsRoot = "artifacts/test-runs";
+    const shellTestSandboxesRoot = "artifacts/test-sandboxes";
+    return {
+        ...summary,
+        test_run_path: toShellArtifactPath(summary.test_run_path, targetTestRunsRootForVerifiableContext(verifiableContextPath), shellTestRunsRoot) ?? summary.test_run_path ?? null,
+        test_sandbox_path: toShellArtifactPath(summary.test_sandbox_path, targetTestSandboxesRootForVerifiableContext(verifiableContextPath), shellTestSandboxesRoot) ?? summary.test_sandbox_path ?? null,
+    };
+}
+function buildLoopContext(options) {
+    const previousVariations = options.previousVariations.map((summary) => mapLoopSummaryForShell(summary, options.verifiableContextPath));
+    const latestFailure = previousVariations.at(-1) ?? null;
+    return {
+        kind: "interf-build-plan-improvement-loop",
+        version: 1,
+        generated_at: new Date().toISOString(),
+        target_name: readInterfConfig(options.verifiableContextPath)?.name ?? "verifiable-context",
+        build_plan_id: options.buildPlanId,
+        loop_index: options.loopIndex,
+        max_loops: options.maxLoops,
+        max_attempts: options.maxAttempts,
+        review_paths: resolveBuildPlanImprovementReviewPaths(options.verifiableContextPath),
+        readiness_checks: {
+            count: options.verifiableContextConfig.checks.length,
+            questions: options.verifiableContextConfig.checks.map((check, index) => ({
+                id: check.id ?? `check-${index + 1}`,
+                question: check.question,
+            })),
+        },
+        previous_variations: previousVariations,
+        latest_failure: latestFailure,
+    };
+}
+function buildBuildPlanImprovementPrompt() {
+    return [
+        "This is an automated Interf Build Plan improvement run, not an open-ended chat session.",
+        "The user already invoked this through `interf build` with self-improving loops enabled. Execute it now.",
+        "Read `runtime/loop-context.json` first.",
+        `Then read \`build-plan/README.md\`, \`build-plan/build-plan.json\`, \`build-plan/${CONTEXT_INTERFACE_FILE}\`, and \`build-plan/improve/SKILL.md\` if it exists.`,
+        "Review preserved evidence from earlier failures under `artifacts/` before you edit the Build Plan.",
+        "Treat `build-plan/improve/SKILL.md` as guidance for how to improve the Build Plan, not as the default file to edit.",
+        "Treat the Build Plan package as four aligned layers: purpose, inputs, context interface, and stages.",
+        "Prefer editing the stage docs, Build Plan contract, input contract, or schema ownership that actually change verifiable-context outputs.",
+        "Edit only files under `build-plan/`.",
+        "Do not edit checks, test specs, source files, or generated verifiable-context outputs.",
+        "Keep the Build Plan package valid for the current build API and `build-plan.schema.json`.",
+        "Respect stage boundaries: a stage may only introduce links that resolve within that stage's declared writes or already-existing read Artifacts.",
+        "Do not make one stage point at files or notes that are only created later by another stage.",
+        "Prefer small, defensible changes to Build Plan docs, stage docs, stage policies, or schema ownership over random churn.",
+        "Do not narrate plans or ask follow-up questions.",
+        "Only emit user-visible updates that begin with STATUS:, DONE:, BLOCKED:, or ERROR:.",
+        "As soon as the Build Plan edits are complete, stop.",
+    ].join("\n");
+}
+function updateBuildPlanOrigin(options) {
+    const current = readInterfConfig(options.verifiableContextPath);
+    if (!current)
+        return;
+    const nextConfig = {
+        ...current,
+        build_plan_origin: {
+            selected: options.selectedBuildPlanId,
+            ...(options.localDraft ? { local_draft: true } : {}),
+        },
+    };
+    saveVerifiableContextInterfConfig(options.verifiableContextPath, nextConfig);
+}
+function buildPlanImprovementRunLedgerPath(verifiableContextPath, runId) {
+    return join(buildPlanImprovementRunRoot(verifiableContextPath, runId), "run.json");
+}
+function buildPlanImprovementLoopHistoryPath(verifiableContextPath, runId) {
+    return join(buildPlanImprovementRunRoot(verifiableContextPath, runId), "loop-history.jsonl");
+}
+function buildPlanImprovementLoopRecordPath(loopRootPath) {
+    return join(loopRootPath, "loop.json");
+}
+function readBuildPlanImprovementRunLedger(verifiableContextPath, runId) {
+    const ledgerPath = buildPlanImprovementRunLedgerPath(verifiableContextPath, runId);
+    if (!existsSync(ledgerPath))
+        return null;
+    return readJsonFileWithSchema(ledgerPath, "Build Plan improvement run ledger", BuildPlanImprovementRunLedgerSchema);
+}
+function writeBuildPlanImprovementRunLedger(verifiableContextPath, runId, record, options) {
+    const runRoot = buildPlanImprovementRunRoot(verifiableContextPath, runId);
+    mkdirSync(runRoot, { recursive: true });
+    const existing = readBuildPlanImprovementRunLedger(verifiableContextPath, runId);
+    const generatedAt = existing?.generated_at ?? new Date().toISOString();
+    const ledger = {
+        kind: "interf-build-plan-improvement-run",
+        version: 1,
+        generated_at: generatedAt,
+        updated_at: new Date().toISOString(),
+        run_id: runId,
+        target_name: options.targetName,
+        build_plan_id: options.buildPlanId,
+        max_loops: options.maxLoops,
+        max_attempts: options.maxAttempts,
+        loops: [...(existing?.loops ?? []), record],
+    };
+    writeFileSync(buildPlanImprovementRunLedgerPath(verifiableContextPath, runId), `${JSON.stringify(ledger, null, 2)}\n`);
+    writeFileSync(buildPlanImprovementLoopRecordPath(record.loop_root_path), `${JSON.stringify(record, null, 2)}\n`);
+    appendFileSync(buildPlanImprovementLoopHistoryPath(verifiableContextPath, runId), `${JSON.stringify(record)}\n`);
+}
+function buildBuildPlanImprovementLoopRecord(options) {
+    return {
+        kind: "interf-build-plan-improvement-loop-record",
+        version: 1,
+        recorded_at: new Date().toISOString(),
+        run_id: options.runId,
+        loop_index: options.loopIndex,
+        target_name: options.targetName,
+        build_plan_id: options.buildPlanId,
+        result: options.result,
+        changed: options.changed,
+        applied: options.result === "updated",
+        summary: options.summary,
+        shell_path: options.shellPath,
+        loop_root_path: options.loopRootPath,
+        context_path: join(options.shellPath, "runtime", "loop-context.json"),
+        build_plan_before_path: options.buildPlanBeforePath,
+        build_plan_after_path: options.buildPlanAfterPath,
+        prompt_log_path: options.promptLogPath,
+        event_log_path: options.eventLogPath,
+        status_log_path: options.statusLogPath,
+        preserved_shell_manifest_path: options.preservedShellManifestPath,
+        validation: options.validation,
+    };
+}
+export async function runBuildPlanImprovementLoop(options) {
+    const verifiableContextName = readInterfConfig(options.verifiableContextPath)?.name ?? "verifiable-context";
+    const context = buildLoopContext(options);
+    const shell = createBuildPlanImprovementShell({
+        verifiableContextPath: options.verifiableContextPath,
+        verifiableContextName,
+        buildPlanId: options.buildPlanId,
+        runId: options.runId,
+        loopIndex: options.loopIndex,
+        context,
+    });
+    const buildPlanRoot = buildPlanPackagePathForVerifiableContext(options.verifiableContextPath);
+    const session = await runBuildPlanEditSession({
+        executor: options.executor,
+        buildPlanPath: buildPlanRoot,
+        shell,
+        prompt: buildBuildPlanImprovementPrompt(),
+        validate: validateBuildPlanPackage,
+        maxValidationRepairAttempts: 1,
+    });
+    if (session.status === "updated") {
+        // 0.15 — fill role=general on any stage the improvement run
+        // dropped a role from. Idempotent and silent when complete.
+        ensureStageRoles(buildPlanRoot);
+    }
+    const preservedShellManifestPath = freezeBuildPlanImprovementShell(shell.rootPath);
+    writeBuildPlanImprovementRunLedger(options.verifiableContextPath, options.runId, buildBuildPlanImprovementLoopRecord({
+        targetName: verifiableContextName,
+        buildPlanId: options.buildPlanId,
+        runId: options.runId,
+        loopIndex: options.loopIndex,
+        shellPath: shell.rootPath,
+        loopRootPath: shell.loopRootPath,
+        buildPlanBeforePath: shell.buildPlanBeforePath,
+        buildPlanAfterPath: shell.buildPlanAfterPath,
+        promptLogPath: shell.promptLogPath,
+        eventLogPath: shell.eventLogPath,
+        statusLogPath: shell.statusLogPath,
+        preservedShellManifestPath,
+        changed: session.changed,
+        validation: session.validation,
+        result: session.status,
+        summary: session.summary,
+    }), {
+        targetName: verifiableContextName,
+        buildPlanId: options.buildPlanId,
+        maxLoops: options.maxLoops,
+        maxAttempts: options.maxAttempts,
+    });
+    if (session.status === "updated") {
+        updateBuildPlanOrigin({
+            verifiableContextPath: options.verifiableContextPath,
+            selectedBuildPlanId: options.buildPlanId,
+            localDraft: true,
+        });
+    }
+    return {
+        status: session.status,
+        changed: session.changed,
+        validation: session.validation,
+        summary: session.summary,
+        shellPath: shell.rootPath,
+        loopRootPath: shell.loopRootPath,
+    };
+}

package/dist/packages/build-plans/authoring/index.d.ts

@@ -0,0 +1,4 @@
+export * as authoring from "./build-plan-authoring.js";
+export * as editSession from "./build-plan-edit-session.js";
+export * as editUtils from "./lib/build-plan-edit-utils.js";
+export * as improvement from "./build-plan-improvement.js";

package/dist/packages/build-plans/authoring/index.js

@@ -0,0 +1,4 @@
+export * as authoring from "./build-plan-authoring.js";
+export * as editSession from "./build-plan-edit-session.js";
+export * as editUtils from "./lib/build-plan-edit-utils.js";
+export * as improvement from "./build-plan-improvement.js";

package/dist/packages/{methods/authoring/lib/method-edit-utils.d.ts → build-plans/authoring/lib/build-plan-edit-utils.d.ts}

@@ -1,9 +1,9 @@
 export declare function copyDirectory(sourcePath: string, targetPath: string): void;
 export declare function directoriesMatch(leftPath: string, rightPath: string): boolean;
-export interface MethodEditShellArtifacts {
+export interface BuildPlanEditShellArtifacts {
     rootPath: string;
-    methodBeforePath: string;
-    methodAfterPath: string;
+    buildPlanBeforePath: string;
+    buildPlanAfterPath: string;
     promptLogPath: string;
     eventLogPath: string;
     statusLogPath: string;

package/dist/packages/build-plans/build-plan-resolution.d.ts

@@ -0,0 +1,6 @@
+export declare const DEFAULT_BUILD_PLAN_ID = "interf-default";
+export interface BuildPlanSelectionLike {
+    build_plan?: string | null;
+}
+export declare function buildPlanIdForSourcePreparationConfig(preparationConfig: BuildPlanSelectionLike | null | undefined): string | null;
+export declare function resolveBuildPlanId(selection: BuildPlanSelectionLike | null | undefined, fallback?: string): string;

package/dist/packages/build-plans/build-plan-resolution.js

@@ -0,0 +1,7 @@
+export const DEFAULT_BUILD_PLAN_ID = "interf-default";
+export function buildPlanIdForSourcePreparationConfig(preparationConfig) {
+    return preparationConfig?.build_plan ?? null;
+}
+export function resolveBuildPlanId(selection, fallback = DEFAULT_BUILD_PLAN_ID) {
+    return buildPlanIdForSourcePreparationConfig(selection) ?? fallback;
+}

package/dist/packages/build-plans/index.d.ts

@@ -0,0 +1,2 @@
+export * as buildPlanResolution from "./build-plan-resolution.js";
+export { DEFAULT_BUILD_PLAN_ID, buildPlanIdForSourcePreparationConfig, resolveBuildPlanId, } from "./build-plan-resolution.js";

package/dist/packages/build-plans/index.js

@@ -0,0 +1,2 @@
+export * as buildPlanResolution from "./build-plan-resolution.js";
+export { DEFAULT_BUILD_PLAN_ID, buildPlanIdForSourcePreparationConfig, resolveBuildPlanId, } from "./build-plan-resolution.js";

package/dist/packages/build-plans/package/build-plan-definitions.d.ts

@@ -0,0 +1,61 @@
+import { type LocalBuildPlanDefinition } from "./local-build-plans.js";
+import type { BuildPlanEngineApi } from "../../engine/build/lib/schema.js";
+import type { BuildPlanId, RuntimeContractType } from "../../contracts/lib/schema.js";
+import { type ContextInterface, type ContextInterfaceArtifactId, type BuildPlanInputSpec } from "./context-interface.js";
+export interface BuildPlanStarterDoc {
+    relativePath: string;
+    content: string;
+}
+export interface BuildPlanStageDefinition {
+    id: string;
+    label: string;
+    description: string;
+    contractType: RuntimeContractType;
+    skillDir: string;
+    /**
+     * Role hint declared by the Build Plan package. Defaults to `general` when
+     * absent; mapped to a connected agent via the user's role-map at run
+     * time.
+     */
+    role: string;
+    reads: ContextInterfaceArtifactId[];
+    writes: ContextInterfaceArtifactId[];
+}
+export interface BuildPlanDefinition<TId extends string> {
+    id: TId;
+    engineApi?: BuildPlanEngineApi;
+    purpose?: {
+        label: string;
+        taskHint: string;
+    };
+    inputs?: BuildPlanInputSpec[];
+    label: string;
+    hint: string;
+    recommended?: boolean;
+    contextInterface?: ContextInterface;
+    schema?: ContextInterface;
+    stages: BuildPlanStageDefinition[];
+    stagePolicyNotes?: Record<string, string[]>;
+    starterDocs?: BuildPlanStarterDoc[];
+    scope?: "builtin" | "user" | "local";
+}
+export type ResolvedBuildPlanId = string;
+export declare function standaloneBuildPlanDefinitionFromLocalPackage(local: LocalBuildPlanDefinition): BuildPlanDefinition<string>;
+export declare function listBuildPlanChoices(prepDataDir?: string): BuildPlanDefinition<string>[];
+export declare function getBuildPlan(buildPlanId: ResolvedBuildPlanId, options?: {
+    prepDataDir?: string;
+}): BuildPlanDefinition<string>;
+export declare function getActiveBuildPlan(verifiableContextPath: string): BuildPlanDefinition<string>;
+export declare function resolveVerifiableContextBuildPlanId(value: unknown): ResolvedBuildPlanId | null;
+export declare function resolveBuildPlanFromConfig(config: unknown): ResolvedBuildPlanId | null;
+export declare function resolveRequiredBuildPlanFromConfig(config: unknown, label?: string): ResolvedBuildPlanId;
+export declare function getBuildPlanStageDefinition(buildPlanId: BuildPlanId, stage: string, prepDataDir?: string): BuildPlanStageDefinition | null;
+export declare function getBuildPlanStagePosition(buildPlanId: BuildPlanId, stage: string, prepDataDir?: string): {
+    stageIndex: number;
+    stageTotal: number;
+    stages: string[];
+} | null;
+export declare function getBuildPlanStages(buildPlanId: BuildPlanId, prepDataDir?: string): string[];
+export declare function getActiveBuildPlanStages(verifiableContextPath: string): string[];
+export declare function getActiveBuildPlanStagePolicyNotes(verifiableContextPath: string, stage: string): string[];
+export declare function formatActiveBuildPlanStageLabel(verifiableContextPath: string, stage: string): string;