From 292b6569527a47dad60650b75631b6fa2b665293 Mon Sep 17 00:00:00 2001
From: tegwick <bernd.worsch@gmail.com>
Date: Fri, 19 Jun 2026 20:24:39 +0200
Subject: [PATCH] workplan: AGENTIC-WP-0011 kaizen correlation follow-up

File ready workplan for bidirectional doc links, session-close env export
convention, and stable digest read path per kaizen-agentic coordination.
---
 ...TIC-WP-0011-kaizen-correlation-followup.md | 95 +++++++++++++++++++
 1 file changed, 95 insertions(+)
 create mode 100644 workplans/AGENTIC-WP-0011-kaizen-correlation-followup.md

diff --git a/workplans/AGENTIC-WP-0011-kaizen-correlation-followup.md b/workplans/AGENTIC-WP-0011-kaizen-correlation-followup.md
new file mode 100644
index 0000000..15572b7
--- /dev/null
+++ b/workplans/AGENTIC-WP-0011-kaizen-correlation-followup.md
@@ -0,0 +1,95 @@
+---
+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: todo
+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: todo
+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: todo
+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).
\ No newline at end of file