Merge pull request 'docs: define central delivery ownership' (#60) from docs/central-delivery-ownership into main

Reviewed-on: #60

AGENTS.md

@@ -16,6 +16,15 @@
 - The testing suite, onboarding, and mutation E2E commands must target `Maidn` fixture sources.
 - `test-org-2` is disposable execution state only. It may host temporary delivery branches and resources, but it is never a fixture source or test-suite owner.
 
+## Delivery Ownership
+
+- Application repositories are build inputs only; do not add or update active
+  `.tekton/` or `.maidn/` delivery resources in them.
+- The cluster repository owns Pipelines, Tasks, triggers, and runtime secret
+  access. The manifests repository owns image tags and promotion state.
+- Flux chart sources must use only the protected `maidn/platform-<app>` branch,
+  never an application `main` or `maidn/delivery-*` branch.
+
 ## Required Checks
 
 - Before each commit: inspect `git status --short`, `git diff --check`, and `git log --oneline -10`.

README.md

@@ -1,26 +1,15 @@
 ## Commands
 
-go mod init github.com/Pingu-Studio/MaidnCLI
-go get -u github.com/spf13/cobra@latest
-go get golang.org/x/term
-go mod tidy
-go get gopkg.in/yaml.v3
-
-in powershell run
-```powershell
-go install github.com/go-delve/delve/cmd/dlv@latest
-dlv version
-```
-## Commands
-
-- `cicd-tool repo init --org <org> --flux-repo <repo>` creates the manifests and Flux repos
+- `cicd-tool repo init` is a legacy GitHub workflow and is not used for new Forgejo/GitOps platform onboarding.
 - `cicd-tool bootstrap` runs a shorter Forgejo-first wizard, asks for a Forgejo PAT, asks where local repos should be cloned, discovers Proxmox nodes/storage/networks, retries without losing entered answers when discovery fails, shows the latest Talos version, derives the standardized Talos factory URL, schematic, and required extensions automatically from the chosen version, writes `terraform.tfvars`, stages Talos images on Proxmox, and can execute Terraform, Talos bootstrap, and Flux bootstrap
 - `cicd-tool bootstrap --config maidn-bootstrap.yaml` skips the wizard and uses the saved config
-- `maidn bootstrap init --config <private-config> --organization <new-org> --create-organization --enable-delivery` locks an isolated workspace, initializes the Forgejo repositories, then runs the non-destructive bootstrap reconcile lifecycle; use `--mode=rebuild --yes` for an authorized rebuild. Delivery scaffolding requires `--enable-delivery`.
-- `maidn app onboard --config <private-config> --from <app-checkout>` opens reviewed source-delivery and cluster-registration PRs; see `docs/operations.md`.
+- `cicd-tool bootstrap init --config <private-config> --organization <new-org> --create-organization` locks an isolated workspace, initializes Forgejo repositories, then runs the non-destructive bootstrap reconcile lifecycle. Use `--mode=rebuild --yes` only for an authorized rebuild.
+- `cicd-tool app onboard --config <private-config> --from <app-checkout>` is being migrated to central delivery ownership. Do not use the source-owned implementation for new applications; see `docs/architecture/delivery-ownership.md`.
 - `cicd-tool e2e` runs bounded, read-only Flux, ExternalSecret, PipelineRun, preview, and promotion-PR checks with JSON output. See `docs/e2e.md`.
 
 See `docs/operations.md` for the authorized operating and verification runbook.
+See `docs/architecture/delivery-ownership.md` for the developer and platform
+ownership boundary.
 App authors: see `docs/delivery-feedback.md` for preview feedback and the scoped Forgejo token contract.
 
 ## Forgejo setup

docs/architecture/delivery-ownership.md

@@ -0,0 +1,103 @@
+# 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

docs/delivery-feedback.md

@@ -1,10 +1,11 @@
 # Delivery feedback
 
-`maidn app onboard` adds source-owned Tekton tasks that update one marked
-Forgejo pull-request comment. The comment contains only the verified preview
-URL, a redacted task-status summary, and the PipelineRun name. Set the optional
-`delivery.tektonDashboardUrl` to a credential-free HTTPS Tekton Dashboard
-origin to add a PipelineRun link.
+The central cluster registration owns the Tekton tasks that update one marked
+Forgejo pull-request comment. Application repositories do not carry active
+delivery Tasks. The comment contains only the verified preview URL, a redacted
+task-status summary, and the PipelineRun name. Set the optional
+`delivery.tektonDashboardUrl` to a credential-free HTTPS Tekton Dashboard origin
+to add a PipelineRun link.
 
 Before enabling delivery feedback, create the separate Forgejo token with
 `bootstrap --config <private-bootstrap-config> --create-forgejo-delivery-status-token`.
@@ -17,5 +18,6 @@ Forgejo API responses.
 Preview and staging feedback waits up to ten minutes for the app Deployment
 and HTTPRoute, then performs a bounded HTTPS check. A production event reports
 the manifest-repository promotion PR; it does not claim a production deploy.
-The chart must name both resources after `delivery.appName`; the HTTPRoute's
-first hostname must be the public HTTPS preview/staging URL.
+The protected `maidn/platform-<app>` chart must name both resources after
+`delivery.appName`; the HTTPRoute's first hostname must be the public HTTPS
+preview/staging URL.

docs/e2e.md

@@ -29,3 +29,10 @@ Build the portable OCI runner with `docker build -t maidn-e2e-runner .`.
 Mount the kubeconfig and optional token file read-only; ensure they are readable
 by the image's non-root user. The build context excludes known secret-bearing
 bootstrap inputs.
+
+## Fixture Boundary
+
+Use `cicd-tool e2e-mutate` only with canonical `Maidn/maidn-e2e-*` fixtures.
+The test runner must prove preview, staging, production promotion, runtime
+secret/database access, preview cleanup, and orphan cleanup against central
+delivery resources. It must not mutate `test-org-2` as a fixture source.

docs/operations.md

@@ -43,10 +43,15 @@ creates the Gateway, Tekton, and Tekton Triggers platform resources using
 go run . bootstrap init --config <private-bootstrap-config> --organization <owner> --create-organization
 ```
 
-Use a clean checkout on `delivery.appRepoRef`. The app repository URL must be
-the canonical source owner, such as `Maidn/<app>.git`; `test-org-2` is only the
-execution owner. Set per-app static build values with command-line overrides,
-not by rewriting the private default:
+The source-owned onboarding implementation is being retired. Do not onboard a
+new application until the central delivery renderer is available. See
+[Delivery Ownership](architecture/delivery-ownership.md) for the approved
+architecture and migration rules.
+
+The future onboarding command uses a clean checkout on `delivery.appRepoRef`.
+The app repository URL must be the canonical source owner, such as
+`Maidn/<app>.git`; `test-org-2` is execution state only. Per-app static build
+values remain command-line overrides rather than private defaults:
 
 ```powershell
 go run . app onboard --config <private-bootstrap-config> --from <clean-checkout> `
@@ -56,16 +61,13 @@ go run . app onboard --config <private-bootstrap-config> --from <clean-checkout>
 ```
 
 For a runtime build, set `--build-strategy runtime`; static-only output options
-remain harmless. Onboarding opens, but never merges, a source delivery PR and a
-cluster registration PR. It registers the Forgejo hook but does not emit a test
-delivery. Review and merge the source delivery PR first, then the cluster
-registration PR. The registration is stored in
-`base/tekton/apps/<app>.yaml`; Flux loads the source-owned `.tekton` path and
-the generic EventListener dispatches by Forgejo repository name.
+remain harmless. Central onboarding will create reviewed platform-branch and
+cluster-registration changes. The cluster repository will own
+`base/tekton/apps/<app>.yaml`; the application repository will remain a build
+input only. The generic EventListener dispatches by Forgejo repository name.
 
-Existing registrations are never overwritten. Move a legacy source registration
-to its canonical source in a separate reviewed cluster-repository PR before
-onboarding that application.
+Existing source-owned registrations are migrated in separate reviewed cluster
+repository PRs. Never overwrite an unmanaged registration.
 
 After Flux reports the app Kustomization Ready, use Forgejo's hook test endpoint
 against a non-`main` ref and inspect the resulting PipelineRun. The command and
@@ -80,14 +82,11 @@ by default. Shared credentials are appropriate only for the shared environment
 database. Use a dedicated service only when isolation, lifecycle, or storage
 requirements demand it.
 
-An application can carry reviewed dedicated resources in
-`.maidn/kustomization.yaml`. Onboarding registers that path as the app's
-`<app>-addons` Flux Kustomization without changing the generated `.tekton`
-files. Runtime secret grants also generate the app's `.maidn/secret-access.yaml`
-there. Add-ons must declare their namespace explicitly and contain references,
-never credential values. Preview namespaces do not receive staging or production
-runtime credentials; preview-safe configuration is the application chart's
-responsibility.
+The cluster repository owns reviewed dedicated resources and runtime secret
+access. Application repositories must not carry active `.maidn` resources.
+Runtime references never contain credential values. Preview namespaces do not
+receive staging or production runtime credentials; preview-safe configuration is
+defined in the protected platform chart branch.
 
 Declare runtime secret access in the private configuration and run normal
 bootstrap reconciliation to create its policy and role. Set values only with