> 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/phase35-session02-fixed-blocker-regression-coverage/spec.md).

# Session Specification

**Session ID**: `phase35-session02-fixed-blocker-regression-coverage` **Phase**: 35 - AI Rogue Audit Hardening And Refactor **Status**: Not Started **Created**: 2026-06-26

***

## 1. Session Overview

This session locks the fixed AI Rogue default-enable blocker contracts behind direct regression evidence before later Phase 35 sessions refactor runtime, renderer, persistence, and world ownership. Session 01 rebaselined the audit and found no live default-enable blockers, so this session is evidence-first: verify the current guards, add or repair only missing focused assertions, and record the exact command evidence.

The work is next because Sessions 03-08 depend on stable regression coverage for lethal turn-start damage, assistive runtime summaries, fixture gating, transient feedback sprite bounds, simulation-owned pre-run state, durable claim validation, and durable saved-run hydration. The product posture remains Production Go with AI Rogue enabled by default and `none` as the explicit extension opt-out.

Implementation should preserve AI Rogue browser-local state, test-only fixture hooks, static Pages demo safety, and the no-new-D3 privacy boundary. Broad module extraction, new gameplay behavior, platform-failure harnesses, storage quota work, and documentation cleanup belong to later Phase 35 sessions.

***

## 2. Objectives

1. Verify or add direct lethal turn-start status damage regression coverage for Movement, Strike, Surge, and every Protocol branch.
2. Verify or add mounted runtime assistive summary coverage that changes after movement and includes motion, contrast, input, and run-state context.
3. Verify or add route and component coverage proving production Play ignores fixture scenario query params while local/test-only deterministic combat remains available.
4. Verify or add regression guards for transient feedback sprite cleanup, simulation-owned pre-run state, direct durable claim validation, and durable-to-runtime saved-run hydration.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase35-session01-rebaseline-audit-evidence` - Provides the current finding status ledger, downstream routing, fixed-versus-caveat classification, and current evidence anchors for Session 02.

### Required Tools Or Knowledge

* Bun 1.3.14 for Vitest, typecheck, and scripts.
* Playwright Chromium for focused AI Rogue browser regression checks.
* `rg`, `jq`, and spec-system scripts for evidence inventory and state checks.
* Current AI Rogue runtime, persistence, renderer, and route test structure.

### Environment Requirements

* Local dependencies installed from `bun.lock`.
* Browser binaries available for `bunx playwright test`.
* `src/data/live-data.json` can be seeded by `bun run seed:data` if absent.

***

## 4. Scope

### In Scope (MVP)

* AI Rogue maintainers can trust lethal turn-start status damage behavior across Movement, Strike, Surge, and Protocol branches - preserve or add focused unit assertions in `status-expanded.test.ts`.
* Screen-reader and compact-input users receive current runtime state after movement - preserve or add mounted runtime summary and mobile route assertions in `runtime-canvas.test.tsx` and `ai-rogue-mobile.spec.ts`.
* Production Play users cannot activate deterministic combat fixtures through query params - preserve or add component and route assertions while keeping the local test hook available.
* Runtime sprite lifecycle remains bounded during feedback-heavy runs - preserve or add renderer lifecycle coverage for inactive `feedback:*` sprites.
* Browser-local save and claim contracts stay schema-owned - preserve or add oversized claim rejection, idempotency, rollback, durable snapshot, and hydration helper coverage.
* Simulation remains owner of selected-upgrade and progression-loadout initialization - preserve or add pre-run state tests for create/update behavior and post-start rejection.

### Out Of Scope (Deferred)

* Runtime public API narrowing and reducer splits - Reason: assigned to Session 06 after regression guards are locked.
* Renderer scheduler, matchMedia, WebGL/Pixi asset, audio, and platform-failure hardening - Reason: assigned to Session 04.
* Storage quota or blocked IndexedDB browser harnesses - Reason: assigned to Session 05 unless an immediate regression is found here.
* Compact Inspect/Next target feature changes and Large HUD product work - Reason: assigned to Session 03.
* Documentation and media-policy cleanup - Reason: assigned to Session 09.
* New AI Rogue collectors, hosted writes, analytics, remote content, workers, WebGPU-only behavior, or expanded game content - Reason: requires fresh review and is outside Phase 35 Session 02.

***

## 5. Technical Approach

### Architecture

Treat the current tests and source as the baseline. Start by building a coverage map from Session 01 evidence and current AI Rogue test names, then run focused subsets before editing. If a contract already has direct coverage, record the evidence and avoid duplicate assertions. If a gap appears, add the smallest test or narrow source repair closest to the behavior owner.

Runtime correctness stays under `src/extensions/ai-rogue/runtime/__tests__/`. React bridge and accessibility coverage stays under `src/extensions/ai-rogue/__tests__/runtime-canvas.test.tsx` and focused Playwright specs. Browser-local persistence coverage stays under `persistence.test.ts`, `save-schema.test.ts`, and `claim-store.test.ts`.

### Design Patterns

* Evidence-first regression pass: Verify existing guards before adding new code because Session 01 classified these blockers as fixed.
* Behavior-owned tests: Keep assertions beside the runtime, renderer, route, or persistence owner they protect.
* Test-only fixture boundary: Use `window.__AI_ROGUE_LOCAL_TEST_SCENARIO__` for deterministic combat and keep product query params ignored.
* Schema-owned persistence: Durable claims and saved runs must parse through save-schema or persistence helpers before wallet, ledger, or runtime load state changes.

***

## 6. Deliverables

### Files To Create

| File                                                                                             | Purpose                                                                               | Est. Lines |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | ---------- |
| `.spec_system/specs/phase35-session02-fixed-blocker-regression-coverage/implementation-notes.md` | Evidence ledger for verified contracts, added guards, commands, and follow-on routing | \~250      |

### Files To Modify

| File                                                                   | Changes                                                                                          | Est. Lines |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------- |
| `src/extensions/ai-rogue/runtime/__tests__/status-expanded.test.ts`    | Verify or add lethal turn-start command matrix assertions                                        | \~20       |
| `src/extensions/ai-rogue/runtime/__tests__/pre-run-state.test.ts`      | Verify or add simulation-owned selected-upgrade and progression-loadout initialization guards    | \~25       |
| `src/extensions/ai-rogue/runtime/__tests__/renderer-lifecycle.test.ts` | Verify or add transient feedback sprite cleanup and pool bound assertions                        | \~25       |
| `src/extensions/ai-rogue/__tests__/runtime-canvas.test.tsx`            | Verify or add assistive summary, test-only fixture hook, and durable hydration bridge assertions | \~45       |
| `src/extensions/ai-rogue/__tests__/persistence.test.ts`                | Verify or add durable claim normalization, oversized rejection, and rollback assertions          | \~35       |
| `src/extensions/ai-rogue/__tests__/claim-store.test.ts`                | Verify or add legacy guard plus durable claim bridge regression assertions                       | \~25       |
| `src/extensions/ai-rogue/__tests__/save-schema.test.ts`                | Verify or add durable snapshot and hydration helper assertions                                   | \~35       |
| `tests/e2e/ai-rogue-runtime.spec.ts`                                   | Verify or add production scenario query and deterministic combat test-hook assertions            | \~25       |
| `tests/e2e/ai-rogue-mobile.spec.ts`                                    | Verify or add mobile assistive summary and compact control route assertions                      | \~25       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Lethal turn-start status damage prevents Movement, Strike, Surge, and every Protocol branch from mutating action state after defeat.
* [ ] Mounted runtime summary changes after movement and includes turn/run state, motion, contrast, and effective input context.
* [ ] Production Play routes ignore `?scenario=` fixture queries while the local test-only combat hook still mounts deterministic combat.
* [ ] Inactive transient `feedback:*` sprites are destroyed or bounded, and persistent inactive sprites are hidden without accidental destruction.
* [ ] Simulation-owned APIs initialize selected upgrade and progression loadout before turn zero and reject or ignore unsafe post-start mutation.
* [ ] Direct oversized durable claims cannot produce wallet and ledger drift.
* [ ] Durable saved-run snapshots hydrate through schema-owned helpers and malformed or unsafe snapshots fail explicitly.

### Testing Requirements

* [ ] Focused AI Rogue unit tests pass.
* [ ] Focused AI Rogue Playwright route tests pass.
* [ ] Typecheck and lint pass after any source or test changes.
* [ ] Privacy/capability scan confirms no new AI Rogue hosted/network primitive, bridge route, collector, analytics, or remote-loading surface.

### Non-Functional Requirements

* [ ] Regression coverage is behavior-focused and does not depend on brittle implementation internals where public helpers already exist.
* [ ] No new AI Rogue bundle, asset, or dependency surface is introduced.
* [ ] No new public-demo bridge, hosted write, collector, analytics, remote content, WebGPU-only path, or worker runtime is introduced.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Primary user-facing surfaces contain product-facing copy only; any deterministic scenario diagnostics remain in test hooks or test code.

***

## 8. Implementation Notes

### Working Assumptions

* Session 02 is a verify-or-add regression session, not a broad implementation session: Session 01 records lethal DOT, assistive summary, scenario gating, sprite cleanup, durable claim rejection, and durable hydration as already covered by current evidence. It is safe to proceed because the current test anchors exist in the repo and this plan includes commands to prove them.
* Application source edits are optional and should occur only when focused tests expose a missing guard: the Phase 35 stub says "verify or add", while Session 01 found no live blocker. It is safe to proceed because test-only evidence can satisfy this session when direct coverage already exists.
* This is not a monorepo session: the required analysis script reported no monorepo detection and no package registry. It is safe to use repo-root relative paths without package metadata.

### Conflict Resolutions

* The folded audit backlog includes historical blocker language, while Session 01 classifies the same blocker IDs as fixed. The chosen interpretation is to preserve current Production Go and lock the fixed contracts with direct evidence, adding tests only where an actual gap appears. This wins because Session 01 is the completed prerequisite and explicitly routes Session 02 to record existing direct regression evidence before adding tests.

### Key Considerations

* Keep AI Rogue browser-local and static-demo safe.
* Do not widen extension capabilities while adding or verifying regression tests.
* Later sessions depend on this coverage before refactor work begins.
* Keep focused test names clear enough to map back to AR-D6-001, AR-D2-001, AR-D1-002, AR-D4-001, AR-D1-001, AR-D5-001, and AR-D5-002.

### Potential Challenges

* Existing coverage may be split across unit and Playwright tests: Mitigation is to record a coverage map in implementation notes before adding assertions.
* Playwright runtime canvas checks can be slower than unit tests: Mitigation is to run focused AI Rogue specs first and avoid full-suite browser runs unless a touched path requires them.
* Durable save types are intentionally near runtime types: Mitigation is to test helper entry points and naming directly instead of relying on casts in view code.

### Relevant Considerations

* \[P34] **AI Rogue is production default-enabled**: Preserve default visibility and `none` opt-out while locking blocker coverage.
* \[P31-P34] **Pages and AI Rogue CI guards deferred**: Keep route and no-bridge evidence bundled even if this session runs focused checks.
* \[P31-P34] **Public-demo and AI Rogue gates stay bundled**: Avoid new bridge, hosted, collector, analytics, remote-loading, or private-runtime surfaces.
* \[P30/P32/P34] **Route-lazy runtime ownership scales**: Keep Pixi behind the Play route/local facade and React-owned assistive surfaces.
* \[P30/P32/P34] **Schema-backed browser-local state works**: Keep claims and durable saved-run hydration schema-owned.
* \[P34] **Do not expose deterministic fixtures through product routes**: Fixture scenarios remain local/test-only.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Fixed blocker regressions can look covered while missing one command branch or route path.
* Browser-local write paths can drift if wallet, ledger, legacy claim guard, and durable persistence do not share validation and rollback behavior.
* Accessibility regressions can hide behind a painted canvas unless the mounted DOM summary updates after real movement and preference changes.

***

## 9. Testing Strategy

### Unit Tests

* Run focused AI Rogue unit tests covering status, pre-run state, renderer lifecycle, runtime canvas, persistence, claim store, and save schema.
* Add or repair assertions only where focused evidence does not directly cover the Session 02 contract.

### Integration Tests

* Run focused Playwright specs for AI Rogue runtime, mobile, ledger, and persistence paths.
* Verify production route query handling and local test-only combat hook behavior through route-level assertions.

### Runtime Verification

* Use Playwright canvas pixel and DOM event checks already present in `ai-rogue-runtime.spec.ts` and `ai-rogue-mobile.spec.ts`.
* Verify the assistive summary region changes after movement and remains tied to the runtime bridge via `aria-describedby`.

### Edge Cases

* Lethal status damage before action resolution.
* Every Protocol branch under lethal status damage.
* Product route `?scenario=combat` ignored with seed replay preserved.
* Local test-only combat scenario still available through the window hook.
* Long or synthetic feedback descriptor sets with inactive feedback sprites.
* Oversized direct claims rejected before wallet and ledger mutation.
* Duplicate claims and durable transaction failure rollback.
* Empty, malformed, unsafe, and legacy durable saved-run snapshots.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase35-session01-rebaseline-audit-evidence`.
* Depended by: `phase35-session03-runtime-accessibility-controls`, `phase35-session04-renderer-robustness-and-scheduling`, `phase35-session05-persistence-schema-contracts`, `phase35-session06-simulation-ownership-refactor`.

***

## 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/phase35-session02-fixed-blocker-regression-coverage/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.