Merge pull request #1167 from eyaltoledano/ralph/chore.merge.main.into.next.august

ralph/chore.merge.main.into.next.august

.changeset/clarify-force-move-docs.md

@@ -0,0 +1,5 @@
+---
+"task-master-ai": patch
+---
+
+docs(move): clarify cross-tag move docs; deprecate "force"; add explicit --with-dependencies/--ignore-dependencies examples

.changeset/quiet-owls-fix-cli-sdk.md

@@ -1,8 +0,0 @@
----
-"task-master-ai": patch
----
-
-fix(claude-code): prevent crash/hang when the optional `@anthropic-ai/claude-code` SDK is missing by guarding `AbortError instanceof` checks and adding explicit SDK presence checks in `doGenerate`/`doStream`. Also bump the optional dependency to `^1.0.88` for improved export consistency.
-
-Related to JSON truncation handling in #920; this change addresses a separate error-path crash reported in #1142.
-

.changeset/rich-emus-say.md

@@ -1,5 +0,0 @@
----
-"task-master-ai": patch
----
-
-Temporarily disable streaming for improved model compatibility - will be re-enabled in upcoming release

.changeset/strong-eagles-vanish.md

@@ -0,0 +1,12 @@
+---
+"task-master-ai": minor
+---
+
+feat(move): improve cross-tag move UX and safety
+
+- CLI: print "Next Steps" tips after cross-tag moves that used --ignore-dependencies (validate/fix guidance)
+- CLI: show dedicated help block on ID collisions (destination tag already has the ID)
+- Core: add structured suggestions to TASK_ALREADY_EXISTS errors
+- MCP: map ID collision errors to TASK_ALREADY_EXISTS and include suggestions
+- Tests: cover MCP options, error suggestions, CLI tips printing, and integration error payload suggestions
+---

CHANGELOG.md

@@ -1,5 +1,15 @@
 # task-master-ai
 
+## 0.25.1
+
+### Patch Changes
+
+- [#1152](https://github.com/eyaltoledano/claude-task-master/pull/1152) [`8933557`](https://github.com/eyaltoledano/claude-task-master/commit/89335578ffffc65504b2055c0c85aa7521e5e79b) Thanks [@ben-vargas](https://github.com/ben-vargas)! - fix(claude-code): prevent crash/hang when the optional `@anthropic-ai/claude-code` SDK is missing by guarding `AbortError instanceof` checks and adding explicit SDK presence checks in `doGenerate`/`doStream`. Also bump the optional dependency to `^1.0.88` for improved export consistency.
+
+  Related to JSON truncation handling in #920; this change addresses a separate error-path crash reported in #1142.
+
+- [#1151](https://github.com/eyaltoledano/claude-task-master/pull/1151) [`db720a9`](https://github.com/eyaltoledano/claude-task-master/commit/db720a954d390bb44838cd021b8813dde8f3d8de) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Temporarily disable streaming for improved model compatibility - will be re-enabled in upcoming release
+
 ## 0.25.0
 
 ### Minor Changes

apps/extension/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Change Log
 
+## 0.24.1
+
+### Patch Changes
+
+- Updated dependencies [[`8933557`](https://github.com/eyaltoledano/claude-task-master/commit/89335578ffffc65504b2055c0c85aa7521e5e79b), [`db720a9`](https://github.com/eyaltoledano/claude-task-master/commit/db720a954d390bb44838cd021b8813dde8f3d8de)]:
+  - task-master-ai@0.25.1
+
 ## 0.24.0
 
 ### Minor Changes

apps/extension/package.json

@@ -3,7 +3,7 @@
 	"private": true,
 	"displayName": "TaskMaster",
 	"description": "A visual Kanban board interface for TaskMaster projects in VS Code",
-	"version": "0.24.0",
+	"version": "0.24.1",
 	"publisher": "Hamster",
 	"icon": "assets/icon.png",
 	"engines": {
@@ -239,7 +239,7 @@
 		"check-types": "tsc --noEmit"
 	},
 	"dependencies": {
-		"task-master-ai": "0.25.0"
+		"task-master-ai": "0.25.1"
 	},
 	"devDependencies": {
 		"@dnd-kit/core": "^6.3.1",

docs/cross-tag-task-movement.md

@@ -65,11 +65,10 @@ This removes the dependency relationships and moves only the specified task.
 
 ### Force Move
 
-Force the move even with dependency conflicts:
+Note: Force moves are no longer supported. Instead, use one of these options:
 
-```bash
+- `--with-dependencies` — move dependents together
-task-master move --from=5 --from-tag=backlog --to-tag=in-progress --force
+- `--ignore-dependencies` — break cross-tag dependencies
-```
 
 ⚠️ **Warning**: This may break dependency relationships and should be used with caution.
 
@@ -93,7 +92,7 @@ Resolution options:
   2. Break dependencies: task-master move --from=5,6 --from-tag=backlog --to-tag=in-progress --ignore-dependencies
   3. Validate and fix dependencies: task-master validate-dependencies && task-master fix-dependencies
   4. Move dependencies first: task-master move --from=2,3 --from-tag=backlog --to-tag=in-progress
-  5. Force move (may break dependencies): task-master move --from=5,6 --from-tag=backlog --to-tag=in-progress --force
+  5. After deciding, re-run the move with either --with-dependencies or --ignore-dependencies
 ```
 
 ### Subtask Movement Restrictions
@@ -149,7 +148,6 @@ task-master fix-dependencies
 
 - **`--with-dependencies`**: When you want to maintain task relationships
 - **`--ignore-dependencies`**: When you want to break cross-tag dependencies
-- **`--force`**: Only when you understand the consequences
 
 ### 3. Organize by Context
 
@@ -265,9 +263,14 @@ task-master move --from=5 --from-tag=backlog --to-tag=done --ignore-dependencies
 
 ### Scenario 3: Force Move
 
+Choose one of these options explicitly:
+
 ```bash
-# Force move despite conflicts
+# Move together with dependencies
-task-master move --from=5 --from-tag=backlog --to-tag=in-progress --force
+task-master move --from=5 --from-tag=backlog --to-tag=in-progress --with-dependencies
+
+# Or break dependencies
+task-master move --from=5 --from-tag=backlog --to-tag=in-progress --ignore-dependencies
 ```
 
 ### Scenario 4: Moving Subtasks

mcp-server/src/core/direct-functions/move-task-cross-tag.js

@@ -189,6 +189,17 @@ export async function moveTaskCrossTagDirect(args, log, context = {}) {
 				'Verify task IDs exist: task-master list',
 				'Check task details: task-master show <id>'
 			];
+		} else if (
+			error.code === 'TASK_ALREADY_EXISTS' ||
+			error.message?.includes('already exists in target tag')
+		) {
+			// Target tag has an ID collision
+			errorCode = 'TASK_ALREADY_EXISTS';
+			suggestions = [
+				'Choose a different target tag without conflicting IDs',
+				'Move a different set of IDs (avoid existing ones)',
+				'If needed, move within-tag to a new ID first, then cross-tag move'
+			];
 		}
 
 		return {

package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "task-master-ai",
-	"version": "0.25.0",
+	"version": "0.25.1",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "task-master-ai",
-			"version": "0.25.0",
+			"version": "0.25.1",
 			"license": "MIT WITH Commons-Clause",
 			"workspaces": [
 				"apps/*",
@@ -93,9 +93,9 @@
 			}
 		},
 		"apps/extension": {
-			"version": "0.24.0",
+			"version": "0.24.1",
 			"dependencies": {
-				"task-master-ai": "0.25.0"
+				"task-master-ai": "0.25.1"
 			},
 			"devDependencies": {
 				"@dnd-kit/core": "^6.3.1",

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "task-master-ai",
-	"version": "0.25.0",
+	"version": "0.25.1",
 	"description": "A task management system for ambitious AI-driven development that doesn't overwhelm and confuse Cursor.",
 	"main": "index.js",
 	"type": "module",

scripts/modules/commands.js

@@ -4103,12 +4103,7 @@ Examples:
 							'  task-master move --from=5 --from-tag=backlog --to-tag=in-progress --ignore-dependencies'
 						) +
 						'\n\n' +
-						chalk.white('  # Force move (may break dependencies)') +
 						'\n' +
-						chalk.white(
-							'  task-master move --from=5 --from-tag=backlog --to-tag=in-progress --force'
-						) +
-						'\n\n' +
 						chalk.yellow.bold('Best Practices:') +
 						'\n' +
 						chalk.white(
@@ -4119,10 +4114,6 @@ Examples:
 							'  • Use --ignore-dependencies to break cross-tag dependencies'
 						) +
 						'\n' +
-						chalk.white(
-							'  • Use --force only when you understand the consequences'
-						) +
-						'\n' +
 						chalk.white(
 							'  • Check dependencies first: task-master validate-dependencies'
 						) +
@@ -4184,6 +4175,12 @@ Examples:
 
 				console.log(chalk.green(`✓ ${result.message}`));
 
+				// Print any tips returned from the move operation (e.g., after ignoring dependencies)
+				if (Array.isArray(result.tips) && result.tips.length > 0) {
+					console.log('\n' + chalk.yellow.bold('Next Steps:'));
+					result.tips.forEach((t) => console.log(chalk.white(`  • ${t}`)));
+				}
+
 				// Check if source tag still contains tasks before regenerating files
 				const tasksData = readJSON(
 					taskMaster.getTasksPath(),
@@ -4450,6 +4447,27 @@ Examples:
 					await handleWithinTagMove(moveContext);
 				}
 			} catch (error) {
+				const errMsg = String(error && (error.message || error));
+				if (errMsg.includes('already exists in target tag')) {
+					console.error(chalk.red(`Error: ${errMsg}`));
+					console.log(
+						'\n' +
+							chalk.yellow.bold('Conflict: ID already exists in target tag') +
+							'\n' +
+							chalk.white(
+								'  • Choose a different target tag without conflicting IDs'
+							) +
+							'\n' +
+							chalk.white(
+								'  • Move a different set of IDs (avoid existing ones)'
+							) +
+							'\n' +
+							chalk.white(
+								'  • If needed, move within-tag to a new ID first, then cross-tag move'
+							)
+					);
+					process.exit(1);
+				}
 				handleMoveError(error, moveContext);
 			}
 		});

scripts/modules/task-manager/move-task.js

@@ -61,6 +61,43 @@ const MOVE_ERROR_CODES = {
 	INVALID_TARGET_TAG: 'INVALID_TARGET_TAG'
 };
 
+/**
+ * Normalize a dependency value to its numeric parent task ID.
+ * - Numbers are returned as-is (if finite)
+ * - Numeric strings are parsed ("5" -> 5)
+ * - Dotted strings return the parent portion ("5.2" -> 5)
+ * - Empty/invalid values return null
+ * - null/undefined are preserved
+ * @param {number|string|null|undefined} dep
+ * @returns {number|null|undefined}
+ */
+function normalizeDependency(dep) {
+	if (dep === null || dep === undefined) return dep;
+	if (typeof dep === 'number') return Number.isFinite(dep) ? dep : null;
+	if (typeof dep === 'string') {
+		const trimmed = dep.trim();
+		if (trimmed === '') return null;
+		const parentPart = trimmed.includes('.') ? trimmed.split('.')[0] : trimmed;
+		const parsed = parseInt(parentPart, 10);
+		return Number.isFinite(parsed) ? parsed : null;
+	}
+	return null;
+}
+
+/**
+ * Normalize an array of dependency values to numeric IDs.
+ * Preserves null/undefined input (returns as-is) and filters out invalid entries.
+ * @param {Array<any>|null|undefined} deps
+ * @returns {Array<number>|null|undefined}
+ */
+function normalizeDependencies(deps) {
+	if (deps === null || deps === undefined) return deps;
+	if (!Array.isArray(deps)) return deps;
+	return deps
+		.map((d) => normalizeDependency(d))
+		.filter((n) => Number.isFinite(n));
+}
+
 /**
  * Move one or more tasks/subtasks to new positions
  * @param {string} tasksPath - Path to tasks.json file
@@ -674,15 +711,34 @@ async function resolveDependencies(
 ) {
 	const { withDependencies = false, ignoreDependencies = false } = options;
 
+	// Scope allTasks to the source tag to avoid cross-tag contamination when
+	// computing dependency chains for --with-dependencies
+	const tasksInSourceTag = Array.isArray(allTasks)
+		? allTasks.filter((t) => t && t.tag === sourceTag)
+		: [];
+
 	// Handle --with-dependencies flag first (regardless of cross-tag dependencies)
 	if (withDependencies) {
 		// Move dependent tasks along with main tasks
-		// Find ALL dependencies recursively within the same tag
+		// Find ALL dependencies recursively, but only using tasks from the source tag
-		const allDependentTaskIds = findAllDependenciesRecursively(
+		const allDependentTaskIdsRaw = findAllDependenciesRecursively(
 			sourceTasks,
-			allTasks,
+			tasksInSourceTag,
 			{ maxDepth: 100, includeSelf: false }
 		);
+
+		// Filter dependent IDs to those that actually exist in the source tag
+		const sourceTagIds = new Set(
+			tasksInSourceTag.map((t) =>
+				typeof t.id === 'string' ? parseInt(t.id, 10) : t.id
+			)
+		);
+		const allDependentTaskIds = allDependentTaskIdsRaw.filter((depId) => {
+			// Only numeric task IDs are eligible to be moved (subtasks cannot be moved cross-tag)
+			const normalizedId = normalizeDependency(depId);
+			return Number.isFinite(normalizedId) && sourceTagIds.has(normalizedId);
+		});
+
 		const allTaskIdsToMove = [...new Set([...taskIds, ...allDependentTaskIds])];
 
 		log(
@@ -711,22 +767,31 @@ async function resolveDependencies(
 		if (ignoreDependencies) {
 			// Break cross-tag dependencies (edge case - shouldn't normally happen)
 			sourceTasks.forEach((task) => {
+				const sourceTagTasks = tasksInSourceTag;
+				const targetTagTasks = Array.isArray(allTasks)
+					? allTasks.filter((t) => t && t.tag === targetTag)
+					: [];
 				task.dependencies = task.dependencies.filter((depId) => {
-					// Handle both task IDs and subtask IDs (e.g., "1.2")
+					const parentTaskId = normalizeDependency(depId);
-					let depTask = null;
+
-					if (typeof depId === 'string' && depId.includes('.')) {
+					// If dependency resolves to a task in the source tag, drop it (would be cross-tag after move)
-						// It's a subtask ID - extract parent task ID and find the parent task
+					if (
-						const [parentId, subtaskId] = depId
+						Number.isFinite(parentTaskId) &&
-							.split('.')
+						sourceTagTasks.some((t) => t.id === parentTaskId)
-							.map((id) => parseInt(id, 10));
+					) {
-						depTask = allTasks.find((t) => t.id === parentId);
+						return false;
-					} else {
-						// It's a regular task ID - normalize to number for comparison
-						const normalizedDepId =
-							typeof depId === 'string' ? parseInt(depId, 10) : depId;
-						depTask = allTasks.find((t) => t.id === normalizedDepId);
 					}
-					return !depTask || depTask.tag === targetTag;
+
+					// If dependency resolves to a task in the target tag, keep it
+					if (
+						Number.isFinite(parentTaskId) &&
+						targetTagTasks.some((t) => t.id === parentTaskId)
+					) {
+						return true;
+					}
+
+					// Otherwise, keep as-is (unknown/unresolved dependency)
+					return true;
 				});
 			});
 
@@ -810,7 +875,16 @@ async function executeMoveOperation(
 		if (existingTaskIndex !== -1) {
 			throw new MoveTaskError(
 				MOVE_ERROR_CODES.TASK_ALREADY_EXISTS,
-				`Task ${taskId} already exists in target tag "${targetTag}"`
+				`Task ${taskId} already exists in target tag "${targetTag}"`,
+				{
+					conflictingId: normalizedTaskId,
+					targetTag,
+					suggestions: [
+						'Choose a different target tag without conflicting IDs',
+						'Move a different set of IDs (avoid existing ones)',
+						'If needed, move within-tag to a new ID first, then cross-tag move'
+					]
+				}
 			);
 		}
 
@@ -851,7 +925,8 @@ async function finalizeMove(
 	tasksPath,
 	context,
 	sourceTag,
-	targetTag
+	targetTag,
+	dependencyResolution
 ) {
 	const { projectRoot } = context;
 	const { rawData, movedTasks } = moveResult;
@@ -859,10 +934,23 @@ async function finalizeMove(
 	// Write the updated data
 	writeJSON(tasksPath, rawData, projectRoot, null);
 
-	return {
+	const response = {
 		message: `Successfully moved ${movedTasks.length} tasks from "${sourceTag}" to "${targetTag}"`,
 		movedTasks
 	};
+
+	// If we intentionally broke cross-tag dependencies, provide tips to validate & fix
+	if (
+		dependencyResolution &&
+		dependencyResolution.type === 'ignored-dependencies'
+	) {
+		response.tips = [
+			'Run "task-master validate-dependencies" to check for dependency issues.',
+			'Run "task-master fix-dependencies" to automatically repair dangling dependencies.'
+		];
+	}
+
+	return response;
 }
 
 /**
@@ -898,7 +986,7 @@ async function moveTasksBetweenTags(
 	const { rawData, sourceTasks, allTasks } = await prepareTaskData(validation);
 
 	// 3. Handle dependencies
-	const { tasksToMove } = await resolveDependencies(
+	const { tasksToMove, dependencyResolution } = await resolveDependencies(
 		sourceTasks,
 		allTasks,
 		options,
@@ -923,7 +1011,8 @@ async function moveTasksBetweenTags(
 		tasksPath,
 		context,
 		sourceTag,
-		targetTag
+		targetTag,
+		dependencyResolution
 	);
 }
 

scripts/modules/ui.js

@@ -2876,9 +2876,6 @@ export function displayCrossTagDependencyError(
 			`  4. Move dependencies first: task-master move --from=${conflicts.map((c) => c.dependencyId).join(',')} --from-tag=${conflicts[0].dependencyTag} --to-tag=${targetTag}`
 		);
 	}
-	console.log(
-		`  5. Force move (may break dependencies): task-master move --from=${sourceIds} --from-tag=${sourceTag} --to-tag=${targetTag} --force`
-	);
 }
 
 /**

tests/integration/cli/move-cross-tag.test.js

@@ -158,20 +158,25 @@ describe('Cross-Tag Move CLI Integration', () => {
 			);
 
 			try {
-				await moveTaskModule.moveTasksBetweenTags(
+				const result = await moveTaskModule.moveTasksBetweenTags(
 					tasksPath,
 					taskIds,
 					sourceTag,
 					toTag,
 					{
 						withDependencies,
-						ignoreDependencies,
+						ignoreDependencies
-						force
 					}
 				);
 
 				console.log(chalk.green('Successfully moved task(s) between tags'));
 
+				// Print advisory tips when present
+				if (result && Array.isArray(result.tips) && result.tips.length > 0) {
+					console.log('Next Steps:');
+					result.tips.forEach((t) => console.log(`  • ${t}`));
+				}
+
 				// Generate task files for both tags
 				await generateTaskFilesModule.default(
 					tasksPath,
@@ -185,6 +190,21 @@ describe('Cross-Tag Move CLI Integration', () => {
 				);
 			} catch (error) {
 				console.error(chalk.red(`Error: ${error.message}`));
+				// Print ID collision guidance similar to CLI help block
+				if (
+					typeof error?.message === 'string' &&
+					error.message.includes('already exists in target tag')
+				) {
+					console.log('');
+					console.log('Conflict: ID already exists in target tag');
+					console.log(
+						'  • Choose a different target tag without conflicting IDs'
+					);
+					console.log('  • Move a different set of IDs (avoid existing ones)');
+					console.log(
+						'  • If needed, move within-tag to a new ID first, then cross-tag move'
+					);
+				}
 				throw error;
 			}
 		} else {
@@ -268,8 +288,7 @@ describe('Cross-Tag Move CLI Integration', () => {
 			'in-progress',
 			{
 				withDependencies: undefined,
-				ignoreDependencies: undefined,
+				ignoreDependencies: undefined
-				force: undefined
 			}
 		);
 	});
@@ -323,8 +342,7 @@ describe('Cross-Tag Move CLI Integration', () => {
 			'in-progress',
 			{
 				withDependencies: true,
-				ignoreDependencies: undefined,
+				ignoreDependencies: undefined
-				force: undefined
 			}
 		);
 	});
@@ -350,8 +368,7 @@ describe('Cross-Tag Move CLI Integration', () => {
 			'in-progress',
 			{
 				withDependencies: undefined,
-				ignoreDependencies: true,
+				ignoreDependencies: true
-				force: undefined
 			}
 		);
 	});
@@ -376,8 +393,7 @@ describe('Cross-Tag Move CLI Integration', () => {
 			'new-tag',
 			{
 				withDependencies: undefined,
-				ignoreDependencies: undefined,
+				ignoreDependencies: undefined
-				force: undefined
 			}
 		);
 	});
@@ -440,6 +456,57 @@ describe('Cross-Tag Move CLI Integration', () => {
 		restore();
 	});
 
+	it('should print advisory tips when result.tips are returned (ignore-dependencies)', async () => {
+		const { errorMessages, logMessages, restore } = captureConsoleAndExit();
+		try {
+			// Arrange: mock move to return tips
+			mockMoveTasksBetweenTags.mockResolvedValue({
+				message: 'ok',
+				tips: [
+					'Run "task-master validate-dependencies" to check for dependency issues.',
+					'Run "task-master fix-dependencies" to automatically repair dangling dependencies.'
+				]
+			});
+
+			await moveAction({
+				from: '2',
+				fromTag: 'backlog',
+				toTag: 'in-progress',
+				ignoreDependencies: true
+			});
+
+			const joined = logMessages.join('\n');
+			expect(joined).toContain('Next Steps');
+			expect(joined).toContain('validate-dependencies');
+			expect(joined).toContain('fix-dependencies');
+		} finally {
+			restore();
+		}
+	});
+
+	it('should print ID collision suggestions when target already has the ID', async () => {
+		const { errorMessages, logMessages, restore } = captureConsoleAndExit();
+		try {
+			// Arrange: mock move to throw collision
+			const err = new Error(
+				'Task 1 already exists in target tag "in-progress"'
+			);
+			mockMoveTasksBetweenTags.mockRejectedValue(err);
+
+			await expect(
+				moveAction({ from: '1', fromTag: 'backlog', toTag: 'in-progress' })
+			).rejects.toThrow('already exists in target tag');
+
+			const joined = logMessages.join('\n');
+			expect(joined).toContain('Conflict: ID already exists in target tag');
+			expect(joined).toContain('different target tag');
+			expect(joined).toContain('different set of IDs');
+			expect(joined).toContain('within-tag');
+		} finally {
+			restore();
+		}
+	});
+
 	it('should handle same tag error correctly', async () => {
 		const options = {
 			from: '1',
@@ -485,8 +552,7 @@ describe('Cross-Tag Move CLI Integration', () => {
 			from: '1',
 			toTag: 'in-progress',
 			withDependencies: false,
-			ignoreDependencies: false,
+			ignoreDependencies: false
-			force: false
 			// fromTag is intentionally not provided to test fallback
 		});
 
@@ -498,8 +564,7 @@ describe('Cross-Tag Move CLI Integration', () => {
 			'in-progress',
 			{
 				withDependencies: false,
-				ignoreDependencies: false,
+				ignoreDependencies: false
-				force: false
 			}
 		);
 
@@ -536,8 +601,7 @@ describe('Cross-Tag Move CLI Integration', () => {
 			'in-progress',
 			{
 				withDependencies: undefined,
-				ignoreDependencies: undefined,
+				ignoreDependencies: undefined
-				force: undefined
 			}
 		);
 
@@ -555,32 +619,7 @@ describe('Cross-Tag Move CLI Integration', () => {
 		);
 	});
 
-	it('should handle --force flag correctly', async () => {
+	// Note: --force flag is no longer supported for cross-tag moves
-		// Mock successful cross-tag move with force flag
-		mockMoveTasksBetweenTags.mockResolvedValue(undefined);
-		mockGenerateTaskFiles.mockResolvedValue(undefined);
-
-		const options = {
-			from: '1',
-			fromTag: 'backlog',
-			toTag: 'in-progress',
-			force: true
-		};
-
-		await moveAction(options);
-
-		expect(mockMoveTasksBetweenTags).toHaveBeenCalledWith(
-			expect.stringContaining('tasks.json'),
-			[1],
-			'backlog',
-			'in-progress',
-			{
-				withDependencies: undefined,
-				ignoreDependencies: undefined,
-				force: true // Force flag should be passed through
-			}
-		);
-	});
 
 	it('should fail when invalid task ID is provided', async () => {
 		const options = {
@@ -662,90 +701,11 @@ describe('Cross-Tag Move CLI Integration', () => {
 		restore();
 	});
 
-	it('should combine --with-dependencies and --force flags correctly', async () => {
+	// Note: --force combinations removed
-		// Mock successful cross-tag move with both flags
-		mockMoveTasksBetweenTags.mockResolvedValue(undefined);
-		mockGenerateTaskFiles.mockResolvedValue(undefined);
 
-		const options = {
+	// Note: --force combinations removed
-			from: '1,2',
-			fromTag: 'backlog',
-			toTag: 'in-progress',
-			withDependencies: true,
-			force: true
-		};
 
-		await moveAction(options);
+	// Note: --force combinations removed
-
-		expect(mockMoveTasksBetweenTags).toHaveBeenCalledWith(
-			expect.stringContaining('tasks.json'),
-			[1, 2],
-			'backlog',
-			'in-progress',
-			{
-				withDependencies: true,
-				ignoreDependencies: undefined,
-				force: true // Both flags should be passed
-			}
-		);
-	});
-
-	it('should combine --ignore-dependencies and --force flags correctly', async () => {
-		// Mock successful cross-tag move with both flags
-		mockMoveTasksBetweenTags.mockResolvedValue(undefined);
-		mockGenerateTaskFiles.mockResolvedValue(undefined);
-
-		const options = {
-			from: '1',
-			fromTag: 'backlog',
-			toTag: 'in-progress',
-			ignoreDependencies: true,
-			force: true
-		};
-
-		await moveAction(options);
-
-		expect(mockMoveTasksBetweenTags).toHaveBeenCalledWith(
-			expect.stringContaining('tasks.json'),
-			[1],
-			'backlog',
-			'in-progress',
-			{
-				withDependencies: undefined,
-				ignoreDependencies: true,
-				force: true // Both flags should be passed
-			}
-		);
-	});
-
-	it('should handle all three flags combined correctly', async () => {
-		// Mock successful cross-tag move with all flags
-		mockMoveTasksBetweenTags.mockResolvedValue(undefined);
-		mockGenerateTaskFiles.mockResolvedValue(undefined);
-
-		const options = {
-			from: '1,2,3',
-			fromTag: 'backlog',
-			toTag: 'in-progress',
-			withDependencies: true,
-			ignoreDependencies: true,
-			force: true
-		};
-
-		await moveAction(options);
-
-		expect(mockMoveTasksBetweenTags).toHaveBeenCalledWith(
-			expect.stringContaining('tasks.json'),
-			[1, 2, 3],
-			'backlog',
-			'in-progress',
-			{
-				withDependencies: true,
-				ignoreDependencies: true,
-				force: true // All three flags should be passed
-			}
-		);
-	});
 
 	it('should handle whitespace in comma-separated task IDs', async () => {
 		// Mock successful cross-tag move with whitespace

tests/integration/move-task-cross-tag.integration.test.js

@@ -426,6 +426,38 @@ describe('Cross-Tag Task Movement Integration Tests', () => {
 			);
 		});
 
+		it('should provide advisory tips when ignoreDependencies breaks deps', async () => {
+			// Move a task that has dependencies so cross-tag conflicts would be broken
+			const taskIds = [2]; // backlog:2 depends on 1
+			const sourceTag = 'backlog';
+			const targetTag = 'in-progress';
+
+			// Override cross-tag detection to simulate conflicts for this case
+			const depManager = await import(
+				'../../scripts/modules/dependency-manager.js'
+			);
+			depManager.findCrossTagDependencies.mockReturnValueOnce([
+				{ taskId: 2, dependencyId: 1, dependencyTag: sourceTag }
+			]);
+
+			const result = await moveTasksBetweenTags(
+				testDataPath,
+				taskIds,
+				sourceTag,
+				targetTag,
+				{ ignoreDependencies: true },
+				{ projectRoot: '/test/project' }
+			);
+
+			expect(Array.isArray(result.tips)).toBe(true);
+			const expectedTips = [
+				'Run "task-master validate-dependencies" to check for dependency issues.',
+				'Run "task-master fix-dependencies" to automatically repair dangling dependencies.'
+			];
+			expect(result.tips).toHaveLength(expectedTips.length);
+			expect(result.tips).toEqual(expect.arrayContaining(expectedTips));
+		});
+
 		it('should move task without cross-tag dependency conflicts (since dependencies only exist within tags)', async () => {
 			const taskIds = [2]; // Task 2 depends on Task 1 (both in same tag)
 			const sourceTag = 'backlog';
@@ -564,6 +596,25 @@ describe('Cross-Tag Task Movement Integration Tests', () => {
 					{ projectRoot: '/test/project' }
 				)
 			).rejects.toThrow('Task 1 already exists in target tag "in-progress"');
+
+			// Validate suggestions on the error payload
+			try {
+				await moveTasksBetweenTags(
+					testDataPath,
+					taskIds,
+					sourceTag,
+					targetTag,
+					{},
+					{ projectRoot: '/test/project' }
+				);
+			} catch (err) {
+				expect(err.code).toBe('TASK_ALREADY_EXISTS');
+				expect(Array.isArray(err.data?.suggestions)).toBe(true);
+				const s = (err.data?.suggestions || []).join(' ');
+				expect(s).toContain('different target tag');
+				expect(s).toContain('different set of IDs');
+				expect(s).toContain('within-tag');
+			}
 		});
 	});
 
@@ -637,37 +688,7 @@ describe('Cross-Tag Task Movement Integration Tests', () => {
 			);
 		});
 
-		it('should handle force flag for dependency conflicts', async () => {
+		// Note: force flag deprecated for cross-tag moves; covered by with/ignore dependencies tests
-			const taskIds = [2]; // Task 2 depends on Task 1
-			const sourceTag = 'backlog';
-			const targetTag = 'in-progress';
-
-			const result = await moveTasksBetweenTags(
-				testDataPath,
-				taskIds,
-				sourceTag,
-				targetTag,
-				{ force: true },
-				{ projectRoot: '/test/project' }
-			);
-
-			// Verify task was moved despite dependency conflicts
-			expect(mockUtils.writeJSON).toHaveBeenCalledWith(
-				testDataPath,
-				expect.objectContaining({
-					'in-progress': expect.objectContaining({
-						tasks: expect.arrayContaining([
-							expect.objectContaining({
-								id: 2,
-								tag: 'in-progress'
-							})
-						])
-					})
-				}),
-				'/test/project',
-				null
-			);
-		});
 	});
 
 	describe('Complex Scenarios', () => {

tests/unit/mcp/tools/move-task-cross-tag-options.test.js

@@ -0,0 +1,135 @@
+import { jest } from '@jest/globals';
+
+// Mocks
+const mockFindTasksPath = jest
+	.fn()
+	.mockReturnValue('/test/path/.taskmaster/tasks/tasks.json');
+jest.unstable_mockModule(
+	'../../../../mcp-server/src/core/utils/path-utils.js',
+	() => ({
+		findTasksPath: mockFindTasksPath
+	})
+);
+
+const mockEnableSilentMode = jest.fn();
+const mockDisableSilentMode = jest.fn();
+jest.unstable_mockModule('../../../../scripts/modules/utils.js', () => ({
+	enableSilentMode: mockEnableSilentMode,
+	disableSilentMode: mockDisableSilentMode
+}));
+
+// Spyable mock for moveTasksBetweenTags
+const mockMoveTasksBetweenTags = jest.fn();
+jest.unstable_mockModule(
+	'../../../../scripts/modules/task-manager/move-task.js',
+	() => ({
+		moveTasksBetweenTags: mockMoveTasksBetweenTags
+	})
+);
+
+// Import after mocks
+const { moveTaskCrossTagDirect } = await import(
+	'../../../../mcp-server/src/core/direct-functions/move-task-cross-tag.js'
+);
+
+describe('MCP Cross-Tag Move Direct Function - options & suggestions', () => {
+	const mockLog = { info: jest.fn(), warn: jest.fn(), error: jest.fn() };
+
+	beforeEach(() => {
+		jest.clearAllMocks();
+	});
+
+	it('passes only withDependencies/ignoreDependencies (no force) to core', async () => {
+		// Arrange: make core throw tag validation after call to capture params
+		mockMoveTasksBetweenTags.mockImplementation(() => {
+			const err = new Error('Source tag "invalid" not found or invalid');
+			err.code = 'INVALID_SOURCE_TAG';
+			throw err;
+		});
+
+		// Act
+		await moveTaskCrossTagDirect(
+			{
+				sourceIds: '1,2',
+				sourceTag: 'backlog',
+				targetTag: 'in-progress',
+				withDependencies: true,
+				projectRoot: '/test'
+			},
+			mockLog
+		);
+
+		// Assert options argument (5th param)
+		expect(mockMoveTasksBetweenTags).toHaveBeenCalled();
+		const args = mockMoveTasksBetweenTags.mock.calls[0];
+		const moveOptions = args[4];
+		expect(moveOptions).toEqual({
+			withDependencies: true,
+			ignoreDependencies: false
+		});
+		expect('force' in moveOptions).toBe(false);
+	});
+
+	it('returns conflict suggestions on cross-tag dependency conflicts', async () => {
+		// Arrange: core throws cross-tag dependency conflicts
+		mockMoveTasksBetweenTags.mockImplementation(() => {
+			const err = new Error(
+				'Cannot move tasks: 2 cross-tag dependency conflicts found'
+			);
+			err.code = 'CROSS_TAG_DEPENDENCY_CONFLICTS';
+			throw err;
+		});
+
+		// Act
+		const result = await moveTaskCrossTagDirect(
+			{
+				sourceIds: '1',
+				sourceTag: 'backlog',
+				targetTag: 'in-progress',
+				projectRoot: '/test'
+			},
+			mockLog
+		);
+
+		// Assert
+		expect(result.success).toBe(false);
+		expect(result.error.code).toBe('CROSS_TAG_DEPENDENCY_CONFLICT');
+		expect(Array.isArray(result.error.suggestions)).toBe(true);
+		// Key suggestions
+		const s = result.error.suggestions.join(' ');
+		expect(s).toContain('--with-dependencies');
+		expect(s).toContain('--ignore-dependencies');
+		expect(s).toContain('validate-dependencies');
+		expect(s).toContain('Move dependencies first');
+	});
+
+	it('returns ID collision suggestions when target tag already has the ID', async () => {
+		// Arrange: core throws TASK_ALREADY_EXISTS structured error
+		mockMoveTasksBetweenTags.mockImplementation(() => {
+			const err = new Error(
+				'Task 1 already exists in target tag "in-progress"'
+			);
+			err.code = 'TASK_ALREADY_EXISTS';
+			throw err;
+		});
+
+		// Act
+		const result = await moveTaskCrossTagDirect(
+			{
+				sourceIds: '1',
+				sourceTag: 'backlog',
+				targetTag: 'in-progress',
+				projectRoot: '/test'
+			},
+			mockLog
+		);
+
+		// Assert
+		expect(result.success).toBe(false);
+		expect(result.error.code).toBe('TASK_ALREADY_EXISTS');
+		const joined = (result.error.suggestions || []).join(' ');
+		expect(joined).toContain('different target tag');
+		expect(joined).toContain('different set of IDs');
+		expect(joined).toContain('within-tag');
+	});
+});

tests/unit/scripts/modules/task-manager/move-task-cross-tag.test.js

@@ -219,6 +219,37 @@ describe('Cross-Tag Task Movement', () => {
 		});
 	});
 
+	// New test: ensure with-dependencies only traverses tasks from the source tag
+	it('should scope dependency traversal to source tag when using --with-dependencies', async () => {
+		findCrossTagDependencies.mockReturnValue([]);
+		validateSubtaskMove.mockImplementation(() => {});
+
+		const result = await moveTasksBetweenTags(
+			mockTasksPath,
+			[1], // backlog:1 depends on backlog:2
+			'backlog',
+			'in-progress',
+			{ withDependencies: true },
+			mockContext
+		);
+
+		// Write should include backlog:2 moved, and must NOT traverse or fetch dependencies from the target tag
+		expect(writeJSON).toHaveBeenCalledWith(
+			mockTasksPath,
+			expect.objectContaining({
+				'in-progress': expect.objectContaining({
+					tasks: expect.arrayContaining([
+						expect.objectContaining({ id: 1 }),
+						expect.objectContaining({ id: 2 }) // the backlog:2 now moved
+						// ensure existing in-progress:2 remains (by id) but we don't double-add or fetch deps from it
+					])
+				})
+			}),
+			mockContext.projectRoot,
+			null
+		);
+	});
+
 	describe('moveTasksBetweenTags', () => {
 		it('should move tasks without dependencies successfully', async () => {
 			// Mock the dependency functions to return no conflicts