> 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-session10-quality-gates-and-enablement/spec.md). # Session Specification **Session ID**: `phase30-session10-quality-gates-and-enablement` **Phase**: 30 - AI Rogue Game Extension **Status**: Not Started **Created**: 2026-06-22 *** ## 1. Session Overview This session closes Phase 30 by validating the accepted AI Rogue slice end to end and making the enablement decision from evidence. Sessions 02 through 09 delivered the registered disabled-first extension, lazy PixiJS runtime, economy and persistence contracts, deterministic simulation, playable route, progression depth, mobile controls, seed sharing, docs, and focused tests. The next required work is therefore a quality-gate pass across type safety, linting, formatting, unit tests, browser tests, production build, bundle budget, media policy, and private-runtime safeguards. The session is intentionally gate-first. New gameplay systems are out of scope; implementation work is limited to repairing failures uncovered by the required checks in existing AI Rogue code, tests, docs, or gate scripts. If all gates pass without source changes, the session still produces validation evidence, updated docs where needed, and a clear decision that AI Rogue remains disabled, becomes opt-in, or is safe for default enablement. The final decision must preserve the Phase 30 privacy and architecture boundaries: no remote loading, no script collectors, no raw private telemetry in browser state, no unbounded token-burn rewards, and no unreviewed media. If any required gate fails and cannot be repaired inside this session scope, AI Rogue remains disabled-first and the follow-up list records the blocker. *** ## 2. Objectives 1. Run and repair the required Phase 30 quality gates for the implemented AI Rogue slice. 2. Verify AI Rogue docs, visual asset provenance, route behavior, runtime cleanup, privacy posture, and media policy evidence match the current implementation. 3. Record a defensible enablement decision: disabled, opt-in, or default-enabled, based on gate results and non-goal checks. 4. Capture follow-up work for future AI Rogue content, collectors, WebGPU verification, worker protocol, audio, or expanded progression without widening this session. *** ## 3. Prerequisites ### Required Sessions * [x] `phase30-session02-extension-shell-and-routes` - Provides the registered disabled-first AI Rogue extension, views, routes, and registry tests. * [x] `phase30-session03-pixijs-runtime-boundary` - Provides lazy PixiJS v8 runtime ownership, canvas proof, resize/input/reset/visibility cleanup, and runtime boundary tests. * [x] `phase30-session04-economy-and-ledger` - Provides deterministic Insight Shards economy, manual claim behavior, daily caps, and privacy-safe ledger provenance. * [x] `phase30-session05-persistence-and-save-contracts` - Provides versioned browser-local persistence, IndexedDB wallet/ledger/run/save storage, and reset scope. * [x] `phase30-session06-dungeon-simulation-core` - Provides deterministic RNG, world generation, field of view, movement, enemy behavior, and combat simulation. * [x] `phase30-session07-play-runtime-integration` - Provides playable PixiJS integration, atlas rendering, controls, save/load, and run lifecycle. * [x] `phase30-session08-progression-depth` - Provides progression derivation, classes, relics, resources, achievements, run history, and loadout states. * [x] `phase30-session09-content-polish-and-mobile` - Provides seed sharing, compact controls, mobile framing, reduced-motion coverage, and no-audio documentation. ### Required Tools Or Knowledge * Bun 1.3.14 project scripts from `package.json`. * Vitest and Playwright command patterns for focused AI Rogue suites. * AI Rogue source, tests, docs, assets, registry, and gate scripts. * Phase 30 PRD, AI Rogue implementation baseline, visual asset provenance, and content/mobile notes. ### Environment Requirements * Local environment can run Bun, TypeScript, ESLint, Prettier, Vitest, Playwright, Vite build, bundle budget, asset-size, and private-runtime checks. * Browser environment supports the existing Playwright WebGL canvas pixel checks. * No external credentials, billing, or third-party dashboard action is required for this session. *** ## 4. Scope ### In Scope (MVP) * Maintainer can run all required quality gates and record pass/fail evidence - Use existing project scripts and focused AI Rogue command lanes. * Player-facing AI Rogue behavior remains stable under focused tests - Repair failures in economy, save migration, RNG, simulation, combat, canvas rendering, interaction, mobile layout, reduced motion, and route cleanup only when gates expose them. * Documentation reflects the implemented slice and enablement decision - Update AI Rogue docs, visual asset records, environment guidance, and changelog entries when the current implementation or decision differs from existing text. * Enablement posture is explicit - Decide disabled, opt-in, or default-enabled from evidence and update the smallest matching docs or env examples. * Future work is captured without implementation creep - Record deferred content, collectors, WebGPU, worker protocol, audio, and expanded progression follow-ups. ### Out Of Scope (Deferred) * New gameplay features, enemies, classes, relics, biomes, crafting, inventory, audio, gamepad, pointer lock, or content packs - Reason: this session validates and closes the accepted slice. * New collectors, generated content pipelines, remote loading, marketplace installs, hosted storage, admin writes, or database-backed game state - Reason: these require new threat-model and implementation sessions. * WebGPU verification or worker simulation - Reason: Phase 30 explicitly defers these until profiling or evidence justifies the widened runtime protocol. * Unreviewed media or large asset expansion - Reason: the committed gameplay and UI atlases are already the locked first-slice assets. *** ## 5. Technical Approach ### Architecture Start with deterministic validation and use gate output to drive the narrowest repair. Keep fixes inside existing AI Rogue modules, tests, docs, or local scripts. Do not change the static extension model, runtime ownership boundary, persistence schema semantics, or media policy unless a gate proves the current implementation contradicts the Phase 30 requirements. For code failures, repair the owning layer rather than weakening tests: economy and persistence fixes stay under `src/extensions/ai-rogue/`; deterministic simulation fixes stay under `src/extensions/ai-rogue/runtime/`; browser interaction fixes stay in the Play view, runtime canvas, renderer, and e2e tests. For docs or decision drift, update AI Rogue docs and environment guidance so the implemented state, disabled-first or opt-in posture, asset provenance, privacy boundary, and follow-ups are accurate. ### Design Patterns * Gate-led remediation: Run a named check, repair the smallest proven failure, and rerun the same check before moving on. * Existing-boundary ownership: Runtime fixes stay route-scoped and lazy; browser-local data fixes stay behind existing Zod schemas and persistence helpers. * Evidence record: Commands, outcomes, repairs, non-goal checks, and final enablement decision are captured in the session notes and AI Rogue closeout doc. * Disabled-first default: Keep AI Rogue disabled unless all required gates and docs/privacy checks support a more permissive posture. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------- | | `docs/extensions/ai-rogue/enablement-decision.md` | Final Session 10 gate evidence, enablement posture, non-goal checks, and follow-up list. | \~160 | | `.spec_system/specs/phase30-session10-quality-gates-and-enablement/implementation-notes.md` | Implementation evidence, commands run, repairs made, and residual risk for this session. | \~180 | ### Files To Modify | File | Changes | Est. Lines | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | | `docs/extensions/ai-rogue/README.md` | Add the enablement decision document and current closeout status to the AI Rogue document map. | \~20 | | `docs/extensions/ai-rogue/implementation-baseline.md` | Update baseline only for validated closeout posture, follow-ups, or changed locked decisions. | \~40 | | `docs/extensions/ai-rogue/visual-assets.md` | Confirm atlas sizes, provenance, and media-policy evidence after final asset-size checks. | \~40 | | `docs/extensions/ai-rogue/content-polish-mobile-notes.md` | Update final Session 09/10 validation references if browser or mobile gates require doc corrections. | \~30 | | `docs/environments.md` | Document AI Rogue enablement posture if the decision changes env guidance. | \~30 | | `.env.local.example` | Add or preserve the smallest accurate AI Rogue enablement example based on the final decision. | \~10 | | `docs/CHANGELOG.md` | Record Phase 30 AI Rogue closeout and enablement posture. | \~40 | | `src/extensions/ai-rogue/**/*.ts` | Repair gate-proven economy, persistence, RNG, simulation, combat, render-model, input, or runtime failures with schema-validated input and explicit error mapping. | \~0-220 | | `src/extensions/ai-rogue/**/*.tsx` | Repair gate-proven Play, Ledger, Loadout, Settings, runtime canvas, accessibility, busy-state, or responsive layout failures. | \~0-180 | | `src/lib/__tests__/extension-registry.test.ts` | Adjust enablement assertions only if the final posture changes registry expectations. | \~0-40 | | `src/lib/__tests__/setup-config-extensions.test.ts` | Adjust env parsing or setup guidance assertions only if final posture changes setup expectations. | \~0-40 | | `src/extensions/ai-rogue/**/__tests__/*` | Repair or add focused regression coverage for any gate-proven unit failures. | \~0-180 | | `tests/e2e/ai-rogue-*.spec.ts` | Repair or add focused browser coverage for route cleanup, mobile layout, reduced motion, persistence, ledger, or runtime failures. | \~0-180 | | `scripts/check-bundle-budget.sh` | Update budget classification only if measured build output proves a PixiJS chunk needs the documented watched-vendor allowance. | \~0-30 | | `scripts/check-asset-sizes.sh` | Update only if the final asset-size gate proves current AI Rogue media policy coverage misses committed runtime assets. | \~0-30 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Required quality commands pass or have explicit recorded failure evidence that keeps AI Rogue disabled-first. * [ ] AI Rogue route behavior remains correct for disabled, opt-in, and tested enabled states. * [ ] Runtime canvas, controls, persistence, seed replay, ledger claims, loadout progression, route cleanup, mobile layout, and reduced-motion behavior pass focused coverage. * [ ] Final enablement decision is recorded with evidence and reflected in docs or env examples where needed. * [ ] Future follow-ups are recorded without adding new gameplay, collector, remote loading, worker, WebGPU, audio, or media scope. ### Testing Requirements * [ ] `bun run typecheck` passes. * [ ] `bun run lint` passes. * [ ] `bun run format:check` passes or all session-owned formatting drift is repaired and legacy drift is documented as a follow-up. * [ ] Focused AI Rogue Vitest suites pass. * [ ] Focused AI Rogue Playwright suites pass. * [ ] `bun run build` passes. * [ ] `bun run budget:check` passes. * [ ] `bash scripts/check-asset-sizes.sh` passes. * [ ] `bun run runtime:check-private` passes. ### Non-Functional Requirements * [ ] No raw prompts, transcripts, command bodies, command output, private paths, credentials, secrets, logs, or raw private telemetry are exposed through AI Rogue UI, save data, shared URLs, docs, or generated artifacts. * [ ] No committed AI Rogue runtime asset exceeds the 200 KB media policy. * [ ] PixiJS remains lazy and route-scoped; AI Rogue runtime code does not enter the static registry, app shell, or non-game routes. * [ ] Browser-local persistence remains versioned, bounded, and recoverable from malformed data. ### Quality Gates * [ ] All files ASCII-encoded * [ ] Unix LF line endings * [ ] Code follows project conventions *** ## 8. Implementation Notes ### Working Assumptions * Session 10 is the next executable session: The analyzer reported Phase 30 active, no current session, sessions 01 through 09 completed, and only Session 10 unfinished. The Phase 30 PRD and stub both define Session 10 as the quality-gate and enablement closeout, so planning can proceed without user arbitration. * AI Rogue is currently registered but not default-enabled: `src/extensions/registry.ts` includes `ai-rogue`, while current docs and env examples gate visibility through `VITE_CLAUDE_OS_ENABLED_EXTENSIONS`. The plan therefore treats default enablement as a decision outcome, not an assumption. * Code repairs cannot be fully enumerated before gates run: The session objective is validation. Planning stays concrete by assigning repair lanes to existing AI Rogue source, test, doc, and script paths, and by requiring reruns of the exact failed gate after each repair. ### Key Considerations * Keep AI Rogue disabled-first unless all required gates, docs, privacy checks, and non-goal checks support opt-in or default enablement. * Respect the Phase 30 no-goals: no remote loading, no unbounded token-burn rewards, no new raw private telemetry, no unreviewed large media, and no collector or admin-write surface. * Preserve route-scoped PixiJS lifecycle cleanup and existing canvas pixel verification. * Treat repo-wide Prettier drift carefully: repair session-owned formatting, and record older unrelated drift only if it still blocks `format:check`. ### Potential Challenges * Repo-wide `format:check` may surface older drift from outside AI Rogue: Repair only when safe and relevant, otherwise document residual drift and keep the final decision conservative. * Playwright WebGL checks can be environment-sensitive: Rerun focused failures, preserve nonblank pixel checks, and avoid weakening assertions without source evidence. * Bundle budget may depend on generated chunk names: Use measured build output before changing `scripts/check-bundle-budget.sh`. * Enablement decision can affect user expectations: Update docs and env examples only to match the evidence-backed posture reached by the gates. ### Relevant Considerations * \[P00] **Stack conventions**: Bun, Vite 8, TanStack Start, React 19, PixiJS v8, and Cloudflare Worker compatibility shape all gate and repair work. * \[P02] **Static extension registry requires code changes**: AI Rogue remains a compile-time extension; no marketplace, dynamic loading, eval, or remote package loading is introduced. * \[P02] **Disabled-first collector pattern**: AI Rogue starts gated; any broader enablement requires explicit Session 10 evidence. * \[P02] **Extension payloads and labels stay bounded**: Browser-visible game state, seed/share text, ledger data, and docs stay bounded and browser-safe. * \[P27] **Repo-wide formatting drift remains**: Full `format:check` is required here, but older unrelated drift must be identified clearly instead of hidden. * \[P29] **Closeout cannot change feature posture**: Documentation can consolidate shipped behavior, but new source, schema, runtime, storage, hosted, credential, or admin-write surfaces need a future session. * \[P29] **Budget checks need separate labels**: Keep bundle gzip, extension payload, asset-size, and private-runtime checks distinct in validation records. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Gate repairs can accidentally weaken tests, relax privacy boundaries, or mask failures instead of fixing source behavior. * Enablement changes can expose an extension before disabled, opt-in, and enabled route states are all understood. * Runtime and persistence fixes can regress cleanup, busy-state protection, idempotent claims, malformed save handling, or mobile accessibility. *** ## 9. Testing Strategy ### Unit Tests * Focused AI Rogue suite: `bun run test -- $(rg --files src/extensions/ai-rogue | rg '(__tests__/.+\\.(test|spec)\\.(ts|tsx)$)' | sort)` * Registry/setup tests if enablement posture changes: `bun run test -- src/lib/__tests__/extension-registry.test.ts src/lib/__tests__/setup-config-extensions.test.ts` ### Integration Tests * Focused AI Rogue browser suite: `bunx playwright test $(rg --files tests/e2e | rg 'ai-rogue-.*\\.spec\\.ts$' | sort)` * Route tests if registry or route behavior changes: `bun run test -- src/routes/__tests__/extensions-routes.test.tsx src/components/__tests__/app-sidebar.test.tsx` ### Runtime Verification * Run `bun run typecheck`. * Run `bun run lint`. * Run `bun run format:check`. * Run `bun run build`. * Run `bun run budget:check`. * Run `bash scripts/check-asset-sizes.sh`. * Run `bun run runtime:check-private`. * Search no-audio and no-remote-loading boundaries with targeted `rg` commands over AI Rogue source, docs, package files, and lockfile. ### Edge Cases * AI Rogue disabled, explicitly enabled with `ai-rogue`, and broad `all` extension enablement. * Malformed save, duplicate claim, seed replay, route exit/re-entry, resize, reduced motion, unavailable WebGL, and mobile portrait viewport. * Legacy repo formatting drift outside Session 10 scope. * Asset-size record mismatch between committed files and `visual-assets.md`. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase30-session02-extension-shell-and-routes`, `phase30-session03-pixijs-runtime-boundary`, `phase30-session04-economy-and-ledger`, `phase30-session05-persistence-and-save-contracts`, `phase30-session06-dungeon-simulation-core`, `phase30-session07-play-runtime-integration`, `phase30-session08-progression-depth`, `phase30-session09-content-polish-and-mobile` * Depended by: Phase 30 closeout, `audit` phase-transition workflow, and future AI Rogue phases. *** ## 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-session10-quality-gates-and-enablement/spec.md?ask=&goal= ``` `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.