hypatia: detect stale issue references in workflow/source comments (from #333 cohort, pattern 7)

[hyperpolymath]

Detector spec (from hypatia#333 Pattern 7)

Pattern 7 — Stale issue references in workflow / source comments

Severity: low (documentation rot)

Detection (Hypatia.Rules.HonestCompletion):

• Scan workflow comments + source comments for #N issue/PR references with phrasing patterns like:
  • until #N, pending #N, gated on #N, awaits #N, blocked by #N, remove when #N
• For each, query the GitHub API: is #N closed/merged?
• If yes, flag the comment as stale.

Worked example (this session):

• The vscode-smoke job comment said "Remove the continue-on-error: true line when chore(deps): bump bb8 from 0.8.6 to 0.9.1 #104 publishes the adapter to npm." — chore(deps): bump bb8 from 0.8.6 to 0.9.1 #104 still open, but if it had closed without the comment being updated, this would be a stale reference.

Remediation guidance to emit:

The referenced issue (#N) is closed/merged. Update or delete this comment so the next reader doesn't waste time looking it up.

Implementation pointers

• Detection algorithm: Scan workflow + source comments for #N refs with phrasing like until #N/pending #N/gated on #N/awaits #N/blocked by #N/remove when #N; query GitHub API; flag if closed/merged.
• Real-world example: affinescript/.github/workflows/ci.yml vscode-smoke comment "Remove the continue-on-error: true line when chore(deps): bump bb8 from 0.8.6 to 0.9.1 #104 publishes the adapter to npm." (chore(deps): bump bb8 from 0.8.6 to 0.9.1 #104 still open at the time, but illustrative).
• Landed fix (reference): (no landed fix referenced)
• Rule statement: The referenced issue (#N) is closed/merged. Update or delete this comment so the next reader doesn't waste time looking it up.

Acceptance

• Rule encoded in hypatia (file path follows existing rule naming convention — lib/rules/<name>.ex if Elixir, or matching the repo's rule DSL)
• Test fixture exercising the positive case + at least one negative case
• Smoke test passes against the cited landed-fix repo

Source cohort: hypatia#333.

[hyperpolymath]

cicd triage 2026-05-30 — scoped plan + park

PR #403 ships the first batch of 4 rules from this cohort (#336, #337, #338, #390). This issue is in the next batch; landing it requires more substantial work than the first four:

Detection: scan workflow + source comments for #N refs with phrasing patterns (until #N / pending #N / gated on #N / awaits #N / blocked by #N / remove when #N); gh API closed-issue check. Add to lib/rules/honest_completion.ex (HC### naming) per issue body.

The issue body is the implementation spec (detection algorithm + worked example + remediation guidance — well-formed). Next-batch PR will pick this up. Leaving open with cicd label.

[hyperpolymath]

Detector landed in PR #411 (merged, d460d6c): Hypatia.Rules.HonestCompletion.check_stale_issue_refs/2 — flags comments referencing a closed/merged issue via stale-marker phrasing (until/pending/gated on/awaits/blocked by/remove when #N).

• Rule encoded
• Test fixtures (positive + open-issue negative) — test/rules/group_b_detectors_test.exs
• Smoke test (needs live issue state)

Remaining (keeping this open): takes closed_issues as a parameter today; wiring the live issue-state lookup into the scan flow + the smoke test are the follow-up.

---

Generated by Claude Code

[hyperpolymath]

Forward-pointer (2026-05-31): hypatia#409 (proposed WF021-WF025) was closed as partially superseded — main's recent WF021-WF023 work consumed the WF021/WF024 slots. The 3 detector ideas in this cohort (#361/#363/#366) remain owed and should be implemented by a successor PR using WF024+ numbering (main's highest is WF023).