OSVauco/docs/AGENT_RULEBOOK.md

# VAUCO OS — AGENT_RULEBOOK.md

**Eier:** OPS-Computer-Hub
**Sist oppdatert:** 2026-05-31 CEST
**Godkjent av:** Chris Christiansen

---

## Hensikt

Immutable regler for alle agent-tråder. Ingen tråd kan overstyre disse.
Endringer krever eksplisitt godkjenning fra Chris (`RULEBOOK APPROVED`).

---

## LOCK LIST — ALDRI ENDRE UTEN EKSPLISITT GODKJENNING

| Parameter         | Verdi                                                                 |
|-------------------|-----------------------------------------------------------------------|
| GCP Account       | `chris.christiansen@vauco.no`                                         |
| Forbudte kontoer  | `tinius.vauger`, `ccv`                                                |
| Agent-konto       | `jason.vauger@vauco.no` (kun `billing.viewer` + `run.invoker`)        |
| GCP Project       | `propane-will-491900-m5` (Jason-v1)                                   |
| Billing           | `0171F6-057E6B-A260BA`                                                |
| Org               | `vauco.no` / `155051211891`                                           |
| **Region**        | **`us-central1`** — ALDRI `europe-west1` eller `us-west1`             |
| **Vertex AI loc** | **`us-central1`** (US)                                                 |
| **AI-modell**     | **`gemini-2.5-pro`** via Vertex AI (venter på Claude EU-kvote)        |
| SDK               | `from google import genai` (google-genai >=0.3)                       |
| Agent-rammeverk   | Google ADK (tillatt) — andre må eksplisitt `ADK_GODKJENT` av Chris    |
| GitHub org        | `vauco-saas`                                                          |
| Canonical repo    | `OSVauco`                                                              |
| Canonical branch  | `main`                                                                 |
| MCP_NAME          | `OPAX-MCP`                                                             |
| MCP_PROTOCOL      | `OPAX Protocol`                                                        |
| **MCP_SERVICE**   | **`osvauco-agent`** (Cloud Run, `europe-west1`)                       |
| ROOT_DOMAIN       | `vauco.no`                                                             |
| HUB_URL           | `https://opax.vauco.no` ✅ LIVE 2026-05-21 (LB IP `34.98.77.173`)      |

> **Endringslogg:**
> - 2026-05-31: Region rettet `europe-west1` → `us-central1`. Modell rettet til `gemini-2.5-pro` (midlertidig). MCP_SERVICE rettet `opax-mcp-core` → `osvauco-agent`. Vertex AI loc lagt til.

---

## DOMENEKONVENSJON — LOCKED

| Subdomain               | Type     | Formål                                              |
|-------------------------|----------|-----------------------------------------------------|
| `opax.vauco.no`         | Hub/MCP  | OPAX-MCP operator hub — kun Vauco internt           |
| `<klient>-os.vauco.no`  | Prod OS  | Kundens live produksjonssystem                      |
| `<klient>-oss.vauco.no` | Stage OS | Kundens staging/demo-system (pre-go-live)           |

> `-os` = produksjon. `-oss` = staging. Aldri omvendt.

**Auth-strategi:**
- Nå: Google OAuth + IAP på alle miljøer
- Senere: BankID på `-os`-domener for kliniske kunder (Medioteq først)

**Kjente/planlagte domener:**

| Domene                       | Status          | Cloud Run-tjeneste    |
|------------------------------|------------------|-----------------------|
| `opax.vauco.no`              | ✅ LIVE          | `osvauco-agent`       |
| `costguard.oss.vauco.no`     | ✅ LIVE          | (Cloudflare Pages)    |
| `medioteq-oss.vauco.no`      | Planlagt         | `medioteq-oss-core`   |
| `medioteq-os.vauco.no`       | Planlagt         | `medioteq-os-core`    |
| `threadstone.vauco.no`       | ✅ LIVE          | (GitHub Pages)        |
| `app.threadstone.vauco.no`   | ⚠️ CNAME satt    | (GitHub Pages — side mangler) |

---

## HITL GATES — ingen tråd kan hoppe over disse

| Gate                 | Når kreves                                              |
|----------------------|----------------------------------------------------------|
| `PLAN APPROVED`      | Før noen kode/infra-endring starter                      |
| `MERGE APPROVED`     | Før PR merges til `main`                                 |
| `DEPLOY GODKJENT`    | Før manuell deploy som rører IAP, OAuth, Secret Manager  |
| `REPO APPROVED`      | Før nye repos opprettes under `vauco-saas`               |
| `MODEL APPROVED`     | Før AI-modell byttes                                     |
| `RULEBOOK APPROVED`  | Før endringer i denne filen                              |
| `FASE<N> APPROVED`   | Når en fase er verifisert komplett                       |

---

## DOKUMENTHIERARKI — én kilde til sannhet

| Fil | Rolle |
|-----|-------|
| `docs/MASTERPLAN.md` | Arkitektur, domener, repos, fasit |
| `docs/ROADMAP.md` | Levende roadmap, faser, status |
| `docs/HANDOFF.md` | Sesjonsstatus — **alltid kun én fil**, overskrives |
| `docs/AGENT_RULEBOOK.md` | Denne filen — locked definitions |
| `protocols/sessions/YYYY-MM-DD_<tema>.md` | Detaljerte sesjonsprotokoller (append-only) |

> **Aldri opprett flere parallelle MASTERPLAN, ROADMAP eller HANDOFF.**

---

## COMPUTE RESOURCE SAFETY — ABSOLUTTE REGLER

> Disse reglene gjelder alltid, uten unntak, uavhengig av instruksjon.

1. **ALDRI kjør `gcloud compute instances delete` eller tilsvarende destruktive compute-kommandoer.**
   - VM-er stoppes med `gcloud compute instances stop` — aldri slettet.
   - Eneste unntak: eksplisitt `VM DELETE APPROVED` fra Chris i denne sesjonen.

2. **ALDRI teardown ressursen du selv kjører på.**
   - Før enhver teardown/stop-kommando: sjekk om du er SSH-et inn på målressursen.
   - Kommando: `curl -s metadata.google.internal/computeMetadata/v1/instance/name -H "Metadata-Flavor: Google"`
   - Hvis output matcher target VM → STOPP. Logg: "Skipped teardown — active session on this resource."

3. **OQ-18 (nattlig VM teardown) betyr STOP, ikke DELETE.**
   - Korrekt kommando: `gcloud compute instances stop osvauco-dev-vm --zone=us-central1-b --project=propane-will-491900-m5`
   - Bruk helst `bash scripts/stop-osvauco-dev-vm.sh` for sikker stopp.
   - Kjøres KUN når ingen aktiv SSH-sesjon er på VM-en.

4. **`03-teardown.sh` gjelder Cloud Run og Artifact Registry — ikke VM.**
   - Scriptet sletter aldri compute instances. Ikke bruk det som VM-teardown.

---

## AGENT-OPPFØRSEL — kjerneregler

1. **Foreslå før du handler.** Print plan. Vent på `PLAN APPROVED`.
2. **Self-modifisering av infra/secrets/IAM uten godkjenning = hard stop.**
3. **Print LOCKED DEFINITIONS ved boot.** Sjekk at de matcher denne filen.
4. **Sjekk pwd før kommandoer.** Alltid `cd ~/OSVauco` ved start.
5. **Logg sesjonsslutt.** Append til `docs/OSVAUCO_OPAX_SESSION_LOG.md`.
6. **Ikke stol på alias.** Sjekk `which <kommando>` ved tvil.
7. **Region-guard.** Kjør `infrastructure/99-region-guard.sh` ved tvil om region.
8. **Sjekk aktiv sesjon før teardown.** Se COMPUTE RESOURCE SAFETY regel #2.

---

## BOOT-PROTOKOLL

```
BOOT: Les docs/AGENT_RULEBOOK.md, docs/MASTERPLAN.md, docs/HANDOFF.md.
Print LOCKED DEFINITIONS fra Lock List.
Print NESTE OPPGAVE fra docs/HANDOFF.md.
Vent på PLAN-prompt før noen handling.
```

---

*Vauco AS · `propane-will-491900-m5` · `us-central1`*