coulomb/railiance-forge
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

seeded repo

Browse Source
This commit is contained in:
Bernd Worsch
2026-06-05 11:38:13 +02:00
parent 58a0ea4034
commit 68ad693b1f
7 changed files with 881 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

174
AGENTS.md Normal file
View File

@@ -0,0 +1,174 @@
# railiance-forge - Agent Instructions
## Repo Identity
**Purpose:** Railiance forge and artifact infrastructure - source forge runtime,
container/package registries, forge-backed runner substrate, artifact lifecycle,
and future Forgejo migration.
**Domain:** railiance
**Repo slug:** railiance-forge
**Topic ID:** `ca369340-a64e-442e-98f1-a4fa7dc74a38`
**Workplan prefix:** `FORGE-WP-`
---
## State Hub Integration
The Custodian State Hub tracks work across all domains. Interact via HTTP REST -
there is no MCP server for Codex agents.
| Context | URL |
|---------|-----|
| Local workstation | `http://127.0.0.1:8000` |
| Remote via tunnel | `http://127.0.0.1:18000` |
### Orient at session start
```bash
cat .custodian-brief.md
curl -s "http://127.0.0.1:8000/workstreams/?topic_id=ca369340-a64e-442e-98f1-a4fa7dc74a38&status=active" \
| python3 -m json.tool
curl -s "http://127.0.0.1:8000/messages/?to_agent=railiance-forge&unread_only=true" \
| python3 -m json.tool
```
Mark a message read:
```bash
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
-H "Content-Type: application/json" -d '{}'
```
### Log progress at session close
```bash
curl -s -X POST http://127.0.0.1:8000/progress/ \
-H "Content-Type: application/json" \
-d '{
"summary": "what was done",
"event_type": "note",
"author": "codex",
"workstream_id": "<uuid>",
"task_id": "<uuid>"
}'
```
Omit `workstream_id` / `task_id` when not applicable.
### Update task status
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-H "Content-Type: application/json" \
-d '{"status": "progress"}'
```
Canonical task values: `wait | todo | progress | done | cancel`.
### Flag a task for human review
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-H "Content-Type: application/json" \
-d '{"needs_human": true, "intervention_note": "reason"}'
```
---
## Session Protocol
**Start:**
1. `cat .custodian-brief.md` - domain goal and open workstreams.
2. Check inbox:
`GET /messages/?to_agent=railiance-forge&unread_only=true`; mark read.
3. Scan workplans: `ls workplans/` and note `ready`, `active`, or `blocked`
workplans and open tasks.
4. Check blocked tasks: `GET /tasks/?needs_human=true`.
**During work:**
- Update task statuses in workplan files as tasks progress.
- Record significant decisions via `POST /decisions/`.
- Keep forge responsibilities separate from S4 templates and S5 app releases.
**Close:**
1. Update workplan file task statuses.
2. Log progress with `POST /progress/`.
3. After workplan file changes, run from `~/state-hub`:
```bash
make fix-consistency REPO=railiance-forge
```
---
## Workplan Convention
Work items originate as files in this repo. State Hub indexes those files as
workstreams and task blocks.
**File location:** `workplans/FORGE-WP-NNNN-<slug>.md`
**Archived location:** `workplans/archived/YYMMDD-FORGE-WP-NNNN-<slug>.md`
**Frontmatter:**
```yaml
---
id: FORGE-WP-NNNN
type: workplan
title: "..."
domain: railiance
repo: railiance-forge
status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex
topic_slug: railiance
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
state_hub_workstream_id: "<uuid>" # written by fix-consistency - do not edit
---
```
**Task block format:**
````text
## Task Title
```task
id: FORGE-WP-NNNN-T01
status: todo | progress | done | wait | cancel
priority: high | medium | low
state_hub_task_id: "<uuid>" # written by fix-consistency - do not edit
```
Task description text.
````
Status progression: `todo` -> `progress` -> `done`, or `wait` / `cancel`.
To create a new workplan:
1. Write the file following the format above.
2. Run from `~/state-hub`:
```bash
make fix-consistency REPO=railiance-forge
```
---
## Repository Boundaries
This repo owns forge runtime and artifact infrastructure. It does not own:
- OS/host provisioning (`railiance-infra`);
- Kubernetes runtime primitives (`railiance-cluster`);
- shared database/storage/secret platforms (`railiance-platform`);
- generic CI/CD templates and developer portal paths (`railiance-enablement`);
- user-facing application releases (`railiance-apps`);
- source application code.

132
INTENT.md Normal file
View File

@@ -0,0 +1,132 @@
# INTENT
> This file captures **why this repository exists**,
> the **direction it is moving toward**, and
> the **kind of system it is meant to become**.
> It is intentionally **aspirational and stable**, not a description of current implementation.
---
## One-liner
**The forge layer - turning source hosting, registries, and automation runners into dependable Railiance release infrastructure.**
---
## Why This Exists
Applications need more than a runtime to ship safely. They need a governed
place for source hosting, package and image publication, CI runner substrate,
release artifact retention, and operational evidence.
Before this repo, forge concerns were spread across S4 enablement and S5
application deployment work. That made it hard to tell who owned Gitea,
Forgejo, package registries, Actions runners, registry storage, and artifact
promotion evidence.
This layer exists to make those responsibilities explicit and operable.
---
## The Mission
> *Where we are going.*
To become the **canonical home for Railiance forge and artifact infrastructure**
- current Gitea operation, future Forgejo migration, container and package
registries, forge-backed automation runner substrate, artifact lifecycle, and
forge operational evidence.
This means:
* Source forge runtime is operated through a clear repo-owned contract
* Package and image registries have retention, restore, and capacity posture
* CI runners are owned separately from reusable CI/CD templates
* S5 applications can consume artifacts without owning forge internals
* Future Forgejo cutover can happen without confusing it with app deployment
---
## Core Principles
### 1. Forge Runtime, Not Application Releases
Own the forge and artifact infrastructure. Do not own user-facing application
release charts or application source code.
### 2. Artifacts With Evidence
Images, packages, and release assets should carry enough provenance and
inspection evidence for downstream releases to trust them.
### 3. Runner Substrate, Not Every Workflow
Own the runner infrastructure and credentials. Reusable workflow templates
belong in S4 enablement, and app-specific workflows belong near the app or its
release repo.
### 4. Stable Handoffs
Consumers should depend on stable forge capabilities: source hosting, Git SSH,
container registry, package registry, workflow execution, and artifact
promotion evidence.
### 5. Restore Before Trust
Forge data is operationally critical. Source repos, packages, registry blobs,
and runner state need explicit backup and restore posture.
### 6. Current Gitea, Future Forgejo
Gitea is the current workload; Forgejo is the intended production direction.
The repo should support both the current operating state and clean future
cutover planning.
---
## What This Is (Conceptually)
This layer is:
* a **source forge operations** layer
* an **artifact registry** layer
* an **automation runner substrate** layer
* a **release evidence** provider
* a bridge between S4 delivery paths and S5 application releases
---
## What This Is Not
This layer is not:
* the infrastructure substrate beneath Railiance
* the Kubernetes runtime
* the shared platform-services layer
* the generic CI/CD template and developer portal layer
* the application release and runbook layer
* the source-code home for business applications
* a runtime secret custody authority
It is the forge and artifact infrastructure that lets the rest of Railiance
build, publish, automate, and consume releases.
---
## Direction of Evolution
This layer is expected to evolve toward:
* Clean extraction of current Gitea operation from `railiance-apps`
* Explicit Forgejo migration and production cutover planning
* Versioned artifact lifecycle and retention policy
* Runner placement, label, credential, and secret-access policy
* Backup and restore evidence for source, package, and registry data
* Fabric declarations for forge capabilities and dependencies
* Self-evidencing forge health and readiness checks
---
## Guiding Question
> **How can Railiance make source hosting, artifact publication, and automation execution dependable enough that application releases can consume them without owning them?**

18
README.md
View File

@@ -1,3 +1,17 @@
# repo-seed
# railiance-forge
A git repository template to bootstrap coulomb projects from.
Railiance forge and artifact infrastructure.
This repository is being founded to separate source forge, registry, and
automation runner responsibilities from `railiance-apps` and
`railiance-enablement`.
Start with:
1. `INTENT.md`
2. `SCOPE.md`
3. `AGENTS.md`
4. `workplans/`
Current implementation status: founding. No live Gitea files have been migrated
from `railiance-apps` yet.

196
SCOPE.md Normal file
View File

@@ -0,0 +1,196 @@
# SCOPE
This file defines what `railiance-forge` owns, when to use it, and where its
boundaries stop.
Last reviewed: 2026-06-05
---
## One-liner
Forge and artifact infrastructure for Railiance: current Gitea operation,
future Forgejo migration, container and package registries, Actions runner
substrate, artifact lifecycle, and forge operational evidence.
---
## Core Idea
`railiance-forge` separates forge responsibilities from S4 developer
enablement and S5 application releases.
The practical contract is:
1. lower layers provide servers, Kubernetes runtime, databases, storage, and
secret custody;
2. this repo owns the source forge runtime and artifact publication surface;
3. `railiance-enablement` owns reusable CI/CD templates and developer paved
paths;
4. `railiance-apps` consumes forge artifacts and deploys user-facing workloads.
No live Gitea files have been migrated here yet. This repo is being founded as
the future home for that operational surface.
---
## In Scope
- Current Gitea operation and future Forgejo migration/cutover planning.
- Source forge deployment configuration and runbooks.
- Container registry and package registry enablement.
- Registry storage posture, cleanup, retention, and restore readiness.
- Forge-backed Actions runner substrate:
- runner deployment ownership;
- runner labels and placement;
- runner credential and secret-access boundaries.
- Artifact publication evidence used by downstream release workflows:
- image tags;
- package versions;
- commit SHA provenance;
- promotion and smoke evidence.
- Forge observability and operator checks:
- web endpoint health;
- Git SSH health;
- registry/package endpoint health;
- runner health;
- storage growth inspection.
- Fabric declarations for forge capabilities, interfaces, and dependencies.
- Repo-local workplan files under `workplans/`.
---
## Out of Scope
- OS provisioning and host hardening: `railiance-infra`.
- Kubernetes runtime primitives, ingress controllers, and cluster addon
installation: `railiance-cluster`.
- Shared databases, object storage, caches, and runtime secret custody:
`railiance-platform`.
- Generic CI/CD templates, SDKs, buildpacks, and developer portal surfaces:
`railiance-enablement`.
- User-facing application release charts, app runbooks, migrations, and smoke
tests: `railiance-apps`.
- Application source code, package metadata, and image build definitions in
source repos.
- Secret value custody. This repo may reference secret names and approved
delivery paths, but it must not commit decrypted secret material.
---
## Relevant When
- Operating or upgrading Gitea as the current Railiance forge.
- Planning or executing a Forgejo migration or cutover.
- Enabling or debugging container/package registry behavior.
- Defining artifact retention, cleanup, provenance, or restore posture.
- Deploying or operating forge-backed Actions runners.
- Deciding whether a workflow issue is runner substrate, reusable template, or
app-specific release logic.
- Declaring forge capabilities in Railiance Fabric.
---
## Not Relevant When
- The work is an application release chart or app-specific runbook.
- The work is a generic workload template or SDK.
- The work is platform database provisioning or object-storage operation.
- The work is Kubernetes runtime installation or ingress controller ownership.
- The work is application source-code behavior.
- The work requires live secret values outside approved custody paths.
---
## Current State
- Status: founding.
- Implementation: repository contract and first workplan are being created.
- Stability: emerging.
- Usage: intended as the new home for forge responsibilities currently
visible in `railiance-apps`.
Known starting point:
- `railiance-apps` currently owns Gitea Helm values, registry overlays, ingress,
Gitea Makefile targets, and registry docs.
- `railiance-enablement` owns the intent for delivery templates and developer
paved paths, but not forge runtime operation.
- `railiance-forge` should absorb forge runtime and artifact infrastructure
without moving S5 app release ownership.
---
## How It Fits
- Upstream dependencies:
`railiance-infra`, `railiance-cluster`, and `railiance-platform`.
- Adjacent collaborators:
`railiance-enablement` for reusable CI/CD paths and `railiance-apps` for
consuming release artifacts in app deployments.
- Downstream consumers:
source repos, app release repos, operators, and Railiance users relying on
source hosting and published artifacts.
---
## Terminology
- Preferred terms:
forge, source forge, artifact registry, package registry, runner substrate,
release evidence.
- Also known as:
Gitea/Forgejo operations, release infrastructure.
- Potentially confusing terms:
"workflow template" belongs in S4 enablement; "runner substrate" belongs
here; "app release workflow" belongs near the app or S5 release surface.
---
## Related / Overlapping Repositories
- `railiance-apps` - currently hosts Gitea deployment files and registry docs;
should become a consumer after extraction.
- `railiance-enablement` - owns reusable CI/CD templates, SDKs, buildpacks, and
developer portal paths.
- `railiance-platform` - provides database, storage, backup, and runtime secret
services consumed by forge workloads.
- `railiance-cluster` - provides Kubernetes runtime and cluster-level addons.
- `railiance-fabric` - should model forge capabilities, interfaces, providers,
and consumers.
---
## Getting Oriented
1. Read `AGENTS.md` for session protocol and State Hub conventions.
2. Read `INTENT.md` for stable purpose.
3. Read this file for scope and boundaries.
4. Read active files in `workplans/`.
5. For migration context, read
`/home/worsch/railiance-apps/workplans/RAILIANCE-WP-0006-railiance-forge-extraction.md`.
---
## Provided Capabilities
```capability
type: infrastructure
title: Railiance source forge operation
description: Operate the current Gitea source forge and plan future Forgejo migration/cutover as dedicated Railiance forge infrastructure.
keywords: [railiance, forge, gitea, forgejo, source-hosting, git]
```
```capability
type: infrastructure
title: Railiance artifact registry operation
description: Own container and package registry enablement, retention, restore posture, and release artifact evidence for Railiance consumers.
keywords: [registry, container-image, python-package, artifact, retention, provenance]
```
```capability
type: operations
title: Forge automation runner substrate
description: Define and operate forge-backed runner infrastructure, runner labels, runner placement, and credential boundaries used by CI/CD workflows.
keywords: [actions, runner, ci, gitops, automation, credentials]
```

102
docs/current-forge-asset-inventory.md Normal file
View File

@@ -0,0 +1,102 @@
# Current Forge Asset Inventory
Date: 2026-06-05
This inventory covers forge-related assets currently visible in
`/home/worsch/railiance-apps`. It supports `FORGE-WP-0001-T03` and the
coordinating `RAILIANCE-WP-0006` extraction plan.
No files have been moved yet. This document assigns each candidate asset a
target disposition for the first migration plan.
## Summary
| Disposition | Meaning |
|-------------|---------|
| Move | Canonical file should move to `railiance-forge`. |
| Copy pointer | Copy canonical content to `railiance-forge`, leave a short pointer in `railiance-apps` temporarily. |
| Leave | Keep in `railiance-apps`; it is S5 app-release surface. |
| Adapt | Keep local behavior, but update references after forge extraction. |
| Supersede | Historical or transitional content should be replaced by new forge-owned docs/workplans. |
## Move To `railiance-forge`
| Asset | Current role | Target disposition | Notes |
|-------|--------------|--------------------|-------|
| `helm/gitea-values.sops.yaml` | SOPS-encrypted Gitea Helm values. | Move | Must preserve secret boundary; move without decrypting. |
| `helm/gitea-registry-values.yaml` | Non-secret overlay enabling Gitea package/container registry behavior. | Move | This is forge runtime config, not S5 app config. |
| `manifests/gitea-ingress.yaml` | Registry-facing Gitea ingress for `/v2`. | Move | Forge owns Gitea/registry exposure; cluster ingress primitives remain S2. |
| `releases/gitea/values.yaml` | Legacy/plain Gitea release values reference. | Move or supersede | Likely keep only as historical migration reference if still useful. |
| `Makefile` variables `GITEA_*` | Gitea release/chart/value/ingress defaults. | Move | Recreate in `railiance-forge/Makefile`; remove from S5 after compatibility window. |
| `make gitea-deploy` | Deploy/upgrade current Gitea release. | Move | Should become `railiance-forge` operator target. |
| `make gitea-ingress-deploy` | Apply Gitea registry ingress. | Move | Should become `railiance-forge` operator target. |
| `make gitea-status` | Check Gitea pod/service/ingress and `gitea-db` status. | Move | Keep database status as consumer evidence; S3 still owns DB implementation. |
## Copy With Compatibility Pointer
| Asset | Current role | Target disposition | Notes |
|-------|--------------|--------------------|-------|
| `docs/gitea-container-registry.md` | Canonical operator recipe for container registry host, auth, pull secrets, storage note. | Copy pointer | Copy to `railiance-forge/docs/`; leave S5 pointer for app consumers. |
| `docs/gitea-package-registry.md` | Python package registry publishing/install recipe and `issue-core` handoff. | Copy pointer | Forge owns endpoint/registry posture; app/source repos own package release details. |
| `workplans/RAIL-AP-WP-0001-gitea-container-registry.md` | Historical implementation evidence for enabling Gitea registry in S5. | Copy pointer or archive | Keep historical record in S5, but create forge follow-up for storage/retention/restore posture. |
| `workplans/RAILIANCE-WP-0006-railiance-forge-extraction.md` | Cross-repo coordination plan. | Leave plus pointer | Remains in `railiance-apps` as extraction coordinator; forge work proceeds in `FORGE-WP-*`. |
## Leave In `railiance-apps`
| Asset | Current role | Target disposition | Notes |
|-------|--------------|--------------------|-------|
| `.gitea/workflows/manifest-server-dry-run.yaml` | S5 manifest dry-run workflow for app charts/manifests. | Leave | Runner substrate belongs in forge; this app-release check remains S5. |
| `make k8s-server-dry-run` | Server-side dry-run for S5 charts/manifests. | Leave | Document runner/cluster prerequisites in forge, but keep app release check here. |
| `tools/k8s-server-dry-run.sh` | Implements S5 dry-run. | Leave | Consumes runner/cluster access; does not operate forge runtime. |
| `charts/vergabe-teilnahme/**` | S5 app chart. | Leave | Application release ownership. |
| `helm/vergabe-teilnahme-values.yaml` | S5 app values, including registry image reference. | Leave | Consumes forge registry; does not own registry. |
| `manifests/vergabe-teilnahme-ingress.yaml` | S5 app ingress. | Leave | Application endpoint ownership. |
| `docs/vergabe-teilnahme.md` | S5 app runbook. | Leave | Update links to point at forge-owned registry docs after migration. |
| `docs/django-on-railiance.md` | Framework-specific S5 app recipe. | Leave | Should reference forge registry capabilities as upstream infrastructure. |
| `docs/operator-recipes.md` | S5 operator recipes. | Leave | Keep only app-release recipes here. |
| `docs/operator-setup.md` | S5 operator setup. | Leave | May need forge cross-link for registry credentials and runner expectations. |
| `tools/build-database-url-secret.sh` | App DB secret helper. | Leave | S5 app data/secret consumer behavior. |
| `tools/smoke-service.sh` | App smoke helper. | Leave | S5 verification. |
| `make apps-pg-status` | Checks shared app database cluster. | Leave or move to platform later | Not forge; keep while S5 needs consumer readiness evidence. |
| `make vergabe-*` targets | App release operations. | Leave | S5 app surface. |
## Adapt In Place
| Asset | Current role | Target disposition | Notes |
|-------|--------------|--------------------|-------|
| `SCOPE.md` | Currently lists Gitea as S5-owned workload. | Adapt | After migration, describe forge as upstream release infrastructure. |
| `INTENT.md` | Mentions Gitea/current forge as S5 workload/learning surface. | Adapt | Keep S5 intent but remove long-term forge ownership language. |
| `AGENTS.md` | Repo identity still says application Helm releases, Gitea, coulomb services. | Adapt | Update after Gitea files move. Also update task status examples to State Hub canon. |
| `Makefile` `SOPS_SENTINEL ?= $(GITEA_VALUES)` | `check-sops` currently validates Gitea SOPS values. | Adapt | Once Gitea values move, choose an S5 sentinel or make the check no-op when no SOPS file exists. |
| `tools/check-sops.sh` | Generic SOPS sentinel check. | Leave/adapt | Useful beyond forge, but current default must change after move. |
| `.custodian-brief.md` | Generated State Hub brief. | Generated | Do not edit manually; consistency sync updates it. |
## Supersede Or Re-home Planning Content
| Asset | Current role | Target disposition | Notes |
|-------|--------------|--------------------|-------|
| `RAILIANCE-WP-0005-T04` | App data backup/restore handoffs includes Gitea package blobs. | Split | App DB handoff stays S5; Gitea package blob durability moves to forge. |
| `RAILIANCE-WP-0005-T06` | Gitea package registry storage and retention posture. | Re-home | Should become forge-owned follow-up, likely under `FORGE-WP-*`. |
| `railiance-apps-WP-0004` I03 | PyPI issue-core blocker references Gitea package registry. | Adapt | Source/package publication remains source repo; forge owns registry endpoint and credentials posture. |
| `railiance-apps-WP-0002` registry references | Historical app deployment evidence. | Leave/adapt | Keep as app deployment history; cross-link to forge docs for current registry operation. |
## First Safe Move Candidate
The first migration should avoid live service changes and move documentation
before deployment configuration:
1. Copy `docs/gitea-container-registry.md` and
`docs/gitea-package-registry.md` into `railiance-forge/docs/`.
2. Replace the originals in `railiance-apps` with short compatibility pointers.
3. Add a `railiance-forge/Makefile` with read-only/status targets first.
4. Move deploy-capable Gitea targets only after the operator path is reviewed.
This gives operators a new canonical forge home while keeping current S5 app
runbooks discoverable.
## Remote Creation Note
Creating `coulomb/railiance-forge` on the current Gitea instance is blocked:
the configured `tea` login `coulomb` exists, but the stored token is invalid as
of 2026-06-05. The local repo is initialized and State Hub-registered, but
`origin` should not be added until the remote repository exists.

130
docs/first-migration-plan.md Normal file
View File

@@ -0,0 +1,130 @@
# First Migration Plan
Date: 2026-06-05
This plan starts the extraction of forge ownership from `railiance-apps` into
`railiance-forge` without changing the live Gitea deployment.
The rule for the first migration is simple: move knowledge and read-only
operator entry points before moving deploy-capable configuration.
## Goals
- Make `railiance-forge` the canonical place to look for forge and registry
operation.
- Keep `railiance-apps` usable for current S5 app operators during transition.
- Preserve all secret boundaries; do not decrypt or copy live secret values.
- Avoid any Helm release or Kubernetes apply during the first migration.
- Keep future Forgejo cutover separate from current Gitea ownership transfer.
## Non-Goals
- No live Gitea upgrade.
- No Forgejo deployment or cutover.
- No registry retention cleanup.
- No Actions runner deployment.
- No app release changes.
- No SOPS decryption.
## Phase 1 - Documentation Canonicalization
Move registry operation knowledge first.
Steps:
1. Copy `railiance-apps/docs/gitea-container-registry.md` to
`railiance-forge/docs/gitea-container-registry.md`.
2. Copy `railiance-apps/docs/gitea-package-registry.md` to
`railiance-forge/docs/gitea-package-registry.md`.
3. Replace the originals in `railiance-apps` with short compatibility pointers
to the new canonical files.
4. Update `railiance-apps/docs/vergabe-teilnahme.md` and other app docs to
refer to forge-owned registry docs.
Validation:
- `git diff --check` in both repos.
- No commands require Gitea credentials.
- No live cluster changes.
## Phase 2 - Read-Only Operator Targets
Add forge-side operator entry points that inspect current state before owning
deployment.
Initial `railiance-forge/Makefile` targets:
- `gitea-status`: current Gitea pod, service, ingress, and `gitea-db` consumer
status, copied/adapted from `railiance-apps`.
- `registry-docs`: print canonical docs to inspect.
- `check-tools`: minimal local tool check for `kubectl`, `helm`, `sops`, and
optional `tea`.
Do not add `gitea-deploy` in this phase.
Validation:
- Targets are read-only.
- Targets either succeed or fail with clear missing-tool messages.
- `railiance-apps` still owns deploy-capable Gitea targets during the
transition.
## Phase 3 - Deploy-Capable Target Review
Move deploy-capable Gitea ownership only after Phase 1 and Phase 2 are reviewed.
Candidate moves:
- `helm/gitea-values.sops.yaml`;
- `helm/gitea-registry-values.yaml`;
- `manifests/gitea-ingress.yaml`;
- `make gitea-deploy`;
- `make gitea-ingress-deploy`.
Review gates:
- `railiance-forge` remote exists and is pushed.
- State Hub workplans are synced in both repos.
- Operator confirms the Gitea token/remote creation issue is fixed.
- `railiance-apps` has compatibility pointers for old paths.
- The plan distinguishes current Gitea operation from future Forgejo cutover.
Validation:
- `helm template` or dry-run equivalent can render from the new path without
decrypting secrets into Git.
- No decrypted SOPS material appears in diffs.
- Existing live service stays untouched until an explicit deploy command is run.
## Phase 4 - S5 Scope Cleanup
After deploy-capable assets move, update `railiance-apps`:
- remove long-term Gitea ownership language from `SCOPE.md`;
- keep app release and app runbook ownership;
- keep app registry consumption references;
- update `RAILIANCE-WP-0005` to split Gitea package storage posture into
forge-owned work;
- keep app database and app backup handoffs in S5/platform coordination.
Validation:
- `railiance-apps` no longer claims forge runtime ownership.
- App operators can still find registry instructions through pointers.
## Open Blocker
The local `tea` login named `coulomb` is configured but currently fails with
`invalid username, password or token`. This blocks creation of the remote
`coulomb/railiance-forge` repository through the Gitea API.
Until refreshed credentials are available:
- keep `railiance-forge` local and State Hub-registered;
- do not add an `origin` remote that points to a missing repository;
- avoid claiming remote publication is complete.
## Next Recommended Action
Proceed with Phase 1 documentation canonicalization after the operator confirms
that compatibility pointers in `railiance-apps` are acceptable.

131
workplans/FORGE-WP-0001-repository-foundation.md Normal file
View File

@@ -0,0 +1,131 @@
---
id: FORGE-WP-0001
type: workplan
title: "railiance-forge repository foundation"
domain: railiance
repo: railiance-forge
status: active
owner: codex
topic_slug: railiance
planning_priority: high
created: "2026-06-05"
updated: "2026-06-05"
state_hub_workstream_id: "4280f3d2-3d4c-4caf-946b-521fb8fb1494"
---
# railiance-forge repository foundation
## Context
`railiance-forge` is being created after the Railiance intent review identified
forge responsibilities as the main cross-layer smell. The current Gitea and
registry surface is still in `railiance-apps`; this workplan establishes the new
repo as the owner for forge runtime and artifact infrastructure before any live
deployment files move.
This workplan implements the opening tasks from
`railiance-apps/workplans/RAILIANCE-WP-0006-railiance-forge-extraction.md`.
## T01 - Define repository contract
```task
id: FORGE-WP-0001-T01
status: done
priority: high
state_hub_task_id: "8ebc1457-f681-4cad-9ca9-119246b0063c"
```
Create the initial repository contract:
- `INTENT.md`;
- `SCOPE.md`;
- `AGENTS.md`;
- `README.md`;
- repo-local workplan convention.
Done when the repo purpose, boundaries, State Hub integration, and workplan
prefix are explicit.
---
## T02 - Register with State Hub
```task
id: FORGE-WP-0001-T02
status: done
priority: high
state_hub_task_id: "cb2346cf-b4e5-47ad-a587-65d6e95e89c8"
```
Register the repo with State Hub and sync the first workplan.
Steps:
- register `railiance-forge` under domain `railiance`;
- register the local host path `/home/worsch/railiance-forge`;
- run `make fix-consistency REPO=railiance-forge`;
- verify State Hub created a workstream and task rows.
Done when State Hub can index this repo independently.
---
## T03 - Inventory current forge assets in `railiance-apps`
```task
id: FORGE-WP-0001-T03
status: done
priority: high
state_hub_task_id: "6957ebd3-321c-41e5-ad28-8d30b0bc1155"
```
Inventory all current Gitea, registry, package, and runner-related files and
operator commands in `railiance-apps`.
Done when each candidate file has a target disposition: move, copy with
compatibility pointer, leave in S5, or supersede.
---
## T04 - Draft first migration plan
```task
id: FORGE-WP-0001-T04
status: done
priority: high
state_hub_task_id: "6894dfb4-5641-45c1-8259-201801e6aede"
```
Draft the first migration plan for moving forge runtime ownership without
touching live service state.
The plan must preserve:
- secret boundaries;
- current Gitea deployment stability;
- operator discoverability during transition;
- future Forgejo cutover separation.
Done when `railiance-apps` and `railiance-forge` can agree on the first safe
file move.
---
## T05 - Define initial forge operating contracts
```task
id: FORGE-WP-0001-T05
status: todo
priority: medium
state_hub_task_id: "a5924b97-ccf7-4da0-acea-4f6017fef278"
```
Create first draft contracts for:
- artifact retention and provenance;
- runner substrate ownership;
- backup and restore handoff with `railiance-platform`;
- secret custody boundaries;
- basic forge observability.
Done when follow-on implementation work can be split into focused workplans.