태스크 상태 전이 가이드 (Task Status Transition Guide)

이 문서는 GIIP 시스템에서 AI 에이전트가 수행하는 태스크의 각 상태가 어떤 의미를 가지며, 어떤 과정을 거쳐 변화하고 어디에 기록되는지 설명합니다.

1. 개요

태스크 상태 관리는 분산된 AI 에이전트들이 협업하기 위한 핵심 메커니즘입니다. 모든 상태 변화는 데이터베이스가 아닌 파일 기반으로 이루어지며, 특정 파워쉘 스크립트들이 이 파일들을 읽고 수정함으로써 상태가 전이됩니다.

2. 상태 전이 흐름 (Transition Flow)

stateDiagram-v2
    [*] --> Pending : [발생] Orchestrator가 파일 생성
    Pending --> In Progress : [시작] launch_subsession.ps1 실행
    In Progress --> Completed : [완료] 에이전트 작업 및 검증 완료
    Completed --> [*] : [종료] MASTER_ISSUE_LIST.md 반영

상태	의미	전이 조건
Pending	대기 중. 작업이 할당되었으나 아직 시작되지 않음	Orchestrator가 giipdb/dispatch/에 파일을 생성함
In Progress	진행 중. 에이전트가 해당 태스크를 점유하여 작업 중	launch_subsession.ps1 또는 launch_role.ps1에 의해 상태가 치환됨
Completed	완료. 작업이 끝났고 에이전트가 스스로 검증을 마침	에이전트가 직접 파일의 Status를 수정함
Archived	보관됨. 완료된 태스크가 마스터 리스트에 반영된 후 정리됨	관리 도구에 의해 파일이 이동되거나 태그됨

3. 기술적 작동 방식 (Technical Mechanics)

3.1 상태 인식 (check_status.ps1)

• 탐색: giipdb/dispatch/ 폴더 내의 TASK_*.md 파일을 스캔합니다.
• 파싱: 파일 상단의 **Status**: 패턴을 정규표현식으로 찾아 현재 상태를 추출합니다.

3.2 상태 업데이트 (launch_subsession.ps1)

• 자동화: Pending 상태의 태스크를 발견하면 해당 파일의 내용을 읽어 **Status:** In Progress로 강제 치환(-replace)합니다.
• 주의: 이 과정은 파일의 물리적 수정을 수반하므로, 인코딩 오류나 정규표현식 매칭 실패 시 파일 내용이 손상될 수 있습니다.

3.3 스크립트별 차이점

• launch_subsession.ps1: 백그라운드 에이전트를 즉시 실행하며 파일을 직접 수정합니다.
• launch_role.ps1: 사용자와의 상호작용을 위해 파일을 수정하고 클립보드에 프롬프트를 생성합니다.

4. 기록 및 동기화 지점

작업 상태가 변할 때 에이전트는 다음 두 곳에 기록을 남겨야 합니다:

1. 개별 태스크 파일: giipdb/dispatch/TASK_*.md (Source of Truth)
2. 마스터 리스트: giipdb/docs/00_Master/MASTER_ISSUE_LIST.md (관제 대시보드)

5. 문제 해결 (Troubleshooting)

• 상태가 변하지 않음: 파일 상단의 **Status:** 포맷이 정확한지 확인하십시오. (오타나 공백 주의)
• 내용 유실: 파일 인코딩이 UTF-8 BOM이 아닌 경우 스크립트 처리 중 내용이 깨질 수 있습니다. 반드시 인코딩을 확인하십시오.

---

최종 수정일: 2026-03-20