Add Markitect bridge and activation quality

docs/activation-quality.md

@@ -0,0 +1,52 @@
+# Activation Quality
+
+`phase-memory` activation can now be planned from deterministic graph
+neighborhoods and event paths without requiring embeddings, vector stores, or
+LLM ranking.
+
+## Graph Neighborhood Retrieval
+
+`retrieve_graph_neighborhood` expands from seed nodes across graph edges.
+
+Supported controls:
+
+- maximum hops
+- edge kind filters
+- `in`, `out`, or `both` direction
+- phase filters
+- memory kind filters
+
+Candidates receive deterministic scores based on explicit priority, graph
+distance, phase, lifecycle state, confidence, source-backed status, freshness,
+and policy allowance.
+
+## Event Path Activation
+
+`select_event_path` activates ordered event ids from a structured
+`MemoryPath`. Active paths are selected by default. Abandoned, merged, or
+compacted paths can be included explicitly when a caller wants to inspect
+inactive branches.
+
+## Token Estimation
+
+`TokenEstimator` is a protocol. The default implementation is
+`WordCountTokenEstimator`, which keeps tests deterministic and dependency-free.
+Provider-specific tokenizers can be supplied later without changing retrieval
+contracts.
+
+## Quality Report
+
+`activation_quality_report` emits local metrics suitable for later export to
+evaluation systems:
+
+- selected expected nodes
+- omitted required nodes
+- policy-denied required nodes
+- token budget utilization
+- stale item activation count
+- provenance coverage
+- source span coverage
+- explanation coverage
+
+The fixture `tests/fixtures/activation-quality-report.json` pins a small
+expected report for regression tests.