@interf/compiler 0.21.0 → 0.22.2

package/dist/packages/{methods → build-plans}/package/context-interface.js

@@ -3,19 +3,19 @@ import { join } from "node:path";
 import { z } from "zod";
 import { warnInterf } from "../../contracts/utils/logger.js";
 import { readJsonFileUnchecked } from "../../contracts/utils/parse.js";
-import { MethodCompiledSchemaSchema, MethodArtifactIdSchema, } from "../../engine/compile/lib/schema.js";
-import { listBuiltinCompiledArtifactSpecs, requiredCompiledArtifactOwners, } from "./builtin-compiled-method.js";
-// Method packages define the context interface. The compiler persists the
+import { BuildPlanContextSchemaSchema, BuildPlanArtifactIdSchema, } from "../../engine/build/lib/schema.js";
+import { listBuiltinBuildPlanArtifactSpecs, requiredBuildPlanArtifactOwners, } from "./builtin-build-plan.js";
+// Build Plan packages define the context interface. The local engine persists the
 // same schema on disk, but higher layers should prefer this boundary when they
-// mean "the Method-declared shape a portable context must implement."
-export const CONTEXT_INTERFACE_FILE = "method.schema.json";
-export const ContextInterfaceSchema = MethodCompiledSchemaSchema;
+// mean "the Build Plan-declared shape verifiable context must implement."
+export const CONTEXT_INTERFACE_FILE = "build-plan.schema.json";
+export const ContextInterfaceSchema = BuildPlanContextSchemaSchema;
 // Package-owned input contract for authoring, review, and future authoring flows.
-// This does not change compiler execution semantics; it describes what data a
-// Method expects to organize before the compiler materializes the context
+// This does not change build execution semantics; it describes what data a
+// Build Plan expects to organize before the local engine materializes the context
 // interface on disk.
-export const MethodInputSpecSchema = z.object({
-    id: MethodArtifactIdSchema,
+export const BuildPlanInputSpecSchema = z.object({
+    id: BuildPlanArtifactIdSchema,
     label: z.string().min(1),
     description: z.string().min(1),
     required: z.boolean().default(false),
@@ -24,10 +24,10 @@ export const MethodInputSpecSchema = z.object({
 function normalizeContextInterface(contextInterface) {
     return {
         ...contextInterface,
-        kind: "method-schema",
+        kind: "build-plan-schema",
     };
 }
-function artifactToMethodArtifact(artifact) {
+function artifactToBuildPlanArtifact(artifact) {
     const path = artifact.shape.kind === "path" ? artifact.shape.path : artifact.id;
     return {
         id: artifact.id,
@@ -40,7 +40,7 @@ function artifactToMethodArtifact(artifact) {
     };
 }
 export function listContextInterfaceArtifacts(contextInterface) {
-    return contextInterface.artifacts.map(artifactToMethodArtifact);
+    return contextInterface.artifacts.map(artifactToBuildPlanArtifact);
 }
 function titleCaseArtifactId(artifactId) {
     return artifactId
@@ -59,8 +59,8 @@ export function resolveContextInterfacePath(rootPath) {
 export function contextInterfaceExists(rootPath) {
     return existsSync(contextInterfaceFilePath(rootPath));
 }
-export function contextInterfaceArtifactAbsolutePath(compiledPath, artifact) {
-    return join(compiledPath, artifact.path);
+export function contextInterfaceArtifactAbsolutePath(verifiableContextPath, artifact) {
+    return join(verifiableContextPath, artifact.path);
 }
 export function contextInterfaceArtifactPath(artifact) {
     if (artifact.kind === "file")
@@ -76,7 +76,7 @@ export function summarizeContextInterface(contextInterface) {
         runtimeArtifacts: artifacts.filter((artifact) => artifact.role === "runtime"),
     };
 }
-export function deriveMethodInputsFromContextInterface(contextInterface) {
+export function deriveBuildPlanInputsFromContextInterface(contextInterface) {
     if (!contextInterface)
         return [];
     return listContextInterfaceArtifacts(contextInterface)
@@ -88,13 +88,13 @@ export function deriveMethodInputsFromContextInterface(contextInterface) {
         required: artifact.required,
     }));
 }
-export function buildContextInterface(stages, label = "Method context interface") {
+export function buildContextInterface(stages, label = "Build Plan context interface") {
     return {
-        kind: "method-schema",
+        kind: "build-plan-schema",
         version: 1,
-        target_type: "compiled",
+        target_type: "verifiable-context",
         label,
-        artifacts: listBuiltinCompiledArtifactSpecs().map((artifact) => ({
+        artifacts: listBuiltinBuildPlanArtifactSpecs().map((artifact) => ({
             id: artifact.id,
             description: artifact.description,
             shape: {
@@ -103,7 +103,7 @@ export function buildContextInterface(stages, label = "Method context interface"
                 artifact_kind: artifact.kind === "file" ? "file" : "directory",
             },
             checks: [],
-            built_by_stages: requiredCompiledArtifactOwners(stages, artifact.id),
+            built_by_stages: requiredBuildPlanArtifactOwners(stages, artifact.id),
         })),
     };
 }
@@ -121,12 +121,12 @@ export function readContextInterface(rootPath) {
     const path = contextInterfaceFilePath(rootPath);
     if (!existsSync(path))
         return null;
-    const raw = readJsonFileUnchecked(path, "Method context interface");
+    const raw = readJsonFileUnchecked(path, "Build Plan context interface");
     if (raw === null)
         return null;
     const parsed = ContextInterfaceSchema.safeParse(raw);
     if (!parsed.success) {
-        warnInterf(`Warning: failed to validate Method context interface at ${path}: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`);
+        warnInterf(`Warning: failed to validate Build Plan context interface at ${path}: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`);
         return null;
     }
     return normalizeContextInterface(parsed.data);

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

@@ -0,0 +1,31 @@
+import { type BuildPlanDefinition } from "./build-plan-definitions.js";
+export declare function writeBuildPlanPackageForVerifiableContext(verifiableContextPath: string, buildPlan: BuildPlanDefinition<string>): void;
+export declare function writeBuildPlanPackageToDir(buildPlanDir: string, buildPlan: BuildPlanDefinition<string>, options?: {
+    overwrite?: boolean;
+}): void;
+export declare function seedVerifiableContextBuildPlanPackage(options: {
+    verifiableContextPath: string;
+    prepDataDir: string;
+    buildPlanId: string;
+}): void;
+export declare function createLocalBuildPlanPackageFromTemplate(options: {
+    prepDataDir: string;
+    baseBuildPlanId: string;
+    buildPlanId: string;
+    label: string;
+    hint: string;
+    stagePolicyNotes: Record<string, string[]>;
+}): string;
+export declare function seedLocalBuildPlanPackageFromBase(options: {
+    prepDataDir: string;
+    baseBuildPlanId: string;
+    buildPlanId: string;
+    label: string;
+    hint: string;
+}): string;
+export declare function createScratchLocalBuildPlanPackage(options: {
+    prepDataDir: string;
+    buildPlanId: string;
+    label: string;
+    hint: string;
+}): string;

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

@@ -0,0 +1,466 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { renderVerifiableContextQuerySkill } from "../../engine/agents/lib/shells.js";
+import { copyBuildPlanPackageDirectory, isPortableBuildPlanPackage, patchBuildPlanPackageMetadata, resolveBuildPlanPackageSourcePath, buildPlanDefinitionPath, mergeStagePolicyNotesForStages, } from "./local-build-plans.js";
+import { getBuildPlan, } from "./build-plan-definitions.js";
+import { CONTEXT_INTERFACE_FILE, deriveBuildPlanInputsFromContextInterface, listContextInterfaceArtifacts, summarizeContextInterface, writeContextInterface, writeContextInterfaceFile, } from "./context-interface.js";
+import { buildPlanPackagePathForVerifiableContext } from "../../engine/build/verifiable-context-paths.js";
+function writeBuildPlanStarterDocs(dirPath, docs, options) {
+    for (const doc of docs ?? []) {
+        const targetPath = join(dirPath, doc.relativePath);
+        if (!options.overwrite && existsSync(targetPath))
+            continue;
+        mkdirSync(dirname(targetPath), { recursive: true });
+        writeFileSync(targetPath, doc.content);
+    }
+}
+function writeBuildPlanPackageJson(rootPath, buildPlan, options) {
+    const targetPath = join(rootPath, "build-plan.json");
+    if (!options.overwrite && existsSync(targetPath))
+        return;
+    const inputs = buildPlan.inputs?.length
+        ? buildPlan.inputs
+        : deriveBuildPlanInputsFromContextInterface(buildPlan.contextInterface ?? buildPlan.schema);
+    writeFileSync(targetPath, `${JSON.stringify({
+        id: buildPlan.id,
+        type: "build-plan",
+        engine_api: buildPlan.engineApi ?? {
+            kind: "build",
+            version: 1,
+        },
+        ...(buildPlan.purpose
+            ? {
+                purpose: {
+                    label: buildPlan.purpose.label,
+                    task_hint: buildPlan.purpose.taskHint,
+                },
+            }
+            : {}),
+        ...(inputs.length > 0 ? { inputs } : {}),
+        label: buildPlan.label,
+        hint: buildPlan.hint,
+        stages: buildPlan.stages.map((stage) => ({
+            id: stage.id,
+            label: stage.label,
+            description: stage.description,
+            contract_type: stage.contractType,
+            skill_dir: stage.skillDir,
+            reads: stage.reads,
+            writes: stage.writes,
+        })),
+        ...(buildPlan.stagePolicyNotes ? { stage_policy_notes: buildPlan.stagePolicyNotes } : {}),
+    }, null, 2)}\n`);
+}
+function renderBuildPlanReadme(buildPlan) {
+    const contextInterface = buildPlan.contextInterface ?? buildPlan.schema ?? null;
+    const stageLines = buildPlan.stages
+        .map((stage) => `- \`${stage.id}\` — ${stage.description} (${stage.contractType}; reads: ${stage.reads.join(", ")}; writes: ${stage.writes.join(", ")})`)
+        .join("\n");
+    const interfaceSummary = contextInterface
+        ? summarizeContextInterface(contextInterface)
+        : null;
+    const contextInterfaceArtifacts = contextInterface
+        ? listContextInterfaceArtifacts(contextInterface)
+        : [];
+    const contextInterfaceLines = contextInterfaceArtifacts.length > 0
+        ? contextInterfaceArtifacts
+            .map((artifact) => `- \`${artifact.id}\` — ${artifact.role} ${artifact.kind} Artifact at \`${artifact.path}\`: ${artifact.description}`)
+            .join("\n")
+        : null;
+    const inputs = buildPlan.inputs?.length
+        ? buildPlan.inputs
+        : deriveBuildPlanInputsFromContextInterface(contextInterface);
+    const inputLines = inputs.length > 0
+        ? inputs
+            .map((input) => `- \`${input.id}\` — ${input.label}: ${input.description}${input.required ? " (required)" : ""}${input.examples?.length ? ` Example inputs: ${input.examples.join("; ")}` : ""}`)
+            .join("\n")
+        : null;
+    const contextInterfaceSummaryLines = interfaceSummary
+        ? [
+            `- Input Artifacts: ${interfaceSummary.inputArtifacts.length > 0 ? interfaceSummary.inputArtifacts.map((artifact) => `\`${artifact.id}\``).join(", ") : "none"}`,
+            `- Working Artifacts: ${interfaceSummary.workingArtifacts.length > 0 ? interfaceSummary.workingArtifacts.map((artifact) => `\`${artifact.id}\``).join(", ") : "none"}`,
+            `- Output Artifacts: ${interfaceSummary.outputArtifacts.length > 0 ? interfaceSummary.outputArtifacts.map((artifact) => `\`${artifact.id}\``).join(", ") : "none"}`,
+            `- Runtime Artifacts: ${interfaceSummary.runtimeArtifacts.length > 0 ? interfaceSummary.runtimeArtifacts.map((artifact) => `\`${artifact.id}\``).join(", ") : "none"}`,
+        ].join("\n")
+        : null;
+    return [
+        `# ${buildPlan.label}`,
+        "",
+        buildPlan.hint,
+        ...(buildPlan.purpose
+            ? [
+                "",
+                "## Purpose",
+                "",
+                `- ${buildPlan.purpose.label}`,
+                `- ${buildPlan.purpose.taskHint}`,
+            ]
+            : []),
+        ...(inputLines
+            ? [
+                "",
+                "## Inputs",
+                "",
+                inputLines,
+            ]
+            : []),
+        ...(contextInterfaceLines
+            ? [
+                "",
+                "## Context Interface",
+                "",
+                ...(contextInterfaceSummaryLines
+                    ? [
+                        contextInterfaceSummaryLines,
+                        "",
+                    ]
+                    : []),
+                "Artifact map:",
+                "",
+                contextInterfaceLines,
+            ]
+            : []),
+        "",
+        "## Package",
+        "",
+        "- `build-plan.json` = Build Plan stage graph, local-engine API target, and build contract mapping",
+        "- `build-plan.schema.json` = deterministic context interface for the Build Plan",
+        "- `improve/`, `build/stages/`, and `use/query/` = human-readable authoring docs",
+        "- Build Plans are standalone: explicit stages, schema, and docs live together in this folder",
+        "- Interf projects native agent shells from these docs for query use, stage execution, and Build Plan improvement loops",
+        "",
+        "## Stages",
+        "",
+        stageLines,
+        "",
+        "Interf runs the local copy of this Build Plan directly from `.interf/build-plan/` inside each verifiable-context output.",
+        "",
+    ].join("\n");
+}
+function renderDerivedBuildPlanReadme(options) {
+    return [
+        `# ${options.label}`,
+        "",
+        options.hint,
+        "",
+        `This Build Plan package was forked from \`${options.baseBuildPlanId}\` and materialized as a standalone package for this kind of agent work.`,
+        "It starts with that Build Plan topology; edit the package when the agent work needs different stages, Artifacts, or checks.",
+        "",
+        "Interf runs the local copy of this package directly. Keep purpose, inputs, context interface, and stage docs self-contained in this folder instead of relying on runtime inheritance.",
+        "",
+        "## Emphasis",
+        "",
+        ...(options.emphasis.length > 0
+            ? options.emphasis.map((entry) => `- ${entry.stageId} (${entry.label}): ${entry.notes.join("; ")}`)
+            : ["- No stage-specific emphasis was added yet."]),
+        "",
+    ].join("\n");
+}
+function renderSeedBuildPlanReadme(options) {
+    return [
+        `# ${options.label}`,
+        "",
+        options.hint,
+        "",
+        `This Build Plan package was forked from \`${options.baseBuildPlanId}\` as a standalone local package.`,
+        "It starts with that Build Plan topology; edit the package when the agent work needs different stages, Artifacts, or checks.",
+        "",
+        "Interf runs the local copy of this package directly. Refine purpose, inputs, context interface, and stage instructions in this folder instead of relying on inheritance.",
+        "",
+    ].join("\n");
+}
+function renderScratchBuildPlanReadme(options) {
+    return [
+        `# ${options.label}`,
+        "",
+        options.hint,
+        "",
+        "This Build Plan package is a neutral from-scratch authoring scaffold.",
+        "",
+        "It is not copied from `interf-default`, and its placeholder stage is not a recommended topology.",
+        "Replace purpose, inputs, context interface, stages, stage docs, proof rules, and query guidance with the Build Plan this source data and task actually need.",
+        "",
+    ].join("\n");
+}
+function renderImproveSkill(buildPlan) {
+    return [
+        "# Build Plan Improvement",
+        "",
+        `Build Plan package: ${buildPlan.id}`,
+        "",
+        "This file is the editable authoring source for Interf's generated native Build Plan improver shell.",
+        "The improver edits this local package directly.",
+        "",
+        "Default loop:",
+        "1. Read the loop context first.",
+        "2. Review preserved stage shells, runtime logs, and saved test runs from failed attempts.",
+        "3. Edit only the local Build Plan package for this verifiable context to create a better Build Plan implementation for this kind of agent work.",
+        `4. Keep purpose, inputs, \`build-plan.json\`, \`${CONTEXT_INTERFACE_FILE}\`, and any changed stage docs aligned.`,
+        "",
+        "Guardrails:",
+        "- do not edit checks, test specs, or source artifacts",
+        "- do not hardcode expected answers into Build Plan docs",
+        "- keep this package standalone; do not rely on runtime inheritance",
+        "- keep the Build Plan stack coherent: purpose, inputs, context interface, and stages should describe the same job",
+        "- prefer small, defensible Build Plan changes over random churn",
+        "",
+    ].join("\n");
+}
+function renderStageSkill(buildPlan, stage) {
+    const notes = buildPlan.stagePolicyNotes?.[stage.id] ?? [];
+    const abstractRules = stage.contractType === "build-file-evidence"
+        ? [
+            "- Valid abstract forms for deterministic validation are:",
+            '  - frontmatter key `"abstract"` with a real sentence, or',
+            "  - a markdown heading `## Abstract` followed by at least one sentence",
+            "- A bare `Abstract` label without markdown heading syntax does not count.",
+        ]
+        : [];
+    return [
+        `# ${stage.label}`,
+        "",
+        stage.description,
+        "",
+        "## Stage Contract",
+        "",
+        `- Contract type: \`${stage.contractType}\``,
+        `- Reads Artifacts: ${stage.reads.map((artifactId) => `\`${artifactId}\``).join(", ")}`,
+        `- Writes Artifacts: ${stage.writes.map((artifactId) => `\`${artifactId}\``).join(", ")}`,
+        "",
+        "## Requirements",
+        "",
+        "- Treat `build-plan.json` and `build-plan.schema.json` as the authoritative package contract for this stage.",
+        "- Read only from the declared input Artifacts unless this package explicitly documents broader Build Plan behavior.",
+        "- Write only inside the declared output Artifacts for this stage. Do not invent undeclared Artifacts or implicit outputs.",
+        "- Keep stage instructions, artifact ownership, and Build Plan checks aligned when you change this stage.",
+        "- Treat runtime files as proof and execution state, not as the source of truth for Build Plan behavior.",
+        "- Prefer direct file-reading and search tools over shell commands for routine file inspection.",
+        ...abstractRules,
+        "",
+        ...(notes.length > 0
+            ? [
+                "## Notes",
+                "",
+                ...notes.map((note) => `- ${note}`),
+                "",
+            ]
+            : []),
+    ].join("\n");
+}
+export function writeBuildPlanPackageForVerifiableContext(verifiableContextPath, buildPlan) {
+    writeBuildPlanPackageToDir(buildPlanPackagePathForVerifiableContext(verifiableContextPath), buildPlan);
+}
+export function writeBuildPlanPackageToDir(buildPlanDir, buildPlan, options = {}) {
+    const overwrite = options.overwrite ?? true;
+    mkdirSync(join(buildPlanDir, "improve"), { recursive: true });
+    mkdirSync(join(buildPlanDir, "use", "query"), { recursive: true });
+    mkdirSync(join(buildPlanDir, "build", "stages"), { recursive: true });
+    for (const stage of buildPlan.stages) {
+        mkdirSync(join(buildPlanDir, "build", "stages", stage.skillDir), { recursive: true });
+    }
+    writeBuildPlanPackageJson(buildPlanDir, buildPlan, { overwrite });
+    if (overwrite || !existsSync(join(buildPlanDir, CONTEXT_INTERFACE_FILE))) {
+        const contextInterface = buildPlan.contextInterface ?? buildPlan.schema;
+        if (contextInterface) {
+            writeContextInterface(buildPlanDir, {
+                ...contextInterface,
+                label: contextInterface.label || `${buildPlan.label} Build Plan schema`,
+            });
+        }
+        else {
+            writeContextInterfaceFile(buildPlanDir, buildPlan.stages, `${buildPlan.label} Build Plan schema`);
+        }
+    }
+    if (overwrite || !existsSync(join(buildPlanDir, "README.md"))) {
+        writeFileSync(join(buildPlanDir, "README.md"), renderBuildPlanReadme(buildPlan));
+    }
+    if (overwrite || !existsSync(join(buildPlanDir, "improve", "SKILL.md"))) {
+        writeFileSync(join(buildPlanDir, "improve", "SKILL.md"), renderImproveSkill(buildPlan));
+    }
+    if (overwrite || !existsSync(join(buildPlanDir, "use", "query", "SKILL.md"))) {
+        writeFileSync(join(buildPlanDir, "use", "query", "SKILL.md"), renderVerifiableContextQuerySkill());
+    }
+    for (const stage of buildPlan.stages) {
+        const targetPath = join(buildPlanDir, "build", "stages", stage.skillDir, "SKILL.md");
+        if (overwrite || !existsSync(targetPath)) {
+            writeFileSync(targetPath, renderStageSkill(buildPlan, stage));
+        }
+    }
+    writeBuildPlanStarterDocs(buildPlanDir, buildPlan.starterDocs, { overwrite });
+}
+export function seedVerifiableContextBuildPlanPackage(options) {
+    const resolvedBuildPlan = getBuildPlan(options.buildPlanId, {
+        prepDataDir: options.prepDataDir,
+    });
+    const sourceBuildPlanPath = resolveBuildPlanPackageSourcePath(options.prepDataDir, resolvedBuildPlan.id);
+    if (sourceBuildPlanPath && isPortableBuildPlanPackage(sourceBuildPlanPath)) {
+        // Portable seed packages can be copied directly because Build runs the
+        // local package folder without reading source-root Build Plan packages.
+        copyBuildPlanPackageDirectory(sourceBuildPlanPath, buildPlanPackagePathForVerifiableContext(options.verifiableContextPath));
+        patchBuildPlanPackageMetadata(buildPlanPackagePathForVerifiableContext(options.verifiableContextPath), {
+            id: resolvedBuildPlan.id,
+            inputs: resolvedBuildPlan.inputs,
+            label: resolvedBuildPlan.label,
+            hint: resolvedBuildPlan.hint,
+            stagePolicyNotes: resolvedBuildPlan.stagePolicyNotes,
+        });
+        // The verifiable-context README is always derived from the resolved Build Plan;
+        // any hand-authored README belongs in the Preparation-local draft at
+        // <prep-data>/build-plans/<id>/, not in the built copy.
+        writeFileSync(join(buildPlanPackagePathForVerifiableContext(options.verifiableContextPath), "README.md"), renderBuildPlanReadme(resolvedBuildPlan));
+        return;
+    }
+    // Legacy or partially-defined seed packages are resolved once and
+    // materialized into a standalone local package.
+    writeBuildPlanPackageForVerifiableContext(options.verifiableContextPath, resolvedBuildPlan);
+}
+export function createLocalBuildPlanPackageFromTemplate(options) {
+    const targetPath = seedLocalBuildPlanPackageFromBase({
+        prepDataDir: options.prepDataDir,
+        baseBuildPlanId: options.baseBuildPlanId,
+        buildPlanId: options.buildPlanId,
+        label: options.label,
+        hint: options.hint,
+    });
+    const baseBuildPlan = getBuildPlan(options.baseBuildPlanId, {
+        prepDataDir: options.prepDataDir,
+    });
+    const stagePolicyNotes = mergeStagePolicyNotesForStages(baseBuildPlan.stages, baseBuildPlan.stagePolicyNotes, options.stagePolicyNotes);
+    patchBuildPlanPackageMetadata(targetPath, {
+        id: options.buildPlanId,
+        label: options.label,
+        hint: options.hint,
+        stagePolicyNotes,
+    });
+    writeFileSync(join(targetPath, "README.md"), renderDerivedBuildPlanReadme({
+        label: options.label,
+        hint: options.hint,
+        baseBuildPlanId: options.baseBuildPlanId,
+        emphasis: baseBuildPlan.stages
+            .map((stage) => ({
+            stageId: stage.id,
+            label: stage.label,
+            notes: stagePolicyNotes?.[stage.id] ?? [],
+        }))
+            .filter((entry) => entry.notes.length > 0),
+    }));
+    return targetPath;
+}
+export function seedLocalBuildPlanPackageFromBase(options) {
+    const baseBuildPlan = getBuildPlan(options.baseBuildPlanId, {
+        prepDataDir: options.prepDataDir,
+    });
+    const sourceBuildPlanPath = resolveBuildPlanPackageSourcePath(options.prepDataDir, options.baseBuildPlanId);
+    const targetPath = buildPlanDefinitionPath(options.prepDataDir, options.buildPlanId);
+    if (sourceBuildPlanPath && isPortableBuildPlanPackage(sourceBuildPlanPath)) {
+        // Copy directly when the base package is already portable and standalone.
+        copyBuildPlanPackageDirectory(sourceBuildPlanPath, targetPath);
+        patchBuildPlanPackageMetadata(targetPath, {
+            id: options.buildPlanId,
+            inputs: baseBuildPlan.inputs,
+            label: options.label,
+            hint: options.hint,
+        });
+        writeFileSync(join(targetPath, "README.md"), renderSeedBuildPlanReadme({
+            label: options.label,
+            hint: options.hint,
+            baseBuildPlanId: options.baseBuildPlanId,
+        }));
+        return targetPath;
+    }
+    // Base packages are materialized immediately so the new local Build Plan package
+    // is standalone from its first write.
+    const localBuildPlan = {
+        ...baseBuildPlan,
+        id: options.buildPlanId,
+        label: options.label,
+        hint: options.hint,
+        recommended: false,
+        scope: "local",
+        starterDocs: [
+            {
+                relativePath: "README.md",
+                content: renderSeedBuildPlanReadme({
+                    label: options.label,
+                    hint: options.hint,
+                    baseBuildPlanId: options.baseBuildPlanId,
+                }),
+            },
+            ...(baseBuildPlan.starterDocs ?? []).filter((doc) => doc.relativePath !== "README.md"),
+        ],
+    };
+    writeBuildPlanPackageToDir(targetPath, localBuildPlan);
+    return targetPath;
+}
+export function createScratchLocalBuildPlanPackage(options) {
+    const targetPath = buildPlanDefinitionPath(options.prepDataDir, options.buildPlanId);
+    const buildPlan = {
+        id: options.buildPlanId,
+        engineApi: {
+            kind: "build",
+            version: 1,
+        },
+        purpose: {
+            label: "From-scratch Build Plan draft",
+            taskHint: "Replace this neutral scaffold with the Build Plan stages, outputs, and proof rules this agent work requires.",
+        },
+        inputs: [
+            {
+                id: "source",
+                label: "Source",
+                description: "Source references assigned to each stage by Interf runtime.",
+                required: true,
+            },
+        ],
+        label: options.label,
+        hint: options.hint,
+        recommended: false,
+        scope: "local",
+        contextInterface: {
+            kind: "build-plan-schema",
+            version: 1,
+            target_type: "verifiable-context",
+            label: `${options.label} Build Plan schema`,
+            artifacts: [
+                {
+                    id: "draft-context",
+                    description: "Temporary placeholder Artifact for the neutral authoring scaffold. Replace it with task-specific Artifacts.",
+                    shape: { kind: "path", path: "draft", artifact_kind: "directory" },
+                    checks: [
+                        { id: "exists", kind: "min_file_count", required: true, params: { min: 1 } },
+                    ],
+                    built_by_stages: ["prepare"],
+                },
+            ],
+        },
+        stages: [
+            {
+                id: "prepare",
+                label: "Prepare",
+                description: "Neutral placeholder stage for Build Plan authoring. Replace this stage with the topology this agent work needs.",
+                contractType: "build-plan-draft-stage",
+                skillDir: "prepare",
+                role: "general",
+                reads: [],
+                writes: ["draft-context"],
+            },
+        ],
+        stagePolicyNotes: {
+            prepare: [
+                "This is a neutral authoring scaffold, not a recommended Build Plan topology.",
+                "Replace this stage, Artifact, and check when drafting the final Build Plan.",
+            ],
+        },
+        starterDocs: [
+            {
+                relativePath: "README.md",
+                content: renderScratchBuildPlanReadme({
+                    label: options.label,
+                    hint: options.hint,
+                }),
+            },
+        ],
+    };
+    writeBuildPlanPackageToDir(targetPath, buildPlan);
+    return targetPath;
+}

package/dist/packages/{methods → build-plans}/package/lib/package-root.js

@@ -2,5 +2,5 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-// Package root (dist/packages/methods/package/lib/ -> package root)
+// Package root (dist/packages/build-plans/package/lib/ -> package root)
 export const PACKAGE_ROOT = join(__dirname, "..", "..", "..", "..", "..");