# Chain Workbench - Analyse-Basis und Erweiterungen

> **Version:** 0.5.x  
> **Stand:** 2025-01-XX  
> **Zielgruppe:** Entwickler, Architekten

---

## Übersicht

Die Chain Workbench (0.5.x) basiert **hauptsächlich** auf den Analysen aus Chain Inspector (0.4.x), erweitert diese aber um zusätzliche Heuristiken und granularere Todo-Generierung.

---

## Basis: Chain Inspector 0.4.x Analysen

### Template Matching (0.4.x)

Die Workbench nutzt direkt die **Template Matches** aus Chain Inspector:

- **`TemplateMatch` Interface:**
  - `templateName`: Name des Templates
  - `score`: Match-Score (+10 pro Link, +2 pro Slot, -5 pro fehlendem required Link)
  - `slotAssignments`: Map von Slot-ID → Node-Referenz
  - `missingSlots`: Array von fehlenden Slot-IDs
  - `satisfiedLinks`: Anzahl erfüllter Links
  - `requiredLinks`: Anzahl erforderlicher Links
  - `roleEvidence`: Array von Edge-Role-Evidence
  - `slotsComplete`: Boolean
  - `linksComplete`: Boolean
  - `confidence`: "confirmed" | "plausible" | "weak"

**Quelle:** `src/analysis/chainInspector.ts` → `inspectChains()` → `matchTemplates()`

### Findings aus 0.4.x (aktuell NICHT verwendet, aber sollten integriert werden)

**Status:** Die Findings aus Chain Inspector werden aktuell **nicht** in der Workbench verwendet, obwohl sie aufwendig getestet wurden und wertvolle Informationen liefern.

**Findings aus 0.4.x:**
- `missing_edges` - Section hat Content aber keine Edges
- `one_sided_connectivity` - Nur incoming oder nur outgoing edges
- `only_candidates` - Nur Candidate-Edges, keine expliziten
- `dangling_target` - Target-Datei existiert nicht
- `dangling_target_heading` - Target-Heading existiert nicht
- `no_causal_roles` - Section hat Edges aber keine kausalen Rollen
- `missing_slot_<slotId>` - Template-basiert: Slot fehlt (aggregiert)
- `missing_link_constraints` - Template-basiert: Links fehlen (aggregiert)
- `weak_chain_roles` - Template-basiert: Nur non-causal Rollen (aggregiert)

**Warum aktuell nicht verwendet?**
- Die Workbench fokussiert sich aktuell nur auf **Template-basierte Todos**
- Findings sind teilweise **aggregiert** (z.B. "missing_slot_trigger" für alle Matches)
- Workbench benötigt **granulare Todos** pro Match (z.B. "missing_slot_trigger" für jeden Match einzeln)
- Workbench benötigt **konkrete Actions** (z.B. `insert_edge_forward`, `create_note_via_interview`)

**Sollten integriert werden:**
Die Findings könnten als **zusätzliche Todos** integriert werden:
- `dangling_target` → Todo mit Action `create_missing_note` oder `retarget_link`
- `dangling_target_heading` → Todo mit Action `create_missing_heading` oder `retarget_to_existing_heading`
- `only_candidates` → Todo mit Action `promote_all_candidates` oder `create_explicit_edges`
- `missing_edges` → Todo mit Action `add_edges_to_section`
- `no_causal_roles` → Todo ähnlich wie `weak_roles`, aber section-weit (nicht template-basiert)
- `one_sided_connectivity` → Informatives Todo (keine Action, nur Hinweis)

**Vorteil der Integration:**
- Nutzung der **getesteten Heuristiken** aus 0.4.x
- **Vollständigere Analyse** (nicht nur Template-basiert)
- **Konsistenz** zwischen Chain Inspector und Workbench

---

## Neue Analysen in 0.5.x

### 1. Status-Berechnung (`statusCalculator.ts`)

**Neu in 0.5.x:** Berechnet `MatchStatus` basierend auf Slot/Link-Erfüllung:

- **`complete`**: `slotsFilled == slotsTotal && linksSatisfied == linksRequired`
- **`near_complete`**: 
  - `slotsFilled == slotsTotal && (linksRequired - linksSatisfied) in {1,2}`
  - ODER `(slotsTotal - slotsFilled) == 1 && linksSatisfied == linksRequired`
- **`weak`**: Match vorhanden, aber nur structural/temporal Rollen (keine causal)
- **`partial`**: Sonstige Fälle mit mindestens einer Lücke

**Basis:** TemplateMatch aus 0.4.x, aber **neue Heuristik** für Status-Kategorisierung.

### 2. Granulare Todo-Generierung (`todoGenerator.ts`)

**Neu in 0.5.x:** Generiert konkrete Todos pro Match:

#### `missing_slot` Todo
- **Basis:** `match.missingSlots` aus TemplateMatch
- **Erweiterung:** 
  - Pro Slot ein Todo (nicht aggregiert)
  - Enthält `allowedNodeTypes` für Interview-Filterung
  - Enthält Actions: `["link_existing", "create_note_via_interview"]`

#### `missing_link` Todo
- **Basis:** Template-Links aus `template.links` + `match.slotAssignments`
- **Erweiterung:**
  - Prüft, ob beide Slots gefüllt sind, aber Link fehlt
  - Enthält `fromNodeRef` und `toNodeRef` (konkrete Referenzen)
  - Enthält `suggestedEdgeTypes` aus `chain_roles.yaml`
  - Enthält Actions: `["insert_edge_forward", "insert_edge_inverse", "choose_target_anchor"]`

#### `weak_roles` Todo
- **Basis:** `match.roleEvidence` aus TemplateMatch
- **Erweiterung:**
  - Prüft, ob alle Rollen structural/temporal sind (keine causal)
  - Enthält Liste von `edges` mit `currentRole` und `suggestedRoles`
  - Enthält Actions: `["change_edge_type"]`

#### `candidate_cleanup` Todo (NEU)
- **Basis:** Candidate-Edges aus `graphIndex` + `missing_link` Todos
- **Vollständig neu:**
  - Findet Candidate-Edges, die zu `missing_link` Requirements passen
  - **Relation-Equality-Check:** Prüft, ob bereits ein confirmed Edge für dieselbe Relation existiert
  - Wenn ja → kein Todo (verhindert Duplikate)
  - Wenn nein → Todo mit `promote_candidate` Action

**Relation-Equality-Logik:**
```typescript
// Prüft:
// 1. Direction match (from → to)
// 2. Node-Refs match (file + heading)
// 3. Canonical Edge-Type match (via edge_vocabulary.md)
```

### 3. Effective Required Links Resolution

**Neu in 0.5.x:** Resolved `required_links` Flag mit Priorität:

1. `template.matching?.required_links` (höchste Priorität)
2. `profile.required_links`
3. `defaults.matching?.required_links`
4. Fallback: `false`

**Basis:** TemplateMatch nutzt bereits `requiredLinks`, aber Workbench benötigt explizite Resolution für UI-Darstellung.

---

## Vergleich: Findings vs. Todos

| Aspekt | Chain Inspector 0.4.x (Findings) | Chain Workbench 0.5.x (Todos) |
|--------|----------------------------------|-------------------------------|
| **Granularität** | Aggregiert (pro Template-Typ) | Granular (pro Match, pro Slot/Link) |
| **Format** | `Finding` Interface (code, severity, message) | `WorkbenchTodoUnion` Interface (type, actions, refs) |
| **Actions** | Keine (nur Informativ) | Konkrete Actions (`insert_edge_forward`, etc.) |
| **Basis** | Template Matches + Gap-Heuristiken | Template Matches + zusätzliche Analysen |
| **Verwendung** | Console-Output, Fix Findings Command | Workbench UI, interaktive Bearbeitung |

---

## Abhängigkeiten

### Direkte Abhängigkeiten (0.4.x)

1. **`TemplateMatch`** aus `chainInspector.ts`
   - Wird direkt verwendet für Status-Berechnung und Todo-Generierung

2. **`ChainTemplatesConfig`** aus `dictionary/types.ts`
   - Wird verwendet für Slot/Link-Definitionen und `allowed_node_types`

3. **`ChainRolesConfig`** aus `dictionary/types.ts`
   - Wird verwendet für `suggestedEdgeTypes` in `missing_link` Todos

4. **`EdgeVocabulary`** aus `vocab/types.ts`
   - Wird verwendet für Canonical-Type-Resolution (Relation-Equality)

5. **`IndexedEdge[]`** aus `graphIndex.ts`
   - Wird verwendet für Candidate/Confirmed-Edge-Trennung

### Indirekte Abhängigkeiten

1. **Template Matching Algorithmus** (0.4.x)
   - Backtracking-Algorithmus für Slot-Assignment
   - Scoring-Mechanismus (+10 pro Link, +2 pro Slot, -5 pro fehlendem required Link)

2. **Edge-Role-Mapping** (0.4.x)
   - `chain_roles.yaml` → Edge-Types → Roles
   - Wird verwendet für `weak_roles` Detection

---

## Neue Heuristiken (nicht in 0.4.x)

### 1. Relation-Equality-Check

**Zweck:** Verhindert Duplikate bei Candidate-Cleanup.

**Logik:**
- Prüft, ob bereits ein confirmed Edge für dieselbe Relation existiert
- Relation = (fromNodeRef, toNodeRef, canonicalEdgeType)
- Wenn ja → kein `candidate_cleanup` Todo

**Implementierung:** `todoGenerator.ts` → `checkRelationExists()`

### 2. Status-Kategorisierung

**Zweck:** Priorisierung von Matches in Workbench UI.

**Logik:**
- `complete` → höchste Priorität (grün)
- `near_complete` → hohe Priorität (gelb)
- `partial` → mittlere Priorität (orange)
- `weak` → niedrige Priorität (rot)

**Implementierung:** `statusCalculator.ts` → `calculateMatchStatus()`

### 3. Effective Required Links Resolution

**Zweck:** Korrekte Darstellung von Link-Requirements in UI.

**Logik:**
- Resolved `required_links` Flag mit Priorität (template > profile > defaults)
- Beeinflusst, ob `missing_link` Todos generiert werden

**Implementierung:** `statusCalculator.ts` → `getEffectiveRequiredLinks()`

---

## Zusammenfassung

### Basierend auf 0.4.x

✅ **Template Matches** - Direkt verwendet  
✅ **Slot-Assignments** - Direkt verwendet  
✅ **Missing Slots** - Direkt verwendet  
✅ **Role Evidence** - Direkt verwendet  
✅ **Edge-Role-Mapping** - Direkt verwendet  
✅ **Canonical Edge Types** - Direkt verwendet  

### Neu in 0.5.x

🆕 **Status-Berechnung** - Neue Heuristik  
🆕 **Granulare Todos** - Pro Match, pro Slot/Link  
🆕 **Candidate-Cleanup** - Relation-Equality-Check  
🆕 **Effective Required Links** - Prioritäts-Resolution  
🆕 **Action-System** - Konkrete Actions pro Todo  

### Nicht verwendet aus 0.4.x (sollten integriert werden)

⚠️ **Findings** - Werden aktuell nicht verwendet, sollten aber integriert werden  
⚠️ **Gap-Heuristiken** - Werden aktuell nicht verwendet, sollten aber integriert werden  
⚠️ **Dangling Target Checks** - Werden aktuell nicht verwendet, sollten aber integriert werden  

**Empfehlung:** Die Findings sollten als **zusätzliche Todos** in die Workbench integriert werden, um die getesteten Heuristiken zu nutzen und eine vollständigere Analyse zu bieten.  

---

## Fazit

Die Chain Workbench (0.5.x) basiert **hauptsächlich** auf den Template Matches aus Chain Inspector (0.4.x), erweitert diese aber um:

1. **Granulare Todo-Generierung** (pro Match, pro Slot/Link)
2. **Status-Kategorisierung** (complete, near_complete, partial, weak)
3. **Candidate-Cleanup-Heuristik** (Relation-Equality-Check)
4. **Action-System** (konkrete Actions pro Todo)

**Aktueller Stand:**
Die Workbench verwendet aktuell **nur** die Template Matches aus 0.4.x, nicht die Findings. Dies ermöglicht eine **interaktive Bearbeitung** mit konkreten Actions.

**Empfohlene Erweiterung:**
Die Findings aus 0.4.x sollten als **zusätzliche Todos** integriert werden, um:
- Die **getesteten Heuristiken** zu nutzen
- Eine **vollständigere Analyse** zu bieten (nicht nur Template-basiert)
- **Konsistenz** zwischen Chain Inspector und Workbench zu gewährleisten

**Nächste Schritte:**
1. Findings aus `report.findings` in `buildWorkbenchModel` einlesen
2. Findings zu Todos konvertieren (mit entsprechenden Actions)
3. Findings-Todos zu den Template-basierten Todos hinzufügen
4. UI erweitern, um beide Todo-Typen anzuzeigen

---

**Letzte Aktualisierung:** 2025-01-XX  
**Version:** 0.5.x