agentmako 0.5.0: a live map that only claims what it can prove

A context engine has one job: when an agent asks about your repo, the answer has to be true. Not "usually true." Not "true when the index is warm." True — or clearly labeled as uncertain.

That bar is higher for agents than for humans. A human sees "7 import cycles detected" and squints: really? those look like type imports. An agent doesn't squint. It treats the finding as ground truth, plans around it, maybe "fixes" code that was never broken. Every false positive a context layer emits gets amplified by whatever the agent does next.

agentmako 0.5.0 is a precision overhaul. We hunted false positives across every surface that makes a claim — imports, cycles, staleness, findings, coverage gates, pre-commit checks — and fixed what we found. Then we pointed the tool at a 2,350-file production Next.js/Supabase app and let it embarrass us some more. This post is the tour.

The false positives we killed

"unresolved" imports that were never broken

Ask the old imports_deps about any file and it would report react, zod, and node:path as unresolved imports — because the import graph resolves against indexed files only, and node_modules isn't indexed. Every file in your repo looked broken. Now only relative and re-export edges that should have resolved to indexable source count as unresolved. Asset imports (./logo.svg, ./styles.module.scss) are excluded too.

Import "cycles" erased at compile time

On the production test repo, imports_cycles reported 7 cycles. We checked every one: all seven were closed by an import type edge — erased at compile time, no runtime cycle, nothing to "break before refactoring." Type-only edges are now excluded from cycle detection. The repo correctly reports zero.

Staleness by wall clock

The old freshness model marked things stale for reasons that had nothing to do with your code changing: an mtime bump from git checkout, a project-wide revision counter advanced by a README edit, a 30-minute cache TTL expiring while you ate lunch. Now staleness is change-based: content hashes gate every mtime comparison, revision drift only counts change sets that overlap what a diagnostic run actually analyzed, and an expired cache reports unknown ("expired without re-verification") — never stale. The inverse holds too: a file that really changed flips its sources stale even inside the cache window.

Findings that never healed

The worst one. Query-time diagnostics were persisted as active findings with no resolution path — fix the code, and the finding stayed active forever. Heuristic name-matching detectors also stamped their guesses confidence: "confirmed" at high severity. A live map that accretes unfixable noise trains agents (and humans) to ignore it.

Now: findings persist under one source, scoped to the files each pass analyzed, so re-analysis resolves anything it can no longer reproduce. Heuristic detectors say probable at medium severity — leads, not verdicts. Only verified evidence gets to say confirmed.

Prose treated as code

Context packets used to treat any backticked phrase as a code literal ("the authentication middleware flow" → "quoted literal was not found on the current filesystem") and any sentence containing the word "import" or "reference" as a dependency-graph request — then downgrade the whole packet for failing to cover anchors that never existed. Sentence-initial capitalized words ("Explain how…") became phantom symbol anchors that actively steered retrieval toward junk. All of that is fixed, and fixing it made retrieval more relevant, not just quieter.

What 0.5.0 adds

Method-level symbols

The symbol index used to stop at top-level declarations. Ask "where is getUserRoles defined and who calls it?" and the map only knew the class shell — the question dead-ended. Class methods are now first-class symbols, which means the whole chain lights up: the method resolves to a graph anchor, the import graph walks its callers, and one context_packet returns the definition plus caller edges, graph status connected.

Misses that self-correct

Agents guess paths and names — that's not going to change. What changed is what a miss returns:

No indexed match found for: lib/auth/index.ts
  — closest indexed matches: lib/auth/dal.ts, lib/auth/roles.ts,
    lib/auth/constants.ts, lib/auth/safe-path.ts

Same for symbols: ask for getUserRole when the repo defines getUserRoles and the packet says so. One step to recover instead of a dead end. (And when there's no good match, the suggestion stays silent — junk corrections are their own kind of false positive.)

Multi-writer protection

We caught this one live: a globally-installed older agentmako MCP server shared a project store with the newer workspace build — and its file watcher quietly re-indexed away the method symbols the new version had just written. Index runs are now stamped with a capability version; an older writer that would downgrade a newer store warns loudly before proceeding.

How we validated it

Two ways, because they catch different things. The synthetic suite (126 smoke tests) pins the semantics: a regression test that touches a file with identical bytes and asserts it does not go stale; one that fixes a flagged call site and asserts the finding resolves; one that lands a docs-only change set and asserts no diagnostic source flips.

Then dogfooding against a real production app, where every one of the ugliest bugs actually surfaced — the type-only cycles, the phantom "Explain" symbol anchor, the multi-writer downgrade. If you build tools for agents, point the tool at a repo it has never seen and ask it the questions an agent would ask. The synthetic suite never would have found these.

The trust contract

0.5.0 turns an implicit goal into an explicit rule for every surface that makes a claim:

• Every claim is evidence-backed — or it isn't made.
• Uncertainty is labeled as uncertainty — unknown and probable exist so stale and confirmed mean something.
• Misses come with corrections — a dead end is a bug.
• Findings heal — fixed code resolves its own findings.

That's the whole point of a live map. Not more context — context an agent can act on without second-guessing.

agentmako 0.5.0 is on npm: npm install -g agentmako. Full changelog on the GitHub release. If you're running an older global install alongside a newer one, update the global first — see the multi-writer note above.