@interf/compiler 0.33.0 → 0.50.0

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

@@ -7,6 +7,15 @@ export interface BuildPlanEditSessionResult {
     validation: BuildPlanValidationResult | null;
     summary: string;
 }
+/**
+ * Stable Build Plan editing rules shared verbatim by every prompt that edits a
+ * Build Plan package — the from-scratch authoring prompt
+ * (`build-plan-authoring.ts`) and the validation-repair prompt below. Defined
+ * once so the wording cannot drift between the two prompts. Each entry is the
+ * bare rule text; the repair prompt renders it as a `- ` bullet, the authoring
+ * prompt renders it as a plain line.
+ */
+export declare const SHARED_BUILD_PLAN_EDIT_RULES: readonly string[];
 export declare function runBuildPlanEditSession(options: {
     executor: AgentExecutor;
     buildPlanPath: string;

package/dist/packages/build-plans/authoring/build-plan-edit-session.js

@@ -1,6 +1,19 @@
 import { appendFileSync, existsSync, realpathSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { copyDirectory, directoriesMatch, } from "./lib/build-plan-edit-utils.js";
+/**
+ * Stable Build Plan editing rules shared verbatim by every prompt that edits a
+ * Build Plan package — the from-scratch authoring prompt
+ * (`build-plan-authoring.ts`) and the validation-repair prompt below. Defined
+ * once so the wording cannot drift between the two prompts. Each entry is the
+ * bare rule text; the repair prompt renders it as a `- ` bullet, the authoring
+ * prompt renders it as a plain line.
+ */
+export const SHARED_BUILD_PLAN_EDIT_RULES = [
+    "Use kebab-case ids everywhere: stage ids, skill_dir values, requested output ids, reads/writes values, and package ids. Never use underscores.",
+    "Use `runtime/authoring-context.json.check_param_contracts` as the exact parameter contract for each check kind.",
+    "Every deterministic diagnostic must include a human-readable `description` that names the user's assertion; keep `kind` and `params` as the machine evaluator and never as user copy.",
+];
 export async function runBuildPlanEditSession(options) {
     const editableBuildPlanPath = join(options.shell.rootPath, "build-plan");
     copyDirectory(options.buildPlanPath, options.shell.buildPlanBeforePath);
@@ -17,6 +30,7 @@ export async function runBuildPlanEditSession(options) {
             code = await options.executor.execute(options.shell.rootPath, prompt, {
                 eventLogPath: options.shell.eventLogPath,
                 statusLogPath: options.shell.statusLogPath,
+                reasoningLogPath: options.shell.reasoningLogPath,
                 completionCheck: () => {
                     try {
                         if (directoriesMatch(options.shell.buildPlanBeforePath, editableBuildPlanPath))
@@ -94,18 +108,21 @@ export async function runBuildPlanEditSession(options) {
             "",
             "Rules:",
             "- Edit only files under `build-plan/`.",
-            "- Use kebab-case ids everywhere: stage ids, skill_dir values, Artifact ids, reads/writes values, and package ids. Never use underscores.",
-            "- Stage `reads` may only contain Artifact ids declared in `build-plan.schema.json` and produced by an earlier stage. Source files are implicit input; never use `source` or source paths in `reads`.",
-            "- Keep user-facing Context Checks plain-English and preserve their `backed_by_artifact_ids` links to requested Artifact ids.",
-            "- If `runtime/authoring-context.json.artifact_requirements[]` is non-empty, copy every required Artifact `id`, `shape`, and `checks[]` exactly into `build-plan.schema.json`.",
-            "- Do not rename, move, merge, split, or reinterpret required Artifacts while repairing validation errors.",
+            // Stable kebab-case-id rule (shared with the authoring prompt).
+            `- ${SHARED_BUILD_PLAN_EDIT_RULES[0]}`,
+            "- Stage `reads` may only contain requested output ids declared in `build-plan.schema.json` and produced by an earlier stage. Source files are implicit input; never use `source` or source paths in `reads`.",
+            "- Keep coverage expectations, requested outputs, and backed output ids aligned with the Project intent.",
+            "- If `runtime/authoring-context.json.artifact_requirements[]` is non-empty, copy every required output `id`, `shape`, and `checks[]` exactly into `build-plan.schema.json`.",
+            "- Do not rename, move, merge, split, or reinterpret required outputs while repairing validation errors.",
             "- Keep every stage `skill_dir` matched by `build-plan/build/stages/<skill_dir>/SKILL.md`.",
-            "- Keep `build-plan.schema.json` Artifact paths unique. Child Artifacts may live under the required layer directories `summaries/`, `knowledge/`, and `artifacts/`; unrelated Artifact paths must not overlap.",
-            "- Put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks.",
+            "- Keep `build-plan.schema.json` requested output paths unique. Child outputs may live under the required layer directories `summaries/`, `knowledge/`, and `artifacts/`; unrelated output paths must not overlap.",
+            "- Keep deterministic validation on requested output `checks[]` minimal; do not add stage `acceptance` blocks.",
             "- Use only CheckKind values listed in `runtime/authoring-context.json`; replace invented aliases with valid kinds.",
-            "- Use `runtime/authoring-context.json.check_param_contracts` as the exact parameter contract for each check kind.",
-            "- Every Artifact diagnostic must include a human-readable `description` that names the user's assertion; keep `kind` and `params` as the machine evaluator and never as user copy.",
-            "- If the Build Plan writes a graph index, keep it declared as an Artifact owned by the producing stage.",
+            // Stable check-param-contract + diagnostic-description rules (shared with
+            // the authoring prompt).
+            `- ${SHARED_BUILD_PLAN_EDIT_RULES[1]}`,
+            `- ${SHARED_BUILD_PLAN_EDIT_RULES[2]}`,
+            "- If the Build Plan writes a graph index, keep it declared as a requested output owned by the producing stage.",
             "- Stop as soon as the package should validate.",
         ].join("\n");
         appendFileSync(options.shell.promptLogPath, `\n\n---\n\n${prompt}\n`);

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

@@ -1,16 +1,16 @@
 import { appendFileSync, existsSync, mkdirSync, writeFileSync, } from "node:fs";
 import { join, relative } from "node:path";
 import { createBuildPlanImprovementShell, freezeBuildPlanImprovementShell, } from "../../runtime/agents/lib/shells.js";
-import { validateBuildPlanPackage } from "../package/local-build-plans.js";
 import { CONTEXT_INTERFACE_FILE } from "../package/context-interface.js";
 import { readJsonFileWithSchema } from "../../contracts/utils/parse.js";
 import { resolveBuildPlanImprovementReviewPaths } from "../package/build-plan-review-paths.js";
 import { targetTestRunsRootForContextGraph, targetTestSandboxesRootForContextGraph, buildPlanImprovementRunRoot, buildPlanPackagePathForContextGraph, } from "../../runtime/build/context-graph-paths.js";
-import { readInterfConfig } from "../../projects/interf.js";
+import { readInterfConfig, resolveSourceFolderPath } from "../../projects/interf.js";
+import { scanSourceContext } from "../../runtime/agents/lib/source-context-scan.js";
 import { saveContextGraphInterfConfig } from "../../projects/source-config.js";
 import { BuildPlanImprovementRunLedgerSchema, } from "../../runtime/build/lib/schema.js";
 import { runBuildPlanEditSession } from "./build-plan-edit-session.js";
-import { ensureStageRoles } from "./build-plan-authoring.js";
+import { ensureStageRoles, validateImproveTailoringNonRegression, validateLifecycleBuildPlanPackage, } from "./build-plan-authoring.js";
 function toShellArtifactPath(absolutePath, sourceRoot, shellRoot) {
     if (!absolutePath)
         return null;
@@ -51,6 +51,31 @@ function buildLoopContext(options) {
         latest_failure: latestFailure,
     };
 }
+/**
+ * Resolve the SAME cheap, contents-free Source inventory the draft path scans,
+ * but from the Context Graph the improvement loop is editing. The Context
+ * Graph's `interf.json` carries the Project's Source binding, so the improve
+ * path CAN reach the Source (`resolveSourceFolderPath` → `scanSourceContext`)
+ * exactly like the draft path does — it is not blind to the Source.
+ *
+ * Returns null (and the tailoring non-regression guard becomes a no-op) only
+ * when there is genuinely nothing to scan: no Source binding in the config, or
+ * the Source has no readable files. A null here never fabricates an inventory.
+ */
+function resolveImproveSourceContext(contextGraphPath) {
+    const config = readInterfConfig(contextGraphPath);
+    let sourceFolderPath;
+    try {
+        sourceFolderPath = resolveSourceFolderPath(contextGraphPath, config);
+    }
+    catch {
+        // No Source binding in the Context Graph config — nothing to tailor
+        // against. The draft path always has a Source folder; the improve path may
+        // run against a Context Graph whose binding is missing, so degrade quietly.
+        return null;
+    }
+    return scanSourceContext(sourceFolderPath) ?? null;
+}
 function buildBuildPlanImprovementPrompt() {
     return [
         "This is an automated Interf Build Plan improvement run, not an open-ended chat session.",
@@ -59,12 +84,12 @@ function buildBuildPlanImprovementPrompt() {
         `Then read \`build-plan/README.md\`, \`build-plan/build-plan.json\`, \`build-plan/${CONTEXT_INTERFACE_FILE}\`, and \`build-plan/improve/SKILL.md\` if it exists.`,
         "Review preserved evidence from earlier failures under `artifacts/` before you edit the Build Plan.",
         "Treat `build-plan/improve/SKILL.md` as guidance for how to improve the Build Plan, not as the default file to edit.",
-        "Treat the Build Plan package as four aligned layers: purpose, inputs, requested Artifact contract, and stages.",
-        "Prefer editing the stage docs, Build Plan contract, input contract, or Artifact ownership that actually change requested Artifacts.",
+        "Treat the Build Plan package as four aligned layers: purpose, inputs, requested output contract, and stages.",
+        "Prefer editing the stage docs, Build Plan contract, input contract, or requested output ownership that actually change graph outputs.",
         "Edit only files under `build-plan/`.",
-        "Do not edit checks, benchmark specs, source files, or generated requested Artifacts.",
+        "Do not edit checks, benchmark specs, source files, or generated requested outputs.",
         "Keep the Build Plan package valid for the current build API and `build-plan.schema.json`.",
-        "Respect stage boundaries: a stage may only introduce links that resolve within that stage's declared writes or already-existing read Artifacts.",
+        "Respect stage boundaries: a stage may only introduce links that resolve within that stage's declared writes or already-existing read outputs.",
         "Do not make one stage point at files or notes that are only created later by another stage.",
         "Prefer small, defensible changes to Build Plan docs, stage docs, stage policies, or schema ownership over random churn.",
         "Do not narrate plans or ask follow-up questions.",
@@ -142,6 +167,9 @@ function buildBuildPlanImprovementLoopRecord(options) {
         prompt_log_path: options.promptLogPath,
         event_log_path: options.eventLogPath,
         status_log_path: options.statusLogPath,
+        // Same canonical location the shell teed reasoning to and the freeze
+        // preserved (derived from shell_path, like context_path above).
+        reasoning_path: join(options.shellPath, "runtime", "agent-reasoning.jsonl"),
         preserved_shell_manifest_path: options.preservedShellManifestPath,
         validation: options.validation,
     };
@@ -158,12 +186,38 @@ export async function runBuildPlanImprovementLoop(options) {
         context,
     });
     const buildPlanRoot = buildPlanPackagePathForContextGraph(options.contextGraphPath);
+    // Scan the Source ONCE (from the Context Graph's own binding) so the tailoring
+    // non-regression guard below compares before/after against one stable
+    // inventory. Null when there is no Source binding or no readable files, which
+    // makes that guard a no-op.
+    const improveSourceContext = resolveImproveSourceContext(options.contextGraphPath);
     const session = await runBuildPlanEditSession({
         executor: options.executor,
         buildPlanPath: buildPlanRoot,
         shell,
         prompt: buildBuildPlanImprovementPrompt(),
-        validate: validateBuildPlanPackage,
+        // Run the SHARED lifecycle validator (base + product-critical backlink and
+        // canonical-top-level-layer invariants), PLUS a tailoring non-regression
+        // delta. An improvement edit must not silently strip those invariants, and
+        // — closing the original C1 gap — it must not DE-TAILOR a plan that was
+        // tailored to the Source back to a generic skeleton. The scaffold-removal,
+        // artifact-requirement, and ABSOLUTE tailoring guards stay authoring-only
+        // (draft-time concerns); the improve path enforces the non-regression delta
+        // so it never false-rejects a faithful improvement to a generic-by-design
+        // plan such as `interf-default`.
+        validate: (afterBuildPlanPath) => {
+            const lifecycle = validateLifecycleBuildPlanPackage(afterBuildPlanPath);
+            const tailoringErrors = validateImproveTailoringNonRegression(shell.buildPlanBeforePath, afterBuildPlanPath, improveSourceContext);
+            if (tailoringErrors.length === 0)
+                return lifecycle;
+            const errors = [...lifecycle.errors, ...tailoringErrors];
+            return {
+                ok: false,
+                summary: `Build Plan package has ${errors.length} issue(s).`,
+                errors,
+                counts: lifecycle.counts,
+            };
+        },
         maxValidationRepairAttempts: 1,
     });
     if (session.status === "updated") {

package/dist/packages/build-plans/authoring/lib/build-plan-edit-utils.d.ts

@@ -7,4 +7,5 @@ export interface BuildPlanEditShellArtifacts {
     promptLogPath: string;
     eventLogPath: string;
     statusLogPath: string;
+    reasoningLogPath: string;
 }

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

@@ -35,7 +35,6 @@ export interface BuildPlanDefinition<TId extends string> {
     hint: string;
     recommended?: boolean;
     contextInterface?: ContextInterface;
-    schema?: ContextInterface;
     stages: BuildPlanStageDefinition[];
     stagePolicyNotes?: Record<string, string[]>;
     starterDocs?: BuildPlanStarterDoc[];

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

@@ -7,7 +7,7 @@ import { buildPlanPackagePathForContextGraph } from "../../runtime/build/context
 import { asProjectDataDir, projectBuildPlanPackagePath } from "../../contracts/lib/project-paths.js";
 import { resolveSourceControlPath } from "../../projects/interf.js";
 import { deriveBuildPlanInputsFromContextInterface, } from "./context-interface.js";
-const DEFAULT_BUILD_PLAN_ID = "interf-default";
+import { DEFAULT_BUILD_PLAN_ID } from "../build-plan-resolution.js";
 let builtinDefaultBuildPlanCache = null;
 function toBuildPlanStages(stages) {
     return stages.map((stage) => ({
@@ -16,7 +16,10 @@ function toBuildPlanStages(stages) {
         description: stage.description ?? stage.label,
         contractType: stage.contract_type,
         skillDir: stage.skill_dir ?? stage.id,
-        role: stage.role && stage.role.trim().length > 0 ? stage.role : "general",
+        // Store the TRIMMED role so a padded value like "  general  " maps to the
+        // same agent-role-map key the validity check (`.trim().length > 0`) tested,
+        // matching how `ensureStageRoles` (build-plan-authoring.ts) stores roles.
+        role: stage.role && stage.role.trim().length > 0 ? stage.role.trim() : "general",
         reads: [...stage.reads],
         writes: [...stage.writes],
     }));
@@ -50,7 +53,6 @@ export function standaloneBuildPlanDefinitionFromLocalPackage(local) {
         hint: local.hint,
         recommended: false,
         contextInterface,
-        ...(contextInterface ? { schema: contextInterface } : {}),
         stages,
         stagePolicyNotes: mergeStagePolicyNotesForStages(stages, undefined, local.stage_policy_notes),
         starterDocs: [...local.starter_docs],

package/dist/packages/build-plans/package/build-plan-stage-runner.d.ts

@@ -15,6 +15,7 @@ interface ExecuteValidatedStageOptions<TContractType extends RuntimeContractType
     targetName: string;
     buildPlan: string;
     buildPlanSourcePath?: string;
+    buildRunId?: string | null;
     stageDefinition: BuildPlanStageShape<TContractType>;
     instructions: RuntimeStageInstructions;
     summary: string;

package/dist/packages/build-plans/package/build-plan-stage-runner.js

@@ -23,6 +23,7 @@ export async function executeValidatedStage(options) {
         contextGraphName: options.targetName,
         buildPlan: options.buildPlan,
         buildPlanSourcePath: options.buildPlanSourcePath,
+        buildRunId: options.buildRunId ?? null,
         stage: options.stageDefinition.id,
         stageLabel: options.stageDefinition.label,
         contractType: options.stageDefinition.contractType,
@@ -43,7 +44,7 @@ function finalizeValidatedStage(options, code) {
         if (!reconciled && validation.ok) {
             return {
                 ok: false,
-                summary: "Stage did not update any declared output Artifact.",
+                summary: "Stage did not update any declared requested output.",
             };
         }
         return validation;

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

@@ -1,8 +1,8 @@
 import { type BuildPlanArtifactKind } from "../../runtime/build/build-plan-primitives.js";
 declare const BUILTIN_BUILD_PLAN_STAGE_IDS: {
     readonly SUMMARIZE: "summarize";
-    readonly STRUCTURE: "structure";
-    readonly SHAPE: "shape";
+    readonly KNOWLEDGE: "knowledge";
+    readonly ENTRYPOINT: "entrypoint";
 };
 type BuiltinBuildStageId = typeof BUILTIN_BUILD_PLAN_STAGE_IDS[keyof typeof BUILTIN_BUILD_PLAN_STAGE_IDS];
 export declare const BUILTIN_BUILD_PLAN_ARTIFACT_IDS: {

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

@@ -5,8 +5,8 @@ import { BuildPlanContextSchemaSchema } from "../../runtime/build/lib/schema.js"
 import { PACKAGE_ROOT } from "./lib/package-root.js";
 const BUILTIN_BUILD_PLAN_STAGE_IDS = {
     SUMMARIZE: "summarize",
-    STRUCTURE: "structure",
-    SHAPE: "shape",
+    KNOWLEDGE: "knowledge",
+    ENTRYPOINT: "entrypoint",
 };
 export const BUILTIN_BUILD_PLAN_ARTIFACT_IDS = {
     SUMMARIES: "summaries",
@@ -30,7 +30,7 @@ let builtinBuildPlanContractCache = null;
 const BUILTIN_DEFAULT_BUILD_PLAN_ROOT = join(PACKAGE_ROOT, "public-repo", "build-plans", "interf-default");
 function assertBuiltinArtifactId(value) {
     if (!BUILTIN_ARTIFACT_ID_SET.has(value)) {
-        throw new Error(`Built-in Interf Build Plan schema declares unsupported Artifact id "${value}".`);
+        throw new Error(`Built-in Interf Build Plan schema declares unsupported requested output id "${value}".`);
     }
     return value;
 }

package/dist/packages/build-plans/package/context-interface.d.ts

@@ -30,6 +30,9 @@ export declare const ContextInterfaceSchema: z.ZodObject<{
                 frontmatter_required_keys: "frontmatter_required_keys";
                 frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                 source_refs_required: "source_refs_required";
+                summary_backlinks_present: "summary_backlinks_present";
+                knowledge_web_connectivity: "knowledge_web_connectivity";
+                graph_notes_connected: "graph_notes_connected";
                 wikilinks_valid: "wikilinks_valid";
                 must_not_contain: "must_not_contain";
                 must_contain: "must_contain";

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

@@ -5,7 +5,7 @@ import { warnInterf } from "../../contracts/utils/logger.js";
 import { readJsonFileUnchecked } from "../../contracts/utils/parse.js";
 import { BuildPlanContextSchemaSchema, BuildPlanArtifactIdSchema, } from "../../runtime/build/lib/schema.js";
 import { listBuiltinBuildPlanArtifactSpecs, requiredBuildPlanArtifactOwners, } from "./builtin-build-plan.js";
-// Build Plan packages define the requested Artifact contract. The local service 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 the Context Graph must implement."
 export const CONTEXT_INTERFACE_FILE = "build-plan.schema.json";
@@ -13,7 +13,7 @@ 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 service materializes the context
-// requested Artifact contract on disk.
+// requested output contract on disk.
 export const BuildPlanInputSpecSchema = z.object({
     id: BuildPlanArtifactIdSchema,
     label: z.string().min(1),
@@ -69,7 +69,7 @@ export function summarizeContextInterface(contextInterface) {
 export function deriveBuildPlanInputsFromContextInterface(_contextInterface) {
     return [];
 }
-export function buildContextInterface(stages, label = "Build Plan requested Artifact contract") {
+export function buildContextInterface(stages, label = "Build Plan requested output contract") {
     return {
         kind: "build-plan-schema",
         version: 1,
@@ -102,12 +102,12 @@ export function readContextInterface(rootPath) {
     const path = contextInterfaceFilePath(rootPath);
     if (!existsSync(path))
         return null;
-    const raw = readJsonFileUnchecked(path, "Build Plan requested Artifact contract");
+    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 requested Artifact contract 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.js

@@ -20,7 +20,7 @@ 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",
@@ -53,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");
@@ -65,7 +65,7 @@ function renderBuildPlanReadme(buildPlan) {
         : [];
     const contextInterfaceLines = contextInterfaceArtifacts.length > 0
         ? contextInterfaceArtifacts
-            .map((artifact) => `- \`${artifact.id}\` — ${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
@@ -78,7 +78,7 @@ function renderBuildPlanReadme(buildPlan) {
         : null;
     const contextInterfaceSummaryLines = interfaceSummary
         ? [
-            `- Output Artifacts: ${interfaceSummary.outputArtifacts.length > 0 ? interfaceSummary.outputArtifacts.map((artifact) => `\`${artifact.id}\``).join(", ") : "none"}`,
+            `- Requested outputs: ${interfaceSummary.outputArtifacts.length > 0 ? interfaceSummary.outputArtifacts.map((artifact) => `\`${artifact.id}\``).join(", ") : "none"}`,
         ].join("\n")
         : null;
     return [
@@ -105,7 +105,7 @@ function renderBuildPlanReadme(buildPlan) {
         ...(contextInterfaceLines
             ? [
                 "",
-                "## Requested Artifact Contract",
+                "## Requested Output Contract",
                 "",
                 ...(contextInterfaceSummaryLines
                     ? [
@@ -113,7 +113,7 @@ function renderBuildPlanReadme(buildPlan) {
                         "",
                     ]
                     : []),
-                "Artifact map:",
+                "Requested output map:",
                 "",
                 contextInterfaceLines,
             ]
@@ -122,7 +122,7 @@ function renderBuildPlanReadme(buildPlan) {
         "## Package",
         "",
         "- `build-plan.json` = Build Plan stage flow, local-engine API target, and build contract mapping",
-        "- `build-plan.schema.json` = deterministic requested Artifact contract for the Build Plan",
+        "- `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",
@@ -142,9 +142,9 @@ 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 task.`,
-        "It starts with that Build Plan topology; edit the package when the agent task 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. Keep purpose, inputs, requested Artifact contract, 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",
         "",
@@ -161,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 task 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, requested Artifact contract, 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");
 }
@@ -176,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, requested Artifact contract, stages, stage docs, evidence 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");
 }
@@ -199,7 +199,7 @@ function renderImproveSkill(buildPlan) {
         "- 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, requested Artifact contract, and stages should describe the same agent task",
+        "- 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");
@@ -222,15 +222,15 @@ 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.",
+        "- 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,
@@ -258,7 +258,7 @@ 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,
@@ -422,13 +422,13 @@ export function createScratchLocalBuildPlanPackage(options) {
             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",
-                            description: "The draft Artifact exists and contains at least one file.",
+                            description: "The draft output exists and contains at least one file.",
                             required: true,
                             params: { min: 1 },
                         },
@@ -452,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

@@ -3,10 +3,7 @@ import { BuildPlanRuntimeApiSchema, BuildPlanPurposeSchema, type BuildPlanStageA
 import { RuntimeContractTypeSchema } from "../../contracts/lib/schema.js";
 import { BuildPlanInputSpecSchema, type ContextInterface, type BuildPlanInputSpec } from "./context-interface.js";
 import { type BuildPlanAuthoringBrief } from "../authoring/brief.js";
-interface LocalBuildPlanStarterDoc {
-    relativePath: string;
-    content: string;
-}
+import type { BuildPlanStarterDoc } from "./build-plan-definitions.js";
 interface LocalBuildPlanStageDefinition {
     id: string;
     label: string;
@@ -34,7 +31,7 @@ export interface LocalBuildPlanDefinition {
     stages?: LocalBuildPlanStageDefinition[];
     stage_policy_notes?: Record<string, string[]>;
     build_plan_schema: ContextInterface;
-    starter_docs: LocalBuildPlanStarterDoc[];
+    starter_docs: BuildPlanStarterDoc[];
     directoryPath: string;
     buildPlanPath: string;
     buildPlanSchemaPath: string;
@@ -73,4 +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 {};