# Delivery Ownership

## Status

This is the approved target architecture. The current source-owned onboarding
implementation is being migrated and must not be used for new applications.

## Trust Boundary

Application repositories are build inputs, not GitOps inputs. A developer can
change application code on `main`, but cannot change an active Pipeline, Task,
runtime secret reference, Helm chart, environment value, or promotion policy.

| Concern | Owner | Location |
| --- | --- | --- |
| Application code, tests, Dockerfile | Developers | `Maidn/<app>` `main` |
| Approved charts and environment values | Platform | `Maidn/<app>` `maidn/platform-<app>` |
| Pipeline, Tasks, triggers, runtime access | Platform | Cluster repository |
| Image tags, preview ownership, promotion PRs | Platform | Deployment manifests repository |
| Secret values and policies | Platform | Private config, SOPS operational state, OpenBao |

The protected platform branch may be readable by developers, but only platform
operators and approved automation may push or merge into it. Flux must track
only that branch for chart content. Flux must never track an application `main`
branch or `maidn/delivery-*` branch.

## Resource Flow

```mermaid
flowchart LR
  App[Application main branch\ncode only]
  Platform[Protected platform branch\nchart and values]
  Cluster[Cluster repository\nPipeline, Tasks, secret access]
  Manifests[Manifests repository\nimage tags and promotion]
  Flux[Flux]
  Workload[Preview, staging, production]

  App -->|exact source SHA| Cluster
  Cluster --> Manifests
  Platform --> Flux
  Manifests --> Flux
  Flux --> Workload
```

The central Pipeline clones the application repository at the event SHA only to
build an image. It obtains chart content from the protected platform branch and
writes only image-tag and promotion state to the manifests repository.

## Prohibited Application Content

Application repositories must not contain active delivery control-plane
resources:

- `.tekton/` Pipeline or Task resources
- `.maidn/` Flux, RBAC, SecretStore, or ExternalSecret resources
- Flux Kustomizations or GitRepositories
- Kubernetes Secret values, SOPS identities, OpenBao tokens, or kubeconfigs

An application `main` branch may retain a chart as a developer proposal, but it
has no delivery effect. A platform operator explicitly reviews and copies an
approved chart and environment values to `maidn/platform-<app>`.

## Approval Sequence

1. A platform operator creates or updates the protected platform branch through
   a reviewed platform PR.
2. A platform operator reviews and merges the central cluster registration that
   renders the Pipeline, Tasks, protected chart source, and runtime references.
3. Flux applies only the central cluster resources and protected chart branch.
4. Developers use Forgejo pull requests and pushes to trigger builds; they do
   not edit deployment control-plane resources.
5. Production promotion remains a reviewed PR in the manifests repository.

## Migration Rules

Existing source-owned registrations are migrated one application at a time.
First establish the protected platform package, then merge the central cluster
registration, then verify Flux and delivery. Remove the legacy source
GitRepository, Kustomizations, and delivery branch only after the replacement
is Ready.

The canonical fixtures are migration pilots. `Maidn/maidn-e2e-secret` remains
disabled until its central replacement is reviewed. Angular and web legacy
registrations must follow the same migration path.

## Command Status

`cicd-tool bootstrap`, `cicd-tool app`, and `cicd-tool e2e` are the current
Forgejo and GitOps command families. `cicd-tool repo init` and `cicd-tool vault
create-*` are legacy GitHub/direct-apply paths and are not part of new platform
onboarding. They will be deprecated or removed after the central delivery
migration.

## Acceptance

The architecture is accepted only after a canonical fixture proves all of the
following with a real Forgejo event:

- pull request preview build, route, and delivery feedback
- main-to-staging deployment at an immutable image SHA
- reviewed production promotion PR
- runtime secret and shared database projection without preview credentials
- closed-preview cleanup and orphan-cleaner recovery