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

3.5 KiB

Raw Permalink Blame History

Genesis — 2026-08-11

How this project arose

It came out of a different question. A railiance-platform session was reviewing the reef/rail/rapp repo family model and asking where bounded rapp contexts should live. One candidate answer was: map them to Forgejo organizations.

That answer was rejected, and the reasoning is what created this project.

The rejected idea, and why

Binding rapp context to Forgejo orgs collapses two independent dimensions, which OAS P1 (canon/standards/orthogonal-architecture_v1.0.md) forbids: architecture descriptions MUST separate independent perspectives into orthogonal dimensions.

The decisive argument was cardinality. A repo lives in exactly one Forgejo org — it is a path segment in the clone URL, so org-to-repo is 1:many. But a repo can legitimately contribute to more than one rapp, so rapp-to-repo is many:many. A many:many grouping cannot be derived from a 1:many one.

Recorded as decision d07ee5f9-90d6-4e04-85d7-772103bc95f0.

The finding that remained

Separating the dimensions did not make the org problem go away — it isolated it. Once orgs were understood as a stewardship grouping answering "who may push, what is discoverable together," the current state was plainly wrong: all 112 repos with a Forgejo origin sit under coulomb/, including net-kingdom, helix-forge, and the entire railiance-* / rail-* / rapp-* / reef-* families. An org containing everything draws no boundary.

The operator had already been considering this refactor independently, and had been weighing whether orgs should instead map strictly to legal companies. That was set aside for a reason worth preserving: legal attribution already has a home in LICENSE, copyright headers, and contribution records (contribution-convention_v0.1) — and those survive repo moves, where org membership does not. So orgs can stay fluid without loosening legal rigor.

Why a project repo rather than a workplan

A blast-radius check turned up three surfaces, one of which changed the assessment:

112 git remotes — every clone and CI checkout.
ArgoCD sources — repoURL: https://forgejo.coulomb.social/coulomb/<repo>.git; GitOps stops syncing on a 404.
Container image paths — repository: forgejo.coulomb.social/coulomb/core-hub. Forgejo's package registry is org-scoped. A rename moves image paths for pods that are already running, so the failure does not appear at rename time; it appears at the next reschedule or restart.

The third is why "rename the org and fix the remotes" is unsafe, and why the operator judged this deep enough to warrant its own project repo rather than a workplan in someone else's.

Deliberately deferred

Operator decision: seed now, execute later, once the surrounding structure is stable enough that side-effect complications can be tested for rather than discovered in production.

That condition is written into ORGREF-WP-0001 as a four-part entry gate — the family declaration validator running, deployable coverage known, a stable re-runnable inventory, and a demonstrated rollback. The gate exists so the decision to start is made against evidence rather than against a memory of this conversation.

Target orgs

railiance, netkingdom, helixforge, binky, experimental, alongside coulomb for what genuinely belongs to it. experimental is flagged in T02 as a lifecycle grouping rather than a stewardship one — a question to settle, not a decision already made.

3.5 KiB Raw Permalink Blame History