repovine-workflow

repovine -- Navigation Workflow

The narrowing loop

Use the public tools as a flexible context loop. You can go deep, branch sideways, return up, or jump cross-layer.

1. Orient: search_context({ "query": "...", "match": "auto", "limit": 15 }) — default match is auto (AND then bounded OR). Use match: "and" when you need every token on one node; use match: "or" only when you intentionally want per-token union (may surface weak tokens like package/route). Filter with types and tune breadth with perTokenLimit. Before inspect_node, read result.matches.strategy (used, relaxedFrom, strongTokens, weakTokenOnlySuppressed), gaps, summary, confidence, and topResults[].matchedTokenCount — OR-relax hits omit emptyDiagnostic and are not strong anchors when relaxedFrom: "and" with low matchedTokenCount or confidence: "low".
2. Map: map_context({ "scope": "...", "view": "summary" })
3. Inspect: inspect_node({ "nodeId": "mod:pkg/path/module", "exportLimit": 20 })
4. Annotation constraints: when implementation will touch inspected nodes, apply this checkpoint before editing:

Annotations hint and constrain; they do not bound inspect scope. Locality: annotation on nodeId X is evidence about X only — not about other nodeIds, including mod: refs in integrationPoints, links, or drillDown. Absence: no annotation and no inspect_node on a nodeId means no conclusion about that node. Unchanged: stating a nodeId is unchanged, verified, or already-correct requires inspect_node on that nodeId in this session. Closure: before leaving related nodes unedited, follow links, navigation.*, and task-relevant integrationPoints mod: refs. Boundary or discovery tasks (find every surface exposing an affordance class) inspect the affordance-class consumers/importers before treating them unchanged — breadth is the task. Refactor or architecture tasks bound closure with one analyze_dependencies impact pass and need not inspect every ref. 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. Derived flags: a capability, permission, or feature flag is consumed at mount and render predicates and at importers, not only the hook that derives it — boundary tasks inspect those consumers. Weak context: while confidence is low, gaps is non-empty, or emptyDiagnostic is present, the scope is not complete.