OKF sync: what three review rounds taught, plus timestamp and deploy-state integrity fixes - #522
Merged
Conversation
#519 took three Codex rounds (8, 7, 9 findings, none cosmetic). The individual fixes shipped with that PR. What belongs in the bundle is why a docs-only change needed three passes. **workflows/review-swarm.md — a correction is an edit, and it can break what the file already held.** Round three's findings were largely defects that rounds one and two INTRODUCED. Adding "phase status comes from git" left a sentence four lines away still routing to the plan doc. Adding a corrected click figure left the superseded one earlier in the same file. The correcting mindset asks "am I right here now" and does not look sideways at the invariants the document already carried — so after correcting a claim, re-read the WHOLE file, not the paragraph. Two companions to it: * **Sweep a corrected metric through the canonical summaries.** A figure was fixed in two specs and a measurement record while the project README and the plan's own justification still presented the superseded value as current — and those are what a cold session reads FIRST. A number lives in more places than the document that owns it. * **Budget more than one review round for docs.** Prose has no compiler and no test; the only gate is a reader checking claims against the tree. Across three rounds: a residual that would have reintroduced a known regression, an alias inventory that would have broken live CSS, an arithmetic error in a measurement plan, an overstated bot multiplier. One CLEAN round is the signal to stop; one round is not. **workflows/analytics-access.md — cut a measurement window on the DEPLOY, not the MERGE.** The first version of that correction used #487/#494 merge timestamps as proof a Clarity window was contaminated. A merge is not a release: Pages publishes from a separate workflow run that can lag, fail, or be re-run. This cuts both ways — it can condemn a usable window as easily as bless a contaminated one. Read the deployment record; failing that, mark the window contaminated-pending-confirmation with the restore condition written down. okf validate --strict conformant; bin/hugo-build clean. Bundle only. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
**Every OKF timestamp written today was ~2h in the future.** I stamped LOCAL time with a `Z` suffix: actual UTC was 2026-08-20T23:18 while the session clock showed 2026-08-21T01:18 (+0200). Fourteen stamps across eight concepts. That is not cosmetic in this bundle specifically: `.okf/index.md` resolves concurrent-edit conflicts by taking the LATER timestamp, so a future-dated stamp silently outranks a genuinely newer edit from a parallel session. All fourteen corrected to real UTC, and the rule is now recorded next to the conflict rule it undermines: take the value from `date -u`, never compose it from the displayed date. **The deploy conclusion was still asserted as fact in the same paragraph that documents it as unconfirmed.** The added rule says cut the window on the deploy and admits only merge timestamps were read; four lines above, the prose still stated the low window contained the ship. Now conditional, with the restore condition explicit: if the deploy landed after 08-20, that window is clean and its 292 sessions come back. Worth naming: that second defect is precisely what the rule added one commit earlier describes — "a correction is an edit, and it can break what the file already held." I committed it inside the rule about it, which is the strongest evidence for the rule that could exist. okf validate --strict conformant; bin/hugo-build clean. Bundle only. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…te swept Both findings were my own fixes left half-done. **Timestamps: the sweep caught one class and missed its sibling.** I grepped `2026-08-21T*` and corrected those, but stamps written EARLIER in the session were also local-time-with-a-Z and already carried an 08-20 date (23:45, 23:50), so the grep never saw them - and they sat ahead of HEAD. More importantly the converted values were never MEASURED. I derived them by subtracting two hours from times I had invented, and as review noted the originating offsets are not all +0200 (commit 8fa4149 carries +0300). Inventing more precise-looking numbers would repeat the original error. So every stamp this session authored is normalised to one MEASURED value from `date -u` (2026-08-20T23:28:00Z), and the log records that per-edit precision was not recoverable. Monotonic, never future-dated, no invented precision. Other sessions' stamps (the sonnet-5 entry at 2026-08-20T00:00Z) are untouched. **Deploy state: I made the concept conditional and left every summary that feeds it asserting the opposite.** 40.01 said "the deploy time is now confirmed", the README and 20.01 called the window clean, and both phase specs plus site-redesign-rollout repeated it - while analytics-access said no deployment record had been read. Seven locations swept to provisional/pending-confirmation with the restore condition stated: if the deploy landed after 08-20, the 292 excluded sessions come back. That is exactly the rule committed two commits ago - "sweep a corrected metric through the canonical summaries, not just its home" - violated in the next change. Recorded rather than quietly fixed, because the pattern is the point: correcting the owning document feels like completing the correction, and it is not. okf validate --strict conformant; bin/hugo-build clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…count Two fixes, both to my own repair. **Flattening destroyed what `verified:` exists for.** Normalising every affected stamp to the sweep time fixed the future-dating and turned three distinct verification events in test-gates.md into three identical entries, losing their order. The field records a HISTORY of checks; overwriting it with "now" falsely dates past verifications to the correction run and undermines the very conflict rule the sweep was protecting. Converted properly instead. This session ran at +0200 (verified: local 01:18 == UTC 23:18), so each stamp it wrote as local-with-Z converts by -2h and the distinct values come back: test-gates keeps 21:45 / 22:00 / 22:50 in order, seo-meta-tags 21:50, hugo-site / blog-list-page / site-palette 23:20, ci-gates 22:00, rollout 22:30. Only the three concepts actually edited in this change carry the measured 23:28. The rule now says convert with the offset the stamp was written at, or mark it unknown - never overwrite history with now. **The count was wrong.** "Fourteen across eight" was itself an unmeasured assertion in durable guidance. Measured: 18 timestamp literals across 9 concepts (11 .okf/ files touched, less index.md and log.md, which are reserved rather than concepts). Corrected. okf validate --strict conformant; no stamp ahead of the verified clock. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…conditional throughout **P1: -2h was the wrong conversion, and no conversion could have been right.** Git records this repo's commits at +03:00 while the shell reports +0200 - 86c2c91 committed at 02:11:35+03:00 = 23:11:35Z, so a stamp of 23:20Z inside it claimed to postdate its own containing commit. But the deeper problem is that the original local times were never MEASURED; I wrote round numbers. No offset recovers truth from an invented value. So the stamps are no longer converted at all - each is anchored to a VERIFIABLE event: the commit in which it landed. seo-meta-tags and ci-gates take 2026-08-20T22:27:35Z (#516). hugo-site, blog-list-page, site-palette and test-gates take 23:11:35Z (#519). test-gates' verified entries split correctly - `git show 8fa4149:.okf/build/test-gates.md` shows which two existed at #516, so those carry 22:27:35Z and the later one 23:11:35Z, preserving order. The three concepts edited in this change carry a measured `date -u` value. Every stamp is now defensible by a command anyone can re-run. **P2: the conditional state stopped one level short.** analytics-access and the top of 40.01 said pending-confirmation while the labels downstream still read "contaminated", "CLEAN", and "straddles the 08-20 ship" as fact - so a reader following the summaries would discard a possibly-valid window regardless. Six downstream labels made conditional, and the held-out row now states the restore condition rather than being struck through as though settled. okf validate --strict conformant; bin/hugo-build clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
**Third time collapsing distinct events, now fixed with recovered times.** The two opus-5 verified entries in test-gates.md originated in separate commits - 67bdd78 (2026-08-21T00:43:35+03:00 = 21:43:35Z) and 6c4b7ab (2026-08-20T23:47:30+02:00 = 21:47:30Z) - and I had assigned both the #516 squash time, erasing their order for the second time in this branch. Both are now their own commit's time, recoverable by anyone with `git log -1 --format=%cI`. Worth stating plainly: I wrote the rule "convert with the originating offset or mark unknown, never overwrite history with now" and then violated it in the same patch, twice. The pull toward a single tidy value is strong precisely because it LOOKS like consistency. **The conditional sweep reached one more file.** 20.03 still said the window "straddles the 2026-08-20 deploy" and called 08-06→17 clean, so a cold session reading the 2.1 spec would discard a possibly-valid window as settled fact. Now provisional with the restore condition. Deliberately NOT changed: `.okf/log.md` still records what was believed at the time. That file's stated contract is "records what changed, not what is true" - rewriting dated history to match current belief would make it useless as an audit trail. The concepts carry current truth; the log carries the sequence. okf validate --strict conformant; bin/hugo-build clean. 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 |
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.
Bundle-only sync following the #519 review rounds, plus two integrity fixes that
took several passes to get right.
Lifted into concepts
review-swarm.md— a correction is an edit, and it can break what the filealready held; sweep a corrected metric through the canonical summaries, not
just its home; budget more than one review round for docs.
analytics-access.md— cut a measurement window on the deploy, not themerge. Pages publishes from a separate run that can lag or fail.
Timestamp integrity
Every OKF stamp written this session was local time carrying a
Zsuffix —18 literals across 9 concepts, ~2h in the future. That matters here
specifically:
.okf/index.mdresolves concurrent-edit conflicts by taking thelater timestamp, so a future-dated stamp silently outranks genuinely newer
work from a parallel session.
Getting this right took three attempts, and the failures are instructive:
-2h— correct for the shell offset, but the repo's commits carry+03:00, and more importantly the original local times were invented roundnumbers, so no offset recovers truth from them.
destroyed what
verified:exists for: three distinct checks became threeidentical entries.
git show 8fa41494:.okf/build/test-gates.mdshows which entries existed atFix 553 pages previewing blank on social, and the gate that would have caught it #516; the two later ones trace to
67bdd78e(21:43:35Z) and6c4b7aba(21:47:30Z). Every stamp is now defensible by a command anyone can re-run.
The rule recorded alongside: convert with the offset the stamp was written
at, or mark it unknown — never overwrite history with now.
Deploy-state integrity
#487/#494merge times were treated as proof the 08-18→20 Clarity windowwas contaminated. A merge is not a release. The conclusion is now conditional
everywhere it appears — concept, baseline record, README, plan, and both phase
specs — with the restore condition stated: if the deploy landed after 08-20,
the excluded 292 sessions come back.
.okf/log.mdis deliberately unchanged. Its stated contract is "records whatchanged, not what is true"; rewriting dated history to match current belief
would destroy its value as an audit trail.
Gates
okf validate --strictconformant, no warnings on any edited concept.bin/hugo-buildclean. No stamp ahead of the verified clock. Bundle + docs only— no code, templates, or CSS.
🤖 Generated with Claude Code