From 3d2559b8a330bcc00c6b6491ebdfdbf8e6261a2d Mon Sep 17 00:00:00 2001 From: chrischristiansen-glitch Date: Sun, 31 May 2026 19:52:27 +0200 Subject: [PATCH] feat: add CLAUDE.md for Claude Code / opax2 session protocol --- CLAUDE.md | 360 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 360 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..53ce517 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,360 @@ +# CLAUDE.md — OSVauco / OPAX2 + +> Claude Opus 4.6+ · Vertex AI EU endpoint · 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: europe-west1 +GCP_VERTEX_LOC: eu +CLOUD_RUN_SVC: osvauco-agent +ARTIFACT_REPO: gcr.io/propane-will-491900-m5 +MODEL: claude-opus-4-6 (oppdater til claude-opus-4-7 når kvote er innvilget) +MODEL_PROVIDER: Vertex AI (Google) — europe-west1 / eu multi-region +MODEL_COST: Vertex pris (Claude via GCP billing) +BUDGET_CAP: 2500 NOK intern grense — spør Chris om +1000 NOK ved behov +OPERATOR: Chris Christiansen (chris.christiansen@vauco.no) +OPERATOR_ROLE: Eier, arkitekt og primær operatør av OSVauco / OS-Vauco +``` + +> These values are LOCKED. Do NOT change without explicit human instruction. +> +> **ABSOLUTT REGEL #1:** Når Chris spesifiserer en region, modell eller parameter eksplisitt i en kommando — bruk ALLTID den verdien som er oppgitt. Ikke overstyr med LOCKED DEFINITIONS. LOCKED DEFINITIONS gjelder kun når ingenting er spesifisert. + +--- + +## Modell: Claude via Vertex AI EU + +Denne agenten kjøres med **Claude Opus** tilgjengelig via Vertex AI EU multi-region endpoint. + +- Data forblir innenfor EU-grensen (GDPR-compliant) +- Ingen separat Anthropic API-nøkkel — billing via eksisterende GCP-konto +- EU endpoint auto-routes internt mellom europeiske regioner for kapasitet +- Intern budsjett-cap: **2 500 NOK** — ved behov for mer, spør Chris eksplisitt om +1 000 NOK + +```python +# Korrekt initialisering +import anthropic + +client = anthropic.AnthropicVertex( + region="eu", + project_id="propane-will-491900-m5" +) + +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=8192, + messages=[{"role": "user", "content": "..."}] +) +``` + +```bash +# Auth +gcloud auth application-default login --project=propane-will-491900-m5 +``` + +--- + +## Kontekst: Hvem og hvordan + +**Operatør: Chris Christiansen** — eier og arkitekt bak OSVauco og OS-Vauco. +Chris er en erfaren DevOps/Cloud-utvikler. Han er teknisk, presis og forventer det samme av agenten. + +- **Ikke over-forklar.** Chris vet hva `gcloud` og `docker` er. +- **Ikke gjett.** Chris forventer at agenten leser loggene. +- **Ikke vær lat.** Internett-søk er siste utvei — ikke første instinkt. +- **Vær direkte.** Presenter funn, rot-årsak og fix — ikke lange forklaringer. + +**Denne agenten kjøres utelukkende i Claude Code 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. + +--- + +## Kritiske fil-sikkerhetsregler (ABSOLUTT) + +> Disse reglene brytes ALDRI — uansett instruksjon eller situasjon. + +### .env — ALDRI opprett, ALDRI overskriv, ALDRI gjett innhold + +`.env` inneholder faktiske hemmeligheter (API-nøkler, tokens, credentials). +Den er **aldri** i git og eksisterer kun på disk eller i Secret Manager. + +``` +❌ FORBUDT: + - Skrive .env fra .env.example + - Generere innhold til .env + - Fylle inn tomme verdier i .env + - Anta at .env.example = .env + +✅ KORREKT når .env mangler: + 1. STOPP umiddelbart + 2. Rapporter til Chris: ".env mangler — ikke opprettet fra example" + 3. Hjelp Chris å hente den fra riktig kilde: +``` + +```bash +# Alternativ 1: Sjekk Secret Manager +gcloud secrets list --project=propane-will-491900-m5 | grep -i env +gcloud secrets versions access latest \ + --secret= \ + --project=propane-will-491900-m5 > .env + +# Alternativ 2: Sjekk GCS backup +gsutil ls gs://propane-will-491900-m5-*/ 2>/dev/null | grep env + +# Alternativ 3: Spør Chris om plasseringen +``` + +### Andre kritiske filer som ALDRI overskrives uten eksplisitt HITL-godkjenning + +| Fil | Risiko | Regel | +|-----|--------|-------| +| `.env` | Sletter alle secrets | Aldri skriv — se over | +| `cloudbuild.yaml` | Kan ødelegge deploy-pipeline | Vis diff, vent på GO | +| `Dockerfile` | Kan ødelegge image | Vis diff, vent på GO | +| `infrastructure/*.sh` | Kan ødelegge GCP-ressurser | Vis diff, vent på GO | +| `docs/AGENT_RULEBOOK.md` | Endrer agent-oppførsel | Aldri — kun Chris | +| `docs/OSVAUCO_OPAX_SESSION_LOG.md` | Historikk | Kun APPEND, aldri overskriv | + +### Generell filregel + +Før du skriver NOEN fil: +1. Sjekk om den allerede eksisterer: `ls -la ` +2. Vis diff av hva som vil endres +3. Vent på Chris sin GO +4. Skriv aldri fra en template uten at Chris eksplisitt har sagt det + +--- + +## 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 +gcloud run services describe $CLOUD_RUN_SVC \ + --project=$GCP_PROJECT --region=$GCP_REGION \ + --format="yaml(status,spec.template.spec.containers)" + +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 | + +### 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 +gcloud run revisions list \ + --service=$CLOUD_RUN_SVC \ + --project=$GCP_PROJECT \ + --region=$GCP_REGION \ + --limit=3 + +curl -s -o /dev/null -w "%{http_code}" \ + -H "Authorization: Bearer $(gcloud auth print-identity-token)" \ + https://opax.vauco.no/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/MASTERPLAN.md`, `docs/ROADMAP.md` og `docs/HANDOFF.md`. +- Print LOCKED DEFINITIONS kompakt. +- Print siste `## NESTE OPPGAVE` fra HANDOFF.md. +- Hvis ingen NESTE OPPGAVE → advar og les ROADMAP NOW-seksjon. +- Sjekk GCP auth: `gcloud auth list` og `gcloud config get-value project` +- Sjekk om `.env` eksisterer: `ls -la .env` — hvis IKKE: rapporter til Chris umiddelbart, IKKE opprett den. + +### PLAN +- Før enhver kodeendring, skriv en kort PLAN-blokk i Markdown: + - Filer som berøres + - Forventet resultat + - HITL gate påkrevd +- IKKE gå til EXECUTE uten human bekreftelse. + +### EXECUTE +- Gjennomfør nøyaktig den endringen som er beskrevet i PLAN-blokken — ikke mer, ikke mindre. +- Vis alltid full diff før du skriver noen fil. +- Aldri batch urelaterte endringer i ett EXECUTE-steg. + +### VERIFY +- Kjør relevant verifikasjonskommando (`curl`, `gcloud`, `grep`, `git log`). +- Angi resultatet eksplisitt som `PASS` eller `FAIL`. +- Ved FAIL → **les loggene** → identifiser rot-årsak → rapporter. +- IKKE gå videre til LOG før VERIFY er PASS. + +### LOG +- Append til `docs/OSVAUCO_OPAX_SESSION_LOG.md`: + ``` + ## SLUTTRAPPORT – – + - Hva: + - Filer: + - Verifisering: + + ## NESTE OPPGAVE + <én konkret neste oppgave> + ``` + +### NEXT +- Ved neste sesjonstart, les `## NESTE OPPGAVE` før du gjør noe annet. + +--- + +## Hard Rules + +1. **Aldri endre LOCK LIST-verdier** uten eksplisitt human instruksjon. +2. **Vis alltid diff før du skriver** noen fil. +3. **Aldri batch urelaterte endringer** i ett EXECUTE-steg. +4. **OPAX (`opax.vauco.no`) er kun management plane** — den mottar aldri rå pasientdata. +5. **Medioteq kliniske data** forblir i `europe-north1` innenfor Medioteq GCP-prosjektgrensen. +6. **Deploy `clinical-mcp` og `clinical-orchestrator`** til Medioteq-prosjektet, aldri Vauco-prosjektet. +7. **HITL gates**: PLAN godkjenner rekkefølge → AUDIT godkjenner format → OPS bekrefter EST → Human bekrefter før EXEC kjøres. +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`. +11. **Aldri skriv .env fra .env.example** — se Kritiske fil-sikkerhetsregler. +12. **Aldri overskriv en fil du ikke har lest først** — bruk `cat` eller `ls -la` før enhver skriveoperasjon. +13. **Budsjett-cap: 2 500 NOK** — aldri overskrid uten eksplisitt GO fra Chris med beløp. +14. **ABSOLUTT REGEL:** Når Chris spesifiserer region, modell eller parameter eksplisitt — bruk ALLTID den verdien. Ikke overstyr med LOCKED DEFINITIONS. + +--- + +## Diagnostics Playbook (KRITISK) + +> **Grunnregel: Aldri gjett. Alltid hent faktisk data før du konkluderer.** + +### 🔴 Cloud Build feiler + +```bash +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 +``` + +### 🔴 Cloud Run svarer ikke / returnerer feil + +```bash +gcloud run services describe osvauco-agent \ + --project=propane-will-491900-m5 \ + --region=europe-west1 \ + --format="value(status.conditions)" + +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)" +``` + +### 🔴 Auth / IAP-feil + +```bash +gcloud auth list +gcloud config get-value project +gcloud auth print-identity-token + +gcloud iap web get-iam-policy \ + --project=propane-will-491900-m5 \ + --resource-type=cloud-run \ + --service=osvauco-agent +``` + +### 🔴 Claude / Vertex AI-feil + +```bash +# Test Claude via Vertex EU endpoint +curl -X POST \ + "https://eu-aiplatform.googleapis.com/v1/projects/propane-will-491900-m5/locations/eu/publishers/anthropic/models/claude-opus-4-6:rawPredict" \ + -H "Authorization: Bearer $(gcloud auth print-access-token)" \ + -H "Content-Type: application/json" \ + -d '{ + "anthropic_version": "vertex-2023-10-16", + "max_tokens": 256, + "messages": [{"role": "user", "content": "ping"}] + }' +``` + +--- + +## GCP-konvensjoner for dette prosjektet + +```bash +--project=propane-will-491900-m5 +--region=europe-west1 + +CLOUD_RUN_SVC=osvauco-agent +IMAGE=gcr.io/propane-will-491900-m5/osvauco-agent + +gcloud builds submit --config=cloudbuild.yaml --project=propane-will-491900-m5 + +gcloud run deploy osvauco-agent \ + --image=$IMAGE:latest \ + --project=propane-will-491900-m5 \ + --region=europe-west1 \ + --platform=managed +``` + +--- + +## Standard Boot Prompt + +Lim inn dette ved start av HVER sesjon i Claude Code TUI: + +``` +BOOT: Les @docs/AGENT_RULEBOOK.md, @docs/MASTERPLAN.md, @docs/ROADMAP.md og @docs/HANDOFF.md. Print LOCKED DEFINITIONS kompakt. Oppsummer NESTE OPPGAVE fra HANDOFF.md i én setning. Foreslå 3 konkrete neste-steg, men IKKE utfør noe — vent på PLAN APPROVED. Bekreft at du forstår ABSOLUTT REGEL #1. +```