docs(product): alignment audit plan 추가

docs/12_core_loop_execution_roadmap.md

@@ -16,6 +16,7 @@ Last Updated: 2026-03-15
 - `09_app_entry_detailed_spec.md`
 - `10_refocus_system_spec.md`
 - `11_away_return_recovery_spec.md`
+- `16_product_alignment_audit_plan.md`
 
 ---
 
@@ -373,4 +374,5 @@ Away / Return이 끼어들기 전, 다음으로 예정된 축은 아래 두 가
 
 현재 위치:
 
-> `3. Break refinement`를 마무리했고, `4. Weekly Review`의 entry flow 구현까지 마친 상태다.
+> 코어 루프 기준으로는 `4. Weekly Review`의 entry flow 구현까지 마친 상태이고,
+> 운영 기준으로는 이제 `Product Alignment Audit`을 통해 core loop 전반의 기획-구현 정합성을 전수 점검하는 단계다.

docs/16_product_alignment_audit_plan.md

@@ -0,0 +1,602 @@
+# 16. Product Alignment Audit Plan
+
+Last Updated: 2026-03-15
+
+이 문서는 VibeRoom 전체에서 **기획과 구현이 어긋난 부분을 체계적으로 찾아내고, 실제 수정 작업까지 연결하는 실행 계획**이다.
+
+목표는 단순하다.
+
+> 우연히 발견한 불일치를 그때그때 고치는 방식에서 벗어나,  
+> 어떤 세션과 어떤 에이전트가 들어와도 같은 기준으로 앱 전체를 점검하고 닫을 수 있는 운영 체계를 만든다.
+
+---
+
+## 1. 왜 이 문서가 필요한가
+
+최근 점검에서 이미 아래 문제가 반복적으로 드러났다.
+
+- 카피는 `break`를 약속하는데 실제 동작은 `pause`인 경우
+- spec은 `/app`이 review의 primary entry라고 적혀 있는데 구현에서는 resume 상태에서 review entry가 사라지는 경우
+- `goal click`, `수정`, `expand/collapse`의 역할 분리가 코드와 문서에서 다르게 남는 경우
+- `/stats -> /app` handoff가 실제 행동을 바꾸지 않는데 문구는 개인화된 추천을 약속하는 경우
+
+즉 현재 문제는 “버그가 많다”가 아니라,
+**기획 / 카피 / 상태 모델 / 실제 코드 / 문서가 동시에 drift할 수 있는 구조**라는 점이다.
+
+이 audit plan의 목적은 아래 4개다.
+
+1. source of truth를 고정한다
+2. route / state / copy / BM claim을 같은 표로 점검한다
+3. 발견된 불일치를 severity와 수정 단위로 즉시 분류한다
+4. 수정 후 문서와 QA까지 같은 라운드에서 닫는다
+
+---
+
+## 2. Audit의 정의
+
+이 문서에서 말하는 `alignment audit`는 아래 5개를 동시에 보는 점검이다.
+
+### 1. Product Alignment
+
+- 제품 원칙과 실제 기능이 맞는가
+- single-goal, single-microStep, commitment-first 원칙이 지켜지는가
+
+### 2. Flow Alignment
+
+- 사용자가 실제로 밟는 경로가 기획된 유저 플로우와 맞는가
+- entry / recovery / complete / review의 연결이 끊기지 않는가
+
+### 3. Copy Alignment
+
+- 화면 문구가 실제 동작을 과장하거나 왜곡하지 않는가
+- 초심자도 용어 없이 이해 가능한가
+
+### 4. State Alignment
+
+- pause / break / return / complete / resume 같은 상태 의미가 코드와 카피에서 일치하는가
+
+### 5. Business Alignment
+
+- Free / Pro 가치 제안이 실제 제품 행동으로 느껴지는가
+- “된다고 쓰여 있지만 실제로는 안 되는” BM성 약속이 없는가
+
+---
+
+## 3. Source of Truth 우선순위
+
+Audit 중 충돌이 생기면 아래 순서로 판단한다.
+
+1. `product_principles.md`
+2. `/Users/ijeongmin/Desktop/corpi/viberoom/current_context.md`
+3. route/flow 관련 상세 spec
+   - `09_app_entry_detailed_spec.md`
+   - `10_refocus_system_spec.md`
+   - `11_away_return_recovery_spec.md`
+   - `13_space_intent_card_collapsed_expanded_spec.md`
+   - `14_weekly_review_reframe_spec.md`
+   - `15_app_stats_entry_flow_spec.md`
+4. `90_current_state.md`
+5. 실제 코드
+
+중요:
+
+- 코드가 source of truth가 아니다
+- 하지만 문서가 낡았고 코드가 더 최근 의도를 반영한다면, 그 차이를 `finding`으로 기록한 뒤 문서를 업데이트한다
+
+---
+
+## 4. Audit 범위
+
+### 4.1 Route 범위
+
+반드시 본다.
+
+- `/`
+- `/login`
+- `/app`
+- `/space`
+- `/stats`
+- `/settings`
+- `/admin`
+
+### 4.2 Core Product Flow 범위
+
+반드시 본다.
+
+- Landing -> Auth -> `/app`
+- `/app` new start
+- `/app` resume
+- `/space` focus
+- `/space` pause
+- `/space` return
+- `/space` next beat
+- `/space` goal complete
+- `/space` complete -> setup
+- `/app -> /stats -> /app`
+- paywall / Pro handoff
+
+### 4.3 Cross-cutting 범위
+
+반드시 본다.
+
+- i18n copy
+- query param handoff
+- API contract / optimistic UI
+- plan tier gating
+- toast / reminder / empty state
+- docs drift
+
+---
+
+## 5. Audit 원칙
+
+### 1. 화면이 아니라 “행동 단위”로 점검한다
+
+예:
+
+- `Goal Complete` 화면 자체를 보는 게 아니라
+- `사용자가 목표를 끝냈다고 느끼는 순간 -> 선택 -> 결과 상태` 전체를 본다
+
+### 2. copy와 behavior를 반드시 함께 본다
+
+카피만 맞고 동작이 다르면 실패다.
+동작은 맞는데 카피가 과장되면 그것도 실패다.
+
+### 3. Free / Pro 약속은 더 엄격하게 본다
+
+BM에 연결된 카피는 일반 카피보다 더 엄격하게 검증한다.
+
+예:
+
+- “추천 ritual로 돌아가기”
+- “방금 끝낸 흐름까지 담아 review”
+- “주간 review가 다음 세션을 돕는다”
+
+### 4. 한 라운드에서 `finding -> fix -> docs -> commit`까지 닫는다
+
+발견만 하고 쌓아두지 않는다.
+
+### 5. 브라우저 QA 없이 닫지 않는다
+
+`tsc`, `eslint` 통과는 필수지만 충분조건이 아니다.
+
+---
+
+## 6. Finding 분류 기준
+
+### P1
+
+제품 의미가 뒤틀리는 불일치
+
+예:
+
+- break로 쓰였는데 실제로 break가 아님
+- primary entry가 없어짐
+- Pro value를 약속하지만 실제로 작동하지 않음
+
+### P2
+
+사용자 플로우가 헷갈리거나 약속이 약해지는 불일치
+
+예:
+
+- 문구는 맞지만 진입점이 숨겨짐
+- 2단계 flow인데 1단계처럼 보임
+- recovery 상태가 시각적으로 구분되지 않음
+
+### P3
+
+문서 / 카피 / 접근성 / 잔여 코드 드리프트
+
+예:
+
+- 오래된 spec 표현
+- dead i18n key
+- aria-label과 가시 UI가 어긋남
+
+---
+
+## 7. 실제 Audit 방법
+
+Audit은 아래 6단계로 진행한다.
+
+### Phase 0. Baseline Freeze
+
+산출물:
+
+- 현재 기준 문서 목록
+- 현재 route / widget ownership map
+- 현재 work order
+
+실행:
+
+- `current_context.md`
+- `90_current_state.md`
+- `12_core_loop_execution_roadmap.md`
+- route map / session brief 확인
+
+목적:
+
+- 무엇이 기준인지 먼저 잠근다
+
+---
+
+### Phase 1. Route & Flow Inventory
+
+각 route마다 아래를 표로 만든다.
+
+- route
+- intended role
+- main CTA
+- secondary CTA
+- entry source
+- exit target
+- hidden states
+- Pro-specific behavior
+
+산출물:
+
+- `route-flow matrix`
+
+점검 질문:
+
+- 사용자는 이 route에 왜 오는가
+- 여기서 무엇을 해야 하는가
+- 다음 화면은 어디인가
+- 실제 코드가 이 흐름을 유지하는가
+
+---
+
+### Phase 2. State Contract Audit
+
+`/space`와 `/app`의 상태 전이를 표로 만든다.
+
+필수 상태:
+
+- setup
+- focus
+- paused
+- return
+- refocus
+- next-beat
+- complete-choice
+- complete-next
+- break
+- review-entry
+
+각 상태마다 본다.
+
+- state 이름
+- 사용자가 이해하는 의미
+- 실제 trigger
+- visible UI
+- exit actions
+- side effects
+
+산출물:
+
+- `state contract matrix`
+
+핵심 목적:
+
+- 이름만 있고 실제 의미가 다른 상태를 찾는다
+
+---
+
+### Phase 3. Copy / Behavior Audit
+
+각 핵심 CTA에 대해 아래를 점검한다.
+
+- label
+- user promise
+- actual effect
+- mismatch 여부
+
+예:
+
+- `잠시 비우기`
+- `쉬기 이어가기`
+- `다음 목표로 바로 시작`
+- `주간 review 보기`
+- `추천 ritual과 함께 /app 돌아가기`
+
+산출물:
+
+- `copy-behavior mismatch list`
+
+---
+
+### Phase 4. Business Model Audit
+
+Free / Pro를 아래 기준으로 본다.
+
+- user sees
+- user clicks
+- actual unlocked behavior
+- value perception
+- overclaim risk
+
+반드시 보는 곳:
+
+- paywall copy
+- `/stats` Pro carry-forward
+- `/app` teaser / return hint
+- review insight / ritual recommendation
+
+산출물:
+
+- `BM promise audit`
+
+---
+
+### Phase 5. Browser Journey Audit
+
+이 단계는 실제 브라우저에서 한다.
+
+필수 시나리오:
+
+1. 로그인 후 `/app` 첫 진입
+2. `/app`에서 새 goal 시작
+3. `/app` resume 상태
+4. `/space` pause -> refocus -> resume
+5. `/space` away -> return(focus)
+6. `/space` focus ended while away -> return(break)
+7. `/space` microStep done -> next beat
+8. `/space` goal complete choice
+9. `/space` goal complete next
+10. `/space` complete -> setup -> review teaser
+11. `/app` weekly review teaser -> `/stats` -> `/app`
+12. Pro 상태 handoff
+
+각 시나리오마다 본다.
+
+- first meaningful paint
+- primary CTA visibility
+- copy comprehension
+- next action clarity
+- state transition correctness
+- dismiss behavior
+- mobile / desktop 차이
+
+산출물:
+
+- `browser QA findings`
+
+---
+
+### Phase 6. Fix Closure
+
+각 finding은 아래 단위로 닫는다.
+
+- finding 요약
+- severity
+- affected files
+- fix approach
+- docs to update
+- validation commands
+- manual QA notes
+- commit hash
+
+이 단계까지 끝나야 “수정 완료”다.
+
+---
+
+## 8. 실제 실행 순서
+
+앱 전체 audit은 아래 순서로 진행한다.
+
+### Slice A. Core Loop Alignment
+
+범위:
+
+- `/app`
+- `/space`
+- `/stats`
+
+우선 점검:
+
+- entry
+- recovery
+- completion
+- review handoff
+
+이유:
+
+- VibeRoom의 돈 되는 핵심 가치가 여기 있다
+
+### Slice B. Monetization Alignment
+
+범위:
+
+- paywall
+- plan tier
+- Pro copy
+- Pro actual behavior
+
+이유:
+
+- BM 과장은 제품 신뢰를 가장 빠르게 해친다
+
+### Slice C. Shell & Supporting Routes
+
+범위:
+
+- `/`
+- `/login`
+- `/settings`
+- `/admin`
+
+이유:
+
+- 핵심 루프보다 우선순위는 낮지만, 전체 완성도와 신뢰에 영향이 크다
+
+### Slice D. Docs & Regression Guard
+
+범위:
+
+- `current_context.md`
+- `90_current_state.md`
+- detailed specs
+- lint / dead copy / route map
+
+이유:
+
+- 다음 세션에서 다시 어긋나지 않게 만드는 단계다
+
+---
+
+## 9. 추천 산출물
+
+이 audit을 실제로 굴릴 때는 아래 3개 파일이 필요하다.
+
+### 1. 기준 문서
+
+- 이 문서 `16_product_alignment_audit_plan.md`
+
+### 2. 실제 finding ledger
+
+추천 파일:
+
+- `17_product_alignment_findings.md`
+
+형식:
+
+- ID
+- severity
+- route / flow
+- product promise
+- actual behavior
+- affected files
+- fix status
+
+### 3. execution checklist
+
+추천 위치:
+
+- `work.md`
+
+형식:
+
+- 이번 slice에서 확인할 시나리오
+- 수정 범위
+- 제외 범위
+- 완료 조건
+
+---
+
+## 10. 이 audit을 어떻게 실행할 것인가
+
+### 라운드 단위 규칙
+
+한 라운드는 아래 순서로만 진행한다.
+
+1. 이번 slice 범위 결정
+2. static audit
+3. browser audit
+4. findings 정리
+5. fix
+6. docs update
+7. validation
+8. commit
+
+### 각 라운드 출력 형식
+
+항상 아래 형식으로 닫는다.
+
+- 추가
+- 수정
+- 삭제
+- 검증
+- 커밋
+
+### 커밋 규칙
+
+- 한 주제 = 한 커밋
+- 기획 불일치 정리는 `fix(flow): ...`
+- 문서 중심 라운드는 `docs(product): ...`
+
+---
+
+## 11. 바로 다음 실행 계획
+
+### 실행 1. `17_product_alignment_findings.md` 생성
+
+범위:
+
+- 현재까지 이미 드러난 core loop mismatch를 먼저 기록
+
+포함:
+
+- break semantics
+- review entry visibility
+- review teaser overclaim
+- Pro handoff realism
+- docs drift
+
+### 실행 2. Slice A static audit
+
+대상:
+
+- `/app`
+- `/space`
+- `/stats`
+
+목표:
+
+- route-flow matrix
+- state contract matrix
+- copy-behavior mismatch list
+
+### 실행 3. Slice A browser audit
+
+대상 시나리오:
+
+1. `/app` first entry
+2. `/app` resume
+3. `/app -> /stats -> /app`
+4. `/space` pause / return / complete
+5. `/space complete -> setup -> review teaser`
+
+### 실행 4. findings fix round
+
+원칙:
+
+- P1 먼저
+- 그 다음 P2
+- P3는 같은 파일을 만질 때 함께 정리
+
+---
+
+## 12. 완료 기준
+
+Alignment audit이 제대로 굴러간 상태는 아래와 같다.
+
+- 중요한 CTA가 실제 동작을 과장하지 않는다
+- primary / secondary entry가 문서와 코드에서 동일하다
+- pause / break / return / complete의 의미가 사용자 기준으로도 분리된다
+- Free / Pro 가치 제안이 실제 행동으로 느껴진다
+- 다음 세션/에이전트가 문서를 읽고도 현재 제품 상태를 오해하지 않는다
+
+---
+
+## 13. 절대 하지 말아야 할 것
+
+- 브라우저 QA 없이 문서만 보고 “정상”이라고 판단
+- 카피만 바꾸고 실제 상태 모델은 그대로 두기
+- BM 문구를 구현보다 앞서 나가게 두기
+- `current_context.md`를 나중에 한꺼번에 갱신하기
+- 한 라운드에 너무 많은 route를 동시에 수정하기
+
+---
+
+## 14. 최종 판단
+
+VibeRoom이 premium product가 되려면,
+UI refinement만으로는 부족하다.
+
+정말 중요한 것은:
+
+> 사용자가 읽는 문구, 누르는 행동, 실제로 일어나는 상태 변화,  
+> 그리고 그걸 설명하는 문서가 모두 같은 제품을 말하고 있어야 한다.
+
+이 audit plan은 그 정합성을 제품 운영의 기본 프로세스로 만들기 위한 문서다.

docs/session_brief.md

@@ -14,9 +14,9 @@ Last Updated: 2026-03-15
 
 ## 현재 우선순위
 
-1. `/space` Refocus + Return 브라우저 QA
+1. `Product Alignment Audit` findings ledger 시작
-2. `Weekly Review` 상세 기획
+2. `Core Loop Alignment` static/browser audit
-3. `Premium Ambience System` 방향 정리
+3. `Weekly Review` recovery 집계 연결
 
 ## 최근 세션 상태
 

docs/work.md

@@ -6,7 +6,8 @@
 
 - 작업은 가능한 한 "주제별"로 분리해서 작성한다.
 - 한 주제는 가능하면 한 커밋으로 끝낼 수 있게 범위를 좁힌다.
-- "금지사항/제외 범위"를 명시해서 불필요한 변경을 막는다.
+- `finding -> fix -> docs -> validation -> commit`까지 한 라운드에서 닫는다.
+- browser QA가 필요한 작업은 반드시 완료 조건에 명시한다.
 
 ## 우선순위
 
@@ -17,104 +18,69 @@
 
 ## 작업 1
 
-- 제목: `/space` Refocus polish 마무리
+- 제목: `Product Alignment Audit` findings ledger 시작
 - 목적:
-  - `10_refocus_system_spec.md` 기준으로 pause / refocus / next beat / goal complete를 premium recovery flow로 정리한다.
+  - `16_product_alignment_audit_plan.md` 기준으로 core loop 전반의 기획-구현 불일치를 하나의 ledger로 수집한다.
-  - recovery overlay가 planner/checklist처럼 보이지 않게 한다.
+  - 더 이상 발견 즉시 감으로 수정하지 않고, severity와 affected flow 기준으로 정리한다.
 - 변경 범위:
-  - pause tray
+  - `/app`
-  - refocus tray
+  - `/space`
-  - next beat tray
+  - `/stats`
-  - goal complete tray
+  - 관련 카피 / query handoff / plan tier
-  - copy / hierarchy / material / motion polish
 - 제외 범위:
-  - multi-goal / list affordance 추가 금지
+  - visual redesign 직접 착수 금지
-  - social/accountability 확장 금지
+  - 새로운 feature spec 확장 금지
-  - review 통계 확장 금지
+  - `/settings`, `/admin` 구현 변경 금지
 - 완료 조건:
-  - refocus가 `편집 기능`이 아니라 `recovery ritual`처럼 읽힌다.
+  - `17_product_alignment_findings.md`가 생성된다
-  - pause / next beat / complete가 한 번에 하나만 보인다.
+  - 최소한 P1 / P2 finding이 route, promise, actual behavior, affected file 기준으로 정리된다
-  - bright/dark scene 모두에서 안정적으로 읽힌다.
+  - 이미 수정된 항목과 아직 열린 항목이 분리된다
 - 검증:
-  - 브라우저 수동 확인
+  - 문서 self-review
 - 커밋 힌트:
-  - feat(space): refocus-system polish
+  - docs(product): alignment findings ledger 시작
 
 ## 작업 2
 
-- 제목: `Away / Return Recovery` 구현
+- 제목: `Core Loop Alignment Audit` static slice
 - 목적:
-  - `11_away_return_recovery_spec.md` 기준으로 pause 없이 떠난 사용자의 복귀 흐름을 구현한다.
+  - `/app`, `/space`, `/stats`의 route-flow matrix와 state contract matrix를 만든다.
-  - `pause`, `break`, `return`이 같은 멈춤 상태처럼 읽히지 않게 한다.
+  - primary/secondary entry, CTA promise, 실제 상태 전환이 맞는지 정리한다.
 - 변경 범위:
-  - `visibilitychange`
+  - route/flow inventory
-  - `pagehide`
+  - state contract matrix
-  - sleep/wake delta 감지
+  - copy-behavior mismatch 정리
-  - return tray
-  - focus ended while away 처리
 - 제외 범위:
-  - webcam / idle tracking / 감시성 기능 금지
+  - visual polish 직접 수정 금지
-  - planner/list affordance 추가 금지
+  - recovery browser QA 금지
-  - break를 standard pause처럼 재사용 금지
 - 완료 조건:
-  - focus가 끝난 뒤 복귀하면 바로 standard break로 가지 않는다.
+  - `/app`, `/space`, `/stats`의 primary CTA와 secondary CTA가 표로 정리된다
-  - return 상태에서 `이어가기 / 한 조각 다시 잡기 / 지금부터 쉬기` 중 적절한 제안이 나온다.
+  - pause / return / complete / review handoff의 상태 의미가 문서화된다
+  - static mismatch가 severity와 함께 분류된다
 - 검증:
-  - 브라우저 수동 확인 + 상태 전이 점검
+  - source-of-truth 문서 대조
 - 커밋 힌트:
-  - feat(space): away-return-recovery
+  - docs(flow): core-loop alignment matrix 추가
 
 ## 작업 3
 
-- 제목: `Pause / Break / Return` 분리 polish
+- 제목: `Core Loop Alignment Audit` browser slice
 - 목적:
-  - 세 상태가 감정적으로도 구조적으로도 다르게 읽히도록 정리한다.
+  - static audit에서 나온 핵심 흐름을 브라우저에서 실제로 검증한다.
+  - 문서와 코드가 맞더라도 실제 체감이 어긋나는지를 잡는다.
 - 변경 범위:
-  - 카피
+  - `/app` first entry
-  - material
+  - `/app` resume
-  - tray hierarchy
+  - `/app -> /stats -> /app`
-  - timer/HUD와의 연결
+  - `/space` pause / return / next beat / complete
+  - `/space` complete -> setup -> weekly review teaser
 - 제외 범위:
-  - review 통계 확장 금지
+  - bulk visual redesign 금지
-  - social/accountability 확장 금지
+  - new feature 추가 금지
 - 완료 조건:
-  - pause는 recovery tone
+  - browser QA findings가 ledger에 반영된다
-  - break는 release tone
+  - P1/P2 mismatch는 수정 대상 라운드로 분리된다
-  - return은 re-entry tone으로 분리된다
-  - copy와 CTA hierarchy 2차 분리가 반영된다
-  - motion polish 1차가 반영된다
 - 검증:
-  - 브라우저 수동 확인
+  - manual browser QA
-  - motion 미세 조정
 - 커밋 힌트:
-  - feat(space): separate-pause-break-return
+  - docs(qa): core-loop browser audit 기록
-
-## 작업 4
-
-- 제목: `Weekly Review Entry Flow` 구현
-- 목적:
-  - `15_app_stats_entry_flow_spec.md` 기준으로 `/app -> /stats -> /app` loop를 실제 제품 루프에 연결한다.
-- 변경 범위:
-  - `/app` weekly review teaser
-  - `/stats` 마지막 CTA의 `/app` return handoff
-  - `/app` review-aware return state
-- 제외 범위:
-  - `/stats`에서 바로 `/space` auto-start 금지
-  - review teaser를 hero보다 강하게 노출하는 것 금지
-  - planner/todo 회고 흐름으로 확장 금지
-- 완료 조건:
-  - `/app`에서 review로 들어가는 primary path가 생긴다.
-  - `/stats`를 보고 다시 `/app`으로 돌아와 다음 세션을 시작할 수 있다.
-  - review가 읽고 끝나는 페이지가 아니라 next-session ritual처럼 동작한다.
-- 진행 상태:
-  - Slice 1 완료: `/app` hero 아래 low-emphasis weekly review teaser 추가
-  - Slice 2 완료: `/stats` 마지막 CTA가 `/app?review=weekly&carryHint=...` handoff로 연결
-  - `/app`은 query를 받아 review-aware return hint를 먼저 보여준다
-  - Slice 3 완료: Pro에서 추천 ritual과 더 구체적인 CTA / return hint가 연결된다
-  - Slice 4 완료: `/space` complete 이후 setup drawer 아래에 secondary review teaser가 노출된다
-  - 다음 작업: recovery browser QA 후 weekly review 실제 recovery 집계 연결
-- 검증:
-  - `/app -> /stats -> /app` 실제 브라우저 플로우 확인
-  - hero와 teaser의 시각 우선순위 확인
-- 커밋 힌트:
-  - feat(app): weekly-review-entry-flow