현재 작업 상태 저장

docs/guides/architecture.md

@@ -204,7 +204,7 @@ RBAC×AIView로 차단된다. 이 모듈은 평가 신호만 산출한다.
 - **fast-loop** `evaluate_turn(ctx, client_reply, engine) -> TurnEvaluation`: 턴 직후 경량 4차원
   ① technique[] ② client_state_read[] ③ appropriateness(pos/warn/neutral) ④ intent_deviation
   (`{dimension, expected, actual, severity}`, "의도와 다른 부분" 1급 시민). `rapport_signal`도 함께
-  산출해 상태머신에 주입 가능. `tier="feedback"`, `structured_schema=_fast_schema()`.
+  산출해 상태머신에 주입 가능. 게이트웨이 호출에는 `structured_schema=_fast_schema()`를 사용한다.
 - **deep-loop** `evaluate_session(...) -> SessionEvaluation`: 단계전환/회기말 정밀평가. 기법 분포
   (`aggregate_distribution`, 코드 결정론 집계) + strengths + improvements(최대 3) +
   supervisor rationale/critique + alternative_utterances. `_deep_schema()`.
@@ -268,7 +268,9 @@ server: ready → state(listening) → state(thinking) → transcript → reply
 - `POST /sessions/{id}/end` — `memory.make_carry_over(...)` → 세션 종료 + carry 준비 →
   `_schedule_session_evaluation(sess)`로 deep-loop 평가를 비동기 태스크로 발사.
 - `GET /sessions/{id}/review` — 저장된 축어록 + 평가 AI 산출물로 학습자-안전 리뷰 구성
-  (`_rubric_from_evaluation`, `_ai_review_points` 등). 평가 미완이면 `degraded/reviewReady=false`로 표기.
+  (`_rubric_from_evaluation`, `_ai_review_points` 등). 리뷰 조회 시 발화별 fast-loop 평가는
+  `app.feedback_scores`/라벨 조인 테이블에서 `TurnRecord.evaluation` 형태로 hydrate한다.
+  평가 미완이면 `degraded/reviewReady=false`로 표기.
 
 발화 가시성: 학습자에게는 `visible_to`에 `counselor`가 포함된 턴만 보여준다
 (`_learner_visible_turns` → `_LEARNER_VISIBLE_AI_ROLE="counselor"`). 평가 전용 데이터는 노출되지 않는다.
@@ -405,8 +407,11 @@ DB는 PostgreSQL 16 + pgvector(단일 SoR). 초기화 SQL은 `infra/db/init/`에
 
 ### 5.2 audit 스키마 + app 평가/종단 (`infra/db/init/04_audit_eval_rls.sql`)
 
-- 평가: `app.feedback_scores`(발화별 점수, `visible_to='{evaluator}'`, loop fast/deep),
-  `app.alternative_utterance`(코칭은 학습자 노출).
+- 평가: `app.feedback_scores`(발화별 점수·rationale, `visible_to='{evaluator}'`, loop fast/deep),
+  `app.turn_technique`/`app.turn_client_state`(fast-loop 라벨 정규화),
+  `app.supervisor_comment`(intent_deviation). `app.alternative_utterance`는 deep-loop 대안발화 정규화 대상이다.
+  `session_persistence.append_turn`은 `app.turns INSERT ... RETURNING id`를 확인한 뒤 같은 트랜잭션에서
+  evaluator 컨텍스트로 fast-loop 평가 rows를 적재한다. 리뷰 경로만 evaluator 컨텍스트로 hydrate한다.
 - 종단: `app.learner_profile`(dim_ewma/dim_slope/persistent_gaps — 회기 거듭하며 나아지는지).
 - 감사(append-only): `audit.persona_drift_log`(임베딩 일관성/CCD 누출), `audit.audit_log`(인간 열람 추적),
   `audit.llm_call_log`(비용·inference_geo).
@@ -512,6 +517,7 @@ npm run e2e        # Playwright (web+api+DB 스택 필요)
 - 자살·자해 수단/방법 정보는 출력 가드레일이 차단·치환한다. `ideation_stage` 안전 상한은 3(R5).
 - 상태머신 수치(stage/openness/resistance/ideation)는 결정론 코드만 만지고 LLM에 위임하지 않으며,
   무손실 carry-over 된다(P2/P4).
-- 평가/정답/평가 전용 데이터는 RBAC×AIView(레이어1 `visible_to`) + RLS(레이어2)로 학습자에게서 차단된다.
+- 평가/정답/평가 전용 데이터는 RBAC×AIView(레이어1 `visible_to`) + RLS(레이어2)로 학습자 직접 조회에서 차단된다.
+  단, 서버 리뷰 응답은 소유 세션 확인 후 evaluator 컨텍스트로 필요한 평가 rows만 hydrate해 학습자-안전 형태로 가공한다.
 - 평가/로깅 훅 실패는 비치명적으로 흡수되어 상담 루프를 멈추지 않는다.
 ```

docs/guides/local-development.md

@@ -36,6 +36,19 @@ powershell -NoProfile -ExecutionPolicy Bypass -File scripts\dev-up.ps1
 > 스크립트는 uvicorn이 설치된 python을 자동 해석한다(시스템에 복수 python 공존 시 'python' 별칭이
 > uvicorn 없는 인터프리터를 가리킬 수 있음 — 이 함정 때문에 명시 해석함).
 
+### 0.1 Tailscale PC/모바일 접속
+
+같은 Tailnet에 로그인한 장비에서는 아래 명령으로 Tailnet 전용 HTTPS 접속점을 켠다.
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\start-tailscale-runtime.ps1
+```
+
+- 현재 머신의 접속 주소: **https://alpaca-home.taile93291.ts.net**
+- 이 경로는 `tailscale serve`로 `https://alpaca-home.taile93291.ts.net` → 로컬 web `127.0.0.1:5173`을 연결한다.
+- API는 Tailnet 전용으로 `127.0.0.1:8010`에 뜨고, Vite proxy는 `VITE_API_PROXY_TARGET`으로 이 포트를 본다. 기존 8000 reloader 잔류와 충돌하지 않기 위해 분리했다.
+- dev-login은 `AUTH_DEV_LOGIN_EXTRA_ORIGINS`에 Tailnet origin이 들어간 경우에만 dev 환경에서 열린다. prod에서는 열리지 않는다.
+
 ### 수동 기동(대안)
 
 DB·엔진 없이도 UI/로그인/페르소나/세션 생성까지는 동작한다(턴 생성만 불가).
@@ -99,6 +112,7 @@ npm install
 | `ENGINE_MODE` | `claude_cli` | 엔진 provider 라우팅 |
 | `AUTH_DEV_LOGIN_ENABLED` | `true` | dev-login 엔드포인트 활성화 |
 | `AUTH_ALLOWED_EMAIL_DOMAINS` | `["hs.ac.kr","twentyoz.kr"]` | 로그인 허용 이메일 도메인(dev-login 포함 검증) |
+| `VIGNETTE_VOICE_POC_SAMPLE_TTS` | `false` | P1 무참조 샘플 음성을 `/voice/ws` TTS에 연결하는 개발 전용 플래그. 마이크/STT는 `OPENAI_API_KEY` 필요, 프로덕션 금지 |
 
 > 참고: 프로세스 환경변수(`$env:KEY`)는 `.env`보다 우선한다. 일회성 오버라이드에 쓸 수 있다.
 
@@ -306,7 +320,7 @@ docker compose up -d           # 전체
 ```powershell
 # 백엔드 (apps/api)
 cd apps\api
-python -m pytest app\ -q              # 현재 77 pass
+python -m pytest app\ -q              # 현재 98 pass
 python -m pytest engine_gateway\ -q   # 7 pass
 
 # 웹 (apps/web)

docs/guides/testing.md

@@ -15,7 +15,7 @@ Vignette 저장소의 모든 검증 수단(백엔드 단위 테스트, 웹 타
 
 | 검증 | 작업 디렉터리 | 명령 | DB | API(8000) | 웹(5173) | 엔진GW(9099) | 브라우저 | 현재 통과 |
 |---|---|---|---|---|---|---|---|---|
-| 백엔드 단위 테스트 | `apps/api` | `python -m pytest app/ -q` | 불필요 | 불필요 | 불필요 | 불필요 | 불필요 | 77 pass |
+| 백엔드 단위 테스트 | `apps/api` | `python -m pytest app/ -q` | 불필요 | 불필요 | 불필요 | 불필요 | 불필요 | 98 pass |
 | 엔진 게이트웨이 테스트 | `apps/api` | `python -m pytest engine_gateway/ -q` | 불필요 | 불필요 | 불필요 | 불필요 | 불필요 | 7 pass |
 | 웹 타입체크 | `apps/web` | `npm run typecheck` | 불필요 | 불필요 | 불필요 | 불필요 | 불필요 | — |
 | 웹 빌드 | `apps/web` | `npm run build` | 불필요 | 불필요 | 불필요 | 불필요 | 불필요 | — |
@@ -41,14 +41,14 @@ Vignette 저장소의 모든 검증 수단(백엔드 단위 테스트, 웹 타
 
 ```sh
 # apps/api
-python -m pytest app/ -q              # 앱 단위 테스트 (현재 77 pass)
+python -m pytest app/ -q              # 앱 단위 테스트 (현재 98 pass)
 python -m pytest engine_gateway/ -q   # 게이트웨이 단위 테스트 (현재 7 pass)
 ```
 
 수집만 빠르게 확인하려면:
 
 ```sh
-python -m pytest app/ --collect-only -q            # → "77 tests collected"
+python -m pytest app/ --collect-only -q            # → "98 tests collected"
 python -m pytest engine_gateway/ --collect-only -q # → "7 tests collected"
 ```
 
@@ -61,6 +61,7 @@ python -m pytest engine_gateway/ --collect-only -q # → "7 tests collected"
 |---|---|
 | `app/test_runtime_policy.py` | 런타임 정책(공개/dev 모드, dev-login 가드) |
 | `app/test_session_turn_persistence.py` | 세션 턴 영속화(DB/인메모리 양쪽) |
+| `app/test_evaluation_persistence.py` | fast-loop 평가 정규화 적재/복원 매핑 |
 | `app/test_orchestrator_masking.py` | 오케스트레이터 PII 마스킹 게이트 |
 | `app/test_state_machine_resistance.py` | 저항엔진 상태머신(openness 전이) |
 | `app/test_rbac_idor.py` | RBAC / IDOR 권한 경계 |
@@ -262,7 +263,7 @@ cd apps/web && npm run e2e
 검증 결과는 **실제로 실행해 통과한 명령**만 근거로 보고한다.
 
 - "통과했다/완료다"라고 말하려면 그 자리에서 **실행 가능한 검증 명령과 관측된 결과(통과 개수)**를
-  함께 제시한다. 예: `python -m pytest app/ -q` → `77 passed`.
+  함께 제시한다. 예: `python -m pytest app/ -q` → `98 passed`.
 - 의존을 갖춘 검증을 우회하지 않는다. E2E를 DB/API 없이 돌려 놓고 "그린"이라고 보고하지
   않는다. 풀스택을 못 띄웠으면 **"E2E 미실행"**이라고 명시한다.
 - 인메모리 degraded 기동(`db:false`)에서 페르소나 헬퍼가 실패하는 것은 환경 문제이지 코드가