# Taskwarrior Notification System - Implementation Plan

**Date:** 2026-03-03
**Status:** READY TO IMPLEMENT
**Approach:** Tag-Based Notifications with Relative Reminders

---

## Overview

Replace the separate state file system with **Taskwarrior native tags**. Tasks with due dates or reminder tags get automatic notification tracking.

### Key Features
- **Tag-based tracking**: No more `~/.local/share/task-notified` file
- **Relative reminders**: `+remind1hour`, `+remind30min`, `+remind2days`, etc.
- **Auto-cleanup**: Notification tags removed when task completed
- **5-minute polling**: Unchanged from current setup
- **Multiple reminders**: Support multiple reminder tags per task

---

## Tag System

### Core Tags

| Tag | Purpose | Auto-Added? | Auto-Removed? |
|-----|---------|-------------|---------------|
| `+notify` | Mark task for notification tracking | Yes (if due date or +remind*) | Yes (on completion) |
| `+notified` | Task has been notified (due time reached) | Yes (when due) | Yes (on completion) |

### Reminder Tags

| Tag | Time Before Due | Example Task |
|-----|-----------------|--------------|
| `+remind5min` | 5 minutes | Quick reminders |
| `+remind10min` | 10 minutes | Short prep time |
| `+remind15min` | 15 minutes | Meeting prep |
| `+remind30min` | 30 minutes | Standard reminder |
| `+remind1hour` | 1 hour | Important tasks |
| `+remind2hours` | 2 hours | Preparation needed |
| `+remind4hours` | 4 hours | Workday planning |
| `+remind8hours` | 8 hours | Next-day prep |
| `+remind12hours` | 12 hours | Half-day warning |
| `+remind1day` | 1 day | Daily planning |
| `+remind2days` | 2 days | Medium-term tasks |
| `+remind3days` | 3 days | Project deadlines |
| `+remind1week` | 1 week | Long-term planning |
| `+remind2weeks` | 2 weeks | Monthly reviews |
| `+remind3weeks` | 3 weeks | Quarterly prep |
| `+remind1month` | 1 month | Annual planning |

---

## Workflow

### 1. Task Creation

```bash
# Standard task - gets +notify automatically
task add "Call dentist" due:tomorrow

# Task with reminders
task add "Client meeting" due:friday +remind1day +remind1hour +remind15min

# Long-term project
task add "Quarterly report" due:2026-04-01 +remind1month +remind1week
```

### 2. Notification Lifecycle

```
Task Created
    ↓
Auto-add +notify (if due date or +remind* present)
    ↓
Every 5 minutes script checks:
  - Reminder tags within window → Send reminder, remove tag
  - Due tasks without +notified → Send due notification, add +notified
    ↓
Task Completed
    ↓
Remove ALL notification tags (+notify, +notified, +remind*)
    ↓
Task remains in Taskwarrior history (completed tasks list)
```

### 3. Notification Types

**Reminder Notifications:**
- Message: "🔔 Reminder: [description] - Due in [time]"
- Urgency: normal
- Removes the triggered reminder tag

**Due Notifications:**
- Message: "⚠️ Task Due: [description]"
- Urgency: critical (stays visible)
- Adds +notified tag
- Also sends to ntfy push server

---

## Script Implementation

**File:** `/etc/nixos/home/sam/bin/task-due-notify.sh`

**Key Logic:**

1. **Auto-tag pending tasks**
   - Find tasks with due dates OR +remind* tags that don't have +notify
   - Add +notify tag to them

2. **Process reminders**
   - For each +remind* tag, calculate if we're within that window
   - Send reminder notification
   - Remove the reminder tag

3. **Process due tasks**
   - Find tasks due before now without +notified
   - Send due notification
   - Add +notified tag

4. **Cleanup completed tasks**
   - Remove all notification tags from completed/deleted tasks
   - This keeps history clean but preserves task in Taskwarrior

---

## Usage Examples

### Add Tasks with Reminders

```bash
# Meeting tomorrow with advance warning
task add "Team standup" due:tomorrow9am +remind15min

# Important deadline with multiple warnings
task add "Project launch" due:friday +remind1week +remind2days +remind1hour

# Simple task - just notify when due
task add "Buy milk" due:6pm

# Add reminder to existing task
task 42 modify +remind30min

# Remove a reminder
task 42 modify -remind1hour
```

### View Tasks

```bash
# All tasks needing notifications
task +notify list

# Tasks due now (overdue)
task due.before:now status:pending list

# Tasks with specific reminder
task +remind1hour list

# Tasks already notified
task +notified list

# All reminders (any +remind*)
task tags.has:remind list
```

---

## Files Modified

### 1. Notification Script (MODIFIED)
**Path:** `/etc/nixos/home/sam/bin/task-due-notify.sh`

**Changes:**
- Remove state file dependency
- Add reminder tag processing
- Add auto-tagging logic
- Add cleanup for completed tasks

### 2. Home Configuration (NO CHANGES NEEDED)
**Path:** `/etc/nixos/home/sam/home.nix`

Timer and service configuration remain the same:
- 5-minute polling interval
- Same systemd service setup

### 3. Other Files (NO CHANGES)
- Waybar config: Unchanged
- Niri config: Unchanged  
- NixOS config: Unchanged

---

## Migration from State File

**Step 1:** Deploy new script
**Step 2:** Remove old state file:
```bash
rm ~/.local/share/task-notified
```
**Step 3:** Run script manually to auto-tag existing tasks:
```bash
~/.local/bin/task-due-notify
```

---

## Testing Checklist

- [ ] Add task with due date - verify +notify auto-added
- [ ] Add task with +remind30min - verify +notify auto-added  
- [ ] Wait for reminder - verify notification sent, tag removed
- [ ] Wait for due time - verify notification sent, +notified added
- [ ] Complete task - verify all notification tags removed
- [ ] Check ntfy still receives push notifications
- [ ] Verify no duplicate notifications

---

## Commands Reference

```bash
# Manual script run
~/.local/bin/task-due-notify

# Check timer
systemctl --user status task-due-notify.timer

# View notified tasks
task +notified list

# View tasks with reminders
task tags.has:remind list

# Add reminder to existing task
task <id> modify +remind1hour

# Complete task
task <id> done

# View completed tasks (history preserved)
task status:completed list
```

---

## Benefits Over State File System

1. **No file corruption** - Tags are part of task database
2. **Sync-friendly** - Tags sync with taskserver
3. **Queryable** - Can filter/view by notification status
4. **Multiple reminders** - Not limited to one notification
5. **Flexible** - Add/remove reminders anytime
6. **Clean history** - Tags auto-removed, task stays in history
7. **Visible** - See notification status in task info

---

*Next agent should read this file and implement the script changes outlined above.*