Add Rego/OPA paradigm guidance to AGENTS.md to reduce false-positive review findings

[fullsend-ai-retro]

What happened

On PR #1745, the fullsend review agent made several findings that revealed a misunderstanding of Rego's declarative/Datalog semantics:

1. "Return values" language: The agent described Rego rules as having "return values" and suggested testing through a "public API" — concepts that don't apply in Rego. Rules evaluate to true/false via logical conjunction; there is no call/return mechanism.
2. Integration test insistence (5 iterations): The agent raised "no integration test through is_registry_dependency" in every review cycle (Jun 11, Jun 15 x3, Jun 16). The author repeatedly explained that in Rego, testing individual conjunction terms separately IS sufficient because rules compose declaratively. The agent never adapted.
3. Missed idiomatic improvements: The human reviewer (simonbaird) provided concrete Rego-idiomatic suggestions (some q in qualifiers, object.get, parsed_purl.version in {null, ""}) that significantly simplified the code. The bot never suggested these patterns despite having the code context.

The current AGENTS.md covers build commands, conventions, and architecture but includes no guidance about Rego's evaluation model or idiomatic testing patterns.

What could go better

The review agent's testing recommendations were calibrated for imperative languages where unit tests cover functions and integration tests cover APIs. In Rego, rules are logical propositions that compose via conjunction — testing each clause independently provides equivalent coverage to testing the composed rule. The agent's repeated insistence on integration tests was not just noise; it consumed author time across 5 dismissals and eroded trust in the bot's domain competence.

Confidence: High that adding Rego paradigm guidance would reduce these false positives. The agent already reads AGENTS.md for context. The pattern of the human reviewer providing better Rego-specific feedback confirms the gap is domain knowledge, not reasoning capability. Partially overlaps with fullsend-ai/fullsend#1609 (domain-specific semantics) but that issue targets Kubernetes RBAC specifically and proposes a platform-level fix, while this is repo-specific context that belongs in AGENTS.md.

Proposed change

Add a "Rego Language Model" or "How Rego Works" section to AGENTS.md covering:

1. Evaluation model: Rego rules are declarative propositions, not functions. Multiple rule bodies for the same name are OR-ed; conditions within a body are AND-ed. There are no "return values" — rules evaluate to true/undefined.
2. Testing idioms: Testing individual rule clauses separately is idiomatic and sufficient. Integration tests through higher-level rules are not required when each conjunction term has coverage. The repo enforces 100% coverage via make test.
3. Common patterns: some x in collection, object.get(obj, key, default), set membership via x in {a, b, c}, and not for negation. Reviewers should suggest these patterns when they see verbose alternatives.
4. What NOT to suggest: Don't recommend imperative patterns (early returns, try/catch, null guards for missing keys when the parser guarantees the key exists).

Example addition to AGENTS.md:

## Rego Evaluation Model (for AI reviewers)

Rego is a declarative policy language (Datalog-inspired), not imperative code:
- Multiple rule bodies with the same name are **disjunctions** (OR). Conditions within a body are **conjunctions** (AND).
- Rules evaluate to `true` or `undefined` — there are no "return values" or control flow.
- Testing each conjunction term independently is sufficient and idiomatic. Do not request integration tests through higher-level rules unless there is a specific composition bug.
- Prefer `some x in collection` over explicit iteration, `object.get(obj, key, default)` over key-existence checks, and `x in {a, b}` over chained equality.

Validation criteria

On the next 3-5 PRs to policy/lib/ files reviewed by fullsend-ai-review[bot]:

1. The agent should not describe Rego rules as having "return values" or suggest imperative patterns.
2. The agent should not request integration tests through higher-level rules when individual clause tests exist and coverage is 100%.
3. The agent should suggest idiomatic Rego patterns (e.g., some x in collection, object.get) when it sees verbose alternatives.

Measurable: count false-positive test-adequacy findings on Rego PRs before vs. after the AGENTS.md update.

---

Generated by retro agent from #1745

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 4:05 PM UTC · Completed 4:08 PM UTC
Commit: 47d3320 · View workflow run →

[fullsend-ai-triage]

Triage Summary

Severity: Medium · Category: Documentation

This issue is well-defined and ready for implementation. The review agent's behavior on PR #1745 clearly demonstrates a gap in Rego-specific domain knowledge in AGENTS.md, leading to repeated false-positive findings.

Problem

The review agent applies imperative-language heuristics to Rego code — describing rules as having "return values," insisting on integration tests through higher-level rules (across 5 review cycles), and missing idiomatic Rego patterns that the human reviewer caught.

Root Cause

AGENTS.md covers build/test commands and architecture but contains no guidance on Rego's declarative evaluation model. The agent defaults to imperative assumptions (functions have return values, unit tests need integration test counterparts) which don't apply to Rego's Datalog semantics.

Recommended Fix

Add a "Rego Evaluation Model" section to AGENTS.md covering:

1. Evaluation semantics — rules are propositions (OR/AND composition), not functions with return values
2. Testing idioms — testing conjunction terms separately is sufficient; don't request integration tests when clause coverage exists
3. Idiomatic patterns — some x in collection, object.get(obj, key, default), x in {a, b}
4. Anti-patterns — don't suggest early returns, try/catch, or null guards for parser-guaranteed keys

The issue provides a ready-to-use markdown block that can be added directly.

Proposed Test

Validation: On the next 3-5 PRs to policy/lib/ files:
1. Agent should not describe Rego rules as having "return values"
2. Agent should not request integration tests when individual clause tests exist
3. Agent should suggest idiomatic Rego patterns for verbose alternatives
Measure: Count false-positive test-adequacy findings before vs. after

This is distinct from fullsend-ai/fullsend#1609 (K8s RBAC knowledge at the platform level) — this issue targets repo-specific Rego context that belongs in AGENTS.md.

---

Labels: This is a documentation improvement to AGENTS.md adding Rego paradigm guidance for AI reviewers.

[fullsend-ai-coder]

🤖 Finished Code · ✅ Success · Started 4:10 PM UTC · Completed 4:13 PM UTC
Commit: 47d3320 · View workflow run →