From d9f6848a5b5d3bc2140c0e69c04b163a519cc49b Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 9 Mar 2026 23:53:49 +0100 Subject: [PATCH] feat(workplan): add WP-0003 for 5-repo OAS stack restructure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- ...RAIL-HO-WP-0003-5repo-stack-restructure.md | 268 ++++++++++++++++++ 1 file changed, 268 insertions(+) create mode 100644 workplans/RAIL-HO-WP-0003-5repo-stack-restructure.md diff --git a/workplans/RAIL-HO-WP-0003-5repo-stack-restructure.md b/workplans/RAIL-HO-WP-0003-5repo-stack-restructure.md new file mode 100644 index 0000000..edc967b --- /dev/null +++ b/workplans/RAIL-HO-WP-0003-5repo-stack-restructure.md @@ -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`