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:

Individual Task File:
```
giipdb/dispatch/TASK_*.md
```
(Source of Truth)

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

Task Status Transition Guide

1. Overview

2. Transition Flow

3. Technical Mechanics

3.1 Status Detection (
`check_status.ps1`
)

3.2 Status Update (
`launch_subsession.ps1`
)

3.3 Script Differences

4. Recording and Synchronization Points

5. Troubleshooting

Task Status Transition Guide

1. Overview

2. Transition Flow

3. Technical Mechanics

3.1 Status Detection (check_status.ps1)

3.2 Status Update (launch_subsession.ps1)

3.3 Script Differences

4. Recording and Synchronization Points

5. Troubleshooting

3.1 Status Detection (
`check_status.ps1`
)

3.2 Status Update (
`launch_subsession.ps1`
)