Add KQL string matching rules to the coding guidelines

[RolandKrummenacher]

🛠️ Description

The coding guidelines cover general practice, content, and the changelog, but say nothing about KQL — the primary language of the hub. docs-wiki/Coding-guidelines.md, AGENTS.md, and CONTRIBUTING.md don't mention KQL or Kusto at all today. That's part of why the redundant tolower() comparisons and word-search contains usages accumulated across the ingestion scripts until #2213 / #2220 — nothing in the project's written standards contradicted them.

This PR writes those rules down where both humans and AI assistants will find them.

docs-wiki/Coding-guidelines.md — a new ⚡ KQL section:

• String comparison: why tolower() in comparison position is always wrong (every KQL string operator is already case-insensitive; the _cs forms are the case-sensitive ones), with an avoid/prefer table for the common rewrites — tolower(x) contains → has, tolower(x) == → =~, tolower(a) != tolower(b) → !~, indexof(...) >= 0 → has, and dynamic operands not needing a tostring() wrapper.
• When contains is required: framed as a semantic distinction (whole term vs. arbitrary substring) rather than a performance one, with the legitimate cases — needles fused inside a larger token (ConsumedUnit contains 'MB' also matching Mbps), word-stem matching, and fragments that never form a whole term. Also documents the term-index limits for punctuation and sub-3-character needles.
• Verify before you swap: per-row cross-tabulation on real data rather than aggregate counts (which can hide offsetting false positives and negatives), plus a pointer to the executable equivalence harness added in Use case-insensitive KQL operators instead of tolower() comparisons #2220.

AGENTS.md — the rule is also stated inline under Coding Standards. That file already listed Bicep, PowerShell, markdown, and commit conventions but not KQL, and it's what both Claude Code (via CLAUDE.md) and Copilot (via .github/copilot-instructions.md) load. Stating it there means an assistant sees the rule without having to follow the link.

No behavior change — documentation only. The guidance is already enforced in CI by HubsKqlOperators.Tests.ps1 (from #2220); this PR documents the reasoning so contributors know why before the test tells them no.

📋 Checklist

🔬 How did you test this change?

• 🤏 Lint tests — markdownlint-cli2 with the repo config: 0 issues

📦 Deploy to test?

Not applicable — documentation only.

🙋‍♀️ Do any of the following that apply?

• 🚨 This is a breaking change.

📑 Did you update docs/changelog?

• N/A — docs-wiki is contributor documentation, not part of the release changelog. It syncs to the GitHub wiki automatically on merge to dev.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Documents project-specific KQL string-matching rules in the contributor coding standards so recurring anti-patterns (e.g., tolower() in comparisons and overuse of contains) are prevented via clear guidance alongside existing CI enforcement.

Changes:

• Adds a new ⚡ KQL section to docs-wiki/Coding-guidelines.md covering case-insensitive operators, has vs contains, and validation guidance.
• Adds a concise KQL rule summary to AGENTS.md under Coding Standards so assistants and contributors see it inline.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
docs-wiki/Coding-guidelines.md	Introduces detailed KQL string matching guidance (operators, has vs contains, and verification steps).
AGENTS.md	Adds an inline KQL standards summary referencing the coding guidelines and existing CI enforcement.

Suppressed comments (1)

docs-wiki/Coding-guidelines.md:65

• This row states that =~ accepts a dynamic operand directly. That can be true for scalar dynamic values, but it is not universally safe if the field can be an object/array (or otherwise not string-like), and may produce confusing comparisons. Suggest qualifying the guidance to avoid implying tostring() is never needed for dynamic fields.

| `tostring(Dyn.Field) =~ 'true'` | `Dyn.Field =~ 'true'` | These operators accept a dynamic operand directly |

[RolandKrummenacher]

Good catch on the dynamic-operand row — it was too absolute. Qualified in 150c52d.

Verified the actual behavior on a live cluster first, and the result is a bit different from what the comment assumed: tostring() is not the missing piece. Raw and tostring()-wrapped comparisons return identical results for every payload shape, objects and arrays included:

d.v	tostring(d.v)	d.v =~ 'true'	tostring(d.v) =~ 'true'	d.v has 'true'	tostring(d.v) has 'true'
"true" (string)	true	true	true	true	true
true (bool)	true	true	true	true	true
1 (number)	1	false	false	false	false
{"nested":"true"} (object)	{"nested":"true"}	false	false	true	true
["true"] (array)	["true"]	false	false	true	true
missing key	(empty)	false	false	false	false

So the real hazard isn't a missing cast — it's that a non-scalar gets compared against its JSON serialization, where has matches a value nested anywhere in the text ({"nested":"true"} has 'true' → true, while =~ → false). Adding tostring() produces the same JSON text and the same surprising result, so recommending it would give false confidence.

The table row is now scoped to scalar dynamic values, with an IMPORTANT note covering the JSON-serialization behavior, why tostring() doesn't help, and what to use instead — extract the member you mean (Dyn.Field.nested), or array_index_of() / set_has_element() for arrays. Every claim in that note was executed against a cluster.