generated from coulomb/repo-seed
tegwick
01d2affc3b
Add bidirectional doc links (PRD §9.1, README, DESIGN §11), session-close HELIX_* env convention, stable digest JSON contract, and digest_lookup CLI for read-only correlate lookups. All tasks done; 163 tests green.
95 lines
3.5 KiB
Markdown
95 lines
3.5 KiB
Markdown
---
|
||
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). |