avizmarlon/ledger-auto-updates

Ledger Auto-Updates — Automatic Session Closure with Living Documentation

Ledger updates (CHANGELOG + session-handoff or project equivalents) are part of session closure — not a manual decision tree, and not something the user should have to request. If the user had to ask "should we update the ledger?", the agent failed.

Principle

The agent detects session-end conditions and automatically updates the project's living documentation to reflect:

1. What changed during this session (CHANGELOG entry)
2. State for the next agent picking up the work (session-handoff entry)

This ensures continuity across multiple AI-agent sessions without explicit handoff ceremony each time.

Triggers — Update without asking when you detect:

• Farewell signals: natural language indicating the session is ending (e.g., "thanks, see you later", "that's all for now", "wrapping up", "good night")
• Explicit wrap-up request: user says "close the session", "prepare for next phase", "create handoff", "open new session"
• Clear topic pivot: moving to an unrelated topic after completing a coherent block of work (e.g., finished a bugfix phase, now asking about a different project)
• User explicitly asks about the ledger: "Should we update CHANGELOG/handoff?" or similar. If they're asking, you missed the trigger. Update immediately and acknowledge the miss.
• Session running long: approaching context limit (>50% full) with substantive work completed
• Before declaring work complete: any message framing closure ("all set", "ready for next session", "finished") must be preceded by ledger updates

Criterion: What counts as "substantive work"

Update the ledger if ANY of these happened:

• Code merged into main branch (commit, PR, or direct push)
• Non-trivial architectural or product decision made
• Bug root cause identified and fixed, with a reusable lesson for other teams
• Changes to rules, instructions, or multi-tool agent configuration
• Significant debugging session that produced a new finding or pattern
• Repository state changed meaningfully (deleted worktrees, removed stale branches, refactoring)
• New tool, wrapper, script, or reusable helper created
• Configuration, MCP setup, or credentials changed in a way that affects workflow

Do NOT update (negative cases):

• Pure exploration or discussion ("how does X work?", "what are your thoughts on Y?")
• Only reading/searching without making changes
• Routine single-issue support that has no impact on the project as a whole

Required Actions at Trigger

When a trigger is detected:

1. Update CHANGELOG.md (or project equivalent):

• Add a new entry at the top
• Follow the project's existing format (semantic versioning, conventional commits, or whatever is already in use)
• Include: what changed, why it matters, and affected files/modules

1. Update session-handoff.md (or equivalent):

• Add a new entry at the top with timestamp
• Record: final repository state, any pending decisions for the next session, non-obvious learnings for the next AI (gotchas, surprising failure modes, commands that failed unexpectedly, paths that don't work)
• This is continuity fuel for a future agent with zero context

1. Commit and push:

• Direct commit to main if it's a solo repository with low-risk changes
• Pull request if the change affects shared code or policy
• Do not wait for user approval — the rule itself grants authority for this action

1. Report to the user:

• 1–2 sentences: "Updated CHANGELOG + session-handoff with [summary]. Commit [sha] pushed."
• No excessive detail; the real content is in the files

Anti-Patterns (Prohibited)

• Waiting for the user to ask: if they're asking "did you update the ledger?", you already failed
• Updating only one document: CHANGELOG and session-handoff serve different purposes (changelog = immutable history; handoff = live context for next agent). Both are required.
• Deferring with "let me propose this first": the ledger update is not a design decision to propose. It is a closure action, already authorized by this rule. (New tooling or rules still require explicit approval under the "permanent learning" rule — but ledger updates do not.)
• Declaring work complete before updating the ledger: e.g., "✅ All done, pushed to main, clean" without having already updated CHANGELOG and handoff. Reorder: ledger first, then closure report.

Detecting a Miss During the Session

If you catch yourself about to report session closure without having updated the ledger:

1. Stop. Do not report closure yet.
2. Update both documents immediately.
3. Then report — no need for apology, just action.

Scope

Applies to: any project using version control (Git, etc.) with a CHANGELOG and/or handoff file as living documentation. Works for all AI agents in all sessions.

Related rules and skills:

• Blind-AI-bootstrap — the principle that every AI must reconstruct full context from durable artifacts. Session-handoff is your contribution to that goal.
• Permanent learning protocol — differs from ledger updates. New rules, tools, and architectural decisions require explicit approval; ledger updates (documenting what happened) do not.
• Git-PR-rules — when to use pull requests vs. direct commits. Ledger updates usually warrant a direct commit to main unless the project requires all changes to go through review.

Example Patterns

Example 1: Feature completion

Session event: User says "Thanks, I think we've got a good foundation here. Chat later!"

Trigger: Farewell signal + coherent block of work completed

Ledger entry (CHANGELOG):

## [Unreleased]

### Added
- New WebSocket event handler for real-time notifications
- Integration test suite covering edge cases in event dispatch

### Changed
- Refactored message queue to use connection pooling for efficiency

Ledger entry (session-handoff):

## Session: 2026-06-14

### Completed
- Implemented WebSocket events, all tests green
- Pushed to `feature/realtime-events` branch

### For next session
- Branch ready to merge after final review
- Watch out: event loop hangs if queue drains before listener reconnects — use backpressure signal (see commit abc1234)

### Appraisal
- Design surface solid; future changes to routing logic might need queue refactor

Example 2: Bug investigation that produced a lesson

Session event: User pivots from the bug investigation to asking about unrelated architecture questions.

Trigger: Clear topic pivot after debugging session

Ledger entry (CHANGELOG):

## [Unreleased]

### Fixed
- Race condition in task scheduler when cancellation arrives during execution
  - Root cause: missing mutex guard in shutdown handler
  - Affected all long-running jobs; very low probability but high impact

### Documentation
- Added concurrency pattern guide to docs/

Ledger entry (session-handoff):

## Session: 2026-06-14

### Completed
- Identified and fixed race in scheduler; added test that catches it deterministically

### Lessons learned
- Shutdown handlers must use the same locking primitive as the main loop — mixing mutexes and atomic flags caused a data race
- The race only shows up under load; normal testing didn't catch it
- See test `test_scheduler_cancel_under_load` for reproduction

### For next sessions
- If you modify shutdown paths, run the full concurrent test suite with stress mode

Example 3: Refactor or cleanup

Session event: User says "I'm going to move on to something else. This cleanup is done."

Trigger: Explicit wrap-up after refactor completion

Ledger entry (CHANGELOG):

## [Unreleased]

### Changed
- Removed deprecated `old_api.ts` module; all consumers migrated to `new_api.ts`
- Flattened worktree structure; deleted stale feature branches

Ledger entry (session-handoff):

## Session: 2026-06-14

### Cleanup completed
- Removed 3 stale branches; deleted unused worktrees
- Deprecated API fully removed; no callers remaining

### For next session
- Repo is clean; no pending structural debt noted

Implementation Tips

1. Build context capture into your hook or startup: at the very start of a session, load and read the existing CHANGELOG and session-handoff so you understand the project's format and recent history.

1. Timestamp entries: include dates in session-handoff entries so future agents know recency and order.

1. Make handoff entries scannable: use clear headers and bullet points. Future agents are busy and will skim.

1. Include the "why" in handoff: not just what happened, but why it matters for the next session and what gotchas to watch.

1. Keep CHANGELOG immutable: once an entry is in CHANGELOG and committed, do not edit it. Session-handoff is the living, mutable record.

1. Link to commits when relevant: "See commit abc1234 for the full diff" gives the next agent a shortcut to understanding.

Validation

Before you claim "ledger updates complete," verify:

• ] CHANGELOG.md exists and has a new entry at the top with this session's changes
• ] session-handoff.md (or equivalent) exists and has a new entry with timestamp, state, and lessons
• ] Both files have been committed and pushed (or are staged, pending user approval if that's the project's workflow)
• ] The user has been notified of the update in 1–2 lines