Disciplines · Decisions (ADRs)

ADR-0035: OSHUN Studio Review and Approval Workflows

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.

Accepted · 2026-02-23
10sections4 minread
Markdown source
On this page

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.
  • 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