heddle context

Context is how Heddle stores the *why* alongside the code. A context annotation targets a file (--path src/auth/mod.rs) or a state (--state hd-d01a8b4e7m9k), and a scope within that target: file (the default), symbol:, or lines:-.

Three kinds carry distinct intent: rationale (default: why this approach), invariant (must always hold), constraint (external requirement). The kind drives the visual register in tooling. Pass --kind invariant etc.; the kinds are always the full words rationale / invariant / constraint. There are no rat / inv / con short forms.

Annotations have logical IDs that survive revision: heddle context edit adds a revision; heddle context supersede replaces with a new logical annotation; heddle context history walks the revision chain. heddle context check and heddle context audit surface stale and superseded notes; heddle context suggest recommends symbols that would benefit from one.

Examples

Attach a rationale to a symbol

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)

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

See also

• heddle thread
• heddle discuss