coreci-chat/.ciagent/REQUIREMENTS.md

# Requirements

Source: CoreCI Chat v0.1 Engineering Specification v1.1 (`.ciagent/steer-v0.1-spec.md`), Sarah Chen (PO), locked 2026-08-24.
Milestone type: **Feature** (at least one `feat:` phase). Tags run on the v0.0.x patch line (no prior minor exists; phase 0 seeds `v0.0.1`).

## M1 Requirements (this milestone — REQ-001..014, 038, 039, 040)

All acceptance criteria verbatim from spec §4. Every REQ maps to Journey J1 and/or J2 (spec §3.2) and to at least one failure/edge path (spec §3.3).

### Identity & Access

- [ ] **REQ-001** (J2, High) Establish SSO session via identity provider — **Given** an unauthenticated user navigates to CoreCI Chat, **when** they complete SSO flow via the configured IdP, **then** a session is established and they are redirected to the dashboard. _(Edge 10: SSO provider down → error w/ retry, tenant creation blocked)_
- [ ] **REQ-002** (J2, High) Provision tenant on first signup — **Given** a user completes signup for the first time, **when** tenant creation runs, **then** a new tenant is created, the user is assigned Admin role, and the admin dashboard loads.
- [ ] **REQ-003** (J2, High) Invite users to tenant via email — **Given** an Admin submits an invitation, **when** the system processes the invite, **then** an email is sent to the invitee containing a single-use acceptance link. _(Edge 15: bounce → admin notified, invite invalidated)_
- [ ] **REQ-004** (J2, High) Apply RBAC role to user — **Given** an Admin assigns a role (Admin/Operator/Viewer), **when** the assignment is saved, **then** the user's role is updated and enforced on the next API call.
- [ ] **REQ-005** (J1, J2, High) Enforce RBAC at API gateway — **Given** a user with role X calls endpoint Y, **when** the role check runs, **then** the request is allowed iff X has permission for Y. _(Critical-path pattern: set at API gateway from first endpoint, no auth-later stubs.)_

### BYOM (Bring Your Own Model)

- [ ] **REQ-006** (J2, High) Configure BYOM endpoint (URL + API key) — **Given** an Admin submits endpoint URL and API key, **when** the form is saved, **then** the API key is stored in the secret manager and the URL is validated.
- [ ] **REQ-007** (J2, High) Validate BYOM endpoint connectivity on save — **Given** an Admin submits a BYOM endpoint, **when** validation runs, **then** a test inference call is sent and the result is displayed as success or failure with error details. _(Edge 11: test fails → save blocked, errors surfaced)_
- [ ] **REQ-008** (J1, J2, High) Route all LLM inference to configured BYOM endpoint — **Given** a user submits a prompt, **when** orchestration runs, **then** 100% of LLM inference calls are sent to the configured BYOM endpoint (verified via outbound traffic log).
- [ ] **REQ-009** (J1, J2, High) Reject LLM request when BYOM is unconfigured or unreachable — **Given** no BYOM endpoint is configured or it is unreachable, **when** an Operator submits a prompt, **then** the request is rejected with a clear actionable error and no inference is attempted. _(Edge 1: unreachable mid-workflow → actionable error, halt.)_

### Relay Agent

- [ ] **REQ-010** (J2, High) Distribute Relay Agent as systemd service via install script — **Given** a Platform Lead runs the install script on a supported host (Ubuntu 24.04 LTS or Debian 12+), **when** execution completes, **then** a systemd service is installed, started, and configured for auto-start on boot; install aborts with clear error on unsupported OS. _(Edge 16: unsupported OS → clean abort, list supported versions. Critical-path: modular install — separate functions detect-OS/install-binary/write-systemd-unit/register-target.)_
- [ ] **REQ-011** (J2, High) Establish outbound WebSocket from Relay Agent to SaaS — **Given** the Relay Agent systemd service is running with valid tenant credentials, **when** the service starts, **then** it establishes an outbound WebSocket to CoreCI Chat SaaS within 60 seconds.
- [ ] **REQ-012** (J2, High) Register Relay Agent with tenant + target metadata — **Given** a Relay Agent connects, **when** registration completes, **then** tenant ID, target ID, hostname, OS name and version, IP address, and agent version are recorded. _(Edge 12: registration fails → error + troubleshooting link, dashboard red.)_
- [ ] **REQ-013** (J2, High) Maintain heartbeat and auto-reconnect on WebSocket drop — **Given** the WebSocket drops, **when** 30 seconds elapse without reconnect, **then** the Relay Agent initiates reconnection with exponential backoff (max 5 attempts before alerting); systemd auto-restarts on hard failure. _(Edge 4: drops mid-investigation → auto-reconnect, resume from durable state.)_
- [ ] **REQ-014** (J2, Med) Surface Relay Agent health and logs in admin dashboard — **Given** a Relay Agent is registered, **when** an Admin views the dashboard, **then** health status (green/yellow/red), target hostname, and the last 100 log lines are visible.

### Security & Compliance (M1)

- [ ] **REQ-038** (J1, J2, High) Log every prompt, tool call, SSH command, and response to immutable audit store — **Given** any of these events occur, **when** the audit log write runs, **then** the entry is written to a write-once store with tenant ID, user ID, target ID (for SSH), timestamp, and correlation ID; write failures halt the operation. _(Edge 7: write fails → halt + alert, no silent drops. Critical-path: append-only from day one; hash-chain pattern propagates to M2/M3.)_
- [ ] **REQ-039** (J1, J2, High) Implement Row-Level Security on all tenant-scoped data — **Given** any database query is executed, **when** the query runs, **then** RLS policies enforce tenant scoping and cross-tenant queries return empty results. _(Critical-path: zero leakage verified by pen test.)_
- [ ] **REQ-040** (J2, High) Store tenant credentials in centralized secret manager — **Given** any tenant credential (BYOM API key, Proxmox token, SSH key, Git token) is stored, **when** stored, **then** it resides in the centralized secret manager and never in plaintext in application logs or DB rows. _(Critical-path: every credential via secret manager from the first secret. No env vars, no config files, no DB columns. Ever.)_

## Deferred to M2 (REQ-015 → REQ-027 — MCP Layer & Day 1 Adapters)

Listed for traceability; NOT in M1 scope. M2 acceptance gate: all four Day 1 integrations respond to a test call, multi-target scoping functional, read-only enforcement verified at both gateway and Relay Agent layers (including SSH whitelist). See spec §2.3.

REQ-015 (abstract MCP tool schema), REQ-016 (route to adapter), REQ-017 (SSE stream), REQ-018 (read-only at gateway), REQ-019 (rate limit), REQ-020 (Proxmox adapter), REQ-021 (SSH/Linux adapter), REQ-022 (GitHub adapter), REQ-023 (Gitea adapter), REQ-024 (multi-target scope), REQ-025 (Proxmox auth PVEAuditor), REQ-026 (SSH key + whitelist enforcement at Relay Agent — **whitelist file format + enforcement hook ship in M1, adapter plugs in M2**), REQ-027 (Git scoped tokens).

## Deferred to M3 (REQ-028 → REQ-037, REQ-041 → REQ-044 — Chat, Orchestration, Hardening)

Listed for traceability; NOT in M1 scope. M3 acceptance gate: Operator asks a diagnostic question, sees streamed tool execution, receives a cited evidence-backed answer within 5 min p95; async workflows persist/rejoin; usage metered; SOC 2 controls instrumented; all v0.1 release gates pass.

REQ-028 (chat UI), REQ-029 (NL input), REQ-030 (streaming response + citations), REQ-031 (tool traces), REQ-032 (conversation history), REQ-033 (reason about tools), REQ-034 (multi-step workflows), REQ-035 (≤20 step limit), REQ-036 (durable execution), REQ-037 (rejoin workflow), REQ-041 (SOC2 posture page), REQ-042 (Vanta instrumentation), REQ-043 (usage metering), REQ-044 (usage dashboard).

## Out of Scope (v0.1 — do not build)

| Feature | Reason |
|---------|--------|
| Write actions (apply/delete/scale/restart/VM start-stop) | v1.1 (spec §2.2) |
| Hosted LLM inference | Never — BYOM permanent (spec §2.2) |
| Kubernetes / ArgoCD / Helm | Not planned (spec §2.2) |
| Slack / Teams / Discord / CLI / mobile chat surfaces | v1.1+ / not planned (spec §2.2) |
| Approval-gated remediation, Senior Approver persona | v1.1 (spec §2.2) |
| RAG over historical incidents | v1.1 (spec §2.2) |
| SOC 2 Type 1 final certification | Audit-in-progress posture only (spec §2.2) |
| Custom RBAC roles beyond Admin/Operator/Viewer | v1.2+ (spec §2.2) |
| BYOK / customer-managed encryption keys | v1.2+ (spec §2.2) |
| Multi-region deployment | Single region MVP (spec §5) |
| Windows server management | Not planned v1.x (spec §2.2) |
| Fine-tuning, custom model deployments | Not planned (spec §2.2) |
| Anything not in the spec | Flag as spec-time scope question; never silently add |

## Traceability

| Requirement | Milestone | Phase | Status |
|-------------|-----------|-------|--------|
| REQ-001 | M1 | Wave B | pending |
| REQ-002 | M1 | Wave B | pending |
| REQ-003 | M1 | Wave B | pending |
| REQ-004 | M1 | Wave B | pending |
| REQ-005 | M1 | Wave B | pending |
| REQ-006 | M1 | Wave C | pending |
| REQ-007 | M1 | Wave C | pending |
| REQ-008 | M1 | Wave C | pending |
| REQ-009 | M1 | Wave C | pending |
| REQ-010 | M1 | Wave D | pending |
| REQ-011 | M1 | Wave D | pending |
| REQ-012 | M1 | Wave D | pending |
| REQ-013 | M1 | Wave D | pending |
| REQ-014 | M1 | Wave E | pending |
| REQ-015 | M2 | — | deferred |
| REQ-016 | M2 | — | deferred |
| REQ-017 | M2 | — | deferred |
| REQ-018 | M2 | — | deferred |
| REQ-019 | M2 | — | deferred |
| REQ-020 | M2 | — | deferred |
| REQ-021 | M2 | — | deferred (whitelist hook ships M1 Wave D) |
| REQ-022 | M2 | — | deferred |
| REQ-023 | M2 | — | deferred |
| REQ-024 | M2 | — | deferred |
| REQ-025 | M2 | — | deferred |
| REQ-026 | M2 | — | deferred (whitelist format + hook ships M1 Wave D) |
| REQ-027 | M2 | — | deferred |
| REQ-028 | M3 | — | deferred |
| REQ-029 | M3 | — | deferred |
| REQ-030 | M3 | — | deferred |
| REQ-031 | M3 | — | deferred |
| REQ-032 | M3 | — | deferred |
| REQ-033 | M3 | — | deferred |
| REQ-034 | M3 | — | deferred |
| REQ-035 | M3 | — | deferred |
| REQ-036 | M3 | — | deferred |
| REQ-037 | M3 | — | deferred |
| REQ-038 | M1 | Wave A | pending |
| REQ-039 | M1 | Wave A | pending |
| REQ-040 | M1 | Wave A | pending |
| REQ-041 | M3 | — | deferred |
| REQ-042 | M3 | — | deferred |
| REQ-043 | M3 | — | deferred |
| REQ-044 | M3 | — | deferred |