@interf/compiler 0.9.4 → 0.13.0

package/dist/packages/method-package/local-methods.js

@@ -1,5 +1,5 @@
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
-import { dirname, join, relative } from "node:path";
+import { basename, dirname, join, relative } from "node:path";
 import { z } from "zod";
 import { listFilesRecursive } from "../shared/filesystem.js";
 import { warnInterf } from "../shared/logger.js";
@@ -7,10 +7,10 @@ import { readJsonFileUnchecked, readJsonFileWithSchema } from "../shared/parse.j
 import { isMarkdownFile } from "../shared/file-types.js";
 import { MethodCompilerApiSchema, RuntimeStageAcceptanceSchema, MethodPurposeSchema, MethodStageZoneAccessSchema, } from "../compiler/lib/schema.js";
 import { RuntimeContractTypeSchema, InterfIdPattern, } from "../contracts/lib/schema.js";
+import { asPreparationDataDir, preparationMethodsRoot, } from "../contracts/lib/preparation-paths.js";
 import { listBuiltinCompiledZoneSpecs, } from "./builtin-compiled-method.js";
 import { CONTEXT_INTERFACE_FILE, ContextInterfaceSchema, contextInterfaceExists, contextInterfaceFilePath, readContextInterface, MethodInputSpecSchema, writeContextInterface, } from "./context-interface.js";
 import { PACKAGE_ROOT } from "./lib/package-root.js";
-import { mergeStagePolicyNotesForStages } from "./method-stage-policy.js";
 const LocalMethodStageDefinitionSchema = z.object({
     id: z.string().regex(InterfIdPattern),
     label: z.string().min(1),
@@ -32,14 +32,45 @@ const LocalMethodDefinitionSchema = z.object({
     stages: z.array(LocalMethodStageDefinitionSchema).min(1).optional(),
     stage_policy_notes: z.record(z.string(), z.array(z.string())).optional(),
 });
-function methodRootPath(sourcePath) {
-    return join(sourcePath, "interf", "methods");
+function normalizeStagePolicyNotes(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const normalized = {};
+    for (const [stageId, notes] of Object.entries(value)) {
+        if (!Array.isArray(notes))
+            continue;
+        const cleaned = Array.from(new Set(notes
+            .filter((note) => typeof note === "string")
+            .map((note) => note.trim())
+            .filter((note) => note.length > 0)));
+        if (cleaned.length > 0) {
+            normalized[stageId] = cleaned;
+        }
+    }
+    return Object.keys(normalized).length > 0 ? normalized : undefined;
 }
-function builtinMethodRootPath(methodId) {
+export function mergeStagePolicyNotesForStages(stages, baseNotes, overrideNotes) {
+    const normalizedBase = normalizeStagePolicyNotes(baseNotes);
+    const merged = {};
+    for (const stage of stages) {
+        const combined = Array.from(new Set([
+            ...(normalizedBase?.[stage.id] ?? []),
+            ...((overrideNotes?.[stage.id] ?? []).map((note) => note.trim()).filter((note) => note.length > 0)),
+        ]));
+        if (combined.length > 0) {
+            merged[stage.id] = combined;
+        }
+    }
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+function methodRootPath(prepDataDir) {
+    return preparationMethodsRoot(asPreparationDataDir(prepDataDir));
+}
+export function builtinMethodPackagePath(methodId) {
     return join(PACKAGE_ROOT, "builtin-methods", methodId);
 }
-export function methodDefinitionPath(sourcePath, id) {
-    return join(methodRootPath(sourcePath), id);
+export function methodDefinitionPath(prepDataDir, id) {
+    return join(methodRootPath(prepDataDir), id);
 }
 function isSupportedMethodStarterDocPath(relativePath) {
     if (relativePath === "README.md")
@@ -109,9 +140,9 @@ export function loadMethodDefinitionFromDir(dirPath) {
         methodSchemaPath: contextInterfaceFilePath(dirPath),
     };
 }
-export function listLocalMethodDefinitions(sourcePath) {
+export function listLocalMethodDefinitions(prepDataDir) {
     const definitions = new Map();
-    const root = methodRootPath(sourcePath);
+    const root = methodRootPath(prepDataDir);
     if (existsSync(root)) {
         for (const entryPath of readdirSync(root).map((entry) => join(root, entry))) {
             try {
@@ -128,25 +159,25 @@ export function listLocalMethodDefinitions(sourcePath) {
     }
     return [...definitions.values()].sort((a, b) => a.label.localeCompare(b.label));
 }
-export function loadLocalMethodDefinition(sourcePath, id) {
-    return loadMethodDefinitionFromDir(methodDefinitionPath(sourcePath, id));
+export function loadLocalMethodDefinition(prepDataDir, id) {
+    return loadMethodDefinitionFromDir(methodDefinitionPath(prepDataDir, id));
 }
-export function resolveMethodPackageSourcePath(sourcePath, methodId) {
-    const localPath = methodDefinitionPath(sourcePath, methodId);
+export function resolveMethodPackageSourcePath(prepDataDir, methodId) {
+    const localPath = methodDefinitionPath(prepDataDir, methodId);
     if (loadMethodDefinitionFromDir(localPath))
         return localPath;
-    const builtinPath = builtinMethodRootPath(methodId);
+    const builtinPath = builtinMethodPackagePath(methodId);
     if (loadMethodDefinitionFromDir(builtinPath))
         return builtinPath;
     return null;
 }
 export function seedLocalDefaultMethod(options) {
     const methodId = "interf-default";
-    const targetPath = methodDefinitionPath(options.sourcePath, methodId);
+    const targetPath = methodDefinitionPath(options.prepDataDir, methodId);
     if (existsSync(join(targetPath, "method.json"))) {
         return { methodId, targetPath, alreadyExisted: true };
     }
-    const builtinInterfPath = builtinMethodRootPath(methodId);
+    const builtinInterfPath = builtinMethodPackagePath(methodId);
     if (!existsSync(join(builtinInterfPath, "method.json"))) {
         throw new Error(`Built-in "${methodId}" Method package not found at ${builtinInterfPath}.`);
     }
@@ -169,7 +200,7 @@ function readMethodJsonObject(dirPath) {
     }
     return { ...raw };
 }
-export function patchMethodPackageMetadata(dirPath, options = {}) {
+export function patchMethodPackageMetadata(dirPath, options) {
     const methodPath = join(dirPath, "method.json");
     const methodJson = readMethodJsonObject(dirPath);
     const normalizedStages = Array.isArray(methodJson.stages) && methodJson.stages.length > 0
@@ -209,6 +240,11 @@ export function patchMethodPackageMetadata(dirPath, options = {}) {
         label: schemaLabel,
     });
 }
+function resolveStageSkillDir(stage) {
+    return typeof stage.skill_dir === "string" && stage.skill_dir.trim().length > 0
+        ? stage.skill_dir
+        : stage.id;
+}
 function collectMethodPackageStructureIssues(dirPath, stages) {
     const issues = [];
     const methodPath = join(dirPath, "method.json");
@@ -225,23 +261,7 @@ function collectMethodPackageStructureIssues(dirPath, stages) {
     if (!stages)
         return issues;
     for (const stage of stages) {
-        const skillDir = typeof stage.skill_dir === "string" && stage.skill_dir.trim().length > 0
-            ? stage.skill_dir
-            : stage.id;
-        if (!existsSync(join(dirPath, "compile", "stages", skillDir, "SKILL.md"))) {
-            issues.push(`missing compile/stages/${skillDir}/SKILL.md`);
-        }
-    }
-    return issues;
-}
-function collectMethodStageSkillIssues(dirPath, stages) {
-    if (!stages)
-        return [];
-    const issues = [];
-    for (const stage of stages) {
-        const skillDir = typeof stage.skill_dir === "string" && stage.skill_dir.trim().length > 0
-            ? stage.skill_dir
-            : stage.id;
+        const skillDir = resolveStageSkillDir(stage);
         if (!existsSync(join(dirPath, "compile", "stages", skillDir, "SKILL.md"))) {
             issues.push(`missing compile/stages/${skillDir}/SKILL.md`);
         }
@@ -271,9 +291,10 @@ export function describeMethodPackagePortability(dirPath) {
         issues.push("method.json must declare explicit stages for a portable Method package");
         return issues;
     }
+    // Structural issues already returned earlier; only stage-skill files can be missing now.
     return [
         ...issues,
-        ...collectMethodStageSkillIssues(dirPath, parsed.data.stages ?? null),
+        ...collectMethodPackageStructureIssues(dirPath, parsed.data.stages ?? null),
     ];
 }
 export function isPortableMethodPackage(dirPath) {
@@ -413,7 +434,7 @@ export function validateMethodPackage(dirPath) {
                 }
             }
         }
-        for (const requiredZone of listBuiltinCompiledZoneSpecs().filter((zone) => zone.id === "raw" || zone.id === "runtime")) {
+        for (const requiredZone of listBuiltinCompiledZoneSpecs().filter((zone) => zone.id === "runtime")) {
             const match = zoneById.get(requiredZone.id);
             if (!match) {
                 errors.push(`method.schema.json is missing required zone "${requiredZone.id}".`);
@@ -461,6 +482,3 @@ function describeContextInterfaceValidationIssues(dirPath) {
         return `method.schema.json ${path}: ${issue.message}`;
     });
 }
-function basename(filePath) {
-    return filePath.split(/[\\/]/).pop() ?? filePath;
-}

package/dist/packages/method-package/method-definitions.d.ts

@@ -1,3 +1,4 @@
+import { type LocalMethodDefinition } from "./local-methods.js";
 import type { RuntimeStageAcceptance, MethodCompilerApi } from "../compiler/lib/schema.js";
 import type { MethodId, RuntimeContractType } from "../contracts/lib/schema.js";
 import { type ContextInterface, type ContextInterfaceZoneId, type MethodInputSpec } from "./context-interface.js";
@@ -31,53 +32,26 @@ export interface MethodDefinition<TId extends string> {
     stages: MethodStageDefinition[];
     stagePolicyNotes?: Record<string, string[]>;
     starterDocs?: MethodStarterDoc[];
-    scope?: "builtin" | "local";
+    scope?: "builtin" | "user" | "local";
 }
 export type CompiledMethodId = string;
-export declare function standaloneMethodDefinitionFromLocalPackage(local: {
-    id: string;
-    compiler_api?: MethodCompilerApi;
-    purpose?: {
-        label: string;
-        task_hint: string;
-    };
-    inputs?: MethodInputSpec[];
-    label: string;
-    hint: string;
-    stages?: Array<{
-        id: string;
-        label: string;
-        description?: string;
-        contract_type: RuntimeContractType;
-        skill_dir?: string;
-        reads: ContextInterfaceZoneId[];
-        writes: ContextInterfaceZoneId[];
-        acceptance?: RuntimeStageAcceptance;
-    }>;
-    stage_policy_notes?: Record<string, string[]>;
-    method_schema?: ContextInterface;
-    starter_docs: MethodStarterDoc[];
-}): MethodDefinition<string>;
-export declare function listCompiledMethodChoices(sourcePath?: string): MethodDefinition<string>[];
+export declare function standaloneMethodDefinitionFromLocalPackage(local: LocalMethodDefinition): MethodDefinition<string>;
+export declare function listCompiledMethodChoices(prepDataDir?: string): MethodDefinition<string>[];
 export declare function getCompiledMethod(methodId: CompiledMethodId, options?: {
-    sourcePath?: string;
+    prepDataDir?: string;
 }): MethodDefinition<string>;
 export declare function getActiveCompiledMethod(compiledPath: string): MethodDefinition<string>;
 export declare function resolveCompiledMethodId(value: unknown): CompiledMethodId | null;
 export declare function resolveCompiledMethodFromConfig(config: unknown): CompiledMethodId | null;
 export declare function resolveRequiredCompiledMethodFromConfig(config: unknown, label?: string): CompiledMethodId;
-export declare function formatCompiledMethodStageStep(methodId: CompiledMethodId, stage: string, options?: {
-    sourcePath?: string;
-}): string;
-export declare function getMethodStageDefinition(methodId: MethodId, stage: string, sourcePath?: string): MethodStageDefinition | null;
-export declare function getMethodStagePosition(methodId: MethodId, stage: string, sourcePath?: string): {
+export declare function getMethodStageDefinition(methodId: MethodId, stage: string, prepDataDir?: string): MethodStageDefinition | null;
+export declare function getMethodStagePosition(methodId: MethodId, stage: string, prepDataDir?: string): {
     stageIndex: number;
     stageTotal: number;
     stages: string[];
 } | null;
-export declare function getMethodStages(methodId: MethodId, sourcePath?: string): string[];
+export declare function getMethodStages(methodId: MethodId, prepDataDir?: string): string[];
 export declare function getActiveCompiledStages(compiledPath: string): string[];
-export declare function getMethodStagePolicyNotes(methodId: MethodId, stage: string, sourcePath?: string): string[];
 export declare function getActiveCompiledStagePolicyNotes(compiledPath: string, stage: string): string[];
 export declare function resolveActiveCompiledStageAcceptance(compiledPath: string, stage: string): MethodStageDefinition["acceptance"] | undefined;
 export declare function formatActiveCompiledMethodStageStep(compiledPath: string, stage: string): string;

package/dist/packages/method-package/method-definitions.js

@@ -1,12 +1,12 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { isMethodId, listLocalMethodDefinitions, loadLocalMethodDefinition, loadMethodDefinitionFromDir, } from "./local-methods.js";
+import { builtinMethodPackagePath, isMethodId, listLocalMethodDefinitions, loadLocalMethodDefinition, loadMethodDefinitionFromDir, mergeStagePolicyNotesForStages, } from "./local-methods.js";
+import { listUserMethodDefinitions, loadUserMethodDefinition, } from "./user-methods.js";
 import { warnInterf } from "../shared/logger.js";
 import { methodPackagePathForCompiled } from "../compiler/compiled-paths.js";
+import { asPreparationDataDir, preparationMethodPackagePath } from "../contracts/lib/preparation-paths.js";
 import { resolveSourceControlPath } from "../project-model/interf.js";
-import { PACKAGE_ROOT } from "./lib/package-root.js";
 import { deriveMethodInputsFromContextInterface, } from "./context-interface.js";
-import { mergeStagePolicyNotesForStages } from "./method-stage-policy.js";
 const DEFAULT_METHOD_ID = "interf-default";
 let builtinDefaultMethodCache = null;
 function toMethodStages(stages) {
@@ -56,9 +56,6 @@ export function standaloneMethodDefinitionFromLocalPackage(local) {
         scope: "local",
     };
 }
-function builtinMethodPackagePath(methodId) {
-    return join(PACKAGE_ROOT, "builtin-methods", methodId);
-}
 function getBuiltinDefaultMethod() {
     if (builtinDefaultMethodCache)
         return builtinDefaultMethodCache;
@@ -78,24 +75,41 @@ function getBuiltinDefaultMethod() {
 function listBuiltinCompiledMethods() {
     return [getBuiltinDefaultMethod()];
 }
-function resolveCompiledMethodFromLocal(methodId, sourcePath) {
-    const local = loadLocalMethodDefinition(sourcePath, methodId);
+function resolveCompiledMethodFromLocal(methodId, prepDataDir) {
+    const local = loadLocalMethodDefinition(prepDataDir, methodId);
     if (!local)
         return null;
     const resolved = standaloneMethodDefinitionFromLocalPackage(local);
     return resolved;
 }
-export function listCompiledMethodChoices(sourcePath) {
+function resolveCompiledMethodFromUserLibrary(methodId) {
+    const user = loadUserMethodDefinition(methodId);
+    if (!user)
+        return null;
+    const resolved = standaloneMethodDefinitionFromLocalPackage(user);
+    return { ...resolved, scope: "user" };
+}
+export function listCompiledMethodChoices(prepDataDir) {
     const builtins = listBuiltinCompiledMethods();
-    if (!sourcePath)
-        return builtins;
     const methodsById = new Map();
     for (const method of builtins) {
         methodsById.set(method.id, method);
     }
-    for (const definition of listLocalMethodDefinitions(sourcePath)) {
+    for (const definition of listUserMethodDefinitions()) {
+        try {
+            const method = resolveCompiledMethodFromUserLibrary(definition.id);
+            if (method)
+                methodsById.set(method.id, method);
+        }
+        catch (error) {
+            warnInterf(`Warning: skipping user Method "${definition.id}" because it could not be resolved cleanly: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (!prepDataDir)
+        return [...methodsById.values()];
+    for (const definition of listLocalMethodDefinitions(prepDataDir)) {
         try {
-            const method = resolveCompiledMethodFromLocal(definition.id, sourcePath);
+            const method = resolveCompiledMethodFromLocal(definition.id, prepDataDir);
             if (method)
                 methodsById.set(method.id, method);
         }
@@ -106,16 +120,21 @@ export function listCompiledMethodChoices(sourcePath) {
     return [...methodsById.values()];
 }
 export function getCompiledMethod(methodId, options = {}) {
+    if (options.prepDataDir) {
+        const local = resolveCompiledMethodFromLocal(methodId, options.prepDataDir);
+        if (local)
+            return local;
+    }
+    const user = resolveCompiledMethodFromUserLibrary(methodId);
+    if (user)
+        return user;
     const builtin = listBuiltinCompiledMethods().find((candidate) => candidate.id === methodId);
     if (builtin)
         return builtin;
-    if (options.sourcePath) {
-        const local = resolveCompiledMethodFromLocal(methodId, options.sourcePath);
-        if (local)
-            return local;
-        throw new Error(`No local Method package found for "${methodId}" under ${join(options.sourcePath, "interf", "methods", methodId)}.`);
+    if (options.prepDataDir) {
+        throw new Error(`No Method "${methodId}" found in this workspace, in your user library, or among bundled Methods. Looked under ${preparationMethodPackagePath(asPreparationDataDir(options.prepDataDir), methodId)} and ~/.interf/methods/${methodId}.`);
     }
-    throw new Error(`Method "${methodId}" is not built-in. Provide a source path so Interf can resolve a local Method package.`);
+    throw new Error(`Method "${methodId}" is not built-in and no workspace root was provided to look for a local override.`);
 }
 export function getActiveCompiledMethod(compiledPath) {
     const methodPath = methodPackagePathForCompiled(compiledPath);
@@ -147,15 +166,12 @@ export function resolveRequiredCompiledMethodFromConfig(config, label = "compile
     }
     return methodId;
 }
-export function formatCompiledMethodStageStep(methodId, stage, options = {}) {
-    return formatMethodStageStep(getCompiledMethod(methodId, options), stage);
-}
-function resolveMethodDefinitionForStageMetadata(methodId, sourcePath) {
-    if (sourcePath &&
-        existsSync(join(methodPackagePathForCompiled(sourcePath), "method.json"))) {
-        return getActiveCompiledMethod(sourcePath);
+function resolveMethodDefinitionForStageMetadata(methodId, prepDataDir) {
+    if (prepDataDir &&
+        existsSync(join(methodPackagePathForCompiled(prepDataDir), "method.json"))) {
+        return getActiveCompiledMethod(prepDataDir);
     }
-    return getCompiledMethod(methodId, { sourcePath });
+    return getCompiledMethod(methodId, { prepDataDir });
 }
 function formatMethodStageStep(method, stage) {
     const stageIndex = method.stages.findIndex((candidate) => candidate.id === stage);
@@ -168,12 +184,12 @@ function formatMethodStageStep(method, stage) {
     }
     return `Stage ${stageIndex + 1}/${method.stages.length} - ${stageDefinition.label}`;
 }
-export function getMethodStageDefinition(methodId, stage, sourcePath) {
-    const method = resolveMethodDefinitionForStageMetadata(methodId, sourcePath);
+export function getMethodStageDefinition(methodId, stage, prepDataDir) {
+    const method = resolveMethodDefinitionForStageMetadata(methodId, prepDataDir);
     return method.stages.find((candidate) => candidate.id === stage) ?? null;
 }
-export function getMethodStagePosition(methodId, stage, sourcePath) {
-    const stages = getMethodStages(methodId, sourcePath);
+export function getMethodStagePosition(methodId, stage, prepDataDir) {
+    const stages = getMethodStages(methodId, prepDataDir);
     const stageIndex = stages.findIndex((candidate) => candidate === stage);
     if (stageIndex === -1)
         return null;
@@ -183,16 +199,12 @@ export function getMethodStagePosition(methodId, stage, sourcePath) {
         stages: [...stages],
     };
 }
-export function getMethodStages(methodId, sourcePath) {
-    return resolveMethodDefinitionForStageMetadata(methodId, sourcePath).stages.map((definition) => definition.id);
+export function getMethodStages(methodId, prepDataDir) {
+    return resolveMethodDefinitionForStageMetadata(methodId, prepDataDir).stages.map((definition) => definition.id);
 }
 export function getActiveCompiledStages(compiledPath) {
     return getActiveCompiledMethod(compiledPath).stages.map((definition) => definition.id);
 }
-export function getMethodStagePolicyNotes(methodId, stage, sourcePath) {
-    const method = resolveMethodDefinitionForStageMetadata(methodId, sourcePath);
-    return [...(method.stagePolicyNotes?.[stage] ?? [])];
-}
 export function getActiveCompiledStagePolicyNotes(compiledPath, stage) {
     const method = getActiveCompiledMethod(compiledPath);
     return [...(method.stagePolicyNotes?.[stage] ?? [])];

package/dist/packages/method-package/method-helpers.d.ts

@@ -9,8 +9,6 @@ export interface MethodStageResult {
     code: number;
     summary?: string | null;
 }
-export declare function methodQueryDirectory(): string;
-export declare function methodImproveDirectory(): string;
 export declare function methodCompileStageDirectory(stageDir: string): string;
 export interface LocalSkillContractExtension {
     reads: string[];
@@ -20,19 +18,9 @@ export interface LocalSkillContractExtension {
     effectiveMode: RuntimeInstructionMode;
     modeSources: string[];
 }
-export declare function emptyLocalSkillContractExtension(): LocalSkillContractExtension;
 export declare function buildLocalSkillContractExtension(rootPath: string, directories: string[], purpose: string): LocalSkillContractExtension;
-export declare function buildLocalSkillContractExtensionRelativeTo(rootPath: string, relativeToPath: string, directories: string[], purpose: string): LocalSkillContractExtension;
-export declare function mergeLocalSkillContractExtensions(extensions: LocalSkillContractExtension[]): LocalSkillContractExtension;
 export declare function buildStageInstructions(stageSkillDir: string, localSkills: LocalSkillContractExtension): RuntimeStageInstructions;
 export declare function reportLine(reporter: MethodReporter | undefined, message: string): void;
 export declare function reportBlankLine(reporter: MethodReporter | undefined): void;
 export declare function reportValidationFailure(reporter: MethodReporter | undefined, summary: string, errors?: string[]): void;
-export declare function resolveStageAcceptance(methodId: string, stageId: string, sourcePath?: string): MethodStageDefinition["acceptance"] | undefined;
-export declare function validateStageOutcome(_dirPath: string, validation: {
-    ok: boolean;
-    summary: string;
-}): {
-    ok: boolean;
-    summary: string;
-};
+export declare function resolveStageAcceptance(methodId: string, stageId: string, prepDataDir?: string): MethodStageDefinition["acceptance"] | undefined;

package/dist/packages/method-package/method-helpers.js

@@ -6,16 +6,10 @@ import { isMarkdownFile } from "../shared/file-types.js";
 import { getCompiledMethod, } from "./method-definitions.js";
 import { COMPILED_METHOD_DIR, methodPackagePathForCompiled } from "../compiler/compiled-paths.js";
 const LOCAL_SKILL_READ_LIMIT = 50;
-export function methodQueryDirectory() {
-    return `${COMPILED_METHOD_DIR}/use/query`;
-}
-export function methodImproveDirectory() {
-    return `${COMPILED_METHOD_DIR}/improve`;
-}
 export function methodCompileStageDirectory(stageDir) {
     return `${COMPILED_METHOD_DIR}/compile/stages/${stageDir}`;
 }
-export function emptyLocalSkillContractExtension() {
+function emptyLocalSkillContractExtension() {
     return {
         reads: [],
         count: 0,
@@ -36,14 +30,11 @@ function readLocalInstructionMode(filePath) {
     }
 }
 function collectLocalSkillDocs(rootPath, directories) {
-    return collectLocalSkillDocsRelativeTo(rootPath, rootPath, directories);
-}
-function collectLocalSkillDocsRelativeTo(rootPath, relativeToPath, directories) {
     const docs = new Map();
     const methodRoot = methodPackagePathForCompiled(rootPath);
     const rootReadme = join(methodRoot, "README.md");
     if (existsSync(rootReadme)) {
-        const read = projectMethodReadPath(rootPath, relativeToPath, rootReadme);
+        const read = projectMethodReadPath(rootPath, rootReadme);
         docs.set(read, {
             read,
             absolutePath: rootReadme,
@@ -53,7 +44,7 @@ function collectLocalSkillDocsRelativeTo(rootPath, relativeToPath, directories)
     for (const directory of directories) {
         const absoluteDirectory = resolveAuthoringDirectory(rootPath, directory);
         for (const filePath of listFilesRecursive(absoluteDirectory, isMarkdownFile)) {
-            const read = projectMethodReadPath(rootPath, relativeToPath, filePath);
+            const read = projectMethodReadPath(rootPath, filePath);
             docs.set(read, {
                 read,
                 absolutePath: filePath,
@@ -75,23 +66,19 @@ function resolveAuthoringDirectory(rootPath, directory) {
     }
     return join(rootPath, directory);
 }
-function projectMethodReadPath(rootPath, relativeToPath, absolutePath) {
+function projectMethodReadPath(rootPath, absolutePath) {
     const methodRoot = methodPackagePathForCompiled(rootPath);
     const normalizedMethodRoot = `${methodRoot}${sep}`;
     if (absolutePath === methodRoot || absolutePath.startsWith(normalizedMethodRoot)) {
         const relativeMethodPath = relative(methodRoot, absolutePath);
-        return relative(relativeToPath, join(rootPath, COMPILED_METHOD_DIR, relativeMethodPath));
+        return relative(rootPath, join(rootPath, COMPILED_METHOD_DIR, relativeMethodPath));
     }
-    return relative(relativeToPath, absolutePath);
+    return relative(rootPath, absolutePath);
 }
 export function buildLocalSkillContractExtension(rootPath, directories, purpose) {
     const docs = collectLocalSkillDocs(rootPath, directories);
     return buildContractExtensionFromDocs(docs, directories, purpose);
 }
-export function buildLocalSkillContractExtensionRelativeTo(rootPath, relativeToPath, directories, purpose) {
-    const docs = collectLocalSkillDocsRelativeTo(rootPath, relativeToPath, directories);
-    return buildContractExtensionFromDocs(docs, directories, purpose);
-}
 function buildContractExtensionFromDocs(docs, directories, purpose) {
     const reads = docs.map((doc) => doc.read);
     const modeSources = docs.filter((doc) => doc.mode !== null).map((doc) => doc.read);
@@ -120,24 +107,6 @@ function buildContractExtensionFromDocs(docs, directories, purpose) {
         modeSources,
     };
 }
-export function mergeLocalSkillContractExtensions(extensions) {
-    const reads = Array.from(new Set(extensions.flatMap((extension) => extension.reads)));
-    const notes = Array.from(new Set(extensions.flatMap((extension) => extension.notes)));
-    const modeSources = Array.from(new Set(extensions.flatMap((extension) => extension.modeSources)));
-    const localMode = extensions.some((extension) => extension.localMode === "override")
-        ? "override"
-        : extensions.some((extension) => extension.localMode === "extend")
-            ? "extend"
-            : null;
-    return {
-        reads,
-        count: reads.length,
-        notes,
-        localMode,
-        effectiveMode: localMode ?? "builtin",
-        modeSources,
-    };
-}
 export function buildStageInstructions(stageSkillDir, localSkills) {
     return {
         stage_skill_dir: stageSkillDir,
@@ -159,9 +128,6 @@ export function reportValidationFailure(reporter, summary, errors = []) {
         reportLine(reporter, `- ${error}`);
     }
 }
-export function resolveStageAcceptance(methodId, stageId, sourcePath) {
-    return getCompiledMethod(methodId, { sourcePath }).stages.find((stage) => stage.id === stageId)?.acceptance;
-}
-export function validateStageOutcome(_dirPath, validation) {
-    return validation;
+export function resolveStageAcceptance(methodId, stageId, prepDataDir) {
+    return getCompiledMethod(methodId, { prepDataDir }).stages.find((stage) => stage.id === stageId)?.acceptance;
 }

package/dist/packages/method-package/method-review-paths.d.ts

@@ -1,7 +1,7 @@
 import type { MethodImprovementContext } from "../compiler/lib/schema.js";
 export interface MethodImprovementReviewSourcePaths {
     compiledRuntime: string | null;
-    testComparisons: string | null;
+    readinessRuns: string | null;
     executionShells: string | null;
     targetTestRuns: string | null;
     targetTestSandboxes: string | null;

package/dist/packages/method-package/method-review-paths.js

@@ -3,15 +3,15 @@ import { join } from "node:path";
 import { testRootForCompiled, targetTestRunsRootForCompiled, targetTestSandboxesRootForCompiled, stageExecutionShellsRoot, compiledRuntimeRoot, } from "../compiler/compiled-paths.js";
 export function resolveMethodImprovementReviewSourcePaths(compiledPath) {
     const compiledRuntime = compiledRuntimeRoot(compiledPath);
-    const testComparisons = testRootForCompiled(compiledPath);
+    const readinessRuns = testRootForCompiled(compiledPath);
     const executionShells = stageExecutionShellsRoot(compiledPath);
     const targetTestRuns = targetTestRunsRootForCompiled(compiledPath);
     const targetTestSandboxes = targetTestSandboxesRootForCompiled(compiledPath);
     return {
         compiledRuntime: existsSync(compiledRuntime) ? compiledRuntime : null,
-        testComparisons: existsSync(join(testComparisons, "latest.json")) ||
-            existsSync(join(testComparisons, "latest.md"))
-            ? testComparisons
+        readinessRuns: existsSync(join(readinessRuns, "latest.json")) ||
+            existsSync(join(readinessRuns, "latest.md"))
+            ? readinessRuns
             : null,
         executionShells: existsSync(executionShells) ? executionShells : null,
         targetTestRuns: existsSync(targetTestRuns) ? targetTestRuns : null,
@@ -23,7 +23,7 @@ export function resolveMethodImprovementReviewPaths(compiledPath) {
     return {
         method_root: "method",
         compiled_runtime: sources.compiledRuntime ? "artifacts/compiled-runtime" : null,
-        test_comparisons: sources.testComparisons ? "artifacts/test-comparisons" : null,
+        readiness_runs: sources.readinessRuns ? "artifacts/readiness-runs" : null,
         execution_shells: sources.executionShells ? "artifacts/execution-shells" : null,
         test_runs: sources.targetTestRuns ? "artifacts/test-runs" : null,
         test_sandboxes: sources.targetTestSandboxes ? "artifacts/test-sandboxes" : null,

package/dist/packages/method-package/method-stage-runner.js

@@ -1,5 +1,5 @@
 import { markRuntimeRunSucceededAfterValidation, buildStagePrompt, markRuntimeRunFailedAfterValidation, runExecutorStage, runExecutorSummarizeStage, } from "../compiler/runtime.js";
-import { reportValidationFailure, validateStageOutcome, } from "./method-helpers.js";
+import { reportValidationFailure, } from "./method-helpers.js";
 export function findStageByContractType(stages, contractType) {
     const stage = stages.find((candidate) => candidate.contractType === contractType);
     if (!stage) {
@@ -66,7 +66,7 @@ function finalizeValidatedStage(options, code) {
         options.syncWrites?.();
         options.reconcile?.();
         options.refreshArtifacts?.();
-        return validateStageOutcome(options.compiledPath, options.validate());
+        return options.validate();
     };
     if (code !== 0) {
         let completionSatisfied = false;

package/dist/packages/method-package/user-methods.d.ts

@@ -0,0 +1,17 @@
+import { type LocalMethodDefinition } from "./local-methods.js";
+export declare function userMethodPath(id: string): string;
+export declare function userMethodExists(id: string): boolean;
+export declare function listUserMethodDefinitions(): LocalMethodDefinition[];
+export declare function loadUserMethodDefinition(id: string): LocalMethodDefinition | null;
+export interface InstallUserMethodOptions {
+    sourceDir: string;
+    id?: string;
+    overwrite?: boolean;
+}
+export interface InstallUserMethodResult {
+    id: string;
+    path: string;
+    overwritten: boolean;
+}
+export declare function installUserMethod(options: InstallUserMethodOptions): InstallUserMethodResult;
+export declare function removeUserMethod(id: string): boolean;