# Taskmaster Task Tracker

Automatically updates Taskmaster tasks with datetime stamps whenever they're created or status changed. This tool monitors the `tasks.json` file and adds timestamps to track task lifecycle events.

## Features

- **Automatic Timestamping**: Adds timestamps for task creation and status changes
- **File Monitoring**: Watches for changes in the tasks.json file
- **Backup System**: Creates backups before making changes
- **Logging**: Comprehensive logging to track all activities
- **Safe Operation**: Only adds timestamps, never modifies existing data

## Timestamp Fields Added

The tracker adds the following timestamp fields to tasks:

- `created_at`: ISO 8601 timestamp when the task was first detected
- `updated_at`: ISO 8601 timestamp when the task was last modified
- `status_changed_to_X`: ISO 8601 timestamp when status changed to X (e.g., `status_changed_to_done`)

## Usage

### Quick Start

```bash
# Run once to process current tasks
./scripts/tm_tracker.sh --once

# Watch for changes continuously (5-second interval)
./scripts/tm_tracker.sh --watch

# Watch with custom interval (10 seconds)
./scripts/tm_tracker.sh --watch --interval 10
```

### Python Script Direct Usage

```bash
# Run once
python scripts/taskmaster_tracker.py

# Watch continuously
python scripts/taskmaster_tracker.py --watch

# Watch with custom interval
python scripts/taskmaster_tracker.py --watch --interval 10
```

## Files and Directories

- `scripts/taskmaster_tracker.py`: Main Python script
- `scripts/tm_tracker.sh`: Shell wrapper script
- `.taskmaster/backups/`: Directory containing task backups
- `logs/taskmaster_tracker.log`: Log file with all tracker activities

## How It Works

1. **File Monitoring**: Uses MD5 hashing to detect changes in `tasks.json`
2. **Task Detection**: Compares current tasks with previously known tasks
3. **Timestamp Addition**: Adds appropriate timestamps for new tasks and status changes
4. **Backup Creation**: Creates timestamped backups before making changes
5. **Logging**: Logs all activities for debugging and audit purposes

## Example Output

When a new task is created:

```json
{
  "id": 11,
  "title": "New Task",
  "status": "pending",
  "created_at": "2024-01-15T10:30:00.123456+00:00",
  "updated_at": "2024-01-15T10:30:00.123456+00:00"
}
```

When a task status changes:

```json
{
  "id": 11,
  "title": "New Task",
  "status": "done",
  "created_at": "2024-01-15T10:30:00.123456+00:00",
  "updated_at": "2024-01-15T14:45:00.789012+00:00",
  "status_changed_to_done": "2024-01-15T14:45:00.789012+00:00"
}
```

## Logging

The tracker logs all activities to `logs/taskmaster_tracker.log` with timestamps:

```
2024-01-15 10:30:00,123 - INFO - New task detected: 11 - New Task
2024-01-15 10:30:00,124 - INFO - Added created_at to task 11: 2024-01-15T10:30:00.123456+00:00
2024-01-15 14:45:00,789 - INFO - Status change detected for task 11: pending -> done
2024-01-15 14:45:00,790 - INFO - Added status_changed_to_done to task 11: 2024-01-15T14:45:00.789012+00:00
```

## Safety Features

- **Backup System**: Always creates backups before modifying tasks
- **Non-Destructive**: Only adds new fields, never modifies existing data
- **Error Handling**: Graceful handling of file errors and JSON parsing issues
- **Cleanup**: Automatically removes old backups (keeps last 10)

## Integration with Taskmaster

The tracker works seamlessly with Taskmaster:

1. **No Conflicts**: Only adds timestamp fields, doesn't interfere with Taskmaster operations
2. **Automatic Detection**: Detects changes made by Taskmaster CLI or MCP tools
3. **Backup Safety**: Creates backups before any modifications
4. **Logging**: Provides audit trail for all task changes

## Troubleshooting

### Common Issues

1. **Permission Errors**: Ensure the script has read/write permissions
2. **File Not Found**: Check that `.taskmaster/tasks/tasks.json` exists
3. **JSON Errors**: The tracker will log JSON parsing errors and continue
4. **Backup Directory**: Automatically creates backup directory if it doesn't exist

### Debug Mode

To see more detailed logging, modify the logging level in the Python script:

```python
logging.basicConfig(level=logging.DEBUG, ...)
```

## Development

The tracker is designed to be:

- **Lightweight**: Minimal resource usage
- **Reliable**: Comprehensive error handling
- **Safe**: Non-destructive operations only
- **Extensible**: Easy to add new timestamp types

## Future Enhancements

Potential improvements:

- Webhook notifications for task changes
- Integration with external time tracking tools
- Custom timestamp field configurations
- Database storage for change history
- Email notifications for status changes