Add phase-memory roadmap workplans

workplans/PMEM-WP-0002-local-runtime-facade-and-cli.md

@@ -0,0 +1,202 @@
+---
+id: PMEM-WP-0002
+type: workplan
+title: "Local Runtime Facade And CLI"
+domain: markitect
+repo: phase-memory
+status: proposed
+owner: phase-memory
+topic_slug: local-runtime
+planning_priority: P1
+planning_order: 20
+related_workplans:
+  - PMEM-WP-0001
+created: "2026-05-18"
+updated: "2026-05-18"
+state_hub_workstream_id: "83dcb429-688d-473d-9973-63f6ac2acd5b"
+---
+
+# PMEM-WP-0002: Local Runtime Facade And CLI
+
+## Goal
+
+Turn the completed planning foundation into a usable local runtime entrypoint.
+
+The runtime should combine contract ingress, profile execution planning,
+lifecycle planning, activation planning, local adapters, policy checks, and
+audit recording behind one deterministic application surface. The first CLI
+should make the package useful from a repository checkout without requiring a
+service, external graph store, vector database, LLM, or enterprise policy
+system.
+
+## Current Evidence
+
+PMEM-WP-0001 already provides:
+
+- Markitect-compatible profile and graph ingress.
+- Profile execution plans.
+- Dry-run lifecycle actions.
+- Activation selection handoff.
+- Runtime port protocols.
+- In-memory adapters and deterministic tests.
+
+The missing layer is orchestration. Callers still need to manually wire modules
+together and there is no command-line path for inspecting plans.
+
+## Non-Goals
+
+- Do not introduce durable writes as a default behavior.
+- Do not make Markitect a hard runtime dependency.
+- Do not start a long-lived HTTP service in this workplan.
+- Do not add live LLM, vector, or graph database dependencies.
+
+## T01 - Add a local runtime facade
+
+```task
+id: PMEM-WP-0002-T01
+status: todo
+priority: high
+state_hub_task_id: "456557a9-3ac3-483b-bbdd-5591224894b9"
+```
+
+Add a `PhaseMemoryRuntime` application service that wires together:
+
+- contract ingress
+- profile execution planning
+- lifecycle planning
+- activation planning
+- memory graph store
+- event log
+- context package compiler port
+- policy gateway
+- audit sink
+
+Output: a small public runtime API that keeps existing pure planner functions
+usable, but gives integrations one obvious local entrypoint.
+
+## T02 - Define runtime input and output envelopes
+
+```task
+id: PMEM-WP-0002-T02
+status: todo
+priority: high
+state_hub_task_id: "b04054cb-d743-4fcd-9b37-2685d1f9c00d"
+```
+
+Define stable dictionary envelopes for local runtime operations:
+
+- profile import result
+- graph import result
+- profile plan result
+- lifecycle plan result
+- activation plan result
+- package compilation request and response
+- audit receipt
+
+Output: deterministic JSON-serializable envelopes with diagnostics, operation
+ids, dry-run flags, and source contract references.
+
+## T03 - Implement profile planning CLI
+
+```task
+id: PMEM-WP-0002-T03
+status: todo
+priority: high
+state_hub_task_id: "8463924e-a6ce-43f1-b7fc-544a2aa7fd5f"
+```
+
+Add a dependency-light CLI entrypoint for:
+
+```bash
+phase-memory profile plan tests/fixtures/memory-profile.json
+```
+
+The command should emit JSON by default and support a concise human-readable
+summary mode.
+
+Output: CLI command, tests around success and diagnostics, and README usage.
+
+## T04 - Implement graph lifecycle CLI
+
+```task
+id: PMEM-WP-0002-T04
+status: todo
+priority: high
+state_hub_task_id: "ab818835-5ef3-4a43-adf2-444ab712ead9"
+```
+
+Add a command for lifecycle planning over a graph fixture:
+
+```bash
+phase-memory graph lifecycle tests/fixtures/memory-graph.json --stale-after-days 7 --delete-after-days 30
+```
+
+The command should emit dry-run lifecycle actions only. It must not mutate
+input files or local stores unless a later workplan adds explicit apply
+behavior.
+
+Output: lifecycle command and fixture tests for stale, delete-requested,
+refresh, and compaction proposals.
+
+## T05 - Implement activation CLI
+
+```task
+id: PMEM-WP-0002-T05
+status: todo
+priority: medium
+state_hub_task_id: "9c8e8511-f00a-4685-91b5-a52c93d8461d"
+```
+
+Add a command for Markitect-compatible activation selection:
+
+```bash
+phase-memory graph activate tests/fixtures/memory-graph.json --max-items 3 --max-tokens 60
+```
+
+The command should emit the selection envelope and explain omitted nodes.
+
+Output: activation command, deterministic output tests, and README usage.
+
+## T06 - Add snapshot tests for CLI and runtime envelopes
+
+```task
+id: PMEM-WP-0002-T06
+status: todo
+priority: medium
+state_hub_task_id: "a005aa31-053e-4b51-b3ea-3bebf24ac833"
+```
+
+Add small JSON snapshot fixtures for the main runtime outputs. Snapshot tests
+should protect the public shape of the local interface without freezing
+internal dataclass implementation details.
+
+Output: stable examples for downstream repos and future compatibility checks.
+
+## T07 - Update documentation for local usage
+
+```task
+id: PMEM-WP-0002-T07
+status: todo
+priority: medium
+state_hub_task_id: "f6c6c6b2-141a-44da-a3d5-dbef95559049"
+```
+
+Update `README.md` and architecture docs with:
+
+- runtime facade role
+- CLI quick start
+- dry-run guarantees
+- example plan outputs
+- how adjacent repos should call the local API
+
+Output: a contributor can run the package and inspect a memory plan in under
+five minutes.
+
+## Acceptance Criteria
+
+- `python3 -m pytest` passes.
+- The package exposes a console script named `phase-memory`.
+- Profile planning, graph lifecycle planning, and activation planning work from
+  the CLI against existing fixtures.
+- Runtime outputs are deterministic and JSON-serializable.
+- No default path mutates durable memory stores.