---
repo: prj-forgejo-org-refactor
repo_flavor: project
project_status: draft
started: "2026-08-11"
reviewed: "2026-08-11"
---

# Project goal

## Outcome

Split the single `coulomb/` Forgejo organization into stewardship organizations
— `railiance`, `netkingdom`, `helixforge`, `binky`, `experimental`, with
`coulomb` retained for what genuinely belongs to it — so that organization
membership expresses **discoverability and responsibility** instead of
expressing nothing.

Today all 112 repositories with a Forgejo origin sit under `coulomb/`,
including `net-kingdom`, `helix-forge`, the whole `railiance-*` family, and the
`rail-*` / `rapp-*` / `reef-*` families. An organization that contains
everything draws no boundary and grants no useful access control.

The migration must complete **without breaking a running system**. That is the
hard part, and it is why this is a project rather than a workplan.

## Why this is deferred

Operator decision, 2026-08-11: seed now, execute later. The migration is only
safe once the surrounding structure is stable enough that side-effect
complications can be *tested for* rather than discovered in production. The
entry gate below makes that condition checkable instead of a feeling.

## Invariants

1. **No silent breakage.** Every reference that moves is inventoried before it
   moves, and verified after.
2. **Organization membership is a stewardship grouping**, not a legal-entity
   grouping and not a deployment grouping. Legal attribution stays with
   `LICENSE`, copyright headers, and contribution records
   (`contribution-convention_v0.1`), which survive repo moves. Deployment
   grouping stays with rapp contexts, which are a separate dimension by
   ratified decision (`d07ee5f9-90d6-4e04-85d7-772103bc95f0`, OAS P1).
3. **Reversible in stages.** No stage may leave the fleet in a state that
   cannot be rolled back to the previous stage.
4. **The running cluster keeps running.** GitOps sync and image pulls must not
   depend on a rename landing everywhere simultaneously.
5. **This repo hosts no production implementation.** It coordinates; the
   changes land in the repos that own them.

## Known blast radius

Verified 2026-08-11. This is the evidence that made the effort project-sized.

| Surface | Finding | Why it hurts |
| --- | --- | --- |
| Git remotes | 112 repos with `coulomb/` origin | Every local clone, every CI checkout |
| ArgoCD sources | `repoURL: https://forgejo.coulomb.social/coulomb/<repo>.git` in Application manifests | GitOps stops syncing if the path 404s |
| **Container registry** | `repository: forgejo.coulomb.social/coulomb/core-hub` in chart values | Forgejo's package registry is **org-scoped** — a rename moves image paths for **already-running pods**, so a node reschedule or restart can fail to pull long after the rename "succeeded" |
| Chart metadata | `home:` / `sources:` URLs in `Chart.yaml` | Cosmetic but fleet-wide |
| Submodules / CI configs | not yet inventoried | Unknown until the inventory task runs |
| Hostname | `forgejo.coulomb.social` is itself coulomb-branded | Open question: does the host stay while orgs split? |

The container-registry finding is the one that makes a naive "rename and fix
the remotes" approach unsafe. It is a *deferred* failure — it does not show up
at rename time, it shows up at the next pod reschedule.

## Success gates

- [ ] **G1 — Complete inventory.** Every `coulomb/` reference across git
      remotes, ArgoCD sources, chart image paths, chart metadata, submodules,
      and CI configs is enumerated by a re-runnable command, not by hand.
- [ ] **G2 — Org taxonomy agreed.** Each repo has an assigned target org with a
      stated reason, and the criteria for assignment are written down so later
      repos can be placed without re-litigating.
- [ ] **G3 — Redirect behavior verified.** Forgejo's actual behavior on org
      rename / repo transfer — for Git paths *and* for the package registry —
      is established by test against a throwaway org, not assumed from docs.
- [ ] **G4 — Rollback proven.** A repo can be moved and moved back with GitOps
      and image pulls recovering, demonstrated on a low-stakes repo first.
- [ ] **G5 — Migration executed.** All repos sit in their target org.
- [ ] **G6 — No stale references.** The G1 inventory command returns clean, and
      the cluster has survived a deliberate pod reschedule on migrated images.
- [ ] **G7 — Convention documented in a permanent home.** The org-assignment
      criteria are promoted out of this project repo, so future repos are
      created in the right org by default rather than by memory.

## Project retirement

This repository may be archived when:

1. every success gate has accepted evidence;
2. residuals have live work records in permanent repos;
3. the org-assignment convention is promoted to a durable home (canon or
   `railiance-master`), per G7;
4. workplans are finished or cancelled with rationale;
5. a completion record exists under `history/`;
6. `project_status` is set to `completed`, then `archived`.