tegwick
57ad4abefc
Assistant: codex Assistant-Model: gpt-6.1-sol Assistant-Session: 01a11beb-4eef-7fc1-94a7-597130a01ae9
125 lines
6.8 KiB
Markdown
125 lines
6.8 KiB
Markdown
---
|
||
repo: prj-forgejo-org-refactor
|
||
repo_flavor: project
|
||
project_status: draft
|
||
started: "2026-08-11"
|
||
reviewed: "2026-10-09"
|
||
---
|
||
|
||
# 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. Authorized preparation has now produced a partial repeatable inventory
|
||
and stewardship matrix; T01/T02 wait on the documented evidence and decisions.
|
||
Fresh platform coverage reports 52 unclaimed workload names. 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. Preparation artifacts:
|
||
[inventory](inventory/README.md), [taxonomy](taxonomy/README.md), and
|
||
[preparation record](history/2026-09-28-preparation.md).
|
||
|
||
## Access-control coordination — 2026-10-09
|
||
|
||
ORGREF-WP-0002 independently coordinates the accepted October 8 policy: private
|
||
forge repositories and packages, external deliberate publication, authenticated
|
||
consumers and staged visibility changes. T01–T03 have accepted preparation;
|
||
identity implementation and closure proofs remain with their owner records.
|
||
See [policy](decisions/forge-visibility-policy.md) and the
|
||
[October 9 review](history/2026-10-09-review-and-maintenance.md). This work does
|
||
not satisfy or waive the four-condition org-transfer entry gate.
|
||
|
||
## 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`.
|