ms-ai-architect/commands/kb-update.md

name	description	argument-hint	allowed-tools	model
architect:kb-update	Manuell oppdatering av kunnskapsbasen — poller Microsoft Learn-sitemaps, sammenligner mot lokale `Last updated`-headere, oppdaterer endrede filer og oppdager nye relevante URLer	[valgfritt: --skip-discover | --priorities critical,high,medium,low | --dry-run]	Bash, Read, Edit, Write, Glob, Grep, mcp__microsoft-learn__microsoft_docs_search, mcp__microsoft-learn__microsoft_docs_fetch, mcp__microsoft-learn__microsoft_code_sample_search	opus

/architect:kb-update — Manuell KB-oppdatering

Holder Microsoft AI-kunnskapsbasen i skills/*/references/ ferskt ved å sammenligne lokale referansefiler mot Microsoft Learn-sitemaps.

Apply (oppdatering av KB-filer) er alltid manuell og kjøres in-session — den bruker Claude og forblir under operatør-gate. Deteksjon (poll → rapport → discovery → skill-livssyklus) er ren node som aldri kontakter Claude/Anthropic, og kan valgfritt schceduleres (se «Scheduled deteksjon» under). Skillet er ToS-forankret: Consumer Terms §3.7 begrenser automatisert tilgang til Anthropics tjenester — ikke kjøring av lokale scripts som ikke rører Claude.

Hva kommandoen gjør

1. Polle sitemaps: kjører node scripts/kb-update/run-weekly-update.mjs --force for å hente fersk <lastmod> for hver Microsoft Learn-URL i registeret
2. Optional discovery: med default --discover finner nye relevante URLer i sitemap som ikke er i registeret (scripts/kb-update/discover-new-urls.mjs --limit 500). Discovery leser beslutnings-ledgeren (data/decisions.json, lag 2) og utelater alt operatøren allerede har tatt stilling til (policy A: approved/rejected/pending) — så de samme kandidatene drukner ikke gaten kjøring etter kjøring
3. Generere endringsrapport: report-changes.mjs produserer data/change-report.json med per-fil prioritering (critical/high/medium/low) basert på antall endrede kilder + alder på lokal fil
4. Vise rapporten: lese rapport, presentere oppsummering til bruker, vente på go
5. Oppdatere filer: for hver fil i valgt prioritetsbøtte (default: critical + high):
   • Hente fersk innhold fra alle endrede kildene via microsoft_docs_fetch
   • Oppdatere relevante seksjoner i den lokale .md-fila
   • Oppdatere Last updated:-header til dagens dato
6. Committe: én git-commit per fil med chore(ms-ai-architect): refresh KB <fil> [skip-docs]-format (eller én samlet commit om brukeren foretrekker det)

Argumenter

Flagg	Effekt
--skip-discover	Hopp over discovery-passet (raskere, ingen nye URLer oppdages)
--priorities <list>	Komma-separert subset av critical,high,medium,low. Default: critical,high
--dry-run	Generer rapport, men ikke oppdater filer eller committ
--single-commit	Samle alle filendringer i én commit i stedet for én per fil

Scheduled deteksjon (opt-in, Spor C / C1)

Deteksjonen kan kjøre automatisk i bakgrunnen ved sesjonsstart — av som default. Den er frivillig å sette opp, men virker når aktivert.

Slik aktiverer du den: opprett ms-ai-architect.local.md i plugin-roten (gitignored) med:

---
scheduled_detection:
  enabled: true            # default false — ingenting kjører før dette er true (Tier 1)
  interval_days: 7         # kjør deteksjon på nytt når det er ≥ N dager siden sist poll
  include_skill_lifecycle: true   # ta med skill-livssyklus-deteksjon (overlapp/gap/bloat)
  os_scheduler_cadence: daily     # Tier 2: daily (poll hver dag) | interval (throttle på interval_days)
---

Tier 1 — sesjonsforankret (SessionStart-hook)

Når enabled: true og det er ≥ interval_days siden sist poll, spawner SessionStart-hooken scripts/kb-update/run-detection.mjs i bakgrunnen. Den kjører kun deteksjon (poll → rapport → discovery → skill-livssyklus) og skriver JSON-rapporter til data/ — aldri til skills/, og kaller aldri Claude. Ferske signaler surfaces ved neste sesjonsstart («KB: …» + «Skill-signaler: …»), og du kjører /architect:kb-update manuelt for å gjennomgå + apply-e gjennom gaten. Begrensning: Tier 1 kjører bare når en Claude-sesjon starter — starter du aldri en sesjon, kjører deteksjonen aldri.

Tier 2 — lokal launchd-scheduler (ekte bakgrunn mellom sesjoner)

For deteksjon som kjører uavhengig av sesjoner, installer en lokal launchd LaunchAgent som fyrer samme Claude-frie entrypoint daglig (kl. 03:00):

node scripts/kb-update/scheduler.mjs install     # skriv plist til ~/Library/LaunchAgents + last agenten
node scripts/kb-update/scheduler.mjs status       # er den lastet?
node scripts/kb-update/scheduler.mjs run-now       # kjør én gang nå (verifiser uten å vente til 03:00)
node scripts/kb-update/scheduler.mjs print          # vis plisten uten å skrive noe (alias --dry-run)
node scripts/kb-update/scheduler.mjs uninstall       # avlast + fjern plist

• Kadens (os_scheduler_cadence): daily (default) poller hver dag; interval throttler til interval_days via samme staleness-gate som Tier 1. (Onboarding setter dette senere; daglig er fornuftig default — poll av Microsoft Learn-sitemaps er billig og read-only.)
• Pause = uninstall. LaunchAgenten kjører uansett enabled:-flagget (det styrer kun Tier 1/hooken). Vil du stoppe Tier 2, kjør uninstall — det er pause-knappen.
• Etter en major brew upgrade node: kjør install på nytt. Node-stien bakes inn ved install-tid (launchd har minimalt PATH); plistens PATH inkluderer /usr/local/bin så barneprosessenes node overlever, men det er ryddigst å re-installere.
• launchd, ikke cron: Apple anbefaler launchd; cron krever Full Disk Access og er «not recommended». Vil du heller bruke cron/systemd/CI, peker du den på samme node scripts/kb-update/run-detection.mjs.

ToS-garanti (strukturell, begge tiers): entrypointet (run-detection.mjs, og scheduler.mjs run som delegerer til det) spawner kun node på de allow-listede deteksjons-scriptene + launchctl for agent-styring; det kan ikke invokere claude. Apply (det eneste Claude-steget) forblir manuelt og in-session. Kjør node scripts/kb-update/run-detection.mjs --dry-run (eller scheduler.mjs print) for å se hva som ville kjørt uten å kjøre noe.

Instruksjoner til assistenten

1. Pre-flight

• pwd — bekreft at du står i plugins/ms-ai-architect/ (eller delegere via absolutt sti)
• git status --porcelain | grep -E '\.md$' && echo "WARN: ucommittede skill-endringer — kommandoen vil blande dem inn" — advar bruker hvis det finnes lokale skill-endringer
• Parse argumenter

2. Kjør pollingsfasen

node scripts/kb-update/run-weekly-update.mjs --force${ARG_DISCOVER}

Hvor ${ARG_DISCOVER} er --discover med mindre --skip-discover ble gitt.

Output forventes å skrive data/change-report.json og evt. nye registry-entries hvis discovery kjørte.

3. Vis rapport-oppsummering

node scripts/kb-update/report-changes.mjs | head -40

Presenter til bruker:

• Antall filer per prioritet
• Hvilke prioriteter som blir behandlet (default: critical + high)
• Estimert antall microsoft_docs_fetch-kall (≈ sum av endrede kilder per fil)
• Spør: "Fortsett med oppdatering? (y/n)"

Hvis --dry-run: stopp her, ikke oppdater filer.

3b. Discovery-gate — nye URLer via decision-ledger (lag 2)

Kjørte discovery (default), lukk løkken her. Dette er operatør-gaten — det eneste stedet beslutninger om nye URLer skrives.

a. Les kandidatene: data/discovery-report.json → candidates[]. Listen er allerede dedupet av scriptet mot både registry og data/decisions.json, så alt her er genuint ubesluttet. Feltet deduped_by_ledger viser hvor mange tidligere beslutninger som ble utelatt.

b. Presenter for operatør, gruppert per suggested_skill (vis url, suggested_category, lastmod). For hver kandidat (eller batch): approve (ta inn i KB), reject (irrelevant — ikke vis igjen), eller utsett (pending — ikke avgjort, vises i pending-bøtta men re-foreslås ikke).

c. Skriv beslutningene til ledgeren — ENESTE skrivevei. Bruk lib/decisions-io.mjs (ikke håndskriv JSON):

import { loadDecisions, recordDecision, saveDecisions } from './scripts/kb-update/lib/decisions-io.mjs';
let led = loadDecisions();
led = recordDecision(led, url, { status: 'rejected', decided_at: '<i dag>', suggested_skill, suggested_category, note });
// ...én recordDecision per beslutning...
saveDecisions(led);

decided_at settes til dagens dato (caller-injisert — recordDecision er ren). decisions.json er tracket i git (overlever, til forskjell fra de genererte rapportene).

d. For approved: registrér URLen i url-registry (gated) så den fanges av polling heretter — via lib/registry-io.mjs saveRegistry. Bruk suggested_skill/suggested_category fra kandidaten. Deretter kjør transformasjonslaget (lag 4) for å lage KB-fila:

1. microsoft_docs_fetch på den godkjente URLen → kildedokument.
2. Destillér via scripts/kb-update/transform-prompt.md (doc→KB-fil; status-påstander holdes eksplisitte). Multi-agent parallell fan-out foreslås i produksjon (roadmap §71), speilet på generate-skills-mønsteret.
3. content = buildKbHeader({title, status, category, source: <godkjent URL>, lastUpdated: <YYYY-MM>}) + body (lib/transform.mjs). Status + Source er obligatoriske — Source i header-blokka (øverste 500 bytes) er det som lar lag 3 backfille authority_source.
4. validateKbFile(content) MÅ være valid: true før noe gates videre (ellers be modellen fylle manglende felt).
5. For hver status-/load-bearing-påstand: buildChange({...}) → lag 5 classifyChange(...) (samme gate som §4 c2). Status-påstander er alltid flagged.
6. resolveTargetPath(tax, category, filename) → eierskill-sti via taksonomien (null = ukjent kategori → flagg for operatør, ikke skriv).
7. Først etter operatør-gate: atomisk skriving (lib/atomic-write.mjs + lib/backup.mjs). transform.mjs skriver aldri selv — verifisert av tests/kb-update/test-transform.test.mjs (import-invariant). Kriterium verifisert av tests/kb-eval/test-transform-criterion.test.mjs (regenerer 1 fil → eval ≥ baseline).

e. Invariant: discover-new-urls.mjs (deteksjon) skriver aldri ledgeren — den kun leser. Bare denne gaten skriver. Verifisert av tests/kb-update/test-discover-invariant.test.mjs.

3c. Kurs-deteksjon-gate — nye/endrede kurs via decision-ledger (courses-kolleksjon, Spor C / C3)

Operatør-gaten for kurs-sporet. Et kurs-lead er et signal om at et tema finnes — aldri en doc-side som ingestes. Å godkjenne et lead henter/transformerer/skriver ingen KB-fil (det ville vært auto-ingest, et eksplisitt ikke-mål) — det registrerer kun operatørens beslutning i den UID-nøklede courses-kolleksjonen. Dette er ENESTE skrivevei for kurs-beslutninger.

a. Sjekk rapporten: data/course-detection-report.json. Produsert av den Claude-frie detektoren (detect-courses.mjs) — enten schedulert (Tier 1/2) eller manuelt: node scripts/kb-update/detect-courses.mjs. Mangler fila, eller status:"skipped" (Keychain-creds mangler — C3 er opt-in inni opt-in): hopp over denne gaten stille. status:"error": rapportér kort og hopp over.

b. Les leads: new[] + updated[] (hver {uid, title, url, products, suggested_skill, suggested_category, updated_at}). removed[] er kun et informasjonssignal — vis det som en notis, aldri som en beslutning (et retirert kurs er ikke et tema å dekke; spec §4.2).

c. Dedup mot ledgeren (policy A): utelat leads operatøren allerede har tatt stilling til. Bruk isCourseLeadDecided (UID er den stabile nøkkelen — URL kan endres):

import { loadDecisions, isCourseLeadDecided } from './scripts/kb-update/lib/decisions-io.mjs';
const led = loadDecisions();
const fresh = [...report.new, ...report.updated].filter((l) => !isCourseLeadDecided(led, l.uid));

d. Presenter fresh for operatør, gruppert per suggested_skill (vis title, url, products, kind new/updated). For hvert lead (eller batch): approve (relevant — verdt å dekke i KB-en), reject (ikke relevant — ikke vis igjen), eller utsett (pending — ikke avgjort).

Hvis --dry-run: stopp etter presentasjonen — ikke skriv ledgeren.

e. Skriv beslutningene til ledgeren — ENESTE skrivevei. Bruk recordCourseLead (ikke håndskriv JSON):

import { loadDecisions, recordCourseLead, saveDecisions } from './scripts/kb-update/lib/decisions-io.mjs';
let led = loadDecisions();
led = recordCourseLead(led, uid, {
  kind, status: 'approved', title, url, products, suggested_skill, suggested_category,
  updated_at, detected_at, decided_at: '<i dag>', note,
});
// ...én recordCourseLead per beslutning...
saveDecisions(led);

decided_at settes til dagens dato (caller-injisert — recordCourseLead er ren). decisions.json er tracket i git.

f. Ingen ingest — strukturell invariant. Et godkjent kurs-lead blir værende i courses-kolleksjonen og leses av ingen av apply-pathene: apply-skill-op.mjs leser kun actions, discover-new-urls.mjs kun decisions. En kurs-beslutning trigger derfor aldri fetch/transform/KB-skriving. Skal et kurs' tema faktisk dekkes med en KB-side, er det en separat, bevisst doc-discovery-handling gjennom §3b (finn doc-URLen) — ikke en automatisk konsekvens av å godkjenne kurset. Et godkjent kurs surfaces ved sesjonsstart (C3.6: «N nye / M endrede kurs i dekkede produkter») som en påminnelse til operatøren.

4. Per-fil oppdatering (etter brukerens y)

For hver fil i valgte prioriteter:

a. Les nåværende fil: Read på filstien b. Hent oppdaterte kilder: for hver URL i change-report.json[file].changed_urls, kjør microsoft_docs_fetch på URLen c. Identifiser endringer: sammenlign hentet markdown mot eksisterende seksjoner i fila. Fokuser på faktuelle endringer (ny info, oppdaterte features, deprecation-varsler) — ikke små formuleringsendringer c1. Autoritetskilde-binding (lag 3) — header-as-truth. authority_source = resolveAuthority(<fil-innhold>) (lib/authority.mjs) — fila sin **Source:**-header ER den utpekte autoriteten for dens påstander. null hvis fila mangler headeren (vokser etter hvert som lag 4 regenererer filer). Dette er inngangsdataen til lag-5 regel 3 (autoritets-mismatch): er en status-/load-bearing-endrings source_url ≠ authority_source, flagges den. Aldri gjett en autoritet fra fila sine siterte URLer (251/303 filer siterer 4–10 → ville vært gjetning). c2. Verifisering-ut (lag 5) — FØR du skriver. Hver kandidat-endring fra (c) går gjennom lib/verify-out.mjs classifyChange({field, old_value, new_value, source_url, authority_source, refutations}) med authority_source fra (c1). Dette fanger regresjons-klassen (en status-påstand «korrigert» mot en tilfeldig sitert side og stille auto-applyet — agentic-retrieval-regresjonen):

• flagged → IKKE auto-skriv. Vis endringen til operatør med reasons[]; operatør avgjør om den tas inn. Status-påstander (GA/preview/versjon/pris) er ALLTID flagged (spec §21) — uansett hvor sikker kilden ser ut.
• auto-applied → trygt å ta inn i (d) (benign, ikke-status, ingen motbevis, autoritets-match).
• Adversarial motbevis-panel (LLM-runtime): for status-/load-bearing-påstander, kjør et lite panel som prøver å motbevise new_value mot den utpekte authority_source, og mat resultatene inn som refutations[] ([{refuted, reason}]). Multi-agent foreslås når lag 4/5 kjøres i produksjon (roadmap §71).
• Invariant: verify-out.mjs skriver aldri — den returnerer kun en verdict. Selve skrivingen skjer i (d), gated. Verifisert av tests/kb-update/test-verify-out.test.mjs. d. Oppdater fila: Edit med endringer som er auto-applied eller eksplisitt godkjent av operatør i (c2). Behold "For Cosmo"-seksjonen og overordnet struktur. Oppdater Last updated: YYYY-MM-DD-header til dagens dato. Lag-4-kontrakt: kjør validateKbFile(<ny fil-innhold>) (lib/transform.mjs) før skriving — den skal være valid: true. Mangler fila et **Source:**-header, legg det til i header-blokka med den utpekte autoritets-URLen for hovedkilden — da fanger lag 3 (resolveAuthority + build-registry) den som authority_source, og lag-5 regel 3 blir virksom for fila. e. Committ: git add <fil> + git commit -m "chore(ms-ai-architect): refresh KB $(basename <fil>) [skip-docs]" med mindre --single-commit ble gitt

5. Single-commit modus

Hvis --single-commit: skip committer per fil, og lag én samlet commit til slutt:

git add skills/
git commit -m "chore(ms-ai-architect): refresh KB — N files [skip-docs]"

6. Push (om bruker bekrefter)

Spør: "Push til Forgejo origin/main? (y/n)". Per global push-policy er direkte main-push pre-autorisert, men spør likevel her siden dette er en bulk-operasjon.

git push origin main

7. Oppsummering

Rapporter:

• Antall filer oppdatert per prioritet
• Antall commits laget
• Hvis discovery kjørte: antall nye URLer oppdaget og lagt til registry
• Eventuelle filer som ble hoppet over (f.eks. ingen reelle endringer i hentet innhold)
• data/change-report.json blir værende på disk for diagnose

Fallgruver

• Sitemap-coverage: ~69% av URLene matche mot sitemap. ~31% (mest azure/ai-foundry/openai/) finnes ikke pga. URL-restrukturering på Microsofts side. Disse rapporteres som "always stale" og må vurderes manuelt
• Microsoft_docs_fetch latency: hver fetch tar 2-5 sek. 9 critical + 44 high filer × ~1.5 kilder hver = ~80 fetches = ~3-7 minutter
• Modellvalg: Opus brukes fordi diff-resonnering + tekst-syntese krever nyanse. For enklere "just refresh dates"-oppdateringer er Sonnet tilstrekkelig — bruker kan overstyre med eksplisitt --model claude-sonnet-4-6 i Claude Code config
• MCP-tilgjengelighet: kommandoen krever at microsoft-learn MCP-serveren er aktiv. Sjekk med claude mcp list ved første kjøring

Når kjøre

• Anbefalt: ukentlig eller månedlig, avhengig av hvor sensitive prosjektene dine er for KB-ferskhet
• Før viktig vurdering: kjør med --priorities critical,high,medium før en stor /architect:utredning eller /architect:adr
• Etter Microsoft-events: Build, Ignite, eller annen større Microsoft-konferanse → forvent mange endringer

Schedulering

Pluginen schedulerer ingenting før du selv aktiverer det (alt er opt-in). Du har tre nivåer, alle Claude-frie i deteksjonsfasen:

• Tier 1 (sesjonsstart): scheduled_detection.enabled: true i ms-ai-architect.local.md — se «Scheduled deteksjon» over.
• Tier 2 (lokal launchd, ekte bakgrunn): node scripts/kb-update/scheduler.mjs install — se «Scheduled deteksjon» over.
• Egen scheduler: vil du heller bruke cron / systemd timer / CI, pek den på node scripts/kb-update/run-detection.mjs (eller run-weekly-update.mjs --force --discover for den eldre poll-flyten) og la den varsle deg om å kjøre /architect:kb-update i en interaktiv sesjon.

Apply-fasen (oppdatere filer + committe) kan ikke automatiseres innenfor denne pluginen — den krever LLM-resonnering på endringene og menneskelig vurdering, og er bevisst designet for kjøring fra en åpen Claude Code-sesjon.