kaizen-agentic/docs/PACKAGE_RELEASE.md

# Python Package Release

`kaizen-agentic` publishes as the `kaizen-agentic` Python package on the Forgejo
PyPI registry. Public [pypi.org](https://pypi.org/) distribution is optional
and not required for ecosystem use.

## Install (consumers)

Dependencies such as `pyyaml` resolve from public PyPI. Use Forgejo as an extra index:

```bash
pip install kaizen-agentic \
  --extra-index-url https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/
```

Global CLI via pipx:

```bash
pipx install kaizen-agentic \
  --pip-args="--extra-index-url https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/"
```

Consumer reads are anonymous. Keep publish credentials in Forgejo Actions secrets
or inject them through the environment for a deliberate local release.

## Local Release

Build and validate artifacts:

```bash
make package-check
```

Publish to the Coulomb organization registry:

```bash
TWINE_USERNAME=<forgejo-user> \
TWINE_PASSWORD=<package-token> \
make publish-forgejo
```

Package upload endpoint:

```text
https://forgejo.coulomb.social/api/packages/coulomb/pypi
```

Consumer simple index:

```text
https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/
```

## Forgejo repository secrets (one-time)

Configure in Forgejo: **Repository → Settings → Actions → Secrets** (or use
organization-level secrets when managed centrally).

| Secret | Value |
|--------|-------|
| `FORGEJO_PYPI_USER` | Forgejo username that owns the package token |
| `FORGEJO_PYPI_TOKEN` | Forgejo token with package-write permission |

Discover credential ownership before requesting or rotating a token:

```bash
warden route find "publish kaizen-agentic to Forgejo PyPI" --json
```

Never commit or copy the token into documentation, workplans, or State Hub.

The publish workflow fails at the upload step when either secret is missing or
invalid. Do not commit tokens to the repository.

**Verified (2026-08-20):** the Forgejo index serves `kaizen-agentic==1.4.0`.
A fresh virtual environment installed it with `--no-cache-dir` and the CLI reported
version `1.4.0`.

Verify secrets without cutting a release:

1. Open **Actions → Publish Python package → Run workflow** (`workflow_dispatch`),
   or dispatch via API:
   `POST /api/v1/repos/coulomb/kaizen-agentic/actions/workflows/publish-python-package.yml/dispatches`
   with body `{"ref":"main"}`
2. Confirm the run completes and `twine upload` succeeds
3. Optional: `pip install kaizen-agentic==<version> --extra-index-url ...`

The publish job uses an isolated `.build-venv` on the runner (PEP 668 safe).

## Pre-tag release checklist

Before `git tag vX.Y.Z && git push origin vX.Y.Z`:

- [ ] `make release-check` passes (tests, flake8, version consistency, agent parity)
- [ ] `make package-check` builds and validates `dist/*`
- [ ] `CHANGELOG.md` has a dated `[X.Y.Z]` section matching `pyproject.toml`
- [ ] `FORGEJO_PYPI_USER` and `FORGEJO_PYPI_TOKEN` secrets are set
- [ ] Publish workflow smoke-tested via `workflow_dispatch` (or prior tag release)
- [ ] `make agents-sync-package` run if `agents/` changed since last release

## Forgejo Actions Release

The `.forgejo/workflows/publish-python-package.yml` workflow publishes on tags
matching `v*`.

Example:

```bash
git tag v1.2.0
git push origin v1.2.0
```

## Public PyPI (optional)

When pypi.org credentials are configured (`~/.pypirc` or `TWINE_PASSWORD` API
token with `TWINE_USERNAME=__token__`):

```bash
make release-publish
python -m twine upload dist/*
```

## Scheduled-run runner prerequisites (WP-0006)

A runner that executes a scheduled kaizen agent task (fired by activity-core)
needs:

- **`kaizen-agentic` on PATH** — `pip install kaizen-agentic` (or `pipx install
  kaizen-agentic`) using the Forgejo PyPI extra index when installing from the
  internal registry:
  ```bash
  pip install kaizen-agentic \
    --extra-index-url https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/
  ```
- **Repo checkout reachable** at the `host_paths[<host>]` registered in State
  Hub, with a valid `.kaizen/schedule.yml` (`kaizen-agentic schedule validate`).
- **No State Hub required for `prepare`** — `schedule prepare` reads local
  `.kaizen/` state only. The hub is needed by the *resolver* (activity-core),
  not by the prepared session.

**Enabling a definition** (activity-core operator): keep the kaizen definitions
at `enabled: false` until a manual smoke test passes (see
[INTEGRATION_PATTERNS.md Pattern 2](INTEGRATION_PATTERNS.md) and the
[activity-core handoff checklist](integrations/activity-core-handoff-wp0006.md)),
then flip one definition to `enabled: true` in staging before fleet-wide enable.