@interf/compiler 0.22.2 → 0.50.0

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

@@ -0,0 +1,494 @@
+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: source-backed summaries, knowledge notes, entrypoints, 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. Start with `home.md`. It is the primary agent entrypoint for this Context Graph.",
+        "2. Use the local native `interf-query` skill that Interf generated for this Context Graph.",
+        "3. Follow links from `home.md` into `knowledge/`, `summaries/`, `artifacts/`, traces, or Build Plan details.",
+        "4. Use `.interf/runtime/graph-manifest.json` for coverage metrics, stage summaries, entrypoints, and readiness.",
+        "5. 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 output 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 output 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/graph-manifest.json` is the authoritative Context Graph manifest recorded for this build.",
+        "- `.interf/runtime/source-state.json` is a derived projection of the Source Manifest.",
+        `- Requested output 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",
+        "",
+        "- Start from `home.md` before other Context Graph outputs or 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, graph entrypoints, 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. Read `home.md` first; it is the primary agent entrypoint.",
+        `3. Use the requested output contract declared in \`.interf/build-plan/${BUILD_PLAN_SCHEMA_FILE}\` and \`.interf/runtime/graph-manifest.json\` when you need to understand coverage, readiness, or prepared outputs.`,
+        "4. Follow at least one linked `knowledge/` or `summaries/` note when the answer depends on a claim, entity, timeline, comparison, or source-backed fact.",
+        "5. Use `.interf/runtime/source-manifest.json` and note source refs 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 graph resources as the working retrieval surface",
+        "- start from `home.md`; treat entrypoints and generated graph files as routing and source-evidence maps, not as a replacement dataset",
+        "- 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, graph entrypoints, or the recorded Source Manifest",
+        "- record the entrypoint and linked `knowledge/` or `summaries/` notes you used when a trace log is requested",
+        "- 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 output contract; do not present a weak graph output 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 generated graph outputs 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 a replayable stage-execution shell generated by Interf.",
+        "It contains the stage prompt, logs, local agent instructions, skill, contract, inputs, output mounts, and validator for this stage.",
+        "",
+        "## Start Here",
+        "",
+        "1. Read `runtime/stage-contract.json` now.",
+        "2. Read `runtime/project.json` now.",
+        "3. Read `runtime/source-manifest.json`, `runtime/stage-inputs.json`, and `runtime/expected-inputs.json` now.",
+        "4. Read `runtime/paths.json` now.",
+        "5. Use the local native `interf-stage` skill now.",
+        `6. Execute only the current stage: \`${stage.id}\` (${stage.label}).`,
+        "7. Write `runtime/reviewed-inputs.json` before DONE.",
+        "",
+        "## Shell ABI",
+        "",
+        "- `inputs/<artifact-id>/` = read mounts for the current stage.",
+        "- `outputs/<artifact-id>/` = write mounts for the current stage.",
+        "- For file outputs, `runtime/paths.json` points to the exact file path inside those mount roots.",
+        "- `runtime/project.json` = Project id and task intent for this stage.",
+        "- `runtime/source-manifest.json` = authoritative Source inventory for this run.",
+        "- `runtime/source-state.json` = derived projection of manifest source references.",
+        "- `runtime/stage-inputs.json` = exact manifest source references assigned to this stage.",
+        "- `runtime/expected-inputs.json` = required inputs this stage must review, use, or mark missing/blocked/not relevant.",
+        "- `runtime/reviewed-inputs.json` = coverage decisions this stage writes before DONE.",
+        "- `runtime/check-stage.mjs` = shell-local deterministic verifier for the current stage outputs.",
+        "- `runtime/workspace.json` = shell map for retrospective inspection and replay.",
+        "- `logs/` = prompt, event stream, and status log for this agent session.",
+        "- declared output 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 is the runnable workspace for this stage.",
+        "- The context-graph root itself is not linked into this shell.",
+        "- Do not switch into query mode or act like a user-facing assistant.",
+        "- Use `runtime/project.json` and `runtime/stage-contract.json.project.intent` as the task focus whenever this stage writes task-aware summaries, knowledge, entrypoints, or requested outputs.",
+        "- Use `runtime/expected-inputs.json` as the coverage contract. Every required expected input must be reviewed or marked missing, blocked, or not relevant with a reason.",
+        "- Do not modify files under `inputs/` unless the same Artifact is also mounted under `outputs/`.",
+        "",
+        "## Current Stage Outputs",
+        "",
+        `- reads: ${stage.reads.join(", ")}`,
+        `- writes: ${stage.writes.join(", ")}`,
+        "",
+        "## Goal",
+        "",
+        "- complete the current stage",
+        "- honor the deterministic contract",
+        "- write outputs through the declared Artifact mounts",
+        "- write `runtime/reviewed-inputs.json` with one decision per required expected input",
+        "- run `node runtime/check-stage.mjs` and fix failures until it prints `VALID:`",
+        "- stop when the stage is complete",
+        "",
+        "## Reviewed Inputs File",
+        "",
+        "Write this JSON shape at `runtime/reviewed-inputs.json`:",
+        "",
+        "```json",
+        "{",
+        "  \"kind\": \"interf-stage-reviewed-inputs\",",
+        "  \"version\": 1,",
+        "  \"generated_at\": \"2026-01-01T00:00:00.000Z\",",
+        `  \"stage_id\": \"${stage.id}\",`,
+        "  \"reviewed\": [",
+        "    {",
+        "      \"resource_id\": \"copy-one-id-from-runtime-expected-inputs\",",
+        "      \"decision\": \"used\",",
+        "      \"source_refs\": [\"source-or-note-ref\"]",
+        "    }",
+        "  ]",
+        "}",
+        "```",
+        "",
+        "Allowed decisions: `used`, `reviewed`, `missing`, `blocked`, `not-relevant`. Missing, blocked, and not-relevant decisions require a concrete `reason`.",
+        "",
+    ].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/project.json`, `runtime/source-manifest.json`, `runtime/stage-inputs.json`, `runtime/expected-inputs.json`, and `runtime/paths.json`.",
+        "Use the assigned source references and the mounted `inputs/` and `outputs/` requested outputs for this stage.",
+        "Use Project intent and the expected input coverage file when this stage writes task-aware summaries, knowledge, entrypoints, or requested outputs.",
+        "Write `runtime/reviewed-inputs.json` with kind `interf-stage-reviewed-inputs`, this stage id, and one decision per required expected input before DONE.",
+        "Allowed decisions are `used`, `reviewed`, `missing`, `blocked`, and `not-relevant`; missing, blocked, and not-relevant decisions require a concrete `reason`.",
+        "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, Project intent, requested outputs, coverage metrics, 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, requested output ids, reads/writes values, and package ids. Never use underscores.",
+        "- Start from the saved Project intent. Build Plans operationalize that intent into summaries, task-aware knowledge, home.md, task entrypoint notes, StageManifest coverage, and GraphManifest metrics.",
+        "- Treat `checks` from `runtime/authoring-context.json` as optional context, not the primary product surface.",
+        "- Design coverage metrics first: expected Source units, reviewed inputs, produced outputs, entrypoints, and missing/blocked/not-relevant coverage decisions.",
+        "- Preserve the file-based Context Graph architecture: `summaries/` for source coverage, `knowledge/` for task-aware navigation/drilldown, and `artifacts/` for focused task entrypoint notes.",
+        "- `home.md` is the primary downstream agent entrypoint. Notes under `artifacts/` supplement it and route to original Source refs for exact claims.",
+        "- For tasks that depend on charts, tables, images, or other visual evidence, requested outputs 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 output 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 output ids.",
+        "- When `artifact_requirements[]` is non-empty, treat it as the legacy storage field for required requested outputs; copy every requirement's `id`, `shape`, and `checks[]` exactly into the requested output contract; do not rename or move required outputs.",
+        "- Put minimal deterministic validation on requested output `checks[]`; StageManifest and GraphManifest coverage are the primary proof surface.",
+        "- Use `runtime/authoring-context.json.check_param_contracts` as the exact parameter contract for each check kind.",
+        "- Give every deterministic check a human-readable `description`; the UI uses evaluator details only 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, Project intent, requested outputs, and coverage metrics in this task",
+        "- replace the neutral scaffold topology with the stage flow this agent task needs",
+        "- define requested outputs and stage docs so Interf can record StageManifests, GraphManifest primary metrics, evidence, and traces",
+        "- satisfy every `artifact_requirements[]` entry from `runtime/authoring-context.json` when entries are present; this is the legacy storage field for required requested outputs",
+        "- otherwise treat `requested_artifacts[]` as the legacy storage field for requested outputs/entrypoints and draft requested output contracts from every entry; do not ignore or truncate them",
+        "- preserve deterministic stage and requested output 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 optional context, not the primary product surface",
+        "- design coverage metrics first: expected inputs, reviewed inputs, produced outputs, entrypoints, and missing coverage decisions",
+        "- preserve the file-based Context Graph architecture: `summaries/` for source coverage, `knowledge/` for task-aware navigation/drilldown, and `artifacts/` for focused task entrypoint notes",
+        "- make `home.md` the primary downstream agent entrypoint; route to original Source refs for exact claims and do not present generated notes as the source of truth",
+        "- 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` in the root Build Plan `brief` and make them match requested output ids",
+        "- keep `purpose` limited to its documented fields; never add `purpose.brief` or other ad-hoc nested promise fields",
+        "- when `artifact_requirements[]` is non-empty, treat it as the legacy storage field for required requested outputs; copy every requirement's `id`, `shape`, and `checks[]` exactly into the requested output contract; do not rename or move required outputs",
+        "- keep deterministic validation on requested output `checks[]` minimal; StageManifest and GraphManifest coverage are the primary proof surface",
+        "- do not edit the root `brief`; the service restores it from Project intent, requested outputs, diagnostic checks, and Source context after every edit attempt",
+        "- 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 deterministic check a human-readable `description`; the UI uses evaluator details only as drilldown",
+        "- keep deterministic checks aligned with produced outputs; use stage docs and StageManifest coverage 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; this is the legacy storage field for required requested outputs",
+        "- otherwise treat `requested_artifacts[]` as the legacy storage field for requested outputs/entrypoints and draft requested output contracts from every 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, requested output 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 `home.md`, `knowledge/`, `summaries/`, `.interf/runtime/graph-manifest.json`, stage manifests, and benchmark/runtime evidence under `artifacts/`.",
+        "- Keep the Build Plan package valid for the current build API and `build-plan.schema.json`.",
+        "- Keep deterministic validation on Artifact `checks[]` minimal and aligned with produced outputs; use stage docs and manifests for coverage proof.",
+        "",
+        "## 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,
+        },
+    });
+}