Skip to content

fix(ci): make agent gates deterministic per head - #311

Merged
abiorh-claw merged 2 commits into
mainfrom
codex/ws-eng-agent-gates-deterministic
Aug 10, 2026
Merged

fix(ci): make agent gates deterministic per head#311
abiorh-claw merged 2 commits into
mainfrom
codex/ws-eng-agent-gates-deterministic

Conversation

@Abiorh001

@Abiorh001 Abiorh001 commented Aug 10, 2026

Copy link
Copy Markdown
Collaborator

Workstream PR Trust Bundle

Chunk

WS-CI-002-01 — Single-Head Agent Gate

Root cause

Agent Gates used one required check name for both PR-head validation and live
approval polling. Dependency-manifest changes therefore produced failures
before approval and new runs after review submission or dismissal. GitHub could
retain contradictory same-head contexts, leaving an approved, fully tested PR
blocked until every historical failure was manually rerun.

What changed

  • Agent Gates now runs only for opened, synchronized, or reopened PR heads.
  • Per-PR concurrency cancels superseded in-progress runs.
  • Guide dependency validation remains blocking but no longer queries review state.
  • Protected-branch review rules remain the independent approval authority.
  • Obsolete GitHub review client code and its tests were removed.
  • Regression tests lock the deterministic trigger, least privilege, static
    dependency command, and rejection of the retired CLI argument.
  • Operations documentation now describes the actual authority boundary.

CI integrity

No dependency hashes, platform constraints, parser import boundaries, tests,
coverage floors, Backend lanes, or branch-protection requirements were weakened.
There is no fallback success or continue-on-error.

Evidence

  • 31 guide dependency tests passed.
  • 11 lightweight Agent Gates tests passed.
  • Ruff passed.
  • Markdown links and stale wording checks passed.
  • CI-integrity review: PASS WITH LOW RISKS; cleanup addressed.
  • Test-delta review: PASS WITH LOW RISKS; no required fixes.

Human review focus

Confirm that repository validation is deterministic per PR head and that
independent approval remains enforced by protected-branch review rules.

Human merge ownership

  • Root cause and fix are documented.
  • No CI or review authority was weakened.
  • The user explicitly approves this PR for merge.

Summary by CodeRabbit

  • CI Improvements
    • Agent Gates now run deterministically for each pull request head.
    • Superseded runs for the same pull request are automatically cancelled.
    • Checks run when pull requests are opened, updated, or reopened.
    • Protected-branch review approval remains enforced independently.
  • Bug Fixes
    • Removed review-state dependencies from automated dependency validation.
    • Added safeguards against unsupported approval-related command options.
  • Documentation
    • Updated testing and operations guidance to reflect the revised CI behavior.

@coderabbitai

coderabbitai Bot commented Aug 10, 2026

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

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

Next review available in: 41 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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e6651e3b-3408-405e-aac4-2eb6d8b33613

📥 Commits

Reviewing files that changed from the base of the PR and between d1cb4ad and 5ad7a6f.

📒 Files selected for processing (5)
  • .github/workflows/agent-gates.yml
  • backend/scripts/check_guide_extractor_dependencies.py
  • backend/tests/test_guide_extractor_dependencies.py
  • docs/operations_backend_testing.md
  • scripts/test_lightweight_agent_gates.py
📝 Walkthrough

Walkthrough

This change makes Agent Gates deterministic per pull request head. It removes review-state triggers and approval-fetching logic, adds cancellation for superseded runs, retains protected-branch approval enforcement, and updates regression tests and operations documentation.

Changes

Deterministic Agent Gates

Layer / File(s) Summary
Gate contract and initiative tracking
.agent-loop/CURRENT_STATE.md, .agent-loop/initiatives/WS-CI-002-deterministic-agent-gates/...
The initiative records and chunk contract define single-head Agent Gates, protected-branch approval authority, allowed changes, acceptance criteria, and verification steps.
Workflow and dependency-gate execution
.github/workflows/agent-gates.yml, backend/scripts/check_guide_extractor_dependencies.py
Agent Gates runs on opened, synchronized, and reopened pull requests. Superseded runs are cancelled. The dependency check uses a fixed no-argument interface and performs local validation without review or approval checks.
Regression checks and operational documentation
backend/tests/test_guide_extractor_dependencies.py, scripts/test_lightweight_agent_gates.py, docs/operations_backend_testing.md
Tests reject the removed approval argument and verify workflow triggers, permissions, concurrency, and dependency checks. Documentation records the independent protected-branch approval model.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name Status Explanation Resolution
Description check ⚠️ Warning The description explains the root cause and changes, but it omits many required template sections, including commands, acceptance proof, test delta, reviewer results, risks, and follow-up work. Complete the trust-bundle template with the missing required sections, test commands and results, acceptance-criteria proof, reviewer statuses, risks, follow-up work, and scope details.
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely describes the primary change: making Agent Gates deterministic for each pull request head.
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 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/ws-eng-agent-gates-deterministic

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

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 @.github/workflows/agent-gates.yml:
- Around line 5-9: Update the actions/checkout step in
.github/workflows/agent-gates.yml (lines 19-22) to set ref to ${{
github.event.pull_request.head.sha }}. Add a regression assertion in
scripts/test_lightweight_agent_gates.py (lines 124-134) verifying the workflow
contains this explicit PR-head checkout ref.

In `@scripts/test_lightweight_agent_gates.py`:
- Around line 124-126: Update the permission assertions in the relevant test to
reject any pull-requests permission, not only the read variant. Assert that the
broader “pull-requests:” key is absent from agent_gates while preserving the
existing checks for pull_request_review and --require-pr-approval.
🪄 Autofix

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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 7a28dac5-2563-4abb-8842-b2c531f77493

📥 Commits

Reviewing files that changed from the base of the PR and between ff38867 and d1cb4ad.

📒 Files selected for processing (8)
  • .agent-loop/CURRENT_STATE.md
  • .agent-loop/initiatives/WS-CI-002-deterministic-agent-gates/STATUS.md
  • .agent-loop/initiatives/WS-CI-002-deterministic-agent-gates/chunks/WS-CI-002-01-single-head-gate.md
  • .github/workflows/agent-gates.yml
  • backend/scripts/check_guide_extractor_dependencies.py
  • backend/tests/test_guide_extractor_dependencies.py
  • docs/operations_backend_testing.md
  • scripts/test_lightweight_agent_gates.py

Comment thread .github/workflows/agent-gates.yml
Comment thread scripts/test_lightweight_agent_gates.py Outdated
Comment on lines +124 to +126
self.assertNotIn("pull_request_review:", agent_gates)
self.assertNotIn("--require-pr-approval", agent_gates)
self.assertNotIn("pull-requests: read", agent_gates)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win

Reject all pull-requests permissions.

The test rejects only pull-requests: read. A change to pull-requests: write would pass this test and restore PR access. Assert that pull-requests: is absent.

Proposed fix
-        self.assertNotIn("pull-requests: read", agent_gates)
+        self.assertNotIn("pull-requests:", agent_gates)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
self.assertNotIn("pull_request_review:", agent_gates)
self.assertNotIn("--require-pr-approval", agent_gates)
self.assertNotIn("pull-requests: read", agent_gates)
self.assertNotIn("pull_request_review:", agent_gates)
self.assertNotIn("--require-pr-approval", agent_gates)
self.assertNotIn("pull-requests:", agent_gates)
🤖 Prompt for 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.

In `@scripts/test_lightweight_agent_gates.py` around lines 124 - 126, Update the
permission assertions in the relevant test to reject any pull-requests
permission, not only the read variant. Assert that the broader “pull-requests:”
key is absent from agent_gates while preserving the existing checks for
pull_request_review and --require-pr-approval.

@Abiorh001
Abiorh001 force-pushed the codex/ws-eng-agent-gates-deterministic branch from d1cb4ad to bd22524 Compare August 10, 2026 17:57
@abiorh-claw
abiorh-claw self-requested a review August 10, 2026 18:03
abiorh-claw
abiorh-claw previously approved these changes Aug 10, 2026
@abiorh-claw
abiorh-claw merged commit 640143c into main Aug 10, 2026
9 checks passed
@abiorh-claw
abiorh-claw deleted the codex/ws-eng-agent-gates-deterministic branch August 10, 2026 19:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants