@uzysjung/agent-harness 26.83.0

package/templates/commands/uzys/review.md

@@ -0,0 +1,44 @@
+Review phase — 다중 관점 리뷰로 품질을 검증한다.
+
+## Gate Check
+
+Verify 단계가 완료되었는지 확인한다. 테스트가 통과하지 않았으면 경고.
+
+## Process
+
+1. agent-skills의 code-review-and-quality + security-and-hardening 스킬을 활성화한다.
+2. **reviewer subagent를 호출한다** (SOD: 구현과 검증 분리):
+   - reviewer는 context: fork로 격리 실행
+   - 5축 리뷰: correctness, readability, architecture, security, performance
+3. 프로젝트 레벨 에이전트도 활성화:
+   - code-reviewer (ECC, sonnet): 일상적 코드 리뷰
+   - security-reviewer (ECC, sonnet): OWASP Top 10, 보안 패턴
+4. 산출물 유형에 따라 리뷰 관점 자동 선택:
+   - 코드: 5축 리뷰
+   - 문서/제안서: 논리 흐름, 설득력, 범위 커버리지
+   - UI: 디자인 일관성, 접근성, 반응형
+5. **UI 변경이 있고 `docs/visual-review-<phase>.md`가 존재**하면 visual review 결과를 입력으로 흡수:
+   - REGRESSION 1건이라도 있으면 **Review Gate 차단** (CRITICAL과 동급)
+   - CHANGED 항목은 의도성 검증 (커밋 메시지/PR 본문과 매칭)
+   - 부재 시 ui-visual-review skill 호출 권유 (UI Track 한정)
+
+## Severity Classification
+
+| Severity | Action |
+|----------|--------|
+| CRITICAL | 즉시 수정 필수. Review 게이트 통과 불가 |
+| HIGH | 수정 권장. 합리적 사유 있으면 예외 가능 |
+| MEDIUM | 제안. 현재 PR에서 안 해도 됨 |
+| LOW | 참고 |
+
+## Gate
+
+CRITICAL 이슈 0건이어야 Review 게이트 통과.
+
+## Gate Status Update
+
+이 단계가 성공적으로 완료되면 `.claude/gate-status.json`의 `review.completed`를 `true`로, `review.timestamp`를 현재 시각으로 업데이트한다.
+
+```bash
+jq '.review.completed = true | .review.timestamp = now | .review.timestamp = (now | strftime("%Y-%m-%dT%H:%M:%SZ"))' .claude/gate-status.json > /tmp/gate-tmp.json && mv /tmp/gate-tmp.json .claude/gate-status.json
+```

package/templates/commands/uzys/ship.md

@@ -0,0 +1,49 @@
+Ship phase — 프리런치 체크리스트 실행 후 배포한다.
+
+## Gate Check
+
+Review 단계가 완료되었는지 확인한다. CRITICAL 이슈가 남아 있으면 경고.
+
+## Process
+
+1. agent-skills의 shipping-and-launch 스킬을 활성화한다.
+2. `.claude/rules/ship-checklist.md` 게이트를 순차 확인:
+
+   - [ ] E2E 테스트 전부 PASS
+   - [ ] test-policy.md 커버리지 기준 충족
+   - [ ] `npx ecc-agentshield scan` — CRITICAL/HIGH 없음
+   - [ ] SPEC.md/PRD.md 대비 배포 항목 일치 확인
+
+3. 하나라도 실패하면 배포 차단 + 실패 항목 보고.
+
+4. 전부 통과하면:
+   - Railway MCP/플러그인으로 배포 (Railway 사용 시)
+   - Health check 엔드포인트 응답 확인
+   - 배포 후 smoke test
+
+5. Post-Ship:
+   - SPEC/PRD 불일치 발견 시 → 업데이트 후 커밋
+   - 아키텍처 결정이 있었으면 → `docs/decisions/` 에 ADR 기록
+   - Change Log 최종 확정
+
+## Issue Closure (issue_tracking: enabled 시)
+
+PR body에 다음 컨벤션 강제 — 머지 시 GitHub Issue 자동 close:
+- 완전 해결: `Closes #N` 또는 `Fixes #N`
+- 부분 진행 (close 안 함): `Refs #N`
+- 후속 issue 분기 시 원본 issue body의 "후속 작업" 섹션에 `#M` cross-link
+
+`gh-issue-workflow` skill의 PR 컨벤션 검증 — 머지 직전 PR body grep으로 1건이라도 issue 참조 누락이면 경고.
+
+## Hotfix Mode
+
+긴급 수정 시 Build → Verify → Ship 단축 경로 허용.
+Define/Plan/Review 게이트 건너뛰기 가능하지만, Verify(테스트)는 필수.
+
+## Gate Status Update
+
+이 단계가 성공적으로 완료되면 `.claude/gate-status.json`의 `ship.completed`를 `true`로, `ship.timestamp`를 현재 시각으로 업데이트한다.
+
+```bash
+jq '.ship.completed = true | .ship.timestamp = now | .ship.timestamp = (now | strftime("%Y-%m-%dT%H:%M:%SZ"))' .claude/gate-status.json > /tmp/gate-tmp.json && mv /tmp/gate-tmp.json .claude/gate-status.json
+```

package/templates/commands/uzys/spec.md

@@ -0,0 +1,93 @@
+Define phase — 구조화된 스펙을 코드 작성 전에 작성한다.
+
+## Process
+
+1. 요청이 모호하면 먼저 아이디어를 정제한다 (agent-skills idea-refine 패턴 활용).
+2. agent-skills의 spec-driven-development 스킬을 따라 SPEC.md를 작성한다.
+   - 6가지 핵심 영역: Objective, Commands, Project Structure, Code Style, Testing Strategy, Boundaries
+3. 대형 프로젝트(비즈니스 맥락 필요)면 PRD 템플릿(Docs/dev/PRD-TEMPLATE-standalone.md)을 참조하여 확장.
+4. Non-Goals를 반드시 명시한다 — "미언급 = 범위 밖" 원칙.
+5. DO NOT CHANGE 영역을 식별하고 SPEC에 기록한다.
+6. SPEC.md를 `docs/SPEC.md`에 저장한다.
+
+## Pre-SPEC 필수 접수 (UI/Test/E2E)
+
+SPEC 작성 **전에** 다음 항목을 사용자에게 질문하고 SPEC에 기록한다. 미기재 시 SPEC 미완료 — Build 단계에서 drift 버그로 이어짐.
+
+### A. Test Environment Parity
+
+1. **Prod DB 엔진** — Postgres/MySQL/SQLite/Redis 등 + 버전
+2. **테스트 DB 전략** — testcontainer / docker-compose / staging DB / none. SQLite 대체는 Prod가 SQLite인 경우에만 허용 (test-policy.md Dev-Prod Parity)
+3. **외부 의존성** — Stripe, Supabase, Railway, SES 등. 각각 Mock / Live staging 중 어떤 전략인지
+
+→ SPEC.md "Testing Strategy" 섹션에 표로 정리.
+
+### B. 핵심 E2E 플로우
+
+- **Mock 금지 대상 목록**: 인증(login/callback/me), 결제(checkout/webhook), 파일업로드 등
+- 각 플로우별 성공 기준 (예: "login → /me 200 + user_id 일치")
+
+→ SPEC.md "Testing Strategy"의 E2E 하위 목록으로.
+
+### C. Design Context (UI Track인 경우)
+
+UI 포함 Track(csr-*/ssr-*/full)이면 SPEC 전에 다음 확인:
+
+1. **`DESIGN.md` 존재 여부** — 디자인 방향/톤/레이아웃 원칙 기록. 없으면 `/teach` 또는 `/shape` 스킬로 먼저 작성 유도
+2. **`.impeccable.md` 존재 여부** — 브랜드/청중/톤 컨텍스트. 없으면 `/teach` 선행
+3. **디자인 참조물** — Figma 링크, 스크린샷, 경쟁사 레퍼런스 등
+
+디자인 컨텍스트 없이 UI 코드 작성 금지. Generic AI 미학 산출물 방지.
+
+### D'. GitHub Issue Tracking (선택)
+
+`git remote -v`로 GitHub remote 확인 가능 + 사용자가 issue를 backlog/소통 채널로 쓰고 싶으면:
+
+- `docs/SPEC.md`에 `issue_tracking: enabled` 라인 명시 (opt-in)
+- 활성화 시 `gh-issue-workflow` skill이 `/uzys:plan`, `/uzys:build`, `/uzys:ship`에서 자동 결합
+- ISSUE 본문은 `templates/skills/gh-issue-workflow/ISSUE.template.md`의 5섹션(배경/전제/방향성/AC/후속) 강제
+
+기본은 비활성. SPEC에 명시 없으면 모든 단계에서 skip.
+
+### D. North Star (선택, 대형 프로젝트 권장)
+
+`docs/NORTH_STAR.md` 부재 + 다음 중 1개 이상 해당 시 작성 권장:
+
+- 6개월 이상 지속 예상되는 프로젝트
+- 복수 Phase / 복수 사용자 / 외부 의존성이 명확한 경우
+- 신규 기능 우선순위 결정이 잦을 것으로 예상
+
+작성 시 `north-star` 스킬 호출 → `templates/skills/north-star/NORTH_STAR.template.md`를 `docs/NORTH_STAR.md`로 복사 후 7개 섹션(NS Statement / NSM / Will-Won't / Phase / 4-gate / Versioning / Changelog) 채움. 단순 1회성 작업이면 skip.
+
+---
+
+위 A/B/C **세 블록은 SPEC 작성 전 접수** (D는 선택). 답변 없으면 "이 항목 정의가 필요합니다" 질문으로 돌아가 반복. 모두 수집된 후에 본 SPEC 작성 진행.
+
+## Gate
+
+이 단계가 완료되어야 `/uzys:plan`으로 진행 가능.
+SPEC.md가 존재하고, 최소 Objective + Boundaries가 정의되어 있어야 완료.
+
+## Auto-Actions
+
+- SPEC.md가 300줄을 초과하면 spec-scaling 스킬로 기능별 분리 제안.
+- change-management.md 규칙 적용: 이후 SPEC 변경 시 CR 분류.
+
+## Gate Status Update
+
+이 단계가 성공적으로 완료되면 `.claude/gate-status.json` 을 다음 두 동작으로 갱신한다:
+
+1. `define.completed = true` + `define.timestamp = now`
+2. **후속 5단계 (`plan` / `build` / `verify` / `review` / `ship`) 모두 리셋** — `completed = false`, `timestamp = null`
+
+**원칙**: SPEC 재정의 = 새 cycle 시작 = 후속 모든 게이트 리셋. 이전 cycle 의 ship 완료 상태가 새 cycle 게이트를 만족시키는 정합성 위반을 차단한다 (gate bypass 방지).
+
+```bash
+jq '.define.completed = true
+    | .define.timestamp = (now | strftime("%Y-%m-%dT%H:%M:%SZ"))
+    | .plan.completed   = false | .plan.timestamp   = null
+    | .build.completed  = false | .build.timestamp  = null
+    | .verify.completed = false | .verify.timestamp = null
+    | .review.completed = false | .review.timestamp = null
+    | .ship.completed   = false | .ship.timestamp   = null' .claude/gate-status.json > /tmp/gate-tmp.json && mv /tmp/gate-tmp.json .claude/gate-status.json
+```

package/templates/commands/uzys/test.md

@@ -0,0 +1,58 @@
+Verify phase — TDD 워크플로우와 Track별 커버리지 게이트를 실행한다.
+
+## Process
+
+1. agent-skills의 test-driven-development 스킬을 따른다.
+2. agent-skills의 **test-engineer 에이전트**를 활성화하여 테스트 전략 설계, 시나리오 분석(happy path, boundary, error path, concurrency)을 수행한다.
+3. `.claude/rules/test-policy.md`의 Track별 커버리지 기준을 참조한다:
+   - UI 컴포넌트: 60%
+   - API 엔드포인트: 80%
+   - 비즈니스 로직: 90%
+3. 브라우저 테스트가 필요한지 판단한다:
+   - UI 변경이 있으면 → browser-testing 스킬 + Playwright 활성화
+   - API/로직만이면 → unit/integration 테스트만
+4. 전체 테스트 스위트를 실행하고 결과를 보고한다.
+5. 커버리지가 기준 미달이면 추가 테스트 작성을 제안한다.
+
+## 핵심 사용자 기능 플로우 E2E (필수)
+
+다음 플로우가 프로젝트에 존재하면 **실환경(staging 또는 로컬 docker-compose) Live E2E 1건 이상 필수**:
+
+- **인증**: login → magic-link/OAuth callback → /me (또는 보호된 엔드포인트) 200
+- **결제**: checkout → webhook → refund (존재 시)
+- **외부 API 의존 플로우**: Stripe, Supabase, Railway, SES 등
+
+검증 방식: Mock이 아닌 실제 서비스 호출. unit/integration의 Mock 테스트는 보조.
+Prod가 Postgres면 테스트도 Postgres (testcontainer/docker-compose) — test-policy.md Dev-Prod Parity 준수.
+
+## UI Visual Review (UI Track 자동)
+
+Track이 csr-*/ssr-*/full이고 E2E 테스트가 PASS인 경우, **`ui-visual-review` 스킬 호출 권유**:
+
+- 핵심 화면 N개 자동 캡처 (chrome-devtools MCP 또는 Playwright)
+- 이전 baseline과 diff (해시 → pixelmatch → 시각 비교 단계적)
+- 에이전트 1차 판정 (REGRESSION / CHANGED / PASS)
+- `docs/visual-review-<phase>.md` 보고서 → 사용자 승인 게이트
+
+`docs/visual-pages.json` 부재 시 skill 첫 실행에서 핵심 화면 목록 질의. `data`/`tooling`/`executive` Track은 skip.
+
+## Bug Fix Mode
+
+버그 수정 시 Prove-It 패턴:
+1. 버그를 재현하는 테스트 작성
+2. 테스트가 실패하는지 확인 (버그 존재 증명)
+3. 수정 구현
+4. 테스트가 통과하는지 확인
+5. 가드 테스트로 유지
+
+## Gate
+
+모든 테스트 PASS + 커버리지 기준 충족 시 완료.
+
+## Gate Status Update
+
+이 단계가 성공적으로 완료되면 `.claude/gate-status.json`의 `verify.completed`를 `true`로, `verify.timestamp`를 현재 시각으로 업데이트한다.
+
+```bash
+jq '.verify.completed = true | .verify.timestamp = now | .verify.timestamp = (now | strftime("%Y-%m-%dT%H:%M:%SZ"))' .claude/gate-status.json > /tmp/gate-tmp.json && mv /tmp/gate-tmp.json .claude/gate-status.json
+```

package/templates/docs/PLAN.template.md

@@ -0,0 +1,102 @@
+# Plan — [Project Name]
+
+> 6개월+ 프로젝트 또는 복수 Phase가 있는 경우 사용. 1-2주 단순 작업은 todo.md만으로 충분.
+> 본 템플릿은 GoalTrack의 `docs/plan.md` 패턴을 일반화한 것.
+
+---
+
+## 0. Sprint Contract
+
+- **목표 (이번 sprint에서 달성할 outcome)**: [한 문장]
+- **포함 (scope)**: [3-5개 bullet]
+- **제외 (out of scope)**: [3-5개 bullet — Non-Goals]
+- **완료 기준 (Definition of Done)**: [측정 가능한 조건]
+- **제약 조건**: [기간, 리소스, 의존성]
+
+---
+
+## 1. Phase Overview
+
+전체 프로젝트를 Phase로 나눈 큰 그림. 본 sprint가 어느 Phase에 속하는지 명시.
+
+| Phase | 이름 | 목표 | 진입 조건 | 완료 조건 |
+|-------|------|------|----------|----------|
+| P1 | [이름] | [한 문장] | (시작) | [측정 가능 기준] |
+| P2 | [이름] | [한 문장] | P1 완료 | [기준] |
+| P3 | [이름] | [한 문장] | P2 완료 + [추가 조건] | [기준] |
+
+---
+
+## 2. Milestone × Dependency Graph
+
+각 Phase 내부를 Milestone으로 분해 + 의존성 표기.
+
+### 표기 규약
+- `M1 → M2`: M1 완료 후 M2 시작 (직렬)
+- `M1 ∥ M2`: 동시 진행 가능 (병렬)
+- `M1 ⇒ M2`: M1의 산출물이 M2의 입력 (강한 의존)
+- `M1 → {M2, M3} → M4`: M1 후 M2/M3 병렬 → 둘 다 끝나면 M4
+
+### 예시 — Phase 1 분해
+
+```
+M1 (foundation) ⇒ {M2 (auth), M3 (data layer)} → M4 (UI integration) → M5 (E2E)
+                                                  ↘
+                                                   M6 (CLI) ∥ M5
+```
+
+| Milestone | 산출물 | 의존성 | 예상 기간 | Status |
+|-----------|--------|--------|---------|--------|
+| M1 | [foundation 산출물] | (없음) | 3d | ⬜ |
+| M2 | [auth 산출물] | M1 | 5d | ⬜ |
+| M3 | [data layer] | M1 | 4d | ⬜ |
+| M4 | [UI integration] | M2, M3 | 3d | ⬜ |
+| M5 | [E2E suite] | M4 | 2d | ⬜ |
+| M6 | [CLI] | M4 | 2d | ⬜ |
+
+### 임계 경로 (Critical Path)
+가장 긴 직렬 체인 — 일정 risk가 가장 큰 경로.
+> M1 → M2 → M4 → M5 = 13일
+
+병렬 경로 (M3, M6) 단축은 임계 경로 단축 안 됨. M2/M4 단축이 우선.
+
+---
+
+## 3. Per-Milestone Detail
+
+각 Milestone의 task breakdown은 `docs/todo.md`에 위임.
+본 문서에는 outcome + AC만.
+
+### M1 — [이름]
+- **Outcome**: [완료 시 무엇이 가능한가]
+- **AC** (Acceptance Criteria):
+  - [ ] [측정 가능 조건 1]
+  - [ ] [측정 가능 조건 2]
+- **References**: [SPEC §, ADR, 외부 문서]
+
+(M2~Mn 동일 구조)
+
+---
+
+## 4. Risk & Mitigation
+
+| Risk | Likelihood | Impact | Mitigation | Owner |
+|------|----------|--------|----------|------|
+| [예: 외부 API rate limit] | M | H | mock + cache layer | [name] |
+| [예: 마이그레이션 실패] | L | H | savepoint + rollback 스크립트 | [name] |
+
+---
+
+## 5. Open Questions
+
+해결되지 않은 의사결정. SPEC/NORTH_STAR 갱신 필요할 수도.
+
+- [ ] [질문 1] — 결정자: [name], 마감: [date]
+- [ ] [질문 2]
+
+---
+
+## 6. Changelog
+
+- YYYY-MM-DD: 초안
+- (이후 갱신 기록)

package/templates/hooks/agentshield-gate.sh

@@ -0,0 +1,101 @@
+#!/bin/bash
+# ============================================================
+# agentshield-gate.sh — PreToolUse Skill hook (uzys:ship 차단)
+#
+# 목적: /uzys:ship Skill 실행 전 ECC AgentShield 보안 스캔 실행.
+#       CRITICAL 발견 + .agentshield-ignore 미매칭 시 exit 2.
+#
+# 입력: PreToolUse stdin JSON (Skill hook)
+# 출력: stderr 경고 + exit 2 (차단) 또는 exit 0 (통과)
+#
+# 활성화 조건:
+#   1. 이 hook이 settings.json Skill matcher에 등록
+#   2. npx 명령 사용 가능 (Node.js 환경)
+#
+# False-positive 허용:
+#   .agentshield-ignore 파일 — 한 줄에 하나의 정규식.
+#   매칭되는 finding은 CRITICAL이어도 무시.
+# ============================================================
+set -u
+
+# Skill 이름 파싱 — uzys:ship 만 대상
+INPUT=$(cat 2>/dev/null || echo "{}")
+SKILL_NAME=""
+if command -v jq &>/dev/null; then
+  SKILL_NAME=$(echo "$INPUT" | jq -r '.tool_input.skill // empty' 2>/dev/null || echo "")
+else
+  SKILL_NAME=$(echo "$INPUT" | grep -oE '"skill"[[:space:]]*:[[:space:]]*"[^"]*"' | sed -E 's/.*"([^"]*)"$/\1/')
+fi
+
+# 대상 아니면 즉시 통과
+case "$SKILL_NAME" in
+  uzys:ship) ;;
+  *) exit 0 ;;
+esac
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+IGNORE_FILE="$PROJECT_DIR/.agentshield-ignore"
+SCAN_LOG="/tmp/agentshield-scan-$$.log"
+
+cd "$PROJECT_DIR" || exit 0
+
+# npx ecc-agentshield 실행 (타임아웃 안전 장치 없음 — ship 시점이라 사용자 대기 허용)
+if ! command -v npx &>/dev/null; then
+  echo "[agentshield-gate] npx not found — scan skipped (manual review required)" >&2
+  exit 0
+fi
+
+npx ecc-agentshield@1.4.0 scan > "$SCAN_LOG" 2>&1 || true
+
+# CRITICAL 섹션에서 finding 라인 추출
+CRITICAL_FINDINGS=$(awk '
+  /● CRITICAL/ { in_crit=1; next }
+  /● HIGH|● MEDIUM|● LOW|● INFO/ { in_crit=0 }
+  in_crit && /^[[:space:]]*●/ { print }
+' "$SCAN_LOG")
+
+if [ -z "$CRITICAL_FINDINGS" ]; then
+  rm -f "$SCAN_LOG"
+  echo "[agentshield-gate] No CRITICAL findings. Ship allowed." >&2
+  exit 0
+fi
+
+# ignore 파일 매칭
+FILTERED_FINDINGS=""
+while IFS= read -r line; do
+  [ -z "$line" ] && continue
+  MATCHED=false
+  if [ -f "$IGNORE_FILE" ]; then
+    while IFS= read -r pattern; do
+      # 빈 라인 / 주석 skip
+      case "$pattern" in
+        ""|"#"*) continue ;;
+      esac
+      # v26.11.2 — grep -F (fixed string) — `.*` 같은 regex로 모든 finding bypass 차단 (M4)
+      if echo "$line" | grep -qF "$pattern"; then
+        MATCHED=true
+        break
+      fi
+    done < "$IGNORE_FILE"
+  fi
+  if [ "$MATCHED" = false ]; then
+    FILTERED_FINDINGS="$FILTERED_FINDINGS$line"$'\n'
+  fi
+done <<< "$CRITICAL_FINDINGS"
+
+if [ -z "$FILTERED_FINDINGS" ]; then
+  rm -f "$SCAN_LOG"
+  echo "[agentshield-gate] CRITICAL findings all matched .agentshield-ignore. Ship allowed." >&2
+  exit 0
+fi
+
+# BLOCK
+echo "[agentshield-gate] BLOCKED: CRITICAL security findings detected" >&2
+echo "" >&2
+echo "$FILTERED_FINDINGS" >&2
+echo "" >&2
+echo "다음 조치 중 하나 필요:" >&2
+echo "  1. 실제 취약점 수정" >&2
+echo "  2. false-positive인 경우 .agentshield-ignore에 정규식 추가" >&2
+echo "  3. 스캔 로그 확인: $SCAN_LOG" >&2
+exit 2

package/templates/hooks/checkpoint-snapshot.sh

@@ -0,0 +1,115 @@
+#!/bin/bash
+# ============================================================
+# checkpoint-snapshot.sh — PostToolUse hook
+#
+# 목적: tool call count가 threshold 초과 시 현재 세션 스냅샷을
+#       docs/checkpoints/ 에 자동 저장하고 /compact 경고 flag 생성.
+#
+# 제약: Claude Code hook은 /compact 슬래시 커맨드를 직접 호출할 수
+#       없음. 따라서 "자동 compact"는 불가능 — 대신 checkpoint 저장 +
+#       session-start 경고로 사용자 수동 /compact 유도.
+#
+# Exit codes: 항상 0 (async hook, 차단 금지)
+# ============================================================
+set -u
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+THRESHOLD="${CHECKPOINT_THRESHOLD:-40}"
+SESSION_ID="${CLAUDE_SESSION_ID:-${PPID:-default}}"
+COUNTER_FILE="/tmp/claude-checkpoint-count-${SESSION_ID}"
+CHECKPOINT_DIR="$PROJECT_DIR/docs/checkpoints"
+WARNING_FLAG="$PROJECT_DIR/.claude/compact-warning.flag"
+
+# Counter increment
+if [ -f "$COUNTER_FILE" ]; then
+  count=$(cat "$COUNTER_FILE" 2>/dev/null || echo 0)
+  count=$((count + 1))
+  echo "$count" > "$COUNTER_FILE"
+else
+  count=1
+  echo "$count" > "$COUNTER_FILE"
+fi
+
+# Threshold 미도달이면 종료
+if [ "$count" -lt "$THRESHOLD" ]; then
+  exit 0
+fi
+
+# threshold 초과 → checkpoint 저장
+mkdir -p "$CHECKPOINT_DIR" 2>/dev/null || exit 0
+
+TS=$(date +%Y%m%d-%H%M%S)
+CHECKPOINT_FILE="$CHECKPOINT_DIR/${TS}.md"
+
+# Git 정보 수집 (git 미존재 환경 안전)
+GIT_BRANCH="(unknown)"
+GIT_HEAD="(unknown)"
+GIT_STATUS="(unknown)"
+if command -v git &>/dev/null && [ -d "$PROJECT_DIR/.git" ]; then
+  GIT_BRANCH=$(cd "$PROJECT_DIR" && git branch --show-current 2>/dev/null || echo "(detached)")
+  GIT_HEAD=$(cd "$PROJECT_DIR" && git rev-parse --short HEAD 2>/dev/null || echo "(no commits)")
+  GIT_STATUS=$(cd "$PROJECT_DIR" && git status --short 2>/dev/null | head -20)
+fi
+
+# Gate status 수집
+GATE_SUMMARY="(no gate-status.json)"
+GATE_FILE="$PROJECT_DIR/.claude/gate-status.json"
+if [ -f "$GATE_FILE" ] && command -v jq &>/dev/null; then
+  GATE_SUMMARY=$(jq -r '
+    "define: \(.define.completed // false)\n" +
+    "plan: \(.plan.completed // false)\n" +
+    "build: \(.build.completed // false)\n" +
+    "verify: \(.verify.completed // false)\n" +
+    "review: \(.review.completed // false)\n" +
+    "ship: \(.ship.completed // false)"
+  ' "$GATE_FILE" 2>/dev/null || echo "(parse error)")
+fi
+
+# Checkpoint 파일 작성
+cat > "$CHECKPOINT_FILE" <<EOF
+# Checkpoint — $TS
+
+> 자동 생성 by checkpoint-snapshot.sh (tool count $count >= $THRESHOLD).
+> 사용자 수동 \`/compact\` 실행 권장. 이 파일은 compact 후 컨텍스트 복원 힌트로 사용.
+
+## Git
+
+- Branch: $GIT_BRANCH
+- HEAD: $GIT_HEAD
+
+### Changed Files
+\`\`\`
+$GIT_STATUS
+\`\`\`
+
+## Gate Status
+
+\`\`\`
+$GATE_SUMMARY
+\`\`\`
+
+## Session ID
+- \`$SESSION_ID\`
+- Tool count at snapshot: $count
+
+## Recovery Hint
+
+compact 후 다음을 확인:
+1. \`git status\` — 변경 사항 복원
+2. \`docs/SPEC.md\` + \`docs/todo.md\` — 현재 작업 컨텍스트
+3. 위 Gate Status — 어느 단계에 있었는지
+4. 최근 checkpoint: \`ls -t docs/checkpoints/ | head -5\`
+EOF
+
+# Counter 리셋
+echo "0" > "$COUNTER_FILE"
+
+# Warning flag 생성 (session-start hook이 감지해서 경고 재표시)
+mkdir -p "$(dirname "$WARNING_FLAG")"
+echo "$TS" > "$WARNING_FLAG"
+
+# stderr에 즉시 경고 (async이므로 차단 안 됨)
+echo "[checkpoint-snapshot] Tool count $count reached. Saved: $CHECKPOINT_FILE" >&2
+echo "[checkpoint-snapshot] Consider running /compact to reclaim context window." >&2
+
+exit 0