fix(gate): print the exact UTC stamp when the date gate fails (#3271)

## What

**Three separate commits landed a future-dated FNXC stamp this
evening**, each turning this blocking gate red on main (#3261 fixed six
across five engine files; #3270 fixes a third in core). This makes the
failure message actionable. Tooling only.

The message said *"Use the current date and a real clock time."* That
tells the author to use the value they already believed they had. It now
prints the exact stamp:

```
Current UTC stamp to use: 2026-07-31-23:39
```

Copy-paste instead of a second judgement call, computed only on a path
that has already failed.

## Why a message change rather than a rule

**The offsets are the evidence.** `00:50` against `23:34`; the engine
batch similar — consistently **1–2 hours into tomorrow**, not wrong
dates. That is the shape of a clock or timezone difference, not
carelessness, and no amount of restating the rule fixes a clock.
AGENTS.md already says to take the stamp from `date -u`; three actors
violated it in one evening anyway.

**I am one of those actors** — I have broken this rule twice today. So
this is not a complaint about anyone's diligence; it is an argument that
the instruction is doing less work than a printed value would.

## I made the same mistake inside this change

The FNXC comment documenting the fix was stamped **two minutes ahead**
of the real UTC time. Corrected from `date -u`.

**The gate did not catch it** — it scans `packages/` and not `scripts/`,
so FNXC stamps in the tooling itself are entirely unchecked. That is a
genuine scope gap and I am reporting rather than closing it: pulling
`scripts/` into scope would surface existing stamps across the tooling
and needs its own baseline pass, which does not belong in a message fix.

There is something clarifying about writing a future-dated stamp *in the
fix for future-dated stamps*, in a file the checker cannot see. It is
the same lesson this whole session kept producing — **an instrument's
blind spot is invisible in exactly the way its subject is** — and I
walked into it while holding the flashlight.

```
lint clean; gate prints the stamp on failure
```


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Bug Fixes**
* Improved validation feedback for future-dated entries by showing the
exact UTC timestamp format and value to use when corrections are needed.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
This commit is contained in:
gsxdsm
2026-07-31 17:33:35 -07:00
committed by GitHub
parent 5acd8e987b
commit 40bb621fd8

View File

@@ -58,6 +58,13 @@ keep honest than two.
const STAMP_TIME = /FNXC:[A-Za-z0-9_-]+\s+\d{4}-\d{2}-\d{2}-(\d{2}):(\d{2})/g;
/** Hours 00-23, minutes 00-59. Returns the count of stamps whose clock time cannot exist. */
/** The stamp an author should paste, in the project's `yyyy-MM-dd-HH:mm` form, in UTC. */
function nowStamp() {
const d = new Date();
const p = (n) => String(n).padStart(2, "0");
return `${d.getUTCFullYear()}-${p(d.getUTCMonth() + 1)}-${p(d.getUTCDate())}-${p(d.getUTCHours())}:${p(d.getUTCMinutes())}`;
}
function impossibleClockTimes(source) {
let bad = 0;
STAMP_TIME.lastIndex = 0;
@@ -259,7 +266,20 @@ if (problems.length > 0) {
+ "the FNXC record — the project's why-does-this-exist trail — read out of order. An hour above 23\n"
+ "or a minute above 59 is not a real time at all.\n"
+ "Use the current date and a real clock time. If a count went DOWN, re-record the baseline in the\n"
+ "same commit.\n",
+ "same commit.\n"
/*
FNXC:FnxcDateGate 2026-07-31-23:39:
PRINT THE STAMP TO USE, do not just say "use the current date".
Three separate commits landed a future-dated stamp in one evening, each turning this blocking gate
red on main. The offsets were 1-2 hours, not wrong dates — the shape of a clock or timezone
difference rather than carelessness, and telling that author to "use the current date" is telling
them to use the value they thought they already had.
Printing the exact UTC stamp makes the correction copy-paste instead of a second judgement call.
Cheap: one `date -u`-equivalent read on a path that has already failed.
*/
+ `Current UTC stamp to use: ${nowStamp()}\n`,
);
process.exit(1);
}