Detached HEAD 및 Lock 경합 해결을 통한 데이터 동기화 신뢰성 확보

Context

Git 기반의 지식 저장소 동기화 시스템인 KIOKU에서 표면적인 정상 작동 뒤에 숨겨진 데이터 불일치와 병목 지점을 분석. 단순한 기능 추가보다 런타임 에러의 무분별한 억제와 잘못된 Lock 범위 설정으로 인한 시스템 불안정성 해결에 집중.

Technical Solution

• git symbolic-ref를 통한 HEAD 상태 검증 로직을 도입하여 Detached HEAD 상태에서의 무의미한 commit/push 시도를 사전에 차단.
• || true와 같은 무조건적인 에러 억제 패턴을 제거하고 명시적인 경고 로그를 출력하는 가드 조건문으로 대체.
• MCP 서버의 Lock 범위를 '전체 PDF 처리 공정'에서 '디스크 쓰기' 단계로 최소화하여 Lock 유지 시간 단축.
• skipLock 플래그 기반의 상태 의존적 API 설계를 폐기하고 각 함수가 독립적으로 Lock을 획득하는 원자적 구조로 리팩토링.
• 호출자의 상태에 의존하지 않는 재진입 가능하거나 짧은 수명의 Lock 전략을 채택하여 결합도 제거.