feat: WP-0005 adoption polish — doc sync, fleet parity, CI lint

- Add make agents-sync-package and release-check parity gate - Add tests/test_packaged_agents_parity.py; sync packaged agents with agents/ - Update install docs (HELLO_WORLD, CLI_CHEAT_SHEET, AGENT_DISTRIBUTION) - Expand PACKAGE_RELEASE.md secrets setup and pre-tag checklist - Add flake8 to Gitea CI; CHANGELOG Unreleased for v1.2.0 - Expand INTEGRATION_PATTERNS activity-core handoff checklist
2026-06-16 02:26:13 +02:00
parent 4a7f5b2b7d
commit c004c3d4d7
44 changed files with 363 additions and 137 deletions
--- a/docs/AGENT_DISTRIBUTION.md
+++ b/docs/AGENT_DISTRIBUTION.md
@@ -13,13 +13,18 @@ The Kaizen Agentic framework provides a comprehensive system for distributing an

 ## Installation

-Install the Kaizen Agentic package:
+Install the Kaizen Agentic package from the Coulomb Gitea PyPI registry:

 ```bash
-pip install kaizen-agentic
+export GITEA_PACKAGE_USER=<gitea-user>
+export GITEA_PACKAGE_TOKEN=<package-token>
+
+pip install kaizen-agentic \
+  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
 ```

-This provides the `kaizen-agentic` CLI tool for managing agents.
+This provides the `kaizen-agentic` CLI tool for managing agents. See
+[PACKAGE_RELEASE.md](PACKAGE_RELEASE.md) for pipx, local builds, and publishing.

 ## CLI Commands

@@ -373,10 +378,7 @@ If you're currently managing agents manually:
   ls agents/agent-*.md
   ```

-2. **Install Package**:
-   ```bash
-   pip install kaizen-agentic
-   ```
+2. **Install Package** (same as Installation section above).

 3. **Validate Current Setup**:
   ```bash
@@ -412,4 +414,4 @@ When updating Kaizen Agentic versions:
   kaizen-agentic validate
   ```

-This distribution system makes it easy to share and maintain consistent development workflows across all your projects using specialized AI agents.
+This distribution system makes it easy to share and maintain consistent development workflows across all your projects using specialized AI agents.
--- a/docs/CLI_CHEAT_SHEET.md
+++ b/docs/CLI_CHEAT_SHEET.md
@@ -3,8 +3,15 @@
 Quick reference for the `kaizen-agentic` command-line tool.

 ## Installation
+
+From Coulomb Gitea PyPI (see [PACKAGE_RELEASE.md](PACKAGE_RELEASE.md)):
+
 ```bash
-pip install kaizen-agentic
+export GITEA_PACKAGE_USER=<gitea-user>
+export GITEA_PACKAGE_TOKEN=<package-token>
+
+pip install kaizen-agentic \
+  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
 ```

 ## Core Commands
@@ -125,7 +132,7 @@ kaizen-agentic status
 ```bash
 git clone team-repo
 cd team-repo
-pip install kaizen-agentic
+# Install CLI — see Installation section above
 kaizen-agentic status        # See what agents are used
 cat CLAUDE.md               # Read agent documentation
 ```
@@ -185,8 +192,7 @@ make agents-status    # Show detailed status

 ### Common Issues
 ```bash
-# Command not found
-pip install kaizen-agentic
+# Command not found — reinstall (see Installation section)

 # No agents directory
 kaizen-agentic install todo-keeper
@@ -227,4 +233,4 @@ kaizen-agentic update && kaizen-agentic validate
 ```bash
 kaizen-agentic status
 cat CLAUDE.md  # Detailed info
-```
+```
--- a/docs/HELLO_WORLD_TUTORIAL.md
+++ b/docs/HELLO_WORLD_TUTORIAL.md
@@ -9,10 +9,18 @@ This step-by-step tutorial will guide you through creating your first project wi

 ## Step 1: Install Kaizen Agentic

+From the Coulomb Gitea PyPI registry (dependencies resolve from public PyPI):
+
 ```bash
-pip install kaizen-agentic
+export GITEA_PACKAGE_USER=<gitea-user>
+export GITEA_PACKAGE_TOKEN=<package-token>
+
+pip install kaizen-agentic \
+  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
 ```

+See [PACKAGE_RELEASE.md](PACKAGE_RELEASE.md) for pipx and release details.
+
 Verify the installation:

 ```bash
@@ -235,7 +243,11 @@ kaizen-agentic status

 **"kaizen-agentic: command not found"**
 ```bash
-pip install kaizen-agentic
+# Same install as Step 1 (Gitea extra index — see PACKAGE_RELEASE.md)
+export GITEA_PACKAGE_USER=<gitea-user>
+export GITEA_PACKAGE_TOKEN=<package-token>
+pip install kaizen-agentic \
+  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
 ```

 **"make: command not found"**
@@ -267,4 +279,4 @@ make test
 - ✅ AI agents for development assistance
 - ✅ Make-based development commands

-You're now ready to build amazing Python projects with AI agent assistance! 🚀
+You're now ready to build amazing Python projects with AI agent assistance! 🚀
--- a/docs/INTEGRATION_PATTERNS.md
+++ b/docs/INTEGRATION_PATTERNS.md
@@ -39,12 +39,26 @@ invoke kaizen-agentic CLI commands.
 | [post-install-metrics-scaffold](integrations/activity-definitions/post-install-metrics-scaffold.md) | `kaizen.agent.installed` | `memory init` validation |
 | [low-success-rate-review](integrations/activity-definitions/low-success-rate-review.md) | `kaizen.metrics.recorded` | `metrics show` + `optimize` |

-**Activation:**
+**Activation handoff (activity-core owners):**

-1. Copy or symlink definitions from `docs/integrations/activity-definitions/` into
-   activity-core's `activity-definitions/` tree (or register as external ConfigMap).
-2. Run `make sync-activity-definitions` in activity-core.
-3. Enable definitions (`enabled: true`) after resolver wiring is verified.
+1. **Copy definitions** from kaizen-agentic:
+   `docs/integrations/activity-definitions/*.md` → activity-core
+   `activity-definitions/kaizen-agentic/` (or org-equivalent path per ACT-ADR-002).
+2. **Register in activity-core index** — ensure each definition slug appears in the
+   activity-core catalog consumed by the resolver.
+3. **Run sync** in activity-core: `make sync-activity-definitions` (or repo-equivalent).
+4. **Wire triggers** — map cron / NATS subjects (`kaizen.agent.installed`,
+   `kaizen.metrics.recorded`) to the documented CLI invocations.
+5. **Enable gradually** — set `enabled: true` per definition after a manual smoke test
+   against a repo with `.kaizen/metrics/` populated.
+6. **Verify credentials** — scheduled runs need `kaizen-agentic` on PATH and any
+   Gitea PyPI extra index if the runner installs from registry (see PACKAGE_RELEASE.md).
+
+**kaizen-agentic maintainer checklist:**
+
+- [ ] Three definition files committed under `docs/integrations/activity-definitions/`
+- [ ] activity-core PR or issue opened to register definitions
+- [ ] Smoke test commands documented below pass on a pilot repo

 **Smoke test (manual):**

@@ -102,4 +116,4 @@ No runtime dependency in WP-0004.
 | `HELIX_TOKENS`, `HELIX_INFRA_OVERHEAD_SHARE` | `metrics record` | Fleet cost fields |
 | `HELIX_STORE_DB` | `metrics correlate` | Digest lookup database |
 | `ARTIFACTSTORE_API_URL` | `metrics publish` | Registry endpoint |
-| `ARTIFACTSTORE_API_TOKEN` | `metrics publish` | Write auth bearer token |
+| `ARTIFACTSTORE_API_TOKEN` | `metrics publish` | Write auth bearer token |
--- a/docs/PACKAGE_RELEASE.md
+++ b/docs/PACKAGE_RELEASE.md
@@ -54,13 +54,39 @@ Consumer simple index:
 https://gitea.coulomb.social/api/packages/coulomb/pypi/simple/
 ```

+## Gitea repository secrets (one-time)
+
+Configure in Gitea: **Repository → Settings → Actions → Secrets**.
+
+| Secret | Value |
+|--------|-------|
+| `GITEA_PACKAGE_USER` | Gitea username with package upload permission (e.g. `tegwick`) |
+| `GITEA_PACKAGE_TOKEN` | Gitea API token with `write:package` scope |
+
+The publish workflow fails at the upload step when either secret is missing or
+invalid. Do not commit tokens to the repository.
+
+Verify secrets without cutting a release:
+
+1. Open **Actions → Publish Python package → Run workflow** (`workflow_dispatch`)
+2. Confirm the run completes and `twine upload` succeeds
+3. Optional: `pip install kaizen-agentic==<version> --extra-index-url ...`
+
+## 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`
+- [ ] `GITEA_PACKAGE_USER` and `GITEA_PACKAGE_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
+
 ## Gitea Actions Release

 The `.gitea/workflows/publish-python-package.yml` workflow publishes on tags
-matching `v*`. Configure these repository secrets before cutting a release:
-
- `GITEA_PACKAGE_USER`
- `GITEA_PACKAGE_TOKEN`
+matching `v*`.

 Example:

--- a/docs/integrations/helix-forge-correlation.md
+++ b/docs/integrations/helix-forge-correlation.md
@@ -93,11 +93,16 @@ documenting expected fields — no ingestion code runs in kaizen-agentic.
 | [DESIGN-session-memory.md](https://github.com/coulomb/agentic-resources/blob/main/docs/DESIGN-session-memory.md) | agentic-resources |
 | `session_memory/core/store.py` — `get_digest()` | agentic-resources |

-agentic-resources should link back to this document from its session-memory design
-notes when documenting downstream consumers of `session_uid`.
+**Reciprocal link status:** agentic-resources should link back to this document from
+its session-memory design notes. As of WP-0005, verify
+`agentic-resources/docs/DESIGN-session-memory.md` (or successor) cites this URL:
+
+`https://gitea.coulomb.social/coulomb/kaizen-agentic/src/branch/main/docs/integrations/helix-forge-correlation.md`
+
+Open a cross-repo issue if the link is missing.

 ## Non-goals

 - No Claude/Codex/Grok JSONL ingestion in kaizen-agentic
 - No write path to Helix Forge from kaizen-agentic CLI
- No merge of fleet baselines into project `summary.json` (Coach may cite both)
+- No merge of fleet baselines into project `summary.json` (Coach may cite both)