foundry-mcp 0.3.3__py3-none-any.whl → 0.8.10__py3-none-any.whl

foundry_mcp/tools/unified/task.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import logging
+import re
 import time
 from dataclasses import asdict
 from pathlib import Path
@@ -24,6 +25,7 @@ from foundry_mcp.core.pagination import (
 from foundry_mcp.core.progress import (
     get_progress_summary,
     list_phases,
+    sync_computed_fields,
     update_parent_status,
 )
 from foundry_mcp.core.responses import (
@@ -43,12 +45,34 @@ from foundry_mcp.core.journal import (
 )
 from foundry_mcp.core.task import (
     add_task,
+    batch_update_tasks,
     check_dependencies,
     get_next_task,
+    manage_task_dependency,
+    move_task,
     prepare_task as core_prepare_task,
     remove_task,
+    REQUIREMENT_TYPES,
     update_estimate,
     update_task_metadata,
+    update_task_requirements,
+)
+from foundry_mcp.core.batch_operations import (
+    prepare_batch_context,
+    start_batch,
+    complete_batch,
+    reset_batch,
+    DEFAULT_MAX_TASKS,
+    DEFAULT_TOKEN_BUDGET,
+    STALE_TASK_THRESHOLD_HOURS,
+)
+from foundry_mcp.cli.context import (
+    AutonomousSession,
+    get_context_tracker,
+)
+from foundry_mcp.core.validation import (
+    VALID_VERIFICATION_TYPES,
+    VERIFICATION_TYPE_MAPPING,
 )
 from foundry_mcp.tools.unified.router import (
     ActionDefinition,
@@ -247,6 +271,303 @@ def _handle_prepare(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
     return _attach_meta(result, request_id=request_id, duration_ms=elapsed_ms)
 
 
+def _handle_prepare_batch(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
+    """
+    Handle prepare-batch action for parallel task execution.
+
+    Returns multiple independent tasks with context for parallel implementation.
+    """
+    request_id = _request_id()
+    action = "prepare-batch"
+    spec_id = payload.get("spec_id")
+    if not isinstance(spec_id, str) or not spec_id.strip():
+        return _validation_error(
+            field="spec_id",
+            action=action,
+            message="Provide a non-empty spec identifier",
+            request_id=request_id,
+        )
+
+    # Optional parameters with defaults
+    max_tasks = payload.get("max_tasks", DEFAULT_MAX_TASKS)
+    if not isinstance(max_tasks, int) or max_tasks < 1:
+        return _validation_error(
+            field="max_tasks",
+            action=action,
+            message="max_tasks must be a positive integer",
+            request_id=request_id,
+            code=ErrorCode.VALIDATION_ERROR,
+        )
+
+    token_budget = payload.get("token_budget", DEFAULT_TOKEN_BUDGET)
+    if not isinstance(token_budget, int) or token_budget < 1000:
+        return _validation_error(
+            field="token_budget",
+            action=action,
+            message="token_budget must be an integer >= 1000",
+            request_id=request_id,
+            code=ErrorCode.VALIDATION_ERROR,
+        )
+
+    workspace = payload.get("workspace")
+    specs_dir = _resolve_specs_dir(config, workspace)
+    if specs_dir is None:
+        return _specs_dir_missing_error(request_id)
+
+    start = time.perf_counter()
+    result, error = prepare_batch_context(
+        spec_id=spec_id.strip(),
+        max_tasks=max_tasks,
+        token_budget=token_budget,
+        specs_dir=specs_dir,
+    )
+    elapsed_ms = (time.perf_counter() - start) * 1000
+
+    if error:
+        _metrics.counter(_metric(action), labels={"status": "error"})
+        return asdict(
+            error_response(
+                error,
+                error_code=ErrorCode.OPERATION_FAILED,
+                error_type=ErrorType.VALIDATION,
+                request_id=request_id,
+            )
+        )
+
+    _metrics.timer(_metric(action) + ".duration_ms", elapsed_ms)
+    _metrics.counter(_metric(action), labels={"status": "success"})
+
+    # Build response with batch context
+    response = success_response(
+        spec_id=spec_id.strip(),
+        tasks=result.get("tasks", []),
+        task_count=result.get("task_count", 0),
+        spec_complete=result.get("spec_complete", False),
+        all_blocked=result.get("all_blocked", False),
+        stale_tasks=result.get("stale_tasks", []),
+        dependency_graph=result.get("dependency_graph", {}),
+        token_estimate=result.get("token_estimate", 0),
+        request_id=request_id,
+        telemetry={"duration_ms": round(elapsed_ms, 2)},
+    )
+
+    warnings = result.get("warnings", [])
+    return _attach_meta(
+        asdict(response),
+        request_id=request_id,
+        duration_ms=elapsed_ms,
+        warnings=warnings if warnings else None,
+    )
+
+
+def _handle_start_batch(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
+    """
+    Handle start-batch action for atomically starting multiple tasks.
+
+    Validates all tasks can be started before making any changes.
+    """
+    request_id = _request_id()
+    action = "start-batch"
+    spec_id = payload.get("spec_id")
+    if not isinstance(spec_id, str) or not spec_id.strip():
+        return _validation_error(
+            field="spec_id",
+            action=action,
+            message="Provide a non-empty spec identifier",
+            request_id=request_id,
+        )
+
+    task_ids = payload.get("task_ids")
+    if not isinstance(task_ids, list) or not task_ids:
+        return _validation_error(
+            field="task_ids",
+            action=action,
+            message="Provide a non-empty list of task IDs",
+            request_id=request_id,
+        )
+
+    # Validate all task_ids are strings
+    for i, tid in enumerate(task_ids):
+        if not isinstance(tid, str) or not tid.strip():
+            return _validation_error(
+                field=f"task_ids[{i}]",
+                action=action,
+                message="Each task ID must be a non-empty string",
+                request_id=request_id,
+                code=ErrorCode.VALIDATION_ERROR,
+            )
+
+    workspace = payload.get("workspace")
+    specs_dir = _resolve_specs_dir(config, workspace)
+    if specs_dir is None:
+        return _specs_dir_missing_error(request_id)
+
+    start = time.perf_counter()
+    result, error = start_batch(
+        spec_id=spec_id.strip(),
+        task_ids=[tid.strip() for tid in task_ids],
+        specs_dir=specs_dir,
+    )
+    elapsed_ms = (time.perf_counter() - start) * 1000
+
+    if error:
+        _metrics.counter(_metric(action), labels={"status": "error"})
+        # Include partial results in error response
+        return asdict(
+            error_response(
+                error,
+                error_code=ErrorCode.OPERATION_FAILED,
+                error_type=ErrorType.VALIDATION,
+                request_id=request_id,
+                details=result if result else None,
+            )
+        )
+
+    _metrics.timer(_metric(action) + ".duration_ms", elapsed_ms)
+    _metrics.counter(_metric(action), labels={"status": "success"})
+
+    response = success_response(
+        spec_id=spec_id.strip(),
+        started=result.get("started", []),
+        started_count=result.get("started_count", 0),
+        started_at=result.get("started_at"),
+        request_id=request_id,
+        telemetry={"duration_ms": round(elapsed_ms, 2)},
+    )
+    return _attach_meta(asdict(response), request_id=request_id, duration_ms=elapsed_ms)
+
+
+def _handle_complete_batch(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
+    """Handle complete-batch action for completing multiple tasks with partial failure support."""
+    request_id = _request_id()
+    action = "complete-batch"
+    spec_id = payload.get("spec_id")
+    if not isinstance(spec_id, str) or not spec_id.strip():
+        return _validation_error(field="spec_id", action=action, message="Provide a non-empty spec identifier", request_id=request_id)
+
+    completions = payload.get("completions")
+    if not isinstance(completions, list) or not completions:
+        return _validation_error(field="completions", action=action, message="Provide a non-empty list of completions", request_id=request_id)
+
+    workspace = payload.get("workspace")
+    specs_dir = _resolve_specs_dir(config, workspace)
+    if specs_dir is None:
+        return _specs_dir_missing_error(request_id)
+
+    start = time.perf_counter()
+    result, error = complete_batch(spec_id=spec_id.strip(), completions=completions, specs_dir=specs_dir)
+    elapsed_ms = (time.perf_counter() - start) * 1000
+
+    if error:
+        _metrics.counter(_metric(action), labels={"status": "error"})
+        return asdict(error_response(error, error_code=ErrorCode.OPERATION_FAILED, error_type=ErrorType.VALIDATION, request_id=request_id, details=result if result else None))
+
+    _metrics.timer(_metric(action) + ".duration_ms", elapsed_ms)
+    _metrics.counter(_metric(action), labels={"status": "success"})
+
+    response = success_response(
+        spec_id=spec_id.strip(),
+        results=result.get("results", {}),
+        completed_count=result.get("completed_count", 0),
+        failed_count=result.get("failed_count", 0),
+        total_processed=result.get("total_processed", 0),
+        request_id=request_id,
+        telemetry={"duration_ms": round(elapsed_ms, 2)},
+    )
+    return _attach_meta(asdict(response), request_id=request_id, duration_ms=elapsed_ms)
+
+
+def _handle_reset_batch(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
+    """
+    Handle reset-batch action for resetting stale or specified in_progress tasks.
+
+    Resets tasks back to pending status and clears started_at timestamp.
+    If task_ids not provided, finds stale tasks automatically based on threshold.
+    """
+    request_id = _request_id()
+    action = "reset-batch"
+    spec_id = payload.get("spec_id")
+    if not isinstance(spec_id, str) or not spec_id.strip():
+        return _validation_error(
+            field="spec_id",
+            action=action,
+            message="Provide a non-empty spec identifier",
+            request_id=request_id,
+        )
+
+    # Optional: specific task IDs to reset
+    task_ids = payload.get("task_ids")
+    if task_ids is not None:
+        if not isinstance(task_ids, list):
+            return _validation_error(
+                field="task_ids",
+                action=action,
+                message="task_ids must be a list of strings",
+                request_id=request_id,
+            )
+        # Validate all task_ids are strings
+        for i, tid in enumerate(task_ids):
+            if not isinstance(tid, str) or not tid.strip():
+                return _validation_error(
+                    field=f"task_ids[{i}]",
+                    action=action,
+                    message="Each task ID must be a non-empty string",
+                    request_id=request_id,
+                    code=ErrorCode.VALIDATION_ERROR,
+                )
+        task_ids = [tid.strip() for tid in task_ids]
+
+    # Optional: threshold in hours for stale detection
+    threshold_hours = payload.get("threshold_hours", STALE_TASK_THRESHOLD_HOURS)
+    if not isinstance(threshold_hours, (int, float)) or threshold_hours <= 0:
+        return _validation_error(
+            field="threshold_hours",
+            action=action,
+            message="threshold_hours must be a positive number",
+            request_id=request_id,
+        )
+
+    workspace = payload.get("workspace")
+    specs_dir = _resolve_specs_dir(config, workspace)
+    if specs_dir is None:
+        return _specs_dir_missing_error(request_id)
+
+    start = time.perf_counter()
+    result, error = reset_batch(
+        spec_id=spec_id.strip(),
+        task_ids=task_ids,
+        threshold_hours=float(threshold_hours),
+        specs_dir=specs_dir,
+    )
+    elapsed_ms = (time.perf_counter() - start) * 1000
+
+    if error:
+        _metrics.counter(_metric(action), labels={"status": "error"})
+        return asdict(
+            error_response(
+                error,
+                error_code=ErrorCode.OPERATION_FAILED,
+                error_type=ErrorType.VALIDATION,
+                request_id=request_id,
+                details=result if result else None,
+            )
+        )
+
+    _metrics.timer(_metric(action) + ".duration_ms", elapsed_ms)
+    _metrics.counter(_metric(action), labels={"status": "success"})
+
+    response = success_response(
+        spec_id=spec_id.strip(),
+        reset=result.get("reset", []),
+        reset_count=result.get("reset_count", 0),
+        errors=result.get("errors"),
+        message=result.get("message"),
+        request_id=request_id,
+        telemetry={"duration_ms": round(elapsed_ms, 2)},
+    )
+    return _attach_meta(asdict(response), request_id=request_id, duration_ms=elapsed_ms)
+
+
 def _handle_next(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
     request_id = _request_id()
     action = "next"
@@ -552,7 +873,7 @@ def _handle_list(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
     if has_more and page_tasks:
         next_cursor = encode_cursor({"last_id": page_tasks[-1].get("id")})
 
-    (time.perf_counter() - start) * 1000
+    _ = (time.perf_counter() - start) * 1000  # timing placeholder
     warnings = _pagination_warnings(total_count, has_more)
     response = paginated_response(
         data={
@@ -980,6 +1301,7 @@ def _handle_start(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
         )
 
     update_parent_status(spec_data, task_id.strip())
+    sync_computed_fields(spec_data)
 
     if note:
         add_journal_entry(
@@ -1069,8 +1391,38 @@ def _handle_complete(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
         )
 
     update_parent_status(spec_data, task_id.strip())
+    sync_computed_fields(spec_data)
 
     task_data = spec_data.get("hierarchy", {}).get(task_id.strip(), {})
+
+    # Determine if commit is suggested based on git cadence config
+    suggest_commit = False
+    commit_scope: Optional[str] = None
+    commit_message_hint: Optional[str] = None
+
+    if config.git.enabled:
+        cadence = config.git.commit_cadence
+        hierarchy = spec_data.get("hierarchy", {})
+
+        if cadence == "task":
+            suggest_commit = True
+            commit_scope = "task"
+            commit_message_hint = f"task: {task_data.get('title', task_id.strip())}"
+        elif cadence == "phase":
+            # Check if parent phase just completed
+            parent_id = task_data.get("parent")
+            if parent_id:
+                parent_data = hierarchy.get(parent_id, {})
+                # Only suggest commit if parent is a phase and is now completed
+                if (
+                    parent_data.get("type") == "phase"
+                    and parent_data.get("status") == "completed"
+                ):
+                    suggest_commit = True
+                    commit_scope = "phase"
+                    commit_message_hint = (
+                        f"phase: {parent_data.get('title', parent_id)}"
+                    )
     add_journal_entry(
         spec_data,
         title=f"Task Completed: {task_data.get('title', task_id.strip())}",
@@ -1103,6 +1455,9 @@ def _handle_complete(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
             "total_tasks": progress.get("total_tasks", 0),
             "percentage": progress.get("percentage", 0),
         },
+        suggest_commit=suggest_commit,
+        commit_scope=commit_scope,
+        commit_message_hint=commit_message_hint,
         request_id=request_id,
         telemetry={"duration_ms": round(elapsed_ms, 2)},
     )
@@ -1195,6 +1550,7 @@ def _handle_block(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
         task_id=task_id.strip(),
         author="foundry-mcp",
     )
+    sync_computed_fields(spec_data)
 
     if specs_dir is None or not save_spec(spec_id.strip(), spec_data, specs_dir):
         return asdict(
@@ -1294,6 +1650,7 @@ def _handle_unblock(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
         task_id=task_id.strip(),
         author="foundry-mcp",
     )
+    sync_computed_fields(spec_data)
 
     if specs_dir is None or not save_spec(spec_id.strip(), spec_data, specs_dir):
         return asdict(
@@ -1418,11 +1775,23 @@ def _handle_add(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
     action = "add"
     spec_id = payload.get("spec_id")
     parent = payload.get("parent")
+    phase_id = payload.get("phase_id")  # Alias for parent
+
+    # Use phase_id as parent if parent not provided
+    if parent is None and phase_id is not None:
+        parent = phase_id
+
     title = payload.get("title")
     description = payload.get("description")
     task_type = payload.get("task_type", "task")
     estimated_hours = payload.get("estimated_hours")
     position = payload.get("position")
+    file_path = payload.get("file_path")
+
+    # Research-specific parameters
+    research_type = payload.get("research_type")
+    blocking_mode = payload.get("blocking_mode")
+    query = payload.get("query")
 
     if not isinstance(spec_id, str) or not spec_id.strip():
         return _validation_error(
@@ -1477,6 +1846,57 @@ def _handle_add(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
             request_id=request_id,
             code=ErrorCode.INVALID_FORMAT,
         )
+    if file_path is not None and not isinstance(file_path, str):
+        return _validation_error(
+            field="file_path",
+            action=action,
+            message="file_path must be a string",
+            request_id=request_id,
+            code=ErrorCode.INVALID_FORMAT,
+        )
+
+    # Validate research-specific parameters when task_type is "research"
+    if task_type == "research":
+        from foundry_mcp.core.validation import VALID_RESEARCH_TYPES, RESEARCH_BLOCKING_MODES
+
+        if research_type is not None and not isinstance(research_type, str):
+            return _validation_error(
+                field="research_type",
+                action=action,
+                message="research_type must be a string",
+                request_id=request_id,
+                code=ErrorCode.INVALID_FORMAT,
+            )
+        if research_type and research_type not in VALID_RESEARCH_TYPES:
+            return _validation_error(
+                field="research_type",
+                action=action,
+                message=f"Must be one of: {', '.join(sorted(VALID_RESEARCH_TYPES))}",
+                request_id=request_id,
+            )
+        if blocking_mode is not None and not isinstance(blocking_mode, str):
+            return _validation_error(
+                field="blocking_mode",
+                action=action,
+                message="blocking_mode must be a string",
+                request_id=request_id,
+                code=ErrorCode.INVALID_FORMAT,
+            )
+        if blocking_mode and blocking_mode not in RESEARCH_BLOCKING_MODES:
+            return _validation_error(
+                field="blocking_mode",
+                action=action,
+                message=f"Must be one of: {', '.join(sorted(RESEARCH_BLOCKING_MODES))}",
+                request_id=request_id,
+            )
+        if query is not None and not isinstance(query, str):
+            return _validation_error(
+                field="query",
+                action=action,
+                message="query must be a string",
+                request_id=request_id,
+                code=ErrorCode.INVALID_FORMAT,
+            )
 
     dry_run = payload.get("dry_run", False)
     if dry_run is not None and not isinstance(dry_run, bool):
@@ -1518,15 +1938,22 @@ def _handle_add(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
             )
 
         elapsed_ms = (time.perf_counter() - start) * 1000
+        dry_run_data: Dict[str, Any] = {
+            "spec_id": spec_id.strip(),
+            "parent": parent.strip(),
+            "title": title.strip(),
+            "task_type": task_type,
+            "position": position,
+            "file_path": file_path.strip() if file_path else None,
+            "dry_run": True,
+        }
+        # Include research parameters in dry_run response
+        if task_type == "research":
+            dry_run_data["research_type"] = research_type
+            dry_run_data["blocking_mode"] = blocking_mode
+            dry_run_data["query"] = query
         response = success_response(
-            data={
-                "spec_id": spec_id.strip(),
-                "parent": parent.strip(),
-                "title": title.strip(),
-                "task_type": task_type,
-                "position": position,
-                "dry_run": True,
-            },
+            data=dry_run_data,
             request_id=request_id,
             telemetry={"duration_ms": round(elapsed_ms, 2)},
         )
@@ -1544,7 +1971,12 @@ def _handle_add(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
         task_type=task_type,
         estimated_hours=float(estimated_hours) if estimated_hours is not None else None,
         position=position,
+        file_path=file_path,
         specs_dir=specs_dir,
+        # Research-specific parameters
+        research_type=research_type,
+        blocking_mode=blocking_mode,
+        query=query,
     )
     elapsed_ms = (time.perf_counter() - start) * 1000
 
@@ -1897,9 +2329,21 @@ def _handle_update_metadata(*, config: ServerConfig, payload: Dict[str, Any]) ->
             remediation="Provide custom_metadata as a JSON object",
         )
 
+    acceptance_criteria = payload.get("acceptance_criteria")
+    if acceptance_criteria is not None and not isinstance(acceptance_criteria, list):
+        return _validation_error(
+            field="acceptance_criteria",
+            action=action,
+            message="acceptance_criteria must be a list of strings",
+            request_id=request_id,
+            code=ErrorCode.INVALID_FORMAT,
+        )
+
     update_fields = [
+        payload.get("title"),
         payload.get("file_path"),
         payload.get("description"),
+        acceptance_criteria,
         payload.get("task_category"),
         payload.get("actual_hours"),
         payload.get("status_note"),
@@ -1911,12 +2355,12 @@ def _handle_update_metadata(*, config: ServerConfig, payload: Dict[str, Any]) ->
     )
     if not has_update:
         return _validation_error(
-            field="file_path",
+            field="title",
             action=action,
-            message="Provide at least one metadata field",
+            message="Provide at least one field to update",
             request_id=request_id,
             code=ErrorCode.MISSING_REQUIRED,
-            remediation="Provide file_path, description, task_category, actual_hours, status_note, verification_type, command, and/or custom_metadata",
+            remediation="Provide title, file_path, description, acceptance_criteria, task_category, actual_hours, status_note, verification_type, command, and/or custom_metadata",
         )
 
     workspace = payload.get("workspace")
@@ -1944,10 +2388,14 @@ def _handle_update_metadata(*, config: ServerConfig, payload: Dict[str, Any]) ->
             )
 
         fields_updated: List[str] = []
+        if payload.get("title") is not None:
+            fields_updated.append("title")
         if payload.get("file_path") is not None:
             fields_updated.append("file_path")
         if payload.get("description") is not None:
             fields_updated.append("description")
+        if acceptance_criteria is not None:
+            fields_updated.append("acceptance_criteria")
         if payload.get("task_category") is not None:
             fields_updated.append("task_category")
         if payload.get("actual_hours") is not None:
@@ -1981,14 +2429,17 @@ def _handle_update_metadata(*, config: ServerConfig, payload: Dict[str, Any]) ->
     result, error = update_task_metadata(
         spec_id=spec_id.strip(),
         task_id=task_id.strip(),
+        title=payload.get("title"),
         file_path=payload.get("file_path"),
         description=payload.get("description"),
+        acceptance_criteria=acceptance_criteria,
         task_category=payload.get("task_category"),
         actual_hours=payload.get("actual_hours"),
         status_note=payload.get("status_note"),
         verification_type=payload.get("verification_type"),
         command=payload.get("command"),
         custom_metadata=custom_metadata,
+        dry_run=dry_run_bool,
         specs_dir=specs_dir,
     )
     elapsed_ms = (time.perf_counter() - start) * 1000
@@ -2022,24 +2473,1146 @@ def _handle_update_metadata(*, config: ServerConfig, payload: Dict[str, Any]) ->
     return asdict(response)
 
 
-_ACTION_DEFINITIONS = [
-    ActionDefinition(
-        name="prepare",
-        handler=_handle_prepare,
-        summary="Prepare next actionable task context",
-    ),
-    ActionDefinition(
-        name="next", handler=_handle_next, summary="Return the next actionable task"
-    ),
-    ActionDefinition(
-        name="info", handler=_handle_info, summary="Fetch task metadata by ID"
-    ),
-    ActionDefinition(
-        name="check-deps",
-        handler=_handle_check_deps,
-        summary="Analyze task dependencies and blockers",
-    ),
-    ActionDefinition(name="start", handler=_handle_start, summary="Start a task"),
+def _handle_move(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
+    """Move a task to a new position or parent.
+
+    Supports two modes:
+    1. Reorder within parent: only specify position (new_parent=None)
+    2. Reparent to different phase/task: specify new_parent, optionally position
+
+    Updates task counts on affected parents. Prevents circular references.
+    Emits warnings for cross-phase moves that might affect dependencies.
+    """
+    request_id = _request_id()
+    action = "move"
+    spec_id = payload.get("spec_id")
+    task_id = payload.get("task_id")
+    new_parent = payload.get("parent")  # Target parent (phase or task ID)
+    position = payload.get("position")  # 1-based position in children list
+
+    # Validate required fields
+    if not isinstance(spec_id, str) or not spec_id.strip():
+        return _validation_error(
+            field="spec_id",
+            action=action,
+            message="Provide a non-empty spec identifier",
+            request_id=request_id,
+        )
+    if not isinstance(task_id, str) or not task_id.strip():
+        return _validation_error(
+            field="task_id",
+            action=action,
+            message="Provide a non-empty task identifier",
+            request_id=request_id,
+        )
+
+    # Validate optional new_parent
+    if new_parent is not None and (
+        not isinstance(new_parent, str) or not new_parent.strip()
+    ):
+        return _validation_error(
+            field="parent",
+            action=action,
+            message="parent must be a non-empty string if provided",
+            request_id=request_id,
+            code=ErrorCode.INVALID_FORMAT,
+        )
+
+    # Validate optional position (must be positive integer)
+    if position is not None:
+        if not isinstance(position, int) or position < 1:
+            return _validation_error(
+                field="position",
+                action=action,
+                message="position must be a positive integer (1-based)",
+                request_id=request_id,
+                code=ErrorCode.INVALID_FORMAT,
+            )
+
+    # Validate dry_run
+    dry_run = payload.get("dry_run", False)
+    if dry_run is not None and not isinstance(dry_run, bool):
+        return _validation_error(
+            field="dry_run",
+            action=action,
+            message="dry_run must be a boolean",
+            request_id=request_id,
+            code=ErrorCode.INVALID_FORMAT,
+        )
+    dry_run_bool = bool(dry_run)
+
+    workspace = payload.get("workspace")
+    specs_dir = _resolve_specs_dir(config, workspace)
+    if specs_dir is None:
+        return _specs_dir_missing_error(request_id)
+
+    start = time.perf_counter()
+
+    # Call the core move_task function
+    result, error, warnings = move_task(
+        spec_id=spec_id.strip(),
+        task_id=task_id.strip(),
+        new_parent=new_parent.strip() if new_parent else None,
+        position=position,
+        dry_run=dry_run_bool,
+        specs_dir=specs_dir,
+    )
+    elapsed_ms = (time.perf_counter() - start) * 1000
+
+    if error or result is None:
+        # Determine appropriate error code based on error message
+        error_lower = (error or "").lower()
+        if "not found" in error_lower:
+            code = ErrorCode.TASK_NOT_FOUND
+            err_type = ErrorType.NOT_FOUND
+            remediation = "Verify the task ID and parent ID exist in the specification"
+        elif "circular" in error_lower:
+            code = ErrorCode.CIRCULAR_DEPENDENCY
+            err_type = ErrorType.CONFLICT
+            remediation = "Task cannot be moved under its own descendants"
+        elif "invalid position" in error_lower:
+            code = ErrorCode.INVALID_POSITION
+            err_type = ErrorType.VALIDATION
+            remediation = "Specify a valid position within the children list"
+        elif "cannot move" in error_lower or "invalid" in error_lower:
+            code = ErrorCode.INVALID_PARENT
+            err_type = ErrorType.VALIDATION
+            remediation = "Specify a valid phase, group, or task as the target parent"
+        else:
+            code = ErrorCode.VALIDATION_ERROR
+            err_type = ErrorType.VALIDATION
+            remediation = "Check task ID, parent, and position parameters"
+
+        return asdict(
+            error_response(
+                error or "Failed to move task",
+                error_code=code,
+                error_type=err_type,
+                remediation=remediation,
+                request_id=request_id,
+                telemetry={"duration_ms": round(elapsed_ms, 2)},
+            )
+        )
+
+    # Build success response with warnings if any
+    response = success_response(
+        **result,
+        request_id=request_id,
+        warnings=warnings if warnings else None,
+        telemetry={"duration_ms": round(elapsed_ms, 2)},
+    )
+    _metrics.timer(_metric(action) + ".duration_ms", elapsed_ms)
+    _metrics.counter(
+        _metric(action),
+        labels={"status": "success", "dry_run": str(dry_run_bool).lower()},
+    )
+    return asdict(response)
+
+
+def _handle_add_dependency(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
+    """Add a dependency relationship between two tasks.
+
+    Manages blocks, blocked_by, and depends relationships.
+    Updates both source and target tasks atomically.
+
+    Dependency types:
+    - blocks: Source task blocks target (target cannot start until source completes)
+    - blocked_by: Source task is blocked by target (source cannot start until target completes)
+    - depends: Soft dependency (informational, doesn't block)
+    """
+    request_id = _request_id()
+    action = "add-dependency"
+    spec_id = payload.get("spec_id")
+    task_id = payload.get("task_id")  # Source task
+    target_id = payload.get("target_id")  # Target task
+    dependency_type = payload.get("dependency_type", "blocks")
+
+    # Validate required fields
+    if not isinstance(spec_id, str) or not spec_id.strip():
+        return _validation_error(
+            field="spec_id",
+            action=action,
+            message="Provide a non-empty spec identifier",
+            request_id=request_id,
+        )
+    if not isinstance(task_id, str) or not task_id.strip():
+        return _validation_error(
+            field="task_id",
+            action=action,
+            message="Provide a non-empty source task identifier",
+            request_id=request_id,
+        )
+    if not isinstance(target_id, str) or not target_id.strip():
+        return _validation_error(
+            field="target_id",
+            action=action,
+            message="Provide a non-empty target task identifier",
+            request_id=request_id,
+        )
+
+    # Validate dependency_type
+    valid_types = ("blocks", "blocked_by", "depends")
+    if dependency_type not in valid_types:
+        return _validation_error(
+            field="dependency_type",
+            action=action,
+            message=f"Must be one of: {', '.join(valid_types)}",
+            request_id=request_id,
+            code=ErrorCode.INVALID_FORMAT,
+        )
+
+    # Validate dry_run
+    dry_run = payload.get("dry_run", False)
+    if dry_run is not None and not isinstance(dry_run, bool):
+        return _validation_error(
+            field="dry_run",
+            action=action,
+            message="dry_run must be a boolean",
+            request_id=request_id,
+            code=ErrorCode.INVALID_FORMAT,
+        )
+    dry_run_bool = bool(dry_run)
+
+    workspace = payload.get("workspace")
+    specs_dir = _resolve_specs_dir(config, workspace)
+    if specs_dir is None:
+        return _specs_dir_missing_error(request_id)
+
+    start = time.perf_counter()
+
+    # Call the core function
+    result, error = manage_task_dependency(
+        spec_id=spec_id.strip(),
+        source_task_id=task_id.strip(),
+        target_task_id=target_id.strip(),
+        dependency_type=dependency_type,
+        action="add",
+        dry_run=dry_run_bool,
+        specs_dir=specs_dir,
+    )
+    elapsed_ms = (time.perf_counter() - start) * 1000
+
+    if error or result is None:
+        # Determine appropriate error code based on error message
+        error_lower = (error or "").lower()
+        if "not found" in error_lower:
+            code = ErrorCode.TASK_NOT_FOUND
+            err_type = ErrorType.NOT_FOUND
+            remediation = "Verify both task IDs exist in the specification"
+        elif "circular" in error_lower:
+            code = ErrorCode.CIRCULAR_DEPENDENCY
+            err_type = ErrorType.CONFLICT
+            remediation = "This dependency would create a cycle"
+        elif "itself" in error_lower:
+            code = ErrorCode.SELF_REFERENCE
+            err_type = ErrorType.VALIDATION
+            remediation = "A task cannot depend on itself"
+        elif "already exists" in error_lower:
+            code = ErrorCode.DUPLICATE_ENTRY
+            err_type = ErrorType.CONFLICT
+            remediation = "This dependency already exists"
+        else:
+            code = ErrorCode.VALIDATION_ERROR
+            err_type = ErrorType.VALIDATION
+            remediation = "Check task IDs and dependency type"
+
+        return asdict(
+            error_response(
+                error or "Failed to add dependency",
+                error_code=code,
+                error_type=err_type,
+                remediation=remediation,
+                request_id=request_id,
+                telemetry={"duration_ms": round(elapsed_ms, 2)},
+            )
+        )
+
+    # Build success response
+    response = success_response(
+        **result,
+        request_id=request_id,
+        telemetry={"duration_ms": round(elapsed_ms, 2)},
+    )
+    _metrics.timer(_metric(action) + ".duration_ms", elapsed_ms)
+    _metrics.counter(
+        _metric(action),
+        labels={"status": "success", "dry_run": str(dry_run_bool).lower()},
+    )
+    return asdict(response)
+
+
+def _handle_remove_dependency(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
+    """Remove a dependency relationship between two tasks.
+
+    Removes blocks, blocked_by, or depends relationships.
+    Updates both source and target tasks atomically for reciprocal relationships.
+    """
+    request_id = _request_id()
+    action = "remove-dependency"
+    spec_id = payload.get("spec_id")
+    task_id = payload.get("task_id")  # Source task
+    target_id = payload.get("target_id")  # Target task
+    dependency_type = payload.get("dependency_type", "blocks")
+
+    # Validate required fields
+    if not isinstance(spec_id, str) or not spec_id.strip():
+        return _validation_error(
+            field="spec_id",
+            action=action,
+            message="Provide a non-empty spec identifier",
+            request_id=request_id,
+        )
+    if not isinstance(task_id, str) or not task_id.strip():
+        return _validation_error(
+            field="task_id",
+            action=action,
+            message="Provide a non-empty source task identifier",
+            request_id=request_id,
+        )
+    if not isinstance(target_id, str) or not target_id.strip():
+        return _validation_error(
+            field="target_id",
+            action=action,
+            message="Provide a non-empty target task identifier",
+            request_id=request_id,
+        )
+
+    # Validate dependency_type
+    valid_types = ("blocks", "blocked_by", "depends")
+    if dependency_type not in valid_types:
+        return _validation_error(
+            field="dependency_type",
+            action=action,
+            message=f"Must be one of: {', '.join(valid_types)}",
+            request_id=request_id,
+            code=ErrorCode.INVALID_FORMAT,
+        )
+
+    # Validate dry_run
+    dry_run = payload.get("dry_run", False)
+    if dry_run is not None and not isinstance(dry_run, bool):
+        return _validation_error(
+            field="dry_run",
+            action=action,
+            message="dry_run must be a boolean",
+            request_id=request_id,
+            code=ErrorCode.INVALID_FORMAT,
+        )
+    dry_run_bool = bool(dry_run)
+
+    workspace = payload.get("workspace")
+    specs_dir = _resolve_specs_dir(config, workspace)
+    if specs_dir is None:
+        return _specs_dir_missing_error(request_id)
+
+    start = time.perf_counter()
+
+    # Call the core function
+    result, error = manage_task_dependency(
+        spec_id=spec_id.strip(),
+        source_task_id=task_id.strip(),
+        target_task_id=target_id.strip(),
+        dependency_type=dependency_type,
+        action="remove",
+        dry_run=dry_run_bool,
+        specs_dir=specs_dir,
+    )
+    elapsed_ms = (time.perf_counter() - start) * 1000
+
+    if error or result is None:
+        # Determine appropriate error code based on error message
+        error_lower = (error or "").lower()
+        if "does not exist" in error_lower:
+            # Dependency relationship doesn't exist
+            code = ErrorCode.DEPENDENCY_NOT_FOUND
+            err_type = ErrorType.NOT_FOUND
+            remediation = "This dependency does not exist"
+        elif "not found" in error_lower:
+            # Task or spec not found
+            code = ErrorCode.TASK_NOT_FOUND
+            err_type = ErrorType.NOT_FOUND
+            remediation = "Verify both task IDs exist in the specification"
+        else:
+            code = ErrorCode.VALIDATION_ERROR
+            err_type = ErrorType.VALIDATION
+            remediation = "Check task IDs and dependency type"
+
+        return asdict(
+            error_response(
+                error or "Failed to remove dependency",
+                error_code=code,
+                error_type=err_type,
+                remediation=remediation,
+                request_id=request_id,
+                telemetry={"duration_ms": round(elapsed_ms, 2)},
+            )
+        )
+
+    # Build success response
+    response = success_response(
+        **result,
+        request_id=request_id,
+        telemetry={"duration_ms": round(elapsed_ms, 2)},
+    )
+    _metrics.timer(_metric(action) + ".duration_ms", elapsed_ms)
+    _metrics.counter(
+        _metric(action),
+        labels={"status": "success", "dry_run": str(dry_run_bool).lower()},
+    )
+    return asdict(response)
+
+
+def _handle_add_requirement(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
+    """Add a structured requirement to a task's metadata.
+
+    Requirements are stored in metadata.requirements as a list of objects:
+    [{"id": "req-1", "type": "acceptance", "text": "..."}, ...]
+
+    Each requirement has:
+    - id: Auto-generated unique ID (e.g., "req-1", "req-2")
+    - type: Requirement type (acceptance, technical, constraint)
+    - text: Requirement description text
+    """
+    request_id = _request_id()
+    action = "add-requirement"
+    spec_id = payload.get("spec_id")
+    task_id = payload.get("task_id")
+    requirement_type = payload.get("requirement_type")
+    text = payload.get("text")
+
+    # Validate required fields
+    if not isinstance(spec_id, str) or not spec_id.strip():
+        return _validation_error(
+            field="spec_id",
+            action=action,
+            message="Provide a non-empty spec identifier",
+            request_id=request_id,
+        )
+    if not isinstance(task_id, str) or not task_id.strip():
+        return _validation_error(
+            field="task_id",
+            action=action,
+            message="Provide a non-empty task identifier",
+            request_id=request_id,
+        )
+    if not isinstance(requirement_type, str) or not requirement_type.strip():
+        return _validation_error(
+            field="requirement_type",
+            action=action,
+            message="Provide a requirement type",
+            request_id=request_id,
+        )
+
+    # Validate requirement_type
+    requirement_type_lower = requirement_type.lower().strip()
+    if requirement_type_lower not in REQUIREMENT_TYPES:
+        return _validation_error(
+            field="requirement_type",
+            action=action,
+            message=f"Must be one of: {', '.join(REQUIREMENT_TYPES)}",
+            request_id=request_id,
+            code=ErrorCode.INVALID_FORMAT,
+        )
+
+    # Validate text
+    if not isinstance(text, str) or not text.strip():
+        return _validation_error(
+            field="text",
+            action=action,
+            message="Provide non-empty requirement text",
+            request_id=request_id,
+        )
+
+    # Validate dry_run
+    dry_run = payload.get("dry_run", False)
+    if dry_run is not None and not isinstance(dry_run, bool):
+        return _validation_error(
+            field="dry_run",
+            action=action,
+            message="dry_run must be a boolean",
+            request_id=request_id,
+            code=ErrorCode.INVALID_FORMAT,
+        )
+    dry_run_bool = bool(dry_run)
+
+    workspace = payload.get("workspace")
+    specs_dir = _resolve_specs_dir(config, workspace)
+    if specs_dir is None:
+        return _specs_dir_missing_error(request_id)
+
+    start = time.perf_counter()
+
+    # Call the core function
+    result, error = update_task_requirements(
+        spec_id=spec_id.strip(),
+        task_id=task_id.strip(),
+        action="add",
+        requirement_type=requirement_type_lower,
+        text=text.strip(),
+        dry_run=dry_run_bool,
+        specs_dir=specs_dir,
+    )
+    elapsed_ms = (time.perf_counter() - start) * 1000
+
+    if error or result is None:
+        # Determine appropriate error code based on error message
+        error_lower = (error or "").lower()
+        if "not found" in error_lower:
+            if "specification" in error_lower:
+                code = ErrorCode.SPEC_NOT_FOUND
+                err_type = ErrorType.NOT_FOUND
+                remediation = "Verify the spec ID exists"
+            else:
+                code = ErrorCode.TASK_NOT_FOUND
+                err_type = ErrorType.NOT_FOUND
+                remediation = "Verify the task ID exists in the specification"
+        elif "maximum" in error_lower or "limit" in error_lower:
+            code = ErrorCode.LIMIT_EXCEEDED
+            err_type = ErrorType.VALIDATION
+            remediation = "Remove some requirements before adding new ones"
+        elif "requirement_type" in error_lower:
+            code = ErrorCode.INVALID_FORMAT
+            err_type = ErrorType.VALIDATION
+            remediation = f"Use one of: {', '.join(REQUIREMENT_TYPES)}"
+        else:
+            code = ErrorCode.VALIDATION_ERROR
+            err_type = ErrorType.VALIDATION
+            remediation = "Check task ID and requirement fields"
+
+        return asdict(
+            error_response(
+                error or "Failed to add requirement",
+                error_code=code,
+                error_type=err_type,
+                remediation=remediation,
+                request_id=request_id,
+                telemetry={"duration_ms": round(elapsed_ms, 2)},
+            )
+        )
+
+    # Build success response
+    response = success_response(
+        **result,
+        request_id=request_id,
+        telemetry={"duration_ms": round(elapsed_ms, 2)},
+    )
+    _metrics.timer(_metric(action) + ".duration_ms", elapsed_ms)
+    _metrics.counter(
+        _metric(action),
+        labels={"status": "success", "dry_run": str(dry_run_bool).lower()},
+    )
+    return asdict(response)
+
+
+_VALID_NODE_TYPES = {"task", "verify", "phase", "subtask"}
+# Note: VALID_VERIFICATION_TYPES imported from foundry_mcp.core.validation
+
+
+def _match_nodes_for_batch(
+    hierarchy: Dict[str, Any],
+    *,
+    phase_id: Optional[str] = None,
+    pattern: Optional[str] = None,
+    node_type: Optional[str] = None,
+) -> List[str]:
+    """Filter nodes by phase_id, regex pattern on title/id, and/or node_type.
+
+    All provided filters are combined with AND logic.
+    Returns list of matching node IDs.
+    """
+    matched: List[str] = []
+    compiled_pattern = None
+    if pattern:
+        try:
+            compiled_pattern = re.compile(pattern, re.IGNORECASE)
+        except re.error:
+            return []  # Invalid regex returns empty
+
+    for node_id, node_data in hierarchy.items():
+        if node_id == "spec-root":
+            continue
+
+        # Filter by node_type if specified
+        if node_type and node_data.get("type") != node_type:
+            continue
+
+        # Filter by phase_id if specified (must be under that phase)
+        if phase_id:
+            node_parent = node_data.get("parent")
+            # Direct children of the phase
+            if node_parent != phase_id:
+                # Check if it's a nested child (e.g., subtask under task under phase)
+                parent_node = hierarchy.get(node_parent, {})
+                if parent_node.get("parent") != phase_id:
+                    continue
+
+        # Filter by regex pattern on title or node_id
+        if compiled_pattern:
+            title = node_data.get("title", "")
+            if not (compiled_pattern.search(title) or compiled_pattern.search(node_id)):
+                continue
+
+        matched.append(node_id)
+
+    return sorted(matched)
+
+
+def _handle_metadata_batch(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
+    """Batch update metadata across multiple tasks matching specified criteria.
+
+    Filters (combined with AND logic):
+    - status_filter: Filter by task status (pending, in_progress, completed, blocked)
+    - parent_filter: Filter by parent node ID (e.g., phase-1, task-2-1)
+    - pattern: Regex pattern to match task titles/IDs
+
+    Legacy filters (deprecated, use parent_filter instead):
+    - phase_id: Alias for parent_filter
+
+    Metadata fields supported:
+    - description, file_path, estimated_hours, category, labels, owners
+    - update_metadata: Dict for custom metadata fields (verification_type, command, etc.)
+    """
+    request_id = _request_id()
+    action = "metadata-batch"
+    start = time.perf_counter()
+
+    # Required: spec_id
+    spec_id = payload.get("spec_id")
+    if not isinstance(spec_id, str) or not spec_id.strip():
+        return _validation_error(
+            field="spec_id",
+            action=action,
+            message="Provide a non-empty spec identifier",
+            request_id=request_id,
+        )
+    spec_id = spec_id.strip()
+
+    # Extract filter parameters
+    status_filter = payload.get("status_filter")
+    parent_filter = payload.get("parent_filter")
+    phase_id = payload.get("phase_id")  # Legacy alias for parent_filter
+    pattern = payload.get("pattern")
+
+    # Use phase_id as parent_filter if parent_filter not provided (backwards compat)
+    if parent_filter is None and phase_id is not None:
+        parent_filter = phase_id
+
+    # Validate status_filter
+    if status_filter is not None:
+        if not isinstance(status_filter, str) or status_filter not in _ALLOWED_STATUS:
+            return _validation_error(
+                field="status_filter",
+                action=action,
+                message=f"status_filter must be one of: {sorted(_ALLOWED_STATUS)}",
+                request_id=request_id,
+                code=ErrorCode.INVALID_FORMAT,
+            )
+
+    # Validate parent_filter
+    if parent_filter is not None:
+        if not isinstance(parent_filter, str) or not parent_filter.strip():
+            return _validation_error(
+                field="parent_filter",
+                action=action,
+                message="parent_filter must be a non-empty string",
+                request_id=request_id,
+                code=ErrorCode.INVALID_FORMAT,
+            )
+        parent_filter = parent_filter.strip()
+
+    # Validate pattern
+    if pattern is not None:
+        if not isinstance(pattern, str) or not pattern.strip():
+            return _validation_error(
+                field="pattern",
+                action=action,
+                message="pattern must be a non-empty string",
+                request_id=request_id,
+                code=ErrorCode.INVALID_FORMAT,
+            )
+        try:
+            re.compile(pattern)
+        except re.error as exc:
+            return _validation_error(
+                field="pattern",
+                action=action,
+                message=f"Invalid regex pattern: {exc}",
+                request_id=request_id,
+                code=ErrorCode.INVALID_FORMAT,
+            )
+        pattern = pattern.strip()
+
+    # At least one filter must be provided
+    if not any([status_filter, parent_filter, pattern]):
+        return _validation_error(
+            field="status_filter",
+            action=action,
+            message="Provide at least one filter: status_filter, parent_filter, or pattern",
+            request_id=request_id,
+            code=ErrorCode.MISSING_REQUIRED,
+            remediation="Specify status_filter, parent_filter (or phase_id), and/or pattern to target tasks",
+        )
+
+    # Extract metadata fields
+    description = payload.get("description")
+    file_path = payload.get("file_path")
+    estimated_hours = payload.get("estimated_hours")
+    category = payload.get("category")
+    labels = payload.get("labels")
+    owners = payload.get("owners")
+    update_metadata = payload.get("update_metadata")  # Dict for custom fields
+    dry_run = payload.get("dry_run", False)
+
+    # Validate metadata fields
+    if description is not None and not isinstance(description, str):
+        return _validation_error(
+            field="description",
+            action=action,
+            message="description must be a string",
+            request_id=request_id,
+            code=ErrorCode.INVALID_FORMAT,
+        )
+
+    if file_path is not None and not isinstance(file_path, str):
+        return _validation_error(
+            field="file_path",
+            action=action,
+            message="file_path must be a string",
+            request_id=request_id,
+            code=ErrorCode.INVALID_FORMAT,
+        )
+
+    if estimated_hours is not None:
+        if not isinstance(estimated_hours, (int, float)) or estimated_hours < 0:
+            return _validation_error(
+                field="estimated_hours",
+                action=action,
+                message="estimated_hours must be a non-negative number",
+                request_id=request_id,
+                code=ErrorCode.INVALID_FORMAT,
+            )
+
+    if category is not None and not isinstance(category, str):
+        return _validation_error(
+            field="category",
+            action=action,
+            message="category must be a string",
+            request_id=request_id,
+            code=ErrorCode.INVALID_FORMAT,
+        )
+
+    if labels is not None:
+        if not isinstance(labels, dict) or not all(
+            isinstance(k, str) and isinstance(v, str) for k, v in labels.items()
+        ):
+            return _validation_error(
+                field="labels",
+                action=action,
+                message="labels must be a dict with string keys and values",
+                request_id=request_id,
+                code=ErrorCode.INVALID_FORMAT,
+            )
+
+    if owners is not None:
+        if not isinstance(owners, list) or not all(isinstance(o, str) for o in owners):
+            return _validation_error(
+                field="owners",
+                action=action,
+                message="owners must be a list of strings",
+                request_id=request_id,
+                code=ErrorCode.INVALID_FORMAT,
+            )
+
+    if update_metadata is not None and not isinstance(update_metadata, dict):
+        return _validation_error(
+            field="update_metadata",
+            action=action,
+            message="update_metadata must be a dict",
+            request_id=request_id,
+            code=ErrorCode.INVALID_FORMAT,
+        )
+
+    if dry_run is not None and not isinstance(dry_run, bool):
+        return _validation_error(
+            field="dry_run",
+            action=action,
+            message="dry_run must be a boolean",
+            request_id=request_id,
+            code=ErrorCode.INVALID_FORMAT,
+        )
+
+    # At least one metadata field must be provided
+    has_metadata = any([
+        description is not None,
+        file_path is not None,
+        estimated_hours is not None,
+        category is not None,
+        labels is not None,
+        owners is not None,
+        update_metadata,
+    ])
+    if not has_metadata:
+        return _validation_error(
+            field="description",
+            action=action,
+            message="Provide at least one metadata field to update",
+            request_id=request_id,
+            code=ErrorCode.MISSING_REQUIRED,
+            remediation="Specify description, file_path, estimated_hours, category, labels, owners, or update_metadata",
+        )
+
+    # Resolve specs directory
+    workspace = payload.get("workspace")
+    specs_dir = _resolve_specs_dir(config, workspace)
+    if specs_dir is None:
+        return _specs_dir_missing_error(request_id)
+
+    # Delegate to core helper
+    result, error = batch_update_tasks(
+        spec_id,
+        status_filter=status_filter,
+        parent_filter=parent_filter,
+        pattern=pattern,
+        description=description,
+        file_path=file_path,
+        estimated_hours=float(estimated_hours) if estimated_hours is not None else None,
+        category=category,
+        labels=labels,
+        owners=owners,
+        custom_metadata=update_metadata,
+        dry_run=bool(dry_run),
+        specs_dir=specs_dir,
+    )
+
+    elapsed_ms = (time.perf_counter() - start) * 1000
+
+    if error:
+        _metrics.counter(_metric(action), labels={"status": "error"})
+        # Map helper errors to response-v2 format
+        if "not found" in error.lower():
+            return asdict(
+                error_response(
+                    error,
+                    error_code=ErrorCode.NOT_FOUND,
+                    error_type=ErrorType.NOT_FOUND,
+                    remediation="Check spec_id and parent_filter values",
+                    request_id=request_id,
+                )
+            )
+        if "at least one" in error.lower() or "must be" in error.lower():
+            return asdict(
+                error_response(
+                    error,
+                    error_code=ErrorCode.VALIDATION_ERROR,
+                    error_type=ErrorType.VALIDATION,
+                    remediation="Check filter and metadata parameters",
+                    request_id=request_id,
+                )
+            )
+        return asdict(
+            error_response(
+                error,
+                error_code=ErrorCode.INTERNAL_ERROR,
+                error_type=ErrorType.INTERNAL,
+                remediation="Check filesystem permissions and retry",
+                request_id=request_id,
+            )
+        )
+
+    assert result is not None
+
+    # Build response with response-v2 envelope
+    warnings: List[str] = result.get("warnings", [])
+    if result["matched_count"] > _TASK_WARNING_THRESHOLD and not warnings:
+        warnings.append(
+            f"Updated {result['matched_count']} tasks; consider using more specific filters."
+        )
+
+    response = success_response(
+        spec_id=result["spec_id"],
+        matched_count=result["matched_count"],
+        updated_count=result["updated_count"],
+        skipped_count=result.get("skipped_count", 0),
+        nodes=result["nodes"],
+        filters=result["filters"],
+        metadata_applied=result["metadata_applied"],
+        dry_run=result["dry_run"],
+        request_id=request_id,
+        telemetry={"duration_ms": round(elapsed_ms, 2)},
+    )
+
+    response_dict = asdict(response)
+    if warnings:
+        meta = response_dict.setdefault("meta", {})
+        meta["warnings"] = warnings
+    if result.get("skipped_tasks"):
+        response_dict["data"]["skipped_tasks"] = result["skipped_tasks"]
+
+    _metrics.timer(_metric(action) + ".duration_ms", elapsed_ms)
+    _metrics.counter(_metric(action), labels={"status": "success"})
+    return response_dict
+
+
+def _handle_fix_verification_types(
+    *, config: ServerConfig, payload: Dict[str, Any]
+) -> dict:
+    """Fix verification types across all verify nodes in a spec.
+
+    This action:
+    1. Finds all verify nodes with invalid or missing verification_type
+    2. Maps legacy values (e.g., 'test' -> 'run-tests') using VERIFICATION_TYPE_MAPPING
+    3. Sets missing types to 'run-tests' (default)
+    4. Sets unknown types to 'manual' (fallback)
+
+    Supports dry-run mode to preview changes without persisting.
+    """
+    request_id = _request_id()
+    action = "fix-verification-types"
+
+    # Required: spec_id
+    spec_id = payload.get("spec_id")
+    if not isinstance(spec_id, str) or not spec_id.strip():
+        return _validation_error(
+            field="spec_id",
+            action=action,
+            message="Provide a non-empty spec identifier",
+            request_id=request_id,
+        )
+
+    dry_run = payload.get("dry_run", False)
+    if dry_run is not None and not isinstance(dry_run, bool):
+        return _validation_error(
+            field="dry_run",
+            action=action,
+            message="dry_run must be a boolean",
+            request_id=request_id,
+            code=ErrorCode.INVALID_FORMAT,
+        )
+    dry_run_bool = bool(dry_run)
+
+    # Load spec
+    workspace = payload.get("workspace")
+    specs_dir = _resolve_specs_dir(config, workspace)
+    spec_data, error = _load_spec_data(spec_id.strip(), specs_dir, request_id)
+    if error:
+        return error
+    assert spec_data is not None
+
+    start = time.perf_counter()
+    hierarchy = spec_data.get("hierarchy", {})
+
+    # Find verify nodes and collect fixes
+    fixes: List[Dict[str, Any]] = []
+    for node_id, node_data in hierarchy.items():
+        if node_data.get("type") != "verify":
+            continue
+
+        metadata = node_data.get("metadata", {})
+        current_type = metadata.get("verification_type")
+
+        # Determine the fix needed
+        fix_info: Optional[Dict[str, Any]] = None
+
+        if current_type is None:
+            # Missing verification_type -> default to 'run-tests'
+            fix_info = {
+                "node_id": node_id,
+                "title": node_data.get("title", ""),
+                "issue": "missing",
+                "old_value": None,
+                "new_value": "run-tests",
+            }
+        elif current_type not in VALID_VERIFICATION_TYPES:
+            # Invalid type -> check mapping or fallback to 'manual'
+            mapped = VERIFICATION_TYPE_MAPPING.get(current_type)
+            if mapped:
+                fix_info = {
+                    "node_id": node_id,
+                    "title": node_data.get("title", ""),
+                    "issue": "legacy",
+                    "old_value": current_type,
+                    "new_value": mapped,
+                }
+            else:
+                fix_info = {
+                    "node_id": node_id,
+                    "title": node_data.get("title", ""),
+                    "issue": "invalid",
+                    "old_value": current_type,
+                    "new_value": "manual",
+                }
+
+        if fix_info:
+            fixes.append(fix_info)
+
+            if not dry_run_bool:
+                # Apply the fix
+                if "metadata" not in node_data:
+                    node_data["metadata"] = {}
+                node_data["metadata"]["verification_type"] = fix_info["new_value"]
+
+    # Save if not dry_run and there were fixes
+    if not dry_run_bool and fixes:
+        if specs_dir is None or not save_spec(spec_id.strip(), spec_data, specs_dir):
+            return asdict(
+                error_response(
+                    "Failed to save spec after fixing verification types",
+                    error_code=ErrorCode.INTERNAL_ERROR,
+                    error_type=ErrorType.INTERNAL,
+                    remediation="Check filesystem permissions and retry",
+                    request_id=request_id,
+                )
+            )
+
+    elapsed_ms = (time.perf_counter() - start) * 1000
+
+    # Count by issue type
+    missing_count = sum(1 for f in fixes if f["issue"] == "missing")
+    legacy_count = sum(1 for f in fixes if f["issue"] == "legacy")
+    invalid_count = sum(1 for f in fixes if f["issue"] == "invalid")
+
+    response = success_response(
+        spec_id=spec_id.strip(),
+        total_fixes=len(fixes),
+        applied_count=len(fixes) if not dry_run_bool else 0,
+        fixes=fixes,
+        summary={
+            "missing_set_to_run_tests": missing_count,
+            "legacy_mapped": legacy_count,
+            "invalid_set_to_manual": invalid_count,
+        },
+        valid_types=sorted(VALID_VERIFICATION_TYPES),
+        legacy_mappings=VERIFICATION_TYPE_MAPPING,
+        dry_run=dry_run_bool,
+        request_id=request_id,
+        telemetry={"duration_ms": round(elapsed_ms, 2)},
+    )
+
+    _metrics.timer(_metric(action) + ".duration_ms", elapsed_ms)
+    _metrics.counter(_metric(action), labels={"status": "success"})
+    return asdict(response)
+
+
+def _handle_session_config(*, config: ServerConfig, payload: Dict[str, Any]) -> dict:
+    """
+    Handle session-config action: get/set autonomous mode preferences.
+
+    This action manages the ephemeral autonomous session state, allowing
+    agents to enable/disable autonomous mode and track task completion
+    during autonomous execution.
+
+    Parameters:
+        get: If true, just return current session config without changes
+        auto_mode: Set autonomous mode enabled (true) or disabled (false)
+
+    Returns:
+        Current session configuration including autonomous state
+    """
+    from datetime import datetime, timezone
+
+    request_id = _request_id()
+    action = "session-config"
+    start = time.perf_counter()
+
+    # Get parameters
+    get_only = payload.get("get", False)
+    auto_mode = payload.get("auto_mode")
+
+    # Get the context tracker and session
+    tracker = get_context_tracker()
+    session = tracker.get_or_create_session()
+
+    # Initialize autonomous if not present
+    if session.autonomous is None:
+        session.autonomous = AutonomousSession()
+
+    # If just getting, return current state
+    if get_only:
+        elapsed_ms = (time.perf_counter() - start) * 1000
+        response = success_response(
+            session_id=session.session_id,
+            autonomous=session.autonomous.to_dict(),
+            message="Current session configuration",
+            request_id=request_id,
+            telemetry={"duration_ms": round(elapsed_ms, 2)},
+        )
+        _metrics.counter(_metric(action), labels={"status": "success", "operation": "get"})
+        return asdict(response)
+
+    # Handle auto_mode setting
+    if auto_mode is not None:
+        if not isinstance(auto_mode, bool):
+            return _validation_error(
+                field="auto_mode",
+                action=action,
+                message="auto_mode must be a boolean (true/false)",
+                request_id=request_id,
+            )
+
+        previous_enabled = session.autonomous.enabled
+        session.autonomous.enabled = auto_mode
+
+        if auto_mode and not previous_enabled:
+            # Starting autonomous mode
+            session.autonomous.started_at = (
+                datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+            )
+            session.autonomous.tasks_completed = 0
+            session.autonomous.pause_reason = None
+        elif not auto_mode and previous_enabled:
+            # Stopping autonomous mode
+            session.autonomous.pause_reason = "user"
+
+    elapsed_ms = (time.perf_counter() - start) * 1000
+    response = success_response(
+        session_id=session.session_id,
+        autonomous=session.autonomous.to_dict(),
+        message="Autonomous mode enabled" if session.autonomous.enabled else "Autonomous mode disabled",
+        request_id=request_id,
+        telemetry={"duration_ms": round(elapsed_ms, 2)},
+    )
+    _metrics.counter(_metric(action), labels={"status": "success", "operation": "set"})
+    return asdict(response)
+
+
+_ACTION_DEFINITIONS = [
+    ActionDefinition(
+        name="prepare",
+        handler=_handle_prepare,
+        summary="Prepare next actionable task context",
+    ),
+    ActionDefinition(
+        name="prepare-batch",
+        handler=_handle_prepare_batch,
+        summary="Prepare multiple independent tasks for parallel execution",
+    ),
+    ActionDefinition(
+        name="start-batch",
+        handler=_handle_start_batch,
+        summary="Atomically start multiple tasks as in_progress",
+    ),
+    ActionDefinition(
+        name="complete-batch",
+        handler=_handle_complete_batch,
+        summary="Complete multiple tasks with partial failure support",
+    ),
+    ActionDefinition(
+        name="reset-batch",
+        handler=_handle_reset_batch,
+        summary="Reset stale or specified in_progress tasks to pending",
+    ),
+    ActionDefinition(
+        name="next", handler=_handle_next, summary="Return the next actionable task"
+    ),
+    ActionDefinition(
+        name="info", handler=_handle_info, summary="Fetch task metadata by ID"
+    ),
+    ActionDefinition(
+        name="check-deps",
+        handler=_handle_check_deps,
+        summary="Analyze task dependencies and blockers",
+    ),
+    ActionDefinition(name="start", handler=_handle_start, summary="Start a task"),
     ActionDefinition(
         name="complete", handler=_handle_complete, summary="Complete a task"
     ),
@@ -2057,6 +3630,26 @@ _ACTION_DEFINITIONS = [
     ),
     ActionDefinition(name="add", handler=_handle_add, summary="Add a task"),
     ActionDefinition(name="remove", handler=_handle_remove, summary="Remove a task"),
+    ActionDefinition(
+        name="move",
+        handler=_handle_move,
+        summary="Move task to new position or parent",
+    ),
+    ActionDefinition(
+        name="add-dependency",
+        handler=_handle_add_dependency,
+        summary="Add a dependency between two tasks",
+    ),
+    ActionDefinition(
+        name="remove-dependency",
+        handler=_handle_remove_dependency,
+        summary="Remove a dependency between two tasks",
+    ),
+    ActionDefinition(
+        name="add-requirement",
+        handler=_handle_add_requirement,
+        summary="Add a structured requirement to a task",
+    ),
     ActionDefinition(
         name="update-estimate",
         handler=_handle_update_estimate,
@@ -2067,6 +3660,16 @@ _ACTION_DEFINITIONS = [
         handler=_handle_update_metadata,
         summary="Update task metadata fields",
     ),
+    ActionDefinition(
+        name="metadata-batch",
+        handler=_handle_metadata_batch,
+        summary="Batch update metadata across multiple nodes matching filters",
+    ),
+    ActionDefinition(
+        name="fix-verification-types",
+        handler=_handle_fix_verification_types,
+        summary="Fix invalid/missing verification types across verify nodes",
+    ),
     ActionDefinition(
         name="progress",
         handler=_handle_progress,
@@ -2087,6 +3690,11 @@ _ACTION_DEFINITIONS = [
         handler=_handle_hierarchy,
         summary="Return paginated hierarchy slices",
     ),
+    ActionDefinition(
+        name="session-config",
+        handler=_handle_session_config,
+        summary="Get/set autonomous session configuration",
+    ),
 ]
 
 _TASK_ROUTER = ActionRouter(tool_name="task", actions=_ACTION_DEFINITIONS)
@@ -2140,6 +3748,7 @@ def register_unified_task_tool(mcp: FastMCP, config: ServerConfig) -> None:
         resolution: Optional[str] = None,
         title: Optional[str] = None,
         description: Optional[str] = None,
+        acceptance_criteria: Optional[List[str]] = None,
         task_type: str = "task",
         estimated_hours: Optional[float] = None,
         position: Optional[int] = None,
@@ -2155,6 +3764,18 @@ def register_unified_task_tool(mcp: FastMCP, config: ServerConfig) -> None:
         dry_run: bool = False,
         max_depth: int = 2,
         include_metadata: bool = False,
+        # metadata-batch specific parameters
+        phase_id: Optional[str] = None,
+        pattern: Optional[str] = None,
+        node_type: Optional[str] = None,
+        owners: Optional[List[str]] = None,
+        labels: Optional[Dict[str, str]] = None,
+        category: Optional[str] = None,
+        parent_filter: Optional[str] = None,
+        update_metadata: Optional[Dict[str, Any]] = None,
+        # session-config specific parameters
+        get: bool = False,
+        auto_mode: Optional[bool] = None,
     ) -> dict:
         payload = {
             "spec_id": spec_id,
@@ -2176,6 +3797,7 @@ def register_unified_task_tool(mcp: FastMCP, config: ServerConfig) -> None:
             "resolution": resolution,
             "title": title,
             "description": description,
+            "acceptance_criteria": acceptance_criteria,
             "task_type": task_type,
             "estimated_hours": estimated_hours,
             "position": position,
@@ -2191,6 +3813,18 @@ def register_unified_task_tool(mcp: FastMCP, config: ServerConfig) -> None:
             "dry_run": dry_run,
             "max_depth": max_depth,
             "include_metadata": include_metadata,
+            # metadata-batch specific
+            "phase_id": phase_id,
+            "pattern": pattern,
+            "node_type": node_type,
+            "owners": owners,
+            "labels": labels,
+            "category": category,
+            "parent_filter": parent_filter,
+            "update_metadata": update_metadata,
+            # session-config specific
+            "get": get,
+            "auto_mode": auto_mode,
         }
         return _dispatch_task_action(action=action, payload=payload, config=config)