generated from coulomb/repo-seed
249 lines
6.9 KiB
Markdown
249 lines
6.9 KiB
Markdown
---
|
|
id: PMEM-WP-0002
|
|
type: workplan
|
|
title: "Local Runtime Facade And CLI"
|
|
domain: markitect
|
|
repo: phase-memory
|
|
status: finished
|
|
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.
|
|
|
|
## Implementation Update - 2026-05-18
|
|
|
|
The local runtime and CLI slice is complete.
|
|
|
|
Implemented outputs:
|
|
|
|
- `src/phase_memory/runtime.py` defines `PhaseMemoryRuntime` with stable
|
|
runtime envelopes for profile import, graph import, profile planning,
|
|
lifecycle planning, activation planning, and package compilation handoff.
|
|
- `src/phase_memory/cli.py` adds dependency-light `argparse` commands for
|
|
profile planning, graph lifecycle planning, and graph activation planning.
|
|
- `pyproject.toml` exposes the installed console script as `phase-memory`.
|
|
- Runtime and CLI tests cover JSON envelopes, dry-run lifecycle actions,
|
|
package requests, summary output, and console-script metadata.
|
|
- Snapshot fixtures pin the public profile-plan and activation-plan envelope
|
|
shape without freezing internal dataclass details.
|
|
- `README.md` and `docs/architecture.md` document local usage, the facade
|
|
boundary, dry-run guarantees, and adjacent-repo expectations.
|
|
|
|
Validation:
|
|
|
|
- `python3 -m pytest` -> 23 passed.
|
|
|
|
## T01 - Add a local runtime facade
|
|
|
|
```task
|
|
id: PMEM-WP-0002-T01
|
|
status: done
|
|
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: done
|
|
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: done
|
|
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: done
|
|
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: done
|
|
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: done
|
|
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: done
|
|
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.
|
|
|
|
## Closure Review - 2026-05-18
|
|
|
|
**Outcome:** All tasks completed.
|
|
|
|
### Completed
|
|
|
|
- PMEM-WP-0002-T01 - Add a local runtime facade
|
|
- PMEM-WP-0002-T02 - Define runtime input and output envelopes
|
|
- PMEM-WP-0002-T03 - Implement profile planning CLI
|
|
- PMEM-WP-0002-T04 - Implement graph lifecycle CLI
|
|
- PMEM-WP-0002-T05 - Implement activation CLI
|
|
- PMEM-WP-0002-T06 - Add snapshot tests for CLI and runtime envelopes
|
|
- PMEM-WP-0002-T07 - Update documentation for local usage
|
|
|
|
### Cancelled
|
|
|
|
None.
|
|
|
|
### Carried Forward
|
|
|
|
Local persistence, review-gated apply behavior, richer policy enforcement, and
|
|
external adapter readiness remain in PMEM-WP-0003 through PMEM-WP-0007.
|