From a6eb238ef504b614808460ad7f6d9673febd59af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Sun, 17 May 2026 09:26:09 +0200 Subject: [PATCH] refactor(contracts): tighten Architecture Documentation, stop bolding template body MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Architecture Documentation contract: - Drop "all 12 chapters, numbered as in arc42" — the arc42 anchor already carries the chapter structure and numbering. - Drop the AsciiDoc/format line — the Docs-as-Code contract sets the format; restating it here is redundant when that contract is selected and inconsistent when it is not. - Drop the Chapter 8 cross-reference — redundant when the Crosscutting Concepts contract is selected, a dangling pointer when it is not. - Name the C4-PlantUML standard library explicitly with a local include (not the remote URL, which Kroki cannot fetch). - State the Pugh scale as 3-point (-1/0/+1) — a genuine project choice, since Pugh matrices also come in -2..+2 and weighted variants. contracts-page.js: plain template lines were rendered with font-medium, making every non-bullet line look semi-bold. Render them at normal weight. Co-Authored-By: Claude Opus 4.7 (1M context) --- website/public/data/contracts.json | 4 ++-- website/public/llms.txt | 10 +++------- website/src/components/contracts-page.js | 2 +- 3 files changed, 6 insertions(+), 10 deletions(-) diff --git a/website/public/data/contracts.json b/website/public/data/contracts.json index 091033d..942825f 100644 --- a/website/public/data/contracts.json +++ b/website/public/data/contracts.json @@ -28,8 +28,8 @@ "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 — 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\".", + "template": "Architecture documentation follows arc42.\n\nEvery context, building-block and runtime chapter carries at least one diagram. Diagrams are PlantUML, not Mermaid; building blocks use C4 with the C4-PlantUML standard library (local include, not the remote URL — Kroki cannot fetch it), not generic boxes.\n\nDecisions are ADRs (Nygard) with a 3-point Pugh Matrix (-1/0/+1). When the rationale is unconfirmed, ADR Status is \"Accepted (inferred)\" and Pugh cells needing team judgment are marked `?` rather than guessed.", + "templateDe": "Architekturdokumentation folgt arc42.\n\nJedes Kontext-, Baustein- und Laufzeit-Kapitel enthält mindestens ein Diagramm. Diagramme sind PlantUML, nicht Mermaid; Bausteine als C4 mit der C4-PlantUML Standard Library (lokales Include, nicht die Remote-URL — Kroki kann sie nicht laden), nicht als generische Kästen.\n\nEntscheidungen sind ADRs (Nygard) mit einer 3-Punkt-Pugh-Matrix (-1/0/+1). 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.", "category": "architecture" }, { diff --git a/website/public/llms.txt b/website/public/llms.txt index 074327e..cef18c7 100644 --- a/website/public/llms.txt +++ b/website/public/llms.txt @@ -5657,15 +5657,11 @@ Clarify requirements using the Socratic Method: ## Architecture Documentation -Architecture documentation follows arc42 — all 12 chapters, numbered as in arc42 (Chapter 3, Chapter 5.1). +Architecture documentation follows arc42. -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. +Every context, building-block and runtime chapter carries at least one diagram. Diagrams are PlantUML, not Mermaid; building blocks use C4 with the C4-PlantUML standard library (local include, not the remote URL — Kroki cannot fetch it), not generic boxes. -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. - -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. - -Crosscutting concepts (Chapter 8): see the "Crosscutting Concepts" contract. +Decisions are ADRs (Nygard) with a 3-point Pugh Matrix (-1/0/+1). When the rationale is unconfirmed, ADR Status is "Accepted (inferred)" and Pugh cells needing team judgment are marked `?` rather than guessed. *Referenced anchors: arc42, c4-diagrams, adr-according-to-nygard, pugh-matrix* diff --git a/website/src/components/contracts-page.js b/website/src/components/contracts-page.js index 8681596..a265c13 100644 --- a/website/src/components/contracts-page.js +++ b/website/src/components/contracts-page.js @@ -109,7 +109,7 @@ function renderContractCard(contract, isSelected) { if (line.startsWith('- ')) { return `• ${esc(line.slice(2))}` } - return `${esc(line)}` + return `${esc(line)}` }) .join('
')