halkyon/docs/adr/0035-train-strength-plans.md

ADR 0035: Train's strength plans and sessions

• Status: decided 2 Nov 2026, by the developer (D1–D4, three of them the agent's recommendations, D2 the developer's own choice), the rest proposed by the agent and flagged where it chose.
• Builds on: ADR 0034 (the places, their equipment and the plate maths), ADR 0030 (Train: D7 sealed rows, D42 interval plans, D60 the tabs).

Context

ADR 0034 built the inventory and the plate maths, and left strength plans as the next step: a plan naming its exercises, sets, repetitions and weights, the plate changes between its sets ordered by the plate maths, and "the training offered adjusting" to the place chosen. Train records cardio alone so far: no model holds an exercise, a set or a repetition.

Decision

1. Exercises come from a catalogue, with the person's own beside them (D1, the recommendation taken). The catalogue (exercise_catalogue.dart) holds some 45 common exercises (squats, hinges, presses, rows, pull-ups, curls, extensions, raises, core, carries), each with:

   • what it needs (ExerciseNeed: a barbell, an EZ bar, a trap bar, dumbbells, a kettlebell, a bench, a rack, a pull-up bar, dip bars, a cable machine, bands), each met by a place's equipment (dumbbells by fixed dumbbells or by handles with plates);
   • what it is loaded with (ExerciseLoad: a barbell, an EZ bar or a trap bar with plates, a pair of dumbbells, one dumbbell, a kettlebell, a cable's stack, a band, the body), which decides how its weight is made up;
   • its pattern (MovementPattern: squat, lunge, hinge, horizontal and vertical push and pull, curl, extension, raise, calf, core, carry), by which swaps are found (D4);
   • whether it is counted in repetitions or held for a time. Its names are the app's texts, by the exercise's id. The person's own exercise is a name with the needs, load, pattern and measure they pick; it lives in the plans that use it (no table of its own), and the editor offers those of every plan again.

2. A plan is blocks of exercises, a block of several done in turn (D2, the developer's choice: supersets and circuits too). A block holds one exercise or more, each with its sets (repetitions or seconds, and a weight in grams where it is loaded), and a rest:

   • one exercise: its sets one after the other, the rest between them;
   • two (a superset) or more (a circuit): a round is each exercise's next set in turn, the rest after each round, and a rest between the exercises within a round (none by default). An exercise with fewer sets drops out of the later rounds. What a block is called (exercise, superset, circuit) follows from how many it holds.

3. This step records a session too (D3, the recommendation taken), on every device, as nothing in it needs the phone's sensors. The session screen leads set by set: the exercise, the set and round, the weight made up at the place chosen (D5) with the plates to change since the exercise's set before, the repetitions or the time, and Done; after it the rest counts down (a tone and a vibration as it ends, where the device has them), skippable. What was actually done is typed over what the plan said. A set can be skipped, an exercise swapped (D4), the session ended at any point. Saved, it is a workout of the new activity strength with what was done (WorkoutStrength: the plan's name, the place's, and each set done: its exercise, repetitions or seconds, weight and time), shown on the workout's page as the exercises with their sets. A session under way is kept in the person's strength_session.json after every change, so one cut off is offered again.

4. The place marks what it can't do and offers swaps (D4, the recommendation taken). A plan whose exercises the chosen place lacks something for is marked in the list, naming what is missing; a session's exercise the place can't do offers, in its place, the catalogue's exercises of the same pattern the place can, and any exercise can be swapped so. A swap holds for the session alone.

5. A strength plan is a sealed, synced row of its own (the agent's): the table strength_plan, as plan and training_place are, rather than a kind of plan, whose readers in released apps would show it as locked. The migration only creates the table, its space index and its cascade to the sync engine's spaces.

6. A strength workout keeps workout schema 1 (the agent's): the activity strength is new, and apps that don't know an activity already skip the workout rather than show it half (decodeWorkout); its sets are a field only strength workouts have. It goes to Health Connect as strength training, to FIT as training/strength training, to TCX as Other; it has no track, so no GPX.

7. How the weight is made up (the agent's): for a bar, the plate maths of ADR 0034 on the place's bar of that kind, the plates of the exercise's sets ordered by loadSeries so that its plate changes are fewest; for a pair of dumbbells, the place's fixed pair nearest at or below the weight, else two handles with plates; for one dumbbell or a kettlebell, the nearest at or below; a cable's stack, a band and the body take the weight as typed. Where nothing at the place makes the weight up, the session says so and takes it as typed.

8. Where it shows (the agent's): the Record tab gets a Strength card beside the activities, its Start offering the strength plans, and the strength plans are listed under the interval plans; where the device doesn't record, Profile's Plans tab lists both, a strength plan's Start there too.

Consequences

• Progression (raising a weight once every set was done) and a one-repetition maximum with weights as a share of it are left for later; the sets done are kept so that both can be worked out from them.
• A session runs in the app alone, not in a service: on Android a session left in the background keeps its time but rings its rest's end only while the app is open; the next step can hand it to the recorder's service if that matters in use.
• The catalogue grows by adding to it and its texts; an exercise's id never changes, as plans and workouts keep it.