admin/Context-Lifecycle-Management-f-r-Agents
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: refresh HANDOFF for modularization tip and push-pending state

Browse Source 
Align HEAD, ahead count, package map, next actions, and checklists with
local commits c5d495f/bf04e35 and a clean working tree.
This commit is contained in:
grok-bot committed 2026-08-06 17:29:53 +02:00
1 parent bf04e35cb7
commit f2f94782f8
1 file changed
+85 -85
Download Patch File Download Diff File Expand all files Collapse all files
HANDOFF.md
+85 -85
View File
@@ -5,11 +5,13 @@
| **Stand** | 2026-08-06 |
| **Version** | `0.4.0a1` |
| **Branch** | `main` |
| **HEAD (local)** | `c5d495f` — modularize for coding agents (runtime, agents, boundaries) |
| **Content on origin** | `b7db73a` — Live Progress v3 + streaming (local is **1 commit ahead**) |
| **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` → `origin/main` (push pending) |
| **Status** | Modularization **must-wave committed** (`c5d495f`). Suite **248 passed**. Optional: push, live smoke, full ACP, `.clm/config.toml`. Do **not** stage `.clm/`. |
| **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) |
---
@@ -17,50 +19,51 @@
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:** P0–P4, pluggable agents I0–I6, Grok Build (json + streaming-json), Live Progress **v3** + `--goal-file` (`b7db73a`).
**On origin (`b7db73a`):** P0–P4, pluggable agents I0–I6, Grok Build (json + streaming-json), Live Progress **v3** + `--goal-file`.
**Local (ahead, modularization):** session vendor-free; adapters under `clm.agents`; composition under `clm.runtime`; loop free of grok imports via `describe_live_event` injection.
**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 (committed in `c5d495f`)
### Package layout (must-wave)
## 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.agents` + `clm.agents.grok` | Vendor adapters: `simulated`, `openai_compatible`, `grok/{agent,cli,stream}` + `register_builtin_agents` |
| `clm.session` | Vendor-free core: `Agent`, capabilities, `WorkingSession` / tracking, pure factory registry |
| `clm.loop` | `OuterControlLoop` + progress; **no** vendor Grok imports |
| `clm.experiments` | A/B memory uses `clm.runtime` only (**not** `clm.cli`) |
| Docs | `AGENTS.md`, `docs/modules/*` (incl. `agents.md`, `runtime.md`), architecture / coding-agents |
| Tests | `tests/support` fakes; unit tree under `tests/unit/<domain>/` (concurrent reorg); import-boundary guard; suite ~248 passed |
| `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 (modularization)
### Design
```text
Composition root (CLI / library)
import clm.agents → register_builtin_agents()
build_agent(cfg, goal=…) → pure registry in clm.session.factory
import clm.agents → register_builtin_agents()
build_agent(cfg, goal=…) → clm.session.factory (pure registry)
OuterControlLoop(
…,
describe_live_event=describe_stream_event # only for grok-build; injected
describe_live_event=describe_stream_event # grok-build only; injected
)
clm.session → models only (no agents)
clm.agents → models + session protocols
clm.runtime → models only
clm.experiments → runtime (+ loop stack); NOT cli
clm.loop → Agent + capabilities; NOT clm.agents.grok*
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 wires `clm.agents.grok.stream.describe_stream_event` into loop.
- **Import boundaries:** `KNOWN_PACKAGE_VIOLATIONS` and loop vendor module violations **empty**.
- **Do not commit:** `.clm/` runtime.
- **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 — already on origin baseline)
### Example progress (stream)
```text
>>> clm run start session_id=… agent=grok-build soft=250000 hard=350000 max_steps=10
@@ -80,33 +83,26 @@ step=1/10 phase=done … turns=… tools=… notes=…; stream=acp
```bash
cd /Volumes/SSD2TB/books/clm-agents
source .venv/bin/activate # always .venv (system Python 3.9 breaks typing)
git status
.venv/bin/pytest -q # expect ~248 passed (may drift during concurrent test reorg)
git status # expect clean except ?? .clm/
.venv/bin/pytest -q # expect 248 passed
```
### 2. Commit modularization (when ready)
Logical slices (do **not** stage `.clm/`):
### 2. Push (optional — confirm if required)
```bash
# runtime + experiments inversion
# agents package + session harden
# loop describe_live_event injection
# docs (AGENTS.md, docs/modules/*, architecture, coding-agents, HANDOFF)
# tests/support + import boundaries
git push origin main
# local: bf04e35 / c5d495f → origin currently at b7db73a
```
Prefer architecture-level commit messages over brittle test-path lists (test tree may still be moving).
### 3. After commit (optional)
### 3. Optional product next steps
| Option | Action |
|--------|--------|
| Push | `git push origin main` (confirm with user if required) |
| 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)
@@ -121,13 +117,14 @@ Prefer architecture-level commit messages over brittle test-path lists (test tre
| 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) |
| Stream labels | Inject `describe_live_event` at composition root (not loop→grok import) |
| Adapters package | `clm.agents` (+ `clm.agents.grok`); session is core only |
| Composition helpers | `clm.runtime`; experiments must not import CLI |
| Compact | CLM pipeline + `inject_context` (not Grok `/compact`) |
| Handoff | Manifest + unbind external + seed |
| Completion | `CLM_TASK_STATUS: completed` / `failed` in agent text |
@@ -155,27 +152,35 @@ clm run … --quiet
clm run --goal-file ./goal.md --script tests/fixtures/sample_transcript.json
```
### Library note
```python
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` |
| Module map / boundaries | `AGENTS.md`, `docs/modules/` |
| Design P0–P4 | `docs/superpowers/specs/2026-08-04-clm-design.md` |
| Agents plan | `docs/superpowers/plans/2026-08-05-configurable-coding-agents.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/` (protocol, capabilities, factory registry, working/tracking) |
| Session core | `src/clm/session/` |
| Runtime helpers | `src/clm/runtime/` |
| Capabilities | `src/clm/session/capabilities.py` |
| Config | `src/clm/models/config.py` |
| Modularization SDD | `.superpowers/sdd/agent-modularization/` |
| Import boundaries | `tests/unit/architecture/test_import_boundaries.py` |
| SDD scratch | `.superpowers/sdd/agent-modularization/` |
---
@@ -186,20 +191,19 @@ clm run --goal-file ./goal.md --script tests/fixtures/sample_transcript.json
- [x] P0–P4
- [x] Pluggable agents I0–I6 + Grok Build (json)
- [x] Live Progress **v2** + `--goal-file` + `--quiet`
- [x] Live Progress **v3** (run-state, workspace `doing=`, one-line STATUS)
- [x] `LiveEventCapable` + Grok `streaming-json` live events
- [x] Threshold experiment reverted (coding 250k/350k)
- [x] Live Progress **v3** + Grok `streaming-json` live events
- [x] Thresholds coding 250k / 350k
### Local modularization (uncommitted; must-wave largely done)
### Local (committed, not pushed — content `c5d495f` + HANDOFF docs tips)
- [x] `clm.runtime` (paths, script_loader, config_build); experiments → runtime not cli
- [x] `clm.agents` + `clm.agents.grok`; adapters moved out of session
- [x] Session core vendor-free; pure factory registry
- [x] OuterControlLoop `describe_live_event` injection (no grok import in loop)
- [x] `AGENTS.md` + `docs/modules/*` (agents, runtime, …)
- [x] `tests/support` fakes + import boundary tests
- [x] Known package / loop-vendor violations **empty**
- [x] Suite ~**248 passed** (confirm with `.venv/bin/pytest -q`; concurrent test reorg may shift paths/counts)
- [x] `clm.runtime`; experiments → runtime (not cli)
- [x] `clm.agents` + `clm.agents.grok`; session vendor-free
- [x] OuterControlLoop `describe_live_event` injection
- [x] `AGENTS.md` + `docs/modules/*`
- [x] `tests/support` fakes + import boundary guard (known violations empty)
- [x] Unit tests mirrored under `tests/unit/<pkg>/`
- [x] Full suite **248 passed**
- [x] Commits: `c5d495f` (code) + subsequent HANDOFF doc commits on `main`
---
@@ -210,19 +214,19 @@ clm run --goal-file ./goal.md --script tests/fixtures/sample_transcript.json
# 0.4.0a1
.venv/bin/pytest -q
# ~248 passed (see modularization task reports; re-run after concurrent test moves)
# 248 passed
# Import boundaries (architecture guard)
.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`
- Commit + push of local modularization work
---
@@ -233,28 +237,24 @@ clm run --goal-file ./goal.md --script tests/fixtures/sample_transcript.json
| 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` / permission mode (not ACP request_permission) |
| Registry global | Tests must snapshot/restore `_REGISTRY`; builtins via `import clm.agents` |
| Concurrent test reorg | Prefer architecture descriptions over hard-coded test paths in docs |
| 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 for modularization must-wave. Optional ops: live smoke, ACP, config.toml. Ready to commit when test reorg settles.
None. Ready to **push** when desired. Optional product work: live smoke, ACP, config.toml.
---
## Quick resume checklist
- [x] I0–I6 + Progress v3 + streaming on origin baseline (`b7db73a`)
- [x] `clm.runtime` + experiments↔cli inversion
- [x] `clm.agents` / session harden + loop injection
- [x] Import boundaries empty for experiments→cli and loop→grok
- [x] Docs modules + AGENTS map
- [x] Suite **248 green**
- [x] Modularization committed as `c5d495f` (not pushed)
- [ ] Optional push to origin
- [x] Origin baseline Progress v3 + streaming (`b7db73a`)
- [x] Modularization must-wave (`c5d495f`) + HANDOFF docs tips
- [x] 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
@@ -264,19 +264,19 @@ None for modularization must-wave. Optional ops: live smoke, ACP, config.toml. R
```text
Repo: /Volumes/SSD2TB/books/clm-agents
Branch: main @ c5d495f (1 ahead of origin/main @ b7db73a)
HANDOFF.md — Stand 2026-08-06
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
Modularization must-wave on local main:
- clm.runtime, clm.agents (+ grok), session core, loop injection
- tests/unit/<pkg>/, AGENTS.md, docs/modules, import boundaries
- 248 tests green
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 kind; config.toml
4) Library: import clm.agents before build_agent for builtins
3) Later: full ACP client; config.toml
Always: .venv/bin/python | .venv/bin/pytest
Do not stage: .clm/
```