docs(agents): date -u is the only rule safe from every timezone — #3277's new instruction inverts it (#3281)
#3277 fixed the gate correctly and I have no argument with the code: `today = max(localToday, utcToday)`, so a stamp is future only if ahead of **both** calendars. That is the right shape for a fleet spread across timezones. It reversed the **authoring rule** along with it, and that part is backwards: > **Write your own local date and a real clock time.** … Do NOT reach for `date -u` Under #3277's own comparison, that reintroduces the failure it just fixed. ## Measured against the merged gate, on current main ``` stamp 2026-08-02 (a UTC+2 author's local date at 22:00 UTC) gate exit=1 REJECTED stamp 2026-08-01 (the same author using date -u) gate exit=0 ACCEPTED ``` Run today, 2026-08-01, with the runner in PDT. Probe file added and removed; tree clean after. ## Why `date -u` is the only safe rule The bound is `max(localToday, utcToday)`, and **UTC only moves forward between writing a stamp and checking it**. So a `date -u` stamp has already been passed by the bound at check time, from every timezone, always. No other rule has that property. Writing your own local date is safe *only if you are not east of UTC*. During a UTC+2 author's evening their local date is already tomorrow in UTC, and the stamp is rejected until UTC catches up hours later — which is exactly the "five reds in two hours" incident #3277 diagnosed. The gate change widens the window enough that CI usually catches up before anyone looks, but "usually, after a delay" is a race, not a rule, and it fails hardest for the authors furthest east. The prior instruction (`date -u`) was correct; what was wrong was its stated *rationale* ("validates against UTC"), which is what I was fixing in #3276 before #3277 landed. This PR keeps #3277's both-directions history — the part that explains why neither naive rule works on its own — and restores the prescription. ## Why not just comment on #3277 It is merged, and AGENTS.md is the file every agent reads before writing a stamp. Leaving the inverted rule in place for a review cycle means every east-of-UTC author in the fleet follows it. Filed as a PR so it can be judged on the measurement rather than on my say-so — if the numbers above are wrong, this should be closed. **Supersedes #3276**, which documented the pre-#3277 mechanism and is now stale. I will close it once this is judged. Docs only; no changeset (AGENTS.md is excluded).
This commit is contained in:
@@ -387,7 +387,8 @@ Note: the embedded main-content views Workflows (`_WorkflowEditorView`), Import
|
||||
|
||||
## FNXC_LOG comments:
|
||||
- Please whenever you're working on a codebase. I want you to add comments describing the date of the change (must be in this format yyyy-MM-dd-hh:mm) and describing the requirements or the change in requirements that made you implement certain functionality.
|
||||
- **Write your own local date and a real clock time.** `check-fnxc-future-dates` accepts a stamp that is not ahead of BOTH the runner's local calendar and UTC, which is what makes it safe for a fleet whose machines sit in different zones. Do NOT reach for `date -u` to satisfy it: this instruction previously said to, back when the gate compared against UTC alone, and following it from a machine EAST of the runner writes tomorrow's date and reddens `main` for everybody else — five separate breakages in two hours on 2026-07-31, all invisible to their authors because `pnpm lint` passed locally. An earlier round of the same defect from the other direction (authors WEST of the runner, whose correct 5pm stamp read as "tomorrow" under a UTC comparison) cost four breakages in one day. Both directions are now accepted; a genuinely invented date — days out rather than hours — still fails. The gate also rejects an impossible clock time, so an hour above 23 or a minute above 59 fails for a different reason.
|
||||
- **Take the timestamp from `date -u`, and use a real clock time.** `check-fnxc-future-dates` accepts a stamp that is not ahead of BOTH the runner's local calendar and UTC (`today = max(localToday, utcToday)`), which is what makes it safe for a fleet whose machines sit in different zones. A `date -u` stamp can never be ahead of that bound — UTC only moves forward between writing and checking — so it passes from every timezone, and it is the only rule with that property. Writing your OWN LOCAL date is safe only if you are not east of UTC: during your evening, an author at UTC+2 has a local date that is already tomorrow in UTC, and that stamp is rejected until UTC catches up hours later. Measured on 2026-08-01: a `2026-08-02` stamp (a UTC+2 author's local date at 22:00 UTC) fails the gate, while the `date -u` stamp of `2026-08-01` passes.
|
||||
- This has now broken `main` from BOTH directions, so neither naive rule is safe on its own. Authors WEST of the runner, whose correct 5pm stamp read as "tomorrow" under a UTC-only comparison, cost four breakages in one day; authors EAST of the runner, writing their own local date, cost five more in two hours on 2026-07-31 — all invisible to their authors because `pnpm lint` passed locally. The gate now accepts both honest cases; a genuinely invented date — days out rather than hours — still fails, and so does an impossible clock time (an hour above 23 or a minute above 59).
|
||||
- I want you to write FNXC:Area-of-product in front of all your comments so they can be grepped.
|
||||
- Most of this should be written as jsdocs but you can add short comments around for the important variables and more complex parts of the codebase.
|
||||
- The idea is to encode the requiements of the system (especially software behavior, UX, and important technical decisions) into the code so it's clearer later why a certain piece of code was written.
|
||||
|
||||
Reference in New Issue
Block a user