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

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

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
PMEM-WP-0011	workplan	Refinement Hardening And Operational Readiness	markitect	phase-memory	finished	codex	phase-memory	2026-05-18	2026-05-18	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

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

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

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

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

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

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.