From 231e08a4718593d01127d71495e1e5132d43ed9f Mon Sep 17 00:00:00 2001 From: chrischristiansen-glitch Date: Wed, 27 May 2026 23:27:05 +0200 Subject: [PATCH] chore(step1+step2): archive duplicates, rewrite MASTERPLAN with Anti-Chaos Protocol --- docs/MASTERPLAN.md | 178 +++++++++++++++++++++++ docs/archive/Cost_Management_Rules.md | 85 +++++++++++ docs/archive/GCPBestPractices.md | 11 ++ docs/archive/OSVAUCO_OPAX_SESSION_LOG.md | 2 + 4 files changed, 276 insertions(+) create mode 100644 docs/MASTERPLAN.md create mode 100644 docs/archive/Cost_Management_Rules.md create mode 100644 docs/archive/GCPBestPractices.md create mode 100644 docs/archive/OSVAUCO_OPAX_SESSION_LOG.md diff --git a/docs/MASTERPLAN.md b/docs/MASTERPLAN.md new file mode 100644 index 0000000..8dac9cf --- /dev/null +++ b/docs/MASTERPLAN.md @@ -0,0 +1,178 @@ +# MASTERPLAN — Vauco OS + +**Eier:** Chris Christiansen · Vauco AS · Org.nr 935 989 779 +**Sist oppdatert:** 2026-05-27 +**Status:** AUTORITATIV — én kilde til sannhet + +--- + +## 1. Plattformhierarki + +``` +Vauco OS (Plattform — visjon, økonomi, token-lag) + └── OPAX (Engine — AI-infrastruktur, Cloud Run, agentic arkitektur) + ├── CostGuard (Modul #1 — live på costguard.oss.vauco.no) + ├── Threadstone (Modul #2 — kreativ AI-assistanse, Q3 2026) + └── [Modul #3+] (TBD basert på CostGuard-læring) +``` + +### Vauco OS +Overordnet plattform og merkevare. Holder VVL (Vauco Value Ledger), token-økonomi ($VCO), og go-to-market-strategi. Ikke et brukervendt produkt — det er infrastrukturen rundt produktene. + +### OPAX +Den tekniske motoren. Cloud Run (`osvauco-agent`) på GCP. Alle produkt-moduler bygger på OPAX-API-et. OPAX er ikke synlig for sluttkunden — det er plumbing. + +### CostGuard (Modul #1) +Første go-to-market produkt. Hjelper bedrifter å forstå og kontrollere GCP-kostnader via AI-drevet analyse. Live på `costguard.oss.vauco.no` (Cloudflare Pages). Backend via Cloud Run. + +--- + +## 2. Infrastrukturstatus (per 2026-05-27) + +| Komponent | Status | URL / Detalj | +|---|---|---| +| Cloud Run (`osvauco-agent`) | ✅ Live | GCP us-central1 | +| `opax.vauco.no` | ✅ Live | CNAME → ghs.googlehosted.com | +| `costguard.oss.vauco.no` | ✅ Live | Cloudflare Pages, docs/ | +| BigQuery (`osvauco_logs`) | ⏳ Venter | Sink oppe, tabell populeres | +| OAuth2 (Google) | ✅ Konfigurert | Secret Manager | +| CI/CD (Cloud Build) | ✅ Live | Google Chat deploy-varsler | +| Budget guard (500 NOK/mnd) | ✅ Live | 50/90/100% terskler | +| IAP på Cloud Run | 🔜 Fase C | Krever LB — Terraform-modul | +| BQ billing export (`gcp_billing_export_v1_*`) | ⏳ Venter | Første tabell ikke populert ennå | + +--- + +## 3. Roadmap + +### ✅ Fullført + +- **Fase 0** — Baseline: `opax-mcp-core` live, OSVauco repo, `.gemini/` grunnmur, boot-script +- **Fase 1** — MCP_NAME/MCP_PROTOCOL/ROOT_DOMAIN locked; ARCHITECTURE.md opprettet · 2026-05-21 +- **Fase 2** — `opax.vauco.no` live: domain mapping + CNAME + SSL · 2026-05-21 +- **Fase 3** — Nemotron session loop i GEMINI.md; TODO.md; sesjonslogg · 2026-05-21 +- **Fase A (infra)** — Deploy, GitHub PAT, CI/CD, webhook, budget guard, GCS bucket, logging sink · 2026-05-24 +- **Fase B (stabilisering)** — Smoke-test 10/10 ✅, BigQuery dataset + sink, Threadstone model-temaer · 2026-05-26 +- **Repos konsolidert** — Alt samlet under `vauco-saas/OSVauco` · 2026-05-27 + +### 🔄 Aktiv nå + +- **CG3 — CostGuard Frontend Wiring** + - `docs/index.html` (Cloudflare Pages) og `static/billing-dashboard.html` + - OAuth login flow (`/auth/login?client_id=demo`) kobles til Cloud Run + - BigQuery-data vises når `gcp_billing_export_v1_*` er populert + - HITL gate: `CG3 APPROVED` + +### 🔜 Neste + +- **Fase C — IAP + Terraform** + - LB + IAP for `opax.vauco.no` (begrens til `@vauco.no`) + - Konverter `infrastructure/*.sh` → Terraform-modul i `vauco-bootstrap/` + +- **BQ-2 / BQ-3** — Verifiser sink-SA IAM → Looker Studio dashboard + +- **Threadstone Fase 1** — `vauco-saas/threadstone-instructions` repo, Master Hub v3.2 + +- **Dialogflow CX** — Norsk Playbook-agent, webhook mot Cloud Run + +### 📋 Backlog + +- `opax-mcp/` restruktureres som modul-subtree +- Full boot cycle acceptance test (automatisert) +- Multi-klient onboard-mønster +- **Medioteq** — kun idéfase, ingenting implementeres før OPAX er fullt operasjonelt +- **VVL Fase 2** — $VCO on-chain (Q3 2026), etter Threadstone Fase 1 er validert + +--- + +## 4. OPAX Anti-Chaos Protocol + +> **Status: Proprietær Vauco-arkitektur · Potensielt salgsbart B2B-produkt** + +### Problemet + +Bedrifter som bruker autonome AI-agenter (GitHub Copilot Workspace, Devin, LangChain-bygg) opplever "AI-ADHD": agenter mister kontekst, hopper over kritiske steg, sletter kode de ikke forstår, og fanges i feilsøkings-loops. Det koster dyrt å rydde opp. + +### Protokollen + +OPAX Anti-Chaos Protocol er en **deterministisk prompt-arkitektur** som tvinger LLM-er til å oppføre seg som lineære state-maskiner: + +``` +REGEL 1 — LINEÆR STATE MACHINE + Agenten opererer strengt trinn-for-trinn. + Trinn N+1 starter ikke før bruker skriver "Step N approved". + +REGEL 2 — INGEN CONTEXT-SWITCHING + Ved blokkering (f.eks. venter på ekstern data): HALT. + Ingen pivoting til andre oppgaver. + +REGEL 3 — CLI-FIRST EXECUTION + All standard utvikling: ready-to-run kommandoer eller kodeblokker. + Manuell filredigering kun for Auth/Security. + +REGEL 4 — PRIME DIRECTIVE + Slett ikke kjernekonsepter. + Syntetiser til ren, enhetlig arkitektur. + Arkiver det som erstattes — slett ingenting. + +REGEL 5 — AUTO-SNAPSHOT VED GH-OPERASJONER + Før enhver GitHub-handling: ta snapshot av tråden. + Lagre til: docs/archive/sessions/[YYYY-MM-DD]_[emne].md +``` + +### Kommersiell potensiell + +Protokollanenn pakkes og selges under OPAX-paraplyen i tre nivåer: + +| Nivå | Produkt | Modell | +|---|---|---| +| **1 — Playbook** | Strukturert bibliotek av system-prompts og arkitektur-regler | Engangslisens / årsabonnement | +| **2 — Middleware API** | OPAX wrapper-API: kundens oppgave inn → Anti-Chaos-pakket prompt ut → svar overvåket | Pay-per-call / SaaS | +| **3 — Enterprise Consulting** | Implementering av Vauco OS-prinsipper i kundens infrastruktur | Prosjektbasert | + +**Målgruppe:** CTO-er og engineering leads i selskaper med 10–500 utviklere som sliter med å få ROI på AI-investeringer. + +**Differensiering:** Vi selger ikke AI-modellen. Vi selger styringssystemet som gjør AI-en brukbar for enterprise. + +> 📁 Detaljert teknisk spec: `docs/architecture/ANTI_CHAOS_PROTOCOL.md` (opprettes i Fase C) + +--- + +## 5. Filstruktur — én kilde til sannhet + +``` +vauco-saas/OSVauco/ +├── docs/ +│ ├── MASTERPLAN.md ← denne filen — autoritativ +│ ├── HANDOFF_[dato].md ← siste sesjonshandoff +│ ├── ARCHITECTURE.md ← teknisk arkitektur +│ ├── AGENT_RULEBOOK.md ← agentregler +│ ├── VAUCO_OS_ROADMAP.md ← ⚠️ deprecated, erstattet av seksjon 3 her +│ ├── protocols/ +│ │ ├── BOOT.md ← boot-kommando +│ │ ├── EOF.md ← sesjonsavslutning +│ │ └── boot-protocol-MD-origin.md +│ ├── architecture/ +│ │ └── ANTI_CHAOS_PROTOCOL.md ← opprettes Fase C +│ └── archive/ ← alt arkivert, ingenting slettet +│ └── sessions/ ← sesjonslogger fra vauco-os +├── static/ +│ └── billing-dashboard.html ← CostGuard dashboard +└── src/ ← OPAX backend +``` + +--- + +## 6. Nøkkelkontakter & secrets + +- **GCP Project:** `propane-will-491900-m5` +- **Region:** `us-central1` +- **Cloud Run service:** `osvauco-agent` +- **Secret Manager:** Google OAuth2-credentials +- **Billing account:** se Secret Manager +- **Kontakt:** chris.christiansen@vauco.no + +--- + +*Vauco AS · Org.nr 935 989 779 · Oslo, Norge* +*Powered by OPAX · Crafted by Chris Vauger* diff --git a/docs/archive/Cost_Management_Rules.md b/docs/archive/Cost_Management_Rules.md new file mode 100644 index 0000000..3600091 --- /dev/null +++ b/docs/archive/Cost_Management_Rules.md @@ -0,0 +1,85 @@ +# Cost Management Rules [ARCHIVED] +> Arkivert 2026-05-27 — erstattet av docs/CostManagementRules.md + +# Cost Management Rules +**OSVauco-NMTMD-GCOS | GCP Agent Master Repo** + +## 1. Budget Alerts + +```bash +gcloud billing budgets create \ + --billing-account="${BILLING_ACCOUNT_ID}" \ + --display-name="Agent Platform Budget" \ + --budget-amount=500USD \ + --threshold-rule=percent=0.5,basis=CURRENT_SPEND \ + --threshold-rule=percent=0.8,basis=CURRENT_SPEND \ + --threshold-rule=percent=1.0,basis=CURRENT_SPEND +``` + +## 2. Resource Labeling + +All GCP resources MUST carry: + +| Label Key | Example | Purpose | +|-----------|---------|--------| +| env | prod/dev/staging | Environment | +| team | osvaucoe | Cost attribution | +| cost-center | ai-platform | Finance | +| agent | orchestrator/rag | Per-agent tracking | + +## 3. Cloud Run Cost Controls + +```bash +gcloud run deploy ${SERVICE} \ + --max-instances=10 \ + --concurrency=80 \ + --timeout=300 +``` + +- CPU throttling on for non-latency-critical agents +- min-instances=1 only for latency-sensitive services + +## 4. Vertex AI Cost Controls + +- Use gemini-2.0-flash for high-volume sub-agent calls +- Context caching for repeated prompts (up to 75% savings) +- max_output_tokens=2048 for most tasks +- Monitor: aiplatform.googleapis.com/prediction/online/token_count + +## 5. RAG Engine Cost Controls + +- Delete stale documents from corpus +- Batch embedding for initial ingestion +- top_k=5 (not higher) +- Archive cold corpora to Cloud Storage lower tier + +## 6. Memory Bank Cost Controls + +- TTL: 7 days for short-lived session memories +- Firestore-backed for most use cases +- Index only user_id and session_id + +## 7. Networking Cost Controls + +- Private Google Access to avoid Vertex AI egress charges +- VPC routing for all agent traffic +- Cloud NAT only where unavoidable + +## 8. Storage Lifecycle + +```json +{ + "rule": [{ + "action": { "type": "Delete" }, + "condition": { "age": 7 } + }] +} +``` +Apply with: `gcloud storage buckets update gs://BUCKET --lifecycle-file=lifecycle.json` + +## 9. End-of-Day Teardown Checklist + +- [ ] Run 03-teardown.sh +- [ ] Verify no active Agent Runtimes: `gcloud ai agent-engines list --region=us-central1` +- [ ] Verify no active Vertex AI endpoints: `gcloud ai endpoints list --region=us-central1` +- [ ] Check billing dashboard for anomalies diff --git a/docs/archive/GCPBestPractices.md b/docs/archive/GCPBestPractices.md new file mode 100644 index 0000000..a7762a2 --- /dev/null +++ b/docs/archive/GCPBestPractices.md @@ -0,0 +1,11 @@ +# GCP Best Practices [ARCHIVED] +> Arkivert 2026-05-27 — erstattet av docs/GCP_Best_Practices.md + +# GCP Best Practices — propane-will-491900-m5 + +## Platform context (2025–2026) +- **Vertex AI Agent Engine** has been rebranded as **Gemini Enterprise Agent Platform**. + Agent runtimes are fully managed serverless — no VM management required. +- **ADK (Agent Development Kit)** 2.0 is open-source, supports Python/TypeScript/Go/Java/Kotlin. + Agents run locally for dev, then deploy to Agent Runtime, Cloud Run, or GKE. +- Region: **us-central1** for all resources (low latency, widest feature availability). diff --git a/docs/archive/OSVAUCO_OPAX_SESSION_LOG.md b/docs/archive/OSVAUCO_OPAX_SESSION_LOG.md new file mode 100644 index 0000000..92408ec --- /dev/null +++ b/docs/archive/OSVAUCO_OPAX_SESSION_LOG.md @@ -0,0 +1,2 @@ +# OSVAUCO OPAX SESSION LOG [ARCHIVED] +> Arkivert 2026-05-27 — historisk sesjonslogg, erstattet av HANDOFF_20260526.md og fremtidige HANDOFF-filer.