gemstone-nexus · Phase 6
DOC04 — Granular User Stories
Metadata
| id | doc_id | title | category | source_path | summary | content_hash | indexed_at |
|---|---|---|---|---|---|---|---|
| 22 | DOC04 | DOC04 — Granular User Stories | doc_suite | DevResources/docs/DOC04-Granular-User-Stories.md | US-01: As a practitioner, I can speak a request to GemStone and receive a response without losing context if I step away mid-session. | b8410a9f38f0f098995eecac26aca95abcdc672d | 2026-07-22 18:33:18 |
Content
# DOC04 — Granular User Stories
*Practitioner-level stories with Given/When/Then acceptance criteria*
**Initiative:** GemStone · **Version:** v2.0 (Rewrite) · **Status:** Approved for Build · **Date:** July 17, 2026
## 1. Epic: Core Voice Interaction
US-01: As a practitioner, I can speak a request to GemStone and receive a response without losing context if I step away mid-session.
Given an ACTIVE session, When the practitioner's app is backgrounded for up to the configured Extended Session timeout, Then the session transitions to PAUSED with an interruption_snapshot written; When the session-ready chime fires, Then state becomes RESUMABLE; When the practitioner returns to the app within the timeout window and taps resume (or reopens the app), Then state restores to ACTIVE with full prior context from the interruption_snapshot.
US-02: As a practitioner, I can resume a session exactly where I left off regardless of how it was interrupted (OS audio focus loss including incoming call, network drop, or app backgrounding).
Given a session that reached RESUMABLE via any of the three interruption causes (OS audio focus loss including incoming call; network drop; app backgrounding), When the practitioner taps resume or reopens the app, Then the restored context is identical across all three causes, verified by comparing the last_turn payload byte-for-byte. (Extended Session timeout with confirmation is a separate path to ENDED, not an interruption-to-PAUSED/RESUMABLE cause.)
## 2. Epic: Security and Tiers
Canonical tier display names are High Security, Standard, and Open Mode (DOC02/DOC10). Wire/enum values are `high_security` / `HIGH_SECURITY`, `standard` / `STANDARD`, and `open_mode` / `OPEN_MODE` (DOC03 Section 1). Acceptance criteria below use enum constants; UI copy uses display names.
US-03: As a practitioner, I select a security tier at session start and it cannot change mid-session.
Given a session created with tier=STANDARD, When any code path attempts to modify the tier field, Then the write is rejected at the database constraint level, not merely by application logic.
US-04: As a practitioner entering Open Mode, I see an itemized disclosure before I confirm.
Given a practitioner selecting Open Mode, When the session-creation flow begins, Then an itemized list of specifically reduced protections is displayed and a distinct consent action is logged before tier=OPEN_MODE is persisted.
## 3. Epic: Domain Packs
US-05: As a PE operating partner, installing the PE Operating Partner Pack makes GemStone fluent in EBITDA optimization immediately.
Given the pack is installed, When the practitioner starts the very next session, Then the system prompt extension and terminology dictionary for that pack are active without requiring an app restart.
US-06: As a practitioner, installing or removing packs never touches my core session history.
Given a practitioner uninstalls a Domain Pack, When their prior sessions are viewed in Recents, Then all prior session content, transcripts, and Atlas Vault entries remain unchanged.
## 4. Epic: Notebooks, Recents, and Search
US-07: As a practitioner, assigning a session to a Notebook never removes it from Recents.
Given a session linked to a Notebook via POST /api/notebooks/{id}/link, When the practitioner views Recents, Then the session appears in chronological position with a Notebook badge, not hidden or moved.
US-08: As a practitioner, I can find something from a past conversation using natural language.
Given a practitioner has a session discussing a specific vendor contract, When they later ask GemStone to find it using approximate natural language, Then inferenced search returns that session in the top 3 results in at least 9 of 10 test cases.
## 5. Epic: Orchestration and Approval
US-09: As a practitioner, I see every build suggestion in one place regardless of which AI tool proposed it.
Given tasks submitted by GemStone, Cursor, Claude, and Gemini, When the practitioner opens the approval queue, Then all four sources appear in a single unified list with no separate view per source, and source is not visually distinguishable without inspecting metadata.
US-10: As a practitioner, GemStone proposing its own tasks changes nothing about my approval responsibility.
Given GemStone is Phase-2 self-hosting capable, When GemStone submits a task with requested_by="GemStone", Then the task enters PENDING and requires the identical approval action as any human-submitted or other-tool-submitted task.
## 6. Epic: Field and Mobility
US-11: As a practitioner driving or cycling, I can tap a single large button without looking at the screen.
Given Field Mode is active, When the practitioner taps anywhere within the locked center-screen target region, Then recording begins within 1 second and an ascending dual-tone chime confirms it audibly.
US-12: As a practitioner working hands-free, I can say a configured wake phrase to bring GemStone to life.
Given the app is fully killed on Android, When the practitioner says a configured wake phrase within range of the device microphone, Then the foreground-service wake-word model detects it and launches GemStone in at least 8 of 10 trials.
US-13: As a practitioner in an Extended Session, I hear a periodic chime confirming the mic is open, and get a confirmation step before timeout.
Given an Extended Session has been open for the configured cue interval, When that interval elapses, Then an unobtrusive audio cue plays, and When the session approaches its extended timeout, Then an explicit confirmation step is required before the mic closes.
US-14: As a practitioner, a failed transcription notifies me rather than silently disappearing.
Given a vectorization pipeline failure on a completed session, When the failure occurs, Then an in-app notification appears and a corresponding system-log entry is written, both within 5 minutes of the failure.
---
NEXTECH Business Technology Management LLC · nex-tech.biz · (941) 499-5505