[singerbj]

Summary

This change makes gh-runner audit workflows against the default branch on GitHub (via the API) rather than relying on the local checkout. This ensures the audit reflects what GitHub will actually run, not a potentially stale or out-of-sync local copy.

Key Changes

• Workflow source abstraction: Introduced WorkflowSource interface to support reading workflows from either a checkout or GitHub API, with implementations checkoutWorkflows() and githubWorkflows()

• GitHub API methods: Added GhClient methods to read workflows from GitHub:

  • workflowFileNames() - lists workflow files on a branch
  • workflowFile() - reads a single workflow file raw and untrimmed
  • openPullRequestWithPrefix() - finds open PRs by branch prefix

• Audit refactoring: New auditWorkflows() function that:

  • Reads workflows from GitHub's default branch first
  • Falls back to checkout only if GitHub read fails and checkout exists
  • Warns when falling back or when GitHub can't be read
  • Works without a checkout entirely

• Fix branch logic: Simplified proposeWorkflowFix() to:

  • Check for open fix PRs by prefix instead of any pushed branch
  • Avoid stacking PRs when one is already open
  • Allow new fixes after a PR is closed (even if branch remains)

• Improved reporting: Enhanced workflow audit output to:

  • Indicate which branch is being checked
  • Warn when nothing will send runners jobs
  • Clarify when the refusal watcher is off

• Test coverage: Added comprehensive tests for:

  • Reading workflows from GitHub vs checkout
  • Fallback behavior when GitHub is unreachable
  • Handling of stale checkouts
  • Scanning without a checkout at all
  • PR branch conflict detection

Notable Implementation Details

• The GitHub API read uses raw content format to preserve line numbers for audit reporting
• Checkout fallback only happens if GitHub read fails; a successful read from GitHub is always preferred
• The fix workflow no longer requires a checkout to exist, though one is still needed to actually apply fixes
• Error messages distinguish between "no workflows directory" and "couldn't read" scenarios

https://claude.ai/code/session_011jzs3cPY8d3Le9V5W22Dyd