Skip to content

[Phase 3] Extend Fleet Monitor stub-drift coverage to the initiative-driver stub #886

Closed

Description

@github-actions

Story

As a fleet maintainer,
I want have Fleet Monitor track per-repo initiative-driver stub coverage/drift the same way it already tracks the planner stub,
so that an out-of-date or missing driver stub in an enrolled repo surfaces in the daily health signal instead of failing silently.

Acceptance Criteria

  1. scripts/fleet_monitor.sh detects drift for the driver stub .github/workflows/initiative-driver.yml against petry-projects/.github/standards/workflows/initiative-driver.yml, in ADDITION to the existing planner stub — generalized to iterate a list of (name, stub_path, canonical_path) entries rather than a single hardcoded STUB_PATH/CANONICAL_STUB_PATH.
  2. The fleet report renders a driver stub coverage/drift section (reusing fleet_stub_drift.sh's pure helpers), and drifted driver stubs feed the alert JSON / HAS_STUB_DRIFT path.
  3. The actions-fleet-monitor.yml stub-drift alert step covers the driver stub without regressing the planner-stub coverage (separate section/issue per stub kind, or a clearly-labelled combined section).
  4. Bats cover the multi-stub generalization (extend tests around fleet_stub_drift / fleet_monitor) and confirm the existing planner-stub behaviour is unchanged.
  5. If the canonical driver-stub SHA cannot be read (the template is not yet merged in petry-projects/.github), the driver registry entry is skipped with a ::warning:: (per-stub, non-fatal) — exactly as the existing single-stub path does when its canonical SHA is empty — so Fleet Monitor degrades gracefully before and after the cross-repo template lands.

Tasks / Subtasks

Dev Notes

  • fleet_stub_drift.sh is ALREADY pure and stub-agnostic (takes a canonical SHA + a per-repo SHA, classifies ALIGNED/DRIFTED/MISSING). The hardcoding lives in fleet_monitor.sh: STUB_PATH (:35), CANONICAL_STUB_PATH (:37), the comparison loop (:187-206), the report section (:239-243), and the alert export (~:309-319).
  • Generalize by looping over a small registry, e.g. [(initiative-planner, .github/workflows/initiative-planner.yml, standards/workflows/initiative-planner.yml), (initiative-driver, .github/workflows/initiative-driver.yml, standards/workflows/initiative-driver.yml)], calling the existing pure helpers per entry and accumulating per-stub drift files.
  • Keep it ADDITIVE: the planner stub section, its tracking issue, and HAS_STUB_DRIFT semantics must keep working — the Live idea:approved canary + Fleet Monitor coverage #822 behaviour is load-bearing.
  • The driver canonical path must match Story 2's exactly; this story is blocked_by Story 2 so the canonical template exists to compare against (otherwise every enrolled repo reads as MISSING/404).
  • Cross-repo merge ordering: this story needs Story 2's stub template MERGED to petry-projects/.github's default branch (not just authored) for a non-empty canonical SHA — blocked_by [2] captures the intra-plan edge, but the canonical read is cross-repo, so the generalized loop must keep the existing empty-canonical warn-and-skip per stub.

Project Structure Notes

All in .github-private — dev-lead-authorable. Net-new bats should be added to lint.yml's bats list per AGENTS.md.

References

  • scripts/fleet_monitor.sh#stub-coverage-and-drift
  • scripts/fleet_stub_drift.sh
  • .github/workflows/actions-fleet-monitor.yml#track-stub-drift
  • tests/ (fleet monitor / stub drift bats)

Likely target surface

  • scripts/fleet_monitor.sh
  • scripts/fleet_stub_drift.sh
  • .github/workflows/actions-fleet-monitor.yml
  • tests/

Story prepared by the BMAD Scrum Master (Bob) for epic #882. Status: ready-for-dev.

Activity

  1. don-petry commented on Jun 22, 2026

    @don-petry
    Collaborator

    Dev-Lead Implementation Plan

    Issue: #886 — [Phase 3] Extend Fleet Monitor stub-drift coverage to the initiative-driver stub

    Scope

    Generalize Fleet Monitor's single hardcoded planner-stub drift check into iteration over a small stub registry (initiative-planner + initiative-driver), reusing fleet_stub_drift.sh's pure helpers per stub, with a per-stub warn-and-skip when a canonical SHA is unreadable.

    Implementation Checklist

    • scripts/fleet_stub_drift.sh: parameterize generate_stub_drift_report by a stub display-label (default keeps "Initiative-planner"); extend stub_drift_alert_json to optionally tag each row with stub/stub_file fields.
    • scripts/fleet_monitor.sh: replace STUB_PATH/CANONICAL_STUB_PATH + the single per-repo loop/report/alert export with a STUB_REGISTRY of (name, label, stub_path, canonical_path); iterate it, building per-stub drift files, a report section per stub, and a merged alert JSON; preserve the empty-canonical ::warning:: warn-and-skip per stub.
    • .github/workflows/actions-fleet-monitor.yml: update the "Track stub drift" step to group the merged alert JSON by stub and create/update a separate tracking issue per stub kind (planner issue title unchanged); keep HAS_STUB_DRIFT/STUB_DRIFT_COUNT semantics.

    Tests to Write

    • tests/fleet_stub_drift.bats: generate_stub_drift_report renders a passed stub label (e.g. "Initiative-driver"); default label still renders "Initiative-planner" (regression).
    • tests/fleet_stub_drift.bats: stub_drift_alert_json with a stub label tags each DRIFTED row with stub/stub_file; without a label the existing output is unchanged (regression).

    Test Command

    scripts/run-bats.sh tests/fleet_stub_drift.bats (full suite via lint.yml bats job) and bash .dev-lead/scripts/dev-lead-lint.sh

  2. don-petry commented on Jun 22, 2026

    @don-petry
    Collaborator

    Dev-Lead: Implementation Complete

    Plan Execution

    • Parameterized fleet_stub_drift.sh pure helpers: generate_stub_drift_report now takes a stub-label (default Initiative-planner); stub_drift_alert_json optionally tags each DRIFTED row with stub/stub_file.
    • Generalized fleet_monitor.sh: replaced the single STUB_PATH/CANONICAL_STUB_PATH with a STUB_REGISTRY of (name, label, stub_path, canonical_path) covering both initiative-planner and initiative-driver; iterates it, builds a per-stub drift file, a report section per stub, and a merged alert JSON. Per-stub empty-canonical ::warning:: warn-and-skip preserved (AC#5).
    • Updated actions-fleet-monitor.yml "Track stub drift" step to group the merged JSON by stub kind and create/update a separate issue per stub (planner issue title unchanged — additive, AC#3).
    • Extended tests/fleet_stub_drift.bats for the parameterized helpers + a regression test that the default heading is still Initiative-planner.

    Test Results

    ok 9 stub_drift_alert_json: emits only DRIFTED enrolled repos
    ok 10 stub_drift_alert_json: an all-aligned TSV yields an empty array
    ok 11 stub_drift_alert_json: an empty/absent TSV yields an empty array
    ok 12 stub_drift_alert_json: a stub label/file tags each DRIFTED row (multi-stub)
    ok 13 generate_stub_drift_report: summarizes counts and lists drifted repos
    ok 14 generate_stub_drift_report: a passed stub label headlines the section (multi-stub)
    ok 15 generate_stub_drift_report: the default label is still Initiative-planner (regression)
    ok 16 generate_stub_drift_report: a clean fleet reports no drift
    

    Full lint.yml bats suite (686 tests) passes; bash .dev-lead/scripts/dev-lead-lint.sh passes (shellcheck + agent-profile validation).

    Files Changed

    • scripts/fleet_stub_drift.sh: parameterized report heading + alert-JSON stub tagging (pure, backward-compatible defaults).
    • scripts/fleet_monitor.sh: single-stub path → stub registry iteration with per-stub drift files, report sections, merged alert JSON, and per-stub warn-and-skip.
    • .github/workflows/actions-fleet-monitor.yml: stub-drift alert step now tracks each stub kind in its own issue; clean-run notice mentions both stubs.
    • tests/fleet_stub_drift.bats: +3 tests (driver label, multi-stub alert tagging, planner-default regression).

    Notes

    • Tests live in the already-listed tests/fleet_stub_drift.bats, so no lint.yml bats-list change was needed.
    • Graceful degradation (AC#5): if the canonical driver template is not yet merged in petry-projects/.github, that registry entry is skipped with a per-stub ::warning:: and the planner path runs unchanged; if both are unreadable, the monitor emits [] and annotates a clean run.
    • No new AGENTS.md workflow exception needed — this modifies the existing canonical fleet-monitor workflow rather than adding a new one.
  3. added a commit that references this issue on Jun 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    dev-leadFor dev-lead agent pickupinitiativeEpic / initiative tracking issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions