# task-1286.1: MoAI-ADK Phase 1 코드화

**팀**: dev1-team (헤르메스)
**레벨**: critical
**일시**: 2026-03-31

---

## SCQA

**S**: MoAI-ADK 시스템의 Phase 1 기능 3건(Progressive Disclosure, 읽기/쓰기 격리, hooks 자동 강제)과 선행 인프라(Phase 0a 기준선, Phase 0b feature flags)의 코드화가 필요하다.

**C**: 5개 Task(Phase 0a, 0b, P1-1, P1-2, P1-7)가 의존 관계를 가지며, feature flag 기반 안전 배포와 롤백을 지원해야 한다. 기존 시스템(dispatch.py, team_prompts.py, worktree_manager.py)에 대한 변경이므로 회귀 위험이 존재한다.

**Q**: 5개 Task를 모두 구현하고 기존 시스템 회귀 없이 통합 테스트를 통과할 수 있는가?

**A**: 5개 Task 전체 구현 완료. Phase 1 신규 테스트 39건 전체 통과(0.20s). 기존 테스트 회귀 없음(team_prompts 111 passed, dispatch 141 passed). 모든 기능은 feature flag(기본값 false)로 보호되어 안전하게 비활성화 상태로 배포됨. pyright 0 error, black/isort 포맷팅 완료.

---

## 구현 내역

### Phase 0a: 기준선 측정
- `.metrics/baseline/baseline_2026-04-03.json` 생성 (8개 지표, sample_size=30)

### Phase 0b: Feature Flags 인프라
- `.claude/feature_flags.json` 생성 (6개 플래그, 모두 false)
- `utils/feature_flags.py` 구현 (FeatureFlagLoader: mtime 캐시, atomic write, JSONDecodeError 복구)
- 단위 테스트 14건 전체 통과

### P1-1: Progressive Disclosure
- `prompts/team_prompts.py`의 `build_prompt`에 `disclosure_phase` 파라미터 추가
- CRITICAL_SET 상수 (~80 tokens), TOKEN_LIMITS, `_count_tokens`, `_truncate_to_token_limit` 구현
- TC-PD-01~04 전체 통과

### P1-2: 읽기/쓰기 격리
- `dispatch.py`에 `--agent-type read|write` 인자 추가 (기본값: write)
- `dispatch()` 함수에 `agent_type` 파라미터 + `rw_isolation_enabled` 플래그 연동
- `scripts/worktree_manager.py`의 `cmd_create`에 `read_only` 파라미터 추가
- `prompts/DIRECT-WORKFLOW.md` 섹션 5 추가
- TC-RW-01~04 + 문서검증 5건 통과

### P1-7: Hooks 자동 강제
- `.claude/settings.json` PostToolUse 훅 설정
- `hooks/post_tool_use.sh` 구현 (pyright + ruff 자동 실행)
- `hooks/circuit_breaker.py` 구현 (warning 15회/critical 30회/3-tuple 연속 3회 halt)
- `teams/shared/QC-RULES.md`에 "hooks와 QC는 별개 의무" 규칙 추가
- TC-HK-01~07 + 추가 테스트 9건 통과

### Spec 문서
- `docs/specs/` 하위 6건 작성

---

## 산출물 파일

- `/home/jay/workspace/.metrics/baseline/baseline_2026-04-03.json`
- `/home/jay/workspace/.claude/feature_flags.json`
- `/home/jay/workspace/.claude/settings.json`
- `/home/jay/workspace/utils/feature_flags.py`
- `/home/jay/workspace/hooks/post_tool_use.sh`
- `/home/jay/workspace/hooks/circuit_breaker.py`
- `/home/jay/workspace/prompts/team_prompts.py` (수정)
- `/home/jay/workspace/dispatch.py` (수정)
- `/home/jay/workspace/scripts/worktree_manager.py` (수정)
- `/home/jay/workspace/prompts/DIRECT-WORKFLOW.md` (수정)
- `/home/jay/workspace/teams/shared/QC-RULES.md` (수정)
- `/home/jay/workspace/docs/specs/spec-p1-1-progressive-disclosure.md`
- `/home/jay/workspace/docs/specs/spec-p1-2-rw-isolation.md`
- `/home/jay/workspace/docs/specs/spec-p1-7-hooks-enforcement.md`
- `/home/jay/workspace/docs/specs/spec-feature-flags.md`
- `/home/jay/workspace/docs/specs/spec-metrics-baseline.md`
- `/home/jay/workspace/docs/specs/spec-rollback-procedure.md`
- `/home/jay/workspace/tests/test_feature_flags.py`
- `/home/jay/workspace/tests/test_progressive_disclosure.py`
- `/home/jay/workspace/tests/test_rw_isolation.py`
- `/home/jay/workspace/tests/test_hooks_enforcement.py`
- `/home/jay/workspace/tests/integration/__init__.py`
- `/home/jay/workspace/tests/integration/test_phase1_integration.py`

---

## 테스트 결과

- Phase 1 신규 테스트: **39/39 passed** (0.20s)
- 기존 test_team_prompts.py: **111/111 passed** (회귀 없음)
- 기존 test_dispatch.py: **141/141 passed** (회귀 없음)
- pyright: 0 errors (check-files 대상)
- style: black/isort 포맷팅 완료

---

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **`_truncate_to_token_limit` 타입 힌트 오류** — `limit: int`를 `limit: Optional[int]`로 수정 (pyright unreachable code 경고 해소)
   - 수정: `prompts/team_prompts.py:532`
2. **circuit_breaker threshold 테스트에서 3-tuple halt 조기 발동** — threshold 테스트에서 동일 파일명 반복 사용 시 연속 3-tuple 조건에 먼저 걸리는 문제. 각 반복마다 다른 파일명(`foo_{i}.py`) 사용으로 해결
   - 수정: `tests/test_hooks_enforcement.py`
3. **테스트 파일 미사용 import** — pyright 경고 해소를 위해 os, pytest, Path, CRITICAL_SET 등 미사용 import 제거
   - 수정: `tests/test_progressive_disclosure.py`, `tests/test_hooks_enforcement.py`

### 범위 외 미해결 (2건)
1. **`_build_direct_prompt` 함수의 미사용 파라미터** — `level`, `timer_start`, `timer_end`, `report_path` 파라미터가 함수 본문에서 사용되지 않음. Phase 1 이전부터 존재하는 설계 결정. 범위 외 사유: 기존 API 호환성 유지 필요
2. **pyright `reportMissingImports` 경고** — 테스트 파일에서 `utils.feature_flags`, `hooks.circuit_breaker` 등의 import를 pyright가 해석하지 못함. 런타임에는 `sys.path.insert()`로 정상 동작. 범위 외 사유: pyright 설정(pyrightconfig.json) 변경은 별도 작업

---

## QC 자동 검증

```json
{
  "task_id": "task-1286.1",
  "checks": {
    "pyright_check": "PASS (0 errors)",
    "test_runner": "PASS (14 passed)",
    "style_check": "PASS (black/isort 적용 후)",
    "data_integrity": "PASS"
  }
}
```

---

## 셀프 QC 체크리스트

- [x] 1. 영향 파일: team_prompts.py, dispatch.py, worktree_manager.py, DIRECT-WORKFLOW.md, QC-RULES.md (기존 파일 수정), 나머지는 신규 생성
- [x] 2. 엣지 케이스: 존재하지 않는 플래그 → False 반환, JSONDecodeError → 이전 캐시 유지, 빈 파일 → 빈 플래그 dict
- [x] 3. 작업 지시 일치 확인: 5개 Task DoD 전체 충족
- [x] 4. 에러 처리/보안: atomic write, tempfile 패턴, JSONDecodeError 복구
- [x] 5. 테스트 커버리지: 39건 (unit 32건 + integration 7건)
- [x] 6. 이슈 자체 해결: 3건 해결, 2건 범위 외
- [x] 7. 코드 아키텍처: SOLID/DRY 위반 없음
- [x] 8. 인터페이스 변경 문서 갱신: DIRECT-WORKFLOW.md 섹션 5 추가, spec 문서 6건 작성