# 오케스트레이터 종합 개발 보고서 (2026-07-13)

> 목적: 전체 개발 내용을 한 번에 검토. 라이브 데이터는 대시보드/목표탭에서 갱신, 이 문서는 서사·근거.
> 절대원칙: 검증부 Anthropic 0 · claude -p 구독 구분 · 판정 기계적 · 날조·술어확장 금지 · 갈리면 불합치 · [비용] 상시 · 못 한 건 정직.

## [비용] 누적
```
누적 총액 ≈ $3.88 (₩약 5,240원) · Anthropic API 0 · 원장: handoff/cost_ledger.md
```

## 1. 이 앱은 무엇인가
**견제 오케스트레이터** — 여러 AI(Claude 로컬·GPT·Grok·Gemini 비판자)가 서로 견제·검증하며 앱을 자동 개발하는 도구. 검증부는 Anthropic API를 0회 쓰고(Claude 자리=로컬), 실행부만 `claude -p`(구독)로 VM에 적용.

## 2. Claude Code의 역할 — **3가지** (2026-07-13 확정)
| 역할 | 내용 | 비용 |
|---|---|---|
| ① AI 대화 참여 | 토론·심판(검증부) | Anthropic 0 (LocalClaudeAdapter) |
| ② 초기 자료 정리 | 업로드된 MD·파일을 **첫 번째로 읽고** 정리 | 구독(claude -p) |
| ③ 앱 VM 설치 | 합의 코드를 VM에 받아쓰기·적용 | 구독(claude -p) |
> ②③은 구독 채널이라 Anthropic API와 별개 표기. ③의 `claude login`은 설치 후 **브라우저 인증만 사람**이 하면 됨(헤드리스 불가 — 정직한 한계).

## 3. 핵심 기능 (기능↔인터페이스 동기 100% · 19/19)
토론·§7검증·심판·처분게이트·사람서명 / 실행부(byte일치·독립테스트·재투입) / 비판자(데이터 교체) / 교차반증(역할반전) / 실시간 SSE / park 의견 대화창 / 최신모델 자동 / 로그인 / VM 주소 입력 / 커버리지·버그체크 / 변경로그 / 개발목표 탭. — 상세·상태는 **개발 목표 탭**(goals.html)에서 실측.

## 4. 설계 규범 (SPEC 개정 이력)
| 개정 | 내용 |
|---|---|
| #1 | E1 vs F3 충돌 해소 (사람 서명) |
| #2 | 비용 보고 상시화 (G4) |
| #3 | 비판자(Devil's Advocate) 로스터 + Gemini, 데이터 교체 |
| #4 | 교차반증(역할반전)을 불합치 해소 기준으로 |
| #5 | 실시간 연동(라이브 SSE, bb.trace 관찰) |
| #6 | 오케스트레이터 핵심 기준(자격증명·최신모델·컨텍스트·교차반증·변경로그·끝까지진행) |
| #7 | 옵션 c 서명·구현(E1↔B4 순차 공존 + resume 가드) |

## 5. 기계 감사 (25 PASS · 0 FAIL · 3 N/A + H1~H15)
정본 28항목 + 보충 H1~H15 전부 PASS. H12 교차반증·H13 실시간·H14 최신모델·H15 옵션c 가드. 실행: `.venv/bin/python audit_offline.py`.

## 6. 오늘 세션 요청 반영 (25건: 완료 21 · 부분 2 · park 1 등)
개발 목표 탭 ①에 실시간 표. **정직하게 안 끝난 것:** 도메인 실연결(대표님 3단계) · 기존앱 보안 나머지(우선순위 중단) · 2FA 방식(park).

## 7. 관측·원장 (append-only)
비용원장 · 비판자원장 · 정제도원장 · 변경로그(무엇·왜·되돌리기·검증) · 투표원장 · 사용모델원장 · 트레이스(런별 대화·에스컬레이션).

## 8. 누락 방지 = 층상 방어 (대표님 우려에 대한 답)
- **1차 기계:** 커버리지(기능↔UI desync + 미등록 라우트) · 버그체크(HTML/JS 괄호·깨진링크·없는API) — 매 빌드 자동, 화면 노출.
- **2차 회의:** AI 완결성 검토(기계가 못 보는 새 요구). 
- **실증:** 오늘 이 방어가 **실제 버그 2건**을 잡음 — /api/goals 미등록, build.py 조용한 import 실패(커버리지 패널이 내내 비어있던 것). 술어확장 금지: "100%"는 등록된 것만.

## 9. 남은 사람 결정 (park — park.html 대화창)
2FA 방식(Basic vs Authelia+지문) · 진행률 표시형식 P1~P5 · Claude Code 대화창 스코프 · 도메인 실연결.

## 10. 정직한 한계
- 커버리지·버그체크는 **등록/구조 검사** — 미등록 새 요구·의미적 버그는 회의(2차)가 방어.
- VM 자동설치의 `claude login`은 브라우저 인증이라 완전 자동 불가.
- "동작 완성"이지 "배포 완성" 아님(도메인·2FA 미완).
- 로그인은 v1(쿠키·비번 파일) — 2FA/해싱은 업그레이드 park.