diff --git a/docs/AUTONOMOUS-LOOP.md b/docs/AUTONOMOUS-LOOP.md index de5d7599..8fb3479f 100644 --- a/docs/AUTONOMOUS-LOOP.md +++ b/docs/AUTONOMOUS-LOOP.md @@ -252,17 +252,26 @@ exception. human maintainer, round 44 — see step 1). Immediately before stopping, in this exact order: -1. **Append a row to `docs/hygiene-history/loop-tick-history.md`.** +1. **Write a per-tick shard file at + `docs/hygiene-history/ticks/YYYY/MM/DD/HHMMZ.md`** (per task + #276 Option B — adopted 2026-04-29 to eliminate the EOF + append-hotspot conflict surface that arose with the legacy + single-table file). The legacy table at + `docs/hygiene-history/loop-tick-history.md` remains the + canonical READ surface for pre-shard ticks; the shard + directory under `docs/hygiene-history/ticks/` is the + canonical WRITE surface for new ticks. Schema (one row per + shard, same columns as the legacy table) and rationale are + in `docs/hygiene-history/ticks/README.md`. Every tick gets + a shard — a no-op speculative-scan tick still gets a + shard (minimal-density), because the log is the factory's + durable answer to *"is the tick actually running?"* (the + commit log undercounts; chat messages evaporate). Write + the shard BEFORE the `CronList` call so even an + abnormally-stopped tick still leaves evidence it ran. Human maintainer, round 44: *"you might as well right a history record somewhere on every loop tool right before - you check cron"*. The schema and rationale are in the - header of that - file. Every tick gets a row — a no-op speculative-scan - tick still gets a row, because the log is the factory's - durable answer to *"is the tick actually running?"* (the - commit log undercounts; chat messages evaporate). Append - BEFORE the `CronList` call so even an abnormally-stopped - tick still leaves evidence it ran. + you check cron"*. 2. **Call `CronList`.** 3. **If `<>` is present at cadence `* * * * *`:** do nothing to the scheduler — the cron diff --git a/docs/hygiene-history/ticks/README.md b/docs/hygiene-history/ticks/README.md new file mode 100644 index 00000000..03c4e68e --- /dev/null +++ b/docs/hygiene-history/ticks/README.md @@ -0,0 +1,119 @@ +# Tick-history shard files + +This directory holds **per-tick shard files** for autonomous-loop +liveness evidence. One shard per autonomous-loop tick. + +## Why shards exist + +The single end-of-file table at +`docs/hygiene-history/loop-tick-history.md` produced an "Append- +Hotspot Merge Friction" failure mode (named by the deep-research +external-AI reviewer 2026-04-29): every tick-history PR added a +row to the same EOF surface, and parallel in-flight PRs +conflicted with each other, generating recursive maintenance work. + +Per task #276 architectural choice (per-tick shard files — +"Option B"), each tick now writes a unique shard file at: + +``` +docs/hygiene-history/ticks/YYYY/MM/DD/HHMMZ.md +``` + +Per-tick uniqueness eliminates the conflict surface entirely. + +## Shard file schema + +Each shard is a single-row Markdown file. Required first line: + +``` +| | | | | | | +``` + +Same column structure as the legacy single-table format. A +generator script (follow-up work) collates shards into the +legacy table on cadence; until that lands, the legacy table is +the authoritative read surface and shards are the authoritative +write surface — both are canonical. + +## Naming + +``` +docs/hygiene-history/ticks/2026/04/29/0210Z.md +docs/hygiene-history/ticks/2026/04/29/0215Z.md +docs/hygiene-history/ticks/2026/04/30/0900Z.md +``` + +- Year / month / day are zero-padded numeric folders. +- Filename is HHMMZ (zero-padded hour + minute, UTC, with `Z` + suffix). +- Extension `.md` so each shard is independently grep-able and + rendered by the docs viewer. + +If a tick lands within the same minute as a prior tick (rare — +the autonomous-loop cron is `* * * * *`), append `-01`, `-02`, +... to disambiguate: `0215Z-01.md`, `0215Z-02.md`. + +## What goes in a shard + +The same content that previously appended as a row to the legacy +table: + +- Material state-transition ticks → rich shard (multiple + paragraphs covering the transitions + observations) +- Pure-maintenance / no-op ticks → minimal shard (one or two + sentences) + +Per the corrected liveness doctrine (see +`docs/AGENT-BEST-PRACTICES.md` operational standing rules +section "Session-closure rule"): every tick gets a shard. +Density depends on whether material state changes happened. + +## Composition with the legacy table + +For the gap before the generator script lands, the legacy table +at `docs/hygiene-history/loop-tick-history.md` remains the +canonical READ surface for past history, and new shards in this +directory become the canonical WRITE surface for new ticks. + +Future generator behavior: + +```text +Generator (cadence: post-merge or daily): + 1. Read all shards under docs/hygiene-history/ticks/**/*.md + 2. Sort by filename (chronological by file naming) + 3. Format as legacy-table rows + 4. Append to docs/hygiene-history/loop-tick-history.md + 5. Optionally retire shards older than N days to a compressed archive +``` + +The generator is follow-up work tracked under task #276. + +## Why per-tick rather than per-day or per-PR + +- **Per-tick**: each tick writes one file; no collision; no + generator pressure beyond mere collation; smallest write unit. +- Per-day or per-PR would re-introduce append-hotspot inside the + bucket. Per-tick removes the hotspot at the file granularity. + +The choice was made 2026-04-29 per the converged stance from +the multi-AI synthesis arc + Aaron's explicit delegation +(*"this falls under your call"*). + +## What this directory does NOT do + +- Does NOT replace the legacy table for past history (that + remains the canonical READ surface for pre-shard ticks). +- Does NOT change the AUTONOMOUS-LOOP.md liveness invariant — + every tick still gets canonical evidence. +- Does NOT remove the markdownlint / chronological-order checks + — those still apply at the shard-file level. +- Does NOT introduce a new tick-history schema — same column + structure as the legacy table, one row per shard. + +## Migration of historical content + +The legacy table at `docs/hygiene-history/loop-tick-history.md` +is NOT migrated to shard files. Pre-2026-04-29-shard ticks stay +in the legacy table. Post-shard ticks go in shards. The +generator (follow-up) collates shards into the legacy table to +preserve the single-table read experience.