BumgeunSong · July 30, 2026 13:46
diff --git a/README.md b/README.md
diff --git a/mutation_gate.py b/mutation_gate.py
 #!/usr/bin/env python3
 """
 Mutation 검증 게이트 — PreToolUse / Bash 훅.

 커밋에 테스트 파일이 스테이징되어 있으면, 커밋 메시지에 mutation 검증 이행 기록
 (Mutation-Verified trailer)이 있는지 확인한다. 없으면 커밋을 막고 무엇을 해야 하는지
 알려준다.

  왜 필요한가
    통과하는 테스트도 false green일 수 있다 — 지킨다고 주장하는 동작이 깨져도 여전히
    초록불인 테스트. mutation 검증은 이걸 걸러내는 절차이고, 이 훅은 그 절차를 잊지
    않게 만드는 장치다.

  이 훅이 하지 않는 것
    mutation을 직접 실행하지 않는다. 검증의 '질'도 판정하지 않는다. 커밋 메시지에
    한 줄이 있는지만 본다. 즉 이건 증명이 아니라 마찰이다. 결정적으로 검사할 수 있는
    지점까지만 결정적으로 검사하고, 나머지는 사람과 스킬에 맡긴다.

  통과하는 두 가지 형태
    Mutation-Verified: killed 3 / survived 1(아무도 안 지킴) by mutation-verify
    Mutation-Verified: skip(no assertion change) by mutation-verify

    단언·케이스를 안 건드린 순수 리팩터(이름·서식·이동)는 검증할 새 보장이 없으므로
    skip(...) 을 쓴다.

  발동하지 않는 경우 (전부 fail-open)
    - git commit 이 아닌 명령
    - 스테이징된 테스트 파일이 없음
    - 메시지를 명령 문자열에서 읽을 수 없는 형태 (-F/--file, 편집기 사용 등)
    - git 저장소가 아니거나 git 호출 실패

  설계 원칙
    잘못 막는 훅은 없는 훅보다 나쁘다. 판단이 애매하면 항상 통과시킨다.

  의식적 우회
    명령 앞에 ALLOW_NO_MUTATION=1 을 붙인다.

  설치
    cp mutation_gate.py .claude/hooks/
    chmod +x .claude/hooks/mutation_gate.py

    .claude/settings.json:
      {"hooks": {"PreToolUse": [{"matcher": "Bash", "hooks": [
        {"type": "command", "command": "python3 .claude/hooks/mutation_gate.py"}]}]}}

  author : bumgeun-song
  license: MIT
 """

 from __future__ import annotations

 import fnmatch
 import json
 import os
 import re
 import shlex
 import subprocess
 import sys

 # ---------------------------------------------------------------------------
 # 설정 — 프로젝트에 맞게 조정
 # ---------------------------------------------------------------------------

 # 이 패턴에 걸리는 파일이 스테이징되어 있을 때만 훅이 관여한다.
 TEST_GLOBS = [
    "**/*.test.ts", "**/*.test.tsx", "**/*.test.js", "**/*.test.jsx",
    "**/*.spec.ts", "**/*.spec.tsx", "**/*.spec.js", "**/*.spec.jsx",
    "**/*.e2e.ts", "**/*.e2e.js",
    "**/test_*.py", "**/*_test.py", "**/*_test.go",
 ]

 # 검증 절차가 적힌 스킬 이름. 거부 메시지에 그대로 노출된다.
 SKILL_NAME = "mutation-verify"

 TRAILER_KEY = "Mutation-Verified:"
 ESCAPE_HATCH = re.compile(r"\bALLOW_NO_MUTATION=(?:1|true|TRUE|yes)\b")

 # 환경변수로 덮어쓸 수 있게 해둔다 (콤마 구분).
 if os.environ.get("MUTATION_GATE_TEST_GLOBS"):
    TEST_GLOBS = [g.strip() for g in
                  os.environ["MUTATION_GATE_TEST_GLOBS"].split(",") if g.strip()]


 # ---------------------------------------------------------------------------
 # 셸 명령 파싱
 # ---------------------------------------------------------------------------

 _GIT_COMMIT = re.compile(r"^((?:[A-Za-z_][A-Za-z0-9_]*=\S*\s+)*)git\s+commit(?:\s|$)")
 _LEADING_KEYWORD = re.compile(r"^(?:if|then|else|elif|do|while|until|for|!|\$\()\s+")
 _EXTERNAL_FLAGS = {"-F", "--file", "-C", "--reuse-message"}


 def split_pipeline(s: str) -> list[str]:
    """따옴표를 존중하면서 ; | && || 개행으로 명령을 분절한다.

    단순 부분문자열 검색(`"git commit" in cmd`)으로 판단하면 안 된다.
    커밋 메시지 본문에 'git commit'이라는 글자가 들어 있는 경우처럼,
    엉뚱한 명령을 커밋으로 오인하게 된다.
    """
    parts: list[str] = []
    buf: list[str] = []
    in_single = in_double = False
    i = 0
    while i < len(s):
        ch = s[i]
        nxt = s[i + 1] if i + 1 < len(s) else ""
        if ch == "\\" and i + 1 < len(s):
            buf.append(ch)
            buf.append(s[i + 1])
            i += 2
            continue
        if ch == '"' and not in_single:
            in_double = not in_double
        elif ch == "'" and not in_double:
            in_single = not in_single
        if not in_single and not in_double:
            if (ch == "&" and nxt == "&") or (ch == "|" and nxt == "|"):
                parts.append("".join(buf))
                buf = []
                i += 2
                continue
            if ch in ";|\n":
                parts.append("".join(buf))
                buf = []
                i += 1
                continue
        buf.append(ch)
        i += 1
    parts.append("".join(buf))
    return [p.strip() for p in parts if p.strip()]


 def classify_command(cmd: str) -> str:
    """'skip' | 'external' | 'inline' 중 하나를 돌려준다.

    skip     — 검사 대상이 아니다 (커밋이 아니거나 우회가 걸렸다)
    external — 커밋이지만 메시지를 명령 문자열에서 읽을 수 없다 → fail-open
    inline   — 메시지가 명령 안에 있다 → 검사 가능
    """
    for segment in split_pipeline(cmd):
        segment = _LEADING_KEYWORD.sub("", segment)
        match = _GIT_COMMIT.match(segment)
        if not match:
            continue

        if ESCAPE_HATCH.search(match.group(1) or ""):
            return "skip"

        try:
            tokens = shlex.split(segment)
        except ValueError:
            tokens = []

        has_inline = bool(re.search(r"(^|\s)(-m\b|--message)", segment)) or "<<" in segment
        has_external = any(
            t in _EXTERNAL_FLAGS
            or t.startswith("--file=")
            or t.startswith("--reuse-message=")
            for t in tokens
        )

        if has_inline:
            return "inline"
        if has_external or "--amend" in tokens:
            return "external"
        # 맨몸 `git commit` — 편집기가 열린다. 메시지를 볼 수 없다.
        return "external"

    return "skip"


 # ---------------------------------------------------------------------------
 # git 조회
 # ---------------------------------------------------------------------------

 def staged_test_files() -> list[str]:
    """스테이징된 파일 중 테스트 패턴에 걸리는 것들. 실패하면 빈 리스트(=통과)."""
    try:
        subprocess.run(
            ["git", "rev-parse", "--git-dir"],
            check=True, capture_output=True, timeout=5,
        )
        out = subprocess.run(
            ["git", "-c", "core.quotepath=false",
             "diff", "--cached", "--name-only", "--diff-filter=d"],
            check=True, capture_output=True, text=True, timeout=5,
        ).stdout
    except Exception:
        return []

    hits = []
    for path in (line.strip() for line in out.splitlines()):
        if not path:
            continue
        name = os.path.basename(path)
        if any(fnmatch.fnmatch(path, g) or fnmatch.fnmatch(name, g.rsplit("/", 1)[-1])
               for g in TEST_GLOBS):
            hits.append(path)
    return hits


 # ---------------------------------------------------------------------------
 # 출력
 # ---------------------------------------------------------------------------

 def allow() -> None:
    sys.exit(0)


 def deny(reason: str) -> None:
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",
            "permissionDecisionReason": reason,
        }
    }, ensure_ascii=False))
    sys.exit(0)


 def build_reason(files: list[str]) -> str:
    listed = "\n".join(f"  - {f}" for f in files)
    return f"""이 커밋에 테스트 파일이 있는데 mutation 검증 기록이 없어요.

 {listed}

 테스트의 단언이나 케이스를 바꿨다면, 커밋 전에 mutation을 심어 false green을
 걸러야 합니다. `{SKILL_NAME}` 스킬을 읽고 수행한 뒤, 커밋 메시지 끝에 아래 trailer를
 한 줄 추가하고 다시 커밋하세요.

  {TRAILER_KEY} killed <N> / survived <M>(<분류>) by {SKILL_NAME}

 단언·케이스를 안 건드린 순수 리팩터(이름·서식·이동)라면 검증할 새 보장이 없으니
 skip으로 남기세요.

  {TRAILER_KEY} skip(no assertion change) by {SKILL_NAME}

 이 게이트는 검증을 증명하지 못합니다. 서명만 먼저 쓰고 검증을 건너뛸 수도 있지만,
 그러면 남는 건 아무것도 지키지 않는 초록불뿐입니다.

 의식적으로 건너뛰려면 명령 앞에 'ALLOW_NO_MUTATION=1 ' 를 붙이세요."""


 # ---------------------------------------------------------------------------

 def main() -> None:
    try:
        event = json.load(sys.stdin)
    except Exception:
        allow()

    cmd = (event.get("tool_input") or {}).get("command") or ""
    if not cmd:
        allow()

    verdict = classify_command(cmd)
    if verdict in ("skip", "external"):
        allow()

    files = staged_test_files()
    if not files:
        allow()

    if TRAILER_KEY in cmd:
        allow()

    deny(build_reason(files))


 if __name__ == "__main__":
    try:
        main()
    except Exception:
        # 훅의 버그가 커밋을 막는 일은 없어야 한다.
        sys.exit(0)
diff --git a/SKILL.md b/SKILL.md
파일	역할
`SKILL.md`	Agent Skill. 관문 → 설계 → 실행 → 판정 → 종결 + 부록 2개
`mutation_gate.py`	커밋 게이트 훅. 검증 기록이 없으면 커밋을 막는다
	#!/usr/bin/env python3
	"""
	Mutation 검증 게이트 — PreToolUse / Bash 훅.

	커밋에 테스트 파일이 스테이징되어 있으면, 커밋 메시지에 mutation 검증 이행 기록
	(Mutation-Verified trailer)이 있는지 확인한다. 없으면 커밋을 막고 무엇을 해야 하는지
	알려준다.

	왜 필요한가
	통과하는 테스트도 false green일 수 있다 — 지킨다고 주장하는 동작이 깨져도 여전히
	초록불인 테스트. mutation 검증은 이걸 걸러내는 절차이고, 이 훅은 그 절차를 잊지
	않게 만드는 장치다.

	이 훅이 하지 않는 것
	mutation을 직접 실행하지 않는다. 검증의 '질'도 판정하지 않는다. 커밋 메시지에
	한 줄이 있는지만 본다. 즉 이건 증명이 아니라 마찰이다. 결정적으로 검사할 수 있는
	지점까지만 결정적으로 검사하고, 나머지는 사람과 스킬에 맡긴다.

	통과하는 두 가지 형태
	Mutation-Verified: killed 3 / survived 1(아무도 안 지킴) by mutation-verify
	Mutation-Verified: skip(no assertion change) by mutation-verify

	단언·케이스를 안 건드린 순수 리팩터(이름·서식·이동)는 검증할 새 보장이 없으므로
	skip(...) 을 쓴다.

	발동하지 않는 경우 (전부 fail-open)
	- git commit 이 아닌 명령
	- 스테이징된 테스트 파일이 없음
	- 메시지를 명령 문자열에서 읽을 수 없는 형태 (-F/--file, 편집기 사용 등)
	- git 저장소가 아니거나 git 호출 실패

	설계 원칙
	잘못 막는 훅은 없는 훅보다 나쁘다. 판단이 애매하면 항상 통과시킨다.

	의식적 우회
	명령 앞에 ALLOW_NO_MUTATION=1 을 붙인다.

	설치
	cp mutation_gate.py .claude/hooks/
	chmod +x .claude/hooks/mutation_gate.py

	.claude/settings.json:
	{"hooks": {"PreToolUse": [{"matcher": "Bash", "hooks": [
	{"type": "command", "command": "python3 .claude/hooks/mutation_gate.py"}]}]}}

	author : bumgeun-song
	license: MIT
	"""

	from __future__ import annotations

	import fnmatch
	import json
	import os
	import re
	import shlex
	import subprocess
	import sys

	# ---------------------------------------------------------------------------
	# 설정 — 프로젝트에 맞게 조정
	# ---------------------------------------------------------------------------

	# 이 패턴에 걸리는 파일이 스테이징되어 있을 때만 훅이 관여한다.
	TEST_GLOBS = [
	"*/.test.ts", "*/.test.tsx", "*/.test.js", "*/.test.jsx",
	"*/.spec.ts", "*/.spec.tsx", "*/.spec.js", "*/.spec.jsx",
	"*/.e2e.ts", "*/.e2e.js",
	"*/test_.py", "*/_test.py", "*/_test.go",
	]

	# 검증 절차가 적힌 스킬 이름. 거부 메시지에 그대로 노출된다.
	SKILL_NAME = "mutation-verify"

	TRAILER_KEY = "Mutation-Verified:"
	ESCAPE_HATCH = re.compile(r"\bALLOW_NO_MUTATION=(?:1\|true\|TRUE\|yes)\b")

	# 환경변수로 덮어쓸 수 있게 해둔다 (콤마 구분).
	if os.environ.get("MUTATION_GATE_TEST_GLOBS"):
	TEST_GLOBS = [g.strip() for g in
	os.environ["MUTATION_GATE_TEST_GLOBS"].split(",") if g.strip()]


	# ---------------------------------------------------------------------------
	# 셸 명령 파싱
	# ---------------------------------------------------------------------------

	_GIT_COMMIT = re.compile(r"^((?:[A-Za-z_][A-Za-z0-9_]=\S\s+)*)git\s+commit(?:\s\|$)")
	_LEADING_KEYWORD = re.compile(r"^(?:if\|then\|else\|elif\|do\|while\|until\|for\|!\|\$\()\s+")
	_EXTERNAL_FLAGS = {"-F", "--file", "-C", "--reuse-message"}


	def split_pipeline(s: str) -> list[str]:
	"""따옴표를 존중하면서 ; \| && \|\| 개행으로 명령을 분절한다.

	단순 부분문자열 검색(`"git commit" in cmd`)으로 판단하면 안 된다.
	커밋 메시지 본문에 'git commit'이라는 글자가 들어 있는 경우처럼,
	엉뚱한 명령을 커밋으로 오인하게 된다.
	"""
	parts: list[str] = []
	buf: list[str] = []
	in_single = in_double = False
	i = 0
	while i < len(s):
	ch = s[i]
	nxt = s[i + 1] if i + 1 < len(s) else ""
	if ch == "\\" and i + 1 < len(s):
	buf.append(ch)
	buf.append(s[i + 1])
	i += 2
	continue
	if ch == '"' and not in_single:
	in_double = not in_double
	elif ch == "'" and not in_double:
	in_single = not in_single
	if not in_single and not in_double:
	if (ch == "&" and nxt == "&") or (ch == "\|" and nxt == "\|"):
	parts.append("".join(buf))
	buf = []
	i += 2
	continue
	if ch in ";\|\n":
	parts.append("".join(buf))
	buf = []
	i += 1
	continue
	buf.append(ch)
	i += 1
	parts.append("".join(buf))
	return [p.strip() for p in parts if p.strip()]


	def classify_command(cmd: str) -> str:
	"""'skip' \| 'external' \| 'inline' 중 하나를 돌려준다.

	skip — 검사 대상이 아니다 (커밋이 아니거나 우회가 걸렸다)
	external — 커밋이지만 메시지를 명령 문자열에서 읽을 수 없다 → fail-open
	inline — 메시지가 명령 안에 있다 → 검사 가능
	"""
	for segment in split_pipeline(cmd):
	segment = _LEADING_KEYWORD.sub("", segment)
	match = _GIT_COMMIT.match(segment)
	if not match:
	continue

	if ESCAPE_HATCH.search(match.group(1) or ""):
	return "skip"

	try:
	tokens = shlex.split(segment)
	except ValueError:
	tokens = []

	has_inline = bool(re.search(r"(^\|\s)(-m\b\|--message)", segment)) or "<<" in segment
	has_external = any(
	t in _EXTERNAL_FLAGS
	or t.startswith("--file=")
	or t.startswith("--reuse-message=")
	for t in tokens
	)

	if has_inline:
	return "inline"
	if has_external or "--amend" in tokens:
	return "external"
	# 맨몸 `git commit` — 편집기가 열린다. 메시지를 볼 수 없다.
	return "external"

	return "skip"


	# ---------------------------------------------------------------------------
	# git 조회
	# ---------------------------------------------------------------------------

	def staged_test_files() -> list[str]:
	"""스테이징된 파일 중 테스트 패턴에 걸리는 것들. 실패하면 빈 리스트(=통과)."""
	try:
	subprocess.run(
	["git", "rev-parse", "--git-dir"],
	check=True, capture_output=True, timeout=5,
	)
	out = subprocess.run(
	["git", "-c", "core.quotepath=false",
	"diff", "--cached", "--name-only", "--diff-filter=d"],
	check=True, capture_output=True, text=True, timeout=5,
	).stdout
	except Exception:
	return []

	hits = []
	for path in (line.strip() for line in out.splitlines()):
	if not path:
	continue
	name = os.path.basename(path)
	if any(fnmatch.fnmatch(path, g) or fnmatch.fnmatch(name, g.rsplit("/", 1)[-1])
	for g in TEST_GLOBS):
	hits.append(path)
	return hits


	# ---------------------------------------------------------------------------
	# 출력
	# ---------------------------------------------------------------------------

	def allow() -> None:
	sys.exit(0)


	def deny(reason: str) -> None:
	print(json.dumps({
	"hookSpecificOutput": {
	"hookEventName": "PreToolUse",
	"permissionDecision": "deny",
	"permissionDecisionReason": reason,
	}
	}, ensure_ascii=False))
	sys.exit(0)


	def build_reason(files: list[str]) -> str:
	listed = "\n".join(f" - {f}" for f in files)
	return f"""이 커밋에 테스트 파일이 있는데 mutation 검증 기록이 없어요.

	{listed}

	테스트의 단언이나 케이스를 바꿨다면, 커밋 전에 mutation을 심어 false green을
	걸러야 합니다. `{SKILL_NAME}` 스킬을 읽고 수행한 뒤, 커밋 메시지 끝에 아래 trailer를
	한 줄 추가하고 다시 커밋하세요.

	{TRAILER_KEY} killed <N> / survived <M>(<분류>) by {SKILL_NAME}

	단언·케이스를 안 건드린 순수 리팩터(이름·서식·이동)라면 검증할 새 보장이 없으니
	skip으로 남기세요.

	{TRAILER_KEY} skip(no assertion change) by {SKILL_NAME}

	이 게이트는 검증을 증명하지 못합니다. 서명만 먼저 쓰고 검증을 건너뛸 수도 있지만,
	그러면 남는 건 아무것도 지키지 않는 초록불뿐입니다.

	의식적으로 건너뛰려면 명령 앞에 'ALLOW_NO_MUTATION=1 ' 를 붙이세요."""


	# ---------------------------------------------------------------------------

	def main() -> None:
	try:
	event = json.load(sys.stdin)
	except Exception:
	allow()

	cmd = (event.get("tool_input") or {}).get("command") or ""
	if not cmd:
	allow()

	verdict = classify_command(cmd)
	if verdict in ("skip", "external"):
	allow()

	files = staged_test_files()
	if not files:
	allow()

	if TRAILER_KEY in cmd:
	allow()

	deny(build_reason(files))


	if __name__ == "__main__":
	try:
	main()
	except Exception:
	# 훅의 버그가 커밋을 막는 일은 없어야 한다.
	sys.exit(0)
name	mutation-verify
author	bumgeun-song
license	MIT
description	테스트가 실제로 버그를 막는지 mutation(원본 코드를 일부러 망가뜨리는 변형)을 심어 검증하고, 결과를 커밋 메시지 trailer로 남긴다. 테스트의 단언이나 케이스를 새로 쓰거나 고쳤을 때, 커밋 게이트가 Mutation-Verified 기록을 요구했을 때, "이 테스트 믿어도 되나" "테스트가 제대로 검증하는지 봐줘" "false green 아닌지 확인해줘" 같은 요청이 있을 때 반드시 사용할 것. 커버리지를 올려달라거나 커버리지로 테스트 품질을 확인해달라는 요청도 이 스킬로 처리한다 — 커버리지는 코드가 실행됐다는 것만 말할 뿐 버그 방어력을 재지 않기 때문. 테스트를 새로 작성한 직후라면 요청이 없어도 이 검증을 먼저 제안한다 .
조건	어기면 생기는 일
1. 실제 버그를 일으킨다	프로덕션에 나가도 아무도 안 다치는 변형. 죽든 살든 알 게 없음
2. 이번 픽스처에서 도달한다	심은 자리가 실행조차 안 됨. 살아남아도 테스트 탓이 아님
3. 관찰 표면에서 결과가 바뀐다	코드는 망가졌는데 그 레벨에서 안 보임. 테스트가 볼 방법이 없음
4. 앞 후보와 실패면이 다르다	같은 단언을 반복해서 때림. 두 번째부터는 새 정보 없음
5. 컴파일된다	실험이 성립하지 않음. 타입 에러는 버그가 아니라 컴파일러의 일
✅ 좋은 후보 (실제 버그로 연결)	❌ 효과 낮은 후보
정책 조건 제거·반전	단순 문구 변경
API 응답 필드 오해	타입·빌드 에러만 내는 변경
선택한 상태 대신 다른 상태 참조	현실적이지 않은 무작위 코드 삭제
안내 UI는 뜨지만 진행도 함께 발생	사용자가 못 보는 내부 리팩터링 차이
feature flag off인데 진입이 열림	현재 테스트 책임 밖 정책의 억지 검증
추가 비용이 있는데 확인 단계 건너뜀	이미 같은 실패면을 검증한 변형의 반복
재고가 있는데 옵션 필터에서 누락
실패 응답을 성공처럼 처리
경계값 이동 (`>` ↔ `>=`)
alias 정규화 그룹에서 멤버 누락