# HyperTwist Phase 4 template launch repository provenance packet

Created on `2026-05-06`

Status:

- first-party HyperTwist packet
- bounded Phase `4` repository-backed template provenance slice

## Purpose

This packet moves template-launch provenance out of dashboard-only retained state and into repository-backed run state and run history.

The open tasks were:

- persist template launch identity into the active run state itself
- carry that provenance into stored run records
- let the dashboard rebuild template-launch recap/history from repository state after widget refresh or rebuild

It is not:

- a repository schema migration packet
- a template browser or editor packet
- a coach weighting rewrite packet
- a broader run-history redesign

## Scope

Bounded lane:

- add a compact persisted template-launch provenance struct in training types
- store that provenance on `FHyperTwistTrainingRunState` and `FHyperTwistTrainingRunRecord`
- annotate template-backed subsystem launches so direct template runs and review-plan resume runs both persist provenance
- copy persisted provenance into run records during repository recording
- rebuild dashboard template-launch recap/history from repository run records instead of widget-only retained snapshots

Out of scope:

- changing dashboard template ranking
- changing review-plan scoring or recommendation rules
- widening into analytics consumers beyond existing dashboard history/recap
- changing non-template run persistence

## Why this was the right next packet

The previous packet made template launch provenance visible on the dashboard, but only as retained widget state.

That left an obvious continuity gap:

- widget rebuilds could discard template-launch identity
- dashboard history depended on the current widget lifetime instead of durable run records
- later coach weighting or analytics work still had no repository-backed template launch provenance to read

So the next honest move was:

- persist the launch provenance at the run-state layer
- let run-record recording carry it forward automatically
- and switch the dashboard history surface to read from repository state instead of only its own memory

## What landed

Primary code changes:

- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingTypes.h`
  - added `FHyperTwistTrainingTemplateLaunchProvenance`
  - added persisted template-launch provenance fields to `FHyperTwistTrainingRunState` and `FHyperTwistTrainingRunRecord`
  - moved `EHyperTwistTrainingSessionTemplateKind` earlier so the persisted provenance struct can use it
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingRepositoryLibrary.cpp`
  - `BuildRunRecord(...)` now copies template-launch provenance from active run state into stored run records
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingSubsystem.cpp`
  - added shared template-to-provenance projection helpers
  - `StartTrainingRunFromTemplate(...)` now persists template-launch provenance for direct launches and stored review-plan resume launches
  - `StartActiveMethodDrillFollowUpRun(...)` now persists the same provenance for template-backed follow-up launches
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistCoachDashboardWidget.h`
  - switched active/retained template launch cache members to the persisted provenance shape
  - replaced widget-only template-history recording with repository-sync plumbing
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistCoachDashboardWidget.cpp`
  - rehydrates active template-launch context from `CachedRunState.TemplateLaunchProvenance`
  - rebuilds `[Template Launch History]` from stored run records for the selected user
  - keeps recap rendering on the same provenance fields, now backed by repository state

## Product effect

Template-backed run provenance now survives beyond a single dashboard widget instance:

- active and completed template-backed runs carry `TemplateId`, `TemplateKind`, and `SourceReviewPlanId` in repository-backed run state/history
- dashboard template-launch history can be rebuilt after widget refresh or reconstruction
- later analytics or coach-weighting work can read template-launch provenance from stored run records instead of depending on transient UI memory

## Acceptance criteria

- template-backed launches persist provenance into active run state
- stored run records retain that provenance
- dashboard recap can rehydrate template launch context from cached repository-backed run state
- dashboard template-launch history rebuilds from repository run records
- full product build succeeds

## Validation checklist

1. build `UnrealHyperTwist.sln` / `UnrealHyperTwistEditor`
2. launch a template-backed run and confirm the active run state carries template provenance
3. complete or abort the run and confirm the dashboard template-launch history still appears after widget refresh/rebuild
4. confirm stored run records include template provenance for template-backed launches

That is the packet.
