@interf/compiler 0.3.4 → 0.4.1

package/dist/lib/validate-workspace.js

@@ -4,9 +4,11 @@ import { countFilesRecursive, listFilesRecursive } from "./filesystem.js";
 import { discoverSourceFiles } from "./discovery.js";
 import { resolveSourceFolderPath } from "./interf.js";
 import { readJsonFileUnchecked } from "./parse.js";
+import { workspaceHomeIsShaped } from "./workspace-home.js";
 import { WorkspaceInventorySchema, WorkspaceStateSchema, } from "./schema.js";
 import { readWorkspaceConfig, validateSynthFiles, countBrokenWikilinks, asNumber, isOutputMarkdownFile, } from "./validate.js";
 import { readInventoryFiles, readInventoryTotal, } from "./validate-helpers.js";
+import { workspaceInterfConfigPath, workspaceRuntimeRoot, } from "./workspace-paths.js";
 export function validateWorkspace(dirPath) {
     const config = readWorkspaceConfig(dirPath);
     const summaryFiles = listFilesRecursive(join(dirPath, "summaries"), isOutputMarkdownFile);
@@ -32,8 +34,9 @@ export function validateWorkspaceSummarize(dirPath) {
     const summaryFiles = listFilesRecursive(join(dirPath, "summaries"), isOutputMarkdownFile);
     const summaryValidation = validateSynthFiles(summaryFiles);
     const summarized = summaryFiles.length;
-    const statePath = join(dirPath, ".interf", "state.json");
-    const inventoryPath = join(dirPath, ".interf", "inventory.json");
+    const runtimeRoot = workspaceRuntimeRoot(dirPath);
+    const statePath = join(runtimeRoot, "state.json");
+    const inventoryPath = join(runtimeRoot, "inventory.json");
     const statePresent = existsSync(statePath);
     const inventoryPresent = existsSync(inventoryPath);
     const state = statePresent
@@ -69,21 +72,21 @@ export function validateWorkspaceSummarize(dirPath) {
     };
     const errors = [];
     if (!checks.config_present)
-        errors.push("Missing interf.json.");
+        errors.push(`Missing ${workspaceInterfConfigPath(dirPath)}.`);
     else if (!checks.config_valid)
-        errors.push("Could not parse interf.json.");
+        errors.push(`Could not parse ${workspaceInterfConfigPath(dirPath)}.`);
     else if (!checks.config_type_match)
         errors.push("Config is not a workspace.");
     if (required && !checks.summaries_present)
         errors.push("Missing summaries/ directory.");
     if (required && !checks.state_present)
-        errors.push("Missing .interf/state.json.");
+        errors.push("Missing .interf/runtime/state.json.");
     else if (required && !checks.state_valid)
-        errors.push("Could not parse .interf/state.json.");
+        errors.push("Could not parse .interf/runtime/state.json.");
     if (required && !checks.inventory_present)
-        errors.push("Missing .interf/inventory.json.");
+        errors.push("Missing .interf/runtime/inventory.json.");
     else if (required && !checks.inventory_valid)
-        errors.push("Could not parse .interf/inventory.json or it has the wrong shape.");
+        errors.push("Could not parse .interf/runtime/inventory.json or it has the wrong shape.");
     if (required && checks.inventory_present && checks.inventory_valid && !checks.inventory_complete) {
         errors.push("state.json does not mark inventory_complete.");
     }
@@ -126,8 +129,9 @@ export function validateWorkspaceCompile(dirPath) {
     const summarizeValidation = validateWorkspaceSummarize(dirPath);
     const structureValidation = validateWorkspaceStructure(dirPath);
     const config = readWorkspaceConfig(dirPath);
-    const statePath = join(dirPath, ".interf", "state.json");
-    const inventoryPath = join(dirPath, ".interf", "inventory.json");
+    const runtimeRoot = workspaceRuntimeRoot(dirPath);
+    const statePath = join(runtimeRoot, "state.json");
+    const inventoryPath = join(runtimeRoot, "inventory.json");
     const statePresent = existsSync(statePath);
     const inventoryPresent = existsSync(inventoryPath);
     const state = statePresent
@@ -169,6 +173,7 @@ export function validateWorkspaceCompile(dirPath) {
     const indexFiles = countFilesRecursive(join(dirPath, "knowledge", "indexes"));
     const outputs = entityFiles + claimFiles + indexFiles;
     const homePresent = existsSync(join(dirPath, "home.md"));
+    const homeShaped = workspaceHomeIsShaped(dirPath);
     const brokenLinks = countBrokenWikilinks(dirPath, [join(dirPath, "summaries"), join(dirPath, "knowledge"), join(dirPath, "home.md")], [join(dirPath, "summaries"), join(dirPath, "knowledge"), join(dirPath, "home.md")]);
     const required = structureValidation.required || homePresent || shaped > 0 || compiled > 0 || inventoryPresent;
     const checks = {
@@ -195,13 +200,14 @@ export function validateWorkspaceCompile(dirPath) {
             state.last_compile.length > 0,
         outputs_present: outputs > 0,
         home_present: homePresent,
+        home_shaped: homeShaped,
         links_valid: brokenLinks === 0,
     };
     const errors = [];
     if (!checks.config_present)
-        errors.push("Missing interf.json.");
+        errors.push(`Missing ${workspaceInterfConfigPath(dirPath)}.`);
     else if (!checks.config_valid)
-        errors.push("Could not parse interf.json.");
+        errors.push(`Could not parse ${workspaceInterfConfigPath(dirPath)}.`);
     else if (!checks.config_type_match)
         errors.push("Config is not a workspace.");
     if (!checks.summarize_complete)
@@ -209,13 +215,13 @@ export function validateWorkspaceCompile(dirPath) {
     if (!checks.structure_complete)
         errors.push("Workspace structure is incomplete or invalid.");
     if (!checks.state_present)
-        errors.push("Missing .interf/state.json.");
+        errors.push("Missing .interf/runtime/state.json.");
     else if (!checks.state_valid)
-        errors.push("Could not parse .interf/state.json.");
+        errors.push("Could not parse .interf/runtime/state.json.");
     if (!checks.inventory_present)
-        errors.push("Missing .interf/inventory.json.");
+        errors.push("Missing .interf/runtime/inventory.json.");
     else if (!checks.inventory_valid)
-        errors.push("Could not parse .interf/inventory.json or it has the wrong shape.");
+        errors.push("Could not parse .interf/runtime/inventory.json or it has the wrong shape.");
     if (checks.inventory_present && checks.inventory_valid && !checks.inventory_complete) {
         errors.push("state.json does not mark inventory_complete.");
     }
@@ -238,6 +244,9 @@ export function validateWorkspaceCompile(dirPath) {
         errors.push("Workspace compile outputs are missing or empty.");
     if (!checks.home_present)
         errors.push("Workspace home.md is missing.");
+    if (checks.home_present && !checks.home_shaped) {
+        errors.push("Workspace home.md still contains the uncompiled scaffold placeholder.");
+    }
     if (!checks.links_valid)
         errors.push("Some knowledge notes contain broken wikilinks.");
     const ok = required ? errors.length === 0 : true;
@@ -272,8 +281,9 @@ export function validateWorkspaceCompile(dirPath) {
 export function validateWorkspaceStructure(dirPath) {
     const summarizeValidation = validateWorkspaceSummarize(dirPath);
     const config = readWorkspaceConfig(dirPath);
-    const statePath = join(dirPath, ".interf", "state.json");
-    const inventoryPath = join(dirPath, ".interf", "inventory.json");
+    const runtimeRoot = workspaceRuntimeRoot(dirPath);
+    const statePath = join(runtimeRoot, "state.json");
+    const inventoryPath = join(runtimeRoot, "inventory.json");
     const statePresent = existsSync(statePath);
     const inventoryPresent = existsSync(inventoryPath);
     const state = statePresent
@@ -335,21 +345,21 @@ export function validateWorkspaceStructure(dirPath) {
     };
     const errors = [];
     if (!checks.config_present)
-        errors.push("Missing interf.json.");
+        errors.push(`Missing ${workspaceInterfConfigPath(dirPath)}.`);
     else if (!checks.config_valid)
-        errors.push("Could not parse interf.json.");
+        errors.push(`Could not parse ${workspaceInterfConfigPath(dirPath)}.`);
     else if (!checks.config_type_match)
         errors.push("Config is not a workspace.");
     if (!checks.summarize_complete)
         errors.push("Workspace summarize is incomplete or invalid.");
     if (!checks.state_present)
-        errors.push("Missing .interf/state.json.");
+        errors.push("Missing .interf/runtime/state.json.");
     else if (!checks.state_valid)
-        errors.push("Could not parse .interf/state.json.");
+        errors.push("Could not parse .interf/runtime/state.json.");
     if (!checks.inventory_present)
-        errors.push("Missing .interf/inventory.json.");
+        errors.push("Missing .interf/runtime/inventory.json.");
     else if (!checks.inventory_valid)
-        errors.push("Could not parse .interf/inventory.json or it has the wrong shape.");
+        errors.push("Could not parse .interf/runtime/inventory.json or it has the wrong shape.");
     if (checks.inventory_present && checks.inventory_valid && !checks.inventory_complete) {
         errors.push("state.json does not mark inventory_complete.");
     }
@@ -395,4 +405,3 @@ export function validateWorkspaceStructure(dirPath) {
         errors,
     };
 }
-//# sourceMappingURL=validate-workspace.js.map

package/dist/lib/validate.d.ts

@@ -15,4 +15,3 @@ export declare function isOutputMarkdownFile(filePath: string): boolean;
 export declare function safeReadText(filePath: string): string | null;
 export { validateWorkspace, validateWorkspaceSummarize, validateWorkspaceStructure, validateWorkspaceCompile, } from "./validate-workspace.js";
 export type { WorkspaceValidationSummary, WorkspaceSummarizeValidation, WorkspaceStructureValidation, WorkspaceCompileValidation, } from "./validate-workspace.js";
-//# sourceMappingURL=validate.d.ts.map

package/dist/lib/validate.js

@@ -3,6 +3,7 @@ import { basename, extname, join } from "node:path";
 import { listFilesRecursive } from "./filesystem.js";
 import { readInterfConfig } from "./interf.js";
 import { parseJsonFrontmatter } from "./parse.js";
+import { workspaceInterfConfigPath } from "./workspace-paths.js";
 const REQUIRED_DIGEST_FIELDS = [
     "source_kind",
     "evidence_tier",
@@ -11,8 +12,10 @@ const REQUIRED_DIGEST_FIELDS = [
 ];
 const MIN_ABSTRACT_WORDS = 5;
 const WIKILINK_PATTERN = /!?\[\[([^[\]]+)\]\]/g;
+const KNOWLEDGE_RELATIVE_PREFIXES = new Set(["entities", "claims", "indexes"]);
 export function readWorkspaceConfig(dirPath) {
-    const configPath = join(dirPath, "interf.json");
+    const configPath = workspaceInterfConfigPath(dirPath);
+    const value = readInterfConfig(dirPath);
     const present = existsSync(configPath);
     if (!present) {
         return {
@@ -22,7 +25,6 @@ export function readWorkspaceConfig(dirPath) {
             typeMatch: () => false,
         };
     }
-    const value = readInterfConfig(dirPath);
     return {
         present: true,
         valid: value !== null,
@@ -57,7 +59,9 @@ export function validateSynthFiles(files) {
 export function countBrokenWikilinks(workspaceRoot, noteIndexRoots, linkScanRoots) {
     const noteIndex = new Set();
     for (const filePath of dedupeFiles(noteIndexRoots)) {
-        noteIndex.add(noteName(filePath).toLowerCase());
+        for (const target of collectWikilinkTargets(filePath)) {
+            noteIndex.add(target.toLowerCase());
+        }
     }
     let brokenLinks = 0;
     for (const filePath of dedupeFiles(linkScanRoots)) {
@@ -73,11 +77,7 @@ export function countBrokenWikilinks(workspaceRoot, noteIndexRoots, linkScanRoot
             if (!target)
                 continue;
             if (target.includes("/")) {
-                const directPath = join(workspaceRoot, target);
-                const markdownPath = directPath.endsWith(".md")
-                    ? directPath
-                    : `${directPath}.md`;
-                if (!existsSync(directPath) && !existsSync(markdownPath)) {
+                if (!wikilinkPathExists(workspaceRoot, target)) {
                     brokenLinks += 1;
                 }
                 continue;
@@ -157,5 +157,51 @@ function countWords(text) {
 function noteName(filePath) {
     return basename(filePath, extname(filePath));
 }
+function wikilinkPathExists(workspaceRoot, target) {
+    return linkPathCandidates(workspaceRoot, target).some((candidate) => existsSync(candidate));
+}
+function linkPathCandidates(workspaceRoot, target) {
+    const candidates = new Set();
+    addPathCandidate(candidates, join(workspaceRoot, target));
+    const [firstSegment] = target.split("/");
+    if (firstSegment && KNOWLEDGE_RELATIVE_PREFIXES.has(firstSegment)) {
+        addPathCandidate(candidates, join(workspaceRoot, "knowledge", target));
+    }
+    return Array.from(candidates);
+}
+function addPathCandidate(candidates, absolutePath) {
+    candidates.add(absolutePath);
+    if (!absolutePath.endsWith(".md")) {
+        candidates.add(`${absolutePath}.md`);
+    }
+}
+function collectWikilinkTargets(filePath) {
+    const targets = new Set();
+    targets.add(noteName(filePath));
+    const content = safeReadText(filePath);
+    if (content === null)
+        return Array.from(targets);
+    const parsed = parseJsonFrontmatter(content);
+    const frontmatter = parsed?.frontmatter;
+    if (!frontmatter)
+        return Array.from(targets);
+    addFrontmatterLinkTarget(targets, frontmatter.label);
+    addFrontmatterLinkTarget(targets, frontmatter.title);
+    addFrontmatterLinkTarget(targets, frontmatter.alias);
+    addFrontmatterLinkTarget(targets, frontmatter.aliases);
+    return Array.from(targets);
+}
+function addFrontmatterLinkTarget(targets, value) {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed.length > 0)
+            targets.add(trimmed);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value) {
+            addFrontmatterLinkTarget(targets, entry);
+        }
+    }
+}
 export { validateWorkspace, validateWorkspaceSummarize, validateWorkspaceStructure, validateWorkspaceCompile, } from "./validate-workspace.js";
-//# sourceMappingURL=validate.js.map

package/dist/lib/workflow-abi.d.ts

@@ -0,0 +1,138 @@
+export declare const WORKSPACE_CONTRACT_TYPES: readonly ["workspace-file-evidence", "workspace-knowledge-structure", "workspace-query-shape"];
+export type WorkspaceContractType = typeof WORKSPACE_CONTRACT_TYPES[number];
+export declare const WORKSPACE_ZONE_KINDS: readonly ["directory", "file", "runtime"];
+export type WorkspaceZoneKind = typeof WORKSPACE_ZONE_KINDS[number];
+export declare const WORKSPACE_CONTRACT_FAMILY_METADATA: {
+    readonly "workspace-file-evidence": {
+        readonly order: 0;
+        readonly bundledSkill: "compile/stages/summarize";
+    };
+    readonly "workspace-knowledge-structure": {
+        readonly order: 1;
+        readonly bundledSkill: "compile/stages/structure";
+    };
+    readonly "workspace-query-shape": {
+        readonly order: 2;
+        readonly bundledSkill: "compile/stages/shape";
+    };
+};
+export declare const BUILTIN_WORKSPACE_STAGE_IDS: {
+    readonly SUMMARIZE: "summarize";
+    readonly STRUCTURE: "structure";
+    readonly SHAPE: "shape";
+};
+export type BuiltinWorkspaceStageId = typeof BUILTIN_WORKSPACE_STAGE_IDS[keyof typeof BUILTIN_WORKSPACE_STAGE_IDS];
+export declare const BUILTIN_WORKSPACE_ZONE_IDS: {
+    readonly RAW: "raw";
+    readonly SUMMARIES: "summaries";
+    readonly KNOWLEDGE_ENTITIES: "knowledge-entities";
+    readonly KNOWLEDGE_CLAIMS: "knowledge-claims";
+    readonly KNOWLEDGE_INDEXES: "knowledge-indexes";
+    readonly HOME: "home";
+    readonly RUNTIME: "runtime";
+};
+export type BuiltinWorkspaceZoneId = typeof BUILTIN_WORKSPACE_ZONE_IDS[keyof typeof BUILTIN_WORKSPACE_ZONE_IDS];
+export interface BuiltinWorkspaceZoneSpec {
+    id: BuiltinWorkspaceZoneId;
+    path: string;
+    kind: WorkspaceZoneKind;
+    required: true;
+    description: string;
+}
+export declare const BUILTIN_WORKSPACE_ZONE_SPECS: readonly [{
+    readonly id: "raw";
+    readonly path: "raw";
+    readonly kind: "directory";
+    readonly required: true;
+    readonly description: "Workspace-local raw snapshot copied from the dataset for direct evidence and verification.";
+}, {
+    readonly id: "summaries";
+    readonly path: "summaries";
+    readonly kind: "directory";
+    readonly required: true;
+    readonly description: "Per-file evidence notes produced by file-evidence stages.";
+}, {
+    readonly id: "knowledge-entities";
+    readonly path: "knowledge/entities";
+    readonly kind: "directory";
+    readonly required: true;
+    readonly description: "Canonical entity notes produced by knowledge-structure stages.";
+}, {
+    readonly id: "knowledge-claims";
+    readonly path: "knowledge/claims";
+    readonly kind: "directory";
+    readonly required: true;
+    readonly description: "Claim notes produced by knowledge-structure stages.";
+}, {
+    readonly id: "knowledge-indexes";
+    readonly path: "knowledge/indexes";
+    readonly kind: "directory";
+    readonly required: true;
+    readonly description: "Retrieval indexes and navigation notes produced by structure and shape stages.";
+}, {
+    readonly id: "home";
+    readonly path: "home.md";
+    readonly kind: "file";
+    readonly required: true;
+    readonly description: "Primary entrypoint note for agents using the compiled workspace.";
+}, {
+    readonly id: "runtime";
+    readonly path: ".interf/runtime";
+    readonly kind: "runtime";
+    readonly required: true;
+    readonly description: "CLI-owned runtime state, health, stage contracts, and proof artifacts.";
+}];
+export interface BuiltinWorkspaceStageAccessPattern {
+    id: BuiltinWorkspaceStageId;
+    label: string;
+    description: string;
+    contractType: WorkspaceContractType;
+    skillDir: string;
+    reads: readonly BuiltinWorkspaceZoneId[];
+    writes: readonly BuiltinWorkspaceZoneId[];
+}
+export declare const BUILTIN_WORKSPACE_STAGE_ACCESS_PATTERNS: readonly [{
+    readonly id: "summarize";
+    readonly label: "Summarize";
+    readonly description: "Turn source files into per-file summaries.";
+    readonly contractType: "workspace-file-evidence";
+    readonly skillDir: "summarize";
+    readonly reads: readonly ["raw", "runtime"];
+    readonly writes: readonly ["summaries"];
+}, {
+    readonly id: "structure";
+    readonly label: "Structure";
+    readonly description: "Build the cross-file knowledge structure from the summaries.";
+    readonly contractType: "workspace-knowledge-structure";
+    readonly skillDir: "structure";
+    readonly reads: readonly ["summaries", "runtime"];
+    readonly writes: readonly ["knowledge-entities", "knowledge-claims", "knowledge-indexes"];
+}, {
+    readonly id: "shape";
+    readonly label: "Shape";
+    readonly description: "Shape the final workspace around the saved focus and truth checks.";
+    readonly contractType: "workspace-query-shape";
+    readonly skillDir: "shape";
+    readonly reads: readonly ["raw", "summaries", "knowledge-entities", "knowledge-claims", "knowledge-indexes", "runtime"];
+    readonly writes: readonly ["knowledge-indexes", "home"];
+}];
+export declare function workspaceContractOrder(contractType: WorkspaceContractType): number;
+export declare function workspaceBundledSkillForContractType(contractType: WorkspaceContractType): string;
+export declare function hasValidWorkspaceContractSequence(contractTypes: readonly WorkspaceContractType[]): boolean;
+export declare function listMissingWorkspaceContractTypes(contractTypes: readonly string[]): WorkspaceContractType[];
+export declare function validateWorkspaceContractSequence(contractTypes: readonly WorkspaceContractType[]): {
+    ok: boolean;
+    orderValid: boolean;
+    missing: WorkspaceContractType[];
+};
+export declare function listBuiltinWorkspaceZoneSpecs(): BuiltinWorkspaceZoneSpec[];
+export declare function listBuiltinWorkspaceFallbackStages(): Array<{
+    id: BuiltinWorkspaceStageId;
+    contract_type: WorkspaceContractType;
+    reads: BuiltinWorkspaceZoneId[];
+    writes: BuiltinWorkspaceZoneId[];
+}>;
+export declare function requiredWorkspaceZoneOwners<TStage extends {
+    id: string;
+    contractType: WorkspaceContractType;
+}>(stages: readonly TStage[], zoneId: BuiltinWorkspaceZoneId): string[];

package/dist/lib/workflow-abi.js

@@ -0,0 +1,181 @@
+export const WORKSPACE_CONTRACT_TYPES = [
+    "workspace-file-evidence",
+    "workspace-knowledge-structure",
+    "workspace-query-shape",
+];
+export const WORKSPACE_ZONE_KINDS = [
+    "directory",
+    "file",
+    "runtime",
+];
+export const WORKSPACE_CONTRACT_FAMILY_METADATA = {
+    "workspace-file-evidence": {
+        order: 0,
+        bundledSkill: "compile/stages/summarize",
+    },
+    "workspace-knowledge-structure": {
+        order: 1,
+        bundledSkill: "compile/stages/structure",
+    },
+    "workspace-query-shape": {
+        order: 2,
+        bundledSkill: "compile/stages/shape",
+    },
+};
+export const BUILTIN_WORKSPACE_STAGE_IDS = {
+    SUMMARIZE: "summarize",
+    STRUCTURE: "structure",
+    SHAPE: "shape",
+};
+export const BUILTIN_WORKSPACE_ZONE_IDS = {
+    RAW: "raw",
+    SUMMARIES: "summaries",
+    KNOWLEDGE_ENTITIES: "knowledge-entities",
+    KNOWLEDGE_CLAIMS: "knowledge-claims",
+    KNOWLEDGE_INDEXES: "knowledge-indexes",
+    HOME: "home",
+    RUNTIME: "runtime",
+};
+export const BUILTIN_WORKSPACE_ZONE_SPECS = [
+    {
+        id: BUILTIN_WORKSPACE_ZONE_IDS.RAW,
+        path: "raw",
+        kind: "directory",
+        required: true,
+        description: "Workspace-local raw snapshot copied from the dataset for direct evidence and verification.",
+    },
+    {
+        id: BUILTIN_WORKSPACE_ZONE_IDS.SUMMARIES,
+        path: "summaries",
+        kind: "directory",
+        required: true,
+        description: "Per-file evidence notes produced by file-evidence stages.",
+    },
+    {
+        id: BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_ENTITIES,
+        path: "knowledge/entities",
+        kind: "directory",
+        required: true,
+        description: "Canonical entity notes produced by knowledge-structure stages.",
+    },
+    {
+        id: BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_CLAIMS,
+        path: "knowledge/claims",
+        kind: "directory",
+        required: true,
+        description: "Claim notes produced by knowledge-structure stages.",
+    },
+    {
+        id: BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_INDEXES,
+        path: "knowledge/indexes",
+        kind: "directory",
+        required: true,
+        description: "Retrieval indexes and navigation notes produced by structure and shape stages.",
+    },
+    {
+        id: BUILTIN_WORKSPACE_ZONE_IDS.HOME,
+        path: "home.md",
+        kind: "file",
+        required: true,
+        description: "Primary entrypoint note for agents using the compiled workspace.",
+    },
+    {
+        id: BUILTIN_WORKSPACE_ZONE_IDS.RUNTIME,
+        path: ".interf/runtime",
+        kind: "runtime",
+        required: true,
+        description: "CLI-owned runtime state, health, stage contracts, and proof artifacts.",
+    },
+];
+export const BUILTIN_WORKSPACE_STAGE_ACCESS_PATTERNS = [
+    {
+        id: BUILTIN_WORKSPACE_STAGE_IDS.SUMMARIZE,
+        label: "Summarize",
+        description: "Turn source files into per-file summaries.",
+        contractType: "workspace-file-evidence",
+        skillDir: "summarize",
+        reads: [
+            BUILTIN_WORKSPACE_ZONE_IDS.RAW,
+            BUILTIN_WORKSPACE_ZONE_IDS.RUNTIME,
+        ],
+        writes: [
+            BUILTIN_WORKSPACE_ZONE_IDS.SUMMARIES,
+        ],
+    },
+    {
+        id: BUILTIN_WORKSPACE_STAGE_IDS.STRUCTURE,
+        label: "Structure",
+        description: "Build the cross-file knowledge structure from the summaries.",
+        contractType: "workspace-knowledge-structure",
+        skillDir: "structure",
+        reads: [
+            BUILTIN_WORKSPACE_ZONE_IDS.SUMMARIES,
+            BUILTIN_WORKSPACE_ZONE_IDS.RUNTIME,
+        ],
+        writes: [
+            BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_ENTITIES,
+            BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_CLAIMS,
+            BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_INDEXES,
+        ],
+    },
+    {
+        id: BUILTIN_WORKSPACE_STAGE_IDS.SHAPE,
+        label: "Shape",
+        description: "Shape the final workspace around the saved focus and truth checks.",
+        contractType: "workspace-query-shape",
+        skillDir: "shape",
+        reads: [
+            BUILTIN_WORKSPACE_ZONE_IDS.RAW,
+            BUILTIN_WORKSPACE_ZONE_IDS.SUMMARIES,
+            BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_ENTITIES,
+            BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_CLAIMS,
+            BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_INDEXES,
+            BUILTIN_WORKSPACE_ZONE_IDS.RUNTIME,
+        ],
+        writes: [
+            BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_INDEXES,
+            BUILTIN_WORKSPACE_ZONE_IDS.HOME,
+        ],
+    },
+];
+export function workspaceContractOrder(contractType) {
+    return WORKSPACE_CONTRACT_FAMILY_METADATA[contractType].order;
+}
+export function workspaceBundledSkillForContractType(contractType) {
+    return WORKSPACE_CONTRACT_FAMILY_METADATA[contractType].bundledSkill;
+}
+export function hasValidWorkspaceContractSequence(contractTypes) {
+    return contractTypes.every((contractType, index) => index === 0 ||
+        workspaceContractOrder(contractType) >= workspaceContractOrder(contractTypes[index - 1]));
+}
+export function listMissingWorkspaceContractTypes(contractTypes) {
+    return WORKSPACE_CONTRACT_TYPES.filter((contractType) => !contractTypes.includes(contractType));
+}
+export function validateWorkspaceContractSequence(contractTypes) {
+    const missing = listMissingWorkspaceContractTypes(contractTypes);
+    const orderValid = hasValidWorkspaceContractSequence(contractTypes);
+    return {
+        ok: missing.length === 0 && orderValid,
+        orderValid,
+        missing,
+    };
+}
+export function listBuiltinWorkspaceZoneSpecs() {
+    return BUILTIN_WORKSPACE_ZONE_SPECS.map((zone) => ({ ...zone }));
+}
+export function listBuiltinWorkspaceFallbackStages() {
+    return BUILTIN_WORKSPACE_STAGE_ACCESS_PATTERNS.map((stage) => ({
+        id: stage.id,
+        contract_type: stage.contractType,
+        reads: [...stage.reads],
+        writes: [...stage.writes],
+    }));
+}
+export function requiredWorkspaceZoneOwners(stages, zoneId) {
+    const writerContractTypes = new Set(BUILTIN_WORKSPACE_STAGE_ACCESS_PATTERNS
+        .filter((stage) => stage.writes.includes(zoneId))
+        .map((stage) => stage.contractType));
+    return Array.from(new Set(stages
+        .filter((stage) => writerContractTypes.has(stage.contractType))
+        .map((stage) => stage.id)));
+}

package/dist/lib/workflow-definitions.d.ts

@@ -1,6 +1,7 @@
 import type { RuntimeContractType, RuntimeStageAcceptance, WorkflowCompilerApi, WorkflowId, WorkflowZoneId } from "./schema.js";
-import { type StarterDoc } from "./workflow-starter-docs.js";
-export interface WorkflowStarterDoc extends StarterDoc {
+export interface WorkflowStarterDoc {
+    relativePath: string;
+    content: string;
 }
 export interface WorkflowStageDefinition {
     id: string;
@@ -24,12 +25,29 @@ export interface WorkflowDefinition<TId extends string> {
     scope?: "builtin" | "local";
 }
 export type WorkspaceWorkflowId = string;
-export declare const WORKSPACE_WORKFLOWS: WorkflowDefinition<"interf">[];
+export declare function standaloneWorkflowDefinitionFromLocalPackage(local: {
+    id: string;
+    compiler_api?: WorkflowCompilerApi;
+    label: string;
+    hint: string;
+    stages?: Array<{
+        id: string;
+        label: string;
+        description?: string;
+        contract_type: RuntimeContractType;
+        skill_dir?: string;
+        reads: WorkflowZoneId[];
+        writes: WorkflowZoneId[];
+        acceptance?: RuntimeStageAcceptance;
+    }>;
+    stage_policy_notes?: Record<string, string[]>;
+    starter_docs: WorkflowStarterDoc[];
+}): WorkflowDefinition<string>;
 export declare function listWorkspaceWorkflowChoices(sourcePath?: string): WorkflowDefinition<string>[];
 export declare function getWorkspaceWorkflow(workflowId: WorkspaceWorkflowId, options?: {
     sourcePath?: string;
-    visited?: Set<string>;
 }): WorkflowDefinition<string>;
+export declare function getActiveWorkspaceWorkflow(workspacePath: string, fallbackWorkflowId: WorkspaceWorkflowId): WorkflowDefinition<string>;
 export declare function resolveWorkspaceWorkflowId(value: unknown): WorkspaceWorkflowId;
 export declare function resolveWorkspaceWorkflowFromConfig(config: unknown): WorkspaceWorkflowId;
 export declare function formatWorkspaceWorkflowStageStep(workflowId: WorkspaceWorkflowId, stage: string, options?: {
@@ -42,5 +60,8 @@ export declare function getWorkflowStagePosition(workflowId: WorkflowId, stage:
     stages: string[];
 } | null;
 export declare function getWorkflowStages(workflowId: WorkflowId, sourcePath?: string): string[];
+export declare function getActiveWorkspaceStages(workspacePath: string, fallbackWorkflowId: WorkflowId): string[];
 export declare function getWorkflowStagePolicyNotes(workflowId: WorkflowId, stage: string, sourcePath?: string): string[];
-//# sourceMappingURL=workflow-definitions.d.ts.map
+export declare function getActiveWorkspaceStagePolicyNotes(workspacePath: string, fallbackWorkflowId: WorkflowId, stage: string): string[];
+export declare function resolveActiveWorkspaceStageAcceptance(workspacePath: string, fallbackWorkflowId: WorkflowId, stage: string): WorkflowStageDefinition["acceptance"] | undefined;
+export declare function formatActiveWorkspaceWorkflowStageStep(workspacePath: string, fallbackWorkflowId: WorkspaceWorkflowId, stage: string): string;