feat: Structured compaction via unified ledger

[vtemian]

Summary

• Remove handoff system entirely (duplicated ledger functionality)
• Add deterministic file operations tracking via tool call interception
• Upgrade ledger to support iterative merging (compaction-style)

Motivation

Based on Factory.ai's structured compaction research, which found that structured summarization with deterministic file tracking retains more useful context than alternatives.

Previously we had three overlapping artifacts:

• Compaction - OpenCode's built-in (opaque, no control)
• Ledger - Session state file
• Handoff - End-of-session document (duplicated ledger)

Now unified into a single improved ledger that serves as both session state and compaction summary.

Changes

Removed: Handoff System

• Deleted handoff-creator.ts and handoff-resumer.ts agents
• Removed references from commander, auto-clear-ledger, artifact indexing
• Removed handoff tables from schema

Added: File Operations Tracker

• New file-ops-tracker.ts hook intercepts read/write/edit tool calls
• Maintains per-session sets of read and modified files
• Deterministic tracking (not LLM-extracted)

Updated: Ledger System

• New format with Progress (Done/In Progress/Blocked) and File Operations sections
• Iterative merging - ledger-creator receives previous ledger + file ops, merges rather than regenerates
• Auto-clear-ledger passes file ops and previous ledger content to ledger-creator

New Ledger Format

# Session: {name}
Updated: {timestamp}

## Goal
## Constraints
## Progress
### Done
### In Progress
### Blocked
## Key Decisions
## Next Steps
## File Operations
### Read
### Modified
## Critical Context

Testing

• 55 tests pass
• Type check passes
• Build succeeds

---

Summary by cubic

Unifies session continuity into a single iterative ledger with deterministic file operation tracking, removing the handoff system. This improves compaction quality, simplifies search/indexing, and auto-updates the ledger when context is near full.

• New Features

  • Iterative ledger updates: merges previous ledger with new state and file ops.
  • Deterministic file ops tracking: intercepts read/write/edit and records Read/Modified in the ledger.
  • Auto-clear flow: passes previous ledger and file ops to ledger-creator, saves the merged ledger, clears context, then reloads the ledger; clears file ops only after update succeeds.
  • Artifact index/search: indexes ledgers (goal/state/decisions plus files_read/files_modified); handoffs excluded.

• Migration

  • Handoff removed: replace any handoff-based flows with the ledger; handoff agents, tables, and docs are gone.
  • Artifact index schema updated: adds files_read/files_modified to ledgers; optional clean rebuild by deleting ~/.config/opencode/artifact-index/context.db.
  • Ledger format changed: “Now” moved to Progress → In Progress; update any consumers that parsed the old fields.

^{Written for commit af987ac. Summary will update on new commits.}

[cubic-dev-ai]

2 issues found across 26 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="src/hooks/auto-clear-ledger.ts">

<violation number="1" location="src/hooks/auto-clear-ledger.ts:108">
P1: File operations are cleared before confirming ledger-creator session was created successfully. If `ledgerSessionID` is undefined (session creation fails), `fileOps` data is lost permanently. Consider moving `getAndClearFileOps` inside the `if (ledgerSessionID)` block, or use `getFileOps` first and only call `clearFileOps` after the ledger-creator successfully processes the data.</violation>
</file>

<file name="tests/hooks/artifact-auto-index-ledger.test.ts">

<violation number="1" location="tests/hooks/artifact-auto-index-ledger.test.ts:4">
P2: Test doesn&#39;t validate parsing behavior - it only checks if certain strings exist in the source code. Consider testing the actual parsing function with sample ledger content to verify correct extraction of file operations.</violation>
</file>

_{Reply to cubic to teach it or ask questions. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 4 files (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="src/hooks/auto-clear-ledger.ts">

<violation number="1" location="src/hooks/auto-clear-ledger.ts:157">
P1: The `clearFileOps` is called even when the ledger-creator polling times out (30 attempts without reaching &quot;idle&quot; status). This contradicts the comment and could cause file operations to be lost if the ledger-creator fails to complete. Consider only clearing when the status successfully reached &quot;idle&quot;.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}