CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

0.11.0 (2026-03-12)

Features

• add production Dockerfile and health endpoint for container deployment (83af4f6)

Bug Fixes

• add ASYNC240 ignore to ruff.toml (not pyproject.toml) (108009b)
• add github-cli to devcontainer for terminal git auth (a431d8c)
• ci: use PAT for release-please to trigger CI on release PRs (f7c349f)
• resolve CI lint failures and track uv.lock (e601363)

[Unreleased]

Added

• Validation to prevent ':' character in task and story titles (reserved as ID separator)
• Error logging when corrupted story files with embedded task objects are detected

Changed

• BREAKING: Removed legacy fallback that saved embedded task objects in story files
• Story files now strictly require normalized format (task IDs as strings, not embedded objects)
• Refactored _load_story() and _load_task() to accept explicit plan_id parameter instead of relying on global state
• Loading code now rejects and logs errors for corrupted story files with embedded task dictionaries

Fixed

• CRITICAL: Fixed 'dict' object has no attribute 'split' error when loading corrupted story files
• Corrected story file format for refactor_board_tile_system_for_multi_modal_interaction story
• Prevented future file corruption by removing fallback that could save malformed data

0.10.0 (2025-10-23)

⚠ BREAKING CHANGES

• Major terminology update for clarity and industry alignment
• workflow: approve_task no longer handles TODO → IN_PROGRESS transitions. Use start_task for Gate 1 instead. The approve_current_task() service function still delegates for backward compatibility.

Features

• acceptance criteria in Story (87883e8)
• add CI/CD pipeline, test isolation, and code quality tools (d6ec879)
• align it with the rewrtitten task-centric workflow defined in .cursor/rules/project-management.mdc (8a3665e)
• assisted planning workflow - introduction (e5e3362)
• basic telemetry for key flows: Implemented env-gated counters/timers with sampling; instrumented approve_task and submit_for_review; documented telemetry env vars. (3d42e80)
• cli: Improve tool-layer error handling (409a94c)
• cli: Improve tool-layer error handling (54af7d7)
• cli: Make set_current commands context-aware (f916c82)
• cli: overhaul workflow for clarity and explicit user control (36367df)
• cli: refactor command layer for clarity and predictability (9a70e4b)
• correlation: correlation IDs to mutations: middleware and propagated corr_id into plan/story/task creation logs; each request includes x-correlation-id. (cb65d2c)
• implement planning/execution workflow, agent actions (workflow_status.actions), select_or_create, guardrails, pagination, client-side changelog (9d8e63b)
• integrate task blocker checking into report service (1d6d306)
• plan create prompt (ef8325f)
• reporting: Implement scoped reports (a821719)
• simple browser to see the work items; can be switched off (f6bd822)
• structured io of approve_task and streamlined changelog (b70e298)
• structured JSON logs now emitted for critical actions (create, approve transitions) with fields like event, ids/titles, statuses, and corr_id. Works with correlation middleware for end-to-end tracing. (90cd4cc)
• tasks: Implement proactive blocker detection (4de24e5)
• triage dashboard and backlog view (16f5c0c)
• workflow: Test and refine task execution workflow (04cb2c0)

Bug Fixes

• main: add return type annotation to main() (acd4261)
• add factory=True to uvicorn.run() to suppress ASGI app factory warning (785a8b0)
• auto-init todo/plan.yaml and ensure dir on save; docs: host.docker.internal SSE url (71a508f)
• ci: ensure CI passes with professional standards (d4f842a)
• ci: fix coverage threshold and twine installation (587c7d4)
• delete_plan not only removes it from the register, but removes the files (3323835)
• enable PENDING_REVIEW → IN_PROGRESS transition for request_pr_changes (a96e1bb)
• improve status rollup to show progress accurately (153b99a)
• license: correct copyright holder to sgrade (58c1d09)
• logging: add type annotation for handlers list (f765296)
• make browse endpoint work even if todo directory does not exist (fb22899)
• missing plan status propagation logic. (d5ef716)
• mypy: fix pre-commit mypy config to use mypy.ini (ee3dc07)
• outputs: add type parameters to generic dict types (def7dd3)
• persistent error executing tool submit_for_review: An execution summary must be provided before submitting for review. (2153582)
• plan_repository: add missing ValidationError import (85d078b)
• plan_service: add type annotations to helper functions (3c7acb6)
• prompt_register: add type annotations and fix handler signature (9e9a47c)
• report_service: handle optional execution_summary properly (42b5cb4)
• resolve mypy strict type checking issues (core services) (eb27ee4)
• server/browser: add type annotations for browse_endpoint (bf832c8)
• server: add complete type annotations for app and browser (ffa4ca1)
• story_tools: add type annotations and fix completion_time check (6e02594)
• task_service: fix type issues with datetime handling (64c2cf5)
• task_tools: add type annotations and fix imports (45ea859)
• telemetry: add type annotations for kwargs and return types (9cf6fd7)
• tools: add type annotations for MCP instance parameters (f51cdae)
• update story was corrupting the list of task IDs in story.md (3326621)
• usage_resources: add type annotation for mcp_instance (e12bef0)
• workflow_prompts: add return type annotation (116bf24)

Performance Improvements

• logging: convert all logging to lazy % formatting (7ff4f3e)

Documentation

• add branching strategy and branch protection guidelines (d8f3c99)
• add docs to uv config, fix budges (c3e7951)
• add guardrails to usage guiede agents (7adfc90)
• changelog: add Unreleased section for dev workflow and docs updates (9ce8fff)
• changelog: update with CI fixes and code quality improvements (5ac2961)
• documentation polish (a0a7535)
• documentation polish (96aa11f)
• env-based configuration and documented stdout vs file sink in config_reference.md (1c884c4)
• how to connect to Plan Manager from another computer and related security considerations; minor corrections (c27159d)
• modified task execution workflow; minor tweaks (450eef1)
• polished task execution workflow; removed duplications between project_workflow diagrams and usage_guide (8909b62)
• preparation to streamline project management workflow (f2ef898)
• product maturity in the readme, polished project_workflow and summarized ideas for langgraph-based next step. (fce8fbd)
• release checklist (fd10378)
• remove the quickstart guide for agents (e8fd9b5)
• structure readme links to other docs; cleanup (04c21e7)
• update release process for release-please automation (37bbc98)

Code Refactoring

• adopt PR-centric workflow terminology (047a4c0)
• workflow: split Gate 1 and Gate 2 approval tools (40398c0)

[0.9.0] - 2025-10-24

Added

• start_task tool for Gate 1 (Pre-Execution Approval: TODO → IN_PROGRESS)
• merge_pr convenience tool (formerly finalize_task) for Gate 2 workflow

Changed

• BREAKING: Renamed changelog_entries field to changes in Task model (clearer PR-centric terminology)
  • Validation function: validate_changelog_entries → validate_changes
  • Config variable: REQUIRE_CHANGELOG_ENTRIES_BEFORE_DONE → REQUIRE_CHANGES_BEFORE_DONE
  • All error messages updated to use "changes" terminology
• BREAKING: Renamed tools to match PR workflow terminology
  • submit_for_review → submit_pr
  • approve_task → approve_pr
  • finalize_task → merge_pr
  • request_changes → request_pr_changes
  • ActionType enum values updated (SUBMIT_PR, APPROVE_PR, REQUEST_PR_CHANGES)
• BREAKING: Renamed service functions to match tools
  • submit_for_code_review → submit_pr
  • approve_current_task_review → approve_pr
• Updated workflow documentation to use "Gate 1" and "Gate 2" terminology consistently
• NextActions now recommend merge_pr as primary action at Gate 2
• Commit message format: removed redundant scope, now uses full task ID in Refs footer, and lowercases first letter of subject line for consistency

Fixed

• Clarified tool responsibilities: start_task (Gate 1) vs approve_pr (Gate 2)
• Status rollup logic now correctly shows stories and plans as IN_PROGRESS when work has been done but no task is currently active (e.g., when some tasks are DONE and others are TODO)
• Stories with tasks in PENDING_REVIEW now correctly show as IN_PROGRESS
• CRITICAL: Fixed request_pr_changes workflow - now correctly allows PENDING_REVIEW → IN_PROGRESS transition and properly persists review feedback and rework count

[0.8.0] - 2025-10-18

Added

• GitHub Actions CI/CD pipeline with automated testing, linting, type checking, and security scanning
• Test isolation infrastructure: all tests run in temporary directories (/tmp/pytest_plan_manager_*)
• Pre-commit hooks for automated code quality checks (ruff, mypy, bandit, pytest)
• Comprehensive unit tests for validation, config, and shared utilities
• Type checking with mypy in strict mode
• Security scanning with bandit
• Dependabot configuration for automated dependency updates
• Dependency review workflow for pull requests
• tests/conftest.py with autouse fixture for complete test isolation
• py.typed marker for PEP 561 compliance
• Automatic redirect from localhost:3000 to localhost:3000/browse/ for user convenience
• Test story_tools integration tests
• Codecov integration for test coverage tracking and reporting

Changed

• Documentation restructured: docs/contributing.md is now the single source of truth for development info
• README.md simplified to user-focused content only
• AGENTS.md updated to guide AI agents developing Plan Manager (vs. using it)
• Expanded ruff linting rules to 30+ categories with per-file ignores
• Test suite optimized for pre-1.0 project (removed performance benchmarks)
• CI pipeline configured for branch-specific checks (full checks on main/PRs, fast unit tests on develop)
• Fixed hardcoded 'todo' paths to use TODO_DIR from config for proper test isolation
• Docs: how to connect to Plan Manager from another computer and related security considerations
• MCP Python SDK bumped to 1.17.0
• Migrated all path operations to use pathlib.Path instead of os.path for modern, maintainable code
• Test coverage threshold set to 40% (appropriate for pre-1.0, targets critical paths)
• Mypy CI configuration aligned with local mypy.ini settings (disallow_subclassing_any = False)

Fixed

• Test isolation: tests no longer create files in real todo/ directory
• Hardcoded paths in paths.py and story_service.py now respect TODO_DIR environment variable
• Update story was corrupting the list of task IDs in story.md
• CI test job: coverage threshold lowered from 50% to 40% to match current coverage (40.83%)
• CI build job: added dev dependencies installation to ensure twine is available for distribution checks
• CI type-check job: fixed mypy to use mypy.ini config instead of --strict flag for consistency
• Pre-commit mypy hook: configured to use mypy.ini instead of --strict for local/CI alignment
• Blind exception catching: replaced 31 instances of except Exception with specific exceptions
• Logging performance: converted 28 f-string logging calls to lazy % formatting
• Code quality: fixed 189 total issues across type safety, maintainability, pathlib migration, and code quality
• LICENSE: corrected copyright holder from "Plan Manager" to "sgrade"

Removed

• Performance benchmark tests (overkill for pre-1.0 project)
• Duplicate documentation across multiple files
• Unused __version__ from __init__.py (pyproject.toml is now single source of truth)

[0.7.0] - 2025-10-08

Added:

• Comprehensive input validation and sanitization for all user inputs
• Unit test suite with 63 tests covering validation, telemetry, and domain models
• Centralized validation module with consistent error handling
• Improved telemetry logging (removed debug print statements)

Changed:

• Consistent, AI-friendly docstrings.
• Polished task workflows.
• MCP Python SDK bumped to 1.16.0
• Default value for status parameter for list tools is empty list instead of None.
• Replaced broad Exception catches with specific exception types
• Enhanced error messages for better user experience
• Improved exception handling in tool layers with proper categorization
• Updated telemetry to use structured logging instead of print statements

Security:

• Added input validation to prevent injection attacks
• Sanitized user inputs with length limits and character restrictions
• Enhanced validation for task steps, execution summaries, and feedback

[0.6.2]

Added:

• Simple browser to see the work items; can be switched off.

Changed:

• Create a shared task ID resolution function and update the tool and service layers to use it.
• Add a local_id to the Task domain model and the TaskOut and TaskListItem schemas.
• Moved the starlette app to server directory.
• Data persistence layer has been successfully migrated to a normalized file structure: plan.yaml simplified, responsibilities shared with other files.
• Remove the quickstart guide for agents. The usage guide for agents is the single document - avoids duplications.
• Separate select current task workflow from other parts of task execution workflow.
• Fast-track path in gate 1 of task execution workflow requires agent to create steps instead of seeding placeholder steps.

Fixed:

• Missing plan status propagation logic.
• Make browse endpoint work even if todo directory does not exist.
• Persistent error executing tool submit_for_review: An execution summary must be provided before submitting for review.

[0.6.1] - 2025-09-18

Added:

• Triage:
  • Create triage dashboard and backlog views: Defined dashboard views (P0/P1, needs‑info, by area) and documented how to access them in triage_guide.md.
  • Establish triage labels and P0/P1/P2 criteria: Added performance labeling guidance (use area:performance with type:enhancement unless functional defect) and concrete P1 vs P2 examples.
  • Verified triage_guide.md covers monitoring P0/P1, needs‑info, and area views.
  • Set up weekly triage routine: Added weekly triage cadence and ownership details to triage_guide.md (schedule, participants, reminders, outcomes, ≤15‑min agenda).
• AGENTS.md - this file guides agents that use the Plan Manager MCP server.
• Correlation: correlation IDs to mutations: middleware and propagated corr_id into plan/story/task creation logs; each request includes x-correlation-id.
• Structure logs for critical actions: Added structured JSON logs for key actions with corr_id, aligned with the correlation middleware.
• Basic telemetry for key flows: Implemented env-gated counters/timers with sampling; insrumented approve_task and submit_for_review; documented telemetry env vars.
• Release Gating and Beta Criteria:
  • Define beta gating checklist: Added docs/release_checklist.md with gates, manual QA, logging/telemetry checks, versioning/tagging, and sign‑offs; linked from contributing.md.

Changed:

• Show execution summary in TaskOut and report: Expose review summaries in UI surfaces.
• Quickstart polish and cross-links: Polished Quickstart wording and added a concise cross‑link to triage_guide.md; kept detailed behavior in usage_guide_agents.md.
• Configuration reference updates: Added docs/config_reference.md with env vars, defaults, and examples (reload, logging, paths, reconnect notes). Linked from contributing and AGENTS.md.
• Unified output for task workflow functions.

Fixed:

• Priority type mismatch at transport vs domain; implemented boundary coercion with clear error messages and updated tool signatures to accept numeric types.
• Task status string vs enum mismatch; updated tool to coerce to Status enum.
• Minor prompt typo fixed ("Create aplan" -> "Create a plan"). Error handling improved in task tools: now raise exceptions instead of returning invalid TaskOuts.

[v0.6.0] - 2025-09-16

Added

• Assisted planning prompts registered and made context-aware (optional args, use current plan/story/task when omitted).
• FastMCP prompt catalog with dynamic registration via register_prompts and PROMPT_SPECS.
• New prompts:
  • create_plan (plan with title and description)
  • create_stories (stories with title, description, acceptance_criteria)
  • create_tasks (tasks with title, description)
  • create_steps (PATCH-level steps suitable for changelog bullets)
• Review checklists and usage guide aligned with the documented workflow.
• Acceptance criteria in Story
• Formal way to request changes in task execution workflow

Changed

• BREAKING: Flattened MCP tool inputs to simple parameters (no nested payload objects):
  • set_current_plan(plan_id?), set_current_story(story_id?), set_current_task(task_id?)
  • create_plan(title, description?, priority?), create_story(title, priority?, depends_on?, description?), create_task(story_id, title, priority?, depends_on?, description?)
  • get_plan(plan_id?), get_story(story_id?), get_task(story_id?, task_id?)
  • update_plan(plan_id, title?, description?, priority?, status?), update_story(story_id, title?, description?, depends_on?, priority?, status?), update_task(story_id, task_id, title?, description?, depends_on?, priority?, status?)
  • delete_plan(plan_id), delete_story(story_id), delete_task(story_id, task_id)
  • list_plans, list_stories, list_tasks
  • task_tools
• Replace usage prompts with MCP server instructions (quickstart) and resource (usage guide)

Removed

• Remove inputs schema

Fixed

• Prompt examples now use valid JSON (no trailing commas; corrected keys: description instead of user_story).

[0.5.5] - 2025-09-10

Added

• Scoped Reporting: The report command now accepts an optional scope. report plan provides a high-level summary of all stories, while the default report continues to show a detailed view of the current story.
• Proactive Blocker Detection: The system now automatically updates task statuses to BLOCKED or TODO based on the completion of their dependencies. This logic is triggered whenever a task is marked as DONE.

Changed

• Interactive set_current Commands: The set_current_plan, set_current_story, and set_current_task commands now list available items if called without an ID, guiding the user to make a valid selection.
• Improved Error Handling: Added robust try...except blocks to the tool layer (approval_tools.py, task_tools.py) to catch service-level exceptions and return user-friendly, structured error messages.

[0.5.4] - 2025-09-10

Fixed

• Corrected a bug in the approve_fast_track service where it failed to find stories due to incorrect ID handling.
• Ensured that approve_fast_track uses fully-qualified task IDs when calling underlying services to prevent lookup failures.

Changed

• The approve_task tool now requires a fully-qualified ID (story_id:task_id) for fast-tracking to prevent ambiguity when multiple tasks share similar local IDs.

[0.5.3] - 2025-09-10

Changed

• Rename approve tool to approve_task
• Structured input and output for the task approval tool
• Streamline changelog functionality and hook it to the approve_task tool
• Integrate the blocker-checking logic directly into the report service.
• Ensure that when a user runs report on a BLOCKED task, they will now see a clear, human-readable list of what needs to be done to unblock it.

Removed

• Remove the explain_task_blockers command, simplifying the user-facing API.

[0.5.2] - 2025-09-10

Added

• prepare command: New command to instruct the agent to generate the implementation steps for a task.
• get_current command: New command to display the current context (Plan, Story, Task IDs).
• Unified Workflow Documentation: Added a new unified workflow diagram and explanation to docs/project_workflow.md for improved clarity.

Changed

• status command renamed to report: To better reflect its function as a rich progress summary and avoid ambiguity with the Status property.
• Task implementation_plan field renamed to steps: For clarity and to avoid confusion with the Plan work item.
• Updated approve command behavior: The approve command is now more explicit for handling steps review and fast-tracking.
• The delete_plan command now properly removes the plan's directory and all associated files.

Removed

• backlog command: Removed in favor of more explicit list_stories, create_story, and list_tasks commands.
• select_or_create_plan command: Removed in favor of the explicit list_plans, create_plan, and set_current_plan workflow.
• workflow_status command: Removed as its functionality is now better covered by the report and get_current commands.

[0.5.1] - 2025-09-08

Added

• MCP prompts for execution intent and summary, review checklist.
• Break development workflow into planning and execution; related convenience features.
• Implement planning/execution workflow, agent actions (workflow_status.actions), select_or_create, guardrails, pagination, client-side changelog
• Align it with the rewrtitten task-centric workflow defined in .cursor/rules/project-management.mdc

Changed

• Refactor changelog tools to work with remote client.

[0.5.0] - 2025-09-04

Added

• Workflow-aligned plan-manager: execution intent, summary, approvals.
• Enforce WorkItem ID generation.
• Basic state management for tracking current plan, story and task.

[0.4.0] - 2025-09-02

Added

• Testing with mcp-inspector

Changed

• Tweak Dockerfile and devcontainer.json to automate dev environment setup for Python.
• Add testing with mcp-inspector.
• Unify Story/Task CRUD, reduce duplication, and tighten types.
• Structure input and output.
• Refactor list_tasks service and tool for stricter structured output.
• Refactor list_stories service and tool for structured input and output.
• Unify plan management is unified with story and task management.
• Deprecate plan archive - use unified plan management instead.

[0.3.1] - 2025-08-29

Changed

• Replace implicit imports from plan_manager.domain (init.py) with explicit imports from plan_manager.domain.models to avoid accidental re-exports, reduce surface area, and lower risk of circular imports.
• Uvicorn config: TIMEOUT_GRACEFUL_SHUTDOWN from 2 to 30 and TIMEOUT_KEEP_ALIVE from 2 to 5 to avoid "ERROR - uvicorn.error:414 - Exception in ASGI application".

Fixed

• Import logging config.
• One empty line in the end of files instead of three.

[0.3.0] - 2025-08-28

Added

• plan_manager.domain.validation module for domain-layer dependency validation.

Changed

• Separate domain models from orchestration (services vs. data models).
• Centralize dependency validation and status transitions.
• Encapsulate file mirroring concerns.
• Enable safer plan writes and easier testing.
• Archive tools now use the repository API exclusively: archive.delete_archived_story performs loads/saves via services.plan_repository.
• Story deletion now also removes the entire story directory (todo/<story_id>/) best-effort, with guardrails to prevent unsafe deletes.
• Refine domain models: Plan validator defers dependency validation import to avoid cycles and keep domain layer pure.
• Improve typing, docstrings, and logging consistency.

Removed

• egacy implementations related to the changed functionality.
• Outdated CLI tools.

[0.2.3] - 2025-08-26

Changed

• Replace SSE transport by Streamable HTTP.
• Refactor application configuration to follow Twelve-Factor App principles. All settings are now sourced from environment variables with sensible defaults. Command-line arguments have been removed for simplicity.
• Consolidate configuration logic has been into the plan_manager.config module.
• Unify the logging system: modules now use a consistent, centrally configured logger that inherits its settings from the main entrypoint.
• Logging now defaults to writing to stdout as an event stream, adhering to Twelve-Factor principles. File-based logging is now an opt-in feature for development.

Added

• The PLAN_MANAGER_ENABLE_FILE_LOG variable is now set in .devcontainer/devcontainer.json to automatically enable file logging for a better development experience.
• Add logs/ directory to .gitignore to prevent log files from being committed.

Fixed

• Suppress ASGI app factory warning from Uvicorn by adding factory=True to the uvicorn.run() call.

[0.2.2] - 2025-08-23

Changed

• Split modules into story_model.py, stories.py, plan.py, archive.py for clarity.
• Explicit MCP tool registration (stories, plan, archive) from mcp_server.py.
• Clean imports, removed sys.path hacks, and fixed circular imports.

Fixed

• Lint issues and missing imports; server starts cleanly with autoreload.

[0.2.1] - 2025-08-23

Added

• create_task supports details_content to initialize the task markdown (remote-friendly).
• New unified update_task handler for partial updates (title, notes, depends_on, priority, status).

Changed

• CRUD naming alignment: get_task, create_task, update_task, delete_task. Removed legacy show_task_handler.
• Empty status/priority in update_task are treated as “no change” to ease client calls.

Removed

• Specialize update_task_status_handler and update_task_priority_handler in favor of update_task.

[0.2.0] - 2025-08-22

Added

• Development autoreload via uvicorn --reload in dev workflow.
• CLI flags for reload directories, include/exclude patterns, and timeouts.
• Env flag PLAN_MANAGER_ENABLE_FILE_LOG to disable file logging in dev.

Changed

• Documentation updated for SSE-only configuration and Cursor SSE setup.

Fixed

• Faster, more predictable shutdown on reload even with long-lived SSE connections open.

[0.1.0] - 2025-07-28

Added

• Initial release of Plan Manager.
• MCP server implementation for AI assistant integration.
• Task management with YAML-based storage (todo/plan.yaml).
• Dependency tracking and topological sorting.
• Priority-based task ordering (0-5 scale).
• Task status management (TODO, IN_PROGRESS, DONE, BLOCKED, DEFERRED).
• Archive functionality for completed tasks.
• CLI tools for direct task management:
  • list_tasks.py - List and filter tasks.
  • show_task.py - Display task details.
  • update_task_status.py - Update task status.
• Comprehensive logging system.
• Pydantic-based data validation.
• SSE transport support for MCP communication.
• Development container configuration.
• Comprehensive documentation and setup instructions.

Features

• Task Management: Create, read, update, delete operations.
• Dependency Management: Define task dependencies with cycle detection.
• Priority System: 6-level priority system (0=highest, 5=lowest, null=no priority).
• Status Tracking: Five status types with validation.
• Archive System: Move completed tasks to archive with detail preservation.
• AI Integration: Full MCP server implementation for AI assistants.
• Data Validation: Robust schema validation using Pydantic models.
• Logging: Comprehensive logging to both files and stderr.
• CLI Interface: Direct command-line access to all functionality.

Technical Details

• Python 3.11+ required.
• Built with FastMCP, Starlette, and Uvicorn.
• YAML-based data storage with backup/archive support.
• Type hints throughout codebase.
• Comprehensive error handling and validation.