Context-Lifecycle-Management-f-r-Agents/HANDOFF.md

HANDOFF — CLM (Context Lifecycle Management)

Feld	Wert
Stand	2026-08-06
Version	0.4.0a1
Branch	main
Content tip (must keep)	c5d495f — modularize for coding agents (runtime, agents, boundaries)
Docs tip	latest docs: refresh HANDOFF… on main (run git log -1 --oneline)
On origin	b7db73a — Live Progress v3 + Grok streaming-json
Remote	http://10.27.27.139:3000/admin/Context-Lifecycle-Management-f-r-Agents.git
Tracking	main 3 commits ahead of origin/main (push pending)
Status	Modularization must-wave done and committed. Working tree clean except untracked .clm/. Suite 248 passed.
Do not commit	.clm/ (runtime)

---

Goal

Automatisiertes Context Lifecycle Management für LLM-Agents: Outer Control Loop entscheidet CONTINUE / COMPACT / HANDOFF, hält Context kontrolliert (Verified Compaction), schreibt Memory und erzeugt auditierbare Handoff-Manifeste — framework-agnostisch.

On origin (b7db73a): P0–P4, pluggable agents I0–I6, Grok Build (json + streaming-json), Live Progress v3 + --goal-file.

Local (ahead, not pushed): same + package modularization for coding agents (clm.runtime, clm.agents, vendor-free session, loop describe_live_event injection, mirrored unit tests, import-boundary guard).

---

Package layout (after c5d495f)

Package	Role
clm.models	Shared DTOs / config
clm.session	Core only: Agent, capabilities, Working/Tracking session, pure factory registry
clm.agents + clm.agents.grok	Adapters: simulated, openai_compatible, grok/{agent,cli,stream} + register_builtin_agents
clm.runtime	Paths, session state I/O, build_config / parse_profile, load_script
clm.loop	OuterControlLoop + progress; no vendor Grok imports
clm.decision / compaction / handoff / memory / metrics	Unchanged domain pipelines
clm.experiments	A/B memory via runtime only (not CLI)
clm.cli	Presentation; re-exports runtime helpers; wires grok describe inject
Docs	AGENTS.md, docs/modules/*, architecture, coding-agents
Tests	tests/unit/<pkg>/, tests/support/, tests/integration/, architecture boundaries

Design

Composition root (CLI / library)
  import clm.agents                    → register_builtin_agents()
  build_agent(cfg, goal=…)             → clm.session.factory (pure registry)
  OuterControlLoop(
      …,
      describe_live_event=describe_stream_event  # grok-build only; injected
  )

clm.session      → models only
clm.agents       → models + session protocols
clm.runtime      → models only
clm.experiments  → runtime + loop stack; NOT cli
clm.loop         → session core/capabilities; NOT clm.agents.grok*

• Builtins: import clm.agents (or register_builtin_agents()) before build_agent.
• Live doing=: CLI injects clm.agents.grok.stream.describe_stream_event for grok-build.
• Boundaries: KNOWN_PACKAGE_VIOLATIONS and loop→vendor module violations are empty.
• Unit tests: pytest tests/unit/<pkg> -q (e.g. tests/unit/agents, tests/unit/loop).

Example progress (stream)

>>> clm run start session_id=… agent=grok-build soft=250000 hard=350000 max_steps=10
step=1/10 phase=agent activity=waiting_for_agent doing=starting agent subprocess …
status … activity=agent_streaming doing=tool read_file: src/App.tsx
status … activity=agent_streaming doing=plan: implement feature
step=1/10 phase=done … turns=… tools=… notes=…; stream=acp
<<< clm run end …

---

Next safe action

1. Baseline

cd /Volumes/SSD2TB/books/clm-agents
source .venv/bin/activate   # always .venv (system Python 3.9 breaks typing)
git status                  # expect clean except ?? .clm/
.venv/bin/pytest -q         # expect 248 passed

2. Push (optional — confirm if required)

git push origin main
# local: bf04e35 / c5d495f  →  origin currently at b7db73a

3. Optional product next steps

Option	Action
Live-Smoke	clm run --agent grok-build --goal "…" --cwd . --yolo --max-turns-per-step 16 --max-steps 30 --path .clm — watch doing=
Disable stream	--agent-option stream=false
Full ACP client	later: agent_kind=acp over grok agent stdio
Config file	.clm/config.toml for agent settings
Plan could-steps	Loop further split; runtime.build_outer_loop; CLI thin-up

Tuning (large tasks)

• Prefer higher --max-steps (CLM can compact between steps).
• Keep max-turns-per-step moderate (12–24), not 50–100.
• Start large: --max-turns-per-step 16 --max-steps 30.

---

Decisions (fixed)

Thema	Entscheidung
Agent pluggable	agent_kind + AgentSettings + build_agent; loop vendor-free
Adapters package	clm.agents (+ grok); session is core only
Builtin registration	Side effect of import clm.agents / register_builtin_agents()
Stream labels	Inject describe_live_event at composition root (not loop→grok)
Composition helpers	clm.runtime; experiments must not import CLI
First live adapter	grok-build
Default agent	simulated + --script
External session	ExternalSessionCapable + external_session_id
Live mid-step	LiveEventCapable + Grok streaming-json (ACP-shaped NDJSON)
Compact	CLM pipeline + inject_context (not Grok /compact)
Handoff	Manifest + unbind external + seed
Completion	CLM_TASK_STATUS: completed / failed in agent text
YOLO	Opt-in
CI	Fake runners only; no live grok
Goal input	--goal or --goal-file
Thresholds	coding soft/hard 250k / 350k (mid-band)
Full ACP JSON-RPC client	later (Phase B registry kind)

CLI contract

# Offline
clm run --agent simulated --script tests/fixtures/sample_transcript.json --goal "…"

# Grok Build (stream on by default)
clm run --agent grok-build --goal "…" --cwd . --profile coding --yolo \
  --model grok-build --max-turns-per-step 16 --max-steps 30 --path .clm

# Stream off
clm run --agent grok-build --goal "…" --agent-option stream=false --cwd . --yolo

# Progress
clm run … --quiet
clm run --goal-file ./goal.md --script tests/fixtures/sample_transcript.json

Library note

import clm.agents  # registers simulated + grok-build
from clm.session.factory import build_agent
from clm.models.config import ClmConfig

---

Source of truth

Artefakt	Pfad
Agent task map	AGENTS.md
Module pages	docs/modules/
Coding agents + stream	docs/coding-agents.md
Architecture	docs/architecture.md
Design P0–P4	docs/superpowers/specs/2026-08-04-clm-design.md
Progress	src/clm/loop/progress.py
Outer loop	src/clm/loop/control.py
Stream parse	src/clm/agents/grok/stream.py
Grok runner / agent	src/clm/agents/grok/cli.py, agent.py
Builtin registration	src/clm/agents/register.py
Session core	src/clm/session/
Runtime helpers	src/clm/runtime/
Config	src/clm/models/config.py
Import boundaries	tests/unit/architecture/test_import_boundaries.py
SDD scratch	.superpowers/sdd/agent-modularization/

---

Done

On origin (through b7db73a)

• P0–P4
• Pluggable agents I0–I6 + Grok Build (json)
• Live Progress v2 + --goal-file + --quiet
• Live Progress v3 + Grok streaming-json live events
• Thresholds coding 250k / 350k

Local (committed, not pushed — content c5d495f + HANDOFF docs tips)

• clm.runtime; experiments → runtime (not cli)
• clm.agents + clm.agents.grok; session vendor-free
• OuterControlLoop describe_live_event injection
• AGENTS.md + docs/modules/*
• tests/support fakes + import boundary guard (known violations empty)
• Unit tests mirrored under tests/unit/<pkg>/
• Full suite 248 passed
• Commits: c5d495f (code) + subsequent HANDOFF doc commits on main

---

Verified

.venv/bin/python -c "import clm; print(clm.__version__)"
# 0.4.0a1

.venv/bin/pytest -q
# 248 passed

.venv/bin/pytest -q tests/unit/architecture/test_import_boundaries.py
# green; known violation allowlists empty

Not verified / out of scope

• Push of modularization commits to origin
• Live Grok headless smoke over CLM (manual)
• Full ACP client (grok agent stdio/WebSocket)
• Live Mem0 / OpenAI; Auto-Apply Calibrate
• .clm/config.toml

---

Assumptions & risks

Thema	Hinweis
Dual session IDs	CLM .clm/sessions/<id> ≠ Grok ~/.grok/sessions/<uuid>
Grok auto-compact ~85%	Can race CLM COMPACT
Stream quality	Depends on Grok emitting tool/plan/thought lines
Permissions	Headless still needs --yolo (not ACP request_permission)
Registry global	Snapshot/restore in tests; builtins need import clm.agents
Alpha hard move	Old clm.session.grok_* / simulated import paths removed (no shims)

---

Blockers

None. Ready to push when desired. Optional product work: live smoke, ACP, config.toml.

---

Quick resume checklist

• Origin baseline Progress v3 + streaming (b7db73a)
• Modularization must-wave (c5d495f) + HANDOFF docs tips
• 248 tests green; boundaries clean
• git push origin main
• Optional live smoke grok-build
• Not: .clm/ in git; live grok in CI; full ACP yet

---

Einstieg nächste Session

Repo: /Volumes/SSD2TB/books/clm-agents
Branch: main (3 ahead of origin/main @ b7db73a); content c5d495f
HANDOFF.md — Stand 2026-08-06; 248 tests green
Confirm tip: git log -1 --oneline

Layout: clm.runtime | clm.agents(+grok) | session core | loop inject
Tests: tests/unit/<pkg>/  |  boundaries empty
Library: import clm.agents before build_agent

Next:
  1) git push origin main (if desired)
  2) Optional live smoke: clm run --agent grok-build …
  3) Later: full ACP client; config.toml

Always: .venv/bin/python | .venv/bin/pytest
Do not stage: .clm/