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

> 한신대 산학협력(구훈정 교수) **원천문서 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된다. | 회기리뷰 UI 좌(축어록 타임라인+비언어)/우(기법·적절성·대안반응·이론) 2열 고도화, 원천 축어록 few-shot 골든셋 적재. | 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.consent_at` 기반 학습자 동의 수락/철회 엔드포인트와 회기 시작·voice dev persona 시작 하드게이트를 추가했고, 프론트 세션 시작 전 동의 UI와 E2E 동의 seed를 연결했다. | 한국어 이름/기관 NER 추가, 미성년/guardian 및 법무 검토가 필요한 서명 동의서/개인정보 고지 evidence 확보. 공개 Google OAuth 실제 `/turn` proof는 별도 운영 게이트. | doc1/2/5(실명·날짜·미성년·자살시도 다수)·doc4(IRB·개인정보) |

### Medium+ (6) — M1~M3, X1~X2, 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`로 정규화한다. 후속은 2열 리뷰 UI·골든셋.
- **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 골든셋 코딩. → 코드는 구조를 선제 구축하되 임상 문안과 평가기준은 외부 정의로 받는다.
- **소유자 평가설계 결정**: H1 실험/통제군 배정·3척도 문항·50분 흐름. κ/ICC·환각률 목표는 doc4 미명시 → 평가설계 문서 확정.
- **기관(한신 IT) 의존**: M3 SSO IdP 프로토콜·test tenant·claim 스키마, SAML 인증서, deprovisioning 거버넌스 증거.
- **거버넌스 결정**: 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`)

```powershell
# 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
```

### 검증 명령 (변경 후)

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

---

### 변경 이력

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