# OSHUN Studio Review and Approval Workflows Journeys and Edge Cases

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

- `docs/adr/ADR-0035-oshun-studio-review-and-approval-workflows.md`
- `docs/releases/v1/specs/studio-review-and-approval-workflows-dependency-and-data-contract-map.md`

## Purpose

Define primary journeys and deterministic edge-case behavior for Studio review
and approval workflows.

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

## Personas

- Collaboration Lead
- Program Operator
- Domain Integrator
- Security Reviewer
- Compliance Auditor

## Journey Principles

1. Every review package must bind to explicit artifact and dependency context.
2. Approval stage transitions must be deterministic and auditable.
3. Delegation and escalation must remain policy-aware and attributable.
4. Final decisions must preserve rationale lineage and reopen history.

## 1. Primary Journeys

### J1. Submit Review Package

**Goal**: Submit canonical review package for an artifact with dependency
context.

**Entry**: `Studio review/approval workspace`

**Steps**:

1. Select target artifact and stage graph profile.
2. Attach blocking and non-blocking dependency references.
3. Provide owner/requester metadata and submit package.
4. Persist package and create stage execution plan.
5. Emit review package lifecycle and audit events.

**Success State**:

- Review package is persisted with complete artifact, dependency, and owner
  context.

### J2. Run Stage Assignment and Review

**Goal**: Assign and execute stage-level review actions with deterministic
routing.

**Entry**: `Submitted review package`

**Steps**:

1. Assign roles to active stage nodes.
2. Start stage execution and record in-review status.
3. Collect review notes and supporting evidence.
4. Resolve stage merge conditions for parallel paths.
5. Emit stage transition and audit events.

**Success State**:

- Stage assignments and transitions are deterministic and traceable.

### J3. Record Approval Decision

**Goal**: Record final stage decision with explicit rationale and ownership.

**Entry**: `In-review stage awaiting disposition`

**Steps**:

1. Select outcome (`approved`, `rejected`, `changes_requested`).
2. Provide rationale and decision metadata.
3. Persist decision and update stage/graph state.
4. Notify dependent stakeholders.
5. Emit decision lifecycle and governance events.

**Success State**:

- Decision is explicit, attributable, and reflected in workflow state.

### J4. Delegate or Escalate Approval Responsibility

**Goal**: Re-route blocked or high-risk approvals through authorized pathways.

**Entry**: `Stage blocked or elevated risk condition`

**Steps**:

1. Trigger delegation or escalation action.
2. Validate role and policy authorization.
3. Reassign stage responsibility and update timeline.
4. Persist delegation/escalation evidence.
5. Emit delegation/escalation lifecycle event.

**Success State**:

- Responsibility transfer is policy-compliant and auditable.

### J5. Finalize Review and Close Workflow

**Goal**: Close review workflow with governance-ready evidence package.

**Entry**: `All required stages resolved`

**Steps**:

1. Validate stage graph completion and unresolved blockers.
2. Compile decision, delegation, and evidence timeline.
3. Export governance package for retention/compliance.
4. Mark workflow as closed.
5. Emit workflow completion and audit events.

**Success State**:

- Workflow closes with complete evidence lineage and explicit outcome.

## 2. Critical Edge Cases

### E1. Missing Artifact Reference

- Trigger: package submitted without `artifactRef`.
- Required behavior: reject package and emit validation error.

### E2. Invalid Stage Graph Reference

- Trigger: package references unknown `stageGraphId`.
- Required behavior: block workflow start and request valid graph selection.

### E3. Duplicate Decision for Stage

- Trigger: two final outcomes submitted for same stage revision.
- Required behavior: quarantine duplicate and preserve canonical decision.

### E4. Decision Without Rationale

- Trigger: final decision submitted with empty rationale.
- Required behavior: reject decision and require rationale input.

### E5. Unauthorized Stage Approval Attempt

- Trigger: actor role not authorized for active stage submits decision.
- Required behavior: deny action and emit policy-denied audit event.

### E6. Delegation Without Policy ID

- Trigger: delegation/escalation action missing `policyId`.
- Required behavior: reject transfer and require policy context.

### E7. Parallel Stage Merge Deadlock

- Trigger: parallel stage merge cannot resolve due conflicting states.
- Required behavior: block closure and open deterministic conflict workflow.

### E8. Reopen Without Prior Decision History

- Trigger: reopen references missing prior decision lineage.
- Required behavior: deny reopen and flag lifecycle-integrity issue.

### E9. Governance Export Contract Failure

- Trigger: close workflow export fails schema or retention validation.
- Required behavior: hold closure and surface governance-export error.

### E10. Approval Audit Emission Failure

- Trigger: lifecycle/delegation/decision events fail emission.
- Required behavior: buffer/retry and surface degraded observability warning.

## 3. Journey-to-Surface Mapping

| Journey                                | Primary Surface           | Supporting Surfaces               |
| -------------------------------------- | ------------------------- | --------------------------------- |
| J1 Submit Review Package               | Review/Approval workflows | Domain artifact adapters          |
| J2 Run Stage Assignment and Review     | Review/Approval workflows | Stage orchestration services      |
| J3 Record Approval Decision            | Review/Approval workflows | Decision persistence services     |
| J4 Delegate or Escalate Responsibility | Review/Approval workflows | Policy and escalation controllers |
| J5 Finalize Review and Close Workflow  | Review/Approval workflows | Governance/compliance pipelines   |

## 4. Instrumentation Requirements

Required events:

- `review_approval.journey.started`
- `review_approval.journey.step.completed`
- `review_approval.journey.blocked`
- `review_approval.journey.recovered`
- `review_approval.journey.completed`

Required dimensions:

- `reviewId`, `stageId`, `decisionId`, `artifactRef`, `stageGraphId`
- `actorId`, `actorRole`, `delegationAction`, `policyId`, `outcome`
- `journeyId`, `stepId`, `latencyMs`, `errorCode`

## 5. Acceptance Criteria (OST-00179)

`OST-00179` is complete only when:

1. At least five review/approval journeys are documented.
2. At least ten deterministic edge cases are documented.
3. Journey-to-surface mapping is explicit.
4. Instrumentation requirements and dimensions are documented.
