docs(#1757): add Rego evaluation model guidance to AGENTS.md

[fullsend-ai-coder]

Add a "Rego Evaluation Model (for AI reviewers)" section to AGENTS.md covering Rego's declarative semantics, idiomatic testing patterns, and common anti-patterns that AI reviewers should avoid suggesting.

Key additions:

• Evaluation semantics: rules are OR/AND propositions, not functions
  with return values or control flow
• Testing idioms: testing conjunction terms independently is sufficient;
  do not request integration tests when clause coverage exists
• Idiomatic patterns table: some x in collection, object.get,
  set membership, negation
• Anti-patterns: no early returns, try/catch, null guards for
  parser-guaranteed keys, or integration test requests when coverage
  is 100%

This addresses repeated false-positive findings from PR #1745 where the review agent applied imperative-language heuristics to Rego code across 5 review cycles.

---

Closes #1757

Post-script verification

• Branch is not main/master (agent/1757-add-rego-paradigm-guidance)
• Secret scan passed (gitleaks — 7e57219e2d4844569bc4933063c0c2d2f1bed147..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 4:15 PM UTC · Completed 4:27 PM UTC
Commit: 47d3320 · View workflow run →

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Flag	Coverage Δ
unit-tests	100.00% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[fullsend-ai-review]

Review

Findings

Medium

• [technical accuracy] AGENTS.md:73 — The claim "Rules evaluate to true or undefined" is incomplete and misleading. Rego rules can evaluate to arbitrary values, not just true or undefined. Complete rules (defined with :=) evaluate to their assigned value, set rules produce sets, and object rules produce objects. This codebase uses value-producing rules extensively (e.g., task_ref(task) := j in policy/lib/tekton/refs.rego, warning_category(rule) := "invalid" in policy/lib/volatile/volatile_config.rego). Only boolean rules (no explicit value assignment) evaluate to true/undefined. Since this guidance targets AI reviewers, the oversimplification could cause reviewers to misunderstand how the majority of this codebase's rules work.
  Remediation: Revise to: "Boolean rules (no :=) evaluate to true or undefined. Rules defined with := evaluate to their assigned value, or undefined if no body matches. Functions accept arguments and produce values. None of these use imperative return statements — the value is determined by which rule body's conditions are satisfied."

• [technical accuracy] AGENTS.md:75 — The claim "There is no call/return mechanism" is factually incorrect. Rego has user-defined functions (e.g., f(x) := y if { ... }) that are called with arguments and produce values. This codebase uses them pervasively — task_ref(task), warning_category(rule), _param(task_ref, name, fallback), among many others. While Rego functions are not imperative (no early returns, no side effects), stating there is "no call/return mechanism" is wrong and will cause AI reviewers to mischaracterize function calls in review comments.
  Remediation: Revise to: "Rego has functions but no imperative control flow — no early returns, no exceptions, no side effects. A function evaluates to the value of whichever body's conditions are satisfied."

• [protected-path] AGENTS.md — This file is under a protected path (AGENTS.md). The PR links to issue Add Rego/OPA paradigm guidance to AGENTS.md to reduce false-positive review findings #1757 and provides clear rationale for the change, but human approval is always required for protected-path changes, regardless of context.

Low

• [internal consistency] AGENTS.md:70 — The statement "Do not describe Rego rules as 'returning' values" contradicts actual Rego semantics and codebase usage. Rego functions and complete rules DO produce values. While it is fair to discourage imperative framing like "early returns", advising AI reviewers to never say a rule "returns" a value will produce awkward or incorrect review language when discussing functions like task_ref(task) := j.
  Remediation: Soften to: "Avoid imperative framing like 'early return' or 'fallthrough'. It is acceptable to say a rule or function 'evaluates to' or 'produces' a value."

[fullsend-ai-review]

See the review comment for full details.

[fullsend-ai-review]

[medium] technical accuracy

The claim that rules evaluate to true or undefined is incomplete and misleading. Rego rules can evaluate to arbitrary values. Complete rules (defined with :=) evaluate to their assigned value, set rules produce sets, and object rules produce objects. This codebase uses value-producing rules extensively. Only boolean rules evaluate to true/undefined.

Suggested fix: Revise to: Boolean rules (no :=) evaluate to true or undefined. Rules defined with := evaluate to their assigned value, or undefined if no body matches. Functions accept arguments and produce values.

[fullsend-ai-review]

[medium] technical accuracy

The claim there is no call/return mechanism is factually incorrect. Rego has user-defined functions that are called with arguments and produce values. This codebase uses them pervasively. While Rego functions are not imperative, stating there is no call/return mechanism is wrong.

Suggested fix: Revise to: Rego has functions but no imperative control flow — no early returns, no exceptions, no side effects. A function evaluates to the value of whichever body conditions are satisfied.

[fullsend-ai-review]

[low] internal consistency

The statement Do not describe Rego rules as returning values contradicts actual Rego semantics. Rego functions and complete rules DO produce values. The guidance is overly prescriptive.

Suggested fix: Soften to: Avoid imperative framing like early return or fallthrough. It is acceptable to say a rule or function evaluates to or produces a value.