# OSHUN V1 Standalone Frontend Deprecation and Sunset Criteria

Status: Accepted v1.0  
Date: March 23, 2026  
Owners: OSHUN Product, OSHUN Engineering, Domain Leads, Support/Ops  
Related:

- `docs/releases/v1/specs/domain-service-consolidation-strategy.md`
- `docs/releases/v1/scope/domain-service-routing-and-discovery-rules.md`
- `docs/releases/v1/specs/program-charter.md`
- `docs/releases/v1/specs/web-app-admin-v1-prd.md`
- `docs/releases/v1/scope/mvp-scope.md`
- `docs/releases/v1/specs/todos.md`

---

## 1. Purpose

This document defines when a standalone domain web or mobile frontend may be
deprecated, redirected, delisted, or retired because the unified OSHUN shell now
owns the overlapping user journey.

It exists to close `V1-ARCH-086`. The consolidation strategy already established
that standalone domain frontends are not canonical shell surfaces. What it did
not yet define was:

- how to distinguish a true shell-superseded frontend from a specialist product
- what evidence is required before a legacy web or mobile surface can be
  deprecated
- which current frontend trees are actual sunset candidates versus retained
  specialist surfaces

This document closes `V1-ARCH-086`. It does **not** close `V1-ARCH-087` through
`V1-ARCH-089`.

## 2. Repo-Informed Current State

The current repository shows all of the following:

- `apps/oshun/web` and `apps/oshun/mobile` are the canonical unified customer
  shell surfaces.
- standalone customer-facing or domain-native frontend trees still exist for
  Tara, Veritas, Nyx, Iris, Lilith, and Metis.
- Tara, Veritas, and Nyx each still have customer web/mobile or PWA frontends
  that overlap with shell-facing journeys.
- Nyx also has specialist immersive clients (`apps/nyx/star-map`,
  `apps/nyx/ar-sky`, `apps/nyx/vr-planetarium`) whose modality is broader than
  the shell's current scope.
- Iris, Lilith, and Metis include standalone desktop, admin, dashboard, or
  broader domain-native experiences that are not automatically superseded by a
  customer shell.
- `apps/iris/web` is present as a directory in the tree but does not currently
  expose a `package.json`, so it must be treated as inventory residue rather
  than an approved deployable frontend until separately clarified.

The governing problem is not "remove all standalone apps." The governing problem
is deciding which overlapping frontends should stay as specialist products and
which should be formally migrated into the shell.

## 3. Governing Decision

For OSHUN V1, a standalone frontend may be sunset only when the shell is the
approved canonical surface for the same user, same job-to-be-done, and same
launch-critical journey class.

The following rules are mandatory:

1. Customer-facing overlap is the only scope eligible for shell-driven sunset.
   Desktop, admin, dashboard, XR, operator, creator, enterprise, and substrate
   surfaces are not sunset candidates merely because the shell exists.
2. A frontend is `superseded by the shell` only when OSHUN owns the relevant
   journey end to end through shell UX, shell routing, shell auth/session, and
   BFF-mediated backend contracts.
3. No standalone frontend may be deprecated on aesthetics or org preference
   alone. Deprecation requires verified journey parity, migration evidence, and
   support readiness.
4. If a standalone frontend still provides a unique modality or specialist
   workflow that the shell does not intend to own, it remains a retained
   specialist surface rather than a sunset candidate.
5. Standalone mobile surfaces require a stricter bar than web because store
   listings, installed versions, push permissions, and offline data make
   retirement harder to reverse safely.

## 4. Lifecycle States

Every standalone frontend in scope must be assigned one of the following states:

| Lifecycle state       | Meaning                                                                                                           |
| --------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `specialist-retained` | Product remains outside shell supersession scope and is not on a shell-driven retirement path.                    |
| `parallel-migration`  | Frontend overlaps with the shell and may continue temporarily while shell parity and migration mature.            |
| `redirect-ready`      | Sunset gates are satisfied; traffic may be redirected or store delisting may begin after notice windows complete. |
| `sunset-approved`     | Owners approved shutdown/delisting/retirement and rollback conditions are documented.                             |
| `retired`             | Frontend is no longer a supported entry point; redirects, delisting, or archival controls are in place.           |
| `inventory-residue`   | Repo path exists but is not yet a clearly supported deployable product; classify before any sunset decision.      |

State transitions are one-way except for rollback from `redirect-ready` or
`sunset-approved` back to `parallel-migration` when migration health degrades.

## 5. Minimum Sunset Gates

All of the following must be true before a `parallel-migration` frontend can
move to `redirect-ready`.

### 5.1 Shared Gates for Web and Mobile

1. The overlapping journey set is written explicitly and approved by the domain
   lead and OSHUN product lead.
2. OSHUN owns 100% of launch-blocking overlapping journeys and at least 95% of
   overlapping session volume from the most recent 28-day measurement window,
   unless an explicit written exception is approved.
3. Shell flows for those journeys use canonical shell auth, deep links, BFF
   routing, save/progress state, notifications where applicable, and analytics.
4. Data continuity is preserved for overlapping journeys: bookmarks, progress,
   preferences, entitlements, and recent activity cannot silently reset during
   migration.
5. Relevant automation for the shell-owned replacement path is present and
   passing: lint, typecheck, affected tests, and browser/mobile end-to-end
   coverage for the migrated journeys.
6. Migration telemetry exists for legacy entry, shell entry, redirect success,
   deep-link success, auth handoff, and critical failure states.
7. No unresolved P0 or P1 defect remains on the shell replacement path and no
   unresolved legal, privacy, policy, or support blocker remains for the
   migrated journeys.
8. Support, incident, and rollback runbooks are updated and on-call ownership is
   explicit.

### 5.2 Web-Specific Gates

Before a standalone web surface can be redirected or retired:

1. Legacy routes that map to shell-owned journeys have verified redirect
   destinations or explanatory landing pages.
2. SEO, canonical metadata, and public-link behavior are updated so search and
   share traffic does not land on broken or contradictory surfaces.
3. Anonymous and authenticated traffic both have deterministic handling for the
   redirect path.
4. Web Playwright coverage verifies legacy-to-shell redirect behavior,
   authenticated handoff, and degraded-state behavior.
5. A minimum 30-day notice window has been provided unless the web surface was
   internal-only or never publicly launched.

### 5.3 Mobile-Specific Gates

Before a standalone mobile app can be delisted or retired:

1. Universal Links, App Links, and in-app deep links route users into the shell
   for all superseded journeys.
2. Push-notification destinations, notification preferences, and permission
   state are migrated or intentionally reset with explicit user communication.
3. Offline or downloaded assets required by the overlapping journeys have a
   shell replacement strategy or an approved exception.
4. Mobile end-to-end automation verifies notification routing, auth/session
   continuity, reinstall/upgrade behavior, and offline/retry behavior where the
   legacy app previously supported them.
5. At least one released legacy-app version contains the deprecation notice and
   shell migration path before store delisting.
6. A minimum 45-day notice window has elapsed between first in-app deprecation
   notice and store delisting, unless the app never reached public launch.

## 6. Sunset Approval Packet

No frontend may move from `redirect-ready` to `sunset-approved` until a written
approval packet exists containing all of the following:

- scoped journey map showing what is superseded and what remains out of scope
- telemetry summary for the overlap period
- support and incident rollback plan
- redirect or delisting execution date
- customer communication plan
- owner signoff from domain lead, OSHUN product, engineering, and support/ops

## 7. Current Frontend Classification

The table below is the canonical March 23, 2026 classification for the
standalone domain frontend trees currently visible in this repository.

| Frontend path             | Current lifecycle state | Shell supersession posture                                                      | Reasoning                                                                                                                                                |
| ------------------------- | ----------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apps/tara/web`           | `parallel-migration`    | sunset candidate for overlapping customer meditation journeys                   | Tara README explicitly says OSHUN exposes only the highest-value Tara entry points today, so retirement is possible only after parity on those journeys. |
| `apps/tara/mobile`        | `parallel-migration`    | sunset candidate for overlapping customer meditation journeys                   | Mobile overlap exists, but offline audio, continuity, and mobile notification migration must be proven before delisting.                                 |
| `apps/veritas/web`        | `parallel-migration`    | sunset candidate for overlapping customer reading and claim-inspection journeys | Veritas shell scope is intentionally narrower than the full newsroom platform, so only overlapping shell-owned user journeys are sunsetable.             |
| `apps/veritas/mobile`     | `parallel-migration`    | sunset candidate for overlapping customer reading and alert journeys            | Same posture as web, with extra mobile gating for notifications, saved state, and install-base migration.                                                |
| `apps/nyx/mobile`         | `parallel-migration`    | sunset candidate only for shell-owned nightly-highlight and continuity journeys | MVP docs still allow Nyx to remain an explicit module; sunset depends on shell/mobile parity for saved objects, reminders, and deep-link continuity.     |
| `apps/nyx/star-map`       | `specialist-retained`   | not superseded by default                                                       | Star-map is a specialist immersive/observatory surface, not a generic shell replacement target.                                                          |
| `apps/nyx/ar-sky`         | `specialist-retained`   | not superseded by default                                                       | AR modality is a domain-native specialist experience outside current shell supersession scope.                                                           |
| `apps/nyx/vr-planetarium` | `specialist-retained`   | not superseded by default                                                       | VR modality is a specialist experience and remains independent unless a separate accepted retirement plan exists.                                        |
| `apps/iris/dashboard`     | `specialist-retained`   | not a customer-shell sunset candidate                                           | Iris is a substrate platform with dashboard/operator concerns broader than shell customer journeys.                                                      |
| `apps/iris/web`           | `inventory-residue`     | classify separately before any retirement decision                              | Repo path exists without a `package.json`, so it is not currently treated as a verified deployable standalone frontend.                                  |
| `apps/iris/mobile`        | `specialist-retained`   | not a customer-shell sunset candidate                                           | Iris mobile is part of a broader assistant platform across device classes, not just a shell-overlap surface.                                             |
| `apps/iris/desktop`       | `specialist-retained`   | not a customer-shell sunset candidate                                           | Desktop is out of scope for shell-driven customer web/mobile retirement.                                                                                 |
| `apps/lilith/web`         | `specialist-retained`   | not a customer-shell sunset candidate                                           | Lilith remains a broader consciousness-experience platform whose standalone UI is not replaced merely by OSHUN customer shell parity.                    |
| `apps/lilith/mobile`      | `specialist-retained`   | not a customer-shell sunset candidate                                           | Same posture as Lilith web, with additional modality and device-capability scope outside shell overlap.                                                  |
| `apps/lilith/desktop`     | `specialist-retained`   | not a customer-shell sunset candidate                                           | Desktop is outside the web/mobile supersession problem.                                                                                                  |
| `apps/metis/web`          | `parallel-migration`    | potential sunset candidate for learner-facing shell-owned journeys only         | Metis web overlaps future shell learning journeys, but the charter and Metis audit show shell integration is still incomplete.                           |
| `apps/metis/admin`        | `specialist-retained`   | not a customer-shell sunset candidate                                           | Admin surfaces belong to the canonical operator model, not the customer shell. Retire only if Oshun admin fully absorbs them.                            |

## 8. Domain-Specific Interpretation Rules

### 8.1 Tara

Tara web/mobile may be sunset only for the journeys OSHUN explicitly intends to
own:

- launch session
- resume session
- save/favorite
- course progress summary
- session-audio continuity

Full Tara wellness-product breadth is not a prerequisite for OSHUN, but any
overlapping Tara journey that remains critical and unsupported in shell blocks
sunset.

### 8.2 Veritas

Veritas web/mobile may be sunset only for shell-owned reading journeys such as:

- trending feed entry
- claim inspection
- continue reading
- save/follow behavior
- alert and notification continuity for shell-owned reading flows

Newsroom operations, regional media tooling, monetization, and broader editorial
systems are not customer-shell sunset targets.

### 8.3 Nyx

Only the shell-owned Nyx continuity layer is sunset-eligible:

- nightly highlights
- shell-owned event discovery
- saved objects
- reminder continuity
- shell-routed exploration entry

Immersive observatory clients remain specialist unless a separate shell product
decision explicitly absorbs them.

### 8.4 Iris and Lilith

Iris and Lilith are substrate or broader domain-native products. Their current
standalone UIs are not subject to shell-driven deprecation unless OSHUN later
defines a specific overlapping customer journey set and explicitly accepts the
migration cost.

### 8.5 Metis

Metis learner-facing web journeys may become sunset candidates once the shell
and BFF-backed Metis adapter own those journeys end to end. Metis admin is not
part of this customer-shell sunset policy; it belongs to the operator-surface
convergence problem defined by the charter and admin PRD.

## 9. Acceptance Record

The OSHUN V1 program accepts the following sunset policy:

- only overlapping customer web/mobile journeys are eligible for shell-driven
  retirement
- specialist, desktop, immersive, admin, and substrate frontends are retained
  unless a separate supersession decision exists
- sunset requires measurable parity, migration evidence, automation, support
  readiness, and notice windows
- Tara, Veritas, Nyx mobile, and Metis web are the current `parallel-migration`
  surfaces; the rest are retained specialist surfaces or inventory residue

This acceptance closes `V1-ARCH-086`.
