Documentation sweep

.changeset/common-schools-cry.md

@@ -0,0 +1,5 @@
+---
+"@cephalization/math": patch
+---
+
+documentation

.math/todo/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/todo/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/todo/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

README.md

@@ -14,6 +14,13 @@ The primary responsibility of this harness is to **reduce context bloat** by dig
 
 The harness consists of a simple for-loop, executing a new coding agent with a mandate from `PROMPT.md` to complete a *single* task from `TASKS.md`, while reading and recording any insight gained during the work into `LEARNINGS.md`.
 
+### Directory Structure
+
+| Path | Description |
+| ---- | ----------- |
+| `.math/todo/` | Active sprint files (PROMPT.md, TASKS.md, LEARNINGS.md) |
+| `.math/backups/<summary>/` | Archived sprints from `math iterate`, named with AI-generated descriptions |
+
 ## Requirements
 
 **[Bun](https://bun.sh) is required** to run this tool. Node.js is not supported.
@@ -70,7 +77,7 @@ bun link
 math init
 ```
 
-Creates a `todo/` directory with template files and offers to run **planning mode** to help you break down your goal into tasks.
+Creates a `.math/todo/` directory with template files and offers to run **planning mode** to help you break down your goal into tasks.
 
 Options:
 
@@ -130,12 +137,14 @@ Shows task progress with a visual progress bar and next task info.
 math iterate
 ```
 
-Backs up `todo/` to `todo-{M}-{D}-{Y}/` and resets for a new goal:
+Backs up `.math/todo/` to `.math/backups/<summary>/` and resets for a new goal:
 
 - TASKS.md and LEARNINGS.md are reset to templates
 - PROMPT.md is preserved (keeping your accumulated "signs")
 - Offers to run planning mode for your new goal
 
+The `<summary>` is a short description of the completed sprint (e.g., `add-user-auth`, `fix-api-bugs`).
+
 Options:
 
 - `--no-plan` - Skip the planning prompt