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:
gsxdsm
2026-07-31 17:36:20 -07:00
committed by GitHub
parent 40bb621fd8
commit 7acfaf6c10

View File

@@ -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.