Ground Truths: Forankring av AI-agenter i virkeligheten

Tallene i dette innlegget gjenspeiler systemet ved publisering (januar 2026). Se teamsiden for gjeldende tall.

AI-agenter er bemerkelsesverdig dyktige. De kan resonnere, syntetisere og generere. Men de har en grunnleggende svakhet: de finner på ting. Ikke ondsinnet, men med stor selvtillit. En agent kan finne opp API-parametere som ikke finnes, referere til konfigurasjoner som aldri ble definert, eller anvende mønstre fra treningsdataene sine som motsier din faktiske arkitektur.

Standardtiltaket er «gi agenten mer kontekst». Men kontekst kan være motstridende. Dokumentasjon driver bort fra implementasjonen. Kommentarer lyver. Selv kode kan villede når den leses uten å forstå intensjonen.

Vi trengte noe mer eksplisitt. Noe som ikke kunne ignoreres eller mistolkes. Noe som ville forankre agenter i verifiserbar virkelighet.

Vi kaller dem Ground Truths.

Hva er en Ground Truth?

En Ground Truth er en eksplisitt, versjonert faktapåstand som agenter må respektere. Det er ikke dokumentasjon. Det er ikke en kommentar. Det er en førsteklasses entitet i systemet med:

• En unik identifikator (som GT-MAG-015 eller GT-MAG-036)
• En livssyklusstatus (current, tentative, eller deprecated)
• Et omfang (plattformomfattende, pakkespesifikt, eller domenebundet)
• Bevis (filstier, URL-er, eller referanser som beviser påstanden)
• Agentveiledning (eksplisitte gjør/unngå-instruksjoner)

Her er et eksempel fra vår Maguyva kodeintelligens-plattform:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

Dette er ikke prosa. Det er en kontrakt. Når en agent støter på denne Ground Truth-en, vet den:

1. Standardverdien er deterministisk (tomme resultater, ikke uklare gjetninger)
2. Det finnes spesifikke parametere (find_similar, exact_match) med definert atferd
3. Bevis finnes i spesifikke filer som kan verifiseres
4. Påstanden ble verifisert på en bestemt dato

Anatomien til et Ground Truth-register

Ground truths lever i YAML-registre under ai_assets/reference/ground_truths.yaml. Hver pakke eller hvert domene kan ha sitt eget register. Strukturen er:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

Registeret inneholder metadata om selve samlingen, renderingskonfigurasjon for dokumentasjonsgenerering, og selve påstandene. Hver påstand følger et strengt skjema validert av Pydantic-modeller:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

Hvordan agenter får tilgang til Ground Truths

Ground truths eksponeres gjennom flere kanaler:

1. Rendret dokumentasjon

Kommandoen orkestra sync transformerer YAML-registre til lesbar markdown:

uv run orkestra sync

Dette genererer GROUND_TRUTHS.md-filer som inkluderes i agentkonteksten. Det rendrede resultatet grupperer påstander etter status og kategori:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. CLI-søk

Agenter med shell-tilgang kan søke i ground truths programmatisk:

uv run orkestra context ground-truths search "embedding"
uv run orkestra context ground-truths search --tag security
uv run orkestra context ground-truths list --status current

Søkefunksjonen scorer treff på tvers av flere felt med vektet relevans:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. Kontekstkomposisjon

Når agenter rendres fra YAML-definisjoner, kan konteksten deres referere til Ground Truth-registre:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

Dette sikrer at relevante ground truths lastes inn før agenten begynner arbeidet.

Kategorier av Ground Truths

Når vi ser på tvers av registrene våre, klynger ground truths seg i flere mønstre:

Produktprinsipper

Begrensninger på hva produktet er og ikke er:

«Maguyva er read-only med hensyn til brukerrepositorier; den eneste ressursen som ikke kan gjenoppbygges, er den betalte embeddings-cachen.» (GT-MAG-001)

Arkitekturgrenser

Hvor ansvar hører hjemme, og hvorfor:

«Grensene mellom pipeline og Maguyva er tilsiktede: pipeline er gjenbrukbar, Maguyva holder kodespesifikk logikk, og CQRS skiller stage-skriving fra server-lesing.» (GT-MAG-006)

Anti-hallusinasjonsregler

Eksplisitte påbud som holder verktøykontrakter deterministiske i stedet for utledet:

«Uklart symbolmatch (fuzzy matching) er opt-in via find_similar=true. Standardatferd returnerer tomme resultater for symboler som ikke finnes; exact_match=true håndhever streng matching og deaktiverer alle uklare fallbacker.» (GT-MAG-015)

Kvalitetsporter

Standarder som må opprettholdes:

«Endringer i delt infrastruktur (post_filters.py, relasjonsekstraktorer, delte håndterere) MÅ valideres mot ALLE støttede språk gjennom full manifestgenerering før commit. Enkeltspråksvalidering er ikke tilstrekkelig for delt kode.» (GT-MAG-036)

Kodemønstre

Implementasjonskrav:

«Bruk asyncio.to_thread() for CPU-tungt arbeid i asynkrone kontekster; det utfasede loop.run_in_executor()-mønsteret skal ikke brukes i ny kode.» (GT-MAG-018)

Livssyklusen til en Ground Truth

Ground truths er ikke statiske. De utvikler seg gjennom en definert livssyklus:

Tentative

En foreslått sannhet under vurdering. Påstanden er registrert, men kan endres:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Current

En verifisert sannhet som agenter må respektere. Bevisene er validert:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Deprecated

En sannhet som ikke lenger gjelder. Beholdt for historisk referanse med en henvisning til det som erstattet den:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

Hvorfor ikke bare dokumentasjon?

Dokumentasjon tjener et annet formål. Den forklarer. Den lærer bort. Den kan være vag, kan bruke kvalifikatorer som «generelt» eller «vanligvis».

Ground truths kan ikke være vage. De er påstander. De gjelder enten, eller så gjør de ikke det.

Se på forskjellen:

Dokumentasjon: «API-et returnerer generelt tomme resultater når et symbol ikke finnes, selv om uklar matching kan være aktivert i enkelte konfigurasjoner.»

Ground Truth: «Standardatferd returnerer tomme resultater for symboler som ikke finnes; exact_match=true håndhever streng matching og deaktiverer alle uklare fallbacker.»

Den første er nyttig for mennesker som lærer systemet. Den andre er handlingsrettet for agenter som skal ta beslutninger.

Agentveiledning: Gjør og unngå

Noen ground truths inkluderer eksplisitt agentveiledning:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

Dette fjerner tvetydighet. En agent som leser dette, vet ikke bare hva som er sant, men hvilke handlinger den sannheten innebærer.

Verifisering og vedlikehold

Ground truths krever vedlikehold. Vi sporer:

• last_verified: Når noen bekreftet at påstanden fortsatt gjelder
• evidence: Filer som beviser påstanden (kan sjekkes for eksistens)
• source: Hvor sannheten stammer fra (CLI-inspeksjon, arkitekturgjennomgang, læring etter hendelser)

En Ground Truth med utdaterte verifiseringsdatoer eller ødelagte bevislenker er et signal om å undersøke. Enten er sannheten fortsatt gyldig og trenger re-verifisering, eller virkeligheten har endret seg og sannheten trenger oppdatering.

Ekte eksempler fra produksjon

Sikkerhetsgrense

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

Denne Ground Truth-en forhindrer en klasse av feilslåtte «sikkerhetsforbedringer» som ville ødelagt produktet.

Nøyaktighet ved ekstraksjonstidspunktet

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

Dette kom fra en smertefull erfaring. Agenter pleide å lappe feilende språkpakker ved å legge til filtre som bare påvirket validatoren, som fikk testriggen til å se grønnere ut, mens den levende Maguyva-ekstraktoren fortsatt sendte ut de feil edgene. Regelen tvinger fikser tilbake til den reelle stien: YAML-konfigurasjon, spørringer, eller håndterere.

Filtrering i flere nivåer

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

Dette forhindrer agenter fra å legge til filtre på feil sted, en vanlig feil som forårsaket nøyaktighetsregresjoner.

Integrasjon med orkestreringssystemet

Ground truths er ett lag i et bredere kontekstsystem:

1. Arkitekturbeslutninger (ADR-er) - Registrerer hvorfor vi valgte tilnærming A fremfor B
2. Ground Truths - Sier hva som definitivt er sant akkurat nå
3. Domenemønstre - Beskriver hvordan man gjør ting riktig
4. Antimønstre - Beskriver hva man skal unngå, og hvorfor

En agent som jobber i systemet, har tilgang til alle fire. Ground truths gir det faktabaserte ankeret, mens beslutninger forklarer historien, mønstre veileder implementasjonen, og antimønstre advarer mot fallgruver.

Måling av effekt

Siden vi introduserte ground truths, har vi observert:

• Færre «fiks den hallusinerte fiksen»-sykluser
• Mer selvsikker agentbeslutningstaking når faktaene er klare
• Bedre PR-gjennomganger fordi forventningene er eksplisitte
• Redusert onboarding-tid for nye agenter (og mennesker)

Investeringen i å vedlikeholde ground truths betaler seg i redusert feilsøking og klarere systemgrenser.

Kom i gang

For å legge til en Ground Truth i systemet ditt:

1. Opprett en ground_truths.yaml i pakkens ai_assets/reference/-katalog
2. Definer metadata og renderingskonfigurasjon
3. Legg til påstander som følger skjemaet
4. Kjør uv run orkestra sync for å generere dokumentasjon
5. Inkluder registeret i agentens kontekstkomposisjon

Start med faktaene som skaper mest forvirring, eller begrensningene som brytes oftest. Det er dine mest verdifulle ground truths.

Konklusjon

AI-agenter vil hallusinere. Det ligger i deres natur. Men vi kan skape miljøer der hallusinasjon er begrenset, der visse fakta ikke er til forhandling, der agenter kan sjekke antakelsene sine mot verifisert virkelighet.

Ground truths er ikke en komplett løsning. De krever vedlikehold. De kan bli utdaterte. De legger til overhead i utviklingsprosessen.

Men de gir noe verdifullt: et delt vokabular av fakta som både mennesker og agenter kan stole på. I en verden der agenter i økende grad deltar i programvareutvikling, blir det delte fundamentet essensielt.

Alternativet er endeløse sykluser med agenter som gjør selvsikre feil og mennesker som retter dem opp. Ground truths bryter den syklusen ved å gjøre rettelsene eksplisitte og varige.

Agentene dine fortjener å vite hva som er sant. Fortell dem det.