neon-sprawl/docs/decomposition/epics/epic_02_classless_progression.md

# Epic 2 - Classless Skill and Progression Framework

## Source Anchors

- Master epic reference: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, System Modules Epic 2
- Related modules: E2.M1, E2.M2, E2.M3, E2.M4

## Ownership and success (Level 1)

- **Ownership focus:** Systems Design + Gameplay Engineering
- **Success criteria:** Any character can train all skills, and progression remains long-term without dead-end grinds.

## Objective

Provide a data-driven **classless non-combat skill** layer: `SkillDef` registry, **skill** XP awards, level curves, and eventually mastery/perk and pacing controls. **Gathering** and **crafting** feed **skill** progression via [E2.M2](../modules/E2_M2_XpAwardAndLevelEngine.md); **combat encounters** feed **gig** progression (not `SkillDef` XP)—see [`docs/game-design/progression.md`](../../game-design/progression.md). **Mission rewards** may still grant **skill** XP when scripted.

## Module Breakdown

### E2.M1 - SkillDefinitionRegistry

- Responsibility: Central catalog for **non-combat** `SkillDef` rows: **stable `id`**, **`SkillCategory`** (`gather` / `process` / `make` / `tech`), **`displayName`**, **`allowedXpSourceKinds`** (which `XpGrantEvent.sourceKind` values may grant XP per skill), and unlock prerequisites. **Combat roles** are **gigs**, not `SkillDef`. Detail: [E2.M1 — SkillDefinitionRegistry](../modules/E2_M1_SkillDefinitionRegistry.md), [`content/schemas/skill-def.schema.json`](../../../content/schemas/skill-def.schema.json).
- Key contracts: `SkillDef`, `SkillCategory`, `UnlockRequirement`; prototype schema requires **`allowedXpSourceKinds`** per skill.
- Dependencies: None
- Stage target: Prototype

### E2.M2 - XpAwardAndLevelEngine

- Responsibility: XP award rules, level thresholds, level-up event generation.
- Key contracts: `XpGrantEvent`, `LevelCurve`, `LevelUpEvent`
- Dependencies: E2.M1
- Stage target: Prototype
- Note: E3.M1, E3.M2, and E5.M1 integrate by calling this engine; they are not dependencies for implementing E2.M2 (see Slice 3).

### E2.M3 - MasteryAndPerkUnlocks

- Responsibility: Mastery tracks and perk unlock state for non-class build expression.
- Key contracts: `MasteryTrack`, `PerkUnlockEvent`, `PerkState`
- Dependencies: E2.M2
- Stage target: Pre-production

### E2.M4 - ProgressionPacingControls

- Responsibility: Tuning knobs for progression velocity and catch-up policy enforcement.
- Key contracts: `XpModifierProfile`, `CatchUpRule`, `PacingPolicy`
- Dependencies: E2.M2, E9.M2
- Stage target: Pre-production

## Implementation Slices (Backlog-Ready)

### Slice 1 - Skill registry and prototype skills

- Scope: E2.M1 with at least three **non-combat** `SkillDef` rows loaded from data—e.g. aligned with **Gather**, **Process** or **Make**, and **Tech** as in [`docs/game-design/skills.md`](../../game-design/skills.md). **Combat role progression** is **gig**-scoped, not a `SkillDef` line (see [`docs/game-design/gigs.md`](../../game-design/gigs.md), [`docs/game-design/progression.md`](../../game-design/progression.md)).
- Dependencies: None
- Acceptance criteria:
  - All prototype activities reference skills by stable IDs.
  - Invalid skill references fail validation in CI or at load time.
- Telemetry hooks: `skill_unlock` (if gating exists), schema validation metrics.

### Slice 2 - XP engine (E2.M2 core)

- Scope: Implement `XpGrantEvent`, `LevelCurve`, `LevelUpEvent`, and server-authoritative level resolution on top of `SkillDef` from E2.M1. No dependency on Epic 3 or Epic 5 modules beyond future call sites.
- Dependencies: E2.M1 (matches module-level E2.M2 → E2.M1 only).
- Acceptance criteria:
  - XP and level-up can be triggered from tests or a stub caller without gathering/combat content.
  - Curves and thresholds are data-driven and hot-reloadable or reloadable by policy agreed for prototype.
- Telemetry hooks: `xp_grant`, `level_up`, time-to-first-level-up (once integration slice fires real activity).

### Slice 3 - XP award integration at activity sites

- Scope: Wire **gathering** (E3.M1) and **crafting** (E3.M2) to the **E2.M2 skill XP** award API so prototype **`SkillDef`** lines gain XP from real play. Wire **combat** (E5.M1) to **gig XP only** ([`gigs.md`](../../game-design/gigs.md), [`progression.md`](../../game-design/progression.md))—**no** hook that maps **encounter resolution** to **skill** XP or a combat `SkillDef`. **Mission / quest reward** paths may still call the **skill** XP API when the **payout** explicitly includes skill XP (**not** the same as “combat trained this skill”).
- Dependencies: E2.M2, E3.M1, E3.M2, E5.M1 (integration prerequisites; not part of the E2.M2 module dependency list). Gig XP plumbing may live beside E2.M2 or under Epic 5—**split call sites** by progression type (skill vs gig).
- Acceptance criteria:
  - Visible **skill** XP and skill level-up feedback within first session from real **gather/craft** actions.
  - Visible **gig** XP and gig progression feedback from **combat** (main gig only, per game-design).
- Telemetry hooks: `xp_grant`, `level_up`, time-to-first-level-up for **skills**; gig progression hooks as agreed when gig model lands (e.g. `gig_xp_grant`, `gig_level_up`).

### Slice 4 - Mastery and pacing (pre-production)

- Scope: E2.M3 and E2.M4 for first mastery branch and global pacing policy.
- Dependencies: E2.M2, E9.M2
- Acceptance criteria:
  - At least one mastery path unlocks a perk without blocking other skills.
  - Pacing policy can be toggled for test cohorts without redeploy where possible.
- Telemetry hooks: `perk_unlock`, `pacing_profile_applied`.

## Risks and Mitigations

- Risk: XP faucets create runaway leveling in one skill.
  - Mitigation: Diminishing returns per slice; monitor skill distribution via E9.M2.
- Risk: Classless identity feels flat without mastery expression.
  - Mitigation: Ship E2.M3 early in pre-production with one flagship mastery line.

## Definition of Done

- Prototype uses E2.M1 + E2.M2 for three **non-combat** `SkillDef` lines (stable **`id`** + **`allowedXpSourceKinds`** per [E2.M1](../modules/E2_M1_SkillDefinitionRegistry.md)); **gig** progression for combat is separate.
- Pre-production adds E2.M3/E2.M4 with documented tuning workflow.
- Events align with baseline telemetry in master plan.