Workflow

Definition of done

A feature is not finished until, in this order:

1. `dune build @check` is clean (type-checks library *and* tests).
2. Alcotests exist for it — unit tests for behaviour, end-to-end tests for flows that cross module boundaries — and `dune runtest` passes.
3. `dune fmt` has been run and `dune build @fmt` is clean.
4. Documentation reflects the change.

Then, and only then:

• Commit — but only when asked.
• Never commit unformatted or failing code.
• Use `direnv exec . dune ...` if the local opam switch is not active.

Commits

• Follow Conventional Commits:

  <type>(<optional scope>): <imperative summary under 72 chars>

  Body: why, not what. Wrap at 72. Note deviations from Heavy Duty doctrine
  and the reasoning behind design decisions.

• Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `build`, `perf`.
• Scopes follow the layering: `core`, `app`, `web`, plus module names (`core/set`, `core/recovery`).
• Commit only when asked.
• Stage specific files rather than `git add .`.

Documentation

Written for a human skimming the repo, not for completeness.

• Terse, idiomatic OCaml documentation.
• Refactor docs aggressively; delete anything stale or redundant in the same change that outdates it.
• Interface docs state **intention**, not implementation. One line where one line will do.
• A module header says what the module is for and which invariant it upholds.
• No Markdown files unless asked.
• Don't restate the signature in prose. Document the *why* and the edge cases.

Build directory safety

Never use the default Dune build directory. A persistent `dune exec -w ogit` process may use `_build`.

Use these commands instead:

• `dune build --build-dir _build-agent`
• `dune runtest --build-dir _build-agent`

Do not run `dune clean` on the default `_build` directory.