docs(PDLC): add STATE.md — Phase 0 project state intake

Ground-truth state for PDLC Phase 0: M1 shipped (v0.0.7, 17 REQs, 189 tests, 98% db coverage), next initiative M2+M3 to complete v0.1. Five known tensions documented (PGlite RLS gap, no cloud infra, G-001 proxy, G-006 audit serialization, INV-7 enforcement model unspecified). ---ci--- phase: 6 milestone: v0.1 status: complete ---/ci---
2026-08-25 02:51:54 +00:00
parent 21724d0300
commit 2a1e6ca698
1 changed files with 109 additions and 0 deletions
@@ -0,0 +1,109 @@
+# Project State Intake Format — PDLC Phase 0
+
+## 1. Header (mandatory)
+Project:            coreci-chat
+Initiative:         CoreCI Chat v0.1 — Read-Only Diagnostic MVP (next: M2 MCP Layer & Day 1 Adapters)
+Initiator:          ciagent (autonomous, full autonomy)
+Date (UTC):         2026-08-25T02:35:00Z
+Current Version:    v0.0.7 (M1 milestone release complete; all 6 phases shipped to main + Gitea upstream)
+System Health:      GREEN — M1 complete, 189 tests green, 98% DB coverage, all 17 M1 REQs PASS, upstream pushed
+Raw Idea (≤ 3 sentences):
+  M1 (read-only diagnostic MVP foundation) shipped: SSO, BYOM, Relay Agent, dashboard, audit, RLS, secrets — no chat/inference yet.
+  Triggered by Sarah Chen (PO) kickoff + locked spec v1.1 (2026-08-24); M1 acceptance gate passed per spec §2.3.
+  Desired outcome: M2 (MCP Layer & Day 1 Adapters, REQ-015..027) + M3 (Chat/Orchestration/Hardening, REQ-028..037+041..044) to complete v0.1.
+
+## 2. Architecture State
+Active Layers (which exist and are stable):
+  [x] Core Primitives — packages/db (Postgres schema, RLS, withTenant, audit hash-chain), packages/secrets (SecretProvider: AWS SM + local-encrypted), packages/config (two-tier credential taxonomy), packages/runtime (Trigger.dev bootstrap + health task)
+  [x] Domain Modules  — packages/auth (WorkOS SSO, sessions, RBAC, provisioning, invitations), packages/byom (endpoint registry, validator, OpenAI-compatible routing shim, REQ-009 reject)
+  [x] API/Dev Surface  — apps/control-plane (Next.js App Router: /api/auth/*, /api/me, /api/team/*, /api/invitations/*, /api/byom/*, /api/targets/*, /api/relay/ws, /api/relay/issue-token, /api/audit/export, /api/relay/status SSE)
+  [x] UI/Agent Surface — apps/control-plane/dashboard (login, onboarding checklist, targets list+detail, team/RBAC, audit export); apps/relay-agent (Go binary: WebSocket client, heartbeat, SSH whitelist hook — no SSH execution in M1)
+
+Compute Topology (per environment):
+  local:        abstract — PGlite (WASM Postgres in Node), LocalEncryptedProvider, mock WorkOS, no AWS/external deps
+  dev:          N/A — same as local (PGlite + local-encrypted); no dev cluster deployed
+  staging:      UNKNOWN — needs investigation (no staging environment provisioned in M1)
+  prod:         single-region AWS us-east-1 (target architecture: Postgres 16, AWS Secrets Manager KMS, Trigger.dev cloud, WorkOS SSO); NOT yet deployed — M1 shipped code only, no prod deployment
+  dr:           N/A — single-region MVP, no DR
+
+Identity Stack in Force:
+  auth:         WorkOS SSO/SAML (dev/mock mode in test; prod requires WORKOS_API_KEY + WORKOS_CLIENT_ID)
+  token-vend:   HS256 JWT (hand-rolled via node:crypto) for sessions + relay registration tokens; no STS
+  signing:      HS256 with SESSION_SIGNING_KEY + RELAY_TOKEN_SIGNING_KEY (env vars, tier (a) infra creds)
+  session:      httpOnly cookie + server-side sessions table row (Postgres, not tenant-scoped)
+
+Audit Stream:
+  source of truth: Postgres audit_log table (append-only, per-tenant hash-chain sha256(prev_hash||canonical(payload)), REVOKE UPDATE/DELETE, BEFORE INSERT trigger)
+  in-repo fallback: yes (PGlite in dev/test — same schema, RLS not enforced on SELECT in PGlite 0.5.7, app-layer withTenant + explicit WHERE is primary enforcement)
+  retention policy: 90 days minimum, 1 year target (spec §5)
+
+## 3. Technical Stack (concrete, not aspirational)
+Language(s) and runtime(s):       TypeScript 5.6 (Node 24.15, Next.js 15 App Router), Go 1.23.4 (static binary, CGO_ENABLED=0)
+Build / packaging:                pnpm 11.23 workspaces (TS monorepo), go build (static ELF amd64+arm64), Gitea releases with binary + install.sh + sha256sums
+CI / CD:                          UNKNOWN — needs investigation (no CI/CD pipeline configured; local verification via pnpm typecheck/test, go test, bash install.test.sh)
+Infrastructure:                   Target: AWS us-east-1 (Postgres 16, Secrets Manager KMS). Current: local/dev only (PGlite, local-encrypted secrets). No cloud infra provisioned in M1.
+Data stores:                      Postgres 16 (prod target) / PGlite 0.5.7 (dev/test, WASM). Tables: tenants, users, tenant_memberships, targets, byom_endpoints, invitations, audit_log (append-only hash-chain), runtime_health, sessions.
+Secrets / KMS:                    Prod: AWS Secrets Manager (KMS-backed, coreci/<tenantId>/<name> naming). Dev: LocalEncryptedProvider (AES-256-GCM, PBKDF2-SHA512 100k iterations, master key from SECRET_MASTER_KEY_DEV env var). Rotation: not implemented in M1.
+External integrations in scope:
+  - WorkOS — SSO/SAML + SCIM + invitation API (auth, tenant provisioning)
+  - Trigger.dev — async durable execution runtime (bootstrapped M1, tasks M3)
+  - AWS Secrets Manager — tenant credential storage (prod)
+  - Gitea (self-hosted, git.cloudinit.dev) — git forge + release distribution
+  - Proxmox VE 7.x/8.x — M2 MCP adapter (not yet implemented)
+  - SSH/Linux (Ubuntu 24.04, Debian 12+) — M2 MCP adapter via Relay Agent (whitelist hook shipped M1, adapter M2)
+  - GitHub — M2 MCP adapter (not yet implemented)
+  - Gitea (customer self-hosted) — M2 MCP adapter (not yet implemented)
+  - Vanta — GRC evidence collection (M3, not yet implemented)
+
+## 4. Active Constraints (the load-bearing ones)
+Locked Decisions:
+  - D-001: OpenAI-compatible BYOM contract (/v1/chat/completions) for M1, pluggable LlmProvider for M3
+  - D-002: Relay Agent in Go (single static binary)
+  - D-003: AWS Secrets Manager (prod) + local-encrypted (dev) behind SecretProvider interface
+  - D-004: Postgres append-only + hash-chain audit for M1, S3 Object Lock WORM in M3
+  - D-005: Next.js App Router + TypeScript single SPA
+  - Spec §7 Q1-Q8: Trigger.dev, WorkOS, Vanta, install script (curl|bash) + apt fallback, fixed SSH whitelist, PVEAuditor, Gitea SaaS-to-API, pgvector (v1.1)
+Active Invariants:
+  - INV-1: Every HTTP request hits API gateway first: auth → tenant resolve → RBAC → audit
+  - INV-2: Every DB query runs under SET app.tenant_id via withTenant transaction; RLS enforces scoping
+  - INV-3: Every credential resolved via SecretProvider.get; never env/config/DB for tenant secrets
+  - INV-4: Every auditable event appended to audit_log with hash-chain; UPDATE/DELETE REVOKE'd; write failure halts
+  - INV-5: Every LLM inference call routed to tenant's BYOM endpoint; unconfigured/unreachable → reject (REQ-009)
+  - INV-6: Relay Agent outbound-only WebSocket; no inbound firewall rules on customer hosts
+  - INV-7: Read-only by default — 100% of write-action requests rejected at MCP gateway (M2) and Relay Agent (SSH whitelist)
+  - INV-8: PGlite 0.5.7 doesn't enforce RLS on SELECT — app-layer withTenant + explicit WHERE is primary in dev/test; RLS + FORCE RLS is prod backstop
+Standing Capability Gate: GATE-M1 — Verified (M1 acceptance gate passed: 17/17 REQs PASS, 189 tests, 98% db coverage, M1-REVIEW.md)
+Anti-Goals Touched: Spec §2.2 out-of-scope (write actions, hosted LLM, K8s/ArgoCD/Helm, Slack/CLI/mobile, approval-gated remediation, RAG, SOC 2 cert, custom RBAC, BYOK, multi-region, Windows)
+Out-of-Scope (hard): Write actions (v1.1), hosted LLM inference (never), Kubernetes/ArgoCD/Helm (not planned), Slack/Teams/CLI/mobile (v1.1+), approval-gated remediation (v1.1), RAG (v1.1), SOC 2 final cert (post-MVP), custom RBAC roles (v1.2+), BYOK (v1.2+), multi-region (MVP single-region), Windows (not planned v1.x), fine-tuning (not planned)
+
+## 5. Recent History & Quality Gates (last 1-2 milestones)
+Last Shipped:       v0.1 M1 — 2026-08-25, 6 phases (P0 pre-execution → P5 Wave E dashboard → P6 final review+ship), 17 REQs (001-014, 038-040), 189 tests, shipped to Gitea v0.0.1-v0.0.7 + binaries
+In Progress:        Nothing — M1 milestone complete. Next: M2 (REQ-015..027, MCP Layer & Day 1 Adapters) not started.
+Coverage Floor:     98.18% (packages/db, the critical-path package; gate ≥80% per spec §6)
+Recent Incidents:   none
+Known Tensions:
+  - PGlite RLS gap: dev/test relies on app-layer withTenant + explicit WHERE; prod RLS is the backstop but untested against real Postgres 16 (no prod deployment yet)
+  - /api/byom/test-inference is a G-001 proxy for REQ-008 — M3 must deprecate when chat orchestration drives real inference
+  - Audit concurrent-write serialization (G-006) — acceptable for M1 volume, M3 needs advisory lock or per-tenant sequence
+  - WorkOS dev/mock mode — prod SSO untested against real WorkOS (no WorkOS keys in this environment)
+  - Lint (eslint) not run — @eslint/js + typescript-eslint not installed at package level (repo-wide, not M1-blocking)
+
+## 6. Agent Context & Assumptions (Agent Initiators Only)
+Missing Context:
+  - Staging/prod deployment state — no cloud infra provisioned; M1 shipped code only
+  - CI/CD pipeline — none configured
+  - WorkOS production keys — not available in this environment (dev/mock mode only)
+  - AWS Secrets Manager — not available in this environment (local-encrypted fallback only)
+  - Real Postgres 16 — not available (PGlite only); RLS enforcement untested against real Postgres
+Agent Assumptions:
+  - PGlite is a sufficient dev/test substitute for Postgres 16 (RLS limitation documented)
+  - The M1 acceptance gate can be verified via unit/integration tests without a prod deployment
+  - Gitea releases with binaries fulfill the "distribution packages" requirement for M1
+  - The next PDLC cycle is M2 (MCP Layer & Day 1 Adapters, REQ-015..027)
+
+## 7. Canonical State References (Version/Hash)
+Vision/Strategy doc:      CoreCI Chat Vision v1.0 (referenced by spec, not in repo)
+Architecture document:    .ciagent/ARCHITECTURE.md @ commit 21724d030033be3fbe9fcdb3c5134ac6e54e03c9
+Last approved SPEC:       steer-v0.1-spec.md v1.1 (locked 2026-08-24) @ commit 6146e9b
+Decision log:             .ciagent/CLARIFY.md (D-001..D-005) + .ciagent/GRILL.md (G-001..G-010) @ commit 21724d0
+Invariants catalog:       .ciagent/ARCHITECTURE.md §Architecture invariants (INV-1..INV-8) @ commit 21724d0