---
id: AGENTIC-WP-0011
type: workplan
title: "Helix Forge ↔ kaizen-agentic correlation — doc links and session-close contract"
domain: helix_forge
repo: agentic-resources
status: ready
owner: codex
topic_slug: helix-forge
created: "2026-06-19"
updated: "2026-06-19"
---

# Helix Forge ↔ kaizen-agentic Correlation — Doc Links and Session-Close Contract

**Coordination trigger:** State Hub inbox from `kaizen-agentic` (2026-06-15) after
KAIZEN-WP-0004 — ADR-004 correlation layer is live on the project-metrics side.
This repo already has a partial link in `docs/DESIGN-session-memory.md` §11 (commit
`a66d502`). Remaining work is bidirectional surfacing, a session-close env-export
convention for agents using both layers, and a stable read-path for
`kaizen-agentic metrics correlate`.

**Boundary:** link-by-reference only — no ingestion or write path from kaizen-agentic
into Helix Forge. Authoritative cross-repo contract stays in kaizen-agentic:
`docs/integrations/helix-forge-correlation.md`.

## Bidirectional Doc Links and Stale Design Footer

```task
id: AGENTIC-WP-0011-T01
status: done
priority: high
```

Complete the bidirectional documentation surface requested by kaizen-agentic:

- Add a **Project metrics correlation** subsection to `docs/PRD-helix-forge.md`
  (ecosystem integration / downstream consumers) linking to DESIGN §11 and the
  kaizen contract doc.
- Add a short **Correlation with kaizen-agentic** section to
  `session_memory/README.md` (two-layer model, link to contract, no re-implementation).
- Remove or replace the stale DESIGN §11 footer (*"Next step: AGENTIC-WP-0002"*) —
  Phase 0–4 and retro are finished.

## Session-Close Env Export Convention

```task
id: AGENTIC-WP-0011-T02
status: done
priority: high
```

Document the recommended environment export at session close for agents that run
**both** Helix Forge capture and kaizen `metrics record`. Cover at minimum:

| Variable | Source (Helix Forge) | Purpose |
|----------|----------------------|---------|
| `HELIX_SESSION_UID` | `Session.session_uid` after digest write | Primary correlation key |
| `HELIX_REPO` | session `repo` field | Project/repo scoping |
| `HELIX_FLAVOR` | session `flavor` | Agent runtime (claude/codex/grok) |
| `HELIX_TOKENS` | `digest.cost` totals | Token rollup for project metrics |
| `HELIX_INFRA_OVERHEAD_SHARE` | MCP/tool histogram share | Infra overhead attribution |

Place in DESIGN §11 (canonical spec) and a concise operator note in
`session_memory/README.md`. Align field names with kaizen-agentic ADR-004 mapping
table — do not invent parallel names.

## Stable Digest Read Path for `metrics correlate`

```task
id: AGENTIC-WP-0011-T03
status: done
priority: medium
```

Give `kaizen-agentic metrics correlate <uid>` a stable, documented read convention
across hosts:

- Document `HELIX_STORE_DB` defaulting to `session_memory/.store/mem.db` (from
  `config.toml` `[store].db_path`, absolute path when exported).
- Document the existing `Store.get_digest(session_uid)` JSON shape consumers may
  rely on (outcome, cost, tool_histogram, repo, flavor, timestamps).
- Add a thin read entrypoint — e.g. `python -m session_memory.digest_lookup <uid>`
  or `python -m session_memory.store --digest <uid> --json` — that prints one
  digest without running a full ingest sweep. Unit-test the CLI; no new runtime
  dependencies.

After workplan updates, notify the operator to run from `~/state-hub`:

```bash
make fix-consistency REPO=agentic-resources
```

Mark the kaizen-agentic inbox message read once T01 is merged or the workplan is
filed (coordination ack).