docs: Update rules for MCP/CLI workflow and project root handling

Updated several Cursor rules documentation files (`mcp.mdc`, `utilities.mdc`, `architecture.mdc`, `new_features.mdc`, `commands.mdc`) to accurately reflect recent refactoring and clarify best practices.

Key documentation updates include:

- Explicitly stating the preference for using MCP tools over CLI commands in integrated environments (`commands.mdc`, `dev_workflow.mdc`).

- Describing the new standard pattern for getting the project root using `getProjectRootFromSession` within MCP tool `execute` methods (`mcp.mdc`, `utilities.mdc`, `architecture.mdc`, `new_features.mdc`).

- Clarifying the simplified role of `findTasksJsonPath` in direct functions (`mcp.mdc`, `utilities.mdc`, `architecture.mdc`, `new_features.mdc`).

- Ensuring proper interlinking between related documentation files.

.changeset/two-bats-smoke.md

@@ -8,73 +8,66 @@
   - Rename `list-tasks` to `get-tasks` for more intuitive client requests like "get my tasks"
   - Rename `show-task` to `get-task` for consistency with GET-based API naming conventions
 
-- Implement robust project root detection with a hierarchical precedence system:
-  - Environment variable override (TASK_MASTER_PROJECT_ROOT)
-  - Explicitly provided project root (--project-root parameter)
-  - Cached project root from previous successful operations
-  - Current directory with project markers
-  - Parent directory traversal to find tasks.json
-  - Package directory as fallback
+- **Refactor project root handling for MCP Server:**
+  - **Prioritize Session Roots**: MCP tools now extract the project root path directly from `session.roots[0].uri` provided by the client (e.g., Cursor).
+  - **New Utility `getProjectRootFromSession`**: Added to `mcp-server/src/tools/utils.js` to encapsulate session root extraction and decoding.
+  - **Simplify `findTasksJsonPath`**: The core path finding utility in `mcp-server/src/core/utils/path-utils.js` now prioritizes the `projectRoot` passed in `args` (originating from the session). Removed checks for `TASK_MASTER_PROJECT_ROOT` env var and package directory fallback.
+  - **Retain CLI Fallbacks**: Kept `lastFoundProjectRoot` cache check and CWD search in `findTasksJsonPath` for compatibility with direct CLI usage.
 
-- Updated all MCP tools to work without explicitly requiring project root:
-  - Changed all tool definitions from `projectRoot: z.string().describe(...)` to `projectRoot: z.string().optional().describe(...)`
-  - Updated all direct function implementations from `findTasksJsonPath(args.file, args.projectRoot)` to use the proper `findTasksJsonPath(args, log)` pattern
-  - These changes allow MCP tools to work properly without requiring the projectRoot parameter, using smart detection to automatically determine the project root
+- Updated all MCP tools to use the new project root handling:
+  - Tools now call `getProjectRootFromSession` to determine the root.
+  - This root is passed explicitly as `projectRoot` in the `args` object to the corresponding `*Direct` function.
+  - Direct functions continue to use the (now simplified) `findTasksJsonPath` to locate `tasks.json` within the provided root.
+  - This ensures tools work reliably in integrated environments without requiring the user to specify `--project-root`.
 
-- Add comprehensive PROJECT_MARKERS array for detecting common project files:
-  - Task Master specific files (tasks.json, tasks/tasks.json)
-  - Version control markers (.git, .svn)
-  - Package files (package.json, pyproject.toml, etc.)
-  - IDE/editor folders (.cursor, .vscode, .idea)
-  - Dependency directories (node_modules, venv)
-  - Configuration files (.env, tsconfig.json, etc.)
-  - CI/CD files (.github/workflows, etc.)
+- Add comprehensive PROJECT_MARKERS array for detecting common project files (used in CLI fallback logic).
+- Improved error messages with specific troubleshooting guidance.
+- Enhanced logging to indicate the source of project root selection.
+- DRY refactoring by centralizing path utilities in `core/utils/path-utils.js` and session handling in `tools/utils.js`.
+- Keep caching of `lastFoundProjectRoot` for CLI performance.
 
-- Improved error messages with specific troubleshooting guidance
-- Enhanced logging to indicate the source of project root selection
-- DRY refactoring by centralizing path utilities in core/utils/path-utils.js
-- Add caching of lastFoundProjectRoot for improved performance
-
-- Split monolithic task-master-core.js into separate function files within direct-functions directory
-- Implement update-task MCP command for updating a single task by ID
-- Implement update-subtask MCP command for appending information to specific subtasks
-- Implement generate MCP command for creating individual task files from tasks.json
-- Implement set-status MCP command for updating task status
-- Implement get-task MCP command for displaying detailed task information (renamed from show-task)
-- Implement next-task MCP command for finding the next task to work on
-- Implement expand-task MCP command for breaking down tasks into subtasks
-- Implement add-task MCP command for creating new tasks using AI assistance
-- Implement add-subtask MCP command for adding subtasks to existing tasks
-- Implement remove-subtask MCP command for removing subtasks from parent tasks
-- Implement expand-all MCP command for expanding all tasks into subtasks
-- Implement analyze-complexity MCP command for analyzing task complexity
-- Implement clear-subtasks MCP command for clearing subtasks from parent tasks
-- Implement remove-dependency MCP command for removing dependencies from tasks
-- Implement validate-dependencies MCP command for checking validity of task dependencies
-- Implement fix-dependencies MCP command for automatically fixing invalid dependencies
-- Implement complexity-report MCP command for displaying task complexity analysis reports
-- Implement add-dependency MCP command for creating dependency relationships between tasks
-- Implement get-tasks MCP command for listing all tasks (renamed from list-tasks)
+- Split monolithic task-master-core.js into separate function files within direct-functions directory.
+- Implement update-task MCP command for updating a single task by ID.
+- Implement update-subtask MCP command for appending information to specific subtasks.
+- Implement generate MCP command for creating individual task files from tasks.json.
+- Implement set-status MCP command for updating task status.
+- Implement get-task MCP command for displaying detailed task information (renamed from show-task).
+- Implement next-task MCP command for finding the next task to work on.
+- Implement expand-task MCP command for breaking down tasks into subtasks.
+- Implement add-task MCP command for creating new tasks using AI assistance.
+- Implement add-subtask MCP command for adding subtasks to existing tasks.
+- Implement remove-subtask MCP command for removing subtasks from parent tasks.
+- Implement expand-all MCP command for expanding all tasks into subtasks.
+- Implement analyze-complexity MCP command for analyzing task complexity.
+- Implement clear-subtasks MCP command for clearing subtasks from parent tasks.
+- Implement remove-dependency MCP command for removing dependencies from tasks.
+- Implement validate-dependencies MCP command for checking validity of task dependencies.
+- Implement fix-dependencies MCP command for automatically fixing invalid dependencies.
+- Implement complexity-report MCP command for displaying task complexity analysis reports.
+- Implement add-dependency MCP command for creating dependency relationships between tasks.
+- Implement get-tasks MCP command for listing all tasks (renamed from list-tasks).
 
 - Enhance documentation and tool descriptions:
-  - Create new `taskmaster.mdc` Cursor rule for comprehensive MCP tool and CLI command reference
-  - Bundle taskmaster.mdc with npm package and include in project initialization
-  - Add detailed descriptions for each tool's purpose, parameters, and common use cases
-  - Include natural language patterns and keywords for better intent recognition
-  - Document parameter descriptions with clear examples and default values
-  - Add usage examples and context for each command/tool
-  - Improve clarity around project root auto-detection in tool documentation
-  - Update tool descriptions to better reflect their actual behavior and capabilities
-  - Add cross-references between related tools and commands
-  - Include troubleshooting guidance in tool descriptions
+  - Create new `taskmaster.mdc` Cursor rule for comprehensive MCP tool and CLI command reference.
+  - Bundle taskmaster.mdc with npm package and include in project initialization.
+  - Add detailed descriptions for each tool's purpose, parameters, and common use cases.
+  - Include natural language patterns and keywords for better intent recognition.
+  - Document parameter descriptions with clear examples and default values.
+  - Add usage examples and context for each command/tool.
+  - **Update documentation (`mcp.mdc`, `utilities.mdc`, `architecture.mdc`, `new_features.mdc`, `commands.mdc`) to reflect the new session-based project root handling and the preferred MCP vs. CLI interaction model.**
+  - Improve clarity around project root auto-detection in tool documentation.
+  - Update tool descriptions to better reflect their actual behavior and capabilities.
+  - Add cross-references between related tools and commands.
+  - Include troubleshooting guidance in tool descriptions.
 
-- Document MCP server naming conventions in architecture.mdc and mcp.mdc files (file names use kebab-case, direct functions use camelCase with Direct suffix, tool registration functions use camelCase with Tool suffix, and MCP tool names use snake_case)
-- Update MCP tool naming to follow more intuitive conventions that better align with natural language requests in client chat applications
-- Enhance task show view with a color-coded progress bar for visualizing subtask completion percentage
-- Add "cancelled" status to UI module status configurations for marking tasks as cancelled without deletion
-- Improve MCP server resource documentation with comprehensive implementation examples and best practices
-- Enhance progress bars with status breakdown visualization showing proportional sections for different task statuses
-- Add improved status tracking for both tasks and subtasks with detailed counts by status
-- Optimize progress bar display with width constraints to prevent UI overflow on smaller terminals
-- Improve status counts display with clear text labels beside status icons for better readability
-- Treat deferred and cancelled tasks as effectively complete for progress calculation while maintaining visual distinction
+- Document MCP server naming conventions in architecture.mdc and mcp.mdc files (file names use kebab-case, direct functions use camelCase with Direct suffix, tool registration functions use camelCase with Tool suffix, and MCP tool names use snake_case).
+- Update MCP tool naming to follow more intuitive conventions that better align with natural language requests in client chat applications.
+- Enhance task show view with a color-coded progress bar for visualizing subtask completion percentage.
+- Add "cancelled" status to UI module status configurations for marking tasks as cancelled without deletion.
+- Improve MCP server resource documentation with comprehensive implementation examples and best practices.
+- Enhance progress bars with status breakdown visualization showing proportional sections for different task statuses.
+- Add improved status tracking for both tasks and subtasks with detailed counts by status.
+- Optimize progress bar display with width constraints to prevent UI overflow on smaller terminals.
+- Improve status counts display with clear text labels beside status icons for better readability.
+- Treat deferred and cancelled tasks as effectively complete for progress calculation while maintaining visual distinction.
+- **Fix `reportProgress` calls** to use the correct `{ progress, total? }` format.