From d2e492da663f87f6e02682d05782a6443aa37447 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Tue, 22 Sep 2026 14:44:17 +0530
Subject: [PATCH] docs(curator): trim drops the oldest lines regardless of
 shape

_trim_oldest never parses lines: it drops the OLDEST ones whatever they
are, so 'malformed lines always survive' was false. Reword docstring,
curator.md and the kept test's docstring to the true guarantee: lines in
the retained tail are never rewritten or parsed, so a malformed line there
survives verbatim. No behaviour change.

PROOF: probes/s5_trim_probe.py (cap 4096, malformed first line, 4 fat
appends) -> old malformed survived: False, contradicting the old wording;
the kept test asserts a LAST-line malformed row, which is what the new
wording promises.
---
 tests/tools/test_skill_ledger.py            | 8 +++++---
 tools/skill_ledger.py                       | 7 ++++---
 website/docs/user-guide/features/curator.md | 2 +-
 3 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/tests/tools/test_skill_ledger.py b/tests/tools/test_skill_ledger.py
index 9b3b5de651..561aa4f426 100644
--- a/tests/tools/test_skill_ledger.py
+++ b/tests/tools/test_skill_ledger.py
@@ -651,9 +651,11 @@ def test_auto_compact_triggers_at_threshold(ledger_env, monkeypatch):
 
 def test_trim_oldest_when_still_over_cap(ledger_env, monkeypatch):
     """When compaction alone cannot reach the cap (every entry genuinely
-    differs), the oldest entries are dropped until it fits under the LOW-WATER
-    mark (80% of the cap, so the next append does not immediately re-trigger the
-    sweep) — newest entries survive, malformed lines are kept verbatim."""
+    differs), the oldest lines are dropped — whatever their shape — until the
+    file fits under the LOW-WATER mark (80% of the cap, so the next append does
+    not immediately re-trigger the sweep). The newest entry survives, and lines
+    in the retained tail are never parsed or rewritten: a malformed last line
+    survives verbatim."""
     from tools import skill_ledger
 
     import hermes_cli.config as _cfg
diff --git a/tools/skill_ledger.py b/tools/skill_ledger.py
index d2bb967109..37c2739027 100644
--- a/tools/skill_ledger.py
+++ b/tools/skill_ledger.py
@@ -357,9 +357,10 @@ _TRIM_LOW_WATER = 0.8  # trim target as a fraction of ``skills.ledger_max_bytes`
 
 
 def _trim_oldest(max_bytes: int) -> int:
-    """Rewrite the ledger without its oldest parsed entries until it is at most
-    *max_bytes*; the newest entry always survives, malformed lines are kept verbatim.
-    Returns the number of lines dropped (0 = file untouched)."""
+    """Rewrite the ledger without its oldest lines until it is at most *max_bytes*;
+    the newest entry always survives. Lines in the retained tail are never rewritten
+    or parsed — malformed lines there survive verbatim; trimming drops the oldest
+    lines regardless of shape. Returns the number of lines dropped (0 = untouched)."""
     path = ledger_path()
     raw = _read_ledger("trim skipped")
     if raw is None:
diff --git a/website/docs/user-guide/features/curator.md b/website/docs/user-guide/features/curator.md
index 303dc69184..c2e3f4b29c 100644
--- a/website/docs/user-guide/features/curator.md
+++ b/website/docs/user-guide/features/curator.md
@@ -175,7 +175,7 @@ skills:
   ledger: false
 ```
 
-The file is also size-bounded: once it grows past `skills.ledger_max_bytes` (default 5 MB), the next mutation first rewrites it through the unchanged-file dedup (exactly what `hermes curator ledger --compact` does) and, if genuinely-divergent entries still exceed the cap, drops the oldest ones — the newest entry and any malformed lines always survive, and the sweep frees blobs nothing references anymore. Set it to `0` to keep the ledger append-only forever.
+The file is also size-bounded: once it grows past `skills.ledger_max_bytes` (default 5 MB), the next mutation first rewrites it through the unchanged-file dedup (exactly what `hermes curator ledger --compact` does) and, if genuinely-divergent entries still exceed the cap, drops the oldest ones regardless of shape — the newest entry always survives, lines in the retained tail are never rewritten or parsed (a malformed line there survives verbatim), and the sweep frees blobs nothing references anymore. Set it to `0` to keep the ledger append-only forever.
 
 ```yaml
 skills: