Skip to content

[Phase 1] Codify the off-peak scheduling standard + CI compliance check #724

Closed

Description

@github-actions

Story

As a org-standards maintainer,
I want document the off-peak-minute scheduling convention (plus the idempotent-sweep higher-frequency guidance) as a repo-local standard and add a CI check that flags any new minute-0 scheduled cron,
so that the convention is enforced for future workflow edits instead of relying on memory, and is staged for promotion into the org-wide standard.

Acceptance Criteria

  1. AGENTS.md gains a 'Scheduled workflows' standard section (mirroring the existing 'Cost reporting' repo-local-standard precedent) stating: never schedule at minute 0 / 0 * * * *; use a staggered off-peak minute; and per Option 2, idempotent/self-healing sweeps may run at a higher frequency on odd offsets because extra ticks are harmless and missed ticks self-heal.
  2. That section includes a 'Promotion' note: this is currently a repo-local standard; to make it org-wide, lift it into petry-projects/.github (standards/ci-standards.md) and have repos defer to it -- explicitly referencing the org-wide rollout story.
  3. A CI check (a new step/job in lint.yml, e.g. validate-workflow-schedules, backed by a small shell script) detects any schedule.cron using minute 0 across this repo's .github/workflows/*.yml and agentic *.md sources and reports the offending file(s).
  4. The check passes on the current tree (it runs after Story 1's offsets are applied) and flags a reintroduced 0 * * * * cron (demonstrated by a fixture/test).
  5. If the check is script-backed, it follows repo conventions (POSIX bash, set -euo pipefail) and its bats test file is added to the bats list in lint.yml.

Tasks / Subtasks

Dev Notes

  • Precedent for a repo-local standard with a promotion path: AGENTS.md '### Cost reporting' ends with a 'Promotion: this is currently a repo-local standard ... lift it into petry-projects/.github' note -- follow that exact shape so the standard is consistent and Story 4 can lift it cleanly.
  • lint.yml already hosts focused validation jobs (shellcheck, bats, validate-agent-profiles, gh-aw-compile) -- add the schedule check as a sibling job/step; the bats job runs an explicit allow-list of test files, so a new test file must be appended to that list (AGENTS.md documents that the bats list is intentionally repo-extended and must not be reset by template syncs).
  • This must land AFTER Story 1: a hard-failing minute-0 check would otherwise fail CI on the existing tree. The standard text also documents the convention Story 1 just applied.
  • Keep the parser simple and robust: match the cron minute field (first whitespace-delimited token after the quoted cron value). Guidance only -- do not attempt full cron validation.

Project Structure Notes

Edits AGENTS.md and lint.yml; adds one small script under scripts/ and one bats file under tests/ (added to the lint.yml bats list). No changes to workflow runtime behavior beyond the new check.

References

  • AGENTS.md#cost-reporting
  • AGENTS.md#workflow-files
  • .github/workflows/lint.yml#bats
  • .github/workflows/lint.yml#validate-agent-profiles
  • tests/fleet_report.bats

Likely target surface

  • AGENTS.md
  • .github/workflows/lint.yml
  • scripts/
  • tests/

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

Activity

  1. don-petry commented on Jul 14, 2026

    @don-petry
    Collaborator

    Dev-Lead Implementation Plan

    Issue: #724 — [Phase 1] Codify the off-peak scheduling standard + CI compliance check

    Scope

    Document the off-peak (never minute-0) scheduled-workflow convention as a repo-local standard in AGENTS.md (with a Promotion note), and add a script-backed CI check in lint.yml that flags any schedule.cron whose minute field is 0 across this repo's own workflow/agentic sources.

    Implementation Checklist

    • AGENTS.md: add ### Scheduled workflows standard section — minute-0 prohibition, staggered off-peak minute, Option-2 idempotent-sweep note, and a Promotion pointer (mirrors ### Cost reporting)
    • scripts/validate-workflow-schedules.sh: POSIX bash (set -euo pipefail) — extract schedule.cron minute field from in-scope sources and flag any minute-0 cron, reporting file:line + offending cron
    • Scope scanned to repo-local sources: .github/workflows/*.yml, .github/workflows/*.md, docs/aw/*.md (excludes frameworks/ subtrees)
    • .github/workflows/lint.yml: add validate-workflow-schedules job + append the new bats test to the bats job list
    • Fixtures under tests/fixtures/schedule-lint/ (clean tree passes, reintroduced 0 * * * * flagged)

    Tests to Write

    • tests/test_validate_workflow_schedules.bats: unit tests for the minute-field parser (flags 0 * * * *, passes 11 9 * * 1, handles quotes/comments/*/6), plus fixture-tree tests (clean passes, dirty flagged), plus a guard that the live repo tree passes
    • Fixture files demonstrating clean vs. reintroduced-minute-0 trees

    Test Command

    scripts/run-bats.sh tests/test_validate_workflow_schedules.bats

  2. don-petry commented on Jul 14, 2026

    @don-petry
    Collaborator

    Dev-Lead: Implementation Complete

    Plan Execution

    • AGENTS.md — added ### Scheduled workflows standard (minute-0 prohibition, staggered off-peak minute, Option-2 idempotent-sweep note, CI-enforcement pointer, and a Promotion note referencing standards/ci-standards.md + the epic Reliable scheduled Actions: off-peak cron offsets, scheduling standard, and schedule-reliability reporting #722 rollout)
    • scripts/validate-workflow-schedules.sh — POSIX bash (set -euo pipefail) that extracts each schedule.cron minute field and flags any minute-0 cron, reporting file:line: <cron>
    • Scope limited to repo-local sources (.github/workflows/*.yml, .github/workflows/*.md, docs/aw/*.md); frameworks/ subtrees intentionally excluded
    • lint.yml — added validate-workflow-schedules job and appended the new bats file to the bats job list
    • Fixtures under tests/fixtures/schedule-lint/ (clean tree passes; reintroduced 0 * * * * in both a .yml and an agentic .md is flagged)
    • tests/test_validate_workflow_schedules.bats — parser unit tests + fixture-tree tests + a live-repo-tree guard

    Test Results

    $ scripts/run-bats.sh <full lint.yml bats list + new file>
    ...
    ok 1173 reintroduced 0 * * * * cron in a workflow yml is flagged
    ok 1174 minute-0 cron in an agentic *.md source is flagged
    ok 1175 the current repository tree passes the schedule-lint
    exit: 0   # 1175/1175 pass (13 new)
    
    $ shellcheck --severity=warning -x scripts/validate-workflow-schedules.sh   # clean
    $ bash .dev-lead/scripts/dev-lead-lint.sh                                    # all checks passed
    $ bash scripts/validate-workflow-schedules.sh
    schedule-lint: OK — no minute-0 (top-of-hour) scheduled crons found.
    

    Files Changed

    • AGENTS.md: new ### Scheduled workflows repo-local standard with Promotion note
    • .github/workflows/lint.yml: new validate-workflow-schedules job + bats-list entry
    • scripts/validate-workflow-schedules.sh: the schedule-lint (new)
    • tests/test_validate_workflow_schedules.bats: unit + fixture tests (new)
    • tests/fixtures/schedule-lint/**: clean/dirty/dirty-md fixtures (new)

    Notes

    • The check is deliberately a minute-field check (first whitespace-delimited token equals 0), not a full cron validator, per the issue's Dev Notes — it precisely targets the documented 0 * * * * prohibition. It handles single/double-quoted and bare cron values and strips trailing comments.
    • It is a hard-failing PR check; the current tree passes because Story 1 ([Phase 1] Move all scheduled workflows off the top of the hour #723) already moved every cron off minute 0.
    • frameworks/ still contains upstream 0 * * * * examples in subtree knowledge docs; these are upstream-owned, not our schedules, and are out of scope by design.
  3. added a commit that references this issue on Jul 14, 2026
  4. added 9 commits that reference this issue on Aug 2, 2026
  5. added a commit that references this issue on Aug 18, 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