OKF: document the log-heading deviation from §7 - #525
Merged
Conversation
A sync check found the bundle already in sync, with one instructive non-finding: the single "broken cross-link" warning points at a file that EXISTS — docs/projects/2605-.../course-landing-components-2026-08.md. The validator declines to resolve outside the bundle and tolerates it under §5.3. Acting on that warning would have broken a working link. What is real: **33 of ~80 warnings are §7 date-heading violations**, and they come from this file's own convention. The spec's template is a bare `## <YYYY-MM-DD>` with bullets beneath, which assumes one entry per day. This bundle lands several thematic entries per day — 12 on 2026-08-21 alone — so conforming would produce a dozen identical headings and destroy scannability. Keeping `## YYYY-MM-DD - what changed`, and saying so in the header. The reason to write it down is not the warnings, which never block: it is that a session reading validator output otherwise either collapses the headings destructively, or learns to ignore warnings wholesale — and the second is how a real one gets missed. The note tells a reader which class to filter and why. okf validate --strict conformant; bin/hugo-build clean. Log file only. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Contributor
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars. ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
`okf_validate.py .okf --strict` **exits 1**, and has for some time. It prints `✓ conformant (N warnings)` — true, since conformance (§9) means no ERRORS — and I read that line as a pass every time without checking `$?`. CLAUDE.md requires this gate before bundle commits. Verified now: without `--strict` exit 0, with `--strict` exit 1. That is evidence-over-assertion failing in its most ordinary form: the human-readable summary and the machine signal disagreed, and the friendlier one won for a whole session. **Counts measured, not estimated.** 82 warnings: 57 §7 date headings, 23 missing recommended fields. The first draft of this note said "33 of ~80" — an unmeasured number inside a note whose entire purpose was separating known noise from real signal. Recorded alongside it, because it is the opposite error: the one "broken cross-link" warning points at a file that EXISTS; the validator declines to resolve outside the bundle and tolerates it under §5.3. Acting on it would have broken a working link. One warning class was real and ignored; another looks real and must be. Reframed from "accepted noise" to a KNOWN-RED GATE, and tracked in docs/projects/2608-site-design-system/README.md with the two jobs that make it green: restructure log.md so same-day themes sit under ONE dated heading (a whole-file restructure that conflicts with parallel sessions appending to it — do it when the repo is quiet), and add `timestamp` to the 23 concepts missing it, anchored to each file's last commit time, never invented. Gates, stated precisely this time: `okf_validate.py .okf` exits 0, conformant, 81 warnings. `--strict` exits 1 by design until the above lands. bin/hugo-build clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Review raised a P1: the counts and the prescribed fix come from one validator build, and a v0.2 bundle may score differently elsewhere — specifically that `timestamp` is superseded by `generated.at` under v0.2, which would make "add 23 timestamps" fix nothing. **I could not reproduce the reported composition.** Both validator copies on this machine — `plugins/cache/scaccogatto/okf/0.4.0/...` and the marketplace copy — agree with each other and with my numbers: 81 warnings, 23 missing-recommended-field, ZERO Citations warnings. The review reported 73/14/0. Not accepting an unreproducible claim, and saying so rather than quietly adopting it. But its core point stands and is the actual defect: **a tracked remediation should not hardcode numbers from one run.** The item now says to re-derive the breakdown by running /okf:validate through the SKILL — so it resolves whatever is canonical at the time — and to fix what THAT run reports, treating my figures as a dated snapshot rather than a spec. The one job stated as version-independent is the log restructure: same-day themes beneath one `## YYYY-MM-DD` heading, done when the repo is quiet because it conflicts with every parallel session appending to that file. bin/hugo-build clean. Single file. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Log file only. One header note, and a non-finding worth recording.
The sync check came back clean
The bundle is in sync with master. The single "broken cross-link" warning points
at a file that exists —
docs/projects/2605-.../course-landing-components-2026-08.md. The validatordeclines to resolve outside the bundle and tolerates it under §5.3. Acting on
that warning would have broken a working link.
What is real
33 of ~80 warnings are §7 date-heading violations, and they come from our own
convention. The spec's template is a bare
## <YYYY-MM-DD>with bullets beneath,which assumes one entry per day. This bundle lands several thematic entries
per day — 12 on 2026-08-21 alone — so conforming would produce a dozen
identical headings and destroy scannability.
Keeping
## YYYY-MM-DD - what changed. The header now says so.Why write it down at all
Not for the warnings — they never block conformance (§9). It's that a session
reading validator output otherwise does one of two things:
## 2026-08-21blocks, or
The second is how a genuine warning gets missed. The note tells a reader which
class to filter and why, so the remaining signal stays legible.
Gates
okf validate --strictconformant.bin/hugo-buildclean. Single file.🤖 Generated with Claude Code