coreci-chat/.ciagent/PLAN.md

Plan — Milestone 1 (v0.1)

Source spec: .ciagent/steer-v0.1-spec.md (v1.1, locked 2026-08-24). M1 scope: REQ-001..014, REQ-038, REQ-039, REQ-040 (17 REQs). M1 acceptance gate: spec §2.3. Architecture: .ciagent/ARCHITECTURE.md. Decisions: .ciagent/CLARIFY.md. Research: .ciagent/RESEARCH.md. Personas: .ciagent/PERSONAS.md.

M1 is decomposed into 5 execution phases (Waves A–E). Each wave is a vertical slice: scaffolds + implements + tests + ships a patch on the v0.0.x line. Each wave maps to explicit REQ IDs and has must-have verification items. Waves are ordered by dependency; A → B → C may overlap (B starts once A's withTenant + audit are green); D is independent of B/C and can run in parallel; E depends on B + D.

Phase mapping (CIAgent phase model)

CIAgent phase	Wave	Branch	Patch tag	REQs
Phase 0	pre-execution	phase/00-pre-execution	v0.0.1	(this plan)
Phase 1	Wave A — Foundations	phase/01-foundations	v0.0.2	REQ-038, REQ-039, REQ-040
Phase 2	Wave B — Identity & RBAC	phase/02-identity-rbac	v0.0.3	REQ-001, REQ-002, REQ-003, REQ-004, REQ-005
Phase 3	Wave C — BYOM	phase/03-byom	v0.0.4	REQ-006, REQ-007, REQ-008, REQ-009
Phase 4	Wave D — Relay Agent	phase/04-relay-agent	v0.0.5	REQ-010, REQ-011, REQ-012, REQ-013, REQ-026 (whitelist hook)
Phase 5	Wave E — Dashboard surfacing	phase/05-dashboard	v0.0.6	REQ-014
Phase 6	Final — Review + Ship	phase/06-final-review-ship	v0.0.7 ← milestone release	all M1

Tags run on the v0.0.x patch line (no prior minor). The final phase's patch (v0.0.7) IS the v0.1 milestone release. The milestone merge to main happens at the final phase.

Grill fixes applied (G-001..G-010)

This plan was grilled (.ciagent/GRILL.md, verdict PASS-WITH-FIXES). The 10 binding fixes are integrated below and flagged inline as [G-NNN]. Summary:

• G-001 (Wave C): /api/byom/test-inference is a plan-time proxy for REQ-008 (no M3 orchestration to drive inference); marked for M3 deprecation; PO-acknowledged.
• G-002 (Wave A): Trigger.dev health-check ticks write to a runtime_health table, NOT audit_log. REQ-038's auditable events are business events only.
• G-003 (Wave A + D): Trigger.dev bootstrap + SSH whitelist hook are pre-investments for M2/M3, with one-line expected payoff.
• G-004 (Wave D): CheckCommand(cmd) error signature + whitelist JSON schema are the M2 SSH adapter contract; changes require a documented migration.
• G-005 (Wave A + B + D): POST /api/relay/issue-token owned by backend-engineer; token contract (format/scope/lifetime) defined in Wave A secrets package so B and D parallelize without blocking.
• G-006 (Wave A): per-tenant hash-chain serializes concurrent audit writes via constraint-trigger rollback — known M1-acceptable limit; M3 mitigation documented.
• G-007 (Wave D): shadow exec.Cmd integration test proves CheckCommand composes with os/exec without a live SSH server.
• G-008 (Wave D): M1 ships REQ-026 partially (whitelist file + hook + tests); spec §4 SSH-key-auth + tool-call execution are M2.
• G-009 (Wave D): unsupported-OS test matrix is ≥2 cases (Fedora + Alpine), not a single container.
• G-010 (Wave A): two-tier credential taxonomy — infra/bootstrap creds (env vars, listed) vs tenant creds (SecretProvider only). PO's "no env vars" applies to tenant creds.

Credential taxonomy [G-010]

The PO's "no env vars, no config files, no DB columns. Ever." (REQ-040) applies to tenant credentials. The platform has a two-tier model:

• Tier (a) — Infra/bootstrap credentials (platform-level, NOT tenant-scoped): loaded via packages/config from environment variables. These are: DATABASE_URL, WORKOS_API_KEY, TRIGGER_API_KEY, TRIGGER_API_URL, AWS_REGION, AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY (or IAM role), SECRET_MASTER_KEY_DEV (dev/test only). They are never tenant secrets.
• Tier (b) — Tenant credentials (BYOM key, Proxmox token, SSH key, Git token, tenant registration token): via SecretProvider ONLY. Never env vars, never config files, never DB columns. The DB stores only a SecretRef.

This two-tier model is the documented exception to the PO's verbatim "no env vars" claim and will be cited in the M1 security review.

---

User-Facing Surface (MVP/UX §1)

M1 ships ONE user-facing surface: the Platform Lead admin dashboard (browser, Next.js, at /dashboard). The chat UI is M3 — explicitly not in M1.

M1 dashboard surfaces (each is a pass/fail QA surface):

1. SSO entry (/login): "Sign in with SSO" button → WorkOS redirect → session → /dashboard redirect. (REQ-001)
2. Onboarding checklist (/dashboard): first-tenant view shows the 5 onboarding steps with status badges (grey/green): Configure BYOM, Install Relay Agent, Register Target, Verify Green Status, Invite Team. (REQ-002)
3. BYOM config form (/dashboard/byom): URL input + API key input + "Validate & Save" button. On save: green "Validated" badge with the test inference result, or red error panel with details. (REQ-006, REQ-007)
4. Relay Agent install instructions (/dashboard/relay): per-tenant curl|bash install command with the tenant registration token embedded; supported OS list shown; "unsupported OS" callout. (REQ-010)
5. Targets list (/dashboard/targets): one row per registered Relay Agent — hostname, OS, IP, agent version, health (green/yellow/red), last-seen, "View logs" link. (REQ-012, REQ-014)
6. Target detail (/dashboard/targets/<id>): health badge, last 100 log lines (streamed via WebSocket fan-out), registration metadata. (REQ-014)
7. Team / RBAC (/dashboard/team): list members + role; "Invite" form (email → single-use link); role change dropdown (Admin/Operator/Viewer). (REQ-003, REQ-004)
8. Audit export (/dashboard/audit): admin-only "Download audit log (CSV)" button — no query UI in MVP (spec §2.2). (REQ-038)

Non-UI surfaces: the Relay Agent install script (curl|bash), the Go binary, the systemd unit. These are operator-facing artifacts, documented in the install guide.

Happy Path (MVP/UX §2)

End-to-end M1 scenario (maps to spec Journey 2 steps 1–4 + 7 + 9), written before EXECUTE:

Given a fresh CoreCI Chat deployment with Postgres + WorkOS + AWS Secrets Manager configured, when a Platform Lead completes the M1 onboarding, then the M1 acceptance gate (spec §2.3) passes: SSO signup → BYOM green validation → Relay Agent install on a target Linux host → target registered → green status in the admin dashboard. Audit logging, RLS, and secret manager are operational.

BDD steps:

1. Given an unauthenticated visitor, when they hit /login and complete WorkOS SSO, then a tenant is provisioned (first signup), they are assigned Admin, and /dashboard loads with the 5-step onboarding checklist (all grey). (REQ-001, REQ-002)
2. Given the Admin on /dashboard/byom, when they submit a valid BYOM URL + API key and click "Validate & Save", then the API key is stored in the secret manager (not the DB), a test inference call to /v1/chat/completions returns 200, the endpoint row is inserted under RLS, the checklist step turns green, and an audit entry is appended. (REQ-006, REQ-007, REQ-038, REQ-039, REQ-040)
3. Given the Admin on /dashboard/relay, when they copy the curl|bash command and run it on an Ubuntu 24.04 host, then the install script detects Ubuntu, downloads the Go binary, verifies the checksum, writes the systemd unit, writes the tenant token to /etc/coreci/relay.env, enables + starts the service, and exits 0. (REQ-010)
4. Given the systemd service is running, when the Relay Agent starts, then it opens an outbound WebSocket to the SaaS within 60s, registers (tenant/target/hostname/Ubuntu 24.04/IP/version), the control plane inserts a targets row under RLS + appends an audit entry, and the dashboard /targets list shows the new row. (REQ-011, REQ-012, REQ-038, REQ-039)
5. Given the Relay Agent is registered, when it sends a heartbeat every 30s, then last_seen updates and the dashboard health badge is green. (REQ-013, REQ-014)
6. Given the Admin on /dashboard/team, when they invite ops@example.com as Operator, then WorkOS sends a single-use acceptance link; when the invitee accepts and hits the API, RBAC enforces Operator permissions (e.g., cannot edit BYOM). (REQ-003, REQ-004, REQ-005)
7. Given a second tenant T2 exists, when T1's user issues any DB query, then RLS returns zero T2 rows (cross-tenant pen test passes). (REQ-039)
8. Given the unsupported-OS case, when the install script runs on Fedora, then it exits non-zero with a message listing Ubuntu 24.04 LTS and Debian 12+. (REQ-010, Edge 16)

This Happy Path is the M1 demo recording required by the M1 review.

UX Acceptance Criteria (MVP/UX §3)

1. SSO works in <3 clicks from /login to /dashboard for a returning user (REQ-001).
2. BYOM validation feedback is synchronous — the "Validate & Save" button shows a spinner and resolves in <10s with a green/red result (REQ-007).
3. Dashboard health badge turns green within 90s of the Relay Agent's first heartbeat (REQ-013, REQ-014).
4. Install command is copy-pasteable — the /dashboard/relay page shows one curl -fsSL <url> | sh line with the tenant token already embedded; no manual editing required (REQ-010).
5. RBAC is enforced on the very next API call after a role change — the dashboard re-fetches and the new permissions apply immediately (REQ-004, REQ-005).
6. Cross-tenant isolation is verifiable — the M1 pen-test script demonstrates zero leakage across two tenants (REQ-039).
7. Audit log is append-only — a test that attempts UPDATE/DELETE on audit_log as the app role fails with a permission error (REQ-038).
8. Secrets are never in the DB — a test that scans byom_endpoints and all tenant-scoped tables for plaintext credentials passes (returns zero matches); secrets are resolvable only via SecretProvider.get (REQ-040).
9. Unsupported OS aborts cleanly — running the install script on an unsupported OS exits non-zero with an actionable message (REQ-010, Edge 16).

---

Wave A — Foundations (Phase 1)

Goal: Monorepo scaffold + Postgres schema with RLS + append-only hash-chain audit + SecretProvider interface + Trigger.dev bootstrap. No HTTP routes yet. Depends on: Phase 0. REQs covered: REQ-038, REQ-039, REQ-040. Personas: backend-engineer, data-engineer, security-engineer (sign-off).

Tasks

1. Scaffold monorepo (backend-engineer): pnpm workspace; apps/control-plane (Next.js App Router + TS), apps/relay-agent (Go module, empty for now), apps/dashboard (part of control-plane for M1), packages/{db,auth,audit,secrets,config,runtime}. tsconfig.json base + per-package extends. package.json scripts: lint, typecheck, test (vitest), migrate. turbo.json or pnpm --filter orchestration. .gitignore additions (.secrets/, node_modules, dist, .next).
2. Postgres schema + migrations (data-engineer): packages/db/migrations/0001_init.sql — tenants, users, tenant_memberships (user_id, tenant_id, role), targets, byom_endpoints (tenant_id, url, secret_ref, validated), invitations, audit_log (id BIGSERIAL, tenant_id, prev_hash, curr_hash, payload JSONB, created_at, user_id, target_id, correlation_id, event_type), runtime_health (id BIGSERIAL, component, status, payload JSONB, created_at) (NOT tenant-scoped; NOT an audit table — see G-002). All tenant-scoped tables carry tenant_id UUID NOT NULL.
3. RLS policies (data-engineer + security-engineer): per-table policy USING (tenant_id = current_setting('app.tenant_id')::uuid). packages/db/rls.sql run by the migrator. App role coreci_app with INSERT/SELECT only; REVOKE UPDATE, DELETE ON audit_log FROM coreci_app. migrator role with BYPASSRLS for migrations only.
4. withTenant helper (data-engineer): packages/db/withTenant.ts — opens a transaction, SET LOCAL app.tenant_id = $1, runs the callback, commits. Throws if called outside a transaction. Unit test: a query outside withTenant returns zero tenant-scoped rows.
5. Audit writer (backend-engineer + security-engineer): packages/audit/writer.ts — append(event) computes curr_hash = sha256(prev_hash || canonical(payload)), INSERTs inside the caller's transaction. Constraint trigger rejects a forged prev_hash. AuditWriteHaltError thrown on failure → caller's transaction rolls back. Unit test: append 3 entries, verify the chain; attempt UPDATE/DELETE → permission denied. [G-006] Known M1-acceptable limit: the per-tenant hash-chain serializes concurrent audit writes within one tenant (two simultaneous appends read the same prev_hash; the second INSERT fails the constraint and rolls back). Acceptable for M1 volume (onboarding + dashboard). M3 mitigation: pg_advisory_xact_lock(hashtext(tenantId)) before the INSERT, or a per-tenant sequence for prev_hash ordering. Documented here so M3 is not a surprise.
6. SecretProvider interface + impls (backend-engineer + security-engineer): packages/secrets/provider.ts (interface), packages/secrets/aws-sm.ts (@aws-sdk/client-secrets-manager), packages/secrets/local-encrypted.ts (AES-256-GCM, master key from SECRET_MASTER_KEY_DEV). SecretValue type with [REDACTED] toString. Unit tests for both impls.
7. Trigger.dev bootstrap (backend-engineer): packages/runtime/index.ts — initializes the Trigger.dev client from config; registers a runtimeHealthCheck task that runs every 5 min and writes a row to runtime_health (NOT audit_log — see G-002; REQ-038's audit store is for business events only: prompts, tool calls, SSH commands, responses). No chat tasks. [G-003] Pre-investment for M3: shipping the runtime now means M3 chat orchestration plugs in without a runtime bootstrap rewrite; the 5-min health tick proves the runtime is wired without polluting the audit store.
8. Cross-tenant pen-test scaffold (security-engineer): tests/pen/cross-tenant.test.ts — two tenants, attempt to read T2 as T1, assert zero rows. (Full pen test runs at M1 review.)
9. Tenant registration token contract (backend-engineer + security-engineer): packages/secrets/relay-token.ts — defines the token issued by POST /api/relay/issue-token (Wave D Task 1) and consumed by the Go Relay Agent (Wave D Task 3). [G-005] Contract (locked here so Wave B's auth middleware and Wave D's WS server + agent parallelize without blocking): token is a signed JWT (HS256, key from SECRET_MASTER_KEY_DEV in dev / KMS-derived in prod — NOT a tenant secret, it's a platform bootstrap signing key in tier (a) of the credential taxonomy), claims {tenantId, scope: "relay.register", iat, exp}, lifetime 24h, refreshable. Stored as a SecretRef for re-issuance. The endpoint itself is built in Wave D; the contract + signing helper live here so neither wave blocks.

Must-haves (verify before ship)

• pnpm typecheck + pnpm lint + pnpm test green.
• Migrations run clean against a fresh Postgres 16.
• withTenant test: query outside wrapper returns zero tenant rows.
• Audit chain test: 3 appends verify; UPDATE/DELETE rejected.
• SecretProvider test: put/get round-trip for both impls; toString() returns [REDACTED].
• Cross-tenant pen-test scaffold compiles + runs (T1 sees zero T2 rows).
• Trigger.dev health task writes a runtime_health row on a 5-min tick (NOT audit_log). [G-002]
• runtime_health table is NOT tenant-scoped (no RLS); audit_log IS tenant-scoped.
• Relay token contract: JWT signed, claims {tenantId, scope: "relay.register"}, 24h lifetime; signing helper + verify helper unit-tested. [G-005]
• Audit concurrent-write limit documented in code comments (per-tenant serialization; M3 mitigation noted). [G-006]
• Code coverage ≥ 80% on packages/db, packages/audit, packages/secrets, packages/runtime.

Wave B — Identity & RBAC (Phase 2)

Goal: WorkOS SSO + session + tenant resolution + RBAC at the API gateway from the first endpoint. First HTTP routes. Depends on: Wave A (withTenant, audit). Wave B does NOT own the relay token-issuance endpoint (that's Wave D Task 1); the token contract is defined in Wave A Task 9 so B and D parallelize. [G-005] REQs covered: REQ-001, REQ-002, REQ-003, REQ-004, REQ-005. Personas: backend-engineer, frontend-engineer, security-engineer (sign-off).

Tasks

1. WorkOS SSO route (backend-engineer): /api/auth/login → WorkOS hosted SSO redirect; /api/auth/callback → code exchange → session. Session stored httpOnly cookie + sessions table row (tenant_id, user_id, role).
2. Tenant provisioning (backend-engineer): on first signup, if the WorkOS organizationId has no tenant, INSERT tenant + tenant_membership(role=Admin) inside withTenant. Audit append (provision event).
3. Tenant resolution middleware (backend-engineer): packages/auth/middleware.ts — reads cookie, loads session, SET app.tenant_id via withTenant, attaches req.user = {id, tenantId, role}.
4. RBAC enforcement (backend-engineer + security-engineer): packages/auth/rbac.ts — role → route permission map (Admin: all; Operator: read + chat; Viewer: read). Applied at the API gateway. First protected endpoint: GET /api/me (returns user + tenant). Test: Viewer calling POST /api/byom → 403.
5. Invitations (backend-engineer): POST /api/invitations (Admin only) → WorkOS invitation API → single-use link emailed. POST /api/invitations/accept → creates tenant_membership. Edge 15: bounce webhook → mark invalid.
6. Role assignment (backend-engineer): PATCH /api/team/<userId> (Admin only) → updates tenant_memberships.role. Enforced on next API call.
7. Login + dashboard shell (frontend-engineer): /login page (SSO button), /dashboard shell with the 5-step onboarding checklist (all grey — steps light up as later waves ship). /dashboard/team page (invite + role UI).

Must-haves

• SSO round-trip works (test with WorkOS sandbox).
• First signup provisions tenant + Admin role; audit entry written.
• RBAC: Viewer → 403 on Admin-only route; Operator → 200 on read.
• Role change enforced on the next API call (test).
• Invitation email sent (WorkOS); acceptance creates membership; bounce marks invalid.
• Audit entry appended for every auth event (login, provision, invite, role change).
• Coverage ≥ 80% on packages/auth.

Wave C — BYOM (Phase 3)

Goal: BYOM endpoint registry + validate-on-save + routing shim (OpenAI-compatible). No chat/orchestration in M1 — the routing shim is a proxy contract + REQ-009 reject path. Depends on: Wave A (secrets, audit, withTenant), Wave B (RBAC). REQs covered: REQ-006, REQ-007, REQ-008, REQ-009. Personas: backend-engineer, frontend-engineer, security-engineer (sign-off).

Tasks

1. BYOM endpoints table + routes (backend-engineer): POST /api/byom (Admin only) — takes {url, apiKey}; secrets.put(tenantId, "byom", apiKey) → secret_ref; INSERT byom_endpoints (url, secret_ref, validated=false) under withTenant; audit append (config event).
2. Validate-on-save (backend-engineer): after INSERT, call the BYOM validator: POST <url>/v1/chat/completions with a trivial test prompt; on 200 → UPDATE ... validated=true, audit append (validation ok), return green; on failure → DELETE the row (or mark invalid), audit append (validation fail), return error details (Edge 11). All inside one transaction per the audit-halt rule.
3. Routing shim (backend-engineer): packages/byom/router.ts — routeInference(tenantId, payload) resolves the tenant's validated endpoint via withTenant, fetches the key via secrets.get, POSTs to /v1/chat/completions. M1 exposes a test endpoint POST /api/byom/test-inference (Admin only) that calls the shim and returns the raw response. [G-001] Scope note: this endpoint is a plan-time proxy to satisfy REQ-008 ("100% of LLM inference calls routed to BYOM, verified via outbound traffic log") in the absence of M3 chat orchestration — there is no other driver of inference in M1. It is marked for M3 deprecation once the chat orchestrator (REQ-033) drives real inference. PO-acknowledged (non-blocking). The outbound traffic log test for REQ-008 runs against this endpoint's egress.
4. REQ-009 reject path (backend-engineer + security-engineer): if no validated BYOM endpoint exists or the endpoint is unreachable, routeInference throws ByomUnconfiguredError / ByomUnreachableError → API returns a clear actionable error. Test: with no endpoint configured, calling /api/byom/test-inference → 400 with actionable message; with an unreachable URL → 503 with actionable message.
5. BYOM dashboard page (frontend-engineer): /dashboard/byom — URL + API key form, "Validate & Save" button, green/red result panel, current endpoint status. /dashboard checklist step 1 turns green on validated save.

Must-haves

• Save stores key in secret manager; DB holds only secret_ref (test: scan tables for plaintext keys → zero).
• Validation POST hits the configured endpoint; green/red result accurate.
• Routing shim sends 100% of test-inference calls to the configured endpoint (outbound traffic log test).
• REQ-009: unconfigured → 400 actionable; unreachable → 503 actionable. No inference attempted.
• Audit entries for config + validation events.
• Coverage ≥ 80% on packages/byom + BYOM routes.

Wave D — Relay Agent (Phase 4)

Goal: Modular install script + Go binary + WebSocket registration + heartbeat + auto-reconnect + SSH whitelist hook (no SSH adapter yet). Depends on: Wave A (audit, withTenant, relay-token contract from Wave A Task 9 [G-005]), Wave B (auth middleware). REQs covered: REQ-010, REQ-011, REQ-012, REQ-013, REQ-026 (partial — whitelist file + hook only; see G-008). Personas: go-engineer (phase-specific), backend-engineer (control-plane WS server), security-engineer (sign-off on whitelist hook).

Scope note — REQ-026 partial coverage in M1 [G-008]

M1 ships REQ-026 partially: the whitelist file format + the CheckCommand enforcement hook + unit + shadow-exec tests. The spec §4 REQ-026 acceptance criteria (customer generates an SSH keypair; the Relay Agent receives a tool call; only whitelisted commands execute; non-whitelisted rejected + audited) describe end-to-end SSH-key-auth + tool-call-driven execution, which is M2 work (the SSH adapter plugs into the hook shipped here). M1's must-have is the hook + whitelist + tests, NOT end-to-end SSH execution. This matches the REQUIREMENTS.md traceability (REQ-026 deferred to M2; whitelist format + hook ship M1 Wave D).

Tasks

1. Tenant registration token endpoint (backend-engineer): POST /api/relay/issue-token (Admin only) — issues the per-tenant registration token defined in Wave A Task 9 [G-005] (signed JWT, scope: "relay.register", 24h). Stores a re-issuance ref via secrets.put. The dashboard /dashboard/relay page shows the curl|bash command with the token embedded.
2. WS server (backend-engineer): apps/control-plane/api/relay/ws — accepts outbound WebSocket, authenticates the tenant token (verify JWT from Wave A Task 9), on register message INSERTs targets (tenant_id, hostname, os, os_version, ip, agent_version, last_seen) under withTenant, audit append. Responds {registered, targetId}. Handles ping → updates last_seen → pong.
3. Go binary — WebSocket client (go-engineer): apps/relay-agent/main.go — reads CORECI_TENANT_TOKEN + CORECI_SAAS_URL from /etc/coreci/relay.env, connects wss://<saas>/api/relay/ws, sends register, then ping every 30s. On disconnect: exponential backoff (1/2/4/8/16s), max 5 attempts → alert + keep trying every 60s. systemd Restart=on-failure for hard crashes.
4. Install script (modular) (go-engineer): scripts/install.sh with separate functions detect_os, install_binary, write_systemd_unit, register_target, main. detect_os parses /etc/os-release (Ubuntu ≥ 24.04, Debian ≥ 12); else exit non-zero with the supported-OS list (Edge 16). install_binary downloads the Go binary for the detected arch, verifies SHA256, installs to /usr/local/bin/coreci-relay-agent. write_systemd_unit writes the unit + daemon-reload + enable --now. register_target writes /etc/coreci/relay.env with the tenant token. Idempotent (re-run upgrades).
5. apt fallback (go-engineer): documented apt package path (same script, --method=apt flag). The apt package ships the same binary + unit. (Documented; primary path is curl|bash.)
6. SSH whitelist file + enforcement hook (go-engineer + security-engineer): /etc/coreci/ssh-whitelist.json (versioned schema {"version": 1, "commands": [...], "arguments": {"deny": [...]}}; fixed list: cat, ls, systemctl status, journalctl, df, du, ps, top, ss, netstat, ip, uptime, uname, free, who, w, last, dmesg, lscpu, lspci, lsblk, mount, findmnt, hostname, "ip addr", "ip route", "ss -tlnp"; argument deny list: -exec, -execdir, --exec, |, >, >>, &, ;, &&, ||). apps/relay-agent/whitelist/check.go — CheckCommand(cmd string) error parses the command, checks base + args, returns error if rejected. Unit tests: every whitelist command passes; rm -rf, find -exec, cat /etc/shadow | nc all rejected. [G-004] Contract lock: the CheckCommand(cmd string) error signature + the whitelist JSON schema are the M2 SSH adapter contract. M2 must consume them as-shipped; any signature change requires a documented migration with a compatibility shim. [G-003] Pre-investment for M2: shipping the hook now means M2's SSH adapter plugs in without reworking the enforcement boundary; the cost is justified by avoiding the "retrofit = rewrite" risk the PO flagged. [G-007] Shadow exec.Cmd integration test: a Go test that constructs exec.Command("systemctl", "status", "nginx") from a parsed whitelist command and asserts CheckCommand accepts it (positive), plus a negative test that exec.Command("rm", "-rf", "/") is rejected by CheckCommand before the Cmd would be started — proving the hook composes with os/exec without a live SSH server. No SSH execution path in M1 — M2 plugs the adapter into CheckCommand.

Must-haves

• Install script on Ubuntu 24.04 succeeds (exit 0, systemd service running, agent connected within 60s).
• Install script on Debian 12+ succeeds (same).
• [G-009] Install script on ≥2 unsupported OSes aborts cleanly with the supported-OS list (Edge 16): at minimum one non-Debian-family (e.g., Fedora or Alpine) AND one wrong-version Debian-family (e.g., Ubuntu 22.04 or Debian 11). Single-OS "unsupported" is not sufficient evidence.
• Re-running the script upgrades, does not fail.
• Relay Agent registers with full metadata (tenant/target/hostname/OS/IP/version); audit entry written.
• Heartbeat updates last_seen; dashboard can read it (Wave E surfaces this).
• Auto-reconnect: kill the WS server, agent retries with backoff, max 5 → alert; restart server → agent reconnects.
• CheckCommand: every whitelist command passes; every deny-list case rejected. Coverage 100% on the whitelist module.
• [G-007] Shadow exec.Cmd test: positive (systemctl status nginx accepted, composes to exec.Command) + negative (rm -rf / rejected pre-start) both pass.
• Whitelist file format is versioned (JSON {"version": 1, ...}). [G-004]
• CheckCommand(cmd string) error signature + whitelist JSON schema documented as the M2 contract. [G-004]

Wave E — Dashboard surfacing (Phase 5)

Goal: Dashboard shows Relay Agent health (green/yellow/red), target hostname, last 100 log lines, per-tenant view under RLS. M1 gate demo path complete. Depends on: Wave B (auth, dashboard shell), Wave D (Relay Agent + WS server). REQs covered: REQ-014. Personas: frontend-engineer, backend-engineer.

Tasks

1. Status fan-out WebSocket (backend-engineer): apps/control-plane/api/relay/status — Admin-authenticated WS that pushes target status changes (health, last_seen, log lines) to connected dashboard clients. Status computed from targets.last_seen (green < 60s, yellow < 5min, red > 5min).
2. Targets list page (frontend-engineer): /dashboard/targets — server component fetches targets via the API (under RLS), renders rows (hostname, OS, IP, version, health badge, last-seen, "View logs"). Client component subscribes to the status WS for live updates.
3. Target detail page (frontend-engineer): /dashboard/targets/<id> — health badge, registration metadata, last 100 log lines (streamed). Under RLS (T1 admin cannot view T2's target — pen-test asserts).
4. Onboarding checklist completion (frontend-engineer): /dashboard checklist step "Verify Green Status" turns green when at least one target is green. The M1 demo path (SSO → BYOM green → install → register → green dashboard) is end-to-end walkable.
5. Audit export (backend-engineer + frontend-engineer): /dashboard/audit — admin-only "Download CSV" button. No query UI (spec §2.2). CSV scoped to the tenant under RLS.

Must-haves

• Dashboard shows a registered target as green within 90s of first heartbeat.
• Killing the agent → badge turns yellow then red as last_seen ages.
• Restarting the agent → badge turns green again.
• T1 admin cannot view T2's target (RLS pen-test asserts).
• Last 100 log lines render on the target detail page.
• Audit CSV export is tenant-scoped (no cross-tenant rows).
• The full M1 Happy Path (UX §2) is walkable end-to-end.

---

Final Phase — Review + Ship (Phase 6)

Goal: Multi-persona code review + project health audit + milestone ship (v0.1.0 release, merge to main). REQs covered: all M1 (sign-off).

Tasks

1. Code review (lead-developer + all personas): review all changes in milestone/v0.1-bootstrap since main. Auto-apply P0 fixes; flag P1+ for post-hoc.
2. Audit (lead-developer): reconstruction test (git log matches .ciagent/ files); file/branch/commit discipline; cross-tenant pen test runs green; install script runs on the 3 OS cases (Ubuntu 24.04 pass, Debian 12+ pass, unsupported abort).
3. M1 acceptance gate verification (lead-developer): spec §2.3 — Platform Lead can SSO → BYOM green → install → register → green dashboard. Audit/RLS/secrets operational.
4. Milestone ship: tag v0.0.7 (final phase patch = v0.1 milestone release); merge phase/06 → milestone/v0.1-bootstrap → main; create Gitea release with full milestone summary; build + upload Relay Agent binaries (linux amd64/arm64) + install script + apt package.
5. Complete: mark all M1 REQs complete in REQUIREMENTS.md; mark milestone complete in ROADMAP.md; clear checkpoint.

M1 review deliverables (per Sarah's kickoff)

1. Per-REQ pass/fail test report with evidence (17 REQs).
2. Demo recording: fresh tenant → SSO → BYOM green → install → register → green dashboard.
3. Cross-tenant isolation pen test result (zero leakage).
4. Install script logs: Ubuntu 24.04 (pass), Debian 12+ (pass), unsupported OS (clean abort).

---

Wave ordering & parallelism

Phase 0 (this plan) ──▶ Wave A (foundations)
                          │
                          ├──▶ Wave B (identity/RBAC) ──▶ Wave E (dashboard) ──▶ Final
                          │                                  ▲
                          └──▶ Wave C (BYOM) ─────────────────┤
                                                          │
                          Wave D (relay agent) ─────────────┘

• A must complete first (B, C, D all depend on withTenant + audit + secrets).
• B and C can run in parallel after A (different territories; both depend on A only).
• D can run in parallel after A (independent of B/C; the WS server in D needs B's auth token-issuance endpoint — coordinate the contract in the plan, then D's WS server + B's token endpoint can land in the same wave window).
• E depends on B (dashboard shell + auth) and D (agent + WS server).
• Final depends on all.

Test strategy

• Unit: vitest in packages/* + apps/control-plane; Go testing in apps/relay-agent.
• Integration: a Postgres 16 container in CI; withTenant + audit + RLS + secrets tests against it.
• Pen test: tests/pen/cross-tenant.test.ts runs at Wave A (scaffold) and Final (full).
• Install test: CI matrix runs scripts/install.sh on Ubuntu 24.04, Debian 12, Fedora (expects abort) containers.
• Coverage gate: ≥ 80% on new modules (spec §6).
• Lint + typecheck: pnpm lint + pnpm typecheck must be green before any wave ships.