| 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 "{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) 모두 통과만 실행.
배치 처리 순서
- Cell 1·3 비파괴: push-only 6개 이하 병렬 /
gh api 포함 3개 이하 / 7개+ 순차
- Cell 7: 1회 안내 스킵
- Cell 2·4: 건별 컨펌 → 순차
- Cell 5: 건별 선택 (기본 보류)
- Cell 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_CHECKbatch-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")
BEHIND=$(git rev-list --count "HEAD..origin/$BRANCH")
✅ CORRECT (v6.1 — 단일 호출):
LR=$(git rev-list --left-right --count "origin/$BRANCH...HEAD")
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 단일 |
