feat(cli): --help 에서 deprecated 서브명령을 별도 구획으로 분리한다

[ictechgy]

문제

context-guard --help 는 새 사용자가 가장 먼저 읽는 표면인데, 27개 서브명령을 설명 없이 한 덩어리로 나열하면서 0.14.0 이 deprecated 로 표시한 다섯 헬퍼를 "Common subcommands" 안에 두고 있었다. help 출력 41줄에 deprecat 문자열이 한 번도 나오지 않았다.

왜 상수인가

각 헬퍼는 이미 자기 소스에 [deprecated] 표식을 갖고 있다(context_compress.py, context_filter.py, context_pack.py, tool_schema_pruner.py, statusline.sh, statusline_merged.sh). 그러나 디스패처는 헬퍼를 import 하지도 실행하지도 않고 명령 매니페스트를 데이터로만 읽는다. 이는 docs/safety-reference.md 가 명시한 신뢰 경계다. 따라서 목록은 상수일 수밖에 없고, 상수와 헬퍼가 갈라지는 것이 유일한 위험이라 그것만 정확히 막는 테스트를 함께 넣는다.

결과

Common subcommands:
  artifact / audit / bench / cache-score / cost / diet / doctor / failed-nudge
  guard-read / hooks / mcp / read-symbol / reference / rewrite-bash / sanitize
  sanitize-output / scan / setup / task-memory / trim / trim-output

Deprecated, still shipped (see docs/guide.md before using):
  compress / filter / pack / statusline / statusline-merged / tool-prune

모든 서브명령은 여전히 정확히 한 번 나온다(테스트로 고정).

드리프트 가드

tests/test_cli_deprecation_surface.py 는 배포되는 plugins/context-guard/bin 사본을 읽어 [deprecated] 표식이 있는 헬퍼 집합과 상수가 정확히 일치하는지 검사한다. 매핑이 (helper, *고정인자) 형태인 doctor/reference/scan 은 첫 요소만 본다.

변이 4종이 모두 잡힌다.

변이	결과
집합에서 pack 제거	잡힘
비-deprecated 인 audit 추가	잡힘
help 를 한 덩어리로 되돌리기	잡힘
매니페스트에 없는 이름 추가	잡힘

의도적으로 하지 않은 것

context_pack.py:6343 의 "P3 live-evidence contract 가 핀해서 계속 배포한다" 는 문구는 고치지 않았다. 확인해 보니 허위가 아니라 불완전한 서술이다. P3 v4 가 canonical_packer 로 실제로 핀하는 것은 맞고, 동시에 Stage-2 protected-surface manifest 도 같은 파일을 lstat 으로 잡고 있어 P3 를 풀어도 삭제되지 않는다. 그 한 줄을 고치려면 보호 표면과 P3 두 캐스케이드를 모두 돌려야 해서 비용이 이득보다 크다.

검증

tests.test_cli_deprecation_surface + stage2   Ran 13 OK, exit 0
scripts/ci_test_gate.py fast                  Ran 76 OK, exit 0
실제 3.11 compileall                          exit 0
scripts/sync_plugin_copies.py --check         plugin copies synchronized
scripts/prepublish_check.py --skip-tests      prepublish check: OK, exit 0
scripts/release_preflight.py                  경고 없음, exit 0

조상 SHA 를 고정하지 않으므로 squash 로 병합해도 된다.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DE3AupXcyv64SEuQeTckSh

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: efa6efc4-efa6-4f83-a161-99b66e2981e2

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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