# ADR-0062: OSHUN Assistant-Led Continuity Journey Model

**Status**: Accepted  
**Date**: 2026-03-24  
**Authors**: OSHUN Product, OSHUN Design, OSHUN Web Engineering  
**Reviewers**: Shell, Iris, and Assistant leads  
**Supersedes**: N/A  
**Superseded by**: N/A

## Context and Problem Statement

The PRD already defines the consumer assistant flow at a system level and the
web shell relationship model already defines `Assistant` as the global
continuity layer rather than a peer structural route.

The codebase also already had important assistant building blocks:

- a shell-local assistant engine, intent model, action router, and response
  formatter under `libs/oshun/shell-assistant/*`
- a global assistant invocation event under
  `apps/oshun/web/src/navigation/assistant-entry.ts`
- a global assistant UI under
  `apps/oshun/web/src/components/assistant/AssistantPanel.tsx`
- cross-domain assistant summaries, domain switching, and saved assistant
  excerpts already present in shell concepts and Library data

But there was still no canonical shell-level answer to the question:

> How should the assistant carry the user's current surface into the right next
> destination without losing context?

That gap mattered because `Assistant` was already treated as a continuity layer
in shell IA, but not yet as an explicit cross-domain journey with bounded
stages, typed handoffs, or a concrete UI that showed how continuity should move
from invocation to handback and preservation.

## Decision Drivers

- **Assistant must act as continuity, not detached chat**: the shell IA already
  says assistant inherits context and hands users back into product surfaces.
- **Context transfer must be explicit**: the invoking surface and entry source
  should survive assistant open and the opening turn.
- **Cross-domain answers need structure**: overview, grounding, and next-step
  help should resolve into real handoffs, not open-ended conversation.
- **Preservation matters**: assistant exchanges should be able to become durable
  Library excerpts or Activity follow-up anchors.
- **Implementation leverage matters**: docs, QA, web, and later mobile or Iris
  work need one typed continuity contract.

## Considered Options

### Option 1: Leave assistant continuity implicit in shell IA and assistant code

**Description**: keep the assistant as a global layer and rely on the existing
assistant engine, UI, and navigation rules without publishing a dedicated
journey model.

**Pros**:

- Lowest implementation cost.
- Reuses the current assistant surface directly.

**Cons**:

- Leaves the assistant continuity promise untyped and untestable.
- Gives no normative stage order for web, QA, or future mobile work.
- Makes handback and preservation behavior easy to regress into generic chat.

### Option 2: Treat assistant continuity as a Library-only preservation feature

**Description**: model assistant continuity only through saved assistant
excerpts and transcript preservation, without defining the invocation and
handoff stages that precede preservation.

**Pros**:

- Builds on existing Library concepts.
- Keeps the durable-save story simple.

**Cons**:

- Misses the invocation and handback behaviors that make assistant a continuity
  layer in the first place.
- Treats assistant continuity as archival rather than active orchestration.
- Does not explain how current-surface context should guide the live exchange.

### Option 3: Publish an explicit assistant-led continuity journey model and render it inside the global assistant panel (Chosen)

**Description**: define one four-stage shell journey from current-surface
invocation through bounded request framing, memory-aware and grounding-ready
answer shaping, real destination handback, and durable preservation; publish it
in shared navigation contracts; map it into web assistant actions; render it in
the assistant panel; and preserve the invocation source from shell entry.

**Pros**:

- Makes the assistant continuity promise executable in one typed shell model.
- Turns `Assistant` from a general chat affordance into a visible continuity
  workflow.
- Preserves invoking-surface context while still resolving into product routes.
- Produces one reusable contract for docs, QA, web, and later mobile work.

**Cons**:

- Adds another cross-domain journey model that later work must respect.
- Requires discipline so assistant-led continuity stays distinct from daypart,
  research-to-practice, story-to-source, and sky-to-text journeys.

## Decision Outcome

**Chosen option**: Option 3.

### Normative Rule

OSHUN owns one canonical `Assistant-led continuity` shell journey.

Its question is:

> How should the assistant carry the user from this surface into the right next
> destination without losing context?

That journey is not complete when the assistant merely opens. It is complete
when the shell has preserved the invoking context, bounded the need, shaped a
handoff-ready brief, and exposed one durable continuity trace after the user is
handed back into the product.

### Stage Rule

The normative stage order is:

1. `Inherit the current context`
2. `Bound the need`
3. `Ground and shape the answer`
4. `Hand back and preserve`

### Stage Semantics

#### 1. Inherit the current context

Assistant is the canonical entry surface, but it must begin from the current
shell or domain context rather than a blank conversation state.

This stage exists to preserve:

- the invoking surface
- the entry source
- the live screen or task context that motivated the assistant open

#### 2. Bound the need

Once assistant is open, the shell should quickly turn the interaction into one
bounded continuity request such as:

- overview or reorientation
- next-best-move guidance
- grounding request
- return-path or preservation help

This stage ensures the conversation stays aimed at continuity rather than
drifting into generic chat.

#### 3. Ground and shape the answer

The assistant should then make its working posture visible by shaping the reply
through:

- memory scope
- source-aware grounding when needed
- one concise assistant brief that can hand back into the product

This stage is where the assistant becomes the shell's meaning layer rather than
just a command relay.

#### 4. Hand back and preserve

The journey must end in:

- one concrete product destination
- one durable assistant excerpt or related continuity trace
- one visible follow-up path when Activity needs to reflect the outcome

This keeps the assistant from becoming a closed conversational cul-de-sac.

### Surface Rule

- `Assistant` is the canonical live continuity surface.
- current shell surfaces remain the continuity origin and return destination.
- `Library` is the canonical preserve surface for saved assistant excerpts.
- `Activity` may reflect resulting follow-up anchors but is not the preserve
  surface.

### Contract Publication

The shared assistant continuity model lives in
`libs/oshun/navigation/src/assistant-continuity-journey.ts`.

The web action mapping for that model lives in
`apps/oshun/web/src/navigation/assistant-continuity-journey.ts`.

The current web rendering of that model lives in
`apps/oshun/web/src/components/assistant/AssistantContinuityJourneyRail.tsx`.

The current web assistant-source carry-over lives in
`apps/oshun/web/src/components/ShellLayout.tsx`.

## Scope Boundaries

- This ADR defines the shell-level assistant continuity journey, not the full
  Iris memory system, Psyche embodiment runtime, or Sophia retrieval stack.
- It does **not** replace deeper assistant disclosure, persona switching, or
  evidence-UI backlog items.
- It does **not** require every assistant outcome to become a Library item; it
  defines the canonical preserve path when continuity should survive.

## Architecture Implications

- shared navigation code should expose typed assistant-continuity stages and
  handoffs
- the assistant panel should render those stages as actionable continuity UI
- shell assistant entry should preserve invocation source into the panel
- Library assistant excerpts should remain a first-class preserve destination
- future mobile, Iris, and grounded-answer work can reuse one canonical
  assistant continuity definition instead of inventing local copies

## Acceptance Criteria

`V1-UX-010` is complete only when all criteria below are true:

1. A canonical ADR defines the assistant-led continuity journey model.
2. Shared navigation code publishes the same stage and handoff model.
3. The web assistant maps that model into concrete query, route, and preserve
   actions.
4. The shipped assistant UI reflects invoking context, bounded assistant asks,
   handback destinations, and Library preservation.
5. Tests verify the shared model, web mapping, shell source carry-over,
   assistant-panel rendering, and browser-level assistant handoff behavior.

## Related Decisions

- `docs/adr/ADR-0061-oshun-web-shell-relationship-model.md`
- `docs/adr/ADR-0064-oshun-daypart-cross-domain-journey-model.md`
- `docs/adr/ADR-0065-oshun-research-to-practice-journey-model.md`
- `docs/adr/ADR-0066-oshun-story-to-source-journey-model.md`
- `docs/adr/ADR-0067-oshun-sky-to-text-journey-model.md`

## References

- `docs/releases/v1/specs/web-app-admin-v1-prd.md`
- `docs/releases/v1/reports/unified-product-gap-analysis-and-nisaba-integration-report-2026-03-22.md`
- `libs/oshun/navigation/src/assistant-continuity-journey.ts`
- `apps/oshun/web/src/navigation/assistant-continuity-journey.ts`
- `apps/oshun/web/src/components/assistant/AssistantContinuityJourneyRail.tsx`
- `apps/oshun/web/src/components/assistant/AssistantPanel.tsx`