> ## Documentation Index
> Fetch the complete documentation index at: https://v2.spacedrive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Task Tracking

The `.tasks/` directory contains a structured task tracking system that manages the entire development lifecycle of Spacedrive. Tasks are defined as markdown files with YAML frontmatter and validated against a JSON schema.

## Overview

Task tracking provides:

* **Hierarchical organization** with epics and subtasks
* **Status tracking** across the development lifecycle
* **Metadata** like priority, assignee, and whitepaper references
* **Validation** via a CLI tool to ensure consistency

### Directory Structure

```
.tasks/
├── core/                         # Backend/Rust tasks
│   ├── CORE-000-vdfs-core.md
│   ├── CORE-001-entry-centric-model.md
│   ├── JOB-000-job-system.md
│   ├── INDEX-*.md
│   ├── LSYNC-*.md
│   └── ...
├── interface/                    # Frontend/React tasks
│   ├── UI-000-interface-v2.md
│   ├── EXPL-000-explorer-epic.md
│   ├── SETS-000-settings-epic.md
│   └── ...
├── mobile/                       # Mobile-specific tasks
│   └── (future tasks)
├── task.schema.json              # JSON schema defining task structure
└── Claude.md                     # Task tracking cheatsheet
```

Tasks follow the naming pattern: `{PREFIX}-{NUMBER}-{slug}.md` and are organized into subdirectories by domain (core, interface, mobile).

## Task Schema

Every task file contains YAML frontmatter that must conform to the schema defined in `task.schema.json`.

### Required Fields

```yaml theme={null}
---
id: CORE-001
title: Entry-Centric Data Model
status: Done
assignee: james
priority: High
---
```

| Field      | Type   | Description                                          |
| ---------- | ------ | ---------------------------------------------------- |
| `id`       | string | Unique identifier matching pattern `^[A-Z]+-[0-9]+$` |
| `title`    | string | Human-readable title (min 5 characters)              |
| `status`   | enum   | One of: `To Do`, `In Progress`, `Done`               |
| `assignee` | string | Person responsible for the task                      |
| `priority` | enum   | One of: `High`, `Medium`, `Low`                      |

### Optional Fields

```yaml theme={null}
---
parent: CORE-000
tags: [core, database, epic]
whitepaper: Section 4.1
last_updated: 2025-12-02
---
```

| Field          | Type   | Description                          |
| -------------- | ------ | ------------------------------------ |
| `parent`       | string | Parent task ID for subtask hierarchy |
| `tags`         | array  | Categorization tags                  |
| `whitepaper`   | string | Reference to design documentation    |
| `last_updated` | string | ISO date of last modification        |

## Task Statuses

The lifecycle of a task follows three states:

### To Do

Task has not been started. No implementation exists.

### In Progress

Task is actively being worked on. Criteria for this status:

* Some code has been written
* Feature is partially implemented
* Still has rough edges or incomplete functionality

### Done

Task is complete. All acceptance criteria must be met:

* All listed acceptance criteria are implemented
* Code is merged to main branch
* Tests pass (if applicable)
* Feature is production-ready

<Note>
  Never mark a task as `Done` if implementation is partial, tests are failing, or the feature doesn't work as specified.
</Note>

## Task Prefixes

Tasks are organized by domain using prefixes. Tasks are further organized into subdirectories:

### Core Tasks (`.tasks/core/`)

Backend and Rust-related tasks:

| Prefix   | Domain                                |
| -------- | ------------------------------------- |
| `CORE`   | Core architecture and data model      |
| `JOB`    | Job system and task execution         |
| `INDEX`  | File indexing and location management |
| `FSYNC`  | File synchronization                  |
| `LSYNC`  | Library synchronization               |
| `NET`    | Networking and P2P                    |
| `SEARCH` | Search functionality                  |
| `FILE`   | File operations                       |
| `LOC`    | Location management                   |
| `VOL`    | Volume operations                     |
| `SEC`    | Security and privacy                  |
| `CLI`    | Command-line interface                |
| `CLOUD`  | Cloud integration                     |
| `AI`     | AI and ML features                    |
| `PLUG`   | Plugin system                         |
| `DEV`    | Development tooling                   |

### Interface Tasks (`.tasks/interface/`)

Frontend and React-related tasks:

| Prefix  | Domain                          |
| ------- | ------------------------------- |
| `UI`    | UI primitives and design system |
| `EXPL`  | Explorer interface              |
| `SETS`  | Settings pages                  |
| `SRCH`  | Search UI                       |
| `TAG`   | Tagging interface               |
| `MEDIA` | Media viewer                    |
| `NAV`   | Navigation and routing          |
| `PERF`  | Performance optimizations       |
| `A11Y`  | Accessibility                   |

### Mobile Tasks (`.tasks/mobile/`)

Mobile-specific tasks (future):

| Prefix  | Domain                |
| ------- | --------------------- |
| `IOS`   | iOS native features   |
| `MACOS` | macOS native features |
| `AND`   | Android features      |

## Task Validator CLI

The `task-validator` binary provides utilities for managing and validating tasks.

### List Tasks

View all tasks sorted by status:

```bash theme={null}
cargo run --bin task-validator -- list --sort-by status
```

Output groups tasks by status (To Do, In Progress, Done):

```
=== Done ===
CORE-000: Epic: VDFS Core Architecture
CORE-001: Entry-Centric Data Model
JOB-001: Job Manager for Task Scheduling

=== In Progress ===
CLOUD-003: Cloud Volume Support

=== To Do ===
AI-002: Create Fine-tuning Dataset
```

### Filter Tasks

Filter by specific criteria:

```bash theme={null}
# By status
cargo run --bin task-validator -- list --status "In Progress"

# By priority
cargo run --bin task-validator -- list --priority High

# By assignee
cargo run --bin task-validator -- list --assignee james
```

### Validate Schema

Ensure all task files conform to the schema:

```bash theme={null}
cargo run --bin task-validator -- validate
```

This checks:

* YAML frontmatter is valid
* All required fields are present
* Field values match allowed enums
* ID pattern is correct
* Parent references exist

Validation runs in CI to prevent invalid tasks from being committed.

## Workflow

### Reviewing Task Status

When code has been merged, tasks should be reviewed and updated:

1. **Check recent commits**:
   ```bash theme={null}
   git log --oneline -20
   ```

2. **List current task state**:
   ```bash theme={null}
   cargo run --bin task-validator -- list --sort-by status
   ```

3. **For each potential completed feature**:
   * Read the task file to understand acceptance criteria
   * Read all implementation files mentioned in the task
   * Check `core/tests/` for integration tests
   * Verify each acceptance criterion is met in the code

4. **Update task status**:
   Edit the YAML frontmatter in the task file:
   ```yaml theme={null}
   ---
   status: Done  # Changed from "In Progress"
   last_updated: 2025-12-02  # Update date
   ---
   ```

5. **Validate changes**:
   ```bash theme={null}
   cargo run --bin task-validator -- validate
   ```

<Tip>
  When unsure if a task is complete, leave it as `In Progress` rather than prematurely marking it `Done`. The tracker is only useful if it's accurate.
</Tip>

### Creating New Tasks

1. Choose appropriate subdirectory (`core/`, `interface/`, or `mobile/`)
2. Choose appropriate prefix based on domain
3. Find next available number (e.g., if `EXPL-002` exists, use `EXPL-003`)
4. Create file with pattern: `.tasks/{subdirectory}/{PREFIX}-{NUMBER}-{slug}.md`
5. Add YAML frontmatter with all required fields
6. Write task description and acceptance criteria
7. Validate:
   ```bash theme={null}
   cargo run --bin task-validator -- validate
   ```

Example core task file (`.tasks/core/LSYNC-017-realtime-sync.md`):

```markdown theme={null}
---
id: LSYNC-017
title: Real-time Sync Protocol
status: To Do
assignee: james
parent: LSYNC-000
priority: High
tags: [core, sync, networking]
whitepaper: Section 5.3
---

## Description

Implement a real-time synchronization protocol that pushes changes
immediately rather than relying on polling intervals.

## Implementation Notes

- Use WebSocket or similar bi-directional protocol
- Integrate with existing sync service
- Maintain backward compatibility with polling-based sync

## Acceptance Criteria

- [ ] Changes propagate within 1 second between devices
- [ ] Protocol handles network interruptions gracefully
- [ ] Fallback to polling when real-time unavailable
- [ ] Integration tests demonstrate cross-device sync
```

Example interface task file (`.tasks/interface/EXPL-004-breadcrumbs.md`):

```markdown theme={null}
---
id: EXPL-004
title: Breadcrumb Navigation
status: To Do
assignee: james
parent: EXPL-000
priority: Medium
tags: [explorer, navigation, ui]
---

## Description

Implement breadcrumb navigation in the Explorer top bar showing the
current path with clickable segments.

## Implementation Notes

- Display full path as clickable segments
- Truncate middle segments if path is too long
- Show dropdown menu for segments with many children
- Keyboard navigation support

## Acceptance Criteria

- [ ] Breadcrumbs show current location path
- [ ] Click segment to navigate to that level
- [ ] Path updates when navigating
- [ ] Works with virtual locations and SD paths
- [ ] Responsive truncation for long paths
```

### Updating Task Status

When updating tasks after completing work:

**DO:**

* Read implementation files thoroughly
* Verify all acceptance criteria are met
* Check for passing integration tests
* Update `last_updated` field
* Be rigorous about what "Done" means

**DON'T:**

* Mark tasks done based on assumptions
* Skip reading the actual code
* Ignore failing tests or partial implementations
* Batch update tasks without verification

## Common Patterns

### Epic Tasks

Epics are high-level tasks that have subtasks:

```yaml theme={null}
---
id: CORE-000
title: "Epic: VDFS Core Architecture"
status: Done
assignee: james
priority: High
tags: [epic, core, vdfs]
---
```

Subtasks reference their epic via the `parent` field:

```yaml theme={null}
---
id: CORE-001
title: Entry-Centric Data Model
parent: CORE-000
status: Done
---
```

### Task Dependencies

While not enforced by schema, dependencies can be documented in task descriptions:

```markdown theme={null}
## Dependencies

This task requires:
- CORE-001 (Entry-Centric Model) - Done
- INDEX-001 (Location Watcher) - In Progress
```

### Whitepaper References

Link tasks to design documentation:

```yaml theme={null}
whitepaper: Section 4.1
```

This helps trace implementation back to architectural decisions.

## Best Practices

### Task Granularity

* **Epics**: High-level features spanning multiple subtasks
* **Tasks**: Concrete features implementable in focused work
* **Too granular**: Don't create tasks for every file or function

### Acceptance Criteria

Write specific, testable criteria:

**Good:**

```markdown theme={null}
- [ ] User can add S3 bucket as a cloud volume
- [ ] Cloud volumes appear in volume list
- [ ] Files in cloud volume can be searched
```

**Bad:**

```markdown theme={null}
- [ ] Implement cloud volume feature
- [ ] Make it work properly
```

### Status Accuracy

The tracker is only valuable if it reflects reality:

* Review and update tasks regularly
* Don't mark tasks done to "clean up" the list
* Keep `In Progress` honest about active work
* Archive or remove truly obsolete tasks

### Git Integration

While not automated, tasks can be referenced in commits:

```bash theme={null}
git commit -m "feat: implement cloud volume indexing (CLOUD-003)"
```

This creates a searchable link between tasks and implementation:

```bash theme={null}
git log --oneline --grep="CLOUD-003"
```

## Troubleshooting

### Validation Errors

**Invalid YAML**:

```
Error: Failed to parse YAML in CORE-001-entry-centric-model.md
```

Fix: Check YAML syntax, ensure frontmatter is enclosed in `---`

**Missing Required Field**:

```
Error: Missing required field 'priority' in CORE-001
```

Fix: Add the missing field to frontmatter

**Invalid Status Value**:

```
Error: Invalid status 'Complete' in CORE-001. Must be one of: To Do, In Progress, Done
```

Fix: Use exact status values from schema (case-sensitive)

### Duplicate IDs

Each task ID must be unique. If validation reports duplicates:

```bash theme={null}
# Find all task IDs
grep "^id:" .tasks/*.md | sort
```

Renumber conflicting tasks and update any parent references.

### Orphaned Tasks

Tasks with `parent` fields referencing non-existent tasks:

```bash theme={null}
cargo run --bin task-validator -- validate
```

Will report broken parent references. Either remove the parent field or create the missing epic.

## Examples

### Complete Epic with Subtasks

```markdown theme={null}
# .tasks/SEARCH-000-semantic-search.md
---
id: SEARCH-000
title: "Epic: Semantic Search System"
status: In Progress
assignee: james
priority: High
tags: [epic, search, ai]
whitepaper: Section 6.2
---

## Description

Build a semantic search system using embeddings and vector similarity.

## Subtasks

- SEARCH-001: Async search job infrastructure
- SEARCH-002: Two-stage FTS + semantic reranking
- SEARCH-003: Unified vector repositories
```

```markdown theme={null}
# .tasks/SEARCH-001-async-searchjob.md
---
id: SEARCH-001
title: Async Search Job
parent: SEARCH-000
status: Done
assignee: james
priority: High
tags: [search, jobs]
last_updated: 2025-11-15
---

## Description

Implement background search job that processes queries asynchronously.

## Acceptance Criteria

- [x] SearchJob implements Job trait
- [x] Queries execute in background thread pool
- [x] Results stream back via events
- [x] Integration test demonstrates full workflow
```

## Integration with Development

The task tracking system complements other development tools:

* **Testing**: Acceptance criteria inform test cases
* **CI/CD**: Schema validation runs in continuous integration
* **Code Review**: Task IDs provide context in pull requests
* **Documentation**: Tasks link to whitepaper design sections
* **Planning**: Status overview shows project progress

By maintaining accurate task status, the team has a real-time view of what's complete, what's in progress, and what's planned.