From 432a3e5ec3dc3e91fc22109e81998e2fd6f9ea04 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Sat, 16 May 2026 19:26:05 +0200 Subject: [PATCH] refactor(contracts): compact Architecture Documentation and Crosscutting Concepts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A contract composes anchors; it should not re-explain the methodology the anchor already triggers. The previous templates spelled out what C4 is (Person/System/Container/Component stereotypes), what each arc42 chapter contains, and the Pugh 3-point scale — all knowledge the arc42, c4-diagrams and pugh-matrix anchors already carry. That bloat works against the anchor approach. Both templates are trimmed to name the anchor plus the project-specific decision only: - C4 detail dropped; kept the actual choice — C4-PlantUML library, not generic boxes; PlantUML, not Mermaid. - Per-chapter diagram enumeration dropped; kept the rule that context, building-block and runtime chapters carry a diagram. - arc42 chapter content (what Chapter 8.x concepts mean) dropped; kept the project's five-concept baseline and the T-ID traceability rule. - The `§` notation note is gone — chapters are now referenced as "Chapter 3" / "Kapitel 3", so there is nothing to disambiguate. Co-Authored-By: Claude Opus 4.7 (1M context) --- website/public/data/contracts.json | 12 +++++----- website/public/llms.txt | 36 ++++++++++-------------------- 2 files changed, 18 insertions(+), 30 deletions(-) diff --git a/website/public/data/contracts.json b/website/public/data/contracts.json index 78f7e5d..091033d 100644 --- a/website/public/data/contracts.json +++ b/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" }, { diff --git a/website/public/llms.txt b/website/public/llms.txt index 5377743..074327e 100644 --- a/website/public/llms.txt +++ b/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*