Disciplines · Decisions (ADRs)

ADR-0024: OSHUN Studio Multi-Project Operations

Project Obsidian operators increasingly coordinate execution across multiple projects simultaneously (pipelines, approvals, dependencies, delivery windows, and incident response).

Accepted · 2026-02-23
10sections4 minread
Markdown source
On this page

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.
  • 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