vhk: Skill for Claude Code

VHK Autopilot (1단계 MVP)

VHK로 개발 중인 프로젝트에서 active goal 카드 1개를 사람 개입 없이 한 바퀴 돌리고, 끝나면 멈춰서 핵심만 보고한다. 위험한 건 하지 않는다 — 외부 발송·이슈 등록·코드 집행은 2단계 vhk auto 명령 영역이다.

🔒 불변조건 (절대 어기지 마라)

• INV-1 진행 허가 = vhk verify green(결정론)에만. 적대리뷰(LLM)는 "중단 트리거"로만 — "진행해도 된다"는 긍정 판정 금지.
• INV-2 외부 발송 0. gh issue create 호출 금지. 문제는 채팅 보고 + 이슈 초안 텍스트까지만.
• INV-3 집행 코드 0. dedupe·rate-limit·이슈 jsonl 영속 금지. (dev log append 는 허용·필수 — INV-5)
• INV-4 자동 합·불 입력 = vhk verify 의 .vhk/reports/latest.json + 각 명령 exit code 만. vhk review·vhk mission check 는 exit code 만 신뢰하고 stdout 텍스트는 파싱하지 말 것 (텍스트는 적대 판단의 신호로만 읽는다).
• INV-5 commit 전 docs/devlog/<오늘날짜>-autopilot.md 에 1줄 append 필수. 안 하면 check-records 훅(exit 2)이 막는다. src 실코드 커밋에 [skip-record] 우회 금지. 이 경로는 비추적이라 git add 하지 않는다(공개 경계 — ADR-008·ADR-010).
• INV-6 critical 결함 발견 또는 vhk verify 연속 2회 red 시 .vhk/HARD_STOP 파일 생성하고 종료. 매 시작(0번)에 .vhk/HARD_STOP 존재를 먼저 확인한다.
• INV-7 commit 만 자동. push·PR·머지·publish 는 절대 자동 금지.
• INV-8 적대리뷰는 현재 호스트에 맞는 독립 리뷰 어댑터를 정확히 1개 사용한다. 리뷰 어댑터를 읽고, 지원되는 어댑터가 없거나 실행·인증·판정에 실패하면 합격으로 간주하지 말고 중단 사유를 보고한다.
• INV-9 루프 시작 시 vhk autonomy-log --event start로 runId를 발급받아 루프 내내 유지하고, 종결 분기에서 결과에 맞는 이벤트로 반드시 종결 기록한다(이슈 #373 자율성완주율 계측 — 시작만 있고 종결이 없으면 완주율 분모/분자가 둘 다 부정확해진다).
• INV-10 합격 종결 전에 vhk receipt 를 반드시 실행한다. 완주 판정은 같은 커밋 SHA 의 receipt 를 요구하는데(isVerifiedComplete), vhk verify 는 그 원장을 쓰지 않는다. 빠지면 런이 기록돼도 verified=false 로 떨어져 관찰 게이트의 유효 실행에 들어가지 않고, 자기 보고 격차로 잡혀 권한 승급까지 영구 차단된다. 커밋 직후에 불러야 SHA 가 일치한다.
• INV-11 자동 commit은 다른 writer가 없는 격리된 작업 브랜치에서만 한다. 병렬 에이전트·사람 편집 세션이 같은 worktree를 쓸 수 있으면 시작하지 말고 각자 별도 worktree를 사용한다. 시작 전에 git -c core.quotepath=false status --porcelain=v1 -z --untracked-files=all의 출력이 비어 있어야 하고 git branch --show-current가 비어 있거나 main·master이면 시작하지 않는다. 기존 변경을 stage·stash·reset·삭제해 기준선을 만들지 않는다. commit 직전 다시 상태를 읽어 현재 브랜치와 Goal 범위를 다시 확인하며, 보호 브랜치이거나 범위 밖 경로가 하나라도 있으면 vhk save를 호출하지 않고 blocked로 끝낸다. vhk verify도 증거 원장을 경로 한정 commit할 수 있으므로 매 verify 직전에 같은 브랜치 검사를 한다. 이 검사를 생략할 수 없다.