Clarify app scope and plan forge extraction
This commit is contained in:
195
workplans/RAILIANCE-WP-0005-s5-app-release-readiness.md
Normal file
195
workplans/RAILIANCE-WP-0005-s5-app-release-readiness.md
Normal file
@@ -0,0 +1,195 @@
|
||||
---
|
||||
id: RAILIANCE-WP-0005
|
||||
type: workplan
|
||||
title: "S5 app release readiness and scope alignment"
|
||||
domain: railiance
|
||||
repo: railiance-apps
|
||||
status: ready
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: medium
|
||||
created: "2026-06-04"
|
||||
updated: "2026-06-04"
|
||||
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: Gitea registry
|
||||
enablement, the `vergabe-teilnahme` Helm release, operator guardrails, and
|
||||
deployment runbooks.
|
||||
|
||||
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.
|
||||
- Gitea 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 Gitea, package registry enablement, `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: todo
|
||||
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;
|
||||
- keep `docs/gitea-package-registry.md` focused on the S5 registry endpoint and
|
||||
cross-link source-repo release docs instead of duplicating them.
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
|
||||
- Gitea package blobs on the shared Gitea PVC;
|
||||
- `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.
|
||||
|
||||
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 - Define Gitea package registry storage and retention posture
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0005-T06
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "382ba252-0f54-45fa-8e33-e656f4472341"
|
||||
```
|
||||
|
||||
Document the 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
|
||||
`docs/gitea-container-registry.md`.
|
||||
351
workplans/RAILIANCE-WP-0006-railiance-forge-extraction.md
Normal file
351
workplans/RAILIANCE-WP-0006-railiance-forge-extraction.md
Normal file
@@ -0,0 +1,351 @@
|
||||
---
|
||||
id: RAILIANCE-WP-0006
|
||||
type: workplan
|
||||
title: "Extract railiance-forge and formalize forge-layer contracts"
|
||||
domain: railiance
|
||||
repo: railiance-apps
|
||||
status: ready
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
created: "2026-06-04"
|
||||
updated: "2026-06-04"
|
||||
state_hub_workstream_id: "1960b22b-82ae-4b67-9fff-397bd38bdd65"
|
||||
---
|
||||
|
||||
# Extract railiance-forge and formalize forge-layer contracts
|
||||
|
||||
## Context
|
||||
|
||||
The 2026-06-04 intent review found the S1-S5 Railiance framework mostly sound:
|
||||
|
||||
```text
|
||||
railiance-infra -> railiance-cluster -> railiance-platform ->
|
||||
railiance-enablement -> railiance-apps
|
||||
```
|
||||
|
||||
The main architecture smell is not the vertical layering. It is the set of
|
||||
cross-cutting forge concerns currently straddling S4 and S5:
|
||||
|
||||
- Gitea/Forgejo runtime ownership;
|
||||
- container and Python package registries;
|
||||
- Actions runners and CI/CD substrate;
|
||||
- source-hosting operational runbooks;
|
||||
- artifact lifecycle, retention, and restore posture;
|
||||
- package/image promotion evidence used by application releases.
|
||||
|
||||
The decision is to create a dedicated `railiance-forge` repository rather than
|
||||
leaving forge responsibilities split between `railiance-apps` and
|
||||
`railiance-enablement`.
|
||||
|
||||
This workplan coordinates the extraction and the accompanying framework
|
||||
contracts so the new repo becomes a clean abstraction rather than another place
|
||||
for cross-layer drift.
|
||||
|
||||
## Boundary Target
|
||||
|
||||
`railiance-forge` should own:
|
||||
|
||||
- current Gitea operation and future Forgejo migration/cutover;
|
||||
- source forge deployment configuration and runbooks;
|
||||
- container, package, and release artifact registries;
|
||||
- forge-backed Actions runner substrate and repository automation hooks;
|
||||
- artifact retention, registry storage, and restore readiness;
|
||||
- forge observability and operational evidence;
|
||||
- Fabric declarations for forge capabilities and interfaces.
|
||||
|
||||
`railiance-forge` should not own:
|
||||
|
||||
- server provisioning and OS hardening (`railiance-infra`);
|
||||
- Kubernetes runtime primitives, ingress controllers, and cluster addons
|
||||
(`railiance-cluster`);
|
||||
- shared databases, object storage, caches, and runtime secret custody
|
||||
(`railiance-platform`);
|
||||
- generic workload templates, SDKs, and developer portal surfaces
|
||||
(`railiance-enablement`);
|
||||
- user-facing application release charts and app runbooks
|
||||
(`railiance-apps`);
|
||||
- application source code, package metadata, and image build definitions in
|
||||
source repos.
|
||||
|
||||
## T01 - Define the `railiance-forge` repository contract
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0006-T01
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "129c2920-8868-4118-8772-ff5d925588cd"
|
||||
```
|
||||
|
||||
Write the initial repository contract for `railiance-forge`.
|
||||
|
||||
Deliverables:
|
||||
|
||||
- `INTENT.md` explaining why the forge layer exists;
|
||||
- `SCOPE.md` defining in-scope and out-of-scope responsibilities;
|
||||
- `AGENTS.md` with State Hub integration, workplan prefix, repo identity, and
|
||||
task-status vocabulary aligned with current State Hub canon;
|
||||
- initial workplan convention using a new prefix, for example `FORGE-WP-`;
|
||||
- explicit relationship to `railiance-apps`, `railiance-enablement`,
|
||||
`railiance-platform`, and `railiance-cluster`.
|
||||
|
||||
Done when the repo can be created without ambiguity about whether forge work
|
||||
belongs there.
|
||||
|
||||
---
|
||||
|
||||
## T02 - Create and register the `railiance-forge` repository
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0006-T02
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "0e71e5a6-ce3c-4334-abf3-750aa8bef4df"
|
||||
```
|
||||
|
||||
Create the sibling repository and connect it to the work coordination model.
|
||||
|
||||
Steps:
|
||||
|
||||
- create `/home/worsch/railiance-forge`;
|
||||
- initialize Git metadata and baseline files;
|
||||
- add `INTENT.md`, `SCOPE.md`, `AGENTS.md`, `README.md`, and a first workplan;
|
||||
- create or register the State Hub topic for the new repo;
|
||||
- run `make fix-consistency REPO=railiance-forge` once State Hub knows the repo;
|
||||
- verify that the new workplan appears as a State Hub workstream.
|
||||
|
||||
Done when `railiance-forge` is a first-class sibling repo with State Hub
|
||||
indexing and no reliance on `railiance-apps` as its planning home.
|
||||
|
||||
---
|
||||
|
||||
## T03 - Move current forge deployment surface out of `railiance-apps`
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0006-T03
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "57162f50-d1a4-4fb3-b4fa-503939b22450"
|
||||
```
|
||||
|
||||
Move the existing Gitea/registry operational surface into `railiance-forge`.
|
||||
|
||||
Candidate source files in `railiance-apps`:
|
||||
|
||||
- `helm/gitea-values.sops.yaml`;
|
||||
- `helm/gitea-registry-values.yaml`;
|
||||
- `manifests/gitea-ingress.yaml`;
|
||||
- `releases/gitea/values.yaml`;
|
||||
- Gitea-related `Makefile` targets;
|
||||
- `docs/gitea-container-registry.md`;
|
||||
- `docs/gitea-package-registry.md`;
|
||||
- Gitea/package-registry sections in `SCOPE.md` and workplans.
|
||||
|
||||
Migration rules:
|
||||
|
||||
- preserve secret boundaries and do not expose decrypted values;
|
||||
- keep the existing deployed service stable during the repo move;
|
||||
- leave compatibility pointers in `railiance-apps` until operators have the
|
||||
new paths;
|
||||
- do not mix this move with the future Forgejo production cutover unless an
|
||||
explicit cutover workplan says to.
|
||||
|
||||
Done when `railiance-apps` no longer owns source-forge deployment config, and
|
||||
current Gitea operation has an equivalent or better home in `railiance-forge`.
|
||||
|
||||
---
|
||||
|
||||
## T04 - Re-scope `railiance-apps` and `railiance-enablement`
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0006-T04
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "64ac73e7-abe5-47df-abbc-51aed25a7ce4"
|
||||
```
|
||||
|
||||
Update the adjacent repos so the new abstraction is visible in their own
|
||||
contracts.
|
||||
|
||||
In `railiance-apps`:
|
||||
|
||||
- remove Gitea/Forgejo as an owned S5 workload after migration;
|
||||
- describe forge services as upstream release infrastructure consumed by app
|
||||
releases;
|
||||
- keep application charts, app-level runbooks, smoke tests, and deployment
|
||||
guardrails in S5;
|
||||
- update `RAILIANCE-WP-0005` tasks that mention Gitea package storage so they
|
||||
point to the new forge ownership.
|
||||
|
||||
In `railiance-enablement`:
|
||||
|
||||
- clarify that reusable CI/CD templates and developer portal paths live in S4;
|
||||
- clarify that the forge runtime, package registries, and Actions runner
|
||||
substrate live in `railiance-forge`;
|
||||
- define the handoff from S4 templates to forge-hosted automation.
|
||||
|
||||
Done when a new operator can answer "is this S4, S5, or forge?" from the scope
|
||||
documents without inspecting historical workplans.
|
||||
|
||||
---
|
||||
|
||||
## T05 - Define artifact lifecycle, retention, and provenance policy
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0006-T05
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "a99520c3-91dc-4af0-9f9b-0f0b53137be5"
|
||||
```
|
||||
|
||||
Make artifact ownership explicit for images, packages, and source-hosted
|
||||
release assets.
|
||||
|
||||
Cover:
|
||||
|
||||
- container image retention for smoke, development, and production tags;
|
||||
- Python package retention for internal libraries such as `issue-core`;
|
||||
- package/blob storage location and capacity inspection;
|
||||
- cleanup commands and operator guardrails;
|
||||
- artifact provenance expectations, including commit SHA tagging;
|
||||
- future SBOM, vulnerability scanning, signing, and attestations;
|
||||
- what evidence S5 needs before consuming a new artifact in an app release.
|
||||
|
||||
Done when package and image growth, cleanup, and release evidence are not
|
||||
implicit tribal knowledge.
|
||||
|
||||
---
|
||||
|
||||
## T06 - Define CI runner, Actions, and GitOps ownership
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0006-T06
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "37945939-e7c5-4717-83d9-294873810fb3"
|
||||
```
|
||||
|
||||
Set the boundary between forge runtime, S4 reusable automation, and S5 release
|
||||
checks.
|
||||
|
||||
Questions to answer:
|
||||
|
||||
- Which repo owns Gitea/Forgejo Actions runner deployment and credentials?
|
||||
- Which repo owns workflow templates?
|
||||
- Which repo owns app-specific workflows?
|
||||
- How are runner labels, placement, and secret access controlled?
|
||||
- What is the cutover path from current Gitea Actions to future Forgejo?
|
||||
- Which server-side manifest dry-run checks belong in S5, and which runner
|
||||
prerequisites belong in forge?
|
||||
|
||||
Done when CI runner substrate and CI/CD templates no longer blur together.
|
||||
|
||||
---
|
||||
|
||||
## T07 - Define backup, restore, and secret handoff contracts
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0006-T07
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "da8bfbab-4bc3-48f0-9837-acf43fec9f0c"
|
||||
```
|
||||
|
||||
Document how forge data and credentials interact with platform services.
|
||||
|
||||
Cover:
|
||||
|
||||
- forge database and package blob backup responsibilities;
|
||||
- restore drills for source repos, packages, runners, and registry data;
|
||||
- handoff to `railiance-platform` for CNPG/object-storage backup mechanisms;
|
||||
- secret custody boundaries with SOPS/age bootstrap and OpenBao runtime
|
||||
delivery;
|
||||
- what operators may reference in docs without storing live secret values;
|
||||
- how S5 apps verify forge artifacts without owning registry credentials.
|
||||
|
||||
Done when the forge repo can state exactly what it owns, what S3 implements,
|
||||
and what evidence consumers can rely on.
|
||||
|
||||
---
|
||||
|
||||
## T08 - Add forge observability and operating evidence requirements
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0006-T08
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "ce2ebe48-052a-4e3e-86aa-441274940078"
|
||||
```
|
||||
|
||||
Close the framework gap around observability for the forge layer.
|
||||
|
||||
Define at least:
|
||||
|
||||
- health checks for web, SSH, registry, package, and Actions endpoints;
|
||||
- log inspection and dashboard expectations;
|
||||
- storage growth checks for package/blob data;
|
||||
- alert thresholds or manual inspection commands;
|
||||
- release-readiness evidence that downstream app deployments can cite;
|
||||
- where future centralized observability should live if a dedicated repo or
|
||||
S3/S4 surface is created.
|
||||
|
||||
Done when forge availability and artifact health can be inspected without
|
||||
manually reconstructing the system.
|
||||
|
||||
---
|
||||
|
||||
## T09 - Add Railiance Fabric declarations for forge capabilities
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0006-T09
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "fd231acc-fe55-417f-a27b-797e1f520e1d"
|
||||
```
|
||||
|
||||
Use `railiance-fabric` to make the new layer visible as a graph contract.
|
||||
|
||||
Declare forge capabilities such as:
|
||||
|
||||
- source hosting;
|
||||
- Git SSH endpoint;
|
||||
- container registry;
|
||||
- Python package registry;
|
||||
- workflow runner substrate;
|
||||
- artifact promotion evidence.
|
||||
|
||||
Declare dependencies such as:
|
||||
|
||||
- Kubernetes runtime from `railiance-cluster`;
|
||||
- database, object storage, and secret services from `railiance-platform`;
|
||||
- CI/CD templates from `railiance-enablement`;
|
||||
- app release consumers from `railiance-apps`.
|
||||
|
||||
Done when State Hub or local Fabric tooling can show the new forge layer's
|
||||
provider and consumer edges without relying only on prose docs.
|
||||
|
||||
---
|
||||
|
||||
## T10 - Decommission compatibility pointers after migration
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0006-T10
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "5bca2a11-453c-4cd0-b86a-7ed269564dfb"
|
||||
```
|
||||
|
||||
After the new repo is operational, clean up transitional references.
|
||||
|
||||
Steps:
|
||||
|
||||
- remove stale Gitea/registry ownership language from `railiance-apps`;
|
||||
- update docs that point to old file locations;
|
||||
- archive or supersede workplans that were only about forge ownership in S5;
|
||||
- ensure State Hub workstreams reference the new repo for forge work;
|
||||
- run consistency sync for affected repos;
|
||||
- record a final decision that `railiance-forge` is the source of truth for
|
||||
forge runtime and artifact-registry operations.
|
||||
|
||||
Done when no active railiance workplan asks operators to modify forge runtime
|
||||
state from the wrong repo.
|
||||
Reference in New Issue
Block a user