task_runnerpy Investigation State Machine

task_runner.py: Investigation State Machine

The task_runner.py script serves as the primary orchestrator for the Claude Sleuth investigation pipeline. It enforces a linear 56-task sequence across six distinct phases, managing state persistence, dependency injection, and phase-transition gates.

Purpose and Scope

The Task Runner is designed to provide a "hard gate" for investigative rigor. It ensures that an analyst cannot proceed to high-level reasoning (Phase 5) or reporting (Phase 6) without first completing the foundational steps of strategic planning, collection, and entity resolution. It acts as a bridge between the high-level intelligence cycle and the low-level execution of Python scripts and Markdown templates.

State Management: .sleuth-progress.json

Investigation progress is persisted in a local JSON file named .sleuth-progress.json. This file tracks the current task ID, completed tasks, and the overall state of the investigation.

State Structure

The state file maintains the following schema:

• current_task: The ID of the active task (e.g., "t1.1").
• completed_tasks: A list of all task IDs that have been finalized via the done command.
• investigation_id: A unique identifier used for CSDb (Cloudflare D1) synchronization.

Data Flow: State Persistence

The diagram below illustrates how task_runner.py interacts with the state file and the configuration metadata.

Task Runner State Flow

graph TD
    subgraph "Filesystem"
        StateFile[".sleuth-progress.json"]
        Config["config.py"]
    end

    subgraph "task_runner.py"
        LoadState["load_progress()"]
        SaveState["save_progress()"]
        CmdNext["do_next()"]
        CmdDone["do_done()"]
    end

    StateFile --> LoadState
    Config --> CmdNext
    CmdNext --> SaveState
    CmdDone --> SaveState
    SaveState --> StateFile

Loading

Command Reference

The task_runner.py provides several CLI commands to navigate the investigation.

Command	Function	Implementation
next	Displays the current task requirements, scripts, and templates.	do_next()
done	Marks the current task as complete and advances the state.	do_done()
status	Shows a progress overview across all 6 phases.	do_status()
jump <id>	Moves the state to a specific task ID (e.g., t6.2).	do_jump()
peek <id>	Views details of a future task without changing state.	do_peek()
notebook	Opens or displays the investigation-notebook.md.	do_notebook()
reset	Wipes the .sleuth-progress.json file to start over.	do_reset()

Phase-Transition Gate Logic

The pipeline is divided into 6 phases. The task_runner.py enforces transitions between these phases by checking the current task ID against the PHASES metadata.

When a user executes done on the final task of a phase (e.g., t2.5 for Phase 1), the runner triggers a phase transition check. It validates that all required steps within that phase's folder (defined in PHASE_FOLDERS) have been addressed.

Automatic Dependency Installation

One of the most critical features of next is the automatic invocation of setup.py.

1. When a task is loaded, task_runner.py identifies the required scripts from STEP_SCRIPTS.
2. It looks up the required module groups for those scripts in SCRIPT_MODULES.
3. It calls scripts/setup.py --modules <names> to ensure the environment is ready before the analyst begins work.

Code Entity Mapping

The following diagram bridges the natural language concepts of the investigation to the specific Python entities in task_runner.py and config.py.

Investigation Concept to Code Mapping

classDiagram
    class InvestigationState {
        +current_task: string
        +completed_tasks: list
        +investigation_id: uuid
    }

    class TaskRunner {
        +do_next()
        +do_done()
        +do_status()
        +check_dependencies()
    }

    class ConfigMetadata {
        +PHASES: dict
        +STEP_TEMPLATES: dict
        +STEP_SCRIPTS: dict
        +STEP_MCP_TOOLS: dict
    }

    TaskRunner --> InvestigationState : updates
    TaskRunner --> ConfigMetadata : reads
    TaskRunner --> SetupScript : calls via subprocess

Loading

Task Execution Lifecycle

When an analyst interacts with a task, the system follows a strict lifecycle to ensure all resources (templates, scripts, and tools) are available.

Task Lifecycle Diagram

sequenceDiagram
    participant Analyst
    participant TR as task_runner.py
    participant CFG as config.py
    participant SU as setup.py
    participant TB as template_builder.py

    Analyst->>TR: next
    TR->>CFG: Get STEP_SCRIPTS & STEP_TEMPLATES
    TR->>SU: Check & Install Modules (SCRIPT_MODULES)
    TR->>TB: Assemble Workspace (STEP_TEMPLATES)
    TR-->>Analyst: Display Task Requirements & MCP Tools
    Analyst->>TR: done
    TR->>TR: Update .sleuth-progress.json
    TR-->>Analyst: Advance to Next Task

Loading

---