docs: move the session history into LOGS.md, record the compaction policy #62

Merged
dsh merged 1 commit from docs/logs-split into master 2026-10-25 00:50:26 +00:00
Owner

What

AGENTS.md had grown to 65 KB, past the workspace instruction budget (it was being truncated for agents), and about half of it was chronological session logs. This splits the two concerns:

  • LOGS.md (new, 31 KB) — the full session history, verbatim: what was broken, what changed, how it was verified. Header says explicitly: README.md is the user manual, AGENTS.md the agent manual, this file the lab notebook.
  • AGENTS.md (38 KB) — keeps the current-state sections (setup, bugs table, settings contract, routes, ground rules, repo map) and replaces the logs with a one-line-per-session index linking to LOGS.md.

Also recorded, per operator decision:

  • Major releases compact the history. Policy paragraph under CI and releases: from 0.9.0, every minor/major squashes the fork commits before the tag; upstream base untouched, v0.8.* tags keep the old shas resolvable, narrative stays in CHANGELOG.md/LOGS.md.
  • Ground rule 5 now spells out the one sanctioned force-push exception (the compaction, with operator approval) so the rule and practice agree.
  • Tracked as #60 in a new 0.9.0 milestone; AGENTS.md points at it as the 0.9.0 dependency.

Verification

  • npm run check: 195 tests, leak scan clean, syntax clean (docs-only change).
  • Content check: LOGS.md starts at the 2026-10-22 session and ends at the 0.8.8 entry; every ## Session log heading from AGENTS.md is present exactly once.
  • AGENTS.md index has 21 rows, oldest first, and the file is 38 KB — comfortably inside the budget.
## What `AGENTS.md` had grown to **65 KB**, past the workspace instruction budget (it was being truncated for agents), and about half of it was chronological session logs. This splits the two concerns: - **`LOGS.md`** (new, 31 KB) — the full session history, verbatim: what was broken, what changed, how it was verified. Header says explicitly: `README.md` is the user manual, `AGENTS.md` the agent manual, this file the lab notebook. - **`AGENTS.md`** (38 KB) — keeps the current-state sections (setup, bugs table, settings contract, routes, ground rules, repo map) and replaces the logs with a **one-line-per-session index** linking to `LOGS.md`. Also recorded, per operator decision: - **Major releases compact the history.** Policy paragraph under *CI and releases*: from 0.9.0, every minor/major squashes the fork commits before the tag; upstream base untouched, `v0.8.*` tags keep the old shas resolvable, narrative stays in `CHANGELOG.md`/`LOGS.md`. - **Ground rule 5** now spells out the one sanctioned force-push exception (the compaction, with operator approval) so the rule and practice agree. - Tracked as **#60** in a new **0.9.0** milestone; `AGENTS.md` points at it as the 0.9.0 dependency. ## Verification - `npm run check`: 195 tests, leak scan clean, syntax clean (docs-only change). - Content check: `LOGS.md` starts at the 2026-10-22 session and ends at the 0.8.8 entry; every `## Session log` heading from `AGENTS.md` is present exactly once. - `AGENTS.md` index has 21 rows, oldest first, and the file is 38 KB — comfortably inside the budget.
AGENTS.md hit the workspace instruction budget (65 KB, half of it
chronological session logs), so the logs move to LOGS.md and AGENTS.md
keeps a one-line-per-session index. AGENTS.md drops to 38 KB, which is
what the next agent actually has to read.

LOGS.md keeps the full history verbatim (what was broken, what changed,
how it was verified) and says explicitly that it is the lab notebook:
README is the user manual, AGENTS is the agent manual.

Also records the release policy the operator asked for: every minor/major
release compacts the fork history, starting with 0.9.0 — tracked as #60
in the 0.9.0 milestone, with the sanctioned force-push exception written
into Ground rule 5 and the release ritual.
dsh merged commit 942d1ee1c2 into master 2026-10-25 00:50:26 +00:00
Sign in to join this conversation.
No description provided.