@voybio/ace-swarm 0.1.0

package/dist/tools-framework.js

@@ -0,0 +1,1414 @@
+/**
+ * Framework tool registrations: bootstrap, status, config, routing,
+ * plus new run_tests and validate_framework tools.
+ */
+import { z } from "zod";
+import { bootstrapStoreWorkspace } from "./store/bootstrap-store.js";
+import { ACE_ROOT_REL, ACE_TASKS_ROOT_REL, ALL_MCP_CLIENTS, ALL_AGENTS, COMPOSABLE_AGENTS, SWARM_AGENTS, SWARM_SUBAGENT_MAP, WORKSPACE_ROOT, classifyPathSource, detectAssetDrift, getAllMcpServerConfigSnippets, getAgentInstructionPath, getAgentManifestPath, getKernelArtifactPath, getMcpClientInstallHint, getMcpServerConfigSnippet, getTaskArtifactPath, isSwarmRole, listAvailableSkills, normalizePathForValidation, safeRead, safeWrite, withFileLock, wsPath, } from "./helpers.js";
+import { getRoleTitle, MCP_CLIENT_ENUM, scoreDomains, } from "./shared.js";
+import { DEFAULT_LLAMA_CPP_MODEL, DEFAULT_OLLAMA_MODEL, } from "./tui/provider-discovery.js";
+import { refreshAstgrepIndex } from "./astgrep-index.js";
+import { scanWorkspaceDelta } from "./index-store.js";
+import { getOrRefreshKanbanSnapshot } from "./kanban.js";
+import { appendRunLedgerEntrySafe } from "./run-ledger.js";
+import { appendStatusEventSafe } from "./status-events.js";
+import { runTestSuite } from "./safe-edit.js";
+import { isGitRepo, gitStatus } from "./git-ops.js";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { auditPublicSurface } from "./public-surface.js";
+import { PROVENANCE_CRITICAL_EVENT_TYPES, validateArtifactManifestPayload, validateProvenanceLogContent, validateTealConfigContent, } from "./schemas.js";
+import { readAceTaskContractAssessment } from "./ace-autonomy.js";
+function getArtifactManifestEntries(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload))
+        return [];
+    const manifest = payload;
+    if (Array.isArray(manifest.artifacts)) {
+        return manifest.artifacts.filter((entry) => !!entry &&
+            typeof entry === "object" &&
+            typeof entry.artifact_id === "string" &&
+            typeof entry.checksum === "string" &&
+            typeof entry.evidence_ref === "string");
+    }
+    if (typeof manifest.artifact_id === "string" &&
+        typeof manifest.checksum === "string" &&
+        typeof manifest.evidence_ref === "string") {
+        return [manifest];
+    }
+    return [];
+}
+function readGateManifests(gatesDir) {
+    const files = readdirSync(gatesDir).filter((f) => f.endsWith(".json"));
+    const allGates = [];
+    for (const file of files) {
+        try {
+            const raw = readFileSync(resolve(gatesDir, file), "utf-8");
+            const gate = JSON.parse(raw);
+            if (gate.id)
+                allGates.push(gate);
+        }
+        catch {
+            /* skip corrupt manifests */
+        }
+    }
+    return allGates;
+}
+function evaluateGateTargets(targets) {
+    const results = [];
+    for (const gate of targets) {
+        if (gate.type === "executable" && gate.command.trim().length > 0) {
+            const testResult = runTestSuite(gate.command);
+            results.push({
+                id: gate.id,
+                type: gate.type,
+                ok: testResult.ok,
+                detail: testResult.ok
+                    ? `PASS (exit ${testResult.exit_code}, ${testResult.duration_ms}ms)`
+                    : `FAIL (exit ${testResult.exit_code}): ${testResult.output.slice(0, 500)}`,
+                invariant: gate.invariant,
+                evidence_requirement: gate.evidence_requirement,
+            });
+            continue;
+        }
+        if (gate.type === "artifact_scan") {
+            const evidenceReq = gate.evidence_requirement.trim();
+            const looksLikeProse = evidenceReq.includes(" ") &&
+                !/\.(md|json|ts|js|yaml|yml|ndjson|txt)\b/.test(evidenceReq) &&
+                !evidenceReq.includes("/");
+            const missing = [];
+            if (looksLikeProse) {
+                const knownArtifacts = [
+                    "STATUS.md",
+                    "EVIDENCE_LOG.md",
+                    "HANDOFF.json",
+                    "DECISIONS.md",
+                    "RISKS.md",
+                    "SCOPE.md",
+                    "TASK.md",
+                    "QUALITY_GATES.md",
+                    "SPEC_CONTRACT.json",
+                    "TEAL_CONFIG.md",
+                ];
+                const invariantLower = gate.invariant.toLowerCase();
+                const relevantArtifacts = knownArtifacts.filter((artifact) => invariantLower.includes(artifact.replace(/\.\w+$/, "").toLowerCase().replace(/_/g, " ")) || invariantLower.includes(artifact.toLowerCase()));
+                if (relevantArtifacts.length === 0) {
+                    missing.push(`(prose evidence cannot be auto-verified: "${evidenceReq.slice(0, 80)}")`);
+                }
+                else {
+                    for (const artifact of relevantArtifacts) {
+                        if (!existsSync(wsPath("agent-state", artifact))) {
+                            missing.push(artifact);
+                        }
+                    }
+                }
+            }
+            else {
+                const evidenceFiles = evidenceReq
+                    .split(/[+,&]/)
+                    .map((s) => s.trim())
+                    .filter(Boolean);
+                for (const ref of evidenceFiles) {
+                    const candidates = [wsPath("agent-state", ref), wsPath(ref)];
+                    const found = candidates.some((candidate) => existsSync(candidate));
+                    if (!found) {
+                        const asFile = ref.replace(/\s+/g, "_").replace(/[^a-zA-Z0-9_./-]/g, "");
+                        const fileFound = existsSync(wsPath("agent-state", asFile));
+                        if (!fileFound)
+                            missing.push(ref);
+                    }
+                }
+            }
+            results.push({
+                id: gate.id,
+                type: gate.type,
+                ok: missing.length === 0,
+                detail: missing.length === 0
+                    ? "PASS (all evidence artifacts present)"
+                    : `FAIL (missing evidence: ${missing.join(", ")})`,
+                invariant: gate.invariant,
+                evidence_requirement: gate.evidence_requirement,
+            });
+            continue;
+        }
+        if (gate.type === "manual_review") {
+            results.push({
+                id: gate.id,
+                type: gate.type,
+                ok: false,
+                detail: "PENDING — requires manual review (not auto-enforceable, blocking until reviewed)",
+                invariant: gate.invariant,
+                evidence_requirement: gate.evidence_requirement,
+            });
+            continue;
+        }
+        results.push({
+            id: gate.id,
+            type: gate.type ?? "unknown",
+            ok: false,
+            detail: "Unknown gate type or no command specified",
+            invariant: gate.invariant,
+            evidence_requirement: gate.evidence_requirement,
+        });
+    }
+    return results;
+}
+function buildAdversarialClaim(result) {
+    switch (result.type) {
+        case "executable":
+            return `Executable gate ${result.id} failed its invariant check.`;
+        case "artifact_scan":
+            return `Artifact evidence for gate ${result.id} is not sufficient to trust the invariant.`;
+        case "manual_review":
+            return `Gate ${result.id} still depends on human review before the invariant can be trusted.`;
+        default:
+            return `Gate ${result.id} could not be verified cleanly.`;
+    }
+}
+function inferRouteHint(result) {
+    if (result.type === "executable")
+        return "agent-builder";
+    if (result.type === "artifact_scan" &&
+        result.detail.toLowerCase().includes("prose evidence cannot be auto-verified")) {
+        return "agent-spec";
+    }
+    if (result.type === "artifact_scan")
+        return "agent-ops";
+    if (result.type === "manual_review")
+        return "agent-skeptic";
+    return undefined;
+}
+function buildAdversarialReview(results, reviewFocus) {
+    const candidates = results
+        .filter((result) => !result.ok)
+        .map((result) => ({
+        gate_id: result.id,
+        gate_type: result.type,
+        claim: buildAdversarialClaim(result),
+        detail: result.detail,
+        invariant: result.invariant,
+        evidence_requirement: result.evidence_requirement,
+        route_hint: inferRouteHint(result),
+    }));
+    const disproved = [];
+    const confirmed = [];
+    for (const finding of candidates) {
+        if (finding.gate_type === "manual_review") {
+            disproved.push({
+                ...finding,
+                reason: "Pending manual review alone is not enough to confirm an actionable defect.",
+            });
+            continue;
+        }
+        if (finding.gate_type === "artifact_scan" &&
+            finding.detail.toLowerCase().includes("prose evidence cannot be auto-verified")) {
+            disproved.push({
+                ...finding,
+                reason: "The evidence contract is too vague to confirm a defect without stronger artifacts.",
+            });
+            continue;
+        }
+        confirmed.push(finding);
+    }
+    return {
+        mode: "skeptic_adversarial",
+        focus: reviewFocus?.trim() || undefined,
+        candidates,
+        disproved,
+        confirmed,
+        summary: {
+            candidate_count: candidates.length,
+            disproved_count: disproved.length,
+            confirmed_count: confirmed.length,
+            actionable_gate_ids: confirmed.map((finding) => finding.gate_id),
+        },
+    };
+}
+async function appendEvidenceLogEntrySafe(review) {
+    const timestamp = new Date().toISOString();
+    const anchor = `#ts:${timestamp}`;
+    const evidenceRef = `agent-state/EVIDENCE_LOG.md${anchor}`;
+    return withFileLock("agent-state/EVIDENCE_LOG.md", () => {
+        const existing = safeRead("agent-state/EVIDENCE_LOG.md");
+        const seed = existing.startsWith("[FILE NOT FOUND]") || existing.startsWith("[ACCESS DENIED]")
+            ? "# EVIDENCE LOG\n\nAppend-only validation evidence.\n\n## Entries\n"
+            : existing.trimEnd();
+        const lines = [
+            "",
+            `[${timestamp}] Skeptic adversarial review via execute_gates`,
+            `- evidence_ref: ${anchor}`,
+            ...(review.focus ? [`- focus: ${review.focus}`] : []),
+            `- candidates: ${review.summary.candidate_count}`,
+            `- disproved: ${review.summary.disproved_count}`,
+            `- confirmed: ${review.summary.confirmed_count}`,
+            `- actionable_gate_ids: ${review.summary.actionable_gate_ids.length > 0
+                ? review.summary.actionable_gate_ids.join(", ")
+                : "none"}`,
+            "- bug_hunter_candidates:",
+            ...(review.candidates.length > 0
+                ? review.candidates.map((finding) => `  - ${finding.gate_id} [${finding.gate_type}]: ${finding.claim} (${finding.detail})`)
+                : ["  - none"]),
+            "- disprover_results:",
+            ...(review.disproved.length > 0
+                ? review.disproved.map((finding) => `  - ${finding.gate_id}: ${finding.reason ?? "candidate rejected"}`)
+                : ["  - none"]),
+            "- adjudicator_confirmed:",
+            ...(review.confirmed.length > 0
+                ? review.confirmed.map((finding) => {
+                    const route = finding.route_hint ? ` route_hint=${finding.route_hint}` : "";
+                    return `  - ${finding.gate_id}: ${finding.detail}.${route}`;
+                })
+                : ["  - none"]),
+        ];
+        const path = safeWrite("agent-state/EVIDENCE_LOG.md", `${seed}${lines.join("\n")}\n`);
+        return { path, evidenceRef };
+    });
+}
+export function registerFrameworkTools(server) {
+    // ── Routing (improved with weighted scoring) ──────────────────────
+    server.tool("route_task", "Determine which ACE agent(s) or skill should handle a task", {
+        description: z.string().describe("Describe the task or question"),
+        domain: z
+            .enum([
+            "venture",
+            "ux",
+            "engineering",
+            "mixed",
+            "research",
+            "unknown",
+        ])
+            .optional()
+            .describe("Known domain, or unknown for auto-detect"),
+    }, async ({ description, domain }) => {
+        const text = description.toLowerCase();
+        let detected = domain ?? "unknown";
+        // Weighted scoring replaces naive if/else chain
+        if (detected === "unknown") {
+            const { domain: scored } = scoreDomains(text);
+            detected = scored;
+        }
+        const routingMap = {
+            venture: {
+                swarm_agents: ["vos"],
+                subagents: [
+                    "astgrep",
+                    "research",
+                    "spec",
+                    "memory",
+                    "skeptic",
+                    "ops",
+                ],
+                pipeline: "VOS -> UI -> Coders (as needed) with composable Research/Spec/Skeptic/Ops support",
+                prompt: "ace-vos",
+            },
+            ux: {
+                swarm_agents: ["ui"],
+                subagents: [
+                    "astgrep",
+                    "research",
+                    "spec",
+                    "builder",
+                    "qa",
+                    "docs",
+                    "skeptic",
+                    "ops",
+                ],
+                pipeline: "UI -> Coders with composable Spec/Builder/QA and Skeptic/Ops sidecars",
+                prompt: "ace-ui",
+            },
+            engineering: {
+                swarm_agents: ["coders"],
+                subagents: [
+                    "astgrep",
+                    "spec",
+                    "builder",
+                    "qa",
+                    "docs",
+                    "security",
+                    "observability",
+                    "eval",
+                    "release",
+                    "skeptic",
+                    "ops",
+                ],
+                pipeline: "Coders with composable Spec -> Builder -> QA -> Docs and Skeptic/Ops guards",
+                prompt: "ace-coders",
+            },
+            mixed: {
+                swarm_agents: ["orchestrator"],
+                subagents: [...COMPOSABLE_AGENTS],
+                pipeline: "Orchestrator -> VOS/UI/Coders with full composable agent support",
+                prompt: "ace-orchestrator",
+            },
+            research: {
+                swarm_agents: ["orchestrator"],
+                subagents: [
+                    "astgrep",
+                    "research",
+                    "spec",
+                    "memory",
+                    "skeptic",
+                    "ops",
+                ],
+                pipeline: "Orchestrator -> Research/Spec with Skeptic/Ops governance",
+                skills: ["astgrep-index", "codemunch", "codesnipe"],
+                prompt: "ace-orchestrator",
+            },
+        };
+        const route = routingMap[detected] ?? routingMap.mixed;
+        const recommendedSkills = new Set(route.skills ?? []);
+        const recommendedSubagents = new Set(route.subagents);
+        const taskContract = readAceTaskContractAssessment();
+        const stateConflictRequested = text.includes("contradict") ||
+            text.includes("conflict") ||
+            text.includes("misalign") ||
+            text.includes("drift") ||
+            text.includes("blocked");
+        const requiresGovernance = detected === "mixed" || !taskContract.ok || stateConflictRequested;
+        const activeRoute = requiresGovernance ? routingMap.mixed : route;
+        if (text.includes("schema") || text.includes("contract")) {
+            recommendedSubagents.add("spec");
+            recommendedSkills.add("schema-forge");
+        }
+        if (text.includes("handoff")) {
+            recommendedSubagents.add("ops");
+            recommendedSkills.add("handoff-lint");
+        }
+        if (text.includes("state") || text.includes("status")) {
+            recommendedSubagents.add("astgrep");
+            recommendedSubagents.add("ops");
+            recommendedSubagents.add("skeptic");
+            recommendedSkills.add("state-auditor");
+        }
+        if (text.includes("ast-grep") ||
+            text.includes("index") ||
+            text.includes("discovery")) {
+            recommendedSubagents.add("astgrep");
+            recommendedSubagents.add("research");
+            recommendedSkills.add("astgrep-index");
+        }
+        if (text.includes("memory") || text.includes("context drift")) {
+            recommendedSubagents.add("memory");
+            recommendedSubagents.add("research");
+            recommendedSubagents.add("docs");
+            recommendedSkills.add("memory-curator");
+        }
+        if (text.includes("skill") &&
+            (text.includes("triage") ||
+                text.includes("trigger") ||
+                text.includes("frontmatter") ||
+                text.includes("portable") ||
+                text.includes("portability") ||
+                text.includes("adapter") ||
+                text.includes("overlay") ||
+                text.includes("claude") ||
+                text.includes("cursor") ||
+                text.includes("codex") ||
+                text.includes("antigravity") ||
+                text.includes("openai.yaml") ||
+                text.includes("openai yaml") ||
+                text.includes("metadata") ||
+                text.includes("canary"))) {
+            recommendedSubagents.add("research");
+            recommendedSubagents.add("spec");
+            recommendedSubagents.add("ops");
+            recommendedSkills.add("problem-triage");
+        }
+        if (text.includes("skill") && (text.includes("audit") || text.includes("readiness"))) {
+            recommendedSubagents.add("research");
+            recommendedSubagents.add("skeptic");
+            recommendedSubagents.add("ops");
+            recommendedSkills.add("skill-auditor");
+        }
+        if (text.includes("risk") || text.includes("threat")) {
+            recommendedSubagents.add("security");
+            recommendedSubagents.add("skeptic");
+            recommendedSubagents.add("ops");
+            recommendedSkills.add("risk-quant");
+        }
+        if (text.includes("eval") ||
+            text.includes("benchmark") ||
+            text.includes("regression")) {
+            recommendedSubagents.add("eval");
+            recommendedSubagents.add("qa");
+            recommendedSkills.add("eval-harness");
+        }
+        if (text.includes("incident") ||
+            text.includes("slo") ||
+            text.includes("outage")) {
+            recommendedSubagents.add("observability");
+            recommendedSubagents.add("ops");
+            recommendedSkills.add("incident-commander");
+        }
+        if (text.includes("release") ||
+            text.includes("rollback") ||
+            text.includes("promote")) {
+            recommendedSubagents.add("release");
+            recommendedSubagents.add("security");
+            recommendedSubagents.add("eval");
+            recommendedSubagents.add("observability");
+            recommendedSubagents.add("qa");
+            recommendedSubagents.add("docs");
+            recommendedSkills.add("release-sentry");
+        }
+        if (text.includes("review") ||
+            text.includes("landing") ||
+            text.includes("merge") ||
+            text.includes("pull request") ||
+            /\bpr\b/.test(text) ||
+            /\bci\b/.test(text)) {
+            recommendedSubagents.add("release");
+            recommendedSubagents.add("qa");
+            recommendedSubagents.add("ops");
+            recommendedSkills.add("landing-review-watcher");
+            recommendedSkills.add("release-sentry");
+        }
+        if (text.includes("build") ||
+            text.includes("code") ||
+            text.includes("implement") ||
+            text.includes("fix")) {
+            recommendedSubagents.add("builder");
+        }
+        if (requiresGovernance) {
+            recommendedSubagents.add("skeptic");
+            recommendedSubagents.add("ops");
+            recommendedSubagents.add("memory");
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "# Task Routing Decision",
+                        "",
+                        `**Task:** ${description}`,
+                        `**Detected Domain:** ${detected}`,
+                        `**Primary Swarm Agent(s):** ${activeRoute.swarm_agents
+                            .map((agent) => `ACE-${getRoleTitle(agent)}`)
+                            .join(", ")}`,
+                        "**Hierarchy Rule:** Top-level routing stays locked to ACE-Orchestrator, ACE-VOS, ACE-UI, or ACE-Coders. Composable agents are delegated specialists, not peer replacements.",
+                        `**Preflight Owner:** ACE-Orchestrator`,
+                        `**Task Contract:** ${taskContract.ok ? "aligned" : "attention required"}`,
+                        `**Composable Subagents (Universal):** ${[...COMPOSABLE_AGENTS].join(", ")}`,
+                        `**Recommended Delegated Subagents:** ${[...recommendedSubagents].join(", ")}`,
+                        `**Pipeline:** ${activeRoute.pipeline}`,
+                        `**Recommended Prompt:** ${activeRoute.prompt}`,
+                        recommendedSkills.size > 0
+                            ? `**Recommended Skills:** ${[...recommendedSkills].join(", ")}`
+                            : "",
+                        ...(!taskContract.ok
+                            ? [
+                                "",
+                                "## Preflight Risks",
+                                ...taskContract.files.map((entry) => `- ${entry.path}: ${entry.valid ? "ok" : entry.note}`),
+                                ...taskContract.blockers.map((entry) => `- blocker: ${entry}`),
+                            ]
+                            : []),
+                        "",
+                        "## Preflight Expectations",
+                        "1. Recall current ACE context from TASK, SCOPE, QUALITY_GATES, STATUS, HANDOFF, and EVIDENCE artifacts.",
+                        "2. Validate the ACE quartet before dispatching substantial work.",
+                        "3. Route ambiguity or contract drift through skeptic/validation before handoff.",
+                        "",
+                        "## Next Steps",
+                        `1. Activate prompt: \`${activeRoute.prompt}\``,
+                        "2. Run `validate_framework` and inspect current ACE state before cross-role dispatch.",
+                        "3. Load shared kernel context with `get_kernel_artifact` (`directive_kernel`, `agent_registry`)",
+                        "4. Generate a structured handoff with `create_handoff` only after preflight clears",
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                },
+            ],
+        };
+    });
+    // ── Bootstrap ─────────────────────────────────────────────────────
+    server.tool("bootstrap_state", "Bootstrap ACE framework files (state, tasks, instructions, skills, scripts, MCP configs, optional local LLM profile)", {
+        project_name: z
+            .string()
+            .optional()
+            .describe("Project name for MASTER_PLAN.md"),
+        force: z
+            .boolean()
+            .optional()
+            .describe("Overwrite existing scaffold files"),
+        include_mcp_config: z
+            .boolean()
+            .optional()
+            .describe("Write the minimal .vscode/mcp.json workspace bridge"),
+        include_client_config_bundle: z
+            .boolean()
+            .optional()
+            .describe("Write minimal workspace host stubs (AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md)"),
+        llm_provider: z
+            .enum(["ollama", "llama.cpp"])
+            .optional()
+            .describe("Optional local LLM profile provider to scaffold"),
+        ollama_model: z
+            .string()
+            .optional()
+            .describe("Model name for generated local profile (legacy field name kept for compatibility)"),
+        ollama_base_url: z
+            .string()
+            .optional()
+            .describe("Local runtime base URL for generated profile (legacy field name kept for compatibility)"),
+    }, async ({ project_name, force, include_mcp_config, include_client_config_bundle, llm_provider, ollama_model, ollama_base_url, }) => {
+        // Store-first bootstrap — initializes ace-state.zarr, bakes host bundles into store,
+        // and optionally materializes minimal workspace stubs.
+        const storeResult = await bootstrapStoreWorkspace({
+            workspaceRoot: WORKSPACE_ROOT,
+            projectName: project_name ?? undefined,
+            force,
+            includeMcpConfig: include_mcp_config,
+            includeClientConfigBundle: include_client_config_bundle,
+            llm: llm_provider ?? undefined,
+            model: ollama_model ?? undefined,
+            ollamaUrl: ollama_base_url ?? undefined,
+        });
+        const astIndex = refreshAstgrepIndex({
+            scope: ".",
+            append_evidence: true,
+            emit_event: true,
+            include_rep_corpus: true,
+        });
+        const delta = scanWorkspaceDelta({
+            path: ".",
+            depth: 8,
+            max_files: 25000,
+            include_hidden: false,
+            exclude: [
+                ".git",
+                "node_modules",
+                "dist",
+                "target",
+                ".venv",
+                "__pycache__",
+                ".DS_Store",
+            ],
+            file_entry_cap: 0,
+        });
+        const runLedger = await appendRunLedgerEntrySafe({
+            tool: "bootstrap_state",
+            category: "major_update",
+            message: "Bootstrapped ACE workspace state",
+            artifacts: [
+                `${ACE_ROOT_REL}/ace-state.zarr`,
+                `${ACE_TASKS_ROOT_REL}/todo.md`,
+                normalizePathForValidation(delta.index_path),
+                "agent-state/AST_GREP_INDEX.json",
+            ],
+            metadata: {
+                materialized: storeResult.materialized.length,
+                force: Boolean(force),
+                llm_provider: llm_provider ?? null,
+                llm_model: ollama_model ?? null,
+                llm_base_url: ollama_base_url ?? null,
+                indexed_files: delta.snapshot.file_count,
+                index_truncated: delta.truncated,
+                ast_index_scope: astIndex.scope,
+                ast_hotspot_files: astIndex.stats.hotspot_files,
+            },
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "# Bootstrap Complete",
+                        "",
+                        `Store: ${storeResult.storePath}`,
+                        `Agents baked: ${storeResult.agents}`,
+                        `Materialized files: ${storeResult.materialized.length}`,
+                        "",
+                        "## Discovery Index",
+                        `- path: ${delta.index_path}`,
+                        `- root: ${delta.snapshot.root}`,
+                        `- file_count: ${delta.snapshot.file_count}`,
+                        `- stored_file_count: ${delta.snapshot.stored_file_count}`,
+                        `- file_entry_cap: ${delta.snapshot.options.file_entry_cap}`,
+                        `- scanned_count: ${delta.scanned_count}`,
+                        `- truncated: ${delta.truncated ? "yes" : "no"}`,
+                        "",
+                        "## AST Discovery Index",
+                        `- scope: ${astIndex.scope}`,
+                        `- ast_grep_command: ${astIndex.astgrep_command ?? "unavailable"}`,
+                        `- hotspot_files: ${astIndex.stats.hotspot_files}`,
+                        `- language_profile_entries: ${astIndex.stats.language_profile_entries}`,
+                        `- json: ${astIndex.output_json_path}`,
+                        `- md: ${astIndex.output_md_path}`,
+                        "",
+                        "## Materialized",
+                        ...(storeResult.materialized.length > 0
+                            ? storeResult.materialized.map((p) => `- ${p}`)
+                            : ["- (none)"]),
+                        "",
+                        ...(llm_provider
+                            ? [
+                                "",
+                                "## Local LLM Profile",
+                                `- provider: ${llm_provider}`,
+                                `- model: ${ollama_model ?? (llm_provider === "llama.cpp" ? DEFAULT_LLAMA_CPP_MODEL : DEFAULT_OLLAMA_MODEL)}`,
+                                `- base_url: ${ollama_base_url ?? "discover via ace doctor --scan or set explicitly"}`,
+                                `- profile_path: ${storeResult.storePath}#state/runtime/llm_profile`,
+                                `- doctor_path: ${storeResult.storePath}#state/runtime/doctor_checks.md`,
+                            ]
+                            : []),
+                        "",
+                        "## Run Ledger",
+                        `- path: ${runLedger.path}`,
+                        `- entry: ${runLedger.entry.id}`,
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    // ── Framework Status ──────────────────────────────────────────────
+    server.tool("get_framework_status", "Inspect ACE framework wiring: agents, tasks, skills, and core state files", {}, async () => {
+        const swarmGroup = [...SWARM_AGENTS].join(", ");
+        const composableGroup = [...COMPOSABLE_AGENTS].join(", ");
+        const agentLines = ALL_AGENTS.flatMap((role) => {
+            const instructionPath = getAgentInstructionPath(role);
+            const manifestPath = getAgentManifestPath(role);
+            const group = isSwarmRole(role) ? "swarm" : "composable";
+            return [
+                `- ${role} [${group}]: instructions -> ${classifyPathSource(instructionPath)}${instructionPath ? ` (${instructionPath})` : ""}`,
+                `  manifest -> ${classifyPathSource(manifestPath)}${manifestPath ? ` (${manifestPath})` : ""}`,
+                isSwarmRole(role)
+                    ? `  subagents -> ${SWARM_SUBAGENT_MAP[role].join(", ")}`
+                    : `  available-to -> ${[...SWARM_AGENTS].join(", ")}`,
+            ];
+        });
+        const kernelKeys = ["directive_kernel", "agent_registry"];
+        const kernelLines = kernelKeys.map((key) => {
+            const path = getKernelArtifactPath(key);
+            return `- ${key}: ${classifyPathSource(path)}${path ? ` (${path})` : ""}`;
+        });
+        const taskKeys = [
+            "todo",
+            "role_tasks",
+            "cli_work_split",
+            "lessons",
+            "handoff_template",
+        ];
+        const taskLines = taskKeys.map((key) => {
+            const path = getTaskArtifactPath(key);
+            return `- ${key}: ${classifyPathSource(path)}${path ? ` (${path})` : ""}`;
+        });
+        const skills = listAvailableSkills();
+        const skillsLines = skills.map((skill) => `- ${skill.name}: ${skill.source} (${skill.path})`);
+        const stateChecks = [
+            "agent-state/TASK.md",
+            "agent-state/STATUS.md",
+            "agent-state/SCOPE.md",
+            "agent-state/QUALITY_GATES.md",
+            "agent-state/EVIDENCE_LOG.md",
+            "agent-state/DECISIONS.md",
+            "agent-state/RISKS.md",
+            "agent-state/TEAL_CONFIG.md",
+            "agent-state/PROVENANCE_LOG.md",
+            "agent-state/ARTIFACT_MANIFEST.json",
+            "agent-state/ACE_WORKFLOW.md",
+            "agent-state/runtime-workspaces.json",
+            "agent-state/runtime-tool-specs.json",
+            "agent-state/runtime-executor-sessions.json",
+            "agent-state/tracker-snapshot.json",
+            "agent-state/vericify/ace-bridge.json",
+            "agent-state/vericify/process-posts.json",
+            "agent-state/PUBLIC_SURFACE_REPORT.md",
+            "agent-state/HANDOFF.json",
+            "agent-state/STATUS_EVENTS.ndjson",
+            "agent-state/handoff-registry.json",
+            "agent-state/run-ledger.json",
+            "agent-state/index.json",
+            "agent-state/index-fingerprints.json",
+            "agent-state/AST_GREP_COMMANDS.md",
+            "agent-state/AST_GREP_INDEX.md",
+            "agent-state/AST_GREP_INDEX.json",
+            "agent-state/MODULES/schemas/ACE_RUNTIME_PROFILE.schema.json",
+            "agent-state/MODULES/schemas/WORKSPACE_SESSION_REGISTRY.schema.json",
+            "agent-state/MODULES/schemas/RUNTIME_TOOL_SPEC_REGISTRY.schema.json",
+            "agent-state/MODULES/schemas/RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json",
+            "agent-state/MODULES/schemas/TRACKER_SNAPSHOT.schema.json",
+            "agent-state/MODULES/schemas/VERICIFY_BRIDGE_SNAPSHOT.schema.json",
+            "agent-state/MODULES/schemas/VERICIFY_PROCESS_POST_LOG.schema.json",
+            "agent-state/todo-state.json",
+            "agent-state/job-queue.json",
+            "agent-state/job-locks.json",
+            "agent-state/scheduler-lease.json",
+            "agent-state/kanban.json",
+            "agent-state/kanban.html",
+        ];
+        const stateLines = stateChecks.map((relPath) => {
+            const abs = wsPath(relPath);
+            const exists = safeRead(relPath).startsWith("[FILE NOT FOUND]")
+                ? "missing"
+                : "ok";
+            return `- ${relPath}: ${exists} (${abs})`;
+        });
+        const kanban = getOrRefreshKanbanSnapshot("tool:get_framework_status");
+        const kanbanLine = `- kanban-counts: backlog=${kanban.counts.backlog}, blocked=${kanban.counts.blocked}, in_progress=${kanban.counts.in_progress}, gated=${kanban.counts.gated}, done=${kanban.counts.done}`;
+        // New: git status
+        const gitLine = isGitRepo()
+            ? (() => {
+                const gs = gitStatus();
+                return `- git: branch=${gs.branch}, clean=${gs.clean}`;
+            })()
+            : "- git: not a git repository";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "# ACE Framework Status",
+                        "",
+                        "## Agent Groups",
+                        `- swarm: ${swarmGroup}`,
+                        `- composable: ${composableGroup}`,
+                        "",
+                        "## Agent Artifacts",
+                        ...agentLines,
+                        "",
+                        "## Kernel Artifacts",
+                        ...kernelLines,
+                        "",
+                        "## Task Artifacts",
+                        ...taskLines,
+                        "",
+                        "## Skills",
+                        ...(skillsLines.length > 0 ? skillsLines : ["- none found"]),
+                        "",
+                        "## Core State",
+                        ...stateLines,
+                        kanbanLine,
+                        "",
+                        "## Version Control",
+                        gitLine,
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    // ── MCP Config ────────────────────────────────────────────────────
+    server.tool("get_mcp_config", "Get MCP client config snippet(s) for this package", {
+        client: MCP_CLIENT_ENUM.optional().describe("codex|vscode|claude|cursor|antigravity (default: vscode)"),
+        all: z
+            .boolean()
+            .optional()
+            .describe("Return snippets and install hints for all supported clients"),
+    }, async ({ client, all }) => {
+        if (all) {
+            const snippets = getAllMcpServerConfigSnippets();
+            const body = ALL_MCP_CLIENTS.map((name) => {
+                const fence = name === "codex" ? "toml" : "json";
+                return [
+                    `## ${name}`,
+                    "",
+                    `Install hint: ${getMcpClientInstallHint(name)}`,
+                    "",
+                    `\`\`\`${fence}`,
+                    snippets[name],
+                    "```",
+                ].join("\n");
+            }).join("\n\n");
+            return {
+                content: [
+                    { type: "text", text: `# MCP Client Configs\n\n${body}` },
+                ],
+            };
+        }
+        const selected = (client ?? "vscode");
+        const fence = selected === "codex" ? "toml" : "json";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `# MCP Config (${selected})`,
+                        "",
+                        `Install hint: ${getMcpClientInstallHint(selected)}`,
+                        "",
+                        `\`\`\`${fence}`,
+                        getMcpServerConfigSnippet(selected),
+                        "```",
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    // ── Run Tests (new P0 tool) ───────────────────────────────────────
+    server.tool("run_tests", "Execute the project test suite and report results", {
+        command: z
+            .string()
+            .optional()
+            .describe("Custom test command (auto-detected from package.json if omitted)"),
+    }, async ({ command }) => {
+        const result = runTestSuite(command);
+        appendStatusEventSafe({
+            source_module: "capability-safety",
+            event_type: result.ok ? "TESTS_PASSED" : "TESTS_FAILED",
+            status: result.ok ? "pass" : "fail",
+            summary: `Tests ${result.ok ? "passed" : "FAILED"} (exit ${result.exit_code}, ${result.duration_ms}ms)`,
+            payload: {
+                command: result.command,
+                exit_code: result.exit_code,
+                duration_ms: result.duration_ms,
+            },
+        });
+        const ledger = await appendRunLedgerEntrySafe({
+            tool: "run_tests",
+            category: result.ok ? "info" : "regression",
+            message: `Tests ${result.ok ? "passed" : "FAILED"}: ${result.command}`,
+            artifacts: [],
+            metadata: {
+                exit_code: result.exit_code,
+                duration_ms: result.duration_ms,
+                command: result.command,
+            },
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        result.ok ? "✅ Tests passed" : "❌ Tests FAILED",
+                        `Command: ${result.command}`,
+                        `Exit code: ${result.exit_code}`,
+                        `Duration: ${result.duration_ms}ms`,
+                        `Run ledger: ${ledger.path} (${ledger.entry.id})`,
+                        "",
+                        "```",
+                        result.output,
+                        "```",
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    // ── Validate Framework (new P1 tool) ──────────────────────────────
+    server.tool("validate_framework", "Run self-checks to detect drift between agent state, schemas, and filesystem", {}, async () => {
+        const checks = [];
+        // Check: required state files exist
+        const requiredFiles = [
+            "agent-state/TASK.md",
+            "agent-state/SCOPE.md",
+            "agent-state/QUALITY_GATES.md",
+            "agent-state/HANDOFF.json",
+            "agent-state/STATUS.md",
+            "agent-state/EVIDENCE_LOG.md",
+            "agent-state/DECISIONS.md",
+            "agent-state/RISKS.md",
+            "agent-state/TEAL_CONFIG.md",
+            "agent-state/PROVENANCE_LOG.md",
+            "agent-state/ARTIFACT_MANIFEST.json",
+            `${ACE_TASKS_ROOT_REL}/todo.md`,
+            `${ACE_TASKS_ROOT_REL}/role_tasks.md`,
+            `${ACE_TASKS_ROOT_REL}/lessons.md`,
+            `${ACE_ROOT_REL}/global-state/MASTER_PLAN.md`,
+        ];
+        for (const f of requiredFiles) {
+            const content = safeRead(f);
+            const exists = !content.startsWith("[FILE NOT FOUND]");
+            checks.push({
+                name: `state-file:${f}`,
+                ok: exists,
+                detail: exists ? "present" : "MISSING",
+            });
+        }
+        // Check: handoff registry parseable
+        const hrRaw = safeRead("agent-state/handoff-registry.json");
+        const hrOk = !hrRaw.startsWith("[FILE NOT FOUND]");
+        if (hrOk) {
+            try {
+                JSON.parse(hrRaw);
+                checks.push({
+                    name: "handoff-registry:parse",
+                    ok: true,
+                    detail: "valid JSON",
+                });
+            }
+            catch {
+                checks.push({
+                    name: "handoff-registry:parse",
+                    ok: false,
+                    detail: "CORRUPT JSON",
+                });
+            }
+        }
+        // Check: run-ledger parseable
+        const rlRaw = safeRead("agent-state/run-ledger.json");
+        if (!rlRaw.startsWith("[FILE NOT FOUND]")) {
+            try {
+                JSON.parse(rlRaw);
+                checks.push({
+                    name: "run-ledger:parse",
+                    ok: true,
+                    detail: "valid JSON",
+                });
+            }
+            catch {
+                checks.push({
+                    name: "run-ledger:parse",
+                    ok: false,
+                    detail: "CORRUPT JSON",
+                });
+            }
+        }
+        // Check: todo-state parseable
+        const tsRaw = safeRead("agent-state/todo-state.json");
+        if (!tsRaw.startsWith("[FILE NOT FOUND]")) {
+            try {
+                JSON.parse(tsRaw);
+                checks.push({
+                    name: "todo-state:parse",
+                    ok: true,
+                    detail: "valid JSON",
+                });
+            }
+            catch {
+                checks.push({
+                    name: "todo-state:parse",
+                    ok: false,
+                    detail: "CORRUPT JSON",
+                });
+            }
+        }
+        // Check: scheduler stores parseable
+        const schedulerStoreChecks = [
+            { rel: "agent-state/job-queue.json", name: "job-queue:parse" },
+            { rel: "agent-state/job-locks.json", name: "job-locks:parse" },
+            { rel: "agent-state/scheduler-lease.json", name: "scheduler-lease:parse" },
+        ];
+        for (const check of schedulerStoreChecks) {
+            const raw = safeRead(check.rel);
+            if (raw.startsWith("[FILE NOT FOUND]")) {
+                checks.push({
+                    name: check.name,
+                    ok: false,
+                    detail: "MISSING",
+                });
+                continue;
+            }
+            try {
+                JSON.parse(raw);
+                checks.push({
+                    name: check.name,
+                    ok: true,
+                    detail: "valid JSON",
+                });
+            }
+            catch {
+                checks.push({
+                    name: check.name,
+                    ok: false,
+                    detail: "CORRUPT JSON",
+                });
+            }
+        }
+        // Check: TEAL config has exactly one active YAML block
+        const tealRaw = safeRead("agent-state/TEAL_CONFIG.md");
+        if (!tealRaw.startsWith("[FILE NOT FOUND]")) {
+            const validation = validateTealConfigContent(tealRaw);
+            checks.push({
+                name: "teal-config:structure",
+                ok: validation.ok,
+                detail: validation.ok
+                    ? `valid (${validation.schema})`
+                    : validation.errors.join("; "),
+            });
+        }
+        // Check: provenance log contains canonical provenance fields
+        const provenanceRaw = safeRead("agent-state/PROVENANCE_LOG.md");
+        if (!provenanceRaw.startsWith("[FILE NOT FOUND]")) {
+            const validation = validateProvenanceLogContent(provenanceRaw);
+            checks.push({
+                name: "provenance-log:structure",
+                ok: validation.ok,
+                detail: validation.ok
+                    ? `valid (${validation.schema})`
+                    : validation.errors.join("; "),
+            });
+        }
+        // Check: artifact manifest exists and satisfies provenance contract
+        const artifactManifestRaw = safeRead("agent-state/ARTIFACT_MANIFEST.json");
+        let artifactManifestEntries = [];
+        if (!artifactManifestRaw.startsWith("[FILE NOT FOUND]")) {
+            try {
+                const parsed = JSON.parse(artifactManifestRaw);
+                const validation = validateArtifactManifestPayload(parsed);
+                checks.push({
+                    name: "artifact-manifest:schema",
+                    ok: validation.ok,
+                    detail: validation.ok
+                        ? `valid (${validation.schema})`
+                        : validation.errors.join("; "),
+                });
+                if (validation.ok) {
+                    artifactManifestEntries = getArtifactManifestEntries(parsed);
+                }
+            }
+            catch {
+                checks.push({
+                    name: "artifact-manifest:parse",
+                    ok: false,
+                    detail: "CORRUPT JSON",
+                });
+            }
+        }
+        if (artifactManifestEntries.length > 0 &&
+            !provenanceRaw.startsWith("[FILE NOT FOUND]")) {
+            const missingLinks = artifactManifestEntries.filter((entry) => !provenanceRaw.includes(entry.artifact_id) ||
+                !provenanceRaw.includes(entry.checksum) ||
+                !provenanceRaw.includes(entry.evidence_ref));
+            checks.push({
+                name: "provenance-log:manifest-linkage",
+                ok: missingLinks.length === 0,
+                detail: missingLinks.length === 0
+                    ? `all ${artifactManifestEntries.length} manifest entries linked in PROVENANCE_LOG.md`
+                    : `${missingLinks.length} manifest entries missing provenance links in PROVENANCE_LOG.md`,
+            });
+        }
+        const taskContract = readAceTaskContractAssessment();
+        checks.push({
+            name: "task-contract:quartet",
+            ok: taskContract.ok,
+            detail: taskContract.ok
+                ? taskContract.summary
+                : [
+                    ...taskContract.files.map((entry) => `${entry.path}=${entry.valid ? "ok" : entry.note}`),
+                    ...taskContract.blockers,
+                ].join("; "),
+        });
+        // Check: git status
+        checks.push({
+            name: "git-repo",
+            ok: isGitRepo(),
+            detail: isGitRepo() ? "initialized" : "NOT a git repo",
+        });
+        // ── Deep checks (P2 hardening) ─────────────────────────────────
+        // Check: module registry role coverage vs event emitters
+        const registryRaw = safeRead("agent-state/MODULES/registry.json");
+        if (!registryRaw.startsWith("[FILE NOT FOUND]")) {
+            try {
+                const registry = JSON.parse(registryRaw);
+                const registeredRoles = new Set(registry.roles ?? []);
+                const expectedEmitters = [
+                    "capability-safety",
+                    "capability-framework",
+                    "capability-git",
+                    "capability-astgrep",
+                    "capability-ops",
+                    "capability-memory",
+                ];
+                for (const emitter of expectedEmitters) {
+                    const found = registeredRoles.has(emitter);
+                    checks.push({
+                        name: `registry-role:${emitter}`,
+                        ok: found,
+                        detail: found ? "registered" : "MISSING from registry",
+                    });
+                }
+            }
+            catch {
+                checks.push({
+                    name: "registry:parse",
+                    ok: false,
+                    detail: "registry.json is corrupt",
+                });
+            }
+        }
+        // Check: asset drift detection
+        const drift = detectAssetDrift();
+        checks.push({
+            name: "asset-drift:total",
+            ok: drift.drifted === 0,
+            detail: drift.drifted === 0
+                ? `${drift.checked} files checked, no drift`
+                : `${drift.drifted}/${drift.checked} files drifted`,
+        });
+        if (drift.missing_runtime > 0) {
+            checks.push({
+                name: "asset-drift:missing-runtime",
+                ok: false,
+                detail: `${drift.missing_runtime} asset files missing from runtime workspace`,
+            });
+        }
+        // Check: handoff consistency (open handoffs have source files)
+        if (hrOk) {
+            try {
+                const registry = JSON.parse(hrRaw);
+                const handoffs = Object.values(registry.handoffs ?? {});
+                let openWithoutFile = 0;
+                for (const h of handoffs) {
+                    if ((h.status === "open" || h.status === "accepted") &&
+                        h.source_file) {
+                        const fileContent = safeRead(h.source_file);
+                        if (fileContent.startsWith("[FILE NOT FOUND]"))
+                            openWithoutFile++;
+                    }
+                }
+                checks.push({
+                    name: "handoff:source-file-integrity",
+                    ok: openWithoutFile === 0,
+                    detail: openWithoutFile === 0
+                        ? "all open handoffs have source files"
+                        : `${openWithoutFile} open handoffs reference missing source files`,
+                });
+            }
+            catch {
+                /* already caught above */
+            }
+        }
+        // Check: event provenance gaps in recent events.
+        // Scans for provenance-critical event types that are missing
+        // objective_id, decision_id, AND payload.evidence_ref (all three absent).
+        // The old _provenance_gap marker is obsolete — fail-closed enforcement
+        // now throws before such events are written, but legacy rows may exist.
+        const recentEventsRaw = safeRead("agent-state/STATUS_EVENTS.ndjson");
+        if (!recentEventsRaw.startsWith("[FILE NOT FOUND]")) {
+            const lines = recentEventsRaw.split("\n").filter((l) => l.trim());
+            const recentLines = lines.slice(Math.max(0, lines.length - 50));
+            let provenanceGaps = 0;
+            for (const line of recentLines) {
+                try {
+                    const ev = JSON.parse(line);
+                    const eventType = ev.event_type;
+                    if (!eventType || !PROVENANCE_CRITICAL_EVENT_TYPES.has(eventType))
+                        continue;
+                    const hasObj = typeof ev.objective_id === "string" && ev.objective_id.length > 0;
+                    const hasDec = typeof ev.decision_id === "string" && ev.decision_id.length > 0;
+                    const payload = ev.payload;
+                    const hasEv = typeof payload?.evidence_ref === "string" && payload.evidence_ref.length > 0;
+                    // Legacy gap detection: also flag the old marker for backward compat scan
+                    const hasLegacyGap = payload && payload._provenance_gap === true;
+                    if ((!hasObj && !hasDec && !hasEv) || hasLegacyGap)
+                        provenanceGaps++;
+                }
+                catch {
+                    /* skip */
+                }
+            }
+            checks.push({
+                name: "event-provenance:recent",
+                ok: provenanceGaps === 0,
+                detail: provenanceGaps === 0
+                    ? "no provenance gaps in recent critical events"
+                    : `${provenanceGaps} recent critical events missing provenance fields`,
+            });
+        }
+        const passed = checks.filter((c) => c.ok).length;
+        const failed = checks.filter((c) => !c.ok).length;
+        const allOk = failed === 0;
+        await appendStatusEventSafe({
+            source_module: "capability-framework",
+            event_type: "FRAMEWORK_VALIDATED",
+            status: allOk ? "pass" : "fail",
+            summary: `Framework validation: ${passed}/${checks.length} passed`,
+            objective_id: "framework-validation",
+            payload: { passed, failed, total: checks.length, evidence_ref: "agent-state/STATUS_EVENTS.ndjson" },
+        });
+        const ledger = await appendRunLedgerEntrySafe({
+            tool: "validate_framework",
+            category: allOk ? "info" : "regression",
+            message: `Framework validation: ${passed}/${checks.length} passed`,
+            artifacts: [],
+            metadata: { passed, failed },
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        allOk
+                            ? `✅ Framework validated: ${passed}/${checks.length} checks passed`
+                            : `⚠️ Framework issues: ${failed}/${checks.length} checks failed`,
+                        `Run ledger: ${ledger.path} (${ledger.entry.id})`,
+                        "",
+                        ...checks.map((c) => `- ${c.ok ? "✅" : "❌"} ${c.name}: ${c.detail}`),
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("audit_public_surface", "Audit exported TypeScript MCP tools/resources/prompts/events and write PUBLIC_SURFACE_REPORT.md", {
+        write_artifact: z
+            .boolean()
+            .optional()
+            .describe("Write agent-state/PUBLIC_SURFACE_REPORT.md (default: true)"),
+        artifact_path: z
+            .string()
+            .optional()
+            .describe("Optional workspace-relative path for the public-surface report"),
+    }, async ({ write_artifact, artifact_path }) => {
+        const result = await auditPublicSurface({
+            write_artifact,
+            artifact_path,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        result.ok
+                            ? `✅ Public surface audit passed (${result.summary.tools} tools, ${result.summary.resources} resources, ${result.summary.prompts} prompts)`
+                            : `❌ Public surface audit failed (${result.failures.length} failure${result.failures.length === 1 ? "" : "s"})`,
+                        `Report: ${result.report_path}`,
+                        `Events: ${result.summary.emitted_events}`,
+                        ...(result.failures.slice(0, 12).map((entry) => `- ${entry}`)),
+                        ...(result.warnings.slice(0, 12).map((entry) => `- warning: ${entry}`)),
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    // ── Execute Gates (manifest-driven gate runner) ───────────────────
+    server.tool("execute_gates", "Run quality gates from agent-state/MODULES/gates/*.json manifests (single source of truth)", {
+        gate_ids: z
+            .array(z.string())
+            .optional()
+            .describe("Specific gate IDs to run (e.g. ['gate-correctness']). Omit to run all registered gates."),
+        review_mode: z
+            .enum(["skeptic_adversarial"])
+            .optional()
+            .describe("Optional skeptic review overlay that keeps only surviving findings actionable."),
+        review_focus: z
+            .string()
+            .optional()
+            .describe("Optional short focus string persisted with skeptic adversarial review evidence."),
+    }, async ({ gate_ids, review_mode, review_focus }) => {
+        const gatesDir = wsPath("agent-state", "MODULES", "gates");
+        if (!existsSync(gatesDir)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "❌ Gates directory not found: agent-state/MODULES/gates/",
+                    },
+                ],
+            };
+        }
+        const allGates = readGateManifests(gatesDir);
+        // Filter to requested gates (or run all)
+        const targets = gate_ids
+            ? allGates.filter((g) => gate_ids.includes(g.id))
+            : allGates;
+        if (targets.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `❌ No matching gates found. Available: ${allGates.map((g) => g.id).join(", ")}`,
+                    },
+                ],
+            };
+        }
+        const results = evaluateGateTargets(targets);
+        const passed = results.filter((r) => r.ok).length;
+        const failed = results.filter((r) => !r.ok).length;
+        const review = review_mode === "skeptic_adversarial"
+            ? buildAdversarialReview(results, review_focus)
+            : undefined;
+        const evidence = review_mode === "skeptic_adversarial" && review
+            ? await appendEvidenceLogEntrySafe(review)
+            : undefined;
+        const blockingFailures = review ? review.summary.confirmed_count : failed;
+        const allOk = blockingFailures === 0;
+        await appendStatusEventSafe({
+            source_module: "capability-framework",
+            event_type: "GATES_EXECUTED",
+            status: allOk ? "pass" : "fail",
+            summary: review
+                ? `Gates executed with skeptic review: ${passed}/${results.length} passed, ${review.summary.confirmed_count} confirmed findings`
+                : `Gates executed: ${passed}/${results.length} passed`,
+            payload: {
+                gates_run: results.map((r) => r.id),
+                gate_results: results.map((r) => ({
+                    id: r.id,
+                    status: r.ok ? "pass" : "fail",
+                    detail: r.detail,
+                })),
+                passed,
+                failed,
+                evidence_ref: evidence?.evidenceRef ?? "agent-state/MODULES/gates/",
+                ...(review
+                    ? {
+                        review: {
+                            mode: review.mode,
+                            focus: review.focus,
+                            candidate_count: review.summary.candidate_count,
+                            disproved_count: review.summary.disproved_count,
+                            confirmed_count: review.summary.confirmed_count,
+                            actionable_gate_ids: review.summary.actionable_gate_ids,
+                            candidates: review.candidates,
+                            disproved: review.disproved,
+                            confirmed: review.confirmed,
+                            evidence_ref: evidence?.evidenceRef,
+                        },
+                    }
+                    : {}),
+            },
+            objective_id: "gate-execution",
+        });
+        const ledger = await appendRunLedgerEntrySafe({
+            tool: "execute_gates",
+            category: allOk ? "info" : "regression",
+            message: review
+                ? `Gate execution with skeptic review: ${review.summary.confirmed_count} confirmed findings`
+                : `Gate execution: ${passed}/${results.length} passed`,
+            artifacts: [
+                ...results.map((r) => `agent-state/MODULES/gates/${r.id}.json`),
+                ...(evidence ? ["agent-state/EVIDENCE_LOG.md"] : []),
+            ],
+            metadata: {
+                passed,
+                failed,
+                gate_ids: results.map((r) => r.id),
+                ...(review
+                    ? {
+                        review_mode: review.mode,
+                        review_focus: review.focus,
+                        candidate_count: review.summary.candidate_count,
+                        disproved_count: review.summary.disproved_count,
+                        confirmed_count: review.summary.confirmed_count,
+                        actionable_gate_ids: review.summary.actionable_gate_ids,
+                        evidence_ref: evidence?.evidenceRef,
+                    }
+                    : {}),
+            },
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        review
+                            ? allOk
+                                ? `✅ Skeptic adversarial review cleared: ${review.summary.confirmed_count} confirmed findings`
+                                : `❌ Skeptic adversarial review found ${review.summary.confirmed_count} confirmed finding${review.summary.confirmed_count === 1 ? "" : "s"}`
+                            : allOk
+                                ? `✅ All gates passed: ${passed}/${results.length}`
+                                : `❌ Gate failures: ${failed}/${results.length} failed`,
+                        `Run ledger: ${ledger.path} (${ledger.entry.id})`,
+                        ...(evidence ? [`Evidence: ${evidence.path} (${evidence.evidenceRef})`] : []),
+                        "",
+                        ...(review
+                            ? [
+                                `Review mode: ${review.mode}`,
+                                ...(review.focus ? [`Review focus: ${review.focus}`] : []),
+                                `- bug-hunter candidates: ${review.summary.candidate_count}`,
+                                `- disproved candidates: ${review.summary.disproved_count}`,
+                                `- confirmed findings: ${review.summary.confirmed_count}`,
+                                ...review.disproved.map((finding) => `- disproved ${finding.gate_id}: ${finding.reason ?? "candidate rejected"}`),
+                                ...review.confirmed.map((finding) => {
+                                    const route = finding.route_hint ? ` (route ${finding.route_hint})` : "";
+                                    return `- confirmed ${finding.gate_id}: ${finding.detail}${route}`;
+                                }),
+                                "",
+                            ]
+                            : []),
+                        ...results.map((r) => `- ${r.ok ? "✅" : "❌"} ${r.id} [${r.type}]: ${r.detail}`),
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=tools-framework.js.map