@mandujs/mcp 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Mandu MCP Server - Agent-native interface for Mandu framework operations",
   "type": "module",
   "main": "./src/index.ts",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@mandujs/core": "^0.37.0",
-    "@mandujs/ate": "^0.21.0",
+    "@mandujs/ate": "^0.22.0",
     "@mandujs/skills": "^16.0.0",
     "@modelcontextprotocol/sdk": "^1.25.3"
   },

package/src/tools/ate-boundary-probe.ts

@@ -0,0 +1,109 @@
+/**
+ * `mandu_ate_boundary_probe` — Phase B.1 deterministic boundary-value
+ * generator for Zod contracts.
+ *
+ * See docs/ate/phase-b-spec.md §B.1 for the full I/O shape. Agents
+ * feed the returned probe set into `mandu_ate_prompt({ kind:
+ * "property_based" })` to produce adversarial specs.
+ *
+ * Snake_case tool name (§11 decision #4). Read-only.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { generateBoundaryProbes } from "@mandujs/ate";
+
+export const ateBoundaryProbeToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_boundary_probe",
+    annotations: {
+      readOnlyHint: true,
+    },
+    description:
+      "Phase B.1 deterministic boundary probe for Zod contracts. Reads a " +
+      "*.contract.ts file, parses request-body schemas per HTTP method, and " +
+      "returns a deterministic set of probe values per field — one per " +
+      "category (valid / invalid_format / boundary_min / boundary_max / " +
+      "empty / null / type_mismatch / enum_reject / missing_required). " +
+      "Every probe also carries the expectedStatus code derived from the " +
+      "contract's response map (400/422 for invalid, 200/201 for valid). " +
+      "The output is stamped with graphVersion for agent cache " +
+      "invalidation. No LLM. No runtime Zod evaluation — source text is " +
+      "parsed directly. Default depth 1, max 3.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: {
+          type: "string",
+          description: "Absolute path to the Mandu project root.",
+        },
+        contractName: {
+          type: "string",
+          description:
+            "Contract identifier. Usually the basename of the contract file (e.g. 'SignupContract' or 'api-signup').",
+        },
+        contractFile: {
+          type: "string",
+          description: "Direct absolute path to the contract file (bypasses name resolution).",
+        },
+        method: {
+          type: "string",
+          enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+          description: "Optional HTTP method filter. Omit to probe every declared method.",
+        },
+        depth: {
+          type: "number",
+          description: "Recursion depth for nested z.object() fields. Default 1, max 3.",
+        },
+      },
+      required: ["repoRoot"],
+    },
+  },
+];
+
+export function ateBoundaryProbeTools(_projectRoot: string) {
+  return {
+    mandu_ate_boundary_probe: async (args: Record<string, unknown>) => {
+      const repoRoot = args.repoRoot as string | undefined;
+      const contractName = args.contractName as string | undefined;
+      const contractFile = args.contractFile as string | undefined;
+      const method = args.method as
+        | "GET"
+        | "POST"
+        | "PUT"
+        | "PATCH"
+        | "DELETE"
+        | undefined;
+      const depth = typeof args.depth === "number" ? args.depth : undefined;
+
+      if (!repoRoot || typeof repoRoot !== "string") {
+        return { ok: false, error: "repoRoot is required" };
+      }
+      if (!contractName && !contractFile) {
+        return { ok: false, error: "contractName or contractFile is required" };
+      }
+
+      try {
+        const result = await generateBoundaryProbes({
+          repoRoot,
+          contractName,
+          contractFile,
+          ...(method ? { method } : {}),
+          ...(depth !== undefined ? { depth } : {}),
+        });
+        return {
+          ok: true,
+          contractName: result.contractName,
+          contractFile: result.contractFile,
+          graphVersion: result.graphVersion,
+          probes: result.probes,
+          warnings: result.warnings,
+        };
+      } catch (err) {
+        return {
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    },
+  };
+}

package/src/tools/ate-context.ts

@@ -1,96 +1,159 @@
-/**
- * `mandu_ate_context` — Phase A.1 agent-native context tool.
- *
- * See `docs/ate/roadmap-v2-agent-native.md` §4.1 for the full design
- * and §11 decision 4 for the naming convention (snake_case).
- *
- * Semantics: return a single JSON blob that an LLM-driven agent
- * (Cursor / Claude Code / Codex) can read *before* generating a test.
- * The blob fuses:
- *
- *   1. Route metadata (pattern, file, isRedirect, static params)
- *   2. Contract surface (request/response schemas + examples)
- *   3. Middleware chain (canonical name + options + file)
- *   4. Guard preset + suggested data-route-id selectors
- *   5. Fixture recommendations (createTestSession, createTestDb, ...)
- *   6. Existing specs (user-written vs ate-generated, last-run status)
- *   7. Related routes (siblings + ui-entry-point pairing)
- *
- * The handler itself is deliberately thin — almost all work is done
- * inside `@mandujs/ate`'s `buildContext` so the same logic is
- * importable from non-MCP callers (CLI, tests).
- */
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
-import { ateContext } from "@mandujs/ate";
-
-export const ateContextToolDefinitions: Tool[] = [
-  {
-    name: "mandu_ate_context",
-    annotations: {
-      readOnlyHint: true,
-    },
-    description:
-      "Phase A.1 agent-native context. Returns a single JSON blob containing the " +
-      "Mandu-specific semantic context an LLM needs to write a correct test: " +
-      "route metadata, contract (with examples), middleware chain, guard preset + " +
-      "suggested [data-route-id] selectors, recommended @mandujs/core/testing fixtures, " +
-      "existing specs (with last-run status when .mandu/ate-last-run.json is present), " +
-      "and related routes (sibling + ui-entry-point pairing). " +
-      "Scope values: " +
-      "'project' = repo summary with route + coverage counts; " +
-      "'route' = single-route deep view (requires id or route); " +
-      "'filling' = server-handler view with middleware + actions (requires id); " +
-      "'contract' = request/response + examples for a contract definition. " +
-      "Run mandu.ate.extract first — this tool reads .mandu/interaction-graph.json.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        repoRoot: {
-          type: "string",
-          description: "Absolute path to the Mandu project root",
-        },
-        scope: {
-          type: "string",
-          enum: ["project", "route", "filling", "contract"],
-          description:
-            "project (summary) | route (single route deep view) | filling (handler view) | contract (contract definition view)",
-        },
-        id: {
-          type: "string",
-          description:
-            "Route id ('api-signup'), filling id ('filling:api-signup'), or contract name. Optional — supply id OR route.",
-        },
-        route: {
-          type: "string",
-          description:
-            "Route pattern match (e.g. '/api/signup'). Optional — supply id OR route.",
-        },
-      },
-      required: ["repoRoot", "scope"],
-    },
-  },
-];
-
-export function ateContextTools(_projectRoot: string) {
-  return {
-    mandu_ate_context: async (args: Record<string, unknown>) => {
-      const { repoRoot, scope, id, route } = args as {
-        repoRoot: string;
-        scope: "project" | "route" | "filling" | "contract";
-        id?: string;
-        route?: string;
-      };
-      // Minimal validation — the MCP SDK already enforces the schema,
-      // but we guard repoRoot explicitly so mis-invocations surface a
-      // loud error rather than a cascading filesystem failure.
-      if (!repoRoot || typeof repoRoot !== "string") {
-        return { ok: false, error: "repoRoot is required" };
-      }
-      if (!scope) {
-        return { ok: false, error: "scope is required" };
-      }
-      const blob = await ateContext({ repoRoot, scope, id, route });
-      return { ok: true, context: blob };
-    },
-  };
-}
+/**
+ * `mandu_ate_context` — Phase A.1 agent-native context tool.
+ *
+ * See `docs/ate/roadmap-v2-agent-native.md` §4.1 for the full design
+ * and §11 decision 4 for the naming convention (snake_case).
+ *
+ * Semantics: return a single JSON blob that an LLM-driven agent
+ * (Cursor / Claude Code / Codex) can read *before* generating a test.
+ * The blob fuses:
+ *
+ *   1. Route metadata (pattern, file, isRedirect, static params)
+ *   2. Contract surface (request/response schemas + examples)
+ *   3. Middleware chain (canonical name + options + file)
+ *   4. Guard preset + suggested data-route-id selectors
+ *   5. Fixture recommendations (createTestSession, createTestDb, ...)
+ *   6. Existing specs (user-written vs ate-generated, last-run status)
+ *   7. Related routes (siblings + ui-entry-point pairing)
+ *
+ * The handler itself is deliberately thin — almost all work is done
+ * inside `@mandujs/ate`'s `buildContext` so the same logic is
+ * importable from non-MCP callers (CLI, tests).
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import {
+  ateContext,
+  appendMemoryEvent,
+  nowTimestamp,
+  readMemoryEvents,
+} from "@mandujs/ate";
+
+export const ateContextToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_context",
+    annotations: {
+      readOnlyHint: true,
+    },
+    description:
+      "Phase A.1 agent-native context. Returns a single JSON blob containing the " +
+      "Mandu-specific semantic context an LLM needs to write a correct test: " +
+      "route metadata, contract (with examples), middleware chain, guard preset + " +
+      "suggested [data-route-id] selectors, recommended @mandujs/core/testing fixtures, " +
+      "existing specs (with last-run status when .mandu/ate-last-run.json is present), " +
+      "and related routes (sibling + ui-entry-point pairing). " +
+      "Scope values: " +
+      "'project' = repo summary with route + coverage counts; " +
+      "'route' = single-route deep view (requires id or route); " +
+      "'filling' = server-handler view with middleware + actions (requires id); " +
+      "'contract' = request/response + examples for a contract definition. " +
+      "Run mandu.ate.extract first — this tool reads .mandu/interaction-graph.json.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: {
+          type: "string",
+          description: "Absolute path to the Mandu project root",
+        },
+        scope: {
+          type: "string",
+          enum: ["project", "route", "filling", "contract"],
+          description:
+            "project (summary) | route (single route deep view) | filling (handler view) | contract (contract definition view)",
+        },
+        id: {
+          type: "string",
+          description:
+            "Route id ('api-signup'), filling id ('filling:api-signup'), or contract name. Optional — supply id OR route.",
+        },
+        route: {
+          type: "string",
+          description:
+            "Route pattern match (e.g. '/api/signup'). Optional — supply id OR route.",
+        },
+      },
+      required: ["repoRoot", "scope"],
+    },
+  },
+];
+
+export function ateContextTools(_projectRoot: string) {
+  return {
+    mandu_ate_context: async (args: Record<string, unknown>) => {
+      const { repoRoot, scope, id, route } = args as {
+        repoRoot: string;
+        scope: "project" | "route" | "filling" | "contract";
+        id?: string;
+        route?: string;
+      };
+      // Minimal validation — the MCP SDK already enforces the schema,
+      // but we guard repoRoot explicitly so mis-invocations surface a
+      // loud error rather than a cascading filesystem failure.
+      if (!repoRoot || typeof repoRoot !== "string") {
+        return { ok: false, error: "repoRoot is required" };
+      }
+      if (!scope) {
+        return { ok: false, error: "scope is required" };
+      }
+      const blob = await ateContext({ repoRoot, scope, id, route });
+
+      // Phase B.2 — first `mandu_ate_context` call of the day writes a
+      // `coverage_snapshot` event (best-effort). The snapshot is derived
+      // from the `project`-scope blob summary; for other scopes we still
+      // fire the snapshot (using scope==='project' would require an
+      // extra call — the project summary's field presence is enough).
+      try {
+        if (!snapshottedToday(repoRoot)) {
+          const withSpec = countWithSpec(blob);
+          const withProperty = 0; // Phase B — property-test detection is part of `mandu_ate_coverage`.
+          const totalRoutes = countTotalRoutes(blob);
+          appendMemoryEvent(repoRoot, {
+            kind: "coverage_snapshot",
+            timestamp: nowTimestamp(),
+            routes: totalRoutes,
+            withSpec,
+            withProperty,
+          });
+        }
+      } catch {
+        // swallow — snapshot is best-effort.
+      }
+
+      return { ok: true, context: blob };
+    },
+  };
+}
+
+function snapshottedToday(repoRoot: string): boolean {
+  try {
+    const events = readMemoryEvents(repoRoot);
+    const today = new Date().toISOString().slice(0, 10);
+    return events.some(
+      (e) => e.kind === "coverage_snapshot" && e.timestamp.slice(0, 10) === today,
+    );
+  } catch {
+    return false;
+  }
+}
+
+function countTotalRoutes(blob: unknown): number {
+  if (!blob || typeof blob !== "object") return 0;
+  const b = blob as { scope?: string; summary?: { routes?: number }; route?: unknown };
+  if (b.scope === "project" && b.summary && typeof b.summary.routes === "number") {
+    return b.summary.routes;
+  }
+  // Non-project scope — we can't meaningfully count; leave 0 so the snapshot
+  // still records the timestamp without lying about totals.
+  return 0;
+}
+
+function countWithSpec(blob: unknown): number {
+  if (!blob || typeof blob !== "object") return 0;
+  const b = blob as {
+    scope?: string;
+    routes?: Array<{ existingSpecCount: number }>;
+  };
+  if (b.scope === "project" && Array.isArray(b.routes)) {
+    return b.routes.filter((r) => (r.existingSpecCount ?? 0) > 0).length;
+  }
+  return 0;
+}

package/src/tools/ate-coverage.ts

@@ -0,0 +1,71 @@
+/**
+ * `mandu_ate_coverage` — Phase B.4 quantified gap report.
+ *
+ * See docs/ate/phase-b-spec.md §B.5 for the output shape. Agents call
+ * this to discover `topGaps` and prioritize spec generation work.
+ *
+ * Snake_case (§11 decision #4). Read-only.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { computeCoverage } from "@mandujs/ate";
+
+export const ateCoverageToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_coverage",
+    annotations: {
+      readOnlyHint: true,
+    },
+    description:
+      "Phase B.4 coverage metrics. Returns the 3-axis coverage report: " +
+      "(1) routes with unit / integration / e2e spec; (2) contracts with " +
+      "full / partial / no boundary-probe coverage; (3) middleware " +
+      "invariants (csrf / rate-limit / session / auth / i18n) tagged as " +
+      "covered / partial / missing. Also returns a `topGaps` list sorted " +
+      "high → medium → low severity. Stamped with graphVersion for " +
+      "agent cache invalidation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: {
+          type: "string",
+          description: "Absolute path to the Mandu project root.",
+        },
+        scope: {
+          type: "string",
+          enum: ["project", "route", "contract"],
+          description:
+            "Default 'project'. Use 'route' (with target=routeId) or 'contract' (with target=contractName) for narrow scans.",
+        },
+        target: {
+          type: "string",
+          description: "Route id or contract basename when scope is not 'project'.",
+        },
+      },
+      required: ["repoRoot"],
+    },
+  },
+];
+
+export function ateCoverageTools(_projectRoot: string) {
+  return {
+    mandu_ate_coverage: async (args: Record<string, unknown>) => {
+      const repoRoot = args.repoRoot as string | undefined;
+      if (!repoRoot || typeof repoRoot !== "string") {
+        return { ok: false, error: "repoRoot is required" };
+      }
+      const scope = args.scope as "project" | "route" | "contract" | undefined;
+      const target = typeof args.target === "string" ? args.target : undefined;
+
+      try {
+        const metrics = await computeCoverage(repoRoot, {
+          scope: scope ?? "project",
+          ...(target ? { target } : {}),
+        });
+        return { ok: true, ...metrics };
+      } catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+      }
+    },
+  };
+}

package/src/tools/ate-recall.ts

@@ -0,0 +1,85 @@
+/**
+ * `mandu_ate_recall` — Phase B.2 memory read tool.
+ *
+ * See docs/ate/phase-b-spec.md §B.2. Agents call this BEFORE generating
+ * a spec so they can reference prior intent / rejected healing history.
+ *
+ * Snake_case (§11 decision #4). Read-only.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { recallMemory, type MemoryEventKind } from "@mandujs/ate";
+
+export const ateRecallToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_recall",
+    annotations: {
+      readOnlyHint: true,
+    },
+    description:
+      "Phase B.2 memory recall. Queries the project-local " +
+      ".mandu/ate-memory.jsonl append-only log with substring + token-" +
+      "overlap scoring (no embeddings). Useful BEFORE generation to see " +
+      "previously rejected specs, accepted heals, or intent history for " +
+      "the same route. Returns { events, totalMatching }. Default limit 10, " +
+      "default sinceDays 90. Filter by kind: intent_history | rejected_spec " +
+      "| accepted_healing | rejected_healing | prompt_version_drift | " +
+      "boundary_gap_filled | coverage_snapshot.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: {
+          type: "string",
+          description: "Absolute path to the Mandu project root.",
+        },
+        intent: {
+          type: "string",
+          description: "Natural-language intent to search (substring + token overlap).",
+        },
+        route: {
+          type: "string",
+          description: "Route id or pattern ('api-signup' or '/api/signup').",
+        },
+        kind: {
+          type: "string",
+          description: "Filter by event kind.",
+        },
+        limit: {
+          type: "number",
+          description: "Max events to return. Default 10.",
+        },
+        sinceDays: {
+          type: "number",
+          description: "Drop events older than N days. Default 90.",
+        },
+      },
+      required: ["repoRoot"],
+    },
+  },
+];
+
+export function ateRecallTools(_projectRoot: string) {
+  return {
+    mandu_ate_recall: async (args: Record<string, unknown>) => {
+      const repoRoot = args.repoRoot as string | undefined;
+      if (!repoRoot || typeof repoRoot !== "string") {
+        return { ok: false, error: "repoRoot is required" };
+      }
+      try {
+        const result = recallMemory(repoRoot, {
+          intent: typeof args.intent === "string" ? args.intent : undefined,
+          route: typeof args.route === "string" ? args.route : undefined,
+          kind:
+            typeof args.kind === "string"
+              ? (args.kind as MemoryEventKind)
+              : undefined,
+          limit: typeof args.limit === "number" ? args.limit : undefined,
+          sinceDays: typeof args.sinceDays === "number" ? args.sinceDays : undefined,
+        });
+        return { ok: true, ...result };
+      } catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+      }
+    },
+  };
+}

package/src/tools/ate-remember.ts

@@ -0,0 +1,79 @@
+/**
+ * `mandu_ate_remember` — Phase B.2 memory write tool.
+ *
+ * Snake_case (§11 decision #4). Idempotent append.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import {
+  appendMemoryEvent,
+  parseMemoryEvent,
+  type MemoryEvent,
+} from "@mandujs/ate";
+
+export const ateRememberToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_remember",
+    description:
+      "Phase B.2 memory write. Appends one event to the project-local " +
+      ".mandu/ate-memory.jsonl. File auto-rotates to .bak when it crosses " +
+      "10 MB. Supported event kinds (discriminated union by `kind`): " +
+      "intent_history | rejected_spec | accepted_healing | rejected_healing " +
+      "| prompt_version_drift | boundary_gap_filled | coverage_snapshot. " +
+      "Timestamp defaults to now (ISO-8601 UTC) if omitted.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: {
+          type: "string",
+          description: "Absolute path to the Mandu project root.",
+        },
+        event: {
+          type: "object",
+          description:
+            "MemoryEvent object. Must carry a `kind` discriminator plus the " +
+            "event-kind-specific required fields (see @mandujs/ate memory/schema.ts).",
+          additionalProperties: true,
+        },
+      },
+      required: ["repoRoot", "event"],
+    },
+  },
+];
+
+export function ateRememberTools(_projectRoot: string) {
+  return {
+    mandu_ate_remember: async (args: Record<string, unknown>) => {
+      const repoRoot = args.repoRoot as string | undefined;
+      const eventRaw = args.event;
+
+      if (!repoRoot || typeof repoRoot !== "string") {
+        return { ok: false, error: "repoRoot is required" };
+      }
+      if (!eventRaw || typeof eventRaw !== "object") {
+        return { ok: false, error: "event is required" };
+      }
+
+      // Default the timestamp if the caller omitted it (agents do).
+      const draft = { ...(eventRaw as Record<string, unknown>) };
+      if (typeof draft.timestamp !== "string") {
+        draft.timestamp = new Date().toISOString();
+      }
+      const parsed = parseMemoryEvent(draft);
+      if (!parsed) {
+        return {
+          ok: false,
+          error:
+            "Event failed validation. Check that `kind` and the kind-specific required fields are present.",
+        };
+      }
+
+      try {
+        const result = appendMemoryEvent(repoRoot, parsed as MemoryEvent);
+        return { ok: true, written: result.written, rotation: result.rotation ?? null };
+      } catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+      }
+    },
+  };
+}

package/src/tools/ate-save.ts

@@ -1,139 +1,160 @@
-/**
- * `mandu_ate_save` — Phase A.3 spec persistence with lint-before-write.
- *
- * See `docs/ate/roadmap-v2-agent-native.md` §4.7 and the §7 extension
- * ("mandu_ate_save lint-before-write").
- *
- * Semantics:
- *   1. Run `lintSpecContent` (from @mandujs/ate) which:
- *        - parses with ts-morph (syntax errors block),
- *        - walks import declarations (banned typos, unknown @mandujs/* barrels),
- *        - detects anti-patterns (bare localhost, hand-rolled CSRF, DB mocks).
- *   2. If any *blocking* diagnostic fires, return { saved: false, ... } WITHOUT
- *      writing. Otherwise write and return { saved: true, path }.
- *
- * Snake_case tool name (§11 decision #4).
- */
-
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
-import { writeFileSync, mkdirSync, existsSync, statSync } from "node:fs";
-import { dirname, isAbsolute } from "node:path";
-import { lintSpecContent, type LintDiagnostic } from "@mandujs/ate";
-
-// Re-export the diagnostic shape so callers can type-check against it without
-// pulling @mandujs/ate directly.
-export type { LintDiagnostic, LintSeverity } from "@mandujs/ate";
-
-export const ateSaveToolDefinitions: Tool[] = [
-  {
-    name: "mandu_ate_save",
-    description:
-      "Phase A.3 persist-with-lint. Writes an agent-generated test file to " +
-      "disk, but first runs a small lint pass that blocks common LLM mistakes: " +
-      "ts-morph syntax errors, unresolved / banned import paths, hand-rolled " +
-      "CSRF cookies, DB mocks when createTestDb is available, and bare " +
-      "`localhost:<port>` URLs (prefer 127.0.0.1 per roadmap §9.2). Returns " +
-      "{ saved: true, path, lintDiagnostics: [warnings...] } on success or " +
-      "{ saved: false, blockingErrors: [...], lintDiagnostics: [...] } when " +
-      "a blocker fires (in which case no file is written).",
-    inputSchema: {
-      type: "object",
-      properties: {
-        path: {
-          type: "string",
-          description:
-            "Absolute path where the spec will be written. Parent directories are created if needed.",
-        },
-        content: {
-          type: "string",
-          description: "The full TypeScript test source to write.",
-        },
-        intent: {
-          type: "string",
-          description:
-            "Optional short description of what the test is verifying (logged to ATE memory).",
-        },
-        kind: {
-          type: "string",
-          description:
-            "Optional prompt kind this spec was generated for (filling_unit, filling_integration, e2e_playwright).",
-        },
-        sourcePrompt: {
-          type: "object",
-          description:
-            "Optional { kind, version } back-reference to the prompt that produced this spec (used by future memory queries).",
-          additionalProperties: true,
-        },
-        allowWarnings: {
-          type: "boolean",
-          description:
-            "When true, non-blocking warnings still allow the write (default true). When false, even warnings block.",
-        },
-      },
-      required: ["path", "content"],
-    },
-  },
-];
-
-export function ateSaveTools(_projectRoot: string) {
-  return {
-    mandu_ate_save: async (args: Record<string, unknown>) => {
-      const path = args.path as string | undefined;
-      const content = args.content as string | undefined;
-      const allowWarnings = args.allowWarnings !== false;
-
-      if (!path || typeof path !== "string") {
-        return { saved: false, error: "'path' is required" };
-      }
-      if (!isAbsolute(path)) {
-        return {
-          saved: false,
-          error: "'path' must be absolute — relative paths are rejected to prevent cwd drift.",
-        };
-      }
-      if (typeof content !== "string") {
-        return { saved: false, error: "'content' is required and must be a string" };
-      }
-
-      const diagnostics = await lintSpecContent(path, content);
-
-      const blocking = diagnostics.filter((d) => d.blocking);
-      const warnings = diagnostics.filter((d) => !d.blocking);
-
-      if (blocking.length > 0 || (!allowWarnings && warnings.length > 0)) {
-        return {
-          saved: false,
-          path,
-          blockingErrors: blocking,
-          lintDiagnostics: diagnostics,
-        };
-      }
-
-      const parent = dirname(path);
-      if (!existsSync(parent)) {
-        mkdirSync(parent, { recursive: true });
-      }
-      if (!statSync(parent).isDirectory()) {
-        return { saved: false, path, error: `Parent path is not a directory: ${parent}` };
-      }
-
-      writeFileSync(path, content, "utf8");
-
-      return {
-        saved: true,
-        path,
-        bytes: Buffer.byteLength(content, "utf8"),
-        lintDiagnostics: diagnostics,
-      };
-    },
-  };
-}
-
-// Re-export for tests that need direct access (package.json test patterns
-// already reach here).
-export async function lintContent(
-  path: string,
-  content: string,
-): Promise<LintDiagnostic[]> {
-  return lintSpecContent(path, content);
-}
+/**
+ * `mandu_ate_save` — Phase A.3 spec persistence with lint-before-write.
+ *
+ * See `docs/ate/roadmap-v2-agent-native.md` §4.7 and the §7 extension
+ * ("mandu_ate_save lint-before-write").
+ *
+ * Semantics:
+ *   1. Run `lintSpecContent` (from @mandujs/ate) which:
+ *        - parses with ts-morph (syntax errors block),
+ *        - walks import declarations (banned typos, unknown @mandujs/* barrels),
+ *        - detects anti-patterns (bare localhost, hand-rolled CSRF, DB mocks).
+ *   2. If any *blocking* diagnostic fires, return { saved: false, ... } WITHOUT
+ *      writing. Otherwise write and return { saved: true, path }.
+ *
+ * Snake_case tool name (§11 decision #4).
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { writeFileSync, mkdirSync, existsSync, statSync } from "node:fs";
+import { dirname, isAbsolute } from "node:path";
+import {
+  lintSpecContent,
+  appendMemoryEvent,
+  nowTimestamp,
+  type LintDiagnostic,
+} from "@mandujs/ate";
+
+// Re-export the diagnostic shape so callers can type-check against it without
+// pulling @mandujs/ate directly.
+export type { LintDiagnostic, LintSeverity } from "@mandujs/ate";
+
+export const ateSaveToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_save",
+    description:
+      "Phase A.3 persist-with-lint. Writes an agent-generated test file to " +
+      "disk, but first runs a small lint pass that blocks common LLM mistakes: " +
+      "ts-morph syntax errors, unresolved / banned import paths, hand-rolled " +
+      "CSRF cookies, DB mocks when createTestDb is available, and bare " +
+      "`localhost:<port>` URLs (prefer 127.0.0.1 per roadmap §9.2). Returns " +
+      "{ saved: true, path, lintDiagnostics: [warnings...] } on success or " +
+      "{ saved: false, blockingErrors: [...], lintDiagnostics: [...] } when " +
+      "a blocker fires (in which case no file is written).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description:
+            "Absolute path where the spec will be written. Parent directories are created if needed.",
+        },
+        content: {
+          type: "string",
+          description: "The full TypeScript test source to write.",
+        },
+        intent: {
+          type: "string",
+          description:
+            "Optional short description of what the test is verifying (logged to ATE memory).",
+        },
+        kind: {
+          type: "string",
+          description:
+            "Optional prompt kind this spec was generated for (filling_unit, filling_integration, e2e_playwright).",
+        },
+        sourcePrompt: {
+          type: "object",
+          description:
+            "Optional { kind, version } back-reference to the prompt that produced this spec (used by future memory queries).",
+          additionalProperties: true,
+        },
+        allowWarnings: {
+          type: "boolean",
+          description:
+            "When true, non-blocking warnings still allow the write (default true). When false, even warnings block.",
+        },
+      },
+      required: ["path", "content"],
+    },
+  },
+];
+
+export function ateSaveTools(projectRoot: string) {
+  return {
+    mandu_ate_save: async (args: Record<string, unknown>) => {
+      const path = args.path as string | undefined;
+      const content = args.content as string | undefined;
+      const intent = typeof args.intent === "string" ? args.intent : undefined;
+      const kind = typeof args.kind === "string" ? args.kind : undefined;
+      const allowWarnings = args.allowWarnings !== false;
+
+      if (!path || typeof path !== "string") {
+        return { saved: false, error: "'path' is required" };
+      }
+      if (!isAbsolute(path)) {
+        return {
+          saved: false,
+          error: "'path' must be absolute — relative paths are rejected to prevent cwd drift.",
+        };
+      }
+      if (typeof content !== "string") {
+        return { saved: false, error: "'content' is required and must be a string" };
+      }
+
+      const diagnostics = await lintSpecContent(path, content);
+
+      const blocking = diagnostics.filter((d) => d.blocking);
+      const warnings = diagnostics.filter((d) => !d.blocking);
+
+      if (blocking.length > 0 || (!allowWarnings && warnings.length > 0)) {
+        return {
+          saved: false,
+          path,
+          blockingErrors: blocking,
+          lintDiagnostics: diagnostics,
+        };
+      }
+
+      const parent = dirname(path);
+      if (!existsSync(parent)) {
+        mkdirSync(parent, { recursive: true });
+      }
+      if (!statSync(parent).isDirectory()) {
+        return { saved: false, path, error: `Parent path is not a directory: ${parent}` };
+      }
+
+      writeFileSync(path, content, "utf8");
+
+      // Phase B.2 — auto-record intent_history event. Non-fatal on failure.
+      try {
+        appendMemoryEvent(projectRoot, {
+          kind: "intent_history",
+          timestamp: nowTimestamp(),
+          intent: intent ?? "(no intent supplied)",
+          agent: typeof args.agent === "string" ? (args.agent as string) : "unknown",
+          resulting: { saved: [path] },
+          ...(kind ? { routeId: kind } : {}),
+        });
+      } catch {
+        // swallow
+      }
+
+      return {
+        saved: true,
+        path,
+        bytes: Buffer.byteLength(content, "utf8"),
+        lintDiagnostics: diagnostics,
+      };
+    },
+  };
+}
+
+// Re-export for tests that need direct access (package.json test patterns
+// already reach here).
+export async function lintContent(
+  path: string,
+  content: string,
+): Promise<LintDiagnostic[]> {
+  return lintSpecContent(path, content);
+}

package/src/tools/ate.ts

@@ -171,16 +171,27 @@ export const ateToolDefinitions: Tool[] = [
       readOnlyHint: true,
     },
     description:
-      "ATE Optimization — Impact Analysis: Calculate the minimal subset of routes affected by changed files using git diff. " +
-      "Avoids running the full test suite when only part of the codebase changed. " +
-      "Returns selectedRoutes to pass to mandu.ate.generate (onlyRoutes) or mandu.ate.run. " +
-      "Typical use: run after `git commit` to test only affected routes in CI.",
+      "ATE Impact Analysis (Phase B.3 v2). Calculates the minimal set of " +
+      "routes / specs affected by changed files using git diff, classifies " +
+      "contract changes (additive / breaking / renaming), and returns " +
+      "`affected.specsToReRun`, `affected.specsLikelyBroken`, " +
+      "`affected.missingCoverage`, plus a `suggestions` list keyed to " +
+      "re_run / heal / regenerate / add_boundary_test. Stamped with " +
+      "graphVersion for agent caching. Keeps v1 fields (changedFiles, " +
+      "selectedRoutes, warnings) for backwards compatibility. " +
+      "Pass `since: 'working'` for uncommitted changes, `since: 'staged'` " +
+      "for staged changes, or a git rev (default: HEAD~1) for committed diffs.",
     inputSchema: {
       type: "object",
       properties: {
         repoRoot: { type: "string", description: "Absolute path to the Mandu project root" },
-        base: { type: "string", description: "Git base ref for diff (default: HEAD~1 or main branch)" },
-        head: { type: "string", description: "Git head ref for diff (default: current working tree)" },
+        base: { type: "string", description: "Git base ref (legacy v1 — use `since` instead)" },
+        head: { type: "string", description: "Git head ref (legacy v1 — defaults to HEAD)" },
+        since: {
+          type: "string",
+          description:
+            "v2 diff source: 'HEAD~1' | 'staged' | 'working' | any git rev. Default 'HEAD~1'.",
+        },
       },
       required: ["repoRoot"],
     },
@@ -333,11 +344,27 @@ export function ateTools(projectRoot: string) {
       return ateHeal({ repoRoot, runId });
     },
     "mandu.ate.impact": async (args: Record<string, unknown>) => {
-      const { repoRoot, base, head } = args as {
+      const { repoRoot, base, head, since } = args as {
         repoRoot: string;
         base?: string;
         head?: string;
+        since?: "HEAD~1" | "staged" | "working" | string;
       };
+
+      // Phase B.3 — try the v2 impact pipeline first so callers get
+      // `affected`, `suggestions`, `contractDiffs`, `graphVersion` in
+      // addition to the v1 fields. Fall back to v1 on failure so the
+      // tool contract stays backwards compatible.
+      try {
+        const { computeImpactV2 } = await import("@mandujs/ate");
+        const v2 = await computeImpactV2({
+          repoRoot,
+          since: since ?? base,
+        });
+        return { ok: true, ...v2 };
+      } catch {
+        // Fall through to v1.
+      }
       return ateImpact({ repoRoot, base, head });
     },
     "mandu.ate.auto_pipeline": async (args: Record<string, unknown>) => {

package/src/tools/index.ts

@@ -34,6 +34,10 @@ export { ateFlakesTools, ateFlakesToolDefinitions } from "./ate-flakes.js";
 export { atePromptTools, atePromptToolDefinitions } from "./ate-prompt.js";
 export { ateExemplarTools, ateExemplarToolDefinitions } from "./ate-exemplar.js";
 export { ateSaveTools, ateSaveToolDefinitions } from "./ate-save.js";
+export { ateBoundaryProbeTools, ateBoundaryProbeToolDefinitions } from "./ate-boundary-probe.js";
+export { ateRecallTools, ateRecallToolDefinitions } from "./ate-recall.js";
+export { ateRememberTools, ateRememberToolDefinitions } from "./ate-remember.js";
+export { ateCoverageTools, ateCoverageToolDefinitions } from "./ate-coverage.js";
 export { resourceTools, resourceToolDefinitions } from "./resource.js";
 export { componentTools, componentToolDefinitions } from "./component.js";
 export { kitchenTools, kitchenToolDefinitions } from "./kitchen.js";
@@ -80,6 +84,13 @@ import { ateFlakesTools, ateFlakesToolDefinitions } from "./ate-flakes.js";
 import { atePromptTools, atePromptToolDefinitions } from "./ate-prompt.js";
 import { ateExemplarTools, ateExemplarToolDefinitions } from "./ate-exemplar.js";
 import { ateSaveTools, ateSaveToolDefinitions } from "./ate-save.js";
+import {
+  ateBoundaryProbeTools,
+  ateBoundaryProbeToolDefinitions,
+} from "./ate-boundary-probe.js";
+import { ateRecallTools, ateRecallToolDefinitions } from "./ate-recall.js";
+import { ateRememberTools, ateRememberToolDefinitions } from "./ate-remember.js";
+import { ateCoverageTools, ateCoverageToolDefinitions } from "./ate-coverage.js";
 import { resourceTools, resourceToolDefinitions } from "./resource.js";
 import { componentTools, componentToolDefinitions } from "./component.js";
 import { kitchenTools, kitchenToolDefinitions } from "./kitchen.js";
@@ -143,6 +154,19 @@ const TOOL_MODULES: ToolModule[] = [
   { category: "ate-prompt", definitions: atePromptToolDefinitions, handlers: atePromptTools },
   { category: "ate-exemplar", definitions: ateExemplarToolDefinitions, handlers: ateExemplarTools },
   { category: "ate-save", definitions: ateSaveToolDefinitions, handlers: ateSaveTools },
+  // Phase B tool suite
+  {
+    category: "ate-boundary-probe",
+    definitions: ateBoundaryProbeToolDefinitions,
+    handlers: ateBoundaryProbeTools,
+  },
+  { category: "ate-recall", definitions: ateRecallToolDefinitions, handlers: ateRecallTools },
+  { category: "ate-remember", definitions: ateRememberToolDefinitions, handlers: ateRememberTools },
+  {
+    category: "ate-coverage",
+    definitions: ateCoverageToolDefinitions,
+    handlers: ateCoverageTools,
+  },
   { category: "resource", definitions: resourceToolDefinitions, handlers: resourceTools },
   { category: "component", definitions: componentToolDefinitions, handlers: componentTools },
   { category: "kitchen", definitions: kitchenToolDefinitions, handlers: kitchenTools },