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.mddocs/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#
- Multi-project operations must use explicit dependency and readiness gates.
- Stage transitions must be deterministic and auditable.
- Partial failures must preserve global operation integrity.
- 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:
- Select program and project set.
- Define dependency graph and release window.
- Validate operation envelope and project uniqueness.
- Save/publish operation baseline.
- 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:
- Run per-project readiness gates.
- Resolve failed or blocked gates.
- Re-evaluate readiness status.
- Start operation stage transition.
- Confirm
runningstate with evidence.
Success State:
- Operation enters
runningstate 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:
- Trigger pause due to risk or dependency issue.
- Confirm deterministic stage transition to
paused. - Remediate identified issue.
- Resume operation with updated evidence.
- 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:
- Identify failed project nodes and impacted dependencies.
- Move operation to
blockedstate. - Apply targeted remediations.
- Re-run dependency and readiness checks.
- 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:
- Select validated rollback checkpoint.
- Execute dependency-aware rollback order.
- Confirm recovery state by project.
- Record audit and telemetry evidence.
- 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
projectIdentries. - 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
blockedand 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.startedmulti_project_operations.journey.step.completedmulti_project_operations.journey.blockedmulti_project_operations.journey.recoveredmulti_project_operations.journey.completed
Required dimensions:
programId,operationId,projectIdsjourneyId,stepId,stage,checkpointIdactorRole,outcome,latencyMs,errorCode
5. Acceptance Criteria (OST-00091)#
OST-00091 is complete only when:
- At least five multi-project operation journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.