| name | gsd-sync-upstream |
| description | get-shit-done-ko 유지보수자가 upstream GitHub release를 tracked baseline과 비교하고, 더 새로운 버전일 때만 vendored GSD를 안전하게 sync해야 할 때 사용하는 스킬. upstream sync, vendored refresh, baseline compare, no-op dry-run, get-shit-done-ko maintainer workflow 요청이 나오면 적극적으로 사용. |
GSD Upstream Sync
get-shit-done-ko 유지보수자가 upstream gsd-build/get-shit-done release를 현재 저장소의 tracked upstream baseline과 비교하고, upstream이 더 새로울 때만 vendored GSD tree를 안전하게 갱신하는 스킬입니다.
이 스킬은 maintainer 전용 repo sync 흐름입니다. npm runtime 설치를 갱신하는 $gsd-update와는 다릅니다.
What to Read First
references/context.md- 저장소 루트의
get-shit-done/UPSTREAM_VERSION
- 저장소 루트의
docs/UPSTREAM-SYNC.md
- 저장소 루트의
docs/RELEASE-CHECKLIST.md
Bundled Helpers
이 스킬은 아래 helper scripts를 함께 번들합니다.
scripts/check-upstream-release.cjsscripts/apply-upstream-refresh.cjs
저장소 루트에 같은 이름의 repo-local scripts가 있으면 그것을 우선 사용합니다. 없으면 bundled scripts를 사용하되 --cwd <repo-root>를 넘겨 현재 저장소를 대상으로 실행합니다.
Preconditions
현재 작업 디렉터리가 get-shit-done-ko 저장소 루트이거나, 적어도 아래 파일이 있는 repo root를 찾을 수 있어야 합니다.
get-shit-done/UPSTREAM_VERSIONdocs/UPSTREAM-SYNC.mddocs/RELEASE-CHECKLIST.md
repo root를 찾지 못하면 먼저 사용자에게 현재 저장소가 맞는지 확인합니다.
Workflow
references/context.md를 읽고, tracked baseline file과 protected paths 정책을 파악합니다.- repo root를 기준으로 compare helper를 실행합니다.
node scripts/check-upstream-release.cjs --current-file get-shit-done/UPSTREAM_VERSION --json
- 아래 값을 사용자에게 보고합니다.
- tracked upstream baseline
- latest upstream GitHub release tag
- latest upstream release published date
- fork
package.json version
- compare status (
current, update_available, ahead)
이 compare report는 항상 먼저 보여줘야 합니다. maintainer는 이 값들과 status만 보고 no-op인지, dry-run으로 갈 수 있는지, local-ahead인지 판단할 수 있어야 합니다.
update_available이 false면:
- repo가
current인지 local-ahead인지 분리해서 설명합니다.
- 이 판단이
package.json만이 아니라 get-shit-done/UPSTREAM_VERSION 기준임을 분명히 말합니다.
- 비교한 버전과 날짜를 보여 주고 명시적으로 no-op으로 종료합니다.
- 이 경로에서는 worktree를 건드리거나 apply/dry-run을 강행하지 않습니다.
Compare outcome handling
current — tracked baseline이 upstream latest와 같다. 날짜와 태그를 보고하고 no-op으로 종료합니다.ahead — tracked baseline이 upstream latest보다 앞선다. local-ahead 상태를 설명하고 no-op으로 종료합니다.update_available — upstream latest가 더 새롭다. 이 경우에만 dry-run/apply로 넘어갑니다.
update_available이 true면 먼저 dry-run을 실행합니다.
node scripts/apply-upstream-refresh.cjs --from-current --to-tag <latest_tag> --dry-run
- dry-run 결과에서 아래를 요약합니다.
- incoming tag
- status
- no-op
- touched paths
- preserved paths
- overlay reapply
- overlay delete
-
실제 반영 전에는 사용자 확인을 받습니다.
-
승인되면 실제 apply를 실행합니다.
node scripts/apply-upstream-refresh.cjs --to-tag <latest_tag> --mode source-of-truth
이 mode는 tracked upstream surface를 다시 가져오고, local overlay를 재적용하고, 제거된 overlay는 삭제한 뒤 get-shit-done/UPSTREAM_VERSION를 새 기준선으로 갱신합니다.
- localization audit가 필요하면 다음 명령으로 changed manifest를 생성합니다.
node scripts/audit-localization-gap.cjs --to-tag <latest_tag> --mode source-of-truth --json
audit 결과에서는 아래 필드를 우선 확인합니다.
- changed_files
- translation_candidates
- overlay_missing
- zh_cn_reintroduced
- token_sensitive_candidates
- overlay_reapply
- overlay_delete
token_sensitive_candidates는 commands, file paths, placeholders, @ references, XML/markdown structure, identifiers를 특히 조심해서 수동 검토해야 하는 항목입니다.
- apply가 끝나면 다음 canonical validation을 실행합니다.
node get-shit-done/bin/gsd-tools.cjs validate health
node get-shit-done/bin/gsd-tools.cjs validate consistency
node get-shit-done/bin/gsd-tools.cjs roadmap analyze
node scripts/run-tests.cjs
Guardrails
- 이 흐름을 npm install/update 흐름으로 설명하지 않습니다.
$gsd-update로 repo sync를 대신하라고 안내하지 않습니다.- sync eligibility는
package.json만으로 판단하지 않습니다.
- upstream latest가 tracked baseline과 같거나 더 낮으면 worktree를 건드리지 않습니다.
- dry-run/apply 전에
references/context.md의 preserved paths 정책과 import surface를 유지합니다.
Expected Output
- no-op인 경우: compared tags/date, current/ahead 판단, no-op 메시지
- update 가능한 경우: dry-run 요약과 apply 전 확인 질문
- apply 후: canonical validation 결과와 후속 확인 포인트
