2026-06-19 20:24:39 +02:00
|
|
|
|
---
|
|
|
|
|
|
id: AGENTIC-WP-0011
|
|
|
|
|
|
type: workplan
|
|
|
|
|
|
title: "Helix Forge ↔ kaizen-agentic correlation — doc links and session-close contract"
|
|
|
|
|
|
domain: helix_forge
|
|
|
|
|
|
repo: agentic-resources
|
2026-06-21 16:09:34 +02:00
|
|
|
|
status: finished
|
2026-06-19 20:24:39 +02:00
|
|
|
|
owner: codex
|
|
|
|
|
|
topic_slug: helix-forge
|
|
|
|
|
|
created: "2026-06-19"
|
2026-06-21 16:09:34 +02:00
|
|
|
|
updated: "2026-06-21"
|
|
|
|
|
|
state_hub_workstream_id: "a689a145-645d-4ed4-a16c-00b75263a2c4"
|
2026-06-19 20:24:39 +02:00
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
# 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
|
2026-06-19 20:27:00 +02:00
|
|
|
|
status: done
|
2026-06-19 20:24:39 +02:00
|
|
|
|
priority: high
|
2026-06-21 16:09:34 +02:00
|
|
|
|
state_hub_task_id: "616ec197-58ce-4de0-bb7b-1c4a3f9a1e24"
|
2026-06-19 20:24:39 +02:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
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
|
2026-06-19 20:27:00 +02:00
|
|
|
|
status: done
|
2026-06-19 20:24:39 +02:00
|
|
|
|
priority: high
|
2026-06-21 16:09:34 +02:00
|
|
|
|
state_hub_task_id: "1c20d5fa-83c2-46c7-b21e-be1ea241bae6"
|
2026-06-19 20:24:39 +02:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
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
|
2026-06-19 20:27:00 +02:00
|
|
|
|
status: done
|
2026-06-19 20:24:39 +02:00
|
|
|
|
priority: medium
|
2026-06-21 16:09:34 +02:00
|
|
|
|
state_hub_task_id: "80e35324-d46e-4737-88e7-0316088e7ace"
|
2026-06-19 20:24:39 +02:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
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).
|
