# OSHUN Studio Audit and Compliance Surfaces Runbook

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Security + Compliance + OSHUN Web +
OSHUN BFF  
Last Updated: 2026-02-23  
Related:

- `docs/adr/ADR-0029-oshun-studio-audit-and-compliance-surfaces.md`
- `docs/releases/v1/specs/studio-audit-and-compliance-surfaces-dependency-and-data-contract-map.md`
- `docs/releases/v1/specs/studio-audit-and-compliance-surfaces-user-journeys-and-edge-cases.md`
- `apps/oshun/web/src/components/studio/StudioAuditComplianceSurfacesWorkspace.tsx`
- `apps/oshun/web/src/analytics/studioAuditComplianceSurfacesTelemetry.ts`

## Purpose

Define operational ownership, SLOs, incident playbooks, and escalation paths for
Studio audit and compliance surfaces governance workflows.

This document is the execution artifact for `OST-00136`.

## 1. Ownership Model

| Surface                                | Primary Owner              | Backup Owner        | Dependencies                        |
| -------------------------------------- | -------------------------- | ------------------- | ----------------------------------- |
| Audit/compliance route                 | OSHUN Web                  | Platform Web        | route + analytics contracts         |
| Evidence ingestion and query contracts | Data Platform + BFF        | Security            | evidence pipeline + query APIs      |
| Compliance review workflow             | Compliance + Security      | Program Ops         | review workflow services            |
| Exception and attestation actions      | Compliance                 | Security governance | exception registry + policy rules   |
| Retention and archival controls        | Data Platform + Compliance | Legal               | retention policies + archival tiers |

## 2. Core SLOs

| Metric                              | Target                 | Alert Threshold                              |
| ----------------------------------- | ---------------------- | -------------------------------------------- |
| Audit/compliance flow success rate  | >= 99.0%               | < 98.0% over 15 min                          |
| Evidence query integrity            | 100% deterministic     | any inconsistent query for identical filters |
| Compliance decision correctness     | 100% policy-consistent | any unauthorized approve                     |
| Audit/compliance flow p95 latency   | <= 2200ms              | > 3200ms over 15 min                         |
| Audit/compliance event completeness | >= 99.5%               | < 99.0% over 15 min                          |

## 3. Operational Playbooks

### 3.1 Evidence Query Execution Failures

Trigger: repeated `AUDIT_EVIDENCE_QUERY_EXECUTION_FAILED` outcomes.

Actions:

1. Validate evidence index and query-service health.
2. Inspect trace-correlation and pagination integrity.
3. Re-run query with diagnostic tracing.
4. Block compliance exports until integrity recovers.

### 3.2 Compliance Review Decision Failures

Trigger: repeated `AUDIT_COMPLIANCE_REVIEW_DECISION_FAILED` outcomes.

Actions:

1. Validate evidence linkage and review policy contracts.
2. Inspect reviewer role/permission payloads.
3. Re-run review workflow in controlled mode.
4. Preserve case state until deterministic decision pass.

### 3.3 Retention Policy Verification Failures

Trigger: repeated `AUDIT_RETENTION_POLICY_VERIFICATION_FAILED` outcomes.

Actions:

1. Validate retention policy version and evidence category mappings.
2. Check archival tier assignment and lifecycle rules.
3. Verify legal-hold conflict handling.
4. Block retention policy promotion until validation passes.

### 3.4 Policy Denial Spike

Trigger: unexpected increase in `ROLE_POLICY_DENIED` outcomes.

Actions:

1. Compare flow allowlists with active entitlement contracts.
2. Validate role payload and policy version changes.
3. Apply policy hotfix or rollback drifted policy bundle.
4. Confirm deny-rate normalization after mitigation.

### 3.5 Telemetry and Audit Degradation

Trigger: missing or delayed audit/compliance telemetry events.

Actions:

1. Validate analytics sink health and ingestion queue depth.
2. Enable degraded-observability warning in workspace.
3. Reconcile missed events from buffered traces.
4. Confirm event completeness and SLO recovery.

## 4. Release Checklist

- [ ] Validate `/studio/audit-compliance-surfaces` renders and executes required
      flows.
- [ ] Validate optimistic, error, and retry behavior for each flow.
- [ ] Validate role-policy allow/deny behavior.
- [ ] Validate telemetry/audit emissions and SLO panel updates.
- [ ] Validate integration/e2e/accessibility evidence artifacts.

## 5. Incident Communication Templates

### Incident Start

```
[P{severity}] Studio Audit and Compliance Surfaces Incident
Detected: {timestamp}
Impact: {evidence query | compliance review | retention verification impact}
Suspected cause: {evidence pipeline drift | workflow policy issue | retention mismatch}
Owner: {on-call}
```

### Incident Update

```
[P{severity}] Studio Audit and Compliance Surfaces Update
Time: {timestamp}
Mitigation: {rollback | hotfix | degraded mode}
Affected flows: {evidenceQueryExecution | complianceReviewDecision | retentionPolicyVerification}
ETA: {time}
```

### Incident Resolved

```
[P{severity}] Studio Audit and Compliance Surfaces Incident Resolved
Resolved: {timestamp}
Root cause: {description}
Fix: {release/hotfix id}
Validation: {tests + telemetry checks}
Postmortem: {link}
```

## 6. Escalation Paths

| Area                              | Primary Channel        | Escalate To                   |
| --------------------------------- | ---------------------- | ----------------------------- |
| Web runtime and workspace         | `#oshun-web`           | Platform on-call              |
| Evidence ingestion/query platform | `#oshun-data-platform` | Data platform lead            |
| Compliance review workflows       | `#oshun-compliance`    | Compliance lead               |
| Policy and permissions            | `#oshun-security`      | Security lead                 |
| Retention/legal hold governance   | `#oshun-legal`         | Legal + compliance leadership |

## 7. Acceptance Criteria (OST-00136)

`OST-00136` is complete only when:

1. Ownership and decision authority are documented.
2. Audit/compliance surface SLOs and alert thresholds are documented.
3. At least five playbooks are documented for major failure modes.
4. Release checklist, communication templates, and escalation paths exist.
