현재 작업 전체 반영

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

@@ -45,34 +45,34 @@
 
 ## 2. 갭 로드맵 — 심각도 우선순위
 
-심각도 분류: **critical 3 / high 4 / medium+ 6**. `✓`는 작성자가 코드 grep으로 직접 재확인한 항목, `(분석)`은 분석 결과로 착수 전 코드 1차 재확인 권고.
+심각도 분류: **critical 3 / high 4 / medium+ 6**. C1의 "구조 전무"는 1차로 해소됐고, 편집·저장·임상 루브릭·AI 채점은 계속 추적한다. `✓`는 작성자가 코드 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 |
+| **C1** | 사례개념화·치료계획 산출물 구조 1차 구현·고도화 필요 | `SessionReviewResponse.caseWorksheet`와 리뷰 화면 read-only 카드가 축어록 근거 기반 초안을 제공한다. CCD는 숨은 정답키이고, 현재 워크시트는 저장형 학습자 제출물은 아님. | 편집·DB 저장형 워크시트, 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** | 턴별 회기 리뷰(상호작용 분석 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(골드 포맷) |
+| **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) 부재 + 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·개인정보) |
+| **H4** | PII 마스킹 한국어 공백 + 외부전송 관측 live proof 잔여 | Presidio `language='en'` 고정이라 이름/기관명은 NER 보강이 필요하지만, 한국어 날짜·금액·행정구역 주소 정규식 폴백은 추가됐다. 외부 LLM 호출은 상담 생성(generate/stream)·fast/deep 평가 직후 `audit.llm_call_log`에 provider/model/token/cost/inference_geo/latency만 적재하도록 연결했고, prompt/completion 본문은 저장하지 않는다. `consent_at` 컬럼만 있고 동의 수집/게이트/철회 엔드포인트는 아직 없다. | 한국어 이름/기관 NER 추가, 실제 운영 로그인 `/turn` 후 `audit.llm_call_log` row 실측, 미성년/guardian 동의 수집·게이트·철회. | doc1/2/5(실명·날짜·미성년·자살시도 다수)·doc4(IRB·개인정보) |
 
 ### Medium+ (6) — M1~M3, X1~X2, 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 모니터링·캐싱 부재. (분석) | 토큰 텔레메트리 실측, 저비용 모델 분기·캐싱, 비용 대시보드. | 
+| **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차 완료·최적화 미구현 | 턴별 provider/model/tokens/cost 저장 경로와 `GET /admin/usage`, 관리자 비용 대시보드를 연결했다. `ADMIN_USAGE_BUDGET_USD` 기준 예산 상태(ok/warn/exceeded)도 응답/UI에 표시한다. DB 미가용 dev는 runtime store fallback, prod는 fail-closed다. 캐싱·저비용 모델 분기는 아직 없다. | 캐싱, 저비용 모델 분기, 장기 비용 추이/한도 정책. |
 | **L1** | 기술스택 신청서-구현 불일치 및 단기일정 산출물 압박 | doc4 신청서 스택(Spring Boot 3/Node.js·TimescaleDB) vs 실제 FastAPI/Python 불일치, 20주 단기일정·9월 저작권 등재 압박. | 스택 정합 또는 변경 사유를 거버넌스 회의록으로, 9월 저작권 등재 문서화 수준을 일정 반영. |
 
 > X2 근거: doc3 회의록이 'AI API 비용'을 운영 리스크로 명시.
@@ -85,17 +85,18 @@
 
 ### A. 즉시 착수 가능 (내부 코드, 외부 합의 불요)
 
-- **C2 배선**: escalate 시 `safety_events` insert + `ideation_observed` 전달.
-- **C3 골격**: `theory` 인자 추가 + `Session.tsx:589` 하드코딩 제거 + 프론트 이론 선택 UI 골격.
-- **H2 배선**: `make_eval_hook`을 turn 파이프라인에 주입(이미 정의·export됨, `evaluator.py:738`).
+- **C1 1차 완료**: `caseWorksheet` 응답 구조와 리뷰 화면 read-only 워크시트 카드. 후속은 저장형 입력 폼·임상 루브릭·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**: 페르소나 저작 CRUD(draft→review) + P4~P7 로드 경로.
-- **H4(부분)·M1(부분)·M2·X1·X2**: 마스킹 한국어 설정·하드게이트, 비언어 메타 이벤트 보존, `build_recall_context` 구현, `ds.*` read/write·export, 토큰 텔레메트리.
+- **H4(부분)·X1·X2**: 마스킹 한국어 정규식 보강과 외부 LLM 호출 metadata-only `audit.llm_call_log` 적재 경로, dry-run JSONL export·PII scan·IAA 계산 1차는 완료했다. `ds.*` write는 `--write-dataset` 명시 시에만 수행한다. X2 비용 관측·예산 경고 1차는 완료했고 캐싱·저비용 모델 분기는 후속. M1/M2도 1차 구현 완료, provider 기반 비언어 감지와 case_digest/pinned_fact 실적재는 후속.
 
 ### B. 소유자 결정 / 외부(임상팀·기관) 의존
 
-- **임상팀(구훈정·어유경) 산출물**: C1 워크시트 항목·채점 루브릭, C3 CBT 이론 콘텐츠·프롬프트 체인, C2 위기 스크립트·서약 문안, H2 골든셋 코딩. → 코드는 '편집 가능 구조'만 선제 구축.
+- **임상팀(구훈정·어유경) 산출물**: C1 채점 루브릭·항목 확정, C3 CBT 이론 콘텐츠·프롬프트 체인, C2 위기 스크립트·서약 문안, H2 골든셋 코딩. → 코드는 구조를 선제 구축하되 임상 문안과 평가기준은 외부 정의로 받는다.
 - **소유자 평가설계 결정**: H1 실험/통제군 배정·3척도 문항·50분 흐름. κ/ICC·환각률 목표는 doc4 미명시 → 평가설계 문서 확정.
-- **기관(한신 IT) 의존**: M3 SSO IdP 프로토콜·test tenant·claim 스키마, SAML 인증서, 거버넌스 증거.
+- **기관(한신 IT) 의존**: M3 SSO IdP 프로토콜·test tenant·claim 스키마, SAML 인증서, deprovisioning 거버넌스 증거.
 - **거버넌스 결정**: L1 스택 정합성 처리 방향, 저작권 등재 문서화 수준, IP 협의.
 
 ---
@@ -113,16 +114,16 @@
 ### 코드 재확인 grep 예시 (저장소 루트 `D:/workspace/vignette`)
 
 ```powershell
-# C1: 사례개념화 구조 존재 여부 (현재 0건이어야 함)
-rg -n "cognitive_triad|case_conceptual|인지삼제|4사분면|quadrant" apps
+# C1: 사례개념화 워크시트 1차 구조와 잔여 저장/채점 경로 확인
+rg -n "caseWorksheet|ReviewCaseWorksheet|사례개념화 워크시트|cognitive_triad|인지삼제|4사분면" 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
+# C3: 이론모드 스레딩과 생성 프롬프트 주입 확인
+rg -n "theory_mode|THEORY_MODE_GUIDANCE|sessionApi.start\\(personaCode" apps
 
-# H2: eval_hook 정의 vs 주입
+# H2: eval_hook 정의와 주입
 rg -n "make_eval_hook" apps/api/app
 
 # H3: 페르소나 SEED(P1~P3) 한정 여부
@@ -133,7 +134,7 @@ rg -n "SEED_PERSONAS" apps/api/app/persona_repository.py
 
 ```powershell
 # 백엔드 (작업 디렉터리 apps/api)
-python -m pytest app/ -q            # 현재 77 pass
+python -m pytest app/ -q            # 현재 118 pass
 python -m pytest engine_gateway/ -q # 현재 7 pass
 
 # 프론트 (작업 디렉터리 apps/web)
@@ -152,7 +153,7 @@ npm run e2e                         # Playwright — web+api+DB 스택 필요
 - 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차 재확인 권고.
+- '현재상태'는 grep/코드 사실 기반 적대적 비평 인용에서 시작했으나, **C1·C2·C3·H2·M3은 1차 구현 후 재검증 완료**, H3은 작성자 직접 재확인(✓) 기준이다. 그 외(H1·H4·M1·M2·X1·X2·L1)는 착수 전 코드 1차 재확인 권고.
 
 ---