diff --git a/docs/onboarding-redesign-plan.md b/docs/onboarding-redesign-plan.md new file mode 100644 index 0000000..b659f29 --- /dev/null +++ b/docs/onboarding-redesign-plan.md @@ -0,0 +1,123 @@ +# 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).