From 5b3d9320e3f892c6cab4468d0d9d98aa95898166 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Fri, 15 May 2026 17:28:23 +0200 Subject: [PATCH] feat(contracts): split Architecture Documentation, add Crosscutting Concepts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Expands the Architecture Documentation contract with per-section diagram requirements (§3.1 business context, §3.2 technical context, §5 C4 building blocks, §6 runtime view) and an "Accepted (inferred)" ADR status with `?`-marked Pugh cells for brownfield work where stakeholder rationale cannot be confirmed. Splits §8 crosscutting concepts into its own contract — five baseline concepts (Threat Model with T-IDs, Security with T-ID traceability, Test, Observability, Error Handling). Domain-specific §8.x sections (persistence, i18n, accessibility, configuration, performance) are added only when the system actually has those concerns. Adds render-contracts.js to the prebuild chain so that the static contracts.html fragment stays in sync with contracts.json on every build (was previously only regenerated manually). Co-Authored-By: Claude Opus 4.7 (1M context) --- website/package.json | 2 +- website/public/data/contracts.json | 42 +++++++++++++++++++++++++----- website/public/llms.txt | 30 ++++++++++++++++++--- 3 files changed, 63 insertions(+), 11 deletions(-) diff --git a/website/package.json b/website/package.json index c2a5b16..eec5830 100644 --- a/website/package.json +++ b/website/package.json @@ -7,7 +7,7 @@ "sync-anchors": "node ../scripts/sync-anchors.js", "predev": "node ../scripts/sync-anchors.js", "dev": "vite", - "prebuild": "node ../scripts/sync-anchors.js && node ../scripts/render-docs.js", + "prebuild": "node ../scripts/sync-anchors.js && node ../scripts/render-docs.js && node ../scripts/render-contracts.js", "build": "vite build && node ../scripts/prerender-routes.js", "preview": "vite preview", "test": "vitest run", diff --git a/website/public/data/contracts.json b/website/public/data/contracts.json index 623cdad..fef40cf 100644 --- a/website/public/data/contracts.json +++ b/website/public/data/contracts.json @@ -25,11 +25,22 @@ "id": "architecture-documentation", "title": "Architecture Documentation", "titleDe": "Architekturdokumentation", - "description": "How we document architecture with ADRs and decision evaluation", - "descriptionDe": "Wie wir Architektur mit ADRs und Entscheidungsbewertung dokumentieren", + "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- C4 diagrams (PlantUML) for visualization at four abstraction levels\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", - "templateDe": "Architekturdokumentation folgt arc42 mit allen 12 Abschnitten.\n- C4-Diagramme (PlantUML) zur Visualisierung auf vier Abstraktionsebenen\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", + "template": "Architecture documentation follows arc42 with all 12 sections.\n\nDiagrams are required per section:\n- §3.1 Business context: business-process / value-flow diagram\n- §3.2 Technical context: classical context diagram (PlantUML/Mermaid)\n- §5 Building blocks: C4 Level 1 (System Context), Level 2 (Container), and Level 3 (Component) where decomposition adds clarity\n- §6 Runtime view: sequence or activity 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\nDiagramme sind pro Abschnitt verpflichtend:\n- §3.1 Fachlicher Kontext: Geschäftsprozess- / Wertfluss-Diagramm\n- §3.2 Technischer Kontext: klassisches Kontextdiagramm (PlantUML/Mermaid)\n- §5 Bausteinsicht: C4 Level 1 (System Context), Level 2 (Container) und Level 3 (Component), wo Zerlegung Klarheit bringt\n- §6 Laufzeitsicht: Sequenz- oder Aktivitätsdiagramm 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.", + "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", + "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.", "category": "architecture" }, { @@ -38,7 +49,13 @@ "titleDe": "Schichtgrenzen", "description": "How we handle boundaries between layers", "descriptionDe": "Wie wir Grenzen zwischen Schichten handhaben", - "anchors": ["clean-architecture", "hexagonal-architecture", "domain-driven-design", "solid-dip", "solid-isp"], + "anchors": [ + "clean-architecture", + "hexagonal-architecture", + "domain-driven-design", + "solid-dip", + "solid-isp" + ], "template": "At every layer boundary:\n- Expose only well-defined DTOs and contracts — never domain entities\n- Use explicit mapping at every seam\n- Apply Anti-Corruption Layers when integrating external systems\n- Dependency direction points inward (DIP)", "templateDe": "An jeder Schichtgrenze:\n- Nur definierte DTOs und Contracts exponieren — niemals Domain-Entitäten\n- Explizites Mapping an jeder Nahtstelle\n- Anti-Corruption-Layer bei Integration externer Systeme\n- Abhängigkeitsrichtung zeigt nach innen (DIP)", "category": "architecture" @@ -60,7 +77,12 @@ "titleDe": "Nächstes Feature", "description": "The implementation loop for each issue", "descriptionDe": "Der Implementierungs-Loop für jedes Issue", - "anchors": ["tdd-london-school", "tdd-chicago-school", "definition-of-done", "conventional-commits"], + "anchors": [ + "tdd-london-school", + "tdd-chicago-school", + "definition-of-done", + "conventional-commits" + ], "template": "For each issue:\n- Create a feature branch for the EPIC\n- Select next issue from backlog (respect dependencies)\n- Analyze and document analysis as a comment on the issue\n- Implement using TDD (London or Chicago School as appropriate)\n- Each test references its Use Case ID for traceability\n- Commit with Conventional Commits, reference issue number\n- Check if spec or architecture docs need updating\n- When EPIC is complete, create a Pull Request", "templateDe": "Für jedes Issue:\n- Feature-Branch für das EPIC erstellen\n- Nächstes Issue aus dem Backlog wählen (Abhängigkeiten beachten)\n- Analysieren und Analyse als Kommentar am Issue dokumentieren\n- Mit TDD implementieren (London oder Chicago School je nach Kontext)\n- Jeder Test referenziert seine Use-Case-ID für Rückverfolgbarkeit\n- Mit Conventional Commits committen, Issue-Nummer referenzieren\n- Prüfen ob Spec oder Architektur-Docs aktualisiert werden müssen\n- Wenn EPIC fertig, Pull Request erstellen", "category": "development" @@ -104,7 +126,13 @@ "titleDe": "Sokratische Code-Theorie-Rekonstruktion", "description": "Recover a program's 'theory' from source code through recursive question refinement", "descriptionDe": "Die 'Theorie' eines Programms aus dem Quellcode durch rekursive Fragenverfeinerung rekonstruieren", - "anchors": ["socratic-method", "arc42", "iso-25010", "adr-according-to-nygard", "mental-model-according-to-naur"], + "anchors": [ + "socratic-method", + "arc42", + "iso-25010", + "adr-according-to-nygard", + "mental-model-according-to-naur" + ], "template": "Recover a program's \"theory\" (Naur 1985) from source code through recursive question refinement.\n- Start with 5 high-level questions: Problem/Users, Specification, Architecture, Quality Goals, Risks\n- Decompose each question using Semantic Anchors as guides: arc42 (12 sub-questions), Cockburn Use Cases, ISO 25010, Nygard ADRs\n- Each leaf is either `[ANSWERED]` (with code evidence) or `[OPEN]` (with Category, Ask role, and why unanswerable)\n- The Question Tree is the primary artifact; documentation is synthesized from answered leaves\n- Open Questions are the handoff document: routed by role (Product Owner, Architect, Developer, Domain Expert, Operations)\n- Two-phase workflow: Phase 1 builds the tree, team answers Open Questions, Phase 2 produces documentation with Q-ID traceability", "templateDe": "Die \"Theorie\" eines Programms (Naur 1985) aus dem Quellcode durch rekursive Fragenverfeinerung rekonstruieren.\n- Start mit 5 High-Level-Fragen: Problem/Nutzer, Spezifikation, Architektur, Qualitätsziele, Risiken\n- Jede Frage mit Semantic Anchors als Leitfaden zerlegen: arc42 (12 Unterfragen), Cockburn Use Cases, ISO 25010, Nygard ADRs\n- Jedes Blatt ist entweder `[BEANTWORTET]` (mit Code-Evidenz) oder `[OFFEN]` (mit Kategorie, zuständiger Rolle und Begründung warum nicht beantwortbar)\n- Der Fragenbaum ist das primäre Artefakt; Dokumentation wird aus beantworteten Blättern synthetisiert\n- Offene Fragen sind das Übergabedokument: nach Rolle geroutet (Product Owner, Architekt, Entwickler, Domänenexperte, Operations)\n- Zwei-Phasen-Workflow: Phase 1 baut den Baum, Team beantwortet offene Fragen, Phase 2 erzeugt Dokumentation mit Q-ID-Rückverfolgbarkeit", "category": "documentation" diff --git a/website/public/llms.txt b/website/public/llms.txt index 78aaacc..9748ae1 100644 --- a/website/public/llms.txt +++ b/website/public/llms.txt @@ -5658,12 +5658,36 @@ Clarify requirements using the Socratic Method: ## Architecture Documentation Architecture documentation follows arc42 with all 12 sections. -- C4 diagrams (PlantUML) for visualization at four abstraction levels -- 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 + +Diagrams are required per section: +- §3.1 Business context: business-process / value-flow diagram +- §3.2 Technical context: classical context diagram (PlantUML/Mermaid) +- §5 Building blocks: C4 Level 1 (System Context), Level 2 (Container), and Level 3 (Component) where decomposition adds clarity +- §6 Runtime view: sequence or activity diagram per named scenario + +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. *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: + +- §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. + +Domain-specific concepts (persistence, i18n, accessibility, configuration, performance) are added as additional §8.x sections only when the system actually has those concerns. + +*Referenced anchors: arc42, stride, testing-pyramid* + ## Layer Boundaries At every layer boundary: