167 lines
11 KiB
JSON
167 lines
11 KiB
JSON
|
{
|
||
|
|
"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. , <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."
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|