weavatrix 0.2.11 → 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.11",
+  "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.11.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.11.md

@@ -1,23 +0,0 @@
-# Weavatrix 0.2.11
-
-## MCP Registry publication hotfix
-
-0.2.11 is the immutable follow-up to 0.2.10. The 0.2.10 npm package published successfully, but
-the official MCP Registry rejected its expanded server description because that field exceeded the
-Registry's 100-character limit. This patch shortens only the Registry summary while preserving the
-broad product positioning across the package, MCPB, skill, README and public site. The release
-verifier now enforces the same 1-100 character boundary before a tag can publish.
-
-The runtime is otherwise the verified 0.2.10 release: 38 graph-backed methods for fast application
-understanding, Health, dependencies, dead-code and duplicate review, history, endpoint and impact
-tracing, proof-carrying changes, target-architecture ratchets and explicit Hosted governance. Its
-Java receiver-aware call resolver and product-code-only architecture starter are unchanged.
-
-## Compatibility and verification
-
-- Tool names, input schemas, result envelopes and Hosted sync payload v2/v3 remain unchanged.
-- 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: 6/6 `PASS`.
-- Repo Lens portable analyzer parity: 21/21 methods present in the default offline profile.
-- Release metadata, MCP Registry description length and MCPB manifest validation: `PASS`.