@interf/compiler 0.3.3 → 0.4.0

package/dist/lib/agent-shells.js

@@ -1,16 +1,179 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, symlinkSync, } from "node:fs";
-import { dirname, join } from "node:path";
+import { cpSync, copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, symlinkSync, } from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
+import { CHART_APPROXIMATION_NOTES } from "./chart-guidance.js";
 import { WORKFLOW_PACKAGE_DIR } from "./interf-detect.js";
-import { renderWorkspaceAgents, renderWorkspaceQuerySkill, } from "./workspace-docs.js";
 import { ensureWorkspaceZoneTargets, readWorkspaceSchemaFile, workspaceZoneAbsolutePath, } from "./workspace-schema.js";
+import { stageExecutionShellsRoot, workflowImprovementLoopRoot, workflowPackagePathForWorkspace, workspaceInterfConfigPath, workspaceRuntimeRoot, } from "./workspace-paths.js";
+import { resolveWorkflowImprovementReviewSourcePaths } from "./workflow-review-paths.js";
 const LOCAL_SKILL_ROOTS = [
     ".claude/skills",
     ".codex/skills",
     ".agents/skills",
     ".cursor/skills",
 ];
-function stageShellsRoot(workspacePath) {
-    return join(workspacePath, ".interf", "execution-shells");
+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;
+}
+function workspaceQuerySkillSourcePath(workspacePath) {
+    return join(workflowPackagePathForWorkspace(workspacePath), "use", "query", "SKILL.md");
+}
+export function renderWorkspaceAgents(name, workflowId, about, options = {}) {
+    const workflowOriginSelected = options.workflowOriginSelected ?? workflowId;
+    const workflowLocalDraft = options.workflowLocalDraft === true;
+    return [
+        `# ${name}`,
+        "",
+        "This is a compiled workspace built by Interf Compiler.",
+        "It is a file-based layer on top of the raw files, built for agents to navigate, retrieve evidence, and answer more accurately.",
+        "",
+        ...(about
+            ? [
+                `About: ${about}`,
+                "",
+            ]
+            : []),
+        "## How to use this workspace",
+        "",
+        "1. Use the local native `interf-query` skill that Interf Compiler generated for this workspace.",
+        "2. Start from `home.md`, then use `knowledge/` and `summaries/`.",
+        "3. Use `raw/` when you need direct quotes, exact chart values, table lookups, or verification.",
+        "",
+        "## How this workspace works",
+        "",
+        "- `.interf/interf.json` points to the workspace-local `raw/` snapshot via `source.path` and back to the dataset control plane via `source.control_path`.",
+        `- Workflow seed: \`${workflowOriginSelected}\`.`,
+        ...(workflowLocalDraft
+            ? ["- This workspace now carries a local workflow draft improved from that seed. Recompiling this workspace reuses the local `.interf/workflow/` package."]
+            : []),
+        `- Active local workflow id: \`${workflowId}\`.`,
+        "- `.interf/workflow/` is the local editable method package for this workspace.",
+        "- `.interf/workflow/workspace.schema.json` is the deterministic output shape for this workspace.",
+        "- `.interf/workflow/improve/` is the editable source for workflow-improvement loops.",
+        "- `.interf/workflow/use/query/` is the editable source for the generated native query shell.",
+        "- `.interf/workflow/compile/stages/` defines stage-specific docs that Interf Compiler 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/`.",
+        "- `raw/` contains the workspace-local raw snapshot used for evidence and verification.",
+        "- `summaries/` contains per-file evidence objects.",
+        "- `knowledge/` contains the cross-file knowledge layer and navigation structure.",
+        "- `home.md` is the starting note.",
+        "- `.interf/runtime/` holds CLI-owned runtime artifacts.",
+        "- `.interf/tests/` holds saved raw-vs-compiled test comparisons for this workspace.",
+        "- `.interf/tests/targets/` holds detailed raw and compiled target runs plus preserved test sandboxes.",
+        "",
+        "## Manual query rules",
+        "",
+        "- Prefer `home.md`, `knowledge/`, and `summaries/` before `raw/`.",
+        "- Use the generated native `interf-query` skill for manual querying. The editable source lives at `.interf/workflow/use/query/SKILL.md`.",
+        "- Treat `.interf/` as method/runtime metadata, not answer evidence, unless explicitly asked to inspect workflow or test history.",
+        "- Use `raw/` for quotes, verification, ambiguity, or evidence the compiled layer does not expose well.",
+        "- If the compiled layer already contains a bounded chart-derived read for the exact metric and year the user asked about, answer from that compiled read first.",
+        "- If exact chart, table, or image-derived evidence matters, inspect the raw source and say whether the answer was text-derived, table-derived, or chart-derived.",
+        "",
+        "## Commands",
+        "",
+        "```",
+        "interf compile            build this compiled workspace",
+        "interf test               run saved truth checks against this workspace",
+        "interf verify summarize   verify summary coverage",
+        "interf verify structure   verify cross-file structure outputs",
+        "interf verify compile     verify compile outputs",
+        "interf status             show deterministic health",
+        "```",
+        "",
+        "## Rules",
+        "",
+        "- Do not modify files under `raw/`.",
+        "- Treat compiled notes as working retrieval artifacts, not final truth.",
+        "- When confidence is low, verify against `raw/` before answering strongly.",
+        "",
+    ].join("\n");
+}
+export function renderWorkspaceQuerySkill() {
+    const chartNotes = CHART_APPROXIMATION_NOTES.map((note) => `- ${note.toLowerCase()}`);
+    return [
+        "# Manual Query Loop",
+        "",
+        "This file is the editable authoring source for the generated native local `interf-query` skill.",
+        "",
+        "Default loop:",
+        "1. Read `home.md` first.",
+        "2. Browse `knowledge/` before `raw/`.",
+        "3. Use `summaries/` for source-grounded evidence.",
+        "4. Use `raw/` for direct quotes, verification, exact table lookups, and cases where the compiled layer is missing or ambiguous.",
+        "",
+        "Answering rule:",
+        "- do not modify files under `raw/`",
+        "- when a number is chart-derived, say that explicitly",
+        "- if the compiled layer already contains a bounded chart-derived read for the exact metric and year, answer from that compiled read first",
+        "- use `raw/` to confirm source page, metric family, or provenance, not to replace a good compiled bounded read with a second incompatible range",
+        "- when the compiled layer preserves a bounded chart-derived range, keep that bounded range in the answer instead of collapsing it to a midpoint or pseudo-exact single value",
+        "- when reading charts, verify you are on the correct metric family and year before answering",
+        "- keep historical annual charts separate from current-quarter snapshots, sector splits, or nearby lookalike panels",
+        ...chartNotes,
+        "- if multiple compiled notes mention the same chart read, keep the answer consistent with the most focused workspace note instead of synthesizing a new midpoint or shifted band",
+        "- when the compiled layer is insufficient, verify in `raw/` and then answer",
+        "",
+        "You can edit this file to bias manual question-answering behavior for this workspace.",
+        "",
+    ].join("\n");
+}
+function renderRawTestAgents() {
+    const chartNotes = CHART_APPROXIMATION_NOTES.map((note) => `- ${note}`);
+    return [
+        "# Raw Test Shell",
+        "",
+        "This is an isolated raw-files test shell generated by Interf Compiler.",
+        "There is no compiled workspace 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 only from `raw/`.",
+        "",
+        "## Rules",
+        "",
+        "- Answer only from the files under `raw/`.",
+        "- There is no compiled workspace here, so do not assume `home.md`, `knowledge/`, or `summaries/` exist.",
+        "- Do not treat hidden runtime files or test artifacts as evidence.",
+        ...chartNotes,
+        "- Write the requested answer and trace files, then stop.",
+        "",
+    ].join("\n");
+}
+function renderRawTestQuerySkill() {
+    const chartNotes = CHART_APPROXIMATION_NOTES.map((note, index) => `${index + 3}. ${note}`);
+    return [
+        "---",
+        "name: interf-query",
+        "description: >",
+        "  Native local query skill for an Interf raw test shell. Use it only",
+        "  to answer baseline questions directly from `raw/`.",
+        "---",
+        "",
+        "# Interf Raw Test Query",
+        "",
+        "This is the native local query skill for an isolated raw-files test shell.",
+        "",
+        "Loop:",
+        "1. Read `raw/` directly.",
+        "2. Verify exact claims against the raw files before answering strongly.",
+        ...chartNotes,
+        "8. Do not rely on compiled workspace artifacts because they do not exist in this shell.",
+        "",
+    ].join("\n");
+}
+function readWorkspaceQuerySkillSource(workspacePath) {
+    const filePath = workspaceQuerySkillSourcePath(workspacePath);
+    if (!existsSync(filePath)) {
+        throw new Error(`Missing workspace query skill source at ${filePath}. Interf compile runs the workspace-local workflow package directly, so reseed or repair this workspace instead of auto-healing query docs.`);
+    }
+    return readFileSync(filePath, "utf8").trim();
 }
 function stageShellWorkflowRoot(shellRoot) {
     return join(shellRoot, WORKFLOW_PACKAGE_DIR);
@@ -21,6 +184,19 @@ function shellInputZonePath(shellRoot, zoneId) {
 function shellOutputZonePath(shellRoot, zoneId) {
     return join(shellRoot, "outputs", zoneId);
 }
+function shellZoneAliasMountPath(shellRoot, zone, mountKind) {
+    const mountRoot = mountKind === "inputs"
+        ? shellInputZonePath(shellRoot, zone.id)
+        : shellOutputZonePath(shellRoot, zone.id);
+    return zone.kind === "file"
+        ? join(mountRoot, basename(zone.path))
+        : mountRoot;
+}
+function describeShellZoneAliasMountPath(zone, mountKind) {
+    return zone.kind === "file"
+        ? `${mountKind}/${zone.id}/${basename(zone.path)}`
+        : `${mountKind}/${zone.id}`;
+}
 function shellRuntimePath(shellRoot, relativePath) {
     return join(shellRoot, "runtime", relativePath);
 }
@@ -44,10 +220,15 @@ function linkPath(targetPath, linkPathname) {
     mkdirSync(dirname(linkPathname), { recursive: true });
     symlinkSync(targetPath, linkPathname);
 }
+function linkRelativePath(targetPath, linkPathname) {
+    mkdirSync(dirname(linkPathname), { recursive: true });
+    symlinkSync(relative(dirname(linkPathname), targetPath), linkPathname);
+}
 function loadWorkspaceSchema(workspacePath) {
-    const schema = readWorkspaceSchemaFile(join(workspacePath, WORKFLOW_PACKAGE_DIR));
+    const workflowRoot = workflowPackagePathForWorkspace(workspacePath);
+    const schema = readWorkspaceSchemaFile(workflowRoot);
     if (!schema) {
-        throw new Error(`Missing workflow workspace schema at ${join(workspacePath, WORKFLOW_PACKAGE_DIR, "workspace.schema.json")}`);
+        throw new Error(`Missing workflow workspace schema at ${join(workflowRoot, "workspace.schema.json")}`);
     }
     return schema;
 }
@@ -62,26 +243,26 @@ function zoneOrThrow(zones, zoneId) {
     return zone;
 }
 function ensureWorkspaceExecutionSurface(workspacePath) {
-    mkdirSync(join(workspacePath, ".interf"), { recursive: true });
-    mkdirSync(join(workspacePath, WORKFLOW_PACKAGE_DIR), { recursive: true });
+    mkdirSync(workspaceRuntimeRoot(workspacePath), { recursive: true });
+    mkdirSync(workflowPackagePathForWorkspace(workspacePath), { recursive: true });
     const schema = loadWorkspaceSchema(workspacePath);
     ensureWorkspaceZoneTargets(workspacePath, schema);
     return schema;
 }
 function readStageMethodDoc(workspacePath, stage) {
-    const path = join(workspacePath, WORKFLOW_PACKAGE_DIR, "compile", "stages", stage.skillDir, "SKILL.md");
+    const path = join(workflowPackagePathForWorkspace(workspacePath), "compile", "stages", stage.skillDir, "SKILL.md");
     if (!existsSync(path))
         return null;
     return readFileSync(path, "utf8").trim();
 }
 function stageWorkflowDocsPath(workspacePath, stage) {
-    return join(workspacePath, WORKFLOW_PACKAGE_DIR, "compile", "stages", stage.skillDir);
+    return join(workflowPackagePathForWorkspace(workspacePath), "compile", "stages", stage.skillDir);
 }
 function renderStageExecutionAgents(workspaceName, workflowId, stage) {
     return [
         `# ${workspaceName} — ${stage.label} Execution Shell`,
         "",
-        "This is an ephemeral Interf stage-execution shell.",
+        "This is an ephemeral stage-execution shell generated by Interf Compiler.",
         "It is for automated pipeline execution only, not for manual querying.",
         "",
         "## Start Here",
@@ -95,7 +276,8 @@ function renderStageExecutionAgents(workspaceName, workflowId, stage) {
         "",
         "- `inputs/<zone-id>/` = read mounts for the current stage.",
         "- `outputs/<zone-id>/` = write mounts for the current stage.",
-        "- schema-declared workspace paths are also projected at the shell root so workflow-relative contract paths stay valid.",
+        "- For file zones, `runtime/paths.json` points to the exact file path inside those mount roots.",
+        "- declared workspace zone paths are also projected at the shell root so workflow-relative contract paths stay valid.",
         "- `runtime/` = stage contract and machine-readable path map for this shell.",
         "- `workflow/` = workflow metadata, workspace schema, and docs for the current stage only.",
         "",
@@ -127,13 +309,13 @@ function renderStageExecutionSkill(stage, stageMethodDoc) {
         "---",
         "name: interf-stage",
         "description: >",
-        `  Native local execution skill for the ${stage.label} stage in this Interf`,
-        "  compile run. Use it only inside an automated stage execution shell.",
+        `  Native local execution skill for the ${stage.label} stage in this`,
+        "  Interf Compiler run. Use it only inside an automated stage execution shell.",
         "---",
         "",
-        `# Interf Stage Execution — ${stage.label}`,
+        `# Interf Compiler Stage Execution — ${stage.label}`,
         "",
-        "This local native skill exists for automated Interf stage execution.",
+        "This local native skill exists for automated Interf Compiler stage execution.",
         "Read `runtime/stage-contract.json` first.",
         "Then read `runtime/paths.json` and use the mounted `inputs/` and `outputs/` zones for this stage.",
         "Do not switch into manual query mode.",
@@ -157,50 +339,52 @@ function renderStageExecutionSkill(stage, stageMethodDoc) {
             : []),
     ].join("\n");
 }
-function renderWorkspaceQueryNativeSkill() {
+function renderWorkspaceQueryNativeSkill(querySkillContent) {
     return [
         "---",
         "name: interf-query",
         "description: >",
-        "  Native local query skill for this Interf compiled workspace. Use it for",
-        "  manual questions against the compiled workspace and its raw fallback.",
+        "  Native local query skill for this compiled workspace built by Interf",
+        "  Compiler. Use it for manual questions against the compiled workspace and",
+        "  its raw fallback.",
         "---",
         "",
-        "# Interf Query",
+        "# Interf Compiler Query",
         "",
-        "This is the native local query skill for an Interf compiled workspace.",
+        "This is the native local query skill for a compiled workspace built by Interf Compiler.",
         "Use it when reading this workspace manually.",
-        "Editable source: `workflow/use/query/SKILL.md`.",
+        "Editable source: `.interf/workflow/use/query/SKILL.md`.",
         "",
-        renderWorkspaceQuerySkill().trim(),
+        querySkillContent.trim(),
         "",
     ].join("\n");
 }
-function syncWorkspaceNativeQuerySkillCopies(workspacePath) {
-    return writeNativeSkillCopies(workspacePath, "interf-query", renderWorkspaceQueryNativeSkill());
-}
 function projectWorkflowMetadata(workspacePath, shellRoot, stage) {
-    const workflowRoot = stageShellWorkflowRoot(shellRoot);
-    mkdirSync(join(workflowRoot, "compile", "stages"), { recursive: true });
-    const workflowJsonPath = join(workspacePath, WORKFLOW_PACKAGE_DIR, "workflow.json");
+    const shellWorkflowRoot = stageShellWorkflowRoot(shellRoot);
+    mkdirSync(join(shellWorkflowRoot, "compile", "stages"), { recursive: true });
+    const workspaceWorkflowRoot = workflowPackagePathForWorkspace(workspacePath);
+    const workflowJsonPath = join(workspaceWorkflowRoot, "workflow.json");
     if (existsSync(workflowJsonPath)) {
-        linkPath(workflowJsonPath, join(workflowRoot, "workflow.json"));
+        linkPath(workflowJsonPath, join(shellWorkflowRoot, "workflow.json"));
     }
-    const workspaceSchemaPath = join(workspacePath, WORKFLOW_PACKAGE_DIR, "workspace.schema.json");
+    const workspaceSchemaPath = join(workspaceWorkflowRoot, "workspace.schema.json");
     if (existsSync(workspaceSchemaPath)) {
-        linkPath(workspaceSchemaPath, join(workflowRoot, "workspace.schema.json"));
+        linkPath(workspaceSchemaPath, join(shellWorkflowRoot, "workspace.schema.json"));
     }
-    const readmePath = join(workspacePath, WORKFLOW_PACKAGE_DIR, "README.md");
+    const readmePath = join(workspaceWorkflowRoot, "README.md");
     if (existsSync(readmePath)) {
-        linkPath(readmePath, join(workflowRoot, "README.md"));
+        linkPath(readmePath, join(shellWorkflowRoot, "README.md"));
     }
     const stageDocsPath = stageWorkflowDocsPath(workspacePath, stage);
     if (existsSync(stageDocsPath)) {
-        linkPath(stageDocsPath, join(workflowRoot, "compile", "stages", stage.skillDir));
+        linkPath(stageDocsPath, join(shellWorkflowRoot, "compile", "stages", stage.skillDir));
     }
 }
-function projectWorkspaceSchemaZones(workspacePath, shellRoot, schema) {
+function projectWorkspaceSchemaZones(workspacePath, shellRoot, schema, zoneIds) {
+    const allowedZoneIds = zoneIds ? new Set(zoneIds) : null;
     for (const zone of schema.zones) {
+        if (allowedZoneIds && !allowedZoneIds.has(zone.id))
+            continue;
         linkPath(workspaceZoneAbsolutePath(workspacePath, zone), join(shellRoot, zone.path));
     }
 }
@@ -212,8 +396,12 @@ function buildStageZoneMounts(workspacePath, shellRoot, stage, schema) {
             zone_id: zone.id,
             workspace_path: zone.path,
             shell_root_path: zone.path,
-            input_mount_path: stage.reads.includes(zoneId) ? `inputs/${zone.id}` : null,
-            output_mount_path: stage.writes.includes(zoneId) ? `outputs/${zone.id}` : null,
+            input_mount_path: stage.reads.includes(zoneId)
+                ? describeShellZoneAliasMountPath(zone, "inputs")
+                : null,
+            output_mount_path: stage.writes.includes(zoneId)
+                ? describeShellZoneAliasMountPath(zone, "outputs")
+                : null,
         };
     };
     return {
@@ -227,10 +415,10 @@ function projectStageZoneMountAliases(workspacePath, shellRoot, stage, schema) {
         const zone = zoneOrThrow(zones, zoneId);
         const targetPath = workspaceZoneAbsolutePath(workspacePath, zone);
         if (stage.reads.includes(zoneId)) {
-            linkPath(targetPath, shellInputZonePath(shellRoot, zoneId));
+            linkPath(targetPath, shellZoneAliasMountPath(shellRoot, zone, "inputs"));
         }
         if (stage.writes.includes(zoneId)) {
-            linkPath(targetPath, shellOutputZonePath(shellRoot, zoneId));
+            linkPath(targetPath, shellZoneAliasMountPath(shellRoot, zone, "outputs"));
         }
     }
 }
@@ -245,50 +433,326 @@ function writeExecutionShellPathsFile(shellRoot, workflowId, stage, mounts) {
     };
     writeFileSync(shellRuntimePath(shellRoot, "paths.json"), `${JSON.stringify(paths, null, 2)}\n`);
 }
+export function syncStageExecutionShellWrites(workspacePath, shellRoot, stage) {
+    const schema = ensureWorkspaceExecutionSurface(workspacePath);
+    const zones = zoneMap(schema);
+    for (const zoneId of new Set(stage.writes)) {
+        const zone = zoneOrThrow(zones, zoneId);
+        const shellZonePath = join(shellRoot, zone.path);
+        if (!existsSync(shellZonePath))
+            continue;
+        const shellZoneStat = lstatSync(shellZonePath);
+        if (shellZoneStat.isSymbolicLink())
+            continue;
+        const workspaceZonePath = workspaceZoneAbsolutePath(workspacePath, zone);
+        if (shellZoneStat.isDirectory()) {
+            rmSync(workspaceZonePath, { recursive: true, force: true });
+            mkdirSync(dirname(workspaceZonePath), { recursive: true });
+            cpSync(shellZonePath, workspaceZonePath, {
+                recursive: true,
+                force: true,
+            });
+            continue;
+        }
+        mkdirSync(dirname(workspaceZonePath), { recursive: true });
+        copyFileSync(shellZonePath, workspaceZonePath);
+    }
+}
+function preservedShellManifestPath(rootPath) {
+    return shellRuntimePath(rootPath, "preserved-shell.json");
+}
+function shouldSkipFrozenStageShellRelativePath(relativePath) {
+    const normalized = relativePath.replaceAll("\\", "/");
+    return normalized === "execution-shells" ||
+        normalized.endsWith("/execution-shells") ||
+        normalized.includes("/execution-shells/") ||
+        normalized === "improvement-loops" ||
+        normalized.endsWith("/improvement-loops") ||
+        normalized.includes("/improvement-loops/");
+}
+function copyResolvedTree(options) {
+    const relativePath = options.relativePath ?? "";
+    if (options.shellType === "stage-execution" && shouldSkipFrozenStageShellRelativePath(relativePath)) {
+        return { materializedSymlinks: 0 };
+    }
+    const stat = lstatSync(options.sourcePath);
+    if (stat.isSymbolicLink()) {
+        const realTarget = realpathSync(options.sourcePath);
+        const realStat = statSync(realTarget);
+        if (realStat.isDirectory()) {
+            const mappedTarget = options.materializedRealPaths?.get(realTarget);
+            if (mappedTarget) {
+                linkRelativePath(mappedTarget, options.targetPath);
+                return { materializedSymlinks: 1 };
+            }
+            return {
+                materializedSymlinks: 1 + copyResolvedTree({
+                    sourcePath: realTarget,
+                    targetPath: options.targetPath,
+                    shellType: options.shellType,
+                    relativePath,
+                    activeRealPaths: options.activeRealPaths,
+                    materializedRealPaths: options.materializedRealPaths,
+                }).materializedSymlinks,
+            };
+        }
+        mkdirSync(dirname(options.targetPath), { recursive: true });
+        copyFileSync(realTarget, options.targetPath);
+        return { materializedSymlinks: 1 };
+    }
+    if (stat.isDirectory()) {
+        const realSource = realpathSync(options.sourcePath);
+        const mappedTarget = options.materializedRealPaths?.get(realSource);
+        if (mappedTarget && mappedTarget !== options.targetPath) {
+            linkRelativePath(mappedTarget, options.targetPath);
+            return { materializedSymlinks: 0 };
+        }
+        const nextRealPaths = new Set([...(options.activeRealPaths ?? []), realSource]);
+        const nextMaterializedRealPaths = new Map(options.materializedRealPaths ?? []);
+        nextMaterializedRealPaths.set(realSource, options.targetPath);
+        mkdirSync(options.targetPath, { recursive: true });
+        let materializedSymlinks = 0;
+        for (const entry of readdirSync(options.sourcePath)) {
+            const childRelativePath = relativePath.length > 0 ? `${relativePath}/${entry}` : entry;
+            const copied = copyResolvedTree({
+                sourcePath: join(options.sourcePath, entry),
+                targetPath: join(options.targetPath, entry),
+                shellType: options.shellType,
+                relativePath: childRelativePath,
+                activeRealPaths: nextRealPaths,
+                materializedRealPaths: nextMaterializedRealPaths,
+            });
+            materializedSymlinks += copied.materializedSymlinks;
+        }
+        return { materializedSymlinks };
+    }
+    mkdirSync(dirname(options.targetPath), { recursive: true });
+    copyFileSync(options.sourcePath, options.targetPath);
+    return { materializedSymlinks: 0 };
+}
+function freezePreservedShell(rootPath, shellType) {
+    if (!existsSync(rootPath))
+        return null;
+    const manifestPath = preservedShellManifestPath(rootPath);
+    if (existsSync(manifestPath))
+        return manifestPath;
+    const tempRoot = `${rootPath}.frozen-${Date.now().toString(36)}`;
+    const copied = copyResolvedTree({
+        sourcePath: rootPath,
+        targetPath: tempRoot,
+        shellType,
+    });
+    const manifest = {
+        kind: "interf-preserved-shell",
+        version: 1,
+        shell_type: shellType,
+        generated_at: new Date().toISOString(),
+        root_path: rootPath,
+        materialized_symlinks: copied.materializedSymlinks,
+    };
+    writeFileSync(preservedShellManifestPath(tempRoot), `${JSON.stringify(manifest, null, 2)}\n`);
+    rmSync(rootPath, { recursive: true, force: true });
+    renameSync(tempRoot, rootPath);
+    return manifestPath;
+}
 export function renderClaudeBootstrap(content) {
     return [
-        "<!-- Generated from AGENTS.md. Edit AGENTS.md; Interf will rewrite this file. -->",
+        "<!-- Generated compatibility mirror of AGENTS.md. Interf Compiler may rewrite this file. -->",
         "",
         content.trimEnd(),
         "",
     ].join("\n");
 }
+function improvementWorkflowDocsPath(workspacePath) {
+    return join(workflowPackagePathForWorkspace(workspacePath), "improve");
+}
+function renderWorkflowImprovementAgents(workspaceName, workflowId, loopIndex) {
+    return [
+        `# ${workspaceName} — Workflow Improvement Shell`,
+        "",
+        "This is an automated workflow-improvement shell generated by Interf Compiler.",
+        "It exists to review failed compile/test runs and edit the workflow package for the next variation.",
+        "",
+        "## Start Here",
+        "",
+        "1. Read `runtime/loop-context.json` now.",
+        "2. Read `workflow/README.md`, `workflow/workflow.json`, and `workflow/workspace.schema.json` now.",
+        "3. Read `workflow/improve/SKILL.md` now.",
+        "4. Use the local native `interf-workflow-improver` skill now.",
+        "",
+        "## Boundaries",
+        "",
+        `- Workflow: \`${workflowId}\`.`,
+        `- Improvement loop: ${loopIndex}.`,
+        "- Edit only files under `workflow/`.",
+        "- Do not edit truth checks, test specs, raw dataset files, or generated workspace outputs.",
+        "- Review compiled outputs under `artifacts/workspace-view/` and test/runtime evidence under `artifacts/`.",
+        "- Keep the workflow valid for the current compiler API and workspace schema.",
+        "",
+        "## Goal",
+        "",
+        "- create a better workflow variation for this dataset",
+        "- preserve deterministic workspace structure",
+        "- stop after the workflow edits are complete",
+        "",
+    ].join("\n");
+}
+function readWorkflowImprovementDoc(workspacePath) {
+    const path = join(improvementWorkflowDocsPath(workspacePath), "SKILL.md");
+    if (!existsSync(path))
+        return null;
+    return readFileSync(path, "utf8").trim();
+}
+function renderWorkflowImprovementSkill(workflowId, loopIndex, improvementDoc) {
+    return [
+        "---",
+        "name: interf-workflow-improver",
+        "description: >",
+        "  Native local workflow-improvement skill for this Interf Compiler run.",
+        "  Use it only inside an automated workflow-improvement shell.",
+        "---",
+        "",
+        `# Interf Compiler Workflow Improvement — ${workflowId}`,
+        "",
+        "This local native skill exists for automated workflow-improvement loops.",
+        "Read `runtime/loop-context.json` first.",
+        "Then review the linked workflow package, `artifacts/workspace-view/`, preserved stage shells, runtime logs, and saved test outputs before editing `workflow/`.",
+        "",
+        "## Current Loop",
+        "",
+        `- workflow: \`${workflowId}\``,
+        `- loop index: ${loopIndex}`,
+        "- editable source: `workflow/improve/SKILL.md`",
+        "",
+        ...(improvementDoc
+            ? [
+                "## Improvement Method",
+                "",
+                improvementDoc,
+                "",
+            ]
+            : []),
+    ].join("\n");
+}
+function projectWorkspaceReviewArtifactsSnapshot(workspacePath, shellRoot, schema) {
+    const workspaceViewRoot = join(shellRoot, "artifacts", "workspace-view");
+    mkdirSync(workspaceViewRoot, { recursive: true });
+    for (const zone of schema.zones) {
+        if (zone.kind === "runtime" || zone.path === "raw")
+            continue;
+        const sourcePath = workspaceZoneAbsolutePath(workspacePath, zone);
+        if (!existsSync(sourcePath))
+            continue;
+        copyResolvedTree({
+            sourcePath,
+            targetPath: join(workspaceViewRoot, zone.path),
+            shellType: "workflow-improvement",
+        });
+    }
+}
+function linkIfExists(targetPath, linkPathname) {
+    if (!existsSync(targetPath))
+        return;
+    linkPath(targetPath, linkPathname);
+}
+function copyIfExists(sourcePath, targetPath, shellType) {
+    if (!existsSync(sourcePath))
+        return;
+    copyResolvedTree({
+        sourcePath,
+        targetPath,
+        shellType,
+    });
+}
+function projectWorkspaceRuntimeArtifacts(workspacePath, shellRoot) {
+    const runtimeTarget = join(shellRoot, "artifacts", "workspace-runtime");
+    mkdirSync(runtimeTarget, { recursive: true });
+    const runtimeRoot = workspaceRuntimeRoot(workspacePath);
+    const artifactNames = [
+        "run.json",
+        "run-history.jsonl",
+        "state.json",
+        "health.json",
+        "view-spec.json",
+        "raw-snapshot.json",
+        "logs",
+    ];
+    for (const artifactName of artifactNames) {
+        copyIfExists(join(runtimeRoot, artifactName), join(runtimeTarget, artifactName), "workflow-improvement");
+    }
+}
 export function pruneStageExecutionShells(workspacePath) {
-    rmSync(stageShellsRoot(workspacePath), { recursive: true, force: true });
+    rmSync(stageExecutionShellsRoot(workspacePath), { recursive: true, force: true });
 }
-export function projectWorkspaceQueryShell(workspacePath, workspaceName, workflowId, about) {
-    const agentsContent = renderWorkspaceAgents(workspaceName, workflowId, about);
-    const querySkillContent = renderWorkspaceQuerySkill();
-    let changed = false;
-    changed = writeIfChanged(join(workspacePath, "AGENTS.md"), agentsContent) || changed;
-    changed =
-        writeIfChanged(join(workspacePath, "CLAUDE.md"), renderClaudeBootstrap(agentsContent)) || changed;
-    const querySkillPath = join(workspacePath, WORKFLOW_PACKAGE_DIR, "use", "query", "SKILL.md");
-    mkdirSync(dirname(querySkillPath), { recursive: true });
-    changed = writeIfChanged(querySkillPath, querySkillContent) || changed;
-    changed = syncWorkspaceNativeQuerySkillCopies(workspacePath) || changed;
-    return changed;
+export function projectWorkspaceQueryShell(workspacePath, workspaceName, workflowId, about, options) {
+    const agentsContent = renderWorkspaceAgents(workspaceName, workflowId, about, options);
+    const querySkillContent = readWorkspaceQuerySkillSource(workspacePath);
+    return writeNativeAgentSurface(workspacePath, agentsContent, "interf-query", renderWorkspaceQueryNativeSkill(querySkillContent));
+}
+export function projectRawTestQueryShell(rootPath) {
+    return writeNativeAgentSurface(rootPath, renderRawTestAgents(), "interf-query", renderRawTestQuerySkill());
 }
 export function createStageExecutionShell(workspacePath, workspaceName, workflowId, stage) {
     const schema = ensureWorkspaceExecutionSurface(workspacePath);
-    const shellsRoot = stageShellsRoot(workspacePath);
+    const shellsRoot = stageExecutionShellsRoot(workspacePath);
     const shellRoot = join(shellsRoot, `${stage.id}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`);
     mkdirSync(shellRoot, { recursive: true });
     mkdirSync(join(shellRoot, "runtime"), { recursive: true });
     mkdirSync(join(shellRoot, "inputs"), { recursive: true });
     mkdirSync(join(shellRoot, "outputs"), { recursive: true });
-    linkPath(join(workspacePath, "interf.json"), join(shellRoot, "interf.json"));
-    linkPath(join(workspacePath, ".interf", "stage-contract.json"), shellRuntimePath(shellRoot, "stage-contract.json"));
-    projectWorkspaceSchemaZones(workspacePath, shellRoot, schema);
+    linkPath(workspaceInterfConfigPath(workspacePath), join(shellRoot, "interf.json"));
+    linkPath(join(workspaceRuntimeRoot(workspacePath), "stage-contract.json"), shellRuntimePath(shellRoot, "stage-contract.json"));
+    projectWorkspaceSchemaZones(workspacePath, shellRoot, schema, new Set([...stage.reads, ...stage.writes]));
     projectWorkflowMetadata(workspacePath, shellRoot, stage);
     projectStageZoneMountAliases(workspacePath, shellRoot, stage, schema);
     writeExecutionShellPathsFile(shellRoot, workflowId, stage, buildStageZoneMounts(workspacePath, shellRoot, stage, schema));
     const agentsContent = renderStageExecutionAgents(workspaceName, workflowId, stage);
-    writeFileSync(join(shellRoot, "AGENTS.md"), `${agentsContent}\n`);
-    writeFileSync(join(shellRoot, "CLAUDE.md"), renderClaudeBootstrap(agentsContent));
-    writeNativeSkillCopies(shellRoot, "interf-stage", renderStageExecutionSkill(stage, readStageMethodDoc(workspacePath, stage)));
+    writeNativeAgentSurface(shellRoot, agentsContent, "interf-stage", renderStageExecutionSkill(stage, readStageMethodDoc(workspacePath, stage)));
     return {
         rootPath: shellRoot,
     };
 }
-//# sourceMappingURL=agent-shells.js.map
+export function freezeStageExecutionShell(rootPath) {
+    return freezePreservedShell(rootPath, "stage-execution");
+}
+export function createWorkflowImprovementShell(options) {
+    const schema = ensureWorkspaceExecutionSurface(options.workspacePath);
+    const loopRootPath = workflowImprovementLoopRoot(options.workspacePath, options.runId, options.loopIndex);
+    const shellRoot = join(loopRootPath, "shell");
+    mkdirSync(shellRoot, { recursive: true });
+    mkdirSync(join(shellRoot, "runtime"), { recursive: true });
+    mkdirSync(join(shellRoot, "artifacts"), { recursive: true });
+    mkdirSync(join(loopRootPath, "logs"), { recursive: true });
+    writeFileSync(join(shellRoot, "runtime", "loop-context.json"), `${JSON.stringify(options.context, null, 2)}\n`);
+    projectWorkspaceReviewArtifactsSnapshot(options.workspacePath, shellRoot, schema);
+    linkPath(workflowPackagePathForWorkspace(options.workspacePath), join(shellRoot, "workflow"));
+    copyIfExists(workspaceInterfConfigPath(options.workspacePath), join(shellRoot, "interf.json"), "workflow-improvement");
+    projectWorkspaceRuntimeArtifacts(options.workspacePath, shellRoot);
+    const reviewSources = resolveWorkflowImprovementReviewSourcePaths(options.workspacePath);
+    if (reviewSources.executionShells) {
+        copyIfExists(reviewSources.executionShells, join(shellRoot, "artifacts", "execution-shells"), "workflow-improvement");
+    }
+    if (reviewSources.testComparisons) {
+        copyIfExists(reviewSources.testComparisons, join(shellRoot, "artifacts", "test-comparisons"), "workflow-improvement");
+    }
+    if (reviewSources.targetTestRuns) {
+        copyIfExists(reviewSources.targetTestRuns, join(shellRoot, "artifacts", "test-runs"), "workflow-improvement");
+    }
+    if (reviewSources.targetTestSandboxes) {
+        copyIfExists(reviewSources.targetTestSandboxes, join(shellRoot, "artifacts", "test-sandboxes"), "workflow-improvement");
+    }
+    const agentsContent = renderWorkflowImprovementAgents(options.workspaceName, options.workflowId, options.loopIndex);
+    writeNativeAgentSurface(shellRoot, agentsContent, "interf-workflow-improver", renderWorkflowImprovementSkill(options.workflowId, options.loopIndex, readWorkflowImprovementDoc(options.workspacePath)));
+    return {
+        rootPath: shellRoot,
+        loopRootPath,
+        workflowBeforePath: join(loopRootPath, "workflow-before"),
+        workflowAfterPath: join(loopRootPath, "workflow-after"),
+        promptLogPath: join(loopRootPath, "logs", "workflow-improver.prompt.txt"),
+        eventLogPath: join(loopRootPath, "logs", "workflow-improver.events.ndjson"),
+        statusLogPath: join(loopRootPath, "logs", "workflow-improver.status.log"),
+    };
+}
+export function freezeWorkflowImprovementShell(rootPath) {
+    return freezePreservedShell(rootPath, "workflow-improvement");
+}