feat: implement revision-guard for automated PR drafting and queue health management

[darshit2308]

Problem

Currently, the PR review lifecycle has a few gaps that can lead to wasted reviewer time and noisy bot interactions:

1. Stale/Incomplete PRs in the Queue: When a maintainer clicks "Request Changes" on a PR, the PR remains open. It can easily be accidentally re-reviewed before the author has actually pushed fixes.
2. Format Failures: If a PR is opened but fails basic formatting checks (missing DCO, missing issue link, GPG signature missing), it still sits in the open PR list. Reviewers might start looking at structurally invalid PRs.
3. Notification Spam vs. Silent Failures: If a bot comments every time a check fails, it spams the PR. If it uses basic deduping (only posting once), authors might not get notified if their second attempt also fails.

Solution

I propose introducing a new, self-contained automation module called revision-guard.

Architecture Note: This module will be built using the exact same self-contained folder pattern established by review-sync (e.g., its own index.js, package.json, helpers/, and tests/). This modularity ensures it can be effortlessly migrated to the centralized sdk-automations repository in the future.

The revision-guard will manage the "draft" lifecycle of PRs using three safe, distinct triggers:

1. Auto-Draft on CHANGES_REQUESTED (Real-Time)
When a reviewer requests changes, the PR is automatically converted to a Draft.

• Action: Converts to Draft, removes any queue:* labels, applies status: needs-revision, and posts a notification to the author.
• Security: Uses the existing safe two-workflow pattern (pull_request_review saves an artifact -> workflow_run picks it up with write permissions).

2. Auto-Draft on Format Failures (Cron-Integrated)
If a PR is missing DCO, issue links, or has merge conflicts, it should not be in the review queue.

• Action: We integrate format checks directly into the review-sync cron job. Before the cron applies a queue:* label, it runs format checks. If they fail, revision-guard converts the PR to draft, applies status: needs-revision, and skips applying the queue label.
• Benefit: This completely eliminates the "Ready for Review" timing gap. If an author clicks "Ready for review" but hasn't fixed the format, the next cron run will instantly draft it again without ever putting it back in the reviewer queue.

3. CI Pipeline Failures (Label Only)

• Action: If the actual CI pipeline fails (tests, build), the cron will apply a status: failed checks label.
• Note: We will not auto-draft on CI failures, as these could be due to flaky tests or repo-side infrastructure issues, which isn't the contributor's fault.

4. Edit-In-Place Notifications (Anti-Spam)
To solve the notification problem, revision-guard will use an "edit-in-place" comment strategy (postOrUpdateComment).

• Instead of posting 5 comments for 5 failed attempts, the bot finds its existing notification comment (via HTML markers) and edits it with the latest timestamp and failure details.
• Because GitHub sends notifications on comment edits, the author is always informed when their PR is kicked back to draft, but the PR timeline remains perfectly clean.

Alternatives

1. Auto-undrafting when the user pushes new commits: Considered and rejected. An author might push a partial fix (e.g., addressing 1 out of 3 comments). It is much safer to let the author manually click the "Ready for review" button when they are completely finished.
2. Posting new comments on every redraft: Considered and rejected. This would create massive comment spam on PRs where contributors are struggling with DCO/formatting. The edit-in-place approach provides notifications without the spam.

[NssGourav]

/assign

[exploreriii]

This is a good idea
Just a thought that status: needs-revision might be reundant if moved to draft anyway, and the user lacks insight into why it needs revision. Maybe we could either label dco/etc, or use some kind of dashboard that makes it clear - but i think the c++ does that, so is perhaps better to avoid duplicating that for now.

for status: failed checks, rather than queue: junior committer maybe junior's can help to triage what to do with it manually. Request changes or get other help. i.e. some kind of help: junior-committer could be useful -- but this might not be a good idea as it adds a lot of differentiation maybe unique to our pipeline

4. i guess we are going with the lightweight dashboard approach!
   Do we need to add notifications at this stage?

Overall, i like the idea and suggest no changes from this at this stage other than perhaps removing notifications, just to avoid some duplication maybe at this stage. Perhaps think how to keep this decoupled in case we merge with c++

[exploreriii]

I will rank this is as higher level intermediate issue because it involves lots of permission handling, pr status handling, consolidation of our auto-draft workflows and also test failure (primary check notifications), state transitions can create conflicts and tests will have to handle various cases.

[github-actions]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Create a self-contained revision-guard module mirroring the review-sync architecture (helpers barrel, constants, tests) for future portability
• Implement draft conversion via GraphQL mutation with crash-safe label management (add new labels before removing old ones)
• Use the established two-workflow security pattern for real-time CHANGES_REQUESTED handling, keeping fork PRs safe
• Integrate format checks into the existing review-sync cron loop, gating queue label assignment on format compliance to eliminate the "ready for review" timing gap

Design Choices

Design Choice 1: DCO Check Implementation Approach

Options Considered:

1. Parse commit messages for "Signed-off-by:" trailer using GitHub's commits API
2. Use a third-party DCO action/service
3. Defer DCO checking to a later phase, focusing on other format checks first

Chosen Option: 1

Rationale: Parse commit messages directly via the commits API, consistent with how bot-verified-commits.js iterates commits for GPG verification. This keeps the module self-contained without external dependencies.

Design Choice 2: Module Import Strategy Between review-sync and revision-guard

Options Considered:

1. revision-guard exports library functions that review-sync imports via relative require
2. Duplicate format check logic in review-sync to maintain complete module isolation
3. Create a shared utilities module in .github/scripts/shared/

Chosen Option: 1

Rationale: revision-guard exports functions via its helpers/ barrel, and review-sync imports them using require('../revision-guard/helpers'). This maintains revision-guard's self-contained design while enabling integration, and the dependency is explicit and easy to update during future migration.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Create revision-guard Module Foundation

Establish the module structure following the review-sync pattern exactly, implementing core utilities for draft conversion and comment management.

Task 1: Create Module Directory Structure

Set up the revision-guard module scaffold with all required files and directories.

• Create .github/scripts/revision-guard/ directory
• Add package.json with private: true, main: "index.js", and scripts.test chaining test files
• Add helpers/index.js as barrel export using named namespaces pattern
• Add helpers/constants.js defining STATUS_LABELS (needs-revision, failed-checks), COMMENT_MARKER, and RATE_LIMIT_FLOOR
• Include // SPDX-License-Identifier: Apache-2.0 header on all files

Task 2: Implement Draft Conversion Helper

Create the GraphQL-based draft conversion utility with label management.

• Add helpers/draft.js exporting convertToDraft, removeQueueLabels, applyStatusLabel
• Implement convertToDraft using GitHub GraphQL API's convertPullRequestToDraft mutation (requires PR node ID)
• Implement removeQueueLabels to strip all queue:* labels from ALL_QUEUE_LABEL_NAMES (import from review-sync constants)
• Implement applyStatusLabel to add status: needs-revision or status: failed-checks (create if not exists, handle 422 race)
• Add dryRun parameter support throughout, logging actions when true

Task 3: Implement Post-or-Update Comment Utility

Create the edit-in-place comment helper for anti-spam notifications.

• Add helpers/comments.js exporting postOrUpdateComment, findBotComment
• Implement findBotComment to paginate issues.listComments and find comment containing HTML marker
• Implement postOrUpdateComment that calls findBotComment first, then either issues.updateComment (if found) or issues.createComment (if not)
• Accept parameters: github, owner, repo, issueNumber, marker, bodyGenerator (function returning comment body with marker embedded)
• Include timestamp in generated comments so edits are visible in the timeline

🤖 Prompt for AI agents

Create the foundational module structure for `revision-guard` under
`.github/scripts/revision-guard/`, mirroring the architecture of the existing
`review-sync` module.

**Directory & Config Files:**
- Create `.github/scripts/revision-guard/` directory with `package.json`
(`private: true`, `main: "index.js"`, `scripts.test` chaining test files)
- Add `helpers/index.js` as a barrel export using named namespaces pattern
- Add `helpers/constants.js` defining:
  - `STATUS_LABELS` with values `needs-revision` and `failed-checks`
  - `COMMENT_MARKER` (HTML marker string for bot comment identification)
  - `RATE_LIMIT_FLOOR`
- All files must include `// SPDX-License-Identifier: Apache-2.0` header

**Draft Conversion Helper (`helpers/draft.js`):**
- Export `convertToDraft`, `removeQueueLabels`, `applyStatusLabel`
- `convertToDraft`: use GitHub GraphQL API's `convertPullRequestToDraft`
mutation, requiring PR node ID
- `removeQueueLabels`: strip all `queue:*` labels using `ALL_QUEUE_LABEL_NAMES`
imported from review-sync constants
- `applyStatusLabel`: add `status: needs-revision` or `status: failed-checks`;
create label if not exists and handle 422 race condition
- All three functions must support a `dryRun` parameter that logs actions
instead of executing writes

**Comment Utility (`helpers/comments.js`):**
- Export `postOrUpdateComment` and `findBotComment`
- `findBotComment`: paginate `issues.listComments`, returning the comment that
contains the HTML marker or `null`
- `postOrUpdateComment`: call `findBotComment` first, then call
`issues.updateComment` if found, or `issues.createComment` if not
- Accept parameters: `github`, `owner`, `repo`, `issueNumber`, `marker`,
`bodyGenerator` (function returning comment body with marker embedded)
- Include a timestamp in generated comments so edits are visible in the timeline

Phase 2: Implement Format Validation Helpers

Build the format check functions that determine whether a PR meets structural requirements.

Task 1: Implement Issue Link Check

Check whether a PR has a closing issue reference.

• Add helpers/format-checks.js with checkIssueLink export
• Use GraphQL closingIssuesReferences query (same pattern as bot-pr-missing-linked-issue.js)
• Return { passed: boolean, details: string } indicating whether at least one OPEN linked issue exists
• Skip check for bot-authored PRs (return passing)

Task 2: Implement GPG Signature Check

Verify all commits in a PR are signed.

• Add checkGpgSignatures to helpers/format-checks.js
• Paginate pulls.listCommits, check commit.verification.verified on each
• Return { passed: boolean, details: string, unverifiedCount: number }
• Follow same pagination limits as bot-verified-commits.js (MAX_PAGES=5)

Task 3: Implement DCO Check

Verify all commits have "Signed-off-by:" trailer.

• Add checkDco to helpers/format-checks.js
• Reuse commit list from GPG check (or accept commits array to avoid duplicate API calls)
• Parse commit.message for Signed-off-by: line (case-insensitive)
• Return { passed: boolean, details: string, missingCount: number }

Task 4: Implement Merge Conflict Check

Check whether PR has merge conflicts.

• Add checkMergeConflicts to helpers/format-checks.js
• Use pulls.get to fetch PR and check mergeable field and mergeable_state
• Return { passed: boolean, details: string } (failed if mergeable === false or mergeable_state === 'dirty')
• Handle mergeable === null (GitHub still computing) by treating as passing to avoid false positives

Task 5: Create Format Check Aggregator

Combine all format checks into a single orchestrated call.

• Add runAllFormatChecks to helpers/format-checks.js
• Accept github, owner, repo, pr (full PR object)
• Run all four checks: issue link, GPG signatures, DCO, merge conflicts
• Return { passed: boolean, failures: Array<{ check: string, details: string }> }
• Short-circuit on first failure for efficiency, or run all and aggregate (prefer aggregate for better error messages)

🤖 Prompt for AI agents

Implement all format validation logic in `helpers/format-checks.js` within the
`revision-guard` module.

**`checkIssueLink(github, owner, repo, pr)`:**
- Use GraphQL `closingIssuesReferences` query (matching the pattern in
`bot-pr-missing-linked-issue.js`)
- Return `{ passed: boolean, details: string }` — passes if at least one OPEN
linked issue exists
- Skip check and return passing for bot-authored PRs

**`checkGpgSignatures(github, owner, repo, prNumber)`:**
- Paginate `pulls.listCommits`, checking `commit.verification.verified` on each
commit
- Return `{ passed: boolean, details: string, unverifiedCount: number }`
- Use same pagination limits as `bot-verified-commits.js` (MAX_PAGES=5)

**`checkDco(commits)`:**
- Accept a commits array (to avoid duplicate API calls with GPG check)
- Parse `commit.message` for `Signed-off-by:` line (case-insensitive)
- Return `{ passed: boolean, details: string, missingCount: number }`

**`checkMergeConflicts(github, owner, repo, prNumber)`:**
- Use `pulls.get` to fetch PR; check `mergeable` field and `mergeable_state`
- Return `{ passed: boolean, details: string }`
- Fail if `mergeable === false` or `mergeable_state === 'dirty'`
- Treat `mergeable === null` (still computing) as passing to avoid false
positives

**`runAllFormatChecks(github, owner, repo, pr)`:**
- Run all four checks (issue link, GPG signatures, DCO, merge conflicts) and
aggregate results
- Return `{ passed: boolean, failures: Array<{ check: string, details: string }>
}`
- Prefer running all checks and aggregating (rather than short-circuiting) for
better error messages

Phase 3: Auto-Draft on CHANGES_REQUESTED

Implement the real-time two-workflow pattern for converting PRs to draft when reviewers request changes.

Task 1: Create Compute Workflow

Build the first workflow that triggers on review submission and saves PR metadata as artifact.

• Create .github/workflows/revision-guard-compute.yml
• Trigger: pull_request_review with types: [submitted]
• Condition: only proceed if github.event.review.state == 'changes_requested'
• Permissions: contents: read only (safe for fork PRs)
• Write JSON artifact with pr_number, pr_node_id, reviewer, timestamp
• Upload artifact with name revision-guard-payload

Task 2: Create Apply Workflow

Build the second workflow that picks up the artifact and performs the draft conversion.

• Create .github/workflows/revision-guard-apply.yml
• Trigger: workflow_run on revision-guard-compute with types: [completed]
• Condition: only proceed if github.event.workflow_run.conclusion == 'success'
• Permissions: pull-requests: write, issues: write, contents: read, actions: read
• Download artifact, parse PR metadata
• Call revision-guard module via actions/github-script to convert to draft
• Include concurrency guard to prevent duplicate runs

Task 3: Implement Workflow Handler Entry Point

Create the main index.js that handles the CHANGES_REQUESTED workflow invocation.

• Add .github/scripts/revision-guard/index.js
• Export async function accepting { github, context, core, prNumber, prNodeId }
• Check if PR is already a draft (skip if so)
• Call convertToDraft, removeQueueLabels, applyStatusLabel('needs-revision')
• Call postOrUpdateComment with marker <!-- revision-guard --> explaining why PR was drafted
• Support DRY_RUN env var for all write operations

🤖 Prompt for AI agents

Implement the real-time two-workflow security pattern and the module entry point
for handling `CHANGES_REQUESTED` events.

**Compute Workflow (`.github/workflows/revision-guard-compute.yml`):**
- Trigger: `pull_request_review` with `types: [submitted]`
- Condition: only proceed if `github.event.review.state == 'changes_requested'`
- Permissions: `contents: read` only (fork-safe)
- Write a JSON artifact containing `pr_number`, `pr_node_id`, `reviewer`,
`timestamp`
- Upload artifact named `revision-guard-payload`

**Apply Workflow (`.github/workflows/revision-guard-apply.yml`):**
- Trigger: `workflow_run` on `revision-guard-compute` with `types: [completed]`
- Condition: only proceed if `github.event.workflow_run.conclusion == 'success'`
- Permissions: `pull-requests: write`, `issues: write`, `contents: read`,
`actions: read`
- Download artifact and parse PR metadata
- Invoke the revision-guard module via `actions/github-script` to convert the PR
to draft
- Include a concurrency guard to prevent duplicate runs

**Entry Point (`.github/scripts/revision-guard/index.js`):**
- Export an async function accepting `{ github, context, core, prNumber,
prNodeId }`
- Check if PR is already a draft; skip all operations if so
- Call `convertToDraft`, `removeQueueLabels`, and
`applyStatusLabel('needs-revision')` in sequence
- Call `postOrUpdateComment` using marker `<!-- revision-guard -->` to explain
why the PR was drafted
- Respect `DRY_RUN` env var to skip all write operations

Phase 4: Integrate with review-sync Cron

Modify the existing review-sync module to perform format checks and apply status labels before queue label assignment.

Task 1: Import revision-guard Helpers into review-sync

Enable review-sync to use revision-guard's format checking and draft conversion functions.

• Update .github/scripts/review-sync/index.js to require revision-guard helpers
• Import runAllFormatChecks, convertToDraft, removeQueueLabels, applyStatusLabel, postOrUpdateComment from ../revision-guard/helpers

Task 2: Add Format Check Gate Before Queue Label Sync

Insert format validation into the per-PR sync loop.

• In review-sync's main loop, before calling syncLabel, call runAllFormatChecks
• If format checks fail: call revision-guard's draft conversion functions, post/update notification comment, skip queue label assignment, continue to next PR
• If format checks pass: proceed with existing queue label logic
• Track format-failure count separately in summary output

Task 3: Add CI Failure Label Application

Apply status: failed checks label when CI is failing (without auto-drafting).

• In review-sync's syncLabel flow, after hasCIFailures check returns true
• Call applyStatusLabel('failed-checks') (use revision-guard helper or inline ensureLabel)
• Do NOT convert to draft (per ticket: CI failures may not be contributor's fault)
• Continue with normal queue label assignment (JUNIOR queue per existing logic)
• Remove status: failed-checks label if CI is now passing (cleanup)

Task 4: Define and Ensure Status Labels Exist

Add the new status labels to the label creation flow.

• Add STATUS_NEEDS_REVISION and STATUS_FAILED_CHECKS label definitions to revision-guard constants
• Update review-sync's label-ensure phase to also ensure these two labels exist
• Use consistent colors: suggest red/orange for visibility

🤖 Prompt for AI agents

Modify the existing `review-sync` module to integrate format checks and status
label management from `revision-guard`.

**Import revision-guard Helpers (`.github/scripts/review-sync/index.js`):**
- Add `require('../revision-guard/helpers')` to import `runAllFormatChecks`,
`convertToDraft`, `removeQueueLabels`, `applyStatusLabel`, and
`postOrUpdateComment`

**Format Check Gate in Main Loop:**
- Before calling `syncLabel` in review-sync's per-PR loop, call
`runAllFormatChecks`
- On failure: call `convertToDraft`, `removeQueueLabels`, post/update
notification comment via `postOrUpdateComment`, skip queue label assignment, and
continue to next PR
- On pass: proceed with existing queue label logic
- Track format-failure count separately in the summary output

**CI Failure Label Application (in `syncLabel` flow):**
- After `hasCIFailures` returns true, call `applyStatusLabel('failed-checks')`
- Do NOT convert to draft (CI failures may not be the contributor's fault)
- Continue with normal queue label assignment (JUNIOR queue per existing logic)
- Remove `status: failed-checks` label when CI is now passing (cleanup)

**Status Label Definitions:**
- Add `STATUS_NEEDS_REVISION` and `STATUS_FAILED_CHECKS` to revision-guard's
`helpers/constants.js`
- Update review-sync's label-ensure phase to also ensure these two labels exist
- Use red/orange colors for visibility

Phase 5: Create Test Suite

Build comprehensive tests following the review-sync testing pattern.

Task 1: Create Test Infrastructure

Set up shared test utilities for revision-guard.

• Add tests/test-utils.js extending patterns from review-sync's test-utils
• Implement createMockGithub with additional tracking for: draftConversions, commentUpdates, commentsCreated
• Add mock for GraphQL API calls (for convertToDraft mutation)
• Implement runTestSuite and printSummaryAndExit helpers

Task 2: Create Draft Helper Tests

Test the draft conversion and label management functions.

• Add tests/test-draft.js
• Test convertToDraft calls correct GraphQL mutation with node ID
• Test removeQueueLabels removes all queue labels, handles 404 gracefully
• Test applyStatusLabel creates label if missing, handles 422 race
• Test dry-run mode skips all write operations

Task 3: Create Comment Helper Tests

Test the post-or-update comment functionality.

• Add tests/test-comments.js
• Test findBotComment returns null when no marker comment exists
• Test findBotComment returns comment when marker is present
• Test postOrUpdateComment creates new comment when none exists
• Test postOrUpdateComment updates existing comment when marker found

Task 4: Create Format Check Tests

Test each format validation function.

• Add tests/test-format-checks.js
• Test checkIssueLink with linked issue, without linked issue, bot author
• Test checkGpgSignatures with all verified, some unverified, pagination truncation
• Test checkDco with valid sign-off, missing sign-off, partial compliance
• Test checkMergeConflicts with clean, conflicted, and null-mergeable states
• Test runAllFormatChecks aggregation and failure collection

Task 5: Create Test Workflow

Add CI workflow to run revision-guard tests on changes.

• Create .github/workflows/test-revision-guard.yml
• Trigger on push and pull_request when .github/scripts/revision-guard/** changes
• Skip fork PRs with if: github.event.pull_request.head.repo.fork == false
• Run npm test from working-directory: .github/scripts/revision-guard

🤖 Prompt for AI agents

Build the complete test suite for the `revision-guard` module under
`.github/scripts/revision-guard/tests/`, following the patterns established in
the `review-sync` test suite.

**Test Infrastructure (`tests/test-utils.js`):**
- Extend patterns from review-sync's test-utils
- `createMockGithub` must track: `draftConversions`, `commentUpdates`,
`commentsCreated`
- Add GraphQL API mock (for `convertPullRequestToDraft` mutation)
- Implement `runTestSuite` and `printSummaryAndExit` helpers

**Draft Helper Tests (`tests/test-draft.js`):**
- `convertToDraft` calls correct GraphQL mutation with node ID
- `removeQueueLabels` removes all queue labels and handles 404 gracefully
- `applyStatusLabel` creates label if missing and handles 422 race condition
- Dry-run mode skips all write operations

**Comment Helper Tests (`tests/test-comments.js`):**
- `findBotComment` returns `null` when no marker comment exists
- `findBotComment` returns the comment when marker is present
- `postOrUpdateComment` creates a new comment when none exists
- `postOrUpdateComment` updates existing comment when marker is found

**Format Check Tests (`tests/test-format-checks.js`):**
- `checkIssueLink`: with linked issue, without linked issue, bot-authored PR
- `checkGpgSignatures`: all verified, some unverified, pagination truncation
- `checkDco`: valid sign-off, missing sign-off, partial compliance
- `checkMergeConflicts`: clean state, conflicted state, `null` mergeable state
- `runAllFormatChecks`: aggregation and failure collection

**CI Test Workflow (`.github/workflows/test-revision-guard.yml`):**
- Trigger on `push` and `pull_request` for changes to
`.github/scripts/revision-guard/**`
- Skip fork PRs: `if: github.event.pull_request.head.repo.fork == false`
- Run `npm test` with `working-directory: .github/scripts/revision-guard`

Research

The .github/scripts/ directory contains modular automation scripts following a consistent pattern exemplified by review-sync/. This module has its own index.js entry point, package.json (private, no external deps), helpers/ barrel with domain-specific modules, and tests/ with shared utilities. Workflows are paired: a main workflow (review-sync.yml) and a test workflow (test-review-sync.yml). The two-workflow security pattern for fork-safe write operations exists in sync-issue-labels-compute.yml → sync-issue-labels-add.yml. Existing scripts for issue link checking (bot-pr-missing-linked-issue.js) and GPG verification (bot-verified-commits.js) provide reference implementations. The bot-conventional-pr-title.js is the only script with a true post-or-update comment pattern.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Create the foundational module structure for `revision-guard` under
`.github/scripts/revision-guard/`, mirroring the architecture of the existing
`review-sync` module.

**Directory & Config Files:**
- Create `.github/scripts/revision-guard/` directory with `package.json`
(`private: true`, `main: "index.js"`, `scripts.test` chaining test files)
- Add `helpers/index.js` as a barrel export using named namespaces pattern
- Add `helpers/constants.js` defining:
  - `STATUS_LABELS` with values `needs-revision` and `failed-checks`
  - `COMMENT_MARKER` (HTML marker string for bot comment identification)
  - `RATE_LIMIT_FLOOR`
- All files must include `// SPDX-License-Identifier: Apache-2.0` header

**Draft Conversion Helper (`helpers/draft.js`):**
- Export `convertToDraft`, `removeQueueLabels`, `applyStatusLabel`
- `convertToDraft`: use GitHub GraphQL API's `convertPullRequestToDraft`
mutation, requiring PR node ID
- `removeQueueLabels`: strip all `queue:*` labels using `ALL_QUEUE_LABEL_NAMES`
imported from review-sync constants
- `applyStatusLabel`: add `status: needs-revision` or `status: failed-checks`;
create label if not exists and handle 422 race condition
- All three functions must support a `dryRun` parameter that logs actions
instead of executing writes

**Comment Utility (`helpers/comments.js`):**
- Export `postOrUpdateComment` and `findBotComment`
- `findBotComment`: paginate `issues.listComments`, returning the comment that
contains the HTML marker or `null`
- `postOrUpdateComment`: call `findBotComment` first, then call
`issues.updateComment` if found, or `issues.createComment` if not
- Accept parameters: `github`, `owner`, `repo`, `issueNumber`, `marker`,
`bodyGenerator` (function returning comment body with marker embedded)
- Include a timestamp in generated comments so edits are visible in the timeline
===============================================================================

Task: 2

Implement all format validation logic in `helpers/format-checks.js` within the
`revision-guard` module.

**`checkIssueLink(github, owner, repo, pr)`:**
- Use GraphQL `closingIssuesReferences` query (matching the pattern in
`bot-pr-missing-linked-issue.js`)
- Return `{ passed: boolean, details: string }` — passes if at least one OPEN
linked issue exists
- Skip check and return passing for bot-authored PRs

**`checkGpgSignatures(github, owner, repo, prNumber)`:**
- Paginate `pulls.listCommits`, checking `commit.verification.verified` on each
commit
- Return `{ passed: boolean, details: string, unverifiedCount: number }`
- Use same pagination limits as `bot-verified-commits.js` (MAX_PAGES=5)

**`checkDco(commits)`:**
- Accept a commits array (to avoid duplicate API calls with GPG check)
- Parse `commit.message` for `Signed-off-by:` line (case-insensitive)
- Return `{ passed: boolean, details: string, missingCount: number }`

**`checkMergeConflicts(github, owner, repo, prNumber)`:**
- Use `pulls.get` to fetch PR; check `mergeable` field and `mergeable_state`
- Return `{ passed: boolean, details: string }`
- Fail if `mergeable === false` or `mergeable_state === 'dirty'`
- Treat `mergeable === null` (still computing) as passing to avoid false
positives

**`runAllFormatChecks(github, owner, repo, pr)`:**
- Run all four checks (issue link, GPG signatures, DCO, merge conflicts) and
aggregate results
- Return `{ passed: boolean, failures: Array<{ check: string, details: string }>
}`
- Prefer running all checks and aggregating (rather than short-circuiting) for
better error messages
===============================================================================

Task: 3

Implement the real-time two-workflow security pattern and the module entry point
for handling `CHANGES_REQUESTED` events.

**Compute Workflow (`.github/workflows/revision-guard-compute.yml`):**
- Trigger: `pull_request_review` with `types: [submitted]`
- Condition: only proceed if `github.event.review.state == 'changes_requested'`
- Permissions: `contents: read` only (fork-safe)
- Write a JSON artifact containing `pr_number`, `pr_node_id`, `reviewer`,
`timestamp`
- Upload artifact named `revision-guard-payload`

**Apply Workflow (`.github/workflows/revision-guard-apply.yml`):**
- Trigger: `workflow_run` on `revision-guard-compute` with `types: [completed]`
- Condition: only proceed if `github.event.workflow_run.conclusion == 'success'`
- Permissions: `pull-requests: write`, `issues: write`, `contents: read`,
`actions: read`
- Download artifact and parse PR metadata
- Invoke the revision-guard module via `actions/github-script` to convert the PR
to draft
- Include a concurrency guard to prevent duplicate runs

**Entry Point (`.github/scripts/revision-guard/index.js`):**
- Export an async function accepting `{ github, context, core, prNumber,
prNodeId }`
- Check if PR is already a draft; skip all operations if so
- Call `convertToDraft`, `removeQueueLabels`, and
`applyStatusLabel('needs-revision')` in sequence
- Call `postOrUpdateComment` using marker `<!-- revision-guard -->` to explain
why the PR was drafted
- Respect `DRY_RUN` env var to skip all write operations
===============================================================================

Task: 4

Modify the existing `review-sync` module to integrate format checks and status
label management from `revision-guard`.

**Import revision-guard Helpers (`.github/scripts/review-sync/index.js`):**
- Add `require('../revision-guard/helpers')` to import `runAllFormatChecks`,
`convertToDraft`, `removeQueueLabels`, `applyStatusLabel`, and
`postOrUpdateComment`

**Format Check Gate in Main Loop:**
- Before calling `syncLabel` in review-sync's per-PR loop, call
`runAllFormatChecks`
- On failure: call `convertToDraft`, `removeQueueLabels`, post/update
notification comment via `postOrUpdateComment`, skip queue label assignment, and
continue to next PR
- On pass: proceed with existing queue label logic
- Track format-failure count separately in the summary output

**CI Failure Label Application (in `syncLabel` flow):**
- After `hasCIFailures` returns true, call `applyStatusLabel('failed-checks')`
- Do NOT convert to draft (CI failures may not be the contributor's fault)
- Continue with normal queue label assignment (JUNIOR queue per existing logic)
- Remove `status: failed-checks` label when CI is now passing (cleanup)

**Status Label Definitions:**
- Add `STATUS_NEEDS_REVISION` and `STATUS_FAILED_CHECKS` to revision-guard's
`helpers/constants.js`
- Update review-sync's label-ensure phase to also ensure these two labels exist
- Use red/orange colors for visibility
===============================================================================

Task: 5

Build the complete test suite for the `revision-guard` module under
`.github/scripts/revision-guard/tests/`, following the patterns established in
the `review-sync` test suite.

**Test Infrastructure (`tests/test-utils.js`):**
- Extend patterns from review-sync's test-utils
- `createMockGithub` must track: `draftConversions`, `commentUpdates`,
`commentsCreated`
- Add GraphQL API mock (for `convertPullRequestToDraft` mutation)
- Implement `runTestSuite` and `printSummaryAndExit` helpers

**Draft Helper Tests (`tests/test-draft.js`):**
- `convertToDraft` calls correct GraphQL mutation with node ID
- `removeQueueLabels` removes all queue labels and handles 404 gracefully
- `applyStatusLabel` creates label if missing and handles 422 race condition
- Dry-run mode skips all write operations

**Comment Helper Tests (`tests/test-comments.js`):**
- `findBotComment` returns `null` when no marker comment exists
- `findBotComment` returns the comment when marker is present
- `postOrUpdateComment` creates a new comment when none exists
- `postOrUpdateComment` updates existing comment when marker is found

**Format Check Tests (`tests/test-format-checks.js`):**
- `checkIssueLink`: with linked issue, without linked issue, bot-authored PR
- `checkGpgSignatures`: all verified, some unverified, pagination truncation
- `checkDco`: valid sign-off, missing sign-off, partial compliance
- `checkMergeConflicts`: clean state, conflicted state, `null` mergeable state
- `runAllFormatChecks`: aggregation and failure collection

**CI Test Workflow (`.github/workflows/test-revision-guard.yml`):**
- Trigger on `push` and `pull_request` for changes to
`.github/scripts/revision-guard/**`
- Skip fork PRs: `if: github.event.pull_request.head.repo.fork == false`
- Run `npm test` with `working-directory: .github/scripts/revision-guard`

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[darshit2308]

Thanks for the detailed feedback @exploreriii ! That makes a lot of sense, I agree that removing notifications at this stage is the right call to avoid duplication and keeping it decoupled is definitely the way to go for a potential future merge.

[exploreriii]

Hi @NssGourav
I see you have a complex beginner issue in the pipeline which has a failing check and I still need to review and study it carefully because there is a fair jump in difficulty for this one.

What do you think? Are you ready to take this one on with full responsibility ?

[NssGourav]

Hi @exploreriii , yes, I’m ready to take responsibility for it.

I understand this is a fair jump in difficulty, especially because it involves PR status handling, workflow behavior, permission boundaries, and the failing check. I’ll first study the existing workflows and the failure carefully, then keep the implementation small, incremental, and reviewable.

If the scope turns out to be too large for one PR, I can split it into smaller linked issues or PRs so each step stays safe and easier to review.

[exploreriii]

This issue is not small or incremental there are several refactors
Assigned
Please do have a careful look and and decide from there
Thanks

[NssGourav]

Thanks for assigning this.

I'll review both the current process and the failed test in detail.
As this problem has different aspects to it,I'll post about what I think we should do on our discord channel before creating the PR, and update the issue accordingly.

[darshit2308]

hi @NssGourav , best of luck for the issue, you will do good
Just one important note from my side, try to keep the file structure the same, as in the review-sync

So that, it would be easy to migrate to the central automations repo

Something like below is expected

[exploreriii]

assigning both as @NssGourav has changes requested in his PR with a fair bit to research, and it requires the completion of this PR. Please see if you can organise in discord how to coordinate