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

---
id: ORGREF-WP-0001
type: workplan
title: "Foundation, blast-radius inventory, and execution entry gate"
domain: infotech
repo: prj-forgejo-org-refactor
status: backlog
owner: codex
topic_slug: railiance
created: "2026-08-11"
updated: "2026-08-19"
related_repos:
  - railiance-forge
  - railiance-platform
  - railiance-apps
  - railiance-master
state_hub_workstream_id: "c1dcd349-1a7a-51ae-8827-4ce96cfe0008"
---

# 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.

All tasks remain `todo` (not started) while the project-wide deferral stands.
An operator may move T01/T02 to `progress` before the full execution gate
because they are read-only; T03 onward still requires all four gate conditions.

## 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

```task
id: ORGREF-WP-0001-T01
status: todo
priority: high
state_hub_task_id: "4964bf8f-96eb-59f0-8a50-5ecb5c7dbc8f"
```

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.

```task
id: ORGREF-WP-0001-T02
status: todo
priority: high
state_hub_task_id: "00d150ed-81dd-51ac-af7b-197900373cbe"
```

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.

```task
id: ORGREF-WP-0001-T03
status: todo
priority: high
state_hub_task_id: "4b57ef3f-2a7c-56ff-b19d-e751b0b4685d"
```

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.

```task
id: ORGREF-WP-0001-T04
status: todo
priority: high
state_hub_task_id: "a55d95e2-6014-5d84-ba6e-b178c3901f3e"
```

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.

```task
id: ORGREF-WP-0001-T05
status: todo
priority: medium
state_hub_task_id: "3ad6090f-5aa9-5087-a670-37d7b2ffdb7c"
```

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.