docs: sterk utvidelse av GEMINI.md — TUI-kontekst, GCP-regler, agent-intelligens og anti-dumhet

2026-05-30 20:10:19 +02:00 · 2026-05-30 20:10:19 +02:00 · d453e09e60
commit d453e09e60
parent 379bbc523d
1 changed files with 241 additions and 31 deletions
--- a/.gemini/GEMINI.md
+++ b/.gemini/GEMINI.md
@ -11,19 +11,109 @@ MCP_NAME:       OPAX-MCP
 MCP_PROTOCOL:   OPAX Protocol
 ROOT_DOMAIN:    vauco.no
 HUB_URL:        https://opax.vauco.no
+GCP_PROJECT:    propane-will-491900-m5
+GCP_REGION:     us-central1
+CLOUD_RUN_SVC:  osvauco-agent
+ARTIFACT_REPO:  gcr.io/propane-will-491900-m5
 ```

 > These values are LOCKED. Do NOT change without explicit human instruction.

 ---

+## Kontekst: Hvordan denne agenten brukes
+
+**Denne agenten kjøres utelukkende i Gemini TUI** (terminal, interaktiv CLI).
+Det er ingen nettleser, ingen GUI, ingen web-editor. Alt skjer i terminalen.
+
+### Hva dette betyr for oppførsel:
+- Du HAR tilgang til `gcloud`, `docker`, `git`, `curl`, `grep`, `cat`, `bash` — **bruk dem**.
+- Du HAR tilgang til loggene — **les dem** i stedet for å gjette.
+- Du er **inne i repoet** (`~/OSVauco`) — du kan lese filer direkte.
+- Internett-søk er **siste utvei**, ikke første instinkt.
+- Operatøren (Marte) er teknisk. Ikke over-forklar. Vær presis og effektiv.
+
+---
+
+## Intelligence Rules — Vær smart, ikke lat
+
+> En god agent løser problemer. En dårlig agent googler dem.
+
+### Regel 1: Hent data først, konkluder etterpå
+
+NÅR noe feiler:
+1. **Les faktiske logger** (build, runtime, HTTP)
+2. **Parse error-meldingen** fra loggene
+3. **Finn rot-årsaken** i koden eller config
+4. **Presenter en konkret fix** med diff
+
+NÅR du er usikker på state:
+```bash
+# Sjekk hva som faktisk kjører
+gcloud run services describe $CLOUD_RUN_SVC \
+  --project=$GCP_PROJECT --region=$GCP_REGION \
+  --format="yaml(status,spec.template.spec.containers)"
+
+# Sjekk siste image som ble bygget
+gcloud artifacts docker images list \
+  gcr.io/$GCP_PROJECT/osvauco-agent \
+  --project=$GCP_PROJECT \
+  --sort-by=~CREATE_TIME \
+  --limit=3
+```
+
+### Regel 2: Aldri gjett exit codes
+
+| Exit code | Betyr | Handling |
+|-----------|-------|----------|
+| `125` | Docker daemon-feil / ukjent flagg | Les build-logg, finn flagget |
+| `1` | Generell appfeil | Les stderr i logg |
+| `137` | OOM / killed | Sjekk minne-limits i cloudbuild.yaml |
+| `2` | Misuse av shell / kommando | Feil argument til gcloud/docker |
+| Non-zero fra docker build | Dockerfile-linje feiler | Les `Step X/Y` som feilet i loggen |
+
+### Regel 3: Aldri fiks symptomer — fiks rot-årsak
+
+❌ Feil: «build feiler → legg til --no-cache»  
+✅ Riktig: «build feiler → les logg → Step 3/8 feiler på apt-get → dependency mangler → fiks Dockerfile"
+
+### Regel 4: Bekreft alltid før du konkluderer at noe virker
+
+Etter enhver endring:
+```bash
+# Bekreft at ny revisjon er aktiv
+gcloud run revisions list \
+  --service=$CLOUD_RUN_SVC \
+  --project=$GCP_PROJECT \
+  --region=$GCP_REGION \
+  --limit=3
+
+# Bekreft at endepunktet svarer
+curl -s -o /dev/null -w "%{http_code}" \
+  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
+  https://osvauco-agent-357036551735.us-central1.run.app/health
+```
+
+### Regel 5: Bruk strukturerte observasjoner
+
+Når du rapporterer en feil, skriv alltid:
+```
+OBSERVASJON: [hva du faktisk leste i loggene]
+ROT-ÅRSAK:   [hva som faktisk feilet og hvorfor]
+FIX:         [konkret endring med diff]
+VERIFY:      [kommando for å bekrefte fix]
+```
+
+---
+
 ## Session Protocol (Nemotron Loop)

 ### BOOT
 - Read `docs/AGENT_RULEBOOK.md`, `docs/VAUCO_OS_ROADMAP.md`, and `docs/OSVAUCO_OPAX_SESSION_LOG.md`.
- Print LOCKED DEFINITIONS (`MCP_NAME`, `MCP_PROTOCOL`, `HUB_URL`, `ROOT_DOMAIN`).
+- Print LOCKED DEFINITIONS (`MCP_NAME`, `MCP_PROTOCOL`, `HUB_URL`, `ROOT_DOMAIN`, `GCP_PROJECT`).
 - Print the last `## NESTE OPPGAVE` block found in the session log.
 - If no NESTE OPPGAVE found → warn and read ROADMAP NOW section instead.
+- Sjekk gjeldende GCP auth: `gcloud auth list` og `gcloud config get-value project`

 ### PLAN
 - Before any code change, write a short PLAN block in Markdown:
@ -40,7 +130,8 @@ HUB_URL:        https://opax.vauco.no
 ### VERIFY
 - Run the relevant verification command (`curl`, `gcloud`, `grep`, `git log`).
 - State result explicitly as `PASS` or `FAIL`.
- If FAIL → stop and report, do not proceed to LOG.
+- If FAIL → **les loggene** → identifiser rot-årsak → rapport.
+- IKKE gå videre til LOG før VERIFY er PASS.

 ### LOG
 - Append to `docs/OSVAUCO_OPAX_SESSION_LOG.md`:
@ -69,69 +160,188 @@ HUB_URL:        https://opax.vauco.no
 5. **Medioteq clinical data** stays in `europe-north1` inside the Medioteq GCP project boundary.
 6. **Deploy `clinical-mcp` and `clinical-orchestrator`** to the Medioteq project (`--project=<MEDIOTEQ_PROJECT_ID>`), never the Vauco project.
 7. **HITL gates**: PLAN approves order → AUDIT approves format → OPS confirms EST → Human confirms before EXEC fires.
+8. **Aldri søk på nett for å diagnostisere feil du kan lese i loggene.**
+9. **Aldri anta at noe virker — verifiser alltid med en faktisk kommando.**
+10. **Aldri gjett på koden — les den.** Du er i repoet. Bruk `cat`, `grep`, `git diff`.

 ---

-## Diagnostics Rules (CRITICAL)
+## Diagnostics Playbook (KRITISK)

-> **Regel: Aldri gjett. Alltid hent faktisk data før du konkluderer.**
+> **Grunnregel: Aldri gjett. Alltid hent faktisk data før du konkluderer.**

-### Ved build-feil (Cloud Build)
-
-NÅR `gcloud builds submit` feiler → kjør ALLTID dette FØR du gjør noe annet:
+### 🔴 Cloud Build feiler

 ```bash
-# Hent siste build-ID og vis logg direkte
+# Steg 1: Hent siste build-ID og vis hele loggen
 BUILD_ID=$(gcloud builds list \
  --project=propane-will-491900-m5 \
  --limit=1 \
  --format="value(id)")

 gcloud builds log $BUILD_ID \
-  --project=propane-will-491900-m5 2>&1 | tail -80
+  --project=propane-will-491900-m5 2>&1 | tail -100
 ```

- IKKE søk på nett før du har lest loggene.
- IKKE gjett på årsak basert på exit code alene.
- Exit code 125 = Docker-feil → les logg for å se hvilken linje som feilet.
+Les output:
+- Finn linjen `Step X/Y` som feilet
+- Les error-meldingen på den linjen
+- Sjekk Dockerfile/cloudbuild.yaml mot feilen
+- IKKE søk på nett før du har lest og forstått feilen

-### Ved deploy-feil (Cloud Run)
+Vanlige årsaker:
+- `exit 125` → Docker ukjent flagg eller image-pull feil → les «Step» som feilet
+- `exit 1` på apt-get → dependency ikke funnet → sjekk pakkenavn
+- `exit 1` på COPY → fil eksisterer ikke i build-kontekst → sjekk .dockerignore
+- `exit 1` på pip install → requirements-konflikt → les pip-output i loggen
+
+### 🔴 Cloud Run svarer ikke / returnerer feil

 ```bash
-# Hent Cloud Run-logger
+# Steg 1: Sjekk om tjenesten er oppe
+gcloud run services describe osvauco-agent \
+  --project=propane-will-491900-m5 \
+  --region=us-central1 \
+  --format="value(status.conditions)"
+
+# Steg 2: Les runtime-logger
 gcloud logging read \
  'resource.type=cloud_run_revision AND resource.labels.service_name=osvauco-agent' \
  --project=propane-will-491900-m5 \
  --limit=50 \
-  --format="value(textPayload)"
-```
+  --order=desc \
+  --format="table(timestamp,textPayload,jsonPayload.message)"

-### Ved HTTP-feil (4xx/5xx fra tjeneste)
-
-```bash
-# Test direkte mot Cloud Run URL (bypasser IAP)
-curl -s -o /dev/null -w "%{http_code}" \
+# Steg 3: Test endepunktet direkte (bypasser IAP)
+curl -sv -o /dev/null \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
-  https://osvauco-agent-357036551735.us-central1.run.app/ENDPOINT
+  https://osvauco-agent-357036551735.us-central1.run.app/health
 ```

-### Ved sertifikat/DNS-feil
+### 🔴 Auth / IAP-feil

 ```bash
-# Sjekk SSL-sertifikat status
-gcloud compute ssl-certificates list \
+# Sjekk hvem du er autentisert som
+gcloud auth list
+gcloud config get-value project
+
+# Hent identity token for testing
+gcloud auth print-identity-token
+
+# Sjekk IAP-tilgang
+gcloud iap web get-iam-policy \
  --project=propane-will-491900-m5 \
-  --format="table(name,managed.status,managed.domainStatus)"
+  --resource-type=cloud-run \
+  --service=osvauco-agent
 ```

-### Generell regel
+### 🔴 Docker-feil lokalt
+
+```bash
+# Bygg image lokalt for å isolere feilen
+docker build -t osvauco-test . 2>&1 | tail -40
+
+# Kjør image lokalt for å teste
+docker run --rm -p 8080:8080 \
+  -e PORT=8080 \
+  osvauco-test
+
+# Test lokalt
+curl -s http://localhost:8080/health
+```
+
+### 🔴 Secret Manager-feil
+
+```bash
+# List secrets
+gcloud secrets list --project=propane-will-491900-m5
+
+# Les en secret-verdi
+gcloud secrets versions access latest \
+  --secret=<SECRET_NAME> \
+  --project=propane-will-491900-m5
+
+# Sjekk tilgang
+gcloud secrets get-iam-policy <SECRET_NAME> \
+  --project=propane-will-491900-m5
+```
+
+### 🔴 Git/kode-feil
+
+```bash
+# Aldri gjett hva som er i en fil — les den
+cat agents/core-logic/main.py | head -50
+
+# Finn hva som endret seg sist
+git log --oneline -10
+git diff HEAD~1 HEAD -- <fil>
+
+# Sjekk hva som faktisk deployes
+git log --oneline -1
+gcloud builds list --limit=1 --format="value(source.repoSource.commitSha)"
+```
+
+### Prioritert diagnose-rekkefølge
+
+```
+FEIL OPPDAGET
+     │
+     ▼
+1. Les loggene (build / runtime / HTTP response)
+     │
+     ▼
+2. Identifiser hvilken linje/steg som feilet
+     │
+     ▼
+3. Les den aktuelle filen i repoet
+     │
+     ▼
+4. Formuler rot-årsak med OBSERVASJON/ROT-ÅRSAK/FIX
+     │
+     ▼
+5. PLAN → HITL → EXECUTE → VERIFY
+     │
+     ▼
+ALDRI: Søk på nett som første steg
+ALDRI: Gjett og prøv uten å lese loggene
+```
+
+### Diagnoseoversikt

 | Situasjon | Gjør DETTE | IKKE dette |
 |-----------|-----------|------------|
-| Build feiler | Les build-logg via `gcloud builds log` | Søk på nett |
-| Runtime-feil | Les Cloud Run-logger | Gjett på koden |
-| HTTP 404 | `curl` tjenesten direkte | Endre kode uten å bekrefte |
-| Auth-feil | `gcloud auth list` + `gcloud auth print-identity-token` | Anta token er ugyldig |
+| Build exit 125 | `gcloud builds log` → finn Step som feilet | Søk på nett |
+| Build exit 1 | `gcloud builds log` → les pip/apt-output | Anta avhengighetsfeil |
+| Cloud Run 500 | `gcloud logging read` → les stack trace | Endre kode uten å se feilen |
+| Cloud Run 404 | `curl` + les rutekonfig | Anta routing er feil |
+| Auth 403 | `gcloud iap get-iam-policy` | Anta token er utløpt |
+| Noe «virker ikke» | `gcloud run services describe` | Anta det er koden sin feil |
+
+---
+
+## GCP-konvensjoner for dette prosjektet
+
+```bash
+# Alltid bruk eksplisitt prosjekt og region
+--project=propane-will-491900-m5
+--region=us-central1
+
+# Cloud Run service
+CLOUD_RUN_SVC=osvauco-agent
+
+# Artifact Registry
+IMAGE=gcr.io/propane-will-491900-m5/osvauco-agent
+
+# Cloud Build
+gcloud builds submit --config=cloudbuild.yaml --project=propane-will-491900-m5
+
+# Deploy manuelt (hvis nødvendig)
+gcloud run deploy osvauco-agent \
+  --image=$IMAGE:latest \
+  --project=propane-will-491900-m5 \
+  --region=us-central1 \
+  --platform=managed
+```

 ---