Skip to content

feat(hooks): require a non-mutating tier in approval menus - #966

Merged
devseunggwan merged 6 commits into
mainfrom
issue-963-feat-nonmutating-tier-in-menus
Aug 12, 2026
Merged

devseunggwan merged 6 commits into
mainfrom
issue-963-feat-nonmutating-tier-in-menus

Conversation

@devseunggwan

@devseunggwan devseunggwan commented Aug 12, 2026 •

Copy link
Copy Markdown
Owner

요약

AskUserQuestion PreToolUse advisory 훅 menu-mutation-tier-advisory 를 추가한다.
한 질문의 후보 옵션이 전부 mutation 티어에 있고 비-mutating 대안이 하나도 없을 때,
비-mutating 티어를 한 칸 넣거나 그것이 불가능한 사유를 메뉴 본문에 적으라고 nudge 한다.

메뉴는 축을 고정하고 사용자는 그 축 위의 한 점만 고른다. 축 전체가 공유 상태를 바꾸면
사용자는 "얼마나 할지"를 고른 것이지 "할지 말지"를 고른 것이 아니다 — 안전 티어가
후보에 없었으므로 동의 자체가 무결하지 않다.

Closes #963

설계 판단 — 신규 훅 vs 기존 훅에 축 추가

이슈가 지정한 두 훅을 먼저 읽고 신규 훅으로 판정했다.

block-manufactured-action-menu 에 축을 얹지 않은 이유 (3가지):

  1. 제어 흐름이 재사용 불가. 이 훅은 _has_manufactured_marker(labels) 에서 가장 먼저
    early-return 하는데, 2026-08-11 사건 메뉴는 manufactured 마커를 하나도 갖고 있지 않다
    (두 소스 다 트리거 / 한 건만 먼저 / 다음 정기 실행에 맡김). 티어 축은 그 게이트
    앞 에 통째로 끼워 넣어야 하고, 공유하는 것은 라벨 추출기 하나뿐이다.
  2. 입력 표면이 다르다. 저 훅의 판정은 transcript 의 직전 사용자 메시지(command-intent)를
    읽어야 성립한다. 티어 축은 payload 만으로 판정되며 transcript 를 전혀 필요로 하지 않는다.
  3. role 이 다르다. 저 훅은 차단 가능한 preflight-gate 다. 이 축은 기본값이 절대
    차단이면 안 된다 — prod 가 유일한 경로인 경우가 실제로 있고, 그때 필요한 것은 차단이
    아니라 사유 고지다.

merge-menu-review-options-advisory 를 구조적으로 그대로 따랐다. 같은 event/matcher,
자기 디렉터리, payload-only 판정, advisory 기본값 + opt-in strict, .strip() == "1"
strict-env 계약, @fail_open, _collect_option_* 라벨 워커. 형제 컨벤션 조사 근거는
이 두 구현이다 (≥2).

세 훅은 같은 이벤트의 서로 다른 축이다.

훅 축 묻는 것
block-manufactured-action-menu 제조 여부 이 메뉴는 중복 인가 — 사용자가 이미 지시했는가?
merge-menu-review-options-advisory 완결성 merge 게이트가 리뷰 레버 를 제공하는가?
menu-mutation-tier-advisory (신규) blast radius 옵션들이 둘 이상의 mutation 티어 에 걸쳐 있는가?

열린 질문에 대한 답 — "아무것도 하지 않는" 옵션은 티어가 아니다

이슈의 열린 질문: 다음 정기 실행에 맡김 같은 포기 옵션을 비-mutating 티어로 쳐야 하는가?

아니다. 사건이 그 근거다. 그 메뉴에는 그런 옵션이 있었고 티어 선택지로 기능하지
못했다 — 더 싸게 검증하는 방법이 아니라 검증을 포기하는 선택이었다. 이것을 안전 티어로
치면 훅은 자기가 존재하는 이유인 바로 그 메뉴에서 침묵한다.

그래서 포기(abandonment)를 독립 클래스로 두고 양방향으로 작동시켰다.

  • advisory 를 억제하지 않는다 — 남은 후보들은 여전히 전부 mutating 이고 사용자에게는
    여전히 안전한 검증 경로가 없다.
  • 후보로도 세지 않는다 — 그래서 이분법 go/no-go 메뉴(squash 머지 / 대기)는
    실질 후보가 1개뿐이라 발화하지 않는다. 그 메뉴는 진짜 "할지 말지"이고, 이 훅이
    보호하려는 것이 바로 그것이다.

픽스처가 이 구분을 양방향으로 고정한다 (테스트 섹션 (d)): 사건 메뉴 발화 / 포기 옵션이
억제하지 않음 3케이스 / 이분법 메뉴 미발화 3케이스 / 같은 모양의 포기 슬롯에 실제 저-blast
옵션을 넣으면 미발화(짝 대조).

이슈 초안의 신호 목록은 하지 않음 을 저-blast 쪽에 두었다. 구현이 이슈에서 의도적으로
갈라지는 유일한 지점이며, 열린 질문 자체가 이 판단을 요구한 것이다. 보고만 은
저-blast 로 남긴다 — report-only 패스는 아무것도 건드리지 않는 진짜 검증이다.

판정 술어

질문 단위 로 평가하고 하나라도 걸리면 발화한다. 질문을 pool 하면 한 질문의 preview
옵션이 다른 질문의 all-prod 메뉴를 덮어버린다.

한 질문의 옵션 집합에 대해, early-return 이 도는 순서대로:

  1. 어떤 옵션도 저-blast 신호를 갖지 않을 것 — 하나라도 있으면 억제
  2. 포기가 아닌 후보가 2개 이상 남을 것
  3. 후보 중 1개 이상 이 mutation 신호를 가질 것

이슈 문구와의 의도적 divergence. 이슈는 모든 옵션이 mutation 신호를 가져야 한다고
쓴다. 어휘적으로 판정 불가능하다: 범위 축소 옵션(한 건만 먼저)은 형제 옵션에서 동사를
생략 상속하므로 자기 토큰이 없고, all-must-match 술어는 이슈 자신의 배경 섹션에 있는 그
사건 메뉴에서 침묵한다. 구현은 mutation 신호를 후보 1개 이상에서 받고 저-blast 옵션의
부재
자체를 결함으로 본다 — 이슈의 헤드라인 논증이 실제로 말하는 속성이 그쪽이다.

토큰 집합

옵션의 label + description 을 합쳐 분류한다. 이슈 SOT 가 "옵션 라벨/설명에서" 라고
명시하고, 생략형 라벨은 대상을 description 에만 담는 일이 흔하다.

영어는 ASCII-letter lookaround ((?<![a-z])prod(?![a-z])) — 이 레포의 whole-token
메커니즘이다. \b 는 prod실행 을 쪼개지 못한다 (Python 의 유니코드 \w 가 한글을
단어 문자로 취급). 그래서 merged/merger/deployment 는 매치되지 않고 prod 트리거,
dry-run 은 매치된다. 한국어는 substring — 이 이벤트의 형제 훅 둘 다 쓰는 컨벤션이며
(CJK 에 ASCII 단어 경계가 없다), 맨 동사 대신 다중 문자 구를 선호해 충돌을 통제한다.
실행 은 의도적으로 제외했다 — 포기 라벨 다음 정기 실행에 맡김 안에 들어 있다.

  • Tier 1 (mutation) — EN: prod production deploy trigger merge delete
    drop truncate apply backfill overwrite publish push / KO: 프로덕션
    실 고객 실고객 실제 고객 운영 환경 운영환경 트리거 머지 삭제 배포
    적용 덮어쓰 백필
  • Tier 2 (저-blast, 억제) — EN: preview dev staging sandbox dry-run
    dryrun dry run local mock simulate simulation read-only readonly
    report-only plan-only no-op noop review reviewer codex critic
    audit inspect / KO: 프리뷰 미리보기 개발 환경 개발환경 샌드박스
    스테이징 드라이런 보고만 조회만 읽기 전용 읽기전용 시뮬레이션 로컬
    리뷰 검토 점검
  • Tier 0 (포기, 억제도 후보도 아님) — EN: later skip defer postpone
    do nothing nothing cancel hold wait none / KO: 다음 정기 다음 주기
    나중에 하지 않 안 함 안함 대기 보류 취소 건너뛰 미루 아무것도
    그대로 둬 그대로 둔

리뷰/점검 레버를 Tier 2 에 넣은 것은 의도적이다 — 리뷰 재실행은 공유 표면을 건드리지 않고
검증하는 행위이고, 이 훅이 메뉴에 요구하는 "더 싼 대안" 이 바로 그것이다. 이 집합의
오탐은 nudge 를 침묵 시킬 뿐이라 안전한 방향이며, merge-menu-review-options-advisory
가 자기 억제 집합에 대해 기록한 것과 같은 논리다. reviewer/codex/critic 을 review
와 나란히 둔 이유는 lookaround 가 whole-token 이라 review 가 code-reviewer 안에서
매치되지 않기 때문이다 (픽스처가 잡아냈다).

오탐 리스크와 self-application 회귀

판정이 어휘 기반이라 오탐 위험이 있다. 알려진 한계 4건을 spec 에 명시했다 (merge-strategy
chooser 발화 / 토큰으로 이름 붙지 않은 비-mutating 옵션 비가시 / production 의 형용사적
용법 / 포기 분류도 어휘적).

자기 detector 를 자기 픽스처로만 검증하면 FP↔FN 상쇄가 비가시라는 이 레포의 교훈에 따라,
이 훅의 spec.md 자체를 payload 로 넣는 self-application 회귀 케이스 를 넣었다 —
세 토큰 집합을 전부 산문으로 담고 있는 문서를 옵션 description 으로 먹여도 침묵해야 한다.

Codex 리뷰 라운드 1 — 3건 전부 재현 후 수정

세 지적 모두 실제 payload 실행으로 재현한 뒤 적용했다 (코드만 읽고 판단하지 않음).

# 지적 재현 (strict mode) 수정
P1 복합 옵션이 안전 티어로 오인됨 Dry-run then deploy to prod / Deploy directly to prod → rc=0 침묵 Tier 1 을 대상(prod/실 고객)과 동사(deploy/트리거…)로 분리. 저-blast 는 high-blast 대상 을 함께 이름하지 않을 때만 억제
P2 외부 쓰기가 mutation 이 아님 Send Slack now / Send email instead → rc=0 침묵 외부 전송 동사(send notify broadcast announce submit / 전송 발송 공지 게시)를 Tier 1b 에 추가
P2 development 미인식 deploy to production / deploy to development first → rc=2 오차단 development, 개발 서버, 개발계 를 저-blast 에 추가

P1 의 수정 방향이 핵심이다. 단순히 "mutation 신호가 있으면 저-blast 아님" 으로 고치면
deploy to dev first 가 실격되어 정당한 안전 옵션이 사라진다. 실격 사유는 mutation
동사 가 아니라 high-blast 대상 이다 — deploy to dev 는 안전 표면을 겨눈
동사이고 정확히 이 훅이 메뉴에 요구하는 대안이다. 양방향 픽스처로 고정했다.

P2 의 "기존 공통 mutation 분류기를 재사용하라" 는 전제는 반증됐다 —
grep -rln "MUTATION_TOKENS" hooks/_lib/ 결과 없음. 재사용할 분류기가 없어 훅 내부에
정의했다.

회귀 픽스처 11건 추가 (섹션 d2), 총 57/57 통과. 수정된 spec.md 로 self-application
케이스를 다시 돌려도 침묵한다.

예약 영역 침범 1건 — hooks/_lib/block_message.py

이 wave 에서 해당 파일은 #951 담당이었으나 회피 불가능해 4줄 append 했다 (로직 0줄).
tests/test_block_message.py::test_ask_and_merge_checklists_match_the_hook_registry
가 hooks/manifest.json 에 등록된 모든 PreToolUse(AskUserQuestion) 훅이
_VERB_CHECKLISTS["AskUserQuestion"] 문자열에 이름으로 등장할 것을 강제한다 — 신규
훅을 manifest 에 등록하는 순간 이 테스트가 빨개지므로 "새 AskUserQuestion 훅 추가"와
"이 파일 수정"은 분리할 수 없다. 팀 리드에 별도 보고함.

검증

  • 훅 전용 스위트 57/57 통과: bash tests/hooks/advisory-nudge/test_menu_mutation_tier.sh
  • 실제 payload 실행으로 발화/침묵 확인 (검증 앵커 코멘트에 출력 게시)
  • ./scripts/check-plugin-manifests.py OK — manifest↔디렉터리 교차 검사, 생성물
    byte-identical, Supported hosts: 대조, docs/bypass-vars.md strict-env 양방향 대조
  • 생성물 재생성: ./scripts/build-plugin-manifests.py (4개 platform hooks.json,
    wrapper, docs/hook-operating-matrix.md, docs/hook/menu-mutation-tier-advisory.md)
  • README.md 는 훅별 인덱스를 갖고 있지 않고 ARCHITECTURE.md → Hook index 로 위임한다.
    그 인덱스와 docs/hook/INDEX.md 두 곳(행 + AskUserQuestion 열거 행)을 갱신했다.

Pre-commit verified: ./scripts/run-tests.sh (CI 진입점) 전체 실행 → ALL TESTS PASSED
EXIT=0, SKIPPED 0건 — pytest 573 passed / shell 전체 / manifest / invariants / ruff /
shellcheck / markdownlint 7단계 전부 실행. markdownlint 는 advisory 3건(레포 설정상 CI
불통과 아님): ARCHITECTURE.md MD040·MD032 2건은 기존 위반, 신규 spec.md MD001 1건은
모든 기존 spec.md 가 공유하는 # → ### 템플릿 컨벤션 (형제
merge-menu-review-options-advisory/spec.md 도 동일 지적)

Caller chain verified: grep -rln 'menu-mutation-tier-advisory' . → 훅 디렉터리 외
12개 참조처 전부 확인 — hooks/manifest.json, 4개 platform hooks.json
(.claude-plugin / .codex-plugin / .cursor-plugin / .opencode), 생성 wrapper
hooks/menu-mutation-tier-advisory.sh, ARCHITECTURE.md, docs/hook/INDEX.md,
docs/hook/menu-mutation-tier-advisory.md, docs/hook-operating-matrix.md,
docs/bypass-vars.md, tests/hooks/advisory-nudge/test_menu_mutation_tier.sh

Summary by CodeRabbit

  • New Features

    • Added guidance for approval menus containing potentially impactful actions without lower-impact alternatives.
    • Menus now recognize previews, dry runs, sandboxes, reviews, and similar safe options.
    • Supports advisory mode by default and optional strict mode to block qualifying menus.
    • Abandonment choices and documented reasons for unavailable safe options are handled appropriately.
  • Documentation

    • Added configuration guidance, operating details, and behavioral specifications.
  • Tests

    • Added coverage for advisory, blocking, safe alternatives, abandonment choices, malformed input, and multiple-question scenarios.

@devseunggwan devseunggwan self-assigned this Aug 12, 2026
@coderabbitai

coderabbitai Bot commented Aug 12, 2026 •

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@devseunggwan, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 58 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: de76cd16-3537-4f27-90cf-a546bae50eb0

📥 Commits

Reviewing files that changed from the base of the PR and between f7cb4c6 and 26392c6.

📒 Files selected for processing (7)
  • ARCHITECTURE.md
  • docs/hook-operating-matrix.md
  • docs/hook/INDEX.md
  • hooks/advisory-nudge/menu-mutation-tier-advisory/impl.py
  • hooks/advisory-nudge/menu-mutation-tier-advisory/spec.md
  • hooks/manifest.json
  • tests/hooks/advisory-nudge/test_menu_mutation_tier.sh
📝 Walkthrough

Walkthrough

This PR adds the menu-mutation-tier-advisory hook for PreToolUse(AskUserQuestion). It classifies menu options, emits advisories by default, supports strict blocking, registers the hook across hosts, documents its behavior, and adds regression tests.

Changes

Menu mutation-tier advisory

Layer / File(s) Summary
Tier classification contract
hooks/advisory-nudge/menu-mutation-tier-advisory/impl.py, hooks/advisory-nudge/menu-mutation-tier-advisory/spec.md
Defines English and Korean mutation, low-blast, and abandonment signals. It specifies per-question evaluation, token matching, fail-open parsing, advisory output, and strict-mode exit behavior.
Hook execution and integration
hooks/advisory-nudge/menu-mutation-tier-advisory/impl.py, hooks/menu-mutation-tier-advisory.sh, hooks/manifest.json, .claude-plugin/hooks/hooks.json, .cursor-plugin/hooks/hooks.json, .opencode/hooks/hooks.json, plugins/praxis/.codex-plugin/hooks/hooks.json, hooks/_lib/block_message.py, ARCHITECTURE.md, docs/bypass-vars.md, docs/hook-operating-matrix.md, docs/hook/INDEX.md, docs/hook/menu-mutation-tier-advisory.md
Traverses AskUserQuestion payloads independently per question and emits an advisory or strict block. Registers the hook with a five-second timeout and documents PRAXIS_MENU_MUTATION_TIER_STRICT.
Behavioral regression coverage
tests/hooks/advisory-nudge/test_menu_mutation_tier.sh
Tests mutation detection, safe-tier suppression, abandonment handling, multilingual and description matching, strict-mode values, malformed payloads, question isolation, and specification self-application.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

  • devseunggwan/praxis#789: Adds a parallel advisory-nudge hook with registration, specification, implementation, and tests.
  • devseunggwan/praxis#931: Adds the related AskUserQuestion verb-checklist infrastructure used by this hook.

Suggested labels: enhancement

Sequence Diagram(s)

sequenceDiagram
  participant AskUserQuestion
  participant menu_mutation_tier_advisory_sh
  participant menu_mutation_tier_impl
  AskUserQuestion->>menu_mutation_tier_advisory_sh: Send PreToolUse payload
  menu_mutation_tier_advisory_sh->>menu_mutation_tier_impl: Forward payload
  menu_mutation_tier_impl-->>AskUserQuestion: Return advisory or strict block
Loading
🚥 Pre-merge checks | ✅ 2 | ❌ 3

❌ Failed checks (3 warnings)

Check name Status Explanation Resolution
Linked Issues check ⚠️ Warning The PR adds the requested hook, classification, fixtures, and advisory, but its broader predicate and blocking mode conflict with issue #963. Require mutation signals on every non-abandonment candidate before advising, and remove strict blocking from this issue's implementation.
Out of Scope Changes check ⚠️ Warning The manifests, wrapper, tests, and documentation are related, but strict blocking and the broader trigger predicate extend beyond issue #963. Limit the implementation to the advisory-only, all-mutating-menu behavior defined in issue #963.
Docstring Coverage ⚠️ Warning Docstring coverage is 54.55% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (2 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly identifies the new hook behavior: requiring a non-mutating tier in approval menus.
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch issue-963-feat-nonmutating-tier-in-menus

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.

@devseunggwan

devseunggwan commented Aug 12, 2026 •

Copy link
Copy Markdown
Owner Author

Verification — 26392c6 (rev 7)

Carried: #974 — codex 라운드-1 어휘 커버리지 3건(아래 Unverified 마지막 항목). 나머지 3건은 이월 대상이 아니다: 런타임 발화 확인은 머지 후 fire-ledger 관측이라 선행 작업이 없고, 사건 메뉴 재구성과 오발화율 미측정은 다음 조치가 명시돼 있지 않다.

# Claim Result
1 2026-08-11 사건 메뉴 형태에서 advisory 가 발화한다 PASS(live)
2 안전 티어가 있거나 티어와 무관한 메뉴에서는 침묵한다 PASS(live)
3 포기 옵션은 억제하지도, 후보로 세지지도 않는다 (열린 질문) PASS(live)
4 복합 옵션이 메뉴를 침묵시키지 않고, mutation 동사만으로는 실격되지 않는다 (codex P1) PASS(live)
5 외부 쓰기가 mutation 으로, development 가 저-blast 로 분류된다 (codex P2) PASS(live)
6 이 훅 자신의 spec.md 를 payload 로 넣어도 오발화하지 않는다 PASS(live)
7 생성 wrapper 경유 end-to-end 로 동작하고 4개 platform 에 등록된다 PASS(live)
8 CI 진입점 ./scripts/run-tests.sh 전체가 통과한다 PASS(live)
9 포기 옵션이 저-blast 토큰을 함께 가져도 억제하지 않는다 (CodeRabbit) PASS(live)
10 Safe-tier-unavailable: 사유 마커가 해당 질문만 억제한다 (CodeRabbit) PASS(live)
11 마커를 감싼 펜스·HTML 주석은 억제하지 못하고, 닫힌 펜스 뒤 진짜 마커는 인정된다 (CodeRabbit 라운드-2) PASS(live)
12 발화한 advisory 가 모델이 읽는 채널로 나가고, 침묵 시에는 아무것도 내보내지 않는다 (CodeRabbit CR4 / codex F1) PASS(live)
Unverified — 실제 Claude Code 런타임 안에서 훅이 발화하는 것은 미확인 · 사건 메뉴는 캡처본이 아닌 이슈 본문 기반 재구성 · 어휘로 이름 붙지 않는 비-mutating 옵션의 오발화율 미측정 · codex 라운드-1 지적 3건은 검증만 하고 미적용
  • 런타임 발화 미확인: 검증은 전부 payload 를 stdin 으로 주입하는 방식이다. 훅의 실제
    프로덕션 입력이 정확히 그 JSON payload 이므로 판정 로직은 live 지만, Claude Code 가
    AskUserQuestion 시점에 이 wrapper 를 실제로 호출하는 것까지는 이 PR 에서 확인하지
    않았다. 등록 사실(행 7)까지만 확인됨. 머지 후 실제 세션에서 fire-ledger 로 확인 가능.
  • 사건 메뉴는 재구성: 이슈 feat(hooks): require a non-mutating tier in shared-state approval menus #963 본문에 라벨 3개만 기록돼 있고 description 은 남아
    있지 않다. 행 1 의 payload 는 그 라벨을 그대로 쓰고 description 을 그럴듯하게 채운
    재구성이다. 라벨만으로도 발화하므로 판정은 description 에 의존하지 않는다.
  • 오발화율 미측정: 판정이 어휘 기반이라 토큰으로 이름 붙지 않는 비-mutating 옵션
    (예: 호스트명으로만 지칭된 스테이징 클러스터)은 비가시다. spec 의 "Known limitations"
    4건에 명시했으며, advisory 라 비용은 문장 하나다.
  • codex 라운드-1 3건 미적용: 검증까지만 하고 편집하지 않았다. 3건(복합 옵션의
    mutation 동사 재검사 / create·update 류 일반 mutation 동사 누락 / 대상이 명시된
    Cancel 을 포기로 오분류)은 strict 프로브로 재현됐고 실재한다. 적용 여부는 이 PR
    밖의 판단이라 승인 대기 중이며, 어느 것도 이 PR 이 주장하는 발화 술어를 무효화하지
    않는다 — 전부 어휘 집합의 커버리지 축이다. 나머지 1건(stderr 는 모델에 안 보임)은
    CodeRabbit CR4 와 같은 지적이며 c41c285 에서 적용했다(행 12).
Evidence 1 — 사건 메뉴 형태에서 advisory 발화

이슈 본문의 라벨 3개를 그대로 쓴 payload 를 훅 stdin 에 주입했다. 훅의 실제 입력이 바로 이
JSON 이므로 이것이 판정 로직에 대한 oracle 이다. 세 옵션 중 다음 정기 실행에 맡김 은
포기로 분류돼 후보에서 빠지고, 남은 두 후보가 전부 mutating 이며 저-blast 옵션이 0개다.

$ echo '{"tool_name":"AskUserQuestion","tool_input":{"questions":[{"question":"prod DAG 트리거 승인","header":"트리거","options":[{"label":"두 소스 다 트리거 (Recommended)","description":"두 소스 모두 지금 트리거"},{"label":"한 건만 먼저","description":"한 건만 먼저 처리"},{"label":"다음 정기 실행에 맡김","description":"이번에는 아무것도 하지 않는다"}]}]}}' \
    | ./hooks/advisory-nudge/menu-mutation-tier-advisory/impl.py
incident -> rc=0, stderr non-empty: [advisory] AskUserQuestion approval menu offers no non-mutating tier.
Evidence 2 — 안전 티어가 있거나 티어와 무관한 메뉴에서 침묵

같은 사건 메뉴에 preview 옵션 한 칸을 넣은 것, 이분법 go/no-go, 그리고 티어와 무관한
문서 톤 선택 세 가지를 같은 방식으로 주입했다. 발화 조건의 세 early-return 을 각각 하나씩
때리는 payload 라 침묵의 사유가 서로 다르다.

$ # 동일 harness, 세 payload
incident+preview -> rc=0, stderr empty
binary 머지/대기 -> rc=0, stderr empty
doc tone         -> rc=0, stderr empty
Evidence 3 — 포기 옵션은 억제하지도 후보로 세지지도 않는다

이슈의 열린 질문에 대한 답을 양방향으로 고정한다. 첫 케이스는 포기 옵션이 있어도 발화해야
하고(억제 안 함), 둘째는 포기 옵션 때문에 실질 후보가 1개뿐이라 침묵해야 하며(후보 아님),
셋째는 같은 자리에 진짜 저-blast 옵션이 오면 침묵해야 한다(짝 대조).

$ # 동일 harness, 세 payload
abandon does not suppress  -> rc=0, stderr non-empty
abandon not a candidate    -> rc=0, stderr empty
safe tier in that slot     -> rc=0, stderr empty
Evidence 4 — 복합 옵션이 침묵시키지 않고, mutation 동사는 실격 사유가 아니다

codex 라운드-1 P1 의 회귀. strict mode 로 돌려 rc 로 판정을 읽는다 — advisory mode 는 두
경우 다 rc=0 이라 stderr 로만 구분되므로, rc 가 갈리는 strict 가 더 선명한 oracle 이다.
첫 줄이 결함(수정 전 rc=0 침묵), 둘째 줄이 과잉 수정을 막는 대조군이다.

$ # PRAXIS_MENU_MUTATION_TIER_STRICT=1, 동일 harness
P1 hybrid dry-run→prod   -> strict rc=2, stderr non-empty
P1 control deploy-to-dev -> strict rc=0, stderr empty
Evidence 5 — 외부 쓰기는 mutation, `development` 는 저-blast

codex 라운드-1 P2 두 건의 회귀. 첫 줄은 수정 전 strict 에서도 rc=0 으로 통과하던 외부
전송 전용 메뉴, 둘째 줄은 dev whole-token 이 development 에 걸리지 않아 안전 옵션이
있는데도 rc=2 로 오차단하던 케이스다.

$ # PRAXIS_MENU_MUTATION_TIER_STRICT=1, 동일 harness
P2 external write -> strict rc=2, stderr non-empty
P2 development    -> strict rc=0, stderr empty
Evidence 6 — 자기 spec.md 를 payload 로 넣어도 오발화하지 않는다

어휘 detector 를 자기 픽스처로만 검증하면 FP↔FN 상쇄가 비가시라, 세 토큰 집합을 전부
산문으로 담고 있는 문서를 옵션 description 으로 먹여 침묵을 확인한다. 이 문서는 판정
술어에 맞춰 깎은 입력이 아니라는 점이 이 oracle 의 값어치다. 억제 사유는 저-blast 토큰의
존재이며, 토큰을 늘린 수정 이후에도 다시 돌려 유지됨을 확인했다.

$ python3 -c '<spec.md 를 두 옵션 description 으로 나누는 payload 생성>' \
    | ./hooks/advisory-nudge/menu-mutation-tier-advisory/impl.py
own spec.md as payload -> rc=0, stderr empty
Evidence 7 — 생성 wrapper 경유 동작 및 4개 platform 등록 (rev 7 에서 rebase HEAD 기준 재측정)

impl.py 직접 실행이 아니라 빌드가 생성한 hooks/menu-mutation-tier-advisory.sh 를 통해
호출했다. 런타임이 실제로 부르는 것이 이 wrapper 이므로, impl.py 통과만으로는 wrapper
생성·경로 해석이 검증되지 않는다. 페이로드는 픽스처의 build_payload 가 만드는 것과 같은
형태로 2026-08-11 사건 메뉴를 실었다.

$ cat /tmp/menu966.json
{"session_id": "test-session", "tool_name": "AskUserQuestion", "tool_input": {"questions": [{"question": "Which?", "header": "Choose", "multiSelect": false, "options": [{"label": "두 소스 다 트리거 (Recommended)", "description": "두 소스 모두 지금 트리거한다"}, {"label": "한 건만 먼저", "description": "한 건만 먼저 처리한다"}, {"label": "다음 정기 실행에 맡김", "description": "이번에는 아무것도 하지 않는다"}]}]}, "cwd": "/tmp"}
$ ./hooks/menu-mutation-tier-advisory.sh < /tmp/menu966.json
[advisory] AskUserQuestion approval menu offers no non-mutating tier.
(이하 advisory 본문 및 permissionDecision=ask JSON 생략 — 첫 줄이 발화 판정의 오라클이다)
wrapper exit=0

이어서 4개 platform hooks.json 각각의 등록 건수를 센다.

$ for f in .claude-plugin/hooks/hooks.json plugins/praxis/.codex-plugin/hooks/hooks.json .cursor-plugin/hooks/hooks.json .opencode/hooks/hooks.json; do printf '%s: %s\n' "$f" "$(grep -c 'menu-mutation-tier-advisory' "$f")"; done
.claude-plugin/hooks/hooks.json: 1
plugins/praxis/.codex-plugin/hooks/hooks.json: 1
.cursor-plugin/hooks/hooks.json: 1
.opencode/hooks/hooks.json: 1

rebase 후 hooks/manifest.json 이 #969 의 항목과 union 됐으므로, 생성물 재생성 drift 0
과 정합 검사도 같은 HEAD 에서 확인했다.

$ python3 scripts/check-plugin-manifests.py
plugin-manifest check OK
check exit=0
Evidence 8 — CI 진입점 전체 통과 (rev 7 에서 rebase HEAD 의 CI job 으로 교체)

부분 실행(pytest tests/)은 셸 테스트를 놓치므로 CI 워크플로가 부르는 진입점 자체
(.github/workflows/ci.yml → bash scripts/run-tests.sh)가 오라클이다. rev 6 까지는
c41c285 에서의 로컬 실행을 근거로 삼았는데 rebase 로 HEAD 가 이동했으므로, 새 HEAD 에
대해 실제로 돌아간 CI job 으로 바꿨다.

$ gh pr checks 966 --repo devseunggwan/praxis | awk -F'\t' '$1=="test"{print "  "$2" "$4}'
  pass https://github.com/devseunggwan/praxis/actions/runs/31601671696/job/94130369980

c41c285 로컬 실행에서 관측된 사실 중 이 커밋에서도 유효한 것: markdownlint 3건은
레포 설정상 advisory 이며 CI 를 실패시키지 않는다 — ARCHITECTURE.md 2건은 기존
위반이고, 신규 spec.md 1건은 기존 spec.md 85개 중 52개가 공유하는 # → ###
템플릿 컨벤션이라 미수정으로 닫았다(억제 지시어 미사용).

Evidence 9 — 포기+저-blast 중첩 옵션이 억제하지 않는다

CodeRabbit 라운드-1. skip this run and review later 는 포기 토큰과 저-blast review
를 동시에 갖는다. strict mode 로 돌려 rc 로 판정을 읽는다 — 수정 전 이 옵션 하나가
전부-prod 메뉴를 strict 에서도 rc=0 으로 침묵시켰다.

수정 전(b34ac92 작업 트리)에서 결함을 먼저 재현했다:

$ python3 -c '<3-option payload 생성>' \
    | PRAXIS_MENU_MUTATION_TIER_STRICT=1 ./hooks/advisory-nudge/menu-mutation-tier-advisory/impl.py
CR3: strict rc=0 stderr=empty

수정 후 같은 폼이 픽스처로 고정돼 있다 (advisory·strict·KO 3면):

$ bash tests/hooks/advisory-nudge/test_menu_mutation_tier.sh   # (d3) 블록
PASS [advisory] abandon+low-blast overlap does not suppress
PASS [block]    strict: overlap form blocks
PASS [advisory] KO 대기+검토 overlap does not suppress
Evidence 10 — 사유 마커가 해당 질문만 억제한다

advisory 는 "안전 옵션을 넣거나 불가능한 사유를 적어라" 둘 중 하나를 요구하는데, 후자를
기록할 방법이 없어 strict 에서는 옵션 추가 외에 통과할 길이 없는 게이트였다. 픽스처가
계약의 네 면을 각각 때린다 — 인정 / 중간 삽입 불인정 / 빈 마커 불인정 / 질문 단위.

$ bash tests/hooks/advisory-nudge/test_menu_mutation_tier.sh   # (d4) 블록
PASS [pass]     stated reason suppresses
PASS [pass]     strict: stated reason suppresses
PASS [advisory] reason marker mid-line does not count
PASS [advisory] empty reason marker does not count
PASS [advisory] reason on q1 does not cover q2
Evidence 11 — 펜스 안 마커는 억제하지 못한다

CodeRabbit 라운드-2. spec.md:115-120 과 impl.py:282 주석이 둘 다 "펜스는 세지 않는다"
라고 이미 적어둔 상태에서 구현만 컬럼 0 startswith 였으므로, 코드가 자기 계약을
어긴 동시에 strict 우회 경로였다. strict 로 돌려 rc 로 읽는다.

수정 전(f7cb4c6 작업 트리)에서 결함을 먼저 재현했다:

$ python3 -c '<question 본문을 ```text 펜스로 감싼 마커로 만드는 payload 생성>' \
    | PRAXIS_MENU_MUTATION_TIER_STRICT=1 ./hooks/advisory-nudge/menu-mutation-tier-advisory/impl.py
strict rc=0

수정 후 같은 payload:

$ PRAXIS_MENU_MUTATION_TIER_STRICT=1 ./hooks/advisory-nudge/menu-mutation-tier-advisory/impl.py < /tmp/fence_payload.json
BLOCKED: AskUserQuestion approval menu offers no non-mutating tier.
strict rc=2

펜스만 막으면 같은 가족의 다른 래퍼가 남으므로 마커 입력 표면을 열거해
(praxis:surface-enumeration) 12종을 _has_reason_marker 에 직접 먹였다. V6 는
짝 대조다 — 닫힌 펜스 뒤 진짜 마커까지 죽이면 우회가 아니라 기능을 없앤 것이 된다.

$ python3 <열거한 12종을 _has_reason_marker 에 먹이는 harness>
OK  V1 plain col-0           counts=True  expected=True
OK  V2 backtick fence        counts=False expected=False
OK  V3 tilde fence           counts=False expected=False
OK  V4 4-backtick fence      counts=False expected=False
OK  V5 unclosed fence        counts=False expected=False
OK  V6 after closed fence    counts=True  expected=True
OK  V7 indented 4sp          counts=False expected=False
OK  V8 bullet                counts=False expected=False
OK  V9 empty reason          counts=False expected=False
OK  V10 html comment         counts=False expected=False
OK  V11 inline backticks     counts=False expected=False
OK  V12 mid-line             counts=False expected=False

$ bash tests/hooks/advisory-nudge/test_menu_mutation_tier.sh   # (d5) 블록
PASS=76 FAIL=0

픽스 없는 트리 대조 — 픽스처가 실제로 방어하는지는 픽스가 있는 트리에서 통과하는
것으로 증명되지 않는다. 픽스 이전 트리(f7cb4c6)를 그대로 꺼내 새 픽스처만 얹으면,
새로 막은 케이스만 정확히 깨지는 것이 방어력의 오라클이다.

$ T="$(mktemp -d)"; git archive f7cb4c6 | tar -x -C "$T"
$ cp tests/hooks/advisory-nudge/test_menu_mutation_tier.sh "$T/tests/hooks/advisory-nudge/"
$ cd "$T" && bash tests/hooks/advisory-nudge/test_menu_mutation_tier.sh
FAIL [advisory→rc=0,stderr=empty] backtick fence does not count
FAIL [block→rc=0,stderr=empty]    strict: backtick fence blocks
FAIL [advisory→rc=0,stderr=empty] tilde fence does not count
FAIL [advisory→rc=0,stderr=empty] 4-backtick fence does not count
FAIL [advisory→rc=0,stderr=empty] unclosed fence does not count
FAIL [advisory→rc=0,stderr=empty] html comment does not count
FAIL [advisory] nudge is emitted on the model-visible channel
PASS=69 FAIL=7

깨진 7건이 이 두 커밋이 새로 막은 것 전부이고, 짝 대조는 옛 트리에서도 통과한다 —
marker after closed fence counts(기능을 죽이지 않았다), indented·inline backticks
(원래도 제외됐다), silent menu emits no decision JSON(옛 트리는 stdout 이 비었다).
대조가 함께 깨졌다면 픽스가 아니라 픽스처가 틀린 것이다.

Evidence 12 — advisory 가 모델이 읽는 채널로 나간다

이 훅의 기본 경로는 stderr 전용이었고, stderr 는 모델에 도달하지 않는다
(CONTRIBUTING.md:304-309). advisory 가 요구하는 행동의 수행자가 메뉴를 작성하는
에이전트이므로, 그 상태의 기본 경로는 요구한 변경을 만들어낼 수 없었다. 오라클은
실제 stdout 이다 — 코드가 아니라 프로세스가 무엇을 내보내는지가 채널 주장의 근거다.

$ ./hooks/advisory-nudge/menu-mutation-tier-advisory/impl.py < <사건 메뉴 payload>
{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "ask",
 "permissionDecisionReason": "[advisory] AskUserQuestion approval menu offers no non-mutating tier. ..."}}
rc=0

짝 대조를 함께 고정했다 — 침묵해야 하는 메뉴에서 stdout 이 비어야 한다. 이게 없으면
항상 ask 를 뱉는 구현도 위 단언을 통과하므로 채널 주장이 무의미해진다.

$ <preview 옵션이 있는 payload> | ./hooks/.../impl.py
(stdout 없음)
rc=0

$ bash tests/hooks/advisory-nudge/test_menu_mutation_tier.sh   # (d6) 블록
PASS [advisory] nudge is emitted on the model-visible channel
PASS [pass]     silent menu emits no decision JSON
PASS=76 FAIL=0
History
  • rev 7 (26392c6) — feat(hooks): advisory for n=1 quantitative claims #969 머지로 origin/main 이 09181e8 로 이동해 rebase 했다.
    이 PR 자신의 변경 파일 중 rebase 로 내용이 바뀐 것은 레지스트리·문서 4개
    (hooks/manifest.json, ARCHITECTURE.md, docs/hook/INDEX.md,
    docs/hook-operating-matrix.md) 뿐이고, 훅 구현과 픽스처는 바이트 동일하다.
    그래서 행 7(생성물·등록)만 새 SHA 에서 다시 쟀고 — wrapper 경유 발화와 4개
    platform 등록 건수를 재측정 — 나머지 행은 c41c285 측정을 유지한다. 행 8 은
    이 커밋의 CI test job 이 근거다. Unverified 의 codex 3건을 fix(hooks): close menu tier advisory vocabulary coverage gaps #974 로 이월했다.

  • rev 6 (c41c285) — origin/main 5efc14c(fix(hooks): guard session state read-modify-write #965 머지) 위로 rebase. rebase 는 커밋을
    다시 쓰므로 아래 rev 5·4 의 SHA 는 더 이상 존재하지 않는다: 펜스 픽스는 19200e0,
    채널 픽스는 c41c285 다. 생성물을 재생성했고(build-plugin-manifests.py, 변경 0건)
    진입점 전체를 새 트리에서 다시 돌려 Evidence 8 을 재측정치로 교체했다 — 이번 rev 는
    vintage 없이 전부 c41c285 기준이다. 이 훅은 세션 상태를 쓰지 않으므로(_paths·
    session_id·파일 쓰기 없음) fix(hooks): guard session state read-modify-write #965 가 추가한 동시성 판정 기준에 걸리지 않는다.

  • rev 5 (ab08b7d → rebase 후 c41c285) — CodeRabbit CR4 / codex F1 적용. 앞선 rev 에서 이 지적을
    Not fixed 로 반려했던 근거가 사실이 아니었음을 정정한다
    : "additionalContext
    사용 0개" 라고 적었으나 hooks/_lib/_hook_io.py 의 공용 emit_decision 을 17개
    훅이 쓰고, 형제 output-block-falsify-advisory 는 같은 PreToolUse(AskUserQuestion)
    표면에서 그것을 쓴다. stderr 전용인 이 훅이 이탈자였다. 행 12 추가, 스위트 74 → 76.

  • rev 4 (88c4044 → rebase 후 19200e0) — CodeRabbit 라운드-2 1건 적용(펜스·HTML 주석 안의 사유 마커가
    advisory 를 억제하던 문제). 행 11 추가, 훅 스위트 65 → 74. Evidence 8 의 스위트
    수치는 이 커밋에서 재측정하지 않았다 — 아래 Unverified 에 vintage 를 적었다.

  • rev 3 (f7cb4c6) — 커밋 1→4 분할 + origin/main 위로 rebase. 증거는 재실행하지
    않았다: 검증 경로 전체에 대해 git diff --quiet 0a1b8ee f7cb4c6 -- <검증 경로>
    가 rc=0 이라 트리 내용이 동일하고, 분할은 커밋 경계만 옮겼기 때문이다. SHA 필드만
    갱신했다. 분할 후 hooks/_lib/block_message.py 만 담은 중간 커밋(fe7ad79)과 등록
    번들 커밋(8b5024e) 각각에서 게이트를 돌려 rc=0 을 확인했다.

  • rev 2 (0a1b8ee) — CodeRabbit 라운드-1 4건 처리 후. 3건 적용(포기/저-blast 순서,
    사유 마커, 문서 술어 정렬), 1건 미적용(advisory 를 additionalContext 로 내보내는
    건 — 34개 advisory 훅 중 32개가 stderr 를 쓰는 레포 전체 계약 사안이라 이 PR
    단독으로 바꾸지 않음. 해당 스레드는 열어 둠). 행 9·10 추가, 훅 스위트 57 → 65.

  • rev 1 (b34ac92) — 최초 앵커. codex 리뷰 라운드-1 3건을 적용한 뒤의 상태.

@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: 4

🤖 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 `@hooks/_lib/block_message.py`:
- Around line 174-178: Align the documentation with the runtime mutation-tier
predicate: require at least two non-abandonment candidates, at least one
recognized mutation signal, and no recognized low-blast alternative. Update the
checklist wording at hooks/_lib/block_message.py lines 174-178 to include
low-blast alternatives, and revise the architecture index entry at
ARCHITECTURE.md line 208 to state the same predicate.

In `@hooks/advisory-nudge/menu-mutation-tier-advisory/impl.py`:
- Around line 296-304: Update the question-text collection around the options
loop to inspect question-level fields such as question and header before
applying the tier predicate. Define and use a stable reason marker in the
question body so a documented safe-tier-unavailable explanation suppresses the
advisory, preserving distinct default-mode and strict-mode behavior with
coverage for both.
- Around line 325-330: Update the advisory decision logic around the low-blast
and abandonment checks to filter abandonment options before evaluating low-blast
signals. Treat abandonment options as neither candidates nor low-blast
alternatives, while preserving the existing minimum-candidate and mutation
checks. Add a regression case covering an option whose text matches both
abandonment and low-blast tokens.
- Around line 411-412: Update the standalone advisory return path around
ADVISORY_MSG so it emits the default advisory as JSON on stdout through
hookSpecificOutput.additionalContext, including hookEventName set to
"PreToolUse", instead of writing only to sys.stderr. Preserve the successful
return status and direct invocation behavior used by the generated wrappers.
🪄 Autofix

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: 486ce841-8083-44dd-b81c-72cad18280e1

📥 Commits

Reviewing files that changed from the base of the PR and between ddea2e3 and b34ac92.

📒 Files selected for processing (15)
  • .claude-plugin/hooks/hooks.json
  • .cursor-plugin/hooks/hooks.json
  • .opencode/hooks/hooks.json
  • ARCHITECTURE.md
  • docs/bypass-vars.md
  • docs/hook-operating-matrix.md
  • docs/hook/INDEX.md
  • docs/hook/menu-mutation-tier-advisory.md
  • hooks/_lib/block_message.py
  • hooks/advisory-nudge/menu-mutation-tier-advisory/impl.py
  • hooks/advisory-nudge/menu-mutation-tier-advisory/spec.md
  • hooks/manifest.json
  • hooks/menu-mutation-tier-advisory.sh
  • plugins/praxis/.codex-plugin/hooks/hooks.json
  • tests/hooks/advisory-nudge/test_menu_mutation_tier.sh

Comment thread hooks/_lib/block_message.py Resolved
@devseunggwan

Copy link
Copy Markdown
Owner Author

Verification updated — 0a1b8ee rev 2 · CodeRabbit 라운드-1 반영으로 행 9(포기+저-blast 중첩)·10(Safe-tier-unavailable: 마커) 추가, Evidence 8 을 커밋된 트리 기준 재측정치로 교체 → #966 (comment)

@devseunggwan
devseunggwan force-pushed the issue-963-feat-nonmutating-tier-in-menus branch from 0a1b8ee to f7cb4c6 Compare August 12, 2026 09:35
@devseunggwan

Copy link
Copy Markdown
Owner Author

Verification updated — f7cb4c6 rev 3 · 커밋 1→4 분할 + origin/main rebase 로 HEAD 이동, 검증 경로는 git diff --quiet 0a1b8ee f7cb4c6 -- <검증 경로> rc=0 으로 무변경이라 SHA 필드만 갱신(재실행 없음) → #966 (comment)

@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 `@hooks/advisory-nudge/menu-mutation-tier-advisory/impl.py`:
- Around line 290-294: Update the marker-detection logic around the
question-text scan to track fenced-code state, toggling on lines whose trimmed
content begins with either ``` or ~~~ and skipping those fence lines and all
enclosed content. Only evaluate _REASON_MARKER when outside a fence, and add
regression coverage for both default and strict modes confirming markers inside
fenced blocks do not suppress the advisory or strict-mode block.
🪄 Autofix

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: 061c4284-de84-442a-b982-23d8727106d7

📥 Commits

Reviewing files that changed from the base of the PR and between b34ac92 and f7cb4c6.

📒 Files selected for processing (6)
  • ARCHITECTURE.md
  • docs/hook/INDEX.md
  • hooks/_lib/block_message.py
  • hooks/advisory-nudge/menu-mutation-tier-advisory/impl.py
  • hooks/advisory-nudge/menu-mutation-tier-advisory/spec.md
  • tests/hooks/advisory-nudge/test_menu_mutation_tier.sh
🚧 Files skipped from review as they are similar to previous changes (3)
  • hooks/_lib/block_message.py
  • ARCHITECTURE.md
  • docs/hook/INDEX.md

@devseunggwan

Copy link
Copy Markdown
Owner Author

Verification updated — 88c4044 rev 4 · CodeRabbit 라운드-2(펜스·HTML 주석 안의 사유 마커가 advisory 를 억제)를 적용해 행 11 추가, 훅 스위트 65 → 74; Evidence 8 의 진입점 수치는 0a1b8ee 측정분이라 vintage 를 명시 → #966 (comment)

@devseunggwan

Copy link
Copy Markdown
Owner Author

Verification updated — ab08b7d rev 5 · CodeRabbit CR4 / codex F1 적용(기본 advisory 를 stderr 전용에서 모델이 읽는 emit_decision("ask", …) 로), 행 12 추가, 스위트 74 → 76; 앞선 rev 의 Not fixed 반려 근거였던 "additionalContext 사용 0개" 가 사실이 아니었음을 History 에 정정 → #966 (comment)

@devseunggwan
devseunggwan force-pushed the issue-963-feat-nonmutating-tier-in-menus branch from ab08b7d to c41c285 Compare August 12, 2026 12:52
@devseunggwan

Copy link
Copy Markdown
Owner Author

Verification updated — c41c285 rev 6 · origin/main 5efc14c 위로 rebase 후 진입점 전체 재측정(594 passed / ALL TESTS PASSED / EXIT=0, SKIPPED 0)으로 Evidence 8 의 vintage 해소; 행 11 에 픽스 없는 트리 대조(git archive f7cb4c6 + 새 픽스처만 → PASS=69 FAIL=7, 새로 막은 케이스만 정확히 실패) 추가 → #966 (comment)

AskUserQuestion 차단 시 출력되는 verb gate 체크리스트에 mutation-tier 축 한 항목을
추가한다. `_VERB_CHECKLISTS["AskUserQuestion"]` 블록에 append 만 했고 기존 항목의
문구·순서는 건드리지 않았다.

이 항목이 없으면 tests/test_block_message.py 의 레지스트리 대조가 깨진다 — manifest 에
등록된 PreToolUse(AskUserQuestion) 훅이 전부 이 문자열에 이름으로 나와야 한다. 즉
훅 등록과 이 파일은 결합돼 있지만 방향이 한쪽뿐이라(등록 ⊆ 체크리스트) 체크리스트가
먼저 들어오는 것은 안전하고, 그래서 등록 번들과 분리해 여기 먼저 둔다.

Confidence: high
Premise-Verified: 이 커밋 내용만 워킹트리에 둔 상태로 게이트 2종 실행 —
 scripts/check-plugin-manifests.py rc=0, tests/test_block_message.py 19 passed
Not-tested: 없음 (체크리스트 문자열 변경, 런타임 판정 무영향)
Scope-risk: narrow
Session-Id: e524eb56-5da2-443c-9ccf-f8e4175674db
승인 메뉴의 후보가 전부 같은 mutation 티어에 있으면 사용자가 고른 것은 "할지 말지"가
아니라 "얼마나 할지"다. AskUserQuestion PreToolUse 에서 그 형태를 잡아 안전 티어 한
칸을 넣거나 불가능한 사유를 적으라고 advisory 로 알린다. prod 가 유일한 경로인 경우가
실제로 있으므로 차단이 아니라 권고가 기본값이고, strict 는 opt-in 이다.

관심사가 넷(훅 구현 / manifest 등록 / 생성물 재생성 / 문서)이지만 한 커밋에 둔다 —
쪼개면 중간 커밋이 CI 게이트를 통과하지 못한다. scripts/check-plugin-manifests.py 의
Rule 1 이 디렉터리↔manifest 를 양방향으로 대조하고, Rule 6 이 wrapper 바이트 동일성을,
Rule 7 이 INDEX.md·ARCHITECTURE.md 등재를, Rule 17 이 bypass-vars.md 행을 각각
manifest 항목과 묶는다. 원자적 커밋 규약의 전제인 "모든 커밋은 빌드·테스트 가능"이
분할 선호보다 앞서므로, 이 번들은 레포 불변식이 정한 최소 단위다. 실제로 분리 가능했던
hooks/_lib/block_message.py 는 앞 커밋으로 떼어냈다.

Confidence: high
Premise-Verified: 훅 디렉터리만 워킹트리에 둔 상태에서 게이트 실행 →
 "UNREGISTERED hooks/advisory-nudge/menu-mutation-tier-advisory: directory exists
 but no manifest.json entry" 로 실패, 분리 불가를 실측으로 확인; 픽스처 65 passed
Not-tested: 실제 Claude Code 런타임이 AskUserQuestion 시점에 이 wrapper 를 호출하는
 것은 미확인 — 등록 사실까지만 확인, 머지 후 fire-ledger 로 관측 가능
Scope-risk: narrow
Session-Id: e524eb56-5da2-443c-9ccf-f8e4175674db
CodeRabbit 라운드-1 두 건. 둘 다 `_question_triggers` 의 계약을 고치므로 한 커밋에
둔다 — 파일·docstring·픽스처 블록이 서로 맞물려 있어 쪼개면 중간 커밋이 빌드되지
않는다. 세 번째 지적(문서 술어 드리프트)은 파일이 분리되므로 별도 커밋.

(1) 포기 옵션을 저-blast 판정보다 먼저 걸러낸다. `skip this run and review later`
는 포기 토큰과 저-blast `review` 를 동시에 갖는다. 저-blast 를 전체 옵션에 대해
먼저 읽던 순서 때문에 이 옵션 하나가 전부-prod 메뉴를 strict 에서도 침묵시켰다.
spec 이 포기를 "후보도 티어도 아니다" 로 정의하므로 두 질문 중 어느 것도 묻기 전에
제거하는 것이 맞다.

(2) `Safe-tier-unavailable: <사유>` 마커를 질문 본문에서 읽어 해당 질문의 advisory
를 억제한다. advisory 는 "안전 옵션을 넣거나, 불가능한 사유를 적어라" 둘 중 하나를
요구하는데 후자를 기록할 방법이 없어, strict 에서는 옵션 추가 외에는 통과할 수 없는
게이트였다. 형태는 형제 훅 output-block-falsify-advisory 의 `Falsified:` 마커를
그대로 미러링한다 — 자기 줄 column 0, startswith, 콜론 뒤 내용 비어있지 않을 것.
질문 단위로 읽으므로 q1 의 사유가 q2 를 덮지 않는다.

픽스처 8건 추가 (d3/d4), 65/65 통과.

Confidence: high
Premise-Verified: 두 건 다 수정 전 payload 로 재현 — overlap 폼
 `["deploy to prod now","deploy to prod partially","skip this run and review later"]`
 이 strict rc=0(침묵)이었고 수정 후 rc=2; 마커 형태는
 output-block-falsify-advisory/impl.py:325 `line.startswith("Falsified:")` 확인
Not-tested: 마커의 실사용 채택률(작성자가 실제로 사유를 적는지)은 배포 후 관측 대상
Scope-risk: narrow
CodeRabbit 라운드-1 세 번째 지적. AskUserQuestion 게이트 체크리스트와 두 인덱스가
"모든 후보가 mutation 신호를 갖는다" 로 적혀 있었는데, 런타임은 포기 옵션을 제외한
후보 2개 이상 + 그 중 1개 이상 mutation + 저-blast 0개를 요구한다. spec.md 에는
이 divergence 를 명시했으나 나머지 세 표면에 전파하지 않아 드리프트가 남았다.

체크리스트가 권위 있게 읽히는 자리라 술어를 틀리게 적는 것은 안 적는 것보다 나쁘다.
`Safe-tier-unavailable:` 마커도 함께 안내한다.

Confidence: high
Premise-Verified: 세 표면 문구를 impl.py `_question_triggers` 본문과 1:1 대조 —
 candidates 필터 → 저-blast → len>=2 → any mutation; 체크리스트 회귀는
 tests/test_block_message.py 19 passed
Not-tested: 없음 (문서 문구 변경, 런타임 무영향)
Scope-risk: narrow
CodeRabbit 라운드-2. 펜스 블록 안의 예시가 컬럼 0에 놓이므로, 마커를 문서화하는
행위 자체가 그 마커를 요구하는 advisory 를 침묵시켰다. spec.md 와 impl.py 주석이
둘 다 이미 "펜스는 세지 않는다" 라고 적어둔 상태였으므로 코드가 자기 계약을 어긴
것이고, 동시에 strict 차단 우회 경로였다.

지적된 펜스만 막지 않고 마커 입력 표면을 열거해 각각을 픽스처로 만들었다
(praxis:surface-enumeration). 컬럼 0에 줄을 놓으면서 독자에게는 사유로 보이지
않는 래퍼가 대상이다 — 백틱/틸드 펜스(길이 무관), 미종료 펜스, HTML 주석,
들여쓰기, 인라인 백틱. 미종료 펜스가 나머지 본문을 삼키는 것은 의도다: 펜스를 연
작성자는 예시를 보이는 중이지 사유를 진술하는 중이 아니다.

짝 대조를 함께 고정했다 — 닫힌 펜스 뒤에 오는 진짜 마커는 여전히 인정된다.
이게 없으면 우회가 아니라 기능 자체를 죽이는 수정이 된다.

픽스처 9건 추가 (d5), 65 → 74 통과.

Confidence: high
Premise-Verified: 수정 전 payload 로 재현 — 펜스 안 마커로 strict rc=0(침묵),
 수정 후 rc=2; 열거한 변형 12종을 _has_reason_marker 에 직접 먹여 12/12 기대치
 일치 확인; spec.md:115-120 과 impl.py:282 주석이 이미 펜스 제외를 명시하고
 있었음을 원문으로 확인
Not-tested: 마커 앞뒤로 중첩된 펜스(펜스 안의 펜스)는 열거하지 않았다 — 질문
 본문에서 발생 가능성이 낮고, 발생해도 바깥 펜스가 전체를 삼켜 fail-closed 다
Scope-risk: narrow
Session-Id: e524eb56-5da2-443c-9ccf-f8e4175674db
CodeRabbit CR4 와 codex F1 이 같은 지점을 독립적으로 지적했고, 내가 처음에 근거를
잘못 세워 반려했던 건이다. 반려 근거는 "advisory 훅 34개 중 32개가 stderr,
additionalContext 사용 0개" 였는데 **0개가 아니었다** — `hooks/_lib/_hook_io.py` 에
공용 `emit_decision` 헬퍼가 있고 17개 이상이 쓴다. 특히 형제
`output-block-falsify-advisory` 는 같은 PreToolUse(AskUserQuestion) 표면에서
`emit_decision("ask", ...)` 를 쓴다. 즉 stderr 전용인 이 훅이 이탈자였다.

기능적으로도 결함이었다. 이 advisory 가 요구하는 행동(안전 옵션 추가 또는 사유
기재)의 수행자는 메뉴를 작성하는 에이전트인데, `CONTRIBUTING.md` 의 "Advisory
output is not visible to the model" 이 stderr 는 모델에 도달하지 않는다고 명시한다.
따라서 기본 경로는 요구한 변경을 만들어낼 수 없는 상태였다.

기본 경로를 `emit_decision("ask", ...)` 로 바꾼다. stderr 는 터미널을 보는 사람을
위해 그대로 둔다. strict 는 exit 2 + stderr 유지 — 차단은 런타임이 종료 코드로 읽는다.

픽스처 2건 추가 (d6): 발화 시 stdout 에 permissionDecision=ask 가 나오는지, 그리고
짝 대조로 침묵 시 stdout 이 비는지. 후자가 없으면 항상 ask 를 뱉는 구현도 통과한다.
74 → 76 통과.

Confidence: high
Premise-Verified: `grep -rl additionalContext hooks/` 로 반려 근거를 반증(0개가
 아니라 _hook_io.py 포함 다수); `grep -rln emit_decision hooks/*/*/impl.py` 17개;
 output-block-falsify-advisory/impl.py:646 이 같은 matcher 에서 emit_decision("ask")
 사용 확인; CONTRIBUTING.md:304-309 원문 확인; 실제 실행으로 stdout JSON 확인
Not-tested: 실제 Claude Code 런타임이 이 ask 결정을 받아 사용자에게 프롬프트를
 띄우는 것까지는 미확인 — payload 계약 형태만 형제와 바이트 동일하게 맞췄다
Scope-risk: moderate
Session-Id: e524eb56-5da2-443c-9ccf-f8e4175674db
@devseunggwan

Copy link
Copy Markdown
Owner Author

Verification updated — 26392c6 rev 7 · #969 머지로 origin/main 이 이동해 rebase 했고, 이 PR 자신의 변경 파일 중 레지스트리·문서 4개만 union 으로 바뀌어 행 7 을 새 SHA 에서 다시 쟀습니다(훅 구현·픽스처는 바이트 동일). 행 8 의 근거를 stale 로컬 실행에서 이 커밋의 CI job 으로 교체했고, Unverified 의 codex 어휘 3건을 #974 로 이월했습니다 → #966 (comment)

@devseunggwan
devseunggwan merged commit 3efa1ed into main Aug 12, 2026
10 checks passed
@devseunggwan
devseunggwan deleted the issue-963-feat-nonmutating-tier-in-menus branch August 12, 2026 13:44
devseunggwan added a commit that referenced this pull request Aug 15, 2026
…ion (#1016)

* fix(menu-tier): gate create/update on shared surface, cancel on mutation

Closes the two reproducible vocabulary/classification gaps codex round-1
found on PR #966, and records the third as deliberately open.

Gap 1 — `create` / `update` / `생성` / `갱신` were in no vocabulary set, so a
menu whose every option mutates ("Create the customer record" / "Update the
customer record") was silent with no high-blast target present. They now enter
a conditional Tier 1c: a mutation signal only when the option also names a
shared surface (SHARED_SURFACE_NOUNS) and not a local authoring artifact
(LOCAL_ARTIFACT_NOUNS).

The unconditional widening the issue sketched was built and rejected on
measurement: it fired on "Create a new test file" / "Update the existing test",
"Create a README section" / "Update the changelog", "문서 생성" / "문서 갱신",
and "Create a shorter title" / "Update the wording". Since PR #966 rev 5 the
default path is emit_decision("ask", …), so each of those is a human
confirmation prompt, not a log line — which also corrects the now-stale
"a false fire costs one sentence" rationale in spec.md. Six nouns
(`schema`, `index`, `namespace`, `migration`, `dag`, `policy`) were drafted
into the gate and removed after they fired on ordinary authoring menus.

Gap 2 — "Cancel the prod deployment" was misclassified as the do-nothing tier,
so cancel-vs-proceed on prod went silent although both options change prod.
Not a vocabulary hole: the option already classified as mutating via `prod`,
but _question_triggers strips abandonment at step 1, before step 4 asks the
mutation question, so the survivor fell below the two-candidate floor. `cancel`
/ `취소` move to CONDITIONAL_ABANDON_*, abandoning only when the option carries
no other mutation signal. A bare "Cancel" is still the do-nothing tier.

That rule has its own reverse false fire, measured: a no-go naming its object
("Cancel — do not deploy to prod") would be promoted to a candidate. An
explicit negation overrides it, read only inside the Tier 0b branch — a global
`do not` was tried and rejected because it silenced "Deploy to prod and notify"
/ "Deploy to prod but do not notify", where the negation attaches to a rider.
Blast radius of the whole gap-2 change is therefore one word: no option without
`cancel` / `취소` changes classification.

Gap 3 — the issue's task-1 gate asked whether anything remains after anchor
row 4 closed the compound-option TARGET axis. It does: the VERB axis. "Dry-run
then delete the customer table" / "Delete the customer table" is silent in both
modes, while the byte-identical payload with `prod` inserted fires (strict
rc=2). The verb-axis discriminator was built and rejected — it closes all four
residual cases and simultaneously fires on "Deploy now" / "Dry-run the deploy",
"Merge now" / "Simulate the merge", "Send the announcement" / "Report-only pass
on the send", and "지금 배포" / "배포 드라이런". A dry run necessarily names the
verb it simulates, so those are the same shape as the residual and no lexical
rule separates them; firing an `ask` at an author who already added the safe
tier inverts the hook's purpose. Documented in spec.md with its reproduction
and pinned in fixtures — the residual as `pass`, the four counter-cases as
must-stay-silent — so a future round fails there instead of shipping the trade
blind.

Evidence. Pre-fix: both repros silent, both same-shape positive controls
(delete/truncate; roll-back/proceed) fire. Post-fix: repros fire EN and KO,
advisory and strict, controls unchanged. A-B against a `git show HEAD:` copy
over 27 cases flips exactly the four issue repros, all silent→FIRE; nothing
loud went silent. All 76 pre-existing fixtures pass unchanged (76→110). The new
positives fail against the pre-fix impl (103/7) and pass against the patched
one, so they pin the fix rather than the harness.

Known and shipping unfixed, recorded in spec.md: "Create a comparison table in
the README" / "Update the existing table" now fires — the veto is per option
and the second names no artifact. Both noun sets are my enumeration, not a
measured corpus; a surface I failed to list is a silent miss.

Not-tested: runtime firing inside Claude Code; Korean coverage is synthetic;
shellcheck unavailable in this environment.
Confidence: medium

Refs #974 (gaps 1 and 2; gap 3 documented as open)

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014Q4o2BtBPpsrr19he6qVpc

* style(docs): rewrap issue ref off the line start

A wrapped sentence left an issue reference at column 0, and markdownlint reads
that shape as a heading (MD018). Nothing rendered wrong — CommonMark requires a
space after the hash — but the rule is not among the four the repo disables, and
reviewdog's suggested fix would have inserted that space and turned prose into a
real heading. Moving the previous line's last word down silences the rule
without touching a word of the text.

Confidence: high
Session-Id: 9e3b4abb-9995-41aa-8c70-4c2be1bb61ba

---------

Co-authored-by: Claude <noreply@anthropic.com>
devseunggwan added a commit that referenced this pull request Aug 22, 2026
* fix(menu-tier): close gap 3 for destructive-verb sequences

이슈 #974 gap 3(PR #966 codex 라운드-1 세 번째 지적)를 닫는다. PR #1016은
이 잔여(`Dry-run then delete the customer table` / `Delete the customer
table`가 두 모드 모두 침묵)를 재현하고 넓은 수정(safe MODE + 아무 mutation
동사나 ⇒ non-low-blast)을 만들었다가 `Deploy now` / `Dry-run the deploy`,
`Merge now` / `Simulate the merge`, `Send the announcement` /
`Report-only pass on the send`, `지금 배포` / `배포 드라이런` — 이 훅이
메뉴에 담기를 바라는 정확한 단일절 dry-run 대안 4건에서 오발화해 기각하고,
d9 픽스처로 현재(결함 있는) 동작을 고정했다.

재현 확인(현재 impl.py, 수정 전):
  $ python3 impl.py < gap3.json   # Dry-run then delete the customer table
  (침묵, rc=0)                    # / Delete the customer table
  $ python3 impl.py < gap3ctrl.json  # 동일 구조 + prod
  [advisory] ...                  # (advisory 발화, strict rc=2) — 잔여가 실재함을 증명

파괴적 동사(delete/drop/truncate/삭제)로 범위를 좁힌 Tier 1e를 추가했다 —
같은 옵션 안에서 safe-MODE 토큰과 공유 표면을 지칭하는 파괴적 동사가
연결어(`then` / ` 후 `)로 이어지면 두 번째 절이 무조건 실행되는 것으로 보고
low-blast 판정을 취소한다. PR #1016이 기각한 4건 반례는 전부
deploy/merge/send를 쓰고 파괴적 동사를 쓰지 않아 좁힌 규칙에 걸리지 않는다
— 4건 모두 재측정해 여전히 침묵함을 확인했다. `merge`/`deploy`/`send` 등
나머지 Tier 1b 동사는 의도적으로 Tier 1e 밖에 남긴다.

수정 후 재현:
  $ python3 impl.py < gap3.json
  [advisory] ... rc=0 (advisory)
  $ PRAXIS_MENU_MUTATION_TIER_STRICT=1 python3 impl.py < gap3.json
  BLOCKED: ... rc=2

거짓양성 대조(신규 판별식 자체에 대한):
  - `Dry-run then delete the test fixture` — LOCAL_ARTIFACT 베토로 침묵 유지
  - `Delete now` / `Dry-run the delete` (연결어 없음) — 침묵 유지

테스트: tests/hooks/advisory-nudge/test_menu_mutation_tier.sh PASS=113
FAIL=0 (기존 110건 전수 재확인, 잔여 3건 → advisory×2+strict-block×1로
치환, 반례 4건 재측정 유지, 신규 거짓양성 대조 2건 추가).
python3 scripts/check-plugin-manifests.py → "plugin-manifest check OK".
shellcheck tests/hooks/advisory-nudge/test_menu_mutation_tier.sh → clean.

Refs #974

Confidence: medium
Not-tested: runtime firing inside Claude Code; Korean coverage is synthetic; shellcheck ran clean but no live-session traffic validation of the new discriminator

* fix(menu-tier): judge tier 1e per clause, not per option

Codex P1 (PR #1072). 앞 커밋의 Tier 1e 는 연결어·파괴적 동사·공유
표면이 한 옵션에 함께 있기만 하면 탈락시켰다. 그래서
`Dry-run the delete operation, then inspect the customer table` —
삭제가 dry-run 의 목적어이고 뒷절은 조회뿐인 안전한 옵션 — 까지
탈락해, strict 모드가 정상 메뉴를 차단했다. 훅의 목적과 정반대다.

연결어로 절을 쪼개고, low-blast 토큰이 없는 절에 파괴적 동사가
있을 때만 탈락시킨다. 순서 특례가 사라진다 —
`Delete the table, then dry-run to confirm` 은 첫 절에서 걸린다.

수정 전 오차단 재현: 위 입력이 default advisory / strict rc=2.
수정 후 침묵하고, gap 3 두 형태와 역순은 계속 발화한다.
PR #1016 이 기각한 반례 4건과 기존 대조군 2건도 재측정해 침묵 유지.

테스트 115/115 (회귀 fixture 2건 추가: P1 입력, 역순).

Confidence: high
Not-tested: 런타임 발화; 한국어 커버리지는 합성 입력
Session-Id: 986b3ff6-861d-4339-9c8a-4442f03ed2df
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(hooks): require a non-mutating tier in shared-state approval menus

1 participant