@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/runtime/agents/lib/shells.d.ts

@@ -0,0 +1,92 @@
+import type { BuildPlanImprovementContext } from "../../build/lib/schema.js";
+import type { BuildPlanAuthoringArtifactRequirement, BuildPlanContextCheckDraft, RequestedArtifact, SourceContext } from "../../../build-plans/authoring/brief.js";
+import { renderClaudeBootstrap, renderContextGraphQuerySkill, type NativeStageDefinition } from "./shell-templates.js";
+import { syncStageExecutionShellWrites } from "./shell-projection.js";
+export type { NativeStageDefinition };
+export { syncStageExecutionShellWrites };
+export { renderClaudeBootstrap, renderContextGraphQuerySkill };
+export declare function validateStageExecutionShellInputs(options: {
+    contextGraphPath: string;
+    shellRoot: string;
+    stage: NativeStageDefinition;
+}): {
+    ok: boolean;
+    summary: string;
+};
+export declare function writeNativeAgentSurface(rootPath: string, agentsContent: string, skillName: string, skillContent: string): boolean;
+/**
+ * One data-driven shell constructor shared by every agent job (stage execution,
+ * Build Plan authoring, Build Plan improvement). The shared skeleton lives here
+ * exactly once: create the shell root, create the requested subdirectories, and
+ * write the native agent surface (AGENTS.md / CLAUDE.md / SKILL.md) the agent
+ * boots from. Job-specific projection (runtime inputs, source locators, build
+ * plan trees, artifact mounts) stays in each caller — `createAgentShell` only
+ * owns the skeleton, so a reader traces shell setup through one function instead
+ * of three near-identical ones.
+ *
+ * `rootPath` is resolved by the caller (the three job kinds keep their distinct
+ * storage roots: stage shells under the Context Graph, improvement loops under
+ * the loop root, authoring shells under the Project's service job storage).
+ */
+export declare function createAgentShell(options: {
+    rootPath: string;
+    subdirs: readonly string[];
+    nativeSurface: {
+        agentsContent: string;
+        skillName: string;
+        skillContent: string;
+    };
+}): {
+    rootPath: string;
+};
+export declare function pruneStageExecutionShells(contextGraphPath: string): void;
+export declare function projectContextGraphQueryShell(contextGraphPath: string, contextGraphName: string, buildPlanId: string, options?: {
+    buildPlanOriginSelected?: string | null;
+    buildPlanLocalDraft?: boolean;
+}): boolean;
+export declare function projectSourceFilesTestQueryShell(rootPath: string): boolean;
+export declare function createStageExecutionShell(contextGraphPath: string, contextGraphName: string, buildPlanId: string, stage: NativeStageDefinition, writeArtifacts?: readonly string[]): {
+    rootPath: string;
+};
+export declare function freezeStageExecutionShell(rootPath: string): string | null;
+export declare function createBuildPlanAuthoringShell(options: {
+    buildPlanPath: string;
+    buildPlanId: string;
+    label: string;
+    referenceBuildPlanId?: string | null;
+    sourceFolderPath: string;
+    intent: string;
+    checks: BuildPlanContextCheckDraft[];
+    userPrepInstructions?: string;
+    requestedArtifacts?: RequestedArtifact[];
+    sourceContext?: SourceContext | null;
+    artifactRequirements?: BuildPlanAuthoringArtifactRequirement[];
+    shellRoot?: string;
+}): {
+    rootPath: string;
+    buildPlanBeforePath: string;
+    buildPlanAfterPath: string;
+    promptLogPath: string;
+    eventLogPath: string;
+    statusLogPath: string;
+    reasoningLogPath: string;
+};
+export declare function freezeBuildPlanAuthoringShell(rootPath: string): string | null;
+export declare function createBuildPlanImprovementShell(options: {
+    contextGraphPath: string;
+    contextGraphName: string;
+    buildPlanId: string;
+    runId: string;
+    loopIndex: number;
+    context: BuildPlanImprovementContext;
+}): {
+    rootPath: string;
+    loopRootPath: string;
+    buildPlanBeforePath: string;
+    buildPlanAfterPath: string;
+    promptLogPath: string;
+    eventLogPath: string;
+    statusLogPath: string;
+    reasoningLogPath: string;
+};
+export declare function freezeBuildPlanImprovementShell(rootPath: string): string | null;

package/dist/packages/runtime/agents/lib/shells.js

@@ -0,0 +1,509 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative, resolve } from "node:path";
+import { buildShellSourceState, loadBuildStageInputs, loadContextGraphSourceManifest, loadContextGraphSourceState, } from "../../build/source-manifest.js";
+import { writeStageExpectedInputs, } from "../../build/stage-manifest.js";
+import { resolveBuildContext, } from "../../build/build-target.js";
+import { CHECK_PARAM_CONTRACTS, CHECK_KINDS, SourceManifestSchema, StageInputsSchema, } from "../../../contracts/lib/schema.js";
+import { stageExecutionShellsRoot, buildPlanImprovementLoopRoot, buildPlanPackagePathForContextGraph, contextGraphInterfConfigPath, contextGraphRuntimeSourceManifestPath, contextGraphRuntimeStageExpectedInputsPath, contextGraphRuntimeRoot, } from "../../build/context-graph-paths.js";
+import { writeFileAtomic, writeJsonAtomic } from "../../build/atomic-fs.js";
+import { resolveBuildPlanImprovementReviewSourcePaths } from "../../../build-plans/package/build-plan-review-paths.js";
+import { copyIfExists, copyResolvedTree, freezePreservedShell, writeIfChanged, writeNativeSkillCopies, } from "./shell-fs.js";
+import { shellRuntimePath, } from "./shell-paths.js";
+import { writeStageExecutionWorkspaceManifest, } from "./shell-workspace.js";
+import { readBuildPlanImprovementDoc, readContextGraphQuerySkillSource, renderBuildPlanAuthoringAgents, renderBuildPlanAuthoringSkill, renderBuildPlanImprovementAgents, renderBuildPlanImprovementSkill, renderClaudeBootstrap, renderSourceFilesTestAgents, renderSourceFilesTestQuerySkill, renderStageExecutionAgents, renderStageExecutionSkill, renderContextGraphAgents, renderContextGraphQueryNativeSkill, renderContextGraphQuerySkill, } from "./shell-templates.js";
+import { buildStageArtifactMounts, ensureBuildExecutionSurface, projectBuildPlanMetadata, projectStageArtifactMountAliases, projectContextGraphReviewArtifactsState, projectContextGraphRuntimeArtifacts, projectContextGraphSchemaArtifacts, readStageBuildPlanDoc, stageMaterializedArtifactSet, syncStageExecutionShellWrites, writeExecutionShellPathsFile, } from "./shell-projection.js";
+export { syncStageExecutionShellWrites };
+export { renderClaudeBootstrap, renderContextGraphQuerySkill };
+function shellRelativePathInside(shellRoot, locator) {
+    const absolutePath = resolve(shellRoot, locator);
+    const relativePath = relative(shellRoot, absolutePath);
+    if (relativePath === "" || relativePath.startsWith("..") || resolve(relativePath) === relativePath) {
+        return null;
+    }
+    return absolutePath;
+}
+export function validateStageExecutionShellInputs(options) {
+    const canonicalInputs = loadBuildStageInputs(options.contextGraphPath, options.stage.id);
+    if (!canonicalInputs) {
+        return { ok: false, summary: `Missing canonical stage inputs for ${options.stage.id}.` };
+    }
+    const canonicalManifest = loadContextGraphSourceManifest(options.contextGraphPath);
+    if (!canonicalManifest) {
+        return { ok: false, summary: "Missing canonical Source Manifest for stage execution." };
+    }
+    if (canonicalInputs.version !== 3 || canonicalInputs.source_manifest_id !== canonicalManifest.manifest_id) {
+        return { ok: false, summary: "Canonical stage inputs are not backed by the current Source Manifest." };
+    }
+    const shellInputsPath = shellRuntimePath(options.shellRoot, "stage-inputs.json");
+    if (!existsSync(shellInputsPath)) {
+        return { ok: false, summary: "Stage shell is missing runtime/stage-inputs.json." };
+    }
+    let shellInputs;
+    try {
+        shellInputs = StageInputsSchema.parse(JSON.parse(readFileSync(shellInputsPath, "utf8")));
+    }
+    catch (error) {
+        return {
+            ok: false,
+            summary: `Stage shell inputs are invalid: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (shellInputs.source_state_id !== canonicalInputs.source_state_id) {
+        return { ok: false, summary: "Stage shell inputs do not match the canonical Source state id." };
+    }
+    if (shellInputs.version !== 3 || shellInputs.source_manifest_id !== canonicalManifest.manifest_id) {
+        return { ok: false, summary: "Stage shell inputs do not match the canonical Source Manifest id." };
+    }
+    if (shellInputs.inputs.length !== canonicalInputs.inputs.length || shellInputs.input_total !== canonicalInputs.input_total) {
+        return { ok: false, summary: "Stage shell input count does not match the canonical stage input count." };
+    }
+    const shellManifestPath = shellRuntimePath(options.shellRoot, "source-manifest.json");
+    if (!existsSync(shellManifestPath)) {
+        return { ok: false, summary: "Stage shell is missing runtime/source-manifest.json." };
+    }
+    let shellManifest;
+    try {
+        shellManifest = SourceManifestSchema.parse(JSON.parse(readFileSync(shellManifestPath, "utf8")));
+    }
+    catch (error) {
+        return {
+            ok: false,
+            summary: `Stage shell Source Manifest is invalid: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (shellManifest.manifest_id !== canonicalManifest.manifest_id) {
+        return { ok: false, summary: "Stage shell Source Manifest does not match the canonical manifest id." };
+    }
+    const shellInputsByKey = new Map(shellInputs.inputs.map((input) => [`${input.source_file_id}\0${input.path}`, input]));
+    for (const canonicalInput of canonicalInputs.inputs) {
+        const key = `${canonicalInput.source_file_id}\0${canonicalInput.path}`;
+        const shellInput = shellInputsByKey.get(key);
+        if (!shellInput) {
+            return { ok: false, summary: `Stage shell is missing source input ${canonicalInput.path}.` };
+        }
+        if (canonicalInput.content_hash && shellInput.content_hash !== canonicalInput.content_hash) {
+            return { ok: false, summary: `Stage shell source input ${canonicalInput.path} has a changed content hash.` };
+        }
+        if (shellInput.locator !== canonicalInput.locator) {
+            return { ok: false, summary: `Stage shell source input ${canonicalInput.path} has a changed locator.` };
+        }
+    }
+    return { ok: true, summary: "Stage shell inputs match canonical source slices." };
+}
+export function writeNativeAgentSurface(rootPath, agentsContent, skillName, skillContent) {
+    let changed = false;
+    changed = writeIfChanged(join(rootPath, "AGENTS.md"), `${agentsContent.trimEnd()}\n`) || changed;
+    changed =
+        writeIfChanged(join(rootPath, "CLAUDE.md"), renderClaudeBootstrap(agentsContent)) || changed;
+    changed = writeNativeSkillCopies(rootPath, skillName, skillContent) || changed;
+    return changed;
+}
+/**
+ * One data-driven shell constructor shared by every agent job (stage execution,
+ * Build Plan authoring, Build Plan improvement). The shared skeleton lives here
+ * exactly once: create the shell root, create the requested subdirectories, and
+ * write the native agent surface (AGENTS.md / CLAUDE.md / SKILL.md) the agent
+ * boots from. Job-specific projection (runtime inputs, source locators, build
+ * plan trees, artifact mounts) stays in each caller — `createAgentShell` only
+ * owns the skeleton, so a reader traces shell setup through one function instead
+ * of three near-identical ones.
+ *
+ * `rootPath` is resolved by the caller (the three job kinds keep their distinct
+ * storage roots: stage shells under the Context Graph, improvement loops under
+ * the loop root, authoring shells under the Project's service job storage).
+ */
+export function createAgentShell(options) {
+    mkdirSync(options.rootPath, { recursive: true });
+    for (const subdir of options.subdirs) {
+        mkdirSync(join(options.rootPath, subdir), { recursive: true });
+    }
+    writeNativeAgentSurface(options.rootPath, options.nativeSurface.agentsContent, options.nativeSurface.skillName, options.nativeSurface.skillContent);
+    return { rootPath: options.rootPath };
+}
+export function pruneStageExecutionShells(contextGraphPath) {
+    rmSync(stageExecutionShellsRoot(contextGraphPath), { recursive: true, force: true });
+}
+export function projectContextGraphQueryShell(contextGraphPath, contextGraphName, buildPlanId, options) {
+    const agentsContent = renderContextGraphAgents(contextGraphPath, contextGraphName, buildPlanId, options);
+    const querySkillContent = readContextGraphQuerySkillSource(contextGraphPath);
+    return writeNativeAgentSurface(contextGraphPath, agentsContent, "interf-query", renderContextGraphQueryNativeSkill(querySkillContent));
+}
+export function projectSourceFilesTestQueryShell(rootPath) {
+    return writeNativeAgentSurface(rootPath, renderSourceFilesTestAgents(), "interf-query", renderSourceFilesTestQuerySkill());
+}
+export function createStageExecutionShell(contextGraphPath, contextGraphName, buildPlanId, stage, writeArtifacts = []) {
+    const schema = ensureBuildExecutionSurface(contextGraphPath);
+    const materializedArtifacts = stageMaterializedArtifactSet(schema, stage, writeArtifacts);
+    const cleanWriteArtifacts = new Set(stage.writes.filter((artifactId) => !stage.reads.includes(artifactId)));
+    const shellsRoot = stageExecutionShellsRoot(contextGraphPath);
+    const { rootPath: shellRoot } = createAgentShell({
+        rootPath: join(shellsRoot, `${stage.id}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`),
+        subdirs: ["runtime", join(".interf", "runtime"), "inputs", "outputs", "logs"],
+        nativeSurface: {
+            agentsContent: renderStageExecutionAgents(contextGraphName, buildPlanId, stage),
+            skillName: "interf-stage",
+            skillContent: renderStageExecutionSkill(stage, readStageBuildPlanDoc(contextGraphPath, stage)),
+        },
+    });
+    copyResolvedTree({
+        sourcePath: contextGraphInterfConfigPath(contextGraphPath),
+        targetPath: join(shellRoot, "interf.json"),
+        shellType: "stage-execution",
+    });
+    copyIfExists(join(contextGraphRuntimeRoot(contextGraphPath), "stage-contract.json"), shellRuntimePath(shellRoot, "stage-contract.json"), "stage-execution");
+    const sourceState = loadContextGraphSourceState(contextGraphPath);
+    const stageInputs = loadBuildStageInputs(contextGraphPath, stage.id);
+    const sourceManifest = loadContextGraphSourceManifest(contextGraphPath);
+    if (!existsSync(contextGraphRuntimeStageExpectedInputsPath(contextGraphPath, stage.id))) {
+        writeStageExpectedInputs({ contextGraphPath, stage });
+    }
+    const buildContext = resolveBuildContext(contextGraphPath);
+    writeJsonAtomic(shellRuntimePath(shellRoot, "project.json"), {
+        kind: "interf-stage-project-context",
+        version: 1,
+        project: buildContext.project,
+        build_plan: buildPlanId,
+        stage: stage.id,
+    });
+    if (sourceManifest) {
+        writeJsonAtomic(shellRuntimePath(shellRoot, "source-manifest.json"), sourceManifest);
+        copyIfExists(contextGraphRuntimeSourceManifestPath(contextGraphPath), join(shellRoot, ".interf", "runtime", "source-manifest.json"), "stage-execution");
+    }
+    if (sourceState && stageInputs) {
+        writeJsonAtomic(shellRuntimePath(shellRoot, "stage-inputs.json"), stageInputs);
+        writeJsonAtomic(shellRuntimePath(shellRoot, "source-state.json"), buildShellSourceState(sourceState, stageInputs));
+    }
+    copyIfExists(contextGraphRuntimeStageExpectedInputsPath(contextGraphPath, stage.id), shellRuntimePath(shellRoot, "expected-inputs.json"), "stage-execution");
+    writeStageSelfCheckScript(shellRoot);
+    projectContextGraphSchemaArtifacts(contextGraphPath, shellRoot, schema, new Set([...stage.reads, ...stage.writes]), materializedArtifacts, cleanWriteArtifacts);
+    projectBuildPlanMetadata(contextGraphPath, shellRoot, stage);
+    projectStageArtifactMountAliases(shellRoot, stage, schema);
+    writeExecutionShellPathsFile(shellRoot, buildPlanId, stage, buildStageArtifactMounts(contextGraphPath, shellRoot, stage, schema));
+    writeStageExecutionWorkspaceManifest({
+        contextGraphPath,
+        shellRoot,
+        buildPlanId,
+        stage,
+    });
+    return {
+        rootPath: shellRoot,
+    };
+}
+function writeStageSelfCheckScript(shellRoot) {
+    const checkEvaluatorModuleUrl = new URL("../../build/check-evaluator.js", import.meta.url).href;
+    const runtimeSchemaModuleUrl = new URL("../../build/lib/schema.js", import.meta.url).href;
+    const contractsSchemaModuleUrl = new URL("../../../contracts/lib/schema.js", import.meta.url).href;
+    const script = [
+        "#!/usr/bin/env node",
+        "import { existsSync, readFileSync } from \"node:fs\";",
+        "import { dirname, resolve } from \"node:path\";",
+        "import { fileURLToPath } from \"node:url\";",
+        "",
+        `const { evaluateChecks } = await import(${JSON.stringify(checkEvaluatorModuleUrl)});`,
+        `const { RuntimeStageContractSchema } = await import(${JSON.stringify(runtimeSchemaModuleUrl)});`,
+        `const { ResourceRefSchema, ReviewedInputSchema, SourceManifestSchema, StageEvidenceSchema, StageInputsSchema } = await import(${JSON.stringify(contractsSchemaModuleUrl)});`,
+        "",
+        "const shellRoot = resolve(dirname(fileURLToPath(import.meta.url)), \"..\");",
+        "const contractPath = resolve(shellRoot, \"runtime\", \"stage-contract.json\");",
+        "const contract = RuntimeStageContractSchema.parse(JSON.parse(readFileSync(contractPath, \"utf8\")));",
+        "const artifactResults = [];",
+        "const evidenceFailures = [];",
+        "const inputFailures = [];",
+        "const coverageFailures = [];",
+        "const stageInputsPath = resolve(shellRoot, \"runtime\", \"stage-inputs.json\");",
+        "",
+        "if (!existsSync(stageInputsPath)) {",
+        "  inputFailures.push(\"runtime/stage-inputs.json was not written.\");",
+        "} else {",
+        "  try {",
+        "    const stageInputs = StageInputsSchema.parse(JSON.parse(readFileSync(stageInputsPath, \"utf8\")));",
+        "    if (stageInputs.input_total !== stageInputs.inputs.length) {",
+        "      inputFailures.push(`stage-inputs input_total ${stageInputs.input_total} does not match ${stageInputs.inputs.length}.`);",
+        "    }",
+        "    const manifestPath = resolve(shellRoot, \"runtime\", \"source-manifest.json\");",
+        "    if (!existsSync(manifestPath)) {",
+        "      inputFailures.push(\"runtime/source-manifest.json was not written.\");",
+        "    } else {",
+        "      const manifest = SourceManifestSchema.parse(JSON.parse(readFileSync(manifestPath, \"utf8\")));",
+        "      if (stageInputs.version !== 3 || stageInputs.source_manifest_id !== manifest.manifest_id) {",
+        "        inputFailures.push(\"stage inputs are not backed by runtime/source-manifest.json.\");",
+        "      }",
+        "    }",
+        "  } catch (error) {",
+        "    inputFailures.push(`stage inputs JSON is invalid: ${error instanceof Error ? error.message : String(error)}`);",
+        "  }",
+        "}",
+        "",
+        "const expectedInputsPath = resolve(shellRoot, \"runtime\", \"expected-inputs.json\");",
+        "const reviewedInputsPath = resolve(shellRoot, \"runtime\", \"reviewed-inputs.json\");",
+        "let expectedInputs = [];",
+        "if (!existsSync(expectedInputsPath)) {",
+        "  coverageFailures.push(\"runtime/expected-inputs.json was not written.\");",
+        "} else {",
+        "  try {",
+        "    const file = JSON.parse(readFileSync(expectedInputsPath, \"utf8\"));",
+        "    if (file.kind !== \"interf-stage-expected-inputs\" || file.stage_id !== contract.stage) {",
+        "      coverageFailures.push(`expected inputs file is not for stage ${contract.stage}.`);",
+        "    }",
+        "    expectedInputs = Array.isArray(file.expected)",
+        "      ? file.expected.map((entry) => ResourceRefSchema.parse(entry))",
+        "      : [];",
+        "    if (!Array.isArray(file.expected)) {",
+        "      coverageFailures.push(\"expected inputs file must contain an expected array.\");",
+        "    }",
+        "  } catch (error) {",
+        "    coverageFailures.push(`expected inputs JSON is invalid: ${error instanceof Error ? error.message : String(error)}`);",
+        "  }",
+        "}",
+        "",
+        "if (!existsSync(reviewedInputsPath)) {",
+        "  coverageFailures.push(\"runtime/reviewed-inputs.json was not written.\");",
+        "} else {",
+        "  try {",
+        "    const file = JSON.parse(readFileSync(reviewedInputsPath, \"utf8\"));",
+        "    if (file.kind !== \"interf-stage-reviewed-inputs\" || file.stage_id !== contract.stage) {",
+        "      coverageFailures.push(`reviewed inputs file is not for stage ${contract.stage}.`);",
+        "    }",
+        "    const reviewed = Array.isArray(file.reviewed)",
+        "      ? file.reviewed.map((entry) => ReviewedInputSchema.parse(entry))",
+        "      : [];",
+        "    if (!Array.isArray(file.reviewed)) {",
+        "      coverageFailures.push(\"reviewed inputs file must contain a reviewed array.\");",
+        "    }",
+        "    const expectedIds = new Set(expectedInputs.map((entry) => entry.id));",
+        "    const reviewedIds = new Set(reviewed.map((entry) => entry.resource_id));",
+        "    for (const entry of reviewed) {",
+        "      if (!expectedIds.has(entry.resource_id)) {",
+        "        coverageFailures.push(`reviewed input ${entry.resource_id} is not in runtime/expected-inputs.json.`);",
+        "      }",
+        "      if ((entry.decision === \"missing\" || entry.decision === \"blocked\" || entry.decision === \"not-relevant\") && !entry.reason) {",
+        "        coverageFailures.push(`reviewed input ${entry.resource_id} needs a reason for decision ${entry.decision}.`);",
+        "      }",
+        "    }",
+        "    for (const input of expectedInputs) {",
+        "      if (input.required !== false && !reviewedIds.has(input.id)) {",
+        "        coverageFailures.push(`required expected input ${input.id} was not reviewed.`);",
+        "      }",
+        "    }",
+        "  } catch (error) {",
+        "    coverageFailures.push(`reviewed inputs JSON is invalid: ${error instanceof Error ? error.message : String(error)}`);",
+        "  }",
+        "}",
+        "",
+        "for (const writeContract of contract.artifacts.write_contracts) {",
+        "  const result = evaluateChecks(writeContract.checks, {",
+        "    rootPath: shellRoot,",
+        "    targetPath: writeContract.path,",
+        "    counts: contract.counts,",
+        "  });",
+        "  artifactResults.push({",
+        "    artifact_id: writeContract.artifact_id,",
+        "    path: writeContract.path,",
+        "    check_results: result.check_results,",
+        "    failures: result.failures,",
+        "  });",
+        "}",
+        "",
+        "const failures = artifactResults.flatMap((artifact) =>",
+        "  artifact.failures.map((failure) => ({ artifact, failure })),",
+        ");",
+        "const totalChecks = artifactResults.reduce((total, artifact) => total + artifact.check_results.length, 0);",
+        "const passedChecks = artifactResults.reduce(",
+        "  (total, artifact) => total + artifact.check_results.filter((check) => check.passed).length,",
+        "  0,",
+        ");",
+        "",
+        "if (contract.contract_type === \"build-file-evidence\") {",
+        "  const evidencePath = resolve(shellRoot, \"runtime\", \"stage-evidence.json\");",
+        "  if (!existsSync(evidencePath)) {",
+        "    evidenceFailures.push(\"runtime/stage-evidence.json was not written.\");",
+        "  } else {",
+        "    try {",
+        "      const evidence = StageEvidenceSchema.parse(JSON.parse(readFileSync(evidencePath, \"utf8\")));",
+        "      if (evidence.run_id !== contract.run_id) {",
+        "        evidenceFailures.push(`stage evidence run_id ${evidence.run_id} does not match ${contract.run_id}.`);",
+        "      }",
+        "      if (evidence.stage !== contract.stage) {",
+        "        evidenceFailures.push(`stage evidence stage ${evidence.stage} does not match ${contract.stage}.`);",
+        "      }",
+        "      const evidenceItemsWithRefs = evidence.items.filter((item) => item.source_refs.length > 0 || item.output_refs.length > 0);",
+        "      if (evidenceItemsWithRefs.length === 0) {",
+        "        evidenceFailures.push(\"stage evidence needs at least one source/output evidence item.\");",
+        "      }",
+        "      const writableArtifacts = new Set([",
+        "        ...contract.artifacts.writes,",
+        "        ...contract.artifacts.write_contracts.map((writeContract) => writeContract.artifact_id),",
+        "      ]);",
+        "      for (const item of evidence.items) {",
+        "        for (const ref of item.output_refs) {",
+        "          if (!writableArtifacts.has(ref.artifact_id)) {",
+        "            evidenceFailures.push(`stage evidence output artifact ${ref.artifact_id} is not a declared write.`);",
+        "          }",
+        "          if (!existsSync(resolve(shellRoot, ref.path))) {",
+        "            evidenceFailures.push(`stage evidence output path ${ref.path} does not exist.`);",
+        "          }",
+        "        }",
+        "      }",
+        "    } catch (error) {",
+        "      evidenceFailures.push(`stage evidence JSON is invalid: ${error instanceof Error ? error.message : String(error)}`);",
+        "    }",
+        "  }",
+        "}",
+        "",
+        "if (failures.length === 0 && evidenceFailures.length === 0 && inputFailures.length === 0 && coverageFailures.length === 0) {",
+        "  console.log(`VALID: ${contract.stage} stage outputs satisfy ${passedChecks}/${totalChecks} deterministic check(s).`);",
+        "  process.exit(0);",
+        "}",
+        "",
+        "console.log(`INVALID: ${failures.length + evidenceFailures.length + inputFailures.length + coverageFailures.length} required deterministic check(s) failed for stage ${contract.stage}.`);",
+        "for (const { artifact, failure } of failures) {",
+        "  console.log(`- ${artifact.artifact_id} (${artifact.path}) / ${failure.check_id}: ${failure.summary}`);",
+        "  if (failure.details) {",
+        "    console.log(`  details: ${JSON.stringify(failure.details)}`);",
+        "  }",
+        "}",
+        "for (const failure of evidenceFailures) {",
+        "  console.log(`- stage evidence: ${failure}`);",
+        "}",
+        "for (const failure of inputFailures) {",
+        "  console.log(`- stage input: ${failure}`);",
+        "}",
+        "for (const failure of coverageFailures) {",
+        "  console.log(`- stage coverage: ${failure}`);",
+        "}",
+        "process.exit(1);",
+        "",
+    ].join("\n");
+    writeFileAtomic(shellRuntimePath(shellRoot, "check-stage.mjs"), script);
+}
+export function freezeStageExecutionShell(rootPath) {
+    return freezePreservedShell(rootPath, "stage-execution");
+}
+export function createBuildPlanAuthoringShell(options) {
+    const { rootPath: shellRoot } = createAgentShell({
+        // Durable Project job storage in the launched path; ephemeral /tmp only when
+        // no durable root was supplied (unit tests of the draft/parse path).
+        rootPath: options.shellRoot ??
+            mkdtempSync(join(tmpdir(), `interf-build-plan-author-${options.buildPlanId}-`)),
+        subdirs: ["runtime", "artifacts", "logs"],
+        nativeSurface: {
+            agentsContent: renderBuildPlanAuthoringAgents({
+                buildPlanId: options.buildPlanId,
+                label: options.label,
+                referenceBuildPlanId: options.referenceBuildPlanId ?? null,
+            }),
+            skillName: "interf-build-plan-author",
+            skillContent: renderBuildPlanAuthoringSkill(),
+        },
+    });
+    // source_context is resolved ONCE by the caller (runBuildPlanAuthoringDraft):
+    // caller-supplied context wins, else the cheap contents-free Source scan,
+    // else null. The shell is a pure consumer here so authoring-context.json and
+    // the persisted authoring brief always carry the SAME value. Do not re-derive
+    // or re-scan it in the shell.
+    const sourceContext = options.sourceContext ?? null;
+    const context = {
+        kind: "interf-build-plan-authoring",
+        version: 1,
+        generated_at: new Date().toISOString(),
+        authoring_mode: "from-scratch",
+        build_plan_id: options.buildPlanId,
+        build_plan_label: options.label,
+        ...(options.referenceBuildPlanId ? { reference_build_plan_id: options.referenceBuildPlanId } : {}),
+        intent: options.intent,
+        ...(options.userPrepInstructions ? { user_prep_instructions: options.userPrepInstructions } : {}),
+        allowed_check_kinds: CHECK_KINDS,
+        check_param_contracts: CHECK_PARAM_CONTRACTS,
+        requested_artifacts: options.requestedArtifacts ?? [],
+        checks: options.checks,
+        artifact_requirements: options.artifactRequirements ?? [],
+        project: {
+            source_folder_path: options.sourceFolderPath,
+            source_context: sourceContext,
+        },
+    };
+    writeFileSync(join(shellRoot, "runtime", "authoring-context.json"), `${JSON.stringify(context, null, 2)}\n`);
+    writeFileSync(join(shellRoot, "runtime", "source-locator.json"), `${JSON.stringify({
+        kind: "interf-source-locator",
+        version: 1,
+        generated_at: new Date().toISOString(),
+        source: {
+            kind: "local-folder",
+            locator: options.sourceFolderPath,
+        },
+        note: "Interf attaches a cheap, contents-free Source scan (folder names, file counts, file kinds, sampled filenames, filename date ranges) to runtime/authoring-context.json.project.source_context. It never reads file contents. Use it to shape stages, then inspect this locator through your own Source access before locking the plan.",
+    }, null, 2)}\n`);
+    copyResolvedTree({
+        sourcePath: options.buildPlanPath,
+        targetPath: join(shellRoot, "build-plan"),
+        shellType: "build-plan-authoring",
+    });
+    return {
+        rootPath: shellRoot,
+        buildPlanBeforePath: join(shellRoot, "artifacts", "build-plan-before"),
+        buildPlanAfterPath: join(shellRoot, "artifacts", "build-plan-after"),
+        promptLogPath: join(shellRoot, "logs", "build-plan-author.prompt.txt"),
+        eventLogPath: join(shellRoot, "logs", "build-plan-author.events.ndjson"),
+        statusLogPath: join(shellRoot, "logs", "build-plan-author.status.log"),
+        // Same canonical convention as the stage path: reasoning is teed into the
+        // shell's runtime/ dir so it is preserved when the shell is frozen.
+        reasoningLogPath: join(shellRoot, "runtime", "agent-reasoning.jsonl"),
+    };
+}
+export function freezeBuildPlanAuthoringShell(rootPath) {
+    return freezePreservedShell(rootPath, "build-plan-authoring");
+}
+export function createBuildPlanImprovementShell(options) {
+    const schema = ensureBuildExecutionSurface(options.contextGraphPath);
+    const loopRootPath = buildPlanImprovementLoopRoot(options.contextGraphPath, options.runId, options.loopIndex);
+    const { rootPath: shellRoot } = createAgentShell({
+        rootPath: join(loopRootPath, "shell"),
+        subdirs: ["runtime", "artifacts"],
+        nativeSurface: {
+            agentsContent: renderBuildPlanImprovementAgents(options.contextGraphName, options.buildPlanId, options.loopIndex),
+            skillName: "interf-build-plan-improver",
+            skillContent: renderBuildPlanImprovementSkill(options.buildPlanId, options.loopIndex, readBuildPlanImprovementDoc(options.contextGraphPath)),
+        },
+    });
+    // Improvement logs live one level up in the loop root (not the shell), so the
+    // loop record can index them beside build-plan-before/after.
+    mkdirSync(join(loopRootPath, "logs"), { recursive: true });
+    writeFileSync(join(shellRoot, "runtime", "loop-context.json"), `${JSON.stringify(options.context, null, 2)}\n`);
+    projectContextGraphReviewArtifactsState(options.contextGraphPath, shellRoot, schema);
+    copyResolvedTree({
+        sourcePath: buildPlanPackagePathForContextGraph(options.contextGraphPath),
+        targetPath: join(shellRoot, "build-plan"),
+        shellType: "build-plan-improvement",
+    });
+    copyIfExists(contextGraphInterfConfigPath(options.contextGraphPath), join(shellRoot, "interf.json"), "build-plan-improvement");
+    projectContextGraphRuntimeArtifacts(options.contextGraphPath, shellRoot);
+    const reviewSources = resolveBuildPlanImprovementReviewSourcePaths(options.contextGraphPath);
+    if (reviewSources.executionShells) {
+        copyIfExists(reviewSources.executionShells, join(shellRoot, "artifacts", "execution-shells"), "build-plan-improvement");
+    }
+    if (reviewSources.benchmarkRuns) {
+        copyIfExists(reviewSources.benchmarkRuns, join(shellRoot, "artifacts", "benchmark-runs"), "build-plan-improvement");
+    }
+    if (reviewSources.targetTestRuns) {
+        copyIfExists(reviewSources.targetTestRuns, join(shellRoot, "artifacts", "test-runs"), "build-plan-improvement");
+    }
+    if (reviewSources.targetTestSandboxes) {
+        copyIfExists(reviewSources.targetTestSandboxes, join(shellRoot, "artifacts", "test-sandboxes"), "build-plan-improvement");
+    }
+    return {
+        rootPath: shellRoot,
+        loopRootPath,
+        buildPlanBeforePath: join(loopRootPath, "build-plan-before"),
+        buildPlanAfterPath: join(loopRootPath, "build-plan-after"),
+        promptLogPath: join(loopRootPath, "logs", "build-plan-improver.prompt.txt"),
+        eventLogPath: join(loopRootPath, "logs", "build-plan-improver.events.ndjson"),
+        statusLogPath: join(loopRootPath, "logs", "build-plan-improver.status.log"),
+        // Reasoning is teed into the shell's runtime/ dir (same convention as the
+        // stage path) so it is preserved when the improvement shell is frozen.
+        reasoningLogPath: join(shellRoot, "runtime", "agent-reasoning.jsonl"),
+    };
+}
+export function freezeBuildPlanImprovementShell(rootPath) {
+    return freezePreservedShell(rootPath, "build-plan-improvement");
+}

package/dist/packages/runtime/agents/lib/source-context-scan.d.ts

@@ -0,0 +1,10 @@
+import type { SourceContext } from "../../../build-plans/authoring/brief.js";
+/**
+ * Produce a populated SourceContext for the authoring agent from a cheap,
+ * contents-free scan. Returns null when the Source has no readable files so
+ * callers can fall back to the existing null (no fabricated inventory). A
+ * genuine read failure on the Source root returns an explicit read-error
+ * SourceContext instead, so an unreadable Source never silently degrades into
+ * a generic plan.
+ */
+export declare function scanSourceContext(sourceFolderPath: string): SourceContext | null;