@interf/compiler 0.18.0 → 0.22.0

package/dist/packages/{methods/authoring/method-authoring.js → build-plans/authoring/build-plan-authoring.js}

@@ -1,24 +1,24 @@
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { createMethodAuthoringShell, } from "../../engine/agents/lib/shells.js";
-import { createScratchLocalMethodPackage } from "../package/interf-method-package.js";
+import { createBuildPlanAuthoringShell, } from "../../engine/agents/lib/shells.js";
+import { createScratchLocalBuildPlanPackage } from "../package/interf-build-plan-package.js";
 import { CONTEXT_INTERFACE_FILE, listContextInterfaceArtifacts } from "../package/context-interface.js";
-import { loadMethodDefinitionFromDir, validateMethodPackage, methodDefinitionPath, } from "../package/local-methods.js";
-import { runMethodEditSession } from "./method-edit-session.js";
+import { loadBuildPlanDefinitionFromDir, validateBuildPlanPackage, buildPlanDefinitionPath, } from "../package/local-build-plans.js";
+import { runBuildPlanEditSession } from "./build-plan-edit-session.js";
 /**
- * Walk method.json after a successful authoring run and fill in
+ * Walk build-plan.json after a successful authoring run and fill in
  * `role: "general"` for any stage missing a role field. Custom role
  * names are kept as-is. Idempotent — does nothing when every stage
  * already declares a role. Returns the list of stage ids that were
  * touched so the runtime can surface that to the user.
  */
-export function ensureStageRoles(methodPath) {
-    const methodJsonPath = join(methodPath, "method.json");
-    if (!existsSync(methodJsonPath))
+export function ensureStageRoles(buildPlanPath) {
+    const buildPlanJsonPath = join(buildPlanPath, "build-plan.json");
+    if (!existsSync(buildPlanJsonPath))
         return [];
     let raw;
     try {
-        raw = readFileSync(methodJsonPath, "utf8");
+        raw = readFileSync(buildPlanJsonPath, "utf8");
     }
     catch {
         return [];
@@ -54,44 +54,44 @@ export function ensureStageRoles(methodPath) {
     if (!changed)
         return [];
     value.stages = nextStages;
-    writeFileSync(methodJsonPath, `${JSON.stringify(value, null, 2)}\n`);
+    writeFileSync(buildPlanJsonPath, `${JSON.stringify(value, null, 2)}\n`);
     return touched;
 }
-function buildMethodAuthoringPrompt() {
+function buildBuildPlanAuthoringPrompt() {
     return [
-        "This is an automated Interf Method-authoring run, not an open-ended chat session.",
+        "This is an automated Interf Build Plan authoring run, not an open-ended chat session.",
         "Execute it now.",
-        "Create one standalone Method package for the source data, desired portable-context outputs, and proof requirements in this source folder.",
+        "Create one standalone Build Plan package for the source data, desired verifiable-context outputs, and proof requirements in this source folder.",
         "Read `runtime/authoring-context.json` first.",
         "Treat `task_prompt` as the user's preparation-and-evidence brief: source data, output shape, and evidence that should show the data is ready.",
-        `Then read \`method/README.md\`, \`method/method.json\`, and \`method/${CONTEXT_INTERFACE_FILE}\`.`,
-        "The `method/` directory starts as a neutral Method package scaffold, not as a suggested Method.",
-        "Replace the scaffold purpose, inputs, Artifacts, stages, stage docs, checks, and query guidance with the Method this agent work actually needs.",
+        `Then read \`build-plan/README.md\`, \`build-plan/build-plan.json\`, and \`build-plan/${CONTEXT_INTERFACE_FILE}\`.`,
+        "The `build-plan/` directory starts as a neutral Build Plan scaffold, not as a suggested final plan.",
+        "Replace the scaffold purpose, inputs, Artifacts, stages, stage docs, checks, and query guidance with the Build Plan this agent work actually needs.",
         "Read `runtime/source-files.json` and inspect the listed source locators before editing the package.",
         "Prefer direct file-reading and search tools over shell commands for routine file inspection.",
         "Do not use shell helpers like `cat`, `sed`, `ls`, or `find` when a native read/search tool can inspect the same files.",
-        "Edit only files under `method/`.",
-        "Keep the Method package valid for the current compiler API and `method.schema.json`.",
+        "Edit only files under `build-plan/`.",
+        "Keep the Build Plan valid for the current local-engine API and `build-plan.schema.json`.",
         "Choose stage ids, stage order, artifact reads, artifact writes, artifact checks, and stage docs from the source data and preparation-and-evidence brief.",
         "Use kebab-case ids everywhere: stage ids, skill_dir values, Artifact ids, reads/writes values, and package ids. Never use underscores.",
         "Each stage MAY declare a `role`: one of `extractor`, `summarizer`, `structurer`, `verifier`, or `general`. Pick the role that best matches what the stage's prompt asks the agent to do. Omit `role` (or use `general`) when the stage doesn't fit any specialized role. Custom role names are allowed; the engine treats unknown roles as `general`.",
-        "Do not preserve the placeholder `prepare` stage unless the final Method genuinely needs a stage with that exact role.",
+        "Do not preserve the placeholder `prepare` stage unless the final Build Plan genuinely needs a stage with that exact role.",
         "Put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks.",
         "Use only the CheckKind values listed in `runtime/authoring-context.json`; do not invent aliases.",
-        "Keep Artifact checks and the producing stage docs aligned: every checked output requirement must be described in the stage doc that writes that Artifact.",
-        "For every stage in `method.json`, create `method/compile/stages/<skill_dir>/SKILL.md` and make the folder name exactly match that stage's kebab-case `skill_dir`.",
-        "Every Artifact path in `method.schema.json` must be unique and non-overlapping.",
+        "Keep Artifact checks aligned with produced outputs. Use stage docs to describe the output contract, but do not turn source-specific user wording into brittle stage-doc wording requirements.",
+        "For every stage in `build-plan.json`, create `build-plan/build/stages/<skill_dir>/SKILL.md` and make the folder name exactly match that stage's kebab-case `skill_dir`.",
+        "Every Artifact path in `build-plan.schema.json` must be unique and non-overlapping.",
         "Make the package materially specific to this Preparation task, output shape, and proof requirement. A no-op scaffold is not acceptable.",
-        "Treat the Method package as four aligned layers: purpose, inputs, context interface, and stages.",
-        "If the Method writes an agent entrypoint, declare it as an Artifact and make the final shaping stage own it.",
+        "Treat the Build Plan as four aligned layers: purpose, inputs, context interface, and stages.",
+        "If the Build Plan writes an agent entrypoint, declare it as an Artifact and make the final shaping stage own it.",
         "Prefer explicit stage-doc, stage-policy, purpose, input-contract, and context-interface edits over vague rewrites.",
-        "Do not introduce wikilinks unless the Method also creates the target note by exact basename or explicit relative path.",
+        "Do not introduce wikilinks unless the Build Plan also creates the target note by exact basename or explicit relative path.",
         "Respect stage boundaries: a stage may only introduce links that resolve within that stage's declared writes or already-existing read Artifacts.",
         "Do not make one stage point at files or notes that are only created later by another stage.",
         "Prefer conservative retrieval routing over speculative note sprawl.",
         "Do not narrate plans or ask follow-up questions.",
         "Only emit user-visible updates that begin with STATUS:, DONE:, BLOCKED:, or ERROR:.",
-        "As soon as the Method edits are complete, stop.",
+        "As soon as the Build Plan edits are complete, stop.",
     ].join("\n");
 }
 function stableJson(value) {
@@ -116,40 +116,8 @@ function checkMatchesRequirement(actual, required) {
 function producingStagesForArtifact(definition, artifactId) {
     return (definition.stages ?? []).filter((stage) => Array.isArray(stage.writes) && stage.writes.includes(artifactId));
 }
-function readProducingStageDocs(methodPath, stages) {
-    return stages
-        .map((stage) => join(methodPath, "compile", "stages", stage.skill_dir ?? stage.id, "SKILL.md"))
-        .filter((filePath) => existsSync(filePath))
-        .map((filePath) => readFileSync(filePath, "utf8"))
-        .join("\n");
-}
-function validateMustContainStageDocs(methodPath, definition) {
-    const artifacts = definition.method_schema.artifacts ?? [];
-    const errors = [];
-    for (const artifact of artifacts) {
-        const producingStages = producingStagesForArtifact(definition, artifact.id);
-        if (producingStages.length === 0)
-            continue;
-        const producingStageDocs = readProducingStageDocs(methodPath, producingStages);
-        for (const check of artifact.checks ?? []) {
-            if (check.kind !== "must_contain")
-                continue;
-            const phrases = check.params?.phrases;
-            if (!Array.isArray(phrases))
-                continue;
-            for (const phrase of phrases) {
-                if (typeof phrase !== "string")
-                    continue;
-                if (!producingStageDocs.includes(phrase)) {
-                    errors.push(`Artifact \`${artifact.id}\` check \`${check.id}\` requires phrase not present in producing stage docs.`);
-                }
-            }
-        }
-    }
-    return errors;
-}
-function validateArtifactRequirements(methodPath, definition, requirements) {
-    const artifacts = definition.method_schema.artifacts ?? [];
+function validateArtifactRequirements(definition, requirements) {
+    const artifacts = definition.build_plan_schema.artifacts ?? [];
     const errors = [];
     for (const requirement of requirements) {
         const artifact = artifacts.find((candidate) => candidate.id === requirement.id);
@@ -174,74 +142,75 @@ function validateArtifactRequirements(methodPath, definition, requirements) {
     }
     return errors;
 }
-function validateAuthoredMethodPackage(methodPath, artifactRequirements = []) {
-    const validation = validateMethodPackage(methodPath);
+function validateAuthoredBuildPlanPackage(buildPlanPath, artifactRequirements = []) {
+    const validation = validateBuildPlanPackage(buildPlanPath);
     if (!validation.ok)
         return validation;
-    const definition = loadMethodDefinitionFromDir(methodPath);
+    const definition = loadBuildPlanDefinitionFromDir(buildPlanPath);
     if (!definition)
         return validation;
     const errors = [...validation.errors];
     const placeholderStage = definition.stages?.find((stage) => stage.id === "prepare" &&
-        stage.contract_type === "method-draft-stage" &&
+        stage.contract_type === "build-plan-draft-stage" &&
         stage.writes.includes("draft-context"));
-    const placeholderArtifact = listContextInterfaceArtifacts(definition.method_schema).find((artifact) => artifact.id === "draft-context");
-    const placeholderPurpose = definition.purpose?.label === "From-scratch Method draft" ||
+    const placeholderArtifact = listContextInterfaceArtifacts(definition.build_plan_schema).find((artifact) => artifact.id === "draft-context");
+    const placeholderPurpose = definition.purpose?.label === "From-scratch Build Plan draft" ||
         definition.purpose?.task_hint?.includes("Replace this neutral scaffold");
     if (placeholderStage) {
-        errors.push("Authored Method still contains the neutral scaffold stage `prepare`.");
+        errors.push("Authored Build Plan still contains the neutral scaffold stage `prepare`.");
     }
     if (placeholderArtifact) {
-        errors.push("Authored Method still contains the neutral scaffold artifact `draft-context`.");
+        errors.push("Authored Build Plan still contains the neutral scaffold artifact `draft-context`.");
     }
     if (placeholderPurpose) {
-        errors.push("Authored Method still contains the neutral scaffold purpose.");
+        errors.push("Authored Build Plan still contains the neutral scaffold purpose.");
     }
-    errors.push(...validateArtifactRequirements(methodPath, definition, artifactRequirements));
-    errors.push(...validateMustContainStageDocs(methodPath, definition));
+    errors.push(...validateArtifactRequirements(definition, artifactRequirements));
     return {
         ok: validation.ok && errors.length === 0,
         summary: errors.length === 0
             ? validation.summary
-            : `Method package has ${errors.length} issue(s).`,
+            : `Build Plan package has ${errors.length} issue(s).`,
         errors,
         counts: validation.counts,
     };
 }
-export async function runMethodAuthoringDraft(options) {
-    const methodPath = createScratchLocalMethodPackage({
+export async function runBuildPlanAuthoringDraft(options) {
+    const buildPlanPath = createScratchLocalBuildPlanPackage({
         prepDataDir: options.prepDataDir,
-        methodId: options.methodId,
+        buildPlanId: options.buildPlanId,
         label: options.label,
         hint: options.hint,
     });
-    const shell = createMethodAuthoringShell({
-        methodPath,
-        methodId: options.methodId,
+    const shell = createBuildPlanAuthoringShell({
+        buildPlanPath,
+        buildPlanId: options.buildPlanId,
         label: options.label,
-        referenceMethodId: options.baseMethodId ?? null,
+        referenceBuildPlanId: options.baseBuildPlanId ?? null,
         sourceFolderPath: options.sourceFolderPath,
         taskPrompt: options.taskPrompt,
         checks: options.checks ?? [],
+        requestedArtifacts: options.requestedArtifacts ?? [],
+        sourceProfile: options.sourceProfile ?? null,
         artifactRequirements: options.artifactRequirements ?? [],
     });
-    const session = await runMethodEditSession({
+    const session = await runBuildPlanEditSession({
         executor: options.executor,
-        methodPath,
+        buildPlanPath,
         shell,
-        prompt: buildMethodAuthoringPrompt(),
-        validate: (methodPath) => validateAuthoredMethodPackage(methodPath, options.artifactRequirements ?? []),
+        prompt: buildBuildPlanAuthoringPrompt(),
+        validate: (buildPlanPath) => validateAuthoredBuildPlanPackage(buildPlanPath, options.artifactRequirements ?? []),
         maxValidationRepairAttempts: 1,
         onStatus: options.onStatus,
     });
     if (session.status !== "updated") {
-        rmSync(methodPath, { recursive: true, force: true });
+        rmSync(buildPlanPath, { recursive: true, force: true });
     }
     else {
         // 0.15 — auto-fill `role: "general"` for any stage the agent
         // didn't explicitly tag. Idempotent and silent when every stage
         // already declares a role.
-        const touched = ensureStageRoles(methodPath);
+        const touched = ensureStageRoles(buildPlanPath);
         if (touched.length > 0 && options.onStatus) {
             options.onStatus(`STATUS: filled role=general on ${touched.length} stage(s) the author didn't tag (${touched.join(", ")}).`);
         }
@@ -251,10 +220,10 @@ export async function runMethodAuthoringDraft(options) {
         changed: session.changed,
         summary: session.summary,
         validation: session.validation,
-        methodPath,
+        buildPlanPath,
         shellPath: shell.rootPath,
     };
 }
-export function resolveMethodDraftPath(sourcePath, methodId) {
-    return methodDefinitionPath(sourcePath, methodId);
+export function resolveBuildPlanDraftPath(sourcePath, buildPlanId) {
+    return buildPlanDefinitionPath(sourcePath, buildPlanId);
 }

package/dist/packages/build-plans/authoring/build-plan-edit-session.d.ts

@@ -0,0 +1,18 @@
+import type { AgentExecutor } from "../../engine/agents/lib/executors.js";
+import type { BuildPlanValidationResult } from "../package/local-build-plans.js";
+import { type BuildPlanEditShellArtifacts } from "./lib/build-plan-edit-utils.js";
+export interface BuildPlanEditSessionResult {
+    status: "updated" | "no-change" | "invalid" | "executor-failed";
+    changed: boolean;
+    validation: BuildPlanValidationResult | null;
+    summary: string;
+}
+export declare function runBuildPlanEditSession(options: {
+    executor: AgentExecutor;
+    buildPlanPath: string;
+    shell: BuildPlanEditShellArtifacts;
+    prompt: string;
+    validate: (buildPlanPath: string) => BuildPlanValidationResult;
+    maxValidationRepairAttempts?: number;
+    onStatus?: (line: string) => void;
+}): Promise<BuildPlanEditSessionResult>;

package/dist/packages/{methods/authoring/method-edit-session.js → build-plans/authoring/build-plan-edit-session.js}

@@ -1,11 +1,11 @@
 import { appendFileSync, existsSync, realpathSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { copyDirectory, directoriesMatch, } from "./lib/method-edit-utils.js";
-export async function runMethodEditSession(options) {
-    const editableMethodPath = join(options.shell.rootPath, "method");
-    copyDirectory(options.methodPath, options.shell.methodBeforePath);
-    if (!existsSync(editableMethodPath)) {
-        copyDirectory(options.methodPath, editableMethodPath);
+import { copyDirectory, directoriesMatch, } from "./lib/build-plan-edit-utils.js";
+export async function runBuildPlanEditSession(options) {
+    const editableBuildPlanPath = join(options.shell.rootPath, "build-plan");
+    copyDirectory(options.buildPlanPath, options.shell.buildPlanBeforePath);
+    if (!existsSync(editableBuildPlanPath)) {
+        copyDirectory(options.buildPlanPath, editableBuildPlanPath);
     }
     writeFileSync(options.shell.promptLogPath, `${options.prompt}\n`);
     const maxValidationRepairAttempts = options.maxValidationRepairAttempts ?? 0;
@@ -19,9 +19,9 @@ export async function runMethodEditSession(options) {
                 statusLogPath: options.shell.statusLogPath,
                 completionCheck: () => {
                     try {
-                        if (directoriesMatch(options.shell.methodBeforePath, editableMethodPath))
+                        if (directoriesMatch(options.shell.buildPlanBeforePath, editableBuildPlanPath))
                             return false;
-                        return options.validate(editableMethodPath).ok;
+                        return options.validate(editableBuildPlanPath).ok;
                     }
                     catch {
                         return false;
@@ -33,84 +33,84 @@ export async function runMethodEditSession(options) {
         catch (error) {
             executeError = error instanceof Error ? error.message : String(error);
         }
-        copyDirectory(editableMethodPath, options.shell.methodAfterPath);
-        const changed = !directoriesMatch(options.shell.methodBeforePath, options.shell.methodAfterPath);
+        copyDirectory(editableBuildPlanPath, options.shell.buildPlanAfterPath);
+        const changed = !directoriesMatch(options.shell.buildPlanBeforePath, options.shell.buildPlanAfterPath);
         if (executeError) {
-            copyDirectory(options.shell.methodBeforePath, options.methodPath);
-            copyDirectory(options.shell.methodBeforePath, editableMethodPath);
+            copyDirectory(options.shell.buildPlanBeforePath, options.buildPlanPath);
+            copyDirectory(options.shell.buildPlanBeforePath, editableBuildPlanPath);
             return {
                 status: "executor-failed",
                 changed,
                 validation: null,
-                summary: `Method editor failed before completing: ${executeError}`,
+                summary: `Build Plan editor failed before completing: ${executeError}`,
             };
         }
         if (code !== 0) {
-            copyDirectory(options.shell.methodBeforePath, options.methodPath);
-            copyDirectory(options.shell.methodBeforePath, editableMethodPath);
+            copyDirectory(options.shell.buildPlanBeforePath, options.buildPlanPath);
+            copyDirectory(options.shell.buildPlanBeforePath, editableBuildPlanPath);
             return {
                 status: "executor-failed",
                 changed,
                 validation: null,
-                summary: `Method editor exited with code ${code}.`,
+                summary: `Build Plan editor exited with code ${code}.`,
             };
         }
-        const validation = options.validate(editableMethodPath);
+        const validation = options.validate(editableBuildPlanPath);
         if (validation.ok) {
-            if (!sameRealPath(editableMethodPath, options.methodPath)) {
-                copyDirectory(editableMethodPath, options.methodPath);
+            if (!sameRealPath(editableBuildPlanPath, options.buildPlanPath)) {
+                copyDirectory(editableBuildPlanPath, options.buildPlanPath);
             }
             return {
                 status: changed ? "updated" : "no-change",
                 changed,
                 validation,
                 summary: changed
-                    ? "Method package updated and validated."
-                    : "Method package is valid without additional edits.",
+                    ? "Build Plan package updated and validated."
+                    : "Build Plan package is valid without additional edits.",
             };
         }
         const details = validation.errors.length > 0
             ? `: ${validation.errors.slice(0, 6).join("; ")}`
             : "";
         if (!changed || attempt >= maxValidationRepairAttempts) {
-            copyDirectory(options.shell.methodBeforePath, options.methodPath);
-            copyDirectory(options.shell.methodBeforePath, editableMethodPath);
+            copyDirectory(options.shell.buildPlanBeforePath, options.buildPlanPath);
+            copyDirectory(options.shell.buildPlanBeforePath, editableBuildPlanPath);
             return {
                 status: "invalid",
                 changed,
                 validation,
                 summary: changed
-                    ? `Method package failed validation: ${validation.summary}${details}`
-                    : `Method package is invalid without any Method edits: ${validation.summary}${details}`,
+                    ? `Build Plan package failed validation: ${validation.summary}${details}`
+                    : `Build Plan package is invalid without any Build Plan edits: ${validation.summary}${details}`,
             };
         }
         prompt = [
-            "This is an automated Interf Method validation-repair pass.",
+            "This is an automated Interf Build Plan validation-repair pass.",
             "The previous edit did not pass package validation.",
-            "Fix only the validation errors below. Do not redesign the Method.",
+            "Fix only the validation errors below. Do not redesign the Build Plan.",
             "",
             "Validation errors:",
             ...validation.errors.slice(0, 12).map((error) => `- ${error}`),
             "",
             "Rules:",
-            "- Edit only files under `method/`.",
+            "- Edit only files under `build-plan/`.",
             "- Use kebab-case ids everywhere: stage ids, skill_dir values, Artifact ids, reads/writes values, and package ids. Never use underscores.",
-            "- Keep every stage `skill_dir` matched by `method/compile/stages/<skill_dir>/SKILL.md`.",
-            "- Keep `method.schema.json` Artifact paths unique and non-overlapping.",
+            "- Keep every stage `skill_dir` matched by `build-plan/build/stages/<skill_dir>/SKILL.md`.",
+            "- Keep `build-plan.schema.json` Artifact paths unique and non-overlapping.",
             "- Put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks.",
             "- Use only CheckKind values listed in `runtime/authoring-context.json`; replace invented aliases with valid kinds.",
-            "- If the Method writes an agent entrypoint, keep it declared as an Artifact owned by the producing stage.",
+            "- If the Build Plan writes an agent entrypoint, keep it declared as an Artifact owned by the producing stage.",
             "- Stop as soon as the package should validate.",
         ].join("\n");
         appendFileSync(options.shell.promptLogPath, `\n\n---\n\n${prompt}\n`);
     }
-    copyDirectory(options.shell.methodBeforePath, options.methodPath);
-    copyDirectory(options.shell.methodBeforePath, editableMethodPath);
+    copyDirectory(options.shell.buildPlanBeforePath, options.buildPlanPath);
+    copyDirectory(options.shell.buildPlanBeforePath, editableBuildPlanPath);
     return {
         status: "invalid",
         changed: true,
         validation: null,
-        summary: "Method package failed validation.",
+        summary: "Build Plan package failed validation.",
     };
 }
 function sameRealPath(leftPath, rightPath) {

package/dist/packages/build-plans/authoring/build-plan-improvement.d.ts

@@ -0,0 +1,23 @@
+import type { AgentExecutor } from "../../engine/agents/lib/executors.js";
+import { type BuildPlanValidationResult } from "../package/local-build-plans.js";
+import type { SourcePreparationConfig } from "../../project/lib/schema.js";
+import type { BuildPlanImprovementLoopSummary } from "../../engine/build/lib/schema.js";
+export interface BuildPlanImprovementRunResult {
+    status: "updated" | "no-change" | "invalid" | "executor-failed";
+    changed: boolean;
+    validation: BuildPlanValidationResult | null;
+    summary: string;
+    shellPath: string;
+    loopRootPath: string;
+}
+export declare function runBuildPlanImprovementLoop(options: {
+    executor: AgentExecutor;
+    verifiableContextPath: string;
+    buildPlanId: string;
+    verifiableContextConfig: Pick<SourcePreparationConfig, "checks">;
+    runId: string;
+    loopIndex: number;
+    maxLoops: number;
+    maxAttempts: number;
+    previousVariations: BuildPlanImprovementLoopSummary[];
+}): Promise<BuildPlanImprovementRunResult>;