[OCaml] High Intensity Training Online
docs convert steering to list-first form, ground domain in HD1
Steering files favour bullet points and ordered lists over prose so they are easier to edit and skim. No rules changed in ocaml.md or workflow.md; only prose was restructured into lists. domain.md now cites the doctrine source (doc/Mike_Mentzer_Heavy_Duty_I.md) and names specific chapters for each binding principle, and states the doctrinal stall remedy explicitly: after two weeks of no progress, take a week off, then reduce volume and frequency. This closes the prior gap where the forbidden space (never more work) was stated but the allowed remedy was not.
.kiro/steering/domain.md
@@ -1,42 +1,64 @@
1
1
# Domain: Mike Mentzer's Heavy Duty
2
2
3
Removed:
hito is a Heavy Duty training tracker. Every domain decision must be justified
4
Removed:
against Mentzer's philosophy (HD1, HD2). When a design choice and the philosophy
5
Removed:
conflict, the philosophy wins — or the conflict is raised, not silently resolved.
3
Added:
hito is a Heavy Duty training tracker.
6
4
5
Added:
- Source of doctrine: `doc/Mike_Mentzer_Heavy_Duty_I.md` (HD1). Every domain
6
Added:
decision must be justified against it.
7
Added:
- On conflict between a design choice and the doctrine:
8
Added:
1. The doctrine wins, or
9
Added:
2. The conflict is raised explicitly.
10
Added:
7
11
## Principles that bind the model
8
12
9
Removed:
- **Intensity is categorical, not scalar.** A working set is taken to momentary
10
Removed:
muscular failure; that is its definition. Going further is qualitative
11
Removed:
(`Beyond_failure`: forced reps, negatives, rest-pause, static hold). Never
12
Removed:
introduce a numeric "intensity score".
13
Removed:
- **Recovery produces growth; the gym only stimulates it.** Recovery is
14
Removed:
systemic and time-based — any hard workout gates the next one.
15
Removed:
- **Volume beyond the minimum is harmful.** One working set per exercise is
16
Removed:
nominal. Rising volume is a diagnostic warning, never an achievement or a
17
Removed:
progress target.
18
Removed:
- **Progressive overload is the progress signal.** Progress is an increase in
19
Removed:
reps, weight or both; one extra rep counts. Reps are an *outcome*, never a
20
Removed:
target — a set ends at failure, not at a number, so the prescribed band only
21
Removed:
calibrates load. Raise the load once twelve reps are reached, by 10-20%, so
22
Removed:
failure returns inside the band. Note the slack: a 6-10 band is not breached
23
Removed:
at eleven.
24
Removed:
- **Brief, infrequent, intense.** Shorter sessions at equal or better overload
25
Removed:
are favourable.
26
Removed:
- **Focus over novelty.** Exercises come from a curated catalog; substitutions
27
Removed:
are limited to author-specified whitelists, which a routine may only narrow.
13
Added:
- **Intensity is categorical, not scalar.**
14
Added:
- A working set is taken to momentary muscular failure; that *is* its
15
Added:
definition (HD1, "The Intensity Factor": the only accurate measures are 0%
16
Added:
at rest and 100% at failure).
17
Added:
- Going further is qualitative — `Beyond_failure`: forced reps, negatives,
18
Added:
rest-pause, static hold.
19
Added:
- Never introduce a numeric "intensity score".
20
Added:
- **Recovery produces growth; the gym only stimulates it.**
21
Added:
- Stimulation is immediate; production is not (HD1, "The Economics of Growth
22
Added:
and Recovery": recovery precedes growth).
23
Added:
- Recovery is systemic and time-based — any hard workout gates the next one.
24
Added:
- **Volume beyond the minimum is harmful.**
25
Added:
- One working set per exercise is nominal; three sets per muscle is the ceiling.
26
Added:
- The net negative effect of each extra set increases geometrically.
27
Added:
- Rising volume is a diagnostic warning — never an achievement or a progress
28
Added:
target.
29
Added:
- **Progressive overload is the progress signal.**
30
Added:
- Progress = an increase in reps, weight, or both; one extra rep counts.
31
Added:
- Reps are an *outcome*, never a target — a set ends at failure, not at a
32
Added:
number. The prescribed band only calibrates load.
33
Added:
- Raise the load once twelve reps are reached, by 10-20%, so failure returns
34
Added:
inside the band.
35
Added:
- Note the slack: a 6-10 band is not breached at eleven.
36
Added:
- **Brief, infrequent, intense.**
37
Added:
- Shorter sessions at equal or better overload are favourable.
38
Added:
- **Focus over novelty.**
39
Added:
- Exercises come from a curated catalog.
40
Added:
- Substitutions are limited to author-specified whitelists, which a routine
41
Added:
may only narrow.
28
42
29
43
## Encoding rules
30
44
31
45
- Prefer making an illegal training state unrepresentable over validating it at
32
46
runtime.
33
47
- Deviations from doctrine (training early, extra volume) must be *possible* but
34
Removed:
never *silent*: require an explicit acknowledgement and retain it.
35
Removed:
- Keep plan and record distinct: prescription/routine vs logged workout;
36
Removed:
prescription vs progression (plan vs observation).
37
Removed:
- The logbook records; it never interprets. Judgement belongs to one module.
38
Removed:
Invariants belong on plans, which are authored, not on history, which is
39
Removed:
observed — a log that refuses to state what happened is worse than one
40
Removed:
recording an error.
41
Removed:
- On a stall the answer is never more work. No remedy may add volume or
42
Removed:
frequency.
48
Added:
never *silent*:
49
Added:
- Require an explicit acknowledgement.
50
Added:
- Retain that acknowledgement.
51
Added:
- Keep plan and record distinct:
52
Added:
- Prescription/routine vs logged workout.
53
Added:
- Prescription vs progression (plan vs observation).
54
Added:
- The logbook records; it never interprets.
55
Added:
- Judgement belongs to one module.
56
Added:
- Invariants belong on plans, which are authored — not on history, which is
57
Added:
observed.
58
Added:
- A log that refuses to state what happened is worse than one recording an
59
Added:
error.
60
Added:
- On a stall, the answer is never more work.
61
Added:
- No remedy may add volume or frequency.
62
Added:
- Doctrinal remedy (HD1, "Regulating Volume and Frequency"): after two weeks
63
Added:
of no progress, take a week off, then *reduce* volume and frequency —
64
Added:
drop sets and add rest days.
.kiro/steering/ocaml.md
@@ -2,20 +2,22 @@
2
2
3
3
## Source of truth
4
4
5
Removed:
`.mli` files are the specification and outrank tests. If an interface and a test
6
Removed:
disagree, fix the test. Changing an interface is a deliberate design decision —
7
Removed:
raise it, don't drift into it.
5
Added:
- `.mli` files are the specification and outrank tests.
6
Added:
- If an interface and a test disagree, fix the test.
7
Added:
- Changing an interface is a deliberate design decision — raise it, don't drift
8
Added:
into it.
8
9
9
10
## Style
10
11
11
12
- Modern, idiomatic OCaml. Favour the principle of least surprise: a reader
12
13
should not need to learn a local idiom to follow the code.
13
14
- Introduce monadic style (`let*`, custom binds) only where it removes
14
Removed:
substantial noise — typically chained `result` plumbing. A single `match` is
15
Removed:
clearer than a monad; don't reach for one reflexively.
15
Added:
substantial noise — typically chained `result` plumbing.
16
Added:
- A single `match` is clearer than a monad; don't reach for one reflexively.
16
17
- Abstract types with smart constructors for anything carrying an invariant.
17
Removed:
- Return `result` with a module-specific error type. Each module defines its own
18
Removed:
errors; no shared catch-all error type, no `string` errors.
18
Added:
- Return `result` with a module-specific error type.
19
Added:
- Each module defines its own errors.
20
Added:
- No shared catch-all error type, no `string` errors.
19
21
- Prefer closed variants — they keep `match` exhaustiveness working for you.
20
22
- Reserve exceptions for genuine programmer error, never for control flow.
21
23
- Total functions where practical; make partiality visible in the type.
@@ -29,11 +31,7 @@
29
31
- `hito.app` — `Repository` port, `Service`, adapters. Knows nothing of Eliom.
30
32
- `hito.web` — Eliom application. The only place Eliom appears.
31
33
32
Removed:
Ports are module types; adapters implement them. Persistence identity is
33
Removed:
assigned in `hito.app`, not in the core.
34
Added:
Rules:
34
35
35
Removed:
## Build hygiene
36
Removed:
37
Removed:
Warnings are errors. Do not silence them with a blanket annotation; fix the
38
Removed:
cause. `[@@warning "-69"]` on a record whose fields are reached only through a
39
Removed:
module type is acceptable and should be rare.
36
Added:
- Ports are module types; adapters implement them.
37
Added:
- Persistence identity is assigned in `hito.app`, not in the core.
.kiro/steering/workflow.md
@@ -10,35 +10,37 @@
10
10
3. `dune fmt` has been run and `dune build @fmt` is clean.
11
11
4. Documentation reflects the change.
12
12
13
Removed:
Only then commit. Never commit unformatted or failing code.
13
Added:
Then, and only then:
14
14
15
Removed:
Use `direnv exec <repo> dune ...` if the local opam switch is not active.
15
Added:
- Commit — but only when asked.
16
Added:
- Never commit unformatted or failing code.
17
Added:
- Use `direnv exec <repo> dune ...` if the local opam switch is not active.
16
18
17
19
## Commits
18
20
19
Removed:
Conventional Commits:
21
Added:
- Follow Conventional Commits:
20
22
21
Removed:
```
22
Removed:
<type>(<optional scope>): <imperative summary under 72 chars>
23
Added:
```
24
Added:
<type>(<optional scope>): <imperative summary under 72 chars>
23
25
24
Removed:
Body: why, not what. Wrap at 72. Note deviations from Heavy Duty doctrine
25
Removed:
and the reasoning behind design decisions.
26
Removed:
```
26
Added:
Body: why, not what. Wrap at 72. Note deviations from Heavy Duty doctrine
27
Added:
and the reasoning behind design decisions.
28
Added:
```
27
29
28
Removed:
Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `build`, `perf`.
29
Removed:
Scopes follow the layering: `core`, `app`, `web`, plus module names
30
Removed:
(`core/set`, `core/recovery`).
30
Added:
- Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `build`, `perf`.
31
Added:
- Scopes follow the layering: `core`, `app`, `web`, plus module names
32
Added:
(`core/set`, `core/recovery`).
33
Added:
- Commit only when asked.
34
Added:
- Stage specific files rather than `git add .`.
31
35
32
Removed:
Commit only when asked. Stage specific files rather than `git add .`.
33
Removed:
34
36
## Documentation
35
37
36
38
Written for a human skimming the repo, not for completeness.
37
39
40
Added:
- Terse, idiomatic OCaml documentation.
38
41
- Refactor docs aggressively; delete anything stale or redundant in the same
39
42
change that outdates it.
40
43
- Interface docs state **intention**, not implementation. One line where one
41
44
line will do.
42
45
- A module header says what the module is for and which invariant it upholds.
43
46
- Don't restate the signature in prose. Document the *why* and the edge cases.
44
Removed:
- No markdown files unless asked.