vignette/docs/TODO.md

# Vignette 할 일 (안된 것들) — 통합 TODO

> **한 곳에서 보는 "남은 작업" 인덱스.** 여러 문서에 흩어져 있던 열린 작업을 주제별로 모았다.
> **권위 기준은 SSOT `dev_dashboard.html`**, 열린 게이트 추적은 `ops/backlog-2026-06-26.md`(얇은 현행본)다.
> 이 파일은 그 둘을 **집계·링크**하는 뷰이며, 상태가 어긋나면 대시보드를 기준으로 맞춘다.
> 완료된 작업 기록은 `archive/`(냉동 보관)에 있고 평상시 읽지 않는다.
>
> 태그: **[환경]** 이 워크스테이션에서 증거 생산 불가 · **[외부]** 기관/소유자 서면·결정 필요 ·
> **[구현]** 코드로 진행 가능 · **[임상]** 임상팀(구훈정·어유경) 외부 콘텐츠 소유.

---

## A. 배포·공개 런타임 게이트  [환경]
> 출처: `ops/backlog-2026-06-26.md` B2 · 대시보드 운영 탭 · `ops/tailscale-vnet-runtime-2026-06-27.md` · `ops/public-runtime-watchdog.md` · `HANDOFF.md`

- [ ] **공개 Google OAuth 실제 `/turn` proof** — 로그인 계정으로 `storageState` 캡처 → `E2E_PUBLIC_AUTH=1` +
  `chromium-public-auth` 1회 통과. 실행 명령은 대시보드 "다음 실행 명령"/`HANDOFF.md`. (소유자 보류 중)
- [ ] **실배포 `infra/.env` owner-secret + real preflight** — `APP_DB_PASSWORD`, `OAUTH_GOOGLE_CLIENT_ID/SECRET`,
  `OPENAI_API_KEY`, `SESSION_SECRET`, prod-safe engine/voice flags 주입 후 `check-deploy-preflight.py` DB 모드 + 배포지 health.
- [ ] **`vnet.18ka.net`/`api-vnet.18ka.net` 공개 live** — DNS A record 등록, cloudflared의 `18ka.net` zone 권한,
  Google redirect URI `https://api-vnet.18ka.net/auth/callback` 등록. (현재 prod API 8001은 health OK)
- [ ] **재부팅 후 watchdog smoke** — 실제 Windows 재부팅 후 엔진/API/터널 자동 복구 + public `/turn` 실측.
  DNS 개통 후 `api-vnet.18ka.net`을 `-AdditionalPublicHealthUrls`로 명시 추가.
- [ ] **음성 캐스케이드 live** — 실제 Deepgram interim/final WSS, 물리 마이크, 공개 WSS, 50분 양방향 장시간 실측.
- [ ] **claude_cli ↔ Messages API 폴백 동일성** — `ANTHROPIC_API_KEY` 필요.

## B. 외부 거버넌스  [외부]
> 출처: 백로그 B4 · `ops/hanshin-data-governance-gate.md` · `ops/source-docs-gap-analysis-2026-06-26.md` · `MASTERPLAN.md`

- [ ] **한신대 데이터/SSO 거버넌스 서면 증거** — 공식 문의서 발송·서면 응답 수령, 동의범위 매트릭스, SSO claim map,
  privacy review, 미성년 원본 활용동의, 개인정보 처리방침. 로컬 골격은 `ops/hanshin-data-governance-gate.md`.
- [ ] **L1 스택 정합성·저작권 등재 문서 반영** — 신청서/등재 문서에 FastAPI 유지 사유 + 계약 우선 Node 전환 계획 반영.
  결정 기록: `decisions/backend-node-transition.md`.

## C. Phase 3 교육용 파일럿  [외부] + [구현 scaffold 완료]
> 출처: 백로그 Phase3 · `phase3/*` · 대시보드 P3 탭. 문서·checker·exporter scaffold는 준비됨.

- [ ] **20명 파일럿 운영** — roster, consent 법무승인(G-P3-02), session completion evidence 수집.
- [ ] **효과성/KPI 측정** — SUS·자기효능감·κ≥0.70/ICC≥0.75·환각률≤3%. 3척도 pre/post 실측 → `kpi_report.json`.
- [ ] **재귀학습 데이터셋 approved 산출** — `approved_for_recursive_learning_seed`(consent/PII/IAA/legal 승인) + 승인 export 실행.
- [ ] **개인정보/동의 감사 서명** — `phase3/privacy-consent-audit.md` 서명 완료, withdrawal_log 종결.

## D. 소유자 결정 완료(2026-06-30) → 구현 후속  [구현]
> 출처: 대시보드 "윤찬 결정 상세" 탭 · `decisions/` · 백로그 B3. 결정 자체는 전건 확정, 아래는 후속 build.

- [ ] **s2s 2차 비교 PoC 구현·실측** — `decisions/voice-s2s-poc.md` 기준표(전사·안전·감사·지연)로 20턴 비교 리포트 → 최종 채택/폐기.
- [ ] **fast-loop 외부 폴백 구현** — 로컬 상주 분류기 우선 + Haiku/Solar 폴백, 전송 가드(데이터주권·로그·동의)·관측.
- [ ] **대체 TTS provider 선정·통합** — 상업 라이선스 명확한 provider. dev sample(`VIGNETTE_VOICE_POC_SAMPLE_TTS`)과 서비스 경로 분리 유지.
- [ ] **재귀학습 fine-tuning 파이프라인** — 동의/데이터셋 게이트 충족 후. few-shot 자동갱신은 선행 가능.
- [ ] **헬스 retention 적용·검증** — raw 90일 / rollup 365일. escalation/그룹 자동화는 미도입 고정.
- [x] **한신대 실사용 피드백 1차 개선팩** — `ops/hanshin-feedback-improvement-plan-2026-07-03.md`,
  `redteam/hanshin-feedback-plan-redteam-2026-07-03.md`, `redteam/hanshin-feedback-plan-counter-redteam-2026-07-03.md`
  기준 P0~P4 1차 완료. 완료 범위: role mapping + client-only stateless history injection, review UI 표시 자연어화,
  raw error display mapper, fast/deep 라벨, 명백한 출력 결함 차단, SSE full-response buffer, 교수자 설명 패널.
  검증 수치는 SSOT 대시보드만 소유한다. 남은 후속은 저장형 fallback/synthetic 계약, 지연을 줄이는 partial stream buffer,
  fast/deep reconciliation, resident session namespace, 임상팀 루브릭/CBT/약물·평가 문구 확정.

## D-2. 전수 E2E 순회 소유자 결정 — **전건 결정 완료(2026-07-27)** → 구현 후속  [구현]
> 출처: `ops/e2e-full-sweep-2026-07-27.md` 발견 결함 로그 · `ops/backlog-2026-06-26.md` B3-신규.
> 결함 12건은 RED→GREEN으로 수정 완료(대시보드 143차). 소유자 결정 7건은 질문 도구로 전건 확정.

- [x] **설정 아바타 변경 UI 구현** — RED→GREEN 완료(full-sweep-settings 4/4, 무회귀 44/44)
- [x] **동의 철회 전체 흐름 구현** — 설정 동의 섹션+철회 2단계 확인+재동의, 실 API round-trip GREEN
- [x] **신규 학습자 기초 우선 추천 구현** — `starterPersona()` 난도 오름차순, 무회귀 42/42
- [x] **학생 분석 테이블 가상화 구현** — @tanstack/react-virtual, 300행 RED→GREEN, 무회귀 40/40+게이트 4/4
- [x] **저작 모드 좌측 레일 마크업 정리** — 레일 JSX·CSS 삭제, dead-code 게이트 통과
- [x] dev-login 재로그인 자동 재승인 — 결정: 현행 유지(코드 변경 없음, 종결)
- [x] **감정 밸런스 타임라인 차트 구현** — deep `turn_valence`+결정론 파생 폴백, 백엔드 421/421, 라이브 5pt 실측

> 전체 검증 수치·상세는 SSOT 대시보드 144차 노트와 `ops/e2e-full-sweep-2026-07-27.md`가 소유한다.

## E. 코드 품질·리팩터 로드맵  [구현] (비게이트 — 여유 시)
> 출처: `ops/code-quality-research-2026-06-26.md` · `decisions/backend-node-transition.md` next candidates.
> **2026-07-02 실측**: 로드맵 상당수는 이미 해결(turn_runtime·tier 제거·eval_hook 주입 등). 아래는 코드 재확인 기준 현행 상태.

- [x] **Stage enum SSOT 통합** — `taxonomy.Stage`를 라벨 단일 정의(SoT)로, `services.state_machine`이 re-export(중복 `class Stage` 제거). **검증: 단일 enum 정체성 확인, 백엔드 pytest 352 passed, 수집 379 import 무결. (2026-07-02)**
- [x] **store `recent_turns`/`masked_turns` Type-2 중복 제거** — `recent_turns = masked_turns()[-k:]` 위임으로 단일 소유. **검증: 백엔드 352 passed. (2026-07-02)**
- [x] **화자 한글 라벨 4× 중복 → `taxonomy.speaker_ko_label` 단일 헬퍼** — evaluator/live_coach/memory 프롬프트의 `'상담자'/'내담자'` 삼항 통합. **검증: 헬퍼 단위 + 백엔드 352 passed. (2026-07-02)**
- [x] ~~턴 파이프라인 dedup~~ — `turn_runtime.py`의 `load_owned_session`/`record_completed_turn`로 이미 추출됨.
- [x] ~~`_iso` 중복 통합~~ — teacher/sessions `_iso` 중복 해소됨(현재 `_iso_text`/`_iso_dt`는 별개 목적 함수).
- [x] ~~tier dead-contract 제거~~ · ~~voice 경로 eval_hook 미주입~~ — gateway tier 제거 + voice eval_hook 주입 완료.
- [x] **Speaker/Role 계약 레벨 — 검토 결과 조치 불요** — DB actor 매핑은 1곳(`session_persistence.py`, 중복 아님), `Role` app↔db는 이미 단일 dict(`DB_ROLE_BY_APP`/`APP_ROLE_BY_DB`), 엔진 `AIRole`은 이미 단일 `Literal`. 실제 중복이던 표시 라벨은 위에서 통합됨 → 별도 추상화 불요. (2026-07-02 실측)
- [x] **`_list_sessions` N+1 제거(1차: state/turns)** — 세션별 `session_state`/`turns` fetch 루프(1+2N) → `= ANY($ids)` 배치 3쿼리 + Python 그룹핑. **검증: 실 DB 동등성 50세션/109턴 불일치 0, 왕복 101→3, 백엔드 352 passed(회귀 테스트 mock 시퀀스 갱신). (2026-07-02)**
- [x] **`_list_sessions` N+1 제거(2차: 턴평가 하이드레이션)** — 상세 뷰에서 세션별 evaluator 연결+평가 로드 루프 → 전 세션 turn_refs 배치(`_hydrate_sessions_turn_evaluations`, 연결 1회). 싱글 헬퍼는 플러럴 위임으로 행위 보존(`_load_turn_evaluations`는 이미 `turn_id = ANY` 배치). **검증: 백엔드 352 passed. (2026-07-02)**
  - **E2E 검증(실 스택)**: dev API(8000, 내 코드 반영)+웹+DB에서 `chromium-single-run` **2 passed** — "위기→교수자 대시보드", "학습자 턴→리뷰+교수자 대시보드"(`list_all_sessions` include_turn_evaluation=True로 1·2차 N+1 경로 모두 브라우저 end-to-end). (2026-07-02)
- [ ] fast-loop `eval_hook` **사용 정책 제품 결정** (현재 주입은 됨; 켤지/끌지 확정은 소유자).
- [ ] Node 게이트웨이 구현 시: 라이브 엔드포인트 conformance, `TurnEvaluationPayload` 어댑터 추출, `admin.py` 매퍼 정리.
- [ ] init SQL과 별도의 idempotent DB migration runner 도입 (인프라 추가 — 소유자 결정 권장).

## F. 임상팀 콘텐츠  [임상] (외부 소유)
> 출처: `ops/source-docs-gap-analysis-2026-06-26.md` · 백로그 B0. 코드 구조는 선제 구축, 문안·기준은 외부 정의.

- [ ] **태깅 축어록 4종 후속 게이트** — `ops/tagged-data-utilization-2026-07-15.md` §3 소유:
  golden set P8~P11, 다회기 스키마 격상, gestalt/dbt 이론모드 신설(소유자 결정), P1~P7 보강,
  사례개념화 루브릭 draft, P8~P11 초안 검수·승인(특히 P9 자해 페르소나는 안전장치 실측 선행).

- [ ] C1 사례개념화 **확정 루브릭 콘텐츠** + AI 추출/채점 calibration (현재 scaffold_only).
- [ ] CBT 체인·이론부합 루브릭.
- [ ] 위기개입 프로토콜 임상 문안.
- [ ] 평가 골든셋 콘텐츠.

## G. 운영 후속  [구현] (비차단)
> 출처: 백로그 B1

- [ ] **운영 티켓 자동 분류·처리** — Claude Recipe headless 자동 수정 후보, 관리자 승인 후 이슈 등록·PR/작업 스레드 생성,
  처리 결과 audit trail 확장. 자동 수정은 운영자 승인 전까지 실행하지 않는다.

## H. 2026-07-13 한신대 회의 결정 구현  [구현] (파일럿 게이트 — 7월 내)
> 출처: `ops/hanshin-meeting-actions-2026-07-13.md` (요구사항 상세·완료기준은 그 문서가 소유).
> 데드라인: **7월 내 배포 → 7월 말~8월 초 파일럿(대학원생 ~20명)**. 9~10월 연구팀 점진 이관.

- [x] **P1. 회기 종료 시간 기반 전환** — 구현 완료(2026-07-14). 60분 시간 기반(`SESSION_DURATION_MINUTES`) +
  10분 전 알람 바 + 시간 만료 정리 유도 다이얼로그 + 유예(+10분) 후 서버 턴 409 거부 + 시작 전 목표 1~4개
  선택(`goal_stages` 계약, DDL·런타임 가드 포함 — 회의 권장 2개 수준, 소유자 지시 2026-07-15로 4개까지 허용).
  목표 달성해도 시간 내 계속 진행. 상태머신은 채점·표시용 유지.
  **검증**: 백엔드 pytest 393 pass, 1분 회기 실측(알람→만료 다이얼로그→409), session-layout 8/8, layout-visual-gate 12/12.
- [x] **P2. 회기 계획·달성도 게이지** — 구현 완료(2026-07-14). 설계 1p `ops/session-progress-gauge-design-2026-07-14.md`.
  단계별 누적 게이지(rapport_credit 파생, 회기 간 ×0.7 이월로 누적) + 상세 수치(방어/개방도/라포 누적+이번 회기 증가분)
  를 세션 화면·상세 응답·스트림 done·대시보드 페르소나 카드(rapport_percent)에 노출. 계획서·프로토콜 첨부는 기존
  `/personas/sources`(+신규 엑셀 업로드)로 흡수. **검증**: 2회기 carry 실측(65%→46% 시작 = ×0.7 정확).
- [~] **P3. 파일럿 인프라 대비** — 부하 검증 완료: `scripts/load-test-sessions.py`, 20 동시 세션 생성 20/20 성공
  (p95 125ms, RAG warm 병목 없음), 5 동시 실턴은 p50 55s로 **claude_cli 상주 풀이 병목** → 파일럿 전
  `ENGINE_MODE=claude_api` 전환 권고. 이관 절차 초안 `ops/server-migration-runbook-draft.md`, 파일럿 사용 지침
  `ops/pilot-usage-guide-draft.md`. **남은 것**: 실제 서버 이관(연구팀·정보처 협의) — 외부 대기.
- [x] **P4. 데이터 업로드 흐름 검증** — 자유 양식 엑셀 업로드 경로가 없어서 신규 구축(2026-07-14):
  `POST /personas/sources/upload`(xlsx/xlsm/csv → 텍스트 결정론 변환 `services/tabular_ingest.py` → 기존 마스킹·
  hash-only 증거·sanitized chunk 경로 재사용, 원본 바이트 미저장) + PersonaStudio 파일 첨부 xlsx 지원.
  **검증**: 파란 라벨 샘플 실업로드(NAME 마스킹·chunk 색인·임베딩 OK, raw hash-only 확인), 방어 테스트 9종
  (.xls 거부·cp949 폴백·손상/빈 파일) pass.
- [~] **P5. 협업 체계** — 비개발자용 가이드 `guides/collaboration-for-researchers.md` 작성 완료(문구 수정 프로세스 포함).
  **남은 것**: 저장소 초대(소유자 직접 실행).
- ⏸️ **외부 대기(구현 착수 금지)**: '실패(게임오버)' 정의 / 검수 표준화 항목 / AI 평가 노출 정책 / 페르소나 추가 제작 — 전부 연구팀 몫, 수신 시 반영.

---

## 지금 임계경로 (한 줄)
납품(공개 데모)의 핵심 블로커는 **A(공개 `/turn` proof + 배포 secrets)**. 그 다음이 **B(한신대 거버넌스)**와
**C(Phase 3 파일럿)** — C는 2026-07-13 회의로 **7월 말~8월 초 파일럿 일정 확정**, 그 전제로 **H의 P1(회기 종료 시간 기반)**이
새 구현 게이트다. D~G는 품질·확장 작업으로 게이트가 아니다. 상세 상태·검증 증거는 SSOT 대시보드가 소유한다.