# ADR-0024: OSHUN Studio Multi-Project Operations

**Status**: Accepted  
**Date**: 2026-02-23  
**Authors**: OSHUN Studio Architecture, OSHUN Web Engineering, OSHUN BFF  
**Reviewers**: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project
Obsidian Program Design

## Context and Problem Statement

Project Obsidian operators increasingly coordinate execution across multiple
projects simultaneously (pipelines, approvals, dependencies, delivery windows,
and incident response). Current Studio surfaces optimize for single-project
workflows and need explicit multi-project operating contracts.

Without a governed multi-project operations model, Studio risks:

- inconsistent cross-project dependency tracking and decision ordering
- conflicting changes promoted across projects without readiness gates
- weak rollback orchestration when one project fails and others continue
- fragmented auditability for cross-project governance decisions

## Decision Drivers

- **Operational coherence**: one model for planning and executing cross-project
  operations.
- **Release safety**: deterministic readiness checks and staged promotions.
- **Failure containment**: explicit rollback and dependency impact controls.
- **Governance traceability**: auditable cross-project approvals and outcomes.
- **Cross-domain interoperability**: consistent behavior for Yemaya, Isis,
  Hathor, Aja, and Bellona.

## Considered Options

### Option 1: Independent Per-Project Operations Only

Treat each project independently and rely on manual coordination.

**Pros**:

- Low implementation complexity.

**Cons**:

- High coordination overhead and drift.
- No deterministic cross-project readiness guarantees.

### Option 2: Loose Aggregation Dashboard

Aggregate project signals visually but keep execution contracts per project.

**Pros**:

- Better visibility with moderate implementation cost.

**Cons**:

- Execution semantics remain inconsistent.
- Rollback and dependency orchestration remain fragile.

### Option 3: Governed Multi-Project Operations Contract Model (Chosen)

Adopt canonical multi-project operation envelopes, dependency policies, staged
execution semantics, and rollback orchestration.

**Pros**:

- Deterministic cross-project planning and execution.
- Stronger release safety and rollback coordination.
- Clear audit/telemetry evidence for governance.

**Cons**:

- Higher upfront schema and policy governance complexity.

## Decision Outcome

**Chosen option**: Option 3.

Multi-project operations requirements:

1. **Operation envelope contract** covering program, project set, dependency
   graph, and release stage metadata.
2. **Readiness and policy contract** for gate checks, approvals, and deny
   outcomes.
3. **Execution contract** for staged run, pause, continue, and abort semantics.
4. **Rollback orchestration contract** for dependency-aware recovery plans.
5. **Release governance** with validation, approval, telemetry/audit, and
   rollback references.

## Normative Rules

### Multi-Project Operation Envelope Contract

- Every operation must include `programId`, `operationId`, and at least two
  project targets.
- Operation envelope must include dependency graph and execution stage metadata.
- Project targets must be unique and version-addressable.

### Readiness and Policy Contract

- Promotion is blocked unless all required project readiness gates pass.
- Policy-denied actions must not mutate operation stage state.
- Approval quorum rules must be explicit and versioned.

### Execution Contract

- Execution supports deterministic transitions:
  `planned -> running -> paused/blocked -> completed/aborted`.
- Stage transitions require persisted evidence and actor attribution.
- Partial project failures must preserve overall operation integrity state.

### Rollback Orchestration Contract

- Rollback plans must be dependency aware and ordered.
- Failed rollback attempts must retain last confirmed safe checkpoint.
- Rollback actions must emit explicit recovery evidence.

### Release Validity Contract

A multi-project operations release is valid only when all are true:

- operation envelope validation checks pass
- readiness/policy checks pass
- staged execution and abort/recovery semantics pass
- telemetry/audit records are complete
- rollback strategy is documented

## Architecture Implications

- Studio web surfaces expose multi-project operation planning and staged
  execution controls.
- BFF coordinates readiness checks and authoritative operation-state
  transitions.
- Navigation and context systems preserve operation origin and project stack
  context.
- Analytics pipelines track operation requests, transitions, failures,
  recoveries, and approvals.

## Acceptance Criteria (OST-00089)

`OST-00089` is complete only when:

1. ADR exists at `docs/adr/ADR-0030-oshun-studio-multi-project-operations.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines operation envelope, readiness/policy, execution,
   rollback-orchestration, and release-validity contracts.
4. ADR aligns with `ADR-0007` through `ADR-0023`.
5. ADR aligns with `docs/releases/v1/design/ux-principles.md`,
   `apps/oshun/web/src/navigation/routes.ts`, and `libs/oshun/domain-registry`.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Consequences

### Positive

- Safer and more predictable cross-project execution governance.
- Better failure containment and coordinated rollback behavior.
- Stronger operational observability and compliance evidence.

### Negative

- Additional contract/governance overhead for program operations.
- Requires disciplined multi-project dependency modeling.

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0014-oshun-web-and-pwa-strategy.md`
- `docs/adr/ADR-0015-deep-linking-and-cross-domain-routing.md`
- `docs/adr/ADR-0016-shared-identity-and-cross-domain-session-model.md`
- `docs/adr/ADR-0017-offline-caching-and-sync-strategy.md`
- `docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0019-oshun-studio-information-architecture.md`
- `docs/adr/ADR-0026-oshun-studio-navigation-and-command-surfaces.md`
- `docs/adr/ADR-0027-oshun-studio-search-and-global-discovery.md`
- `docs/adr/ADR-0028-oshun-studio-cross-domain-entity-model.md`
- `docs/adr/ADR-0029-oshun-studio-workspace-context-switching.md`

## References

- `docs/releases/v1/design/ux-principles.md`
- `apps/oshun/web/src/navigation/routes.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `docs/domains/yemaya/features.md`
- `docs/domains/isis/features.md`
- `docs/domains/hathor/features.md`
- `docs/domains/aja/features.md`
- `docs/domains/bellona/features.md`