fuzzer AGENTS.md

AGENTS.md — fuzzer-tool

Coverage-guided binary fuzzer: ASAN/MSAN/TSAN/UBSAN detection, dictionary mutations, Markov chain generation, Monte Carlo optimization, format-aware grammar mutations, and state persistence. CLI tool that fuzzes arbitrary binaries (see fuzzer-tool --help).

The fuzzer executes attacker-controlled input against instrumented targets and parses the targets' own binaries — any bug in this tool's parsing/process code is a bug in the fuzzer, not just the target.

References (read on demand)

Hard Rules

1. Always make surgical changes.
2. Always follow existing conventions. Before adding anything — a target, a script, a scheduler, a test fixture — find the closest existing example and match it: directory layout, file naming, function shape, flag names, error handling, comment style. Read the surrounding code first; do not invent a parallel way of doing something the repo already does. Concretely: vendored library sources go in vendor/<lib>/ (gitignored) fetched by a tools/vendor_<lib>.sh script — never committed and never under targets/; new fuzz targets are wired into tools/build_targets.sh rather than built by hand; new schedulers register in _OPERATOR_STRATEGY_NAMES and follow the select_op/record/bandit_stats interface. If a convention appears wrong, fix it in one place for everything rather than working around it locally, and say so.
3. Never bypass the pre-commit hooks (--no-verify). Fix the warnings, then recommit.
4. Always fix impactguard breaking changes.
5. Always use clang, never gcc (build scripts prefer clang automatically).
6. Stop suggesting use_direct_lite = False to work around ASAN in direct_lite mode — debug the root cause instead.
7. Never commit binary files or corpus directories — build targets from source, keep corpus data local.
8. Before deleting code, find where it should be wired first; if not found, clean up. When removing code, stay strictly within the scope of the removal — do not remove unrelated code.
9. Do not nuke the repo.
10. All fuzz targets: compile with ASAN (-fsanitize=address) and AFL edge coverage via afl_shim.c (-include src/fuzzer_tool/adapters/afl_shim.c). Pre-compile library sources as .o files; link the shim only into the target wrapper.
11. Always create TODOs. Always commit and push after finishing a task.
12. Update docs/DEEP_DIVE.md with new features (the comprehensive reference). Update README.md only when adding or changing high-level capabilities visible in the quick-start or feature overview.
13. Op mutators have a single source of truth: src/fuzzer_tool/core/operator_registry.py's REGISTRY. Register new operators there only — the dispatch table (build_dispatch), the per-input op list (build_ops), scheduler arming (_register_arms), and OPERATOR_CATEGORIES all derive from it. Never add operator names to the legacy MUTATIONS/FORMAT_MUTATIONS/DICT_MUTATIONS lists or hand-edit OPERATOR_CATEGORIES; schedulers discover ops through the services layer and never hardcode op lists.
14. Only run the full pytest suite if a file in the codebase was modified.
15. Always after developing a new function and verify its correctness try to vectorize it after the fact, keep the fastest version.
16. Always use the existing pickle machinery, avoid json.
17. For random always use the prng in src/fuzzer_tool/core/rand_pool.py.
18. Do not create artifacts in the source codebase dir.
19. Always create corpus on ~/.
20. Always make sure when creating a new functionality that is wired-up where needed.
21. try except pass is a bad pattern.
22. Always excersice higiene: every test must clean up their mess.
23. If you solved the halting problem you are allowed to run tests that the user is saying they are hanging otherwise read the code to see what it does.
24. For every new functionality always add one falsification test and one adversarial test.
25. Always use subagents for multiple file exploring or long tasks.
26. Without any question when the user instructs you to git and commit now, you obey, create the commit message, commit and push. no questions asked and no deliberation.
27. When writing something intended for human consumption, (comment, commit message, reply to prompt) use as few words as possible. Pick every word meticulously to reduce the volume to a strict minimum. Be down to the point. Less is more.
28. Avoid superlatives and praise. Stop telling me I am absolutely right. Give me the cold hard truth.
29. Avoid magic numbers and strings by extracting recurring or meaningful values into descriptive constants (const) or enums. Keep self-explanatory, one-off values inline to avoid clutter. If a value comes from a spec (e.g. HTTP 200 OK), use a constant regardless.
30. Reduce code indentation. Avoid Arrow Anti-Pattern. Leverage early return and continue.
31. Keep function names short. Less than 30 characters.
32. Use enums instead of booleans for function parameters.
33. Let the reader of the code breathe. Add empty lines between logical blocks of code.
34. Add a small, to the point, comment to explain what the block does and why. Use examples when possible. Propose ASCII drawings to explain complete systems.
35. Treat member visibility changes as a breaking design shift. Keep all fields and functions private unless external access is strictly required by the design. Prompt the user for explicit approval before changing any access modifier from private to internal or public.
36. Program to levels of abstraction. Lower-level mechanics must be encapsulated in a dedicated driver/abstraction layer. Expose clean, high-level APIs to the rest of the application so calling code works with domain concepts, not raw implementation details.
37. Don't touch blocks of code unrelated to the feature you implement. e.g. Don't add comments to a block of code if you did not create it or modify it. As much as possible try to minimize the number of changed lines when implementing a feature.
38. Strictly adhere to the layered boundary hierarchy: each layer may only communicate with its immediate neighbor directly below it. Never "punch holes" through layers (e.g., controllers or UI components must never directly call database queries, raw hardware drivers, or low-level network clients; always route through the intermediate service/abstraction layer).
39. If the prompt indicates that a bug is being fixed, don't write the fix right away. First write the test. Observe it failing. Then write the fix. And observe the test passing.
40. When implementing a new feature don't write it right away. First write the test. Observe it failing. Then write the feature. And observe the test passing (Test driven development).
41. No retry-until-random-hit loops in tests (for _ in range(N): if cond: break/found=True). This tests luck, not behavior — it can pass while the code is broken and fails unreproducibly when it doesn't. Inject a scripted/fake RNG that deterministically drives the exact call sequence and assert the exact output. See docs/refs/bug-classes.md §Testing.
42. Every scheduler armed through _register_arms (src/fuzzer_tool/services/fuzzer.py) must declare an explicit class-level supports_priors bool: True only when its init_arm() accepts an informative (prior_alpha, prior_beta) override. _register_arms gates priors behind getattr(scheduler, "supports_priors", False), so a scheduler that omits the flag silently discards format-operator priors instead of failing loudly. Declare it directly after the class docstring with a one-line reason, following monte_carlo.py / exp3.py.
43. Always check that the new features implemented or bug fixes do not introduce speed penalty regressions.