feat(workplan): add WP-0003 for 5-repo OAS stack restructure
Plans the rename of railiance-hosts→infra and railiance-bootstrap→cluster, creation of railiance-platform/enablement/apps, ADR-003 (supersedes ADR-002), content relocations, state hub re-registration, and resolution of the pending railiance-apps decision (7cddead6). 7 tasks; state_hub_workstream_id: 3ae0afc5-13f2-4e6c-aea7-1c1fb9f1ab81 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
268
workplans/RAIL-HO-WP-0003-5repo-stack-restructure.md
Normal file
268
workplans/RAIL-HO-WP-0003-5repo-stack-restructure.md
Normal file
@@ -0,0 +1,268 @@
|
||||
---
|
||||
id: RAIL-HO-WP-0003
|
||||
type: workplan
|
||||
title: "Railiance 5-Repo Stack Restructure"
|
||||
domain: railiance
|
||||
repo: railiance-hosts
|
||||
status: active
|
||||
owner: railiance
|
||||
topic_slug: railiance
|
||||
state_hub_workstream_id: "3ae0afc5-13f2-4e6c-aea7-1c1fb9f1ab81"
|
||||
created: "2026-03-09"
|
||||
updated: "2026-03-09"
|
||||
---
|
||||
|
||||
# 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: todo
|
||||
priority: high
|
||||
state_hub_task_id: "4ff2c35f-7cf8-46a3-a5e3-366bb0e193c7"
|
||||
```
|
||||
|
||||
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: todo
|
||||
priority: high
|
||||
state_hub_task_id: "5b29d8f8-ab9b-4d8c-a2a0-87918eac5cc4"
|
||||
```
|
||||
|
||||
**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: todo
|
||||
priority: high
|
||||
state_hub_task_id: "caf3c22e-3d83-46a3-9bd8-23a5d9021f72"
|
||||
```
|
||||
|
||||
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: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "35d3b599-8325-472c-abd0-2c4939f1f8cd"
|
||||
```
|
||||
|
||||
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: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "ba48bdca-a3e5-4efa-8bd1-55077e92a787"
|
||||
```
|
||||
|
||||
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: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "a5310b9a-665c-4341-92bf-e51db65c2388"
|
||||
```
|
||||
|
||||
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: todo
|
||||
priority: low
|
||||
state_hub_task_id: "2aaebc21-da59-456e-abdf-8cf03fd82e49"
|
||||
```
|
||||
|
||||
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`
|
||||
Reference in New Issue
Block a user