Initial Commit

openspec/changes/enterprise-gaming-progression/proposal.md

@@ -0,0 +1,168 @@
+# OpenSpec Change: enterprise-gaming-progression
+
+- **Change ID**: enterprise-gaming-progression
+- **Package**: `@suaveplan/progression`
+- **Category**: gaming/narrative
+- **Target path**: `gaming/narrative/progression`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/progression.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/progression` on the genesis branch from scratch at enterprise quality. The package provides character progression with XP curves, skill trees, perks, and achievements. A `ProgressionManager` accumulates XP and triggers level-up events; an `XpCurve` computes required XP per level from configurable formulas (polynomial, exponential, flat table); a `SkillTree` represents an acyclic graph of `SkillNode` objects with prerequisite unlocking; a `PerkRegistry` holds passive modifiers unlockable at level milestones; an `AchievementTracker` monitors player statistics and fires unlock events. Genesis adds Zod schemas, structured errors, OTel XP counter, injectable clock, and 100% coverage.
+
+---
+
+## Current-state audit (genesis)
+
+Package does not exist on genesis yet — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | `ProgressionError`; `PROG.*` codes |
+| `@suaveplan/types` (`workspace:^`) | `Clock` |
+| `@suaveplan/events` (`workspace:^`) | `prog:level_up`, `prog:skill_unlocked`, `prog:perk_unlocked`, `prog:achievement` |
+| `zod` (`catalog:forms`) | Skill tree + achievement schemas |
+| `@opentelemetry/api` (`catalog:observability`) | XP counter, level gauge |
+
+---
+
+## Public API surface
+
+```ts
+interface XpCurveOptions {
+  formula: 'polynomial' | 'exponential' | 'table'
+  base?: number
+  coefficient?: number
+  exponent?: number
+  table?: number[]       // XP required per level (table formula)
+}
+
+function createXpCurve(options: XpCurveOptions): XpCurve
+interface XpCurve {
+  xpForLevel(level: number): number
+  levelForXp(xp: number): number
+}
+
+function createProgressionManager(options: ProgressionManagerOptions): ProgressionManager
+
+interface ProgressionManagerOptions {
+  curve: XpCurve
+  maxLevel?: number
+  clock?: Clock
+}
+
+interface ProgressionManager {
+  awardXp(playerId: string, amount: number, source?: string): void
+  getLevel(playerId: string): number
+  getXp(playerId: string): number
+  getProgress(playerId: string): number   // 0–1 toward next level
+}
+
+// Skill tree
+interface SkillNode {
+  id: string
+  name: string
+  description: string
+  cost: number            // skill points required
+  prerequisites?: string[]
+  effects?: SkillEffect[]
+}
+
+interface SkillEffect {
+  stat: string
+  modifier: number
+  type: 'add' | 'multiply'
+}
+
+function createSkillTree(nodes: SkillNode[]): SkillTree
+interface SkillTree {
+  canUnlock(nodeId: string, unlockedIds: Set<string>, availablePoints: number): boolean
+  unlock(nodeId: string, unlockedIds: Set<string>, availablePoints: number): Set<string>
+  computeEffects(unlockedIds: Set<string>): Map<string, number>
+}
+
+// Achievements
+interface AchievementDefinition {
+  id: string
+  title: string
+  description: string
+  condition: { stat: string; threshold: number; op: '>=' | '<=' | '==' }
+}
+
+function createAchievementTracker(definitions: AchievementDefinition[]): AchievementTracker
+interface AchievementTracker {
+  updateStat(stat: string, value: number): void
+  incrementStat(stat: string, by?: number): void
+  getUnlocked(): string[]
+  isUnlocked(id: string): boolean
+}
+```
+
+### Error codes
+
+```ts
+type ProgErrorCode =
+  | 'PROG_PLAYER_NOT_FOUND'
+  | 'PROG_SKILL_NOT_FOUND'
+  | 'PROG_PREREQUISITES_NOT_MET'
+  | 'PROG_INSUFFICIENT_POINTS'
+  | 'PROG_MAX_LEVEL_REACHED'
+```
+
+---
+
+## File layout
+
+```text
+gaming/narrative/progression/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    error-codes.ts
+    constants/index.ts
+    types/common.ts
+    types/common.md
+    core/
+      xp-curve/
+        xp-curve.ts
+        xp-curve.md
+        xp-curve.types.ts
+        xp-curve.test.ts
+        index.ts
+      progression-manager/
+        progression-manager.ts
+        progression-manager.md
+        progression-manager.types.ts
+        progression-manager.test.ts
+        index.ts
+      skill-tree/
+        skill-tree.ts
+        skill-tree.md
+        skill-tree.types.ts
+        skill-tree.test.ts
+        index.ts
+      achievement-tracker/
+        achievement-tracker.ts
+        achievement-tracker.md
+        achievement-tracker.types.ts
+        achievement-tracker.test.ts
+        index.ts
+  tests/
+    integration.test.ts
+```
+
+---
+
+## Impact
+
+**Downstream**: `@suaveplan/economy` reads player level for pricing; `@suaveplan/react-game-hud` shows XP bar. Prerequisites: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`.

openspec/changes/enterprise-gaming-progression/tasks.md

@@ -0,0 +1,52 @@
+# Tasks: enterprise-gaming-progression
+
+## 0. Pre-flight (non-negotiable)
+
+- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## Phase 1 — Scaffold
+
+- [ ] Create `gaming/narrative/progression/` (`@suaveplan/progression`, `0.1.0`, `sideEffects: false`)
+- [ ] `tsconfig.json`, `vitest.config.ts`
+
+## Phase 2 — Error codes & constants
+
+- [ ] `src/error-codes.ts` + `src/constants/index.ts` — `DEFAULT_MAX_LEVEL`
+
+## Phase 3 — Types
+
+- [ ] `src/types/common.ts` + `common.md`
+
+## Phase 4 — XP curve
+
+- [ ] `src/core/xp-curve/xp-curve.ts` — polynomial/exponential/table formulas
+- [ ] Tests (levelForXp round-trip, monotone xpForLevel)
+- [ ] Docs
+
+## Phase 5 — Progression manager
+
+- [ ] `src/core/progression-manager/progression-manager.ts` — awardXp/getLevel/getXp/getProgress, level-up events, OTel
+- [ ] Tests + docs
+
+## Phase 6 — Skill tree
+
+- [ ] `src/core/skill-tree/skill-tree.ts` — canUnlock/unlock/computeEffects, prerequisite DAG check
+- [ ] Tests (prerequisite gate, effect aggregation)
+- [ ] Docs
+
+## Phase 7 — Achievement tracker
+
+- [ ] `src/core/achievement-tracker/achievement-tracker.ts` — stat tracking, condition evaluation, unlock events
+- [ ] Tests + docs
+
+## Phase 8 — Integration tests
+
+- [ ] `tests/integration.test.ts` — XP award → level-up → skill point → unlock → achievement stat update
+
+## Phase 9 — Pre-publish gate
+
+- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/progression` green
+- [ ] 100% coverage
+- [ ] Publish: `bun scripts/publish.ts --package @suaveplan/progression`