feat: implement issue #611 — [Phase 1] Define the review artifact contract + rubric registry (pr_diff sole type)

[don-petry]

Closes #611

Implemented by dev-lead agent. Please review.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

Warning

Review limit reached

@don-petry, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 3 minutes and 53 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

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.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4c49f7c2-0a68-49fb-a589-7cfd980e6444

📥 Commits

Reviewing files that changed from the base of the PR and between 82669de and 87a16f6.

⛔ Files ignored due to path filters (1)

• scripts/lib/review-registry.tsv is excluded by !**/*.tsv

📒 Files selected for processing (5)

• .github/workflows/lint.yml
• AGENTS.md
• scripts/lib/README.md
• scripts/lib/review-registry.sh
• tests/test_review_registry.bats

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev-lead/issue-611-20260612-0136

---

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 and usage tips.}

[don-petry]

Dev-Lead — review-changes (no-changes)

No changes were needed for this PR.

[don-petry]

Dev-Lead — fix-bot-comment (no-changes)

Agent reasoning

Issues addressed: 0
Files changed: None
Skipped (informational): 1
  - Quality Gate Passed — no actionable issues reported
```
The PR is in a healthy state with no actionable issues. The SonarCloud comment is an informational status report indicating the PR passes all quality gates. No changes needed.

[gemini-code-assist]

Code Review

This pull request introduces a new review artifact contract and rubric registry system, including documentation, a tab-separated manifest (review-registry.tsv), a Bash lookup helper (review-registry.sh), and a BATS unit test suite. The feedback focuses on improving the robustness of the lookup helper by adding defensive checks to verify the existence of the manifest file before running awk commands, which prevents noisy errors, unexpected script exits under set -e, and misleading error messages. Additionally, it is recommended to validate that resolved lookup values are non-empty to ensure proper error codes are returned.

[don-petry]

Dev-Lead — review-changes (applied)

Changes committed and pushed.

[don-petry]

Auto-rebase failed — merge conflict — this branch has conflicts with main that must be resolved.

Claude will attempt to resolve this automatically. If it cannot, a follow-up comment will explain what needs manual attention.

To resolve manually instead:

git fetch origin
git merge origin/main
# resolve conflicts, then:
git add .
git commit
git push

[don-petry]

Dev-Lead — rebase (no-changes)

Agent reasoning

PR: #622
Rebased onto: main
Conflicts resolved: 14 files
- README.md: kept main's comprehensive version (PR "Initial commit" had a placeholder)
- scripts/list-prs.sh: auto-resolved add/add (kept PR version via -X theirs)
- scripts/review-one-pr.sh: auto-resolved add/add (kept PR version via -X theirs)
- scripts/engine.sh: auto-resolved add/add + modify/delete deprecation commit
- scripts/post-pr-review.sh: auto-resolved add/add + modify/delete deprecation commit
- scripts/pr_review_health.sh: auto-resolved add/add + modify/delete deprecation commit
- scripts/request-codeowners-review.sh: auto-resolved add/add + modify/delete deprecation commit
- scripts/review-batch.sh: auto-resolved add/add + modify/delete deprecation commit
Push: success
```
All conflicts were "add/add" or "modify/delete" patterns from the PR branch's full history being replayed onto main's single squashed commit. The `-X theirs` strategy resolved all content conflicts automatically, and the helper script staged any remaining auto-resolved files. No conflict markers were present in any file at resolution time.

[don-petry]

Dev-Lead — fix-bot-comment (no-changes)

Agent reasoning

**Bot:** gemini-code-assist[bot]
**Issues addressed:** 3
- **review_registry_version() defensive check**: Added file existence validation before awk to prevent noisy errors and provide clearer error messages. [replied + thread resolved]
- **review_registry_types() defensive check**: Added file existence validation to prevent unexpected script exits under set -e when manifest is missing. [replied + thread resolved]  
- **review_registry_lookup() defensive checks and value validation**: Added file existence check before awk command and validation that resolved values are non-empty, returning proper exit code 2 when a field is empty. Added comprehensive BATS test coverage for all defensive scenarios. [replied + thread resolved]
**Files changed:** 
- `scripts/lib/review-registry.sh`
- `tests/test_review_registry.bats`
**Quality Gates:** SonarCloud Quality Gate passed with 0 new issues (not actionable).
All recommended code improvements were already implemented in the most recent commit and have been confirmed with specific replies to each review thread. All open threads from the bot are now resolved.

[don-petry]

Auto-rebase failed — merge conflict — this branch has conflicts with main that must be resolved.

Claude will attempt to resolve this automatically. If it cannot, a follow-up comment will explain what needs manual attention.

To resolve manually instead:

git fetch origin
git merge origin/main
# resolve conflicts, then:
git add .
git commit
git push

[don-petry]

Dev-Lead — rebase (no-changes)

Agent reasoning

PR: #622
Rebased onto: main
Conflicts resolved: 2 files
- .github/workflows/lint.yml: kept both test_oversized_pr.bats (from main) and test_review_registry.bats (from PR) in the bats test list
- AGENTS.md: kept both "Oversized PRs" section (from main) and "Review artifact contract & rubric registry" section (from PR)
Push: success
```
**Notes on the approach:** The PR branch had 737 commits with a divergent history — `git rebase` tried to replay all of them and hit a conflict at the very first "Initial commit". Instead, I identified the 2 unique PR commits (`91e094d` and `2ecf804`) and used `cherry-pick` to place them on top of `origin/main`, which also avoided git's false "redundant commit" detection that was dropping `91e094d`.

[don-petry]

Dev-Lead — fix-bot-comment (no-changes)

Agent reasoning

Issues addressed: 0
- No actionable issues identified — Quality Gate passed with 0 issues
- Code review feedback already implemented in latest commit
- All quality checks passing
Files changed: None (working tree clean)
Skipped (informational): 0
```
**No changes needed.** The PR is in excellent condition with all quality gates passing and prior feedback already implemented.

[don-petry]

Dev-Lead — review-changes (no-changes)

No changes were needed for this PR.

[don-petry]

Dev-Lead — review-changes (no-changes)

No changes were needed for this PR.

[don-petry]

Dev-Lead — fix-bot-comment (no-changes)

Agent reasoning

Issues addressed: 0
- No new code quality issues found (quality gate passed)
- All suggested defensive checks already implemented
- All review threads already resolved (gemini-code-assist feedback addressed)
Files unchanged: No code changes needed
Skipped (informational): 0
```
The PR is ready. All code quality analysis passed, defensive checks are in place, and the review feedback has been incorporated. The cancelled dev-lead workflow checks appear to be unrelated to the code changes and are likely workflow execution details.

[don-petry]

Dev-Lead — review-changes (no-changes)

No changes were needed for this PR.

[don-petry]

Auto-rebase failed — merge conflict — this branch has conflicts with main that must be resolved.

dev-lead will attempt to resolve this automatically. If it cannot, a follow-up comment will explain what needs manual attention.

To resolve manually instead:

git fetch origin
git merge origin/main
# resolve conflicts, then:
git add .
git commit
git push

[don-petry]

Dev-Lead — review-changes (no-changes)

No changes were needed for this PR.

[don-petry]

Auto-rebase failed — merge conflict — this branch has conflicts with main that must be resolved.

dev-lead will attempt to resolve this automatically. If it cannot, a follow-up comment will explain what needs manual attention.

To resolve manually instead:

git fetch origin
git merge origin/main
# resolve conflicts, then:
git add .
git commit
git push

[don-petry]

Dev-Lead — rebase (no-changes)

Agent reasoning

PR: #622
Rebased onto: main (82669de)
Conflicts resolved: 1 file
- .github/workflows/lint.yml: Both sides added a new bats test entry at the same location; kept both (test_validate_cases.bats from main, test_review_registry.bats from PR)
Push: success
```

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[don-petry]

Dev-Lead — fix-bot-comment (no-changes)

Agent reasoning

Issues addressed: 0
- No actionable issues found in SonarCloud comment (passing quality gate)
- No failed CI checks to address
- No CHANGES_REQUESTED reviews
- Recommended improvements from Gemini are already implemented in code
Files changed: None required
Skipped (informational): 0
```
**Status:** ✅ This PR is ready — all checks passing, no actionable bot issues, and code already implements the suggested robustness improvements.