Pre-Build Punch-List (tracked)
Prioritized review findings, each with an owner role and the milestone by which it must close; the gate checklist before and during M0.
The prioritized review findings, each with an owner role + the milestone by which it must be closed. This is the gate checklist before and during M0. Items map to the file where the fix lives. Status legend: [x] closed in docs (the spec now reflects the fix — code still to be written) · [ ] decision pending (needs the owner).
Must fix before M0 (load-bearing for the regulated/sovereign positioning)
| # | Item | Fix | File | Owner | Milestone | Status |
|---|---|---|---|---|---|---|
| P1 | RLS enforces neither clearance nor cell | Added app.clearance GUC; classification gated by ordered dominance (class_rank), fails closed to OPEN; cell predicate cell_id IS NULL OR = app.cell OR is_faculty so "no cell" ≠ "see everything". One combined policy. | 82 (D15) | Eng | M0 | [x] closed in docs |
| P2 | Break-glass principal not modeled | Third principal type operator-in-tenant (read-only, no tenant role, hard write/export deny); dual-issuer JWT so a control-plane token can never get the normal-user path. | 41,60,83 (D16) | Eng | M0 | [x] closed in docs |
| P3 | App DB role could bypass RLS | Dedicated insigz_app role NOBYPASSRLS NOSUPERUSER; separate owner/migration role; startup assertion. | 82 (D17) | Eng/Infra | M0 | [x] closed in docs |
Fix before the layer that depends on it
| # | Item | Fix | File | Owner | Milestone | Status |
|---|---|---|---|---|---|---|
| P4 | Citation validator under-scans | Validator walks all text-bearing fields (report sections[].body_markdown, timeline[].text, claims[].text) + structured arrays (citations[], claims[].citations, grounding.observations); claims[].citations given the {kind,id} shape. | 80 | Eng | before agent layer (M0 chat / M2 reports) | [x] closed in docs |
| P5 | Realtime channel grammar inconsistent; session-only NOTIFY won't fit live-ops | One canonical grammar t:<tid>:{entity|aoi|case|session}:<id>; live-ops NOTIFYs entity/aoi (not session); coarse channels + client-side filtering; realtime min-instances ≥ 1 noted as a cost floor. | 61,10 | Eng | before realtime layer (M0) | [x] closed in docs |
Cheap cleanups
| # | Item | Fix | File | Owner | Milestone | Status |
|---|---|---|---|---|---|---|
| P6 | name_norm wrongly implied a unique alias | entity_aliases holds deterministic keys only; name_norm is a Stage-2 similarity feature, not a unique alias. | 20,21 | Eng | M1 | [x] closed in docs |
| P7 | Doc 10 used SET not SET LOCAL | Now SET LOCAL (canonical per 82), and lists app.clearance. | 10 | Eng | M0 | [x] closed in docs |
| P8 | WebSocket outlives short JWT | Silent re-auth handshake (refresh → new JWT → re-subscribe); server closes expired sockets. | 61,40 | Eng | M0 | [x] closed in docs |
Decisions (one-way doors — decide now)
| # | Decision | Resolution | File | Owner | Status |
|---|---|---|---|---|---|
| D-a | Defer Mongo → single-store pgvector for M0–M1 | Decided: yes, single-store pgvector first (D1 updated). Polyglot is the documented migration target. | 00,11 | Owner/Eng | [x] decided |
| D-b | Pin embedding model + dimensions before any index | Pin on day one (D5 default Voyage voyage-3/1024-d). | 00,32 | Owner | [ ] confirm provider |
| D-c | Connection pooling | PgBouncer transaction-mode (D18). | 60 | Eng | [x] decided |
| D-d | Tier isolation + cost honesty | Silo for regulated/enterprise; pooled tier for cheap trials; drop "scales to zero" for silo (D19). | 50,61 | Owner | [x] decided |
Owner-only open questions (carried from 00)
- Embeddings provider to pin (D-b).
- Per-tenant IdP strategy (SSO from day one vs. one IdP).
- Launch regions / residency commitments.
- The M0 customer/use case that drives the first vertical slice (
01).
Net
Architecture is coherent; the build sequence (01) is sound; none of this is a redesign. P1–P3 are the gate before M0 (load-bearing for classified-capable positioning). P4–P5 are cheap and best done before the agent and realtime layers are written against the contracts. All documentation fixes are applied; what remains is the owner confirmations above and writing the code to match.
Build Milestones (the sequence Claude Code executes)
Vertical slices in priority order; each milestone is end-to-end shippable, built fully before the next, driven by the first customer use case.
Phase 0 — Discover & Reuse Before Building (PREREQUISITE)
Study the owner's existing estate, harvest what works, reuse deliberately, and re-validate the decisions before writing any code.