weavatrix 0.2.13 → 0.2.15

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 |
 |---|---:|---|
@@ -218,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.
 
@@ -240,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`
@@ -252,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
@@ -318,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
@@ -329,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`
@@ -347,25 +388,45 @@ 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.
-
-### 0.2.13 runtime-integrity and cross-language verification patch
-
-- `verified_change` no longer requires `package.json` when no package tests can run. Python, Go,
-  Java, Rust and other non-Node repositories now receive `NOT_REQUESTED` or `DISABLED` test evidence
-  instead of a false `BLOCKED`; actual package-script execution keeps the same double opt-in and
-  allowlist.
-- Release verification starts the packed npm artifact and portable MCPB stage over stdio. It asserts
-  the exact profile counts and required 38-tool `full` surface, including `trace_endpoint`,
-  `trace_api_contract` and `preview_sync`, so source/package drift cannot publish silently.
-- Runtime diagnostics expose the package version, selected capability groups and registered tool
-  count. The documentation now distinguishes an old client connection from an intentional profile
-  omission and explains that custom capabilities need `crossrepo` for contract tracing.
-- The bundled skill documents practical CLI/worker/event flows, local target-architecture adoption,
-  repository classification, undirected path semantics and the correct release and proof-carrying
-  change recipes without reducing Weavatrix to text search.
-
-Full patch notes: [docs/releases/v0.2.13.md](docs/releases/v0.2.13.md).
+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.15 self-audit precision patch
+
+- Dependency review now scopes nested manifests correctly, recognizes framework peer packages and
+  package references assembled from bounded dynamic path fragments, and avoids misclassifying
+  dependency-owned source as an unused root declaration.
+- Reachability follows source-owned HTML asset references, so maintained browser entry scripts and
+  styles remain part of the production surface instead of appearing as dead files.
+- Malware heuristics distinguish inert placeholders, comments, documentation URLs, and ordinary
+  Unicode text from executable registry or download behavior while retaining explicit review
+  evidence for actionable patterns.
+- Duplicate review ignores policy-like numeric tables and stable ordered-member declarations where
+  repetition is intentional, and the remaining reverse-reach, Git-output, member-order, path-term,
+  and retrieval logic now uses shared owners instead of drifting copies.
+
+Full patch notes: [docs/releases/v0.2.15.md](docs/releases/v0.2.15.md).
+
+### 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
 
@@ -752,10 +813,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`.
 
@@ -763,9 +824,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.15.x` | Yes |
+| `0.2.14` 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.15.md

@@ -0,0 +1,37 @@
+# Weavatrix 0.2.15
+
+0.2.15 is a focused self-audit precision release. It keeps the 38-tool MCP surface and all wire and
+security boundaries stable while removing false-positive dependency, dead-code, malware, and
+duplicate findings discovered by running Weavatrix against its own repository.
+
+## Dependency and reachability precision
+
+- Dependency verification now respects the owning nested manifest before deciding whether an import
+  is missing or a declaration is unused.
+- Framework peer dependencies and bounded package paths assembled from static string fragments are
+  recognized without treating arbitrary runtime values as proof.
+- Source-owned HTML asset references participate in reachability, protecting maintained browser
+  scripts and styles from false dead-file findings.
+
+## Safer review queues
+
+- Malware scanning distinguishes placeholders, comments, documentation URLs, and ordinary Unicode
+  text from executable registry/download behavior. Static heuristic evidence remains review-only and
+  does not claim execution or compromise.
+- Duplicate detection suppresses policy-like numeric tables and stable ordered declarations where
+  repeated structure carries meaning, while preserving clone evidence for executable code.
+- Reverse reachability, Git output parsing, ordered-member comparison, path terminology, task
+  retrieval, and duplicate evidence now share focused owners instead of maintaining divergent copies.
+
+## Compatibility and security
+
+- There are no MCP tool-schema, capability-profile, Hosted payload, sync-consent, or architecture
+  contract changes in this release.
+- The default profile remains offline and local-first. Advisory and Hosted network capabilities
+  remain explicit opt-ins.
+
+## Verification
+
+The release is gated by the full Node suite, six-language fixture benchmark, six-repository semantic
+regression gate, release-manifest verification, packed npm and MCPB stdio checks, and npm audit. The
+exact counts and artifacts are recorded by the immutable GitHub release workflow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weavatrix",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "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.13.md",
+    "docs/releases/v0.2.15.md",
     "README.md",
     "SECURITY.md",
     "LICENSE"

package/skill/SKILL.md

@@ -17,10 +17,11 @@ Tools are named `mcp__weavatrix__…`. If none are available, ask the user to re
 `codex mcp add weavatrix -- npx -y weavatrix <repoRoot>`), then retry.
 
 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`. If the running
-version/count differs from the installed package, or local tools such as `trace_endpoint` are missing,
-reconnect/start a new agent task because clients commonly cache `tools/list` for one connection. A
-custom capability list needs `crossrepo` for `trace_api_contract`; legacy `online` adds only
+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:
@@ -53,8 +54,10 @@ projection; expand only when the answer requires it.
 - **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` when
-  known, and keep its broad result as orientation evidence.
+- **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
@@ -86,11 +89,14 @@ projection; expand only when the answer requires it.
 
 ### 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
@@ -104,9 +110,15 @@ 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` ->
@@ -117,11 +129,13 @@ projection; expand only when the answer requires it.
 - **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
 
@@ -171,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
@@ -248,12 +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.
-- **CLI, worker, queue, cron or event flow**: locate the manifest/registration literal with
-  `search_code`, then pin the discovered entry file with `query_graph seed_files=[...]`; use
-  `context_bundle` on its exact handler plus `get_neighbors` / `get_dependents`, and confirm the
-  registration and call sites with `read_source`. Do not force a non-HTTP flow through endpoint tools.
+  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
@@ -273,19 +295,16 @@ TypeScript/JavaScript overlay. Java receiver-type call edges are parser-resolved
   `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. For offline adoption, have the owner review/edit `starterContract`, save it as
-  `.weavatrix/architecture.json`, and rerun the lookup. To establish a ratchet over accepted current
-  debt, run `verify_architecture output_format:"json"`; only after explicit owner approval, copy the
-  accepted `verification.new[*].fingerprint` values into `ratchet.baseline.fingerprints`, save, and
-  verify again so accepted debt is `existing` while later debt is `new`. The v1 verifier classifies
-  ratchet debt by fingerprints; `ratchet.baseline.metrics` is metadata, not a replacement. An approved local exception
-  is applied by adding the exact returned `proposal` to `exceptions`; rerun verification afterward.
-  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. No Weavatrix tool silently writes either policy.
+- **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

package/src/analysis/architecture/contract-graph.js

@@ -0,0 +1,119 @@
+import {architectureHash} from './contract-schema.js'
+
+export const isSymbolNode = (id) => String(id).includes('#')
+const endpointId = (value) => value && typeof value === 'object' ? String(value.id) : String(value ?? '')
+
+export function fileOfNode(id, byId) {
+    const node = byId.get(String(id))
+    if (node?.source_file) return String(node.source_file).replace(/\\/g, '/')
+    return String(id).split('#')[0].replace(/\\/g, '/')
+}
+
+export function componentForFile(file, components) {
+    const normalized = String(file || '').replace(/\\/g, '/')
+    let best = null
+    for (const component of components) for (const prefix of component.paths) {
+        if (normalized !== prefix && !normalized.startsWith(`${prefix}/`)) continue
+        if (!best || prefix.length > best.prefix.length) best = {id: component.id, prefix}
+    }
+    return best?.id || '(unmapped)'
+}
+
+export function relationKind(link) {
+    if (link.typeOnly === true) return 'type-only'
+    if (link.compileOnly === true) return 'compile-only'
+    return 'runtime'
+}
+
+export function runtimeFileGraph(graph) {
+    const byId = new Map((graph.nodes || []).map((node) => [String(node.id), node]))
+    const files = new Set((graph.nodes || []).filter((node) => !isSymbolNode(node.id)).map((node) => String(node.id)))
+    const adjacency = new Map([...files].map((file) => [file, new Set()]))
+    for (const link of graph.links || []) {
+        if (relationKind(link) !== 'runtime' || !['imports', 're_exports'].includes(link.relation) || link.barrelProxy === true) continue
+        const source = fileOfNode(endpointId(link.source), byId)
+        const target = fileOfNode(endpointId(link.target), byId)
+        if (source && target && source !== target && files.has(source) && files.has(target)) adjacency.get(source)?.add(target)
+    }
+    return adjacency
+}
+
+export function stronglyConnected(adjacency) {
+    let index = 0
+    const indexes = new Map(), low = new Map(), stack = [], onStack = new Set(), out = []
+    const visit = (node) => {
+        indexes.set(node, index); low.set(node, index); index++; stack.push(node); onStack.add(node)
+        for (const target of adjacency.get(node) || []) {
+            if (!indexes.has(target)) { visit(target); low.set(node, Math.min(low.get(node), low.get(target))) }
+            else if (onStack.has(target)) low.set(node, Math.min(low.get(node), indexes.get(target)))
+        }
+        if (low.get(node) !== indexes.get(node)) return
+        const component = []
+        while (stack.length) {
+            const value = stack.pop()
+            onStack.delete(value)
+            component.push(value)
+            if (value === node) break
+        }
+        if (component.length > 1 || adjacency.get(node)?.has(node)) out.push(component.sort())
+    }
+    for (const node of [...adjacency.keys()].sort()) if (!indexes.has(node)) visit(node)
+    return out.sort((a, b) => b.length - a.length || a[0].localeCompare(b[0]))
+}
+
+export function architectureViolation(ruleId, kind, evidence, current, target) {
+    const normalizedEvidence = String(evidence).replace(/:\d+(?=\b|$)/g, '')
+    const fingerprint = architectureHash({ruleId, kind, evidence: normalizedEvidence}).slice(0, 32)
+    return {fingerprint, ruleId, kind, evidence, ...(current != null ? {current} : {}), ...(target != null ? {target} : {})}
+}
+
+export const matchComponentSelector = (selector, value) => selector.includes('*') || selector.includes(value)
+
+export function collectComponentEdges(graph, contract) {
+    const nodes = Array.isArray(graph?.nodes) ? graph.nodes : []
+    const links = Array.isArray(graph?.links) ? graph.links : []
+    const byId = new Map(nodes.map((node) => [String(node.id), node]))
+    const componentEdges = new Map()
+    for (const link of links) {
+        if (!['imports', 're_exports', 'calls', 'references'].includes(link.relation) || link.barrelProxy === true) continue
+        const fromFile = fileOfNode(endpointId(link.source), byId)
+        const toFile = fileOfNode(endpointId(link.target), byId)
+        if (!fromFile || !toFile || fromFile === toFile) continue
+        const from = componentForFile(fromFile, contract.components)
+        const to = componentForFile(toFile, contract.components)
+        if (from === to) continue
+        const kind = relationKind(link)
+        const key = `${from}\0${to}\0${kind}`
+        const record = componentEdges.get(key) || {from, to, kind, count: 0, samples: []}
+        record.count++
+        if (record.samples.length < 5) record.samples.push(`${fromFile} -> ${toFile}`)
+        componentEdges.set(key, record)
+    }
+    return {nodes, links, byId, componentEdges}
+}
+
+export function collectComponentFitness(nodes, links, byId, contract) {
+    const stats = new Map(contract.components.map((component) => [component.id, {
+        files: new Set(), internalPairs: new Set(), boundaryPairs: new Set(),
+    }]))
+    for (const node of nodes.filter((item) => !isSymbolNode(item.id))) {
+        const file = String(node.source_file || node.id).replace(/\\/g, '/')
+        stats.get(componentForFile(file, contract.components))?.files.add(file)
+    }
+    const runtimePairs = new Set()
+    for (const link of links) {
+        if (relationKind(link) !== 'runtime' || !['imports', 're_exports', 'calls', 'references'].includes(link.relation) || link.barrelProxy === true) continue
+        const source = fileOfNode(endpointId(link.source), byId), target = fileOfNode(endpointId(link.target), byId)
+        if (!source || !target || source === target) continue
+        const pair = `${source}\0${target}`
+        if (runtimePairs.has(pair)) continue
+        runtimePairs.add(pair)
+        const from = componentForFile(source, contract.components), to = componentForFile(target, contract.components)
+        if (from === to) stats.get(from)?.internalPairs.add(pair)
+        else {
+            stats.get(from)?.boundaryPairs.add(pair)
+            stats.get(to)?.boundaryPairs.add(pair)
+        }
+    }
+    return stats
+}