Status: Active
Owner: OSHUN Studio Product Design + Web Engineering
Last Updated: 2026-02-23
Related:
docs/adr/ADR-0020-oshun-studio-navigation-and-command-surfaces.mddocs/releases/v1/specs/studio-navigation-and-command-surfaces-dependency-and-data-contract-map.md
Purpose#
Define primary journeys and deterministic edge-case behavior for Studio navigation and command-surface governance.
This document is the execution artifact for OST-00059.
Personas#
- Program Operator
- Domain Specialist
- Studio Reviewer
- Security Reviewer
- Accessibility Lead
Journey Principles#
- Commands must be discoverable and scoped.
- Navigation must preserve context and return paths.
- Sensitive commands must be policy-gated and auditable.
- Command surfaces must remain keyboard and screen-reader accessible.
1. Primary Journeys#
J1. Global Command Discovery and Invocation#
Goal: Find and execute global Studio commands quickly.
Entry: Studio -> Global Command Surface
Steps:
- Open global command surface.
- Filter commands by text and scope.
- Inspect command metadata and required context.
- Execute command with optimistic feedback.
- Record audit and telemetry evidence.
Success State:
- Target command executes successfully with preserved context.
J2. Workspace-Scoped Command Execution#
Goal: Run workspace-specific actions without losing navigation state.
Entry: Studio -> Workspace Command Surface
Steps:
- Open workspace command tray.
- Select scoped command.
- Verify policy and confirmation requirements.
- Execute command and monitor result.
- Return to originating context with back-stack integrity.
Success State:
- Command executes and user returns to correct workspace state.
J3. Cross-Domain Navigation Handoff#
Goal: Navigate from one domain surface to another while preserving origin context and stack.
Entry: Studio -> Domain Surface Link
Steps:
- Trigger cross-domain route action.
- Carry origin and stack parameters.
- Land in target domain with hydrated context.
- Perform target operation.
- Return using deterministic back path.
Success State:
- Cross-domain roundtrip preserves all required context.
J4. Policy-Gated Command Approval Flow#
Goal: Gate sensitive commands through policy and approval checks.
Entry: Studio -> Sensitive Command Invocation
Steps:
- Attempt execution of high-impact command.
- Evaluate policy matrix and role entitlement.
- Require explicit confirmation/approval if needed.
- Execute or deny with rationale.
- Emit audit event with decision evidence.
Success State:
- Sensitive command executes only when policy requirements are satisfied.
J5. Navigation/Command Incident Recovery#
Goal: Recover from route or command-surface regressions.
Entry: Observability alert or user escalation
Steps:
- Identify failing route/command path.
- Roll back to last certified route/command bundle.
- Validate context restoration and command behavior.
- Freeze problematic changes.
- Publish incident report with mitigation actions.
Success State:
- Stable navigation and command behavior is restored.
2. Critical Edge Cases#
E1. Missing Required Context#
- Trigger: command invoked without required context keys.
- Required behavior: block invocation and prompt context completion.
E2. Unauthorized Command Invocation#
- Trigger: role lacks permission for command.
- Required behavior: deny with explicit policy reason and audit record.
E3. Stale Back-Stack Pointer#
- Trigger: back-stack route is invalid or expired.
- Required behavior: route to deterministic fallback and preserve session.
E4. Cross-Domain Return Path Loss#
- Trigger: origin context missing on domain handoff.
- Required behavior: restore via fallback strategy and notify operator.
E5. Command Confirmation Bypass Attempt#
- Trigger: sensitive command executes without required confirmation.
- Required behavior: block release and flag critical policy violation.
E6. Keyboard Trap in Command Surface#
- Trigger: focus cannot escape command overlay.
- Required behavior: fail accessibility validation and block promotion.
E7. Screen Reader Label Drift#
- Trigger: command items missing semantic labels.
- Required behavior: fail accessibility checks with actionable diagnostics.
E8. Command Telemetry Sink Failure#
- Trigger: command audit/telemetry events fail to emit.
- Required behavior: retry, mark degraded observability, reconcile buffered events.
E9. Command Timeout Without Resolution#
- Trigger: long-running command neither succeeds nor fails in SLA window.
- Required behavior: mark timed out, offer retry/rollback, capture diagnostics.
E10. Rollback Artifact Missing#
- Trigger: release package lacks rollback route/command mapping.
- Required behavior: block production promotion.
3. Journey-to-Surface Mapping#
| Journey | Primary Surface | Supporting Surfaces |
|---|---|---|
| J1 Global Command Discovery and Invocation | Navigation & Commands | Observability |
| J2 Workspace-Scoped Command Execution | Navigation & Commands | Workspace surfaces |
| J3 Cross-Domain Navigation Handoff | Navigation & Commands | Domain surfaces |
| J4 Policy-Gated Command Approval Flow | Governance | Navigation & Commands |
| J5 Navigation/Command Incident Recovery | Observability | Governance, Navigation & Commands |
4. Instrumentation Requirements#
Required events:
navigation_command.journey.startednavigation_command.journey.step.completednavigation_command.journey.blockednavigation_command.journey.recoverednavigation_command.journey.completed
Required dimensions:
programId,projectId,workspaceIdjourneyId,stepId,routeId,commandIdactorRole,outcome,latencyMs,errorCode
5. Acceptance Criteria (OST-00059)#
OST-00059 is complete only when:
- At least five navigation/command journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.