weavatrix 0.2.10 → 0.2.12

package/README.md

@@ -49,6 +49,100 @@ Weavatrix answers questions a text index cannot:
   impact, bounded call-argument flow, Git graph drift, architecture/duplicate/API ratchets, and
   affected-test evidence.
 
+## Worked examples
+
+These are representative sequences from local dogfooding, not fabricated chat transcripts. Counts
+describe the observed repository snapshots and will move with the code.
+
+### Understand an unfamiliar backend without reading it linearly
+
+```text
+Question: Where does an attack-mitigation request go?
+
+module_map
+  -> production territories and strongest module dependencies
+list_endpoints
+  -> 462 routes observed in a 1,076-file backend snapshot
+trace_endpoint
+  -> composed router mount -> controller -> service -> task/messaging
+  -> bounded call-site excerpts around decisive edges
+```
+
+Use `module_map` for the initial application shape, then switch to the exact endpoint or symbol. Do
+not lead with a broad natural-language `query_graph` when the route or identifier is already known.
+
+### Check whether a backend handler is used by another repository
+
+```text
+Question: Can this handler be removed?
+
+list_known_repos -> trace_api_contract
+  backend endpoints observed: 163
+  client callsites joined:     267 across two registered clients
+  handler liveness:            NOT_DEAD_EXTERNAL_USE
+  unresolved dynamic URLs:     POSSIBLE_EXTERNAL_USE / UNKNOWN
+```
+
+This joins separately cached local graphs; it does not upload source. Medium/high-confidence
+external use can keep a handler out of the dead-code queue, while dynamic or ambiguous calls remain
+explicitly incomplete evidence.
+
+### Change one method with an evidence trail
+
+```text
+inspect_symbol -> context_bundle -> get_dependents -> coverage_map
+  -> edit the bounded workset
+  -> verified_change phase=verify base_ref=<merge-base>
+```
+
+On an observed BranchPilot diff, `change_impact` separated removed methods/signatures from additive
+exports and ranked a 98-node radius without collapsing runtime and type-only coupling. If measured
+coverage, the architecture contract, or requested tests are missing, the final state is `UNKNOWN`,
+not a cosmetic pass.
+
+### Review Health and clone debt without auto-deleting code
+
+```text
+run_audit category=dependencies debt=all
+  -> missing direct dependency (observed: mongodb)
+  -> lockfile drift and unresolved imports
+run_audit debt=all
+  -> runtime cycles separated from compile/type-only coupling
+find_duplicates
+  -> clone families and same-name divergence
+  -> homogeneous router boilerplate suppressed by default
+```
+
+Every dead-code, orphan, dependency and duplicate item remains review evidence. Confirm framework
+conventions and source use before editing; Weavatrix does not auto-delete or merge findings.
+
+## Benchmarks
+
+Two different gates ship in the repository:
+
+- `npm run benchmark` is a reproducible golden suite for TypeScript, JavaScript, Python, Go, Java
+  and Rust, plus cross-repository HTTP matching, framework conventions and the MCP graph lifecycle.
+- `npm run benchmark:real` compares revision-pinned local application snapshots with the checked-in
+  0.2.1 relation baseline. It fails on unexplained signal loss; `MISSING`, `STALE` and `UNBASELINED`
+  remain incomplete, not green.
+
+Latest local release run (Windows x64, Node 24.15.0, July 18, 2026):
+
+| Gate | Result | Selected evidence |
+|---|---:|---|
+| Six language fixtures | 6/6 PASS | exact symbols/edges and complete edge provenance |
+| Cross-repo fixture | PASS, 431.79 ms cold | endpoint match, typed wrapper, external use, affected screen |
+| Lifecycle | PASS | `full -> incremental -> none -> reconnect/none`; 1,376-byte text response |
+| Total fixture cold build | 1.31 s | all six language graphs; 6.4 KB bounded report |
+| Real-repository baseline | 6/6 PASS | TS, JS, Python, Go, Java and Rust snapshots |
+
+Real snapshots ranged from 473 nodes / 1,165 edges in 0.22 s (Go) to 8,192 nodes / 21,814 edges
+in 9.44 s (TypeScript). The Java snapshot built 7,143 nodes / 23,708 edges in 2.61 s, including
+receiver-aware cross-file calls. These are regression measurements on one machine, not competitor
+benchmarks or universal latency claims. See [benchmark/cases.mjs](benchmark/cases.mjs),
+[benchmark/real-repositories.json](benchmark/real-repositories.json), and run the commands above to
+reproduce them on your own repositories.
+
 ## Quick start
 
 Requires Node ≥ 18. One command:

package/docs/releases/v0.2.12.md

@@ -0,0 +1,45 @@
+# Weavatrix 0.2.12
+
+## Agent workflow routing and cross-repository API clarity
+
+0.2.12 incorporates a second hands-on evaluation across Weavatrix, BranchPilot,
+controller-rest-api and its registered clients. It does not reduce the product to a short list: the
+skill still maps all 38 methods across application understanding, graph views, Health, dependencies,
+dead code, duplicates, coverage, history, endpoints, impact, architecture and Hosted governance.
+
+The skill now makes three high-leverage routing decisions explicit:
+
+- prefer `trace_api_contract` over disconnected per-repository searches when a backend change can
+  affect registered clients;
+- use `change_impact` as a diff-risk classifier that separates additive exports from
+  signature/body/removal risk, runtime/type-only radius and honest coverage evidence;
+- treat `verified_change` as a proof layer around an agent's edit, never a hidden source editor or
+  auto-fix.
+
+The one-symbol refactor workflow now carries exact context, dependents and coverage through the
+post-edit `verified_change` ratchet. The public site also surfaces cross-repository API contract
+tracing as a first-class graph capability rather than hiding it under generic multi-repository mode.
+
+## Worked examples and public benchmark evidence
+
+The README and public site now show four concrete dogfood scenarios instead of relying on feature
+names alone: orienting inside a 1,076-file backend and tracing one of 462 observed routes; proving
+external handler use across three registered repositories; classifying a BranchPilot change before
+editing; and turning Health plus clone evidence into a bounded review queue. The examples preserve
+uncertainty for dynamic URLs, advisory coverage and review-required findings.
+
+The public benchmark section reports reproducible fixture and revision-pinned real-repository
+regression gates with dates, environment, commands and explicit limits. It does not present these
+machine-dependent local measurements as competitor benchmarks. A lightweight CSS motion sequence
+illustrates the graph-to-verdict workflow and respects `prefers-reduced-motion`; no synthetic product
+screenshots are used.
+
+## Compatibility and verification
+
+- Runtime implementation, tool names, schemas and result envelopes are unchanged from 0.2.11.
+- Hosted sync payload v2/v3 and architecture-contract transport are unchanged.
+- Skill inventory: all 38 current methods are routed; 0 missing.
+- Full Node suite baseline: 506 tests, 503 passed, 3 platform skips, 0 failed.
+- Six-language fixture, cross-repository and lifecycle benchmark: `PASS`.
+- Six locally available revision-pinned real-repository baselines: `PASS`.
+- Release metadata, 99-character MCP Registry description and MCPB validation: `PASS`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weavatrix",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "type": "module",
   "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>",
@@ -26,7 +26,7 @@
     "skill",
     "scripts/run-agent-task-benchmark.mjs",
     "docs/agent-task-benchmark.md",
-    "docs/releases/v0.2.10.md",
+    "docs/releases/v0.2.12.md",
     "README.md",
     "SECURITY.md",
     "LICENSE"

package/skill/SKILL.md

@@ -59,16 +59,21 @@ projection; expand only when the answer requires it.
 - **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.
+  explicit backend/client set; prefer this over separate per-repository endpoint/search passes when
+  a backend change may affect registered clients, and 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`.
+- **Review the current branch, diff, or external patch**: `change_impact`; it distinguishes additive
+  exports from signature/body/removal risk and separates runtime/type-only radius plus available
+  measured coverage or explicitly static reachability.
 - **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.
+  architecture, duplicate, optional API and test proof into one PASS/BLOCKED/UNKNOWN envelope. It is
+  a proof layer around an agent's edit, not a source editor or hidden auto-fix.
 
 ### Health, debt and testing scenarios
 
@@ -110,6 +115,9 @@ TypeScript/JavaScript overlay. Java receiver-type call edges are parser-resolved
 
 ## Ground rules
 
+- **No hidden source mutation**: Weavatrix builds derived graph/cache artifacts and can run explicitly
+  authorized tests, but it does not edit repository source, auto-delete debt, merge clones, or rewrite
+  architecture policy. The coding agent remains responsible for the change and its tests.
 - **Evidence, not verdicts**: treat audit, hub, orphan and duplicate output as hypotheses. Confirm a
   finding in source and check framework/runtime conventions before deleting, merging or redesigning
   code. A same-name/different-body pair is a divergence candidate, not proof of duplication.
@@ -195,8 +203,9 @@ TypeScript/JavaScript overlay. Java receiver-type call edges are parser-resolved
 - **Orient in the configured repo**: `module_map` → `list_communities` → `god_nodes`. Hub ranking
   is production-only by default; use `include_classified:true` only when tests/generated/build
   surfaces are deliberately part of the question.
-- **Refactor safety for one symbol**: `inspect_symbol` → `get_dependents` → `coverage_map` (low coverage × many
-  dependents ⇒ write tests first) → `read_source`.
+- **Refactor safety for one symbol**: `inspect_symbol` → `context_bundle` → `get_dependents` →
+  `coverage_map` (low coverage × many dependents ⇒ write tests first) → edit →
+  `verified_change phase=verify base_ref=<merge-base>`.
 - **Performance review**: `hot_path_review` → inspect its local evidence with `read_source` → use
   `get_dependents` for change risk → confirm with the repository's profiler/benchmark before editing.
 - **Pre-PR review of your current changes**: `change_impact` (auto merge-base; includes uncommitted

package/docs/releases/v0.2.10.md

@@ -1,53 +0,0 @@
-# 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.