boc/SIL/README.md

System Intelligence Layer (SIL)

Ett lager mellan kodbasen och alla AI-agenter. Experiment-fas — ej aktiverad för merge-beslut ännu.

---

Arkitektur

┌─────────────────────────────────────────────────────────────┐
│                    AI-AGENTER (Bernt, etc.)                  │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              SYSTEM INTELLIGENCE LAYER (SIL)                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  OBSERVER   │  │  REASONER   │  │   PLANNER   │         │
│  │  (Ingest)   │  │  (Query)    │  │  (Action)   │         │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
│         │                │                │                 │
│         └────────────────┼────────────────┘                 │
│                          │                                  │
│                   ┌──────┴──────┐                          │
│                   │  PROVENANCE │                          │
│                   │   (Spår)    │                          │
│                   └──────┬──────┘                          │
│                          │                                  │
│                   ┌──────┴──────┐                          │
│                   │  CONFIDENCE │                          │
│                   │   SYSTEM    │                          │
│                   └──────┬──────┘                          │
│                          │                                  │
│                   ┌──────┴──────┐                          │
│                   │ CONTINUOUS  │                          │
│                   │REALITY CHECK│                          │
│                   └─────────────┘                          │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                    KUNSKAPSGRAF (Graph DB)                   │
│  Noder: Services, APIs, Tables, Deployments, Tests, etc.    │
│  Kanter: Med confidence, källa, verifieringsdatum            │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                      VERKLIGHET (Reality)                    │
│  Git · AST · Databases · K8s · Logs · Metrics · Traces      │
└─────────────────────────────────────────────────────────────┘

---

Komponenter

Fil	Syfte	Status
pr-analyzer.mjs	Analyserar PR mot kunskapsgrafen	✅ Experiment
provenance.mjs	Revisionsspår för varje slutsats	✅ Klar
metrics.mjs	Diagnostiska metriker (recall, precision, FNR, FPR)	✅ Klar
gold-set.mjs	Bygger ground truth från historiska PR:er	✅ Klar
webhook-server.mjs	Event-driven triggning (ersätter cron)	✅ Klar
experiment-report.mjs	Veckovis experimentrapport	✅ Klar
graph-version.mjs	Versionera kunskapsgrafen	✅ Klar
stability.mjs	Mät stabilitet och determinism	✅ Klar
uncertainty.mjs	Osäkerhet som förstklassig signal	✅ Klar
decision-engine.mjs	Beslutsunderlag för PR:er	✅ Klar
observability.mjs	Dashboard och metriker för SIL självt	✅ Klar
reasoning-suite.mjs	Regressionstester för resonemang	✅ Klar
architecture-policy.mjs	Arkitekturregler som kod	✅ Klar
historical-analysis.mjs	Trender och långsiktiga mönster	✅ Klar
VALIDATION_PROGRAM.md	Valideringsplan för v1.0	✅ Klar
validation/human-impact.mjs	Fråga 1: Hjälper SIL människor?	✅ Klar
validation/provenance-audit.mjs	Fråga 2: Kan SIL motivera slutsatser?	✅ Klar
validation/robustness-test.mjs	Fråga 3: Hur robust är SIL?	✅ Klar
validation/external-project-test.mjs	Fråga 4: Fungerar på okänt projekt?	✅ Klar
validation/cross-project-metrics.mjs	Tvärsnittsanalys över projekt	✅ Klar
HYPOTHESES.md	Testbara hypoteser (H1-H5)	✅ Klar
failure-review.mjs	Klassificering av fel	✅ Klar
replay-mode.mjs	Spela upp historiska analyser	✅ Klar
SIL_TECHNICAL_SPECIFICATION.md	Teknisk specifikation	✅ Klar
auto-updater.mjs	Uppdaterar grafen från verkligheten	✅ Klar
observer.mjs	Övervakar källor och upptäcker ändringar	✅ Klar

---

Experiment-fas

Kriterier för aktivering

Metrik	Mål	Nuvarande
Recall	> 85%	❓ Samla data
Precision	> 80%	❓ Samla data
False Negative Rate	< 10%	❓ Samla data
Calibration Error	< 10%	❓ Samla data

Arbetsflöde

# 1. Bygg Gold Set från historiska PR:er
node SIL/gold-set.mjs --build 100

# 2. Kör diagnostiska metriker
node SIL/metrics.mjs

# 3. Generera veckorapport
node SIL/experiment-report.mjs

# 4. Starta webhook-server (event-driven)
node SIL/webhook-server.mjs

---

Provenance (Revisionsspår)

För varje slutsats loggas:

• Vilka observationer användes? (git diff, filändringar)
• Vilka regler aktiverades? (fil → komponent-mappning)
• Vilka grafnoder traverserades? (direkta och indirekta beroenden)
• Vilka relationer användes? (kanter i grafen)
• Vilka confidence-värden påverkade slutsatsen?
• Vilken del var verifierad och vilken del var inferens?

Exempel

Slutsats: "Wallet Service påverkar Stripe"
Confidence: 0.95
Verifierad: Ja (git diff visar ändring i stripe.ts)
Infererad: Nej

Kedja:
  ✅ [observation] Hämta git diff för PR
  ✅ [rule] Mappa fil wallet/stripe.ts → Wallet Service
  ✅ [traversal] Traversera graf: Wallet → Stripe API

---

Diagnostiska Metriker

Recall

Hur många verkligt påverkade komponenter hittade SIL?

recall = true_positives / (true_positives + false_negatives)

Precision

Hur många av de rapporterade beroendena var faktiskt relevanta?

precision = true_positives / (true_positives + false_positives)

False Negative Rate

Missade SIL någon kritisk påverkan?

FNR = false_negatives / (true_positives + false_negatives)

Confidence Calibration

Stämmer confidence-värdena med verklig träffsäkerhet?

|förutsagd_confidence - verklig_träffsäkerhet| < 10%

---

Gold Set

Ground truth-dataset byggt från historiska PR:er. Varje entry innehåller:

• PR-hash och metadata
• Förutsagda komponenter (av SIL)
• Faktiskt påverkade komponenter (från git diff)
• Verifiering: korrekt/felaktig per komponent

---

Webhook-baserad Arkitektur

Ersätter cron-pollning med event-driven triggning:

GitHub/GitLab ──webhook──► SIL Webhook Server ──► PR Analyzer
                              (port 8765)

Konfiguration

# Sätt miljövariabler
export SIL_WEBHOOK_SECRET="din-hemlighet"
export SIL_WEBHOOK_PORT=8765

# Starta server
node SIL/webhook-server.mjs

GitHub Webhook URL

http://<server>:8765/github

GitLab Webhook URL

http://<server>:8765/gitlab

---

Filstruktur

SIL/
├── README.md                      # Denna fil
├── SYSTEM_INTELLIGENCE_LAYER.md   # Design-dokument
├── VALIDATION_FRAMEWORK.md        # Valideringsramverk
├── VISION.md                      # Vision och mål
├── pr-analyzer.mjs                # PR-analysator
├── provenance.mjs                 # Revisionsspår
├── metrics.mjs                    # Diagnostiska metriker
├── gold-set.mjs                   # Ground truth-byggare
├── webhook-server.mjs             # Event-driven server
├── experiment-report.mjs          # Veckorapport
├── auto-updater.mjs               # Graf-uppdaterare
├── observer.mjs                   # Källövervakare
├── shadow-log.jsonl               # Skuggläges-logg
├── gold-set.jsonl                 # Ground truth-data
├── webhook-events.jsonl           # Webhook-event-logg
└── reports/                       # Genererade rapporter

---

Nya funktioner (v0.3)

1. Graf-versionering (graph-version.mjs)

Varje uppdatering av grafen får ett versions-ID:

• Parent-version
• Timestamp
• Commit SHA
• Dataset Version
• Observer/Reasoner Version
• Jämför versioner, återskapa beslutsunderlag

2. Stabilitetstestning (stability.mjs)

• Stability Score: Samma PR analyseras N gånger
• Determinism Index: Blir resultatet identiskt?
• Graph Churn: Hur mycket ändras grafen mellan körningar?

3. Osäkerhet som signal (uncertainty.mjs)

• UNKNOWN: "Jag vet inte" — kräver manuell review
• UNCERTAIN: "Jag är osäker" — föreslå verifiering
• CERTAIN: "Jag är säker" — auto-approve OK

4. Decision Engine (decision-engine.mjs)

Beslutsunderlag för varje PR:

Risk Score: 18/100
Blast Radius: 3 services, 2 databases, 1 external
Confidence: 96%
Required Tests: Integration, Payment, Regression
Deployment: Safe Canary
Rollback: Available
Recommendation: Approve after Payment Integration Tests

5. Observability (observability.mjs)

Dashboard och metriker för SIL självt:

• Daglig rapport: beslut, osäkerhet, stabilitet
• Regelanvändning, confidence-fördelning
• HTML-dashboard
• Veckotrender för recall/precision

6. Reasoning Suite (reasoning-suite.mjs)

Regressionstester för resonemang:

• 30+ standardfrågor med kända svar
• Kategorier: impact, tests, dependencies, risk, architecture, business, rollback
• Regressionstest: jämför med tidigare körning
• Kritiska vs icke-kritiska tester

7. Architecture Policy (architecture-policy.mjs)

Arkitekturregler som kod:

• 10 regler (CRITICAL, HIGH, MEDIUM, LOW)
• UI får inte anropa databas direkt
• Alla betalningar måste vara idempotenta
• KYC-flöden måste loggas
• Blockera merge vid kritiska överträdelser

8. Historical Analysis (historical-analysis.mjs)

Trender och långsiktiga mönster:

• Moduler med flest regressionsfel
• Mest förändrade komponenter
• Lägst confidence
• Instabila beroenden
• Teknisk skuld över tid

Nästa Steg

1. ✅ Bygg Gold Set (50-100 historiska PR:er)
2. ✅ Sätt upp diagnostiska metriker
3. ✅ Implementera provenance-spårning
4. ✅ Byt från cron till webhook-baserad arkitektur
5. ✅ Graf-versionering
6. ✅ Stabilitetstestning
7. ✅ Osäkerhetshantering
8. ✅ Decision Engine
9. ✅ Observability
10. ✅ Reasoning Suite
11. ✅ Architecture Policy
12. ✅ Historical Analysis
13. ⏳ Samla data i 2-4 veckor
14. ⏳ Utvärdera mot kriterier
15. ⏳ Aktivera för merge-reviews om kriterier uppfylls

Valideringsprogram (v1.0 = Feature Complete)

6–8 veckors empirisk validering innan aktivering.

Fråga 1: Hjälper SIL människor?

• validation/human-impact.mjs — Logga beslut och utfall
• Mäter: tid till merge, regressionsbuggar, följsamhet, rätt vs fel

Fråga 2: Kan SIL motivera slutsatser?

• validation/provenance-audit.mjs — Granska 50 slumpmässiga analyser
• Checklista: regel, observation, artefakter, noder, verifierat, inferens

Fråga 3: Hur robust är SIL?

• validation/robustness-test.mjs — Simulerade förändringar
• Tester: rename, move, split, add dependency, change structure, violation

Fråga 4: Fungerar på okänt projekt?

• validation/external-project-test.mjs — Testa på open source-projekt
• validation/cross-project-metrics.mjs — Jämför över projekt

Två-lagers arkitektur

Deterministiskt lager (confidence: 0.99-1.00)
  → Graf, regler, AST, beroenden, policyer
Probabilistiskt lager (confidence: < 0.99)
  → LLM-resonemang, heuristik, uppskattningar

Success-kriterier

Kriterium	Mål
Färre regressionsfel	20% minskning
Snabbare merge	15% förbättring
Provenance completeness	> 90%
Robusthet vid refactoring	< 10% degradation
Recall på nya projekt	> 70%
Utvecklarnas förtroende	> 60% följer rekommendationer

Mål för v1.0

SIL ska kunna ta en okänd pull request, utan README eller mänsklig förklaring, analysera den utifrån kod, arkitektur, tester och telemetri och producera ett beslutsunderlag som en erfaren staff engineer skulle kunna använda för att fatta ett merge-beslut.

---

System Intelligence Layer v0.4 "Mäta för att förbättra"