yunchan/vignette
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
vignette/docs/ops/source-docs-gap-analysis-2026-06-26.md

17 KiB
Raw Blame History

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사분면 구조 SessionReviewResponse.caseWorksheet와 리뷰 화면 read-only 카드 1차 구현. 편집·저장·임상 루브릭·AI 채점은 후속 ✓
C2 위기 escalate 배선 실제 위기 신호는 엔진 호출 전 중단하고 109 리소스·conversation_stopped를 반환한다. crisis.risk_level은 ideation_observed로 전달되고, escalate 시 app.safety_events detail 적재 및 교수자 대시보드 알림 큐로 연결된다. 안전 이벤트 DB insert payload는 회귀 테스트로 고정했다.
C3 이론모드 1차 배선 theory_mode가 세션·평가·생성 프롬프트까지 전달되고 Session.tsx 하드코딩 제거 ✓
H2 턴별 평가 1차 가동 make_eval_hook이 submit/voice에 주입되고 stream 평가도 붙어 정규화 적재·복원 ✓
H3 페르소나 저작 경로 부재 persona_repository.py는 in-code SEED_PERSONAS(P1~P3)만 materialize, draft CRUD·외부 JSON 로드 없음 ✓

그 외 항목(H1 KPI 수집, H4 한국어 이름/기관 NER와 동의 게이트, M1M2, X1X2, L1)은 분석 결과이며 착수 전 코드 재확인 권고. M3은 1차 구현 후 재검증 완료. doc4 KPI 범위(κ/ICC·환각률)는 신청서 본문 미명시 — 별도 평가설계 문서 근거 가능성(과대해석 금지).

1. 총평

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

  1. 임상 산출물 구조의 1차 구현과 고도화 필요 — doc1/doc4/doc5가 1급 산출물로 요구하는 사례개념화 워크시트(11탐색항목·호소 5영역·인지삼제·1·2차 감정·보호/방해 4사분면·생물심리사회 목표)는 리뷰 API와 read-only UI 초안으로 1차 구현됐다. 편집·DB 저장, 임상 루브릭, AI 추출/채점, 교수자 검수는 아직 후속이다.
  2. 위기개입 안전 프로토콜의 1차 배선 완료와 임상 고도화 필요 — 실제 위기 신호는 LLM 호출 전 중단하고 109 안내·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. 사례개념화·치료계획 산출물 구조 1차 구현·고도화 필요

  • 근거: doc1, doc4(mockup '상담 설정·피드백 리포트'), doc5
  • 현재상태(✓직접검증): SessionReviewResponse.caseWorksheet와 리뷰 화면 read-only 카드가 축어록 근거 기반 초안을 제공한다. CCD는 숨겨진 정답키이고, 현재 워크시트는 저장형 학습자 제출물은 아님.
  • 권고: 편집·DB 저장형 사례개념화 워크시트, AI 축어록 초안 추출 고도화, 규칙 기반 채점, 교수자 검수 플로우를 추가한다. 루브릭은 임상팀이 외부 설정으로 정의 가능하게 외부화.

[critical] C2. 위기개입 프로토콜·생명유지서약·에스컬레이션 1차 배선 완료·임상 고도화 필요

  • 근거: doc1, doc5(핵심 훈련 시나리오), doc4(IRB 전제)
  • 현재상태(✓직접검증): 실제 자해·자살 신호는 REST/SSE/voice에서 엔진 호출 전 중단하고 crisis_resource(109), conversation_stopped를 반환한다. prepare_turn은 crisis risk level을 ideation_observed로 전달하고, record_safety_event는 app.safety_events에 109 resource·turn_seq·matched detail을 적재한다. 교수자 대시보드는 list_safety_alerts 기반 안전 알림 큐를 노출한다.
  • 권고: 후속은 콘텐츠/정책 영역이다. 위기 분기 스크립트(비밀보장 예외고지→단계적 탐색→서약 유도), 실시간 push/메일 알림 정책, 학습자 위기탐색 누락 시 회기리뷰 감점 루브릭을 임상팀 산출물로 외부화한다.

[critical] C3. 이론모드 1차 배선 완료 + CBT 콘텐츠/선택 UI 잔여

  • 근거: doc4(humanistic+CBT 필수), doc2/doc5
  • 현재상태(✓직접검증): TurnContext/prepare_turn/sessions/voice/evaluator에 theory_mode가 전달되고, build_turn_messages도 인간중심·CBT·통합 이론 프레이밍을 엔진 메시지에 넣는다. 프론트는 persona.theory_target 기준으로 시작해 기존 humanistic 하드코딩을 제거했다.
  • 권고: 임상팀 확정 CBT 단계 프롬프트 체인(공감·반영 / 인지재구조화·행동활성화), 이론부합 스코어링 루브릭, 명시적 프론트 이론 선택 UI. 현재는 페르소나 설계 이론 자동 선택이다.

[high] H1. 계약 평가 KPI(자기효능감·기술숙련도·수련만족도 사전사후) 수집·집계 전무

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

[high] H2. 턴별 회기 리뷰 fast-loop 1차 가동 + 골든셋/2열 UI 잔여

  • 근거: doc2, doc5(골드 포맷: 기법 태깅+적절성+대안반응+이론해석)
  • 현재상태(✓직접검증): make_eval_hook이 submit/voice 생성 경로에 주입되고, stream은 _evaluate_stream_turn으로 fast-loop 평가를 붙인다. 결과는 feedback_scores, alternative_utterance 등 정규화 테이블에 적재·hydrate된다.
  • 권고: 회기리뷰 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 마스킹 한국어 이름/기관 NER + 동의 게이트 잔여

  • 근거: doc1/2/5(실명·날짜·장소·금액·미성년·자살시도 다수), doc4(IRB·개인정보)
  • 현재상태(재검증): Presidio language='en' 고정으로 이름/기관명은 NER 보강이 필요하다. 한국어 날짜·금액·행정구역 주소 정규식 폴백은 추가됐고, 상담 생성(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행 증가를 확인했다. consent_at 컬럼만, 동의 수집/게이트/철회 엔드포인트 전무.
  • 권고: 한국어 이름/기관 NER 추가, 미성년/guardian 동의 수집·하드게이트·철회. 공개 Google OAuth 실제 /turn proof는 별도 운영 게이트.

[medium] M1. 비언어/준언어 임상 이벤트 캡처·태깅 부재

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

[medium] M2. 다회기 종단 케이스 아크·교차회기 사례개념화 미구동

  • 근거: doc1(2~10회기), doc2(3회기 자기개념 진화)
  • 현재상태: 1차로 (persona_id, learner_id) 안정 case_profile upsert, 원자적 session_no, 직전 session_summary 기반 seed recall, REST/SSE/voice recall cache 주입을 연결했다. case_digest/pinned_fact 실적재, episodic embedding writer, trajectory 갱신은 아직 없다.
  • 권고: case_state 런타임 보강, build_recall_context의 pinned_fact·case_digest 실적재, 접수면접→다회기 연속성·자기개념 진화 실증.

[medium] M3. SSO claim 매핑·식별자 안정성 1차 완료·운영 IdP 감사 미연결

  • 근거: doc3(교내 SSO), doc4(RBAC·익명화)
  • 현재상태(✓직접검증): 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.

[medium/추적] 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 승격 검증.

[medium/추적] X2. AI API 비용 관측·예산 경고·평가 저비용 라우팅 1차 완료

  • 근거: doc3(회의록이 'AI API 비용'을 운영 리스크로 명시)
  • 현재상태: 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, 장기 비용 추이/한도 정책, 운영 모델별 비용 검증.

[low] L1. 기술스택 신청서-구현 불일치 및 단기일정 산출물 압박

  • 근거: doc4(Spring Boot 3/Node.js·TimescaleDB vs 실제 FastAPI/Python), doc3(20주)
  • 권고: 스택 정합 또는 변경 사유를 거버넌스 회의록으로, 9월 저작권 등재 문서화 수준을 일정 반영.

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

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

  • C1 1차 완료: caseWorksheet 응답 구조와 리뷰 화면 read-only 워크시트 카드. 후속은 저장형 입력 폼·임상 루브릭·AI 추출/채점.
  • C2 1차 완료: escalate 시 safety_events insert, prepare_turn의 ideation_observed 전달, 109 resource, 교수자 알림 큐까지 배선했다. 후속은 임상 스크립트·서약 문안·감점 루브릭.
  • C3 1차 완료: theory_mode가 세션·평가·생성 프롬프트까지 흐른다. 후속은 임상팀 CBT 체인·이론부합 루브릭·명시적 선택 UI.
  • H2 1차 완료: make_eval_hook과 stream 평가가 턴 파이프라인에 붙고 정규화 테이블로 적재·복원된다. 대안발화도 app.alternative_utterance로 정규화한다. 후속은 2열 리뷰 UI·골든셋.
  • H3: 페르소나 저작 CRUD + P4~P7 로드 경로.
  • H4(부분): 한국어 이름/기관 NER, 동의 게이트. LLM call audit 적재와 로컬 live row proof는 완료.
  • X1: dry-run JSONL export·PII scan·IAA 계산 1차 완료. ds.* write는 --write-dataset 명시 시에만 수행한다. X2 비용 관측·budget alert와 evaluator 모델 override 1차는 완료했고 semantic cache·장기 한도 정책은 후속. M1/M2도 1차 구현 완료, provider 기반 비언어 감지와 case_digest/pinned_fact 실적재는 후속.

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

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

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

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