> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase30-session08-progression-depth/spec.md).

# Session Specification

**Session ID**: `phase30-session08-progression-depth` **Phase**: 30 - AI Rogue Game Extension **Status**: Not Started **Created**: 2026-06-22

***

## 1. Session Overview

This session expands the stable AI Rogue playable slice into browser-safe progression depth. It adds skill-linked classes, relic choices, capped model-flavored resources, richer deterministic content, and local achievements without changing the disabled-first extension posture or adding collectors, backend services, remote loading, or new third-party transfers.

The previous session validated the core play loop, committed atlas rendering, save slots, wallet-backed `Integrity Patch`, run summaries, and focused browser coverage. The next step is to make replayable runs reflect AI OS usage diversity through bounded counts, categories, and labels from existing LiveData branches.

The implementation should preserve the pure TypeScript simulation boundary. React can derive and display the progression profile, but the runtime rules, catalogs, save envelopes, and tests must remain deterministic and independent of PixiJS, browser storage, raw prompts, command output, private paths, or logs.

***

## 2. Objectives

1. Add browser-safe progression profile derivation from `skills.active`, `localAgents.skillSources`, and `modelUsage`.
2. Add deterministic class, relic, resource, objective, enemy, and room-modifier rules that enrich runs without requiring new art or a worker.
3. Extend browser-local run history with achievement and progression metadata through the existing IndexedDB/localStorage contracts.
4. Surface class, relic, resource, objective, and achievement state in Play and Loadout while preserving loading, empty, error, offline, and denied-storage behavior.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase30-session07-play-runtime-integration` - Provides the validated playable runtime slice, committed atlas rendering, save/load controls, run summaries, and one wallet-backed upgrade.

### Required Tools Or Knowledge

* Bun, React 19, TanStack Router, Vite 8, Vitest, Playwright, PixiJS v8 WebGL runtime boundary.
* Existing AI Rogue persistence schemas in `src/extensions/ai-rogue/save-schema.ts`.
* Existing AI Rogue economy derivation in `src/extensions/ai-rogue/economy.ts`.

### Environment Requirements

* Local dependencies installed with Bun.
* AI Rogue can remain disabled-first behind `VITE_CLAUDE_OS_ENABLED_EXTENSIONS`; tests can seed enabled extension state as existing e2e coverage does.

***

## 4. Scope

### In Scope (MVP)

* AI OS users can derive a bounded progression profile from active skills, local-agent skill-source counts, and model usage labels - implemented as a pure, testable helper that sanitizes labels and emits fallback states.
* AI Rogue players can choose or receive skill-linked classes and relics - implemented as deterministic catalogs and runtime rules that apply scoped stat, pickup, objective, or resource effects.
* AI Rogue runs include capped model-flavored resources and expanded content - implemented through existing world generation, entity templates, render descriptors, and save envelopes.
* AI Rogue stores expanded run history and achievements locally - implemented through existing save contracts with safe defaults, bounded arrays, and malformed/private-record rejection.
* AI Rogue Play and Loadout make progression legible - implemented with compact operational UI states and no Session 09 mobile/audio/polish scope creep.

### Out Of Scope (Deferred)

* New backend, auth, realtime service, remote package loading, or dynamic plugin loading - Reason: Phase 30 explicitly keeps AI Rogue repo-local and disabled-first.
* Optional generated content packs and collectors - Reason: no browser-safe content need exists in the current slice, and collectors remain deferred.
* Web Audio, new atlases, mobile/pointer-first layout polish, seed sharing, and presentation pass - Reason: these are Session 09 responsibilities.
* Worker simulation protocol - Reason: Session 08 only evaluates whether profiling or deterministic tests justify a worker; no current evidence shows input or rendering blockage.

***

## 5. Technical Approach

### Architecture

Add a pure `src/extensions/ai-rogue/progression.ts` helper that reads the existing browser-safe LiveData contract and emits a compact progression profile: class candidates, relic candidates, model-resource caps, content weights, achievement candidates, provenance labels, and warnings. The helper should mirror the economy module's sanitization posture: accept counts, categories, model labels, source labels, and cap states; reject or replace private-looking text.

Extend the runtime contracts under `src/extensions/ai-rogue/runtime/` with progression-aware class/relic/resource/objective metadata. Simulation remains pure TypeScript and receives a selected progression loadout from React rather than reaching into LiveData, storage, or PixiJS. World generation can use the selected loadout and depth to add bounded enemies, hazards, objectives, and pickup mix without changing asset files.

Extend the existing save schema and IndexedDB run-history store instead of adding a new storage surface. Additive defaults keep old records parseable. Run summaries should include only safe class IDs, relic IDs, objective IDs, achievement IDs, resource counts, depth, turns, and shard deltas.

### Design Patterns

* Pure derivation helper: Keeps LiveData-to-progression mapping testable and independent of views.
* Additive Zod defaults: Preserves older wallet, save-slot, and run-history records while adding progression metadata.
* Catalog-driven runtime rules: Makes classes, relics, resources, objectives, and enemy modifiers deterministic and unit-testable.
* Existing route-scoped runtime bridge: Keeps PixiJS ownership inside the Play route and avoids shared-chunk leakage.
* Existing durable transaction wrappers: Reuse IndexedDB wallet, ledger, run-history, and save-slot mutation safeguards.

***

## 6. Deliverables

### Files To Create

| File                                                    | Purpose                                                                              | Est. Lines |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------- |
| `src/extensions/ai-rogue/progression.ts`                | Browser-safe LiveData progression profile, catalogs, sanitization, and warnings.     | \~220      |
| `src/extensions/ai-rogue/__tests__/progression.test.ts` | Unit tests for class, relic, resource, achievement, fallback, and privacy behavior.  | \~180      |
| `docs/extensions/ai-rogue/progression-depth-notes.md`   | Session 08 notes for worker decision, bounded inputs, and future content follow-ups. | \~80       |

### Files To Modify

| File                                                           | Changes                                                                                               | Est. Lines |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------- |
| `src/extensions/ai-rogue/runtime/types.ts`                     | Add progression loadout, resource, objective, achievement, and snapshot metadata types.               | \~90       |
| `src/extensions/ai-rogue/runtime/entities.ts`                  | Add catalog-aware enemy and pickup templates while reusing committed frames.                          | \~70       |
| `src/extensions/ai-rogue/runtime/world.ts`                     | Add deterministic depth/content options for room modifiers, objectives, resources, and spawn weights. | \~120      |
| `src/extensions/ai-rogue/runtime/simulation.ts`                | Apply class/relic/resource/objective effects to run creation, turns, pickups, and completion.         | \~180      |
| `src/extensions/ai-rogue/runtime/render-model.ts`              | Project class, relic, resource, objective, and achievement state into HUD descriptors.                | \~80       |
| `src/extensions/ai-rogue/runtime/renderer.ts`                  | Render updated HUD descriptors without importing React or widening lifecycle ownership.               | \~50       |
| `src/extensions/ai-rogue/save-schema.ts`                       | Extend wallet/run-history/save-slot schemas with bounded progression and achievement metadata.        | \~140      |
| `src/extensions/ai-rogue/persistence.ts`                       | Preserve additive schema defaults and run-history writes for expanded metadata.                       | \~50       |
| `src/extensions/ai-rogue/use-save-state.ts`                    | Record enriched run summaries and expose progression-safe save-state values.                          | \~60       |
| `src/extensions/ai-rogue/views/play-view.tsx`                  | Derive progression profile, pass selected runtime loadout, and show compact status states.            | \~90       |
| `src/extensions/ai-rogue/views/runtime-canvas.tsx`             | Include progression loadout in runtime create/save/load/summary flows.                                | \~120      |
| `src/extensions/ai-rogue/views/loadout-view.tsx`               | Replace reserved class/relic copy with selectable progression controls and safe provenance.           | \~120      |
| `src/extensions/ai-rogue/__tests__/client.test.tsx`            | Cover Play and Loadout progression loading, empty, error, and selected states.                        | \~140      |
| `src/extensions/ai-rogue/__tests__/persistence.test.ts`        | Cover achievement/run-history persistence and malformed/private metadata rejection.                   | \~100      |
| `src/extensions/ai-rogue/__tests__/save-schema.test.ts`        | Cover schema defaults, migrations, bounded arrays, and private progression text rejection.            | \~100      |
| `src/extensions/ai-rogue/__tests__/use-save-state.test.tsx`    | Cover enriched run summaries, duplicate mutation guards, and denied-storage states.                   | \~100      |
| `src/extensions/ai-rogue/runtime/__tests__/simulation.test.ts` | Cover deterministic class, relic, objective, resource, enemy, and achievement effects.                | \~140      |
| `src/extensions/ai-rogue/runtime/__tests__/world.test.ts`      | Cover deterministic content weighting and fixture parsing for expanded content.                       | \~90       |
| `src/extensions/ai-rogue/runtime/__tests__/combat.test.ts`     | Cover new enemy behavior or modifier interactions.                                                    | \~60       |
| `tests/e2e/ai-rogue-runtime.spec.ts`                           | Verify visible progression HUD state, deterministic run effects, and no runtime leak.                 | \~80       |
| `tests/e2e/ai-rogue-persistence.spec.ts`                       | Verify class/relic/achievement metadata survives refresh and reset remains scoped.                    | \~80       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Progression profile derivation uses only browser-safe counts, categories, model labels, source labels, and capped signals from existing LiveData.
* [ ] At least two class choices, two relic choices, one capped model-flavored resource, one expanded objective, and one expanded enemy or room modifier affect deterministic simulation outcomes.
* [ ] Play can start, save, load, complete, and summarize a progression-aware run without exposing raw prompts, logs, command bodies, command output, private paths, credentials, or provider payloads.
* [ ] Loadout shows class and relic choices with clear disabled, unavailable, selected, insufficient-data, and persistence-degraded states.
* [ ] Run history stores safe achievement/progression metadata and drops malformed or private-looking records without failing the whole record.
* [ ] Worker simulation is either kept deferred with measured notes or scoped behind a tested decision record; no worker is added without evidence.

### Testing Requirements

* [ ] Unit tests cover progression profile derivation, sanitization, fallback behavior, deterministic class/relic/resource/objective rules, schema parsing, persistence, and hook mutation sequencing.
* [ ] Component tests cover Play and Loadout progression UI states.
* [ ] Focused Playwright tests cover visible progression HUD/selection, persistence across refresh, scoped reset, and canvas cleanup.

### Non-Functional Requirements

* [ ] No new backend, auth, realtime, remote loading, dynamic plugin, collector, or third-party transfer path is introduced.
* [ ] Runtime simulation remains pure TypeScript and does not import PixiJS, React, browser storage, or LiveData directly.
* [ ] Added progression data stays bounded under existing local payload and browser-local persistence limits.

### Quality Gates

* [ ] All files ASCII-encoded
* [ ] Unix LF line endings
* [ ] Code follows project conventions
* [ ] `bun run typecheck` passes
* [ ] Focused AI Rogue Vitest suites pass
* [ ] Focused AI Rogue Playwright suites pass
* [ ] `bash scripts/check-asset-sizes.sh` passes if any media files are touched
* [ ] `bun run runtime:check-private` passes

***

## 8. Implementation Notes

### Working Assumptions

* Session 08 is the next executable session: The analysis script reports `current_phase` 30, `current_session` null, Sessions 01-07 completed, and Session 08 as the first unfinished candidate. Planning can proceed because Session 07 validation passed with no blockers.
* Progression can be implemented without new art: The Session 08 stub and `visual-assets.md` identify boss, relic, reward, shard, HUD, and enemy frames already committed. Reusing those frames is enough for progression depth; Session 09 owns art polish.
* Progression should derive from existing LiveData instead of new collectors: `economy.ts` already reads `skills.active`, `localAgents.skillSources`, and `modelUsage` safely; the Phase 30 plan defers optional generated content packs and collectors.
* Worker simulation should remain deferred unless tests show blockage: The stub says to evaluate a worker only if profiling shows measurable input or rendering blockage, and no current Session 07 validation evidence reports such a blockage.

### Conflict Resolutions

* Master PRD table says Phase 30 is "Not Started", while `.spec_system/state.json`, the Phase 30 PRD, and analyzer JSON say Phase 30 is `in_progress` with 7/10 sessions completed. The analyzer JSON is authoritative for workflow state, and the Phase 30 PRD is newer and more specific, so Session 08 is selected.
* The Session 08 stub shows the Session 07 prerequisite checkbox unchecked, while analyzer JSON lists `phase30-session07-play-runtime-integration` in `completed_sessions` and Session 07 validation reports PASS. The completed analyzer state and validation artifact satisfy the prerequisite.

### Key Considerations

* Keep `ai-rogue` disabled-first and compile-time registered.
* Preserve existing `VITE_CLAUDE_OS_ENABLED_EXTENSIONS` compatibility naming.
* Keep raw token/spend a capped progression input, never the dominant reward.
* Store only bounded labels, IDs, counts, dates, and safe metadata.
* Do not hand-edit generated route trees.

### Potential Challenges

* Progression scope can expand into Session 09 polish: Limit UI work to functional class/relic/resource/objective state and persistence visibility.
* Schema changes can break existing saves: Use additive defaults and parser tests for missing, stale, malformed, and future records.
* Runtime catalogs can become entangled with React or LiveData: Keep the LiveData derivation outside the runtime folder and pass a serialized loadout into pure simulation.
* Worker evaluation can become speculative: Record a measured decision based on focused runtime tests instead of building a worker protocol by default.

### Relevant Considerations

* \[P02] **Static extension registry requires code changes**: AI Rogue remains a compile-time extension; no marketplace, dynamic loading, eval, or remote code.
* \[P02] **Disabled-first collector pattern**: AI Rogue should stay gated until Phase 30 quality gates and enablement decision pass.
* \[P02] **Extension payloads and labels stay bounded**: Progression labels and achievements must be capped and explicit about unavailable/degraded states.
* \[P02] **Zod schemas with `.default()` for safe parsing**: Additive defaults keep older saves, wallets, run histories, and save slots parseable.
* \[P00] **Stack conventions**: Bun, Vite 8, TanStack Start, React 19, and Cloudflare Worker compatibility remain baseline constraints.
* \[P29] **Budget checks need separate labels**: Keep local payload, total client JS, watched vendor, individual chunk, and media-size gates distinct.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Persistence writes could double-record achievements or corrupt run history during duplicate clicks.
* LiveData-derived progression could accidentally persist raw labels that look like paths, commands, secrets, logs, or provider payloads.
* Play and Loadout could expose stale selections after LiveData, storage, or route re-entry state changes.

***

## 9. Testing Strategy

### Unit Tests

* Progression helper tests for safe label derivation, class/relic/resource unlocks, unavailable states, private-looking text rejection, deterministic ordering, and example data fallback.
* Simulation tests for class stat effects, relic modifiers, resource pickups, objective completion, enemy/room modifier determinism, terminal states, and save/load serialization.
* Schema and persistence tests for additive defaults, bounded arrays, malformed record drops, private text rejection, duplicate mutation prevention, and transaction failure behavior.

### Integration Tests

* Component tests for Play and Loadout loading, empty, ready, error, offline, disabled, selected, insufficient-data, denied-storage, and persistence-degraded states.
* Hook tests that record enriched run summaries and achievements through the existing save-state API.

### Runtime Verification

* Focused Playwright run on `/extensions/ai-rogue/play` verifies a selected class/relic/resource/objective is visible, affects runtime behavior, paints the canvas, survives refresh through save/load, and cleans up on route exit.
* Focused Playwright run on `/extensions/ai-rogue/loadout` verifies keyboard selection, accessible labels, selected state, insufficient-data state, and no horizontal overflow caused by progression labels.

### Edge Cases

* No active skills, no skill sources, no model usage, example LiveData, and unknown pricing should produce safe unavailable or fallback progression.
* Private-looking skill, source, model, achievement, or summary labels should be replaced or rejected.
* Malformed run-history, save-slot, or wallet records should drop only the bad records and preserve defaults.
* Duplicate achievement or persistence mutations should not create duplicate run-history entries.
* Loading, offline, denied-storage, route re-entry, and reset flows should revalidate or reset selected class/relic state.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase30-session07-play-runtime-integration`
* Depended by: `phase30-session09-content-polish-and-mobile`, `phase30-session10-quality-gates-and-enablement`

***

## Next Steps

Run the `implement` workflow step to begin implementation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase30-session08-progression-depth/spec.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.