feat(lefthook): pre-push 3 hook incremental gate + envtest 자동 보장 (ADR-0024)

[eightynine01]

Summary

• RFC-0002 (GHA → 로컬 4계층) 후 발견된 push 차단 부채 3건 을 incremental gate 로 해결
• .lefthook.yml pre-push 3 hook 수정: unit-test (envtest 자동) + full-lint (--new-from-rev=origin/main) + markdown-link-check (PR 변경 .md 만)
• ADR-0024 신규 (Nygard 5 sections) + docs/kb/adr/INDEX.md 갱신

사용자 시나리오 (Given / When / Then)

Given: 신규 contributor 가 postgres-operator clone 후 문서만 변경한 PR push.

When (이전, 본 PR 전): pre-push hook 이 (1) KUBEBUILDER_ASSETS 미설정 → webhook BeforeSuite fork/exec fail, (2) full-lint 가 기존 main 의 8 modernize/staticcheck 부채로 fail, (3) markdown-link-check 가 기존 22 dead link 로 fail → 머지 0%.

Then (본 PR 후): 동일 contributor 가 (1) make setup-envtest 자동 호출 → KUBEBUILDER_ASSETS 절대 경로 자동 export, (2) --new-from-rev=origin/main 으로 PR 신규 이슈만 평가, (3) PR 변경 .md 만 link check → 문서 PR 정상 통과. 기존 부채는 별개 PR 로 누적 처리.

변경 내역

파일	변경
.lefthook.yml (pre-push)	unit-test: make setup-envtest 자동 + KUBEBUILDER_ASSETS 절대 경로
.lefthook.yml (pre-push)	full-lint: --new-from-rev=origin/main (HEAD~1 fallback)
.lefthook.yml (pre-push)	markdown-link-check: git diff --name-only \$BASE...HEAD | grep .md\$ 변경 파일만
docs/kb/adr/0024-lefthook-pre-push-incremental-lint-envtest.md	신규 ADR (Nygard 5 sections) — 22 dead link 목록 명시
docs/kb/adr/INDEX.md	0024 entry 추가

검증 (push 실제 결과 인용)

```
✔️ full-lint (1.97 seconds)
✔️ gitleaks (0.08 seconds)
✔️ go-licenses (0.02 seconds)
✔️ go-mod-tidy (0.10 seconds)
✔️ govulncheck (0.02 seconds)
✔️ helm-lint (0.20 seconds)
✔️ helm-template (0.06 seconds)
✔️ kube-linter (0.18 seconds)
✔️ markdown-link-check (0.50 seconds)
✔️ platforms-amd64-guard (0.02 seconds)
✔️ unit-test (20.14 seconds)
✔️ version-sync (0.06 seconds)
```

3 hook 모두 수정된 incremental wrapping 으로 통과.

Test plan

• make setup-envtest → bin/k8s//{etcd,kube-apiserver,kubectl} 다운로드
• KUBEBUILDER_ASSETS=\$(pwd)/bin/k8s/1.36.0-darwin-arm64 go test ./internal/webhook/v1alpha1/... → PASS 9.5s
• ./bin/golangci-lint run --new-from-rev=origin/main → 0 issues (PR Go 변경 0)
• markdown-link-check -q for 2 staged .md → 0 dead links
• 전체 pre-push hook (push 실제 실행) → 12/12 PASS

후속 작업 (별개 PR 로 누적)

• 8 modernize/staticcheck 이슈 fix (ptrInt64/scheme.Builder 등)
• 22 dead link fix (README/CHANGELOG/family/index/PR-8109 등) — ADR-0024 Context 섹션 목록 참조
• mongodb-operator + valkey-operator 동일 .lefthook.yml 패턴 sister-port

Related

• ADR-0024 (본 PR)
• RFC-0002 (GHA 영구 금지, 2026-04-29)
• ADR-0018 (GHA → 로컬 4계층), ADR-0021 (gha-block hook)