Implement local runtime persistence and policy gates

README.md

@@ -35,6 +35,43 @@ python3 -m pytest
 
 The default test suite uses only deterministic local fixtures.
 
+From a checkout, run the CLI through the local source tree:
+
+```bash
+PYTHONPATH=src python3 -m phase_memory.cli profile plan tests/fixtures/memory-profile.json
+PYTHONPATH=src python3 -m phase_memory.cli graph lifecycle tests/fixtures/memory-graph.json --stale-after-days 7 --delete-after-days 30
+PYTHONPATH=src python3 -m phase_memory.cli graph activate tests/fixtures/memory-graph.json --max-items 3 --max-tokens 60
+PYTHONPATH=src python3 -m phase_memory.cli store import --store .phase-memory-local --profile tests/fixtures/memory-profile.json --graph tests/fixtures/memory-graph.json
+```
+
+When installed, the package exposes the same commands as `phase-memory`.
+Commands emit JSON runtime envelopes by default and accept `--format summary`
+for a concise human-readable view. All current commands are dry-run planning
+operations; they do not mutate durable memory stores.
+
+## Local Runtime
+
+`PhaseMemoryRuntime` is the dependency-light application facade for local
+integrations. It coordinates contract ingress, profile planning, lifecycle
+planning, activation planning, the context-package compiler port, policy
+checks, and audit recording.
+
+Example:
+
+```python
+import json
+from phase_memory import PhaseMemoryRuntime
+
+runtime = PhaseMemoryRuntime()
+profile = json.load(open("tests/fixtures/memory-profile.json", encoding="utf-8"))
+envelope = runtime.plan_profile(profile, source_ref="tests/fixtures/memory-profile.json")
+```
+
+Runtime outputs use stable JSON-serializable envelopes with operation ids,
+diagnostics, policy decisions, audit receipts, dry-run flags, and source
+references. Activation planning also includes a Markitect-compatible selection
+and a package compilation request for the `ContextPackageCompiler` boundary.
+
 ## Package Map
 
 - `phase_memory.models`: domain records, phases, lifecycle states, diagnostics,
@@ -45,6 +82,10 @@ The default test suite uses only deterministic local fixtures.
 - `phase_memory.activation`: Markitect-compatible activation selection planning.
 - `phase_memory.ports`: runtime port protocols.
 - `phase_memory.adapters`: deterministic in-memory test adapters.
+- `phase_memory.runtime`: local runtime facade and stable operation envelopes.
+- `phase_memory.cli`: dependency-light command-line interface.
 
 See [docs/architecture.md](docs/architecture.md) for the first architecture
-sketch and [SCOPE.md](SCOPE.md) for repository boundaries.
+sketch, [docs/local-persistence.md](docs/local-persistence.md) for the local
+file-backed adapter, [docs/policy-audit.md](docs/policy-audit.md) for local
+policy and review gates, and [SCOPE.md](SCOPE.md) for repository boundaries.