@interf/compiler 0.1.12 → 0.2.0

package/dist/lib/workflows-interface.js

@@ -1,15 +1,15 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { countFilesRecursive } from "./filesystem.js";
-import { readInterfConfig, refreshWorkspaceBootstrapGuidance, resolveInterfaceKnowledgeBasePath, resolveKnowledgeBaseSourcePath, syncClaudeBootstrap, } from "./interf.js";
+import { readInterfConfig, refreshWorkspaceBootstrapGuidance, resolveInterfaceKnowledgeBasePath, resolveKnowledgeBaseSourcePath, syncClaudeBootstrap, writeInterfaceCompilePlanTemplate, } from "./interf.js";
 import { loadState, computeInterfaceHealth, refreshInterfaceArtifacts, } from "./state.js";
-import { buildStagePrompt, markRuntimeRunFailedAfterValidation, markRuntimeRunSucceededAfterValidation, runtimeRunStdoutContains, runExecutorStage, validateStageContractAcceptance, } from "./runtime.js";
-import { formatInterfaceWorkflowStageStep, getInterfaceWorkflow, getWorkflowStagePolicyNotes, resolveInterfaceWorkflowFromConfig, } from "./workflow-definitions.js";
-import { validateInterfaceRetrieve, validateInterfacePlan, } from "./validate.js";
-import { reportLine, reportBlankLine, reportValidationFailure, buildLocalSkillContractExtension, buildLocalSkillContractExtensionRelativeTo, mergeLocalSkillContractExtensions, emptyLocalSkillContractExtension, buildStageInstructions, bundledSkillForContractType, resolveStageAcceptance, validateStageOutcome, workflowCreateDirectory, workflowQueryDirectory, workflowCompileStageDirectory, } from "./workflow-helpers.js";
-// ---------------------------------------------------------------------------
-// Interface-specific helpers
-// ---------------------------------------------------------------------------
+import { buildStagePrompt, markRuntimeRunFailedAfterValidation, markRuntimeRunSucceededAfterValidation, runExecutorStage, validateStageContractAcceptance, } from "./runtime.js";
+import { reconcileInterfaceAnalyzeRun, reconcileInterfaceCompileRun, reconcileInterfaceRetrieveRun, } from "./runtime-reconcile.js";
+import { formatInterfaceWorkflowStageStep, getInterfaceWorkflow, resolveInterfaceWorkflowFromConfig, } from "./workflow-definitions.js";
+import { validateInterfaceRetrieve, } from "./validate.js";
+import { reportLine, reportBlankLine, buildLocalSkillContractExtension, buildLocalSkillContractExtensionRelativeTo, emptyLocalSkillContractExtension, mergeLocalSkillContractExtensions, buildStageInstructions, bundledSkillForContractType, workflowCreateDirectory, workflowCompileStageDirectory, } from "./workflow-helpers.js";
+import { buildInterfaceAnalyzeContract, buildInterfaceCompileContract, buildInterfaceCreateContract, buildInterfaceRetrieveContract, isRetrieveStageComplete, validateInterfacePlanForUseCase, } from "./workflows-interface-contracts.js";
+import { executeValidatedStage, findStageByContractType, } from "./workflow-stage-runner.js";
 export function resolveInterfaceContext(knowledgeBasePath) {
     const config = readInterfConfig(knowledgeBasePath);
     const workflowId = resolveInterfaceWorkflowFromConfig(config);
@@ -24,284 +24,36 @@ export function resolveInterfaceContext(knowledgeBasePath) {
 export function interfaceExecutionStages(workflowId, interfacePath) {
     return getInterfaceWorkflow(workflowId, { workspacePath: interfacePath }).stages;
 }
-export function isRetrieveStageComplete(dirPath) {
-    const validation = validateInterfaceRetrieve(dirPath);
-    return validation.required && validation.ok;
-}
-// ---------------------------------------------------------------------------
-// Interface contract builders
-// ---------------------------------------------------------------------------
-function buildInterfaceCreateContract(options) {
-    const connectedKnowledgeBasePath = resolveInterfaceKnowledgeBasePath(options.knowledgeBasePath);
-    const workflowSourcePath = connectedKnowledgeBasePath
-        ? resolveKnowledgeBaseSourcePath(connectedKnowledgeBasePath)
-        : undefined;
-    const workflow = getInterfaceWorkflow(options.workflow, {
-        sourcePath: workflowSourcePath,
-        workspacePath: options.knowledgeBasePath,
-    });
-    const localSkills = mergeLocalSkillContractExtensions([
+function buildInterfaceCreateInstructions(interfacePath, connectedKnowledgeBasePath) {
+    return buildStageInstructions("interface/create", mergeLocalSkillContractExtensions([
         connectedKnowledgeBasePath
-            ? buildLocalSkillContractExtensionRelativeTo(connectedKnowledgeBasePath, options.knowledgeBasePath, [workflowQueryDirectory()], "Use the connected knowledge-base workflow docs as higher-level knowledge-base guidance only if they materially improve the interface scaffold.")
+            ? buildLocalSkillContractExtensionRelativeTo(connectedKnowledgeBasePath, interfacePath, [], "Use the connected knowledge-base workflow README as high-level guidance only if it materially improves the interface scaffold.")
             : emptyLocalSkillContractExtension(),
-        buildLocalSkillContractExtension(options.knowledgeBasePath, [workflowCreateDirectory()], "Use the interface workflow's local create docs as scaffolding heuristics only if they materially improve the interface setup."),
-    ]);
-    return {
-        instructions: options.instructions,
-        counts: {
-            workflow_selected: 1,
-            local_skill_docs: localSkills.count,
-        },
-        artifacts: {
-            reads: [
-                "AGENTS.md",
-                "home.md",
-                "../../AGENTS.md",
-                "../../interf.json",
-                "../../home.md",
-                "../../knowledge/",
-                "../../summaries/",
-                ...localSkills.reads,
-            ],
-            writes: [
-                "interf.json",
-                "compile-plan.md",
-                "AGENTS.md",
-                "CLAUDE.md",
-            ],
-            verifies: [
-                "interf verify interface-plan --json",
-            ],
-        },
-        policies: {
-            execution_mode: "deterministic",
-            status_prefixes: ["STATUS:", "DONE:", "BLOCKED:", "ERROR:"],
-            notes: [
-                `Interface name: ${options.name}.`,
-                `Selected workflow: ${workflow.id} (${workflow.label}).`,
-                `Workflow stages: ${workflow.stages.map((stage) => `${stage.label} [${stage.id}]`).join(" -> ")}.`,
-                `Use case: ${options.useCase}.`,
-                `Connected knowledge-base: ${options.knowledgeBaseName} at ${connectedKnowledgeBasePath ?? "unknown"}.`,
-                "The scaffold already exists with home.md, AGENTS.md, CLAUDE.md, interf.json, and the .interf runtime artifacts.",
-                "Read the current local AGENTS.md and home.md first. They are the interface workspace bootstrap you are updating.",
-                "Then consult ../../AGENTS.md and ../../home.md for parent knowledge-base navigation and evidence structure.",
-                "This interface lives inside the parent knowledgeBase. Do not assume it will be opened as a standalone Obsidian vault.",
-                "Do not recreate the vault or ask follow-up questions.",
-                "Use the selected workflow as the starting point, then adapt it to the knowledge-base data and the use case.",
-                "Edit the existing compile-plan.md scaffold in place. Preserve the stage headings and required subsection labels from the starter plan; refine the bullets and narrative instead of replacing the structure.",
-                "Preserve the existing AGENTS.md scaffold sections, especially the manual access checklist, raw-source gate, and navigation/router guidance. Update only the interface-specific description and lines that must reflect the use case.",
-                "Do not replace AGENTS.md with a shorter template.",
-                "Analyze the knowledge-base and update only the interface definition files in this vault: interf.json, compile-plan.md, and AGENTS.md. CLAUDE.md is a generated mirror of AGENTS.md and will be rewritten by the harness.",
-                ...localSkills.notes,
-            ],
-        },
-    };
-}
-export function buildInterfaceRetrieveContract(interfacePath, workflowId, summaryCount, instructions, stageId = "retrieve", stageSkillDir = "retrieve") {
-    const connectedKnowledgeBasePath = resolveInterfaceKnowledgeBasePath(interfacePath);
-    const sourcePath = connectedKnowledgeBasePath ? resolveKnowledgeBaseSourcePath(connectedKnowledgeBasePath) : undefined;
-    const acceptance = resolveStageAcceptance("interface", workflowId, stageId, sourcePath, interfacePath);
-    const localSkills = mergeLocalSkillContractExtensions([
-        connectedKnowledgeBasePath
-            ? buildLocalSkillContractExtensionRelativeTo(connectedKnowledgeBasePath, interfacePath, [workflowQueryDirectory()], "Use the connected knowledge-base workflow docs as higher-level knowledge-base guidance before applying interface-local retrieve rules.")
-            : emptyLocalSkillContractExtension(),
-        buildLocalSkillContractExtension(interfacePath, [workflowCompileStageDirectory(stageSkillDir)], "Use interface-local docs to refine filters, expansion heuristics, ranking, and ontology hints."),
-    ]);
-    return {
-        instructions,
-        counts: {
-            knowledge_base_summary_total: summaryCount,
-            local_skill_docs: localSkills.count,
-        },
-        ...(acceptance ? { acceptance } : {}),
-        artifacts: {
-            reads: [
-                "AGENTS.md",
-                "home.md",
-                "../../AGENTS.md",
-                "../../home.md",
-                "interf.json",
-                "compile-plan.md",
-                "../../.interf/source-access.json",
-                "../../summaries/",
-                ".interf/state.json",
-                ...localSkills.reads,
-            ],
-            writes: [
-                ".interf/relevant.json",
-                ".interf/coverage.json",
-                ".interf/state.json",
-                ".interf/health.json",
-            ],
-            verifies: [
-                "interf verify retrieve --json",
-            ],
-        },
-        policies: {
-            execution_mode: "deterministic",
-            status_prefixes: ["STATUS:", "DONE:", "BLOCKED:", "ERROR:"],
-            notes: [
-                "Read local `AGENTS.md` first, then consult parent knowledge-base `../../AGENTS.md` and `../../home.md` before considering raw-source fallback.",
-                "Access hierarchy for this stage is: local interface artifacts -> parent knowledge-base artifacts -> raw source files only when needed.",
-                "Treat the interface runtime in compile-plan.md as an initial hypothesis, not a final truth.",
-                "Scan ALL knowledge-base summaries frontmatter before making any selection.",
-                "Review abstracts for the candidate set, expand through linked summaries when needed, and stop only when the retrieved set is coverage-complete for this interface.",
-                "Selection quality is judged by the proof of reviewed, retrieved, and excluded files, not by superficial brevity.",
-                "If you need raw-file fallback, inspect `../../.interf/source-access.json` first and verify one suggested path is readable. These are canonical absolute source-file paths shared by the parent knowledge base. If they are not reachable, continue from knowledge-base summaries and report that raw fallback was unavailable.",
-                ...getWorkflowStagePolicyNotes("interface", workflowId, stageId, sourcePath, interfacePath),
-                ...localSkills.notes,
-            ],
-            evidence_weighting: {
-                required_fields: ["source_kind", "evidence_tier", "truth_mode", "state"],
-                preserve_tiers: true,
-            },
-            working_set: {
-                target_context_fraction: 0.15,
-                strategy: "Frontmatter scan first, then abstract review, then linked expansion only where coverage proof requires it.",
-            },
-        },
-    };
-}
-export function buildInterfaceAnalyzeContract(interfacePath, workflowId, analyzeCount, instructions, stageId = "analyze", stageSkillDir = "analyze") {
-    const connectedKnowledgeBasePath = resolveInterfaceKnowledgeBasePath(interfacePath);
-    const sourcePath = connectedKnowledgeBasePath ? resolveKnowledgeBaseSourcePath(connectedKnowledgeBasePath) : undefined;
-    const acceptance = resolveStageAcceptance("interface", workflowId, stageId, sourcePath, interfacePath);
-    const localSkills = mergeLocalSkillContractExtensions([
-        connectedKnowledgeBasePath
-            ? buildLocalSkillContractExtensionRelativeTo(connectedKnowledgeBasePath, interfacePath, [workflowQueryDirectory()], "Use the connected knowledge-base workflow docs as higher-level knowledge-base guidance before applying interface-local analyze rules.")
-            : emptyLocalSkillContractExtension(),
-        buildLocalSkillContractExtension(interfacePath, [workflowCompileStageDirectory(stageSkillDir)], "Use interface-local docs to refine the interface ontology, extraction schema, and evidence grouping."),
-    ]);
-    return {
-        instructions,
-        counts: {
-            relevant_total: analyzeCount,
-            local_skill_docs: localSkills.count,
-        },
-        ...(acceptance ? { acceptance } : {}),
-        artifacts: {
-            reads: [
-                "AGENTS.md",
-                "home.md",
-                "../../AGENTS.md",
-                "../../home.md",
-                "interf.json",
-                "compile-plan.md",
-                ".interf/relevant.json",
-                "../../.interf/source-access.json",
-                "../../summaries/",
-                ".interf/state.json",
-                ...localSkills.reads,
-            ],
-            writes: [
-                ".interf/analysis.json",
-                ".interf/state.json",
-                ".interf/health.json",
-            ],
-            verifies: [],
-        },
-        policies: {
-            execution_mode: "deterministic",
-            status_prefixes: ["STATUS:", "DONE:", "BLOCKED:", "ERROR:"],
-            notes: [
-                "Read local `AGENTS.md` first, then consult parent knowledge-base `../../AGENTS.md` and `../../home.md` before considering raw-source fallback.",
-                "Access hierarchy for this stage is: local interface artifacts -> parent knowledge-base artifacts -> raw source files only when needed.",
-                "This is the deep extraction pass over the relevant set selected by retrieve.",
-                "Refine the interface runtime from evidence when the knowledge base clearly demands it.",
-                "Keep extraction local to the interface ontology and output goals.",
-                "If you need raw-file fallback, inspect `../../.interf/source-access.json` first and verify one suggested path is readable. These are canonical absolute source-file paths shared by the parent knowledge base. If they are not reachable, continue from knowledge-base summaries and report that raw fallback was unavailable.",
-                ...getWorkflowStagePolicyNotes("interface", workflowId, stageId, sourcePath, interfacePath),
-                ...localSkills.notes,
-            ],
-            evidence_weighting: {
-                required_fields: ["source_kind", "evidence_tier", "truth_mode", "state"],
-                preserve_tiers: true,
-            },
-            working_set: {
-                target_context_fraction: 0.3,
-                strategy: "Batch relevant summaries into bounded sets, derive local entities/claims, then merge before writing analysis artifacts.",
-            },
-        },
-    };
+        buildLocalSkillContractExtension(interfacePath, [workflowCreateDirectory()], "Use the interface workflow's local create docs as scaffolding heuristics only if they materially improve the interface setup."),
+    ]));
 }
-export function buildInterfaceCompileContract(interfacePath, workflowId, relevantCount, instructions, stageId = "compile", stageSkillDir = "compile") {
-    const connectedKnowledgeBasePath = resolveInterfaceKnowledgeBasePath(interfacePath);
-    const sourcePath = connectedKnowledgeBasePath ? resolveKnowledgeBaseSourcePath(connectedKnowledgeBasePath) : undefined;
-    const acceptance = resolveStageAcceptance("interface", workflowId, stageId, sourcePath, interfacePath);
-    const localSkills = mergeLocalSkillContractExtensions([
+function buildInterfaceStageInstructions(contractType, interfacePath, connectedKnowledgeBasePath, stageSkillDir, parentPurpose, localPurpose) {
+    return buildStageInstructions(bundledSkillForContractType(contractType), mergeLocalSkillContractExtensions([
         connectedKnowledgeBasePath
-            ? buildLocalSkillContractExtensionRelativeTo(connectedKnowledgeBasePath, interfacePath, [workflowQueryDirectory()], "Use the connected knowledge-base workflow docs as higher-level knowledge-base guidance before applying interface-local compile rules.")
+            ? buildLocalSkillContractExtensionRelativeTo(connectedKnowledgeBasePath, interfacePath, [], parentPurpose)
             : emptyLocalSkillContractExtension(),
-        buildLocalSkillContractExtension(interfacePath, [workflowCompileStageDirectory(stageSkillDir)], "Use interface-local docs to refine the output inventory, navigation, canvases, and final interface shape."),
-    ]);
-    return {
-        instructions,
-        counts: {
-            relevant_total: relevantCount,
-            local_skill_docs: localSkills.count,
-        },
-        ...(acceptance ? { acceptance } : {}),
-        artifacts: {
-            reads: [
-                "AGENTS.md",
-                "home.md",
-                "../../AGENTS.md",
-                "../../home.md",
-                "interf.json",
-                "compile-plan.md",
-                ".interf/analysis.json",
-                ".interf/relevant.json",
-                "../../.interf/source-access.json",
-                "../../summaries/",
-                ...localSkills.reads,
-            ],
-            writes: [
-                "knowledge/",
-                "briefs/",
-                "summaries/",
-                "home.md",
-                ".interf/state.json",
-                ".interf/health.json",
-            ],
-            verifies: [],
-        },
-        policies: {
-            execution_mode: "deterministic",
-            status_prefixes: ["STATUS:", "DONE:", "BLOCKED:", "ERROR:"],
-            notes: [
-                "Read local `AGENTS.md` first, then consult parent knowledge-base `../../AGENTS.md` and `../../home.md` before considering raw-source fallback.",
-                "Access hierarchy for this stage is: local interface artifacts -> parent knowledge-base artifacts -> raw source files only when needed.",
-                "The interface is a local context shell for agents. Build it so an agent can navigate AGENTS.md -> home.md -> local knowledge/briefs/summaries -> knowledge-base summaries -> raw only when needed.",
-                "When local outputs cite knowledge-base evidence, point to the parent knowledge-base summary path `../../summaries/...`, not the interface-local `summaries/` folder.",
-                "Prefer durable local notes and indexes over monolithic summaries.",
-                "Delete stale analysis handoff artifacts once durable outputs and state have been written.",
-                "If you need raw-file fallback, inspect `../../.interf/source-access.json` first and verify one suggested path is readable. These are canonical absolute source-file paths shared by the parent knowledge base. If they are not reachable, continue from knowledge-base summaries and report that raw fallback was unavailable.",
-                ...getWorkflowStagePolicyNotes("interface", workflowId, stageId, sourcePath, interfacePath),
-                ...localSkills.notes,
-            ],
-            evidence_weighting: {
-                required_fields: ["source_kind", "evidence_tier", "truth_mode", "state"],
-                preserve_tiers: true,
-            },
-            working_set: {
-                target_context_fraction: 0.25,
-                strategy: "Use analysis artifacts as the compile ledger, then write entities, claims, briefs, and navigation in separate local passes.",
-            },
-        },
-    };
+        buildLocalSkillContractExtension(interfacePath, [workflowCompileStageDirectory(stageSkillDir)], localPurpose),
+    ]));
 }
 // ---------------------------------------------------------------------------
 // Interface orchestration functions
 // ---------------------------------------------------------------------------
 export async function planInterface(options) {
     const connectedKnowledgeBasePath = resolveInterfaceKnowledgeBasePath(options.knowledgeBasePath);
+    writeInterfaceCompilePlanTemplate(options.knowledgeBasePath, {
+        workflowId: options.workflow,
+        sourcePath: connectedKnowledgeBasePath ? resolveKnowledgeBaseSourcePath(connectedKnowledgeBasePath) : undefined,
+        interfaceName: options.name,
+        useCase: options.useCase.trim(),
+        targetQuestions: options.targetQuestions,
+    });
     const interfaceWorkflow = resolveInterfaceWorkflowFromConfig(readInterfConfig(options.knowledgeBasePath));
-    const instructions = buildStageInstructions("interface/create", mergeLocalSkillContractExtensions([
-        connectedKnowledgeBasePath
-            ? buildLocalSkillContractExtensionRelativeTo(connectedKnowledgeBasePath, options.knowledgeBasePath, [workflowQueryDirectory()], "Use the connected knowledge-base workflow docs as higher-level guidance only if they materially improve the interface scaffold.")
-            : emptyLocalSkillContractExtension(),
-        buildLocalSkillContractExtension(options.knowledgeBasePath, [workflowCreateDirectory()], "Use the interface workflow's local create docs as scaffolding heuristics only if they materially improve the interface setup."),
-    ]));
+    const instructions = buildInterfaceCreateInstructions(options.knowledgeBasePath, connectedKnowledgeBasePath);
     const code = await runExecutorStage({
         executor: options.executor,
         knowledgeBasePath: options.knowledgeBasePath,
@@ -319,19 +71,22 @@ export async function planInterface(options) {
             useCase: options.useCase,
             knowledgeBaseName: options.knowledgeBaseName,
             knowledgeBasePath: options.knowledgeBasePath,
+            targetQuestions: options.targetQuestions,
             instructions,
         }),
         buildPrompt: (contractPath) => buildStagePrompt(instructions, contractPath, [
-            "Emit exactly one startup line: STATUS: loaded interface creation contract.",
-            "Emit STATUS: analyzed knowledge-base when the scaffold inputs and knowledge-base evidence have been reviewed.",
-            "Emit STATUS: wrote compile plan after interf.json and compile-plan.md are updated and AGENTS.md still preserves the scaffold router/checklist.",
-            "Emit DONE: interface create complete when the scaffold is ready for `interf compile`.",
+            "Emit exactly one startup line, verbatim and on its own line: STATUS: loaded interface creation contract.",
+            "After the scaffold inputs and knowledge-base evidence have been reviewed, emit this canonical line verbatim and on its own line: STATUS: analyzed knowledge-base.",
+            "Do not inspect raw source files or run chart extraction in this stage. Encode future raw/chart work in compile-plan.md instead.",
+            "After compile-plan.md is updated and the scaffold still validates, emit this canonical line verbatim and on its own line: STATUS: wrote compile plan. interf.json and AGENTS.md may remain unchanged when the scaffold is already correct.",
+            "When the scaffold is ready for `interf compile`, stop. You may emit `DONE: interface create complete.` as a final progress line, but the CLI validates completion from the scaffold files instead of trusting that line.",
+            "You may emit additional STATUS lines, but the three canonical STATUS lines above are mandatory and must not be paraphrased.",
         ]),
+        completionCheck: () => validateInterfacePlanForUseCase(options.knowledgeBasePath, options.useCase).ok,
     });
     syncClaudeBootstrap(options.knowledgeBasePath);
-    const validation = validateInterfacePlan(options.knowledgeBasePath);
-    const emittedDone = runtimeRunStdoutContains(options.knowledgeBasePath, "DONE: interface create complete");
-    if (validation.ok && (code === 0 || emittedDone)) {
+    const validation = validateInterfacePlanForUseCase(options.knowledgeBasePath, options.useCase);
+    if (validation.ok) {
         if (code !== 0) {
             markRuntimeRunSucceededAfterValidation(options.knowledgeBasePath, "create-interface completed successfully.");
         }
@@ -355,63 +110,56 @@ export async function runInterfaceRetrieve(options) {
     const sourcePath = options.sourcePath ?? context.sourcePath ?? resolveKnowledgeBaseSourcePath(resolveInterfaceKnowledgeBasePath(options.knowledgeBasePath) ?? options.knowledgeBasePath);
     const workflowId = context.workflowId;
     const connectedKnowledgeBasePath = context.connectedKnowledgeBasePath;
-    const stageDefinition = options.stageDefinition ?? interfaceExecutionStages(workflowId, options.knowledgeBasePath).find((stage) => stage.contractType === "interface-retrieval");
+    const stageDefinition = options.stageDefinition ?? findStageByContractType(interfaceExecutionStages(workflowId, options.knowledgeBasePath), "interface-retrieval");
     const stageStatusLabel = stageDefinition.label.toLowerCase();
     const knowledgeBaseSummaryTotal = connectedKnowledgeBasePath ? countFilesRecursive(join(connectedKnowledgeBasePath, "summaries")) : 0;
     if (options.reportStep !== false) {
         reportLine(options.reporter, formatInterfaceWorkflowStageStep(workflowId, stageDefinition.id, { sourcePath }));
     }
-    const instructions = buildStageInstructions(bundledSkillForContractType(stageDefinition.contractType), mergeLocalSkillContractExtensions([
-        connectedKnowledgeBasePath
-            ? buildLocalSkillContractExtensionRelativeTo(connectedKnowledgeBasePath, options.knowledgeBasePath, [workflowQueryDirectory()], "Use the connected knowledge-base workflow docs as higher-level knowledge-base guidance before applying interface-local retrieve rules.")
-            : emptyLocalSkillContractExtension(),
-        buildLocalSkillContractExtension(options.knowledgeBasePath, [workflowCompileStageDirectory(stageDefinition.skillDir)], "Use interface-local docs to refine filters, expansion heuristics, ranking, and ontology hints."),
-    ]));
-    const code = await runExecutorStage({
+    const instructions = buildInterfaceStageInstructions(stageDefinition.contractType, options.knowledgeBasePath, connectedKnowledgeBasePath, stageDefinition.skillDir, "Use the connected knowledge-base workflow README as high-level knowledge-base context before applying interface-local retrieve rules.", "Use interface-local docs to refine filters, expansion heuristics, ranking, and ontology hints.");
+    const stageResult = await executeValidatedStage({
         executor: options.executor,
-        knowledgeBasePath: options.knowledgeBasePath,
+        workspacePath: options.knowledgeBasePath,
         targetType: "interface",
-        knowledgeBaseName: context.knowledgeBaseName,
+        targetName: context.knowledgeBaseName,
         workflow: workflowId,
         workflowSourcePath: sourcePath,
-        stage: stageDefinition.id,
-        stageLabel: stageDefinition.label,
-        contractType: stageDefinition.contractType,
+        stageDefinition,
+        instructions,
         summary: `Preparing ${stageDefinition.label.toLowerCase()} across ${knowledgeBaseSummaryTotal} knowledge-base summaries.`,
         contract: buildInterfaceRetrieveContract(options.knowledgeBasePath, workflowId, knowledgeBaseSummaryTotal, instructions, stageDefinition.id, stageDefinition.skillDir),
-        buildPrompt: (contractPath) => buildStagePrompt(instructions, contractPath, [
+        statusLines: [
             `Emit exactly one startup line: STATUS: loaded ${stageStatusLabel} plan ${knowledgeBaseSummaryTotal} summary files.`,
             `Emit STATUS: scanned X/${knowledgeBaseSummaryTotal} after each scan batch or every 250 files, whichever comes first.`,
             "Emit STATUS: reviewed A abstracts, P expansion passes after the candidate-review phase is complete.",
             "Emit STATUS: selected R relevant, J rejected, D delta after filters are applied and the retrieved set is finalized.",
-            `Emit DONE: ${stageStatusLabel} complete when \`.interf/relevant.json\`, \`.interf/coverage.json\`, and \`.interf/state.json\` are updated.`,
-        ]),
+            "If the retrieved set is final, write `.interf/relevant.json` and `.interf/coverage.json` immediately, then emit the DONE line and stop.",
+            `Emit DONE: ${stageStatusLabel} complete when \`.interf/relevant.json\` and \`.interf/coverage.json\` are updated.`,
+        ],
+        reporter: options.reporter,
         completionCheck: () => isRetrieveStageComplete(options.knowledgeBasePath) &&
             validateStageContractAcceptance(options.knowledgeBasePath).ok,
+        reconcile: () => reconcileInterfaceRetrieveRun(options.knowledgeBasePath),
+        refreshArtifacts: () => refreshInterfaceArtifacts(options.knowledgeBasePath, { ensureViewSpec: true }),
+        validate: () => validateInterfaceRetrieve(options.knowledgeBasePath),
     });
-    if (code !== 0) {
+    if (!stageResult.ok) {
         return {
             ok: false,
-            code,
+            code: stageResult.code,
             knowledgeBaseSummaryTotal,
             relevantCount: 0,
             deltaCount: 0,
             analyzeCount: 0,
         };
     }
-    refreshInterfaceArtifacts(options.knowledgeBasePath, { ensureViewSpec: true });
-    const validation = validateStageOutcome(options.knowledgeBasePath, validateInterfaceRetrieve(options.knowledgeBasePath));
-    if (!validation.ok) {
-        reportValidationFailure(options.reporter, validation.summary);
-        markRuntimeRunFailedAfterValidation(options.knowledgeBasePath, validation.summary);
-    }
     const queryState = loadState(options.knowledgeBasePath);
     const relevantCount = queryState?.relevant_count ?? 0;
     const deltaCount = queryState?.delta_count ?? relevantCount;
     const analyzeCount = deltaCount > 0 ? deltaCount : relevantCount;
     return {
-        ok: validation.ok,
-        code: validation.ok ? 0 : 1,
+        ok: true,
+        code: 0,
         knowledgeBaseSummaryTotal,
         relevantCount,
         deltaCount,
@@ -424,7 +172,7 @@ export async function runInterfaceAnalyze(options) {
     const workflowId = resolveInterfaceWorkflowFromConfig(interfaceConfig);
     const connectedKnowledgeBasePath = resolveInterfaceKnowledgeBasePath(options.knowledgeBasePath);
     const sourcePath = options.sourcePath ?? (connectedKnowledgeBasePath ? resolveKnowledgeBaseSourcePath(connectedKnowledgeBasePath) : options.knowledgeBasePath);
-    const stageDefinition = options.stageDefinition ?? interfaceExecutionStages(workflowId, options.knowledgeBasePath).find((stage) => stage.contractType === "interface-analysis");
+    const stageDefinition = options.stageDefinition ?? findStageByContractType(interfaceExecutionStages(workflowId, options.knowledgeBasePath), "interface-analysis");
     const stageStatusLabel = stageDefinition.label.toLowerCase();
     const queryState = loadState(options.knowledgeBasePath);
     const relevantCount = queryState?.relevant_count ?? 0;
@@ -434,50 +182,44 @@ export async function runInterfaceAnalyze(options) {
         reportBlankLine(options.reporter);
         reportLine(options.reporter, `${formatInterfaceWorkflowStageStep(workflowId, stageDefinition.id, { sourcePath })}${analyzeCount > 0 ? ` (${analyzeCount} files)` : ""}`);
     }
-    const instructions = buildStageInstructions(bundledSkillForContractType(stageDefinition.contractType), mergeLocalSkillContractExtensions([
-        connectedKnowledgeBasePath
-            ? buildLocalSkillContractExtensionRelativeTo(connectedKnowledgeBasePath, options.knowledgeBasePath, [workflowQueryDirectory()], "Use the connected knowledge-base workflow docs as higher-level knowledge-base guidance before applying interface-local analyze rules.")
-            : emptyLocalSkillContractExtension(),
-        buildLocalSkillContractExtension(options.knowledgeBasePath, [workflowCompileStageDirectory(stageDefinition.skillDir)], "Use interface-local docs to refine the interface ontology, extraction schema, and evidence grouping."),
-    ]));
-    const code = await runExecutorStage({
+    const instructions = buildInterfaceStageInstructions(stageDefinition.contractType, options.knowledgeBasePath, connectedKnowledgeBasePath, stageDefinition.skillDir, "Use the connected knowledge-base workflow README as high-level knowledge-base context before applying interface-local analyze rules.", "Use interface-local docs to refine the interface ontology, extraction schema, and evidence grouping.");
+    const stageResult = await executeValidatedStage({
         executor: options.executor,
-        knowledgeBasePath: options.knowledgeBasePath,
+        workspacePath: options.knowledgeBasePath,
         targetType: "interface",
-        knowledgeBaseName,
+        targetName: knowledgeBaseName,
         workflow: workflowId,
         workflowSourcePath: sourcePath,
-        stage: stageDefinition.id,
-        stageLabel: stageDefinition.label,
-        contractType: stageDefinition.contractType,
+        stageDefinition,
+        instructions,
         summary: `Preparing ${stageDefinition.label.toLowerCase()} for ${analyzeCount} interface summaries.`,
         contract: buildInterfaceAnalyzeContract(options.knowledgeBasePath, workflowId, analyzeCount, instructions, stageDefinition.id, stageDefinition.skillDir),
-        buildPrompt: (contractPath) => buildStagePrompt(instructions, contractPath, [
+        statusLines: [
             `Emit exactly one startup line: STATUS: loaded ${stageStatusLabel} plan ${analyzeCount} files.`,
+            "Emit STATUS: inspecting <current subtask> before each new raw page group, market batch, chart family, or extraction method.",
+            "During long-running raw/PDF/chart extraction, do not stay silent for more than about one minute. Emit another STATUS: inspecting <current subtask> line before continuing.",
             `Emit STATUS: analyzed X/${analyzeCount} after each batch or every 25 files, whichever comes first.`,
+            `If the target ledger is narrower than the file count, still emit visible STATUS lines as each target batch is classified. Do not wait for the final analyzed X/${analyzeCount} milestone before reporting progress.`,
             `Emit STATUS: wrote ${stageStatusLabel} outputs after \`.interf/analysis.json\` is updated.`,
-            `Emit DONE: ${stageStatusLabel} complete when state reflects the finished extraction pass.`,
-        ]),
+            `Emit DONE: ${stageStatusLabel} complete when \`.interf/analysis.json\` reflects the finished extraction pass.`,
+        ],
+        reporter: options.reporter,
         completionCheck: () => {
             const state = loadState(options.knowledgeBasePath);
             return Boolean(state?.analyze_complete &&
                 existsSync(join(options.knowledgeBasePath, ".interf", "analysis.json")) &&
                 validateStageContractAcceptance(options.knowledgeBasePath).ok);
         },
+        reconcile: () => reconcileInterfaceAnalyzeRun(options.knowledgeBasePath),
+        refreshArtifacts: () => refreshInterfaceArtifacts(options.knowledgeBasePath, { ensureViewSpec: true }),
+        validate: () => ({
+            ok: true,
+            summary: "Interface analyze verified.",
+        }),
     });
-    if (code === 0) {
-        refreshInterfaceArtifacts(options.knowledgeBasePath, { ensureViewSpec: true });
-    }
-    const acceptance = code === 0
-        ? validateStageContractAcceptance(options.knowledgeBasePath)
-        : { ok: false, summary: "Stage execution failed before acceptance validation." };
-    if (code === 0 && !acceptance.ok) {
-        reportValidationFailure(options.reporter, acceptance.summary);
-        markRuntimeRunFailedAfterValidation(options.knowledgeBasePath, acceptance.summary);
-    }
     return {
-        ok: code === 0 && acceptance.ok,
-        code: code === 0 && acceptance.ok ? 0 : 1,
+        ok: stageResult.ok,
+        code: stageResult.code,
         relevantCount,
         deltaCount,
         analyzeCount,
@@ -489,54 +231,64 @@ export async function runInterfaceCompileStage(options) {
     const workflowId = resolveInterfaceWorkflowFromConfig(interfaceConfig);
     const connectedKnowledgeBasePath = resolveInterfaceKnowledgeBasePath(options.knowledgeBasePath);
     const sourcePath = options.sourcePath ?? (connectedKnowledgeBasePath ? resolveKnowledgeBaseSourcePath(connectedKnowledgeBasePath) : options.knowledgeBasePath);
-    const stageDefinition = options.stageDefinition ?? interfaceExecutionStages(workflowId, options.knowledgeBasePath).find((stage) => stage.contractType === "interface-output");
+    const stageDefinition = options.stageDefinition ?? findStageByContractType(interfaceExecutionStages(workflowId, options.knowledgeBasePath), "interface-output");
     const stageStatusLabel = stageDefinition.label.toLowerCase();
     const relevantCount = loadState(options.knowledgeBasePath)?.relevant_count ?? 0;
     if (options.reportStep !== false) {
         reportBlankLine(options.reporter);
         reportLine(options.reporter, formatInterfaceWorkflowStageStep(workflowId, stageDefinition.id, { sourcePath }));
     }
-    const instructions = buildStageInstructions(bundledSkillForContractType(stageDefinition.contractType), mergeLocalSkillContractExtensions([
-        connectedKnowledgeBasePath
-            ? buildLocalSkillContractExtensionRelativeTo(connectedKnowledgeBasePath, options.knowledgeBasePath, [workflowQueryDirectory()], "Use the connected knowledge-base workflow docs as higher-level knowledge-base guidance before applying interface-local compile rules.")
-            : emptyLocalSkillContractExtension(),
-        buildLocalSkillContractExtension(options.knowledgeBasePath, [workflowCompileStageDirectory(stageDefinition.skillDir)], "Use interface-local docs to refine the output inventory, navigation, canvases, and final interface shape."),
-    ]));
-    const code = await runExecutorStage({
+    const instructions = buildInterfaceStageInstructions(stageDefinition.contractType, options.knowledgeBasePath, connectedKnowledgeBasePath, stageDefinition.skillDir, "Use the connected knowledge-base workflow README as high-level knowledge-base context before applying interface-local compile rules.", "Use interface-local docs to refine the output inventory, navigation, canvases, and final interface shape.");
+    const stageResult = await executeValidatedStage({
         executor: options.executor,
-        knowledgeBasePath: options.knowledgeBasePath,
+        workspacePath: options.knowledgeBasePath,
         targetType: "interface",
-        knowledgeBaseName,
+        targetName: knowledgeBaseName,
         workflow: workflowId,
         workflowSourcePath: sourcePath,
-        stage: stageDefinition.id,
-        stageLabel: stageDefinition.label,
-        contractType: stageDefinition.contractType,
+        stageDefinition,
+        instructions,
         summary: `Preparing ${stageDefinition.label.toLowerCase()} from ${relevantCount} relevant files.`,
         contract: buildInterfaceCompileContract(options.knowledgeBasePath, workflowId, relevantCount, instructions, stageDefinition.id, stageDefinition.skillDir),
-        buildPrompt: (contractPath) => buildStagePrompt(instructions, contractPath, [
+        statusLines: [
             `Emit exactly one startup line: STATUS: loaded ${stageStatusLabel} plan ${relevantCount} relevant files.`,
             "Emit STATUS: wrote entities X after the entity pass completes.",
             "Emit STATUS: wrote claims Y after the claim pass completes.",
             `Emit STATUS: wrote ${stageStatusLabel} outputs after local notes and home.md are updated.`,
-            `Emit DONE: ${stageStatusLabel} complete when state is updated and temporary analysis artifacts are cleaned up.`,
-        ]),
-        completionCheck: () => computeInterfaceHealth(options.knowledgeBasePath).status === "compiled" &&
-            validateStageContractAcceptance(options.knowledgeBasePath).ok,
+            `Emit DONE: ${stageStatusLabel} complete when the required outputs are on disk and temporary analysis artifacts are cleaned up.`,
+        ],
+        reporter: options.reporter,
+        completionCheck: () => {
+            const state = loadState(options.knowledgeBasePath);
+            const health = computeInterfaceHealth(options.knowledgeBasePath);
+            return Boolean(state?.compile_complete &&
+                typeof state.last_compile === "string" &&
+                health.checks.home_present &&
+                health.checks.outputs_present &&
+                !health.checks.analysis_pending &&
+                validateStageContractAcceptance(options.knowledgeBasePath).ok);
+        },
+        reconcile: () => reconcileInterfaceCompileRun(options.knowledgeBasePath),
+        refreshArtifacts: () => refreshInterfaceArtifacts(options.knowledgeBasePath, { ensureViewSpec: true }),
+        validate: () => {
+            const state = loadState(options.knowledgeBasePath);
+            const health = computeInterfaceHealth(options.knowledgeBasePath);
+            const ok = Boolean(state?.compile_complete &&
+                typeof state.last_compile === "string" &&
+                health.checks.home_present &&
+                health.checks.outputs_present &&
+                !health.checks.analysis_pending);
+            return {
+                ok,
+                summary: ok
+                    ? "Interface compile verified."
+                    : `Interface compile failed — health is ${health.status}/${health.stage}.`,
+            };
+        },
     });
-    if (code === 0) {
-        refreshInterfaceArtifacts(options.knowledgeBasePath, { ensureViewSpec: true });
-    }
-    const acceptance = code === 0
-        ? validateStageContractAcceptance(options.knowledgeBasePath)
-        : { ok: false, summary: "Stage execution failed before acceptance validation." };
-    if (code === 0 && !acceptance.ok) {
-        reportValidationFailure(options.reporter, acceptance.summary);
-        markRuntimeRunFailedAfterValidation(options.knowledgeBasePath, acceptance.summary);
-    }
     return {
-        ok: code === 0 && acceptance.ok,
-        code: code === 0 && acceptance.ok ? 0 : 1,
+        ok: stageResult.ok,
+        code: stageResult.code,
         relevantCount,
     };
 }