Load your rules: a section for rules that rest on a standard you don't control

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

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
57/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
developer-experience, documentation

Research direction

Read docs/LOAD-YOUR-RULES.md and the README TTL passages, then check current command behavior in src/okl/store.py and src/okl/drift.py before describing it. Add the proposed section and worked example, link the README TTL sentences to it, and record a rule covering those three files. Done means the commands were checked against the current release and the text accurately explains expiry and verification behavior.

Written by the indexing model from the issue text.

Description

enhancement

Problem

docs/LOAD-YOUR-RULES.md covers rules that come from a team's own documents and are kept true by the team's own code changing. Step 8 goes one step further: put a caller the rule relies on, or the lockfile when a version matters, in the rule's files. It stops there. Nothing covers a rule whose authority is outside the repository altogether: a public body's code list, a published data standard, a vendor's API contract. Those rules go stale when the other party changes something, no file in the repo moves, and the review that was right when it happened is wrong afterwards with no signal.

okl has the pieces for this and the guide never assembles them. The guide mentions the TTL once, as the ttl_days field in the list of allowed import fields. The README documents the TTL in three places (the failure-modes table, the "what makes a lesson different" list, and the drift section) and none says when to set one.

Proposal

A section in docs/LOAD-YOUR-RULES.md, "Rules that rest on a standard you don't control", with four steps and one worked example:

  1. Pin the authority in the repo. A version number in a manifest, or a vendored copy of the code list or schema, committed next to the code that depends on it. An upstream revision then becomes a local diff.
  2. Watch the pin. Put the pinned file in the rule's files, so content drift fires when the pin changes. This is step 8's advice applied to something you don't own.
  3. Give the rule an expiry. --ttl-days matched to the publisher's cadence (a quarterly code list gets a quarter). Say plainly what that does on the current release: the briefing tags the rule stale and okl show says so; the gate does not go red, and okl reverify does not re-run an expired rule whose files are unchanged, until #231 ships.
  4. Write the check as pinned-versus-current. okl verify <id> --run "<command that fetches the current version and compares it with the pin>" --expect "<signal>". Say when it runs: when a person runs okl verify, when okl reverify picks the rule up because its files changed, and on a schedule only once #232 exists.

The worked example is generic: a published code list a pipeline reads, where the publisher renames a code and reassigns its identifier, so every consumer that reviewed its mapping earlier is wrong without any local change.

Acceptance

  • The section exists, every command in it is run against the current release before merging, and it states the gate's behaviour as it is on that release rather than as planned.
  • The README's TTL sentences link to the section.
  • A rule is recorded for the section with files naming docs/LOAD-YOUR-RULES.md, src/okl/store.py and src/okl/drift.py and a check, so a later change to TTL or drift behaviour re-opens the guide. No drift rule governs the guide today.

Related: #231, #232.

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.