# 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:

```json
{
  "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:

```bash
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)

```bash
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)

```bash
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](../adr/ADR-004-project-metrics-convention.md) | kaizen-agentic |
| [wiki/EcosystemIntegration.md](../../wiki/EcosystemIntegration.md) | 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 |

**Reciprocal link status:** verified (WP-0005 T16). `agentic-resources/docs/DESIGN-session-memory.md`
§11 cites this document and ADR-004.

## 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)