ms-ai-architect/docs/onboarding-redesign-plan.md

Spec — Redesign av onboarding-/virksomhetskontekst-mekanismen (ms-ai-architect)

Godkjent plan (operatør, 2026-06-22). Avløser planleggings-input i onboarding-redesign-brief.md. Spor C fase C2 (etter C1 ✅, før C3 kurs). Implementeres én delsesjon per økt; STATE.md peker på neste. Samme kontinuitetsregler som KB-redesignet: planen bor i docs/, refereres fra STATE.md, ingen egen ROADMAP.md.

Context

Virksomhetskontekst (sektor, lisens, dataklassifisering, residens, budsjett, styringsmodell, regelverk + fri prosa) er det som gjør pluginens output relevant for denne brukeren i stedet for generisk. Operatørens vurdering (2026-06-19, gjentatt 2026-06-20): hvis konteksten ikke er til stede i enhver interaksjon og ikke overlever oppgraderinger, skaper mekanismen frustrasjon i stedet for verdi. C2 er kritisk for at pluginen blir praktisk i bruk.

Verifisert tilstand (2026-06-22, mot koden — ikke briefen alene)

#	Krav	Faktisk tilstand i koden
1	Ambient i enhver interaksjon	Reelt gap. hooks/scripts/session-start-context.mjs:135-139 injiserer kun status («Ingen virksomhetstilpasning»), ikke innhold. De 11 agentene (adr-writer, summary, research, cost-estimation, license-mapper, diagram-generation, dpia, ros-analysis, ai-act-assessor, security-assessment, architecture-review) leser org/ betinget («Hvis org/-mappen finnes…»). Kommandoer/fritekst uten egen org-seksjon får ingenting.
2	Overlever oppgraderinger	Reelt gap. org/ er gitignored (.gitignore:24) og bor i plugin-katalogen → reinstall/marketplace-flytt blåser den bort. Samme gjelder ms-ai-architect.local.md (C1-scheduler-config): leses fra plugin-rot (loadScheduleConfig(pluginRoot), detection-schedule.mjs:95) og er *.local.md-gitignored → scheduler-innstillingene dør også ved reinstall.
3	Fritekst-felt	Reelt gap. Onboarding samler kun strukturerte AskUserQuestion-svar. Ingen fri-prosa-felt («alt annet du vil pluginen skal vite»).
4	Privat-sektor-paritet	Trolig allerede løst — agents/onboarding-agent.md Phase 1 forgrener allerede offentlig/privat med egen reg-liste (DORA, Finansforetaksloven, Finanstilsynets IKT-forskrift, Verdipapirhandelloven, Hvitvaskingsloven, …). C2.4 verifiserer og lukker evt. devils-advocate-audit-2026-06-18.md §167-residu — antar ikke at det er gjort.
5 (S24)	Eksponer os_scheduler_cadence	Config-plumbingen finnes alt (DEFAULT_SCHEDULE_CONFIG.os_scheduler_cadence:'daily', parses fra scheduled_detection:-blokk i detection-schedule.mjs). Gapet: eneste måte å sette den på er å hånd-redigere den gitignored config-fila. Onboarding må skrive den (operatør: «avgjøres i onboardingen, egen innstilling, daglig default»).

Nøkkelinnsikt: #1 og #2 løses renest sammen. Når hooken injiserer org-innhold ambient, og dataene bor på en bruker-eid sti, blir «hvor bor dataene» et spørsmål bare hooken + onboarding-agenten må svare på.

Låst scope og retning (operatør, 2026-06-22)

• Lagringssted (BESLUTTET): flytt både org-data og C1-scheduler-config ut av plugin-katalogen til en bruker-eid mappe ~/.claude/ms-ai-architect/ (søsken av ~/.claude/plugins/, overlever plugin-reinstall). Personvern bevart — ligger ikke i noe git-repo. Bakoverkompat: les ny sti først, fall tilbake til plugin-rot/org/; migrer gammel hvis present (i praksis no-op i dag — ingen eksisterende data).
• Ambient: session-start-context.mjs injiserer et kompakt org-sammendrag (lengde-budsjett, ~25 linjer), slik STATE.md injiseres. Ikke rå-filer.
• Agentenes betingede lesing beholdes som fallback, men peker på den bruker-eide stien (se risiko 5 — subagent-injeksjon er en antakelse som SKAL testes i C2.1).
• Ingen destruktive ops på eksisterende org-data. Innhold kan vokse (fritekst-fil).
• TDD ufravikelig: test FØR kode i hver delsesjon. Operatør-gate på beslutninger.

Arkitektur

LAGRING       ~/.claude/ms-ai-architect/
              ├── org/*.md            (5 strukturerte filer + free-context.md)
              └── ms-ai-architect.local.md   (scheduler-config; samme blokk-format)

RESOLVER      lib/user-data.mjs (NY, ren, SKRIVER ALDRI)
              resolveUserDataDir(homedir) · resolveOrgDir · resolveConfigPath
              buildOrgSummary(files,{cap}) — deterministisk, lengde-kappet

AMBIENT       session-start-context.mjs LESER resolver → injiserer summary (stdout)
KONSUM        11 agenter: betinget lesing (fallback) peker på resolveOrgDir
SKRIVING      onboarding-agent.md → resolveOrgDir; scheduler-spørsmål → resolveConfigPath
              (gated KB-/config-skriving via lib/atomic-write + lib/backup)

Bakoverkompat-invariant (C1 må ikke knekke): loadScheduleConfig skal lese bruker-sti FØRST, deretter falle tilbake til dagens plugin-rot-sti. Den allerede-shippede Tier-1/Tier-2-scheduleren leser samme config — fallbacken garanterer uendret oppførsel for en bruker som allerede har en plugin-rot-config.

Roadmap (multi-delsesjon, én økt per delsesjon)

Delsesjon	Leveranse	Verifiserbart kriterium
C2.1	Bruker-eid lagring + ambient injeksjon (#1 + #2)	K1 + K2 (se under). loadScheduleConfig bakoverkompat-test grønn (bruker-sti vinner, fallback til plugin-rot).
C2.2	Fritekst-felt (#3)	K3: onboarding fanger org/free-context.md; innholdet synlig i etterfølgende interaksjon (summary inkluderer det, kappet).
C2.3	os_scheduler_cadence + enabled i onboarding (S24)	K5: onboarding skriver scheduled_detection:-blokk som parseScheduleConfig leser tilbake korrekt (round-trip-test: daily/interval/enabled).
C2.4	Privat-sektor-paritet — verifiser + lukk §167-residu (#4)	K4: privat virksomhet fullfører onboarding uten «Annet» på sektor, med relevant reg-liste.

C2.1 er den bærende delsesjonen (etablerer lagring + resolver alle andre bygger på). C2.2–C2.4 er additive oppå den.

Verifiserbare akseptansekriterier (binding)

• K1 (ambient): Frisk sesjon med utfylt org-kontekst + et fritekst-spørsmål uten å invokere en org-bevisst agent → svaret reflekterer ≥1 org-faktum. Bevis: konteksten injiseres (ikke betinget lest). Test: hook-output inneholder org-sammendrags-blokken når resolver finner org-filer.
• K2 (overlevelse): Simuler oppgradering (flytt/reinstaller plugin-katalogen) → org-konteksten + scheduler-configen er fortsatt tilgjengelig. Bevis: resolver peker på ~/.claude/ms-ai-architect/, utenfor det reinstall blåser bort. Test: resolver returnerer bruker-sti uavhengig av pluginRoot; loadScheduleConfig finner bruker-config selv når plugin-rot-config mangler.
• K3 (fritekst): Onboarding fanger et fritt prosa-felt; innholdet er synlig i en etterfølgende interaksjon (i ambient-sammendraget, kappet til budsjett).
• K4 (paritet): Privat virksomhet kan fullføre onboarding uten å velge «Annet» på sektor, med relevant reguleringsliste.
• K5 (S24 cadence): Onboarding skriver en scheduled_detection:-blokk (enabled + os_scheduler_cadence) til bruker-config; parseScheduleConfig leser den tilbake til samme verdier (round-trip). Garbage/utelatt → daily-default (eksisterende coerce-regel).

Gjenbruk vs. nybygg (navngitte filer)

Gjenbruk direkte:

• detection-schedule.mjs scheduled_detection:-blokkformat + parseScheduleConfig/coerce (C2.3 skriver dette formatet; ingen ny parser).
• lib/atomic-write.mjs + lib/backup.mjs (for all gated config-/org-skriving).
• session-start-context.mjs injeksjonsmekanisme (stdout → SessionStart additional context).

Nytt:

• scripts/.../lib/user-data.mjs (ren resolver + buildOrgSummary; SKRIVER ALDRI; null avhengigheter utover node:fs/path/os). Speiler detection-schedule.mjs-stilen (ren kjerne, tynn konsument).
• org/free-context.md-konvensjon (C2.2).
• Onboarding scheduler-spørsmål (C2.3).

Må endres:

• session-start-context.mjs — resolve bruker-org-dir (fallback plugin org/), injiser kompakt summary (ikke bare status).
• detection-schedule.mjs loadScheduleConfig — bruker-sti først, fallback plugin-rot (bakoverkompat).
• agents/onboarding-agent.md — skriv til bruker-sti; nytt fritekst-felt (C2.2); scheduler-spørsmål (C2.3).
• 11 agentfiler — «Virksomhetskontekst (automatisk)»-seksjonen: fallback-lesing peker bruker-sti + note om at kontekst injiseres ambient. Mekanisk, uniform (grep-test for konsistens).
• commands/onboard.md (88 l), CLAUDE.md, README.md, .gitignore (org/-regel blir moot men beholdes som forsvar-i-dybden) — sti-referanser.

Risiko (rangert) og håndtering

1. Subagent-injeksjon-antakelse (KRITISK — testes i C2.1). SessionStart-hookens stdout blir main-kontekst. Det er ikke verifisert at Task-spawnede subagenter (de 11) arver den. Hvis ikke: ambient-injeksjonen dekker main-kontekst + ikke-agent-kommandoer, mens agentene bæres av fallback fil-lesing fra bruker-stien. Derfor beholdes agentenes betingede lesing (pekt på resolver) — design er robust uansett utfall. Eksplisitt test i C2.1 før vi stoler på «ambient».
2. C1-config bakoverkompat. Flytting av config-sti kan knekke den shippede scheduleren. → fallback (bruker-sti → plugin-rot) + round-trip-test; ikke fjern plugin-rot-lesing.
3. Hook-injeksjon-bloat. Summary prependes hver sesjon. → hardt lengde-budsjett (~25 l) i buildOrgSummary, kapp fritekst.
4. 11-agent mekanisk drift. → uniform edit + grep-test at alle org-bevisste agenter refererer resolver-stien likt.
5. Personvern. Bruker-sti ligger ikke i repo; behold .gitignore org/ som forsvar-i-dybden.

Verification (overordnet)

• Per-delsesjon K-kriterier (tabell) er kjørbare sjekker.
• Pluginens gates ved hver commit: validate (239+), kb-integrity, test-hooks.sh, gitleaks clean (3 pre-eksisterende i playground/vendor/ = uendret baseline).
• Nøkkelantakelse testet (CLAUDE.md plan-kvalitet): subagent-injeksjon (risiko 1) — eksplisitt test i C2.1; merket risiko til den er bevist.
• Arkitektur-invariant: lib/user-data.mjs er ren resolver (SKRIVER ALDRI); all org-/config-skriving gated via atomic-write/backup.

Avgrensning

• Ikke del av KB-mekanisme-redesignet (kb-mechanism-redesign-plan.md) eller Spor B (skill-lifecycle-spor-b-plan.md). Eget spor, egen plan.
• C3 (kurs/training, #25) tas etter C2.
• docs/onboarding-ros-analysis.md er feildøpt (Windows clone-to-PR-guide, ikke onboarding-analyse) — vurder omdøping i C2.4 (lav prioritet).

---

C2.1 — konkret startplan (bruker-eid lagring + ambient injeksjon)

Mål: etabler ~/.claude/ms-ai-architect/ som bruker-eid datarot, en ren resolver alle andre delsesjoner bygger på, og ambient injeksjon av et kompakt org-sammendrag. TDD: test FØR kode. Invariant: resolver SKRIVER ALDRI; C1-scheduler må ikke knekke (fallback).

Rekkefølge:

1. Les først: hooks/scripts/session-start-context.mjs, scripts/kb-update/lib/detection-schedule.mjs (loadScheduleConfig/CONFIG_FILENAME), agents/onboarding-agent.md, ett agent-eksempel (security-assessment-agent.md:33-39), lib/atomic-write.mjs + lib/backup.mjs.
2. lib/user-data.mjs (ny, ren): resolveUserDataDir(homedir = os.homedir()) → join(homedir,'.claude','ms-ai-architect'); resolveOrgDir(homedir); resolveConfigPath(homedir); buildOrgSummary(orgFiles, {cap}) → deterministisk, lengde-kappet sammendrag (sektor, virksomhet, størrelse, reg-krav, lisens, dataklassifisering, residens, budsjett, styringsmodell). TDD: tester for resolver (homedir-injisert), summary (manglende filer, cap), FØR kode.
3. detection-schedule.mjs bakoverkompat: loadScheduleConfig leser resolveConfigPath først, fallback dagens plugin-rot. Round-trip-test: bruker-config vinner; plugin-rot brukes når bruker-config mangler.
4. session-start-context.mjs: resolve bruker-org-dir (fallback plugin org/), bygg + injiser kompakt summary (ikke bare status). Behold status-linja når org tom.
5. onboarding-agent.md: skriv org-filer til resolveOrgDir.
6. 11 agenter: «Virksomhetskontekst (automatisk)»-seksjon peker resolver-sti + ambient-note. Uniform + grep-test.
7. Subagent-injeksjon-test (risiko 1): bevis om en Task-spawnet agent ser hook-injeksjonen. Dokumentér utfall; behold fil-fallback uansett.
8. Avslutt: validate 239 + nye enhetstester + test-hooks.sh grønne · commit per logisk enhet · push (vindu 20–23 hverdag) · oppdater STATE (C2.2 neste) + denne planen (C2.1-resultater).

Ikke i C2.1: fritekst-felt (C2.2), scheduler-spørsmål i onboarding (C2.3), §167-verifisering (C2.4).

C2.1 — RESULTAT (levert, TDD test FØR kode)

• lib/user-data.mjs (NY, ren, SKRIVER ALDRI; kun node:os/path): resolveUserDataDir/resolveOrgDir/resolveConfigPath (peker ~/.claude/ms-ai-architect/, uavhengig av pluginRoot → K2), CONFIG_FILENAME (delt med C1, én sannhetskilde), ORG_FILES, buildOrgSummary(orgFiles,{cap,maxValueLen}) (generisk H2-ekstraksjon, frontmatter+H1-stripp, deterministisk ORG_FILES-rekkefølge, lengde-kapp ~25 l + per-felt-trim).
• detection-schedule.mjs bakoverkompat: loadScheduleConfig(pluginRoot, home=homedir()) leser bruker-sti FØRST, fallback plugin-rot. Lokal CONFIG_FILENAME fjernet → importeres fra resolver. Alle 3 kallere (hook, run-detection, scheduler) bruker ett-arg-kall → uendret oppførsel.
• session-start-context.mjs ambient (K1): resolver bruker-org-dir (fallback plugin org/), leser filene, injiserer buildOrgSummary som egen «Virksomhetskontekst (auto-injisert …)»-blokk. Status-nudge beholdt når org tom.
• Skriving: onboard.md (orkestrator) resolver absolutt $ORG_DIR via Bash + mkdir -p og gir agenten den; onboarding-agent.md skriver til den absolutte bruker-stien (ikke plugin-rot).
• 11 agenter: uniform «Virksomhetskontekst»-blokk → bruker-sti + note om ambient + subagent-fallback (grep-verifisert 11/11).
• Risiko 1 BEVIST: Task-spawnet subagent arver IKKE SessionStart-injeksjonen (live-probe) → agentene bæres av fallback-fil-lesing; Read/Glob ekspanderer ~ (verifisert) → bruker-sti lesbar uten Bash.
• Verifisert: user-data 16/16 · detection-schedule 23/23 (+2 round-trip) · test-hooks 10/10 (+4: K1-injeksjon + tom-org-negativ) · kb-update 191 · kb-eval 100 · validate PASSED (0/0) · kb-integrity 192/192 (220 baseline-warns) · discovery 13/13 · gitleaks 3 PRE-EKSISTERENDE (playground/vendor/). CLAUDE.md trengte ingen sti-endring (kun kommando/agent-omtale); .gitignore org/ beholdt som forsvar-i-dybden.
• Neste: C2.2 (fritekst-felt org/free-context.md → fanges av onboarding + inkluderes kappet i buildOrgSummary).

C2.2 — RESULTAT (levert, TDD test FØR kode)

Mål nådd: valgfritt fri-prosa-felt free-context.md fanges i onboarding og overflater (kappet) i det ambiente sammendraget → K3 oppfylt.

• Designvalg som avvek fra startnotatet (begrunnet): free-context.md ble IKKE lagt i ORG_FILES. ORG_FILES er doblet brukt i hooken — både fil-lesing OG fullføringskontrakt (orgComplete < ORG_FILES.length). Hadde fila blitt en sjette ORG_FILES-oppføring, ville en fullt onboardet bruker uten fritekst vist «Onboarding 5/6 — kjør for å fullføre». Løst med egen export const FREE_CONTEXT_FILE (utenfor ORG_FILES); hooken leser den uten å telle den.
• lib/user-data.mjs: FREE_CONTEXT_FILE + FREE_CONTEXT_LABEL='Fri kontekst'. collapseProse() (strip frontmatter + ALLE header-linjer + kollaps whitespace) → fri kontekst overflates som ÉTT felt uansett markdown-struktur (rå prosa, kun H1, eller H2) — fjerner stille-drop-feilmodus som ellers truet K3. capValue() ekstrahert (DRY — brukes nå av både strukturert-loop og fri-kontekst). I buildOrgSummary legges fri kontekst SIST, kappet av samme maxValueLen (160) som øvrige felt.
• session-start-context.mjs: leser FREE_CONTEXT_FILE valgfritt inn i files-mappen (ingen count++) → ambient-summary inkluderer den; fullføringstellingen uendret.
• onboarding-agent.md: ny Phase 6 (VALGFRI) — ett åpent fritekst-spørsmål; skriver free-context.md ordrett kun hvis bruker gir tekst (hopper over → ingen fil). Resume-logikk + completion-report + retningslinjer oppdatert (5 strukturerte = fullføringskontrakt; fri kontekst valgfri 6.).
• commands/onboard.md: prosess-liste (6. fri kontekst, valgfritt), Task-prompt (kjør Phase 6 hvis fila mangler), status-tabell (egen valgfri-rad; teller ikke i X/5).
• 11 agenter: uniform 6. bullet free-context.md — Fri kontekst (valgfri) … (grep 11/11).
• Kapp-tradeoff (bevisst): fri kontekst kappes til maxValueLen (160) i det ambiente teaser-et — K3 krever bare «kappet til budsjett»-synlighet, og agentene leser full fil via fallback. Egen, mer raus fri-kontekst-cap er en triviell oppfølging hvis 160 viser seg for kort i praksis (ikke gjort — unngår knott uten påvist behov).
• Verifisert: user-data 25/25 (+9 fri-kontekst) · test-hooks 11/11 (+1: K3-ambient) · kb-update 200 · kb-eval 100 · validate PASSED (239/0/0) · kb-integrity 192/192 (220 baseline-warns) · discovery 13/13 · gitleaks 3 PRE-EKSISTERENDE (playground/vendor/).
• Neste: C2.3 (os_scheduler_cadence + enabled skrives av onboarding; round-trip mot parseScheduleConfig).

C2.3 — RESULTAT (levert, TDD test FØR kode)

Mål nådd: onboarding skriver scheduled_detection:-blokka (enabled + os_scheduler_cadence) til den bruker-eide configen, og parseScheduleConfig leser den tilbake til samme verdier → K5 oppfylt (round-trip bevist deterministisk). Brukeren slipper å hånd-redigere den gitignored fila.

• Deterministisk kjerne (K5): ny serializeScheduleConfig(config) i detection-schedule.mjs — invers av parseScheduleConfig, lagt RETT VED parseren (én formatsannhet, ingen andre-parser). Skriver alle fire kjente nøkler normalisert slik coerce() leser dem, så parseScheduleConfig(serializeScheduleConfig(c)) round-tripper (daily/interval/enabled/interval_days; garbage-kadens → daily).
• Gated skrive-CLI: ny scripts/kb-update/write-schedule-config.mjs (--enabled --cadence [--home]) — MERGER på eksisterende config (parse → override KUN de to onboarding-eide nøklene → serialize), så interval_days/include_skill_lifecycle satt andre steder overlever. Pure node, Claude-fri (kun ToS-rasjonale i kommentarer, ingen invokasjon); ikke en DETECTION_STEP. Skriver til resolveConfigPath (bruker-eid).
• Gating-invariant (ufravikelig): sikkerhetskopi via ny backupFile(filePath, backupRoot) i lib/backup.mjs (presis enkeltfil-backup — drar IKKE org/ inn i backup ved hver kadens-endring, slik backupDir ville) + atomicWriteSync (aldri rå fs-write). Backup er no-op ved første skriv (ingenting å bevare); backup tas før overskriving.
• Designvalg som avvek fra plan-teksten (begrunnet): scheduler-spørsmålet ligger i orkestratoren (onboard.md), ikke i onboarding-agent.md. Agenten har kun Write (ingen Bash) og kan ikke kjøre den gatede CLI-en; orkestratoren har Bash + AskUserQuestion. Agenten fikk en note om at scheduler håndteres av orkestratoren etter intervjuet. (Speiler C2.2-mønsteret: dokumenter avviket, ikke følg plan-bokstaven når koden tilsier annet.)
• onboard.md: ny «Planlagt deteksjon»-seksjon (aktiver Ja/Nei opt-in → kadens daily/interval, daily anbefalt → gated CLI-kall + kort rapport); scheduler-rad i --status; «dekker»-liste utvidet med pkt. 7. onboarding-agent.md: note om at scheduler er orkestratorens jobb.
• Kjent begrensning (pre-eksisterende, ikke C2.3-introdusert): CLI-kallet i onboard.md bruker relativ node scripts/...-sti (antar cwd = plugin-rot), identisk konvensjon som kb-update.md. Org-/config-stiene er home-baserte (robuste).
• Verifisert: detection-schedule 33/33 (+10: serialize round-trip + writeScheduleConfig merge/backup/end-to-end) · backup-restore 15/15 (+3: backupFile) · kb-update 213 · kb-eval 100 · validate PASSED (239/0/0) · test-hooks 11/11 · kb-integrity 192/192 (220 baseline-warns) · discovery 13/13 · gitleaks 3 PRE-EKSISTERENDE (playground/vendor/).
• Neste: C2.4 (verifiser privat-sektor-paritet #4 + lukk evt. §167-residu).