FaST-LMM AGENTS.md

Coding Notes for Agents

This file contains repository-wide guidance for FaST-LMM, a mature numerical Python package with downstream users. Preserve compatibility and numerical correctness unless the task explicitly changes those goals.

General Policies

• When work is interrupted or reaches a stopping point, report the current status, what remains, and the recommended next step. If the next step is within the current task and safe to perform, perform it instead of merely recommending it.
• Inspect existing code, tests, documentation, and project configuration before introducing a new pattern. Prefer a focused change that follows nearby conventions over an unrelated cleanup or broad rewrite.
• Do not silently skip required Python versions, operating systems, architectures, dependency configurations, tests, doctests, or artifact checks. If a required environment or tool is unavailable, fail clearly and report what is missing.
• Avoid silent clamping, coercion, truncation, or fallback behavior. Validate inputs and fail clearly unless the public API explicitly documents another behavior.
• Preserve behavior on every supported Python version, not only the interpreter used for development.

Cross-Repository Release Coordination

FaST-LMM depends on the separately released pysnptools and fastlmmclib projects. When a release changes their compatibility requirements, complete and publish the prerequisite releases first, update FaST-LMM's dependency bounds, and perform final acceptance against the published artifacts rather than unpublished sibling checkouts.

Numerical Correctness

• Treat changes to numerical algorithms, tolerances, array shapes, dtypes, missing-value handling, sample or marker ordering, and random-number behavior as behavior changes, not mechanical refactors.
• Do not update expected numerical or textual output merely to make a test pass. First confirm that the new result is correct and does not hide a regression.
• Use deterministic seeds in tests involving randomness. When exact equality is inappropriate, use an explicit, justified tolerance rather than an unnecessarily broad one.
• Preserve representative small end-to-end tests for association, inference, and packaged data so integration failures are not hidden by unit tests.