feat(contracts): split Architecture Documentation, add Crosscutting Concepts

[raifdmueller]

Summary

• Architecture Documentation contract now requires diagrams per arc42 section (§3.1 business context, §3.2 technical context, §5 C4 building blocks, §6 runtime view) and introduces an "Accepted (inferred)" ADR status with ?-marked Pugh cells for brownfield work where stakeholder rationale cannot be confirmed.
• Crosscutting Concepts is now its own contract — five baseline §8 concepts (Threat Model with T-IDs, Security with T-ID traceability, Test, Observability, Error Handling). Domain-specific §8.x sections are added only when the system actually has those concerns.
• render-contracts.js is now part of prebuild so the static contracts.html fragment stays in sync with contracts.json on every build (was previously regenerated manually).

Test plan

• npm run build succeeds and dist/contracts/index.html contains both contracts (verified locally: Crosscutting appears twice in the pre-rendered HTML)
• llms.txt lists all 14 contracts (was 13)
• On the live /contracts page, both contracts are selectable and downloadable

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• Documentation

  • Erweiterte Richtlinien für Architektur-Dokumentation mit spezifischen Diagramm-Anforderungen pro Abschnitt
  • Neue Standards für ADR-Dokumentation einschließlich Pugh-Matrix-Erstellung
  • Hinzugefügte Baseline-Crosscutting-Concepts: Threat Model, Security, Test, Observability und Error Handling Konzepte

• Chores

  • Build-Prozess optimiert mit zusätzlichem Verarbeitungsschritt für Vertragsdaten

[coderabbitai]

Walkthrough

Der PR aktualisiert die Build-Pipeline, um Verträge zu rendern, und erweitert die Contract-Definitionen mit präzisierten arc42- und ADR-Anforderungen. Die entsprechende LLM-Kontext-Dokumentation wird mit detaillierten Crosscutting-Concepts-Standards ergänzt.

Changes

Architektur-Dokumentations-Standards

Layer / File(s)	Zusammenfassung
Build-Pipeline-Integration website/package.json	Die prebuild-Scriptkette wird um node ../scripts/render-contracts.js erweitert, um Contract-Daten vor dem Build zu verarbeiten.
Contract-Definitionen und Formatierung website/public/data/contracts.json	Der architecture-documentation-Vertrag wird mit detaillierten arc42-Diagramm-Anforderungen pro Abschnitt und präzisierten ADR-Regeln (einschließlich Pugh-Matrix und Notation für inferred Entscheidungen) aktualisiert. Die anchors-Arrays in layer-boundaries, implement-next und socratic-code-theory-recovery werden auf mehrzeilige Darstellung formatiert.
LLM-Kontext-Dokumentation website/public/llms.txt	Der Architecture-Documentation-Abschnitt wird mit spezifischen Diagramm-Lieferungen und ADR-Pugh-Matrix-Anforderungen erweitert. Ein neuer Crosscutting-Concepts-Abschnitt führt fünf baseline Konzepte in arc42-Reihenfolge ein: Threat Model (mit T-ID-Traceability), Security Concept (Migrationszuordnung), Test Concept (Pyramid/Traceability), Observability Concept (Logs, Metrics, Traces, Audit Trails) und Error Handling Concept (Failure-Propagation, Retry, Circuit Breaker, Fallback).

Geschätzter Code-Review-Aufwand

🎯 2 (Simple) | ⏱️ ~12 Minuten

Möglicherweise verwandte PRs

• LLM-Coding/Semantic-Anchors#369: Beide PRs modifizieren Vertragsinhalte in website/public/data/contracts.json, insbesondere architektur- und dokumentationsbezogene Anker und Templates.
• LLM-Coding/Semantic-Anchors#454: Beide PRs ändern website/public/data/contracts.json direkt; der verwandte PR führt den socratic-code-theory-recovery-Vertrag ein, während dieser PR seine Anker erweitert und die Build-Pipeline mit render-contracts aktualisiert.
• LLM-Coding/Semantic-Anchors#366: Der aktuelle PR erweitert die prebuild-Pipeline mit render-contracts und aktualisiert website/public/data/contracts.json, die direkt die Semantic-Contracts-Seite versorgt, auf der Benutzer diese Verträge laden und auswählen können.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	Der Titel beschreibt präzise die zwei Hauptveränderungen: Aufteilung der Architecture Documentation und Hinzufügung von Crosscutting Concepts, was den wesentlichen Änderungen in der Changeset entspricht.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

website/package.json (1)

8-10: ⚡ Quick win

Build- und Dev-Vorbereitung sollten konsistent sein.

prebuild rendert jetzt Docs + Contracts, predev aber nicht. Das kann lokal zu veraltetem /contracts-Inhalt führen. Bitte die Render-Schritte auch im Dev-Flow bündeln (z. B. gemeinsames Script).

🔧 Vorschlag

   "scripts": {
     "sync-anchors": "node ../scripts/sync-anchors.js",
-    "predev": "node ../scripts/sync-anchors.js",
+    "predev": "node ../scripts/sync-anchors.js && node ../scripts/render-docs.js && node ../scripts/render-contracts.js",
     "dev": "vite",
     "prebuild": "node ../scripts/sync-anchors.js && node ../scripts/render-docs.js && node ../scripts/render-contracts.js",

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@website/package.json` around lines 8 - 10, predev only runs sync-anchors.js
while prebuild runs sync-anchors.js plus render-docs.js and render-contracts.js,
causing dev to serve stale /contracts; create a single preparatory script (e.g.,
"prepare-docs-contracts") that runs node ../scripts/sync-anchors.js && node
../scripts/render-docs.js && node ../scripts/render-contracts.js (or add the two
render calls directly) and update package.json so "predev" invokes that same
script (same entry point names: predev, prebuild and the scripts
sync-anchors.js, render-docs.js, render-contracts.js) to ensure dev and build
flows are consistent.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@website/package.json`:
- Around line 8-10: predev only runs sync-anchors.js while prebuild runs
sync-anchors.js plus render-docs.js and render-contracts.js, causing dev to
serve stale /contracts; create a single preparatory script (e.g.,
"prepare-docs-contracts") that runs node ../scripts/sync-anchors.js && node
../scripts/render-docs.js && node ../scripts/render-contracts.js (or add the two
render calls directly) and update package.json so "predev" invokes that same
script (same entry point names: predev, prebuild and the scripts
sync-anchors.js, render-docs.js, render-contracts.js) to ensure dev and build
flows are consistent.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 5b0d8589-efeb-4a7a-aa75-d1867ee3a78a

📥 Commits

Reviewing files that changed from the base of the PR and between 2b2c2bc and 5b3d932.

📒 Files selected for processing (3)

• website/package.json
• website/public/data/contracts.json
• website/public/llms.txt