# petekTools — build conventions
## What this is
A **standalone, pure-leaf** Rust library of numerics & geostatistics kernels —
the scattered-data gridding layer Rust lacks, plus a curated front-door over
mature numeric crates. Consumed by petekio and petekSim; depends on neither.
PyO3 bindings are planned. Read `SPEC.md` (design constitution) and `API.md`
(the locked contract) before changing anything. Follows the shared **petek house
style** (canonical: `petekSuite/dev-docs/petek-house-style.md`) — the rules below
are this library's slice of it.
## Mantra: SPLIT UP THE ELEPHANT 🐘
One module per concept, one concept per file. Split before a file owns two jobs
or grows past a few hundred lines. Keep the layers (`foundation → gridding →
[stats] → [sampling] → [py]`) one-directional.
## Hard rules (from SPEC.md)
1. **Pure leaf.** Never depend on petekio or petekSim. Only general-purpose
numeric crates (`ndarray`, `thiserror`, and later `faer`/`statrs`/`kiddo`/
`rstar`/`rand_distr`).
2. **Don't reinvent.** If a mature crate already does it well, curate it; only
build what Rust is missing (the geostatistics/gridding kernels).
3. **Type-agnostic kernels.** `Lattice` + `[[f64; 3]]` in, `ndarray` out. No
consumer domain types, no I/O.
4. **Parity with consolidated prior art.** Lifting a kernel from petekio (the
author's own code) means matching its algorithm/defaults/tolerances and
citing it. The GATE-0 kernels came from petekio 0.2.0; geometry parity is
pinned by `tests/lattice_parity.rs`.
5. **PyO3-ready.** Keep public signatures binding-friendly (owned types, no
public lifetimes).
## Tooling
- `cargo test` after any behaviour change; `cargo clippy` is **warnings = errors**;
`cargo fmt`. `criterion` for benches when kernels land.
- GATE-0 is complete (the geometry `Lattice`, the `grid()` dispatcher, and the
three ported kernels). Since then, shipped to HEAD (unreleased, heading for
0.2.0): warm-start / `ConvergentGridder` gridding, the `Gridder` trait +
`OrdinaryKriging`, the curated `stats` / `sampling` front-doors, and the
`units` / `container` modules. Only the PyO3 wheel remains from the old
roadmap — see `dev-docs/designs/roadmap.md`.
## Suite-owned coordination
petekSuite is the sole control plane for this managed library. It owns agent
lifecycle, the planning graph, actionable todos, GitHub Actions operations,
publishing, and releases. Work here is executed by a directly spawned
petekTools agent through the suite's `run-library-task` skill; do not recreate
a local skill tree, inbox, MCP configuration, or todo index.
Before changing a shared seam, the coordinator reads the petekSuite planning
graph and passes the relevant contract and graph ids into the task. The owning
agent reports findings, evidence, and graph-worthy changes back to the
coordinator; only petekSuite writes coordination state.
`dev-docs/` may retain stable petekTools-only technical plans, designs, and
benchmark records when code or historical reasoning depends on those paths.
Actionable state lives centrally under
`petekSuite/dev-docs/libraries/petekTools/`.
## Commits
`type: short description` (`feat`, `fix`, `docs`, `refactor`, `test`, `chore`).
Update `CHANGELOG.md` `[Unreleased]` for surface changes. Pushing needs explicit
approval.