fix: link a PR to its issue on any #N reference, not just closing keywords (#652)

[johanzander]

Summary

• The backlog digest now links an open PR to its issue on any #N body reference, not just closing keywords (fixes/closes/resolves/refs #N). A no-auto-close PR that says "Part of #N", "tracking #N", or a bare #N is visible on the board instead of invisible.
• Documented cross-ref phrases (Blocked by #N, Depends on, Unblocks/Unblocking, Related to, Relationship to, See/See also, Not part of) are phrase-stripped before matching, so a PR that merely names another issue never links to it.
• The merged-PR scan uses work verbs only (fixes/closes/resolves/refs/part of/tracking/tracks): a merged intermediate PR keeps its issue In Verification (never re-dispatchable), while a merged PR that names another issue in prose does not flip it. A new merged_prs field exposes every merged work-referencing PR.
• GitHub's lazily-computed mergeable is re-queried until it leaves UNKNOWN (budget 6, covering the Consolidate PredictionSnapshotStore into the unified per-day DailyView format #490 six-pass measurement) and emitted null when still UNKNOWN.

Root cause

pr_matches_issue in scripts/backlog-digest.sh matched (fixes|closes|resolves|refs) #N only. The no-auto-close rule forbids closing verbs on intermediate PRs — they carry Part of #N / tracking #N / a bare #N — so those PRs resolved to no issue and the issue's column fell through to the live worktree: issue #409 reported In Progress while its approved PR #490 sat open. The merged-PR scan had the same closing-keyword-only blind spot in reverse: narrowing it (during this fix's first pass) flipped #643/#542/#571/#592/#666 from In Verification to Backlog / Ready for Dev on the live board, because their merged PRs (#675/#591/#584/#619/#672) used Refs #N-style references.

Fix

• pr_matches_issue now tests (^|[^0-9])#N\b on a linkage_body that first strips the documented cross-ref phrases, so Part of #N / tracking #N / Refs #N / bare #N all link while cross-refs never do. Stripping the phrase (not the line) keeps combined references like - Blocked by #100 -- part of #409 working.
• Merged scan: work verbs only — deliberately not bare #N, so prose ("until Quarterly schedule-update tick: prevent misfire under long hardware-write retries #456 and Quarterly schedule-update tick: backfill/retry sweep for a missed period #457 are also resolved") cannot flip an unrelated issue to In Verification. merged_pr_for gates the column; the new merged_prs field lists every match, sorted.
• mergeable: bounded re-query (6 passes) around GitHub's lazy computation; prs_for emits null when it never settles.

Test plan

• ./scripts/quality-check.sh passes locally (Errors: 0)
• .venv/bin/pytest -m slow passes locally (554 passed, 8 skipped)
• Step 8 — live digest against the real board: corrected digest runs clean (exit 0, empty stderr), restores Runtime error: Check grid charge state #643/Battery Discharge Power sensor missing from Solax Modbus #542/bug: discharge gate reads a raw snapped V grid difference while the policy uses _interpolate_value — shadow price 42% above the optimizer's own objective #571/VPP idle mode #592/Negative export compensation #666 to In Verification exactly as origin/main did (with the new merged_prs data), preserves baseline open-PR linkage (backlog-digest matches sessions by cwd, so a dispatched implement-issue session is invisible — rhythm re-proposes resume every tick #647→677, Accept an external consumption forecast as a time-series entity #428→437, Add external_solar_mode battery setting for AC-coupled PV systems #162→167), leaks zero UNKNOWN/null mergeables, and keeps the same three pr_no_issue orphans (PRs fix: stop the fleet prune from destroying the worktrees it cannot remove #653/feat: enforce review-loop legality and derive fleet state from GitHub #638/fix: gate grid_first on export materiality instead of intent classification #354 — all reference only merged/closed numbers).
• Docs check: docs/agents/bess-knowledge.md and docs/SOFTWARE_DESIGN.md each contain 0 matches for "backlog" — neither describes the digest mechanism, so no doc update is owed.

Evidence the test discriminates

The RED tests were written first and observed failing on the pre-fix script; the mutations below confirm they still discriminate on the final tree.

• Reverted: merged-PR scan narrowed to closing verbs only (fixes|closes|resolves|refs)
  • Result: test_a_merged_intermediate_pr_keeps_the_issue_in_verification FAILED (a merged "Part of fix: serve sub-lattice net load from the battery instead of idling (#466) #517" PR no longer kept fix: serve sub-lattice net load from the battery instead of idling (#466) #517 In Verification); 63 tests total
• Reverted: merged-PR scan widened to bare #N
  • Result: test_a_merged_cross_ref_does_not_move_an_issue_to_in_verification FAILED ("Related to Quarterly schedule-update tick can be silently skipped when hardware retries run long, permanently dropping a period's actuals #403… until Quarterly schedule-update tick: prevent misfire under long hardware-write retries #456/Quarterly schedule-update tick: backfill/retry sweep for a missed period #457" flipped Quarterly schedule-update tick can be silently skipped when hardware retries run long, permanently dropping a period's actuals #403 to In Verification)
• Reverted: the linkage_body phrase-strip neutralized
  • Result: test_a_blocked_by_reference_does_not_link_a_pr_to_its_issue FAILED (and the 8-case test_a_non_work_reference… parametrization)
• Reverted (individually) the relationship to, see, not part of, and unblocking strip alternatives
  • Result: the matching test_a_non_work_reference_does_not_link_a_pr_to_its_issue[<phrase>] case FAILED each time
• Restored: tree clean, all 68 digest tests pass

Outcome-level coverage

• none, because this is a bash tooling fix — the outcomes are board columns (In Review / In Verification / Backlog), pinned by the test harness's _gh_shim-driven digest runs above; there is no optimizer/execution model involved.

Refs #652

[bess-agent]

@claude-bot review

[bess-manager-claude-bot]

Verdict: APPROVE

Matches linked issue's root cause (#652): Yes, exactly. #652 diagnosed two independent defects and prescribed both fixes verbatim:

1. pr_matches_issue matched only (fixes|closes|resolves) #N, which the no-auto-close convention forbids on intermediate PRs — so a "Part of #409" PR resolved to no issue and #409's column fell through to the live-worktree branch, reporting In Progress for an approved, mergeable PR.
2. mergeable: UNKNOWN (GitHub's lazily-computed first-query value) was passed through as if final.

scripts/backlog-digest.sh's new linkage_body/pr_matches_issue (any #N, with documented cross-ref phrases like Blocked by/Related to/Unblocks stripped first) and the bounded MERGE_RETRY_LIMIT/MERGE_RETRY_SLEEP re-query loop implement exactly what #652's "Proposed fix" section asked for. The widened merged-PR regex (fixes|closes|resolves|refs|part of|tracking|tracks, still deliberately excluding bare #N) fixes a real regression the PR's own root-cause section documents was introduced mid-fix (narrowing it flipped #643/#542/#571/#592/#666 off In Verification on the live board) — same underlying defect class as #652, not unrelated scope.

Would the tests catch a regression? Yes, verified independently, not just taken on the PR's word. I checked out the branch, ran the full test_backlog_digest.py suite (68 passed), then mutated pr_matches_issue back to the pre-fix closing-keyword-only regex and re-ran: test_a_bare_number_reference_links_a_pr_to_its_issue, test_a_blocked_by_side_reference_still_links_the_prs_own_issue, and one other failed as expected (3 failed / 65 passed), then restored to green. The tests assert board-visible outcomes (item[\"column\"], item[\"prs\"], orphan lists) rather than jq internals, consistent with docs/agents/testing.md. I also hand-traced the linkage_body regex against every parametrized non-work-reference case (Related to, Unrelated to, Unblocks/Unblocking, See/See also, Not part of) and the boundary regex (#2409 vs issue 409, #4095 vs issue 409) — all correct, including the accidental-but-correct substring behavior on Unrelated to #900.

Minimal / no scope creep: Yes. Three files touched (CHANGELOG.md, the script, its test file), all load-bearing for #652. The new merged_prs (plural) field is the one piece not explicitly asked for in #652, but it falls directly out of widening the merged-PR regex to work-verb spellings (now multiple merged PRs can legitimately match one issue) and is cheap, tested, additive visibility data — not a separate feature.

Rule violations: None found. No Python/API-layer/architecture rules apply (pure bash/jq + test file). No secrets, no injection vectors, no new classes. mergeable's null-on-still-UNKNOWN change doesn't affect backlog-rhythm.sh, which queries mergeable independently via its own gh pr view call and never reads the digest's prs[].mergeable field — confirmed by grep.

Minor observation (non-blocking): The PR description doesn't include an explicit "local fix / structural fix / escalated" scope-assessment line per rules.md Debugging Protocol step 9. I judged this a local fix — confined to one script's existing linkage/merge-scan responsibilities, no new cross-module ownership — so I'm not treating the missing statement as a blocker, but flagging it since the checklist calls for it explicitly.

CI: all checks green (Fast tests, E2E, Docker build, Frontend, Code quality, Merge gate; Algorithm tests skipped as expected for this diff).