> 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/phase34-session01-characterization-test-harness/spec.md).

# Session Specification

**Session ID**: `phase34-session01-characterization-test-harness` **Phase**: 34 - AI Rogue Audit Remediation **Status**: Not Started **Created**: 2026-06-26

***

## 1. Session Overview

This session starts Phase 34 by adding focused characterization coverage for the AI Rogue audit findings that later sessions must fix or refactor around. It is next because the Phase 34 PRD marks Session 01 as the prerequisite for the accessibility, simulation, renderer, runtime API, and durable persistence work that follows.

The work covers five concrete seams from the audit: lethal turn-start status damage across Movement, Strike, Surge, and Protocol; dynamic runtime summaries reaching the mounted React/runtime bridge; transient Pixi feedback sprite pool growth; direct oversized claim validation; and durable saved-run conversion. The intent is to make high-risk behavior visible before product fixes and module splits begin.

This is a test-first session. It may add narrow test harness seams, but it does not change default enablement, gameplay balance, production fixture exposure, or user-facing AI Rogue product behavior.

***

## 2. Objectives

1. Add a lethal turn-start status matrix that covers Movement, Strike, Surge, and Protocol behavior with deterministic simulation fixtures.
2. Add mounted runtime summary characterization proving whether dynamic runtime summary text reaches a stable assistive DOM or canvas surface.
3. Add renderer/resource characterization for transient `feedback:*` sprite retention during long mounted or simulated render sequences.
4. Add durable persistence characterization for direct oversized claims and durable saved-run conversion before schema contract changes.

***

## 3. Prerequisites

### Required Sessions

* None - this is the first executable Phase 34 session.

### Required Tools Or Knowledge

* Bun 1.3.14 and project scripts in `package.json`.
* Existing AI Rogue Vitest coverage under `src/extensions/ai-rogue/**/__tests__/`.
* Existing AI Rogue Play e2e coverage under `tests/e2e/ai-rogue-*.spec.ts`.
* Audit finding IDs and remediation order from `.spec_system/PRD/phase_35/PRD_phase_35.md`.

### Environment Requirements

* Work from the repository root.
* Do not add dependencies, remote services, hosted storage, collectors, or public-demo runtime bridge calls.
* Keep AI Rogue state browser-local and explicit opt-in.
* Use existing Vitest and Playwright commands; record any baseline command failure in `implementation-notes.md` with exact command and output summary.

***

## 4. Scope

### In Scope (MVP)

* AI Rogue runtime maintainers can see lethal turn-start status behavior across all core command families - add deterministic unit coverage in the existing simulation/status test suite.
* AI Rogue accessibility maintainers can see whether mounted runtime summaries reach assistive technology surfaces - add bridge or DOM-level coverage in the runtime canvas test suite.
* AI Rogue renderer maintainers can observe transient feedback sprite retention pressure before sprite cleanup changes - add a mocked Pixi lifecycle characterization target.
* AI Rogue persistence maintainers can see direct claim and saved-run contract drift before schema helper work - add focused save-schema and persistence tests.
* Session implementers can trace every new test to audit finding IDs - record the mapping and any intentionally current-behavior assertions in session notes.

### Out Of Scope (Deferred)

* Fixing AR-D6-001 dynamic accessibility behavior - Reason: Session 02 owns product behavior and compact input remediation.
* Fixing AR-D2-001 lethal turn-start status handling or AR-D1-002 fixture exposure - Reason: Session 03 owns simulation and scenario-gate remediation.
* Fixing AR-D4-001 transient Pixi sprite retention or renderer fallback paths - Reason: Session 04 owns renderer lifecycle remediation.
* Renaming durable runtime snapshot types or adding schema-owned hydration helpers - Reason: Session 06 owns persistence/schema contract remediation.
* Flipping AI Rogue to default-enabled - Reason: Phase 34 closeout must first rerun gates and publish a recommendation.

***

## 5. Technical Approach

### Architecture

Use existing behavior-driven test locations rather than adding a new test framework. Simulation/status checks belong in `src/extensions/ai-rogue/runtime/__tests__/status-expanded.test.ts` or `simulation.test.ts`; mounted React/runtime bridge checks belong in `src/extensions/ai-rogue/__tests__/runtime-canvas.test.tsx`; durable state checks belong in `persistence.test.ts` and `save-schema.test.ts`.

For renderer characterization, avoid mounting real WebGL in unit tests. Add a small mocked Pixi lifecycle harness in `src/extensions/ai-rogue/runtime/__tests__/renderer-lifecycle.test.ts` and, if needed, extract a narrow internal helper from `src/extensions/ai-rogue/runtime/renderer.ts` without changing runtime behavior or exposing a user-facing diagnostic surface.

### Design Patterns

* Behavior tests near the owned module: keep characterization close to the code it constrains.
* Deterministic fixtures: use stable seeds and `createAiRogueWorldFromRows` instead of random or browser-only setup.
* Browser-safe boundaries: tests must not require generated private data, local bridge endpoints, hosted writes, collectors, or new runtime assets.
* Notes-backed characterization: when a passing test documents current audited behavior, record the finding ID and expected later remediation in `implementation-notes.md`.

***

## 6. Deliverables

### Files To Create

| File                                                                                         | Purpose                                                                                                    | Est. Lines |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------- |
| `.spec_system/specs/phase34-session01-characterization-test-harness/implementation-notes.md` | Baseline command evidence, finding-to-test map, current-behavior assertions, and handoff notes.            | \~140      |
| `src/extensions/ai-rogue/runtime/__tests__/renderer-lifecycle.test.ts`                       | Mocked renderer lifecycle coverage for transient feedback sprite retention and future sprite cleanup work. | \~180      |

### Files To Modify

| File                                                                | Changes                                                                                                                               | Est. Lines |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `src/extensions/ai-rogue/runtime/__tests__/status-expanded.test.ts` | Add lethal turn-start status command matrix helpers and assertions for Movement, Strike, Surge, and Protocol.                         | \~110      |
| `src/extensions/ai-rogue/runtime/__tests__/render-model.test.ts`    | Add render-summary source characterization that confirms summary text changes with meaningful snapshot state.                         | \~60       |
| `src/extensions/ai-rogue/__tests__/runtime-canvas.test.tsx`         | Add mounted bridge characterization for runtime summary propagation, save/load conversion, and compact control prereq seams.          | \~120      |
| `src/extensions/ai-rogue/__tests__/persistence.test.ts`             | Add direct oversized claim persistence characterization for wallet and ledger consistency risk.                                       | \~70       |
| `src/extensions/ai-rogue/__tests__/save-schema.test.ts`             | Add durable snapshot and saved-run conversion characterization that protects future schema helper work.                               | \~80       |
| `src/extensions/ai-rogue/runtime/renderer.ts`                       | Add a narrow internal test seam for sprite lifecycle characterization if the mocked renderer test cannot observe retention otherwise. | \~40       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Lethal turn-start status behavior is covered for Movement, Strike, Surge, and Protocol with deterministic fixtures.
* [ ] Mounted runtime summary behavior is covered at the React/runtime bridge or DOM accessibility surface, with movement-driven summary changes represented.
* [ ] Transient `feedback:*` sprite retention has a repeatable unit characterization target.
* [ ] Direct oversized claim behavior is covered so wallet and ledger amount drift cannot hide during Session 06.
* [ ] Durable saved-run conversion risk is covered with schema-owned or bridge-level characterization.

### Testing Requirements

* [ ] Focused AI Rogue unit tests written and passing or exact current-behavior caveats recorded.
* [ ] Relevant AI Rogue runtime or persistence e2e scenarios identified for later sessions.
* [ ] No tests require remote services, hosted storage, generated private data, or new dependencies.

### Non-Functional Requirements

* [ ] AI Rogue remains disabled-first and browser-local.
* [ ] Public-demo behavior makes no `/__*` bridge or mutation request changes.
* [ ] Test fixtures use deterministic seeds and bounded data.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] User-facing AI Rogue routes contain no test-only diagnostics.

***

## 8. Implementation Notes

### Working Assumptions

* Phase 34 Session 01 is the next executable session: `analyze-project.sh` reported `current_phase` 34, `current_session` null, zero completed Phase 34 sessions, and Session 01 as the first candidate. Planning can proceed because later stubs explicitly depend on Session 01 coverage.
* The repository is treated as a single package: the analysis script reported `monorepo` as null and no packages. All paths are repo-root-relative.
* Expected-failure test APIs will not be introduced in this plan: a source sweep found no existing `test.fails`, `it.fails`, or `todo` convention in the repo. Characterization should use enabled tests and session notes to distinguish current audited behavior from later desired remediation.

### Conflict Resolutions

* Session 01 says new tests should "fail or assert clearly against the audited behavior," while repo conventions require normal project tests to stay useful and there is no expected-failure convention. This plan chooses enabled, deterministic characterization tests plus explicit implementation notes for any current-behavior assertion. That preserves CI usability while still making the audited seams concrete before remediation.

### Key Considerations

* AR-D6-001, AR-D2-001, AR-D1-002, and AR-D4-001 remain the key default enablement findings until later sessions fix or explicitly carry them.
* Tests should characterize current behavior without adding product diagnostics to the Play surface.
* Any renderer test seam must remain internal to test code and must not become a browser-visible debug API.

### Potential Challenges

* Renderer internals are private and Pixi/WebGL-heavy: use mocked sprite and container objects or a small internal pure helper to avoid brittle browser setup.
* Lethal DOT setup can be hard to trigger naturally: build deterministic run state fixtures directly around known status effect and command paths.
* Durable saved-run type names currently overlap: use explicit imports and aliases so the test documents the confusion instead of adding more of it.

### Relevant Considerations

* \[P30/P32] **AI Rogue default enablement deferred**: This session adds proof for later recommendation work but does not flip default enablement.
* \[P31-P33] **Pages demo stays static-only**: Tests and notes must preserve no hosted writes, no collectors, no analytics, and no local bridge calls.
* \[P30/P32] **Route-lazy runtime ownership scales**: Keep Pixi behind runtime boundaries and let React own only coarse state, controls, and bridge checks.
* \[P30/P32] **Schema-backed browser-local state works**: Durable state tests should preserve Zod defaults, migrations, localStorage, IndexedDB, reset, and save contracts.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Characterization tests can accidentally encode the wrong future behavior if current-bug assertions are not mapped to audit IDs.
* Browser-facing accessibility checks can become implementation-detail tests unless they assert a real assistive surface.
* Persistence tests can hide privacy or state-boundary regressions if fixtures include private-looking strings or generated local data.

***

## 9. Testing Strategy

### Unit Tests

* Add and run focused Vitest coverage for status commands, render summaries, runtime canvas bridge behavior, persistence claims, durable save schema, and renderer lifecycle harness behavior.

### Integration Tests

* Identify existing Playwright scenarios in `tests/e2e/ai-rogue-runtime.spec.ts`, `tests/e2e/ai-rogue-mobile.spec.ts`, and `tests/e2e/ai-rogue-persistence.spec.ts` that later sessions should update after remediation.

### Runtime Verification

* Run focused AI Rogue unit tests and record command evidence in `implementation-notes.md`.
* Run a narrow AI Rogue e2e subset only if the implemented characterization changes touch Play bridge behavior that requires browser evidence.

### Edge Cases

* Lethal DOT before every core command family.
* Movement-driven summary text changes after a mounted runtime snapshot update.
* Long sequences of unique `feedback:*` descriptors.
* Direct oversized claim amounts above the 100-shard daily cap.
* Durable save slots with runtime state that must stay browser-safe.

***

## 10. Dependencies

### Other Sessions

* Depends on: none.
* Depended by: `phase34-session02-accessibility-and-compact-input`, `phase34-session03-simulation-correctness-and-scenario-gate`, `phase34-session04-renderer-lifecycle-and-robustness`, `phase34-session05-runtime-api-ownership`, `phase34-session06-persistence-schema-contracts`, and `phase34-session07-render-performance-and-audio-docs`.

***

## 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/phase34-session01-characterization-test-harness/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.