coulomb/prj-forgejo-org-refactor
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Seed the org refactor: goal, scope, blast radius, entry gate

Browse source 
Establishes the prj- flavor baseline (GOAL.md, SCOPE.md, AGENTS.md,
.repo-classification.yaml, genesis, foundation workplan) for splitting the
single coulomb/ Forgejo org into stewardship orgs.

Records the blast radius verified 2026-08-11: 112 repos with a coulomb/ origin,
ArgoCD repoURL sources, Chart.yaml metadata, and - the finding that made this
project-sized rather than workplan-sized - container image paths, since
Forgejo's package registry is org-scoped. That failure is deferred: it does not
appear at rename time but at the next pod reschedule.

Seeded deliberately deferred per operator decision. ORGREF-WP-0001 is backlog
and carries a four-part entry gate (validator live, deployable coverage known,
stable re-runnable inventory, demonstrated rollback) so the decision to start
is made against evidence rather than memory. T01 and T02 are read-only and safe
to advance at any time.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
tegwick 2026-08-11 13:39:24 +02:00
parent 12bf13f020
commit ec2a72f435
10 changed files with 827 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

164
.gitignore vendored Normal file
View file

@ -0,0 +1,164 @@
# ---> Python
# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class
# C extensions
*.so
# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST
# PyInstaller
# Usually these files are written by a python script from a template
# before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest
*.spec
# Installer logs
pip-log.txt
pip-delete-this-directory.txt
# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
cover/
# Translations
*.mo
*.pot
# Django stuff:
*.log
local_settings.py
db.sqlite3
db.sqlite3-journal
# Flask stuff:
instance/
.webassets-cache
# Scrapy stuff:
.scrapy
# Sphinx documentation
docs/_build/
# PyBuilder
.pybuilder/
target/
# Jupyter Notebook
.ipynb_checkpoints
# IPython
profile_default/
ipython_config.py
# pyenv
# For a library or package, you might want to ignore these files since the code is
# intended to run in multiple environments; otherwise, check them in:
# .python-version
# pipenv
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
# However, in case of collaboration, if having platform-specific dependencies or dependencies
# having no cross-platform support, pipenv may install dependencies that don't work, or not
# install all needed dependencies.
#Pipfile.lock
# poetry
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
# This is especially recommended for binary packages to ensure reproducibility, and is more
# commonly ignored for libraries.
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
#poetry.lock
# pdm
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
#pdm.lock
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
# in version control.
# https://pdm.fming.dev/latest/usage/project/#working-with-version-control
.pdm.toml
.pdm-python
.pdm-build/
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
__pypackages__/
# Celery stuff
celerybeat-schedule
celerybeat.pid
# SageMath parsed files
*.sage.py
# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/
# Spyder project settings
.spyderproject
.spyproject
# Rope project settings
.ropeproject
# mkdocs documentation
/site
# mypy
.mypy_cache/
.dmypy.json
dmypy.json
# Pyre type checker
.pyre/
# pytype static type analyzer
.pytype/
# Cython debug symbols
cython_debug/
# PyCharm
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
# and can be added to the global gitignore or merged into this file. For a more nuclear
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
#.idea/

29
.repo-classification.yaml Normal file
View file

@ -0,0 +1,29 @@
repo_classification:
standard: Repo Classification Standard
version: "1.0"
classified_at: "2026-08-11"
classified_by: agent
category: project
domain: infotech
secondary_domains:
- agents
capability_tags:
- governance
- operations
- coordination
- migration
business_stake:
- operations
- execution
business_mechanics:
- intention
- coordination
- control
notes: >-
Temporary prj-flavor repository coordinating the split of the single
coulomb/ Forgejo organization into stewardship organizations (railiance,
netkingdom, helixforge, binky, experimental) without breaking GitOps
sources, container image paths, or clones. Seeded 2026-08-11 and
deliberately deferred until its entry gate holds. Archive when GOAL.md
retirement gates are met and the org-assignment convention is promoted to
a permanent home.

45
AGENTS.md Normal file
View file

@ -0,0 +1,45 @@
# Agent session protocol — prj-forgejo-org-refactor
Dev Hub (State Hub API): http://127.0.0.1:8000
## Before anything else
This project is **deliberately deferred**. Read `GOAL.md` "Why this is
deferred" and the `ORGREF-WP-0001` entry gate before proposing execution work.
T01 and T02 are read-only and safe to advance at any time; **T03 onward must
not start until all four entry-gate conditions hold.**
If you believe the gate is met, say which of the four conditions changed and
what evidence shows it — do not infer readiness from elapsed time.
## Session start
1. `GOAL.md` → `SCOPE.md` → `history/` → `workplans/`
2. `get_domain_summary("infotech")` when MCP tools are exposed, else
`curl -s http://127.0.0.1:8000/state/summary`
3. `get_messages(to_agent="prj-forgejo-org-refactor", unread_only=True)`
## During work
`record_decision()` · `add_progress_event()` · `resolve_decision()`
State Hub is a read model. **Never register workplans or tasks by hand.**
Write the workplan file, commit, then run:
```bash
statehub fix-consistency --repo prj-forgejo-org-refactor
```
C-06 registers the workplan and writes IDs back into the file.
## Boundary
This repo coordinates; it hosts no production implementation. Child work lands
in participating repos and is linked by stable ID, never copied.
Do not absorb rapp-context or State Hub domain grouping into this project —
they are separate dimensions (decision `d07ee5f9`, OAS P1).
## Session close
`add_progress_event()` with the workplan id, then `statehub fix-consistency`.

98
GOAL.md Normal file
View file

@ -0,0 +1,98 @@
---
repo: prj-forgejo-org-refactor
repo_flavor: project
project_status: draft
started: "2026-08-11"
reviewed: "2026-08-11"
---
# Project goal
## Outcome
Split the single `coulomb/` Forgejo organization into stewardship organizations
— `railiance`, `netkingdom`, `helixforge`, `binky`, `experimental`, with
`coulomb` retained for what genuinely belongs to it — so that organization
membership expresses **discoverability and responsibility** instead of
expressing nothing.
Today all 112 repositories with a Forgejo origin sit 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.
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.
## Why this is deferred
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.
## Invariants
1. **No silent breakage.** Every reference that moves is inventoried before it
moves, and verified after.
2. **Organization membership is a stewardship grouping**, not a legal-entity
grouping and not a deployment grouping. Legal attribution stays with
`LICENSE`, copyright headers, and contribution records
(`contribution-convention_v0.1`), which survive repo moves. Deployment
grouping stays with rapp contexts, which are a separate dimension by
ratified decision (`d07ee5f9-90d6-4e04-85d7-772103bc95f0`, OAS P1).
3. **Reversible in stages.** No stage may leave the fleet in a state that
cannot be rolled back to the previous stage.
4. **The running cluster keeps running.** GitOps sync and image pulls must not
depend on a rename landing everywhere simultaneously.
5. **This repo hosts no production implementation.** It coordinates; the
changes land in the repos that own them.
## Known blast radius
Verified 2026-08-11. This is the evidence that made the effort project-sized.
| 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" |
| 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? |
The container-registry finding is the one that makes a naive "rename and fix
the remotes" approach unsafe. It is a *deferred* failure — it does not show up
at rename time, it shows up at the next pod reschedule.
## Success gates
- [ ] **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.
- [ ] **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.
- [ ] **G3 — Redirect behavior verified.** Forgejo's actual behavior on org
rename / repo transfer — for Git paths *and* for the package registry —
is established by test against a throwaway org, not assumed from docs.
- [ ] **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
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
created in the right org by default rather than by memory.
## Project retirement
This repository may be archived when:
1. every success gate has accepted evidence;
2. residuals have live work records in permanent repos;
3. the org-assignment convention is promoted to a durable home (canon or
`railiance-master`), per G7;
4. workplans are finished or cancelled with rationale;
5. a completion record exists under `history/`;
6. `project_status` is set to `completed`, then `archived`.

151
LICENSE Normal file
View file

@ -0,0 +1,151 @@
# Target Revenue Source License
**Version 1.0, Candidate 1 (V1C1)**
---
> **PRELIMINARY CANDIDATE — SUBJECT TO CHANGE — NOT FINAL**
>
> This repository is governed by the Target Revenue Source License
> (TRSL), Version 1, Candidate 1. This is the framework's first working
> candidate, adopted as the org's preliminary operating license across
> all repos (maintainer decision, 2026-07-29) during the build/alpha
> stage — see `SCOPE.md` §1 and Appendix A of the canonical text (link
> below) for the alpha/beta risk-acceptance decision this reflects and
> what it does and does not mean. Full specialist legal review is
> explicitly deferred until the framework moves out of beta.
>
> **Canonical source, full candidate-status banner, and Appendix A
> (non-normative candidate notes tracking every open item):** the
> `coulomb` org's `target-revenue` repository,
> `specs/TargetRevenueSourceLicense-V1C1.md` — this file is the operative
> legal text (Preamble through Section 11) only; the canonical document
> is authoritative if this copy and that document ever diverge.
---
## Preamble
This Target Revenue Source License ("**License**") governs the Software identified in the applicable Phase Manifest. It implements the Target Revenue Framework: a defined development Phase accumulates Development Credit and Remission Credit against an immutable Initial Target until the Milestone Release automatically and irrevocably converts to a declared permissive Future License.
Commercial beneficiaries fund the creation and early availability of a software improvement; once the declared target is satisfied, the governed release becomes permissively open source.
## 1. Definitions
Capitalized terms used in this License have the meanings given below. Where a term is also defined in the Phase Manifest or Target Ledger for a specific Phase, the Phase Manifest and Target Ledger govern the *values* (amounts, dates, identifiers) and this License governs the *legal effect* of those values — the two must not be read as conflicting definitions of the same concept.
**"Commercial Entitlement"** means a right, purchased or otherwise granted under a Commercial Use Agreement, to make Commercial Use of the Software during a Phase.
**"Commercial Use"** means billing, invoicing, or otherwise charging any customer a fee, subscription, license fee, or other consideration for or in connection with use of the Software, at any time before the Conversion Event for the applicable Phase, regardless of whether the person or organization billed would otherwise qualify for Noncommercial Use. Commercial Use occurs by virtue of such billing alone, whether or not the resulting payment is registered with the Trust Service; in particular, billing a customer for pre-conversion use of the Software without recording the corresponding payment in the applicable Phase's Target Ledger is Commercial Use without a valid Commercial Entitlement — a violation of Section 3, addressed under Section 7 and, where applicable, the Enforcement Network described in the canonical repository's `specs/EnforcementNetworkConcept.md`.
**"Commercial Use Agreement"** means the separate agreement, referenced by the applicable Phase Manifest, under which a Commercial Entitlement is purchased or granted. This License does not itself set pricing, metering, or payment terms — those are governed by the Commercial Use Agreement.
**"Conversion Event"** means the moment the Outstanding Target for a Phase reaches zero, as computed from the Phase Manifest and Target Ledger per the Target Ledger Specification. The Conversion Event occurs automatically and is not conditioned on any declaration, attestation, or other act by the Licensor or any Trust Service.
**"Development Credit"** means the portion of a collected and settled payment explicitly allocated toward satisfying the Initial Target of a specific Phase, as recorded in that Phase's Target Ledger.
**"Future License"** means the permissive license identified in the applicable Phase Manifest, being either the MIT License or the Apache License, Version 2.0, which applies to the Milestone Release upon the Conversion Event.
**"Initial Target"** means the immutable monetary target declared for a Phase in its Phase Manifest.
**"Licensor"** means **Binky Hedgehog GmbH**, the party that publishes the Phase Manifest and holds the rights necessary to grant this License and the Future License for the Milestone Release.
**"Milestone Release"** means the precisely identified software release designated in the applicable Phase Manifest, identified by an immutable source revision, release artifact, or cryptographic digest.
**"Noncommercial Use"** means use of the Software for personal purposes, private study, hobby or amateur projects; use by any charitable organization, educational institution, public research organization, or government institution acting in a non-revenue-generating capacity; or other use of a materially similar character.
**"Outstanding Target"** means, at any time, `max(0, Initial Target − cumulative Development Credit − cumulative Remission Credit)` for a Phase, as computed from that Phase's Target Ledger.
**"Phase"** means a bounded development undertaking governed by one Initial Target, one Milestone Release, one degeneration policy, and one Future License declaration, as declared in a Phase Manifest.
**"Phase Manifest"** means the published, immutable declaration identifying a Phase, its Milestone Release, Initial Target, Future License, degeneration policy, and Target Ledger location, as specified in the Phase Manifest Specification.
**"Remission Credit"** means a transparent, non-revenue reduction of a Phase's Outstanding Target, generated under that Phase's published degeneration policy and recorded in the Target Ledger.
**"Settled Payment"** means a payment that has cleared through its payment processor and is no longer subject to reversal in the ordinary course (chargeback, dispute, or equivalent), as further specified by the applicable Commercial Use Agreement or monetization extension.
**"Software"** means the source code, object code, and associated documentation of the Milestone Release identified in the applicable Phase Manifest.
**"Target Ledger"** means the append-only record of Development Credit, Remission Credit, and correction entries for a Phase, as specified in the Target Ledger Specification.
**"You"** or **"Licensee"** means the individual or entity exercising rights under this License.
## 2. Grant of Rights for Noncommercial Use
Subject to the terms of this License, the Licensor grants You a worldwide, royalty-free, non-exclusive license, during the applicable Phase, to:
(a) use, reproduce, and study the Software for any Noncommercial Use;
(b) modify the Software and create derivative works of it for any Noncommercial Use; and
(c) redistribute the Software and Your modifications, in source or object form, for any Noncommercial Use, provided that You include this License, unmodified, with any such redistribution, and that You do not remove or alter any copyright, patent, trademark, or attribution notices contained in the Software.
This grant does not extend to Commercial Use. Commercial Use requires a Commercial Entitlement under Section 3.
## 3. Commercial Use
You may not make Commercial Use of the Software during the applicable Phase unless You hold a valid, current Commercial Entitlement under a Commercial Use Agreement with the Licensor covering the applicable Phase. A Commercial Entitlement granted under one Phase's Commercial Use Agreement does not extend to a later Phase's Milestone Release unless the Commercial Use Agreement expressly says so.
This Section 3 states the existence and boundary of the commercial-use restriction. It does not itself set pricing, invoicing, metering, audit rights, or payment terms — those are governed exclusively by the applicable Commercial Use Agreement.
## 4. Patent License
Subject to the terms of this License, each contributor to the Software grants You, during the applicable Phase and solely to the extent of rights granted under Sections 2 and 3, a perpetual (subject to the termination below), worldwide, non-exclusive, no-charge, royalty-free patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Software, limited to those patent claims licensable by that contributor that are necessarily infringed by their contribution(s) alone or by combination of their contribution(s) with the Software.
If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Software or a contribution incorporated within it constitutes direct or contributory patent infringement, then any patent licenses granted to You under this Section 4 for the Software shall terminate as of the date such litigation is filed.
## 5. Automatic Conversion to the Future License
**5.1 Automatic effect.** Upon the Conversion Event for a Phase, the rights and restrictions in Sections 3 (Commercial Use) of this License, as they apply to that Phase's Milestone Release, terminate automatically. In their place, the Milestone Release is licensed under the Future License identified in that Phase's Phase Manifest, effective as of the Conversion Event, without any further act, declaration, or attestation required by the Licensor, any Trust Service, or any other party.
**5.2 Irrevocability.** Once a valid Conversion Event has occurred for a Phase, no subsequent refund, chargeback, accounting correction, dispute, or termination of this License for an unrelated breach shall revoke, suspend, or otherwise impair the Future License grant for that Phase's Milestone Release. Any shortfall or dispute arising after a Conversion Event is a commercial or accounting matter between the relevant parties and does not reinstate a commercial-use restriction over already-converted Software.
**5.3 Prior freedom preserved.** A later Phase covering subsequent improvements to the Software does not restrict, withdraw, or otherwise affect the rights granted under the Future License for an earlier Phase's already-converted Milestone Release.
**5.4 Evidence, not cause.** A Trust Service may publish a Conversion Attestation documenting a Conversion Event. Such an attestation is evidence that the Conversion Event occurred; it is not a condition of, and its absence or delay does not postpone, the automatic effect described in Section 5.1. Any person may independently verify whether a Conversion Event has occurred directly from the Phase Manifest and Target Ledger.
## 6. Successive Phases
The Licensor may declare a new Phase covering subsequent improvements to the Software following a Milestone Release's Conversion Event. Each Phase is independently governed by its own Phase Manifest, Initial Target, degeneration policy, and Target Ledger. Nothing in a later Phase's Phase Manifest may be construed to reduce or withdraw rights already granted under Section 5 for an earlier Phase's Milestone Release.
## 7. Term and Termination
**7.1 Term.** This License applies to the Software for the duration of the applicable Phase, and, for the Milestone Release, indefinitely following that Phase's Conversion Event under the Future License.
**7.2 Termination for breach.** If You breach Section 3 (Commercial Use) or Section 2(c) (redistribution notice requirement), the Licensor may terminate this License as to You. Before such termination becomes effective, the Licensor shall provide You written notice of the breach; if You cure the breach within thirty (30) days of that notice, this License continues in effect. A second breach of the same provision within twelve (12) months may be terminated immediately without a further cure opportunity.
**7.3 Effect of termination.** Termination under this Section 7 affects only Your rights under Sections 2 and 3 for the Phase in which the breach occurred. It does not affect any rights already vested under Section 5 (Automatic Conversion) for a Milestone Release whose Conversion Event has already occurred, per Section 5.2.
**7.4 Public record of breach and resolution.** The Licensor shall cause the Trust Service to publish, as part of the public record for the affected Phase, notice of: (a) any breach notice issued under Section 7.2, stating the general nature of the breach and the date of notice; (b) whether the breach was cured within the applicable cure period, and the date of cure; and (c) any termination determination made under this Section 7, including its effective date and scope. This public record exists to give the ecosystem a transparent, verifiable conformity signal for the Phase, distinct from and in addition to the Development Credit and Remission Credit facts already published under Section 5.4 and the Target Ledger Specification.
A breach that You dispute, and that has not been finally determined, shall be recorded as **alleged**; it shall be recorded as **determined** only once the cure period has run without cure, or the dispute has been resolved against You under the applicable Commercial Use Agreement's dispute process, if any. The Trust Service shall update the record promptly upon resolution in either direction. Recording an alleged or determined breach under this Section 7.4 is a ministerial act of publishing the Licensor's determination (or a dispute process's outcome); it does not give the Trust Service discretionary authority to decide whether a breach occurred, consistent with Section 5.4's evidence-not-cause principle.
Whether, and under what conditions, the public record identifies a Commercial Entitlement holder by name is governed exclusively by the applicable Commercial Use Agreement, which the Licensor and that Commercial Entitlement holder negotiate and agree to directly. This License does not itself set a naming default. Where no Commercial Use Agreement addresses the question, or where the affected party has no Commercial Use Agreement at all (for example, a Section 2(c) breach by a Noncommercial Use licensee), the public record states the Phase and breach category only, without naming the party.
## 8. Disclaimer of Warranty
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. THE LICENSOR DOES NOT WARRANT THAT THE SOFTWARE WILL BE ERROR-FREE OR THAT ANY PHASE WILL REACH ITS CONVERSION EVENT.
## 9. Limitation of Liability
IN NO EVENT SHALL THE LICENSOR OR ANY CONTRIBUTOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE, EXCEPT TO THE EXTENT SUCH LIMITATION IS PROHIBITED BY APPLICABLE LAW.
## 10. Trademarks
This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary attribution.
## 11. General Provisions
**11.1 Governing law and venue.** Adopted for alpha/beta 2026-07-29: disputes arising under this License shall be resolved by binding arbitration, seated at a neutral, arbitration-mature venue (Singapore or London are the two candidates concretely supported by current research), rather than by litigation in a national court. The specific arbitral institution and substantive governing law remain a per-deployment blank pending final selection; they are not fixed by this candidate. See the canonical repository's `history/260729-TRSL-Jurisdiction-Synthesis.md` §2.
**11.2 Severability.** If any provision of this License is held unenforceable, the remaining provisions remain in full force, and the unenforceable provision shall be reformed to the minimum extent necessary to make it enforceable.
**11.3 No waiver.** Failure to enforce any provision of this License is not a waiver of future enforcement of that or any other provision.
**11.4 Entire agreement (as to licensing).** This License, together with the applicable Phase Manifest and, where applicable, the Commercial Use Agreement, constitutes the entire agreement between You and the Licensor regarding the Software's licensing terms. Operations, service, and consulting arrangements are governed by separate agreements, if any, and are not part of this License.
**11.5 Definitions control.** Marketing materials, documentation, or other non-normative communications about the Software must not describe pre-Conversion-Event Software as "Open Source," "free software," or "open core." Pre-conversion Noncommercial Use is **source-available**; pre-conversion Commercial Use requires a **Commercial Entitlement**; only post-conversion Software may be described as Open Source, under the Future License.
---
**No Phase is currently declared for this repository under this License.** Until a Phase Manifest is published and registered with the Trust Service for a Milestone Release in this repository, Sections 2–7 above have no operative subject matter here — this License establishes the governing framework in advance of that declaration, consistent with the org-wide rollout decision recorded in `target-revenue`'s `workplans/TREV-WP-0008-governance-and-pilot-rollout.md`.

31
README.md
View file

@ -1,3 +1,30 @@
# prj-forgjo-org-refactor
# prj-forgejo-org-refactor
A migration to establish railiance, netkingdom, helixforge, binky, experimental as forgjo orgs next to coulomb with the relevant repos changing their org to better structure discoverability and responsibility.
A migration to establish `railiance`, `netkingdom`, `helixforge`, `binky` and
`experimental` as Forgejo orgs next to `coulomb`, with the relevant repos
changing their org to better structure discoverability and responsibility.
**Status: seeded, deliberately deferred.** The finding and its blast radius are
recorded; execution waits until the entry gate in `ORGREF-WP-0001` holds.
## Why this is a project and not a workplan
All 112 repos with a Forgejo origin currently sit under `coulomb/`. Renaming
touches Git remotes, ArgoCD `repoURL` sources, `Chart.yaml` metadata — and,
most dangerously, **container image paths**, because Forgejo's package registry
is org-scoped. That last one fails *deferred*: not at rename time, but at the
next pod reschedule.
## Start here
- [`GOAL.md`](GOAL.md) — outcome, invariants, blast radius, success gates
- [`SCOPE.md`](SCOPE.md) — authority, participating repos, what is out of scope
- [`AGENTS.md`](AGENTS.md) — session protocol
- [`history/2026-08-11-genesis.md`](history/2026-08-11-genesis.md) — why this exists
- [`workplans/ORGREF-WP-0001-foundation-and-entry-gate.md`](workplans/ORGREF-WP-0001-foundation-and-entry-gate.md) — foundation and entry gate
## Not this repo
Rapp context grouping and State Hub domains are **separate dimensions** by
ratified decision (`d07ee5f9`, OAS P1). Org membership is a stewardship
grouping; it does not determine what deploys together.

91
SCOPE.md Normal file
View file

@ -0,0 +1,91 @@
# SCOPE
> Lightweight orientation: what this project repo is for, and when it is not
> the right place to work.
---
## One-liner
Temporary coordination repo for splitting the single `coulomb/` Forgejo
organization into stewardship organizations without breaking GitOps, image
pulls, or clones.
---
## Project authority
This repo **coordinates**. It owns the inventory, the org taxonomy, the
sequencing, the rollback plan, and the evidence. It does **not** own the repos
being moved, and it hosts no production implementation.
Changes land in the repos that own them. This project links their work records
by ID; it does not duplicate their tasks.
---
## In Scope
- Inventory of every `coulomb/` reference across the fleet
- Target org taxonomy and the assignment criteria behind it
- Verification of Forgejo rename / transfer / redirect behavior, including the
package registry
- Migration sequencing, rollback plan, and cutover evidence
- Promotion of the durable org-assignment convention to a permanent home
---
## Out of Scope
- Rapp context grouping — a separate dimension by ratified decision
(`d07ee5f9`); see `railiance-platform/docs/rapp-platform-service-pattern.md`
- State Hub domain taxonomy — a separate dimension, owned by the-custodian
- Legal-entity structure and IP attribution — handled by `LICENSE`, copyright
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
---
## Participating repos
| Repo | Role |
| --- | --- |
| `railiance-forge` | Forgejo runtime owner — executes org/transfer operations |
| `railiance-platform` | ArgoCD Application sources, OpenBao lanes referencing repo URLs |
| `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 |
---
## Relevant When
- Planning or executing the Forgejo org split
- Deciding which org a **new** repo should be created in (until G7 promotes
that convention to a permanent home)
## Not Relevant When
- 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
---
## Work-record rule
Workplan files live in `workplans/` with prefix `ORGREF-WP-NNNN`. Child work in
participating repos keeps its own prefix and is linked by stable ID from this
project's workplans, never copied.
---
## Current State
- 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

76
history/2026-08-11-genesis.md Normal file
View file

@ -0,0 +1,76 @@
# Genesis — 2026-08-11
## How this project arose
It came out of a different question. A `railiance-platform` session was
reviewing the reef/rail/rapp repo family model and asking where **bounded rapp
contexts** should live. One candidate answer was: map them to Forgejo
organizations.
That answer was rejected, and the reasoning is what created this project.
## The rejected idea, and why
Binding rapp context to Forgejo orgs collapses two independent dimensions,
which OAS P1 (`canon/standards/orthogonal-architecture_v1.0.md`) forbids:
*architecture descriptions MUST separate independent perspectives into
orthogonal dimensions*.
The decisive argument was cardinality. A repo lives in exactly one Forgejo org
— it is a path segment in the clone URL, so org-to-repo is 1:many. But a repo
can legitimately contribute to more than one rapp, so rapp-to-repo is
many:many. A many:many grouping cannot be derived from a 1:many one.
Recorded as decision `d07ee5f9-90d6-4e04-85d7-772103bc95f0`.
## The finding that remained
Separating the dimensions did not make the org problem go away — it isolated
it. Once orgs were understood as a **stewardship** grouping answering "who may
push, what is discoverable together," the current state was plainly wrong: all
112 repos with a Forgejo origin sit under `coulomb/`, including `net-kingdom`,
`helix-forge`, and the entire `railiance-*` / `rail-*` / `rapp-*` / `reef-*`
families. An org containing everything draws no boundary.
The operator had already been considering this refactor independently, and had
been weighing whether orgs should instead map strictly to legal companies. That
was set aside for a reason worth preserving: legal attribution already has a
home in `LICENSE`, copyright headers, and contribution records
(`contribution-convention_v0.1`) — and those survive repo moves, where org
membership does not. So orgs can stay fluid without loosening legal rigor.
## Why a project repo rather than a workplan
A blast-radius check turned up three surfaces, one of which changed the
assessment:
1. **112 git remotes** — every clone and CI checkout.
2. **ArgoCD sources** — `repoURL: https://forgejo.coulomb.social/coulomb/<repo>.git`;
GitOps stops syncing on a 404.
3. **Container image paths** — `repository: forgejo.coulomb.social/coulomb/core-hub`.
Forgejo's package registry is **org-scoped**. A rename moves image paths for
pods that are *already running*, so the failure does not appear at rename
time; it appears at the next reschedule or restart.
The third is why "rename the org and fix the remotes" is unsafe, and why the
operator judged this deep enough to warrant its own project repo rather than a
workplan in someone else's.
## Deliberately deferred
Operator decision: seed now, execute later, once the surrounding structure is
stable enough that side-effect complications can be *tested for* rather than
discovered in production.
That condition is written into `ORGREF-WP-0001` as a four-part entry gate — the
family declaration validator running, deployable coverage known, a stable
re-runnable inventory, and a demonstrated rollback. The gate exists so the
decision to start is made against evidence rather than against a memory of this
conversation.
## Target orgs
`railiance`, `netkingdom`, `helixforge`, `binky`, `experimental`, alongside
`coulomb` for what genuinely belongs to it. `experimental` is flagged in T02 as
a lifecycle grouping rather than a stewardship one — a question to settle, not
a decision already made.

1
inventory/.gitkeep Normal file
View file

@ -0,0 +1 @@
Inventory outputs land here (ORGREF-WP-0001-T01). Empty until the inventory command exists.

143
workplans/ORGREF-WP-0001-foundation-and-entry-gate.md Normal file
View file

@ -0,0 +1,143 @@
---
id: ORGREF-WP-0001
type: workplan
title: "Foundation, blast-radius inventory, and execution entry gate"
domain: infotech
repo: prj-forgejo-org-refactor
status: backlog
owner: codex
topic_slug: railiance
created: "2026-08-11"
updated: "2026-08-11"
related_repos:
- railiance-forge
- railiance-platform
- railiance-apps
- railiance-master
---
# ORGREF-WP-0001 - Foundation, blast-radius inventory, and execution entry gate
## Status note
`backlog`, deliberately. Operator decision of 2026-08-11: seed the project now,
execute later, once the surrounding structure is stable enough that side-effect
complications can be tested for rather than discovered in production.
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.
## 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.
## 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: todo
priority: high
```
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
machine-readable inventory under `inventory/` plus a command that can be
re-run to verify clean at G6.
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: todo
priority: high
```
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.
```task
id: ORGREF-WP-0001-T03
status: wait
priority: high
```
Verify Forgejo's actual rename/transfer behavior against a throwaway org (G3),
for **both** the Git path and the package registry. 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
priority: high
```
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.
```task
id: ORGREF-WP-0001-T05
status: wait
priority: medium
```
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.
## Residuals
None yet — the project is seeded, not started.