Define future Trainlog roadmap
This commit is contained in:
fy59
parent
83a88d98a3
commit
396bea6910
1 changed files with 353 additions and 144 deletions
497
docs/roadmap.md
497
docs/roadmap.md
|
|
@ -1,153 +1,398 @@
|
|||
# Roadmap
|
||||
|
||||
This file describes the current project state and the next implementation
|
||||
cursor. Historical checkpoint detail belongs in Git history and `docs/reviews`.
|
||||
This file is the canonical product roadmap for Trainlog.
|
||||
|
||||
## Gate 0 — Project contract
|
||||
Historical implementation detail belongs in Git history and `docs/reviews`.
|
||||
The published Trainlog JSON v1 compatibility boundary remains frozen unless a
|
||||
future feature explicitly introduces a new version.
|
||||
|
||||
## Completed foundation
|
||||
|
||||
```text
|
||||
GATE_0=PASS
|
||||
```
|
||||
|
||||
Development rules, ownership boundaries, identity rules, validation discipline,
|
||||
and Git workflow are established.
|
||||
|
||||
## Gate 1 — Trainlog exchange format v1
|
||||
|
||||
```text
|
||||
GATE_1=PASS
|
||||
TRAINLOG_FORMAT_V1=FROZEN
|
||||
```
|
||||
|
||||
The published Trainlog JSON v1 compatibility boundary remains unchanged.
|
||||
|
||||
## Gate 2 — Persistence and usable desktop TUI
|
||||
|
||||
```text
|
||||
GATE_2=PASS
|
||||
|
||||
TRAINLOG_FORMAT_V1=FROZEN
|
||||
DESKTOP_SCHEMA_V5=PASS
|
||||
FIRST_USABLE_TUI=PASS
|
||||
ANDROID_LOCAL_DATABASE_V3=PASS
|
||||
|
||||
DIRECT_MTP_TRANSPORT=PASS
|
||||
BIDIRECTIONAL_SYNC_V1=PASS
|
||||
|
||||
VARIABLE_REPETITION_SETS=PASS
|
||||
MEASURED_MAX_V1=PASS
|
||||
BODY_ANALYTICS_V1=PASS
|
||||
|
||||
DESKTOP_TESTS=21/21 PASS
|
||||
```
|
||||
|
||||
Completed baseline includes:
|
||||
The current product baseline includes:
|
||||
|
||||
- SQLite persistence and explicit migrations;
|
||||
- direct session entry;
|
||||
- session history/detail/editing;
|
||||
- usable ncurses desktop TUI;
|
||||
- native Android capture client;
|
||||
- exercise catalog;
|
||||
- profile-aware set and continuous work;
|
||||
- body history/editing/visualization;
|
||||
- exercise performance history;
|
||||
- strict validation and rollback behavior.
|
||||
|
||||
## Android local client
|
||||
|
||||
```text
|
||||
ANDROID_LOCAL_WORKFLOWS=PASS
|
||||
ANDROID_LOCAL_DATABASE_V3=PASS
|
||||
```
|
||||
|
||||
Completed:
|
||||
|
||||
- exercise creation;
|
||||
- inline exercise creation;
|
||||
- profile-aware session entry;
|
||||
- profile-aware set and continuous activity;
|
||||
- heterogeneous repetition sets;
|
||||
- continuous activity;
|
||||
- session history/detail;
|
||||
- body measurements;
|
||||
- exercise removal from the current session draft.
|
||||
- session history and editing;
|
||||
- body measurements and body history;
|
||||
- measured-max sessions and measured-max analysis;
|
||||
- desktop body analytics;
|
||||
- direct USB/MTP transport;
|
||||
- bidirectional Android/PC synchronization;
|
||||
- shared synchronization engine and `trainlog-syncd`.
|
||||
|
||||
## Variable set checkpoint
|
||||
## Product boundary
|
||||
|
||||
The intended split remains:
|
||||
|
||||
```text
|
||||
VARIABLE_REPETITION_SETS=PASS
|
||||
REPETITION_SHORTHAND_5x10=PASS
|
||||
REPETITION_EXPLICIT_LIST=PASS
|
||||
REPETITION_PYRAMID=PASS
|
||||
ANDROID
|
||||
= fast capture during real use
|
||||
|
||||
DESKTOP_SCHEMA_V5=PASS
|
||||
V4_TO_V5_MIGRATION_REGRESSION=PASS
|
||||
MOBILE_HETEROGENEOUS_SET_IMPORT=PASS
|
||||
NO_FAKE_UNIFORM_TARGET=PASS
|
||||
DESKTOP TUI
|
||||
= planning
|
||||
+ catalog management
|
||||
+ history
|
||||
+ analytics
|
||||
+ long-term decision support
|
||||
```
|
||||
|
||||
## Direct MTP transport
|
||||
Android must not become the main analytics surface unless this boundary is
|
||||
explicitly revised later.
|
||||
|
||||
## Operational cursor — real data baseline
|
||||
|
||||
The immediate priority is not another implementation block.
|
||||
|
||||
Trainlog now needs real measurements and real training sessions so later
|
||||
analytics are based on useful data rather than fixtures.
|
||||
|
||||
```text
|
||||
USB_MTP_DETECTION=PASS
|
||||
MTP_STORAGE_ACCESS=PASS
|
||||
MTP_WRITE=PASS
|
||||
MTP_LIST_FOLDER=PASS
|
||||
MTP_READ=PASS
|
||||
MTP_ROUNDTRIP=PASS
|
||||
DIRECT_MTP_TRANSPORT=PASS
|
||||
CURRENT_OPERATIONAL_CURSOR=REAL_DATA_BASELINE_V1
|
||||
```
|
||||
|
||||
No mounted-filesystem dependency is required.
|
||||
Expected baseline:
|
||||
|
||||
## Bidirectional synchronization v1
|
||||
- first complete real body observation;
|
||||
- first real training sessions;
|
||||
- Android used for capture;
|
||||
- Android -> PC synchronization after training;
|
||||
- measured max recorded only through explicit `max_test` sessions;
|
||||
- no fictitious user data in the canonical databases.
|
||||
|
||||
Gate:
|
||||
|
||||
```text
|
||||
ANDROID_TO_PC_MTP=PASS
|
||||
DESKTOP_MOBILE_IMPORT_V1=PASS
|
||||
DESKTOP_MOBILE_IMPORT_IDEMPOTENT=PASS
|
||||
|
||||
PC_CATALOG_EXPORT_V1=PASS
|
||||
PC_TO_ANDROID_MTP_PUBLISH=PASS
|
||||
|
||||
COMMON_SYNC_ENGINE=PASS
|
||||
TRAINLOG_SYNCD=PASS
|
||||
ANDROID_TRIGGERED_SYNC=PASS
|
||||
ANDROID_SYNC_RECEIPT=PASS
|
||||
TUI_SYNC_LOG_SHOW=PASS
|
||||
|
||||
BIDIRECTIONAL_SYNC_V1=PASS
|
||||
REAL_DATA_BASELINE_V1=PASS
|
||||
```
|
||||
|
||||
Validated architecture:
|
||||
## Next feature — gym catalog v1
|
||||
|
||||
```text
|
||||
Android local change
|
||||
-> automatic mobile snapshot
|
||||
NEXT_FEATURE=GYM_CATALOG_V1
|
||||
```
|
||||
|
||||
Android "Synchroniser maintenant"
|
||||
-> request
|
||||
The catalog must be based on the equipment actually available in the user's
|
||||
gym rather than on a generic Internet exercise list.
|
||||
|
||||
trainlog-syncd
|
||||
-> shared C sync engine
|
||||
-> Android -> PC import
|
||||
-> PC -> Android catalog
|
||||
-> receipt
|
||||
The initial inventory will be built from a complete photo survey of the gym.
|
||||
|
||||
For each useful equipment item, record where applicable:
|
||||
|
||||
```text
|
||||
gym zone
|
||||
equipment family
|
||||
machine name
|
||||
manufacturer/model if identifiable
|
||||
useful duplicate count
|
||||
supported exercise(s)
|
||||
Trainlog recording profile
|
||||
load semantics
|
||||
primary muscles
|
||||
secondary muscles
|
||||
```
|
||||
|
||||
Important rule:
|
||||
|
||||
```text
|
||||
one photographed machine != one exercise
|
||||
```
|
||||
|
||||
A single piece of equipment may support multiple exercises. Equipment and
|
||||
exercise identity must remain distinct concepts.
|
||||
|
||||
Gate:
|
||||
|
||||
```text
|
||||
GYM_CATALOG_V1=PASS
|
||||
```
|
||||
|
||||
## Exercise metadata v1
|
||||
|
||||
After the real gym inventory is normalized, enrich the exercise catalog with
|
||||
structured metadata needed by planning and analytics.
|
||||
|
||||
Candidate metadata:
|
||||
|
||||
```text
|
||||
equipment
|
||||
primary_muscles
|
||||
secondary_muscles
|
||||
movement_family
|
||||
body_region
|
||||
laterality
|
||||
```
|
||||
|
||||
The final schema must be designed before implementation. Do not encode these
|
||||
concepts into names or free-form notes as a substitute for a real model.
|
||||
|
||||
Gate:
|
||||
|
||||
```text
|
||||
EXERCISE_METADATA_V1=PASS
|
||||
```
|
||||
|
||||
## Session planner v1
|
||||
|
||||
The desktop TUI becomes the canonical session-planning surface.
|
||||
|
||||
A planned session should allow:
|
||||
|
||||
- selecting exercises from the real gym catalog;
|
||||
- ordering exercises;
|
||||
- planned sets/repetitions or duration;
|
||||
- planned rest;
|
||||
- optional planned load where semantically valid;
|
||||
- synchronization to Android.
|
||||
|
||||
Android should then open a prepared session and require only actual performance
|
||||
entry during training.
|
||||
|
||||
Target workflow:
|
||||
|
||||
```text
|
||||
Desktop TUI
|
||||
-> prepare session
|
||||
-> sync
|
||||
|
||||
Android
|
||||
-> matching receipt
|
||||
-> catalog apply
|
||||
-> final result
|
||||
-> open planned session
|
||||
-> enter actual values
|
||||
-> save
|
||||
-> sync
|
||||
|
||||
Desktop TUI
|
||||
-> history and analytics
|
||||
```
|
||||
|
||||
The TUI invokes the same engine manually.
|
||||
|
||||
## Current quality baseline
|
||||
The feature should also make later support possible for:
|
||||
|
||||
```text
|
||||
DESKTOP_TESTS=19/19 PASS
|
||||
ANDROID_BUILD=PASS
|
||||
HARDWARE_SYNC_VALIDATION=PASS
|
||||
TRAINLOG_FORMAT_V1=FROZEN
|
||||
duplicate previous session
|
||||
reuse a planned session
|
||||
session templates
|
||||
```
|
||||
|
||||
## Current implementation cursor
|
||||
|
||||
No next product feature is frozen by this documentation checkpoint.
|
||||
Gates:
|
||||
|
||||
```text
|
||||
NEXT_FEATURE=UNFROZEN
|
||||
SESSION_PLANNER_V1=PASS
|
||||
ANDROID_PLANNED_SESSION_ENTRY=PASS
|
||||
```
|
||||
|
||||
Candidate future areas may include richer analytics, measured-max semantics,
|
||||
additional editing workflows, synchronization hardening, or other product work,
|
||||
but none is canonical until explicitly selected.
|
||||
## Session templates v1
|
||||
|
||||
Templates are built from the real exercise catalog and planning model.
|
||||
|
||||
Candidate examples:
|
||||
|
||||
```text
|
||||
glutes + arms
|
||||
back + shoulders
|
||||
chest + arms
|
||||
legs
|
||||
full body
|
||||
cardio
|
||||
```
|
||||
|
||||
Templates are conveniences, not rigid training prescriptions.
|
||||
|
||||
Gate:
|
||||
|
||||
```text
|
||||
SESSION_TEMPLATES_V1=PASS
|
||||
```
|
||||
|
||||
## Training analytics v1
|
||||
|
||||
Implement only after enough real sessions exist to make the output meaningful.
|
||||
|
||||
Candidate views:
|
||||
|
||||
```text
|
||||
7 days
|
||||
30 days
|
||||
90 days
|
||||
since baseline
|
||||
```
|
||||
|
||||
Candidate metrics:
|
||||
|
||||
- training frequency;
|
||||
- sets;
|
||||
- repetitions;
|
||||
- duration;
|
||||
- external load;
|
||||
- assistance;
|
||||
- measured-max progression;
|
||||
- useful volume metrics where semantically valid;
|
||||
- progression by exercise.
|
||||
|
||||
Once exercise metadata exists, aggregate by muscle group or movement family to
|
||||
help evaluate training balance.
|
||||
|
||||
Gate:
|
||||
|
||||
```text
|
||||
TRAINING_ANALYTICS_V1=PASS
|
||||
```
|
||||
|
||||
## Body analytics v2
|
||||
|
||||
Implement after multiple real body observations exist.
|
||||
|
||||
Possible additions:
|
||||
|
||||
- baseline comparison;
|
||||
- previous-observation comparison;
|
||||
- 7/30/90-day trends;
|
||||
- moving-average weight trend;
|
||||
- waist trend;
|
||||
- anthropometric estimate trend;
|
||||
- left/right asymmetry trend;
|
||||
- obvious measurement-outlier warnings.
|
||||
|
||||
Permanent semantic rule:
|
||||
|
||||
```text
|
||||
DIRECT_MEASUREMENT != ESTIMATE
|
||||
```
|
||||
|
||||
Derived body-composition values remain explicitly labelled estimates.
|
||||
|
||||
Gate:
|
||||
|
||||
```text
|
||||
BODY_ANALYTICS_V2=PASS
|
||||
```
|
||||
|
||||
## Progression assist v1
|
||||
|
||||
Use accumulated history to produce conservative training suggestions.
|
||||
|
||||
Examples:
|
||||
|
||||
```text
|
||||
external load:
|
||||
stable completed work
|
||||
-> suggest a small load increase
|
||||
|
||||
assistance:
|
||||
stable completed work
|
||||
-> suggest a small assistance decrease
|
||||
```
|
||||
|
||||
The system proposes. It does not silently change planned training.
|
||||
|
||||
Measured max and estimated performance must remain distinct concepts.
|
||||
|
||||
Gate:
|
||||
|
||||
```text
|
||||
PROGRESSION_ASSIST_V1=PASS
|
||||
```
|
||||
|
||||
## Objectives v1
|
||||
|
||||
Support explicit user-defined objectives such as:
|
||||
|
||||
```text
|
||||
body weight
|
||||
waist circumference
|
||||
plank duration
|
||||
exercise load
|
||||
repetitions
|
||||
measured max
|
||||
weekly training frequency
|
||||
```
|
||||
|
||||
Display current value, target, remaining difference, and trend where the data
|
||||
supports it.
|
||||
|
||||
Avoid mandatory gamification.
|
||||
|
||||
Gate:
|
||||
|
||||
```text
|
||||
OBJECTIVES_V1=PASS
|
||||
```
|
||||
|
||||
## Backup and export v1
|
||||
|
||||
SQLite remains canonical.
|
||||
|
||||
Provide durable user-controlled export and backup:
|
||||
|
||||
```text
|
||||
SQLite
|
||||
-> dated backup
|
||||
-> complete JSON export
|
||||
-> CSV export where useful
|
||||
-> period-limited export
|
||||
```
|
||||
|
||||
Gate:
|
||||
|
||||
```text
|
||||
BACKUP_EXPORT_V1=PASS
|
||||
```
|
||||
|
||||
## Canonical implementation order
|
||||
|
||||
```text
|
||||
REAL_DATA_BASELINE_V1
|
||||
|
|
||||
v
|
||||
GYM_CATALOG_V1
|
||||
|
|
||||
v
|
||||
EXERCISE_METADATA_V1
|
||||
|
|
||||
v
|
||||
SESSION_PLANNER_V1
|
||||
|
|
||||
v
|
||||
SESSION_TEMPLATES_V1
|
||||
|
|
||||
v
|
||||
TRAINING_ANALYTICS_V1
|
||||
|
|
||||
v
|
||||
BODY_ANALYTICS_V2
|
||||
|
|
||||
v
|
||||
PROGRESSION_ASSIST_V1
|
||||
|
|
||||
v
|
||||
OBJECTIVES_V1
|
||||
|
|
||||
v
|
||||
BACKUP_EXPORT_V1
|
||||
```
|
||||
|
||||
This order is canonical until explicitly revised.
|
||||
|
||||
## Permanent constraints
|
||||
|
||||
|
|
@ -159,44 +404,8 @@ mandatory mounted Android filesystem
|
|||
exercise-name identity heuristics
|
||||
fake performed sets for continuous activity
|
||||
fake uniform targets for heterogeneous actual sets
|
||||
incompatible changes to Trainlog JSON v1
|
||||
```
|
||||
|
||||
## Measured max v1
|
||||
|
||||
```text
|
||||
MEASURED_MAX_V1=PASS
|
||||
MEASURED_MAX_ONLY_FROM_MAX_TEST=PASS
|
||||
MEASURED_MAX_HISTORY=PASS
|
||||
MEASURED_MAX_GRAPH=PASS
|
||||
WORKING_LOAD_PERCENTAGES=PASS
|
||||
ANDROID_MAX_TEST_SESSION=PASS
|
||||
DESKTOP_TESTS=20/20 PASS
|
||||
```
|
||||
|
||||
No schema v6 and no Trainlog JSON v1 change were required.
|
||||
|
||||
The next product feature remains intentionally unfrozen:
|
||||
|
||||
```text
|
||||
NEXT_FEATURE=UNFROZEN
|
||||
```
|
||||
|
||||
## Body analytics v1
|
||||
|
||||
```text
|
||||
BODY_ANALYTICS_V1=PASS
|
||||
BODY_ANALYTICS_TUI_ONLY=PASS
|
||||
BODY_COMPOSITION_ESTIMATE=PASS
|
||||
BODY_PROPORTION_RATIOS=PASS
|
||||
BODY_SYMMETRY_ANALYTICS=PASS
|
||||
NO_ESTIMATE_PERSISTENCE=PASS
|
||||
DESKTOP_TESTS=21/21 PASS
|
||||
```
|
||||
|
||||
No Android feature, database schema migration, or frozen JSON v1 change was
|
||||
required.
|
||||
|
||||
```text
|
||||
NEXT_FEATURE=UNFROZEN
|
||||
ordinary training promoted to measured max
|
||||
assistance interpreted as external load
|
||||
body-composition estimates presented as direct measurements
|
||||
incompatible changes to Trainlog JSON v1 without a new format version
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in a new issue