prj-forgejo-org-refactor/GOAL.md

repo	repo_flavor	project_status	started	reviewed
prj-forgejo-org-refactor	project	draft	2026-08-11	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, 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.