tegwick ec2a72f435 Seed the org refactor: goal, scope, blast radius, entry gate

Establishes the prj- flavor baseline (GOAL.md, SCOPE.md, AGENTS.md,
.repo-classification.yaml, genesis, foundation workplan) for splitting the
single coulomb/ Forgejo org into stewardship orgs.

Records the blast radius verified 2026-08-11: 112 repos with a coulomb/ origin,
ArgoCD repoURL sources, Chart.yaml metadata, and - the finding that made this
project-sized rather than workplan-sized - container image paths, since
Forgejo's package registry is org-scoped. That failure is deferred: it does not
appear at rename time but at the next pod reschedule.

Seeded deliberately deferred per operator decision. ORGREF-WP-0001 is backlog
and carries a four-part entry gate (validator live, deployable coverage known,
stable re-runnable inventory, demonstrated rollback) so the decision to start
is made against evidence rather than memory. T01 and T02 are read-only and safe
to advance at any time.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-11 13:39:24 +02:00

5 KiB

Raw Permalink Blame History

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

No silent breakage. Every reference that moves is inventoried before it moves, and verified after.
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).
Reversible in stages. No stage may leave the fleet in a state that cannot be rolled back to the previous stage.
The running cluster keeps running. GitOps sync and image pulls must not depend on a rename landing everywhere simultaneously.
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:

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

5 KiB Raw Permalink Blame History