vignette/docs/ops/source-docs-gap-analysis-2026-06-26.md

# Vignette 원천문서 갭 분석 종합 (2026-06-26)

> **SSOT 주의**: 결론·상태의 권위 기준은 `docs/dev_dashboard.html`이다. 이 문서는 그 SSOT 항목의
> **상세 근거**다. 대시보드 "원천문서 갭" 항목과 함께 본다.

## 메타

- **원천문서 5종**(한신대 산학협력, 구훈정 교수): doc1 청소년·대학생 사례 워크북(3·4장), doc2 인간중심접근 사례·프로토콜(4장), doc3 산학협력 회의록(2026-06-08), doc4 산학협력 신청서(공식 계약), doc5 사례개념화 워크북(3장, 상호작용 분석 추가본).
- **방법**: 각 문서를 PDF로 변환해 시각 정독(에이전트 1/문서) + Vignette 코드베이스 4개 도메인 조사 → 1차 종합 → 적대적 비평 → 최종 재구성. (워크플로우 `source-docs-gap-analysis`, 에이전트 12, 토큰 ~1.11M.)
- **변환 산출물**(scratchpad): `docs-analysis/pdf/doc{1..5}-*.pdf`, `txt/*.md|txt`, `hwphtml/doc4*/`(신청서 폼 이미지). 원본 raw 결과: `tasks/wrimqxyqf.output`.

## 검증 메모 (정직성)

최종 보고서의 "현재상태"는 조사 에이전트의 grep/코드 판독을 적대적 비평이 인용한 것이다. 보고서 스스로
"착수 전 코드에서 1차 재확인 권고"라고 명시한다. **아래 핵심 주장은 작성자(메인 루프)가 직접 grep으로 재확인했다:**

| 주장 | 직접 검증 결과 |
|---|---|
| C1 사례개념화/인지삼제/4사분면 구조 부재 | `cognitive_triad/case_conceptual/인지삼제/4사분면/quadrant` grep **0건** ✓ |
| C2 위기 escalate가 safety_events 미적재 | `orchestrator.py:281` escalate 시 `StreamEvent("safety")`만 yield, DB insert·교수자 알림 **없음** ✓ (stream 신호는 존재) |
| C3 이론모드 미주입 | `services/persona.py:147 build_turn_messages` 시그니처에 `theory` 인자 **없음** + `Session.tsx:589` `"humanistic"` 하드코딩 ✓ |
| H2 턴별 평가 미가동 | `make_eval_hook` 정의·export(`evaluator.py:738`)됐으나 `routes/`에서 주입 **0건** ✓ |
| H3 페르소나 저작 경로 부재 | `persona_repository.py`는 in-code `SEED_PERSONAS`(P1~P3)만 materialize, draft CRUD·외부 JSON 로드 **없음** ✓ |

그 외 항목(H1 KPI 수집, H4 한국어 PII, M1~M3, X1~X2, L1)은 분석 결과이며 착수 전 코드 재확인 권고. doc4 KPI 범위(κ/ICC·환각률)는 신청서 본문 미명시 — 별도 평가설계 문서 근거 가능성(과대해석 금지).

---

## 1. 총평

원천문서가 요구하는 다수 차원 대비 Vignette가 **가장 부족한 핵심 3가지**:

1. **임상 산출물 구조의 전면 부재** — doc1/doc4/doc5가 1급 산출물로 요구하는 사례개념화 워크시트(11탐색항목·호소 5영역·인지삼제·1·2차 감정·보호/방해 4사분면·생물심리사회 목표)가 코드·스키마에 전무.
2. **위기개입 안전 프로토콜의 미구현** — IRB 100% 준수 전제인 비밀보장 예외 고지·자살사고 단계적 탐색·생명유지서약·에스컬레이션이 없고, escalate=True여도 safety_events 적재·교수자 알림이 없음.
3. **계약 평가 KPI 수집 체계의 부재** — doc4가 못박은 자기효능감·기술숙련도·수련만족도 3종 사전사후 비교와 20명 실험/통제군 설계가 코드에 0건.

## 2. 원천문서 5종 요지

- **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 스킴)·페르소나 사양·종결 규칙의 직접 근거.

## 3. 부족한 부분 — 심각도 우선순위

### [critical] C1. 사례개념화·치료계획 산출물 구조 전면 부재
- **근거**: doc1, doc4(mockup '상담 설정·피드백 리포트'), doc5
- **현재상태**(✓직접검증): 사례개념화/cognitive_triad/4사분면 grep 0건. CCD는 숨겨진 정답키일 뿐 학습자 산출물 폼 아님.
- **권고**: 사례개념화 워크시트 스키마(11항목/5영역/인지삼제/4사분면/생물심리사회 목표)를 입력 폼으로, AI가 축어록에서 신념·감정·욕구 초안 추출·제안, 규칙 기반 채점. 루브릭은 임상팀이 외부 설정으로 정의 가능하게 외부화.

### [critical] C2. 위기개입 프로토콜·생명유지서약·에스컬레이션 미구현
- **근거**: doc1, doc5(핵심 훈련 시나리오), doc4(IRB 전제)
- **현재상태**(✓직접검증): escalate=True 시 client stream 이벤트만, safety_events insert·교수자 알림 코드 없음. prepare_turn이 risk_level을 state_machine.evolve의 ideation_observed로 미전달.
- **권고**: (1) 위기 분기 상태(예외고지→단계적 탐색→서약 유도)를 상태머신에 추가, (2) escalate 시 safety_events insert + 교수자 알림, (3) 학습자 위기탐색 누락 시 회기리뷰 감점, (4) ideation_observed 전달.

### [critical] C3. 이론모드 미주입 + CBT 콘텐츠 자체 부재
- **근거**: doc4(humanistic+CBT 필수), doc2/doc5
- **현재상태**(✓직접검증): build_turn_messages에 theory 인자 없음, Session.tsx:589 'humanistic' 하드코딩. CBT 프롬프트 체인·이론부합 루브릭 전무.
- **권고**: theory 인자 추가 + 이론별 단계적 프롬프트 체인(공감·반영 / 인지재구조화·행동활성화) + 프론트 이론 선택 UI + 이론 부합도 스코어링 루브릭.

### [high] H1. 계약 평가 KPI(자기효능감·기술숙련도·수련만족도 사전사후) 수집·집계 전무
- **근거**: doc4(20명 실험/통제군·단회기 50분·3척도 pre-post)
- **현재상태**: 자기효능감/사전사후/수련만족/실험통제군 grep 0건. Phase3 KPI도 report shape만, 계산 코드 0줄.
- **권고**: 3척도 pre-post 폼, 실험/통제군 배정, 자동누적 대시보드, 추이 시각화, 검정 계산 코드. (κ/ICC·환각률은 doc4 미명시 — 평가설계 문서 확정 필요.)

### [high] H2. 턴별 회기 리뷰(상호작용 분석 2열) 미가동
- **근거**: doc2, doc5(골드 포맷: 기법 태깅+적절성+대안반응+이론해석)
- **현재상태**(✓직접검증): make_eval_hook 정의·export됐으나 라우트 미주입 → 턴별 fast-loop 미동작(회기종료 deep-loop만). few-shot 골든셋 기본 OFF.
- **권고**: eval_hook을 turn 파이프라인에 주입. 회기리뷰 UI 좌(축어록 타임라인+비언어)/우(기법·적절성·대안반응·이론) 2열. 원천 축어록을 채점 few-shot 골든셋으로 적재.

### [high] H3. 임상팀 콘텐츠 입력 경로(페르소나 저작 CRUD) 부재 + P4~P7 미적재
- **근거**: doc3(R&R), doc4(페르소나=전문가 산출물)
- **현재상태**(✓직접검증): personas 라우트에 검수 승인/반려만, draft 생성·편집 API 없음. persona_repository는 in-code SEED(P1~P3)만, 외부 JSON 미로드.
- **권고**: 페르소나 저작 CRUD(draft→review)와 P4~P7 적재, 루브릭·이론 콘텐츠를 임상팀 편집 가능 데이터로 외부화.

### [high] H4. PII 마스킹 한국어 공백 + 외부전송 관측 부재
- **근거**: doc1/2/5(실명·날짜·장소·금액·미성년·자살시도 다수), doc4(IRB·개인정보)
- **현재상태**(분석): Presidio language='en' 고정으로 한국어 이름/주소/기관 미탐지, 폴백은 번호·이메일만. audit.llm_call_log 0행(런타임 미관측). consent_at 컬럼만, 동의 수집/게이트/철회 엔드포인트 전무.
- **권고**: 한국어 PII 탐지 추가, 마스킹 미들웨어 하드게이트화, llm_call_log 적재로 런타임 관측, 미성년/guardian 동의 수집·하드게이트·철회.

### [medium] M1. 비언어/준언어 임상 이벤트 캡처·태깅 부재
- **근거**: doc1/2/5(침묵 초·한숨·울음·떨림을 1급 단서)
- **현재상태**(분석): voice.py는 EOT용 silence_ms만, 한숨/울음/침묵 타임스탬프 이벤트 캡처·리뷰 표시 전무. 서버 RMS 힌트 프론트 미사용(dead).
- **권고**: 침묵·한숨·울음을 타임스탬프 메타 이벤트로 보존·시각화, '침묵 견디기'를 역량 지표화, 페르소나 의도적 침묵·비유창 한국어 렌더링.

### [medium] M2. 다회기 종단 케이스 아크·교차회기 사례개념화 미구동
- **근거**: doc1(2~10회기), doc2(3회기 자기개념 진화)
- **현재상태**(분석): case_state.ccd_estimate/presenting_arc/alliance_level 스키마만, build_recall_context() 빈 컨텍스트 반환. 음성 경로 빈 RecallContext.
- **권고**: case_state 런타임 구동, build_recall_context 실제 회상/pinned_fact 주입, 접수면접→다회기 연속성·자기개념 진화.

### [medium] M3. SSO claim 매핑·식별자 안정성·deprovisioning 감사 미연결
- **근거**: doc3(교내 SSO), doc4(RBAC·익명화)
- **현재상태**(분석): Google/SAML 콜백 cohort_ids=[] 하드코딩, role이 email allowlist, external_id가 'email:{}' 파생(불안정). SAML 서명검증 미구현. role변경/삭제 audit 미기록. 거버넌스 증거(claim-map·동의 매트릭스) 부재.
- **권고**: SSO claim→role/cohort/institution_user_id 매핑+안정 식별자(sub/NameID), SAML 서명검증, deprovisioning audit, 한신 IdP 확정·외부 증거 수급.

### [medium/추적] X1. 재귀학습·데이터셋 export 파이프라인 미구현
- **현재상태**(분석): ds.* 스키마(κ/ICC 컬럼)만, read/write 코드 0건. JSONL export·IAA 게이트·골든셋 승격 미코딩.
- **권고**: JSONL export 잡, IAA 게이트(κ≥0.6/ICC≥0.75), 골든셋 승격.

### [medium/추적] X2. AI API 비용 관측 부재
- **근거**: doc3(회의록이 'AI API 비용'을 운영 리스크로 명시)
- **현재상태**(분석): 게이트웨이 토큰 텔레메트리 0 고정, cost 모니터링·캐싱 부재.
- **권고**: 토큰 텔레메트리 실측, 저비용 모델 분기·캐싱, 비용 대시보드.

### [low] L1. 기술스택 신청서-구현 불일치 및 단기일정 산출물 압박
- **근거**: doc4(Spring Boot 3/Node.js·TimescaleDB vs 실제 FastAPI/Python), doc3(20주)
- **권고**: 스택 정합 또는 변경 사유를 거버넌스 회의록으로, 9월 저작권 등재 문서화 수준을 일정 반영.

## 4. 즉시 착수 가능 vs 소유자 결정/외부 의존

### A. 즉시 착수 가능(코드/스키마 내부, 외부 합의 불요)
- C2(2),(4): escalate 시 safety_events insert, prepare_turn에서 ideation_observed 전달 — 배선 수정.
- C3: theory 인자 추가 + Session.tsx 하드코딩 제거 + 프론트 선택 UI 골격.
- H2: eval_hook을 turn 파이프라인에 주입(이미 정의·export됨) — 배선.
- H3: 페르소나 저작 CRUD + P4~P7 로드 경로.
- H4(부분): Presidio 한국어 설정·룰, llm_call_log 적재, 마스킹 미들웨어 하드게이트.
- M1(부분), M2, X1, X2: 메타 이벤트 보존, build_recall_context 구현, ds.* read/write·export, 토큰 텔레메트리.

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

## 5. 미해결·판독 한계 (quality_flags)

- 원천 핵심 축어록 2단 표(doc5 8~28p 상1~63, doc2 3회기 표)는 txt 추출 시 일부 누락 — PDF 시각 판독이 1차 근거.
- OCR 잔재(doc1 '괴게 씩씩'≈'되게 씩씩', doc5 따옴표 깨짐·오탈자). 의미는 시각 보정했으나 일부 표현 불확실.
- doc4 KPI 범위 주의: κ/ICC·환각률은 신청서 본문 미명시('정량 신뢰도 확보' 수준) — 계약 확정 지표로 단정 금지.
- doc4/doc3 행정 불일치: 참여교수 1명 vs 구훈정·어유경 2명 병기, 서식7 연도 '2025' 오기, 연구책임자 표기 불일치(류승택/구훈정), 트웬티온스 4인 성명 공란.
- '현재상태'는 grep/코드 사실 기반 적대적 비평 인용 — 위 검증 메모 5건은 작성자 직접 재확인. 그 외는 착수 전 코드 1차 재확인 권고.