phase-memory/workplans/PMEM-WP-0011-refinement-hardening-and-operational-readiness.md

---
id: PMEM-WP-0011
type: workplan
title: "Refinement Hardening And Operational Readiness"
domain: markitect
repo: phase-memory
status: finished
owner: codex
topic_slug: phase-memory
created: "2026-05-18"
updated: "2026-05-18"
state_hub_workstream_id: "a427c05f-0ff5-49d1-b719-7dfd4f1f8571"
---

# PMEM-WP-0011: Refinement Hardening And Operational Readiness

## Goal

Close the gap exposed by the refined maturity scorecard: the local core is
integration-ready, but the operational surface still needs service parity,
durability/migration semantics, richer evaluation, and adapter compatibility
gates.

## Current Evidence

The repo now has:

- deterministic runtime envelopes and CLI behavior;
- file-backed graph/event/audit adapters;
- policy, review, and activation denials;
- Markitect package bridge envelopes;
- profile-derived runtime config and lifecycle rules;
- service contracts, health checks, and adapter conformance helpers;
- fake external adapter packs.

The refined scorecard in `docs/maturity-scorecard.md` scores the project at
**4.0 / 5** overall, with stronger local integration maturity than operational
maturity.

## Non-Goals

- Build production-hosted services in this repo.
- Add network credentials or live service dependencies to default tests.
- Replace fake adapter packs with mandatory live adapters.
- Expand beyond phase-memory's ownership boundary.

## T01 - Bring service runner to contract parity

```task
id: PMEM-WP-0011-T01
status: done
priority: high
state_hub_task_id: "2b3c6eb4-8d3f-4c73-ab53-74e1bed8b93f"
```

Implement local service runner handling for every operation in
`SERVICE_OPERATIONS`, especially `package.compile`, `lifecycle.apply`, and
`audit.query`.

Acceptance:

- Every operation in `service_contracts()` has a local runner path or explicit
  unsupported diagnostic.
- Tests cover successful `package.compile`, review-gated `lifecycle.apply`,
  and audit querying.

## T02 - Harden local persistence migration and repair

```task
id: PMEM-WP-0011-T02
status: done
priority: high
state_hub_task_id: "2c19cfb0-e147-40b8-b964-6c617bddb90e"
```

Add migration and repair semantics for the local file-backed store.

Acceptance:

- Store metadata can declare schema versions and planned migrations.
- Repair diagnostics distinguish corruption, missing references, and migration
  needs.
- Writes are made safer through atomic write behavior where practical.

## T03 - Expand evaluation fixtures and gates

```task
id: PMEM-WP-0011-T03
status: done
priority: high
state_hub_task_id: "cdce1c6a-4581-4184-87c6-f7bec6c3fcbd"
```

Broaden activation/lifecycle evaluation beyond the single primary fixture
family.

Acceptance:

- Add at least three profile/graph scenario families.
- Cover policy-denied activation, profile lifecycle rules, event-path
  activation, semantic-index hints, and budget pressure.
- Add deterministic report fixtures or threshold assertions.

## T04 - Add adapter pack compatibility manifests

```task
id: PMEM-WP-0011-T04
status: done
priority: medium
state_hub_task_id: "602c22bb-d440-4d38-a51f-bf6ed504fd1e"
```

Define manifest metadata for fake and future live adapter packs.

Acceptance:

- Adapter packs can declare capabilities, ownership boundaries, and required
  conformance helpers.
- Fake pack tests use the manifest rather than only direct class assertions.
- Missing capability diagnostics are explicit.

## T05 - Make policy/audit retention inspectable

```task
id: PMEM-WP-0011-T05
status: done
priority: medium
state_hub_task_id: "c4fa6001-b20c-4ec1-b885-af9b80c832de"
```

Add query and retention behavior around audit records.

Acceptance:

- Audit sink query behavior is exposed through runtime/service paths.
- Retention metadata is visible and testable.
- Review and denial audit records can be traced after operations.

## T06 - Improve operational developer experience

```task
id: PMEM-WP-0011-T06
status: done
priority: medium
state_hub_task_id: "f4674eaf-cbc1-4eac-b1d1-b07ae51289cf"
```

Add end-to-end recipes, troubleshooting, and API compatibility notes.

Acceptance:

- README links to the refined maturity scorecard.
- Docs include a local end-to-end recipe from profile/graph import to
  lifecycle, activation, package compile, audit query, and health.
- Public API compatibility expectations are documented.

## Acceptance Criteria

- Refined maturity blockers have concrete executable coverage.
- The scorecard can move from 3.8 toward 4.0 based on behavior, not optimism.
- StateHub has this refinement workplan as the next actionable PMEM workstream.

## Closure Review

Completed on 2026-05-18.

Implemented:

- Full `LocalServiceRunner` handling for every `SERVICE_OPERATIONS` entry.
- Runtime and service audit queries with queryable recording/JSONL/fake audit
  sinks and retention metadata.
- Review-gated `lifecycle.apply` and `package.compile` service coverage.
- Atomic JSON writes for file-backed store records plus metadata migration,
  planned-migration, corrupt-record, missing-reference, and orphaned-path
  diagnostics.
- Three evaluation scenario families covering policy-denied activation,
  profile lifecycle rules, event-path activation, semantic-index hints, and
  budget pressure.
- Adapter pack compatibility manifests and explicit missing-capability
  diagnostics.
- Operational readiness docs and scorecard update from 3.8 to 4.0.

Verification:

- `python3 -m pytest` passes with 70 tests.