Kjell Tore Guttormsen
6af3624b17
Lag 5 kjører ETTER transformasjon (lag 4) og FØR en kandidat-endring skrives til
en KB-fil. Den fanger regresjons-klassen: en status-påstand «korrigert» mot en
tilfeldig sitert side og stille auto-applyet (den kjente agentic-retrieval-
regresjonen — hovedkontekst måtte rette manuelt).
Regel (spec §21): status-påstander (GA/preview/versjon/pris) flagges ALLTID for
operatør, aldri auto-applyet — uansett hvor sikker evidensen ser ut.
- lib/verify-out.mjs: ren klassifiserer, null deps (speiler decisions-io).
detectStatusClaim(text) → {isStatus, kinds}; classifyChange(change) →
{verdict: flagged|auto-applied, status_claim, reasons}. Tre flag-regler:
status-gate (§21) · adversarial refutering · autoritets-mismatch (regresjonens
rotårsak). Konservativ med vilje: ved tvil flagges. SKRIVER ALDRI.
- Fixtur tests/fixtures/kb-update/agentic-retrieval-regression.json: den kjente
regresjonen (flat «GA» mot nyansert «delvis GA … resten preview»).
- TDD: 13 tester før kode, inkl. import-invariant (ingen write-utils).
- Wiret i kb-update.md §4 c2 (lag 5 mellom identifiser-endring og skriv).
Kriterium møtt: fixtur → flagged:true, ikke auto-applied.
Tester: validate 239 · kb-update 95 (+13) · kb-eval 13 · kb-integrity 115/115.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01REiKFhP4w6xGXXqWKpPCJJ
148 lines
9.9 KiB
Markdown
148 lines
9.9 KiB
Markdown
---
|
||
name: architect:kb-update
|
||
description: Manuell oppdatering av kunnskapsbasen — poller Microsoft Learn-sitemaps, sammenligner mot lokale `Last updated`-headere, oppdaterer endrede filer og oppdager nye relevante URLer
|
||
argument-hint: "[valgfritt: --skip-discover | --priorities critical,high,medium,low | --dry-run]"
|
||
allowed-tools: 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
|
||
model: opus
|
||
---
|
||
|
||
# /architect:kb-update — Manuell KB-oppdatering
|
||
|
||
Holder Microsoft AI-kunnskapsbasen i `skills/*/references/` ferskt ved å sammenligne lokale referansefiler mot Microsoft Learn-sitemaps. **All kjøring er manuell** — pluginen schedulerer ingenting, og brukere som ønsker periodisk kjøring sørger for det selv (cron, launchd, GitHub Actions, etc.).
|
||
|
||
## 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 |
|
||
|
||
## 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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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 hentes innholdet og en KB-fil skrives i transformasjonslaget (lag 4, Sesjon 5) — for nå holder det å registrere + flagge for henting.
|
||
|
||
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`.
|
||
|
||
### 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
|
||
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})`. 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
|
||
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:
|
||
|
||
```bash
|
||
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.
|
||
|
||
```bash
|
||
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**. Hvis du vil ha periodisk kjøring, sett opp en cron-jobb / launchd-jobb / systemd timer / GitHub Actions-workflow som kjører `node scripts/kb-update/run-weekly-update.mjs --force --discover` (uten apply-fasen) og varsler deg om å kjøre `/architect:kb-update` i en interaktiv Claude Code-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.
|