Repository navigation
feat(hooks): enumerate verb gates on first block - #931
Conversation
같은 action verb 에 여러 게이트가 걸리는데 각자 자기 토큰만 보고해, 작성자가 요구사항을 한 번에 하나씩 발견하며 게이트마다 리트라이 턴을 소모했다. #873 은 한 세션에서 그런 차단 6회를 측정했고 그중 최소 4건은 만족 형태가 이미 문서에 있었다. 문서 부재가 아니라 호출 시점 retrieval 이 갭이다. 첫 차단이 그 verb 가 빚진 게이트 전부를 알려주도록 한다. #824 가 `gh pr create` 에 도입한 패턴을 verb 키 레지스트리로 일반화하고, momentum(`gh pr merge`) 과 output-block-falsify-advisory(`AskUserQuestion`) 에 배선했다. 각 토큰은 소유 훅의 소스에서 직접 확인해 적었다 — 게이트가 실제로 받지 않는 토큰을 적으면 권위 있게 읽히므로 체크리스트가 없는 것보다 나쁘다. `pr_body_evidence_checklist()` 는 사본이 아니라 alias 로 남겨 drift 를 막았다. AskUserQuestion 체크리스트는 `Falsified:` 토큰을 들여쓴다. 이 텍스트는 차단할 때마다 트랜스크립트로 나가고 해당 토큰은 컬럼 0 에서만 인식되므로, 들여쓰지 않으면 훅 자신의 출력이 작성자에게 요구하는 술어를 스스로 만족시킨다. Closes #873 Confidence: high Premise-Verified: test_block_message.py 15/15, momentum 88/88, output-block-falsify-advisory 104/104, 전체 scripts/run-tests.sh exit 0. 음성 대조 — momentum impl 되돌리면 신규 케이스가 "missing: pre-merge-approval-gate / gh-merge-worktree-precondition / commit-title-length-check" 로 FAIL, falsify impl 되돌리면 신규 3케이스 전부 FAIL. 체크리스트에 적은 토큰 (PRAXIS_MOMENTUM_MERGE_ADVISORY / # briefing-surfaced / PRAXIS_ASK_END_ADVISORY / pre-merge-approval 의 bypass 부재)은 각 훅 소스·spec 에서 직접 확인. Not-tested: 이슈 작업 3번(fire ledger 로 재차단률 측정)은 배포 후에만 가능하다 — 활성 캐시 플러그인이 7.7.0 이라 이 변경은 릴리스 전까지 실행되지 않는다. Constraint: git commit / gh issue create verb 는 배선할 훅 없이 레지스트리 항목만 추가하면 죽은 코드가 되므로 넣지 않고 docs/hook/INDEX.md 에 미커버로 명시했다. Session-Id: c16298d9-ce90-4536-8b4b-3d63818b411d
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (9)
🚧 Files skipped from review as they are similar to previous changes (9)
📝 WalkthroughWalkthroughAdded shared gate checklists for ChangesVerb gate checklist expansion
Estimated code review effort: 3 (Moderate) | ~25 minutes Sequence Diagram(s)sequenceDiagram
participant AdvisoryHook
participant VerbChecklist
participant Stderr
participant DecisionJSON
AdvisoryHook->>VerbChecklist: Request action-verb checklist
VerbChecklist-->>AdvisoryHook: Return gate checklist
AdvisoryHook->>Stderr: Emit checklist
AdvisoryHook->>DecisionJSON: Emit unchanged advisory decision
Possibly related PRs
Suggested labels: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
"모든 게이트를 열거한다"는 변경이 정작 열거를 빠뜨렸다. AskUserQuestion 은 manifest 기준 PreToolUse 훅이 7개인데 3개만 적었고, gh pr merge 는 항상 걸리는 side-effect-scan 을 빠뜨렸다. 과소 열거한 체크리스트는 이 이슈가 고치려는 결함을 그대로 재현하면서 권위 있게 읽히므로 없는 것보다 나쁘다. 무조건 걸리는 게이트, 조건부 게이트, 절대 차단하지 않는 advisory 를 구분해 적었다 — 구분 없이 나열하면 advisory 를 만족시키려 또 한 턴을 쓴다. PRAXIS_ASK_END_ADVISORY 를 "per call" 로 안내한 것도 고쳤다. 훅은 자기 프로세스 environment 에서 읽으므로 인라인 VAR=1 접두는 도달하지 않는다 — momentum 게이트가 in-band 마커를 따로 만든 이유가 정확히 이것인데 반대로 적었다. AskUserQuestion 체크리스트를 hooks/manifest.json 에 직접 대조하는 테스트를 넣어 훅이 추가될 때 문서가 조용히 뒤처지지 않게 했다. Refs #873 Confidence: high Premise-Verified: jq '.hooks[] | select(matcher contains "AskUserQuestion")' → PreToolUse 7개. grep -rln "pr merge" hooks/*/*/impl.py → merge 경로 게이트 전수 확인(side-effect-scan :144, pipefail-advisory :175, skill-gate-commands :113). grep -n PRAXIS_ASK_END_ADVISORY block-ask-end-option/impl.py → :365 os.environ.get(...). test_block_message.py 17/17, 전체 scripts/run-tests.sh exit 0. Not-tested: gh pr merge 쪽 열거는 manifest 쿼리로 자동 대조할 수 없다 — Bash matcher 라 훅 이름만으로 verb 판정이 안 되고, 현재는 impl 전수 grep 한 시점의 스냅샷이다. AskUserQuestion 쪽과 달리 구조적으로 고정돼 있지 않다. Session-Id: c16298d9-ce90-4536-8b4b-3d63818b411d
|
Codex 리뷰 P2 3건을 P2 — 지적대로 P2 — PreToolUse 7개인데 3개만 적었습니다. 지적하신 2개보다 실제 누락이 많았습니다 — 무조건 / 조건부(strict env) / advisory-only 를 구분해 적었습니다. 구분 없이 나열하면 차단하지도 않는 advisory 를 만족시키려 또 한 턴을 씁니다. P2 — 지적대로입니다. 훅이 자기 프로세스 environment 에서 읽으므로 인라인 드리프트 재발 방지
남은 취약점 (PR 본문에도 명시)
검증 — 검증 제약 관련 — Codex 가 "read-only sandbox 에 writable temp dir 이 없어 pytest 와 shell suite 를 완료하지 못했다"고 밝혔습니다. 테스트는 이쪽에서 실행했습니다. |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/hook/INDEX.md`:
- Around line 21-25: Classify gh-merge-worktree-precondition as conditional in
docs/hook/INDEX.md lines 21-25, indicating it applies only with --delete-branch
or -d while preserving the other gate classifications. Update the five-gate
description in hooks/advisory-nudge/momentum-rule-retrieval-gate/spec.md lines
213-226 so it does not present every listed gate as unconditional.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 3718128b-0303-463f-83c1-932b67f85258
📒 Files selected for processing (9)
docs/hook/INDEX.mdhooks/_lib/block_message.pyhooks/advisory-nudge/momentum-rule-retrieval-gate/impl.pyhooks/advisory-nudge/momentum-rule-retrieval-gate/spec.mdhooks/advisory-nudge/output-block-falsify-advisory/impl.pyhooks/advisory-nudge/output-block-falsify-advisory/spec.mdtests/hooks/advisory-nudge/test_momentum_rule_retrieval_gate.shtests/hooks/advisory-nudge/test_output_block_falsify_advisory.shtests/test_block_message.py
체크리스트가 각 항목 아래에는 "Only when --delete-branch" 라고 적어놓고 묶음 제목은 무조건으로 분류하고 있었다. 같은 블록 안의 자기모순이다. 조건부를 무조건으로 적는 것은 과소 열거의 거울상이다 — 자기 명령에 해당하지도 않는 요구사항을 찾아 헤매게 만들어, 이 이슈가 없애려는 리트라이 비용을 반대 방향으로 만든다. 플래그 무관하게 걸리는 것은 momentum / pre-merge-approval / side-effect-scan 3개뿐이다. gh-merge-worktree-precondition 은 --delete-branch, title-length-check 는 --squash, pipefail-advisory 는 파이프, skill-gate-commands 는 opt-in 이 있어야 발화한다. Refs #873 Confidence: high Premise-Verified: grep -n _DELETE_BRANCH_FLAGS gh-merge-worktree-precondition/ impl.py → :106 frozenset({"-d","--delete-branch"}). grep -n _SQUASH_FLAGS commit-title-length-check/impl.py → :99 frozenset({"-s","--squash"}). sed -n '145p' side-effect-scan/impl.py → return _gh_subcommand_pair(argv) == ("pr","merge") (플래그 무관). test_block_message.py 18/18, 음성 대조 — block_message.py 되돌리면 신규 케이스만 FAIL. 전체 run-tests.sh exit 0. Not-tested: 실제 훅 실행 시점의 발화 여부는 확인하지 않았다 — 분류 근거는 각 훅의 플래그 상수와 매칭 함수를 읽은 것이다. Session-Id: c16298d9-ce90-4536-8b4b-3d63818b411d
codex 재리뷰 2라운드 결과 4건 반영.
- 체크리스트 전달 경로를 decision JSON → stderr 로 변경.
hooks/_lib/_dispatch.py 는 모든 훅의 stderr 를 전달하지만 stdout
decision JSON 은 "첫 deny" 것만 표면화한다. 같은 verb 의 게이트들은
병렬 실행이므로, 형제 게이트가 먼저 deny 하면 permissionDecisionReason
에 실어 보낸 체크리스트는 그대로 버려진다 — 체크리스트가 존재해야 할
다중 게이트 상황이 바로 그 케이스였다. momentum 은 emit_decision 직전
sys.stderr.write, falsify 는 _emit_verb_checklist() 를 _emit_ask /
_emit_t1_ask 양쪽에서 호출한다. format_block 5필드 포맷은 불변.
- gh pr merge 체크리스트에 session-intent 누락분 추가. 이 훅은 문자열
리터럴이 아니라 집합 멤버십("merge" in {...})으로 verb 를 판정해서
기존 grep 열거에 잡히지 않았다.
- block-manufactured-action-menu 를 unconditional → conditional 로 이동.
기본은 advisory 이고 PRAXIS_BLOCK_MANUFACTURED_MENU_STRICT=1 에서만
차단한다.
- spec 2종 + docs/hook/INDEX.md 를 stderr 라우팅 근거와 재분류에 맞춰 동기화.
검증:
- NC1 momentum stderr write 제거 → merge_checklist_rides_stderr_not_decision_json
FAIL (87 passed / 1 failed), 복원 후 88/0
- NC2 _emit_verb_checklist 무력화 → falsify 3건 FAIL (101/3), 복원 후 104/0
- PRAXIS_TESTS_STRICT=1 ./scripts/run-tests.sh → ALL TESTS PASSED
(manifest OK, hook-token 7 invariants OK, ruff clean, shellcheck clean)
Refs #873
Confidence: high
Premise-Verified: dispatch aggregation 계약을 _dispatch.py:184-201 에서 직접 확인
Not-tested: 실제 Claude Code 런타임에서 형제 게이트 동시 deny 시 stderr 표면화는 미실측 (7.8.0 미배포)
Session-Id: c16298d9-ce90-4536-8b4b-3d63818b411d
codex 재리뷰 2라운드 반영 (
|
| 항목 | 결과 |
|---|---|
| NC1 (momentum stderr write 제거) | FAIL [merge_checklist_rides_stderr_not_decision_json] — 87 passed / 1 failed. 복원 후 88/0 |
NC2 (_emit_verb_checklist 무력화) |
falsify 3건 FAIL — 101 passed / 3 failed. 복원 후 104/0 |
tests/test_block_message.py |
19 passed |
PRAXIS_TESTS_STRICT=1 ./scripts/run-tests.sh |
ALL TESTS PASSED (manifest OK, hook-token 7 invariants OK, ruff clean, shellcheck clean) |
새 테스트 2종이 회귀를 고정합니다:
merge_checklist_rides_stderr_not_decision_json 는 게이트 이름이 stderr 에
있고 decision JSON 에는 없음을 양쪽으로 검사하고,
test_ask_checklist_splits_unconditional_from_conditional 는 조건부/무조건
분리를 고정합니다.
미검증
7.8.0 이 아직 배포 전이라, 실제 Claude Code 런타임에서 형제 게이트가 동시에
deny 할 때 stderr 가 모델에 표면화되는지는 실측하지 못했습니다. 근거는
_dispatch.py 의 집계 계약 코드 직접 확인까지입니다.
* fix(hooks): emit verb checklist on both channels #931 이 체크리스트를 decision JSON → stderr 로 옮겼는데, ask 경로에서는 모델에 도달하지 않는다. hooks/_lib/_dispatch.py 의 종료 코드 분기: :201 deny → return 2 :207 ask → return 0 PreToolUse 훅의 stderr 는 exit 2 일 때만 모델에 전달된다. 따라서 형제 게이트가 아무도 deny 하지 않는 일반적인 경우(output-block-falsify-advisory 단독 ask) 체크리스트는 exit-0 stderr 로 나가고 소실된다. #931 이전에는 permissionDecisionReason 안에 있어 표면화됐으므로 회귀다. 수정: 양쪽 채널 동시 emit. - reason 문자열 → 단독 ask(exit 0)에서 도달 - stderr → 형제 게이트 deny 선행(exit 2)에서 도달 deny 는 항상 exit 2 라 momentum 은 stderr 만으로도 충분하지만, 두 훅 처리를 갈라둔 것이 이 결함의 원인이므로 동일하게 맞춘다. 검증: - fix-up probe: dispatcher exit=0 경로에서 reason 에 체크리스트 FOUND, stderr 에도 유지 (수정 전 동일 probe 는 reason MISSING) - NC3 falsify reason 채널 제거 → #932 케이스 3건 FAIL (104/3), 복원 후 107/0 - NC4 momentum reason 채널 제거 → 토큰 5개 missing from decision JSON, FAIL (87/1), 복원 후 88/0 - PRAXIS_TESTS_STRICT=1 ./scripts/run-tests.sh → ALL TESTS PASSED Closes #932 Confidence: high Premise-Verified: _dispatch.py:195-207 종료 코드 분기를 dispatcher 직접 실행으로 실측 Not-tested: exit 2 경로의 stderr 표면화는 코드 근거만 — 7.8.0 미배포로 런타임 실측 없음 Session-Id: c16298d9-ce90-4536-8b4b-3d63818b411d * docs(hooks): avoid line-initial issue refs in prose reviewdog markdownlint MD018 지적 2건 반영. 문장이 `#873` 으로 줄을 시작해 ATX heading 으로 파싱됐다. reviewdog 제안(`# 873`)은 실제 h1 헤딩을 만들어 의미를 바꾸므로 채택하지 않고, "Issue #873 ..." 으로 어순을 바꿨다. 검증: markdownlint MD018 0건 (잔여 8건은 기존 지적), pytest 527 passed, manifest check OK, falsify 107/0, momentum 88/0. Refs #932 Confidence: high Session-Id: c16298d9-ce90-4536-8b4b-3d63818b411d * test(hooks): derive gate tokens from the registry CodeRabbit nitpick 반영. 두 셸 테스트가 게이트 토큰을 하드코딩된 부분 목록으로 검사하고 있었다 — momentum 은 5개만 보는데 _VERB_CHECKLISTS 의 `gh pr merge` 항목에는 8개가 등록돼 있어 momentum-rule-retrieval-gate / pipefail-advisory / skill-gate-commands 가 무검사였다. 이 PR 계열이 없애려는 under-enumeration 결함이 테스트 쪽에 남아 있던 셈이다. - verb_gate_checklist() 출력에서 `←` 태그된 게이트명을 정규식으로 도출해 전수 검사. 레지스트리에 항목이 늘면 테스트가 자동으로 따라간다. - raw stdout grep → 파싱된 permissionDecisionReason 대조. JSON 봉투의 다른 필드에 매칭되는 오진을 막는다. - falsify 쪽 개별 run_case 6건을 파생 전수 케이스 2건으로 대체. - momentum 의 relief 문구(PRAXIS_MOMENTUM_MERGE_ADVISORY=1, briefing-surfaced:)는 `←` 태그가 아닌 산문이라 파생 불가 — 명시 유지하고 주석에 이유를 남겼다. 검증: - 파생 토큰 수 merge 8개(기존 하드코딩 5개), AskUserQuestion 5개 - NC5 falsify reason 채널 제거 → 게이트 5개 전부 missing from decision reason, FAIL 2건 (101/2), 복원 후 103/0 - NC6 레지스트리에서 pipefail-advisory 제거 → 파생 8 → 7, 복원 8. 파생이 레지스트리를 실제로 추종함 확인 - PRAXIS_TESTS_STRICT=1 ./scripts/run-tests.sh → ALL TESTS PASSED Refs #932 Confidence: high Session-Id: c16298d9-ce90-4536-8b4b-3d63818b411d
배경
같은 action verb 에 여러 게이트가 걸리는데 각 게이트가 자기 토큰만 보고합니다. 작성자는 요구사항을 한 번에 하나씩 발견하며 게이트마다 리트라이 턴을 소모합니다. #873 은 한 세션에서 그런 차단 6회를 측정했고, 그중 최소 4건은 만족 형태가 이미 문서에 있었습니다 — 문서 부재가 아니라 호출 시점 retrieval 이 갭입니다.
이 세션에서도 같은 패턴이 1회 더 발생했습니다.
momentum-rule-retrieval-gate가 머지를 차단했고,# briefing-surfaced:마커는 spec 에 이미 있었는데 차단당한 뒤에야 읽었습니다.진단 — 이슈의 방식 B 전제는 절반만 맞았습니다
hooks/_lib/block_message.py의pr_body_evidence_checklist()(#824)가 이미 "한 deny 가 전체를 가르친다" 패턴을 구현하고 있었으나gh pr create하나에 하드코딩돼 있었습니다.output-block-falsify-advisory는 #787/#682/#828 로 자기 토큰 안내가 이미 충실합니다.실제 갭은 "deny 가 첫 누락만 보고한다"가 아니라 같은 verb 의 형제 게이트를 한 번도 알려주지 않는다 였습니다.
변경 사항
hooks/_lib/block_message.py— verb 키 레지스트리_VERB_CHECKLISTS+verb_gate_checklist(verb):gh pr creategh pr mergeAskUserQuestionPRAXIS_MOMENTUM_MERGE_ADVISORY=1,# briefing-surfaced:,--delete-branch조건,PRAXIS_ASK_END_ADVISORY=1, pre-merge-approval 의 "bypass 없음"). 게이트가 실제로 받지 않는 토큰은 권위 있게 읽히므로 체크리스트 부재보다 나쁩니다.pr_body_evidence_checklist()는 사본이 아니라 alias — 두 벌이 되면 drift 합니다.""를 반환해 호출자가 빈 블록을 붙일 수 없습니다.자기적용 함정
AskUserQuestion 체크리스트는
Falsified:토큰을 언급하고, 이 텍스트는 차단할 때마다 트랜스크립트로 나갑니다. 해당 토큰은 컬럼 0 에서만 인식되므로 들여쓰지 않으면 훅 자신의 출력이 작성자에게 요구하는 술어를 스스로 만족시킵니다. 들여쓰기로 막고 모든 등록 verb 에 대해test_verb_checklists_do_not_start_a_column_0_falsified_line로 고정했습니다.검증
음성 대조 — momentum impl 만 되돌리면 신규 케이스가
missing: pre-merge-approval-gate / gh-merge-worktree-precondition / commit-title-length-check로 FAIL, falsify impl 만 되돌리면 신규 3케이스 전부 FAIL.Pre-commit verified: scripts/run-tests.sh → ALL TESTS PASSED (1 skipped: markdownlint, 로컬 미설치), ruff clean, shellcheck clean, manifest check OK
Caller chain verified:
verb_gate_checklist호출부 3곳 전수 — momentum impl.py(merge deny), output-block-falsify-advisory impl.py(_build_ask_msg/_build_anchoring_ask_msg), block_message.py 내부pr_body_evidence_checklist()alias. 기존pr_body_evidence_checklist호출부 2곳(block-pr-without-caller-evidence, block-pr-without-precommit-evidence)은 시그니처 변경 없이 그대로 동작미검증 / 범위 밖
7.7.0이고 릴리스 PR chore(main): release 7.8.0 #904(7.8.0)가 열려 있어, 이 변경은 릴리스 전까지 실행되지 않습니다. 측정은 배포 이후 별도로 해야 합니다.git commit/gh issue createverb 는 배선할 훅 없이 레지스트리 항목만 추가하면 죽은 코드가 되므로 넣지 않았습니다.docs/hook/INDEX.md에 미커버로 명시했습니다.Closes #873
Summary by CodeRabbit
New Features
Documentation
Bug Fixes