@voybio/ace-swarm 2.4.0 → 2.4.1

package/dist/tools-agent.js

@@ -11,12 +11,13 @@ import { getTrackerAdapter, listTrackerAdapterKinds, loadTrackerSnapshot, valida
 import { refreshTrackerSnapshot } from "./tracker-sync.js";
 import { appendVericifyProcessPost, loadVericifyBridgeSnapshot, loadVericifyProcessPostLog, refreshVericifyBridgeSnapshot, validateVericifyBridgeSnapshotContent, validateVericifyProcessPostLogContent, } from "./vericify-bridge.js";
 import { getRoleTitle, ROLE_ENUM, KERNEL_KEY_ENUM, ROLE_TITLES } from "./shared.js";
-import { createDefaultModelBridgeClients, resolveLocalModelRuntime, runLocalModelTask, } from "./local-model-runtime.js";
+import { createDefaultModelBridgeClients, resolveLocalModelRuntime, resolveTier, runLocalModelTask, } from "./local-model-runtime.js";
 import { withLocalModelRuntimeRepository } from "./store/repositories/local-model-runtime-repository.js";
 import { executeAceInternalTool } from "./ace-internal-tools.js";
 import { ModelBridge } from "./model-bridge.js";
 import { getVericifyContextPacket, getVericifyDelta } from "./vericify-context.js";
-import { createTaskPlan, superviseTaskPlan, } from "./orchestrator-supervisor.js";
+import { proposePlan as proposePlanImpl, proposePlanDeterministic, validatePlan as validatePlanImpl, loadAcceptanceTraceContract as loadAcceptanceTraceContractImpl, persistAcceptanceTraceMapWithContract, } from "./plan-proposal.js";
+import { amendTaskPlan, createTaskPlan, superviseTaskPlan, } from "./orchestrator-supervisor.js";
 function parseOptionalJsonObject(raw) {
     if (!raw)
         return {};
@@ -77,6 +78,67 @@ function extractHandoffId(text) {
     const lineMatch = text.match(/handoff_id:\s*([A-Z0-9-]+)/i);
     return lineMatch?.[1];
 }
+export function formatStepTaskForBridge(step) {
+    const upstreamOutputs = step.upstream_outputs ?? [];
+    if (upstreamOutputs.length === 0) {
+        return step.task;
+    }
+    const renderedOutputs = upstreamOutputs
+        .map((output) => `- ${output.step_id}: ${output.result_summary || "[no summary]"}${output.evidence_refs.length > 0 ? ` (evidence: ${output.evidence_refs.join(", ")})` : ""}`)
+        .join("\n");
+    return [
+        step.task,
+        "",
+        "Upstream outputs:",
+        renderedOutputs,
+    ].join("\n");
+}
+// ── Re-export plan-proposal API ────────────────────────────────────────────
+export { loadAcceptanceTraceContractImpl as loadAcceptanceTraceContract };
+export { proposePlanImpl as proposePlan, validatePlanImpl as validatePlan };
+// ── proposalToSteps: maps PlanProposal steps to local PlannedStepInput ────
+function proposalToSteps(proposal) {
+    return proposal.steps.map((s) => ({
+        role: s.role,
+        task: s.task,
+        depends_on: s.depends_on && s.depends_on.length > 0 ? s.depends_on : undefined,
+        tool_scope: s.tool_scope && s.tool_scope.length > 0 ? s.tool_scope : 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,
+    }));
+}
+function stripPlanIdFromVerdict(verdict) {
+    return {
+        ok: verdict.ok,
+        score: verdict.score,
+        blocking_findings: [...verdict.blocking_findings],
+        soft_findings: [...verdict.soft_findings],
+    };
+}
+function proposalToNormalization(proposal, verdict) {
+    const acMap = new Map();
+    const stopConditionsMap = new Map();
+    proposal.steps.forEach((ps, idx) => {
+        acMap.set(stepLabel(idx), ps.acceptance_criteria ?? []);
+        stopConditionsMap.set(stepLabel(idx), ps.stop_condition ?? []);
+    });
+    return {
+        planSource: proposal.plan_source,
+        steps: proposalToSteps(proposal),
+        insertedResearch: false,
+        shipFanoutEnabled: false,
+        intentSummary: proposal.intent_summary,
+        successCriteria: proposal.success_criteria,
+        validationVerdict: stripPlanIdFromVerdict(verdict),
+        acceptanceCriteriaByStep: acMap,
+        stopConditionsByStep: stopConditionsMap,
+    };
+}
 function stepLabel(index) {
     return `step-${index + 1}`;
 }
@@ -87,8 +149,18 @@ function isImplementationRole(role) {
     return role === "coders" || role === "builder";
 }
 async function buildOrchestratorSteps(task, sessionId) {
-    void sessionId;
-    return [{ role: "orchestrator", task }];
+    // (a) propose a plan via the planner model
+    const proposal = await proposePlanImpl(task, sessionId);
+    // (b) validate the proposal
+    const verdict = await validatePlanImpl({ proposal, sessionId });
+    // (c) if ok, return validated steps with planner enrichment
+    if (verdict.ok && proposal.steps.length > 0) {
+        return proposalToNormalization(proposal, verdict);
+    }
+    // Deterministic fallback: still validate the floor before returning it.
+    const fallbackProposal = proposePlanDeterministic(task);
+    const fallbackVerdict = await validatePlanImpl({ proposal: fallbackProposal, sessionId });
+    return proposalToNormalization(fallbackProposal, fallbackVerdict);
 }
 function normalizeExplicitPlanSteps(steps, task) {
     const originalIdByLabel = new Map();
@@ -181,6 +253,7 @@ function normalizeExplicitPlanSteps(steps, task) {
         finalIdByInternal.set(step.id, stepLabel(index));
     });
     return {
+        planSource: "explicit_steps",
         steps: normalized.map((step) => ({
             role: step.role,
             task: step.task,
@@ -189,6 +262,13 @@ function normalizeExplicitPlanSteps(steps, task) {
                 : undefined,
             parallel_group: step.parallel_group,
             tool_scope: step.tool_scope,
+            expected_output_class: step.expected_output_class,
+            expected_artifacts: step.expected_artifacts,
+            allowed_tools: step.allowed_tools,
+            forbidden_patterns: step.forbidden_patterns,
+            required_evidence_refs: step.required_evidence_refs,
+            structural_edit_plan_required: step.structural_edit_plan_required,
+            structural_edit_waiver: step.structural_edit_waiver,
         })),
         insertedResearch,
         shipFanoutEnabled,
@@ -196,32 +276,49 @@ function normalizeExplicitPlanSteps(steps, task) {
 }
 async function normalizeOrchestratorPlanSteps(task, steps, sessionId) {
     if (!Array.isArray(steps) || steps.length === 0) {
-        return {
-            planSource: "orchestrator_default_step",
-            normalization: {
-                steps: await buildOrchestratorSteps(task, sessionId),
-                insertedResearch: false,
-                shipFanoutEnabled: false,
-            },
-        };
+        const normalization = await buildOrchestratorSteps(task, sessionId);
+        return { planSource: normalization.planSource, normalization };
     }
-    return {
-        planSource: "explicit_steps",
-        normalization: normalizeExplicitPlanSteps(steps, task),
+    const normalization = normalizeExplicitPlanSteps(steps, task);
+    // Run the same artifact/output-class gate that planner-derived steps go through.
+    const syntheticProposal = {
+        plan_id: `explicit-${Date.now()}`,
+        status: "planning",
+        intent_summary: task,
+        success_criteria: [],
+        steps: normalization.steps.map((s) => ({
+            role: s.role,
+            task: s.task,
+            depends_on: s.depends_on,
+            tool_scope: s.tool_scope,
+            acceptance_criteria: [],
+            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: "explicit_steps",
     };
+    const verdict = await validatePlanImpl({ proposal: syntheticProposal, sessionId });
+    normalization.validationVerdict = stripPlanIdFromVerdict(verdict);
+    return { planSource: "explicit_steps", normalization };
 }
 async function persistAcceptanceTraceMap(input) {
-    return safeWriteAsync("agent-state/ACCEPTANCE_TRACE_MAP.json", JSON.stringify({
-        version: 1,
-        generated_at: new Date().toISOString(),
+    return persistAcceptanceTraceMapWithContract({
         plan_id: input.plan.plan_id,
         task: input.task,
         plan_source: input.planSource,
+        intent_summary: input.normalization?.intentSummary,
+        success_criteria: input.normalization?.successCriteria,
+        validation_verdict: input.normalization?.validationVerdict,
         policies: {
             inserted_research_before_spec: input.insertedResearch,
             ship_fanout_enabled: input.shipFanoutEnabled,
         },
-        steps: input.plan.steps.map((step) => ({
+        steps: input.plan.steps.map((step, idx) => ({
             step_id: step.step_id,
             role: step.role,
             task: step.task,
@@ -232,8 +329,17 @@ async function persistAcceptanceTraceMap(input) {
                 : step.role === "spec"
                     ? "research"
                     : null,
+            acceptance_criteria: input.normalization?.acceptanceCriteriaByStep?.get(`step-${idx + 1}`),
+            stop_condition: input.normalization?.stopConditionsByStep?.get(`step-${idx + 1}`),
+            expected_output_class: step.expected_output_class,
+            expected_artifacts: step.expected_artifacts,
+            allowed_tools: step.allowed_tools,
+            forbidden_patterns: step.forbidden_patterns,
+            required_evidence_refs: step.required_evidence_refs,
+            structural_edit_plan_required: step.structural_edit_plan_required,
+            structural_edit_waiver: step.structural_edit_waiver,
         })),
-    }, null, 2));
+    });
 }
 function appendUniqueNote(target, note) {
     if (!target.includes(note)) {
@@ -276,6 +382,265 @@ function buildDefaultOrchestratorAmendment(input) {
         add_after_step_id: input.step.step_id,
     };
 }
+function isAcceptanceTraceContract(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return Array.isArray(candidate.steps);
+}
+const INTENT_STOPWORDS = new Set([
+    "the",
+    "and",
+    "for",
+    "with",
+    "this",
+    "that",
+    "step",
+    "step1",
+    "step2",
+    "step3",
+    "step4",
+    "step5",
+    "step6",
+    "step7",
+    "step8",
+    "step9",
+    "step10",
+    "complete",
+    "completed",
+    "validate",
+    "validation",
+    "implement",
+    "implementation",
+    "done",
+    "ready",
+]);
+function normalizeIntentText(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+function intentTokens(value) {
+    return normalizeIntentText(value)
+        .split(/\s+/)
+        .filter((token) => token.length > 2 && !INTENT_STOPWORDS.has(token));
+}
+function intentCriterionSatisfied(haystack, criterion) {
+    const normalizedHaystack = normalizeIntentText(haystack);
+    const tokens = intentTokens(criterion);
+    if (tokens.length === 0)
+        return false;
+    const hits = tokens.filter((token) => normalizedHaystack.includes(token)).length;
+    return hits >= Math.min(2, tokens.length) || hits / tokens.length >= 0.5;
+}
+function resultContractText(result) {
+    return [
+        result.summary,
+        JSON.stringify(result.tool_calls ?? []),
+        JSON.stringify(result.child_results ?? []),
+    ].join("\n");
+}
+const ARTIFACT_STUB_PATTERN = /\b(?:todo-only|placeholder|stub(?:bed|by)?|tbd|boilerplate(?:-only)?|scaffold(?:ing)?\s+(?:stub|only))\b/i;
+function isUiPlainTextContract(step, contractStep) {
+    const expected = contractStep.expected_output_class ?? inferContractClassFromStep(step);
+    return step.role === "ui" && expected === "plain_text_plan";
+}
+function validateUiTopicAnchor(input) {
+    if (!isUiPlainTextContract(input.step, input.contract_step)) {
+        return { ok: true };
+    }
+    const acceptanceCriteria = (input.contract_step.acceptance_criteria ?? []).filter((criterion) => typeof criterion === "string" && criterion.trim().length > 0);
+    if (acceptanceCriteria.length === 0) {
+        return { ok: true };
+    }
+    const outputText = resultContractText(input.result);
+    if (intentTokens(outputText).length < 4) {
+        return { ok: true };
+    }
+    const taskAnchored = intentCriterionSatisfied(outputText, input.step.task);
+    const matchedCriteria = acceptanceCriteria.filter((criterion) => intentCriterionSatisfied(outputText, criterion));
+    if (!taskAnchored && matchedCriteria.length === 0) {
+        return {
+            ok: false,
+            reason_code: "role_drift_ui_off_topic",
+            reason: `UI step ${input.step.step_id} drifted off topic instead of staying anchored to the requested plan.`,
+            uncovered_clauses: acceptanceCriteria,
+        };
+    }
+    return { ok: true };
+}
+function inferContractClassFromStep(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 requiresContract(step) {
+    if ((step.tool_scope ?? []).length > 0)
+        return true;
+    if (step.role === "coders" || step.role === "builder" || step.role === "qa")
+        return true;
+    return (step.tool_scope ?? []).some((tool) => /write|edit|safe_edit|astgrep|structural/i.test(tool));
+}
+function validateContractClass(input) {
+    const expected = input.contract_step.expected_output_class ?? inferContractClassFromStep(input.step);
+    const toolCalls = input.result.tool_calls ?? [];
+    const evidenceRefs = input.result.evidence_refs ?? [];
+    if (input.contract_step.allowed_tools?.length) {
+        const allowed = new Set(input.contract_step.allowed_tools);
+        const disallowed = toolCalls.find((call) => !allowed.has(call.tool));
+        if (disallowed) {
+            return {
+                ok: false,
+                reason_code: "bridge_output_malformed_json",
+                reason: `Tool ${disallowed.tool} is not allowed for ${input.step.step_id}.`,
+            };
+        }
+    }
+    if (expected === "qa_verdict" && toolCalls.some((call) => /write|edit|rewrite|safe_edit/i.test(call.tool))) {
+        return {
+            ok: false,
+            reason_code: "qa_rewrote_artifact",
+            reason: `QA step ${input.step.step_id} attempted a mutation tool.`,
+        };
+    }
+    if ((expected === "tool_envelope" || expected === "structural_edit_plan") && toolCalls.length === 0) {
+        return {
+            ok: false,
+            reason_code: "bridge_output_malformed_json",
+            reason: `Step ${input.step.step_id} expected a tool envelope but produced none.`,
+        };
+    }
+    if (expected === "code_artifact" || expected === "structural_edit_plan") {
+        const expectedArtifacts = (input.contract_step.expected_artifacts ?? []).filter((artifact) => artifact.required !== false);
+        const missingArtifacts = expectedArtifacts
+            .map((artifact) => artifact.path)
+            .filter((artifactPath) => !evidenceRefs.some((ref) => ref.includes(artifactPath)));
+        if (missingArtifacts.length > 0) {
+            return {
+                ok: false,
+                reason_code: "artifact_mismatch",
+                reason: `Step ${input.step.step_id} did not prove expected artifact evidence.`,
+                uncovered_clauses: missingArtifacts,
+            };
+        }
+    }
+    if (expected === "code_artifact") {
+        const mutationSignal = toolCalls.some((call) => /write|edit|patch|create|apply|safe_edit/i.test(call.tool)) || evidenceRefs.length > 0;
+        if (mutationSignal && ARTIFACT_STUB_PATTERN.test(resultContractText(input.result))) {
+            return {
+                ok: false,
+                reason_code: "coder_artifact_stub",
+                reason: `Step ${input.step.step_id} reported a stub or placeholder artifact instead of a real implementation.`,
+            };
+        }
+    }
+    const forbiddenPatterns = input.contract_step.forbidden_patterns ?? [];
+    const outputText = resultContractText(input.result);
+    const forbiddenHit = forbiddenPatterns.find((pattern) => outputText.includes(pattern));
+    if (forbiddenHit) {
+        return {
+            ok: false,
+            reason_code: "forbidden_pattern",
+            reason: `Step ${input.step.step_id} output matched a forbidden pattern.`,
+            uncovered_clauses: [forbiddenHit],
+        };
+    }
+    const missingEvidence = (input.contract_step.required_evidence_refs ?? [])
+        .filter((required) => !evidenceRefs.some((ref) => ref.includes(required)));
+    if (missingEvidence.length > 0) {
+        return {
+            ok: false,
+            reason_code: "required_evidence_missing",
+            reason: `Step ${input.step.step_id} is missing required evidence refs.`,
+            uncovered_clauses: missingEvidence,
+        };
+    }
+    return { ok: true };
+}
+export function verifyIntentAgainstContract(input) {
+    const contract = isAcceptanceTraceContract(input.intent_contract)
+        ? input.intent_contract
+        : loadAcceptanceTraceContractImpl(input.plan.plan_id);
+    if (!contract) {
+        if (requiresContract(input.step)) {
+            return {
+                outcome: "revisit_step",
+                reason: `No acceptance trace contract available for ${input.plan.plan_id}.`,
+                reason_code: "contract_missing",
+            };
+        }
+        return {
+            outcome: "ok",
+            reason: `No acceptance trace contract available for ${input.plan.plan_id}.`,
+        };
+    }
+    const contractStep = contract.steps.find((candidate) => candidate.step_id === input.step.step_id);
+    if (!contractStep) {
+        return {
+            outcome: requiresContract(input.step) ? "revisit_step" : "ok",
+            reason: `No acceptance trace step recorded for ${input.step.step_id}.`,
+            reason_code: requiresContract(input.step) ? "contract_missing" : undefined,
+        };
+    }
+    const classValidation = validateContractClass({
+        step: input.step,
+        result: input.result,
+        contract_step: contractStep,
+    });
+    if (!classValidation.ok) {
+        return {
+            outcome: "revisit_step",
+            reason: classValidation.reason ?? `Step ${input.step.step_id} failed contract-class validation.`,
+            reason_code: classValidation.reason_code,
+            uncovered_clauses: classValidation.uncovered_clauses,
+        };
+    }
+    const acceptanceCriteria = (contractStep?.acceptance_criteria ?? []).filter((criterion) => typeof criterion === "string" && criterion.trim().length > 0);
+    if (acceptanceCriteria.length === 0) {
+        return {
+            outcome: "ok",
+            reason: `No acceptance criteria recorded for ${input.step.step_id}.`,
+        };
+    }
+    const uiTopicValidation = validateUiTopicAnchor({
+        step: input.step,
+        result: input.result,
+        contract_step: contractStep,
+    });
+    if (!uiTopicValidation.ok) {
+        return {
+            outcome: "revisit_step",
+            reason: uiTopicValidation.reason ?? `Step ${input.step.step_id} drifted off topic.`,
+            reason_code: uiTopicValidation.reason_code,
+            uncovered_clauses: uiTopicValidation.uncovered_clauses,
+        };
+    }
+    const haystack = [
+        input.step.task,
+        input.result.summary,
+        JSON.stringify(input.result.tool_calls ?? []),
+        JSON.stringify(input.result.child_results ?? []),
+    ].join("\n");
+    const uncovered = acceptanceCriteria.filter((criterion) => !intentCriterionSatisfied(haystack, criterion));
+    if (uncovered.length === 0) {
+        return {
+            outcome: "ok",
+            reason: `Step ${input.step.step_id} satisfied persisted acceptance criteria.`,
+        };
+    }
+    return {
+        outcome: "revisit_step",
+        reason: `Step ${input.step.step_id} did not satisfy acceptance criteria yet.`,
+        reason_code: "contract_invalid",
+        uncovered_clauses: uncovered,
+    };
+}
 async function tryVericifyPacket(factory, onWarning) {
     try {
         return await factory();
@@ -771,6 +1136,56 @@ export function registerAgentTools(server) {
             ],
         };
     });
+    server.tool("propose_plan", "Use the ACE Planner role to decompose a task into a multi-step PlanProposal with intent_summary, success_criteria, per-step acceptance_criteria, and explicit stop conditions. On model failure, falls back to the deterministic goal compiler scaffold.", {
+        task: z.string().describe("The task to decompose into a plan"),
+        session_id: z.string().optional().describe("Optional session ID for transition record linkage"),
+    }, async ({ task, session_id }) => {
+        const proposal = await proposePlanImpl(task, session_id);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(proposal, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("validate_plan", "Run shape checks against a PlanProposal (coverage, verification chain, tool-scope realism, acceptance criteria presence, stop conditions visibility). Returns { ok, score, blocking_findings, soft_findings }. Persists a transition record and Vericify process post.", {
+        plan_id: z.string().optional().describe("ID of a previously proposed plan to validate"),
+        proposal: z
+            .object({
+            plan_id: z.string(),
+            status: z.literal("planning"),
+            intent_summary: z.string(),
+            success_criteria: z.array(z.string()),
+            steps: z.array(z.object({
+                role: z.string(),
+                task: z.string(),
+                depends_on: z.array(z.string()).optional(),
+                tool_scope: z.array(z.string()).optional(),
+                acceptance_criteria: z.array(z.string()),
+                stop_condition: z.array(z.string()).optional(),
+            })),
+            plan_source: z.string(),
+        })
+            .optional()
+            .describe("Inline proposal to validate; mutually exclusive with plan_id"),
+        session_id: z.string().optional().describe("Optional session ID for transition record linkage"),
+    }, async ({ plan_id, proposal, session_id }) => {
+        const result = await validatePlanImpl({
+            plan_id,
+            proposal: proposal,
+            sessionId: session_id,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
     server.tool("run_local_model", "Offload a governed ACE subtask to the provider-backed ACE bridge and return the result", {
         task: z.string().describe("Task to execute with the ACE model bridge"),
         role: ROLE_ENUM.optional().describe("Optional ACE role; defaults to orchestrator"),
@@ -792,6 +1207,10 @@ export function registerAgentTools(server) {
             .string()
             .optional()
             .describe("Optional model override; otherwise discovered from workspace/runtime context"),
+        model_class: z
+            .enum(["frontier", "mid", "small_local"])
+            .optional()
+            .describe("Optional capability class override; provider name alone is not used as capability authority"),
         base_url: z
             .string()
             .optional()
@@ -808,13 +1227,14 @@ export function registerAgentTools(server) {
             .string()
             .optional()
             .describe("Optional workspace root override; defaults to the active workspace"),
-    }, async ({ task, role, max_turns, tier, provider, model, base_url, ollama_url, tool_scope, workspace_root, }) => {
+    }, async ({ task, role, max_turns, tier, provider, model, model_class, base_url, ollama_url, tool_scope, workspace_root, }) => {
         const delegated = await runLocalModelTask({
             task,
             role,
             workspaceRoot: workspace_root,
             provider,
             model,
+            modelClass: model_class,
             baseUrl: base_url,
             ollamaUrl: ollama_url,
             maxTurns: max_turns,
@@ -830,6 +1250,9 @@ export function registerAgentTools(server) {
                         `- role: ${delegated.role}`,
                         `- provider: ${delegated.runtime.provider}`,
                         `- model: ${delegated.runtime.model}`,
+                        `- model_class: ${delegated.policy.model_class}`,
+                        `- tier: ${delegated.policy.tier}`,
+                        `- mutation_lane: ${delegated.policy.mutation_lane}`,
                         `- workspace: ${delegated.runtime.workspaceRoot}`,
                         `- status: ${delegated.result.status}`,
                         `- turns: ${delegated.result.turns}`,
@@ -860,7 +1283,7 @@ export function registerAgentTools(server) {
             ],
         };
     });
-    server.tool("run_orchestrator", "Execute a supervised plan via model bridge child runs; when steps are omitted, the plan starts with ACE-Orchestrator", {
+    server.tool("run_orchestrator", "Execute a supervised plan via model bridge child runs; when steps are omitted, the plan is compiled through the deterministic goal scaffold first", {
         task: z.string().describe("The task to decompose and execute"),
         steps: z
             .array(z.object({
@@ -878,9 +1301,44 @@ export function registerAgentTools(server) {
                 .array(z.string())
                 .optional()
                 .describe("Optional ACE tool allowlist for the step"),
+            expected_output_class: z
+                .enum(["plain_text_plan", "tool_envelope", "code_artifact", "structural_edit_plan", "qa_verdict"])
+                .optional()
+                .describe("Optional expected output contract class for intent verification"),
+            expected_artifacts: z
+                .array(z.object({
+                path: z.string(),
+                required: z.boolean().optional(),
+                evidence_ref_kind: z.enum(["artifact", "diff", "hash", "test", "gate"]).optional(),
+            }))
+                .optional()
+                .describe("Optional artifact evidence expected from this step"),
+            allowed_tools: z
+                .array(z.string())
+                .optional()
+                .describe("Optional stricter tool allowlist for contract verification"),
+            forbidden_patterns: z
+                .array(z.string())
+                .optional()
+                .describe("Optional forbidden output substrings for contract verification"),
+            required_evidence_refs: z
+                .array(z.string())
+                .optional()
+                .describe("Optional evidence ref substrings required from this step"),
+            structural_edit_plan_required: z
+                .boolean()
+                .optional()
+                .describe("Require this code-mutating step to route through a structural edit plan"),
+            structural_edit_waiver: z
+                .object({
+                reason: z.string(),
+                evidence_ref: z.string(),
+            })
+                .optional()
+                .describe("Evidence-backed waiver when a code-mutating step cannot use structural edits"),
         }))
             .optional()
-            .describe("Pre-defined steps; if omitted, the orchestrator starts with a single ACE-Orchestrator step"),
+            .describe("Pre-defined steps; if omitted, the orchestrator compiles a deterministic goal scaffold first"),
         execution_mode: z
             .enum(["sequential", "scheduled"])
             .optional()
@@ -936,13 +1394,15 @@ export function registerAgentTools(server) {
             steps: normalization.steps,
             execution_mode: execution_mode ?? "sequential",
         });
-        const traceArtifactPath = await persistAcceptanceTraceMap({
+        let traceArtifactPath = await persistAcceptanceTraceMap({
             plan,
             task,
             planSource,
             insertedResearch: normalization.insertedResearch,
             shipFanoutEnabled: normalization.shipFanoutEnabled,
+            normalization,
         });
+        const intentContract = loadAcceptanceTraceContractImpl(plan.plan_id);
         const bridge = runtime
             ? new ModelBridge(createDefaultModelBridgeClients(runtime))
             : undefined;
@@ -971,9 +1431,10 @@ export function registerAgentTools(server) {
             async spawnStep(step) {
                 if (bridge && runtime) {
                     return bridge.spawn({
-                        task: step.task,
+                        task: formatStepTaskForBridge(step),
                         role: step.role,
                         workspace: runtime.workspaceRoot,
+                        tier: resolveTier(undefined, runtime.provider, runtime.model, step.role),
                         maxTurns: max_turns_per_step ?? 6,
                         provider: runtime.provider,
                         model: runtime.model,
@@ -1018,11 +1479,23 @@ export function registerAgentTools(server) {
                     : step.status === "blocked"
                         ? "step_blocked"
                         : "step_failed");
-                return buildDefaultOrchestratorAmendment({
+                const amendment = buildDefaultOrchestratorAmendment({
                     plan: activePlan,
                     step,
                     result,
                 });
+                if (!amendment)
+                    return undefined;
+                const amendedPlan = amendTaskPlan(activePlan, amendment);
+                traceArtifactPath = await persistAcceptanceTraceMap({
+                    plan: amendedPlan,
+                    task,
+                    planSource,
+                    insertedResearch: normalization.insertedResearch,
+                    shipFanoutEnabled: normalization.shipFanoutEnabled,
+                    normalization,
+                });
+                return amendedPlan;
             },
             async getVericifyContext() {
                 return tryVericifyPacket(() => getVericifyContextPacket({
@@ -1035,6 +1508,34 @@ export function registerAgentTools(server) {
                     workspaceRoot: effectiveWorkspaceRoot,
                 }), (message) => appendUniqueNote(vericifyWarnings, `Vericify delta unavailable for ${plan.plan_id}: ${message}`));
             },
+            async verifyIntent({ plan: activePlan, step, result, intent_contract }) {
+                const verification = verifyIntentAgainstContract({
+                    plan: activePlan,
+                    step,
+                    result,
+                    intent_contract: intent_contract ?? loadAcceptanceTraceContractImpl(activePlan.plan_id) ?? intentContract,
+                });
+                // Transition recording is deferred to recordIntentVerificationFailure so
+                // the supervisor can supply the correct from/to based on retry state.
+                return verification;
+            },
+            async replanForClauses({ uncovered_clauses }) {
+                if (!uncovered_clauses.length) {
+                    return undefined;
+                }
+                return {
+                    append_steps: [
+                        {
+                            role: "research",
+                            task: `Resolve uncovered acceptance clauses: ${uncovered_clauses.join("; ")}`,
+                            tool_scope: ["recall_context", "read_workspace_file", "build_continuity_packet"],
+                        },
+                    ],
+                };
+            },
+            async recordIntentVerificationFailure({ step, verification, from, to }) {
+                await appendSessionPlanTransition(step.step_id, from, to, verification.reason, verification.reason_code);
+            },
             async openCircuitBreaker(reason) {
                 await executeAceInternalTool("open_circuit_breaker", {
                     reason,
@@ -1076,6 +1577,14 @@ export function registerAgentTools(server) {
                 }, sessionId);
             },
         });
+        traceArtifactPath = await persistAcceptanceTraceMap({
+            plan: supervised.plan,
+            task,
+            planSource,
+            insertedResearch: normalization.insertedResearch,
+            shipFanoutEnabled: normalization.shipFanoutEnabled,
+            normalization,
+        });
         const step_summaries = supervised.plan.steps.map((step) => ({
             step_id: step.step_id,
             role: step.role,
@@ -1096,8 +1605,8 @@ export function registerAgentTools(server) {
                         runtime_warnings: runtimeWarnings,
                         workspace_root: effectiveWorkspaceRoot,
                         plan_source: planSource,
-                        planning_note: planSource === "orchestrator_default_step"
-                            ? "Auto-planning currently starts with ACE-Orchestrator. Pass explicit steps for multi-step orchestration."
+                        planning_note: planSource === "orchestrator_default_step" || planSource === "deterministic_fallback" || planSource === "planner_model"
+                            ? "Auto-planning now starts with a deterministic goal compiler scaffold; planner_model means the scaffold was refined."
                             : normalization.insertedResearch
                                 ? "Research was inserted ahead of spec work to require source-backed evidence before specification."
                                 : normalization.shipFanoutEnabled
@@ -1114,6 +1623,7 @@ export function registerAgentTools(server) {
                         job_ids: supervised.job_ids,
                         circuit_opened: supervised.circuit_opened,
                         final_gate: supervised.final_gate ?? null,
+                        plan_validation_verdict: normalization.validationVerdict ?? null,
                         vericify_warnings: vericifyWarnings,
                     }, null, 2),
                 },