fix(ai-sdk): make interpretation-intent override reliably win

PR #34's fixed +0.25 guidance gain was too small live: for "Was empfiehlt der
EDPB zum DSB?" the binding Art. 37 (1.381) still edged out the boosted EDPB
guidance (1.348), because the live authority score gives the binding article a
topic/domain bonus the (partly English) guidance chunk does not match.

Replace the fixed gain with a deterministic lift: a semantically competitive
guideline (raw semantic >= best_binding_semantic - 0.05) is lifted just ABOVE
the best binding FINAL score (ordered by semantic), so authority/topic/domain
bonuses can no longer edge it out. Obligation questions (no intent signal) are
untouched — binding stays Top-1; off-topic guidance stays demoted.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

ai-compliance-sdk/internal/ucca/authority_rerank.go

@@ -1,20 +1,61 @@
 package ucca
 
-import "sort"
+import (
+	"sort"
+	"strings"
+)
 
 // Re-ranking coefficients (validated in the offline golden harness; Phase A — conservative).
 const (
-	authorityCoef     = 0.40 // * weight/100
-	jurisdictionGain  = 0.05 // binding/guidance from DE or EU
-	foreignPenalty    = 0.60 // foreign law on a DE/EU question (demoted, not removed)
-	unknownPenalty    = 0.08
-	domainMatchGain   = 0.15
-	offDomainPenalty  = 0.10 // off-domain binding (demoted, not removed)
-	scopePenalty      = 0.25 // BDSG Teil 3 (law enforcement) on a general DP question
-	topicGain         = 0.18 // amplifier only
-	supersededPenalty = 0.50 // superseded Alt-Quelle (pre-eu-v1): demoted, nicht versteckt
+	authorityCoef        = 0.40 // * weight/100
+	jurisdictionGain     = 0.05 // binding/guidance from DE or EU
+	foreignPenalty       = 0.60 // foreign law on a DE/EU question (demoted, not removed)
+	unknownPenalty       = 0.08
+	domainMatchGain      = 0.15
+	offDomainPenalty     = 0.10 // off-domain binding (demoted, not removed)
+	scopePenalty         = 0.25 // BDSG Teil 3 (law enforcement) on a general DP question
+	topicGain            = 0.18 // amplifier only
+	supersededPenalty    = 0.50 // superseded Alt-Quelle (pre-eu-v1): demoted, nicht versteckt
+	guidanceIntentGain   = 0.10 // epsilon a qualifying guideline is lifted ABOVE the best binding hit
+	guidanceIntentMargin = 0.05 // ...only if the guideline is semantically competitive with binding
 )
 
+// guidanceIntentSignals mark a query that EXPLICITLY asks for an interpretation /
+// recommendation by a guidance body, rather than for the binding obligation. Only
+// then may a (semantically competitive) guideline outrank the binding norm.
+var guidanceIntentSignals = []string{
+	"edpb", "europäischer datenschutzausschuss", "europaeischer datenschutzausschuss",
+	"dsk", "enisa", "bsi", "leitlinie", "guideline", "orientierungshilfe",
+	"auslegung", "empfiehlt", "empfehlung", "sagt", "laut",
+}
+
+// queryWantsGuidance reports whether the query explicitly asks for guidance/interpretation.
+func queryWantsGuidance(query string) bool {
+	q := strings.ToLower(query)
+	for _, sig := range guidanceIntentSignals {
+		if strings.Contains(q, sig) {
+			return true
+		}
+	}
+	return false
+}
+
+// bestBindingSemantic returns the highest RAW semantic score among binding-law
+// results (0 if none / intent not requested). Used as the guard threshold so an
+// off-topic guideline cannot ride the interpretation-intent boost.
+func bestBindingSemantic(results []LegalSearchResult, wantsGuidance bool) float64 {
+	if !wantsGuidance {
+		return 0
+	}
+	best := 0.0
+	for _, r := range results {
+		if r.SourceClass == "binding_law" && r.Score > best {
+			best = r.Score
+		}
+	}
+	return best
+}
+
 // authorityScore computes the normative relevance of a result for a query. It augments the
 // semantic score with authority/jurisdiction/domain/scope/topic signals. Exposed for tests.
 func authorityScore(query string, r LegalSearchResult, qDomain string, qForeign bool) float64 {
@@ -62,14 +103,43 @@ func rerankByAuthority(query string, results []LegalSearchResult) []LegalSearchR
 	}
 	qDomain := queryDomain(query)
 	qForeign := queryIsForeign(query)
+	wantsGuidance := queryWantsGuidance(query)
+	bestBindingSem := bestBindingSemantic(results, wantsGuidance)
 
 	out := make([]LegalSearchResult, len(results))
 	copy(out, results)
 	for i := range out {
 		out[i].Score = authorityScore(query, out[i], qDomain, qForeign)
 	}
+	if wantsGuidance {
+		applyGuidanceIntent(out, results, bestBindingSem)
+	}
 	sort.SliceStable(out, func(a, b int) bool {
 		return out[a].Score > out[b].Score
 	})
 	return out
 }
+
+// applyGuidanceIntent lifts semantically-competitive guidance just ABOVE the best
+// binding hit (ordered by semantic), so an EXPLICIT interpretation question can
+// return guidance Top-1. Obligation questions (no intent → not called) keep
+// binding on top. Guidance below the semantic margin is left untouched, so an
+// off-topic guideline can never ride the override — and the lift is computed from
+// the binding FINAL score, so authority/topic/domain bonuses cannot edge it out.
+func applyGuidanceIntent(out, raw []LegalSearchResult, bestBindingSem float64) {
+	bestBindingFinal := 0.0
+	for i := range out {
+		if out[i].SourceClass == "binding_law" && out[i].Score > bestBindingFinal {
+			bestBindingFinal = out[i].Score
+		}
+	}
+	for i := range out {
+		if out[i].SourceClass != "supervisory_guidance" || raw[i].Score < bestBindingSem-guidanceIntentMargin {
+			continue
+		}
+		lifted := bestBindingFinal + guidanceIntentGain + (raw[i].Score - bestBindingSem)
+		if lifted > out[i].Score {
+			out[i].Score = lifted
+		}
+	}
+}

ai-compliance-sdk/internal/ucca/legal_rag_intent_test.go

@@ -0,0 +1,72 @@
+package ucca
+
+import "testing"
+
+func intentRes(reg, sourceClass string, sem float64, weight int) LegalSearchResult {
+	return LegalSearchResult{
+		RegulationShort: reg, SourceClass: sourceClass, Score: sem,
+		AuthorityWeight: weight, Jurisdiction: "EU",
+	}
+}
+
+func TestQueryWantsGuidance(t *testing.T) {
+	wants := []string{
+		"Was empfiehlt der EDPB zum DSB?",
+		"Was sagt die ENISA zu Security Updates?",
+		"laut DSK ...",
+		"Orientierungshilfe zur DSFA",
+		"Welche BSI-Empfehlung gilt?",
+		"Auslegung der Aufsichtsbehörde",
+	}
+	plain := []string{
+		"Ab wann braucht man einen Datenschutzbeauftragten?",
+		"Welche Anforderungen bestehen an Security Updates?",
+	}
+	for _, q := range wants {
+		if !queryWantsGuidance(q) {
+			t.Errorf("should detect interpretation intent: %q", q)
+		}
+	}
+	for _, q := range plain {
+		if queryWantsGuidance(q) {
+			t.Errorf("should NOT detect intent (norm question): %q", q)
+		}
+	}
+}
+
+func TestRerank_NormQuestion_BindingStaysTop(t *testing.T) {
+	// No intent signal → binding wins even though guidance is semantically higher.
+	results := []LegalSearchResult{
+		intentRes("EDPB DPO", "supervisory_guidance", 0.64, 70),
+		intentRes("DSGVO", "binding_law", 0.58, 100),
+	}
+	out := rerankByAuthority("Ab wann braucht man einen Datenschutzbeauftragten?", results)
+	if out[0].SourceClass != "binding_law" {
+		t.Errorf("norm question: binding must stay Top-1, got %s", out[0].SourceClass)
+	}
+}
+
+func TestRerank_InterpretationQuestion_GuidanceMayWin(t *testing.T) {
+	// Explicit intent + guidance semantically competitive → guidance wins.
+	results := []LegalSearchResult{
+		intentRes("EDPB DPO", "supervisory_guidance", 0.64, 70),
+		intentRes("DSGVO", "binding_law", 0.58, 100),
+	}
+	out := rerankByAuthority("Was empfiehlt der EDPB zum Datenschutzbeauftragten?", results)
+	if out[0].SourceClass != "supervisory_guidance" {
+		t.Errorf("interpretation question: guidance should win Top-1, got %s", out[0].SourceClass)
+	}
+}
+
+func TestRerank_OffTopicGuidance_BlockedByGuard(t *testing.T) {
+	// Intent present, but guidance semantic is far below the best binding hit →
+	// the margin guard keeps binding on top (no off-topic guideline override).
+	results := []LegalSearchResult{
+		intentRes("EDPB DPO", "supervisory_guidance", 0.40, 70),
+		intentRes("DSGVO", "binding_law", 0.58, 100),
+	}
+	out := rerankByAuthority("Was empfiehlt der EDPB zum Datenschutzbeauftragten?", results)
+	if out[0].SourceClass != "binding_law" {
+		t.Errorf("off-topic guidance must not win even with intent, got %s", out[0].SourceClass)
+	}
+}