# 체이닝 시스템 아키텍처 (Chaining Architecture)

> 작성: task-569.1 | 날짜: 2026-03-15

## 개요

워크스페이스에는 2개의 체이닝 시스템이 존재하며, 각각 다른 역할을 수행한다.

## 1. chain.py — 멀티팀 Phase 오케스트레이터

- **역할**: 여러 팀이 동일 Phase에서 병렬 작업 → 모든 팀 완료 시 다음 Phase 자동 dispatch
- **데이터 파일**: `memory/chains/{chain_id}.json` (접두어 없음)
- **dispatch 연동**: `dispatch.py --chain <chain_id>` → 팀장 완료 시 `chain.py task-done` 호출
- **데이터 구조**: phases 배열 내 tasks 배열 (2단계 중첩)
- **사용 시나리오**: 여러 팀(dev1, dev2)이 동시에 참여하는 대규모 프로젝트 Phase 관리

### 서브커맨드
- `create --id <id> --desc <설명>`: 빈 체인 생성
- `add-phase --chain <id> --name <이름> --tasks <JSON>`: Phase 추가
- `task-done --chain <id> --task <task_id>`: task 완료 마킹 + Phase 전환
- `status --chain <id>`: 상태 조회
- `list`: 전체 목록

## 2. chain_manager.py — 단일팀 순차 체이닝

- **역할**: 개별 작업을 순서대로 실행 (한정승인/scoped delegation)
- **데이터 파일**: `memory/chains/chain-{chain_id}.json` (chain- 접두어)
- **dispatch 연동**: `dispatch.py --phases N` → `chain_manager.py create` 자동 호출
- **완료 연동**: `notify-completion.py` → `chain_manager.py next` 호출로 다음 task dispatch
- **데이터 구조**: tasks 배열 (1단계, order 필드로 순서 관리)
- **사용 시나리오**: 단일 팀이 순차적으로 수행하는 Phase 작업 (예: Phase 1 완료 → Phase 2 자동 시작)

### 서브커맨드
- `create --chain-id <id> --tasks <JSON>`: 체인 생성 + watchdog cron 등록
- `next --task-id <task_id>`: 완료된 task의 다음 pending task 반환
- `update --task-id <id> --status <상태>`: task 상태 수정
- `check --task-id <id>`: 체인 소속 및 마지막 여부 확인 (읽기 전용)
- `check-stalled --max-hours N`: 정체 작업 검색
- `list`: 활성 체인 목록

## 파일 네이밍 규칙

| 시스템 | 파일 패턴 | 예시 |
|--------|-----------|------|
| chain.py | `{chain_id}.json` | `insuwiki-p1p2.json` |
| chain_manager.py | `chain-{chain_id}.json` | `chain-scoped-566.json` |

## dispatch.py 연동

| dispatch 플래그 | 대상 시스템 | 동작 |
|----------------|------------|------|
| `--chain <id>` | chain.py | 팀장 프롬프트에 chain_id 전달, 팀장이 완료 시 chain.py task-done 호출 |
| `--phases N` | chain_manager.py | dispatch 성공 후 chain_manager.py create 자동 호출 |

## 혼동 방지 가이드

1. **"이 작업이 체인에 속하나?"** → `chain_manager.py check --task-id` 사용
2. **"멀티팀 Phase를 관리하고 싶다"** → `chain.py` 사용
3. **"순차 작업을 자동 연결하고 싶다"** → `chain_manager.py` (dispatch.py --phases) 사용
4. **파일 경로 보고 구분**: `chain-` 접두어가 있으면 chain_manager.py, 없으면 chain.py