gobby 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

gobby/workflows/{task_enforcement_actions.py → enforcement/task_policy.py}

@@ -1,15 +1,15 @@
-"""
-Task enforcement actions for workflow engine.
+"""Task policy enforcement for workflow engine.
 
-Provides actions that enforce task tracking before allowing certain tools,
-and enforce task completion before allowing agent to stop.
+Provides actions that enforce task tracking and scoping requirements.
 """
 
+from __future__ import annotations
+
 import logging
-import subprocess  # nosec B404 - subprocess needed for git commands
 from typing import TYPE_CHECKING, Any
 
 from gobby.mcp_proxy.tools.task_readiness import is_descendant_of
+from gobby.workflows.git_utils import get_task_session_liveness
 
 if TYPE_CHECKING:
     from gobby.config.app import DaemonConfig
@@ -21,378 +21,13 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-def _get_dirty_files(project_path: str | None = None) -> set[str]:
-    """
-    Get the set of dirty files from git status --porcelain.
-
-    Excludes .gobby/ files from the result.
-
-    Args:
-        project_path: Path to the project directory
-
-    Returns:
-        Set of dirty file paths (relative to repo root)
-    """
-    if project_path is None:
-        logger.warning(
-            "_get_dirty_files: project_path is None, git status will use daemon's cwd "
-            "which may not be the project directory"
-        )
-
-    try:
-        result = subprocess.run(  # nosec B603 B607 - hardcoded git command
-            ["git", "status", "--porcelain"],
-            cwd=project_path,
-            capture_output=True,
-            text=True,
-            timeout=10,
-        )
-
-        if result.returncode != 0:
-            logger.warning(f"_get_dirty_files: git status failed: {result.stderr}")
-            return set()
-
-        dirty_files = set()
-        # Split by newline first, don't strip() the whole string as it removes
-        # the leading space from git status format (e.g., " M file.py")
-        for line in result.stdout.split("\n"):
-            line = line.rstrip()  # Remove trailing whitespace only
-            if not line:
-                continue
-            # Format is "XY filename" or "XY filename -> newname" for renames
-            # Skip the status prefix (first 3 chars: 2 status chars + space)
-            filepath = line[3:].split(" -> ")[0]  # Handle renames
-            # Exclude .gobby/ files
-            if not filepath.startswith(".gobby/"):
-                dirty_files.add(filepath)
-
-        return dirty_files
-
-    except subprocess.TimeoutExpired:
-        logger.warning("_get_dirty_files: git status timed out")
-        return set()
-    except FileNotFoundError:
-        logger.warning("_get_dirty_files: git not found")
-        return set()
-    except Exception as e:
-        logger.error(f"_get_dirty_files: Error running git status: {e}")
-        return set()
-
-
-def _get_task_session_liveness(
-    task_id: str,
-    session_task_manager: "SessionTaskManager | None",
-    session_manager: "LocalSessionManager | None",
-    exclude_session_id: str | None = None,
-) -> bool:
-    """
-    Check if a task is currently being worked on by an active session.
-
-    Args:
-        task_id: The task ID to check
-        session_task_manager: Manager to look up session-task links
-        session_manager: Manager to check session status
-        exclude_session_id: ID of session to exclude from check (e.g. current one)
-
-    Returns:
-        True if an active session (status='active') is linked to this task.
-    """
-    if not session_task_manager or not session_manager:
-        return False
-
-    try:
-        # Get all sessions linked to this task
-        linked_sessions = session_task_manager.get_task_sessions(task_id)
-
-        for link in linked_sessions:
-            session_id = link.get("session_id")
-            if not session_id or session_id == exclude_session_id:
-                continue
-
-            # Check if session is truly active
-            session = session_manager.get(session_id)
-            if session and session.status == "active":
-                return True
-
-        return False
-    except Exception as e:
-        logger.warning(f"_get_task_session_liveness: Error checking liveness for {task_id}: {e}")
-        return False
-
-
-async def capture_baseline_dirty_files(
-    workflow_state: "WorkflowState | None",
-    project_path: str | None = None,
-) -> dict[str, Any] | None:
-    """
-    Capture current dirty files as baseline for session-aware detection.
-
-    Called on session_start to record pre-existing dirty files. The
-    require_commit_before_stop action will compare against this baseline
-    to detect only NEW dirty files made during the session.
-
-    Args:
-        workflow_state: Workflow state to store baseline in
-        project_path: Path to the project directory for git status check
-
-    Returns:
-        Dict with captured baseline info, or None if no workflow_state
-    """
-    if not workflow_state:
-        logger.debug("capture_baseline_dirty_files: No workflow_state, skipping")
-        return None
-
-    dirty_files = _get_dirty_files(project_path)
-
-    # Store as a list in workflow state (sets aren't JSON serializable)
-    workflow_state.variables["baseline_dirty_files"] = list(dirty_files)
-
-    # Log for debugging baseline capture issues
-    files_preview = list(dirty_files)[:5]
-    logger.info(
-        f"capture_baseline_dirty_files: project_path={project_path}, "
-        f"captured {len(dirty_files)} files: {files_preview}"
-    )
-
-    return {
-        "baseline_captured": True,
-        "file_count": len(dirty_files),
-        "files": list(dirty_files),
-    }
-
-
-async def require_commit_before_stop(
-    workflow_state: "WorkflowState | None",
-    project_path: str | None = None,
-    task_manager: "LocalTaskManager | None" = None,
-) -> dict[str, Any] | None:
-    """
-    Block stop if there's an in_progress task with uncommitted changes.
-
-    This action is designed for on_stop triggers to enforce that agents
-    commit their work and close tasks before stopping.
-
-    Args:
-        workflow_state: Workflow state with variables (claimed_task_id, etc.)
-        project_path: Path to the project directory for git status check
-        task_manager: LocalTaskManager to verify task status
-
-    Returns:
-        Dict with decision="block" and reason if task has uncommitted changes,
-        or None to allow the stop.
-    """
-    if not workflow_state:
-        logger.debug("require_commit_before_stop: No workflow_state, allowing")
-        return None
-
-    claimed_task_id = workflow_state.variables.get("claimed_task_id")
-    if not claimed_task_id:
-        logger.debug("require_commit_before_stop: No claimed task, allowing")
-        return None
-
-    # Verify the task is actually still in_progress (not just cached in workflow state)
-    if task_manager:
-        task = task_manager.get_task(claimed_task_id)
-        if not task or task.status != "in_progress":
-            # Task was changed - clear the stale workflow state
-            logger.debug(
-                f"require_commit_before_stop: Task '{claimed_task_id}' is no longer "
-                f"in_progress (status={task.status if task else 'not found'}), clearing state"
-            )
-            workflow_state.variables["claimed_task_id"] = None
-            workflow_state.variables["task_claimed"] = False
-            return None
-
-    # Check for uncommitted changes using baseline-aware comparison
-    current_dirty = _get_dirty_files(project_path)
-
-    if not current_dirty:
-        logger.debug("require_commit_before_stop: No uncommitted changes, allowing")
-        return None
-
-    # Get baseline dirty files captured at session start
-    baseline_dirty = set(workflow_state.variables.get("baseline_dirty_files", []))
-
-    # Calculate NEW dirty files (not in baseline)
-    new_dirty = current_dirty - baseline_dirty
-
-    if not new_dirty:
-        logger.debug(
-            f"require_commit_before_stop: All {len(current_dirty)} dirty files were pre-existing "
-            f"(in baseline), allowing"
-        )
-        return None
-
-    logger.debug(
-        f"require_commit_before_stop: Found {len(new_dirty)} new dirty files "
-        f"(baseline had {len(baseline_dirty)}, current has {len(current_dirty)})"
-    )
-
-    # Track how many times we've blocked to prevent infinite loops
-    block_count = workflow_state.variables.get("_commit_block_count", 0)
-    if block_count >= 3:
-        logger.warning(
-            f"require_commit_before_stop: Reached max block count ({block_count}), allowing"
-        )
-        return None
-
-    workflow_state.variables["_commit_block_count"] = block_count + 1
-
-    # Block - agent needs to commit and close
-    logger.info(
-        f"require_commit_before_stop: Blocking stop - task '{claimed_task_id}' "
-        f"has {len(new_dirty)} uncommitted changes"
-    )
-
-    # Build list of new dirty files for the message (limit to 10 for readability)
-    new_dirty_list = sorted(new_dirty)[:10]
-    files_display = "\n".join(f"  - {f}" for f in new_dirty_list)
-    if len(new_dirty) > 10:
-        files_display += f"\n  ... and {len(new_dirty) - 10} more files"
-
-    return {
-        "decision": "block",
-        "reason": (
-            f"Task '{claimed_task_id}' is in_progress with {len(new_dirty)} uncommitted "
-            f"changes made during this session:\n{files_display}\n\n"
-            f"Before stopping, commit your changes and close the task:\n"
-            f"1. Commit with [{claimed_task_id}] in the message\n"
-            f'2. Close the task: close_task(task_id="{claimed_task_id}", commit_sha="...")'
-        ),
-    }
-
-
-async def require_task_review_or_close_before_stop(
-    workflow_state: "WorkflowState | None",
-    task_manager: "LocalTaskManager | None" = None,
-    project_id: str | None = None,
-    **kwargs: Any,
-) -> dict[str, Any] | None:
-    """Block stop if session has an in_progress task.
-
-    Agents must close their task (or send to review) before stopping.
-    The close_task() validation already requires a commit, so we don't
-    need to check for uncommitted changes here - that's handled by
-    require_commit_before_stop if needed.
-
-    Checks both:
-    1. claimed_task_id - task explicitly claimed via update_task(status="in_progress")
-    2. session_task - task(s) assigned via set_variable (fallback if no claimed_task_id)
-
-    Args:
-        workflow_state: Workflow state with variables (claimed_task_id, etc.)
-        task_manager: LocalTaskManager to verify task status
-        project_id: Project ID for resolving task references (#N, N formats)
-        **kwargs: Accepts additional kwargs for compatibility
-
-    Returns:
-        Dict with decision="block" and reason if task is still in_progress,
-        or None to allow the stop.
-    """
-    if not workflow_state:
-        logger.debug("require_task_review_or_close_before_stop: No workflow_state, allowing")
-        return None
-
-    # 1. Check claimed_task_id first (existing behavior)
-    claimed_task_id = workflow_state.variables.get("claimed_task_id")
-
-    # 2. If no claimed task, fall back to session_task
-    if not claimed_task_id and task_manager:
-        session_task = workflow_state.variables.get("session_task")
-        if session_task and session_task != "*":
-            # Normalize to list
-            task_ids = [session_task] if isinstance(session_task, str) else session_task
-
-            if isinstance(task_ids, list):
-                for task_id in task_ids:
-                    try:
-                        task = task_manager.get_task(task_id, project_id=project_id)
-                    except ValueError:
-                        continue
-                    if task and task.status == "in_progress":
-                        claimed_task_id = task_id
-                        logger.debug(
-                            f"require_task_review_or_close_before_stop: Found in_progress "
-                            f"session_task '{task_id}'"
-                        )
-                        break
-                    # Also check subtasks
-                    if task:
-                        subtasks = task_manager.list_tasks(parent_task_id=task.id)
-                        for subtask in subtasks:
-                            if subtask.status == "in_progress":
-                                claimed_task_id = subtask.id
-                                logger.debug(
-                                    f"require_task_review_or_close_before_stop: Found in_progress "
-                                    f"subtask '{subtask.id}' under session_task '{task_id}'"
-                                )
-                                break
-                    if claimed_task_id:
-                        break
-
-    if not claimed_task_id:
-        logger.debug("require_task_review_or_close_before_stop: No claimed task, allowing")
-        return None
-
-    if not task_manager:
-        logger.debug("require_task_review_or_close_before_stop: No task_manager, allowing")
-        return None
-
-    try:
-        task = task_manager.get_task(claimed_task_id, project_id=project_id)
-        if not task:
-            # Task not found - clear stale workflow state and allow
-            logger.debug(
-                f"require_task_review_or_close_before_stop: Task '{claimed_task_id}' not found, "
-                f"clearing state"
-            )
-            workflow_state.variables["claimed_task_id"] = None
-            workflow_state.variables["task_claimed"] = False
-            return None
-
-        if task.status != "in_progress":
-            # Task is closed or in review - allow stop
-            logger.debug(
-                f"require_task_review_or_close_before_stop: Task '{claimed_task_id}' "
-                f"status={task.status}, allowing"
-            )
-            # Clear stale workflow state
-            workflow_state.variables["claimed_task_id"] = None
-            workflow_state.variables["task_claimed"] = False
-            return None
-
-        # Task is still in_progress - block the stop
-        logger.info(
-            f"require_task_review_or_close_before_stop: Blocking stop - task "
-            f"'{claimed_task_id}' is still in_progress"
-        )
-
-        return {
-            "decision": "block",
-            "reason": (
-                f"Task '{claimed_task_id}' is still in_progress. "
-                f"Close it with close_task() before stopping, or set to review "
-                f"if user intervention is needed."
-            ),
-            "task_id": claimed_task_id,
-            "task_status": task.status,
-        }
-
-    except Exception as e:
-        logger.warning(
-            f"require_task_review_or_close_before_stop: Failed to check task status: {e}"
-        )
-        # Allow stop if we can't check - don't block on errors
-        return None
-
-
 async def require_task_complete(
-    task_manager: "LocalTaskManager | None",
+    task_manager: LocalTaskManager | None,
     session_id: str,
     task_ids: list[str] | None,
     event_data: dict[str, Any] | None = None,
     project_id: str | None = None,
-    workflow_state: "WorkflowState | None" = None,
+    workflow_state: WorkflowState | None = None,
 ) -> dict[str, Any] | None:
     """
     Block agent from stopping until task(s) (and their subtasks) are complete.
@@ -406,10 +41,10 @@ async def require_task_complete(
     - Wildcard mode handled by caller (passes ready tasks as list)
 
     Logic per task:
-    1. If task has incomplete subtasks and agent has no claimed task → suggest next subtask
-    2. If task has incomplete subtasks and agent has claimed task → remind to finish it
-    3. If all subtasks done but task not closed → remind to close the task
-    4. If task is closed → move to next task in list
+    1. If task has incomplete subtasks and agent has no claimed task -> suggest next subtask
+    2. If task has incomplete subtasks and agent has claimed task -> remind to finish it
+    3. If all subtasks done but task not closed -> remind to close the task
+    4. If task is closed -> move to next task in list
 
     Args:
         task_manager: LocalTaskManager for querying tasks
@@ -571,14 +206,14 @@ async def require_task_complete(
 
 
 async def require_active_task(
-    task_manager: "LocalTaskManager | None",
+    task_manager: LocalTaskManager | None,
     session_id: str,
-    config: "DaemonConfig | None",
+    config: DaemonConfig | None,
     event_data: dict[str, Any] | None,
     project_id: str | None = None,
-    workflow_state: "WorkflowState | None" = None,
-    session_manager: "LocalSessionManager | None" = None,
-    session_task_manager: "SessionTaskManager | None" = None,
+    workflow_state: WorkflowState | None = None,
+    session_manager: LocalSessionManager | None = None,
+    session_task_manager: SessionTaskManager | None = None,
 ) -> dict[str, Any] | None:
     """
     Check if an active task exists before allowing protected tools.
@@ -708,7 +343,7 @@ async def require_active_task(
                 )
 
                 # Check liveness of the candidate task
-                is_live = _get_task_session_liveness(
+                is_live = get_task_session_liveness(
                     task.id, session_task_manager, session_manager, exclude_session_id=session_id
                 )
 
@@ -748,10 +383,14 @@ async def require_active_task(
     if error_already_shown:
         return {
             "decision": "block",
-            "reason": "No task claimed. See previous **Task Required** error for instructions.",
+            "reason": (
+                "No task claimed. See previous **Task Required** error for instructions.\n"
+                "See skill: **claiming-tasks** for help."
+            ),
             "inject_context": (
                 f"**Task Required**: `{tool_name}` blocked. "
-                f"Create or claim a task before editing files (see previous error for details)."
+                f"Create or claim a task before editing files (see previous error for details).\n"
+                f'For detailed guidance: `get_skill(name="claiming-tasks")`'
                 f"{project_task_hint}"
             ),
         }
@@ -764,7 +403,8 @@ async def require_active_task(
             f"- Create a task: call_tool(server_name='gobby-tasks', tool_name='create_task', arguments={{...}})\n"
             f"- Claim an existing task: call_tool(server_name='gobby-tasks', tool_name='update_task', "
             f"arguments={{'task_id': '...', 'status': 'in_progress'}})"
-            f"{project_task_hint}"
+            f"{project_task_hint}\n\n"
+            f"See skill: **claiming-tasks** for detailed guidance."
         ),
         "inject_context": (
             f"**Task Required**: The `{tool_name}` tool is blocked until you claim a task for this session.\n\n"
@@ -772,14 +412,15 @@ async def require_active_task(
             f'1. **Create a new task**: `create_task(title="...", description="...")`\n'
             f'2. **Claim an existing task**: `update_task(task_id="...", status="in_progress")`\n\n'
             f"Use `list_ready_tasks()` to see available tasks."
-            f"{project_task_hint}"
+            f"{project_task_hint}\n\n"
+            f'For detailed guidance: `get_skill(name="claiming-tasks")`'
         ),
     }
 
 
 async def validate_session_task_scope(
-    task_manager: "LocalTaskManager | None",
-    workflow_state: "WorkflowState | None",
+    task_manager: LocalTaskManager | None,
+    workflow_state: WorkflowState | None,
     event_data: dict[str, Any] | None = None,
 ) -> dict[str, Any] | None:
     """

gobby/workflows/engine.py

@@ -15,7 +15,12 @@ from .audit_helpers import (
     log_transition,
 )
 from .definitions import WorkflowDefinition, WorkflowState
-from .detection_helpers import detect_mcp_call, detect_plan_mode, detect_task_claim
+from .detection_helpers import (
+    detect_mcp_call,
+    detect_plan_mode,
+    detect_plan_mode_from_context,
+    detect_task_claim,
+)
 from .evaluator import ConditionEvaluator
 from .lifecycle_evaluator import (
     evaluate_all_lifecycle_workflows as _evaluate_all_lifecycle_workflows,
@@ -375,6 +380,7 @@ class WorkflowEngine:
             evaluator=self.evaluator,
             detect_task_claim_fn=self._detect_task_claim,
             detect_plan_mode_fn=self._detect_plan_mode,
+            detect_plan_mode_from_context_fn=self._detect_plan_mode_from_context,
             check_premature_stop_fn=self._check_premature_stop,
             context_data=context_data,
         )
@@ -474,12 +480,17 @@ class WorkflowEngine:
     def _detect_task_claim(self, event: HookEvent, state: WorkflowState) -> None:
         """Detect gobby-tasks calls that claim or release a task for this session."""
         session_task_manager = getattr(self.action_executor, "session_task_manager", None)
-        detect_task_claim(event, state, session_task_manager)
+        task_manager = getattr(self.action_executor, "task_manager", None)
+        detect_task_claim(event, state, session_task_manager, task_manager)
 
     def _detect_plan_mode(self, event: HookEvent, state: WorkflowState) -> None:
         """Detect Claude Code plan mode entry/exit and set workflow variable."""
         detect_plan_mode(event, state)
 
+    def _detect_plan_mode_from_context(self, event: HookEvent, state: WorkflowState) -> None:
+        """Detect plan mode from system reminders in user prompt."""
+        detect_plan_mode_from_context(event, state)
+
     def _detect_mcp_call(self, event: HookEvent, state: WorkflowState) -> None:
         """Track MCP tool calls by server/tool for workflow conditions."""
         detect_mcp_call(event, state)

gobby/workflows/git_utils.py

@@ -4,8 +4,15 @@ Extracted from actions.py as part of strangler fig decomposition.
 These are pure utility functions with no ActionContext dependency.
 """
 
+from __future__ import annotations
+
 import logging
 import subprocess  # nosec B404 - subprocess needed for git commands
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from gobby.storage.session_tasks import SessionTaskManager
+    from gobby.storage.sessions import LocalSessionManager
 
 logger = logging.getLogger(__name__)
 
@@ -94,3 +101,102 @@ def get_file_changes() -> str:
 
     except Exception:
         return "Unable to determine file changes"
+
+
+def get_dirty_files(project_path: str | None = None) -> set[str]:
+    """
+    Get the set of dirty files from git status --porcelain.
+
+    Excludes .gobby/ files from the result.
+
+    Args:
+        project_path: Path to the project directory
+
+    Returns:
+        Set of dirty file paths (relative to repo root)
+    """
+    if project_path is None:
+        logger.warning(
+            "get_dirty_files: project_path is None, git status will use daemon's cwd "
+            "which may not be the project directory"
+        )
+
+    try:
+        result = subprocess.run(  # nosec B603 B607 - hardcoded git command
+            ["git", "status", "--porcelain"],
+            cwd=project_path,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+
+        if result.returncode != 0:
+            logger.warning(f"get_dirty_files: git status failed: {result.stderr}")
+            return set()
+
+        dirty_files = set()
+        # Split by newline first, don't strip() the whole string as it removes
+        # the leading space from git status format (e.g., " M file.py")
+        for line in result.stdout.split("\n"):
+            line = line.rstrip()  # Remove trailing whitespace only
+            if not line:
+                continue
+            # Format is "XY filename" or "XY filename -> newname" for renames
+            # Skip the status prefix (first 3 chars: 2 status chars + space)
+            filepath = line[3:].split(" -> ")[0]  # Handle renames
+            # Exclude .gobby/ files
+            if not filepath.startswith(".gobby/"):
+                dirty_files.add(filepath)
+
+        return dirty_files
+
+    except subprocess.TimeoutExpired:
+        logger.warning("get_dirty_files: git status timed out")
+        return set()
+    except FileNotFoundError:
+        logger.warning("get_dirty_files: git not found")
+        return set()
+    except Exception as e:
+        logger.error(f"get_dirty_files: Error running git status: {e}")
+        return set()
+
+
+def get_task_session_liveness(
+    task_id: str,
+    session_task_manager: SessionTaskManager | None,
+    session_manager: LocalSessionManager | None,
+    exclude_session_id: str | None = None,
+) -> bool:
+    """
+    Check if a task is currently being worked on by an active session.
+
+    Args:
+        task_id: The task ID to check
+        session_task_manager: Manager to look up session-task links
+        session_manager: Manager to check session status
+        exclude_session_id: ID of session to exclude from check (e.g. current one)
+
+    Returns:
+        True if an active session (status='active') is linked to this task.
+    """
+    if not session_task_manager or not session_manager:
+        return False
+
+    try:
+        # Get all sessions linked to this task
+        linked_sessions = session_task_manager.get_task_sessions(task_id)
+
+        for link in linked_sessions:
+            session_id = link.get("session_id")
+            if not session_id or session_id == exclude_session_id:
+                continue
+
+            # Check if session is truly active
+            session = session_manager.get(session_id)
+            if session and session.status == "active":
+                return True
+
+        return False
+    except Exception as e:
+        logger.warning(f"get_task_session_liveness: Error checking liveness for {task_id}: {e}")
+        return False