@interf/compiler 0.21.0 → 0.22.2

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

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { BuildPlanEngineApiSchema, BuildPlanPurposeSchema, type BuildPlanStageArtifactReadAccess, type BuildPlanStageArtifactWriteAccess } from "../../engine/build/lib/schema.js";
+import { RuntimeContractTypeSchema } from "../../contracts/lib/schema.js";
+import { BuildPlanInputSpecSchema, type ContextInterface, type BuildPlanInputSpec } from "./context-interface.js";
+export interface LocalBuildPlanStarterDoc {
+    relativePath: string;
+    content: string;
+}
+export interface LocalBuildPlanStageDefinition {
+    id: string;
+    label: string;
+    contract_type: z.infer<typeof RuntimeContractTypeSchema>;
+    skill_dir?: string;
+    description?: string;
+    /**
+     * Optional role hint. Open-ended string; defaults to `general` at the
+     * runtime layer when missing. Maps to a connected agent via the user's
+     * role-map (`~/.interf/agents.json`).
+     */
+    role?: string;
+    reads: BuildPlanStageArtifactReadAccess;
+    writes: BuildPlanStageArtifactWriteAccess;
+}
+export interface LocalBuildPlanDefinition {
+    id: string;
+    type: "build-plan";
+    engine_api?: z.infer<typeof BuildPlanEngineApiSchema>;
+    purpose?: z.infer<typeof BuildPlanPurposeSchema>;
+    inputs?: Array<z.infer<typeof BuildPlanInputSpecSchema>>;
+    label: string;
+    hint: string;
+    stages?: LocalBuildPlanStageDefinition[];
+    stage_policy_notes?: Record<string, string[]>;
+    build_plan_schema: ContextInterface;
+    starter_docs: LocalBuildPlanStarterDoc[];
+    directoryPath: string;
+    buildPlanPath: string;
+    buildPlanSchemaPath: string;
+}
+export declare function mergeStagePolicyNotesForStages(stages: readonly {
+    id: string;
+}[], baseNotes: unknown, overrideNotes: Record<string, string[]> | undefined): Record<string, string[]> | undefined;
+export declare function builtinBuildPlanPackagePath(buildPlanId: string): string;
+export declare function buildPlanDefinitionPath(prepDataDir: string, id: string): string;
+export declare function loadBuildPlanDefinitionFromDir(dirPath: string): LocalBuildPlanDefinition | null;
+export declare function isNeutralScaffoldBuildPlanDefinition(definition: Pick<LocalBuildPlanDefinition, "purpose" | "stages" | "build_plan_schema">): boolean;
+export declare function listLocalBuildPlanDefinitions(prepDataDir: string): LocalBuildPlanDefinition[];
+export declare function loadLocalBuildPlanDefinition(prepDataDir: string, id: string): LocalBuildPlanDefinition | null;
+export declare function resolveBuildPlanPackageSourcePath(prepDataDir: string, buildPlanId: string): string | null;
+export declare function seedLocalDefaultBuildPlan(options: {
+    prepDataDir: string;
+}): {
+    buildPlanId: string;
+    targetPath: string;
+    alreadyExisted: boolean;
+};
+export declare function isBuildPlanId(value: string): boolean;
+export declare function patchBuildPlanPackageMetadata(dirPath: string, options: {
+    id?: string;
+    inputs?: BuildPlanInputSpec[];
+    label?: string;
+    hint?: string;
+    stagePolicyNotes?: Record<string, string[]>;
+}): void;
+export declare function describeBuildPlanPackagePortability(dirPath: string): string[];
+export declare function isPortableBuildPlanPackage(dirPath: string): boolean;
+export declare function copyBuildPlanPackageDirectory(sourceBuildPlanPath: string, targetBuildPlanPath: string): void;
+export interface BuildPlanValidationResult {
+    ok: boolean;
+    summary: string;
+    errors: string[];
+    counts: Record<string, number>;
+}
+export declare function validateBuildPlanPackage(dirPath: string): BuildPlanValidationResult;

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

@@ -5,30 +5,30 @@ import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
 import { warnInterf } from "../../contracts/utils/logger.js";
 import { readJsonFileUnchecked, readJsonFileWithSchema } from "../../contracts/utils/parse.js";
 import { isMarkdownFile } from "../../contracts/utils/file-types.js";
-import { MethodCompilerApiSchema, MethodPurposeSchema, MethodStageArtifactReadAccessSchema, MethodStageArtifactWriteAccessSchema, } from "../../engine/compile/lib/schema.js";
+import { BuildPlanEngineApiSchema, BuildPlanPurposeSchema, BuildPlanStageArtifactReadAccessSchema, BuildPlanStageArtifactWriteAccessSchema, } from "../../engine/build/lib/schema.js";
 import { RuntimeContractTypeSchema, InterfIdPattern, } from "../../contracts/lib/schema.js";
-import { asPreparationDataDir, preparationMethodsRoot, } from "../../contracts/lib/preparation-paths.js";
-import { CONTEXT_INTERFACE_FILE, ContextInterfaceSchema, contextInterfaceExists, contextInterfaceFilePath, listContextInterfaceArtifacts, readContextInterface, MethodInputSpecSchema, writeContextInterface, } from "./context-interface.js";
+import { asPreparationDataDir, preparationBuildPlansRoot, } from "../../contracts/lib/preparation-paths.js";
+import { CONTEXT_INTERFACE_FILE, ContextInterfaceSchema, contextInterfaceExists, contextInterfaceFilePath, listContextInterfaceArtifacts, readContextInterface, BuildPlanInputSpecSchema, writeContextInterface, } from "./context-interface.js";
 import { PACKAGE_ROOT } from "./lib/package-root.js";
-const LocalMethodStageDefinitionSchema = z.object({
+const LocalBuildPlanStageDefinitionSchema = z.object({
     id: z.string().regex(InterfIdPattern),
     label: z.string().min(1),
     contract_type: RuntimeContractTypeSchema,
     skill_dir: z.string().regex(InterfIdPattern).optional(),
     description: z.string().min(1).optional(),
     role: z.string().min(1).optional(),
-    reads: MethodStageArtifactReadAccessSchema,
-    writes: MethodStageArtifactWriteAccessSchema,
+    reads: BuildPlanStageArtifactReadAccessSchema,
+    writes: BuildPlanStageArtifactWriteAccessSchema,
 });
-const LocalMethodDefinitionSchema = z.object({
+const LocalBuildPlanDefinitionSchema = z.object({
     id: z.string().regex(InterfIdPattern),
-    type: z.literal("compiled"),
-    compiler_api: MethodCompilerApiSchema.optional(),
-    purpose: MethodPurposeSchema.optional(),
-    inputs: z.array(MethodInputSpecSchema).min(1).optional(),
+    type: z.literal("build-plan"),
+    engine_api: BuildPlanEngineApiSchema.optional(),
+    purpose: BuildPlanPurposeSchema.optional(),
+    inputs: z.array(BuildPlanInputSpecSchema).min(1).optional(),
     label: z.string().min(1),
     hint: z.string().min(1),
-    stages: z.array(LocalMethodStageDefinitionSchema).min(1).optional(),
+    stages: z.array(LocalBuildPlanStageDefinitionSchema).min(1).optional(),
     stage_policy_notes: z.record(z.string(), z.array(z.string())).optional(),
 });
 function normalizeStagePolicyNotes(value) {
@@ -62,39 +62,39 @@ export function mergeStagePolicyNotesForStages(stages, baseNotes, overrideNotes)
     }
     return Object.keys(merged).length > 0 ? merged : undefined;
 }
-function methodRootPath(prepDataDir) {
-    return preparationMethodsRoot(asPreparationDataDir(prepDataDir));
+function buildPlanRootPath(prepDataDir) {
+    return preparationBuildPlansRoot(asPreparationDataDir(prepDataDir));
 }
-export function builtinMethodPackagePath(methodId) {
-    return join(PACKAGE_ROOT, "public-repo", "methods", methodId);
+export function builtinBuildPlanPackagePath(buildPlanId) {
+    return join(PACKAGE_ROOT, "public-repo", "build-plans", buildPlanId);
 }
-export function methodDefinitionPath(prepDataDir, id) {
-    return join(methodRootPath(prepDataDir), id);
+export function buildPlanDefinitionPath(prepDataDir, id) {
+    return join(buildPlanRootPath(prepDataDir), id);
 }
-function isSupportedMethodStarterDocPath(relativePath) {
+function isSupportedBuildPlanStarterDocPath(relativePath) {
     if (relativePath === "README.md")
         return true;
     if (relativePath.startsWith("improve/"))
         return true;
     if (relativePath.startsWith("use/query/"))
         return true;
-    if (relativePath.startsWith("compile/stages/"))
+    if (relativePath.startsWith("build/stages/"))
         return true;
     return false;
 }
 function collectStarterDocs(dirPath) {
     return listFilesRecursive(dirPath, isMarkdownFile)
         .map((filePath) => relative(dirPath, filePath).replaceAll("\\", "/"))
-        .filter((relativePath) => isSupportedMethodStarterDocPath(relativePath))
+        .filter((relativePath) => isSupportedBuildPlanStarterDocPath(relativePath))
         .map((relativePath) => ({
         relativePath,
         content: readFileSync(join(dirPath, relativePath), "utf8"),
     }))
         .sort((a, b) => a.relativePath.localeCompare(b.relativePath));
 }
-function methodPackageCopyPaths(dirPath) {
+function buildPlanPackageCopyPaths(dirPath) {
     return [
-        "method.json",
+        "build-plan.json",
         CONTEXT_INTERFACE_FILE,
         ...collectStarterDocs(dirPath).map((doc) => doc.relativePath),
     ];
@@ -107,51 +107,51 @@ function copyRelativeFile(sourceRoot, targetRoot, relativePath) {
     mkdirSync(dirname(targetPath), { recursive: true });
     cpSync(sourcePath, targetPath, { force: true });
 }
-function copyMethodPackageFiles(sourceMethodPath, targetMethodPath) {
-    rmSync(targetMethodPath, { recursive: true, force: true });
-    mkdirSync(targetMethodPath, { recursive: true });
-    for (const relativePath of methodPackageCopyPaths(sourceMethodPath)) {
-        copyRelativeFile(sourceMethodPath, targetMethodPath, relativePath);
+function copyBuildPlanPackageFiles(sourceBuildPlanPath, targetBuildPlanPath) {
+    rmSync(targetBuildPlanPath, { recursive: true, force: true });
+    mkdirSync(targetBuildPlanPath, { recursive: true });
+    for (const relativePath of buildPlanPackageCopyPaths(sourceBuildPlanPath)) {
+        copyRelativeFile(sourceBuildPlanPath, targetBuildPlanPath, relativePath);
     }
 }
-export function loadMethodDefinitionFromDir(dirPath) {
-    const methodPath = existsSync(join(dirPath, "method.json"))
-        ? join(dirPath, "method.json")
+export function loadBuildPlanDefinitionFromDir(dirPath) {
+    const buildPlanPath = existsSync(join(dirPath, "build-plan.json"))
+        ? join(dirPath, "build-plan.json")
         : null;
-    if (!methodPath)
+    if (!buildPlanPath)
         return null;
-    const definition = readJsonFileWithSchema(methodPath, "local Method definition", LocalMethodDefinitionSchema);
+    const definition = readJsonFileWithSchema(buildPlanPath, "local Build Plan definition", LocalBuildPlanDefinitionSchema);
     if (!definition)
         return null;
-    const methodSchema = readContextInterface(dirPath);
-    if (!methodSchema)
+    const buildPlanSchema = readContextInterface(dirPath);
+    if (!buildPlanSchema)
         return null;
-    if (definition.type !== "compiled") {
-        warnInterf(`Warning: local Method definition at ${methodPath} has unexpected type "${definition.type}".`);
+    if (definition.type !== "build-plan") {
+        warnInterf(`Warning: local Build Plan definition at ${buildPlanPath} has unexpected type "${definition.type}".`);
         return null;
     }
     return {
         ...definition,
-        method_schema: methodSchema,
+        build_plan_schema: buildPlanSchema,
         starter_docs: collectStarterDocs(dirPath),
         directoryPath: dirPath,
-        methodPath,
-        methodSchemaPath: contextInterfaceFilePath(dirPath),
+        buildPlanPath,
+        buildPlanSchemaPath: contextInterfaceFilePath(dirPath),
     };
 }
-export function isNeutralScaffoldMethodDefinition(definition) {
-    const hasScaffoldPurpose = definition.purpose?.label === "From-scratch Method draft" ||
+export function isNeutralScaffoldBuildPlanDefinition(definition) {
+    const hasScaffoldPurpose = definition.purpose?.label === "From-scratch Build Plan draft" ||
         Boolean(definition.purpose?.task_hint?.includes("Replace this neutral scaffold"));
     const hasScaffoldStage = Boolean(definition.stages?.some((stage) => stage.id === "prepare" &&
-        stage.contract_type === "method-draft-stage" &&
+        stage.contract_type === "build-plan-draft-stage" &&
         stage.writes.includes("draft-context")));
-    const hasScaffoldArtifact = listContextInterfaceArtifacts(definition.method_schema).some((artifact) => artifact.id === "draft-context" &&
+    const hasScaffoldArtifact = listContextInterfaceArtifacts(definition.build_plan_schema).some((artifact) => artifact.id === "draft-context" &&
         artifact.description.includes("neutral authoring scaffold"));
     return hasScaffoldPurpose || hasScaffoldStage || hasScaffoldArtifact;
 }
-export function listLocalMethodDefinitions(prepDataDir) {
+export function listLocalBuildPlanDefinitions(prepDataDir) {
     const definitions = new Map();
-    const root = methodRootPath(prepDataDir);
+    const root = buildPlanRootPath(prepDataDir);
     if (existsSync(root)) {
         for (const entryPath of readdirSync(root).map((entry) => join(root, entry))) {
             try {
@@ -161,73 +161,73 @@ export function listLocalMethodDefinitions(prepDataDir) {
             catch {
                 continue;
             }
-            const definition = loadMethodDefinitionFromDir(entryPath);
-            if (definition && !isNeutralScaffoldMethodDefinition(definition)) {
+            const definition = loadBuildPlanDefinitionFromDir(entryPath);
+            if (definition && !isNeutralScaffoldBuildPlanDefinition(definition)) {
                 definitions.set(definition.id, definition);
             }
         }
     }
     return [...definitions.values()].sort((a, b) => a.label.localeCompare(b.label));
 }
-export function loadLocalMethodDefinition(prepDataDir, id) {
-    const definition = loadMethodDefinitionFromDir(methodDefinitionPath(prepDataDir, id));
-    if (!definition || isNeutralScaffoldMethodDefinition(definition))
+export function loadLocalBuildPlanDefinition(prepDataDir, id) {
+    const definition = loadBuildPlanDefinitionFromDir(buildPlanDefinitionPath(prepDataDir, id));
+    if (!definition || isNeutralScaffoldBuildPlanDefinition(definition))
         return null;
     return definition;
 }
-export function resolveMethodPackageSourcePath(prepDataDir, methodId) {
-    const localPath = methodDefinitionPath(prepDataDir, methodId);
-    const local = loadMethodDefinitionFromDir(localPath);
-    if (local && !isNeutralScaffoldMethodDefinition(local))
+export function resolveBuildPlanPackageSourcePath(prepDataDir, buildPlanId) {
+    const localPath = buildPlanDefinitionPath(prepDataDir, buildPlanId);
+    const local = loadBuildPlanDefinitionFromDir(localPath);
+    if (local && !isNeutralScaffoldBuildPlanDefinition(local))
         return localPath;
-    const builtinPath = builtinMethodPackagePath(methodId);
-    if (loadMethodDefinitionFromDir(builtinPath))
+    const builtinPath = builtinBuildPlanPackagePath(buildPlanId);
+    if (loadBuildPlanDefinitionFromDir(builtinPath))
         return builtinPath;
     return null;
 }
-export function seedLocalDefaultMethod(options) {
-    const methodId = "interf-default";
-    const targetPath = methodDefinitionPath(options.prepDataDir, methodId);
-    if (existsSync(join(targetPath, "method.json"))) {
-        return { methodId, targetPath, alreadyExisted: true };
+export function seedLocalDefaultBuildPlan(options) {
+    const buildPlanId = "interf-default";
+    const targetPath = buildPlanDefinitionPath(options.prepDataDir, buildPlanId);
+    if (existsSync(join(targetPath, "build-plan.json"))) {
+        return { buildPlanId, targetPath, alreadyExisted: true };
     }
-    const builtinInterfPath = builtinMethodPackagePath(methodId);
-    if (!existsSync(join(builtinInterfPath, "method.json"))) {
-        throw new Error(`Built-in "${methodId}" Method package not found at ${builtinInterfPath}.`);
+    const builtinInterfPath = builtinBuildPlanPackagePath(buildPlanId);
+    if (!existsSync(join(builtinInterfPath, "build-plan.json"))) {
+        throw new Error(`Built-in "${buildPlanId}" Build Plan package not found at ${builtinInterfPath}.`);
     }
-    copyMethodPackageDirectory(builtinInterfPath, targetPath);
-    patchMethodPackageMetadata(targetPath, {
-        id: methodId,
-        label: "Built-in Interf Method",
-        hint: "Built-in file-processing Method: summarize source-grounded evidence, structure cross-file connections, and shape portable context around the saved readiness checks.",
+    copyBuildPlanPackageDirectory(builtinInterfPath, targetPath);
+    patchBuildPlanPackageMetadata(targetPath, {
+        id: buildPlanId,
+        label: "Built-in Interf Build Plan",
+        hint: "Built-in file-processing Build Plan: summarize source-grounded evidence, structure cross-file connections, and shape verifiable context around the saved readiness checks.",
     });
-    return { methodId, targetPath, alreadyExisted: false };
+    return { buildPlanId, targetPath, alreadyExisted: false };
 }
-export function isMethodId(value) {
+export function isBuildPlanId(value) {
     return InterfIdPattern.test(value);
 }
-function readMethodJsonObject(dirPath) {
-    const methodPath = join(dirPath, "method.json");
-    const raw = readJsonFileUnchecked(methodPath, "Method package");
+function readBuildPlanJsonObject(dirPath) {
+    const buildPlanPath = join(dirPath, "build-plan.json");
+    const raw = readJsonFileUnchecked(buildPlanPath, "Build Plan package");
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-        throw new Error(`Method package at ${dirPath} is missing a valid method.json.`);
+        throw new Error(`Build Plan package at ${dirPath} is missing a valid build-plan.json.`);
     }
     return { ...raw };
 }
-export function patchMethodPackageMetadata(dirPath, options) {
-    const methodPath = join(dirPath, "method.json");
-    const methodJson = readMethodJsonObject(dirPath);
-    const normalizedStages = Array.isArray(methodJson.stages) && methodJson.stages.length > 0
-        ? methodJson.stages
+export function patchBuildPlanPackageMetadata(dirPath, options) {
+    const buildPlanPath = join(dirPath, "build-plan.json");
+    const buildPlanJson = readBuildPlanJsonObject(dirPath);
+    const normalizedStages = Array.isArray(buildPlanJson.stages) && buildPlanJson.stages.length > 0
+        ? buildPlanJson.stages
         : null;
     if (!normalizedStages) {
-        throw new Error(`Cannot patch Method package at ${dirPath}: method.json must declare explicit stages before it can be copied or rewritten.`);
+        throw new Error(`Cannot patch Build Plan package at ${dirPath}: build-plan.json must declare explicit stages before it can be copied or rewritten.`);
     }
-    const nextMethodJson = {
-        ...methodJson,
-        type: "compiled",
-        compiler_api: methodJson.compiler_api ?? {
-            kind: "compiled",
+    const nextBuildPlanJson = {
+        ...buildPlanJson,
+        type: "build-plan",
+        engine_api: buildPlanJson.engine_api ?? {
+            kind: "build",
             version: 1,
         },
         stages: normalizedStages,
@@ -236,18 +236,18 @@ export function patchMethodPackageMetadata(dirPath, options) {
         ...(options.label ? { label: options.label } : {}),
         ...(options.hint ? { hint: options.hint } : {}),
     };
-    const mergedStagePolicyNotes = mergeStagePolicyNotesForStages(normalizedStages, methodJson.stage_policy_notes, options.stagePolicyNotes);
+    const mergedStagePolicyNotes = mergeStagePolicyNotesForStages(normalizedStages, buildPlanJson.stage_policy_notes, options.stagePolicyNotes);
     if (mergedStagePolicyNotes) {
-        nextMethodJson.stage_policy_notes = mergedStagePolicyNotes;
+        nextBuildPlanJson.stage_policy_notes = mergedStagePolicyNotes;
     }
     else {
-        delete nextMethodJson.stage_policy_notes;
+        delete nextBuildPlanJson.stage_policy_notes;
     }
-    writeFileSync(methodPath, JSON.stringify(nextMethodJson, null, 2) + "\n");
-    const schemaLabel = `${String(nextMethodJson.label ?? methodJson.label ?? options.id ?? "Method")} Method schema`;
+    writeFileSync(buildPlanPath, JSON.stringify(nextBuildPlanJson, null, 2) + "\n");
+    const schemaLabel = `${String(nextBuildPlanJson.label ?? buildPlanJson.label ?? options.id ?? "Build Plan")} Build Plan schema`;
     const existingSchema = readContextInterface(dirPath);
     if (!existingSchema) {
-        throw new Error(`Cannot patch Method package at ${dirPath}: missing ${CONTEXT_INTERFACE_FILE}. Restore or reseed the package instead of regenerating a schema from method.json.`);
+        throw new Error(`Cannot patch Build Plan package at ${dirPath}: missing ${CONTEXT_INTERFACE_FILE}. Restore or reseed the package instead of regenerating a schema from build-plan.json.`);
     }
     writeContextInterface(dirPath, {
         ...existingSchema,
@@ -259,13 +259,13 @@ function resolveStageSkillDir(stage) {
         ? stage.skill_dir
         : stage.id;
 }
-function collectMethodPackageStructureIssues(dirPath, stages) {
+function collectBuildPlanPackageStructureIssues(dirPath, stages) {
     const issues = [];
-    const methodPath = join(dirPath, "method.json");
-    if (!existsSync(methodPath))
-        issues.push("missing method.json");
+    const buildPlanPath = join(dirPath, "build-plan.json");
+    if (!existsSync(buildPlanPath))
+        issues.push("missing build-plan.json");
     if (!contextInterfaceExists(dirPath))
-        issues.push("missing method.schema.json");
+        issues.push("missing build-plan.schema.json");
     if (!existsSync(join(dirPath, "README.md")))
         issues.push("missing README.md");
     if (!existsSync(join(dirPath, "improve", "SKILL.md")))
@@ -276,77 +276,77 @@ function collectMethodPackageStructureIssues(dirPath, stages) {
         return issues;
     for (const stage of stages) {
         const skillDir = resolveStageSkillDir(stage);
-        if (!existsSync(join(dirPath, "compile", "stages", skillDir, "SKILL.md"))) {
-            issues.push(`missing compile/stages/${skillDir}/SKILL.md`);
+        if (!existsSync(join(dirPath, "build", "stages", skillDir, "SKILL.md"))) {
+            issues.push(`missing build/stages/${skillDir}/SKILL.md`);
         }
     }
     return issues;
 }
-export function describeMethodPackagePortability(dirPath) {
-    const issues = collectMethodPackageStructureIssues(dirPath, null);
+export function describeBuildPlanPackagePortability(dirPath) {
+    const issues = collectBuildPlanPackageStructureIssues(dirPath, null);
     if (issues.length > 0)
         return issues;
-    let methodJson;
+    let buildPlanJson;
     try {
-        methodJson = readMethodJsonObject(dirPath);
+        buildPlanJson = readBuildPlanJsonObject(dirPath);
     }
     catch (error) {
         issues.push(error instanceof Error ? error.message : String(error));
         return issues;
     }
-    const parsed = LocalMethodDefinitionSchema.safeParse(methodJson);
+    const parsed = LocalBuildPlanDefinitionSchema.safeParse(buildPlanJson);
     if (!parsed.success) {
         issues.push(...parsed.error.issues.map((issue) => issue.path.length > 0
-            ? `method.json ${issue.path.join(".")}: ${issue.message}`
-            : `method.json: ${issue.message}`));
+            ? `build-plan.json ${issue.path.join(".")}: ${issue.message}`
+            : `build-plan.json: ${issue.message}`));
         return issues;
     }
     if (!parsed.data.stages || parsed.data.stages.length === 0) {
-        issues.push("method.json must declare explicit stages for a portable Method package");
+        issues.push("build-plan.json must declare explicit stages for a portable Build Plan package");
         return issues;
     }
     // Structural issues already returned earlier; only stage-skill files can be missing now.
     return [
         ...issues,
-        ...collectMethodPackageStructureIssues(dirPath, parsed.data.stages ?? null),
+        ...collectBuildPlanPackageStructureIssues(dirPath, parsed.data.stages ?? null),
     ];
 }
-export function isPortableMethodPackage(dirPath) {
-    return describeMethodPackagePortability(dirPath).length === 0;
+export function isPortableBuildPlanPackage(dirPath) {
+    return describeBuildPlanPackagePortability(dirPath).length === 0;
 }
-export function copyMethodPackageDirectory(sourceMethodPath, targetMethodPath) {
-    const portabilityIssues = describeMethodPackagePortability(sourceMethodPath);
+export function copyBuildPlanPackageDirectory(sourceBuildPlanPath, targetBuildPlanPath) {
+    const portabilityIssues = describeBuildPlanPackagePortability(sourceBuildPlanPath);
     if (portabilityIssues.length > 0) {
-        throw new Error(`Method package at ${sourceMethodPath} is not directly copyable: ${portabilityIssues.join("; ")}.`);
+        throw new Error(`Build Plan package at ${sourceBuildPlanPath} is not directly copyable: ${portabilityIssues.join("; ")}.`);
     }
-    mkdirSync(dirname(targetMethodPath), { recursive: true });
-    copyMethodPackageFiles(sourceMethodPath, targetMethodPath);
+    mkdirSync(dirname(targetBuildPlanPath), { recursive: true });
+    copyBuildPlanPackageFiles(sourceBuildPlanPath, targetBuildPlanPath);
 }
-export function validateMethodPackage(dirPath) {
-    const methodPath = join(dirPath, "method.json");
-    if (!existsSync(methodPath)) {
+export function validateBuildPlanPackage(dirPath) {
+    const buildPlanPath = join(dirPath, "build-plan.json");
+    if (!existsSync(buildPlanPath)) {
         return {
             ok: false,
-            summary: `No method.json found at ${dirPath}`,
-            errors: ["Missing method.json"],
+            summary: `No build-plan.json found at ${dirPath}`,
+            errors: ["Missing build-plan.json"],
             counts: {},
         };
     }
-    const raw = readJsonFileUnchecked(methodPath, "Method package");
+    const raw = readJsonFileUnchecked(buildPlanPath, "Build Plan package");
     if (!raw) {
         return {
             ok: false,
-            summary: `Failed to parse method.json at ${methodPath}`,
-            errors: ["Invalid JSON in method.json"],
+            summary: `Failed to parse build-plan.json at ${buildPlanPath}`,
+            errors: ["Invalid JSON in build-plan.json"],
             counts: {},
         };
     }
-    const parsed = LocalMethodDefinitionSchema.safeParse(raw);
+    const parsed = LocalBuildPlanDefinitionSchema.safeParse(raw);
     if (!parsed.success) {
         const issues = parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`);
         return {
             ok: false,
-            summary: `method.json failed validation: ${issues.length} issue(s)`,
+            summary: `build-plan.json failed validation: ${issues.length} issue(s)`,
             errors: issues,
             counts: {},
         };
@@ -354,32 +354,32 @@ export function validateMethodPackage(dirPath) {
     const def = parsed.data;
     const errors = [];
     if (!def.stages || def.stages.length === 0) {
-        errors.push("method.json must declare explicit stages.");
+        errors.push("build-plan.json must declare explicit stages.");
     }
     if (def.stage_policy_notes && def.stages) {
         const stageIds = new Set(def.stages.map((stage) => stage.id));
         for (const stageId of Object.keys(def.stage_policy_notes)) {
             if (!stageIds.has(stageId)) {
-                errors.push(`method.json stage_policy_notes references unknown stage "${stageId}".`);
+                errors.push(`build-plan.json stage_policy_notes references unknown stage "${stageId}".`);
             }
         }
     }
-    for (const issue of collectMethodPackageStructureIssues(dirPath, def.stages ?? null)) {
+    for (const issue of collectBuildPlanPackageStructureIssues(dirPath, def.stages ?? null)) {
         const formatted = issue.startsWith("missing ")
             ? `Missing ${issue.slice("missing ".length)}.`
             : issue;
         errors.push(formatted);
     }
-    const methodSchema = readContextInterface(dirPath);
-    if (!methodSchema) {
+    const buildPlanSchema = readContextInterface(dirPath);
+    if (!buildPlanSchema) {
         errors.push(...describeContextInterfaceValidationIssues(dirPath));
     }
-    if (methodSchema) {
+    if (buildPlanSchema) {
         const stages = def.stages ?? [];
         const stageIds = new Set(stages.map((stage) => stage.id));
         const seenPaths = new Map();
         const seenArtifactIds = new Set();
-        const schemaArtifacts = listContextInterfaceArtifacts(methodSchema);
+        const schemaArtifacts = listContextInterfaceArtifacts(buildPlanSchema);
         const artifactById = new Map(schemaArtifacts.map((artifact) => [artifact.id, artifact]));
         const normalizedParts = (value) => value.replaceAll("\\", "/").split("/").filter(Boolean);
         const hasOverlappingPath = (value, other) => {
@@ -391,27 +391,27 @@ export function validateMethodPackage(dirPath) {
         };
         for (const artifact of schemaArtifacts) {
             if (seenArtifactIds.has(artifact.id)) {
-                errors.push(`method.schema.json repeats Artifact id "${artifact.id}".`);
+                errors.push(`build-plan.schema.json repeats Artifact id "${artifact.id}".`);
             }
             seenArtifactIds.add(artifact.id);
             const existingPathOwner = seenPaths.get(artifact.path);
             if (existingPathOwner) {
-                errors.push(`method.schema.json repeats Artifact path "${artifact.path}".`);
+                errors.push(`build-plan.schema.json repeats Artifact path "${artifact.path}".`);
             }
             for (const [existingPath, existingZoneId] of seenPaths.entries()) {
                 if (existingPath === artifact.path)
                     continue;
                 if (hasOverlappingPath(artifact.path, existingPath)) {
-                    errors.push(`method.schema.json Artifacts "${artifact.id}" and "${existingZoneId}" overlap on path "${artifact.path}" / "${existingPath}".`);
+                    errors.push(`build-plan.schema.json Artifacts "${artifact.id}" and "${existingZoneId}" overlap on path "${artifact.path}" / "${existingPath}".`);
                 }
             }
             seenPaths.set(artifact.path, artifact.id);
             if ((artifact.role === "input" || artifact.role === "runtime") && artifact.owned_by.length > 0) {
-                errors.push(`method.schema.json Artifact "${artifact.id}" cannot declare owners because its role is "${artifact.role}".`);
+                errors.push(`build-plan.schema.json Artifact "${artifact.id}" cannot declare owners because its role is "${artifact.role}".`);
             }
             for (const owner of artifact.owned_by) {
                 if (!stageIds.has(owner)) {
-                    errors.push(`method.schema.json references unknown stage "${owner}" for Artifact path "${artifact.path}".`);
+                    errors.push(`build-plan.schema.json references unknown stage "${owner}" for Artifact path "${artifact.path}".`);
                 }
             }
         }
@@ -431,42 +431,42 @@ export function validateMethodPackage(dirPath) {
                     errors.push(`Stage "${stage.id}" writes Artifact "${artifactId}" but Artifacts with role "${artifact.role}" are engine-owned inputs, not writable stage outputs.`);
                 }
                 if (!artifact.owned_by.includes(stage.id)) {
-                    errors.push(`Stage "${stage.id}" writes Artifact "${artifactId}" but that Artifact is not owned by the stage in method.schema.json.`);
+                    errors.push(`Stage "${stage.id}" writes Artifact "${artifactId}" but that Artifact is not owned by the stage in build-plan.schema.json.`);
                 }
             }
         }
     }
-    const stageDirs = existsSync(join(dirPath, "compile", "stages"))
-        ? listFilesRecursive(join(dirPath, "compile", "stages"), (filePath) => basename(filePath) === "SKILL.md")
+    const stageDirs = existsSync(join(dirPath, "build", "stages"))
+        ? listFilesRecursive(join(dirPath, "build", "stages"), (filePath) => basename(filePath) === "SKILL.md")
         : [];
     const counts = {
         starter_docs: collectStarterDocs(dirPath).length,
-        compile_stage_docs: stageDirs.length,
-        compiled_artifacts: methodSchema ? listContextInterfaceArtifacts(methodSchema).length : 0,
-        method_artifacts: methodSchema ? listContextInterfaceArtifacts(methodSchema).length : 0,
+        build_stage_docs: stageDirs.length,
+        build_artifacts: buildPlanSchema ? listContextInterfaceArtifacts(buildPlanSchema).length : 0,
+        build_plan_artifacts: buildPlanSchema ? listContextInterfaceArtifacts(buildPlanSchema).length : 0,
     };
     return {
         ok: errors.length === 0,
-        summary: errors.length === 0 ? "Method package is valid." : `Method package has ${errors.length} issue(s).`,
+        summary: errors.length === 0 ? "Build Plan package is valid." : `Build Plan package has ${errors.length} issue(s).`,
         errors,
         counts,
     };
 }
 function describeContextInterfaceValidationIssues(dirPath) {
-    const methodSchemaPath = contextInterfaceFilePath(dirPath);
-    if (!existsSync(methodSchemaPath)) {
-        return ["method.schema.json is missing."];
+    const buildPlanSchemaPath = contextInterfaceFilePath(dirPath);
+    if (!existsSync(buildPlanSchemaPath)) {
+        return ["build-plan.schema.json is missing."];
     }
-    const raw = readJsonFileUnchecked(methodSchemaPath, "Method context interface");
+    const raw = readJsonFileUnchecked(buildPlanSchemaPath, "Build Plan context interface");
     if (raw === null) {
-        return ["method.schema.json is invalid JSON."];
+        return ["build-plan.schema.json is invalid JSON."];
     }
     const parsed = ContextInterfaceSchema.safeParse(raw);
     if (parsed.success) {
-        return ["method.schema.json is missing or invalid."];
+        return ["build-plan.schema.json is missing or invalid."];
     }
     return parsed.error.issues.map((issue) => {
         const path = issue.path.length > 0 ? issue.path.join(".") : "<root>";
-        return `method.schema.json ${path}: ${issue.message}`;
+        return `build-plan.schema.json ${path}: ${issue.message}`;
     });
 }