Add phase-memory roadmap workplans

2026-05-18 12:51:35 +02:00
parent 9d7b8d0df3
commit 3b83ab9c44
8 changed files with 1283 additions and 0 deletions
--- a/docs/pmem-wp-0002-outline.md
+++ b/docs/pmem-wp-0002-outline.md
@@ -1,5 +1,7 @@
 # Candidate PMEM-WP-0002 Outline
 Superseded by `workplans/PMEM-WP-0002-local-runtime-facade-and-cli.md`.
 Status: candidate outline
 ## Title
--- a/workplans/PMEM-MATURITY-SCORECARD.md
+++ b/workplans/PMEM-MATURITY-SCORECARD.md
@@ -0,0 +1,119 @@
 ---
 id: PMEM-MATURITY-SCORECARD
 type: scorecard
 title: "Phase Memory Maturity Scorecard"
 domain: markitect
 repo: phase-memory
 status: active
 owner: phase-memory
 created: "2026-05-18"
 updated: "2026-05-18"
 state_hub_workstream_id: "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: **2.0 / 5**
 The repo has crossed from intent-only into a working deterministic library
 foundation. It is not yet a usable local runtime because there is no facade,
 CLI, file-backed persistence, review-gated apply path, package compiler bridge,
 or service contract.
 | 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 | 2.5 | 4.0 | Python package, exports, dependency-light tests | Add runtime facade, stable public envelopes, CLI. |
 | Profile contract ingress | 2.0 | 4.0 | Markitect-compatible profile loading and diagnostics | Add validation adapter boundary and compatibility fixture catalog. |
 | Graph/event contract ingress | 2.0 | 4.0 | Graph loading, edge endpoint diagnostics, event model | Add richer event path modeling and import/export repair diagnostics. |
 | Phase domain model | 2.5 | 4.0 | Phases, memory kinds, lifecycle states, actions | Add transition rules, approved apply behavior, path-aware state updates. |
 | Profile execution planning | 2.5 | 4.0 | Adapter plan, capabilities, policy gates, fallback behavior | Add runtime orchestration, JSON snapshots, CLI outputs. |
 | Lifecycle planning | 2.0 | 4.0 | Transition, retention, refresh, compaction dry-run plans | Add profile-driven rule evaluation and review-gated apply. |
 | Activation planning | 2.0 | 5.0 | Budgeted selection and Markitect-compatible selection output | Add graph neighborhoods, event paths, ranking, metadata preservation, metrics. |
 | Local persistence | 1.0 | 4.0 | In-memory adapters only | Add versioned file-backed graph store and JSONL event log. |
 | Policy and audit | 1.5 | 5.0 | Policy/audit ports, allow-all gateway, recording sink, review flags | Add enforcement points, review records, redaction, audit schema. |
 | Observability and diagnostics | 1.5 | 4.0 | Planner diagnostics and observability event names | Add audit/health envelopes and adapter status diagnostics. |
 | Markitect interop | 1.5 | 4.0 | Compatible schema constants and selection handoff | Add package bridge envelopes, optional validation/compiler adapters. |
 | Kontextual/Infospace interop | 1.0 | 4.0 | Boundaries documented and small derived fixtures | Add delegation envelope design and evaluation fixture reports. |
 | Testing and evaluation | 2.0 | 4.0 | 13 deterministic tests over core planners/adapters | Add CLI snapshots, file-store round trips, policy denial, activation metrics. |
 | Service readiness | 0.5 | 4.0 | Runtime ports exist | Add service contracts, config, health checks, adapter conformance tests. |
 | Developer experience | 2.0 | 4.0 | README quick start and package map | Add CLI guide, local persistence guide, examples, troubleshooting. |
 ## 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
 ```mermaid
 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"]
  WP1 --> WP2
  WP2 --> WP3
  WP2 --> WP4
  WP2 --> WP5
  WP3 --> WP4
  WP5 --> WP6
  WP4 --> WP6
  WP3 --> WP7
  WP4 --> WP7
  WP5 --> WP7
  WP6 --> WP7
 ```
 ## 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
--- a/workplans/PMEM-WP-0002-local-runtime-facade-and-cli.md
+++ b/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.
--- a/workplans/PMEM-WP-0003-file-backed-stores-and-event-path-runtime.md
+++ b/workplans/PMEM-WP-0003-file-backed-stores-and-event-path-runtime.md
@@ -0,0 +1,188 @@
 ---
 id: PMEM-WP-0003
 type: workplan
 title: "File-Backed Stores And Event Path Runtime"
 domain: markitect
 repo: phase-memory
 status: proposed
 owner: phase-memory
 topic_slug: local-persistence
 planning_priority: P1
 planning_order: 30
 related_workplans:
  - PMEM-WP-0002
 created: "2026-05-18"
 updated: "2026-05-18"
 state_hub_workstream_id: "c15d2f61-449b-48fa-9e4d-ea22a9b419b2"
 ---
 # PMEM-WP-0003: File-Backed Stores And Event Path Runtime
 ## Goal
 Add a local-first durable adapter layer that can persist profiles, graph
 records, and append-only memory events without requiring external
 infrastructure.
 This should move the project from deterministic in-memory tests to a useful
 developer runtime while preserving the INTENT.md principle that durable writes
 are explicit, inspectable, and policy-aware.
 ## Current Evidence
 The repository has port protocols and in-memory adapters, but no file-backed
 store, event replay, export, import, or durable local graph snapshot format.
 The memory event model also exists, but conversational paths are not yet
 first-class runtime objects.
 ## Non-Goals
 - Do not choose a production graph database.
 - Do not implement a generic vector database.
 - Do not add hidden background compaction or deletion.
 - Do not make file-backed storage the only adapter option.
 ## T01 - Define local storage layout
 ```task
 id: PMEM-WP-0003-T01
 status: todo
 priority: high
 state_hub_task_id: "37d082c7-c019-4ecd-8655-94f8f27807ff"
 ```
 Define a simple versioned local storage layout for:
 - profiles
 - nodes
 - edges
 - events
 - activation plans
 - audit records
 - runtime metadata
 Prefer JSON and JSONL formats for this slice unless a concrete requirement
 forces SQLite.
 Output: documented storage layout, schema version fields, and fixture examples.
 ## T02 - Implement a file-backed graph store
 ```task
 id: PMEM-WP-0003-T02
 status: todo
 priority: high
 state_hub_task_id: "c417f7ec-0423-4723-91c3-3b4681e30ec3"
 ```
 Implement a deterministic adapter for the `MemoryGraphStore` protocol that can:
 - save and load profiles
 - save and load nodes
 - save and load edges
 - list nodes by kind
 - list edges by source or target
 - export a Markitect-compatible graph envelope
 Output: adapter implementation and tests for round-trip behavior.
 ## T03 - Implement a JSONL event log
 ```task
 id: PMEM-WP-0003-T03
 status: todo
 priority: high
 state_hub_task_id: "1d3b3ffb-fc9b-401f-a77f-cfad4a4f6b72"
 ```
 Implement an append-only `MemoryEventLog` adapter with:
 - duplicate event id detection
 - deterministic ordering
 - kind filtering
 - replay into graph snapshots where possible
 - corruption diagnostics for malformed lines
 Output: event log adapter and tests for append, list, replay, and diagnostics.
 ## T04 - Model conversational paths explicitly
 ```task
 id: PMEM-WP-0003-T04
 status: todo
 priority: high
 state_hub_task_id: "43d5863c-f2db-441e-8f3e-7e1843b6bc33"
 ```
 Add first-slice path records for fluid memory:
 - path id
 - parent path id
 - event ids
 - active branch marker
 - merge marker
 - abandoned branch reason
 - compaction status
 Output: path model, path event helpers, and tests that show branch, merge, and
 abandon flows without requiring transcript storage.
 ## T05 - Add safe apply behavior behind review gates
 ```task
 id: PMEM-WP-0003-T05
 status: todo
 priority: medium
 state_hub_task_id: "e9079c0c-5834-47b2-b1dc-1d97604c96f8"
 ```
 Add an optional runtime operation that applies approved lifecycle actions to a
 file-backed store. The operation must reject actions that require review unless
 the caller provides an explicit approval marker.
 Output: apply operation, approval checks, audit records, and tests that prove
 unapproved durable actions are denied.
 ## T06 - Add import, export, and repair diagnostics
 ```task
 id: PMEM-WP-0003-T06
 status: todo
 priority: medium
 state_hub_task_id: "a0597e3e-2f2d-4abf-8fc2-37c914e0ce34"
 ```
 Add local tooling to:
 - import Markitect-compatible graph and profile fixtures
 - export local state to a graph envelope
 - report missing edge endpoints
 - report orphaned events
 - report unknown schema versions
 Output: CLI/runtime helpers and tests for useful diagnostics.
 ## T07 - Update docs with local persistence examples
 ```task
 id: PMEM-WP-0003-T07
 status: todo
 priority: medium
 state_hub_task_id: "60b3bce7-3e73-427b-95d7-d68283503a3c"
 ```
 Document how to create a local memory workspace, import a profile and graph,
 append events, inspect paths, and export a graph.
 Output: local persistence guide and README pointers.
 ## Acceptance Criteria
 - `python3 -m pytest` passes.
 - File-backed adapters satisfy the same public protocols as in-memory adapters.
 - A local workspace can be created, inspected, exported, and replayed
  deterministically.
 - Review-required actions cannot be applied without an explicit approval
  marker.
 - Conversational path branches and merges are represented as structured memory
  events, not only as transcript text.
--- a/workplans/PMEM-WP-0004-policy-audit-and-review-gates.md
+++ b/workplans/PMEM-WP-0004-policy-audit-and-review-gates.md
@@ -0,0 +1,204 @@
 ---
 id: PMEM-WP-0004
 type: workplan
 title: "Policy, Audit, And Review Gates"
 domain: markitect
 repo: phase-memory
 status: proposed
 owner: phase-memory
 topic_slug: policy-audit
 planning_priority: P1
 planning_order: 40
 related_workplans:
  - PMEM-WP-0002
  - PMEM-WP-0003
 created: "2026-05-18"
 updated: "2026-05-18"
 state_hub_workstream_id: "e8d405a3-3ddd-4353-81a2-518850033b8e"
 ---
 # PMEM-WP-0004: Policy, Audit, And Review Gates
 ## Goal
 Make policy-aware memory behavior concrete enough that phase-memory can safely
 plan and apply memory lifecycle changes.
 The project intent calls for provenance, confidence, freshness, policy
 metadata, reauthorization, audit, redaction, and trust-zone boundaries. The
 current implementation surfaces policy gates, but it does not yet enforce
 review gates beyond planner metadata.
 ## Current Evidence
 Current code includes:
 - `PolicyDecision`
 - `PolicyGateway` protocol
 - `AuditSink` protocol
 - `AllowAllPolicyGateway`
 - `RecordingAuditSink`
 - policy gate strings in profile execution plans
 - review-required flags on stabilization, compaction, refresh, and deletion
  proposals
 The next step is an explicit authorization and audit workflow for reads,
 activations, writes, compactions, and phase transitions.
 ## Non-Goals
 - Do not build a full identity platform.
 - Do not implement enterprise authorization policy languages.
 - Do not make `flex-auth` a hard dependency.
 - Do not store or expose secrets in test fixtures.
 ## T01 - Define memory operation policy points
 ```task
 id: PMEM-WP-0004-T01
 status: todo
 priority: high
 state_hub_task_id: "1231b7bf-b23c-498d-a9d6-a6ee307aa3d4"
 ```
 Define the canonical policy check points for:
 - profile import
 - graph import
 - node read
 - event read
 - activation
 - stabilization
 - compaction
 - refresh
 - delete request
 - archive
 - export
 Output: operation vocabulary and tests that runtime operations call policy at
 the right boundary.
 ## T02 - Add review authorization records
 ```task
 id: PMEM-WP-0004-T02
 status: todo
 priority: high
 state_hub_task_id: "b989d43c-eb25-4663-afd1-a54673ad565a"
 ```
 Add structured review records for actions that move memory into stabilized or
 rigid states, compact source records, refresh source-backed facts, or request
 deletion.
 Records should capture:
 - reviewer id or local reviewer label
 - reviewed action id
 - approval or rejection
 - timestamp
 - reason
 - policy obligations
 - source digests
 Output: review record model and approval checks in the runtime facade.
 ## T03 - Enforce durable write gates
 ```task
 id: PMEM-WP-0004-T03
 status: todo
 priority: high
 state_hub_task_id: "6b677c18-7135-4d54-9e46-5116645d2ebe"
 ```
 Make durable write operations fail closed when profile policy declares
 review-gated durable writes.
 Output: runtime tests proving that stabilization, rigid updates, compaction,
 and deletion requests cannot be applied silently.
 ## T04 - Add activation policy checks
 ```task
 id: PMEM-WP-0004-T04
 status: todo
 priority: high
 state_hub_task_id: "6f07087b-e6e2-469a-9bce-71bfd21cb633"
 ```
 Before memory nodes or events are included in activation packages, check:
 - required labels
 - denied labels
 - trust zone compatibility
 - secrets allowance
 - reauthorization requirements
 - source freshness requirements
 Output: activation planner/runtime policy tests and omitted-item diagnostics
 for policy-denied records.
 ## T05 - Add audit event schema
 ```task
 id: PMEM-WP-0004-T05
 status: todo
 priority: medium
 state_hub_task_id: "bb6461a8-9181-4b88-a152-334668b22208"
 ```
 Define a stable audit event envelope for memory operations:
 - operation id
 - operation kind
 - subject id
 - profile id
 - graph id
 - policy decision
 - dry-run flag
 - planned action id
 - actor label
 - timestamp
 - source contract references
 Output: audit schema helpers and tests for profile, lifecycle, activation, and
 apply operations.
 ## T06 - Add redaction and denial diagnostics
 ```task
 id: PMEM-WP-0004-T06
 status: todo
 priority: medium
 state_hub_task_id: "dcdec3af-d20f-43ba-b12e-6febc4347d38"
 ```
 Add deterministic redaction behavior for denied fields and policy-sensitive
 metadata. Redaction should be visible in diagnostics and audit events.
 Output: redaction utility, denied activation examples, and regression tests.
 ## T07 - Document policy and audit guarantees
 ```task
 id: PMEM-WP-0004-T07
 status: todo
 priority: medium
 state_hub_task_id: "c4e0bdff-5047-4fe5-ab86-e422d4b1a17e"
 ```
 Document what the local runtime guarantees and what remains delegated to
 external policy infrastructure.
 Output: policy architecture note with examples of allowed, denied, and
 review-required operations.
 ## Acceptance Criteria
 - `python3 -m pytest` passes.
 - Every apply-capable operation has policy and audit coverage.
 - Activation explains policy-denied and redacted items.
 - Review-required actions fail closed without an explicit review record.
 - The policy layer remains adapter-based and does not become an identity
  platform.
--- a/workplans/PMEM-WP-0005-markitect-package-bridge-and-contract-interop.md
+++ b/workplans/PMEM-WP-0005-markitect-package-bridge-and-contract-interop.md
@@ -0,0 +1,184 @@
 ---
 id: PMEM-WP-0005
 type: workplan
 title: "Markitect Package Bridge And Contract Interop"
 domain: markitect
 repo: phase-memory
 status: proposed
 owner: phase-memory
 topic_slug: markitect-interop
 planning_priority: P1
 planning_order: 50
 related_workplans:
  - PMEM-WP-0002
  - PMEM-WP-0004
 created: "2026-05-18"
 updated: "2026-05-18"
 state_hub_workstream_id: "be683a3e-49d1-4e35-a227-c43233cc652e"
 ---
 # PMEM-WP-0005: Markitect Package Bridge And Contract Interop
 ## Goal
 Make the boundary with `markitect-tool` operational while preserving clean
 ownership.
 `phase-memory` should consume Markitect-compatible profiles, graphs, events,
 and selections; plan memory operations; and hand activation selections to a
 Markitect-owned context-package compiler. It should not fork Markitect syntax
 or quietly depend on Markitect internals.
 ## Current Evidence
 The repository currently has:
 - constants for Markitect memory profile, graph, and selection schema versions
 - profile and graph ingress helpers
 - a selection output from activation planning
 - a `ContextPackageCompiler` protocol
 - a noop compiler adapter for tests
 The missing work is a real bridge contract, compatibility fixtures, validation
 delegation, and stable package request/response envelopes.
 ## Non-Goals
 - Do not reimplement Markitect schema validation.
 - Do not own context package internals.
 - Do not require Markitect installation for the default test suite.
 - Do not turn Markitect into a hidden import dependency.
 ## T01 - Define compiler bridge envelopes
 ```task
 id: PMEM-WP-0005-T01
 status: todo
 priority: high
 state_hub_task_id: "e51c4804-4938-443b-b02f-afa7bac0b846"
 ```
 Define the request and response shape for context package compilation:
 - selection id
 - graph id
 - profile id
 - selected nodes
 - selected events
 - budget metadata
 - policy metadata
 - provenance metadata
 - compiler diagnostics
 - package reference
 Output: typed helpers and JSON fixtures for package requests and responses.
 ## T02 - Add Markitect validation adapter boundary
 ```task
 id: PMEM-WP-0005-T02
 status: todo
 priority: high
 state_hub_task_id: "5a1a8777-b971-4f1b-bf65-bd71918eabf6"
 ```
 Add an adapter boundary that can delegate validation to Markitect when
 available, while still accepting already-valid dictionaries in dependency-light
 mode.
 Output: protocol, noop/local validation adapter, optional Markitect-backed
 adapter design, and tests around fallback behavior.
 ## T03 - Preserve provenance and source spans through activation
 ```task
 id: PMEM-WP-0005-T03
 status: todo
 priority: high
 state_hub_task_id: "012210c6-fc05-467e-9d36-7358c0e11abd"
 ```
 Ensure activation selections carry enough information for Markitect to compile
 inspectable packages:
 - source spans
 - provenance
 - confidence
 - freshness
 - namespace
 - policy labels
 - reason selected
 Output: expanded selection metadata and tests proving metadata survives ingress
 to package request.
 ## T04 - Add interop fixture catalog
 ```task
 id: PMEM-WP-0005-T04
 status: todo
 priority: medium
 state_hub_task_id: "90ebf80e-1f7e-422c-879c-f4270f1e232e"
 ```
 Create a fixture catalog that mirrors the Markitect contract shapes this repo
 expects, including:
 - valid profile
 - invalid profile
 - valid graph
 - invalid graph
 - activation selection
 - package request
 - package response
 Output: fixtures and docs that downstream repos can use as compatibility
 examples.
 ## T05 - Add contract compatibility tests
 ```task
 id: PMEM-WP-0005-T05
 status: todo
 priority: medium
 state_hub_task_id: "95b07795-6d8c-4473-a98a-5e48a3e6cca9"
 ```
 Add tests that prove phase-memory can:
 - accept Markitect profile and graph fixtures
 - report diagnostics without claiming schema ownership
 - emit Markitect-compatible selections
 - build package requests through the compiler port
 - consume package responses without understanding internals
 Output: compatibility test suite.
 ## T06 - Document the Markitect boundary
 ```task
 id: PMEM-WP-0005-T06
 status: todo
 priority: medium
 state_hub_task_id: "21e4ffb5-e8dc-4b32-9008-97fb6ffb3726"
 ```
 Update architecture docs with a concrete boundary contract:
 - what Markitect owns
 - what phase-memory owns
 - which data moves across the boundary
 - which diagnostics stay local
 - how optional Markitect integration is configured
 Output: interop architecture note.
 ## Acceptance Criteria
 - `python3 -m pytest` passes.
 - Activation package bridge envelopes are stable and documented.
 - The default test suite does not require Markitect to be installed.
 - Optional Markitect validation or compilation can be added without changing
  the core planner APIs.
 - Source spans, provenance, freshness, confidence, and policy metadata survive
  from graph ingress to package request.
--- a/workplans/PMEM-WP-0006-retrieval-activation-quality-and-evaluation.md
+++ b/workplans/PMEM-WP-0006-retrieval-activation-quality-and-evaluation.md
@@ -0,0 +1,189 @@
 ---
 id: PMEM-WP-0006
 type: workplan
 title: "Retrieval, Activation Quality, And Evaluation"
 domain: markitect
 repo: phase-memory
 status: proposed
 owner: phase-memory
 topic_slug: activation-quality
 planning_priority: P2
 planning_order: 60
 related_workplans:
  - PMEM-WP-0002
  - PMEM-WP-0005
 created: "2026-05-18"
 updated: "2026-05-18"
 state_hub_workstream_id: "68417e46-d0a4-4168-bdd6-9ba6ac7847c1"
 ---
 # PMEM-WP-0006: Retrieval, Activation Quality, And Evaluation
 ## Goal
 Move activation planning beyond deterministic id ordering into explainable,
 policy-aware memory retrieval and evaluation.
 INTENT.md expects activation memory to compile graph neighborhoods, decision
 paths, conversation episodes, and knowledge slices into bounded context
 packages. The current activation planner selects nodes under item and token
 budgets, but it does not yet model graph neighborhoods, event paths, freshness,
 confidence, or retrieval quality.
 ## Current Evidence
 Current activation behavior:
 - prioritizes explicitly requested node ids
 - sorts remaining nodes by id
 - estimates tokens with word count
 - includes events only when they reference packages or activations
 - emits Markitect-compatible selection dictionaries
 - explains budget omissions
 This is enough for a first handoff, but not enough to satisfy the full
 activation-memory intent.
 ## Non-Goals
 - Do not require embeddings or vector stores in the default path.
 - Do not use live LLM ranking in deterministic tests.
 - Do not own benchmark dashboards that belong in `infospace-bench`.
 - Do not optimize for a single application domain.
 ## T01 - Add deterministic graph-neighborhood retrieval
 ```task
 id: PMEM-WP-0006-T01
 status: todo
 priority: high
 state_hub_task_id: "8ed0909f-9e8e-4d49-9312-dca267df29f5"
 ```
 Add selection strategies that can expand from seed nodes across graph edges:
 - one-hop neighbors
 - bounded multi-hop neighbors
 - edge-kind filters
 - source and target direction filters
 - phase filters
 - memory kind filters
 Output: retrieval planner and tests for stable graph-neighborhood selection.
 ## T02 - Add event-path activation
 ```task
 id: PMEM-WP-0006-T02
 status: todo
 priority: high
 state_hub_task_id: "5d48ba91-fef0-4d4f-a560-836abed1c527"
 ```
 Select conversational path episodes and event windows as first-class
 activation inputs.
 Output: event-path selection support, path budget behavior, and tests around
 active, abandoned, and merged paths.
 ## T03 - Add ranking signals and explanations
 ```task
 id: PMEM-WP-0006-T03
 status: todo
 priority: high
 state_hub_task_id: "0f6340ef-f7bd-408b-b98e-6d90188c5969"
 ```
 Rank activation candidates using deterministic local signals:
 - explicit priority
 - graph distance from seed
 - lifecycle state
 - phase
 - freshness
 - confidence
 - policy allowance
 - source-backed status
 - prior activation references
 Output: scoring model, per-item selection reason, and omitted-item reason.
 ## T04 - Improve token and budget accounting
 ```task
 id: PMEM-WP-0006-T04
 status: todo
 priority: medium
 state_hub_task_id: "12d83382-a767-45a8-b7cc-8c3f6f3f4c37"
 ```
 Replace rough word-count behavior with a pluggable budget estimator that can
 stay deterministic locally and later delegate to provider-specific tokenizers.
 Output: estimator protocol, default estimator, and tests for node, event, and
 package budget pressure.
 ## T05 - Add evaluation fixture scenarios
 ```task
 id: PMEM-WP-0006-T05
 status: todo
 priority: medium
 state_hub_task_id: "509e9417-3aa7-4899-aed5-20749372fe00"
 ```
 Add small evaluation fixtures inspired by adjacent `infospace-bench` pilots:
 - restart package
 - decision recall
 - stale source refresh
 - policy-denied activation
 - compacted trace window
 - conflicting preference update
 Output: fixture set and expected activation plans.
 ## T06 - Add maturity metrics for activation quality
 ```task
 id: PMEM-WP-0006-T06
 status: todo
 priority: medium
 state_hub_task_id: "477a896a-8013-42a5-b965-b1ccd2577fec"
 ```
 Define local metrics that can be exported to `infospace-bench` later:
 - selected expected nodes
 - omitted required nodes
 - policy-denied required nodes
 - token budget utilization
 - stale item activation count
 - provenance coverage
 - source span coverage
 - explanation coverage
 Output: metrics helper and JSON report fixture.
 ## T07 - Document retrieval and evaluation behavior
 ```task
 id: PMEM-WP-0006-T07
 status: todo
 priority: medium
 state_hub_task_id: "551432e4-2551-49fa-b17b-f762853a6a50"
 ```
 Document activation strategy, scoring inputs, limitations, and evaluation
 fixtures.
 Output: activation planning guide and scorecard update.
 ## Acceptance Criteria
 - `python3 -m pytest` passes.
 - Activation can select graph neighborhoods and event paths under budget.
 - Every selected and omitted item has a machine-readable reason.
 - Evaluation fixtures produce deterministic activation quality reports.
 - Optional semantic indexes remain behind the `SemanticIndex` port.
--- a/workplans/PMEM-WP-0007-service-readiness-and-external-adapters.md
+++ b/workplans/PMEM-WP-0007-service-readiness-and-external-adapters.md
@@ -0,0 +1,195 @@
 ---
 id: PMEM-WP-0007
 type: workplan
 title: "Service Readiness And External Adapters"
 domain: markitect
 repo: phase-memory
 status: proposed
 owner: phase-memory
 topic_slug: service-readiness
 planning_priority: P2
 planning_order: 70
 related_workplans:
  - PMEM-WP-0003
  - PMEM-WP-0004
  - PMEM-WP-0005
  - PMEM-WP-0006
 created: "2026-05-18"
 updated: "2026-05-18"
 state_hub_workstream_id: "35512fad-8a37-406d-9074-6b6891a5a83a"
 ---
 # PMEM-WP-0007: Service Readiness And External Adapters
 ## Goal
 Prepare phase-memory to run as an embedded runtime or service-backed adapter
 layer once the local runtime, persistence, policy, package bridge, and
 activation quality slices are stable.
 INTENT.md says the project should run standalone, embedded behind a local
 agent toolchain, as a service with durable stores, and as an adapter layer over
 existing systems. This workplan is the transition from local library to
 integration-ready runtime.
 ## Current Evidence
 The repository currently defines ports for graph stores, event logs, context
 package compilers, semantic indexes, policy gateways, audit sinks, and runtime
 registries. It does not yet define service API contracts, adapter conformance
 tests, runtime configuration, health checks, or deployment guidance.
 ## Non-Goals
 - Do not make the service path mandatory for local use.
 - Do not choose one production graph, vector, policy, or audit provider as the
  only supported backend.
 - Do not move durable knowledge ownership out of `kontextual-engine`.
 - Do not add operational complexity before PMEM-WP-0002 through PMEM-WP-0006
  stabilize.
 ## T01 - Define runtime service API contracts
 ```task
 id: PMEM-WP-0007-T01
 status: todo
 priority: high
 state_hub_task_id: "48dc8e83-ff0f-4c25-b1c9-d94c3a2ac0eb"
 ```
 Define service-level request and response contracts for:
 - profile plan
 - graph import
 - lifecycle plan
 - lifecycle apply
 - activation plan
 - package compile handoff
 - audit query
 - health check
 Output: API contract docs and fixture request/response envelopes.
 ## T02 - Add adapter conformance tests
 ```task
 id: PMEM-WP-0007-T02
 status: todo
 priority: high
 state_hub_task_id: "da22d548-3123-46fc-acac-8bbcf8b54fb7"
 ```
 Create conformance tests for all public adapter protocols:
 - graph store
 - event log
 - context package compiler
 - semantic index
 - policy gateway
 - audit sink
 - runtime registry
 Output: reusable test helpers that any external adapter must pass.
 ## T03 - Add Kontextual delegation adapter design
 ```task
 id: PMEM-WP-0007-T03
 status: todo
 priority: high
 state_hub_task_id: "2a0fc3d0-3dda-4c58-95de-3f70cf097ff1"
 ```
 Define the first external delegation boundary for `kontextual-engine`:
 - what phase-memory asks Kontextual to persist or retrieve
 - what Kontextual delegates back to phase-memory for phase policy
 - how audit and policy decisions are exchanged
 - how circular imports are avoided
 Output: adapter design note, envelope fixtures, and local fake adapter tests.
 ## T04 - Add optional service runner
 ```task
 id: PMEM-WP-0007-T04
 status: todo
 priority: medium
 state_hub_task_id: "10934c46-db81-4a68-be4f-2ce95408d279"
 ```
 Add an optional service runner only after the local runtime API is stable.
 Keep dependencies optional and the default test suite dependency-light.
 Output: minimal service module, health endpoint, deterministic tests, and
 clear installation extras if a framework is used.
 ## T05 - Add runtime configuration model
 ```task
 id: PMEM-WP-0007-T05
 status: todo
 priority: medium
 state_hub_task_id: "a7129077-b736-4d69-94ab-d6921cd8ed15"
 ```
 Define configuration for:
 - local store path
 - adapter registry
 - policy mode
 - audit sink mode
 - package compiler mode
 - semantic index mode
 - dry-run default
 - trust-zone labels
 Output: config model, default local config, and validation diagnostics.
 ## T06 - Add observability and health diagnostics
 ```task
 id: PMEM-WP-0007-T06
 status: todo
 priority: medium
 state_hub_task_id: "24ef8feb-90f8-454d-8c8f-7b3468454f57"
 ```
 Expose runtime diagnostics for:
 - adapter availability
 - store schema version
 - pending review actions
 - stale memory counts
 - activation budget pressure
 - audit sink status
 - package compiler status
 Output: health report helpers and tests.
 ## T07 - Document deployment modes
 ```task
 id: PMEM-WP-0007-T07
 status: todo
 priority: medium
 state_hub_task_id: "89c8802c-f536-441b-a514-8d3e56b3c6e5"
 ```
 Document the supported deployment modes:
 - pure library
 - CLI over local files
 - embedded runtime
 - optional service
 - adapter layer over external stores
 Output: service-readiness guide and scorecard update.
 ## Acceptance Criteria
 - `python3 -m pytest` passes.
 - Service contracts are documented before service implementation expands.
 - External adapters can be validated with reusable conformance tests.
 - Local library and CLI use remain first-class.
 - The Kontextual delegation boundary is explicit and avoids ownership drift.