Add KAIZEN-WP-0010 — migrate package distribution to forgejo before 2026-08-31

Drafted by prj-state-hub-retirement from the estate-wide gitea sweep.
kaizen-agentic appears to be the only repo that never migrated off the gitea
PyPI index, which dies with CoulombCore on 2026-08-31. The Makefile publishes
there and six documents instruct users to install from it.

The workplan's one structural rule is publish-before-repoint: changing the docs
first points users at a 404 instead of a soon-to-be-404, and today's
instructions at least work.

Proposed and unapplied — the packaging decisions belong to this repo.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

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

@@ -0,0 +1,164 @@
+---
+id: KAIZEN-WP-0010
+type: workplan
+title: "Migrate package distribution from gitea to forgejo before CoulombCore retires"
+domain: agents
+repo: kaizen-agentic
+status: proposed
+owner: kaizen-agentic
+topic_slug: custodian
+created: "2026-08-20"
+updated: "2026-08-20"
+depends_on: []
+tasks:
+  - id: T01
+    status: todo
+    title: Establish whether kaizen-agentic packages already exist on forgejo
+  - id: T02
+    status: todo
+    title: Publish current versions to the forgejo PyPI index
+  - id: T03
+    status: todo
+    title: Repoint Makefile and all six docs in one change
+  - id: T04
+    status: todo
+    title: Verify a clean install from forgejo on an uncached machine
+  - id: T05
+    status: todo
+    title: 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
+
+```task
+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.
+
+```task
+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.
+
+```task
+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.
+
+```task
+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.
+
+```task
+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.