gobby 0.2.5__py3-none-any.whl

gobby/storage/tasks/_models.py

@@ -0,0 +1,300 @@
+"""Task models, exceptions, and constants.
+
+This module contains:
+- Task dataclass with serialization methods
+- Task-related exceptions
+- Priority and category constants
+- Validation and normalization helpers
+"""
+
+import json
+import sqlite3
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+# Priority name to numeric value mapping
+PRIORITY_MAP = {"backlog": 4, "low": 3, "medium": 2, "high": 1, "critical": 0}
+
+# Valid task categories (enum-like constraint)
+VALID_CATEGORIES: frozenset[str] = frozenset(
+    {
+        "code",  # Implementation tasks
+        "config",  # Configuration file changes
+        "docs",  # Documentation tasks
+        "test",  # Test infrastructure tasks (fixtures, helpers)
+        "refactor",  # Refactoring tasks (including updating existing tests)
+        "research",  # Investigation/exploration tasks
+        "planning",  # Design/architecture tasks
+        "manual",  # Manual functional testing (observe output)
+    }
+)
+
+# Sentinel for unset optional parameters
+UNSET: Any = object()
+
+
+def validate_category(category: str | None) -> str | None:
+    """Validate and normalize a category value.
+
+    Args:
+        category: Category string to validate (case-insensitive)
+
+    Returns:
+        Normalized lowercase category if valid, None otherwise
+    """
+    if category is None:
+        return None
+    normalized = category.lower().strip()
+    return normalized if normalized in VALID_CATEGORIES else None
+
+
+def normalize_priority(priority: int | str | None) -> int:
+    """Convert priority to numeric value for sorting."""
+    if priority is None:
+        return 999
+    if isinstance(priority, str):
+        # Check if it's a named priority
+        if priority.lower() in PRIORITY_MAP:
+            return PRIORITY_MAP[priority.lower()]
+        # Try to parse as int
+        try:
+            return int(priority)
+        except ValueError:
+            return 999
+    return int(priority)
+
+
+class TaskIDCollisionError(Exception):
+    """Raised when a unique task ID cannot be generated."""
+
+    pass
+
+
+class TaskNotFoundError(Exception):
+    """Raised when a task reference cannot be resolved to an existing task."""
+
+    pass
+
+
+@dataclass
+class Task:
+    id: str
+    project_id: str
+    title: str
+    status: Literal[
+        "open", "in_progress", "review", "closed", "failed", "escalated", "needs_decomposition"
+    ]
+    priority: int
+    task_type: str  # bug, feature, task, epic, chore
+    created_at: str
+    updated_at: str
+    # Optional fields
+    description: str | None = None
+    parent_task_id: str | None = None
+    created_in_session_id: str | None = None
+    closed_in_session_id: str | None = None
+    closed_commit_sha: str | None = None
+    closed_at: str | None = None
+    assignee: str | None = None
+    labels: list[str] | None = None
+    closed_reason: str | None = None
+    validation_status: Literal["pending", "valid", "invalid"] | None = None
+    validation_feedback: str | None = None
+    category: str | None = None
+    complexity_score: int | None = None
+    estimated_subtasks: int | None = None
+    expansion_context: str | None = None
+    validation_criteria: str | None = None
+    use_external_validator: bool = False
+    validation_fail_count: int = 0
+    validation_override_reason: str | None = None  # Why agent bypassed validation
+    # Workflow integration fields
+    workflow_name: str | None = None
+    verification: str | None = None
+    sequence_order: int | None = None
+    # Commit linking
+    commits: list[str] | None = None
+    # Escalation fields
+    escalated_at: str | None = None
+    escalation_reason: str | None = None
+    # GitHub integration fields
+    github_issue_number: int | None = None
+    github_pr_number: int | None = None
+    github_repo: str | None = None
+    # Linear integration fields
+    linear_issue_id: str | None = None
+    linear_team_id: str | None = None
+    # Human-friendly ID fields (task renumbering)
+    seq_num: int | None = None
+    path_cache: str | None = None
+    # Agent configuration
+    agent_name: str | None = None  # Subagent config file to use for this task
+    # Spec traceability
+    reference_doc: str | None = None  # Path to source specification document
+    # Processing flags for idempotent operations
+    is_expanded: bool = False  # Subtasks have been created
+    is_tdd_applied: bool = False  # TDD pairs have been generated
+    # Review status fields (HITL support)
+    requires_user_review: bool = False  # Task requires user sign-off before closing
+    accepted_by_user: bool = False  # Set True when user moves review → closed
+    # Dependency fields (populated on demand, not stored in tasks table)
+    blocked_by: set[str] = field(default_factory=set)
+
+    @classmethod
+    def from_row(cls, row: sqlite3.Row) -> "Task":
+        """Convert database row to Task object."""
+        labels_json = row["labels"]
+        labels = json.loads(labels_json) if labels_json else []
+
+        # Handle optional columns that might not exist yet if migration pending
+        keys = row.keys()
+
+        return cls(
+            id=row["id"],
+            project_id=row["project_id"],
+            title=row["title"],
+            status=row["status"],
+            priority=normalize_priority(row["priority"]),
+            task_type=row["task_type"],
+            created_at=row["created_at"],
+            updated_at=row["updated_at"],
+            description=row["description"],
+            parent_task_id=row["parent_task_id"],
+            created_in_session_id=(
+                row["created_in_session_id"]
+                if "created_in_session_id" in keys
+                else (
+                    row["discovered_in_session_id"] if "discovered_in_session_id" in keys else None
+                )
+            ),
+            closed_in_session_id=(
+                row["closed_in_session_id"] if "closed_in_session_id" in keys else None
+            ),
+            closed_commit_sha=row["closed_commit_sha"] if "closed_commit_sha" in keys else None,
+            closed_at=row["closed_at"] if "closed_at" in keys else None,
+            assignee=row["assignee"],
+            labels=labels,
+            closed_reason=row["closed_reason"],
+            validation_status=row["validation_status"] if "validation_status" in keys else None,
+            validation_feedback=(
+                row["validation_feedback"] if "validation_feedback" in keys else None
+            ),
+            category=row["category"] if "category" in keys else None,
+            complexity_score=row["complexity_score"] if "complexity_score" in keys else None,
+            estimated_subtasks=row["estimated_subtasks"] if "estimated_subtasks" in keys else None,
+            expansion_context=row["expansion_context"] if "expansion_context" in keys else None,
+            validation_criteria=(
+                row["validation_criteria"] if "validation_criteria" in keys else None
+            ),
+            use_external_validator=(
+                bool(row["use_external_validator"]) if "use_external_validator" in keys else False
+            ),
+            validation_fail_count=(
+                row["validation_fail_count"] if "validation_fail_count" in keys else 0
+            ),
+            validation_override_reason=(
+                row["validation_override_reason"] if "validation_override_reason" in keys else None
+            ),
+            workflow_name=row["workflow_name"] if "workflow_name" in keys else None,
+            verification=row["verification"] if "verification" in keys else None,
+            sequence_order=row["sequence_order"] if "sequence_order" in keys else None,
+            commits=json.loads(row["commits"]) if "commits" in keys and row["commits"] else None,
+            escalated_at=row["escalated_at"] if "escalated_at" in keys else None,
+            escalation_reason=row["escalation_reason"] if "escalation_reason" in keys else None,
+            github_issue_number=(
+                row["github_issue_number"] if "github_issue_number" in keys else None
+            ),
+            github_pr_number=row["github_pr_number"] if "github_pr_number" in keys else None,
+            github_repo=row["github_repo"] if "github_repo" in keys else None,
+            linear_issue_id=row["linear_issue_id"] if "linear_issue_id" in keys else None,
+            linear_team_id=row["linear_team_id"] if "linear_team_id" in keys else None,
+            seq_num=row["seq_num"] if "seq_num" in keys else None,
+            path_cache=row["path_cache"] if "path_cache" in keys else None,
+            agent_name=row["agent_name"] if "agent_name" in keys else None,
+            reference_doc=row["reference_doc"] if "reference_doc" in keys else None,
+            is_expanded=bool(row["is_expanded"]) if "is_expanded" in keys else False,
+            is_tdd_applied=bool(row["is_tdd_applied"]) if "is_tdd_applied" in keys else False,
+            requires_user_review=(
+                bool(row["requires_user_review"]) if "requires_user_review" in keys else False
+            ),
+            accepted_by_user=(
+                bool(row["accepted_by_user"]) if "accepted_by_user" in keys else False
+            ),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert Task to dictionary."""
+        return {
+            "ref": f"#{self.seq_num}" if self.seq_num else self.id[:8],
+            "project_id": self.project_id,
+            "title": self.title,
+            "status": self.status,
+            "priority": self.priority,
+            "type": self.task_type,  # Use 'type' for API compatibility
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "description": self.description,
+            "parent_task_id": self.parent_task_id,
+            "created_in_session_id": self.created_in_session_id,
+            "closed_in_session_id": self.closed_in_session_id,
+            "closed_commit_sha": self.closed_commit_sha,
+            "closed_at": self.closed_at,
+            "assignee": self.assignee,
+            "labels": self.labels,
+            "closed_reason": self.closed_reason,
+            "validation_status": self.validation_status,
+            "validation_feedback": self.validation_feedback,
+            "category": self.category,
+            "complexity_score": self.complexity_score,
+            "estimated_subtasks": self.estimated_subtasks,
+            "expansion_context": self.expansion_context,
+            "validation_criteria": self.validation_criteria,
+            "use_external_validator": self.use_external_validator,
+            "validation_fail_count": self.validation_fail_count,
+            "validation_override_reason": self.validation_override_reason,
+            "workflow_name": self.workflow_name,
+            "verification": self.verification,
+            "sequence_order": self.sequence_order,
+            "commits": self.commits,
+            "escalated_at": self.escalated_at,
+            "escalation_reason": self.escalation_reason,
+            "github_issue_number": self.github_issue_number,
+            "github_pr_number": self.github_pr_number,
+            "github_repo": self.github_repo,
+            "linear_issue_id": self.linear_issue_id,
+            "linear_team_id": self.linear_team_id,
+            "seq_num": self.seq_num,
+            "path_cache": self.path_cache,
+            "agent_name": self.agent_name,
+            "reference_doc": self.reference_doc,
+            "is_expanded": self.is_expanded,
+            "is_tdd_applied": self.is_tdd_applied,
+            "requires_user_review": self.requires_user_review,
+            "accepted_by_user": self.accepted_by_user,
+            "id": self.id,  # UUID at end for backwards compat
+        }
+
+    def to_brief(self) -> dict[str, Any]:
+        """Convert Task to brief discovery format for list operations.
+
+        Returns only essential fields needed for task discovery.
+        Use get_task() with to_dict() for full task details.
+
+        This follows the progressive disclosure pattern used for MCP tools:
+        - list_tasks() returns brief format (8 fields)
+        - get_task() returns full format (33 fields)
+        """
+        return {
+            "ref": f"#{self.seq_num}" if self.seq_num else self.id[:8],
+            "title": self.title,
+            "status": self.status,
+            "priority": self.priority,
+            "type": self.task_type,
+            "parent_task_id": self.parent_task_id,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "seq_num": self.seq_num,
+            "path_cache": self.path_cache,
+            "requires_user_review": self.requires_user_review,
+            "id": self.id,  # UUID at end for backwards compat
+        }

gobby/storage/tasks/_ordering.py

@@ -0,0 +1,119 @@
+"""Hierarchical task ordering utilities.
+
+This module provides functions for ordering tasks hierarchically,
+with parents appearing before their children and siblings sorted
+topologically by dependencies.
+"""
+
+from gobby.storage.tasks._models import Task, normalize_priority
+
+
+def order_tasks_hierarchically(tasks: list[Task]) -> list[Task]:
+    """
+    Reorder tasks so parents appear before their children.
+
+    The ordering is: parent -> children (recursively), then next parent -> children, etc.
+    Root tasks (no parent) are sorted by priority ASC, then created_at ASC.
+    Children are sorted by priority ASC, then created_at ASC within their parent.
+
+    Returns a new list with tasks ordered hierarchically.
+    """
+    if not tasks:
+        return []
+
+    # Build lookup structures
+    task_by_id: dict[str, Task] = {t.id: t for t in tasks}
+    children_by_parent: dict[str | None, list[Task]] = {}
+
+    for task in tasks:
+        parent_id = task.parent_task_id
+        # Only group under parent if parent is in the result set
+        if parent_id and parent_id not in task_by_id:
+            parent_id = None
+        if parent_id not in children_by_parent:
+            children_by_parent[parent_id] = []
+        children_by_parent[parent_id].append(task)
+
+    def sort_siblings(siblings: list[Task]) -> list[Task]:
+        """Sort siblings topologically with priority tie-breaking."""
+        if not siblings:
+            return []
+
+        # 1. Build local dependency graph for these siblings
+        sibling_ids = {t.id for t in siblings}
+        graph: dict[str, list[str]] = {t.id: [] for t in siblings}
+        in_degree: dict[str, int] = {t.id: 0 for t in siblings}
+
+        for task in siblings:
+            # Check who blocks this task (Local dependencies only)
+            # task.blocked_by contains IDs of tasks that block 'task'
+            # If A blocks B, we want A -> B order.
+            # So graph edge is A -> B.
+            # task.blocked_by = {A} means B depends on A.
+
+            for blocker_id in task.blocked_by:
+                if blocker_id in sibling_ids:
+                    graph[blocker_id].append(task.id)
+                    in_degree[task.id] += 1
+
+        # 2. Initialize queue with tasks having 0 in-degree (no local blockers)
+        # We want to process high priority tasks first among available ones.
+        # Priority 0 is highest, so valid sort key is (priority, created_at).
+        # We sort the initial list to ensure deterministic order for stable sort
+        queue = [t for t in siblings if in_degree[t.id] == 0]
+        # Sort queue by priority/created_at so we pop high priority first
+        queue.sort(key=lambda t: (normalize_priority(t.priority), t.created_at))
+
+        sorted_siblings: list[Task] = []
+
+        while queue:
+            # Pop the first (highest priority available)
+            current = queue.pop(0)
+            sorted_siblings.append(current)
+
+            # Decrease in-degree of neighbors
+            neighbors = graph[current.id]
+            # Neighbors might become available. Collect them.
+            newly_available = []
+            for neighbor_id in neighbors:
+                in_degree[neighbor_id] -= 1
+                if in_degree[neighbor_id] == 0:
+                    newly_available.append(task_by_id[neighbor_id])
+
+            # Sort newly available nodes by priority and add to queue
+            # We need to re-sort queue every time or insert in order.
+            # Since N is small (siblings usually < 50), simple re-sort of queue is fine.
+            newly_available.sort(key=lambda t: (normalize_priority(t.priority), t.created_at))
+
+            # Add newly available to queue. We want to maintain global order in queue
+            # based on priority.
+            # Merging two sorted lists is O(N).
+            queue.extend(newly_available)
+            queue.sort(key=lambda t: (normalize_priority(t.priority), t.created_at))
+
+        # Check for cycles (remaining nodes with >0 in-degree)
+        if len(sorted_siblings) < len(siblings):
+            # Cycle detected. Append remaining nodes sorted by priority.
+            remaining = [t for t in siblings if t not in sorted_siblings]
+            remaining.sort(key=lambda t: (normalize_priority(t.priority), t.created_at))
+            sorted_siblings.extend(remaining)
+
+        return sorted_siblings
+
+    # Sort children within each parent group
+    for parent_id, children in children_by_parent.items():
+        children_by_parent[parent_id] = sort_siblings(children)
+
+    # Build result with DFS traversal
+    result: list[Task] = []
+
+    def add_with_children(task: Task) -> None:
+        result.append(task)
+        for child in children_by_parent.get(task.id, []):
+            add_with_children(child)
+
+    # Start with root tasks (no parent or parent not in result set)
+    for root_task in children_by_parent.get(None, []):
+        add_with_children(root_task)
+
+    return result

gobby/storage/tasks/_path_cache.py

@@ -0,0 +1,110 @@
+"""Path cache computation and management utilities.
+
+This module provides functions for computing and updating task path caches,
+which represent the hierarchical position of a task as a dotted seq_num path.
+"""
+
+import logging
+from datetime import UTC, datetime
+
+from gobby.storage.database import DatabaseProtocol
+
+logger = logging.getLogger(__name__)
+
+
+def compute_path_cache(db: DatabaseProtocol, task_id: str) -> str | None:
+    """Compute the hierarchical path for a task.
+
+    Traverses up the parent chain to build a dotted path from seq_nums.
+    Format: 'ancestor_seq.parent_seq.task_seq' (e.g., '1.3.47')
+
+    Args:
+        db: Database protocol instance
+        task_id: The task ID to compute path for
+
+    Returns:
+        Dotted path string (e.g., '1.3.47'), or None if task not found
+        or any task in the chain is missing a seq_num.
+    """
+    # Build path by walking up parent chain
+    path_parts: list[str] = []
+    current_id: str | None = task_id
+
+    # Safety limit to prevent infinite loops (max 100 levels deep)
+    max_depth = 100
+    depth = 0
+
+    while current_id and depth < max_depth:
+        row = db.fetchone(
+            "SELECT seq_num, parent_task_id FROM tasks WHERE id = ?",
+            (current_id,),
+        )
+        if not row:
+            # Task not found
+            return None
+
+        seq_num = row["seq_num"]
+        if seq_num is None:
+            # seq_num not yet assigned
+            return None
+
+        path_parts.append(str(seq_num))
+        current_id = row["parent_task_id"]
+        depth += 1
+
+    if depth >= max_depth:
+        logger.warning(f"Task {task_id} exceeded max depth ({max_depth}) when computing path")
+        return None
+
+    # Reverse to get root-to-leaf order
+    path_parts.reverse()
+    return ".".join(path_parts)
+
+
+def update_path_cache(db: DatabaseProtocol, task_id: str) -> str | None:
+    """Compute and store the path_cache for a task.
+
+    Args:
+        db: Database protocol instance
+        task_id: The task ID to update
+
+    Returns:
+        The computed path, or None if computation failed
+    """
+    path = compute_path_cache(db, task_id)
+    if path is not None:
+        now = datetime.now(UTC).isoformat()
+        db.execute(
+            "UPDATE tasks SET path_cache = ?, updated_at = ? WHERE id = ?",
+            (path, now, task_id),
+        )
+    return path
+
+
+def update_descendant_paths(db: DatabaseProtocol, task_id: str) -> int:
+    """Update path_cache for a task and all its descendants.
+
+    Use this after reparenting a task to cascade path updates.
+
+    Args:
+        db: Database protocol instance
+        task_id: The root task ID to start updating from
+
+    Returns:
+        Number of tasks updated
+    """
+    updated_count = 0
+
+    # Update the task itself
+    if update_path_cache(db, task_id):
+        updated_count += 1
+
+    # Find and update all descendants (recursive)
+    children = db.fetchall(
+        "SELECT id FROM tasks WHERE parent_task_id = ?",
+        (task_id,),
+    )
+    for child in children:
+        updated_count += update_descendant_paths(db, child["id"])
+
+    return updated_count