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

2026-05-30 20:10:19 +02:00

11 KiB

Raw Blame History

GEMINI.md — OSVauco / OPAX

Gemini 2.5 Pro · Nemotron session protocol · HITL-safe

Locked Definitions

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:

Les faktiske logger (build, runtime, HTTP)
Parse error-meldingen fra loggene
Finn rot-årsaken i koden eller config
Presenter en konkret fix med diff

NÅR du er usikker på state:

# 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:

# 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, 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:
- Files to touch
- Expected outcome
- HITL gate required
Do NOT proceed to EXECUTE without human confirmation.

EXECUTE

Apply exactly the change described in the PLAN block — no more, no less.
Always show a full diff before writing any file.
Never batch unrelated edits in a single EXECUTE step.

VERIFY

Run the relevant verification command (curl, gcloud, grep, git log).
State result explicitly as PASS or FAIL.
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:

## SLUTTRAPPORT – <date> – <Phase>
- Hva: <description of change>
- Filer: <list of files changed>
- Verifisering: <command + result>

## NESTE OPPGAVE
<single next task, explicit>

At the next session start, read ## NESTE OPPGAVE before doing anything else.
The boot script reads the last NESTE OPPGAVE automatically — keep it updated.

Hard Rules

Never change LOCK LIST values without explicit human instruction.
Always show diff before writing any file.
Never batch unrelated edits in a single EXECUTE step.
OPAX (opax.vauco.no) is management plane only — it never receives raw patient data.
Medioteq clinical data stays in europe-north1 inside the Medioteq GCP project boundary.
Deploy clinical-mcp and clinical-orchestrator to the Medioteq project (--project=<MEDIOTEQ_PROJECT_ID>), never the Vauco project.
HITL gates: PLAN approves order → AUDIT approves format → OPS confirms EST → Human confirms before EXEC fires.
Aldri søk på nett for å diagnostisere feil du kan lese i loggene.
Aldri anta at noe virker — verifiser alltid med en faktisk kommando.
Aldri gjett på koden — les den. Du er i repoet. Bruk cat, grep, git diff.

Diagnostics Playbook (KRITISK)

Grunnregel: Aldri gjett. Alltid hent faktisk data før du konkluderer.

🔴 Cloud Build feiler

# 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 -100

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

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

# 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 \
  --order=desc \
  --format="table(timestamp,textPayload,jsonPayload.message)"

# 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/health

🔴 Auth / IAP-feil

# 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 \
  --resource-type=cloud-run \
  --service=osvauco-agent

🔴 Docker-feil lokalt

# 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

# 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

# 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 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

# 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

Domain Convention

Subdomain	Type	Purpose
`opax.vauco.no`	Hub / MCP	OPAX-MCP operator hub — Vauco internal only
`<client>-os.vauco.no`	Prod OS	Client live production OS
`<client>-oss.vauco.no`	Stage OS	Client staging / demo OS

Auth: Google OAuth now. BankID on -os later (Medioteq first).

Standard Boot Prompt

Paste this at the start of every Gemini TUI session:

BOOT: Read docs/AGENT_RULEBOOK.md, docs/VAUCO_OS_ROADMAP.md, docs/OSVAUCO_OPAX_SESSION_LOG.md.
Print LOCKED DEFINITIONS. Print last NESTE OPPGAVE. Do not take any action until I give a PLAN prompt.

11 KiB Raw Blame History Unescape Escape