Open_Ultra_SAST/.kiro/specs/plane-on-kubernetes/requirements.md

Requirements Document

Introduction

The plane moves from this laptop's kind cluster to a Kubernetes cluster of the maintainer's choosing without changing what runs: the same ax manifests, runner image, memory store and credential path. Every host-bound piece becomes a cluster resource or a configuration value, each change is proven on kind first, and the production entry point (a delta Run for a push) is added. Context: brief.md, docs/deployment.md.

Boundary Context

• In scope: two profiles of one code base, kind (local, kept) and k3s (production); a remote execution mode of the CLI; artifacts delivered to the store; configurable cluster context, registry and image pins; our own snapshot and memory buckets; the Joern engine as a plane task on a larger worker pool; worker pool sizing and autoscaling; a delta Run command and Workspaces from URL + commit; a deployment runbook with a proof on kind and a checklist for the target cluster.
• Out of scope: provisioning or operating the target cluster; modifying Agent Substrate or ax; any change to detection, scoring, populations or the decision engine; replacing the ax CLI with a bespoke client beyond what remote submission needs.
• Adjacent expectations: ai-service-plane requirements (one Model + budget per task, attribution, credentials only in the start request, egress policies, verify-at-startup memory store) keep holding; harnessx-removal Req 6 (memory on the S3 store) keeps holding; nothing is deleted before its replacement passes its test (the harnessx-removal sequencing rule).

Target Environment (maintainer, 2026-10-02)

• Cluster: k3s. Consequences: containerd (no Docker socket; the engine's host-Docker path does not exist there), gVisor needs runsc and a RuntimeClass installed on the nodes Substrate's workers run on, k3s ships Traefik and local-path storage, and single-node k3s is close enough to kind that the kind proof transfers.
• Images and source: GitHub. Images are published to GitHub Container Registry (ghcr.io/norandom/...), built by GitHub Actions from tagged commits, digest-pinned in the manifests; private packages need an imagePullSecret on the worker ServiceAccounts and the CI principal. Substrate's and ax's own images are built with ko from their checkouts and pushed to the same registry.

Requirements

Requirement 1: Nothing assumes this host

User Story: As the maintainer, I want every host-bound assumption replaced by a cluster resource or a configuration value, so the plane runs the same on kind and on the target cluster.

Acceptance Criteria

1. The kube context, the registry (GHCR in production), the ax-server address, the router address, the receiver address and the snapshot and memory buckets are configuration (environment or one config file), with the kind values as the documented defaults for development; no module names kind-ousast, localhost:5001 or 172.19.0.1.
2. ousast plane doctor checks the configured cluster, not kind by name, and reports each configured address.
3. A test enumerates the source tree for host-only literals and fails on any.

Requirement 2: The reconciler stays the CLI, with a remote execution mode

User Story: As the maintainer, I want to trigger the checks in the cluster from the CLI and get the results fed back, so that remote execution is a mode of the same tool, not a separate service.

Acceptance Criteria

1. ousast plane run (and the later ousast plane scan) takes an execution mode, local or remote, from the profile or a flag; remote submits the Run to ax-server in the target cluster (over the cluster's ingress or a kubeconfig), local is today's kind path. The manifests, the memory-key seeding, the budgets and the attribution table are identical in both modes.
2. In remote mode the CLI needs no inbound path: it polls the memory store for task completion and artifacts and prints the same status, attribution table and verdicts; ousast plane status <run> reports a Run started earlier from any machine with the store credentials.
3. Provider and store credentials come from the caller's environment (a laptop .env, a CI secret), travel only in the start request, and never appear in a manifest, an ActorTemplate or a log.
4. The principal the CLI uses against the cluster has the least privilege the ax API needs and nothing against Agent Substrate directly; a test compares the rendered role with the calls the CLI makes.
5. kind stays a first-class local execution mode, not a stepping stone: ousast plane run from a laptop against the kind cluster keeps working with the development profile (same code, same manifests, local registry), and every release is proven on it before anything is applied to k3s.
6. An unattended in-cluster reconciler (a Deployment or Job that runs without a caller) is a later option, not part of this spec.

Requirement 3: Artifacts land in the store, not on a host

User Story: As the maintainer, I want task artifacts delivered to the memory store so that no host has to be reachable from the cluster.

Acceptance Criteria

1. Tasks deliver their artifacts to the S3 memory store (presigned URLs minted by the CLI and carried in the start request, or a scoped delivery credential; the design chooses one and states why) and the CLI reads completion from the store. The receiver thread and the kind gateway EndpointSlice remain only if the design shows the local profile needs them; one delivery path for both profiles is preferred.
2. Egress policies grant each task exactly the hosts it needs (the store's endpoint, git hosts, the bound Model's host) and nothing else; a test renders the policy for every committed Task.

Requirement 4: The engine is a plane task

User Story: As the maintainer, I want Joern to run where the other tasks run, on a worker sized for it.

Acceptance Criteria

1. A second WorkerPool sized for the engine (memory and CPU from a measured run) exists alongside the default pool; an engine task module wraps today's host engine run and emits the same alerts.jsonl rows and coverage as alerts-engine.
2. The engine image is digest-pinned in the registry like the runner image; its size and pull time are recorded.
3. alerts-engine on the host remains available for development and is marked as such.

Requirement 5: Sizing and autoscaling

User Story: As the maintainer, I want the pool to follow the load of pushes without manual resizing.

Acceptance Criteria

1. Worker pool replicas, limits and the autoscaling rule (Substrate's assigned-worker signal) are manifests under ops/k8s/ with the kind values as a small profile and a documented production profile.
2. The runbook records the measured footprint per task type and the queueing consequence of one actor per worker.

Requirement 6: A delta Run for a push

User Story: As a user with a repository the project has never seen, I want a push checked by the plane.

Acceptance Criteria

1. ousast plane scan <repo-url> --base <commit> --head <commit> generates Workspaces from the URL and commits, derives candidates from the changed functions (quick rules, inferred roles, repository facts), and submits a Run of facts, verify a/b, tie-break and agree with per-task budgets; a whole-repository mode is secondary.
2. Results are written to the memory store under the repository and head commit and reported with the attribution table; the decision engine's verdict is reported only when a model is adopted, else the plane's agreement (ai-service-plane Req 6 and learned-decision-engine Req 6 unchanged).
3. The latency split is explicit: a blocking pre-push carries quick rules and the delta engine within its deadline; plane verdicts arrive asynchronously.

Requirement 7: Proven on kind, then documented for the target

User Story: As the maintainer, I want each step shown working on kind before I touch the real cluster.

Acceptance Criteria

1. Every requirement above is exercised end to end on the kind cluster (remote mode included, with the kind cluster as the remote target), with a recorded run under benchmarks/measurements/.
2. docs/deployment.md becomes the runbook: prerequisites for the target cluster (Substrate, ax, registry, buckets, Secrets, node requirements for gVisor workers), the profile switch, and a checklist whose every item maps to a requirement here; planned items are labelled planned until their run is recorded.