kaizen-agentic/workplans/kaizen-agentic-WP-0010-forgejo-pypi-migration.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	depends_on	tasks
KAIZEN-WP-0010	workplan	Migrate package distribution from gitea to forgejo before CoulombCore retires	agents	kaizen-agentic	proposed	kaizen-agentic	custodian	2026-08-20	2026-08-20		id status title T01 todo Establish whether kaizen-agentic packages already exist on forgejo id status title T02 todo Publish current versions to the forgejo PyPI index id status title T03 todo Repoint Makefile and all six docs in one change id status title T04 todo Verify a clean install from forgejo on an uncached machine id status title T05 todo Retire the gitea variables and close out

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 appears to be the only repo in the estate that never migrated. The rest moved in early July — issue-core carries both endpoints (Makefile:68 gitea, Makefile:69 forgejo, publish targets at 240 and 250), and vergabe-teilnahme/pyproject.toml already points at forgejo.coulomb.social/api/packages/coulomb/pypi/simple/. So the destination exists and is in use; this repo was missed.

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

id: KAIZEN-WP-0010-T01
status: todo
priority: high

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.

Credentials: this needs a forgejo package token, not a gitea one. Route through warden plan "forgejo package publish token" rather than reusing GITEA_PACKAGE_TOKEN, and never paste a token into the Makefile or a doc.

id: KAIZEN-WP-0010-T02
status: todo
priority: high

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.

id: KAIZEN-WP-0010-T03
status: todo
priority: high

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.

id: KAIZEN-WP-0010-T04
status: todo
priority: high

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.

id: KAIZEN-WP-0010-T05
status: todo
priority: medium

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.

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.