# task-313.1: Agent Mode Gap 항목 구현 (6개)

## 개요
task-310.1 Agent Mode 감사에서 식별된 부분 적용/미적용 Gap 4개를 6개 구체 구현 항목으로 해소한다.

## 사전 확인 사항
- `black` 26.1.0, `isort` 8.0.1 → **이미 설치됨** (pip 설치 불필요)
- `/home/jay/workspace/` → **git repo** (main 브랜치)
- 참조 보고서: `/home/jay/workspace/memory/reports/task-310.1.md`

## 구현 항목 (6개)

### 항목 1. pyproject.toml — black + isort 설정
- **파일**: `/home/jay/workspace/pyproject.toml` (신규 생성 또는 기존에 추가)
- **내용**:
  ```toml
  [tool.black]
  line-length = 120
  target-version = ["py311"]

  [tool.isort]
  profile = "black"
  line_length = 120
  ```
- 설정 후 테스트: `black --check --diff teams/dev1/qc/qc_verify.py` 실행하여 동작 확인

### 항목 2. style_check verifier — qc_verify.py에 추가
- **파일**: `/home/jay/workspace/teams/dev1/qc/qc_verify.py`
- **추가할 verifier**: `style_check`
- **동작**:
  - `--check-files`로 전달된 Python 파일에 대해 `black --check --quiet` + `isort --check --quiet` 실행
  - 둘 다 통과 → PASS
  - 포매팅 필요 → WARN (자동 수정 안내 메시지 포함: `black <file> && isort <file>`)
  - black/isort 미설치 → SKIP
- **결과 형식**:
  ```json
  {
    "style_check": {
      "status": "PASS|WARN|SKIP",
      "details": ["black: OK", "isort: 2 files need reformatting"]
    }
  }
  ```
- **별도 verifier 파일**: `/home/jay/workspace/teams/dev1/qc/verifiers/style_check.py` (pyright_check.py 패턴 따라)

### 항목 3. scope_check verifier — qc_verify.py에 추가
- **파일**: `/home/jay/workspace/teams/dev1/qc/qc_verify.py`
- **추가할 verifier**: `scope_check`
- **동작**:
  - `--expected-files` 파라미터 (콤마 구분 파일 목록) 또는 `--expected-files-from` (파일에서 읽기)
  - audit-trail.jsonl에서 현재 task_id의 실제 변경 파일 추출
  - 실제 변경 ↔ 예상 파일 대조
  - 일치 → PASS
  - 예상 외 파일 변경 → WARN (변경된 예상 외 파일 목록 출력)
  - `--expected-files` 미전달 → SKIP (선택적 verifier)
- **결과 형식**:
  ```json
  {
    "scope_check": {
      "status": "PASS|WARN|SKIP",
      "details": ["Expected: 3 files", "Actual: 4 files", "Unexpected: renderer/utils.py"]
    }
  }
  ```
- **별도 verifier 파일**: `/home/jay/workspace/teams/dev1/qc/verifiers/scope_check.py`

### 항목 4. DIRECT-WORKFLOW.md — git 커밋 규칙 추가
- **파일**: `/home/jay/workspace/prompts/DIRECT-WORKFLOW.md`
- **추가 위치**: "LSP 활용 규칙" 섹션 아래에 새 섹션
- **추가 내용**:
  ```markdown
  ## Git 커밋 규칙
  - 서브태스크 단위로 커밋 (하나의 논리적 변경 = 하나의 커밋)
  - 커밋 메시지 형식: `[task-id] 변경 내용 요약`
    - 예: `[task-300.1] 렌더러 Bold 폰트 적용 + 오버플로우 방지`
  - 코드 변경 시 반드시 `black` + `isort` 포매팅 후 커밋
  - 커밋 전 pyright 체크 통과 필수
  ```

### 항목 5. DIRECT-WORKFLOW.md — QC 재시도 루프 추가
- **파일**: `/home/jay/workspace/prompts/DIRECT-WORKFLOW.md`
- **추가 위치**: "작업 규칙" 섹션에 추가
- **추가 내용**:
  ```markdown
  ## QC 재시도 규칙
  - qc_verify.py 실행 → FAIL 항목 발견 시:
    1. FAIL 원인 분석 및 코드 수정
    2. qc_verify.py 재실행
    3. 최대 3회 재시도. 3회 실패 시 팀장이 아누에게 에스컬레이션
  - WARN은 보고서에 기록하되 재시도 불필요
  ```

### 항목 6. QC-RULES.md v2.2 업데이트
- **파일**: `/home/jay/workspace/teams/shared/QC-RULES.md`
- **변경**:
  - verifier 목록 테이블에 `style_check`, `scope_check` 행 추가
  - 변경 이력에 v2.2 기록
  - `style_check`: "Python 코드 스타일(black+isort) 검증"
  - `scope_check`: "변경 범위 검증 (예상 파일 ↔ 실제 변경 대조)"

## 참고 파일
- 기존 qc_verify.py: `/home/jay/workspace/teams/dev1/qc/qc_verify.py`
- pyright_check verifier (패턴 참조): `/home/jay/workspace/teams/dev1/qc/verifiers/pyright_check.py`
- QC-RULES.md: `/home/jay/workspace/teams/shared/QC-RULES.md`
- DIRECT-WORKFLOW.md: `/home/jay/workspace/prompts/DIRECT-WORKFLOW.md`
- audit-trail 경로: scope_check에서 사용. 경로 확인 필요.

## 테스트
1. **style_check 테스트**: 임의 Python 파일에 대해 `black --check` + `isort --check` 실행하여 PASS/WARN 확인
2. **scope_check 테스트**: `--expected-files` 전달/미전달 시 PASS/SKIP 확인
3. **기존 verifier 정상 동작**: regression 없는지 전체 qc_verify.py 실행 테스트
4. **pyproject.toml 설정 적용**: `black --check` 실행 시 line-length=120 적용 확인
5. **문서 정합성**: DIRECT-WORKFLOW.md, QC-RULES.md 내용이 구현과 일치하는지

## 완료 기준
- [ ] pyproject.toml에 black + isort 설정
- [ ] style_check verifier 동작 (PASS/WARN/SKIP)
- [ ] scope_check verifier 동작 (PASS/WARN/SKIP)
- [ ] DIRECT-WORKFLOW.md에 git 커밋 규칙 추가
- [ ] DIRECT-WORKFLOW.md에 QC 재시도 규칙 추가
- [ ] QC-RULES.md v2.2 업데이트 (2개 verifier 추가)
- [ ] 기존 verifier regression 없음
- [ ] pyright 체크 에러 0건

## task-timer
- task_id: task-313.1
- 완료 시: `python3 /home/jay/workspace/memory/task-timer.py end task-313.1`