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