{
  "task_id": "DOCS-RESTRUCTURE-001",
  "summary": "Kompletter Umbau der Dokumentation im Verzeichnis docs nach einem strikt angewendeten Diátaxis-Modell mit genau vier Quadranten (Tutorials, How-to, Explanation, Reference), konsequenter Umbenennung der Markdown-Dateien, Migration der Agent-Dokumente aus dem Unterordner in Top-Level-Slugs und vollständiger Aktualisierung aller internen Doku-Links ohne fachliche Inhaltsänderung.",
  "assumptions": [
    "Alte /admin/docs/<slug>-Links dürfen brechen; es werden keine Kompatibilitäts-Stubs für alte Slugs vorgesehen.",
    "Die technische Scope-Grenze bleibt bei doc/*; es werden keine Änderungen in lib/, pages/, templates/ oder web/ vorgenommen.",
    "Weil der aktuelle Docs-Parser nur /docs/<slug>.md indexiert, müssen alle Markdown-Zieldateien im Top-Level docs/ liegen (kein docs/agents/*.md im Zielzustand).",
    "docs/openapi.yaml bleibt unter exakt diesem Pfad bestehen, da der API-Docs-Endpunkt diese Datei fest referenziert.",
    "Die Aufgabe ist rein strukturell/redaktionell (Verständlichkeit, IA, Navigierbarkeit) und prüft keine fachliche Korrektheit der Inhalte."
  ],
  "scope": {
    "in": [
      "docs/index.md",
      "alle Markdown-Dateien in docs/*.md",
      "Migration von docs/agents/*.md zu neuen Top-Level-Dateien in docs/",
      "Aktualisierung interner Links und Verweise innerhalb docs/*.md",
      "Beibehaltung und Verlinkung von docs/openapi.yaml innerhalb der neuen Reference-Struktur"
    ],
    "out": [
      "neue fachliche Themen",
      "UI-Redesign oder Änderungen am Docs-Renderer",
      "Änderungen an Routing/Parser/Service-Code außerhalb docs/",
      "inhaltliche Fachvalidierung bestehender technischer Aussagen"
    ]
  },
  "guardrails": {
    "required_guard_ids": [
      "GR-UI-009",
      "GR-SEC-004"
    ],
    "required_quality_gate_ids": [
      "QG-001",
      "QG-002",
      "QG-003",
      "QG-004"
    ]
  },
  "success_criteria": [
    {
      "id": "SC-001",
      "criterion": "docs/index.md enthält exakt vier Diátaxis-Hauptgruppen in dieser Reihenfolge: Tutorials, How-to Guides, Explanation, Reference."
    },
    {
      "id": "SC-002",
      "criterion": "Alle bisherigen 42 Markdown-Dokumente (39 in docs/*.md plus 3 aus docs/agents/*.md) sind auf neue Diátaxis-konforme Slugs migriert und liegen danach vollständig im Top-Level docs/."
    },
    {
      "id": "SC-003",
      "criterion": "Jede Markdown-Datei (außer docs/index.md) ist genau einmal in docs/index.md referenziert; es gibt keine Orphans und keine Duplikat-Referenzen."
    },
    {
      "id": "SC-004",
      "criterion": "Alle internen /docs/*.md-Verweise in der Doku zeigen auf existierende neue Slugs; es bleiben keine Verweise auf alte Slugs oder /docs/agents/*.md übrig."
    },
    {
      "id": "SC-005",
      "criterion": "Alle migrierten Seiten behalten genau ein H1 und eine Zeile 'Letzte Aktualisierung: YYYY-MM-DD' und sind sprachlich auf Klarheit/Lesbarkeit in ihrem Diátaxis-Typ harmonisiert."
    },
    {
      "id": "SC-006",
      "criterion": "docs/openapi.yaml bleibt unverändert am Pfad docs/openapi.yaml und wird in der neuen Reference-Struktur konsistent verlinkt."
    },
    {
      "id": "SC-007",
      "criterion": "Admin-Dokumentation unter /admin/docs funktioniert mit der neuen Struktur: Navigation zeigt alle Gruppen/Seiten, Seiteninhalte und TOC-Anker laden korrekt, Suche liefert Treffer auf umbenannte Seiten."
    },
    {
      "id": "SC-008",
      "criterion": "Alle festgelegten Quality Gates (QG-001, QG-002, QG-003, QG-004) sind erfolgreich ausgeführt und Guard-Evidence für GR-UI-009 und GR-SEC-004 ist dokumentiert."
    }
  ],
  "implementation_steps": [
    {
      "id": "S1",
      "title": "Verbindliche Ziel-IA und Rename-Konvention festlegen",
      "description": "Definiere als harte Regel: Dateinamenformat <quadrant-prefix>-<slug>.md, wobei Prefix nur tutorial-, howto-, explanation-, reference- ist. Lege die vollständige Zuordnung fest: Tutorials = erste-schritte, 00-systemueberblick, 01-setup-und-erster-login, 03-architektur-request-flow, 04-erste-aenderung-ui, 05-erste-aenderung-backend, 06-security-tenant-scope, 07-api-erweitern, 08-advanced-scheduler-sso; How-to = erste-aenderung, globale-suche, importe, benutzerdefinierte-felder, geplante-aufgaben, auth-sso-smoke-test, anfragelimits, rbac-permissions-playbook, request-input-validation, docker-lokal, docker-produktiv, betriebscheck-doctor, fehlerbehebung, lokale-entwicklung, dokumentation-erweitern; Explanation = architektur, di-container, sicherheitsmodell, einstellungen-speicherung, docker-betrieb; Reference = 02-domain-glossar, api, konfiguration, konventionen, lib-standards, benutzer-lifecycle-policy, frontend-css, frontend-javascript, entwickler-checkliste, codex-prompts sowie agents/overview, agents/roles, agents/flow.",
      "guard_refs": [
        "GR-UI-009",
        "GR-SEC-004"
      ]
    },
    {
      "id": "S2",
      "title": "Dateien konsequent umbenennen und Agents ins Top-Level migrieren",
      "description": "Benenne alle Markdown-Dateien gemäß Mapping um. Tutorials nummeriert als tutorial-01-erste-schritte bis tutorial-09-advanced-scheduler-sso; How-to als howto-<alter-slug>; Explanation als explanation-<alter-slug>; Reference als reference-<alter-slug>. Migriere docs/agents/overview.md, docs/agents/roles.md, docs/agents/flow.md zu docs/reference-agents-overview.md, docs/reference-agents-roles.md, docs/reference-agents-flow.md und entferne anschließend den Unterordner docs/agents aus der aktiven Struktur.",
      "guard_refs": [
        "GR-UI-009"
      ]
    },
    {
      "id": "S3",
      "title": "docs/index.md strikt auf vier Diátaxis-Gruppen umbauen",
      "description": "Ersetze die bestehende gemischte Struktur in docs/index.md vollständig durch genau vier Gruppen: Tutorials, How-to Guides, Explanation, Reference. Trage jede Ziel-Datei genau einmal ein, behalte das bestehende Linkformat /docs/<slug>.md bei (wegen Parser), und aktualisiere 'Letzte Aktualisierung' auf den Migrationstag.",
      "guard_refs": [
        "GR-UI-009"
      ]
    },
    {
      "id": "S4",
      "title": "Alle internen Links und Querverweise auf neue Slugs migrieren",
      "description": "Führe eine vollständige Link-Migration in allen docs/*.md durch: alte Slugs, alte nummerierte Lernpfad-Dateinamen und /docs/agents/*-Verweise durch neue Diátaxis-Slugs ersetzen; Referenzen auf docs/openapi.yaml bestehen lassen. Stelle sicher, dass keine tote Verlinkung und kein Alt-Slug-Backlink verbleibt.",
      "guard_refs": [
        "GR-UI-009",
        "GR-SEC-004"
      ]
    },
    {
      "id": "S5",
      "title": "Lesbarkeits- und Diátaxis-Format normalisieren",
      "description": "Harmonisiere die Seitenstruktur ohne fachliche Neuinhalte: pro Seite genau ein H1, 'Letzte Aktualisierung', klarer Zielabschnitt und Diátaxis-typische Abschnittsreihenfolge (Tutorial: Lernschritte/Ergebnis; How-to: Voraussetzungen/Schritte/Validierung; Explanation: Kontext/Warum/Abgrenzung; Reference: Fakten, Kontrakte, Tabellen). Passe auch die Contributor-Regeln in der umbenannten How-to-Dokumentationsseite an die neue IA an.",
      "guard_refs": [
        "GR-UI-009"
      ]
    },
    {
      "id": "S6",
      "title": "Guard-Checks, Quality-Gates und Docs-Smoke ausführen",
      "description": "Führe die strukturellen Doku-Checks und alle geforderten Gates aus, dokumentiere Ergebnisse nach SC-ID: Link-Konsistenz, Index-Abdeckung, keine Remote-Asset-Einbindung in Markdown, anschließend QG-001, QG-002, QG-003, QG-004. Abschließend manueller Smoke in /admin/docs für Navigation, TOC-Anker und Suche.",
      "guard_refs": [
        "GR-UI-009",
        "GR-SEC-004"
      ]
    }
  ],
  "tests": [
    "Index-Strukturcheck: docs/index.md enthält exakt 4 H2-Gruppen (Tutorials, How-to Guides, Explanation, Reference) in dieser Reihenfolge.",
    "Abdeckungscheck ohne Orphans/Duplikate: Vergleich docs/*.md (ohne index.md) gegen alle in docs/index.md referenzierten /docs/<slug>.md muss leer sein.",
    "Subfolder-Check: find docs -mindepth 2 -name '*.md' liefert 0 Treffer (keine verbleibenden docs/agents/*.md).",
    "Alt-Link-Check: rg auf alte Slugs und /docs/agents/ in docs/*.md liefert 0 Treffer.",
    "Link-Existenzcheck: jeder /docs/<slug>.md-Verweis in docs/*.md zeigt auf eine vorhandene Datei docs/<slug>.md.",
    "GR-SEC-004 Check: rg nach externen Asset-Einbindungen in Markdown (z. B. ![](...https://...), <script>, <link>, @import url(https://)) liefert 0 Treffer.",
    "Dokumentenformat-Check: jede Datei in docs/*.md hat genau ein H1 und eine Zeile 'Letzte Aktualisierung: YYYY-MM-DD'.",
    "Manueller Docs-Smoke: /admin/docs lädt, Gruppennavigation vollständig, TOC-Anker springen korrekt, Suche findet Treffer in umbenannten Seiten.",
    "QG-001: docker compose exec php vendor/bin/phpunit",
    "QG-002: docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress",
    "QG-003: docker compose exec php vendor/bin/phpunit tests/Architecture/CoreStarterkitContractTest.php",
    "QG-004: Structural rg checks gemäß agent-system/checks/quality-gates.json"
  ],
  "acceptance_checks": [
    "SC-001: Sichtprüfung docs/index.md bestätigt exakt vier Diátaxis-Gruppen in korrekter Reihenfolge.",
    "SC-002: Dateiinventur zeigt 42 migrierte Markdown-Seiten im Top-Level docs/ und keine verbleibenden docs/agents/*.md.",
    "SC-003: Abdeckungscheck (Dateiliste vs. Index-Referenzen) ist leer und ohne Duplikate.",
    "SC-004: Alt-Link-Check und Link-Existenzcheck laufen ohne Treffer/Fehler.",
    "SC-005: Format-Check bestätigt pro Seite 1x H1 + Letzte-Aktualisierung + lesbare Diátaxis-Struktur.",
    "SC-006: docs/openapi.yaml existiert unverändert und ist in der Reference-Sektion korrekt verlinkt.",
    "SC-007: Manueller Smoke in /admin/docs bestätigt Navigation, Inhaltsanzeige, TOC und Suche für neue Slugs.",
    "SC-008: QG-001, QG-002, QG-003 und QG-004 sind mit PASS dokumentiert; Guard-Evidence für GR-UI-009 und GR-SEC-004 liegt vor."
  ],
  "risks": [
    {
      "risk": "Große Rename-Migration kann interne Links oder Suchpfade unbemerkt brechen.",
      "mitigation": "Vollständige Alt-Link- und Link-Existenz-Checks automatisiert ausführen und erst nach fehlerfreiem Ergebnis finalisieren."
    },
    {
      "risk": "Durch Wegfall alter Slugs verlieren bestehende Bookmarks und gespeicherte Admin-Docs-Links ihre Gültigkeit.",
      "mitigation": "Breaking explizit dokumentieren, neue Diátaxis-Slug-Liste im Changelog/Release-Hinweis veröffentlichen."
    },
    {
      "risk": "Beim Vereinheitlichen der Struktur könnten unbeabsichtigt fachliche Aussagen verändert werden.",
      "mitigation": "Redaktionelle Änderungen auf Struktur/Klarheit begrenzen, fachliche Sätze nicht neu interpretieren, Diff-Review mit Fokus auf semantische Unverändertheit."
    },
    {
      "risk": "Nicht beachtete Parser-Regeln für docs/index.md könnten dazu führen, dass Seiten trotz vorhandener Datei nicht im Admin auftauchen.",
      "mitigation": "Index strikt im erwarteten /docs/<slug>.md-Format pflegen und nach jeder größeren Index-Änderung /admin/docs-Smoketest durchführen."
    }
  ]
}