docs: add utilities unit test requirements to AGENTS.md

AGENTS.md

@@ -276,12 +276,34 @@ This is a test suite - internal APIs have NO backward compatibility requirements
   - `##### Special notes for reviewer:` — must be present (may be empty)
   - `##### jira-ticket:` — must be present (may be empty)
 
+### Utilities Unit Test Requirements
+
+Changes under `utilities/` require matching unit test coverage unless an exception below applies. If you add a function, add its tests. If you change behavior, update the assertions. Do not treat a passing `utilities-unittests` as proof of coverage — it only runs existing tests. Missing test coverage for new or modified utility code is a defect.
+
+**Add or update unit tests in the same commit/PR when ANY of these apply:**
+
+- A **coverage-enforced** utilities module changed (any `utilities/*.py` file **not** listed in `[tool.coverage.run] omit` in `pyproject.toml`)
+- A module that already has `utilities/unittests/test_<module>.py` and the change adds or modifies **testable behavior** (new public function, changed logic, bug fix, new error path)
+- A bug fix in utilities code where a mocked unit test can lock the regression without a cluster
+
+Add or update tests in `utilities/unittests/test_<module>.py`. New public functions need dedicated test methods. For changes to existing behavior, extend the matching test rather than adding a redundant one. Follow patterns in [`utilities/unittests/README.md`](utilities/unittests/README.md) and existing `test_*.py` files. Do not put utility helpers in `conftest.py` under `utilities/unittests/`.
+
+**Unit tests are NOT required before commit when:**
+
+- Only **coverage-omitted** large modules changed (`virt.py`, `infra.py`, `network.py`, `storage.py`) and the change is thin wiring (parameter pass-through, logging, default value) already covered by integration tests
+- The change is docs-only, import-only, or a rename with no behavior change
+
+When unit tests are not added, state why in the PR (`##### Special notes for reviewer:`) — e.g. "coverage-omitted `virt.py` helper; behavior covered by `test_migrate_snapshot_hotplugged_vm`".
+
 ## Essential Commands
 
 ### Before Committing Verification (MANDATORY)
 
 Before committing, these checks MUST pass:
 
+1. **Utilities unit test assessment** — per [Utilities Unit Test Requirements](#utilities-unit-test-requirements) above: add tests when required, or document why not
+2. **Commands below** — all must pass
+
 ```bash
 # Required before every commit
 uv run pre-commit run --all-files  # Linting and formatting
@@ -299,6 +321,7 @@ uv run tox -e utilities-unittests
 ## Related Documentation
 
 - [`docs/CODE_ORGANIZATION.md`](docs/CODE_ORGANIZATION.md) — Constants, utilities, and fixtures layout and import rules
+- [`utilities/unittests/README.md`](utilities/unittests/README.md) — Utilities unit test patterns and coverage status
 - [`docs/QUARANTINE_GUIDELINES.md`](docs/QUARANTINE_GUIDELINES.md) — Test quarantine and de-quarantine procedures
 - [`docs/SOFTWARE_TEST_DESCRIPTION.md`](docs/SOFTWARE_TEST_DESCRIPTION.md) — STD docstring format and requirements
 - [`docs/CODING_AND_STYLE_GUIDE.md`](docs/CODING_AND_STYLE_GUIDE.md) — Detailed coding and style conventions