/recovery-monitor

description: "Weekly recovery tracking with VI, keyword data, and Change History effect tracking."
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, mcp__*

Recovery Monitor

Zweck

Woechentliches Recovery-Tracking. Holt aktuelle VI + Keyword-Daten, berechnet Recovery-Score, appendet an die History-Datei. Laeuft auch bei fehlenden Datenquellen durch und schreibt einen Partial-Eintrag — der Zeitstempel allein ist wertvoll fuer die Zeitreihe.

Change Governance

Mode: `read_only`. Change Budget: 0. Keine Live-Shop-Writes. Schreibt nur History-Artefakte (`history.ndjson`, append-only, via `lib/safe.js`).

Wenn `change-history.ndjson` existiert, wird sie fuer die Change-History-Integration gelesen und im Eintrag referenziert (siehe `## Change History Integration`). Jede Score-Bewegung traegt Quelle und Confidence.

Settlement Gate Awareness

Dieses Command ist read-only gegenueber dem Live-Shop (`audit_only`, Change Budget 0, schreibt nur Cache-Artefakte) — ein aktiver Settlement Gate (`references/SEO_SETTLEMENT_GATE.md`) blockiert es NIE. Es muss den Gate-State aber kennen und ausweisen:

1. Lies `~/.cache/seo-rescue/{slug}/recovery-gate.json`, falls vorhanden. **Writer dieser Datei ist `recovery-audit`** (siehe `commands/recovery-audit.md`, Schritt 7: Settlement-Gate-Detection) — recovery-monitor liest sie nur. Fehlt die Datei, gilt der Gate als `never_triggered`: keine Warnung, normaler Ablauf. 2. Falls `settlement_gate_active = true`:

• Monitoring laeuft normal weiter — read-only Tracking ist waehrend eines aktiven Gates immer erlaubt und ausdruecklich erwuenscht (der Gate braucht Re-Evaluation-Daten).
• In den History-Eintrag (Top-Level) das Feld `settlement_gate_status` aufnehmen, gespiegelt aus der Gate-Datei:

     "settlement_gate_status": {
       "active": true,
       "next_allowed_review_date": "2026-06-06",
       "unlock_status": "blocked"
     }

(`unlock_status`: `blocked | partial | open`, direkt aus der Gate-Datei uebernommen.)

• In der User-Ausgabe (Delta-Report) eine Zeile ausgeben: `Settlement Gate: AKTIV bis {next_allowed_review_date} — read-only Monitoring erlaubt, Live-Aenderungen blockiert`
• Jeder Empfehlungstext darf KEINE sofortigen Live-Aenderungen vorschlagen. Naechste Schritte als "jetzt vorbereiten/Drafts erstellen, Ausfuehrung nach Gate-Re-Evaluation" formulieren (`prepare_now_execute_later`-Prinzip aus `SEO_SETTLEMENT_GATE.md`).
• **Score-Bewegung waehrend aktivem Gate:** Wenn der Recovery Score stark gefallen ist (Drop > 15 Punkte gegenueber dem letzten History-Eintrag), KEINE korrigierende Live-Aktion empfehlen. Stattdessen empfehlen, die Beobachtung in die Gate-Re-Evaluation am `next_allowed_review_date` mitzunehmen — der Gate existiert genau dafuer, dass frisches Post-Batch-Rauschen nicht sofort beantwortet wird. Das gilt auch fuer Rollback-Empfehlungen aus der Change-History-Integration: Anomalies werden geflagged und fuer die Re-Evaluation dokumentiert; ob daraus ein Emergency-Rollback per `SEO_SETTLEMENT_GATE.md` section 7 wird, entscheidet der Operator.

3. Falls Gate-Datei fehlt oder `settlement_gate_active = false`: `settlement_gate_status: { "active": false }` in den History-Eintrag schreiben. Keine User-Ausgabe-Zeile noetig.

Trigger

`/seo-rescue:recovery-monitor <domain>`

Input-Kontrakt

| Feld | Quelle | Pflicht | |------|--------|---------| | `domain` | CLI-Argument | ja |

Script CLI Contract

node scripts/recovery-monitor.js --domain <domain> --cache-dir <path>

| Exit Code | Bedeutung | |-----------|-----------| | `0` | Monitor-Eintrag geschrieben (complete oder partial) | | `1` | Monitor fehlgeschlagen (kein Eintrag geschrieben) | | `2` | Security-Abbruch (Symlink, Path-Traversal) | | `3` | Lock-Timeout (anderer Command laeuft) |

Ablauf

Schritt 1: Domain normalisieren

Normalisiere den Input via `normalizeDomain()` aus `lib/safe.js` — gibt `input_domain`, `domain`, `canonical_domain`, `slug` zurueck.

Schritt 2: Cache-Verzeichnis anlegen

`ensureDomainDir(slug)` — Modus 0700, Abbruch bei Symlink.

Schritt 3: Run-ID generieren

Falls eine `run_id` vom Orchestrator (`recovery-full`) uebergeben wurde: diese unveraendert verwenden, KEIN eigenes Prefix erzeugen. Sonst generiere eine eindeutige Run-ID fuer diesen Lauf:

node -e "const { randomUUID } = require('crypto'); console.log('mon-' + randomUUID().slice(0,8) + '-' + Date.now())"

Speichere die Run-ID als `run_id`. Sie wird im Output-Schema mitgefuehrt.

Schritt 4: Sistrix VI abrufen

Rufe Sistrix API fuer aktuellen VI-Wert auf.

Falls nicht verfuegbar:

• Warnung eintragen: `"Sistrix nicht erreichbar — VI-Komponente faellt aus Score"`
• `vi = null`
• Weiter — Monitor laeuft auch ohne VI durch

Schritt 5: DataForSEO ranked_keywords abrufen

Rufe DataForSEO MCP `ranked_keywords/live` auf (location 2276, Deutschland).

Extrahiere:

• `keywords_t10`: Anzahl Keywords in Top-10
• `keywords_total`: Gesamtzahl rankender Keywords

Falls DataForSEO MCP nicht verfuegbar:

• Pruefe ob `~/.cache/seo-rescue/{slug}/imports/keywords.csv` existiert (CSV-Fallback)
• Falls CSV verfuegbar: Keywords aus CSV laden, `source_notes` eintragen
• Falls beides nicht verfuegbar: Warnung, `keywords_t10 = null`
• Weiter — Monitor laeuft auch ohne Keyword-Daten durch

Schritt 6: Issue-Daten-Aktualitaet pruefen

Pruefe ob `~/.cache/seo-rescue/{slug}/issues.json` existiert und sein Timestamp aktuell ist (< 7 Tage alt).

Setze `issue_data_fresh`:

• `true`: issues.json existiert und ist < 7 Tage alt
• `false`: issues.json fehlt, status=failed, oder > 7 Tage alt

Hinweis: Wenn `issue_data_fresh = false`, wird `issues_fixed` im Score auf `null` gesetzt — keine Claim ueber Issue-Reduktion ohne frische Crawl-Daten.

Schritt 7: Score berechnen und History schreiben

Rufe das Helper-Script auf. Die reale Signatur ist `writeMonitorEntry(inputDomain, domain, slug, vi, keywordsT10, warnings, errors, options