prj-forgejo-org-refactor/workplans/ORGREF-WP-0001-foundation-and-entry-gate.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	related_repos
ORGREF-WP-0001	workplan	Foundation, blast-radius inventory, and execution entry gate	infotech	prj-forgejo-org-refactor	backlog	codex	railiance	2026-08-11	2026-08-11	railiance-forge railiance-platform railiance-apps railiance-master

ORGREF-WP-0001 - Foundation, blast-radius inventory, and execution entry gate

Status note

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

This workplan exists so the finding and its evidence are not lost, and so the condition for starting is written down and checkable rather than a judgement call made from memory months later.

Entry gate — do not start T03 onward until all four hold

1. Family declaration validator is live and green. The rapp/rail/reef validator proposed to railiance-master (message 04c776c4, amended by f88f938d) is running. Without it there is no way to tell whether a post-migration inconsistency was caused by the migration.
2. Deployable coverage is known. Every live deployable maps to exactly one rapp (the coverage check from decision d07ee5f9). Migrating image paths for workloads nobody has inventoried is how the container-registry failure mode goes unnoticed.
3. The G1 inventory command exists and returns a stable result across two consecutive runs with no fleet changes between them.
4. A rollback has been demonstrated on a throwaway or low-stakes repo, covering both Git path and package-registry recovery.

T01 and T02 below are safe to run at any time — they are read-only and they build the evidence the gate depends on.

Boundaries

This project may:

• inventory, plan, sequence, and verify the migration
• test Forgejo behavior against throwaway orgs and repos
• coordinate child work records in participating repos

It must not:

• move a production repo before the entry gate holds
• change any repo's internal structure or content
• absorb rapp-context or State Hub domain grouping (separate dimensions, decision d07ee5f9)

Tasks

id: ORGREF-WP-0001-T01
status: todo
priority: high

Build the re-runnable coulomb/ reference inventory (G1). Must cover: git remotes across all repos, ArgoCD repoURL values, chart image repository: paths, Chart.yaml home:/sources:, submodules, and CI configs. Output a machine-readable inventory under inventory/ plus a command that can be re-run to verify clean at G6.

Known starting evidence, verified 2026-08-11: 112 repos with a coulomb/ origin; repoURL: https://forgejo.coulomb.social/coulomb/railiance-platform.git in railiance-platform/argocd/applications/; repository: forgejo.coulomb.social/coulomb/core-hub in railiance-apps/charts/core-hub/values.yaml; home:/sources: URLs across at least five charts.

id: ORGREF-WP-0001-T02
status: todo
priority: high

Establish the org-assignment criteria and draft the taxonomy (G2) for railiance, netkingdom, helixforge, binky, experimental, and what coulomb retains. Criteria must be written so a future repo can be placed without re-litigating — that is what gets promoted at G7.

Guidance from the 2026-08-11 design review: an org is a stewardship grouping answering "who may push, what is discoverable together." It is deliberately not a legal-entity grouping (that lives in LICENSE, copyright headers, and contribution records, which survive repo moves) and not a deployment grouping (that is rapp context, a separate dimension per decision d07ee5f9).

Open question to settle here: experimental is a lifecycle grouping rather than a stewardship one. Decide whether it is a legitimate exception or whether experimental work belongs in its steward's org with a different visibility or archival policy.

id: ORGREF-WP-0001-T03
status: wait
priority: high

Verify Forgejo's actual rename/transfer behavior against a throwaway org (G3), for both the Git path and the package registry. Specifically: does a renamed org leave a working redirect for git clone/git fetch? Does it for docker pull? For how long? Is it configurable? Do not assume from documentation — the container-registry path is the dangerous one because its failure is deferred to the next pod reschedule rather than surfacing at rename time.

id: ORGREF-WP-0001-T04
status: wait
priority: high

Prove rollback (G4) on a low-stakes repo: move it, confirm GitOps sync and image pull both recover, move it back, confirm again. Produce the evidence record. This closes the entry gate.

id: ORGREF-WP-0001-T05
status: wait
priority: medium

Write the migration sequencing and cutover plan from the T01–T04 evidence: ordering, per-stage rollback point, which references must change ahead of the move versus after it, and how a deliberate pod-reschedule test is used to prove G6 rather than assuming success.

Residuals

None yet — the project is seeded, not started.