From 6dc455a5957bd163cbb20f565dc085038c8f2c81 Mon Sep 17 00:00:00 2001 From: Jonathan Borduas Date: Sun, 23 Aug 2026 15:21:46 +0100 Subject: [PATCH] tools: prefer the timestamp form that CANNOT lie -- iso-strict-local computes the offset #574 landed the normalising form as TZ=UTC ... --date=format-local:%Y-%m-%dT%H:%M:%SZ plus a warning that the trailing Z is a literal. Measured, that warning is carrying two silent failures: TZ=UTC format-local:...%SZ 2026-08-22T01:30:03Z true TZ=Asia/Tokyo same command 2026-08-22T10:30:03Z WRONG TZ=America/Los_Angeles same command 2026-08-21T18:30:03Z WRONG Two of three are well-formed, confidently wrong, and compare cleanly against real UTC. The TZ=UTC prefix is load-bearing, and "remember the prefix" is principle-shaped -- the shape that binds 0 of 5 times here, by this repository's own count. --date=iso-strict-local computes the offset instead of taking it from the format string, so it labels itself: TZ=UTC iso-strict-local 2026-08-22T01:30:03Z TZ=Asia/Tokyo iso-strict-local 2026-08-22T10:30:03+09:00 TZ=America/Los_Angeles iso-strict-local 2026-08-21T18:30:03-07:00 Same answer when TZ is right, visibly different when TZ is wrong instead of silently. This does not remove the need to normalise; it removes the failure mode where you cannot tell that you didn't. That is #573's rule applied to a remedy this repository shipped yesterday: the shape decides whether a rule binds, and a form that cannot produce the wrong output beats a warning not to produce it. Bound stated in the file: one git, one machine, 2026-08-23, re-run before relying on the mode name. Gates: check-orientation 0, check-goal-conformance 0, check-tools-index 0, gate-selftests 0. Filed by ARCHITECT, session c83ecf77. Refs #574, #573, #570. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01RTX4A8KkC9cRRrt17yzjWQ --- tools/README.md | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/tools/README.md b/tools/README.md index 205ac7a..562ec9f 100644 --- a/tools/README.md +++ b/tools/README.md @@ -1185,9 +1185,32 @@ TZ=UTC git log -1 --format=%cd --date=format-local:%Y-%m-%dT%H:%M:%SZ 2fa1a3b ``` ⚠ **`format-local` DOES honour `TZ` — the opposite property from `%cI`, which is the whole reason it -works.** ⛔ **And the trailing `Z` is a LITERAL, not a computed zone: drop the `TZ=UTC` prefix under -`Asia/Tokyo` and it prints `2026-08-22T10:30:03Z`** — well-formed, confidently wrong, and it will -compare cleanly against anything. ★ **The `TZ=UTC` is load-bearing, not decoration.** +works.** ⛔ **But the trailing `Z` is a LITERAL, not a computed zone**, and that makes the whole form +a warning rather than a guarantee: + +``` +TZ=UTC --date=format-local:%Y-%m-%dT%H:%M:%SZ ⇒ 2026-08-22T01:30:03Z ✅ +TZ=Asia/Tokyo same command ⇒ 2026-08-22T10:30:03Z ⛔ +TZ=America/Los_Angeles same command ⇒ 2026-08-21T18:30:03Z ⛔ +``` + +⇒ ⛔ **Two of three are well-formed, confidently wrong, and compare cleanly against real UTC.** The +`TZ=UTC` prefix is load-bearing, and *"remember the prefix"* is **PRINCIPLE-shaped** — the shape that +binds 0 of 5 times in this repository. + +★★ **SO PREFER THE FORM THAT CANNOT LIE.** `--date=iso-strict-local` **COMPUTES** the offset instead +of taking it from your format string, so it labels itself: + +``` +TZ=UTC --date=iso-strict-local ⇒ 2026-08-22T01:30:03Z +TZ=Asia/Tokyo --date=iso-strict-local ⇒ 2026-08-22T10:30:03+09:00 +TZ=America/Los_Angeles --date=iso-strict-local ⇒ 2026-08-21T18:30:03-07:00 +``` + +⇒ ★ **Same answer when `TZ` is right; VISIBLY different when `TZ` is wrong, instead of silently.** +⚠ **This does not remove the need to normalise — it removes the failure mode where you cannot tell +that you didn't.** *(Measured 2026-08-23 on `2fa1a3b`, one git, one machine; re-run before relying +on the mode name.)* ★ **The remedy is TEAMLEAD's and it does not involve a clock:** `git merge-tree --write-tree` → `commit-tree` → `worktree add --detach` → **run the CURRENT gate against the actual merge result** —