weavatrix 0.2.12 → 0.2.14

package/README.md

@@ -34,8 +34,8 @@ Weavatrix answers questions a text index cannot:
   depends on them — with test coverage attached, so the **untested part of the blast radius** stands
   out before you ship.
 - *"Who calls this function?"* → `inspect_symbol` returns exact bounded TS/JS occurrences plus
-  source context; `context_bundle` adds grouped graph relations, exact re-export sites, and a
-  smaller source workset. `get_dependents` walks the symbol-level reverse graph transitively. Opt into
+  source context; `context_bundle` adds production-first graph relations, exact re-export sites,
+  diverse call-site excerpts, and a smaller source workset. `get_dependents` walks the symbol-level reverse graph transitively. Opt into
   `include_container_importers:true` only when a broader module-import radius is intended.
 - *"Did my refactor actually decouple anything?"* → `graph_diff base_ref=HEAD~1` builds an immutable
   baseline graph without checking it out, then reports the structural delta: new module
@@ -116,6 +116,43 @@ find_duplicates
 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.
 
+`run_audit` also returns an explicit capability matrix. `STRUCTURE CHECKED` and a supported package
+ecosystem do not imply `RUNTIME_CORRECTNESS` or `CONCURRENCY` is complete. Maven/Gradle manifests are
+reported `NOT_SUPPORTED`/`PARTIAL` for import-to-artifact verification rather than as a false clean
+`0 declared / 0 external`; bounded Go/Java correctness checks disclose that they are neither compiler
+proof nor a race detector.
+
+### Trace an event, queue, worker, cron or CLI flow
+
+```text
+query_graph
+  seed_symbols=["handleAttackEvents"]
+  relation_filter=["calls", "references"]
+  flow_direction="both"
+  -> exact listener plus bounded producers and consumers
+context_bundle label="handleAttackEvents"
+  -> production callers first and diverse excerpts around decisive call sites
+```
+
+Exact symbol seeds avoid fuzzy routing noise and work for non-HTTP entry points without adding a
+special-purpose tool for every framework. A narrow `search_code` registration check is still useful
+when the handler name is not known; it is a discovery aid, not the graph.
+
+### Establish an architecture contract without silently changing policy
+
+```text
+get_architecture_contract action=preview baseline_mode=none
+  -> adaptive Maven/Gradle/monorepo territories
+  -> observed dependency directions labelled OBSERVED_NOT_ENFORCED
+  -> exact proposed file, verification, hash and short-lived token
+get_architecture_contract action=approve confirm_token=<reviewed-token>
+  -> creates only a missing .weavatrix/architecture.json
+prepare_change -> edit -> verify_architecture
+```
+
+Use `baseline_mode=accept-current` only when the owner explicitly accepts current deterministic debt.
+Approval rechecks the graph and never overwrites an existing local or Hosted policy.
+
 ## Benchmarks
 
 Two different gates ship in the repository:
@@ -126,7 +163,7 @@ Two different gates ship in the repository:
   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):
+Representative local regression run (Windows x64, Node 24.15.0, July 18, 2026):
 
 | Gate | Result | Selected evidence |
 |---|---:|---|
@@ -194,6 +231,13 @@ Advanced registrations may still pass an exact comma-separated capability set:
 a compatibility alias for `advisories,hosted`; new registrations should use the named profiles or
 the narrower capability names.
 
+After an upgrade, reconnect the MCP server or start a new agent task before checking its tool list:
+many clients snapshot `tools/list` and input schemas for the lifetime of one connection. The expected
+counts are 31 for `pinned`, 34 for `offline`, 35 for `osv`, and all 38 for `hosted` / `full`. A custom
+capability list must include `crossrepo` to expose `trace_api_contract`; `online` alone adds only the
+legacy advisory/Hosted groups. `graph_stats` reports the running package version, enabled capabilities
+and registered-tool count so a cached process can be distinguished from the installed package.
+
 Or clone it:
 
 ```sh
@@ -211,7 +255,7 @@ No graph yet? Ask the agent to call `rebuild_graph`; it builds the missing graph
 With the default `offline` profile (or an explicit capability set containing `retarget`),
 `open_repo` can change the active repository
 and builds a missing graph automatically. A normal
-`open_repo` also upgrades graphs that predate current typed-edge/provenance metadata; `build:false`
+`open_repo` also upgrades graphs that predate current typed-edge/provenance/physical-LOC metadata; `build:false`
 probes without building and refuses a legacy graph. Retargeting is offline but intentionally changes
 the filesystem boundary for subsequent tools; select `pinned` when that boundary must not move.
 
@@ -233,8 +277,8 @@ Every current edge carries versioned provenance. The parser emits `EXTRACTED`, `
 confirmed by its bundled `typescript-language-server` + TypeScript runtime to `EXACT_LSP`.
 `CONFLICT` means evidence disagrees. `graph_stats` reports the provenance breakdown and the semantic
 provider's `COMPLETE`, `PARTIAL`, `UNAVAILABLE`, or `OFF` state; `OFF` means precision was explicitly
-disabled and only static evidence is active. Java and Rust language-server providers are not bundled
-in 0.2.9: their edges never become `EXACT_LSP`, even when a mixed repository reports a complete
+disabled and only static evidence is active. Java and Rust language-server providers are not bundled:
+their edges never become `EXACT_LSP`, even when a mixed repository reports a complete
 TypeScript/JavaScript overlay.
 
 The bounded JS/TS provider is enabled by default for new graphs. Set `WEAVATRIX_PRECISION=off`
@@ -245,19 +289,21 @@ choice as **TypeScript/JavaScript semantic precision**.
 **search / source** — `search_code` (ripgrep-backed, pure-Node fallback, with repository-relative
 path globs on Windows/macOS/Linux), `read_source` (a
 symbol's actual code in one hop), `context_bundle` (definition plus grouped inbound/outbound
-containers, exact re-export sites, call-site/target provenance and bounded excerpts around decisive
+containers ranked production-first, exact re-export sites, call-site/target provenance and diverse bounded excerpts around decisive
 edges), `inspect_symbol` (one exact
 bounded TS/JS reference query, logical containers, impact and source excerpts), `list_endpoints` (HTTP route inventory:
 Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum and actix-web, including nested Express
-`router.use(...)` mount composition, declaration/reachability counts and mount provenance),
+`router.use(...)` mount composition, declaration/reachability counts, mount provenance, and Spring
+conditional/default-active state),
 `trace_endpoint` (one exact composed route → handler → bounded production call graph with call-site excerpts)
 
 **health** — `find_dead_code` (bounded review queue for statically unreferenced and test-only files,
 functions, methods, and symbols, with evidence tiers, completed/remaining verification and explicit
 public/framework/dynamic caveats),
-`run_audit` (unused files/exports/dependencies with per-finding manifest/indexed-source/script/config verification;
+`run_audit` (an explicit capability matrix plus unused files/exports/dependencies with per-finding manifest/indexed-source/script/config verification;
 `category:dependencies` isolates missing/unused/duplicate declarations, unresolved imports and lockfile drift,
-missing npm/Go/Python deps, runtime
+missing npm/Go/Python deps, honest Maven/Gradle `NOT_SUPPORTED`/`PARTIAL` import verification, bounded
+Go/Java correctness candidates, runtime
 cycles, type-only/compile-only coupling, orphans, boundary rules, offline OSV vulnerabilities + typosquat +
 lockfile drift; accepts an immutable `base_ref`, `changed_files`, and `debt: new|existing|all` for
 review-scoped results; production paths are the default and `include_classified:true` opts into
@@ -311,8 +357,10 @@ not CFG, value-propagation, or taint analysis.
 **crossrepo** *(included in `offline`; absent from `pinned`; reads only registered local graphs)* —
 `trace_api_contract`; reconciles the selected backend/client graphs and joins routes to client callsites
 
-`query_graph` accepts optional `seed_files` when an architectural question must start from exact
-entry points. Resolved explicit seeds are exclusive by default; set `augment_seeds:true` only when
+`query_graph` accepts optional `seed_files` and exact `seed_symbols` when an architectural or
+event-driven question must start from known entry points. `relation_filter` limits edge kinds and
+`flow_direction:forward|backward|both` turns the same graph into a bounded producer/consumer view.
+Resolved explicit seeds are exclusive by default; set `augment_seeds:true` only when
 question-derived seeds are also wanted. A code-shaped identifier such as `startMitigate` is treated
 as a stronger bounded seed than surrounding words such as controller/service/flow; all exact
 same-name declarations are retained instead of adding unrelated concept seeds. Broad
@@ -322,7 +370,7 @@ and fixture matches. Production-first classification also applies during travers
 tests/generated/docs/benchmarks do not leak back from a production seed; name a class in the
 question or set `include_classified:true` to include it. Unreferenced unmatched constant/field leaves
 are hidden unless `include_low_signal:true`. Broad ranking remains orientation evidence; use
-`seed_files`, an exact endpoint, or `inspect_symbol` when the intended entry point is already known.
+`seed_files`, `seed_symbols`, an exact endpoint, or `inspect_symbol` when the intended entry point is already known.
 Instruction words such as “REST”, “path”, and “inspect” do not become fuzzy code seeds.
 
 **advisories** *(network, explicit opt-in)* — `refresh_advisories`
@@ -340,7 +388,29 @@ disclosed instead of silently guessed; and the server **hot-reloads its watched
 modules and catalog** when those files change — other MCP helpers and analysis engines require a
 reconnect. Every MCP response also carries local, transient `_meta["weavatrix/metrics"]` with elapsed
 time, output bytes/token estimate, graph freshness/revision/update and graph-cache status. These
-metrics are not persisted or transmitted by Weavatrix.
+metrics are not persisted or transmitted by Weavatrix. If a source checkout's package version moves
+while an old daemon remains alive, `initialize`, `tools/list`, and tool calls fail loudly with
+`STALE_RUNTIME` until the client reconnects; the opt-out is reserved for deliberate development.
+
+### 0.2.14 typed flows, honest Health, and architecture bootstrap
+
+- Go call resolution now follows receiver types through parameters, locals, constructor returns,
+  imported types and struct fields. It links calls such as `bgpSpeaker.RemoveMitigator(update)` to
+  `(*Speaker).RemoveMitigator` without guessing across ambiguous same-name receivers.
+- `query_graph` adds exact `seed_symbols`, `relation_filter`, and directed traversal for generic
+  event/queue/worker/cron/CLI flows. `context_bundle` ranks production callers before tests and uses
+  diverse edge-centered excerpts. `FlowSpec` no longer accidentally requests test traversal.
+- Health exposes per-capability completeness. Maven/Gradle support is honest instead of returning a
+  clean zero, and bounded Go/Java correctness findings never claim compiler, runtime, race, or
+  concurrency proof. Spring endpoints expose conditional/default-inactive controllers.
+- Architecture bootstrap adapts to Maven/Gradle/monorepo source roots and uses a reviewable
+  preview/approve handshake. A stale daemon now refuses analysis when its runtime version differs
+  from the package on disk.
+- The MCP implementation and static site are split into owner-focused modules/assets. A release test
+  enforces a physical 300-line maximum for JavaScript/TypeScript under `src`, `bin`, `scripts`, and
+  `test`, plus maintained HTML/CSS/JavaScript under `site`.
+
+Full patch notes: [docs/releases/v0.2.14.md](docs/releases/v0.2.14.md).
 
 ### 0.2.9 correctness, signal, and consent patch
 
@@ -727,10 +797,10 @@ The benchmark checks representative graph correctness, complete edge provenance,
 HTTP tracing, output bytes, latency, freshness, reconnect and active-target stability. Its budgets, semantics and intentionally
 limited claims are documented in [docs/benchmarking.md](docs/benchmarking.md).
 
-Refactoring target: keep focused implementation modules near 300 lines and split larger concerns
-into dotted-suffix modules behind a slim facade (`foo.js` re-exports `foo.parse.js`,
-`foo.report.js`, …). A few older orchestration modules remain above that target; new work should
-reduce them instead of growing new monoliths. The MCP layer lives
+Maintained JavaScript/TypeScript files under `src`, `bin`, `scripts`, and `test`, plus HTML/CSS/JavaScript
+under `site`, have a hard physical 300-line ceiling enforced by the release suite. Larger concerns are
+split into owner-focused modules behind slim stable facades (`foo.js` re-exports `foo.parse.js`,
+`foo.report.js`, …). The MCP layer lives
 in `src/mcp/` (graph context, tool entry modules, focused helpers, and the catalog/hot-reload
 loader) behind the thin stdio entry `src/mcp-server.mjs`.
 
@@ -738,9 +808,8 @@ loader) behind the thin stdio entry `src/mcp-server.mjs`.
 
 - **Public 0.2.2 regression foundation** now has the permanent six-language golden corpus,
   cross-repository wrapper/liveness fixture, framework/convention fixture, full MCP lifecycle gate
-  and a portable real-repository runner. Five source-free 0.2.1 real-repository baselines are
-  recorded; edge provenance is gated end-to-end. The unavailable Rust source checkout is the only
-  explicit local gap preventing the strict six-repository release command from passing here.
+  and a portable real-repository runner. Six source-free 0.2.1 real-repository baselines are
+  recorded; edge provenance is gated end-to-end and the strict six-repository release command passes.
 - **Wrapper-aware API contracts** shipped in 0.2.2: persistent/ad-hoc configuration,
   conservative discovery, cross-repository handler liveness and explicit unknown states. The next
   hosted increment joins privacy-safe contract identities across separately synced services.

package/SECURITY.md

@@ -4,8 +4,8 @@
 
 | Version | Supported |
 |---|---|
-| `0.2.9.x` | Yes |
-| `0.2.8` and older | Upgrade to the latest release |
+| `0.2.14.x` | Yes |
+| `0.2.13` and older | Upgrade to the latest release |
 
 Security fixes are provided for the latest published version of Weavatrix. Upgrade before reporting
 an issue that may already be resolved.

package/docs/releases/v0.2.14.md

@@ -0,0 +1,93 @@
+# Weavatrix 0.2.14
+
+0.2.14 is a trust and maintainability release found by dogfooding the MCP on a Go BGP service and a
+Java event-driven application. It keeps the 38-tool surface and the local-first/Hosted wire boundary,
+while closing false dead-code, false clean-health, noisy flow, weak architecture-bootstrap, and stale
+daemon failure modes.
+
+## Go receiver-aware call flow
+
+- Go call resolution now carries receiver types from function parameters, explicit and inferred
+  locals, constructor return types (including the first value of `value, err := pkg.New()`), imported
+  package types, and struct fields.
+- Calls such as `bgpSpeaker.RemoveMitigator(update)` resolve to
+  `(*Speaker).RemoveMitigator` instead of leaving the method falsely test-only.
+- Unknown or ambiguous same-name receivers still fail closed rather than inventing a call edge.
+
+## Focused generic flows
+
+- `query_graph` accepts exact `seed_symbols`, a `relation_filter`, and
+  `flow_direction: forward|backward|both`. The same bounded graph can now trace Kafka listeners,
+  queues, workers, cron jobs, CLI entry points, and other event/data flows without one tool per
+  framework.
+- Exact seeds remain exclusive unless `augment_seeds:true` is requested. CamelCase identifiers such
+  as `FlowSpec` no longer opt tests into production traversal merely because they contain `spec`.
+- `context_bundle` ranks production callers before classified test callers and uses diverse,
+  non-overlapping excerpts around decisive call sites.
+
+## Honest Health and endpoint state
+
+- `run_audit` returns an explicit capability matrix for structure, dependencies, runtime correctness,
+  concurrency, advisories, malware scanning, and measured coverage. Each row has independent status
+  and completeness.
+- Maven and Gradle manifests are detected and inventoried, but unsupported import-to-artifact
+  verification returns `NOT_SUPPORTED`/`PARTIAL` instead of a misleading complete zero.
+- Conservative source checks can flag selected Go fixed-index slice/discriminator hazards and Java
+  interruption/retry candidates, including conditional `while` and `do/while` loops with failure plus
+  wait behavior but no visible attempt/deadline/cancellation policy. The result explicitly does not
+  claim compiler, runtime, CFG, race, or full concurrency proof.
+- Ordinary Go grouped imports (`import (...)`) no longer trigger the JavaScript dynamic-import caveat;
+  real Go reflection evidence remains visible independently.
+- Spring endpoint inventory includes conditional activation evidence and whether a controller is
+  inactive by default.
+
+## Safe target-architecture bootstrap
+
+- The starter discovers adaptive Maven/Gradle source roots and nested monorepo product territories
+  instead of grouping an entire Java application under its first directory. Oversized Java package
+  branches split recursively at real child packages, while a large flat package remains an honest
+  size hotspot instead of being divided into invented components.
+- Observed dependency directions are proposed separately as `OBSERVED_NOT_ENFORCED`; inventory is not
+  silently promoted to intended architecture.
+- Only universal starter guards (`runtimeCycles=0`, `maxFileLoc=300`) are active. Generic function,
+  complexity, cohesion, and boundary thresholds are returned as `CANDIDATE_NOT_ENFORCED` so a first
+  preview does not manufacture hundreds of policy violations.
+- `maxFileLoc` now reads physical file LOC stored on file nodes, not the last declaration's end line;
+  older graphs rebuild before this budget can report a pass.
+- `get_architecture_contract action=preview` returns the materialized candidate, verification, exact
+  file content/hash, and a short-lived token without writing. `action=approve` rechecks repository and
+  graph identity, then creates only a missing `.weavatrix/architecture.json` with the exact reviewed
+  content. Existing policy is never overwritten.
+- `baseline_mode=accept-current` is an explicit owner action for ratcheting accepted current debt; the
+  default records no baseline findings.
+
+## Runtime and codebase integrity
+
+- The MCP compares its running version with the package version on disk. A mismatch blocks
+  `initialize`, `tools/list`, and tool calls with `STALE_RUNTIME` until the client reconnects. The
+  environment override is reserved for deliberate source development.
+- Large MCP, graph, analysis, precision, and test modules were split into owner-focused folders with
+  stable hot-reload facades. The watcher and cache-busting chain include the new graph, Health,
+  action, and architecture owner modules, so supported tool edits still go live without reconnecting.
+- The public page keeps the same design and continuous canvas graph animation while CSS and animation
+  code move into focused assets. A release test enforces a physical 300-line ceiling for
+  JavaScript/TypeScript under `src`, `bin`, `scripts`, and `test`, plus site HTML/CSS/JavaScript.
+- The 38-tool catalog and profile counts remain unchanged: 31 pinned, 34 offline, 35 OSV, and 38
+  hosted/full.
+
+## Compatibility and security
+
+- Hosted payload v2/v3, `preview_sync` confirmation, and architecture-contract transport are
+  unchanged. This release does not modify the separate Hosted frontend/backend application.
+- Local architecture approval writes only inside the active repository boundary, uses an exclusive
+  create, expires and consumes tokens, rejects repository/graph drift, and refuses an existing target.
+- Source bodies, snippets, absolute paths, credentials, environment values, and Git remotes remain
+  excluded from Hosted sync payloads.
+
+## Verification
+
+The release is gated by the full Node suite (538 tests: 535 passed and three platform skips), the
+six-language fixture benchmark, a 6/6 real-repository semantic-regression gate, zero npm audit
+vulnerabilities, packed npm and MCPB stdio checks, plus direct Go and Java dogfooding. Cold timings
+vary with machine load and repository snapshots; the public README keeps a dated representative
+run instead of presenting one release machine's timing as a universal result.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weavatrix",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "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.12.md",
+    "docs/releases/v0.2.14.md",
     "README.md",
     "SECURITY.md",
     "LICENSE"

package/skill/SKILL.md

@@ -16,15 +16,21 @@ Tools are named `mcp__weavatrix__…`. If none are available, ask the user to re
 (`claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot>`; Codex:
 `codex mcp add weavatrix -- npx -y weavatrix <repoRoot>`), then retry.
 
-If `refresh_advisories`, `preview_sync`, `pull_architecture_contract`, or `sync_graph` is missing, do not diagnose a
-broken installation: network tools are intentionally absent from `offline` and `pinned`.
+First compare the selected profile with the `graph_stats` runtime line. Expected catalogs are 31
+tools for `pinned`, 34 for `offline`, 35 for `osv`, and 38 for `hosted` / `full`. Weavatrix refuses
+`initialize`, `tools/list`, and tool calls when the running package version differs from the
+`package.json` version on disk, with a loud `STALE_RUNTIME` error; restart/reconnect rather than using
+an old daemon. `WEAVATRIX_ALLOW_STALE_RUNTIME=1` is only for deliberate source development. A custom
+capability list needs `crossrepo` for `trace_api_contract`; legacy `online` adds only
+`advisories,hosted`. Missing HTTP tools are intentional only when the selected profile excludes them.
 
 Profiles use the same npm package and binary:
 
 - `offline` (default): all local analysis and explicit `open_repo`; no HTTP tools.
 - `pinned`: local analysis with no `open_repo`, no global/cross-repository graph access, and no HTTP tools.
 - `osv`: `offline` plus explicit `refresh_advisories`.
-- `hosted` / `full`: `osv` plus local-only `preview_sync`, `pull_architecture_contract` and `sync_graph`.
+- `hosted` / `full`: `osv` plus local-only `preview_sync` and the explicitly invoked network tools
+  `pull_architecture_contract` and confirmed `sync_graph`.
 
 The legacy `online` capability remains a compatibility alias for `advisories,hosted`; prefer the
 named profiles for new registrations.
@@ -45,9 +51,13 @@ projection; expand only when the answer requires it.
 - **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.
+- **Find a connectivity path between two concepts**: `shortest_path`. It traverses the graph as
+  undirected reachability, so it is not proof of call/dependency direction; confirm direction with
+  `get_neighbors` and `read_source`.
+- **Explore an unknown entry point or architectural question**: `query_graph`; pin `seed_files` or
+  exact `seed_symbols` when known. Use `relation_filter` plus `flow_direction` for a bounded event,
+  worker, queue, cron, CLI, or data-flow view; keep a broad natural-language 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
@@ -63,25 +73,30 @@ projection; expand only when the answer requires it.
   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`; it distinguishes additive
-  exports from signature/body/removal risk and separates runtime/type-only radius plus available
-  measured coverage or explicitly static reachability.
+- **Review the current branch, diff, or external patch**: `change_impact`; its explicit baseline
+  parameter is `base`, not the `base_ref` used by audit/diff/verification tools. 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,
+- **Plan and verify a serious change or pre-commit gate**:
+  `verified_change task=<same-task> phase=plan base_ref=<merge-base>` -> edit ->
+  `verified_change task=<same-task> 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. It is
   a proof layer around an agent's edit, not a source editor or hidden auto-fix.
 
 ### Health, debt and testing scenarios
 
-- **Run a whole-repository Health review**: `run_audit debt=all`.
+- **Run a whole-repository Health review**: `run_audit debt=all`, then read its capability matrix.
+  `STRUCTURE CHECKED` and `DEPENDENCIES CHECKED` do not imply runtime or concurrency correctness.
 - **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.
+  Maven/Gradle manifests are inventoried but unsupported import-to-artifact verification is reported
+  `NOT_SUPPORTED`/`PARTIAL`, never a false clean `0 declared / 0 external`.
 - **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
@@ -95,23 +110,32 @@ projection; expand only when the answer requires it.
 
 ### 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.
+- **Read or establish intended architecture**: `get_architecture_contract`. A returned starter adapts
+  to Maven/Gradle source roots and monorepos and proposes product-code territories plus observed
+  dependency directions labelled `OBSERVED_NOT_ENFORCED`; oversized Java branches split only at real
+  child packages. Only runtime-cycle and 300-line file guards are active by default; generic
+  complexity/cohesion thresholds are `CANDIDATE_NOT_ENFORCED`. None becomes policy automatically.
+- **Bootstrap local policy safely**: `get_architecture_contract action=preview` with an optional
+  reviewed `candidate_contract` and `baseline_mode=none|accept-current`; inspect the exact content,
+  verification and patch, then call `action=approve confirm_token=<exact-token>`. Approval creates
+  only a missing `.weavatrix/architecture.json`, rechecks graph identity, and never overwrites 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.
+  `propose_architecture_exception`; proposals never mutate policy automatically. After human approval,
+  the owner must add the returned proposal to the local contract's `exceptions` or approve it in Hosted.
 - **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.
+Across every scenario, treat `PARTIAL`, `UNAVAILABLE`, `OFF`, `NOT_SUPPORTED`, `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 and Go receiver-type call edges are parser-resolved
+and explicitly `INFERRED`; Go resolution uses parameter, local, constructor-return, imported and
+struct-field types. These edges improve cross-file flow without claiming compiler-exact overload,
+interface dispatch, reflection, or runtime behavior.
 
 ## Ground rules
 
@@ -161,10 +185,15 @@ TypeScript/JavaScript overlay. Java receiver-type call edges are parser-resolved
   and the score is not profiler data or an interprocedural Big-O proof. The default queue uses
   `min_score=85` plus a narrow strong-local fallback; use `min_score=0` only for full diagnostics.
   Inspect its line evidence and measure runtime before scheduling a performance rewrite.
-- **Audit completeness**: read `dependencyReport.status` plus its unused/missing counts, then
-  each npm finding's `verification` (manifest, indexed source, scripts/config, unresolved dynamic
-  usage), then `checks.osv.status` and `checks.malware.status`. A dependency result from a partial graph is not a
-  repository-wide clean zero. For OSV, `OK` is
+- **Audit completeness**: read the top-level Health capability matrix first: structure, dependencies,
+  runtime correctness, concurrency, advisories, malware and measured coverage each have independent
+  status/completeness. The bounded Go/Java correctness patterns can flag a fixed-index slice hazard,
+  discriminator mismatch, lost Java interrupt or unbounded retry candidate, but they are not a
+  compiler, race detector, runtime trace, CFG, or proof of race freedom. Then read
+  `dependencyReport.status`, ecosystem support, unused/missing counts, each npm finding's
+  `verification` (manifest, indexed source, scripts/config, unresolved dynamic usage), and
+  `checks.osv.status` / `checks.malware.status`. A dependency result from a partial or unsupported
+  ecosystem is not a repository-wide clean zero. For OSV, `OK` is
   complete for the recorded dependency fingerprint; `PARTIAL` is incomplete or stale,
   `NOT_CHECKED` has no repository-specific result, and `ERROR` means the local check failed. Treat
   the same non-`OK` states as incomplete for malware scanning. Refresh OSV only when the user has
@@ -195,17 +224,19 @@ TypeScript/JavaScript overlay. Java receiver-type call edges are parser-resolved
 
 ## Recipes
 
-- **Proof-carrying refactor**: `verified_change task="..." phase=plan base_ref=<merge-base>` -> edit ->
-  `verified_change task="..." phase=verify base_ref=<same-ref> tests=[{"script":"test","args":[...]}]`.
+- **Proof-carrying refactor**: `verified_change task=<same-task> phase=plan base_ref=<merge-base>` -> edit ->
+  `verified_change task=<same-task> phase=verify base_ref=<same-ref> tests=[{"script":"test","args":[...]}]`.
+  Repeat `task` on both calls; it is required and is not retained between invocations.
   Add `run_tests:true` only when test execution was authorized. `BLOCKED` means an evidenced ratchet
   or test failure; `UNKNOWN` means at least one required proof is incomplete.
 
 - **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` → `context_bundle` → `get_dependents` →
+- **Refactor safety for one symbol**: `context_bundle` → optional `inspect_symbol` when raw LSP
+  occurrences, ambiguity details or the larger source window are needed → `get_dependents` →
   `coverage_map` (low coverage × many dependents ⇒ write tests first) → edit →
-  `verified_change phase=verify base_ref=<merge-base>`.
+  `verified_change task=<task> 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
@@ -236,8 +267,15 @@ TypeScript/JavaScript overlay. Java receiver-type call edges are parser-resolved
   safety semantics, not boilerplate. Use `.weavatrix-deps.json` entrypoints/nonRuntimeRoots only for
   verified conventions.
 - **API inventory**: `list_endpoints` (including mount provenance, Next.js App Router, Rust axum and
-  actix-web). When one exact route is known, use `trace_endpoint` for its composed mount chain,
-  handler and bounded production call graph instead of broad natural-language traversal.
+  actix-web). Spring endpoint rows also expose conditional activation and whether the controller is
+  inactive by default. When one exact route is known, use `trace_endpoint` for its composed mount
+  chain, handler and bounded production call graph instead of broad natural-language traversal.
+- **CLI, worker, queue, cron or event flow**: identify the exact listener/handler/registration symbol,
+  then call `query_graph seed_symbols=[...] relation_filter=["calls","references"]
+  flow_direction="both"`; use `context_bundle` for production-first inbound/outbound containers and
+  diverse call-site excerpts, then `get_dependents` / `read_source` for decisive evidence. If the
+  symbol is unknown, use a narrow `search_code` registration check once and pin what it finds. Do not
+  force a non-HTTP flow through endpoint tools or begin with an unconstrained natural-language seed.
 - **Cross-repository API impact**: ensure both repositories are in `list_known_repos`, then call
   `trace_api_contract backend=<uuid-or-label> clients=[<uuid-or-label>]`; narrow with `method`, `path`,
   or backend `changed_files`. `path` may be a segment-aligned fragment (`/query` can select
@@ -248,27 +286,34 @@ TypeScript/JavaScript overlay. Java receiver-type call edges are parser-resolved
   confidence; only an unambiguously resolved handler node can suppress a dead-method candidate.
   `POSSIBLE_EXTERNAL_USE`, `UNKNOWN`, and remaining unresolved/dynamic URLs are incomplete evidence,
   never proof that a method is dead.
-- **Release regression gate**: for a Weavatrix source checkout, use `npm test` for the quick
-  six-language golden corpus and `npm run benchmark` before release for the real MCP
+- **Release regression gate**: for a Weavatrix source checkout, use `npm test` for the full
+  unit/integration suite, `npm run benchmark:quick` for the quick six-language golden corpus, and
+  `npm run benchmark` before release for the golden corpus plus the real MCP
   `full -> incremental -> none -> reconnect/none` lifecycle, bounded output and active-target checks.
   Use `npm run benchmark:real` for available manifest repositories and
   `npm run benchmark:real:release` only when all six source checkouts are present; `MISSING`,
   `UNBASELINED` and `STALE` are explicit incomplete states, not green results.
   A green Java/Rust fixture proves only its declared representative signals, not compiler-exact
   coverage of arbitrary repositories.
-- **Target architecture before editing**: `get_architecture_contract` → `prepare_change` with the
-  intended files → edit and rebuild → `verify_architecture`. A missing contract returns a starter
-  proposal from `get_architecture_contract output_format:"json"`, not an automatically approved
-  architecture. Without a contract, `prepare_change` still returns provisional no-regression
-  budgets, but they are guidance rather than enforceable policy. Pull an owner-approved hosted
-  contract only when the user selected `hosted` and explicitly asks for it.
+- **Target architecture before editing**: if no contract exists, call
+  `get_architecture_contract action=preview baseline_mode=none` and inspect the adaptive product
+  territories, observed-but-not-enforced directions and verification. Pass a reviewed
+  `candidate_contract` when the desired target differs. Only after explicit owner approval call
+  `get_architecture_contract action=approve confirm_token=<exact-token>`. Use
+  `baseline_mode=accept-current` only when the owner intentionally accepts current deterministic
+  debt into the ratchet. Then run `prepare_change` with intended files → edit/rebuild →
+  `verify_architecture`. An approved exception is still applied by adding the exact returned proposal
+  to `exceptions` and verifying again. Existing contracts are never overwritten; Hosted contracts
+  are pulled only after explicit opt-in. No tool silently changes an active policy.
 - **Behavioral architecture**: `git_history` ranks churn × connectivity hotspots and hidden
   co-change coupling from bounded local numstat history. Always set `top_n`; it is enforced across
   every returned structured collection and JSON reports per-collection truncation. Use it as review
   evidence, not proof that two files must be merged.
 - **Machine output**: keep the default `output_format:"text"` for concise agent conversations; opt
   into `output_format:"json"` only when a workflow consumes the full `weavatrix.tool.v1` envelope.
-- **Find code**: `search_code` (regex + glob) → `get_node` → `read_source`.
+- **Find code**: `search_code` (regex + glob) →
+  `read_source path=<match-path> start_line=<match-line>`; add `get_node` / `get_neighbors` only after
+  identifying an exact graph symbol.
 - **Another repo**: `list_known_repos` → `open_repo <path>`
   (builds or upgrades the graph when needed; `build:false` probes without building).
 
@@ -276,9 +321,29 @@ TypeScript/JavaScript overlay. Java receiver-type call edges are parser-resolved
 
 Weavatrix understands nearest workspace manifests, nested `tsconfig`/`jsconfig` aliases,
 framework-owned runtime peers such as Next.js + `react-dom`, generated NAPI-RS platform loaders,
-and Next.js App Router route exports. For project-specific entry points, reusable template catalogs,
-or Python dependencies supplied by an external runtime, add `.weavatrix-deps.json` at the repository
-root:
+and Next.js App Router route exports. Use repository-root `.weavatrix.json` to correct ambiguous
+production classification without deleting graph evidence:
+
+```json
+{
+  "classify": {
+    "generated": ["src/generated/**"],
+    "test": ["qa/**"],
+    "product": ["benchmarks/core/**"]
+  },
+  "exclude": ["resources/snapshots/**"]
+}
+```
+
+Use `generated` / `test` (or `e2e`, `mock`, `story`, `docs`, `benchmark`, `temp`) for non-production
+code, top-level `exclude` for resource/catalog roots that should stay visible in the graph but not
+drive production-first Health/query ranking, and `product` only to opt a verified benchmark/temp path
+back into production review. `product` does not override an explicit generated/test classification or
+`exclude`. Use `.weavatrixignore` instead only when a path must be removed consistently from graph,
+audit and duplicate scans.
+
+For project-specific entry points, reusable template catalogs, or Python dependencies supplied by an
+external runtime, add `.weavatrix-deps.json` at the repository root:
 
 ```json
 {