Annotation that survives refactor

Why wikis fall behind

The reason your team's architecture wiki is six months stale isn't laziness. It's that the wiki has no relationship to the code. Nothing notifies the wiki when a function is renamed, nothing fails CI when a doc describes a flow that no longer exists, nothing tells the next reader that this page is talking about code that's since been split across three modules.

Commit messages are slightly better — they're at least versioned with the code — but they're write-once and detached from the symbol they describe. A reviewer reading the diff sees the message; a reader returning to the same code months later does not, unless they go run git log on the right blame line.

Heddle's contexts are neither. They're first-class objects attached to specific symbols, files, or line ranges. They travel with the code.

What "anchored" means

A context note is created with a target — a symbol name (fn authorize), a file path (src/auth/mod.rs), or a path:line pair (src/auth/mod.rs:42). The note is stored as an object in the Heddle store with a pointer to the target.

Attach a rationale to a function

bash$ heddle context set --path src/auth/mod.rs --scope symbol:authorize -m "scope check happens before role check by design"Annotated fn authorize (1 active annotation)

On every subsequent capture, the context system re-resolves its target. If the function moved to a different file, the context's stored path updates. If the function was renamed via a refactor tool, the context re-anchors to the new name. If the function was split into two, the context asks for confirmation: stay on the original, or split into two contexts? (Defaults to stay-on-original; a one-line interactive prompt during capture.)

The three kinds

Context kind drives visual register and search semantics. Heddle ships three:

• inv · invariant — something that must always hold. "Capability chain must be append-only." Surfaces in red when violated.
• rat · rationale — why this approach. "Scope check before role check, by design." The most common kind.
• con · constraint — external requirement. "SOC2 requires this audit field to be append-only." Often references an external standard or ticket.

Cross-agent handoff

The killer feature: when a new agent opens a file for the first time in a session, it gets the active contexts automatically. The IDE integration surfaces them inline. The CLI prints them via heddle context get. The next agent doesn't have to read a wiki, doesn't have to scroll a chat history, doesn't have to ask the human "why is this here?" — the reasoning is right next to the code.

Read what's active on a file

bash$ heddle context get --path src/auth/mod.rsfile src/auth/mod.rs--- [rationale] ann-9a2f (active) ---by: anan@heddle.shscope check happens before role check by design--- [invariant] ann-9b04 (active) ---by: anan@heddle.shcapability chain must be append-only

How re-anchoring works

During capture, the context system runs a re-anchor pass over every context whose target intersects with changed files. For symbol targets, it parses the AST and looks for the symbol by name (with a structural-similarity fallback when the name changed). For path targets, it follows file moves. For path:line targets, it adjusts the line number based on the diff.

Re-anchoring is not magic — it's heuristic. When it can't resolve confidently, the context is flagged for human confirmation before the capture completes. The honest failure mode (ask before guessing) is the point.

Compared to Git

The commands

• heddle context — set, get, list, edit, supersede, remove.
• heddle discuss — multi-author conversations on the same symbol targets.

Next: attribution and signing for how the author of every context is recorded, or git overlay for how contexts survive a Git-side refactor that goes through the bridge.