docs: encode operator_add null-skip, exception lowering, and charset rules in xtend-to-java skill

[joaodinissf]

What

Hardens the .agents/skills/xtend-to-java skill with three faithfulness rules and one meta-lesson, all learned from an independent blind re-migration of check.core and a follow-up archaeology audit of the already-merged migrations.

The rules

1. rules/10 §10.5 — operator_add (+= over a collection) skips nulls. The single most dangerous inferrer trap. list += map[toField/toMethod/…] binds to JvmTypesBuilder.operator_add, which silently drops null elements; the to<Factory> builders return null on a null name/type. A bare addAll/loop-add leaks the null → IllegalArgumentException: element: null in production — past PMD, Checkstyle, SpotBugs, and every test that doesn't happen to feed a null. Faithful Java needs filterNull or an explicit null guard.
2. rules/05 §5.5 — Xtend exception lowering. catch (Specific) → catch (Throwable) + instanceof + sneakyThrow; an uncaught checked-exception body → sneakyThrow(raw) with no declared checked exceptions. Reproduce with Exceptions.sneakyThrow; never wrap in new RuntimeException(e)/IllegalStateException(e) (changes the observed exception type).
3. rules/09 §9.11 — charset is a sanctioned deviation. Specify StandardCharsets.UTF_8 (PMD RelianceOnDefaultCharset forbids the default); do not reproduce the default-charset constructor. General principle: where a valid lint rule conflicts with a literal xtend-gen behaviour on a latent-bug pattern, fix the bug.
4. known-pitfalls — behavioural equivalence ≠ literal-token equivalence. Don't decide "faithful" by whether a token appears in xtend-gen; test-validate every divergence — the gate is the arbiter.

Why now — this caught a real shipped bug

Rule 1 isn't hypothetical. Applying it to the merged migrations found that FormatJvmModelInferrer.inferConstants had translated the Xtend members += allConstants.map[createConstant] (null-skipping operator_add) into a bare for { it.getMembers().add(createConstant(format, c)); } — and createConstant returns null for a value-less constant. A null JvmMember leaks into the model, undetected by all gates and tests until a value-less constant is declared. That fix ships separately; this PR encodes the rule that prevents the next one.

Skill-only change (markdown under .agents/skills/); no build impact.

🤖 Generated with Claude Code