feat(hooks): 커밋 게이트가 package.json lint 스크립트를 돌린다

[hsleedevelop]

요약

커밋 게이트 templates/.claude/hooks/pre-commit-check.sh가 package.json에 lint 스크립트가 있을 때 커밋 직전에 결정론적으로 실행한다. 지금까지 lint는 사람이 /verify를 부를 때만 돌았다. 특정 린터나 규칙은 내장하지 않고 프로젝트가 이미 설정한 스크립트를 그대로 쓴다(스택 중립).

• 순서: typecheck → lint → test (싼 검사 먼저)
• $PM run lint 결과에 따라
  • 0 → 통과
  • 127 (command not found, 린터 미설치) → ⚠ 경고 두 줄 후 통과
  • 그 외 non-zero (실제 위반) → ❌ exit 2로 차단
• has_test_script를 has_script <name>으로 일반화해 test와 lint가 함께 쓴다. jq가 없으면 node로 판정한다(기존 폴백 그대로).
• jq-fallback 공통 블록과 timeout 120s는 바꾸지 않았다.

의도된 비대칭: lint 127은 경고, test 127은 차단

test 게이트는 바꾸지 않았다. test는 127이어도 계속 차단한다. lint만 127을 경고로 낮춘 이유는 착수 전 소비자 실측 때문이다. deep-math의 lint 스크립트가 eslint 미설치로 exit 127이었다. 차단으로 도입하면 stock 훅을 쓰는 소비자의 모든 커밋이 갑자기 막힌다. 이 결정(C안)은 spec, overview 카드, hooks.mmd에 명시했다.

PM별 127 전파 실측

빈 프로젝트에 "lint": "nonexistent-linter-xyz ."를 두고 <pm> run lint를 실행했다.

PM	버전	exit
npm	11.9.0	127
pnpm	12.4.1	127
yarn classic	1.22.22	127
yarn berry	4.5.0 (yarn install 후)	127
bun	1.3.9	127

예외: yarn berry에서 install하지 않은 프로젝트는 스크립트를 실행하기 전에 lockfile 오류로 exit 1이 나온다. 위반과 구분할 수 없으므로 차단된다. PM 바이너리 자체가 없으면 127이 나와 lint는 경고하고, test 게이트가 같은 이유로 차단한다.

소비자 영향

• deep-math: npm run lint → exit 127 (eslint: command not found, 의존성과 설정 모두 없음). 훅이 stock이라 migrate로 새 게이트가 배달된다. 그 뒤 매 커밋 ⚠ 경고가 나오지만 차단되지는 않는다.
• heliosent-profile: bun run lint → exit 0. 다만 훅이 커스터마이즈본(bun.lock 감지 추가)이라 migrate가 덮지 않으므로 lint 게이트가 배달되지 않는다(기존 보존 계약).
• 배달 경로: 직전 판(blob ed90db5b)을 KNOWN_STOCK_HOOK_SHA256과 tests/fixtures/stock-hooks/pre-lint/에 추가했다. stock 설치본은 refresh로 갱신되고, 커스터마이즈본은 보존된다.

검증

$ npm run test      → exit 0
ℹ tests 1088 · pass 1087 · fail 0 · skipped 1   (skip = CI 전용 jq 매트릭스 가드)
ℹ tests 1 · pass 1 · fail 0                      (perf)
$ npm run docs:check → harness overview 생성 상태가 최신입니다.

• tests/hooks-jq-fallback.test.mjs: npm 스텁으로 lint 위반 / 통과 / 스크립트 없음 / 127 경고 후 통과(test 127은 차단)를 jq 있음과 없음 양쪽에서 확인한다.
• tests/migrate-hooks.test.mjs: pre-lint 판 stock 설치본이 refresh로 lint 게이트를 받는지 확인한다.
• 판별력: 구 훅으로 바꿔 실행하면 신규 lint 테스트 6건이 실패한다.
• 리뷰: Codex read-only 결함 0건, codex-shipcheck S1–S5 PASS. 기록은 docs/hslee/commit-gate-lint/commit-gate-lint-artifact.md ## Reviews에 있다.

후속 후보 (이 PR 범위 밖)

• 템플릿의 detect_pm이 bun.lockb만 봐서 bun 1.2+ 텍스트 락파일 bun.lock 프로젝트를 npm으로 오인한다.
• heliosent-profile의 커스터마이즈 훅에는 lint 게이트가 배달되지 않는다(수동 병합 또는 bun.lock 수정의 템플릿 반영 필요).
• deep-math의 죽은 lint 스크립트 정리(eslint 설치 또는 스크립트 제거).
• package.json 없는 프로젝트(ruff를 쓰는 job-scraper)로의 확장.

🤖 Generated with Claude Code

[hsleedevelop]

닫습니다. 2026-10-05 범위 재검토에서 커밋 게이트(typecheck·lint·test)와 auto-format을 하네스 범위에서 빼기로 결정했습니다. 품질 게이트는 프로젝트 도구(husky·lefthook·CI)의 몫으로 둡니다. 근거는 1.0 범위 헌장(D11 후보)에 기록합니다. 브랜치는 지우지 않았습니다.