PresenceWith · PresenceWith · Mar 13, 2026 · Mar 13, 2026 · Mar 13, 2026
diff --git a/agents/vync-translator.md b/agents/vync-translator.md
@@ -33,11 +33,18 @@ permissionMode: bypassPermissions
 
 ## 반환 포맷
 
-**성공 시**: 한 줄 요약만 반환. 추가 설명 불필요.
-- create: `"mindmap: 프로젝트 > [기획, 개발, 출시]"`
-- read (변경 있음): `"변화 요약: 개발 프로세스에 테스팅이 추가되고, 기획의 리서치가 축소됨. 실행 중심으로 구조가 이동하는 방향."`
-- read (변경 없음): `"mindmap: 프로젝트 > [기획, 개발] (변경 없음)"`
-- update: `"updated: 개발 > [FE, BE, +테스트, +CI/CD]"`
+**create**: 한 줄 요약. 예: `"mindmap: 프로젝트 > [기획, 개발, 출시]"`
+**update**: 한 줄 요약. 예: `"updated: 개발 > [FE, BE, +테스트, +CI/CD]"`
+
+**read (변경 있음)**: 구조화 반환 (3-5줄)
+```
+요약: <구조적 변경의 사실적 기술>
+의도: <변경이 시사하는 사용자의 생각/판단 추론>
+확신: <높음|중간|낮음> (<근거>)
+제안: <추론 기반 다음 행동 제안, optional>
+```
+
+**read (변경 없음)**: `"요약: 변경 없음"`
 
 **실패 시**: `"error: <간략한 설명>"` 형식으로 반환.
 예: `"error: 파일을 찾을 수 없습니다"`, `"error: JSON 검증 실패 — 중복 ID"`
@@ -56,10 +63,17 @@ permissionMode: bypassPermissions
 
 ### Read
 1. 전달받은 diff 결과를 분석 (직접 JSON 비교하지 않음!)
-2. 대화 맥락과 결합하여 "생각의 변화"를 의미적으로 번역
-3. 반환: 변화의 의미 요약
-   예: "개발 프로세스에 테스팅이 추가되고, 기획의 리서치가 축소됨. 실행 중심으로 구조가 이동하는 방향."
-4. 스냅샷 갱신은 vync diff가 이미 처리 (sub-agent에서 안 함)
+2. **semanticHint가 있으면 이를 기반으로**, 없으면 구조+유형에서 직접 추론
+3. 대화 맥락과 결합하여 "사용자의 생각이 어떻게 변했는지" 번역
+4. 확신 레벨 판단:
+   - **높음**: mindmap 위계 변경, 명확한 추가/삭제
+   - **중간**: 다중 동시 이동, 복합 변경
+   - **낮음**: 의미 불분명한 소규모 변경
+5. 변화의 **방향성** 포착:
+   - 구조 변경이 시사하는 사고의 전환 (예: "독립 개념 → 종속 개념")
+   - 복합 변경에서 드러나는 의도 패턴 (예: "실행 중심으로 구조 이동")
+6. 반환: 4-필드 구조화 (요약/의도/확신/제안)
+7. 스냅샷 갱신은 vync diff가 이미 처리 (sub-agent에서 안 함)
 
 ### Update
 1. 대화 맥락 + diff 이해

diff --git a/commands/vync.md b/commands/vync.md
@@ -72,7 +72,13 @@ Agent({
 })
 ```
 
-5. Sub-agent의 의미적 번역을 대화에 통합
+5. Sub-agent의 구조화된 반환을 활용:
+   - **확신 높음**: 의도를 대화에 자연스럽게 반영 + 제안 전달
+     예: "기획의 세부 활동으로 리서치를 보시는 것 같은데, 개발 쪽도 정리할까요?"
+   - **확신 중간**: 추론 언급 + 확인 포함
+     예: "A-B, C-D로 묶으셨네요. 이 구분으로 진행할까요?"
+   - **확신 낮음**: 요약(사실)만 간략히 언급, 의도 추론은 하지 않음
+     예: "구조에 약간 변화가 있네요."
 
 ### Update
 

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -363,7 +363,7 @@ Vync/                              # nx monorepo (Drawnix 포크 기반)
 │       └── __tests__/
 │           ├── init.test.ts       # init 유닛 테스트
 │           ├── open.test.ts       # smart restart + vyncStop 유닛 테스트
-│           └── diff.test.ts       # diff 엔진 유닛 테스트 (15개)                          [VYNC 추가: D-015]
+│           └── diff.test.ts       # diff 엔진 유닛 테스트 (31개: 구조적 diff 16 + semantic hint 15)  [VYNC 추가: D-015, D-017]
 ├── bin/
 │   └── vync.js                    # CLI 진입점 (CommonJS, tsx spawn) [VYNC 추가]
 ├── .claude-plugin/                # Claude Code 플러그인 메타 (marketplace 표준) [VYNC 추가]

diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
@@ -26,6 +26,7 @@
 | D-015 | [Diff 파이프라인: Hybrid Architecture](#d-015) | 확정 | 2026-03-11 |
 | D-016 | [Sub-agent 역할 확장: 시각화 전문가](#d-016) | 확정 | 2026-03-11 |
 | D-017 | [의미적 동기화: Semantic Sync](#d-017) | 확정 | 2026-03-13 |
+| D-018 | [파일 유형 정책: 한 파일 = 한 시각화 유형](#d-018) | 확정 | 2026-03-13 |
 
 ---
 
@@ -405,7 +406,37 @@ Level 3: Confirmed Intent   사용자 확인 (필요시에만)
 | 항상 명시적 확인 | 대화 흐름 중단, Vync 철학(D-007) 위배 |
 
 **핵심 원칙**: 오추론의 비용이 낮음 (자연어 정정 한마디). **자연스러움 > 정확도**.
-**구현**: diff.ts semantic annotation + translator prompt 강화 + 반환 포맷 확장 (~80 LOC)
+**구현 세부 결정 (S-1~S-4)**:
+- **S-1**: 파일 레벨 유형 감지 (D-018에 의해 혼합 캔버스 구조적 방지)
+- **S-2**: 복합 패턴은 다중 moved(그룹화)만 (Phase 1). moved+modified 결합은 관찰 후 결정.
+- **S-3**: 확신 낮음 시 간략히 언급 ("구조에 약간 변화가 있네요"). 무시 안 함.
+- **S-4**: enrichWithSemanticHints()를 computeDiff와 분리. 기존 테스트 무변경.
+
+**구현**: diff.ts semantic annotation + translator prompt 강화 + 반환 포맷 확장 (~95 LOC)
 **설계 문서**: `docs/plans/2026-03-13-semantic-sync-design.md`
+**구현 계획**: `docs/plans/2026-03-13-semantic-sync.md`
 
 **재검토 조건**: semantic hint가 translator 추론 품질을 유의미하게 향상시키지 못할 경우
+
+---
+
+### D-018
+
+**파일 유형 정책: 한 파일 = 한 시각화 유형**
+
+하나의 `.vync` 파일에는 하나의 시각화 유형만 포함한다. 다른 유형이 필요하면 별도 파일을 생성한다.
+
+- **mindmap** 파일에 flowchart 노드를 혼합하지 않음
+- 대화 중 다른 시각화 형식이 필요하면 `/vync create`로 새 파일 생성
+- vync-translator의 create/update 시 기존 파일의 유형을 유지
+
+| 대안 | 기각 사유 |
+|------|----------|
+| 혼합 캔버스 허용 | 유형별 semantic annotation이 노드 레벨로 복잡해짐, 해석 안정성 저하 |
+| 파일 내 섹션으로 유형 분리 | .vync 포맷에 섹션 개념 없음, 복잡성 증가 |
+
+**근거**: D-017(Semantic Sync)에서 파일 레벨 유형 감지를 채택한 전제 조건. 혼합 캔버스를 방지하면 시각화 유형 감지가 구조적으로 안전해지고, semantic annotation의 정확도가 보장됨. 멀티 파일/멀티 탭(D-014)이 이미 지원되므로 별도 파일 생성의 UX 비용이 낮음.
+
+**영향 범위**: vync-translator (create/update 행동 규칙), diff.ts (파일 레벨 유형 감지 근거)
+
+**재검토 조건**: 사용자가 한 캔버스에서 여러 유형을 동시에 필요로 하는 패턴이 빈번히 발생할 경우
diff --git a/docs/PLAN.md b/docs/PLAN.md
@@ -13,7 +13,7 @@
 - Server Lifecycle Fix (PR #10): 완료 (2026-03-11)
 - macOS 코드 서명 + 공증: 완료 (2026-03-11)
 - Tab Bar "+" 버튼 수정 (PR #11): 구현 완료, PR 대기 (2026-03-12)
-- Semantic Sync (D-017): 설계 완료, 구현 대기 (2026-03-13) — `docs/plans/2026-03-13-semantic-sync.md`
+- Semantic Sync (D-017): 구현 완료, PR 대기 (2026-03-13) — `feat/semantic-sync` 브랜치
 
 ---
 
@@ -189,7 +189,7 @@
 - [x] 7-P1.3 vync 커맨드 Read 섹션에 diff 컨텍스트 반영
 - [x] 7-P1.4 설계문서 데이터 흐름 업데이트
 - [x] `/vync create` → sub-agent → 한 줄 요약 반환 흐름 동작
-- [x] Install script가 에이전트 파일을 `~/.claude/agents/`에 설치
+- [x] Install script가 플러그인을 마켓플레이스 캐시에 설치 (`install.sh` → rsync)
 
 ---
 
@@ -349,6 +349,35 @@
 
 ---
 
+## Semantic Sync (D-017/D-018)
+
+**목표**: diff의 구조적 변경에 시각화 유형별 semantic annotation을 추가하고, Sub-agent가 맥락과 결합하여 사용자 의도를 추론하는 파이프라인 개선.
+**브랜치**: `feat/semantic-sync`
+**설계**: `docs/plans/2026-03-13-semantic-sync-design.md`
+**구현 계획**: `docs/plans/2026-03-13-semantic-sync.md`
+
+- [x] SS.1 DiffChange 타입에 `semanticHint` 필드 추가
+- [x] SS.2 `detectVizType()` — 파일 레벨 시각화 유형 감지 (S-1)
+- [x] SS.3 `enrichWithSemanticHints()` — computeDiff와 분리된 semantic layer (S-4)
+- [x] SS.4 다중 moved 그룹화 패턴 감지 (S-2)
+- [x] SS.5 `formatDiffResult` hint 포함 출력
+- [x] SS.6 신규 테스트 15개 추가 (총 31 diff 테스트, 93 전체 PASS)
+- [x] SS.7 translator prompt: Read 반환 4-필드 구조화 (요약/의도/확신/제안)
+- [x] SS.8 translator prompt: Read 절차 해석 가이드 + 확신 레벨 판단
+- [x] SS.9 vync.md: 확신 레벨별 메인 세션 활용 가이드 (S-3)
+- [x] SS.10 플러그인 캐시 동기화 완료
+
+**완료 기준**:
+- [x] `vync diff`가 mindmap에서 semanticHint 포함 출력
+- [x] translator가 Read 시 4-필드 구조화 반환
+- [x] 메인 세션이 확신 레벨별 행동 가이드 보유
+- [x] 93개 전체 테스트 PASS (diff 31개 포함)
+
+### 남은 작업
+- PR 생성 (feat/semantic-sync → develop)
+
+---
+
 ## 리스크
 
 | 리스크 | 영향 | 완화 방안 | 평가 시점 |

diff --git a/docs/plans/2026-03-13-semantic-sync-design.md b/docs/plans/2026-03-13-semantic-sync-design.md
@@ -266,7 +266,7 @@ translator: "요약: A→B 하위, C→D 하위로 이동\n의도: 쌍별 그룹
 확신 낮음:
 ```
 translator: "요약: 노드 3개 위치 약간 조정\n의도: 시각적 정리로 추정\n확신: 낮음\n제안: 없음"
-→ 메인: (언급하지 않거나) "구조에 큰 변화는 없네요."
+→ 메인: "구조에 약간 변화가 있네요." (간략히 언급, 의도 추론 없이)
 ```
 
 ---
@@ -292,8 +292,9 @@ Vync의 핵심 철학은 **대화 흐름을 끊지 않는 것**. 의도가 모
 
 **Type C: 의미 판단 어려움** (낮은 확신)
 - 예: 레이아웃만 약간 조정 (diff가 감지 못하거나 layout 필드만 변경)
-- 처리: 구조적 사실만 보고, 의도 추론 시도하지 않음
-- "구조 변경이 감지되지 않았습니다" 또는 사실만 전달
+- 처리: 구조적 사실(요약)만 **간략히 언급**, 의도 추론은 하지 않음
+- 예: "구조에 약간 변화가 있네요." — 변경 사실은 전달하되 해석 없이
+- **주의**: 완전히 무시하지 않음. 사용자의 의도적 변경을 놓치는 것보다 간략한 언급이 안전
 
 ### 확인의 형태
 
@@ -324,7 +325,7 @@ Vync의 핵심 철학은 **대화 흐름을 끊지 않는 것**. 의도가 모
 
 2. **단일 스냅샷 한계**: .lastread가 하나뿐이므로, "A→B→C" 3단계 변경에서 중간 단계 B를 놓침. 사용자가 여러 번 수정한 후 read하면 최종 결과만 보임.
 
-3. **시각화 유형 정보 부재**: 현재 .vync 파일에 명시적 "type" 필드가 없음. elements의 구조(mindmap children vs geometry+arrow)로 유추해야 함. 혼합 캔버스(mindmap + flowchart)에서는 유형별 해석이 복잡해짐.
+3. ~~**시각화 유형 정보 부재**~~: **D-018에 의해 해소**. "한 파일 = 한 시각화 유형" 원칙으로 혼합 캔버스를 구조적으로 방지. 파일 레벨 유형 감지(root 노드 type 확인)로 충분.
 
 ### LLM 추론 한계
 
@@ -340,14 +341,30 @@ Vync의 핵심 철학은 **대화 흐름을 끊지 않는 것**. 의도가 모
 
 ---
 
-## 7. 구현 로드맵 (이후 세션 참조)
+## 7. 구현 세부 결정 (2026-03-13 확정)
+
+리뷰를 통해 확정된 구현 세부 결정:
+
+| ID | 항목 | 결정 | 근거 |
+|----|------|------|------|
+| S-1 | 시각화 유형 감지 단위 | **파일 레벨** | D-018("한 파일 = 한 유형")에 의해 혼합 캔버스 구조적 방지. generic 폴백으로 안전. |
+| S-2 | 복합 패턴 범위 | **다중 moved(그룹화)만** | 가장 빈번하고 의미 명확. moved+modified 결합("재해석")은 실사용 관찰 후 결정. |
+| S-3 | 확신 낮음 시 행동 | **간략히 언급** | 무시보다 안전. "구조에 약간 변화가 있네요" — 사용자가 이어서 말하거나 무시 가능. |
+| S-4 | semanticHint 생성 위치 | **computeDiff와 분리** | enrichWithSemanticHints() 별도 함수. computeDiff 순수성 유지, 테스트 독립. |
+
+**관련 결정**: D-018 (한 파일 = 한 시각화 유형) — 이 설계에서 도출되어 별도 결정으로 등록됨.
+
+---
+
+## 8. 구현 로드맵 (이후 세션 참조)
 
 ### Phase 1: diff.ts semantic annotation (~50 LOC)
 - DiffChange에 `semanticHint` 필드 추가
-- 시각화 유형 감지 로직 (elements 구조 기반)
-- 유형별 hint 생성 규칙 적용
+- `detectVizType()` — 파일 레벨 유형 감지 (S-1)
+- `enrichWithSemanticHints()` — computeDiff와 분리된 별도 함수 (S-4)
+- 개별 hint 생성 + 다중 moved 그룹화만 (S-2)
 - formatDiffResult에 hint 포함
-- 기존 테스트 + semantic hint 테스트 추가
+- 기존 computeDiff 테스트 무변경 + enrichWithSemanticHints 테스트 추가
 
 ### Phase 2: translator prompt 강화 (~30 LOC)
 - Read 절차에 해석 가이드 추가 (§3 해석 규칙 참조)
@@ -362,7 +379,7 @@ Vync의 핵심 철학은 **대화 흐름을 끊지 않는 것**. 의도가 모
 - 확신 레벨별 메인 세션 행동 가이드:
   - 높음 → 자연스럽게 반영 + 제안 활용
   - 중간 → 추론 + 확인 포함
-  - 낮음 → 사실만 전달
+  - 낮음 → 사실만 간략히 언급 (S-3)
 - "추론 + 자연스러운 확인" 패턴 예시
 
 ### 예상 변경 규모
@@ -372,7 +389,7 @@ Vync의 핵심 철학은 **대화 흐름을 끊지 않는 것**. 의도가 모
 
 ---
 
-## 8. 설계 결정
+## 9. 설계 결정
 
 ### D-017: Semantic Sync (의미적 동기화)