coreci-chat/.ciagent/steer-v0.1-spec.md

CoreCI Chat v0.1 — Engineering Specification v1.1 (FINAL)

Owner: Sarah Chen Status: Locked (v1.1) Type: Feature (MVP) Target Milestone: CoreCI Chat v0.1 — Read-Only Diagnostic MVP Companion Product: CoreCI (existing CI/CD platform by owner) Locked Date: 2026-08-24

Operating Principles for this Spec:

1. Incremental Delivery: Defines net-new work for CoreCI Chat v0.1. Pre-existing systems and locked architectures are referenced, not restated.
2. Zero Ambiguity: Any requirement not translatable to a pass/fail QA test is rejected by Engineering.
3. No Scope Expansion: Any requirement discovered during spec build that is not authorized by CoreCI Chat Vision v1.0 / Phase 2 scope will be flagged as a spec-time scope question and escalated — never silently added.

---

1. Objective

CoreCI Chat v0.1 delivers a browser-based chat interface where mid-market enterprise IT operators ask natural-language questions about their infrastructure and receive coherent, evidence-backed diagnostic answers within five minutes. CoreCI Chat speaks MCP to a Relay Agent installed as a systemd service on the customer's Linux servers (Ubuntu 24.04 or Debian), and directly to Proxmox and GitHub/Gitea APIs. All AI inference is routed through a customer-provided model endpoint (BYOM). Every prompt, tool call, and command execution is immutably audited. The wedge is deliberately conservative: CoreCI Chat investigates in v0.1 and proposes remediation in v1.1. CoreCI Chat is a companion product to CoreCI (the owner's existing CI/CD platform).

Acceptance Gate: A developer reading this can state the goal of the feature in a single sentence.

---

2. Scope & Target Milestones

2.1 In Scope (Explicit Additions)

Core Application

• Browser-based chat UI (no mobile, no native apps, no CLI)
• Streaming tool execution traces with inline citations
• Conversation history persistence per user/tenant
• Tenant admin dashboard

AI Orchestration

• LLM orchestration engine (BYOM endpoint routing only — no hosted inference)
• Async durable execution for long-running tool calls
• Conversation memory within session
• Rejoin-in-progress async workflow
• LLM step limit (≤20 tool calls per workflow)

MCP Layer

• Abstract generic MCP tool schema
• MCP gateway with read-only enforcement at proxy layer
• Adapter implementations (Day 1): Proxmox, SSH/Linux Server, GitHub, Gitea
• Multi-tenancy isolation at gateway
• SSE streaming from MCP to UI
• Token-bucket rate limiting (per user, per tenant)

Relay Agent

• Lightweight systemd service running on Linux hosts (Ubuntu 24.04, Debian 12+)
• Distribution via install script (curl|bash or apt package)
• Outbound WebSocket to CoreCI Chat SaaS (no inbound firewall rules required)
• Read-only enforcement at Relay Agent layer for SSH command execution
• Heartbeat, health check, and auto-reconnect
• Per-target registration (each Relay Agent = one target)

Identity & Access

• SSO/SAML via WorkOS (or equivalent)
• RBAC: Admin, Operator, Viewer roles
• Per-tenant credential storage in centralized secret manager

Security & Compliance

• Immutable audit logging (prompts, tool calls, SSH commands, responses)
• Row-Level Security on all tenant-scoped data
• "SOC 2 Type 1 Audit in Progress" posture published
• GRC platform (Vanta or Drata) instrumentation

Pricing Infrastructure

• Usage metering layer (tool calls, LLM tokens, workflow executions)
• Per-tenant usage dashboard for Admin

Out-of-Box Setup

• Install script for Relay Agent
• Configuration templates for Day 1 integrations
• Pre-built smoke-test investigation scenarios

2.2 Out of Scope (Explicit Exclusions)

• Write actions of any kind (apply, delete, scale, rollback, restart, container start/stop, VM start/stop) — deferred to v1.1
• Approval-gated remediation workflows and Senior Approver persona — v1.1
• Remediation diff preview UI — v1.1
• Hosted LLM inference from CoreCI Chat — never (BYOM is permanent)
• Fine-tuning on customer data
• Custom model deployments managed by CoreCI Chat
• MCP integrations beyond Proxmox, SSH/Linux Server, GitHub, Gitea — v1.2+
• Custom MCP server authoring tools for customers — v1.2+
• Inbound webhook ingestion from alerting tools (manual chat launch only in MVP)
• Visual drag-and-drop workflow builder (LLM-driven dynamic only in MVP)
• Workflow templates, sharing, versioning — v1.2+
• Slack / Teams / Discord chat interfaces — v1.1+
• Mobile apps — not planned for v1.x
• CLI for power users — v1.1
• Email notifications — v1.1
• Multi-region deployment (single region MVP)
• White-label / multi-brand tenants
• Custom RBAC roles beyond Admin / Operator / Viewer — v1.2+
• Audit log query UI (logs captured and exportable, not searchable in MVP) — v1.2+
• RAG over historical incidents, post-mortems, Slack threads — v1.1
• SOC 2 Type 1 final certification — controls in place, audit running, cert post-MVP
• HIPAA, FedRAMP, PCI, ISO 27001 — not planned for v1.x
• Customer-managed encryption keys (BYOK) — v1.2+
• Data residency controls beyond BYOM (single region MVP)
• Kubernetes integration of any kind — not planned
• ArgoCD integration of any kind — not planned
• Helm-based distribution of any kind — not planned
• Container orchestration surfaces (Kubernetes, Nomad, Docker Swarm, etc.) — not planned for v1.x
• Windows server management — not planned for v1.x (Linux only)

2.3 Milestone Breakdown

• Milestone 1 — Foundation (Weeks 1–3): Ships REQ-001 through REQ-014, REQ-038, REQ-039, REQ-040.

  • Acceptance Gate: Platform Lead can sign up via SSO, configure a BYOM endpoint with green validation, deploy Relay Agent via install script on at least one target Linux host, register the target, and see green status in admin dashboard. Audit logging, RLS, and secret manager are operational.

• Milestone 2 — MCP Layer & Day 1 Adapters (Weeks 4–5): Ships REQ-015 through REQ-027.

  • Acceptance Gate: Platform Lead can configure all four Day 1 integrations (Proxmox, SSH target, GitHub or Gitea) and verify each adapter responds to a test call from the admin dashboard. Multi-target scoping is functional. Read-only enforcement is verified at both gateway and Relay Agent layers (including SSH command whitelist).

• Milestone 3 — Chat, Orchestration, Hardening (Weeks 6–8): Ships REQ-028 through REQ-037, REQ-041 through REQ-044.

  • Acceptance Gate: Operator can ask a natural-language diagnostic question, see streamed tool execution, and receive a cited, evidence-backed answer within 5 minutes (p95). Async workflows persist and rejoin correctly. Usage is metered. SOC 2 controls are instrumented. All v0.1 release gates pass.

---

3. Personas & User Journeys

3.1 Personas

• Persona A — The Operator (Primary User): SRE, Sysadmin, or Platform Engineer who owns infrastructure reliability across on-prem Proxmox environments, Linux servers (Ubuntu/Debian), and Git-based CI/CD workflows. Day is SSH sessions, Proxmox UI, GitHub/Gitea, observability tools, Slack, Jira. Pain is real-time cognitive load during incidents across heterogeneous infrastructure. MVP authority: read-only across all integrated systems.
• Persona B — The Platform Lead / Tenant Admin (Secondary User): Senior platform engineer or IT lead who owns the CoreCI Chat tenant. Connects MCP integrations, deploys Relay Agents, configures BYOM endpoint, manages RBAC, reviews audit logs. Pain is setup time for a small team.

3.2 Happy Paths

Journey 1 — Operator performs diagnostic investigation to achieve evidence-backed root cause in under 5 minutes

1. Step 1: Operator opens CoreCI Chat in browser → Chat UI loads with input field, history, and streaming area. (Maps to REQ-028)
2. Step 2: Operator types natural-language question and submits → Submission accepted, orchestration begins. (Maps to REQ-029)
3. Step 3: LLM (via BYOM) reasons about which abstract MCP tools to invoke → Tool selection recorded. (Maps to REQ-033)
4. Step 4: Orchestrator invokes abstract tools; gateway routes to tenant-specific adapters → Routing confirmed with tenant context. (Maps to REQ-015, REQ-016)
5. Step 5: Adapter executes read-only query (Proxmox, SSH, GitHub, or Gitea); read-only enforced at both layers → Query results returned, write attempts blocked. SSH commands go through whitelist enforcement. (Maps to REQ-018, REQ-020, REQ-021, REQ-022, REQ-023, REQ-024, REQ-025, REQ-026, REQ-027)
6. Step 6: Tool execution output streams to UI in real-time → Trace panel updates as each tool returns. (Maps to REQ-017, REQ-031)
7. Step 7: LLM synthesizes cited answer from tool evidence → Response rendered inline with citations. (Maps to REQ-030)
8. Step 8: If workflow exceeds 30s, state persists; user can rejoin → Resume works seamlessly. (Maps to REQ-036, REQ-037)
9. Step 9: Audit log captures prompt, all tool calls (including SSH commands), all responses → Immutable entries written. (Maps to REQ-038)
10. Step 10: Conversation history persisted per user/tenant → Available next session. (Maps to REQ-032)

• Testable Acceptance (BDD Format):
  • Given an Operator is authenticated and on the chat page, when they submit "why is web-server-01 throwing 503s in production", then within 5 minutes (p95) the response includes a cited root-cause hypothesis referencing at least one tool execution (Proxmox VM state, SSH service status, or recent deploy commit).
  • Given the LLM invokes a tool, when the tool returns, then a tool trace entry is rendered in the UI within 1 second of the return.
  • Given the workflow completes, when the Operator refreshes or returns later, then the conversation is fully retrievable with prompts, tool calls, SSH command outputs, and responses.

Journey 2 — Platform Lead onboards a CoreCI Chat tenant to achieve working integration in under 2 hours

1. Step 1: Platform Lead signs up via SSO → Session established, tenant created, user assigned Admin. (Maps to REQ-001, REQ-002)
2. Step 2: Platform Lead configures BYOM endpoint (URL + API key) → Endpoint validated with green test call. (Maps to REQ-006, REQ-007)
3. Step 3: Platform Lead runs Relay Agent install script on target Linux host(s) → systemd service installed and started. (Maps to REQ-010, REQ-011)
4. Step 4: Relay Agent establishes outbound WebSocket → Registered with tenant + target metadata (hostname, OS, IP). (Maps to REQ-012)
5. Step 5: Platform Lead configures Day 1 integrations (Proxmox, SSH targets, GitHub or Gitea) → Adapters activated with credentials. (Maps to REQ-020, REQ-021, REQ-022, REQ-023, REQ-025, REQ-026, REQ-027)
6. Step 6: Platform Lead verifies multi-target scope where applicable → Target selector functions correctly. (Maps to REQ-024)
7. Step 7: Platform Lead assigns RBAC roles (Operator, Viewer) to team members → Roles enforced on next API call. (Maps to REQ-003, REQ-004, REQ-005)
8. Step 8: Platform Lead runs smoke-test investigation → End-to-end diagnostic returns expected result. (Maps to REQ-033, REQ-034, REQ-035)
9. Step 9: Relay Agent health and logs visible in admin dashboard → Status green, logs accessible. (Maps to REQ-014)
10. Step 10: Usage metering is active → Counters increment for tool calls, LLM tokens, workflow executions. (Maps to REQ-043, REQ-044)

• Testable Acceptance (BDD Format):
  • Given a Platform Lead completes signup via SSO, when the dashboard loads, then a new tenant exists with the user as Admin and all onboarding steps are visible.
  • Given the Relay Agent install script is executed with valid tenant credentials, when the systemd service starts, then an outbound WebSocket to CoreCI Chat SaaS is established within 60 seconds and health status turns green.
  • Given all onboarding steps complete, when the Platform Lead runs the smoke-test scenario, then the diagnostic returns a result, audit log entries are written (including SSH commands if invoked), and usage counters increment.

3.3 Failure & Edge Paths

• Edge 1 (J1): BYOM endpoint unreachable mid-workflow → System displays actionable error, suggests reconfiguration, halts workflow. Handled via REQ-009.
• Edge 2 (J1): LLM step limit hit (>20 tool calls) → Workflow halts with clear error to user; partial results preserved. Handled via REQ-035.
• Edge 3 (J1): MCP adapter times out → Surface timeout with retry option; tool trace shows failure. Handled via REQ-016, REQ-017.
• Edge 4 (J1): Relay Agent WebSocket drops mid-investigation → Auto-reconnect via exponential backoff; workflow resumes from durable state. Handled via REQ-013, REQ-036.
• Edge 5 (J1): Rate limit hit → HTTP 429 surfaced with retry-after window. Handled via REQ-019.
• Edge 6 (J1): Multi-target scope ambiguous (multiple targets registered, no selection) → Prompt user to select target before tool execution. Handled via REQ-024.
• Edge 7 (J1): Audit log write fails → Operation halts; admin alerted; no silent drops. Handled via REQ-038.
• Edge 8 (J1): Write-action request submitted to MCP gateway → Rejected with HTTP 403 and audited. Handled via REQ-018.
• Edge 9 (J1): SSH command not on whitelist → Command rejected at Relay Agent, error returned to LLM, audit log records attempt. Handled via REQ-026.
• Edge 10 (J2): SSO provider down → Error displayed with retry; tenant creation blocked. Handled via REQ-001.
• Edge 11 (J2): BYOM endpoint test fails on save → Save blocked; error details surfaced. Handled via REQ-007.
• Edge 12 (J2): Relay Agent fails to register → Registration error with troubleshooting link; dashboard shows red status. Handled via REQ-012.
• Edge 13 (J2): MCP adapter auth fails (Proxmox token, SSH key, Git token) → Credential validation error; integration not activated. Handled via REQ-025, REQ-026, REQ-027.
• Edge 14 (J2): Smoke-test investigation fails → Specific failure point surfaced (LLM, adapter, network, auth). Handled via REQ-033, REQ-034.
• Edge 15 (J2): Email invitation bounces → Admin notified; invitation marked invalid. Handled via REQ-003.
• Edge 16 (J2): Unsupported OS detected during Relay Agent install → Install aborted with clear message listing supported OS versions. Handled via REQ-010.

---

4. Functional Requirements

Every REQ must map to at least one journey and possess testable criteria.

ID	Title	Journeys	Priority	Acceptance Criteria (Given/When/Then or explicit rules)
REQ-001	Establish SSO session via identity provider	J2	High	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.
REQ-002	Provision tenant on first signup	J2	High	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	Invite users to tenant via email	J2	High	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.
REQ-004	Apply RBAC role to user	J2	High	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	Enforce RBAC at API gateway	J1, J2	High	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.
REQ-006	Configure BYOM endpoint (URL + API key)	J2	High	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	Validate BYOM endpoint connectivity on save	J2	High	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.
REQ-008	Route all LLM inference to configured BYOM endpoint	J1, J2	High	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	Reject LLM request when BYOM is unconfigured or unreachable	J1, J2	High	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.
REQ-010	Distribute Relay Agent as systemd service via install script	J2	High	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.
REQ-011	Establish outbound WebSocket from Relay Agent to SaaS	J2	High	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	Register Relay Agent with tenant + target metadata	J2	High	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.
REQ-013	Maintain heartbeat and auto-reconnect on WebSocket drop	J2	High	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.
REQ-014	Surface Relay Agent health and logs in admin dashboard	J2	Med	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.
REQ-015	Define abstract MCP tool schema	J1, J2	High	Given the MCP gateway receives a call, when it routes, then calls match one of the approved abstract tools: get_logs, list_resources, describe_topology, get_recent_deploys, list_events, get_metrics, list_ci_runs, get_ci_run.
REQ-016	Route abstract MCP calls to tenant-specific adapter	J1, J2	High	Given an Operator submits a prompt, when the LLM requests an abstract tool, then the gateway routes to the tenant's specific adapter (Proxmox, SSH, GitHub, or Gitea) based on tool type and tenant config.
REQ-017	Stream tool execution output to chat UI via SSE	J1	High	Given an Operator submits a prompt, when tool calls execute, then partial results are streamed to the UI within 1 second of each tool return.
REQ-018	Enforce read-only at MCP gateway proxy layer	J1, J2	High	Given any write-action request (POST, PUT, DELETE, PATCH) is submitted to MCP, when the gateway processes it, then the request is rejected with HTTP 403 and audited.
REQ-019	Apply token-bucket rate limit per user and per tenant	J1	Med	Given a user exceeds 60 req/min or a tenant exceeds 300 req/min, when the next request arrives, then the request is rejected with HTTP 429 and the limit window is communicated.
REQ-020	Implement read-only Proxmox MCP adapter	J1, J2	High	Given an Operator requests VM list or VM status, when the adapter executes, then a list of VMs (ID, name, status, node, resource allocation) is returned, no state mutation is possible, and the audit log records the call. Supports Proxmox VE 7.x and 8.x.
REQ-021	Implement read-only SSH/Linux Server MCP adapter	J1, J2	High	Given an Operator requests system state (e.g., service status, disk usage, recent logs), when the adapter executes, then a whitelisted read-only command runs via SSH and the output is returned; commands not on the whitelist are rejected at the Relay Agent layer; audit log records the full command and output.
REQ-022	Implement read-only GitHub MCP adapter	J1, J2	High	Given an Operator requests recent commits, PRs, or Actions workflow runs, when the adapter executes, then the requested data is returned, no state mutation is possible, and the audit log records the call.
REQ-023	Implement read-only Gitea MCP adapter	J1, J2	High	Given an Operator requests repositories, commits, PRs, or Gitea Actions runs, when the adapter executes, then the requested data is returned, no state mutation is possible, and the audit log records the call.
REQ-024	Scope MCP queries to explicitly selected target in multi-target tenants	J1, J2	High	Given a tenant has ≥2 registered targets and the Operator selects target X, when any MCP call executes, then only target X is queried and results are labeled with target identifier.
REQ-025	Authenticate to Proxmox via scoped API token + read-only role	J2	High	Given a customer creates a Proxmox user with PVEAuditor role and generates an API token, when the adapter authenticates, then API calls succeed only for read-only operations; the token is stored in the secret manager.
REQ-026	Authenticate to Linux servers via SSH key with command whitelist enforcement at Relay Agent	J2	High	Given a customer generates an SSH keypair for the Relay Agent and authorizes it on the target host, when the Relay Agent receives a tool call, then only commands on the approved whitelist (cat, ls, systemctl status, journalctl, df, du, ps, top, ss, netstat, ip, uptime, uname, etc.) are executed; non-whitelisted commands are rejected and audited.
REQ-027	Authenticate to GitHub and Gitea via scoped API tokens	J2	High	Given a customer provides a GitHub or Gitea API token with read-only scope, when the adapter authenticates, then API calls succeed only for permitted resources; the token is stored in the secret manager.
REQ-028	Render chat interface in browser	J1	High	Given an Operator navigates to CoreCI Chat, when the page loads, then a chat interface renders with input field, message history, and streaming output area.
REQ-029	Accept natural language input and submit for orchestration	J1	High	Given an Operator types a question and submits, when the submission is processed, then the prompt is sent to the LLM orchestrator and streaming response begins within 3 seconds (p95).
REQ-030	Display streaming LLM response with inline citations	J1	High	Given the LLM returns a response, when the response streams to the UI, then citations referencing specific tool calls or evidence are rendered inline and clickable to expand the underlying evidence (including raw SSH command output where applicable).
REQ-031	Display streaming tool execution traces	J1	High	Given the orchestrator invokes tools, when each tool returns, then the UI displays the tool name, target, and a snippet of the result in a collapsible trace panel (SSH commands show full command + output snippet).
REQ-032	Persist conversation history per user/tenant	J1	High	Given an Operator completes a conversation, when they reload or return later, then the conversation is retrievable in full (prompts, tool calls, responses).
REQ-033	Reason about which MCP tools to invoke from user prompt	J1	High	Given an Operator asks a diagnostic question, when orchestration runs, then the LLM invokes at least one relevant abstract MCP tool (e.g., get_logs, list_resources, get_recent_deploys).
REQ-034	Execute multi-step tool sequences (LLM-driven dynamic workflows)	J1	High	Given a complex question, when orchestration runs, then the LLM can chain multiple tool calls in sequence, with each result informing the next call.
REQ-035	Apply LLM step limit to prevent infinite loops	J1	Med	Given an LLM attempts >20 tool calls in a single workflow, when the limit is reached, then the workflow halts with a clear error to the user and partial results are preserved.
REQ-036	Persist workflow state across async boundaries via durable execution	J1	High	Given a workflow exceeds 30 seconds (e.g., long log query, slow SSH execution), when orchestration suspends, then state is persisted to durable execution store and the workflow can resume.
REQ-037	Allow user to rejoin in-progress async workflow	J1	High	Given a workflow is in progress, when the Operator refreshes or returns, then they see current workflow state and can resume interaction.
REQ-038	Log every prompt, tool call, SSH command, and response to immutable audit store	J1, J2	High	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.
REQ-039	Implement Row-Level Security on all tenant-scoped data	J1, J2	High	Given any database query is executed, when the query runs, then RLS policies enforce tenant scoping and cross-tenant queries return empty results.
REQ-040	Store tenant credentials in centralized secret manager	J2	High	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.
REQ-041	Publish "SOC 2 Type 1 Audit in Progress" posture	J2	Med	Given a prospect visits the security page, when they read, then the "Audit in Progress" posture is clearly stated with target completion timeline and current control coverage.
REQ-042	Instrument GRC platform with control evidence	J2	Med	Given CoreCI Chat runs in production, when the GRC platform syncs, then evidence of controls (access logs, change management, vendor risk, incident response) is automatically collected.
REQ-043	Meter tool calls, LLM tokens, and workflow executions per tenant	J1, J2	High	Given a tenant uses CoreCI Chat, when usage events occur, then counters increment for tool calls, LLM tokens, and workflow executions, and values are queryable per tenant per day.
REQ-044	Display per-tenant usage dashboard to Admin	J2	Med	Given an Admin opens the usage dashboard, when the page loads, then current period tool calls, LLM tokens, workflow executions, and projected cost are displayed.

---

5. Technical Constraints & NFRs (Non-Functional Requirements)

• Read-Only by Default: No write actions permitted at MCP gateway or Relay Agent layers. Threshold: 100% of write-action requests rejected at both layers with HTTP 403 (REQ-018). SSH write commands rejected at Relay Agent (REQ-026).
• BYOM Mandatory: All LLM inference routed to customer-configured endpoint. Threshold: 100% of inference calls outbound to customer endpoint; zero inference calls originate from CoreCI Chat infrastructure (REQ-008, REQ-009).
• Multi-Tenancy Isolation: All tenant-scoped data protected by Row-Level Security. Threshold: Zero cross-tenant data exposure verified via quarterly pen tests (REQ-039).
• Audit Log Immutability: All prompts, tool calls, SSH commands, and responses logged to write-once store. Threshold: 100% capture rate, zero deletes permitted (REQ-038).
• SSH Command Whitelist Enforcement: Relay Agent enforces command whitelist for all SSH-issued commands. Threshold: 100% of SSH commands checked against whitelist before execution; non-whitelisted commands rejected and audited (REQ-026).
• Supported Target Operating Systems: Ubuntu 24.04 LTS and Debian 12 (Bookworm) or later. Install script aborts on unsupported OS (REQ-010).
• Supported Proxmox Versions: Proxmox VE 7.x and 8.x. Older versions explicitly unsupported (REQ-020).
• Time to First Streamed Token: <3 seconds (p95) from user submission to first visible token.
• Diagnostic Completion Time: <5 minutes (p95) for typical investigation (≤10 tool calls).
• Concurrent Workflows per Tenant: ≥5 concurrent investigations per tenant.
• LLM Step Limit: ≤20 tool calls per workflow.
• Conversation History Retention: 90 days minimum, 1 year target.
• SaaS Availability Target: 99.5% uptime MVP, 99.9% target post-MVP.
• Relay Agent Reconnection: Auto-reconnect within 30 seconds of drop, exponential backoff, max 5 attempts before alerting; systemd auto-restarts on hard failure (REQ-013).
• Browser Support: Latest 2 versions of Chrome, Firefox, Safari, Edge.
• Rate Limiting: Token-bucket, 60 req/min per user, 300 req/min per tenant (REQ-019).
• Encryption: TLS 1.2+ in transit, AES-256 at rest.
• Secret Handling: All credentials stored in centralized secret manager (AWS Secrets Manager or equivalent); never logged in plaintext (REQ-040).
• Single-Region Deployment: MVP deploys to one region (us-east-1 default).
• Browser-Only Chat UI: No mobile apps, no native apps, no CLI, no Slack/Teams in MVP.
• Systemd-Only Relay Agent Distribution: Distributed exclusively as a systemd service via install script (REQ-010).
• Per-Target Relay Agent Model: Each Relay Agent registers as one target and queries only its own host. Multi-target environments deploy multiple agents (REQ-012, REQ-026).
• Outbound-Only Network Model: Relay Agent establishes outbound WebSocket to CoreCI Chat SaaS. No inbound firewall rules required from customer (REQ-011).
• Self-Hosted Gitea Limitation: CoreCI Chat SaaS requires network access to customer's self-hosted Gitea instance for read-only API calls. Customers must expose the Gitea API endpoint or run a Relay Agent locally.
• Async Durable Execution Runtime: Trigger.dev — best DX for TypeScript-first team, supports long-running workflows, cost-effective at MVP scale.
• Identity Provider: WorkOS — best enterprise SAML/SSO/SCIM coverage at mid-market price point; clean separation from product user model.
• GRC Platform: Vanta — best ecosystem integrations for AWS-native stacks; mature control monitoring.

---

6. Milestone Plan & Release Gates

Test evidence required for Production Release:

• Code coverage ≥ 80% on new modules
• CI/CD pipeline builds successfully (GREEN)
• QA sign-off: 100% of Journey 1 and Journey 2 integration tests pass
• Security/Compliance review approved (audit logging, RLS, secret handling, read-only enforcement, SSH whitelist enforcement verified)
• All Milestone 1, 2, and 3 acceptance gates passed (Section 2.3)
• All 16 Failure & Edge Paths have passing test cases (Section 3.3)
• Load test: ≥5 concurrent workflows per tenant sustained for 1 hour with no degradation
• Pen test: Cross-tenant data leakage test passed (zero leakage)
• SSH whitelist test: Attempt to execute non-whitelisted command (e.g., rm -rf /tmp/test) and verify rejection at Relay Agent with audit log entry
• Documentation: Admin onboarding guide, Operator quick-start, security & compliance page, public status page, Relay Agent install guide

Pre-Production Design Partner Gate (recommended before GA):

• At least 1 mid-market design partner (ideally existing CoreCI customer) completes full onboarding via Journey 2
• At least 3 distinct Operators across 2 design partners complete ≥10 diagnostic investigations via Journey 1
• Audit logs (including SSH command capture), usage metering, and Relay Agent health verified end-to-end in production-like environment

---

7. Open Questions & Assumptions

Unresolved product or architectural questions. All questions below were resolved and approved by Product Owner on 2026-08-24.

1. Async Durable Execution Runtime — Trigger.dev vs Inngest vs Temporal.

   • Decision: Trigger.dev — best DX for TypeScript-first team, supports long-running workflows, cost-effective at MVP scale.

2. Identity Provider — WorkOS vs Clerk vs Auth0.

   • Decision: WorkOS — best enterprise SAML/SSO/SCIM coverage at mid-market price point; clean separation from product user model.

3. GRC Platform — Vanta vs Drata vs Secureframe.

   • Decision: Vanta — best ecosystem integrations for AWS-native stacks; mature control monitoring.

4. Relay Agent Distribution Mechanism — Install script (curl|bash) vs apt package vs Docker container.

   • Decision: Install script (curl|bash) with apt package as fallback — install script is fastest to ship and most flexible; apt package for design partners that prefer managed distribution. Docker container deferred to v1.1+.

5. SSH Command Whitelist Maintenance — Ship fixed whitelist with Relay Agent vs allow customer extension via config file.

   • Decision: Ship fixed whitelist initially; allow customer extension via signed config in v1.1 — fixed whitelist is more secure for v0.1; extension mechanism requires careful design (signed configs, audit logging on whitelist changes).

6. Proxmox Permission Model — Built-in PVEAuditor role vs custom role with finer-grained permissions.

   • Decision: Built-in PVEAuditor for v0.1 — simpler setup, well-understood scope. Custom role support in v1.1 if design partners request specific restrictions.

7. Self-Hosted Gitea Access Pattern — Customer exposes API to SaaS vs Relay Agent on Gitea host.

   • Decision: Customer exposes API to SaaS for v0.1 (with documented firewall rules); Relay Agent variant deferred until demand justifies the engineering.

8. Vector Store for v1.1 RAG (future-facing, not v0.1) — PostgreSQL+pgvector vs dedicated (Pinecone, Weaviate).

   • Decision: pgvector — avoids new infrastructure; co-located with primary database.

---

8. Changelog

Version	Date	Author	What Changed	REQs Affected
v1.0	2026-08-24	Sarah Chen	Initial Draft generated from Steer Vision v1.0 and locked Phase 2 scope (superseded by v1.1)	REQ-001 – REQ-043 (original)
v1.1	2026-08-24	Sarah Chen	Major revision per product owner pivot: Product renamed CoreCI Chat (companion to existing CoreCI CI/CD platform). Removed all Kubernetes, ArgoCD, and Helm dependencies. Replaced Kubernetes MCP adapter with Proxmox MCP adapter. Removed ArgoCD MCP adapter. Added SSH/Linux Server MCP adapter with command whitelist enforcement at Relay Agent. Replaced ServiceAccount auth with SSH key auth; replaced Helm distribution with systemd service via install script. Renamed "multi-cluster" to "multi-target" scoping. Added supported OS constraint (Ubuntu 24.04, Debian 12+). Added Proxmox version support constraint (7.x, 8.x). Added 16th failure path (unsupported OS). Added 8th open question (self-hosted Gitea access pattern). Total REQs now 44 (was 43). Product Owner set to Sarah Chen.	REQ-010, REQ-011, REQ-012 (Relay Agent deployment), REQ-020 (Proxmox), REQ-021 (SSH/Linux — new), REQ-022/023 (GitHub/Gitea expanded for Actions), REQ-024 (multi-target), REQ-025 (Proxmox auth), REQ-026 (SSH auth + whitelist), REQ-027 (Git auth — new split), REQ-038 (audit log expanded for SSH commands)

---

End of CoreCI Chat v0.1 Engineering Specification v1.1

Product Owner: Sarah Chen — Locked 2026-08-24 — Ready for ciagent Milestone 1 implementation.