Continuity Ledger

Continuity Ledger

Maintain a ledger file that survives /clear for long-running sessions. Unlike handoffs (cross-session), ledgers preserve state within a session.

Why clear instead of compact? Each compaction is lossy compression - after several compactions, you're working with degraded context. Clearing + loading the ledger gives you fresh context with full signal.

When to Use

• Before running /clear
• Context usage approaching 70%+
• Multi-day implementations
• Complex refactors you pick up/put down
• Any session expected to hit 85%+ context

When NOT to Use

• Quick tasks (< 30 min)
• Simple bug fixes
• Single-file changes
• Already using handoffs for cross-session transfer

Ledger Location

Ledgers are stored in: $PROJECT_ROOT/.ring/ledgers/ Format: CONTINUITY-<session-name>.md

Use kebab-case for session name (e.g., auth-refactor, api-migration)

Process

1. Determine Ledger File

Check if a ledger already exists:

ls "$PROJECT_ROOT/.ring/ledgers/CONTINUITY-"*.md 2>/dev/null

• If exists: Update the existing ledger
• If not: Create new file with the template below

2. Create/Update Ledger

REQUIRED SECTIONS (all must be present):

# Session: <name>
Updated: <ISO timestamp>

## Goal
<Success criteria - what does "done" look like?>

## Constraints
<Tech requirements, patterns to follow, things to avoid>

## Key Decisions
<Choices made with brief rationale>
- Decision 1: Chose X over Y because...
- Decision 2: ...

## State
- Done:
  - [x] Phase 1: <completed phase>
  - [x] Phase 2: <completed phase>
- Now: [->] Phase 3: <current focus - ONE thing only>
- Next:
  - [ ] Phase 4: <queued item>
  - [ ] Phase 5: <queued item>

## Open Questions
- UNCONFIRMED: <things needing verification after clear>
- UNCONFIRMED: <assumptions that should be validated>

## Working Set
<Active files, branch, test commands>
- Branch: `feature/xyz`
- Key files: `src/auth/`, `tests/auth/`
- Test cmd: `npm test -- --grep auth`
- Build cmd: `npm run build`

3. Checkbox States

Why checkboxes in files: TodoWrite survives compaction, but the understanding around those todos degrades each time context is compressed. File-based checkboxes are never compressed - full fidelity preserved.

4. Real-Time Update Rule (MANDATORY)

⛔ HARD GATE: Update ledger IMMEDIATELY after completing ANY phase.

You (the AI) are the one doing the work. You know exactly when:

• A phase is complete
• A decision is made
• An open question is resolved

There is NO excuse to wait for the user to ask. This is the same discipline as TodoWrite - update in real-time.

Anti-Rationalization:

5. Update Guidelines

When to update the ledger:

• IMMEDIATELY after completing a phase (MANDATORY - see above)
• Session start: Read and refresh
• After major decisions
• Before /clear
• At natural breakpoints
• When context usage >70%

What to update:

• Move completed items from "Now" to "Done" (change [->] to [x])
• Update "Now" with current focus
• Add new decisions as they're made
• Mark items as UNCONFIRMED if uncertain
• Add Status: COMPLETED when all phases done

6. After Clear Recovery

When resuming after /clear:

1. Ledger loads automatically (SessionStart hook)
2. Find [->] marker to see current phase
3. Review UNCONFIRMED items
4. Ask 1-3 targeted questions to validate assumptions
5. Update ledger with clarifications
6. Continue work with fresh context

Template Response

After creating/updating the ledger, respond:

Continuity ledger updated: .ring/ledgers/CONTINUITY-<name>.md

Current state:
- Done: <summary of completed phases>
- Now: <current focus>
- Next: <upcoming phases>

Ready for /clear - ledger will reload on resume.

UNCONFIRMED Prefix

Mark uncertain items explicitly:

## Open Questions
- UNCONFIRMED: Does the auth middleware need updating?
- UNCONFIRMED: Are we using v2 or v3 of the API?

After /clear, these prompt you to verify before proceeding.

Comparison with Other Tools

Example

# Session: auth-refactor
Updated: 2025-01-15T14:30:00Z

## Goal
Replace JWT auth with session-based auth. Done when all tests pass and no JWT imports remain.

## Constraints
- Must maintain backward compat for 2 weeks (migration period)
- Use existing Redis for session storage
- No new dependencies

## Key Decisions
- Session tokens: UUID v4 (simpler than signed tokens for our use case)
- Storage: Redis with 24h TTL (matches current JWT expiry)
- Migration: Dual-auth period, feature flag controlled

## State
- Done:
  - [x] Phase 1: Session model
  - [x] Phase 2: Redis integration
  - [x] Phase 3: Login endpoint
- Now: [->] Phase 4: Logout endpoint and session invalidation
- Next:
  - [ ] Phase 5: Middleware swap
  - [ ] Phase 6: Remove JWT
  - [ ] Phase 7: Update tests

## Open Questions
- UNCONFIRMED: Does rate limiter need session awareness?

## Working Set
- Branch: `feature/session-auth`
- Key files: `src/auth/session.ts`, `src/middleware/auth.ts`
- Test cmd: `npm test -- --grep session`

Additional Notes

• Keep it concise - Brevity matters for context
• One "Now" item - Forces focus, prevents sprawl
• UNCONFIRMED prefix - Signals what to verify after clear
• Update frequently - Stale ledgers lose value quickly
• Clear > compact - Fresh context beats degraded context