weavatrix 0.2.9 → 0.2.10

package/README.md

@@ -1,18 +1,29 @@
 # Weavatrix
 
-**Code graph & blast-radius MCP server for AI coding agents.**
-
-Weavatrix builds and compares the living architecture of any local repository: files, symbols,
-imports, calls, inheritance, health findings, clone families and Git-history coupling. It serves that
-evidence to Claude Code, Codex, or any MCP client for change impact, transitive dependents, health
-audit, clone detection and coverage mapping. Text search is included as a convenience, not the product
-core. **38 tools available; 34 enabled by the default offline profile. Local-first: with
+**Local repository intelligence for AI coding agents — understand the application quickly, then change it with evidence.**
+
+Weavatrix builds a reusable living graph of any local repository: files, symbols, imports, calls,
+inheritance, health findings, clone families and Git-history coupling. It gives Claude Code, Codex,
+or any MCP client a bounded map for fast application understanding and lower repeated context, then
+reuses the same graph for change impact, Health, dead-code review, duplicates, history and intended-
+architecture safeguards. Text search is included as a supporting source check, not the product core.
+**38 tools available; 34 enabled by the default offline profile. Local-first: with
 the defaults, no repository data leaves your machine.**
 
 - Website: [weavatrix.com](https://weavatrix.com)
 - Source: [github.com/sergii-ziborov/weavatrix](https://github.com/sergii-ziborov/weavatrix)
 - npm: [`weavatrix`](https://www.npmjs.com/package/weavatrix) — `npx -y weavatrix <repoRoot>`
 
+## One graph, many views
+
+The 38 MCP methods are not one linear workflow. They project the same reusable graph into the
+smallest view needed for a task: repository and build state; modules, communities, hubs, neighbors
+and paths; exact symbols and bounded source context; endpoint and cross-repository API flow; symbol
+and change-set blast radius; graph revision and behavioral Git history; Health, dependencies,
+vulnerabilities, dead code, clones, coverage and hot paths; proof-carrying change verification;
+intended-architecture contracts and ratchets; local multi-repository work; and explicit,
+preview-confirmed Hosted exchange.
+
 ## Why
 
 An AI agent editing code without architecture, health and history evidence is refactoring blind.
@@ -443,9 +454,11 @@ Java graphs:
 - Java class/interface/enum/record/annotation declarations retain their symbol kind; methods and
   constructors are linked to their declaring type with visibility metadata. Internal
   `extends`/`implements` relationships and resolvable type references link to real declarations.
-  Imports are compile-only; call/reference/heritage edges contribute impact. Maven/Gradle Java
-  trees use package-aware communities instead of one giant `src` bucket. External or synthetic
-  placeholder types are not created merely to inflate graph counts.
+  Field, parameter, local and static receiver types resolve project-internal cross-file calls;
+  overloads are selected by arity and ambiguous/external targets fail closed. Imports are
+  compile-only; call/reference/heritage edges contribute impact. Maven/Gradle Java trees use
+  package-aware communities instead of one giant `src` bucket. External or synthetic placeholder
+  types are not created merely to inflate graph counts.
 - Dependency checks resolve the nearest workspace manifest and `tsconfig`/`jsconfig` aliases,
   account for framework-owned runtime peers such as Next.js + `react-dom`, and recognize Next.js
   App Router route exports as endpoints.

package/docs/releases/v0.2.10.md

@@ -0,0 +1,53 @@
+# Weavatrix 0.2.10
+
+## Broad graph workflows without losing graph depth
+
+0.2.10 is a graph-quality, positioning and agent-routing patch. It does not narrow Weavatrix to text search, a
+single blast-radius tool, or three fixed workflows. The package, MCP registry metadata, portable
+MCPB, skill, README and public site now describe one reusable graph exposed through 38 methods and
+many task-specific projections: module/community/hub navigation, exact symbols and paths, local and
+cross-repository API flow, symbol/diff impact, structural and behavioral history, Health,
+dependencies, vulnerability evidence, dead code, clones, coverage, hot paths, proof-carrying change
+verification, intended-architecture ratchets, local multi-repository work and explicit Hosted
+governance.
+
+The skill's intent router now maps each independent scenario to the smallest sufficient graph view or
+analysis before lower-level source search. `module_map` is explicitly the first unfamiliar-repository
+orientation view, `run_audit` is the core production-first Health review, and `verified_change` is
+explicitly the pre-commit proof-carrying safeguard. Text search remains a useful source check, not the
+product center.
+
+## Java call graph and Repo Lens baseline
+
+- Java field, parameter, local and static receiver types now resolve project-internal cross-file
+  method calls. Overloads are selected by argument arity; ambiguous methods and external or
+  same-basename impostor types fail closed. Call-site lines remain available to bounded context and
+  endpoint traces, while hub ranking continues to count unique neighbors rather than occurrences.
+- A release regression test now asserts that the default offline catalog retains all 21 portable
+  repository-analysis methods inherited from Repo Lens. Its Electron-only `app_action` and
+  `app_job_status` process-control bridge is not misrepresented as an analyzer method: rebuild,
+  audit, advisory refresh, duplicate review and coverage generation/mapping retain direct bounded
+  MCP paths, while the persistent Electron job journal remains app-specific orchestration.
+- The skill routes every one of the 38 current methods into a concrete scenario, so graph, history,
+  Health, duplicates, dead code and architecture governance remain first-class product surfaces.
+- The unconfigured-architecture starter now proposes product-code territories only: tests, docs,
+  benchmarks, generated files and repository configs are filtered out, while direct source-root
+  files are grouped without overlapping deeper modules. It remains a source-free owner-review
+  proposal and is never saved or enforced automatically.
+
+## Compatibility and data boundary
+
+Tool names, MCP schemas, result envelopes and Hosted sync payloads are unchanged. Java graph nodes
+and edges gain additive local `parameter_count` and `javaResolution` evidence; existing readers can
+ignore those fields, and the Hosted payload allowlist remains unchanged. The default profile still
+exposes 34 local tools and no HTTP tools. Hosted remains separately opt-in, preview-confirmed and
+wire-compatible with payload v3.
+
+## Verification
+
+- Full Node suite: 506 tests, 503 passed, 3 platform skips, 0 failed.
+- Six-language, cross-repository, framework and MCP lifecycle benchmark: `PASS`.
+- Six available real-repository baselines, including the Java call-graph case: 6/6 `PASS`.
+- Release metadata consistency and JSON syntax: `PASS`.
+- Repo Lens portable analyzer parity: 21/21 methods present in the default offline profile.
+- Hosted API and sync-payload schemas are unchanged.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "weavatrix",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "type": "module",
-  "description": "Weavatrix — architecture graph, health, clone and history MCP server for AI coding agents: blast radius, dependency audit, graph diff and coverage over any local repository.",
+  "description": "Local repository intelligence MCP for AI coding agents: reusable architecture graph for fast application understanding, Health, dead code, clones, history, blast radius and architecture safeguards.",
   "author": "Sergii Ziborov <sergii.ziborov@gmail.com>",
   "license": "MIT",
   "homepage": "https://weavatrix.com",
@@ -26,7 +26,7 @@
     "skill",
     "scripts/run-agent-task-benchmark.mjs",
     "docs/agent-task-benchmark.md",
-    "docs/releases/v0.2.9.md",
+    "docs/releases/v0.2.10.md",
     "README.md",
     "SECURITY.md",
     "LICENSE"

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: weavatrix
-description: Drive the weavatrix MCP — code graph, blast-radius (get_dependents/change_impact), dead-code review, health audit, duplicates, coverage, endpoints — over any local repo. Use when analyzing code structure, refactor risk, dead code, dependency health, or before opening a PR.
+description: "Use the Weavatrix MCP as a reusable local repository-intelligence layer: understand unfamiliar applications with a bounded code graph, reduce repeated context, review Health, dead code, duplicates and history, trace endpoints and blast radius, enforce target architecture, and verify changes before a PR."
 ---
 
 # weavatrix MCP
@@ -31,31 +31,82 @@ named profiles for new registrations.
 
 ## Intent router
 
-Start from the task, not from the complete tool list:
-
-- **Orient in a repository**: `graph_stats` -> verify `Repo`, `Graph`, and `Build mode`; if the target
-  is wrong, call `open_repo`, then `graph_stats` again -> `module_map` (production-only by default).
-- **Review a branch/diff**: `change_impact` for changed-file blast radius; add
-  `graph_diff base_ref=<merge-base>` for structural drift, then drill into exact candidates with
-  `get_dependents` and `read_source`.
-- **Plan or verify a serious change**: call `verified_change phase=plan` with the natural-language
-  task and current diff/files. After editing, call it again with `phase=verify` and an immutable
-  `base_ref`. Treat `UNKNOWN` as missing proof, not success; inspect its blockers and unknowns instead
-  of manually orchestrating the lower-level graph, context, impact, ratchet, and test tools.
-- **Trace an API across repositories**: `list_known_repos` -> `trace_api_contract` with an explicit
-  backend and client list; inspect each `graphReconciliation.buildMode` before using the verdict.
-- **Inspect exact symbol references**: start with `graph_stats`, then call `context_bundle` with an
-  exact node ID (or an unambiguous label) for a compact definition, grouped relations, exact
-  re-export sites and source workset. Use `inspect_symbol` when the raw bounded point query is needed;
-  it spends evidence beyond the broad overlay cap. Use `get_dependents` for transitive
-  graph impact and `find_dead_code` for bounded zero-reference
-  candidates. Treat `PARTIAL`, `UNAVAILABLE`, `OFF`, or zero exact edges as incomplete evidence, not
-  a compiler-exact result; `OFF` means the caller explicitly selected static-only mode. Java and Rust
-  providers are not bundled in 0.2.7, so their edges never become `EXACT_LSP` even when a mixed
-  repository has a complete TypeScript/JavaScript overlay.
-- **Explore an architectural question**: use broad `query_graph` when entry points are unknown; its
-  bootstrap/tool-execution ranking prefers production executables over docs, sites and fixtures.
-  Pass exact `seed_files` when the intended entry points are already known.
+Weavatrix is not one report or three fixed workflows. Its 38 methods expose different bounded views
+and analyses over the same reusable graph. Start from the task and choose the smallest sufficient
+projection; expand only when the answer requires it.
+
+### Graph views and application understanding
+
+- **Confirm repository, graph freshness and build mode**: `graph_stats`; use `rebuild_graph` only for
+  a reported fallback/error or an intentional mode/precision change.
+- **Switch or inventory local repositories**: `list_known_repos` -> `open_repo` -> `graph_stats`.
+- **See production module topology**: `module_map`; use this first for a large unfamiliar application.
+- **See discovered communities and their members**: `list_communities` -> `get_community`.
+- **Find high-coupling hubs**: `god_nodes`; repeated call sites do not inflate unique connectivity.
+- **Inspect one graph entity**: `get_node`; pass an exact node ID when labels are ambiguous.
+- **Inspect direct one-hop relations**: `get_neighbors`; do not confuse it with transitive impact.
+- **Prove a path between two concepts**: `shortest_path`.
+- **Explore an unknown entry point or architectural question**: `query_graph`; pin `seed_files` when
+  known, and keep its broad result as orientation evidence.
+- **Inspect one exact symbol deeply**: `context_bundle` for the bounded edit workset;
+  `inspect_symbol` for the raw point query and on-demand JS/TS reference evidence.
+- **Confirm graph evidence in source**: `read_source`; use `search_code` only for a narrow regex/glob
+  check. Search is supporting evidence, not the repository-intelligence layer.
+
+### Runtime, API and change scenarios
+
+- **Inventory HTTP routes**: `list_endpoints` for declared/reachable composed paths and mount proof.
+- **Trace one endpoint through the application**: `trace_endpoint` for route -> handler -> bounded
+  downstream call flow with edge-centered excerpts.
+- **Trace an API contract across repositories**: `list_known_repos` -> `trace_api_contract` with an
+  explicit backend/client set; inspect each graph reconciliation state before using the verdict.
+- **Measure one symbol's transitive blast radius**: `get_dependents`.
+- **Review the current branch, diff, or external patch**: `change_impact`.
+- **Compare structural graph revisions**: `graph_diff base_ref=<merge-base>` for module edges, cycles,
+  orphans and lost callers; without `base_ref`, compare the last rebuild snapshots.
+- **Use behavioral history**: `git_history` for churn x connectivity, hidden co-change and expected
+  test/source coupling from bounded local Git numstat evidence.
+- **Plan and verify a serious change or pre-commit gate**: `verified_change phase=plan` -> edit ->
+  `verified_change phase=verify base_ref=<same-ref>`. It composes exact context, impact, graph,
+  architecture, duplicate, optional API and test proof into one PASS/BLOCKED/UNKNOWN envelope.
+
+### Health, debt and testing scenarios
+
+- **Run a whole-repository Health review**: `run_audit debt=all`.
+- **Gate only newly introduced branch debt**: `run_audit base_ref=<merge-base> debt=new`; old debt in
+  a changed file remains existing.
+- **Review dependency declarations/imports**: `run_audit category=dependencies`; it includes missing,
+  unused, duplicate, unresolved-import and lockfile-drift evidence without relabelling identities.
+- **Refresh vulnerability evidence when explicitly authorized**: `refresh_advisories`, then
+  `run_audit category=vulnerability`. `NOT_CHECKED` is unknown, never clean.
+- **Review dead files, functions, methods and symbols**: `find_dead_code`; every result remains a
+  review candidate with framework/dynamic/public-API caveats, never an auto-delete verdict.
+- **Review clone families or same-name divergence**: `find_duplicates`; framework router boilerplate
+  is suppressed unless explicitly requested.
+- **Map measured coverage or honest static test reachability**: `coverage_map`; unavailable measured
+  coverage is not 0%.
+- **Prioritize local performance-review candidates**: `hot_path_review`; confirm with a profiler or
+  benchmark before changing runtime behavior.
+
+### Intended architecture and Hosted governance
+
+- **Read or establish intended architecture**: `get_architecture_contract`. A returned starter is a
+  product-code-only territory proposal (not tests, docs, benchmarks, generated output or repository
+  configs), not automatically approved policy.
+- **Select rules before editing**: `prepare_change`; **enforce the ratchet after editing**:
+  `verify_architecture`.
+- **Understand or request an exception**: `explain_architecture_violation` ->
+  `propose_architecture_exception`; proposals never mutate policy automatically.
+- **Pull an owner-approved Hosted target**: `pull_architecture_contract` only in an explicitly enabled
+  Hosted profile.
+- **Review exactly what Hosted sync would send**: `preview_sync`; only an approved
+  `sync_graph dry_run=false confirm_token=...` may send that exact bounded payload.
+
+Across every scenario, treat `PARTIAL`, `UNAVAILABLE`, `OFF`, `NOT_CHECKED`, `ERROR`, or capped
+evidence as incomplete rather than success. Java and Rust exact language-server providers are not
+bundled, so their edges never become `EXACT_LSP` even when a mixed repository has a complete
+TypeScript/JavaScript overlay. Java receiver-type call edges are parser-resolved and explicitly
+`INFERRED`; they improve cross-file flow without claiming compiler-exact overload or dynamic dispatch.
 
 ## Ground rules
 

package/src/graph/builder/lang-java-calls.js

@@ -0,0 +1,142 @@
+// Java call resolution beyond bare same-file method names. Tree-sitter gives us the declared type of
+// fields, parameters and locals; imports/same-package resolution then identifies the project type that
+// owns a receiver method. This restores useful cross-file call flow without inventing external nodes or
+// pretending to perform compiler-exact overload/dynamic-dispatch resolution.
+const TYPE_DECLARATIONS = new Set([
+  "class_declaration", "interface_declaration", "enum_declaration",
+  "record_declaration", "annotation_type_declaration",
+]);
+const CALLABLE_DECLARATIONS = new Set([
+  "method_declaration", "constructor_declaration", "lambda_expression",
+]);
+const BINDING_DECLARATIONS = new Set([
+  "formal_parameter", "spread_parameter", "catch_formal_parameter",
+  "enhanced_for_statement", "resource",
+]);
+
+const contains = (scope, node) => scope && node
+  && scope.startIndex <= node.startIndex && scope.endIndex >= node.endIndex;
+
+function nearest(node, accepted) {
+  for (let current = node?.parent, hops = 0; current && hops < 30; current = current.parent, hops++) {
+    if (accepted.has(current.type)) return current;
+  }
+  return null;
+}
+
+function baseTypeName(typeNode, field) {
+  if (!typeNode) return null;
+  if (typeNode.type === "type_identifier") return typeNode.text;
+  if (typeNode.type === "scoped_type_identifier") return typeNode.text.split(".").pop() || null;
+  const nested = field(typeNode, "type") || field(typeNode, "element")
+    || typeNode.namedChildren?.find((child) => [
+      "type_identifier", "scoped_type_identifier", "generic_type", "array_type", "annotated_type",
+    ].includes(child.type));
+  return nested && nested !== typeNode ? baseTypeName(nested, field) : null;
+}
+
+function collectBindings(root, field) {
+  const bindings = [];
+  const add = (nameNode, typeNode, declaration, scope, allowForward = false) => {
+    const typeName = baseTypeName(typeNode, field);
+    if (!nameNode?.text || !typeName || !scope) return;
+    bindings.push({
+      name: nameNode.text,
+      typeName,
+      declaration,
+      scope,
+      allowForward,
+    });
+  };
+  const stack = [root];
+  while (stack.length) {
+    const node = stack.pop();
+    if (!node) continue;
+    if (node.type === "field_declaration" || node.type === "local_variable_declaration") {
+      const type = field(node, "type");
+      const owner = node.type === "field_declaration"
+        ? nearest(node, TYPE_DECLARATIONS)
+        : nearest(node, new Set(["block", ...CALLABLE_DECLARATIONS]));
+      for (const child of node.namedChildren || []) {
+        if (child.type !== "variable_declarator") continue;
+        add(field(child, "name"), type, node, owner, node.type === "field_declaration");
+      }
+    } else if (BINDING_DECLARATIONS.has(node.type)) {
+      const scope = node.type === "enhanced_for_statement"
+        ? node
+        : nearest(node, CALLABLE_DECLARATIONS) || nearest(node, new Set(["catch_clause", "try_with_resources_statement"]));
+      add(field(node, "name"), field(node, "type"), node, scope);
+    }
+    for (const child of node.namedChildren || []) stack.push(child);
+  }
+  return bindings;
+}
+
+function receiverName(node, field) {
+  if (!node) return null;
+  if (node.type === "identifier" || node.type === "type_identifier") return node.text;
+  if (node.type === "scoped_type_identifier") return node.text.split(".").pop() || null;
+  if (node.type === "field_access") {
+    const object = field(node, "object");
+    if (["this", "super"].includes(object?.type)) return field(node, "field")?.text || null;
+  }
+  return null;
+}
+
+function bindingAt(bindings, name, callNode) {
+  return bindings
+    .filter((item) => item.name === name && contains(item.scope, callNode)
+      && (item.allowForward || item.declaration.startIndex <= callNode.startIndex))
+    .sort((left, right) => {
+      const leftSpan = left.scope.endIndex - left.scope.startIndex;
+      const rightSpan = right.scope.endIndex - right.scope.startIndex;
+      return leftSpan - rightSpan || right.declaration.startIndex - left.declaration.startIndex;
+    })[0] || null;
+}
+
+function methodIn(file, name, argumentCount, symIdsByFileName, nodeById) {
+  const candidates = (symIdsByFileName.get(file)?.get(name) || [])
+    .map((id) => nodeById.get(id))
+    .filter((node) => ["method", "constructor"].includes(node?.symbol_kind));
+  if (candidates.length === 1) return candidates[0].id;
+  const exact = candidates.filter((node) => node.parameter_count === argumentCount);
+  return exact.length === 1 ? exact[0].id : null;
+}
+
+export function addJavaCalls({
+  grammar, tree, fileRel, caps, field, enclosing, links, nodeById,
+  symIdsByFileName, resolveCall, resolveJavaType,
+}) {
+  const bindings = collectBindings(tree.rootNode, field);
+  for (const cap of caps(grammar, `(method_invocation) @call`, tree.rootNode)) {
+    const call = cap.node;
+    const name = field(call, "name")?.text;
+    const argumentCount = field(call, "arguments")?.namedChildren?.length ?? 0;
+    const caller = enclosing(fileRel, call.startPosition.row + 1);
+    if (!name || !caller) continue;
+
+    const receiver = field(call, "object");
+    let target = null;
+    let resolution = "unqualified";
+    if (!receiver || ["this", "super"].includes(receiver.type)) {
+      target = resolveCall(name, fileRel);
+    } else {
+      const localName = receiverName(receiver, field);
+      const binding = localName && bindingAt(bindings, localName, call);
+      const declaredType = binding?.typeName || localName;
+      const typeTarget = declaredType && resolveJavaType(declaredType, fileRel);
+      const targetFile = typeTarget && nodeById.get(typeTarget)?.source_file;
+      target = targetFile && methodIn(targetFile, name, argumentCount, symIdsByFileName, nodeById);
+      resolution = binding ? "receiver-declared-type" : "static-type";
+    }
+    if (!target || target === caller.id) continue;
+    links.push({
+      source: caller.id,
+      target,
+      relation: "calls",
+      confidence: "INFERRED",
+      line: call.startPosition.row + 1,
+      javaResolution: resolution,
+    });
+  }
+}

package/src/graph/builder/lang-java.js

@@ -1,6 +1,8 @@
 // Java extractor. Keeps file-level imports/calls while modelling the Java ownership and type system:
 // classes/interfaces/enums/records own their methods, heritage distinguishes extends from implements,
 // and project-local type references resolve to the declaration node (never to synthetic type-name nodes).
+import { addJavaCalls } from "./lang-java-calls.js";
+
 const TYPE_CORE = `
   (class_declaration name: (identifier) @class)
   (interface_declaration name: (identifier) @interface)
@@ -39,6 +41,13 @@ const visibilityOf = (declaration, owner) => {
 };
 
 const lineOf = (node) => node.startPosition.row + 1;
+const parameterCountOf = (declaration) => {
+  const parameters = declaration?.childForFieldName?.("parameters");
+  if (!parameters) return null;
+  return (parameters.namedChildren || []).filter((node) => [
+    "formal_parameter", "spread_parameter", "receiver_parameter",
+  ].includes(node.type)).length;
+};
 const symbolBaseId = (fileRel, nameNode) => `${fileRel}#${nameNode.text}@${lineOf(nameNode)}`;
 const declarationKey = (node) => `${node?.startIndex ?? -1}:${node?.endIndex ?? -1}`;
 const exactJavaTarget = (resolveJavaImport, parts) => {
@@ -52,6 +61,7 @@ export default {
   grammars: ["java"],
   exts: { ".java": "java" },
   isWeb: false,
+  customCalls: true,
   calls: `(method_invocation name: (identifier) @callee)`,
   // Capturing the base type_identifier (rather than the whole generic/scoped type) gives the shared
   // resolver the imported/local declaration name. Each query is deliberately non-overlapping.
@@ -110,6 +120,7 @@ export default {
       const memberId = addJavaSym(cap.node, cap.name !== "field", {
         sourceNode: declaration,
         symbolKind: memberKind,
+        ...(["method", "constructor"].includes(memberKind) ? { parameterCount: parameterCountOf(declaration) } : {}),
         ...(ownerNameNode ? { memberOf: ownerNameNode.text } : {}),
         visibility: visibilityOf(declaration, owner),
       });
@@ -190,4 +201,6 @@ export default {
       }
     }
   },
+
+  pass2: addJavaCalls,
 };

package/src/graph/internal-builder.build.js

@@ -143,7 +143,8 @@ export async function buildInternalGraph(repoDir, opts = {}) {
         ...(extra && extra.symbolKind ? { symbol_kind: extra.symbolKind } : {}),
         ...(extra && extra.symbolSpace ? { symbol_space: extra.symbolSpace } : {}),
         ...(extra && extra.memberOf ? { member_of: extra.memberOf } : {}),
-        ...(extra && extra.visibility ? { visibility: extra.visibility } : {})
+        ...(extra && extra.visibility ? { visibility: extra.visibility } : {}),
+        ...(Number.isInteger(extra?.parameterCount) ? { parameter_count: extra.parameterCount } : {})
       });
       links.push({ source: fileRel, target: id, relation: "contains", confidence: "EXTRACTED" });
       syms.push({
@@ -154,6 +155,7 @@ export async function buildInternalGraph(repoDir, opts = {}) {
         ...(extra?.memberOf ? {memberOf: extra.memberOf} : {}),
         ...(extra?.symbolKind ? {symbolKind: extra.symbolKind} : {}),
         ...(extra?.symbolSpace ? {symbolSpace: extra.symbolSpace} : {}),
+        ...(Number.isInteger(extra?.parameterCount) ? {parameterCount: extra.parameterCount} : {}),
       });
       if (!nameToId.has(name)) nameToId.set(name, id);
       const ids = nameToIds.get(name) || [];
@@ -290,7 +292,7 @@ export async function buildInternalGraph(repoDir, opts = {}) {
       try {
         lang.pass2({
           grammar, tree, fileRel, code, caps, field, enclosing, links, nodeById,
-          perFileSymbols, symByFileName, importedLocals, resolveCall,
+          perFileSymbols, symByFileName, symIdsByFileName, importedLocals, resolveCall, resolveJavaType,
         });
       } catch (e) { /* one language-specific resolver never sinks the graph */ void e; }
     }

package/src/mcp/catalog.mjs

@@ -41,7 +41,7 @@ function buildTools({tg, ti, th, ts, tb, te, ta, tar, thi, tc, tv, caps}) {
         {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: 'graph', refreshGraph: true, name: 'verified_change',
-            description: 'Proof-carrying change workflow. Given a natural-language task and current diff/files, returns compact edit contexts, bounded call-argument data-flow, blast radius, graph/architecture/duplicate/API ratchets, affected tests, and one PASS/BLOCKED/UNKNOWN verdict. Package tests run only when explicitly requested and WEAVATRIX_ALLOW_TEST_RUNS=1.',
+            description: 'Pre-commit, proof-carrying change safeguard. Given a natural-language task and current diff/files, returns compact edit contexts, bounded call-argument data-flow, blast radius, graph/architecture/duplicate/API ratchets, affected tests, and one PASS/BLOCKED/UNKNOWN verdict. Use this high-level workflow before manually composing lower-level checks. Package tests run only when explicitly requested and WEAVATRIX_ALLOW_TEST_RUNS=1.',
             inputSchema: {type: 'object', additionalProperties: false, properties: {
                 task: {type: 'string', minLength: 1, maxLength: 4000}, phase: {type: 'string', enum: ['plan', 'verify'], default: 'plan'},
                 base_ref: {type: 'string', maxLength: 200, default: 'HEAD'}, diff: {type: 'string', maxLength: 2097152}, files: {type: 'array', items: {type: 'string'}, maxItems: 500},
@@ -108,16 +108,16 @@ function buildTools({tg, ti, th, ts, tb, te, ta, tar, thi, tc, tv, caps}) {
           {cap: 'source', refreshGraph: true, name: 'context_bundle', description: 'Return one compact, bounded source bundle for an exact symbol: definition, aggregated inbound/outbound containers, exact re-export sites, on-demand TS/JS reference evidence and a few focused source excerpts. Use before an edit when query_graph would be too broad.', inputSchema: {type: 'object', properties: {label: {type: 'string', description: 'Exact node ID or unambiguous symbol label'}, precision: {type: 'string', enum: ['auto', 'graph', 'lsp'], default: 'auto'}, max_references: {type: 'integer', minimum: 1, maximum: 5000, default: 1000}, max_related: {type: 'integer', minimum: 1, maximum: 30, default: 10}, max_reexports: {type: 'integer', minimum: 1, maximum: 100, default: 20}, max_source_files: {type: 'integer', minimum: 1, maximum: 8, default: 4}, context_lines: {type: 'integer', minimum: 0, maximum: 12, default: 4}, timeout_ms: {type: 'integer', minimum: 1000, maximum: 60000, default: 30000}}, required: ['label']}, run: (g, a, ctx) => tb.tContextBundle(g, a, ctx, ts.tInspectSymbol)},
         {cap: 'health', name: 'find_duplicates', description: "Content-based clone detection over production code (MOSS winnowing over method bodies). Supports high-confidence small clones down to 12 tokens when min_tokens is lowered. Tests, classified non-product paths, and all-router framework boilerplate clone groups are excluded by default; opt them in explicitly.", inputSchema: {type: 'object', properties: {min_similarity: {type: 'integer', description: '50-100, default 80 (ignored in semantic mode)'}, min_tokens: {type: 'integer', minimum: 12, maximum: 400, description: 'min fragment size, 12-400; default 50'}, mode: {type: 'string', enum: ['renamed', 'strict', 'semantic'], default: 'renamed'}, include_tests: {type: 'boolean', default: false}, include_classified: {type: 'boolean', default: false, description: 'Include generated/mock/story/docs/benchmark/temp and paths explicitly classified as excluded; tests still require include_tests'}, include_boilerplate: {type: 'boolean', default: false, description: 'Include clone groups made entirely of conventional *.router.js/ts router symbols'}, include_strings: {type: 'boolean', description: 'Also clone-check large multi-line string literals', default: false}, top_n: {type: 'integer', default: 15}}}, run: (g, a, ctx) => th.tFindDuplicates(g, a, ctx)},
         {cap: 'health', name: 'find_dead_code', description: 'Conservative review queue for statically unreferenced files, functions, methods and symbols. Returns confidence, reason, bounded evidence and explicit framework/dynamic/reflection/public-API caveats; never an auto-delete verdict. Tests, generated code, mocks, stories, docs, benchmarks and temporary roots are excluded by default.', inputSchema: {type: 'object', properties: {path: {type: 'string', maxLength: 1024, description: 'Optional repo-relative path prefix'}, kinds: {type: 'array', items: {type: 'string', enum: ['file', 'function', 'method', 'symbol']}, maxItems: 4, uniqueItems: true, description: 'Optional candidate kinds; defaults to all'}, min_confidence: {type: 'string', enum: ['high', 'medium', 'low'], default: 'medium', description: 'Minimum confidence to include. low explicitly includes public/framework/dynamic review candidates'}, include_tests: {type: 'boolean', default: false}, include_classified: {type: 'boolean', default: false, description: 'Include generated/mock/story/docs/benchmark/temp and paths explicitly classified as excluded; tests still require include_tests'}, top_n: {type: 'integer', minimum: 1, maximum: 100, default: 30}}}, run: (g, a, ctx) => th.tFindDeadCode(g, a, ctx)},
-        {cap: 'health', name: 'run_audit', description: 'Production-first internal health audit. Findings whose evidence is entirely test/e2e/generated/mock/story/docs/benchmark/temp or explicitly excluded are suppressed by default; opt them in with include_classified. category=dependencies is a dedicated dependency-health projection across missing, unused and duplicate declarations while preserving each finding\'s native category. With base_ref, builds and audits an immutable Git checkout and compares stable deterministic finding IDs; debt defaults to genuinely new findings. Supply-chain checks remain explicitly uncomparable across the source-only baseline. changed_files without base_ref is only changed-scope, never a new-debt claim.', inputSchema: {type: 'object', properties: {category: {type: 'string', enum: ['dependencies', 'unused', 'structure', 'vulnerability', 'malware'], description: 'Only findings of this category; dependencies selects dependency manifest/import findings across native categories'}, min_severity: {type: 'string', enum: ['critical', 'high', 'medium', 'low', 'info'], description: 'Minimum severity to include'}, max_findings: {type: 'integer', description: 'Max findings to list, default 30'}, include_classified: {type: 'boolean', default: false, description: 'Include findings whose evidence is entirely tests/e2e/generated/mocks/stories/docs/benchmarks/temp or explicitly excluded'}, include_malware_scan: {type: 'boolean', description: 'Also grep installed packages for malware heuristics (slow)', default: false}, base_ref: {type: 'string', maxLength: 200, description: 'Optional immutable Git baseline (for example HEAD~1 or origin/main). Enables honest new/existing/fixed debt comparison'}, changed_files: {type: 'array', items: {type: 'string'}, minItems: 1, maxItems: 500, description: 'Optional explicit repo-relative scope. Without base_ref this is changed-scope only; when omitted with base_ref, files are derived from the Git diff'}, debt: {type: 'string', enum: ['new', 'existing', 'all'], default: 'new', description: 'Baseline comparison view. Defaults to genuinely new deterministic findings when base_ref is present'}}}, run: (g, a, ctx) => th.tRunAudit(g, a, ctx)},
+        {cap: 'health', name: 'run_audit', description: 'Core production-first repository Health review: structure, dependency declarations, unused surfaces and explicitly bounded supply-chain evidence. Findings whose evidence is entirely test/e2e/generated/mock/story/docs/benchmark/temp or explicitly excluded are suppressed by default; opt them in with include_classified. category=dependencies is a dedicated dependency-health projection across missing, unused and duplicate declarations while preserving each finding\'s native category. With base_ref, builds and audits an immutable Git checkout and compares stable deterministic finding IDs; debt defaults to genuinely new findings. Supply-chain checks remain explicitly uncomparable across the source-only baseline. changed_files without base_ref is only changed-scope, never a new-debt claim.', inputSchema: {type: 'object', properties: {category: {type: 'string', enum: ['dependencies', 'unused', 'structure', 'vulnerability', 'malware'], description: 'Only findings of this category; dependencies selects dependency manifest/import findings across native categories'}, min_severity: {type: 'string', enum: ['critical', 'high', 'medium', 'low', 'info'], description: 'Minimum severity to include'}, max_findings: {type: 'integer', description: 'Max findings to list, default 30'}, include_classified: {type: 'boolean', default: false, description: 'Include findings whose evidence is entirely tests/e2e/generated/mocks/stories/docs/benchmarks/temp or explicitly excluded'}, include_malware_scan: {type: 'boolean', description: 'Also grep installed packages for malware heuristics (slow)', default: false}, base_ref: {type: 'string', maxLength: 200, description: 'Optional immutable Git baseline (for example HEAD~1 or origin/main). Enables honest new/existing/fixed debt comparison'}, changed_files: {type: 'array', items: {type: 'string'}, minItems: 1, maxItems: 500, description: 'Optional explicit repo-relative scope. Without base_ref this is changed-scope only; when omitted with base_ref, files are derived from the Git diff'}, debt: {type: 'string', enum: ['new', 'existing', 'all'], default: 'new', description: 'Baseline comparison view. Defaults to genuinely new deterministic findings when base_ref is present'}}}, run: (g, a, ctx) => th.tRunAudit(g, a, ctx)},
         {cap: 'health', name: 'coverage_map', description: 'Map a real existing coverage report onto the graph. If no report exists, return clearly labelled static test reachability (a test imports/reaches a source file) with actualCoverage=NOT_AVAILABLE; reachability is never presented as measured coverage.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', description: 'Max risk hotspots to list, default 15'}, path: {type: 'string', description: 'Optional repo-relative path prefix filter, e.g. src/query'}}}, run: (g, a, ctx) => th.tCoverageMap(g, a, ctx)},
         {cap: 'health', name: 'hot_path_review', description: 'Rank a focused production-symbol hot-path queue from parser-derived local complexity, inside-loop allocations/copies/scans/sorts/recursion, graph fan-in/fan-out, and measured coverage or clearly labelled static test reachability. The default score gate is 85 with a narrow strong-local fallback; set min_score=0 for the full diagnostic queue. This is not profiler data or interprocedural Big-O.', inputSchema: {type: 'object', properties: {path: {type: 'string', maxLength: 1024, description: 'Optional repository-relative path prefix'}, top_n: {type: 'integer', minimum: 1, maximum: 100, default: 20}, min_score: {type: 'integer', minimum: 0, maximum: 100, default: 85, description: 'Focused default is 85; lower explicitly to broaden, or use 0 for every threshold-matching diagnostic candidate'}, cyclomatic_threshold: {type: 'integer', minimum: 2, maximum: 1000, default: 8}, call_threshold: {type: 'integer', minimum: 1, maximum: 10000, default: 12}, loop_depth_threshold: {type: 'integer', minimum: 1, maximum: 10, default: 2}, time_rank_threshold: {type: 'integer', minimum: 0, maximum: 5, default: 2}, include_tests: {type: 'boolean', default: false}, include_classified: {type: 'boolean', default: false, description: 'Include generated/mock/story/docs/benchmark/temp and explicitly excluded paths; tests still require include_tests'}}}, run: (g, a, ctx) => th.tHotPathReview(g, a, ctx)},
         {cap: 'graph', name: 'list_communities', description: 'List graph communities named by their dominant folder (largest first) with sample files — a readable module overview; feed the list position into get_community.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', description: 'Max communities to list, default 20'}}}, run: (g, a, ctx) => th.tListCommunities(g, a, ctx)},
-        {cap: 'graph', name: 'module_map', description: 'Production-first folder architecture map with file/symbol counts and strongest module dependencies, separating runtime, TypeScript type-only and language compile-only coupling.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', description: 'Max modules to list, default 25'}, include_non_product: {type: 'boolean', default: false, description: 'Include tests, fixtures, benchmarks, generated output, docs and other classified non-product files; false by default'}}}, run: (g, a, ctx) => th.tModuleMap(g, a, ctx)},
+        {cap: 'graph', name: 'module_map', description: 'First orientation view for understanding an unfamiliar application with little context: a production-first folder architecture map with file/symbol counts and strongest module dependencies, separating runtime, TypeScript type-only and language compile-only coupling.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', description: 'Max modules to list, default 25'}, include_non_product: {type: 'boolean', default: false, description: 'Include tests, fixtures, benchmarks, generated output, docs and other classified non-product files; false by default'}}}, run: (g, a, ctx) => th.tModuleMap(g, a, ctx)},
         {cap: 'source', refreshGraph: true, name: 'list_endpoints', description: 'Inventory of HTTP endpoints defined in the repo (Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum and actix-web/Spring MVC and WebFlux): declared and reachable composed paths, static mount provenance, confidence, handler, and file:line.', inputSchema: {type: 'object', properties: {method: {type: 'string', enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS', 'TRACE', 'CONNECT', 'ALL', 'ANY']}, path: {type: 'string', maxLength: 2048, description: 'Optional exact composed path or segment-aligned suffix'}, max_results: {type: 'integer', description: 'Max endpoints to list, default 100'}}}, run: (g, a, ctx) => th.tListEndpoints(g, a, ctx)},
         {cap: 'source', refreshGraph: true, name: 'trace_endpoint', description: 'Resolve one exact reachable HTTP endpoint, prove its router mount chain, bind its handler symbol, and return a bounded production-only multi-hop call graph with call-site excerpts. This is a focused projection of the repository graph, not text-search inference.', inputSchema: {type: 'object', properties: {path: {type: 'string', minLength: 1, maxLength: 2048, description: 'Exact composed path; a suffix is accepted only when unambiguous'}, method: {type: 'string', enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS', 'TRACE', 'CONNECT', 'ALL', 'ANY']}, max_depth: {type: 'integer', minimum: 1, maximum: 4, default: 3}, max_nodes: {type: 'integer', minimum: 2, maximum: 40, default: 20}, max_excerpts: {type: 'integer', minimum: 0, maximum: 12, default: 6}, context_lines: {type: 'integer', minimum: 0, maximum: 6, default: 2}, include_classified: {type: 'boolean', default: false, description: 'Include test/e2e/generated/mock/story/docs/benchmark/temp and explicitly excluded targets'}}, required: ['path']}, run: (g, a, ctx) => te.tTraceEndpoint(g, a, ctx)},
         {cap: 'build', name: 'rebuild_graph', description: "Rebuild the active full-repository graph and report a structural delta. Omitted mode/precision preserve the active graph; a first build uses full and the startup precision setting (lsp unless WEAVATRIX_PRECISION=off). The local TypeScript/JavaScript LSP overlay validates bounded ambiguous edges; precision:off is an explicit fallback. With scope, build an isolated diagnostic graph without replacing or diffing the full graph.", inputSchema: {type: 'object', properties: {mode: {type: 'string', enum: ['full', 'no-tests', 'tests-only'], description: 'Build mode; omit to preserve the active mode (or use full for a first build)'}, precision: {type: 'string', enum: ['lsp', 'off'], description: 'Semantic precision; omit to preserve the active mode (or use the startup setting for a first build)'}, scope: {type: 'string', description: 'Optional isolated diagnostic path prefix; never replaces the active full graph'}}}, run: (g, a, ctx) => ta.tRebuildGraph(g, a, ctx)},
         {cap: 'graph', name: 'graph_diff', description: 'Structural graph diff: compare the current graph with an immutable Git-ref baseline (base_ref such as HEAD~1 or main), or with graph.prev.json from the last rebuild when base_ref is omitted. Reports architecture drift, cycle changes and symbols that lost their last caller.', inputSchema: {type: 'object', properties: {base_ref: {type: 'string', maxLength: 256, description: 'Optional immutable Git baseline to build in isolation, e.g. HEAD~1, main or origin/main; never checks out or mutates the working tree'}, path: {type: 'string', description: 'Optional node-id/path prefix to scope the diff, e.g. src/query'}}}, run: (g, a, ctx) => ti.tGraphDiff(g, a, ctx)},
-        {cap: 'graph', name: 'get_architecture_contract', description: 'Return the executable target-architecture contract, quality budgets and ratchet mode that an agent must follow before editing.', inputSchema: {type: 'object', properties: {}}, run: (g, a, ctx) => tar.tGetArchitectureContract(g, a, ctx)},
+        {cap: 'graph', name: 'get_architecture_contract', description: 'Start the intended-architecture workflow: return the executable owner-approved target, quality budgets and ratchet mode that an agent must follow before editing. When absent, returns a starter proposal rather than silently inventing policy.', inputSchema: {type: 'object', properties: {}}, run: (g, a, ctx) => tar.tGetArchitectureContract(g, a, ctx)},
         {cap: 'graph', name: 'prepare_change', description: 'Select active target-architecture rules for an intended set of changed files. Run before a non-trivial edit.', inputSchema: {type: 'object', properties: {intent: {type: 'string'}, files: {type: 'array', items: {type: 'string'}, maxItems: 200}}, required: ['files']}, run: (g, a, ctx) => tar.tPrepareChange(g, a, ctx)},
         {cap: 'health', name: 'verify_architecture', description: 'Verify the fresh graph against the active target contract and ratchet; separates new, existing, fixed and excepted debt.', inputSchema: {type: 'object', properties: {}}, run: (g, a, ctx) => tar.tVerifyArchitecture(g, a, ctx)},
         {cap: 'health', name: 'explain_architecture_violation', description: 'Explain one active architecture violation and the governing rule.', inputSchema: {type: 'object', properties: {fingerprint: {type: 'string'}}, required: ['fingerprint']}, run: (g, a, ctx) => tar.tExplainArchitectureViolation(g, a, ctx)},

package/src/mcp/tools-architecture.mjs

@@ -15,6 +15,12 @@ const PROVISIONAL_BUDGETS = Object.freeze({
     maxModuleBoundaryRatio: .65,
 })
 
+const SOURCE_ROOTS = new Set(['src', 'app', 'lib', 'packages', 'services'])
+const PRODUCT_CODE_EXTENSIONS = new Set([
+    '.cjs', '.cs', '.css', '.go', '.htm', '.html', '.java', '.js', '.jsx', '.less', '.mjs', '.py', '.pyi',
+    '.rs', '.scss', '.ts', '.tsx',
+])
+
 const remediation = () => ({
     offlinePath: '.weavatrix/architecture.json',
     hostedAction: 'Open Architecture -> choose intended style -> Save target & baseline',
@@ -35,24 +41,51 @@ function activeContract(ctx) {
     return loadArchitectureContract(ctx.repoRoot, ctx.graphPath)
 }
 
-function starterContract(g) {
+const codeExtension = (file) => {
+    const name = String(file || '').split('/').at(-1) || ''
+    const dot = name.lastIndexOf('.')
+    return dot >= 0 ? name.slice(dot).toLowerCase() : ''
+}
+
+function starterContract(g, repoRoot) {
+    const classifier = createPathClassifier(repoRoot)
     const files = [...new Set((g?.nodes || [])
         .filter((node) => !String(node.id).includes('#'))
         .map((node) => String(node.source_file || node.id || '').replace(/\\/g, '/'))
-        .filter(Boolean))]
+        .filter((file) => file && PRODUCT_CODE_EXTENSIONS.has(codeExtension(file))))]
+        .filter((file) => {
+            const explanation = classifier.explain(file)
+            return !explanation.excluded && !hasPathClass(
+                explanation, 'test', 'e2e', 'generated', 'mock', 'story', 'docs', 'benchmark', 'temp',
+            )
+        })
     const groups = new Map()
     for (const file of files) {
         const parts = file.split('/').filter(Boolean)
-        const depth = ['src', 'app', 'lib', 'packages', 'services'].includes(parts[0]) ? 2 : 1
-        const path = parts.slice(0, Math.max(1, Math.min(depth, parts.length - 1))).join('/') || '(root)'
-        groups.set(path, (groups.get(path) || 0) + 1)
+        let key, name, path
+        if (parts.length === 1) {
+            key = 'root-code'
+            name = 'root code'
+            path = file
+        } else if (SOURCE_ROOTS.has(parts[0]) && parts.length === 2) {
+            key = `${parts[0]}-root`
+            name = `${parts[0]} (root files)`
+            path = file
+        } else {
+            path = parts.slice(0, SOURCE_ROOTS.has(parts[0]) ? 2 : 1).join('/')
+            key = path
+            name = path
+        }
+        const group = groups.get(key) || {name, paths: new Set(), files: 0}
+        group.paths.add(path)
+        group.files += 1
+        groups.set(key, group)
     }
-    const components = [...groups].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 80)
-        .filter(([path]) => path !== '(root)')
-        .map(([path], index) => ({
-            id: path.toLowerCase().replace(/[^a-z0-9._:-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 100) || `component-${index + 1}`,
-            name: path,
-            paths: [path],
+    const components = [...groups].sort((a, b) => b[1].files - a[1].files || a[0].localeCompare(b[0])).slice(0, 80)
+        .map(([key, group], index) => ({
+            id: key.toLowerCase().replace(/[^a-z0-9._:-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 100) || `component-${index + 1}`,
+            name: group.name,
+            paths: [...group.paths].sort((a, b) => a.localeCompare(b)),
         }))
     return normalizeArchitectureContract({
         name: 'Proposed no-regressions baseline', style: 'custom', enforcement: 'ratchet', components,
@@ -62,10 +95,10 @@ function starterContract(g) {
     })
 }
 
-function notConfiguredResult(g, action, {includeStarter = false} = {}) {
-    const starter = includeStarter ? starterContract(g) : null
+function notConfiguredResult(g, action, {includeStarter = false, repoRoot = null} = {}) {
+    const starter = includeStarter ? starterContract(g, repoRoot) : null
     const starterText = starter
-        ? ` A source-free starter with ${starter.components.length} path territories is available in JSON output from this lookup.`
+        ? ` A source-free starter with ${starter.components.length} product-code territories is available in JSON output from this lookup.`
         : ''
     return toolResult([
         `Architecture ${action} is NOT_CONFIGURED — no target contract is active.${starterText}`,
@@ -122,7 +155,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', {includeStarter: true})
+        if (!loaded.error) return notConfiguredResult(g, 'lookup', {includeStarter: true, repoRoot: ctx?.repoRoot})
         return toolResult(text, {state: 'ERROR', source: loaded.source, error: loaded.error})
     }
     const contract = loaded.contract

package/docs/releases/v0.2.9.md

@@ -1,123 +0,0 @@
-# Weavatrix 0.2.9
-
-## Correctness, signal, and consent
-
-0.2.9 is a focused MCP correctness release driven by dogfooding on a 10,000-node JavaScript REST
-service. It fixes cases where broad repository orientation was useful but precision tools handed an
-agent incomplete paths, mismatched call-site provenance, or noisy review queues.
-
-## Composed Express routes
-
-`list_endpoints` now follows relative ESM/CommonJS router imports and nested `router.use(...)`
-mounts. A handler declared as `/:attackId/startMitigate` below `/warRoom` and `/attack` is reported as
-`/warRoom/attack/:attackId/startMitigate` while retaining its local declaration path. The inventory
-separates declaration and reachable-route counts, labels local versus statically composed evidence,
-and returns the exact mount files, lines and prefixes.
-
-Composition is intentionally bounded. Dynamic mount expressions that cannot be resolved statically
-remain local-path evidence rather than guessed full routes.
-
-The new `trace_endpoint` tool resolves one exact composed route, binds its handler without silently
-choosing among same-name symbols, and traverses a bounded production-only call graph with excerpts at
-the actual edge lines. On the dogfood route it recovered router mount provenance, controller:268,
-service, messaging and task calls in one graph-anchored response.
-
-## Edge-centered source context
-
-`context_bundle` now keeps two facts separate:
-
-- the file and line containing an outbound call;
-- the target symbol's definition file.
-
-The compact source bundle prioritizes the definition and bounded excerpts around decisive inbound and
-outbound edge lines. Long Swagger/JSDoc comments at the beginning of a controller therefore no longer
-consume the only excerpt before the real service call.
-
-## Search and retrieval signal
-
-- Ripgrep-backed `search_code` runs from the repository root, so documented relative globs such as
-  `services/attack/**` behave consistently on Windows, macOS, and Linux.
-- Broad `query_graph` prompts discard generic REST/instruction terms before fuzzy seeding and use a
-  smaller automatic seed set. When prose contains a code-shaped identifier such as `startMitigate`,
-  its exact same-name declarations are exclusive automatic seeds; generic controller/service/flow
-  words cannot add unrelated modules. Exact files, endpoints, and symbols remain the preferred
-  precision path.
-
-## Production-first review queues
-
-- `run_audit` suppresses findings whose evidence is entirely in tests, generated output, docs,
-  benchmarks, fixtures, mocks, or stories. `include_classified:true` restores the full diagnostic
-  view; mixed production/non-production evidence remains visible by default.
-- `run_audit category=dependencies` projects missing, unused and duplicate declarations, unresolved
-  imports and lockfile drift into one dependency-health review without relabelling their native
-  deterministic finding identities.
-- `find_duplicates` suppresses groups made entirely of router boilerplate by default.
-  `include_boilerplate:true` restores them for framework-template review.
-- Incomplete OSV coverage remains explicit as `NOT_CHECKED`; this release does not turn missing
-  advisory data into a clean security verdict.
-
-## Preview-confirm graph sync
-
-`preview_sync` and `sync_graph` are now a two-step consent flow:
-
-1. `preview_sync` builds and validates the strict payload allowlist locally and has no network path.
-2. Display the destination, repository identity, exact top-level fields, payload
-   version/sections/size/hash and return a short-lived confirmation token.
-3. `sync_graph` sends only the exact cached payload when it supplies both `dry_run:false` and that token
-   within five minutes. A token alone remains a no-network dry-run.
-
-Incorrect or expired tokens never send. Sync also rejects embedded URL credentials/fragments and
-requires HTTPS except for loopback development endpoints. URL query values are not echoed in previews
-or errors.
-
-`pull_architecture_contract` applies the same HTTPS-outside-loopback and embedded-credential URL
-rules before sending bearer authentication. It now distinguishes authentication, forbidden,
-repository-not-registered, endpoint-not-found, repository-not-ready and general HTTP failures.
-Hosted's `REPOSITORY_NOT_FOUND` response is therefore no longer confused with a wrong endpoint;
-`NOT_CONFIGURED` explicitly means sync/authentication succeeded but no target contract was saved.
-
-## Per-call metrics without telemetry
-
-Every MCP response carries transient local `_meta["weavatrix/metrics"]`: duration, text/structured
-bytes, estimated output tokens, graph freshness/revision/update and graph-cache status. These values
-are returned to the caller only; Weavatrix does not persist, aggregate or transmit them.
-
-## Public contract alignment
-
-The README, package manifests, public home page, privacy policy, security policy, and new public
-license/security pages now describe the same 38-tool surface, 34-tool offline default, preview-confirm
-sync behavior, and source/data boundary. The optional Hosted workbench is described as an
-independently evolving access-controlled preview. Payload v3 is unchanged, so existing Hosted storage,
-history and evidence readers remain wire-compatible; Hosted contract tests validate v1/v2/v3.
-
-## Compatibility
-
-The release adds `trace_endpoint` to the local source surface and `preview_sync` to the explicit
-Hosted surface, taking the catalog from 36 to 38 tools and the default offline profile from 33 to 34.
-Existing offline, pinned, osv, hosted, full and legacy online capability names remain valid.
-`sync_graph` retains its no-network dry-run compatibility form, but `preview_sync` is the canonical
-approval step for new clients.
-
-## Verification
-
-- Full Node suite: 502 tests, 499 passed, 3 platform skips, 0 failed.
-- Deterministic six-language, cross-repository, framework-convention and MCP lifecycle benchmark:
-  `PASS`.
-- Real pinned corpus: 6 of 6 repositories `PASS` across TypeScript, JavaScript, Python, Go, Java and
-  Rust.
-- Release metadata consistency: `PASS`; production npm audit: 0 vulnerabilities; npm 0.2.9 package
-  dry-run: 154 files, 413,993 bytes.
-- Portable MCPB: manifest validation `PASS`; archive built at 6.7 MiB
-  (`5a5def22491bc0777c882c314b12be7153d56d29`). The local archive is unsigned.
-- Direct `controller-rest-api` dogfood: 1,076 indexed files and 989 reachable composed endpoints;
-  public and internal composed
-  `startMitigate` routes found; documented attack glob returned real matches; context preserved
-  `controller:268 → service` with the call excerpt; production-first audit retained the manually
-  confirmed missing `mongodb` declaration and explicit `OSV NOT_CHECKED`; 2 router-only clone groups
-  were separated from 60 default groups; exact identifier seeding returned only controller, service
-  and messaging declarations.
-
-Focused regressions cover nested Express mounts, call-site/target provenance and edge excerpts,
-Windows path globs, generic REST and exact-identifier seed handling, production-first audit filtering,
-router boilerplate suppression, no-network sync previews, confirmation-token mismatch, URL redaction,
-and actionable contract 404 state.