weavatrix 0.2.0 → 0.2.1

package/README.md

@@ -168,6 +168,24 @@ disclosed instead of silently guessed; and the server **hot-reloads its watched
 modules and catalog** when those files change — other MCP helpers and analysis engines require a
 reconnect.
 
+### 0.2.1 bounded-output patch
+
+- `git_history top_n=N` is a hard per-collection MCP cap, including churn, hotspots and every
+  coupling list. JSON output reports `total`, `returned` and `truncated` for each collection.
+- `god_nodes` ranks production code by default, excluding classified tests and generated/build
+  artifacts; pass `include_classified:true` only when those surfaces are intentionally in scope.
+- `output_format:"text"` returns concise TextContent only. Use `output_format:"json"` when a
+  workflow needs the full stable `weavatrix.tool.v1` structured envelope.
+- `trace_api_contract` resolves bounded constant prefixes in template URLs and accepts
+  segment-aligned path fragments such as `/query` for `/edgeAnalytics/query/...`.
+- `change_impact` labels test/e2e edits as `test-only` and does not seed product blast radius from
+  them.
+- Without a saved architecture contract, `prepare_change` returns concise provisional budgets and
+  clearly labels them as non-enforceable; request `get_architecture_contract output_format:"json"`
+  only when the inferred starter contract is actually needed.
+
+Full patch notes: [docs/releases/v0.2.1.md](docs/releases/v0.2.1.md).
+
 ## Signal quality and repository configuration
 
 Weavatrix `0.2.0` reduces the most common sources of static-analysis noise while deepening Rust and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weavatrix",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Weavatrix — code graph & blast-radius MCP server for AI coding agents: change impact, transitive dependents, health audit, duplicate detection, and coverage mapping over any local repository.",
   "author": "Sergii Ziborov <sergii.ziborov@gmail.com>",

package/skill/SKILL.md

@@ -84,7 +84,9 @@ named profiles for new registrations.
 
 ## Recipes
 
-- **Orient in the configured repo**: `module_map` → `list_communities` → `god_nodes`.
+- **Orient in the configured repo**: `module_map` → `list_communities` → `god_nodes`. Hub ranking
+  is production-only by default; use `include_classified:true` only when tests/generated/build
+  surfaces are deliberately part of the question.
 - **Refactor safety for one symbol**: `get_dependents` → `coverage_map` (low coverage × many
   dependents ⇒ write tests first) → `read_source`.
 - **Pre-PR review of your current changes**: `change_impact` (auto merge-base; includes uncommitted
@@ -114,14 +116,21 @@ named profiles for new registrations.
 - **API inventory**: `list_endpoints` (including Next.js App Router, Rust axum and actix-web).
 - **Cross-repository API impact**: ensure both repositories are in `list_known_repos`, then call
   `trace_api_contract backend=<uuid-or-label> clients=[<uuid-or-label>]`; narrow with `method`, `path`,
-  or backend `changed_files`. Treat unresolved/dynamic URLs as incomplete evidence, not a clean result.
+  or backend `changed_files`. `path` may be a segment-aligned fragment (`/query` can select
+  `/edgeAnalytics/query/...`), and bounded constant prefixes in template URLs are resolved. Treat
+  remaining unresolved/dynamic URLs as incomplete evidence, not a clean result.
 - **Target architecture before editing**: `get_architecture_contract` → `prepare_change` with the
   intended files → edit and rebuild → `verify_architecture`. A missing contract returns a starter
-  proposal, not an automatically approved architecture. Pull an owner-approved hosted contract only
-  when the user selected `hosted` and explicitly asks for it.
+  proposal from `get_architecture_contract output_format:"json"`, not an automatically approved
+  architecture. Without a contract, `prepare_change` still returns provisional no-regression
+  budgets, but they are guidance rather than enforceable policy. Pull an owner-approved hosted
+  contract only when the user selected `hosted` and explicitly asks for it.
 - **Behavioral architecture**: `git_history` ranks churn × connectivity hotspots and hidden
-  co-change coupling from bounded local numstat history. Use it as review evidence, not proof that two
-  files must be merged.
+  co-change coupling from bounded local numstat history. Always set `top_n`; it is enforced across
+  every returned structured collection and JSON reports per-collection truncation. Use it as review
+  evidence, not proof that two files must be merged.
+- **Machine output**: keep the default `output_format:"text"` for concise agent conversations; opt
+  into `output_format:"json"` only when a workflow consumes the full `weavatrix.tool.v1` envelope.
 - **Find code**: `search_code` (regex + glob) → `get_node` → `read_source`.
 - **Another repo**: `list_known_repos` → `open_repo <path>`
   (builds or upgrades the graph when needed; `build:false` probes without building).

package/src/analysis/change-classification.js

@@ -4,6 +4,7 @@
 // from flooding the report with every legacy importer of that file.
 import { spawnSync } from "node:child_process";
 import { childProcessEnv } from "../child-env.js";
+import { createPathClassifier, hasPathClass } from "../path-classification.js";
 
 const DEFAULT_LIMITS = Object.freeze({
   maxDiffBytes: 2 * 1024 * 1024,
@@ -15,6 +16,7 @@ const DEFAULT_LIMITS = Object.freeze({
 });
 const CLASS_RANK = Object.freeze({
   "metadata-only": 0,
+  "test-only": 0,
   added: 1,
   "body-changed": 2,
   "signature-changed": 3,
@@ -395,6 +397,20 @@ function unknownFile(path, indexed, reason) {
   };
 }
 
+function classifyTestSurface(file, pathClassifier) {
+  const explanation = pathClassifier.explain(file.path);
+  if (!hasPathClass(explanation, "test", "e2e")) return file;
+  const surface = explanation.classes.includes("e2e") ? "e2e" : "test";
+  return {
+    ...file,
+    classification: "test-only",
+    changeClassification: file.classification,
+    reason: `${surface} path; excluded from the product blast-radius seed set`,
+    pathClasses: explanation.classes,
+    seedIds: [],
+  };
+}
+
 function runGitDiff(repoRoot, base, _files, limits) {
   const args = ["-C", repoRoot, "diff", "--no-ext-diff", "--find-renames", "--no-color", "--unified=0", String(base), "--"];
   const result = spawnSync("git", args, {
@@ -443,17 +459,25 @@ export function classifyChangeImpact({
   }
 
   const indexed = graphIndex(graph, limits);
+  const pathClassifier = createPathClassifier(repoRoot);
   const parsed = available ? parseZeroContextDiff(text, limits) : { files: [], changedLines: 0, byteLength: 0, truncated: gitOversized, oversized: gitOversized, limits };
-  const analyzed = parsed.files.map((file) => analyzeParsedFile(file, indexed, { includeAddedSeeds }));
+  const analyzed = parsed.files.map((file) => classifyTestSurface(
+    analyzeParsedFile(file, indexed, { includeAddedSeeds }),
+    pathClassifier,
+  ));
   const represented = new Set(analyzed.flatMap((file) => [file.oldPath, file.newPath].filter(Boolean)));
   for (const file of explicitFiles) {
-    if (!represented.has(file)) analyzed.push(unknownFile(file, indexed, available ? "explicitly changed file had no textual hunk" : unavailableReason));
+    if (!represented.has(file)) analyzed.push(classifyTestSurface(
+      unknownFile(file, indexed, available ? "explicitly changed file had no textual hunk" : unavailableReason),
+      pathClassifier,
+    ));
   }
   if (!available && !explicitFiles.length) analyzed.push(unknownFile("(diff unavailable)", indexed, unavailableReason));
   analyzed.sort((a, b) => a.path.localeCompare(b.path));
 
   if (parsed.truncated || parsed.oversized || gitOversized) {
     for (const file of analyzed) {
+      if (file.classification === "test-only") continue;
       file.classification = "unknown";
       file.reason = "diff was truncated/oversized; symbol-level classification is incomplete";
       const record = indexed.get(file.newPath) || indexed.get(file.oldPath);
@@ -480,6 +504,7 @@ export function classifyChangeImpact({
   if (counts["body-changed"]) reasons.push(`${counts["body-changed"]} file(s) contain mapped executable body changes.`);
   if (counts.added && !includeAddedSeeds) reasons.push(`${counts.added} purely additive file change(s) create no dependent seeds by default.`);
   if (counts["metadata-only"]) reasons.push(`${counts["metadata-only"]} metadata-only file change(s) create no dependent seeds.`);
+  if (counts["test-only"]) reasons.push(`${counts["test-only"]} test-only file change(s) are labelled explicitly and create no product blast-radius seeds.`);
   if (counts.unknown) reasons.push(`${counts.unknown} file change(s) remain unknown and are seeded conservatively.`);
   if (!reasons.length) reasons.push("No changed files were present in the supplied diff.");
 

package/src/analysis/git-history.js

@@ -547,3 +547,45 @@ export function formatGitHistoryAnalytics(result, options = {}) {
   if (result.completeness.reasons.length) lines.push("", `Partial: ${result.completeness.reasons.join("; ")}.`);
   return lines.join("\n");
 }
+
+// Keep the full analytics object available to local callers, but never expose its unbounded
+// collections through an MCP response. `topN` is a per-collection ceiling, not merely a text
+// formatting hint. The accompanying page metadata lets machine consumers distinguish "there were
+// no more results" from "more evidence exists but was deliberately omitted".
+export function boundGitHistoryAnalytics(result, options = {}) {
+  const topN = boundedInteger(options.topN, 10, 1, 50);
+  const source = result && typeof result === "object" ? result : {};
+  const coupling = source.coupling && typeof source.coupling === "object" ? source.coupling : {};
+  const collections = {};
+  const cap = (name, value) => {
+    const items = Array.isArray(value) ? value : [];
+    const bounded = items.slice(0, topN);
+    collections[name] = {
+      total: items.length,
+      returned: bounded.length,
+      truncated: items.length > bounded.length,
+    };
+    return bounded;
+  };
+
+  const bounded = {
+    ...source,
+    limits: {...(source.limits || {}), topN},
+    fileChurn: cap("fileChurn", source.fileChurn),
+    hotspots: cap("hotspots", source.hotspots),
+    coupling: {
+      ...coupling,
+      observed: cap("coupling.observed", coupling.observed),
+      expectedTestSource: cap("coupling.expectedTestSource", coupling.expectedTestSource),
+      hidden: cap("coupling.hidden", coupling.hidden),
+    },
+  };
+  return {
+    result: bounded,
+    page: {
+      limit: topN,
+      truncated: Object.values(collections).some((entry) => entry.truncated),
+      collections,
+    },
+  };
+}

package/src/analysis/http-contracts.js

@@ -148,7 +148,7 @@ function quotedArgument(text, start, quote) {
   return null;
 }
 
-function templateArgument(text, start) {
+function templateArgument(text, start, constants = null, requireStatic = false) {
   let value = "";
   let dynamicSegments = 0;
   let unknownPrefix = false;
@@ -182,6 +182,13 @@ function templateArgument(text, start) {
       cursor += 1;
     }
     if (depth !== 0) return null;
+    const expression = text.slice(index + 2, cursor - 1).trim();
+    if (/^[A-Za-z_$][\w$]*$/.test(expression) && constants?.has(expression)) {
+      value += constants.get(expression);
+      index = cursor - 1;
+      continue;
+    }
+    if (requireStatic) return null;
     const next = text[cursor];
     const leftBoundary = value === "" || value.endsWith("/");
     const rightBoundary = !next || next === "/" || next === "?" || next === "#" || next === "`";
@@ -194,7 +201,41 @@ function templateArgument(text, start) {
   return null;
 }
 
-function parseUrlArgument(text, openParen) {
+function extractStaticStringConstants(text) {
+  const source = String(text || "");
+  const mask = maskNonCode(source);
+  const declarations = [];
+  const declaration = /\bconst\s+([A-Za-z_$][\w$]*)\s*=/g;
+  let match;
+  while ((match = declaration.exec(mask)) && declarations.length < 500) {
+    let start = match.index + match[0].length;
+    while (/\s/.test(source[start] || "")) start += 1;
+    declarations.push({ name: match[1], start });
+  }
+
+  const constants = new Map();
+  for (const item of declarations) {
+    const quote = source[item.start];
+    if (quote !== "'" && quote !== '"') continue;
+    const parsed = quotedArgument(source, item.start, quote);
+    if (parsed && parsed.value.length <= 2_048) constants.set(item.name, parsed.value);
+  }
+  // Resolve bounded chains such as `const route = `${API_ROOT}/query`` without evaluating code.
+  for (let pass = 0; pass < Math.min(8, declarations.length); pass += 1) {
+    let changed = false;
+    for (const item of declarations) {
+      if (constants.has(item.name) || source[item.start] !== "`") continue;
+      const parsed = templateArgument(source, item.start, constants, true);
+      if (!parsed || parsed.value.length > 2_048) continue;
+      constants.set(item.name, parsed.value);
+      changed = true;
+    }
+    if (!changed) break;
+  }
+  return constants;
+}
+
+function parseUrlArgument(text, openParen, constants) {
   let start = openParen + 1;
   while (/\s/.test(text[start] || "")) start += 1;
   const quote = text[start];
@@ -204,7 +245,7 @@ function parseUrlArgument(text, openParen) {
     return { path: normalizeHttpContractPath(parsed.value), endIndex: parsed.endIndex, kind: "literal", dynamic: false, unknownPrefix: false, partialDynamic: false, reason: null };
   }
   if (quote === "`") {
-    const parsed = templateArgument(text, start);
+    const parsed = templateArgument(text, start, constants);
     if (!parsed) return { path: null, endIndex: start, kind: "dynamic", dynamic: true, reason: "unterminated URL template" };
     return {
       path: normalizeHttpContractPath(parsed.value),
@@ -239,13 +280,14 @@ function normalizedClientNames(values) {
 export function extractHttpClientCallsFromText(text, file, options = {}) {
   const source = String(text || "");
   const mask = maskNonCode(source);
+  const constants = extractStaticStringConstants(source);
   const allowed = normalizedClientNames(options.clientNames);
   const maxCalls = boundedInteger(options.maxCalls, DEFAULTS.maxCallsPerClient, 1, HARD.maxCallsPerClient);
   const calls = [];
   let truncated = false;
   const add = (clientName, method, openParen, fetch = false) => {
     if (calls.length >= maxCalls) { truncated = true; return; }
-    const parsed = parseUrlArgument(source, openParen);
+    const parsed = parseUrlArgument(source, openParen, constants);
     const fetchInfo = fetch ? fetchMethod(source, parsed.endIndex) : { method: method.toUpperCase(), uncertain: false };
     calls.push({
       file: normalizeFile(file),
@@ -334,6 +376,14 @@ function suffixShapeMatch(endpointSegments, callSegments) {
   return routeShapeMatches(endpointSegments.slice(endpointSegments.length - callSegments.length), callSegments);
 }
 
+function routeShapeContains(endpointSegments, requestedSegments) {
+  if (!requestedSegments.length || requestedSegments.length > endpointSegments.length) return false;
+  for (let start = 0; start <= endpointSegments.length - requestedSegments.length; start += 1) {
+    if (routeShapeMatches(endpointSegments.slice(start, start + requestedSegments.length), requestedSegments)) return true;
+  }
+  return false;
+}
+
 function methodMatches(endpointMethod, callMethod) {
   return endpointMethod === "ANY" || endpointMethod === "ALL" || endpointMethod === callMethod;
 }
@@ -450,7 +500,9 @@ function endpointFilter(endpoint, backendId, options) {
   if (options.method && endpoint.method !== options.method && endpoint.method !== "ANY" && endpoint.method !== "ALL") return false;
   if (options.path) {
     const requested = normalizeHttpContractPath(options.path);
-    if (!requested || !routeShapeMatches(pathSegments(normalizeHttpContractPath(endpoint.path)), pathSegments(requested))) return false;
+    const endpointSegments = pathSegments(normalizeHttpContractPath(endpoint.path));
+    const requestedSegments = pathSegments(requested);
+    if (!requested || (!routeShapeMatches(endpointSegments, requestedSegments) && !routeShapeContains(endpointSegments, requestedSegments))) return false;
   }
   if (options.changedFiles?.size) {
     const file = normalizeFile(endpoint.file);

package/src/mcp/catalog.mjs

@@ -34,12 +34,12 @@ function buildTools({tg, ti, th, ta, tar, thi, tc}) {
         {cap: 'graph', name: 'get_node', description: 'Get full details for a specific node by label or ID.', inputSchema: {type: 'object', properties: {label: {type: 'string', description: 'Node label or ID to look up'}}, required: ['label']}, run: (g, a, ctx) => tg.tGetNode(g, a, ctx)},
         {cap: 'graph', name: 'get_neighbors', description: 'Get all direct neighbors of a node with edge details (1 hop, call sites deduped). For transitive impact use get_dependents; for the impact of your current branch changes use change_impact.', inputSchema: {type: 'object', properties: {label: {type: 'string'}, relation_filter: {type: 'string', description: 'Optional: filter by relation type'}}, required: ['label']}, run: (g, a, ctx) => tg.tGetNeighbors(g, a, ctx)},
         {cap: 'graph', name: 'query_graph', description: 'Explore the graph around a concept (BFS/DFS). Returns a focused, ranked subgraph — the closest, most-connected nodes near the matched seeds, with edges among them — not the full flood; states how many nodes were reached vs shown.', inputSchema: {type: 'object', properties: {question: {type: 'string', description: 'Natural language question or keyword search'}, mode: {type: 'string', enum: ['bfs', 'dfs'], default: 'bfs'}, depth: {type: 'integer', default: 3}, context_filter: {type: 'array', items: {type: 'string'}}, seed_files: {type: 'array', items: {type: 'string'}, maxItems: 12, description: 'Optional exact repo-relative file paths. When resolved, these are the only seeds unless augment_seeds is true'}, augment_seeds: {type: 'boolean', default: false, description: 'With seed_files, also add fuzzy question-derived seeds; false keeps traversal strictly pinned'}, token_budget: {type: 'integer', description: 'Higher budget shows more nodes/edges', default: 2000}}, required: ['question']}, run: (g, a) => tg.tQueryGraph(g, a)},
-        {cap: 'graph', name: 'god_nodes', description: 'Rank connectivity hubs by unique call/import/reference neighbors, with class/method ownership reported separately from runtime connectivity. Repeated call sites do not inflate the rank.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', default: 10}}}, run: (g, a) => tg.tGodNodes(g, a)},
+        {cap: 'graph', name: 'god_nodes', description: 'Rank production-code connectivity hubs by unique call/import/reference neighbors, with class/method ownership reported separately from runtime connectivity. Repeated call sites do not inflate the rank; classified tests, generated/build output and other non-product paths are excluded by default.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', default: 10}, include_classified: {type: 'boolean', default: false, description: 'Include tests/e2e/generated/build output/mocks/stories/docs/benchmarks/temp and paths explicitly excluded by repository classification'}}}, run: (g, a, ctx) => tg.tGodNodes(g, a, ctx)},
         {cap: 'graph', name: 'shortest_path', description: 'Find the shortest path between two concepts in the knowledge graph.', inputSchema: {type: 'object', properties: {source: {type: 'string'}, target: {type: 'string'}, max_hops: {type: 'integer', default: 8}}, required: ['source', 'target']}, run: (g, a) => tg.tShortestPath(g, a)},
         {cap: 'graph', name: 'get_dependents', description: 'Transitive blast-radius of ONE node: everything that calls/imports/inherits it, directly or through intermediaries (reverse edges, ranked by proximity then connectivity). For a symbol, also follows importers of its containing file. Use before refactoring; get_neighbors shows only 1 hop, change_impact covers your whole current diff at once.', inputSchema: {type: 'object', properties: {label: {type: 'string', description: 'Node label or ID'}, depth: {type: 'integer', description: 'Max reverse hops, default 3', default: 3}, max_nodes: {type: 'integer', description: 'Max dependents to list, default 40', default: 40}}, required: ['label']}, run: (g, a) => ti.tGetDependents(g, a)},
         {cap: 'graph', name: 'change_impact', description: 'Verdict-first, symbol-aware blast radius. Parses a zero-context git diff, distinguishes additive exports from signature/body/removal risk, and reverse-traverses only exact changed seeds so a new API does not inherit every legacy importer of its file. Measured coverage is used when present; otherwise static test reachability is labelled actualCoverage=NOT_AVAILABLE. Pass `diff` for a not-checked-out PR; `files` without a diff remains a conservative fallback.', inputSchema: {type: 'object', properties: {base: {type: 'string', description: 'Base ref, e.g. origin/main or HEAD~1 (default: first existing of origin/HEAD, origin/main, origin/master, main, master)'}, diff: {type: 'string', maxLength: 2097152, description: 'Optional unified diff (prefer --unified=0) for a PR/change that is not checked out; enables symbol-level classification'}, files: {type: 'array', items: {type: 'string'}, maxItems: 500, description: 'Optional repo-relative changed-file hints. Without diff evidence these are classified conservatively rather than guessed additive'}, depth: {type: 'integer', description: 'Max reverse hops, default 2'}, max_nodes: {type: 'integer', description: 'Max impacted nodes to list, default 40'}}}, run: (g, a, ctx) => ti.tChangeImpact(g, a, ctx)},
         {cap: 'graph', name: 'git_history', description: 'Behavioral architecture evidence from bounded local git history: churn × connectivity hotspots, hidden co-change coupling, and expected test/source coupling. Reads numstat only — never commit messages, authors, or source bodies.', inputSchema: {type: 'object', properties: {months: {type: 'integer', enum: [3, 6, 12], default: 6}, max_commits: {type: 'integer', minimum: 1, maximum: 5000, default: 1000}, min_pair_count: {type: 'integer', minimum: 2, maximum: 100, default: 3}, max_pairs: {type: 'integer', minimum: 1, maximum: 500, default: 100}, top_n: {type: 'integer', minimum: 1, maximum: 50, default: 10}}}, run: (g, a, ctx) => thi.tGitHistory(g, a, ctx)},
-        {cap: 'crossrepo', name: 'trace_api_contract', description: 'Cross-repository HTTP contract and blast-radius evidence. Select a registered backend and one or more registered clients by stable repository UUID or unambiguous label; joins backend endpoints to static client calls and follows client importers to affected screens. Repository paths stay local and cannot be supplied through this tool. This capability is intentionally absent from the pinned profile.', inputSchema: {type: 'object', properties: {backend: {type: 'string', description: 'Backend repository UUID or exact unambiguous registry label'}, clients: {type: 'array', items: {type: 'string'}, minItems: 1, maxItems: 20, description: 'Client repository UUIDs or exact unambiguous registry labels'}, method: {type: 'string', enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']}, path: {type: 'string', maxLength: 2048, description: 'Optional endpoint route filter; {id}, :id and concrete parameter values are normalized'}, changed_files: {type: 'array', items: {type: 'string'}, maxItems: 500, description: 'Optional backend repo-relative changed files; only endpoints declared in those files are traced'}, include_tests: {type: 'boolean', default: false}, max_impact_depth: {type: 'integer', minimum: 0, maximum: 5, default: 2}, max_endpoints: {type: 'integer', minimum: 1, maximum: 500, default: 250}, max_matches: {type: 'integer', minimum: 1, maximum: 5000, default: 1000}, max_affected_files: {type: 'integer', minimum: 1, maximum: 500, default: 100}, top_n: {type: 'integer', minimum: 1, maximum: 50, default: 10}}, required: ['backend', 'clients']}, run: (g, a, ctx) => tc.tTraceApiContract(g, a, ctx)},
+        {cap: 'crossrepo', name: 'trace_api_contract', description: 'Cross-repository HTTP contract and blast-radius evidence. Select a registered backend and one or more registered clients by stable repository UUID or unambiguous label; joins backend endpoints to static client calls and follows client importers to affected screens. Repository paths stay local and cannot be supplied through this tool. This capability is intentionally absent from the pinned profile.', inputSchema: {type: 'object', properties: {backend: {type: 'string', description: 'Backend repository UUID or exact unambiguous registry label'}, clients: {type: 'array', items: {type: 'string'}, minItems: 1, maxItems: 20, description: 'Client repository UUIDs or exact unambiguous registry labels'}, method: {type: 'string', enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']}, path: {type: 'string', maxLength: 2048, description: 'Optional full route or segment-aligned route fragment; /query matches /edgeAnalytics/query/... and {id}, :id and concrete parameter values are normalized'}, changed_files: {type: 'array', items: {type: 'string'}, maxItems: 500, description: 'Optional backend repo-relative changed files; only endpoints declared in those files are traced'}, include_tests: {type: 'boolean', default: false}, max_impact_depth: {type: 'integer', minimum: 0, maximum: 5, default: 2}, max_endpoints: {type: 'integer', minimum: 1, maximum: 500, default: 250}, max_matches: {type: 'integer', minimum: 1, maximum: 5000, default: 1000}, max_affected_files: {type: 'integer', minimum: 1, maximum: 500, default: 100}, top_n: {type: 'integer', minimum: 1, maximum: 50, default: 10}}, required: ['backend', 'clients']}, run: (g, a, ctx) => tc.tTraceApiContract(g, a, ctx)},
         {cap: 'graph', name: 'get_community', description: 'Get all nodes in a community by community ID (0-indexed by size).', inputSchema: {type: 'object', properties: {community_id: {type: 'integer', description: 'Community ID (0-indexed by size)'}}, required: ['community_id']}, run: (g, a) => tg.tGetCommunity(g, a)},
         {cap: 'search', name: 'search_code', description: 'Full-text or regex search across the repo source (ripgrep-backed, Node fallback). The graph only stores structure — use this to find literal text/patterns, then get_node/get_neighbors for structure.', inputSchema: {type: 'object', properties: {query: {type: 'string', description: 'text or regex to search for'}, is_regex: {type: 'boolean', default: false}, glob: {type: 'string', description: 'optional path glob, e.g. "*.js" or "src/**"'}, max_results: {type: 'integer', default: 40}}, required: ['query']}, run: (g, a, ctx) => searchCode({repoRoot: ctx.repoRoot, resolveRg}, a)},
         {cap: 'source', name: 'read_source', description: "Read the actual source of a node (by label/ID) or a repo-relative file path — the symbol's lines with context. The graph stores only locations, not source text. For a path read, pass start_line to anchor the window anywhere in the file (otherwise it shows the head).", inputSchema: {type: 'object', properties: {label: {type: 'string', description: 'node label or ID'}, path: {type: 'string', description: 'or a repo-relative file path'}, start_line: {type: 'integer', description: 'anchor line: window = start_line-before .. start_line+after'}, before: {type: 'integer', default: 3}, after: {type: 'integer', default: 40}}}, run: (g, a, ctx) => readSource({repoRoot: ctx.repoRoot, resolveNode, isSymbol}, g, a)},
@@ -63,8 +63,10 @@ function buildTools({tg, ti, th, ta, tar, thi, tc}) {
         {cap: 'hosted', name: 'pull_architecture_contract', description: 'NETWORK / explicit hosted profile: fetch the owner-approved target architecture for the active stable repository UUID, validate it and cache it locally. Sends only the opaque UUID with bearer auth; never source or paths.', inputSchema: {type: 'object', properties: {timeout_ms: {type: 'integer', minimum: 1000, maximum: 120000, default: 30000}}}, run: (g, a, ctx) => ta.tPullArchitectureContract(g, a, ctx)},
         {cap: 'hosted', name: 'sync_graph', description: 'NETWORK / explicit hosted profile, off until configured: derive a bounded evidence snapshot locally and send it with an allowlisted graph payload to an endpoint you configure (env WEAVATRIX_SYNC_URL, WEAVATRIX_SYNC_TOKEN bearer auth). Local analyzers may read source files, but file bodies, snippets, absolute paths and unknown fields are never uploaded. Payload v3 includes architecture/health/stack/package evidence; request v2 only for graph-only compatibility.', inputSchema: {type: 'object', properties: {payload_version: {type: 'integer', enum: [2, 3], default: 3, description: '3 includes the evidence snapshot; 2 is graph-only compatibility and is never selected as a silent fallback'}, timeout_ms: {type: 'integer', minimum: 1000, maximum: 120000, default: 30000, description: 'Network timeout in milliseconds'}}}, run: (g, a, ctx) => ta.tSyncGraph(g, a, ctx)},
     ]
-    // Every tool supports the same machine-output switch. structuredContent is returned regardless;
-    // output_format=json mirrors that envelope into TextContent for older workflow runners.
+    // Every tool supports the same machine-output switch. Text mode is TextContent-only so large
+    // analysis payloads are not duplicated into an agent's context; JSON opts into structuredContent
+    // and mirrors that envelope into TextContent for older workflow runners. Since MCP output schemas
+    // apply to every invocation, tools do not advertise one conditionally here.
     return tools.map((tool) => ({
         ...tool,
         inputSchema: {
@@ -75,11 +77,10 @@ function buildTools({tg, ti, th, ta, tar, thi, tc}) {
                     type: 'string',
                     enum: ['text', 'json'],
                     default: 'text',
-                    description: 'text keeps the concise summary; json mirrors the stable structuredContent envelope',
+                    description: 'text returns only the concise TextContent summary; json also returns and mirrors the stable structuredContent envelope',
                 },
             },
         },
-        outputSchema: {type: 'object', additionalProperties: true},
     }))
 }
 

package/src/mcp/tool-result.mjs

@@ -1,7 +1,6 @@
-// MCP tool results keep a concise human summary and a stable machine-readable envelope together.
-// Older clients continue to consume TextContent; MCP 2025-06 clients can use structuredContent
-// directly without scraping prose. Tool implementations may opt into richer `result` data through
-// toolResult(), while legacy string-returning tools still receive a deterministic envelope.
+// Text mode stays genuinely compact for agents and older clients: it returns TextContent only.
+// JSON mode adds the stable machine-readable structuredContent envelope and mirrors that envelope
+// into TextContent for workflow runners that cannot consume structured results directly.
 
 export const TOOL_RESULT_SCHEMA = 'weavatrix.tool.v1'
 
@@ -44,8 +43,12 @@ export function normalizeToolResult({toolName, value, args, ctx, refresh, warnin
         page: rich ? (value.page || {}) : {},
         ...(rich && value.completeness ? {completeness: value.completeness} : {}),
     }
+    const json = args?.output_format === 'json'
     return {
-        text: args?.output_format === 'json' ? JSON.stringify(structured, null, 2) : `Repository: ${structured.repo.name}\n${text}`,
-        structured,
+        text: json ? JSON.stringify(structured, null, 2) : `Repository: ${structured.repo.name}\n${text}`,
+        // MCP output schemas apply to every invocation of a tool. The catalog intentionally does not
+        // advertise one because text mode must not attach a second, potentially very large payload.
+        // JSON callers still receive the stable structured result as an optional MCP extension.
+        structured: json ? structured : undefined,
     }
 }

package/src/mcp/tools-architecture.mjs

@@ -1,9 +1,26 @@
 // Executable target architecture for agents: read the active contract before a change, then run the
 // same deterministic verifier after it. No tool silently edits policy or accepts debt.
 import {contractForChange, loadArchitectureContract, normalizeArchitectureContract, verifyArchitecture} from '../analysis/architecture-contract.js'
+import {createPathClassifier, hasPathClass} from '../path-classification.js'
 import {detectRepoStack} from '../scan/discover.js'
 import {toolResult} from './tool-result.mjs'
 
+const PROVISIONAL_BUDGETS = Object.freeze({
+    runtimeCycles: 0,
+    maxFileLoc: 300,
+    maxFunctionLoc: 120,
+    maxCyclomatic: 15,
+    maxModuleFiles: 80,
+    minModuleCohesion: .5,
+    maxModuleBoundaryRatio: .65,
+})
+
+const remediation = () => ({
+    offlinePath: '.weavatrix/architecture.json',
+    hostedAction: 'Open Architecture -> choose intended style -> Save target & baseline',
+    nextTool: 'verify_architecture',
+})
+
 const stackIds = (repoRoot) => {
     try {
         const stack = detectRepoStack(repoRoot)
@@ -40,25 +57,62 @@ function starterContract(g) {
     return normalizeArchitectureContract({
         name: 'Proposed no-regressions baseline', style: 'custom', enforcement: 'ratchet', components,
         dependencyRules: [],
-        budgets: {runtimeCycles: 0, maxFileLoc: 300, maxFunctionLoc: 120, maxCyclomatic: 15, maxModuleFiles: 80, minModuleCohesion: .5, maxModuleBoundaryRatio: .65},
+        budgets: PROVISIONAL_BUDGETS,
         technologies: {required: [], forbidden: []}, exceptions: [], ratchet: {baseline: {fingerprints: [], metrics: {}}},
     })
 }
 
-function notConfiguredResult(g, action) {
-    const starter = starterContract(g)
+function notConfiguredResult(g, action, {includeStarter = false} = {}) {
+    const starter = includeStarter ? starterContract(g) : null
+    const starterText = starter
+        ? ` A source-free starter with ${starter.components.length} path territories is available in JSON output from this lookup.`
+        : ''
+    return toolResult([
+        `Architecture ${action} is NOT_CONFIGURED — no target contract is active.${starterText}`,
+        'Next: save .weavatrix/architecture.json (offline) or approve a target in Hosted, then call verify_architecture.',
+    ].join('\n'), {
+        state: 'NOT_CONFIGURED',
+        remediation: remediation(),
+        ...(starter ? {
+            starterSummary: {components: starter.components.length, budgets: starter.budgets},
+            starterContract: starter,
+        } : {}),
+    })
+}
+
+function classifyChangeFiles(files, repoRoot) {
+    const classifier = createPathClassifier(repoRoot)
+    const normalized = [...new Set((Array.isArray(files) ? files : [])
+        .slice(0, 200)
+        .map((file) => String(file || '').replace(/\\/g, '/').replace(/^\.\//, ''))
+        .filter((file) => file && !file.startsWith('../') && !file.includes('/../')))]
+        .sort((a, b) => a.localeCompare(b))
+    const testOnlyFiles = normalized.filter((file) => hasPathClass(classifier.explain(file), 'test', 'e2e'))
+    const testOnly = new Set(testOnlyFiles)
+    return {files: normalized, productFiles: normalized.filter((file) => !testOnly.has(file)), testOnlyFiles}
+}
+
+function provisionalPreflight(g, args, ctx) {
+    const surfaces = classifyChangeFiles(args?.files, ctx?.repoRoot)
+    const intent = String(args?.intent || '').slice(0, 500)
+    const budgetText = [
+        `no new runtime cycles (baseline ${PROVISIONAL_BUDGETS.runtimeCycles})`,
+        `file <= ${PROVISIONAL_BUDGETS.maxFileLoc} LOC`,
+        `function <= ${PROVISIONAL_BUDGETS.maxFunctionLoc} LOC`,
+        `cyclomatic <= ${PROVISIONAL_BUDGETS.maxCyclomatic}`,
+    ].join('; ')
     return toolResult([
-        `Architecture ${action} is NOT_CONFIGURED — no target contract is active.`,
-        `A source-free starter was inferred from ${starter.components.length} path territories; review it before saving because folders are evidence, not semantic truth.`,
-        'Next: save it as .weavatrix/architecture.json (offline) or approve it in the hosted Architecture editor, then call verify_architecture.',
+        `Architecture preflight is NOT_CONFIGURED for ${surfaces.files.length} file(s)${intent ? ` — ${intent}` : ''}.`,
+        `Provisional no-regression guidance (not enforced policy): ${budgetText}.`,
+        `${surfaces.productFiles.length} product file(s); ${surfaces.testOnlyFiles.length} test-only file(s). Save a target contract to make these budgets enforceable.`,
     ].join('\n'), {
         state: 'NOT_CONFIGURED',
-        remediation: {
-            offlinePath: '.weavatrix/architecture.json',
-            hostedAction: 'Open Architecture → choose intended style → Save target & baseline',
-            nextTool: 'verify_architecture',
-        },
-        starterContract: starter,
+        guidance: 'PROVISIONAL_BUDGETS',
+        enforceable: false,
+        intent,
+        ...surfaces,
+        provisionalBudgets: PROVISIONAL_BUDGETS,
+        remediation: remediation(),
     })
 }
 
@@ -68,7 +122,7 @@ export function tGetArchitectureContract(g, args, ctx) {
         const text = loaded.error
             ? `Architecture contract is invalid (${loaded.source || 'unknown'}): ${loaded.error}`
             : 'No target architecture contract is active.'
-        if (!loaded.error) return notConfiguredResult(g, 'lookup')
+        if (!loaded.error) return notConfiguredResult(g, 'lookup', {includeStarter: true})
         return toolResult(text, {state: 'ERROR', source: loaded.source, error: loaded.error})
     }
     const contract = loaded.contract
@@ -79,17 +133,19 @@ export function tGetArchitectureContract(g, args, ctx) {
     ].join('\n'), {state: 'ACTIVE', source: loaded.source, contract})
 }
 
-export function tPrepareChange(g, args, ctx) {
+export function tPrepareChange(g, args = {}, ctx) {
     const loaded = activeContract(ctx)
-    if (!loaded.contract) return notConfiguredResult(g, 'preflight')
+    if (!loaded.contract) return provisionalPreflight(g, args, ctx)
     const prepared = contractForChange(loaded.contract, args.files)
+    const surfaces = classifyChangeFiles(prepared.files, ctx?.repoRoot)
     const intent = String(args.intent || '').slice(0, 500)
     return toolResult([
         `Architecture preflight for ${prepared.files.length} file(s)${intent ? ` — ${intent}` : ''}.`,
         `Affected target components: ${prepared.components.join(', ') || '(unmapped)'}.`,
+        ...(surfaces.testOnlyFiles.length ? [`Test-only surface: ${surfaces.testOnlyFiles.join(', ')}.`] : []),
         `Applicable rules: ${prepared.rules.map((rule) => rule.id).join(', ') || '(none)'}.`,
         'Run verify_architecture after the edit; do not silently add an exception or rewrite the target contract.',
-    ].join('\n'), {state: 'READY', intent, contractHash: loaded.contract.contractHash, ...prepared})
+    ].join('\n'), {state: 'READY', intent, contractHash: loaded.contract.contractHash, ...prepared, productFiles: surfaces.productFiles, testOnlyFiles: surfaces.testOnlyFiles})
 }
 
 export function tVerifyArchitecture(g, args, ctx) {

package/src/mcp/tools-graph-hubs.mjs

@@ -1,14 +1,30 @@
 // Connectivity-hub reporting, split from the general graph query tools.
 import {connList} from './graph-context.mjs'
+import {createPathClassifier, hasPathClass} from '../path-classification.js'
 
 const isCompileTimeEdge = (edge) => edge?.typeOnly === true || edge?.compileOnly === true
+const NON_PRODUCT_CLASSES = Object.freeze(['test', 'e2e', 'generated', 'mock', 'story', 'docs', 'benchmark', 'temp'])
+const sourceFileOf = (node) => String(node?.source_file || (node?.file_type === 'code' ? node?.id : '') || '').replace(/\\/g, '/')
 
-export function tGodNodes(g, {top_n = 10} = {}) {
+export function tGodNodes(g, {top_n = 10, include_classified = false} = {}, ctx = {}) {
     const n = Math.max(1, Math.min(100, Number(top_n) || 10))
+    const classifier = createPathClassifier(ctx.repoRoot || null)
+    const classificationByFile = new Map()
+    const isNonProduct = (node) => {
+        if (include_classified === true) return false
+        const file = sourceFileOf(node)
+        if (!file) return false
+        if (!classificationByFile.has(file)) classificationByFile.set(file, classifier.explain(file))
+        const info = classificationByFile.get(file)
+        return info.excluded || hasPathClass(info, ...NON_PRODUCT_CLASSES)
+    }
+    const excludedIds = new Set(g.nodes.filter(isNonProduct).map((node) => String(node.id)))
     const scored = g.nodes
+        .filter((node) => !excludedIds.has(String(node.id)))
         .map((node) => {
-            const rawOuts = g.out.get(String(node.id)) || []
-            const rawIns = g.inn.get(String(node.id)) || []
+            // Coupling from a suppressed artifact must not inflate an otherwise valid product hub.
+            const rawOuts = (g.out.get(String(node.id)) || []).filter((edge) => !excludedIds.has(String(edge.id)))
+            const rawIns = (g.inn.get(String(node.id)) || []).filter((edge) => !excludedIds.has(String(edge.id)))
             const outs = connList(rawOuts)
             const ins = connList(rawIns)
             const ownedMethods = new Set(rawOuts.filter((e) => e.relation === 'method').map((e) => String(e.id)))
@@ -54,5 +70,8 @@ export function tGodNodes(g, {top_n = 10} = {}) {
         ...occurrenceHotspots.map((r) =>
             `  ${r.node.label ?? r.node.id}  (${r.occurrences} occurrences across ${r.deg} unique neighbors; ${r.occurrences - r.deg} repeats)  [${r.node.id}]`
         ),
+        excludedIds.size > 0 && include_classified !== true
+            ? `${excludedIds.size} node(s) classified as tests/e2e/generated/build output/mocks/stories/docs/benchmarks/temp or explicitly excluded were omitted; pass include_classified:true to inspect them.`
+            : null,
     ].filter((line) => line != null).join('\n')
 }

package/src/mcp/tools-history.mjs

@@ -1,8 +1,20 @@
 // Behavioral architecture evidence from bounded, local git history.
-import {analyzeGitHistory, formatGitHistoryAnalytics} from '../analysis/git-history.js'
+import {analyzeGitHistory, boundGitHistoryAnalytics, formatGitHistoryAnalytics} from '../analysis/git-history.js'
 import {toolResult} from './tool-result.mjs'
 
-export async function tGitHistory(g, args, ctx) {
+export function gitHistoryToolResult(result, args = {}) {
+    const bounded = boundGitHistoryAnalytics(result, {topN: args.top_n})
+    return toolResult(formatGitHistoryAnalytics(bounded.result, {topN: args.top_n}), bounded.result, {
+        page: bounded.page,
+        completeness: {
+            status: result.status,
+            complete: result.completeness?.complete === true,
+            reasons: result.completeness?.reasons || [],
+        },
+    })
+}
+
+export async function tGitHistory(g, args = {}, ctx) {
     if (!ctx?.repoRoot) return toolResult('Git history intelligence is unavailable: no repository root is active.', {status: 'unavailable'})
     const result = await analyzeGitHistory({
         repoRoot: ctx.repoRoot,
@@ -12,11 +24,5 @@ export async function tGitHistory(g, args, ctx) {
         maxPairs: args.max_pairs,
         minPairCount: args.min_pair_count,
     })
-    return toolResult(formatGitHistoryAnalytics(result, {topN: args.top_n}), result, {
-        completeness: {
-            status: result.status,
-            complete: result.completeness?.complete === true,
-            reasons: result.completeness?.reasons || [],
-        },
-    })
+    return gitHistoryToolResult(result, args)
 }

package/src/mcp/tools-impact-change.mjs

@@ -214,7 +214,7 @@ export function tChangeImpactV2(g, args = {}, ctx = {}) {
         '',
         impacted.length
             ? `Blast radius: ${impacted.length} impacted node(s) within ${maxDepth} reverse hop(s) (${runtimeImpacted} runtime, ${compileImpacted} compile-time-only), showing ${shown.length}:`
-            : seeds.size ? `Blast radius: nothing else depends on the exact changed symbols within ${maxDepth} hop(s).` : `Blast radius: 0 — additive/metadata-only changes do not inherit the containing file's legacy importers.`,
+            : seeds.size ? `Blast radius: nothing else depends on the exact changed symbols within ${maxDepth} hop(s).` : `Blast radius: 0 — additive, metadata-only, and test-only changes do not inherit the containing file's legacy importers.`,
         hasCoverage
             ? 'Test evidence: measured coverage is shown where mapped; static reachability remains separate in structured output.'
             : `Test evidence: actualCoverage NOT_AVAILABLE; static paths only (${staticTests.reachableFiles}/${staticTests.productFiles} product files reachable from indexed tests).`,

package/src/mcp-server.mjs

@@ -217,7 +217,9 @@ async function main() {
                         if (schemaWarning) text += `\n\nWarning: ${schemaWarning.message}`
                         if (staleLine && staleNotices.shouldShow({line: staleLine, graphPath: callCtx.graphPath, force: tool.name === 'graph_stats'})) text += `\n\n${staleLine}`
                     }
-                    return reply(id, {content: [{type: 'text', text}], structuredContent: normalized.structured})
+                    const response = {content: [{type: 'text', text}]}
+                    if (normalized.structured) response.structuredContent = normalized.structured
+                    return reply(id, response)
                 } catch (e) {
                     log(`tool ${params?.name} threw: ${e.stack || e.message}`)
                     return reply(id, {content: [{type: 'text', text: `Tool error: ${e.message}`}], isError: true})

package/src/path-classification.js

@@ -53,6 +53,11 @@ const DEFAULT_RULES = [
     pattern: "generated/OpenAPI output path",
     regex: /(^|\/)(?:generated|gen|openapi[-_]?generated|generated[-_]?client|api[-_]?client[-_]?generated)(\/|$)/i,
   },
+  {
+    category: "generated",
+    pattern: "conventional build output path",
+    regex: /(^|\/)(?:dist|build|out|coverage|\.next)(\/|$)/i,
+  },
   {
     category: "mock",
     pattern: "mock/fixture path or mockData filename",