prj-forgejo-org-refactor/GOAL.md

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

# 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.

At the August 11 seed review, 112 repositories with a forge origin sat under `coulomb/`,
including `net-kingdom`, `helix-forge`, the whole `railiance-*` family, and the
`rail-*` / `rapp-*` / `reef-*` families. An organization that contains
everything draws no useful stewardship boundary. The September 28 local scan
finds 151 `coulomb` origins; neither count is a current server census.

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 in `ORGREF-WP-0001` makes that condition checkable instead of a feeling.

Reviewed September 28: the family validator runs green locally; fresh deployable
coverage, a stable full reference inventory and transfer rollback proof remain
missing. T01/T02 can advance; T03 onward stays deferred. See the
[readiness review](history/2026-09-28-readiness-review.md), including the circular
dependency between the rollback prerequisite and T04.

## 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

Historical seed evidence, 2026-08-11. Reconcile current endpoints and runtime
version before using it: forge owner docs still distinguish Gitea operation from
a future Forgejo migration. The org split does not include that product migration.

| 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** — changed or unavailable package paths can break a later node reschedule or restart; actual package transfer/redirect behavior remains unverified |
| 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.
      Include package consumers, GitOps access policies, release/retention
      inputs and rollback references; reconcile server repos with local clones.
- [ ] **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 reports no unexplained
      operational references to moved paths (approved `coulomb` assignments and
      immutable historical evidence are accounted for), 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`.