Files

tegwick b48a2102d7 WP-0004: ecosystem integration complete

Add Helix Forge correlation (HELIX_SESSION_UID env, metrics correlate),
artifact-store publish (metrics publish), activity-core ActivityDefinition
references, integration patterns docs, and canon/knowledge design artifacts.

2026-06-16 01:53:01 +02:00

3.9 KiB

Raw Blame History

Integration Patterns

How kaizen-agentic composes with ecosystem repos by contract — no merged codebases, no duplicated capabilities.

Reference: wiki/EcosystemIntegration.md, KAIZEN-WP-0004.

Pattern 1 — Helix Forge correlation (agentic-resources)

Problem: Project metrics and fleet session metrics answer different questions.

Contract: Optional helix_session_uid on ADR-004 execution records.

kaizen-agentic	agentic-resources
`metrics record` at session close	Helix capture → digest store
`metrics correlate <uid>` read-only lookup	`Store.get_digest(session_uid)`
`HELIX_SESSION_UID` env auto-merge	`Session.session_uid`

Docs: integrations/helix-forge-correlation.md

Boundary: kaizen-agentic does not ingest session JSONL.

Pattern 2 — activity-core triggers

Problem: Recurring kaizen checks need scheduling without custom cron in this repo.

Contract: ActivityDefinition markdown files declare triggers + actions that invoke kaizen-agentic CLI commands.

Definition	Trigger	CLI command
weekly-metrics-optimize	Cron Mon 08:00	`metrics optimize`
post-install-metrics-scaffold	`kaizen.agent.installed`	`memory init` validation
low-success-rate-review	`kaizen.metrics.recorded`	`metrics show` + `optimize`

Activation:

Copy or symlink definitions from docs/integrations/activity-definitions/ into activity-core's activity-definitions/ tree (or register as external ConfigMap).
Run make sync-activity-definitions in activity-core.
Enable definitions (enabled: true) after resolver wiring is verified.

Smoke test (manual):

# Against a repo with populated metrics
cd /path/to/project-with-kaizen
kaizen-agentic metrics list
kaizen-agentic metrics optimize
# Verify analysis.json written
test -f .kaizen/metrics/optimizer/analysis.json && echo OK

Boundary: kaizen-agentic does not run Temporal schedules.

Pattern 3 — artifact-store evidence retention

Problem: Optimizer outputs need durable, attributable retention beyond local disk.

Contract: metrics publish registers analysis.json + recommendations.jsonl as an artifact package with retention_class: raw-evidence.

export ARTIFACTSTORE_API_URL=http://127.0.0.1:8000
export ARTIFACTSTORE_API_TOKEN=<token>
kaizen-agentic metrics optimize
kaizen-agentic metrics publish --target .

Manifest: integrations/optimizer-artifact-manifest.md

Boundary: Publish is optional; local .kaizen/metrics/optimizer/ remains canonical.

Pattern 4 — Canon and knowledge (stretch)

Design-only paths for info-tech-canon and kontextual-engine:

No runtime dependency in WP-0004.

Environment variables

Variable	Used by	Purpose
`HELIX_SESSION_UID`	`metrics record`	Fleet session correlation
`HELIX_REPO`, `HELIX_FLAVOR`	`metrics record`	Session context
`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

3.9 KiB Raw Blame History