gemstone-nexus · Phase 6

DOC07 — Punchlist

← Documents

Metadata

iddoc_idtitlecategorysource_pathsummarycontent_hashindexed_at
25DOC07DOC07 — PunchlistpunchlistDevResources/docs/DOC07-Punchlist.md| Item | Owner | Verification Artifact | | --- | --- | --- | | Docker Compose stack, all services healthy | Engineering | docker compose ps output, 10-min idle stability log | | gemstone-db schema migrations applied | Engineering | Alembic migration history, schema diff | | Auth0 RBAC roles configured | Engineering | RBAC matrix (DOC03 Sec 7) mapped to live Auth0 config export | | make rollback verified | Engineering | Rollback dry-run log, timestamped |13d4e030c99ba88329f0dfabd8ca2f91ad4e055d2026-07-23 16:24:57

Content

# DOC07 — Punchlist

*Phased build checklist with owning role and verification artifact*

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

## Phase 0: Infrastructure

| Item | Owner | Verification Artifact |
| --- | --- | --- |
| Docker Compose stack, all services healthy | Engineering | docker compose ps output, 10-min idle stability log |
| gemstone-db schema migrations applied | Engineering | Alembic migration history, schema diff |
| Auth0 RBAC roles configured | Engineering | RBAC matrix (DOC03 Sec 7) mapped to live Auth0 config export |
| make rollback verified | Engineering | Rollback dry-run log, timestamped |

### Deferred / non-blocking (production closeout punchlist)

| Item | Priority | Owner | Exact ask / keys | Status |
| --- | --- | --- | --- | --- |
| **Live Auth0 provisioning + EC2 wiring** | **Deferred — non-blocking for engineering** | Practitioner | Create Auth0 tenant; social Google/Facebook/LinkedIn; four roles (`SuperAdmin`, `Org Admin`, `Practitioner`, `GemStone Agent`); store eight keys in `DATARIGHT_DEV_SECRETS` per `DOC-Auth0-Provisioning.md` (`AUTH0_DOMAIN`, `AUTH0_AUDIENCE`, `AUTH0_CLIENT_ID`, `AUTH0_CLIENT_SECRET`, `AUTH0_ISSUER`, `AUTH0_ENABLED`, `VITE_AUTH0_DOMAIN`, `VITE_AUTH0_CLIENT_ID`). Reply “Auth0 secrets are in DATARIGHT_DEV_SECRETS” for agent wiring. | **DEFERRED 2026-07-21** — `/healthz` allows `auth0.configured:false`; phases 0–5 ran without live tenant. Work continues without live Auth0. |
| **Real Atlas Vault credentials** | Deferred — non-blocking (stub gates PASS) | Practitioner | Add `ATLAS_MCP_ENDPOINT`, `ATLAS_MCP_API_KEY` (optional), optionally `ATLAS_MCP_MODE=auto` to `DATARIGHT_DEV_SECRETS`; follow `DOC-Atlas-Index-B.md` → recreate `api` → verify `/mcp/atlas/health` not stub. Confirmed absent from secrets (21 keys, no `ATLAS_*`) 2026-07-21. | **DEFERRED 2026-07-21** — leave stub; Phase 2A gates already PASS on stub. |
| Third-party penetration test | Vendor gate | NEXTECH + vendor | Engage vendor using `DOC-PenTest-Engagement-Brief.md`; remediate Critical/High; re-test. | Prep complete; engagement pending |
| BABA principal sign-off | Human gate | NEXTECH principal | Sign `DOC-BABA-Western-Origin-Checklist.md` / DOC17 against Syft SBOM; record in ledger. | Engineering checklist complete; sign-off pending |
| App Store / Play Store accounts + submit | Account gate | Practitioner | Apple Developer + Google Play Console; signing keys in vault; follow `DOC-Store-Submission-Checklist.md`. | Assembly checklist complete; accounts pending |
| Device UAT (DOC20 mobility) | Practitioner QA | QA / practitioner | Outdoor sunlight Field Mode; call interruption 10-trial; Android wake 8/10; iOS Siri 9/10 — see `DOC-Device-UAT-Checklist.md`. | Checklist authored; device runs pending |
| **Capacitor Android ↔ live EC2** | Engineering | Engineering | Wire `server.url` + `apiOrigin` + debug TLS trust so Android runs in parallel with web (Auth0 deferred). | **DONE 2026-07-21** — see `DOC-Capacitor-Live-EC2.md`; device QA still open |
| True 10k voice soak (DOC02 §6.10) | Capacity / engineering | Engineering | Needs voice RTT instrumentation + more RAM than g4dn.xlarge 16Gi for true concurrent voice. Root EBS grown 30→80G (online growfs; Whisper retained; ~53G free). Docker data ~114G free. **2026-07-21 probes:** 1k HTTPS `/healthz` 1000/1000 p95 199ms; 10k HTTPS `/healthz` 10000/10000 p95 403ms — **HTTP proxy only, `pass_doc02_full_gate: false`**. | **DEFERRED 2026-07-21** — per practitioner direction, skip until the rest of the solution is built out (feature-complete, without per-user-level gating). Revisit after core features land. Disk already grown; true 10k voice still punchlisted. |

### Stage 2 — Operating model (pre–Phase 0 gate)

| Item | Owner | Status / Verification |
| --- | --- | --- |
| plink/`dr` + host-key pin to T4 EC2 | Engineering | Connected; fingerprint recorded in `project.env.example` / DOC-Deploy-Pipeline |
| `DEVELOPMENT_DIRECTORY` clone + PAT pull | Engineering | `/home/dr/AppDev/gemstone-nexus`; origin URL clean |
| Deploy scripts (commit→push→pull→compose) | Engineering | `scripts/run-remote-docker-deploy.ps1`, `scripts/aws/deploy.sh`, `DOC-Deploy-Pipeline.md` |
| EventBridge spot cost schedule | Engineering | `gemstone-nexus-start/stop` ENABLED (09:00/01:00 ET) |
| Terraform `launch_instance=true` hygiene | Engineering | Commented intentional; README guardrail updated — do not apply destroy |
| Atomic-concurrency doc maintenance | Engineering | DOC08/12/13/19 + punchlist notes updated with Stage 2 |

## Phase 1A/1B: Voice Pipeline and Session Core

| Item | Owner | Verification Artifact |
| --- | --- | --- |
| STT accuracy >= 92% | Engineering + QA | 200-utterance benchmark report |
| TTS first chunk <= 800ms | Engineering | Latency measurement log |
| WebSocket reconnection <= 5s | Engineering + QA | Reconnection test log, 20 trials |
| Cross-org isolation, zero leakage | QA | Isolation test suite report, 50 concurrent sessions |

## Phase 2A: Atlas Integration

- MCP Index B queries p95 <= 800ms under 50 concurrent practitioners (Engineering + QA, latency report).
- Fine-tuning signal write-back verified within 2s of correction event (Engineering, log trace).
- Named/dated session recall correct in 9/10 test cases (QA, test report).
- **Status 2026-07-21:** COMPLETE tip `8232695` on EC2 `i-04333dae160ab0daa`. Gates: Index B p95 7.2ms @50, signal 10/10 ≤2s, recall 10/10; Phase 1B regression PASS. Real remote Atlas Vault not in `DATARIGHT_DEV_SECRETS` — stub backend; see `DOC-Atlas-Index-B.md`.

## Phase 2B/2C: Mobility Layer

- Field Mode voice activation <1s (Engineering, device test log, Android + iOS).
- Heads-Up UI direct-sunlight legibility (QA, manual outdoor test, signed off).
- Extended Session survives call interruption, one-tap resume (QA, 10-trial test log per platform).
- Android wake-word from killed state, 8/10 trials (QA, device test log).
- iOS Siri Shortcut trigger, 9/10 trials (QA, device test log).
- Chunked-hold failure-flagging, in-app + system log within 5 min (Engineering + QA, failure-injection test).
- **Status 2026-07-21:** Engineering COMPLETE tip `a2af898` on EC2 `i-04333dae160ab0daa`. Field Mode UI + WebView audio + Recents API (≥20); Extended Session Android FG mic + wake FG scaffold; iOS Info.plist/Swift/Siri scaffold; interruption lifecycle REST identical across three causes (gate PASS). Device QA gates (sunlight, call 10-trial, wake 8/10 & 9/10) remain open. HorizonORBIT login still stubbed.
## Phase 3A/3B: Domain Packs

- Pack install/activate <10s (Engineering, timing log).
- All six packs pass individual UAT scripts (QA, six signed UAT reports, DOC20 Sec 2).
- **Status 2026-07-21:** Engineering COMPLETE tip `7042354` on EC2 `i-04333dae160ab0daa`. Alembic `0002_phase3ab`; six first-party packs seeded in Postgres; DOC20 §2 UAT 6/6 PASS (`scripts/phase3ab-gates.sh`); max `activate_ms` **7.7ms** (budget 10000ms); HTTP smoke install→active prompt→uninstall history-untouched. Capacitor `/packs` UI build+sync PASS locally. Practitioner device sign-off optional.

## Phase 3C: Didymus Integration

- No task reaches RUNNING without approved_by/approved_at (Engineering + QA, direct DB inspection report).
- Approval queue shows no source distinction (QA, blind review test report).
- Schema-level rejection of unapproved RUNNING transition (Engineering, forced-failure test log).
- **Status 2026-07-21:** Engineering COMPLETE tip `eabc2df` on EC2 `i-04333dae160ab0daa`. Alembic `0003_phase3c`; `didymus_tasks_approval_gate` CHECK; three MVP workers (cursor/claude/gemini); REST + MCP tools; Capacitor `/didymus` blind-source queue; `scripts/phase3c-gates.sh` **PASS** — DOC20 §4 UAT ok, schema reject unapproved RUNNING, DB inspection RUNNING rows have approved_by/approved_at, Whisper CUDA retained (disk ~2.0G free after rebuild).
- **Status 2026-07-22 (OD `i-0f5f3b32dfa9c6a12`):** Live worker execute + vendor-key vault shipped. `WORKER_SECRETS_KEY` enabled on host (vault_available=true). Smoke PENDING→APPROVED→schema-reject force-RUNNING→lease RUNNING→Gemini **live** execute COMPLETED (`didymus-ok`). Cursor/Claude practitioner keys still optional via `/app/onboarding/workers` or host env; Gemini uses stack `GEMINI_API_KEY`. Auth0 still deferred (local JWT optional, `AUTH_ENABLED=false`).
## Phase 2B/2C follow-on: Recents / Notebooks / Inferenced search

- Recents chronological scroll-and-select ≥20 + notebook dual-visibility badges (US-07).
- `POST /api/notebooks` + `POST /api/notebooks/{id}/link` additive (never removes from Recents).
- `POST /api/search/inferenced` top-3 ≥9/10 (US-08 / FR-GS-006).
- Gemini Live hello accepts `context_text` / `recall_query` for Atlas continuity.
- **Status 2026-07-22:** LIVE on OD `i-0f5f3b32dfa9c6a12` tip `238eadb`. Alembic `0007_notebook_links`; `/api/notebooks` + `/api/search/inferenced`; Capacitor `/app/recents`; vault_available=true; Gemini Live `/` retained.
- **Status 2026-07-23:** Agent page Notebooks are interactive end-to-end: create → open notebook → **Add current chat** / pick from Recents → click linked conversation restores turns (same path as Recents). `GET /api/notebooks/{id}` returns `sessions[{session_id,title,linked_at}]`. Dual-visibility unchanged (link never removes Recents).

- WCAG AA automated scan, zero critical violations (QA, scan report).
- Platform Dashboard load <2s (Engineering, performance trace).
- All UAT Structured scripts passing on staging (QA, full UAT report, DOC20).

## Phase 5: Production Hardening

- Playwright E2E suite, zero failures, two consecutive runs (Engineering, CI log). **Status 2026-07-21:** PASS 9/9 ×2.
- Penetration test, Critical/High remediated and re-tested (NEXTECH principal sign-off, pen test report). **Prep:** `DOC-PenTest-Engagement-Brief.md` ready; **vendor engagement pending** (punchlist).
- 10,000 concurrent session load test, p95 <3s (Engineering, load test report). **2026-07-21:** root EBS `vol-0907e6a4ef3d6ed66` grown **30→80G** + online growfs (Whisper healthy; ~53G root free). Docker data ~114G free. HTTPS `/healthz` proxy: **1k** 1000/1000 p95 **199ms**; **10k** 10000/10000 p95 **403ms** (`phase5-load-10k-http.json`). **True 10k voice RTT NOT claimed** on g4dn.xlarge 16Gi — punchlist capacity gate.
- Final SBOM (Syft) and BABA sign-off (NEXTECH principal, signed compliance doc). **Engineering checklist:** `DOC-BABA-Western-Origin-Checklist.md`; **principal sign-off pending**.
- App Store / Play Store submission packages assembled and submitted (Engineering, submission confirmation). **Assembly:** `DOC-Store-Submission-Checklist.md`; **accounts pending**.
- Device UAT mobility scripts (sunlight / call / wake / Siri): `DOC-Device-UAT-Checklist.md` — **practitioner pending**.

## Production-safe backlog — Top 15 (DOC suite gap 2026-07-22)

Source: [`DOC-Suite-Gap-Summary.md`](./DOC-Suite-Gap-Summary.md). Order for additive, zero-downtime delivery:

| # | Item | Status |
| --- | --- | --- |
| 1 | Harden local AUTH (`AUTH_ENABLED`, strong `JWT_SECRET`, bootstrap SuperAdmin, `AUTH_ALLOW_SIGNUP=false` in prod) | **In progress 2026-07-22** — compose default signup closed; Admin invites replace open signup |
| 2 | **Admin Panel MVP** `/app/admin` — users invite/role/deactivate, org pack availability, Atlas health RO, wake/GATE2 knobs | **Shipping 2026-07-22** |
| 3 | Verify Alembic `0008` (+ `0009` admin) on live; smoke `vault_store` writers | **Verify on deploy** |
| 4 | Wire real Atlas remote when `ATLAS_MCP_*` secrets land (keep stub fallback) | Deferred — secrets |
| 5 | TierGuard + stop mid-session tier overwrite (DOC03 immutable) | **Done 2026-07-22** — `session/tier_guard.py`; manager preserves tier on reconnect |
| 6 | Open Mode consent UX (US-04) → `consent_events` | Open |
| 7 | RBAC enforcement audit (Didymus, packs, support view) | Partial — Admin RBAC gated |
| 8 | Chunked-hold dual-flag (FR-GS-009) | Open |
| 9 | Didymus Cursor/Claude worker vault keys smoke | Open (Gemini live) |
| 10 | Device UAT mobility closeout | Practitioner |
| 11 | WCAG AA automated scan; fix criticals | Open |
| 12 | Research Agent (or DOC amend out of MVP) | Deferred |
| 13 | Auth0 cutover after secrets phrase | Deferred |
| 14 | Phase 5 human gates (pen-test, BABA, store) | Human |
| 15 | True 10k voice soak (not `/healthz` proxy) | Deferred capacity |

**Also shipping with this change set:** Project Ledger ↔ conversation (DOC ingest → `ProjectDocuments` + MCP tools + Gemini Live tool calls + sidebar Ledger link).

### GemStoneGuardRails (2026-07-23)

| Item | Status |
| --- | --- |
| Product `GemStoneGuardRails` — match before answers; seed Mark Furiate / DataRight Horizon | Shipping |
| Passcode-gated `guardrails_add`; SuperAdmin passcode + contributor flag | Shipping |
| Alembic `0010_gemstone_guardrails`; Admin tab; MCP tools; Live + sovereign inject | Shipping |
| Doc | [`DOC-GemStoneGuardRails.md`](./DOC-GemStoneGuardRails.md) |

### Push notifications — SNS + FCM + Capacitor (2026-07-23)

| Item | Status |
| --- | --- |
| Scaffold: `device_push_tokens`, `/api/push/register|unregister`, `notify_practitioner` | **Scaffold shipped** |
| Didymus hooks (approval needed / task completed) best-effort; gate untouched | **Scaffold shipped** |
| Capacitor `@capacitor/push-notifications` + register on login | **Scaffold shipped** |
| Env placeholders `SNS_PUSH_PLATFORM_ARN_ANDROID`, `AWS_SNS_REGION=us-east-1` | **In place** (no FCM in secrets yet) |
| **Mark: Firebase Android app** (`com.nextech.gemstone`) + `google-services.json` | **Blocked — Mark** |
| **Mark: secrets** `FCM_SERVER_KEY`, `FCM_PROJECT_ID`, then SNS platform app → `SNS_PUSH_PLATFORM_ARN_ANDROID` | **Blocked — Mark** |
| Real device push delivery | **Blocked on Firebase** |
| APNs / iOS | Deferred |
| Doc | [`DOC-Push-Notifications-SNS.md`](./DOC-Push-Notifications-SNS.md) |

### Field Mode DevExternal + export / Artifacts / Send Email (2026-07-23)

| Item | Status |
| --- | --- |
| Field Mode → Dev External Live when available; sessions in Recents/Search/Notebooks | Shipping |
| Export transcript → email PDF (practitioner) or Artifacts downloadable | Shipping |
| **Send Email** command → “What email…?” → SES report (body + PDF) | Shipping |
| Artifacts CRUD `/api/artifacts` + `/app/artifacts`; Alembic `0013_artifacts` | Shipping |

### Practitioner personal rules (GemStone MVP — shipped 2026-07-23)

*Distinct from product-wide `GemStoneGuardRails`. HorizonIQ deferrals below remain out of scope.*

| Item | Status |
| --- | --- |
| Personal Atlas segment (`org_id` + `practitioner_id`); Alembic `0011_practitioner_rules` | **MVP shipped** |
| Phrase **"Make that a rule"** — capture from recent turns; signed-in required | **MVP shipped** |
| Overlap → remind + **keep original** / **use new**; superseded retained (never delete) | **MVP shipped** |
| Rule history phrase; active rules in chat/Live context after GuardRails | **MVP shipped** |
| MCP: match / propose / commit / history / list; Live + sovereign short-circuit | **MVP shipped** |
| Doc | [`DOC-Practitioner-Rules.md`](./DOC-Practitioner-Rules.md) |

| Intent (unchanged) | Notes |
| --- | --- |
| Scope | **Personal** Atlas segment only (per signed-in practitioner) |
| Approvals | **keep original** vs **use new** via **chat or voice** |
| Auth | User **must be signed in** so the correct Atlas segment is referenced/updated |
| Passcode | **No** passcode on personal practitioner rules (MVP). Product GuardRails keep SuperAdmin passcode |

### HorizonIQ (later)

*Deferred from practitioner-rules design — out of scope for current GemStone MVP. Revisit under HorizonIQ / suite expansion.*

| # | Item | Why deferred |
| --- | --- | --- |
| 1 | **Org-wide shared practitioner rules** (beyond personal Atlas segment) | Org sharing / multi-practitioner rule packs is HorizonIQ territory; GemStone MVP stays personal-segment only |
| 2 | **"Make that a rule" affecting or merging with GemStoneGuardRails** | Product-wide guardrails stay separate for now; no auto-promote from personal rules into GuardRails |
| 3 | **Passcode gate on personal practitioner rules** | Personal rules currently no passcode; GuardRails keep SuperAdmin passcode — do not unify gates in MVP |

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