generated from coulomb/repo-seed
255 lines
6.6 KiB
Markdown
255 lines
6.6 KiB
Markdown
---
|
|
id: PMEM-WP-0004
|
|
type: workplan
|
|
title: "Policy, Audit, And Review Gates"
|
|
domain: markitect
|
|
repo: phase-memory
|
|
status: finished
|
|
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.
|
|
|
|
## Implementation Update - 2026-05-18
|
|
|
|
The policy, audit, and review-gate slice is complete.
|
|
|
|
Implemented outputs:
|
|
|
|
- `phase_memory.policy` defines canonical memory operation points, audit event
|
|
schema helpers, review-record helpers, activation policy checks, and
|
|
deterministic redaction.
|
|
- `ReviewRecord` and `ReviewDecision` model structured local approvals and
|
|
rejections for review-gated lifecycle actions.
|
|
- Runtime audit events now use `phase_memory.audit.event.v1` and carry policy
|
|
decisions, source references, dry-run flags, actor labels, and subjects.
|
|
- `apply_lifecycle_actions` rejects review-required actions unless the caller
|
|
provides a matching approved review record or explicit local approval marker.
|
|
- Activation planning can evaluate required labels, denied labels, trust zones,
|
|
secret denial, reauthorization, and freshness policy context before package
|
|
selection.
|
|
- Policy-denied activation nodes are omitted and returned as redacted denial
|
|
records with diagnostics.
|
|
- `docs/policy-audit.md` documents operation points, review records,
|
|
activation policy, audit envelopes, and ownership boundaries.
|
|
|
|
Validation:
|
|
|
|
- `python3 -m pytest` -> 36 passed.
|
|
|
|
## T01 - Define memory operation policy points
|
|
|
|
```task
|
|
id: PMEM-WP-0004-T01
|
|
status: done
|
|
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: done
|
|
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: done
|
|
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: done
|
|
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: done
|
|
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: done
|
|
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: done
|
|
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.
|
|
|
|
## Closure Review - 2026-05-18
|
|
|
|
**Outcome:** All tasks completed.
|
|
|
|
### Completed
|
|
|
|
- PMEM-WP-0004-T01 - Define memory operation policy points
|
|
- PMEM-WP-0004-T02 - Add review authorization records
|
|
- PMEM-WP-0004-T03 - Enforce durable write gates
|
|
- PMEM-WP-0004-T04 - Add activation policy checks
|
|
- PMEM-WP-0004-T05 - Add audit event schema
|
|
- PMEM-WP-0004-T06 - Add redaction and denial diagnostics
|
|
- PMEM-WP-0004-T07 - Document policy and audit guarantees
|
|
|
|
### Cancelled
|
|
|
|
None.
|
|
|
|
### Carried Forward
|
|
|
|
Optional Markitect validation and context-package compiler bridge behavior
|
|
remain in PMEM-WP-0005.
|