feat(drift-issues): reconcile with apply when the capability-map PR merges

[juemerson-at-purestorage]

Summary

Merging the weekly capability-map PR now starts the drift-issue reconciler automatically, with -Apply. Until now, drift-issues.yml ran only when dispatched by hand, so a new REST spec release reached the drift reports but never reached the issue tracker unless someone remembered to run it.

The weekly update-api-capability-map.yml rebuild stays the detector; nothing polls. The event is that PR's merge.

Behaviour

• Trigger. drift-issues.yml adds a push trigger on main, scoped to Reports/PfbApiDriftReport.json and Reports/PfbDeadKeyReport.json. workflow_dispatch is unchanged (apply still defaults to false).

• Gate. A new step runs tools/Test-PfbCapabilityMapMerge.ps1. It asks GitHub which merged PR introduced the pushed commit (GET repos/{repo}/commits/{sha}/pulls) and passes only if that PR:

  • is merged,
  • came from head branch automated/update-api-capability-map,
  • came from head repository dmann000/fb-powershell (a fork branch with the same name does not pass),
  • targeted main.

  Any other merge that touches the reports skips the reconcile step cleanly and logs why (for example PR #173 head branch 'feat/backlog-scorer' is not 'automated/update-api-capability-map'). An empty association is retried 3 times, 15s apart. A failed API call fails the job instead of answering "no".

• Reconcile. On a gated push, New-PfbDriftIssue.ps1 runs with -Apply and its existing -MaxCreate 10 cap and mass-vanish guard. -AcceptMassVanish is never passed automatically.

• Chain. Backlog already re-ranks after Drift Issues completes, so a merge now flows through to a re-ranked backlog.

• Hardening. Permissions are contents: read, issues: write, pull-requests: read. Values reach run: only through env: (no ${{ }} in any run: block). The job is guarded to dmann000/fb-powershell for push events. Concurrency group drift-issues, never cancelled.

The decision is a pure function (Get-PfbCapabilityMapMergeVerdict in tools/lib/PfbDriftIssueTools.ps1). The script only does the API call, retry and output.

Files

• tools/lib/PfbDriftIssueTools.ps1: Get-PfbCapabilityMapMergeVerdict and a null-safe field helper.
• tools/Test-PfbCapabilityMapMerge.ps1: new gate script. Writes is_capability_map_merge to GITHUB_OUTPUT.
• .github/workflows/drift-issues.yml: push trigger, gate step, conditional apply.
• tools/README.md: reconciler CI paragraph rewritten; "## CI" now says what merging the capability-map PR starts.
• Tests: Tests/PfbDriftIssueTools.Tests.ps1 (+11), new Tests/Test-PfbCapabilityMapMerge.Tests.ps1 (7, fake gh, GITHUB_OUTPUT isolated), Tests/New-PfbDriftIssue.Tests.ps1 workflow block replaced (8).

Tested

• Scoped Pester on the touched files: pwsh 7 212 passed / 0 failed / 0 skipped; Windows PowerShell 5.1 196 / 0 / 16 (the 16 are Build-PfbBacklog's existing declared skips). The new test file runs on both editions, so coverage-baseline.psd1 does not move.
• Repo-wide sweep tests (TestModuleImportGuard, CiCoverageGate, PfbApprovedVerbSuppressions): 39 / 0 / 0 on both editions.
• PSScriptAnalyzer with repo settings, per file: 0 findings.
• drift-issues.yml parses as YAML (js-yaml); triggers, permissions and both if: conditions as intended.
• scripts/Assert-PfbDerivedArtifacts.ps1: all 11 artifacts up to date.
• Live gate against this repo's real history (read-only GET):
  • b9670ff (merge of the capability-map integration branch): true.
  • the same PR checked against the default branch name as a control: false.
  • 233b7c8 (merge of Backlog scorer: rank open issues into lanes (read-only) #173): false, wrong head branch.
  • 302f9e4 (a squash merge from a fork): false, wrong head repository.

Can't be tested before merge

• The push trigger fires only from the workflow file on the default branch. The first real capability-map PR merge is the true-path test: look for a Drift Issues run with event push whose gate step prints PR #N merged from dmann000/fb-powershell:automated/update-api-capability-map into main.
• Rebase merges are unmeasured. The repo allows "Rebase and merge", but none of the last 76 merges used it, so there is no case to check the commit-to-PR association against. Merge commits and squashes are both measured above. Until one rebase case is observed, please merge the automated capability-map PR with a merge commit or a squash. If a rebase merge were not associated, the gate would log no associated pull request and skip, not write anything wrong.

Precondition (unchanged)

The repository's Actions setting "Allow GitHub Actions to create and approve pull requests" must stay on for the weekly PR to open at all. This is already stated in tools/README.md "## CI"; nothing here adds to it.

Live-verification exemption

Wire-exempt per Test-PfbWireExemption.ps1 (VERDICT: EXEMPT). Basis: 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 or CHANGELOG change.

🤖 Generated with Claude Code