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.1 KiB

Raw Blame History

Helix Forge Correlation Contract

Cross-repo contract between kaizen-agentic (project metrics, ADR-004) and agentic-resources (Helix Forge fleet session metrics).

Purpose

Link a project-scoped agent execution record to the fleet session that produced it, without duplicating session JSONL ingestion in kaizen-agentic.

Layers

Layer	Owner	Storage
Project	kaizen-agentic	`.kaizen/metrics/<agent>/executions.jsonl`
Fleet	agentic-resources	Helix Forge digest store (`digests` table)

Correlation fields (ADR-004)

Optional on each project execution record:

{
  "helix_session_uid": "claude:17092961-…",
  "repo": "kaizen-agentic",
  "flavor": "claude",
  "tokens": 12500,
  "infra_overhead_share": 0.12
}

Field mapping

Helix Forge (`session_memory`)	ADR-004 project record
`Session.session_uid`	`helix_session_uid`
`Session.repo`	`repo`
`Session.flavor`	`flavor`
`digest.cost.input_tokens + output_tokens`	`tokens`
MCP tool share of `tool_histogram`	`infra_overhead_share`
`digest.outcome == "success"`	informs `success` at record time
`digest.cost.wall_clock_s`	complements `execution_time_s`

Population at session close

Automatic (environment)

When Helix Forge capture is active in the same shell session:

export HELIX_SESSION_UID="claude:17092961-…"
export HELIX_REPO="kaizen-agentic"
export HELIX_FLAVOR="claude"
export HELIX_TOKENS="12500"
export HELIX_INFRA_OVERHEAD_SHARE="0.12"

kaizen-agentic metrics record tdd-workflow --success --time 4200 --quality 0.9

metrics record merges env vars into the execution record before append.

Explicit (JSON)

echo '{
  "success": true,
  "execution_time_s": 4200,
  "quality_score": 0.9,
  "helix_session_uid": "claude:17092961-…",
  "repo": "kaizen-agentic",
  "flavor": "claude",
  "tokens": 12500,
  "infra_overhead_share": 0.12
}' | kaizen-agentic metrics record tdd-workflow --json

Fleet lookup (read-only)

export HELIX_STORE_DB=~/.helix-forge/store.db   # agentic-resources session store
kaizen-agentic metrics correlate claude:17092961-…

When HELIX_STORE_DB is unset, metrics correlate returns a stub response documenting expected fields — no ingestion code runs in kaizen-agentic.

Bidirectional references

Document	Repo
ADR-004	kaizen-agentic
wiki/EcosystemIntegration.md	kaizen-agentic
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.

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)

3.1 KiB Raw Blame History