refactor(plugin): clarify UserPromptSubmit bootstrap architecture

[JeremyDev87]

Summary

The plugin uses two distinct hook layers and the split is not self-documenting:

1. plugin-local hooks/hooks.json — SessionStart, PreToolUse, PostToolUse, Stop
2. global install — hooks/session-start.py writes a UserPromptSubmit entry into ~/.claude/settings.json at every session start

Because UserPromptSubmit is absent from hooks.json, contributors auditing the package repeatedly mistake the missing entry for a bug. This PR clarifies the architecture without changing behavior.

Approach A (document + regression-test) chosen over Approach B (migrate into hooks.json)

• Low risk: no behavior change, comments + docs + tests only
• Preserves global-scope semantics: PLAN/ACT/EVAL/AUTO keyword detection must fire in any Claude Code session, not only inside CodingBuddy projects — plugin-local hooks would narrow that scope
• Parallel-safe with bug(plugin): Stale global ~/.claude/hooks/codingbuddy-mode-detect.py from prior version not cleaned up during v5.3.0 install #1381: keeps file footprint separate from the stale legacy hook migration
• Approach B remains viable as a follow-up once bug(plugin): Stale global ~/.claude/hooks/codingbuddy-mode-detect.py from prior version not cleaned up during v5.3.0 install #1381 lands

Changes

• hooks/hooks.json: top-level \$comment field pointing contributors at session-start.py and the new architecture doc
• hooks/session-start.py: module docstring expanded to name the bootstrap role and two-layer architecture; register_hook_in_settings docstring expanded with the why behind global install
• docs/bootstrap-architecture.md (new): long-form rationale, source-of-truth cheat sheet, drift safeguards, future-simplification notes
• tests/test_bootstrap_architecture.py (new, 18 tests): invariant regression suite covering hooks.json shape, \$comment presence and contents, session-start.py docstring, doc existence and required sections

Test plan

• yarn workspace codingbuddy-claude-plugin lint
• yarn workspace codingbuddy-claude-plugin format:check
• yarn workspace codingbuddy-claude-plugin typecheck
• yarn workspace codingbuddy-claude-plugin test:coverage — 123 passed
• python3 -m pytest tests/ — 766 passed (incl. 18 new bootstrap tests)
• yarn workspace codingbuddy-claude-plugin circular
• yarn workspace codingbuddy-claude-plugin build
• yarn workspace codingbuddy npm audit --severity high
• yarn workspace codingbuddy-claude-plugin npm audit --severity high
• yarn workspace landing-page npm audit --severity high

Verification (RED → GREEN evidence)

Before the changes, 5 bootstrap tests failed + 4 errored (18 total, 9 passing) — confirming the invariants the suite is meant to enforce were not yet in place. After the documentation/comment changes, all 18 pass.

Closes #1380

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
codingbuddy-landing	Ready	Preview, Comment	Apr 5, 2026 1:41pm

[JeremyDev87]

Review: APPROVE

CI Status: PASS

모든 28개 check 통과 — build, lint, typecheck, test, security, circular, e2e (hooks 3.11/3.12, docker), vercel preview 포함.

Local Verification: PASS

yarn workspace codingbuddy-claude-plugin lint       ✅
yarn workspace codingbuddy-claude-plugin typecheck  ✅
yarn workspace codingbuddy-claude-plugin test       ✅ (123/123)
python3 -m pytest tests/                            ✅ (766/766, incl. 18 new)

Severity Findings

• Critical (blocking): 없음
• High (must fix): 없음
• Medium (should fix): 없음
• Low (nice to have): 없음

문서/주석/테스트만 추가하는 순수 non-behavioral 변경이라 런타임 리스크 제로. 코드 품질 이슈 없음 (unused imports/any/dead code/security 모두 clean).

Spec Compliance (#1380 Acceptance Criteria)

• Bootstrap architecture is clearly documented and testable

  • docs/bootstrap-architecture.md (신규, 115 lines): TL;DR 표, two-layer 설명, 글로벌 설치 근거, cheat sheet, 드리프트 세이프가드, 미래 단순화 노트까지 포괄
  • 18개 regression test로 invariant 잠금

• Contributors can tell where UserPromptSubmit is registered

  • hooks/hooks.json에 top-level $comment 필드로 session-start.py / bootstrap-architecture.md / #1380 포인터 제공
  • hooks/session-start.py 모듈 docstring이 bootstrap 역할과 two-layer 구조 명시
  • register_hook_in_settings() docstring에 "왜 글로벌이어야 하는가" 근거(global scope semantics) 포함

• If simplified, single path is explicit and regression-tested

  • PR은 Approach A (문서 + 회귀 테스트) 채택 — 의도적으로 현 아키텍처 유지
  • 근거: global scope semantics 보존, #1381 stale cleanup과 병렬 충돌 방지, 저위험
  • Approach B(단일 경로 마이그레이션)는 #1381 머지 이후 follow-up으로 명시적 연기
  • 선택된 two-layer 상태가 18개 테스트로 잠겨 있어 양방향 드리프트(하나에서 사라지거나 양쪽에 중복) 모두 감지

리뷰어 노트 (정보 공유)

좋은 점:

• 드리프트 양방향 방어: "UserPromptSubmit이 hooks.json에 나타나면 fail" + "session-start.py에서 사라지면 fail" 두 방향 모두 테스트로 잠겨 있어 미래의 silent regression을 확실히 차단
• $comment 컨벤션 일관성: JSON Schema와 동일한 관례를 따르고, 테스트가 그 내용(session-start.py / UserPromptSubmit / bootstrap-architecture 문자열)을 강제해 주석의 의미가 퇴색되는 것도 막음
• 문서의 self-aware 톤: "If you are here because you opened hooks/hooks.json...you are not the first" — 실제 contributor 혼란 포인트를 정면에서 다룸
• Future simplification 섹션: 현 결정이 영구적이지 않음을 명시하고, Approach B로 넘어갈 조건(#1381 머지, Claude Code의 first-class global hook 지원)을 구체적으로 기록

소소한 관찰(블로커 아님, 수정 불필요):

• Python 테스트는 텍스트/구조 invariant만 검증 — register_hook_in_settings()의 런타임 동작(파일 락, 멱등성)은 다른 파일에서 커버되는 것으로 보임. 이 PR 스코프에서는 적절.
• 전체 접근이 "docs-as-code" 패턴을 잘 보여줌 — 향후 유사한 architectural decision에도 재사용할 만함.

Recommendation: APPROVE

스펙 준수 완벽, CI 전체 통과, 로컬 lint/typecheck/test/pytest 전체 통과, 코드 품질 이슈 없음, 회귀 방어 탄탄. 머지 가능.