Nothing re-runs a check on a schedule, so a change outside the repository is never noticed

Open
  • Is something wrong?
#232 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
github-actions, python, yaml
Domain
ci-cd, developer-experience

Research direction

Start by reading .github/workflows/okl-verify.yml, its mirrors in ci/ and src/okl/scaffold/ci/, and tests/test_scaffold.py::test_mirror_files_identical. Then inspect how _stored_check parses verified_by and how okl init updates owned workflows. Decide how scheduled checks handle machine specific commands and the opt-in question; done means the acceptance cases pass, the three workflow copies match, and okl init --ci --dry-run shows the schedule.

Written by the indexing model from the issue text.

Description

enhancement

Problem

A check runs only when a person runs okl verify, or okl reverify, which re-runs the stored checks of lessons whose files changed or whose stamp is from another branch. Drift is event-driven: it fires when a governed file changes in the repository. Nothing in okl runs a check on a schedule, and the shipped CI workflow triggers only on pull_request and push to main.

So a check written to catch a change outside the repository (compare the pinned version of a standard with what its publisher currently serves; probe a vendor contract the code depends on) runs only when someone happens to push. If the publisher changes the standard on a Tuesday and nobody pushes until the following month, every briefing in between is wrong and every gate is green.

Where it stands (verified 2026-10-18)

  • .github/workflows/okl-verify.yml has on: pull_request and on: push: branches: [main] and no schedule:. The copies in ci/ and src/okl/scaffold/ci/ are byte-identical by test (tests/test_scaffold.py::test_mirror_files_identical), so a change lands in all three.
  • CI has no store (okl init gitignores .okl/). The gate reads the committed snapshot okl-drift.json, which carries each rule's verified_by (the evidence receipt: command, expected signal, commit, minute) and verified_commit; _stored_check already parses the command and expected signal back out of it. The snapshot is a one-way export, never imported back into the store (decision of 2026-10-05).
  • okl reverify refuses to run without a store, so it cannot be the thing CI runs today.
  • okl init replaces a workflow it owns only when the file's fingerprint shows it unmodified (_place_owned), and records ci in the config, so a plain okl init refreshes the workflow in a repo set up with --ci.

Proposal

  1. A scheduled job in the shipped workflow. schedule: (weekly) added to the workflow okl writes, so repos get it on their next okl init refresh. See the open question on how it ships.
  2. What the scheduled run does. It re-runs the command parsed from verified_by for each rule in the committed snapshot whose check is self-contained in the repository, and fails the job on a failed check. Rules that expired by TTL (#231) are the first candidates; a flag chooses between "expired only" and "every rule in the snapshot". The run never writes to the snapshot or the store; a failure is a signal for a person to re-verify locally, as it is today.
  3. Honest output. The job reports how many commands it ran; zero counts as "nothing checked", exit 2, per the CLI's exit-code contract, so an empty or malformed snapshot cannot pass as green.

Open questions

  • Opt-in versus the mirror test. The three workflow copies must stay byte-identical, so a per-repo variant breaks the test unless the schedule block ships in the template itself (on by default, or present and commented out), and a variant okl writes with a flag would need re-stamping at write time or the next okl init reads it as modified and keeps the old one. Decide the shape before building.
  • Checks that assume the author's machine. Some verified_by commands name a local interpreter path or a tool CI lacks. The job needs a way to skip those visibly rather than fail on them, or the snapshot needs a per-rule "runs in CI" marker written at verify time.

Acceptance

  • A scratch repo with one rule whose check compares a pinned file with a fixture standing in for the publisher: when the fixture changes and no repo file does, the scheduled job fails; before the change, nothing in the repository would have noticed.
  • The three workflow copies stay byte-identical, and any test that reads the workflow keeps to the standard library (no YAML parser is a declared dependency).
  • okl init --ci --dry-run lists the schedule it would add.

Depends on: #231 for the "expired only" mode. Related: #63 (the pre-push gate and re-verify runner, closed).

Dominant language
Python
Stars
1
Forks
1
Avg merge
5h 10m
Merged PRs (30d)
127

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from emeraldleaf/okl

All issues in emeraldleaf/okl

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.