@a5c-ai/krate 5.0.1-staging.f672fe79b

package/docs/ontology/resource-contracts.md

@@ -0,0 +1,40 @@
+# Resource Contracts
+
+All resources use `apiVersion: krate.a5c.ai/v1alpha1`, `kind`, `metadata`, `spec`, and `status`.
+
+## Common metadata
+
+- `metadata.name` is required.
+- `metadata.namespace` defaults to `default`.
+- `metadata.labels` and `metadata.annotations` default to empty maps.
+- `metadata.resourceVersion` increments on every stored mutation.
+
+## Lifecycle contract
+
+1. Caller submits a resource mutation.
+2. Control plane normalizes metadata and validates kind support.
+3. RBAC checks `user`, verb, kind, and namespace.
+4. Admission policies evaluate in audit or enforce mode.
+5. Resource is routed to etcd or Postgres by storage class.
+6. Audit and watch events are emitted.
+7. Status is patched by controllers or workflow services.
+
+## Kind-specific contracts
+
+- `User`, `Team`, `Invite`, `IdentityMapping`, and `AuthProvider` drive sign-in, admin-managed user mapping, teams, invites, and access configuration.
+- `RepositoryPermission` and `SSHKey` reconcile repository access and key material into the repository backend.
+- `Repository` status includes Gitea backend integration and health.
+- `PullRequest` includes repository, source ref, target ref, title, and phase.
+- `Pipeline` includes repository, ref, steps, trust tier, and resume point.
+- `Job` includes service-account scopes, step name, and isolation metadata.
+- `RunnerPool` includes warm replicas, maximum replicas, and cache policy.
+- `WebhookDelivery` includes request, signature, response, phase, latency, and replay metadata.
+- `RefPolicy` and `BranchProtection` are enforced before protected writes.
+- `View` and `Selector` are label/query definitions used by UI and workflows.
+
+## Validation requirements
+
+- Unsupported kinds fail fast.
+- Missing names fail fast.
+- Selectors match labels deterministically.
+- Storage class is inspectable in status.

package/docs/ontology/resource-taxonomy.md

@@ -0,0 +1,42 @@
+# Resource Taxonomy
+
+## CRD-backed configuration resources
+
+These are low-cardinality desired-state contracts and are safe for etcd-backed storage.
+
+| Kind | Owner | Purpose |
+| --- | --- | --- |
+| `Organization` | Identity/data plane | Workspace organization, owners, teams, and default repository policy |
+| `User` | Identity | Human account profile, sign-in state, and linked identities |
+| `Team` | Identity | Team membership, maintainers, and repository permission grants |
+| `Invite` | Identity | Pending invitation, role, requested teams, and expiry |
+| `IdentityMapping` | Identity | Mapping between sign-in subjects, Kubernetes identities, and repository accounts |
+| `AuthProvider` | Identity | Installation sign-in provider status and delegated identity settings |
+| `Repository` | Data plane | Repository identity, visibility, Gitea hosting integration, object/search settings |
+| `SSHKey` | Identity/data plane | User, deploy, and automation keys reconciled into repository hosting |
+| `RepositoryPermission` | Identity/data plane | Collaborator and team grants synced to repository hosting |
+| `WebhookSubscription` | Hooks/events | Endpoint, event filters, signing configuration, retry policy |
+| `RefPolicy` | Data plane/hooks | Deny refs, force-push policy, signing and linear-history policy |
+| `BranchProtection` | Data plane/control | PR requirement and protected ref rules |
+| `RunnerPool` | Runners/CI | Runner capacity, scale limits, cache configuration |
+| `View` | Web UI | Saved triage view and presentation contract |
+| `Selector` | Web UI/control | Reusable label/query selector for workflows |
+
+## Aggregated Postgres-backed resources
+
+These are high-cardinality runtime records and must not store primary records in etcd.
+
+| Kind | Owner | Purpose |
+| --- | --- | --- |
+| `PullRequest` | Control/UI | Review unit, refs, status, checks, merge lifecycle |
+| `Issue` | Control/UI | Work item, labels, assignment, lifecycle |
+| `Review` | Control/UI | Approval/comment/change-request records |
+| `Pipeline` | Runners/CI | Pipeline run state and resume point |
+| `Job` | Runners/CI | Step execution record and service-account scope |
+| `WebhookDelivery` | Hooks/events | Durable delivery attempt, signature, response, replay chain |
+
+## Taxonomy invariants
+
+- Config resources can drive reconciliation and must remain small.
+- Aggregated resources can be listed, watched, and label-selected through the API server but store primary state outside etcd.
+- Every kind has metadata, spec, status, storage class, owner context, and executable tests.

package/docs/ontology/runners-and-ci.md

@@ -0,0 +1,29 @@
+# Runners and CI
+
+## Runner pools
+
+`RunnerPool` records declare warm replicas, maximum replicas, queue scaling, cache settings, and trust boundaries.
+
+## Pipelines
+
+`Pipeline` records represent a run for repository/ref work. They include steps, status, trust tier, and optional `resumeFrom` state for rerun/resume.
+
+## Jobs
+
+`Job` records represent executable steps. Each job receives a service-account profile derived from the pipeline trust tier.
+
+## Fork isolation
+
+- Fork PR pipelines are untrusted.
+- Untrusted jobs have `secrets: false` and `clusterApi: false`.
+- Trusted jobs may use configured scopes, but scopes remain explicit.
+
+## Scaling
+
+Queue depth maps to desired replicas within warm and max bounds. Scaling is deterministic and inspectable from pool spec/status.
+
+## Acceptance gates
+
+- Starting a fork pipeline produces jobs with no secrets and no cluster API access.
+- Rerun from a named step sets `resumeFrom`.
+- Pool replica planning respects warm and maximum replica limits.

package/docs/ontology/solution-space.md

@@ -0,0 +1,24 @@
+# Solution-Space Ontology
+
+The MVP is a deterministic Kubernetes-native contract implementation of the Krate architecture. Local tests do not require a live cluster, but the modules, chart, examples, Argo CD Application surface, and Gitea backend integration model the cluster contracts described in `docs/`.
+
+## Architectural shape
+
+- `src/resource-model.js` defines resource kinds, storage classes, metadata normalization, selectors, and Kubernetes-list output.
+- `src/control-plane.js` models create/update/status verbs, RBAC, admission, audit, storage boundary routing, and watches.
+- `src/identity-policy.js` maps OIDC identities, groups, trust tiers, service accounts, admission policies, and policy rollout.
+- `src/data-plane.js` and `src/gitea-backend.js` model repository creation, Gitea-backed Git hosting, SSH keys, collaborators/teams, branch protection, ref policy, webhooks, object metadata, and search hooks.
+- `src/runners-ci.js` models runner pools, pipelines, jobs, queue scaling, fork isolation, and rerun/resume.
+- `src/hooks-events.js` models webhook subscriptions, signing, durable deliveries, failure inspection, and replay.
+- `src/web-ui.js` models excellent UI flows as resource-backed view models.
+- `src/operations.js` and `src/argocd-gitops.js` model manifests, Argo CD GitOps Applications, observability, backup/restore, release gates, and the MVP demo.
+
+## MVP boundaries
+
+- In scope: Kubernetes resource contracts, Argo CD Application generation, Gitea API-shaped backend integration, deterministic control-plane behavior, workflow models, tests, docs coverage, and smokeable demo output.
+- Out of scope for local validation: requiring a live APIService deployment, live Argo CD controller, live Gitea server, real Postgres, real etcd, real ARC runners, and real browser rendering.
+- Required fidelity: storage classes, Gitea integration calls, Argo CD Application fields, policy decisions, eventing, and operational gates must behave like the docs even when validated through deterministic JavaScript harnesses.
+
+## Quality strategy
+
+The solution converges through ontology authoring, module implementation, acceptance tests, doc coverage, smoke output, and final quality review.

package/docs/ontology/storage-and-data-boundaries.md

@@ -0,0 +1,29 @@
+# Storage and Data Boundaries
+
+## etcd boundary
+
+etcd stores CRD-backed configuration: `Repository`, `WebhookSubscription`, `RefPolicy`, `BranchProtection`, `RunnerPool`, `View`, and `Selector`. These are low-cardinality desired-state resources.
+
+## Postgres boundary
+
+Postgres stores aggregated records: `PullRequest`, `Issue`, `Review`, `Pipeline`, `Job`, and `WebhookDelivery`. These records can be listed and watched through Kubernetes APIs but their primary storage is not etcd.
+
+## Gitea repository boundary
+
+Gitea stores repositories and terminates smart-HTTP/SSH Git traffic. Repository status points to the Gitea backend integration, protected branch state, deploy keys, collaborators/teams, webhooks, and health, while Krate routing remains stateless.
+
+## Object storage boundary
+
+Object storage contains large immutable objects such as LFS blobs, archives, and artifacts. Repository specs reference object storage configuration without embedding large data.
+
+## Search boundary
+
+Search indexing hooks observe Git and resource events. Search lag must not block Git write success.
+
+## Boundary invariant
+
+No workflow should require copying high-cardinality logs, comments, jobs, or webhook attempts into etcd.
+
+## Deterministic runtime snapshot boundary
+
+The deterministic harness can export and import a KrateRuntimeSnapshot that preserves the control-plane etcd/postgres resource split, audit log, and events. This is the executable backup/restore boundary for the current package contract; production cluster backup still requires the external Postgres, object storage, Gitea repository storage, and declarative resource backup plan described in the operations docs.

package/docs/ontology/validation-matrix.md

@@ -0,0 +1,24 @@
+# Validation Matrix
+
+| Requirement | Ontology | Implementation | Validation |
+| --- | --- | --- | --- |
+| CRD vs aggregated storage | `resource-taxonomy.md`, `storage-and-data-boundaries.md` | `src/resource-model.js`, `src/control-plane.js` | storage tests, `validate-doc-coverage.mjs` |
+| RBAC and admission | `policies-and-invariants.md` | `src/identity-policy.js`, `src/control-plane.js` | RBAC/admission tests |
+| Warm Gitea receive path | `workflows.md`, `storage-and-data-boundaries.md` | `src/data-plane.js` | Gitea backend tests |
+| BranchProtection and RefPolicy | `resource-contracts.md`, `events-and-hooks.md` | `src/data-plane.js` | protected branch/ref tests |
+| Fork CI isolation | `runners-and-ci.md` | `src/runners-ci.js` | runner scheduler tests |
+| Webhook signing/replay | `events-and-hooks.md` | `src/hooks-events.js` | webhook bus tests |
+| UI YAML transparency | `web-ui-excellent-flows.md` | `src/web-ui.js` | smoke assertions |
+| Backup/restore/release gates | `operations-and-release.md` | `src/operations.js`, `scripts/build.mjs`, `scripts/smoke.mjs` | `npm run check` with docs and ontology coverage |
+
+## Local validation commands
+
+- `npm run build`
+- `npm run validate:docs`
+- `npm test`
+- `npm run smoke`
+- `npm run check`
+
+## Green definition
+
+The project is green only when all ontology files exist, coverage terms are found in docs and source, tests pass, smoke assertions pass, and the Babysitter run returns a successful completion proof.

package/docs/ontology/web-ui-excellent-flows.md

@@ -0,0 +1,32 @@
+# Web UI Excellent Flows
+
+The UI ontology is a set of resource-backed view models rather than a hidden application state machine.
+
+## Required flows
+
+- Create and inspect a repository.
+- Open and review a pull request.
+- Inspect failed checks and rerun/resume CI.
+- Edit runner pool capacity and cache policy.
+- Inspect and replay webhook deliveries.
+- Open YAML/resource views for UI actions.
+
+## View model invariants
+
+- Dashboard cards summarize repositories, PRs, pipelines, runner pools, and webhook deliveries.
+- PR review surfaces changed files, pipeline checks, comments, and YAML.
+- Runner pool editor exposes scaling limits and resource YAML.
+- Webhook inspector exposes request, response, phase, signature, and replay action.
+- Every view includes enough resource identity for kubectl-style workflows.
+
+## Traceability
+
+`View` and `Selector` resources support saved triage and cross-repository work. UI filters should map to selector labels or query metadata.
+
+## Current executable UI contract
+
+- Breadcrumbs orient each organization and repository route.
+- `ForgeFlowRail` makes the default Git forge flow explicit: create, clone, branch, open PR, merge, deploy, and notify.
+- `RepositoryCommandBar` keeps clone, branch, watch, RBAC, PR-flow, and YAML actions visible across repository tabs.
+- Degraded-state banners render on every route that depends on the controller model, not only on the dashboard.
+- Architecture boundaries include the API controller, Kubernetes resource gateway, Kubernetes client, Kubernetes reconciler, and Git data plane.

package/docs/ontology/workflows.md

@@ -0,0 +1,39 @@
+# Workflows
+
+## Repository creation
+
+1. Repository admin creates a `Repository` resource.
+2. Control plane authorizes and stores it in etcd.
+3. Data plane provisions a Gitea repository integration and initializes repository storage.
+4. Status exposes Gitea backend integration and health.
+
+## Pull request review
+
+1. Developer creates a `PullRequest` with source/target refs and title.
+2. Admission validates required fields and policy.
+3. CI starts a `Pipeline` and one or more `Job` records.
+4. UI shows checks, changed files, comments, and YAML/resource equivalent.
+5. Branch protection requires PR flow for protected refs.
+
+## Git receive-pack
+
+1. Gitea backend resolves repository routing.
+2. `RefPolicy` denies forbidden refs or unsafe writes.
+3. `BranchProtection` blocks direct protected writes unless actor has repo-admin permission.
+4. Write event is emitted and optional search indexing hook is queued.
+
+## Webhook delivery and replay
+
+1. Repository admin creates a `WebhookSubscription`.
+2. Event dispatch signs payload and stores a `WebhookDelivery` record.
+3. Failure status remains inspectable with request/response metadata.
+4. Replay creates a new delivery using the current secret and links replay metadata.
+
+## Backup and restore
+
+1. Export CRDs and low-cardinality config.
+2. Backup Postgres aggregated records.
+3. Snapshot Gitea repository integration state.
+4. Preserve object storage.
+5. Restore API/config, Postgres, repositories, objects, then controllers.
+6. Validate by listing resources, reading refs, opening a PR, and replaying a webhook.

package/docs/ontology/world.md

@@ -0,0 +1,35 @@
+# World Ontology
+
+Krate is a Kubernetes-native forge: repositories, review, CI, policy, hooks, and operations are expressed through Kubernetes-style resources rather than a separate opaque application model.
+
+## Domain entities
+
+- **Kubernetes API server** is the interaction contract for discovery, verbs, watches, RBAC, admission, and status.
+- **etcd** stores low-cardinality configuration resources such as `Repository`, `WebhookSubscription`, `RefPolicy`, `BranchProtection`, `RunnerPool`, `View`, and `Selector`.
+- **Postgres** stores high-cardinality aggregated records such as `PullRequest`, `Issue`, `Review`, `Pipeline`, `Job`, and `WebhookDelivery`.
+- **Gitea backend** stores repositories and keeps the write path warm for `receive-pack`.
+- **Object storage** stores LFS objects, archives, and large immutable artifacts.
+- **Search index** receives repository indexing hooks without blocking Git writes.
+
+## Human actors
+
+- **Developer** opens pull requests, comments, reviews, runs pipelines, and investigates failures.
+- **Repository admin** creates repositories, branch protection, ref policies, webhook subscriptions, and triage views.
+- **Platform engineer** installs Krate, manages runner pools, admission rollout, observability, backup, and release gates.
+- **Team lead** uses views and selectors to triage cross-repository work.
+
+## Machine actors
+
+- **Controllers** reconcile resource state and patch status.
+- **Runner jobs** execute pipeline steps with scoped service-account identity.
+- **Admission policies** validate mutations in audit or enforce mode.
+- **Webhook dispatchers** sign, deliver, retry, and replay outbound events.
+- **Git clients** use smart HTTP/SSH routes resolved by the Gitea backend integration.
+
+## Non-negotiable assumptions
+
+- Kubernetes RBAC remains authoritative for user and machine actions.
+- UI state must be explainable as resources, YAML, events, and status.
+- High-cardinality activity must not overload etcd.
+- Untrusted fork work must not access secrets or the cluster API.
+- Operations must be installable, observable, backupable, restorable, and release-gated.

package/docs/product-requirements.md

@@ -0,0 +1,62 @@
+# Product Requirements
+
+## Product summary
+
+Krate is a Kubernetes-native forge for platform engineering teams. It extends the Kubernetes API with repository, pull request, issue, pipeline, runner, hook, and policy resources so Git workflows compose directly with RBAC, admission webhooks, Argo, Crossplane, ARC, Kyverno, and Gatekeeper.
+
+## Problem
+
+Existing Kubernetes-hosted forges are usually monoliths packaged in Helm. They still bring a separate identity model, permission model, webhook system, CI security surface, and integration layer. The naive Kubernetes-native design also fails if every issue/comment is stored in etcd, every repository gets its own PVC, or push traffic is cold-started.
+
+## Goals
+
+- Provide a forge where repos, PRs, CI, hooks, and policy share one Kubernetes identity and RBAC model.
+- Make forge resources queryable and automatable with `kubectl`.
+- Support admission-webhook policy for PRs, issues, and CI without custom integration glue.
+- Keep high-cardinality social data out of etcd while preserving Kubernetes API semantics.
+- Make GitOps transparency a first-class UX pattern for every mutation.
+- Ship an MVP that proves policy, Git push, PR review, and CI identity end to end.
+
+## Non-goals for MVP
+
+- Scaled Gitea-backed production data plane beyond the single-backend MVP.
+- Full native runner abstraction if ARC integration is sufficient for the first demo.
+- Built-in code search beyond design-ready interfaces.
+- Multi-cluster federation.
+- Replacing Kyverno or Gatekeeper with a bespoke policy language.
+
+## Personas
+
+### Developer
+
+Developers review PRs, browse code, debug failing runs, and need fast keyboard-first workflows. They should not need to understand cluster internals to use the forge, but should always be able to reveal the underlying resource and command.
+
+### Platform engineer
+
+Platform engineers own runner pools, policy, identity, storage, hooks, tenancy, install, upgrade, and cost. They need auditability, safe rollout modes, and GitOps-managed configuration.
+
+### Repo admin
+
+Repo admins configure repository settings, branch protection, webhooks, runner permissions, and policy overrides. They use the same IA as developers with additional settings access.
+
+## Product principles
+
+- Kubernetes is the backend. Krate should not recreate permission, policy, audit, and identity systems already present in Kubernetes.
+- CRDs are contracts, not a database. High-cardinality records must live behind the aggregated API server.
+- Push paths must stay warm. Reads can scale elastically; writes cannot impose cold-start latency on `git push`.
+- UI state can be declarative. Saved views and selectors should be resources that teams can commit, share, and apply.
+- Policy rollout must be observable. Audit mode and violation preview are required for PR policy authoring.
+
+## Success metrics
+
+- Time from `helm install krate` to first repository push is under 15 minutes in a documented environment.
+- A Kyverno policy can block or audit PR creation without custom Krate code.
+- A developer can open, review, and merge a PR with CI status from the UI.
+- A platform engineer can configure a runner pool and export/save its YAML.
+- Webhook failures are inspectable and replayable from both UI and `kubectl`.
+
+## Organization-scoped tenancy
+
+Krate is organization-first. Every repository, deployment, runner pool, agent stack, trigger, company brain memory repository, session, workspace, secret grant, and config grant belongs to an org. Each org maps to its own Kubernetes namespace so Kubernetes RBAC, ServiceAccounts, Secrets, ConfigMaps, admission, and audit remain the isolation boundary.
+
+The UI should feel like GitHub organization navigation: select an org, then browse repositories, deployments, agents, memory, settings, runners, and audit for that org. Cross-org sharing is explicit policy, not an accidental reference.

package/docs/roadmap-mvp.md

@@ -0,0 +1,87 @@
+# MVP Roadmap
+
+## MVP promise
+
+A user can install Krate, create a repository resource, push Git content, create/review a PR, run CI through ARC with Workload Identity, and apply a Kyverno policy that blocks a PR while the same policy appears in the UI.
+
+## Six-week plan
+
+### Weeks 1-2: Aggregated API server
+
+Deliverables:
+
+- `Repository` and `PullRequest` resources with Kubernetes discovery.
+- Postgres-backed storage for aggregated resources.
+- Working `kubectl get/create` flows.
+- Initial RBAC and admission compatibility.
+
+Exit criteria:
+
+- PR creation and listing work through `kubectl`.
+- PR data is not stored as large etcd objects.
+
+### Week 3: Gitea-backed data plane
+
+Deliverables:
+
+- Gitea-backed smart-HTTP and SSH pathing.
+- Single Gitea backend with persistent repository storage.
+- `git-upload-pack` and `git-receive-pack` support.
+- Repository operator creates Gitea repository integration plans.
+
+Exit criteria:
+
+- `kubectl create -f repo.yaml` followed by `git push` works.
+
+### Week 4: Next.js skeleton
+
+Deliverables:
+
+- OIDC login skeleton.
+- Repo list and file view.
+- PR list.
+- Watch API to SSE route.
+- GitOps-transparent mutation panel pattern.
+
+Exit criteria:
+
+- Repo and PR pages update from watch streams.
+
+### Week 5: PR creation and review
+
+Deliverables:
+
+- PR creation flow.
+- Inline diff view.
+- Comment threads.
+- Pipeline status in PR rail.
+
+Exit criteria:
+
+- Developer can create and review a PR in the UI.
+
+### Week 6: CI identity and demo
+
+Deliverables:
+
+- ARC-backed workflow execution.
+- Workload Identity for CI jobs.
+- Demo Kyverno PR policy.
+- Outbound webhook and delivery log.
+- Helm chart packaging.
+
+Exit criteria:
+
+- Public demo path: `helm install krate`; create repo; push; create PR; run CI; policy blocks a PR; UI shows policy and delivery state.
+
+## Post-MVP roadmap
+
+- v0.2: Live run view refinements, `RefPolicy` with WASM hooks, scaled Gitea data plane, and richer saved `View`/`Selector` templates.
+- v0.3: Zoekt code search, multi-cluster federation, richer insights and cost attribution.
+
+## Open decisions
+
+- Commit to aggregated API server over pure CRDs for high-cardinality resources.
+- Choose ARC-only MVP or executor-pluggable runner abstraction from day one.
+- Decide whether to bundle Kyverno or support BYO only.
+- Decide final product name before public README and chart publication.

package/docs/system-requirements.md

@@ -0,0 +1,90 @@
+# System Requirements
+
+## Functional requirements
+
+- Krate must expose forge resources through Kubernetes-style APIs.
+- Low-cardinality declarative configuration must use CRDs: `Repository`, `WebhookSubscription`, `RefPolicy`, `BranchProtection`, `RunnerPool`, `View`, and `Selector`.
+- High-cardinality social and execution data must be served by an aggregated API server backed by Postgres: `PullRequest`, `Issue`, `Review`, `Pipeline`, `Job`, and delivery records.
+- Git traffic and Git hosting integrations must be backed by a Kubernetes-hosted Gitea backend server for smart-HTTP/SSH, repositories, SSH keys, collaborators/teams, protected branches, and webhooks.
+- CI jobs must run under scoped Kubernetes ServiceAccounts, not PATs.
+- UI mutations must share code paths with generated YAML/kubectl actions.
+
+## Integration requirements
+
+- Kubernetes API aggregation must register Krate aggregated resources with normal discovery, watch, list, get, create, update, patch, and delete semantics where applicable.
+- Admission webhooks must be able to validate and mutate PRs, issues, pipelines, and jobs.
+- Kyverno and OPA Gatekeeper policies must work on Krate resources without a Krate-specific policy adapter.
+- Repository operator must reconcile `Repository` resources into Gitea repository hosting, access configuration, integration plans, and status.
+- PR operator must support preview-environment integration through ArgoCD ApplicationSet.
+- Runner integration must compose with ARC for MVP and leave an abstraction seam for Tekton or Buildkite Agent.
+- Webhook delivery must integrate with durable queueing, preferably NATS JetStream, and HMAC signing.
+
+## Publish and install requirements
+
+- Krate must ship as a public Helm chart.
+- The chart must install CRDs, APIService registration, aggregated API server, controllers, Gitea backend, Argo CD Application surface, UI, service accounts, RBAC, and default policies.
+- Install documentation must describe required and optional dependencies: Kubernetes version, Argo CD, Gitea, Postgres, RWX storage, object storage, NATS, ARC, Kyverno/Gatekeeper, OIDC provider, and ingress.
+- The chart must support BYO Postgres, BYO object storage, BYO RWX class, and BYO Kyverno/Gatekeeper.
+- Install must support a minimal demo mode and a production-shaped mode.
+
+## Upgrade requirements
+
+- CRD schema upgrades must be backward compatible inside a supported minor version.
+- Aggregated API storage migrations must be versioned, idempotent, and observable.
+- Controllers must tolerate partially upgraded components during Helm rollout.
+- Gitea backend versions must be rollable without corrupting repositories or interrupting in-flight receive-pack writes.
+- Release notes must list API changes, migration steps, and rollback constraints.
+
+## CI/CD requirements
+
+- The repository must publish chart artifacts and container images together with traceable versions.
+- CI must run schema validation, controller tests, API conformance checks, security scans, Helm template validation, and a smoke install.
+- Release candidates must prove the MVP path: install, create repository, push, create PR, run CI, apply policy, observe webhook delivery.
+
+## Security requirements
+
+- Krate must not use personal access tokens as a core credential mechanism.
+- Human login must use OIDC and Kubernetes user/group mapping.
+- UI server-side calls must carry the user’s Kubernetes identity or a strictly scoped delegated token.
+- Runner jobs must use projected ServiceAccount tokens scoped to repo, ref, and pipeline identity.
+- Fork PRs must be forced into untrusted pools with no secrets and no cluster API access.
+- Server-side custom Git hooks must run in a WASM sandbox, not arbitrary shell.
+- Outbound webhooks must be signed and secret rotation must be supported.
+
+## Observability requirements
+
+- Expose metrics for API latency, Postgres latency, Git operation latency, Gitea capacity, queue depth, webhook delivery status, runner wait time, runner cost, and policy violations.
+- Emit Kubernetes events for reconciliation failures and user-visible operational issues.
+- Preserve auditability through Kubernetes resources and copyable kubectl-equivalent activity entries.
+- Provide dashboards for runner pools, hook health, Gitea/storage health, and API health.
+
+## Backup and restore requirements
+
+- Backup Postgres, repository RWX storage, object storage, and declarative resources.
+- Document consistent restore ordering: API/config, Postgres, repositories, objects, controllers.
+- Validate restore by listing resources, reading repository refs, opening PRs, and replaying a representative webhook delivery.
+
+## Release readiness gates
+
+- All required docs in this directory exist and link from `docs/README.md`.
+- Helm install smoke test passes in a documented cluster profile.
+- MVP demo path is reproducible from a clean namespace.
+- Security model is documented with explicit threat boundaries.
+- Known open decisions are tracked in the roadmap.
+
+
+## KubeVela and OAM requirements
+
+- The deployment must optionally install KubeVela as a GitOps-managed dependency through Argo CD.
+- Krate must assimilate OAM Application, Component, Trait, Policy, Workflow Step, and Scope concepts into its ontology and UI.
+- The UI must wrap KubeVela capabilities as repository and pull-request delivery flows while preserving raw Kubernetes/OAM YAML.
+- KubeVela owns OAM reconciliation status; Krate only projects and summarizes it.
+
+## Organization and namespace requirements
+
+- Krate must model `Organization` as the top-level product scope for repositories, deployments, agents, runners, memory, sessions, secrets, config, and audit.
+- Each organization must own or bind to exactly one Kubernetes namespace by default.
+- Namespaced product resources must carry org and namespace labels and reject cross-org references unless an explicit sharing policy exists.
+- Controllers must run cluster-wide if needed but reconcile side effects through the owning org namespace.
+- UI routes and API routes must support org-addressed access such as `/orgs/[org]/repositories/[repo]` and `/api/orgs/[org]/...`.
+- Backup, restore, retention, and audit must support org-level export and recovery.

package/docs/tests/README.md

@@ -0,0 +1,53 @@
+# QA automation and test strategy
+
+## Purpose
+
+This directory defines Krate's QA automation plan, framework, and tooling for existing and future functionality. It covers unit tests, integration tests, API/controller tests, browser and UI tests, E2E tests, package/chart tests, security checks, accessibility, performance, coverage, fixtures, and CI gates.
+
+The plan is product-wide: current forge features, Kubernetes-native resource APIs, org-scoped UI, Gitea/Git hosting, CI/runners, hooks, deployments, KubeVela/OAM, and future agent/company-brain functionality all share one quality model.
+
+## Current test anchors
+
+Krate already has these executable gates:
+
+| Command | Current purpose |
+| --- | --- |
+| `npm test` | Node test runner over `tests/*.test.js`. |
+| `npm run e2e` | Node test runner over `tests/e2e/*.test.js`. |
+| `npm run validate:docs` | docs/ontology/source coverage validation. |
+| `npm run package:check` | package/chart/example coverage validation. |
+| `npm run ui:validate` | static UI validation. |
+| `npm run ui:build` | Next.js production build. |
+| `npm run smoke` | runtime smoke validation. |
+| `npm run check` | full local quality gate chaining build, docs, tests, e2e, package, smoke, UI validation, and UI build. |
+
+## Documents
+
+- [QA automation plan](./qa-automation-plan.md) defines the lifecycle, test pyramid, responsibilities, rollout order, and done criteria.
+- [Test framework and tools](./test-framework-tools.md) defines the recommended tools and how they map to Krate layers.
+- [Coverage model](./coverage-model.md) defines coverage dimensions, thresholds, traceability, and reporting.
+- [Unit and integration tests](./unit-integration-tests.md) defines module, controller, API, resource-model, and persistence tests.
+- [E2E and scenario tests](./e2e-scenario-tests.md) defines end-to-end flows for forge, org, runners, hooks, deployments, and agents.
+- [Browser and UI tests](./browser-ui-tests.md) defines browser automation, component tests, accessibility, visual, and UX assertions.
+- [CI quality gates](./ci-quality-gates.md) defines PR, merge, release, nightly, and staging gates.
+- [Fixtures and test data](./fixtures-test-data.md) defines deterministic org/repo/memory/.a5c fixtures and data policy.
+- [Security and compliance tests](./security-compliance-tests.md) defines auth, RBAC, secret, supply-chain, and audit checks.
+- [Observability and reliability tests](./observability-reliability-tests.md) defines metrics, events, logs, watches, retries, and failure injection.
+- [Agent QA plan](./agent-qa-plan.md) defines tests for agent dispatch, Agent Mux sessions, company brain memory, triggers, tools, subagents, and run imports.
+
+## Quality principles
+
+- Every feature has tests at the lowest useful layer plus at least one user-facing acceptance path.
+- Every controller side effect has idempotency, retry, and audit tests.
+- Every org-scoped path has cross-org negative tests.
+- Every UI action has a server-enforced permission test behind it.
+- Every secret/config/tool/memory path has no-leak tests.
+- Every future feature ships with fixtures before broad E2E expansion.
+- Browser tests focus on critical workflows and route semantics, not brittle snapshots.
+- Package/chart checks are release blockers, not optional validation.
+
+## Additional planning docs
+
+- [Product test matrix](./product-test-matrix.md) maps every major product area to unit, integration/API, browser/UI, E2E, security, and package coverage.
+- [Test suite layout and naming](./test-suite-layout.md) defines future test directories, naming, metadata, fixtures, and migration rules.
+- [QA adoption roadmap](./qa-adoption-roadmap.md) sequences the move from current gates to browser, coverage, security, agent, and live reliability gates.