enhance(backlog-triage): snapshot v2 schema for closing PRs, comments, and closed-issue scan

[sungjunlee]

Follow-up to #59 epic. Surfaced during Batch 2 reviews (#62, #63) and re-triaged on 2026-05-31.

Why now

The current backlog-triage snapshot cannot support several high-signal checks:

• PR linkage: merged PR -> still-open issue requires per-issue closing PR references.
• Comment mentions: issue-to-issue edges in comments require optional issue comments.
• Duplicate of closed issue: stale/obsolete detection needs bounded closed-issue context.

The MVP scanners cover body-scan, keyword, and label signals. Snapshot v2 should add the missing data without breaking the default explicit-sync model.

Scope

Extend skills/backlog-triage/scripts/triage-collect.js and snapshot consumers.

1. Default snapshot v2 schema

   • Add a snapshot schema/version marker.
   • Add per-issue closing_prs: [{number, state, mergedAt, url}]; empty array when no closing PR is linked.
   • Preserve the default one-fetch mental model; if GraphQL pagination is required, document exactly how it is invoked and why it is still one collection step.

2. Optional --with-comments enrichment

   • Default off.
   • Adds comments: [{author, body, createdAt}] to each issue.
   • May perform bounded per-issue calls; warn with expected API call count and concurrency cap.

3. Optional --with-closed-issues enrichment

   • Default off.
   • Adds top-level closed_issues: [{number, title, body, closedAt}].
   • Bound by config window, defaulting to recently closed issues only.

4. Downstream gating

   • triage-relate PR-linkage and comment-mention scans should require the relevant snapshot fields/features.
   • triage-stale duplicate-of-closed scans should require closed_issues.
   • Missing optional fields must degrade clearly, not fail with undefined-field behavior.

Explicit out of scope

• ML-based duplicate detection.
• Cross-repo issue resolution.
• Timeline events beyond closing-PR references.
• Changing sync-pull.js behavior unless the migration is trivial and behavior-preserving.

Acceptance Criteria

• Snapshot contains an explicit schema/version marker.
• Per-issue closing_prs field is present on every default snapshot issue.
• Default collection path is documented as one explicit collection step.
• --with-comments is opt-in, documented with API-call cost, and concurrency-bounded.
• --with-closed-issues is opt-in and bounded by config.
• Existing schema tests are updated; new tests cover closing_prs via stubbed GraphQL/API response.
• Downstream relate/stale scanners gate optional signals on snapshot features instead of assuming fields exist.
• sync-pull.js behavior remains unchanged unless explicitly justified in the PR.

[coderabbitai]

🔗 Related PRs

#74 - feat(backlog-triage): triage report renderer (#64) [merged]
#80 - fix(backlog-triage): exclude progress issues from triage snapshots [merged]
#82 - feat(backlog-triage): add snapshot v2 collector [merged]
#155 - Align spec-system harness signals [merged]
#174 - feat(backlog-triage): add spec-aware Decision Review [closed]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[sungjunlee]

2026-05-31 triage update: keep this issue open, but tighten the contract before implementation. The default snapshot path should preserve the one-fetch mental model and add schema-versioned per-issue closing_prs. Optional enrichments must be explicit: --with-comments may perform bounded per-issue calls and must warn about call count; --with-closed-issues may perform a second bounded query and must record its window/config in the snapshot. Downstream relate/stale scanners should gate PR-linkage and duplicate-of-closed logic on snapshot schema/features instead of assuming fields exist. sync-pull remains out of scope unless the migration is trivial and behavior-preserving.

[sungjunlee]

Audit update for snapshot v2 scope:

• Collector-side snapshot v2 was largely completed by PR feat(backlog-triage): add snapshot v2 collector #82: default closing_prs, opt-in --with-comments, opt-in --with-closed-issues, bounded comments/closed issue collection, and collector tests are already present.
• This follow-up branch adds the missing explicit schema_version: 2 marker and updates docs/report placeholders so they no longer claim the collector fields are absent.
• Remaining analyzer work has been split out:
  • enhance(backlog-triage): emit comment and closing-PR relationship signals #189 for comment and closing-PR relationship signals in triage-relate.js
  • enhance(backlog-triage): add stale signals for merged PRs and closed duplicates #190 for merged-PR and duplicate-of-closed stale signals in triage-stale.js

Plan: close #73 with the schema/audit cleanup PR, then handle analyzer behavior in #189/#190 separately.