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.mddocs/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#
- Every review package must bind to explicit artifact and dependency context.
- Approval stage transitions must be deterministic and auditable.
- Delegation and escalation must remain policy-aware and attributable.
- 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:
- Select target artifact and stage graph profile.
- Attach blocking and non-blocking dependency references.
- Provide owner/requester metadata and submit package.
- Persist package and create stage execution plan.
- 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:
- Assign roles to active stage nodes.
- Start stage execution and record in-review status.
- Collect review notes and supporting evidence.
- Resolve stage merge conditions for parallel paths.
- 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:
- Select outcome (
approved,rejected,changes_requested). - Provide rationale and decision metadata.
- Persist decision and update stage/graph state.
- Notify dependent stakeholders.
- 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:
- Trigger delegation or escalation action.
- Validate role and policy authorization.
- Reassign stage responsibility and update timeline.
- Persist delegation/escalation evidence.
- 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:
- Validate stage graph completion and unresolved blockers.
- Compile decision, delegation, and evidence timeline.
- Export governance package for retention/compliance.
- Mark workflow as closed.
- 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.startedreview_approval.journey.step.completedreview_approval.journey.blockedreview_approval.journey.recoveredreview_approval.journey.completed
Required dimensions:
reviewId,stageId,decisionId,artifactRef,stageGraphIdactorId,actorRole,delegationAction,policyId,outcomejourneyId,stepId,latencyMs,errorCode
5. Acceptance Criteria (OST-00179)#
OST-00179 is complete only when:
- At least five review/approval journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.