@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/build-plans/package/context-interface.js

@@ -3,17 +3,17 @@ import { join } from "node:path";
 import { z } from "zod";
 import { warnInterf } from "../../contracts/utils/logger.js";
 import { readJsonFileUnchecked } from "../../contracts/utils/parse.js";
-import { BuildPlanContextSchemaSchema, BuildPlanArtifactIdSchema, } from "../../engine/build/lib/schema.js";
+import { BuildPlanContextSchemaSchema, BuildPlanArtifactIdSchema, } from "../../runtime/build/lib/schema.js";
 import { listBuiltinBuildPlanArtifactSpecs, requiredBuildPlanArtifactOwners, } from "./builtin-build-plan.js";
-// Build Plan packages define the context interface. The local engine persists the
+// Build Plan packages define the requested output contract. The local service persists the
 // same schema on disk, but higher layers should prefer this boundary when they
-// mean "the Build Plan-declared shape verifiable context must implement."
+// mean "the Build Plan-declared shape the Context Graph 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 build execution semantics; it describes what data a
-// Build Plan expects to organize before the local engine materializes the context
-// interface on disk.
+// Build Plan expects to organize before the local service materializes the context
+// requested output contract on disk.
 export const BuildPlanInputSpecSchema = z.object({
     id: BuildPlanArtifactIdSchema,
     label: z.string().min(1),
@@ -42,13 +42,6 @@ function artifactToBuildPlanArtifact(artifact) {
 export function listContextInterfaceArtifacts(contextInterface) {
     return contextInterface.artifacts.map(artifactToBuildPlanArtifact);
 }
-function titleCaseArtifactId(artifactId) {
-    return artifactId
-        .split("-")
-        .filter(Boolean)
-        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-        .join(" ");
-}
 export function contextInterfaceFilePath(rootPath) {
     return join(rootPath, CONTEXT_INTERFACE_FILE);
 }
@@ -59,8 +52,8 @@ export function resolveContextInterfacePath(rootPath) {
 export function contextInterfaceExists(rootPath) {
     return existsSync(contextInterfaceFilePath(rootPath));
 }
-export function contextInterfaceArtifactAbsolutePath(verifiableContextPath, artifact) {
-    return join(verifiableContextPath, artifact.path);
+export function contextInterfaceArtifactAbsolutePath(contextGraphPath, artifact) {
+    return join(contextGraphPath, artifact.path);
 }
 export function contextInterfaceArtifactPath(artifact) {
     if (artifact.kind === "file")
@@ -70,29 +63,17 @@ export function contextInterfaceArtifactPath(artifact) {
 export function summarizeContextInterface(contextInterface) {
     const artifacts = listContextInterfaceArtifacts(contextInterface);
     return {
-        inputArtifacts: artifacts.filter((artifact) => artifact.role === "input"),
-        workingArtifacts: artifacts.filter((artifact) => artifact.role === "working"),
-        outputArtifacts: artifacts.filter((artifact) => artifact.role === "output"),
-        runtimeArtifacts: artifacts.filter((artifact) => artifact.role === "runtime"),
+        outputArtifacts: artifacts,
     };
 }
-export function deriveBuildPlanInputsFromContextInterface(contextInterface) {
-    if (!contextInterface)
-        return [];
-    return listContextInterfaceArtifacts(contextInterface)
-        .filter((artifact) => artifact.role === "input")
-        .map((artifact) => ({
-        id: artifact.id,
-        label: titleCaseArtifactId(artifact.id),
-        description: artifact.description,
-        required: artifact.required,
-    }));
+export function deriveBuildPlanInputsFromContextInterface(_contextInterface) {
+    return [];
 }
-export function buildContextInterface(stages, label = "Build Plan context interface") {
+export function buildContextInterface(stages, label = "Build Plan requested output contract") {
     return {
         kind: "build-plan-schema",
         version: 1,
-        target_type: "verifiable-context",
+        target_type: "context-graph",
         label,
         artifacts: listBuiltinBuildPlanArtifactSpecs().map((artifact) => ({
             id: artifact.id,
@@ -121,12 +102,12 @@ export function readContextInterface(rootPath) {
     const path = contextInterfaceFilePath(rootPath);
     if (!existsSync(path))
         return null;
-    const raw = readJsonFileUnchecked(path, "Build Plan context interface");
+    const raw = readJsonFileUnchecked(path, "Build Plan requested output contract");
     if (raw === null)
         return null;
     const parsed = ContextInterfaceSchema.safeParse(raw);
     if (!parsed.success) {
-        warnInterf(`Warning: failed to validate Build Plan context interface at ${path}: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`);
+        warnInterf(`Warning: failed to validate Build Plan requested output contract 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

@@ -1,30 +1,19 @@
 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;
+export declare function writeBuildPlanPackageForContextGraph(contextGraphPath: string, buildPlan: BuildPlanDefinition<string>): void;
+export declare function seedContextGraphBuildPlanPackage(options: {
+    contextGraphPath: string;
+    projectDataDir: 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;
+    projectDataDir: string;
     baseBuildPlanId: string;
     buildPlanId: string;
     label: string;
     hint: string;
 }): string;
 export declare function createScratchLocalBuildPlanPackage(options: {
-    prepDataDir: string;
+    projectDataDir: string;
     buildPlanId: string;
     label: string;
     hint: string;

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

@@ -1,10 +1,10 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { renderVerifiableContextQuerySkill } from "../../engine/agents/lib/shells.js";
+import { renderContextGraphQuerySkill } from "../../runtime/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";
+import { buildPlanPackagePathForContextGraph } from "../../runtime/build/context-graph-paths.js";
 function writeBuildPlanStarterDocs(dirPath, docs, options) {
     for (const doc of docs ?? []) {
         const targetPath = join(dirPath, doc.relativePath);
@@ -20,11 +20,11 @@ function writeBuildPlanPackageJson(rootPath, buildPlan, options) {
         return;
     const inputs = buildPlan.inputs?.length
         ? buildPlan.inputs
-        : deriveBuildPlanInputsFromContextInterface(buildPlan.contextInterface ?? buildPlan.schema);
+        : deriveBuildPlanInputsFromContextInterface(buildPlan.contextInterface);
     writeFileSync(targetPath, `${JSON.stringify({
         id: buildPlan.id,
         type: "build-plan",
-        engine_api: buildPlan.engineApi ?? {
+        runtime_api: buildPlan.runtimeApi ?? {
             kind: "build",
             version: 1,
         },
@@ -36,6 +36,7 @@ function writeBuildPlanPackageJson(rootPath, buildPlan, options) {
                 },
             }
             : {}),
+        ...(buildPlan.brief ? { brief: buildPlan.brief } : {}),
         ...(inputs.length > 0 ? { inputs } : {}),
         label: buildPlan.label,
         hint: buildPlan.hint,
@@ -52,7 +53,7 @@ function writeBuildPlanPackageJson(rootPath, buildPlan, options) {
     }, null, 2)}\n`);
 }
 function renderBuildPlanReadme(buildPlan) {
-    const contextInterface = buildPlan.contextInterface ?? buildPlan.schema ?? null;
+    const contextInterface = buildPlan.contextInterface ?? null;
     const stageLines = buildPlan.stages
         .map((stage) => `- \`${stage.id}\` — ${stage.description} (${stage.contractType}; reads: ${stage.reads.join(", ")}; writes: ${stage.writes.join(", ")})`)
         .join("\n");
@@ -64,7 +65,7 @@ function renderBuildPlanReadme(buildPlan) {
         : [];
     const contextInterfaceLines = contextInterfaceArtifacts.length > 0
         ? contextInterfaceArtifacts
-            .map((artifact) => `- \`${artifact.id}\` — ${artifact.role} ${artifact.kind} Artifact at \`${artifact.path}\`: ${artifact.description}`)
+            .map((artifact) => `- \`${artifact.id}\` — ${artifact.kind} requested output at \`${artifact.path}\`: ${artifact.description}`)
             .join("\n")
         : null;
     const inputs = buildPlan.inputs?.length
@@ -77,10 +78,7 @@ function renderBuildPlanReadme(buildPlan) {
         : 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"}`,
+            `- Requested outputs: ${interfaceSummary.outputArtifacts.length > 0 ? interfaceSummary.outputArtifacts.map((artifact) => `\`${artifact.id}\``).join(", ") : "none"}`,
         ].join("\n")
         : null;
     return [
@@ -107,7 +105,7 @@ function renderBuildPlanReadme(buildPlan) {
         ...(contextInterfaceLines
             ? [
                 "",
-                "## Context Interface",
+                "## Requested Output Contract",
                 "",
                 ...(contextInterfaceSummaryLines
                     ? [
@@ -115,7 +113,7 @@ function renderBuildPlanReadme(buildPlan) {
                         "",
                     ]
                     : []),
-                "Artifact map:",
+                "Requested output map:",
                 "",
                 contextInterfaceLines,
             ]
@@ -123,8 +121,8 @@ function renderBuildPlanReadme(buildPlan) {
         "",
         "## 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",
+        "- `build-plan.json` = Build Plan stage flow, local-engine API target, and build contract mapping",
+        "- `build-plan.schema.json` = deterministic requested output contract 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",
@@ -133,7 +131,7 @@ function renderBuildPlanReadme(buildPlan) {
         "",
         stageLines,
         "",
-        "Interf runs the local copy of this Build Plan directly from `.interf/build-plan/` inside each verifiable-context output.",
+        "Interf builds the local copy of this Build Plan directly from `.interf/build-plan/` inside each Context Graph output.",
         "",
     ].join("\n");
 }
@@ -143,10 +141,10 @@ function renderDerivedBuildPlanReadme(options) {
         "",
         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.",
+        `This Build Plan package was forked from \`${options.baseBuildPlanId}\` and materialized as a standalone package for this kind of agent task.`,
+        "It starts with that Build Plan topology; edit the package when the agent task needs different stages, requested outputs, entrypoints, or diagnostics.",
         "",
-        "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.",
+        "Interf runs the local copy of this package directly. Keep purpose, inputs, requested output contract, and stage docs self-contained in this folder instead of relying on runtime inheritance.",
         "",
         "## Emphasis",
         "",
@@ -163,9 +161,9 @@ function renderSeedBuildPlanReadme(options) {
         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.",
+        "It starts with that Build Plan topology; edit the package when the agent task needs different stages, requested outputs, entrypoints, or diagnostics.",
         "",
-        "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.",
+        "Interf runs the local copy of this package directly. Refine purpose, inputs, requested output contract, and stage instructions in this folder instead of relying on inheritance.",
         "",
     ].join("\n");
 }
@@ -178,7 +176,7 @@ function renderScratchBuildPlanReadme(options) {
         "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.",
+        "Replace purpose, inputs, requested output contract, stages, stage docs, coverage rules, and query guidance with the Build Plan this source data and task actually need.",
         "",
     ].join("\n");
 }
@@ -193,15 +191,15 @@ function renderImproveSkill(buildPlan) {
         "",
         "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.",
+        "2. Review preserved stage shells, runtime logs, and saved benchmark runs from failed attempts.",
+        "3. Edit only the local Build Plan package for this Context Graph to create a better Build Plan implementation for this kind of agent task.",
         `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 edit checks, benchmark 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",
+        "- keep the Build Plan stack coherent: purpose, inputs, requested output contract, and stages should describe the same agent task",
         "- prefer small, defensible Build Plan changes over random churn",
         "",
     ].join("\n");
@@ -224,16 +222,16 @@ function renderStageSkill(buildPlan, stage) {
         "## Stage Contract",
         "",
         `- Contract type: \`${stage.contractType}\``,
-        `- Reads Artifacts: ${stage.reads.map((artifactId) => `\`${artifactId}\``).join(", ")}`,
-        `- Writes Artifacts: ${stage.writes.map((artifactId) => `\`${artifactId}\``).join(", ")}`,
+        `- Reads requested outputs: ${stage.reads.map((artifactId) => `\`${artifactId}\``).join(", ")}`,
+        `- Writes requested outputs: ${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.",
+        "- Read only from the declared input outputs unless this package explicitly documents broader Build Plan behavior.",
+        "- Write only inside the declared requested outputs for this stage. Do not invent undeclared outputs.",
+        "- Keep stage instructions, output ownership, and Build Plan diagnostics aligned when you change this stage.",
+        "- Treat runtime files as evidence 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,
         "",
@@ -247,10 +245,10 @@ function renderStageSkill(buildPlan, stage) {
             : []),
     ].join("\n");
 }
-export function writeBuildPlanPackageForVerifiableContext(verifiableContextPath, buildPlan) {
-    writeBuildPlanPackageToDir(buildPlanPackagePathForVerifiableContext(verifiableContextPath), buildPlan);
+export function writeBuildPlanPackageForContextGraph(contextGraphPath, buildPlan) {
+    writeBuildPlanPackageToDir(buildPlanPackagePathForContextGraph(contextGraphPath), buildPlan);
 }
-export function writeBuildPlanPackageToDir(buildPlanDir, buildPlan, options = {}) {
+function writeBuildPlanPackageToDir(buildPlanDir, buildPlan, options = {}) {
     const overwrite = options.overwrite ?? true;
     mkdirSync(join(buildPlanDir, "improve"), { recursive: true });
     mkdirSync(join(buildPlanDir, "use", "query"), { recursive: true });
@@ -260,7 +258,7 @@ export function writeBuildPlanPackageToDir(buildPlanDir, buildPlan, options = {}
     }
     writeBuildPlanPackageJson(buildPlanDir, buildPlan, { overwrite });
     if (overwrite || !existsSync(join(buildPlanDir, CONTEXT_INTERFACE_FILE))) {
-        const contextInterface = buildPlan.contextInterface ?? buildPlan.schema;
+        const contextInterface = buildPlan.contextInterface;
         if (contextInterface) {
             writeContextInterface(buildPlanDir, {
                 ...contextInterface,
@@ -278,7 +276,7 @@ export function writeBuildPlanPackageToDir(buildPlanDir, buildPlan, options = {}
         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());
+        writeFileSync(join(buildPlanDir, "use", "query", "SKILL.md"), renderContextGraphQuerySkill());
     }
     for (const stage of buildPlan.stages) {
         const targetPath = join(buildPlanDir, "build", "stages", stage.skillDir, "SKILL.md");
@@ -288,42 +286,42 @@ export function writeBuildPlanPackageToDir(buildPlanDir, buildPlan, options = {}
     }
     writeBuildPlanStarterDocs(buildPlanDir, buildPlan.starterDocs, { overwrite });
 }
-export function seedVerifiableContextBuildPlanPackage(options) {
+export function seedContextGraphBuildPlanPackage(options) {
     const resolvedBuildPlan = getBuildPlan(options.buildPlanId, {
-        prepDataDir: options.prepDataDir,
+        projectDataDir: options.projectDataDir,
     });
-    const sourceBuildPlanPath = resolveBuildPlanPackageSourcePath(options.prepDataDir, resolvedBuildPlan.id);
+    const sourceBuildPlanPath = resolveBuildPlanPackageSourcePath(options.projectDataDir, 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), {
+        // Portable seed packages can be copied directly because the Build
+        // runs the local package folder without reading source-root Build Plan packages.
+        copyBuildPlanPackageDirectory(sourceBuildPlanPath, buildPlanPackagePathForContextGraph(options.contextGraphPath));
+        patchBuildPlanPackageMetadata(buildPlanPackagePathForContextGraph(options.contextGraphPath), {
             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));
+        // The Context Graph README is always derived from the resolved Build Plan;
+        // any hand-authored README belongs in the Project-local draft at
+        // <project-data>/build-plans/<id>/, not in the built copy.
+        writeFileSync(join(buildPlanPackagePathForContextGraph(options.contextGraphPath), "README.md"), renderBuildPlanReadme(resolvedBuildPlan));
         return;
     }
-    // Legacy or partially-defined seed packages are resolved once and
+    // Previous or partially-defined seed packages are resolved once and
     // materialized into a standalone local package.
-    writeBuildPlanPackageForVerifiableContext(options.verifiableContextPath, resolvedBuildPlan);
+    writeBuildPlanPackageForContextGraph(options.contextGraphPath, resolvedBuildPlan);
 }
-export function createLocalBuildPlanPackageFromTemplate(options) {
+function createLocalBuildPlanPackageFromTemplate(options) {
     const targetPath = seedLocalBuildPlanPackageFromBase({
-        prepDataDir: options.prepDataDir,
+        projectDataDir: options.projectDataDir,
         baseBuildPlanId: options.baseBuildPlanId,
         buildPlanId: options.buildPlanId,
         label: options.label,
         hint: options.hint,
     });
     const baseBuildPlan = getBuildPlan(options.baseBuildPlanId, {
-        prepDataDir: options.prepDataDir,
+        projectDataDir: options.projectDataDir,
     });
     const stagePolicyNotes = mergeStagePolicyNotesForStages(baseBuildPlan.stages, baseBuildPlan.stagePolicyNotes, options.stagePolicyNotes);
     patchBuildPlanPackageMetadata(targetPath, {
@@ -348,10 +346,10 @@ export function createLocalBuildPlanPackageFromTemplate(options) {
 }
 export function seedLocalBuildPlanPackageFromBase(options) {
     const baseBuildPlan = getBuildPlan(options.baseBuildPlanId, {
-        prepDataDir: options.prepDataDir,
+        projectDataDir: options.projectDataDir,
     });
-    const sourceBuildPlanPath = resolveBuildPlanPackageSourcePath(options.prepDataDir, options.baseBuildPlanId);
-    const targetPath = buildPlanDefinitionPath(options.prepDataDir, options.buildPlanId);
+    const sourceBuildPlanPath = resolveBuildPlanPackageSourcePath(options.projectDataDir, options.baseBuildPlanId);
+    const targetPath = buildPlanDefinitionPath(options.projectDataDir, options.buildPlanId);
     if (sourceBuildPlanPath && isPortableBuildPlanPackage(sourceBuildPlanPath)) {
         // Copy directly when the base package is already portable and standalone.
         copyBuildPlanPackageDirectory(sourceBuildPlanPath, targetPath);
@@ -393,16 +391,16 @@ export function seedLocalBuildPlanPackageFromBase(options) {
     return targetPath;
 }
 export function createScratchLocalBuildPlanPackage(options) {
-    const targetPath = buildPlanDefinitionPath(options.prepDataDir, options.buildPlanId);
+    const targetPath = buildPlanDefinitionPath(options.projectDataDir, options.buildPlanId);
     const buildPlan = {
         id: options.buildPlanId,
-        engineApi: {
+        runtimeApi: {
             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.",
+            taskHint: "Replace this neutral scaffold with the Build Plan stages, outputs, and evidence rules this agent task requires.",
         },
         inputs: [
             {
@@ -419,15 +417,21 @@ export function createScratchLocalBuildPlanPackage(options) {
         contextInterface: {
             kind: "build-plan-schema",
             version: 1,
-            target_type: "verifiable-context",
+            target_type: "context-graph",
             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.",
+                    description: "Temporary placeholder requested output for the neutral authoring scaffold. Replace it with task-specific outputs.",
                     shape: { kind: "path", path: "draft", artifact_kind: "directory" },
                     checks: [
-                        { id: "exists", kind: "min_file_count", required: true, params: { min: 1 } },
+                        {
+                            id: "exists",
+                            kind: "min_file_count",
+                            description: "The draft output exists and contains at least one file.",
+                            required: true,
+                            params: { min: 1 },
+                        },
                     ],
                     built_by_stages: ["prepare"],
                 },
@@ -436,8 +440,8 @@ export function createScratchLocalBuildPlanPackage(options) {
         stages: [
             {
                 id: "prepare",
-                label: "Prepare",
-                description: "Neutral placeholder stage for Build Plan authoring. Replace this stage with the topology this agent work needs.",
+                label: "Build",
+                description: "Neutral placeholder stage for Build Plan authoring. Replace this stage with the topology this agent task needs.",
                 contractType: "build-plan-draft-stage",
                 skillDir: "prepare",
                 role: "general",
@@ -448,7 +452,7 @@ export function createScratchLocalBuildPlanPackage(options) {
         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.",
+                "Replace this stage, requested output, and diagnostic when drafting the final Build Plan.",
             ],
         },
         starterDocs: [

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

@@ -1,12 +1,10 @@
 import { z } from "zod";
-import { BuildPlanEngineApiSchema, BuildPlanPurposeSchema, type BuildPlanStageArtifactReadAccess, type BuildPlanStageArtifactWriteAccess } from "../../engine/build/lib/schema.js";
+import { BuildPlanRuntimeApiSchema, BuildPlanPurposeSchema, type BuildPlanStageArtifactReadAccess, type BuildPlanStageArtifactWriteAccess } from "../../runtime/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 {
+import { type BuildPlanAuthoringBrief } from "../authoring/brief.js";
+import type { BuildPlanStarterDoc } from "./build-plan-definitions.js";
+interface LocalBuildPlanStageDefinition {
     id: string;
     label: string;
     contract_type: z.infer<typeof RuntimeContractTypeSchema>;
@@ -24,15 +22,16 @@ export interface LocalBuildPlanStageDefinition {
 export interface LocalBuildPlanDefinition {
     id: string;
     type: "build-plan";
-    engine_api?: z.infer<typeof BuildPlanEngineApiSchema>;
+    runtime_api?: z.infer<typeof BuildPlanRuntimeApiSchema>;
     purpose?: z.infer<typeof BuildPlanPurposeSchema>;
+    brief?: BuildPlanAuthoringBrief;
     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[];
+    starter_docs: BuildPlanStarterDoc[];
     directoryPath: string;
     buildPlanPath: string;
     buildPlanSchemaPath: string;
@@ -41,14 +40,13 @@ 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 buildPlanDefinitionPath(projectDataDir: 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 listLocalBuildPlanDefinitions(projectDataDir: string): LocalBuildPlanDefinition[];
+export declare function loadLocalBuildPlanDefinition(projectDataDir: string, id: string): LocalBuildPlanDefinition | null;
+export declare function resolveBuildPlanPackageSourcePath(projectDataDir: string, buildPlanId: string): string | null;
 export declare function seedLocalDefaultBuildPlan(options: {
-    prepDataDir: string;
+    projectDataDir: string;
 }): {
     buildPlanId: string;
     targetPath: string;
@@ -72,3 +70,12 @@ export interface BuildPlanValidationResult {
     counts: Record<string, number>;
 }
 export declare function validateBuildPlanPackage(dirPath: string): BuildPlanValidationResult;
+/**
+ * Explain WHY a `build-plan.schema.json` failed to read. Exported so the
+ * regression test can assert the corrected branch directly: a valid schema must
+ * return `[]` (no issues), an invalid one must return the concrete Zod issues.
+ * The previous inverted `if (parsed.success)` reported a VALID schema as
+ * "missing or invalid."
+ */
+export declare function describeContextInterfaceValidationIssues(dirPath: string): string[];
+export {};