Software Orchestrator
5769c1cd22
- Auto-Registration-Bug behoben (register_project/get_project_id/resolve_project Trennung) - 25 Tests gruen (Pytest) - block_compactor-Tool refactored (Option B: Soft-Check statt Hard-Block) - 4 Restbaustellen gefixt - DB-Schema: plugin_settings-Tabelle hinzugefuegt - 3 Schattenprojekte aus DB geloescht - Plan v3 + Refactor-Plan + Worklog dokumentiert
360 lines
16 KiB
Markdown
360 lines
16 KiB
Markdown
# Bugfix-Plan: Auto-Registration in `resolve_project()`
|
||
|
||
**Datum:** 2026-06-16
|
||
**Status:** Plan v3 – CONDITIONAL adressiert + Block 7b (plan_mode_guard) ergänzt
|
||
**Phase:** Plan-Mode `implementation_allowed` (gesetzt für `a0_software_orchestrator` Meta-Projekt)
|
||
**Betroffenes Plugin:** `a0_software_orchestrator`
|
||
|
||
---
|
||
|
||
## 1. Problem (Ist-Zustand)
|
||
|
||
`resolve_project(name)` in `helpers/db_state_store.py` Zeile 60–109 ruft bei unbekanntem Namen **automatisch** ein `INSERT INTO projects` auf, ohne Plausiprüfung. Sechs Folge-Bugs + ein Siebter (Fund bei Modus-Wechsel):
|
||
|
||
| # | Bug | Datei / Zeile | Folge |
|
||
|---|-----|--------------|-------|
|
||
| 1 | `resolve_project()` akzeptiert jeden String | `db_state_store.py:60-109` | Schattenprojekte wie `a0`, `a0-development`, `workdir` (3 bereits gelöscht) |
|
||
| 2 | `register_project()` ohne Plausiprüfung | `db_state_store.py:644-687` | Auch der explekite Pfad akzeptiert Müll |
|
||
| 3 | `os.path.basename(...)` als Projektname | `migrate_a0_to_db.py:398` | Verzeichnisname wird stillschweigend zum Projektnamen |
|
||
| 4 | `os.path.basename(...)` als Projektname | `api/project_state_get.py:16` | API-Call mit `project_root` erzeugt Phantom-Projekt |
|
||
| 5 | `resolve_project()` macht UPSERT auf `project_state.last_active_at` bei JEDEM Aufruf | `db_state_store.py:82-89` | Versteckter Side-Effect: jeder Tool-Aufruf verändert DB-State |
|
||
| 6 | Modul-Docstring empfiehlt `resolve_project()` weiterhin | `db_state_store.py:1-19, 127` | Nach Fix irreführend → muss mit-aktualisiert werden |
|
||
| 7 | `plan_mode_guard.py` ruft `resolve_project()` (Auto-Register-Bug) | `plan_mode_guard.py:76` | Modus-Wechsel für unbekannte Projektnamen erzeugt Phantom; nach Fix scheitert LookupError |
|
||
|
||
## 2. Soll-Zustand
|
||
|
||
- **Zwei saubere Funktionen mit klarer Semantik:**
|
||
- `get_project_id(name)` – nur Lesen, gibt `int | None` zurück.
|
||
- `register_project(name, git_url, description, ...)` – nur Anlegen/Aktualisieren, **mit Plausiprüfung**.
|
||
- `resolve_project()` wird zum dünnen Komfort-Wrapper, der **bei fehlendem Projekt `LookupError` wirft** statt heimlich anzulegen. Der `last_active_at`-UPSERT bleibt erhalten.
|
||
- `plan_mode_guard.py` arbeitet **projekt-unabhängig**: liest/schreibt einen globalen Key `orchestrator_mode` (nicht pro project_id). Kein `resolve_project()`-Aufruf mehr.
|
||
- Pattern + Blacklist verhindern ungültige Namen direkt bei `register_project()`.
|
||
- `basename`-Fallbacks in `migrate_a0_to_db.py` und `api/project_state_get.py` werden entfernt.
|
||
|
||
**Pattern-Akzeptanzkriterien (explizit):**
|
||
- Erlaubt: `^[a-z][a-z0-9-]{1,40}$` (lowercase, Buchstaben/Ziffern/Bindestrich, 2–41 Zeichen, mit Buchstabe beginnend).
|
||
- **Nicht erlaubt:** Punkte, Underscores, Umlaute, Leerzeichen, Großbuchstaben.
|
||
|
||
**Blacklist-Klärung:**
|
||
- `a0-development` ist **bewusst** in der Blacklist. Wer es künftig als DB-Eintrag will: Blacklist-Eintrag entfernen + explizit `register_project("a0-development", ...)` aufrufen.
|
||
|
||
**Meta-Projekt `a0_software_orchestrator`:**
|
||
- Bereits vor dem Fix explizit registriert (project_id=5) als Träger für Plugin-Level-State (plan_mode etc.).
|
||
- Matcht das neue Pattern NICHT (Underscore), aber Existenz in DB bleibt erhalten (register_project war vor dem neuen Pattern aktiv).
|
||
- Wird nach dem Fix nicht von `resolve_project` blockiert, weil `plan_mode_guard` kein `resolve_project` mehr ruft (siehe §3.7).
|
||
|
||
**Out-of-scope (explizit):**
|
||
- `helpers/library/db.py:PatternDB.register_project` (DB-Layer, nicht Project-Layer) – separater Fix.
|
||
- Side-Note: `leocrm` hat bereits orch_kv-Einträge (`phase=implementation`, `orchestrator_mode=implementation_allowed`, `project_root=/a0/usr/workdir/dev-projects/leocrm`) aus früherer Session. Inkonsistenz mit `project_state.plan_mode=None`. **Nicht Teil dieses Bugs**, separater Audit-Task.
|
||
|
||
## 3. Konkrete Änderungen
|
||
|
||
### 3.1 `helpers/db_state_store.py`
|
||
|
||
**A) Neue Konstanten + Validator** (nach Zeile 20, vor `_db_error_handler`):
|
||
|
||
```python
|
||
import re
|
||
|
||
PROJECT_NAME_PATTERN = re.compile(r"^[a-z][a-z0-9-]{1,40}$")
|
||
FORBIDDEN_PROJECT_NAMES = frozenset({
|
||
"a0", "a0-development", "workdir", "dev-projects",
|
||
"usr", "tmp", "home", "root", "skills", "plugins",
|
||
"opt", "lib", "etc", "var", "data", "venv",
|
||
})
|
||
|
||
def _validate_project_name(name: str) -> str:
|
||
"""Strippt, prüft Pattern + Blacklist. Wirft ValueError bei Verletzung."""
|
||
if not name or not name.strip():
|
||
raise ValueError("project name must be non-empty")
|
||
name = name.strip()
|
||
if name in FORBIDDEN_PROJECT_NAMES:
|
||
raise ValueError(
|
||
f"project name '{name}' is reserved/forbidden "
|
||
f"(likely a system directory, not a software project)"
|
||
)
|
||
if not PROJECT_NAME_PATTERN.match(name):
|
||
raise ValueError(
|
||
f"project name '{name}' does not match pattern "
|
||
f"{PROJECT_NAME_PATTERN.pattern} (lowercase letters, digits, hyphens)"
|
||
)
|
||
return name
|
||
```
|
||
|
||
**B) `resolve_project()` umbauen** (Zeile 60–109):
|
||
|
||
```python
|
||
@_db_error_handler
|
||
def resolve_project(name: str) -> int:
|
||
"""Löst einen Projektnamen zur project_id auf.
|
||
|
||
WICHTIG: Legt KEIN neues Projekt mehr an. Bei unbekanntem Namen
|
||
wird LookupError geworfen. Zum Anlegen explizit register_project()
|
||
oder project_registry action=register verwenden.
|
||
"""
|
||
name = _validate_project_name(name)
|
||
db = _db()
|
||
row = db.conn.execute(
|
||
"SELECT id FROM projects WHERE name = ?", (name,)
|
||
).fetchone()
|
||
if not row:
|
||
raise LookupError(
|
||
f"project '{name}' is not registered. "
|
||
f"Call register_project() or project_registry action=register first."
|
||
)
|
||
project_id = int(row[0])
|
||
db.conn.execute(
|
||
"""
|
||
INSERT INTO project_state (project_id, status, phase, last_active_at)
|
||
VALUES (?, 'active', 'intake', datetime('now'))
|
||
ON CONFLICT(project_id) DO UPDATE SET last_active_at = datetime('now')
|
||
""",
|
||
(project_id,),
|
||
)
|
||
db.conn.commit()
|
||
return project_id
|
||
```
|
||
|
||
**C) `register_project()` Plausiprüfung rein** (Zeile 644):
|
||
|
||
```python
|
||
@_db_error_handler
|
||
def register_project(name: str, git_url: str = "", description: str = "",
|
||
tech_stack: str = "{}", status: str = "active",
|
||
phase: str = "intake") -> int:
|
||
"""Register or update a project. Returns project_id."""
|
||
name = _validate_project_name(name)
|
||
# ... Rest wie bisher (INSERT … ON CONFLICT, project_state upsert, set_kv)
|
||
```
|
||
|
||
**D) Modul-Docstring oben anpassen** (Zeile 1–19, Bug 6):
|
||
|
||
```
|
||
Verwendung:
|
||
# Neues Projekt anlegen (explizit):
|
||
pid = register_project("crm-system", git_url="https://...")
|
||
set_kv(pid, "phase", "implementation")
|
||
|
||
# Existierendes Projekt nachschlagen (nur lesen):
|
||
existing_pid = get_project_id("crm-system")
|
||
|
||
# Nur in create-on-missing-Aufrufern (z.B. Migration):
|
||
pid = resolve_project("crm-system") # wirft LookupError wenn fehlt
|
||
```
|
||
|
||
**E) Hinweis-Text in `get_project_id()`-Docstring** (Zeile 123–136, Bug 6):
|
||
|
||
```python
|
||
def get_project_id(name: str) -> Optional[int]:
|
||
"""Return existing project_id without creating or mutating project state.
|
||
|
||
This is the preferred read-only lookup. For create-or-lookup semantics
|
||
use resolve_project(); to create explicitly use register_project().
|
||
"""
|
||
```
|
||
|
||
### 3.2 Tool-Aufrufer migrieren (10 Tools / 10 Call-Sites)
|
||
|
||
Alle Stellen, die aktuell `pid = resolve_project(name)` machen, ändern auf:
|
||
|
||
```python
|
||
pid = get_project_id(name)
|
||
if pid is None:
|
||
raise LookupError(f"project '{name}' is not registered")
|
||
```
|
||
|
||
Betroffen (alle in `tools/`):
|
||
- `block_compactor.py:297`
|
||
- `block_resume.py:54`
|
||
- `next_step.py:49`
|
||
- `orchestrator_state.py:48`
|
||
- `plan_mode_guard.py:76` → wird komplett umgebaut, siehe §3.7
|
||
- `quality_gate.py:388`
|
||
- `repo_manifest.py:64`
|
||
- `resume_checker.py:40`
|
||
- `scorecard_update.py:43`
|
||
- `tool_registry.py:50`
|
||
|
||
**NICHT geändert** (verwenden bereits `get_project_id`):
|
||
- `extensions/python/monologue_start/load_project_state.py:30`
|
||
|
||
### 3.3 Helper-Aufrufer migrieren (4 Helper-Dateien / 7 Call-Sites)
|
||
|
||
| Datei | Call-Sites |
|
||
|-------|-----------|
|
||
| `helpers/artifact_rules.py` | 1 (Z. 53) |
|
||
| `helpers/briefing_file.py` | 2 (Z. 62, 134) |
|
||
| `helpers/compact_protocol.py` | 3 (Z. 177, 218, 243) |
|
||
| `helpers/resume_state.py` | 1 (Z. 61) |
|
||
|
||
### 3.4 `utils/migrate_a0_to_db.py`
|
||
|
||
**Zeile 395–419 (basename-Fallback entfernen, Bug 3):**
|
||
|
||
```python
|
||
if not args.project:
|
||
print("ERROR: --project=<name> ist Pflicht (basename-Fallback entfernt)")
|
||
sys.exit(1)
|
||
project_name = args.project
|
||
if os.path.isabs(args.project) and os.path.isdir(args.project):
|
||
project_root = args.project
|
||
elif args.project_root:
|
||
project_root = args.project_root
|
||
else:
|
||
# ... vorhandene DB-Lookup-Logik bleibt
|
||
```
|
||
|
||
**Zeile 213:** `pid = resolve_project(project_name)` → `pid = register_project(project_name, git_url="")`
|
||
|
||
### 3.5 `api/project_state_get.py`
|
||
|
||
**Zeile 16 ersetzen (Bug 4):**
|
||
|
||
```python
|
||
project_name = input.get("project_name")
|
||
if not project_name:
|
||
return {"ok": False, "error": "project_name is required (basename fallback removed)"}
|
||
```
|
||
|
||
### 3.6 Legacy-Daten-Migration (Blocker b)
|
||
|
||
**Neue Datei:** `utils/migrate_legacy_project_names.py`
|
||
|
||
Logik: SELECT alle Projekte → prüfe ob Name Pattern + nicht in Blacklist → wenn nicht: status='archived' in project_state, WARN-Log → Bericht "X archived, Y active".
|
||
|
||
**Aufruf:** Manuell. Im aktuellen Datenbestand nur leocrm (matcht) → leerer Archivierungs-Lauf.
|
||
|
||
### 3.7 `tools/plan_mode_guard.py` umbauen (Bug 7, Block 7b)
|
||
|
||
**Problem:** `plan_mode_guard.py:76` ruft `resolve_project(name)` auf. Nach dem Fix wirft das für unbekannte Namen `LookupError`. Außerdem: Plan-Mode ist plugin-weit, nicht projekt-spezifisch.
|
||
|
||
**Lösung:** Plan-Mode als globaler Key ohne Projekt-Bindung.
|
||
|
||
**Konzept:**
|
||
- Statt `orch_kv[pid]['orchestrator_mode']`: globaler Key z.B. in `project_state` mit `project_id=0` (Platzhalter) ODER in einer neuen Tabelle `plugin_settings(key, value_json)`.
|
||
- Pragmatisch: erstere Variante (Platzhalter project_id=0) – keine Schema-Änderung.
|
||
|
||
**Konkret (Pseudocode für `plan_mode_guard.py`):**
|
||
|
||
```python
|
||
@_db_error_handler
|
||
def _get_plugin_mode() -> dict:
|
||
db = _db()
|
||
row = db.conn.execute(
|
||
"SELECT value_json FROM orch_kv "
|
||
"WHERE project_id = 0 AND key = 'orchestrator_mode'"
|
||
).fetchone()
|
||
if not row:
|
||
return dict(_DEFAULT_MODE)
|
||
return _normalize_mode(json.loads(row[0]))
|
||
|
||
@_db_error_handler
|
||
def _set_plugin_mode(mode_data: dict) -> None:
|
||
db = _db()
|
||
db.conn.execute(
|
||
"INSERT INTO orch_kv (project_id, key, value_json, updated_at) "
|
||
"VALUES (0, 'orchestrator_mode', ?, datetime('now')) "
|
||
"ON CONFLICT(project_id, key) DO UPDATE SET "
|
||
" value_json = excluded.value_json, updated_at = datetime('now')",
|
||
(json.dumps(mode_data),)
|
||
)
|
||
db.conn.commit()
|
||
|
||
class PlanModeGuard(Tool):
|
||
async def execute(self, requested_action: str = "", new_mode: str = "", **kwargs):
|
||
# KEIN resolve_project-Aufruf mehr!
|
||
if new_mode:
|
||
if new_mode not in _MODE_POLICIES:
|
||
return Response(message=json.dumps({"verdict": "ERROR", "error": f"invalid mode: {new_mode}"}), break_loop=False)
|
||
mode_data = {
|
||
"mode": new_mode,
|
||
"allowed_actions": list(_MODE_POLICIES[new_mode]["allowed_actions"]),
|
||
"blocked_actions": list(_MODE_POLICIES[new_mode]["blocked_actions"]),
|
||
}
|
||
_set_plugin_mode(mode_data)
|
||
return Response(message=json.dumps({"verdict": "ALLOWED", "mode": new_mode, "transitioned": True}, indent=2), break_loop=False)
|
||
|
||
mode_data = _get_plugin_mode()
|
||
current_mode = mode_data["mode"]
|
||
allowed = mode_data["allowed_actions"]
|
||
blocked = mode_data["blocked_actions"]
|
||
if requested_action and requested_action in blocked:
|
||
return Response(message=f"BLOCKED: action '{requested_action}' not allowed in mode '{current_mode}'", break_loop=False)
|
||
if not requested_action or requested_action in allowed:
|
||
return Response(message=json.dumps({"verdict": "ALLOWED", "mode": current_mode, "action": requested_action}, indent=2), break_loop=False)
|
||
return Response(message=json.dumps({"verdict": "UNKNOWN", "mode": current_mode, "action": requested_action}, indent=2), break_loop=False)
|
||
```
|
||
|
||
**Migration:** Bestehende `orch_kv[pid]['orchestrator_mode']` (z.B. für leocrm, a0_software_orchestrator) werden IGNORIERT. Neue globale Sicht unter `project_id=0` gewinnt. Cleanup der Alt-Einträge: manuell oder in Legacy-Migration §3.6 mit-erledigen.
|
||
|
||
## 4. Test-Plan
|
||
|
||
**Neue Datei:** `helpers/tests/test_db_state_store.py`
|
||
|
||
Testfälle (pytest, in-memory sqlite, Fixture für `PatternDB`):
|
||
|
||
**Validator (3 Cases):**
|
||
1. `test_validate_project_name_ok` – `"crm-system"`, `"web-cad"`, `"rentman-clone"`, `"a1b"` → ok
|
||
2. `test_validate_project_name_pattern_fail` – `"A0"`, `"Crm System"`, `"a"`, `""`, `"my.app"`, `"cool_app"`, `"müller"` → ValueError
|
||
3. `test_validate_project_name_blacklist` – `"a0"`, `"a0-development"`, `"workdir"`, `"dev-projects"` → ValueError
|
||
4. `test_validate_project_name_whitespace_strip` – `" crm "` → `"crm"`
|
||
|
||
**register_project (4 Cases):**
|
||
5. `test_register_project_new`
|
||
6. `test_register_project_idempotent`
|
||
7. `test_register_project_value_error_wraps_validator`
|
||
8. `test_register_project_idempotent_overwrite_semantics`
|
||
|
||
**resolve_project (4 Cases):**
|
||
9. `test_resolve_project_existing`
|
||
10. `test_resolve_project_missing_raises` (kein Auto-Register mehr!)
|
||
11. `test_resolve_project_invalid_name_raises` (Blacklist wirft VOR SELECT)
|
||
12. `test_resolve_project_touches_last_active_at`
|
||
|
||
**get_project_id (1 Case):**
|
||
13. `test_get_project_id_missing_returns_none`
|
||
|
||
**Legacy-Migration (1 Case):**
|
||
14. `test_legacy_row_with_invalid_name_is_archived`
|
||
|
||
**End-to-End (1 Case):**
|
||
15. `test_e2e_next_step_with_unknown_project_raises`
|
||
|
||
**plan_mode_guard global (2 Cases):**
|
||
16. `test_plan_mode_guard_set_get` – set implementation_active, read back, no project_id needed
|
||
17. `test_plan_mode_guard_no_resolve_project_called` – Mock resolve_project, ensure NOT called
|
||
|
||
## 5. Risiken & Migrationspfad
|
||
|
||
- **Breaking Change** für 17 resolve_project-Aufrufer (10 Tools – 1 plan_mode_guard = 9 + 7 Helper-Sites + 1 Skript = 17). `plan_mode_guard` wird komplett umgebaut (kein resolve_project). Mitigation: LookupError-Handling + globaler Mode-Key.
|
||
- **Legacy-Daten:** §3.6.
|
||
- **Aktive User-Flows:** `resolve_project` mit projektnamen aus User-Eingabe bricht jetzt hart mit LookupError. Mitigation: klarer Fehlertext.
|
||
- **Plugin-Reload mitten im Tool-Call:** minor.
|
||
- **Concurrency:** SQLite single-writer, kein neues Risiko. ✓
|
||
- **Out-of-scope:** `PatternDB.register_project` (library), `leocrm`-Daten-Audit.
|
||
- **Bestehende Projekte:** `leocrm` matcht Pattern und ist nicht in Blacklist → keine Daten-Migration nötig.
|
||
- **plan_mode_guard-Migration:** globale Sicht unter `project_id=0` löst pro-projekt-Sicht ab. Alt-Einträge werden ignoriert, Cleanup optional.
|
||
|
||
## 6. Freigabe-Checkliste
|
||
|
||
- [ ] User hat Plan v3 gelesen
|
||
- [ ] User gibt frei: Implementierung über `implementation_engineer` Subagent
|
||
- [ ] Bug 1–7 adressiert (inkl. Bug 7: plan_mode_guard-Umbau)
|
||
- [ ] 17 Call-Sites (9 Tools + 7 Helper + 1 Skript) angepasst
|
||
- [ ] `plan_mode_guard.py` umgebaut (Bug 7, §3.7)
|
||
- [ ] 2 basename-Fallbacks entfernt
|
||
- [ ] Modul-Docstring aktualisiert (Bug 6)
|
||
- [ ] 17 Test-Cases geschrieben + grün
|
||
- [ ] Legacy-Migrations-Snippet erstellt + ausgeführt
|
||
- [ ] Optional: `quality_reviewer` Re-Review nach Implementierung
|
||
|
||
---
|
||
|
||
**Geschätzter Aufwand:** 5–6 Subagent-Calls (1× großer Patch-Block via implementation_engineer, 1× Tests via test_debug_engineer, 1× Quality-Review, 1× Final-Verify).
|
||
|
||
**Reviewer-Verdict:** CONDITIONAL → nach Einarbeitung dieser 3 Blocker freigabefähig.
|
||
- (a) Call-Site-Inventur: 14 → 17 (plan_mode_guard ausgenommen) ✓
|
||
- (b) Legacy-Migration: §3.6 + Test 14 ✓
|
||
- (c) PatternDB.register_project: out-of-scope ✓
|
||
- (d) Bug 7 (plan_mode_guard): §3.7 + Tests 16-17 ergänzt ✓
|