@interf/compiler 0.13.0 → 0.18.0

package/dist/packages/{agents → engine/agents}/lib/shells.js

@@ -2,13 +2,14 @@ import { cpSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, re
 import { tmpdir } from "node:os";
 import { basename, dirname, join, relative, sep as pathSep } from "node:path";
 import { CHART_APPROXIMATION_NOTES } from "./chart-guidance.js";
-import { buildCompiledSourceFiles } from "../../compiler/source-files.js";
-import { METHOD_PACKAGE_DIR } from "../../project-model/interf-detect.js";
-import { CONTEXT_INTERFACE_FILE as METHOD_SCHEMA_FILE, contextInterfaceZoneAbsolutePath as compiledZoneAbsolutePath, readContextInterface as readCompiledSchemaFile, resolveContextInterfacePath as resolveMethodSchemaPath, } from "../../method-package/context-interface.js";
-import { stageExecutionShellsRoot, methodImprovementLoopRoot, methodPackagePathForCompiled, compiledInterfConfigPath, compiledRuntimeRoot, compiledRuntimeSourceSnapshotPath, compiledRuntimeStageInputsPath, } from "../../compiler/compiled-paths.js";
-import { ensureCompiledZoneTargets } from "../../compiler/compiled-schema.js";
-import { listFilesRecursive } from "../../shared/filesystem.js";
-import { resolveMethodImprovementReviewSourcePaths } from "../../method-package/method-review-paths.js";
+import { buildCompiledSourceFiles } from "../../compile/source-files.js";
+import { METHOD_PACKAGE_DIR } from "../../../project/interf-detect.js";
+import { CHECK_KINDS, } from "../../../contracts/lib/schema.js";
+import { CONTEXT_INTERFACE_FILE as METHOD_SCHEMA_FILE, contextInterfaceArtifactAbsolutePath as compiledArtifactAbsolutePath, listContextInterfaceArtifacts, readContextInterface as readCompiledSchemaFile, resolveContextInterfacePath as resolveMethodSchemaPath, } from "../../../methods/package/context-interface.js";
+import { stageExecutionShellsRoot, methodImprovementLoopRoot, methodPackagePathForCompiled, compiledInterfConfigPath, compiledRuntimeRoot, compiledRuntimeSourceSnapshotPath, compiledRuntimeStageInputsPath, } from "../../compile/compiled-paths.js";
+import { ensureCompiledArtifactTargets } from "../../compile/compiled-schema.js";
+import { listFilesRecursive } from "../../../contracts/utils/filesystem.js";
+import { resolveMethodImprovementReviewSourcePaths } from "../../../methods/package/method-review-paths.js";
 const LOCAL_SKILL_ROOTS = [
     ".claude/skills",
     ".codex/skills",
@@ -26,18 +27,18 @@ export function writeNativeAgentSurface(rootPath, agentsContent, skillName, skil
 function compiledQuerySkillSourcePath(compiledPath) {
     return join(methodPackagePathForCompiled(compiledPath), "use", "query", "SKILL.md");
 }
-function compiledZoneSummaryLines(compiledPath) {
+function compiledArtifactSummaryLines(compiledPath) {
     const schema = readCompiledSchemaFile(methodPackagePathForCompiled(compiledPath));
     if (!schema)
         return ["- No Method schema is available yet."];
-    return schema.zones
-        .filter((zone) => zone.kind !== "runtime")
-        .map((zone) => `- \`${zone.id}\` -> \`${zone.path}\` (${zone.role} ${zone.kind})`);
+    return listContextInterfaceArtifacts(schema)
+        .filter((artifact) => artifact.kind !== "runtime")
+        .map((artifact) => `- \`${artifact.id}\` -> \`${artifact.path}\` (${artifact.role} ${artifact.kind})`);
 }
 export function renderCompiledAgents(compiledPath, name, methodId, about, options = {}) {
     const methodOriginSelected = options.methodOriginSelected ?? methodId;
     const methodLocalDraft = options.methodLocalDraft === true;
-    const zoneLines = compiledZoneSummaryLines(compiledPath);
+    const artifactLines = compiledArtifactSummaryLines(compiledPath);
     return [
         `# ${name}`,
         "",
@@ -53,7 +54,7 @@ export function renderCompiledAgents(compiledPath, name, methodId, about, option
         "## How to use this portable context",
         "",
         "1. Use the local native `interf-query` skill that Interf generated for this portable context.",
-        "2. Let the Method docs and declared output zones guide retrieval instead of assuming a fixed note layout.",
+        "2. Let the Method docs and declared Artifacts guide retrieval instead of assuming a fixed note layout.",
         "3. Use `.interf/runtime/source-snapshot.json` when you need to inspect the source references behind the output.",
         "",
         "## How this portable context works",
@@ -72,8 +73,8 @@ export function renderCompiledAgents(compiledPath, name, methodId, about, option
         "- `.interf/method/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/`.",
         "- `.interf/runtime/source-snapshot.json` records the source files assigned to the latest runtime snapshot.",
-        `- Method zones are declared in \`.interf/method/${METHOD_SCHEMA_FILE}\`.`,
-        ...zoneLines,
+        `- Method Artifacts are declared in \`.interf/method/${METHOD_SCHEMA_FILE}\`.`,
+        ...artifactLines,
         "- `.interf/runtime/` holds runtime artifacts written by Interf.",
         "- `.interf/tests/` mirrors the latest saved readiness-check run and keeps detailed target runs plus preserved sandboxes.",
         "- `.interf/tests/targets/` holds detailed source-files and compiled target runs plus preserved test sandboxes.",
@@ -90,7 +91,7 @@ export function renderCompiledAgents(compiledPath, name, methodId, about, option
         "",
         "```",
         "interf compile            build this portable context",
-        "interf test               run checks against this portable context",
+        "interf verify               run checks against this portable context",
         "interf status             show deterministic health",
         "```",
         "",
@@ -110,12 +111,12 @@ export function renderCompiledQuerySkill() {
         "",
         "Default loop:",
         "1. Read `.interf/method/README.md` and this file first.",
-        `2. Use the Method zones declared in \`.interf/method/${METHOD_SCHEMA_FILE}\` before consulting source references.`,
+        `2. Use the Method Artifacts declared in \`.interf/method/${METHOD_SCHEMA_FILE}\` before consulting source references.`,
         "3. Use `.interf/runtime/source-snapshot.json` for direct quotes, verification, exact lookups, and cases where the portable context is missing the needed evidence or is ambiguous.",
         "",
         "Answering rule:",
         "- do not modify source files while answering",
-        "- treat the Method as the portable-context contract and use its zones as the working retrieval surface",
+        "- treat the Method as the portable-context contract and use its Artifacts as the working retrieval surface",
         "- say explicitly when an answer depends on approximation, bounded inference, or a source re-check",
         "- use source references to confirm source page, metric family, provenance, or exact wording when the portable context is missing the needed evidence or is ambiguous",
         "- do not invent navigation or note structure beyond what this Method declares",
@@ -142,7 +143,7 @@ function renderSourceFilesTestAgents() {
         "## Rules",
         "",
         "- Answer only from source files listed in `runtime/source-files.json`.",
-        "- There is no portable context here, so do not assume any portable-context output zones exist.",
+        "- There is no portable context here, so do not assume any portable-context Artifacts exist.",
         "- Do not treat hidden runtime files or test artifacts as evidence.",
         ...chartNotes,
         "- Write the requested answer and trace files, then stop.",
@@ -181,24 +182,24 @@ function readCompiledQuerySkillSource(compiledPath) {
 function stageShellMethodRoot(shellRoot) {
     return join(shellRoot, METHOD_PACKAGE_DIR);
 }
-function shellInputZonePath(shellRoot, zoneId) {
-    return join(shellRoot, "inputs", zoneId);
+function shellInputArtifactPath(shellRoot, artifactId) {
+    return join(shellRoot, "inputs", artifactId);
 }
-function shellOutputZonePath(shellRoot, zoneId) {
-    return join(shellRoot, "outputs", zoneId);
+function shellOutputArtifactPath(shellRoot, artifactId) {
+    return join(shellRoot, "outputs", artifactId);
 }
-function shellZoneAliasMountPath(shellRoot, zone, mountKind) {
+function shellArtifactAliasMountPath(shellRoot, artifact, mountKind) {
     const mountRoot = mountKind === "inputs"
-        ? shellInputZonePath(shellRoot, zone.id)
-        : shellOutputZonePath(shellRoot, zone.id);
-    return zone.kind === "file"
-        ? join(mountRoot, basename(zone.path))
+        ? shellInputArtifactPath(shellRoot, artifact.id)
+        : shellOutputArtifactPath(shellRoot, artifact.id);
+    return artifact.kind === "file"
+        ? join(mountRoot, basename(artifact.path))
         : mountRoot;
 }
-function describeShellZoneAliasMountPath(zone, mountKind) {
-    return zone.kind === "file"
-        ? `${mountKind}/${zone.id}/${basename(zone.path)}`
-        : `${mountKind}/${zone.id}`;
+function describeShellArtifactAliasMountPath(artifact, mountKind) {
+    return artifact.kind === "file"
+        ? `${mountKind}/${artifact.id}/${basename(artifact.path)}`
+        : `${mountKind}/${artifact.id}`;
 }
 function shellRuntimePath(shellRoot, relativePath) {
     return join(shellRoot, "runtime", relativePath);
@@ -240,15 +241,15 @@ function loadCompiledSchema(compiledPath) {
     }
     return schema;
 }
-function zoneMap(schema) {
-    return new Map(schema.zones.map((zone) => [zone.id, zone]));
+function artifactMap(schema) {
+    return new Map(listContextInterfaceArtifacts(schema).map((artifact) => [artifact.id, artifact]));
 }
-function zoneOrThrow(zones, zoneId) {
-    const zone = zones.get(zoneId);
-    if (!zone) {
-        throw new Error(`Missing Method schema zone "${zoneId}" for stage shell projection.`);
+function artifactOrThrow(artifacts, artifactId) {
+    const artifact = artifacts.get(artifactId);
+    if (!artifact) {
+        throw new Error(`Missing Method schema Artifact "${artifactId}" for stage shell projection.`);
     }
-    return zone;
+    return artifact;
 }
 function normalizeArtifactRelativePath(path) {
     return path
@@ -263,28 +264,29 @@ function relativePathEqualsOrWithin(basePath, candidatePath) {
         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 stageWriteArtifactSet(schema, stage) {
+    const artifacts = listContextInterfaceArtifacts(schema);
+    return new Set(stage.writes.filter((artifactId) => artifacts.some((artifact) => artifact.id === artifactId)));
 }
-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);
+function stageMaterializedArtifactSet(schema, stage, writeArtifacts = []) {
+    const materialized = stageWriteArtifactSet(schema, stage);
+    for (const artifact of listContextInterfaceArtifacts(schema)) {
+        if (artifact.kind === "runtime" && stage.reads.includes(artifact.id)) {
+            materialized.add(artifact.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));
+        const owner = listContextInterfaceArtifacts(schema).find((artifact) => relativePathEqualsOrWithin(artifact.path, normalizedArtifactPath));
         if (owner) {
             materialized.add(owner.id);
         }
     }
     return materialized;
 }
-function ensureShellLocalProjection(sourcePath, targetPath, zone) {
+function ensureShellLocalProjection(sourcePath, targetPath, artifact) {
     if (existsSync(sourcePath)) {
         copyResolvedTree({
             sourcePath,
@@ -293,7 +295,7 @@ function ensureShellLocalProjection(sourcePath, targetPath, zone) {
         });
         return;
     }
-    if (zone.kind === "file") {
+    if (artifact.kind === "file") {
         mkdirSync(dirname(targetPath), { recursive: true });
         return;
     }
@@ -303,7 +305,7 @@ function ensureCompiledExecutionSurface(compiledPath) {
     mkdirSync(compiledRuntimeRoot(compiledPath), { recursive: true });
     mkdirSync(methodPackagePathForCompiled(compiledPath), { recursive: true });
     const schema = loadCompiledSchema(compiledPath);
-    ensureCompiledZoneTargets(compiledPath, schema);
+    ensureCompiledArtifactTargets(compiledPath, schema);
     return schema;
 }
 function readStageMethodDoc(compiledPath, stage) {
@@ -332,12 +334,12 @@ function renderStageExecutionAgents(compiledName, methodId, stage) {
         "",
         "## 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.",
+        "- `inputs/<artifact-id>/` = read mounts for the current stage.",
+        "- `outputs/<artifact-id>/` = write mounts for the current stage.",
+        "- For file Artifacts, `runtime/paths.json` points to the exact file path inside those mount roots.",
         "- `runtime/source-snapshot.json` = source references captured for this run.",
         "- `runtime/stage-inputs.json` = exact source references assigned to this stage.",
-        "- declared compiled zone paths are also projected at the shell root so Method-relative contract paths stay valid.",
+        "- declared Artifact paths are also projected at the shell root so Method-relative contract paths stay valid.",
         "- `runtime/` = stage contract and machine-readable path map for this shell.",
         "- `method/` = Method metadata, `method.schema.json`, and docs for the current stage only.",
         "",
@@ -348,9 +350,9 @@ function renderStageExecutionAgents(compiledName, methodId, stage) {
         "- This shell has its own AGENTS/CLAUDE/native skills. It does not inherit the portable-context query shell.",
         "- The portable 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/`.",
+        "- Do not modify files under `inputs/` unless the same Artifact is also mounted under `outputs/`.",
         "",
-        "## Current Stage Zones",
+        "## Current Stage Artifacts",
         "",
         `- reads: ${stage.reads.join(", ")}`,
         `- writes: ${stage.writes.join(", ")}`,
@@ -359,7 +361,7 @@ function renderStageExecutionAgents(compiledName, methodId, stage) {
         "",
         "- complete the current stage",
         "- honor the deterministic contract",
-        "- write outputs through the declared zone mounts",
+        "- write outputs through the declared Artifact mounts",
         "- stop when the stage is complete",
         "",
     ].join("\n");
@@ -378,7 +380,7 @@ function renderStageExecutionSkill(stage, stageMethodDoc) {
         "This local native skill exists for automated Interf stage execution.",
         "Read `runtime/stage-contract.json` first.",
         "Then read `runtime/source-snapshot.json`, `runtime/stage-inputs.json`, and `runtime/paths.json`.",
-        "Use the assigned source references and the mounted `inputs/` and `outputs/` zones for this stage.",
+        "Use the assigned source references and the mounted `inputs/` and `outputs/` Artifacts for this stage.",
         "Do not switch into manual query mode.",
         "",
         "## Current Stage",
@@ -440,33 +442,33 @@ function projectMethodMetadata(compiledPath, shellRoot, stage) {
         linkPath(stageDocsPath, join(shellMethodRoot, "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))
+function projectCompiledSchemaArtifacts(compiledPath, shellRoot, schema, artifactIds, materializedArtifactIds) {
+    const allowedArtifactIds = artifactIds ? new Set(artifactIds) : null;
+    for (const artifact of listContextInterfaceArtifacts(schema)) {
+        if (allowedArtifactIds && !allowedArtifactIds.has(artifact.id))
             continue;
-        const sourcePath = compiledZoneAbsolutePath(compiledPath, zone);
-        const targetPath = join(shellRoot, zone.path);
-        if (materializedZoneIds?.has(zone.id)) {
-            ensureShellLocalProjection(sourcePath, targetPath, zone);
+        const sourcePath = compiledArtifactAbsolutePath(compiledPath, artifact);
+        const targetPath = join(shellRoot, artifact.path);
+        if (materializedArtifactIds?.has(artifact.id)) {
+            ensureShellLocalProjection(sourcePath, targetPath, artifact);
             continue;
         }
         linkPath(sourcePath, targetPath);
     }
 }
-function buildStageZoneMounts(compiledPath, shellRoot, stage, schema) {
-    const zones = zoneMap(schema);
-    const mountFor = (zoneId) => {
-        const zone = zoneOrThrow(zones, zoneId);
+function buildStageArtifactMounts(compiledPath, shellRoot, stage, schema) {
+    const artifacts = artifactMap(schema);
+    const mountFor = (artifactId) => {
+        const artifact = artifactOrThrow(artifacts, artifactId);
         return {
-            zone_id: zone.id,
-            compiled_path: zone.path,
-            shell_root_path: zone.path,
-            input_mount_path: stage.reads.includes(zoneId)
-                ? describeShellZoneAliasMountPath(zone, "inputs")
+            artifact_id: artifact.id,
+            artifact_path: artifact.path,
+            shell_root_path: artifact.path,
+            input_mount_path: stage.reads.includes(artifactId)
+                ? describeShellArtifactAliasMountPath(artifact, "inputs")
                 : null,
-            output_mount_path: stage.writes.includes(zoneId)
-                ? describeShellZoneAliasMountPath(zone, "outputs")
+            output_mount_path: stage.writes.includes(artifactId)
+                ? describeShellArtifactAliasMountPath(artifact, "outputs")
                 : null,
         };
     };
@@ -475,16 +477,16 @@ function buildStageZoneMounts(compiledPath, shellRoot, stage, schema) {
         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"));
+function projectStageArtifactMountAliases(shellRoot, stage, schema) {
+    const artifacts = artifactMap(schema);
+    for (const artifactId of new Set([...stage.reads, ...stage.writes])) {
+        const artifact = artifactOrThrow(artifacts, artifactId);
+        const targetPath = join(shellRoot, artifact.path);
+        if (stage.reads.includes(artifactId)) {
+            linkRelativePath(targetPath, shellArtifactAliasMountPath(shellRoot, artifact, "inputs"));
         }
-        if (stage.writes.includes(zoneId)) {
-            linkRelativePath(targetPath, shellZoneAliasMountPath(shellRoot, zone, "outputs"));
+        if (stage.writes.includes(artifactId)) {
+            linkRelativePath(targetPath, shellArtifactAliasMountPath(shellRoot, artifact, "outputs"));
         }
     }
 }
@@ -501,46 +503,46 @@ function writeExecutionShellPathsFile(shellRoot, methodId, stage, mounts) {
 }
 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" &&
+    const artifacts = artifactMap(schema);
+    const stageWriteArtifacts = Array.from(stageWriteArtifactSet(schema, stage))
+        .map((artifactId) => artifactOrThrow(artifacts, artifactId));
+    for (const artifact of stageWriteArtifacts) {
+        const canonicalShellArtifactPath = join(shellRoot, artifact.path);
+        const outputAliasPath = shellArtifactAliasMountPath(shellRoot, artifact, "outputs");
+        const shellArtifactPath = artifact.kind === "file" &&
             existsSync(outputAliasPath) &&
             !lstatSync(outputAliasPath).isSymbolicLink()
             ? outputAliasPath
-            : canonicalShellZonePath;
-        if (!existsSync(shellZonePath))
+            : canonicalShellArtifactPath;
+        if (!existsSync(shellArtifactPath))
             continue;
-        const shellZoneStat = lstatSync(shellZonePath);
-        if (shellZoneStat.isSymbolicLink())
+        const shellArtifactStat = lstatSync(shellArtifactPath);
+        if (shellArtifactStat.isSymbolicLink())
             continue;
-        const compiledZonePath = compiledZoneAbsolutePath(compiledPath, zone);
-        if (shellZoneStat.isDirectory()) {
-            const shellZoneFiles = listFilesRecursive(shellZonePath);
-            const compiledZoneFiles = existsSync(compiledZonePath)
-                ? listFilesRecursive(compiledZonePath)
+        const compiledArtifactPath = compiledArtifactAbsolutePath(compiledPath, artifact);
+        if (shellArtifactStat.isDirectory()) {
+            const shellArtifactFiles = listFilesRecursive(shellArtifactPath);
+            const compiledArtifactFiles = existsSync(compiledArtifactPath)
+                ? listFilesRecursive(compiledArtifactPath)
                 : [];
-            if (shellZoneFiles.length === 0 && compiledZoneFiles.length > 0) {
+            if (shellArtifactFiles.length === 0 && compiledArtifactFiles.length > 0) {
                 continue;
             }
-            rmSync(compiledZonePath, { recursive: true, force: true });
-            mkdirSync(dirname(compiledZonePath), { recursive: true });
-            cpSync(shellZonePath, compiledZonePath, {
+            rmSync(compiledArtifactPath, { recursive: true, force: true });
+            mkdirSync(dirname(compiledArtifactPath), { recursive: true });
+            cpSync(shellArtifactPath, compiledArtifactPath, {
                 recursive: true,
                 force: true,
             });
             continue;
         }
-        mkdirSync(dirname(compiledZonePath), { recursive: true });
-        copyFileSync(shellZonePath, compiledZonePath);
+        mkdirSync(dirname(compiledArtifactPath), { recursive: true });
+        copyFileSync(shellArtifactPath, compiledArtifactPath);
     }
     for (const artifactPath of writeArtifacts) {
         const normalizedArtifactPath = normalizeArtifactRelativePath(artifactPath);
         if (normalizedArtifactPath.length === 0 ||
-            stageWriteZones.some((zone) => relativePathEqualsOrWithin(zone.path, normalizedArtifactPath))) {
+            stageWriteArtifacts.some((artifact) => relativePathEqualsOrWithin(artifact.path, normalizedArtifactPath))) {
             continue;
         }
         const shellArtifactPath = join(shellRoot, normalizedArtifactPath);
@@ -747,9 +749,8 @@ function renderMethodAuthoringAgents(options) {
         "- Edit only files under `method/`.",
         "- Do not edit source artifacts.",
         "- Keep the Method package valid for the current compiler API and `method.schema.json`.",
-        "- Use kebab-case ids everywhere: stage ids, skill_dir values, zone ids, reads/writes values, and package ids. Never use underscores.",
-        "- For acceptance criteria, use `zone_counts_at_least` for numeric fixed minimums and `zone_counts_at_least_counts` only for runtime count-key strings such as `source_total`.",
-        "- For file output zones that replace scaffold files, add `artifacts_must_not_contain` entries that reject `Not yet compiled.` placeholder text; its keys must be artifact paths like `home.md`, not zone ids like `home`.",
+        "- Use kebab-case ids everywhere: stage ids, skill_dir values, Artifact ids, reads/writes values, and package ids. Never use underscores.",
+        "- Put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks.",
         "- 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.",
         "",
@@ -757,7 +758,8 @@ function renderMethodAuthoringAgents(options) {
         "",
         "- produce one standalone Method package tuned to the source data, desired outputs, and checks in this task",
         "- replace the neutral scaffold topology with the stage graph this agent work needs",
-        "- define output zones and stage proof so Interf can show whether the data is ready",
+        "- define Artifacts and checks so Interf can show whether the data is ready",
+        "- satisfy every `artifact_requirements[]` entry from `runtime/authoring-context.json` when entries are present",
         "- preserve deterministic stage and context-interface contracts",
         "- stop once the Method edits are complete",
         "",
@@ -779,10 +781,12 @@ function renderMethodAuthoringSkill() {
         "Rules:",
         "- edit only `method/`",
         `- keep \`method.json\`, \`${METHOD_SCHEMA_FILE}\`, and any changed stage docs aligned`,
-        "- use `zone_counts_at_least` for numeric fixed minimums; use `zone_counts_at_least_counts` only for runtime count-key strings such as `source_total`",
-        "- for file output zones that replace scaffold files, add `artifacts_must_not_contain` entries that reject `Not yet compiled.` placeholder text; its keys must be artifact paths like `home.md`, not zone ids like `home`",
+        "- put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks",
+        "- use only CheckKind values listed in `runtime/authoring-context.json`; do not invent aliases",
+        "- keep Artifact checks and the producing stage docs aligned",
+        "- satisfy every `artifact_requirements[]` entry from `runtime/authoring-context.json` when entries are present",
         "- design the stage graph from the source data and preparation-and-evidence brief",
-        "- use kebab-case ids everywhere: stage ids, skill_dir values, zone ids, reads/writes values, and package ids; never use underscores",
+        "- use kebab-case ids everywhere: stage ids, skill_dir values, Artifact ids, reads/writes values, and package ids; never use underscores",
         "- replace the placeholder `prepare` stage unless that exact stage is truly the final method",
         "- keep the package standalone; do not introduce runtime inheritance or hidden source-package assumptions",
         "- do not introduce wikilinks unless the Method also creates the target note by exact basename or explicit relative path",
@@ -790,7 +794,7 @@ function renderMethodAuthoringSkill() {
         "- 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 readiness-check answers into Method docs",
+        "- do not hardcode readiness-check answers into reusable Method docs",
         "- do not edit source artifacts",
         "",
     ].join("\n");
@@ -812,6 +816,8 @@ export function createMethodAuthoringShell(options) {
         method_label: options.label,
         ...(options.referenceMethodId ? { reference_method_id: options.referenceMethodId } : {}),
         task_prompt: options.taskPrompt,
+        allowed_check_kinds: CHECK_KINDS,
+        artifact_requirements: options.artifactRequirements ?? [],
         preparation: {
             source_folder_path: options.sourceFolderPath,
             checks: {
@@ -866,7 +872,7 @@ function renderMethodImprovementAgents(compiledName, methodId, loopIndex) {
         "- Do not edit checks, test specs, source files, or generated context outputs.",
         "- Review context outputs under `artifacts/compiled-view/` and test/runtime evidence under `artifacts/`.",
         "- Keep the Method package valid for the current compiler API and `method.schema.json`.",
-        "- For acceptance criteria, use `zone_counts_at_least` for numeric fixed minimums and `zone_counts_at_least_counts` only for runtime count-key strings such as `source_total`.",
+        "- Put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks.",
         "",
         "## Goal",
         "",
@@ -916,15 +922,15 @@ function renderMethodImprovementSkill(methodId, loopIndex, improvementDoc) {
 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 === "source-files")
+    for (const artifact of listContextInterfaceArtifacts(schema)) {
+        if (artifact.kind === "runtime" || artifact.path === "source-files")
             continue;
-        const sourcePath = compiledZoneAbsolutePath(compiledPath, zone);
+        const sourcePath = compiledArtifactAbsolutePath(compiledPath, artifact);
         if (!existsSync(sourcePath))
             continue;
         copyResolvedTree({
             sourcePath,
-            targetPath: join(compiledViewRoot, zone.path),
+            targetPath: join(compiledViewRoot, artifact.path),
             shellType: "method-improvement",
         });
     }
@@ -970,21 +976,22 @@ export function projectSourceFilesTestQueryShell(rootPath) {
 }
 export function createStageExecutionShell(compiledPath, compiledName, methodId, stage, writeArtifacts = []) {
     const schema = ensureCompiledExecutionSurface(compiledPath);
-    const materializedZones = stageMaterializedZoneSet(schema, stage, writeArtifacts);
+    const materializedArtifacts = stageMaterializedArtifactSet(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, ".interf", "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"));
     linkIfExists(compiledRuntimeSourceSnapshotPath(compiledPath), shellRuntimePath(shellRoot, "source-snapshot.json"));
     linkIfExists(compiledRuntimeStageInputsPath(compiledPath, stage.id), shellRuntimePath(shellRoot, "stage-inputs.json"));
-    projectCompiledSchemaZones(compiledPath, shellRoot, schema, new Set([...stage.reads, ...stage.writes]), materializedZones);
+    projectCompiledSchemaArtifacts(compiledPath, shellRoot, schema, new Set([...stage.reads, ...stage.writes]), materializedArtifacts);
     projectMethodMetadata(compiledPath, shellRoot, stage);
-    projectStageZoneMountAliases(shellRoot, stage, schema);
-    writeExecutionShellPathsFile(shellRoot, methodId, stage, buildStageZoneMounts(compiledPath, shellRoot, stage, schema));
+    projectStageArtifactMountAliases(shellRoot, stage, schema);
+    writeExecutionShellPathsFile(shellRoot, methodId, stage, buildStageArtifactMounts(compiledPath, shellRoot, stage, schema));
     const agentsContent = renderStageExecutionAgents(compiledName, methodId, stage);
     writeNativeAgentSurface(shellRoot, agentsContent, "interf-stage", renderStageExecutionSkill(stage, readStageMethodDoc(compiledPath, stage)));
     return {

package/dist/packages/{agents → engine/agents}/lib/user-config.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { readJsonFileWithSchema } from "../../shared/parse.js";
-import { interfHomeRoot } from "../../contracts/lib/preparation-paths.js";
+import { readJsonFileWithSchema } from "../../../contracts/utils/parse.js";
+import { interfHomeRoot } from "../../../contracts/lib/preparation-paths.js";
 import { InterfUserConfigSchema } from "./schema.js";
 /** `~/.interf/` (overridable via `INTERF_USER_HOME`). */
 export function interfHome() {

package/dist/packages/engine/agents/registry.d.ts

@@ -0,0 +1,91 @@
+import { type AgentRecord, type AgentsRegistry, type RoleMap } from "../../contracts/lib/schema.js";
+export declare const AGENTS_REGISTRY_FILENAME = "agents.json";
+/** `~/.interf/agents.json` — persisted custom agents + role-map. */
+export declare function agentsRegistryPath(): string;
+/**
+ * Load just the persisted on-disk part of the registry. Built-in agents
+ * are NOT included — call `loadAgentsRegistry()` for the merged view.
+ *
+ * Returns `{ agents: [], role_map: {} }` when the file is missing or
+ * unreadable; persisted custom agents always have `source: "user"`.
+ */
+export declare function loadPersistedRegistry(): AgentsRegistry;
+/** Persist the on-disk part of the registry (custom agents + role-map). */
+export declare function savePersistedRegistry(registry: AgentsRegistry): void;
+/**
+ * Detect built-in agents present on this machine. Filtered to agents
+ * whose marker home directory exists; we do NOT require the command
+ * to be on PATH at registry read time — that's a runtime concern.
+ */
+export declare function detectBuiltinAgentRecords(): AgentRecord[];
+/**
+ * Same as `detectBuiltinAgentRecords()` but only includes agents the
+ * current Interf build can fully drive (Claude Code, Codex). Used by
+ * the role-router and the CLI / UI listing as the "available agents"
+ * set.
+ */
+export declare function detectAutomatableBuiltinAgentRecords(): AgentRecord[];
+/**
+ * Full advertisement set — all built-in agents Interf knows about,
+ * regardless of whether they are installed locally. Used by the
+ * "install cards" zero-state surface so the UI / wizard can offer
+ * the user choices to install.
+ */
+export declare function listKnownBuiltinAgents(): AgentRecord[];
+export interface ResolvedRegistry {
+    /** All currently usable agents — built-in detected + persisted custom. */
+    agents: AgentRecord[];
+    /** Role → agent-name. Includes any persisted user edits. */
+    roleMap: RoleMap;
+    /**
+     * The "active" / default agent. This is whatever the role-map's
+     * `general` row points at, falling back to the first available
+     * agent when `general` is unset or maps to something that no longer
+     * exists in `agents`.
+     */
+    activeAgent: AgentRecord | null;
+}
+/**
+ * Public entry point — read the persisted registry, merge with detected
+ * built-ins, and seed the default role-map on first read if needed.
+ *
+ * Does NOT write back to disk. Callers that mutate the registry should
+ * call `savePersistedRegistry()` explicitly with the persisted slice.
+ */
+export declare function loadAgentsRegistry(): ResolvedRegistry;
+/** Pure helper — like `loadAgentsRegistry()` but works off in-memory data. */
+export declare function resolveRegistry(persisted: AgentsRegistry, builtinDetected: AgentRecord[]): ResolvedRegistry;
+/**
+ * Update the role-map (full replace). Returns the persisted slice that
+ * was written.
+ */
+export declare function updateRoleMap(nextRoleMap: RoleMap): AgentsRegistry;
+/**
+ * Patch the role-map with a partial update. Empty-string values clear
+ * the role (it falls back to `general` / active agent at run time).
+ */
+export declare function patchRoleMap(patch: Record<string, string>): AgentsRegistry;
+/**
+ * Register a new custom agent. Throws if `name` collides with a known
+ * built-in or with an already-persisted custom agent.
+ */
+export declare function registerCustomAgent(input: {
+    name: string;
+    display_name: string;
+    command: string;
+}): AgentsRegistry;
+/**
+ * Unregister a custom agent. Throws if `name` matches a built-in or no
+ * custom record exists. Removes any role-map entry pointing at the
+ * removed agent.
+ */
+export declare function unregisterCustomAgent(name: string): AgentsRegistry;
+/**
+ * Set the "active" agent — i.e. the agent the role-map's `general` row
+ * points at. Also updates any role still pointing at the previous
+ * active agent so existing single-active-agent setups don't need
+ * per-role edits when switching agents.
+ *
+ * Throws if `name` is not in the merged agents list.
+ */
+export declare function setActiveAgent(name: string): AgentsRegistry;