repwise 3.1.0__tar.gz → 3.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. {repwise-3.1.0/src/repwise.egg-info → repwise-3.3.0}/PKG-INFO +3 -3
  2. {repwise-3.1.0 → repwise-3.3.0}/README.md +2 -2
  3. {repwise-3.1.0 → repwise-3.3.0}/pyproject.toml +1 -1
  4. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/__init__.py +1 -1
  5. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/app/update.py +35 -8
  6. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/domain/models.py +73 -0
  7. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/domain/progression.py +150 -25
  8. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/planner.py +129 -25
  9. {repwise-3.1.0 → repwise-3.3.0/src/repwise.egg-info}/PKG-INFO +3 -3
  10. {repwise-3.1.0 → repwise-3.3.0}/tests/test_models.py +74 -0
  11. {repwise-3.1.0 → repwise-3.3.0}/tests/test_planner.py +188 -8
  12. {repwise-3.1.0 → repwise-3.3.0}/tests/test_progression.py +217 -22
  13. {repwise-3.1.0 → repwise-3.3.0}/tests/test_update.py +18 -0
  14. {repwise-3.1.0 → repwise-3.3.0}/LICENSE +0 -0
  15. {repwise-3.1.0 → repwise-3.3.0}/setup.cfg +0 -0
  16. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/__main__.py +0 -0
  17. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/app/__init__.py +0 -0
  18. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/app/checking.py +0 -0
  19. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/app/fetch.py +0 -0
  20. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/app/importing.py +0 -0
  21. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/app/listing.py +0 -0
  22. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/app/logout.py +0 -0
  23. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/app/report.py +0 -0
  24. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/checker.py +0 -0
  25. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/cli/__init__.py +0 -0
  26. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/cli/completion.py +0 -0
  27. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/cli/parser.py +0 -0
  28. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/config.py +0 -0
  29. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/domain/__init__.py +0 -0
  30. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/domain/effort.py +0 -0
  31. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/domain/matching.py +0 -0
  32. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/dumps.py +0 -0
  33. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/errors.py +0 -0
  34. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/garmin/__init__.py +0 -0
  35. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/garmin/catalog.py +0 -0
  36. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/garmin/client.py +0 -0
  37. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/garmin/payloads.py +0 -0
  38. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/importer.py +0 -0
  39. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/log.py +0 -0
  40. {repwise-3.1.0 → repwise-3.3.0}/src/repwise/yamlio.py +0 -0
  41. {repwise-3.1.0 → repwise-3.3.0}/src/repwise.egg-info/SOURCES.txt +0 -0
  42. {repwise-3.1.0 → repwise-3.3.0}/src/repwise.egg-info/dependency_links.txt +0 -0
  43. {repwise-3.1.0 → repwise-3.3.0}/src/repwise.egg-info/entry_points.txt +0 -0
  44. {repwise-3.1.0 → repwise-3.3.0}/src/repwise.egg-info/requires.txt +0 -0
  45. {repwise-3.1.0 → repwise-3.3.0}/src/repwise.egg-info/top_level.txt +0 -0
  46. {repwise-3.1.0 → repwise-3.3.0}/tests/test_catalog.py +0 -0
  47. {repwise-3.1.0 → repwise-3.3.0}/tests/test_checker.py +0 -0
  48. {repwise-3.1.0 → repwise-3.3.0}/tests/test_checking.py +0 -0
  49. {repwise-3.1.0 → repwise-3.3.0}/tests/test_cli.py +0 -0
  50. {repwise-3.1.0 → repwise-3.3.0}/tests/test_client.py +0 -0
  51. {repwise-3.1.0 → repwise-3.3.0}/tests/test_completion.py +0 -0
  52. {repwise-3.1.0 → repwise-3.3.0}/tests/test_config.py +0 -0
  53. {repwise-3.1.0 → repwise-3.3.0}/tests/test_dumps.py +0 -0
  54. {repwise-3.1.0 → repwise-3.3.0}/tests/test_effort.py +0 -0
  55. {repwise-3.1.0 → repwise-3.3.0}/tests/test_fetch.py +0 -0
  56. {repwise-3.1.0 → repwise-3.3.0}/tests/test_importer.py +0 -0
  57. {repwise-3.1.0 → repwise-3.3.0}/tests/test_importing.py +0 -0
  58. {repwise-3.1.0 → repwise-3.3.0}/tests/test_listing.py +0 -0
  59. {repwise-3.1.0 → repwise-3.3.0}/tests/test_log.py +0 -0
  60. {repwise-3.1.0 → repwise-3.3.0}/tests/test_logout.py +0 -0
  61. {repwise-3.1.0 → repwise-3.3.0}/tests/test_main.py +0 -0
  62. {repwise-3.1.0 → repwise-3.3.0}/tests/test_matching.py +0 -0
  63. {repwise-3.1.0 → repwise-3.3.0}/tests/test_payloads.py +0 -0
  64. {repwise-3.1.0 → repwise-3.3.0}/tests/test_report.py +0 -0
  65. {repwise-3.1.0 → repwise-3.3.0}/tests/test_yamlio.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: repwise
3
- Version: 3.1.0
3
+ Version: 3.3.0
4
4
  Summary: Advance Garmin strength workout targets using double progression
5
5
  Author-email: Adam Żmuda <adam@zmuda.pro>
6
6
  License-Expression: MIT
@@ -81,8 +81,8 @@ session, so training A and then B and running once brings both up to date:
81
81
 
82
82
  1. Start at the bottom of the rep range.
83
83
  2. Add a rep to every set each session.
84
- 3. Once every set reaches the top of the range, add weight and reset to the
85
- bottom.
84
+ 3. Once every set reaches the top of the range twice, add weight and reset to
85
+ the bottom.
86
86
  4. If you missed the target, repeat it unchanged.
87
87
  5. A load only counts once you can carry it for the bottom of the range.
88
88
 
@@ -54,8 +54,8 @@ session, so training A and then B and running once brings both up to date:
54
54
 
55
55
  1. Start at the bottom of the rep range.
56
56
  2. Add a rep to every set each session.
57
- 3. Once every set reaches the top of the range, add weight and reset to the
58
- bottom.
57
+ 3. Once every set reaches the top of the range twice, add weight and reset to
58
+ the bottom.
59
59
  4. If you missed the target, repeat it unchanged.
60
60
  5. A load only counts once you can carry it for the bottom of the range.
61
61
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "repwise"
7
- version = "3.1.0"
7
+ version = "3.3.0"
8
8
  description = "Advance Garmin strength workout targets using double progression"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -1,4 +1,4 @@
1
1
  """Advance Garmin strength workout targets using double progression."""
2
2
 
3
3
  __all__ = ["__version__"]
4
- __version__ = "3.1.0"
4
+ __version__ = "3.3.0"
@@ -15,6 +15,7 @@ from ..config import ConfigError, record_workout_id
15
15
  from ..domain.matching import normalise
16
16
  from ..domain.models import Config, ExerciseSpec, Workout
17
17
  from ..domain.progression import (
18
+ CONFIRMED_AFTER,
18
19
  PerformedSet,
19
20
  Session,
20
21
  Target,
@@ -29,6 +30,7 @@ from ..planner import (
29
30
  History,
30
31
  Performed,
31
32
  Plan,
33
+ decided_markers,
32
34
  decided_targets,
33
35
  executed_targets,
34
36
  find_workout,
@@ -186,7 +188,7 @@ def sessions_before(
186
188
  def wants_more(
187
189
  spec: ExerciseSpec, logged: list[PerformedSet], earlier: list[Session]
188
190
  ) -> bool:
189
- """Whether one more session back could still change this exercise's streak.
191
+ """Whether one more session back could still change this exercise's answer.
190
192
 
191
193
  The walk that counts a streak stops of its own accord at a session that
192
194
  hit, at a change of load, or at `sets - 1` misses. If instead it ran off
@@ -194,8 +196,15 @@ def wants_more(
194
196
  back is worth fetching; anything else is already settled. So one activity
195
197
  answers a smoothly progressing exercise, and only a genuine stall reads
196
198
  deeper.
199
+
200
+ The floor of `CONFIRMED_AFTER` is what rule 3's two-session confirmation
201
+ needs, and it only ever binds on a single-set exercise. Everything else
202
+ already reads at least one session back for the miss streak, which is the
203
+ same session the confirmation asks about; at one set `sets - 1` is none at
204
+ all, and without the floor a single-set exercise would arrive at the top of
205
+ its range with no history to confirm against and hold there forever.
197
206
  """
198
- limit = max(spec.sets - 1, 0)
207
+ limit = max(spec.sets - 1, CONFIRMED_AFTER)
199
208
  if not logged or len(earlier) >= limit:
200
209
  # Not trained in the session being judged, so there is nothing for a
201
210
  # streak to explain -- or already as deep as the rules can read.
@@ -316,6 +325,7 @@ def sync_other_workouts(
316
325
  config: Config,
317
326
  source: Workout,
318
327
  targets: dict[str, Target],
328
+ markers: dict[str, str],
319
329
  ) -> list[Plan]:
320
330
  """Propagate decided targets into every other workout that shares them.
321
331
 
@@ -324,6 +334,10 @@ def sync_other_workouts(
324
334
  name, and the weight one of them earned is not a weight the other can be
325
335
  asked for: 20 kg of gym machine says nothing about a pair of dumbbells.
326
336
  Such an entry is left where it is, to be moved by its own sessions.
337
+
338
+ `markers` is carried on the same terms and gated the same way. A miss is
339
+ about the exercise as it was actually loaded, so a miss on the gym cable
340
+ says nothing about the same movement done on a band at home.
327
341
  """
328
342
  loads = {normalise(spec.garmin_name): spec.load for spec in source.exercises}
329
343
 
@@ -333,15 +347,22 @@ def sync_other_workouts(
333
347
  continue
334
348
 
335
349
  carried: dict[str, Target] = {}
350
+ held: dict[str, str] = {}
336
351
  for spec in other.exercises:
337
352
  name = normalise(spec.garmin_name)
338
- if name in targets and spec.load == loads.get(name):
353
+ if spec.load != loads.get(name):
354
+ continue
355
+ if name in targets:
339
356
  carried[name] = targets[name]
340
- if not carried:
357
+ if name in markers:
358
+ held[name] = markers[name]
359
+ # A hold moves no target, so a workout worth visiting for its notes
360
+ # alone is the ordinary case rather than an edge one.
361
+ if not carried and not held:
341
362
  continue
342
363
 
343
364
  payload = payloads[garmin_id(other)]
344
- plan = plan_sync(other, payload, carried, source.key)
365
+ plan = plan_sync(other, payload, carried, held, source.key)
345
366
  if not plan.writable:
346
367
  continue
347
368
 
@@ -454,10 +475,16 @@ def advance_trained(
454
475
  report_plan(plan)
455
476
  plans.append(plan)
456
477
 
457
- # Anything that moved must move everywhere that exercise appears.
478
+ # Anything that moved must move everywhere that exercise appears, and
479
+ # so must a hold - which moves nothing, so it has to be asked for
480
+ # separately or a stalled exercise would carry its marker in one
481
+ # workout and not in the others.
458
482
  targets = decided_targets(plan)
459
- if targets:
460
- plans.extend(sync_other_workouts(payloads, config, workout, targets))
483
+ markers = decided_markers(plan)
484
+ if targets or markers:
485
+ plans.extend(
486
+ sync_other_workouts(payloads, config, workout, targets, markers)
487
+ )
461
488
 
462
489
  return plans, usable
463
490
 
@@ -5,6 +5,7 @@ lives in, and the settings that govern progression. Nothing here reads a file
5
5
  or talks to Garmin.
6
6
  """
7
7
 
8
+ import re
8
9
  from collections.abc import Iterator
9
10
  from dataclasses import dataclass, field
10
11
 
@@ -28,6 +29,78 @@ READABLE_NOTE = 160
28
29
  #: warned about long before it reaches one.
29
30
  STORED_NOTE = 512
30
31
 
32
+ #: The word a note carries while an exercise is holding after a missed target.
33
+ #: Short because it is read on a watch mid-set, and because every character
34
+ #: here is one the cue behind it does not get.
35
+ HOLD = "hold"
36
+
37
+ #: What a hold marker looks like, matched against a whole `|`-separated field
38
+ #: rather than searched for.
39
+ #:
40
+ #: Anchored on purpose. A cue is free text that a user typed, and one of them
41
+ #: begins "hold the chair, lean away" - searching for the word would read that
42
+ #: as a marker, and clearing it would delete the cue. Only a field that is
43
+ #: exactly `hold`, `hold x3` or `hold x3+` and nothing else counts.
44
+ HOLD_MARKER = re.compile(rf"^{HOLD}(?: x\d+\+?)?$")
45
+
46
+
47
+ def hold_marker(streak: int, sets: int) -> str:
48
+ """The marker for a session that just missed, `streak` misses behind it.
49
+
50
+ `streak` comes from `miss_streak`, which counts the sessions before the
51
+ latest one, so the figure shown is one more than it: the session that has
52
+ just been judged missed too, and a lifter reading "x2" wants the total
53
+ rather than the history behind it.
54
+
55
+ `miss_streak` stops counting at `sets - 1` because past there the advance
56
+ is already pinned at its minimum and no further history could change the
57
+ target. That bound is invisible to the rules and would be a lie to a
58
+ reader, so a saturated count is marked with a `+`: `hold x3+` on a
59
+ three-set exercise means three *or more*, which is all this can honestly
60
+ say.
61
+ """
62
+ misses = streak + 1
63
+ if misses == 1:
64
+ return HOLD
65
+ saturated = "+" if streak >= max(sets - 1, 0) else ""
66
+ return f"{HOLD} x{misses}{saturated}"
67
+
68
+
69
+ def _split_note(note: str) -> tuple[str, str, str]:
70
+ """A note as its fixed head, its marker, and everything after.
71
+
72
+ The head is the two fields `ExerciseSpec.note` always writes - the rep span
73
+ and the load - and the tail is the cue, which is free text and may hold
74
+ `|` of its own. So the split is bounded rather than greedy: exactly two
75
+ separators to reach the field a marker could occupy, and one more to step
76
+ over it. Anything the cue contains after that is carried whole.
77
+ """
78
+ parts = note.split(" | ", 2)
79
+ if len(parts) < 3:
80
+ return note, "", ""
81
+ head = " | ".join(parts[:2])
82
+ field, _, rest = parts[2].partition(" | ")
83
+ if HOLD_MARKER.match(field):
84
+ return head, field, rest
85
+ return head, "", parts[2]
86
+
87
+
88
+ def marker_of(note: str) -> str:
89
+ """The hold marker a note is carrying, or empty where it has none."""
90
+ return _split_note(note)[1]
91
+
92
+
93
+ def with_marker(note: str, marker: str) -> str:
94
+ """The same note carrying exactly `marker`, which empty clears.
95
+
96
+ Idempotent by construction: a note already carrying the marker asked for
97
+ comes back unchanged, which is what lets `update` run twice over one
98
+ session and write nothing the second time.
99
+ """
100
+ head, _, rest = _split_note(note)
101
+ written = " | ".join(part for part in (head, marker, rest) if part)
102
+ return written[:STORED_NOTE]
103
+
31
104
 
32
105
  @dataclass(frozen=True)
33
106
  class LoadTier:
@@ -11,8 +11,8 @@ The rules, as written in README.md:
11
11
  2. Each workout, add a rep to every set, e.g. 7-7-7, then 8-8-8 -- but after a
12
12
  stall, to only some of them, so that the way back up is gentler than the way
13
13
  that failed.
14
- 3. Once all sets reach the upper end, increase the weight and reset to the
15
- lower end.
14
+ 3. Once all sets reach the upper end, hold it there for a second session, then
15
+ increase the weight and reset to the lower end.
16
16
  4. If you didn't match the previous result, stay at the same weight and reps.
17
17
  5. A load is only adopted once it can be carried for the bottom of the range.
18
18
  Lift something other than what was prescribed and come up short of rep_low
@@ -131,6 +131,37 @@ def working_weight(performed: list[PerformedSet]) -> float:
131
131
  return max(counts, key=lambda weight: (counts[weight], weight))
132
132
 
133
133
 
134
+ def _counted_reps(performed: list[PerformedSet], weight: float) -> list[int]:
135
+ """The reps a session at `weight` is judged on, hardest sets included.
136
+
137
+ The sets at the working weight, plus any carried at a *heavier* load for at
138
+ least the reps those managed: harder than asked is not worse than asked,
139
+ and a session split across two loads is still a whole session. Without this
140
+ the set count is taken from one load alone, and three sets done as two at
141
+ 20 kg and one at 30 kg read as an abandoned session rather than a finished
142
+ one.
143
+
144
+ What a heavier set contributes is its own rep count, which is a lower bound
145
+ on what it would have managed at the lighter load, so this can only ever
146
+ add sets to the tally - never flatter the reps, since every set it adds is
147
+ at or above the floor and `min` is left where it was. A set that came up
148
+ *short* at the heavier load counts for nothing, which is what keeps a
149
+ failed top set from reading as a completed session.
150
+
151
+ Empty when nothing was done at `weight`, which only a caller inventing a
152
+ load can produce: `working_weight` always names one of the loads used.
153
+ """
154
+ at_weight = [entry.reps for entry in performed if entry.weight == weight]
155
+ if not at_weight:
156
+ return []
157
+ floor = min(at_weight)
158
+ return at_weight + [
159
+ entry.reps
160
+ for entry in performed
161
+ if entry.weight > weight and entry.reps >= floor
162
+ ]
163
+
164
+
134
165
  def hit(spec: ExerciseSpec, target: Target, reps: list[int]) -> bool:
135
166
  """Whether a session met what was asked of it.
136
167
 
@@ -187,6 +218,62 @@ def miss_streak(spec: ExerciseSpec, history: list[Session], weight: float) -> in
187
218
  return streak
188
219
 
189
220
 
221
+ #: How many sessions must already have cleared the top of the range for this
222
+ #: one to earn the load. One, so the weight moves on the *second* session at
223
+ #: `rep_high` rather than on the first.
224
+ #:
225
+ #: This is ACSM's own condition for adding load, which asks for the surplus on
226
+ #: "two consecutive training sessions" - see `top_streak` for the quote and
227
+ #: `docs/progression.md` for the reference. A single session at the top of the
228
+ #: range can be a good day rather than a new capacity: better sleep, a longer
229
+ #: rest, a kinder rep judgement. Rule 3 spending that day on a load increase is
230
+ #: what sets up the stall rule 4 then has to unwind, and asking for it twice is
231
+ #: the cheapest filter there is - one extra session, only ever at the top of
232
+ #: the range, and only ever immediately before a jump.
233
+ CONFIRMED_AFTER = 1
234
+
235
+
236
+ def top_streak(spec: ExerciseSpec, history: list[Session], weight: float) -> int:
237
+ """How many sessions in a row cleared the top of the range, before the latest.
238
+
239
+ ACSM's 2009 position stand asks for a "2-10% increase in load [...] when the
240
+ individual can perform the current workload for one to two repetitions over
241
+ the desired number on two consecutive training sessions". This counts the
242
+ consecutive sessions; `CONFIRMED_AFTER` says how many rule 3 wants.
243
+
244
+ `history` is the sessions before the one being judged, newest first, and
245
+ `weight` the load that one was worked at - the same arguments `miss_streak`
246
+ takes, because this is its mirror: not how long an exercise has been
247
+ failing its target, but how long it has been clearing the top of its range
248
+ at one load. The walk stops at:
249
+
250
+ - the first session that did not clear it, which is what ends a run;
251
+ - a change of load, because clearing the top at 20 kg says nothing about
252
+ whether 22.5 kg has been earned - the confirmation belongs to the load
253
+ being confirmed;
254
+ - `CONFIRMED_AFTER`, past which nothing could change the answer: the load
255
+ moves on that session and the next one restarts at `rep_low`, so a longer
256
+ run does not exist to be found.
257
+
258
+ A session too short to judge does not clear anything. That is rule 3's own
259
+ set count, applied to history for the same reason: a session that would
260
+ have consolidated rather than advanced cannot confirm a jump either.
261
+ """
262
+ streak = 0
263
+
264
+ for session in history:
265
+ if streak >= CONFIRMED_AFTER:
266
+ break
267
+ if not session.performed or working_weight(session.performed) != weight:
268
+ break
269
+ counted = _counted_reps(session.performed, weight)
270
+ if len(counted) < spec.sets or min(counted) < spec.rep_high:
271
+ break
272
+ streak += 1
273
+
274
+ return streak
275
+
276
+
190
277
  #: How many sessions must have missed *before* this one for it to count as a
191
278
  #: stall rather than a bad day. One, so the target eases on the second miss in
192
279
  #: a row - and, because easing has to bottom out in the range before the load
@@ -195,6 +282,34 @@ def miss_streak(spec: ExerciseSpec, history: list[Session], weight: float) -> in
195
282
  #: they wait three failures because they have no rep range to give first.
196
283
  STALLED_AFTER = 1
197
284
 
285
+ #: How every reason for a session that fell short of its target begins.
286
+ #:
287
+ #: The rules say what a session earned by returning a target; whether it
288
+ #: *failed* is a second question, and only the reason string distinguishes a
289
+ #: target that held because the session missed from one that held because
290
+ #: there was nothing to learn. Matching on the reason is the cheap way to ask
291
+ #: it - `next_target` has one caller in the application and around a hundred
292
+ #: in the tests, so widening its return to carry a flag would churn all of
293
+ #: them to answer a question only the note asks.
294
+ #:
295
+ #: The cost is a list that has to be kept in step with the reasons below it,
296
+ #: which `test_every_miss_is_recognised` is there to enforce: it walks each
297
+ #: failing path and asserts `missed` knows it. Add a reason without adding it
298
+ #: here and that test fails rather than the marker quietly never appearing.
299
+ MISS_REASONS = ("missed target", "missed twice", "stalled at the bottom")
300
+
301
+
302
+ def missed(reason: str) -> bool:
303
+ """Whether a reason from `next_target` reports a session that fell short.
304
+
305
+ Deliberately narrower than "the target did not go up". A session that
306
+ logged too few sets to judge, or one that came in under `rep_low` at a
307
+ load nobody prescribed, also leaves the target where it was - but neither
308
+ is a failed attempt at the figure on the watch, and telling someone to
309
+ hold a number they never really tried for would be noise.
310
+ """
311
+ return reason.startswith(MISS_REASONS)
312
+
198
313
 
199
314
  def _ladder(spec: ExerciseSpec, target: Target) -> int:
200
315
  """Where a target sits on the ladder, so two of them can be compared.
@@ -328,6 +443,7 @@ def _advance( # noqa: PLR0913 - each argument is one independent input
328
443
  streak: int,
329
444
  *,
330
445
  bodyweight: float = 0.0,
446
+ topped: int = 0,
331
447
  ) -> tuple[Target, str]:
332
448
  """Move a session that counted, by an amount the streak behind it decides.
333
449
 
@@ -386,6 +502,21 @@ def _advance( # noqa: PLR0913 - each argument is one independent input
386
502
  Target(spec.rep_high, weight),
387
503
  f"top of the range, {sits} the {shown:g} kg maximum",
388
504
  )
505
+ # ACSM's two-session confirmation: the top of the range has to be
506
+ # cleared twice at one load before the load moves.
507
+ #
508
+ # Placed *after* the two endings above rather than before them, because
509
+ # both of those leave the target exactly where this would. There is
510
+ # nothing to confirm when there is nothing to add, and an exercise that
511
+ # is bodyweight or out of rack would otherwise be told, every run, to
512
+ # hold once more for a jump that is never coming.
513
+ if topped < CONFIRMED_AFTER:
514
+ return (
515
+ Target(spec.rep_high, weight),
516
+ f"hit {floor} on every set{lifted}, top of the range, "
517
+ "hold it once more before the load goes up",
518
+ )
519
+
389
520
  # Three shapes of the same move, and the report is the only place they
390
521
  # differ: a plain step, a step shortened to land on the rack's own
391
522
  # ceiling, and a step that ran off the end of one rack onto the next.
@@ -446,12 +577,14 @@ def _advance( # noqa: PLR0913 - each argument is one independent input
446
577
  )
447
578
 
448
579
 
449
- def next_target(
580
+ def next_target( # noqa: PLR0913 - each argument is one independent input
450
581
  spec: ExerciseSpec,
451
582
  current: Target,
452
583
  performed: list[PerformedSet],
453
584
  streak: int = 0,
585
+ *,
454
586
  bodyweight: float = 0.0,
587
+ topped: int = 0,
455
588
  ) -> tuple[Target, str]:
456
589
  """Decide the next prescription for one exercise.
457
590
 
@@ -467,6 +600,13 @@ def next_target(
467
600
  most of any routine and harmless for the rest, because a step chosen a size
468
601
  small still progresses.
469
602
 
603
+ `topped` is how many sessions in a row already cleared the top of the range
604
+ at this load, from `top_streak`, and gates rule 3's load increase alone.
605
+ Like `streak` it defaults to none, which is the reading to give when there
606
+ is no history to consult - a first-ever session, or one too old to look
607
+ behind - and costs a single held session at the top of the range, which the
608
+ session after it then confirms.
609
+
470
610
  Returns the new target plus a short human-readable reason.
471
611
  """
472
612
  if not performed:
@@ -475,32 +615,15 @@ def next_target(
475
615
  # Judge everything at the load actually used, which may not be the load the
476
616
  # workout still has stored.
477
617
  weight = working_weight(performed)
478
- at_weight = [entry.reps for entry in performed if entry.weight == weight]
479
618
  rebased = weight != current.weight
619
+ counted = _counted_reps(performed, weight)
480
620
 
481
621
  # Progress from the weakest set, not from the stored target. The next
482
622
  # target has to be achievable on every set, so extra reps on the easy sets
483
623
  # earn nothing while the floor stays put -- but beating the target on all
484
- # of them does count.
485
- floor = min(at_weight)
486
-
487
- # A set carried at a *heavier* load, for at least the reps the working sets
488
- # managed, counts as one of them: harder than asked is not worse than
489
- # asked, and a session split across two loads is still a whole session.
490
- # Without this the set count is taken from one load alone, and three sets
491
- # done as two at 20 kg and one at 30 kg read as an abandoned session rather
492
- # than a finished one.
493
- #
494
- # What it contributes is its own rep count, which is a lower bound on what
495
- # it would have managed at the lighter load, so this can only ever add sets
496
- # to the tally - never flatter the reps. A set that came up short at the
497
- # heavier load counts for nothing, which is what keeps a failed top set
498
- # from reading as a completed session.
499
- counted = at_weight + [
500
- entry.reps
501
- for entry in performed
502
- if entry.weight > weight and entry.reps >= floor
503
- ]
624
+ # of them does count. The heavier sets `_counted_reps` folds in never sit
625
+ # below this, so taking it from the whole tally is the same figure.
626
+ floor = min(counted)
504
627
 
505
628
  # Rule 5: a load is only worth keeping once it can be carried for at least
506
629
  # the bottom of the range. Falling short of rep_low means the jump was too
@@ -532,4 +655,6 @@ def next_target(
532
655
  return _deload(spec, current, weight, counted, bodyweight=bodyweight)
533
656
  return current, _missed(floor)
534
657
 
535
- return _advance(spec, current, weight, floor, streak, bodyweight=bodyweight)
658
+ return _advance(
659
+ spec, current, weight, floor, streak, bodyweight=bodyweight, topped=topped
660
+ )