# 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.