Task Status Transition Guide

This document explains what each task status means in the GIIP system, how they transition, and where they are recorded.

1. Overview

Task status management is a key mechanism for collaboration among distributed AI agents. All status changes are file-based (not database-based), and transitions occur as specific PowerShell scripts read and modify these files.

2. Transition Flow

stateDiagram-v2
    [*] --> Pending : [Occurs] Orchestrator creates file
    Pending --> In Progress : [Start] launch_subsession.ps1 runs
    In Progress --> Completed : [Complete] Agent work and verification done
    Completed --> [*] : [Termination] Reflect on MASTER_ISSUE_LIST.md

Status	Meaning	Transition Condition
Pending	Waiting. Task is assigned but not yet started.	Orchestrator creates a file in giipdb/dispatch/.
In Progress	Active. An agent has occupied the task and is working on it.	Status is replaced by launch_subsession.ps1 or launch_role.ps1.
Completed	Finished. Work is done, and the agent has performed self-verification.	The agent explicitly modifies the Status in the file.
Archived	Archived. Completed tasks are cleaned up after being reflected in the master list.	Files are moved or tagged by management tools.

3. Technical Mechanics

3.1 Status Detection (check_status.ps1)

• Search: Scans TASK_*.md files in the giipdb/dispatch/ folder.
• Parsing: Extracts the current status using a regular expression for the **Status**: pattern at the top of the file.

3.2 Status Update (launch_subsession.ps1)

• Automation: When a Pending task is found, it reads the file and forcibly replaces the status with **Status:** In Progress using -replace.
• Caution: Since this involves physical modification of the file, file content may be corrupted in case of encoding errors or regex matching failures.

3.3 Script Differences

• launch_subsession.ps1: Executes background agents immediately and modifies files directly.
• launch_role.ps1: Modifies files and generates a prompt in the clipboard for user interaction.

4. Recording and Synchronization Points

When a task status changes, the agent must leave traces in two places:

1. Individual Task File: giipdb/dispatch/TASK_*.md (Source of Truth)
2. Master Issue List: giipdb/docs/00_Master/MASTER_ISSUE_LIST.md (Control Dashboard)

5. Troubleshooting

• Status Not Changing: Ensure the **Status:** format at the top of the file is exact (check for typos or spaces).
• Data Loss: If the file encoding is not UTF-8 BOM, the content may get corrupted during script processing. Always verify the encoding.

---

Last Updated: March 20, 2026