feat(gitops): distinguish accidental removal from intentional retirement and automatically reclaim owned data #5627

Outcome

The agent-operated GitOps platform safely distinguishes an accidental removal of application manifests from an intentionally requested retirement. Intentional retirement automatically removes the application, its exclusively owned data and associated resources when safe, with no maintainer PR review, manual Kubernetes/cloud API calls, or routine cleanup chores. Accidental edits or speculative merge-queue deployments must never irreversibly destroy data.

Maintainer direction (2026-10-31)

• The maintainer states the need (e.g., "retire application X"). Agents are the engineering owners: validate downstream dependencies, shared resources, operational consequences and data ownership; choose the method. They must flag a material risk via a maintainer ask, or reject/explain an unsafe task, rather than blindly executing instructions.
• A disappearing Kustomize entry, namespace, HelmRelease or PVC is not sufficient proof of authorization to delete permanent data.
• A deliberate, reviewable, declarative retirement intent in committed Git state may authorize automatic cleanup. Merge-queue candidates are not committed intent; they must not destroy production state. Agent-managed PR checks and merge gates remain; no human PR approval is a requirement.
• No arbitrary mandatory 24-hour wait. Agents should select the simplest safe retirement mechanism, with retention/cooling-off only when the risk model justifies it. Successful safe retirements should not need a manual trigger.
• App owners/controllers manage their data lifecycle; infrastructure reclamation must not infer that retained application data can be dropped simply because storage is underutilized. Retired applications' resources must not be mistaken for unrelated shared resources, backup sets or bootstrap dependencies.
• Clean up or explicitly retain and account for orphaned PVs, Longhorn volumes, Hetzner volumes, secrets, DNS, backing stores and backups as ownership and retention rules permit. Nothing quietly leaks costs.

Existing context; integrate, do not duplicate

• Make GitOps the source of truth for deletion: retain data at the storage layer instead of opting out of prune #3369: GitOps source of truth and Retain instead of prune opt-outs.
• Make the Longhorn storage classes retain deleted volumes #4439, Make the hcloud storage class retain deleted volumes #4440, Set every existing volume to Retain and report the ones that are not #4441: protect StorageClasses and existing PVs.
• Write and drill the procedure for reclaiming a released volume #4442: verified recovery/discard of released PVs.
• An evicted merge-queue candidate must delete nothing in production #4443: prevent destructive deployment from evicted merge-group candidates (must be a safety gate).
• Document tenant decommissioning as deleting the tenant's directory #4445: tenant decommissioning documentation.
• Consult existing docs/adr/storage-retention.md and owner-specific cleanup workflows; preserve the established sequencing and avoid unsafe shortcuts.

Acceptance criteria

• A declarative, testable, auditable distinction between accidental manifest disappearance and explicit agent-authorized permanent retirement.
• After a safe committed retirement, the app and only its exclusively owned data/resources are automatically reclaimed; cloud/storage deletion is verified. No manual API calls or routine human approval required.
• A broken Kustomize change, an evicted/failed merge-group candidate, a mistaken tenant removal and a retried/partially failed cleanup do not cause irreversible data loss.
• The tool refuses/reports unsafe cleanup (dependent services, shared datasets, unknown owner, critical backups, unproven data retention) and raises a bounded maintainer ask only for genuinely unresolved business risk; agents may abandon an unsafe retirement with explanation.
• Existing retained PVs are recoverable where required; cleanup and retained-data handling coexist with Retain and do not reintroduce blanket prune opt-outs.
• Clean replay/idempotency after workflow/controller restarts, GitOps drift, partial failure and rollback; tests cover deletion proof, ownership boundaries and dependency graph.
• Show retirement intent, safeguards, outcome, intentionally retained resources and continuing storage costs in Git/observability, without leaking secrets.
• Verify an intentional retirement and a mistaken-removal scenario end-to-end in a safe fixture before production; update operational documentation.
• Close or link existing overlapping work only after evidence; do not assert the feature is delivered merely because retention was implemented.

Deliver an outcome, not a mandated custom controller. Agents own the technical solution and may challenge maintainer assumptions with evidence.