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

id	type	title	domain	repo	status	flavor	owner	topic_slug	created	updated	related_repos	state_hub_workstream_id
ORGREF-WP-0001	workplan	Foundation, blast-radius inventory, and execution entry gate	infotech	prj-forgejo-org-refactor	blocked	implementation	codex	railiance	2026-08-11	2026-09-28	railiance-forge railiance-platform railiance-apps railiance-master	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.

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.

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.

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

id: ORGREF-WP-0001-T01
status: wait
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. 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. T01 is not done.

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: wait
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 and CSV/JSON matrix cover 153 known paths: 118 proposed org assignments and 35 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.

id: ORGREF-WP-0001-T03
status: todo
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.

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

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