Migrate task management to dex

.changeset/tame-years-report.md

@@ -0,0 +1,13 @@
+---
+"@cephalization/math": major
+---
+
+feat: Migrate math task management to `dex`
+
+This is a breaking change and a complete refactor to how tasks are managed within math.
+
+We now leverage the excellent [dex](https://dex.rip) CLI tool for LLM native but human friendly task management.
+
+It has slightly more overhead than a simple markdown document, but it provides stronger ergonmics and skills to the LLM.
+
+`math` will prompt you to migrate any current TODO.md documents you have in flight, or you can finish your current work before migrating.

.dex/tasks.jsonl

@@ -0,0 +1,3 @@
+{"id":"1kr8etni","parent_id":null,"name":"update-loop-tests","description":"Update src/loop.test.ts to work with the new dex-based loop. Mock the dex module functions instead of TASKS.md file operations. Ensure existing test patterns for agent invocation and error handling still work.","priority":1,"completed":true,"result":"Updated loop.test.ts to use mock.module() for dex module mocking. Tests now use mock functions for isDexAvailable, dexStatus, dexListReady, and dexShow instead of creating TASKS.md files. Added new test describe block for dex integration testing including error handling cases.","metadata":null,"created_at":"2026-01-29T14:59:21.918Z","updated_at":"2026-01-29T15:04:17.279Z","started_at":"2026-01-29T14:59:31.348Z","completed_at":"2026-01-29T15:04:17.279Z","blockedBy":[],"blocks":[],"children":[]}
+{"id":"fnf2e6mx","parent_id":null,"name":"update-help-text","description":"Update index.ts help text to reflect dex integration. Mention that math uses dex for task management. Update example commands if needed. Ensure --help output is accurate for the new workflow.","priority":1,"completed":true,"result":"Updated help text in index.ts to reflect dex integration: changed tagline, description, command descriptions, added TASK MANAGEMENT section with common dex commands","metadata":null,"created_at":"2026-01-29T14:59:24.468Z","updated_at":"2026-01-29T15:09:23.756Z","started_at":"2026-01-29T15:08:04.277Z","completed_at":"2026-01-29T15:09:23.756Z","blockedBy":[],"blocks":[],"children":[]}
+{"id":"gcun61e9","parent_id":null,"name":"update-init-tests","description":"Update src/commands/init.test.ts for dex initialization. Test that dex init -y is called when no .dex/ exists. Test that existing .dex/ is reused. Test that PROMPT.md and LEARNINGS.md are still created but TASKS.md is not.","priority":1,"completed":true,"result":"Updated init.test.ts with 6 tests for dex initialization: tests verify dex init is called when no .dex exists, reused when exists, skipped when unavailable, and that TASKS.md is no longer created","metadata":null,"created_at":"2026-01-29T14:59:23.441Z","updated_at":"2026-01-29T15:07:29.750Z","started_at":"2026-01-29T15:05:14.479Z","completed_at":"2026-01-29T15:07:29.750Z","blockedBy":[],"blocks":[],"children":[]}

.math/backups/readme-updates/LEARNINGS.md

@@ -0,0 +1,63 @@
+# Project Learnings Log
+
+This file is appended by each agent after completing a task.
+Key insights, gotchas, and patterns discovered during implementation.
+
+Use this knowledge to avoid repeating mistakes and build on what works.
+
+---
+
+<!-- Agents: Append your learnings below this line -->
+<!-- Format:
+## <task-id>
+
+- Key insight or decision made
+- Gotcha or pitfall discovered
+- Pattern that worked well
+- Anything the next agent should know
+-->
+
+## update-readme-paths
+
+- README.md had exactly 2 locations with `todo/` references that needed updating: the `math init` section (line 73) and the `math iterate` section (line 133)
+- The old date-based format `todo-{M}-{D}-{Y}/` has been replaced with AI-generated summary names in `.math/backups/<summary>/`
+- Added a brief explanation of what `<summary>` means (AI-generated short description) with examples like `add-user-auth`, `fix-api-bugs`
+- Use `grep` to verify all path references are updated after making changes
+
+## add-directory-structure-table
+
+- Placed the directory structure table under Core Concept section as a "### Directory Structure" subsection since that's where document organization is already discussed
+- Kept to exactly 2 rows as specified: `.math/todo/` and `.math/backups/<summary>/`
+- Mentioned AI-generated descriptions in the backups row to connect with the earlier `math iterate` explanation
+- No tests needed for documentation-only changes, but ran `bun test` anyway to ensure nothing was accidentally broken
+
+## update-loop-diagram
+
+- The ASCII loop diagram (lines 166-178 in README.md) does NOT reference any file paths, only file names like `TASKS.md` and `PROMPT.md`
+- The diagram accurately reflects the current flow: check tasks → exit if complete → invoke agent → agent works → loop back
+- No changes were needed - the diagram was already correct
+- Verification-only tasks are valid - not all tasks require code changes
+
+## verify-cli-help
+
+- All help text in index.ts already uses the correct `.math/todo/` and `.math/backups/` paths
+- Found 3 `todo/` references at lines 34, 38, and 58 - all correctly prefixed with `.math/`
+- No standalone `todo/` references exist that need updating
+- The help output correctly describes: `init` creates `.math/todo/`, `iterate` backs up to `.math/backups/`, and `prune` deletes from `.math/backups/`
+- Verification-only tasks with no required changes are valid - document findings even when everything is already correct
+
+## verify-subcommand-help
+
+- Reviewed all 6 subcommand files in `src/commands/`: init.ts, run.ts, status.ts, iterate.ts, plan.ts, prune.ts
+- Used `grep "todo/"` to find 30 matches across all .ts files - all are correctly using `.math/todo/` or are intentionally referencing legacy `todo/` in migration code
+- Legacy `todo/` references in src/migration.ts and src/migration.test.ts are intentional - they handle migrating from old paths
+- No changes needed - all subcommand help text and descriptions already use correct `.math/` paths
+- Pattern: when verifying path references, grep for the short form (`todo/`) rather than full form (`.math/todo/`) to catch any missed updates
+
+## final-documentation-review
+
+- All `todo/` references in README.md (3 matches) and index.ts (3 matches) are correctly prefixed with `.math/`
+- Verified no bare `todo/` references exist that should have `.math/` prefix
+- "Todo" references in product name "Multi-Agent Todo Harness" and "TODO list" descriptions are correct usage (referring to concept, not directory)
+- Checked for old `todo-{date}` pattern - none found, confirming full migration to `.math/backups/<summary>/` format
+- Phase 3 final review confirmed all previous tasks were completed correctly - documentation is now fully consistent

.math/backups/readme-updates/PROMPT.md

@@ -0,0 +1,113 @@
+# Agent Task Prompt
+
+You are a coding agent implementing tasks one at a time.
+
+## Your Mission
+
+Implement ONE task from TASKS.md, test it, commit it, log your learnings, then EXIT.
+
+## The Loop
+
+1. **Read TASKS.md** - Find the first task with `status: pending` where ALL dependencies have `status: complete`
+2. **Mark in_progress** - Update the task's status to `in_progress` in TASKS.md
+3. **Implement** - Write the code following the project's patterns. Use prior learnings to your advantage.
+4. **Write tests** - For behavioral code changes, create unit tests in the appropriate directory. Skip for documentation-only tasks.
+5. **Run tests** - Execute tests from the package directory (ensures existing tests still pass)
+6. **Fix failures** - If tests fail, debug and fix. DO NOT PROCEED WITH FAILING TESTS.
+7. **Mark complete** - Update the task's status to `complete` in TASKS.md
+8. **Log learnings** - Append insights to LEARNINGS.md
+9. **Commit** - Stage and commit: `git add -A && git commit -m "feat: <task-id> - <description>"`
+10. **EXIT** - Stop. The loop will reinvoke you for the next task.
+
+---
+
+## Signs
+
+READ THESE CAREFULLY. They are guardrails that prevent common mistakes.
+
+---
+
+### SIGN: One Task Only
+
+- You implement **EXACTLY ONE** task per invocation
+- After your commit, you **STOP**
+- Do NOT continue to the next task
+- Do NOT "while you're here" other improvements
+- The loop will reinvoke you for the next task
+
+---
+
+### SIGN: Dependencies Matter
+
+Before starting a task, verify ALL its dependencies have `status: complete`.
+
+```
+❌ WRONG: Start task with pending dependencies
+✅ RIGHT: Check deps, proceed only if all complete
+✅ RIGHT: If deps not complete, EXIT with clear error message
+```
+
+Do NOT skip ahead. Do NOT work on tasks out of order.
+
+---
+
+### SIGN: Learnings are Required
+
+Before exiting, append to `LEARNINGS.md`:
+
+```markdown
+## <task-id>
+
+- Key insight or decision made
+- Gotcha or pitfall discovered
+- Pattern that worked well
+- Anything the next agent should know
+```
+
+Be specific. Be helpful. Future agents will thank you.
+
+---
+
+### SIGN: Commit Format
+
+One commit per task. Format:
+
+```
+feat: <task-id> - <short description>
+```
+
+Only commit AFTER tests pass.
+
+---
+
+### SIGN: Don't Over-Engineer
+
+- Implement what the task specifies, nothing more
+- Don't add features "while you're here"
+- Don't refactor unrelated code
+- Don't add abstractions for "future flexibility"
+- Don't make perfect mocks in tests - use simple stubs instead
+- Don't use complex test setups - keep tests simple and focused
+- YAGNI: You Ain't Gonna Need It
+
+---
+
+## Quick Reference
+
+| Action | Command |
+|--------|---------|
+| Run tests | `bun test` |
+| Typecheck | `bun run typecheck` |
+| Run CLI | `bun ./index.ts <command>` |
+| Stage all | `git add -A` |
+| Commit | `git commit -m "feat: ..."` |
+
+**Directory Structure:**
+- `.math/todo/` - Active sprint files (PROMPT.md, TASKS.md, LEARNINGS.md)
+- `.math/backups/<summary>/` - Archived sprints from `math iterate`
+
+---
+
+## Remember
+
+You do one thing. You do it well. You learn. You exit.

.math/backups/readme-updates/TASKS.md

@@ -0,0 +1,65 @@
+# Project Tasks
+
+Task tracker for multi-agent development.
+Each agent picks the next pending task, implements it, and marks it complete.
+
+## How to Use
+
+1. Find the first task with `status: pending` where ALL dependencies have `status: complete`
+2. Change that task's status to `in_progress`
+3. Implement the task
+4. Write and run tests
+5. Change the task's status to `complete`
+6. Append learnings to LEARNINGS.md
+7. Commit with message: `feat: <task-id> - <description>`
+8. EXIT
+
+## Task Statuses
+
+- `pending` - Not started
+- `in_progress` - Currently being worked on
+- `complete` - Done and committed
+
+---
+
+## Phase 1: README Updates
+
+### update-readme-paths
+
+- content: Update all `todo/` path references in README.md to `.math/todo/`. Update `math init` description to say it creates `.math/todo/` directory. Update the `math iterate` section to mention `.math/backups/<summary>/` instead of `todo-{M}-{D}-{Y}/`. Add brief explanation that summaries are AI-generated short descriptions of the sprint.
+- status: complete
+- dependencies: none
+
+### add-directory-structure-table
+
+- content: Add a brief table to README.md documenting the `.math/` directory structure. Include `.math/todo/` (active sprint files) and `.math/backups/` (archived sprints). Keep it to 2-3 rows with one-sentence descriptions each.
+- status: complete
+- dependencies: update-readme-paths
+
+### update-loop-diagram
+
+- content: Update the ASCII loop diagram in README.md if it references any old paths. Verify the diagram accurately reflects the current flow.
+- status: complete
+- dependencies: update-readme-paths
+
+## Phase 2: Help Output Verification
+
+### verify-cli-help
+
+- content: Run `bun ./index.ts --help` and verify all command descriptions reference `.math/` paths correctly. The help output should already be updated based on recent commits, but verify and fix any remaining `todo/` references in help strings in index.ts.
+- status: complete
+- dependencies: none
+
+### verify-subcommand-help
+
+- content: Check each subcommand for help text or descriptions that may reference old paths. Review index.ts for any command descriptions that need updating.
+- status: complete
+- dependencies: verify-cli-help
+
+## Phase 3: Final Review
+
+### final-documentation-review
+
+- content: Do a final grep for any remaining `todo/` references in README.md and index.ts that should be `.math/todo/`. Ensure consistency across all documentation. Skip code files - only documentation and help text.
+- status: complete
+- dependencies: add-directory-structure-table, update-loop-diagram, verify-subcommand-help