vignette/docs/archive/ops/handoff-2026-06-27.md

세션 인계 — 2026-06-27 (Vignette)

다음 세션에서 아직 못한 작업을 이어가기 위한 인계 문서. SSOT는 docs/dev_dashboard.html — 최상단 "한신대 기술분석 PDF 정합성 + 이번 세션 발견" 섹션이 권위 기준.

---

0. 즉시 재개 방법

# 전체 dev 스택 기동(핫리로드 포함)
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\dev-up.ps1
# 진입점: http://localhost:5173/learn  (로그인 페이지에서 dev-login)

• 핫리로드 ON: API(8000)는 --reload(watchfiles) — apps/api/app/**.py 저장 시 자동 재기동. 웹(5173)은 Vite HMR. → 백엔드/프론트 수정이 즉시 반영(수동 재시작 불필요).
• 게이트웨이(9099)만 no-reload(상주 claude -p 세션 보존 — Windows에선 reload 시 자식 claude 고아화).
• 스택: web 5173 · API 8000(db:true·engine:true) · gateway 9099 · DB vignette-dev-db(Docker) · voice(OPENAI_API_KEY는 apps/api/.env, gitignore) · RAG(BGE-M3).

---

1. 이번 세션 완료 (커밋 085460b + 본 핸드오프 커밋, origin/master push, 검증됨)

항목	내용	검증
페르소나 격리 버그	내담자가 "저 Claude Code인데…git status" 캐릭터 붕괴 → engine_gateway/gateway.py: --append-system-prompt→--system-prompt(교체) + --exclude-dynamic-system-prompt-sections	라이브 인캐릭터 + CCD누설/탈옥 probe 차단
RAG 비차단	임베더 동기 로드(~7-13s)가 세션 생성 블로킹 → _warm_rag_caches 백그라운드 task(routes/sessions.py), 턴은 캐시만 읽음	session-layout E2E 4/4 회복
역린(逆鱗)·misconduct 반응	PersonaCard.triggers 필드(services/persona.py) + CCD 핵심상처 파생 역린 블록 + L0에 무례·모욕·조롱 시 동맹 균열 지침	무회귀 77/77, 라이브 균열 반응 확인
데드코드/리팩토링	LogHook·tier·voice RMS 힌트 제거, init_state OpennessParams 파라미터객체화	84/84
한국어 PII	날짜·금액·주소 마스킹 추가(services/guardrail.py)	6/6
RAG 활성화·C2·C3·H2·H4	(이전 라운드) 임베더 핀+배선, 위기 safety_events, 이론모드 스레딩, 턴평가, PII	라이브+84/84
대시보드	한신대 PDF 정합성 섹션 + 폴드아웃/목차 드릴다운(내용 0 축약)	렌더·폴드 검증
핫리로드 인프라	scripts/dev-up.ps1 API --reload	watchfiles 리로드 실증
E2E 종합	데스크톱 27 · 모바일 11 · 아바타 4 · 시각게이트 7/7	전부 green

---

2. 다음 세션에서 이어갈 것 (우선순위)

🔴 CRITICAL — PDF가 "통과·납품 필수조건/법적 생존선"이라 명시

(A) 위기 안전게이트 (CrisisGate, 109) — 착수 직전까지 조사함

• PDF(9·16·18쪽): 자해·자살 감지 시 ① 대화 중단 ② 자살예방상담 109 안내 ③ 지도교수 자동 알림, 안전은 LLM 밖 별도 게이트.
• 현 상태(조사 완료):
  • 분류·적재는 있음 — guardrail.classify_crisis(LEARNER_REAL/escalate), routes/sessions.py:694 _record_safety_event가 app.safety_events 적재(C2). 턴 응답에 crisis_kind(L60)·safety_flagged 존재.
  • 프론트 pages/Session.tsx:700,994가 safety_flagged 시 일반 안내 문구만 표시.
  • 빠진 것: ① 핫라인 번호가 코드 어디에도 없음(추가할 번호 = 109, 2024.1 1393·1577 통합) ② 위기 시 대화 중단/일시정지 흐름 ③ 109 자원 카드 UI ④ 지도교수 실시간 알림(safety_events는 레코드일 뿐, push 없음).
• 착수안: guardrail.py에 CRISIS_RESOURCE(109 + 안내문) 상수 → escalate 시 TurnResponse에 crisis_resource 노출 → Session.tsx에 위기 개입 카드(109·"지도교수 알림 전송됨"·머무르기/일시정지). LLM 밖 분기 유지.

(B) 교수자 학습자 이력·성장 추적 UI/UX

• PDF 핵심 루프: 학습자 반복 연습 → 교수자가 학습자별 이력·성장곡선(이론부합도·자신감·숙련도, '연습 전·후' 비교)·항목별(공감·질문·정상화·이론부합) 추이 검수. 현 교수자 콘솔은 회기 목록 수준 — 가시화·검수 동선 부재. 데이터(H2 평가)는 쌓이는데 안 보임.
• 착수안: 교수자 = 학습자별 대시보드(회기 타임라인·4항목 추이·전후 비교·역린/위기 플래그). 학습자 = 성장곡선 + 회기 리뷰 누적.

🟡 중기

• 2-tier 모델: 고성능(Claude·GPT=내담자발화·실시간평가)/저비용 한국어(Solar=단순응답·사후요약) + 캐싱. ENGINE_MODE 라우팅으로 점진. 벤더중립 인터페이스는 이미 있음.
• 백엔드 언어(소유자 결정): PDF는 Node.js 우선(팀 보유기술·5개월 일정)/Spring 대안. 현재 Python/FastAPI — 재작성은 일정·인력 리스크. 임의 결정 금지.

🟫 임상팀 소유 (위조 금지 — doc3 R&R)

• C1 사례개념화 워크시트 항목·루브릭, CBT 이론별 단계 프롬프트 체인, 위기 스크립트·생명유지서약 문안, H2 평가 골든셋. → 구조/폼만 선제 구축, 콘텐츠는 임상팀(구훈정·어유경).

⚪ hygiene (#3 잔여, 저위험)

• prepare_turn TurnMemory 파라미터객체, 턴 처리 REST/WS 중복 → 공통 record_completed_turn 추출, upsert_managed_user ManagedUserInput. 스테이징: docs/ops/refactor-rag-patches-2026-06-26.{md,json}.

---

3. 한신대 기술분석 PDF 핵심 (다음 세션 참조)

• AI 피드백이 효과의 핵심 — Stanford RCT(94명): 피드백 없는 연습은 공감 역효과. 4항목(공감·질문·정상화·이론부합) 점수+근거, JSON Schema 강제(현재 evaluator._fast/_deep_schema로 정렬됨 ✓).
• '저항·반응 조절'이 우리만의 핵심 차별 기술 — 역린/triggers가 이 축을 강화(이번 세션 착수).
• '교육용(비의료)' 포지션이 생존선 — 치료·진단 표현 배제, AI 평가는 교수자 검토용 보조지표.
• 본선 모델 1개 + 벤더중립 교체구조, 위기대응은 LLM 밖, RAG·대화기억 분리.
• 원본: C:\Users\encep\Dropbox\Obsidian\Yun Chan Repository\Projects\영업\2026\한신대학교 산학협력 프로젝트\한신대_AI상담플랫폼_기술분석.pdf(19쪽).

---

4. ⚠️ 주의 — 병렬 세션(아바타) 미커밋 작업

서연 아바타 작업이 별도 세션에서 동시 진행 중. 다음 파일들은 그 세션 소유이며 미커밋 상태로 두었다(건드리거나 git add -A로 쓸어담지 말 것):

• apps/web/public/avatar/seoyeon/parts/*.png, apps/web/src/components/avatar/RasterBust.tsx, docs/avatar-art/seoyeon/*
• 핸드오프: docs/ops/handoff-avatar-seoyeon-2026-06-27.md

커밋 시 경로를 명시(git add scripts/... docs/ops/...)해 아바타 작업과 분리한다.