anvil-dev-framework 0.1.6

package/docs/specifications/SPEC-ANV-context-checkpoints.md

@@ -0,0 +1,781 @@
+---
+spec_id: SPEC-ANV-CCS
+title: Context Checkpoint System - Intelligent Context Preservation
+status: draft
+created: 2026-01-07
+updated: 2026-01-07
+linear_issue: TBD
+---
+
+# Context Checkpoint System (CCS)
+
+## Overview
+
+Replace Claude Code's auto-compact with an intelligent, proactive context preservation system. CCS monitors context usage, estimates task scope, triggers structured handoffs at optimal breakpoints, and integrates with Linear for task-oriented session continuity.
+
+## Problem Statement
+
+Claude Code's auto-compact has significant limitations:
+
+1. **Reactive, not proactive** - Triggers at ~95% usage, leaving no room for graceful handoff
+2. **Lossy summarization** - Forgets CLAUDE.md instructions, tool configurations, learned patterns
+3. **No task awareness** - Compacts mid-task without regard for logical breakpoints
+4. **No scope estimation** - Starts tasks that will inevitably exceed context
+5. **Poor continuation** - Next session lacks structured context to resume effectively
+
+**Evidence from research:**
+- Multiple GitHub issues (#6689, #12053) request disabling auto-compact
+- Users report Claude "forgets" project rules after compaction
+- Disabling recovers ~22.5% context but sessions end abruptly
+- Manual compaction at strategic points is the recommended workaround
+
+## Goals
+
+1. **Proactive Monitoring** - Alert before hitting limits, not after
+2. **Task-Aware Checkpoints** - Align context boundaries with logical work boundaries
+3. **Zero-Loss Handoff** - Preserve all critical context through structured documents
+4. **Scope Estimation** - Predict and prevent context overruns
+5. **Linear Integration** - Tie checkpoints to issue lifecycle for seamless continuation
+
+---
+
+## Design Principles
+
+### Principle 1: Proactive Over Reactive
+
+Trigger checkpoints based on trajectory, not just current position:
+
+```
+Context at 60% + large task ahead → Initiate handoff at 70%
+Context at 80% + small task remaining → Complete then handoff
+Context at 90% + any task → Emergency handoff immediately
+```
+
+### Principle 2: Task-Oriented Checkpoints
+
+Checkpoints should align with natural work boundaries:
+
+| Good Checkpoint | Bad Checkpoint |
+|-----------------|----------------|
+| After completing Linear issue | Mid-function implementation |
+| After passing tests | During debugging |
+| After PR creation | During code review response |
+| Between sharded sub-tasks | In the middle of a shard |
+
+### Principle 3: Hierarchical Context Preservation
+
+Different context types need different preservation strategies:
+
+| Layer | Content | Preservation |
+|-------|---------|--------------|
+| **Permanent** | CLAUDE.md, constitution | Always loaded (never summarized) |
+| **Session** | Current task, decisions, blockers | Captured in handoff document |
+| **Working** | Current file contents, recent edits | Git diff, uncommitted changes |
+| **Ephemeral** | Tool outputs, search results | Summarize key findings only |
+
+### Principle 4: Sharding for Prevention
+
+Break large tasks before they exceed context, not after:
+
+| Estimated Size | Action |
+|----------------|--------|
+| <30% context | Execute normally |
+| 30-60% context | Consider sharding |
+| >60% context | Must shard before starting |
+
+### Principle 5: Structured Handoff Over Summarization
+
+Replace lossy auto-summarization with structured handoff documents:
+
+| Auto-Compact | CCS Handoff |
+|--------------|-------------|
+| Lossy summary | Structured markdown |
+| Forgets instructions | References CLAUDE.md explicitly |
+| No file tracking | Git status + modified files |
+| No task context | Linear issue + progress state |
+| No continuation path | Explicit next steps |
+
+---
+
+## System Architecture
+
+### Components
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Context Checkpoint System                 │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐   │
+│  │   MONITOR     │  │   ESTIMATOR   │  │   HANDLER     │   │
+│  │               │  │               │  │               │   │
+│  │ - Poll context│  │ - Task sizing │  │ - L1: Warning │   │
+│  │ - Track trend │  │ - Scope check │  │ - L2: Handoff │   │
+│  │ - Emit alerts │  │ - Shard hints │  │ - L3: Emergency│  │
+│  └───────┬───────┘  └───────┬───────┘  └───────┬───────┘   │
+│          │                  │                  │            │
+│          └──────────────────┼──────────────────┘            │
+│                             │                               │
+│                    ┌────────▼────────┐                      │
+│                    │   ORCHESTRATOR  │                      │
+│                    │                 │                      │
+│                    │ - Decision logic│                      │
+│                    │ - Linear sync   │                      │
+│                    │ - Handoff flow  │                      │
+│                    └────────┬────────┘                      │
+│                             │                               │
+│          ┌──────────────────┼──────────────────┐            │
+│          │                  │                  │            │
+│  ┌───────▼───────┐  ┌───────▼───────┐  ┌───────▼───────┐   │
+│  │   HANDOFF     │  │   SHARD       │  │   LINEAR      │   │
+│  │   GENERATOR   │  │   MANAGER     │  │   INTEGRATION │   │
+│  │               │  │               │  │               │   │
+│  │ Structured doc│  │ Break tasks   │  │ Issue state   │   │
+│  └───────────────┘  └───────────────┘  └───────────────┘   │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Context Threshold Levels
+
+| Level | Threshold | State | Action |
+|-------|-----------|-------|--------|
+| L0 | 0-69% | Normal | Continue work, no alerts |
+| L1 | 70-84% | Warning | Alert + prepare for handoff |
+| L2 | 85-94% | Critical | Initiate handoff sequence |
+| L3 | 95%+ | Emergency | Force immediate handoff |
+
+### Hook Integration Points
+
+| Hook | Purpose |
+|------|---------|
+| `PostToolUse` | Monitor context after each tool call |
+| `PreCompact` | Intercept auto-compact, run CCS handoff instead |
+| `SessionStart` | Load handoff context if resuming |
+| `Stop` | Prompt handoff if context > 50% |
+
+---
+
+## Requirements
+
+### Context Monitor
+
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| MON-001 | Poll context percentage from statusline data | P0 |
+| MON-002 | Track context growth rate (tokens/minute) | P1 |
+| MON-003 | Predict time-to-threshold based on trend | P1 |
+| MON-004 | Emit alerts at L1, L2, L3 thresholds | P0 |
+| MON-005 | Cache polling to avoid overhead (<100ms) | P2 |
+
+### Task Estimator
+
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| EST-001 | Estimate task size from spec/plan | P1 |
+| EST-002 | Warn if estimated size > remaining context | P0 |
+| EST-003 | Suggest sharding for oversized tasks | P1 |
+| EST-004 | Learn from actual vs. estimated for future accuracy | P2 |
+
+### Checkpoint Handler
+
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| CHK-001 | L1: Display warning in statusline | P0 |
+| CHK-002 | L1: Recommend completing current task | P1 |
+| CHK-003 | L2: Initiate handoff generation | P0 |
+| CHK-004 | L2: Commit WIP if uncommitted changes | P0 |
+| CHK-005 | L3: Force handoff with max preservation | P0 |
+| CHK-006 | L3: Update Linear issue with checkpoint note | P1 |
+
+### Handoff Generator
+
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| HND-001 | Generate structured handoff document | P0 |
+| HND-002 | Include git status and modified files | P0 |
+| HND-003 | Include Linear issue state and progress | P0 |
+| HND-004 | Include explicit next steps | P0 |
+| HND-005 | Reference CLAUDE.md sections to reload | P1 |
+| HND-006 | Summarize decisions made this session | P1 |
+
+### Shard Manager
+
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| SHD-001 | Integrate with existing `/shard` command | P1 |
+| SHD-002 | Auto-suggest sharding when task > 60% context | P1 |
+| SHD-003 | Create sub-issues in Linear for shards | P1 |
+| SHD-004 | Track shard progress in parent issue | P2 |
+
+### Linear Integration
+
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| LIN-001 | Update issue status on checkpoint | P0 |
+| LIN-002 | Add checkpoint comment with handoff reference | P1 |
+| LIN-003 | Link handoff document in issue | P1 |
+| LIN-004 | Set "context-checkpointed" label | P2 |
+
+---
+
+## User Interface
+
+### Statusline Integration
+
+Enhance existing statusline with checkpoint awareness:
+
+```
+Before (current):
+[CTX: ████████░░ 82%] [ISSUE: ANV-123] [PHASE: IMPL]
+
+After (with CCS):
+[CTX: ████████░░ 82% ⚠️ L2] [ISSUE: ANV-123] [PHASE: IMPL] [CKPT: Ready]
+```
+
+### Alert Messages
+
+**L1 Warning (70%):**
+```
+⚠️ Context at 70% - Consider completing current task before starting new work.
+   Run `/handoff` to checkpoint, or continue if task is nearly complete.
+```
+
+**L2 Critical (85%):**
+```
+🔶 Context at 85% - Initiating checkpoint sequence.
+   Completing current edit, then generating handoff document.
+   Linear issue ANV-123 will be updated with progress.
+```
+
+**L3 Emergency (95%):**
+```
+🔴 Context at 95% - Emergency checkpoint!
+   Committing WIP changes and generating handoff NOW.
+   Next session should run `/orient` to continue.
+```
+
+### Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/checkpoint` | Manual checkpoint at current state |
+| `/checkpoint --estimate [task]` | Estimate if task fits in remaining context |
+| `/checkpoint --status` | Show current context state and recommendation |
+
+---
+
+## Data Model
+
+### Checkpoint State
+
+Stored in `.claude/checkpoint-state.json`:
+
+```json
+{
+  "version": "1.0.0",
+  "sessionId": "abc123",
+  "startedAt": "2026-01-07T11:00:00Z",
+  "currentLevel": "L1",
+  "contextPercent": 72,
+  "contextTrend": "increasing",
+  "tokensPerMinute": 850,
+  "estimatedTimeToL2": "15m",
+  "linearIssue": "ANV-123",
+  "lastCheckpoint": {
+    "timestamp": "2026-01-07T10:45:00Z",
+    "handoffFile": ".claude/handoffs/2026-01-07-1045.md",
+    "reason": "manual"
+  },
+  "uncommittedChanges": true,
+  "modifiedFiles": [
+    "src/components/Feature.tsx",
+    "src/services/api.ts"
+  ]
+}
+```
+
+### Handoff Document Enhancement
+
+Extend existing `/handoff` format with CCS metadata:
+
+```markdown
+---
+session_date: 2026-01-07
+session_time: 11:45
+branch: feature/ANV-123-new-feature
+linear_issues: ANV-123
+checkpoint_trigger: L2 (context at 86%)
+context_at_checkpoint: 86%
+---
+
+# Session Handoff: ANV-123 Feature Implementation
+
+## Checkpoint Reason
+Context reached 86% (L2 threshold) during implementation of UserProfile component.
+
+## Context to Reload
+- **CLAUDE.md**: Sections 2.3 (Error Handling), 4.1 (File Conventions)
+- **Active Spec**: .claude/specs/current/SPEC-ANV-123.md
+
+## Remaining Context Budget
+Estimated 14% (~28,000 tokens) remaining in original session.
+
+... (rest of standard handoff format)
+```
+
+---
+
+## Acceptance Criteria
+
+### Scenario: L1 Warning Alert
+
+```gherkin
+GIVEN context usage is at 68%
+AND agent is working on task ANV-123
+WHEN context crosses 70%
+THEN statusline displays L1 warning indicator
+AND agent receives alert message recommending task completion
+AND no automatic action is taken
+```
+
+### Scenario: L2 Handoff Initiation
+
+```gherkin
+GIVEN context usage is at 84%
+AND agent has uncommitted changes
+WHEN context crosses 85%
+THEN agent completes current edit (max 1 minute)
+AND WIP commit is created with message "[WIP] ANV-123 - checkpoint"
+AND handoff document is generated
+AND Linear issue is updated with checkpoint comment
+AND agent suggests resumption command for next session
+```
+
+### Scenario: Task Estimation Warning
+
+```gherkin
+GIVEN context usage is at 55%
+AND user requests new task from spec
+WHEN estimated task size is 50% of total context
+THEN agent warns that task may exceed remaining context
+AND suggests sharding or checkpointing first
+AND provides option to proceed anyway
+```
+
+### Scenario: Shard Suggestion
+
+```gherkin
+GIVEN spec file has estimated size of 70% context
+WHEN agent prepares to implement spec
+THEN agent automatically suggests sharding
+AND provides breakdown into 3 smaller shards
+AND offers to create Linear sub-issues for each shard
+```
+
+### Scenario: Session Resume
+
+```gherkin
+GIVEN previous session ended with L2 checkpoint
+AND handoff document exists at .claude/handoffs/2026-01-07-1045.md
+WHEN new session starts with `/orient`
+THEN handoff document is loaded
+AND key context is summarized for agent
+AND Linear issue state is displayed
+AND explicit next steps are presented
+```
+
+---
+
+## Implementation Phases
+
+### Phase 1: Monitoring Foundation (P0)
+
+1. Enhance statusline hook to emit context alerts
+2. Add L1/L2/L3 visual indicators
+3. Create checkpoint-state.json tracking
+4. Integrate with existing `/handoff` command
+
+### Phase 2: Proactive Handoff (P0)
+
+1. Implement L2 automatic handoff trigger
+2. Add WIP commit before handoff
+3. Enhance handoff document with CCS metadata
+4. Add Linear issue checkpoint comments
+
+### Phase 3: Task Estimation (P1)
+
+1. Build task size estimator from spec analysis
+2. Add `/checkpoint --estimate` command
+3. Warn when task may exceed remaining context
+4. Learn from actual vs. estimated accuracy
+
+### Phase 4: Shard Integration (P1)
+
+1. Trigger automatic shard suggestions
+2. Create Linear sub-issues for shards
+3. Track shard progress in parent issue
+4. Enable seamless shard-to-shard handoffs
+
+### Phase 5: Intelligence Layer (P2)
+
+1. Predict optimal checkpoint timing
+2. Learn user preferences for checkpoint timing
+3. Suggest task reordering to optimize context usage
+4. Provide session planning recommendations
+
+---
+
+## Out of Scope
+
+- **Disabling auto-compact** - CCS works alongside, not instead of auto-compact initially
+- **Cross-session memory persistence** - Use claude-mem for that, CCS focuses on single session
+- **Multi-agent coordination** - Each agent manages its own context independently
+- **Custom compaction algorithm** - We use structured handoff, not modified summarization
+
+---
+
+## Risks and Mitigations
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Over-aggressive checkpoints interrupt flow | Medium | Allow user to defer L1/L2 for "just one more task" |
+| Estimation inaccuracy wastes context | Medium | Learn from history, start conservative |
+| Linear API failures during checkpoint | High | Queue updates, retry, log locally as fallback |
+| Handoff documents grow too large | Low | Focus on structure over detail, link to specs |
+
+---
+
+## Success Metrics
+
+| Metric | Target |
+|--------|--------|
+| Context lost to auto-compact | Reduce by 80% |
+| Session continuity success rate | >90% successful resumes |
+| Task completion per session | Increase by 20% |
+| Mid-task compaction events | Reduce to <5% of sessions |
+| User-initiated checkpoints | >50% (showing adoption) |
+
+---
+
+## Ralph Wiggum Integration
+
+### Critical Requirement
+
+Ralph Wiggum is a continuous-loop autonomous execution system that WILL hit context limits frequently during overnight runs. CCS must be deeply integrated into Ralph to enable graceful handoffs within and across iterations.
+
+### Two-Level Integration Model
+
+CCS operates at two levels within Ralph:
+
+| Level | Scope | Purpose |
+|-------|-------|---------|
+| **Micro** | Within single iteration | Monitor context during Claude Code session |
+| **Macro** | Across iterations | Pass context state from iteration N to N+1 |
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                  CCS-RALPH INTEGRATION                               │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  ralph-loop.sh (Macro Level)                                        │
+│  ┌────────┐    ┌────────┐    ┌────────┐    ┌────────┐               │
+│  │ Iter 1 │───▶│ Iter 2 │───▶│ Iter 3 │───▶│ Iter N │               │
+│  └────────┘    └────────┘    └────────┘    └────────┘               │
+│       │              │              │              │                 │
+│       ▼              ▼              ▼              ▼                 │
+│  [Checkpoint]   [Resume]      [Resume]      [Complete]               │
+│                                                                     │
+│  Within Each Iteration (Micro Level):                               │
+│  ┌─────────────────────────────────────────────────────────────┐    │
+│  │  Claude Code Session                                         │    │
+│  │  Tool #1 → Tool #2 → ... → Tool #N                           │    │
+│  │    ↓         ↓               ↓                               │    │
+│  │  [20%]     [45%]           [86%] → L2 Checkpoint             │    │
+│  └─────────────────────────────────────────────────────────────┘    │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Ralph State Enhancement
+
+Add to `ralph-state.json`:
+
+```json
+{
+  "context_checkpoint": {
+    "active": true,
+    "level": "L2",
+    "percent_at_checkpoint": 87,
+    "timestamp": "2026-01-07T11:45:00Z",
+    "handoff_file": ".claude/handoffs/2026-01-07-1145.md",
+    "resume_summary": "Implementing OAuth callback handler",
+    "files_in_progress": [
+      {"path": "src/auth/oauth.ts", "lines": "45-120"}
+    ],
+    "current_todo_item": "Implement OAuth callback",
+    "progress_on_item": "70%"
+  },
+  "context_history": [
+    {"iteration": 1, "peak_percent": 45, "checkpoint": false},
+    {"iteration": 2, "peak_percent": 88, "checkpoint": true}
+  ]
+}
+```
+
+### Ralph-Specific Requirements
+
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| RLP-001 | Add `context_checkpoint` fields to ralph-state.json | P0 |
+| RLP-002 | Create `ralph_context_monitor.py` PostToolUse hook | P0 |
+| RLP-003 | Enhance `ralph_stop.sh` with CCS checkpoint handling | P0 |
+| RLP-004 | Regenerate PROMPT.md with resume context on checkpoint | P0 |
+| RLP-005 | Track context history across iterations | P1 |
+| RLP-006 | Estimate context per TODO item before starting | P1 |
+| RLP-007 | Add `/ralph context` status command | P1 |
+| RLP-008 | Add `/ralph checkpoint` manual checkpoint command | P1 |
+
+### Checkpoint Flow Within Ralph
+
+```
+Iteration N at 85% context (L2 threshold)
+│
+├── 1. ralph_context_monitor.py detects L2
+│   └── Sets context_checkpoint.active = true
+│
+├── 2. Claude completes current edit (max 60s)
+│
+├── 3. CCS generates handoff document
+│   └── .claude/handoffs/YYYY-MM-DD-HHMM.md
+│
+├── 4. WIP commit created
+│   └── "ralph: checkpoint iter N (L2 at 85%)"
+│
+├── 5. Session ends → ralph_stop.sh fires
+│
+├── 6. ralph_stop.sh detects checkpoint
+│   ├── Regenerates PROMPT.md with resume context
+│   └── exit 1 (restart loop)
+│
+└── 7. Iteration N+1 starts with fresh context
+    └── PROMPT.md contains resume instructions
+```
+
+### Enhanced PROMPT.md for Resume
+
+```markdown
+# Task: [Original Task]
+
+## CONTEXT CHECKPOINT RESUME
+
+> This iteration is resuming from a context checkpoint.
+> Previous session hit 87% context (L2 threshold).
+
+### Resume From
+- **File**: src/auth/oauth.ts (lines 45-120)
+- **Item**: Implement OAuth callback (70% complete)
+- **Handoff**: .claude/handoffs/2026-01-07-1145.md
+
+### Instructions
+1. DO NOT restart the task from scratch
+2. Read the handoff document first
+3. Continue from where previous session left off
+```
+
+### Ralph-Specific Success Metrics
+
+| Metric | Target |
+|--------|--------|
+| Context loss per Ralph run | <5% (vs 100% without CCS) |
+| Successful checkpoint resumes | >95% |
+| Iterations per context window | Increase by 30% |
+| Overnight run success rate | >90% (vs ~60% without CCS) |
+
+### Ralph Implementation Phases
+
+**Phase R1: Core Integration (P0)**
+1. Add `context_checkpoint` to ralph-state.json schema
+2. Create `ralph_context_monitor.py` PostToolUse hook
+3. Modify `ralph_stop.sh` to handle CCS checkpoints
+4. Update PROMPT.md generation for resume context
+
+**Phase R2: Automatic Checkpointing (P0)**
+1. Implement L2 automatic checkpoint trigger in Ralph
+2. Generate CCS-enhanced handoff documents
+3. Test full checkpoint → resume cycle
+
+**Phase R3: Context Efficiency (P1)**
+1. Add context budget estimation per TODO item
+2. Recommend subagent delegation for heavy tasks
+3. Add `/ralph context` and `/ralph checkpoint` commands
+
+---
+
+## Claude-Mem Integration
+
+### Overview
+
+Claude-mem is a persistent cross-session memory system already installed in the Anvil framework. Rather than building a separate persistence layer, CCS can leverage claude-mem for session-to-session continuity.
+
+### How Claude-Mem Works
+
+Claude-mem operates through lifecycle hooks that run automatically:
+
+| Hook | When | Purpose |
+|------|------|---------|
+| `SessionStart` | On startup/compact | Loads recent context into session |
+| `UserPromptSubmit` | Each user message | Captures prompts |
+| `PostToolUse` | After every tool call | Creates observations automatically |
+| `Stop` | Session end | Generates session summary |
+| `SessionEnd` | Cleanup | Handles cleanup tasks |
+
+**Key Insight**: Observations are created automatically. When CCS writes a handoff document or updates ralph-state.json, these become searchable observations without any additional code.
+
+### MCP Tools Available
+
+Claude-mem exposes an MCP server with these tools:
+
+| Tool | Purpose |
+|------|---------|
+| `search` | Find observations by query, type, date, concepts, files |
+| `timeline` | Get context around a specific observation ID |
+| `get_recent_context` | Fast retrieval of recent sessions and observations |
+| `get_observation` | Full details for specific observation by ID |
+| `get_batch_observations` | Batch fetch multiple observations |
+
+### Integration Architecture
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                  CCS + CLAUDE-MEM INTEGRATION                      │
+├──────────────────────────────────────────────────────────────────┤
+│                                                                    │
+│  Ralph Iteration N (Context Checkpoint Event):                     │
+│  ┌─────────────────────────────────────────────────────────────┐  │
+│  │ 1. CCS detects L2 threshold (85%)                           │  │
+│  │ 2. Creates handoff doc → Captured as observation #3500      │  │
+│  │ 3. Updates ralph-state.json → Captured as observation #3501 │  │
+│  │ 4. Commits WIP → Captured as observation #3502              │  │
+│  │ 5. Session ends → Stop hook creates session summary         │  │
+│  └─────────────────────────────────────────────────────────────┘  │
+│                               │                                    │
+│                               ▼                                    │
+│  Ralph Iteration N+1 (Session Start):                              │
+│  ┌─────────────────────────────────────────────────────────────┐  │
+│  │ 1. SessionStart hook fires                                   │  │
+│  │ 2. context-hook.js loads recent context (auto)               │  │
+│  │ 3. PROMPT.md uses get_recent_context for checkpoint detail   │  │
+│  │ 4. Claude resumes with full checkpoint context               │  │
+│  └─────────────────────────────────────────────────────────────┘  │
+│                                                                    │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### What Claude-Mem Already Provides
+
+| CCS Need | Claude-Mem Solution |
+|----------|---------------------|
+| Persist checkpoint state | Observations are auto-captured on file writes |
+| Resume context on restart | SessionStart hook provides recent context |
+| Search past checkpoints | `search` with `type=change` or `query=checkpoint` |
+| Timeline of events | `timeline` around checkpoint observation ID |
+| Cross-iteration memory | Automatic via persistent database |
+
+### What CCS Needs to Add
+
+| Addition | Purpose |
+|----------|---------|
+| Structured checkpoint metadata | Ensure checkpoint observations have predictable format |
+| PROMPT.md claude-mem queries | Fetch checkpoint context at iteration start |
+| Checkpoint observation type | Tag observations as `checkpoint` type for filtering |
+
+### Enhanced PROMPT.md for Claude-Mem Resume
+
+```markdown
+# Task: [Original Task]
+
+## CONTEXT CHECKPOINT RESUME
+
+> This iteration is resuming from a context checkpoint.
+> Previous session hit 87% context (L2 threshold).
+
+### Memory Query (Run First)
+
+Use claude-mem to retrieve checkpoint context:
+
+```
+1. Get recent context: mcp__claude-mem-search__get_recent_context(limit=5)
+2. Search checkpoints: mcp__claude-mem-search__search(query="checkpoint L2", type="observations")
+```
+
+### Resume Instructions
+1. Read the memory search results first
+2. Read the handoff document referenced in results
+3. Continue from where previous session left off
+```
+
+### Progressive Disclosure for Token Efficiency
+
+Claude-mem implements progressive disclosure to minimize token usage:
+
+1. **Index First**: Search returns minimal metadata (~50-100 tokens/result)
+2. **Drill Down**: Full details only for relevant items (~500-1000 tokens/result)
+3. **Batch Fetch**: Get multiple observations in one request
+
+For CCS-Ralph, this means:
+- Iteration starts with ~500-1000 tokens of checkpoint context
+- Full handoff details loaded only when needed
+- 75% token savings vs loading everything upfront
+
+### Claude-Mem Integration Requirements
+
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| MEM-001 | Tag checkpoint observations with `checkpoint` concept | P0 |
+| MEM-002 | Include checkpoint level (L1/L2/L3) in observation title | P0 |
+| MEM-003 | Add PROMPT.md template with claude-mem queries | P0 |
+| MEM-004 | Query `get_recent_context` at iteration start | P1 |
+| MEM-005 | Use `timeline` to understand pre-checkpoint context | P2 |
+| MEM-006 | Search past checkpoints for pattern analysis | P2 |
+
+### Implementation Notes
+
+1. **No Write API Needed**: Claude-mem automatically captures observations via PostToolUse hook. CCS just needs to perform tool calls (write files, git commit) and they become searchable.
+
+2. **SessionStart Already Works**: The existing context-hook.js runs on `startup|clear|compact`, meaning every new Ralph iteration already gets recent context.
+
+3. **Predictable Observation Titles**: CCS should use consistent titles like "Context Checkpoint L2 at 87% - ANV-123" so searches are reliable.
+
+4. **Handoff + Memory = Complete Picture**: The handoff document provides structured detail; claude-mem provides the search/retrieval layer.
+
+---
+
+## Open Questions
+
+1. **Context API**: How does PostToolUse hook get context percentage from Claude Code?
+   - Option A: Environment variable `CLAUDE_CONTEXT_PERCENT`
+   - Option B: Parse from statusline output
+   - Option C: Query internal Claude Code API
+
+2. **Checkpoint granularity**: Checkpoint mid-file or only at file boundaries?
+   - Recommendation: File boundaries when possible, mid-file only at L3
+
+3. **Linear comments**: Append to existing or create separate comments per checkpoint?
+   - Recommendation: Append with iteration prefix
+
+4. **Claude-mem observation type**: Use existing types or create new `checkpoint` type?
+   - Recommendation: Use `change` type with `checkpoint` in concepts for filtering
+
+---
+
+## References
+
+- [GitHub Issue #6689: Request for --no-auto-compact flag](https://github.com/anthropics/claude-code/issues/6689)
+- [GitHub Issue #12053: Disable auto-compact buffer](https://github.com/anthropics/claude-code/issues/12053)
+- [ClaudeLog: Strategic Manual Compacting](https://claudelog.com)
+- Existing Anvil: `global/hooks/statusline.sh`, `global/commands/handoff.md`, `global/commands/shard.md`
+- Ralph System: `global/commands/ralph.md`, `global/lib/ralph_state.py`, `global/tools/ralph-loop.sh`, `global/hooks/ralph_stop.sh`
+- CCS-Ralph Design: `.claude/explorations/2026-01-07-ccs-ralph-integration-design.md`