refactor(contracts): compact Architecture Documentation and Crosscutting Concepts

website/public/data/contracts.json

@@ -28,19 +28,19 @@
     "description": "How we document architecture with diagrams, ADRs, and decision evaluation",
     "descriptionDe": "Wie wir Architektur mit Diagrammen, ADRs und Entscheidungsbewertung dokumentieren",
     "anchors": ["arc42", "c4-diagrams", "adr-according-to-nygard", "pugh-matrix"],
-    "template": "Architecture documentation follows arc42 with all 12 sections.\n\nSections are numbered as in arc42 itself: `1.`, `1.1`, `2.`, … No `§` prefix in the output (the `§` symbol is used in this contract only to reference arc42 sections, not as the prescribed notation).\n\nFile formats:\n- arc42, ADRs, PRD, specification documents: AsciiDoc (.adoc), per the Docs-as-Code contract.\n- Use-case files and entity model retain whatever format the AIUP-reverse-engineer skill produces (Markdown today).\n- Question Tree and Open Questions: AsciiDoc (.adoc).\n\nDiagrams are required per section, all as PlantUML:\n- 3.1 Business context: business-process / value-flow diagram (BPMN or annotated sequence).\n- 3.2 Technical context: classical context diagram showing the system as a black box with all external systems and protocols labelled.\n- 5.1 / 5.2 / 5.3 Building blocks: C4 model using the C4-PlantUML standard library (`!include` C4_Context / C4_Container / C4_Component) with the proper stereotypes (`Person`, `System`, `Container`, `Component`, `Rel`). Generic `box`/`rectangle` shapes do not satisfy this requirement.\n- 6 Runtime view: PlantUML sequence diagram per named scenario.\n\nDecisions:\n- Every architecture decision documented as an ADR according to Nygard (Context, Decision, Status, Consequences).\n- Each ADR includes a Pugh Matrix with 3-point scale (-1, 0, +1) evaluating alternatives against quality goals.\n- When the rationale cannot be confirmed by a stakeholder, ADR Status is \"Accepted (inferred)\" and Pugh cells requiring team judgment are marked `?` rather than filled with assumptions.\n\nCrosscutting concepts (§8) are listed in the separate \"Crosscutting Concepts\" contract.",
-    "templateDe": "Architekturdokumentation folgt arc42 mit allen 12 Abschnitten.\n\nAbschnitte werden wie in arc42 selbst nummeriert: `1.`, `1.1`, `2.`, … Kein `§`-Präfix in der Ausgabe (das `§`-Zeichen wird in diesem Contract nur zur Referenzierung von arc42-Abschnitten verwendet, nicht als vorgeschriebene Notation).\n\nDateiformate:\n- arc42, ADRs, PRD, Spezifikationsdokumente: AsciiDoc (.adoc), gemäß Docs-as-Code-Contract.\n- Use-Case-Dateien und Entity Model behalten das Format, das die AIUP-reverse-engineer-Skill erzeugt (heute Markdown).\n- Question Tree und Open Questions: AsciiDoc (.adoc).\n\nDiagramme sind pro Abschnitt verpflichtend, alle als PlantUML:\n- 3.1 Fachlicher Kontext: Geschäftsprozess- / Wertfluss-Diagramm (BPMN oder annotierte Sequenz).\n- 3.2 Technischer Kontext: klassisches Kontextdiagramm, das das System als Black Box zeigt, mit allen externen Systemen und beschrifteten Protokollen.\n- 5.1 / 5.2 / 5.3 Bausteinsicht: C4-Modell mit der C4-PlantUML-Standardbibliothek (`!include` C4_Context / C4_Container / C4_Component) und den korrekten Stereotypen (`Person`, `System`, `Container`, `Component`, `Rel`). Generische `box`/`rectangle`-Formen erfüllen diese Anforderung nicht.\n- 6 Laufzeitsicht: PlantUML-Sequenzdiagramm pro benanntem Szenario.\n\nEntscheidungen:\n- Jede Architekturentscheidung als ADR nach Nygard dokumentiert (Kontext, Entscheidung, Status, Konsequenzen).\n- Jedes ADR enthält eine Pugh-Matrix mit 3-Punkt-Skala (-1, 0, +1) zur Bewertung von Alternativen gegen Qualitätsziele.\n- Wenn die Begründung nicht von einem Stakeholder bestätigt werden kann, lautet der ADR-Status \"Accepted (inferred)\", und Pugh-Zellen, die Team-Urteil erfordern, werden mit `?` markiert statt mit Annahmen gefüllt.\n\nQuerschnittliche Konzepte (§8) sind im separaten Contract \"Crosscutting Concepts\" beschrieben.",
+    "template": "Architecture documentation follows arc42 — all 12 chapters, numbered as in arc42 (Chapter 3, Chapter 5.1).\n\nFormat is AsciiDoc, per the Docs-as-Code contract. Reverse-engineered use-case files and the entity model keep whatever format their source skill emits.\n\nEvery context, building-block and runtime chapter carries at least one diagram. Diagrams are PlantUML, not Mermaid; building blocks use C4 drawn with the C4-PlantUML library, not generic boxes.\n\nDecisions are ADRs (Nygard) with a Pugh Matrix. When the rationale is unconfirmed, ADR Status is \"Accepted (inferred)\" and Pugh cells needing team judgment are marked `?` rather than guessed.\n\nCrosscutting concepts (Chapter 8): see the \"Crosscutting Concepts\" contract.",
+    "templateDe": "Architekturdokumentation folgt arc42 — alle 12 Kapitel, nummeriert wie in arc42 (Kapitel 3, Kapitel 5.1).\n\nFormat ist AsciiDoc, gemäß Docs-as-Code-Contract. Reverse-engineerte Use-Case-Dateien und das Entity Model behalten das Format, das ihre Quell-Skill erzeugt.\n\nJedes Kontext-, Baustein- und Laufzeit-Kapitel enthält mindestens ein Diagramm. Diagramme sind PlantUML, nicht Mermaid; Bausteine als C4, gezeichnet mit der C4-PlantUML-Bibliothek, nicht als generische Kästen.\n\nEntscheidungen sind ADRs (Nygard) mit Pugh-Matrix. Wenn die Begründung unbestätigt ist, lautet der ADR-Status \"Accepted (inferred)\", und Pugh-Zellen, die Team-Urteil erfordern, werden mit `?` markiert statt geraten.\n\nQuerschnittliche Konzepte (Kapitel 8): siehe Contract \"Crosscutting Concepts\".",
     "category": "architecture"
   },
   {
     "id": "crosscutting-concepts",
     "title": "Crosscutting Concepts",
     "titleDe": "Querschnittliche Konzepte",
-    "description": "Baseline §8 concepts every system documents: threat model, security, test, observability, error handling",
-    "descriptionDe": "Basis-§8-Konzepte, die jedes System dokumentiert: Threat Model, Security, Test, Observability, Error Handling",
+    "description": "Baseline arc42 Chapter 8 concepts every system documents: threat model, security, test, observability, error handling",
+    "descriptionDe": "Basis-Konzepte für arc42 Kapitel 8, die jedes System dokumentiert: Threat Model, Security, Test, Observability, Error Handling",
     "anchors": ["arc42", "stride", "testing-pyramid"],
-    "template": "arc42 leaves §8 open; we require these five baseline crosscutting concepts in this order:\n\n- §8.1 Threat Model: assets, actors, attack surfaces, prioritized threats (STRIDE or equivalent). Threats receive IDs (T-001…) so §8.2 mitigations can trace to them.\n- §8.2 Security Concept: authentication, authorization, secrets, sandbox boundaries, supply chain, crypto. Every mitigation references the T-IDs it addresses.\n- §8.3 Test Concept: test pyramid, layer-to-coverage mapping, traceability from Use Cases / Business Rules to tests.\n- §8.4 Observability Concept: logs, metrics, traces, and audit trails — what is captured, retention, alerting thresholds.\n- §8.5 Error Handling Concept: failure propagation (retry, circuit breaker, fallback), user-facing communication, recovery after partial failure.\n\nDomain-specific concepts (persistence, i18n, accessibility, configuration, performance) are added as additional §8.x sections only when the system actually has those concerns.",
-    "templateDe": "arc42 lässt §8 offen; wir verlangen diese fünf querschnittlichen Basis-Konzepte in dieser Reihenfolge:\n\n- §8.1 Threat Model: Assets, Akteure, Angriffsflächen, priorisierte Bedrohungen (STRIDE oder Äquivalent). Bedrohungen erhalten IDs (T-001…), damit §8.2-Mitigationen darauf verweisen können.\n- §8.2 Security-Konzept: Authentifizierung, Autorisierung, Secrets, Sandbox-Grenzen, Supply Chain, Kryptografie. Jede Mitigation referenziert die T-IDs, die sie adressiert.\n- §8.3 Test-Konzept: Testpyramide, Mapping Schicht → Coverage, Traceability von Use Cases / Business Rules zu Tests.\n- §8.4 Observability-Konzept: Logs, Metriken, Traces und Audit-Trails — was erfasst wird, Aufbewahrung, Alarmschwellen.\n- §8.5 Fehlerbehandlungs-Konzept: Fehlerausbreitung (Retry, Circuit Breaker, Fallback), Kommunikation zum Nutzer, Wiederherstellung nach Teilausfall.\n\nDomänenspezifische Konzepte (Persistenz, i18n, Barrierefreiheit, Konfiguration, Performance) werden nur als zusätzliche §8.x-Abschnitte aufgenommen, wenn das System diese Belange tatsächlich hat.",
+    "template": "arc42 leaves Chapter 8 open. We require five baseline crosscutting concepts, in this order:\n\n- 8.1 Threat Model — STRIDE; threats get IDs (T-001…).\n- 8.2 Security — every mitigation references the T-IDs it closes.\n- 8.3 Test — testing pyramid; tests trace to Use Cases and Business Rules.\n- 8.4 Observability — logs, metrics, traces, audit trails.\n- 8.5 Error Handling — retry, circuit breaker, fallback, recovery.\n\nAdd further Chapter 8.x concepts (persistence, i18n, accessibility, configuration, performance) only when the system actually has that concern.",
+    "templateDe": "arc42 lässt Kapitel 8 offen. Wir verlangen fünf querschnittliche Basis-Konzepte, in dieser Reihenfolge:\n\n- 8.1 Threat Model — STRIDE; Bedrohungen erhalten IDs (T-001…).\n- 8.2 Security — jede Mitigation referenziert die T-IDs, die sie schließt.\n- 8.3 Test — Testpyramide; Tests verweisen auf Use Cases und Business Rules.\n- 8.4 Observability — Logs, Metriken, Traces, Audit-Trails.\n- 8.5 Error Handling — Retry, Circuit Breaker, Fallback, Recovery.\n\nWeitere Kapitel-8.x-Konzepte (Persistenz, i18n, Barrierefreiheit, Konfiguration, Performance) nur aufnehmen, wenn das System diesen Belang tatsächlich hat.",
     "category": "architecture"
   },
   {

website/public/llms.txt

@@ -5657,41 +5657,29 @@ Clarify requirements using the Socratic Method:
 
 ## Architecture Documentation
 
-Architecture documentation follows arc42 with all 12 sections.
+Architecture documentation follows arc42 — all 12 chapters, numbered as in arc42 (Chapter 3, Chapter 5.1).
 
-Sections are numbered as in arc42 itself: `1.`, `1.1`, `2.`, … No `§` prefix in the output (the `§` symbol is used in this contract only to reference arc42 sections, not as the prescribed notation).
+Format is AsciiDoc, per the Docs-as-Code contract. Reverse-engineered use-case files and the entity model keep whatever format their source skill emits.
 
-File formats:
-- arc42, ADRs, PRD, specification documents: AsciiDoc (.adoc), per the Docs-as-Code contract.
-- Use-case files and entity model retain whatever format the AIUP-reverse-engineer skill produces (Markdown today).
-- Question Tree and Open Questions: AsciiDoc (.adoc).
+Every context, building-block and runtime chapter carries at least one diagram. Diagrams are PlantUML, not Mermaid; building blocks use C4 drawn with the C4-PlantUML library, not generic boxes.
 
-Diagrams are required per section, all as PlantUML:
-- 3.1 Business context: business-process / value-flow diagram (BPMN or annotated sequence).
-- 3.2 Technical context: classical context diagram showing the system as a black box with all external systems and protocols labelled.
-- 5.1 / 5.2 / 5.3 Building blocks: C4 model using the C4-PlantUML standard library (`!include` C4_Context / C4_Container / C4_Component) with the proper stereotypes (`Person`, `System`, `Container`, `Component`, `Rel`). Generic `box`/`rectangle` shapes do not satisfy this requirement.
-- 6 Runtime view: PlantUML sequence diagram per named scenario.
+Decisions are ADRs (Nygard) with a Pugh Matrix. When the rationale is unconfirmed, ADR Status is "Accepted (inferred)" and Pugh cells needing team judgment are marked `?` rather than guessed.
 
-Decisions:
-- Every architecture decision documented as an ADR according to Nygard (Context, Decision, Status, Consequences).
-- Each ADR includes a Pugh Matrix with 3-point scale (-1, 0, +1) evaluating alternatives against quality goals.
-- When the rationale cannot be confirmed by a stakeholder, ADR Status is "Accepted (inferred)" and Pugh cells requiring team judgment are marked `?` rather than filled with assumptions.
-
-Crosscutting concepts (§8) are listed in the separate "Crosscutting Concepts" contract.
+Crosscutting concepts (Chapter 8): see the "Crosscutting Concepts" contract.
 
 *Referenced anchors: arc42, c4-diagrams, adr-according-to-nygard, pugh-matrix*
 
 ## Crosscutting Concepts
 
-arc42 leaves §8 open; we require these five baseline crosscutting concepts in this order:
+arc42 leaves Chapter 8 open. We require five baseline crosscutting concepts, in this order:
 
-- §8.1 Threat Model: assets, actors, attack surfaces, prioritized threats (STRIDE or equivalent). Threats receive IDs (T-001…) so §8.2 mitigations can trace to them.
-- §8.2 Security Concept: authentication, authorization, secrets, sandbox boundaries, supply chain, crypto. Every mitigation references the T-IDs it addresses.
-- §8.3 Test Concept: test pyramid, layer-to-coverage mapping, traceability from Use Cases / Business Rules to tests.
-- §8.4 Observability Concept: logs, metrics, traces, and audit trails — what is captured, retention, alerting thresholds.
-- §8.5 Error Handling Concept: failure propagation (retry, circuit breaker, fallback), user-facing communication, recovery after partial failure.
+- 8.1 Threat Model — STRIDE; threats get IDs (T-001…).
+- 8.2 Security — every mitigation references the T-IDs it closes.
+- 8.3 Test — testing pyramid; tests trace to Use Cases and Business Rules.
+- 8.4 Observability — logs, metrics, traces, audit trails.
+- 8.5 Error Handling — retry, circuit breaker, fallback, recovery.
 
-Domain-specific concepts (persistence, i18n, accessibility, configuration, performance) are added as additional §8.x sections only when the system actually has those concerns.
+Add further Chapter 8.x concepts (persistence, i18n, accessibility, configuration, performance) only when the system actually has that concern.
 
 *Referenced anchors: arc42, stride, testing-pyramid*