# OSHUN Studio Multi-Project Operations Journeys and Edge Cases

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

- `docs/adr/ADR-0024-oshun-studio-multi-project-operations.md`
- `docs/releases/v1/specs/studio-multi-project-operations-dependency-and-data-contract-map.md`

## Purpose

Define primary journeys and deterministic edge-case behavior for Studio
multi-project operations governance.

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

## Personas

- Program Operator
- Release Coordinator
- Domain Integrator
- Security Reviewer
- Reliability Engineer

## Journey Principles

1. Multi-project operations must use explicit dependency and readiness gates.
2. Stage transitions must be deterministic and auditable.
3. Partial failures must preserve global operation integrity.
4. Recovery and rollback paths must be explicit and reversible.

## 1. Primary Journeys

### J1. Multi-Project Operation Planning and Baseline Publish

**Goal**: Create and publish a baseline operation plan across multiple projects.

**Entry**: `Studio -> Multi-Project Operations -> Planning Console`

**Steps**:

1. Select program and project set.
2. Define dependency graph and release window.
3. Validate operation envelope and project uniqueness.
4. Save/publish operation baseline.
5. Attach rollback checkpoint reference.

**Success State**:

- Multi-project operation baseline is published and ready for stage execution.

### J2. Readiness Gate Evaluation and Stage Start

**Goal**: Evaluate readiness gates and start operation execution.

**Entry**: `Operation plan -> Start`

**Steps**:

1. Run per-project readiness gates.
2. Resolve failed or blocked gates.
3. Re-evaluate readiness status.
4. Start operation stage transition.
5. Confirm `running` state with evidence.

**Success State**:

- Operation enters `running` state with all required readiness gates passing.

### J3. Coordinated Pause/Resume During Active Execution

**Goal**: Pause and resume multi-project execution safely.

**Entry**: `Operation execution controls`

**Steps**:

1. Trigger pause due to risk or dependency issue.
2. Confirm deterministic stage transition to `paused`.
3. Remediate identified issue.
4. Resume operation with updated evidence.
5. Confirm stage continuity and dependency health.

**Success State**:

- Operation resumes safely with preserved stage continuity.

### J4. Partial Failure Containment and Recovery

**Goal**: Contain and recover when one or more project executions fail.

**Entry**: `Operation alert`

**Steps**:

1. Identify failed project nodes and impacted dependencies.
2. Move operation to `blocked` state.
3. Apply targeted remediations.
4. Re-run dependency and readiness checks.
5. Resume or abort based on outcomes.

**Success State**:

- Failure is contained and operation transitions deterministically.

### J5. Dependency-Aware Rollback and Incident Closure

**Goal**: Roll back operation safely and close incident with evidence.

**Entry**: `Abort/rollback decision`

**Steps**:

1. Select validated rollback checkpoint.
2. Execute dependency-aware rollback order.
3. Confirm recovery state by project.
4. Record audit and telemetry evidence.
5. Publish incident closure and prevention actions.

**Success State**:

- All impacted projects are restored to last known safe state.

## 2. Critical Edge Cases

### E1. Duplicate Project in Operation Envelope

- Trigger: operation envelope includes duplicate `projectId` entries.
- Required behavior: fail validation and block plan publish.

### E2. Missing Dependency Graph Version

- Trigger: operation plan omits dependency graph metadata.
- Required behavior: block stage execution until metadata is provided.

### E3. Readiness Gate Drift

- Trigger: gate status changes between evaluation and stage commit.
- Required behavior: cancel transition and require re-evaluation.

### E4. Unauthorized Stage Transition

- Trigger: actor lacks permission for start/pause/abort transitions.
- Required behavior: deny action and preserve current stage state.

### E5. Inconsistent Stage Transition Request

- Trigger: invalid stage transition (for example `planned -> completed`).
- Required behavior: reject transition with explicit stage-rule diagnostics.

### E6. Partial Project Failure Cascade

- Trigger: one project failure impacts dependent projects.
- Required behavior: move operation to `blocked` and quarantine impacted nodes.

### E7. Rollback Checkpoint Missing

- Trigger: rollback requested without certified checkpoint.
- Required behavior: block rollback and escalate operator action.

### E8. Rollback Order Violation

- Trigger: rollback order conflicts with dependency graph.
- Required behavior: deny execution and recompute valid order.

### E9. Telemetry/Audit Emission Failure

- Trigger: operation events fail to emit.
- Required behavior: buffer/retry and expose degraded observability warning.

### E10. Context Loss Across Project Stack

- Trigger: active operation loses project-stack context after navigation.
- Required behavior: restore from persisted operation context or safe fallback.

## 3. Journey-to-Surface Mapping

| Journey                                                  | Primary Surface          | Supporting Surfaces      |
| -------------------------------------------------------- | ------------------------ | ------------------------ |
| J1 Multi-Project Operation Planning and Baseline Publish | Multi-Project Operations | Governance               |
| J2 Readiness Gate Evaluation and Stage Start             | Multi-Project Operations | Review & Approvals       |
| J3 Coordinated Pause/Resume During Active Execution      | Multi-Project Operations | Observability            |
| J4 Partial Failure Containment and Recovery              | Observability            | Multi-Project Operations |
| J5 Dependency-Aware Rollback and Incident Closure        | Multi-Project Operations | Incident Management      |

## 4. Instrumentation Requirements

Required events:

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

Required dimensions:

- `programId`, `operationId`, `projectIds`
- `journeyId`, `stepId`, `stage`, `checkpointId`
- `actorRole`, `outcome`, `latencyMs`, `errorCode`

## 5. Acceptance Criteria (OST-00091)

`OST-00091` is complete only when:

1. At least five multi-project operation 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.
