diff --git a/README.md b/README.md index 4c6d276..de3efc2 100644 --- a/README.md +++ b/README.md @@ -72,9 +72,9 @@ docker compose -f docker-compose.prod.yml up --build -d Details stehen in: -- `/docs/docker-lokal.md` -- `/docs/docker-produktiv.md` -- `/docs/docker-betrieb.md` (Übersicht) +- `/docs/howto-docker-lokal.md` +- `/docs/howto-docker-produktiv.md` +- `/docs/explanation-docker-betrieb.md` (Übersicht) ## Seed-Daten @@ -216,12 +216,12 @@ docker compose exec php composer cs:fix ## Dokumentation - `/docs/index.md` Dokumentationsstart mit chronologischem Lernpfad und Referenzbereichen -- `/docs/00-systemueberblick.md` Einstieg in Produktbild und Kernprinzipien -- `/docs/01-setup-und-erster-login.md` lokales Setup und erster Smoke-Test -- `/docs/02-domain-glossar.md` zentrale Begriffe fuer Tenant/Role/Scope -- `/docs/03-architektur-request-flow.md` Request-Flow und Schichtmodell -- `/docs/06-security-tenant-scope.md` Security-Grundlagen vor Feature-Arbeit -- `/docs/07-api-erweitern.md` verbindlicher API-Aenderungsablauf inkl. OpenAPI +- `/docs/tutorial-02-systemueberblick.md` Einstieg in Produktbild und Kernprinzipien +- `/docs/tutorial-03-setup-und-erster-login.md` lokales Setup und erster Smoke-Test +- `/docs/reference-domain-glossar.md` zentrale Begriffe fuer Tenant/Role/Scope +- `/docs/tutorial-04-architektur-request-flow.md` Request-Flow und Schichtmodell +- `/docs/tutorial-07-security-tenant-scope.md` Security-Grundlagen vor Feature-Arbeit +- `/docs/tutorial-08-api-erweitern.md` verbindlicher API-Aenderungsablauf inkl. OpenAPI ## Troubleshooting diff --git a/agent-system/README.md b/agent-system/README.md index 7ad0985..343aca4 100644 --- a/agent-system/README.md +++ b/agent-system/README.md @@ -12,3 +12,4 @@ Structure: References: - Planner standard: `tools/codex-skills/starterkit-planner/SKILL.md` - Guardrails: `tools/codex-skills/core-guardrails/SKILL.md` +- Docs/Skills audit policy: `agent-system/checks/docs-skills-audit-policy.md` diff --git a/agent-system/checks/docs-skills-audit-policy.md b/agent-system/checks/docs-skills-audit-policy.md new file mode 100644 index 0000000..166738f --- /dev/null +++ b/agent-system/checks/docs-skills-audit-policy.md @@ -0,0 +1,27 @@ +# Docs/Skills Audit Policy + +Letzte Aktualisierung: 2026-03-09 + +## Ziel + +Einheitliche Einstufung und Ablage von Findings fuer Docs-/Skills-Audits. + +## Severity-Klassen + +- `P0`: Kritischer Produktions- oder Sicherheitsimpact. +- `P1`: Hoher Architektur-/Compliance-Impact, kurzfristig zu beheben. +- `P2`: Mittlerer Impact, kein unmittelbarer Betriebsblocker. +- `P3`: Niedriger Impact, redaktionell oder kosmetisch. + +## Persistenzregeln + +- `P0` und `P1` muessen als eigener Run unter `agent-system/runs/` dokumentiert werden. +- Naming fuer diese Runs: `DOCS-SKILLS-AUDIT-00x` (fortlaufend). +- `P2` und `P3` werden kompakt im laufenden Audit-Protokoll gesammelt und spaeter gebuendelt umgesetzt. + +## Mindestinhalt pro grossem Finding-Run (`P0`/`P1`) + +- Finding-ID, Severity, betroffene Dateien. +- Reproduzierbare Evidenz (Befehl/Output oder Dateiverweis). +- Geplante Mitigation inkl. Guard-/Gate-Bezug. +- Abschlussstatus (`open`, `resolved`, `accepted-risk`). diff --git a/bin/codex-skills-sync.sh b/bin/codex-skills-sync.sh index a2cada6..f76bcfa 100755 --- a/bin/codex-skills-sync.sh +++ b/bin/codex-skills-sync.sh @@ -50,6 +50,8 @@ target_dir="${codex_home_dir}/skills" managed_skills=( "core-guardrails" "starterkit-planner" + "starterkit-grid-standards" + "starterkit-php-style-ci" ) for skill in "${managed_skills[@]}"; do @@ -70,7 +72,7 @@ check_skill() { fi local diff - diff="$(rsync -rcn --delete --itemize-changes "${src}/" "${dst}/" || true)" + diff="$(diff -qr "${src}" "${dst}" || true)" if [[ -n "${diff}" ]]; then echo "[DRIFT] ${skill} differs:" echo "${diff}" | sed 's/^/ /' diff --git a/docs/howto-erste-aenderung.md b/docs/howto-erste-aenderung.md index 5241439..e2905ac 100644 --- a/docs/howto-erste-aenderung.md +++ b/docs/howto-erste-aenderung.md @@ -1,6 +1,6 @@ # Leitfaden für die erste Änderung -Letzte Aktualisierung: 2026-03-06 +Letzte Aktualisierung: 2026-03-09 ## Ziel @@ -37,7 +37,7 @@ Ein neuer Entwickler soll den ersten Change strukturiert und reproduzierbar umse 2. Permission- und Tenant-Scope-Prüfungen beibehalten 3. Optional Service/Repository ergänzen, Instanziierung über `app(...)`/Factory-Standards 4. `docs/openapi.yaml` aktualisieren -5. `docs/api.md` mit Beispiel aktualisieren +5. `/docs/reference-api.md` mit Beispiel aktualisieren 6. Bei neuen Berechtigungen: `PermissionService` + `init.sql` synchron halten, für Bestandsumgebungen idempotentes SQL-Update in `db/updates/*.sql` bereitstellen ### Done-Kriterien diff --git a/docs/howto-lokale-entwicklung.md b/docs/howto-lokale-entwicklung.md index 80b8da6..3587a0e 100644 --- a/docs/howto-lokale-entwicklung.md +++ b/docs/howto-lokale-entwicklung.md @@ -1,6 +1,6 @@ # Lokale Entwicklung -Letzte Aktualisierung: 2026-03-06 +Letzte Aktualisierung: 2026-03-09 ## Ziel @@ -55,8 +55,8 @@ Bei JS-Änderungen zusätzlich Browser-Smoke mit DevTools-Console (keine JS-Erro ## API-spezifisch - `docs/openapi.yaml` aktualisieren -- bei Bedarf `docs/api.md` ergänzen -- bei Security-Änderungen `docs/sicherheitsmodell.md` aktualisieren +- bei Bedarf `/docs/reference-api.md` ergänzen +- bei Security-Änderungen `/docs/explanation-sicherheitsmodell.md` aktualisieren ## Vertiefung diff --git a/docs/index.md b/docs/index.md index 47415f1..be5c8f5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ # Dokumentation -Letzte Aktualisierung: 2026-03-06 +Letzte Aktualisierung: 2026-03-09 Diese Dokumentation ist nach dem Diataxis-Modell in vier Quadranten gegliedert: Tutorials zum Lernen, How-to Guides zum Nachschlagen von Aufgaben, Explanation zum Verstehen und Reference zum Nachschlagen von Fakten. @@ -93,6 +93,8 @@ Diese Dokumentation ist nach dem Diataxis-Modell in vier Quadranten gegliedert: - Definition of Done vor Merge. - `/docs/reference-codex-prompts.md` - Standard-Prompts fuer Skill-basierte Planung und Implementierung. +- `/docs/reference-extension-readiness.md` + - Verbindliche Vorbedingungen fuer spaetere Module ohne Hook-/Lifecycle-Festlegung. - `/docs/reference-agents-overview.md` - Einstieg in das Rollenmodell und die Artefakte. - `/docs/reference-agents-roles.md` diff --git a/docs/reference-agents-overview.md b/docs/reference-agents-overview.md index b3ef9f6..4ab4846 100644 --- a/docs/reference-agents-overview.md +++ b/docs/reference-agents-overview.md @@ -1,6 +1,6 @@ # Agent Workflow Overview -Letzte Aktualisierung: 2026-03-06 +Letzte Aktualisierung: 2026-03-09 This project uses a multi-role workflow for issue and feature delivery. @@ -24,6 +24,6 @@ Source of truth: - quality gates: `agent-system/checks/quality-gates.json` Entry points: -- roles: `docs/agents/roles.md` -- workflow: `docs/agents/flow.md` +- roles: `/docs/reference-agents-roles.md` +- workflow: `/docs/reference-agents-flow.md` - schemas and prompts: `agent-system/` diff --git a/docs/reference-codex-prompts.md b/docs/reference-codex-prompts.md index 647aa2e..619eb2c 100644 --- a/docs/reference-codex-prompts.md +++ b/docs/reference-codex-prompts.md @@ -1,6 +1,6 @@ # Codex Prompt-Standards -Letzte Aktualisierung: 2026-03-06 +Letzte Aktualisierung: 2026-03-09 ## Ziel @@ -63,3 +63,4 @@ Regel: 1. Keine impliziten Extension-Standards erfinden. 2. Erweiterungen explizit als Out-of-Scope kennzeichnen. 3. Nur dokumentieren, was bereits verbindlich im Repo festgelegt ist. +4. Vor Implementierungsstart die Vorbedingungen aus `/docs/reference-extension-readiness.md` prüfen. diff --git a/docs/reference-extension-readiness.md b/docs/reference-extension-readiness.md new file mode 100644 index 0000000..6268d51 --- /dev/null +++ b/docs/reference-extension-readiness.md @@ -0,0 +1,41 @@ +# Extension-Readiness (ohne Architektur-Festlegung) + +Letzte Aktualisierung: 2026-03-09 + +## Ziel + +Verbindliche Vorbedingungen fuer spaetere eigenstaendige Module festhalten, ohne jetzt eine konkrete Extension-Mechanik (Hooks/Lifecycle/Loader) zu standardisieren. + +## Readiness-Checkliste vor neuem Modul + +1. **Modulgrenzen klarziehen** + - Betroffene Schichten benoennen (`pages -> Service -> Repository`). + - Keine SQL-/Business-Logik in Templates oder `pages/*.phtml`. +2. **Contracts definieren** + - Oeffentliche API-/UI-Contracts dokumentieren (Inputs, Outputs, Fehlerfaelle). + - Bei API-Aenderungen `docs/openapi.yaml` im selben Merge pflegen. +3. **Security + Scope absichern** + - AuthZ/RBAC serverseitig pruefen. + - Tenant-Scope serverseitig pruefen. + - POST-Mutationen mit CSRF absichern. +4. **Testbarkeit und Gates** + - Architektur- und Domain-Tests fuer neue Logik ergaenzen. + - Relevante Quality Gates (`QG-*`) im Merge reporten. +5. **Daten- und Betriebsfaehigkeit** + - Schema-/Datenaenderungen fuer Bestandsinstallationen idempotent in `db/updates/*.sql`. + - Logs/Audit ohne unredacted PII/Secrets. + +## Bewusst Out of Scope in diesem Stand + +- Kein standardisierter Extension-Loader. +- Kein Hook-/Plugin-Lifecycle. +- Keine verbindlichen Modul-Ablageorte ausserhalb bestehender Schichten. + +## Entscheidungslog fuer spaetere Standardisierung + +Wenn die Extension-Mechanik spaeter konkretisiert wird, muss die Entscheidung mindestens diese Punkte mitliefern: + +1. Aktivierung/Deaktivierung und Reihenfolge von Modulen. +2. Versionierung und Migrationsstrategie pro Modul. +3. Sicherheits- und Tenant-Isolation pro Erweiterung. +4. Test- und Rollback-Strategie fuer Modul-Deployments. diff --git a/docs/reference-konventionen.md b/docs/reference-konventionen.md index 0b09b3c..1426271 100644 --- a/docs/reference-konventionen.md +++ b/docs/reference-konventionen.md @@ -1,6 +1,6 @@ # Konventionen (kurz und verbindlich) -Letzte Aktualisierung: 2026-03-06 +Letzte Aktualisierung: 2026-03-09 ## 1) Code @@ -44,7 +44,7 @@ Letzte Aktualisierung: 2026-03-06 - Templates nur für Rendering. - UI-Texte über `t('...')`. -- Strukturregeln in `docs/frontend-css.md` und `docs/frontend-javascript.md`. +- Strukturregeln in `/docs/reference-frontend-css.md` und `/docs/reference-frontend-javascript.md`. ## 6) Mindestchecks vor Merge diff --git a/docs/reference-lib-standards.md b/docs/reference-lib-standards.md index 87704ac..4929296 100644 --- a/docs/reference-lib-standards.md +++ b/docs/reference-lib-standards.md @@ -1,8 +1,8 @@ # lib-Standards -Letzte Aktualisierung: 2026-03-06 +Letzte Aktualisierung: 2026-03-09 -Praktische Regeln nur für `lib/**`. Ergänzt `docs/architektur.md`. +Praktische Regeln nur für `lib/**`. Ergänzt `/docs/explanation-architektur.md`. ## 1) Repository-Regeln diff --git a/tests/Architecture/CodexSkillsContractTest.php b/tests/Architecture/CodexSkillsContractTest.php index 42ea06c..49426f4 100644 --- a/tests/Architecture/CodexSkillsContractTest.php +++ b/tests/Architecture/CodexSkillsContractTest.php @@ -63,5 +63,41 @@ class CodexSkillsContractTest extends TestCase $this->assertStringContainsString('--check', $script); $this->assertStringContainsString('--apply', $script); $this->assertStringContainsString('mode="check"', $script); + $this->assertStringContainsString('"core-guardrails"', $script); + $this->assertStringContainsString('"starterkit-planner"', $script); + $this->assertStringContainsString('"starterkit-grid-standards"', $script); + $this->assertStringContainsString('"starterkit-php-style-ci"', $script); + } + + public function testDocumentationLinksResolveInReadmeDocsAndSourceMap(): void + { + $files = [ + 'README.md', + 'tools/codex-skills/core-guardrails/references/source-map.md', + ]; + + $docFiles = glob($this->projectRootPath() . '/docs/*.md'); + $this->assertNotFalse($docFiles, 'Failed to enumerate docs/*.md files.'); + foreach ($docFiles as $fullPath) { + $files[] = 'docs/' . basename($fullPath); + } + + foreach ($files as $file) { + $content = $this->readProjectFile($file); + preg_match_all('/(?projectRootPath() . '/' . $normalized; + $this->assertFileExists($absolute, sprintf('Broken docs link "%s" in %s', $link, $file)); + } + } + } + + public function testDocsSkillsAuditPolicyExists(): void + { + $policy = $this->readProjectFile('agent-system/checks/docs-skills-audit-policy.md'); + $this->assertStringContainsString('P0', $policy); + $this->assertStringContainsString('P1', $policy); + $this->assertStringContainsString('DOCS-SKILLS-AUDIT-00x', $policy); } } diff --git a/tools/codex-skills/core-guardrails/references/source-map.md b/tools/codex-skills/core-guardrails/references/source-map.md index 70feb01..fc529f8 100644 --- a/tools/codex-skills/core-guardrails/references/source-map.md +++ b/tools/codex-skills/core-guardrails/references/source-map.md @@ -2,24 +2,24 @@ ## Kernregeln -- Architektur- und Schichtgrenzen: `/docs/architektur.md` -- `lib/**`-Regeln und Instanziierung: `/docs/lib-standards.md` -- Kurzkonventionen: `/docs/konventionen.md` -- Request/Input/Validation: `/docs/request-input-validation.md` +- Architektur- und Schichtgrenzen: `/docs/explanation-architektur.md` +- `lib/**`-Regeln und Instanziierung: `/docs/reference-lib-standards.md` +- Kurzkonventionen: `/docs/reference-konventionen.md` +- Request/Input/Validation: `/docs/howto-request-input-validation.md` ## UI-/Frontend-Contracts -- JavaScript-Standards und Wrapper: `/docs/frontend-javascript.md` -- CSS-Standards und Scope-Regeln: `/docs/frontend-css.md` -- DoD-Checks: `/docs/entwickler-checkliste.md` -- Rollen-Workflow (Planner/Executor/Reviewer/Finalizer): `/docs/agents/overview.md` +- JavaScript-Standards und Wrapper: `/docs/reference-frontend-javascript.md` +- CSS-Standards und Scope-Regeln: `/docs/reference-frontend-css.md` +- DoD-Checks: `/docs/reference-entwickler-checkliste.md` +- Rollen-Workflow (Planner/Executor/Reviewer/Finalizer): `/docs/reference-agents-overview.md` ## Security / RBAC -- RBAC-Erweiterungen: `/docs/rbac-permissions-playbook.md` -- Sicherheitsmodell: `/docs/sicherheitsmodell.md` +- RBAC-Erweiterungen: `/docs/howto-rbac-permissions-playbook.md` +- Sicherheitsmodell: `/docs/explanation-sicherheitsmodell.md` ## Betrieb und Qualitaetschecks -- Entwickler-Checkliste: `/docs/entwickler-checkliste.md` -- Architektur-Request-Flow: `/docs/03-architektur-request-flow.md` +- Entwickler-Checkliste: `/docs/reference-entwickler-checkliste.md` +- Architektur-Request-Flow: `/docs/tutorial-04-architektur-request-flow.md`