ahmido
2f45ff5a84
## Summary - add tenant triage review-state persistence, fingerprinting, resolver logic, service layer, and migration for current affected-set tracking - surface review-state and affected-set progress across tenant registry, tenant dashboard arrival continuity, and workspace overview - extend RBAC, audit/badge support, specs, and test coverage for portfolio triage review-state workflows - suppress expected hidden-page background transport failures in the global unhandled rejection logger while keeping visible-page failures logged ## Validation - targeted Pest coverage added for tenant registry, workspace overview, arrival context, RBAC authorization, badges, fingerprinting, resolver behavior, and logger asset behavior - code formatted with `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` ## Notes - full suite was not re-run in this final step - branch includes the spec artifacts under `specs/189-portfolio-triage-review-state/` Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #220
237 lines
8.6 KiB
Markdown
237 lines
8.6 KiB
Markdown
# TenantPilot Spec Approval Rubric (Anti-Overengineering Guardrails)
|
||
|
||
## Leitsatz
|
||
|
||
> Kein neuer Layer ohne klaren Operatorgewinn, und kein neuer Spec nur für interne semantische Schönheit.
|
||
|
||
Ein neuer Spec ist nur dann stark genug, wenn er **sichtbar mehr Produktwahrheit oder Operator-Wirkung** erzeugt als er dauerhafte Systemkomplexität importiert.
|
||
|
||
Jeder Spec muss zwei Dinge gleichzeitig beweisen:
|
||
|
||
1. Welches echte Problem wird gelöst?
|
||
2. Warum ist diese Lösung die kleinste enterprise-taugliche Form?
|
||
|
||
Wenn der Spec nur interne Eleganz, feinere Semantik oder mehr Konsistenz bringt, aber keinen klaren Workflow-, Trust- oder Audit-Gewinn, dann ist er **verdächtig**.
|
||
|
||
---
|
||
|
||
## 5 Pflichtfragen vor jeder Freigabe
|
||
|
||
Ein Spec darf nur weiterverfolgt werden, wenn diese 5 Fragen sauber beantwortet sind.
|
||
|
||
### A. Welcher konkrete Operator-Workflow wird besser?
|
||
|
||
Nicht abstrakt „Konsistenz verbessern", sondern konkret: welcher Nutzer, auf welcher Fläche, in welchem Schritt, mit welchem heutigen Schmerz, und was danach schneller, sicherer oder ehrlicher wird.
|
||
|
||
Wenn kein klarer Vorher/Nachher-Workflow benennbar ist → Spec ist zu abstrakt.
|
||
|
||
### B. Welche falsche oder gefährliche Produktaussage wird verhindert?
|
||
|
||
Legitime Antworten:
|
||
|
||
- Falscher „alles okay"-Eindruck
|
||
- Irreführende Recovery-Claims
|
||
- Unsaubere Ownership
|
||
- Fehlende nächste Aktion
|
||
- Fehlende Audit-Nachvollziehbarkeit
|
||
- Tenant/Workspace Leakage
|
||
- RBAC-Missverständnisse
|
||
|
||
Wenn ein Spec weder Workflow noch Trust verbessert → kaum zu rechtfertigen.
|
||
|
||
### C. Was ist die kleinste brauchbare Version?
|
||
|
||
Explizit benennen:
|
||
|
||
- Was ist die v1-Minimalversion?
|
||
- Welche Teile sind bewusst nicht enthalten?
|
||
- Welche Generalisierung wird absichtlich verschoben?
|
||
|
||
Wenn v1 wie ein Framework, eine Plattform oder eine universelle Taxonomie klingt → zu groß.
|
||
|
||
### D. Welche dauerhafte Komplexität entsteht?
|
||
|
||
Nicht nur Implementierungsaufwand, sondern Dauerfolgen:
|
||
|
||
- Neue Models / Tables?
|
||
- Neue Enums / Statusachsen?
|
||
- Neue UI-Semantik?
|
||
- Neue cross-surface Contracts?
|
||
- Neue Tests, die dauerhaft gepflegt werden müssen?
|
||
- Neue Begriffe, die jeder verstehen muss?
|
||
|
||
Wenn die Liste lang ist → Produktgewinn muss entsprechend hoch sein.
|
||
|
||
### E. Warum jetzt?
|
||
|
||
Legitime Gründe:
|
||
|
||
- Blockiert Kernworkflow
|
||
- Verhindert gefährliche Fehlinterpretation
|
||
- Ist Voraussetzung für unmittelbar folgende Hauptdomäne
|
||
- Beseitigt echten systemischen Widerspruch
|
||
- Wird bereits von mehreren Flächen schmerzhaft benötigt
|
||
|
||
Schwache Gründe:
|
||
|
||
- „wäre sauberer"
|
||
- „brauchen wir später bestimmt"
|
||
- „passt gut zur Architektur"
|
||
- „macht das Modell vollständiger"
|
||
|
||
---
|
||
|
||
## 4 Spec-Klassen
|
||
|
||
Jeden Kandidaten zwingend in genau eine Klasse einordnen.
|
||
|
||
### Klasse 1 — Core Enterprise Spec
|
||
|
||
Mindestens eins muss stimmen:
|
||
|
||
- Schützt echte System-/Tenant-/RBAC-Korrektheit
|
||
- Verhindert falsche Governance-/Recovery-/Audit-Aussagen
|
||
- Schließt klaren Workflow-Gap
|
||
- Beseitigt cross-surface Widerspruch mit realem Operator-Schaden
|
||
- Ist echte Voraussetzung für eine wichtige Produktfunktion
|
||
|
||
Dürfen Komplexität einführen, aber nur gezielt.
|
||
|
||
### Klasse 2 — Workflow Compression Spec
|
||
|
||
Gut, wenn sie:
|
||
|
||
- Klickpfade verkürzen
|
||
- Kontextverlust senken
|
||
- Return-/Drilldown-Kontinuität verbessern
|
||
- Triage-/Review-/Run-Bearbeitung beschleunigen
|
||
|
||
Nützlich, aber klein halten.
|
||
|
||
### Klasse 3 — Cleanup / Consolidation
|
||
|
||
- Vereinfachung, Zusammenführung, Entkopplung
|
||
- Entfernen von Legacy / Duplikaten
|
||
- Reduktion unnötiger Schichten
|
||
|
||
Explizit erwünscht als Gegengewicht zu Wachstum.
|
||
|
||
### Klasse 4 — Premature / Defer
|
||
|
||
Wenn der Kandidat hauptsächlich bringt:
|
||
|
||
- Neue Semantik, Frameworks, Taxonomien
|
||
- Generalisierung für künftige Fälle
|
||
- Infrastruktur ohne breite aktuelle Nutzung
|
||
|
||
→ Nicht freigeben. Verschieben oder brutal einkürzen.
|
||
|
||
---
|
||
|
||
## Rote Flaggen
|
||
|
||
Wenn **zwei oder mehr** zutreffen → Spec muss aktiv verteidigt werden.
|
||
|
||
| # | Rote Flagge | Prüffrage |
|
||
|---|---|---|
|
||
| 1 | **Neue Achsen** — neues Truth-Modell, Statusdimension, Taxonomie, Bewertungsachse | Braucht der Operator das wirklich, oder nur das Modell? |
|
||
| 2 | **Neue Meta-Infrastruktur** — Presenter, Resolver, Catalog, Matrix, Registry, Builder, Policy-Layer | Sehr hoher Beweiswert nötig. |
|
||
| 3 | **Viele Flächen, wenig Nutzerwert** — 6 Flächen „harmonisiert", kein klarer Nutzerflow besser | Architektur um ihrer selbst willen? |
|
||
| 4 | **Klingt nach Foundation** — foundation, framework, generalized, reusable, future-proof, canonical semantics | Fast immer erklärungsbedürftig. |
|
||
| 5 | **Mehr Begriffe als Outcomes** — lange semantische Erklärung, Nutzerverbesserung kaum in einem Satz | Verdächtig. |
|
||
| 6 | **Mehrere Mikrospecs für eine Domäne** — foundation + semantics + presentation + hardening + integration | Zu fein zerlegt. |
|
||
|
||
---
|
||
|
||
## Grüne Flaggen
|
||
|
||
- Löst klar beobachtbaren Operator-Schmerz
|
||
- Verbessert echte Entscheidungssituation
|
||
- Verhindert konkrete Fehlinterpretation
|
||
- Reduziert Navigation oder Denkaufwand
|
||
- Vereinfacht bereits existierende Komplexität
|
||
- Führt wenig neue Begriffe ein
|
||
- Hat klare Nicht-Ziele
|
||
- Ist in einer Sitzung gut erklärbar
|
||
- Braucht keine neue Meta-Schicht
|
||
- Macht mehrere Flächen einfacher statt abstrakter
|
||
|
||
---
|
||
|
||
## Bewertungsraster (0–2 pro Dimension)
|
||
|
||
| Dimension | 0 | 1 | 2 |
|
||
|---|---|---|---|
|
||
| **Nutzen** | unklar | lokal nützlich | klarer Workflow-/Trust-/Audit-Gewinn |
|
||
| **Dringlichkeit** | kann warten | sinnvoll bald | blockiert oder schützt Wichtiges jetzt |
|
||
| **Scope-Disziplin** | wirkt wie Framework/Plattform | etwas breit | klar begrenzte v1 |
|
||
| **Komplexitätslast** | hohe dauerhafte Last | mittel | niedrig / gut beherrschbar |
|
||
| **Produktnähe** | vor allem intern/architektonisch | gemischt | direkt spürbar für Operatoren |
|
||
| **Wiederverwendung belegt** | hypothetisch | wahrscheinlich | bereits an mehreren echten Stellen nötig |
|
||
|
||
### Auswertung
|
||
|
||
| Score | Entscheidung |
|
||
|---|---|
|
||
| **10–12** | Freigabefähig |
|
||
| **7–9** | Nur freigeben wenn Scope enger gezogen wird |
|
||
| **4–6** | Verschieben oder zu Cleanup/Micro-Follow-up downgraden |
|
||
| **0–3** | Nicht freigeben |
|
||
|
||
---
|
||
|
||
## TenantPilot-spezifische Regeln
|
||
|
||
### Regel A — Keine neue semantische Achse ohne UI-Beweis
|
||
|
||
Wo wird sie sichtbar? Warum reichen bestehende Achsen nicht? Welche Fehlentscheidung bleibt ohne sie bestehen?
|
||
|
||
### Regel B — Keine neue Support-/Presentation-Schicht ohne ≥ 3 echte Verbraucher
|
||
|
||
Registry, Resolver, Catalog, Presenter, Matrix, Explanation-Layer → nur mit mindestens drei echten (nicht künstlich erzeugten) Verbrauchern. Sonst lokal lösen.
|
||
|
||
### Regel C — Keine Spec-Aufspaltung unterhalb Operator-Domäne
|
||
|
||
Wenn ein Thema nicht eigenständig als Operator-Problem beschrieben werden kann → kein eigener Spec.
|
||
|
||
### Regel D — Jeder neue Status braucht eine echte Folgehandlung
|
||
|
||
Neue Status/Outcome nur erlaubt wenn sie etwas Konkretes ändern: andere nächste Aktion, anderes Routing, andere Audit-Bedeutung, andere Workflow-Behandlung.
|
||
|
||
### Regel E — Consolidation ist ein legitimer Spec-Typ
|
||
|
||
Zusammenführen von Semantik, Reduktion von Komplexität, Entfernen von Parallelmodellen, Vereinfachung von Navigation/Resolvern, Rückbau unnötiger Zwischenlayer — aktiv Platz geben.
|
||
|
||
---
|
||
|
||
## Freigabe-Template (Pflichtabschnitt in spec.md)
|
||
|
||
```markdown
|
||
## Spec Candidate Check
|
||
|
||
- **Problem**: [Konkreter Operator-Schmerz oder Trust-Gap heute]
|
||
- **Today's failure**: [Welche Fehlentscheidung / Verlangsamung / irreführende Produktaussage passiert aktuell?]
|
||
- **User-visible improvement**: [Was wird konkret schneller, sicherer oder ehrlicher?]
|
||
- **Smallest enterprise-capable version**: [Kleinste Version die das Problem sauber löst]
|
||
- **Explicit non-goals**: [Was wird bewusst nicht modelliert/generalisiert/frameworkisiert?]
|
||
- **Permanent complexity imported**: [Neue Models, Status, Enums, Services, Support-Layer, Tests, UI-Konzepte, Begriffe]
|
||
- **Why now**: [Warum jetzt wichtiger als später?]
|
||
- **Why not local**: [Warum reicht keine lokale, schmale Lösung?]
|
||
- **Approval class**: [Core Enterprise / Workflow Compression / Cleanup / Defer]
|
||
- **Red flags triggered**: [Welche roten Flaggen treffen zu?]
|
||
- **Score**: [Nutzen: _ | Dringlichkeit: _ | Scope: _ | Komplexität: _ | Produktnähe: _ | Wiederverwendung: _ | **Gesamt: _/12**]
|
||
- **Decision**: [approve / shrink / merge / defer / reject]
|
||
```
|
||
|
||
---
|
||
|
||
## Erlaubt vs. Verdächtig (Schnellreferenz)
|
||
|
||
| Erlaubt | Verdächtig |
|
||
|---|---|
|
||
| Echte Workflow-Specs | Neue truth sub-axes |
|
||
| Governance-/Finding-/Review-Bearbeitbarkeit | Neue explanation frameworks |
|
||
| Trust-/Audit-/RBAC-Härtung | Neue presentation taxonomies |
|
||
| Portfolio-Operator-Durchsatzverbesserungen | Neue generalized support layers |
|
||
| Consolidation-Specs | Mikro-Specs für bereits stark zerlegte Domänen |
|