Files

tegwick e52eab1791 Link forge move review in workplan

2026-06-05 12:17:10 +02:00

11 KiB

Raw Blame History

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	created	updated	state_hub_workstream_id
RAILIANCE-WP-0006	workplan	Extract railiance-forge and formalize forge-layer contracts	railiance	railiance-apps	active	codex	railiance	high	2026-06-04	2026-06-05	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:

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

id: RAILIANCE-WP-0006-T01
status: done
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

id: RAILIANCE-WP-0006-T02
status: done
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`

id: RAILIANCE-WP-0006-T03
status: in_progress
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.

Progress 2026-06-05: canonical registry docs moved to railiance-forge, with compatibility pointers left in railiance-apps. Deploy-capable Gitea Helm/SOPS/manifests and Makefile deploy targets still remain here pending a separate review. That review is now drafted in /home/worsch/railiance-forge/docs/deploy-capable-gitea-move-review.md.

T04 - Re-scope `railiance-apps` and `railiance-enablement`

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

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

Completed on 2026-06-05 in /home/worsch/railiance-forge/docs/initial-operating-contracts.md.

T06 - Define CI runner, Actions, and GitOps ownership

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

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

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

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

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.