AGENTS.md

Ironpress agent guardrails

Writing Rust code

• Structure state so that invalid state is unrepresentable in the type system.

• Do not validate; parse. Turn raw input into a richer type once, at the boundary; past that boundary the type is proof the data is well-formed.

• Use semantic types that carry meaning and reusable functionality instead of abusing meaningless scalars. Group fields by domain responsibility; copying a flat field list from an enum variant into a flat struct is not a semantic refactor.

• Do not use interior mutability or reference counting. They normally indicate that ownership has not been modeled correctly; prefer owned values, &, and &mut.

• Production code must never panic. Tests may panic when an assertion fails.

• Keep code simple. Long or complicated code indicates a missing abstraction; use the type system to represent prevalidated states instead of propagating Result or Option without semantic need.

• Do not reinvent functionality that an appropriate, well-maintained crate already provides.

• Establish every test expectation from an independent requirement, applicable specification, verified oracle, or reproduced regression before changing implementation. Never rewrite a test merely to match the code's new output; delete a test with no independently known behavioral contract instead of using it to bless the implementation.

• Diagnostics for parsed languages must explain what went wrong, why, and how to fix it when a useful hint exists.

• Avoid noisy code and keep each function at a homogeneous abstraction level. Every statement should contribute to understanding the computation.

• Avoid bare helper functions when the behavior belongs on a type or is shared through a trait.

• When multiple structures provide common behavior and a consumer does not care which structure backs it, constrain that behavior with a trait and implement the trait on each structure.

• Do not use field-bearing object-enum leaves. Model each leaf as a concrete struct. If the object family is open or consumers depend on shared behavior, use a trait (with Box<dyn Trait> and an object-safe visitor or narrower capability traits where heterogeneous storage or dispatch is required). Keep enums only for genuinely closed value/state alternatives, not as substitutes for behavior-bearing types.

• Group reusable contextual values into semantic structs with their own constructors, operators, helpers, and Default implementations. Prefer Struct { nondefault: value, ..Default::default() } over repeating neutral fields.

• Code files should remain a few hundred lines long. A larger file indicates a missing module boundary or abstraction.

• The parity bar is specification compliance to the point of untrained-human indistinguishability from a correct render. Raw differences remain evidence; configuration-controlled optimizations may trade only imperceptible precision.

• Paged CSS compliance is the target. Do not assume an oracle is correct: check disputed behavior against the applicable standard and repair or regenerate an incorrect reference.

• Future oracle PDFs must be generated only by the pinned Chromium Fontations/Foundation launcher. Authenticated historical non-Chromium references may remain as evidence, but must never be regenerated or used as the source of a new oracle.

• Candidate and oracle PDFs use the same pinned pdf2ppm/pdftoppm executable and arguments. A raster difference means the PDFs differ; do not attribute it to different rasterizers.

• Never translate, register, jitter, crop, resize, filter, resample, or replace either comparison raster. Diffs must show the complete page canvas without copying source content into the diff.

• A per-pixel RGB channel delta below 1% is semantically correct, while the exact RGBA mismatch remains reported. A complete page may contain at most 1% above-floor pixels; authored-scale defects can still fail below that aggregate ceiling.

• Pin UA behavior explicitly in oracle fixtures. If a fixture or pinned UA change affects oracle paint, regenerate the affected PDF references and refs.lock before publishing a report.

• Keep tests/parity/reports/index.html, tests/parity/REPORT.md, and tests/parity/report.json current after retained renderer or comparator changes.

• Fix shared problem families, starting with the largest human-visible differences. Verify visually similar failures before weakening a global guard.

• Prefer proper module hierarchies over flat files or compatibility scaffolding. Do not use #[path = "..."] to simulate a module hierarchy.