ADR-008: Walking Skeleton Policy Governance

Status: Accepted Version: 1.0 Date: 2026-01-01 Supersedes: N/A Related ADRs: ADR-006 (Ingest), ADR-007 (Memory) Related PRDs: PRD-GOVERN-001

Context

The Walking Skeleton requires policy-based governance to validate access and enforce constraints. After ingesting policies (S1A) and enabling retrieval (S1B), we need a governance layer that:

Evaluates policy rules (OPA)
Enforces access control (who can query what)
Logs audit events (compliance)

Per P001-SKELETON, this is the third component in the golden thread: “Govern - Check ‘Am I allowed to see this?’“

Decision

Implement a minimal policy governance service for Cycle S1C with:

Policy Engine: Open Policy Agent (OPA) with Rego rules
Enforcement Point: Query authorization check before retrieval
Audit Log: Structured logging of policy decisions
Integration: Lightweight HTTP API for decision requests

Rationale

OPA as Policy Engine

Standard: CNCF graduated project, industry-standard
Declarative: Rego policy language, version-controllable
Fast: In-process evaluation, <1ms decision latency
Flexible: Supports RBAC, ABAC, custom rules

Alternatives Considered

Alternative	Rejected Because
Casbin	Less flexible than OPA, limited policy expressiveness
Custom authorization	Reinventing the wheel, harder to audit
AWS IAM / Cloud providers	Non-local, vendor lock-in
Keycloak policies	Over-engineered for skeleton, auth server overhead

Consequences

Positive

Zero external dependencies (OPA runs as sidecar/library)
Declarative policy-as-code (version control, CI/CD)
Fast local evaluation (<1ms)
Standard audit format (structured JSON logs)
Foundation for compliance requirements

Negative

Rego learning curve for complex policies
OPA binary dependency (~50MB)
Policy testing requires OPA tooling
Initial setup complexity

Implementation Notes

OPA deployment: Embedded library or sidecar process
Rego policies: Stored in policies/ directory
Decision API: POST /v1/data/sea/allow with context
Audit format: JSON logs with timestamp, user, resource, decision
Default policy: Deny-by-default (fail-safe)

Success Criteria

OPA evaluates Rego policy rules
Authorization check succeeds/fails based on policy
Audit logs record all policy decisions
Decision latency <5ms for simple policies
Policy updates reload without service restart

Next Steps:

Define PRD-GOVERN-001 (requirements)
Design SDS-GOVERN-010 (service architecture)
Implement Cycle S1C (policy enforcement)