feat: lean .wolf handoff files — TODO.md, ROADMAP.md, history.md rotation + buglog index

[meketreve]

What & why

A cohesive pass to keep the .wolf files that Claude reads every turn small, so long-lived projects don't pay a growing token tax on each session. On one real project (~130K-line STATUS.md, 200K memory.md, 270K buglog.json) the per-resume + per-fix read cost dropped dramatically with no data loss. Everything is opt-out-safe: existing installs are untouched on upgrade, and every mechanism is a no-op until a file actually grows.

Two commits, one theme.

New managed files

• TODO.md — working checklist (🔥 Now / ⏭️ Next / 💡 Later / ✅ Done), complementing STATUS.md's handoff narrative. create-if-missing, seeded with {{PROJECT_NAME}}/{{DATE}}.
• ROADMAP.md — planned-but-not-active work (milestones, backlog, someday), so STATUS.md stays focused on the current quest. create-if-missing.

Auto-rotation into a shared history.md (Stop hook)

• STATUS.md session journal (> **SESSION N ... / > **SESSÃO N ... blocks) → history.md ## Session Journal, keeping the newest openwolf.status.max_sessions (default 2).
• memory.md chronological ## Session: blocks → history.md ## Action Log, keeping the newest openwolf.memory.max_sessions (default 20). memory.md is oldest-first; handled explicitly.
• Single history.md (name configurable via openwolf.status.archive_file) with both sections, newest-first. No-op unless a file exceeds its keep count.

buglog index + rotation (Stop hook)

• Renders a compact buglog.md (id · tags · file · truncated message) from buglog.json when the source changes. Protocol now says scan buglog.md, then open only the matching entry — never read the whole JSON.
• Rotation: caps live buglog.json at the newest openwolf.buglog.max_entries (default 200); older bugs move to buglog-archive.json (chronological, append-only). Keeps the index small without ever deleting a logged fix.

cerebrum budget nudge

• Reminder (via additionalContext) when cerebrum.md exceeds ~2× openwolf.cerebrum.max_tokens. Not auto-trimmed — it's curated knowledge, so Claude is asked to consolidate by hand (keeping active preferences / Do-Not-Repeat).

Config (all defaulted)

"status":  { "max_sessions": 2, "archive_file": "history.md" },
"memory":  { "max_sessions": 20 },
"todo":    { "enabled": true }

Safety

• All writes are atomic (tmp + rename) — a concurrent Stop hook from another agent/session in the same project can never read a half-written file (validated live with two concurrent Claude sessions).
• Every housekeeping step is wrapped best-effort; a failure never breaks the Stop hook.
• Reminders route through additionalContext (the v2 convention), except the pre-existing STATUS freshness check.

Testing

• tsc -p tsconfig.json and tsc -p tsconfig.hooks.json both clean.
• Fixtures exercise: journal rotation (kept newest N, preamble + live sections preserved), memory rotation (oldest-first eviction, reversed to newest-first in history), buglog index (pipe escaping, truncation), cerebrum nudge, mixed SESSION/SESSÃO markers, empty stdin.
• Applied end-to-end to a real project: STATUS.md 18K→7K tokens, buglog read 68K→13K (index), memory 51K→18K, zero data loss (all rotated blocks accounted for in history.md).

🤖 Generated with Claude Code