--- id: RAILIANCE-WP-0005 type: workplan title: "S5 app release readiness and scope alignment" domain: railiance repo: railiance-apps status: active owner: codex topic_slug: railiance planning_priority: medium created: "2026-06-04" updated: "2026-06-05" state_hub_workstream_id: "685f1c18-33c0-400d-a2b1-e1dae0f27c3e" --- # S5 app release readiness and scope alignment ## Context The 2026-06-04 review of `SCOPE.md` against the actual repository implementation found that `railiance-apps` has moved beyond "Gitea Helm values" and now owns the repeatable S5 application release surface: forge-backed artifact consumption, the `vergabe-teilnahme` Helm release, operator guardrails, and deployment runbooks. The 2026-06-05 `railiance-forge` extraction moved canonical registry operating docs and registry-retention policy into the new forge layer. This workplan now keeps only app-release readiness items in S5. The same review found several gaps: - `INTENT.md` is missing, so purpose and scope are collapsed into one document. - The `vergabe-teilnahme` runbook still contains stale image-promotion guidance tied to the old local `issue-core` build context. - First-app lessons are documented, but there is no reusable checklist for the next S5 app release. - Forge package storage and app database backup responsibilities need clearer contracts with platform-layer work. - The server-side dry-run workflow does not state its live-cluster/CRD prerequisites clearly enough for a future runner. This workplan turns those scope gaps into the next improvement strand. ## T01 - Write `INTENT.md` ```task id: RAILIANCE-WP-0005-T01 status: done priority: high state_hub_task_id: "af15d202-c013-48b1-8522-671477e31381" ``` Create `INTENT.md` for `railiance-apps`. It should explain: - why this repo exists as the S5 application deployment surface; - what problem it solves for operators and source app repos; - what it intentionally does not own across S1-S4 boundaries; - how forge-owned registry capabilities, `vergabe-teilnahme`, and future S5 apps fit together; - how workplan files relate to State Hub workstreams and task rows. Done when `INTENT.md` stands on its own and `SCOPE.md` can reference it instead of carrying all purpose language itself. --- ## T02 - Normalize app image promotion and package registry docs ```task id: RAILIANCE-WP-0005-T02 status: done priority: high state_hub_task_id: "f8f63edb-a7ef-4692-8b01-66402d296cbb" ``` Update app promotion docs after the `issue-core` package handoff is complete. Focus areas: - remove stale references to the old `--build-context issue-core=...` path from `docs/vergabe-teilnahme.md`; - document the package-registry credential path for private Python package installs without committing tokenized index URLs; - state when `vergabe-teilnahme/uv.lock` must be regenerated in the source repo; - link to forge-owned registry endpoint docs and source-repo release docs instead of duplicating them in S5. Done when the Railiance operator docs describe the portable image promotion path and no active runbook tells an operator to rely on a sibling repo checkout. Completed on 2026-06-05 by updating `docs/vergabe-teilnahme.md` and replacing local registry ownership with direct links to `railiance-forge`. The temporary compatibility pointers were removed later by `RAILIANCE-WP-0006-T10`. --- ## T03 - Create a reusable S5 app onboarding checklist ```task id: RAILIANCE-WP-0005-T03 status: todo priority: medium state_hub_task_id: "4eab93a9-ad1b-46ca-97ef-18a059f64ab5" ``` Turn the `vergabe-teilnahme` deployment lessons into a reusable checklist for the next S5 app. The checklist should cover: - chart and values layout; - ingress and TLS ownership; - health probe Host headers for framework apps; - database secret handoff and URL-encoding guidance; - image registry naming and pull verification; - runbook sections every S5 app should ship; - smoke-test pattern using persistent pods plus `kubectl exec`; - State Hub workplan and task-sync expectations. Done when a new app can start from the checklist without reading all historical workplans first. --- ## T04 - Define app data backup and restore handoffs ```task id: RAILIANCE-WP-0005-T04 status: todo priority: high state_hub_task_id: "299d9623-3a54-4e85-9a70-016e8356c3d9" ``` Clarify where S5 app data durability begins and ends. Cover at least: - `vergabe_db` on the shared `apps-pg` CNPG cluster; - responsibility split between S5 runbooks and `railiance-platform` backup controllers; - minimum restore-drill evidence S5 app operators need before promoting an app beyond smoke-test usage; - how to file or link platform-layer workplans when the durability gap is not local to this repo. - how S5 app runbooks cite forge-owned package/blob restore evidence without owning Gitea package backup procedures. Done when `SCOPE.md` and app runbooks clearly separate S5 release ownership from S3 backup implementation while still giving operators an actionable restore readiness gate. --- ## T05 - Make manifest dry-run workflow prerequisites explicit ```task id: RAILIANCE-WP-0005-T05 status: todo priority: medium state_hub_task_id: "6cf0e662-d7e2-48b1-b1f2-c7636240dd81" ``` Document and, where useful, encode the assumptions behind `.gitea/workflows/manifest-server-dry-run.yaml` and `make k8s-server-dry-run`. Questions to answer: - Does the workflow expect a live representative cluster? - Which CRDs must already exist for server-side dry-run to be meaningful? - What credentials or runner placement are required? - What should happen when a runner has no cluster access? - Which failures are release-blocking versus local operator setup issues? Done when a future operator can tell whether the workflow is ready to enforce PR checks or still needs runner/cluster preparation. --- ## T06 - Hand off Gitea package registry storage and retention posture ```task id: RAILIANCE-WP-0005-T06 status: done priority: medium state_hub_task_id: "382ba252-0f54-45fa-8e33-e656f4472341" ``` Document the forge-owned operating posture for Gitea package storage while Gitea remains the active forge. Include: - current PVC, size, and package blob location; - expected retention approach for smoke-test images and Python wheels; - cleanup procedure for superseded test tags; - alert or inspection command for package storage growth; - handoff to platform backup/restore work when package data becomes production critical. Done when registry growth is no longer only a note in S5 app docs. Completed on 2026-06-05 by moving the canonical storage and retention posture to `/home/worsch/railiance-forge/docs/initial-operating-contracts.md`; S5 app runbooks now cite forge docs directly.