codex
bca478df73
These workplans carried random pre-ADR-007 identifiers minted by the retired local hub. Central never held them, so C-06 refused them as stale references — which also blocked minting for every other workplan in the repo. Deriving the identifier from the canonical record id (ADR-007 decision 2) takes no identity from anything: the records do not exist on central and the old ids live only in the dying cache. Refs CUST-WP-0068-T06 Assistant: claude-code Assistant-Model: opus Assistant-Process: 2583210@bnt-lap001 Assistant-Session: f2bff2d5-e9b2-4338-92ca-10282a927006
192 lines
7.7 KiB
Markdown
192 lines
7.7 KiB
Markdown
---
|
||
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.
|