Skip to content

feat(hooks): enumerate verb gates on first block - #931

Merged
devseunggwan merged 4 commits into
mainfrom
issue-873-feat-enumerate-gate-tokens
Aug 2, 2026
Merged

devseunggwan merged 4 commits into
mainfrom
issue-873-feat-enumerate-gate-tokens

Conversation

@devseunggwan

@devseunggwan devseunggwan commented Aug 2, 2026 •

Copy link
Copy Markdown
Owner

배경

같은 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):

verb 첫 차단에서 나열되는 게이트 방출 훅
gh pr create caller-evidence, precommit-evidence 두 pr-body 게이트 (기존)
gh pr merge momentum, pre-merge-approval, worktree-precondition, title-length(squash) momentum-rule-retrieval-gate
AskUserQuestion falsify-advisory, block-ask-end-option, block-manufactured-action-menu output-block-falsify-advisory
  • 각 토큰은 소유 훅의 소스에서 직접 확인해 적었습니다 (PRAXIS_MOMENTUM_MERGE_ADVISORY=1, # briefing-surfaced:, --delete-branch 조건, PRAXIS_ASK_END_ADVISORY=1, pre-merge-approval 의 "bypass 없음"). 게이트가 실제로 받지 않는 토큰은 권위 있게 읽히므로 체크리스트 부재보다 나쁩니다.
  • pr_body_evidence_checklist() 는 사본이 아니라 alias — 두 벌이 되면 drift 합니다.
  • 미등록 verb 는 "" 를 반환해 호출자가 빈 블록을 붙일 수 없습니다.

자기적용 함정

AskUserQuestion 체크리스트는 Falsified: 토큰을 언급하고, 이 텍스트는 차단할 때마다 트랜스크립트로 나갑니다. 해당 토큰은 컬럼 0 에서만 인식되므로 들여쓰지 않으면 훅 자신의 출력이 작성자에게 요구하는 술어를 스스로 만족시킵니다. 들여쓰기로 막고 모든 등록 verb 에 대해 test_verb_checklists_do_not_start_a_column_0_falsified_line 로 고정했습니다.

검증

python3 -m pytest tests/test_block_message.py -q          → 15 passed
tests/hooks/advisory-nudge/test_momentum_rule_retrieval_gate.sh   → 88 passed, 0 failed
tests/hooks/advisory-nudge/test_output_block_falsify_advisory.sh  → 104 passed, 0 failed
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.

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)은 시그니처 변경 없이 그대로 동작

미검증 / 범위 밖

  • 이슈 작업 3번(fire ledger 로 재차단률 측정)은 배포 후에만 가능합니다. 활성 캐시 플러그인이 7.7.0 이고 릴리스 PR chore(main): release 7.8.0 #904(7.8.0)가 열려 있어, 이 변경은 릴리스 전까지 실행되지 않습니다. 측정은 배포 이후 별도로 해야 합니다.
  • git commit / gh issue create verb 는 배선할 훅 없이 레지스트리 항목만 추가하면 죽은 코드가 되므로 넣지 않았습니다. docs/hook/INDEX.md 에 미커버로 명시했습니다.

Closes #873

Summary by CodeRabbit

  • New Features

    • Added comprehensive gate checklists for pull request creation, pull request merging, and user-question prompts.
    • Denial and escalation messages now include applicable required, conditional, and advisory checks.
    • Checklists clearly identify required approvals, worktree conditions, commit-title validation, and briefing details.
  • Documentation

    • Documented checklist coverage, delivery behavior, and current limitations.
  • Bug Fixes

    • Improved checklist formatting to prevent misleading or self-satisfying entries.

같은 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
@devseunggwan devseunggwan self-assigned this Aug 2, 2026
@coderabbitai

coderabbitai Bot commented Aug 2, 2026 •

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d11b7810-ae73-4e9e-9da3-018527aaec6f

📥 Commits

Reviewing files that changed from the base of the PR and between 6328fd7 and 23b0b4a.

📒 Files selected for processing (9)
  • docs/hook/INDEX.md
  • hooks/_lib/block_message.py
  • hooks/advisory-nudge/momentum-rule-retrieval-gate/impl.py
  • hooks/advisory-nudge/momentum-rule-retrieval-gate/spec.md
  • hooks/advisory-nudge/output-block-falsify-advisory/impl.py
  • hooks/advisory-nudge/output-block-falsify-advisory/spec.md
  • tests/hooks/advisory-nudge/test_momentum_rule_retrieval_gate.sh
  • tests/hooks/advisory-nudge/test_output_block_falsify_advisory.sh
  • tests/test_block_message.py
🚧 Files skipped from review as they are similar to previous changes (9)
  • hooks/advisory-nudge/output-block-falsify-advisory/spec.md
  • tests/hooks/advisory-nudge/test_momentum_rule_retrieval_gate.sh
  • docs/hook/INDEX.md
  • hooks/_lib/block_message.py
  • hooks/advisory-nudge/momentum-rule-retrieval-gate/impl.py
  • hooks/advisory-nudge/momentum-rule-retrieval-gate/spec.md
  • hooks/advisory-nudge/output-block-falsify-advisory/impl.py
  • tests/hooks/advisory-nudge/test_output_block_falsify_advisory.sh
  • tests/test_block_message.py

📝 Walkthrough

Walkthrough

Added shared gate checklists for gh pr create, gh pr merge, and AskUserQuestion. Updated advisory messages to emit the relevant checklist on stderr. Added documentation and regression tests.

Changes

Verb gate checklist expansion

Layer / File(s) Summary
Checklist registry and contract validation
hooks/_lib/block_message.py, tests/test_block_message.py, docs/hook/INDEX.md
Added verb-keyed checklists, lookup behavior, the PR-create compatibility alias, registry consistency checks, and documentation for supported and unsupported verbs.
Merge-denial checklist emission
hooks/advisory-nudge/momentum-rule-retrieval-gate/..., tests/hooks/advisory-nudge/test_momentum_rule_retrieval_gate.sh
Merge denial now writes the gh pr merge checklist to stderr before emitting the deny decision. Tests verify all gate identifiers and exclude the checklist from decision JSON.
AskUserQuestion checklist emission
hooks/advisory-nudge/output-block-falsify-advisory/..., tests/hooks/advisory-nudge/test_output_block_falsify_advisory.sh
T1 and T2 ask paths now write the AskUserQuestion checklist to stderr. Tests verify sibling gates and prevent column-zero Falsified: output.

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
Loading

Possibly related PRs

Suggested labels: enhancement, tool-friction:skill

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly states that the hooks now enumerate gate requirements by action verb.
Linked Issues check ✅ Passed The PR implements the verb-to-gate mapping and expands denial guidance for wired hooks; fire-ledger measurement is a post-deployment follow-up.
Out of Scope Changes check ✅ Passed All implementation, documentation, and test changes directly support verb-based gate checklists and their stderr delivery.
Docstring Coverage ✅ Passed Docstring coverage is 90.00% which is sufficient. The required threshold is 80.00%.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch issue-873-feat-enumerate-gate-tokens

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

"모든 게이트를 열거한다"는 변경이 정작 열거를 빠뜨렸다. 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
@devseunggwan

Copy link
Copy Markdown
Owner Author

Codex 리뷰 P2 3건을 6328fd7 로 반영했습니다. 세 건 모두 probe 로 확인된 유효한 지적이었고, "모든 게이트를 열거한다"는 PR 이 정작 열거를 빠뜨린 자기 반증입니다.

P2 — gh pr merge 체크리스트가 실제 게이트를 누락

Probe: grep -n "pr merge" hooks/preflight-gate/side-effect-scan/impl.py
  → 144: """Return True iff argv is `gh [global flags] pr merge ...`."""
  → 63:  OPT_OUT_MARKER = "# side-effect:ack"

지적대로 side-effect-scan 은 모든 gh pr merge 에 걸립니다. 여기서 멈추지 않고 impl 전수 grep 을 돌렸더니 조건부 2개가 더 나왔습니다:

Probe: grep -rln "pr merge" hooks/*/*/impl.py
  → pipefail-advisory (:175, 머지를 파이프로 연결한 경우)
  → skill-gate-commands (:113, PRAXIS_SKILL_GATED_COMMANDS opt-in)

P2 — AskUserQuestion 나머지 차단 게이트

Probe: jq -r '.hooks[] | select((.matcher//"") | contains("AskUserQuestion")) | .name' hooks/manifest.json
  → pr-state-refetch-gate / memory-hint / pre-output-falsification-gate /
    merge-menu-review-options-advisory / block-ask-end-option /
    block-manufactured-action-menu / output-block-falsify-advisory

PreToolUse 7개인데 3개만 적었습니다. 지적하신 2개보다 실제 누락이 많았습니다 — pre-output-falsification-gate 와 memory-hint 도 빠져 있었습니다. 지적을 그대로만 반영했으면 부분 수정으로 끝났을 것입니다.

무조건 / 조건부(strict env) / advisory-only 를 구분해 적었습니다. 구분 없이 나열하면 차단하지도 않는 advisory 를 만족시키려 또 한 턴을 씁니다.

P2 — PRAXIS_ASK_END_ADVISORY 의 "per call" 안내

Probe: grep -n PRAXIS_ASK_END_ADVISORY hooks/preflight-gate/block-ask-end-option/impl.py
  → 365: advisory_env = os.environ.get("PRAXIS_ASK_END_ADVISORY", "")

지적대로입니다. 훅이 자기 프로세스 environment 에서 읽으므로 인라인 VAR=1 접두는 도달하지 않습니다. session-level 설정임을 명시하고, per-call marker 가 없다는 것도 함께 적었습니다. momentum 게이트가 in-band 마커를 따로 만든 이유가 정확히 이건데 반대로 적었습니다.

드리프트 재발 방지

test_ask_and_merge_checklists_match_the_hook_registry — 체크리스트를 hooks/manifest.json 에 직접 대조합니다. AskUserQuestion 훅이 추가되면 이 테스트가 먼저 깨집니다. test_ask_end_optout_is_not_described_as_per_call 로 opt-out 문구도 고정했습니다.

남은 취약점 (PR 본문에도 명시)

gh pr merge 쪽 열거는 manifest 쿼리로 자동 대조할 수 없습니다 — Bash matcher 라 훅 이름만으로 verb 판정이 안 되고, 현재는 impl 전수 grep 한 시점의 스냅샷입니다. AskUserQuestion 쪽과 달리 구조적으로 고정돼 있지 않습니다.

검증 — test_block_message.py 17/17, 전체 scripts/run-tests.sh exit 0.

검증 제약 관련 — Codex 가 "read-only sandbox 에 writable temp dir 이 없어 pytest 와 shell suite 를 완료하지 못했다"고 밝혔습니다. 테스트는 이쪽에서 실행했습니다.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

📥 Commits

Reviewing files that changed from the base of the PR and between 3b7495b and 6328fd7.

📒 Files selected for processing (9)
  • docs/hook/INDEX.md
  • hooks/_lib/block_message.py
  • hooks/advisory-nudge/momentum-rule-retrieval-gate/impl.py
  • hooks/advisory-nudge/momentum-rule-retrieval-gate/spec.md
  • hooks/advisory-nudge/output-block-falsify-advisory/impl.py
  • hooks/advisory-nudge/output-block-falsify-advisory/spec.md
  • tests/hooks/advisory-nudge/test_momentum_rule_retrieval_gate.sh
  • tests/hooks/advisory-nudge/test_output_block_falsify_advisory.sh
  • tests/test_block_message.py

Comment thread docs/hook/INDEX.md Resolved
체크리스트가 각 항목 아래에는 "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
@devseunggwan

Copy link
Copy Markdown
Owner Author

codex 재리뷰 2라운드 반영 (23b0b4a)

4건 모두 적용했습니다.

F4 / F5 — 형제 게이트가 먼저 deny 하면 체크리스트가 버려짐

hooks/_lib/_dispatch.py 는 모든 훅의 stderr 를 전달하지만(184-187),
stdout decision JSON 은 첫 deny 것만 표면화합니다(195-201). 같은 verb 의
게이트들은 병렬 실행이므로, 형제 게이트가 먼저 deny 하면
permissionDecisionReason 에 실어 보낸 체크리스트는 그대로 소실됩니다 —
체크리스트가 존재해야 할 다중 게이트 상황이 정확히 그 케이스였습니다.

전달 경로를 stderr 로 옮겼습니다.

  • momentum-rule-retrieval-gate/impl.py: emit_decision("deny", ...) 직전
    sys.stderr.write(verb_gate_checklist("gh pr merge")). _merge_escalation_reason
    의 reason 문자열은 format_block(...) 원형으로 복원 (5필드 포맷 불변).
  • output-block-falsify-advisory/impl.py: _emit_verb_checklist() 를 신설해
    _emit_ask / _emit_t1_ask 양쪽에서 호출. ask 메시지 본문은 원상 복구.

F6 — gh pr merge 체크리스트에 session-intent 누락

session-intent 훅은 문자열 리터럴이 아니라 집합 멤버십
("pr": {..., "merge", ...}, impl.py:329)으로 verb 를 판정해서, 앞서 제가
근거로 제시한 grep -rln "pr merge" hooks/*/*/impl.py 열거에 잡히지
않았습니다. 그 grep 을 전수 검증이라고 보고한 것은 부정확했고, 조건부 항목으로
추가했습니다.

F7 — block-manufactured-action-menu 조건부로 이동

기본 advisory, PRAXIS_BLOCK_MANUFACTURED_MENU_STRICT=1 에서만 차단하므로
unconditional 블록에서 조건부 블록으로 옮기고 발동 조건을 명시했습니다.

문서

momentum .../spec.md, output-block-falsify-advisory/spec.md,
docs/hook/INDEX.md 를 stderr 라우팅 근거 + F6/F7 재분류에 맞춰 동기화.

검증

항목 결과
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 의 집계 계약 코드 직접 확인까지입니다.

@devseunggwan
devseunggwan merged commit cf71fe9 into main Aug 2, 2026
10 checks passed
@devseunggwan
devseunggwan deleted the issue-873-feat-enumerate-gate-tokens branch August 2, 2026 22:22
devseunggwan added a commit that referenced this pull request Aug 3, 2026
* 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(hook): enumerate all gate tokens per action verb

1 participant