# Sprint 8a TDD Plan — Token Optimization

Testing framework: pytest + pytest-asyncio (`asyncio_mode = "auto"`)
Test location: `tests/test_tools/`
Fixtures: `tests/fixtures/`

---

## Section 1: Enhance output_limit.py

### truncate_output tests (`tests/test_tools/test_truncate_output.py`)

```python
# Test: text under brief limit returns unchanged
# Test: text over brief limit is truncated with notice
# Test: text under normal limit returns unchanged
# Test: text over normal limit is truncated with notice
# Test: text at full level returns unchanged (unlimited)
# Test: truncation notice includes accurate remaining line count
# Test: truncated text + notice fits within limit (max_chars total)
# Test: unknown detail value treated as "normal"
# Test: empty string returns unchanged
# Test: text exactly at limit boundary returns unchanged
```

### apply_output_limit validation tests (`tests/test_tools/test_truncate_output.py`)

```python
# Test: unknown detail value normalized to "normal" behavior
# Test: detail="verbose" applies normal limits (not unlimited)
# Test: detail="" (empty string) applies normal limits
# Test: valid values ("brief", "normal", "full") work unchanged
```

---

## Section 2: Add detail to Assets Tools

### suggest_scale detail tests (`tests/test_tools/test_detail_levels.py`)

```python
# Test: suggest_scale accepts detail parameter without error
# Test: suggest_scale default (no detail) returns dict
# Test: suggest_scale brief output under 3000 chars
# Test: suggest_scale normal output under 10000 chars
```

---

## Section 3: Rename impact_check Parameter + Add detail

### impact_check tests (`tests/test_tools/test_detail_levels.py`)

```python
# Test: impact_check accepts change_description parameter
# Test: returned dict contains "change_description" field (not "detail")
# Test: safe_alternative message uses change_description content correctly
# Test: impact_check detail="brief" output under 3000 chars
# Test: impact_check detail="normal" output under 10000 chars
# Test: impact_check default detail is "normal"
# Test: apply_output_limit adds truncation metadata when callers list is large
```

---

## Section 4: Add detail to Spatial Tools

### placement detail tests (`tests/test_tools/test_detail_levels.py`)

```python
# Test: placement accepts detail parameter without error
# Test: placement default (no detail) returns dict
# Test: placement brief output under 3000 chars
# Test: placement normal output under 10000 chars
```

---

## Section 5: Add detail to Bridge Tools

### Bridge tool detail tests (`tests/test_tools/test_detail_levels.py`)

For each bridge tool that needs detail added:

```python
# Test: {tool_name} function signature accepts detail parameter
# Test: {tool_name} detail parameter has default value "normal"
```

For high-output-risk bridge tools specifically:

```python
# Test: file_ops with detail="brief" applies output limit
# Test: file_ops op="read" with large content truncates string value
# Test: node_ops with detail="brief" applies output limit
# Test: editor_context with detail="brief" applies output limit
# Test: input with detail="brief" applies output limit
# Test: watch with detail="brief" applies output limit
# Test: undo_history with detail="brief" applies output limit
```

For no-op bridge tools:

```python
# Test: screenshot accepts detail parameter (no behavior change)
# Test: run accepts detail parameter (no behavior change)
# Test: save_scene accepts detail parameter (no behavior change)
# Test: camera accepts detail parameter (no behavior change)
# Test: script_ops accepts detail parameter (no behavior change)
```

### ping detail test

```python
# Test: ping accepts detail parameter without error
```

---

## Section 6: Verify and Tune Existing Detail Implementations

### Existing tool size verification (`tests/test_tools/test_detail_levels.py`)

```python
# Test: asset_registry brief output under 3000 chars (existing fixture)
# Test: asset_registry normal output under 10000 chars (existing fixture)
# Test: scene_map brief output under 3000 chars
# Test: scene_map normal output under 10000 chars
# Test: scene_map full keeps 30-node cap (performance)
# Test: spatial_audit brief output under 3000 chars
# Test: spatial_audit normal output under 10000 chars
# Test: signal_map brief output under 3000 chars
# Test: signal_map normal output under 10000 chars
# Test: dependency_graph brief output under 3000 chars
# Test: dependency_graph normal output under 10000 chars
# Test: trace_flow brief output under 3000 chars
# Test: project_summary brief output under 3000 chars
# Test: animation_info brief output under 3000 chars
# Test: animation_audit brief output under 3000 chars
# Test: validate brief output under 3000 chars
# Test: file_context brief output under 3000 chars
```

---

## Section 7: Integration Tests

### Token budget test (`tests/test_tools/test_token_budget.py`)

```python
# Test: combined workflow (project_summary brief + scene_map normal + asset_registry brief + spatial_audit brief + signal_map brief) total < 30000 chars
# Test: all tools called with default detail produce output within normal limits
```
