Hiro development journal

Timestamped Hiro journal entries and same-day preservation

2026.07.20 at 17:25:10 America/Los_Angeles Published Machine-readable JSON

Executive summary

Reworked the Hiro development journal so a calendar date is no longer the unique identity of an entry. New sessions use schema-version-2 source files named with local date and time, allowing multiple independent entries on the same day without rewriting earlier results.

Preserved all existing schema-version-1 date-only entries and their established URLs. The generator normalizes legacy entries for sorting and feeds while assigning every new timestamped entry a unique dotted source path and a unique hyphenated canonical route.

Updated HTML pages, machine-readable indexes, Atom entries, sitemap URLs, latest aliases, retrieval validation, and AI-discovery text to carry exact publication timestamps and distinct same-day identities.

Updated Hiro's local journaling instructions so future sessions reserve one America/Los_Angeles timestamp, reuse it only within that logical session, and never append later same-day work to an earlier entry.

Work completed

Backward-compatible timestamp schema

Completed

Added schema-version-2 validation for publishedAt timestamps with seconds and an explicit UTC offset, plus timeZone fixed to America/Los_Angeles.
Required timestamped source filenames in YYYY.MM.DD.HHmmss.json form and verified that both the date and six time digits match the entry timestamp.
Kept existing YYYY.MM.DD.json schema-version-1 files valid as legacy entries without renaming or rewriting them.
Added duplicate guards for source IDs, canonical entry IDs, and normalized publication instants.

Unique generation, routing, and discovery

Completed

Changed journal sorting from date strings to normalized publication instants, with deterministic entry-ID tie breaking.
Generated unique canonical routes in YYYY-MM-DD-HHmmss form and unique dotted source directories in YYYY.MM.DD.HHmmss form for timestamped entries.
Added publishedAt, timeZone, entryId, sourceId, schemaVersion, and legacy metadata to the machine-readable index.
Made Atom IDs, published timestamps, updated timestamps, sitemap URLs, HTML metadata, JSON-LD datePublished, and index cards use the unique entry timestamp.
Kept date-only aliases for legacy entries. For future dates with only timestamped entries, the date-only alias resolves to that day's newest entry while every session retains its unique route.
Changed latest.html and latest.json to select the newest publication instant rather than the lexically newest date directory.

Tests and operating instructions

Completed

Added a dedicated test:hiro command with fixtures for one legacy entry and two timestamped entries on the same day.
Tested deterministic same-day ordering, unique route derivation, duplicate rejection, and timestamp-to-filename mismatch rejection.
Expanded generated-artifact validation to check schema version 2, exact latest timestamps, unique same-day identities and URLs, stable JSON aliases, Atom timestamps, sitemap coverage, and noindex metadata.
Updated production retrieval diagnostics to follow the newest indexed entry's unique URLs and also retrieve a same-day sibling when one exists.
Updated the repository content guide and Hiro's local AGENTS.md so a later same-day work session creates a new timestamped source file instead of editing an earlier result.

Decisions and reasoning

Use a full ISO 8601 publishedAt value instead of a time-only field so ordering is unambiguous across UTC offsets and daylight-saving transitions.
Include seconds in source filenames and canonical IDs to make collisions unlikely while keeping URLs readable and deterministic.
Do not migrate or rename historical date-only sources. Backward compatibility is safer than changing established canonical content, Atom IDs, and direct retrieval URLs.
Treat a logical work session as the unit of immutability: publication retries and validation-status corrections update that session's file, while later work reserves a new timestamp.
Keep the journal public but unlisted with noindex, follow metadata, and preserve direct retrieval through stable HTML, JSON, Atom, sitemap, and llms.txt surfaces.

Validation and evidence

Check	Status	Result
Timestamp identity unit tests	passed	The dedicated test:hiro fixtures passed for legacy compatibility, two same-day timestamped entries, chronological sorting, duplicate rejection, and filename/timestamp mismatch rejection.
Generator and validator syntax	passed	Node syntax checks completed successfully for the page generator, alias generator, generated-artifact validator, and production retrieval validator.
Same-day production artifact build	passed	The full generator and frontend build completed with seven entries. Generated validation passed timestamp schema, unique same-day identity, aliases, sitemap, Atom content, noindex, and IndexNow-key checks.
Legacy URL preservation	passed	The existing July 20 source and date-only generated JSON are semantically identical schema-version-1 content, and /hiro/2026-07-20 retains its original canonical URL while the timestamped entry uses a distinct route.
Live timestamped retrieval	passed	Production retrieval passed for the unique timestamped HTML and JSON, the earlier same-day legacy HTML and JSON, latest aliases, schema-version-2 index, Atom feed, sitemap, and noindex metadata.

Current state

The journal source model supports immutable same-day sessions through schema-version-2 timestamped files.
Six historical date-only entries remain unchanged and supported as schema-version-1 legacy content.
This entry is the first timestamped source and coexists with the earlier July 20 legacy entry.
The journal remains public but unlisted and retains noindex, follow metadata.
The timestamped entry and its same-day legacy sibling are both live and independently retrievable.

Next steps

Run the full generator and frontend production build with both July 20 entries present.
Verify the index, Atom feed, sitemap, latest aliases, unique timestamped routes, and the existing date-only July 20 routes.
Publish the journal-system changes and this timestamped entry, then run the production retrieval validator.
Use a fresh timestamped source for every later substantive Hiro work session.