Find the relevant code

A repository search can find matching text. It usually cannot tell the agent why a symbol exists, which decision selected its behavior, which specification it is meant to satisfy, or whether that rationale has gone stale.

Haft combines a code index with project records so the agent can move from a concern to likely files and symbols, then to related decisions, specifications, invariants, and notes.

The practical route

1. Start with the concern when you do not know the exact code identity.
2. Select the relevant file or symbol from the actual task, not from search rank alone.
3. Ask for context or impact on that exact target before a non-mechanical edit.
4. Open the exact decision or specification before relying on its claim.
5. Skip this route for an obvious mechanical edit when governance context cannot affect it.

haft graph explore --query "where is the index epoch published?" --json
haft graph explore --symbol PublishIndexEpoch --json

The same reads are available to the host agent:

haft_query(action="explore", query="where is the index epoch published?")
haft_query(action="code_context", file="internal/index/epoch.go")
haft_query(action="impact", symbol="PublishIndexEpoch")

What the result can and cannot say

The graph is an orientation surface. It can show a nearby decision or an invariant linked to a module. Nearness is not proof that the record is active or governing. The agent must still inspect its scope, status, limiting conditions, and exact links.

• An empty caller list does not prove that no dependency exists.
• An incomplete traversal is not a safety claim.
• A missing decision-to-file link does not prove the file is unconstrained.
• A broad file link may create noisy drift even when the relevant symbol did not change.

Freshness and concurrent agents

Code indexing is automatic. Several haft serve processes for the same project share published index epochs instead of repeating all parser work. If a request cannot establish freshness in time, Haft returns the last complete index as degraded, or says the index is unavailable. It should not turn an uncertain refresh into a confident empty result.

Advanced: result views and replay

Replay is tied to the same request and source snapshot. When either changes, Haft reports a mismatch instead of pretending the old trace proves the new result.

The trade-off

Code context becomes more useful as decisions and specifications carry precise code links. Creating and maintaining those links costs attention. Too few links produce gaps; links that are too broad produce noise. Haft exposes both problems instead of guessing certainty.

Related pages

• How project memory is organized
• How drift and evidence are read