Refresh org refactor plan against September readiness evidence

Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a0e782-9f45-7382-afff-77ad665b88ec
This commit is contained in:
tegwick 2026-09-28 12:20:59 +02:00
parent 2a59d0d354
commit dff3513a4f
4 changed files with 204 additions and 22 deletions

27
GOAL.md
View file

@ -3,7 +3,7 @@ repo: prj-forgejo-org-refactor
repo_flavor: project
project_status: draft
started: "2026-08-11"
reviewed: "2026-08-11"
reviewed: "2026-09-28"
---
# Project goal
@ -16,10 +16,11 @@ Split the single `coulomb/` Forgejo organization into stewardship organizations
membership expresses **discoverability and responsibility** instead of
expressing nothing.
Today all 112 repositories with a Forgejo origin sit under `coulomb/`,
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 boundary and grants no useful access control.
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.
@ -29,7 +30,13 @@ hard part, and it is why this is a project rather than a workplan.
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.
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. T01/T02 can advance; 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.
## Invariants
@ -50,13 +57,15 @@ entry gate below makes that condition checkable instead of a feeling.
## Known blast radius
Verified 2026-08-11. This is the evidence that made the effort project-sized.
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** — a rename moves image paths for **already-running pods**, so a node reschedule or restart can fail to pull long after the rename "succeeded" |
| **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? |
@ -70,6 +79,8 @@ at rename time, it shows up at the next pod reschedule.
- [ ] **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.
@ -79,7 +90,9 @@ at rename time, it shows up at the next pod reschedule.
- [ ] **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
- [ ] **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

View file

@ -44,7 +44,8 @@ by ID; it does not duplicate their tasks.
headers, and `contribution-convention_v0.1`
- Renaming the `forgejo.coulomb.social` host (open question, may become scope
only if the org split forces it)
- Any repo's internal structure or content
- Forge product migration (Gitea/Forgejo)
- Any repo's internal structure or content beyond coordinated migration references
---
@ -57,7 +58,9 @@ by ID; it does not duplicate their tasks.
| `railiance-apps` | Chart image `repository:` paths and chart metadata |
| `railiance-master` | Durable home candidate for the org-assignment convention |
| `the-custodian` | Canon home candidate; repo-classification alignment |
| all 112 `coulomb/` repos | Subjects of the migration |
| Current server-backed `coulomb/` repo inventory | Subjects of the migration; 112 was the seed count |
| `railiance-enablement` | Reusable CI/CD references and developer checkout paths |
| Source/rapp owners | Release manifests, package consumers, workload declarations |
---
@ -71,8 +74,8 @@ by ID; it does not duplicate their tasks.
- Deciding which rapp a workload belongs to (different dimension)
- Deciding which State Hub domain work belongs to (different dimension)
- The entry gate in `GOAL.md` is not yet met — the project is deliberately
parked until then
- Executing T03 onward before all four entry conditions in `ORGREF-WP-0001`
hold; read-only T01/T02 preparation remains relevant and permitted
---
@ -88,4 +91,8 @@ project's workplans, never copied.
- Status: **draft, deliberately deferred**
- Seeded 2026-08-11 with the finding, blast radius, and entry gate
- Execution begins only when the `ORGREF-WP-0001` entry gate is met
- Reviewed 2026-09-28: local family validator green; fresh deployable coverage,
stable full reference inventory and transfer rollback evidence still needed
- T01/T02 preparation can proceed now; execution requires the unchanged
`ORGREF-WP-0001` entry gate and resolution of its circular rollback dependency
- Evidence and next sequence: [readiness review](history/2026-09-28-readiness-review.md)

View file

@ -0,0 +1,106 @@
# Readiness review — 2026-09-28
## Disposition
Keep the stewardship-org outcome and the production deferral. Read-only T01/T02
preparation can proceed now. T03 onward cannot start: condition 1 has fresh
positive evidence, condition 2 is unproven, and conditions 3/4 lack evidence.
This review does not complete T01/T02 or authorize transfers, test-org creation,
package moves, credential changes, or reschedules.
## Evidence and limits
The session read State Hub `/state/summary` and unread messages for this repo;
the latter returned only the standing environment-orientation notice. Owner
workplan files, rather than aggregate completion counts, support this review.
Local checkouts were inspected; they were not fetched or changed.
| Entry condition | Evidence on September 28 | Assessment |
| --- | --- | --- |
| 1. Family validator live and green | `RMASTER-WP-0021-T05` delivered the validator on August 13. Running `python3 /home/worsch/railiance-master/tools/validate-family-declarations.py --root /home/worsch` now exits 0: 16 declarations, 0 errors, 1 informational derived-reef warning. | Satisfied for the inspected local fleet; repeat against the final migration snapshot. This is an executed validator, not evidence of a scheduled control. |
| 2. Every live deployable maps to exactly one rapp | `RMASTER-WP-0021-T06` delivered the check; `RMASTER-WP-0025` clarified universal managed-deployable coverage. Adding `--inventory /home/worsch/railiance-platform/docs/evidence/reef-railiance-deployables.json` exits 1: 16 declarations, 36 errors, 19 warnings. That inventory was captured August 13, 22:37:46Z. | Not satisfied. These are failures against an old snapshot, not a claim that precisely 36 workloads are uncovered today. Obtain fresh complete owner inventories, then resolve missing/ambiguous ownership. |
| 3. Stable G1 reference inventory | No project inventory command or machine-readable complete inventory exists. A bounded scan of immediate `/home/worsch` Git checkouts finds 151 origins containing `/coulomb/` or `:coulomb/`, versus the seed's 112. | Not satisfied. Local clone count is not a server repository count, may include multiple checkouts, and omits repos without local clones. It is not G1. |
| 4. Git and package rollback demonstrated | No applicable org-transfer rollback evidence found in this project or the inspected forge workplans. Recent application rollback/retention work does not test org transfer. | Not satisfied. Requires an applicable disposable-repo evidence record, including authenticated Git and uncached package recovery. |
Owner revisions inspected:
- railiance-master: `6729627d174afaff4501ccb798c6788aa3314bbf`
- railiance-platform: `a13fa575db507f36686eea0c42a2dea6d4b266d4`
- railiance-forge: `e395e5e9c196fe7cea9cd2be513554e493e675ee`
## Progress to reuse, not rebuild
- `RMASTER-WP-0021-T05/T06`: schema/family validation and inventory coverage
implementation; `RMASTER-WP-0025` (State Hub
`09d6dfc6-0bde-5516-acaa-a6a4f0551805`): operational and tooling deployables
also need exactly-one-rapp coverage. Non-workload actions stay outside it.
- `RPF-WP-0009`: platform inventory producer
`scripts/capture-reef-deployables.py` and the historical coverage snapshot.
- `RPF-WP-0028` (`622d1208-b085-5ec2-9fb7-5e41f23e1843`): durable additive
live-image inventory with refusal on missing/invalid exports. Its retained
union protects old images; it is not a current deployable-ownership census.
- `RPF-WP-0048-T03` (`6c2650a2-5da8-5999-a6e7-b22eb7c655f4`): digest-aware
package retention deployed and verified September 27, including rollback
protection. Org/package paths and retained aliases must join the migration
inventory. `RPF-WP-0048-T02` remains waiting for bounded promotion admission
and healthy observation; its September 28 record explicitly invalidates the
previous observation interval. An existing GitOps Application is not proof
that a migration has a usable release identity.
These are related owner records, not new child assignments or duplicated tasks.
## Corrections to the original plan
1. Treat 112 repositories as historical evidence. Reconcile server inventory,
registered repositories and local clones, including archived repos and
untracked consumers. Record exclusions and unavailable surfaces explicitly.
2. Inventory actual forge products, versions and endpoints first. The seed uses
`forgejo.coulomb.social`, while forge's August 22 SCOPE still describes current
Gitea and future Forgejo migration. This discrepancy is unresolved; do not
infer runtime identity from a hostname or conflate org transfer with a
product/host migration.
3. Distinguish individual repository transfer from organization rename and from
package ownership changes. Org-scoped registry paths are a risk surface;
automatic package movement or registry redirects are not established facts.
4. Include GitOps AppProject source allowlists, repository credentials and access
policy references, reusable Actions, runners/webhooks, package indexes,
digest/tag retention inputs, release manifests, and rollback image references.
Store reference locations and access requirements, never secret values.
5. Keep `experimental` a proposal. Lifecycle and stewardship are different
dimensions; default draft guidance is steward-owned experimental repositories,
with any shared incubator requiring an explicit accountable steward.
6. Make G6 mean zero unexplained operational references to moved paths. Valid
`coulomb` assignments and immutable historical evidence are not stale links.
7. The foundation plan ends at a cutover plan. Actual migration waves (G5/G6)
and permanent convention publication (G7) require subsequent file-backed
coordination and owner records, not an implied extension of T05.
## Circular gate: unresolved decision
Decision `e9aca79b-f167-4326-94cd-037dcea34cd2` records the conflict: condition 4
requires the proof T04 was supposed to produce, but T04 cannot start until all
four conditions hold. T04 is now described as revalidating accepted prior proof;
that clarifies the unchanged rule but does not manufacture a prerequisite.
Recommended future amendment: once conditions 1–3 hold, allow a precisely scoped,
isolated disposable rehearsal owned by railiance-forge, while retaining all four
conditions before any production transfer. This requires an explicit gate
amendment covering AGENTS.md and the workplan. Alternatively consume independently
authorized applicable owner evidence. Neither path is assumed authorized here.
## Next sequence
1. Complete T01's repeatable inventory and reconcile its coverage; capture two
identical normalized results with source revisions unchanged.
2. Complete T02's steward/permissions matrix and per-repo assignments; settle
`experimental`, retained `coulomb`, and the durable convention owner.
3. Obtain current deployable coverage receipts from the existing owners and
link their gap-closing work by stable ID. Repeat the family scan.
4. Resolve the circular-gate decision and obtain valid rollback proof without
bypassing the standing gate.
5. Only then start T03/T04, approve evidence for G3/G4, and complete T05's staged
cutover design. Require old/new package availability, retention protection,
source permissions, rollback owners and abort criteria for every wave.
6. Create follow-on migration and convention-publication workplans. Execute a
low-stakes wave before wider transfers; prove fresh image pulls/reschedules
and GitOps recovery, then close G5–G7 and retire the project.

View file

@ -9,7 +9,7 @@ flavor: implementation
owner: codex
topic_slug: railiance
created: "2026-08-11"
updated: "2026-08-19"
updated: "2026-09-28"
related_repos:
- railiance-forge
- railiance-platform
@ -30,7 +30,7 @@ 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.
All tasks remain `todo`: this review updates the plan, not task acceptance.
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.
@ -52,6 +52,29 @@ because they are read-only; T03 onward still requires all four gate conditions.
T01 and T02 below are safe to run at any time — they are read-only and they
build the evidence the gate depends on.
## Readiness review — 2026-09-28
See [evidence, owner records and next sequence](../history/2026-09-28-readiness-review.md).
| Condition | Current evidence | Disposition |
| --- | --- | --- |
| 1 | Validator implemented in `RMASTER-WP-0021-T05`; current local scan: 16 declarations, zero errors, one warning | Green for inspected fleet; rerun before execution |
| 2 | Coverage check exists (`RMASTER-WP-0021-T06`); universal scope clarified by `RMASTER-WP-0025`. August 13 snapshot yields 36 errors/19 warnings today | Not met; fresh complete coverage required |
| 3 | No complete G1 command or stable paired output; bounded local count now 151 `coulomb` origins | Not met; T01 remains open |
| 4 | No applicable Git/package transfer rollback receipt found | Not met; T03 onward remains gated |
**Circular prerequisite:** T04 cannot produce the first condition-4 proof while
it is itself gated on that proof. Pending decision
`e9aca79b-f167-4326-94cd-037dcea34cd2` proposes a separately scoped disposable
forge-owner rehearsal after conditions 1–3, with all four conditions retained for
production. It is a proposal, not an exception to AGENTS.md. Until the gate is
explicitly amended, consume independently authorized applicable proof or remain
deferred. Do not start T03/T04 to work around this dependency.
Reuse owner work instead of rebuilding it: `RPF-WP-0028` provides durable image
inventory; `RPF-WP-0048-T03` provides digest/rollback retention protection.
Neither establishes complete current rapp coverage or org-transfer recovery.
## Boundaries
This project may:
@ -78,9 +101,22 @@ 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
paths, `Chart.yaml` `home:`/`sources:`, submodules, and CI configs. Also include AppProject source allowlists, repository access
references, reusable Actions, runners/webhooks, package indexes, digest/tag
retention inputs, and release/rollback image references. Output a
machine-readable inventory under `inventory/` plus a command that can be
re-run to verify clean at G6.
re-run to verify clean at G6. Discover actual server product/version and all
Git/registry endpoints; owner docs disagree with the seed's Forgejo-only naming.
Reconcile server repository IDs with registered repos and clones; do not treat
151 local origins as a complete server census. Inventory package ownership
separately from linked repositories. Capture source revisions, unavailable
surfaces, exclusions and reference owners without secret values.
Acceptance: two normalized inventory runs match with no intervening fleet
changes; unresolved coverage is explicit and prevents G1 acceptance. G6 checks
moved paths against an approved disposition list, preserving legitimate retained
`coulomb` paths and historical records. This read-only collector/evidence belongs
here; production fixes belong to the owning repos.
Known starting evidence, verified 2026-08-11: 112 repos with a `coulomb/`
origin; `repoURL: https://forgejo.coulomb.social/coulomb/railiance-platform.git`
@ -109,7 +145,11 @@ contribution records, which survive repo moves) and not a deployment grouping
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.
archival policy. Draft preference: keep it with its steward unless a shared
incubator has an explicit accountable owner. Target org names remain candidates.
Acceptance requires every server repo's stable ID, target, steward, rationale,
visibility/team permissions and unresolved assignment (if any); approve the
matrix and select the permanent convention owner before declaring G2 complete.
```task
id: ORGREF-WP-0001-T03
@ -118,8 +158,11 @@ 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
Verify the deployed forge product/version's actual behavior against a throwaway org (G3),
for **both** the Git path and the package registry. Test repository transfer,
organization rename and package ownership separately; do not infer that a repo
transfer moves its packages. Include authenticated Git/CI access, private pulls,
digests/tags and relevant package indexes. 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
@ -135,7 +178,11 @@ 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.
record. This revalidates the previously accepted condition-4 evidence for the selected
migration path; it cannot bootstrap its own prerequisite under the standing gate.
Record exact operation, product/version, old/new paths, uncached pulls, GitOps
revision/health, retention protections, credentials scope, cleanup and recovery
time. Unrelated application rollout rollback is not acceptable transfer proof.
```task
id: ORGREF-WP-0001-T05
@ -147,8 +194,17 @@ 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.
G6 rather than assuming success. Include release broker/admission readiness,
AppProject/repository access updates, old/new package availability and retention
protection for live and rollback digests. Identify owners, abort criteria and
validation receipts for each stage. Start with a low-stakes wave; never combine
an org split with an unplanned host or forge-product migration.
## Residuals
None yet — the project is seeded, not started.
- Resolve pending gate decision `e9aca79b-f167-4326-94cd-037dcea34cd2`.
- Fresh deployable coverage and gap closure remain with platform/framework and
workload owners; link their work by stable ID rather than importing tasks.
- T05 produces the plan only. Follow-on file-backed workplans must cover migration
waves (G5/G6), durable convention publication (G7) and retirement evidence.
Create those after foundation acceptance; no migration task is implied done.