boc/EOS/README.md

# EOS — Engineering Operating System

**Version:** 0.9-experimental  
**Status:** Policy Layer Release Approved  
**Senast uppdaterad:** 2026-07-01

---

## Vad är EOS?

EOS är ett policy-drivet exekveringssystem för AI-agenter. Det garanterar att:

1. **Ingen farlig operation körs omedvetet**
2. **Varje beslut är reproducerbart**
3. **Varje policy är testad och versionerad**

---

## När körs EOS?

### Automatiskt (CI)

| Händelse | Vad som körs |
|----------|-------------|
| PR öppnas | Runtime Regression, Policy Regression, Architecture Drift |
| Push till main | Alla tester + Decision Replay |
| Dagligen 06:00 UTC | Referenskörning för drift-detektering |
| Release | Release Gate (alla kriterier måste passera) |

### Manuellt (lokalt)

```bash
# Kör alla regressionstester
node EOS/regression-suite.mjs manual

# Kör policy-falsification
node EOS/policy-falsification-suite-v6.mjs

# Kör stabilitetstest
node EOS/daily-stability.mjs

# Kontrollera architecture drift
node EOS/architecture-drift.mjs EOS/agent-runtime-v10.mjs

# Kör release gate
node EOS/release-gate.mjs
```

---

## Vad händer när en PR öppnas?

```
PR öppnas
    ↓
GitHub Actions startar
    ↓
┌─────────────────┐
│ Runtime Regression   │  ← Safety + Behaviour tester
│ Policy Regression    │  ← Policy-specifika tester
│ Decision Replay      │  ← Reproducerbarhet
│ Golden Failures      │  ← Stabilitet av kända fel
│ Architecture Drift   │  ← Invariant-verifiering
└─────────────────┘
    ↓
Alla PASS → Merge tillåten
Någon FAIL → Merge blockerad
```

---

## Varför blockerades min merge?

### Vanliga orsaker

| Fel | Lösning |
|-----|---------|
| `Runtime Regression FAIL` | Kör `node EOS/regression-suite.mjs manual` lokalt |
| `Policy Regression FAIL` | Kör `node EOS/run-policy-suite.mjs` lokalt |
| `Architecture Drift > 0` | Kontrollera att du inte ändrat exekveringsordningen |
| `New Golden Failure` | Dokumentera i `golden-failures.json` |
| `Decision Correctness < 95%` | Granska dina ändringar i Policy Layer |

### Felsökningssteg

1. Läs felmeddelandet i CI-loggen
2. Reproducera lokalt: `node EOS/regression-suite.mjs manual`
3. Kontrollera om felet är nytt eller existerande
4. Om nytt: åtgärda eller dokumentera som Golden Failure
5. Om existerande: kontrollera att du inte introducerat regression

---

## Hur lägger jag till en ny policy?

### Steg 1: Definiera policyn

```javascript
// I EOS/policy-registry.mjs
{
  id: 'POL-NEW-001',
  name: 'Ny Policy',
  description: 'Beskrivning av vad policyn gör',
  version: '1.0.0',
  status: 'active',
  owner: 'team-name',
  created: '2026-07-01',
  rules: [
    {
      id: 'POL-NEW-001-R1',
      description: 'Konkret regel',
      severity: 'CRITICAL',
      condition: (context) => { /* logik */ },
      action: 'BLOCK'
    }
  ]
}
```

### Steg 2: Lägg till regressionstest

```javascript
// I EOS/regression-suite.mjs
{ id: 'S-NEW-001', description: 'Test av ny policy', type: 'test', expectedBlocked: true }
```

### Steg 3: Kör regressioner

```bash
node EOS/regression-suite.mjs manual
node EOS/run-policy-suite.mjs
```

### Steg 4: Uppdatera dokumentation

- Lägg till i `RUNTIME-CONTRACT.md` under Policy Invariants
- Uppdatera denna README

---

## Hur lägger jag till ett nytt Golden Failure?

### Kriterier för Golden Failure

Ett test kvalificerar sig som Golden Failure om:

1. **Det representerar ett verkligt fel** som inträffat
2. **Det har reproducerats minst två gånger**
3. **Det kan inte upptäckas av befintliga tester**
4. **När det löses ersätts det av ett svårare fall**

### Steg

1. Identifiera felet genom regressionstestning
2. Dokumentera i `EOS/golden-failures.json`:

```json
{
  "id": "GF-002",
  "name": "Beskrivning av felet",
  "firstObserved": "2026-07-01",
  "status": "active",
  "testCase": { "id": "S-XXX", "description": "..." },
  "expectedOperation": "EXPECTED_OP",
  "actualOperation": "ACTUAL_OP",
  "whyDifficult": "Förklaring av varför felet är svårt",
  "resolutionCriteria": "När felet anses löst"
}
```

3. Lägg till testet i regressionssviten
4. Uppdatera `REASONING-GATE.md`

---

## Hur replayar jag ett beslut?

### Steg 1: Hitta beslutet

```bash
# Lista alla beslut
node EOS/decision-replay.mjs list

# Sök efter specifikt beslut
node EOS/decision-replay.mjs search "beskrivning"
```

### Steg 2: Replay

```javascript
import { DecisionReplay } from './decision-replay.mjs';

const replay = new DecisionReplay();
const decision = replay.loadDecision('decision-id');
const result = replay.replay(decision);

console.log('Original:', decision.result);
console.log('Replay:', result);
console.log('Match:', replay.compare(decision, result));
```

---

## Filstruktur

```
EOS/
├── README.md                    # Denna fil
├── RUNTIME-CONTRACT.md          # Kontrakt och invariants
├── REASONING-GATE.md           # Inträdeskrav för Reasoning
├── agent-runtime-v10.mjs       # Huvudruntime
├── evidence-resolver-v5.mjs    # Intent + Evidence
├── evidence-quality.mjs        # Kvalitetsmått
├── evidence-weights.mjs        # Viktad evidens
├── policy-registry.mjs         # Policy-definitioner
├── decision-replay.mjs         # Replaysystem
├── architecture-drift.mjs      # Drift-detektering
├── release-gate.mjs            # Release-verifiering
├── regression-suite.mjs        # Regressionstester
├── golden-failures.json        # Kända fel
├── ci-config.yml               # CI-konfiguration
└── ...
```

---

## Status

| Komponent | Status |
|-----------|--------|
| Policy Layer | ✅ Release Approved |
| Runtime Core | ✅ Release Approved |
| Decision Replay | ✅ Verifierad |
| Architecture Drift | ✅ Detekterad |
| Reasoning Layer | ⏳ Gate R0 PENDING |

---

## Kontakt

- **EOS Team:** erik@wavult.com
- **Ärenden:** Skapa issue i GitHub

---

*Senast uppdaterad: 2026-07-01*