phase-memory/workplans/PMEM-MATURITY-SCORECARD.md

id, type, title, domain, repo, status, owner, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	created	updated	state_hub_workstream_id
PMEM-MATURITY-SCORECARD	scorecard	Phase Memory Maturity Scorecard	markitect	phase-memory	active	phase-memory	2026-05-18	2026-05-18	e82b1c2d-0c5e-47d3-9627-f85e7173dcbe

Phase Memory Maturity Scorecard

Purpose

Track progress from the current foundation toward the full INTENT.md vision: a profile-driven, phase-aware memory infrastructure layer for agentic systems.

This scorecard is intentionally practical. It scores what exists in this repo, not what adjacent repositories may already provide.

Scoring Scale

Score	Meaning
0	Not started.
1	Intent or docs exist, but no executable behavior.
2	Deterministic local library slice exists with tests.
3	Usable local runtime or CLI exists with stable envelopes.
4	Integration-ready with policy, persistence, interop, and evaluation coverage.
5	Service-ready and operationally mature with adapter conformance and diagnostics.

Milestone Ladder

Milestone	Target State	Primary Workplans
M1	Foundation complete: domain model, contract ingress, dry-run planners, ports, tests.	PMEM-WP-0001
M2	Usable local runtime: facade, CLI, stable JSON envelopes, local file persistence.	PMEM-WP-0002, PMEM-WP-0003
M3	Governed interop runtime: review gates, audit, policy-aware activation, Markitect package bridge.	PMEM-WP-0004, PMEM-WP-0005
M4	Evaluated activation memory: graph neighborhoods, event paths, ranking, quality metrics.	PMEM-WP-0006
M5	Service-ready adapter layer: service contracts, config, health, external adapter conformance.	PMEM-WP-0007

Current Baseline - 2026-05-18

Overall maturity: 4.5 / 5

The repo has crossed from intent-only into a working deterministic library foundation, a usable local runtime facade, a CLI, a file-backed local workspace, first-slice policy/review/audit gates, a concrete Markitect package bridge, deterministic activation quality helpers, and first-slice service readiness contracts with profile-driven runtime adapter resolution, profile-derived lifecycle rules, and fake external adapter packs.

Dimension	Current	Target	Evidence	Needed Next
Intent and boundaries	4.0	5.0	INTENT.md, SCOPE.md, README.md, architecture doc, PMEM-WP-0001 closure	Keep boundaries current as runtime behavior expands.
Package foundation	4.0	4.0	Python package, exports, runtime facade, CLI entrypoint, config, service contracts, dependency-light tests	Maintain public API compatibility as adapters expand.
Profile contract ingress	3.2	4.0	Markitect-compatible profile loading, diagnostics, runtime envelopes, profile-derived runtime config, local adapter alias normalization	Add richer compatibility coverage.
Graph/event contract ingress	3.7	4.0	Graph loading, edge endpoint diagnostics, event model, JSONL event log, export, repair diagnostics, service import/export contracts, fake external graph/event adapters	Add broader external adapter fixtures.
Phase domain model	3.4	4.0	Phases, memory kinds, lifecycle states, actions, explicit path records, profile-derived transition rules	Add migration semantics.
Profile execution planning	4.0	4.0	Adapter plan, capabilities, policy gates, fallback behavior, CLI output, snapshot fixture, service contract, config-driven local and fake external adapter resolution	Maintain compatibility as live adapters land.
Lifecycle planning	3.6	4.0	Transition, retention, refresh, compaction dry-run plans, profile-driven lifecycle rules, review-gated local apply	Add service apply contracts and migration semantics.
Activation planning	3.8	5.0	Budgeted selection, Markitect-compatible selection output, package request envelope, graph neighborhoods, event paths, ranking, metadata preservation, metrics	Add semantic-index adapters and broader evaluation corpora.
Local persistence	3.0	4.0	Versioned local workspace, file-backed graph store, JSONL event log, JSONL audit sink	Add migration/repair utilities and stronger durability semantics.
Policy and audit	3.5	5.0	Operation points, policy gateway checks, audit schema, review records, redaction, activation denials, fake external policy/audit adapters	Add richer audit retention behavior and live policy adapters.
Observability and diagnostics	3.8	4.0	Planner diagnostics, runtime diagnostics, event log corruption checks, repair diagnostics, policy denial diagnostics, health envelopes, adapter status, fake telemetry audit sink	Add production telemetry adapters.
Markitect interop	3.7	4.0	Compatible contract ingress, optional validation boundary, enriched selection metadata, package request/response envelopes, fake Markitect package compiler	Add live optional Markitect compiler adapter when available.
Kontextual/Infospace interop	3.0	4.0	Boundaries documented, small derived fixtures, activation quality report fixture, Kontextual delegation envelope, fake Kontextual runtime registry	Add live delegation adapters and broader Infospace reports.
Testing and evaluation	4.0	4.0	60 deterministic tests over planners, adapters, runtime envelopes, CLI, snapshots, file-store round trips, lifecycle rules, apply denial, review records, audit schema, policy redaction, Markitect bridge fixtures, retrieval, activation metrics, service contracts, config, health, conformance, adapter resolution, and fake external packs	Add broader evaluation corpora.
Service readiness	4.0	4.0	Runtime ports, service contracts, config model, profile-derived adapter resolution, health checks, local service runner lifecycle support, adapter conformance helpers, fake external adapter pack	Add framework-specific bindings and production adapter packs.
Developer experience	3.7	4.0	README quick start, package map, runtime facade docs, CLI examples, local persistence guide, service adapter resolution docs, lifecycle rule docs, external adapter pack docs	Add troubleshooting and richer examples.

Progress Update - PMEM-WP-0002

Closed on 2026-05-18:

• Added PhaseMemoryRuntime as the local application facade.
• Added JSON runtime envelopes with policy decisions, audit receipts, diagnostics, dry-run flags, operation ids, and source references.
• Added phase-memory console script metadata and CLI commands for profile planning, graph lifecycle planning, and graph activation planning.
• Added snapshot fixtures for profile-plan and activation-plan envelope shapes.
• Updated local usage and architecture docs.

Remaining maturity blockers:

• File-backed persistence and event path runtime.
• Review-gated apply behavior.
• Policy enforcement and redaction beyond the allow-all local adapter.
• Stronger Markitect compiler/validation bridge.
• Activation quality evaluation.
• Service contracts and external adapter conformance.

Progress Update - PMEM-WP-0003

Closed on 2026-05-18:

• Added a versioned local file-backed workspace layout.
• Added deterministic file-backed profile, node, edge, and path storage.
• Added append-only JSONL event and audit adapters.
• Added graph export, event replay, and repair diagnostics.
• Added explicit conversational path records and path-event helpers.
• Added review-gated lifecycle apply behavior for local stores.
• Added store import/export/repair CLI coverage and local persistence docs.

Remaining maturity blockers:

• Policy operation vocabulary and review records.
• Activation-time policy checks and redaction.
• Stable audit event schema.
• Markitect compiler/validation bridge.
• Activation quality metrics.
• Service readiness and external adapter conformance.

Progress Update - PMEM-WP-0006

Closed on 2026-05-18:

• Added deterministic graph-neighborhood retrieval.
• Added event-path selection from structured memory paths.
• Added candidate scoring and explanation reasons.
• Added pluggable token estimator protocol with deterministic word-count default.
• Added activation quality report metrics and fixture.
• Documented retrieval and evaluation behavior.

Remaining maturity blockers:

• Service API contracts.
• Runtime configuration model.
• Health diagnostics.
• External adapter conformance tests.
• Kontextual delegation adapter design.

Progress Update - PMEM-WP-0007

Closed on 2026-05-18:

• Added service operation contract catalog.
• Added runtime configuration model.
• Added health reports and adapter status diagnostics.
• Added local service runner shape without framework dependency.
• Added adapter conformance helpers.
• Added Kontextual delegation envelope.
• Documented deployment modes.

Remaining maturity blockers:

• Live external adapter implementations.
• Broader evaluation corpora.
• Optional framework-specific service bindings.
• Production telemetry and audit retention integrations.

Progress Update - PMEM-WP-0008

Closed on 2026-05-18:

• Added RuntimeConfig.from_profile(...) for Markitect-compatible profile mappings and ProfileIntent inputs.
• Added adapter alias normalization for local graph stores, event logs, audit sinks, package compilers, semantic indexes, and runtime registries.
• Added RuntimeAdapterBundle and resolve_runtime_adapters(...).
• Updated runtime_from_config(...) and LocalServiceRunner to use resolved adapters.
• Added diagnostics that block unresolved external adapters.
• Added tests and service readiness documentation for the resolver path.

Remaining maturity blockers:

• Live external adapter implementations.
• Broader evaluation corpora.
• Optional framework-specific service bindings.
• Production telemetry and audit retention integrations.

Progress Update - PMEM-WP-0009

Closed on 2026-05-18:

• Added LifecycleRuleConfig for profile-derived retention, transition, refresh, and compaction settings.
• Added profile-derived retention planning.
• Added review-gated phase transition rules from profile metadata.
• Added plan_lifecycle_from_profile(...).
• Added PhaseMemoryRuntime.plan_lifecycle_with_profile(...).
• Added CLI graph lifecycle --profile.
• Added lifecycle rule docs, README examples, and regression tests.

Remaining maturity blockers:

• Migration semantics for profile/rule changes over durable stores.
• Service apply contracts.
• Live external adapter implementations.
• Broader evaluation corpora.

Progress Update - PMEM-WP-0010

Closed on 2026-05-18:

• Added ExternalAdapterPack.
• Added deterministic fake external graph and event adapters.
• Added fake Markitect package compiler.
• Added fake external policy gateway.
• Added fake telemetry audit sink with retention metadata.
• Added fake semantic index and fake Kontextual runtime registry.
• Added fake_external_adapter_pack() and fake_external_runtime_config().
• Added conformance tests and all-external runtime wiring tests.
• Added external adapter pack documentation and README links.

Remaining maturity blockers:

• Live external adapter implementations.
• Broader evaluation corpora.
• Framework-specific service bindings.
• Production audit retention and telemetry integrations.

Progress Update - PMEM-WP-0004

Closed on 2026-05-18:

• Added canonical memory operation policy points.
• Added review records and deterministic review ids.
• Added stable audit event schema phase_memory.audit.event.v1.
• Added review-record enforcement for lifecycle apply.
• Added activation policy checks for labels, denied labels, trust zones, secrets, reauthorization, and freshness.
• Added deterministic redaction records and diagnostics for denied activation items.
• Added policy/audit documentation.

Remaining maturity blockers:

• Optional Markitect validation and package compiler bridge.
• Activation ranking and evaluation metrics.
• Service contracts, health diagnostics, and external adapter conformance.

Progress Update - PMEM-WP-0005

Closed on 2026-05-18:

• Added Markitect package request and response envelopes.
• Added local and optional Markitect validation adapter boundary.
• Preserved selected item source spans, provenance, confidence, freshness, namespace, policy metadata, and selection reasons through activation.
• Added compatibility fixtures and tests for invalid contracts, activation package requests, and opaque package responses.
• Documented the Markitect boundary.

Remaining maturity blockers:

• Graph-neighborhood retrieval and event-path activation.
• Ranking signals and token accounting.
• Activation quality metrics and evaluation fixtures.
• Service readiness and external adapter conformance.

Score Movement Rules

A dimension should move up only when executable behavior and tests exist. Documentation alone can justify score 1, but not score 2 or higher.

Suggested gates:

• Move to 3 when the behavior is usable through the runtime facade or CLI.
• Move to 4 when the behavior has policy, persistence, interop, and regression coverage appropriate to its risk.
• Move to 5 when the behavior has service contracts, health diagnostics, adapter conformance tests, and operational documentation.

Workplan Dependency Map

flowchart TD
  WP1["PMEM-WP-0001\nArchitecture and foundation"]
  WP2["PMEM-WP-0002\nLocal runtime facade and CLI"]
  WP3["PMEM-WP-0003\nFile-backed stores and event paths"]
  WP4["PMEM-WP-0004\nPolicy, audit, review gates"]
  WP5["PMEM-WP-0005\nMarkitect package bridge"]
  WP6["PMEM-WP-0006\nRetrieval and activation quality"]
  WP7["PMEM-WP-0007\nService readiness and adapters"]
  WP8["PMEM-WP-0008\nProfile-driven runtime config"]
  WP9["PMEM-WP-0009\nProfile-driven lifecycle rules"]
  WP10["PMEM-WP-0010\nFake external adapter packs"]

  WP1 --> WP2
  WP2 --> WP3
  WP2 --> WP4
  WP2 --> WP5
  WP3 --> WP4
  WP5 --> WP6
  WP4 --> WP6
  WP3 --> WP7
  WP4 --> WP7
  WP5 --> WP7
  WP6 --> WP7
  WP3 --> WP8
  WP5 --> WP8
  WP7 --> WP8
  WP2 --> WP9
  WP4 --> WP9
  WP8 --> WP9
  WP7 --> WP10
  WP8 --> WP10

Next Tracking Cadence

Update this scorecard at the end of each workplan closure review:

• record completed task ids
• update dimension scores only when tests and docs support the change
• add residual risks
• list score regressions if behavior was removed or narrowed
• link new workplans if the intent expands