docs(EC-1932): add Rego evaluation model guidance to AGENTS.md

[cuipinghuo]

Summary

• Add a "Rego Evaluation Model (for AI reviewers)" section to AGENTS.md
• Explains Rego's declarative semantics: disjunction/conjunction, no return values, no control flow
• Clarifies that testing individual conjunction terms independently is idiomatic and sufficient
• Lists preferred patterns (some x in collection, object.get, set membership)
• Explicitly tells AI reviewers not to suggest imperative patterns (early returns, try/catch, null guards, integration tests)

Ref: EC-1932
Upstream: #1757

Test plan

• Verify AI review agents stop suggesting imperative patterns on future Rego PRs
• Verify AI review agents stop requesting integration tests when individual clause tests exist

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@cuipinghuo, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 34 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 185321dc-d38f-4a97-bced-1d6b74b1d504

📥 Commits

Reviewing files that changed from the base of the PR and between 4f3b969 and 08be80e.

📒 Files selected for processing (1)

• AGENTS.md

📝 Walkthrough

Walkthrough

AGENTS.md adds a “Rego Evaluation Model” section. It documents declarative rule semantics, fallback behavior, testing guidance, preferred idioms, and imperative patterns to avoid.

Changes

Rego Evaluation Guidance

Layer / File(s)	Summary
Document Rego evaluation model AGENTS.md	The guidance covers OR/AND semantics, rule forms, fallback constructs, testing, collection and lookup idioms, and patterns to avoid.

Estimated code review effort: 1 (Trivial) | ~2 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the documentation change and its Rego evaluation model guidance.
Description check	✅ Passed	The description explains what changed, why it changed, the related ticket, and the planned verification steps.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-for-conforma]

PR Summary by Qodo

Document Rego evaluation model guidance for AI reviewers

📝 Documentation 🕐 Less than 5 minutes

AI Description

• Add guidance on Rego’s declarative evaluation semantics to reduce incorrect AI review feedback.
• Clarify idiomatic testing expectations (clause-level tests) and discourage integration-test
 demands.
• Recommend preferred Rego patterns and explicitly forbid imperative-code suggestions.

High-Level Assessment

The following are alternative approaches to this PR:

1. Move guidance into a dedicated Rego style guide doc

• ➕ Keeps AGENTS.md shorter and more focused
• ➕ Allows future expansion (examples, anti-patterns, FAQs) without bloating contributor guidance
• ➖ One more document for contributors/reviewers to discover
• ➖ Less likely to be read by default than a single canonical AGENTS.md

2. Enforce guidance via reviewer/agent configuration (prompt template or linted review checklist)

• ➕ More reliably influences AI review behavior than passive documentation
• ➕ Can be updated centrally without editing repo docs
• ➖ May not apply across all review entry points/tools
• ➖ Harder to version alongside policy code expectations

Recommendation: The PR’s approach (a concise, explicit section in AGENTS.md) is the best default because it’s discoverable at the repository’s primary reviewer guidance entry point and directly addresses recurrent AI review failure modes. Consider a follow-up only if the section grows substantially (split to a dedicated Rego style guide) or if AI tooling supports centralized prompt/checklist enforcement.

Files changed (1) +13 / -0

Documentation (1) +13 / -0

AGENTS.mdAdd Rego evaluation model guidance for AI reviewers +13/-0

Add Rego evaluation model guidance for AI reviewers

• Introduces a new section explaining Rego’s declarative semantics (disjunction vs conjunction, true/undefined results) and sets expectations for idiomatic testing. Adds preferred Rego patterns and explicitly discourages imperative review suggestions (returns/control flow, try/catch, null guards, and unnecessary integration tests).

AGENTS.md

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 3:22 AM UTC · Ended 3:30 AM UTC
Commit: 87c4a29 · View workflow run →

[qodo-for-conforma]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. Misstates Rego semantics ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

AGENTS.md claims Rego rules only evaluate to true/undefined and have no “return values” or
control flow, but this repo widely uses value-producing rules (function-like := rules) plus
else/default for rule selection. This guidance can lead reviewers to incorrectly flag or
misunderstand common, valid patterns used throughout policy/lib/*.

Code

AGENTS.md[R63-66]

+- 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

Relevance

●●● Strong

Team often accepts fixes for misleading guidance/comments; correcting inaccurate Rego semantics
aligns with prior doc corrections.

PR-#1779
PR-#1609

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The added AGENTS.md bullet conflicts with existing repo patterns: the policy libraries define many
value-producing rules via := (e.g., parse(ref) := d) and use else/default as a selection
mechanism, so it’s incorrect to describe Rego rules as only boolean or to say control-flow-like
selection constructs don’t exist at all.

AGENTS.md[60-71]
policy/lib/image/image.rego[5-58]
policy/lib/tekton/pipeline.rego[66-111]
policy/lib/sigstore/sigstore.rego[5-17]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`AGENTS.md` currently states that Rego rules evaluate only to `true`/`undefined` and that there are no “return values” or control flow. In this repo, rules are frequently *value-producing* (function-like complete rules) and use `else` and `default` for declarative rule selection.

### Issue Context
The current wording is likely intended to discourage imperative suggestions (early returns, try/catch, etc.), but it overgeneralizes and contradicts common patterns used in this codebase.

### Fix Focus Areas
- AGENTS.md[60-71]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context used

✅ Compliance rules (platform): 15 rules

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

[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.
see 6 files with indirect coverage changes

🚀 New features to boost your workflow:

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

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 3:31 AM UTC · Completed 3:43 AM UTC
Commit: 87c4a29 · View workflow run →

[fullsend-ai-review]

Review

Findings

Medium

• [protected-path] AGENTS.md — This PR modifies AGENTS.md, which is a protected governance file requiring human approval for all changes. The PR links to Issue Add Rego/OPA paradigm guidance to AGENTS.md to reduce false-positive review findings #1757 and the description explains the rationale (adding Rego evaluation model guidance to reduce false-positive review findings). Human approval is always required for protected-path changes, regardless of context.

Low

• [scope-completeness] AGENTS.md:60 — Issue Add Rego/OPA paradigm guidance to AGENTS.md to reduce false-positive review findings #1757 specifically mentions the problem of AI using "return values" language inappropriate for Rego (complaint First unit test and Github action #1 in the issue), but the added section does not explicitly call out avoiding "return value" terminology. The DO NOT section covers early returns, try/catch, and exception handling, but the "return values" framing issue is only implicitly addressed by the declarative semantics explanation rather than explicitly prohibited. This is a minor gap — the existing content likely prevents the behavior in practice.

Previous run

Review

Findings

Medium

• [protected-path] AGENTS.md — This PR modifies AGENTS.md, which is a protected governance file. The change is well-justified by issue Add Rego/OPA paradigm guidance to AGENTS.md to reduce false-positive review findings #1757 and the PR description explains the rationale clearly, but human approval is always required for protected-path changes regardless of context.

Previous run (2)

Review

Findings

Medium

• [protected-path] AGENTS.md — This PR modifies AGENTS.md, a protected governance file. The change is well-justified by linked issue Add Rego/OPA paradigm guidance to AGENTS.md to reduce false-positive review findings #1757 and the PR description explains the rationale, but human approval is always required for protected-path changes regardless of context.

Previous run (3)

Review

Findings

Medium

• [protected-path] AGENTS.md — This PR modifies AGENTS.md, which is a protected governance file. The change is authorized by issue Add Rego/OPA paradigm guidance to AGENTS.md to reduce false-positive review findings #1757 and the rationale is clear (adding Rego evaluation model guidance for AI reviewers). Human approval is always required for protected-path changes, regardless of context.

Low

• [technical accuracy] AGENTS.md:65 — The sentence "Rules can be boolean (deny contains ...) or value-producing (f(x) := y, complete rules)" conflates Rego terminology. In OPA/Rego, deny contains ... is a "partial set rule" (not simply "boolean"), f(x) := y is a "function", and "complete rules" are name := value { ... } (no arguments). The parenthetical "(complete rules)" is placed ambiguously after the function syntax, which could mislead an AI reviewer into treating functions and complete rules as the same concept.
  Remediation: Consider: "Rules can define partial sets (deny contains ...), complete values (allowed := true), or functions (f(x) := y)."

---

Labels: PR is a pure documentation change to AGENTS.md adding Rego evaluation model guidance

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 7:49 PM UTC · Completed 7:59 PM UTC
Commit: 87c4a29 · View workflow run →

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@AGENTS.md`:
- Around line 68-69: Update the testing guidance in AGENTS.md to remove the
claim that independent conjunction-term tests are sufficient, and permit
higher-level integration tests when rule composition affects behavior, including
bindings, aggregation, fallback selection, or final violation output. Retain the
preference for focused tests unless composition-specific behavior requires
coverage.
- Around line 72-73: Update the guidance around the prohibition in AGENTS.md to
restrict it to constructs Rego does not provide: retain the bans on early
returns and try/catch, remove the blanket ban on null guards, and allow tests of
entry-point or composed rule output.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1d99898a-6537-487c-954a-99e8c127086e

📥 Commits

Reviewing files that changed from the base of the PR and between 4510bf1 and 4f3b969.

📒 Files selected for processing (1)

• AGENTS.md

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 8:03 PM UTC · Completed 8:12 PM UTC
Commit: 87c4a29 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 8:15 PM UTC · Completed 8:26 PM UTC
Commit: 87c4a29 · View workflow run →

[fullsend-ai-review]

See the review comment for full details.

[jsmid1]

LGTM

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 2:05 PM UTC · Completed 2:21 PM UTC
Commit: 87c4a29 · View workflow run →

[fullsend-ai-retro]

Retro: PR #1790 — Add Rego evaluation model guidance to AGENTS.md

Timeline

1. Jun 22: Retro agent creates issue #1757 after PR feat: Ignore local go dependencies when using proxy #1745 — identifying repeated false-positive review findings (imperative patterns, integration test demands) on Rego code.
2. Jun 22: Code agent creates PR #1759 (Closes #1757). Review agent requests changes.
3. Aug 3 03:21 UTC: Human author cuipinghuo creates PR #1790 addressing the same issue via internal ticket EC-1932.
4. Aug 3: Five review runs dispatched (1 cancelled by concurrency group, 4 successful). Total review cost: ~$10.50. Multiple bots (qodo, coderabbit, fullsend) provide substantive feedback.
5. Aug 3 03:43–20:26: Author iterates via force-push across 4 versions, incorporating feedback from all three review bots.
6. Aug 4 08:54: Human reviewer jsmid1 approves with "LGTM".
7. Aug 5 14:05: PR merged.

What went well

• The feedback loop delivered a real outcome. The retro agent identified a genuine problem on PR feat: Ignore local go dependencies when using proxy #1745, created issue Add Rego/OPA paradigm guidance to AGENTS.md to reduce false-positive review findings #1757, and the system produced a working fix — first attempted by the code agent (PR docs(#1757): add Rego evaluation model guidance to AGENTS.md #1759), then refined and shipped by a human (PR docs(EC-1932): add Rego evaluation model guidance to AGENTS.md #1790). This is the intended workflow operating end-to-end.
• Substantive review quality. The fullsend review agent's Run 2 caught a real terminology conflation (Rego partial set rules, functions, and complete rules were mislabeled). The author fixed it. The qodo bot independently flagged a related semantics issue. CodeRabbit provided two actionable suggestions about testing guidance and prohibition scope, both addressed in subsequent commits.
• Protected-path correctly enforced. All runs correctly identified AGENTS.md as a governance file requiring human approval, preventing auto-merge.

What could go better

• Redundant review runs. Four successful runs for a 16-line docs change (~$10.50 total). Runs 3 and 4 found only the protected-path governance notice — no actionable code findings. This is evidence for the cluster of existing dedup issues (fullsend#893, Add policy rules to verify test_results att #1390, Bump github.com/open-policy-agent/opa from 0.70.0 to 1.4.0 in /acceptance #1418, #5007, #5139).
• Orphaned issue and PR. Issue Add Rego/OPA paradigm guidance to AGENTS.md to reduce false-positive review findings #1757 remains open and PR docs(#1757): add Rego evaluation model guidance to AGENTS.md #1759 (code agent's version) remains open despite PR docs(EC-1932): add Rego evaluation model guidance to AGENTS.md #1790 merging the same change. PR docs(EC-1932): add Rego evaluation model guidance to AGENTS.md #1790 references Add Rego/OPA paradigm guidance to AGENTS.md to reduce false-positive review findings #1757 via a link but does not use GitHub closing keywords. This is evidence for agents#586 (retro agent should detect when a merged PR supersedes open agent-created PRs/issues).
• Model availability degraded runs 3–4. Three of four sub-agents failed on claude-sonnet-4-5@20250929 via Vertex on runs 3 and 4. The agent retried with the parent opus model — a reasonable fallback, but contributing to cost without new findings.

Proposal filed

One proposal below: the review orchestrator's challenger empty-result fallback heuristic prevents the challenger from legitimately clearing all findings on a single-finding review.

Proposals filed

• Challenger empty-result fallback prevents valid exoneration of single-finding reviews (in fullsend-ai/agents)