# 4-State 완료 코드 시스템 설계 문서

**작성일**: 2026-03-23
**작성자**: 루 (백엔드 개발자, dev2-team)
**Phase**: B-3 (설계 문서 작성)
**상태**: 초안 (설계 전용, 코드 미수정)

---

## 1. 개요

### 배경

기존 완료 코드 시스템은 단순 이진(binary) 구조였다. 팀원 에이전트가 작업을 마치면 `.done` 파일을 생성하고, done-watcher.py가 이를 감지하여 자동 dispatch 또는 idle 전환을 수행하는 구조다.

그러나 이 구조에는 다음과 같은 한계가 있었다:

- **정상 완료**와 **우려사항 있는 완료**를 구분할 방법이 없음
- **정보 부족**으로 작업을 중단해야 하는 경우와 **외부 의존성 장애**로 인한 중단을 구분할 수 없음
- 팀장(아누)이 모든 완료 이벤트를 동일하게 처리하여 미묘한 상황 차이를 놓치게 됨

### 도입 목적

**Superpowers v5.0.2 격리 원칙**의 도입으로, 각 에이전트의 작업 결과를 더욱 세밀하게 추적하고 팀장이 적절한 후속 조치를 취할 수 있도록 4-State 완료 코드 시스템을 설계한다.

이 시스템은 다음 목표를 달성한다:

1. **투명성 향상**: 팀원이 작업 결과의 성격을 명확히 보고
2. **팀장 판단 지원**: 자동 dispatch 대 수동 검토 분기 지점 명확화
3. **에스컬레이션 체계화**: 정보 부족 및 외부 장애 상황의 일관된 처리
4. **하위 호환성**: 기존 도구 체인 무중단 전환

---

## 2. 4가지 상태 코드 정의

### 2.1 DONE - 정상 완료

**정의**: 작업이 완전히 완료되었으며, 팀장이 알아야 할 이슈가 없는 상태.

**사용 조건**:
- 4개 검증 게이트(Syntax, Logic, Integration, QC) 모두 통과
- 보고 내용과 실제 구현 내용이 일치
- 사이드 이펙트 없음

**팀장(아누) 처리 방법**:
- 체인의 다음 Phase 자동 dispatch
- 수동 개입 불필요

**예시 상황**:
- API 엔드포인트 구현 및 테스트 통과
- 버그 수정 완료 및 재현 불가 확인
- 리팩토링 완료 및 동작 동일성 검증

---

### 2.2 DONE_WITH_CONCERNS - 우려사항 있는 완료

**정의**: 기술적으로 작업은 완료되었으나, 팀장이 인지해야 할 우려사항이 존재하는 상태.

**사용 조건**:
- 기능 요구사항은 충족되었으나 비기능적 우려사항 발견
- 구현 중 스펙 모호성으로 임의 판단한 부분 존재
- 미래에 변경 또는 추가 작업이 필요한 부채 발생

**팀장(아누) 처리 방법**:
- `concerns` 필드의 우려사항 검토
- 우려사항 심각도에 따라 dispatch 진행 또는 보류 결정
- Telegram 알림 수신 후 팀장 판단 대기 (자동 dispatch 없음)

**예시 상황**:
- 성능 측정 결과 기준치 대비 20% 저하 발견, 기능은 동작
- 스펙 문서 A와 B가 충돌하여 A 기준으로 구현, B 기준 구현 필요 시 재작업 예상
- 임시 해결책(workaround) 적용, 근본 원인 해결 별도 필요
- 의존 라이브러리 보안 취약점 발견 (업무 차단은 아님)

---

### 2.3 NEEDS_CONTEXT - 추가 정보 필요

**정의**: 작업 진행을 위해 팀장 또는 다른 팀원의 추가 정보가 필요한 상태. 작업 자체는 중단됨.

**사용 조건**:
- 스펙 문서가 불명확하거나 서로 모순됨
- 의존 파일, 모듈, 또는 서비스가 존재하지 않음
- 외부 API 인증 정보, 엔드포인트, 계약 명세 부재
- 비즈니스 로직 결정이 필요하여 에이전트 단독 판단 불가

**팀장(아누) 처리 방법**:
- 에스컬레이션 알림 수신
- `context_needed` 필드에 명시된 필요 정보 확인
- 정보 제공 또는 관련 팀원에게 재위임
- 정보 제공 완료 후 해당 팀원에게 동일 태스크 재위임

**예시 상황**:
- "payment-service API 스펙 없음, 인증 방식 불명확"
- "의존 모듈 `libs/analytics.py`가 존재하지 않음"
- "스펙에서 요금 계산 로직이 두 가지 방식으로 기술되어 있음, 어느 것을 따를지 결정 필요"
- "외부 파트너사 webhook URL 미제공"

---

### 2.4 BLOCKED - 진행 불가 (외부 장애)

**정의**: 에이전트 제어 범위 밖의 외부 의존성 문제로 작업 진행이 완전히 불가능한 상태.

**사용 조건**:
- 인프라 장애 (DB 연결 불가, 서버 다운)
- 필수 환경 변수 또는 시크릿 누락
- 외부 API 서비스 다운 또는 할당량 초과
- 파일시스템 권한 부재
- 네트워크 접근 불가

**팀장(아누) 처리 방법**:
- 긴급 알림 수신 (Telegram)
- `blocked_reason` 필드의 차단 원인 확인
- 체인 stalled 처리 (해당 체인 일시 중단)
- 근본 원인 해결 담당자 지정 및 해결 후 체인 재개

**예시 상황**:
- "PostgreSQL 연결 실패: Connection refused (port 5432)"
- "환경변수 `PAYMENT_API_SECRET` 미설정"
- "외부 SMS API rate limit 초과, 24시간 대기 필요"
- "S3 버킷 읽기 권한 없음 (403 Forbidden)"

---

## 3. .done 파일 포맷 변경안

### 3.1 현재 포맷

현재 `.done` 파일은 두 가지 형태로 존재한다.

**finish-task.sh 생성 포맷** (`memory/events/<task_id>.done`):
```json
{
  "task_id": "task-831.1",
  "completed_at": "2026-03-23T10:00:00+09:00"
}
```

**팀원 에이전트 생성 포맷** (QC 결과 포함):
```json
{
  "task_id": "task-831.1",
  "status": "done",
  "merge_needed": false,
  "merge_branch": null,
  "qc_result": "PASS"
}
```

### 3.2 변경 후 포맷

```json
{
  "task_id": "task-831.1",
  "completion_state": "DONE",
  "status": "done",
  "merge_needed": false,
  "merge_branch": null,
  "qc_result": "PASS",
  "concerns": null,
  "context_needed": null,
  "blocked_reason": null
}
```

### 3.3 필드 설명

| 필드명 | 타입 | 필수 | 설명 |
|--------|------|------|------|
| `task_id` | string | 필수 | 태스크 ID (예: `task-831.1`) |
| `completion_state` | string | 필수(신규) | 4가지 상태 중 하나: `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, `BLOCKED` |
| `status` | string | 유지 | 하위 호환성 유지용. 항상 `"done"` |
| `merge_needed` | boolean | 기존 | 병합 필요 여부 |
| `merge_branch` | string\|null | 기존 | 병합 대상 브랜치명 |
| `qc_result` | string\|null | 기존 | QC 결과: `PASS`, `FAIL`, `WARN` |
| `concerns` | string\|null | 조건부 | `DONE_WITH_CONCERNS` 시 우려사항 상세 텍스트 |
| `context_needed` | string\|null | 조건부 | `NEEDS_CONTEXT` 시 필요한 정보 상세 설명 |
| `blocked_reason` | string\|null | 조건부 | `BLOCKED` 시 차단 원인 상세 설명 |

### 3.4 상태별 유효 필드 조합

```
DONE:
  completion_state: "DONE"
  concerns: null
  context_needed: null
  blocked_reason: null

DONE_WITH_CONCERNS:
  completion_state: "DONE_WITH_CONCERNS"
  concerns: "성능 20% 저하 발견 - P95 응답시간 200ms → 240ms. 기능 동작은 정상."
  context_needed: null
  blocked_reason: null

NEEDS_CONTEXT:
  completion_state: "NEEDS_CONTEXT"
  concerns: null
  context_needed: "payment-service API 인증 방식 불명확. Bearer token vs API-Key 중 어느 방식 사용인지 확인 필요."
  blocked_reason: null

BLOCKED:
  completion_state: "BLOCKED"
  concerns: null
  context_needed: null
  blocked_reason: "PostgreSQL 연결 불가 (Connection refused, port 5432). DB 서버 상태 확인 필요."
```

---

## 4. done-watcher.py 연동 변경점

### 4.1 현재 동작

```
.done 파일 감지
    → team_id 추출
    → bot-activity.json 상태 idle 전환
```

### 4.2 변경 후 동작

```
.done 파일 감지
    → team_id 추출
    → completion_state 읽기 (없으면 "DONE" 으로 간주)
    → 상태별 분기 처리:

    DONE:
        → 기존 동작 유지 (bot idle 전환)
        → 체인 연동 시: 다음 Phase 자동 dispatch

    DONE_WITH_CONCERNS:
        → bot idle 전환
        → 팀장(아누)에게 Telegram 알림
          알림 내용: task_id, concerns 텍스트
        → 자동 dispatch 보류 (팀장 판단 대기)
        → done-protocol.log에 CONCERNS 이벤트 기록

    NEEDS_CONTEXT:
        → bot idle 전환
        → 팀장에게 에스컬레이션 알림
          알림 내용: task_id, context_needed 텍스트
        → dispatch 중단
        → done-protocol.log에 ESCALATION 이벤트 기록

    BLOCKED:
        → bot idle 전환
        → 팀장에게 긴급 알림 (CRITICAL 레벨)
          알림 내용: task_id, blocked_reason 텍스트
        → 체인 stalled 처리 (chain.json에 stalled 상태 기록)
        → done-protocol.log에 BLOCKED 이벤트 기록
```

### 4.3 신규 함수 목록 (구현 시 추가 예정)

```python
def read_completion_state(done_file: Path) -> tuple[str, dict]:
    """
    .done 파일에서 completion_state와 부가 정보 읽기.

    Returns:
        (completion_state, extra_fields)
        completion_state: "DONE" | "DONE_WITH_CONCERNS" | "NEEDS_CONTEXT" | "BLOCKED"
        extra_fields: {"concerns": ..., "context_needed": ..., "blocked_reason": ...}

    completion_state 필드 없을 경우 ("DONE", {}) 반환 (하위 호환)
    """

def notify_concerns(task_id: str, concerns: str) -> None:
    """DONE_WITH_CONCERNS 시 팀장 Telegram 알림"""

def notify_escalation(task_id: str, context_needed: str) -> None:
    """NEEDS_CONTEXT 시 팀장 에스컬레이션 알림"""

def notify_blocked(task_id: str, blocked_reason: str) -> None:
    """BLOCKED 시 팀장 긴급 알림 (CRITICAL)"""

def mark_chain_stalled(task_id: str) -> None:
    """BLOCKED 상태의 태스크가 속한 체인을 stalled 처리"""
```

### 4.4 변경 영향 범위

- **파일**: `/home/jay/workspace/scripts/done-watcher.py`
- **변경 유형**: 기존 `process_done_files()` 함수에 분기 로직 추가
- **외부 의존성 추가**: notify-completion.py 또는 Telegram 알림 모듈 연동

---

## 5. task-timer.py 연동 변경점

### 5.1 현재 동작

```bash
python3 task-timer.py end <task_id> [--qc-result PASS|FAIL|WARN]
```

`task-timers.json`에 `end_time`, `duration_seconds`, `qc_result` 기록.

### 5.2 변경 후 동작

```bash
python3 task-timer.py end <task_id> \
    [--qc-result PASS|FAIL|WARN] \
    [--state DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED]
```

`task-timers.json`에 `completion_state` 필드 추가 기록.

### 5.3 task-timers.json 변경 포맷

**현재**:
```json
{
  "tasks": {
    "task-831.1": {
      "status": "completed",
      "team_id": "dev2-team",
      "start_time": "2026-03-23T09:00:00",
      "end_time": "2026-03-23T10:30:00",
      "duration_seconds": 5400,
      "qc_result": "PASS"
    }
  }
}
```

**변경 후**:
```json
{
  "tasks": {
    "task-831.1": {
      "status": "completed",
      "team_id": "dev2-team",
      "start_time": "2026-03-23T09:00:00",
      "end_time": "2026-03-23T10:30:00",
      "duration_seconds": 5400,
      "qc_result": "PASS",
      "completion_state": "DONE"
    }
  }
}
```

### 5.4 finish-task.sh 연동

`finish-task.sh`는 현재 `.done` 파일에서 `qc_result`를 추출하여 `task-timer end`에 전달한다. 동일 방식으로 `completion_state`도 추출하여 전달하도록 변경 예정.

```bash
# 현재 (finish-task.sh 발췌)
python3 "$WORKSPACE/memory/task-timer.py" end "$TASK_ID" --qc-result "$QC_RESULT"

# 변경 후
python3 "$WORKSPACE/memory/task-timer.py" end "$TASK_ID" \
    --qc-result "$QC_RESULT" \
    --state "$COMPLETION_STATE"
```

### 5.5 신규 CLI 인자 (구현 시 추가 예정)

```
python3 task-timer.py end <task_id> --state DONE_WITH_CONCERNS
python3 task-timer.py end <task_id> --state NEEDS_CONTEXT
python3 task-timer.py end <task_id> --state BLOCKED
```

`--state` 미제공 시 기본값 `DONE` 적용 (하위 호환).

### 5.6 변경 영향 범위

- **파일**: `/home/jay/workspace/memory/task-timer.py`
- **변경 유형**: `end` 서브커맨드에 `--state` 인자 추가, `task-timers.json` 기록 로직 추가
- **파일**: `/home/jay/workspace/scripts/finish-task.sh`
- **변경 유형**: `completion_state` 추출 및 `task-timer end --state` 전달 로직 추가

---

## 6. 하위 호환성

### 6.1 원칙

이 시스템 도입으로 인해 기존 도구 체인이 중단되어서는 안 된다.

### 6.2 호환성 보장 방법

**`.done` 파일 호환성**:
- 기존 `status: "done"` 필드는 유지
- `completion_state` 필드가 없는 구형 `.done` 파일은 `completion_state: "DONE"`으로 간주
- done-watcher.py는 `completion_state` 없는 파일을 DONE으로 처리 (기존 동작 동일)

**task-timers.json 호환성**:
- `completion_state` 필드 없는 기존 레코드는 `DONE`으로 간주
- 조회 시 필드 없을 경우 기본값 `"DONE"` 반환

**finish-task.sh 호환성**:
- `--state` 인자 없이 `task-timer end` 호출 시 기본값 `DONE` 적용

**기존 도구 영향 없음**:
- chain.py: `.done` 파일의 신규 필드 무시 (기존 로직 그대로)
- dispatch.py: 변경 없음
- notify-completion.py: 기존 `task_id` 기반 알림 로직 변경 없음

### 6.3 마이그레이션

- 기존 `.done` 파일 재작성 불필요
- 기존 `task-timers.json` 데이터 변환 불필요
- 신규 필드는 새로 생성되는 파일부터 자동 적용

---

## 7. 구현 우선순위

### Phase B-3 (현재 단계): 설계 문서 작성

- [x] 4-state 완료 코드 시스템 설계 문서 작성
- [ ] 코드 수정 없음

### Phase C 이후: 실제 코드 수정

**C-1. done-watcher.py 수정**
- `read_completion_state()` 함수 추가
- `process_done_files()` 내 상태별 분기 로직 추가
- `notify_concerns()`, `notify_escalation()`, `notify_blocked()` 함수 추가
- `mark_chain_stalled()` 함수 추가

**C-2. task-timer.py 수정**
- `end` 서브커맨드에 `--state` 인자 추가
- `_end_task()` 함수에 `completion_state` 기록 로직 추가

**C-3. finish-task.sh 수정**
- `.done` 파일에서 `completion_state` 추출 로직 추가
- `task-timer end --state` 인자 전달 로직 추가

**C-4. 팀원 에이전트 프롬프트 업데이트**
- `finish-task.sh` 호출 전 `.done` 파일에 `completion_state` 기록 지침 추가
- 각 상태 코드 사용 조건 명시

**C-5. 통합 테스트**
- 각 상태 코드별 end-to-end 시나리오 검증
- 하위 호환성 테스트 (구형 `.done` 파일 처리 확인)

---

## 8. 참조

- `/home/jay/workspace/scripts/done-watcher.py` - 현재 done-watcher 구현
- `/home/jay/workspace/memory/task-timer.py` - 현재 task-timer 구현
- `/home/jay/workspace/scripts/finish-task.sh` - L1 마무리 스크립트
- `/home/jay/workspace/dispatch.py` - dispatch 시스템
- `/home/jay/workspace/memory/specs/phase-gate-checklist.md` - 4개 검증 게이트 정의
- `/home/jay/workspace/memory/specs/retry-escalation-protocol.md` - 에스컬레이션 프로토콜
- `/home/jay/workspace/memory/specs/incident-response.md` - 인시던트 대응 절차