@interf/compiler 0.22.0 → 0.33.0

package/dist/packages/runtime/agents/lib/shell-templates.d.ts

@@ -0,0 +1,30 @@
+export interface NativeStageDefinition {
+    id: string;
+    label: string;
+    description: string;
+    contractType: import("../../../contracts/lib/schema.js").RuntimeContractType;
+    skillDir: string;
+    reads: import("../../../build-plans/package/context-interface.js").ContextInterfaceArtifactId[];
+    writes: import("../../../build-plans/package/context-interface.js").ContextInterfaceArtifactId[];
+}
+export declare function renderContextGraphAgents(contextGraphPath: string, name: string, buildPlanId: string, options?: {
+    buildPlanOriginSelected?: string | null;
+    buildPlanLocalDraft?: boolean;
+}): string;
+export declare function renderContextGraphQuerySkill(): string;
+export declare function renderSourceFilesTestAgents(): string;
+export declare function renderSourceFilesTestQuerySkill(): string;
+export declare function readContextGraphQuerySkillSource(contextGraphPath: string): string;
+export declare function renderStageExecutionAgents(contextGraphName: string, buildPlanId: string, stage: NativeStageDefinition): string;
+export declare function renderStageExecutionSkill(stage: NativeStageDefinition, stageBuildPlanDoc: string | null): string;
+export declare function renderContextGraphQueryNativeSkill(querySkillContent: string): string;
+export declare function renderClaudeBootstrap(content: string): string;
+export declare function renderBuildPlanAuthoringAgents(options: {
+    buildPlanId: string;
+    label: string;
+    referenceBuildPlanId?: string | null;
+}): string;
+export declare function renderBuildPlanAuthoringSkill(): string;
+export declare function renderBuildPlanImprovementAgents(contextGraphName: string, buildPlanId: string, loopIndex: number): string;
+export declare function readBuildPlanImprovementDoc(contextGraphPath: string): string | null;
+export declare function renderBuildPlanImprovementSkill(buildPlanId: string, loopIndex: number, improvementDoc: string | null): string;

package/dist/packages/runtime/agents/lib/shell-templates.js

@@ -0,0 +1,452 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildPlanPackagePathForContextGraph } from "../../build/context-graph-paths.js";
+import { CONTEXT_INTERFACE_FILE as BUILD_PLAN_SCHEMA_FILE, listContextInterfaceArtifacts, readContextInterface as readBuildPlanContextFile, } from "../../../build-plans/package/context-interface.js";
+import { improvementBuildPlanDocsPath, contextGraphQuerySkillSourcePath, } from "./shell-paths.js";
+const CHART_APPROXIMATION_NOTES = [
+    "When a chart-derived value is approximate, use a bounded range instead of a pseudo-exact number.",
+    "Match the granularity of the visible axis labels or bands. Do not invent finer precision than the chart supports.",
+    "Keep the answer inside the visible tick band unless the chart supports a tighter bound.",
+    "Use an upper-half or lower-half band only when the mark clearly sits there.",
+    "If a mark touches or nearly touches a labeled gridline, anchor the answer at that gridline or the immediately adjacent half-band.",
+    "Do not widen a chart-derived range across multiple visible bands unless the chart genuinely supports that uncertainty.",
+];
+function contextGraphArtifactSummaryLines(contextGraphPath) {
+    const schema = readBuildPlanContextFile(buildPlanPackagePathForContextGraph(contextGraphPath));
+    if (!schema)
+        return ["- No Build Plan schema is available yet."];
+    return listContextInterfaceArtifacts(schema)
+        .map((artifact) => `- \`${artifact.id}\` -> \`${artifact.path}\` (${artifact.kind})`);
+}
+export function renderContextGraphAgents(contextGraphPath, name, buildPlanId, options = {}) {
+    const buildPlanOriginSelected = options.buildPlanOriginSelected ?? buildPlanId;
+    const buildPlanLocalDraft = options.buildPlanLocalDraft === true;
+    const artifactLines = contextGraphArtifactSummaryLines(contextGraphPath);
+    return [
+        `# ${name}`,
+        "",
+        "This is a Context Graph built by Interf.",
+        "This folder gives agents a prepared knowledge map over the Source: summaries, claims, requested Artifacts, traces, routes, and links back to sources.",
+        "It normally contains source references rather than raw source copies. The original Source remains the source of truth.",
+        "Use this graph before any source drilldown so you know what exists, what matters, and where evidence lives.",
+        "",
+        "## How to use this Context Graph",
+        "",
+        "1. Use the local native `interf-query` skill that Interf generated for this Context Graph.",
+        "2. Let the Build Plan docs and declared Artifacts guide retrieval instead of assuming a fixed note layout.",
+        "3. Use `.interf/runtime/source-manifest.json` to follow graph-provided source references for exact quotes, table values, chart reads, and provenance-sensitive claims.",
+        "",
+        "## How this Context Graph works",
+        "",
+        "- The Build Plan defines the requested Artifact contract this Context Graph implements on disk.",
+        "- `.interf/interf.json` records the selected Source binding and Project metadata.",
+        `- Build Plan seed: \`${buildPlanOriginSelected}\`.`,
+        ...(buildPlanLocalDraft
+            ? ["- This Context Graph now carries a local Build Plan draft improved from that seed. Building this Context Graph again reuses the local `.interf/build-plan/` package."]
+            : []),
+        `- Selected Build Plan id: \`${buildPlanId}\`.`,
+        "- `.interf/build-plan/` is the local editable Build Plan package for this Context Graph.",
+        `- \`.interf/build-plan/${BUILD_PLAN_SCHEMA_FILE}\` is the deterministic requested Artifact contract for this Context Graph.`,
+        "- `.interf/build-plan/improve/` is the editable source for Build Plan improvement loops.",
+        "- `.interf/build-plan/use/query/` is the editable source for the generated native query shell.",
+        "- `.interf/build-plan/build/stages/` defines stage-specific docs that Interf projects into native execution shells for automated runs.",
+        "- Native local query skills are generated under local agent skill directories such as `.claude/skills/` and `.codex/skills/`.",
+        "- `.interf/runtime/source-manifest.json` is the authoritative Source inventory recorded for this Context Graph.",
+        "- `.interf/runtime/source-state.json` is a compatibility projection of the Source Manifest.",
+        `- Requested Artifact contracts are declared in \`.interf/build-plan/${BUILD_PLAN_SCHEMA_FILE}\`.`,
+        ...artifactLines,
+        "- `.interf/runtime/` holds runtime artifacts written by Interf.",
+        "- `.interf/tests/` mirrors the latest saved benchmark/evaluation run and keeps detailed target runs plus preserved sandboxes.",
+        "- `.interf/tests/targets/` holds detailed source-files and context-graph target runs plus preserved benchmark sandboxes.",
+        "",
+        "## Manual query rules",
+        "",
+        "- Prefer the Build Plan-declared Context Graph outputs before source drilldown.",
+        "- Use the generated native `interf-query` skill for manual querying. The editable source lives at `.interf/build-plan/use/query/SKILL.md`.",
+        "- Treat `.interf/` as Build Plan/runtime metadata, not answer evidence, unless explicitly asked to inspect Build Plan or benchmark history.",
+        "- Do not bypass the graph with ad hoc source browsing. Drill into Source only through graph-provided source references, traces, requested Artifacts, or recorded Source state.",
+        "- Use `.interf/runtime/source-manifest.json` to find source references for quotes, verification, ambiguity, or evidence the Context Graph does not expose well.",
+        "- If exact chart, table, or image-derived evidence matters, inspect the cited source reference and say whether the answer was text-derived, table-derived, or chart-derived.",
+        "- If the graph points to the right evidence but misses required range, axis, period, unit, series, or provenance semantics, treat the graph as not ready and improve the Build Plan instead of presenting a blurry artifact as ready.",
+        "",
+        "## Commands",
+        "",
+        "```",
+        "interf build <project-id>  build this Context Graph",
+        "interf benchmark               run Q&A / fact-check evaluation questions against this Context Graph",
+        "interf status             show deterministic health",
+        "```",
+        "",
+        "## Rules",
+        "",
+        "- Do not modify source files while answering from this Context Graph.",
+        "- Treat Context Graph notes as source-backed working context and routing, not a replacement for the underlying Source.",
+        "- When precision matters, verify against graph-cited source references before making a strong claim.",
+        "",
+    ].join("\n");
+}
+export function renderContextGraphQuerySkill() {
+    return [
+        "# Manual Query Loop",
+        "",
+        "This file is the editable authoring source for the generated native local `interf-query` skill.",
+        "",
+        "Default loop:",
+        "1. Read `.interf/build-plan/README.md` and this file first.",
+        `2. Use the requested Artifact contract declared in \`.interf/build-plan/${BUILD_PLAN_SCHEMA_FILE}\` plus \`home.md\` to understand the prepared map.`,
+        "3. Use Context Graph notes and requested Artifacts to locate the relevant evidence before any source drilldown.",
+        "4. Use `.interf/runtime/source-manifest.json` to follow graph-provided source references for direct quotes, exact values, visual/table verification, and provenance-sensitive claims.",
+        "",
+        "Answering rule:",
+        "- do not modify source files while answering",
+        "- treat the Build Plan as the Context Graph contract and use its Artifacts as the working retrieval surface",
+        "- use the Context Graph as a knowledge map over the Source, not as a raw-source replacement",
+        "- do not bypass the graph with ad hoc source browsing; source drilldown must follow graph-provided source references, traces, requested Artifacts, or the recorded Source Manifest",
+        "- say explicitly when an answer depends on approximation, bounded inference, or a source re-check",
+        "- when exact wording, table values, chart positions, visual ranges, or provenance matter, follow the cited source reference before making a strong claim",
+        "- use source references to confirm source page, metric family, visual series, axis/range, period, unit, provenance, or exact wording",
+        "- do not invent navigation or note structure beyond what this Build Plan declares",
+        "- when the Context Graph is insufficient but points to the right source evidence, improve or rebuild if the missing semantics are part of the requested Artifact contract; do not present a blurry artifact as ready",
+        "",
+        "You can edit this file to bias manual question-answering behavior for this Context Graph.",
+        "",
+    ].join("\n");
+}
+export function renderSourceFilesTestAgents() {
+    const chartNotes = CHART_APPROXIMATION_NOTES.map((note) => `- ${note}`);
+    return [
+        "# Source Files Test Shell",
+        "",
+        "This is an isolated source-files benchmark shell generated by Interf.",
+        "There is no Context Graph in this shell.",
+        "",
+        "## How to use this shell",
+        "",
+        "1. Read this file first.",
+        "2. Use the local native `interf-query` skill available in this shell.",
+        "3. Read `runtime/source-manifest.json` and use only the listed source references.",
+        "",
+        "## Rules",
+        "",
+        "- Answer only from source files listed in `runtime/source-manifest.json`.",
+        "- There is no Context Graph here, so do not assume any Context Graph Artifacts exist.",
+        "- Do not treat hidden runtime files or benchmark artifacts as evidence.",
+        ...chartNotes,
+        "- Write the requested answer and trace files, then stop.",
+        "",
+    ].join("\n");
+}
+export function renderSourceFilesTestQuerySkill() {
+    const chartNotes = CHART_APPROXIMATION_NOTES.map((note, index) => `${index + 3}. ${note}`);
+    return [
+        "---",
+        "name: interf-query",
+        "description: >",
+        "  Native local query skill for an Interf source-files benchmark shell. Use it only",
+        "  to answer source-files benchmark questions from `runtime/source-manifest.json` references.",
+        "---",
+        "",
+        "# Interf Source Files Test Query",
+        "",
+        "This is the native local query skill for an isolated source-files benchmark shell.",
+        "",
+        "Loop:",
+        "1. Read `runtime/source-manifest.json`.",
+        "2. Verify exact claims against the listed source locators before making a strong claim.",
+        ...chartNotes,
+        "8. Do not rely on context-graph artifacts because they do not exist in this shell.",
+        "",
+    ].join("\n");
+}
+export function readContextGraphQuerySkillSource(contextGraphPath) {
+    const filePath = contextGraphQuerySkillSourcePath(contextGraphPath);
+    if (!existsSync(filePath)) {
+        throw new Error(`Missing context-graph query skill source at . Interf build runs the local Build Plan package directly, so reseed or repair this Context Graph instead of auto-healing query docs.`);
+    }
+    return readFileSync(filePath, "utf8").trim();
+}
+export function renderStageExecutionAgents(contextGraphName, buildPlanId, stage) {
+    return [
+        `# ${contextGraphName} — ${stage.label} Execution Shell`,
+        "",
+        "This is an ephemeral stage-execution shell generated by Interf.",
+        "It is for automated pipeline execution only, not for manual querying.",
+        "",
+        "## Start Here",
+        "",
+        "1. Read `runtime/stage-contract.json` now.",
+        "2. Read `runtime/source-manifest.json`, `runtime/source-state.json`, and `runtime/stage-inputs.json` now.",
+        "3. Read `runtime/paths.json` now.",
+        "4. Use the local native `interf-stage` skill now.",
+        `5. Execute only the current stage: \`${stage.id}\` (${stage.label}).`,
+        "",
+        "## Shell ABI",
+        "",
+        "- `inputs/<artifact-id>/` = read mounts for the current stage.",
+        "- `outputs/<artifact-id>/` = write mounts for the current stage.",
+        "- For file Artifacts, `runtime/paths.json` points to the exact file path inside those mount roots.",
+        "- `runtime/source-manifest.json` = authoritative Source inventory for this run.",
+        "- `runtime/source-state.json` = compatibility projection of manifest source references.",
+        "- `runtime/stage-inputs.json` = exact manifest source references assigned to this stage.",
+        "- `runtime/check-stage.mjs` = shell-local deterministic verifier for the current stage outputs.",
+        "- declared Artifact paths are also projected at the shell root so Build Plan-relative contract paths stay valid.",
+        "- `runtime/` = stage contract and machine-readable path map for this shell.",
+        "- `build-plan/` = Build Plan metadata, `build-plan.schema.json`, and docs for the current stage only.",
+        "",
+        "## Boundaries",
+        "",
+        `- Build Plan: \`${buildPlanId}\`.`,
+        `- Contract type: \`${stage.contractType}\`.`,
+        "- This shell has its own AGENTS/CLAUDE/native skills. It does not inherit the context-graph query shell.",
+        "- The context-graph root itself is not linked into this shell.",
+        "- Do not switch into query mode or act like a user-facing assistant.",
+        "- Do not modify files under `inputs/` unless the same Artifact is also mounted under `outputs/`.",
+        "",
+        "## Current Stage Artifacts",
+        "",
+        `- reads: ${stage.reads.join(", ")}`,
+        `- writes: ${stage.writes.join(", ")}`,
+        "",
+        "## Goal",
+        "",
+        "- complete the current stage",
+        "- honor the deterministic contract",
+        "- write outputs through the declared Artifact mounts",
+        "- run `node runtime/check-stage.mjs` and fix failures until it prints `VALID:`",
+        "- stop when the stage is complete",
+        "",
+    ].join("\n");
+}
+export function renderStageExecutionSkill(stage, stageBuildPlanDoc) {
+    return [
+        "---",
+        "name: interf-stage",
+        "description: >",
+        `  Native local execution skill for the ${stage.label} stage in this`,
+        "  Interf run. Use it only inside an automated stage execution shell.",
+        "---",
+        "",
+        `# Interf Stage Execution — ${stage.label}`,
+        "",
+        "This local native skill exists for automated Interf stage execution.",
+        "Read `runtime/stage-contract.json` first.",
+        "Then read `runtime/source-manifest.json`, `runtime/source-state.json`, `runtime/stage-inputs.json`, and `runtime/paths.json`.",
+        "Use the assigned source references and the mounted `inputs/` and `outputs/` Artifacts for this stage.",
+        "Before emitting DONE, run `node runtime/check-stage.mjs` from the shell root and fix outputs until it prints `VALID:`.",
+        "Do not switch into manual query mode.",
+        "",
+        "## Current Stage",
+        "",
+        `- id: \`${stage.id}\``,
+        `- label: ${stage.label}`,
+        `- contract type: \`${stage.contractType}\``,
+        `- reads: ${stage.reads.join(", ")}`,
+        `- writes: ${stage.writes.join(", ")}`,
+        `- editable source: \`build-plan/build/stages/${stage.skillDir}/SKILL.md\``,
+        "",
+        ...(stageBuildPlanDoc
+            ? [
+                "## Stage Build Plan",
+                "",
+                stageBuildPlanDoc,
+                "",
+            ]
+            : []),
+    ].join("\n");
+}
+export function renderContextGraphQueryNativeSkill(querySkillContent) {
+    return [
+        "---",
+        "name: interf-query",
+        "description: >",
+        "  Native local query skill for a Context Graph built by Interf.",
+        "  Use it for manual questions against a Context Graph and source references.",
+        "---",
+        "",
+        "# Interf Query",
+        "",
+        "This is the native local query skill for a Context Graph built by Interf.",
+        "Use it when reading this Context Graph manually.",
+        "Editable source: `.interf/build-plan/use/query/SKILL.md`.",
+        "",
+        querySkillContent.trim(),
+        "",
+    ].join("\n");
+}
+export function renderClaudeBootstrap(content) {
+    return [
+        "<!-- Generated mirror of AGENTS.md. Interf may rewrite this file. -->",
+        "",
+        content.trimEnd(),
+        "",
+    ].join("\n");
+}
+export function renderBuildPlanAuthoringAgents(options) {
+    return [
+        `# ${options.label} — Build Plan Authoring Shell`,
+        "",
+        "This is an automated Build Plan authoring shell generated by Interf.",
+        "It exists to create one standalone Build Plan package from the source data, requested Artifacts, Context Checks, and evidence requirements in this task.",
+        "",
+        "## Start Here",
+        "",
+        "1. Read `runtime/authoring-context.json` now.",
+        `2. Read \`build-plan/README.md\`, \`build-plan/build-plan.json\`, and \`build-plan/${BUILD_PLAN_SCHEMA_FILE}\` now.`,
+        "3. Read `runtime/source-locator.json` and inspect Source through your own tools when needed.",
+        "4. Use the local native `interf-build-plan-author` skill now.",
+        "",
+        "## Boundaries",
+        "",
+        `- New Build Plan id: \`${options.buildPlanId}\`.`,
+        "- Authoring mode: from scratch.",
+        ...(options.referenceBuildPlanId
+            ? [`- Reference Build Plan id: \`${options.referenceBuildPlanId}\` (context only, not a seed).`]
+            : []),
+        "- Edit only files under `build-plan/`.",
+        "- Do not edit source artifacts.",
+        "- Keep the Build Plan package valid for the current build API and `build-plan.schema.json`.",
+        "- Use kebab-case ids everywhere: stage ids, skill_dir values, Artifact ids, reads/writes values, and package ids. Never use underscores.",
+        "- Treat `checks` from `runtime/authoring-context.json` as user-facing Context Checks: plain-English checks the requested Artifacts must satisfy.",
+        "- Create Context Checks first, then requested Artifacts that back those checks, then deterministic Artifact diagnostics (`checks[]`) under each Artifact.",
+        "- Preserve the file-based Context Graph architecture: `summaries/` for source coverage, `knowledge/` for task-aware navigation/drilldown, and `artifacts/` for task-specific agent handoffs.",
+        "- Artifact handoffs under `artifacts/` are the default downstream agent handoff surface. They must route to original Source refs for exact claims; generated summaries and knowledge notes are not the source of truth.",
+        "- Treat `home.md` as a graph index only, not as the answer surface.",
+        "- For tasks that depend on charts, tables, images, or other visual evidence, requested Artifacts must capture target period, unit, series/legend, axis or table interpretation, exact printed values when available, bounded ranges when not, evidence tier, and source page.",
+        "- Do not let structural diagnostics such as file existence, frontmatter keys, or phrase presence stand in for evidence fidelity. Stage docs and Artifact descriptions must require the semantic fields the agent task needs.",
+        "- If visual evidence has no printed data labels, require a bounded read at source granularity and unresolved-semantics handling instead of pseudo-exact precision.",
+        "- Preserve `backed_by_artifact_ids` and make them match requested Artifact ids.",
+        "- When `artifact_requirements[]` is non-empty, copy every requirement's `id`, `shape`, and `checks[]` exactly into the requested Artifact contract; do not rename or move required Artifacts.",
+        "- Put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks.",
+        "- Use `runtime/authoring-context.json.check_param_contracts` as the exact parameter contract for each check kind.",
+        "- Give every Artifact diagnostic a human-readable `description`; the UI shows that assertion first and uses evaluator details as drilldown.",
+        "- Prefer direct file-reading and search tools over shell commands for routine file inspection.",
+        "- Do not use shell helpers like `cat`, `sed`, `ls`, or `find` when a native read/search tool can inspect the same files.",
+        "",
+        "## Goal",
+        "",
+        "- produce one standalone Build Plan package tuned to the source data, requested Artifacts, and checks in this task",
+        "- replace the neutral scaffold topology with the stage flow this agent task needs",
+        "- define Context Checks, requested Artifacts, and Artifact diagnostics so Interf can show which checks passed, which Artifacts back them, and what evidence or traces support them",
+        "- satisfy every `artifact_requirements[]` entry from `runtime/authoring-context.json` when entries are present",
+        "- otherwise draft requested Artifact contracts from every `requested_artifacts[]` entry; do not ignore or truncate them",
+        "- preserve deterministic stage and requested Artifact contracts",
+        "- stop once the Build Plan edits are complete",
+        "",
+    ].join("\n");
+}
+export function renderBuildPlanAuthoringSkill() {
+    return [
+        "---",
+        "name: interf-build-plan-author",
+        "description: >",
+        "  Native local Build Plan authoring skill for an automated Interf Build Plan draft run.",
+        "---",
+        "",
+        "# Interf Build Plan Authoring",
+        "",
+        "Read `runtime/authoring-context.json` first.",
+        "Then review the neutral Build Plan package scaffold under `build-plan/`, read `runtime/source-locator.json`, and inspect Source through your own tools when needed.",
+        "",
+        "Rules:",
+        "- edit only `build-plan/`",
+        `- keep \`build-plan.json\`, \`${BUILD_PLAN_SCHEMA_FILE}\`, and any changed stage docs aligned`,
+        "- treat `checks` from `runtime/authoring-context.json` as user-facing Context Checks, not deterministic operators",
+        "- create Context Checks first, then requested Artifacts that back them, then deterministic Artifact diagnostics (`checks[]`) under those Artifacts",
+        "- preserve the file-based Context Graph architecture: `summaries/` for source coverage, `knowledge/` for task-aware navigation/drilldown, and `artifacts/` for task-specific agent handoffs",
+        "- make `artifacts/` the downstream agent handoff layer; route to original Source refs for exact claims and do not present generated notes as the source of truth",
+        "- treat `home.md` as a graph index only, not as the answer surface",
+        "- for charts, tables, images, and other visual evidence, require target period, unit, series/legend, axis or table interpretation, exact printed values when available, bounded ranges when not, evidence tier, and source page",
+        "- structural diagnostics are not evidence fidelity; do not treat file existence, frontmatter keys, or phrase presence as proof that a visual/table value was correctly extracted",
+        "- if visual evidence has no printed data labels, preserve a bounded read at source granularity and unresolved-semantics handling instead of pseudo-exact precision",
+        "- preserve `backed_by_artifact_ids` and make them match requested Artifact ids",
+        "- when `artifact_requirements[]` is non-empty, copy every requirement's `id`, `shape`, and `checks[]` exactly into the requested Artifact contract; do not rename or move required Artifacts",
+        "- put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks",
+        "- use only CheckKind values listed in `runtime/authoring-context.json`; do not invent aliases",
+        "- use `runtime/authoring-context.json.check_param_contracts` as the exact parameter contract for each check kind",
+        "- give every Artifact diagnostic a human-readable `description`; the UI shows that assertion first and uses evaluator details as drilldown",
+        "- keep Artifact diagnostics aligned with produced outputs; use stage docs to describe the output contract without requiring exact source-specific phrases in the stage docs",
+        "- satisfy every `artifact_requirements[]` entry from `runtime/authoring-context.json` when entries are present",
+        "- otherwise draft requested Artifact contracts from every `requested_artifacts[]` entry; do not ignore or truncate them",
+        "- design the stage flow from the source data, agent task, and evidence brief",
+        "- use kebab-case ids everywhere: stage ids, skill_dir values, Artifact ids, reads/writes values, and package ids; never use underscores",
+        "- replace the placeholder `prepare` stage unless that exact stage is truly the final Build Plan",
+        "- keep the package standalone; do not introduce runtime inheritance or hidden source-package assumptions",
+        "- do not introduce wikilinks unless the Build Plan also creates the target note by exact basename or explicit relative path",
+        "- respect stage boundaries: do not make structure outputs link to notes or graph routes first created by later stages",
+        "- prefer conservative routing changes over speculative note sprawl",
+        "- prefer direct file-reading and search tools over shell commands for routine file inspection",
+        "- do not use shell helpers like `cat`, `sed`, `ls`, or `find` when a native read/search tool can inspect the same files",
+        "- do not hardcode benchmark expected answers into Build Plan docs",
+        "- do not edit source artifacts",
+        "",
+    ].join("\n");
+}
+export function renderBuildPlanImprovementAgents(contextGraphName, buildPlanId, loopIndex) {
+    return [
+        `# ${contextGraphName} — Build Plan Improvement Shell`,
+        "",
+        "This is an automated Build Plan improvement shell generated by Interf.",
+        "It exists to review failed Build/benchmark runs and edit the Build Plan package for the next variation.",
+        "",
+        "## Start Here",
+        "",
+        "1. Read `runtime/loop-context.json` now.",
+        `2. Read \`build-plan/README.md\`, \`build-plan/build-plan.json\`, and \`build-plan/${BUILD_PLAN_SCHEMA_FILE}\` now.`,
+        "3. Read `build-plan/improve/SKILL.md` now.",
+        "4. Use the local native `interf-build-plan-improver` skill now.",
+        "",
+        "## Boundaries",
+        "",
+        `- Build Plan: \`${buildPlanId}\`.`,
+        `- Improvement loop: ${loopIndex}.`,
+        "- Edit only files under `build-plan/`.",
+        "- Do not edit checks, benchmark specs, source files, or generated context outputs.",
+        "- Review context-graph outputs under `artifacts/context-graph-view/` and benchmark/runtime evidence under `artifacts/`.",
+        "- Keep the Build Plan package valid for the current build API and `build-plan.schema.json`.",
+        "- Put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks.",
+        "",
+        "## Goal",
+        "",
+        "- create a better Build Plan variation for this kind of agent task",
+        "- preserve deterministic context-graph structure",
+        "- stop after the Build Plan edits are complete",
+        "",
+    ].join("\n");
+}
+export function readBuildPlanImprovementDoc(contextGraphPath) {
+    const path = join(improvementBuildPlanDocsPath(contextGraphPath), "SKILL.md");
+    if (!existsSync(path))
+        return null;
+    return readFileSync(path, "utf8").trim();
+}
+export function renderBuildPlanImprovementSkill(buildPlanId, loopIndex, improvementDoc) {
+    return [
+        "---",
+        "name: interf-build-plan-improver",
+        "description: >",
+        "  Native local Build Plan improvement skill for this Interf run.",
+        "  Use it only inside an automated Build Plan improvement shell.",
+        "---",
+        "",
+        `# Interf Build Plan Improvement — ${buildPlanId}`,
+        "",
+        "This local native skill exists for automated Build Plan improvement loops.",
+        "Read `runtime/loop-context.json` first.",
+        "Then review the linked Build Plan package, `artifacts/context-graph-view/`, preserved stage shells, runtime logs, and saved benchmark outputs before editing `build-plan/`.",
+        "",
+        "## Current Loop",
+        "",
+        `- Build Plan: \`${buildPlanId}\``,
+        `- loop index: ${loopIndex}`,
+        "- editable source: `build-plan/improve/SKILL.md`",
+        "",
+        ...(improvementDoc
+            ? [
+                "## Improvement Guidance",
+                "",
+                improvementDoc,
+                "",
+            ]
+            : []),
+    ].join("\n");
+}

package/dist/packages/runtime/agents/lib/shell-workspace.d.ts

@@ -0,0 +1,17 @@
+import type { ExecutionStageLedger, RuntimeStageContract } from "../../build/lib/schema.js";
+import type { NativeStageDefinition } from "./shell-templates.js";
+export interface StageExecutionWorkspaceLogPaths {
+    promptLogPath: string;
+    eventLogPath: string;
+    statusLogPath: string;
+}
+export declare function stageExecutionWorkspaceLogPaths(shellRoot: string, runId: string): StageExecutionWorkspaceLogPaths;
+export declare function writeStageExecutionWorkspaceManifest(options: {
+    contextGraphPath: string;
+    shellRoot: string;
+    buildPlanId: string;
+    stage: Pick<NativeStageDefinition, "id" | "label" | "contractType">;
+    run?: ExecutionStageLedger | null;
+    contract?: RuntimeStageContract | null;
+    logPaths?: StageExecutionWorkspaceLogPaths | null;
+}): void;

package/dist/packages/runtime/agents/lib/shell-workspace.js

@@ -0,0 +1,70 @@
+import { existsSync, readFileSync } from "node:fs";
+import { relative } from "node:path";
+import { writeJsonAtomic } from "../../build/atomic-fs.js";
+import { LOCAL_SKILL_ROOTS, shellEventLogPath, shellPromptLogPath, shellRuntimePath, shellStatusLogPath, shellWorkspaceManifestPath, } from "./shell-paths.js";
+export function stageExecutionWorkspaceLogPaths(shellRoot, runId) {
+    return {
+        promptLogPath: shellPromptLogPath(shellRoot, runId),
+        eventLogPath: shellEventLogPath(shellRoot, runId),
+        statusLogPath: shellStatusLogPath(shellRoot, runId),
+    };
+}
+function shellRelative(shellRoot, path) {
+    return relative(shellRoot, path).replaceAll("\\", "/");
+}
+function contextGraphRelative(contextGraphPath, path) {
+    return relative(contextGraphPath, path).replaceAll("\\", "/");
+}
+function readPathsFile(shellRoot) {
+    const pathsFile = shellRuntimePath(shellRoot, "paths.json");
+    if (!existsSync(pathsFile))
+        return null;
+    try {
+        return JSON.parse(readFileSync(pathsFile, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeStageExecutionWorkspaceManifest(options) {
+    const skillPaths = LOCAL_SKILL_ROOTS.map((root) => `${root}/interf-stage/SKILL.md`);
+    const logPaths = options.logPaths
+        ? {
+            prompt_path: shellRelative(options.shellRoot, options.logPaths.promptLogPath),
+            event_stream_path: shellRelative(options.shellRoot, options.logPaths.eventLogPath),
+            status_path: shellRelative(options.shellRoot, options.logPaths.statusLogPath),
+        }
+        : null;
+    writeJsonAtomic(shellWorkspaceManifestPath(options.shellRoot), {
+        kind: "interf-stage-execution-workspace",
+        version: 1,
+        generated_at: new Date().toISOString(),
+        workspace_type: "stage-execution",
+        root_path: contextGraphRelative(options.contextGraphPath, options.shellRoot),
+        run_id: options.run?.run_id ?? options.contract?.run_id ?? null,
+        build_plan: options.contract?.build_plan.id ?? options.buildPlanId,
+        stage: options.contract?.stage ?? options.stage.id,
+        stage_label: options.contract?.stage_label ?? options.stage.label,
+        contract_type: options.contract?.contract_type ?? options.stage.contractType,
+        instructions: {
+            agents: "AGENTS.md",
+            claude: "CLAUDE.md",
+            skill_paths: skillPaths,
+        },
+        runtime: {
+            contract: "runtime/stage-contract.json",
+            paths: "runtime/paths.json",
+            source_manifest: "runtime/source-manifest.json",
+            source_state: "runtime/source-state.json",
+            stage_inputs: "runtime/stage-inputs.json",
+            verifier: "runtime/check-stage.mjs",
+            stage_evidence: "runtime/stage-evidence.json",
+        },
+        logs: logPaths,
+        artifacts: readPathsFile(options.shellRoot),
+        boundaries: {
+            build_plan: "build-plan",
+            context_graph_linked: false,
+        },
+    });
+}

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

@@ -0,0 +1,63 @@
+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;
+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[];
+}): {
+    rootPath: string;
+    buildPlanBeforePath: string;
+    buildPlanAfterPath: string;
+    promptLogPath: string;
+    eventLogPath: string;
+    statusLogPath: string;
+};
+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;
+};
+export declare function freezeBuildPlanImprovementShell(rootPath: string): string | null;