glpi-neuroforge-mega/README.md

# GLPI NeuroForge Mega v1.4.0

Ein kontrolliertes Monorepo aus **GLPI AI Agent**, **GLPI AI Knowledgebase** und **NeuroForge + SQAR**. Ziel ist nicht ein untrennbarer Monolith, sondern eine gemeinsame Plattform mit klaren Zuständigkeiten, getrennten Credentials und nachvollziehbaren Failure-Modi.

## Unified Graph Explorer (v1.4.0)

Das read-only Control Center visualisiert Runtime/Trust, Ticket-Evidence, Learning-Lineage, Research-Provenance, einen redigierten NeuroForge-Brain-Graph sowie einen reproduzierbaren Engineering-Graph aus Go-AST und Compose. Für Dateien/Symbole/Routen gibt es zusätzlich eine statische Change-Impact-/Blast-Radius-Sicht. 2D ist der operative Default; 3D ist ein optionaler, gebundener Explorer.

Der Agent stellt diese Daten ausschließlich über einen eigenen `CONTROL_READ_TOKEN` bereit. Ein optionales `codebase-memory-mcp` kann lokal für tiefere Developer-Analyse betrieben werden, ist aber keine Produktionsabhängigkeit. Siehe `docs/UNIFIED-GRAPH.md` und `docs/CODEBASE-MEMORY-MCP.md`.

## Leitprinzipien

- **Maximale Kontrolle:** GLPI-Schreibregeln, Auto-Reply-Gates, Eskalation, Idempotenz und Audit bleiben im Agenten. NeuroForge liefert semantische Evidenz, entscheidet aber nicht über Sicherheits- oder Kommunikationsregeln.
- **Maximale Effizienz:** Chunk-Vektoren können zentral in NeuroForge/HNSW/Disk-PQ liegen; das NFVJ2 Vector Journal nutzt die integrierte SQAR-Kompression. Dokument-Updates werden batchweise synchronisiert.
- **Maximale Transparenz:** `local`, `dual` und `neuroforge` erlauben einen messbaren Cutover; Fehlerverhalten ist explizit `fail-open` oder `fail-closed`; das Control Center ist read-only.
- **Human Governance:** Maschinell erzeugte Research-Vorschläge dürfen ausschließlich ins KB-Staging. Produktiv wird Wissen erst nach menschlicher Freigabe.

## Komponenten

| Komponente | Aufgabe | Schreibrechte |
|---|---|---|
| `services/agent` | GLPI-Triage, Policies, Antworten, Eskalation, Hybrid-Reranking | GLPI nach vorhandenen Policy-Gates |
| `services/knowledge` | Knowledge Authoring, Suche, Staging, Review, Promotion | Knowledge-Dateien + Staging |
| `platform/neuroforge` | semantisches Gedächtnis, HNSW/Disk-PQ, Learning, Research, SQAR-Vector-Journal | eigenes Brain-Storage |
| `services/control` | Status, aktive Migrationsparameter, Links | **keine**; read-only |
| `ollama` | gemeinsamer lokaler Inference-Endpunkt | Modellcache |

## Schnellstart

```bash
cp .env.example .env
./scripts/generate-secrets.sh
# Werte in .env übernehmen und GLPI-Zugangsdaten setzen.

docker compose config
docker compose up -d --build
./scripts/status.sh
```

Standardmäßig bindet der Stack nur an `127.0.0.1`:

- Control Center: `http://127.0.0.1:8070`
- GLPI Agent: `http://127.0.0.1:8080`
- Knowledgebase: `http://127.0.0.1:8081`
- NeuroForge: `http://127.0.0.1:8090/admin`
- Ollama: `http://127.0.0.1:11434`

Vor dem ersten produktiven Start bleiben in `.env.example` alle automatischen GLPI-Aktionen deaktiviert und `DRY_RUN=true`.

## Kontrollierter Vektor-Cutover

`KNOWLEDGE_VECTOR_BACKEND` kennt drei Modi:

- `local`: ursprüngliches Verhalten; Chunk-Vektoren bleiben im lokalen Agent-Snapshot.
- `dual`: lokale Vektoren bleiben maßgeblich und werden zusätzlich nach NeuroForge gespiegelt. Das ist der empfohlene Beobachtungsmodus.
- `neuroforge`: NeuroForge ist für Chunk-Vektor-Persistenz und semantische Kandidatensuche maßgeblich. Titel-, Text-, Metadaten- und GLPI-Policy-Signale bleiben lokal; der Agent führt weiterhin sein deterministisches Hybrid-Reranking aus.

Mit `NEUROFORGE_FAIL_OPEN=true` kann der Agent bei Backend-Ausfall lokale/lexikalische Evidenz verwenden. Mit `false` wird ein semantischer Backend-Fehler sichtbar blockierend behandelt.

Details: [`docs/MIGRATION-CUTOVER.md`](docs/MIGRATION-CUTOVER.md).

## Kontrolliertes Lernen: erst Outcome, dann Wissen

Im produktionsnahen Standard (`NEUROFORGE_CONTROLLED_LEARNING=true`) werden rohe Chat-Eingaben und KI-Antworten **nicht automatisch** zu vertrauenswürdigem Langzeitwissen. Der Helpdesk-Lernpfad ist explizit menschlich gegated:

```text
Ticket -> KI-Vorschlag -> Techniker bestätigt/korrigiert -> auditiertes Outcome -> NeuroForge lernt
```

Im Agent-Dashboard kann ein Antwortvorschlag als **„KI-Antwort bestätigen“** oder **„KI-Antwort korrigieren“** validiert werden. Jede Entscheidung wird lokal in `ticket-outcomes.json` mit Sync-Status gespeichert. Eine spätere Korrektur überschreibt die frühere Entscheidung nicht, sondern erzeugt eine neue Revision mit `supersedes_id`. Nur `accepted` und `corrected` dürfen den App-Key-geschützten NeuroForge-Endpunkt `/api/v1/integrations/outcomes` verwenden; NeuroForge weist die vertrauenswürdige Provenance serverseitig zu.

Vor der Hochstufung verifiziert der Agent außerdem, dass sich der GLPI-Ticketzustand seit dem analysierten Run nicht geändert hat. Ein veralteter Run darf nicht als Trusted Outcome gelernt werden.

Standardmäßig ist `OUTCOME_LEARNING_FAIL_OPEN=false`: Kann das bestätigte Outcome nicht nach NeuroForge synchronisiert werden, sieht der Techniker einen Fehler. Der lokale Audit-Eintrag bleibt mit `sync_status=failed` für einen kontrollierten Retry erhalten.

v1.3.0 schließt den Feedback-Loop: aktive, menschlich validierte Outcomes werden bei späteren ähnlichen Tickets als **sekundäre Erfahrungs-Evidenz** aus NeuroForge abgerufen. Sie dürfen die Antwortauswahl unterstützen oder ihr widersprechen, ersetzen aber niemals die Pflicht zu einem freigegebenen Knowledge-Artikel. Korrekturen superseden den alten NeuroForge-Memory atomar; die alte Revision bleibt auditierbar, ist aber nicht mehr retrieval-aktiv.

```text
Ticket -> offizielle KB-Kandidaten
       -> aktive validierte Erfahrungen
       -> LLM-Auswahl unter Policy-Gates
       -> Techniker bestätigt/korrigiert
       -> NeuroForge Outcome Memory
       -> spätere Tickets profitieren davon
```

Die Wirkung kann read-only über `POST /api/quality/replay` gemessen werden. Der Replay-Runner berichtet u. a. Knowledge Recall@K/MRR, Outcome Recall@K/MRR und Fälle, in denen validierte Erfahrung einen Knowledge-Miss sichtbar macht. Beispiel: [`docs/QUALITY-REPLAY.md`](docs/QUALITY-REPLAY.md).

Details: [`docs/CONTROLLED-AUTONOMY.md`](docs/CONTROLLED-AUTONOMY.md).

## Optionales SearXNG / kontrollierte Autonomie

SearXNG ist ein echtes, aber **optionales** Compose-Profil. Der normale Stack startet es nicht. Research und zeitgesteuerte Autonomie besitzen getrennte Schalter:

```bash
# .env: echten SEARXNG_SECRET setzen
./scripts/research-up.sh
```

`research-up.sh` startet SearXNG sowie NeuroForge mit Research/SearXNG aktiviert. `NEUROFORGE_AUTONOMY_ENABLED` bleibt davon unberührt und ist standardmäßig `false`. Damit sind drei Betriebsstufen möglich:

1. Research aus – keine Webrecherche.
2. Research an, Autonomy aus – Recherche kann explizit/manuell angestoßen werden.
3. Research an, Autonomy an – fällige Research-Goals dürfen zyklisch selbst recherchieren.

Web-Evidence erhält bewusst niedrigere Source-Trust-Werte als menschlich bestätigte GLPI-Outcomes. Unabhängige Quellen können bestehende Evidence über die vorhandene Corroboration-Logik stärken; produktive KB-Promotion bleibt trotzdem menschlich kontrolliert.

## Research → Staging

Die Knowledgebase stellt einen getrennt authentifizierten Eingang bereit:

```text
POST /api/integrations/staging
Authorization: Bearer <KB_INTEGRATION_TOKEN>
```

Dieser Endpunkt kann **nur Staging-Entwürfe** erzeugen. Er kann keine produktiven Artikel schreiben und erzwingt `auto_reply=false`. Beispiel:

```bash
export KB_INTEGRATION_TOKEN='...'
./scripts/propose-draft.sh proposal.json
```

Die Promotion bleibt ausschließlich beim normalen KB-Review-Workflow.


## Obsidian / llm-wiki Export

Die Wissensbasis kann in zwei Sichten als Obsidian-kompatibler Vault exportiert werden:

- Knowledgebase: `GET /api/export/obsidian` – kanonische produktive JSON-Wissensbasis.
- Agent: `GET /api/knowledge/export/obsidian` – Live-Sicht inklusive synchronisierter GLPI-KB-Artikel und, sofern die GLPI-OpenAPI sie lesbar bereitstellt, `KnowbaseItem_Item`-Verknüpfungen.

Der Vault enthält YAML-Frontmatter, `[[Wikilinks]]`, `Wiki/Schema.md`, `Wiki/index.md`, `graph.json` und ein Manifest. Beide UIs besitzen einen **„⇩ Obsidian Export“**-Button. CLI-Helfer:

```bash
./scripts/export-obsidian.sh kb ./knowledge-vault.zip
./scripts/export-obsidian.sh agent ./live-vault.zip
```

Details: [`docs/OBSIDIAN-EXPORT.md`](docs/OBSIDIAN-EXPORT.md).

## Wichtige Sicherheitsgrenzen

1. Der Agent erhält nur den NeuroForge **App Key**, niemals den Admin-Token.
2. NeuroForge erhält keine GLPI-Credentials.
3. Das Control Center besitzt keine Admin-/Editor-Credentials.
4. KB-Health ist ohne Editor-Credentials probe-fähig; alle Editor-Funktionen bleiben Basic-Auth-geschützt.
5. Research-Vorschläge haben einen separaten `KB_INTEGRATION_TOKEN` und landen ausschließlich im Staging.
6. `runs.jsonl`, State/Idempotenz, Policy-Gates und GLPI-Aktionen werden nicht in lernendes Memory verschoben.

Siehe [`docs/CONTROL-MATRIX.md`](docs/CONTROL-MATRIX.md), [`docs/CONTROL-CENTER.md`](docs/CONTROL-CENTER.md) und [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).

## Validierung

```bash
./scripts/validate.sh
cd services/agent && go test -race ./internal/knowledge
cd ../../platform/neuroforge && go test -race ./internal/httpapi ./internal/store
```

Die importierten GLPI-Projekte wurden im Mega-Repo auf Go 1.23 normalisiert. Die komplette Testbasis läuft damit in der bereitgestellten Umgebung. Die ursprünglichen Quellarchive bleiben davon unberührt.

Für Qualitätsmessungen gegen historische Fälle:

```bash
python3 scripts/quality-replay.py docs/QUALITY-REPLAY-example.json --url http://127.0.0.1:8080
```

## Bewusst begrenzte Autonomie

Auch bei aktivierter Research-Autonomie veröffentlicht NeuroForge **nicht selbstständig** in die produktive Knowledgebase. Der technische Draft-Ingress ist vorhanden, aber der Übergang von einem konkreten Research-Run zu einem KB-Draft soll über einen expliziten Workflow/Job erfolgen. Das ist eine Governance-Entscheidung, kein fehlender Schreibweg.