ARCHITECTURE.md

# Meta3.0 Architecture

Stand: 2026-06-15

## Ziel

Meta3.0 soll eine sehr grosse, ueber Nacht laufende Analyse der bisherigen
Agenten-/Session-Historie vorbereiten. Der Ordner soll Anforderungen aufnehmen,
Runs reproduzierbar manifestieren und Batch-/Budgetplanung sichtbar machen.

Meta3.0 ist nicht "Meta2 nochmal". Meta2.0 ist die Datenmaschine: Inventory,
Layer-1-Digests, Backfill, stabile Qwen-Batches. Meta3.0 ist der bessere
Versuchsaufbau darueber: kontrollierte Fragelogik, Evidenzpflicht,
Gegenbeweis-Suche, Validitaets-Gates und owner-faehige Verdichtung.

## Nicht-Ziel

- Keine unkontrollierten API-Calls beim Setup.
- Kein Legacy-Frage-Fanout ueber alle Rohsessions.
- Keine Edits in globalen Profilen, MCP-Configs, Registries oder anderen
  Projekten.
- Keine Secrets in Dateien.

## Datenlinie

```text
Meta2.0 Layer 0 Inventory
  -> Meta2.0 Layer 1 session_digests.jsonl
  -> Meta3.0 experiment design
  -> Meta3.0 question set + claim/evidence contract
  -> Meta3.0 batch plan + validity gates
  -> spaeter: Layer 2/3 Antworten mit Evidenz, Gegenbelegen und Owner-Fazit
```

Meta3.0 liest vorhandene Meta2.0-Artefakte read-only:

- `/home/smlflg/Projekte/Meta2.0/data/session_inventory.json`
- `/home/smlflg/Projekte/Meta2.0/data/layer1/session_digests.jsonl`
- `/home/smlflg/Projekte/Meta2.0/data/layer1/audit.json`

## Run-Vertrag

Jeder Run bekommt einen eigenen Ordner:

```text
runs/<timestamp>_<slug>/
  manifests/
    run_manifest.json
    batch_plan.json
  state/
  outputs/
  logs/
  tmp/
```

`run_manifest.json` ist die Wahrheit fuer:

- welche Fragen,
- welches Profil,
- welche Quellen,
- welche Env-Variablen vorhanden waren,
- welche Sicherheitsflags aktiv waren.

`batch_plan.json` ist die Wahrheit fuer:

- wie viele Sessions/Digests aktuell existieren,
- ob diese Zahl aus Audit-Unique-Digests oder rohen JSONL-Zeilen stammt,
- wie viele Layer-1 Backfill-Calls geschaetzt werden,
- wie viele Frage-/Synthese-Calls geschaetzt werden,
- welche Gates vor dem Start noch offen sind.

## Meta3 Improvement Contract

Ein Meta3-Run darf nur als Verbesserung gegenueber Meta2 gelten, wenn er mehr
leistet als "mehr Calls":

1. **Stratifizierte Evidenz statt blinder Masse.** Antworten muessen Quellen
   ueber Sessions, Zeitraeume und Tool-Familien streuen, damit 954 Codex-Files
   nicht automatisch alle anderen Spuren ueberrollen.
2. **Claim Ledger statt Essay.** Jede starke Aussage braucht mindestens eine
   positive Evidenz, eine Unsicherheit oder ein Gegenbeispiel und eine
   Rueckfuehrung auf konkrete Artefakte.
3. **Gegenbeweis-Pflicht.** Fuer jede Hauptthese wird aktiv nach Sessions
   gesucht, die sie schwaechen. Fehlt Gegenbeweis-Suche, ist das Ergebnis nur
   Rohsynthese.
4. **Validitaet vor Score.** Kein "finales Ergebnis", wenn Quellenabdeckung,
   Run-Manifest, Modell-/Prompt-Versionen, Call-Ledger oder Output-Artefakte
   fehlen.
5. **Fragen als Graph, nicht Liste.** Q01-Q09 erzeugen Zwischenbefunde,
   Konflikte und offene Wahrheiten; Q10 darf erst daraus verdichten.
6. **Owner-Fazit statt Agentenlarm.** Jede Antwort endet mit einer kanonischen
   These, Grenzen der Aussage und einem naechsten menschlich sinnvollen Schritt.

Der maschinenlesbare Vertrag steht in `config/experiment_design.json`. Die
blockierende Eval-Spezifikation steht in
`docs/evals/EVAL_meta3_improvement_over_meta2.md`.

## Call-Strategie

Der grosse Wert kommt nicht aus 10 Mio Fragen gegen Rohdaten, sondern aus
einmaligem, question-agnostic Digesting. Danach duerfen Fragen gegen die
verdichteten Layer laufen.

Meta3 nutzt die 10-Mio-Call-Grenze als Budget-Oberkante, nicht als Startbefehl.
Die intelligente Reihenfolge ist:

1. kleine Kalibrierung gegen vorhandene Digests,
2. Abgleich der Antwortqualitaet gegen den Improvement Contract,
3. kontrollierter Layer-1-Backfill,
4. erst danach breite Frage- und Synthese-Laeufe.

Startregel:

- sichere Meta2-Einstellung respektieren: `batch_size=3`, `concurrency=2`.
- nur hochdrehen, wenn Fehlerrate, 429-Rate und Datenqualitaet stabil bleiben.