docs(docs): 화면별 current와 archive 구조로 분리

docs/README.md

@@ -31,7 +31,7 @@
   - 기획-구현 불일치 점검 계획
 - [17_product_alignment_findings.md](./product/17_product_alignment_findings.md) `source-of-truth`
   - 실제 불일치 ledger
-- [08_app_reframe_strategy.md](./screens/app/08_app_reframe_strategy.md) `legacy`
+- [08_app_reframe_strategy.md](./screens/app/archive/08_app_reframe_strategy.md) `legacy`
   - 초반 `/app` 방향 논의용 아이디어 문서
 
 ## 화면별 기획 문서
@@ -40,32 +40,38 @@
 
 `/app` 진입 경험, paused gate, review entry를 볼 때 읽는다.
 
-- [19_app_atmosphere_entry_spec.md](./screens/app/19_app_atmosphere_entry_spec.md) `source-of-truth`
+- [screens/app/README.md](./screens/app/README.md) `source-of-truth`
+  - `/app` current/archive 인덱스
+- [19_app_atmosphere_entry_spec.md](./screens/app/current/19_app_atmosphere_entry_spec.md) `source-of-truth`
   - `goal + duration + atmosphere` 중심의 새 `/app` 설계
-- [18_paused_session_reentry_spec.md](./screens/app/18_paused_session_reentry_spec.md) `source-of-truth`
-  - paused/running 상태에 따른 `/app <-> /space` 재진입 정책
-- [15_app_stats_entry_flow_spec.md](./screens/app/15_app_stats_entry_flow_spec.md) `source-of-truth`
-  - `/app -> /stats -> /app` review 진입/복귀 플로우
 
 ### `/space`
 
 `/space` HUD, refocus, break/return, goal card를 볼 때 읽는다.
 
-- [10_refocus_system_spec.md](./screens/space/10_refocus_system_spec.md) `source-of-truth`
+- [screens/space/README.md](./screens/space/README.md) `source-of-truth`
-  - pause/refocus/next-beat/goal-complete 구조
+  - `/space` current/archive 인덱스
-- [11_away_return_recovery_spec.md](./screens/space/11_away_return_recovery_spec.md) `source-of-truth`
+- [13_space_intent_card_collapsed_expanded_spec.md](./screens/space/current/13_space_intent_card_collapsed_expanded_spec.md) `source-of-truth`
-  - away/return 감지와 복귀 UX
-- [13_space_intent_card_collapsed_expanded_spec.md](./screens/space/13_space_intent_card_collapsed_expanded_spec.md) `source-of-truth`
   - 좌상단 목표 카드 구조
 
 ### `/stats`
 
 review 구조와 BM 연결을 볼 때 읽는다.
 
-- [14_weekly_review_reframe_spec.md](./screens/stats/14_weekly_review_reframe_spec.md) `source-of-truth`
+- [screens/stats/README.md](./screens/stats/README.md) `source-of-truth`
+  - `/stats` current/archive 인덱스
+- [14_weekly_review_reframe_spec.md](./screens/stats/current/14_weekly_review_reframe_spec.md) `source-of-truth`
   - weekly review를 행동 시스템으로 재정의한 문서
-- [15_app_stats_entry_flow_spec.md](./screens/app/15_app_stats_entry_flow_spec.md) `source-of-truth`
+
-  - `/stats` 진입/복귀 플로우
+## 플로우 문서
+
+두 화면 이상을 가로지르는 문서는 별도로 관리한다.
+
+- [flows/README.md](./flows/README.md) `source-of-truth`
+- [10_refocus_system_spec.md](./flows/current/10_refocus_system_spec.md) `source-of-truth`
+- [11_away_return_recovery_spec.md](./flows/current/11_away_return_recovery_spec.md) `source-of-truth`
+- [15_app_stats_entry_flow_spec.md](./flows/current/15_app_stats_entry_flow_spec.md) `source-of-truth`
+- [18_paused_session_reentry_spec.md](./flows/current/18_paused_session_reentry_spec.md) `source-of-truth`
 
 ## 개발 시 참고 문서
 
@@ -103,16 +109,19 @@ review 구조와 BM 연결을 볼 때 읽는다.
 ## 빠른 선택 가이드
 
 - `/app`을 수정한다:
-  - [19_app_atmosphere_entry_spec.md](./screens/app/19_app_atmosphere_entry_spec.md)
+  - [screens/app/README.md](./screens/app/README.md)
-  - [18_paused_session_reentry_spec.md](./screens/app/18_paused_session_reentry_spec.md)
+  - [19_app_atmosphere_entry_spec.md](./screens/app/current/19_app_atmosphere_entry_spec.md)
-  - [15_app_stats_entry_flow_spec.md](./screens/app/15_app_stats_entry_flow_spec.md)
+  - [18_paused_session_reentry_spec.md](./flows/current/18_paused_session_reentry_spec.md)
+  - [15_app_stats_entry_flow_spec.md](./flows/current/15_app_stats_entry_flow_spec.md)
 - `/space` recovery를 수정한다:
-  - [10_refocus_system_spec.md](./screens/space/10_refocus_system_spec.md)
+  - [screens/space/README.md](./screens/space/README.md)
-  - [11_away_return_recovery_spec.md](./screens/space/11_away_return_recovery_spec.md)
+  - [10_refocus_system_spec.md](./flows/current/10_refocus_system_spec.md)
-  - [13_space_intent_card_collapsed_expanded_spec.md](./screens/space/13_space_intent_card_collapsed_expanded_spec.md)
+  - [11_away_return_recovery_spec.md](./flows/current/11_away_return_recovery_spec.md)
+  - [13_space_intent_card_collapsed_expanded_spec.md](./screens/space/current/13_space_intent_card_collapsed_expanded_spec.md)
 - `/stats`를 수정한다:
-  - [14_weekly_review_reframe_spec.md](./screens/stats/14_weekly_review_reframe_spec.md)
+  - [screens/stats/README.md](./screens/stats/README.md)
-  - [15_app_stats_entry_flow_spec.md](./screens/app/15_app_stats_entry_flow_spec.md)
+  - [14_weekly_review_reframe_spec.md](./screens/stats/current/14_weekly_review_reframe_spec.md)
+  - [15_app_stats_entry_flow_spec.md](./flows/current/15_app_stats_entry_flow_spec.md)
 - 지금 다음 작업이 뭔지 본다:
   - [work.md](./work.md)
   - [session_brief.md](./session_brief.md)

docs/flows/README.md

@@ -0,0 +1,20 @@
+# Flow Docs
+
+여기는 특정 화면 하나에 속하지 않고, 두 화면 이상을 가로지르는 플로우 문서를 둔다.
+
+예:
+
+- `/app -> /stats -> /app`
+- paused session re-entry
+- refocus / away-return recovery
+
+## current
+
+- [10_refocus_system_spec.md](./current/10_refocus_system_spec.md)
+- [11_away_return_recovery_spec.md](./current/11_away_return_recovery_spec.md)
+- [15_app_stats_entry_flow_spec.md](./current/15_app_stats_entry_flow_spec.md)
+- [18_paused_session_reentry_spec.md](./current/18_paused_session_reentry_spec.md)
+
+## archive
+
+- 현재 없음

docs/product/12_core_loop_execution_roadmap.md

@@ -13,11 +13,11 @@ Last Updated: 2026-03-15
 
 - `../../product_principles.md`
 - `../../current_context.md`
-- `../screens/app/19_app_atmosphere_entry_spec.md`
+- `../screens/app/current/19_app_atmosphere_entry_spec.md`
-- `../screens/space/10_refocus_system_spec.md`
+- `../flows/current/10_refocus_system_spec.md`
-- `../screens/space/11_away_return_recovery_spec.md`
+- `../flows/current/11_away_return_recovery_spec.md`
-- `../screens/app/15_app_stats_entry_flow_spec.md`
+- `../flows/current/15_app_stats_entry_flow_spec.md`
-- `../screens/app/18_paused_session_reentry_spec.md`
+- `../flows/current/18_paused_session_reentry_spec.md`
 - `./16_product_alignment_audit_plan.md`
 
 ---
@@ -49,7 +49,7 @@ VibeRoom은 아래 방식으로 진행한다.
 
 ### 완료 2. `/app` Entry Reframe (Legacy)
 
-- 문서: historical, superseded by `../screens/app/19_app_atmosphere_entry_spec.md`
+- 문서: historical, superseded by `../screens/app/current/19_app_atmosphere_entry_spec.md`
 - 구현 상태:
   - `/app`은 한때 single-goal commitment gate로 정리됐음
   - planner/list-first 구조 제거
@@ -57,7 +57,7 @@ VibeRoom은 아래 방식으로 진행한다.
 
 ### 다음 Phase A. `/app` Atmosphere Entry Redesign
 
-- 문서: `../screens/app/19_app_atmosphere_entry_spec.md`
+- 문서: `../screens/app/current/19_app_atmosphere_entry_spec.md`
 - 목적:
   - `/app` no-session 상태를 `goal + duration + atmosphere` 중심의 premium entry stage로 재설계
   - scene/sound를 다시 entry 가치로 끌어올리되 planner/dashboard처럼 보이지 않게 유지
@@ -72,14 +72,14 @@ VibeRoom은 아래 방식으로 진행한다.
 
 ### 완료 3. Refocus System 기본 구조
 
-- 문서: `../screens/space/10_refocus_system_spec.md`
+- 문서: `../flows/current/10_refocus_system_spec.md`
 - 구현 상태:
   - pause -> refocus 흐름의 기본 skeleton 존재
   - next beat / goal complete의 상태 분리 시작
 
 ### 완료 4. Away / Return Recovery 기본 구현
 
-- 문서: `../screens/space/11_away_return_recovery_spec.md`
+- 문서: `../flows/current/11_away_return_recovery_spec.md`
 - 구현 상태:
   - `visibilitychange`, `pagehide`, sleep/wake gap 기반 detection 연결
   - focus running 복귀 시 `Return` tray 노출
@@ -98,7 +98,7 @@ VibeRoom은 아래 방식으로 진행한다.
 
 ### 끼어든 기획
 
-- `../screens/space/11_away_return_recovery_spec.md`
+- `../flows/current/11_away_return_recovery_spec.md`
 
 이 기획은 원래 흐름을 덮어쓴 것이 아니다.
 이 문서는 **Refocus System을 실제 사용자 행동에 맞게 완성하기 위해 중간에 추가된 필수 slice**다.
@@ -134,7 +134,7 @@ VibeRoom은 아래 방식으로 진행한다.
 
 문서:
 
-- `../screens/space/10_refocus_system_spec.md`
+- `../flows/current/10_refocus_system_spec.md`
 
 목적:
 
@@ -152,7 +152,7 @@ VibeRoom은 아래 방식으로 진행한다.
 
 문서:
 
-- `../screens/space/11_away_return_recovery_spec.md`
+- `../flows/current/11_away_return_recovery_spec.md`
 
 목적:
 
@@ -201,14 +201,14 @@ VibeRoom은 아래 방식으로 진행한다.
 
 문서:
 
-- `../screens/stats/14_weekly_review_reframe_spec.md`
+- `../screens/stats/current/14_weekly_review_reframe_spec.md`
-- `../screens/app/15_app_stats_entry_flow_spec.md`
+- `../flows/current/15_app_stats_entry_flow_spec.md`
 
 ### Phase 5.5. Session Routing / Paused Re-entry Alignment
 
 문서:
 
-- `../screens/app/18_paused_session_reentry_spec.md`
+- `../flows/current/18_paused_session_reentry_spec.md`
 
 목적:
 

docs/product/16_product_alignment_audit_plan.md

@@ -69,12 +69,12 @@ Audit 중 충돌이 생기면 아래 순서로 판단한다.
 1. `product_principles.md`
 2. `/Users/ijeongmin/Desktop/corpi/viberoom/current_context.md`
 3. route/flow 관련 상세 spec
-   - `../screens/app/19_app_atmosphere_entry_spec.md`
+   - `../screens/app/current/19_app_atmosphere_entry_spec.md`
-   - `../screens/space/10_refocus_system_spec.md`
+   - `../flows/current/10_refocus_system_spec.md`
-   - `../screens/space/11_away_return_recovery_spec.md`
+   - `../flows/current/11_away_return_recovery_spec.md`
-   - `../screens/space/13_space_intent_card_collapsed_expanded_spec.md`
+   - `../screens/space/current/13_space_intent_card_collapsed_expanded_spec.md`
-   - `../screens/stats/14_weekly_review_reframe_spec.md`
+   - `../screens/stats/current/14_weekly_review_reframe_spec.md`
-   - `../screens/app/15_app_stats_entry_flow_spec.md`
+   - `../flows/current/15_app_stats_entry_flow_spec.md`
 4. `90_current_state.md`
 5. 실제 코드
 

docs/product/17_product_alignment_findings.md

@@ -59,15 +59,15 @@ Last Updated: 2026-03-15
 | ID | Severity | Area | Product Promise | Actual Behavior | Affected Files | Status | Next Action |
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | ALN-001 | P1 | `/space` Goal Complete / Break semantics | `잠깐 쉬기`는 블록을 닫고 break로 넘어가는 것처럼 읽힘 | 실제로는 overlay만 닫고 reminder만 예약되어 break 의미가 깨졌음 | `src/widgets/space-focus-hud/ui/SpaceFocusHudWidget.tsx`, `src/shared/i18n/messages/space.ts` | fixed-awaiting-browser | `잠시 비우기 -> pause + reminder`가 실제 체감상도 맞는지 브라우저 확인 |
-| ALN-002 | P1 | `/app` Weekly Review primary entry | `/app`이 Weekly Review의 primary entry라고 정의됨 | current session이 있으면 review entry가 완전히 사라져 primary entry가 끊겼음 | `src/widgets/focus-dashboard/ui/FocusDashboardWidget.tsx`, `docs/screens/app/15_app_stats_entry_flow_spec.md` | fixed-awaiting-browser | resume 상태에서 review entry 발견성과 우선순위 확인 |
+| ALN-002 | P1 | `/app` Weekly Review primary entry | `/app`이 Weekly Review의 primary entry라고 정의됨 | current session이 있으면 review entry가 완전히 사라져 primary entry가 끊겼음 | `src/widgets/focus-dashboard/ui/FocusDashboardWidget.tsx`, `docs/flows/current/15_app_stats_entry_flow_spec.md` | fixed-awaiting-browser | resume 상태에서 review entry 발견성과 우선순위 확인 |
 | ALN-003 | P2 | `/space` secondary review teaser | `방금 끝낸 흐름까지 review에 담아둘까요?`처럼 read-after-write를 약속했음 | 실제로는 generic `/stats`만 열고, 방금 끝낸 흐름을 별도 handoff하지 않았음 | `src/shared/i18n/messages/space.ts`, `src/widgets/space-workspace/ui/SpaceWorkspaceWidget.tsx` | fixed-awaiting-browser | setup drawer teaser가 과장 없이 자연스럽게 읽히는지 확인 |
 | ALN-004 | P1 | Pro personalized handoff | `/stats`에서 추천 ritual로 돌아간다고 말했음 | 실제로는 `/app` 문구만 바뀌고 start behavior는 기본 ritual 그대로였음 | `src/widgets/focus-dashboard/ui/FocusDashboardWidget.tsx`, `src/shared/i18n/messages/app.ts` | fixed-awaiting-browser | `entryPreset`이 실제 scene/sound/timer 시작값으로 적용되는지 검증 |
-| ALN-005 | P2 | `/space` intent card interaction | rail, edit, expand/collapse의 역할이 분리돼야 함 | goal 클릭과 edit 진입이 섞여 예측 가능성이 낮았음 | `src/widgets/space-focus-hud/ui/IntentCapsule.tsx`, `docs/screens/space/13_space_intent_card_collapsed_expanded_spec.md` | fixed-awaiting-browser | desktop/mobile에서 expand와 edit 구분이 분명한지 확인 |
+| ALN-005 | P2 | `/space` intent card interaction | rail, edit, expand/collapse의 역할이 분리돼야 함 | goal 클릭과 edit 진입이 섞여 예측 가능성이 낮았음 | `src/widgets/space-focus-hud/ui/IntentCapsule.tsx`, `docs/screens/space/current/13_space_intent_card_collapsed_expanded_spec.md` | fixed-awaiting-browser | desktop/mobile에서 expand와 edit 구분이 분명한지 확인 |
 | ALN-006 | P2 | `/space` Goal Complete 2단계 인지 | 1단계 choice와 2단계 next 입력이 명확히 구분돼야 함 | 사용자 입장에서는 `돌아가기 / 다음 목표로 바로 시작` 화면이 top-level 분기처럼 읽히기 쉬움 | `src/widgets/space-focus-hud/ui/GoalCompleteSheet.tsx`, `src/shared/i18n/messages/space.ts` | open | choice view와 next view의 제목, 구조, motion, context label을 더 분리하는 기획 필요 |
-| ALN-007 | P2 | Weekly Review discoverability | review는 `/app`의 primary ritual이어야 함 | 데이터 gate와 currentSession 조건에 따라 사용자에게 “아예 없는 기능”처럼 느껴질 수 있음 | `src/widgets/focus-dashboard/ui/FocusDashboardWidget.tsx`, `docs/screens/app/15_app_stats_entry_flow_spec.md` | open | low-data 상태와 resume 상태를 포함한 discoverability 정책 재정의 |
+| ALN-007 | P2 | Weekly Review discoverability | review는 `/app`의 primary ritual이어야 함 | 데이터 gate와 currentSession 조건에 따라 사용자에게 “아예 없는 기능”처럼 느껴질 수 있음 | `src/widgets/focus-dashboard/ui/FocusDashboardWidget.tsx`, `docs/flows/current/15_app_stats_entry_flow_spec.md` | open | low-data 상태와 resume 상태를 포함한 discoverability 정책 재정의 |
-| ALN-008 | P1 | `잠시 비우기`와 `Break`의 제품 의미 | break는 reward/reset, pause는 recovery로 분리돼야 함 | 현재는 카피와 트레이는 개선됐지만, 제품 차원의 최종 정의와 시각 분리까지 완전히 닫히진 않았음 | `docs/screens/space/10_refocus_system_spec.md`, `docs/screens/space/11_away_return_recovery_spec.md`, `src/widgets/space-focus-hud/ui/GoalCompleteSheet.tsx`, `src/widgets/space-focus-hud/ui/ReturnPrompt.tsx` | open | `잠시 비우기`, active break, return(break)를 하나의 최종 state model로 재정의 |
+| ALN-008 | P1 | `잠시 비우기`와 `Break`의 제품 의미 | break는 reward/reset, pause는 recovery로 분리돼야 함 | 현재는 카피와 트레이는 개선됐지만, 제품 차원의 최종 정의와 시각 분리까지 완전히 닫히진 않았음 | `docs/flows/current/10_refocus_system_spec.md`, `docs/flows/current/11_away_return_recovery_spec.md`, `src/widgets/space-focus-hud/ui/GoalCompleteSheet.tsx`, `src/widgets/space-focus-hud/ui/ReturnPrompt.tsx` | open | `잠시 비우기`, active break, return(break)를 하나의 최종 state model로 재정의 |
-| ALN-009 | P3 | Spec / current-state drift | 다음 세션 문서가 실제 구현과 맞아야 함 | intent card, goal complete, review entry 관련 오래된 표현이 여러 spec에 남아 있었음 | `docs/screens/space/10_refocus_system_spec.md`, `docs/screens/space/13_space_intent_card_collapsed_expanded_spec.md`, `docs/90_current_state.md`, `docs/session_brief.md`, `../../current_context.md` | fixed-awaiting-browser | 이후 라운드부터는 fix와 문서 갱신을 같은 커밋에서 닫는지 점검 |
+| ALN-009 | P3 | Spec / current-state drift | 다음 세션 문서가 실제 구현과 맞아야 함 | intent card, goal complete, review entry 관련 오래된 표현이 여러 spec에 남아 있었음 | `docs/flows/current/10_refocus_system_spec.md`, `docs/screens/space/current/13_space_intent_card_collapsed_expanded_spec.md`, `docs/90_current_state.md`, `docs/session_brief.md`, `../../current_context.md` | fixed-awaiting-browser | 이후 라운드부터는 fix와 문서 갱신을 같은 커밋에서 닫는지 점검 |
-| ALN-010 | P1 | paused session 재진입 정책 | running은 바로 `/space`, paused는 `/app` resume gate, explicit continue 이후에는 자동 resume이어야 함 | Session Routing Contract, paused resume gate, auto-resume handoff, takeover flow까지 구현됐다. 남은 것은 browser QA와 takeover wording polish이다 | `docs/screens/app/18_paused_session_reentry_spec.md`, `src/widgets/focus-dashboard/ui/FocusDashboardWidget.tsx`, `src/widgets/space-workspace/ui/SpaceWorkspaceWidget.tsx`, `src/features/focus-session/model/useFocusSessionEngine.ts` | fixed-awaiting-browser | paused resume / refocus / takeover 3경로를 브라우저에서 확인 |
+| ALN-010 | P1 | paused session 재진입 정책 | running은 바로 `/space`, paused는 `/app` resume gate, explicit continue 이후에는 자동 resume이어야 함 | Session Routing Contract, paused resume gate, auto-resume handoff, takeover flow까지 구현됐다. 남은 것은 browser QA와 takeover wording polish이다 | `docs/flows/current/18_paused_session_reentry_spec.md`, `src/widgets/focus-dashboard/ui/FocusDashboardWidget.tsx`, `src/widgets/space-workspace/ui/SpaceWorkspaceWidget.tsx`, `src/features/focus-session/model/useFocusSessionEngine.ts` | fixed-awaiting-browser | paused resume / refocus / takeover 3경로를 브라우저에서 확인 |
 
 ---
 

docs/screens/app/README.md

@@ -0,0 +1,22 @@
+# `/app` Docs
+
+`/app` 화면 관련 문서를 모아둔 폴더다.
+
+## current
+
+지금 `/app` 작업에 직접 영향을 주는 source-of-truth 문서다.
+
+- [19_app_atmosphere_entry_spec.md](./current/19_app_atmosphere_entry_spec.md)
+
+## archive
+
+이전 `/app` 방향이나 구현 완료 후 더 이상 기준 문서가 아닌 자료다.
+
+- [08_app_reframe_strategy.md](./archive/08_app_reframe_strategy.md)
+
+## 같이 볼 문서
+
+`/app`은 화면 자체 문서 외에도 cross-screen flow 영향을 많이 받는다.
+
+- [../../flows/current/15_app_stats_entry_flow_spec.md](../../flows/current/15_app_stats_entry_flow_spec.md)
+- [../../flows/current/18_paused_session_reentry_spec.md](../../flows/current/18_paused_session_reentry_spec.md)

docs/screens/space/README.md

@@ -0,0 +1,18 @@
+# `/space` Docs
+
+`/space` 화면 자체 구조와 시각 규칙 문서를 모아둔 폴더다.
+
+## current
+
+- [13_space_intent_card_collapsed_expanded_spec.md](./current/13_space_intent_card_collapsed_expanded_spec.md)
+
+## archive
+
+- 현재 없음
+
+## 같이 볼 문서
+
+`/space`는 recovery flow 문서와 함께 읽어야 한다.
+
+- [../../flows/current/10_refocus_system_spec.md](../../flows/current/10_refocus_system_spec.md)
+- [../../flows/current/11_away_return_recovery_spec.md](../../flows/current/11_away_return_recovery_spec.md)

docs/screens/stats/README.md

@@ -0,0 +1,17 @@
+# `/stats` Docs
+
+`/stats` 화면의 review 구조 문서를 모아둔 폴더다.
+
+## current
+
+- [14_weekly_review_reframe_spec.md](./current/14_weekly_review_reframe_spec.md)
+
+## archive
+
+- 현재 없음
+
+## 같이 볼 문서
+
+`/stats`는 `/app` 진입/복귀 플로우와 함께 읽어야 한다.
+
+- [../../flows/current/15_app_stats_entry_flow_spec.md](../../flows/current/15_app_stats_entry_flow_spec.md)

docs/work.md

@@ -20,7 +20,7 @@
 
 - 제목: `/app` Atmosphere Entry Shell
 - 목적:
-  - `docs/screens/app/19_app_atmosphere_entry_spec.md` 기준으로 `/app` no-session 상태를 `goal + duration + atmosphere` 중심의 premium entry screen으로 재설계한다.
+  - `docs/screens/app/current/19_app_atmosphere_entry_spec.md` 기준으로 `/app` no-session 상태를 `goal + duration + atmosphere` 중심의 premium entry screen으로 재설계한다.
   - entry에서 scene/sound의 감각 품질을 다시 살리되 planner/dashboard 톤으로 흐르지 않게 만든다.
 - 변경 범위:
   - no-session `/app` shell