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

한신대 산학협력(구훈정 교수) 원천문서 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. C1의 "구조 전무"와 저장형 제출물 부재는 2차로 해소됐고, 임상 루브릭·AI 채점·교수자 검수는 계속 추적한다. ✓는 작성자가 코드 grep으로 직접 재확인한 항목, (분석)은 분석 결과로 착수 전 코드 1차 재확인 권고.

Critical (3)

ID	갭	현재상태	권고	근거
C1	사례개념화·치료계획 산출물 저장형 구조 2차 구현·채점/검수 잔여	`SessionReviewResponse.caseWorksheet`가 축어록 근거 기반 초안을 제공하고, 리뷰 화면에서 학습자가 편집한 워크시트를 `PUT /sessions/{id}/review/worksheet`로 `app.case_worksheet`에 저장한다. 이후 `GET /review`는 `saved_by_learner` 저장본을 자동 초안보다 우선 반환한다. CCD는 숨은 정답키로 남고 저장본에 점수로 노출하지 않는다.	AI 축어록 초안 추출 고도화, 규칙 기반 채점, 교수자 검수 플로우. 루브릭은 임상팀 외부 정의 가능하게 외부화.	doc1·doc4·doc5
C2	위기개입 프로토콜·생명유지서약·에스컬레이션 1차 배선 완료·임상 고도화 필요	실제 자해·자살 신호는 LLM/엔진 호출 전 중단하고 109 리소스와 `conversation_stopped`를 REST/SSE/voice 응답에 싣는다. `crisis.risk_level`은 상태머신 `ideation_observed`로 전달하고, escalate 시 `app.safety_events` detail 적재 및 교수자 대시보드 안전 알림 큐로 연결한다.	남은 것은 임상팀 콘텐츠: 비밀보장 예외고지→단계적 탐색→생명유지서약 스크립트, 실시간 push/메일 알림 정책, 위기탐색 누락 시 회기리뷰 감점 루브릭.	doc1·doc5(핵심 시나리오)·doc4(IRB 전제)
C3	이론모드 1차 배선 완료·CBT 콘텐츠/선택 UI 잔여	`TurnContext`/`prepare_turn`/sessions/voice/evaluator에 `theory_mode`가 전달되고, `build_turn_messages`도 인간중심·CBT·통합 이론 프레이밍을 엔진 메시지에 넣는다. 프론트는 `persona.theory_target` 기준으로 시작해 기존 `humanistic` 하드코딩을 제거했다.	임상팀이 확정한 CBT 단계 프롬프트 체인, 이론부합 채점 루브릭, 학습자/교수자용 명시적 이론 선택 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	턴별 fast-loop + 라이브 코칭 1차 가동·골든셋/리뷰 2열 UI 잔여	`make_eval_hook`이 submit/voice 생성 경로에 주입되고, stream은 `_evaluate_stream_turn`으로 fast-loop 평가를 붙인다. 결과는 `feedback_scores`, `alternative_utterance` 등 정규화 테이블에 적재·hydrate된다. 추가로 `app/services/live_coach.py`, `POST/GET /sessions/{id}/live-coach`, `POST /kb/live-coach/source-packs/sync`, `app.live_coach_events`, `data/kb/live_coaching_workbook_0615.json`, `data/kb/live_coaching_sources/*.json`을 연결해 워크북·DSM·공식 지침 요약 기반 코칭 아바타 말풍선·근거 모달·발화별 이력 오버레이와 RAG 증분 색인을 제공한다.	회기리뷰 UI 좌(축어록 타임라인+비언어)/우(기법·적절성·대안반응·이론) 2열 고도화, 원천 축어록 few-shot 골든셋 적재, 임상팀 확정 루브릭과 source pack 버전·citation 운영정책 보강.	doc2·doc5(골드 포맷)
H3	임상팀 콘텐츠 입력 경로(페르소나 저작 CRUD) 2차 구현·임상 검수 잔여	draft 생성·조회·편집·검수요청 API와 교수 콘솔 JSON 초안 패널은 연결됐다. `persona_repository.py`는 in-code `SEED_PERSONAS`(P1~~P3)와 `data/personas/P4.json`~~`P7.json`을 `PersonaCard`로 합쳐 `materialize_seed_personas()`와 seed fallback catalog에 포함한다.	JSON 대신 항목형 저작 UI, 루브릭·이론 콘텐츠 외부화, P4~P7 포함 임상팀 최종 검수/서면 evidence 확보.	doc3(R&R)·doc4(페르소나=전문가 산출물)
H4	PII 마스킹 한국어 이름/기관 NER + 온보딩·동의 게이트 잔여	Presidio `language='en'` 고정이라 이름/기관명은 NER 보강이 필요하지만, 한국어 날짜·금액·행정구역 주소 정규식 폴백은 추가됐다. 외부 LLM 호출은 상담 생성(generate/stream)·fast/deep 평가 직후 `audit.llm_call_log`에 provider/model/token/cost/inference_geo/latency만 적재하도록 연결했고, prompt/completion 본문은 저장하지 않는다. 로컬 dev-login 실제 `/turn` smoke에서 `audit.llm_call_log` 3행 증가를 확인했다. `app_user`에 이름·소속·학과·학년/직위·연락처·주소/수령지·닉네임·자기소개·아바타 URL·약관/개인정보 동의 버전 필드를 추가했고, 로그인 직후 `/onboarding` 완료 전에는 역할 홈과 learner 회기 시작을 막는다. 아바타 이미지는 `/users/me/avatar`에서 MIME/시그니처/3MB 제한 후 파일 저장소에 두고 URL만 보관한다. 온보딩 저장 시 learner `consent_at`도 함께 세팅하며 auth E2E에서 신규 계정 온보딩→아바타 업로드→학습자 홈 이동을 검증했다.	한국어 이름/기관 NER 추가, 미성년/guardian 및 법무 검토가 필요한 최종 서명 동의서·개인정보 처리방침·약관 evidence 확보. 공개 Google OAuth 실제 `/turn` proof는 별도 운영 게이트.	doc1/2/5(실명·날짜·미성년·자살시도 다수)·doc4(IRB·개인정보)

Medium+ (6) — M1M3, X1X2, L1

ID	갭	현재상태	권고
M1	비언어/준언어 임상 이벤트 캡처·태깅 부재	`voice.py`는 EOT용 `silence_ms`만, 침묵·한숨·울음 타임스탬프 이벤트 캡처·리뷰 표시 전무. 서버 RMS 힌트 프론트 미사용(dead). (분석)	침묵·한숨·울음을 타임스탬프 메타 이벤트로 보존·시각화, '침묵 견디기'를 역량 지표화, 페르소나 의도적 침묵·비유창 한국어 렌더링.
M2	다회기 종단 케이스 아크·교차회기 사례개념화 부분 구동	1차로 `(persona_id, learner_id)` 안정 `case_profile` upsert, 원자적 `session_no`, 직전 `session_summary` 기반 seed recall, voice/REST/SSE recall cache 주입을 연결했다. `case_digest`/`pinned_fact` 실적재, episodic embedding writer, trajectory 갱신은 아직 없다.	case_state 런타임 보강, pinned_fact·case_digest 압축/갱신, 접수면접→다회기 연속성·자기개념 진화 실증.
M3	SSO claim 매핑·식별자 안정성 1차 완료·운영 IdP 감사 미연결	Google/SAML/dev-login이 `AUTH_EMAIL_COHORT_MAP`·`AUTH_DOMAIN_COHORT_MAP` 및 SAML cohort claim을 `cohort_ids`로 전달하고, `app_user.external_id`는 provider subject(`google:`/`saml:`/`dev:`) 기반으로 저장한다. 운영 SAML 서명검증, 기관 claim schema/test tenant, deprovisioning audit은 아직 없다.	한신 IdP 확정 후 SAML 서명검증, claim→role/cohort/institution_user_id 매핑 표 실연동, role변경/삭제 audit, deprovisioning evidence.
X1	재귀학습·데이터셋 export 파이프라인 1차 구현	`scripts/export-recursive-dataset.py`와 `app.services.dataset_export`로 masked-text JSONL dry-run, PII scan, kappa/ICC 계산, approved export 게이트를 구현했다. 기본은 `technical_dry_run`이며 실제 승인 export·골든셋 승격은 데이터 steward/legal review와 IAA 통과가 필요하다.	파일럿 evidence에서 reviewer disposition, steward/legal 승인, gold annotation 라운드 적재 후 `approved_for_recursive_learning_seed` 승격 검증.
X2	AI API 비용 관측·예산 경고 1차 완료·평가 저비용 라우팅 1차 완료	턴별 provider/model/tokens/cost 저장 경로와 `GET /admin/usage`, 관리자 비용 대시보드를 연결했다. `ADMIN_USAGE_BUDGET_USD` 기준 예산 상태(ok/warn/exceeded)도 응답/UI에 표시한다. `EVALUATOR_FAST_MODEL`/`EVALUATOR_DEEP_MODEL` 설정 시 fast/deep 평가 호출만 해당 모델 override로 gateway에 전달하고, 비워두면 기존 gateway default 라우팅을 유지한다. DB 미가용 dev는 runtime store fallback, prod는 fail-closed다. 캐싱은 L0~L2 cache hint와 gateway session reuse까지만 연결돼 있고 semantic cache·장기 한도 정책은 아직 없다.	semantic cache, 장기 비용 추이/한도 정책, 운영 모델별 비용 검증.
L1	기술스택 신청서-구현 불일치 및 단기일정 산출물 압박	doc4 신청서 스택(Spring Boot 3/Node.js·TimescaleDB) vs 실제 FastAPI/Python 불일치, 20주 단기일정·9월 저작권 등재 압박.	스택 정합 또는 변경 사유를 거버넌스 회의록으로, 9월 저작권 등재 문서화 수준을 일정 반영.

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

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

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

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

C1 2차 완료: caseWorksheet 응답 구조, 리뷰 화면 편집 UI, app.case_worksheet 저장/재조회 경로. 후속은 임상 루브릭·AI 추출/채점·교수자 검수.
C2 1차 완료: 위기 신호는 엔진 전 중단, 109 안내, safety_events 적재, 교수자 알림 큐, ideation_observed 전달까지 배선했다. 후속은 임상 스크립트·서약 문안·감점 루브릭.
C3 1차 완료: theory_mode가 세션·평가·생성 프롬프트까지 흐른다. 후속은 임상팀 CBT 체인·이론부합 루브릭·명시적 선택 UI.
H2 1차+라이브 코칭 완료: make_eval_hook과 stream 평가가 턴 파이프라인에 붙고 정규화 테이블로 적재·복원된다. 대안발화도 app.alternative_utterance로 정규화한다. 라이브 코칭은 0615 워크북·DSM·공식 지침 요약/RAG 근거로 코칭 아바타 말풍선·근거 모달·발화별 이력 오버레이까지 연결했다. POST /kb/live-coach/source-packs/sync로 같은 source pack을 evaluator 전용 RAG에도 증분 색인한다. 후속은 2열 리뷰 UI·골든셋·임상팀 루브릭·source pack 버전 운영.
H3 2차 완료: 페르소나 저작 CRUD(draft→review)와 P4~P7 저장소 JSON 로드 경로가 붙었다. 후속은 항목형 저작 UI, 루브릭·이론 콘텐츠 외부화, 임상팀 최종 검수 evidence.
H4(부분)·X1·X2: 마스킹 한국어 정규식 보강, 외부 LLM 호출 metadata-only audit.llm_call_log 적재 경로, 학습자 동의 수락/철회/회기 시작 하드게이트 골격은 완료했다. 한국어 이름/기관 NER와 guardian/legal 서명 evidence는 후속이다. dry-run JSONL export·PII scan·IAA 계산 1차도 완료했고 ds.* write는 --write-dataset 명시 시에만 수행한다. X2 비용 관측·예산 경고와 evaluator fast/deep 모델 override 1차는 완료했고 semantic cache·장기 한도 정책은 후속. M1/M2도 1차 구현 완료, provider 기반 비언어 감지와 case_digest/pinned_fact 실적재는 후속.

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

임상팀(구훈정·어유경) 산출물: C1 채점 루브릭·항목 확정, C3 CBT 이론 콘텐츠·프롬프트 체인, C2 위기 스크립트·서약 문안, H2 골든셋 코딩·라이브 코칭 루브릭 검수. DSM/공식 지침/논문은 사용 허가 확인 기준으로 KB 확장 가능하며, 각 source pack은 version/citation/임상 검수 상태를 남긴다. → 코드는 구조를 선제 구축하되 임상 문안과 평가기준은 외부 정의로 받는다.
소유자 평가설계 결정: H1 실험/통제군 배정·3척도 문항·50분 흐름. κ/ICC·환각률 목표는 doc4 미명시 → 평가설계 문서 확정.
기관(한신 IT) 의존: M3 SSO IdP 프로토콜·test tenant·claim 스키마, SAML 인증서, deprovisioning 거버넌스 증거.
거버넌스 결정: L1 스택 정합성 처리 방향, 저작권 등재 문서화 수준, IP 협의.

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

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

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

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

# C1: 사례개념화 워크시트 저장형 구조와 잔여 채점/검수 경로 확인
rg -n "caseWorksheet|ReviewCaseWorksheet|case_worksheet|save_session_review_worksheet|사례개념화 워크시트|인지삼제|4사분면" apps infra

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

# C3: 이론모드 스레딩과 생성 프롬프트 주입 확인
rg -n "theory_mode|THEORY_MODE_GUIDANCE|sessionApi.start\\(personaCode" apps

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

# H3: 페르소나 seed/materialize 로드 경로
rg -n "SEED_PERSONAS|load_file_personas|built_in_personas|materialize_seed_personas" apps/api/app/persona_repository.py

검증 명령 (변경 후)

# 백엔드 (작업 디렉터리 apps/api)
python -m pytest app/ -q            # 현재 118 pass
python -m pytest engine_gateway/ -q # 현재 11 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·M3은 구현 후 재검증 완료 기준이다. 그 외(H1·H4·M1·M2·X1·X2·L1)는 착수 전 코드 1차 재확인 권고.

변경 이력

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

20 KiB Raw Blame History