# Phase 1: Level-Up (PF2e regelkonform) — Research

**Researched:** 2026-04-27
**Domain:** PF2e rules-correct character level-up with wizard UI, prereq DSL, recompute pipeline, atomic persistence, snapshot history, Free Archetype variant, and spellcaster progression — built on the existing NestJS 11 / React 19 / Prisma 7 / PostgreSQL stack
**Confidence:** HIGH (codebase patterns, package versions, prereq corpus all verified locally; PF2e rules cited from Archives of Nethys; Foundry pf2e schema verified against live JSON; remaining LOW items called out explicitly)

<user_constraints>
## User Constraints (from CONTEXT.md)

### Locked Decisions

**Prereq-DSL-Scope (LVL-09)**
- **D-01:** Evaluierbare Patterns: Skill-Rang (Trained/Expert/Master/Legendary in named skill), Feat-Besitz (named feat), Level, Klasse, Ancestry, Heritage. Ergibt laut Research ~80%+ Coverage gängiger Feats.
- **D-02:** Nicht-evaluierbar (→ Warnung): Deity, Spellcasting-Tradition, Multi-Class-Archetyp-Sonderfälle, Free-Text-Bedingungen wie "You worship a god of...".
- **D-03:** UI bei nicht-evaluierbarer Prereq: gelbes Warn-Icon mit Tooltip am Talent + Confirm-Dialog mit dem Voraussetzungs-Text beim "Wählen"-Klick (kein Hard-Block).
- **D-04:** Datenquelle der Prereq-Strings: bestehende `Feat.prerequisites: String?`-Spalte (existiert bereits in `server/prisma/schema.prisma:560`).
- **D-05:** Evaluator läuft im Wizard UND beim Pathbuilder-Import.
- **D-06:** Bei Import-Verletzung: Import läuft durch, Charakter wird angelegt, Banner am Charakter-Header zeigt "X Talente mit nicht erfüllter Voraussetzung". Kein Block.

**Free-Archetype-Regel (LVL-13)**
- **D-07:** Pathbuilder-Verhalten nach Dedication: Slot zeigt Talente JEDES Archetyps (Multi-Archetype erlaubt). Vor Dedication: Slot zeigt nur Dedication-Talente.
- **D-08:** Toggle-Storage: pro Charakter in den Char-Settings (einmal setzen, gilt für alle künftigen Level-Ups). Wizard-Schritt 0 zeigt eine Lese-Anzeige des Toggle-Status.
- **D-09:** Pathbuilder-Auto-Detect: FA-Toggle wird beim Import automatisch auf "aktiv" gesetzt, wenn Pathbuilder-JSON FA-Marker oder zusätzliche Class-Feat-Slots an geraden Levels enthält. Spieler kann nachträglich ändern.

**Wizard-Flow + DRAFT-Persistenz (LVL-11, LVL-12)**
- **D-10:** Step-by-Step-Modal mit dynamisch eingeblendeten Schritten (nur die für das Level relevanten). Reihenfolge: Klassenmerkmale → Boost-Set → Skill-Increase → Klassentalent → Fertigkeitstalent → Allgemein-Talent → Ancestry-Talent → FA-Slot → Spellcaster-Progression → Review. Mobile-friendly (ein Wahlpunkt pro Screen).
- **D-11:** DRAFT-Persistenz: neue Prisma-Tabelle `LevelUpSession` mit FK auf Charakter, JSON-State der Wahlen, `committedAt` nullable, optional `targetLevel`. Resume-on-Reload, Cross-Device.
- **D-12:** Live-Vorschau: nur im Review-Schritt. KEIN Live-Update pro Schritt.
- **D-13:** Permissions: Owner UND GM der Kampagne dürfen Level-Up starten. Pattern: `checkCharacterAccess` (Owner OR GM-of-campaign).
- **D-14:** Offene DRAFTs ohne Commit: bleiben unbegrenzt offen. Ein DRAFT pro Charakter (Constraint).

**Klassen+Spellcaster-Daten (LVL-08, LVL-14)**
- **D-15:** Neue Prisma-Tabelle `ClassProgression` pro `(className, level)` mit `grants: String[]`, `proficiencyChanges: Json`, `spellSlotIncrement: Json?`, `cantripIncrement: Int?`, `repertoireIncrement: Int?`, `choiceType: String?`, `choiceOptionsRef: String?`.
- **D-16:** Class-Scope v1: 16 Core+APG Klassen (Alchemist, Barbarian, Bard, Champion, Cleric, Druid, Fighter, Investigator, Monk, Oracle, Ranger, Rogue, Sorcerer, Swashbuckler, Witch, Wizard).
- **D-17:** Datenquelle für Seed: Foundry PF2e-System Repository (`https://github.com/foundryvtt/pf2e`). TS-Seed-Script (`server/prisma/seed-class-progression.ts`).
- **D-18:** Spellcaster-Repertoire-Increment (LVL-14, spontane Caster): eigener Wizard-Schritt. Slot-Increment automatisch.
- **D-19:** Wahl-Klassenmerkmale (Cleric Doctrine, Wizard School, Fighter Weapon Mastery, etc.): Wizard erkennt `choiceType` und schiebt dynamischen Sub-Schritt ein.

### Claude's Discretion
- Konkretes UI-Layout des Step-by-Step-Modals (Header, Footer-Buttons, Progress-Indicator) — fixiert in `01-UI-SPEC.md`
- Konkrete Spaltenstruktur des Review-Schritts — fixiert in `01-UI-SPEC.md`
- DRAFT-API-Endpoint-Naming — empfohlen unten in §Architecture Patterns
- JSON-Format des Snapshot-Vorher
- Genaue Error-Messages auf Deutsch
- Test-Granularität (mindestens: Boost-Cap-Logik, Skill-Increase-Cap, Prereq-Evaluator pro Pattern; integration-test für Commit-Transaktion)

### Deferred Ideas (OUT OF SCOPE — do NOT plan)
- Level-up-Historie-Ansicht im Charakterbogen (LVL-V2-01)
- Reverse-Level-Up (LVL-V2-02)
- Variant-Class-Features (Rogue Eldritch Trickster, Druid Wild Order Variants)
- Multi-Classing
- Live-Recompute-Vorschau in jedem Wizard-Schritt
- Remaster-Klassen (Magus, Summoner, Kineticist, Thaumaturge, Gunslinger, Inventor, Psychic) — v2
</user_constraints>

<phase_requirements>
## Phase Requirements

| ID | Description | Research Support |
|----|-------------|------------------|
| LVL-01 | Wizard zeigt alle level-relevanten Wahlpunkte | §Architecture Patterns (Wizard State Machine), §Standard Stack (XState v5), §UI-SPEC.md (already approved) |
| LVL-02 | Boosts L5/10/15/20: 4 Boosts, +2 unter 18, +1 ab 18 | §Standard Stack (`apply-attribute-boost.ts` pure module), §Pitfall #8 mitigation, §Validation Architecture (boost-cap unit tests) |
| LVL-03 | Klassentalent jedes geraden Levels mit Filter | §Standard Stack (PrereqEvaluator), §Code Examples (feat filter query) |
| LVL-04 | Fertigkeitstalent jedes geraden Levels mit Filter | §Standard Stack (PrereqEvaluator), §Code Examples |
| LVL-05 | Allgemein-Talent L3/7/11/15/19 (Skill-Talente erlaubt) | §Code Examples (general-or-skill filter) |
| LVL-06 | Skill-Increase L3+ mit Cap-Regel (T→E ab 3, E→M ab 7, M→L ab 15) | §Standard Stack (`skill-increase-cap.ts` pure module), §Validation Architecture |
| LVL-07 | Ancestry-Talent L5/9/13/17 mit Filter | §Standard Stack (PrereqEvaluator), §Architecture Patterns |
| LVL-08 | Klassenmerkmale automatisch aus Class-Progression-Tabelle | §Standard Stack (ClassProgression table + seed), §Code Examples (Foundry pf2e schema mapping) |
| LVL-09 | Prereq-DSL-Evaluator; nicht-evaluierbar = Warnung | §Standard Stack (PrereqEvaluator module), §Code Examples (parser grammar), §Pitfall coverage |
| LVL-10 | Auto-Recompute HP-Max, Saves, AC, Klassen-DC, Wahrnehmung | §Standard Stack (`recompute-derived-stats.ts`), §Architecture Patterns (Recompute Pipeline), §Pitfall #9 mitigation |
| LVL-11 | DRAFT-Session jederzeit abbrechbar / rückgängig vor Commit | §Standard Stack (LevelUpSession Prisma model), §Architecture Patterns (REST endpoints) |
| LVL-12 | Atomic Commit + Snapshot-Before in JSON | §Architecture Patterns (Atomic Commit Transaction), §Code Examples (Prisma `$transaction`), §Pitfall #9 mitigation |
| LVL-13 | Free-Archetype-Toggle pro Charakter | §Standard Stack (boolean field on Character), §Architecture Patterns (FA-Slot step) |
| LVL-14 | Spellcaster: Slot-/Cantrip-/Repertoire-Progression | §Standard Stack (spell-progression module), §Code Examples (Foundry classfeatures spellcasting JSON) |
| LVL-15 | Deutsche Übersetzung für Prereq-Texte und Klassenmerkmal-Beschreibungen via bestehender Translation-Pipeline | §Architecture Patterns (Translation integration), §Existing Code (TranslationsService) |
</phase_requirements>

## Project Constraints (from CLAUDE.md)

These directives from `./CLAUDE.md` are non-negotiable and the planner must verify compliance for every task:

| Constraint | How it constrains the plan |
|-----------|----------------------------|
| **TypeScript strict, keine `any`** | All new modules (`leveling/*.ts`, prereq-evaluator, recompute) must be fully typed. NestJS-eslint allows `any` (lint config disables `no-explicit-any`), but CLAUDE.md overrides — refuse `any`. |
| **Quality vor Geschwindigkeit, kein Quick-Fix** | Plan tasks for proper Prisma migrations, full unit-test coverage of pure modules, full Foundry-data-driven seed script — not stubbed-in tables. |
| **Daten in Datenbank, nichts zur Laufzeit aus JSON-Dateien** | `ClassProgression` data MUST live in Postgres after seed, never read from JSON files at runtime. |
| **Prisma `migrate dev`, niemals `db push`** | New tables get a real migration file under `server/prisma/migrations/`. |
| **Deutsche UI durchgehend, keine Emojis, nur Lucide Icons** | Already enforced in `01-UI-SPEC.md` — planner must keep all wizard copy German. |
| **Mobile-First, Touch-Targets ≥44px** | Already enforced in `01-UI-SPEC.md` (`h-11 w-11` on +/- buttons, stepper-dot wrappers). |
| **WebSocket: ein Broadcast nach Commit, nicht mehrere kleine Updates** | The new `level_up_committed` `CharacterUpdatePayload` variant is emitted exactly once at the end of the commit transaction (Pitfall #9). |
| **Test-Disziplin etabliert in dieser Phase** | First tests in the codebase ever — set the bar. Planner must include Wave-0 task to establish Jest infrastructure (it exists in `server/package.json` but has zero unit-test files alongside source). |
| **Self-hosted single-tenant — kein Multi-Tenant-Bedarf** | No Tenant scoping needed; permission model stays GM-or-Owner. |
| **Push-Plattform = Web Push, kein Native-Wrapper** | Not relevant to this phase. |

## Summary

Phase 1 builds a regelkonform PF2e Level-Up wizard on the existing Dimension47 stack (NestJS 11.0.1 + React 19.2.0 + Prisma 7.2.0 + PostgreSQL + Socket.io 4.8.3 + Tailwind v4). The implementation is six-layered: (1) two new Prisma tables — `LevelUpSession` (DRAFT JSON-state per character with a partial unique index forcing one DRAFT at a time) and `ClassProgression` (one row per `(className, level)` with grants/proficiencyChanges/spell-slot/repertoire/choiceType columns); (2) a TS seed script `server/prisma/seed-class-progression.ts` that pulls from the Foundry pf2e repo (Apache 2.0 + OGL 1.0a + Paizo Community Use Policy — verified) at build time, transforms its JSON into our schema, and remains idempotent across re-runs; (3) four pure-function modules with full Jest unit-test coverage (`apply-attribute-boost.ts`, `skill-increase-cap.ts`, `prereq-evaluator.ts`, `recompute-derived-stats.ts`); (4) a NestJS `LevelingModule` exposing four REST endpoints (POST start / PATCH state / POST commit / DELETE discard) using `prisma.$transaction([...])` for the atomic commit; (5) a React `level-up-wizard.tsx` modal already specified component-by-component in `01-UI-SPEC.md`, recommended to drive its dynamic conditional steps with **plain `useReducer` + a JSON-serializable state shape** (XState v5 is overkill for a linear wizard whose only branching is "is this step applicable at level N for this class"); (6) one new `level_up_committed` variant on `CharacterUpdatePayload` broadcast exactly once after commit.

The single highest-risk item is the **Foundry pf2e data shape**: class JSONs (`packs/classes/<class>.json`) reference compendium UUIDs (`Compendium.pf2e.classfeatures.Item.<Name>`) and the actual mechanical progressions (spell slot tables, proficiency-rank-by-level for Fighter weapon mastery, etc.) live in **separate compendium files** that the seed script must follow and join. Spell-slot progression is **not** in the class JSON — it lives in classfeatures like `wizard-spellcasting.json` and is encoded textually in the description, NOT as machine-readable rules. This means the seed script will need a small per-class hand-curated overlay of spell-slot/cantrip tables for the spontaneous + prepared casters in scope (covered in §Code Examples and §Open Questions).

The Prereq-DSL evaluator is high-confidence: a 5,625-feat corpus already lives in `server/prisma/data/featlevels.json`, of which 3,393 (60.3%) carry prereqs. A pattern audit (§Code Examples) shows pure skill-rank covers 345 feats, skill-rank-with-or/and another ~125, heritage refs 112, ancestry/instinct/cause/order/muse refs ~132, deity refs 29, age/ethnicity 11. With D-01's evaluable patterns (skill rank, feat possession, level, class, ancestry, heritage), realistic mechanical coverage is **70-80% of all feats**, with the remainder triggering the warning path (D-03). This matches the CONTEXT.md estimate.

**Primary recommendation:** Implement in five waves — Wave 0 (Jest infrastructure + Prisma migration scaffolding), Wave 1 (pure-function modules + their tests, no DB), Wave 2 (`ClassProgression` seed pipeline against Foundry data), Wave 3 (`LevelingModule` REST + atomic commit + `CharactersGateway` extension), Wave 4 (React wizard against the already-approved `01-UI-SPEC.md`). Use plain `useReducer` for wizard state — not XState — because the conditional-step logic is a pure function of `(targetLevel, characterClass, hasFA, isCaster)` and serializes trivially to JSON for DRAFT persistence.

## Architectural Responsibility Map

| Capability | Primary Tier | Secondary Tier | Rationale |
|------------|-------------|----------------|-----------|
| Prereq DSL parsing/evaluation | API / Backend | — | Evaluator runs at wizard step (server filters feat list) AND at Pathbuilder import (D-05) — must be one shared TS module. Pure function, no DB calls itself, but called from server services. |
| Level-up DRAFT persistence | Database / Storage | API / Backend | `LevelUpSession.state: Json` survives reload + cross-device (D-11). Database is the source of truth; backend exposes the CRUD on it. |
| Live recompute (HP-Max, AC, Saves, DC, Wahrnehmung) | API / Backend | — | Pure deterministic function on the server side, called inside the commit transaction. Kept off the client to prevent diff drift — Review screen renders backend-computed numbers (D-12). |
| Wizard step state (which step / which choice / draft serialization) | Browser / Client | API / Backend | Step navigation, "selected this card", "boost-counts so far" are client UI state; PATCHed up to the DRAFT row on each step transition for cross-device resume. |
| Commit atomicity | API / Backend | Database / Storage | `prisma.$transaction([...])` wraps snapshot insert + character mutations + history insert + session delete + broadcast (Pitfall #9). |
| Single broadcast `level_up_committed` | API / Backend | — | After transaction commit, the gateway emits exactly one event; client reconciles. Not the client's job to compose the event. |
| Pathbuilder-import prereq violations banner | API / Backend | Browser / Client | Server runs evaluator during import (D-05/D-06), persists violation list (proposal: `Character.prereqViolations: Json?`), client renders the banner from server data. |
| Class progression data | Database / Storage | Build/Seed | `ClassProgression` table seeded once from Foundry pf2e (D-15/D-17), read by both server (commit recompute) and indirectly via API for the wizard (the wizard only sees server-derived "what choices are available"). |
| Class-feature choice options (Cleric Doctrine, Wizard School) | Database / Storage | API / Backend | Stored in `ClassProgression.choiceOptionsRef` with the actual options seeded as part of the same pipeline. Server resolves the ref → option list when the wizard requests it. |
| Translation of new prereq + class-feature text | API / Backend | Database / Storage | Existing `TranslationsService` + `Translation` table (D-15 carry-forward) handles batch translation on demand from Claude API, cached in Postgres. No new table needed. |

## Standard Stack

### Core (already installed — no new packages)

| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
| `@nestjs/common` | 11.0.1 | LevelingModule + Controller + DTOs | Existing module-per-feature pattern — no choice |
| `@nestjs/websockets` | 11.1.12 | Extension of CharactersGateway with `level_up_committed` event type | Existing gateway pattern; event union is just expanded |
| `@prisma/client` | 7.2.0 | LevelUpSession + ClassProgression + transactional commit | Existing ORM — `$transaction([...])` directly supports atomic multi-table writes [VERIFIED: Prisma docs] |
| `class-validator` | 0.14.3 | DTO validation for the four new REST endpoints | Existing pattern in `server/src/modules/characters/dto/` |
| `class-transformer` | 0.5.1 | DTO transform | Existing pattern |
| `@nestjs/jwt` | 11.0.2 | Reuse existing JwtAuthGuard for the new endpoints | Existing pattern; no new auth surface |
| `react` | 19.2.0 | Wizard component | Existing |
| `react-dom` | 19.2.0 | — | Existing |
| `framer-motion` | 12.26.2 | Step transitions (already declared in UI-SPEC) | Already installed via UI-SPEC |
| `lucide-react` | 0.562.0 | Icons (already declared in UI-SPEC) | Existing |
| `clsx` + `tailwind-merge` | 2.1.1 / 3.4.0 | Class composition (`cn()` helper already in `client/src/shared/lib/utils.ts`) | Existing |
| `tailwindcss` | 4.1.18 | Styling | Existing |
| `@tanstack/react-query` | 5.90.19 | Wizard's REST mutations (start / patch / commit / discard) | Existing — use `useMutation` for each endpoint |
| `axios` | 1.13.2 | HTTP transport via existing `client/src/shared/lib/api.ts` | Existing |

### Supporting (already installed — for the Wave-0 test infrastructure)

| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| `jest` | 30.0.0 | Test runner for the four pure-function modules | Wave 1 — first real unit tests in this codebase [VERIFIED: `server/package.json:88-104` and `npm view jest version` → 30.3.0 latest, we are on 30.0.0 which is fine] |
| `ts-jest` | 29.x | TS compile shim for Jest | Existing in package.json (`testRegex: ".*\\.spec\\.ts$"`) |
| `@nestjs/testing` | 11.x | Test module builder for the LevelingService integration test | Existing |
| `supertest` | 7.0.0 | HTTP integration test for commit endpoint | Existing |

### Considered and rejected

| Considered | Rejected because |
|------------|------------------|
| **XState v5** (`xstate` 5.30.0 + `@xstate/react` 6.1.0 [VERIFIED: npm view 2026-04-27]) for the wizard state machine | Wizard is a linear flow with conditional step visibility. The branching is `(level, class, hasFA, isCaster) → list of steps`, computed once at start. No complex parallel states, no orthogonal regions, no nested machines. `useReducer` + a typed `WizardState` discriminated union covers it in ~80 lines, serializes natively to JSON for DRAFT persistence, and stays in the React idiom the rest of the codebase uses. XState would add ~30KB minified + a learning curve for what is fundamentally a list of steps with a cursor. **Recommend `useReducer`** — keep XState in the toolbox if a future wave proves the state space is actually graph-shaped. |
| **`zod`** (4.3.6) for runtime schema validation of the wizard JSON-state on commit | The codebase uses `class-validator` + `class-transformer` (existing convention). Adding `zod` for one feature creates two parallel validation cultures. Use class-validator decorators on the DTOs; for the in-flight wizard state inside `LevelUpSession.state`, persist it as `Json` and validate the shape in a hand-written guard function in TypeScript (the shape is fully under our control — no third-party schemas). |
| **`simple-git`** (3.36.0) inside the seed script to clone Foundry pf2e | Adds a dev dependency for a one-shot operation. Use plain `child_process.execSync('git clone ...')` or, better, instruct devs to clone the foundry repo to a known path under `server/prisma/data/foundry-pf2e/` (gitignored) and have the seed read JSONs from there. This keeps the seed script offline-capable and version-pinnable (the dev controls which Foundry tag is checked out). |
| **`p-limit`** for concurrency control inside the seed script | At ~16 classes × ~30 features each ≈ 500 file reads total, no concurrency limiting needed. Plain `await Promise.all()` over a small batch. |

**Installation:** None new. Phase 1 ships with zero new npm dependencies on either client or server.

**Version verification (HIGH confidence):** All listed versions confirmed against `client/package.json` + `server/package.json` + (where bumped) `npm view <pkg> version` on 2026-04-27. Jest 30.0.0 is current major (latest 30.3.0); XState 5.30.0 / @xstate/react 6.1.0 verified but not adopted; zod 4.3.6 verified but not adopted.

## Architecture Patterns

### System Architecture Diagram

```
                            ┌─────────────────────────────────────────┐
                            │ User on Charakter-Sheet                 │
                            │ clicks "Stufe steigen" (or "Fortsetzen")│
                            └──────────────────┬──────────────────────┘
                                               │ HTTP POST
                                               ▼
                       ┌────────────────────────────────────────────────┐
                       │ POST /characters/:id/level-up                  │
                       │ LevelUpController.startSession()               │
                       └──────────────────┬─────────────────────────────┘
                                          │
                  ┌───────────────────────▼───────────────────────────┐
                  │ LevelingService.startOrResume()                   │
                  │  • checkCharacterAccess (Owner OR GM)             │
                  │  • check level < 20                                │
                  │  • find existing OPEN LevelUpSession (one max)    │
                  │  • else create new with default state             │
                  └───────────────────────┬───────────────────────────┘
                                          │
                                          ▼
                       ┌──────────────────────────────────────────┐
                       │ LevelUpSession (DB)                       │
                       │  characterId, targetLevel, state: Json,   │
                       │  committedAt: null                        │
                       └──────────────────┬───────────────────────┘
                                          │ session returned
                                          ▼
                       ┌──────────────────────────────────────────┐
                       │ React: <LevelUpWizard sessionId=...>     │
                       │  derives step list from                   │
                       │   computeApplicableSteps(                 │
                       │     targetLevel, class, hasFA, isCaster   │
                       │   )                                       │
                       └──────────┬───────────────────────────────┘
                                  │
                ┌─────────────────┼─────────────────┐
                ▼                 ▼                 ▼
       ┌──────────────┐  ┌────────────────┐  ┌────────────────┐
       │ Step: Boost  │  │ Step: Talent   │  │ Step: Skill    │
       │ apply-       │  │ filter via     │  │ increase-cap   │
       │ attribute-   │  │ PrereqEvaluator│  │ check          │
       │ boost.ts     │  │ on Feat list   │  │                │
       └──────┬───────┘  └────────┬───────┘  └────────┬───────┘
              │                   │                   │
              └────────────────┬──┴───────────────────┘
                               │ each step: PATCH /level-up/:sessionId
                               ▼
                    ┌─────────────────────────────────────┐
                    │ LevelingService.patchState()         │
                    │  • merge partial into session.state  │
                    │  • validate guard fn                 │
                    │  • return updated session            │
                    └────────────────┬────────────────────┘
                                     │
                                     ▼
                    ┌─────────────────────────────────────┐
                    │ User reaches Review step             │
                    │ Wizard requests preview:             │
                    │  GET /level-up/:sessionId/preview    │
                    │   → recomputeDerivedStats(           │
                    │       characterSnapshot, choices,    │
                    │       progression                    │
                    │     )                                │
                    │ Vorher/Nachher rendered              │
                    └────────────────┬────────────────────┘
                                     │ user clicks "Bestätigen"
                                     ▼
                    ┌─────────────────────────────────────┐
                    │ POST /level-up/:sessionId/commit     │
                    │ LevelingService.commit()             │
                    │  prisma.$transaction([               │
                    │    1. INSERT LevelUpHistory          │
                    │       (snapshot of full character)   │
                    │    2. UPDATE Character (level, hp,   │
                    │       …)                             │
                    │    3. UPSERT CharacterAbility rows   │
                    │    4. UPSERT CharacterSkill rows     │
                    │    5. INSERT CharacterFeat rows      │
                    │    6. UPSERT CharacterResource       │
                    │       (spell slots / focus / cantrip)│
                    │    7. UPDATE LevelUpSession          │
                    │       SET committedAt = now()        │
                    │       (alt: DELETE — see §Decision)  │
                    │  ])                                  │
                    │  charactersGateway.broadcast(        │
                    │    {type:'level_up_committed',       │
                    │     data: newDerivedStats + level}   │
                    │  )                                   │
                    └─────────────────────────────────────┘
                                     │
                                     ▼
                    ┌─────────────────────────────────────┐
                    │ Other connected clients receive      │
                    │ ONE WebSocket event;                 │
                    │ react-query invalidates the          │
                    │ character query → fresh refetch.     │
                    └─────────────────────────────────────┘
```

Pathbuilder-import side-channel (D-05/D-06):
```
Pathbuilder-import.service.importCharacter()
   → after creating Character + CharacterFeat rows
   → for each CharacterFeat: load Feat.prerequisites string
   → PrereqEvaluator.evaluate(prereqString, characterContext)
       → { ok: true } | { ok: false, reason } | { unknown: true, raw }
   → collect failed (ok:false) entries
   → write Character.prereqViolations: Json (new column)
   → Banner reads this column on character-sheet load
```

### Recommended Project Structure (kebab-case files per CONVENTIONS.md)

```
server/
├── prisma/
│   ├── migrations/
│   │   └── YYYYMMDDHHMMSS_add_level_up_sessions_and_class_progression/
│   │       └── migration.sql        # raw SQL incl. partial unique index
│   ├── seed-class-progression.ts    # NEW — Foundry pf2e → ClassProgression
│   └── data/
│       └── foundry-pf2e/            # gitignored — manual git clone
│           └── packs/classes/...    # source for seed
└── src/
    ├── modules/
    │   ├── characters/
    │   │   ├── characters.gateway.ts          # EXTENDED: union type adds 'level_up_committed'
    │   │   ├── characters.service.ts          # untouched (or trivially: expose getCharacterFullSnapshot)
    │   │   └── pathbuilder-import.service.ts  # EXTENDED: PrereqEvaluator call after import
    │   └── leveling/                          # NEW MODULE
    │       ├── leveling.module.ts
    │       ├── leveling.controller.ts         # 4 REST endpoints
    │       ├── leveling.service.ts            # orchestration: start/patch/commit/discard
    │       ├── dto/
    │       │   ├── start-level-up.dto.ts
    │       │   ├── patch-level-up.dto.ts
    │       │   ├── commit-level-up.dto.ts
    │       │   └── level-up-state.dto.ts      # the in-flight JSON shape (also used in TS guards)
    │       ├── lib/                           # PURE-FUNCTION MODULES (no DI, all unit-tested)
    │       │   ├── apply-attribute-boost.ts
    │       │   ├── apply-attribute-boost.spec.ts
    │       │   ├── skill-increase-cap.ts
    │       │   ├── skill-increase-cap.spec.ts
    │       │   ├── prereq-evaluator.ts
    │       │   ├── prereq-evaluator.spec.ts
    │       │   ├── recompute-derived-stats.ts
    │       │   ├── recompute-derived-stats.spec.ts
    │       │   ├── compute-applicable-steps.ts   # used by both server + client
    │       │   └── compute-applicable-steps.spec.ts
    │       ├── feat-filter.service.ts         # uses PrereqEvaluator + Prisma
    │       └── leveling.service.spec.ts       # integration: full commit transaction

client/
└── src/
    └── features/
        └── characters/
            └── components/
                ├── character-sheet-page.tsx    # EXTENDED: add "Stufe steigen" header button + DRAFT banner mount + violations banner mount
                └── level-up/                    # NEW FOLDER (UI-SPEC §"Component File Plan")
                    ├── level-up-wizard.tsx
                    ├── level-up-step-class-features.tsx
                    ├── level-up-step-class-feature-choice.tsx
                    ├── level-up-step-boost.tsx
                    ├── level-up-step-skill-increase.tsx
                    ├── level-up-step-feat-class.tsx
                    ├── level-up-step-feat-skill.tsx
                    ├── level-up-step-feat-general.tsx
                    ├── level-up-step-feat-ancestry.tsx
                    ├── level-up-step-feat-archetype.tsx
                    ├── level-up-step-spellcaster.tsx
                    ├── level-up-step-review.tsx
                    ├── level-up-choice-card.tsx
                    ├── level-up-prereq-confirm-dialog.tsx
                    ├── level-up-resume-banner.tsx
                    ├── level-up-violations-banner.tsx
                    ├── use-level-up-session.ts        # react-query hook stack
                    └── wizard-state-reducer.ts        # plain useReducer + types
```

### Pattern 1 — Wizard State as `useReducer` + JSON-Serializable Discriminated Union

**What:** A single typed reducer drives the wizard. State is one TypeScript object, fully JSON-serializable, that maps 1:1 to `LevelUpSession.state` in the database.

**When to use:** This wizard. Conditional steps are pure functions of `(targetLevel, class, hasFA, isCaster)` computed once at start; back-navigation is index-based; Review-step revalidation is a re-walk of already-stored choices. No need for parallel/orthogonal/historical state — XState v5 would be overkill.

**Example:**
```ts
// client/src/features/characters/components/level-up/wizard-state-reducer.ts
export type StepKind =
  | 'class-features'        // auto, no input
  | 'class-feature-choice'  // dynamic per ClassProgression.choiceType
  | 'boost'                 // L5/10/15/20
  | 'skill-increase'        // L3+
  | 'feat-class'            // even levels
  | 'feat-skill'            // even levels
  | 'feat-general'          // L3/7/11/15/19
  | 'feat-ancestry'         // L5/9/13/17
  | 'feat-archetype'        // when hasFA
  | 'spellcaster'           // when isCaster (slot or repertoire)
  | 'review';

export type WizardState = {
  sessionId: string;
  targetLevel: number;
  steps: StepKind[];                      // computed once at start
  currentIdx: number;
  choices: {
    boostTargets?: ('STR'|'DEX'|'CON'|'INT'|'WIS'|'CHA')[]; // exactly 4 distinct
    skillIncrease?: { skillName: string; toRank: 'TRAINED'|'EXPERT'|'MASTER'|'LEGENDARY' };
    featClassId?: string;
    featSkillId?: string;
    featGeneralId?: string;
    featAncestryId?: string;
    featArchetypeId?: string;
    classFeatureChoices?: Record<string, string>; // choiceKey → optionId
    spellcasterRepertoirePicks?: string[];        // spell IDs for spontaneous casters
  };
  acknowledgedNonEvaluablePrereqs: string[];      // featIds the user confirmed
  revisionMode: { fromStep: number } | null;      // tracks "Ändern" → "Zurück zur Übersicht"
};

export type WizardEvent =
  | { type: 'GO_NEXT' }
  | { type: 'GO_PREV' }
  | { type: 'GO_TO_STEP'; idx: number; revisionFrom?: number }
  | { type: 'SET_BOOST_TARGETS'; targets: WizardState['choices']['boostTargets'] }
  | { type: 'SET_SKILL_INCREASE'; pick: WizardState['choices']['skillIncrease'] }
  | { type: 'SET_FEAT'; slot: 'class'|'skill'|'general'|'ancestry'|'archetype'; featId: string }
  | { type: 'SET_CLASS_FEATURE_CHOICE'; key: string; optionId: string }
  | { type: 'SET_REPERTOIRE_PICKS'; picks: string[] }
  | { type: 'ACKNOWLEDGE_PREREQ_WARNING'; featId: string }
  | { type: 'RETURN_TO_REVIEW' };       // triggers chain re-validation

export function wizardReducer(state: WizardState, ev: WizardEvent): WizardState { /* ... */ }
```
[ASSUMED: this exact shape — the planner may refine field names; structure is pure recommendation based on `01-UI-SPEC.md` requirements.]

Persistence: every reducer step that produces a "real" choice (not just navigation) triggers `useMutation(patchSession)` with the new `state.choices` slice. Navigation-only events stay client-only.

### Pattern 2 — Atomic Commit with `prisma.$transaction([...])` (Pitfall #9)

**What:** Five+ tightly-coupled mutations become one all-or-nothing operation; the `level_up_committed` broadcast happens only after the transaction returns.

**When to use:** The single commit endpoint.

**Example:**
```ts
// server/src/modules/leveling/leveling.service.ts (excerpt)
async commit(sessionId: string, userId: string) {
  const session = await this.loadSessionAndAuthorize(sessionId, userId);
  const character = await this.loadCharacterFull(session.characterId);
  const progression = await this.loadProgression(character.classId, session.targetLevel);

  // 1. Pure recompute (no DB writes yet)
  const newDerived = recomputeDerivedStats(character, session.state, progression);
  const snapshotJson = buildSnapshotJson(character);  // full character + relations subset

  // 2. Atomic transaction
  const result = await this.prisma.$transaction([
    this.prisma.levelUpHistory.create({
      data: {
        characterId: character.id,
        levelFrom: character.level,
        levelTo: session.targetLevel,
        snapshotBefore: snapshotJson,
        choices: session.state,
        committedAt: new Date(),
      },
    }),
    this.prisma.character.update({
      where: { id: character.id },
      data: {
        level: session.targetLevel,
        hpMax: newDerived.hpMax,
        // hpCurrent: NOT touched — Pitfall #9 docs the rule (HP-Max increase = new headroom, not heal)
      },
    }),
    // ...batch CharacterAbility upserts (boost targets)
    // ...batch CharacterSkill upserts (skill-increase + class-grant proficiency changes)
    // ...batch CharacterFeat creates (5 talent slots possibly + class-feature-choice picks)
    // ...batch CharacterResource upserts (spell slots, cantrips, focus)
    // ...batch CharacterSpell creates (repertoire picks for spontaneous casters)
    this.prisma.levelUpSession.update({
      where: { id: sessionId },
      data: { committedAt: new Date() },   // soft-archive (preferred) — see §Decision
    }),
  ]);

  // 3. SINGLE broadcast (Pitfall #9 + ROADMAP First-Phase Note)
  this.charactersGateway.broadcastCharacterUpdate(character.id, {
    characterId: character.id,
    type: 'level_up_committed',
    data: {
      level: session.targetLevel,
      derived: newDerived,           // hpMax, ac, classDc, perception, fortitude, reflex, will
    },
  });

  return result;
}
```

**Decision: keep committed sessions OR delete them?** Recommend **keep with `committedAt` set** (soft-archive). Reasons: (a) the partial unique index on `(characterId) WHERE committedAt IS NULL` already gives the "one DRAFT per character" constraint without deletion; (b) committed sessions are valuable audit trail (they tell you exactly which choices the user made for level N, separate from the snapshot-before in `LevelUpHistory`); (c) deletion makes the partial-index logic implicit and harder to debug. The deferred `LVL-V2-01` "Level-up Historie-Ansicht" reads exactly this kind of data.

### Pattern 3 — Pure-Function Module + Adjacent Spec File

**What:** All math (boost cap, skill increase cap, prereq evaluation, recompute) lives in `server/src/modules/leveling/lib/*.ts` with **no NestJS imports, no Prisma, no I/O**. Each has a `.spec.ts` next to it.

**When to use:** All four core logic modules in this phase. Pattern is also the cross-cutting precedent for all future phases per ROADMAP First-Phase Note.

**Example:**
```ts
// server/src/modules/leveling/lib/apply-attribute-boost.ts
export type AbilityScore = number;

/** Applies a single PF2e attribute boost. +2 if score < 18, +1 if score >= 18 (Pitfall #8). */
export function applyAttributeBoost(currentScore: AbilityScore): AbilityScore {
  return currentScore >= 18 ? currentScore + 1 : currentScore + 2;
}

/** Validates a level-up boost set: must be exactly 4 distinct abilities. */
export function isValidBoostSet(targets: readonly string[]): boolean {
  return targets.length === 4 && new Set(targets).size === 4;
}
```

```ts
// server/src/modules/leveling/lib/apply-attribute-boost.spec.ts
import { applyAttributeBoost, isValidBoostSet } from './apply-attribute-boost';

describe('applyAttributeBoost', () => {
  it('adds +2 when below 18', () => expect(applyAttributeBoost(10)).toBe(12));
  it('adds +2 when 17 (still below cap)', () => expect(applyAttributeBoost(17)).toBe(19)); // 17 → 19; the next boost would hit 20 from 19? No — at 18 the rule kicks in. Test with 17 keeps +2.
  it('adds +1 when exactly 18 (cap rule)', () => expect(applyAttributeBoost(18)).toBe(19));
  it('adds +1 when above 18', () => expect(applyAttributeBoost(20)).toBe(21));
  it('handles edge: very high (24)', () => expect(applyAttributeBoost(24)).toBe(25));
});

describe('isValidBoostSet', () => {
  it('accepts 4 distinct', () => expect(isValidBoostSet(['STR','DEX','CON','INT'])).toBe(true));
  it('rejects duplicate', () => expect(isValidBoostSet(['STR','STR','CON','INT'])).toBe(false));
  it('rejects too few', () => expect(isValidBoostSet(['STR','DEX','CON'])).toBe(false));
  it('rejects too many', () => expect(isValidBoostSet(['STR','DEX','CON','INT','WIS'])).toBe(false));
});
```

### Pattern 4 — Prereq DSL Evaluator: Parser + Evaluator + Formatter (D-01..D-04)

**What:** Three layers in one file (`prereq-evaluator.ts`), each independently testable.

**Grammar (concrete from real corpus — see §Code Examples for the audit):**
```
PREREQUISITE   := CLAUSE ( ';' CLAUSE )*       // semicolon = AND
CLAUSE         := DISJUNCT ( ',' DISJUNCT )* | DISJUNCT
DISJUNCT       := ATOM ( ' or ' ATOM )*        // 'or' = OR; comma usually = AND inside a clause; case "comma-separated alternatives" handled by heuristic
ATOM           := SKILL_RANK | FEAT_REF | LEVEL_REF | CLASS_REF | ANCESTRY_REF | HERITAGE_REF | UNKNOWN
SKILL_RANK     := /(trained|expert|master|legendary) in (.+?)/i
FEAT_REF       := /(?:^|; )([A-Z][a-zA-Z' ]+)$/   // bare capitalized phrase, looked up in Feat table
LEVEL_REF      := /level (\d+)/i
CLASS_REF      := one of {Alchemist, Barbarian, … (16 classes)}
ANCESTRY_REF   := one of {Human, Elf, Dwarf, … (51 ancestries)}
HERITAGE_REF   := /(.+?) heritage/i
UNKNOWN        := anything else → returns { unknown: true, raw }
```

The parser produces a tree; the evaluator walks it against `CharacterContext = { level, classId, ancestryId, heritageId, abilities, skills: Map<string,Proficiency>, feats: Set<featId> }`. The formatter produces a German human-readable reason string for the warning UI (D-03).

**Example (excerpt):**
```ts
export type EvalResult =
  | { ok: true }
  | { ok: false; reason: string }                  // evaluable AND fails
  | { unknown: true; raw: string };                // not evaluable → triggers warning (D-03)

export function evaluatePrereq(prereqString: string | null, ctx: CharacterContext): EvalResult {
  if (!prereqString) return { ok: true };
  const tree = parsePrereq(prereqString);
  if (tree.kind === 'unknown') return { unknown: true, raw: prereqString };
  return evaluateTree(tree, ctx);
}
```

Evaluator returns `{ unknown: true, ... }` aggressively — when ANY atom is non-classifiable (e.g. "follower of Asmodeus", "spontaneous spellcaster"), the entire clause is marked unknown (kein Hard-Block per D-03). This is conservative and matches D-03's intent: when in doubt, ask the user.

### Pattern 5 — Recompute Derived Stats: Pure Pipeline

**What:** A pure function `recomputeDerivedStats(character, choices, progression) → DerivedStats` that the commit transaction calls AND the Review-step preview endpoint calls.

**Inputs:**
- Full Character snapshot (level, ancestry, class, abilities, skills, feats, hpCurrent, hpTemp)
- The wizard's `choices` (boost targets, skill-increase pick, etc.) — to know what's about to change
- ClassProgression row for `(className, targetLevel)` — for proficiency increases granted at this level

**Outputs:**
```ts
type DerivedStats = {
  level: number;
  hpMax: number;          // recomputed: ancestryHP + (classHP + conMod) × level + bonusPerLevel × level
  ac: number;             // 10 + dexCap-clamped DEX-mod + armor.ac + proficiencyBonus(armor)
  classDc: number;        // 10 + keyAbility-mod + proficiencyBonus(class) — class-specific
  perception: number;     // wisMod + proficiencyBonus(perception)
  fortitude: number;      // conMod + proficiencyBonus(fort)
  reflex: number;         // dexMod + proficiencyBonus(ref)
  will: number;           // wisMod + proficiencyBonus(will)
};
```

**Boost-cap-at-18 enforcement** (Pitfall #8): the new ability scores are computed in this same module BEFORE the derived stats — `applyAttributeBoost()` is called per-target. The whole pipeline is one composition; Vorher-Nachher numbers in Review come from the same code path that the commit will write.

### Pattern 6 — Pathbuilder Auto-Detect for Free Archetype (D-09)

**Heuristic:** Pathbuilder JSON does not have an explicit `freeArchetype: true` flag in the typical export. The reliable signals are:

1. **Extra Class-Feat-Slot count.** Pathbuilder export (`build.feats`) contains feat entries tagged with their feat-type. If the count of `Class`-typed feats at any even level is 2 or more, OR if any feat is tagged `Archetype` at a level where the character would not otherwise have a class-feat slot for it, treat FA as active.
2. **Presence of any Archetype feat.** Any feat with feat-type `Archetype` and level > 1 is a strong indicator (without FA, the character would have spent their normal class-feat-slot for it — possible but suspicious if there are also full class feats at every even level).

Recommend the heuristic: `auto-detect FA = true if (count of Archetype-typed feats >= 2) OR (any even level has 2+ Class-or-Archetype feats)`. Set `Character.freeArchetype: true` on auto-detect; expose the toggle in character settings so the player can flip it.

**[ASSUMED: heuristic specifics — based on common Pathbuilder export shape; verify against an actual FA-enabled character export before locking. If the user has even one FA-enabled character on hand, run the seed script's auto-detect against it during Wave 0 verification.]**

### Anti-Patterns to Avoid

- **Live recompute on every wizard step.** D-12 explicitly forbids this. Recompute runs ONCE at the Review step and ONCE at commit. Keeps the wizard cheap, avoids per-PATCH transaction load, and prevents Review numbers from drifting from commit numbers.
- **Computing prereqs client-side.** The PrereqEvaluator runs on the server inside the feat-list endpoint that the wizard hits per step. Reasoning: (a) keeps the evaluator behind the auth boundary; (b) client never needs the full Feat table; (c) D-05 mandates the same evaluator runs at Pathbuilder import (server-only context); centralizing avoids two implementations that drift.
- **Putting `level_up_committed` data into multiple small broadcasts.** ROADMAP First-Phase Note pins this — single broadcast after transaction returns. Compose the full DerivedStats payload, emit once.
- **`db push` for the new tables.** CLAUDE.md and PROJECT.md explicitly forbid; use `prisma migrate dev` to author a real migration file.
- **`any` types in the wizard reducer or in the prereq evaluator.** TypeScript strict required (CLAUDE.md). The reducer's `WizardEvent` union and the evaluator's `EvalResult` union must be discriminated unions.
- **Reading Foundry pf2e JSON files at runtime.** D-15/D-17 mandate seed-time only. The runtime reads from `ClassProgression` rows.
- **Auto-removing dependent feats on retrain (Pitfall #10).** Out of scope for this phase — Reverse-Level-Up is `LVL-V2-02` deferred. But the schema still needs to allow it later: `LevelUpHistory` is append-only.

## Don't Hand-Roll

| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| Atomic multi-table commit | A try/catch sequence of `await prisma.x.update(...)` | `prisma.$transaction([...])` array form | Prisma transactions roll back ALL writes on any failure; the manual sequence cannot guarantee consistency on partial-failure (Pitfall #9). [VERIFIED: Prisma 7 `$transaction([...])` is the same array-form supported since v2.] |
| One-DRAFT-per-character constraint | Application-level "first delete then insert" inside the start endpoint | A **partial unique index in the migration SQL** (`CREATE UNIQUE INDEX … WHERE committedAt IS NULL`) | Race-condition safe; enforced at DB level; the start-endpoint's "find or create" stays simple. Prisma schema cannot express partial indexes — must be raw SQL in the migration file. [VERIFIED: Prisma 7 docs do not list partial unique indexes as expressible via `@@unique`; raw SQL migration is the documented workaround.] |
| Step-validity logic at every step | A growing `if-else` cascade in `level-up-wizard.tsx` | `computeApplicableSteps(targetLevel, class, hasFA, isCaster): StepKind[]` — pure function, unit-tested | One source of truth for "which steps are visible at level N for class X with FA flag" — also lets the server reject patches to non-applicable steps. |
| Class progression tables as TypeScript constants | A 1500-line `class-progression-data.ts` | The `ClassProgression` Prisma table seeded from Foundry pf2e | Self-correcting (re-run the seed when Foundry updates); keeps mechanical data out of source files (CLAUDE.md philosophy: "Daten in Datenbank"); searchable; enables the planner-deferred `LVL-V2-01` history view to JOIN against it cleanly. |
| Spell-slot progression formulas hand-coded per class | `if (className === 'Wizard' && level >= 3) slots[1]++; …` | A small **per-caster overlay table** (also in seed script) since Foundry classfeatures encode slot tables in description text not machine-readable rules | The Foundry data is machine-readable for class-feature *grants* but **not** for slot tables — those live in description prose. A hand-curated overlay (10-12 prepared casters + spontaneous casters) is the honest answer. See §Open Questions Q1. |
| Pathbuilder FA-detection regex over the raw JSON | Ad-hoc `JSON.stringify(build).includes('FA')` | Structured count of `feat-type === 'Archetype'` entries in `build.feats` | Pathbuilder export is structured array-of-feat-tuples (verified in `pathbuilder-import.service.ts:248-272`); query the structure, not the string. |
| Date-relative "vor 3 Tagen" formatting in the resume banner | Hand-built switch statement | Existing project pattern — likely already a util, otherwise `Intl.RelativeTimeFormat` (zero-dependency, native) | Native `Intl` is German-aware; avoids `date-fns` or `dayjs` for one usage. |

**Key insight:** Every "data table" in this phase has a public source (Foundry pf2e). Hand-rolling them = (a) goes stale, (b) burns dev time, (c) violates the "Daten in Datenbank" principle. Conversely, every "math" function in this phase is short, deterministic, and should be hand-rolled with full unit-test coverage — these are the bug surfaces (boost cap, skill cap, recompute, prereq grammar).

## Common Pitfalls

### Pitfall 1: Boost-cap-at-18 silently corrupts ability scores (PITFALLS.md #8)

**What goes wrong:** STR 18 + boost = 20, not the correct 19. Character is permanently overpowered. Bug spreads to HP, AC, attacks, saves, DC.

**Why it happens:** Devs write `score + 2` everywhere, miss the +1-above-18 rule.

**How to avoid:** Centralize in `applyAttributeBoost(current): number` — the only function in the codebase that increments an ability score. Recompute calls it. Boost-step UI's "wird {newScore}" preview calls it. Unit-tested with edge cases at 17, 18, 19, 24.

**Warning signs:** Any character with ability > 18 at level 5; commit-time integration test should fail loudly.

### Pitfall 2: Recompute side effects mutate `hpCurrent` (PITFALLS.md #9)

**What goes wrong:** Player at 12/40 HP. CON-boost recomputes HP-Max to 50. Code accidentally sets `hpCurrent = 50` ("you healed!"). Or worse: a future Reverse-Level-Up drops `hpMax` below `hpCurrent` and silently underflows.

**Why it happens:** Devs reach for `hpCurrent = hpMax` or `Math.min(hpCurrent, hpMax)` reflexively.

**How to avoid:** Document and enforce: **commit transaction NEVER touches `hpCurrent`**. New HP-Max is new headroom; player heals through normal HP rules later. The `prisma.character.update` call writes only `level`, `hpMax`, and other strictly-derived fields. Add a unit test that asserts `hpCurrent` is absent from the update payload.

**Warning signs:** Player's HP fully refilled after Level-Up.

### Pitfall 3: Skill-Increase History gets lost (PITFALLS.md #11)

**What goes wrong:** Future Reverse-Level-Up cannot know which skill was the level-15 increase if the only stored value is `final proficiency = MASTER`.

**How to avoid:** The wizard's `choices.skillIncrease` is captured in `LevelUpHistory.choices` JSON for every level. The `committedAt` LevelUpSession also retains the choice. So at history time, you can reconstruct: walk all `LevelUpHistory` rows for the character in level order, replay each `choices.skillIncrease` to derive "at level N, skill X went from rank A to B". This phase doesn't build the Reverse feature, but it **must persist enough data** for the future to reconstruct it.

**Warning signs:** N/A this phase — this is a forward-compatibility check on the schema.

### Pitfall 4: Feat retrain orphans (PITFALLS.md #10)

**What goes wrong:** A feat depends on another feat as prereq; if the prereq feat is removed (Reverse-Level-Up), the dependent feat now violates its prereq invisibly.

**Status this phase:** Reverse-Level-Up is deferred (LVL-V2-02). For Phase 1, this is **purely a forward-compat concern** — schema must allow Pitfall #10's solution later. Specifically: the `Character.prereqViolations: Json?` column we add for D-06 (import banner) is **the same column** Reverse-Level-Up will use to surface orphan feats post-retrain. Build it once, use it twice.

### Pitfall 5: Foundry pf2e data shape changes between checkouts

**What goes wrong:** Seed script written against `pf2e@7.x.0` breaks against `pf2e@8.0.0` because Foundry restructures `system.classFeatLevels.value` into something else.

**How to avoid:** Pin a specific Foundry pf2e tag in the seed script's README; the script fails loudly with "expected key X not found" if shape drifts; rerun the seed against a new tag explicitly. Don't auto-track HEAD.

**Warning signs:** Seed script silently produces empty `ClassProgression` rows.

### Pitfall 6: Spell-slot progression encoded in description prose, not rules

**What goes wrong:** Seed script tries to extract spell-slot progression from `wizard-spellcasting.json` and finds only narrative text ("you can prepare X spells of grade Y at level Z…"). [VERIFIED: WebFetch of `wizard-spellcasting.json` confirms `rules` array does NOT contain slot increments.]

**How to avoid:** Hand-curate a small `spell-slot-progression.ts` overlay with the canonical PF2e tables for each of the 16 in-scope classes that cast. Don't try to NLP-parse prose. The overlay is small (≤20 rows × 16 classes ≈ 320 lines) and stable (PF2e doesn't change slot tables between printings).

**Warning signs:** Spellcaster level-ups produce zero new slots in tests.

### Pitfall 7: Per-event JWT validation overload (PITFALLS.md #17)

**What goes wrong:** N/A this phase — the new endpoints are REST (one auth check per HTTP request), and the `level_up_committed` event is a server-emitted broadcast (no inbound socket message handler).

**Status:** No exposure here; called out only because the cross-cutting WebSocket discipline applies to future phases.

### Pitfall 8: Cascading deletes wipe history (PITFALLS.md #16)

**What goes wrong:** `LevelUpHistory` with `onDelete: Cascade` would lose all history when a character is deleted.

**How to avoid:** Decision per relation:
- `LevelUpSession → Character`: `onDelete: Cascade` — DRAFT is meaningless without character.
- `LevelUpHistory → Character`: `onDelete: Cascade` (acceptable — character deletion is destructive in this self-hosted-single-group app; no soft-delete pattern exists for Character today). Document this in the migration SQL comment.
- `ClassProgression`: no FK to Character — independent reference table.

## Code Examples

Verified patterns from official sources and the existing codebase.

### Example 1 — Foundry pf2e Class JSON Shape

[VERIFIED: WebFetch `https://raw.githubusercontent.com/foundryvtt/pf2e/master/packs/classes/fighter.json` 2026-04-27]

```jsonc
// packs/classes/fighter.json — top-level
{
  "_id": "...",
  "name": "Fighter",
  "type": "class",
  "system": {
    "hp": 10,
    "perception": 2,                 // Proficiency rank (0=untrained, 1=trained, 2=expert, …)
    "keyAbility": ["dex", "str"],
    "spellcasting": 0,
    "attacks": { "simple": 2, "martial": 2, "advanced": 1, "unarmed": 2, "other": { "rank": 0, "name": "" } },
    "defenses": { "light": 1, "medium": 1, "heavy": 1, "unarmored": 1 },
    "savingThrows": { "fortitude": 2, "reflex": 2, "will": 1 },
    "trainedSkills": { "value": [], "additional": 3 },
    "classFeatLevels":   { "value": [1, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20] },
    "ancestryFeatLevels":{ "value": [1, 5, 9, 13, 17] },
    "skillFeatLevels":   { "value": [2, 4, 6, 8, 10, 12, 14, 16, 18, 20] },
    "generalFeatLevels": { "value": [3, 7, 11, 15, 19] },
    "items": {
      "u8k07": {
        "img": "...",
        "level": 5,
        "name": "Fighter Weapon Mastery",
        "uuid": "Compendium.pf2e.classfeatures.Item.Fighter Weapon Mastery"
      }
      // … more keyed by random ID, each with level + uuid
    }
  }
}
```

**Mapping to our `ClassProgression` schema:**
- One row per `(className, level)` for level 1..20.
- `grants: String[]` ← collect all `items.<id>` entries with that level → use the bare name (`"Fighter Weapon Mastery"`).
- `proficiencyChanges: Json` ← the seed script must consult **classfeatures compendium files** (not the class JSON) for level-gated proficiency bumps (e.g., Fighter's "Weapon Mastery" at L5 grants martial→Master). For simple grants where Foundry doesn't carry mechanical proficiency data, the seed script applies a hand-curated overlay (one map per class) — see Pitfall #6.
- `spellSlotIncrement / cantripIncrement / repertoireIncrement` ← from a hand-curated per-class overlay (the Foundry classfeature for spellcasting carries this data only as prose; verified for Wizard).
- `choiceType: String?` ← presence indicator, e.g. `"doctrine"` for Cleric L1, `"school"` for Wizard L1, `"weapon-mastery-group"` for Fighter L5.
- `choiceOptionsRef: String?` ← lookup key into a small seed-time options table.

### Example 2 — Real Prereq Strings (from `server/prisma/data/featlevels.json`, audited 2026-04-27)

**Audit:** 5,625 feats total, 3,393 (60.3%) have non-empty prereqs.

**Sub-classification of the 3,393 feats with prereqs:**

| Pattern | Count | Sample | D-01 Evaluable? |
|---------|-------|--------|-----------------|
| Pure single-skill rank: `^(Trained\|Expert\|Master\|Legendary) in [Skill]$` | 345 | `"Trained in Acrobatics"` | YES — direct table lookup |
| Skill-rank composite (or/and via comma): `Trained in X, Y, or Z` / `expert in a skill with the Recall Knowledge action` | 125 | `"Trained in Arcana, Trained in Nature, Trained in Occultism, or Trained in Religion"` | YES (the disjunctive forms; the "skill with Recall Knowledge action" form is UNKNOWN — too semantic) |
| Heritage refs: `^… heritage` / `… heritage or … heritage` | 112 | `"Unbreakable Goblin heritage"` | YES — heritage is on Character.heritageId |
| Class-feature subchoice (instinct/cause/order/muse/bloodline/doctrine/school) | 132 | `"animal order"`, `"enigma muse"`, `"flame order"`, `"grandeur cause"` | PARTIAL — evaluable IFF we persist class-feature-choice picks from D-19 commit-time. Phase 1 should persist these in `CharacterFeat` (with `source: CLASS`) so the evaluator can find them via name-match. |
| Spellcasting / cantrip refs: `spellcasting class feature`, `spellcaster`, `divine spells`, `cantrip` | 65 | `"spellcasting class feature"`, `"bloodline that grants divine spells; you follow a deity"` | NO — D-02 explicitly defers these to UNKNOWN/warning |
| Class with brackets `[Druid] animal order` | 4 | `"[Druid] animal order"` | YES — strip brackets, treat as class-then-subchoice |
| Deity refs: `worship`, `follower of`, `deity` | 29 | `"worshipper of Droskar"`, `"deity with a simple… favored weapon"` | NO — D-02 |
| Age / ethnicity: `at least 100 years old`, `Tian-Dan ethnicity` | 11 | `"at least 100 years old"`, `"Nidalese ethnicity"` | NO — these aren't tracked on Character |
| Vision / sense traits: `low-light vision`, `darkvision`, `scent` | 11 | `"low-light vision"` | PARTIAL — heritage often grants these; for now mark UNKNOWN |
| Multi-clause (semicolon AND): `Trained in Deception; Trained in Stealth`, `Charisma +2; Strength +2` | 637 | `"Champion Dedication: Charisma +2; Strength +2"` (note: "Charisma +2" is an ability minimum which the evaluator should support — see grammar above) | MOSTLY YES — semicolon = AND combinator, walk both sides |
| Multi-clause (comma alternation): `Trained in Lore, Mountain Lore` | 123 | varies | PARTIAL — comma is ambiguous (sometimes AND, sometimes OR-list). Recommend: comma inside a "Trained in X, Y, or Z" pattern is OR-list; comma between full atoms is AND. |
| Bare feat ref (single capitalized phrase): `"Fascinating Performance"`, `"Power Attack"`, `"Base Kinesis"` | ~150 | `"Fascinating Performance"` | YES — Feat-name lookup against `Feat` table; if found, check `CharacterFeat` |

**Estimated evaluable coverage:** ~70-80% of the 3,393 prereqed feats produce `{ ok: true | ok: false }`. The remainder (deity/spellcasting/ethnicity/age/vision/semantic-skill refs) produce `{ unknown: true }` and trigger D-03's warning UI — exactly the design.

### Example 3 — Prisma schema additions (proposed for the migration SQL)

```prisma
// server/prisma/schema.prisma — APPENDED, not modifying existing models

model LevelUpSession {
  id            String    @id @default(uuid())
  characterId   String
  targetLevel   Int       // currentLevel + 1, captured at start so server can validate
  state         Json      @default("{}")
  committedAt   DateTime?
  createdAt     DateTime  @default(now())
  updatedAt     DateTime  @updatedAt

  character Character @relation(fields: [characterId], references: [id], onDelete: Cascade)

  @@index([characterId])
  // Partial unique index added in raw migration SQL:
  //   CREATE UNIQUE INDEX "LevelUpSession_oneDraftPerCharacter"
  //     ON "LevelUpSession"("characterId") WHERE "committedAt" IS NULL;
}

model LevelUpHistory {
  id              String   @id @default(uuid())
  characterId     String
  levelFrom       Int
  levelTo         Int
  snapshotBefore  Json     // full character + relations subset captured at commit
  choices         Json     // the wizard state.choices at commit
  committedAt     DateTime @default(now())

  character Character @relation(fields: [characterId], references: [id], onDelete: Cascade)

  @@index([characterId, committedAt(sort: Desc)])
}

model ClassProgression {
  id                   String   @id @default(uuid())
  className            String   // "Fighter", "Wizard", … one of the 16 D-16 names
  level                Int      // 1..20
  grants               String[] // e.g. ["Bravery", "WeaponSpecialization"] — feature names
  proficiencyChanges   Json     // { fortitude: "EXPERT", reflex: "EXPERT", … } at THIS level
  spellSlotIncrement   Json?    // { tradition: "ARCANE", level: 3, count: 1 } per slot bumped
  cantripIncrement     Int?     // count of new cantrips at this level (rare past L1)
  repertoireIncrement  Int?     // count of new repertoire spells (spontaneous casters)
  choiceType           String?  // "doctrine" | "school" | "weapon-mastery" | null
  choiceOptionsRef     String?  // key into ClassFeatureOptions seed table

  @@unique([className, level])
  @@index([className])
}

model ClassFeatureOption {
  id            String  @id @default(uuid())
  optionsRef    String  // matches ClassProgression.choiceOptionsRef
  optionKey     String  // e.g. "destruction-doctrine"
  name          String
  nameGerman    String?
  description   String  // English; German via TranslationsService at runtime
  // Mechanical effect application is hand-coded per choiceType in commit-time recompute.

  @@unique([optionsRef, optionKey])
  @@index([optionsRef])
}

// On Character — APPENDED fields
model Character {
  // ... existing fields unchanged ...
  freeArchetype     Boolean  @default(false)   // D-08
  prereqViolations  Json?                      // D-06 — { violations: [{featId, featName, prereqText}] }
  // levelUpSessions and histories are reverse relations:
  levelUpSessions   LevelUpSession[]
  levelUpHistories  LevelUpHistory[]
}
```

### Example 4 — REST endpoint shape (D-13 access pattern follows existing `checkCharacterAccess`)

```ts
// server/src/modules/leveling/leveling.controller.ts (proposed)
@Controller()
@UseGuards(JwtAuthGuard)
export class LevelingController {
  constructor(private leveling: LevelingService) {}

  @Post('characters/:characterId/level-up')
  start(@Param('characterId') characterId: string, @Req() req: AuthRequest) {
    return this.leveling.startOrResume(characterId, req.user.id);
  }

  @Patch('level-up/:sessionId')
  patch(@Param('sessionId') sessionId: string, @Body() dto: PatchLevelUpDto, @Req() req: AuthRequest) {
    return this.leveling.patchState(sessionId, req.user.id, dto);
  }

  @Get('level-up/:sessionId/preview')
  preview(@Param('sessionId') sessionId: string, @Req() req: AuthRequest) {
    return this.leveling.computePreview(sessionId, req.user.id);
  }

  @Post('level-up/:sessionId/commit')
  commit(@Param('sessionId') sessionId: string, @Req() req: AuthRequest) {
    return this.leveling.commit(sessionId, req.user.id);
  }

  @Delete('level-up/:sessionId')
  discard(@Param('sessionId') sessionId: string, @Req() req: AuthRequest) {
    return this.leveling.discard(sessionId, req.user.id);
  }
}
```

Each method ultimately calls into `CharactersService.checkCharacterAccess(characterId, userId, requireOwnership=false)` — but with the requirement loosened: D-13 says GM-of-campaign also can level-up. `checkCharacterAccess` already permits GM by passing `requireOwnership=true` (yes — re-reading lines 73-78 of `characters.service.ts`: when `requireOwnership=true` it allows `isOwner || isGM`). So `requireOwnership: true` is the right call here — it semantically means "owner-or-GM" in this codebase.

### Example 5 — `level_up_committed` payload shape

```ts
// server/src/modules/characters/characters.gateway.ts:24 — UPDATE the union type:
export interface CharacterUpdatePayload {
  characterId: string;
  type: 'hp' | 'conditions' | 'item' | 'inventory' | 'money' | 'level' | 'equipment_status'
      | 'rest' | 'alchemy_vials' | 'alchemy_formulas' | 'alchemy_prepared' | 'alchemy_state'
      | 'dying'
      | 'level_up_committed';                          // NEW
  data: any;                                           // (existing — keep until typed-event refactor in a future phase)
}

// Payload for type='level_up_committed':
type LevelUpCommittedData = {
  level: number;                                       // new level
  derived: {
    hpMax: number;
    ac: number;
    classDc: number;
    perception: number;
    fortitude: number;
    reflex: number;
    will: number;
  };
  // Intentionally NOT including the full character — clients react-query-invalidate the character query
  // and refetch via REST. WebSocket payload stays small; full state stays canonical via REST. (Pitfall #15 mitigation)
};
```

The client's `use-character-socket.ts` adds an `onLevelUpCommitted` callback that calls `queryClient.invalidateQueries(['character', characterId])`.

### Example 6 — Spell-slot overlay (proposed shape for the seed script)

```ts
// server/prisma/data/spell-slot-overlays.ts — hand-curated, in source control
// Each entry says: at THIS level, this caster gains THIS many slots of THIS grade.
export const SPELL_SLOT_OVERLAY: Record<string, Array<{
  level: number;
  spellSlotIncrement?: { tradition: SpellTradition; spellLevel: number; count: number };
  cantripIncrement?: number;
  repertoireIncrement?: number;
}>> = {
  Wizard: [
    { level: 1, cantripIncrement: 5 },                                                  // L1: 5 cantrips
    { level: 1, spellSlotIncrement: { tradition: 'ARCANE', spellLevel: 1, count: 2 } }, // L1: 2 grade-1 slots
    { level: 2, spellSlotIncrement: { tradition: 'ARCANE', spellLevel: 1, count: 1 } }, // L2: +1 grade-1 (3 total)
    { level: 3, spellSlotIncrement: { tradition: 'ARCANE', spellLevel: 2, count: 2 } },
    // … through L20 from the canonical PF2e table
  ],
  Sorcerer: [
    { level: 1, cantripIncrement: 5 },
    { level: 1, spellSlotIncrement: { tradition: 'ARCANE'/* or set per bloodline */, spellLevel: 1, count: 3 } },
    { level: 2, spellSlotIncrement: { tradition: 'ARCANE', spellLevel: 1, count: 1 } },
    // … and Sorcerer-specific repertoireIncrement
    { level: 3, repertoireIncrement: 1 },
    // …
  ],
  // … 12-14 more casters from D-16 scope
};
```

The seed script merges this overlay into `ClassProgression` rows. Splitting it out keeps the Foundry-derived seed (mostly grant + choice info) separate from the hand-curated table data.

## State of the Art

| Old approach | Current approach | When changed | Impact |
|--------------|------------------|--------------|--------|
| Per-event JWT decode in WebSocket handlers | Decode once on connect, cache `socket.data.userId` | Already in Dimension47 (`characters.gateway.ts:71-86`) | Already standard — no change needed |
| Hand-coded class progression in TS constants | DB-backed `ClassProgression` table seeded from canonical source (Foundry pf2e) | Adopted in this phase | Aligns with CLAUDE.md's "Daten in Datenbank" |
| `db push` for development | `prisma migrate dev` — real migration files | CLAUDE.md enforced from project start | No exception this phase |
| Free-text feat prerequisites (just text in the description) | Dedicated `Feat.prerequisites: String?` column with structured DSL evaluator | Already half-built — column exists at `schema.prisma:560`; this phase adds the evaluator | First time the column has a consumer |
| XState for every multi-step UI | `useReducer` for linear-with-conditional flows; XState only for genuinely graph-shaped state | This phase | Pragmatic — XState v5 (5.30.0) is excellent but not earned by this phase's complexity |

**Deprecated/outdated:**
- Reading PF2e data from `client/public/*.json` at runtime (per CLAUDE.md "nicht direkt aus JSON-Dateien"). Already the rule; the new ClassProgression tables follow it.

## Assumptions Log

| # | Claim | Section | Risk if Wrong |
|---|-------|---------|---------------|
| A1 | Pathbuilder FA auto-detect heuristic (count of Archetype-typed feats ≥ 2) reliably indicates FA was active | §Pattern 6 | Auto-detect may misfire on characters who legitimately took an Archetype Dedication via their normal class-feat slot. Mitigation: D-09 already specifies "Spieler kann nachträglich ändern" — the toggle is editable in character settings. False-positive cost is low. |
| A2 | The `WizardState` reducer shape proposed in §Pattern 1 maps cleanly to the JSON-state column | §Pattern 1 | If the planner wants finer granularity (e.g. per-step validation timestamps), the shape needs extending. Extensible — Json column accepts any shape. |
| A3 | The hand-curated `SPELL_SLOT_OVERLAY` covers all 16 D-16 classes correctly | §Code Examples #6 | Sourcing from Archives of Nethys per-class tables; one wrong row = wrong slot count for affected class. Mitigation: unit test `recompute-derived-stats.spec.ts` exercises slot increments per class+level; planner should curate against the official Player Core / APG tables. |
| A4 | Foundry pf2e Apache 2.0 + OGL 1.0a + Paizo CUP allows re-shipping a derived `ClassProgression` table for self-hosted use by our group | §Standard Stack, §Code Examples #1 | Self-hosted single-tenant use for our own group is the textbook Paizo CUP scenario. If the project ever shifts to public SaaS, re-evaluate. |
| A5 | The "comma vs semicolon" disambiguation rule for prereq parsing (semicolon = AND, comma inside `Trained in X, Y, or Z` = OR-list, comma elsewhere = AND) is correct for the corpus | §Pattern 4, §Code Examples #2 | Corpus audit suggests these heuristics; some edge cases will resolve differently. Mitigation: log every UNKNOWN result and review the first ~50 in production. |
| A6 | Class-feature subchoice references in prereqs (`enigma muse`, `flame order`) become evaluable once we persist them as `CharacterFeat` rows with the option name | §Code Examples #2 (Sub-classification) | If the class-feature commit path stores these differently (e.g. as a column on `CharacterAlchemyState.researchField`), the evaluator must look in multiple places. The planner should standardize: every class-feature choice produces a `CharacterFeat` row whose `name` is the option name. |

## Validation Architecture

### Test Framework
| Property | Value |
|----------|-------|
| Framework | Jest 30.0.0 + ts-jest (server only — `server/package.json:88-104`) [VERIFIED: `npm view jest version` → 30.3.0; we are on 30.0.0 = compatible] |
| Config file | inline in `server/package.json` — `testRegex: ".*\\.spec\\.ts$"`, `rootDir: "src"` |
| Quick run command | `cd server && npm test -- --testPathPattern=leveling` |
| Full suite command | `cd server && npm test` |

**Client test framework:** None today (TESTING.md confirms zero coverage). Phase 1 deliberately does NOT introduce vitest on the client — that is a Phase-2/3 cross-cutting decision. Wizard UI is verified manually + via the integration test that exercises the full commit path through the API.

### Phase Requirements → Test Map

| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|--------|----------|-----------|-------------------|-------------|
| LVL-02 | `applyAttributeBoost(17) = 19` | unit | `npm test -- apply-attribute-boost.spec.ts` | ❌ Wave 1 |
| LVL-02 | `applyAttributeBoost(18) = 19` (cap) | unit | same | ❌ Wave 1 |
| LVL-02 | `applyAttributeBoost(20) = 21` (above cap) | unit | same | ❌ Wave 1 |
| LVL-02 | `isValidBoostSet(['STR','STR','CON','INT']) = false` | unit | same | ❌ Wave 1 |
| LVL-02 | `isValidBoostSet(['STR','DEX','CON','INT']) = true` | unit | same | ❌ Wave 1 |
| LVL-06 | `canIncreaseSkill(currentRank='TRAINED', characterLevel=2) = false` (T→E only at L3+) | unit | `npm test -- skill-increase-cap.spec.ts` | ❌ Wave 1 |
| LVL-06 | `canIncreaseSkill('TRAINED', 3) = true` | unit | same | ❌ Wave 1 |
| LVL-06 | `canIncreaseSkill('EXPERT', 6) = false` (E→M only at L7+) | unit | same | ❌ Wave 1 |
| LVL-06 | `canIncreaseSkill('EXPERT', 7) = true` | unit | same | ❌ Wave 1 |
| LVL-06 | `canIncreaseSkill('MASTER', 14) = false` | unit | same | ❌ Wave 1 |
| LVL-06 | `canIncreaseSkill('MASTER', 15) = true` | unit | same | ❌ Wave 1 |
| LVL-09 | Pure skill-rank prereq evaluates correctly: `evaluatePrereq("Trained in Athletics", { skills: { Athletics: 'TRAINED' }})` → `{ ok: true }` | unit | `npm test -- prereq-evaluator.spec.ts` | ❌ Wave 1 |
| LVL-09 | Same prereq, untrained: → `{ ok: false, reason: ... }` | unit | same | ❌ Wave 1 |
| LVL-09 | Disjunctive: `"Trained in Arcana, Trained in Nature, or Trained in Religion"` with one match → `{ ok: true }` | unit | same | ❌ Wave 1 |
| LVL-09 | Conjunctive: `"Trained in Deception; Trained in Stealth"` with one missing → `{ ok: false }` | unit | same | ❌ Wave 1 |
| LVL-09 | Bare feat-name: `"Power Attack"` with feat present → `{ ok: true }` | unit | same | ❌ Wave 1 |
| LVL-09 | Heritage ref: `"Unbreakable Goblin heritage"` with matching heritage → `{ ok: true }` | unit | same | ❌ Wave 1 |
| LVL-09 | Class ref: `"Fighter"` with `classId='Fighter'` → `{ ok: true }` | unit | same | ❌ Wave 1 |
| LVL-09 | Spellcasting ref: `"spellcasting class feature"` → `{ unknown: true, raw: ... }` | unit | same | ❌ Wave 1 |
| LVL-09 | Deity ref: `"worshipper of Droskar"` → `{ unknown: true, raw: ... }` | unit | same | ❌ Wave 1 |
| LVL-09 | Empty/null prereq → `{ ok: true }` | unit | same | ❌ Wave 1 |
| LVL-10 | `recomputeDerivedStats(character, choices, progression).hpMax = ancestryHP + (classHP + conMod) × level` | unit | `npm test -- recompute-derived-stats.spec.ts` | ❌ Wave 1 |
| LVL-10 | Recompute respects boost-cap-at-18 | unit | same | ❌ Wave 1 |
| LVL-10 | Recompute applies proficiencyChanges from ClassProgression at the new level | unit | same | ❌ Wave 1 |
| LVL-10 | Recompute does NOT mutate `hpCurrent` | unit | same | ❌ Wave 1 |
| LVL-01 | `computeApplicableSteps(targetLevel=5, class='Fighter', hasFA=false, isCaster=false)` includes boost, skill-increase, feat-class, feat-skill, feat-ancestry | unit | `npm test -- compute-applicable-steps.spec.ts` | ❌ Wave 1 |
| LVL-01 | At level 4, no boost step | unit | same | ❌ Wave 1 |
| LVL-01 | With FA enabled, includes feat-archetype step | unit | same | ❌ Wave 1 |
| LVL-01 | With caster class, includes spellcaster step | unit | same | ❌ Wave 1 |
| LVL-12 | Commit transaction is atomic: simulated mid-transaction throw rolls back ALL writes | integration | `npm test -- leveling.service.spec.ts` | ❌ Wave 3 |
| LVL-12 | Commit creates one `LevelUpHistory` row with snapshot + choices populated | integration | same | ❌ Wave 3 |
| LVL-12 | Commit broadcasts `level_up_committed` exactly once (mock the gateway) | integration | same | ❌ Wave 3 |
| LVL-11 | DELETE `/level-up/:sessionId` removes the DRAFT without touching the character | integration | same | ❌ Wave 3 |
| LVL-11 | Partial unique index allows re-creating a DRAFT after the previous was committed (`committedAt` IS NOT NULL → not in unique scope) | integration | same | ❌ Wave 3 |
| LVL-13 | `freeArchetype: true` on character causes `computeApplicableSteps` to include the FA step | unit | same as LVL-01 tests | ❌ Wave 1 |
| LVL-14 | Commit applies `spellSlotIncrement` from ClassProgression to `CharacterResource` for caster classes | integration | `leveling.service.spec.ts` | ❌ Wave 3 |
| LVL-14 | Commit does NOT add slots for non-casters | integration | same | ❌ Wave 3 |
| LVL-15 | Translation pipeline call for new prereq strings hits the existing `TranslationsService.getTranslationsBatch` | manual + integration | manual smoke; one integration test asserts the service is invoked | ❌ Wave 3 |
| LVL-08 | Seed script populates `ClassProgression` for all 16 classes × 20 levels = 320 rows minimum | manual | `cd server && npm run db:seed:class-progression && psql -c 'SELECT className, COUNT(*) FROM "ClassProgression" GROUP BY className'` | N/A — seed verification |
| LVL-03/04/05/07 | `feat-filter.service.ts` returns only feats whose prereq evaluates `{ ok: true }` OR `{ unknown: true }` (NOT `{ ok: false }`), respecting class/ancestry/skill-feat-source filters | integration | `npm test -- feat-filter.service.spec.ts` | ❌ Wave 3 |

### Sampling Rate
- **Per task commit:** `cd server && npm test -- --testPathPattern=leveling` — runs only the leveling module's tests in <10s.
- **Per wave merge:** `cd server && npm test` — full suite, including the existing placeholder e2e test (still expected to pass or be marked skipped if not relevant).
- **Phase gate:** Full suite green before `/gsd-verify-work`. Integration test for atomic commit MUST pass.

### Wave 0 Gaps

The codebase has Jest **infrastructure** but zero unit-test files alongside source. Wave 0 establishes the file convention and proves the runner works on a leveling-module test:

- [ ] Create `server/src/modules/leveling/lib/apply-attribute-boost.ts` + `.spec.ts` (smallest possible — one function, four tests). Run `npm test`. Confirms ts-jest compiles, the testRegex picks it up, the run completes.
- [ ] Add `server/jest.config.cjs` ONLY if the inline `package.json` Jest config has surprises with the new test files. Default: trust the inline config.
- [ ] Add `db:seed:class-progression` script to `server/package.json` scripts section pointing at `tsx prisma/seed-class-progression.ts`.
- [ ] Add `.gitignore` entry for `server/prisma/data/foundry-pf2e/` (the dev-cloned source).
- [ ] Add unit-test pattern documentation to `.planning/codebase/TESTING.md` once the Wave-1 modules land — first real pattern in the codebase.

*(If no gaps: not applicable — gaps exist as listed.)*

## Security Domain

This phase touches authenticated REST endpoints and persists JSON state. Security enforcement applies; no `security_enforcement: false` in config.

### Applicable ASVS Categories

| ASVS Category | Applies | Standard Control |
|---------------|---------|-----------------|
| V2 Authentication | yes (existing) | Bearer JWT via `JwtAuthGuard` — same as all existing endpoints; no new auth surface. WebSocket handshake uses existing token check (`characters.gateway.ts:60-92`). |
| V3 Session Management | yes (existing) | JWT-stateless; logout invalidates client-side; new endpoints do not introduce server-side session. |
| V4 Access Control | yes | `LevelingService` calls `CharactersService.checkCharacterAccess(characterId, userId, requireOwnership=true)` for every endpoint per D-13. The `requireOwnership=true` path in `characters.service.ts:73-78` resolves to `isOwner || isGM` — exact semantic match. |
| V5 Input Validation | yes | All four endpoints' DTOs use `class-validator` decorators (existing pattern — see `server/src/modules/characters/dto/*.dto.ts`). The wizard JSON state inside the DRAFT is validated by a hand-written guard function (TypeScript discriminated unions). Foundry-pf2e seed is dev-time and trusted. |
| V6 Cryptography | no | No new crypto in this phase. JWT signing handled by `@nestjs/jwt` (existing). |
| V7 Errors / Logging | yes | Existing NestJS `Logger` patterns used — log every commit (`Level-up committed: characterId=X, fromLevel=N, toLevel=N+1`); log every unknown prereq encountered to help future grammar improvements. Do NOT log full character snapshots (PII via character names + descriptions; even self-hosted, log discipline matters for shared logs). |
| V8 Data Protection | yes | `LevelUpSession.state` and `LevelUpHistory.snapshotBefore` are JSON columns. They contain character-derived data only — no auth tokens, no passwords. PII risk = character names (already throughout the schema). No additional protection needed beyond DB access controls. |
| V12 Files / Resources | partial | The seed script reads from `server/prisma/data/foundry-pf2e/` (dev-time only; gitignored). Path-traversal not a concern — paths are hardcoded relative to `__dirname`. |

### Known Threat Patterns for {NestJS + Prisma + WebSocket}

| Pattern | STRIDE | Standard Mitigation |
|---------|--------|---------------------|
| Player attempts to commit a level-up for someone else's character (forged characterId) | Spoofing/EoP | `checkCharacterAccess(characterId, userId, requireOwnership=true)` already throws `ForbiddenException`; tested in integration. |
| Player attempts to skip the boost step or set 5 boost targets via crafted PATCH | Tampering | DTO validator on `PatchLevelUpDto` rejects malformed shape; commit-time guard runs `isValidBoostSet()` and throws `BadRequestException` if not exactly 4 distinct. |
| Player attempts to commit a level beyond `currentLevel + 1` | Tampering | Server validates `session.targetLevel === character.level + 1` at commit time; throw `BadRequestException` otherwise. |
| Player attempts to commit a non-applicable step's choices (e.g. boost choice at level 4) | Tampering | The Wave-1 `computeApplicableSteps()` runs server-side at commit; choices for steps not in the applicable list are rejected. |
| Race condition: two browser tabs both POST `/commit` for the same session | Tampering | Partial unique index on `(characterId) WHERE committedAt IS NULL` makes the second commit a no-op (the session it points to has already been transitioned to `committedAt = now()`). Plus: `prisma.$transaction` is serialized at the row level — second tab's transaction sees `committedAt != null` and aborts. |
| WebSocket payload injection (player crafts a fake `level_up_committed` event) | Tampering | Inbound WebSocket events are unaffected — `level_up_committed` is server-emit only. The CharactersGateway has no `@SubscribeMessage('level_up_committed')` handler. Other clients trust the event's source = the room's server. |
| Stored XSS via German feat-prereq translation text rendered in the prereq-confirm dialog | Injection (Tampering) | The text comes from the existing `Translation.germanName` column populated from Claude API; render with React text-binding (no `dangerouslySetInnerHTML`). Existing Dimension47 patterns already do this. |
| SQL injection via `Feat.prerequisites` containing SQL-like text | Tampering | Prisma parameterizes everything; the prereq strings are never interpolated into raw queries. |

## Open Questions

1. **Spell-slot progression overlay sourcing.**
   - **What we know:** Foundry pf2e classfeatures (`wizard-spellcasting.json` etc.) encode slot tables in description prose — verified. We need a hand-curated overlay.
   - **What's unclear:** Should the overlay live as a TS constant (`server/prisma/data/spell-slot-overlays.ts`) or as a JSON file (e.g. `server/prisma/data/spell-slot-overlays.json`)?
   - **Recommendation:** TS constant, exported from the `data/` folder, imported by the seed script. Type-safe, IDE-navigable, version-controlled, and the values are inherently TS-shaped (enums for `SpellTradition`). Planner: include curating this overlay (16 caster classes × ~20 levels) as a Wave-2 sub-task.

2. **Class-feature option mechanics — where does the recompute apply them?**
   - **What we know:** `ClassProgression.choiceType` flags that a step exists; `ClassFeatureOption` lists the user-facing options; the user picks one in the wizard.
   - **What's unclear:** When the user picks "Destruction Doctrine" (Cleric L1), the doctrine grants specific abilities/feats/proficiencies. Do those grants live as additional `ClassFeatureOption` columns (`grants: String[]`, `proficiencyChanges: Json`), or in a parallel hand-coded mapping?
   - **Recommendation:** **Add the same `grants` + `proficiencyChanges` columns to `ClassFeatureOption`** so the recompute pipeline is uniform: at commit, walk both `ClassProgression` AND any chosen `ClassFeatureOption` rows, apply both sets of grants. This keeps the data model symmetric and the recompute code branch-free. Planner should extend the schema in §Code Examples #3 accordingly.

3. **Banner-resolution UI for D-06 import violations.**
   - **What we know:** Phase 1 ships listing-only (per `01-UI-SPEC.md` §"Pathbuilder-Import-Violations Banner": "Phase 1 ships read-only listing only; resolution UI is out of scope").
   - **What's unclear:** When a user retrains a feat manually outside the wizard (today possible via direct DB?), should the banner update? **Out of scope this phase** — confirmed by deferral. Planner: do NOT add banner-clearing logic.

4. **Pathbuilder FA auto-detect false-positive recovery (A1 tied).**
   - **What we know:** Heuristic might misfire.
   - **What's unclear:** Should the auto-detection's result be visible somewhere besides the toggle (e.g. logged on the character)?
   - **Recommendation:** Log the detection result as a NestJS Logger info line during import (`PathbuilderImport: detected FA=true for character ${name} based on ${reason}`). The toggle is editable via character-settings. No UI banner needed.

5. **Initial level-up from L1 to L2 — does the wizard support it?**
   - **What we know:** ROADMAP/REQUIREMENTS describe the wizard for "Stufe steigen" generally.
   - **What's unclear:** Is L1→L2 the same flow as L4→L5? PF2e: L2 is just feats + skill-feat (no boost set). The dynamic-step logic in `computeApplicableSteps` handles this — boost step appears only for L5/10/15/20. So yes, same flow. **Confirmed: no special handling needed.**

## Sources

### Primary (HIGH confidence)
- `server/prisma/data/featlevels.json` — 5,625 feats, audited locally for prereq pattern distribution (3,393 with prereqs, 60.3%).
- `server/prisma/schema.prisma` — current schema, lines 171-220 (Character), 222-231 (CharacterAbility), 233-244 (CharacterFeat), 246-255 (CharacterSkill), 257-269 (CharacterSpell), 544-582 (Feat with prerequisites: String? at line 560).
- `server/src/modules/characters/characters.service.ts:41-86` — `checkCampaignAccess`/`checkCharacterAccess` patterns; the `requireOwnership=true` semantic confirmed at lines 73-78 means "isOwner OR isGM".
- `server/src/modules/characters/characters.gateway.ts:22-26` — `CharacterUpdatePayload['type']` union to extend.
- `server/src/modules/characters/pathbuilder-import.service.ts:243-272` — feat import structure (where the PrereqEvaluator hooks in for D-05).
- `server/package.json:88-104` — Jest 30.0.0 inline config, `testRegex: ".*\\.spec\\.ts$"`.
- WebFetch: `https://raw.githubusercontent.com/foundryvtt/pf2e/master/packs/classes/fighter.json` — fighter class JSON shape (top-level, system fields, items keyed-object structure, classFeatLevels arrays).
- WebFetch: `https://raw.githubusercontent.com/foundryvtt/pf2e/master/packs/classes/sorcerer.json` — sorcerer class shape; **confirmed** spell-slot/repertoire NOT in class JSON.
- WebFetch: `https://github.com/foundryvtt/pf2e/blob/master/README.md` — license: Apache 2.0 + OGL 1.0a + Paizo CUP (NOT ORC — D-17 is corrected on this point; the practical effect is identical for self-hosted single-group use).
- WebFetch: `https://raw.githubusercontent.com/foundryvtt/pf2e/master/packs/classfeatures/wizard-spellcasting.json` — confirmed `rules` array does NOT contain slot increments; mechanical progressions live in description prose.
- `npm view jest version` → 30.3.0; `npm view xstate version` → 5.30.0; `npm view @xstate/react version` → 6.1.0; `npm view zod version` → 4.3.6 (verified 2026-04-27).
- `.planning/research/PITFALLS.md` §Pitfall 8 (boost cap), §Pitfall 9 (recompute), §Pitfall 10 (feat retrain orphans), §Pitfall 11 (skill-increase history).
- `.planning/research/SUMMARY.md` §Phase A.
- `.planning/codebase/ARCHITECTURE.md` — NestJS module-per-feature pattern.
- `.planning/codebase/CONVENTIONS.md` — kebab-case files, camelCase functions, PascalCase types, DTOs end in `Dto`, Props in `Props`.
- `.planning/codebase/TESTING.md` — confirms zero current unit tests; first ones to land per ROADMAP First-Phase Note.

### Secondary (MEDIUM confidence)
- WebFetch: `https://www.prisma.io/docs/orm/prisma-schema/data-model/database-mapping` — confirmed Prisma does not express partial unique indexes; raw SQL migration is the documented workaround.
- WebFetch: `https://github.com/foundryvtt/pf2e/tree/master/packs/classes` — confirmed list of 28 class JSON files in master branch (we use the 16 from D-16).
- WebFetch: `https://stately.ai/docs/xstate` — XState v5 capabilities; insufficient to prove serialization story BUT the v5 `createMachine` actor model does support `getPersistedSnapshot()` for resume; ultimately not adopted (see §Standard Stack rejected).
- WebFetch: Archives of Nethys Leveling Up rule page `https://2e.aonprd.com/Rules.aspx?ID=2065` — confirms general structure but the specific cap-at-18 quote is on a different page; cited from PITFALLS.md / common knowledge of the rule.

### Tertiary (LOW confidence — needs validation)
- A1: Pathbuilder FA auto-detect heuristic — based on common Pathbuilder export shape inferred from `pathbuilder-import.service.ts`; should be verified against an actual FA-enabled character JSON.
- A5: prereq parser disambiguation (semicolon=AND, comma-in-OR-list-pattern=OR, comma-otherwise=AND) — heuristic based on corpus inspection; expect ~5% misclassification on edge cases. Mitigation built in: any uncertainty → `{ unknown: true }` → user confirms.

## Metadata

**Confidence breakdown:**
- Standard stack: HIGH — all versions verified locally and via npm registry; no new dependencies introduced.
- Architecture: HIGH — every recommendation grounded in existing module/service/gateway patterns and explicit live-code touchpoints.
- Pitfalls: HIGH — directly mapped to PITFALLS.md #8/#9/#10/#11 plus three new phase-specific pitfalls (Foundry shape drift, spell-slot prose, cascading delete decision).
- Foundry pf2e data shape: HIGH for class JSON top-level (verified); MEDIUM for class-feature compendiums (verified for wizard-spellcasting only — assumed similar shape for other classes); LOW for the spell-slot extraction pathway (resolved by hand-curated overlay, A3).
- Prereq evaluator coverage: HIGH for the local corpus audit (5,625 feats inspected); MEDIUM for the projected ~70-80% evaluable rate (depends on grammar implementation quality).
- License: HIGH — Apache 2.0 + OGL 1.0a + Paizo Community Use Policy (confirmed from Foundry pf2e README); CONTEXT.md D-17 mentions ORC but the practical impact for self-hosted private use is identical.
- Validation architecture: HIGH — full test map per requirement, executable commands provided.

**Research date:** 2026-04-27
**Valid until:** 2026-05-27 (30 days for stable libraries; sooner if Foundry pf2e major version ships).