superme-todo

name	superme-todo
description	Use when working with superme todos and threads — adding or closing an item, deciding a lane, chasing someone who owes a reply, opening a new thread for an obligation, or explaining why something ranks where it does in TODAY.md.

superme-todo

Items are the moving parts; threads are the open loops that own them. The model mirrors ~/Desktop/email/ACTIVE/*/STATUS.md, which already works.

Lanes

Lane	Meaning	Required
YOU	Only the user can do it — sign, send, attend, decide, appear
ME	superme can do it — draft, file, verify, prepare, chase
WAITING	Blocked on another human	waiting_on

WAITING without waiting_on fails validation, because "waiting" with nobody named is how things quietly rot.

Item shape

id: todo-0043
type: todo
thread: permit-renewal-2026
lane: YOU
title: Book toma de huellas appointment
deadline: 2026-08-20
hard: true
blocks: []              # ids this item unblocks — see Keystones
waiting_on: null
waiting_since: null
chase_on: null
next_action: run the permits folder's cita_check.sh, then book via Chrome
evidence: [threads/permit-renewal-2026/evidence/dana-2026-07-30.eml]
opened: 2026-07-30

Keystones — importance is not the same as urgency

Some items have no deadline of their own yet gate a whole chain of work. In a permit thread, "the office confirms the solicitud is presented" has no date, but nothing downstream — the fingerprint appointment, the next form, the card itself — can move until it clears. Deadline-only ranking buries it; a human puts it first.

Give such an item a blocks: list of the ids it unblocks. It becomes a keystone: marked 🔑, annotated unblocks N items, and lifted into TODAY.md's "Needs you now" section even with no deadline.

A keystone does not displace a real deadline — a hard cutoff tomorrow still ranks above an undated keystone. The keystone earns visibility, not precedence: it is surfaced prominently rather than pushed to the top. blocks: is only a tiebreak in the sort, below deadline proximity.

This came directly from QC against the residence folder, where the single most consequential item was the one with no date attached.

Ranking

Urgency first, lane only as a tiebreak: overdue → hard → soonest → lane → title.

Lane deliberately does not dominate. Ranking by lane would sink every WAITING item beneath every ME item, hiding "the office has owed the autorización for 19 days and the cita is Tuesday" under "someday, no deadline". TODAY.md draws the lane sections; this ordering applies within each.

hard:

External or legal deadline only — visa, grant, contract, court, tax. A date the user picked himself is not hard. Only hard deadlines escalate, and away mode reports almost nothing else, so inflating this is what breaks the month-away case.

Threads = projects, and a project is one folder

A thread is one open loop. It is not a separate threads/ tree — a thread IS its project, and everything about that project lives in one folder, filed by lifecycle:

active/open/residence-permit/        (or active/awaiting/… or db/archive/…)
├── STATUS.md      deadline, status, summary — the narrative (hand-editable)
├── todo-*.md      the task entities
├── _files/        copies of the project's documents      ┐ mirrored by
├── _mail/         drafts + READY-TO-SEND composed emails  ┘ superme workspace
├── evidence/      the paper trail
└── _WORKSPACE.md  generated index: tasks · docs · mail · lifecycle

Open a thread when an obligation will outlive a single conversation. Close it by setting status: done in STATUS.md — the whole folder then graduates into db/archive/ on the next run; the folder is kept as the evidence trail (which is why ~/Desktop/email/DONE/ still exists). A live todo is never in db/: db is the settled store, and a todo that is not done has no place there.

superme workspace makes each folder self-contained by copying the project's real documents and emails in from the matching ~/Desktop/email/ACTIVE|DONE/<slug>/. Originals are never moved; the _ prefix keeps the copies out of the entity scan.

Lifecycle — open / awaiting / finished

PROJECTS.md (at the SUPERME root) groups every project by lifecycle, and the lifecycle is the folder location — computed from the thread status and its todos' lanes, never hand-set:

Lifecycle	Folder	Meaning
🟢 open	active/open/	has a live YOU/ME task — something is on the user's own plate
⏳ awaiting	active/awaiting/	still open, but every open task is WAITING on someone else
✅ finished	db/archive/	no open tasks left, or the thread/email folder is done/superseded

Move a task's lane or close it and the whole project folder re-files to the matching bucket on the next superme today / superme workspace.

Chasing

For a WAITING item set waiting_since and chase_on. WAITING.md reports who owes what and for how long, and flags anything past its chase date. Drafting the chase is ME; sending it is always YOU.