# Context Composition Redesign Specification

## Overview

Redesign Context Composition in Manual Slop to support sophisticated, layered context management for MMA epics and 1:1 agent discussions. The goal is explicit user control over what context an agent receives at varying granularities.

## Current State

- Files & Media and Context Composition are coupled (flags sync visually)
- Context Composition inherits from Files & Media automatically
- No view presets, limited slice visualization
- No context preview before sending

## Design Goals

1. **Decouple** Files & Media from Context Composition
2. **Context Composition** = curated selection from project whitelist with view modes
3. **File View Presets** = named combinations of sig/def/full/custom for per-file selection
4. **Directory grouping** for compact, scrollable file lists
5. **Slice visualization** with annotation support
6. **Context Presets** = save/load file+view+slices compositions
7. **Context Preview** = show exactly what will be sent to agent

---

## Phase 1: Decoupling + File Stats + View Selection

### 1.1 Files & Media = Project Whitelist

**Purpose:** Define what files exist and belong to the project codebase.

**Behavior:**
- Raw file list with wildcards (existing)
- Does NOT affect Discussion Context directly
- RAG indexing pulls from this list
- Tool access pulls from this list (via tooling permissions)

**UI:**
- File listing with path display
- Add/remove files
- Wildcard patterns for bulk add
- Rescan project for new files

### 1.2 Context Composition = Curated Selection

**Purpose:** Select which files to include in THIS discussion/epic and HOW.

**Behavior:**
- Independent from Files & Media (decoupled)
- User manually adds files FROM the project whitelist
- Or user adds ALL from whitelist then removes unwanted
- Each file has view mode and optional custom slices

**View Modes per file:**
- `full` - raw text (no AST pruning)
- `sig` - signature-only outline (basic)
- `def` - definition outline (includes forwards, full AST)
- `custom` - sig/def + user-defined slices with annotations

**UI Structure:**
```
[Preset Selector: ▼ Default ▼] [+ New] [💾 Save] [🗑 Delete]

[Search/Filter files...]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📁 base/auxiliary/
   ☑ builder.cpp      [View: def ▼] [Inspect] [Slices]
   ☑ allocator.cpp     [View: sig ▼] [Inspect] [Slices]
📁 core/
   ☑ engine.h         [View: full ▼] [Inspect] [Slices]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[Stats Panel]
Files: 3  |  Lines: 1,247  |  AST Elements: 89
```

### 1.3 Directory Grouping

**Compact display:**
- Files grouped by common relative directory prefix
- Directory header collapsible
- Reduces scrolling, eliminates horizontal scroll
- Format: `📁 relative/path/`

### 1.4 File Stats

**Per-file stats display:**
- Line count
- AST element count (functions, classes, structs, etc.)
- View mode indicator

**Aggregate stats for selection:**
- Total files, total lines, total AST elements
- Helps user decide: "should I just inject full text or curate?"

---

## Phase 2: Slice Visualization + Annotations

### 2.1 Slice Inspector (replaces Inspect button)

**Purpose:** Visualize and edit slices for a file.

**Opens as popup/modal showing:**
- Full file content with line numbers
- AST-derived slices highlighted (sig elements, def elements)
- User custom slices with annotations
- Line range indicators for each slice

**Slice types:**
- `sig` - AST signature elements
- `def` - AST definition elements
- `custom` - user-defined line ranges with optional tag/comment

**Annotation support:**
- Each custom slice can have:
  - `tag` - category label (e.g., "performance", "bug", "api")
  - `comment` - free-text explanation for agent

### 2.2 View Presets

**Named combinations of view settings:**
- Preset defines default view mode + default slices for a file type
- Example: "Debug View" = full text + custom slice at error-prone lines
- Example: "API Surface" = sig + custom slices for public API functions

**Behavior:**
- Select preset for a file → auto-fills view mode + common slices
- User can override after selecting preset
- Presets are project-scoped (saved in project config)

---

## Phase 3: Context Presets

### 3.1 Save/Load Context Presets

**Context Preset contains:**
- List of files with:
  - Relative path
  - View mode (full/sig/def/custom)
  - Custom slices with line ranges, tags, comments
- Preset name
- Preset description (optional)

**Save behavior:**
- Validate all files exist in project
- If file missing: warn user, offer to:
  - Save without missing files
  - Cancel and resolve manually
- Save to project config (project_context_presets.toml)

**Load behavior:**
- On preset select, Context Composition populates with saved state
- If file from preset is missing: highlight in red, warn
- User can remove missing or attempt to re-path

### 3.2 Context Preview

**Before sending to agent:**
- Show exactly what will be composed
- For each file, show:
  - Which view mode applied
  - Line ranges included
  - Tags/comments visible to agent
  - Total token estimate

**Preview modes:**
- Collapsed (just file list + view modes)
- Expanded (show actual text/slices that will be sent)

---

## Data Models

### FileViewPreset
```python
@dataclass
class FileViewPreset:
    name: str
    description: str
    view_mode: str  # "full" | "sig" | "def" | "custom"
    default_slices: list[dict]  # [{start_line, end_line, tag, comment}]
```

### ContextPreset
```python
@dataclass
class ContextPreset:
    name: str
    description: str
    files: list[ContextFileEntry]

@dataclass
class ContextFileEntry:
    relative_path: str  # relative to project root
    view_mode: str
    custom_slices: list[dict]  # [{start_line, end_line, tag, comment}]
```

---

## UX Flows

### Adding Files to Context Composition

1. User clicks "Add Files" in Context Composition
2. File picker shows project whitelist files, grouped by directory
3. User selects files (multi-select supported)
4. Files added with default view mode (configurable)

### Creating Custom Slice

1. User clicks [Slices] on a file
2. Slice editor opens showing file content + AST slices
3. User selects line range via click-drag or input
4. User adds tag and/or comment
5. Slice saved to file entry in Context Composition

### Saving Context Preset

1. User curates Context Composition
2. Clicks [💾 Save]
3. Dialog: enter preset name + optional description
4. Validation runs - warns if files missing
5. Preset saved to project

### Loading Context Preset

1. User selects preset from dropdown
2. Context Composition cleared
3. Files populated from preset
4. Missing files highlighted with warning
5. User resolves or proceeds

---

## Technical Notes

- All file paths in presets stored as relative to project root
- FileItem model extended with view_mode, custom_slices
- Context Composition panel completely rewired to be independent of Files & Media
- Aggregate functions updated to respect view modes and slices
- Tool access still uses Files & Media whitelist

---

## Out of Scope

- RAG configuration changes (handled separately)
- Tool preset changes (already exists)
- MMA track creation (handled by track system)
- Agent behavior when given incomplete views (assumes tooling access)