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

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

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.

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.

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.

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.

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.