@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/{engine → runtime}/native-run-handlers.js

@@ -2,42 +2,43 @@ import { cpSync, existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import chalk from "chalk";
-import { buildVerifiableContext, } from "./build/build-plan-runs.js";
-import { readInterfConfig } from "../project/interf.js";
-import { resolveLocalExecutor, } from "./agents/lib/executors.js";
+import { buildContextGraph, } from "./build/build-plan-runs.js";
+import { readInterfConfig } from "../projects/interf.js";
+import { buildRuntimeExecutorInfo, resolveLocalExecutor, } from "./agents/lib/executors.js";
 import { formatAgentExecutionProfile } from "./agents/lib/execution-profile.js";
 import { loadAgentsRegistry } from "./agents/registry.js";
 import { buildRoleExecutorBundle } from "./agents/role-executors.js";
 import { clearBuildRuntimeDerivedArtifacts, } from "./build/reset.js";
 import { formatActiveBuildPlanStageLabel, resolveRequiredBuildPlanFromConfig, } from "../build-plans/package/build-plan-definitions.js";
 import { createRunEventId, createRunEventTimestamp, } from "./execution/events.js";
-import { loadVerifiableContextPreparationConfig, resolvePreparationBuildMaxAttempts, resolvePreparationBuildMaxLoops, } from "../project/source-config.js";
+import { loadContextGraphProjectConfig, resolveBuildMaxAttempts, resolveBuildMaxLoops, buildTestSpecFromSourceFolderConfig, } from "../projects/source-config.js";
 import { runBuildPlanImprovementLoop } from "../build-plans/authoring/build-plan-improvement.js";
-import { stageExecutionShellsRoot, buildPlanPackagePathForVerifiableContext, } from "./build/verifiable-context-paths.js";
-import { listBuildPlanContextArtifacts, readBuildPlanContextFile } from "./build/verifiable-context-schema.js";
+import { stageExecutionShellsRoot, buildPlanPackagePathForContextGraph, } from "./build/context-graph-paths.js";
+import { listBuildPlanContextArtifacts, readBuildPlanContextFile } from "./build/context-graph-schema.js";
 import { initializeBuildRuntimeState } from "./build/state.js";
-import { readinessPassRate, runReadinessChecksForExecutor, runSavedVerifiableContextCheck, } from "./verify/readiness-check-run.js";
+import { benchmarkPassRate, runBenchmarkForExecutor, runSavedContextGraphBenchmark, } from "./verify/benchmark-run.js";
 import { runBuildPlanAuthoringDraft, } from "../build-plans/authoring/build-plan-authoring.js";
-import { draftReadinessChecks, } from "./readiness-check-draft.js";
+import { draftBenchmarkQuestions, } from "./benchmark-question-draft.js";
+import { asProjectDataDir, projectServiceJobShellsRoot, } from "../contracts/lib/project-paths.js";
 import { planActionProposalWithExecutor, } from "./action-planner.js";
-import { ActionProposalPlanSchema, } from "./lib/schema.js";
-function printBuildFailure(verifiableContextPath, failedStage) {
-    resolveRequiredBuildPlanFromConfig(readInterfConfig(verifiableContextPath), `.interf/interf.json for ${verifiableContextPath}`);
+import { ActionProposalPlanSchema, } from "./schemas/index.js";
+function printBuildFailure(contextGraphPath, failedStage) {
+    resolveRequiredBuildPlanFromConfig(readInterfConfig(contextGraphPath), `.interf/interf.json for ${contextGraphPath}`);
     let failedStageLabel = failedStage ? `Stage "${failedStage}"` : "Build";
     try {
-        failedStageLabel = formatActiveBuildPlanStageLabel(verifiableContextPath, failedStage ?? "build");
+        failedStageLabel = formatActiveBuildPlanStageLabel(contextGraphPath, failedStage ?? "build");
     }
     catch {
         // Keep the original failure visible even when the failure is outside a declared Build Plan stage.
     }
     console.log(chalk.red(`  ${failedStageLabel} failed.`));
 }
-function testScore(outcome) {
+export function testScore(outcome) {
     return (outcome.result.passedCases * 1000) + outcome.result.passedChecks;
 }
-async function buildVerifiableContextWithReporter(executor, verifiableContextPath, options = {}) {
+async function buildContextGraphWithReporter(executor, contextGraphPath, options = {}) {
     console.log();
-    console.log(chalk.bold(`  ${options.heading ?? "Building Verifiable Context..."}`));
+    console.log(chalk.bold(`  ${options.heading ?? "Building Context Graph..."}`));
     const profileLabel = formatAgentExecutionProfile(executor.executionProfile);
     if (profileLabel) {
         console.log(chalk.dim(`  Execution profile: ${profileLabel}`));
@@ -47,27 +48,28 @@ async function buildVerifiableContextWithReporter(executor, verifiableContextPat
         line: (message) => console.log(chalk.dim(`  ${message}`)),
         blankLine: () => console.log(),
     };
-    const result = await buildVerifiableContext({
+    const result = await buildContextGraph({
         executor,
         resolveStageExecutor: options.resolveStageExecutor,
-        verifiableContextPath,
+        contextGraphPath,
         reporter,
         preserveStageShells: options.preserveStageShells,
         runId: options.runId,
         events: options.events,
+        maxStageValidationAttempts: options.maxStageValidationAttempts,
     });
     if (!result.ok)
         return result;
     console.log();
-    console.log(chalk.green(`  ${options.successMessage ?? "Verifiable context ready."}`));
+    console.log(chalk.green(`  ${options.successMessage ?? "Context Graph ready."}`));
     return result;
 }
-function printSavedReadinessOutcome(prefix, outcome) {
+function printSavedBenchmarkOutcome(prefix, outcome) {
     const color = outcome.result.ok ? chalk.green : chalk.red;
     const status = outcome.result.ok ? chalk.green("PASS") : chalk.red("FAIL");
     console.log(chalk.bold(`  ${prefix}`));
     console.log();
-    console.log(color(`  ${status} ${outcome.result.passedCases}/${outcome.result.totalCases} readiness checks`));
+    console.log(color(`  ${status} ${outcome.result.passedCases}/${outcome.result.totalCases} benchmark checks`));
     console.log();
     for (const [index, caseResult] of outcome.result.caseResults.entries()) {
         const caseStatus = caseResult.ok ? chalk.green("PASS") : chalk.red("FAIL");
@@ -85,10 +87,9 @@ function printSavedReadinessOutcome(prefix, outcome) {
     }
     console.log(chalk.dim(`  Saved run: ${outcome.displayRunPath ?? outcome.runPath}`));
 }
-function bestVariationRestorePaths(verifiableContextPath) {
-    const schema = readBuildPlanContextFile(buildPlanPackagePathForVerifiableContext(verifiableContextPath));
+function bestVariationRestorePaths(contextGraphPath) {
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForContextGraph(contextGraphPath));
     const artifactPaths = (schema ? listBuildPlanContextArtifacts(schema) : [])
-        .filter((artifact) => artifact.kind !== "runtime")
         .map((artifact) => artifact.path);
     return [
         "AGENTS.md",
@@ -114,45 +115,70 @@ function copyRelativePathIfPresent(sourceRoot, targetRoot, relativePath) {
         errorOnExist: false,
     });
 }
-function snapshotBestBuildState(verifiableContextPath) {
-    const snapshotRoot = mkdtempSync(join(tmpdir(), "interf-build-attempt-"));
-    const snapshotPath = join(snapshotRoot, "verifiable-context");
-    for (const relativePath of bestVariationRestorePaths(verifiableContextPath)) {
-        copyRelativePathIfPresent(verifiableContextPath, snapshotPath, relativePath);
+function captureBestBuildState(contextGraphPath) {
+    const backupRoot = mkdtempSync(join(tmpdir(), "interf-build-attempt-"));
+    const backupPath = join(backupRoot, "context-graph");
+    for (const relativePath of bestVariationRestorePaths(contextGraphPath)) {
+        copyRelativePathIfPresent(contextGraphPath, backupPath, relativePath);
     }
-    return snapshotPath;
+    return backupPath;
 }
-function restoreBestBuildState(snapshotPath, verifiableContextPath) {
-    for (const relativePath of bestVariationRestorePaths(verifiableContextPath)) {
-        rmSync(join(verifiableContextPath, relativePath), { recursive: true, force: true });
-        copyRelativePathIfPresent(snapshotPath, verifiableContextPath, relativePath);
+function restoreBestBuildState(backupPath, contextGraphPath) {
+    for (const relativePath of bestVariationRestorePaths(contextGraphPath)) {
+        rmSync(join(contextGraphPath, relativePath), { recursive: true, force: true });
+        copyRelativePathIfPresent(backupPath, contextGraphPath, relativePath);
+    }
+    // Restoring a changed Build Plan must invalidate stage fingerprints; the next
+    // build has to validate the restored graph against the restored Plan from zero.
+    clearBuildRuntimeDerivedArtifacts(contextGraphPath);
+    initializeBuildRuntimeState(contextGraphPath);
+}
+export function createVariationBestTracker() {
+    return { outcome: null, backupPath: null, attempt: 0, variation: 0 };
+}
+export function considerVariationBest(tracker, variation, result, prune) {
+    if (result.bestOutcome &&
+        result.bestGraphBackupPath &&
+        (!tracker.outcome || testScore(result.bestOutcome) > testScore(tracker.outcome))) {
+        if (tracker.backupPath) {
+            prune(tracker.backupPath);
+        }
+        tracker.outcome = result.bestOutcome;
+        tracker.backupPath = result.bestGraphBackupPath;
+        tracker.attempt = result.bestAttempt;
+        tracker.variation = variation;
+        result.bestGraphBackupPath = null;
+        return;
+    }
+    if (result.bestGraphBackupPath) {
+        prune(result.bestGraphBackupPath);
+        result.bestGraphBackupPath = null;
     }
-    clearBuildRuntimeDerivedArtifacts(verifiableContextPath);
-    initializeBuildRuntimeState(verifiableContextPath);
 }
 async function runBuildPlanVariation(options) {
     let bestOutcome = null;
-    let bestSnapshotPath = null;
+    let bestGraphBackupPath = null;
     let bestAttempt = 0;
     let attemptsRun = 0;
     try {
         for (let attempt = 1; attempt <= options.maxAttempts; attempt += 1) {
             attemptsRun = attempt;
-            const result = await buildVerifiableContextWithReporter(options.executor, options.verifiableContextPath, {
+            const result = await buildContextGraphWithReporter(options.executor, options.contextGraphPath, {
                 heading: options.maxAttempts > 1
-                    ? `Building Verifiable Context (${options.variationLabel}, attempt ${attempt}/${options.maxAttempts})...`
-                    : `Building Verifiable Context (${options.variationLabel})...`,
+                    ? `Building Context Graph (${options.variationLabel}, attempt ${attempt}/${options.maxAttempts})...`
+                    : `Building Context Graph (${options.variationLabel})...`,
                 successMessage: options.maxAttempts > 1
-                    ? `Verifiable context ready for ${options.variationLabel}, attempt ${attempt}.`
-                    : `Verifiable context ready for ${options.variationLabel}.`,
+                    ? `Context Graph ready for ${options.variationLabel}, attempt ${attempt}.`
+                    : `Context Graph ready for ${options.variationLabel}.`,
                 preserveStageShells: options.preserveStageShells,
                 runId: options.runId,
                 events: options.events,
                 resolveStageExecutor: options.resolveStageExecutor,
+                maxStageValidationAttempts: options.maxAttempts,
             });
             if (!result.ok) {
-                printBuildFailure(options.verifiableContextPath, result.failedStage);
-                printStageShellReviewHint(options.verifiableContextPath, options.preserveStageShells, "failure");
+                printBuildFailure(options.contextGraphPath, result.failedStage);
+                printStageShellReviewHint(options.contextGraphPath, options.preserveStageShells, "failure");
                 if (attempt < options.maxAttempts) {
                     console.log(chalk.yellow(`  ${options.variationLabel} attempt ${attempt}/${options.maxAttempts} failed. Retrying with a fresh build.`));
                     continue;
@@ -162,16 +188,16 @@ async function runBuildPlanVariation(options) {
                     attemptsRun,
                     failedStage: result.failedStage,
                     bestOutcome,
-                    bestSnapshotPath,
+                    bestGraphBackupPath,
                     bestAttempt,
                     fatalError: null,
                 };
             }
-            const outcome = await runSavedVerifiableContextCheck({
+            const outcome = await runSavedContextGraphBenchmark({
                 sourcePath: options.sourcePath,
-                preparationConfig: options.verifiableContextConfig,
+                projectConfig: options.contextGraphConfig,
                 executor: options.testExecutor,
-                verifiableContextPath: options.verifiableContextPath,
+                contextGraphPath: options.contextGraphPath,
                 preserveSandboxes: options.preserveStageShells === "always" ? "always" : "on-failure",
             });
             if (!outcome) {
@@ -180,31 +206,31 @@ async function runBuildPlanVariation(options) {
                     attemptsRun,
                     failedStage: null,
                     bestOutcome,
-                    bestSnapshotPath,
+                    bestGraphBackupPath,
                     bestAttempt,
-                    fatalError: "Could not run saved readiness checks against verifiable context after build.",
+                    fatalError: "Could not run saved benchmark checks against Context Graph after build.",
                 };
             }
             console.log();
-            printSavedReadinessOutcome(`${options.variationLabel} · attempt ${attempt}/${options.maxAttempts}`, outcome);
+            printSavedBenchmarkOutcome(`${options.variationLabel} · attempt ${attempt}/${options.maxAttempts}`, outcome);
             if (!bestOutcome || testScore(outcome) > testScore(bestOutcome)) {
-                if (bestSnapshotPath) {
-                    rmSync(bestSnapshotPath, { recursive: true, force: true });
+                if (bestGraphBackupPath) {
+                    rmSync(bestGraphBackupPath, { recursive: true, force: true });
                 }
                 bestOutcome = outcome;
-                bestSnapshotPath = snapshotBestBuildState(options.verifiableContextPath);
+                bestGraphBackupPath = captureBestBuildState(options.contextGraphPath);
                 bestAttempt = attempt;
             }
             if (outcome.result.ok) {
                 console.log();
-                console.log(chalk.green(`  Verifiable context passed on ${options.variationLabel}, attempt ${attempt}/${options.maxAttempts}.`));
-                printStageShellReviewHint(options.verifiableContextPath, options.preserveStageShells, "success");
+                console.log(chalk.green(`  Context Graph passed on ${options.variationLabel}, attempt ${attempt}/${options.maxAttempts}.`));
+                printStageShellReviewHint(options.contextGraphPath, options.preserveStageShells, "success");
                 return {
                     passed: true,
                     attemptsRun,
                     failedStage: null,
                     bestOutcome,
-                    bestSnapshotPath,
+                    bestGraphBackupPath,
                     bestAttempt,
                     fatalError: null,
                 };
@@ -219,7 +245,7 @@ async function runBuildPlanVariation(options) {
             attemptsRun,
             failedStage: null,
             bestOutcome,
-            bestSnapshotPath,
+            bestGraphBackupPath,
             bestAttempt,
             fatalError: null,
         };
@@ -230,7 +256,7 @@ async function runBuildPlanVariation(options) {
             attemptsRun,
             failedStage: null,
             bestOutcome,
-            bestSnapshotPath,
+            bestGraphBackupPath,
             bestAttempt,
             fatalError: error instanceof Error ? error.message : String(error),
         };
@@ -240,11 +266,11 @@ function summarizeBuildPlanVariation(options) {
     const passedChecks = options.result.bestOutcome?.result.passedCases ?? 0;
     const totalChecks = options.result.bestOutcome?.result.totalCases ?? options.defaultTotalChecks;
     const summary = options.result.passed
-        ? `Passed ${passedChecks}/${totalChecks} readiness checks.`
+        ? `Passed ${passedChecks}/${totalChecks} benchmark checks.`
         : options.result.bestOutcome
-            ? `Best result: ${passedChecks}/${totalChecks} readiness checks passed.`
+            ? `Best result: ${passedChecks}/${totalChecks} benchmark checks passed.`
             : options.result.failedStage
-                ? `Build failed at stage ${options.result.failedStage} before any saved readiness result.`
+                ? `Build failed at stage ${options.result.failedStage} before any saved benchmark result.`
                 : "Build Plan variation did not produce a passing result.";
     return {
         variation: options.variation,
@@ -261,8 +287,8 @@ function summarizeBuildPlanVariation(options) {
         summary,
     };
 }
-function printStageShellReviewHint(verifiableContextPath, preserveStageShells, result) {
-    const reviewRoot = stageExecutionShellsRoot(verifiableContextPath);
+function printStageShellReviewHint(contextGraphPath, preserveStageShells, result) {
+    const reviewRoot = stageExecutionShellsRoot(contextGraphPath);
     if (preserveStageShells === "always") {
         console.log(chalk.dim(`  Stage shells are saved under: ${reviewRoot}`));
         return;
@@ -272,18 +298,18 @@ function printStageShellReviewHint(verifiableContextPath, preserveStageShells, r
     }
 }
 function printPostBuildNextStep(options) {
-    console.log(chalk.dim(`  Verifiable context: ${options.verifiableContextPath}`));
+    console.log(chalk.dim(`  Context Graph: ${options.contextGraphPath}`));
     if (options.checks === 0) {
-        console.log(chalk.dim("  Next: run `interf` to add readiness checks, then `interf test`."));
+        console.log(chalk.dim("  Next: run `interf` to add benchmark questions, then `interf benchmark`."));
         return;
     }
     if (options.testedDuringBuild) {
-        console.log(chalk.dim("  Next: inspect the verifiable context agents will use, or run `interf test` if you also want readiness evidence for source files and verifiable context."));
+        console.log(chalk.dim("  Next: inspect the Context Graph agents will use, or run `interf benchmark` if you also want a Source Manifest baseline versus Context Graph benchmark."));
         return;
     }
-    console.log(chalk.dim("  Next: run `interf test` to collect readiness evidence for source files and verifiable context."));
+    console.log(chalk.dim("  Next: run `interf benchmark` to benchmark the Source Manifest baseline and/or the Context Graph."));
 }
-function formatVariationReadinessSummary(summary) {
+function formatVariationBenchmarkSummary(summary) {
     return `${summary.passed_questions}/${summary.total_questions}`;
 }
 function printBuildPlanVariationSummary(summaries) {
@@ -292,101 +318,98 @@ function printBuildPlanVariationSummary(summaries) {
     console.log();
     console.log(chalk.bold("  Build Plan variation summary"));
     console.log();
-    console.log("  | Variation | Kind | Readiness checks | Result |");
+    console.log("  | Variation | Kind | Benchmark checks | Result |");
     console.log("  | --- | --- | --- | --- |");
     for (const summary of summaries) {
-        console.log(`  | ${summary.variation} | ${summary.kind} | \`${formatVariationReadinessSummary(summary)}\` | ${summary.passed ? "pass" : "fail"} |`);
+        console.log(`  | ${summary.variation} | ${summary.kind} | \`${formatVariationBenchmarkSummary(summary)}\` | ${summary.passed ? "pass" : "fail"} |`);
     }
 }
-function printSelectedBuildPlanOwnership(verifiableContextPath, bestVariation) {
+function printSelectedBuildPlanOwnership(contextGraphPath, bestVariation) {
     if (bestVariation <= 1)
         return;
     console.log();
-    console.log(chalk.dim(`  Best Build Plan variation now lives in: ${buildPlanPackagePathForVerifiableContext(verifiableContextPath)}`));
-    console.log(chalk.dim("  The project-level Build Plan selection was not changed automatically."));
-    console.log(chalk.dim("  Rebuilding this existing verifiable context reuses that local Build Plan draft."));
+    console.log(chalk.dim(`  Best Build Plan variation now lives in: ${buildPlanPackagePathForContextGraph(contextGraphPath)}`));
+    console.log(chalk.dim("  The Project-level Build Plan selection was not changed automatically."));
+    console.log(chalk.dim("  Building this existing Context Graph again reuses that local Build Plan draft."));
 }
 export async function runConfiguredBuild(options) {
-    const preserveStageShells = options.preserveStageShells ?? "on-failure";
-    const configuredMaxAttempts = resolvePreparationBuildMaxAttempts(options.verifiableContextConfig ?? { max_attempts: undefined }, options.maxAttemptsOverride);
-    const maxLoops = resolvePreparationBuildMaxLoops(options.verifiableContextConfig ?? { max_loops: undefined }, options.maxLoopsOverride);
+    const preserveStageShells = options.preserveStageShells ?? "always";
+    const configuredMaxAttempts = resolveBuildMaxAttempts(options.maxAttemptsOverride);
+    const maxLoops = resolveBuildMaxLoops(options.maxLoopsOverride);
     const maxAttempts = configuredMaxAttempts ?? (maxLoops != null ? 1 : null);
     const loopEnabled = maxAttempts != null;
-    const checks = options.verifiableContextConfig?.checks ?? [];
-    if (loopEnabled && checks.length === 0) {
-        console.log(chalk.yellow("  Retry and self-improving modes need saved readiness checks. Building once without those loops."));
+    // Read the persisted Interf config once for the entry path. `readInterfConfig`
+    // does fs I/O + JSON parse + zod validation, and nothing here mutates the
+    // config file before the improvement loop, so a single read drives the
+    // project-name fallback (below) and the improvement-loop config fallback
+    // identically. The in-loop read at the improvement step stays a live re-read
+    // because that loop edits the Build Plan/config between iterations.
+    const interfConfig = readInterfConfig(options.contextGraphPath);
+    const projectName = options.contextGraphConfig?.name ?? interfConfig?.name ?? "project";
+    const benchmarkSpec = buildTestSpecFromSourceFolderConfig({
+        projectDataDir: options.sourcePath,
+        targetName: projectName,
+        targetType: "context-graph",
+    });
+    const benchmarkCheckCount = benchmarkSpec?.cases.length ?? 0;
+    if (loopEnabled && benchmarkCheckCount === 0) {
+        console.log(chalk.yellow("  Retry and self-improving modes need saved benchmark checks. Building once without those loops."));
     }
     else if (loopEnabled) {
         if (maxAttempts > 1) {
             console.log(chalk.dim(`  Retry mode: up to ${maxAttempts} build attempts.`));
-            console.log(chalk.dim("  Interf will rerun the same Build Plan variation, check the verifiable context agents can use, and stop early if it passes."));
+            console.log(chalk.dim("  Interf will rerun the same Build Plan variation, check the Context Graph agents can use, and stop early if it passes."));
         }
         else {
             console.log(chalk.dim("  Build mode: 1 attempt per Build Plan variation."));
         }
         if (maxLoops != null) {
             console.log(chalk.dim(`  Build Plan improvement: up to ${maxLoops} Build Plan edits after retries fail.`));
-            console.log(chalk.dim("  Interf will review failed runs, edit the Build Plan, and test new Build Plan variations."));
+            console.log(chalk.dim("  Interf will review failed runs, edit the Build Plan, and benchmark new Build Plan variations."));
         }
     }
-    if (!loopEnabled || checks.length === 0) {
-        const result = await buildVerifiableContextWithReporter(options.executor, options.verifiableContextPath, {
+    if (!loopEnabled || benchmarkCheckCount === 0) {
+        const result = await buildContextGraphWithReporter(options.executor, options.contextGraphPath, {
             preserveStageShells,
             runId: options.runId,
             events: options.events,
             resolveStageExecutor: options.resolveStageExecutor,
+            maxStageValidationAttempts: configuredMaxAttempts ?? undefined,
         });
         if (!result.ok) {
             process.exitCode = 1;
-            printBuildFailure(options.verifiableContextPath, result.failedStage);
-            printStageShellReviewHint(options.verifiableContextPath, preserveStageShells, "failure");
+            printBuildFailure(options.contextGraphPath, result.failedStage);
+            printStageShellReviewHint(options.contextGraphPath, preserveStageShells, "failure");
             return false;
         }
-        printStageShellReviewHint(options.verifiableContextPath, preserveStageShells, "success");
+        printStageShellReviewHint(options.contextGraphPath, preserveStageShells, "success");
         printPostBuildNextStep({
-            verifiableContextPath: options.verifiableContextPath,
-            checks: checks.length,
+            contextGraphPath: options.contextGraphPath,
+            checks: benchmarkCheckCount,
             testedDuringBuild: false,
         });
         return true;
     }
-    let bestOutcome = null;
-    let bestSnapshotPath = null;
-    let bestAttempt = 0;
-    let bestVariation = 0;
+    const best = createVariationBestTracker();
     const previousVariations = [];
     const improvementRunId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+    const pruneBackup = (backupPath) => rmSync(backupPath, { recursive: true, force: true });
     try {
-        const verifiableContextConfig = options.verifiableContextConfig
-            ?? loadVerifiableContextPreparationConfig(options.verifiableContextPath)
+        const contextGraphConfig = options.contextGraphConfig
+            ?? loadContextGraphProjectConfig(options.contextGraphPath)
             ?? {
-                name: readInterfConfig(options.verifiableContextPath)?.name ?? "preparation",
+                name: interfConfig?.name ?? "project",
+                intent: interfConfig?.intent ?? "",
                 path: "./source-folder",
-                checks: [],
             };
-        const adoptVariationBest = (variation, result) => {
-            if (result.bestOutcome && result.bestSnapshotPath && (!bestOutcome || testScore(result.bestOutcome) > testScore(bestOutcome))) {
-                if (bestSnapshotPath) {
-                    rmSync(bestSnapshotPath, { recursive: true, force: true });
-                }
-                bestOutcome = result.bestOutcome;
-                bestSnapshotPath = result.bestSnapshotPath;
-                bestAttempt = result.bestAttempt;
-                bestVariation = variation;
-                result.bestSnapshotPath = null;
-            }
-            if (result.bestSnapshotPath) {
-                rmSync(result.bestSnapshotPath, { recursive: true, force: true });
-                result.bestSnapshotPath = null;
-            }
-        };
+        const adoptVariationBest = (variation, result) => considerVariationBest(best, variation, result, pruneBackup);
         const baseline = await runBuildPlanVariation({
             executor: options.executor,
             testExecutor: options.testExecutor,
             resolveStageExecutor: options.resolveStageExecutor,
-            verifiableContextPath: options.verifiableContextPath,
+            contextGraphPath: options.contextGraphPath,
             sourcePath: options.sourcePath,
-            verifiableContextConfig,
+            contextGraphConfig,
             executionProfile: options.executionProfile,
             preserveStageShells,
             maxAttempts,
@@ -404,13 +427,13 @@ export async function runConfiguredBuild(options) {
             variation: 1,
             kind: "baseline",
             result: baseline,
-            defaultTotalChecks: checks.length,
+            defaultTotalChecks: benchmarkCheckCount,
         }));
         if (baseline.passed) {
             printBuildPlanVariationSummary(previousVariations);
             printPostBuildNextStep({
-                verifiableContextPath: options.verifiableContextPath,
-                checks: checks.length,
+                contextGraphPath: options.contextGraphPath,
+                checks: benchmarkCheckCount,
                 testedDuringBuild: true,
             });
             return true;
@@ -421,9 +444,12 @@ export async function runConfiguredBuild(options) {
                 console.log(chalk.dim(`  Self-improving loop ${loopIndex}/${maxLoops}: reviewing failed runs and editing the Build Plan.`));
                 const improvement = await runBuildPlanImprovementLoop({
                     executor: options.executor,
-                    verifiableContextPath: options.verifiableContextPath,
-                    buildPlanId: resolveRequiredBuildPlanFromConfig(readInterfConfig(options.verifiableContextPath), `.interf/interf.json for ${options.verifiableContextPath}`),
-                    verifiableContextConfig,
+                    contextGraphPath: options.contextGraphPath,
+                    buildPlanId: resolveRequiredBuildPlanFromConfig(readInterfConfig(options.contextGraphPath), `.interf/interf.json for ${options.contextGraphPath}`),
+                    benchmarkChecks: benchmarkSpec?.cases.map((testCase) => ({
+                        id: testCase.id,
+                        question: testCase.question,
+                    })) ?? [],
                     runId: improvementRunId,
                     loopIndex,
                     maxLoops,
@@ -444,9 +470,9 @@ export async function runConfiguredBuild(options) {
                     executor: options.executor,
                     testExecutor: options.testExecutor,
                     resolveStageExecutor: options.resolveStageExecutor,
-                    verifiableContextPath: options.verifiableContextPath,
+                    contextGraphPath: options.contextGraphPath,
                     sourcePath: options.sourcePath,
-                    verifiableContextConfig,
+                    contextGraphConfig,
                     executionProfile: options.executionProfile,
                     preserveStageShells,
                     maxAttempts,
@@ -464,44 +490,44 @@ export async function runConfiguredBuild(options) {
                     variation: loopIndex + 1,
                     kind: "edited",
                     result: variation,
-                    defaultTotalChecks: checks.length,
+                    defaultTotalChecks: benchmarkCheckCount,
                 }));
                 if (variation.passed) {
                     printBuildPlanVariationSummary(previousVariations);
-                    printSelectedBuildPlanOwnership(options.verifiableContextPath, bestVariation);
+                    printSelectedBuildPlanOwnership(options.contextGraphPath, best.variation);
                     printPostBuildNextStep({
-                        verifiableContextPath: options.verifiableContextPath,
-                        checks: checks.length,
+                        contextGraphPath: options.contextGraphPath,
+                        checks: benchmarkCheckCount,
                         testedDuringBuild: true,
                     });
                     return true;
                 }
             }
         }
-        if (bestSnapshotPath && bestVariation > 0) {
-            restoreBestBuildState(bestSnapshotPath, options.verifiableContextPath);
+        if (best.backupPath && best.variation > 0) {
+            restoreBestBuildState(best.backupPath, options.contextGraphPath);
             console.log();
-            console.log(chalk.dim(`  Restored the best-performing verifiable context from variation ${bestVariation}, attempt ${bestAttempt}.`));
+            console.log(chalk.dim(`  Restored the best-performing Context Graph from variation ${best.variation}, attempt ${best.attempt}.`));
         }
         process.exitCode = 1;
         console.log();
         printBuildPlanVariationSummary(previousVariations);
-        printSelectedBuildPlanOwnership(options.verifiableContextPath, bestVariation);
+        printSelectedBuildPlanOwnership(options.contextGraphPath, best.variation);
         if (maxLoops != null) {
-            console.log(chalk.red(`  Verifiable context did not pass after ${maxAttempts} attempt${maxAttempts === 1 ? "" : "s"} per variation and ${maxLoops} Build Plan improvement loop${maxLoops === 1 ? "" : "s"}.`));
+            console.log(chalk.red(`  Context Graph did not pass after ${maxAttempts} attempt${maxAttempts === 1 ? "" : "s"} per variation and ${maxLoops} Build Plan improvement loop${maxLoops === 1 ? "" : "s"}.`));
         }
         else {
-            console.log(chalk.red(`  Verifiable context did not pass within ${maxAttempts} attempt${maxAttempts === 1 ? "" : "s"}.`));
+            console.log(chalk.red(`  Context Graph did not pass within ${maxAttempts} attempt${maxAttempts === 1 ? "" : "s"}.`));
         }
-        if (bestOutcome) {
-            console.log(chalk.dim(`  Best attempt readiness-check pass rate: ${readinessPassRate(bestOutcome)}%.`));
+        if (best.outcome) {
+            console.log(chalk.dim(`  Best attempt benchmark pass rate: ${benchmarkPassRate(best.outcome)}%.`));
         }
-        printStageShellReviewHint(options.verifiableContextPath, preserveStageShells, "failure");
+        printStageShellReviewHint(options.contextGraphPath, preserveStageShells, "failure");
         return false;
     }
     finally {
-        if (bestSnapshotPath) {
-            rmSync(bestSnapshotPath, { recursive: true, force: true });
+        if (best.backupPath) {
+            rmSync(best.backupPath, { recursive: true, force: true });
         }
     }
 }
@@ -523,7 +549,7 @@ export function createNativeLocalServiceRunHandlers(options = {}) {
             if (!resolved.executor) {
                 return ActionProposalPlanSchema.parse({
                     action_type: "clarification",
-                    preparation: request.preparation,
+                    project: request.project,
                     assistant_message: resolved.error ?? "No local agent detected for action planning.",
                 });
             }
@@ -568,9 +594,9 @@ export function createNativeLocalServiceRunHandlers(options = {}) {
                     }
                     return stageExecutor;
                 },
-                verifiableContextPath: context.verifiableContextPath,
+                contextGraphPath: context.contextGraphPath,
                 sourcePath: context.sourcePath,
-                verifiableContextConfig: context.preparationConfig,
+                contextGraphConfig: context.projectConfig,
                 maxAttemptsOverride: request.max_attempts ?? null,
                 maxLoopsOverride: request.max_loops ?? null,
                 preserveStageShells: request.preserve_stage_shells,
@@ -590,47 +616,69 @@ export function createNativeLocalServiceRunHandlers(options = {}) {
             });
             // Verify runs always use the `verifier` role. We resolve here
             // for symmetry with Build runs — verify-run events are not
-            // streamed in 0.15, so the resolution shows up only in the
-            // executor field on the saved test run record.
-            const { executor } = bundle.resolveExecutorForRole("verifier");
-            const result = await runReadinessChecksForExecutor({
+            // streamed, so the resolution shows up only in the executor
+            // field on the saved benchmark run record.
+            const executor = request.agent_name
+                ? (() => {
+                    const agent = registry.agents.find((entry) => entry.name === request.agent_name && entry.available !== false);
+                    if (!agent) {
+                        throw new Error(`Benchmark agent "${request.agent_name}" is not connected.`);
+                    }
+                    const requestedExecutor = bundle.executors.get(agent.name);
+                    if (!requestedExecutor) {
+                        throw new Error(`Benchmark agent "${agent.name}" is not available for automated runs.`);
+                    }
+                    return requestedExecutor;
+                })()
+                : bundle.resolveExecutorForRole("verifier").executor;
+            const executorInfo = buildRuntimeExecutorInfo(executor);
+            const result = await runBenchmarkForExecutor({
                 sourcePath: context.sourcePath,
-                preparationConfig: context.preparationConfig,
-                verifiableContextPath: context.verifiableContextPath,
+                projectConfig: context.projectConfig,
+                contextGraphPath: context.contextGraphPath,
                 executor,
                 target: request.target,
             });
-            const outcome = request.target === "source-files"
-                ? result.sourceFilesOutcome
-                : result.verifiableContextOutcome;
-            if (!outcome) {
-                const targetLabel = request.target === "source-files"
-                    ? "Source files"
-                    : "Verifiable context";
+            const missingTargets = [
+                ...(request.target === "source-files" || request.target === "both"
+                    ? result.sourceFilesOutcome ? [] : ["Source files"]
+                    : []),
+                ...(request.target === "context-graph" || request.target === "both"
+                    ? result.contextGraphOutcome ? [] : ["Context Graph"]
+                    : []),
+            ];
+            if (missingTargets.length > 0) {
                 return {
                     ok: false,
-                    readiness_run: result.readinessRun,
-                    error: `${targetLabel} is not ready for readiness checks.`,
+                    benchmark_run: result.benchmarkRun,
+                    executor: executorInfo,
+                    agent_label: executor.displayName,
+                    error: `${missingTargets.join(" and ")} ${missingTargets.length === 1 ? "is" : "are"} not ready for benchmark evaluation.`,
                 };
             }
             return {
                 ok: true,
-                readiness_run: result.readinessRun,
+                benchmark_run: result.benchmarkRun,
+                executor: executorInfo,
+                agent_label: executor.displayName,
             };
         },
-        async createReadinessCheckDraft(request, context) {
+        async createBenchmarkQuestionDraft(request, context) {
             const executor = resolveHandlerExecutor(options.executor);
             context.emit({
                 type: "log.appended",
                 step_id: "agent-draft",
-                message: `Using ${executor.displayName} to draft readiness checks.`,
+                message: `Using ${executor.displayName} to draft benchmark questions.`,
             });
-            const drafted = await draftReadinessChecks({
-                preparationName: request.preparation,
+            const drafted = await draftBenchmarkQuestions({
+                projectName: request.project,
                 sourceFolderPath: request.source_folder_path,
-                about: request.about,
+                intent: request.intent,
                 executor,
                 targetCount: request.target_count,
+                // Preserve the drafting shell under the Project's durable job storage so
+                // the draft execution (prompt, reasoning, output, verdict) is inspectable.
+                preservedShellRoot: join(projectServiceJobShellsRoot(asProjectDataDir(context.sourcePath)), `benchmark-question-draft-${context.runId}`),
                 onStatus: (line) => context.emit({
                     type: "log.appended",
                     step_id: "agent-draft",
@@ -638,10 +686,12 @@ export function createNativeLocalServiceRunHandlers(options = {}) {
                 }),
             });
             if (!drafted.checks) {
-                throw new Error(drafted.error ?? "Could not draft readiness checks from this Source Folder.");
+                throw new Error(drafted.error ?? "Could not draft benchmark questions from this Source Folder.");
             }
             return {
                 checks: drafted.checks,
+                ...(drafted.shellPath ? { shell_path: drafted.shellPath } : {}),
+                ...(drafted.reasoningPath ? { reasoning_path: drafted.reasoningPath } : {}),
             };
         },
         async createBuildPlanAuthoringRun(request, context) {
@@ -652,16 +702,17 @@ export function createNativeLocalServiceRunHandlers(options = {}) {
                 message: `Using ${executor.displayName} for Build Plan authoring.`,
             });
             const result = await runBuildPlanAuthoringDraft({
-                prepDataDir: context.sourcePath,
+                projectDataDir: context.sourcePath,
                 sourceFolderPath: request.source_folder_path,
                 baseBuildPlanId: request.reference_build_plan_id ?? request.base_build_plan_id,
                 buildPlanId: request.build_plan_id,
                 label: request.label,
                 hint: request.hint,
-                taskPrompt: request.task_prompt,
+                intent: request.intent,
                 checks: request.checks,
+                userPrepInstructions: request.user_prep_instructions,
                 requestedArtifacts: request.requested_artifacts,
-                sourceProfile: request.source_profile ?? null,
+                sourceContext: request.source_context ?? null,
                 artifactRequirements: request.artifact_requirements,
                 executor,
                 onStatus: (line) => context.emit({