vignette/docs/guides/source-docs-and-gaps.md

원천문서·갭 로드맵 가이드

한신대 산학협력(구훈정 교수) 원천문서 5종과 거기서 도출된 **갭(부족분)**의 인덱스/로드맵을 한 장으로 정리한 가이드다. 갭 항목의 상세 근거는 docs/ops/source-docs-gap-analysis-2026-06-26.md에, 상태·결론의 권위 기준(SSOT)은 docs/dev_dashboard.html의 "원천문서 갭 분석" 섹션에 있다. 이 가이드는 그 두 산출물을 요약·링크한다.

---

0. 이 문서를 읽는 법 (3분)

• 무엇인가: Vignette(AI 심리상담 시뮬레이션 훈련 플랫폼)가 산학협력 원천문서가 요구하는 임상 사양 대비 어디가 비어 있는지를 심각도(critical/high/medium+)로 분류한 인덱스다.
• 왜 있는가: 어떤 갭이 "코드만 고치면 되는 것"이고, 어떤 갭이 "임상팀/기관/소유자 결정이 선행돼야 하는 것"인지 구분해 착수 순서를 정하기 위함이다.
• 권위 순서(SSOT):
  1. docs/dev_dashboard.html → "원천문서 갭 분석 (2026-06-26)" 섹션 = 상태·결론의 단일 진실원천(SSOT).
  2. docs/ops/source-docs-gap-analysis-2026-06-26.md = 그 SSOT 항목의 상세 근거(원천문서 요지·항목별 근거·검증 메모).
  3. 이 가이드 = 위 둘의 요약 + 빠른 진입 인덱스.
• 핵심 R&R 한 줄: 콘텐츠(워크시트 문항·채점 루브릭·이론 프롬프트·위기 스크립트·골든셋)는 임상팀(구훈정·어유경) 소유, 기술팀은 "편집 가능한 구조"만 선제 구축한다. (출처: doc3 회의록 R&R)

원천 산출물 바로가기

산출물	경로	역할
갭 상세 분석	docs/ops/source-docs-gap-analysis-2026-06-26.md	원천문서 요지·항목별 근거·직접검증 메모·판독 한계
SSOT 대시보드	docs/dev_dashboard.html (# "원천문서 갭 분석" 섹션)	상태·우선순위의 권위 기준, 갭 요약 카드
데이터 거버넌스 게이트	docs/ops/hanshin-data-governance-gate.md	H4/M3 관련 거버넌스
백로그	docs/ops/backlog-2026-06-26.md	실행 작업 목록
레이아웃 핸드오프	docs/ops/layout-redesign-handoff-2026-06-26.md	UI 재설계 맥락

---

1. 원천문서 5종 (한신대 산학협력 · 구훈정 교수)

5종 문서를 PDF로 변환해 시각 정독(에이전트 1/문서)하고 Vignette 코드베이스 4개 도메인을 교차 조사한 뒤, 1차 종합 → 적대적 비평 → 최종 재구성한 결과다(워크플로우 source-docs-gap-analysis, 에이전트 12, 토큰 약 1.11M).

ID	문서	핵심 함의(Vignette 그라운드 트루스)
doc1	청소년·대학생 사례 워크북(3·4장)	첫 회기 축어록→사례개념화→목표·전략 표준 분석틀 + 두 사례(비자발 청소년/자발 대학생). 페르소나 완성형 스펙, openness 곡선 정량 근거, 위기 프로토콜, 다회기 아크(2~10회기), 회기리뷰 주석 포맷의 기준점.
doc2	인간중심접근 사례·프로토콜(4장)	미혼모 3회기 상담의 인간중심 사례개념화 정답지. theory_mode=humanistic 1급 필드, 공감·반영 정확도 기반 openness, 회기리뷰 채점 루브릭의 직접 근거.
doc3	산학협력 회의록(2026-06-08)	3주체(임상팀 구훈정·어유경 / 트웬티온스 / 사업단 김시윤) 협력·거버넌스 확정. R&R: 콘텐츠·평가기준=임상팀 소유, 구현=기술팀. 평가 루브릭은 임상팀이 외부 정의·수정 가능해야 함. AI API 비용을 운영 리스크로 명시.
doc4	산학협력 신청서(공식 계약)	기간(2026.5.18~9.30, 20주)·예산·평가지표·산출물·서약의 권위 원천. humanistic+CBT 2종 필수 이론을 '단계적 프롬프트 체인'으로 계약, 3척도 사전사후·20명 실험/통제군·단회기 50분, 9월 저작권 등재, IRB 100% 준수. 기술스택 명시(Spring Boot 3/Node.js·TimescaleDB — 실제 FastAPI/Python과 불일치).
doc5	사례개념화 워크북(3장, 상호작용 분석 추가본)	비자발 청소년(자살사고) 축어록(상1~63)에 기법 코딩. 회기리뷰 루브릭·기법 코딩 택소노미(κ/ICC 스킴)·페르소나 사양·종결 규칙의 직접 근거.

주의(doc4 KPI 범위): κ/ICC·환각률은 신청서 본문에 미명시('정량 신뢰도 확보' 수준). 계약 확정 지표로 단정하지 말 것 — 별도 평가설계 문서로 확정 필요.

---

2. 갭 로드맵 — 심각도 우선순위

심각도 분류: critical 3 / high 4 / medium+ 6. ✓는 작성자가 코드 grep으로 직접 재확인한 항목, (분석)은 분석 결과로 착수 전 코드 1차 재확인 권고.

Critical (3)

ID	갭	현재상태	권고	근거
C1	사례개념화·치료계획 산출물 구조 전면 부재	cognitive_triad/case_conceptual/인지삼제/4사분면/quadrant grep 0건 ✓. CCD는 숨은 정답키일 뿐 학습자 산출물 폼이 아님.	워크시트 스키마(11탐색항목·호소 5영역·인지삼제·1·2차감정·보호/방해 4사분면·생물심리사회 목표) 입력 폼 + AI 축어록 초안 추출 + 규칙 기반 채점. 루브릭은 임상팀 외부 정의 가능하게 외부화.	doc1·doc4·doc5
C2	위기개입 프로토콜·생명유지서약·에스컬레이션 미구현	escalate=True 시 client stream 이벤트(StreamEvent("safety"))만, safety_events DB 적재·교수자 알림 코드 없음 ✓. prepare_turn이 risk_level을 상태머신 ideation_observed로 미전달.	위기 분기 상태(예외고지→단계적 탐색→서약)를 상태머신에 추가, escalate 시 safety_events insert+교수자 알림, 위기탐색 누락 시 회기리뷰 감점, ideation_observed 전달.	doc1·doc5(핵심 시나리오)·doc4(IRB 전제)
C3	이론모드 미주입 + CBT 콘텐츠 자체 부재	build_turn_messages 시그니처에 theory 인자 없음 + apps/web/src/pages/Session.tsx:589 sessionApi.start(personaCode, "humanistic") 하드코딩 ✓. CBT 프롬프트 체인·이론부합 루브릭 전무.	theory 인자 + 이론별 단계 프롬프트 체인(공감·반영 / 인지재구조화·행동활성화) + 프론트 이론 선택 UI + 이론 부합도 루브릭.	doc4(humanistic+CBT 필수)·doc2/doc5

High (4)

ID	갭	현재상태	권고	근거
H1	계약 평가 KPI(자기효능감·기술숙련도·수련만족도 사전사후) 수집·집계 전무	자기효능감/사전사후/수련만족/실험통제군 grep 0건. Phase3 KPI도 report shape만, 계산 코드 0줄. (분석)	3척도 pre-post 폼·실험/통제군 배정·자동누적 대시보드·추이 시각화·검정 계산 코드. (κ/ICC·환각률은 doc4 미명시 → 평가설계 확정.)	doc4(20명 실험/통제군·단회기 50분·3척도 pre-post)
H2	턴별 회기 리뷰(상호작용 분석 2열) 미가동	make_eval_hook은 apps/api/app/services/evaluator.py:738에 정의·export됐으나 routes/에서 주입 0건 → 턴별 fast-loop 미동작(회기종료 deep-loop만) ✓. few-shot 골든셋 기본 OFF.	eval_hook을 turn 파이프라인에 주입. 회기리뷰 UI 좌(축어록 타임라인+비언어)/우(기법·적절성·대안반응·이론) 2열. 원천 축어록을 채점 few-shot 골든셋으로 적재.	doc2·doc5(골드 포맷)
H3	임상팀 콘텐츠 입력 경로(페르소나 저작 CRUD) 부재 + P4~P7 미적재	personas 라우트에 검수 승인/반려만, draft 생성·편집 API 없음. persona_repository.py는 in-code SEED_PERSONAS(P1~P3)만 materialize, 외부 JSON 미로드 ✓.	페르소나 저작 CRUD(draft→review) + P4~P7 적재, 루브릭·이론 콘텐츠를 임상팀 편집 가능 데이터로 외부화.	doc3(R&R)·doc4(페르소나=전문가 산출물)
H4	PII 마스킹 한국어 공백 + 외부전송 관측 부재	Presidio language='en' 고정으로 한국어 이름/주소/기관 미탐지(폴백은 번호·이메일만). audit.llm_call_log 0행(런타임 미관측). consent_at 컬럼만, 동의 수집/게이트/철회 엔드포인트 전무. (분석)	한국어 PII 탐지 추가, 마스킹 미들웨어 하드게이트화, llm_call_log 적재로 런타임 관측, 미성년/guardian 동의 수집·게이트·철회.	doc1/2/5(실명·날짜·미성년·자살시도 다수)·doc4(IRB·개인정보)

Medium+ (6) — M1M3, X1X2, L1

ID	갭	현재상태	권고
M1	비언어/준언어 임상 이벤트 캡처·태깅 부재	voice.py는 EOT용 silence_ms만, 침묵·한숨·울음 타임스탬프 이벤트 캡처·리뷰 표시 전무. 서버 RMS 힌트 프론트 미사용(dead). (분석)	침묵·한숨·울음을 타임스탬프 메타 이벤트로 보존·시각화, '침묵 견디기'를 역량 지표화, 페르소나 의도적 침묵·비유창 한국어 렌더링.
M2	다회기 종단 케이스 아크·교차회기 사례개념화 미구동	case_state.ccd_estimate/presenting_arc/alliance_level 스키마만, build_recall_context() 빈 컨텍스트 반환. 음성 경로 빈 RecallContext. (분석)	case_state 런타임 구동, build_recall_context 실제 회상/pinned_fact 주입, 접수면접→다회기 연속성·자기개념 진화.
M3	SSO claim 매핑·식별자 안정성·deprovisioning 감사 미연결	Google/SAML 콜백 cohort_ids=[] 하드코딩, role이 email allowlist, external_id가 email:{} 파생(불안정). SAML 서명검증 미구현. role변경/삭제 audit 미기록. (분석)	claim→role/cohort/institution_user_id 매핑+안정 식별자(sub/NameID), SAML 서명검증, deprovisioning audit, 한신 IdP 확정·외부 증거 수급.
X1	재귀학습·데이터셋 export 파이프라인 미구현	ds.* 스키마(κ/ICC 컬럼)만, read/write 코드 0건. JSONL export·IAA 게이트·골든셋 승격 미코딩. (분석)	JSONL export 잡, IAA 게이트(κ≥0.6/ICC≥0.75), 골든셋 승격.
X2	AI API 비용 관측 부재	게이트웨이 토큰 텔레메트리 0 고정, cost 모니터링·캐싱 부재. (분석)	토큰 텔레메트리 실측, 저비용 모델 분기·캐싱, 비용 대시보드.
L1	기술스택 신청서-구현 불일치 및 단기일정 산출물 압박	doc4 신청서 스택(Spring Boot 3/Node.js·TimescaleDB) vs 실제 FastAPI/Python 불일치, 20주 단기일정·9월 저작권 등재 압박.	스택 정합 또는 변경 사유를 거버넌스 회의록으로, 9월 저작권 등재 문서화 수준을 일정 반영.

X2 근거: doc3 회의록이 'AI API 비용'을 운영 리스크로 명시.

---

3. R&R — 누가 무엇을 소유하는가

원칙(doc3 회의록): 콘텐츠는 임상팀 소유, 코드는 "편집 가능 구조"만 선제 구축. 코드와 콘텐츠를 한 PR에 섞지 말 것 — 구조(스키마·폼·주입 경로)는 기술팀이 먼저 만들되, 그 안에 들어갈 임상 문안은 임상팀이 데이터로 채운다.

A. 즉시 착수 가능 (내부 코드, 외부 합의 불요)

• C2 배선: escalate 시 safety_events insert + ideation_observed 전달.
• C3 골격: theory 인자 추가 + Session.tsx:589 하드코딩 제거 + 프론트 이론 선택 UI 골격.
• H2 배선: make_eval_hook을 turn 파이프라인에 주입(이미 정의·export됨, evaluator.py:738).
• H3: 페르소나 저작 CRUD(draft→review) + P4~P7 로드 경로.
• H4(부분)·M1(부분)·M2·X1·X2: 마스킹 한국어 설정·하드게이트, 비언어 메타 이벤트 보존, build_recall_context 구현, ds.* read/write·export, 토큰 텔레메트리.

B. 소유자 결정 / 외부(임상팀·기관) 의존

• 임상팀(구훈정·어유경) 산출물: C1 워크시트 항목·채점 루브릭, C3 CBT 이론 콘텐츠·프롬프트 체인, C2 위기 스크립트·서약 문안, H2 골든셋 코딩. → 코드는 '편집 가능 구조'만 선제 구축.
• 소유자 평가설계 결정: H1 실험/통제군 배정·3척도 문항·50분 흐름. κ/ICC·환각률 목표는 doc4 미명시 → 평가설계 문서 확정.
• 기관(한신 IT) 의존: M3 SSO IdP 프로토콜·test tenant·claim 스키마, SAML 인증서, 거버넌스 증거.
• 거버넌스 결정: L1 스택 정합성 처리 방향, 저작권 등재 문서화 수준, IP 협의.

---

4. 작업 시작 절차 (체크리스트)

특정 갭(예: C2)에 착수하기 전에:

1. SSOT 확인: docs/dev_dashboard.html의 "원천문서 갭 분석" 섹션에서 해당 항목의 최신 상태/우선순위를 본다.
2. 상세 근거 확인: docs/ops/source-docs-gap-analysis-2026-06-26.md의 동일 ID 항목에서 근거·권고·소유 구분(A/B)을 본다.
3. 코드 1차 재확인: (분석) 표기 항목은 착수 전 grep으로 현재상태를 직접 재확인한다(아래 예시).
4. 소유 구분 판정: 콘텐츠가 필요한가? → 임상팀 핸드오프 선행. 구조/배선만인가? → 즉시 착수(섹션 3-A).
5. 검증 게이트 통과: 변경 후 표준 테스트를 돌린다(아래 명령).

코드 재확인 grep 예시 (저장소 루트 D:/workspace/vignette)

# C1: 사례개념화 구조 존재 여부 (현재 0건이어야 함)
rg -n "cognitive_triad|case_conceptual|인지삼제|4사분면|quadrant" apps

# C2: escalate 시 safety_events 적재 여부
rg -n "safety_events|escalate|ideation_observed" apps/api/app/services/orchestrator.py

# C3: 이론모드 하드코딩 위치
rg -n "humanistic" apps/web/src/pages/Session.tsx apps/api/app/services/persona.py

# H2: eval_hook 정의 vs 주입
rg -n "make_eval_hook" apps/api/app

# H3: 페르소나 SEED(P1~P3) 한정 여부
rg -n "SEED_PERSONAS" apps/api/app/persona_repository.py

검증 명령 (변경 후)

# 백엔드 (작업 디렉터리 apps/api)
python -m pytest app/ -q            # 현재 77 pass
python -m pytest engine_gateway/ -q # 현재 7 pass

# 프론트 (작업 디렉터리 apps/web)
npm run typecheck
npm run build                       # vite
npm run e2e                         # Playwright — web+api+DB 스택 필요

로컬 기동: API는 apps/api에서 python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload(pydantic-settings가 apps/api/.env 자동 로드, DB 미가용 시 in-memory degraded 폴백). 웹은 apps/web에서 npm run dev(http://localhost:5173, /api→127.0.0.1:8000 프록시). AI 턴 생성은 ENGINE_MODE=claude_cli일 때 engine_gateway가 포트 9099에 떠 있어야 한다.

---

5. 판독 한계 (정직성)

• 핵심 축어록 2단 표(doc5 상1~63, doc2 3회기 표)는 txt 추출 시 일부 누락 — PDF 시각 판독이 1차 근거.
• OCR 잔재·오탈자 존재(doc1·doc5). 의미는 시각 보정했으나 일부 표현 불확실.
• doc4 κ/ICC·환각률은 신청서 본문 미명시 — 계약 확정 지표로 단정 금지.
• doc4/doc3 행정 불일치(참여교수 1명 vs 2명, 서식 연도 '2025' 오기, 연구책임자 표기 불일치, 트웬티온스 성명 공란).
• '현재상태'는 grep/코드 사실 기반 적대적 비평 인용. C1·C2·C3·H2·H3은 작성자 직접 재확인(✓), 그 외(H1·H4·M1~M3·X1·X2·L1)는 착수 전 코드 1차 재확인 권고.

---

변경 이력

• 2026-06-26: 초판. docs/ops/source-docs-gap-analysis-2026-06-26.md와 SSOT 대시보드 "원천문서 갭 분석" 섹션을 요약·인덱스화.