diff --git a/a2/README.md b/a2/README.md new file mode 100644 index 0000000..5da2094 --- /dev/null +++ b/a2/README.md @@ -0,0 +1,52 @@ +# RED QUEEN — A2: Persistent Mission State & State Machine + +> **Phase:** A2 (CONTROLLED BUILD) · **Status:** ABGESCHLOSSEN · Commit `dbbbb1d` +> **Scope:** Persistente Mission-State- und Work-Package-State-Machine. +> **Keine** autonome Orchestrierung, keine Loops, kein Heartbeat, kein Cron (A2 §16). + +--- + +## 1. Architektur (verbindlich, A2 §3/§8) + +- **Work Packages → native Hermes-Kanban** (primärer Task-State) via `KanbanMirror` + (best effort): Dependencies via `link`, Block via `block`, Complete via `complete`, + Idempotenz via `--idempotency-key`. `HERMES_KANBAN_DB` steuert die (isolierte) DB. +- **Mission-Ebene → minimaler Metadata-Layer** `missions.db` (SQLite) als **PRIMÄRER + State**: Mission-States, WP-States, Dependencies, Transition-Evidence, ID-Fortschritt. +- **Keine zweite vollständige Task-Queue.** Kanban = WP-State; Missions-Layer minimal. +- Priorität: **HERMES NATIVE > CONFIG > SKILL > MINIMAL CUSTOM > EXTERNAL**. + +## 2. Module + +| Datei | Rolle | +|-------|-------| +| `rq_state_machine.py` | Deterministische Transition-Tabellen (MISSION + WP), direkt aus `MISSION_STATE_MACHINE.md`. Keine Persistenz. | +| `rq_mission.py` | `MissionStore`: persistente SQLite-DB, Validierung, Fail-closed, Idempotenz, KanbanMirror. | +| `rq_mission_cli.py` | CLI (maschinenlesbar via `--json`, Exit 2 bei RqError). | +| `test_a2.py` | Deterministische Tests (isolierte Temp-DBs). **PASS=61 FAIL=0**. | +| `MISSION.md.template` | Markdown-Metadaten-Template (Goal/Scope/Constraints/AC). Aktiver State nie aus Markdown. | +| `.gitignore` | `__pycache__/`, `*.pyc`, `*.db`, `*.tmp` | + +## 3. ID-Schema (§7) +- Mission: `RQ-MISSION-YYYYMMDD-NNN` (NNN restart-stabil via Max+1 in DB). +- WP: `-WP-NNN` (innerhalb der Mission eindeutig). + +## 4. State Machines (autoritativ A1) +- **Mission:** CREATED/PLANNING/READY/RUNNING/REVIEW/COMPLETED + BLOCKED/PAUSED/FAILED/CANCELLED/ESCALATED. +- **WP:** TODO/READY/IN_PROGRESS/CHECKING/DONE + FAILED/BLOCKED/ESCALATED. +- Verbote: COMPLETED→RUNNING, DONE→IN_PROGRESS ohne Recovery, Mission COMPLETED mit offenen Pflicht-WPs, WP DONE mit offener Dependency → REJECT. +- Fail-closed: unbekannter/korrupter State → `STATE_ERROR`, keine Mutation. + +## 5. Tests (§18) +`python3 test_a2.py` → **PASS=61 FAIL=0 EXIT=0**. Deckt: create/read, valid/invalid +transitions, dependency, block, wp/mission complete, idempotency, unknown id/state, +**RESTART-PERSISTENCE** (identisch), state-consistency, STATE_ERROR fail-closed, +Kanban-Mirror-Isolation. Isolierte Temp-DBs, produktive `/opt/data/kanban.db` unangetastet. + +## 6. Rollback (§22) +- **Code-/-Docs neu:** `a2/` (6 Dateien + Template) und README-Abschnitt „Implementierungsstatus". +- **Zurückrollen:** `git reset --hard 3d738e6` (A1-Zustand) oder `git revert dbbbb1d 581253c`. +- **Config/DB-Strukturen erzeugt:** nur `missions.db` zur Laufzeit in einem wählbaren Pfad + (Konstruktor-Argument); produktive `kanban.db` NICHT verändert. +- **Testzustand:** entsteht nur in `tempfile.mkdtemp()`; nie im produktiven Bereich. +- **Impact:** kein Rain/Alice/Trading-System/Forgejo-Infrastruktur-Eingriff.