v0.5.0 — typed annotations

Typed name/value annotations on graph entities — assumptions, questions, notes, observations, comments, and custom types — with the semantics services need to treat them differently.

Typed annotations

• One type field on each annotation (no enum): fixed types note/observation/comment (informational), assumption/question (advisory), community (system-derived), plus arbitrary custom types stored + queried identically.
• advisory is computed from the type — assumption/question surface as advisory: true so an agent never reads them as fact (R7). Confidence keeps its own meaning.
• Stored on the existing annotations table (one additive column); idempotent migration; pre-0.5 untyped annotations read back as note. Multiple per entity, stable SymbolId keying.

Surfaces

• CLI: annotate --type <t> --key K --value V; annotations <name> [--type <t>] --json; annotations + annotation_summary {count, by_type, has_advisory} in nodes --json and source --json.
• clusters --annotate writes each symbol's community as a system-authored community annotation (opt-in; no mutation without the flag).
• MCP: RetrieveEntity returns annotations + annotation_summary + per-item advisory, capped at 20/entity (advisory-class first; count is the true total).

The known types are service conventions, never a storage match — a new framework or custom type is data, not a core change.

Gates

cargo build --workspace (0 warnings) · cargo test --workspace (44 suites, 0 failures, GraphStore conformance covers typed annotations on both stores) · cargo clippy --workspace --all-targets -- -D warnings · cargo fmt --all --check — all green at the tag.

Consumer contract: docs/recon/annotation-consumer-spec.md.

🤖 Generated with Claude Code