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

# 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:

# 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