@interf/compiler 0.18.0 → 0.22.0

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;

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

@@ -0,0 +1,214 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { builtinBuildPlanPackagePath, isBuildPlanId, listLocalBuildPlanDefinitions, loadLocalBuildPlanDefinition, loadBuildPlanDefinitionFromDir, mergeStagePolicyNotesForStages, } from "./local-build-plans.js";
+import { listUserBuildPlanDefinitions, loadUserBuildPlanDefinition, } from "./user-build-plans.js";
+import { warnInterf } from "../../contracts/utils/logger.js";
+import { buildPlanPackagePathForVerifiableContext } from "../../engine/build/verifiable-context-paths.js";
+import { asPreparationDataDir, preparationBuildPlanPackagePath } from "../../contracts/lib/preparation-paths.js";
+import { resolveSourceControlPath } from "../../project/interf.js";
+import { deriveBuildPlanInputsFromContextInterface, } from "./context-interface.js";
+const DEFAULT_BUILD_PLAN_ID = "interf-default";
+let builtinDefaultBuildPlanCache = null;
+function toBuildPlanStages(stages) {
+    return stages.map((stage) => ({
+        id: stage.id,
+        label: stage.label,
+        description: stage.description ?? stage.label,
+        contractType: stage.contract_type,
+        skillDir: stage.skill_dir ?? stage.id,
+        role: stage.role && stage.role.trim().length > 0 ? stage.role : "general",
+        reads: [...stage.reads],
+        writes: [...stage.writes],
+    }));
+}
+export function standaloneBuildPlanDefinitionFromLocalPackage(local) {
+    if (!local.stages || local.stages.length === 0) {
+        throw new Error(`Build Plan package "${local.id}" is missing explicit stages. Local Build Plan packages must be standalone.`);
+    }
+    const stages = toBuildPlanStages(local.stages);
+    const contextInterface = local.build_plan_schema;
+    const inputs = local.inputs?.length
+        ? [...local.inputs]
+        : deriveBuildPlanInputsFromContextInterface(contextInterface);
+    return {
+        id: local.id,
+        engineApi: local.engine_api ?? {
+            kind: "build",
+            version: 1,
+        },
+        ...(local.purpose
+            ? {
+                purpose: {
+                    label: local.purpose.label,
+                    taskHint: local.purpose.task_hint,
+                },
+            }
+            : {}),
+        inputs,
+        label: local.label,
+        hint: local.hint,
+        recommended: false,
+        contextInterface,
+        ...(contextInterface ? { schema: contextInterface } : {}),
+        stages,
+        stagePolicyNotes: mergeStagePolicyNotesForStages(stages, undefined, local.stage_policy_notes),
+        starterDocs: [...local.starter_docs],
+        scope: "local",
+    };
+}
+function getBuiltinDefaultBuildPlan() {
+    if (builtinDefaultBuildPlanCache)
+        return builtinDefaultBuildPlanCache;
+    const local = loadBuildPlanDefinitionFromDir(builtinBuildPlanPackagePath(DEFAULT_BUILD_PLAN_ID));
+    if (!local) {
+        throw new Error(`Missing built-in Interf Build Plan package at public-repo/build-plans/${DEFAULT_BUILD_PLAN_ID}.`);
+    }
+    const resolved = standaloneBuildPlanDefinitionFromLocalPackage(local);
+    builtinDefaultBuildPlanCache = {
+        ...resolved,
+        id: DEFAULT_BUILD_PLAN_ID,
+        recommended: true,
+        scope: "builtin",
+    };
+    return builtinDefaultBuildPlanCache;
+}
+function listBuiltinBuildPlans() {
+    return [getBuiltinDefaultBuildPlan()];
+}
+function resolveBuildPlanFromLocal(buildPlanId, prepDataDir) {
+    const local = loadLocalBuildPlanDefinition(prepDataDir, buildPlanId);
+    if (!local)
+        return null;
+    const resolved = standaloneBuildPlanDefinitionFromLocalPackage(local);
+    return resolved;
+}
+function resolveBuildPlanFromUserLibrary(buildPlanId) {
+    const user = loadUserBuildPlanDefinition(buildPlanId);
+    if (!user)
+        return null;
+    const resolved = standaloneBuildPlanDefinitionFromLocalPackage(user);
+    return { ...resolved, scope: "user" };
+}
+export function listBuildPlanChoices(prepDataDir) {
+    const builtins = listBuiltinBuildPlans();
+    const buildPlansById = new Map();
+    for (const buildPlan of builtins) {
+        buildPlansById.set(buildPlan.id, buildPlan);
+    }
+    for (const definition of listUserBuildPlanDefinitions()) {
+        try {
+            const buildPlan = resolveBuildPlanFromUserLibrary(definition.id);
+            if (buildPlan)
+                buildPlansById.set(buildPlan.id, buildPlan);
+        }
+        catch (error) {
+            warnInterf(`Warning: skipping user Build Plan "${definition.id}" because it could not be resolved cleanly: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (!prepDataDir)
+        return [...buildPlansById.values()];
+    for (const definition of listLocalBuildPlanDefinitions(prepDataDir)) {
+        try {
+            const buildPlan = resolveBuildPlanFromLocal(definition.id, prepDataDir);
+            if (buildPlan)
+                buildPlansById.set(buildPlan.id, buildPlan);
+        }
+        catch (error) {
+            warnInterf(`Warning: skipping local Build Plan "${definition.id}" because it could not be resolved cleanly: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return [...buildPlansById.values()];
+}
+export function getBuildPlan(buildPlanId, options = {}) {
+    if (options.prepDataDir) {
+        const local = resolveBuildPlanFromLocal(buildPlanId, options.prepDataDir);
+        if (local)
+            return local;
+    }
+    const user = resolveBuildPlanFromUserLibrary(buildPlanId);
+    if (user)
+        return user;
+    const builtin = listBuiltinBuildPlans().find((candidate) => candidate.id === buildPlanId);
+    if (builtin)
+        return builtin;
+    if (options.prepDataDir) {
+        throw new Error(`No Build Plan package "${buildPlanId}" found in this Preparation, in your user library, or among bundled Build Plan packages. Looked under ${preparationBuildPlanPackagePath(asPreparationDataDir(options.prepDataDir), buildPlanId)} and ~/.interf/build-plans/${buildPlanId}.`);
+    }
+    throw new Error(`Build Plan package "${buildPlanId}" is not built-in and no Preparation data directory was provided to look for a local override.`);
+}
+export function getActiveBuildPlan(verifiableContextPath) {
+    const buildPlanPath = buildPlanPackagePathForVerifiableContext(verifiableContextPath);
+    if (existsSync(join(buildPlanPath, "build-plan.json"))) {
+        const local = loadBuildPlanDefinitionFromDir(buildPlanPath);
+        if (!local) {
+            throw new Error(`Local Build Plan package at ${buildPlanPath} is missing or invalid. Interf build runs the local package directly; recreate or reseed this verifiable context.`);
+        }
+        return standaloneBuildPlanDefinitionFromLocalPackage(local);
+    }
+    throw new Error(`Missing local Build Plan package at ${buildPlanPath}. Interf build runs the local package directly, so recreate or reseed this verifiable context under ${resolveSourceControlPath(verifiableContextPath)}.`);
+}
+export function resolveVerifiableContextBuildPlanId(value) {
+    if (typeof value === "string" && isBuildPlanId(value)) {
+        return value;
+    }
+    return null;
+}
+export function resolveBuildPlanFromConfig(config) {
+    if (!config || typeof config !== "object")
+        return null;
+    const raw = config;
+    return resolveVerifiableContextBuildPlanId(raw.build_plan);
+}
+export function resolveRequiredBuildPlanFromConfig(config, label = "verifiable-context config") {
+    const buildPlanId = resolveBuildPlanFromConfig(config);
+    if (!buildPlanId) {
+        throw new Error(`Missing or invalid Build Plan in ${label}.`);
+    }
+    return buildPlanId;
+}
+function resolveBuildPlanDefinitionForStageMetadata(buildPlanId, prepDataDir) {
+    if (prepDataDir &&
+        existsSync(join(buildPlanPackagePathForVerifiableContext(prepDataDir), "build-plan.json"))) {
+        return getActiveBuildPlan(prepDataDir);
+    }
+    return getBuildPlan(buildPlanId, { prepDataDir });
+}
+function formatBuildPlanStageLabel(buildPlan, stage) {
+    const stageIndex = buildPlan.stages.findIndex((candidate) => candidate.id === stage);
+    if (stageIndex === -1) {
+        throw new Error(`Stage "${stage}" is not part of the build runtime.`);
+    }
+    const stageDefinition = buildPlan.stages[stageIndex];
+    if (!stageDefinition) {
+        throw new Error(`Stage "${stage}" is not part of the build runtime.`);
+    }
+    return `Stage ${stageIndex + 1}/${buildPlan.stages.length} - ${stageDefinition.label}`;
+}
+export function getBuildPlanStageDefinition(buildPlanId, stage, prepDataDir) {
+    const buildPlan = resolveBuildPlanDefinitionForStageMetadata(buildPlanId, prepDataDir);
+    return buildPlan.stages.find((candidate) => candidate.id === stage) ?? null;
+}
+export function getBuildPlanStagePosition(buildPlanId, stage, prepDataDir) {
+    const stages = getBuildPlanStages(buildPlanId, prepDataDir);
+    const stageIndex = stages.findIndex((candidate) => candidate === stage);
+    if (stageIndex === -1)
+        return null;
+    return {
+        stageIndex: stageIndex + 1,
+        stageTotal: stages.length,
+        stages: [...stages],
+    };
+}
+export function getBuildPlanStages(buildPlanId, prepDataDir) {
+    return resolveBuildPlanDefinitionForStageMetadata(buildPlanId, prepDataDir).stages.map((definition) => definition.id);
+}
+export function getActiveBuildPlanStages(verifiableContextPath) {
+    return getActiveBuildPlan(verifiableContextPath).stages.map((definition) => definition.id);
+}
+export function getActiveBuildPlanStagePolicyNotes(verifiableContextPath, stage) {
+    const buildPlan = getActiveBuildPlan(verifiableContextPath);
+    return [...(buildPlan.stagePolicyNotes?.[stage] ?? [])];
+}
+export function formatActiveBuildPlanStageLabel(verifiableContextPath, stage) {
+    return formatBuildPlanStageLabel(getActiveBuildPlan(verifiableContextPath), stage);
+}

package/dist/packages/{methods/package/method-helpers.d.ts → build-plans/package/build-plan-helpers.d.ts}

@@ -1,14 +1,14 @@
-import { type LocalInstructionMode, type RuntimeInstructionMode, type RuntimeStageInstructions } from "../../engine/compile/lib/schema.js";
-export interface MethodReporter {
+import { type LocalInstructionMode, type RuntimeInstructionMode, type RuntimeStageInstructions } from "../../engine/build/lib/schema.js";
+export interface BuildPlanReporter {
     line?: (message: string) => void;
     blankLine?: () => void;
 }
-export interface MethodStageResult {
+export interface BuildPlanStageResult {
     ok: boolean;
     code: number;
     summary?: string | null;
 }
-export declare function methodCompileStageDirectory(stageDir: string): string;
+export declare function buildPlanStageDirectory(stageDir: string): string;
 export interface LocalSkillContractExtension {
     reads: string[];
     count: number;
@@ -19,6 +19,6 @@ export interface LocalSkillContractExtension {
 }
 export declare function buildLocalSkillContractExtension(rootPath: string, directories: string[], purpose: string): LocalSkillContractExtension;
 export declare function buildStageInstructions(stageSkillDir: string, localSkills: LocalSkillContractExtension): RuntimeStageInstructions;
-export declare function reportLine(reporter: MethodReporter | undefined, message: string): void;
-export declare function reportBlankLine(reporter: MethodReporter | undefined): void;
-export declare function reportValidationFailure(reporter: MethodReporter | undefined, summary: string, errors?: string[]): void;
+export declare function reportLine(reporter: BuildPlanReporter | undefined, message: string): void;
+export declare function reportBlankLine(reporter: BuildPlanReporter | undefined): void;
+export declare function reportValidationFailure(reporter: BuildPlanReporter | undefined, summary: string, errors?: string[]): void;

package/dist/packages/{methods/package/method-helpers.js → build-plans/package/build-plan-helpers.js}

@@ -3,10 +3,10 @@ import { join, relative, sep } from "node:path";
 import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
 import { parseJsonFrontmatter } from "../../contracts/utils/parse.js";
 import { isMarkdownFile } from "../../contracts/utils/file-types.js";
-import { COMPILED_METHOD_DIR, methodPackagePathForCompiled } from "../../engine/compile/compiled-paths.js";
+import { VERIFIABLE_CONTEXT_BUILD_PLAN_DIR, buildPlanPackagePathForVerifiableContext } from "../../engine/build/verifiable-context-paths.js";
 const LOCAL_SKILL_READ_LIMIT = 50;
-export function methodCompileStageDirectory(stageDir) {
-    return `${COMPILED_METHOD_DIR}/compile/stages/${stageDir}`;
+export function buildPlanStageDirectory(stageDir) {
+    return `${VERIFIABLE_CONTEXT_BUILD_PLAN_DIR}/build/stages/${stageDir}`;
 }
 function emptyLocalSkillContractExtension() {
     return {
@@ -30,10 +30,10 @@ function readLocalInstructionMode(filePath) {
 }
 function collectLocalSkillDocs(rootPath, directories) {
     const docs = new Map();
-    const methodRoot = methodPackagePathForCompiled(rootPath);
-    const rootReadme = join(methodRoot, "README.md");
+    const buildPlanRoot = buildPlanPackagePathForVerifiableContext(rootPath);
+    const rootReadme = join(buildPlanRoot, "README.md");
     if (existsSync(rootReadme)) {
-        const read = projectMethodReadPath(rootPath, rootReadme);
+        const read = projectBuildPlanReadPath(rootPath, rootReadme);
         docs.set(read, {
             read,
             absolutePath: rootReadme,
@@ -43,7 +43,7 @@ function collectLocalSkillDocs(rootPath, directories) {
     for (const directory of directories) {
         const absoluteDirectory = resolveAuthoringDirectory(rootPath, directory);
         for (const filePath of listFilesRecursive(absoluteDirectory, isMarkdownFile)) {
-            const read = projectMethodReadPath(rootPath, filePath);
+            const read = projectBuildPlanReadPath(rootPath, filePath);
             docs.set(read, {
                 read,
                 absolutePath: filePath,
@@ -56,21 +56,21 @@ function collectLocalSkillDocs(rootPath, directories) {
         .slice(0, LOCAL_SKILL_READ_LIMIT);
 }
 function resolveAuthoringDirectory(rootPath, directory) {
-    if (directory === COMPILED_METHOD_DIR) {
-        return methodPackagePathForCompiled(rootPath);
+    if (directory === VERIFIABLE_CONTEXT_BUILD_PLAN_DIR) {
+        return buildPlanPackagePathForVerifiableContext(rootPath);
     }
-    if (directory.startsWith(`${COMPILED_METHOD_DIR}${sep}`) || directory.startsWith(`${COMPILED_METHOD_DIR}/`)) {
-        const relativeMethodPath = directory.replace(/^method[\\/]/, "");
-        return join(methodPackagePathForCompiled(rootPath), relativeMethodPath);
+    if (directory.startsWith(`${VERIFIABLE_CONTEXT_BUILD_PLAN_DIR}${sep}`) || directory.startsWith(`${VERIFIABLE_CONTEXT_BUILD_PLAN_DIR}/`)) {
+        const relativeBuildPlanPath = directory.replace(/^build-plan[\\/]/, "");
+        return join(buildPlanPackagePathForVerifiableContext(rootPath), relativeBuildPlanPath);
     }
     return join(rootPath, directory);
 }
-function projectMethodReadPath(rootPath, absolutePath) {
-    const methodRoot = methodPackagePathForCompiled(rootPath);
-    const normalizedMethodRoot = `${methodRoot}${sep}`;
-    if (absolutePath === methodRoot || absolutePath.startsWith(normalizedMethodRoot)) {
-        const relativeMethodPath = relative(methodRoot, absolutePath);
-        return relative(rootPath, join(rootPath, COMPILED_METHOD_DIR, relativeMethodPath));
+function projectBuildPlanReadPath(rootPath, absolutePath) {
+    const buildPlanRoot = buildPlanPackagePathForVerifiableContext(rootPath);
+    const normalizedBuildPlanRoot = `${buildPlanRoot}${sep}`;
+    if (absolutePath === buildPlanRoot || absolutePath.startsWith(normalizedBuildPlanRoot)) {
+        const relativeBuildPlanPath = relative(buildPlanRoot, absolutePath);
+        return relative(rootPath, join(rootPath, VERIFIABLE_CONTEXT_BUILD_PLAN_DIR, relativeBuildPlanPath));
     }
     return relative(rootPath, absolutePath);
 }
@@ -98,8 +98,8 @@ function buildContractExtensionFromDocs(docs, directories, purpose) {
         notes: [
             readNotice,
             localMode === "override"
-                ? `${purpose} One or more local docs declare \`mode: override\`, so their Method instructions replace Interf's bundled stage instructions for this run. They still do not bypass coverage proof, evidence weighting, required writes, or deterministic runtime reconciliation.`
-                : `${purpose} These local Method docs can refine the stage, but they do not bypass coverage proof, evidence weighting, required writes, or deterministic runtime reconciliation.`,
+                ? `${purpose} One or more local docs declare \`mode: override\`, so their Build Plan instructions replace Interf's bundled stage instructions for this run. They still do not bypass coverage proof, evidence weighting, required writes, or deterministic runtime reconciliation.`
+                : `${purpose} These local Build Plan docs can refine the stage, but they do not bypass coverage proof, evidence weighting, required writes, or deterministic runtime reconciliation.`,
         ],
         localMode,
         effectiveMode: localMode ?? "builtin",