Backlog scorer: rank open issues into lanes (read-only)

[juemerson-at-purestorage]

Summary

Adds tools/Build-PfbBacklog.ps1, a read-only backlog scorer. It sorts every open issue into exactly one lane and ranks the lanes that are ready to work, so a script rather than a person picks the next unit of work.

Lanes:

• Ranked: build (agent-ready, design-approved) and design (needs-design).
• Proposals: triage, where each issue gets a proposed priority and size for batch confirmation.
• Unranked: inFlight, parked (blocked, human-only), confirmClose (resolved-upstream).
• labelErrors: issues whose labels break the rules in docs/TRIAGE-ROLES.md.

Output is PfbBacklog.json (schema v1) and PfbBacklog.md. The new Backlog workflow publishes the Markdown to the job summary and uploads the JSON as a 90-day artifact. Nothing is committed and Reports/ is untouched.

What it adds

• tools/lib/PfbGitHubRead.ps1: shared read-only GitHub REST helpers (Invoke-PfbGitHubApi, Invoke-PfbGitHubList, and a new Invoke-PfbGitHubPagedList).
  • Paging uses -FollowRelLink, flattening both page shapes.
  • The helper throws rather than truncating when the last page still links to a next page.
  • A rate-limit 403 and a permission 403 produce different messages.
• tools/lib/PfbBacklogTools.ps1: the pure rules.
  • Normalises REST rows and keeps the drift trust boundary: only source:drift issues contribute findings.
  • Places each issue in a lane and reports label problems in two tiers.
  • Holds the impact-class table, the triage proposal and the tiered sort with decidedBy.
  • Builds the schema-v1 object and the Markdown.
• tools/Build-PfbBacklog.ps1: reads open issues through the paged helper and joins them to the committed drift and dead-key reports.
  • Parameters: -Repo, -Token (then GH_TOKEN, then GITHUB_TOKEN), -OutputPath, -Lane, -First.
• .github/workflows/backlog.yml: runs on workflow_dispatch and after every Drift Issues run.
  • Permissions are contents: read and issues: read only.
  • Concurrency group backlog with cancel-in-progress.
  • Inputs reach run: blocks only through env:.
• Tests: Tests/PfbGitHubRead.Tests.ps1, Tests/PfbBacklogTools.Tests.ps1 and Tests/Build-PfbBacklog.Tests.ps1.
• tools/README.md: a new section documenting the scorer.

Refactor

scripts/Assert-PfbAgentReadyBrief.ps1 now dot-sources tools/lib/PfbGitHubRead.ps1 instead of defining its own REST helpers. Its messages, guards and User-Agent are unchanged. The script has no tests, so I checked it with an anonymous live run before and after the extraction: the output was identical (Compare-Object printed nothing). tools/New-PfbDriftIssue.ps1:158's comment pointer now points at the lib.

Design decisions

• Priority first. The human priority: label is the primary sort key; the score only orders issues within a band.

• Tiered keys, no weights. Issues sort by priority, readiness, impact class, size, live finding count (descending), then issue number. decidedBy names the first key that differs from the row above.

• Proposals only. No labels are written. Triage issues get a proposed priority and size, with a differs flag when these disagree with the current labels.

• Impact classes. The proposal comes from the issue's live drift findings. It reproduces the hand triage of Drift: dead or unreachable request keys in the 'arrays' family #163-Drift: dead or unreachable request keys in the 'support' family #172 10/10, pinned as a fixture test.

  Class	Findings	Proposed
  A	dead key on a write (DESTRUCTIVE, CREATE)	P0
  B	dead key on a GET, no surviving selector	P1
  C	response or ValidateSet drift	P1
  D	net-new coverage	P2
  E	new ValidateSet candidate	P3

  Size is S for 10 or fewer live findings and M above that; L is never proposed. An unknown category or severity throws.

• Nothing committed. Output goes to the job summary and a run artifact.

• Output shaping only. -Lane and -First shape the Markdown only; the JSON always carries every lane.

• notes field. Each row carries a notes array. For example, a trusted issue with 0 live findings is flagged as possibly resolved.

• Markdown escaping. Cells escape | and <, so titles and label problems that contain <name> or HTML comments are not dropped by GFM.

Verification

Scoped Pester, touched areas (8 files):

Edition	Pester	Passed	Failed	Skipped	Container
pwsh 7 (7.6.6)	6.0.1	406	0	0	ok
WinPS 5.1	6.0.1	225	0	181	ok

File	pwsh 7 passed/failed/skipped	5.1 passed/failed/skipped
Tests/PfbGitHubRead.Tests.ps1	18 / 0 / 0	0 / 0 / 18
Tests/PfbBacklogTools.Tests.ps1	147 / 0 / 0	0 / 0 / 147
Tests/Build-PfbBacklog.Tests.ps1	16 / 0 / 0	0 / 0 / 16

• Coverage baseline. Tests/coverage-baseline.psd1 pins the winps51 ExpectedSkips at 18 / 147 / 16. The source is #Requires -Version 7.0, so every Describe skips on 5.1. The header was recomputed as 22 entries summing to 503, across 213 test files.
• Analyzer. PSScriptAnalyzer 1.25.0 with the repo settings: 0 gated findings and 0 warnings on every touched file. Every added line is ASCII.
• Live read-only smoke run. One anonymous GET scored all open issues, 56 at the time of the run. Drift: dead or unreachable request keys in the 'arrays' family #163-Drift: dead or unreachable request keys in the 'support' family #172 landed in build/design, the legacy triage set landed in triage with proposals, and labelErrors was empty. git status was clean afterwards.
• Live multi-page probe. Run during the final review, it confirmed the paging path against the real API:
  • several pages flatten to the full record set;
  • the ceiling throws when a next page remains;
  • exactly-full pages at the ceiling do not throw.
• Wire exemption. Test-PfbWireExemption.ps1 gives VERDICT: EXEMPT. The diff leaves the module source and the manifest entirely untouched, so nothing here can alter a request the module sends or a response it parses.

No version bump or CHANGELOG edit.

After merge

workflow_run fires only from the workflow file on the default branch. The Drift Issues → Backlog chain starts working once this is merged; until then only workflow_dispatch can run it.

🤖 Generated with Claude Code