railiance-apps/workplans/archived/260702-RAILIANCE-WP-0005-s5-app-release-readiness.md

---
id: RAILIANCE-WP-0005
type: workplan
title: "S5 app release readiness and scope alignment"
domain: financials
repo: railiance-apps
status: finished
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"
---

> **Terminology note:** Historical text in this archived workplan may use the legacy term "workstream". The fleet term is **workplan** (`canon/standards/workplan-terminology-fleet_v0.1.md`).

# 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 planning-time gaps that are closed by this
workplan:

- `INTENT.md` was missing, so purpose and scope were collapsed into one
  document.
- The `vergabe-teilnahme` runbook contained stale image-promotion guidance tied
  to the old local `issue-core` build context.
- First-app lessons were documented, but not yet turned into a reusable
  checklist for the next S5 app release.
- Forge package storage and app database backup responsibilities needed clearer
  contracts with platform-layer work.
- The server-side dry-run workflow did 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: done
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.

Completed on 2026-06-05 by adding
`docs/s5-app-onboarding-checklist.md` and cross-linking it from `SCOPE.md` and
the `vergabe-teilnahme` runbook. The checklist covers app scope, chart/values
layout, forge artifact consumption, database and secret handoff, ingress/TLS,
probe Host headers, smoke tests, runbook baseline, and State Hub sync.

---

## T04 - Define app data backup and restore handoffs

```task
id: RAILIANCE-WP-0005-T04
status: done
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.

Completed on 2026-06-05 by adding
`docs/app-data-backup-restore-handoff.md`, updating
`docs/vergabe-teilnahme.md`, and refreshing `SCOPE.md`. The handoff states that
S5 owns app release evidence and post-restore app checks, while
`railiance-platform` owns `apps-pg` backup/restore mechanisms and
`railiance-forge` owns artifact restore evidence.

---

## T05 - Make manifest dry-run workflow prerequisites explicit

```task
id: RAILIANCE-WP-0005-T05
status: done
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.

Completed on 2026-06-05 by adding
`docs/manifest-server-dry-run.md`, updating `docs/operator-recipes.md`, and
making `tools/k8s-server-dry-run.sh` print an explicit representative-cluster
preflight error. The docs classify runner/cluster prerequisite gaps separately
from release-blocking manifest failures and note that
`DRY_RUN_CREATE_NAMESPACES=true` creates the namespace as a real side effect.

---

## 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.