Merge pull request #401 from raifdmueller/feat/business-rules

feat: add Business Rules (BR-IDs) to Use Case structure

Author: rdmueller

docs/brownfield-workflow.adoc

@@ -6,7 +6,7 @@ Ralf D. Müller
 
 == Introduction
 
-You have mastered the link:spec-driven-workflow.adoc[greenfield workflow].
+You have mastered the link:#/workflow[greenfield workflow].
 Now you want to apply it to an existing codebase.
 
 The core principles remain the same: small steps, high autonomy, error correction loops.
@@ -64,7 +64,7 @@ The output is a set of use cases that describe the *existing* behavior -- not wh
 .Prompt
 ----
 Read the code in [bounded context path]. Extract the existing behavior as Use Cases.
-For each Use Case: ID, Trigger, Actors, Preconditions, Main Flow, Alternative Flows, Postconditions.
+For each Use Case: ID, Trigger, Actors, Preconditions, Main Flow, Alternative Flows, Postconditions, Business Rules.
 Save as docs/specs/use-cases-[context-name].adoc.
 ----
 
@@ -152,7 +152,7 @@ Stable code that nobody touches does not need specs.
 |link:#/anchor/tdd-london-school[TDD London] / link:#/anchor/tdd-chicago-school[Chicago]
 
 |Continue
-|Follow link:spec-driven-workflow.adoc[the standard workflow] from Step 3 (PRD) or Step 8 (Implementation), depending on whether you are adding new features or fixing bugs.
+|Follow link:#/workflow[the standard workflow] from Step 3 (PRD) or Step 8 (Implementation), depending on whether you are adding new features or fixing bugs.
 |{empty}--
 |===
 

docs/spec-driven-workflow.adoc

@@ -31,7 +31,7 @@ Click on any anchor to see its full definition on the Semantic Anchors website.
 [IMPORTANT]
 ====
 This workflow is designed for greenfield projects built from scratch with AI assistance.
-For existing codebases, see link:brownfield-workflow.adoc[Adapting the Workflow to Brownfield Projects].
+For existing codebases, see link:#/brownfield[Adapting the Workflow to Brownfield Projects].
 ====
 
 == The Key Principle: Small Steps, High Autonomy
@@ -210,7 +210,7 @@ From the PRD, generate a full specification:
 [source]
 ----
 Create a detailed specification from the PRD. Include:
-- Use Cases (Trigger, Main Flow, Alternative Flows, Postconditions)
+- Use Cases (Trigger, Main Flow, Alternative Flows, Postconditions, Business Rules)
 - Activity Diagrams for all flows (not just the happy path)
 - Acceptance criteria in Gherkin format
 Save as .adoc files in src/docs/specs/.
@@ -224,6 +224,9 @@ Without a trigger, neither the AI nor a tester knows when the use case begins.
 * *Alternative Flows*: Named branches (A1, A2, ...) for error handling, validation failures, and edge cases.
 * *Postconditions*: The guaranteed system state after successful completion.
 Postconditions are what your tests assert.
+* *Business Rules*: Numbered rules (BR-001, BR-002, ...) that capture validation constraints, calculation logic, or domain invariants.
+Business rules make implicit knowledge explicit.
+Without them, the AI invents its own validation logic -- or skips it entirely.
 
 This structure follows Alistair Cockburn's Use Case format, which LLMs recognize reliably.
 The more precise the use case, the less the AI has to guess during implementation.
@@ -431,7 +434,7 @@ Consider assigning different AI models to different review roles.
 Run ATAM reviews after each major architectural change, not just once.
 Groom the backlog more frequently as the project grows.
 *Legacy codebases*:: This workflow assumes you start from scratch.
-See link:brownfield-workflow.adoc[Adapting the Workflow to Brownfield Projects] for a dedicated guide covering reverse engineering, baseline test coverage, and incremental migration using bounded contexts.
+See link:#/brownfield[Adapting the Workflow to Brownfield Projects] for a dedicated guide covering reverse engineering, baseline test coverage, and incremental migration using bounded contexts.
 *Frontend / HTML applications*:: This workflow works well for backend code, CLIs, and libraries where the compiler and TDD provide strong error correction.
 Frontend applications can be built with the same approach, but consistent UI is harder to verify automatically.
 The error correction layers that make backend development reliable (compiler errors, test failures) have no direct equivalent for visual consistency.
@@ -457,7 +460,7 @@ The essential one-liners for each phase, with the Semantic Anchors they activate
 |link:#/anchor/plain-english-strunk-white[Strunk & White]
 
 |Specification
-|`Create a detailed spec with Use Cases (Trigger, Main Flow, Alternative Flows, Postconditions), Activity Diagrams (all paths), and Gherkin acceptance criteria.`
+|`Create a detailed spec with Use Cases (Trigger, Main Flow, Alternative Flows, Postconditions, Business Rules), Activity Diagrams (all paths), and Gherkin acceptance criteria.`
 |link:#/anchor/gherkin[Gherkin]
 
 |Architecture
@@ -529,7 +532,7 @@ Start with the Socratic Method for requirements and see where it leads.
 If you discover anchors that work well in your workflow, https://github.com/LLM-Coding/Semantic-Anchors/blob/main/CONTRIBUTING.md[contribute them to the collection].
 
 Once you are comfortable with this greenfield workflow, you can adapt it to existing codebases.
-See link:brownfield-workflow.adoc[Adapting the Workflow to Brownfield Projects] for a step-by-step guide.
+See link:#/brownfield[Adapting the Workflow to Brownfield Projects] for a step-by-step guide.
 
 === Further Reading
 

docs/specs/01_use_cases.adoc

@@ -47,6 +47,10 @@ stop
 * URL enthält Filter-Parameter (für Deep-Linking)
 * Filter-Auswahl wird in localStorage persistiert
 
+=== Geschäftsregeln
+* **BR-01-001**: Ein Anker kann mehreren Rollen zugeordnet sein. Filterung zeigt alle Anker, die mindestens eine der ausgewählten Rollen enthalten.
+* **BR-01-002**: Bei Auswahl von "All Roles" oder leerem Filter werden alle Anker ohne Einschränkung angezeigt.
+
 === Fehlerszenarien
 * **F1**: Keine Anker für ausgewählte Rolle → System zeigt "Keine Anker gefunden für diese Rolle"
 * **F2**: Browser-localStorage nicht verfügbar → Filter wird nicht persistiert, aber funktioniert während Session
@@ -100,6 +104,10 @@ stop
 * Treemap ist interaktiv und responsive
 * Kategorien sind proportional zur Anzahl ihrer Anker dargestellt
 
+=== Geschäftsregeln
+* **BR-02-001**: Kategorie-Größe in der Treemap entspricht der Anzahl der enthaltenen Anker.
+* **BR-02-002**: Kategorien ohne Anker (nach Filterung) werden nicht dargestellt.
+
 === Fehlerszenarien
 * **F1**: Metadata-Datei nicht gefunden → System zeigt Fehlermeldung "Kategorien können nicht geladen werden"
 * **F2**: Sehr kleine Bildschirmgröße → Treemap wird zu vereinfachter Liste
@@ -151,6 +159,11 @@ stop
 * Suchergebnisse sind nach Relevanz sortiert
 * URL enthält Suchquery (für Deep-Linking)
 
+=== Geschäftsregeln
+* **BR-03-001**: Suche durchsucht Anker-Namen, Proponenten, Core Concepts und Tags. Andere Felder werden nicht durchsucht.
+* **BR-03-002**: Suche wird debounced (min. 150ms Verzögerung) um übermäßige Anfragen zu vermeiden.
+* **BR-03-003**: Suchbegriffe werden auf maximal 100 Zeichen begrenzt.
+
 === Fehlerszenarien
 * **F1**: Suchindex nicht geladen → System zeigt "Suche vorübergehend nicht verfügbar"
 * **F2**: Sehr lange Suchbegriffe → System limitiert auf 100 Zeichen
@@ -249,6 +262,11 @@ stop
 * Sprachpräferenz wird bei nächstem Besuch beibehalten
 * `<html lang="...">` ist korrekt gesetzt
 
+=== Geschäftsregeln
+* **BR-05-001**: Unterstützte Sprachen: Englisch (EN) und Deutsch (DE). Englisch ist die Standardsprache.
+* **BR-05-002**: Nur UI-Texte (Navigation, Labels, Buttons, Tooltips) werden übersetzt. Anker-Inhalte bleiben in der Originalsprache.
+* **BR-05-003**: Fehlende Übersetzungen fallen auf Englisch zurück, niemals auf leere Strings.
+
 === Fehlerszenarien
 * **F1**: Übersetzung fehlt → System zeigt Fallback auf Englisch
 * **F2**: localStorage nicht verfügbar → Sprache nur für aktuelle Session
@@ -295,6 +313,10 @@ stop
 * Theme-Präferenz wird persistiert
 * Alle Komponenten (inkl. Treemap) respektieren Theme
 
+=== Geschäftsregeln
+* **BR-06-001**: Theme-Ermittlung folgt der Priorität: 1. localStorage, 2. `prefers-color-scheme`, 3. Light als Default.
+* **BR-06-002**: Theme-Wechsel erfolgt ohne Seiten-Reload und ohne visuelles Flackern.
+
 === Fehlerszenarien
 * **F1**: localStorage nicht verfügbar → Theme nur für Session, reagiert auf prefers-color-scheme
 * **F2**: Theme-CSS nicht geladen → Fallback auf System-Theme
@@ -362,6 +384,11 @@ stop
 * Automatisches Feedback ist gepostet (bei Validation)
 * Bei Approval: PR ist erstellt mit generiertem Content
 
+=== Geschäftsregeln
+* **BR-07-001**: Jeder vorgeschlagene Anker muss die vier Qualitätskriterien erfüllen: Precise, Rich, Consistent, Attributable.
+* **BR-07-002**: Vorschläge, die reine Instruktionen ohne konzeptuelle Tiefe sind (z.B. "TLDR", "ELI5"), werden abgelehnt.
+* **BR-07-003**: Duplikate bestehender Anker werden abgelehnt mit Verweis auf den existierenden Eintrag.
+
 === Fehlerszenarien
 * **F1**: GitHub Actions Workflow schlägt fehl → Issue bleibt ohne Auto-Comment, manueller Review nötig
 * **F2**: Copilot API nicht verfügbar → Maintainer erstellt Entry manuell
@@ -420,6 +447,10 @@ stop
 * Issue hat passendes Label
 * Contributor hat klares Feedback
 
+=== Geschäftsregeln
+* **BR-08-001**: Validierungs-Score basiert auf einer 10-Punkt-Skala. Score > 7 gilt als "validated".
+* **BR-08-002**: Die vier Bewertungskriterien sind: Precise, Rich, Consistent, Attributable — gleichgewichtet.
+
 === Fehlerszenarien
 * **F1**: Copilot API Timeout → Workflow posted "Validation failed, manual review required"
 * **F2**: Issue-Body unlesbar → Workflow posted "Cannot parse issue, please use template"
@@ -519,6 +550,11 @@ stop
 * URL ist share-bar (kopierbar)
 * State (Filter, Language) ist in URL kodiert
 
+=== Geschäftsregeln
+* **BR-10-001**: Gültige Deep-Link-Formate: `#/anchor/<anchor-id>` (Hash-basiert).
+* **BR-10-002**: Anker-IDs sind case-sensitive und müssen exakt mit der ID in der Anchor-Datei übereinstimmen.
+* **BR-10-003**: Filter- und Sprachparameter aus der URL werden beim Laden angewendet.
+
 === Fehlerszenarien
 * **F1**: Anker-ID ungültig → 404 Seite mit Suchfunktion
 * **F2**: Alter Link (nach Rename) → System zeigt Redirect-Hinweis oder 301 Redirect

scripts/render-docs.js

@@ -84,6 +84,11 @@ renderFile(
   path.join(WEB_DOCS, 'spec-driven-workflow.html')
 )
 
+renderFile(
+  path.join(ROOT, 'docs/brownfield-workflow.adoc'),
+  path.join(WEB_DOCS, 'brownfield-workflow.html')
+)
+
 renderFile(
   path.join(ROOT, 'docs/anchor-evaluations.adoc'),
   path.join(WEB_DOCS, 'anchor-evaluations.html')

website/public/data/contracts.json

@@ -6,8 +6,8 @@
     "description": "What we mean when we say 'spec'",
     "descriptionDe": "Was wir meinen, wenn wir 'Spec' sagen",
     "anchors": ["gherkin", "bdd-given-when-then"],
-    "template": "When we talk about a \"specification\" or \"spec\", we mean:\n- Use Cases with Trigger, Main Flow, Alternative Flows, and Postconditions\n- Activity Diagrams for all flows (not just the happy path)\n- Acceptance criteria in Gherkin format (Given/When/Then)",
-    "templateDe": "Wenn wir von einer \"Spezifikation\" oder \"Spec\" sprechen, meinen wir:\n- Use Cases mit Trigger, Hauptablauf, Alternativabläufe und Nachbedingungen\n- Activity Diagrams für alle Abläufe (nicht nur der Happy Path)\n- Akzeptanzkriterien im Gherkin-Format (Given/When/Then)",
+    "template": "When we talk about a \"specification\" or \"spec\", we mean:\n- Use Cases with Trigger, Main Flow, Alternative Flows, Postconditions, and Business Rules (BR-IDs)\n- Activity Diagrams for all flows (not just the happy path)\n- Acceptance criteria in Gherkin format (Given/When/Then)",
+    "templateDe": "Wenn wir von einer \"Spezifikation\" oder \"Spec\" sprechen, meinen wir:\n- Use Cases mit Trigger, Hauptablauf, Alternativabläufe, Nachbedingungen und Geschäftsregeln (BR-IDs)\n- Activity Diagrams für alle Abläufe (nicht nur der Happy Path)\n- Akzeptanzkriterien im Gherkin-Format (Given/When/Then)",
     "category": "requirements"
   },
   {

website/src/main.js

@@ -110,6 +110,7 @@ function initApp() {
   addRoute('/rejected-proposals', renderRejectedProposalsPage)
   addRoute('/all-anchors', renderAllAnchorsPage)
   addRoute('/workflow', renderWorkflowPage)
+  addRoute('/brownfield', renderBrownfieldPage)
   addRoute('/contracts', renderContractsPageHandler)
   addRoute('/evaluations', renderEvaluationsPage)
 
@@ -233,6 +234,15 @@ function renderWorkflowPage() {
   loadDocContent('docs/spec-driven-workflow.adoc')
 }
 
+function renderBrownfieldPage() {
+  const pageContent = document.getElementById('page-content')
+  if (!pageContent) return
+
+  pageContent.innerHTML = renderDocPage()
+  updateActiveNavLink()
+  loadDocContent('docs/brownfield-workflow.adoc')
+}
+
 function renderContractsPageHandler() {
   const pageContent = document.getElementById('page-content')
   if (!pageContent) return
@@ -458,6 +468,8 @@ function handleLanguageChange() {
     loadDocContent('docs/all-anchors.adoc')
   } else if (currentRoute === '/workflow') {
     loadDocContent('docs/spec-driven-workflow.adoc')
+  } else if (currentRoute === '/brownfield') {
+    loadDocContent('docs/brownfield-workflow.adoc')
   } else if (currentRoute === '/') {
     initCardGridVisualization()
   }

website/src/utils/router.js

@@ -17,6 +17,7 @@ const ROUTE_TITLES = {
   '/about': 'About — Semantic Anchors',
   '/contracts': 'Semantic Contracts — Semantic Anchors',
   '/workflow': 'Development Workflow — Semantic Anchors',
+  '/brownfield': 'Brownfield Workflow — Semantic Anchors',
   '/evaluations': 'Evaluations — Semantic Anchors',
   '/contributing': 'Contributing — Semantic Anchors',
   '/changelog': 'Changelog — Semantic Anchors',