git-sync

name	git-sync
version	1
description	스킬·설정 폴더를 개별 GitHub 레포로 동기화하는 엔진. 파일 3-way·Git 상태 이중 매트릭스로 안전하게 rsync→commit→push, 단일은 Fast Path·배치는 Pre-Flight 후 비파괴→파괴적 순. 스킬·UP 파일을 GitHub에 올리거나 백업·동기화할 때, 스킬 수정·패키징 후 레포에 반영할 때 쓴다. 트리거: 깃동기화, 깃싱크, 깃푸시, 레포 동기화, 스킬 업로드, 새 레포 생성, sync, push, upload. NOT: GitHub Pages 웹배포(→github-deploy), 스킬 내용 수정(→skill-builder), 일반 git 작업(→직접).

Git Sync

스킬·UP → GitHub 레포 생명주기 관리. 이중 매트릭스 순차 게이트(파일 3-way 8셀 + Git 상태 6셀) + Fast Path 캐시 활용.

v6.2 (2026-05-25): stale UUID 사본 자동 청소 — sync-skill.sh ENV resolve 직후 prune_stale_skills_plugin() 추가. 앱 재기동마다 쌓이는 옛 UUID 스킬 사본을 자동 정리(현행 활성 경로·7일 미만 비활성은 보존). v5 재스캔 후보가 N벌로 누적되며 첫 호출이 느려지던 "뺑뺑이" 영구 차단.

v6.1 (2026-05-10): 속도 패치 — sync-skill.sh rev-list 2회 → --left-right --count 1회 통합, pre-flight-scan.sh ORIGIN/LOCAL mtime 캐시 TTL=60s 추가. bash 줄수 감축·공식 plugin 패턴 회귀.

v6 (2026-04-18): Git 상태 매트릭스(G1~G6) 추가. sync-skill.sh를 3-Phase 상태머신으로 재구성(scan → dispatch → execute). v5의 silent failure / auto-rebase detached HEAD / rebase 중단 감지 누락을 매트릭스 단계에서 전차단.

---

⛔ 절대 규칙 (7개)

#	규칙	이유
1	Bash 도구로 스크립트 직접 실행 — 본문에서 git·rsync 명령 재조립 금지, scripts/*.sh 호출만	Claude Code의 Bash는 형 맥북 셸 그대로라 로컬 git repo·gh·SSH 전부 접근 가능
2	원본→레포 단방향 — 역방향 금지	원본은 skills-plugin 관리
3	README/LICENSE/.gitignore 보호 — rsync exclude 필수	레포 전용 메타파일
4	파괴적 액션 게이트 — gh repo create·rsync --delete·로컬 rm -rf는 명시 컨펌. gh repo delete·git push --force(bare)는 절대 금지(복구 §F 예외). git push --force-with-lease는 허용 — race-safe, 로컬이 원격보다 앞서고 원격 변경 이미 로컬에 반영된 경우(rename·rebase 직후) 컨펌 없이 실행	중복·유실 방지 + 과잉 방어 차단
5	새 레포 = README 2종 필수 — 초기 커밋에 README.md + README.ko.md	매번 수동 생성 방지
6	Pre-Flight Scan 필수 — 배치 진입 전 3-way 상태 수집 완료 전 어떤 액션도 금지. 단일 스킬은 Fast Path 허용	2026-04-16 사고(3축 독립 수집 미비) 재발 방지
7	매트릭스 외 분기 금지 — state-matrix.md 8셀 + git-state-matrix.md 6셀 + UNKNOWN만 신뢰. 기억 재구성·추측 분기=FAIL	상태 공간 완전 열거
8	이중 매트릭스 순차 게이트 — 파일 매트릭스(O·L·R) Cell 1·3 통과 → Git 매트릭스(HEAD·Rebase·Ahead·Behind) G1·G2 통과만 실행 진입. 한 축이라도 실패 = STOP	파일은 정상이어도 로컬 git 상태가 비정상이면 push 파괴

---

진입 분기 (1회 판정)

요청 유형?
  ├─ 단일 스킬 (1개 명시)    → Fast Path
  ├─ 배치·전체·N개+          → Full Pipeline
  ├─ UP 수정 후               → UP 동기화 (→ batch-guide.md §4)
  └─ Cell 2/4/5/6 복구        → disaster-recovery.md

---

Fast Path (단일 스킬)

조건: 1개 스킬 명시 + .git-sync-env 존재.

Bash 1회 호출로 완결: sync-skill.sh가 ENV 자동 로딩 → rsync → push → 리포트

Bash 호출: 1회. ENV 미존재시 Full Pipeline으로 자동 폴백.

# Bash 1회 — ENV 자동 source + sync + push 완결 (기본 = turbo)
bash "{repo_root}/git-sync/scripts/sync-skill.sh" \
  "{skill-name}" "Update {skill-name}: {변경요약}"

기본 = turbo (v4~): dry-run 스킵 + --delete 없음. 일반 업데이트 2배 빠름. 옵션 없이 기본 호출이 최속경로.

--strict: 파일 삭제가 포함된 업데이트일 때만 지정. dry-run으로 삭제 감지 후 실제 --delete 수행. 지정 안 하면 기본(turbo) 모드에서 레포에 고아 파일이 남을 수 있음.

--turbo: 하위호환 no-op. v4부터 기본이라 지정 불필요.

레거시 5인자 호환: sync-skill.sh <name> <plugin_path> <repo_root> <gh_user> <msg> [--strict] 도 동작.

세부 → references/batch-guide.md §1·2.

---

Full Pipeline (배치)

⓪ ENV resolve+캐시  →  ① Pre-Flight Scan  →  ② 분류 리포트+컨펌  →  ③ 비파괴(Cell 1·3)  →  ④ 파괴적(Cell 2·4·5·6) 건별  →  ⑤ 최종 리포트

상세 → references/batch-guide.md §1·3.

---

ENV_CACHE (파일 영속화)

{repo_root}/git-sync/.git-sync-env (shell 소스 가능)

export GITHUB_USER="jasonnamii"
export USER_HOME="$HOME"
export PLUGIN_SKILLS_PATH="$HOME/Library/.../skills"
export REPO_ROOT="$HOME/github-repos/skill-repos"

resolve 우선순위: 1) .git-sync-env 파일 → 2) 명령어로 1회 resolve 후 파일 작성 → 3) 실패시 STOP + 형에게 확인.

v5 자동 복구 (stale 감지): sync-skill.sh 실행 시 $PLUGIN_SKILLS_PATH/$SKILL_NAME 부재 감지 → skills-plugin root($HOME/.../skills-plugin) 하위 */*/skills 재스캔 → SKILL_NAME 포함 & mtime 최신 경로로 .git-sync-env 자동 갱신(백업 .bak.<epoch> 생성 후 sed). 앱 재설치·UUID 변경에도 자동 복구.

필드	확인 명령 (파일 없을 때만)
GITHUB_USER	gh api user --jq .login
PLUGIN_SKILLS_PATH	find "$HOME/Library/Application Support/Claude/local-agent-mode-sessions/skills-plugin" -maxdepth 3 -name "skills" -type d
REPO_ROOT	$HOME/github-repos/skill-repos/ (고정)

REMOTE 목록: .remote-cache 파일 (TTL 600초, pre-flight-scan.sh가 관리).

auto_mode: 기본 false. "앞으로 자동으로 해" → 세션 내 true. 파괴적 액션은 무관 항상 컨펌.

---

경로 테이블

대상	원본	레포	GitHub
스킬	$PLUGIN_SKILLS_PATH/{name}/	$REPO_ROOT/{name}/	github.com/$GITHUB_USER/{name}
UP	$HOME/.../Agent-Ops/UP_*.md	$REPO_ROOT/user-preferences/	github.com/$GITHUB_USER/user-preferences

---

상태 매트릭스 — 파일 3-way (8셀)

파일 존재 축. Origin · Local · Remote 3-way.

#	O	L	R	의미	액션	컨펌
1	✓	✓	✓	정상	sync-skill.sh	auto
2	✓	✓	✗	원격 유실	disaster §A	필수
3	✓	✗	✓	로컬 미클론	clone → sync	auto
4	✓	✗	✗	진짜 신규	batch-guide §5	필수
5	✗	✓	✓	원본 삭제	STOP → disaster §B/C	필수
6	✗	✓	✗	고아 로컬	disaster §D	필수
7	✗	✗	✓	외부 레포	스킵	—
8	✗	✗	✗	없음	스킵	—
?	UNKNOWN			스캔 실패	STOP + 재스캔	—

세부 → state-matrix.md. 매트릭스 외 분기 = FAIL.

---

상태 매트릭스 — Git 상태 (6셀)

브랜치·커밋 축. HEAD·Rebase·Ahead·Behind 4축 스냅샷.

셀	HEAD	Rebase	Ahead	Behind	액션	종료코드
G1	on-branch	✗	0	0	clean sync — rsync→add→(staged)commit→push→POST_CHECK	0
G2	on-branch	✗	N	0	push-only — 미푸시 커밋 함께 상승 (v5 silent failure 차단)	0
G3	on-branch	✗	N	M	DIVERGED — STOP — 자동 rebase 금지, 사용자 컨펌	5
G4	on-branch	✗	0	M	BEHIND — STOP — fast-forward pull 필요	5
G5	*	✓	*	*	REBASE 중단 — STOP — git rebase --abort 안내	6
G6	detached	✗	*	*	DETACHED — STOP — 수동 복구 안내	7
?	UNKNOWN				스캔 실패 — 재시도	8

POST_CHECK: G1·G2 실행 후 git rev-list --count origin/$BRANCH..HEAD == 0 확인. 미일치시 exit 8.

세부 → git-state-matrix.md. 이중 게이트 원칙: 파일 매트릭스(Cell 1·3) AND Git 매트릭스(G1·G2) 모두 통과만 실행.

---

배치 처리 순서

1. Cell 1·3 비파괴: push-only 6개 이하 병렬 / gh api 포함 3개 이하 / 7개+ 순차
2. Cell 7: 1회 안내 스킵
3. Cell 2·4: 건별 컨펌 → 순차
4. Cell 5: 건별 선택 (기본 보류)
5. Cell 6: 건별 선택 (기본 보류)
6. UNKNOWN: 리포트만

비파괴가 먼저 끝나야 파괴적 에러가 전체를 블록하지 않음.

---

Scripts

스크립트	역할	최신 개선
pre-flight-scan.sh	파일 3-way 스캔 + 8셀 분류	v6.1 (2026-05-10): ORIGIN/LOCAL mtime 캐시 TTL=60s 추가 — 배치 N개 처리 시 ls 반복 차단. REMOTE TTL 600s 승계. --no-cache 플래그
sync-skill.sh	Cell 1·3 동기화	v6.2 (2026-05-25): stale 사본 자동 청소 — ENV resolve 직후 prune_stale_skills_plugin()로 현행 외 7일↑ 비활성 UUID 폴더 자동 삭제. 재스캔 뺑뺑이 영구 차단. v6.1 rev-list 통합·v6 3-Phase 상태머신·POST_CHECK·turbo 기본 승계
secret-scan.sh	민감정보 검사	v2: allowlist 지원 — secret-scan-allowlist.txt 정규식 FP 허용
secret-scan-allowlist.txt	FP 허용 목록	라인 단위 정규식. 주석(#)·빈 줄 무시
rsync-exclude.txt	exclude 패턴	logs/ .remote-cache 포함
excluded-names.txt	Pre-Flight 제외 목록	—

---

References

• state-matrix.md — 파일 3-way 8셀 결정 테이블 + 셀별 세부 액션
• git-state-matrix.md — v6 Git 상태 6셀 매트릭스 (HEAD·Rebase·Ahead·Behind) + POST_CHECK
• batch-guide.md — Pre-Flight·단일·배치·UP·신규 레포 통합 프로토콜
• readme-templates.md — 이중언어 README 템플릿
• disaster-recovery.md — Cell 2·5·6 복구 + 사고 롤백

---

Gotchas

함정	대응
본문에서 git·rsync 명령 직접 조립	금지. scripts/*.sh를 Bash로 호출. CC Bash는 로컬 git 접근 정상
단일 스킬에 Full Pipeline 강제	Fast Path 존재. 캐시 10분 이내면 Pre-Flight 스킵
sync-skill.sh rsync 여러번	v2부터 itemize-changes 단일. 3회 동작 시 스크립트 업데이트 누락
gh repo list --limit 500 매번	.remote-cache TTL 600초. --no-cache로만 강제
ENV resolve 반복	.git-sync-env 영속화. 세션 유실에도 유지
auto_mode=true에서 Cell 2·4·5·6 자동	금지. auto_mode는 Cell 1·3만
REMOTE UNKNOWN을 '없음'으로 해석	금지. 재스캔 또는 UNKNOWN 유지
로그·캐시가 rsync에 섞임	logs/·.remote-cache exclude 필수(v2 기본)
에이전트가 rsync·git 직접 조립	금지. 스크립트 호출. 재조립 금지
skills-plugin UUID 변경	v5부터 자동 감지·갱신. SKILL_NAME 부재 시 skills-plugin root 재스캔 후 mtime 최신 경로로 ENV 자동 치환(백업 생성). 수동 수정 불요
macOS에 timeout 없음	sync-skill.sh에 perl 기반 폴백 내장. brew install coreutils(gtimeout) 불요
Bash 호출 2회+ 느림	v4 기본 turbo 모드로 Bash 1회 완결. 옵션 없이 sync-skill.sh <name> <msg>
매번 dry-run 느림	v4부터 기본이 dry-run 스킵. --strict 지정 시에만 dry-run + --delete. 삭제 감지 필요할 때만
파일 삭제했는데 레포에 남음	기본 turbo 모드는 --delete 없음. 삭제 포함 업데이트는 --strict 지정 필수
force-with-lease 과잉 방어	race-safe(원격 변경 감지 시 자동 거부). rename·rebase 후 diverge 시 컨펌 없이 실행. --force(bare)만 금지
rename 후 diverge 컨펌 요청	원격 변경이 이미 로컬에 반영됐다면(SKILL.md 재작성 등) force-with-lease 즉시 실행. 질문 루프 금지
secret-scan false positive (api_key 언급·메타 패턴 리스트 등)	scripts/secret-scan-allowlist.txt 에 해당 라인 정규식 추가. 코드 수정·bypass 금지. 허용 건수는 스캔 결과에 표시됨
push 성공했다는데 원격에 반영 안 됨	v6 POST_CHECK 필수. origin/$BRANCH..HEAD == 0 검증 후에만 성공 처리. 네트워크·branch protection·race로 push RC=0여도 반영 안 될 수 있음
로컬 미푸시 커밋 있는데 "변경 없음" 종료	v5 silent failure. v6에서 G2 셀로 강제 push — rsync diff 유무와 무관하게 로컬이 원격보다 앞서면 push 실행
push rejected 받고 auto rebase	금지. v6에서 G3 셀 = STOP + 사용자 컨펌. v5의 git pull --rebase 자동 실행은 timeout 시 detached HEAD 잔존 위험 → 제거
이전 세션의 rebase 중단 상태로 rsync	working tree 오염. v6에서 G5 셀 = Phase 1에서 선차단. .git/rebase-{merge,apply}/ 감지 시 exit 6 + abort 안내
detached HEAD에서 commit	고아 커밋 생성. v6에서 G6 셀 = 자동 복구 금지, 수동 판단 강제. git symbolic-ref HEAD 실패 시 exit 7
fetch 없이 Ahead/Behind 측정	origin/$BRANCH가 stale → G1~G4 오분류. v6 Phase 1에서 git fetch origin 1회 필수 (timeout 15s)
rev-list 2회 fork 누적 (배치 N개)	v6.1에서 --left-right --count 단일 호출로 통합. 자동 적용 — 별도 조치 불요
배치 진입 시 ORIGIN/LOCAL ls 매번 풀스캔	v6.1에서 .origin-cache·.local-cache mtime TTL=60s 추가. 같은 배치 내 N개 처리 1회만 ls. 60s 후 자동 갱신. 강제 무효화 = rm $REPO_ROOT/git-sync/.{origin,local}-cache
앱 재기동마다 옛 UUID 스킬 사본 누적 → 재스캔 뺑뺑이	v6.2 prune_stale_skills_plugin()가 매 동기 시 자동 청소. 현행 활성 경로·7일 미만 비활성은 보존, 그 외만 삭제. 활성세션 다중 운용 시 7일 cutoff가 보호막 — 안전 우선이라 덜 지우는 쪽
청소 훅이 현행 폴더를 지울까 우려	KEEP = dirname $PLUGIN_SKILLS_PATH(user-UUID). KEEP이 skills-plugin 하위가 아니면 즉시 return(fail-safe). 현행은 구조적으로 삭제 불가

---

✅ WRONG / CORRECT 대조 (v6.1)

❌ WRONG (v6 이전 — Ahead/Behind 직렬 fork):

AHEAD=$(git rev-list --count "origin/$BRANCH..HEAD")   # git fork 1회
BEHIND=$(git rev-list --count "HEAD..origin/$BRANCH")  # git fork 1회 (총 2회)

✅ CORRECT (v6.1 — 단일 호출):

LR=$(git rev-list --left-right --count "origin/$BRANCH...HEAD")  # 1회
BEHIND=$(echo "$LR" | awk '{print $1}')
AHEAD=$(echo "$LR" | awk '{print $2}')

효과: N개 스킬 배치 시 N×80ms 절감. 단일 호출도 fork·로딩 절반.

---

Version

버전	날짜	변경
v6.2	2026-05-25	stale UUID 사본 자동 청소 — 재스캔 뺑뺑이 영구 차단. sync-skill.sh ENV resolve 직후 prune_stale_skills_plugin() 신설. 현행 활성 경로(PLUGIN_SKILLS_PATH 상위 UUID)는 절대 보존 + 7일 미만 비활성도 보존, 그 외 stale UUID 폴더만 rm -rf. KEEP이 skills-plugin 하위가 아니면 청소 중단(fail-safe). 빈 상위 UUID 폴더 정리 포함.
v6.1	2026-05-10	속도 패치 — bash 줄수 -68% 목표·공식 plugin 패턴 회귀. ① sync-skill.sh rev-list 2회 → --left-right --count 1회 통합 (git fork -1, ~80ms × N). ② pre-flight-scan.sh ORIGIN/LOCAL ls mtime 캐시 TTL=60s 신설 (배치 N×ls 차단). ③ Gotchas + WRONG/CORRECT 1쌍 추가.
v6	2026-04-18	Git 상태 매트릭스 6셀 신설 (G1~G6 + UNKNOWN). sync-skill.sh 3-Phase 상태머신 재구성(scan→dispatch→execute). POST_CHECK 추가. v5 silent failure / auto-rebase detached HEAD / rebase 중단 감지 누락 3대 결함 전차단. references/git-state-matrix.md 추가. 이중 매트릭스 순차 게이트 원칙(절대규칙 8) 추가.
v5	—	PLUGIN_SKILLS_PATH stale 자동 감지·복구
v4	—	기본 turbo 모드 (dry-run·--delete 스킵)
v2	—	pre-flight TTL 캐시, secret-scan allowlist, itemize-changes 단일