VianoBugAnalysis/docs/source-context-relevance-v2.md

# Kontextbezogene Source-Auswahl v2

Die Überarbeitung übernimmt Prinzipien aus der untersuchten wowsrc-0.7-Referenz:
Suchanker tragen Herkunft und Rolle; Wiederholungen einer Zahl erzeugen keine
zusätzliche Relevanz; eine leere primäre Auswahl ist zulässig. Es werden keine
wowsrc-Programme ausgeführt und keine vollständigen Dateien pauschal an eine LLM
übertragen. `docs/architecture.md` bleibt unverändert.

## Anfrage und Herkunft

```json
{"kind":"source.context","text":"23487","path_prefix":"","entity_refs":["N0005"],"scope":"code"}
```

`entity_refs` und `scope` sind optional. Die Referenzen müssen auf existierende
Entitäten im kanonischen Interpretationskontext zeigen; erfundene Entitäten oder
freie Modell-Ankerlisten sind unzulässig. Ohne Referenzen ordnet der Controller
eindeutige IDs oder Namen selbst zu. Bei mehreren Entitätstypen mit gleicher ID
wird kein Typ für eine reine Zahl geraten. Die im Interpretationskontext vorhandene
kontextuelle Namensauflösung bleibt eine beobachtungsbasierte Zuordnung, kein
Beweis für Ursache oder Rolle.

Der Controller ergänzt begrenzt Namen, Schreibvarianten, konfigurierte Fokusrollen
und Kontextfakten. Gleicher Name und seine Schreibvarianten bleiben dieselbe
Ankergruppe. Scriptnamen werden nur aus zugeordneten, erfassten DB-Spalten gelesen;
die Fallzusammenfassung allein genügt dafür nicht. Im Vcore-Adapter ist dies zunächst
`creature_template.entry` → `ScriptName`. Die Konfiguration kann weitere tatsächlich
vorliegende Datensätze ergänzen; das Werkzeug führt dafür keine zusätzlichen
Datenbankabfragen aus. Ein bereits belegter Scriptname lässt sich auch direkt als
Suchbegriff verwenden.

Die ausgewählten Anker werden mit Quelle, JSON-Pointer, Typ und Rollen im Capture
gespeichert. Case- und Interpretationskontext erhalten Referenz und Hash in der
Capture-Bindung. Die Werkzeugkonfiguration und die Anker gehen in den lokalen
Abfragecache ein. Gleiche Anfragen mit anderen belegten Ankern sind andere Captures.

## Auswahlregeln

- Scriptanker und ausdrücklich angefragte Symbole liefern starke Suchkandidaten.
  Ein bekannter Anzeigename wird dadurch nicht zu einem Scriptnamen umgedeutet.
- Namen und Kontextanker liefern ergänzenden Kontext. Groß-/Kleinschreibung und
  Unterstrichvarianten sind keine unabhängige Bestätigung.
- Eine Zahl allein bleibt eine schwache Fundstelle. Nur eine zur belegten
  Entitätsart passende konfigurierte Namensraum-Bindung, beispielsweise
  `NPC_… = 23487`, kann sie zum primären Kandidaten machen. Ein `SPELL_…`-Treffer
  mit derselben Zahl ist kein NPC-Beleg.
- Solche Bindungen bleiben Textheuristiken, keine semantische C++-Analyse. Auch
  ein passend benannter Zähler könnte falsch eingeordnet werden; die LLM muss
  den tatsächlichen Code bewerten.
- Pro Datei und Ankergruppe zählt nur das stärkste Signal. Häufige Wiederholungen
  und mehrere unzugeordnete Zahlen erzeugen keinen primären Kandidaten.
- Einfache, typisierte Konstantenbindungen können zu Symbol-/Registrierungssuchen
  führen. Eine bloße Zahl führt nicht zur Erkundung sämtlicher Registrierungen
  ihrer zufällig getroffenen Datei.
- Bekannte andere Ortszuordnungen werden über optionale Operatorregeln als
  ergänzender Kontext eingeordnet. Sie werden nicht ausgeschlossen: gemeinsame
  Infrastruktur und gebietsübergreifende Mechanismen können relevant sein.

Die Auswahl enthält `primary_candidate`, `supporting_context`,
`supporting_other_location` oder `weak_numeric`. Schwache Zahlentreffer erhalten
nur kurze Fundstellenübersichten; es gibt keinen Ersatz-Primärtreffer, wenn kein
starkes Signal gefunden wurde. Die Klassifikation beschreibt Suchrelevanz, niemals
Confidence in eine Bugursache.

## Suchräume und Grenzen

`code` ist der Standard. Der Vcore-Adapter beschränkt ihn auf `src/` und schließt
SQL-Dateien aus. `schema` nutzt konfigurierte Schemaverzeichnisse, hier `sql/base/`.
`historical_sql` muss ausdrücklich angefordert werden und nutzt die konfigurierten
Archivverzeichnisse. Ein nicht zum Suchraum passender `path_prefix` wird kontrolliert
abgelehnt. Ein leerer Prefix bedeutet in v2 den konfigurierten Suchraum, nicht die
gesamte Repositorywurzel.

Numerische Suchen berücksichtigen vollständige dezimale Tokens; Teile größerer
Zahlen, Bezeichner und Fließkommazahlen zählen nicht als ID-Treffer. Andere
Schreibweisen wie hexadezimale IDs sind damit nicht ausgeschlossen oder abgedeckt.

Anzahl von Ankern, Kandidatentreffern, Suchen, schwachen Zusammenfassungen, Dateien,
Zeilen und Blöcken ist konfigurierbar begrenzt. Treffer werden vor der Auswahl von
Codeausschnitten gewichtet. Relevante Ausschnitte werden zusammengeführt; Code
wird nicht nochmals in jeder Trefferbeschreibung wiederholt. Fehlende Kontextzeilen
und gekürzte Zeilen werden gemeldet. Such-, Seed- und Ausgabelimits verhindern
weiterhin Vollständigkeitsbehauptungen außerhalb des geprüften Ausschnitts.

`selection.primary_files` darf leer sein. Das heißt lediglich, dass unter den
untersuchten Treffern kein starker Kandidat vorliegt. Es schließt dynamische Pfade,
generierten Code, andere Suchräume, nicht untersuchte Anker oder andere
Darstellungsformen nicht aus. Die bisherigen Grundwerkzeuge bleiben verfügbar.

## Aktivierung und Kompatibilität

`[source_analysis] protocol = 2` aktiviert die neue Auswahl. Projektbezogene
Namensräume, DB-Spalten und Suchverzeichnisse stehen im Projektprofil, nicht als
Vcore-Wissen im Kernalgorithmus. `focus_roles`, `context_fact_names`,
`type_markers`, `entity_tables` und optionale `location_paths` sind Operatorregeln.
Neue v2-Einstellungen ohne expliziten Protokollwechsel werden abgelehnt.

v1-Katalog, Argumentvertrag und Algorithmus bleiben für alte Konfigurationen
erhalten. Gespeicherte Kontexte werden nicht migriert; das Ausführen unter
abweichenden Einstellungen wird weiterhin kontrolliert abgelehnt. Bestehende
Prompts bleiben aus ihren gespeicherten Kontexten reproduzierbar.

## Prüfung

Lokale Tests behandeln gleiche Zahlen in unterschiedlichen Namensräumen,
massenhafte Wiederholung, Namensvarianten, reine Zahlen ohne primäre Kandidaten,
Quelltext trotz veränderter Arbeitskopie, unterschiedliche Orte bei erhaltenem
Querverweis, explizite SQL-Suchräume, ungültige Anker, Grenzen, Herkunft und
budgetierte Paket-Wiederaufnahme.

Der lesende Probeaufruf am vorhandenen Bug-20-Paket wählt N0005 (Zielkreatur) und
N0004 (Questkontext) aus. Die im Codebereich geprüften Anker ergeben keinen starken
primären Kandidaten und keine historische SQL-Sammlung; das Suchbudget wird dabei
ausdrücklich als begrenzt gemeldet. Dies ist ein lokaler Werkzeugtest, keine neue
LLM-Bewertung des Bugs und kein Nachweis realer Token-/Kostenersparnis.

Die fehlende Gateway-Schemafehlerdiagnostik für Bootstrap v21 wurde anschließend
separat korrigiert; siehe `bootstrap-schema-diagnostics.md`.