Your codebase changes daily. Your context shouldn’t decay with it.
Stale docs mislead the next engineer — and every agent, on every run. Surface anchors prose to the code it describes and fails the build when that logic changes, so the context everyone reasons from stays true.
no model · no network · no API key in the core
A test asserts behavior. Surface asserts prose.
Your tests are green. Your docs can still be stale. The two drift apart the moment someone updates one and forgets the other — and the code that works fine but no longer matches its description is the cell nothing else catches.
Surface owns that cell.
catches this code broken tests catch it both might fire
Anchor a sentence to the code it’s about. The gate seals its logic.
# auth/_hub.md
anchors:
- claim: refresh rotation is single-use;
reuse triggers global logout
at: src/auth/refresh.ts > rotateRefreshToken
hash: 9b1c33a$ surf check
DIVERGED hubs/auth.md
at src/auth/refresh.ts > rotateRefreshToken
stored 9b1c33ade8f1 -> now 4d5e6f2a0b7c
magnitude: Small
surf check: 1 divergence(s).- 01 Locate. tree-sitter resolves the at: path to an exact node span.
- 02 Canonicalize. the syntax tree, not the text — comments & renames drop out.
- 03 Hash. SHA-256, truncated. A list anchor is stale if any site changes.
- 04 Compare. against the sealed hash. Equal passes; different blocks the merge.
- - const userId = user.id+ const uid = user.id
rename a local · stays silent
- - sum(a,b,c)+ sum(a, b, c)
reformat · stays silent
- - return base + tax+ return base + tax // incl. tax
add a comment · stays silent
- - return base + tax+ return base - tax
flip + to − · fires
- - if (i < limit)+ if (i <= limit)
< to <= · fires
- - await save(user)+ save(user)
drop an await · fires
A tamper-evident seal on the logic of exactly the code your docs claim to describe.
complexity × velocity × (humans + agents)
Honestly? Maybe not. A small, slow, simple codebase doesn’t need this — two well-kept markdown files beat the whole apparatus. Use Surface where rebuilding the mental model from source is expensive and the code moves fast enough to drift.
One multiplier pushes it toward yes: agents. A human onboards once and amortizes over months. An agent re-onboards every session and amortizes nothing — so accurate context isn’t a nicety, it’s the performance budget.