@interf/compiler 0.7.3 → 0.9.3

package/{builtin-workflows/interf → builtin-methods/interf-default}/README.md

@@ -1,11 +1,11 @@
-# Interf (Built-in Workflow)
+# Built-in Interf Method
 
-Interf's built-in workflow: summarize source-grounded evidence, structure the cross-file layer, then shape the final portable context around its task focus and checks.
+Built-in file-processing Method: summarize source-grounded evidence, structure cross-file connections, and shape portable context around the saved readiness checks.
 
 ## Purpose
 
-- General portable-context workflow for agent use
-- Compile mixed raw files into evidence-backed summaries, cross-file structure, and a usable entrypoint for agents answering the questions this task depends on.
+- General portable-context Method for agent use
+- Compile mixed raw files into evidence-backed summaries, cross-file structure, and a usable entrypoint for agents running the readiness checks this task depends on.
 
 ## Zones
 
@@ -14,18 +14,18 @@ Interf's built-in workflow: summarize source-grounded evidence, structure the cr
 - `knowledge-entities` — output directory at `knowledge/entities`
 - `knowledge-claims` — output directory at `knowledge/claims`
 - `knowledge-indexes` — output directory at `knowledge/indexes`
-- `home` — output file at `home.md` used as the primary entrypoint for this workflow
+- `home` — output file at `home.md` used as the primary entrypoint for this Method
 - `runtime` — runtime zone at `.interf/runtime`
 
 ## Stages
 
 - `summarize` — Turn source files into per-file summaries. (compiled-file-evidence; reads: raw, runtime; writes: summaries)
 - `structure` — Build the cross-file knowledge structure from the summaries. (compiled-knowledge-structure; reads: summaries, runtime; writes: knowledge-entities, knowledge-claims, knowledge-indexes)
-- `shape` — Shape the final portable context around the saved task focus and checks. (compiled-query-shape; reads: raw, summaries, knowledge-entities, knowledge-claims, knowledge-indexes, runtime; writes: knowledge-indexes, home)
+- `shape` — Shape the final portable context around the saved task focus and readiness checks. (compiled-query-shape; reads: raw, summaries, knowledge-entities, knowledge-claims, knowledge-indexes, runtime; writes: knowledge-indexes, home)
 
 ## Why `home.md` exists here
 
-This built-in workflow creates `home.md` as the main agent entrypoint for the portable context.
-That is behavior of the `interf` workflow, not a compiler-wide rule.
+This built-in Method creates `home.md` as the main agent entrypoint for the portable context.
+That is behavior of the `interf-default` Method, not a compiler-wide rule.
 
-This package is the built-in seed for `interf`.
+This package is the built-in seed for `interf-default`.

package/{builtin-workflows/interf → builtin-methods/interf-default}/compile/stages/shape/SKILL.md

@@ -1,12 +1,12 @@
 # Shape
 
-Shape the final portable context around the saved task focus and checks.
+Shape the final portable context around the saved task focus and readiness checks.
 
 Contract type: `compiled-query-shape`
 
 ## Requirements
 
-- Use the compiled task focus plus saved truth-check question text to shape `home.md` and retrieval routes.
+- Use the compiled task focus plus saved readiness-check text to shape `home.md` and retrieval routes.
 - Rewrite `home.md` into a real entrypoint note. Do not leave the scaffold `Not yet compiled.` placeholder in place.
 - When you add wikilinks, target real compiled notes by exact basename or explicit relative path.
 - If you introduce a new note name in `home.md` or another shaped output, the same stage must also create that note file.
@@ -22,10 +22,10 @@ Contract type: `compiled-query-shape`
 
 ## Notes
 
-- Use the saved task focus and checks to bias the final portable context toward the job it should be especially good at.
+- Use the saved task focus and readiness checks to bias the final portable context toward the job it should be especially good at.
 - Do not copy expected answers into the final portable context just because the checks imply them.
 - Prefer the saved summary evidence and structured notes when they already preserve the bounded chart/table reads plus provenance you need.
 - Reopen `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.
-- If a saved truth check depends on chart-derived or table-derived values, carry the final bounded reads forward into focused notes with provenance instead of repeatedly recomputing them from raw.
+- If a saved readiness check depends on chart-derived or table-derived values, carry the final bounded reads forward into focused notes with provenance instead of repeatedly recomputing them from raw.
 - Prefer better routing, prioritization, and focused navigation over speculative synthesis.
 - Any wikilinks you add to `home.md` or indexes must resolve to real compiled note basenames or explicit relative paths.

package/{builtin-workflows/interf → builtin-methods/interf-default}/compile/stages/structure/SKILL.md

@@ -15,7 +15,7 @@ Contract type: `compiled-knowledge-structure`
 
 - Bias structure toward canonical entities, claims, timelines, and stable indexes.
 - Use taxonomy and ontology only as means to improve retrieval, navigation, and evidence tracking.
-- For small datasets, prefer a minimal stable substrate over exhaustive graph sprawl.
+- For small source folders, prefer a minimal stable substrate over exhaustive graph sprawl.
 - When you add wikilinks, target real compiled notes by exact basename or explicit relative path. Do not invent title-style links unless that exact title is also a declared note label or alias.
 - Do not add wikilinks in structure outputs to files that the shape stage creates later. If a route belongs in `home.md` or a later shaped note, leave plain text now and let the later stage add the link.
 - For summary references, prefer explicit links like `[[summaries/<file-stem>]]` or plain code paths. For knowledge notes, prefer the final filename stem under `knowledge/`.

package/builtin-methods/interf-default/improve/SKILL.md

@@ -0,0 +1,18 @@
+# Method Improvement
+
+Method: interf-default
+
+This file is the editable authoring source for Interf's generated native Method-improver shell.
+The improver edits this local package directly.
+
+Default loop:
+1. Read the loop context first.
+2. Review preserved stage shells, runtime logs, and saved test runs from failed attempts.
+3. Edit only the local Method package for this portable context to create a better Method variation for this task.
+4. Keep `method.json`, `method.schema.json`, and any changed stage docs aligned.
+
+Guardrails:
+- do not edit checks, test specs, or raw source files
+- do not hardcode expected answers into Method docs
+- keep this package standalone; do not rely on runtime inheritance
+- prefer small, defensible Method changes over random churn

package/{builtin-workflows/interf/workflow.json → builtin-methods/interf-default/method.json}

@@ -1,16 +1,16 @@
 {
-  "id": "interf",
+  "id": "interf-default",
   "type": "compiled",
   "compiler_api": {
     "kind": "compiled",
     "version": 1
   },
   "purpose": {
-    "label": "General compiled context workflow for agent use",
-    "task_hint": "Compile mixed raw files into evidence-backed summaries, cross-file structure, and a usable entrypoint for agents answering the questions this task depends on."
+    "label": "Built-in portable-context Method for agent use",
+    "task_hint": "Compile mixed raw files into evidence-backed summaries, cross-file structure, and a usable entrypoint for agents running the readiness checks this task depends on."
   },
-  "label": "Interf (Built-in)",
-  "hint": "Interf's built-in workflow: summarize source-grounded evidence, structure the cross-file layer, then shape the final portable context around its task focus and checks.",
+  "label": "Built-in Interf Method",
+  "hint": "Built-in file-processing Method: summarize source-grounded evidence, structure cross-file connections, and shape portable context around the saved readiness checks.",
   "stages": [
     {
       "id": "summarize",
@@ -82,7 +82,7 @@
     {
       "id": "shape",
       "label": "Shape",
-      "description": "Shape the final portable context around the saved task focus and checks.",
+      "description": "Shape the final portable context around the saved task focus and readiness checks.",
       "contract_type": "compiled-query-shape",
       "skill_dir": "shape",
       "reads": [
@@ -129,15 +129,15 @@
     "structure": [
       "Bias structure toward canonical entities, claims, timelines, and stable indexes.",
       "Use taxonomy and ontology only as means to improve retrieval, navigation, and evidence tracking.",
-      "For small datasets, prefer a minimal stable substrate over exhaustive graph sprawl.",
+      "For small Source Folders, prefer a minimal stable substrate over exhaustive graph sprawl.",
       "When you add wikilinks, target real compiled notes by exact basename or explicit relative path. Do not invent title-style links unless that exact title is also a declared note label or alias.",
       "Do not add wikilinks in structure outputs to files that the shape stage creates later. If a route belongs in `home.md` or a later shaped note, leave plain text now and let the later stage add the link.",
       "For summary references, prefer explicit links like `[[summaries/<file-stem>]]` or plain code paths. For knowledge notes, prefer the final filename stem under `knowledge/`."
     ],
     "shape": [
-      "Use the saved task focus and checks to bias the final portable context toward the job it should be especially good at.",
+      "Use the saved task focus and readiness checks to bias the final portable context toward the job it should be especially good at.",
       "Do not copy expected answers into the final portable context just because the checks imply them.",
-      "If a saved truth check depends on chart-derived or table-derived values, verify the needed evidence in `raw/` while shaping and write focused notes that preserve bounded values plus provenance.",
+      "If a saved readiness check depends on chart-derived or table-derived values, verify the needed evidence in `raw/` while shaping and write focused notes that preserve bounded values plus provenance.",
       "Prefer better routing, prioritization, and focused navigation over speculative synthesis.",
       "Any wikilinks you add to `home.md` or indexes must resolve to real compiled note basenames or explicit relative paths."
     ]

package/{builtin-workflows/interf/workflow.schema.json → builtin-methods/interf-default/method.schema.json}

@@ -1,8 +1,8 @@
 {
-  "kind": "workflow-schema",
+  "kind": "method-schema",
   "version": 1,
   "target_type": "compiled",
-  "label": "Interf built-in workflow schema",
+  "label": "Interf built-in Method schema",
   "zones": [
     {
       "id": "raw",
@@ -11,7 +11,7 @@
       "kind": "directory",
       "required": true,
       "owned_by": [],
-      "description": "Dataset-local raw snapshot copied from the dataset for direct evidence and verification."
+      "description": "Preparation-local raw snapshot copied from the source folder for direct evidence and verification."
     },
     {
       "id": "summaries",

package/{builtin-workflows/interf → builtin-methods/interf-default}/use/query/SKILL.md

@@ -12,7 +12,7 @@ Answering rule:
 - do not modify files under `raw/`
 - when a number is chart-derived, say that explicitly
 - if the compiled layer already contains a bounded chart-derived read for the exact metric and year the user asked about, answer from that compiled read first
-- use `raw/` to confirm the source page, metric family, or provenance, not to replace a good compiled bounded read with a second incompatible range
+- use `raw/` to confirm the source page, metric family, or provenance, not to replace a good compiled bounded read with a mismatched range
 - when the compiled layer preserves a bounded chart-derived range, keep that bounded range in the answer instead of collapsing it to a midpoint or pseudo-exact single value
 - match the granularity of the visible axis labels or bands and do not invent finer precision than the chart supports
 - when reading charts, verify you are on the correct metric family and year before answering

package/dist/cli/commands/check-draft.d.ts

@@ -1,19 +1,20 @@
-import type { WorkflowExecutor } from "../../packages/agents/lib/executors.js";
-import type { SourceTruthCheck } from "../../packages/project-model/lib/schema.js";
-export declare function buildTruthCheckDraftPrompt(options: {
-    datasetName: string;
-    datasetPath: string;
+import type { MethodExecutor } from "../../packages/agents/lib/executors.js";
+import type { SourceReadinessCheck } from "../../packages/project-model/lib/schema.js";
+export declare function buildReadinessCheckDraftPrompt(options: {
+    preparationName: string;
+    sourceFolderPath: string;
     about?: string;
     outputPath: string;
     targetCount: number;
 }): string;
-export declare function draftTruthChecks(options: {
-    datasetName: string;
-    datasetPath: string;
+export declare function draftReadinessChecks(options: {
+    preparationName: string;
+    sourceFolderPath: string;
     about?: string;
-    executor: WorkflowExecutor;
+    executor: MethodExecutor;
     targetCount?: number;
+    onStatus?: (line: string) => void;
 }): Promise<{
-    checks: SourceTruthCheck[] | null;
+    checks: SourceReadinessCheck[] | null;
     error?: string;
 }>;

package/dist/cli/commands/check-draft.js

@@ -2,37 +2,37 @@ import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "no
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { z } from "zod";
-const DraftTruthCheckSchema = z.object({
+const DraftReadinessCheckSchema = z.object({
     question: z.string().min(1),
     answer: z.string().min(1),
 }).strict();
-const DraftTruthChecksSchema = z.array(DraftTruthCheckSchema).min(1).max(8);
-export function buildTruthCheckDraftPrompt(options) {
+const DraftReadinessChecksSchema = z.array(DraftReadinessCheckSchema).min(1).max(8);
+export function buildReadinessCheckDraftPrompt(options) {
     const normalizedAbout = options.about?.trim();
     const taskLines = normalizedAbout
         ? [
-            `Primary work: ${normalizedAbout}`,
-            "Draft checks that directly measure whether a local agent can answer the key questions from the data behind that work.",
-            "Prefer checks that would make a human confident the dataset is useful for that exact job.",
+            `Primary agent work: ${normalizedAbout}`,
+            "Draft readiness checks that directly measure whether a local agent can recover the agent-work-critical facts from the source files.",
+            "Prefer checks that would make a human confident the Preparation is useful for that exact job.",
         ]
         : [
-            "No primary work was provided.",
-            "Prefer broad, representative checks that reflect the most useful questions a human would verify from this source folder.",
+            "No primary agent work was provided.",
+            "Prefer broad, representative readiness checks that reflect the facts a human would verify from this Source Folder.",
         ];
     return [
-        "You are drafting Interf checks for a local source folder.",
+        "You are drafting Interf readiness checks for a local Source Folder.",
         "Read the files in this folder and draft a small set of checks that a human can verify from the source material.",
         "Do not ask follow-up questions.",
-        "Keep the checks concrete, explicit, and useful for measuring whether an agent can reason correctly over the files in this source folder.",
+        "Keep the checks concrete, explicit, and useful for measuring whether an agent can reason correctly over the files in this Source Folder.",
         "",
-        `Setup id: ${options.datasetName}`,
-        `Source folder: ${options.datasetPath}`,
+        `Preparation id: ${options.preparationName}`,
+        `Source Folder: ${options.sourceFolderPath}`,
         ...taskLines,
         "",
         `Write exactly one JSON array to ${JSON.stringify(options.outputPath)}.`,
-        `Draft ${options.targetCount} checks unless the source folder is too small; in that case write fewer.`,
+        `Draft ${options.targetCount} checks unless the Source Folder is too small; in that case write fewer.`,
         "Each array item must be an object with exactly these keys:",
-        '- "question": a plain-English question answerable from this source folder',
+        '- "question": a plain-English question answerable from this Source Folder',
         '- "answer": the expected correct answer in plain English',
         "",
         "Quality bar:",
@@ -52,21 +52,22 @@ export function buildTruthCheckDraftPrompt(options) {
         "- Stop after writing the file.",
     ].join("\n");
 }
-export async function draftTruthChecks(options) {
+export async function draftReadinessChecks(options) {
     const tempDir = mkdtempSync(join(tmpdir(), "interf-draft-checks-"));
     const outputPath = join(tempDir, "checks.json");
     const promptPath = join(tempDir, "prompt.txt");
-    const prompt = buildTruthCheckDraftPrompt({
-        datasetName: options.datasetName,
-        datasetPath: options.datasetPath,
+    const prompt = buildReadinessCheckDraftPrompt({
+        preparationName: options.preparationName,
+        sourceFolderPath: options.sourceFolderPath,
         about: options.about,
         outputPath,
         targetCount: options.targetCount ?? 4,
     });
     writeFileSync(promptPath, `${prompt}\n`);
     try {
-        const code = await options.executor.execute(options.datasetPath, prompt, {
+        const code = await options.executor.execute(options.sourceFolderPath, prompt, {
             completionCheck: () => existsSync(outputPath),
+            onStatus: options.onStatus,
         });
         if (!existsSync(outputPath)) {
             return {
@@ -86,7 +87,7 @@ export async function draftTruthChecks(options) {
                 error: `Draft checks were not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
             };
         }
-        const validated = DraftTruthChecksSchema.safeParse(parsed);
+        const validated = DraftReadinessChecksSchema.safeParse(parsed);
         if (!validated.success) {
             const detail = validated.error.issues[0]?.message ?? "invalid draft checks";
             return {

package/dist/cli/commands/compile-controller.d.ts

@@ -1,14 +1,17 @@
-import type { WorkflowExecutionProfile, WorkflowExecutor } from "../../packages/agents/lib/executors.js";
-import type { SourceDatasetConfig } from "../../packages/project-model/lib/schema.js";
-import type { StageShellRetentionMode } from "../../packages/compiler/workflows.js";
+import type { MethodExecutionProfile, MethodExecutor } from "../../packages/agents/lib/executors.js";
+import type { SourcePreparationConfig } from "../../packages/project-model/lib/schema.js";
+import type { StageShellRetentionMode } from "../../packages/compiler/method-runs.js";
+import type { RunEventSink } from "../../packages/execution/events.js";
 export declare function runConfiguredCompiledCompile(options: {
-    executor: WorkflowExecutor;
-    testExecutor?: WorkflowExecutor | null;
+    executor: MethodExecutor;
+    testExecutor?: MethodExecutor | null;
     compiledPath: string;
     sourcePath: string;
-    compiledConfig: SourceDatasetConfig | null;
-    executionProfile?: WorkflowExecutionProfile;
+    compiledConfig: SourcePreparationConfig | null;
+    executionProfile?: MethodExecutionProfile;
     maxAttemptsOverride: number | null;
     maxLoopsOverride: number | null;
     preserveStageShells?: StageShellRetentionMode;
+    runId?: string;
+    events?: RunEventSink;
 }): Promise<boolean>;