/recovery-audit

description: "Audit all SEO changes made to a domain within a given period. Read-only audit_only mode."
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, mcp__*

Recovery Audit

Zweck

Auditiert alle SEO-Aenderungen an einer Domain innerhalb eines Zeitraums: Change-Inventar, fehlgeschlagene Versuche, unverifizierte Aenderungen, Risiko- und Approval-Compliance, Rollback-Readiness, Settlement-Gate-Status und Hypothesen-Registry. Read-only gegenueber dem Live-Shop — das Audit stellt fest, was passiert ist, und bewertet es; es aendert nichts.

Change Governance

Mode: immer `audit_only`. Change Budget: 0. Keine Live-Shop-Writes. Schreibt nur Report-Artefakte nach `~/.cache/seo-rescue/{slug}/` (via `lib/safe.js`, siehe Schritt 9).

Settlement Gate Awareness

Dieses Command ist read-only gegenueber dem Live-Shop — ein aktiver Settlement Gate (`references/SEO_SETTLEMENT_GATE.md`) blockiert es NIE. Sonderrolle: **`recovery-audit` ist der Writer der Gate-Datei** `~/.cache/seo-rescue/{slug}/recovery-gate.json` — alle anderen Commands (diagnose, plan, monitor, full) lesen sie nur. Die Gate-Detection selbst ist Teil des Ablaufs (Schritt 7).

Trigger

/seo-rescue:recovery-audit <domain> [--days 14]

Input-Kontrakt

| Feld | Quelle | Pflicht | |------|--------|---------| | `domain` | CLI-Argument | ja | | `--days` | CLI-Flag | nein — Default: `14` |

`--days` definiert das Audit-Fenster: `period_end` = jetzt, `period_start` = jetzt minus `--days` Tage. Wird das Command vom Orchestrator (`recovery-full`) ohne Flag aufgerufen, gilt der Default 14.

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('aud-' + randomUUID().slice(0,8) + '-' + Date.now())"

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

Schritt 4: Audit-Zeitraum bestimmen

`period_start` / `period_end` aus `--days` berechnen (Default 14) und im Output festhalten. Alle folgenden Schritte betrachten nur Aenderungen innerhalb dieses Fensters.

Schritt 5: Change-History lesen oder rekonstruieren

Primaerquelle ist `~/.cache/seo-rescue/{slug}/change-history.ndjson`. Fehlt sie oder ist sie unvollstaendig, rekonstruiere aus diesen Quellen **in Prioritaetsreihenfolge**:

1. `~/.cache/seo-rescue/{slug}/change-history.ndjson` (primaer, audit-safe) 2. `~/.cache/seo-rescue/{slug}/snapshots/` (lokale CMS-Slot-Snapshots und andere Before/After-Artefakte; werden von externem Tooling erzeugt — read-if-present, fehlende Snapshots sind kein Fehler) 3. **Shopware-API-`updatedAt`-Felder** mit `--days`-Filter auf: `seo-url`, `category`, `product`, `cms-slot` (nicht zuverlaessig — siehe Audit-Gap-Marker), `system-config`, `dreisc-seo-redirect` 4. Shell-History / Claude-Conversation-Logs (falls zugreifbar) 5. Shopware-Ist-Zustand vs. bekannte Snapshots 6. Screaming-Frog-Crawl-Diffs (mehrere Crawls vergleichen, falls vorhanden) 7. Live-HTTP-Checks (aktueller Zustand) 8. DataForSEO- / Sistrix- / GSC-Snapshots 9. Manuelle Ableitung aus Operator-Gedaechtnis oder Notizen

**Rekonstruktions-Marker:** Jeder rekonstruierte Eintrag muss enthalten:

{
  "reconstructed": true,
  "reconstruction_sources": ["..."],
  "reconstruction_confidence": "high|medium|low",
  "audit_source": "shopware_updatedAt_reconstruction"
}

Fehlt `change-history.ndjson` vollstaendig, setze im Audit-Output `"not_audit_safe_reconstruction": true`.

Schritt 6: Audit-Felder erheben

Das Audit muss fuer jede erkannte Aenderung erfassen:

• Change-Inventar (Tabelle)
• Fehlgeschlagene Change-Versuche (API-500er, falsche Slugs)
• Unverifizierte Aenderungen (via API-State erkannt, aber nicht live-bestaetigt)
• Risiko-Bewertung (verbrauchte Risk Points gesamt)
• Approval-Compliance (Aenderungen ohne ordentliches Approval)
• Rollback-Readiness (Aenderungen ohne dokumentierten Rollback)
• **Erkannte Shopware-seo-url-Kollisionen** (Entities mit mehreren non-deleted Eintraegen pro foreignKey)
• **Erkannte DreiscSeo-301→404-Ketten**
• **Medical-/Compliance-Term-Flags**
• Empfehlungen (`keep | observe | fix | rollback | dev_ticket`)

Schritt 7: Settlement-Gate-Detection

Das Audit muss erkennen:

• **Last Major Batch** — juengste Session, die die Trigger-Schwellen aus `references/SEO_SETTLEMENT_GATE.md` section 3 ueberschritten hat
• **Anzahl der Aenderungen** in diesem Batch
• **Verbrauchtes Change Budget** — Risk Points ueber den Batch summiert
• **Settlement-Gate-Status** — `active | ended | never_triggered`
• **Aktuelles Unlock-Level** — `blocked | partial | open` per `schemas/recovery-gate.schema.json`
• Ob aktuell weitere Live-Aenderungen erlaubt sind

Erkennt das Audit einen Major Batch, der nicht mit `triggered_settlement_gate: true` geloggt wurde:

1. Berechne `started_at`, `minimum_until`, `recommended_until` 2. Schreibe `~/.cache/seo-rescue/{slug}/recovery-gate.json` mit `settlement_gate_active: true` und rueckdatierten Werten — via `atomicWriteJSON()` unter Lock (siehe Schritt 9) 3. Appende ein `gate_activated`-Event an die `gate_history` der Gate-Datei (append-only, niemals bestehende Eintraege ueberschreiben) 4. Emittiere ein Finding `gate_activated_retroactively` mit Severity `high`

Schritt 8: Hypothesis Registry aufbauen

Das Audit emittiert ein `hypothesis_registry`-Array. Fuer jede Ursachen-Attribution (bei erfolgreichen Aenderungen, fehlgeschlagenen Versuchen oder offenen Risiken) enthaelt die Registry einen Eintrag per `schemas/hypothesis-verification.schema.json`.

Das Audit