@a5c-ai/krate 5.0.1-staging.00fa5317c

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.

package/docs/tests/agent-qa-plan.md

@@ -0,0 +1,63 @@
+# Agent QA plan
+
+## Scope
+
+Agent QA covers future agent orchestration functionality:
+
+- agent stacks, tools, MCP servers, skills, subagents;
+- triggers from CI, webhooks, issues, PRs, labels, mentions, schedules, and manual UI;
+- Agent Mux run/session/chat integration;
+- dispatches displayed as CI-like runs;
+- context assembly, labels, memory, redaction, and snapshots;
+- company brain memory and `.a5c` run imports;
+- approvals, artifacts, write-back, and audit;
+- org-scoped RBAC, secrets, config, service accounts, and runner placement.
+
+## Required suites
+
+| Suite | Tests |
+| --- | --- |
+| Stack schema | stack/tool/MCP/skill/subagent resource validation and readiness conditions. |
+| Permission review | RBAC, secret/config grants, memory grants, missing capability explanations. |
+| Context assembly | prompt layers, source provenance, labels, redaction, digest snapshots. |
+| Dispatch lifecycle | create run/attempt, Agent Mux handoff, event stream, cancel/resume/retry. |
+| Trigger rules | dry-run, dedupe, coalesce, branch/source filters, trusted/untrusted refs. |
+| Agent Mux adapter | launch payload, capability discovery, session binding, transcript events. |
+| Memory | query, historical refs, tool access, snapshot reuse, stale warnings. |
+| Run import | `MEMORY.md`, sessions, `.a5c` journals/tasks/artifacts, redaction, PR review. |
+| Write-back | patch/comment/check/review artifacts, approval, idempotency, rollback. |
+| UI | dispatch composer, run detail/chat, memory dashboard, imports, approvals. |
+
+## Critical negative tests
+
+- stack references tool without required Secret grant;
+- skill requires ConfigMap not granted;
+- agent on fork tries to access trusted secrets;
+- trigger label tries to grant permission;
+- context label tries to hide instructions from preview;
+- Agent Mux session ID belongs to another org/run;
+- memory tool reads outside pinned snapshot;
+- `.a5c` import contains secret-like content;
+- write-back tries to mutate unapproved target;
+- subagent requests parent-only capability.
+
+## Browser journeys
+
+- manual dispatch from Code page with memory preview;
+- failed CI repair from Runs page;
+- issue mention dispatch with linked workspace/session;
+- run detail chat/session with event timeline;
+- memory import review and approval;
+- permission wizard fixes missing secret/config/memory grant;
+- trigger rule dry-run preview.
+
+## Done criteria
+
+Agent functionality is not production-ready until:
+
+- unit/integration/API tests cover resource and controller logic;
+- browser tests cover the primary user journeys;
+- cross-org and no-secret negative tests pass;
+- Agent Mux fake/session tests pass;
+- memory snapshot and import fixtures pass;
+- audit/events can explain every dispatch and write-back.

package/docs/tests/browser-ui-tests.md

@@ -0,0 +1,62 @@
+# Browser and UI tests
+
+## Browser framework
+
+Use Playwright for browser E2E once added. Browser tests should focus on route behavior, accessibility, and critical workflows rather than brittle visual snapshots.
+
+## Route smoke coverage
+
+Required route smoke tests:
+
+- `/orgs`;
+- `/orgs/[org]`;
+- `/orgs/[org]/repositories`;
+- `/orgs/[org]/repositories/[repo]/code`;
+- `/issues`, `/pull-requests`, `/runs`, `/hooks`, `/settings` under repo routes;
+- `/orgs/[org]/deployments`;
+- `/orgs/[org]/runs`;
+- future `/orgs/[org]/agents/*` and `/orgs/[org]/agents/memory/*`.
+
+Every route smoke asserts:
+
+- org switcher visible;
+- breadcrumbs include org;
+- main heading exists;
+- no server error;
+- advanced YAML/resource panels are reachable where expected;
+- unauthorized or missing resources show safe empty states.
+
+## Critical UI journeys
+
+| Journey | Assertions |
+| --- | --- |
+| Org switch | route changes org, data changes, no cross-org leakage. |
+| Repository navigation | tabs preserve org/repo and active page. |
+| Create/apply resource | YAML/plan preview, server validation, status update. |
+| Run debugging | run list, event stream, details, rerun affordance. |
+| Agent dispatch | composer, memory preview, permission review, created run link. |
+| Memory import review | generated diff, redaction status, validation status, approve/reject. |
+
+## Accessibility checks
+
+Run automated checks on primary routes for:
+
+- headings and landmarks;
+- form labels;
+- button/link names;
+- keyboard navigation;
+- focus management in dialogs/panels;
+- color contrast for status indicators;
+- reduced-motion behavior where relevant.
+
+## Visual regression
+
+Use visual checks sparingly for stable layout contracts:
+
+- app shell/sidebar/topbar;
+- repository code layout;
+- run detail layout;
+- memory import review panel;
+- empty/loading/error states.
+
+Prefer semantic assertions for changing data-heavy pages.

package/docs/tests/ci-quality-gates.md

@@ -0,0 +1,48 @@
+# CI quality gates
+
+## Gate levels
+
+| Gate | Trigger | Required checks |
+| --- | --- | --- |
+| PR fast gate | pull request | install, static/docs/package checks, unit/integration tests, UI validation. |
+| PR browser gate | pull request when UI changes | browser route smoke, critical UI journeys impacted by change. |
+| Merge gate | main/staging merge | full `npm run check`, package/chart validation, UI build. |
+| Nightly gate | schedule | live-ish integration, browser full suite, security scans, performance smoke. |
+| Release gate | tag/release | Docker build, Helm package, smoke install, upgrade/rollback plan, SBOM/signing if enabled. |
+| Staging gate | deployment | real cluster smoke, webhooks, runners, Gitea, Argo/KubeVela, Agent Mux if enabled. |
+
+## Current required local gate
+
+`npm run check` remains the all-up local gate:
+
+```text
+build -> validate:docs -> test -> e2e -> package:check -> smoke -> ui:validate -> ui:build
+```
+
+## Future gate additions
+
+- `test:browser` for Playwright route and journey tests.
+- `test:coverage` for coverage reporting.
+- `test:security` for dependency, secret, and auth/RBAC checks.
+- `test:charts` for rendered chart validation.
+- `test:agents` for agent/company-brain vertical slice.
+
+## CI artifact policy
+
+CI should retain:
+
+- test logs;
+- browser traces/screenshots/videos on failure;
+- coverage reports;
+- rendered manifests;
+- package validation report;
+- memory import redaction/validation fixtures;
+- smoke output;
+- SBOM/signature artifacts when release gates run.
+
+## Flake policy
+
+- A flaky test is a failing test until triaged.
+- Retries may be used only to collect evidence, not to hide failures.
+- Quarantined tests need owner, expiry, issue link, and reduced gate impact.
+- CI should track test duration and failure signatures.

package/docs/tests/coverage-model.md

@@ -0,0 +1,64 @@
+# Coverage model
+
+## Coverage dimensions
+
+Krate coverage is multi-dimensional. Line coverage is useful but not sufficient.
+
+| Dimension | Required coverage |
+| --- | --- |
+| Code coverage | statements, branches, functions, and critical path modules. |
+| Resource coverage | every CRD/config kind and aggregated kind has schema and example tests. |
+| Route coverage | every org/repo/agent/deployment route has render and authorization tests. |
+| API coverage | every typed endpoint has success, validation failure, auth failure, and cross-org negative tests. |
+| Controller coverage | reconcile create/update/delete, idempotency, retry, drift, finalizer, and status conditions. |
+| UI coverage | primary journeys, disabled states, advanced YAML panels, accessibility, route guards. |
+| Security coverage | auth, RBAC, Secret/ConfigMap grants, no-leak responses, audit records. |
+| Release coverage | package files, chart templates, CRDs, examples, smoke install, Docker image. |
+| Agent coverage | dispatch, context, memory, tools, triggers, sessions, imports, approvals, write-back. |
+
+## Initial thresholds
+
+| Layer | Target |
+| --- | --- |
+| Pure `src` modules | 85% line, 75% branch once coverage tooling lands. |
+| Controller/API critical paths | 90% path coverage by table-driven tests. |
+| UI route smoke | 100% of primary org/repo/deployment/agent routes render. |
+| Resource kinds | 100% listed in resource model, docs, package examples, and tests. |
+| Security negative paths | 100% for cross-org, no-secret, untrusted fork, and missing grant cases. |
+
+Thresholds should ratchet upward; do not block early docs-only work on coverage tooling that does not exist yet.
+
+## Traceability
+
+Every feature should map:
+
+```text
+requirement -> resource/API/UI/controller -> test file -> CI gate -> artifact/report
+```
+
+The existing `docs/agents/traceability-matrix.md` is the model for agent features. Product-wide coverage should extend the same pattern into `docs/tests`.
+
+## Coverage reports
+
+Reports should include:
+
+- per-command status;
+- code coverage when available;
+- resource kind coverage;
+- route/API coverage;
+- browser scenario coverage;
+- security negative coverage;
+- flaky tests and retries;
+- untested new files/resources.
+
+## Coverage exclusions
+
+Allowed exclusions:
+
+- generated files;
+- static docs;
+- vendored assets;
+- intentionally unreachable defensive branches when documented;
+- live-only integrations covered by staging/nightly gates.
+
+Exclusions must be explicit and reviewed.

package/docs/tests/e2e-scenario-tests.md

@@ -0,0 +1,53 @@
+# E2E and scenario tests
+
+## Existing E2E baseline
+
+Current E2E tests validate chart package surface and minikube dry-run command plans. This remains the first E2E layer because it is deterministic and does not require a live cluster.
+
+## Core forge scenarios
+
+| Scenario | Steps | Assertions |
+| --- | --- | --- |
+| Create repository | org dashboard -> repositories -> create | repository resource exists, clone instructions render, namespace/org labels exist. |
+| Pull request lifecycle | create PR -> review -> CI status -> merge | PR status, review state, pipeline/job link, policy gates. |
+| CI run lifecycle | trigger pipeline -> jobs run -> logs/events -> rerun | pipeline/job statuses, runner pool, ServiceAccount, artifacts. |
+| Webhook delivery | configure hook -> send test delivery -> replay failed delivery | signed payload, retry policy, delivery records. |
+| Deployment promotion | repo change -> deployment page -> promote/rollback | OAM/Argo status, environment scoping, audit. |
+| Org isolation | duplicate repo slug across orgs | no silent legacy route selection, cross-org API denial. |
+
+## Agent and memory scenarios
+
+| Scenario | Steps | Assertions |
+| --- | --- | --- |
+| Manual agent dispatch | repo code -> dispatch agent -> run detail | dispatch run, attempt, Agent Mux session, context bundle. |
+| Dispatch with memory | select memory source -> preview -> dispatch | memory snapshot commit, selected records, digests, redaction. |
+| Historical memory | choose `refAt` -> dispatch -> retry | retry stays pinned, stale warning shown. |
+| Import run memory | run detail -> import `.a5c` summary -> approve | redacted import, validation report, memory PR/commit. |
+| Triggered repair | failed CI -> trigger rule -> dispatch | dedupe, permission review, run row beside pipeline. |
+| Write-back approval | agent proposes patch/comment -> approve | artifact digest, approval audit, PR/comment update. |
+
+## Live cluster scenarios
+
+Nightly/staging suites should eventually run against a real cluster with:
+
+- Kubernetes API aggregation;
+- Gitea smart HTTP/SSH;
+- Postgres;
+- object storage;
+- NATS/webhook queue;
+- Argo CD/KubeVela;
+- ARC or runner abstraction;
+- Agent Mux gateway/runtime when enabled.
+
+## E2E artifacts
+
+E2E tests should collect:
+
+- generated resources;
+- API responses;
+- event/watch logs;
+- screenshots/traces for browser flows;
+- Helm manifests;
+- controller logs;
+- redaction/validation reports;
+- audit event excerpts.

package/docs/tests/fixtures-test-data.md

@@ -0,0 +1,63 @@
+# Fixtures and test data
+
+## Principles
+
+- Fixtures are deterministic and committed to the repo.
+- Fixtures must never contain real secrets, tokens, private keys, customer data, or personal data beyond synthetic examples.
+- Secret-like synthetic values should be clearly marked and used only to test redaction.
+- Every fixture has an owner and purpose.
+- Fixtures should be small enough to understand in a test failure.
+
+## Core fixtures
+
+| Fixture | Purpose |
+| --- | --- |
+| default org | simple org and namespace for current tests. |
+| duplicate org repos | route ambiguity and cross-org denial. |
+| repository with PR/issue/pipeline | core forge E2E path. |
+| webhook delivery set | success, retry, replay, signature mismatch. |
+| runner pool/job set | trusted/untrusted runner policy. |
+| deployment/OAM set | environment, promotion, rollback. |
+| company brain memory repo | graph/Markdown/frontmatter/search fixtures. |
+| `.a5c` run fixture | Babysitter run import and redaction. |
+| Agent Mux session fixture | session binding, transcript summary, events. |
+
+## Directory proposal
+
+```text
+tests/fixtures/
+  orgs/
+  repositories/
+  resources/
+  webhooks/
+  runners/
+  deployments/
+  agents/
+  memory/
+    company-brain/
+    a5c-runs/
+    sessions/
+  browser/
+```
+
+## Redaction fixture requirements
+
+Redaction fixtures should include synthetic values that look like:
+
+- API keys;
+- bearer tokens;
+- private key headers;
+- kubeconfig snippets;
+- webhook signatures;
+- high-entropy strings.
+
+Tests assert these values do not appear in prompt previews, context bundles, memory imports, transcripts, artifacts, API responses, UI, or audit records.
+
+## Fixture review checklist
+
+- No real credentials.
+- No real customer data.
+- Org labels and namespace fields included.
+- Expected status conditions documented.
+- Stable timestamps and IDs.
+- Cross-platform paths where possible.