# Forma — Adaptive Workout Progress Logic ## Purpose Replace the current fixed “week streak” summary at the bottom of the Home screen with an adaptive progress summary. Users can view their completed workouts against a target calculated from their scheduled training days and the remaining eligible dates in the selected period. The progress view supports three periods: - **This week** - **This month** - **This year** The target is based on the user's active workout schedule, not a fixed universal number. ## Core concepts ### Scheduled training days Use the user's configured weekly schedule (weekday slots, such as Monday, Tuesday, Thursday, and Friday) as the source of eligible training dates. A date is an eligible training date when: 1. It falls within the selected period. 2. It is on a weekday included in the user's current workout schedule. 3. It is on or after the applicable start date for the period. For the current week, month, or year, the applicable start date is the later of: - the period's first date, and - the user's account creation date. For a future period, count all scheduled weekdays in that period. For a completed past period, use the scheduled weekdays across the full period. ### Completed workouts Count distinct workout sessions completed in the selected period. A completed session contributes one to the completed count, regardless of the number of exercises or sets. Do not count an in-progress, abandoned, or deleted session as completed. Prevent duplicate session records from increasing the count more than once. ### Target calculation For each period: `target = number of eligible scheduled training dates in that period` `completed = number of distinct completed workout sessions in that period` Display progress as `completed / target`. Do not cap the completed count at the target. If a user completes extra workouts, show the actual count (for example, `5 / 4`) rather than hiding the extra activity. If the target is zero, avoid division by zero and show a sensible empty state such as “No scheduled workouts” rather than a percentage. ## Period rules ### This week Use the app's existing week-start convention and locale consistently (for example, Monday through Sunday if that is the existing convention). For the current week, count scheduled dates from the later of the week start or account creation date through the week end. The target is recalculated as the calendar advances, but should not shrink simply because a scheduled day has already passed; past eligible dates remain part of the period target. For other weeks, count all weekdays in the user's schedule that fall within that week. ### This month For the current month, count scheduled dates from the later of the first day of the month or account creation date through the last day of the month. For other months, count all scheduled weekdays in the month. ### This year For the current year, count scheduled dates from the later of January 1 or account creation date through December 31. For other years, count all scheduled weekdays in that calendar year. ## Example: account created September 15, 2026 Assume the user's schedule is Monday, Tuesday, Thursday, and Friday, and the week starts on Monday. September 15, 2026 is a Tuesday. - **This week (Sep 14–20):** eligible dates on/after account creation are Tue Sep 15, Thu Sep 17, and Fri Sep 18. Target: **3**. - **This month (Sep 1–30):** eligible dates on/after account creation are Sep 15, 17, 18, 21, 22, 24, 25, 28, and 29. Target: **9**. - **This year (Sep 15–Dec 31):** target is the total number of Mondays, Tuesdays, Thursdays, and Fridays from Sep 15 through Dec 31, 2026, inclusive. Calculate this from calendar dates rather than hard-coding a number. For complete future weeks, the weekly target is **4**. For complete future months and years, calculate the number of scheduled weekdays in each calendar period. > Arithmetic note: in the September example, there are six eligible dates after Sep 18 (Sep 21, 22, 24, 25, 28, 29), so the monthly total is 3 + 6 = 9, not 12. ## Date and schedule-change behavior - Use the user's local calendar date/time zone for period boundaries and date comparisons. - Use date-only calendar arithmetic for scheduled weekdays; avoid UTC conversion shifting a date to the previous/next day. - Recompute the current period's target when the local date changes, when the user changes their schedule, and when account/profile data is refreshed. - For historical periods, ideally use the schedule that was active at the time. If schedule history is not available, document and consistently apply the current schedule to historical calculations rather than silently mixing approaches. - Do not count dates before account creation. - Do not count a date outside the selected period. ## UI behavior Follow the attached sketches as visual references. - Keep the existing **My Progress** entry point and make it open the full progress view if that is the current behavior. - Add a compact period selector with **This week**, **This month**, and **This year**. - Show a prominent completed count followed by `/ target` and the label **workouts**. - Show a compact calendar-like sequence of marks for eligible dates in the selected period: - completed workout dates use the existing completed/filled visual treatment; - eligible dates without a completed workout use the unfilled treatment; - dates that are not eligible training days should be visually quiet or omitted, consistent with the sketches. - For month and year views, keep the visualization responsive and avoid forcing an unreadably dense row. Use wrapping or a compact calendar/grid representation while preserving chronological order. - Preserve the app's existing design tokens, typography, spacing, accessibility patterns, and bottom navigation/safe-area behavior. - Ensure the selected period and progress state are accessible to assistive technology; do not rely on color alone to communicate completion. ## Acceptance criteria 1. The period selector switches among week, month, and year without changing workout history. 2. Each period's target is calculated from scheduled weekdays within its date boundaries. 3. Current partial periods exclude dates before account creation. 4. The September 15, 2026 example produces weekly target 3 and monthly target 9 for a Mon/Tue/Thu/Fri schedule. 5. A complete week with that schedule produces target 4. 6. The year target is computed by enumerating eligible dates through December 31, not by multiplying a weekly target by a fixed number of weeks. 7. Completed sessions are counted once and only when completed. 8. Progress can exceed the target without being capped. 9. A zero-target period has a safe, understandable empty state. 10. Date calculations respect the user's local time zone and existing week-start convention. 11. Existing workout logging, schedule, and navigation behavior remain intact. 12. Add or update tests for period boundaries, leap years, account creation mid-period, schedule weekdays, duplicate sessions, and zero-target periods.