prj-forgejo-org-refactor/GOAL.md

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