# ADR-0035: OSHUN Studio Review and Approval Workflows

**Status**: Accepted  
**Date**: 2026-02-23  
**Authors**: OSHUN Studio Architecture, OSHUN Web + BFF Engineering, OSHUN
Security  
**Reviewers**: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project
Obsidian Program Design

## Context and Problem Statement

Studio teams need deterministic review and approval workflows for high-impact
operations such as release gates, model promotion, narrative sign-off, timeline
cut approval, and runtime-risk waivers. Current approval behavior varies across
teams and tools, causing inconsistent decision quality and weak traceability.

Without canonical review/approval workflows, OSHUN risks:

- approval ambiguity with unclear authority boundaries
- delayed production decisions from non-deterministic escalation paths
- missing evidence for compliance and governance verification
- contradictory approvals across cross-domain dependencies

## Decision Drivers

- **Determinism**: review and approval states must transition predictably.
- **Accountability**: every decision must be attributable to explicit actors.
- **Governance**: approval evidence must be exportable and auditable.
- **Security**: policy and role constraints must gate privileged approvals.
- **Interoperability**: shared approval model across
  Yemaya/Isis/Hathor/Aja/Bellona.

## Considered Options

### Option 1: External Ticket-Only Approvals

Keep approvals in external ticketing/work-management systems.

**Pros**:

- Minimal Studio implementation effort.

**Cons**:

- Decision context split from execution surfaces.
- Weak deterministic stage and escalation semantics.

### Option 2: Domain-Specific Local Approval Models

Allow each domain to run unique review/approval rules.

**Pros**:

- Fast local optimization for domain teams.

**Cons**:

- Inconsistent decision semantics and evidence contracts.
- High integration and governance overhead.

### Option 3: Canonical Studio Review/Approval Contracts (Chosen)

Adopt one policy-aware approval model with typed review envelopes, stage graph
contracts, escalation rules, and audit evidence contracts.

**Pros**:

- Consistent approval behavior and ownership semantics.
- Strong policy/compliance posture and evidence continuity.
- Better cross-domain release confidence.

**Cons**:

- Requires governance discipline and shared contract management.

## Decision Outcome

**Chosen option**: Option 3.

Review/approval requirements:

1. **Canonical review package envelope** with actor, artifact, and dependency
   context.
2. **Approval stage graph contract** with deterministic transitions and
   escalation edges.
3. **Decision lifecycle contract** for approve/reject/request-changes outcomes.
4. **Delegation and escalation contract** with policy-gated authority transfer.
5. **Audit and governance contract** for retention, evidence, and export
   integrity.

## Normative Rules

### Canonical Review Package Contract

- Every package must include `reviewId`, `artifactRef`, `ownerId`,
  `requestedBy`, and `submittedAt`.
- Dependency references must enumerate blocking and non-blocking relationships.
- Incomplete or schema-invalid packages must be rejected before workflow start.

### Approval Stage Graph Contract

- Stage transitions must be explicit and deterministic.
- Parallel stages must define merge rules and completion semantics.
- Stage history must remain immutable and queryable.

### Decision Lifecycle Contract

- Final outcomes are constrained to `approved`, `rejected`, or
  `changes_requested`.
- Decision outcomes must capture rationale and actor attribution.
- Re-opened approvals must preserve prior decision lineage.

### Delegation and Escalation Contract

- Delegation must reference active policy scope and authorized delegate roles.
- Escalation thresholds must be explicit and policy-gated.
- Unauthorized delegation/escalation attempts must be denied and audited.

### Audit and Governance Contract

- Workflow lifecycle and policy decisions must emit structured audit events.
- Governance exports must include stage timeline and decision rationale lineage.
- Missing or delayed audit events must trigger degraded-observability warnings.

### Release Validity Contract

A review/approval release is valid only when all are true:

- review package schema validation passes
- stage-graph transition tests pass
- decision lifecycle tests pass
- delegation/escalation policy tests pass
- telemetry/audit integrity checks pass
- rollback and operational handoff are documented

## Architecture Implications

- Studio surfaces share one review/approval package and stage model.
- BFF persists stage and decision lifecycle with policy guardrails.
- Domain adapters attach artifact/dependency context to approval packages.
- Analytics pipelines measure approval throughput, denial rates, and latency.

## Acceptance Criteria (OST-00177)

`OST-00177` is complete only when:

1. ADR exists at
   `docs/adr/ADR-0041-oshun-studio-review-and-approval-workflows.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines review package, stage graph, decision lifecycle,
   delegation/escalation, audit/governance, and release-validity contracts.
4. ADR aligns with `ADR-0007` through `ADR-0034`, especially `ADR-0012`,
   `ADR-0030`, and `ADR-0034`.
5. ADR aligns with `docs/releases/v1/design/ux-principles.md`,
   `libs/oshun/analytics`, and `libs/oshun/domain-registry`.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Consequences

### Positive

- Faster, clearer, and more accountable approval decisions.
- Stronger governance and compliance evidence for release-critical operations.
- Better cross-domain synchronization for approvals and escalations.

### Negative

- Increased governance/modeling complexity for stage design.
- Requires consistent policy bundle maintenance and role hygiene.

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0036-oshun-studio-notification-center.md`
- `docs/adr/ADR-0040-oshun-studio-commenting-and-annotation-system.md`

## References

- `libs/oshun/analytics/src/types.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `docs/releases/v1/design/ux-principles.md`
- `docs/domains/yemaya/features.md`
- `docs/domains/isis/features.md`
- `docs/domains/hathor/features.md`
- `docs/domains/aja/features.md`
- `docs/domains/bellona/features.md`