weavatrix 0.2.0 → 0.2.2

package/src/mcp/catalog.mjs

@@ -30,16 +30,58 @@ export const HOT_FILES = ['tools-graph.mjs', 'tools-impact.mjs', 'tools-health.m
 
 function buildTools({tg, ti, th, ta, tar, thi, tc}) {
     const tools = [
-        {cap: 'graph', name: 'graph_stats', description: 'Return summary statistics: node count, edge count, communities, confidence breakdown, and graph build time vs repo HEAD (staleness).', inputSchema: {type: 'object', properties: {}}, run: (g, a, ctx) => tg.tGraphStats(g, ctx)},
+        {cap: 'graph', name: 'graph_stats', description: 'Return summary statistics: node count, edge count, communities, versioned edge-provenance/legacy-confidence breakdowns, and graph build time vs repo HEAD (staleness).', inputSchema: {type: 'object', properties: {}}, run: (g, a, ctx) => tg.tGraphStats(g, ctx)},
         {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, handler-liveness and blast-radius evidence. Select a registered backend and one or more registered clients; joins backend endpoints to built-in, configured, or conservatively auto-discovered HTTP wrappers. Medium/high-confidence external matches mark a handler NOT_DEAD_EXTERNAL_USE; no match remains UNKNOWN. Repository paths stay local and cannot be supplied through this tool.',
+            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'},
+                    client_names: {type: 'array', items: {type: 'string', pattern: '^[A-Za-z_$][\\w$]{0,127}$'}, maxItems: 40, uniqueItems: true, description: 'Extra object-style clients whose .get/.post/... methods perform HTTP requests; persistent per-repo configuration belongs in .weavatrix.json httpContracts.clientNames'},
+                    client_wrappers: {
+                        type: 'array', maxItems: 100,
+                        description: 'Fixed-method wrapper calls. Use call+method for get(url), or object+member+method for transport.send(url). url_argument is zero-based.',
+                        items: {
+                            type: 'object', additionalProperties: false,
+                            properties: {
+                                call: {type: 'string', pattern: '^[A-Za-z_$][\\w$]{0,127}$'},
+                                object: {type: 'string', pattern: '^[A-Za-z_$][\\w$]{0,127}$'},
+                                member: {type: 'string', pattern: '^[A-Za-z_$][\\w$]{0,127}$'},
+                                method: {type: 'string', enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']},
+                                url_argument: {type: 'integer', minimum: 0, maximum: 5, default: 0},
+                            },
+                            anyOf: [
+                                {required: ['call', 'method'], not: {anyOf: [{required: ['object']}, {required: ['member']}]}},
+                                {required: ['object', 'member', 'method'], not: {required: ['call']}},
+                            ],
+                        },
+                    },
+                    auto_discover_wrappers: {type: 'boolean', default: true, description: 'Discover only simple unambiguous functions that forward a URL parameter directly to a known object-style HTTP client'},
+                    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 +105,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 +119,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/graph-context.mjs

@@ -8,6 +8,7 @@ import {spawnSync} from 'node:child_process'
 import {childProcessEnv} from '../child-env.js'
 import {resolveRepoPath} from '../repo-path.js'
 import {isStructuralRelation} from '../graph/relations.js'
+import {edgeProvenance} from '../graph/edge-provenance.js'
 
 // ---- graph load + indexes -----------------------------------------------------------------------
 export function loadGraph(path) {
@@ -36,6 +37,7 @@ export function loadGraph(path) {
         const metadata = {
             relation: e.relation,
             confidence: e.confidence,
+            provenance: edgeProvenance(e),
             ...(e.typeOnly === true ? {typeOnly: true} : {}),
             ...(e.compileOnly === true ? {compileOnly: true} : {}),
             ...(Number.isInteger(e.line) ? {line: e.line} : {}),
@@ -51,6 +53,7 @@ export function loadGraph(path) {
         nodes, links, byId, byLabel, out, inn,
         repoBoundaryV: Number(raw.repoBoundaryV) || 0,
         edgeTypesV: Number(raw.edgeTypesV) || 0,
+        edgeProvenanceV: Number(raw.edgeProvenanceV) || 0,
         barrelResolutionV: Number(raw.barrelResolutionV) || 0,
         extractorSchemaV: Number(raw.extractorSchemaV) || 0,
         extImportsV: Number(raw.extImportsV) || 0,

package/src/mcp/sync-payload.mjs

@@ -1,6 +1,7 @@
 // Versioned, explicit wire schema for sync_graph. Never forward graph.json wholesale: it is a local
 // cache file and may contain future fields or attacker-injected data that are not safe to upload.
 import {sanitizeEvidenceSnapshot} from './sync-evidence.mjs';
+import {edgeProvenance} from '../graph/edge-provenance.js';
 
 const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
 const ABSOLUTE_PATH_FRAGMENT = /(?:^|[\/\s"'`(=])[a-z]:[\\/]|(?:^|[\s"'`(=])(?:\\\\[^\\/\s]+(?:[\\/]|$)|file:(?:\/\/)?[\\/]|\/(?!\/)[^\s])/i;
@@ -202,6 +203,8 @@ function sanitizeLinkV3(value) {
         if (safe) out[key] = safe;
         else delete out[key];
     }
+    const provenance = edgeProvenance(value);
+    if (provenance !== 'UNKNOWN') out.provenance = provenance;
     const specifier = privacySafeText(value.specifier, 1024);
     if (specifier) out.specifier = specifier;
     else delete out.specifier;
@@ -265,6 +268,9 @@ export function createSyncPayloadV3(raw, evidence) {
     // Reuse the v2 schema gates, but construct v3 arrays independently so the stricter path/identity
     // rules cannot change graph-only compatibility for existing endpoints.
     const base = createSyncPayload(raw);
+    if (!Number.isInteger(raw.edgeProvenanceV) || raw.edgeProvenanceV < 1) {
+        throw new Error('graph predates edge provenance metadata');
+    }
     assertArrayLimit(raw, 'nodes', MAX_SYNC_NODES);
     assertArrayLimit(raw, 'links', MAX_SYNC_LINKS);
     assertArrayLimit(raw, 'externalImports', MAX_SYNC_EXTERNAL_IMPORTS);
@@ -285,6 +291,7 @@ export function createSyncPayloadV3(raw, evidence) {
         syncPayloadV: 3,
         repoBoundaryV: base.repoBoundaryV,
         edgeTypesV: base.edgeTypesV,
+        edgeProvenanceV: Number.isInteger(raw.edgeProvenanceV) ? raw.edgeProvenanceV : 0,
         extImportsV: base.extImportsV,
         complexityV: base.complexityV,
         evidenceV: 1,

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-actions.mjs

@@ -41,6 +41,7 @@ export async function tRebuildGraph(g, args, ctx) {
     const before = g?.nodes ? {
         nodes: g.nodes, links: g.links,
         edgeTypesV: g.edgeTypesV || 0,
+        edgeProvenanceV: g.edgeProvenanceV || 0,
         barrelResolutionV: g.barrelResolutionV || 0,
         extractorSchemaV: g.extractorSchemaV || 0,
     } : null
@@ -73,6 +74,7 @@ export async function tOpenRepo(g, args, ctx) {
         try {
             const saved = JSON.parse(readFileSync(graphPath, 'utf8'))
             upgrade = !Number.isInteger(saved.edgeTypesV) || saved.edgeTypesV < 2
+                || !Number.isInteger(saved.edgeProvenanceV) || saved.edgeProvenanceV < 1
         } catch {
             upgrade = true
         }
@@ -80,7 +82,7 @@ export async function tOpenRepo(g, args, ctx) {
     if (!existsSync(graphPath) || upgrade) {
         if (args.build === false) {
             return upgrade
-                ? `The existing graph for ${repoPath} predates compile-only edge metadata (edge schema v2). Re-call without build:false to upgrade it before switching.`
+                ? `The existing graph for ${repoPath} predates current typed-edge/provenance metadata. Re-call without build:false to upgrade it before switching.`
                 : `No graph yet for ${repoPath} (expected at ${graphPath}). Re-call without build:false to build one — large repos can take minutes.`
         }
         const mode = ['no-tests', 'tests-only', 'full'].includes(args.mode) ? args.mode : 'full'
@@ -99,7 +101,7 @@ export async function tOpenRepo(g, args, ctx) {
         return `Failed to load ${graphPath} — still targeting the previous repo (${prev.repoRoot || 'none'}).`
     }
     registerRepository({repoPath, graphDir: graphOutDirForRepo(repoPath), graphHome: graphHomeDir()})
-    const buildNote = built ? (upgrade ? ' (graph upgraded to edge metadata v2)' : ' (graph built fresh)') : ''
+    const buildNote = built ? (upgrade ? ' (graph upgraded to current edge metadata)' : ' (graph built fresh)') : ''
     return `Opened ${repoPath}${buildNote}: ${loaded.nodes.length} nodes / ${loaded.links.length} edges. All tools now target this repo.`
 }
 

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-company.mjs

@@ -9,6 +9,7 @@ import {liveRepositoryRecords} from '../graph/repo-registry.js'
 import {loadGraph} from './graph-context.mjs'
 import {toolResult} from './tool-result.mjs'
 
+const CROSS_REPO_HTTP_CONTRACT_V = 2
 const selectorText = (value) => String(value ?? '').trim()
 
 function selectRecord(records, selector) {
@@ -120,6 +121,10 @@ function verdictFor(analysis) {
         affectedScreens: affectedScreens.size,
         methodMismatches: analysis.totals.methodMismatches,
         uncertainCalls: analysis.totals.uncertainCalls,
+        notDeadExternalUse: analysis.totals.notDeadExternalUse,
+        notDeadExternalHandlers: analysis.totals.notDeadExternalHandlers,
+        possibleExternalUse: analysis.totals.possibleExternalUse,
+        unknownLiveness: analysis.totals.unknownLiveness,
     }
 }
 
@@ -188,7 +193,7 @@ export async function tTraceApiContract(_g, args = {}, ctx = {}) {
         return toolResult(
             `VERDICT PARTIAL — selected repository graphs could not all be refreshed and loaded.\nCompleteness: partial — ${reasons.join('; ')}.`,
             {
-                crossRepoHttpContractV: 1,
+                crossRepoHttpContractV: CROSS_REPO_HTTP_CONTRACT_V,
                 status: 'PARTIAL',
                 repositories: {
                     backend: publicRecord(backend, backendAlias),
@@ -209,6 +214,9 @@ export async function tTraceApiContract(_g, args = {}, ctx = {}) {
             path: args.path,
             changedFiles: args.changed_files,
             includeTests: args.include_tests === true,
+            clientNames: args.client_names,
+            wrappers: args.client_wrappers,
+            autoDiscoverWrappers: args.auto_discover_wrappers !== false,
             maxImpactDepth: args.max_impact_depth,
             maxEndpoints: args.max_endpoints,
             maxMatches: args.max_matches,
@@ -236,7 +244,7 @@ export async function tTraceApiContract(_g, args = {}, ctx = {}) {
                 const screens = endpoint.affected.screens.slice(0, 3)
                     .map((screen) => `    screen ${screen.client}:${screen.file} (distance ${screen.distance})`)
                 return [
-                    `  ${endpoint.method} ${endpoint.path}${location} → ${endpoint.callsites.length} callsite(s), ${endpoint.affected.screens.length} screen(s), ${endpoint.affected.files.length} affected file(s)`,
+                    `  ${endpoint.method} ${endpoint.path}${location} [${endpoint.liveness.status}${endpoint.handler ? `; handler ${endpoint.handler}` : ''}] → ${endpoint.callsites.length} callsite(s), ${endpoint.affected.screens.length} screen(s), ${endpoint.affected.files.length} affected file(s)`,
                     ...callsites,
                     ...screens,
                 ]
@@ -246,7 +254,7 @@ export async function tTraceApiContract(_g, args = {}, ctx = {}) {
                 : `Completeness: partial — ${completeness.reasons.join('; ')}.`,
         ]
         const result = {
-            crossRepoHttpContractV: 1,
+            crossRepoHttpContractV: CROSS_REPO_HTTP_CONTRACT_V,
             verdict,
             repositories: {
                 backend: publicRecord(backend, backendAlias),

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-graph.mjs

@@ -6,6 +6,7 @@ import {
     resolveNodeInfo, resolveNode, ambiguityNote, findSeeds, resolveSeedFiles, undirectedNeighbors,
     graphStaleness, fileStalenessNote,
 } from './graph-context.mjs'
+import {summarizeEdgeProvenance} from '../graph/edge-provenance.js'
 
 const compileKind = (edge) => edge?.typeOnly === true ? 'type-only' : edge?.compileOnly === true ? 'compile-only' : null
 
@@ -34,15 +35,17 @@ export function tGraphStats(g, ctx) {
             .map(([k, v]) => `${k}: ${v}`)
             .join(', ')
     const freshness = ctx ? graphStaleness(ctx) : null
+    const provenance = summarizeEdgeProvenance(g.links)
     return [
         `Graph summary`,
         ctx?.repoRoot ? `- Repo: ${ctx.repoRoot}` : null,
         `- Nodes: ${g.nodes.length} (${files} files, ${symbols} symbols)`,
         `- Edges: ${g.links.length}`,
         g.edgeTypesV ? `- Typed-edge metadata: v${g.edgeTypesV} (${typeOnlyEdges} type-only, ${compileOnlyEdges} compile-only edges)` : `- Typed-edge metadata: unavailable (rebuild_graph required)`,
+        g.edgeProvenanceV ? `- Edge provenance: v${g.edgeProvenanceV} (${fmt(provenance.counts)}; ${provenance.complete ? 'complete' : `${provenance.counts.UNKNOWN} unclassified`})` : `- Edge provenance: unavailable (rebuild_graph required)`,
         g.barrelResolutionV ? `- Barrel resolution: v${g.barrelResolutionV} (semantic tools look through JS/TS re-export facades)` : `- Barrel resolution: unavailable (rebuild_graph required for JS/TS barrel transparency)`,
         `- Relations: ${fmt(relCount)}`,
-        Object.keys(confCount).length ? `- Confidence: ${fmt(confCount)}` : null,
+        Object.keys(confCount).length ? `- Legacy confidence: ${fmt(confCount)}` : null,
         `- Communities: ${comm.size} (top by size: ${topComm.map(([c, n]) => `#${c}=${n}`).join(', ')})`,
         freshness?.builtAt ? `- Built: ${freshness.builtAt.toISOString()}${freshness.headAt ? ` (repo HEAD committed ${freshness.headAt.toISOString()})` : ''}` : null,
     ]

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/tools-impact.mjs

@@ -112,6 +112,7 @@ export async function tGraphDiff(g, args, ctx) {
         nodes: (graph.nodes || []).filter((n) => String(n.id).startsWith(filter)),
         links: (graph.links || []).filter((l) => String(edgeEndpoint(l.source)).startsWith(filter) || String(edgeEndpoint(l.target)).startsWith(filter)),
         edgeTypesV: graph.edgeTypesV || 0,
+        edgeProvenanceV: graph.edgeProvenanceV || 0,
         barrelResolutionV: graph.barrelResolutionV || 0,
         extractorSchemaV: graph.extractorSchemaV || 0,
     } : graph

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",