/commit-push-pr

allowed-tools: Bash(git:*), Bash(gh:*), Bash(npm:*), Bash(python:*), Bash(go:*), Bash(cargo:*), Bash(make:*), Read, Grep, Glob, Edit, Write, Skill(sync-docs)
description: 머지 전 /sync-docs 문서 동기화 의무 게이트 → 검증 → 커밋 & PR & 머지 + MCP 알림 (v7)
argument-hint: "[커밋 메시지] [--merge|--squash|--rebase] [--draft] [--no-verify] [--no-checklist] [--skip-security] [--skip-sync-docs] [--notify]"

Task

0단계: Context 수집

git status --short
git branch --show-current
git rev-parse --abbrev-ref origin/HEAD 2>/dev/null | sed 's/origin\///' || echo "main"
git log --oneline -3
git diff --staged --stat 2>/dev/null || git diff --stat
git remote get-url origin 2>/dev/null
gh --version 2>/dev/null | head -1 || echo "not installed"

---

1단계: 인자 파싱

**$ARGUMENTS에서 옵션 추출:**

• `--merge` → 머지 모드: merge commit
• `--squash` → 머지 모드: squash merge
• `--rebase` → 머지 모드: rebase merge
• `--draft` → Draft PR (머지 옵션과 함께 사용 불가)
• `--no-verify` → 빌드/테스트 스킵
• `--no-checklist` → 머지 후 웹 체크리스트 생성 스킵
• `--skip-security` → 보안 사전 검증 스킵
• `--skip-sync-docs` → 문서 동기화 게이트 스킵 (긴급 hotfix 전용, v7 신규 — 머지 모드에서는 경고 출력)
• `--notify` → 머지 후 MCP 알림 발송 (v6 신규)
• 나머지 → 커밋 메시지

**`--draft`와 머지 옵션 동시 사용 시:**

--draft와 머지 옵션(--merge/--squash/--rebase)은 함께 사용할 수 없습니다.

Draft PR은 머지하지 않고 리뷰용으로 생성됩니다.

→ 중단

---

2단계: 사전 체크

**변경사항 없으면:**

커밋할 변경사항이 없습니다.

현재 상태:
- 브랜치: [브랜치명]
- 마지막 커밋: [커밋 메시지]

→ 중단

**main/master 브랜치면:**

main 브랜치에서 직접 커밋하려고 합니다.

권장: 브랜치 생성 후 작업
  git checkout -b feature/[기능명]

옵션:
1. "브랜치 생성" - 새 브랜치 만들고 진행
2. "계속" - main에 직접 커밋 (PR 생략)
3. "취소" - 작업 중단

---

3단계: 빌드/테스트 검증

**`--no-verify` 있으면 스킵.**

프로젝트 타입별 검증:

| 파일 | 타입 | 검증 명령 | |------|------|----------| | package.json | Node.js | `npm run build && npm test` | | pyproject.toml / setup.py | Python | `python -m pytest` | | go.mod | Go | `go build ./... && go test ./...` | | Cargo.toml | Rust | `cargo build && cargo test` | | Makefile | Make | `make test` |

**실패 시:**

검증 실패

[에러 메시지]

해결 후 다시 시도하거나:
  /commit-push-pr --no-verify

→ 중단

---

3.5단계: Merge Gate (자동 품질 관문)

커밋 전 아래 4개 조건을 **AND**로 검증한다. 하나라도 FAIL이면 커밋을 중단한다.

| 검증 항목 | 명령어 | FAIL 조건 | --no-verify 시 | |-----------|--------|-----------|---------------| | 빌드 | `npm run build` | exit code ≠ 0 | 스킵 가능 | | 테스트 | `npm test` | exit code ≠ 0 | 스킵 가능 | | 린트 | `npm run lint` | exit code ≠ 0 | 스킵 가능 | | 보안 스캔 | security-reviewer agent | CRITICAL 발견 | **스킵 불가** |

**게이트 실패 시 출력 형식:**

┌─────────────┬────────┬──────────────────┐
│ 검증 항목    │ 결과   │ 상세              │
├─────────────┼────────┼──────────────────┤
│ 빌드        │ PASS   │                   │
│ 테스트      │ FAIL   │ 2 tests failed    │
│ 린트        │ PASS   │                   │
│ 보안 스캔   │ PASS   │                   │
└─────────────┴────────┴──────────────────┘
❌ Merge Gate FAIL: 테스트 실패. 커밋을 중단합니다.

**규칙:**

• `--no-verify` 플래그가 있으면 빌드/테스트/린트는 스킵 가능
• 보안 스캔에서 CRITICAL이 발견되면 `--no-verify`여도 **반드시 차단**
• 모든 검증이 PASS면 다음 단계(4단계)로 진행

---

4단계: 보안 검증

> **머지 옵션이 있을 때만 실행.** PR만 생성하는 경우 스킵. > `--skip-security` 있으면 스킵 (경고 출력 후).

**`--skip-security` 사용 시:**

보안 검증을 건너뜁니다 (--skip-security)
   머지 후 반드시 수동 보안 검토를 수행하세요.

→ 5단계로 진행

**보안 검증 실행:**

**4-1. 변경 파일 수집:**

git diff --cached --name-only 2>/dev/null || git diff --name-only

**4-2. 보안 민감 파일 자동 감지:**

다음 패턴에 해당하는 파일이 변경 목록에 있으면 보안 검증 **강제 실행** (--skip-security 무시):

| 패턴 | 영역 | |------|------| | `auth/*`, `**/auth/**` | 인증 | | `payment/*`, `**/payment/**` | 결제 | | `session/*`, `**/session/**` | 세션 | | `*secret*`, `*token*`, `*password*` | 시크릿 | | `middleware*`, `**/middleware/**` | 미들웨어 | | `.env*`, `*credentials*` | 환경변수/자격증명 | | `**/api/admin/**` | 관리자 API |

**4-3. 보안 스캔 항목:**

| 검사 항목 | 패턴 | 심각도 | |-----------|------|--------| | 하드코딩된 시크릿 | `sk-`, `pk_`, `AKIA`, `ghp_`, `password\s*=\s*["']` | CRITICAL | | SQL 인젝션 | 문자열 보간 SQL, `${}` in query | CRITICAL | | XSS 취약점 | `dangerouslySetInnerHTML`, `innerHTML =` | HIGH | | 민감 데이터 로깅 | `console.log.*password`, `console.log.*token` | HIGH | | 하드코딩 URL | `http://localhost` in production code | MEDIUM | | 취약한 의존성 | `package.json` 변경 시 known vulnerabilities | MEDIUM | | 인증 우회 | `auth.*skip`, `verify.*false`, `bypass` | HIGH | | CORS 설정 | `Access-Control-Allow-Origin: *` | MEDIUM |

**4-4. 결과 처리:**

**CRITICAL 발견 시 → 머지 차단:**

보안 검증 실패 - 머지 차단
─────────────────────────────────

CRITICAL 이슈 발견:

  [파일:라인] [CWE-XXX] [설명]

수정 제안:
  [구체적 수정 방법]

수정 후 다시 시도:
  /commit-push-pr [원래 옵션들]
─────────────────────────────────

→ 중단

**HIGH/MEDIUM만 발견 시 → 경고 후 진행:**

보안 검증 완료 (경고 있음)
─────────────────────────────────

HIGH: [N]건
  [파일:라인] [설명]

MEDIUM: [N]건
  [파일:라인] [설명]

머지를 계속 진행합니다.
─────────────────────────────────

→ 5단계로 진행

**이슈 없음:**

보안 검증 통과
─────────────────────────────────
  스캔 파일: [N]개
  발견 이슈: 없음 (CWE scan clean)
─────────────────────────────────

→ 5단계로 진행

**보안 검증 결과 변수 저장:**

• `$SECURITY_STATUS` → "pass" | "warn" | "block"
• `$SECURITY_SUMMARY` → PR 본문에 포함할 요약 텍스트

---

4.5단계: /sync-docs 문서 동기화 게이트 (머지 전 의무, v7 CRITICAL)

> **머지 옵션(`--merge`/`--squash`/`--rebase`)이 있으면 이 단계는 의무다.** > 인라인 요약 갱신으로 대체 금지 — 반드시 **Skill 도구로 실제 `/sync-docs` 스킬을 실행**한다. > 사용자에게 되묻지 않고 자동 실행한다 (frontmatter `Skill(sync-docs)` 사전 승인).

**실행 규칙:**

| 모드 | 동작 | |------|------| | 머지 모드 (`--merge`/`--squash`/`--rebase`) | **`sync-docs` 의무 실행. 스킵 불가** (`--skip-sync-docs` 명시 시에만 경고 후 스킵 — 긴급 hotfix 전용) | | PR-only / `--draft` | `sync-docs` 기본 실행 (`--skip-sync-docs`로 스킵 가능) |

**실행 방법 (자동 — 사용자 확인 불필요):**

Skill 도구 호출: skill = "sync-docs"

`/sync-docs` v7.1이 수행하는 것: 1. `prompt_plan.md` → 완료 항목 체크 + 진행 상황 갱신 2. `spec.md` → 구현 기능/API/데이터 모델 반영 3. `CLAUDE.md` → 명령어/구조 변경 반영 (200줄 원칙) 4. `.claude/rules/` → glob 매핑 기반 규칙 동기화 5. 흩어진 파일 housekeeping scan (PII/시크릿 감지)

**게이트 규칙:**

• sync-docs가 변경한 문서는 5단계 `git add -A`로 **같은 커밋에 포함**한다 (별도 커밋 생성 금지)
• sync-docs housekeeping scan이 `alert`(PII/시크릿)를 반환하면 → **커밋/머지 중단** + `/save-work --apply` 안내
• `--skip-sync-docs` + 머지 모드 조합 시 경고 출력 후 진행:

⚠ 문서 동기화 게이트