Actuation: consume hypatia SHA-bump-needs-propagation findings + trigger farm propagation #248

Context

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

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

The propagation primitive landed at hyperpolymath/.git-private-farm#66 (scripts/sha-bump-propagate.sh). The detection ruleset is tracked in a separate hypatia issue (reusable_workflow_sha_bump_needs_propagation).

This issue is the actuation glue.

Proposed behaviour

When a hypatia finding of rule cicd_rules/reusable_workflow_sha_bump_needs_propagation arrives:

1. Title-keyword pre-filter (HARD REQUIREMENT — see feedback_pr_sweep_title_keyword_exclusion). Reject + route to manual review if finding.pr_title matches any of:

   license, SPDX, PMPL, MPL, AGPL, GPL, Apache, copyright, attribution,
   relicens, secret, vulnerab, CVE-
   

   Per feedback_no_automated_licence_edits, licence-related changes are NEVER automated, even when policy-correct.

2. Build consumer TSV. Enumerate repos pinning <source_repo>/.github/workflows/<workflow>@<old_sha> via:

   • Query GitHub code search (or the cached estate index in hypatia).
   • Filter to estate-owned repos only.
   • Drop forks (per estate license policy: never touch third-party / forked stuff).
   • Output: <repo>\t<workflow_path> one consumer per line.

3. Compose propagation invocation. Build the env-var payload for sha-bump-propagate.sh:

   REUSABLE_PATH=hyperpolymath/<source_repo>/.github/workflows/<workflow>
   OLD_SHA=<finding.old_sha>
   NEW_SHA=<finding.new_sha>
   BRANCH_NAME=ci/bump-<workflow-slug>-<finding.new_sha:0:7>
   TITLE_SUFFIX=<finding.pr_title cleaned>
   BODY_BLURB=<auto-generated, including upstream PR link>
   CONSUMERS_TSV=<path>
   

4. Trigger propagation via repository_dispatch. Fire a propagate-sha-bump event to hyperpolymath/.git-private-farm carrying the env-var payload as client_payload.

5. Owner notification. Emit a brief summary issue or comment on the upstream PR linking the propagation progress TSV.

Safety properties

• Cap honoured. Hypatia license-related findings have :review strategy with severity-cap — gitbot-fleet's existing licence refusal gates (fix-license-hygiene.sh, fix-license-file.sh, fix-missing-spdx.sh all carry exit 1 refusal banners at the top per the estate feedback_no_automated_licence_edits) must extend to this new actuation path.
• No force-push, no main-direct. All consumer changes go via clone + branch + PR (propagation script already enforces this).
• Throttle. 60s default in propagation script; gitbot-fleet should not invoke multiple concurrent propagations on the same SHA-bump finding.
• Idempotent. If the finding fires twice (e.g. retry), the propagation script's skip_already_bumped / skip_pr_exists short-circuits keep it safe.

Open design questions

• Where does the actuation script live? Likely gitbot-fleet/scripts/dispatch-runner.sh extension OR a new entry in dispatch-runner's recipe set.
• How does gitbot-fleet authenticate to .git-private-farm for repository_dispatch? Existing FARM_DISPATCH_TOKEN pattern per .git-private-farm/dispatch-templates/notify-dependents.yml.
• Granularity: one finding per upstream PR, or batch multiple SHA bumps in a single propagation? Recommend one-per-PR for traceability.

Related

• .git-private-farm#66 — propagation primitive (PR open)
• hypatia issue (to be filed) — detection rule
• feedback_pr_sweep_title_keyword_exclusion
• feedback_no_automated_licence_edits
• Existing licence-refusal precedent in scripts/fix-license-*.sh

Origin trace: standards#341 + neurophone#107 (both closed 2026-06-02 as redundant); the salvaged scripts at .git-private-farm#66 are ready to receive actuation from this layer.