docs(plan): v0.3.0 Cut E — 양방향 git sync (spec 정정: 단위 608, ImportService.run 활용, 'sync' enum 미도입, both deferred)

docs/superpowers/specs/2026-05-09-v030-cut-e-design.md

@@ -38,60 +38,81 @@ async sync(opts: { interval?: boolean } = {}): Promise<SyncStatus> {
 
   const git = new GitClient(this.syncDir);
 
-  // 1. fetch
-  const fetchR = await git.fetch();
-  if (fetchR.exitCode !== 0) return { ok: false, reason: `fetch failed: ${fetchR.stderr}` };
-
-  // 2. local export (변경 감지 위해)
+  // 1. local export — 현재 SQLite 상태를 syncDir 에 markdown 으로 출력
   await this.exportSvc.export(this.syncDir, { includeMedia: true });
   await git.addAll();
   const localChanged = await git.hasUncommittedChanges();
 
-  // 3. local commit (있으면)
+  // 2. local commit (변경 있으면)
   let localSha: string | null = null;
   if (localChanged) {
     const c = await git.commit(`chore(notes): sync ${this.now().toISOString()}`);
     localSha = c.sha;
   }
 
-  // 4. rebase
+  // 3. fetch
+  const fetchR = await git.fetch();
+  if (fetchR.exitCode !== 0) return { ok: false, reason: `fetch failed: ${fetchR.stderr}` };
+
+  // 4. rebase onto origin/main
   const rebaseR = await git.rebaseOnto('origin/main');
   if (rebaseR.exitCode !== 0) {
-    // conflict — abort + 사용자에게 conflict UI 안내
+    // conflict — abort + conflict 목록 반환 (UI 가 활성)
     await git.rebaseAbort();
-    return { ok: false, reason: 'conflict', conflicts: await this.listConflicts() };
+    return { ok: false, reason: 'conflict', conflicts: await this.listConflictsFromMarkdown() };
   }
 
-  // 5. re-import (rebase 후 markdown 변경 → SQLite 적용)
-  const imported = await this.importSvc.importAll(this.syncDir);
+  // 5. re-import (rebase 후 markdown 변경 → SQLite upsertFromSync)
+  const imported = await this.importSvc.applySyncFromDir(this.syncDir);
 
   // 6. push
-  const pushR = await git.push();
-  if (pushR.exitCode !== 0) return { ok: false, reason: `push failed: ${pushR.stderr}` };
+  try { await git.push(); } catch (e) { return { ok: false, reason: `push failed: ${(e as Error).message}` }; }
 
   return { ok: true, changed: localChanged || imported.changedCount > 0, localSha, importedCount: imported.changedCount, pushed: true };
 }
 ```
 
-### 3-2. ImportService 활용
+**6 단계 흐름 — local export 가 fetch 보다 먼저 (Cut E 정정)**: spec 초안은 fetch 우선이었으나, local export → commit 후 fetch + rebase 가 git workflow 표준 (rebase 가 local commit 위에 origin commit 적용). local export 안 한 상태로 fetch + rebase → 혼란 발생.
 
-기존 ImportService (백업 복원 흐름) 가 markdown → SQLite 적재. sync 의 re-import 도 같은 service 활용:
+`SyncStatus` 인터페이스 확장:
 
 ```ts
-class ImportService {
-  async importAll(dir: string): Promise<{ changedCount: number; conflicts: string[] }> {
-    // dir 하위의 모든 .md 파일 → frontmatter parse → notes UPSERT
-    // existing note 와 비교 — updated_at 더 최신이면 갱신, 아니면 skip
-    // raw_text 다른 경우 → note_revisions 에 INSERT (new rev, edited_by='sync')
-  }
+export interface SyncStatus {
+  ok: boolean;
+  reason?: string;
+  changed?: boolean;
+  localSha?: string | null;
+  pushed?: boolean;
+  importedCount?: number;
+  conflicts?: Array<{ noteId: string; localText: string; remoteText: string }>;  // reason='conflict' 시
 }
 ```
 
-**revision linear merge 정책**:
+### 3-2. ImportService 활용 (실제 코드 정정)
 
-- 옛 rev (origin/main 의 rev_5) 가 local 에 없으면 → INSERT note_revisions (timestamp 기준 적절 위치)
-- local rev 와 origin rev 가 동일 timestamp + 다른 raw_text → conflict (사용자 prompt)
-- 일반적으로 다른 timestamp 면 timestamp 순 linear chain 으로 merge
+기존 ImportService 는 `run(sourceDir)` 메서드 (백업 복원 흐름) — `parsedToInput` → `repo.importNote()` 호출. spec 작성 시 가정한 `importAll(dir)` 시그니처는 실재 코드와 다름.
+
+`repo.importNote()` 의 기존 conflict 정책 (export tree 복원용):
+
+- id 없음 → INSERT (`status: 'inserted'`)
+- id 있음 + raw_text 동일 → no-op (`status: 'skipped'`)
+- id 있음 + raw_text 다름 → fork-on-id-collision (fresh uuidv7) (`status: 'forked'`)
+
+**Cut E sync 정책 — fork 미적합, in-place update + revision 보존**:
+
+sync 에서 양 기기 raw_text 가 다를 때 fork 하면 노트 갯수 무한 증가 → 부적합. 신설 메서드 `repo.upsertFromSync(input)`:
+
+- id 없음 → INSERT (m006 trigger 가 capture revision 자동 생성)
+- id 있음 + raw_text 동일 → metadata 갱신 path
+  - source.updatedAt > local.updatedAt 인 경우만 ai_title/ai_summary/tags/status/dueDate 갱신
+  - tags 변경 시 `rebuildFtsTagsForNote` 호출 (Cut D single write path)
+  - 동등/older 면 skip
+- id 있음 + raw_text 다름 → 옵션 분기:
+  - source.updatedAt > local.updatedAt → `updateRawText(id, sourceRawText, sourceUpdatedAt)` (Cut C single write path) → 새 user revision INSERT, latest = source
+  - local.updatedAt > source.updatedAt → skip (다음 push 가 source 갱신할 것)
+  - 동일 timestamp + 다른 raw_text → SyncService 가 conflict 마킹 (rebase 단계 git markdown conflict 가 먼저 잡힘 — 본 분기는 rare)
+
+**revision edited_by**: 'sync' enum 추가 안 함 — `updateRawText` 의 default 'user' 그대로 활용 (sync = user-edited 변경 전파 = 의미상 user). YAGNI: m008 회피.
 
 ### 3-3. GitClient 확장
 
@@ -193,7 +214,7 @@ settings: `sync_auto_enabled: boolean` (default true 단, configured 일 때만)
 | Conflict UI | 3 choice 별 sync 동작 |
 | 자동 주기 sync | timer + interval=true mode |
 
-**목표**: 단위 528 → 약 555 (+27), typecheck 0.
+**목표**: 단위 608 → 약 635 (+27), typecheck 0.
 
 ---