Skip to content

Codify the off-peak scheduling standard and offset this repo's 11 minute-0 crons #1052

Closed

Description

@don-petry

Story

As an org administrator,
I want the off-peak scheduling standard codified in standards/ci-standards.md and this repo's own minute-0 crons offset,
so that the org source-of-truth repo both documents and obeys the convention before it is rolled out to the fleet.

Context

Promoted from petry-projects/.github-private#726 (epic #722). Phase 1 established the convention repo-locally in .github-private, which is now fully compliant: 0 minute-0 crons out of 20. The convention was never lifted into the org standard, and this repo is now the worst offender in the fleet — 11 of 14 scheduled workflows fire on the top of the hour, including one hourly 0 * * * *.

This story was previously held as hands_off because .github-private's dev-lead could not modify this repo. That is no longer true: this repo has its own dev-lead.yml, so the work is in-repo and automatable here.

Current violations in this repo

Workflow Cron
compliance-retrigger.yml 0 * * * * — hourly, on the hour
dependabot-rebase.yml 0 */4 * * *
canary-rollout.yml 0 */4 * * *
add-to-project-reconcile.yml 0 7 * * *
feature-ideation.yml 0 7 * * 5
standards-deploy.yml 0 8 * * 1
pinned-version-report.yml 0 8 * * 1
org-scorecard.yml 0 9 * * 1
daily-org-status.yml 0 11 * * *
pr-limits-report.yml 0 12 * * *
compliance-audit-and-improvement.yml 0 12 * * 5

Note standards-deploy.yml and pinned-version-report.yml collide exactly (0 8 * * 1), as do the two 0 */4 entries.

Acceptance Criteria

  1. standards/ci-standards.md gains a Scheduled workflow timing section codifying: no 0 * * * *; no minute-0 starts; spread minutes across the hour; guidance for higher-frequency idempotent sweeps. It cites the .github-private repo-local section as its origin and is written so downstream repos defer to it.
  2. Every scheduled workflow in this repo is offset off the top of the hour, changing only the cron minute field — never the hour, day, or frequency. No two workflows in this repo share an identical cron expression afterward.
  3. A CI compliance check fails any workflow in this repo whose cron minute is 0, with a message pointing at the new standard section. Wire it into the existing lint job.
  4. The check and the offsets are covered by tests using the repo's existing bats conventions; shellcheck --severity=warning -x stays clean.
  5. Downstream fan-out is explicitly out of scope and stated as such in the PR — 18 minute-0 crons across 9 consumer repos remain, tracked in .github-private#726.

Tasks / Subtasks

Dev Notes

  • Change the minute field only. canary-rollout.yml must stay every-4-hours; compliance-retrigger.yml must stay hourly. Retiming frequency is not in scope and would change agent behaviour.
  • Pick offsets deterministically (e.g. hash the workflow filename into 1–59) rather than by hand, so the CI check and the values agree and new workflows get a defensible minute.
  • .github-private/AGENTS.md has the repo-local "Scheduled workflows" section this standard is promoted from — mirror its wording so the two do not drift, and expect that repo to replace its copy with a deferral pointer once this lands.
  • Precedent for repo-local → org promotion is the Cost-reporting section noted in AGENTS.md; reuse that pattern rather than inventing a new one.

References

  • standards/ci-standards.md
  • petry-projects/.github-private#726 (origin), epic #722

Activity

  1. don-petry commented on Sep 1, 2026

    @don-petry
    ContributorAuthor

    Dev-Lead Implementation Plan

    Issue: #1052 — Codify the off-peak scheduling standard and offset this repo's 11 minute-0 crons

    Scope

    Codify an off-peak "Scheduled workflow timing" section in standards/ci-standards.md (promoted from the .github-private repo-local convention), offset all 11 minute-0 crons in this repo's own .github/workflows/ (minute field only, de-duplicating the two colliding pairs via a deterministic filename hash), and add a CI lint check + bats coverage that fails any minute-0 cron. Downstream fan-out to consumer repos is explicitly out of scope.

    Implementation Checklist

    • standards/ci-standards.md: add the Scheduled Workflow Timing section (AC Addressing PR comments #1) — no 0 * * * *, no minute-0 starts, spread minutes, guidance for high-frequency idempotent sweeps; cites the .github-private repo-local origin and is written for downstream deferral.
    • scripts/lib/cron-timing.sh: pure, sourceable helpers — cron_minute_field, cron_minute_is_zero, deterministic cron_offset_minute (cksum-based, 1–59).
    • scripts/check-cron-timing.sh: scans .github/workflows/*.yml, fails on any minute-0 cron, message points at the new standard section (AC Add coding standards & principles section to AGENTS.md #3).
    • Offset all 11 minute-0 crons — minute field only, hour/day/frequency unchanged; de-dup the two 0 */4 and two 0 8 * * 1 collisions (AC Add multi-agent isolation strategy using git worktrees #2).
    • Wire the check into ci.yml's Lint job and .dev-lead/scripts/dev-lead-lint.sh (AC Add coding standards & principles section to AGENTS.md #3).
    • .github/workflows/cron-timing-tests.yml: bats runner for the new suite.

    Tests to Write

    • test/scripts/cron-timing/cron-timing.bats: unit-test the lib helpers (minute extraction, minute-0 detection, deterministic/collision-free offsets).
    • test/scripts/cron-timing/check.bats: the check fails on a fixture with a minute-0 cron and passes on the real .github/workflows/ after offsetting; asserts no two workflows share an identical cron expression.

    Test Command

    bats test/scripts/cron-timing/ (plus bash scripts/check-cron-timing.sh and bash .dev-lead/scripts/dev-lead-lint.sh)

  2. don-petry commented on Sep 1, 2026

    @don-petry
    ContributorAuthor

    Dev-Lead: Implementation Complete

    Plan Execution

    Offsets applied (minute field only)

    Workflow Before After
    compliance-retrigger.yml 0 * * * * 11 * * * *
    dependabot-rebase.yml 0 */4 * * * 50 */4 * * *
    canary-rollout.yml 0 */4 * * * 33 */4 * * *
    add-to-project-reconcile.yml 0 7 * * * 54 7 * * *
    feature-ideation.yml 0 7 * * 5 41 7 * * 5
    standards-deploy.yml 0 8 * * 1 16 8 * * 1
    pinned-version-report.yml 0 8 * * 1 31 8 * * 1
    org-scorecard.yml 0 9 * * 1 6 9 * * 1
    daily-org-status.yml 0 11 * * * 55 11 * * *
    pr-limits-report.yml 0 12 * * * 44 12 * * *
    compliance-audit-and-improvement.yml 0 12 * * 5 57 12 * * 5

    Both collisions are resolved (50 vs 33; 16 vs 31) and no two workflows in .github/workflows/ share an identical cron expression.

    Test Results

    $ bats --print-output-on-failure test/scripts/cron-timing/
    1..14
    ok 1 check passes on a directory whose crons are all offset
    ok 2 check fails on a minute-0 cron and points at the standard
    ok 3 check catches the hourly-on-the-hour form (0 * * * *)
    ok 4 check suggests a non-zero replacement minute for the offending file
    ok 5 the real .github/workflows/ tree passes the check (AC #2)
    ok 6 no two workflows in this repo share an identical cron expression (AC #2)
    ok 7 cron_minute_field extracts field 1 of a 5-field expression
    ok 8 cron_minute_field tolerates leading/trailing whitespace
    ok 9 cron_minute_is_zero is true only for a bare minute-0 start
    ok 10 cron_minute_is_zero is false for any offset minute
    ok 11 cron_offset_minute returns a deterministic minute in 1..59
    ok 12 cron_offset_minute never returns 0 (would recreate the violation)
    ok 13 cron_offset_minute is basename-based (path-independent)
    ok 14 cron_offset_minute de-duplicates the two colliding pairs
    
    $ bash .dev-lead/scripts/dev-lead-lint.sh
      [lint] shellcheck on 33 file(s)...
      [lint] checking scheduled workflow cron timing...
    cron-timing: all scheduled workflows in .../.github/workflows are offset off the top of the hour
      [lint] validating .github/CODEOWNERS... OK
      [lint] all checks passed
    
    # Also clean: shellcheck --severity=warning -x, yamllint (ci config), actionlint 1.7.7,
    # markdownlint-cli2, and the pre-existing ci/ + compliance-audit stub-surface-drift suites.
    

    Files Changed

    • standards/ci-standards.md: new Scheduled Workflow Timing section; org-scorecard schedule line updated to 09:06 UTC.
    • 11 .github/workflows/*.yml: minute-only cron offsets (table above), comments updated to the new times.
    • scripts/lib/cron-timing.sh, scripts/check-cron-timing.sh: new (lib + check).
    • .github/workflows/ci.yml: new "Lint scheduled workflow timing" step in the Lint job.
    • .dev-lead/scripts/dev-lead-lint.sh: runs the check locally.
    • .github/workflows/cron-timing-tests.yml, test/scripts/cron-timing/{cron-timing,check}.bats: new tests + runner.
    • docs/initiatives/canary-rollout-adr.md: cron reference updated to 33 */4 * * *.

    Notes

    • Downstream fan-out is explicitly out of scope (AC Add stacked PR strategy and Epic-level workflow guidance #5): the templates in standards/workflows/ (e.g. feature-ideation.yml 0 7 * * 5, dependabot-rebase.yml 0 */4 * * *) are left untouched, and the check deliberately does not sweep them. The remaining 18 minute-0 crons across 9 consumer repos remain tracked in petry-projects/.github-private#726; retiming a template changes what every consumer receives and belongs to that fan-out effort, not this source-of-truth timing fix.
    • Offsets are chosen deterministically by hashing the filename (cron_offset_minute), so the CI check and the values agree and any newly added workflow gets a defensible, collision-resistant minute.
    • The stub-surface-drift compliance test already asserts feature-ideation cron retuning is not drift, so the minute change there is expressly sanctioned.
  3. added a commit that references this issue on Sep 1, 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

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions