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 src/auth/mod.rs (1 active annotation)

Heddle records the source it was looking at when you wrote the note. Later, on demand, heddle context check re-reads the target and compares: if the file or symbol is untouched the note is Fresh; if the scoped source changed it's SourceChanged; if the file is gone it's FileMissing; if the symbol no longer resolves by name it's SymbolMissing. The note isn't silently rewritten; you're told it needs a look.

The three kinds

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

• invariant: something that must always hold. "Capability chain must be append-only." Surfaces in red when violated.
• rationale: why this approach. "Scope check before role check, by design." The most common kind.
• 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] hd-9a2f7k3m1qbt8x4re0vyc6hzdn (active) ---by: anan@heddle.shscope check happens before role check by design--- [invariant] hd-9b04tj6w2zfn5q8mxe1ry7hckp (active) ---by: anan@heddle.shcapability chain must be append-only

How staleness checking works

When you write a note, Heddle stores a hash of the source at the annotated scope: the whole file, the chosen line range, or the bytes of the named symbol. heddle context check re-reads that scope and compares hashes. For a symbol target it resolves the symbol by name in the current file; if the bytes still match, the note is Fresh; if they changed, SourceChanged; if the symbol's name no longer resolves, SymbolMissing; if the file is gone, FileMissing.

This is detection, not magic re-anchoring. Heddle does not silently follow a rename or rewrite the stored target during capture; within-file rename tracking isn't implemented for contexts. It tells you the note went stale and leaves the decision to you. The honest failure mode, flag and don't guess, is the point. (Anchors that do travel across renames and cross-file moves are heddle discuss, below.)

Compared to Git

The commands

• heddle context: set, get, list, edit, supersede, rm, check, audit.
• 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.