# ADR-0042: OSHUN Studio Experimentation and Feature Flags

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

## Context and Problem Statement

Studio now operates broad cross-domain workflows and requires safe progressive
delivery. Without a canonical experimentation and feature-flag model, teams face
release risk, inconsistent rollouts, and weak attribution for experiment
outcomes.

Without unified experimentation and flag governance, OSHUN risks:

- uncontrolled or inconsistent feature activation across Studio domains
- weak confidence in experiment results due to poor exposure attribution
- elevated incident risk from all-at-once launches
- governance and compliance gaps for high-impact runtime toggles

## Decision Drivers

- **Safety**: support progressive rollout and fast rollback.
- **Attribution**: deterministic experiment exposure and outcome telemetry.
- **Governance**: policy-aware control of production-impacting flags.
- **Consistency**: one Studio-wide vocabulary and lifecycle model.
- **Operability**: rapid diagnosis of experiment and rollout regressions.

## Considered Options

### Option 1: Domain-Local Feature Flags

Allow each domain to define local flag lifecycles and exposure semantics.

**Pros**:

- Fast local implementation for individual teams.

**Cons**:

- Fragmented rollout behavior and inconsistent telemetry semantics.
- Harder cross-domain governance and incident handling.

### Option 2: Release-Only Static Config

Use only environment/static release config without dynamic flag controls.

**Pros**:

- Minimal runtime control-plane complexity.

**Cons**:

- Slow rollback and no safe progressive rollout path.
- No robust experimentation capability.

### Option 3: Canonical Studio Experimentation + Flag Control Plane (Chosen)

Adopt typed flag definitions, experiment assignment contracts, policy-aware
targeting, and deterministic exposure/outcome telemetry.

**Pros**:

- Safer progressive delivery and rollback across all Studio domains.
- Strong experiment attribution and analytics confidence.
- Better policy/audit governance for production toggles.

**Cons**:

- Requires shared contract/version governance and operational discipline.

## Decision Outcome

**Chosen option**: Option 3.

Experimentation and flag requirements:

1. **Canonical flag-definition contract** for lifecycle, owner, and risk class.
2. **Assignment and targeting contract** for cohort routing and eligibility.
3. **Exposure and outcome telemetry contract** for experiment analytics.
4. **Policy and approval contract** for sensitive/production toggles.
5. **Rollback and kill-switch contract** for rapid containment.

## Normative Rules

### Flag Definition Contract

- Every flag must include `flagKey`, `owner`, `description`, `riskClass`,
  `defaultState`, and `expiresAt`.
- Flags without owner or expiry metadata are not production-eligible.
- Deprecated flags must be removed within defined cleanup windows.

### Assignment and Targeting Contract

- Assignment dimensions must include `actorId`, `workspaceId`, `domain`,
  `releaseChannel`, and `cohortId`.
- Cohort assignment must be deterministic and reproducible.
- Targeting predicates must reject ambiguous or conflicting conditions.

### Exposure and Outcome Telemetry Contract

- Every evaluated flag must emit exposure telemetry with assignment context.
- Experiment outcomes must include success/failure and key KPI deltas.
- Missing exposure or outcome telemetry is a release-blocking defect.

### Policy and Approval Contract

- Sensitive and production-impacting flags require role + permission-tier
  checks.
- High-risk production toggles require CAB/approval evidence.
- Policy denials must be auditable and queryable.

### Rollback and Kill-Switch Contract

- All high-risk flags must support instant disable/rollback.
- Rollback actions must be idempotent and telemetry-instrumented.
- Kill-switch activations must emit governance audit events.

## Architecture Implications

- Studio workspaces consume one shared flag and experiment contract model.
- Web/BFF/data pipelines align on exposure and outcome schema.
- Policy enforcement integrates with Studio RBAC and permission tiers.
- Observability dashboards can correlate rollout state with operational health.

## Acceptance Criteria (OST-00233)

`OST-00233` is complete only when:

1. ADR exists at
   `docs/adr/ADR-0048-oshun-studio-experimentation-and-feature-flags.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines flag definition, targeting, telemetry, policy/approval, and
   rollback/kill-switch contracts.
4. ADR aligns with `ADR-0007` through `ADR-0041`, especially `ADR-0012`,
   `ADR-0040`, and `ADR-0041`.
5. ADR aligns with `docs/releases/v1/design/ux-principles.md`,
   `libs/oshun/analytics`, and `libs/oshun/domain-registry`.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Consequences

### Positive

- Safer progressive delivery and higher release confidence.
- Better experiment insight with deterministic attribution.
- Stronger operational and compliance governance for runtime toggles.

### Negative

- Additional governance overhead for flag lifecycle maintenance.
- Requires strict discipline on exposure/outcome telemetry completeness.

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0046-oshun-studio-metrics-and-analytics-instrumentation.md`
- `docs/adr/ADR-0047-oshun-studio-observability-and-operational-dashboards.md`

## References

- `libs/oshun/analytics/src/types.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `docs/releases/v1/design/ux-principles.md`
- `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`