|
| 1 | +# AGENTS.md — Das Brain |
| 2 | + |
| 3 | +> **Diese Datei ist die einzige Wahrheit.** Wenn andere Docs widersprechen, gewinnt diese. |
| 4 | +> Wer hier einen Pfad oder eine Regel ändert, muss `incidents/` einen Eintrag mit Begründung + Datum hinterlassen. |
| 5 | +> Erstellt: 2026-05-13 (Critic-Agent-Brief #218, Issue #212). |
| 6 | +
|
| 7 | +--- |
| 8 | + |
| 9 | +## 1. Mission (nicht verhandelbar) |
| 10 | + |
| 11 | +**Stealth-Runner ist ein Survey-Solver. Punkt.** |
| 12 | + |
| 13 | +- Ziel: Hochintelligenter, 24/7 autonomer Survey-Agent, der echtes Geld verdient. |
| 14 | +- Output-Metrik: **Cents pro Tag auf einem realen Heypiggy-Account**, nichts anderes. |
| 15 | +- Was im Repo lebt, muss für genau diese Metrik kämpfen. |
| 16 | + |
| 17 | +### Was zählt als "Survey-Solver-Code"? |
| 18 | + |
| 19 | +Genau diese Verantwortlichkeiten — alles andere ist verdächtig: |
| 20 | + |
| 21 | +1. **Survey-Discovery** — Heypiggy / Civey / PureSpectrum / Qualtrics / Toluna / Nfield-Dashboards scannen, eine offene Umfrage finden. |
| 22 | +2. **Pre-Qualifier** — entscheiden ob eine gefundene Umfrage überhaupt gestartet werden soll. |
| 23 | +3. **Survey-Execution-Graph** — DOM lesen, Fragetypen erkennen (radio/checkbox/slider/matrix/open-text/ranking), antworten, Seite weiterklicken. |
| 24 | +4. **Answer-Engine** — kontextkonsistente Persona-Antworten produzieren, Anti-Drift via question_hash. |
| 25 | +5. **CAPTCHA-Fallback-Chain** — 4 Solver + Human-Handoff-Log (real, nicht Behauptung — siehe H-1 unten). |
| 26 | +6. **Stealth/Anti-Detection** — Browser-Fingerprint, Human-Like Timing, Session/Cookie/IP-Rotation. |
| 27 | +7. **Auth / Login** — Login-Flow + Login-Verifier pro Plattform. |
| 28 | +8. **Daemon-Lifecycle** — 24/7-Lauf, Auto-Recovery, Heartbeat, State-Persistenz. |
| 29 | +9. **Reliability** — Network-State-Gate, DOM-Stability-Gate, Visual-Hash, Attestation (sobald sie wirklich existieren — siehe H-5/H-9). |
| 30 | +10. **Cash-Out** — Schwelle erreicht → Auszahlung triggern → Log + Beweis. |
| 31 | + |
| 32 | +Eine Datei, die keiner dieser 10 Verantwortlichkeiten dient, gehört nicht in dieses Repo. |
| 33 | + |
| 34 | +--- |
| 35 | + |
| 36 | +## 2. Repo-Topologie (Soll-Zustand) |
| 37 | + |
| 38 | +``` |
| 39 | +/ |
| 40 | +├── AGENTS.md # ← diese Datei. Das Brain. |
| 41 | +├── README.md # Kurzbeschreibung + Verweis auf AGENTS.md |
| 42 | +├── ROADMAP.md # was als nächstes implementiert wird |
| 43 | +├── CHANGELOG.md # was geändert wurde |
| 44 | +├── survey-cli/ # DAS PRODUKT (alle 10 Verantwortlichkeiten leben hier) |
| 45 | +│ ├── survey/ # Implementation |
| 46 | +│ ├── commands/ # CLI-Subcommands |
| 47 | +│ ├── tests/ # einzige Test-Quelle |
| 48 | +│ ├── tools/ # interne Tools |
| 49 | +│ ├── evals/ # Eval-Harness |
| 50 | +│ ├── data/ # statische Daten (Personas, Frage-Patterns) |
| 51 | +│ ├── plan_*.md # technische Pläne (mission-spezifisch) |
| 52 | +│ ├── pyproject.toml |
| 53 | +│ └── survey_cli_entry.py # einziger Entry-Point |
| 54 | +├── plans/ # CEO-Pläne (chronologisch nummeriert) |
| 55 | +├── incidents/ # Postmortems + Kill-Logs |
| 56 | +├── issues/ # offene Tickets (markdown) |
| 57 | +├── scripts/ # repo-weite Maintenance-Skripte |
| 58 | +├── docs/ # mission-relevante externe Doku |
| 59 | +├── profiles/ # Chrome-Profile (nicht versioniert, .gitignore) |
| 60 | +├── .agents/ .claude/ .opencode/ .qwen/ # Agent-Konfigs (read-only) |
| 61 | +└── .github/ # CI |
| 62 | +``` |
| 63 | + |
| 64 | +**Alles andere ist Kill-Candidate** (siehe Sektion 5 — Audit 2026-05-13). |
| 65 | + |
| 66 | +--- |
| 67 | + |
| 68 | +## 3. Critic-Agent — Rolle & Autorität |
| 69 | + |
| 70 | +Es gibt im Repo **drei Agentenrollen**: |
| 71 | + |
| 72 | +| Rolle | Aufgabe | Darf … | |
| 73 | +|---|---|---| |
| 74 | +| **Builder-Agent** | implementiert Features | Code schreiben, PRs öffnen | |
| 75 | +| **Reviewer-Agent** | reviewt offene PRs auf Style/Tests | PRs kommentieren, mergen | |
| 76 | +| **Critic-Agent** | jagt stillen Failure-Modus + tötet Mission-fremden Code | Code als Kill-Candidate markieren, BLOCKER-Issues anlegen, KEINE Builds | |
| 77 | + |
| 78 | +Der Critic-Agent ist **Anwalt des CEOs**, nicht der Programmierer. Default-Annahme: **Behauptung = Lüge bis zum Gegenbeweis**. |
| 79 | + |
| 80 | +### Erste Pflicht jedes Critic-Runs |
| 81 | + |
| 82 | +Bevor irgendeine Aktion gestartet wird: |
| 83 | + |
| 84 | +1. Lies dieses Brain komplett. |
| 85 | +2. Lies Issue **#212** (Status-Update CEO) und Issue **#218** (Detektiv-Brief). |
| 86 | +3. Lies `incidents/CRITIC-AUDIT-LATEST.md` (oder den jüngsten datierten Audit). |
| 87 | +4. Lies `survey-cli/AGENTS.md` (operative Regeln des Survey-CLI). |
| 88 | +5. Lies die zehn Hypothesen (Sektion 4) und prüfe pro Hypothese: hat sich seit letztem Audit etwas geändert? |
| 89 | + |
| 90 | +### Code-Style ist NICHT die Aufgabe |
| 91 | + |
| 92 | +- Linter, Formatter, Type-Checks → `ruff`, `mypy` machen das in CI. |
| 93 | +- PR-Reviews → Reviewer-Agent. |
| 94 | +- Style-Kommentare in PRs vom Critic sind verboten. |
| 95 | + |
| 96 | +--- |
| 97 | + |
| 98 | +## 4. Die 10 stehenden Hypothesen (H-1 .. H-10) |
| 99 | + |
| 100 | +Diese Hypothesen sind **permanent**. Jeder Critic-Run muss sie alle re-prüfen. Sie wurden in Issue #218 vom Auftraggeber definiert. |
| 101 | + |
| 102 | +| # | Hypothese | Letzter Status (2026-05-13) | |
| 103 | +|---|---|---| |
| 104 | +| H-1 | CAPTCHA-Chain ist 5-stufig | **WIDERLEGT als headline** — `_solvers` Liste hat 4 Einträge (siehe `fallback_chain.py:229-234`). Solver 5 = nur Log-Handoff. | |
| 105 | +| H-2 | Anti-Drift via question_hash hält Matrix-Fragen | **UNKLAR** — reproducer fehlt. | |
| 106 | +| H-3 | Daemon kann 24h laufen | **UNKLAR** — kein 30-min-Memory-Plot, kein Heartbeat-Recovery-Test. | |
| 107 | +| H-4 | Alle 5 Solver echt verdrahtet | **PARTIAL** — Solver-Dateien existieren, aber kein Integration-Test gegen echte API. | |
| 108 | +| H-5 | Verifier (#175) wird aktiv aufgerufen | **WIDERLEGT** — `state.verify` 0 Matches in `survey-cli/survey/`. Verifier lebt nur in `stealth-captcha/` (Fremdpaket). | |
| 109 | +| H-6 | Pre-Qualifier (413 LoC) filtert sinnvoll | **UNKLAR** — Regeln noch nicht zusammengefasst. | |
| 110 | +| H-7 | 70 Test-Dateien, davon wieviele tot? | 11 `@pytest.mark.skip`-Marker, Restzahl noch nicht klassifiziert. | |
| 111 | +| H-8 | Network-Gate (#185) hat keinen toten Pfad | **UNKLAR** — Default-Timeout-Verhalten ungeprüft. | |
| 112 | +| H-9 | Visual-Hash (#209) ist real & nützlich | **BLOCKER** — `visual_hash.py` existiert nicht. 0 Matches für `visual_hash\|pHash\|dct_hash`. PR #209 hat 11/11 CI grün, aber der gemergte Code ist im Repo nicht auffindbar. | |
| 113 | +| H-10 | Cash-Out wurde je live ausgelöst | **UNKLAR** — `runner.py:782` ruft `self.cash_out.trigger(...)`, aber kein Receipt-Log, kein Screenshot, kein 1-Cent-Beweis. | |
| 114 | + |
| 115 | +### Output-Format pro Hypothese |
| 116 | + |
| 117 | +Jeder Critic-Bericht hat exakt diese Struktur (siehe Issue #218 §4): |
| 118 | + |
| 119 | +```markdown |
| 120 | +### H-N: <Hypothese> |
| 121 | +Status: BESTÄTIGT | WIDERLEGT | UNKLAR |
| 122 | +Schweregrad: BLOCKER | HIGH | MEDIUM | LOW |
| 123 | +Beweis: |
| 124 | + - <Datei:Zeile> — <ein Satz> |
| 125 | + - reproducer: <Befehl oder Schritte> |
| 126 | +Aktion: |
| 127 | + - <1-2 Zeilen> |
| 128 | +``` |
| 129 | + |
| 130 | +--- |
| 131 | + |
| 132 | +## 5. Kill-Liste (Mission-fremder Code, 2026-05-13) |
| 133 | + |
| 134 | +Verdächtige Pfade — jede Zeile braucht **vor dem Löschen** Beweis durch den Critic-Agent (call-graph trace, grep nach Importen, Beweis dass kein Survey-Solver-Pfad ihn berührt). |
| 135 | + |
| 136 | +| Pfad | Verdacht | Beweismittel benötigt | |
| 137 | +|---|---|---| |
| 138 | +| `src/stealth_sync/` (4 Dateien) | Dublette zu `survey-cli/survey/daemon/` | grep nach `from stealth_sync` außerhalb von `src/` und `tests/` | |
| 139 | +| `core/` | parallele Codebasis | grep nach `from core` außerhalb der eigenen Tests | |
| 140 | +| `tests/test_core_*.py`, `tests/test_event_handlers.py`, `tests/test_form_validation.py` | testet Code aus `core/` | wenn `core/` stirbt, stirbt mit | |
| 141 | +| `cli/main.py` + `cli/modules/` | Dublette zu `survey_cli_entry.py` | importer-trace | |
| 142 | +| `agent-toolbox/` | Fremdcodebasis, eigenes `__init__.py`, separate Pfade | importer-trace | |
| 143 | +| `stealth-captcha/` | externes Paket mit eigener `pyproject.toml` | sollte als Git-Submodule oder PyPI-Dep eingebunden sein, nicht inline | |
| 144 | +| `_plans/` UND `plans/` | zwei Plan-Verzeichnisse | konsolidieren in `plans/` | |
| 145 | +| `commands/bot-chrome/`, `commands/cua-driver/`, `commands/playstealth/`, `commands/chrome/`, `commands/infisical/`, `commands/session-manager/` | nicht-Survey-Solver-Doku | hat README einen mission-relevanten Bezug? | |
| 146 | +| `graphify-out/` | generierte Artefakte | sollte in `.gitignore`, nicht committed | |
| 147 | +| `manifest.json` (3 Bytes), `graph.json` (3 Bytes) | leere Dateien | löschen oder sinnvoll füllen | |
| 148 | +| `test_e2e_survey.py` (Root), `test_graph_invoke.py` (Root) | Tests außerhalb der Test-Quelle | nach `survey-cli/tests/` verschieben oder löschen | |
| 149 | +| `start_toolbox.py`, `run_survey.py` (Root) | parallele Entry-Points | konsolidieren mit `survey_cli_entry.py` | |
| 150 | + |
| 151 | +### Kill-Ritual (Pflicht-Sequenz) |
| 152 | + |
| 153 | +Für jeden Kill-Candidate: |
| 154 | + |
| 155 | +1. **Beweisen**, dass kein Survey-Solver-Pfad ihn erreicht: |
| 156 | + ```bash |
| 157 | + grep -rn "from <pfad>" survey-cli/ scripts/ --include="*.py" |
| 158 | + grep -rn "import <pfad>" survey-cli/ scripts/ --include="*.py" |
| 159 | + ``` |
| 160 | +2. Wenn 0 Matches: **Eintrag in `incidents/KILL-LOG-YYYY-MM-DD.md`** mit Pfad + Beweis + Datum + Critic-Run-ID. |
| 161 | +3. Per separatem PR löschen (1 Kill = 1 PR), Titel: `kill: <pfad> — no survey-solver caller`. |
| 162 | +4. PR-Description enthält den grep-Output vollständig. |
| 163 | +5. Wenn Matches > 0: **kein Kill**, statt dessen Issue mit Label `mission-debt` und Migrations-Plan. |
| 164 | + |
| 165 | +--- |
| 166 | + |
| 167 | +## 6. Meta-Lügen, die heute (2026-05-13) im Repo stehen |
| 168 | + |
| 169 | +Diese werden separat in `incidents/CRITIC-AUDIT-2026-05-13.md` belegt. Kurzfassung: |
| 170 | + |
| 171 | +1. README verweist auf `AGENTS.md`, `sinrules.md`, `brain.md`, `fix.md`, `registry.md` am Root — nur diese Datei (`AGENTS.md`) existiert; die anderen vier fehlen. |
| 172 | +2. Issue #212 listet PRs #209, #215, #216 als "merged, CI grün". Die zugehörigen Module (`visual_hash`, `attestation`, `dom_stability`) sind im Repo nicht auffindbar. |
| 173 | +3. PR #175 ("Verifier-Node") ist als gemergt gelistet, aber kein `state.verify`-Flag oder Verifier-Knoten im Survey-Graph. |
| 174 | + |
| 175 | +→ **Konsequenz für Critic**: PR-Merge-Status der Issue-Tracker-Tabelle ist keine Quelle der Wahrheit. **Source of Truth = Filesystem + Call-Graph.** |
| 176 | + |
| 177 | +--- |
| 178 | + |
| 179 | +## 7. Eskalation |
| 180 | + |
| 181 | +Jeder BLOCKER (etwas, das den nächsten Live-Run garantiert killt): |
| 182 | + |
| 183 | +1. Sofort separates Issue mit Label `blocker` (Critic schlägt vor; nur Maintainer öffnen). |
| 184 | +2. Pointer-Kommentar in **Issue #212** (CEO-Status). |
| 185 | +3. Eintrag in `incidents/CRITIC-AUDIT-LATEST.md` (Sektion BLOCKER). |
| 186 | +4. Nicht warten bis Gesamtbericht fertig ist. |
| 187 | + |
| 188 | +--- |
| 189 | + |
| 190 | +## 8. Anti-Patterns (Critic darf NICHT tun) |
| 191 | + |
| 192 | +- "Looks good" sagen ohne Beweis. |
| 193 | +- Tests als Beweis akzeptieren, ohne den Produktionspfad zu prüfen. |
| 194 | +- Neue Features vorschlagen — wir wollen **weniger** Lügen, nicht mehr Code. |
| 195 | +- Mass-Delete ohne Beweis-Sequenz aus Sektion 5. |
| 196 | +- PRs reviewen (das macht der Reviewer-Agent). |
| 197 | +- Code-Style anmerken (das macht `ruff`). |
| 198 | + |
| 199 | +--- |
| 200 | + |
| 201 | +## 9. Schluss |
| 202 | + |
| 203 | +> Du musst nichts beweisen. Du musst nur die Wahrheit finden, ob unsere "Meister"-Behauptung Bestand hat |
| 204 | +> oder ob wir uns selbst belügen. **Im Zweifel: Annahme = Lüge bis zum Gegenbeweis.** |
| 205 | +> — Agent One, 2026-05-13 (Issue #218) |
0 commit comments