tegwick
5ce3d0766e
Update correlation contract status and close T16 in the adoption-parity workplan after agentic-resources DESIGN-session-memory.md §11 landed.
104 lines
3.1 KiB
Markdown
104 lines
3.1 KiB
Markdown
# 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)
|