💡 Fleet-Wide Stub Drift Auto-Remediation via Automated PRs

[github-actions[bot]]

Summary

Extend the fleet stub drift detection system (fleet_stub_drift.sh, template_stub_drift.sh) into an automated remediation loop: when drift is detected between a consumer repo's workflow stub and the canonical standards, automatically open a PR in the consumer repo with the corrected content from seed-repo-template.sh. This closes the detect→fix gap that currently requires manual intervention for each drift issue.

Market Signal

• Internal Developer Platforms (Backstage, Cortex, Port) all implement "golden path enforcement" that auto-remediates config drift in consumer repos — this is the standard pattern for platform engineering in 2026
• The GitOps reconciliation loop (detect → remediate → verify) is the established pattern in infrastructure-as-code; the project currently has detect and verify but not remediate
• Gartner predicts 80% of large engineering orgs will have dedicated platform teams by 2026, with automated template sync as a core capability
• GitHub's template repository feature provides initial scaffolding but not ongoing sync — the auto-remediation step fills this gap for petry-projects' internal platform
• AI-powered scaffolding is trending toward embedding observability, security, and deployment patterns by default, with spec-driven bootstrapping ensuring structured context for future AI contributions

User Signal

• Three open drift issues: [Fleet Monitor] Initiative-driver stub drift #910 (initiative-driver stub drift), [Fleet Monitor] Initiative-planner stub drift #863 (initiative-planner stub drift), Compliance: non-stub-feature-ideation.yml #944 (non-stub-feature-ideation.yml compliance) — all represent detected drift requiring manual intervention
• Template drift guard (feat: implement issue #969 — [Phase 1] Drift-guard CI: fail when template stubs diverge from standards/ #983, landed June 28) detects drift at CI time — step 1 of the reconciliation loop is live
• Bootstrap wrapper (feat: implement issue #967 — [Phase 2] Bootstrap wrapper: scripts/bootstrap-new-repo.sh applies the full non-file policy surface #972, landed June 27) handles initial repo setup — step 0 is live
• seed-repo-template.sh generates the canonical content for each file — the fix content is already computable
• But between initial setup and CI detection, there is no automated remediation — drift accumulates until a human notices a drift issue and manually opens a fix PR
• The drift detection system already surfaces the exact file paths and expected content — all the information needed to construct a fix PR

Technical Opportunity

The remediation loop can be built from existing components:

1. fleet_stub_drift.sh already computes the ALIGNED / DRIFTED / MISSING status for every tracked file in every consumer repo
2. seed-repo-template.sh generates the canonical content for each file (and --emit-* flags produce the expected byte-identical content)
3. TEMPLATE_DRIFT_ALLOWLIST in template_stub_drift.sh already handles intentionally-customized files — they are excluded from drift checks and would also be excluded from auto-remediation
4. The GitHub App identity used by the dev-lead and other cross-repo operations already has write access to consumer repos
5. Adding a --remediate flag to the drift detection script would: for each DRIFTED file, create a branch in the consumer repo, commit the canonical content, and open a PR via gh pr create

The PR content is deterministic (computed from the canonical standards), so every auto-remediation PR is auditable and reproducible.

Assessment

Dimension	Score	Rationale
Feasibility	high	All components exist (drift detection, canonical content generation, cross-repo auth, gh CLI PR creation). Integration is incremental.
Impact	med	Closes the detect→fix gap for fleet drift. Reduces manual toil per drift issue from ~30 min (create branch, copy content, open PR) to zero. Scales with fleet size.
Urgency	med	3 open drift issues. Not blocking, but the gap grows as more reusables are onboarded into the canary-ring model (#1008, #1036).

Adversarial Review

Strongest objection: Cross-repo automated PRs introduce a new class of supply-chain risk. A compromised drift-fix bot could push malicious workflow changes to consumer repos under the guise of "standards alignment."

Rebuttal: The auto-PRs would be opened by the same authenticated GitHub App identity that already has write access for dev-lead and other cross-repo operations — no new attack surface is introduced. The PRs go through the normal PR review pipeline (including the project's own pr-review agent) — they are proposals, not direct commits. The content is deterministic (computed from the canonical standards via seed-repo-template.sh), so every change is auditable and reproducible. The TEMPLATE_DRIFT_ALLOWLIST ensures intentionally-customized files are never overwritten. The supply-chain risk is equivalent to the existing cross-repo dev-lead operations.

Suggested Next Step

Extend fleet_stub_drift.sh with a --remediate flag that, for each DRIFTED file, opens a PR in the consumer repo with the canonical content from seed-repo-template.sh. Gate behind DRY_RUN for initial testing. Pilot with a single consumer repo before fleet-wide rollout.

[github-actions[bot]]

📋 Initiative planned by the BMAD Scrum Master (Bob).

Epic #1148 — Fleet-wide stub drift auto-remediation: DRY_RUN-gated, pilot-first PRs that re-sync consumer stubs to canon

4 stories created (inert — labelled initiative, NOT initiative:auto):

• [Phase 1] Pure remediation-plan builder + never-overwrite allowlist #1149 (M) — [Phase 1] Pure remediation-plan builder + never-overwrite allowlist
• [Phase 2] Cross-repo remediation PR driver (DRY_RUN-gated, idempotent) #1150 (L) — [Phase 2] Cross-repo remediation PR driver (DRY_RUN-gated, idempotent)
• [Phase 3] Pilot scope + per-run cap + drift-closed verification gate #1151 (M) — [Phase 3] Pilot scope + per-run cap + drift-closed verification gate
• [Phase 4] Wire opt-in remediation into the fleet-monitor workflow behind a human go/no-go #1152 (M) — [Phase 4] Wire opt-in remediation into the fleet-monitor workflow behind a human go/no-go

Open questions for review:

• Content-source generalization: this plan grounds remediation for the two tracked fleet stubs (initiative-planner.yml, initiative-driver.yml) on the verbatim canonical bytes in petry-projects/.github standards/workflows/. If STUB_REGISTRY later tracks stubs that require repinning (the caller stubs in seed-repo-template.sh's WORKFLOW_MANIFEST), remediation must instead emit via seed-repo-template.sh --emit-workflow so the repin is applied. Confirm scope before extending STUB_REGISTRY.
• Which consumer repo should be the remediation pilot? [Fleet Monitor] Initiative-planner stub drift #863 (initiative-planner) and [Fleet Monitor] Initiative-driver stub drift #910 (initiative-driver) are current DRIFTED cases; confirm a safe pilot repo (and that its stub is genuinely drift-not-intentional-customization) before enabling live remediation at the Phase-4 go/no-go.

---

Review the epic and its sub-issue DAG, adjust as needed, then add initiative:auto to epic #1148 to hand it to initiative-driver for auto-implementation.