@interf/compiler 0.9.5 → 0.16.0

package/dist/packages/{method-package → methods/package}/context-interface.js

@@ -1,18 +1,15 @@
 import { existsSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
-import { warnInterf } from "../shared/logger.js";
-import { readJsonFileUnchecked } from "../shared/parse.js";
-import { MethodCompiledSchemaSchema, MethodCompiledZoneSchema, MethodZoneIdSchema, MethodZoneRoleSchema, } from "../compiler/lib/schema.js";
+import { warnInterf } from "../../contracts/utils/logger.js";
+import { readJsonFileUnchecked } from "../../contracts/utils/parse.js";
+import { MethodCompiledSchemaSchema, MethodZoneIdSchema, } from "../../engine/compile/lib/schema.js";
 import { listBuiltinCompiledZoneSpecs, requiredCompiledZoneOwners, } from "./builtin-compiled-method.js";
 // Method packages define the context interface. The compiler persists the
 // same schema on disk, but higher layers should prefer this boundary when they
 // mean "the Method-declared shape a portable context must implement."
 export const CONTEXT_INTERFACE_FILE = "method.schema.json";
 export const ContextInterfaceSchema = MethodCompiledSchemaSchema;
-export const ContextInterfaceZoneSchema = MethodCompiledZoneSchema;
-export const ContextInterfaceZoneIdSchema = MethodZoneIdSchema;
-export const ContextInterfaceZoneRoleSchema = MethodZoneRoleSchema;
 // Package-owned input contract for authoring, review, and future authoring flows.
 // This does not change compiler execution semantics; it describes what data a
 // Method expects to organize before the compiler materializes the context
@@ -24,7 +21,6 @@ export const MethodInputSpecSchema = z.object({
     required: z.boolean().default(false),
     examples: z.array(z.string().min(1)).optional(),
 }).strict();
-export const MethodInputContractSchema = z.array(MethodInputSpecSchema);
 function normalizeContextInterface(contextInterface) {
     return {
         ...contextInterface,
@@ -53,15 +49,6 @@ export function resolveContextInterfacePath(rootPath) {
 export function contextInterfaceExists(rootPath) {
     return existsSync(contextInterfaceFilePath(rootPath));
 }
-export function contextInterfaceRelativePath() {
-    return `method/${CONTEXT_INTERFACE_FILE}`;
-}
-export function listContextInterfaceZones(contextInterface) {
-    return [...contextInterface.zones];
-}
-export function findContextInterfaceZone(contextInterface, zoneId) {
-    return contextInterface.zones.find((zone) => zone.id === zoneId) ?? null;
-}
 export function contextInterfaceZoneAbsolutePath(compiledPath, zone) {
     return join(compiledPath, zone.path);
 }
@@ -70,15 +57,6 @@ export function contextInterfaceArtifactPath(zone) {
         return zone.path;
     return zone.path.endsWith("/") ? zone.path : `${zone.path}/`;
 }
-export function contextInterfaceArtifactPathsForZoneIds(contextInterface, zoneIds) {
-    return zoneIds.map((zoneId) => {
-        const zone = findContextInterfaceZone(contextInterface, zoneId);
-        if (!zone) {
-            throw new Error(`Context interface is missing declared zone "${zoneId}".`);
-        }
-        return contextInterfaceArtifactPath(zone);
-    });
-}
 export function summarizeContextInterface(contextInterface) {
     return {
         inputZones: contextInterface.zones.filter((zone) => zone.role === "input"),

package/dist/packages/{method-package → methods/package}/interf-method-package.d.ts

@@ -5,11 +5,11 @@ export declare function writeMethodPackageToDir(methodDir: string, method: Metho
 }): void;
 export declare function seedCompiledMethodPackage(options: {
     compiledPath: string;
-    sourcePath: string;
+    prepDataDir: string;
     methodId: string;
 }): void;
 export declare function createLocalMethodPackageFromTemplate(options: {
-    sourcePath: string;
+    prepDataDir: string;
     baseMethodId: string;
     methodId: string;
     label: string;
@@ -17,14 +17,14 @@ export declare function createLocalMethodPackageFromTemplate(options: {
     stagePolicyNotes: Record<string, string[]>;
 }): string;
 export declare function seedLocalMethodPackageFromBase(options: {
-    sourcePath: string;
+    prepDataDir: string;
     baseMethodId: string;
     methodId: string;
     label: string;
     hint: string;
 }): string;
 export declare function createScratchLocalMethodPackage(options: {
-    sourcePath: string;
+    prepDataDir: string;
     methodId: string;
     label: string;
     hint: string;

package/dist/packages/{method-package → methods/package}/interf-method-package.js

@@ -1,14 +1,10 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { renderCompiledQuerySkill } from "../agents/lib/shells.js";
-import { copyMethodPackageDirectory, isPortableMethodPackage, patchMethodPackageMetadata, resolveMethodPackageSourcePath, methodDefinitionPath, } from "./local-methods.js";
+import { renderCompiledQuerySkill } from "../../engine/agents/lib/shells.js";
+import { copyMethodPackageDirectory, isPortableMethodPackage, patchMethodPackageMetadata, resolveMethodPackageSourcePath, methodDefinitionPath, mergeStagePolicyNotesForStages, } from "./local-methods.js";
 import { getCompiledMethod, } from "./method-definitions.js";
 import { CONTEXT_INTERFACE_FILE, deriveMethodInputsFromContextInterface, summarizeContextInterface, writeContextInterface, writeContextInterfaceFile, } from "./context-interface.js";
-import { methodPackagePathForCompiled } from "../compiler/compiled-paths.js";
-import { mergeStagePolicyNotesForStages } from "./method-stage-policy.js";
-function methodPackagePath(dirPath) {
-    return methodPackagePathForCompiled(dirPath);
-}
+import { methodPackagePathForCompiled } from "../../engine/compile/compiled-paths.js";
 function writeMethodStarterDocs(dirPath, docs, options) {
     for (const doc of docs ?? []) {
         const targetPath = join(dirPath, doc.relativePath);
@@ -200,7 +196,7 @@ function renderImproveSkill(method) {
         `4. Keep purpose, inputs, \`method.json\`, \`${CONTEXT_INTERFACE_FILE}\`, and any changed stage docs aligned.`,
         "",
         "Guardrails:",
-        "- do not edit checks, test specs, or raw files",
+        "- do not edit checks, test specs, or source artifacts",
         "- do not hardcode expected answers into Method docs",
         "- keep this package standalone; do not rely on runtime inheritance",
         "- keep the Method stack coherent: purpose, inputs, context interface, and stages should describe the same job",
@@ -259,7 +255,7 @@ function renderStageSkill(method, stage) {
     ].join("\n");
 }
 export function writeCompiledMethodPackage(compiledPath, method) {
-    writeMethodPackageToDir(methodPackagePath(compiledPath), method);
+    writeMethodPackageToDir(methodPackagePathForCompiled(compiledPath), method);
 }
 export function writeMethodPackageToDir(methodDir, method, options = {}) {
     const overwrite = options.overwrite ?? true;
@@ -301,23 +297,24 @@ export function writeMethodPackageToDir(methodDir, method, options = {}) {
 }
 export function seedCompiledMethodPackage(options) {
     const resolvedMethod = getCompiledMethod(options.methodId, {
-        sourcePath: options.sourcePath,
+        prepDataDir: options.prepDataDir,
     });
-    const sourceMethodPath = resolveMethodPackageSourcePath(options.sourcePath, resolvedMethod.id);
+    const sourceMethodPath = resolveMethodPackageSourcePath(options.prepDataDir, resolvedMethod.id);
     if (sourceMethodPath && isPortableMethodPackage(sourceMethodPath)) {
         // Portable seed packages can be copied directly because compile runs the
         // local package folder without reading source-root Method packages.
-        copyMethodPackageDirectory(sourceMethodPath, methodPackagePath(options.compiledPath));
-        patchMethodPackageMetadata(methodPackagePath(options.compiledPath), {
+        copyMethodPackageDirectory(sourceMethodPath, methodPackagePathForCompiled(options.compiledPath));
+        patchMethodPackageMetadata(methodPackagePathForCompiled(options.compiledPath), {
             id: resolvedMethod.id,
             inputs: resolvedMethod.inputs,
             label: resolvedMethod.label,
             hint: resolvedMethod.hint,
             stagePolicyNotes: resolvedMethod.stagePolicyNotes,
         });
-        if (resolvedMethod.scope === "builtin") {
-            writeFileSync(join(methodPackagePath(options.compiledPath), "README.md"), renderMethodReadme(resolvedMethod));
-        }
+        // The portable-context README is always derived from the resolved Method;
+        // any hand-authored README belongs in the workspace draft at
+        // <workspace>/methods/<id>/, not in the compiled copy.
+        writeFileSync(join(methodPackagePathForCompiled(options.compiledPath), "README.md"), renderMethodReadme(resolvedMethod));
         return;
     }
     // Legacy or partially-defined seed packages are resolved once and
@@ -326,14 +323,14 @@ export function seedCompiledMethodPackage(options) {
 }
 export function createLocalMethodPackageFromTemplate(options) {
     const targetPath = seedLocalMethodPackageFromBase({
-        sourcePath: options.sourcePath,
+        prepDataDir: options.prepDataDir,
         baseMethodId: options.baseMethodId,
         methodId: options.methodId,
         label: options.label,
         hint: options.hint,
     });
     const baseMethod = getCompiledMethod(options.baseMethodId, {
-        sourcePath: options.sourcePath,
+        prepDataDir: options.prepDataDir,
     });
     const stagePolicyNotes = mergeStagePolicyNotesForStages(baseMethod.stages, baseMethod.stagePolicyNotes, options.stagePolicyNotes);
     patchMethodPackageMetadata(targetPath, {
@@ -358,10 +355,10 @@ export function createLocalMethodPackageFromTemplate(options) {
 }
 export function seedLocalMethodPackageFromBase(options) {
     const baseMethod = getCompiledMethod(options.baseMethodId, {
-        sourcePath: options.sourcePath,
+        prepDataDir: options.prepDataDir,
     });
-    const sourceMethodPath = resolveMethodPackageSourcePath(options.sourcePath, options.baseMethodId);
-    const targetPath = methodDefinitionPath(options.sourcePath, options.methodId);
+    const sourceMethodPath = resolveMethodPackageSourcePath(options.prepDataDir, options.baseMethodId);
+    const targetPath = methodDefinitionPath(options.prepDataDir, options.methodId);
     if (sourceMethodPath && isPortableMethodPackage(sourceMethodPath)) {
         // Copy directly when the base package is already portable and standalone.
         copyMethodPackageDirectory(sourceMethodPath, targetPath);
@@ -403,7 +400,7 @@ export function seedLocalMethodPackageFromBase(options) {
     return targetPath;
 }
 export function createScratchLocalMethodPackage(options) {
-    const targetPath = methodDefinitionPath(options.sourcePath, options.methodId);
+    const targetPath = methodDefinitionPath(options.prepDataDir, options.methodId);
     const method = {
         id: options.methodId,
         compilerApi: {
@@ -416,9 +413,9 @@ export function createScratchLocalMethodPackage(options) {
         },
         inputs: [
             {
-                id: "raw",
-                label: "Raw",
-                description: "Source-folder raw snapshot copied into the Preparation for direct evidence and verification.",
+                id: "source",
+                label: "Source",
+                description: "Source references assigned to each stage by Interf runtime.",
                 required: true,
             },
         ],
@@ -432,15 +429,6 @@ export function createScratchLocalMethodPackage(options) {
             target_type: "compiled",
             label: `${options.label} Method schema`,
             zones: [
-                {
-                    id: "raw",
-                    role: "input",
-                    path: "raw",
-                    kind: "directory",
-                    required: true,
-                    owned_by: [],
-                    description: "Source-folder raw snapshot copied into the Preparation for direct evidence and verification.",
-                },
                 {
                     id: "draft-context",
                     role: "output",
@@ -468,7 +456,8 @@ export function createScratchLocalMethodPackage(options) {
                 description: "Neutral placeholder stage for Method authoring. Replace this stage with the topology this agent work needs.",
                 contractType: "method-draft-stage",
                 skillDir: "prepare",
-                reads: ["raw", "runtime"],
+                role: "general",
+                reads: ["runtime"],
                 writes: ["draft-context"],
                 acceptance: {
                     stage_truthy: ["finished_at"],

package/dist/packages/{method-package → methods/package}/lib/package-root.js

@@ -2,5 +2,5 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-// Package root (dist/packages/method-package/lib/ -> package root)
-export const PACKAGE_ROOT = join(__dirname, "..", "..", "..", "..");
+// Package root (dist/packages/methods/package/lib/ -> package root)
+export const PACKAGE_ROOT = join(__dirname, "..", "..", "..", "..", "..");

package/dist/packages/{method-package → methods/package}/local-methods.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
-import { MethodCompilerApiSchema, RuntimeStageAcceptanceSchema, MethodPurposeSchema, MethodStageZoneAccessSchema } from "../compiler/lib/schema.js";
-import { RuntimeContractTypeSchema } from "../contracts/lib/schema.js";
+import { MethodCompilerApiSchema, RuntimeStageAcceptanceSchema, MethodPurposeSchema, MethodStageZoneAccessSchema } from "../../engine/compile/lib/schema.js";
+import { RuntimeContractTypeSchema } from "../../contracts/lib/schema.js";
 import { MethodInputSpecSchema, type ContextInterface, type MethodInputSpec } from "./context-interface.js";
 export interface LocalMethodStarterDoc {
     relativePath: string;
@@ -12,6 +12,12 @@ export interface LocalMethodStageDefinition {
     contract_type: z.infer<typeof RuntimeContractTypeSchema>;
     skill_dir?: string;
     description?: string;
+    /**
+     * Optional role hint. Open-ended string; defaults to `general` at the
+     * runtime layer when missing. Maps to a connected agent via the user's
+     * role-map (`~/.interf/agents.json`).
+     */
+    role?: string;
     reads: z.infer<typeof MethodStageZoneAccessSchema>;
     writes: z.infer<typeof MethodStageZoneAccessSchema>;
     acceptance?: z.infer<typeof RuntimeStageAcceptanceSchema>;
@@ -32,20 +38,24 @@ export interface LocalMethodDefinition {
     methodPath: string;
     methodSchemaPath: string;
 }
-export declare function methodDefinitionPath(sourcePath: string, id: string): string;
+export declare function mergeStagePolicyNotesForStages(stages: readonly {
+    id: string;
+}[], baseNotes: unknown, overrideNotes: Record<string, string[]> | undefined): Record<string, string[]> | undefined;
+export declare function builtinMethodPackagePath(methodId: string): string;
+export declare function methodDefinitionPath(prepDataDir: string, id: string): string;
 export declare function loadMethodDefinitionFromDir(dirPath: string): LocalMethodDefinition | null;
-export declare function listLocalMethodDefinitions(sourcePath: string): LocalMethodDefinition[];
-export declare function loadLocalMethodDefinition(sourcePath: string, id: string): LocalMethodDefinition | null;
-export declare function resolveMethodPackageSourcePath(sourcePath: string, methodId: string): string | null;
+export declare function listLocalMethodDefinitions(prepDataDir: string): LocalMethodDefinition[];
+export declare function loadLocalMethodDefinition(prepDataDir: string, id: string): LocalMethodDefinition | null;
+export declare function resolveMethodPackageSourcePath(prepDataDir: string, methodId: string): string | null;
 export declare function seedLocalDefaultMethod(options: {
-    sourcePath: string;
+    prepDataDir: string;
 }): {
     methodId: string;
     targetPath: string;
     alreadyExisted: boolean;
 };
 export declare function isMethodId(value: string): boolean;
-export declare function patchMethodPackageMetadata(dirPath: string, options?: {
+export declare function patchMethodPackageMetadata(dirPath: string, options: {
     id?: string;
     inputs?: MethodInputSpec[];
     label?: string;

package/dist/packages/{method-package → methods/package}/local-methods.js

@@ -1,22 +1,23 @@
 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";
-import { readJsonFileUnchecked, readJsonFileWithSchema } from "../shared/parse.js";
-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 { listFilesRecursive } from "../../contracts/utils/filesystem.js";
+import { warnInterf } from "../../contracts/utils/logger.js";
+import { readJsonFileUnchecked, readJsonFileWithSchema } from "../../contracts/utils/parse.js";
+import { isMarkdownFile } from "../../contracts/utils/file-types.js";
+import { MethodCompilerApiSchema, RuntimeStageAcceptanceSchema, MethodPurposeSchema, MethodStageZoneAccessSchema, } from "../../engine/compile/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),
     contract_type: RuntimeContractTypeSchema,
     skill_dir: z.string().regex(InterfIdPattern).optional(),
     description: z.string().min(1).optional(),
+    role: z.string().min(1).optional(),
     reads: MethodStageZoneAccessSchema,
     writes: MethodStageZoneAccessSchema,
     acceptance: RuntimeStageAcceptanceSchema.optional(),
@@ -32,14 +33,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 +141,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 +160,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 +201,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 +241,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 +262,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 +292,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 +435,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 +483,3 @@ function describeContextInterfaceValidationIssues(dirPath) {
         return `method.schema.json ${path}: ${issue.message}`;
     });
 }
-function basename(filePath) {
-    return filePath.split(/[\\/]/).pop() ?? filePath;
-}

package/dist/packages/{method-package → methods/package}/method-definitions.d.ts

@@ -1,5 +1,6 @@
-import type { RuntimeStageAcceptance, MethodCompilerApi } from "../compiler/lib/schema.js";
-import type { MethodId, RuntimeContractType } from "../contracts/lib/schema.js";
+import { type LocalMethodDefinition } from "./local-methods.js";
+import type { RuntimeStageAcceptance, MethodCompilerApi } from "../../engine/compile/lib/schema.js";
+import type { MethodId, RuntimeContractType } from "../../contracts/lib/schema.js";
 import { type ContextInterface, type ContextInterfaceZoneId, type MethodInputSpec } from "./context-interface.js";
 export interface MethodStarterDoc {
     relativePath: string;
@@ -11,6 +12,12 @@ export interface MethodStageDefinition {
     description: string;
     contractType: RuntimeContractType;
     skillDir: string;
+    /**
+     * Role hint declared by the Method package. Defaults to `general` when
+     * absent; mapped to a connected agent via the user's role-map at run
+     * time.
+     */
+    role: string;
     reads: ContextInterfaceZoneId[];
     writes: ContextInterfaceZoneId[];
     acceptance?: RuntimeStageAcceptance;
@@ -31,53 +38,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;