@interf/compiler 0.22.0 → 0.33.0

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

@@ -1,7 +1,6 @@
-import { type BuildPlanAuthoringArtifactRequirement } from "../../engine/agents/lib/shells.js";
-import type { AgentExecutor } from "../../engine/agents/lib/executors.js";
+import type { AgentExecutor } from "../../runtime/agents/lib/executors.js";
 import { validateBuildPlanPackage } from "../package/local-build-plans.js";
-import type { RequestedArtifact, SourceProfile, SourceReadinessCheck } from "../../project/lib/schema.js";
+import type { BuildPlanAuthoringArtifactRequirement, BuildPlanContextCheckDraft, RequestedArtifact, SourceContext } from "./brief.js";
 /**
  * Walk build-plan.json after a successful authoring run and fill in
  * `role: "general"` for any stage missing a role field. Custom role
@@ -10,7 +9,7 @@ import type { RequestedArtifact, SourceProfile, SourceReadinessCheck } from "../
  * touched so the runtime can surface that to the user.
  */
 export declare function ensureStageRoles(buildPlanPath: string): string[];
-export interface BuildPlanAuthoringRunResult {
+interface BuildPlanAuthoringRunResult {
     status: "updated" | "no-change" | "invalid" | "executor-failed";
     changed: boolean;
     summary: string;
@@ -19,18 +18,19 @@ export interface BuildPlanAuthoringRunResult {
     shellPath: string;
 }
 export declare function runBuildPlanAuthoringDraft(options: {
-    prepDataDir: string;
+    projectDataDir: string;
     sourceFolderPath: string;
     baseBuildPlanId?: string;
     buildPlanId: string;
     label: string;
-    hint: string;
-    taskPrompt: string;
-    checks?: SourceReadinessCheck[];
+    hint?: string;
+    intent: string;
+    checks?: BuildPlanContextCheckDraft[];
+    userPrepInstructions?: string;
     requestedArtifacts?: RequestedArtifact[];
-    sourceProfile?: SourceProfile | null;
+    sourceContext?: SourceContext | null;
     artifactRequirements?: BuildPlanAuthoringArtifactRequirement[];
     executor: AgentExecutor;
     onStatus?: (line: string) => void;
 }): Promise<BuildPlanAuthoringRunResult>;
-export declare function resolveBuildPlanDraftPath(sourcePath: string, buildPlanId: string): string;
+export {};

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

@@ -1,9 +1,9 @@
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { createBuildPlanAuthoringShell, } from "../../engine/agents/lib/shells.js";
+import { createBuildPlanAuthoringShell, } from "../../runtime/agents/lib/shells.js";
 import { createScratchLocalBuildPlanPackage } from "../package/interf-build-plan-package.js";
 import { CONTEXT_INTERFACE_FILE, listContextInterfaceArtifacts } from "../package/context-interface.js";
-import { loadBuildPlanDefinitionFromDir, validateBuildPlanPackage, buildPlanDefinitionPath, } from "../package/local-build-plans.js";
+import { loadBuildPlanDefinitionFromDir, validateBuildPlanPackage, } from "../package/local-build-plans.js";
 import { runBuildPlanEditSession } from "./build-plan-edit-session.js";
 /**
  * Walk build-plan.json after a successful authoring run and fill in
@@ -61,30 +61,48 @@ function buildBuildPlanAuthoringPrompt() {
     return [
         "This is an automated Interf Build Plan authoring run, not an open-ended chat session.",
         "Execute it now.",
-        "Create one standalone Build Plan package for the source data, desired verifiable-context outputs, and proof requirements in this source folder.",
+        "Create one standalone Build Plan package for the Source data, requested Artifacts, Context Checks, and evidence requirements behind the Source locator.",
         "Read `runtime/authoring-context.json` first.",
-        "Treat `task_prompt` as the user's preparation-and-evidence brief: source data, output shape, and evidence that should show the data is ready.",
+        "Treat `intent`, `requested_artifacts`, `checks`, `user_prep_instructions`, and `source_context` as the user's agent task and evidence brief.",
         `Then read \`build-plan/README.md\`, \`build-plan/build-plan.json\`, and \`build-plan/${CONTEXT_INTERFACE_FILE}\`.`,
         "The `build-plan/` directory starts as a neutral Build Plan scaffold, not as a suggested final plan.",
-        "Replace the scaffold purpose, inputs, Artifacts, stages, stage docs, checks, and query guidance with the Build Plan this agent work actually needs.",
-        "Read `runtime/source-files.json` and inspect the listed source locators before editing the package.",
+        "Replace the scaffold purpose, inputs, Artifacts, stages, stage docs, checks, and query guidance with the Build Plan this agent task actually needs.",
+        "Read `runtime/source-locator.json` and inspect the Source through your own available tools before editing the package.",
         "Prefer direct file-reading and search tools over shell commands for routine file inspection.",
         "Do not use shell helpers like `cat`, `sed`, `ls`, or `find` when a native read/search tool can inspect the same files.",
         "Edit only files under `build-plan/`.",
         "Keep the Build Plan valid for the current local-engine API and `build-plan.schema.json`.",
-        "Choose stage ids, stage order, artifact reads, artifact writes, artifact checks, and stage docs from the source data and preparation-and-evidence brief.",
+        "Choose stage ids, stage order, Artifact reads, Artifact writes, Artifact diagnostics, and stage docs from the source data, agent task, and evidence brief.",
+        "Stage `reads` may only contain requested Artifact ids that are declared in `build-plan.schema.json` and produced by an earlier stage. Source files are implicit input through runtime stage assignment; never put `source`, source file paths, or source-folder ids in stage `reads`.",
         "Use kebab-case ids everywhere: stage ids, skill_dir values, Artifact ids, reads/writes values, and package ids. Never use underscores.",
         "Each stage MAY declare a `role`: one of `extractor`, `summarizer`, `structurer`, `verifier`, or `general`. Pick the role that best matches what the stage's prompt asks the agent to do. Omit `role` (or use `general`) when the stage doesn't fit any specialized role. Custom role names are allowed; the engine treats unknown roles as `general`.",
         "Do not preserve the placeholder `prepare` stage unless the final Build Plan genuinely needs a stage with that exact role.",
+        "Treat `checks` as user-facing Context Checks: plain-English promises under `What Interf will prove`.",
+        "Create Context Checks first, then requested Artifacts that back those checks, then deterministic Artifact diagnostics (`checks[]`) that validate the produced files.",
+        "For file-based Projects, every final Build Plan must preserve the three-layer Context Graph shape: `summaries/` for source coverage, `knowledge/` for task-aware claims/entities/topics/indexes, and `artifacts/` for the task-specific agent handoff.",
+        "`summaries/` is the coverage layer. It should prove what source files were inspected. For PDFs, decks, or paginated reports, prefer page-level notes or explicit page coverage records when practical; each summary must link back to the original Source path, page, section, figure, table, or other source reference instead of copying the Source file.",
+        "`knowledge/` is the graph layer. The current default contract is flat `knowledge/*.md` notes. It should be built from summaries and source references, and may contain claims, entities, topics, and indexes. Treat knowledge notes as navigation and assurance, not as the authority for exact wording, table values, chart reads, or provenance-sensitive claims.",
+        "`artifacts/` is the agent handoff layer. Requested Artifacts should live under `artifacts/` by default and should tell the downstream agent which original Source files, pages, figures, tables, sections, units, periods, series, and caveats matter for the task.",
+        "Requested Artifacts should normally route the downstream agent to the right original Source evidence. They should not present generated summaries or knowledge notes as the dataset or source of truth.",
+        "For tasks that depend on charts, tables, images, or other visual evidence, requested Artifacts must capture the source semantics needed to answer: target period, unit, series/legend, axis or table interpretation, exact printed values when available, bounded ranges when not, evidence tier, and source page.",
+        "For unlabeled charts, screenshots, diagrams, or visual marks, do not write a final numeric answer unless the Artifact also captures a source-grounded measurement method, visual reference, axis/table calibration, and uncertainty. Otherwise the Artifact must route the downstream agent to inspect the original Source before answering.",
+        "Do not let structural diagnostics such as file_exists, frontmatter_required_keys, or must_contain stand in for evidence fidelity. Use stage docs and Artifact descriptions to require the semantic fields the agent task needs.",
+        "If a visual source has no printed data labels, the Artifact should preserve a bounded read at source granularity and should mark unresolved semantics instead of inventing pseudo-exact precision.",
+        "Verification stages must not pass by comparing generated notes only to other generated notes. If a verifier did not inspect the relevant original Source reference, page-level summary with source refs, table extraction, visual trace, or measurement Artifact required by the claim, it must report the claim as not verified.",
+        "Preserve `backed_by_artifact_ids` in the Build Plan brief and use the matching requested Artifact ids in `build-plan.schema.json`.",
+        "When `runtime/authoring-context.json.artifact_requirements[]` is non-empty, it is binding: copy each requirement's `id`, `shape`, and `checks[]` exactly into `build-plan.schema.json`.",
+        "Do not rename, move, merge, split, or reinterpret required Artifacts. `stage_hint` can guide which stage writes the Artifact, but it never changes the required `shape.path`, `shape.artifact_kind`, or diagnostic contract.",
         "Put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks.",
         "Use only the CheckKind values listed in `runtime/authoring-context.json`; do not invent aliases.",
-        "Keep Artifact checks aligned with produced outputs. Use stage docs to describe the output contract, but do not turn source-specific user wording into brittle stage-doc wording requirements.",
+        "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.",
+        "Keep Artifact diagnostics aligned with produced requested Artifacts. Use stage docs to describe the Artifact contract, but do not turn source-specific user wording into brittle stage-doc wording requirements.",
         "For every stage in `build-plan.json`, create `build-plan/build/stages/<skill_dir>/SKILL.md` and make the folder name exactly match that stage's kebab-case `skill_dir`.",
-        "Every Artifact path in `build-plan.schema.json` must be unique and non-overlapping.",
-        "Make the package materially specific to this Preparation task, output shape, and proof requirement. A no-op scaffold is not acceptable.",
-        "Treat the Build Plan as four aligned layers: purpose, inputs, context interface, and stages.",
-        "If the Build Plan writes an agent entrypoint, declare it as an Artifact and make the final shaping stage own it.",
-        "Prefer explicit stage-doc, stage-policy, purpose, input-contract, and context-interface edits over vague rewrites.",
+        "Every Artifact path in `build-plan.schema.json` must be unique. Child Artifacts may live under the required layer directories `summaries/`, `knowledge/`, and `artifacts/`; unrelated Artifact paths must not overlap.",
+        "Make the package materially specific to this Project's agent task, output shape, checks, and evidence requirement. A no-op scaffold is not acceptable.",
+        "Treat the Build Plan as four aligned layers: purpose, inputs, requested Artifact contract, and stages.",
+        "If the Build Plan writes a graph index, declare it as an Artifact and make the final shaping stage own it.",
+        "Prefer explicit stage-doc, stage-policy, purpose, input-contract, and requested-Artifact-contract edits over vague rewrites.",
         "Do not introduce wikilinks unless the Build Plan also creates the target note by exact basename or explicit relative path.",
         "Respect stage boundaries: a stage may only introduce links that resolve within that stage's declared writes or already-existing read Artifacts.",
         "Do not make one stage point at files or notes that are only created later by another stage.",
@@ -107,12 +125,30 @@ function stableJson(value) {
         .map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
         .join(",")}}`;
 }
+function writeBuildPlanAuthoringBrief(buildPlanPath, brief) {
+    const buildPlanJsonPath = join(buildPlanPath, "build-plan.json");
+    if (!existsSync(buildPlanJsonPath))
+        return;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(buildPlanJsonPath, "utf8"));
+    }
+    catch {
+        return;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return;
+    writeFileSync(buildPlanJsonPath, `${JSON.stringify({ ...parsed, brief }, null, 2)}\n`);
+}
 function checkMatchesRequirement(actual, required) {
     return actual.id === required.id &&
         actual.kind === required.kind &&
         (actual.required ?? true) === (required.required ?? true) &&
         stableJson(actual.params) === stableJson(required.params);
 }
+function compactJson(value) {
+    return JSON.stringify(value);
+}
 function producingStagesForArtifact(definition, artifactId) {
     return (definition.stages ?? []).filter((stage) => Array.isArray(stage.writes) && stage.writes.includes(artifactId));
 }
@@ -128,11 +164,11 @@ function validateArtifactRequirements(definition, requirements) {
         if (artifact.shape.kind !== requirement.shape.kind ||
             artifact.shape.path !== requirement.shape.path ||
             artifact.shape.artifact_kind !== requirement.shape.artifact_kind) {
-            errors.push(`Artifact \`${requirement.id}\` does not match required shape.`);
+            errors.push(`Artifact \`${requirement.id}\` must declare required shape ${compactJson(requirement.shape)}; found ${compactJson(artifact.shape)}.`);
         }
         for (const check of requirement.checks) {
             if (!artifact.checks.some((candidate) => checkMatchesRequirement(candidate, check))) {
-                errors.push(`Artifact \`${requirement.id}\` is missing required check \`${check.id}\`.`);
+                errors.push(`Artifact \`${requirement.id}\` must include required diagnostic ${compactJson(check)}.`);
             }
         }
         const producingStages = producingStagesForArtifact(definition, requirement.id);
@@ -144,8 +180,6 @@ function validateArtifactRequirements(definition, requirements) {
 }
 function validateAuthoredBuildPlanPackage(buildPlanPath, artifactRequirements = []) {
     const validation = validateBuildPlanPackage(buildPlanPath);
-    if (!validation.ok)
-        return validation;
     const definition = loadBuildPlanDefinitionFromDir(buildPlanPath);
     if (!definition)
         return validation;
@@ -177,10 +211,10 @@ function validateAuthoredBuildPlanPackage(buildPlanPath, artifactRequirements =
 }
 export async function runBuildPlanAuthoringDraft(options) {
     const buildPlanPath = createScratchLocalBuildPlanPackage({
-        prepDataDir: options.prepDataDir,
+        projectDataDir: options.projectDataDir,
         buildPlanId: options.buildPlanId,
         label: options.label,
-        hint: options.hint,
+        hint: options.hint ?? options.intent,
     });
     const shell = createBuildPlanAuthoringShell({
         buildPlanPath,
@@ -188,10 +222,11 @@ export async function runBuildPlanAuthoringDraft(options) {
         label: options.label,
         referenceBuildPlanId: options.baseBuildPlanId ?? null,
         sourceFolderPath: options.sourceFolderPath,
-        taskPrompt: options.taskPrompt,
+        intent: options.intent,
         checks: options.checks ?? [],
+        userPrepInstructions: options.userPrepInstructions,
         requestedArtifacts: options.requestedArtifacts ?? [],
-        sourceProfile: options.sourceProfile ?? null,
+        sourceContext: options.sourceContext ?? null,
         artifactRequirements: options.artifactRequirements ?? [],
     });
     const session = await runBuildPlanEditSession({
@@ -200,20 +235,28 @@ export async function runBuildPlanAuthoringDraft(options) {
         shell,
         prompt: buildBuildPlanAuthoringPrompt(),
         validate: (buildPlanPath) => validateAuthoredBuildPlanPackage(buildPlanPath, options.artifactRequirements ?? []),
-        maxValidationRepairAttempts: 1,
+        maxValidationRepairAttempts: 2,
         onStatus: options.onStatus,
     });
     if (session.status !== "updated") {
         rmSync(buildPlanPath, { recursive: true, force: true });
     }
     else {
-        // 0.15 — auto-fill `role: "general"` for any stage the agent
+        // auto-fill `role: "general"` for any stage the agent
         // didn't explicitly tag. Idempotent and silent when every stage
         // already declares a role.
         const touched = ensureStageRoles(buildPlanPath);
         if (touched.length > 0 && options.onStatus) {
             options.onStatus(`STATUS: filled role=general on ${touched.length} stage(s) the author didn't tag (${touched.join(", ")}).`);
         }
+        writeBuildPlanAuthoringBrief(buildPlanPath, {
+            intent: options.intent,
+            requested_artifacts: options.requestedArtifacts ?? [],
+            checks: options.checks ?? [],
+            ...(options.userPrepInstructions ? { user_prep_instructions: options.userPrepInstructions } : {}),
+            source_context: options.sourceContext ?? null,
+            artifact_requirements: options.artifactRequirements ?? [],
+        });
     }
     return {
         status: session.status,
@@ -224,6 +267,3 @@ export async function runBuildPlanAuthoringDraft(options) {
         shellPath: shell.rootPath,
     };
 }
-export function resolveBuildPlanDraftPath(sourcePath, buildPlanId) {
-    return buildPlanDefinitionPath(sourcePath, buildPlanId);
-}

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

@@ -1,4 +1,4 @@
-import type { AgentExecutor } from "../../engine/agents/lib/executors.js";
+import type { AgentExecutor } from "../../runtime/agents/lib/executors.js";
 import type { BuildPlanValidationResult } from "../package/local-build-plans.js";
 import { type BuildPlanEditShellArtifacts } from "./lib/build-plan-edit-utils.js";
 export interface BuildPlanEditSessionResult {

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

@@ -95,11 +95,17 @@ 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.",
             "- Keep every stage `skill_dir` matched by `build-plan/build/stages/<skill_dir>/SKILL.md`.",
-            "- Keep `build-plan.schema.json` Artifact paths unique and non-overlapping.",
+            "- 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.",
             "- Use only CheckKind values listed in `runtime/authoring-context.json`; replace invented aliases with valid kinds.",
-            "- If the Build Plan writes an agent entrypoint, keep it declared as an Artifact owned by the producing stage.",
+            "- 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.",
             "- 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.d.ts

@@ -1,8 +1,7 @@
-import type { AgentExecutor } from "../../engine/agents/lib/executors.js";
+import type { AgentExecutor } from "../../runtime/agents/lib/executors.js";
 import { type BuildPlanValidationResult } from "../package/local-build-plans.js";
-import type { SourcePreparationConfig } from "../../project/lib/schema.js";
-import type { BuildPlanImprovementLoopSummary } from "../../engine/build/lib/schema.js";
-export interface BuildPlanImprovementRunResult {
+import type { BuildPlanImprovementLoopSummary } from "../../runtime/build/lib/schema.js";
+interface BuildPlanImprovementRunResult {
     status: "updated" | "no-change" | "invalid" | "executor-failed";
     changed: boolean;
     validation: BuildPlanValidationResult | null;
@@ -12,12 +11,16 @@ export interface BuildPlanImprovementRunResult {
 }
 export declare function runBuildPlanImprovementLoop(options: {
     executor: AgentExecutor;
-    verifiableContextPath: string;
+    contextGraphPath: string;
     buildPlanId: string;
-    verifiableContextConfig: Pick<SourcePreparationConfig, "checks">;
+    benchmarkChecks: Array<{
+        id: string;
+        question: string;
+    }>;
     runId: string;
     loopIndex: number;
     maxLoops: number;
     maxAttempts: number;
     previousVariations: BuildPlanImprovementLoopSummary[];
 }): Promise<BuildPlanImprovementRunResult>;
+export {};

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

@@ -1,14 +1,14 @@
 import { appendFileSync, existsSync, mkdirSync, writeFileSync, } from "node:fs";
 import { join, relative } from "node:path";
-import { createBuildPlanImprovementShell, freezeBuildPlanImprovementShell, } from "../../engine/agents/lib/shells.js";
+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 { targetTestRunsRootForVerifiableContext, targetTestSandboxesRootForVerifiableContext, buildPlanImprovementRunRoot, buildPlanPackagePathForVerifiableContext, } from "../../engine/build/verifiable-context-paths.js";
-import { readInterfConfig } from "../../project/interf.js";
-import { saveVerifiableContextInterfConfig } from "../../project/source-config.js";
-import { BuildPlanImprovementRunLedgerSchema, } from "../../engine/build/lib/schema.js";
+import { targetTestRunsRootForContextGraph, targetTestSandboxesRootForContextGraph, buildPlanImprovementRunRoot, buildPlanPackagePathForContextGraph, } from "../../runtime/build/context-graph-paths.js";
+import { readInterfConfig } from "../../projects/interf.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";
 function toShellArtifactPath(absolutePath, sourceRoot, shellRoot) {
@@ -21,34 +21,31 @@ function toShellArtifactPath(absolutePath, sourceRoot, shellRoot) {
     const relativePath = relative(sourceRoot, absolutePath);
     return join(shellRoot, relativePath);
 }
-function mapLoopSummaryForShell(summary, verifiableContextPath) {
+function mapLoopSummaryForShell(summary, contextGraphPath) {
     const shellTestRunsRoot = "artifacts/test-runs";
     const shellTestSandboxesRoot = "artifacts/test-sandboxes";
     return {
         ...summary,
-        test_run_path: toShellArtifactPath(summary.test_run_path, targetTestRunsRootForVerifiableContext(verifiableContextPath), shellTestRunsRoot) ?? summary.test_run_path ?? null,
-        test_sandbox_path: toShellArtifactPath(summary.test_sandbox_path, targetTestSandboxesRootForVerifiableContext(verifiableContextPath), shellTestSandboxesRoot) ?? summary.test_sandbox_path ?? null,
+        test_run_path: toShellArtifactPath(summary.test_run_path, targetTestRunsRootForContextGraph(contextGraphPath), shellTestRunsRoot) ?? summary.test_run_path ?? null,
+        test_sandbox_path: toShellArtifactPath(summary.test_sandbox_path, targetTestSandboxesRootForContextGraph(contextGraphPath), shellTestSandboxesRoot) ?? summary.test_sandbox_path ?? null,
     };
 }
 function buildLoopContext(options) {
-    const previousVariations = options.previousVariations.map((summary) => mapLoopSummaryForShell(summary, options.verifiableContextPath));
+    const previousVariations = options.previousVariations.map((summary) => mapLoopSummaryForShell(summary, options.contextGraphPath));
     const latestFailure = previousVariations.at(-1) ?? null;
     return {
         kind: "interf-build-plan-improvement-loop",
         version: 1,
         generated_at: new Date().toISOString(),
-        target_name: readInterfConfig(options.verifiableContextPath)?.name ?? "verifiable-context",
+        target_name: readInterfConfig(options.contextGraphPath)?.name ?? "context-graph",
         build_plan_id: options.buildPlanId,
         loop_index: options.loopIndex,
         max_loops: options.maxLoops,
         max_attempts: options.maxAttempts,
-        review_paths: resolveBuildPlanImprovementReviewPaths(options.verifiableContextPath),
-        readiness_checks: {
-            count: options.verifiableContextConfig.checks.length,
-            questions: options.verifiableContextConfig.checks.map((check, index) => ({
-                id: check.id ?? `check-${index + 1}`,
-                question: check.question,
-            })),
+        review_paths: resolveBuildPlanImprovementReviewPaths(options.contextGraphPath),
+        benchmark_questions: {
+            count: options.benchmarkChecks.length,
+            questions: options.benchmarkChecks,
         },
         previous_variations: previousVariations,
         latest_failure: latestFailure,
@@ -62,10 +59,10 @@ 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, context interface, and stages.",
-        "Prefer editing the stage docs, Build Plan contract, input contract, or schema ownership that actually change verifiable-context outputs.",
+        "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.",
         "Edit only files under `build-plan/`.",
-        "Do not edit checks, test specs, source files, or generated verifiable-context outputs.",
+        "Do not edit checks, benchmark specs, source files, or generated requested Artifacts.",
         "Keep the Build Plan package valid for the current build API and `build-plan.schema.json`.",
         "Respect stage boundaries: a stage may only introduce links that resolve within that stage's declared writes or already-existing read Artifacts.",
         "Do not make one stage point at files or notes that are only created later by another stage.",
@@ -76,7 +73,7 @@ function buildBuildPlanImprovementPrompt() {
     ].join("\n");
 }
 function updateBuildPlanOrigin(options) {
-    const current = readInterfConfig(options.verifiableContextPath);
+    const current = readInterfConfig(options.contextGraphPath);
     if (!current)
         return;
     const nextConfig = {
@@ -86,27 +83,27 @@ function updateBuildPlanOrigin(options) {
             ...(options.localDraft ? { local_draft: true } : {}),
         },
     };
-    saveVerifiableContextInterfConfig(options.verifiableContextPath, nextConfig);
+    saveContextGraphInterfConfig(options.contextGraphPath, nextConfig);
 }
-function buildPlanImprovementRunLedgerPath(verifiableContextPath, runId) {
-    return join(buildPlanImprovementRunRoot(verifiableContextPath, runId), "run.json");
+function buildPlanImprovementRunLedgerPath(contextGraphPath, runId) {
+    return join(buildPlanImprovementRunRoot(contextGraphPath, runId), "run.json");
 }
-function buildPlanImprovementLoopHistoryPath(verifiableContextPath, runId) {
-    return join(buildPlanImprovementRunRoot(verifiableContextPath, runId), "loop-history.jsonl");
+function buildPlanImprovementLoopHistoryPath(contextGraphPath, runId) {
+    return join(buildPlanImprovementRunRoot(contextGraphPath, runId), "loop-history.jsonl");
 }
 function buildPlanImprovementLoopRecordPath(loopRootPath) {
     return join(loopRootPath, "loop.json");
 }
-function readBuildPlanImprovementRunLedger(verifiableContextPath, runId) {
-    const ledgerPath = buildPlanImprovementRunLedgerPath(verifiableContextPath, runId);
+function readBuildPlanImprovementRunLedger(contextGraphPath, runId) {
+    const ledgerPath = buildPlanImprovementRunLedgerPath(contextGraphPath, runId);
     if (!existsSync(ledgerPath))
         return null;
     return readJsonFileWithSchema(ledgerPath, "Build Plan improvement run ledger", BuildPlanImprovementRunLedgerSchema);
 }
-function writeBuildPlanImprovementRunLedger(verifiableContextPath, runId, record, options) {
-    const runRoot = buildPlanImprovementRunRoot(verifiableContextPath, runId);
+function writeBuildPlanImprovementRunLedger(contextGraphPath, runId, record, options) {
+    const runRoot = buildPlanImprovementRunRoot(contextGraphPath, runId);
     mkdirSync(runRoot, { recursive: true });
-    const existing = readBuildPlanImprovementRunLedger(verifiableContextPath, runId);
+    const existing = readBuildPlanImprovementRunLedger(contextGraphPath, runId);
     const generatedAt = existing?.generated_at ?? new Date().toISOString();
     const ledger = {
         kind: "interf-build-plan-improvement-run",
@@ -120,9 +117,9 @@ function writeBuildPlanImprovementRunLedger(verifiableContextPath, runId, record
         max_attempts: options.maxAttempts,
         loops: [...(existing?.loops ?? []), record],
     };
-    writeFileSync(buildPlanImprovementRunLedgerPath(verifiableContextPath, runId), `${JSON.stringify(ledger, null, 2)}\n`);
+    writeFileSync(buildPlanImprovementRunLedgerPath(contextGraphPath, runId), `${JSON.stringify(ledger, null, 2)}\n`);
     writeFileSync(buildPlanImprovementLoopRecordPath(record.loop_root_path), `${JSON.stringify(record, null, 2)}\n`);
-    appendFileSync(buildPlanImprovementLoopHistoryPath(verifiableContextPath, runId), `${JSON.stringify(record)}\n`);
+    appendFileSync(buildPlanImprovementLoopHistoryPath(contextGraphPath, runId), `${JSON.stringify(record)}\n`);
 }
 function buildBuildPlanImprovementLoopRecord(options) {
     return {
@@ -150,17 +147,17 @@ function buildBuildPlanImprovementLoopRecord(options) {
     };
 }
 export async function runBuildPlanImprovementLoop(options) {
-    const verifiableContextName = readInterfConfig(options.verifiableContextPath)?.name ?? "verifiable-context";
+    const contextGraphName = readInterfConfig(options.contextGraphPath)?.name ?? "context-graph";
     const context = buildLoopContext(options);
     const shell = createBuildPlanImprovementShell({
-        verifiableContextPath: options.verifiableContextPath,
-        verifiableContextName,
+        contextGraphPath: options.contextGraphPath,
+        contextGraphName,
         buildPlanId: options.buildPlanId,
         runId: options.runId,
         loopIndex: options.loopIndex,
         context,
     });
-    const buildPlanRoot = buildPlanPackagePathForVerifiableContext(options.verifiableContextPath);
+    const buildPlanRoot = buildPlanPackagePathForContextGraph(options.contextGraphPath);
     const session = await runBuildPlanEditSession({
         executor: options.executor,
         buildPlanPath: buildPlanRoot,
@@ -170,13 +167,13 @@ export async function runBuildPlanImprovementLoop(options) {
         maxValidationRepairAttempts: 1,
     });
     if (session.status === "updated") {
-        // 0.15 — fill role=general on any stage the improvement run
+        // fill role=general on any stage the improvement run
         // dropped a role from. Idempotent and silent when complete.
         ensureStageRoles(buildPlanRoot);
     }
     const preservedShellManifestPath = freezeBuildPlanImprovementShell(shell.rootPath);
-    writeBuildPlanImprovementRunLedger(options.verifiableContextPath, options.runId, buildBuildPlanImprovementLoopRecord({
-        targetName: verifiableContextName,
+    writeBuildPlanImprovementRunLedger(options.contextGraphPath, options.runId, buildBuildPlanImprovementLoopRecord({
+        targetName: contextGraphName,
         buildPlanId: options.buildPlanId,
         runId: options.runId,
         loopIndex: options.loopIndex,
@@ -193,14 +190,14 @@ export async function runBuildPlanImprovementLoop(options) {
         result: session.status,
         summary: session.summary,
     }), {
-        targetName: verifiableContextName,
+        targetName: contextGraphName,
         buildPlanId: options.buildPlanId,
         maxLoops: options.maxLoops,
         maxAttempts: options.maxAttempts,
     });
     if (session.status === "updated") {
         updateBuildPlanOrigin({
-            verifiableContextPath: options.verifiableContextPath,
+            contextGraphPath: options.contextGraphPath,
             selectedBuildPlanId: options.buildPlanId,
             localDraft: true,
         });

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

@@ -5,10 +5,10 @@ export function copyDirectory(sourcePath, targetPath) {
     mkdirSync(targetPath, { recursive: true });
     cpSync(sourcePath, targetPath, { recursive: true });
 }
-function listFileSnapshot(dirPath) {
-    const snapshot = new Map();
+function listFileState(dirPath) {
+    const fileState = new Map();
     if (!existsSync(dirPath))
-        return snapshot;
+        return fileState;
     const collect = (currentPath) => {
         for (const entry of readdirSync(currentPath)) {
             const fullPath = join(currentPath, entry);
@@ -19,15 +19,15 @@ function listFileSnapshot(dirPath) {
             }
             if (!stat.isFile())
                 continue;
-            snapshot.set(relative(dirPath, fullPath), readFileSync(fullPath, "utf8"));
+            fileState.set(relative(dirPath, fullPath), readFileSync(fullPath, "utf8"));
         }
     };
     collect(dirPath);
-    return snapshot;
+    return fileState;
 }
 export function directoriesMatch(leftPath, rightPath) {
-    const left = listFileSnapshot(leftPath);
-    const right = listFileSnapshot(rightPath);
+    const left = listFileState(leftPath);
+    const right = listFileState(rightPath);
     if (left.size !== right.size)
         return false;
     for (const [relativePath, content] of left.entries()) {

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

@@ -2,5 +2,5 @@ export declare const DEFAULT_BUILD_PLAN_ID = "interf-default";
 export interface BuildPlanSelectionLike {
     build_plan?: string | null;
 }
-export declare function buildPlanIdForSourcePreparationConfig(preparationConfig: BuildPlanSelectionLike | null | undefined): string | null;
+export declare function buildPlanIdForProjectConfig(projectConfig: BuildPlanSelectionLike | null | undefined): string | null;
 export declare function resolveBuildPlanId(selection: BuildPlanSelectionLike | null | undefined, fallback?: string): string;

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

@@ -1,7 +1,7 @@
 export const DEFAULT_BUILD_PLAN_ID = "interf-default";
-export function buildPlanIdForSourcePreparationConfig(preparationConfig) {
-    return preparationConfig?.build_plan ?? null;
+export function buildPlanIdForProjectConfig(projectConfig) {
+    return projectConfig?.build_plan ?? null;
 }
 export function resolveBuildPlanId(selection, fallback = DEFAULT_BUILD_PLAN_ID) {
-    return buildPlanIdForSourcePreparationConfig(selection) ?? fallback;
+    return buildPlanIdForProjectConfig(selection) ?? fallback;
 }

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

@@ -1,2 +1,2 @@
 export * as buildPlanResolution from "./build-plan-resolution.js";
-export { DEFAULT_BUILD_PLAN_ID, buildPlanIdForSourcePreparationConfig, resolveBuildPlanId, } from "./build-plan-resolution.js";
+export { DEFAULT_BUILD_PLAN_ID, buildPlanIdForProjectConfig, resolveBuildPlanId, } from "./build-plan-resolution.js";

package/dist/packages/build-plans/index.js

@@ -1,2 +1,2 @@
 export * as buildPlanResolution from "./build-plan-resolution.js";
-export { DEFAULT_BUILD_PLAN_ID, buildPlanIdForSourcePreparationConfig, resolveBuildPlanId, } from "./build-plan-resolution.js";
+export { DEFAULT_BUILD_PLAN_ID, buildPlanIdForProjectConfig, resolveBuildPlanId, } from "./build-plan-resolution.js";

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

@@ -1,7 +1,8 @@
 import { type LocalBuildPlanDefinition } from "./local-build-plans.js";
-import type { BuildPlanEngineApi } from "../../engine/build/lib/schema.js";
+import type { BuildPlanRuntimeApi } from "../../runtime/build/lib/schema.js";
 import type { BuildPlanId, RuntimeContractType } from "../../contracts/lib/schema.js";
 import { type ContextInterface, type ContextInterfaceArtifactId, type BuildPlanInputSpec } from "./context-interface.js";
+import type { BuildPlanAuthoringBrief } from "../authoring/brief.js";
 export interface BuildPlanStarterDoc {
     relativePath: string;
     content: string;
@@ -23,11 +24,12 @@ export interface BuildPlanStageDefinition {
 }
 export interface BuildPlanDefinition<TId extends string> {
     id: TId;
-    engineApi?: BuildPlanEngineApi;
+    runtimeApi?: BuildPlanRuntimeApi;
     purpose?: {
         label: string;
         taskHint: string;
     };
+    brief?: BuildPlanAuthoringBrief;
     inputs?: BuildPlanInputSpec[];
     label: string;
     hint: string;
@@ -41,21 +43,21 @@ export interface BuildPlanDefinition<TId extends string> {
 }
 export type ResolvedBuildPlanId = string;
 export declare function standaloneBuildPlanDefinitionFromLocalPackage(local: LocalBuildPlanDefinition): BuildPlanDefinition<string>;
-export declare function listBuildPlanChoices(prepDataDir?: string): BuildPlanDefinition<string>[];
+export declare function listBuildPlanChoices(projectDataDir?: string): BuildPlanDefinition<string>[];
 export declare function getBuildPlan(buildPlanId: ResolvedBuildPlanId, options?: {
-    prepDataDir?: string;
+    projectDataDir?: string;
 }): BuildPlanDefinition<string>;
-export declare function getActiveBuildPlan(verifiableContextPath: string): BuildPlanDefinition<string>;
-export declare function resolveVerifiableContextBuildPlanId(value: unknown): ResolvedBuildPlanId | null;
+export declare function getActiveBuildPlan(contextGraphPath: string): BuildPlanDefinition<string>;
+export declare function resolveContextGraphBuildPlanId(value: unknown): ResolvedBuildPlanId | null;
 export declare function resolveBuildPlanFromConfig(config: unknown): ResolvedBuildPlanId | null;
 export declare function resolveRequiredBuildPlanFromConfig(config: unknown, label?: string): ResolvedBuildPlanId;
-export declare function getBuildPlanStageDefinition(buildPlanId: BuildPlanId, stage: string, prepDataDir?: string): BuildPlanStageDefinition | null;
-export declare function getBuildPlanStagePosition(buildPlanId: BuildPlanId, stage: string, prepDataDir?: string): {
+export declare function getBuildPlanStageDefinition(buildPlanId: BuildPlanId, stage: string, projectDataDir?: string): BuildPlanStageDefinition | null;
+export declare function getBuildPlanStagePosition(buildPlanId: BuildPlanId, stage: string, projectDataDir?: string): {
     stageIndex: number;
     stageTotal: number;
     stages: string[];
 } | null;
-export declare function getBuildPlanStages(buildPlanId: BuildPlanId, prepDataDir?: string): string[];
-export declare function getActiveBuildPlanStages(verifiableContextPath: string): string[];
-export declare function getActiveBuildPlanStagePolicyNotes(verifiableContextPath: string, stage: string): string[];
-export declare function formatActiveBuildPlanStageLabel(verifiableContextPath: string, stage: string): string;
+export declare function getBuildPlanStages(buildPlanId: BuildPlanId, projectDataDir?: string): string[];
+export declare function getActiveBuildPlanStages(contextGraphPath: string): string[];
+export declare function getActiveBuildPlanStagePolicyNotes(contextGraphPath: string, stage: string): string[];
+export declare function formatActiveBuildPlanStageLabel(contextGraphPath: string, stage: string): string;