a0_software_orchestrator/docs/block-compactor-simplification.md

# Plan: Block-Compactor-Tool vereinfachen

**Projekt:** a0_software_orchestrator (Plugin)
**Datum:** 2026-06-16
**Zweck:** Overengineered `block_compactor`-Tool auf einen sinnvollen Funktionsumfang reduzieren
**Status:** DRAFT – wartet auf User-Freigabe
**Backup vor Refactor:** `/a0/usr/plugins/a0_software_orchestrator.backup-20260616T134526Z/` (Code-Archiv 161K + DB 256K + WAL/SHM)

---

## IST-Zustand

`tools/block_compactor.py` `BlockCompactor.execute()` (Z. 276-401) prüft VOR dem Schreibvorgang:

1. **5 mandatory artifacts** (via `check_mandatory_artifacts(name)`):
   - `worklog` (≥1 Eintrag in `orch_worklog`)
   - `todo` (Tabelle `orch_todos` existiert + Schema OK)
   - `project_state` (KV-Key `project_state` oder `phase` in `orch_kv`)
   - `current_status` (Eintrag in `orch_status`)
   - `next_steps` (≥1 pending in `orch_next_steps`)
2. **Token-Ratio** (≥0.8 empfohlen, ≥0.9 erzwungen)
3. **Subagent-Status** (muss 0 sein)
4. **Quality-Gate** (muss `passed` sein)
5. **User-Approval** (muss gegeben sein, falls nötig)

Bei Fehler: BLOCKED-Response, kein Schreibvorgang, Tool blockt HARD.

`force=true` umgeht NUR Token-Ratio, NICHT die anderen Preconditions.

---

## Problem

- **Overengineered**: 5 Preconditions für einen Schreibvorgang sind zu viel.
- **False-Positives**: Heute geschehen – alle 5 mandatory artifacts sind in der Live-DB, Tool meldet trotzdem 'todo missing' (vermutlich Cache-Problem im Plugin-Loader, nicht reproduzierbar in LIVE-Tests).
- **Schwer debuggbar**: Wenn ein Precondition fehlt, zeigt das Tool nur den Namen, nicht warum.
- **Wenig Nutzen**: Der Refactor-Schutz (z.B. 'session-ende = alles sauber') hat in der Praxis keinen Mehrwert, weil die mandatory artifacts sowieso in der DB stehen (man füllt sie ja während des Blocks).

---

## Refactor-Optionen

### Option A – Minimal-Refactor

- mandatory artifact checks KOMPLETT rauswerfen.
- Behalten: Token-Ratio (als WARN), Quality-Gate (als WARN), Subagent-Status (BLOCK bei > 0).
- `force=true` umgeht nur Token-Ratio.
- Pro: einfach, keine False-Positives mehr.
- Contra: keine 'Mindest-Sicherheit' mehr.

### Option B – Soft-Check (EMPFOHLEN)

- mandatory artifacts werden geprüft, aber als **WARN geloggt, nicht als BLOCK**.
- Behalten: Token-Ratio (BLOCK bei ≥0.9), Subagent-Status (BLOCK bei > 0), Quality-Gate (BLOCK bei fail).
- Tool schreibt IMMER, aber das Output-JSON enthält ein Feld `warnings: []` mit Hinweisen.
- Pro: pragmatischer Mittelweg. User sieht, was fehlt, aber das Tool blockt nicht.
- Contra: User muss die Warnings aktiv prüfen.

### Option C – Pure-Simple

- ALLE Preconditions raus außer Subagent-Status > 0.
- Tool macht nur: `INSERT INTO orch_block_compact` + `INSERT INTO orch_worklog` + `docs/projects/<name>/snapshots/<ts>.json`.
- Pro: maximal einfach, fast unfehlbar.
- Contra: keine Sicherheit. Versehentlicher Aufruf mit leerem Block schreibt trotzdem.

---

## Empfehlung: **Option B (Soft-Check)**

Begründung:
- Blockierende Preconditions nur dort, wo sie ECHTEN Schaden verhindern (laufende Subagents = Datenverlust möglich, Quality-Gate-Fail = Block mit bekanntem Bug persistiert).
- mandatory artifacts als WARN: User behält Überblick, aber False-Positives blocken nicht mehr.
- Token-Ratio bleibt BLOCK, weil das bei echtem Memory-Druck tatsächlich sinnvoll ist.
- Komplexitäts-Reduktion: 5 Preconditions → 3 (davon 2 als WARN), 1 BLOCK (Token-Ratio), 1 BLOCK (Subagent > 0).

---

## Konkret: was ändert sich

### `tools/block_compactor.py`

```python
# VORHER (Z. 323-353):
decision = should_block_compact(
    project_name=name, estimated_ratio=ratio,
    open_subagent_calls=int(open_subagent_calls),
    quality_gate_passed=bool(quality_gate_passed),
    user_gave_new_instruction=bool(user_gave_new_instruction),
)
if not decision["allowed"] and not force:
    return Response(message=f"BLOCK COMPACT BLOCKED: {decision['reason']}...", break_loop=False)

# NACHHER (Vorschlag):
decision = should_block_compact(
    project_name=name, estimated_ratio=ratio,
    open_subagent_calls=int(open_subagent_calls),
    quality_gate_passed=bool(quality_gate_passed),
)
if not decision["allowed"] and not force:
    return Response(message=f"BLOCK COMPACT BLOCKED: {decision['reason']}...", break_loop=False)

# WARNINGS sammeln (statt BLOCK):
warnings = []
artifacts = check_mandatory_artifacts(name)
missing = [k for k, v in artifacts.items() if not v]
if missing:
    warnings.append(f"mandatory artifacts incomplete: {missing}")
```

### `helpers/compact_protocol.py`

- `MANDATORY_ARTIFACTS` und `check_mandatory_artifacts` bleiben UNVERÄNDERT (andere Tools könnten sie noch nutzen).
- KEIN Refactor dieser Datei.

### Tests

- **3 neue Tests** in `helpers/tests/test_db_state_store.py` (oder `test_block_compactor.py`):
  1. `test_block_compactor_warns_but_writes_with_missing_artifacts` – mandatory artifacts fehlen, Tool schreibt trotzdem + gibt WARN im Response.
  2. `test_block_compactor_blocks_on_open_subagents` – open_subagent_calls=1, Tool blockt HARD.
  3. `test_block_compactor_blocks_on_quality_gate_fail` – quality_gate_passed=False, Tool blockt HARD.
- **Bestehende 22 Tests bleiben unverändert** (andere Tools sind nicht betroffen).

---

## Risiken

- **Risk 1**: User verliert die 'garantiert sauber'-Sicherheit. Mitigation: WARN-Output ist sichtbar, User kann selbst entscheiden.
- **Risk 2**: Versehentliche Aufrufe schreiben in die DB. Mitigation: in der Praxis ist `block_compactor` ein Orchestrator-only-Tool, nicht user-facing.
- **Risk 3**: Andere Tools, die `check_mandatory_artifacts` nutzen, brechen. Mitigation: Funktion bleibt erhalten, nur ihr Aufruf-Kontext ändert sich.

---

## Rollback

Falls der Refactor Probleme macht:
```bash
# 1) Plugin-Code wiederherstellen
rm -rf /a0/usr/plugins/a0_software_orchestrator/{helpers,tools,utils,docs}
tar -xzf /a0/usr/plugins/a0_software_orchestrator.backup-20260616T134526Z/code.tar.gz -C /a0/usr/plugins/a0_software_orchestrator/

# 2) DB wiederherstellen
cp /a0/usr/plugins/a0_software_orchestrator.backup-20260616T134526Z/patterns.db /a0/usr/plugins/a0_software_orchestrator/helpers/library/patterns.db
cp /a0/usr/plugins/a0_software_orchestrator.backup-20260616T134526Z/patterns.db-wal /a0/usr/plugins/a0_software_orchestrator/helpers/library/
cp /a0/usr/plugins/a0_software_orchestrator.backup-20260616T134526Z/patterns.db-shm /a0/usr/plugins/a0_software_orchestrator/helpers/library/
```

---

## Aufwand

- **Subagent-Call** (Implementation Engineer): 1, ca. 20 min
- **Test-Run**: 1, ca. 5 min (22 → 25 Tests, alle grün)
- **Manueller Smoke-Test**: 1 block_compactor-Call mit fehlenden mandatory artifacts, prüfen ob WARN + Schreibvorgang
- **Gesamt**: ca. 30 min

---

## Freigabe

Bitte sag eines:
- **'los B'** = Option B (Soft-Check) umsetzen
- **'los A'** = Option A (Minimal-Refactor) umsetzen
- **'los C'** = Option C (Pure-Simple) umsetzen
- **'anpassen'** = Plan anpassen (was?)
- **'stop'** = nicht refactoren, Session beenden