docs(ms-ai-architect): KB-mekanisme-redesign spec + roadmap + Sesjon 1-funn

Godkjent 6-lags-arkitektur (taksonomi->deteksjon->decision-ledger->verif-inn->transformasjon->verif-ut+eval). Scope krav 1-4 (currency/completeness/optimalisering); krav 5/6 utsatt til fremtidige faser i roadmapen (ikke forkastet). Inkluderer Sesjon 1 eval-baseline-funn + ai-foundry POLL-FIKS-beslutning for Sesjon 2.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01REiKFhP4w6xGXXqWKpPCJJ

docs/kb-mechanism-redesign-plan.md

@@ -0,0 +1,120 @@
+# Spec — Redesign av KB-kunnskapsmekanismen (ms-ai-architect)
+
+_Godkjent plan (operatør, 2026-06-19). Avløser planleggings-input i `kb-mechanism-redesign-brief.md`. Implementeres én sesjon per økt; STATE.md peker på neste sesjon._
+
+## Context
+
+Kunnskapen pluginen leverer (389 referansefiler over 5 skills) er dens kjerneverdi; de 29 kommandoene/12 agentene er bare leveringsmekanismer oppå den. Dagens `kb-update`-mekanisme er **URL- og metadata-forankret**: den ser bare endring i sider den *allerede* siterer, måler «endret» på sitemap-`lastmod` (ikke faktisk innhold), og forankrer status-påstander (GA/preview/versjon) mot en *tilfeldig sitert* side — som ga en reell regresjon (agentic-retrieval-status ble «korrigert» feil; hovedkontekst måtte rette manuelt).
+
+Empiri fra søk-først kvantifiserer problemet:
+- **35 % av KB-en (468/1344 URLer) er `not_in_sitemap`** → «alltid stale». For Azure AI Foundry er det **100 % (164/164)** fordi MS restrukturerte URL-rommet — kjerne-produktet gir aldri et currency-signal.
+- **0 % av filene har en maskinlesbar `Source:`-header** → en forankret per-fil-verifisering har ingen inngangsdata i dag.
+- **Discovery er en dead-end:** `discover-new-urls.mjs` skriver `discovery-report.json` som *leses av ingenting*; nye sider registreres aldri. Kurs (`/training/`) er eksplisitt ekskludert.
+- **Fire divergerende taksonomier** styrer i dag hva som er «i domenet» (poll-prefikser, discovery-INCLUDE, skill-gen-kategorier, prioritets-regex) — allerede inkonsistente.
+
+**Mål:** en mekanisme som holder de eksisterende skills *oppdatert* (currency), *komplette* (nye sider + kurs) og *optimaliserte* (målbar kvalitet), med **auto-deteksjon (scheduled) og operatør-gate på all skriving**. Utfall: pluginen «står på egne ben» — mindre avhengig av manuell hovedkontekst-verifisering, uten å miste operatør-kontroll over innholdet.
+
+### Låst scope og retning (operatør, 2026-06-19)
+- **I scope:** krav 1 currency · 2 completeness (nye sider + kurs) · 4 optimalisering av eksisterende skills.
+- **UTE av scope:** krav 5 (lage nye skills) · krav 6 (slå sammen/slette skills). Innhold kan *vokse* (nye ref-filer ok), men **ingen destruktive ops**.
+- **Autonomi:** deteksjon kjører automatisk → rapport; **all** KB-skriving + URL-registrering går gjennom operatør-gate.
+- **Verifisering:** hver faktapåstand forankres mot en *utpekt* autoritetskilde; status-påstander (GA/preview/versjon/pris) flagges **alltid** for operatør.
+- **Kurs:** Microsoft Learn **Platform API** direkte (krever Entra ID app-registrering; verifisert: app-only, scope `https://learn.microsoft.com/.default`, `api-version=2023-11-01-preview` obligatorisk, 100 calls/min, ingen betaling). Legacy Catalog API er deprecated «through June 2026» → kill-switch-fallback.
+
+## Arkitektur — 6 lag oppå delt registry
+
+```
+0. TAKSONOMI         data/domain-taxonomy.json — én sannhetskilde for "i domenet"
+                     (poll, discovery, skill-gen, prioritet leser HERFRA)
+1. DETEKSJON         currency + completeness + kurs → produserer KUN rapporter
+2. DECISION-LEDGER   data/decisions.json — eneste skrive-autoriserte bro;
+   / OPERATØR-GATE    dedup så avviste kandidater ikke re-foreslås
+3. VERIFISERING-INN  autoritetskilde-binding på godkjente kandidater
+4. TRANSFORMASJON    doc→KB-fil (LLM-destillasjon, status-felt obligatorisk)
+5. VERIFISERING-UT   adversarial "prøv-å-motbevis" + status-gate
+                     (fanger regresjons-klassen — kjøres ETTER transformasjon)
+6. EVAL/OPTIMALISERING  rubrikk K1–K9 (uavhengig av 1–5)
+```
+
+**Lag 0** og **lag 2** er ikke valgfrie: uten konsolidert taksonomi blir completeness til silent misrouting; uten decision-ledger + dedup drukner gaten operatøren → autonomien blir teater (primær-fallgruve). Verifisering er bevisst splittet i **inn** (lag 3) og **ut** (lag 5) fordi den kjente regresjonen er en *post*-transformasjons-feil.
+
+## Roadmap (multi-sesjon, én økt per sesjon)
+
+| Sesjon | Leveranse | Verifiserbart kriterium |
+|---|---|---|
+| **1** | **Eval-baseline + ai-foundry-probe** (read-only) | `node eval.mjs --json \| jq '.skills\|length' == 5`; 10 ai-foundry-URLer kategorisert {redirect/dead/ny-sti} med beslutning |
+| **2** | Taksonomi-konsolidering (lag 0) + registry-skjema (`authority_source`, `status`, kurs-felt) + ai-foundry signal-fiks | `grep -c "TARGET_PREFIXES = \[" scripts/kb-update/*.mjs == 0`; ai-foundry `not_in_sitemap` < 50 % |
+| **3** | Decision-ledger (lag 2) + lukk discovery-løkken gjennom gaten | Discovery 2× re-foreslår ikke en `rejected` URL (dedup-diff) |
+| **4** | Verifisering-ut (lag 5) + adversarial regresjonstest | Kjent agentic-retrieval-regresjon som fixtur → `flagged:true`, ikke `auto-applied` |
+| **5** | Transformasjonslag (lag 4) | Regenerer 1 fil → eval-score ≥ baseline |
+| **Parallelt spor** | Kurs / Platform API-spike (Entra-app + token + date/product-filter) — **av kritisk vei** | `poll-training.mjs` ≥1 kurs m/ `last_modified`; ELLER kill-switch→legacy dokumentert |
+
+Scheduled deteksjon (`/schedule` eller hook) + wiring i `commands/kb-update.md` = siste integrasjonssteg etter lag 1–3.
+
+## Sesjon 1 (detaljert)
+
+**Del A — Eval-baseline (lag 6, flyttet fram):** nytt read-only script som kjører K2/K3/K5/K6 (grep/wc) på alle 5 `SKILL.md` + refs, og LLM-judge (Opus) for K1/K4/K7/K8/K9 på de 5 `SKILL.md`. Output `eval-baseline.json` (skrives kun etter operatør-gate) = referansen alt senere måles mot.
+
+**Del B — ai-foundry signal-probe (riskeste antakelse, ren read):** 10 `not_in_sitemap` ai-foundry-URLer → `microsoft_docs_fetch` → kategoriser {finnes/redirect/ny-sti}. Avgjør om Sesjon 2 er en poll-fiks eller en re-mapping-oppgave.
+
+### Rubrikk K1–K9 (krav 4, «optimalisert skill»)
+- K1 trigger-presisjon (LLM, 20 test-prompts ≥90 %/≤10 %) · K2 tredjeperson/format i description (regex) · K3 SKILL.md ≤500 linjer (wc) · K4 ingen SKILL.md↔ref-duplisering (LLM ≥4/5) · K5 progressive disclosure: navngitte filer ikke mapper (grep, ratio ≥20 %) · K6 kjernefil-routing-tabell finnes (grep) · K7 imperativ-stil (LLM ≥80 %) · K8 kildehenvisning i ref-filer (LLM ≥80 %) · K9 ingen tid-sensitiv info i SKILL.md body (LLM).
+
+## Gjenbruk vs. nybygg (navngitte filer)
+
+**Gjenbruk direkte:** `scripts/kb-update/lib/sitemap-stream.mjs`, `lib/url-normalize.mjs`, `lib/registry-io.mjs`, `lib/atomic-write.mjs` + `lib/backup.mjs` (← for **all** gated skriving), `poll-sitemaps.mjs`-kjernen, `generate-skills.md` 5-parallelle fan-out + `prompt-template.md`.
+
+**Må endres:** `discover-new-urls.mjs` (INCLUDE → poll-paritet + ikke-bare-engineering; skriv decision-ledger-input); `report-changes.mjs` (`getFilePriority` leser taksonomi; datoløse filer = «uverifisert», ikke critical-støy); `build-registry.mjs` (les `Source:`-header → `authority_source`); `commands/kb-update.md` (apply leser decision-ledger); `scripts/skill-gen/category-skill-map.json` (inn i taksonomien).
+
+**Nytt:** `data/domain-taxonomy.json`, `data/decisions.json`, `data/training-registry.json`, `poll-training.mjs`, eval-script (K1–K9) + `eval-baseline.json`, doc→KB-destillasjons-prompt, adversarial motbevis-prompt.
+
+**Multi-agent gir kvalitet (senere):** lag 5 (adversarial motbevis-panel per status-påstand), lag 4 (parallell doc→KB-transformasjon). Foreslås når fasene starter.
+
+## Risiko (rangert) og håndtering
+1. **Gaten drukner operatøren → autonomi blir teater** (primær). → decision-ledger + dedup (lag 2); riktig klassifisering av datoløse/`not_in_sitemap`-filer (Sesjon 2).
+2. **ai-foundry = re-mapping, ikke poll-fiks** (35 % av KB). → testes først (Sesjon 1 Del B).
+3. **Platform API-onboarding blokkerer** (ekstern). → av kritisk vei + kill-switch→legacy.
+4. **Taksonomi-drift → misrouting.** → lag 0 før discovery lukkes.
+5. **Transformasjon innfører regresjon.** → eval-baseline før-måling; lag 5 adversarial-test før vi stoler på laget.
+
+## Verification (overordnet)
+- Per-sesjon kriterier (tabell) er kjørbare sjekker.
+- Pluginens gates ved hver commit: `validate` (239+), `kb-integrity` (115/115), `gitleaks` clean.
+- Arkitektur-invariant: deteksjon skriver *aldri* til KB direkte — kun via `decisions.json` etter gate (deteksjon-scripts importerer ikke write-utils).
+
+## Inneværende scope vs. fremtidig roadmap
+
+**Inneværende mekanisme-arbeid (Sesjon 1–5 + kurs-spor):** krav 1 currency · 2 completeness · 4 optimalisering — på de eksisterende 5 skills. Innhold kan vokse (nye ref-filer).
+
+**Utsatt til senere faser — på roadmap, IKKE forkastet** (operatørens valg 2026-06-19 var «krav 1–4 nå»; krav 5/6 var merket «ikke nå», dvs. utsatt):
+- **Krav 5 — lage nye skills profesjonelt.** Naturlig neste utvidelse når deteksjonen (lag 1) begynner å avdekke domener uten dekning (fra domene-taksonomien: f.eks. Power Platform AI / AI Builder / Power Automate, Dynamics365). Forutsetter lag 0–3.
+- **Krav 6 — slå sammen/slette skills (livssyklus, destruktive ops).** Krever egne guardrails (aldri tap av kuratert verdi) + obligatorisk operatør-gate. Vurderes etter at lag 1–6 står.
+
+Annet utsatt arbeid sporet her: **Low-currency-bøtta (51 filer)** — parkert bak redesignet; kjøres med den nye mekanikken (eller som siste enkle bøtte hvis redesignet drar ut).
+
+> Denne seksjonen ER roadmapen for fremtidige faser. Den bor i `docs/` (ikke en egen `ROADMAP.md`) per den globale «ingen lokale kontinuitets-mekanismer»-regelen, og refereres fra `STATE.md`.
+
+---
+
+## Sesjon 1 — resultater (2026-06-19) ✅ FERDIG
+
+Kriterier møtt: `node scripts/kb-eval/eval.mjs --json | jq '.skills|length'` = 5; 10 ai-foundry-URLer kategorisert. Tester: **kb-eval 13 PASS · kb-update 42 PASS (regresjon) · validate 239 PASS**. Node 25 krever eksplisitte filstier (`tests/X/*.test.mjs`), ikke katalog.
+
+### Eval-baseline (referanse for senere optimalisering — lag 6)
+Verktøy: `scripts/kb-eval/eval.mjs` (determ. K2/K3/K5/K6 + ref-tall) + operatør-gated LLM-judge (`judge-prompt.md` → `data/judge-results.json`), flettet til `data/eval-baseline.json`. Tester i `tests/kb-eval/`.
+
+Pass-matrise (K2/K3/K7/K8 ✓ for alle 5):
+- **K5 (progressive disclosure): 3/5 FAIL** — advisor (1,6 %), engineering (0 %), security (16 %) bruker mappehenvisninger; infrastructure (97 %) er forbildet å kopiere.
+- **K9 (tid-sensitiv info i SKILL.md body): 4/5 FAIL** — GA/preview-status, modellversjoner, SLA-/perf-tall ligger i body (kun advisor ren). Hører i ref-filer (currency-sporet).
+- **K4 (duplisering): 2/5 FAIL** — governance (3/5: DPIA/AI-Act/Digdir dupliserer ref-filer), security (3/5).
+- **refTall-konsistens: 2/5 FAIL** — engineering (agent-orch tabell 20 vs faktisk 24; total 149 vs 153), governance (29 vs 30).
+
+**To konkrete bugs (operatør-beslutning kreves; fikses i optimaliserings-fase, ikke nå):**
+1. **security 6×5-vekting motstrider kanonisk rubrikk:** SKILL.md body (Identity 20/Network 15/Data 20/Content 20/Compliance 15/Mon 10) ≠ `security-scoring-rubrics-6x5.md` (Compliance 25/Data 20/Identity 20/Content 15/Network 10/Mon 10). Påvirker scoring-output. → hvilken er kanonisk?
+2. **governance-SKILL.md linje 191** peker på ikke-eksisterende `drift-detection-automated-retraining.md` (faktisk: `model-performance-drift-detection.md`).
+
+K1-presisjon (0,95–1,0) er **PROVISORISK** — operatør må kuratere 20 trigger-prompts/skill. Flagg: governance-description mangler Schrems II-trigger; advisor-description er bred nok til å over-trigge mot søsken-kommandoer.
+
+### ai-foundry signal-probe → BESLUTNING for Sesjon 2
+10 URLer: **8 LIVE · 0 MOVED · 2 DEAD**. Rotårsak: MS rebrandet «Azure AI Foundry» → «Microsoft Foundry»; nye canonical-URLer under `/azure/foundry/` (i `azure_en-us_7`-sitemap), gamle `/azure/ai-foundry/` serverer fortsatt innhold men matcher aldri sitemapet → 100 % `not_in_sitemap`.
+**→ POLL-FIKS (ikke re-arkitektur av signalet):** remap registry `azure/ai-foundry/*` → `azure/foundry/*` + 2 DEAD-remappinger (`concepts/evaluation-evaluators`→`concepts/built-in-evaluators`; `agent-service`→`agents/overview`). Sitemap-`lastmod` fra `azure_en-us_7` er tilstrekkelig signal; ingen innholdshash nødvendig.