When the gate blocks, say what changed against the lesson, and record the block

Open
  • Is something wrong?
#236 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
52/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
git, python
Domain
developer-experience, tooling

Research direction

Start with cmd_drift in src/okl/cli/verification.py, DriftHit, the store schema, and the pre-push hook; trace how verified_commit and governed files reach the gate. Then inspect okl metric and okl show plus the hook fingerprint and Claude Code hook copies. Done means drift output explains matching or unmatched changes, local blocks are stored and reported while green gates write nothing, and the hook acceptance checks pass.

Written by the indexing model from the issue text.

Description

enhancement

Problem

When the pre-push gate blocks, it says which lesson drifted and which governed files changed, and tells you to run okl reverify. It does not say what in the change contradicts the lesson, and it leaves no trace that it fired. Two consequences:

  • The person at the terminal has to open the diff and work out why the lesson cares. Often the answer is visible in one hunk: a number the lesson names changed, or a term from the lesson's fix was removed.
  • Nothing records the block. The store keeps every check run (pass or fail) and okl show lists them, but a push stopped by the gate is the loop's most direct evidence of value and it vanishes when the terminal scrolls.

Where it stands (verified 2026-10-20)

  • okl drift --gate (cmd_drift, src/okl/cli/verification.py) lists drifted rules with their files and exits 1; the pre-push hook prints the list and "Re-check them with 'okl reverify', commit, then push again".
  • Drift already knows the commit each check passed at (verified_commit) and compares governed files between it and HEAD, so the exact diff is one git diff <verified_commit> HEAD -- <files> away. DriftHit does not carry the commit today; the Node and the snapshot do.
  • The store's tables are node, edge, briefing, retirement and check_run. There is no record of a gate block, and okl metric reports recurrence and briefing exposure only (#129 asks for more).

Proposal

  1. Explain. When a rule drifts, scan the diff of its governed files between verified_commit and HEAD for the numbers and identifiers that appear in the lesson's title, symptom and fix, and print the matching hunk lines beside the lesson, one block per rule: client.py:51 -RETRY_MAX = 4 +RETRY_MAX = 10 · [id] keep the retry cap at 4. When nothing in the diff matches, print the files and lines changed and say no term matched, so the absence is visible rather than silent. DriftHit gains verified_commit so the gate can do this from the hit.
  2. Record. A block on the local gate writes one row (lesson id, governed files, commit, branch, time) to a new gate_block table. CI's gate reads the snapshot and has no store, so it writes nothing; that is stated, not hidden. okl metric reports blocks beside briefings; okl show <id> lists them.
  3. Keep the proof unchanged: the way out is still a passing check or the code back to what passed.

Acceptance

  • A repo with a lesson whose fix names a constant: change the constant, run okl drift --gate, and the output shows the hunk with the lesson; change an unrelated line in the same file and the output says no term matched. Both assertions fail before the change.
  • The block is in the store after the local gate exits 1, and okl metric counts it; a green gate writes nothing.
  • The scaffold pre-push hook keeps a current fingerprint, and the Claude Code hook copies stay byte-identical.

Related: #129 (what the rules cost: catches, false positives, overrides; proposal 2 is one slice of it).

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

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.