diff --git a/workplans/PMEM-WP-0016-ops-warden-cross-runtime-memory.md b/workplans/PMEM-WP-0016-ops-warden-cross-runtime-memory.md new file mode 100644 index 0000000..45e7162 --- /dev/null +++ b/workplans/PMEM-WP-0016-ops-warden-cross-runtime-memory.md @@ -0,0 +1,220 @@ +--- +id: PMEM-WP-0016 +type: workplan +title: "Ops-Warden Cross-Runtime Memory Profile And Contracts" +domain: communication +repo: phase-memory +status: proposed +owner: codex +topic_slug: phase-memory +created: "2026-07-02" +updated: "2026-07-02" +--- + +# PMEM-WP-0016: Ops-Warden Cross-Runtime Memory Profile And Contracts + +## Goal + +Define the phase-memory profile, event schemas, activation packs, and evaluation +gates that let **ops-warden learn from experience** across every runtime surface: + +- **Direct ops-warden use** — `warden worker` with llm-connect / OpenRouter + inference, scheduled ticks, and operator CLI (`route`, `access`, `sign`). +- **Coding agent sessions** — Claude Code, Codex, Grok, and future agents that + invoke warden commands during an interactive session. + +Memory must be **present** (discoverable, activatable, writable) in all three +modes without duplicating stores or leaking secrets. + +## Current Evidence + +`PMEM-WP-0015` added credential-safe pilot artifacts, ops-warden routing +advisories, evaluation trend regression gates, and redacted operator reports. +`WARDEN-WP-0020` shipped `warden worker` with `RuleBrain` and `LlmConnectBrain`, +fixed guardrails, and metadata-only audit via `warden activity`. + +The gap: no shared memory substrate connects worker ticks, agent sessions, and +operator CLI usage. Each invocation starts cold. + +## Non-Goals + +- Store secret values, tokens, endpoint URLs, or prompt bodies with credentials. +- Override ops-warden's fixed charter, action allowlist, or no-secret invariant + through learned memory. +- Own llm-connect, OpenRouter configuration, or ops-warden worker scheduling. +- Replace State Hub as the coordination transport. + +## Cross-Runtime Model + +```mermaid +flowchart LR + subgraph surfaces [Runtime surfaces] + Worker[warden worker tick] + Agent[Agent session
claude / codex / grok] + Operator[Operator CLI] + end + + subgraph contract [Shared contract] + Store[(warden memory store)] + Profile[ops-warden profile] + Activate[activation plan] + end + + Worker --> Store + Agent --> Store + Operator --> Store + Store --> Profile + Profile --> Activate +``` + +| Runtime mode | `session_kind` | Typical trigger | +| --- | --- | --- | +| `worker` | `warden.worker` | Scheduled tick, `warden worker run` | +| `agent_session` | `warden.agent.` | Coding agent invokes `warden route` / `warden access` | +| `operator` | `warden.operator` | Human shell without agent wrapper | + +All modes read/write the **same canonical store** (path owned by ops-warden, +schema owned by phase-memory). Modes differ only in `session_kind` metadata and +activation budget — not in storage location. + +## T01 - Define ops-warden memory profile + +```task +id: PMEM-WP-0016-T01 +status: todo +priority: high +``` + +Author the `ops-warden-coordination` memory profile covering routing, +coordination, escalation, and pilot-feedback memory kinds. + +Acceptance: + +- Profile declares memory kinds, retention, compaction, activation budgets, and + policy (`secrets_allowed: false`, `durable_writes: review-gated`). +- Rigid memory kinds are documented as **import-only** (charter, allowlist) and + never promoted from learned episodes. +- Profile validates through existing `profile_from_markitect` / runtime planning + paths with deterministic diagnostics. +- Fixture lives at `tests/fixtures/ops-warden-coordination-profile.json`. + +## T02 - Cross-runtime memory contract + +```task +id: PMEM-WP-0016-T02 +status: todo +priority: high +``` + +Define the `phase_memory.ops_warden.runtime.v1` contract: canonical store path +resolution, `session_kind` enum, read/write envelopes, and redaction rules. + +Acceptance: + +- Contract specifies canonical store default (XDG-based, overridable via + `WARDEN_MEMORY_STORE`) without embedding secrets. +- `session_kind` covers `warden.worker`, `warden.agent.*`, and `warden.operator`. +- Write envelopes reject payloads containing secret-field patterns (tokens, raw + URLs with credentials, key material). +- Contract is documented in `docs/ops-warden-memory-contract.md` and covered by + unit tests. + +## T03 - Agent session event schema + +```task +id: PMEM-WP-0016-T03 +status: todo +priority: high +``` + +Define metadata-only event schemas for coding agent sessions (Claude, Codex, +Grok, extensible `agent_id`). + +Acceptance: + +- Events capture: `agent_id`, `session_id`, `command` (`route find`, `access`, + `worker run`, etc.), `need_fingerprint`, `route_id`, `outcome` + (`resolved|escalated|skipped`), and `diagnostic_codes`. +- Schema supports unknown future `agent_id` values without code changes. +- No event field may contain secret values or full credential payloads. +- Conformance fixtures cover at least claude, codex, and grok agent ids. + +## T04 - Activation pack for routing memory + +```task +id: PMEM-WP-0016-T04 +status: todo +priority: high +``` + +Build an ops-warden activation pack that retrieves relevant coordination +episodes before inference or routing decisions. + +Acceptance: + +- Pack retrieves stabilized routing patterns, recent fluid thread summaries, and + applicable troubleshooting rows within profile token/item budgets. +- Activation output is a bounded context package suitable for llm-connect + injection and for agent session orientation. +- Pack works without network access (local store only). +- Tests prove deterministic selection for fixture graphs with duplicate need + fingerprints. + +## T05 - Evaluation scenarios and regression gate + +```task +id: PMEM-WP-0016-T05 +status: todo +priority: medium +``` + +Add evaluation scenarios and trend metrics for ops-warden memory quality across +runtime modes. + +Acceptance: + +- Scenarios cover: routing repeat accuracy, escalation precision, cross-runtime + continuity (agent session write → worker read), and OpenRouter call avoidance + when stabilized memory matches. +- Metrics integrate with `evaluation_trend_regression_gate`. +- Scenario fixture at `tests/fixtures/ops-warden-evaluation-scenarios.json`. +- Threshold report runs in default CI without live OpenRouter access. + +## T06 - Ops-warden adapter pack conformance + +```task +id: PMEM-WP-0016-T06 +status: todo +priority: medium +``` + +Publish a live-shaped ops-warden adapter pack and conformance suite for +ops-warden to consume. + +Acceptance: + +- Adapter pack manifest declares graph store, event log, audit sink, and + activation helpers required by `WARDEN-WP-0024`. +- `validate_adapter_pack_manifest` passes for the ops-warden pack. +- Public exports and API snapshot updated if new symbols are added. +- Pack documentation explains how ops-warden depends on phase-memory without + circular repo ownership. + +## Acceptance Criteria + +- ops-warden can activate phase-memory consistently from worker, agent session, + and operator CLI modes using one canonical store. +- Learned memory improves routing suggestions without weakening security + guardrails. +- Evaluation gates can block promotion when cross-runtime continuity or routing + accuracy regresses. + +## Dependencies + +- `WARDEN-WP-0024` (ops-warden repo) — consumes the contract and adapter pack. +- `WARDEN-WP-0020` — worker brain and guardrail foundation (finished). +- `PMEM-WP-0015` — pilot evidence and regression gate patterns (finished). + +## Closure Review + +Pending implementation. \ No newline at end of file