gemstone-nexus · Phase 6

DOC02 — Statement of Work

← Documents

Metadata

iddoc_idtitlecategorysource_pathsummarycontent_hashindexed_at
20DOC02DOC02 — Statement of WorksowDevResources/docs/DOC02-SOW.md| Term | Definition | | --- | --- | | Practitioner | The licensed end user of GemStone; owns one Atlas Vault; scoped by org_id and practitioner_id. | | Session | A single continuous voice or text interaction, WebSocket-backed, assigned exactly one Security Tier at creation. | | Security Tier | One of High Security, Standard, or Open Mode; immutable for the life of a session; enforced exclusively by TierGuard. | | Domain Pack | An installable bundle of system prompt extension…f6f64b1953f8c2adb0d47ac1e2466196b9184fe32026-07-22 18:33:18

Content

# DOC02 — Statement of Work

*Scope, definitions, phased delivery plan, gate criteria, RACI, risk register, and change control*

**Initiative:** GemStone · **Version:** v2.0 (Rewrite) · **Status:** Approved for Build · **Date:** July 17, 2026

## 1. Definitions

| Term | Definition |
| --- | --- |
| Practitioner | The licensed end user of GemStone; owns one Atlas Vault; scoped by org_id and practitioner_id. |
| Session | A single continuous voice or text interaction, WebSocket-backed, assigned exactly one Security Tier at creation. |
| Security Tier | One of High Security, Standard, or Open Mode; immutable for the life of a session; enforced exclusively by TierGuard. |
| Domain Pack | An installable bundle of system prompt extension, terminology, methodology templates, and knowledge documents for a practice area. |
| Didymus Task | A unit of build work registered in the Didymus queue; requires human approval (approved_by/approved_at) before execution regardless of source. |
| Worker | An AI tool or desktop application implementing the DidymusWorker contract (Cursor, Claude, Gemini at MVP). |
| Notebook | A named, practitioner-created grouping construct in Atlas Vault; session association is additive metadata, never a move. |
| Gate | A phase-completion checkpoint with numeric, binary pass/fail criteria; a phase cannot be marked complete until every gate criterion is independently verified. |
| MVP | The Phase 1 through Phase 5 scope defined in Section 6 of this SOW; excludes everything in Section 3 (Out of Scope). |

## 2. Scope Statement

This SOW covers the design, build, test, and production deployment of: (a) the GemStone core platform, comprising the voice pipeline, WebSocket session layer, Atlas Vault integration, three-tier security model, and Domain Pack system; (b) the GemStone Mobility Layer, comprising the Capacitor mobile application, Field Mode, and Extended Sessions; (c) GemStone participation in Didymus as the universal task presentation and approval surface; and (d) the supporting operational infrastructure (Project Ledger, Platform Dashboard, testing framework) required to run (a) through (c) in production.

Deliverables under this SOW are considered complete only when they pass the Gate criteria defined in Section 6, verified by an individual other than the engineer who implemented the deliverable.

## 3. Out of Scope, Phase 1

- Third-party Domain Pack marketplace (Phase 3). Trigger for inclusion: at least 3 first-party packs in production for 90+ days with practitioner-requested pack topics logged.
- Claude Code, AntiGravity, and GemStone-as-worker as Didymus workers (planned, deferred). Trigger: Phase 1 three-worker MVP stable in production for 30+ days.
- SolidWorks and KiCad desktop-application workers. Trigger: DidymusWorker contract proven stable across all three MVP AI workers; dedicated native-integration engineering allocated.
- Multi-language voice support (FR-GS-005, Phase 2). Trigger: Whisper/Piper Phase 1 accuracy targets met in English; non-English accuracy benchmarked.
- GemStone for Teams / shared session mode (FR-GS-007, Phase 3).
- Horizon IQ direct reporting from GemStone (Phase 2, after Horizon IQ ships).
- Custom voice model training per practitioner (Phase 3).
- Android default-assistant (VoiceInteractionService) status (deferred stretch goal; foreground-service wake-word detection is committed Phase 1 scope instead).
- Custom Android launcher for GemStone (FR-GS-015, noted feature request, not committed).

## 4. Assumptions and Constraints

- Primary runtime is the T4 GoldenAMI EC2 in Ohio (`i-04333dae160ab0daa`). Local secondary/offline is a NEW clean VM clone from `DataRightGoldenOVAFullBase` at `D:\Virtual Machines\DataRightGoldenOVAFullBase\` only; the prior GemStone VM at `10.0.0.210` is retired and is not a build target.
- Backend is sovereign-first: Ollama + Whisper + Piper on the T4; Gemini is available as development inference mode only (see contract-notes.md). Data tier is PostgreSQL + Redis (AOF) + SQLite Project Ledger; GemStone is an MCP client to a remote Atlas Vault.
- Auth is Auth0 with roles SuperAdmin, Org Admin, Practitioner, and GemStone Agent (DOC03 Section 7), including Google, Facebook, and LinkedIn social connections. UI is strict DataRightTailwind; login layout is modeled on HorizonORBIT (HorizonCRM repo).
- Capacitor is first-class: web + Android + iOS ship with atomic concurrency; a Capacitor build or test failure fails the feature and blocks the phase gate.
- Build vehicle is this repo (`GemStone-Nexus-StackOne`); `DataRightAppBundle` provides the bootstrap pipeline. After the first green GoldenAMI build, legacy product naming from the prior StackOne extraction is purged.
- AWS G-series migration is assumed to be underway in parallel but is not a dependency of this SOW; wake-word reliability targets in Section 6 Phase 2C are conditioned on CPU-only inference unless G-series is confirmed live before that phase gate.
- HUME AI integration is explicitly out of scope for all phases under this SOW pending formal principal review (see DOC03 Section 3); no phase gate depends on HUME availability.
- All AI/ML, messaging, and MQTT components must be Western-origin per standing technology stack constraints; no phase gate may be passed using a prohibited component even temporarily.
- iOS App Store review timelines (historically 1 to 3 business days per submission, subject to change without notice by Apple) are outside NEXTECH control and are not counted against internal Phase 5 gate deadlines.
- Didymus Hub (DIDYMUS-ARCH-01) is assumed to exist as shared infrastructure; this SOW covers GemStone's integration with Didymus, not Didymus's own build, which is governed by its own specification. Practitioner worker credential provisioning follows DIDYMUS-PLAYBOOK.
- Bootstrap and Self-Hosting maturity gates are defined in DOC26-Bootstrap-Self-Hosting.md; Mobility Layer detail is in GS-MOB-01.

## 5. Roles and Responsibilities (RACI)

| Deliverable Area | Engineering (Cursor-directed build) | NEXTECH Principal | QA / UAT |
| --- | --- | --- | --- |
| Voice Pipeline (1A) | Responsible | Accountable | Consulted |
| Security Tier Infrastructure | Responsible | Accountable, must sign off before Phase 0 gate closes | Consulted |
| Domain Pack Authoring (3B) | Responsible for schema/tooling | Accountable for content accuracy per pack | Consulted |
| Didymus Integration (3C) | Responsible | Accountable | Responsible for approval-gate verification |
| Mobility Layer Native Bridge (2C) | Responsible | Accountable | Responsible for device-level verification |
| Penetration Testing (5) | Informed | Accountable, must review findings personally | Responsible |
| HUME AI Review | Informed | Responsible and Accountable, cannot be delegated | Informed |

## 6. Phased Delivery Plan

Each phase below lists entry criteria (what must be true to start), the task breakdown, and exit/gate criteria (what must be independently verified to close the phase). A phase cannot begin before its entry criteria are met, and cannot close before every exit criterion passes verification.

## 6.1 Phase 0, Infrastructure

Entry criteria: NEXTECH AWS account and Docker registry access provisioned; gemstone-db PostgreSQL instance provisioned.

## 6.1 Phase 0, Task Breakdown

1. Docker Compose stack: gemstone-api, gemstone-mobile (build artifact only at this phase), gemstone-tts, atlas-ollama, gemstone-db, gemstone-redis, mcp-server, NGINX (WebSocket-upgrade configured), Supervisor.
2. gemstone-db schema migration scripts (Alembic) for: sessions, security_tiers, domain_packs, practitioners, orgs.
3. Auth0 tenant configuration with SuperAdmin, Org Admin, Practitioner, GemStone Agent roles (see DOC03 Section 7 for the full RBAC permission matrix).
4. GemStone Project Ledger initialization (ledger-api instance, empty schema).
5. /healthz endpoint returning 200 with dependency status (db, redis, mcp-server reachability).
6. make rollback target implemented and dry-run tested against a non-production environment.

## 6.1 Phase 0, Exit Criteria

- All containers report healthy via docker compose ps for 10 consecutive minutes under idle load.
- A WebSocket connection to gemstone-api successfully upgrades from HTTP and receives an echo response within 200ms.
- /healthz returns 200 with all dependencies marked healthy.
- make rollback executed against a deliberately broken deployment and restores the prior known-good state within 5 minutes.

## 6.2 Phase 1A, Voice Pipeline

Entry criteria: Phase 0 closed.

## 6.2 Phase 1A, Task Breakdown

1. Containerize Whisper large-v3 in atlas-ollama; expose a gRPC or WebSocket streaming interface for partial and final transcript segments.
2. Containerize Piper TTS in gemstone-tts; expose a streaming interface emitting audio chunks as they are synthesized, not only on full-sentence completion.
3. Implement webrtcvad-based voice activity detection with a configurable pause threshold parameter (default 800ms, override to 2 to 3 seconds for "Deep Thinking Mode").
4. Implement the STTProvider and TTSProvider abstract base classes (see DOC03 Section 2 for the exact interface) and the WhisperSTTProvider / PiperTTSProvider concrete implementations.
5. Build the round-trip test harness: audio in, transcript out, response text in, audio out, measuring end-to-end latency.

## 6.2 Phase 1A, Exit Criteria

- STT word error rate at or below 8% (92%+ accuracy) against a 200-utterance benchmark set covering the six Domain Pack vocabularies.
- First TTS audio chunk emitted within 800ms of receiving the first sentence of response text.
- End-to-end round-trip latency (speech end to first response audio) at or under 2 seconds, measured at p95 across 100 test utterances.
- VAD pause threshold is configurable at runtime without a service restart.

## 6.3 Phase 1B, Session Core

Entry criteria: Phase 1A closed.

## 6.3 Phase 1B, Task Breakdown

1. WebSocket session manager: connection registry keyed by session_id, heartbeat/ping-pong at 30-second intervals, graceful reconnect handling.
2. Redis session state store: active session metadata (tier, practitioner_id, org_id, last_activity_at, conversation_buffer).
3. Reconnection logic: on reconnect within a 5-minute grace window, restore session state from Redis and replay the last N conversation turns to the client.
4. Cross-org isolation test: verify a session for org_id=A cannot read or write state belonging to org_id=B under any code path.

## 6.3 Phase 1B, Exit Criteria

- A deliberately dropped WebSocket connection reconnects and restores full session state within 5 seconds.
- Cross-org isolation test suite passes with zero leakage across 50 concurrent simulated sessions spanning at least 5 distinct org_ids.
- Session state survives a gemstone-redis container restart when Redis persistence (AOF) is enabled.

## 6.4 Phase 2A, Atlas Integration

Entry criteria: Phase 1B closed; Atlas Vault MCP Index B endpoint available.

## 6.4 Phase 2A, Task Breakdown

1. Implement the context-retrieval client querying MCP Index B for relevant Atlas Vault entries given the current conversation context.
2. Implement the fine-tuning signal writer: on practitioner correction or explicit rating, write a structured signal record to Atlas Vault.
3. Implement named/dated session recall: given a practitioner query like "the conversation from last Tuesday about the vendor contract," resolve to the correct session_id and restore it.

## 6.4 Phase 2A, Exit Criteria

- MCP Index B context queries return in 800ms or less at p95 under a simulated load of 50 concurrent practitioners.
- A fine-tuning signal is verifiably written to Atlas Vault within 2 seconds of a practitioner correction event.
- A practitioner can name a prior session in natural language and GemStone restores the correct one in at least 9 of 10 test cases.

## 6.5 Phase 2B, Mobility Layer Field Mode

Entry criteria: Phase 2A closed. See GS-MOB-01 for the full Mobility Layer specification.

## 6.5 Phase 2B, Exit Criteria

- Voice capture activates within 1 second of the field-mode button tap, measured on a mid-tier Android device and an iPhone 13 or later.
- Heads-Up UI passes a direct-sunlight legibility check (manual test, outdoors, midday Florida sun).
- Session list (Recents) correctly displays and restores at least 20 prior sessions in a scroll-and-select test.

## 6.6 Phase 2C, Mobility Layer Extended Sessions

Entry criteria: Phase 2B closed. Android is the priority platform; iOS follows once Android is proven.

## 6.6 Phase 2C, Exit Criteria

- An Extended Session survives OS audio focus loss from an incoming phone call (one of the three interruption causes in DOC03 Section 5), reaches RESUMABLE after the session-ready chime, and resumes on one tap with full prior context restored, tested on both platforms.
- Android wake-word activation succeeds from a fully killed app state in at least 8 of 10 trials under quiet-room conditions.
- iOS Siri Shortcut trigger successfully launches GemStone and begins listening in at least 9 of 10 trials.
- The periodic mic-open audio cue is audible and occurs at the configured interval in a 10-minute continuous Extended Session test.

## 6.7 Phase 3A/3B, Domain Pack System and First-Party Packs

Entry criteria: Phase 2A closed (Domain Packs do not depend on Mobility Layer completion).

## 6.7 Phase 3A/3B, Exit Criteria

- A Domain Pack installs and activates in under 10 seconds, measured from practitioner tap to system prompt extension active in the next turn.
- All six Phase 1 packs (PE Operating Partner, Healthcare Executive, FinTech/Capital Markets, Management Consulting, Construction/Real Estate, Manufacturing Operations) pass their individual Domain Pack UAT scripts (see DOC20 Section 2).
- Uninstalling a pack removes its terminology/system-prompt extension from the next session without affecting prior session history or Atlas Vault content.

## 6.8 Phase 3C, Didymus Integration

Entry criteria: Didymus Hub deployed and reachable (per DIDYMUS-ARCH-01); Phase 1B closed.

## 6.8 Phase 3C, Exit Criteria

- A task submitted by any of the three MVP workers (Cursor, Claude, Gemini) reaches the RUNNING state only after approved_by and approved_at are populated by a human; verified by direct database inspection, not by UI observation alone.
- A GemStone-facing approval queue displays tasks from all three workers with no visual or structural distinction based on source, verified by a blind review test.
- Attempting to force a task to RUNNING via direct API call without approval fields populated is rejected by the schema constraint, not merely by application logic.

## 6.9 Phase 4, Polish and Dashboard

Entry criteria: Phases 2B/2C/3A/3B/3C all closed.

## 6.9 Phase 4, Exit Criteria

- Mobile app passes a WCAG AA automated accessibility scan with zero critical violations.
- Platform Dashboard (DOC21) loads its default view in under 2 seconds on a standard broadband connection.
- All UAT Structured scripts (DOC20) pass on a clean staging environment.

## 6.10 Phase 5, Production Hardening

Entry criteria: Phase 4 closed.

## 6.10 Phase 5, Exit Criteria

- Full Playwright E2E suite passes with zero failures on two consecutive runs.
- Third-party penetration test complete; all Critical and High findings remediated and re-tested; Medium findings have a documented remediation plan with an owner and date.
- Load test sustains 10,000 concurrent sessions with p95 voice round-trip latency remaining under 3 seconds.
- Final Syft SBOM generated and BABA compliance audit signed off by a NEXTECH principal.
- App Store and Play Store submission packages assembled and submitted.

## 7. Risk Register

| Risk | Likelihood | Impact | Mitigation |
| --- | --- | --- | --- |
| Wake-word false-trigger rate too high for field use | Medium | High, undermines Extended Session usability | Field-condition benchmark before Phase 2C gate; tunable sensitivity parameter; re-test after AWS G-series migration |
| iOS background-audio entitlement rejected by App Store review | Low | High, blocks Phase 2C on iOS | Follow Apple background-audio guidelines precisely; avoid any pattern resembling always-on ambient listening; Siri Shortcuts path avoids the highest-risk pattern entirely |
| Didymus Hub instability blocks Phase 3C | Medium | Medium, delays but does not block other phases | Phase 3C has no downstream dependents among 2B/2C/3A/3B; can proceed in parallel |
| HUME AI review stalls indefinitely | Low | Low, feature already excluded from all phase gates | No mitigation needed; explicitly out of scope per Section 4 |
| Whisper/Piper accuracy below target on Domain Pack-specific terminology | Medium | Medium | Benchmark set explicitly includes Domain Pack vocabulary; fine-tuning flywheel improves accuracy post-launch |

## 8. Change Control

Any change to the phase boundaries, gate criteria, or in/out-of-scope lists in this SOW requires a written amendment (following the Amendment 1/Amendment 2 pattern already established for Didymus and Mobility Layer integration) reviewed and approved by a NEXTECH principal before implementation begins. Engineering may not silently expand or contract scope based on implementation convenience.

## 9. Delivery Format

All Cursor-facing deliverables ship in both .docx and .md formats together, per standing NEXTECH documentation standards.


---
NEXTECH Business Technology Management LLC · nex-tech.biz · (941) 499-5505