[DONE] 정리 3단계를 PR 스물일곱으로 나눈 계획서 — 같이 열릴 수 있는 PR 끼리는 파일이 안 겹친다

[patternflow-bot]

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

정리 3단계(코드 위생)를 정찰해서 PR 스물일곱으로 나눈 계획서를 썼다. 머지하면 기다릴 것이 없는 아홉(k1·k2·k4·k5·k6·k7·k10·k11·k13) 가운데 아무 셋이나 바로 맡길 수 있다. 정찰하다 보니 MIDI 페이지가 아직 한 바퀴를 20 디텐트로 센다(엔코더는 24). 이건 정리가 아니라 고침이라 k10 으로 따로 두었다.

좋아지는 것: 없음

체크리스트

• docs/rfc-cleanup.md §2.5 · §2.1 · §2.8–§2.13 과 §2.13 답 읽기
• 진행 기록 · 0단계 기준 기록 · 1·2단계 계획서 읽기. docs/voice.md 는 포크 dev 에 아직 없다([DONE] 영어는 README·조립 가이드 글투로, 한국어는 번역체를 피하는 기준으로 한 쪽에 적고, 쓰지 않는 말은 따로 목록으로 둔다 #18 이 열려 있음)
• 일마다 정찰: lint·typecheck, 옛 경로·키, 의존성, HUB75 포크, TODO/FIXME, 공유 상수
• docs/investigations/2026-10-cleanup-step3-plan.md: 맨 위 표에 k · 고칠 파일 · 먼저 머지될 k · §2.13 번호
• 표를 스크립트로 읽어, 같이 열릴 수 있는 두 줄에 같은 파일이 없는지 확인
• docs/rfc-cleanup-progress.md 표의 3단계 줄을 planned 와 계획서 링크로
• 링크 검사 · doc map 돌림(CSV 는 되돌림)
• dev merge(그새 안 움직임: Already up to date)

한 일

• 계획서 docs/investigations/2026-10-cleanup-step3-plan.md (영어 295줄, 2단계 계획과 같은 꼴). 구현은 하지 않았다.
• PR 표 (파일까지는 계획서 맨 위 표)
  • lint: k1 안 쓰는 이름 넷과 훅 의존 하나, k2 <img> 일곱에 이유 단 예외, k3 CI 가 경고에도 실패(.github/ 만, k1·k2 뒤)
  • 옛 경로·키: k4 Pattern Lab v1 키, k5 사이트 redirect·옛 경로, k6 커뮤니티·빌드 서비스가 아직 받는 옛 형식
  • 공유 상수: k7 shared/constants.json · 생성기 · 생성 파일 둘 · check:shared, 그 뒤에 k8 펌웨어가 읽기와 k9 웹이 읽기
  • k10 MIDI 를 24 디텐트로(정리가 아니라 고침)
  • HUB75: k11 UPSTREAM.md 와 patternflow.patch, k12 upstream 고침을 커밋마다 PR 하나씩(k11 목록이 비면 없음)
  • k13 새 TODO/FIXME 를 막는 drift 검사
  • 의존성 k14–k24: 가족마다 하나, 한 번에 하나씩 차례로(lockfile 을 같이 써서)
  • k25 AGENTS.md, k26 트리 지도 문서 셋, k27 3단계 닫기
  • §2.13 번호: 의존성 줄은 4(메이저는 이번 창에서 안 함), 나머지 —
  • 같이 고칠 자리 check:ci 는 아무도 안 고친다. 2단계 k1 러너가 web/scripts/drift/ 의 파일을 저절로 돌려서, k7·k13 은 파일만 더하면 든다. web/package.json 은 k7 이 먼저(이름 둘), 뒤에 k23·k24(고정 버전)
• 정찰에서 나온 것
  1. lint 경고는 기준 기록과 같은 12개, typecheck 는 깨끗하다. CI 가 경고를 통과시켜서 고쳐도 다시 생길 수 있다.
  2. <img> 를 next/image 로 바꾸면 페이지 마크업이 바뀐다(§2.1 위반). 트리는 이미 같은 규칙에 줄 단위 예외를 아홉 번 두었다.
  3. Pattern Lab 의 draft 키는 7월 25–27일 이틀만 쓰였다. 「한 번만 읽는다」는 주석이 틀렸다: 세션을 치우면 프로젝트 키가 지워지고, 다음에 열 때 마이그레이션이 다시 돈다.
  4. /variants·/flash redirect 는 이미 무엇이 가리키는지 적혀 있다. 이름 없는 것: 저널 ?lang=en 둘, /en/en, 캠페인 링크 여덟, /business.
  5. HUB75 포크는 blitRGB888 말고도 고친 데가 많다(버퍼 체인, 300 Hz 패딩, OE 창, 반올림, 표시 없는 on-time 접근자). VENDORED.md 의 「다른 건 안 고쳤다」는 낡았다. upstream 커밋 SHA 는 어디에도 없고 태그 3.0.13 만 있다.
  6. TODO/FIXME 는 우리가 쓴 코드에 0개다. 있는 건 vendored HUB75 안의 upstream 것 하나다. 5월–10월 dev 일곱 시점에서도 0개라, RFC 가 센 「다섯」은 이 레포에 없다.
  7. 펌웨어에는 「한 바퀴 디텐트 수」 상수가 아예 없다. 24 는 웹에만 있고, MIDI 기능(9월)은 20 을 쓴다(midi.html:206, core_midi.h:69, docs/midi-spec.md:119).
  8. core_shared.h 를 해시되는 헤더 넷(core_color/math/noise/module_loader.h) 밖에서만 include 하면 .pfm 캐시 키가 안 움직인다. 이미지에 __DATE__ 가 들어가 바이트 비교가 안 돼서, k8 은 static_assert 커밋과 이미지 크기로 증명한다.
• 창작자에게 물을 것 (계획서 끝. 2단계 계획의 15 다음 번호, 모두 기본값 있음)
  16. 다섯 마커는 어디 있었나 · 17. 이유 단 줄 예외가 「규칙 완화」인가(기본: 아니오) · 18. v1 draft·ramp 마이그레이션을 지워도 되나(기본: 두고 이름 달기) · 19. /business·?lang=en 을 둘까 · 20. k11·k12 세션에 upstream HUB75 레포 읽기 권한(기본: hub 가 읽기로 붙임) · 21. 빌드가 무시하는 upstream HEAD 클론 둘을 지울까(기본: 이번엔 안 함) · 22. k10 을 이번 창에 고침으로 받을까(기본: 예) · 23. 화면 타이밍 스물도 JSON 에 넣을까(기본: 아니오) · 24. AI 프롬프트의 「0.05 per detent」(기본: 정리 뒤 고침) · 25. 생성된 글을 300줄 셈에서 뺄까(기본: 예)

증거

$ cd web && npm ci && npm run lint
✖ 12 problems (0 errors, 12 warnings)        # 기준 기록 표와 같은 파일·줄
$ npm run typecheck
> tsc --noEmit                                # 출력 없음, exit 0
$ npm outdated                                # 14일, 계획서 finding 7 이 이 결과
next 16.3.0 → 16.4.1 · react 19.2.4 → 19.3.1 · better-auth 1.6.23 → 1.7.8 · … (메이저: typescript 7, vitest 5, eslint 10, jsdom 29 …)

$ git grep -n -E "TODO|FIXME"
.gitignore:79:TODO-personal.md
docs/rfc-cleanup.md:157:- The five remaining `TODO`/`FIXME` markers become issues or get resolved.
firmware/patternflow/src/hub75/ESP32-HUB75-MatrixPanel-I2S-DMA.cpp:126:        // TODO: should we release all previous rowBitStructs here???

$ python3 table_check.py docs/investigations/2026-10-cleanup-step3-plan.md   # 표를 읽어 k 사이 순서를 따짐
27 rows
rows sharing a file without an order between them: none
files in more than one row: {'web/package.json': [7, 23, 24], 'web/package-lock.json': [14..24]}   # 둘 다 차례로 이어진 줄
named paths that do not exist yet: [... 10개, 전부 백틱]
wait on nothing: [1, 2, 4, 5, 6, 7, 10, 11, 13]
markdown links: ['../rfc-cleanup.md']

$ python3 .github/scripts/check_links.py
All 666 relative links resolve
$ git fetch --tags && (cd web && npx tsx scripts/doc-map.ts)
1055 links from 210 files → docs/investigations/2026-10-doc-map.csv
0 do not resolve
$ git checkout docs/investigations/2026-10-doc-map.csv docs/investigations/2026-10-doc-parity.csv   # CSV 는 k27 만 커밋

$ git diff --stat origin/dev...HEAD
 docs/investigations/2026-10-cleanup-step3-plan.md | 295 +++
 docs/rfc-cleanup-progress.md                      |   2 +-
 2 files changed, 296 insertions(+), 1 deletion(-)      # 300줄 안

실행법

계획서만 있는 PR 이라 돌릴 것이 없다. 읽을 곳은 docs/investigations/2026-10-cleanup-step3-plan.md 맨 위 「The PRs」 표다. 2단계가 닫히면(§2.12) 총괄이 k1·k2·k4·k5·k6·k7·k10·k11·k13 가운데 셋을 빈 시트에 맡긴다. 그 뒤 「merges after」 가 다 머지된 줄을 맡기면 된다. 의존성 k14–k24 는 늘 하나씩만 연다.

가정

• 「진행 기록의 앞 단계 줄」은 표의 3단계 줄로 읽었다([DONE] 정리 1단계를 세 갈래로 나눈 계획서 — 셋이 파일 안 겹치게 바로 시작할 수 있다 #12·[DONE] 정리 2단계를 PR 열넷으로 나눈 계획서 — 어느 셋을 같이 맡겨도 파일이 안 겹친다 #19 가 자기 단계 줄만 고친 것처럼). 「Where it stands」 줄은 닫는 PR 몫이라 두었다.
• k 는 1·2·3 에서 그치지 않고 27까지다. 「PR 하나에 300줄, 관심사 하나」(§2.1(5))와 「가족마다 PR 하나」(§2.5)를 지키면 셋으로는 안 된다. 「셋이 같이 해도」는 「같이 열릴 수 있는 어느 줄끼리도 파일이 안 겹친다」로 읽었다. lockfile 을 같이 쓰는 의존성 열한 줄은 차례로 잇는 길밖에 없어서 그렇게 했다.
• 「없는 §2.9 잠금·§2.10 글투 검사」는 2단계 계획의 k8·k9 가 이미 맡았다. 같은 파일을 두 PR 이 쓰게 되니 다시 넣지 않았다. 3단계는 §2.12 대로 2단계가 닫힌 뒤 열린다고 적었고, 3단계 PR 은 잠긴 글을 안 고치고 더한 글에 글투 검사를 돌린다.
• CHANGELOG.md 는 고치는 PR 이 없다. 각 PR 의 변경 줄은 본문 ## Changelog 로 간다. AGENTS.md(k25)와 .github/(k3)는 따로 PR 이다.
• MIDI 20→24(k10)는 RFC 가 이 단계의 이유로 든 바로 그 사건이라 표에 넣었다. 다만 화면이 바뀌므로 「정리가 아니라 고침」(§2.2)으로 적고 질문 22 로 물었다. AI 프롬프트의 「0.05 per detent」는 이 단계의 이유가 아니라서 질문 24 로만 남겼다.
• RFC 의 「다섯 마커」는 찾지 못했다. 그래서 「새로 안 생기게」를 drift 검사 하나(k13)로 두고 질문 16 으로 물었다.
• 옛 경로·키는 「두고 이름 달기」가 기본이다(D2). 지우면 동작이 바뀌어서다. 지울지는 질문 18·19 로 창작자에게 남겼다.
• upstream HUB75 레포(mrcodetastic)는 이 세션 범위 밖이라 읽지 않았다. 그래서 「태그 3.0.13 이후 upstream 커밋이 몇 개인가」를 몰라 k12 를 조건부 한 줄로 두었다.
• 히스토리를 읽으려고 이 레포(포크) 클론의 shallow 를 풀었다(git fetch --unshallow origin dev). 다른 레포는 건드리지 않았다.
• docs/voice.md 가 포크 dev 에 없어([DONE] 영어는 README·조립 가이드 글투로, 한국어는 번역체를 피하는 기준으로 한 쪽에 적고, 쓰지 않는 말은 따로 목록으로 둔다 #18 열림) RFC §2.10 규칙대로 썼다. 여는 말·맺는 말 없음, 금지어 없음(grep 확인), 표 칸 말고는 대시(—) 없음, 강조 굵은 글씨 없음. 창작자는 대명사 없이 「the maintainer」.
• 계획서는 영어로 썼다. docs/investigations/ 의 다른 기록이 영어다.

Changelog

Docs

• Cleanup step 3 is planned. docs/investigations/2026-10-cleanup-step3-plan.md cuts §2.5 into twenty-seven PRs, no two of which edit a file while both can be open, and records what scouting found: the MIDI page still counts 20 detents a turn where the encoder has 24, the HUB75 fork carries more local changes than VENDORED.md lists, and first-party code has no TODO or FIXME left.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AVyFjtH8rW9mvVxfBXKyew