[OCaml] High Intensity Training Online
docs add project steering for domain, OCaml style, and workflow
Persist the conventions we established during interface design so they survive across sessions instead of being restated each time. - domain.md: Heavy Duty principles that bind the model, and the encoding rules that follow from them (intensity categorical not scalar, volume as warning, deviations possible but never silent, plan vs record). - ocaml.md: .mli files outrank tests; idiomatic OCaml with monads only where they earn it; per-module error types; the three-library layering and its one-way dependencies. - workflow.md: definition of done (check, test, format, document, then commit), Conventional Commits with layer-based scopes, and docs written for a skimming reviewer.
.kiro/steering/domain.md
@@ -0,0 +1,34 @@
1
Added:
# Domain: Mike Mentzer's Heavy Duty
2
Added:
3
Added:
hito is a Heavy Duty training tracker. Every domain decision must be justified
4
Added:
against Mentzer's philosophy (HD1, HD2). When a design choice and the philosophy
5
Added:
conflict, the philosophy wins — or the conflict is raised, not silently resolved.
6
Added:
7
Added:
## Principles that bind the model
8
Added:
9
Added:
- **Intensity is categorical, not scalar.** A working set is taken to momentary
10
Added:
muscular failure; that is its definition. Going further is qualitative
11
Added:
(`Beyond_failure`: forced reps, negatives, rest-pause, static hold). Never
12
Added:
introduce a numeric "intensity score".
13
Added:
- **Recovery produces growth; the gym only stimulates it.** Recovery is
14
Added:
systemic and time-based — any hard workout gates the next one.
15
Added:
- **Volume beyond the minimum is harmful.** One working set per exercise is
16
Added:
nominal. Rising volume is a diagnostic warning, never an achievement or a
17
Added:
progress target.
18
Added:
- **Progressive overload is the progress signal.** Add reps within the
19
Added:
prescribed band; once the band is exceeded, add load and reset to its bottom.
20
Added:
- **Brief, infrequent, intense.** Shorter sessions at equal or better overload
21
Added:
are favourable.
22
Added:
- **Focus over novelty.** Exercises come from a curated catalog; substitutions
23
Added:
are limited to author-specified whitelists, which a routine may only narrow.
24
Added:
25
Added:
## Encoding rules
26
Added:
27
Added:
- Prefer making an illegal training state unrepresentable over validating it at
28
Added:
runtime.
29
Added:
- Deviations from doctrine (training early, extra volume) must be *possible* but
30
Added:
never *silent*: require an explicit acknowledgement and retain it.
31
Added:
- Keep plan and record distinct: prescription/routine vs logged workout;
32
Added:
prescription vs progression (plan vs observation).
33
Added:
- Anything prescribed is derived from logged evidence and carries that evidence
34
Added:
plus the status computed from it.
.kiro/steering/ocaml.md
@@ -0,0 +1,39 @@
1
Added:
# OCaml implementation
2
Added:
3
Added:
## Source of truth
4
Added:
5
Added:
`.mli` files are the specification and outrank tests. If an interface and a test
6
Added:
disagree, fix the test. Changing an interface is a deliberate design decision —
7
Added:
raise it, don't drift into it.
8
Added:
9
Added:
## Style
10
Added:
11
Added:
- Modern, idiomatic OCaml. Favour the principle of least surprise: a reader
12
Added:
should not need to learn a local idiom to follow the code.
13
Added:
- Introduce monadic style (`let*`, custom binds) only where it removes
14
Added:
substantial noise — typically chained `result` plumbing. A single `match` is
15
Added:
clearer than a monad; don't reach for one reflexively.
16
Added:
- Abstract types with smart constructors for anything carrying an invariant.
17
Added:
- Return `result` with a module-specific error type. Each module defines its own
18
Added:
errors; no shared catch-all error type, no `string` errors.
19
Added:
- Prefer closed variants — they keep `match` exhaustiveness working for you.
20
Added:
- Reserve exceptions for genuine programmer error, never for control flow.
21
Added:
- Total functions where practical; make partiality visible in the type.
22
Added:
23
Added:
## Layering
24
Added:
25
Added:
Three libraries, dependencies pointing inward only:
26
Added:
27
Added:
- `hito.core` — pure domain. No framework, database, or serialization
28
Added:
dependencies. Ever.
29
Added:
- `hito.app` — `Repository` port, `Service`, adapters. Knows nothing of Eliom.
30
Added:
- `hito.web` — Eliom application. The only place Eliom appears.
31
Added:
32
Added:
Ports are module types; adapters implement them. Persistence identity is
33
Added:
assigned in `hito.app`, not in the core.
34
Added:
35
Added:
## Build hygiene
36
Added:
37
Added:
Warnings are errors. Do not silence them with a blanket annotation; fix the
38
Added:
cause. `[@@warning "-69"]` on a record whose fields are reached only through a
39
Added:
module type is acceptable and should be rare.
.kiro/steering/workflow.md
@@ -0,0 +1,44 @@
1
Added:
# Workflow
2
Added:
3
Added:
## Definition of done
4
Added:
5
Added:
A feature is not finished until, in this order:
6
Added:
7
Added:
1. `dune build @check` is clean (type-checks library *and* tests).
8
Added:
2. Alcotests exist for it — unit tests for behaviour, end-to-end tests for flows
9
Added:
that cross module boundaries — and `dune runtest` passes.
10
Added:
3. `dune fmt` has been run and `dune build @fmt` is clean.
11
Added:
4. Documentation reflects the change.
12
Added:
13
Added:
Only then commit. Never commit unformatted or failing code.
14
Added:
15
Added:
Use `direnv exec <repo> dune ...` if the local opam switch is not active.
16
Added:
17
Added:
## Commits
18
Added:
19
Added:
Conventional Commits:
20
Added:
21
Added:
```
22
Added:
<type>(<optional scope>): <imperative summary under 72 chars>
23
Added:
24
Added:
Body: why, not what. Wrap at 72. Note deviations from Heavy Duty doctrine
25
Added:
and the reasoning behind design decisions.
26
Added:
```
27
Added:
28
Added:
Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `build`, `perf`.
29
Added:
Scopes follow the layering: `core`, `app`, `web`, plus module names
30
Added:
(`core/set`, `core/recovery`).
31
Added:
32
Added:
Commit only when asked. Stage specific files rather than `git add .`.
33
Added:
34
Added:
## Documentation
35
Added:
36
Added:
Written for a human skimming the repo, not for completeness.
37
Added:
38
Added:
- Refactor docs aggressively; delete anything stale or redundant in the same
39
Added:
change that outdates it.
40
Added:
- Interface docs state **intention**, not implementation. One line where one
41
Added:
line will do.
42
Added:
- A module header says what the module is for and which invariant it upholds.
43
Added:
- Don't restate the signature in prose. Document the *why* and the edge cases.
44
Added:
- No markdown files unless asked.