# HyperTwist Phase 4 template launch selection provenance packet

Created on `2026-05-07`

Status:

- first-party HyperTwist packet
- bounded Phase `4` dashboard template selection persistence slice

## Purpose

This packet persists why the dashboard chose a template when analytics broke a tied launch decision.

The open tasks were:

- stop leaving dashboard template tie-break reasoning in widget-only state
- stamp the analytics tie-break decision onto the launched run itself
- make repo-backed template run history capable of showing not just which template launched, but which tied peer it beat and why

It is not:

- a new template analytics derivation packet
- a dashboard priority rewrite packet
- a broader run-history schema redesign packet
- a new review-plan or method-drill semantics packet

## Scope

Bounded lane:

- add a small structured template-launch selection provenance payload to persisted template launch provenance
- let the dashboard preferred-template selector emit structured analytics tie-break provenance
- add a subsystem path to stamp that provenance onto the active run and re-record the run state
- carry the persisted selector provenance through dashboard template history and run recap detail surfaces

Out of scope:

- persisting selector provenance for non-dashboard launch paths
- changing which templates are eligible for dashboard launch
- changing repository analytics aggregation rules
- adding a separate selector-audit screen

## Why this was the right next packet

The previous packet explained the analytics tie-break on the live dashboard launch surface.

That still left one obvious gap:

- operators could see why the current preferred template won before launch
- but that selector decision disappeared into widget state once the run was started
- and repo-backed run history still knew only which template launched, not which tied peer it beat or why

So the next honest move was:

- persist the selector decision into the launched run provenance itself
- keep the payload small and structured
- and let the existing recap/history surfaces read it back from stored run records

## What landed

Primary code changes:

- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingTypes.h`
  - added `EHyperTwistTrainingTemplateLaunchSelectionReasonClass`
  - added `FHyperTwistTrainingTemplateLaunchSelectionProvenance`
  - nested the new selection provenance under `FHyperTwistTrainingTemplateLaunchProvenance`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingSubsystem.h`
  - added a subsystem entry point for recording active-run template launch selection provenance
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingSubsystem.cpp`
  - stamps selection provenance onto the active run and re-records that run into repository state
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistCoachDashboardWidget.h`
  - widened template launch history entry state and selector/capture signatures to carry structured selection provenance
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistCoachDashboardWidget.cpp`
  - emits structured analytics tie-break provenance from the preferred-template selector
  - persists that provenance immediately after a successful dashboard template launch
  - carries the persisted selector provenance into active template launch context, template launch history detail, and run recap detail

## Product effect

Template launch auditing is now durable:

- when the dashboard launches a template because analytics broke a tie, that decision is written into repo-backed run history
- the stored payload includes the selector source, reason class, tied peer template, and a concise decision summary
- dashboard template launch history can now show that selector provenance for completed runs
- template-backed run recap can show the same selector provenance after launch, not only before launch

## Acceptance criteria

- analytics tie-break selection provenance is persisted on launched template-backed runs
- the persisted payload includes reason class and tied peer template context
- dashboard template launch history can read selector provenance from stored run records
- template-backed run recap can read selector provenance from stored run provenance
- full product build succeeds

## Validation checklist

1. build `UnrealHyperTwist.sln` / `UnrealHyperTwistEditor`
2. confirm an analytics tie-break template launch stamps selector provenance onto the active run
3. confirm repo-backed template launch history shows the stored selector provenance
4. confirm template-backed run recap shows the same stored selector provenance after launch completion

That is the packet.
