Add Markitect bridge and activation quality

docs/markitect-interop.md

@@ -0,0 +1,93 @@
+# Markitect Interop
+
+`phase-memory` consumes and emits Markitect-compatible memory contracts while
+keeping ownership boundaries explicit.
+
+## Ownership
+
+Markitect owns:
+
+- markdown-facing memory profile syntax
+- memory graph contract vocabulary
+- memory selection validation
+- context-package internals
+- package compilation semantics
+
+`phase-memory` owns:
+
+- phase-aware runtime planning
+- lifecycle planning
+- activation planning
+- policy/audit/review checks around memory runtime behavior
+- adapter orchestration
+- package compile request handoff
+
+## Contract Inputs
+
+The dependency-light boundary accepts already-valid dictionaries for:
+
+- `markitect.memory.profile.v1`
+- `markitect.memory.graph.v1`
+- `markitect.memory.selection.v1`
+
+`LocalMarkitectValidator` uses local ingress diagnostics only. It checks
+schema ids, required ids, known first-slice memory kinds, and graph edge
+integrity. It does not claim to be the Markitect schema owner.
+
+`OptionalMarkitectValidator` can wrap a Markitect-owned validator object with
+methods such as `validate_memory_profile`, `validate_memory_graph`, and
+`validate_memory_selection`. If no delegate is configured, it falls back to the
+local boundary.
+
+## Package Request
+
+Activation planning emits a Markitect-compatible selection and a package
+request envelope:
+
+```text
+phase_memory.markitect.package_request.v1
+```
+
+The request includes:
+
+- selection id
+- graph id
+- profile id
+- selected node ids
+- selected event ids
+- budget metadata
+- policy metadata
+- selected item provenance metadata
+- compiler name
+- compiler diagnostics
+- original selection
+
+Selected item metadata preserves source spans, provenance, confidence,
+freshness, namespace, policy labels, and reason selected. This gives Markitect
+enough input to build inspectable packages without requiring phase-memory to
+understand package internals.
+
+## Package Response
+
+Package compiler responses are wrapped in:
+
+```text
+phase_memory.markitect.package_response.v1
+```
+
+The wrapper keeps the Markitect response opaque and extracts only a
+`package_ref` when present.
+
+## Fixture Catalog
+
+Compatibility fixtures live under `tests/fixtures/`:
+
+- `memory-profile.json` - valid Markitect-compatible profile
+- `memory-graph.json` - valid Markitect-compatible graph
+- `markitect-invalid-profile.json` - invalid profile diagnostics
+- `markitect-invalid-graph.json` - invalid graph diagnostics
+- `runtime-activation-plan-snapshot.json` - activation/package request shape
+- `markitect-package-response.json` - opaque package response fixture
+
+These fixtures are small and deterministic so adjacent repositories can reuse
+them as examples without installing Markitect.