jd-task-manager

What this skill does

# Johnny.Decimal Task Manager

This skill manages tasks in Johnny.Decimal systems using the jdtodo.txt
plain-text format. It reads, creates, completes, cancels, and modifies tasks
stored in `todo.txt` files within `00.02 Tasks/` folders. It also handles
`done.txt` (completed and cancelled tasks) and `someday.txt` (deferred items).

Before processing, read `references/jdtodo-spec.md` for the complete jdtodo.txt
format specification.

---

## 1. Orientation: Discover the JD Environment

Before touching any files, build a mental map of the user's JD setup.

### 1.1 Locate the JD Root

The JD root folder is wherever the user's systems live. Common locations:

- `~/Library/Mobile Documents/com~apple~CloudDocs/JD/` (iCloud Drive)
- `~/Documents/JD/`
- `~/JD/`
- A project-specific folder the user designates

If you don't know the root, ask the user. If the user says "show my tasks"
without further context, check the most common locations above. If you find
exactly one, confirm it. If you find multiple or none, ask.

### 1.2 Identify Systems

List the top-level folders under the JD root. Each folder whose name matches
the pattern `[A-Z][0-9][0-9] *` is a JD system (e.g., `P10 Personal`,
`W20 Work`, `C40 Citywide`).

If the user has a single system (no SYS prefix), treat the entire JD root as
one system.

### 1.3 Load Each System's JDex

For every system you'll work with, read the JDex file at:

```
SYS/00-09 */00 */00.00 *JDex*
```

The JDex is needed to validate JD codes on tasks and to display human-readable
descriptions alongside `+AC.ID` references. If the JDex is missing, you can
still manage tasks but cannot validate JD code references — flag this to the
user.

### 1.4 Locate Task Files

For each system, look for task files at:

```
SYS/00-09 */00 */00.02 Tasks*/todo.txt
SYS/00-09 */00 */00.02 Tasks*/done.txt
SYS/00-09 */00 */00.02 Tasks*/someday.txt
```

**Legacy detection:** If a file named `00.02 Tasks.md` exists (instead of a
`00.02 Tasks/` directory), this is the legacy markdown-checkbox format from the
system setup workflow. See §10 for migration guidance.

If no task files exist at all, offer to create the `00.02 Tasks/` directory
with an empty `todo.txt`.

---

## 2. Parse Tasks

Each line in `todo.txt` (and `done.txt`, `someday.txt`) is a task. Parse using
these rules from the jdtodo.txt specification.

### 2.1 Logical Lines

A task is one logical line. If a line ends with `\` (backslash as the very last
character, no trailing whitespace), the next physical line is a continuation of
the current task's note. Gather all continuation lines before parsing.

Skip blank lines and any lines that are entirely whitespace.

### 2.2 Task States

Determine the task state from the line prefix:

| Prefix | State | File |
|--------|-------|------|
| `x YYYY-MM-DD` | Complete | done.txt |
| `~ YYYY-MM-DD` | Cancelled | done.txt |
| `(A)` through `(Z)` | Incomplete (with priority) | todo.txt |
| Anything else | Incomplete (no priority) | todo.txt |

### 2.3 Priority and Dates

For **incomplete tasks**:

1. If the line starts with `(X) ` where X is A–Z, extract the priority.
2. After priority (or at line start if no priority), check for a date in
   `YYYY-MM-DD` format — this is the creation date.

For **complete/cancelled tasks**:

1. After the `x ` or `~ ` marker, the first date is the completion/cancellation
   date.
2. The second date (if present) is the creation date.

### 2.4 Contexts and Projects

Scan the task body (everything before ` --- ` if a note exists) for:

- **Contexts**: tokens matching `@non-whitespace` (e.g., `@phone`, `@laptop`,
  `@waiting`, `@someday`)
- **Projects**: tokens matching `+non-whitespace` (e.g., `+GarageSale`,
  `+N42.12.05`)

**JD code detection regex** for project tags:

```
\+([A-Z]\d{2}\.)?\d{2}\.\d{2}(\+[A-Za-z0-9]+)?
```

This matches `+AC.ID`, `+SYS.AC.ID`, `+AC.ID+SUB`, and `+SYS.AC.ID+SUB`.

### 2.5 Key:Value Extensions

Extract recognized key:value pairs from the task body:

| Key | Value format | Purpose |
|-----|-------------|---------|
| `due` | `YYYY-MM-DD` or `someday` | Hard deadline |
| `before` | `YYYY-MM-DD` or `someday` | Soft deadline |
| `t` | `YYYY-MM-DD` or `someday` | Threshold / visibility gate (user deferral) |
| `after` | `YYYY-MM-DD` or `someday` | Visibility gate (external constraint) |
| `id` | Non-whitespace, no colons | Task identifier |
| `dep` | Non-whitespace, no colons | Blocked by another task |
| `sup` | Non-whitespace, no colons | Subtask of another task |
| `rec` | `[+]N[d\|w\|m\|y\|b]` | Recurrence interval |
| `h` | `1` | Hidden from default views |
| `pri` | `A`–`Z` | Preserved priority (on completed tasks) |

Preserve any unrecognized key:value pairs when modifying tasks.

### 2.6 Notes

If the task body contains ` --- ` (space-hyphen-hyphen-hyphen-space), everything
after the first occurrence is the note. The note may span multiple physical lines
via `\` continuation. Leading whitespace on continuation lines is trimmed.

Key:value pairs in the note are freeform text — do NOT parse them as task
metadata.

---

## 3. List and Filter Tasks

### 3.1 Default View

When the user asks to see their tasks without specific filters, show all
**actionable** tasks. A task is actionable if ALL of these are true:

- It is incomplete (not `x` or `~`)
- It is not hidden (`h:1` absent)
- Its threshold date has passed or is absent (`t:` date ≤ today, or no `t:`)
- Its `after:` date has passed or is absent (`after:` date ≤ today, or no
  `after:`)
- It does not have `@someday` context
- It does not have `due:someday`
- All `dep:` references point to completed tasks (or the referenced `id:` does
  not exist in the active task list)

Tasks with unresolved dependencies are shown in a separate **Blocked** section
rather than hidden entirely.

### 3.2 Filter by Context

When the user specifies a context (e.g., "show me @phone tasks"), show only
tasks that have that context tag. Common filters:

- `@phone` — calls to make
- `@laptop` — computer work
- `@errands` — out-of-house tasks
- `@waiting` — blocked on someone else
- `@someday` — not currently actionable
- `@agenda` — discuss at next meeting

### 3.3 Filter by Project or JD Code

When the user specifies a project or JD code:

- `+GarageSale` — all tasks in that named project
- `+N42.12.05` — all tasks referencing that JD ID
- `+N42.12` — all tasks referencing any ID in that JD category

### 3.4 Filter by Priority

Show tasks at or above a given priority:

- "show priority A tasks" → only `(A)` tasks
- "show high priority" → `(A)` and `(B)` tasks
- "show all priorities" → all tasks grouped by priority

### 3.5 Filter by Date

- **overdue**: Tasks where `due:` or `before:` date is before today
- **due today**: Tasks where `due:` is today
- **due this week**: Tasks where `due:` is within the next 7 days
- **upcoming**: Tasks where `due:` is within the next 14 or 30 days
- **no due date**: Tasks with no `due:` or `before:` tag

### 3.6 Dependency Resolution

Build the dependency graph from `id:`, `dep:`, and `sup:` tags:

1. Index all tasks by their `id:` value.
2. For each task with `dep:X`, check if `id:X` exists and is incomplete.
3. If `id:X` is incomplete, the task is **blocked**.
4. If `id:X` is complete (in done.txt) or doesn't exist, the dependency is
   resolved.

Show blocked tasks in a separate section with the blocking task identified:

```
### Blocked

(B) Sort items into keep/sell/donate +GarageSale dep:garage-clean
    ↳ blocked by: (A) Clean out garage for sale [garage-clean]
```

For `sup:` relationships, show subtask grouping when listing by project:

```
### +GarageSale

(A) Clean out garage for sale id:garage-clean due:2026-05-01
  ├─ (B) Sort items into keep/sell/donate sup:garage-clean
  ├─ (B) Sweep and mop garage floor sup:garage-clean
  └─ (C) Arrange sale items on tables sup:garage-clean dep:sort-items
```

### 3.7 Grouping

Default grouping is by priority. The user may request grouping by:

- **System**: Group tasks by JD sy