docs: branch-naming convention and the ergoExo contract in CLAUDE.md

[joglekara]

Writes down two rules that were tribal knowledge, so agents and new contributors pick them up without being told.

Branch names

Branches and commit scopes are named after the solver being touched — the convention already visible in the log (feat/vlasov1d-dougherty-nodrag, fix/vlasov1d-v0-units, feat(vlasov1d): ...). Repo-wide work with no solver uses the area instead: ci/, docs/, chore/.

Everything is built on ergoExo

Solvers are never invoked directly, so the section records the contract rather than just naming it: the ADEPTModule lifecycle calls in the order ergoExo#_setup_() and ergoExo#__call__() make them, plus the constraints that follow from that order.

• a later step can only read what an earlier step built — a term needing a coefficient array can't first appear in init_state_and_args() if nothing put it in cfg during get_solver_quantities()
• the scalar/array split between get_derived_quantities() and get_solver_quantities() is load-bearing: the former's cfg goes to MLflow param logging, which arrays break
• gradients go through vg(), which raises unless the module implements a metric
• _get_adept_module_ is a hand-written registry with no autodiscovery, keyed per runnable module rather than per directory — vlasov-1d and vlasov-1d-iaw both live in _vlasov1d

Relationship to dev_guide.md

#330 rewrote docs/source/dev_guide.md around this same lifecycle, so CLAUDE.md deliberately does not carry a second copy of the "adding a solver" list — it points at dev_guide.md as canonical. Two doc sources drifting apart is the trap #330 called out about Read the Docs, and it applies here too.

What CLAUDE.md keeps in its own words is the lifecycle order and the failure modes above, because CLAUDE.md is always in an agent's context and dev_guide.md is not.

The one step dev_guide.md was missing is added to it directly: a paths filter and a test job in .github/workflows/cpu-tests.yaml. CI only runs suites for solvers it detects as changed (#302), so a new tests/test_<solver>/ without them silently never runs.

Docs only, no code changes.

One thing to settle: this branch is claude/adept-claude-md-docs-5d74c7, which the new rule would have as docs/.... The claude/* names are harness-generated — worth an explicit exemption in the convention if that's fine as-is.

🤖 Generated with Claude Code