docs(gap-baseline): document the opencode-review required-check race

[seonghobae]

Summary

Documents a structural, org-wide gap found while driving several other PRs to green this session: the opencode-review required check (job opencode-review-target in opencode-review.yml) checks synchronously, within seconds of push, whether an opencode-agent review already exists for the current head — but the real review is posted by a separate, asynchronous path (pr-review-merge-scheduler.yml's TRIGGER_REVIEWS → repository_dispatch: opencode-review → opencode-review-dispatch.yml) that can take far longer. Nothing re-runs the check once the real review lands, since opencode-review.yml's only trigger is pull_request_target, unlike noema-review.yml and pr-review-merge-scheduler.yml, which both also listen for workflow_run completion.

Confirmed live on 5 independent PRs across .github and contextual-orchestrator (contextual-orchestrator#953, .github#1437/#1478/#1479/#1482), all failing identically within 1–10 seconds of push, and confirmed not a flake — an immediate re-run reproduces the same race.

Documented rather than fixed this pass: this is required-workflow, pull_request_target trust-boundary code shared by every sibling repo, and multiple sessions were independently pushing to the same review-pipeline files while this was being diagnosed. Landing a fix needs deliberate, single-owned attention in its own PR — two candidate directions are recorded in the entry for whoever picks this up.

Test plan

• PYTHONPATH=. coverage run -m pytest tests -q — 2105 passed, 1 skipped, 21 subtests
• coverage report --show-missing — 100%
• interrogate — 100%
• tests/test_product_technical_gap_baseline.py — passes unchanged
• Docs-only change

---

Generated by Claude Code

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

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

[seonghobae]

The opencode-review check failed with exactly the race this PR documents (see the new entry) — a fittingly direct confirmation. Same systemic cause as #953, #1437, #1478, #1479, #1482, not this PR's diff. Re-queued the failed job once; will keep this PR watched until it resolves.

---

Generated by Claude Code

[seonghobae]

Closing: main's 4a5dfd82 (#1497, "require substantive agent verdicts") already fixed the race this PR documents — opencode-review-target now actively dispatches its own merge-scheduler repository_dispatch event and polls synchronously for up to 90 minutes (timeout-minutes: 100) for the review to land, rather than checking once synchronously with nothing to re-trigger it. That's a different mechanism than either candidate direction this entry recorded (workflow_run re-entry was attempted in #1494, now closed as superseded once I found this).

The five PRs this entry cites as evidence (contextual-orchestrator#953, .github#1437/#1478/#1479/#1482) should self-resolve on their next natural re-evaluation now that main carries the fix, if they haven't already. There's a new, different open question this surfaced while investigating — #1500's opencode-review failed even with the active-dispatch-and-poll mechanism in place, meaning the actively dispatched review didn't land within the full 90-minute window — but that's a distinct problem from the one this entry describes, not a reason to keep this draft open.

---

Generated by Claude Code