Context
The PR resource family is a separate one-PR leaf because reviews, inline review comments, dismissals, and two-pass verification have different source contracts from issue timelines. It reuses the normalized runner and trust foundation established by the GitHub issue leaf.
This is one fully closeable PR leaf under Epic #15145. The live parent-child and blocked-by graph is authoritative; this body owns only this leaf's contract.
The Problem
Ordinary PR sync bounds reviews and omits inline comments/timeline events; the resolved-PR Bird View exhausts surviving conversations but does not preserve edit/delete/dismissal occurrences or cover active PRs as a durable event source.
The Architectural Reality
The work belongs in ai/services/github-workflow/, reusing PullRequestHistoryService.mjs, PullRequestSyncer.mjs, and pullRequestQueries.mjs. The existing two-pass mutation detector and citation/coverage semantics are gold standards, not a replacement for durable occurrence reconciliation.
The Agent OS structure map was run on 2026-07-14. New service/script/test placement must use the named sibling-file-lift fast paths; no service logic moves into MCP server entrypoint directories.
The Fix
Exhaust active/closed/merged PR roots, issue comments, reviews, inline review comments, and provider timeline events; normalize create/edit/close/reopen/merge/review/dismiss/delete evidence into neutral batches with independent cursors, verification rereads, and honest unsupported-family gaps.
Contract Ledger Matrix
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback / Edge Case |
Docs |
Evidence |
| PR census/conversation |
OQ2 PR matrix + PR #15131 |
All-state roots and independently exhausted child families |
Mutation/caps degrade coverage, never truncate silently |
Service JSDoc |
Two-pass and pagination tests |
| Review occurrences |
Provider review/timeline contracts |
Stable review/comment/dismiss/edit/delete identities where available |
Unsupported delete history stays a named gap |
Adapter docs |
Dismiss/delete/revision fixtures |
| Neutral output |
Issue-leaf runner + admission v1 |
Deterministic metadata-only batches |
No receipt means no checkpoint advance |
Runner docs |
Canonical parity tests |
Decision Record impact
Depends on ADR 0036, neutral admission, and the GitHub issue reconciliation foundation.
Decision Record
Required: ADR 0036. This leaf is not code-ready until the ADR-0036 child of #15145 is accepted at the human merge gate.
Discussion Criteria Mapping
| Upstream graduated criterion |
This leaf's executable contract |
| OQ2 |
Covers active/resolved PR roots, issue comments, reviews, inline comments, lifecycle, dismissals, and gaps. |
| OQ3 |
Preserves provider entity, occurrence/revision, batch, and admitted-order separation. |
| OQ8 |
Inherits source-relative trust and metadata-only automatic output. |
Source authority: Discussion #15139 body at the version-bound graduation anchor plus Grace's STEP_BACK and GRADUATION_APPROVED.
Operator Scope Clarification — 2026-07-14
The community substrate is not a mirror of every GitHub repository notification. It separates:
- source occurrences needed to reconstruct supported issue, pull-request/review, and Discussion conversation state; and
- attention-eligible community items: externally authored, response-bearing occurrences that may need maintainer attention.
Stars/un-stars, forks, watches, and equivalent popularity telemetry are outside the community-event source families and cannot enter Bird View, counts, wake, or Task claim. Internal/rostered actions may update or resolve the state of an existing external item without minting new community attention. First-time versus trusted-repeat external status affects trust/projection, not basic eligibility. Bot eligibility must be an explicit ADR disposition and cannot be inferred from provider actor kind or trust tier.
Attention eligibility remains zero-authority: it does not assign work, enter LifecycleFrontier, or create a Task. Only the explicit canonical claim transition owns that promotion.
Acceptance Criteria
Out of Scope
Issue-family runner redesign, Discussion reconciliation, webhook authority, Bird View UI, or source-owned outbox.
Avoided Traps
Do not treat PR #15131 as a repo-global ledger, collapse repeated transitions to snapshot state, or couple all resource families into one giant PR.
Related
Origin Session ID: 837ad74b-c2d2-413d-9aab-b7165a93a82a
Handoff Retrieval Hints
GitHub PR review inline comment dismissal exhaustive reconciliationPullRequestHistoryService durable occurrence gap
Creation Freshness
Creation duplicate sweep: immediately before filing at 2026-07-14T05:30:37.221Z, checked the latest 20 open issues and last 30 all-state A2A messages. The independent broader audit at 2026-07-14T05:13:00Z covered open and closed issues, pull requests, A2A, ADRs, and code; no equivalent owner or foreign claim existed.
Context
The PR resource family is a separate one-PR leaf because reviews, inline review comments, dismissals, and two-pass verification have different source contracts from issue timelines. It reuses the normalized runner and trust foundation established by the GitHub issue leaf.
This is one fully closeable PR leaf under Epic #15145. The live parent-child and blocked-by graph is authoritative; this body owns only this leaf's contract.
The Problem
Ordinary PR sync bounds reviews and omits inline comments/timeline events; the resolved-PR Bird View exhausts surviving conversations but does not preserve edit/delete/dismissal occurrences or cover active PRs as a durable event source.
The Architectural Reality
The work belongs in
ai/services/github-workflow/, reusingPullRequestHistoryService.mjs,PullRequestSyncer.mjs, andpullRequestQueries.mjs. The existing two-pass mutation detector and citation/coverage semantics are gold standards, not a replacement for durable occurrence reconciliation.The Agent OS structure map was run on 2026-07-14. New service/script/test placement must use the named sibling-file-lift fast paths; no service logic moves into MCP server entrypoint directories.
The Fix
Exhaust active/closed/merged PR roots, issue comments, reviews, inline review comments, and provider timeline events; normalize create/edit/close/reopen/merge/review/dismiss/delete evidence into neutral batches with independent cursors, verification rereads, and honest unsupported-family gaps.
Contract Ledger Matrix
Decision Record impact
Depends on ADR 0036, neutral admission, and the GitHub issue reconciliation foundation.
Decision Record
Required: ADR 0036. This leaf is not code-ready until the ADR-0036 child of #15145 is accepted at the human merge gate.
Discussion Criteria Mapping
Source authority: Discussion #15139 body at the version-bound graduation anchor plus Grace's STEP_BACK and GRADUATION_APPROVED.
Operator Scope Clarification — 2026-07-14
The community substrate is not a mirror of every GitHub repository notification. It separates:
Stars/un-stars, forks, watches, and equivalent popularity telemetry are outside the community-event source families and cannot enter Bird View, counts, wake, or Task claim. Internal/rostered actions may update or resolve the state of an existing external item without minting new community attention. First-time versus trusted-repeat external status affects trust/projection, not basic eligibility. Bot eligibility must be an explicit ADR disposition and cannot be inferred from provider actor kind or trust tier.
Attention eligibility remains zero-authority: it does not assign work, enter LifecycleFrontier, or create a Task. Only the explicit canonical claim transition owns that promotion.
Acceptance Criteria
AC1 — OPEN/CLOSED/MERGED PR roots are exhausted and verified.
AC2 — Issue comments, reviews, and inline review comments use independent progress-checked pagination.
AC3 — Close/reopen/merge/review/dismiss/edit/delete evidence is normalized only when provider-backed.
AC4 — Existing resolved-PR two-pass verification and honest degradation remain intact.
AC5 — Active high-volume PRs cannot silently truncate at current review/comment bounds.
AC6 — Actor kind/trust separation and metadata-only output match the issue foundation.
AC7 — Checkpoint advances only after durable admission receipt.
AC8 — Fixtures cover mutation during paging, duplicate ids, dismissal, deletion gaps, and unsupported history.
AC9 — PR/review output inherits the shared eligibility contract: external response-bearing PR/review occurrences are eligible, while internal/rostered state changes remain context and popularity telemetry remains absent.
Out of Scope
Issue-family runner redesign, Discussion reconciliation, webhook authority, Bird View UI, or source-owned outbox.
Avoided Traps
Do not treat PR #15131 as a repo-global ledger, collapse repeated transitions to snapshot state, or couple all resource families into one giant PR.
Related
Origin Session ID: 837ad74b-c2d2-413d-9aab-b7165a93a82a
Handoff Retrieval Hints
GitHub PR review inline comment dismissal exhaustive reconciliationPullRequestHistoryService durable occurrence gapCreation Freshness
Creation duplicate sweep: immediately before filing at 2026-07-14T05:30:37.221Z, checked the latest 20 open issues and last 30 all-state A2A messages. The independent broader audit at 2026-07-14T05:13:00Z covered open and closed issues, pull requests, A2A, ADRs, and code; no equivalent owner or foreign claim existed.