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-d01a8b4e), 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 abbreviations rat/inv/con appear in the UI but the CLI takes full names.

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 fn authorize (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

Subcommands

• context set Attach a context annotation to a file, symbol, line range, or state
• context get Show context annotations for a file or state target
• context list List all active context targets
• context history Show full revision history for one logical annotation
• context edit Add a new revision to an existing logical annotation
• context supersede Create a replacement annotation and supersede an older one
• context rm Remove context annotations
• context check Check annotation staleness against current code
• context suggest Suggest low-noise targets that may benefit from context
• context audit Audit stale, superseded, and duplicate context