delaunay: Instructions file for Codex

AGENTS.md

Essential guidance for AI assistants working in this repository.

This file is the entry point for all coding agents. It should stay short enough to load and remember. Detailed operational rules are indexed in docs/dev/README.md; focused architecture references are indexed from docs/code_organization.md.

---

Contents

• Required Reading
• Non-Negotiable Rules
• Project Context
• Design Priority
• Scientific Invariants
  • Numerical Correctness
  • Topological Correctness
  • Validation Layers
  • Symbolic Perturbation
• Design Principles
• Where Detailed Rules Live
• Agent Expectations

---

Required Reading

Before modifying repository files, agents MUST read:

• AGENTS.md (this file)
• docs/dev/README.md - development guidance index; read each focused document whose ownership row matches the files or workflows the task touches
• docs/code_organization.md - short architecture hub; follow its focused links when touching module layout, public namespace, preludes, or file organization

docs/dev/README.md explains which focused document owns each development workflow. Agents must read the task-relevant focused documents completely before making changes and load additional owners if the task expands. Cross-cutting changes must follow every applicable owner; unrelated development histories and workflow references do not need to be loaded preemptively.

Non-Negotiable Rules

• Scientific correctness is the acceptance criterion. A passing test suite does not by itself establish numerical or topological validity. When a legitimate regression test fails, agents MUST correct the production code while preserving the original input and intended behavior. Never weaken assertions, substitute easier fixtures, reduce coverage, skip the test, or replace expected success with accepted failure merely to obtain a green run. Change a test's contract only when independent evidence demonstrates that its mathematics, fixture, or expectation is wrong; explain that evidence and preserve meaningful regression coverage. Typed errors and rollback are required safeguards, not substitutes for supported successful behavior.
• Do not mutate version-control state unless the maintainer explicitly asks. Never run git commit, git push, git tag, or ref/index-mutating Git commands by default. Use git --no-pager for read-only Git commands. Detailed Git/GitHub rules live in docs/dev/git.md.
• Use patch editing for manual edits. Never use sed, awk, perl, or Python to modify code. Shell text tools are fine for read-only analysis.
• Do not revert user changes. The worktree may be dirty; preserve unrelated changes and work with any overlapping edits.
• Unsafe Rust is forbidden. The crate enforces #![forbid(unsafe_code)].
• Validate with the right command. Use just check during iterative review and fixes, alongside targeted tests for changed behavior. Run just check on the final working tree before every push; focused validators do not replace this gate. Core Rust/Cargo, substantial Python, or public-behavior changes also require just ci before a PR is ready or changes are pushed. A successful just ci includes and satisfies the just check gate. Smaller documentation, configuration, Python, notebook, test-only, benchmark-only, and example-only changes use the matching focused validators from docs/dev/commands.md alongside the pre-push gate; compose those validators once each when multiple focused surfaces changed.
• CodeRabbit review requires explicit authorization. Never run CodeRabbit automatically. Run just review (or just review-uncommitted) only when the maintainer explicitly requests that command or gives permission for the CodeRabbit review. A general request to review, fix, or prepare a PR does not authorize uploading the diff to this external service. Without authorization, continue local review and validation; CodeRabbit is not a readiness requirement. When authorized, assess its findings and fix valid issues before final validation. Command scope and follow-up guidance live in docs/dev/commands.md#local-coderabbit-review.
• Do not edit generated changelogs manually. Changelog and documentation maintenance rules live in docs/dev/docs.md.
• Keep documentation owners distinct. README owns evaluation and quickstart; REFERENCES owns thematic bibliography and stable citation keys; docs/scientific_basis.md owns the scientific overview. Preserve Contents, early API/scope guidance, and existing deep links. Sort independent methods lexicographically within coherent groups, after their prerequisites. Task guides use uppercase verb/gerund filenames; discussions, policy, references, and results use lowercase descriptive names. Keep conventional indexes and archives intact; details live in documentation policy. README Quickstart owns usage and bare just discovery; CONTRIBUTING owns contributor checks, fixes, tests, security, and PR preparation.
• Keep manuscript ownership separate. Active manuscript sources and builds live in acgetchell/Papers. Preserve Delaunay-owned scientific inputs and historical release evidence; see docs/dev/docs.md.
• Keep notebook execution deliberate. just notebook-check is lint-only. The canonical macOS leg of just ci may execute the validation notebook only to compare regenerated figures with tracked artifacts; it must not publish them. Execute other notebooks only when the task requires it, and refresh tracked notebook artifacts only through named recipes when the task includes that refresh. Every cell must have a unique, stable, descriptive lowercase kebab-case ID. Detailed policy lives in docs/dev/notebooks.md.
• Keep README and citation prose mirrored. The first paragraph under README.md's Introduction is mirrored by the abstract field in CITATION.cff; update both together. The invariant is checked by tests/tooling/test_readme_citation_mirror.py.