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

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.

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

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. T01 is not done. The follow-up now links owner records, 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.

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

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.

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.

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.