docs(session): 9차 세션 기록 — 구조 재편 3건 + 재발 방지 도구

CLAUDE.md 관례대로 세션 로그 신설 + 압축 요약 추가.

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

.claude/session/2026-08-13-09-structure-and-guardrails.md

@@ -0,0 +1,83 @@
+# 2026-08-13 아홉 번째 세션 — 구조 재편(luau-test/bind-system/question) + 재발 방지 도구
+
+## 배경
+
+직전 세션(8차 감사)이 끝난 뒤 사용자가 네 가지를 한 번에 요청 — 앞의 셋은
+**"사람이 읽을 수 없는 문서"** 라는 같은 뿌리의 문제이고, 넷째는 그 뿌리를
+없애는 방법에 대한 질문:
+
+1. `luau-test/`가 평평해서 "지금 볼 게 뭔지" 못 고르겠음 → 상태별 폴더로
+2. `bind-system-plan.md`가 3000줄이라 검토 불가 + 한 곳 실수의 파급이 큼
+   → 쪼개도 되는지 판단 요청("이대로 둬야 해요?")
+3. `question.md`에 해결된 게 많아 필터가 안 됨 → archive로
+4. **"이런 깊은 감사를 재발 방지하는 방법이 있나"**
+
+## 1. `luau-test/` — 폴더가 곧 상태
+
+파일 21개를 4폴더로: `review-required/`(1, 사람 결정) /
+`rewrite-required/`(3, 스파이크 코드가 깨짐) / `not-run/`(1+헬퍼, Studio 전용) /
+`done/`(15). STATUS.md를 폴더 구조 그대로 재작성하고 **"파일을 옮기는 게 곧
+상태 갱신"** 을 규칙으로 명시.
+
+부수적으로 중요한 결정: 폴더가 상태라 파일이 옮겨 다니므로 **다른 문서는
+경로가 아니라 파일명으로 참조**하도록 6곳 정규화 — 안 그러면 상태를 바꿀
+때마다 링크가 깨져 stale이 또 쌓임.
+
+## 2. `bind-system-plan.md` 분할 — "쪼개되 반만, 나머지는 0-Z 반영과 같이"
+
+**판단**: 쪼개는 게 맞음. 근거는 사용자가 든 것 그대로(검토 불가 + 파급) 이고,
+반대 근거였던 "인바운드 참조 253개"는 실측해보니 절 이름까지 지목한 건
+60곳뿐이라 감당 가능.
+
+다만 **전부 쪼개지는 않음**. 남은 두 덩어리(디스패치 코어 ~1000줄, 반응형
+코어 ~950줄)는 `question.md` 0-Z가 정해지면 **어차피 전면 재작성 대상**이라,
+지금 옮기면 같은 텍스트를 두 번 만지고 인바운드 참조(~37곳)도 두 번 고쳐야
+함. 재작성하는 그 패스에서 파일을 가르는 게 총 변경량과 실수 위험이 모두
+작음 — `dispatch-redispatch-diff-plan.md` 6절에 그 지시를 넣어뒀음.
+
+**1단계(완료, 2989 → 2263줄)**: `ref-plan.md`(509) / `event-plan.md`(103,
+사용자가 직접 지목) / `brand-plan.md`(137). 전부 **순수 이동, 결정 불변**.
+이벤트 *네이밍* 관례만 인스턴스 생성과 한 절에 섞여 있어 쪼개면 양쪽이
+반토막 나므로 원위치 유지(그 사실을 `event-plan.md` 헤더에 명시).
+
+## 3. `question.md` — 사용자가 답할 것만 (525 → 279줄)
+
+`archive/question-resolved.md`에 분리 직전 전문을 보존하고, 본문은
+⭐최우선 2건(0-Y/0-Z) → 결정 대기 2건 → 용어 미확정 6건 → 낮은 우선순위
+5건만 남김. 통째로 해소된 옛 "0번(추가 프리미티브)"/"2번(구현 착수 직전
+감사)"과 맨 아래 확정 요약표(README와 중복)는 archive로.
+**"항목을 해소하면 여기서 지우고 archive로 옮길 것"** 을 상단에 명시 —
+이게 없으면 같은 문제가 다시 쌓임.
+
+인바운드 참조 보호를 위해 절 번호 1/3은 헤딩에 유지하고, 없어진 0번/2번을
+가리키던 2곳은 실제 원본으로 재지정.
+
+## 4. 재발 방지 — 규율 문서가 아니라 검사기
+
+**진단**: 7·8차 감사에서 찾은 55건이 거의 전부 "변경한 세션이 그 자리에서
+안 한 일"이었고, 그중 상당수가 grep으로 잡히는 기계적 종류. 사람/에이전트의
+성실성에 기대는 규칙을 하나 더 쓰는 건 이미 실패한 방법(CLAUDE.md엔 이미
+"주기적으로 감사할 것"이 있었음).
+
+**`.claude/tools/doc-check.py` 신설** — 라이브 문서 61개에 대해 깨진 파일/절
+참조, README 색인 누락, 날짜 없는 시한부 주장, 미반영 배너를 한 번에 검사.
+오탐 제거에 공을 들임(아직 없는 소스 트리 `.luau`, 읽기 전용 `initreq/`,
+외부 문서명은 ERROR에서 제외 — 처음 돌렸을 때 232건이 나와 쓸모없었고,
+정밀화 후 ERROR 1 / WARN 58로 수렴).
+
+**검사기가 같은 세션 안에서 실효를 증명함**: bind-system-plan.md를 쪼개며
+"이중 바인딩 금지" 절 참조 4곳을 `ref-plan.md`로 옮겼는데, 그 절은 실제로는
+Observer/Effect 쪽이라 **이동 대상이 아니었음** — 사람 눈으로는 못 잡았을
+실수를 스크립트가 즉시 잡아내 되돌림. 이 한 건이 도구의 존재 이유를 그대로
+보여줌.
+
+**CLAUDE.md에 중대 변경 핸드오버 체크리스트 6단계 명문화**:
+doc-check 실행 → **부정당한 본문 문장 전수 grep**(배너만 달고 본문 방치가
+최다 실패 패턴) → 뒤집힌 원문은 archive로 → 개수/상태는 소스 하나만 →
+시한부 주장엔 날짜 → 인덱스 레이어 3개 동시 갱신.
+
+## 남은 것
+
+- `doc-check.py` WARN 58건 중 절 참조 불일치 51건은 대부분 "절 제목을 의역해
+  인용"한 관례라 판단이 필요 — 급하지 않지만 훑어서 진짜 깨진 것만 고칠 것.
+- `bind-system-plan.md` 2단계 분할(0-Z 반영과 같은 패스).

CLAUDE.md

@@ -1003,3 +1003,20 @@ Slot 언마운트 전환 미반영 6곳. 뒤집힌 "폐기, 옮기지 않음 + p
 달면 그 배너가 부정하는 *본문 문장*까지 같은 커밋에서 고쳤는지 확인할 것,
 (2) 영역 분할 감사는 "아무 영역에도 안 속한 파일"을 통째로 빠뜨리므로
 레포 루트 파일 목록으로 커버리지를 먼저 체크할 것.
+
+**2026-08-13 아홉 번째 세션 — 구조 재편(luau-test/bind-system/question) + 재발 방지 도구**
+(`session/2026-08-13-09-structure-and-guardrails.md`)
+"사람이 읽을 수 없는 문서" 문제를 사용자가 세 건 지적하고 재발 방지법을 물음.
+(1) `luau-test/`를 **상태별 폴더**로 재편(`done`/`review-required`/
+`rewrite-required`/`not-run`, 폴더 이동이 곧 상태 갱신 — 그래서 다른 문서는
+경로 아닌 **파일명**으로 참조하도록 정규화). (2) `bind-system-plan.md`
+**1단계 분할**(2989→2263줄, `ref-plan.md`/`event-plan.md`/`brand-plan.md`로
+순수 이동) — 남은 디스패치·반응형 코어는 0-Z 반영 때 **어차피 전면 재작성**
+대상이라 그 패스에서 같이 가르는 게 총 변경량·위험이 작다고 판단해 의도적
+연기(`dispatch-redispatch-diff-plan.md` 6절에 지시). (3) `question.md`를
+**사용자가 답할 것만**으로 축소(525→279줄, 해소분은
+`archive/question-resolved.md`). (4) 재발 방지는 규율 문서가 아니라
+**검사기**로 — `.claude/tools/doc-check.py` 신설(깨진 파일/절 참조, 색인
+누락, 날짜 없는 시한부 주장, 미반영 배너). **같은 세션에 실효 증명**: 분할
+중 "이중 바인딩 금지" 절 참조 4곳을 잘못 옮긴 걸 스크립트가 잡아내 되돌림.
+CLAUDE.md "작업 방식"에 중대 변경 핸드오버 체크리스트 6단계도 명문화.