Rule: detect estate-wide reusable workflow SHA bumps needing propagation

[hyperpolymath]

Context

Three-system propagation architecture for estate-wide reusable workflow SHA bumps:

hypatia (detection)  →  gitbot-fleet (actuation)  →  .git-private-farm (propagation)

The propagation primitive has landed at hyperpolymath/.git-private-farm (scripts/sha-bump-propagate.sh + scripts/wait-for-pr-merge.sh, PR #66). It's generic, env-var driven. It does NOT know when to fire.

The detection role is this issue: when does an estate-wide SHA bump need propagating?

Proposed rule shape

Name: cicd_rules/reusable_workflow_sha_bump_needs_propagation

Trigger: a PR has merged on a repo whose .github/workflows/*.yml is referenced via uses: <repo>/.github/workflows/X.yml@<SHA> from N estate consumers (N >= some threshold, say 5).

Detection signal:

1. PR merge event on hyperpolymath/<repo>.
2. Changed file matches .github/workflows/*-reusable.yml OR .github/workflows/*-validate*.yml OR a workflow listed in the explicit reusable-workflow registry.
3. SHA of the merge commit becomes the new pin target.

Output (finding payload):

finding:
  rule: reusable_workflow_sha_bump_needs_propagation
  severity: medium  # this is a coordination signal, not a defect
  source_repo: hyperpolymath/standards
  source_workflow: .github/workflows/governance-reusable.yml
  old_sha: 861b5e911d9e5dcfb3c0ab3dd2a9a3c8fd0a1613
  new_sha: <merge commit SHA>
  estimated_consumers: 228
  pr_title: <upstream PR title>   # for keyword exclusion at actuation
  pr_number: 341

Sensitivity / specificity

Sensitivity: every merged change to a known reusable workflow should fire. False negatives are expensive (consumers drift on stale SHAs).

Specificity: must NOT fire for:

• Non-reusable workflows (workflows that aren't pinned by SHA from elsewhere).
• Documentation-only changes in the reusable repo.
• PRs whose title matches the keyword-exclusion list (license, SPDX, PMPL, MPL, AGPL, GPL, Apache, copyright, attribution, relicens, secret, vulnerab, CVE-) — per feedback_pr_sweep_title_keyword_exclusion. The keyword filter belongs in actuation (gitbot-fleet), not detection — hypatia should still emit the finding, just with the title attached so the actuator can reject it.

Strategy

Strategy: :review (flag-only — never :auto_execute). The finding routes to gitbot-fleet for actuation; gitbot-fleet pre-filters and triggers propagation.

Estate context

Currently identified reusable workflows in hyperpolymath/standards/.github/workflows/:

• governance-reusable.yml (228 consumers pin)
• rust-ci-reusable.yml
• deno-ci-reusable.yml
• elixir-ci-reusable.yml
• scorecard-reusable.yml
• secret-scanner-reusable.yml
• codeql-reusable.yml
• hypatia-scan-reusable.yml
• mirror-reusable.yml
• changelog-reusable.yml

Also: hyperpolymath/a2ml-validate-action (acts as a reusable action; ~215 consumers per the a2ml-sweep memory).

Test plan

• Unit-test the file-path / event-type filtering against a fixture of recent estate PRs.
• Integration: trigger on a synthetic standards merge, verify finding payload shape.
• False-positive test: a docs-only PR in standards should NOT fire.
• False-positive test: a PR titled "fix: bump license header" should fire detection but the finding payload must include the title so actuation can reject.

Related

• .git-private-farm PR chore(deps): bump trufflesecurity/trufflehog from 3.93.6 to 3.93.7 #66 — propagation primitive
• gitbot-fleet issue (to be filed) — actuation
• feedback_pr_sweep_title_keyword_exclusion
• feedback_no_automated_licence_edits

Origin trace: standards#341 + neurophone#107 (both closed 2026-06-02 as redundant given baseline mechanism); the salvaged scripts at .git-private-farm#66 are the propagation half of this architecture.

[hyperpolymath]

PR #419 open with the detection rule + 27-assertion test suite. Module compiles standalone; ExUnit suite runs in CI. Per the issue's plan, this is the contract everyone downstream needs.