fix: restore Guardrails before PR Sync

[v-Kaefer]

Linked Issue

• Closes fix: align PR governance order with reference implementation #52

Milestone

• Repository governance

Summary

• Restore the proven governance order from the Take Your Pills reference: Autofill -> Guardrails -> PR Sync.
• Move Autofill into the trusted PR metadata/Guardrails workflow before validation.
• Trigger normal PR Sync only from a successful Guardrails workflow_run, so Sync refetches the live pull request instead of consuming stale pull_request_target body state.
• Preserve direct lifecycle Sync for ready_for_review, converted_to_draft, and closed.
• Keep Q.A -> main live QA gated after successful Guardrails.
• Add English and PT-BR architecture documentation with Mermaid diagrams and token/security boundaries.
• Replace workflow-contract tests that encoded the previous inverted architecture and add explicit live-PR refetch coverage.

How to test

• Run the repository quality/unit test suite.
• Verify workflow contracts require Autofill before live metadata validation in .github/workflows/pr-metadata.yml.
• Verify .github/workflows/pr-sync.yml waits for successful PR metadata validation via workflow_run for normal implementation updates.
• Verify Sync workflow_run context fetches /pulls/{number} before parsing the linked task.
• After promotion to main, open a fresh implementation PR with recoverable branch metadata and confirm it converges without manual edit/rerun.

Evidence

• Architecture compared against the working Take Your Pills Guardrails/Hygiene flow.
• Stale-state regression represented in unit/workflow contract tests.
• Mermaid architecture documented in English and PT-BR.

Known risks

• This PR changes privileged workflow ordering, so the definitive live validation must use a fresh PR event after the workflow reaches the branch that governs the target PR.
• The current PR itself is still initially governed by the pre-fix workflow present on its base branch.

DoD checklist

• Scope implemented conforme definido
• Opção de teste selecionada
• Nenhuma quebra crítica conhecida foi introduzida

[github-actions]

PR Sync

• Linked task: fix: align PR governance order with reference implementation #52
• PR lifecycle target: Done
• Project v2: skipped because PROJECT_SETUP_PROJECT_NUMBER is not configured.
• Parent/sub-issue: no parent reference found.
• PR: fix: restore Guardrails before PR Sync #53

[coderabbitai]

Warning

Review limit reached

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

Next review available in: 59 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: e24d1a2b-9413-416d-9ac0-e3e78c1fc285

📥 Commits

Reviewing files that changed from the base of the PR and between a4d7f88 and acd12c6.

📒 Files selected for processing (7)

• .github/workflows/pr-metadata.yml
• .github/workflows/pr-sync.yml
• docs/repo/pr-governance-architecture.md
• docs/repo/pr-governance-architecture.pt-BR.md
• tests/test_pr_sync.py
• tests/test_pr_sync_autofill.py
• tests/test_qa_workflows.py

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/issue-52-pr-governance-order

---

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.}

[v-Kaefer]

Validation result

The hosted Repository quality workflow now passes on the final branch head (acd12c6).

The regression suite covers the architectural contract introduced by this PR:

• Guardrails receives normal PR events directly.
• Autofill runs before metadata validation.
• Metadata validation reads the live PR through the GitHub API.
• Normal PR Sync waits for successful Guardrails via workflow_run.
• workflow_run PR Sync refetches /pulls/{number} before resolving the linked task.
• Direct lifecycle Sync remains limited to ready_for_review, converted_to_draft, and closed.
• Q.A -> main Live QA remains gated on successful Guardrails.
• Promotion PR exemptions remain covered.

The initial failed CI attempt exposed one QA contract test that still asserted the previous workflow_run.pull_requests[0] metadata shape; that test was updated to the new direct Guardrails event and the subsequent hosted run passed.