Kjell Tore Guttormsen
466094f2a2
- onboard.md (orkestrator): resolver absolutt $ORG_DIR via Bash + mkdir -p, gir agenten stien. allowed-tools +Bash. Status/resume globber bruker-sti. - onboarding-agent.md: skriver de 5 org-filene til den absolutte bruker-stien (~/.claude/ms-ai-architect/org/), aldri plugin-rot. - 11 org-bevisste agenter: uniform Virksomhetskontekst-blokk -> bruker-sti + note om ambient injeksjon + subagent-fallback (grep-verifisert 11/11). Risiko 1 BEVIST: Task-subagent arver IKKE SessionStart-injeksjon; Read/Glob ekspanderer ~ -> fallback lesbar uten Bash. - README + plan: sti-referanse + C2.1-resultat. CLAUDE.md uendret (ingen sti-ref). Verifisert: validate PASSED · kb-integrity 192/192 · discovery 13/13. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
134 lines
15 KiB
Markdown
134 lines
15 KiB
Markdown
# 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`).
|