Files

tegwick 8089a7c8fa Implement local runtime persistence and policy gates

2026-05-18 18:21:27 +02:00

6.9 KiB

Raw Blame History

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, related_workplans, created, updated, state_hub_workstream_id

type

title

domain

repo

status

owner

topic_slug

planning_priority

planning_order

related_workplans

created

updated

state_hub_workstream_id

PMEM-WP-0002

workplan

Local Runtime Facade And CLI

markitect

phase-memory

finished

phase-memory

local-runtime

PMEM-WP-0001

2026-05-18

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

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

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

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:

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

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:

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

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:

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

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

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.

6.9 KiB Raw Blame History