# HyperTwist Phase 4 clear-run repository-view continuity packet

Created on `2026-05-06`

Status:

- first-party HyperTwist packet
- bounded Phase `4` coach-to-review validation slice

## Purpose

This packet closes the next post-review continuity gap in the live recognition-assisted coach-to-review loop.

The open task is:

- preserve repository-derived carryover pressure, coach guidance, and queue state across `ClearActiveRun()` after a review run has already finalized truthfully

It is not:

- a new review-policy heuristic packet
- a new recognition transport packet
- a new queue-model redesign
- a dashboard layout packet

## Scope

Bounded lane:

- retain the minimum repository-view context needed after a run clears
- rebuild repository-derived coach and queue state from that retained context when no run is active
- keep active review-plan inspection cleared so the dashboard does not imply a run is still open
- let post-run coach launch surfaces resolve their focus deck from repository state instead of requiring a live run deck

Out of scope:

- new review scoring
- new persistence formats
- startup-wide multi-user queue arbitration
- broader subsystem decomposition

## Why this was the right next packet

Before this slice:

- review-start summary continuity was already landed
- review-finalization carryover continuity was already landed
- post-review carryover could survive explicit review-run completion inside repository state

But one clear-run seam was still wrong:

- `ClearActiveRun()` reset the live run state and then called `RefreshRepositoryViews()`
- `RefreshRepositoryViews()` treated `!ActiveRunState.Session.IsStructurallyValid()` as a full reset boundary
- that zeroed repository-derived coach brief, queue summary, learner deck summary, review-program summary, and dashboard-facing carryover pressure

That meant the product could preserve open review carryover in the repository and still lose it immediately in the coach/dashboard lane as soon as the run was cleared.

The practical consequence was:

- queue-backed follow-up pressure could disappear right after run clear
- post-review coach guidance could collapse to idle state even though carryover still existed
- dashboard inspection could look clean only because the repository-derived view had been zeroed, not because the review program was actually resolved

So the next honest move was:

- keep the active review plan cleared, but stop discarding valid repository-derived coach and queue state at the clear-run boundary

## What landed

Primary code changes:

- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingSubsystem.h`
  - added retained repository-view user/deck/reference fields plus private helpers for repository-view context and focus-deck resolution
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingSubsystem.cpp`
  - `ClearActiveRun()` now captures retained repository-view context before clearing the active run
  - `StartTrainingRunFromDeck()` clears retained idle-context state when a new run begins
  - `RefreshRepositoryViews()` now derives coach memory, review-program summary, queue state, and coach briefs from retained repository-view context when no run is active
  - recommended/follow-up deck builders now resolve their source deck from repository context instead of requiring a live active deck

## Product effect

The post-review boundary is now more truthful:

- explicit run clear no longer erases open carryover pressure that still exists in repository state
- coach guidance and queue materialization can remain visible after run clear when open review work still exists
- the dashboard can stay aligned with repository-derived carryover without reviving stale active-review-plan state
- launch-budget and queue-follow-up surfaces can still resolve a usable focus deck after run clear when repository context identifies one

## Acceptance criteria

- `ClearActiveRun()` preserves enough context for repository-derived coach state to survive the clear-run boundary
- `RefreshRepositoryViews()` no longer hard-resets repository-derived coach/queue state solely because there is no active run
- active review-plan inspection remains cleared when the run is gone
- coach recommended/follow-up deck resolution still works after the clear-run transition when repository focus deck context exists
- full product build succeeds

## Validation checklist

1. build `UnrealHyperTwist.sln` / `UnrealHyperTwistEditor`
2. confirm `ClearActiveRun()` captures retained repository-view context before zeroing the active run
3. confirm `RefreshRepositoryViews()` can derive coach and queue state from retained repository-view context when idle
4. confirm active review-plan state is still cleared after run clear
5. confirm coach deck builders resolve focus deck state without requiring a live active run deck

That is the packet.
