@interf/compiler 0.3.4 → 0.4.0

package/dist/lib/local-workflows.js

@@ -1,12 +1,14 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { z } from "zod";
+import { PACKAGE_ROOT } from "./config.js";
 import { isMarkdownFile } from "./util.js";
 import { listFilesRecursive } from "./filesystem.js";
 import { warnInterf } from "./logger.js";
 import { readJsonFileUnchecked, readJsonFileWithSchema } from "./parse.js";
+import { listBuiltinWorkspaceZoneSpecs, validateWorkspaceContractSequence, } from "./workflow-abi.js";
 import { WorkflowCompilerApiSchema, RuntimeContractTypeSchema, RuntimeStageAcceptanceSchema, WorkflowStageZoneAccessSchema, WorkflowWorkspaceSchemaSchema, WorkflowIdPattern, } from "./schema.js";
-import { BUILTIN_WORKSPACE_ZONE_IDS, writeWorkspaceSchemaFile, workspaceSchemaFilePath, } from "./workspace-schema.js";
+import { writeWorkspaceSchemaFile, workspaceSchemaFilePath } from "./workspace-schema.js";
 const LocalWorkflowStageDefinitionSchema = z.object({
     id: z.string().regex(WorkflowIdPattern),
     label: z.string().min(1),
@@ -27,24 +29,31 @@ const LocalWorkflowDefinitionSchema = z.object({
     stages: z.array(LocalWorkflowStageDefinitionSchema).min(1).optional(),
     stage_policy_notes: z.record(z.string(), z.array(z.string())).optional(),
 }).superRefine((value, ctx) => {
-    const allowed = new Set([
-        "workspace-file-evidence",
-        "workspace-knowledge-structure",
-        "workspace-query-shape",
-    ]);
-    for (const [index, stage] of (value.stages ?? []).entries()) {
-        if (!allowed.has(stage.contract_type)) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                path: ["stages", index, "contract_type"],
-                message: `contract_type "${stage.contract_type}" is not valid for workspace workflows`,
-            });
-        }
+    const stages = value.stages ?? [];
+    if (stages.length === 0)
+        return;
+    const sequence = validateWorkspaceContractSequence(stages.map((stage) => stage.contract_type));
+    if (!sequence.orderValid) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["stages"],
+            message: "Workspace workflow stages must keep non-decreasing order: file-evidence -> knowledge-structure -> query-shape.",
+        });
+    }
+    for (const missing of sequence.missing) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["stages"],
+            message: `Workspace workflows must include at least one ${missing} stage.`,
+        });
     }
 });
 function workflowRootPath(sourcePath) {
     return join(sourcePath, "interf", "workflows");
 }
+function builtinWorkflowRootPath(workflowId) {
+    return join(PACKAGE_ROOT, "builtin-workflows", workflowId);
+}
 export function workflowDefinitionPath(sourcePath, id) {
     return join(workflowRootPath(sourcePath), id);
 }
@@ -104,9 +113,162 @@ export function listLocalWorkflowDefinitions(sourcePath) {
 export function loadLocalWorkflowDefinition(sourcePath, id) {
     return loadWorkflowDefinitionFromDir(workflowDefinitionPath(sourcePath, id));
 }
+export function resolveWorkflowPackageSourcePath(sourcePath, workflowId) {
+    const builtinPath = builtinWorkflowRootPath(workflowId);
+    if (workflowId === "interf" && existsSync(join(builtinPath, "workflow.json")))
+        return builtinPath;
+    const localPath = workflowDefinitionPath(sourcePath, workflowId);
+    if (existsSync(join(localPath, "workflow.json")))
+        return localPath;
+    if (existsSync(join(builtinPath, "workflow.json")))
+        return builtinPath;
+    return null;
+}
 export function isWorkflowId(value) {
     return WorkflowIdPattern.test(value);
 }
+function normalizeStagePolicyNotes(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const normalized = {};
+    for (const [stageId, notes] of Object.entries(value)) {
+        if (!Array.isArray(notes))
+            continue;
+        const cleaned = Array.from(new Set(notes
+            .filter((note) => typeof note === "string")
+            .map((note) => note.trim())
+            .filter((note) => note.length > 0)));
+        if (cleaned.length > 0) {
+            normalized[stageId] = cleaned;
+        }
+    }
+    return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+function mergeStagePolicyNotes(currentValue, nextValue) {
+    const current = normalizeStagePolicyNotes(currentValue);
+    if (!nextValue || Object.keys(nextValue).length === 0)
+        return current;
+    const merged = { ...(current ?? {}) };
+    for (const [stageId, notes] of Object.entries(nextValue)) {
+        merged[stageId] = Array.from(new Set([
+            ...(merged[stageId] ?? []),
+            ...notes.map((note) => note.trim()).filter((note) => note.length > 0),
+        ]));
+    }
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+function readWorkflowJsonObject(dirPath) {
+    const workflowPath = join(dirPath, "workflow.json");
+    const raw = readJsonFileUnchecked(workflowPath, "workflow package");
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`Workflow package at ${dirPath} is missing a valid workflow.json.`);
+    }
+    return { ...raw };
+}
+export function patchWorkflowPackageMetadata(dirPath, options = {}) {
+    const workflowPath = join(dirPath, "workflow.json");
+    const schemaPath = workspaceSchemaFilePath(dirPath);
+    const workflowJson = readWorkflowJsonObject(dirPath);
+    const normalizedStages = Array.isArray(workflowJson.stages) && workflowJson.stages.length > 0
+        ? workflowJson.stages
+        : null;
+    if (!normalizedStages) {
+        throw new Error(`Cannot patch workflow package at ${dirPath}: workflow.json must declare explicit stages before it can be copied or rewritten.`);
+    }
+    const nextWorkflowJson = {
+        ...workflowJson,
+        type: "workspace",
+        compiler_api: workflowJson.compiler_api ?? {
+            kind: "workspace",
+            version: 1,
+        },
+        stages: normalizedStages,
+        ...(options.id ? { id: options.id } : {}),
+        ...(options.label ? { label: options.label } : {}),
+        ...(options.hint ? { hint: options.hint } : {}),
+    };
+    delete nextWorkflowJson.extends;
+    const mergedStagePolicyNotes = mergeStagePolicyNotes(workflowJson.stage_policy_notes, options.stagePolicyNotes);
+    if (mergedStagePolicyNotes) {
+        nextWorkflowJson.stage_policy_notes = mergedStagePolicyNotes;
+    }
+    else {
+        delete nextWorkflowJson.stage_policy_notes;
+    }
+    writeFileSync(workflowPath, JSON.stringify(nextWorkflowJson, null, 2) + "\n");
+    const schemaLabel = `${String(nextWorkflowJson.label ?? workflowJson.label ?? options.id ?? "Workflow")} workspace schema`;
+    if (!existsSync(schemaPath)) {
+        writeWorkspaceSchemaFile(dirPath, normalizedStages, schemaLabel);
+        return;
+    }
+    const rawSchema = readJsonFileUnchecked(schemaPath, "workspace schema");
+    if (!rawSchema || typeof rawSchema !== "object" || Array.isArray(rawSchema))
+        return;
+    writeFileSync(schemaPath, JSON.stringify({
+        ...rawSchema,
+        label: schemaLabel,
+    }, null, 2) + "\n");
+}
+export function describeWorkflowPackagePortability(dirPath) {
+    const issues = [];
+    const workflowPath = join(dirPath, "workflow.json");
+    const schemaPath = workspaceSchemaFilePath(dirPath);
+    if (!existsSync(workflowPath))
+        issues.push("missing workflow.json");
+    if (!existsSync(schemaPath))
+        issues.push("missing workspace.schema.json");
+    if (!existsSync(join(dirPath, "README.md")))
+        issues.push("missing README.md");
+    if (!existsSync(join(dirPath, "improve", "SKILL.md")))
+        issues.push("missing improve/SKILL.md");
+    if (!existsSync(join(dirPath, "use", "query", "SKILL.md")))
+        issues.push("missing use/query/SKILL.md");
+    if (issues.length > 0)
+        return issues;
+    let workflowJson;
+    try {
+        workflowJson = readWorkflowJsonObject(dirPath);
+    }
+    catch (error) {
+        issues.push(error instanceof Error ? error.message : String(error));
+        return issues;
+    }
+    const parsed = LocalWorkflowDefinitionSchema.safeParse(workflowJson);
+    if (!parsed.success) {
+        issues.push(...parsed.error.issues.map((issue) => issue.path.length > 0
+            ? `workflow.json ${issue.path.join(".")}: ${issue.message}`
+            : `workflow.json: ${issue.message}`));
+        return issues;
+    }
+    if (typeof parsed.data.extends === "string" && parsed.data.extends.trim().length > 0) {
+        issues.push("workflow.json uses legacy extends; portable workflow packages must be materialized standalone");
+    }
+    if (!parsed.data.stages || parsed.data.stages.length === 0) {
+        issues.push("workflow.json must declare explicit stages for a portable workflow package");
+        return issues;
+    }
+    for (const stage of parsed.data.stages) {
+        const skillDir = typeof stage.skill_dir === "string" && stage.skill_dir.trim().length > 0
+            ? stage.skill_dir
+            : stage.id;
+        if (!existsSync(join(dirPath, "compile", "stages", skillDir, "SKILL.md"))) {
+            issues.push(`missing compile/stages/${skillDir}/SKILL.md`);
+        }
+    }
+    return issues;
+}
+export function isPortableWorkflowPackage(dirPath) {
+    return describeWorkflowPackagePortability(dirPath).length === 0;
+}
+export function copyWorkflowPackageDirectory(sourceWorkflowPath, targetWorkflowPath) {
+    const portabilityIssues = describeWorkflowPackagePortability(sourceWorkflowPath);
+    if (portabilityIssues.length > 0) {
+        throw new Error(`Workflow package at ${sourceWorkflowPath} is not directly copyable: ${portabilityIssues.join("; ")}.`);
+    }
+    rmSync(targetWorkflowPath, { recursive: true, force: true });
+    mkdirSync(dirname(targetWorkflowPath), { recursive: true });
+    cpSync(sourceWorkflowPath, targetWorkflowPath, { recursive: true });
+}
 export function validateWorkflowPackage(dirPath) {
     const workflowPath = join(dirPath, "workflow.json");
     const schemaPath = workspaceSchemaFilePath(dirPath);
@@ -139,70 +301,53 @@ export function validateWorkflowPackage(dirPath) {
     }
     const def = parsed.data;
     const errors = [];
+    if (typeof def.extends === "string" && def.extends.trim().length > 0) {
+        errors.push("workflow.json uses legacy extends. Portable workflow packages must be materialized as standalone packages.");
+    }
+    if (!def.stages || def.stages.length === 0) {
+        errors.push("workflow.json must declare explicit stages. Legacy inherited packages are not portable.");
+    }
     if (!existsSync(schemaPath)) {
         errors.push("Missing workspace.schema.json.");
     }
+    if (!existsSync(join(dirPath, "README.md"))) {
+        errors.push("Missing README.md.");
+    }
+    if (!existsSync(join(dirPath, "improve", "SKILL.md"))) {
+        errors.push("Missing improve/SKILL.md.");
+    }
+    if (!existsSync(join(dirPath, "use", "query", "SKILL.md"))) {
+        errors.push("Missing use/query/SKILL.md.");
+    }
     const workspaceSchema = readJsonFileWithSchema(schemaPath, "workspace schema", WorkflowWorkspaceSchemaSchema);
     if (!workspaceSchema) {
         errors.push("workspace.schema.json is missing or invalid.");
     }
     if (def.stages && def.stages.length > 0) {
-        const order = new Map([
-            ["workspace-file-evidence", 0],
-            ["workspace-knowledge-structure", 1],
-            ["workspace-query-shape", 2],
-        ]);
         const contractTypes = def.stages.map((stage) => stage.contract_type);
+        const sequence = validateWorkspaceContractSequence(contractTypes);
         if (def.stages.length < 3) {
             errors.push("Workspace workflows must include summarize, structure, and shape stages in order.");
         }
-        else if (!contractTypes.every((contractType, index) => index === 0 || (order.get(contractType) ?? -1) >= (order.get(contractTypes[index - 1]) ?? -1))) {
+        else if (!sequence.orderValid) {
             errors.push("Workspace workflow stages must keep non-decreasing order: file-evidence -> knowledge-structure -> query-shape.");
         }
         else {
-            if (!contractTypes.includes("workspace-file-evidence")) {
-                errors.push("Workspace workflows must include at least one workspace-file-evidence stage.");
+            for (const missing of sequence.missing) {
+                errors.push(`Workspace workflows must include at least one ${missing} stage.`);
             }
-            if (!contractTypes.includes("workspace-knowledge-structure")) {
-                errors.push("Workspace workflows must include at least one workspace-knowledge-structure stage.");
-            }
-            if (!contractTypes.includes("workspace-query-shape")) {
-                errors.push("Workspace workflows must include at least one workspace-query-shape stage.");
+        }
+        for (const stage of def.stages) {
+            const skillDir = typeof stage.skill_dir === "string" && stage.skill_dir.trim().length > 0
+                ? stage.skill_dir
+                : stage.id;
+            if (!existsSync(join(dirPath, "compile", "stages", skillDir, "SKILL.md"))) {
+                errors.push(`Missing compile/stages/${skillDir}/SKILL.md.`);
             }
         }
     }
     if (workspaceSchema) {
-        const fallbackStages = [
-            {
-                id: "summarize",
-                reads: [BUILTIN_WORKSPACE_ZONE_IDS.RAW, BUILTIN_WORKSPACE_ZONE_IDS.RUNTIME],
-                writes: [BUILTIN_WORKSPACE_ZONE_IDS.SUMMARIES],
-            },
-            {
-                id: "structure",
-                reads: [BUILTIN_WORKSPACE_ZONE_IDS.SUMMARIES, BUILTIN_WORKSPACE_ZONE_IDS.RUNTIME],
-                writes: [
-                    BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_ENTITIES,
-                    BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_CLAIMS,
-                    BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_INDEXES,
-                ],
-            },
-            {
-                id: "shape",
-                reads: [
-                    BUILTIN_WORKSPACE_ZONE_IDS.SUMMARIES,
-                    BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_ENTITIES,
-                    BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_CLAIMS,
-                    BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_INDEXES,
-                    BUILTIN_WORKSPACE_ZONE_IDS.RUNTIME,
-                ],
-                writes: [
-                    BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_INDEXES,
-                    BUILTIN_WORKSPACE_ZONE_IDS.HOME,
-                ],
-            },
-        ];
-        const stages = def.stages ?? fallbackStages;
+        const stages = def.stages ?? [];
         const stageIds = new Set(stages.map((stage) => stage.id));
         const seenPaths = new Map();
         const seenZoneIds = new Set();
@@ -255,16 +400,7 @@ export function validateWorkflowPackage(dirPath) {
                 }
             }
         }
-        const requiredZones = [
-            { id: BUILTIN_WORKSPACE_ZONE_IDS.RAW, path: "raw", kind: "directory" },
-            { id: BUILTIN_WORKSPACE_ZONE_IDS.SUMMARIES, path: "summaries", kind: "directory" },
-            { id: BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_ENTITIES, path: "knowledge/entities", kind: "directory" },
-            { id: BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_CLAIMS, path: "knowledge/claims", kind: "directory" },
-            { id: BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_INDEXES, path: "knowledge/indexes", kind: "directory" },
-            { id: BUILTIN_WORKSPACE_ZONE_IDS.HOME, path: "home.md", kind: "file" },
-            { id: BUILTIN_WORKSPACE_ZONE_IDS.RUNTIME, path: ".interf", kind: "runtime" },
-        ];
-        for (const requiredZone of requiredZones) {
+        for (const requiredZone of listBuiltinWorkspaceZoneSpecs()) {
             const match = zoneById.get(requiredZone.id);
             if (!match) {
                 errors.push(`workspace.schema.json is missing required zone "${requiredZone.id}".`);
@@ -278,7 +414,9 @@ export function validateWorkflowPackage(dirPath) {
             }
         }
     }
-    const stageDirs = listFilesRecursive(join(dirPath, "compile", "stages"), (filePath) => basename(filePath) === "SKILL.md");
+    const stageDirs = existsSync(join(dirPath, "compile", "stages"))
+        ? listFilesRecursive(join(dirPath, "compile", "stages"), (filePath) => basename(filePath) === "SKILL.md")
+        : [];
     const counts = {
         starter_docs: collectStarterDocs(dirPath).length,
         compile_stage_docs: stageDirs.length,
@@ -291,33 +429,6 @@ export function validateWorkflowPackage(dirPath) {
         counts,
     };
 }
-export function writeLocalWorkflowDefinition(sourcePath, id, workflowJson, docs) {
-    const root = workflowDefinitionPath(sourcePath, id);
-    mkdirSync(root, { recursive: true });
-    const normalizedWorkflowJson = {
-        compiler_api: {
-            kind: "workspace",
-            version: 1,
-        },
-        ...workflowJson,
-    };
-    writeFileSync(join(root, "workflow.json"), JSON.stringify(normalizedWorkflowJson, null, 2) + "\n");
-    const stages = Array.isArray(normalizedWorkflowJson.stages)
-        ? (normalizedWorkflowJson.stages)
-        : [
-            { id: "summarize", contract_type: "workspace-file-evidence" },
-            { id: "structure", contract_type: "workspace-knowledge-structure" },
-            { id: "shape", contract_type: "workspace-query-shape" },
-        ];
-    writeWorkspaceSchemaFile(root, stages, `${String(normalizedWorkflowJson.label ?? id)} workspace schema`);
-    for (const doc of docs) {
-        const targetPath = join(root, doc.relativePath);
-        mkdirSync(dirname(targetPath), { recursive: true });
-        writeFileSync(targetPath, doc.content);
-    }
-    return root;
-}
 function basename(filePath) {
     return filePath.split(/[\\/]/).pop() ?? filePath;
 }
-//# sourceMappingURL=local-workflows.js.map

package/dist/lib/logger.d.ts

@@ -1,4 +1,3 @@
 export type InterfWarningHandler = (message: string) => void;
 export declare function setInterfWarningHandler(handler?: InterfWarningHandler): void;
 export declare function warnInterf(message: string): void;
-//# sourceMappingURL=logger.d.ts.map

package/dist/lib/logger.js

@@ -8,4 +8,3 @@ export function setInterfWarningHandler(handler) {
 export function warnInterf(message) {
     currentWarningHandler(message);
 }
-//# sourceMappingURL=logger.js.map

package/dist/lib/obsidian.d.ts

@@ -1,2 +1 @@
 export declare function writeObsidianDefaults(dirPath: string, type: "workspace"): void;
-//# sourceMappingURL=obsidian.d.ts.map

package/dist/lib/obsidian.js

@@ -13,4 +13,3 @@ export function writeObsidianDefaults(dirPath, type) {
     };
     writeFileSync(join(obsidianDir, "graph.json"), JSON.stringify(graphSettings, null, 2) + "\n");
 }
-//# sourceMappingURL=obsidian.js.map

package/dist/lib/parse.d.ts

@@ -6,4 +6,3 @@ export declare function parseJsonFrontmatter(content: string): {
     frontmatter: Record<string, unknown>;
     body: string;
 } | null;
-//# sourceMappingURL=parse.d.ts.map

package/dist/lib/parse.js

@@ -52,4 +52,3 @@ export function parseJsonFrontmatter(content) {
         return null;
     }
 }
-//# sourceMappingURL=parse.js.map

package/dist/lib/registry.d.ts

@@ -14,4 +14,3 @@ export declare function listWorkspaceEntries(registry?: Registry): WorkspaceEntr
 export declare function addWorkspace(name: string, path: string, workflow: string): void;
 export declare function findWorkspaceByName(name: string): WorkspaceEntry[];
 export declare function findInterf(name: string): WorkspaceEntry | undefined;
-//# sourceMappingURL=registry.d.ts.map

package/dist/lib/registry.js

@@ -63,4 +63,3 @@ export function findInterf(name) {
     const matches = listWorkspaceEntries().filter((workspace) => workspace.name === name);
     return matches.length === 1 ? matches[0] : undefined;
 }
-//# sourceMappingURL=registry.js.map

package/dist/lib/runtime-acceptance.d.ts

@@ -1,4 +1,3 @@
 import { type RuntimeStageContract } from "./schema.js";
 import { type RuntimeStageAcceptanceValidation } from "./runtime-types.js";
 export declare function validateStageContractAcceptance(dirPath: string, contract?: RuntimeStageContract | null): RuntimeStageAcceptanceValidation;
-//# sourceMappingURL=runtime-acceptance.d.ts.map

package/dist/lib/runtime-acceptance.js

@@ -68,7 +68,7 @@ export function validateStageContractAcceptance(dirPath, contract = null) {
         };
     }
     const failures = [];
-    const state = readWorkspaceJsonFile(dirPath, ".interf/state.json");
+    const state = readWorkspaceJsonFile(dirPath, ".interf/runtime/state.json");
     for (const relativePath of acceptance?.artifacts_exist ?? []) {
         if (!existsSync(join(dirPath, relativePath))) {
             failures.push(`Missing required artifact: ${relativePath}.`);
@@ -120,4 +120,3 @@ export function validateStageContractAcceptance(dirPath, contract = null) {
         failures,
     };
 }
-//# sourceMappingURL=runtime-acceptance.js.map

package/dist/lib/runtime-contracts.d.ts

@@ -2,4 +2,3 @@ import { type RuntimeStageContractDraft, type WorkspaceKnowledgeContractOptions,
 export declare function buildWorkspaceSummarizeContract(options: WorkspaceSummarizeContractOptions): RuntimeStageContractDraft;
 export declare function buildWorkspaceStructureContract(options: WorkspaceKnowledgeContractOptions): RuntimeStageContractDraft;
 export declare function buildWorkspaceShapeContract(options: WorkspaceShapeContractOptions): RuntimeStageContractDraft;
-//# sourceMappingURL=runtime-contracts.d.ts.map

package/dist/lib/runtime-contracts.js

@@ -1,3 +1,4 @@
+import { CHART_APPROXIMATION_NOTES } from "./chart-guidance.js";
 export function buildWorkspaceSummarizeContract(options) {
     const localSkillDocs = options.localSkillDocs ?? [];
     const workflowNotes = options.workflowNotes ?? [];
@@ -14,12 +15,12 @@ export function buildWorkspaceSummarizeContract(options) {
                 "interf.json",
                 options.planPath,
                 "workflow/workspace.schema.json",
-                ".interf/raw-snapshot.json",
+                ".interf/runtime/raw-snapshot.json",
                 ...localSkillDocs,
             ],
             writes: [
                 "summaries/",
-                ".interf/inventory.json",
+                ".interf/runtime/inventory.json",
             ],
             verifies: [
                 "interf verify summarize --json",
@@ -39,10 +40,10 @@ export function buildWorkspaceSummarizeContract(options) {
                 "Also include a `## Abstract` section or another clearly labeled abstract block so humans can scan the summary quickly.",
                 "Use cautious, source-grounded titles. Summary filenames should describe what the file is or records without overstating uncertain conclusions.",
                 "If links are added, keep them minimal and source-grounded.",
-                "Do not precreate `.interf/inventory.json` with placeholder writes. Write the final JSON document directly.",
-                "When updating `.interf/inventory.json`, rewrite the full JSON document in one whole-file write instead of patching partial lines.",
-                "The CLI reconciles `.interf/state.json` and refreshes `.interf/health.json` after stage validation. Do not treat those files as stage-owned write targets for this stage.",
-                "Prefer the current inventory runtime shape: `.interf/inventory.json` should use `entries` plus `total`, with one object per source file containing at least `source`, `summary`, and a conservative status/state field.",
+                "Do not precreate `.interf/runtime/inventory.json` with placeholder writes. Write the final JSON document directly.",
+                "When updating `.interf/runtime/inventory.json`, rewrite the full JSON document in one whole-file write instead of patching partial lines.",
+                "The CLI reconciles `.interf/runtime/state.json` and refreshes `.interf/runtime/health.json` after stage validation. Do not treat those files as stage-owned write targets for this stage.",
+                "Prefer the current inventory runtime shape: `.interf/runtime/inventory.json` should use `entries` plus `total`, with one object per source file containing at least `source`, `summary`, and a conservative status/state field.",
                 "Keep scratch extraction commands single-purpose and non-destructive. Do not use `rm`, wildcard cleanup, `;`, or `&&` chains during summarize.",
                 "Use `workflow/workspace.schema.json` as the deterministic output-shape reference for this workspace.",
                 "The workspace includes its own `raw/` snapshot. Read source files there when summary evidence depends on direct inspection.",
@@ -78,7 +79,7 @@ export function buildWorkspaceStructureContract(options) {
                 "interf.json",
                 "workflow/workspace.schema.json",
                 "summaries/",
-                ".interf/inventory.json",
+                ".interf/runtime/inventory.json",
                 ...localSkillDocs,
             ],
             writes: [
@@ -137,6 +138,7 @@ export function buildWorkspaceShapeContract(options) {
                 "interf.json",
                 "workflow/workspace.schema.json",
                 options.shapeInputPath,
+                "raw/",
                 "knowledge/entities/",
                 "knowledge/claims/",
                 "knowledge/indexes/",
@@ -158,7 +160,12 @@ export function buildWorkspaceShapeContract(options) {
                 `Use ${options.shapeInputPath} as the shaping input for this workspace.`,
                 "The shaping input provides the workspace focus plus saved truth-check question text only. It does not provide expected answers.",
                 "Use the focus and saved truth checks to bias routing, navigation, priority notes, and the final workspace home.",
+                "Replace any scaffold or placeholder content in `home.md`. The final home note must not keep the initial `Not yet compiled.` message.",
                 "Do not copy expected answers into the workspace or treat the checks as license to hallucinate missing evidence.",
+                "When a focused question depends on chart-derived or table-derived evidence, prefer the saved summaries and structured notes if they already preserve the needed bounded reads plus provenance.",
+                "Use `raw/` during shaping only when the compiled layer is missing the needed value, the metric family is ambiguous, or the earlier bounded read is clearly inconsistent.",
+                "Carry the final bounded reads forward into focused indexes with clear provenance instead of repeatedly recomputing them from `raw/`.",
+                ...CHART_APPROXIMATION_NOTES,
                 "Use `workflow/workspace.schema.json` as the deterministic output-shape reference for this workspace.",
                 "Prefer better retrieval routes, tighter home.md guidance, and focused indexes over speculative synthesis.",
                 ...workflowNotes,
@@ -182,4 +189,3 @@ export function buildWorkspaceShapeContract(options) {
         },
     };
 }
-//# sourceMappingURL=runtime-contracts.js.map

package/dist/lib/runtime-paths.d.ts

@@ -5,4 +5,3 @@ export declare function logsDirPath(dirPath: string): string;
 export declare function promptLogPath(dirPath: string, runId: string): string;
 export declare function eventLogPath(dirPath: string, runId: string): string;
 export declare function statusLogPath(dirPath: string, runId: string): string;
-//# sourceMappingURL=runtime-paths.d.ts.map

package/dist/lib/runtime-paths.js

@@ -1,20 +1,16 @@
 import { join } from "node:path";
-import { STATE_DIR } from "./util.js";
-const RUN_FILE = "run.json";
-const RUN_HISTORY_FILE = "run-history.jsonl";
-const STAGE_CONTRACT_FILE = "stage-contract.json";
-const LOGS_DIR = "logs";
+import { workspaceRuntimeLogsRoot, workspaceRuntimeRunHistoryPath, workspaceRuntimeRunPath, workspaceRuntimeStageContractPath, } from "./workspace-paths.js";
 export function runPath(dirPath) {
-    return join(dirPath, STATE_DIR, RUN_FILE);
+    return workspaceRuntimeRunPath(dirPath);
 }
 export function runHistoryPath(dirPath) {
-    return join(dirPath, STATE_DIR, RUN_HISTORY_FILE);
+    return workspaceRuntimeRunHistoryPath(dirPath);
 }
 export function stageContractPath(dirPath) {
-    return join(dirPath, STATE_DIR, STAGE_CONTRACT_FILE);
+    return workspaceRuntimeStageContractPath(dirPath);
 }
 export function logsDirPath(dirPath) {
-    return join(dirPath, STATE_DIR, LOGS_DIR);
+    return workspaceRuntimeLogsRoot(dirPath);
 }
 export function promptLogPath(dirPath, runId) {
     return join(logsDirPath(dirPath), `${runId}.prompt.txt`);
@@ -25,4 +21,3 @@ export function eventLogPath(dirPath, runId) {
 export function statusLogPath(dirPath, runId) {
     return join(logsDirPath(dirPath), `${runId}.status.log`);
 }
-//# sourceMappingURL=runtime-paths.js.map

package/dist/lib/runtime-prompt.d.ts

@@ -1,3 +1,2 @@
 import { type RuntimeStageInstructions } from "./schema.js";
 export declare function buildStagePrompt(instructions: RuntimeStageInstructions, contractPath: string, statusLines: string[]): string;
-//# sourceMappingURL=runtime-prompt.d.ts.map

package/dist/lib/runtime-prompt.js

@@ -1,11 +1,4 @@
-import { existsSync, readFileSync, } from "node:fs";
-import { join } from "node:path";
-import { SKILLS_DIR } from "./config.js";
 export function buildStagePrompt(instructions, contractPath, statusLines) {
-    const bundledSkillPath = join(SKILLS_DIR, ...instructions.bundled_skill.split("/"), "SKILL.md");
-    const bundledSkillDoc = existsSync(bundledSkillPath)
-        ? readFileSync(bundledSkillPath, "utf8").trim()
-        : null;
     const modeNotes = instructions.effective_mode === "override"
         ? [
             "Local stage instruction docs are authoritative for this run.",
@@ -14,30 +7,31 @@ export function buildStagePrompt(instructions, contractPath, statusLines) {
         ]
         : instructions.effective_mode === "extend"
             ? [
-                "Use the bundled stage instructions as the default workflow for this run.",
-                "Then apply any local stage instruction docs referenced by the contract as stage-specific extensions.",
+                "Use the current workspace workflow docs as the default workflow for this run.",
+                "Then apply any additional local stage instruction docs referenced by the contract as stage-specific extensions.",
             ]
             : [
-                "Use the bundled stage instructions as the default workflow for this run.",
+                "Use the current workspace workflow docs as the default workflow for this run.",
             ];
     return [
-        `Interf built-in stage: ${instructions.bundled_skill}`,
+        `Interf built-in stage id: ${instructions.bundled_skill}`,
         "",
         "This is an automated Interf stage run, not an open-ended chat session.",
         "The user has already invoked this stage through the Interf CLI. Execute it now.",
         "Do not ask what the user wants, offer help, list tools, or wait for another instruction.",
         `Read \`${contractPath}\` first. It is the authoritative contract for this stage.`,
         "If `runtime/paths.json` exists in this shell, read it next. It maps workflow zone ids onto the shell-local `inputs/` and `outputs/` mounts for this stage.",
+        "For file-zone mounts, `runtime/paths.json` also gives the exact file path inside the `inputs/` or `outputs/` mount root.",
         "Honor the contract's counts, artifact paths, and policies instead of inventing another workflow.",
         "Read only the files named by the contract's `artifacts.reads` list plus any paths they explicitly direct you to open.",
         "If the contract lists `instructions.local_docs`, open every one of those files before you write artifacts or declare the stage complete.",
         "If `AGENTS.md` is listed in the contract, use it only for workspace routing that is directly relevant to this stage.",
-        "`.interf/run.json`, `.interf/state.json`, `.interf/health.json`, and `.interf/view-spec.json` are CLI-owned runtime artifacts. You may read them, but do not create, edit, or replace them unless the contract explicitly marks a different proof artifact as stage-owned.",
+        "`.interf/runtime/run.json`, `.interf/runtime/state.json`, `.interf/runtime/health.json`, and `.interf/runtime/view-spec.json` are CLI-owned runtime artifacts. You may read them, but do not create, edit, or replace them unless the contract explicitly marks a different proof artifact as stage-owned.",
         "If a contract-listed output file does not exist yet, create it in one whole-file write. Do not attempt patch-style edits against a missing runtime path.",
         "Stay inside the current workspace. Do not try to open SDK repo docs, SDK source files, or other paths outside the workspace unless the stage contract explicitly requires them.",
         instructions.effective_mode === "override"
-            ? "Do not depend on globally installed slash-command skills for this run. Local stage instruction docs are the primary workflow layer for this run."
-            : "Do not depend on globally installed slash-command skills for this run. Use the bundled stage instructions below as the default behavior.",
+            ? "Do not depend on any repo-root or globally installed skill cache for this run. Local stage instruction docs are the primary workflow layer for this run."
+            : "Do not depend on any repo-root or globally installed skill cache for this run. Use the current workspace workflow docs and the contract as the default behavior.",
         ...modeNotes,
         "Do not narrate intentions, plans, or reasoning to the user.",
         "Only emit user-visible updates that begin with STATUS:, DONE:, BLOCKED:, or ERROR:.",
@@ -47,14 +41,5 @@ export function buildStagePrompt(instructions, contractPath, statusLines) {
         "If you respond conversationally instead of executing the stage, the run will be treated as failed.",
         "As soon as the required proof artifacts are complete, stop. Do not keep browsing or auditing after the contract is satisfied.",
         ...statusLines,
-        ...(bundledSkillDoc && instructions.effective_mode !== "override"
-            ? [
-                "",
-                "Bundled Stage Instructions",
-                "==========================",
-                bundledSkillDoc,
-            ]
-            : []),
     ].join("\n");
 }
-//# sourceMappingURL=runtime-prompt.js.map

package/dist/lib/runtime-reconcile.d.ts

@@ -1,4 +1,3 @@
 export declare function reconcileWorkspaceSummarizeRun(dirPath: string, expectedSummaryTotal: number): boolean;
 export declare function reconcileWorkspaceStructureRun(dirPath: string): boolean;
 export declare function reconcileWorkspaceShapeRun(dirPath: string): boolean;
-//# sourceMappingURL=runtime-reconcile.d.ts.map