Release v4.0.0b3

Release 4.0.0b3

This release introduces significant improvements to task lifecycle management with two powerful new commands for managing TODO.md files. The empty trash functionality automatically removes tasks from the Deleted section after 30 days, providing a clean safety net for accidentally deleted items while preventing TODO.md from growing indefinitely. Users no longer need to manually clean up deleted tasks, as the system now handles this transparently on startup.

The prune command offers powerful control over archived task retention with flexible filtering options. Users can remove archived tasks based on age thresholds using --days, specific task ranges with --from-task and --to-task, or individual task IDs. The command includes robust safety features such as automatic backups before pruning, git history analysis to determine archive dates, and preservation of task metadata for audit trails. All pruned tasks are saved to timestamped archive files in the .ai-todo/archives/ directory, enabling recovery if needed. Comprehensive usage examples are available in docs/examples/PRUNE_EXAMPLES.md.

Several bug fixes improve robustness and reliability. Timezone-aware datetime comparisons now work correctly across different system configurations in prune operations. Task ID sorting in archive backups uses proper numeric sorting to maintain correct task ordering. Regex metacharacter escaping prevents errors when working with tasks that contain special characters. Duplicate prevention in subtask operations ensures data integrity during complex task manipulations.

Python 3.10 compatibility has been fully restored by replacing datetime.UTC with timezone.utc throughout the codebase, ensuring the tool works reliably across all supported Python versions.

---

✨ Features

• Add branch-cleanup skill for automated branch maintenance (a893e9f)
• Add PEP 440 versioning strategy to release-please config (c818c22)
• Enable beta prerelease mode for 4.0.0 cycle (task#269.3) (25628d4)
• Enable beta release workflow (task#269.3) (f5312ec)
• Add Release Please configuration (task#269.3, Phase 1) (f2404c6)
• Enhance linear-release-workflow rule with feedback loop (aa87f80)
• Add automated release workflow rule with Linear tracking (bc37eb1)
• Implement empty trash functionality (task#268) (dae88da)
• Implement core prune functionality (task#267) (7195206)
• Linear integration implementation and review fixes (task#266) (aa6d373)
• Add commit guideline to ai-todo Cursor rule (task#265) (6867af4)
• Add Linear–ai-todo integration Cursor rule (d69d409)

🐛 Bug Fixes

• Add UTF-8 encoding for ascii-guard on Windows (task#272.5) (a6d3fab)
• Use PEP 440 format in release-please manifest (03ed8f4)
• Replace UTC with timezone.utc in source files for Python 3.10 (b2b02f9)
• Replace datetime.UTC with timezone.utc for Python 3.10 compatibility (04465f4)
• Disable prerelease config to use Release-As for beta versions (5d8f82e)
• Change extra-files type from python to generic (task#269.3) (ad7df4c)
• Exclude .ai-todo directory from CI markdown linting (task#268) (2b1bc6e)
• Use numeric sorting for task IDs in archive backups (task#267) (0e5e2ce)
• Prevent duplicate subtasks in task range pruning (task#267) (63f91a4)
• Use timezone-aware datetimes for prune age comparisons (task#267) (20a42ed)
• Make days parameter optional to respect filter precedence (task#267) (e099fec)
• Escape regex metacharacters in task IDs for git grep (task#267) (58d9b25)
• Use OR logic for git grep patterns in archive date detection (task#267) (d2acfc9)
• Correct backup header to reflect actual prune criteria (task#267) (ede65b3)
• Include TASK_METADATA in prune backup archives (task#267) (3183eee)
• Handle timezone comparison in prune date filtering (task#267) (50176d6)
• Correct username logic for Linear integration (task#266) (bb10c31)

🔧 Other Changes

• Update release log for 4.0.0b3 abort (3fba8ee)
• refactor: Remove redundant ascii-guard validation tests (task#272.5) (d3f8fe3)
• infra: Archive completed tasks (task#270, task#271, task#272) (9b85194)
• docs: ascii-guard linting (#80) (f7ca7af)
• infra: Incorrect branch names for linear issue (#79) (74f5ad7)
• infra: Incorrect branch names for linear issue (#78) (cfd9153)
• infra: Refactor release workflow to Cursor Skill (task#270) (#74) (457430a)
• Revert "feat: Enable beta release workflow (task#269.3)" (65b922f)
• docs: Add Phase 1 completion summary (task#269.3) (027dcba)
• docs: Update design with approved decisions (task#269.2) (3ec0467)
• docs: Address design feedback from Linear (task#269.2) (b7c921a)
• docs: Complete Release Please design document (task#269.2) (5813ec3)
• docs: Complete Release Please analysis (task#269.1) (6e55843)
• refactor: Rename release-automation.mdc to linear-release-workflow.mdc (b37b147)
• docs: Remove Pionizer references from OSS project (f514206)
• docs: Add empty trash documentation (task#268) (48ef24c)
• test: Add comprehensive tests for empty trash (task#268) (2909ed5)
• docs: Add auto empty trash after delete command (task#268) (b7aa75d)
• docs: Remove all backup functionality from empty trash design (task#268) (e128694)
• docs: Add empty trash design document (task#268) (8d61043)
• docs: Resolve open questions in analysis document (task#268) (3d7b1c3)
• docs: Remove legacy bash code from analysis document (task#268) (cce3764)
• docs: Update task#268 description with 30-day retention change ([b7677c7](b7677c7723dbe55617f49a...

v4.0.0b2

Release 4.0.0b2

This release addresses a critical bug (GitHub Issue #49) where archived tasks with incomplete subtasks would incorrectly reappear in the Tasks section when adding new tasks. The fix changes how task status is determined during parsing: section membership now takes precedence over checkbox state, ensuring that all tasks in "Recently Completed" or "Archived Tasks" sections are properly treated as archived regardless of their checkbox character.

Additionally, this release fixes the config://settings MCP resource to correctly report coordination.enabled status. Previously it was checking for a non-existent configuration key, causing it to always return false. The resource now properly derives the enabled state from the configured coordination type.

Both fixes include regression tests to prevent these issues from recurring. Users who experienced archived tasks unexpectedly appearing in their active task list should update to this version immediately.

---

✨ Features

• Add task#264 for GitHub Issue #49 - archived tasks reappearing bug (bbc4468)

🐛 Bug Fixes

• Prevent orphan subtasks from leaking into Tasks section (task#264) (2508033)
• Derive coordination.enabled from type instead of non-existent key (491842d)

🔧 Other Changes

• chore: Update release log for v4.0.0b2 (0885f41)
• docs: Prepare release notes for v4.0.0b2 (5adbd23)
• docs: Add AI release summary for v4.0.0b2 (ceeea5c)
• internal: Archive completed task#264 (GitHub Issue #49 fix) (be5c9b8)
• docs: Update CHANGELOG.md for v4.0.0b1 release (401ed5b)

Previous Beta Release Notes

Release 4.0.0b1

Breaking Changes

This release includes API terminology standardization (task#253) that aligns ai-todo with industry conventions. The MCP tools and CLI commands have been updated:

• add_task(description) → add_task(title, description?, tags?)
• add_subtask(parent_id, description) → add_subtask(parent_id, title, description?, tags?)
• modify_task(task_id, description) → modify_task(task_id, title, description?, tags?)
• add_note, update_note, delete_note → set_description(task_id, description)
• New: set_tags(task_id, tags) for dedicated tag management

Legacy shell scripts have been frozen with a FROZEN header for backward compatibility but are no longer actively maintained.

New Features

MCP Resources (task#262, GitHub Issue #48): AI agents can now access task data via MCP resources - tasks://open for pending tasks, tasks://active for in-progress work, tasks://{id} for individual task details, and config://settings for configuration. This enables IDE integrations to display real-time task status without explicit tool calls.

Task Metadata Persistence (task#263): Task timestamps (created_at, updated_at) are now persisted across sessions via hidden HTML comments in TODO.md. Timestamps are lazily backfilled when tasks are modified, ensuring accurate tracking without migration scripts. Completion dates continue to appear inline for human readability.

Batch Operations (task#261, GitHub Issue #31): The complete, delete, archive, and restore commands now accept multiple task IDs in a single call, reducing round-trips when managing multiple tasks. Both MCP tools and CLI support this batch interface.

Security & Reliability

.cursorignore Protection (task#260, GitHub Issue #29): Added .cursorignore patterns to prevent AI agents from directly accessing tamper detection state files. Security best practices documentation added at docs/guides/SECURITY_BEST_PRACTICES.md.

Bug Fixes: Fixed TASK_METADATA being incorrectly captured as interleaved content, causing subtask display issues. Resolved archive/delete task ordering bug where parent tasks were processed before subtasks (task#242). Restored GitHub task number coordination posting (task#247).

---

🔴 Breaking Changes

• feat!: Implement API terminology standardization (task#253) (338d0eb)

✨ Features

• Implement task metadata persistence for timestamps (task#263) (b9500b8)
• Add MCP resources for task data and begin metadata design (task#262, task#263) (b07b27c)
• Implement .cursorignore security for ai-todo state files (task#260) (d8552d3)
• Implement batch operations for task state commands (task#261) (1e1b0e2)
• Add tasks for API terminology standardization and legacy freeze (task#253, task#254) (3aa79c7)
• Add restart MCP tool for dev mode quick-reload (task#250) (7957cbd)
• Add version pinning and constraints to self-update feature (task#245) (c118e2d)
• Implement self-update feature with MCP and CLI support (task#241) (4b59823)
• Add task #242 to investigate archive/delete task ordering bug (4f50342)
• Add task #241 for self-update feature via uv with MCP server shutdown (090cd53)

🐛 Bug Fixes

• Prevent TASK_METADATA from being captured as interleaved content (d075259)
• Windows CI failure in test_default_path (6b16b01)
• Restore GitHub task number coordination posting (task#247) (78314b0)
• Resolve archive/delete task ordering bug - parent before subtasks (task#242) (e7e4a82)
• Update version comment to 3.0.2 in shell scripts (d449997)

🔧 Other Changes

• docs: Add AI release summary for v4.0.0 (6d34739)
• chore: Archive task#262, task#263 (MCP resources and metadata persistence) (4986bc0)
• chore: Archive task#260, task#261 and clean up task#51 subtasks (287c6b0)
• chore: Freeze legacy shell scripts and remove parity tests (task#254) (ec714af)
• chore: Archive completed tasks #239, #240, #241, #242, #245, #246 (df65839)
• test: Add unit test for archived task reordering (task#246) (f63b013)

Previous Release Notes

Release 3.0.2

This release fixes a critical bug where TODO.md files became malformed when adding multiple subtasks via MCP on fresh repositories. The issue caused orphaned timestamp lines to accumulate in the file, breaking the expected format. The fix ensures footer timestamps are properly handled and always regenerated cleanly, while also updating the branding from legacy "todo.ai" to "ai-todo" in default headers.

The cursor rule generator that installs rules in new projects now documents that tasks are displayed in reverse chronological order (newest on top), helping prevent confusion about the intentional task ordering behavior.

---

🐛 Bug Fixes

• Resolve malformed TODO.md on fresh repos with multiple subtasks (task#240) (cddfb9d)

🔧 Infrastructure

• Add fastmcp 3.x compatibility testing in CI (task#239) (661253b)

v4.0.0b1

Release 4.0.0b1

Breaking Changes

This release includes API terminology standardization (task#253) that aligns ai-todo with industry conventions. The MCP tools and CLI commands have been updated:

• add_task(description) → add_task(title, description?, tags?)
• add_subtask(parent_id, description) → add_subtask(parent_id, title, description?, tags?)
• modify_task(task_id, description) → modify_task(task_id, title, description?, tags?)
• add_note, update_note, delete_note → set_description(task_id, description)
• New: set_tags(task_id, tags) for dedicated tag management

Legacy shell scripts have been frozen with a FROZEN header for backward compatibility but are no longer actively maintained.

New Features

MCP Resources (task#262, GitHub Issue #48): AI agents can now access task data via MCP resources - tasks://open for pending tasks, tasks://active for in-progress work, tasks://{id} for individual task details, and config://settings for configuration. This enables IDE integrations to display real-time task status without explicit tool calls.

Task Metadata Persistence (task#263): Task timestamps (created_at, updated_at) are now persisted across sessions via hidden HTML comments in TODO.md. Timestamps are lazily backfilled when tasks are modified, ensuring accurate tracking without migration scripts. Completion dates continue to appear inline for human readability.

Batch Operations (task#261, GitHub Issue #31): The complete, delete, archive, and restore commands now accept multiple task IDs in a single call, reducing round-trips when managing multiple tasks. Both MCP tools and CLI support this batch interface.

Security & Reliability

.cursorignore Protection (task#260, GitHub Issue #29): Added .cursorignore patterns to prevent AI agents from directly accessing tamper detection state files. Security best practices documentation added at docs/guides/SECURITY_BEST_PRACTICES.md.

Bug Fixes: Fixed TASK_METADATA being incorrectly captured as interleaved content, causing subtask display issues. Resolved archive/delete task ordering bug where parent tasks were processed before subtasks (task#242). Restored GitHub task number coordination posting (task#247).

---

🔴 Breaking Changes

• feat!: Implement API terminology standardization (task#253) (338d0eb)

✨ Features

• Implement task metadata persistence for timestamps (task#263) (b9500b8)
• Add MCP resources for task data and begin metadata design (task#262, task#263) (b07b27c)
• Implement .cursorignore security for ai-todo state files (task#260) (d8552d3)
• Implement batch operations for task state commands (task#261) (1e1b0e2)
• Add tasks for API terminology standardization and legacy freeze (task#253, task#254) (3aa79c7)
• Add restart MCP tool for dev mode quick-reload (task#250) (7957cbd)
• Add version pinning and constraints to self-update feature (task#245) (c118e2d)
• Implement self-update feature with MCP and CLI support (task#241) (4b59823)
• Add task #242 to investigate archive/delete task ordering bug (4f50342)
• Add task #241 for self-update feature via uv with MCP server shutdown (090cd53)

🐛 Bug Fixes

• Prevent TASK_METADATA from being captured as interleaved content (d075259)
• Windows CI failure in test_default_path (6b16b01)
• Restore GitHub task number coordination posting (task#247) (78314b0)
• Resolve archive/delete task ordering bug - parent before subtasks (task#242) (e7e4a82)
• Update version comment to 3.0.2 in shell scripts (d449997)

🔧 Other Changes

• docs: Add AI release summary for v4.0.0 (6d34739)
• chore: Archive task#262, task#263 (MCP resources and metadata persistence) (4986bc0)
• chore: Archive task#260, task#261 and clean up task#51 subtasks (287c6b0)
• chore: Freeze legacy shell scripts and remove parity tests (task#254) (ec714af)
• chore: Archive completed tasks #239, #240, #241, #242, #245, #246 (df65839)
• test: Add unit test for archived task reordering (task#246) (f63b013)

Previous Release Notes

Release 3.0.2

This release fixes a critical bug where TODO.md files became malformed when adding multiple subtasks via MCP on fresh repositories. The issue caused orphaned timestamp lines to accumulate in the file, breaking the expected format. The fix ensures footer timestamps are properly handled and always regenerated cleanly, while also updating the branding from legacy "todo.ai" to "ai-todo" in default headers.

The cursor rule generator that installs rules in new projects now documents that tasks are displayed in reverse chronological order (newest on top), helping prevent confusion about the intentional task ordering behavior.

---

🐛 Bug Fixes

• Resolve malformed TODO.md on fresh repos with multiple subtasks (task#240) (cddfb9d)

🔧 Infrastructure

• Add fastmcp 3.x compatibility testing in CI (task#239) (661253b)

v3.0.2

Release 3.0.2

This release fixes a critical bug where TODO.md files became malformed when adding multiple subtasks via MCP on fresh repositories. The issue caused orphaned timestamp lines to accumulate in the file, breaking the expected format. The fix ensures footer timestamps are properly handled and always regenerated cleanly, while also updating the branding from legacy "todo.ai" to "ai-todo" in default headers.

The cursor rule generator that installs rules in new projects now documents that tasks are displayed in reverse chronological order (newest on top), helping prevent confusion about the intentional task ordering behavior.

---

🐛 Bug Fixes

• Resolve malformed TODO.md on fresh repos with multiple subtasks (task#240) (cddfb9d)

🔧 Infrastructure

• Add fastmcp 3.x compatibility testing in CI (task#239) (661253b)

v3.0.1

Release 3.0.1

ai-todo v3.0.1 Release Summary

This patch release fixes a bug in the archive cooldown feature and updates CI/CD dependencies.

Bug Fix: The archive cooldown (which prevents AI agents from immediately archiving completed tasks) was incorrectly triggering for all tasks because completed_at timestamps were reset to datetime.now() when parsing TODO.md. The cooldown is now session-based in the MCP server, only blocking archival of tasks completed within the current session. This allows archiving of previously completed tasks while still protecting against overeager agents archiving tasks immediately after completion.

Infrastructure: Updated GitHub Actions dependencies via Dependabot: actions/checkout v6, actions/setup-python v6, actions/cache v5, astral-sh/setup-uv v7, and markdownlint-cli2-action v22.

---

🐛 Bug Fixes

• Make archive cooldown session-based in MCP server (683fa05)

🔧 Other Changes

• docs: Add AI release summary for v3.0.1 (461399b)
• chore: Archive completed v3.0 release tasks (fc4c6f8)
• chore(deps): Bump astral-sh/setup-uv from 3 to 7 (dede9b0)
• chore(deps): Bump actions/cache from 4 to 5 (0c13116)
• chore(deps): Bump DavidAnson/markdownlint-cli2-action from 20 to 22 (934deef)
• chore(deps): Bump actions/checkout from 4 to 6 (4121abf)
• chore(deps): Bump actions/setup-python from 5 to 6 (eedcd0a)

v3.0.0

Release 3.0.0

ai-todo v3.0.0 Release Summary

ai-todo v3.0.0 represents a complete rewrite of the project, evolving from a shell-based task management tool into a modern, production-ready Python package. The MCP server and CLI are now unified into a single executable (ai-todo), providing seamless integration with AI assistants like Cursor while maintaining a powerful command-line interface. Installation is as simple as pip install ai-todo or uv tool install ai-todo, and the package is published via PyPI with secure OIDC-based trusted publishing.

This major release introduces several key features for data integrity and workflow safety. A tamper detection system protects TODO.md from unintended external modifications, with configurable security modes and automatic recovery options. An archive cooldown (60-second default) prevents AI agents from prematurely archiving completed tasks, requiring human review for root tasks. The new start/stop commands allow marking tasks as in-progress with #inprogress tags. The delete command now removes subtasks by default, and deleted tasks display with [D] markers instead of confusing checkmarks.

The architecture has been significantly modernized. The Python implementation uses FastMCP for the MCP server with full async support. The CLI uses Click with rich help text. A comprehensive CI/CD pipeline on GitHub Actions handles testing across Python 3.13+ on Ubuntu, macOS, and Windows, with automated PyPI publishing on tagged releases. The data directory migrated from .todo.ai/ to .ai-todo/ with automatic migration for existing users. Legacy shell scripts remain available but are deprecated. The MCP/CLI tool set was audited and streamlined from 37 to 27 tools, removing redundant operations and standardizing naming conventions.

---

🔴 Breaking Changes

• feat!: Major release v3.0.0 - Python Rewrite (task#163) (28fb9bd)

✨ Features

• Add beta-to-stable graduation logic for releases (task#238.11) (a8fcd6e)
• Add archive cooldown protection for root tasks (task#205) (aa54253)
• Implement MCP/CLI tools audit cleanup (task#238.4) (d4b1969)
• Implement data directory migration .todo.ai/ → .ai-todo/ (task#219.6) (718d3f3)
• Complete Task #210 - Tamper Detection System (147cc67)
• Implement dual logging strategy (shared + local audit log) (8c62862)
• Implement Tamper Detection System (task#210.4, task#210.5) (b1fb0bd)
• Add task#211 to fix subtask alphabetical sorting bug (0bef627)
• Add task#210 for TODO.md tamper detection (task#210) (b53eb33)
• Implement TODO.md visual standards (task#200) (08ab23c)
• Implement 'start' and 'stop' commands with MCP support (task#201) (066bb60)
• Design 'start' command architecture (task#201) (813e36f)
• Enhance task management with ordering fixes and linting tools (e595b0e)
• Unify CLI and MCP server into single executable with FastMCP (4228a45)
• remove update-note confirmation prompt (task#185) (b95f09e)
• remove delete-note confirmation prompt (task#184) (8e14e4c)
• add show-root parity tests (task#182.5, task#182.6) (429af92)
• add pinned root resolution (task#182.4) (42733df)
• add task#182 for pinned directory design (c845a42)
• Add --abort command to clean up failed releases (1dee0af)
• Implement clean release dependencies with Python PEP 440 validation (7305dd0)
• Fix release workflow dependencies and sequencing (task#177) (7443ce9)
• Improve workflow run naming and version commit message (7268a41)
• Add dynamic workflow names with emojis for clarity (task#177) (450c7fe)
• Add three-layer defense against forbidden flags (task#175) (1b603bf)
• Switch to PyPI Trusted Publisher (OIDC) for secure publishing (task#174.6) (c3161f5)
• Enhance error messages with remediation steps (task#172.2.3) (8bdd11c)
• Implement Phase 2 hardening for beta releases (task#172.2) (de286c6)
• Implement Phase 1 of beta/pre-release strategy (task#172.1) (9670ea5)
• Make code quality a prerequisite for all tests (task#171) (9a0ff44)
• Improve CI job naming with comprehensive vs quick test grouping (task#171) (0048408)
• Optimize CI/CD workflow and pre-commit configuration (task#169) (f68337c)
• Add detailed CI/CD optimization task list with phases (task#169) (d2f489f)
• Implement Phase 15 - Cleanup (task#163.51) (d99534c)
• Implement Phase 14 - Simplify Commands (task#163.50) (e9bedf1)
• Implement Phase 13 - Remove Old State Variables (task#163.49) (e5058eb)
• Implement Phase 12 - Use Snapshot for Generation (task#163.48) (0b84518)
• Implement Phase 11 - Create Structure Snapshot (task#163.47) (b0d23ae)
• Implement Phase 10 - Enhanced Parsing for interleaved content (task#163.46) (154e2f4)
• Add dataset parity tests for all commands (task#163.44.4) (c0f6ac5)
• Add feature parity validation tests (task#163.44.3) (8df5282)
• Add MCP tool integration tests (task#163.44.2) (98f5aa4)
• Add comprehensive integration tests for all CLI commands (task#163.44.1) (8dc382e)
• Implement Phase 8 - MCP Server Completion (task#163.43) (0bc250a)
• Implement Phase 7 - Utility Commands (task#163.42) (5129d5c)
• Implement Phase 5 & 6 - System Operations and Configuration (task#163.40, task#163.41) (9810082)
• Implement Phase 3 - Task Display and Relationships (task#163.38) (5842079)
• Implement Phase 2 - Note Management (task#163.37) (d62b0a3)
• Implement Phase 1 - Core Task Management Operations (task#163.36) (d8fa8e3)
• Complete CI/CD Phase 3 - coverage, multi-OS testing, and docs validation (task#167.7, task#167.8, task#167.9) (acc3d41)
• Integrate release.sh with GitHub Actions release workflow (task#167.6) ([36b...

v3.0.0b18

Release 3.0.0b18

Release Summary: v3.0.0b18

Major Naming Unification

This release completes a comprehensive rename from todo.ai to ai-todo across the entire project. The unified naming eliminates confusion between the various component names by standardizing on ai-todo everywhere: CLI command, PyPI package, GitHub repository, and data directory.

Key changes:

• CLI command: todo-ai → ai-todo
• Data directory: .todo.ai/ → .ai-todo/ (automatic migration on startup)
• Python package: todo_ai/ → ai_todo/
• GitHub repository: Renamed to ai-todo
• Shell scripts: Moved to legacy/ directory (deprecated)

The migration is fully transparent - the tool automatically detects and migrates old .todo.ai/ directories to .ai-todo/ on first run.

Additional Improvements

• 3-level task nesting: Tasks can now have sub-subtasks (e.g., #1.2.3)
• Simplified MCP configuration: uvx config no longer requires redundant --from flag
• Test isolation: Shell tests now properly isolated to prevent pollution of project root
• Documentation overhaul: All docs updated with MCP-first approach and simplified examples

---

✨ Features

• Implement data directory migration .todo.ai/ → .ai-todo/ (task#219.6) (718d3f3)

🐛 Bug Fixes

• Update convert script for legacy/todo.ai path (9e4d96e)
• Update release script for ai-todo naming (legacy/todo.ai, ai_todo/) (910ba94)
• Only ignore legacy .todo.ai/ directory, keep .ai-todo/ tracked (86884ea)
• Isolate shell tests to prevent .todo.ai pollution (3686545)
• Update tests for ai-todo naming and legacy shell path (task#219) (b72cab3)
• Allow 3-level task nesting (task.subtask.sub-subtask) (70ea225)

🔧 Other Changes

• docs: Add AI release summary for v3.0.0b18 (33d750d)
• docs: Simplify uvx MCP configuration (remove redundant --from) (5008698)
• chore: Remove accidentally re-added .todo.ai directory (ed1b2e0)
• docs: Add AI release summary for v3.0.0b18 (02989af)
• chore: Clean up deleted tasks and orphaned subtasks (eab3b9c)
• docs: Remove redundant example from task structure rule (80fdcdd)
• docs: Add task list vs tasks guidance to cursor rules (2d7cad5)
• internal: Update GitHub URLs to ai-todo (task#219) (992024c)
• docs: Update user-facing documentation for ai-todo naming (task#219.8) (562add0)
• internal: Update Cursor rules for ai-todo naming (task#219) (aadc42c)
• internal: Deprecate shell scripts (task#219) (589a4d2)
• internal: Update tests and CI for ai_todo (task#219) (73ab83b)
• internal: Rename todo_ai/ to ai_todo/ (task#219.1.1) (45f0916)
• docs: Create naming implementation plan (task#219.3) (3093eb9)
• docs: Add task#219.8 for documentation updates and bug task#222 (2a040c7)
• docs: Add bug task#221 - delete task leaves orphaned subtasks (ad98920)
• docs: Add Decision 9 - rename data directory .todo.ai/ to .ai-todo/ (task#219.1) (fdf0064)
• docs: Add Decision 8 - update all Cursor rules to ai-todo (task#219.1) (d1728eb)
• docs: Add Decision 7 - rename todo_ai/ to ai_todo/ (task#219.1) (9ad200f)
• docs: Record all naming decisions (task#219.1) (eff261c)
• docs: Record naming decisions in analysis (task#219.1) (f321b94)
• docs: Remove Next Steps from naming analysis (task#219.1) (107df89)
• docs: Create naming unification analysis (task#219.1) (f271499)
• chore: Start task#219.1 (naming analysis) (787b057)
• docs: Add task#219 for unified naming decision (ai-todo) (6b221a4)
• docs: Update referenced documentation for MCP-first approach (task#203) (1d785c9)
• docs: Add subtasks for referenced documentation updates (task#203) (8072a8d)
• docs: Implement README redesign with MCP-first approach (task#203) (e2bba2f)
• docs: Add isolation requirement note to task#203.4 (591ee1e)
• docs: Update task#203 subtasks for implementation workflow (10f7298)
• docs: Remove Next Steps section from README redesign doc (task#203.1) (9e1db38)
• docs: Update README redesign with design decisions (task#203.1) (372bb32)
• chore: Add summary note to task#203 (8baed6a)
• chore: Start task#203.1 and add design document note (fec6fca)
• docs: Create README redesign design document (task#203.1) (27cc167)
• chore: Archive completed tasks #216, #217 (981365d)
• chore: Archive completed task#218 (Simplify Cursor rules) (efaa729)

Previous Beta Release Notes

Release 3.0.0b17

Summary

This release introduces the Tamper Detection System, a significant new feature that protects TODO.md integrity by detecting external modifications. When enabled, todo.ai maintains a shadow copy and checksum of TODO.md, alerting users if the file is modified outside of todo.ai tools. This is an opt-in feature that helps maintain task consistency in collaborative or automated environments.

Several important bug fixes improve the overall experience. Subtask sorting now uses numerical comparison instead of alphabetical, ensuring task#10 appears after task#9 rather than after task#1. The restore command has been fixed to correctly position both root tasks and subtasks. A whitespace conflict between todo.ai and pre-commit hooks has been resolved, and UTF-8 encoding is now explicitly specified for Windows compatibility.

Documentation and developer experience have been enhanced with simplified Cursor rules that are more concise and actionable. The TODO.md visual standards have been implemented to ensure consistent formatting, and the tamper detection documentation clearly explains the feature as an optional integrity tool rather than a security mechanism.

---

✨ Features

• Complete Task #210 - Tamper Detection System (147cc67)
• Implement dual logging strategy (shared + local audit log) (8c62862)
• Implement Tamper Detection System (task#210.4, task#210.5) (b1fb0bd)
• Add task#211 to fix subtask alphabetical sorting bug (0bef627)
• Add task#210 for TODO.md tamper detection (task#21...

v3.0.0b17

Release 3.0.0b17

Summary

This release introduces the Tamper Detection System, a significant new feature that protects TODO.md integrity by detecting external modifications. When enabled, todo.ai maintains a shadow copy and checksum of TODO.md, alerting users if the file is modified outside of todo.ai tools. This is an opt-in feature that helps maintain task consistency in collaborative or automated environments.

Several important bug fixes improve the overall experience. Subtask sorting now uses numerical comparison instead of alphabetical, ensuring task#10 appears after task#9 rather than after task#1. The restore command has been fixed to correctly position both root tasks and subtasks. A whitespace conflict between todo.ai and pre-commit hooks has been resolved, and UTF-8 encoding is now explicitly specified for Windows compatibility.

Documentation and developer experience have been enhanced with simplified Cursor rules that are more concise and actionable. The TODO.md visual standards have been implemented to ensure consistent formatting, and the tamper detection documentation clearly explains the feature as an optional integrity tool rather than a security mechanism.

---

✨ Features

• Complete Task #210 - Tamper Detection System (147cc67)
• Implement dual logging strategy (shared + local audit log) (8c62862)
• Implement Tamper Detection System (task#210.4, task#210.5) (b1fb0bd)
• Add task#211 to fix subtask alphabetical sorting bug (0bef627)
• Add task#210 for TODO.md tamper detection (task#210) (b53eb33)
• Implement TODO.md visual standards (task#200) (08ab23c)

🐛 Bug Fixes

• Skip cursor rules auto-generation in development repository (task#218) (999c1ed)
• Add explicit UTF-8 encoding to read_text() calls for Windows (task#217) (44ef639)
• Normalize date and section header differences in parity tests (task#217) (8df5d1e)
• Restore file structure preservation logic (Task #216) (a310b17)
• Restore Task #213 and verify whitespace fix (c2d5703)
• Resolve whitespace conflict between todo.ai and pre-commit hooks (Task #213) (a9c5b92)
• Fix subtask sorting to use numerical comparison instead of alphabetical (task#211) (723fb4e)
• Resolve orphaned subtasks by restoring and re-archiving parent tasks (0edd165)
• Remove outdated 'Remaining' note from completed task#200 (4632752)
• Fix restore command positioning for root tasks and subtasks (task#200) (622d48f)
• Enforce strict spacing and fix date duplication in TODO.md (665863b)

🔧 Other Changes

• chore: Update TODO.md state (1faffcd)
• docs: Add AI release summary for v3.0.0b17 (b2d64e9)
• docs: Simplify cursor-rules-guidelines.mdc (task#218) (0af93c4)
• docs: Simplify todo-ai-interaction.mdc Cursor rule (task#218) (6bdea0a)
• docs: Simplify release-workflow.mdc Cursor rule (task#218) (5992767)
• docs: Add AI release summary for v3.0.0b17 (8506858)
• test: Update parity tests to ignore header/footer differences (Task #217) (d954d98)
• chore: Archive Task #213 (Whitespace conflict resolution) (8452d9e)
• chore: Complete Task #213 (Whitespace conflict resolution) (ea5f5c8)
• chore: Delete Task #215 (Jokes collection) (2be81ab)
• chore: Update Task #213 subtasks to completed (e7aa5b0)
• docs: Add analysis for whitespace conflict and track Task #213 (de93752)
• chore: Archive completed task #212 (8e3d7bf)
• chore: Complete Task #212 and add .cursorignore (b6cfec6)
• chore: Consolidate and update Cursor rules for MCP-first workflow (Task #212) (472423d)
• Archive completed task #210 (Tamper Detection System) (3c84eab)
• docs: Tone down tamper detection description in dev guidelines (7bbdcb1)
• docs: Remove reference to todo-ai edit command (158be11)
• docs: Emphasize tamper detection is optional and passive by default (66f496b)
• docs: Clarify tamper detection is for integrity not security (86550b3)
• docs: Tone down tamper detection description (96e897c)
• docs: Document Tamper Detection feature (Task #210.6) (9a744de)
• chore: Protect integrity files from manual edits in VS Code (e69987b)
• chore: Configure IDE read-only mode and finalize state directory refactor (e2a0fa3)
• refactor: Move tamper detection state to .todo.ai/state/ (c793321)
• docs: Complete research and design for tamper detection (task#210.2, task#210.3) (30ce4f6)
• Archive completed tasks #211, #125, #126, #161 (8bfd633)
• docs: Complete task#210.1 - Analyze TODO.md tamper detection (2805473)
• chore: Archive completed task#200 (visual standards) (dee09ec)
• chore: Update task serial for task#210 (5c2b3bd)
• docs: Complete task#200 - TODO.md visual standards implementation (4e7ca8e)
• docs: Complete task#200.6 - Document TODO.md visual standards (0f3b361)
• docs: Simplify task#200 notes to concise summary (fccd7bb)
• docs: Add test subtasks for visual standards validation (task#200) (b3d5624)
• docs: Update TODO.md with refined task#200 subtasks (7be709c)
• docs: Create TODO.md visual standards design document (task#200.2) (a4c5417)

Previous Beta Release Notes

Release 3.0.0b16

This beta release brings significant improvements to task workflow management and cross-version compatibility. The headline feature is the new start and stop commands, which allow you to mark tasks as in-progress and track active work across sessions. When you start a task, it automatically gets tagged with #inprogress, and AI agents using the MCP server can now see which tasks are actively being worked on t...

v3.0.0b16

Release 3.0.0b16

This beta release brings significant improvements to task workflow management and cross-version compatibility. The headline feature is the new start and stop commands, which allow you to mark tasks as in-progress and track active work across sessions. When you start a task, it automatically gets tagged with #inprogress, and AI agents using the MCP server can now see which tasks are actively being worked on through a dedicated status prompt. This makes it easier to maintain context across multiple coding sessions and prevents duplicate work on the same tasks.

The Python CLI has been upgraded to support Python 3.14 while maintaining full backward compatibility with Python 3.10 through 3.13, ensuring the tool works across a wide range of environments. We've also fixed several important bugs that improve reliability: the restore command now correctly restores subtasks in the proper order and preserves their completion status, the --root parameter now works correctly in the Python CLI (it was previously being ignored), and test isolation has been significantly improved to prevent cross-test contamination.

Behind the scenes, we've enhanced the development infrastructure with integrated todo-ai lint checks in pre-commit hooks and CI/CD pipelines, ensuring consistent TODO.md formatting across all contributions. The test suite now includes comprehensive parity validation between the shell script and Python CLI, with better environment isolation and more robust path resolution. These improvements make todo.ai more reliable and maintainable for both users and contributors.

---

✨ Features

• Implement 'start' and 'stop' commands with MCP support (task#201) (066bb60)
• Design 'start' command architecture (task#201) (813e36f)
• Enhance task management with ordering fixes and linting tools (e595b0e)

🐛 Bug Fixes

• Make Python CLI respect --root parameter and fix test isolation (task#207) (e747422)
• Clear TODO_FILE environment variable in parity tests (task#206) (ed3649b)
• Suppress cursor rules initialization and mode display during tests (task#206) (851545e)
• Populate completed_at for archived tasks in FileOps (task#204) (a1be429)
• Preserve completion status when restoring tasks (task#204) (2fe9881)
• Restore subtasks in reverse-chronological order (task#204) (1994bfe)
• Restore subtasks recursively and idempotently (task#204) (6ba67bf)
• Update archive_task MCP tool signature to match CLI default (with_subtasks=True) (99240d6)

🔧 Other Changes

• Archive completed tasks #202, #206, #207 (716410b)
• docs: Add task#207 to fix newly discovered parity issues (6254488)
• docs: Complete task#206 (shell script test failures fix) (8e0477b)
• docs: Complete investigation subtasks for task#206 (e6dffb4)
• docs: Add task#206 to fix shell script test failures (09330fd)
• docs: Complete task#202 (Python 3.14 upgrade with legacy support) (4ac8da3)
• docs: Archive completed task#204 (68b74c9)
• docs: Add task#205 to prevent premature task archiving (8db76bb)
• docs: Mark completed subtasks for task#204 (6b0c491)
• docs: Add commentary to pre-commit config explaining local execution (64d3268)
• infra: Use direct module execution for pre-commit lint hook (97be314)
• style: Reorder subtasks for task#204 (2705757)
• chore: Reopen task#204 to fix restore behavior (preserve completion status) (18162a9)
• chore: Start task#204 (Fix restore ordering bug) (e74017c)
• chore: Reopen task#204 to fix subtask ordering bug (ea91213)
• style: Reorder subtasks for task#202 (59be33b)
• chore: Restore task#202 to pending state (7fb0489)
• chore: Start task#204 (Fix restore subtasks bug) (de685cd)
• docs: Add requirement for idempotent/self-healing restore (task#204) (86e0aaf)
• docs: Add task#204 to fix restore subtasks bug (b9a0fa0)
• infra: Restore legacy Python support (3.10-3.13) while keeping 3.14 preferred (task#202) (7e54e29)
• docs: Archive completed task#202 (a51b0d8)
• infra: Upgrade to Python 3.14 and update dependencies (task#202) (a559e71)
• chore: Start task#202 (Python 3.14 upgrade) (8b09b16)
• docs: Archive completed task#201 (5f1c4bf)
• docs: Add task#203 for README.md redesign (v3.0 migration) (79709cc)
• docs: Clarify that 'stop' command is optional (task#201) (d0b0fe9)
• docs: Document 'start' and 'stop' commands (task#201) (a379d8b)
• docs: Add 'stop' command to design and task list (task#201) (0628794)
• docs: Update 'start' command design with dedicated status tool (task#201) (b6c7207)
• docs: Update 'start' command design with MCP Prompts (task#201) (0cfa53b)
• docs: Merge task#193 into task#201 (ecd0fe5)
• docs: Add task#202 for Python 3.14 upgrade and dependency updates (96612dd)
• docs: Archive completed task#196 (4925514)
• infra: Enhance Pre-commit and CI/CD with todo-ai linting (task#196) (6f96c18)
• docs: Add task#201 for start command design and implementation (4b37121)
• docs: Archive completed task#188 (9bd1941)
• docs: Archive completed task#195 (8d3e843)
• docs: Archive completed tasks and update README with new commands (a553801)
• docs: Update task status for recent completions (d518f1f)
• docs: Update task status and documentation for linting features (7ab6856)
• docs: Update task status for unified executable release (a2fcb61)

Previous Beta Release Notes

Release 3.0.0b15

This release introduces a major architectural unification, combining the CLI and MCP server into a single `todo-ai...

v3.0.0b15

Release 3.0.0b15

This release introduces a major architectural unification, combining the CLI and MCP server into a single todo-ai executable. The MCP server has been completely rewritten using the modern FastMCP framework, significantly improving maintainability and performance. A new serve command (todo-ai serve) has been added to launch the MCP server, with support for a --root argument to ensure correct project context awareness.

Documentation and Cursor rules have been updated to reflect these changes, guiding AI agents to prefer the MCP interface over CLI commands. The release also includes comprehensive updates to the installation guides and design documentation.

Key changes include:

• Unification of CLI and MCP server into todo-ai
• FastMCP integration for the MCP server
• New serve command with --root support
• Updated Cursor rules and documentation
• Various bug fixes and linting improvements
• Removed obsolete integration tests to resolve CI failures

---