docs(shared): document UTC-format selection rule in autobot_shared.time_utils (#5169 part A) (#5176)

Adds a module docstring with a clear selection rule for picking between
utc_timestamp() (default for new code, +00:00 with microseconds) and
utc_timestamp_z() (legacy compatibility only, Z-suffix, second precision).
Each function docstring now cross-references the module rule.

Body changes: none — docstrings only. Both helpers retain byte-identical
output. Verified via:
  python3 -c "from autobot_shared.time_utils import utc_timestamp, utc_timestamp_z;
              print(utc_timestamp(), '|', utc_timestamp_z())"
  -> 2026-04-18T20:36:03.523477+00:00 | 2026-04-18T20:36:03Z

Part A of #5169. Parts B (parser audit) and C (canonicalization ADR)
deferred to follow-up — issue stays OPEN.

Refs #5169

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mrveiss

autobot_shared/time_utils.py

@@ -1,19 +1,53 @@
-"""Shared time utility helpers."""
+"""Shared UTC timestamp helpers.
+
+This module exposes two helpers for producing the current UTC time as an
+ISO-8601 string. They differ in *output format*; the choice between them
+is dictated by what consumers can parse, not by author preference.
+
+Selection rule (#5106, #5152, #5169)
+------------------------------------
+
+``utc_timestamp()`` — **default for new code.**
+    Returns ``+00:00`` ISO-8601 with microseconds
+    (e.g. ``2026-04-18T19:34:50.123456+00:00``). Use this unless you are
+    reading or writing a stored format that explicitly expects ``Z``.
+
+``utc_timestamp_z()`` — **legacy compatibility only.**
+    Returns ``Z``-suffix ISO-8601 with second precision and no
+    microseconds (e.g. ``2026-04-18T19:34:50Z``). Use ONLY when reading
+    or writing existing on-disk records that already use this format
+    (currently: workflow-version records via
+    ``services/workflow_versioning.py``). **Do not use for new
+    producers** — pick ``utc_timestamp()`` instead so the codebase
+    converges on one canonical format.
+
+Long-term canonicalization (#5169 parts B + C) is deferred pending a
+parser audit; until then both formats coexist and the rule above tells
+new code which to pick.
+"""
 import time
 from datetime import datetime, timezone
 
 
 def utc_timestamp() -> str:
-    """Return the current time as an ISO-8601 UTC timestamp string."""
+    """Return current UTC time as ISO-8601 with ``+00:00`` offset.
+
+    Format: ``YYYY-MM-DDTHH:MM:SS.ffffff+00:00`` (microsecond precision).
+    Default helper for new code — see module docstring for selection rule.
+    """
     return datetime.now(timezone.utc).isoformat()
 
 
 def utc_timestamp_z() -> str:
-    """Return current UTC time as an ISO-8601 string with Z suffix.
+    """Return current UTC time as ISO-8601 with ``Z`` suffix.
+
+    Format: ``YYYY-MM-DDTHH:MM:SSZ`` (exactly 20 chars, second precision,
+    no microseconds, no ``+00:00`` offset). Matches the on-disk format
+    used by workflow_versioning records.
 
-    Produces exactly 20 characters in the form ``YYYY-MM-DDTHH:MM:SSZ``
-    with no microseconds and no ``+00:00`` offset — matching the on-disk
-    format used by workflow_versioning records (#5152).
+    Use ONLY for legacy compatibility — see module docstring for
+    selection rule. Picking this for new producers perpetuates format
+    drift (#5106, #5152, #5169).
     """
     t = time.gmtime()
     return (