path: root/makima/docs/REQUIREMENTS-resume-history-system.md

# Resume and History System - Requirements Document

## 1. Executive Summary

The Resume and History System enables users to view historical conversations, resume interrupted work, and rewind/restore to previous states within the Makima platform. This system is essential for recovering from interruptions, exploring alternative approaches, and maintaining visibility into AI-assisted development activities.

## 2. Functional Requirements

### 2.1 History Viewing (FR-HV)

| ID | Requirement | Priority |
|----|-------------|----------|
| FR-HV-01 | System shall display complete conversation history for contracts across all phases | Must Have |
| FR-HV-02 | System shall display conversation history for individual tasks | Must Have |
| FR-HV-03 | System shall display task output/tool call history with timestamps | Must Have |
| FR-HV-04 | System shall display checkpoint history with git diffs | Must Have |
| FR-HV-05 | System shall provide a unified timeline view of all activities | Should Have |
| FR-HV-06 | System shall support filtering history by phase, event type, and time range | Should Have |
| FR-HV-07 | System shall support pagination for large history datasets | Must Have |
| FR-HV-08 | System shall display supervisor conversation history including spawned tasks | Must Have |

### 2.2 Resume System (FR-RS)

| ID | Requirement | Priority |
|----|-------------|----------|
| FR-RS-01 | System shall resume interrupted supervisor conversations with full context | Must Have |
| FR-RS-02 | System shall resume interrupted task conversations with context | Must Have |
| FR-RS-03 | System shall allow resuming from specific checkpoints | Must Have |
| FR-RS-04 | System shall allow continuing tasks from previous task state (worktree inheritance) | Must Have |
| FR-RS-05 | System shall support multiple resume modes: continue, restart-phase, from-checkpoint | Should Have |
| FR-RS-06 | System shall preserve conversation context during resume operations | Must Have |
| FR-RS-07 | System shall support resuming on different daemons after daemon failures | Must Have |

### 2.3 Rewind/Restore Features (FR-RW)

| ID | Requirement | Priority |
|----|-------------|----------|
| FR-RW-01 | System shall rewind code to any checkpoint (git restore) | Must Have |
| FR-RW-02 | System shall rewind conversation to any point in history | Should Have |
| FR-RW-03 | System shall create new branches from historical points | Must Have |
| FR-RW-04 | System shall fork tasks from any point in history | Should Have |
| FR-RW-05 | System shall preserve current state when rewinding (create branch, stash) | Should Have |
| FR-RW-06 | System shall support rewinding both code and conversation together | Should Have |

### 2.4 Integration Requirements (FR-INT)

| ID | Requirement | Priority |
|----|-------------|----------|
| FR-INT-01 | System shall provide CLI commands for all history/resume/rewind operations | Must Have |
| FR-INT-02 | System shall provide REST API endpoints for frontend integration | Must Have |
| FR-INT-03 | System shall integrate with existing task_checkpoints table | Must Have |
| FR-INT-04 | System shall integrate with existing task_events table | Must Have |
| FR-INT-05 | System shall integrate with existing supervisor_states table | Must Have |
| FR-INT-06 | System shall integrate with existing conversation state in tasks | Must Have |

## 3. Non-Functional Requirements

### 3.1 Performance (NFR-P)

| ID | Requirement | Target |
|----|-------------|--------|
| NFR-P-01 | History queries shall complete within 500ms for up to 1000 entries | 500ms |
| NFR-P-02 | Resume operations shall complete within 5 seconds | 5s |
| NFR-P-03 | Rewind operations shall complete within 10 seconds | 10s |
| NFR-P-04 | Checkpoint diff generation shall complete within 2 seconds | 2s |

### 3.2 Scalability (NFR-S)

| ID | Requirement | Target |
|----|-------------|--------|
| NFR-S-01 | System shall support contracts with 100+ tasks | 100+ tasks |
| NFR-S-02 | System shall support tasks with 1000+ conversation messages | 1000+ messages |
| NFR-S-03 | System shall support checkpoints with 500+ file changes | 500+ files |

### 3.3 Security (NFR-SEC)

| ID | Requirement |
|----|-------------|
| NFR-SEC-01 | All operations shall verify owner_id authorization |
| NFR-SEC-02 | Supervisor operations shall require tool key authentication |
| NFR-SEC-03 | Users shall not access other users' history data |
| NFR-SEC-04 | All rewind operations shall be logged for audit |

### 3.4 Reliability (NFR-R)

| ID | Requirement |
|----|-------------|
| NFR-R-01 | Resume operations shall not lose conversation context |
| NFR-R-02 | Rewind operations shall be atomic (all-or-nothing) |
| NFR-R-03 | System shall handle daemon disconnects gracefully |

## 4. Data Requirements

### 4.1 New Data Entities

#### Conversation Snapshots
- Store conversation state at specific points
- Link to checkpoints for combined code+conversation restore
- Support manual and automatic snapshot creation

#### History Events
- Unified event stream for timeline views
- Include task events, chat messages, checkpoints, phase changes
- Support efficient querying by contract, task, or owner

### 4.2 Data Retention

| Data Type | Retention Period | Notes |
|-----------|-----------------|-------|
| Conversation history | Indefinite | Core to resume functionality |
| Conversation snapshots | 90 days | Configurable by user |
| History events | 1 year | Configurable by user |
| Checkpoint diffs | Indefinite | Git-based, low overhead |

## 5. API Requirements

### 5.1 New Endpoints Required

| Method | Path | Description |
|--------|------|-------------|
| GET | `/contracts/{id}/history` | Contract history timeline |
| GET | `/contracts/{id}/supervisor/conversation` | Supervisor conversation |
| POST | `/contracts/{id}/supervisor/resume` | Resume supervisor |
| POST | `/contracts/{id}/supervisor/conversation/rewind` | Rewind conversation |
| GET | `/mesh/tasks/{id}/conversation` | Task conversation |
| GET | `/mesh/tasks/{id}/checkpoints/{cid}/diff` | Checkpoint diff |
| POST | `/mesh/tasks/{id}/checkpoints/{cid}/resume` | Resume from checkpoint |
| POST | `/mesh/tasks/{id}/checkpoints/{cid}/branch` | Branch from checkpoint |
| POST | `/mesh/tasks/{id}/rewind` | Rewind task code |
| POST | `/mesh/tasks/{id}/fork` | Fork from history |
| GET | `/timeline` | Unified timeline |

### 5.2 Enhanced Existing Endpoints

| Method | Path | Enhancement |
|--------|------|-------------|
| POST | `/mesh/tasks/{id}/continue` | Add resumeMode and contextOptions |
| POST | `/mesh/tasks` | Document checkpoint_sha and continueFromTaskId usage |

## 6. CLI Requirements

### 6.1 New Commands

| Command | Description |
|---------|-------------|
| `makima contract history` | View contract history timeline |
| `makima task history` | View task conversation history |
| `makima task checkpoints` | List task checkpoints |
| `makima task checkpoint-diff` | View checkpoint diff |
| `makima supervisor resume` | Resume interrupted supervisor |
| `makima task resume` | Resume interrupted task |
| `makima task resume-from` | Resume from specific checkpoint |
| `makima task rewind` | Rewind code to checkpoint |
| `makima supervisor rewind-conversation` | Rewind supervisor conversation |
| `makima task fork` | Fork task from historical point |

## 7. User Interface Requirements

### 7.1 Frontend Components

| Component | Description |
|-----------|-------------|
| ContractTimeline | Visual timeline of contract activities |
| ConversationViewer | Display conversation history |
| CheckpointBrowser | Browse and select checkpoints |
| DiffViewer | Display git diffs |
| RewindControls | UI for rewind operations |
| ForkDialog | Modal for forking from history |
| ResumeDialog | Modal for resume options |

### 7.2 Frontend Routes

| Route | Description |
|-------|-------------|
| `/contracts/:id/history` | Contract history page |
| `/contracts/:id/supervisor` | Supervisor conversation view |
| `/tasks/:id/conversation` | Task conversation view |
| `/tasks/:id/checkpoints` | Checkpoint browser |
| `/tasks/:id/checkpoints/:cid` | Checkpoint detail with diff |

## 8. Dependencies

### 8.1 Existing System Dependencies

| Dependency | Usage |
|------------|-------|
| supervisor_states table | Store/retrieve supervisor conversation |
| task_checkpoints table | Git checkpoint tracking |
| task_events table | Task output history |
| tasks.conversation_state | Task conversation context |
| tasks.continue_from_task_id | Worktree inheritance |

### 8.2 External Dependencies

| Dependency | Usage |
|------------|-------|
| Git | Checkpoint restore, branching, diffing |
| PostgreSQL JSONB | Conversation storage and querying |

## 9. Acceptance Criteria Summary

### 9.1 History Viewing
- [ ] User can view complete contract history across all phases
- [ ] User can view task conversation with tool calls
- [ ] User can view checkpoint history with diffs
- [ ] Timeline view shows all activities chronologically
- [ ] Pagination works for large datasets

### 9.2 Resume System
- [ ] Supervisor can be resumed after daemon disconnect
- [ ] Task can be resumed with full conversation context
- [ ] Resume from specific checkpoint works correctly
- [ ] Task continuation preserves worktree state

### 9.3 Rewind/Restore
- [ ] Code can be rewound to any checkpoint
- [ ] Conversation can be rewound to any point
- [ ] Branch can be created from any checkpoint
- [ ] Fork creates new task with correct state
- [ ] Original state can be preserved during rewind

## 10. Out of Scope

The following are explicitly out of scope for the initial implementation:

1. Full-text search within conversation history
2. History comparison/diffing between two points
3. Interactive replay mode
4. History export functionality
5. AI-powered history summaries
6. Cross-user history sharing
7. Real-time history synchronization