--- id: KAIZEN-WP-0010 type: workplan title: "Migrate package distribution from gitea to forgejo before CoulombCore retires" domain: agents repo: kaizen-agentic status: finished owner: kaizen-agentic topic_slug: custodian created: "2026-08-20" updated: "2026-08-20" depends_on: [] tasks: - id: T01 status: done title: Establish whether kaizen-agentic packages already exist on forgejo - id: T02 status: done title: Publish current versions to the forgejo PyPI index - id: T03 status: done title: Repoint Makefile and all six docs in one change - id: T04 status: done title: Verify a clean install from forgejo on an uncached machine - id: T05 status: done title: Retire the gitea variables and close out state_hub_workstream_id: "ade14e03-98d8-5d0b-88d7-f7774114f050" --- # KAIZEN-WP-0010 — Migrate package distribution to forgejo **Deadline: 2026-08-31.** Not a target — CoulombCore is being decommissioned by the operator on that date. ## Why this exists `gitea.coulomb.social` runs on CoulombCore and serves two things: a container registry and a **PyPI package index** at `/api/packages/coulomb/pypi`. Both stop existing when the host does. kaizen-agentic's release workflow moved to Forgejo in early July, but the Makefile, consumer documentation, issue links, templates, and capability metadata did not move with it. This left a split-brain distribution story even though the destination already existed and was in use. ### What breaks, and why it is worse than a broken link ``` Makefile:10 GITEA_PYPI_REPOSITORY_URL ?= https://gitea.coulomb.social/api/packages/$(GITEA_PACKAGE_OWNER)/pypi Makefile:11 GITEA_PYPI_SIMPLE_URL ?= https://gitea.coulomb.social/api/packages/$(GITEA_PACKAGE_OWNER)/pypi/simple/ ``` and the install instructions in **six** documents — `README.md`, `docs/GETTING_STARTED.md`, `docs/AGENT_DISTRIBUTION.md`, `docs/PACKAGE_RELEASE.md`, `docs/HELLO_WORLD_TUTORIAL.md`, `docs/CLI_CHEAT_SHEET.md` — all tell users to `pip install --extra-index-url …@gitea.coulomb.social/api/packages/coulomb/pypi/simple/`. These are the documented install instructions for the kaizen agent distribution. After 2026-08-31 every one fails, and it fails *looking like a broken package* rather than a retired host — so the person hitting it will debug the wrong thing. ## The one rule for sequencing **Publish before you repoint.** A registry migration is not a find-and-replace. If the docs change first, they point at a 404 instead of a soon-to-be-404, which is strictly worse: today's instructions at least work. T01 and T02 come before T03, and T03 is a single change covering the Makefile and all six documents together — a half-migrated doc set is how the next repo gets missed. ## Tasks ```task id: KAIZEN-WP-0010-T01 status: done priority: high state_hub_task_id: "63acba1a-f8e5-584d-9a85-b5e599e23681" ``` **Establish whether kaizen-agentic packages already exist on forgejo.** Check `forgejo.coulomb.social/api/packages/coulomb/pypi` for current package names and versions. This is a read; do not publish yet. Record what is there against what gitea holds. If forgejo already has current versions, T02 becomes a no-op and this finishes much faster than feared — worth five minutes before assuming a full republication. **Result (2026-08-20):** Forgejo anonymously serves the current `1.4.0` wheel and sdist. Gitea serves `1.1.0`, `1.2.0`, and `1.4.0`. The repository version and latest tag are both `1.4.0`. The simple package index is anonymously readable. If a write or authenticated API inventory is ever needed, route the Forgejo credential through `warden` and never paste a token into the Makefile or documentation. ```task id: KAIZEN-WP-0010-T02 status: done priority: high state_hub_task_id: "51ef8a2f-880e-5c93-ac88-c2468453f391" ``` **Publish current versions to the forgejo PyPI index.** Only the versions that matter — whatever the docs tell users to install, plus the current release. Historical versions are a judgement call: republish them only if something actually pins an old version. `issue-core/Makefile:250` is a working example of the forgejo `twine upload` target and is the shortest path to a correct invocation. **Result (2026-08-20):** No-op. The current `1.4.0` release was already on Forgejo, published by `.forgejo/workflows/publish-python-package.yml`; no credential request or duplicate upload was necessary. ```task id: KAIZEN-WP-0010-T03 status: done priority: high state_hub_task_id: "db50966e-1f3b-5fc0-ad8f-ea55f9b2f881" ``` **Repoint the Makefile and all six docs in one change.** Add `FORGEJO_PYPI_REPOSITORY_URL` / `FORGEJO_PYPI_SIMPLE_URL` and make them the default path, then update every install instruction listed above. Decide deliberately whether to keep the gitea variables temporarily for comparison or delete them now. `issue-core` kept both and now carries a legacy target that fails after 08-31 — a trap for whoever runs the wrong `make`. Given the deadline is nine days after this workplan is written, deleting outright is probably the better call here, but make it a decision rather than a default. Also update `GITEA_PACKAGE_USER` / `GITEA_PACKAGE_TOKEN` variable *names* if you keep the credential envelope — a variable called `GITEA_*` pointing at forgejo is the kind of thing that survives for years and confuses everyone who reads it. **Result (2026-08-20):** Removed the Gitea Make variables and target outright; `publish-forgejo` and `FORGEJO_PYPI_*` are the only release path. Consumer instructions now use the anonymously readable Forgejo index without embedding unnecessary credentials. Updated the six named documents plus operational references in contributing/scope/capability metadata, CLI feedback URLs, issue templates, project metadata, and packaged agent guidance. ```task id: KAIZEN-WP-0010-T04 status: done priority: high state_hub_task_id: "2db93b97-62c6-539b-b0a1-471dd0767014" ``` **Verify a clean install from forgejo on a machine with no cache.** A `pip install` that succeeds because the wheel is already in a local cache proves nothing. Use a fresh venv and `--no-cache-dir`, following the README's own instructions verbatim — if the documented command does not work, the docs are still wrong regardless of what the registry holds. This is the task that actually closes the risk. T01–T03 are preparation. **Result (2026-08-20):** A new temporary virtual environment installed `kaizen-agentic==1.4.0` with `--no-cache-dir` and the documented anonymous Forgejo extra index. Pip downloaded the wheel from Forgejo; both the CLI and Python package reported `1.4.0`. ```task id: KAIZEN-WP-0010-T05 status: done priority: medium state_hub_task_id: "36e9d767-c4f9-57f2-9be4-8e474d8aab11" ``` **Close out.** Remove any remaining gitea references from operational files (`Makefile`, docs, CI). Leave alone anything that merely *records* that gitea existed — history stays true after the host is switched off, and rewriting it to tidy a grep loses information. Tell `prj-state-hub-retirement` when T04 passes; this is tracked there as `SHR-WP-0002-T07` and is one of two items gating CoulombCore's retirement. **Result (2026-08-20):** No CoulombCore/Gitea host, package variable, publish target, workflow path, or issue-template path remains in operational files. Historical workplans and changelog entries were deliberately preserved. ## Notes - Drafted by `prj-state-hub-retirement` on 2026-08-20 from the estate-wide sweep that found this repo. The sequencing rule and the deadline are ours; **the packaging decisions are yours** — nothing here has been applied to your files. - If any of this is wrong about how kaizen-agentic actually publishes, trust your own knowledge and tell the project. The sweep read your Makefile and docs; it did not run your release process.