Eve library

OSHUN Studio Review and Approval Workflows Journeys and Edge Cases

Spec

Revision 1

On this page

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.