docs: 문서 stale 감소용 include 도구 백로그 신설(doc-include.py)

반복된 stale 문제(같은 사실이 여러 곳에 중복 서술)를 근본적으로 줄이는
방법으로 마커 기반 include 도구를 논의 — AsciiDoc tagged include/
markdown-magic 선례 확인 후 build-vs-buy 검토, doc-check.py와 짝인 Python
직접 제작 채택. research/doc-include-plan.md에 플랜 초안(마커 문법,
CLAUDE.md 세션 히스토리 파일럿 범위, 열린 질문) 작성 — 세부는 사용자가
다듬을 예정, 구현 착수는 안 함. README.md 색인/CLAUDE.md 백로그·세션
히스토리 동기화.

.claude/README.md

@@ -77,6 +77,7 @@
 | `debounce-throttle-plan.md` | **[2026-08-14 신설]** 시간 기반 전파 게이트 `Debounce`/`Throttle` — 사용자 요청("`Blocker`와 유사하게")으로 신설. 요지: (1) `Blocker`가 이미 쓰는 게이트 노드의 **릴리스 트리거만 타이머로 바꾼 것**이라 새 전파 메커니즘이 아님 — `Blocker` 구현(M3) 시점에 게이트를 공용으로 빼두는 게 쌈, (2) 무효화 채널만 만지므로 laziness 안 깨짐, (3) **Debounce/Throttle의 차이는 "신호가 창 타이머를 리셋하는가" 한 비트뿐** — 공개 생성자는 둘, 구현은 하나(초안의 lodash식 `maxWait` 공식엔 trailing 통과 직후 이중 발화 버그가 있었음), (4) 알고리즘은 quad-base + 주입 op 2개 `setTimeout(func, delay) -> Timeout`/`clearTimeout`(Roblox `task.delay`/`task.cancel`로 배선 — **인자 순서 반대라 주의**). `os.clock()`은 Luau 표준 라이브러리라 주입 대상 아님(단 절대 시각이 아니라 **diff 전용**), 취소 없는 엔진도 래핑+유효 플래그로 대응 가능, `Timeout`은 `{ __type_timeout: true, _native: any }`. **부수 성과**: 이 설계 중 `source-state-plan.md`의 무효화 dedup 서술이 `Observer` 계약과 모순되는 게 발견돼 base 전면 정정(`archive/invalidate-dedup-propagation-reversed.md`) | 하 — M0 안 막음(코어 계약 변경 없음), 다만 순수 슈가가 아니라 실제 기능 갭이라 `operator-sugar-plan.md`보다는 위. 의존은 M3(State)+백엔드 주입. 남은 열린 질문: 이름(Roblox 관용 debounce와 충돌)/값 지연 의미론/제어 핸들 `Flush`/`Time=0` 허용 |
 | `quad-recursive-acronym.md` | **[2026-08-14 신설]** GNU/WINE류로 `Quad`를 재귀 약어화하는 카피 브레인스토밍 — 설계 결정도 착수 게이팅도 아니고 나중에 README.md 헤딩 등에 쓸 캐치프레이즈 후보 모음. 자학 개그 방향(기각)과 지연평가/재귀·커링/펑터/클로저를 자랑하는 방향(채택 후보, 미확정) 정리 | 하 — 카피 소재, 설계 상의 필요 없음. 사용자가 최종 문구 고르면 반영 |
 | `v1-compat-plan.md` | v1 하위호환(compat) 레이어 — `quad-roblox-v1-compat` 패키지, v2→v1 단방향 브리지(`state:Observer()`+v1 프로퍼티 재대입), v2-in-v1/v1-in-v2 두 임베딩 방향의 기술 규칙까지 확정. quad2-try의 `quad-compat`은 빈 폴더로 실제 시도된 적 없었음을 확인 | 하 — Slot이 foreign Instance를 어떻게 다루는지만 Slot 코어 구현 시점까지 미결 |
+| `doc-include-plan.md` | **[2026-08-14 신설]** 문서 stale 감소용 include 도구 `doc-include.py`(가칭) — 원본 파일에 `<!--#summary-->` 류 마커로 요약 구간을 표시해두면 인용하는 문서가 그 구간을 기계적으로 추출해 붙여넣게 하는 도구. `doc-check.py`(사후 탐지)와 짝을 이루는 사전 차단 장치. AsciiDoc tagged include/markdown-magic이 선례, build vs buy 검토 후 Python 표준 라이브러리로 직접 제작(~100줄) 채택. 파일럿은 `CLAUDE.md` 세션 히스토리 ← `.claude/session/*.md` 요약 마커부터(부작용 최소) | 하 — M0/설계 게이트와 무관한 메타 도구, 플랜만 초안, 사용자가 내일 다듬을 예정 |
 
 ## `archive/` — 완료됐거나 완전히 뒤집힌 것, 능동 참고 불필요
 

.claude/research/doc-include-plan.md

@@ -0,0 +1,101 @@
+# 문서 stale 감소용 include 도구 — `doc-include.py` (가칭)
+
+**상태**: research — 2026-08-14 세션에 아이디어 확정, **플랜만 초안, 사용자가
+다듬을 예정(내일 처리)**. 구현 착수 전.
+
+## 배경
+
+같은 날 진행된 코퍼스 전체 사실관계 감사(서브에이전트 4개 병렬)에서 실제
+오류 20건을 찾아 고쳤는데, 대부분이 "같은 사실이 두 곳 이상에 적혀있다가
+한쪽만 갱신됨" 패턴이었음(`bind-system-plan.md` 3단계 분할 후 다른 문서가
+옛 줄번호를 가리키던 것 11곳 등). 이 프로젝트는 이미 `doc-check.py`(기계
+검증기, ERROR/WARN 리포트)로 이 문제를 **사후 탐지**하고 있는데, 사용자가
+**사전 차단**(애초에 중복 서술이 안 생기게)이 더 근본적이지 않겠냐고 제안 —
+"summary" 같은 블록을 원본 파일에 마커로 표시해두고, 인용하는 쪽은 그 마커
+구간을 기계적으로 추출해 붙여넣는 도구를 만들면 정보의 관리 주체가 자연히
+한 파일로 모인다는 아이디어.
+
+## 선례 (재발명 아님을 확인)
+
+- **AsciiDoc tagged region include** — `// tag::x[]` ... `// end::x[]`로
+  구간 표시, `include::file.adoc[tag=x]`로 다른 문서가 그 구간만 당겨옴.
+  사용자가 제안한 `--#summary-start`/`--#summary-end` 아이디어의 원조 격.
+- **markdown-magic**(JS) — HTML 주석 마커(`<!-- AUTO-GENERATED-CONTENT:START -->`)로
+  README 등에 다른 파일 내용을 주입, 재실행하면 갱신. Markdown 생태계에서
+  가장 가까운 기존 도구.
+- **Obsidian/Roam/Logseq의 block transclusion**(`![[file#^blockid]]`) —
+  빌드 스텝 없이 렌더 시점에 라이브로 당겨옴. stale이 구조적으로 원천 차단되는
+  더 강한 버전이지만 이 프로젝트는 정적 `.md` 파일이 소스라 뷰어 종속적인
+  이 방식은 안 맞음.
+
+## Build vs Buy 판단 — 직접 제작 채택
+
+- 필요한 기능이 좁음: 마커 사이 텍스트를 원본에서 읽어 대상에 갱신 삽입 +
+  재실행해도 안정적(idempotent) + `--check` 모드로 어긋나면 실패. 정규식
+  몇 개 + 파일 I/O가 전부라 100줄 내외로 충분.
+- 기존 도구(markdown-magic 등)를 쓰면 이 레포에 없던 Node/npm 툴체인이
+  새로 들어옴 — 지금 유일한 도구인 `doc-check.py`가 Python 표준 라이브러리만
+  쓰는 의존성 0 스크립트라는 관례와 어긋남. 프로젝트가 얻는 이득(TOC 생성,
+  배지 삽입 등 우리가 안 쓸 기능들)에 비해 대가가 큼.
+- 마커 문법을 이 코퍼스 관례(한국어, `doc-check.py`의 ERROR/WARN 리포팅
+  스타일)에 맞춰 직접 정하고 싶으므로, 외부 도구 설정 파일로 끼워 맞추는
+  것보다 직접 짜는 쪽이 코드도 적고 통제도 쉬움.
+
+**결론**: `.claude/tools/doc-check.py`와 짝을 이루는 `doc-include.py`를
+Python 표준 라이브러리만으로 신설. `--write`(갱신 삽입)/`--check`(어긋나면
+ERROR, `doc-check.py` 파이프라인에 편입) 두 모드.
+
+## 파일럿 범위 — CLAUDE.md 세션 히스토리부터
+
+사용자가 지목한 이유: 세션 히스토리 항목은 서로 독립적(과거 기록이라
+다른 문서가 그 문장을 인용하는 경우가 거의 없음)이라 이 도구가 버그가
+있어도 **부작용이 다른 곳으로 안 번짐** — 첫 적용 대상으로 가장 안전.
+
+- 지금 구조: `.claude/session/YYYY-MM-DD-NN-slug.md`에 세션 원문 전체가
+  있고, `CLAUDE.md`의 "세션 히스토리" 절엔 사람이 손으로 압축한 2~4줄
+  요약 + 링크가 별도로 적혀있음(둘이 물리적으로 분리된 텍스트라 한쪽만
+  갱신되면 어긋날 수 있음 — 실제로 아직 발생한 적은 없지만 구조적으로
+  가능한 상태).
+- 적용 후: 각 세션 파일 안에 "이 요약이 CLAUDE.md에 들어갈 정본"이라고
+  표시하는 마커 블록을 신설(**새로 요약을 쓸 필요 없음** — 지금
+  `CLAUDE.md`에 이미 있는 압축 요약을 그대로 그 블록 안으로 옮기면 됨).
+  `CLAUDE.md` 쪽엔 대응하는 include 마커만 남기고, `doc-include.py --write`가
+  두 마커 사이 콘텐츠를 세션 파일에서 가져와 채움.
+
+## 마커 문법 (초안 — 사용자가 확정할 것)
+
+```
+# 세션 파일(.claude/session/2026-08-14-14-....md) 안:
+<!--#summary:2026-08-14-14-->
+**2026-08-14 열네 번째 세션 — ...** (`session/2026-08-14-14-....md`)
+... 2~4줄 압축 요약 ...
+<!--#/summary-->
+
+# CLAUDE.md "세션 히스토리" 절 안:
+<!--#include:2026-08-14-14 from=session/2026-08-14-14-....md-->
+(doc-include.py --write가 여기를 원본 summary 블록 내용으로 갱신)
+<!--#/include-->
+```
+
+## 열린 질문 (사용자가 다듬을 것)
+
+1. 마커 문법 자체(위 초안 확정 여부, id 네이밍 규칙 — 날짜+세션번호로
+   충분한지).
+2. 기존 세션 항목 전부(13개+)에 마커를 소급 삽입할지, 아니면 다음
+   세션부터 신규 항목에만 적용하고 과거분은 그대로 둘지.
+3. `--write` 실행 시점 — 수동(세션 마무리 시 사람이 실행) vs 커밋 훅.
+   이 레포는 지금 CI가 없고 사람이 `doc-check.py`도 수동으로 돌리는
+   관례라 같은 패턴(수동 + 커밋 전 확인)이 자연스러워 보이지만 확정은
+   사용자 몫.
+4. `--check` 실패를 `doc-check.py`의 ERROR로 편입할지 별도 스크립트로
+   둘지.
+5. 파일럿이 성공하면 다음 확대 후보 — `.claude/README.md` 표의 "상태"
+   요약을 각 `base/`/`research/` 문서 맨 위 `**상태**: ...` 줄에서
+   추출해오는 것(단, `luau-test/STATUS.md`처럼 이미 "폴더 구조 자체가
+   상태"인 곳은 include로 바꿀 필요 없음 — 그쪽은 이미 소스가 하나로
+   수렴된 상태라 적용 대상 아님).
+
+## 우선순위
+
+하 — M0/설계 게이트와 무관한 메타 도구. 사용자가 플랜을 다듬은 뒤 착수
+시점 결정.

.claude/session/2026-08-14-14-corpus-audit-doc-include-backlog.md

@@ -0,0 +1,61 @@
+# 2026-08-14 열네 번째 세션 — 코퍼스 전체 사실관계 감사 + `doc-include.py` 백로그 신설
+
+사용자 요청("전체 내용 감사해줘, 서브에이전트 써도 좋아")으로 `.claude/`
+코퍼스 전체를 대상으로 사실관계 감사 진행.
+
+## 1. 기계 점검 + 서브에이전트 4개 병렬 감사
+
+`python3 .claude/tools/doc-check.py` 선실행(ERROR 0, WARN 85 — 대부분
+"절 제목 의역 인용" 정상 관례). 이어서 base/, research+reference/,
+luau-test+audit/, archive+root 네 영역으로 나눠 general-purpose 서브에이전트
+4개를 병렬로 띄워 각자 독립적으로 감사·직접 수정하게 함(같은 파일을
+동시에 건드리지 않도록 영역 분리, CLAUDE.md 자체는 제외해 어시스턴트가
+직접 처리).
+
+**결과**: 13개 파일에 걸쳐 실제 오류 20건 수정.
+- 가장 큰 원인: `bind-system-plan.md` 3단계 분할(1238→203줄, 9차/14차
+  세션) 이후 `research/`·`reference/` 문서 11곳이 여전히 옛 줄번호나
+  이관된 내용을 옛 파일로 가리키던 것 — `source-state-plan.md`/
+  `event-plan.md`/`dispatch-core-plan.md`/`archive/
+  quad2-try-research-findings-rejected.md` 등 실제 위치로 정정.
+- `HUMAN_TODO.md`가 이중 바인딩 게이트를 "`canExecute` 하나"로 서술
+  중이었으나 열한 번째 세션의 `canBound` 재도입이 반영 안 돼 있던 것 정정.
+- `architecture.md`/`blocker-plan.md`/`component-composition-plan.md`/
+  `debug-tooling-plan.md`의 "남은 건 X뿐" 류 날짜 없는 완결 주장 4건에
+  `[YYYY-MM-DD 기준]` 날짜 태그 추가(git log로 유추).
+- `luau-test/`·`archive/`·`.claude/README.md`·`ROADMAP.md`·`question.md`·
+  `HUMAN_TODO.md`·`SAFETY.md`는 감사 결과 이상 없음 확인(agent 보고).
+- 어시스턴트가 CLAUDE.md 자체도 직접 대조(`bind-system-plan.md`의
+  "확정된 것" 절 존재 여부, 최근 승격 파일 실존 여부 등) — 이상 없음.
+
+`doc-check.py` ERROR 0 유지, 커밋 완료(`f829487`).
+
+## 2. State 노드 남발 줄이는 법 — 탐색 질문
+
+기존 확정 설계에서 이미 있는 절제 수단 세 가지를 정리해 답변: (1)
+`:With(a,b,c)` 가변인자로 한 호출에 의존성 몰아넣기, (2) 이미 다른 이유로
+노드를 만드는 자리면 `:Compute(fn, ...)` trailing-args로 공짜로 의존성만
+얹기(단 호출문 로컬 안에서만 무료), (3) 재사용되는 파생 로직은
+`:Apply(factory)`로 감싼 콤비네이터를 한 번만 만들어 재사용. 근본
+원칙은 "관측해야 실체화된다"(source-state-plan.md) — 반응성이 실제로
+필요 없는 값은 State로 안 감싸는 것. 새 설계 결정 아님, 기존 문서
+인용 답변.
+
+## 3. 문서 stale 감소 방안 논의 → `doc-include.py` 백로그 신설
+
+사용자가 "요약 부분을 특정 파일에서 마커로 표시해두고, 인용하는 문서가
+그 구간을 기계적으로 추출해 붙여넣는 도구를 만들면 안 되냐"고 제안(선례
+있는지도 질문). 어시스턴트가 AsciiDoc tagged region include / markdown-magic
+/ Obsidian block transclusion을 선례로 확인, 이 코퍼스엔 아직 없음을
+확인. 사용자가 "직접 만들지 vs 기존 걸 가져다 쓸지"를 재질문 —
+build-vs-buy 판단으로 **직접 제작 채택**을 권고(문제가 좁아 100줄 내외로
+충분, 기존 JS 도구는 Node/npm 툴체인을 새로 들여옴 — `doc-check.py`가
+Python 의존성 0이라는 관례와 어긋남, 마커 문법을 코퍼스 관례에 맞춰
+직접 정하는 게 더 간단).
+
+사용자가 동의, **오늘은 플랜만 작성**하고 세부는 내일 사용자가 직접
+다듬기로 함 — 파일럿 범위는 **CLAUDE.md 세션 히스토리부터**(다른 문서가
+그 문장을 인용하는 경우가 거의 없어 부작용이 가장 작다는 사용자 판단).
+`research/doc-include-plan.md` 신설(마커 문법 초안, 파일럿 범위, 열린
+질문 5개, 우선순위 하) — `.claude/README.md` research 표, `CLAUDE.md`
+"지금 할 일" 6번에 반영. 구현 착수는 아직 안 함.

CLAUDE.md

@@ -270,6 +270,10 @@ modifier/Ref의 컴포넌트 경계 통과 방식) 논의도 2026-08-04 세션
    거기도 반복 안 함 — 소스는 `research/debounce-throttle-plan.md` 12절).
 5. 자율 작업 루프/스케줄 설정 여부는 사용자 결정 대기 중
    (`HUMAN_TODO.md` 2번 항목).
+6. **[신규 백로그, 2026-08-14 열네 번째 세션]** 문서 stale 감소용 include
+   도구 `doc-include.py`(가칭, `doc-check.py`와 짝) — `research/
+   doc-include-plan.md` 참고. 플랜만 초안, **사용자가 내일 다듬을
+   예정**. M0/설계 게이트와 무관.
 
 ## 세션 히스토리
 
@@ -1450,3 +1454,19 @@ v1) Did` 등)은 톤이 안 맞아 기각, 사용자가 실제로 내걸고 싶
 지연평가·재귀/커링·펑터·일급 익명 클로저 방향으로 `Quad Unwinds,
 Applies, Defers` 등 4개 후보 정리 — `research/quad-recursive-acronym.md`
 신설(나중에 README.md 헤딩 후보용), 최종 문구는 미확정.
+
+**2026-08-14 열네 번째 세션 — 코퍼스 전체 사실관계 감사, `doc-include.py`
+백로그 신설** (`session/2026-08-14-14-corpus-audit-doc-include-backlog.md`)
+서브에이전트 4개 병렬(base/research+reference/luau-test+audit/archive+root)로
+전 코퍼스 재감사 — `bind-system-plan.md` 3단계 분할 후 stale 참조 11곳,
+`HUMAN_TODO.md`의 `canBound` 재도입 미반영, 날짜 없는 완결 주장 4건 등
+13개 파일 20건 수정, `doc-check.py` ERROR 0 유지(커밋 `f829487`). 이어
+사용자가 반복된 stale 원인(같은 사실이 여러 곳에 중복 서술)을 근본적으로
+줄이는 방법으로 마커 기반 include 도구(원본에 요약 구간을 마커로 표시,
+인용 문서가 기계적으로 추출해 붙여넣음)를 제안 — AsciiDoc tagged
+include/markdown-magic이 선례임을 확인 후 build-vs-buy 논의, 문제가 좁고
+기존 도구는 새 Node/npm 의존성을 들여온다는 이유로 **직접 제작**(Python,
+`doc-check.py`와 짝) 채택. 오늘은 플랜만 `research/doc-include-plan.md`로
+작성 — 파일럿은 부작용이 가장 작은 CLAUDE.md 세션 히스토리부터, 마커
+문법·소급 적용 범위 등 열린 질문은 **사용자가 내일 직접 다듬기로 함**,
+구현 착수 안 함.