@interf/compiler 0.1.9 → 0.1.11

package/dist/lib/workflows-interface.js

@@ -0,0 +1,625 @@
+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 { 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
+// ---------------------------------------------------------------------------
+export function resolveInterfaceContext(knowledgeBasePath) {
+    const config = readInterfConfig(knowledgeBasePath);
+    const workflowId = resolveInterfaceWorkflowFromConfig(config);
+    const connectedKnowledgeBasePath = resolveInterfaceKnowledgeBasePath(knowledgeBasePath);
+    return {
+        knowledgeBaseName: config?.name ?? "interface",
+        connectedKnowledgeBasePath,
+        sourcePath: connectedKnowledgeBasePath ? resolveKnowledgeBaseSourcePath(connectedKnowledgeBasePath) : null,
+        workflowId,
+    };
+}
+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([
+        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.")
+            : 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.",
+            },
+        },
+    };
+}
+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([
+        connectedKnowledgeBasePath
+            ? buildLocalSkillContractExtensionRelativeTo(connectedKnowledgeBasePath, interfacePath, [workflowQueryDirectory()], "Use the connected knowledge-base workflow docs as higher-level knowledge-base guidance before applying interface-local compile rules.")
+            : 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.",
+            },
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Interface orchestration functions
+// ---------------------------------------------------------------------------
+export async function planInterface(options) {
+    const connectedKnowledgeBasePath = resolveInterfaceKnowledgeBasePath(options.knowledgeBasePath);
+    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 code = await runExecutorStage({
+        executor: options.executor,
+        knowledgeBasePath: options.knowledgeBasePath,
+        targetType: "interface",
+        knowledgeBaseName: options.name,
+        workflow: interfaceWorkflow,
+        workflowSourcePath: connectedKnowledgeBasePath ? resolveKnowledgeBaseSourcePath(connectedKnowledgeBasePath) : undefined,
+        stage: "create-interface",
+        stageLabel: "Create Interface",
+        contractType: "interface-plan",
+        summary: `Designing the initial runtime hypothesis for the ${options.name} interface.`,
+        contract: buildInterfaceCreateContract({
+            name: options.name,
+            workflow: options.workflow,
+            useCase: options.useCase,
+            knowledgeBaseName: options.knowledgeBaseName,
+            knowledgeBasePath: options.knowledgeBasePath,
+            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`.",
+        ]),
+    });
+    syncClaudeBootstrap(options.knowledgeBasePath);
+    const validation = validateInterfacePlan(options.knowledgeBasePath);
+    const emittedDone = runtimeRunStdoutContains(options.knowledgeBasePath, "DONE: interface create complete");
+    if (validation.ok && (code === 0 || emittedDone)) {
+        if (code !== 0) {
+            markRuntimeRunSucceededAfterValidation(options.knowledgeBasePath, "create-interface completed successfully.");
+        }
+        return {
+            ok: true,
+            code: 0,
+            summary: validation.summary,
+        };
+    }
+    if (!validation.ok) {
+        markRuntimeRunFailedAfterValidation(options.knowledgeBasePath, validation.summary);
+    }
+    return {
+        ok: false,
+        code,
+        summary: validation.summary,
+    };
+}
+export async function runInterfaceRetrieve(options) {
+    const context = resolveInterfaceContext(options.knowledgeBasePath);
+    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 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({
+        executor: options.executor,
+        knowledgeBasePath: options.knowledgeBasePath,
+        targetType: "interface",
+        knowledgeBaseName: context.knowledgeBaseName,
+        workflow: workflowId,
+        workflowSourcePath: sourcePath,
+        stage: stageDefinition.id,
+        stageLabel: stageDefinition.label,
+        contractType: stageDefinition.contractType,
+        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, [
+            `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.`,
+        ]),
+        completionCheck: () => isRetrieveStageComplete(options.knowledgeBasePath) &&
+            validateStageContractAcceptance(options.knowledgeBasePath).ok,
+    });
+    if (code !== 0) {
+        return {
+            ok: false,
+            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,
+        knowledgeBaseSummaryTotal,
+        relevantCount,
+        deltaCount,
+        analyzeCount,
+    };
+}
+export async function runInterfaceAnalyze(options) {
+    const interfaceConfig = readInterfConfig(options.knowledgeBasePath);
+    const knowledgeBaseName = interfaceConfig?.name ?? "interface";
+    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 stageStatusLabel = stageDefinition.label.toLowerCase();
+    const queryState = loadState(options.knowledgeBasePath);
+    const relevantCount = queryState?.relevant_count ?? 0;
+    const deltaCount = queryState?.delta_count ?? relevantCount;
+    const analyzeCount = deltaCount > 0 ? deltaCount : relevantCount;
+    if (options.reportStep !== false) {
+        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({
+        executor: options.executor,
+        knowledgeBasePath: options.knowledgeBasePath,
+        targetType: "interface",
+        knowledgeBaseName,
+        workflow: workflowId,
+        workflowSourcePath: sourcePath,
+        stage: stageDefinition.id,
+        stageLabel: stageDefinition.label,
+        contractType: stageDefinition.contractType,
+        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, [
+            `Emit exactly one startup line: STATUS: loaded ${stageStatusLabel} plan ${analyzeCount} files.`,
+            `Emit STATUS: analyzed X/${analyzeCount} after each batch or every 25 files, whichever comes first.`,
+            `Emit STATUS: wrote ${stageStatusLabel} outputs after \`.interf/analysis.json\` is updated.`,
+            `Emit DONE: ${stageStatusLabel} complete when state reflects the finished extraction pass.`,
+        ]),
+        completionCheck: () => {
+            const state = loadState(options.knowledgeBasePath);
+            return Boolean(state?.analyze_complete &&
+                existsSync(join(options.knowledgeBasePath, ".interf", "analysis.json")) &&
+                validateStageContractAcceptance(options.knowledgeBasePath).ok);
+        },
+    });
+    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,
+        relevantCount,
+        deltaCount,
+        analyzeCount,
+    };
+}
+export async function runInterfaceCompileStage(options) {
+    const interfaceConfig = readInterfConfig(options.knowledgeBasePath);
+    const knowledgeBaseName = interfaceConfig?.name ?? "interface";
+    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 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({
+        executor: options.executor,
+        knowledgeBasePath: options.knowledgeBasePath,
+        targetType: "interface",
+        knowledgeBaseName,
+        workflow: workflowId,
+        workflowSourcePath: sourcePath,
+        stage: stageDefinition.id,
+        stageLabel: stageDefinition.label,
+        contractType: stageDefinition.contractType,
+        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, [
+            `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,
+    });
+    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,
+        relevantCount,
+    };
+}
+export async function compileInterface(options) {
+    refreshWorkspaceBootstrapGuidance(options.knowledgeBasePath);
+    const context = resolveInterfaceContext(options.knowledgeBasePath);
+    const sourcePath = context.sourcePath ?? (context.connectedKnowledgeBasePath ? resolveKnowledgeBaseSourcePath(context.connectedKnowledgeBasePath) : options.knowledgeBasePath);
+    const stages = interfaceExecutionStages(context.workflowId, options.knowledgeBasePath);
+    let retrieve = {
+        ok: true,
+        code: 0,
+        knowledgeBaseSummaryTotal: 0,
+        relevantCount: 0,
+        deltaCount: 0,
+        analyzeCount: 0,
+    };
+    let analyze = null;
+    let compile = null;
+    for (const stageDefinition of stages) {
+        if (stageDefinition.contractType === "interface-retrieval") {
+            retrieve = await runInterfaceRetrieve({
+                executor: options.executor,
+                knowledgeBasePath: options.knowledgeBasePath,
+                sourcePath,
+                reporter: options.reporter,
+                reportStep: true,
+                stageDefinition,
+            });
+            if (!retrieve.ok) {
+                return {
+                    ok: false,
+                    retrieve,
+                    analyze: null,
+                    compile: null,
+                    failedStage: stageDefinition.id,
+                };
+            }
+            continue;
+        }
+        if (stageDefinition.contractType === "interface-analysis") {
+            analyze = await runInterfaceAnalyze({
+                executor: options.executor,
+                knowledgeBasePath: options.knowledgeBasePath,
+                sourcePath,
+                reporter: options.reporter,
+                reportStep: true,
+                stageDefinition,
+            });
+            if (!analyze.ok) {
+                return {
+                    ok: false,
+                    retrieve,
+                    analyze,
+                    compile: null,
+                    failedStage: stageDefinition.id,
+                };
+            }
+            continue;
+        }
+        compile = await runInterfaceCompileStage({
+            executor: options.executor,
+            knowledgeBasePath: options.knowledgeBasePath,
+            sourcePath,
+            reporter: options.reporter,
+            reportStep: true,
+            stageDefinition,
+        });
+        if (!compile.ok) {
+            return {
+                ok: false,
+                retrieve,
+                analyze,
+                compile,
+                failedStage: stageDefinition.id,
+            };
+        }
+    }
+    return {
+        ok: compile?.ok ?? analyze?.ok ?? retrieve.ok,
+        retrieve,
+        analyze,
+        compile,
+        failedStage: null,
+    };
+}
+//# sourceMappingURL=workflows-interface.js.map