N5는 명령 안 어디에 있든 `verify.sh <단계>`를 실행으로 셌다. 그래서
`echo scripts/verify.sh pr`, `bash -n scripts/verify.sh pr`도 desktop
실행이 됐다. here-document는 명령 안 아무 낱말이나 bash·sh·zsh면
스크립트로 읽었고(`grep -c bash <<EOF`), `<<\EOF`·`<<'END NOTE'`
구분자는 못 알아 본문을 명령으로 읽었다. `ssh … gradlew`는 옛 검사
그대로 명령 글 전체에서 낱말을 찾아, 커밋 메시지 본문이나 주석의
`ssh desktop ./gradlew`도 셌다. registry에 없는 leaf 대상, 미추적
파일로 보내기를 거절한 실행(rc 5)처럼 Gradle 전에 멈춘 verify.sh도
셌다.
N6는 HEAD와 비교해서, 이 브랜치에서 새로 쓰고 커밋한 기록을 다듬을
때도 「본문을 되돌린다」를 알렸다. 아직 main에 들어가지 않은 글이라
그 알림은 정당한 수정을 되돌리게 만든다.
고친 방법:
- N5: 단순 명령마다 실제로 실행되는 낱말 하나만 본다. 대입과 감싸개
(timeout·flock·env·nohup 등, 값 받는 옵션과 앞 인자 수를 표로 둠)
뒤의 낱말, 셸에 준 스크립트 파일이다. 셸은 옵션을 읽어 -c 스크립트,
stdin 스크립트(-s 또는 인자 없음), 스크립트 파일, -n(실행 안 함)을
가른다. ssh 원격 명령은 ssh가 보내는 대로 리다이렉션을 뺀 낱말을
이어 desktop에서 다시 읽는다. gradlew도 같은 길로 desktop 안에서
돌 때만 센다. leaf 대상은 registry gradle_path와 대조하고, 출력에
verify.sh의 거절 문구가 있으면 그 명령의 verify.sh는 세지 않는다.
스크립트 안의 스크립트는 MAX_NESTING단까지만 읽는다(깊은 ssh 중첩이
RecursionError로 훅을 죽이지 않게).
- here-document 구분자 정규식이 `\WORD`와 따옴표 안 공백을 받는다.
- N6: 기준 커밋을 verify.sh와 같은
`git merge-base HEAD "${VERIFY_BASE_REF:-origin/main}"`로 하고, 그
ref가 없으면 HEAD로 돌아간다. 알림 문구는 기준 커밋 이름을 적는다.
버린 대안:
- README의 N5 문구를 verify.sh 경로로 좁히고 옛 gradlew 검사를 둔다
— 같은 오판이 gradlew 쪽에 남는다.
- 실패한 Bash는 PostToolUse가 안 돈다고 보고 rc 5를 두지 않는다 —
`| tail`·`; echo rc=$?`로 끝나면 rc가 0이라 돈다.
위험·한계: 여전히 넛지다. 원격 준비 실패(rc 4)는 출력으로 가리지
못해 센다. flock의 `-c` 꼴, 감싸개 표에 없는 감싸개는 실행으로 보지
않아 알림이 한 번 더 나올 수 있다. 「실행 중」 계획서 체크 상자 수정은
기록 규칙상 본문 수정이라 N6가 계속 알린다(이 브랜치에서 새로 쓴
계획서는 이제 조용하다).
검증(노트북, Python·문서만):
- python3 -m unittest discover -s scripts/tests -p test_hooks.py:
61개 rc=0(1 skip = 실제 포매터 jar).
- RED: 9c0a7cb3d의 hooks.py에 새 상수 셋만 얹고 새 시험을 돌리면
rc=1, failures=20.
- 변이: 이 커밋이 더하거나 건드린 조건 41개를 하나씩 끈 사본에서
모두 rc=1(생존 0).
- python3 scripts/check-docs.py, scripts/check-work-docs.py rc=0.
문제: 기록 문서(설계서·계획서·증거·학습 문서·ADR) 본문은 쓴 때의
원문이고 머리 블록만 고친다는 규칙(docs/README.md 「문서 수명과
언어」, .claude/rules/docs.md)과 docs/vision.md는 소유자만 쓴다는
규칙이 문서에만 있다. 훅도 게이트도 보지 않아, 세션이 기록 본문을
고쳐도 아무도 알리지 않는다(6a792b814가 기록 30개의 본문 경로를
고친 일이 있다).
고른 방법: post-edit에서 .md 편집마다 본다. docs/vision.md면
「소유자만 쓴다, 되돌리고 제안만 한다」 한 줄.
scripts/check-docs.py의 RECORD_KINDS 폴더 문서면 `git show
HEAD:./<경로>`의 옛 글과 머리 블록 끝 뒤 본문을 비교한다. 설계서·
history 기록은 같아야 하고, DECISION_PREFIXES(ADR)는 옛 본문이 새
본문의 앞부분이면 된다(끝에 보완 절). 끝의 빈 줄은 세지 않는다. 어기면
「기록 본문 알림(N6) <경로>: … n곳 다르다 …」와 바뀐 줄을 최대 5줄로
알린다(exit 0). HEAD에 없는 새 기록은 조용하다. N6에는 뒤에 게이트가
없으니 첫 줄은 늘 맨 앞에 두고, N2 실패 줄이 함께 있으면 N6는 첫 줄만
내 N2 줄이 잘리지 않게 한다. 상수(RECORD_KINDS·DECISION_PREFIXES·
HEAD_START·HEAD_END·HEAD_SEARCH_LINES)는 check-docs.py 소스에서
ast.literal_eval로 읽어 복사본을 두지 않는다. 하나라도 없거나 값이
리터럴이 아니면 N6는 조용하다(편집을 실패시키지 않는다). 시험이 진짜
check-docs.py의 record_kind·strip_head_block과 훅 판정이 같은지 본다.
README 표에 N6 줄과 한계, 루트 CLAUDE.md 훅 목록에 「기록 본문 알림」.
버린 대안: (1) check-docs.py를 import해 함수를 그대로 쓴다 — 편집마다
그 스크립트의 최상위 코드를 실행한다. N2 시험의 가짜 스크립트처럼
최상위에서 sys.exit하면 훅이 죽는다. (2) 상수를 hooks.py에 복사한다 —
두 벌이 갈라진다. (3) docs/reviews/도 본다 — 리뷰 기록 규칙이 문서끼리
맞지 않아 따로 정할 일이라 넣지 않았다(check-docs.py도 머리 블록을 아직
요구하지 않는다). (4) N2를 앞에 둔다 — N2 줄이 다섯이면 게이트가 없는
N6가 통째로 잘린다.
위험·한계: 편집 도구(Edit·Write·MultiEdit)만 본다. Bash 일괄 치환
(sed -i 등)이나 이미 커밋한 본문 변경은 잡지 못한다. 비교 기준이
HEAD라서, 이 브랜치에서 새로 쓰고 커밋한 기록을 다시 다듬을 때도
알린다. check-docs.py가 상수 이름을 바꾸면 N6는 조용해진다 — 그때 시험
test_the_record_rules_are_the_document_checkers가 실패한다.
check-docs.py와 settings.json은 고치지 않았다.
검증: python3 -m unittest discover -s scripts/tests -p test_hooks.py
rc=0(52개, 1 skip). 변이 18개(비교 끄기·ADR을 설계서처럼·설계서를
ADR처럼·머리 블록 안 떼기·시작 줄 확인 끄기·탐색 범위 끄기·vision
끄기·새 기록도 비교·reviews 넣기·post-edit 연결 끊기·N2 옆 첫 줄만
끄기·ADR 끝 덧붙임을 알림에 넣기·5줄 상한 끄기·없는 check-docs.py에서
죽기·리터럴 아닌 값에서 죽기·상수 일부만 받기·끝 빈 줄 세기·빈 줄
대신 첫 글자 줄 보이기 끄기)가 모두 시험 하나 이상을 실패시킨다. N5
변이 31개도 그대로 잡힌다. 실제 저장소에서 post-edit: docs/vision.md는
알림 한 줄, 고치지 않은 설계서·ADR은 출력 없음(rc=0).
python3 scripts/check-work-docs.py rc=0, python3 scripts/check-docs.py
rc=0.
문제: 턴 끝 알림 N5는 `ssh <desktop> … gradlew …` 모양만 desktop
실행으로 본다. AGENTS.md 「검증」이 정식 진입점이라 한
`scripts/verify.sh leaf <gradle-path>`·`scripts/verify.sh pr`(기본
호스트가 desktop)로 검증해도, `ssh desktop '… scripts/verify.sh app
--on here'`로 돌려도 턴 끝이 한 번 막힌다. 알림 문구도 정식 진입점이
아니라 `<gradle-path>:check`를 가리킨다.
고른 방법: Bash 명령에서 주석·줄 잇기·here-document 본문을 먼저 떼고,
shlex로 낱말과 제어 연산자(`;`·`&&`·`||`·`|`·`&`·괄호·줄바꿈)로
나눈다. `verify.sh`로 끝나는 낱말 다음이 Gradle 단계(verify.sh
run_here와 같은 leaf·pr·main·nightly·release·app·round)이면 인자를
verify.sh main과 같이 읽는다: leaf 대상, `--on`·`--log` 값, 플래그
둘, 리다이렉션. 그 밖의 인자가 있으면 verify.sh가 사용법 오류로 멈추니
세지 않는다. 호스트는 마지막 `--on`, 없으면 그 명령 앞의
`VERIFY_HOST=` 대입 → 앞선 `export VERIFY_HOST=` → (노트북만) 환경
값 → desktop이고, 빈 값은 기본값이다. `--on here`는
`ssh <desktop 호스트>` 안(원격 명령 낱말, 따옴표 원격 명령, 그 ssh가
읽는 here-document)에서만 desktop이다. `<셸> -c '…'`과 셸이 읽는
here-document는 그 셸이 도는 곳에서 읽고, 그 밖의 here-document
본문(`cat > 파일 <<EOF`, `git commit -F - <<EOF`)은 글로 본다.
`docs`는 세지 않는다. 알림 문구와 README N5 줄·흐름 그림·한계 줄을
`scripts/verify.sh leaf <gradle-path>`에 맞춘다. 기존 gradlew 판정은
그대로 두고 새 판정을 뒤에 붙였다. 새 눈 리뷰가 줄바꿈·here-document
경계(노트북 명령과 글을 desktop 실행으로 세던 것), 대입 범위·빈 값·
사용법 오류 인자를 짚어 같은 커밋에서 고쳤다.
버린 대안: (1) 명령에 `verify.sh`가 있으면 무조건 desktop으로 본다 —
`docs`·노트북 `--on here`까지 지워 알림이 사라진다. (2) verify.sh에서
단계·옵션 목록을 실행 중에 읽는다 — bash case 줄을 매번 파싱하는 것은
깨지기 쉽다. 대신 시험이 verify.sh run_here 단계 목록, main 옵션
목록과 훅 상수가 같은지 본다.
위험·한계: 셸 문법을 다 해석하지는 않는다(`$'…'` 따옴표, 중첩
명령 치환 안의 here-document 등). 잘못 세도 알림 하나가 빠지거나 더
나올 뿐, 게이트는 그대로다. `run_in_background` 실행은 시작할 때
센다(기존 gradlew 판정과 같다). 노트북 감싸개 `laptop-gate`의
`./gradlew`는 여전히 세지 않는다.
검증: python3 -m unittest discover -s scripts/tests -p test_hooks.py
rc=0(37개, 1 skip은 실제 포매터 jar 시험). 기준 b2bfb9bbf의
hooks.py에 새 시험을 얹으면 rc=1(failures=20, errors=2: desktop 실행
모양이 모두 막히고 새 상수가 없다). 변이 31개(verify 분기·`--on`
무시·첫 `--on`·docs·ssh 범위·따옴표 원격·here-document 스크립트·
본문을 명령으로 읽기·줄바꿈 경계·here 판정·호스트 판정·환경 무시·원격에
환경 쓰기·자기 대입 무시·대입 범위·export·빈 값·사용법 오류 인자·대상
없는 leaf·리다이렉션·주석·줄 잇기·닫히지 않은 따옴표·`-c` 스크립트·
셸 here-document·인자 범위·ssh 호스트 확인·단계 범위·ssh 호스트
범위·ssh 옵션·문구)가 모두 시험 하나 이상을 실패시킨다.
python3 scripts/check-work-docs.py rc=0, python3 scripts/check-docs.py
rc=0.