repovine

Run architecture analysis for a scope or expand one finding. This is read-only and heuristic: treat findings as review candidates. Use after context mapping or when the user asks for smells, risks, duplicated responsibilities, security-sensitive boundaries, frontend state/effect issues, or event boundaries. Empty reports or missing finding detail include emptyDiagnostic with reason and conditional nextActions. Detectors read modules, runtime resources and domains, so all, pkg:, domain:, mod: and resource: scopes are inspected and every other scope kind is refused by name. A mod:/resource: scope holds one node: per-node signals are reported in full, comparisons between in-scope nodes cannot fire, and gaps says so. Report mode previews each finding's nodes and reports the cut in the finding's truncation block; pass detailFindingId for the full maxNodes-bounded node set.

Analyze import/export contracts and dependency risk. Replaces impact, cross-package dependencies, interface implementations, and import-map style queries. Use before changing exported APIs, types, package boundaries, interfaces, or shared modules. Empty or mode/scope-mismatch results include emptyDiagnostic with reason and conditional nextActions. impact on an export-symbol scope (or a module scope plus exportName) resolves reverse callers: precise resolved-import callers carry uses; callers matched by call name carry provenance {basis:"inferred",method:"call-name-index"} (spans re-export barrels) and are counted by nameMatchedCallers; an entry without provenance was reached over a graph edge. The name index is capped per declaration while extracting, so it is a completeness backstop, not grep parity, and gaps say so. impact, interface-implementations, and package-boundaries cap every returned list; each cut reports shown/total and how to reach the rest, in result.analysis.truncation for a top-level list and in a truncation block beside the list itself for a nested one (topModuleEdges on a package edge, importedBy on a boundary violation). An oversized result is withheld whole behind the envelope-level truncation.result with narrowing guidance.

Record declined advisory items in workspace-local state so they stop resurfacing; the advisory producers stay read-only. kind "domains-config": hide suggestion ids from suggest_domains_config in .repovine/onboarding-state.json; never writes the committed repovine.domains.json. kind "carrier-link-gaps": record reviewed-not-a-gap decisions per consumer-risk SSOT target in .repovine/carrier-review.json; each decision stores a riskHash of the target's consumer-scoped risks — a changed risk set re-surfaces the target; validate_annotations reports suppressedTargets and view:"carrier-gaps" keeps reviewed targets visible; never writes repovine.annots.json. Declines are workspace-local (not committed) — triage does not travel with clones. Pass ids from the kind's advisory surface, or all: true to decline every currently visible item. reason is stored per target for carrier-link-gaps and ignored for domains-config.

Check whether repovine.annots.json exists, is parseable, contains conflict markers, or has an unmerged git index entry. Use before annotation work and after pull/merge/rebase. indexUnmerged marks a file-level conflict (or a hand-resolved file) that carries no markers.

Report annotation build health: coverage, stale/missing annotation queue, and orphaned annotations. Use before annotation work or when trusting graph notes. The default queue is ONE unified, bottom-up backlog spanning annotatable node types — code modules, templates, services, infra (IaC), and domain roll-ups. Queue sort order: content-stale (staleKind:content) before propagation-stale (staleKind:propagation), then unannotated; within each tier, modules/templates before domain roll-ups and lower dependency depth first. Drain via view:"queue" top pages — do not run propagation-first via derived-review unless content-stale is cleared or orchestrator requests propagation-only. view:"risk-scope-candidates" pages advisory plain/local risk entries that look like scope:"consumer" or scope:"boundary" authoring candidates; they are not stale items and do not affect needsWork. view:"carrier-gaps" pages missing-carrier-link candidates grouped by consumer-risk SSOT target, with per-target riskHash and reviewed/suppression state from .repovine/carrier-review.json; reviewed targets stay visible, never filtered. Propagation-stale is in needsWork as stale+staleKind:"propagation". Annotation work is complete when needsWork is 0 for every type. Coverage counts the same backlog: allNodeTypes.needsWork on view:"coverage" equals needsWork on view:"queue". A bucket may also report unconfirmable — nodes no freshness question is asked about (no hash source, no graph node, or an advisory package-domain roll-up). They are inside total and never inside needsWork, so a coverage shortfall with needsWork 0 is unconfirmable nodes, not work.

Report the current build status of the repository graph. Use when other tools return a `result.status:"building"` payload to discover the current stage, remaining stage count, progress, and recommended retry delay. stageEtaSec estimates only the current stage, not time until ready. Stage 1 reports package/module counts; stage 3 reports semantic search embed card counts when `semantic_search_embeddings` is enabled. Always callable; returns immediately by default. Pass waitSec to long-poll: the call holds server-side and returns the moment the build settles (ready or failed) or the wait expires — one waiting call instead of a polling loop. Pass cancel:true to stop an in-flight startup build (mutating): it stops Stage 1 where it stands — every worker thread is asked to shut down and force-terminated after a few seconds' grace, so packages still extracting are dropped and the work already done on them is discarded. The response is the post-cancel status: `cancelled` (bare tree, no graph; other tools then report an error with the recovery action, since a settled build is not something to wait for) when no prior graph exists, or `ready` when a prior graph keeps serving. get_build_status itself answers normally in every state — reporting a failed build is an answered question. cancel ignores waitSec and is a no-op returning the current status when no build is running.

Inspect configuration and resource-binding surface: env vars, secrets, public config, and code-to-resource bindings. Items carry kind env, secret, public-config or resource-binding; the kind filter also accepts iac-param, which no item carries, so a filter on it returns nothing. Use before adding config, changing resource names, or debugging hidden runtime coupling. Empty results include emptyDiagnostic with reason and conditional nextActions.

Return the deterministic Context Session Quality report for a contextSessionId/sessionId recorded from repovine MCP tool responses. The report is computed from returned tool JSON and shaped response byte volume, not from agent prose. Use before accepting a subagent handoff. overall is an observation, not a graded assessment: shipped weights reduce it to 1 when the session called inspect_node and 0 otherwise, because the former 14-weight score failed its outcome-labelled falsification. acceptHandoff and rejectReasons are advisory in every mode, including harness — they emit warnings and requiredFollowups and never fail compliance. docs/context-quality.md states the return bar a hard gate must clear first.

List execution entrypoints independent of stack: pages, routes, APIs, webhooks, queue consumers, schedules, websockets, and unknown starts. The kind filter also accepts cli, worker and test, which no shipped interpreter emits — a filter on one of them returns nothing about a repository that has them. Routes are just one entrypoint kind; provider/runtime details are returned as metadata instead of being baked into the tool name. Prefer package, module, service, or query scopes for runtime lookup; domain scopes are semantic/path tags and may be empty. Empty results include emptyDiagnostic with reason and conditional nextActions.

Inspect one graph node in detail. For modules it returns exports/signatures/line ranges/annotations; for exports it returns signature/calls and can include source body. Use this only after narrowing context. The response points deeper, sideways, up, and cross-layer; package and domain scopes also point at validation. Annotations hint and constrain; they do not bound inspect scope — no annotation means no pre-written checklist, not skip. Stating a nodeId is unchanged requires inspect_node on that nodeId in the same session; annotation on another nodeId is not evidence for it. A derived capability, permission, or feature flag is consumed by every importer of the module that derives it, not by that module alone; on boundary tasks inspect those consumers before treating them unchanged. Investigate channel: a `links`/`drillDown`/`investigatePointers` ref returned with `investigate` is must-inspect; inspect that node and close the flag as fixed or scoped-out with a code citation before reporting this node unchanged. Tags: `risk` (consumer-scoped risk on the target), `boundary` (off-limits surface — published contract, frozen migration, or structural slot — not edited in place), `effect` (target declares a persistent side effect), `wiring` (deployed runtime topology dispatches into or binds from the target), `co-change` (implements relation — contract and implementations move together), `hub` (target has many importers; impact-check before editing). Same-node citation: that code citation must be on the affordance path of the flagged node itself; gating by a sibling control, a parent or badge, or a different mount does not close the flag unless this affordance is shown to route through that gate. Enumerate-before-unchanged: reviewing a node means listing each mutation affordance, exported action, and protected side effect on it (mutation = anything that creates, changes, or removes state — including but not limited to writes, deletes, dispatches, and lifecycle callbacks) with its capability gate; a single gated affordance does not close a multi-affordance node — `affordanceCount` reports how many to enumerate. These are floors, not ceilings: the `investigate` tags and `affordanceCount` are minimums to check, their absence is not absence of work, and closing every delivered flag or enumerating one node is per-node completeness, never task completeness. When annotations are returned, treat relevant invariants, risks, dataFlow/flowDescription, integrationPoints, and sideEffects as verification obligations: must preserve, must verify, known risk, or surface to check before editing. annotationMeta.fresh answers for the whole note and matches what the annotation queue reports for that node; when it is false, staleReason names the check that decided it — content (the node text moved, rewrite the note), schema (backfill), no-baseline (written with no hash to compare against, rewrite), propagation (the note still matches this node but a module it imports moved, so re-verify its integrationPoints/dataFlow claims before relying on them). fresh is omitted only for a node kind that carries no hash at all. References in links or drillDown may carry an investigate tag (risk/boundary/effect/wiring/co-change/hub) — the target holds a consumer-scoped risk, a boundary-scoped risk (off-limits surface), a persistent side effect, runtime wiring (deployed topology dispatches into or binds from it), an implements relation (contract and implementations move together), or many importers; investigatePointers surface the same flags for a deeper dependency named in this node's integrationPoints, and are must-inspect under the same closure. Structural-only tags may stay inline instead of being duplicated into attention/navigation; affordanceCount reports how many affordances/exports the node has to enumerate. The response may also carry a top-level attention block — edit-relevant signals hoisted for primacy as data plus the cheapest next call, never a gate.

Map the architectural area for a scope before reading code. Returns domain/package/module context, top connected modules, subdomains, semantic summary, and navigation. Use this after search_context or when the user names a feature/package/module directly. Empty/unresolved maps include emptyDiagnostic with reason and conditional nextActions. On a domain scope, taggedModules counts modules and taggedNonModuleCount the resources and subdomains beside them; byPackage keys are package ids, and modules under no package sit in withoutPackage.

Resolve conflict markers in repovine.annots.json using annotation merge rules. Different node IDs are combined, compatible annotation fields are merged, and ambiguous scalar fields are reported for review. Scalar conflicts add patterns such as merge-review:summary plus [merge-review:…:ours/theirs] assumptions for a later write_annotation rewrite. This writes repovine.annots.json, and snapshots the replaced worktree file under .repovine/annotation-backups/ (named in replacedBackupPath) whenever git index stages are the merge input. dryRun writes neither.

Build or refresh the repository syntax index after code changes. Acts as a synchronization barrier. The response reports graph deltas, annotation orphan status, searchTokens (token+annotation index size), semanticSearch ({ status: disabled|up_to_date|updated|failed, embedded?, total?, error? }), which reports status disabled while semantic_search_embeddings is off, and domainsSuggestions ({ count, axes, declinedHidden }) for first-run domains advisor follow-up. annotationMergeKeeps ({ readded, reverted, sample, warning }) appears when the reload kept in-memory notes the file disagreed with — the shape a reverted repovine.annots.json produces, which is otherwise undone silently. buildRefusals ([{ reason, kind, message, details? }]) appears when the build refused something and lists every refusal: a path outside the workspace, a source plugin whose prerequisite is missing, a plugin the config could not load, a file two plugins claimed, or a graph that did not take every scanned record. What it names is absent from the graph, so a count that looks low is explained here. get_build_status reports the same array for the first build, and repovine status prints it. outsideRepo ({ count, sample, warning }) projects the containment refusal from that array in the shape it has always been published in. Pass reloadConfig: true after editing repovine.config.json to re-read config and rebuild with a fresh runtime; pass cleanupOrphans: true to remove orphaned annotations after rebuild. After get_build_status({ cancel: true }) left the server in result.status:"cancelled" (no graph), refresh_context re-triggers a fresh background build and returns the building status.

Find likely repository context for a task. Searches domains, packages, modules, exports, templates, services, entrypoints, and config names. Use this when the task is still fuzzy or starts from a keyword/symbol. Combines a deterministic token index with optional local embeddings over graph node cards when semantic_search_embeddings is enabled. Multi-token queries default to match auto: AND (every token on one node) first, then bounded OR per token when AND finds nothing. emptyDiagnostic appears only when totalResults is 0 and there are no config/entrypoint aux matches — not when OR-relax produced hits. When hits exist after OR-relax, read result.matches.strategy (used, relaxedFrom, strongTokens, weakTokenOnlySuppressed), gaps, topResults[].matchedTokenCount/score, and summary/confidence before inspect_node. When topResults[].annotationMatched is true, annotation fields are omitted — use inspect_node on that nodeId before source-only reasoning. annotationStale beside it says the matched words come from a note the node content has since outrun: the hit is still a lead, its wording is not evidence for the current code. Weak/common tokens (package, route, handler, module, …) match at reduced weight; auto may suppress OR noise via weakTokenOnlySuppressed. A semantic-only nearest neighbour has low confidence, no matched tokens, and an advisory suggestedScope reason; it is not evidence that the requested functionality exists. When perTokenLimit truncates an OR posting list before global ranking, strategy.truncation names each affected token with shown/total counts, gaps repeat them, and confidence is low. Responses include matchedTokens, strategy.semantic.used/attempted, semanticRank/semanticScore on fused hits, suggestedScopes, navigation, and emptyDiagnostic reasons such as no_token_hits, strict_and_no_single_node, and filtered_out (with details.narrowings naming what removed the rows).

Return additive graph-derived suggestions for repovine.domains.json. This tool is read-only: it reports additions, counts, merge strategy, declined-hidden count, a mergedConfig preview (accept = exclude), and, when an infra-noise suggestion is keepable, a keepConfig preview (keep = a committed infra.keep marker that keeps the resource visible and stops the suggestion). Agents should show the diff to the user and only write repovine.domains.json after approval (mergedConfig to accept, keepConfig to keep), then call refresh_context. To skip without committing, call decline_advisory({ "kind": "domains-config" }) instead.

Trace runtime/data flow through modules, services, resources, triggers, and entrypoints. Use this for cross-layer questions: UI to API, API to queue, queue to worker, worker to DB/resource, and request routing (e.g. ingress to backend service, surfaced as routesTo/routedFrom on a service). The tool reports only graph-proven links and lists gaps when a transition cannot be proven. runtimeHandoff lists the handler module (mod:) of a traced runtime resource under three triggers, named per item: secret-binding (the resource or its handler binds a secret resource), annotation (a consumer- or boundary-scoped risk on the resource or its handler), and scoped-resource (a resource: scope, or a module scope with exactly one infra resource behind it). A summary-only note and a risk with no scope carry no trigger. Annotations and consumer/boundary obligations live on code nodes, not on resource listings alone. Prefer service or package scopes; domain scopes only work when the domain directly owns runtime services/resources. Topology is narrowed by all, resource:, mod:, pkg:, domain: and query: scopes; export:, template: and infra: scopes answer empty with emptyDiagnostic reason scope_kind_not_analyzable and details.supportedScopeKinds. Empty results include emptyDiagnostic with reason and conditional nextActions.

Validate repovine.annots.json against the current graph after annotation-file merge, especially after pull/merge/rebase, or before handoff. Reports conflict markers, parse problems, orphaned notes, content-stale and propagation-stale notes, riskScopeCandidates advisory counts, carrierLinkGaps candidates (runtime 2-hop delegation, minus targets suppressed via decline_advisory kind "carrier-link-gaps"), counts.inconsistent (notes naming something the graph does not have — advisory, does not move status), and annotation queue next actions.

Write or update an annotation for a module, export, template, domain, or service. Shared memory write path after understanding or changing code. Existing fields are merged; send only fields that changed. On a node whose content moved since the note was written, a partial write leaves the note content-stale and names the fields it did not resubmit — resubmit every field to clear it. New notes require annotation.summary; empty updates and obvious secret values are rejected. For code modules, every write snapshots importBaseline (direct import contentHashes) for propagation-stale detection. To clear propagation-stale without changing prose, pass refreshImportBaseline: true alone; that shape is the one hard consistency issues refuse. A write that carries annotation fields re-snapshots the baseline on its own, flag or not. On success, result.submittedAnnotation reports submitted text size (chars, estimatedTokens ~chars/4; heuristic, not LLM billing). result.quality.score is COMPLETENESS only (how many fields), not correctness or trust; result.quality.consistency reports filled fields that contradict graph facts (keyExports/env names absent from the module, declared-pure while the graph detects effects). Do not fill a field you cannot back from inspect_node or source — an empty field beats a fabricated one; inspect the node in the same contextSessionId before writing (the harness checks that provenance over annotationsWritten).