fix(hooks): N5가 verify.sh를 desktop 실행으로 보고 기록 본문 알림 N6를 더한다 #84

Merged
donghyeon.kang merged 4 commits from fix/hooks-n5-verify-sh-n6-records into main 2026-11-21 17:29:11 +00:00
Owner

무엇을, 왜

편집 훅 두 가지를 고친다.

  • N5(턴 끝 알림) 거짓 막힘. 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를 가리켰다. 이제 verify.sh의 Gradle 단계를 desktop에서 돌린 것을 desktop 실행으로 보고, 문구는 scripts/verify.sh leaf <gradle-path>를 가리킨다.
  • N6(새 알림) 기록 본문·vision. 「기록 본문은 쓴 때의 원문, 머리 블록만 고친다」(docs/README.md 「문서 수명과 언어」)와 「docs/vision.md는 소유자만 쓴다」가 문서에만 있고 훅·게이트가 없었다. post-edit에서 둘을 알린다(exit 0, 막지 않는다).

고른 방법과 버린 대안

N5. Bash 명령에서 주석·줄 잇기·here-document 본문을 먼저 떼고, shlex로 낱말과 제어 연산자(;·&&·||·|·&·괄호·줄바꿈)로 나눈다. 단순 명령마다 실제로 실행되는 낱말 하나만 본다: 리다이렉션을 뺀 낱말에서 대입과 감싸개(timeout·flock·env·nohup 등, 값 받는 옵션과 앞 인자 수를 표로 둔다) 뒤의 낱말, 또는 셸에 준 스크립트 파일. 그 낱말이 verify.sh이고 다음이 run_here의 Gradle 단계(leaf·pr·main·nightly·release·app·round)면 인자를 verify.sh main과 같이 읽는다(leaf 대상, --on·--log 값, 플래그 둘, 리다이렉션). 그 밖의 인자가 있거나 leaf 대상이 registry gradle_path가 아니면 Gradle 전에 멈추니 세지 않는다. 출력에 verify.sh의 「미추적 파일이 있어 보내지 않는다」(rc 5)가 있으면 그 명령의 verify.sh도 세지 않는다. 그 낱말이 gradlew면 desktop 안에서 돌 때만 센다. 호스트는 마지막 --on → 그 명령 앞 VERIFY_HOST= → 앞선 export → (노트북만) 환경 값 → desktop, 빈 값은 기본값. --on here는 ssh <desktop 호스트> 안에서만 desktop. ssh 원격 명령은 ssh가 보내는 대로 리다이렉션을 뺀 낱말을 이어 desktop에서 다시 읽고, 그 ssh가 읽는 here-document·<<< 문자열도 desktop 스크립트다. 셸은 옵션으로 -c 스크립트, stdin 스크립트(-s 또는 인자 없음), 스크립트 파일, -n(실행 안 함)을 가르고, 스크립트는 그 셸이 도는 곳에서 읽는다. 그 밖의 here-document 본문(cat > 파일 <<EOF, git commit -F - <<EOF, bash 파일 <<EOF)은 글로 본다. docs는 세지 않는다. 스크립트 안의 스크립트는 MAX_NESTING단까지만 읽는다(깊은 ssh 중첩이 RecursionError로 훅을 죽이지 않게).

  • 버림: 명령에 verify.sh가 있으면 무조건 desktop — docs·노트북 --on here까지 알림을 지운다.
  • 버림: 옛 ssh + 명령 글 안 gradlew 판정을 그대로 두고 README만 verify.sh로 좁힌다 — 커밋 메시지 본문이나 주석의 ssh desktop ./gradlew를 계속 실행으로 센다.
  • 버림: 실패한 Bash는 PostToolUse가 안 돈다고 보고 rc 5를 두지 않는다 — | tail·; echo rc=$?로 끝나면 rc가 0이라 돈다.
  • 버림: 실행 중에 verify.sh의 case 줄을 파싱 — 깨지기 쉽다. 대신 시험이 훅 상수와 verify.sh run_here 단계 목록·main 옵션 목록이 같은지 본다.

N6. .md 편집마다 N2보다 먼저 본다. docs/vision.md면 「소유자만 쓴다(docs/vision.md:3-4). 되돌리고 제안만 한다」 한 줄. scripts/check-docs.py의 RECORD_KINDS 폴더 문서면 기준 커밋의 옛 글과 머리 블록 끝 뒤 본문을 비교한다. 기준 커밋은 verify.sh와 같은 git merge-base HEAD "${VERIFY_BASE_REF:-origin/main}"이고, 그 ref가 없으면 HEAD다. 설계서·history 기록은 같아야 하고, 결정 기록(DECISION_PREFIXES)은 옛 본문이 새 본문의 앞부분이면 된다. 기준 커밋에 없는 기록(이 브랜치에서 새로 쓴 기록, 커밋했어도)과 docs/reviews/는 보지 않는다. 출력은 「기록 본문 알림(N6) <경로>: … 기준 커밋(merge-base origin/main)과 n곳 다르다 …」와 바뀐 줄, 최대 5줄. N6에는 뒤에 게이트가 없으니 첫 줄은 늘 앞에 두고, N2 실패 줄이 함께 있으면 N6는 첫 줄만 낸다(N2 줄이 잘리지 않게).

  • 상수 5개는 check-docs.py 소스에서 ast.literal_eval로 읽는다(복사본 없음, 그 파일을 실행하지 않음). 시험이 진짜 check-docs.py의 record_kind·strip_head_block과 훅 판정을 대조한다.
  • 버림: check-docs.py를 import해 함수를 쓴다 — 편집마다 그 스크립트의 최상위 코드가 돈다. N2 시험의 가짜 스크립트처럼 최상위에서 sys.exit하면 훅이 죽었다(실제로 겪음).
  • 버림: 상수를 hooks.py에 복사 — 두 벌이 갈라진다.
  • 버림: docs/reviews/도 본다 — 리뷰 기록 규칙이 문서끼리 맞지 않아 따로 정할 일이다.
  • 버림: HEAD와 비교 — 이 브랜치에서 새로 쓰고 커밋한 기록(아직 main에 없는 글)을 다듬을 때도 「본문을 되돌린다」가 나와 정당한 수정을 되돌리게 만든다.
  • 버림: N2를 앞에 둔다 — N2 줄이 다섯이면 게이트가 없는 N6가 통째로 잘린다.

위험과 영향

  • 둘 다 넛지다. N5는 턴을 한 번 막는 기존 동작 그대로, N6는 exit 0 알림만 더한다. 게이트·settings.json·check-docs.py·verify.sh는 바뀌지 않는다.
  • N5는 셸 문법을 다 해석하지는 않는다($'…' 따옴표, 명령 치환 안의 here-document, flock 파일 -c '…' 꼴, 감싸개 표에 없는 감싸개 등). 잘못 세도 알림 하나가 빠지거나 더 나올 뿐이다. 원격 준비 실패(verify.sh rc 4)는 출력으로 가리지 못해 센다. run_in_background 실행은 시작할 때 센다(기존 gradlew 판정과 같다).
  • N6는 편집 도구(Edit·Write·MultiEdit)만 본다. Bash 일괄 치환은 못 잡는다. 그렇게 바꿔 커밋한 본문은 그 파일을 다음에 편집할 때 알린다(README에 적음). 「실행 중」 계획서의 체크 상자 수정도 기록 규칙(docs/README.md 「문서 수명과 언어」)상 본문 수정이라 알린다. 이 브랜치에서 새로 쓴 계획서는 조용하다. check-docs.py가 상수 이름을 바꾸면 N6는 조용해지는데, 그때 test_the_record_rules_are_the_document_checkers가 실패해 PR 단계 testDocumentChecks에서 걸린다.
  • 노트북 감싸개 laptop-gate의 ./gradlew는 여전히 N5가 세지 않는다(소유자 판단으로 넘김).

검증

모두 노트북(Python·문서만 바뀜, Gradle 없음).

  • python3 -m unittest discover -s scripts/tests -p test_hooks.py: 커밋 8b86f0127 37개 rc=0, 커밋 9c0a7cb3d 52개 rc=0, 커밋 a86e00d6e 61개 rc=0(1 skip = 실제 포매터 jar 시험).
  • RED(리뷰 반영 a86e00d6e): 9c0a7cb3d의 hooks.py에 새 상수 셋만 얹고 새 시험을 돌리면 rc=1(failures=20). echo scripts/verify.sh pr, bash -n …, grep -c bash <<EOF, <<\EOF·<<'END NOTE', 커밋 메시지 본문의 ssh desktop ./gradlew, registry에 없는 leaf, 거절 문구가 있는 실행을 모두 desktop 실행으로 셌고, 이 브랜치에서 커밋한 계획서 편집에 N6가 알렸다.
  • RED(N5): 기준 b2bfb9bbf의 hooks.py에 새 시험을 얹으면 rc=1(failures=20, errors=2). scripts/verify.sh leaf :domain-core, ssh desktop 'cd ~/wt && scripts/verify.sh app --on here' 등 desktop 실행 모양이 모두 턴을 막았다.
  • N5 통과(턴 안 막힘): scripts/verify.sh leaf :domain-core, ssh desktop 'cd ~/wt && scripts/verify.sh app --on here' 외 19모양. 막힘(decision: block): scripts/verify.sh docs, 노트북 scripts/verify.sh pr --on here 외 20모양, 글로 쓴 here-document 3모양. 기존 ssh … ./gradlew 시험 그대로 통과.
  • N6 조용(rc 0, 출력 없음): 머리 블록 칸만 바꿈, ADR 끝 보완 절, 커밋 안 된 새 기록, docs/reviews/ 편집, 끝 빈 줄, check-docs.py 없음·상수 빠짐·리터럴 아님. 알림(rc 0, N6): 설계서 본문 한 줄, 설계서 끝 덧붙임, ADR 본문 중간, docs/vision.md, 바뀐 곳 여럿(5줄 안), N2 실패 줄과 함께(첫 줄만).
  • 변이: N5 31개, N6 18개를 하나씩 넣은 사본에서 모두 rc=1(살아남은 것 0). 리뷰 반영 커밋 a86e00d6e는 더하거나 건드린 조건 41개(구분자 정규식, 따옴표·주석·<<-, 실행 낱말·감싸개·리다이렉션, ssh·셸 판정, gradlew, 거절 문구, registry, 중첩 한도, merge-base)를 하나씩 끈 사본에서 모두 rc=1(생존 0).
  • scripts/verify.sh docs(커밋마다 깨끗한 detached worktree): 8b86f0127 rc=0(scripts/tests 226개), 9c0a7cb3d rc=0(241개), a86e00d6e rc=0(250개).
  • Gradle 입력: build.gradle testDocumentChecks(Exec, prCheck)가 같은 python3 -m unittest discover -s scripts/tests를 돌린다. 선언 입력이 없는 Exec라 캐시로 옛 결과가 나오지 않는다. src/bootstrap/app/build.gradle·src/*.java는 scripts/hooks·루트 CLAUDE.md를 읽지 않는다. desktop verify.sh pr는 돌리지 않았고, PR run pr / done이 prCheck를 돈다.
  • 새 눈 리뷰 1회(reviewer, 렌즈 be-build-ci·be-testing): Medium 1(줄바꿈·here-document 경계로 노트북 명령·글을 desktop 실행으로 셈), Low 3(변이 생존 6, verify.sh 인자 처리와 다른 곳 3, N6가 N2 줄을 가림) — 모두 이 PR 커밋에서 고침.

리뷰 반영

  • 확인 리뷰 1회(reviewer, 렌즈 be-build-ci·be-testing): Medium 0, Low 6(구분자 \EOF·공백, 셸 판정이 아무 낱말, 옛 gradlew 판정, 변이 생존 3, Gradle 전에 멈춘 verify.sh, 명령 위치 아닌 verify.sh)과 질문 둘(N6 기준 → merge-base 권고, 「실행 중」 계획서 체크 상자 → 본문 수정이라 알림이 맞음) — a86e00d6e에서 Low 6과 merge-base를 고쳤고, 체크 상자는 바꾸지 않았다. 깊은 ssh 중첩의 RecursionError는 반영 중 직접 찾아 같은 커밋에서 고쳤다.

리뷰어가 볼 곳

  • scripts/hooks/hooks.py ran_desktop_gradle·command_words·command_word·shell_input·runs_gradle·verify_target·post_bash(N5), record_rules·base_commit·record_body·record_findings(N6), post_edit의 호출 순서.
  • scripts/tests/test_hooks.py TurnEndNudgeTest(새 시험 11개), RecordBodyNudgeTest(새 묶음).
  • scripts/hooks/README.md 흐름 그림·표 N5·N6 줄·한계 줄, 루트 CLAUDE.md 5행.

관련

  • 훅 원칙: scripts/hooks/README.md 1절(되돌릴 수 없는 것만 막는다)·3절(변이 시험).
  • 기록 규칙: docs/README.md 「문서 수명과 언어」, .claude/rules/docs.md, docs/vision.md 머리.
## 무엇을, 왜 편집 훅 두 가지를 고친다. - **N5(턴 끝 알림) 거짓 막힘.** 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`를 가리켰다. 이제 `verify.sh`의 Gradle 단계를 desktop에서 돌린 것을 desktop 실행으로 보고, 문구는 `scripts/verify.sh leaf <gradle-path>`를 가리킨다. - **N6(새 알림) 기록 본문·vision.** 「기록 본문은 쓴 때의 원문, 머리 블록만 고친다」(`docs/README.md` 「문서 수명과 언어」)와 「`docs/vision.md`는 소유자만 쓴다」가 문서에만 있고 훅·게이트가 없었다. post-edit에서 둘을 알린다(exit 0, 막지 않는다). ## 고른 방법과 버린 대안 **N5.** Bash 명령에서 주석·줄 잇기·here-document 본문을 먼저 떼고, shlex로 낱말과 제어 연산자(`;`·`&&`·`||`·`|`·`&`·괄호·줄바꿈)로 나눈다. 단순 명령마다 실제로 실행되는 낱말 하나만 본다: 리다이렉션을 뺀 낱말에서 대입과 감싸개(`timeout`·`flock`·`env`·`nohup` 등, 값 받는 옵션과 앞 인자 수를 표로 둔다) 뒤의 낱말, 또는 셸에 준 스크립트 파일. 그 낱말이 `verify.sh`이고 다음이 run_here의 Gradle 단계(`leaf`·`pr`·`main`·`nightly`·`release`·`app`·`round`)면 인자를 verify.sh `main`과 같이 읽는다(leaf 대상, `--on`·`--log` 값, 플래그 둘, 리다이렉션). 그 밖의 인자가 있거나 leaf 대상이 registry `gradle_path`가 아니면 Gradle 전에 멈추니 세지 않는다. 출력에 verify.sh의 「미추적 파일이 있어 보내지 않는다」(rc 5)가 있으면 그 명령의 verify.sh도 세지 않는다. 그 낱말이 `gradlew`면 desktop 안에서 돌 때만 센다. 호스트는 마지막 `--on` → 그 명령 앞 `VERIFY_HOST=` → 앞선 `export` → (노트북만) 환경 값 → `desktop`, 빈 값은 기본값. `--on here`는 `ssh <desktop 호스트>` 안에서만 desktop. ssh 원격 명령은 ssh가 보내는 대로 리다이렉션을 뺀 낱말을 이어 desktop에서 다시 읽고, 그 ssh가 읽는 here-document·`<<<` 문자열도 desktop 스크립트다. 셸은 옵션으로 `-c` 스크립트, stdin 스크립트(`-s` 또는 인자 없음), 스크립트 파일, `-n`(실행 안 함)을 가르고, 스크립트는 그 셸이 도는 곳에서 읽는다. 그 밖의 here-document 본문(`cat > 파일 <<EOF`, `git commit -F - <<EOF`, `bash 파일 <<EOF`)은 글로 본다. `docs`는 세지 않는다. 스크립트 안의 스크립트는 `MAX_NESTING`단까지만 읽는다(깊은 ssh 중첩이 RecursionError로 훅을 죽이지 않게). - 버림: 명령에 `verify.sh`가 있으면 무조건 desktop — `docs`·노트북 `--on here`까지 알림을 지운다. - 버림: 옛 `ssh` + 명령 글 안 `gradlew` 판정을 그대로 두고 README만 verify.sh로 좁힌다 — 커밋 메시지 본문이나 주석의 `ssh desktop ./gradlew`를 계속 실행으로 센다. - 버림: 실패한 Bash는 PostToolUse가 안 돈다고 보고 rc 5를 두지 않는다 — `| tail`·`; echo rc=$?`로 끝나면 rc가 0이라 돈다. - 버림: 실행 중에 verify.sh의 case 줄을 파싱 — 깨지기 쉽다. 대신 시험이 훅 상수와 verify.sh run_here 단계 목록·main 옵션 목록이 같은지 본다. **N6.** `.md` 편집마다 N2보다 먼저 본다. `docs/vision.md`면 「소유자만 쓴다(docs/vision.md:3-4). 되돌리고 제안만 한다」 한 줄. `scripts/check-docs.py`의 `RECORD_KINDS` 폴더 문서면 기준 커밋의 옛 글과 머리 블록 끝 뒤 본문을 비교한다. 기준 커밋은 verify.sh와 같은 `git merge-base HEAD "${VERIFY_BASE_REF:-origin/main}"`이고, 그 ref가 없으면 HEAD다. 설계서·history 기록은 같아야 하고, 결정 기록(`DECISION_PREFIXES`)은 옛 본문이 새 본문의 앞부분이면 된다. 기준 커밋에 없는 기록(이 브랜치에서 새로 쓴 기록, 커밋했어도)과 `docs/reviews/`는 보지 않는다. 출력은 「기록 본문 알림(N6) <경로>: … 기준 커밋(merge-base origin/main)과 n곳 다르다 …」와 바뀐 줄, 최대 5줄. N6에는 뒤에 게이트가 없으니 첫 줄은 늘 앞에 두고, N2 실패 줄이 함께 있으면 N6는 첫 줄만 낸다(N2 줄이 잘리지 않게). - 상수 5개는 `check-docs.py` 소스에서 `ast.literal_eval`로 읽는다(복사본 없음, 그 파일을 실행하지 않음). 시험이 진짜 `check-docs.py`의 `record_kind`·`strip_head_block`과 훅 판정을 대조한다. - 버림: `check-docs.py`를 import해 함수를 쓴다 — 편집마다 그 스크립트의 최상위 코드가 돈다. N2 시험의 가짜 스크립트처럼 최상위에서 `sys.exit`하면 훅이 죽었다(실제로 겪음). - 버림: 상수를 `hooks.py`에 복사 — 두 벌이 갈라진다. - 버림: `docs/reviews/`도 본다 — 리뷰 기록 규칙이 문서끼리 맞지 않아 따로 정할 일이다. - 버림: HEAD와 비교 — 이 브랜치에서 새로 쓰고 커밋한 기록(아직 main에 없는 글)을 다듬을 때도 「본문을 되돌린다」가 나와 정당한 수정을 되돌리게 만든다. - 버림: N2를 앞에 둔다 — N2 줄이 다섯이면 게이트가 없는 N6가 통째로 잘린다. ## 위험과 영향 - 둘 다 넛지다. N5는 턴을 한 번 막는 기존 동작 그대로, N6는 exit 0 알림만 더한다. 게이트·`settings.json`·`check-docs.py`·`verify.sh`는 바뀌지 않는다. - N5는 셸 문법을 다 해석하지는 않는다(`$'…'` 따옴표, 명령 치환 안의 here-document, `flock 파일 -c '…'` 꼴, 감싸개 표에 없는 감싸개 등). 잘못 세도 알림 하나가 빠지거나 더 나올 뿐이다. 원격 준비 실패(verify.sh rc 4)는 출력으로 가리지 못해 센다. `run_in_background` 실행은 시작할 때 센다(기존 gradlew 판정과 같다). - N6는 편집 도구(Edit·Write·MultiEdit)만 본다. Bash 일괄 치환은 못 잡는다. 그렇게 바꿔 커밋한 본문은 그 파일을 다음에 편집할 때 알린다(README에 적음). 「실행 중」 계획서의 체크 상자 수정도 기록 규칙(`docs/README.md` 「문서 수명과 언어」)상 본문 수정이라 알린다. 이 브랜치에서 새로 쓴 계획서는 조용하다. `check-docs.py`가 상수 이름을 바꾸면 N6는 조용해지는데, 그때 `test_the_record_rules_are_the_document_checkers`가 실패해 PR 단계 `testDocumentChecks`에서 걸린다. - 노트북 감싸개 `laptop-gate`의 `./gradlew`는 여전히 N5가 세지 않는다(소유자 판단으로 넘김). ## 검증 모두 노트북(Python·문서만 바뀜, Gradle 없음). - `python3 -m unittest discover -s scripts/tests -p test_hooks.py`: 커밋 8b86f0127 37개 rc=0, 커밋 9c0a7cb3d 52개 rc=0, 커밋 a86e00d6e 61개 rc=0(1 skip = 실제 포매터 jar 시험). - RED(리뷰 반영 a86e00d6e): 9c0a7cb3d의 `hooks.py`에 새 상수 셋만 얹고 새 시험을 돌리면 rc=1(failures=20). `echo scripts/verify.sh pr`, `bash -n …`, `grep -c bash <<EOF`, `<<\EOF`·`<<'END NOTE'`, 커밋 메시지 본문의 `ssh desktop ./gradlew`, registry에 없는 leaf, 거절 문구가 있는 실행을 모두 desktop 실행으로 셌고, 이 브랜치에서 커밋한 계획서 편집에 N6가 알렸다. - RED(N5): 기준 b2bfb9bbf의 `hooks.py`에 새 시험을 얹으면 rc=1(failures=20, errors=2). `scripts/verify.sh leaf :domain-core`, `ssh desktop 'cd ~/wt && scripts/verify.sh app --on here'` 등 desktop 실행 모양이 모두 턴을 막았다. - N5 통과(턴 안 막힘): `scripts/verify.sh leaf :domain-core`, `ssh desktop 'cd ~/wt && scripts/verify.sh app --on here'` 외 19모양. 막힘(`decision: block`): `scripts/verify.sh docs`, 노트북 `scripts/verify.sh pr --on here` 외 20모양, 글로 쓴 here-document 3모양. 기존 `ssh … ./gradlew` 시험 그대로 통과. - N6 조용(rc 0, 출력 없음): 머리 블록 칸만 바꿈, ADR 끝 보완 절, 커밋 안 된 새 기록, `docs/reviews/` 편집, 끝 빈 줄, check-docs.py 없음·상수 빠짐·리터럴 아님. 알림(rc 0, `N6`): 설계서 본문 한 줄, 설계서 끝 덧붙임, ADR 본문 중간, `docs/vision.md`, 바뀐 곳 여럿(5줄 안), N2 실패 줄과 함께(첫 줄만). - 변이: N5 31개, N6 18개를 하나씩 넣은 사본에서 모두 rc=1(살아남은 것 0). 리뷰 반영 커밋 a86e00d6e는 더하거나 건드린 조건 41개(구분자 정규식, 따옴표·주석·`<<-`, 실행 낱말·감싸개·리다이렉션, ssh·셸 판정, gradlew, 거절 문구, registry, 중첩 한도, merge-base)를 하나씩 끈 사본에서 모두 rc=1(생존 0). - `scripts/verify.sh docs`(커밋마다 깨끗한 detached worktree): 8b86f0127 rc=0(scripts/tests 226개), 9c0a7cb3d rc=0(241개), a86e00d6e rc=0(250개). - Gradle 입력: `build.gradle` `testDocumentChecks`(Exec, prCheck)가 같은 `python3 -m unittest discover -s scripts/tests`를 돌린다. 선언 입력이 없는 Exec라 캐시로 옛 결과가 나오지 않는다. `src/bootstrap/app/build.gradle`·`src/*.java`는 `scripts/hooks`·루트 `CLAUDE.md`를 읽지 않는다. desktop `verify.sh pr`는 돌리지 않았고, PR run `pr / done`이 prCheck를 돈다. - 새 눈 리뷰 1회(reviewer, 렌즈 be-build-ci·be-testing): Medium 1(줄바꿈·here-document 경계로 노트북 명령·글을 desktop 실행으로 셈), Low 3(변이 생존 6, verify.sh 인자 처리와 다른 곳 3, N6가 N2 줄을 가림) — 모두 이 PR 커밋에서 고침. ## 리뷰 반영 - 확인 리뷰 1회(reviewer, 렌즈 be-build-ci·be-testing): Medium 0, Low 6(구분자 `\EOF`·공백, 셸 판정이 아무 낱말, 옛 gradlew 판정, 변이 생존 3, Gradle 전에 멈춘 verify.sh, 명령 위치 아닌 verify.sh)과 질문 둘(N6 기준 → merge-base 권고, 「실행 중」 계획서 체크 상자 → 본문 수정이라 알림이 맞음) — a86e00d6e에서 Low 6과 merge-base를 고쳤고, 체크 상자는 바꾸지 않았다. 깊은 ssh 중첩의 RecursionError는 반영 중 직접 찾아 같은 커밋에서 고쳤다. ## 리뷰어가 볼 곳 - `scripts/hooks/hooks.py` `ran_desktop_gradle`·`command_words`·`command_word`·`shell_input`·`runs_gradle`·`verify_target`·`post_bash`(N5), `record_rules`·`base_commit`·`record_body`·`record_findings`(N6), `post_edit`의 호출 순서. - `scripts/tests/test_hooks.py` `TurnEndNudgeTest`(새 시험 11개), `RecordBodyNudgeTest`(새 묶음). - `scripts/hooks/README.md` 흐름 그림·표 N5·N6 줄·한계 줄, 루트 `CLAUDE.md` 5행. ## 관련 - 훅 원칙: `scripts/hooks/README.md` 1절(되돌릴 수 없는 것만 막는다)·3절(변이 시험). - 기록 규칙: `docs/README.md` 「문서 수명과 언어」, `.claude/rules/docs.md`, `docs/vision.md` 머리.
donghyeon.kang added 3 commits 2026-11-21 17:20:26 +00:00
문제: 턴 끝 알림 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.
문제: 기록 문서(설계서·계획서·증거·학습 문서·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는 명령 안 어디에 있든 `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.
donghyeon.kang added 1 commit 2026-11-21 17:25:57 +00:00
donghyeon.kang merged commit 0c4c9ed78a into main 2026-11-21 17:29:11 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-backend-template#84