OSVauco/docs/HANDOFF-LOCAL-LLM-GITEA-MCP.md

HANDOFF-LOKAL-LLM-GITEA-MCP.md

EGEN HANDOFF – UFRAVIKELIG STYRINGSDOKUMENT

GJELDER FRA NÅ OG FREM TIL 100 % FERDIGSTILLELSE

0. STATUS OG KOMMANDO

Denne handoffen skal opprettes som et eget, separat handoff-dokument. Den skal ikke blandes inn i generelle handoff-notater, gamle migreringsblokker eller løse TODO-lister. Fra dette tidspunktet er dette dokumentet den eneste autoritative arbeidsplanen for sporet “lokal LLM-fabrikk + OPAX-MCP + Gitea stabilisering + blueprinting til Gitea-VM”. [cite:900][cite:914]

Denne handoffen skal følges slavisk frem til alt er 100 % verifisert. Den skal ikke omgås fordi noe “nesten virker”, fordi det “sikkert bare er en env var”, eller fordi noen vil hoppe rett til deploy, write-funksjoner eller blueprinting. Alt arbeid på dette sporet skal måles mot dette dokumentet og ingenting anses som ferdig før exit-kriteriene her er oppfylt. [cite:913][cite:916]

1. STRATEGISK MÅL

Målet er å etablere en komplett, stabil og replikerbar lokal driftsmodell på dev-snap/GPU-VM som kan fungere som en blueprint for en senere overføring til Gitea-VM. Dev-snap/GPU-VM brukes nå som en verifikasjons- og byggeflate for å få fart i arbeidet.

Den endelige målplattformen, Gitea-VM, er en CPU-VM med 16 GB RAM og 50 GB disk. Modellvalgene må derfor være optimalisert for CPU, RAM og disk. gemma3:27b og andre tunge modeller er uaktuelle for Gitea-VM. Målet er å låse et mindre, replikerbart modelloppsett.

En lettvekts tre-lags arkitektur (Gemma/Qwen/Gemma eller lignende) skal vurderes, med qwen2.5:3b som et sannsynlig mellomledd. Dette er den sannsynlige målarkitekturen som skal bekreftes videre gjennom dokumentasjon og kodebevis.

2. FASTE SANNHETER

Følgende punkter er låst og skal ikke debatteres under gjennomføring:

• Gitea er source of truth. GitHub er kun mirror/backup og skal ikke være aktiv automasjonsbane. [cite:911]
• Lokale modeller er hovedretning. API-basert agentvei er avleggs som primærbane i dette sporet. Kun nødvendige Google API-er beholdes. [cite:914]
• Dev-snap/GPU-VM er nåværende verifikasjonsflate. Gitea-VM er planlagt permanent målmaskin. [cite:900][cite:912]
• Denne handoffen overstyrer løs ad hoc-jobbing, muntlige antakelser og midlertidige “snarveier”. [cite:916]

3. AKTUELL REALITET

Dagens verifiserte bilde er ikke “alt fungerer”. Dagens verifiserte bilde er at store deler av GCP- og Workspace-sporet fungerer, men at lokalmodell- og Gitea-sporet fortsatt ikke er ferdig. Testoppsummeringen viser at getconnectorstatus, gethealth, getbuildstatus, getstate, listcustomers, listgceinstances, listbuilds og listworkspaceusers er OK, mens listemmamodels feiler og Gitea-verktøy feiler. [file:899]

Detaljtestene viser også at getconnectorstatus rapporterte opaxmcpstatus: live, giteastatus: offline og toolcount: 37, noe som bekrefter at MCP-serveren er oppe, men at Gitea-integrasjonen ikke er frisk. list_commits og get_file feiler med Illegal header value b'token ', mens get_file_content og list_repo_files feiler med GITEA_URL environment variable is not set. [file:898][file:894]

4. HOVEDREGEL

Ingen skal omtale dette systemet som “klart”, “stabilt”, “blueprintbart” eller “ferdig” før alle blokkerende feil i dette dokumentet er lukket med testbevis. Subjektiv følelse, vellykket enkeltrun eller tidligere suksessfull deploy er ikke tilstrekkelig. [file:899][file:898]

Ingen fase får passere på grunnlag av håp. Kun målbare resultater teller. “Vi vet sikkert hva problemet er” teller ikke. “Det virker for meg” teller ikke. “Det deployet uten error” teller ikke. Kun eksplisitt verifisert grønn status teller. [cite:916]

5. FORBUDTE AVSPORINGER

Følgende er forbudt frem til denne handoffen er fullført:

• Ingen blueprinting til Gitea-VM før dev-snap/GPU-VM er 100 % verifisert.
• Ingen write-capabilities i Gitea får prioritet før read-only-capabilities er helt grønne. [cite:910]
• Ingen ny featureutvikling i MCP mens kritiske read-only feil fortsatt står åpne.
• Ingen GitHub-først arbeidsflyt.
• Ingen fallback tilbake til gammel agent-/API-bane som hovedløsning.
• Ingen skjult eller udokumentert env-var-, secret- eller path-magi.
• Ingen “rydder senere”-holdning på modellnavn, URL-er, tokens eller handler-paths. [cite:911][cite:914][file:894]

6. FASE 0 – LÅS SITUASJONEN

Formål: Stoppe arkitekturglidning og definere ett operativt sannhetsgrunnlag.

Skal gjøres:

• Bekreft skriftlig at denne handoffen er opprettet som eget dokument.
• Bekreft skriftlig at dette dokumentet er styrende frem til fullført.
• Bekreft at dev-snap/GPU-VM er aktiv verifikasjonsbase.
• Bekreft at Gitea-VM er planlagt permanent målmaskin.
• Bekreft at lokal LLM-bane er primær retning.
• Bekreft at Gitea er eneste source of truth. [cite:900][cite:912][cite:914]

Exit-kriterium:

• Ingen motstridende handoff, faseplan eller “midlertidig hovedplan” står aktivt side om side.

7. FASE 1 – LOKALE MODELLER SKAL LEVE

Phase 1 Investigation & Clarification Report

Blueprint & Target Architecture:

• Verification Platform: The dev-snap/GPU-VM is the current platform for verification and blueprinting. This is to accelerate development.
• Target Platform: The blueprint created on the GPU-VM will be optimized for the Gitea-VM, which is a CPU-only machine with 16GB RAM and a 50GB disk.
• Model Strategy: The goal is to define a lightweight, replicable, three-tiered model architecture. gemma3:27b is considered a historical or temporary setting, not the target for the Gitea-VM. A likely architecture is a Gemma/Qwen/Gemma stack, with qwen2.5:3b as the middle layer. This is the likely target architecture that needs to be confirmed.

Architectural Evidence:

• Heavy GPU Architecture Evidence:
  • opax-mcp/server.py: EMMA_MODEL is set to gemma3:27b.
  • docs/MASTERPLAN.md and docs/AGENT_RULEBOOK.md: Mention a gemma-4-12b-it model on a GPU-VM.
• Lightweight CPU Architecture Evidence:
  • User's explicit instructions.
  • opax-mcp/server.py: Presence of EMMA_FAST_MODEL (gemma3:4b) and EMMA_LIGHT_MODEL (qwen2.5:3b).
  • emma/emma_run.py: Default model is llama3.2.

Files to be Changed Later:

• opax-mcp/server.py: The EMMA_MODEL, EMMA_FAST_MODEL, and EMMA_LIGHT_MODEL environment variables will need to be updated.
• cloudbuild.mcp.yaml: The OLLAMA_BASE_URL will likely need to be updated.
• docs/MASTERPLAN.md: The AI model strategy will need to be updated.
• docs/AGENT_RULEBOOK.md: The model hierarchy will need to be updated.
• emma/emma_run.py: The default model may need to be changed.

What is Still Unclear:

• The exact models for the three-tiered architecture (front, middle, back) are not yet confirmed.
• The specific roles of EMMA_FAST_MODEL and EMMA_LIGHT_MODEL are not explicitly defined.
• The mapping between the OSV/OSVrelay/Emma concept and the EMMA_ environment variables is not documented.

Formål: Bevise at de 2–3 lokale modellene som er planlagt faktisk lever, kan listes, kan nås og kan brukes lokalt.

Bakgrunn: Koden viser at OPAX-MCP allerede er skrudd mot en lokal Ollama-lignende backend via OLLAMABASEURL, og listemmamodels er definert i verktøyregisteret. Likevel feiler listemmamodels i dagens tester, og det er derfor et blokkerende hull i hovedretningen. [file:894][file:899]

Skal gjøres:

• Identifiser eksakt hvilke 2–3 lokale modeller som inngår i målarkitekturen.
• Dokumenter modellnavn nøyaktig, uten kallenavn eller gjetting.
• Dokumenter hvilken runtime som brukes.
• Dokumenter base URL / host for modellmotoren.
• Bekreft at runtime faktisk kjører.
• Bekreft at modellene kan listes.
• Bekreft at minst én enkel prompt mot lokal modell lykkes. [cite:913][cite:914][file:894]

Blokkerende feil:

• listemmamodels FAIL = fasen er ikke ferdig. [file:899]
• Manglende eller feil OLLAMABASEURL = fasen er ikke ferdig. [file:894]
• Modell finnes, men svarer ikke = fasen er ikke ferdig.
• Uklart hvilken modell som er “Emma”, “Emma Fast” eller “Qwen” = fasen er ikke ferdig. [file:894]

Exit-kriterium:

• Lokalmodellene er synlige, svarer lokalt og er dokumentert som produksjonsnær baseline. [cite:913]

8. FASE 2 – MCP MÅ PEKE KORREKT TIL LOKAL MODELLSTI

Formål: Bevise at OPAX-MCP ikke bare har modeller tilgjengelig, men faktisk bruker dem riktig.

Bakgrunn: Koden viser at runemma, runemmafast og runqwen går via ollamachat, og at listemmamodels går via OLLAMABASEURL/api/tags. Dette betyr at den lokale modellveien allerede finnes i kodebasen, men ikke er verifisert som fullstendig operativ. [file:894]

Skal gjøres:

• Verifiser OLLAMABASEURL.
• Verifiser EMMAMODEL.
• Verifiser EMMAFASTMODEL.
• Verifiser EMMALIGHTMODEL.
• Bekreft at hver tool peker til riktig modell.
• Bekreft at responsene faktisk kommer lokalt.
• Bekreft at hovedløpet ikke skjult faller tilbake til gammel agent-/API-vei. [file:894][cite:914]

Forbud:

• Ingen aksept for “det går sikkert via lokal modell”.
• Ingen aksept for udokumenterte alias som bare finnes i én shell-session.
• Ingen aksept for modellnavn som må “huskes”.

Exit-kriterium:

• Det er entydig bevist hvilken modell hver tool bruker, og at kallene går lokalt. [file:894]

9. FASE 3 – GITEA READ-ONLY SKAL TILBAKE I TJENESTE

Formål: Gjenopprette full read-only funksjon mot Gitea før noe write-relatert arbeid vurderes.

Bakgrunn: Read-only Gitea er en forutsetning for å kunne stole på Gitea som source of truth i verktøykjeden. Testene viser at dette ikke er sant ennå. list_commits og get_file feiler med Illegal header value b'token ', mens get_file_content og list_repo_files feiler med GITEA_URL environment variable is not set. [file:899][file:894]

Koden viser samtidig at gammel Gitea-sti bruker GITEAURL og GITEATOKEN, mens ny handlerbasert sti for get_file_content og list_repo_files delegerer til giteahandler, noe som svært sannsynlig betyr at dere har to forskjellige konfigurasjonsforventninger i spill. [file:894]

Skal gjøres:

• Fastslå én autoritativ URL-variabel for Gitea.
• Fastslå én autoritativ token-variabel for Gitea.
• Kartlegg forskjellen mellom GITEAURL og GITEA_URL.
• Kartlegg hvorfor token-header bygges som token uten verdi.
• Rydd opp i env vars, secrets og handlerforventninger.
• Få alle read-only Gitea-tools til å gi ekte data, ikke bare slutte å kaste feil. [file:894][file:899]

Må være grønne:

• list_commits
• get_file
• get_file_content
• list_repo_files [file:899]

Forbud:

• Ingen write-testing før disse er grønne. [cite:910]
• Ingen “midlertidig hardkoding” som ikke dokumenteres og kan flyttes til Gitea-VM senere.
• Ingen aksept for at bare én av dem virker. Hele read-only-sporet skal være grønt.

Exit-kriterium:

• Alle fire read-only Gitea-tools returnerer gyldige svar og bruker konsistent konfigurasjon. [cite:910][file:899]

10. FASE 4 – HEL KJEDE MÅ VÆRE SAMTIDIG GRØNN

Formål: Sikre at lokale modeller, MCP, Gitea og øvrige read-only støttetjenester virker samtidig etter alle rettelser.

Bakgrunn: Det er ikke nok at komponenter virker hver for seg på forskjellige tidspunkter. Systemet skal kunne stå samlet uten regressjon. Dagens tester viser at GCP- og Workspace-sporet i stor grad er grønt, så poenget her er å bevise at modell- og Gitea-rettelser ikke ødelegger det som allerede fungerer. [file:899]

Minste samlede smoke test:

• getconnectorstatus
• gethealth
• getbuildstatus
• describe_service
• getworkspaceuser
• listworkspaceusers
• listemmamodels
• listcommits
• getfilecontent
• listrepofiles [file:899][file:898]

Krav:

• Alle skal testes i samme kontrollrunde.
• Resultatene skal lagres og dokumenteres.
• Ny FAIL i tidligere grønn funksjon regnes som regresjon og blokkerer videre fremdrift.

Exit-kriterium:

• Hele kjeden er grønn i samme runde. [file:899]

11. FASE 5 – FRYS BLUEPRINT PÅ DEV-SNAP

Formål: Gjøre det fungerende dev-snap-oppsettet om til en presis og flyttbar mal for Gitea-VM.

Dette er ikke migrering ennå. Dette er frysing av sannhet.

Skal dokumenteres fullstendig:

• alle env vars,
• alle secrets,
• alle modellnavn,
• alle base URLs,
• alle nødvendige filer og paths,
• alle services,
• alle testkommandoer,
• hvilke deler som må være identiske på Gitea-VM,
• hvilke deler som kan være maskinspesifikke. [file:894][cite:905][cite:912]

Forbud:

• Ingen “vi kopierer bare disken og håper”.
• Ingen blueprinting basert på muntlig hukommelse.
• Ingen migrering før dette er skrevet ned ferdig.

Exit-kriterium:

• Oppsettet er så godt dokumentert at en ren replisering til Gitea-VM kan utføres uten ny arkitekturdebatt eller gjettearbeid. [cite:905][cite:912]

12. DEFINITION OF DONE

Dette sporet er først ferdig når samtlige punkter under er sanne samtidig:

• lokale modeller lever og kan brukes lokalt,
• OPAX-MCP bruker lokal modellbackend korrekt,
• listemmamodels er grønn,
• Gitea read-only tools er grønne,
• GCP/Workspace-kjernen er fortsatt grønn,
• konfigurasjon er konsolidert,
• ingen skjult API-/agentavhengighet står igjen som hovedbane,
• dev-snap-oppsettet er dokumentert godt nok til å blueprintes til Gitea-VM. [cite:914][file:899][file:894]

Før dette er oppnådd, er prosjektet ikke ferdig. Ikke nesten ferdig. Ikke deploy-ferdig. Ikke migreringsklart. Ikke blueprint-klar.

13. DAGENS BLOKKERENDE FEIL

Per nå skal følgende behandles som åpne blokkerende forhold:

• listemmamodels FAIL. [file:899]
• Gitea read-only FAIL. [file:899]
• Illegal header value b'token ' på gammel Gitea-sti. [file:894][file:899]
• GITEA_URL environment variable is not set på ny handlersti. [file:894][file:899]
• getconnectorstatus viser Gitea offline. [file:898]

Ingen har lov å late som disse er sideproblemer. Dette er hovedproblemet.

14. OPERATIV PRIORITET REKKEFØLGE

Prioritet 1: Få lokalmodell-banen frisk og dokumentert. [cite:913][file:899]

Prioritet 2: Få Gitea read-only helt grønn med konsistent konfig. [file:894][file:899]

Prioritet 3: Kjør full smoke test og bevis at alt virker samtidig. [file:899]

Prioritet 4: Frys blueprint på dev-snap. [cite:905]

Prioritet 5: Først deretter planlegg og utfør flytting til Gitea-VM. [cite:912]

15. ENDRINGSREGLER

Enhver endring under dette sporet skal oppdateres tilbake i denne handoffen samme dag. Hver rettelse skal logges med:

• hva som var feil,
• hva som ble endret,
• hvordan det ble verifisert,
• om det finnes risiko for regresjon,
• hvilken fase som nå er påvirket.

Ingen “usynlige” endringer er akseptable.

16. SLUTTORDRE

Denne handoffen er opprettet nettopp for å stoppe glidning, halve sannheter og premature hopp til neste steg. Den skal derfor følges konsekvent helt til systemet er 100 % verifisert og klart for blueprinting til Gitea-VM. Enhver aktivitet som ikke bringer systemet nærmere grønne porter i dette dokumentet er støy og skal nedprioriteres. [cite:916][cite:918]