277 lines
7.9 KiB
Markdown
277 lines
7.9 KiB
Markdown
---
|
||
id: RAIL-HO-WP-0003
|
||
type: workplan
|
||
title: "Railiance 5-Repo Stack Restructure"
|
||
domain: railiance
|
||
repo: railiance-infra
|
||
status: completed
|
||
owner: railiance
|
||
topic_slug: railiance
|
||
state_hub_workstream_id: "3ae0afc5-13f2-4e6c-aea7-1c1fb9f1ab81"
|
||
created: "2026-03-09"
|
||
updated: "2026-03-10"
|
||
completed: "2026-03-10"
|
||
---
|
||
|
||
# Railiance 5-Repo Stack Restructure
|
||
|
||
## Goal
|
||
|
||
Restructure the railiance tooling to align one-to-one with the OAS Stack
|
||
dimensions (S1–S5). Each repo owns exactly one stack layer.
|
||
|
||
| OAS Level | Repo | Stack Responsibility |
|
||
|-----------|------|---------------------|
|
||
| S1 Infrastructure Substrate | `railiance-infra` | OS, Ansible roles, Goss spec, Terraform, inventory |
|
||
| S2 Cluster Runtime | `railiance-cluster` | k3s, Helm, ingress, CNI, operators |
|
||
| S3 Platform Services | `railiance-platform` | PostgreSQL HA, object storage, secret mgmt, identity |
|
||
| S4 Developer Enablement | `railiance-enablement` | CI/CD, developer portal, platform templates |
|
||
| S5 Workloads & Experience | `railiance-apps` | App Helm releases, Gitea, coulomb services |
|
||
|
||
## Motivation
|
||
|
||
The original names (`railiance-hosts`, `railiance-bootstrap`) do not signal
|
||
their stack layer. The new names make the architecture self-documenting and
|
||
enforce the OAS P1 principle (Separation of Dimensions).
|
||
|
||
## Boundary rule (new)
|
||
|
||
> **Every file and playbook belongs in exactly one repo, determined by the
|
||
> OAS Stack level of the concern it addresses.**
|
||
|
||
ADR-003 (written in T01) supersedes ADR-002.
|
||
|
||
## Content relocations from railiance-cluster
|
||
|
||
The following items currently in railiance-bootstrap (→ railiance-cluster)
|
||
belong at other layers and must move:
|
||
|
||
| Item | Current location | Destination | Layer |
|
||
|------|-----------------|-------------|-------|
|
||
| `cloudinit/user-data.yaml` | railiance-cluster | railiance-infra | S1 |
|
||
| `tools/cmd/railiance-plan-host` | railiance-cluster | railiance-infra | S1 |
|
||
| `tools/cmd/railiance-backup` | railiance-cluster | railiance-platform | S3 |
|
||
|
||
Everything else in railiance-cluster (k3s playbook, Helm, smoke tests,
|
||
preflight, doctor, seed_node) is correctly placed at S2.
|
||
|
||
---
|
||
|
||
## Tasks
|
||
|
||
### T01 — Write ADR-003: Railiance 5-Repo Stack Architecture
|
||
|
||
```task
|
||
id: T01
|
||
status: done
|
||
priority: high
|
||
state_hub_task_id: "4ff2c35f-7cf8-46a3-a5e3-366bb0e193c7"
|
||
completed: "2026-03-10"
|
||
```
|
||
|
||
Create `docs/adr/ADR-003-railiance-5repo-stack-architecture.md` in
|
||
railiance-infra (formerly railiance-hosts) covering:
|
||
|
||
- The five-repo layout and OAS S1–S5 mapping
|
||
- Naming rationale (`railiance-{infra,cluster,platform,enablement,apps}`)
|
||
- Boundary rule: one repo per stack layer
|
||
- Content relocation table (items moving from railiance-cluster)
|
||
- Migration note: supersedes ADR-002
|
||
- Invalidation note in ADR-002 header pointing to ADR-003
|
||
|
||
**Done when:** ADR-003 written; ADR-002 updated with superseded status and
|
||
forward reference.
|
||
|
||
---
|
||
|
||
### T02 — Rename railiance-hosts → railiance-infra
|
||
|
||
```task
|
||
id: T02
|
||
status: done
|
||
priority: high
|
||
state_hub_task_id: "5b29d8f8-ab9b-4d8c-a2a0-87918eac5cc4"
|
||
completed: "2026-03-10"
|
||
```
|
||
|
||
**Local:**
|
||
```bash
|
||
mv ~/railiance-hosts ~/railiance-infra
|
||
cd ~/railiance-infra
|
||
# Update any self-referencing paths (CLAUDE.md, Makefile REPO var, etc.)
|
||
grep -r "railiance-hosts" . --include="*.md" --include="*.sh" --include="Makefile"
|
||
```
|
||
|
||
**Gitea remote:**
|
||
Rename the repository in Gitea UI or via API, then update the local remote:
|
||
```bash
|
||
git remote set-url origin https://gitea.example.com/coulomb/railiance-infra.git
|
||
```
|
||
|
||
**State Hub:**
|
||
```
|
||
rename_domain is not the right tool — use the API directly or update
|
||
the ManagedRepo slug via the admin API once rename_repo is available.
|
||
```
|
||
Current slug: `railiance-hosts` → new slug: `railiance-infra`
|
||
|
||
**CLAUDE.md:** Update repo name references.
|
||
|
||
**Workplan files:** Update `repo:` frontmatter field in all workplans.
|
||
|
||
**Done when:** `ls ~/railiance-infra` works; git remote points to renamed
|
||
Gitea repo; state hub slug updated.
|
||
|
||
---
|
||
|
||
### T03 — Rename railiance-bootstrap → railiance-cluster
|
||
|
||
```task
|
||
id: T03
|
||
status: done
|
||
priority: high
|
||
state_hub_task_id: "caf3c22e-3d83-46a3-9bd8-23a5d9021f72"
|
||
completed: "2026-03-10"
|
||
```
|
||
|
||
Same procedure as T02 for railiance-bootstrap → railiance-cluster:
|
||
|
||
```bash
|
||
mv ~/railiance-bootstrap ~/railiance-cluster
|
||
```
|
||
|
||
Update:
|
||
- Gitea remote
|
||
- State hub slug (`railiance-bootstrap` → `railiance-cluster`)
|
||
- CLAUDE.md repo name references
|
||
- Workplan `repo:` frontmatter fields
|
||
|
||
**Done when:** rename complete; all cross-references updated.
|
||
|
||
---
|
||
|
||
### T04 — Relocate misplaced content to correct repos
|
||
|
||
```task
|
||
id: T04
|
||
status: done
|
||
priority: medium
|
||
state_hub_task_id: "35d3b599-8325-472c-abd0-2c4939f1f8cd"
|
||
completed: "2026-03-10"
|
||
```
|
||
|
||
After T02 and T03 are complete, move items to their correct layer repos:
|
||
|
||
**→ railiance-infra (S1):**
|
||
```bash
|
||
# From railiance-cluster:
|
||
git mv cloudinit/user-data.yaml /path/to/railiance-infra/cloudinit/
|
||
git mv tools/cmd/railiance-plan-host /path/to/railiance-infra/tools/cmd/
|
||
```
|
||
|
||
**→ railiance-platform (S3):**
|
||
```bash
|
||
# From railiance-cluster (after T05 creates the repo):
|
||
git mv tools/cmd/railiance-backup /path/to/railiance-platform/tools/cmd/
|
||
```
|
||
|
||
Commit in both source and destination repos. Add a tombstone stub in the
|
||
source location pointing to the new home.
|
||
|
||
**Done when:** all three items committed in their destination repos; stubs
|
||
in place in railiance-cluster.
|
||
|
||
---
|
||
|
||
### T05 — Create and scaffold three new repos
|
||
|
||
```task
|
||
id: T05
|
||
status: done
|
||
priority: medium
|
||
state_hub_task_id: "ba48bdca-a3e5-4efa-8bd1-55077e92a787"
|
||
completed: "2026-03-10"
|
||
```
|
||
|
||
Create `railiance-platform`, `railiance-enablement`, `railiance-apps` as
|
||
git repos with minimal scaffolding:
|
||
|
||
For each repo:
|
||
1. `git init ~/railiance-{platform,enablement,apps}`
|
||
2. Create `CLAUDE.md` using the Custodian project template
|
||
3. Create `workplans/` directory with a `.gitkeep`
|
||
4. Create a `Makefile` stub with `help` target
|
||
5. Create `README.md` describing the layer's scope
|
||
6. Initial commit
|
||
|
||
**Done when:** all three repos exist locally with at least CLAUDE.md,
|
||
workplans/, and a Makefile stub.
|
||
|
||
---
|
||
|
||
### T06 — Register all five repos in the state hub
|
||
|
||
```task
|
||
id: T06
|
||
status: done
|
||
priority: medium
|
||
state_hub_task_id: "a5310b9a-665c-4341-92bf-e51db65c2388"
|
||
completed: "2026-03-10"
|
||
```
|
||
|
||
After T02, T03, T05:
|
||
|
||
```
|
||
register_repo(domain_slug="railiance", name="railiance-infra",
|
||
slug="railiance-infra", local_path="/home/worsch/railiance-infra")
|
||
|
||
register_repo(domain_slug="railiance", name="railiance-cluster",
|
||
slug="railiance-cluster", local_path="/home/worsch/railiance-cluster")
|
||
|
||
register_repo(domain_slug="railiance", name="railiance-platform",
|
||
slug="railiance-platform", local_path="/home/worsch/railiance-platform")
|
||
|
||
register_repo(domain_slug="railiance", name="railiance-enablement",
|
||
slug="railiance-enablement", local_path="/home/worsch/railiance-enablement")
|
||
|
||
register_repo(domain_slug="railiance", name="railiance-apps",
|
||
slug="railiance-apps", local_path="/home/worsch/railiance-apps")
|
||
```
|
||
|
||
The old slugs (`railiance-hosts`, `railiance-bootstrap`) can be archived
|
||
or left as stale records until a rename-repo API endpoint exists.
|
||
|
||
**Done when:** all five repos appear in `list_domain_repos("railiance")`.
|
||
|
||
---
|
||
|
||
### T07 — Resolve pending railiance-apps decision
|
||
|
||
```task
|
||
id: T07
|
||
status: done
|
||
priority: low
|
||
state_hub_task_id: "2aaebc21-da59-456e-abdf-8cf03fd82e49"
|
||
completed: "2026-03-10"
|
||
```
|
||
|
||
Decision `7cddead6` ("Create railiance-apps repo for application-layer
|
||
deployments") is now resolved by this workplan. Resolve it in the state hub:
|
||
|
||
```
|
||
resolve_decision(decision_id="7cddead6-79dd-4cca-a6d5-6512369603bb",
|
||
rationale="railiance-apps created as S5 layer of the 5-repo OAS stack.",
|
||
decided_by="Bernd Worsch")
|
||
```
|
||
|
||
**Done when:** decision marked resolved.
|
||
|
||
---
|
||
|
||
## References
|
||
|
||
- OAS Standard: `canon/standards/orthogonal-architecture_v1.0.md`
|
||
- ADR-002 (superseded): `docs/adr/ADR-002-repo-boundary-hosts-vs-bootstrap.md`
|
||
- State Hub workstream: `3ae0afc5-13f2-4e6c-aea7-1c1fb9f1ab81`
|
||
- Pending decision (railiance-apps): `7cddead6-79dd-4cca-a6d5-6512369603bb`
|