@voybio/ace-swarm 0.2.5 → 2.4.1

package/dist/plan-proposal.js

@@ -0,0 +1,1073 @@
+/**
+ * Workstream J — Planner contract: propose_plan, validate_plan, loadAcceptanceTraceContract.
+ * Extracted to its own module so both tools-agent.ts and runtime-executor.ts can import without
+ * a circular dependency (tools-agent already imports from runtime-executor).
+ */
+import { randomUUID } from "node:crypto";
+import { listAceInternalToolCatalog } from "./ace-internal-tools.js";
+import { runLocalModelTask } from "./local-model-runtime.js";
+import { listRuntimeToolSpecs } from "./runtime-tool-specs.js";
+import { resolveWorkspaceRoot, safeRead, safeWriteAsync } from "./helpers.js";
+import { appendVericifyProcessPostSafe } from "./vericify-bridge.js";
+import { withLocalModelRuntimeRepository } from "./store/repositories/local-model-runtime-repository.js";
+// ── In-memory proposal cache (plan_id → ProposePlanResult) ────────────────
+const _proposalCache = new Map();
+function storeProposal(result) {
+    _proposalCache.set(result.plan_id, result);
+}
+export function lookupProposal(plan_id) {
+    return _proposalCache.get(plan_id);
+}
+// ── Helpers ────────────────────────────────────────────────────────────────
+export function inferExpectedOutputClass(step) {
+    if (step.role === "qa" || step.role === "release")
+        return "qa_verdict";
+    if ((step.tool_scope ?? []).some((tool) => tool.includes("astgrep") || tool.includes("structural_edit"))) {
+        return "structural_edit_plan";
+    }
+    if ((step.tool_scope ?? []).some((tool) => tool.includes("write") || tool.includes("safe_edit"))) {
+        return "code_artifact";
+    }
+    if ((step.tool_scope ?? []).length > 0)
+        return "tool_envelope";
+    return "plain_text_plan";
+}
+function enrichPlanProposalStep(step) {
+    return {
+        ...step,
+        expected_output_class: step.expected_output_class ?? inferExpectedOutputClass(step),
+        allowed_tools: step.allowed_tools ?? step.tool_scope,
+        structural_edit_plan_required: step.structural_edit_plan_required ??
+            (inferExpectedOutputClass(step) === "structural_edit_plan" ? true : undefined),
+    };
+}
+function enrichContractStep(step) {
+    return {
+        ...step,
+        expected_output_class: step.expected_output_class ?? inferExpectedOutputClass(step),
+        allowed_tools: step.allowed_tools ?? step.tool_scope,
+        structural_edit_plan_required: step.structural_edit_plan_required ??
+            (inferExpectedOutputClass(step) === "structural_edit_plan" ? true : undefined),
+    };
+}
+function scaffoldArtifactExpectations(step) {
+    const expected = inferExpectedOutputClass(step);
+    if (expected !== "code_artifact" && expected !== "structural_edit_plan")
+        return undefined;
+    if (step.role === "spec") {
+        return [{ path: "agent-state/SPEC_CONTRACT.json", required: false, evidence_ref_kind: "artifact" }];
+    }
+    if (step.role === "docs") {
+        return [{ path: "agent-state", required: false, evidence_ref_kind: "artifact" }];
+    }
+    return [{ path: "workspace-artifact", required: false, evidence_ref_kind: "artifact" }];
+}
+function isCodeMutatingStep(step) {
+    if (step.role === "coders" || step.role === "builder" || step.role === "astgrep")
+        return true;
+    if (step.expected_output_class === "code_artifact" || step.expected_output_class === "structural_edit_plan")
+        return true;
+    return (step.tool_scope ?? []).some((tool) => /write|edit|rewrite|safe_edit|astgrep|structural/i.test(tool));
+}
+function hasStructuralEditWaiver(step) {
+    const waiver = step.structural_edit_waiver;
+    return Boolean(waiver?.reason?.trim() && waiver?.evidence_ref?.trim());
+}
+function isPlanProposal(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    return (typeof v.intent_summary === "string" &&
+        Array.isArray(v.success_criteria) &&
+        Array.isArray(v.steps));
+}
+function extractJsonBlock(text) {
+    const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fenced?.[1])
+        return fenced[1].trim();
+    const bare = text.match(/(\{[\s\S]*\})/);
+    if (bare?.[1])
+        return bare[1].trim();
+    return undefined;
+}
+function getAvailableToolNames() {
+    try {
+        const names = new Set();
+        for (const tool of listAceInternalToolCatalog()) {
+            names.add(tool.name);
+        }
+        for (const tool of listRuntimeToolSpecs()) {
+            names.add(tool.name);
+        }
+        return names.size > 0 ? names : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizeTaskText(task) {
+    return task.replace(/\s+/g, " ").trim();
+}
+const CLAUSE_HINTS = [
+    "research",
+    "investigate",
+    "analyze",
+    "analyse",
+    "audit",
+    "inspect",
+    "diagnose",
+    "dissect",
+    "study",
+    "discover",
+    "explore",
+    "understand",
+    "spec",
+    "design",
+    "plan",
+    "contract",
+    "define",
+    "implement",
+    "build",
+    "create",
+    "add",
+    "fix",
+    "patch",
+    "refactor",
+    "rewrite",
+    "migrate",
+    "update",
+    "validate",
+    "verify",
+    "test",
+    "review",
+    "check",
+    "ship",
+    "release",
+    "deploy",
+    "publish",
+    "merge",
+    "document",
+    "docs",
+    "security",
+    "hardening",
+    "observe",
+    "orchestrate",
+    "handoff",
+    "coordinate",
+];
+function countClauseHints(text) {
+    const lower = text.toLowerCase();
+    return CLAUSE_HINTS.reduce((count, hint) => {
+        const pattern = new RegExp(`\\b${hint.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i");
+        return count + (pattern.test(lower) ? 1 : 0);
+    }, 0);
+}
+function splitTaskClauses(task) {
+    const normalized = normalizeTaskText(task);
+    if (!normalized)
+        return [];
+    const initialSegments = normalized
+        .split(/[\n;]+/)
+        .flatMap((segment) => segment.split(/(?<=[.!?])\s+/))
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0);
+    const clauses = [];
+    const segments = initialSegments.length > 0 ? initialSegments : [normalized];
+    for (const segment of segments) {
+        if (segment.length > 180 && countClauseHints(segment) >= 2) {
+            const conjunctive = segment
+                .split(/\s+(?:and|then|plus|while|after)\s+/i)
+                .map((piece) => piece.trim().replace(/^[,;:]+|[,;:]+$/g, ""))
+                .filter((piece) => piece.length > 0);
+            if (conjunctive.length > 1) {
+                clauses.push(...conjunctive);
+                continue;
+            }
+        }
+        if (segment.includes(",")) {
+            const commaParts = segment
+                .split(/\s*,\s*/)
+                .map((piece) => piece.trim())
+                .filter((piece) => piece.length > 0);
+            if (commaParts.length > 1 && commaParts.some((piece) => piece.length > 12)) {
+                clauses.push(...commaParts);
+                continue;
+            }
+        }
+        clauses.push(segment);
+    }
+    return Array.from(new Set(clauses.map((clause) => clause.trim()).filter(Boolean)));
+}
+function classifyClauseKind(clause) {
+    const text = clause.toLowerCase();
+    if (/\b(research|investigate|analy[sz]e|audit|inspect|diagnose|dissect|study|discover|explore|understand|triage|map)\b/.test(text)) {
+        return "discovery";
+    }
+    if (/\b(spec|design|plan|architect|contract|define|interface|requirements?|shape)\b/.test(text)) {
+        return "spec";
+    }
+    if (/\b(verify|validate|test|qa|check|confirm|review|prove)\b/.test(text)) {
+        return "verification";
+    }
+    if (/\b(release|ship|deploy|publish|merge|promote|rollout|launch)\b/.test(text)) {
+        return "release";
+    }
+    if (/\b(document|docs|documentation|readme|guide|onboard|changelog)\b/.test(text)) {
+        return "docs";
+    }
+    if (/\b(security|hardening|privacy|threat|vulnerab|auth|risk)\b/.test(text)) {
+        return "security";
+    }
+    if (/\b(ops|orchestrate|coordinate|handoff|schedule|route|dispatch)\b/.test(text)) {
+        return "ops";
+    }
+    return "implementation";
+}
+function roleForClauseKind(kind) {
+    switch (kind) {
+        case "discovery":
+            return "research";
+        case "spec":
+            return "spec";
+        case "verification":
+            return "qa";
+        case "release":
+            return "release";
+        case "docs":
+            return "docs";
+        case "security":
+            return "security";
+        case "ops":
+            return "orchestrator";
+        case "implementation":
+        default:
+            return "coders";
+    }
+}
+function isShipBoundaryTask(task) {
+    return /\b(ship|release|promot(?:e|ion)|land|merge)\b/i.test(task);
+}
+function toolScopeForClauseKind(kind, shipBoundary) {
+    switch (kind) {
+        case "discovery":
+            return [
+                "recall_context",
+                "read_workspace_file",
+                "build_continuity_packet",
+                "validate_framework",
+            ];
+        case "spec":
+            return ["read_workspace_file", "write_workspace_file", "execute_gates", "validate_framework"];
+        case "verification":
+            return shipBoundary
+                ? ["run_tests", "execute_gates", "git_diff", "git_status"]
+                : ["run_tests", "execute_gates", "git_diff"];
+        case "release":
+            return ["git_status", "git_diff", "execute_gates", "validate_framework"];
+        case "docs":
+            return ["read_workspace_file", "write_workspace_file", "git_diff", "git_status"];
+        case "security":
+            return ["execute_gates", "validate_framework", "read_workspace_file", "git_diff"];
+        case "ops":
+            return ["recall_context", "build_continuity_packet", "execute_gates", "validate_framework"];
+        case "implementation":
+        default:
+            return [
+                "outline_file",
+                "astgrep_query",
+                "astgrep_locate",
+                "read_file_lines",
+                "compile_structural_edit",
+                "preview_structural_edit",
+                "astgrep_rewrite",
+                "safe_edit_file",
+                "run_tests",
+                "git_diff",
+                "git_status",
+            ];
+    }
+}
+function buildAcceptanceCriteriaForStep(input) {
+    const { kind, clause, task, index, total, shipBoundary } = input;
+    switch (kind) {
+        case "discovery":
+            return [
+                "The objective, constraints, and dependencies are enumerated.",
+                "Known unknowns are explicit before downstream work starts.",
+                "Existing workspace state is reviewed before planning further passes.",
+            ];
+        case "spec":
+            return [
+                "The work is broken into explicit phases with dependencies.",
+                "Each downstream pass has a clear success criterion.",
+                "Stop conditions are written before implementation begins.",
+            ];
+        case "verification":
+            return [
+                "The results map back to the original intent.",
+                "Any residual gaps or failures are explicit.",
+                "Evidence exists for the verification verdict.",
+            ];
+        case "release":
+            return [
+                "The ship decision is evidence-backed.",
+                "Residual risks are explicit before the handoff closes.",
+                "The release gate references the validated work rather than assumptions.",
+            ];
+        case "docs":
+            return [
+                "User-facing explanation matches the work performed.",
+                "Documentation references the actual artifact state.",
+                "Open questions are called out rather than hidden.",
+            ];
+        case "security":
+            return [
+                "Security risks are assessed against the current change set.",
+                "Any blockers are explicit and reviewable.",
+                "Ship readiness remains grounded in evidence.",
+            ];
+        case "ops":
+            return [
+                "Dependencies and handoffs are ordered.",
+                "The execution route is explicit.",
+                "Circuit-breaker points are clear before the next pass starts.",
+            ];
+        case "implementation":
+        default:
+            return [
+                `Complete clause ${index + 1}/${total}: ${clause}`,
+                "Produce a reviewable artifact or diff for the clause.",
+                shipBoundary
+                    ? "Leave ship-relevant evidence available for downstream review."
+                    : "Leave evidence available for downstream verification.",
+            ];
+    }
+}
+function buildStopConditionsForStep(input) {
+    const { kind, clause, task, shipBoundary } = input;
+    switch (kind) {
+        case "discovery":
+            return [
+                "Stop when the objective can be restated with constraints, unknowns, and dependencies.",
+            ];
+        case "spec":
+            return [
+                "Stop when the plan has a sequenced set of work packages and explicit acceptance gates.",
+            ];
+        case "verification":
+            return [
+                "Stop when the result is clearly accepted, rejected, or blocked with evidence.",
+            ];
+        case "release":
+            return [
+                "Stop when the ship decision is explicit and evidence-backed.",
+            ];
+        case "docs":
+            return [
+                "Stop when the documentation reflects the actual deliverable and no major gap remains.",
+            ];
+        case "security":
+            return [
+                "Stop when security risks are either cleared or isolated as explicit blockers.",
+            ];
+        case "ops":
+            return [
+                "Stop when the handoff path and dependency order are explicit enough to execute.",
+            ];
+        case "implementation":
+        default:
+            return [
+                shipBoundary
+                    ? `Stop when clause work for "${clause}" is complete and ready for review in the ship path.`
+                    : `Stop when clause work for "${clause}" is complete and ready for verification.`,
+            ];
+    }
+}
+function buildSuccessCriteria(task, clauses, shipBoundary) {
+    const criteria = [
+        "The objective is broken into explicit phases.",
+        "Each phase names a role, tool scope, acceptance criteria, and stop condition.",
+        "Verification closes the loop before handoff.",
+    ];
+    if (clauses.length > 1) {
+        criteria.push(`All ${clauses.length} goal clauses are addressed in order.`);
+    }
+    if (shipBoundary) {
+        criteria.push("Ship readiness is explicitly confirmed before release.");
+    }
+    if (task.trim().length > 0) {
+        criteria.push(`The compiled plan still traces back to the original goal: ${task}.`);
+    }
+    return criteria;
+}
+function buildDeterministicScaffoldStepTask(input) {
+    const { kind, clause, task, index, total, shipBoundary } = input;
+    switch (kind) {
+        case "discovery":
+            return `Phase 3.${index + 1} - Discovery: map constraints, unknowns, and dependencies for ${clause}`;
+        case "spec":
+            return `Phase 3.${index + 1} - Planning: translate ${clause} into sequenced work with explicit gates`;
+        case "verification":
+            return `Phase 3.${index + 1} - Verification: validate the compiled goal against ${clause || task}`;
+        case "release":
+            return `Phase 3.${index + 1} - Release: finalize the ship decision for ${task}`;
+        case "docs":
+            return `Phase 3.${index + 1} - Documentation: align user-facing explanation with ${clause}`;
+        case "security":
+            return `Phase 3.${index + 1} - Security: assess risks for ${clause}`;
+        case "ops":
+            return `Phase 3.${index + 1} - Coordination: turn ${clause} into an executable handoff path`;
+        case "implementation":
+        default:
+            return shipBoundary
+                ? `Phase 3.${index + 1} - Implementation: deliver ${clause} and keep evidence for ship review`
+                : `Phase 3.${index + 1} - Implementation: deliver ${clause} and keep evidence for verification`;
+    }
+}
+function compileGoalScaffold(task, plan_id) {
+    const normalizedTask = normalizeTaskText(task) || "Clarify the objective";
+    const clauses = splitTaskClauses(normalizedTask);
+    const shipBoundary = isShipBoundaryTask(normalizedTask);
+    const scaffoldSteps = [];
+    const discoveryId = "goal-discovery";
+    scaffoldSteps.push({
+        id: discoveryId,
+        role: "research",
+        task: `Phase 1 - Discovery: map constraints, unknowns, and dependencies for ${normalizedTask}`,
+        depends_on_ids: [],
+        tool_scope: toolScopeForClauseKind("discovery", shipBoundary),
+        acceptance_criteria: buildAcceptanceCriteriaForStep({
+            kind: "discovery",
+            clause: normalizedTask,
+            task: normalizedTask,
+            index: 0,
+            total: Math.max(clauses.length, 1),
+            shipBoundary,
+        }),
+        stop_condition: buildStopConditionsForStep({
+            kind: "discovery",
+            clause: normalizedTask,
+            task: normalizedTask,
+            shipBoundary,
+        }),
+    });
+    const specId = "goal-spec";
+    scaffoldSteps.push({
+        id: specId,
+        role: "spec",
+        task: `Phase 2 - Planning: turn the objective into sequenced work with explicit gates for ${normalizedTask}`,
+        depends_on_ids: [discoveryId],
+        tool_scope: toolScopeForClauseKind("spec", shipBoundary),
+        acceptance_criteria: buildAcceptanceCriteriaForStep({
+            kind: "spec",
+            clause: normalizedTask,
+            task: normalizedTask,
+            index: 0,
+            total: Math.max(clauses.length, 1),
+            shipBoundary,
+        }),
+        stop_condition: buildStopConditionsForStep({
+            kind: "spec",
+            clause: normalizedTask,
+            task: normalizedTask,
+            shipBoundary,
+        }),
+    });
+    const executionStepIds = [];
+    const executionClauses = clauses.length > 0 ? clauses : [normalizedTask];
+    for (const [index, clause] of executionClauses.entries()) {
+        const rawKind = classifyClauseKind(clause);
+        const kind = rawKind === "release" && shipBoundary && executionClauses.length === 1 && normalizeTaskText(clause) === normalizedTask
+            ? "implementation"
+            : rawKind;
+        const role = roleForClauseKind(kind);
+        const stepId = `goal-${role}-${index + 1}`;
+        const dependency = index === 0 ? specId : executionStepIds[index - 1];
+        scaffoldSteps.push({
+            id: stepId,
+            role,
+            task: buildDeterministicScaffoldStepTask({
+                kind,
+                clause,
+                task: normalizedTask,
+                index,
+                total: executionClauses.length,
+                shipBoundary,
+            }),
+            depends_on_ids: [dependency],
+            tool_scope: toolScopeForClauseKind(kind, shipBoundary),
+            acceptance_criteria: buildAcceptanceCriteriaForStep({
+                kind,
+                clause,
+                task: normalizedTask,
+                index,
+                total: executionClauses.length,
+                shipBoundary,
+            }),
+            stop_condition: buildStopConditionsForStep({
+                kind,
+                clause,
+                task: normalizedTask,
+                shipBoundary,
+            }),
+        });
+        executionStepIds.push(stepId);
+    }
+    const verificationDependsOn = executionStepIds.length > 0 ? [...executionStepIds] : [specId];
+    if (shipBoundary) {
+        const reviewId = "goal-skeptic-1";
+        const securityId = "goal-security-1";
+        const qaId = "goal-qa-1";
+        scaffoldSteps.push({
+            id: reviewId,
+            role: "skeptic",
+            task: `Phase 4 - Review: assess ship readiness for ${normalizedTask}`,
+            depends_on_ids: verificationDependsOn,
+            tool_scope: toolScopeForClauseKind("verification", shipBoundary),
+            acceptance_criteria: buildAcceptanceCriteriaForStep({
+                kind: "verification",
+                clause: normalizedTask,
+                task: normalizedTask,
+                index: executionClauses.length,
+                total: executionClauses.length + 3,
+                shipBoundary,
+            }),
+            stop_condition: buildStopConditionsForStep({
+                kind: "verification",
+                clause: normalizedTask,
+                task: normalizedTask,
+                shipBoundary,
+            }),
+        });
+        scaffoldSteps.push({
+            id: securityId,
+            role: "security",
+            task: `Phase 5 - Security: assess security readiness for ${normalizedTask}`,
+            depends_on_ids: verificationDependsOn,
+            tool_scope: toolScopeForClauseKind("security", shipBoundary),
+            acceptance_criteria: buildAcceptanceCriteriaForStep({
+                kind: "security",
+                clause: normalizedTask,
+                task: normalizedTask,
+                index: executionClauses.length + 1,
+                total: executionClauses.length + 3,
+                shipBoundary,
+            }),
+            stop_condition: buildStopConditionsForStep({
+                kind: "security",
+                clause: normalizedTask,
+                task: normalizedTask,
+                shipBoundary,
+            }),
+        });
+        scaffoldSteps.push({
+            id: qaId,
+            role: "qa",
+            task: `Phase 6 - QA: validate ship readiness for ${normalizedTask}`,
+            depends_on_ids: verificationDependsOn,
+            tool_scope: toolScopeForClauseKind("verification", shipBoundary),
+            acceptance_criteria: buildAcceptanceCriteriaForStep({
+                kind: "verification",
+                clause: normalizedTask,
+                task: normalizedTask,
+                index: executionClauses.length + 2,
+                total: executionClauses.length + 3,
+                shipBoundary,
+            }),
+            stop_condition: buildStopConditionsForStep({
+                kind: "verification",
+                clause: normalizedTask,
+                task: normalizedTask,
+                shipBoundary,
+            }),
+        });
+        scaffoldSteps.push({
+            id: "goal-release-1",
+            role: "release",
+            task: `Phase 7 - Release: finalize the ship decision for ${normalizedTask}`,
+            depends_on_ids: [reviewId, securityId, qaId],
+            tool_scope: toolScopeForClauseKind("release", shipBoundary),
+            acceptance_criteria: buildAcceptanceCriteriaForStep({
+                kind: "release",
+                clause: normalizedTask,
+                task: normalizedTask,
+                index: executionClauses.length + 3,
+                total: executionClauses.length + 4,
+                shipBoundary,
+            }),
+            stop_condition: buildStopConditionsForStep({
+                kind: "release",
+                clause: normalizedTask,
+                task: normalizedTask,
+                shipBoundary,
+            }),
+        });
+    }
+    else {
+        scaffoldSteps.push({
+            id: "goal-qa-1",
+            role: "qa",
+            task: `Phase 4 - Verification: validate the compiled goal against ${normalizedTask}`,
+            depends_on_ids: verificationDependsOn,
+            tool_scope: toolScopeForClauseKind("verification", shipBoundary),
+            acceptance_criteria: buildAcceptanceCriteriaForStep({
+                kind: "verification",
+                clause: normalizedTask,
+                task: normalizedTask,
+                index: executionClauses.length,
+                total: executionClauses.length + 1,
+                shipBoundary,
+            }),
+            stop_condition: buildStopConditionsForStep({
+                kind: "verification",
+                clause: normalizedTask,
+                task: normalizedTask,
+                shipBoundary,
+            }),
+        });
+    }
+    const publicStepLabels = new Map();
+    scaffoldSteps.forEach((step, index) => {
+        publicStepLabels.set(step.id, `step-${index + 1}`);
+    });
+    const steps = scaffoldSteps.map(({ id: _id, depends_on_ids: dependsOnIds, ...step }) => ({
+        role: step.role,
+        task: step.task,
+        depends_on: dependsOnIds.length > 0
+            ? dependsOnIds.map((dependency) => publicStepLabels.get(dependency) ?? dependency)
+            : undefined,
+        tool_scope: step.tool_scope,
+        acceptance_criteria: step.acceptance_criteria,
+        stop_condition: step.stop_condition,
+        expected_artifacts: scaffoldArtifactExpectations(step),
+        structural_edit_plan_required: inferExpectedOutputClass(step) === "code_artifact" ||
+            inferExpectedOutputClass(step) === "structural_edit_plan"
+            ? true
+            : undefined,
+    }));
+    const result = {
+        plan_id,
+        status: "planning",
+        intent_summary: `Deterministic goal compiler scaffold for: ${normalizedTask}`,
+        success_criteria: buildSuccessCriteria(normalizedTask, clauses.length > 0 ? clauses : [normalizedTask], shipBoundary),
+        steps,
+        plan_source: "deterministic_fallback",
+    };
+    storeProposal(result);
+    return result;
+}
+// ── Planner model call ─────────────────────────────────────────────────────
+async function callPlannerModel(task, scaffold) {
+    const plannerTask = [
+        `You are ACE-Planner. Refine the deterministic scaffold into the strongest valid JSON PlanProposal for the following task.`,
+        ``,
+        `Task: ${task}`,
+        ``,
+        `Deterministic scaffold to preserve or improve (do not shrink coverage, remove verification, or drop stop conditions):`,
+        JSON.stringify({
+            intent_summary: scaffold.intent_summary,
+            success_criteria: scaffold.success_criteria,
+            steps: scaffold.steps,
+        }, null, 2),
+        ``,
+        `Return ONLY valid JSON matching this shape (no prose before or after):`,
+        `{`,
+        `  "intent_summary": "<one paragraph summary of intent>",`,
+        `  "success_criteria": ["<criterion>", ...],`,
+        `  "steps": [`,
+        `    {`,
+        `      "role": "<ace-role>",`,
+        `      "task": "<task directive>",`,
+        `      "depends_on": ["<step-N>"],`,
+        `      "tool_scope": ["<tool-name>"],`,
+        `      "acceptance_criteria": ["<criterion>"],`,
+        `      "stop_condition": ["<stop condition>"],`,
+        `      "expected_output_class": "plain_text_plan|tool_envelope|code_artifact|structural_edit_plan|qa_verdict",`,
+        `      "expected_artifacts": [{"path":"<relative artifact path>","required":true,"evidence_ref_kind":"artifact|diff|hash|test|gate"}],`,
+        `      "allowed_tools": ["<tool-name>"],`,
+        `      "forbidden_patterns": ["<pattern>"],`,
+        `      "required_evidence_refs": ["<evidence ref substring>"]`,
+        `    }`,
+        `  ]`,
+        `}`,
+    ].join("\n");
+    try {
+        const delegated = await runLocalModelTask({
+            task: plannerTask,
+            role: "planner",
+            toolScope: [
+                "recall_context",
+                "read_workspace_file",
+                "build_continuity_packet",
+                "get_skill_instructions",
+            ],
+        });
+        const rawSummary = delegated.result.summary ?? "";
+        const jsonText = extractJsonBlock(rawSummary) ?? rawSummary;
+        const parsed = JSON.parse(jsonText);
+        return isPlanProposal(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ── Plan shape validation ──────────────────────────────────────────────────
+function validatePlanShape(plan_id, proposal) {
+    void plan_id;
+    const blockingFindings = [];
+    const softFindings = [];
+    let passingChecks = 0;
+    // 1. Coverage: intent_summary non-empty and at least one step exists.
+    // We do not compare sentence count to step count because one comprehensive step
+    // (e.g. orchestrator) can legitimately cover a multi-clause intent.
+    {
+        if (!proposal.intent_summary.trim()) {
+            blockingFindings.push("coverage: intent_summary is empty");
+        }
+        else if (proposal.steps.length === 0) {
+            blockingFindings.push("coverage: plan has no steps");
+        }
+        else {
+            passingChecks += 1;
+        }
+    }
+    // 2. Verification chain: implementation steps must have a downstream qa/skeptic step.
+    // Implementation roles: coders, builder, ops, astgrep (code-mutating roles).
+    {
+        const IMPL_ROLES = new Set(["coders", "builder", "ops", "astgrep"]);
+        const implStepIndices = [];
+        for (let i = 0; i < proposal.steps.length; i++) {
+            if (IMPL_ROLES.has(proposal.steps[i].role))
+                implStepIndices.push(i);
+        }
+        const unverified = [];
+        for (const idx of implStepIndices) {
+            const stepRef = `step-${idx + 1}`;
+            const hasDownstream = proposal.steps.slice(idx + 1).some((ds) => {
+                const isQaOrSkeptic = ds.role === "qa" || ds.role === "skeptic";
+                const dependsOnThis = !ds.depends_on || ds.depends_on.length === 0 || ds.depends_on.includes(stepRef);
+                return isQaOrSkeptic && dependsOnThis;
+            });
+            if (!hasDownstream)
+                unverified.push(stepRef);
+        }
+        if (unverified.length === 0) {
+            passingChecks += 1;
+        }
+        else {
+            blockingFindings.push(`verification_chain: implementation step(s) ${unverified.join(", ")} lack a downstream qa/skeptic step`);
+        }
+    }
+    // 3. Tool-scope realism: every step's tool_scope is a subset of the runtime catalog.
+    // Fail closed when the catalog is unavailable so a broken registry cannot silently
+    // disable the check.
+    {
+        const available = getAvailableToolNames();
+        if (!available) {
+            blockingFindings.push("tool_scope_realism: runtime tool catalog unavailable");
+        }
+        else {
+            const unknownTools = [];
+            for (const s of proposal.steps) {
+                for (const tool of s.tool_scope ?? []) {
+                    if (!available.has(tool))
+                        unknownTools.push(tool);
+                }
+            }
+            if (unknownTools.length === 0) {
+                passingChecks += 1;
+            }
+            else {
+                blockingFindings.push(`tool_scope_realism: unknown tool(s) requested: ${[...new Set(unknownTools)].join(", ")}`);
+            }
+        }
+    }
+    // 4. Acceptance criteria presence: every step has at least one criterion
+    {
+        const missingCriteria = proposal.steps
+            .map((s, i) => ({ i, s }))
+            .filter(({ s }) => !s.acceptance_criteria || s.acceptance_criteria.length === 0)
+            .map(({ i }) => `step-${i + 1}`);
+        if (missingCriteria.length === 0) {
+            passingChecks += 1;
+        }
+        else {
+            softFindings.push(`acceptance_criteria: step(s) ${missingCriteria.join(", ")} have no acceptance criteria`);
+        }
+    }
+    // 5. Stop conditions: prefer explicit stop conditions for every step, but do not block
+    // legacy plans yet. The deterministic scaffold always emits them.
+    {
+        const missingStopConditions = proposal.steps
+            .map((s, i) => ({ i, s }))
+            .filter(({ s }) => !s.stop_condition || s.stop_condition.length === 0)
+            .map(({ i }) => `step-${i + 1}`);
+        if (missingStopConditions.length > 0) {
+            softFindings.push(`stop_conditions: step(s) ${missingStopConditions.join(", ")} have no stop conditions`);
+        }
+    }
+    // 6. Contract-class artifact expectations: code and structural edits must say
+    // what artifact evidence can prove them before execution.
+    {
+        const missingArtifacts = proposal.steps
+            .map((step, index) => ({
+            step: enrichPlanProposalStep(step),
+            ref: `step-${index + 1}`,
+        }))
+            .filter(({ step }) => (step.expected_output_class === "code_artifact" ||
+            step.expected_output_class === "structural_edit_plan") &&
+            (step.expected_artifacts ?? []).length === 0)
+            .map(({ ref }) => ref);
+        if (missingArtifacts.length > 0) {
+            blockingFindings.push(`contract_artifacts: code/structural step(s) ${missingArtifacts.join(", ")} lack expected_artifacts`);
+        }
+        else {
+            passingChecks += 1;
+        }
+    }
+    // 7. Code-mutating steps must route through a structural edit plan or carry
+    // an explicit, evidence-backed waiver.
+    {
+        const missingStructuralPlan = proposal.steps
+            .map((step, index) => ({
+            step: enrichPlanProposalStep(step),
+            ref: `step-${index + 1}`,
+        }))
+            .filter(({ step }) => isCodeMutatingStep(step) &&
+            step.structural_edit_plan_required !== true &&
+            !hasStructuralEditWaiver(step))
+            .map(({ ref }) => ref);
+        if (missingStructuralPlan.length > 0) {
+            blockingFindings.push(`structural_edit_plan: code-mutating step(s) ${missingStructuralPlan.join(", ")} require structural_edit_plan_required=true or an evidence-backed waiver`);
+        }
+        else {
+            passingChecks += 1;
+        }
+    }
+    const score = Math.round((passingChecks / 6) * 100);
+    return {
+        ok: blockingFindings.length === 0,
+        score,
+        blocking_findings: blockingFindings,
+        soft_findings: softFindings,
+    };
+}
+// ── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Lightweight synchronous variant used in runtime preflights.
+ * Skips the model bridge call entirely and returns the deterministic goal scaffold.
+ * This keeps the preflight free of network I/O that could delay session startup.
+ */
+export function proposePlanDeterministic(task) {
+    const plan_id = `plan-${randomUUID()}`;
+    const scaffold = compileGoalScaffold(task, plan_id);
+    const result = {
+        ...scaffold,
+        steps: scaffold.steps.map(enrichPlanProposalStep),
+    };
+    storeProposal(result);
+    return result;
+}
+export async function proposePlan(task, sessionId) {
+    void sessionId;
+    const plan_id = `plan-${randomUUID()}`;
+    const scaffold = compileGoalScaffold(task, plan_id);
+    const proposal = await callPlannerModel(task, scaffold);
+    if (proposal) {
+        const result = {
+            plan_id,
+            status: "planning",
+            intent_summary: proposal.intent_summary,
+            success_criteria: proposal.success_criteria,
+            steps: proposal.steps.map(enrichPlanProposalStep),
+            plan_source: "planner_model",
+        };
+        const scaffoldStopConditions = scaffold.steps.filter((step) => (step.stop_condition ?? []).length > 0).length;
+        const proposalStopConditions = proposal.steps.filter((step) => (step.stop_condition ?? []).length > 0).length;
+        if (proposal.steps.length >= scaffold.steps.length &&
+            proposal.success_criteria.length >= scaffold.success_criteria.length &&
+            proposalStopConditions >= scaffoldStopConditions) {
+            storeProposal(result);
+            return result;
+        }
+    }
+    const enrichedScaffold = {
+        ...scaffold,
+        steps: scaffold.steps.map(enrichPlanProposalStep),
+    };
+    storeProposal(enrichedScaffold);
+    return enrichedScaffold;
+}
+export async function validatePlan(input) {
+    let proposal;
+    let resolvedPlanId;
+    if (input.proposal) {
+        proposal = input.proposal;
+        resolvedPlanId = input.proposal.plan_id;
+    }
+    else if (input.plan_id) {
+        resolvedPlanId = input.plan_id;
+        // Check in-memory cache first, then fall back to the persisted ACCEPTANCE_TRACE_MAP.json
+        // so plan_id lookups survive process boundaries.
+        proposal = lookupProposal(resolvedPlanId);
+        if (!proposal) {
+            const contract = loadAcceptanceTraceContract(resolvedPlanId);
+            if (contract) {
+                proposal = {
+                    plan_id: resolvedPlanId,
+                    status: "planning",
+                    intent_summary: contract.intent_summary ?? contract.task,
+                    success_criteria: contract.success_criteria ?? [],
+                    steps: contract.steps.map((s) => ({
+                        role: s.role,
+                        task: s.task,
+                        depends_on: s.depends_on.length > 0 ? s.depends_on : undefined,
+                        tool_scope: s.tool_scope.length > 0 ? s.tool_scope : undefined,
+                        acceptance_criteria: s.acceptance_criteria ?? [],
+                        stop_condition: s.stop_condition && s.stop_condition.length > 0 ? s.stop_condition : undefined,
+                        expected_output_class: s.expected_output_class,
+                        expected_artifacts: s.expected_artifacts,
+                        allowed_tools: s.allowed_tools,
+                        forbidden_patterns: s.forbidden_patterns,
+                        required_evidence_refs: s.required_evidence_refs,
+                        structural_edit_plan_required: s.structural_edit_plan_required,
+                        structural_edit_waiver: s.structural_edit_waiver,
+                    })),
+                    plan_source: contract.plan_source,
+                };
+            }
+        }
+    }
+    else {
+        return {
+            plan_id: "unknown",
+            ok: false,
+            score: 0,
+            blocking_findings: ["No plan_id or proposal supplied."],
+            soft_findings: [],
+        };
+    }
+    if (!proposal) {
+        return {
+            plan_id: resolvedPlanId,
+            ok: false,
+            score: 0,
+            blocking_findings: [`Plan ${resolvedPlanId} not found in proposal cache or trace map.`],
+            soft_findings: [],
+        };
+    }
+    const planProposal = {
+        intent_summary: proposal.intent_summary,
+        success_criteria: proposal.success_criteria,
+        steps: proposal.steps,
+    };
+    const verdict = validatePlanShape(resolvedPlanId, planProposal);
+    // Persist transition record
+    try {
+        await withLocalModelRuntimeRepository(resolveWorkspaceRoot(), async (repo) => {
+            await repo.appendTransitionRecord({
+                subject_kind: "plan_proposal",
+                subject_id: resolvedPlanId,
+                from: "proposed",
+                to: verdict.ok ? "validated" : "rejected",
+                reason: verdict.ok
+                    ? `Plan validated with score ${verdict.score}`
+                    : `Plan rejected: ${verdict.blocking_findings.join("; ")}`,
+                reason_code: verdict.ok ? "plan_validated" : "plan_rejected",
+                evidence_refs: [],
+            });
+        });
+    }
+    catch {
+        // Non-fatal
+    }
+    // Emit Vericify process post
+    await appendVericifyProcessPostSafe({
+        run_id: "workspace:current",
+        agent_id: "ace-planner",
+        kind: "plan_quality_assessment",
+        summary: verdict.ok
+            ? `Plan ${resolvedPlanId} passed quality gate (score=${verdict.score})`
+            : `Plan ${resolvedPlanId} failed quality gate (score=${verdict.score}): ${verdict.blocking_findings.join("; ")}`,
+        tool_refs: ["validate_plan"],
+        evidence_refs: [resolvedPlanId],
+    });
+    return { plan_id: resolvedPlanId, ...verdict };
+}
+export function loadAcceptanceTraceContract(plan_id) {
+    try {
+        const raw = safeRead("agent-state/ACCEPTANCE_TRACE_MAP.json");
+        if (!raw || raw.startsWith("[FILE NOT FOUND]") || raw.startsWith("[ACCESS DENIED]")) {
+            return undefined;
+        }
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object")
+            return undefined;
+        const record = parsed;
+        if ("contracts" in record && record.contracts && typeof record.contracts === "object") {
+            const contract = record.contracts[plan_id];
+            return contract && contract.plan_id === plan_id ? contract : undefined;
+        }
+        const contract = record;
+        if (contract.plan_id !== plan_id)
+            return undefined;
+        return contract;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function persistAcceptanceTraceMapWithContract(input) {
+    const current = safeRead("agent-state/ACCEPTANCE_TRACE_MAP.json");
+    const generated_at = new Date().toISOString();
+    let nextMap = {
+        version: 1,
+        generated_at,
+        contracts: {},
+    };
+    if (current && !current.startsWith("[FILE NOT FOUND]") && !current.startsWith("[ACCESS DENIED]")) {
+        try {
+            const parsed = JSON.parse(current);
+            if (parsed && typeof parsed === "object" && "contracts" in parsed) {
+                const existing = parsed;
+                nextMap = {
+                    ...existing,
+                    generated_at,
+                    contracts: { ...(existing.contracts ?? {}) },
+                };
+            }
+            else if (parsed && typeof parsed === "object" && "plan_id" in parsed) {
+                const existing = parsed;
+                nextMap.contracts[existing.plan_id] = existing;
+            }
+        }
+        catch {
+            // keep the new map shape and overwrite corrupted content
+        }
+    }
+    nextMap.contracts[input.plan_id] = {
+        version: 1,
+        generated_at,
+        plan_id: input.plan_id,
+        task: input.task,
+        plan_source: input.plan_source,
+        intent_summary: input.intent_summary,
+        success_criteria: input.success_criteria,
+        validation_verdict: input.validation_verdict,
+        policies: input.policies,
+        steps: input.steps.map(enrichContractStep),
+    };
+    nextMap = {
+        ...nextMap,
+        plan_id: input.plan_id,
+        task: input.task,
+        plan_source: input.plan_source,
+        intent_summary: input.intent_summary,
+        success_criteria: input.success_criteria,
+        validation_verdict: input.validation_verdict,
+        policies: input.policies,
+        steps: input.steps.map(enrichContractStep),
+    };
+    return safeWriteAsync("agent-state/ACCEPTANCE_TRACE_MAP.json", JSON.stringify(nextMap, null, 2));
+}
+//# sourceMappingURL=plan-proposal.js.map