@interf/compiler 0.33.0 → 0.50.0

package/dist/packages/runtime/build/artifact-status.d.ts

@@ -23,7 +23,7 @@ import type { StageRun } from "../execution/lib/schema.js";
  * the run record carries the real causal signal.
  */
 export declare function computeArtifactStatuses(options: {
-    buildPlan: Pick<BuildPlanDefinition<string>, "stages" | "contextInterface" | "schema">;
+    buildPlan: Pick<BuildPlanDefinition<string>, "stages" | "contextInterface">;
     contextGraphPath: string;
     stageRuns: StageRun[];
     /**

package/dist/packages/runtime/build/artifact-status.js

@@ -39,7 +39,7 @@ export function computeArtifactStatuses(options) {
     }));
 }
 function pickContextInterface(buildPlan) {
-    return buildPlan.contextInterface ?? buildPlan.schema;
+    return buildPlan.contextInterface;
 }
 function buildStageWriteIndex(stages) {
     const index = new Map();

package/dist/packages/runtime/build/build-evidence.d.ts

@@ -1,4 +1,4 @@
-import { type BuildEvidenceResource, type Readiness } from "../../contracts/lib/schema.js";
+import { type BuildEvidenceResource, type MetricCount, type Readiness } from "../../contracts/lib/schema.js";
 import type { BuildRun } from "../execution/lib/schema.js";
 import type { StageEvidenceReconciliation } from "./lib/schema.js";
 interface BuildBuildEvidenceInput {
@@ -9,6 +9,7 @@ interface BuildBuildEvidenceInput {
     expectedStageCount?: number;
     expectedOutputCount?: number;
     stageEvidence?: readonly StageEvidenceReconciliation[];
+    primaryMetrics?: readonly MetricCount[];
     generatedAt?: string;
 }
 export declare function buildBuildEvidence(input: BuildBuildEvidenceInput): BuildEvidenceResource;

package/dist/packages/runtime/build/build-evidence.js

@@ -25,6 +25,10 @@ function sourceFilesProcessed(stages) {
     }
     return observed;
 }
+function primaryMetricValue(metrics, key) {
+    const value = metrics?.find((entry) => entry.key === key)?.value;
+    return typeof value === "number" && Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : null;
+}
 function requiredArtifactCheckResults(artifacts) {
     return artifacts
         .flatMap((artifact) => artifact.check_results ?? [])
@@ -61,8 +65,10 @@ export function buildBuildEvidence(input) {
     const acceptedFilesProcessed = acceptedEvidenceCounts
         .filter((count) => count.key === "files_processed")
         .reduce((max, count) => Math.max(max, count.value), 0);
+    const graphFilesProcessed = primaryMetricValue(input.primaryMetrics, "files_processed");
     const filesObserved = buildRun
-        ? Math.min(hasAcceptedStageEvidence ? acceptedFilesProcessed : sourceFilesProcessed(stages), filesTotal)
+        ? Math.min(graphFilesProcessed ??
+            (hasAcceptedStageEvidence ? acceptedFilesProcessed : sourceFilesProcessed(stages)), filesTotal)
         : 0;
     const filesState = issueState(filesObserved, filesTotal, { reviewWhenEmpty: true });
     rows.push({
@@ -74,7 +80,7 @@ export function buildBuildEvidence(input) {
             label: buildRun ? "Build stage records" : "Source inventory",
             ...(buildRun ? { run_id: buildRun.run_id, ref: `run:${buildRun.run_id}` } : { ref: "source-files" }),
         },
-        ...rowStateIssue(filesState, `${filesTotal - filesObserved} Source file${filesTotal - filesObserved === 1 ? "" : "s"} lack accepted Build evidence.`),
+        ...rowStateIssue(filesState, `${filesTotal - filesObserved} Source file${filesTotal - filesObserved === 1 ? "" : "s"} lack accepted coverage records.`),
     });
     const stageTotal = input.expectedStageCount ?? stages[0]?.stage_total ?? stages.length;
     const stagesSucceeded = stages.filter((stage) => stage.status === "succeeded").length;
@@ -141,16 +147,16 @@ export function buildBuildEvidence(input) {
     }
     const failed = buildRun?.status === "failed";
     const hasBlockingRows = rowsHaveBlockingIssue(rows);
-    // Build evidence explains the runtime readiness verdict; it does not
+    // Supplemental diagnostics explain the runtime readiness verdict; they do not
     // create a second readiness source of truth.
     const ready = Boolean(input.readiness?.ready) && !failed;
     const summary = failed
         ? "Latest Build failed before the Context Graph was ready."
         : ready
             ? hasBlockingRows
-                ? "Ready by runtime readiness; review Build evidence rows for follow-up."
+                ? "Ready by runtime readiness; review supplemental diagnostic rows for follow-up."
                 : "Ready for agent task."
-            : "Context Graph is not ready; review missing Build evidence.";
+            : "Context Graph is not ready; review missing coverage diagnostics.";
     return BuildEvidenceResourceSchema.parse({
         kind: "interf-build-evidence",
         version: 1,

package/dist/packages/runtime/build/build-pipeline.js

@@ -3,11 +3,15 @@ import { validateBuildPlanPackage } from "../../build-plans/package/local-build-
 import { reportValidationFailure, } from "../../build-plans/package/build-plan-helpers.js";
 import { validateContextGraph, } from "./validate.js";
 import { pruneStageExecutionShells, } from "../agents/lib/shells.js";
+import { reconcilePrunedStageExecutionSessions, } from "./stage-session.js";
 import { buildExecutionStages, resolveBuildContext, } from "./build-target.js";
 import { runBuildStage } from "./build-stage-runner.js";
 import { buildPlanPackagePathForContextGraph } from "./context-graph-paths.js";
 import { runSourceInventory } from "./source-inventory.js";
 import { stageReuseDecision } from "./stage-reuse.js";
+import { loadStageManifest, writeGraphManifest, } from "./stage-manifest.js";
+import { writeContextGraphInspectMap } from "./inspect-map.js";
+import { ensureSummaryCoverageIndex } from "./summary-coverage-index.js";
 import { createRunEventId, createRunEventTimestamp, } from "../execution/events.js";
 function pickStageExecutor(fallback, stage, resolve) {
     if (!resolve)
@@ -53,6 +57,24 @@ async function emitReusedStagePassed(options) {
 function reusedStageResult(summary = "reused (verified, unchanged)") {
     return { ok: true, code: 0, summary };
 }
+/**
+ * Deterministic connectivity floor, applied after the stage agents have produced
+ * the graph but BEFORE readiness validation. Writes a managed coverage block into
+ * `home.md` (the entrypoint spine) wikilinking every summary the build produced,
+ * so every summary note has a guaranteed inbound edge no matter how the stage
+ * agent behaved. Best-effort: assembly is already complete, so a finalization
+ * error must never fail the build (the `graph_notes_connected` check still runs
+ * and will report any real gap).
+ */
+function finalizeGraphConnectivity(contextGraphPath) {
+    try {
+        ensureSummaryCoverageIndex(contextGraphPath);
+    }
+    catch {
+        // Never fail a built graph on the navigation-index write. The connectivity
+        // check runs next and is the source of truth on readiness.
+    }
+}
 export async function runBuildSummarize(options) {
     const context = resolveBuildContext(options.contextGraphPath);
     const stageDefinition = options.stageDefinition
@@ -69,6 +91,7 @@ export async function runBuildSummarize(options) {
         executor: pickStageExecutor(options.executor, stageDefinition, options.resolveStageExecutor),
         contextGraphPath: options.contextGraphPath,
         project: context.contextGraphName,
+        projectIntent: context.projectIntent,
         sourceLocator: context.sourcePath,
         buildPlanId: context.buildPlanId,
         stageIds: [stageDefinition.id],
@@ -90,7 +113,7 @@ export async function runBuildSummarize(options) {
         contextGraphPath: options.contextGraphPath,
         stageDefinition,
     });
-    if (reuse.reuse) {
+    if (reuse.reuse && loadStageManifest(options.contextGraphPath, stageDefinition.id)) {
         await emitReusedStagePassed({
             events: options.events,
             runId: options.runId,
@@ -128,7 +151,7 @@ export async function runBuildSummarize(options) {
     };
 }
 export async function runBuildStages(options) {
-    const preserveMode = options.preserveStageShells ?? "on-failure";
+    const preserveMode = options.preserveStageShells ?? "always";
     if (preserveMode !== "always") {
         pruneStageExecutionShells(options.contextGraphPath);
     }
@@ -141,6 +164,7 @@ export async function runBuildStages(options) {
             executor: sourceInventoryExecutor,
             contextGraphPath: options.contextGraphPath,
             project: context.contextGraphName,
+            projectIntent: context.projectIntent,
             sourceLocator: context.sourcePath,
             buildPlanId: context.buildPlanId,
             stageIds: stages.map((stage) => stage.id),
@@ -158,7 +182,7 @@ export async function runBuildStages(options) {
                     contextGraphPath: options.contextGraphPath,
                     stageDefinition,
                 });
-                if (reuse.reuse) {
+                if (reuse.reuse && loadStageManifest(options.contextGraphPath, stageDefinition.id)) {
                     await emitReusedStagePassed({
                         events: options.events,
                         runId: options.runId,
@@ -188,16 +212,36 @@ export async function runBuildStages(options) {
             if (!result.ok)
                 return result;
         }
+        // Connectivity floor: link every summary into a deterministic navigation
+        // index before the GraphManifest rolls up coverage and connectivity metrics.
+        finalizeGraphConnectivity(options.contextGraphPath);
+        writeGraphManifest({
+            contextGraphPath: options.contextGraphPath,
+            projectId: context.contextGraphName,
+            buildPlanId: context.buildPlanId,
+            intent: context.projectIntent,
+            runId: options.runId ?? null,
+        });
+        // Refresh the developer/agent map of the built folder from already-recorded
+        // state. Best-effort: it never fails the build.
+        writeContextGraphInspectMap(options.contextGraphPath);
         return lastResult;
     }
     finally {
         if (preserveMode !== "always" && lastResult.ok) {
             pruneStageExecutionShells(options.contextGraphPath);
+            // Pruning deleted the shells the sessions point at; downgrade those
+            // sessions so none dangles with replay_ready:true (F2).
+            reconcilePrunedStageExecutionSessions({ contextGraphPath: options.contextGraphPath });
+            // The in-try map render above reflected pre-reconcile sessions (shells the
+            // prune was about to delete). Re-render from the reconciled state so the
+            // map points only at shells still on disk (F1). Best-effort, never fails.
+            writeContextGraphInspectMap(options.contextGraphPath);
         }
     }
 }
 export async function buildContextGraph(options) {
-    const preserveMode = options.preserveStageShells ?? "on-failure";
+    const preserveMode = options.preserveStageShells ?? "always";
     if (preserveMode !== "always") {
         pruneStageExecutionShells(options.contextGraphPath);
     }
@@ -232,6 +276,7 @@ export async function buildContextGraph(options) {
             executor: sourceInventoryExecutor,
             contextGraphPath: options.contextGraphPath,
             project: context.contextGraphName,
+            projectIntent: context.projectIntent,
             sourceLocator: context.sourcePath,
             buildPlanId: context.buildPlanId,
             stageIds: stages.map((stage) => stage.id),
@@ -253,7 +298,7 @@ export async function buildContextGraph(options) {
                     contextGraphPath: options.contextGraphPath,
                     stageDefinition,
                 });
-                if (reuse.reuse) {
+                if (reuse.reuse && loadStageManifest(options.contextGraphPath, stageDefinition.id)) {
                     await emitReusedStagePassed({
                         events: options.events,
                         runId: options.runId,
@@ -286,6 +331,9 @@ export async function buildContextGraph(options) {
                 return result;
             }
         }
+        // Connectivity floor: ensure every produced summary is reachable through a
+        // deterministic navigation index BEFORE readiness is validated.
+        finalizeGraphConnectivity(options.contextGraphPath);
         const buildPlanValidationResult = validateContextGraph(options.contextGraphPath);
         result.ok = buildPlanValidationResult.ok;
         result.failedStage = buildPlanValidationResult.ok ? null : buildPlanValidationResult.stage;
@@ -294,11 +342,47 @@ export async function buildContextGraph(options) {
             code: buildPlanValidationResult.ok ? 0 : 1,
             summary: buildPlanValidationResult.summary,
         };
+        if (buildPlanValidationResult.ok) {
+            try {
+                const graphManifest = writeGraphManifest({
+                    contextGraphPath: options.contextGraphPath,
+                    projectId: context.contextGraphName,
+                    buildPlanId: context.buildPlanId,
+                    intent: context.projectIntent,
+                    runId: options.runId ?? null,
+                });
+                result.stageResults["graph-manifest"] = {
+                    ok: true,
+                    code: 0,
+                    summary: `GraphManifest recorded ${graphManifest.resources.length} resource${graphManifest.resources.length === 1 ? "" : "s"} and ${graphManifest.graph_outputs.edges} graph edge${graphManifest.graph_outputs.edges === 1 ? "" : "s"}.`,
+                };
+                // Refresh the developer/agent map (.interf/INSPECT.md) of the built
+                // folder from already-recorded state. Best-effort: it never fails the
+                // build, so a render error does not flip a ready graph to failed.
+                writeContextGraphInspectMap(options.contextGraphPath);
+            }
+            catch (error) {
+                result.ok = false;
+                result.failedStage = "graph-manifest";
+                result.stageResults["graph-manifest"] = {
+                    ok: false,
+                    code: 1,
+                    summary: `Could not write GraphManifest: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+        }
         return result;
     }
     finally {
         if (preserveMode !== "always" && result.ok) {
             pruneStageExecutionShells(options.contextGraphPath);
+            // Pruning deleted the shells the sessions point at; downgrade those
+            // sessions so none dangles with replay_ready:true (F2).
+            reconcilePrunedStageExecutionSessions({ contextGraphPath: options.contextGraphPath });
+            // The in-try map render above reflected pre-reconcile sessions (shells the
+            // prune was about to delete). Re-render from the reconciled state so the
+            // map points only at shells still on disk (F1). Best-effort, never fails.
+            writeContextGraphInspectMap(options.contextGraphPath);
         }
     }
 }

package/dist/packages/runtime/build/build-stage-plan.js

@@ -4,7 +4,7 @@ import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
 import { contextGraphArtifactPath, contextGraphArtifactPathsForArtifactIds, findBuildPlanContextArtifact, readBuildPlanContextFile, } from "./context-graph-schema.js";
 import { buildLocalSkillContractExtension, buildStageInstructions, buildPlanStageDirectory, } from "../../build-plans/package/build-plan-helpers.js";
 import { loadContextGraphSourceManifest } from "./source-manifest.js";
-import { getActiveBuildPlanStagePolicyNotes, } from "../../build-plans/package/build-plan-definitions.js";
+import { getActiveBuildPlan, getActiveBuildPlanStagePolicyNotes, } from "../../build-plans/package/build-plan-definitions.js";
 import { buildPlanPackagePathForContextGraph } from "./context-graph-paths.js";
 import { readInterfConfig } from "../../projects/interf-detect.js";
 import { resolveBuildContext, } from "./build-target.js";
@@ -72,6 +72,7 @@ export function buildStageContract(contextGraphPath, stageDefinition, instructio
     const stageArtifacts = resolveStageContractArtifacts(contextGraphPath, stageDefinition);
     return buildRuntimeStageContract({
         contextGraphName: config?.name ?? "context-graph",
+        project: resolveBuildContext(contextGraphPath).project,
         stageId: stageDefinition.id,
         stageLabel: stageDefinition.label,
         counts: buildStageCounts(contextGraphPath, stageDefinition),
@@ -82,6 +83,7 @@ export function buildStageContract(contextGraphPath, stageDefinition, instructio
         stageReadArtifacts: stageArtifacts.reads,
         stageWriteArtifacts: stageArtifacts.writes,
         stageWriteContracts: stageArtifacts.writeContracts,
+        contextChecks: getActiveBuildPlan(contextGraphPath).brief?.checks ?? [],
         buildPlanNotes: getActiveBuildPlanStagePolicyNotes(contextGraphPath, stageDefinition.id),
         localSkillDocs: instructions.local_docs,
         instructions,

package/dist/packages/runtime/build/build-stage-runner.js

@@ -1,11 +1,15 @@
 import { writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, relative } from "node:path";
 import { createStageExecutionShell, freezeStageExecutionShell, syncStageExecutionShellWrites, validateStageExecutionShellInputs, } from "../agents/lib/shells.js";
 import { reconcileBuildStageRun } from "./runtime-reconcile.js";
 import { refreshContextGraphArtifacts } from "./state.js";
 import { validateBuildStage } from "./validate.js";
 import { reconcileStageEvidence, stageEvidenceAcceptanceFailure, supportsStageEvidenceHarness, } from "./stage-evidence.js";
+import { persistStageReviewedInputsFromShell, writeStageExpectedInputs, writeStageManifestFromOutputs, } from "./stage-manifest.js";
+import { createNativeEntrypointExecutor, } from "./native-entrypoint.js";
 import { executeValidatedStage, } from "../../build-plans/package/build-plan-stage-runner.js";
+import { loadExecutionStageLedger, } from "./runtime.js";
+import { markStageExecutionSessionsShellPreserved, recordStageExecutionSessionValidationAttempt, } from "./stage-session.js";
 import { formatActiveBuildPlanStageLabel, } from "../../build-plans/package/build-plan-definitions.js";
 import { reportBlankLine, reportLine, } from "../../build-plans/package/build-plan-helpers.js";
 import { buildBuildStageExecutionPlan, } from "./build-stage-plan.js";
@@ -20,50 +24,156 @@ function boundedStageValidationAttempts(value) {
         return 2;
     return Math.max(1, Math.min(5, Math.trunc(value)));
 }
+function stageOutputValidationForActiveRun(validation, stageId) {
+    if (validation.ok)
+        return validation;
+    const terminalStateErrors = new Set([
+        `Stage "${stageId}" has no finished_at evidence in runtime state.`,
+        `Stage "${stageId}" is not marked succeeded in runtime state.`,
+    ]);
+    const activeOutputErrors = validation.errors.filter((error) => !terminalStateErrors.has(error));
+    if (activeOutputErrors.length > 0) {
+        return {
+            ...validation,
+            errors: activeOutputErrors,
+            summary: `Stage "${stageId}" failed — ${activeOutputErrors[0]}`,
+        };
+    }
+    return {
+        ...validation,
+        ok: true,
+        errors: [],
+        summary: `Stage "${stageId}" output checks passed.`,
+    };
+}
 function stageValidationRetryStatusLines(options) {
     if (!options.lastFailureSummary || options.attempt <= 1)
         return [];
     return [
         `Previous service validation for this stage failed on attempt ${options.attempt - 1}/${options.maxValidationAttempts}: ${options.lastFailureSummary}`,
-        "Inspect the existing outputs in this same shell, fix the exact validation failure, then rerun `node runtime/check-stage.mjs` until it prints `VALID:`.",
+        "This is a fresh retry shell. Read `runtime/retry-feedback.md`, use previous shells as read-only logs, fix the exact validation failure, then rerun `node runtime/check-stage.mjs` until it prints `VALID:`.",
     ];
 }
+function contextGraphRelativePath(contextGraphPath, path) {
+    return relative(contextGraphPath, path).replaceAll("\\", "/");
+}
+function writeStageRetryFeedback(options) {
+    if (options.attempts.length === 0)
+        return;
+    writeFileSync(join(options.shellRoot, "runtime", "previous-attempts.json"), `${JSON.stringify({
+        kind: "interf-stage-previous-attempts",
+        version: 1,
+        stage_id: options.stageId,
+        attempts: options.attempts,
+    }, null, 2)}\n`);
+    writeFileSync(join(options.shellRoot, "runtime", "retry-feedback.md"), [
+        "# Retry Feedback",
+        "",
+        "This shell is a fresh retry for the current stage.",
+        "Previous attempt shells are preserved as read-only context. Do not mutate them.",
+        "Use their prompts, logs, outputs, and validation failures to repair this attempt.",
+        "",
+        "## Previous Attempts",
+        "",
+        ...options.attempts.flatMap((attempt) => [
+            `### Attempt ${attempt.attempt}`,
+            "",
+            `- stage_run_id: ${attempt.stage_run_id ?? "unknown"}`,
+            `- shell: ${attempt.context_graph_relative_shell_path}`,
+            `- status: ${attempt.status}`,
+            `- validation: ${attempt.summary}`,
+            "",
+        ]),
+        "## Required Action",
+        "",
+        "Write the declared outputs in this shell, record `runtime/reviewed-inputs.json`, and run `node runtime/check-stage.mjs` until it reports `VALID:`.",
+        "",
+    ].join("\n"));
+}
 export async function runBuildStage(options) {
     const stageDefinition = options.stageDefinition;
     const plan = buildBuildStageExecutionPlan(options.contextGraphPath, stageDefinition);
+    writeStageExpectedInputs({
+        contextGraphPath: options.contextGraphPath,
+        stage: stageDefinition,
+    });
     if (options.reportStep !== false) {
         reportBlankLine(options.reporter);
         reportLine(options.reporter, `${formatActiveBuildPlanStageLabel(options.contextGraphPath, stageDefinition.id)} (${stageDefinition.description.toLowerCase()})`);
     }
-    const shell = createStageExecutionShell(options.contextGraphPath, plan.context.contextGraphName, plan.context.buildPlanId, stageDefinition, plan.contract.artifacts.writes);
+    const executor = stageDefinition.contractType === "build-entrypoint"
+        ? createNativeEntrypointExecutor()
+        : options.executor;
     const stageEvidenceHarness = supportsStageEvidenceHarness(stageDefinition);
     const maxValidationAttempts = boundedStageValidationAttempts(options.maxValidationAttempts);
-    const validateStageOutputsAndEvidence = () => {
+    const validateStageOutputsAndEvidence = (shellRoot) => {
         const shellInputValidation = validateStageExecutionShellInputs({
             contextGraphPath: options.contextGraphPath,
-            shellRoot: shell.rootPath,
+            shellRoot,
             stage: stageDefinition,
         });
         if (!shellInputValidation.ok)
             return shellInputValidation;
-        const outputValidation = validateBuildStage(options.contextGraphPath, stageDefinition.id);
-        if (!outputValidation.ok || !stageEvidenceHarness)
+        const outputValidation = stageOutputValidationForActiveRun(validateBuildStage(options.contextGraphPath, stageDefinition.id), stageDefinition.id);
+        if (!outputValidation.ok)
             return outputValidation;
-        const reconciliation = reconcileStageEvidence({
+        if (stageEvidenceHarness) {
+            const reconciliation = reconcileStageEvidence({
+                contextGraphPath: options.contextGraphPath,
+                shellRoot,
+                stage: stageDefinition,
+            });
+            const evidenceFailure = stageEvidenceAcceptanceFailure(reconciliation);
+            if (evidenceFailure) {
+                return { ok: false, summary: evidenceFailure };
+            }
+        }
+        const reviewedInputs = persistStageReviewedInputsFromShell({
             contextGraphPath: options.contextGraphPath,
-            shellRoot: shell.rootPath,
-            stage: stageDefinition,
+            shellRoot,
+            stageId: stageDefinition.id,
         });
-        const evidenceFailure = stageEvidenceAcceptanceFailure(reconciliation);
-        if (evidenceFailure) {
-            return { ok: false, summary: evidenceFailure };
+        if (!reviewedInputs.ok) {
+            return {
+                ok: false,
+                summary: `${outputValidation.summary} ${reviewedInputs.summary}`,
+            };
+        }
+        try {
+            const manifest = writeStageManifestFromOutputs({
+                contextGraphPath: options.contextGraphPath,
+                buildPlanId: plan.context.buildPlanId,
+                projectId: plan.context.contextGraphName,
+                runId: options.runId ?? null,
+                stage: stageDefinition,
+            });
+            if (!manifest) {
+                return { ok: false, summary: `Could not write StageManifest for ${stageDefinition.id}.` };
+            }
+            return {
+                ...outputValidation,
+                summary: `${outputValidation.summary} ${reviewedInputs.summary} StageManifest recorded ${manifest.produced.length} produced resource${manifest.produced.length === 1 ? "" : "s"}.`,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                summary: `Could not write StageManifest for ${stageDefinition.id}: ${error instanceof Error ? error.message : String(error)}`,
+            };
         }
-        return outputValidation;
     };
     let lastResult = { ok: false, code: 1 };
     let lastFailureSummary = null;
-    try {
-        for (let attempt = 1; attempt <= maxValidationAttempts; attempt += 1) {
+    const previousAttempts = [];
+    for (let attempt = 1; attempt <= maxValidationAttempts; attempt += 1) {
+        const shell = createStageExecutionShell(options.contextGraphPath, plan.context.contextGraphName, plan.context.buildPlanId, stageDefinition, plan.contract.artifacts.writes);
+        writeStageRetryFeedback({
+            contextGraphPath: options.contextGraphPath,
+            shellRoot: shell.rootPath,
+            stageId: stageDefinition.id,
+            attempts: previousAttempts,
+        });
+        try {
             if (options.runId && options.events) {
                 await emitRunEvent(options.events, {
                     type: "stage.started",
@@ -76,12 +186,13 @@ export async function runBuildStage(options) {
                 });
             }
             const result = await executeValidatedStage({
-                executor: options.executor,
+                executor,
                 contextGraphPath: options.contextGraphPath,
                 executionPath: shell.rootPath,
                 targetName: plan.context.contextGraphName,
                 buildPlan: plan.context.buildPlanId,
                 buildPlanSourcePath: options.contextGraphPath,
+                buildRunId: options.runId ?? null,
                 stageDefinition,
                 instructions: plan.instructions,
                 summary: `Executing ${stageDefinition.label.toLowerCase()}.`,
@@ -94,13 +205,15 @@ export async function runBuildStage(options) {
                             "Write `runtime/stage-evidence.json` with source/output refs before DONE; status text alone is not accepted evidence.",
                         ]
                         : []),
+                    "Read `runtime/expected-inputs.json` before writing outputs.",
+                    "Write `runtime/reviewed-inputs.json` with one decision per required expected input before DONE.",
                     ...stageValidationRetryStatusLines({ attempt, maxValidationAttempts, lastFailureSummary }),
                     "Emit STATUS: reading declared inputs after you confirm the shell contract and local docs.",
-                    "Emit STATUS: writing declared outputs after the stage starts updating the built Artifacts.",
-                    `Emit DONE: ${stageDefinition.id} complete when the declared outputs and evidence are on disk.`,
+                    "Emit STATUS: writing declared outputs after the stage starts updating the requested outputs.",
+                    `Emit DONE: ${stageDefinition.id} complete when the declared outputs, coverage review, and evidence are on disk.`,
                 ],
                 reporter: options.reporter,
-                completionCheck: () => validateStageOutputsAndEvidence().ok,
+                completionCheck: () => validateStageOutputsAndEvidence(shell.rootPath).ok,
                 onStatus: options.runId && options.events
                     ? (line) => {
                         void options.events?.emit({
@@ -117,9 +230,21 @@ export async function runBuildStage(options) {
                 syncWrites: () => syncStageExecutionShellWrites(options.contextGraphPath, shell.rootPath, stageDefinition, plan.contract.artifacts.writes),
                 reconcile: () => reconcileBuildStageRun(options.contextGraphPath, stageDefinition),
                 refreshArtifacts: () => refreshContextGraphArtifacts(options.contextGraphPath, { ensureViewSpec: true }),
-                validate: validateStageOutputsAndEvidence,
+                validate: () => validateStageOutputsAndEvidence(shell.rootPath),
             });
             lastResult = result;
+            const stageRun = loadExecutionStageLedger(options.contextGraphPath);
+            const stageRunId = stageRun?.stage === stageDefinition.id ? stageRun.run_id : null;
+            if (stageRun?.stage === stageDefinition.id) {
+                recordStageExecutionSessionValidationAttempt({
+                    contextGraphPath: options.contextGraphPath,
+                    stageId: stageDefinition.id,
+                    stageRunId: stageRun.run_id,
+                    attempt,
+                    status: result.ok ? "succeeded" : "failed",
+                    summary: result.summary ?? `${stageDefinition.label} ${result.ok ? "passed" : "failed"}.`,
+                });
+            }
             if (result.ok) {
                 if (options.runId && options.events) {
                     await emitRunEvent(options.events, {
@@ -135,6 +260,14 @@ export async function runBuildStage(options) {
             }
             lastFailureSummary = result.summary ?? `${stageDefinition.label} failed with code ${result.code}.`;
             writeFileSync(join(shell.rootPath, "runtime", "last-validation-failure.txt"), `${lastFailureSummary}\n`);
+            previousAttempts.push({
+                attempt,
+                stage_run_id: stageRunId,
+                shell_path: shell.rootPath,
+                context_graph_relative_shell_path: contextGraphRelativePath(options.contextGraphPath, shell.rootPath),
+                status: "failed",
+                summary: lastFailureSummary,
+            });
             if (attempt < maxValidationAttempts && options.runId && options.events) {
                 await emitRunEvent(options.events, {
                     type: "log.appended",
@@ -147,19 +280,23 @@ export async function runBuildStage(options) {
                 });
             }
         }
-        if (options.runId && options.events) {
-            await emitRunEvent(options.events, {
-                type: "stage.failed",
-                event_id: createRunEventId("event"),
-                run_id: options.runId,
-                timestamp: createRunEventTimestamp(),
-                stage_id: stageDefinition.id,
-                error: lastResult.summary ?? `${stageDefinition.label} failed.`,
+        finally {
+            freezeStageExecutionShell(shell.rootPath);
+            markStageExecutionSessionsShellPreserved({
+                contextGraphPath: options.contextGraphPath,
+                shellRoot: shell.rootPath,
             });
         }
-        return lastResult;
     }
-    finally {
-        freezeStageExecutionShell(shell.rootPath);
+    if (options.runId && options.events) {
+        await emitRunEvent(options.events, {
+            type: "stage.failed",
+            event_id: createRunEventId("event"),
+            run_id: options.runId,
+            timestamp: createRunEventTimestamp(),
+            stage_id: stageDefinition.id,
+            error: lastResult.summary ?? `${stageDefinition.label} failed.`,
+        });
     }
+    return lastResult;
 }

package/dist/packages/runtime/build/build-target.d.ts

@@ -1,9 +1,12 @@
 import { type BuildPlanStageDefinition } from "../../build-plans/package/build-plan-definitions.js";
 import { type ResolvedBuildPlanId } from "../../build-plans/package/build-plan-definitions.js";
+import type { RuntimeProjectContext } from "./lib/schema.js";
 export interface BuildStageExecutionDefinition extends BuildPlanStageDefinition {
 }
 export declare function resolveBuildContext(contextGraphPath: string): {
     contextGraphName: string;
+    project: RuntimeProjectContext;
+    projectIntent: string | null;
     sourcePath: string;
     projectDataDir: string;
     buildPlanId: ResolvedBuildPlanId;

package/dist/packages/runtime/build/build-target.js

@@ -1,10 +1,34 @@
 import { getActiveBuildPlan, resolveRequiredBuildPlanFromConfig, } from "../../build-plans/package/build-plan-definitions.js";
 import { readInterfConfig, resolveSourceFolderPath, resolveSourceControlPath, } from "../../projects/interf-detect.js";
+function normalizedIntent(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function readPersistedProjectIntent(contextGraphPath, config) {
+    const parsedIntent = normalizedIntent(config?.intent);
+    if (parsedIntent)
+        return parsedIntent;
+    try {
+        return normalizedIntent(getActiveBuildPlan(contextGraphPath).brief?.intent);
+    }
+    catch {
+        return null;
+    }
+}
 export function resolveBuildContext(contextGraphPath) {
     const config = readInterfConfig(contextGraphPath);
     const buildPlanId = resolveRequiredBuildPlanFromConfig(config, `.interf/interf.json for ${contextGraphPath}`);
+    const contextGraphName = config?.name ?? "context-graph";
+    const projectIntent = readPersistedProjectIntent(contextGraphPath, config);
     return {
-        contextGraphName: config?.name ?? "context-graph",
+        contextGraphName,
+        project: {
+            id: contextGraphName,
+            intent: projectIntent,
+        },
+        projectIntent,
         sourcePath: resolveSourceFolderPath(contextGraphPath, config),
         projectDataDir: resolveSourceControlPath(contextGraphPath),
         buildPlanId,