gemstone-nexus · Phase 6

DOC Suite Gap Summary

← Documents

Metadata

iddoc_idtitlecategorysource_pathsummarycontent_hashindexed_at
17DOC-SUITE-GAP-SUMMARYDOC Suite Gap SummaryreferenceDevResources/docs/DOC-Suite-Gap-Summary.md| Capability | Doc source | Live code | Status | |---|---|---|---| | Gemini Live voice (`/ws/gemstone/live`) | contract-notes, punchlist | `api/app/ws/gemstone_live.py`, `web/gemstone-live.js` | **Done** | | Sovereign Whisper/Piper wake loop | DOC03 §2, contract-notes | `whisper_stt`, `piper_tts`, `gemstone-voice.js` | **Done** (primary path is Live in development mode) | | Recents ≥20 + notebooks + inferenced search | DOC03/04 US-07/08, punchlist | `/api/sessions`, `/api/no…424bbb3074e878db33d54e47df4bf48c2befae3b2026-07-23 15:02:12

Content

## Missing / Partial / Done matrix (high signal)

| Capability | Doc source | Live code | Status |
|---|---|---|---|
| Gemini Live voice (`/ws/gemstone/live`) | contract-notes, punchlist | `api/app/ws/gemstone_live.py`, `web/gemstone-live.js` | **Done** |
| Sovereign Whisper/Piper wake loop | DOC03 §2, contract-notes | `whisper_stt`, `piper_tts`, `gemstone-voice.js` | **Done** (primary path is Live in development mode) |
| Recents ≥20 + notebooks + inferenced search | DOC03/04 US-07/08, punchlist | `/api/sessions`, `/api/notebooks*`, `/api/search/inferenced`, Agent sidebar Recents (`/app/recents` redirects) | **Done** |
| Domain Packs (6 first-party) install/uninstall | DOC03 §10–11, Phase 3A/3B | `api/app/packs/*`, `/app/packs`, Alembic `0002` | **Done** (self-install only) |
| Didymus approval gate + blind queue | DOC03 §6/12, DOC26 | Alembic `0003`, `/api/didymus/*`, `/app/didymus` | **Done** (schema gate) |
| Didymus live worker execute | DIDYMUS-PLAYBOOK | Gemini live path; Cursor/Claude keys optional | **Partial** |
| Platform Dashboard (DOC21 ×8) | DOC21, Phase 4 | `/api/dashboard*`, `/app/dashboard` | **Done** (metrics scaffold; some sources empty) |
| Local JWT auth (signup/login/me) | DOC-Atlas-Data-Model | `/api/auth/*`, Alembic `0005` | **Done** (Auth0 substitute) |
| Auth0 + social + HorizonORBIT login | DOC02/03/Auth0 | `auth0.py` scaffold; login stub; `AUTH0_ENABLED=false` | **Missing** (deferred) |
| Atlas remote MCP vault | DOC-Atlas-Index-B | stub when no `ATLAS_*` | **Missing** (deferred) |
| Atlas durable PG mirror `0008` | DOC-Atlas-Data-Model | migration + `vault_store.py` writers | **Partial** (schema/writers exist; remote still stub; apply/wire verify needed) |
| Project Ledger `/project/*` | DOC19 | `api/app/project/router.py` SQLite views | **Partial** (scaffold; not full DOC19 `ledger_entries` distillation) |
| Capacitor ↔ live EC2 APK | DOCA2, Cap docs | wired per punchlist | **Done** eng / **Partial** device QA |
| Field Mode / Extended Session / wake scaffolds | GS-MOB-01 | frontend pages + native scaffolds | **Partial** (device UAT open) |
| Admin Panel (users/roles/packs/vault) | DOC03 §7 + inferred ops | `/app/admin` + `/api/admin/*` | **Done** (Auth0 deferred) |
| GemStoneGuardRails (mandatory framing) | Mark agreement 2026-07-23 | `api/app/guardrails/*`, Alembic `0010`, Admin tab | **Done** |
| Org-level Domain Pack availability | DOC03 RBAC | only practitioner self-install | **Missing** |
| TierGuard + DOC03 tiers (`high_security`/`standard`/`open_mode`) | DOC03 §1/9, DOC06/08/16 | live tiers = `PUBLIC/INTERNAL/RESTRICTED/SOVEREIGN`; **no** `TierGuard` class; session code can overwrite `tier` | **Missing / drift** |
| Open Mode consent UX (US-04) | DOC04 | `consent_events` table + dashboard; session create UX not verified | **Partial** |
| External Research Agent + NER scrub | DOC03 §8, DOC16 | dashboard counter only; no Brave/Perplexity/spaCy path | **Missing** |
| Cloud STT (Azure/Deepgram) abstraction | DOC03 §2 | providers: Whisper/Ollama/Gemini/Piper only | **Missing** (acceptable until Standard/Open Mode cloud path needed) |
| Chunked-hold dual-flag (FR-GS-009) | DOC03/05/08/21 | `audio_pipeline_holds` + dashboard; pipeline write path thin | **Partial** |
| WCAG AA automated scan | DOC02 Phase 4 | focus/skip-link polish only | **Partial** |
| Playwright E2E ×2 | Phase 5 | 9/9×2 claimed | **Done** eng |
| True 10k voice soak | DOC02 §6.10 | HTTP `/healthz` only; voice gate deferred | **Missing** |
| Pen test / BABA sign-off / store submit / device UAT | DOC07 deferred | docs ready | **Missing** (human gates) |
| Self-hosting Gate 2/3 + `GATE2_SUPERVISED_CYCLE_N` admin | DOC26, DOC06 | Gate 1-ish; admin config UI absent | **Partial / Missing** |
| HUME AI | DOC03 §3 | none | **Out of scope** (correct) |

---

## Top 15 remaining engineering items (production-safe order)

1. **Keep Auth0 deferred but harden local auth for production** — `AUTH_ENABLED=true`, strong `JWT_SECRET`, bootstrap SuperAdmin, disable open signup in prod (`AUTH_ALLOW_SIGNUP=false`), tenancy on all sensitive routes.
2. **Ship Admin Panel MVP (see next section)** — user create/invite + role assign + org pack availability; no Auth0 dependency.
3. **Apply/verify Alembic `0008` on live DB** and confirm Recents/Search/Live dual-write into `atlas_*` tables with org+practitioner isolation.
4. **Wire real Atlas remote when secrets land** — graceful stub fallback must remain; health not-stub only after `ATLAS_MCP_*` present.
5. **Fix security-tier model drift** — align to DOC03 enums OR formally amend docs; implement single `TierGuard`; **stop mid-session tier mutation** (`session/manager.py` overwrite path).
6. **Open Mode consent flow (US-04)** — itemized disclosure + `consent_events` write before `open_mode` persist; dashboard 1:1 must be real.
7. **RBAC enforcement audit** — Didymus approve/submit, pack org-availability, SuperAdmin support-view audit; GemStone Agent never approves.
8. **Chunked-hold vectorization failure path (FR-GS-009)** — write holds + in-app + system log ≤5 min; feed dashboard.
9. **Complete Didymus worker credentialing** — Cursor/Claude vault keys; keep approval schema invariant untouched.
10. **Device UAT mobility closeout** — sunlight, call interrupt 10-trial, Android wake 8/10, iOS Siri 9/10 (`DOC-Device-UAT-Checklist.md`).
11. **WCAG AA automated scan** on Capacitor web; fix criticals only.
12. **Research Agent (if in MVP cut)** — scrub → Brave/Perplexity → audit token to ledger; else amend DOC scope.
13. **Auth0 cutover (when practitioner provisions secrets)** — wire 8 keys, social roles, replace stub login; keep local JWT as break-glass until stable.
14. **Phase 5 human gates** — pen-test engagement, BABA principal sign-off, store accounts/submit packages.
15. **True 10k voice soak** — only after feature-complete + capacity; do not claim from `/healthz` proxy.

**Do later / defer intentionally:** marketplace packs, multi-language, Teams, SolidWorks/KiCad, Android default-assistant, HUME, SMS sandbox (ops; SES email OK).

**HorizonIQ (later)** — see `DOC07-Punchlist.md`: org-wide shared practitioner rules; “make that a rule” merging into `GemStoneGuardRails`; passcode on personal practitioner rules. GemStone MVP personal-rules intent (when built): chat/voice keep-original vs use-new; signed-in Atlas segment only; no personal-rule passcode; GuardRails stay separate.

---

## Admin Panel requirements (extracted from docs)

Docs never name a page called “Admin Panel,” but DOC03 §7 + DOC06 + DIDYMUS-PLAYBOOK + Auth0 docs require these **admin capabilities**:

| Requirement | Source | Exists today? |
|---|---|---|
| **User create** | Local: `POST /api/auth/signup` (creates Org Admin + org + practitioner); bootstrap SuperAdmin via env | API yes / **Admin UI no**; signup may be too open for prod |
| **User invite** | Implied by Auth0 org + role provisioning; training/ops | **No invite API/UI** |
| **Role assign** (`SuperAdmin`, `Org Admin`, `Practitioner`, `GemStone Agent`) | DOC03 §7, Auth0 provisioning | Roles in JWT/store; **no set-role endpoint/UI** |
| **Create/modify org-level Domain Pack availability** | DOC03 RBAC row | **Missing** (only self install/uninstall) |
| **Install/uninstall pack for self** | DOC03 | **Done** (`/app/packs`) |
| **Atlas vault provision** | DOC-Atlas-Index-B | Env/secrets only — **no vault-provision UI**; admin should at most show stub vs remote health + runbook link |
| **Worker credential vault** | DIDYMUS-PLAYBOOK | **Partial** (`/app/onboarding/workers`) |
| **Wake phrases / Gate2 N from admin/dev session** | DOC05 FR-GS-008, DOC06, DOC26 | Env-only; **no admin session UI** |
| **Didymus approve (role-gated)** | DOC03 | Queue UI exists; Auth0 roles deferred → local role claims |
| **SuperAdmin support view of other practitioners’ sessions (audited)** | DOC03 | **Not found** |
| **Cannot change session tier mid-session** | DOC03 | **Must enforce** (current code can overwrite) |

**Suggested Admin Panel checklist for implementer**
- Routes: `/app/admin` (SuperAdmin/Org Admin only)
- Users: list org users; create; invite (email token or temp password); set role; deactivate
- Packs: org allowlist / availability toggle; still use existing install API for self
- Atlas: read-only health (`stub|remote`), link to `DOC-Atlas-Index-B` (no secrets in UI)
- Platform knobs: `WAKE_PHRASES`, `GATE2_SUPERVISED_CYCLE_N` (persist + audit)
- Audit log for role changes + SuperAdmin cross-practitioner views

---

## What NOT to break (production invariants)

1. **Didymus:** no task → `RUNNING` without `approved_by` + `approved_at` (schema CHECK); no auto-execute / no source-colored queue.
2. **Recents:** notebook link is additive only — never hides sessions.
3. **Transcripts / audio:** never send session transcripts or raw audio to external APIs in sovereign/High Security paths; no HUME.
4. **Tenancy:** org RLS + practitioner segment isolation; no guest reading another practitioner’s Atlas.
5. **Atlas degrade:** remote down → stub fallback; don’t hard-fail voice.
6. **Inference modes:** sovereign (local) vs development (Gemini Live); mode switch via ops stays controlled.
7. **Capacitor path:** no React Native/Expo reintroduction; Field vs Extended audio paths stay separate.
8. **Whisper CUDA + disk:** don’t pull Playwright browsers onto tight root; keep voice stack healthy.
9. **`/healthz`:** Auth0/Atlas unconfigured must remain non-blocking until secrets exist.
10. **Deploy hygiene:** no secrets in git; don’t take down `gemstone.dataright.net`; atomic doc/ledger updates with schema/API/UI changes.
11. **Tier immutability + single TierGuard** (once aligned) — no secondary bypass checks.

---

## Implementation-agent checklist (copy/paste)

```
[ ] Confirm live AUTH_ENABLED / AUTH_ALLOW_SIGNUP / JWT_SECRET / bootstrap admin on OD
[ ] Admin Panel: users create/invite/role/deactivate (RBAC-gated)
[ ] Admin Panel: org Domain Pack availability (DOC03 SuperAdmin/Org Admin)
[ ] Admin Panel: Atlas health read-only + wake/GATE2 knobs
[ ] Verify Alembic head includes 0008 on live Postgres; smoke vault_store writers
[ ] Fix tier model: DOC03 enums + TierGuard OR doc amendment; remove mid-session tier overwrite
[ ] Open Mode consent UX → consent_events before persist
[ ] Chunked-hold failure dual-flag path → audio_pipeline_holds
[ ] Cursor/Claude worker vault keys smoke (Gemini already live)
[ ] Device UAT scripts (DOC-Device-UAT-Checklist) — practitioner
[ ] WCAG AA automated scan; fix criticals
[ ] Auth0 wiring only after “Auth0 secrets are in DATARIGHT_DEV_SECRETS”
[ ] Atlas remote only after ATLAS_* in secrets; keep stub fallback
[ ] Pen-test / BABA / store — human gates (do not fake)
[ ] Do NOT: weaken Didymus gate, Recents additive rule, cross-org isolation, HUME, RN/Expo
```

**Net:** Core practitioner product (Live voice, Recents/Search, packs, Didymus, dashboard, Capacitor eng, local auth, ledger `/project`) is largely **Done**. Production-safe remaining work clusters around **Admin/RBAC**, **tier correctness**, **Atlas durability→remote**, **device/UAT**, then **Phase 5 human closeout**.