---
name: consolidate-task-state
description: Consolidate task state by moving state.json into task folder and removing duplicated data
parts:
  - src/types/task.rs
  - src/storage.rs
  - src/servers/unified.rs
  - src/servers/task.rs
  - CLAUDE.md
estimate:
  optimistic: 3 hours
  normal: 5 hours
  pessimistic: 8 hours
---

# Implementation Plan

## Feature Sizing Checklist

- [x] Each feature can be described in 2-3 sentences
- [x] Each feature is completable in one context window
- [x] No feature tries to do too much

## New Directory Structure

```
tasks/
  .config/
    config.toml           # Project config (unchanged)
  my-task/
    task.md               # User's description (read-only)
    plan.md               # Implementation plan (status removed from frontmatter)
    feature-list.json     # Features array
    questions.json        # Questions array (NEW - replaces questions.md)
    state.json            # Slim state (moved from .state/my-task/)
    progress.txt          # Progress log
    .review/
      review-*.json       # Review sessions (moved from .state/my-task/)
```

## New state.json Structure

```json
{
  "status": "implementing",
  "created_at": "2026-01-11T10:38:26Z",
  "updated_at": "2026-01-11T10:59:42Z",
  "current_review": "review-id-here",
  "review_iterations": 1,
  "feature_approval_mode": null
}
```

Removed fields: `name`, `project_path`, `features`, `questions`

## New questions.json Structure

```json
[
  {
    "id": "q1",
    "question": "What is the expected behavior?",
    "category": "clarification",
    "answered": true,
    "answer": "The answer here"
  }
]
```

## Task Summary

| ID | Task | Files |
|----|------|-------|
| T1 | Create slim TaskState struct | `src/types/task.rs` |
| T2 | Update storage paths and methods | `src/storage.rs` |
| T3 | Update feature reading/writing | `src/servers/unified.rs`, `src/servers/task.rs` |
| T4 | Replace questions.md with questions.json | `src/storage.rs`, `src/servers/unified.rs`, `src/servers/task.rs` |
| T5 | Remove status from Frontmatter | `src/types/task.rs` |
| T6 | Add automatic migration | `src/storage.rs` |
| T7 | Update documentation | `CLAUDE.md` |

## Tasks

### T1: Create slim TaskState struct (F1)
- [ ] Remove `name` field from TaskState
- [ ] Remove `project_path` field from TaskState
- [ ] Remove `features` field from TaskState
- [ ] Remove `questions` field from TaskState
- [ ] Update `TaskState::new()` to not require name
- [ ] Remove `TaskSummary` or update it to not depend on TaskState fields
- [ ] Update all tests

### T2: Update storage paths and methods (F2)
- [ ] Change `task_state_path()` to return `tasks/task-name/state.json`
- [ ] Add `review_dir()` method returning `tasks/task-name/.review/`
- [ ] Change `review_path()` to use new `.review/` directory
- [ ] Remove `state_dir()` method
- [ ] Remove `task_state_dir()` method
- [ ] Update `ensure_dirs()` methods
- [ ] Update `list_tasks()` to scan task folders instead of .state/
- [ ] Update `list_reviews()` to use new path

### T3: Update feature reading/writing (F3)
- [ ] Find all `state.features` access points
- [ ] Create helper function to load features from feature-list.json
- [ ] Update `save_features` to only write feature-list.json (not state)
- [ ] Update `mark_feature_complete` to read/write feature-list.json
- [ ] Update `mark_feature_verified` similarly
- [ ] Update `all_features_completed()` to read from file
- [ ] Update `incomplete_features()` to read from file

### T4: Replace questions.md with questions.json (F4)
- [ ] Add `questions_json_path()` method to storage
- [ ] Add `read_questions_json()` method
- [ ] Add `write_questions_json()` method
- [ ] Remove `questions_md_path()`, `read_questions_md()`, `write_questions_md()`
- [ ] Remove `generate_questions_md()` function
- [ ] Update `save_questions` tool to write JSON
- [ ] Update `save_qa_response` tool to read/write JSON
- [ ] Update `unanswered_questions()` to read from file
- [ ] Update `analyze_task` response to reflect new file

### T5: Remove status from Frontmatter (F5)
- [ ] Remove `status` field from `Frontmatter` struct
- [ ] Update `Frontmatter::new()` signature
- [ ] Update `generate_frontmatter()` 
- [ ] Update `parse_frontmatter()` to ignore status if present (backward compat)
- [ ] Update all code that creates Frontmatter instances
- [ ] Update tests

### T6: Add automatic migration (F6)
- [ ] Create `needs_migration()` function to detect old structure
- [ ] Create `migrate_task()` function for single task
- [ ] Migrate state.json: move file, strip features/questions/name/project_path
- [ ] Migrate review files: move from .state/task/ to task/.review/
- [ ] Convert questions.md to questions.json during migration
- [ ] Call migration automatically in `load_task_state()`
- [ ] After all tasks migrated, delete .state/ directory
- [ ] Add migration logging to progress.txt

### T7: Update documentation (F7)
- [ ] Update directory structure in CLAUDE.md
- [ ] Update File Responsibilities table
- [ ] Remove references to .state/ directory
- [ ] Update state.json description
- [ ] Add questions.json description
- [ ] Update example workflow if needed

## Testing Considerations

- Test migration with existing tasks in old structure
- Test fresh task creation with new structure
- Test that features are correctly read from feature-list.json
- Test that questions are correctly read/written to questions.json
- Test review workflow with new .review/ location
- Test list_tasks works with new folder scanning
- Ensure backward compatibility during transition

## Estimate

**Senior Developer Profile:** 5+ years experience, familiar with Rust and the K4000 codebase.

| Scenario | Time |
|----------|------|
| Optimistic | 3 hours |
| Normal | 5 hours |
| Pessimistic | 8 hours |

### Assumptions
- No major architectural issues discovered during implementation
- Existing tests provide good coverage for refactoring
- Migration logic handles all edge cases in existing tasks
