feat(tasks): add a folder-based task tracker (new / inprogress / done)

[fig-ai-agent]

Task tracker — new / inprogress / done

Additive only: 11 new files under new.inprogress.done/. Nothing existing is modified, moved, or deleted — verified with git diff --name-only (empty) against main.

Inspected before building

I checked the real repository rather than assuming:

• Fresh clone of main; the directory did not exist (no collision).
• Searched mht, tasks, todo across the repo, the org (gh search code), every branch/PR, and Issue pure-agent-dev #63 — nothing.
• Checked existing tracking files at root (task|todo|plan|roadmap|progress) — none.
• Confirmed which docs actually exist: CONTRIBUTING.md yes, AGENTS.md and COPILOT_INSTRUCTIONS.md do not — so nothing references them.
• Measured the documentation language: README.md and CONTRIBUTING.md contain 0 Thai characters, so the new docs are written in English to match the repository, not in Thai.

Structure

new.inprogress.done/
├── README.md                 purpose, statuses, create/move, file format,
│                             naming, Definition of Done, worked example
├── TASK_TEMPLATE.md          the template
├── new/example-task.md       worked example (real task, real blocker)
├── inprogress/.gitkeep
├── done/.gitkeep
├── done/TASK-20260910-001-issue63-pure-agent-dev.md
├── done/TASK-20260910-002-update-changelog-readme.md
├── inprogress/TASK-20260910-003-ncc-ci-sha-fix.md
├── tools/tasks.py            CLI (stdlib only)
└── tests/{conftest.py,test_tasks.py}

Status meanings

Folder	Means
new/	Understood, not started. May be blocked.
inprogress/	Started, not finished. Open work listed.
done/	Finished and verified — Definition of Done met.

Task file format

Front-matter (id, title, status, priority, created, updated, owner, repo, issue, prs, blocked_by, tokens) then fixed sections: Goal · Scope · Out of scope · Steps · Acceptance criteria · Dependencies/blockers · Files changed · Validation · Token usage · Notes · Completion summary.

The three things you asked to be reported — what was done, which files changed, whether tokens were used — are structural sections, not optional prose.

CLI

python3 new.inprogress.done/tools/tasks.py list      # tasks by status, [blocked] markers
python3 new.inprogress.done/tools/tasks.py report    # counts + total estimated tokens
python3 new.inprogress.done/tools/tasks.py new "Title"
python3 new.inprogress.done/tools/tasks.py move <id> done

move relocates the file and rewrites status:, so the two cannot disagree.

Definition of Done

A task enters done/ only when every step is complete or its omission is explained, every acceptance criterion is checked, the Validation table holds real commands and real results, and prs: names a merged PR or the task records a commit SHA. A task in done/ without evidence fails the test suite.

On tokens

tokens: uses this project's len(text) // 4 rule over the files a task lists. It is an estimate, not a measured API figure — real provider usage also includes the system prompt and session context. The README says this explicitly so nobody bills against it.

Verification

Command	Result
python3 -m pytest tests/	15 passed
tools/tasks.py list	works; 4 tasks across all three statuses, 2 blocked
tools/tasks.py report	works; counts + 73,600 estimated tokens
git diff --name-only vs main	empty — no tracked file modified
git status --short	only the new directory

Tests enforce the structure rather than trusting it: required front-matter keys, unique ids, ISO dates, status: matching the containing folder, a numeric tokens value, and a PR reference on anything in done/.

Two real bugs surfaced while writing them and were fixed in the tool: cmd_new substituted the title by placeholder text (silently did nothing when the template wording changed), and the move test caught that templates/ no longer exists — the template lives at the directory root.

Blocked work is recorded, not hidden

The seed tasks carry honest blockers in blocked_by:, which is why list prints [blocked]:

• TASK-20260910-003 (new-crystalcastle CI SHA fix) — blocked on repository write access.
• TASK-20260910-004 (this repo's Actions repair, the worked example) — blocked on write access to .github/workflows/; the App lacks the workflows permission.

Not done

• No application code touched. This is documentation and process only.
• The new-crystalcastle CI fix and this repo's workflow repair remain blocked and unstarted — recorded as tasks rather than quietly dropped.