diff options
Diffstat (limited to 'makima/docs/REQUIREMENTS-resume-history-system.md')
| -rw-r--r-- | makima/docs/REQUIREMENTS-resume-history-system.md | 232 |
1 files changed, 232 insertions, 0 deletions
diff --git a/makima/docs/REQUIREMENTS-resume-history-system.md b/makima/docs/REQUIREMENTS-resume-history-system.md new file mode 100644 index 0000000..3a7cac9 --- /dev/null +++ b/makima/docs/REQUIREMENTS-resume-history-system.md @@ -0,0 +1,232 @@ +# 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 |