gobby 0.2.5__py3-none-any.whl

gobby/mcp_proxy/tools/tasks/_lifecycle_validation.py

@@ -0,0 +1,301 @@
+"""Validation helpers for task lifecycle operations.
+
+Provides validation functions used by close_task to verify tasks
+can be closed (commit checks, child completion, LLM validation).
+"""
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from gobby.mcp_proxy.tools.tasks._helpers import SKIP_REASONS
+from gobby.storage.tasks import Task
+
+if TYPE_CHECKING:
+    from gobby.config.tasks import TaskValidationConfig
+    from gobby.mcp_proxy.tools.tasks._context import RegistryContext
+    from gobby.storage.tasks import LocalTaskManager
+    from gobby.tasks.validation import TaskValidator
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ValidationResult:
+    """Result of validation checks."""
+
+    can_close: bool
+    error_type: str | None = None
+    message: str | None = None
+    extra: dict[str, Any] | None = None
+
+
+def validate_commit_requirements(
+    task: Task,
+    reason: str,
+    no_commit_needed: bool,
+    override_justification: str | None,
+) -> ValidationResult:
+    """Check if task meets commit requirements for closing.
+
+    Args:
+        task: The task to validate
+        reason: Reason for closing
+        no_commit_needed: If True, allow closing without commits
+        override_justification: Justification for skipping commit check
+
+    Returns:
+        ValidationResult indicating if task can be closed
+    """
+    # Skip commit check for certain close reasons that imply no work was done
+    requires_commit_check = reason.lower() not in SKIP_REASONS
+
+    if requires_commit_check and not task.commits:
+        # No commits linked - require explicit acknowledgment
+        if no_commit_needed:
+            if not override_justification:
+                return ValidationResult(
+                    can_close=False,
+                    error_type="justification_required",
+                    message=(
+                        "When no_commit_needed=True, you must provide "
+                        "override_justification explaining why no commit was needed."
+                    ),
+                )
+            # Allowed to proceed - agent confirmed no commit needed
+        else:
+            return ValidationResult(
+                can_close=False,
+                error_type="no_commits_linked",
+                message=(
+                    "Cannot close task: no commits are linked. Either:\n"
+                    "1. Commit your changes and use link_commit() or include [task_id] in commit message\n"
+                    "2. Set no_commit_needed=True with override_justification if this task didn't require code changes"
+                ),
+            )
+
+    return ValidationResult(can_close=True)
+
+
+def validate_parent_task(
+    ctx: "RegistryContext",
+    task_id: str,
+) -> ValidationResult:
+    """Check if a parent task's children are all closed.
+
+    Args:
+        ctx: Registry context
+        task_id: The parent task ID
+
+    Returns:
+        ValidationResult indicating if parent can be closed
+    """
+    children = ctx.task_manager.list_tasks(parent_task_id=task_id, limit=1000)
+
+    if children:
+        open_children = [c for c in children if c.status != "closed"]
+        if open_children:
+            open_titles = [f"- {c.id}: {c.title}" for c in open_children[:5]]
+            remaining = len(open_children) - 5 if len(open_children) > 5 else 0
+            feedback = f"Cannot close: {len(open_children)} child tasks still open:\n"
+            feedback += "\n".join(open_titles)
+            if remaining > 0:
+                feedback += f"\n... and {remaining} more"
+            return ValidationResult(
+                can_close=False,
+                error_type="validation_failed",
+                message=feedback,
+                extra={"open_children": [c.id for c in open_children]},
+            )
+
+    return ValidationResult(can_close=True)
+
+
+def gather_validation_context(
+    task: Task,
+    changes_summary: str | None,
+    repo_path: str | None,
+    task_manager: "LocalTaskManager",
+) -> tuple[str | None, str | None]:
+    """Gather context for LLM validation.
+
+    Uses provided changes_summary or auto-fetches via smart context gathering.
+
+    Args:
+        task: The task to validate
+        changes_summary: Optional user-provided summary
+        repo_path: Path to the repository
+        task_manager: LocalTaskManager for fetching task diff
+
+    Returns:
+        Tuple of (validation_context, raw_diff)
+    """
+    from gobby.tasks.commits import get_task_diff, summarize_diff_for_validation
+
+    validation_context = changes_summary
+    raw_diff = None
+
+    if not validation_context:
+        # First try commit-based diff if task has linked commits
+        if task.commits:
+            try:
+                # Don't include uncommitted changes - they're likely unrelated to this task
+                # The linked commits ARE the work for this task
+                diff_result = get_task_diff(
+                    task_id=task.id,
+                    task_manager=task_manager,
+                    include_uncommitted=False,
+                    cwd=repo_path,
+                )
+                if diff_result.diff:
+                    raw_diff = diff_result.diff
+                    # Use smart summarization to ensure all files are visible
+                    summarized_diff = summarize_diff_for_validation(raw_diff)
+                    validation_context = (
+                        f"Commit-based diff ({len(diff_result.commits)} commits, "
+                        f"{diff_result.file_count} files):\n\n{summarized_diff}"
+                    )
+                else:
+                    logger.warning(
+                        f"get_task_diff returned empty for task {task.id} "
+                        f"with commits {task.commits}"
+                    )
+            except Exception as e:
+                logger.warning(f"get_task_diff failed for task {task.id}: {e}")
+
+        # Fall back to smart context ONLY if no linked commits
+        # (uncommitted changes are unrelated if we have specific commits linked)
+        if not validation_context and not task.commits:
+            from gobby.tasks.validation import get_validation_context_smart
+
+            # Smart context gathering: uncommitted changes + multi-commit window + file analysis
+            smart_context = get_validation_context_smart(
+                task_title=task.title,
+                validation_criteria=task.validation_criteria,
+                task_description=task.description,
+                cwd=repo_path,
+            )
+            if smart_context:
+                validation_context = f"Validation context:\n\n{smart_context}"
+
+    return validation_context, raw_diff
+
+
+async def validate_leaf_task_with_llm(
+    task: Task,
+    task_validator: "TaskValidator",
+    validation_context: str,
+    raw_diff: str | None,
+    ctx: "RegistryContext",
+    resolved_id: str,
+    validation_config: "TaskValidationConfig | None",
+) -> ValidationResult:
+    """Run LLM validation on a leaf task.
+
+    Args:
+        task: The task to validate
+        task_validator: The validator instance
+        validation_context: Context for validation
+        raw_diff: Raw diff for doc-only check
+        ctx: Registry context
+        resolved_id: Resolved task ID
+        validation_config: Validation configuration
+
+    Returns:
+        ValidationResult indicating if task can be closed
+    """
+    from gobby.tasks.commits import is_doc_only_diff
+
+    # Auto-skip LLM validation for doc-only changes
+    if raw_diff and is_doc_only_diff(raw_diff):
+        logger.info(f"Skipping LLM validation for task {task.id}: doc-only changes")
+        ctx.task_manager.update_task(
+            resolved_id,
+            validation_status="valid",
+            validation_feedback="Auto-validated: documentation-only changes",
+        )
+        return ValidationResult(can_close=True)
+
+    # Run LLM validation
+    result = await task_validator.validate_task(
+        task_id=task.id,
+        title=task.title,
+        description=task.description,
+        changes_summary=validation_context,
+        validation_criteria=task.validation_criteria,
+        category=task.category,
+    )
+
+    # Store validation result regardless of pass/fail
+    ctx.task_manager.update_task(
+        resolved_id,
+        validation_status=result.status,
+        validation_feedback=result.feedback,
+    )
+
+    if result.status != "valid":
+        # Block closing on invalid or pending (error during validation)
+        return ValidationResult(
+            can_close=False,
+            error_type="validation_failed",
+            message=result.feedback or "Validation did not pass",
+            extra={"validation_status": result.status},
+        )
+
+    # Run external validation if enabled (after internal validation passes)
+    if validation_config and validation_config.use_external_validator:
+        from gobby.tasks.external_validator import run_external_validation
+
+        external_result = await run_external_validation(
+            config=validation_config,
+            llm_service=task_validator.llm_service,
+            task={
+                "id": task.id,
+                "title": task.title,
+                "description": task.description,
+                "validation_criteria": task.validation_criteria,
+            },
+            changes_context=validation_context,
+            agent_runner=ctx.agent_runner,
+        )
+
+        if external_result.status not in ("valid", "skipped"):
+            # Block closing on external validation failure
+            return ValidationResult(
+                can_close=False,
+                error_type="external_validation_failed",
+                message=external_result.summary,
+                extra={
+                    "validation_status": external_result.status,
+                    "issues": [issue.to_dict() for issue in external_result.issues],
+                },
+            )
+
+    return ValidationResult(can_close=True)
+
+
+def determine_close_outcome(
+    task: Task,
+    skip_validation: bool,
+    no_commit_needed: bool,
+    override_justification: str | None,
+) -> tuple[bool, bool]:
+    """Determine the close outcome for a task.
+
+    Args:
+        task: The task being closed
+        skip_validation: Whether validation was skipped
+        no_commit_needed: Whether commit was not needed
+        override_justification: Justification for override
+
+    Returns:
+        Tuple of (route_to_review, store_override)
+    """
+    # Determine if override should be stored
+    store_override = skip_validation or no_commit_needed
+
+    # Route to review if task requires user review OR override was used
+    # This ensures tasks with HITL flag or skipped validation go through human review
+    route_to_review = bool(task.requires_user_review or (override_justification and store_override))
+
+    return route_to_review, store_override

gobby/mcp_proxy/tools/tasks/_resolution.py

@@ -0,0 +1,55 @@
+"""Task ID resolution for MCP tools.
+
+Provides resolve_task_id_for_mcp() which resolves various task reference
+formats (#N, N, path, UUID) to task UUIDs.
+"""
+
+from gobby.mcp_proxy.tools.tasks._helpers import _is_path_format
+from gobby.storage.tasks import LocalTaskManager, TaskNotFoundError
+from gobby.utils.project_context import get_project_context
+
+
+def resolve_task_id_for_mcp(
+    task_manager: LocalTaskManager,
+    task_id: str,
+    project_id: str | None = None,
+) -> str:
+    """Resolve a task reference to its UUID for MCP tools.
+
+    Supports multiple reference formats:
+      - #N: Project-scoped seq_num (e.g., #1, #47) - requires project_id
+      - N: Bare numeric seq_num (e.g., 1, 47) - requires project_id
+      - 1.2.3: Path cache format - requires project_id
+      - UUID: Direct UUID lookup (validated to exist)
+
+    Args:
+        task_manager: The task manager
+        task_id: Task reference in any supported format
+        project_id: Project ID for scoped lookups (#N and path formats).
+                   If not provided, will try to get from project context.
+
+    Returns:
+        The resolved task UUID
+
+    Raises:
+        TaskNotFoundError: If the reference cannot be resolved
+        ValueError: If the format is invalid
+    """
+    # Get project_id from context if not provided
+    if project_id is None:
+        ctx = get_project_context()
+        project_id = ctx.get("id") if ctx else None
+
+    # Check for #N format or path format (requires project_id)
+    if project_id and (task_id.startswith("#") or _is_path_format(task_id)):
+        return task_manager.resolve_task_reference(task_id, project_id)
+
+    # Check for bare numeric string (seq_num without #)
+    if project_id and task_id.isdigit():
+        return task_manager.resolve_task_reference(f"#{task_id}", project_id)
+
+    # UUID format: validate it exists by trying to get it
+    task = task_manager.get_task(task_id)
+    if task is None:
+        raise TaskNotFoundError(f"Task with UUID '{task_id}' not found")
+    return task_id

gobby/mcp_proxy/tools/tasks/_search.py

@@ -0,0 +1,215 @@
+"""Search operations for task management.
+
+Provides semantic search tools for tasks using TF-IDF.
+"""
+
+from typing import Any
+
+from gobby.mcp_proxy.tools.internal import InternalToolRegistry
+from gobby.mcp_proxy.tools.tasks._context import RegistryContext
+from gobby.mcp_proxy.tools.tasks._resolution import resolve_task_id_for_mcp
+from gobby.utils.project_context import get_project_context
+
+
+def create_search_registry(ctx: RegistryContext) -> InternalToolRegistry:
+    """Create a registry with task search tools.
+
+    Args:
+        ctx: Shared registry context
+
+    Returns:
+        InternalToolRegistry with search tools registered
+    """
+    registry = InternalToolRegistry(
+        name="gobby-tasks-search",
+        description="Task search operations",
+    )
+
+    def search_tasks(
+        query: str,
+        status: str | list[str] | None = None,
+        task_type: str | None = None,
+        priority: int | None = None,
+        parent_task_id: str | None = None,
+        category: str | None = None,
+        limit: int = 20,
+        min_score: float = 0.0,
+        all_projects: bool = False,
+    ) -> dict[str, Any]:
+        """Search tasks using semantic TF-IDF search.
+
+        Performs semantic search on task title, description, labels, and type.
+        Results are ranked by relevance and can be filtered by status, type, etc.
+
+        Args:
+            query: Search query text (required). Natural language query.
+            status: Filter by status (open, in_progress, review, closed).
+                Can be a single status or comma-separated list.
+            task_type: Filter by task type (task, bug, feature, epic)
+            priority: Filter by priority (1=High, 2=Medium, 3=Low)
+            parent_task_id: Filter by parent task ID (UUID, #N, or N format)
+            category: Filter by task category
+            limit: Maximum number of results (default: 20)
+            min_score: Minimum similarity score 0.0-1.0 (default: 0.0)
+            all_projects: If true, search all projects instead of current project
+
+        Returns:
+            Dict with matching tasks and their similarity scores
+        """
+        if not query or not query.strip():
+            return {"error": "Query is required", "tasks": [], "count": 0}
+
+        # Get current project context unless all_projects
+        project_id = None
+        if not all_projects:
+            project_ctx = get_project_context()
+            if project_ctx and project_ctx.get("id"):
+                project_id = project_ctx["id"]
+
+        # Handle comma-separated status string
+        status_filter: str | list[str] | None = status
+        if isinstance(status, str) and "," in status:
+            status_filter = [s.strip() for s in status.split(",")]
+
+        # Resolve parent_task_id if provided (#N, N, or UUID -> UUID)
+        resolved_parent_id = None
+        if parent_task_id:
+            try:
+                resolved_parent_id = resolve_task_id_for_mcp(
+                    ctx.task_manager, parent_task_id, project_id
+                )
+            except Exception:
+                return {
+                    "error": f"Invalid parent_task_id: {parent_task_id}",
+                    "tasks": [],
+                    "count": 0,
+                }
+
+        # Perform search
+        results = ctx.task_manager.search_tasks(
+            query=query.strip(),
+            project_id=project_id,
+            status=status_filter,
+            task_type=task_type,
+            priority=priority,
+            parent_task_id=resolved_parent_id,
+            category=category,
+            limit=limit,
+            min_score=min_score,
+        )
+
+        return {
+            "tasks": [
+                {
+                    **task.to_brief(),
+                    "score": round(score, 4),
+                }
+                for task, score in results
+            ],
+            "count": len(results),
+            "query": query.strip(),
+        }
+
+    registry.register(
+        name="search_tasks",
+        description="Search tasks using semantic TF-IDF search. Returns tasks ranked by relevance to the query.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Search query text. Natural language query to find matching tasks.",
+                },
+                "status": {
+                    "oneOf": [
+                        {"type": "string"},
+                        {"type": "array", "items": {"type": "string"}},
+                    ],
+                    "description": "Filter by status. Can be single status or comma-separated list (e.g., 'open,in_progress')",
+                    "default": None,
+                },
+                "task_type": {
+                    "type": "string",
+                    "description": "Filter by task type (task, bug, feature, epic)",
+                    "default": None,
+                },
+                "priority": {
+                    "type": "integer",
+                    "description": "Filter by priority (1=High, 2=Medium, 3=Low)",
+                    "default": None,
+                },
+                "parent_task_id": {
+                    "type": "string",
+                    "description": "Filter by parent task ID (UUID, #N, or N format)",
+                    "default": None,
+                },
+                "category": {
+                    "type": "string",
+                    "description": "Filter by task category",
+                    "default": None,
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "Maximum number of results to return",
+                    "default": 20,
+                },
+                "min_score": {
+                    "type": "number",
+                    "description": "Minimum similarity score threshold (0.0-1.0)",
+                    "default": 0.0,
+                },
+                "all_projects": {
+                    "type": "boolean",
+                    "description": "If true, search all projects instead of just the current project",
+                    "default": False,
+                },
+            },
+            "required": ["query"],
+        },
+        func=search_tasks,
+    )
+
+    def reindex_tasks(all_projects: bool = False) -> dict[str, Any]:
+        """Force rebuild of the task search index.
+
+        Use this to refresh the search index after bulk operations
+        or if search results seem stale.
+
+        Args:
+            all_projects: If true, reindex all projects instead of current project
+
+        Returns:
+            Dict with index statistics
+        """
+        # Get current project context unless all_projects
+        project_id = None
+        if not all_projects:
+            project_ctx = get_project_context()
+            if project_ctx and project_ctx.get("id"):
+                project_id = project_ctx["id"]
+
+        stats = ctx.task_manager.reindex_search(project_id)
+
+        return {
+            "success": True,
+            "message": f"Search index rebuilt with {stats.get('item_count', 0)} tasks",
+            "stats": stats,
+        }
+
+    registry.register(
+        name="reindex_tasks",
+        description="Force rebuild of the task search index. Use after bulk operations or if search seems stale.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "all_projects": {
+                    "type": "boolean",
+                    "description": "If true, reindex all projects instead of just the current project",
+                    "default": False,
+                },
+            },
+        },
+        func=reindex_tasks,
+    )
+
+    return registry

gobby/mcp_proxy/tools/tasks/_session.py

@@ -0,0 +1,125 @@
+"""Session integration tools for task management.
+
+Provides tools for linking tasks to sessions and querying task-session
+relationships.
+"""
+
+from typing import Any
+
+from gobby.mcp_proxy.tools.internal import InternalToolRegistry
+from gobby.mcp_proxy.tools.tasks._context import RegistryContext
+from gobby.mcp_proxy.tools.tasks._resolution import resolve_task_id_for_mcp
+from gobby.storage.tasks import TaskNotFoundError
+
+
+def create_session_registry(ctx: RegistryContext) -> InternalToolRegistry:
+    """Create a registry with session-task integration tools.
+
+    Args:
+        ctx: Shared registry context
+
+    Returns:
+        InternalToolRegistry with session tools registered
+    """
+    registry = InternalToolRegistry(
+        name="gobby-tasks-session",
+        description="Task-session integration tools",
+    )
+
+    def link_task_to_session(
+        task_id: str,
+        session_id: str | None = None,
+        action: str = "worked_on",
+    ) -> dict[str, Any]:
+        """Link a task to a session."""
+        if not session_id:
+            return {"error": "session_id is required"}
+
+        try:
+            resolved_id = resolve_task_id_for_mcp(ctx.task_manager, task_id)
+        except (TaskNotFoundError, ValueError) as e:
+            return {"error": str(e)}
+
+        try:
+            ctx.session_task_manager.link_task(session_id, resolved_id, action)
+            return {}
+        except ValueError as e:
+            return {"error": str(e)}
+
+    registry.register(
+        name="link_task_to_session",
+        description="Link a task to a session.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "task_id": {
+                    "type": "string",
+                    "description": "Task reference: #N (e.g., #1, #47), path (e.g., 1.2.3), or UUID",
+                },
+                "session_id": {
+                    "type": "string",
+                    "description": "Session ID (optional, defaults to linking context if available)",
+                    "default": None,
+                },
+                "action": {
+                    "type": "string",
+                    "description": "Relationship type (worked_on, discovered, mentioned, closed)",
+                    "default": "worked_on",
+                },
+            },
+            "required": ["task_id"],
+        },
+        func=link_task_to_session,
+    )
+
+    def get_session_tasks(session_id: str) -> dict[str, Any]:
+        """Get all tasks associated with a session."""
+        tasks = ctx.session_task_manager.get_session_tasks(session_id)
+        return {"session_id": session_id, "tasks": tasks}
+
+    registry.register(
+        name="get_session_tasks",
+        description="Get all tasks associated with a session.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "session_id": {"type": "string", "description": "Session ID"},
+            },
+            "required": ["session_id"],
+        },
+        func=get_session_tasks,
+    )
+
+    def get_task_sessions(task_id: str) -> dict[str, Any]:
+        """Get all sessions that touched a task."""
+        try:
+            resolved_id = resolve_task_id_for_mcp(ctx.task_manager, task_id)
+        except (TaskNotFoundError, ValueError) as e:
+            return {"error": str(e)}
+        task = ctx.task_manager.get_task(resolved_id)
+        sessions = ctx.session_task_manager.get_task_sessions(resolved_id)
+        # Handle case where task is not found (shouldn't happen after resolve, but be defensive)
+        ref = f"#{task.seq_num}" if task and task.seq_num else resolved_id[:8]
+        return {
+            "ref": ref,
+            "task_id": resolved_id,
+            "sessions": sessions,
+        }
+
+    registry.register(
+        name="get_task_sessions",
+        description="Get all sessions that touched a task.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "task_id": {
+                    "type": "string",
+                    "description": "Task reference: #N (e.g., #1, #47), path (e.g., 1.2.3), or UUID",
+                },
+            },
+            "required": ["task_id"],
+        },
+        func=get_task_sessions,
+    )
+
+    return registry