@interf/compiler 0.5.1 → 0.6.3

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

@@ -0,0 +1,1021 @@
+import { cpSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, symlinkSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, relative } from "node:path";
+import { CHART_APPROXIMATION_NOTES } from "../../../lib/chart-guidance.js";
+import { projectRawSnapshot } from "../../../lib/compiled-raw.js";
+import { WORKFLOW_PACKAGE_DIR } from "../../../lib/interf-detect.js";
+import { WORKFLOW_SCHEMA_FILE, ensureCompiledZoneTargets, readCompiledSchemaFile, compiledZoneAbsolutePath, resolveWorkflowSchemaPath, } from "../../../lib/compiled-schema.js";
+import { stageExecutionShellsRoot, workflowImprovementLoopRoot, workflowPackagePathForCompiled, compiledInterfConfigPath, compiledRuntimeRoot, } from "../../../lib/compiled-paths.js";
+import { listFilesRecursive } from "../../../lib/filesystem.js";
+import { resolveWorkflowImprovementReviewSourcePaths } from "../../workflow-package/workflow-review-paths.js";
+const LOCAL_SKILL_ROOTS = [
+    ".claude/skills",
+    ".codex/skills",
+    ".agents/skills",
+    ".cursor/skills",
+];
+export function writeNativeAgentSurface(rootPath, agentsContent, skillName, skillContent) {
+    let changed = false;
+    changed = writeIfChanged(join(rootPath, "AGENTS.md"), `${agentsContent.trimEnd()}\n`) || changed;
+    changed =
+        writeIfChanged(join(rootPath, "CLAUDE.md"), renderClaudeBootstrap(agentsContent)) || changed;
+    changed = writeNativeSkillCopies(rootPath, skillName, skillContent) || changed;
+    return changed;
+}
+function compiledQuerySkillSourcePath(compiledPath) {
+    return join(workflowPackagePathForCompiled(compiledPath), "use", "query", "SKILL.md");
+}
+function compiledZoneSummaryLines(compiledPath) {
+    const schema = readCompiledSchemaFile(workflowPackagePathForCompiled(compiledPath));
+    if (!schema)
+        return ["- No workflow schema is available yet."];
+    return schema.zones
+        .filter((zone) => zone.kind !== "runtime")
+        .map((zone) => `- \`${zone.id}\` -> \`${zone.path}\` (${zone.role} ${zone.kind})`);
+}
+export function renderCompiledAgents(compiledPath, name, workflowId, about, options = {}) {
+    const workflowOriginSelected = options.workflowOriginSelected ?? workflowId;
+    const workflowLocalDraft = options.workflowLocalDraft === true;
+    const zoneLines = compiledZoneSummaryLines(compiledPath);
+    return [
+        `# ${name}`,
+        "",
+        "This is a context folder built by Interf.",
+        "Technically, it is the compiled context for this dataset entry: a file-based task context layer on top of the raw files, prepared for agents to navigate, retrieve evidence, and reach source-backed answers more reliably.",
+        "",
+        ...(about
+            ? [
+                `About: ${about}`,
+                "",
+            ]
+            : []),
+        "## How to use this context folder",
+        "",
+        "1. Use the local native `interf-query` skill that Interf generated for this context folder.",
+        "2. Let the workflow docs and declared output zones guide retrieval instead of assuming a fixed note layout.",
+        "3. Use `raw/` when you need direct quotes, exact chart values, table lookups, or verification.",
+        "",
+        "## How this compiled context works",
+        "",
+        "- `.interf/interf.json` points to the local `raw/` snapshot via `source.path` and back to the project root via `source.control_path`.",
+        `- Workflow seed: \`${workflowOriginSelected}\`.`,
+        ...(workflowLocalDraft
+            ? ["- This compiled context now carries a local workflow draft improved from that seed. Recompiling this context folder reuses the local `.interf/workflow/` package."]
+            : []),
+        `- Active local workflow id: \`${workflowId}\`.`,
+        "- `.interf/workflow/` is the local editable method package for this compiled context.",
+        `- \`.interf/workflow/${WORKFLOW_SCHEMA_FILE}\` is the deterministic zone contract for this compiled context.`,
+        "- `.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 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 local raw snapshot used for evidence and verification.",
+        `- Workflow zones are declared in \`.interf/workflow/${WORKFLOW_SCHEMA_FILE}\`.`,
+        ...zoneLines,
+        "- `.interf/runtime/` holds runtime artifacts written by Interf.",
+        "- `.interf/tests/` mirrors the latest saved comparison and keeps detailed target runs plus preserved sandboxes.",
+        "- `.interf/tests/targets/` holds detailed raw and compiled target runs plus preserved test sandboxes.",
+        "",
+        "## Manual query rules",
+        "",
+        "- Prefer the workflow-declared context outputs 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 context does not expose well.",
+        "- 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 context folder",
+        "interf test               run checks against this context folder",
+        "interf verify stage <id>  verify one workflow stage",
+        "interf verify compiled    verify the full compiled context output",
+        "interf status             show deterministic health",
+        "```",
+        "",
+        "## Rules",
+        "",
+        "- Do not modify files under `raw/`.",
+        "- Treat compiled notes as working task context artifacts, not final truth.",
+        "- When confidence is low, verify against `raw/` before answering strongly.",
+        "",
+    ].join("\n");
+}
+export function renderCompiledQuerySkill() {
+    return [
+        "# Manual Query Loop",
+        "",
+        "This file is the editable authoring source for the generated native local `interf-query` skill.",
+        "",
+        "Default loop:",
+        "1. Read `workflow/README.md` and this file first.",
+        `2. Use the workflow zones declared in \`workflow/${WORKFLOW_SCHEMA_FILE}\` before falling back to \`raw/\`.`,
+        "3. Use `raw/` for direct quotes, verification, exact lookups, and cases where the compiled context is missing the needed evidence or is ambiguous.",
+        "",
+        "Answering rule:",
+        "- do not modify files under `raw/`",
+        "- treat the workflow as the method layer and the compiled zones as the working retrieval surface",
+        "- say explicitly when an answer depends on approximation, bounded inference, or a raw-source re-check",
+        "- use `raw/` to confirm source page, metric family, provenance, or exact wording when the compiled context is missing the needed evidence or is ambiguous",
+        "- do not invent navigation or note structure beyond what this workflow declares",
+        "- when the compiled context is insufficient, verify in `raw/` and then answer",
+        "",
+        "You can edit this file to bias manual question-answering behavior for this context folder.",
+        "",
+    ].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.",
+        "There is no compiled context 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 context here, so do not assume any compiled-context output zones 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 context artifacts because they do not exist in this shell.",
+        "",
+    ].join("\n");
+}
+function readCompiledQuerySkillSource(compiledPath) {
+    const filePath = compiledQuerySkillSourcePath(compiledPath);
+    if (!existsSync(filePath)) {
+        throw new Error(`Missing compiled query skill source at ${filePath}. Interf compile runs the local workflow package directly, so reseed or repair this compiled context instead of auto-healing query docs.`);
+    }
+    return readFileSync(filePath, "utf8").trim();
+}
+function stageShellWorkflowRoot(shellRoot) {
+    return join(shellRoot, WORKFLOW_PACKAGE_DIR);
+}
+function shellInputZonePath(shellRoot, zoneId) {
+    return join(shellRoot, "inputs", 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);
+}
+function writeIfChanged(path, content) {
+    if (existsSync(path) && readFileSync(path, "utf8") === content) {
+        return false;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+    return true;
+}
+function writeNativeSkillCopies(rootPath, skillName, content) {
+    let changed = false;
+    for (const skillsRoot of LOCAL_SKILL_ROOTS) {
+        const skillPath = join(rootPath, skillsRoot, skillName, "SKILL.md");
+        changed = writeIfChanged(skillPath, content) || changed;
+    }
+    return changed;
+}
+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 loadCompiledSchema(compiledPath) {
+    const workflowRoot = workflowPackagePathForCompiled(compiledPath);
+    const schema = readCompiledSchemaFile(workflowRoot);
+    if (!schema) {
+        throw new Error(`Missing workflow schema at ${join(workflowRoot, WORKFLOW_SCHEMA_FILE)}`);
+    }
+    return schema;
+}
+function zoneMap(schema) {
+    return new Map(schema.zones.map((zone) => [zone.id, zone]));
+}
+function zoneOrThrow(zones, zoneId) {
+    const zone = zones.get(zoneId);
+    if (!zone) {
+        throw new Error(`Missing workflow schema zone "${zoneId}" for stage shell projection.`);
+    }
+    return zone;
+}
+function normalizeArtifactRelativePath(path) {
+    return path
+        .replaceAll("\\", "/")
+        .replace(/^\.?\//, "")
+        .replace(/\/+$/g, "");
+}
+function relativePathEqualsOrWithin(basePath, candidatePath) {
+    const base = normalizeArtifactRelativePath(basePath);
+    const candidate = normalizeArtifactRelativePath(candidatePath);
+    if (base.length === 0 || candidate.length === 0)
+        return false;
+    return candidate === base || candidate.startsWith(`${base}/`);
+}
+function stageWriteZoneSet(schema, stage) {
+    return new Set(stage.writes.filter((zoneId) => schema.zones.some((zone) => zone.id === zoneId)));
+}
+function stageMaterializedZoneSet(schema, stage, writeArtifacts = []) {
+    const materialized = stageWriteZoneSet(schema, stage);
+    for (const zone of schema.zones) {
+        if (zone.kind === "runtime" && stage.reads.includes(zone.id)) {
+            materialized.add(zone.id);
+        }
+    }
+    for (const artifactPath of writeArtifacts) {
+        const normalizedArtifactPath = normalizeArtifactRelativePath(artifactPath);
+        if (normalizedArtifactPath.length === 0)
+            continue;
+        const owner = schema.zones.find((zone) => relativePathEqualsOrWithin(zone.path, normalizedArtifactPath));
+        if (owner) {
+            materialized.add(owner.id);
+        }
+    }
+    return materialized;
+}
+function ensureShellLocalProjection(sourcePath, targetPath, zone) {
+    if (existsSync(sourcePath)) {
+        copyResolvedTree({
+            sourcePath,
+            targetPath,
+            shellType: "stage-execution",
+        });
+        return;
+    }
+    if (zone.kind === "file") {
+        mkdirSync(dirname(targetPath), { recursive: true });
+        return;
+    }
+    mkdirSync(targetPath, { recursive: true });
+}
+function ensureCompiledExecutionSurface(compiledPath) {
+    mkdirSync(compiledRuntimeRoot(compiledPath), { recursive: true });
+    mkdirSync(workflowPackagePathForCompiled(compiledPath), { recursive: true });
+    const schema = loadCompiledSchema(compiledPath);
+    ensureCompiledZoneTargets(compiledPath, schema);
+    return schema;
+}
+function readStageMethodDoc(compiledPath, stage) {
+    const path = join(workflowPackagePathForCompiled(compiledPath), "compile", "stages", stage.skillDir, "SKILL.md");
+    if (!existsSync(path))
+        return null;
+    return readFileSync(path, "utf8").trim();
+}
+function stageWorkflowDocsPath(compiledPath, stage) {
+    return join(workflowPackagePathForCompiled(compiledPath), "compile", "stages", stage.skillDir);
+}
+function renderStageExecutionAgents(compiledName, workflowId, stage) {
+    return [
+        `# ${compiledName} — ${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/paths.json` now.",
+        "3. Use the local native `interf-stage` skill now.",
+        `4. Execute only the current stage: \`${stage.id}\` (${stage.label}).`,
+        "",
+        "## Shell ABI",
+        "",
+        "- `inputs/<zone-id>/` = read mounts for the current stage.",
+        "- `outputs/<zone-id>/` = write mounts for the current stage.",
+        "- For file zones, `runtime/paths.json` points to the exact file path inside those mount roots.",
+        "- declared compiled 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, workflow schema, and docs for the current stage only.",
+        "",
+        "## Boundaries",
+        "",
+        `- Workflow: \`${workflowId}\`.`,
+        `- Contract type: \`${stage.contractType}\`.`,
+        "- This shell has its own AGENTS/CLAUDE/native skills. It does not inherit the compiled-context query shell.",
+        "- The compiled context 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 zone is also mounted under `outputs/`.",
+        "",
+        "## Current Stage Zones",
+        "",
+        `- reads: ${stage.reads.join(", ")}`,
+        `- writes: ${stage.writes.join(", ")}`,
+        "",
+        "## Goal",
+        "",
+        "- complete the current stage",
+        "- honor the deterministic contract",
+        "- write outputs through the declared zone mounts",
+        "- stop when the stage is complete",
+        "",
+    ].join("\n");
+}
+function renderStageExecutionSkill(stage, stageMethodDoc) {
+    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/paths.json` and use the mounted `inputs/` and `outputs/` zones for this stage.",
+        "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: \`workflow/compile/stages/${stage.skillDir}/SKILL.md\``,
+        "",
+        ...(stageMethodDoc
+            ? [
+                "## Stage Method",
+                "",
+                stageMethodDoc,
+                "",
+            ]
+            : []),
+    ].join("\n");
+}
+function renderCompiledQueryNativeSkill(querySkillContent) {
+    return [
+        "---",
+        "name: interf-query",
+        "description: >",
+        "  Native local query skill for this context folder built by Interf",
+        "  Compiler. Use it for manual questions against the compiled context",
+        "  and its raw fallback.",
+        "---",
+        "",
+        "# Interf Query",
+        "",
+        "This is the native local query skill for a compiled context built by Interf.",
+        "Use it when reading this context folder manually.",
+        "Editable source: `.interf/workflow/use/query/SKILL.md`.",
+        "",
+        querySkillContent.trim(),
+        "",
+    ].join("\n");
+}
+function projectWorkflowMetadata(compiledPath, shellRoot, stage) {
+    const shellWorkflowRoot = stageShellWorkflowRoot(shellRoot);
+    mkdirSync(join(shellWorkflowRoot, "compile", "stages"), { recursive: true });
+    const compiledWorkflowRoot = workflowPackagePathForCompiled(compiledPath);
+    const workflowJsonPath = join(compiledWorkflowRoot, "workflow.json");
+    if (existsSync(workflowJsonPath)) {
+        linkPath(workflowJsonPath, join(shellWorkflowRoot, "workflow.json"));
+    }
+    const compiledSchemaPath = resolveWorkflowSchemaPath(compiledWorkflowRoot);
+    if (compiledSchemaPath) {
+        linkPath(compiledSchemaPath, join(shellWorkflowRoot, WORKFLOW_SCHEMA_FILE));
+    }
+    const readmePath = join(compiledWorkflowRoot, "README.md");
+    if (existsSync(readmePath)) {
+        linkPath(readmePath, join(shellWorkflowRoot, "README.md"));
+    }
+    const stageDocsPath = stageWorkflowDocsPath(compiledPath, stage);
+    if (existsSync(stageDocsPath)) {
+        linkPath(stageDocsPath, join(shellWorkflowRoot, "compile", "stages", stage.skillDir));
+    }
+}
+function projectCompiledSchemaZones(compiledPath, shellRoot, schema, zoneIds, materializedZoneIds) {
+    const allowedZoneIds = zoneIds ? new Set(zoneIds) : null;
+    for (const zone of schema.zones) {
+        if (allowedZoneIds && !allowedZoneIds.has(zone.id))
+            continue;
+        const sourcePath = compiledZoneAbsolutePath(compiledPath, zone);
+        const targetPath = join(shellRoot, zone.path);
+        if (materializedZoneIds?.has(zone.id)) {
+            ensureShellLocalProjection(sourcePath, targetPath, zone);
+            continue;
+        }
+        linkPath(sourcePath, targetPath);
+    }
+}
+function buildStageZoneMounts(compiledPath, shellRoot, stage, schema) {
+    const zones = zoneMap(schema);
+    const mountFor = (zoneId) => {
+        const zone = zoneOrThrow(zones, zoneId);
+        return {
+            zone_id: zone.id,
+            compiled_path: zone.path,
+            shell_root_path: zone.path,
+            input_mount_path: stage.reads.includes(zoneId)
+                ? describeShellZoneAliasMountPath(zone, "inputs")
+                : null,
+            output_mount_path: stage.writes.includes(zoneId)
+                ? describeShellZoneAliasMountPath(zone, "outputs")
+                : null,
+        };
+    };
+    return {
+        reads: stage.reads.map(mountFor),
+        writes: stage.writes.map(mountFor),
+    };
+}
+function projectStageZoneMountAliases(shellRoot, stage, schema) {
+    const zones = zoneMap(schema);
+    for (const zoneId of new Set([...stage.reads, ...stage.writes])) {
+        const zone = zoneOrThrow(zones, zoneId);
+        const targetPath = join(shellRoot, zone.path);
+        if (stage.reads.includes(zoneId)) {
+            linkRelativePath(targetPath, shellZoneAliasMountPath(shellRoot, zone, "inputs"));
+        }
+        if (stage.writes.includes(zoneId)) {
+            linkRelativePath(targetPath, shellZoneAliasMountPath(shellRoot, zone, "outputs"));
+        }
+    }
+}
+function writeExecutionShellPathsFile(shellRoot, workflowId, stage, mounts) {
+    const paths = {
+        kind: "interf-execution-shell",
+        version: 1,
+        workflow: workflowId,
+        stage: stage.id,
+        reads: mounts.reads,
+        writes: mounts.writes,
+    };
+    writeFileSync(shellRuntimePath(shellRoot, "paths.json"), `${JSON.stringify(paths, null, 2)}\n`);
+}
+export function syncStageExecutionShellWrites(compiledPath, shellRoot, stage, writeArtifacts = []) {
+    const schema = ensureCompiledExecutionSurface(compiledPath);
+    const zones = zoneMap(schema);
+    const stageWriteZones = Array.from(stageWriteZoneSet(schema, stage))
+        .map((zoneId) => zoneOrThrow(zones, zoneId));
+    for (const zone of stageWriteZones) {
+        const canonicalShellZonePath = join(shellRoot, zone.path);
+        const outputAliasPath = shellZoneAliasMountPath(shellRoot, zone, "outputs");
+        const shellZonePath = zone.kind === "file" &&
+            existsSync(outputAliasPath) &&
+            !lstatSync(outputAliasPath).isSymbolicLink()
+            ? outputAliasPath
+            : canonicalShellZonePath;
+        if (!existsSync(shellZonePath))
+            continue;
+        const shellZoneStat = lstatSync(shellZonePath);
+        if (shellZoneStat.isSymbolicLink())
+            continue;
+        const compiledZonePath = compiledZoneAbsolutePath(compiledPath, zone);
+        if (shellZoneStat.isDirectory()) {
+            const shellZoneFiles = listFilesRecursive(shellZonePath);
+            const compiledZoneFiles = existsSync(compiledZonePath)
+                ? listFilesRecursive(compiledZonePath)
+                : [];
+            if (shellZoneFiles.length === 0 && compiledZoneFiles.length > 0) {
+                continue;
+            }
+            rmSync(compiledZonePath, { recursive: true, force: true });
+            mkdirSync(dirname(compiledZonePath), { recursive: true });
+            cpSync(shellZonePath, compiledZonePath, {
+                recursive: true,
+                force: true,
+            });
+            continue;
+        }
+        mkdirSync(dirname(compiledZonePath), { recursive: true });
+        copyFileSync(shellZonePath, compiledZonePath);
+    }
+    for (const artifactPath of writeArtifacts) {
+        const normalizedArtifactPath = normalizeArtifactRelativePath(artifactPath);
+        if (normalizedArtifactPath.length === 0 ||
+            stageWriteZones.some((zone) => relativePathEqualsOrWithin(zone.path, normalizedArtifactPath))) {
+            continue;
+        }
+        const shellArtifactPath = join(shellRoot, normalizedArtifactPath);
+        if (!existsSync(shellArtifactPath))
+            continue;
+        const compiledArtifactPath = join(compiledPath, normalizedArtifactPath);
+        const shellArtifactStat = lstatSync(shellArtifactPath);
+        if (shellArtifactStat.isSymbolicLink())
+            continue;
+        if (shellArtifactStat.isDirectory()) {
+            rmSync(compiledArtifactPath, { recursive: true, force: true });
+            mkdirSync(dirname(compiledArtifactPath), { recursive: true });
+            cpSync(shellArtifactPath, compiledArtifactPath, {
+                recursive: true,
+                force: true,
+            });
+            continue;
+        }
+        mkdirSync(dirname(compiledArtifactPath), { recursive: true });
+        copyFileSync(shellArtifactPath, compiledArtifactPath);
+    }
+}
+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 compatibility mirror of AGENTS.md. Interf may rewrite this file. -->",
+        "",
+        content.trimEnd(),
+        "",
+    ].join("\n");
+}
+function renderWorkflowAuthoringAgents(options) {
+    return [
+        `# ${options.label} — Workflow Authoring Shell`,
+        "",
+        "This is an automated workflow-authoring shell generated by Interf.",
+        "It exists to create or refine one standalone workflow for the files and checks in this task.",
+        "",
+        "## Start Here",
+        "",
+        "1. Read `runtime/authoring-context.json` now.",
+        `2. Read \`workflow/README.md\`, \`workflow/workflow.json\`, and \`workflow/${WORKFLOW_SCHEMA_FILE}\` now.`,
+        "3. Review `artifacts/source-dataset/raw/` and `artifacts/preview-compiled/` if present.",
+        "4. Use the local native `interf-workflow-author` skill now.",
+        "",
+        "## Boundaries",
+        "",
+        `- New workflow id: \`${options.workflowId}\`.`,
+        `- Seed workflow: \`${options.baseWorkflowId}\`.`,
+        "- Edit only files under `workflow/`.",
+        "- Do not edit raw files or preview artifacts.",
+        "- Keep the workflow valid for the current compiler API and workflow schema.",
+        "- 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 workflow tuned to the files and checks in this task",
+        "- preserve deterministic stage and zone contracts",
+        "- stop once the workflow edits are complete",
+        "",
+    ].join("\n");
+}
+function renderWorkflowAuthoringSkill() {
+    return [
+        "---",
+        "name: interf-workflow-author",
+        "description: >",
+        "  Native local workflow-authoring skill for an automated Interf workflow draft run.",
+        "---",
+        "",
+        "# Interf Workflow Authoring",
+        "",
+        "Read `runtime/authoring-context.json` first.",
+        "Then review the seeded package under `workflow/`, the raw snapshot under `artifacts/source-dataset/raw/`, and any preview context outputs under `artifacts/preview-compiled/`.",
+        "",
+        "Rules:",
+        "- edit only `workflow/`",
+        `- keep \`workflow.json\`, \`${WORKFLOW_SCHEMA_FILE}\`, and any changed stage docs aligned`,
+        "- prefer small, defensible package edits over random churn",
+        "- keep the package standalone; do not introduce runtime inheritance or fallback assumptions",
+        "- do not introduce wikilinks unless the workflow also creates the target note by exact basename or explicit relative path",
+        "- respect stage boundaries: do not make structure outputs link to notes or entrypoints 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 answers into workflow docs",
+        "- do not edit raw files or preview artifacts",
+        "",
+    ].join("\n");
+}
+function authoringCopyIfExists(sourcePath, targetPath) {
+    if (!existsSync(sourcePath))
+        return;
+    mkdirSync(dirname(targetPath), { recursive: true });
+    cpSync(sourcePath, targetPath, {
+        recursive: true,
+        force: true,
+        errorOnExist: false,
+        preserveTimestamps: true,
+    });
+}
+function projectCompiledPreviewSnapshot(previewCompiledPath, shellRoot) {
+    const previewRoot = join(shellRoot, "artifacts", "preview-compiled");
+    mkdirSync(previewRoot, { recursive: true });
+    authoringCopyIfExists(join(previewCompiledPath, "AGENTS.md"), join(previewRoot, "AGENTS.md"));
+    authoringCopyIfExists(join(previewCompiledPath, "CLAUDE.md"), join(previewRoot, "CLAUDE.md"));
+    const schema = readCompiledSchemaFile(workflowPackagePathForCompiled(previewCompiledPath));
+    for (const zone of schema?.zones ?? []) {
+        if (zone.kind === "runtime" || zone.role === "input")
+            continue;
+        const absolutePath = compiledZoneAbsolutePath(previewCompiledPath, zone);
+        if (!existsSync(absolutePath))
+            continue;
+        authoringCopyIfExists(absolutePath, join(previewRoot, zone.path));
+    }
+}
+function projectCompiledPreviewRuntime(previewCompiledPath, shellRoot) {
+    const targetRoot = join(shellRoot, "artifacts", "preview-runtime");
+    mkdirSync(targetRoot, { recursive: true });
+    const runtimeRoot = compiledRuntimeRoot(previewCompiledPath);
+    for (const artifactName of [
+        "run.json",
+        "state.json",
+        "health.json",
+        "view-spec.json",
+        "raw-snapshot.json",
+        "execution-shells",
+        "logs",
+    ]) {
+        authoringCopyIfExists(join(runtimeRoot, artifactName), join(targetRoot, artifactName));
+    }
+}
+function improvementWorkflowDocsPath(compiledPath) {
+    return join(workflowPackagePathForCompiled(compiledPath), "improve");
+}
+export function createWorkflowAuthoringShell(options) {
+    const shellRoot = mkdtempSync(join(tmpdir(), `interf-workflow-author-${options.workflowId}-`));
+    mkdirSync(join(shellRoot, "runtime"), { recursive: true });
+    mkdirSync(join(shellRoot, "artifacts"), { recursive: true });
+    mkdirSync(join(shellRoot, "logs"), { recursive: true });
+    const context = {
+        kind: "interf-workflow-authoring",
+        version: 1,
+        generated_at: new Date().toISOString(),
+        workflow_id: options.workflowId,
+        workflow_label: options.label,
+        seed_workflow_id: options.baseWorkflowId,
+        task_prompt: options.taskPrompt,
+        dataset: {
+            source_path: options.datasetPath,
+            checks: {
+                count: options.checks.length,
+                questions: options.checks.map((check, index) => ({
+                    id: check.id ?? `check-${index + 1}`,
+                    question: check.question,
+                })),
+            },
+        },
+        preview: options.preview
+            ? {
+                prepared: true,
+                compile_ok: options.preview.compileResult.ok,
+                failed_stage: options.preview.compileResult.failedStage,
+            }
+            : {
+                prepared: false,
+                compile_ok: null,
+                failed_stage: null,
+            },
+    };
+    writeFileSync(join(shellRoot, "runtime", "authoring-context.json"), `${JSON.stringify(context, null, 2)}\n`);
+    projectRawSnapshot({
+        sourcePath: options.datasetPath,
+        destinationPath: join(shellRoot, "artifacts", "source-dataset", "raw"),
+        compiledPath: shellRoot,
+        mode: "copy",
+        prune: true,
+        preserveTimestamps: true,
+    });
+    if (options.preview) {
+        projectCompiledPreviewSnapshot(options.preview.compiledPath, shellRoot);
+        projectCompiledPreviewRuntime(options.preview.compiledPath, shellRoot);
+    }
+    linkPath(options.workflowPath, join(shellRoot, "workflow"));
+    writeNativeAgentSurface(shellRoot, renderWorkflowAuthoringAgents({
+        workflowId: options.workflowId,
+        label: options.label,
+        baseWorkflowId: options.baseWorkflowId,
+    }), "interf-workflow-author", renderWorkflowAuthoringSkill());
+    return {
+        rootPath: shellRoot,
+        workflowBeforePath: join(shellRoot, "artifacts", "workflow-before"),
+        workflowAfterPath: join(shellRoot, "artifacts", "workflow-after"),
+        promptLogPath: join(shellRoot, "logs", "workflow-author.prompt.txt"),
+        eventLogPath: join(shellRoot, "logs", "workflow-author.events.ndjson"),
+        statusLogPath: join(shellRoot, "logs", "workflow-author.status.log"),
+    };
+}
+function renderWorkflowImprovementAgents(compiledName, workflowId, loopIndex) {
+    return [
+        `# ${compiledName} — Workflow Improvement Shell`,
+        "",
+        "This is an automated workflow-improvement shell generated by Interf.",
+        "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/${WORKFLOW_SCHEMA_FILE}\` 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 checks, test specs, raw files, or generated context outputs.",
+        "- Review context outputs under `artifacts/compiled-view/` and test/runtime evidence under `artifacts/`.",
+        "- Keep the workflow valid for the current compiler API and workflow schema.",
+        "",
+        "## Goal",
+        "",
+        "- create a better workflow variation for this task",
+        "- preserve deterministic compiled-context structure",
+        "- stop after the workflow edits are complete",
+        "",
+    ].join("\n");
+}
+function readWorkflowImprovementDoc(compiledPath) {
+    const path = join(improvementWorkflowDocsPath(compiledPath), "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 run.",
+        "  Use it only inside an automated workflow-improvement shell.",
+        "---",
+        "",
+        `# Interf 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/compiled-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 projectCompiledReviewArtifactsSnapshot(compiledPath, shellRoot, schema) {
+    const compiledViewRoot = join(shellRoot, "artifacts", "compiled-view");
+    mkdirSync(compiledViewRoot, { recursive: true });
+    for (const zone of schema.zones) {
+        if (zone.kind === "runtime" || zone.path === "raw")
+            continue;
+        const sourcePath = compiledZoneAbsolutePath(compiledPath, zone);
+        if (!existsSync(sourcePath))
+            continue;
+        copyResolvedTree({
+            sourcePath,
+            targetPath: join(compiledViewRoot, 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 projectCompiledRuntimeArtifacts(compiledPath, shellRoot) {
+    const runtimeTarget = join(shellRoot, "artifacts", "compiled-runtime");
+    mkdirSync(runtimeTarget, { recursive: true });
+    const runtimeRoot = compiledRuntimeRoot(compiledPath);
+    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(compiledPath) {
+    rmSync(stageExecutionShellsRoot(compiledPath), { recursive: true, force: true });
+}
+export function projectCompiledQueryShell(compiledPath, compiledName, workflowId, about, options) {
+    const agentsContent = renderCompiledAgents(compiledPath, compiledName, workflowId, about, options);
+    const querySkillContent = readCompiledQuerySkillSource(compiledPath);
+    return writeNativeAgentSurface(compiledPath, agentsContent, "interf-query", renderCompiledQueryNativeSkill(querySkillContent));
+}
+export function projectRawTestQueryShell(rootPath) {
+    return writeNativeAgentSurface(rootPath, renderRawTestAgents(), "interf-query", renderRawTestQuerySkill());
+}
+export function createStageExecutionShell(compiledPath, compiledName, workflowId, stage, writeArtifacts = []) {
+    const schema = ensureCompiledExecutionSurface(compiledPath);
+    const materializedZones = stageMaterializedZoneSet(schema, stage, writeArtifacts);
+    const shellsRoot = stageExecutionShellsRoot(compiledPath);
+    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(compiledInterfConfigPath(compiledPath), join(shellRoot, "interf.json"));
+    linkPath(join(compiledRuntimeRoot(compiledPath), "stage-contract.json"), shellRuntimePath(shellRoot, "stage-contract.json"));
+    projectCompiledSchemaZones(compiledPath, shellRoot, schema, new Set([...stage.reads, ...stage.writes]), materializedZones);
+    projectWorkflowMetadata(compiledPath, shellRoot, stage);
+    projectStageZoneMountAliases(shellRoot, stage, schema);
+    writeExecutionShellPathsFile(shellRoot, workflowId, stage, buildStageZoneMounts(compiledPath, shellRoot, stage, schema));
+    const agentsContent = renderStageExecutionAgents(compiledName, workflowId, stage);
+    writeNativeAgentSurface(shellRoot, agentsContent, "interf-stage", renderStageExecutionSkill(stage, readStageMethodDoc(compiledPath, stage)));
+    return {
+        rootPath: shellRoot,
+    };
+}
+export function freezeStageExecutionShell(rootPath) {
+    return freezePreservedShell(rootPath, "stage-execution");
+}
+export function createWorkflowImprovementShell(options) {
+    const schema = ensureCompiledExecutionSurface(options.compiledPath);
+    const loopRootPath = workflowImprovementLoopRoot(options.compiledPath, 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`);
+    projectCompiledReviewArtifactsSnapshot(options.compiledPath, shellRoot, schema);
+    linkPath(workflowPackagePathForCompiled(options.compiledPath), join(shellRoot, "workflow"));
+    copyIfExists(compiledInterfConfigPath(options.compiledPath), join(shellRoot, "interf.json"), "workflow-improvement");
+    projectCompiledRuntimeArtifacts(options.compiledPath, shellRoot);
+    const reviewSources = resolveWorkflowImprovementReviewSourcePaths(options.compiledPath);
+    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.compiledName, options.workflowId, options.loopIndex);
+    writeNativeAgentSurface(shellRoot, agentsContent, "interf-workflow-improver", renderWorkflowImprovementSkill(options.workflowId, options.loopIndex, readWorkflowImprovementDoc(options.compiledPath)));
+    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");
+}