@voybio/ace-swarm 0.2.5 → 2.4.1

package/dist/tools-agent.js

@@ -2,20 +2,22 @@
  * Agent, skill, kernel, and task-pack tool registrations.
  */
 import { z } from "zod";
-import { ALL_AGENTS, COMPOSABLE_AGENTS, SWARM_AGENTS, SWARM_SUBAGENT_MAP, classifyPathSource, getAgentInstructionPath, getAgentManifestPath, getKernelArtifactPath, isSwarmRole, listAvailableSkills, readAgentInstructions, readAgentManifest, readKernelArtifact, readSkillInstructions, readTaskArtifact, resolveWorkspaceRoot, resolveWritableTaskPath, safeWrite, } from "./helpers.js";
+import { ALL_AGENTS, COMPOSABLE_AGENTS, SWARM_AGENTS, SWARM_SUBAGENT_MAP, classifyPathSource, getAgentInstructionPath, getAgentManifestPath, getKernelArtifactPath, isSwarmRole, listAvailableSkills, readAgentInstructions, readAgentManifest, readKernelArtifact, readSkillInstructions, readTaskArtifact, resolveWorkspaceRoot, resolveWritableTaskPath, safeWriteAsync, } from "./helpers.js";
 import { loadRuntimeProfile, readRuntimePromptTemplate, readRuntimeProfileState, validateRuntimeProfileContent, } from "./runtime-profile.js";
 import { getUnattendedSession, listUnattendedSessions, startUnattendedSession, stopUnattendedSession, validateRuntimeExecutorSessionRegistryContent, waitForUnattendedSession, } from "./runtime-executor.js";
 import { executeRuntimeTool, listRuntimeToolSpecs, loadRuntimeToolRegistry, validateRuntimeToolRegistryContent, } from "./runtime-tool-specs.js";
-import { createWorkspaceSession, listWorkspaceSessions, removeWorkspaceSession, resolveRuntimeWorkspaceRoot, validateManagedWorkspacePath, } from "./workspace-manager.js";
+import { createWorkspaceSessionAsync, listWorkspaceSessions, removeWorkspaceSession, resolveRuntimeWorkspaceRoot, validateManagedWorkspacePath, } from "./workspace-manager.js";
 import { getTrackerAdapter, listTrackerAdapterKinds, loadTrackerSnapshot, validateTrackerSnapshotContent, } from "./tracker-adapters.js";
 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 {};
@@ -52,6 +54,11 @@ function extractToolTextContent(result) {
         .filter(Boolean)
         .join("\n");
 }
+function didExecuteGatesPass(result) {
+    if (Boolean(result?.isError))
+        return false;
+    return !extractToolTextContent(result).trimStart().startsWith("❌");
+}
 function mapRoleToTaskType(role) {
     switch (role) {
         case "vos":
@@ -71,9 +78,268 @@ 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}`;
+}
+function isShipBoundaryTask(task) {
+    return /\b(ship|release|promot(?:e|ion)|land|merge)\b/i.test(task);
+}
+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();
+    const normalized = steps.map((step, index) => {
+        const id = `explicit-${index + 1}`;
+        originalIdByLabel.set(stepLabel(index), id);
+        return {
+            ...step,
+            id,
+            depends_on_ids: [...(step.depends_on ?? [])],
+        };
+    });
+    for (const step of normalized) {
+        step.depends_on_ids = step.depends_on_ids.map((dependency) => originalIdByLabel.get(dependency) ?? dependency);
+    }
+    let insertedResearch = false;
+    for (let index = 0; index < normalized.length; index += 1) {
+        const step = normalized[index];
+        if (step.role !== "spec")
+            continue;
+        const hasResearchBefore = normalized.slice(0, index).some((candidate) => candidate.role === "research");
+        if (hasResearchBefore)
+            continue;
+        const researchId = `auto-research-${index + 1}`;
+        normalized.splice(index, 0, {
+            id: researchId,
+            role: "research",
+            task: `Validate source-backed claims and gather evidence before spec work: ${step.task}`,
+            tool_scope: ["recall_context", "read_workspace_file", "build_continuity_packet"],
+            depends_on_ids: [],
+        });
+        step.depends_on_ids = Array.from(new Set([researchId, ...step.depends_on_ids]));
+        insertedResearch = true;
+        index += 1;
+    }
+    const shipFanoutEnabled = isShipBoundaryTask(task) || normalized.some((step) => isShipBoundaryTask(step.task));
+    if (shipFanoutEnabled) {
+        const hasReviewRole = normalized.some((step) => step.role === "skeptic");
+        const hasSecurityRole = normalized.some((step) => step.role === "security");
+        const hasQaRole = normalized.some((step) => step.role === "qa");
+        const hasReleaseRole = normalized.some((step) => step.role === "release");
+        const lastImplementation = [...normalized].reverse().find((step) => isImplementationRole(step.role)) ?? normalized.at(-1);
+        const implementationDependency = lastImplementation ? [lastImplementation.id] : [];
+        const fanoutStepIds = [];
+        if (!hasReviewRole) {
+            const reviewId = `auto-review-${normalized.length + 1}`;
+            normalized.push({
+                id: reviewId,
+                role: "skeptic",
+                task: `Review ship readiness for: ${task}`,
+                tool_scope: ["execute_gates", "validate_framework"],
+                depends_on_ids: implementationDependency,
+            });
+            fanoutStepIds.push(reviewId);
+        }
+        if (!hasSecurityRole) {
+            const securityId = `auto-security-${normalized.length + 1}`;
+            normalized.push({
+                id: securityId,
+                role: "security",
+                task: `Assess security readiness for: ${task}`,
+                tool_scope: ["execute_gates", "validate_framework"],
+                depends_on_ids: implementationDependency,
+            });
+            fanoutStepIds.push(securityId);
+        }
+        if (!hasQaRole) {
+            const qaId = `auto-qa-${normalized.length + 1}`;
+            normalized.push({
+                id: qaId,
+                role: "qa",
+                task: `Validate ship readiness for: ${task}`,
+                tool_scope: ["run_tests", "execute_gates", "git_diff"],
+                depends_on_ids: implementationDependency,
+            });
+            fanoutStepIds.push(qaId);
+        }
+        if (!hasReleaseRole && fanoutStepIds.length > 0) {
+            normalized.push({
+                id: `auto-release-${normalized.length + 1}`,
+                role: "release",
+                task: `Finalize ship decision for: ${task}`,
+                tool_scope: ["git_status", "execute_gates", "validate_framework"],
+                depends_on_ids: fanoutStepIds,
+            });
+        }
+    }
+    const finalIdByInternal = new Map();
+    normalized.forEach((step, index) => {
+        finalIdByInternal.set(step.id, stepLabel(index));
+    });
+    return {
+        planSource: "explicit_steps",
+        steps: normalized.map((step) => ({
+            role: step.role,
+            task: step.task,
+            depends_on: step.depends_on_ids.length > 0
+                ? step.depends_on_ids.map((dependency) => finalIdByInternal.get(dependency) ?? dependency)
+                : 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,
+    };
+}
+async function normalizeOrchestratorPlanSteps(task, steps, sessionId) {
+    if (!Array.isArray(steps) || steps.length === 0) {
+        const normalization = await buildOrchestratorSteps(task, sessionId);
+        return { planSource: normalization.planSource, normalization };
+    }
+    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 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, idx) => ({
+            step_id: step.step_id,
+            role: step.role,
+            task: step.task,
+            depends_on: step.depends_on ?? [],
+            tool_scope: step.tool_scope ?? [],
+            verification_role: step.role === "coders" || step.role === "builder"
+                ? "qa"
+                : 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,
+        })),
+    });
 }
 function appendUniqueNote(target, note) {
     if (!target.includes(note)) {
@@ -116,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();
@@ -282,6 +807,45 @@ export function registerAgentTools(server) {
             ],
         };
     });
+    server.tool("get_transition_log", "Read the transition log for a session. Answers 'why stopped?', 'what changed?', and 'what evidence caused it?' from the ACE transition record store.", {
+        session_id: z.string().describe("Session ID to read transitions for"),
+        limit: z.number().int().positive().optional().default(20).describe("Max transitions to return (default: 20)"),
+    }, async ({ session_id, limit }) => {
+        try {
+            const transitions = await withLocalModelRuntimeRepository(resolveWorkspaceRoot(), (repo) => repo.getTransitionLog(session_id, limit ?? 20));
+            return {
+                content: [{ type: "text", text: JSON.stringify(transitions, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error reading transition log: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("get_capability_snapshot", "Read the capability snapshot for a specific turn. Shows which tools were available, their cost class, and any unavailable tools with reasons.", {
+        session_id: z.string().describe("Session ID"),
+        turn_number: z.number().int().positive().describe("Turn number"),
+    }, async ({ session_id, turn_number }) => {
+        try {
+            const snapshot = await withLocalModelRuntimeRepository(resolveWorkspaceRoot(), (repo) => repo.getCapabilitySnapshot(session_id, turn_number));
+            if (!snapshot) {
+                return {
+                    content: [{ type: "text", text: `No capability snapshot found for session ${session_id} turn ${turn_number}` }],
+                };
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(snapshot, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error reading capability snapshot: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
     server.tool("validate_runtime_profile", "Validate ACE runtime profile markdown content or the current ACE_WORKFLOW.md file", {
         content: z
             .string()
@@ -493,7 +1057,19 @@ export function registerAgentTools(server) {
             .boolean()
             .optional()
             .describe("If false, keep the managed workspace session after completion"),
-    }, async ({ task, context_json, workspace_name, workspace_path, objective_id, tracker_item_id, max_turns, turn_timeout_ms, auto_cleanup, }) => {
+        emit_to: z
+            .array(z.enum(["tui", "tracker", "handoff", "vericify"]))
+            .optional()
+            .describe("Output emission targets for this session. Defaults to ['tui', 'vericify']."),
+        silent_unless_blocked: z
+            .boolean()
+            .optional()
+            .describe("If true, turns that produce no tool calls are classified as no_op_success and do not emit."),
+        require_approval_before_emit: z
+            .boolean()
+            .optional()
+            .describe("If true, require operator approval before emitting meaningful_completion output."),
+    }, async ({ task, context_json, workspace_name, workspace_path, objective_id, tracker_item_id, max_turns, turn_timeout_ms, auto_cleanup, emit_to, silent_unless_blocked, require_approval_before_emit, }) => {
         const result = await startUnattendedSession({
             task,
             context: parseOptionalJsonObject(context_json),
@@ -504,6 +1080,9 @@ export function registerAgentTools(server) {
             max_turns,
             turn_timeout_ms,
             auto_cleanup,
+            emit_to,
+            silent_unless_blocked,
+            require_approval_before_emit,
         });
         return {
             content: [
@@ -557,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"),
@@ -578,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()
@@ -594,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,
@@ -616,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}`,
@@ -646,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({
@@ -664,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()
@@ -716,27 +1388,53 @@ export function registerAgentTools(server) {
         const effectiveWorkspaceRoot = runtime?.workspaceRoot ??
             (workspace_root ? resolveRuntimeWorkspaceRoot(workspace_root) : resolveWorkspaceRoot());
         const sessionId = typeof extra?.sessionId === "string" ? extra.sessionId : undefined;
-        const planSource = Array.isArray(steps) && steps.length > 0 ? "explicit_steps" : "orchestrator_default_step";
-        const planSteps = Array.isArray(steps) && steps.length > 0
-            ? steps
-            : await buildOrchestratorSteps(task, sessionId);
+        const { planSource, normalization } = await normalizeOrchestratorPlanSteps(task, steps, sessionId);
         const plan = createTaskPlan({
             task,
-            steps: planSteps,
+            steps: normalization.steps,
             execution_mode: execution_mode ?? "sequential",
         });
+        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;
         const fallbackHandoffPrefix = `LOCAL-${plan.plan_id}-`;
         const vericifyWarnings = [];
+        const appendSessionPlanTransition = async (stepId, from, to, reason, reasonCode) => {
+            if (!sessionId)
+                return;
+            await withLocalModelRuntimeRepository(effectiveWorkspaceRoot, async (repo) => {
+                const step = plan.steps.find((candidate) => candidate.step_id === stepId);
+                if (!step)
+                    return;
+                await repo.appendTransitionRecord({
+                    session_id: sessionId,
+                    subject_kind: "plan_step",
+                    subject_id: `${plan.plan_id}/${step.step_id}`,
+                    from,
+                    to,
+                    reason,
+                    reason_code: reasonCode,
+                    evidence_refs: step.tool_scope ?? [],
+                });
+            }).catch(() => undefined);
+        };
         const supervised = await superviseTaskPlan(plan, {
             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,
@@ -775,12 +1473,29 @@ export function registerAgentTools(server) {
                     note,
                 }, sessionId);
             },
-            amendPlan({ plan: activePlan, step, result }) {
-                return buildDefaultOrchestratorAmendment({
+            async amendPlan({ plan: activePlan, step, result }) {
+                await appendSessionPlanTransition(step.step_id, "running", step.status, `Plan step ${step.step_id} ${step.status}: ${result.summary}`, step.status === "done"
+                    ? "step_completed"
+                    : step.status === "blocked"
+                        ? "step_blocked"
+                        : "step_failed");
+                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({
@@ -793,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,
@@ -807,7 +1550,7 @@ export function registerAgentTools(server) {
             async executeGates() {
                 const result = await executeAceInternalTool("execute_gates", {}, sessionId);
                 return {
-                    ok: !Boolean(result?.isError),
+                    ok: didExecuteGatesPass(result),
                     summary: extractToolTextContent(result),
                 };
             },
@@ -822,6 +1565,9 @@ export function registerAgentTools(server) {
                 }, sessionId);
             },
             async emitStatusEvent(event) {
+                if (event.step_id) {
+                    await appendSessionPlanTransition(event.step_id, "planned", "running", `Plan step ${event.step_id} started: ${event.summary}`, "step_started");
+                }
                 await executeAceInternalTool("emit_status_event", {
                     source_module: "capability-ops",
                     event_type: "ORCHESTRATOR_STEP",
@@ -831,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,
@@ -851,15 +1605,25 @@ 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."
-                            : null,
+                        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
+                                    ? "Ship fan-out enforcement added review, security, QA, and release coordination steps."
+                                    : null,
+                        trace_artifact_path: traceArtifactPath,
+                        engskills_imports: {
+                            inserted_research_before_spec: normalization.insertedResearch,
+                            ship_fanout_enabled: normalization.shipFanoutEnabled,
+                        },
                         plan: supervised.plan,
                         step_summaries,
                         handoff_ids: supervised.handoff_ids,
                         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),
                 },
@@ -1153,7 +1917,7 @@ export function registerAgentTools(server) {
             .optional()
             .describe("Optional hook timeout override in milliseconds"),
     }, async ({ workspace_name, workspace_path, source, objective_id, tracker_item_id, root, hooks_timeout_ms, }) => {
-        const result = createWorkspaceSession({
+        const result = await createWorkspaceSessionAsync({
             workspace_name,
             workspace_path,
             source,
@@ -1204,7 +1968,7 @@ export function registerAgentTools(server) {
             .optional()
             .describe("Optional hook timeout override in milliseconds"),
     }, async ({ session_id, workspace_path, root, hooks_timeout_ms }) => {
-        const result = removeWorkspaceSession({
+        const result = await removeWorkspaceSession({
             session_id,
             workspace_path,
             root,
@@ -1540,7 +2304,7 @@ export function registerAgentTools(server) {
             "",
         ].join("\n");
         const existing = readTaskArtifact("lessons");
-        const path = safeWrite(resolveWritableTaskPath("lessons"), `${existing}${entry}`);
+        const path = await safeWriteAsync(resolveWritableTaskPath("lessons"), `${existing}${entry}`);
         return {
             content: [{ type: "text", text: `✅ Lesson recorded in ${path}` }],
         };