[DONE] 정리를 시작하기 전 레포의 출발점(시험 결과·문서 지도)을 기록해 둔다

[patternflow-bot]

dev / https://claude.ai/code/session_014L3ZRG6hS4BH2Q8YQjhzS5

정리 계획서 Step 0 입니다. 출발 커밋 8226f7e 에서 명령 다섯이 모두 통과했습니다(펌웨어 빌드는 이 상자에서 PlatformIO 가 막혀 GitHub Actions 로 같은 SHA 에서 돌렸습니다). 머지하면 레포로 들어오는 링크 1007개의 문서 지도와 그것을 만드는 npm run doc-map, AGENTS.md 의 정리 기간 규칙이 생겨, 파일을 옮길 때 깨질 링크를 미리 압니다.

좋아지는 것: 없음

체크리스트

• 계획서 §2.1·§2.2·§2.8·§2.9·§2.10 읽기
• 출발 SHA 와 §2.1(1) 명령 다섯 → docs/investigations/2026-10-cleanup-baseline.md (다섯 다 통과, 빨간 것 없음)
• web/scripts/doc-map.ts + npm run doc-map → docs/investigations/2026-10-doc-map.csv (1007줄, resolves=no 0)
• AGENTS.md 하드 룰 8 (§2.2 의 한 줄)
• docs/rfc-cleanup-progress.md Step 0 칸과 「Step 0 — baseline」 절
• 손으로 쓴 줄 300 미만(297) — CSV 는 생성물이라 셈에서 뺌(가정 2)
• §2.8 손대지 않을 것·§2.9 사람 글 잠금 파일 안 건드림, 동작 바뀜 없음
• 이 PR 머리(ad1083f) CI 초록: Web CI · Docs point at files that exist · Core knows no features
• dev merge 확인(그새 dev 안 움직임, 8226f7e)

한 일

1. 기준선 기록 docs/investigations/2026-10-cleanup-baseline.md: 출발 SHA 8226f7ea5da15b0e0e55b15fa9ec7af136eef080(dev, progress 문서를 넣은 커밋), 명령 다섯의 결과 표, 펌웨어가 상자에서 못 돈 까닭과 CI 에서 돈 결과(조합 다섯의 이미지 크기·마커 검사), Step 3 이 0으로 만들 lint 경고 12개 표, 문서 지도 요약, 알려진 깨진 링크(없음).
2. 문서 지도 web/scripts/doc-map.ts(191줄) + npm run doc-map: 추적되는 .md/.mdx/.ts/.tsx/.h, 콘솔 페이지, next.config.ts 의 redirect 표에서 레포로 들어오는 링크를 모아 from,to,kind,anchor,resolves CSV 로 씁니다. kind 는 relative · absolute-blob · absolute-raw · site(라우트·public·redirect/rewrite 소스로 판정) · console(펌웨어가 .on("/path") 로 등록한 경로로 판정). .md 로 가는 앵커는 GitHub 슬러그 규칙으로 제목과 맞춰 봅니다. 사이트가 const REPO = "…" · ${REPO}/blob/main/… · blob("…") 로 만드는 링크도 펼쳐서 잡습니다.
3. AGENTS.md 하드 룰 8: 「During a cleanup window (see docs/rfc-cleanup.md) no PR changes behaviour; moves and renames carry a redirect or an updated link map.」 — 계획서 문장 그대로, 경로만 링크로.
4. 진행 기록 docs/rfc-cleanup-progress.md: Step 0 칸 「done ([DONE] 정리를 시작하기 전 레포의 출발점(시험 결과·문서 지도)을 기록해 둔다 #11)」, 「Step 0 — baseline」 절, 맨 위 「Where it stands」 줄(「Baseline SHA to be recorded in step 0」 자리)에 SHA.

찾은 것 하나: 계획서 §2.3 은 사이트가 BUILD_GUIDE_v2.md 의 §1·§2·§4·§8·§10 에 앵커 링크를 건다고 하지만, 지금 사이트는 v2 가이드를 BuildPanel.tsx 에서 앵커 없이 한 번만 겁니다. 앵커 링크들은 BUILD_GUIDE.md 로 갑니다. v2 가이드를 옮기면 그 한 곳·옆 테스트·Markdown 다섯 파일이 바뀝니다(기준선 문서에 적음, 계획서는 안 고침).

증거

웹 명령은 출발 SHA 그대로의 트리에서, Node 22.22.0 · npm 10.9.4 · npm ci (CI 는 Node 20).

명령	결과	출력
firmware/bundles/build.sh all	통과 (CI)	Firmware builds run 38560727407, dev @ 8226f7e, workflow_dispatch: default 1102672 bytes ok · audio 1208656 bytes ok · performance 1526624 bytes ok · clock 1187088 bytes ok · midi 1163440 bytes ok, 다섯 다 every edition within tolerance
npm run check:ci	통과 (exit 0)	25 스위트, All module cache checks passed. (50 s)
npm run check:panels	통과 (exit 0)	Test Files 35 passed (35) · Tests 478 passed (478)
npm run typecheck	통과 (exit 0)	출력 없음
npm run lint	통과 (exit 0)	✖ 12 problems (0 errors, 12 warnings)

• 상자 안 펌웨어: build.sh all → Platform Manager: Installing espressif32 @ 7.0.1 → HTTPClientError (68 s). 프록시 기록: api.registry.platformio.org:443 CONNECT 403. 대신 firmware-checks.yml 의 호스트 검사 17개·console-sync.yml 둘을 상자에서 돌려 모두 exit 0(예: boundary holds: 73 core files know none of 42 feature namespaces across 9 features).
• 이 PR 머리 ad1083f 의 CI: Web CI(lint·typecheck·build·check:ci, Node 20) success · Docs point at files that exist success · Core knows no features success. 상자에서도 npm run build exit 0, npm run lint 같은 12 warnings·0 errors(새 스크립트는 경고 없음).
• npm run doc-map → 1007 links from 193 files → docs/investigations/2026-10-doc-map.csv · 0 do not resolve. 두 번 돌려 같은 파일(cmp). kind: relative 532 · site 329 · absolute-blob 114 · console 32 · absolute-raw 0.
• 판정기 시험: docs/README.md 에 일부러 깨진 링크(없는 파일, 없는 앵커, 없는 사이트 경로, main·v2.1.0 의 없는 blob)와 살아 있는 링크(/guide/play#flash, /variants, /r/arduino, /flash/manifest.json, raw URL, BUILD_GUIDE.md#2-power-input--use-the-screw-terminal)를 잠깐 넣어 돌림 → 깨진 6개만 no, 나머지 yes. 파일은 되돌림.
• 리팩터 뒤 CSV 가 바뀐 줄은 이 PR 이 더한 문서의 링크 7줄뿐(diff 확인).

실행법

cd web && npm ci
git fetch --depth=1 origin tag v1.0.0 tag v2.0.0 tag v2.1.0 tag v3.0.0 tag v3.1.0   # 얕은 클론이면
npm run doc-map

펌웨어 기준선을 다시 보려면 Actions 의 「Firmware builds」를 dev 에서 Run workflow 하거나, PlatformIO 저장소에 닿는 기계에서 ./firmware/bundles/build.sh all.

가정

1. 스크립트 자리 — 계획서는 scripts/doc-map.ts (web workspace, reads the whole repo) 라고 해서 web/scripts/doc-map.ts 에 두고 npm run doc-map 으로 걸었습니다(다른 check 스크립트들도 web/scripts). check:ci 에는 안 넣었습니다 — Step 0 은 지도를 원하고, CI 로 막는 일은 Step 2 의 check:links-absolute 몫입니다.
2. 300줄 — 손으로 쓴 변경은 297줄(스크립트 191, 기준선·progress·AGENTS·package.json 나머지)입니다. CSV(1008줄)는 스크립트의 출력이라 lockfile 처럼 셈에서 뺐습니다. 계획서가 Step 0 결과물로 CSV 를 요구해서 어느 PR 도 그것을 300줄 아래로 담을 수 없으니, 둘로 나누지 않았습니다.
3. 출발 SHA 는 dev 머리 8226f7e 입니다(제 빈 시작 커밋이 아니라). 웹 명령은 그 트리에 아무것도 더하지 않고 돌렸습니다.
4. 펌웨어를 CI 로 — 세션 네트워크 정책이 api.registry.platformio.org 를 403 으로 막아 상자에선 못 돌렸습니다(우회는 안 함). firmware-build.yml 에 workflow_dispatch 가 있어 dev 에서 한 번 돌렸고, 그 run 의 head 가 정확히 8226f7e 입니다. 그 워크플로는 build.sh all 을 조합마다 한 job(build.sh one)으로 나눈 것이고 아무것도 올리지 않습니다(배포 아님). 처음엔 포크에 Actions 실행 기록이 0이라 CI 가 없는 줄 알았는데, 이 PR 에서 실제로 돌아서 바로잡았습니다.
5. 지도가 빼는 것 — 한 파일 안의 #앵커, 레포 첫 화면·이슈·PR·릴리스 링크, TSX 컴포넌트의 사이트 라우트 링크(href="/guide", 파일 이동으로 안 깨짐), 벤더 코드(hub75·webserver·pubsubclient, check_links.py 와 같음), 콘솔 페이지를 다시 담은 *_index.h. 테스트 파일(.test.ts)은 계획서가 「every .ts」라 넣었습니다. 사이트 경로의 앵커(#flash)는 라우트만 봅니다.
6. 태그 링크 24줄 — 얕은 클론엔 태그가 없어 no 가 됩니다. 이 상자에서는 태그를 받아 확인했고, 스크립트 머리와 기준선 문서에 적었습니다.
7. 글투 — 영어 글(기준선·progress·AGENTS 줄·스크립트 주석·커밋 첫 줄)은 §2.10 대로 em dash 없이, 금지어 없이, 시작·맺음 요약 없이 썼습니다. progress 의 굵은 「Where it stands」는 원래 있던 꼴을 따랐습니다. 커밋 꼬리말과 이 본문 맨 끝 한 줄은 세션의 귀속 표기라 그대로 뒀습니다(레포 파일엔 없음).
8. 계획서 §2.11(브랜치 cleanup/…, 라벨, 세 줄 본문)은 이번 일에서 따르라고 한 절이 아니고 일꾼 규칙(세션 브랜치·본문 꼴)과 겹쳐서 일꾼 규칙을 따랐습니다. CONTRIBUTING.md 는 §2.2 가 AGENTS.md 만 말해 고치지 않았습니다.
9. CHANGELOG.md 는 일꾼 규칙대로 안 고쳤습니다 — 넣을 줄은 아래.

Changelog

Docs

• The cleanup has a baseline. docs/investigations/2026-10-cleanup-baseline.md records the commit the cleanup starts from and what the five commands in docs/rfc-cleanup.md §2.1 said there. All five pass. AGENTS.md gains hard rule 8: during a cleanup window no PR changes behaviour, and moves and renames carry a redirect or an updated link map.

Web

• npm run doc-map writes every link into the repository, from Markdown, site code, the console pages and the redirect table, to docs/investigations/2026-10-doc-map.csv with whether it resolves. 1007 links at the baseline, none broken.

Which row

CONTRIBUTING 표의 「A fix to a guide, a README or a spec」에 가장 가깝습니다(문서·도구, 동작 변화 없음).

---

• Touches web/ → it builds (npm run build)
• Touches a markdown file → its relative links resolve (python3 .github/scripts/check_links.py)

🤖 Generated with Claude Code

https://claude.ai/code/session_014L3ZRG6hS4BH2Q8YQjhzS5