diff --git a/GOAL.md b/GOAL.md index 90c66a9..99daa39 100644 --- a/GOAL.md +++ b/GOAL.md @@ -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/.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 diff --git a/SCOPE.md b/SCOPE.md index e3f27df..da46624 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -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) diff --git a/history/2026-09-28-readiness-review.md b/history/2026-09-28-readiness-review.md new file mode 100644 index 0000000..5a5fe2a --- /dev/null +++ b/history/2026-09-28-readiness-review.md @@ -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. diff --git a/workplans/ORGREF-WP-0001-foundation-and-entry-gate.md b/workplans/ORGREF-WP-0001-foundation-and-entry-gate.md index e7cd670..fc476c9 100644 --- a/workplans/ORGREF-WP-0001-foundation-and-entry-gate.md +++ b/workplans/ORGREF-WP-0001-foundation-and-entry-gate.md @@ -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.