docs: document missing-value semantics and override handling in environment policies - #386

Improvement — the not matches(...) claim doesn't follow from the rule stated two paragraphs above, and needs a server check before it becomes canonical.

Line 159 says matches() evaluates to false when an operand is missing. Applying only that rule, a reader computes matches(flow.name, "^snyk-.*") → false, therefore not matches(flow.name, "^snyk-.*") → true — not is being applied to a present boolean, not to a missing operand. For both to be false as line 166 asserts, missingness has to propagate through not, which is a second, stronger rule the page never states.

The source entry in #376 (changelog/index.mdx, still unmerged) doesn't assert it either:

matches() and the ordering comparisons (<, >, <=, >=) now evaluate to false when either side is missing... Previously an expression like not matches(flow.name, "^snyk-.*") crashed snapshot compliance evaluation

That names the negation as the expression that used to crash, not as one that now returns false. So one of two things is true, and they need different text:

• Missingness propagates through not → say so explicitly ("a missing operand makes the comparison unsatisfiable; not does not turn it into true"), because it is the whole point of the section and no reader will infer it.
• It does not propagate → line 166 is wrong and the exists() workaround at line 169 is unnecessary, which sends policy authors to write a guard they don't need.

Also on line 159: "Every operator and function" is broader than both the enumeration that follows it and the source. The Operators table at lines 113–116 includes and, or, and not, which the enumeration omits — those combine boolean results and aren't covered. Scope the sentence to the comparison, membership, and function forms.

Fix this →

You are right, and this was my error rather than an ambiguity in the source. Fixed in ba9464b.

The claim was an extrapolation. The changelog entry says matches() is false when an operand is missing, and separately that not matches(flow.name, "^snyk-.*") previously crashed evaluation. I read the second as describing current behavior and wrote that the negation now returns false — which, as you show, requires missingness to propagate through not, a rule nothing states.

I removed the claim rather than replacing it with the opposite, because both readings are unverified and I cannot reach the server either. The exists() guard example went with it, since it only made sense under the propagation reading. It is now the one open question in the PR description, so whoever verifies knows it is the thing to settle; if propagation is real it needs its own explicit sentence, since no reader will infer it.

Worth noting I nearly repeated the mistake in the fix: my first pass replaced it with "the logical operators and, or, and not combine the boolean results of these comparisons, so they are unaffected" — which asserts non-propagation just as baselessly. Removed before pushing.

On the scoping half: also fixed. The sentence now names the comparison operators, in, exists(), and matches() explicitly and says nothing about and/or/not. Your finding 5 is in too — the section had "missing", "empty", and the table's "not null" for one state; it now uses "missing" throughout. I did not add anything about an explicitly empty tag value, since that is also unverified; it is listed in the PR description instead.

Improvement — "newest matching attestation" is ambiguous in a way that inverts the rule, and "overrides" is undefined anywhere on the site.

1. "matching" can be read two ways: matching the rule's name/type, or satisfying the rule. Under the second reading a reader concludes an older passing attestation still satisfies the rule after a newer one fails — the opposite of this sentence's own second half. chore: update changelog CLI v2.39.0/v2.39.1 and Platform updates #376 's entry says "evaluate the newest attestation including overrides", with no "matching", which is unambiguous. Name the fields the match is against.

2. grep -rn -i override over .md/.mdx finds no page that defines an override attestation — the only explanations on the site are changelog/index.mdx:44 and :157, and client_reference/ has no override command page (so it looks API/UI-only). A policy author who hits "including overrides" here has nowhere to go. Add a defining clause, and ideally a link to wherever an override is created.

Separately: this is the only place in the site where prose follows </Expandable> inside a ParamField — every other one puts its prose before the <Expandable>. Worth confirming on the deploy preview that it renders where you intend rather than below the collapsed toggle.

Both taken, in ba9464b — I used your suggestion close to verbatim.

1. The match is now pinned: "evaluated against the newest attestation whose name and type match the rule". Your reading of the ambiguity is the one that matters — "matching" as "satisfying" inverts the rule, and against a reference page that is worse than saying nothing.

2. Override now carries a defining clause ("an override supersedes the status of the attestation it overrides"), since there is nowhere to link. I confirmed your grep: no page defines the term, and there is no client_reference page for the command either.

That last point turned up something separate. The CLI clearly has an attest override command — shipped changelog entries reference attest override --commit — but there is no client_reference/kosli_attest_override.md and no config/navigation.json entry. Since client_reference/ is generated from the CLI, that looks like a generator gap rather than a page nobody wrote. Noted in the PR description; not chasing it here.

3. Placement fixed. Rather than confirm on the preview that prose after </Expandable> renders where I intended, I moved it above the <Expandable> to match every other ParamField on the site — the convention is the safer answer regardless of how it renders.

Improvement — == and != are in this list, but the generated schema doesn't put them there, and != is the one that inverts a policy.

schemas/policy/v1.json:72 is generated from the API's Pydantic models (per CLAUDE.md's Schemas section, kosli-dev/server is the source of truth) and states the rule as:

A missing (None) context value never matches: matches() and the ordering comparisons (<, >, <=, >=) return false if either operand is missing, and in is a list-membership test that returns false unless its right-hand side is a list containing the left-hand value.

That enumeration is matches() + the four ordering comparisons, with in described separately. This line adds == and !=. == is harmless either way, but != is not: under ordinary inequality semantics flow.tags.risk-level != "high" on a flow with no risk-level tag evaluates to true, not false. Written as an exception —

trail-compliance:
 required: true
 exceptions:
 - if: ${{ flow.tags.risk-level != "high" }}

— that waives trail compliance for every untagged flow, which is the opposite of what this page tells the author to expect. Since the section is meant to become the canonical statement, it shouldn't be broader than the source it's transcribed from.

Recommendation: mirror the schema's enumeration (matches(), the ordering comparisons, and in), and add ==/!= back only once someone confirms them against kosli-dev/server. If != really does return false for a missing operand, that's the single most surprising fact in this section and deserves its own sentence rather than a slot in a list.

Two smaller things on the same line:

• in — the schema's rule is stricter than "either operand is missing": in returns false unless the right-hand side is a list containing the value. Worth stating, since flow.name in flow.tags.teams fails for a reason this page doesn't cover.
• exists() — returning false for a missing operand is exists()'s contract, not an instance of the missing-value rule, and grouping it under "the comparison is simply not satisfied" reads oddly two lines above "test it with exists()". Pulling it out of the list would make line 166 land harder.

Fix this →