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: blocked
flavor: implementation
owner: codex
topic_slug: railiance
created: "2026-08-11"
updated: "2026-10-05"
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

`blocked` after authorized read-only preparation on 2026-09-28. The founder's
August 11 production deferral remains in force. T01/T02 now have review artifacts
and are waiting on evidence/access and stewardship decisions; T03–T05 have not
started.

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.

The user authorized preparation on September 28. T01/T02 are `wait` after the
bounded preparation below; their acceptance criteria are not yet met. T03 onward
still requires all four gate conditions.

2026-10-05: T01 is wait on the authenticated-metadata decision
`5f3680fc-0cd5-4d27-ba39-59fbdd13313c`. T02 also waits on the stewardship
review `60c5767c-d510-4d13-9a24-d5d58485b7e5`. T03 and T04 wait on the
rollback-gate decision `e9aca79b-f167-4326-94cd-037dcea34cd2`. T05 waits on
T01–T04. None of these tasks started a forge change.

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

## 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 | Fresh September 28 platform capture: 68 units; validator reports 52 errors/10 warnings. Wider runtime capture covers 132 controllers | Not met; owner mapping/name drift and collector coverage still need resolution |
| 3 | Collector implemented; 141 public repos + 12 additional local paths, 2,160 source/archive references. Paired reference sets match but fleet revisions/content changed; private/package/access evidence missing | Not met; partial inventory is not G1 acceptance |
| 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.
The [exact proposed amendment](../decisions/rollback-gate-amendment.md) is now
reviewable; approval has been requested but is not assumed from preparation
authorization. No standing rule has changed.

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:

- 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: wait
needs_human: true
decision_id: 5f3680fc-0cd5-4d27-ba39-59fbdd13313c
blocking_reason: "The September 28 collector is not G1 acceptance. Authenticated metadata still waits on decision 5f3680fc, and an unchanged-fleet pair is still missing."
priority: high
state_hub_task_id: "4964bf8f-96eb-59f0-8a50-5ecb5c7dbc8f"
```
2026-09-29 (CUST-WP-0074-T05 backfill): this task was `wait` with no external dependency or human gate stated, which Task Wait Qualifiers v0.1 treats as unqualified; set to `todo`. Re-add `wait` with a qualifier if a real gate exists.


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

Preparation delivered September 28:

- `tools/inventory.py`, paired snapshots and `inventory/comparison.json`;
  150 non-coordinator local checkouts plus two pinned public remote-only archives,
  2,133 local + 27 archive reference occurrences, no scan errors.
- Fresh workload and GitOps exports, source revision/content hashes, exclusions,
  machine-readable repo/State Hub reconciliation and safe reference-only records.
- Four focused tests pass; the migration cleanliness precheck correctly refuses
  incomplete coverage and an unapproved matrix.
- Waiting on authenticated metadata decision
  `5f3680fc-0cd5-4d27-ba39-59fbdd13313c`, exclusion/consumer coverage review and an
  unchanged-fleet pair. The existing credential lane was denied by flex-auth;
  package ownership and private completeness are not known.

See [inventory instructions and gaps](../inventory/README.md). T01 is not done.
The follow-up now links [owner records](../inventory/owner-followups.md), a
52-row coverage review queue, 326 excluded-item dispositions and four submodule
pins. An immediate retry still observed hub-core changing; condition 3 remains
unmet. Authenticated evidence has an explicit [export contract](../inventory/owner-evidence-contract.md).

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: wait
depends_on: [ORGREF-WP-0001-T01]
needs_human: true
decision_id: 60c5767c-d510-4d13-9a24-d5d58485b7e5
blocking_reason: "The taxonomy draft waits on the G1 inventory (T01) and on stewardship review 60c5767c. The September 28 matrix is not acceptance."
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. 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.

Preparation delivered September 28: [taxonomy proposal](../taxonomy/README.md)
and CSV/JSON matrix cover 153 known paths: 122 proposed org assignments and 31
explicitly unresolved stewards. Visibility is preserved by proposal; named teams,
actual grants and missing private IDs still need owner evidence. Recommend no
lifecycle-only `experimental` org and `the-custodian` as the durable convention
home, both pending acceptance. Decision
`60c5767c-d510-4d13-9a24-d5d58485b7e5` tracks the concrete review. G2 is not accepted. The deeper review proposes
whynot as an additional steward, and records evidence for ops-hub/disaster-control.
Naming and maintainer acceptance remain pending.

```task
id: ORGREF-WP-0001-T03
status: wait
depends_on: [ORGREF-WP-0001-T01, ORGREF-WP-0001-T02]
needs_human: true
decision_id: e9aca79b-f167-4326-94cd-037dcea34cd2
blocking_reason: "The August 11 production deferral remains in force. Throwaway forge behavior does not start while G1 and G2 are unaccepted and the rollback-gate decision is open."
priority: high
state_hub_task_id: "4b57ef3f-2a7c-56ff-b19d-e751b0b4685d"
```

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
failure is deferred to the next pod reschedule rather than surfacing at rename
time.

```task
id: ORGREF-WP-0001-T04
status: wait
needs_human: true
decision_id: e9aca79b-f167-4326-94cd-037dcea34cd2
blocking_reason: "Rollback proof cannot bootstrap its own prerequisite. Decision e9aca79b is still open, and the August 11 production deferral remains in force."
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 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
status: wait
depends_on: [ORGREF-WP-0001-T01, ORGREF-WP-0001-T02, ORGREF-WP-0001-T03, ORGREF-WP-0001-T04]
blocking_reason: "The cutover plan is written from T01–T04 evidence. Those tasks are still open."
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. 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

- T01 metadata access/completeness: `5f3680fc-0cd5-4d27-ba39-59fbdd13313c`.
- T02 matrix/maintainer/convention acceptance: `60c5767c-d510-4d13-9a24-d5d58485b7e5`.

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