AGENTS.md -- iccDEV

This file is a short navigation aid for automated coding agents and maintainers. Detailed rules live in .github/copilot-instructions.md and .github/instructions/*.instructions.md.

AGENTS.md is the canonical agent-instruction file. GitHub Copilot also recognizes CLAUDE.md (Anthropic Claude) and GEMINI.md (Google Gemini) at the repository root; both are thin mirrors that route back here so every agent shares one source of truth. Update rules here, not in the mirrors.

Ground Rules

• Check git --no-pager status --short --branch before edits.
• Prefer focused changes with exact repros and regression coverage.
• Keep documentation links Doxygen-safe: use relative Markdown links for generated Markdown pages and \ref for generated source files. Use absolute GitHub HTML anchors for repo-only resources; relative HTML anchors can break in the packaged site even when Doxygen emits no warning. Before handing off documentation changes, run the bounded graph-light Doxygen check in docs/documentation-maintenance.md and require an empty docs/generated/doxygen-warnings.log. Time is valuable: reserve full graph generation for release packaging or graph changes, not routine prose edits. Keep HAVE_DOT=YES for checked-in diagrams; leave CTest implementation and fixtures outside the generated package. Do not add generated output to Git.
• Use 2-space C++ indentation, K&R braces, m_ members, and return-value errors.
• Exit 1-127 is graceful failure. Exit 128+ is signal termination.
• Use sanitizer builds for bug hunting; see .github/instructions/build-system.instructions.md.
• Add the nearest regression test for behavior fixes.
• For legacy packed intent decoding and named-color overprint behavior, keep iccApplyNamedCmm and iccApplySearch coverage aligned with .github/scripts/iccdev-applynamedcmm-cli-args-regression.sh, .github/scripts/iccdev-applysearch-cli-args-regression.sh, and .github/scripts/iccdev-namedcolor-overprint-regression-tests.sh.
• For maintainer pre-PR validation, use the current maintainer image and local tools for applicable builds, preflight, scanners, and dynamic checks. On the pushed pre-PR branch, run ci-qa-pr with ctest-mode=full and ctest-recent-limit=0 plus ci-codeql-security on the same head. Record terminal results before opening an explicitly authorized PR. Run ci-pr-action on the PR head for final cross-platform builds, profile checks, and representative CTest coverage; it does not replace the local or pre-PR screening.
• Before the first automated review, record a base...HEAD contract matrix for every changed cross-cutting surface: producer, consumer, build/runtime behavior, platform or toolchain boundary, CI trigger, dependency owner, and local evidence. A later update still requires the complete contract matrix, not a delta-only review. Any newly found blocker returns the branch to branch-only grooming before another review.
• Every new or relocated ICC-owned C/C++ source or header must retain the complete BSD-3-Clause notice derived from LICENSE.md; run .github/scripts/check-license-notices.py before review. Abbreviated, placeholder, or omitted notices are blocking defects. Preserve third-party and generated-file attribution as directed by their provenance.
• For MCP runtime checks, validate every Docker image variant against its discovered capabilities. Do not hard-code a total tool count.
• Keep the pure Python iccdev-mcp Python 3.10+ package contract separate from the compiled iccdev CPython 3.11-3.14 wheel contract. For MCP behavior or packaging changes, use .github/skills/mcp-server-qa/SKILL.md and require source tests plus the relevant installed-package, native, or image smoke; record skipped native tests as unverified coverage.
• The published unified container is a native linux/amd64 and linux/arm64 manifest. Build and smoke each platform before publishing a tag; Apple Silicon Docker hosts must select linux/arm64 without emulation.
• Python CI and rolling-release wheels share _build-python-wheels.yml between ci-json-python and ci-latest-release, with Python 3.13 driving cibuildwheel 3.4.0 for all seven platform lanes. Keep installed-wheel tests and their binary NumPy dependency aligned across all lanes. Primary CI disables shared wheel artifact upload and fails on empty test collection; release CI enables explicitly named artifact intake validated by .github/scripts/validate-python-release-wheels.py with an independent --lane inventory, complete license checks, checksums, and provenance; PyPI publication uses explicit pypi_packages selection on the manual ci-latest-release.yml workflow. Keep iccdev and iccdev-mcp staging, trusted-publisher identities, outcomes, and post-publication smoke tests separate. Run public-package smoke tests after every selected publication and report their diagnostic outcomes without blocking later package publications. Require complete package inventories, dual checksums, release attestations, the protected release environment, and OIDC publishing. Validate downloaded release wheels with --release to require all 36 targets without CI identifier files. Require RECORD file coverage, secure hashes, and sizes before attestation; ZIP CRCs alone do not prove this contract.
• Rolling-release MCP artifacts are a separate universal wheel and sdist, validated by .github/scripts/validate-mcp-release-package.py. Keep the Windows/Linux source, installed wheel, and installed sdist checks in the mcp-package job. Prove parent/child imports and console stdio/REST behavior with iccdev-mcp-package-smoke.py; do not infer installed behavior from editable installs. Preserve the iccdev_mcp namespace and optional native capability failures. MCP distributions participate in checksums/provenance; publish them through the same protected trusted-publishing workflow without combining the MCP package contract with the compiled-wheel inventory.
• MATLAB public entry points that require arguments must provide actionable bare-invocation errors pinned by matlab/tests/test_usage_guidance.m. Interactive examples must show visible UI defaults first; label hidden or headless options as automation-only. Shape errors must explain row semantics and include copy/paste-ready single-item and batch examples.

Navigation

CFL Harness Scope

Keep the six command-line CFL targets as filesystem-backed CLI wrappers. The in-process targets are the intentional exceptions: consume only public headers, compile the engine sources as separate translation units, and never include a CLI implementation or call processLuts().

Keep them separate rather than folding serialization into the model target, so a crash stays attributable to one layer.

The official ClusterFuzzLite lane builds all eight in-process targets above. Keep its address, undefined, and memory builds separate, pass all compiler and linker instrumentation through the OSS-Fuzz environment, require matching Clang 21 or 22 compilers across AFL, CFL, and ClusterFuzzLite, and keep the workflow limited to manual dispatch and the nightly schedule. The ClusterFuzzLite memory build must bootstrap the pinned instrumented libc++ and libc++abi, reject libstdc++ or another libc++ at runtime, and replay the pinned #2687 artifact before fuzzing. A report crossing an uninstrumented C++ runtime boundary is not attributable to iccDEV.

Keep cmmapply controls outside the ICC header: an optional three-byte trailer selects direction, intent, and interpolation without corrupting the encoded profile size. Keep at least one schema-shaped IccConnect configuration seed in .github/ci/test-data, use the dedicated config dictionary, and preserve round-trip coverage for top-level and nested CIccCfg* objects.

Temporary CFL MSan workarounds live as individual issue patches under .github/ci/fuzz-patches/cfl. The default fuzz build attempts every patch and continues after drift or prior integration; --strict is only for maintaining the patch inventory. Retire one issue patch at a time after its normal source fix lands.

An in-process target that needs a CLUT raster also needs a corpus that still contains one. max_seed_bytes and libFuzzer's max_len both removed the only CLUT-bearing seed at their old defaults (#2120), which left such a target reporting runs, coverage and a clean exit while never executing the layer it exists to cover. Both defaults now admit it, and dropping a seed committed under .github/ci/test-data is a hard error rather than a silent prune. Raise max_len alongside the cap when adding a target that consumes large structured inputs -- they are independent gates. Validate with

.github/ci/cfl/build.sh --targets profilevisualize,writerserialize --seconds 30

WASM Scope

WASM now ships as a staged Node/npm-style module package. Do not expect or restore legacy wasm/*.html, wasm/*.css, or wasm/*.js browser UI assets. Use .github/skills/wasm-build-test/SKILL.md for the current module smoke and profile parity checks.

AVX2 CLUT Diagnostics

Use vs2022-clangcl-x64-avx2-diagnostics for a Windows source-level AVX2 debugging session. It enables ICC_AVX2_CLUT_DEBUG, which traces runtime dispatch and kernel inputs through IccSignatureUtils.h. Do not use the diagnostic preset for throughput comparisons; use the matching vs2022-clangcl-x64-avx2-qa-flags build for measurements. The focused regression is iccdev.clut-eight-output-regression. Use .github/scripts/iccdev-windows-clut-avx2-benchmark.ps1 for interleaved Release comparisons across 8-16 outputs. Windows AVX2 is a ClangCL path; native MSVC intentionally retains SSE2 after measured AVX2 regressions. Runtime AVX2 dispatch is limited to 15 outputs. Require output_vector_match=True for every benchmark row.

For Linux evidence collection, configure a separate Release build with ICCDEV_ENABLE_TELEMETRY=ON and use .github/scripts/iccdev-clut-profile.sh. The script writes timing distributions, hardware-counter CSVs, syscall summaries, and optional FlameGraph inputs; keep profiling and source-coverage builds separate from release measurements.