[DONE] 정리 5단계를 PR 넷으로 나눈 계획서 — 기록 하나와 RFC 초안 둘을 셋이 같이 써도 파일이 안 겹친다

[patternflow-bot]

studio / https://claude.ai/code/session_01T3bixs9Ya2G7jhkR72Fq4v

정리 5단계(해상도 자유 RFC 초안과 리눅스 플레이어 RFC 초안)를 정찰해서 PR 넷으로 나눈 계획서를 썼다. 머지하면 패널 크기가 박힌 자리를 적는 기록(k1)과 두 초안(k2·k3)을 세 사람에게 한꺼번에 맡길 수 있고, 닫는 PR(k4)만 3·4단계의 닫는 PR 이 비켜 줄 때를 기다린다.

좋아지는 것: 없음

체크리스트

• docs/rfc-cleanup.md §2.7 · §2.1 · §2.8–§2.13 과 §2.13 답 읽기
• 진행 기록 · 1–4단계 계획서 · docs/voice.md · docs/voice-banned.txt 읽기
• 정찰: 펌웨어 쪽(크기 매크로, config.h 지오메트리, 모듈 ABI, 캐시 키, DMA 메모리, 드라이버 IC, 콘솔 설정)과 웹·플레이어 쪽(PatternRuntime, @matrix, DeviceSim, 프리셋, 리눅스 흔적, 입력, 계약 다섯)
• docs/investigations/2026-10-cleanup-step5-plan.md: 맨 위 표에 k · 고칠 파일 · 먼저 머지될 k · §2.13 번호
• 표를 스크립트로 읽어 같이 열릴 수 있는 줄끼리 파일이 안 겹치는지, 3·4단계 표와 겹치는 곳이 k4 뿐인지 확인
• docs/rfc-cleanup-progress.md 표의 5단계 줄을 planned 와 계획서 링크로
• 링크 검사 · doc map(CSV 는 되돌림) · 글투 검사(금지어 · 대시 · 굵은 글씨)
• dev merge(daf5b4b, [DONE] 정리 1단계를 닫는다 — docs 안내 두 장이 옮긴 자리와 맞고, 링크 1066개가 다 닿는 지도를 커밋한다 #23 이 들어옴. 마지막 fetch 에서 더 들어온 것 없음)

한 일

• 계획서 docs/investigations/2026-10-cleanup-step5-plan.md (영어 289줄, 1–4단계 계획서와 같은 꼴). 구현은 하지 않았다.
• PR 표
  • k1 패널 크기가 정해지거나 가정된 자리를 파일·줄 단위로 적는 기록 docs/investigations/2026-10-panel-geometry.md. 아무 것도 제안하지 않는다
  • k2 docs/rfc-any-resolution.md Part 2: 런타임 지오메트리 구조체, 크기별 모듈과 캐시 키, 다시 굽지 않고 고르는 콘솔 페이지, 사이트 하네스, 다른 크기의 가상 패널, 한계(HUB75 1·2단계만, S-PWM 안 됨, DMA 메모리), 일 순서와 PR 수, 질문
  • k3 docs/rfc-linux-player.md Part 2: 엔진(PatternRuntime on Node), 출력 셋(rpi-rgb-led-matrix · Colorlight 계열 수신 카드 · HDMI), 입력 넷(USB 인코더 · MIDI · OSC · 웹 노브), 계약 다섯 중 무엇을 어떤 순서로, 못 하는 것(.pfm · 브라우저 플래시), 둘 곳, 일 순서, 질문
  • k4 5단계 닫기: 진행 기록, docs/README.md 에 초안 두 줄, CSV 둘, 두 초안의 서로 가리키는 줄을 링크로
  • k2·k3 는 k1 과 나란히 쓰고 k1 뒤에 머지(둘 다 k1 기록을 링크). 셋이 같이 일해도 파일이 안 겹친다
• 정찰에서 나온 것
  1. §2.7 의 25·4·7 은 줄이 아니라 PANEL_RES_W/H 의 출현 수다(src/ 의 25 는 21줄, 그중 8개가 주석). 크기를 정하는 config.h(11), 프리셋 35개의 142개, PFCanvas::W/H 와 24 KB 캔버스 버퍼, 손으로 친 128·64 넷, build_module.py 는 세지 않았다. 그래서 줄 단위 목록을 k1 기록으로 뺐다
  2. 사이트의 PatternRuntime 은 DOM 없이 돌고 너비·높이를 받는다. // @matrix 는 8–512 를 받는다. 128×64 에 묶인 쪽은 장치와 DeviceSim, 3D 패널, 가이드 미리보기다
  3. 모듈 ABI 두 구조체는 이미 panel_w/panel_h 를 갖고 크기가 다르면 양쪽이 거절한다. 캐시 키 (source_sha, builder_rev) 에 크기는 build_module.py 해시로만 들어간다
  4. DMA 버퍼는 begin() 때 내부 DMA RAM 에 한 번 잡힌다(PSRAM DMA 안 씀). 드라이버 식으로 128×64·8비트·이중 버퍼는 128 KB(트리에 없는 숫자라 계산으로 표시). 그래서 콘솔에서 고른 지오메트리는 다음 부팅에 먹는다
  5. 펌웨어가 못 켜는 S-PWM 패널은 바로 Colorlight 같은 수신 카드용이다. 리눅스 플레이어의 출력이 그 빈자리를 맡는다
  6. 사이트에 이미 라즈베리 파이로 돌린 빌드가 둘 있다(64×32 매트릭스, Pi 4 + HUB75 HAT). 리눅스 쪽 코드는 트리에 없다
  7. 계약 다섯 중 크기를 말하는 건 rest-api.md 하나다(status 의 panel, 썸네일, 사이드카, /api/clock 의 w/h)
  8. 5단계는 2단계 머지 뒤 3·4단계와 나란히 열리는 유일한 단계다. 3단계 k27, 4단계 k22·k24 와 파일(진행 기록 · docs/README.md · CSV)이 겹쳐서 그 셋은 k4 하나에 모았다
• 창작자에게 물을 것 (계획서 끝. 4단계 계획의 29 다음 번호, 모두 기본값 있음)
  30. 초안 Part 1 은 비워 둔다. 머지 뒤에 쓰면 잠금 검사가 빨개진다(기본: k2·k3 브랜치에서 머지 전에 쓰면 새 파일로 읽힌다) · 31. 목록을 기록으로 따로 둘까(기본: 예) · 32. 해상도 자유 초안이 어느 크기까지 일을 셀까(기본: ESP32-S3 하나가 메모리 식으로 감당하는 데까지, 벽·전광판은 플레이어로) · 33. 캐시 키에 W×H 열(§2.7)은 커뮤니티 DB 마이그레이션이다(기본: 열을 제안하고 비용과 다른 길을 같이 적는다) · 34. 플레이어는 이 레포에 둘까 따로 둘까, 관문에서 같이 proposed 가 되나(기본: 둘 다 적고 고르지 않음, 창작자가 말할 때까지 draft)

증거

$ python3 table_check.py docs/investigations/2026-10-cleanup-step5-plan.md .   # 표를 읽어 k 사이 순서를 따짐
4 rows; cycles: none
rows sharing a file without an order between them: none
files in more than one row: {'docs/rfc-any-resolution.md': [2, 4], 'docs/rfc-linux-player.md': [3, 4]}   # k4 는 k2·k3 뒤, 서로 가리키는 한 줄만
wait on nothing: [1]
named paths in the table that do not exist yet: ['docs/investigations/2026-10-panel-geometry.md', 'docs/rfc-any-resolution.md', 'docs/rfc-linux-player.md']   # 전부 백틱

# 3·4단계 계획서 표와 겹치는 파일 (5단계는 이 둘과 같은 때 열릴 수 있다)
step5 k4 x step3 k27: ['docs/investigations/2026-10-doc-map.csv', 'docs/investigations/2026-10-doc-parity.csv', 'docs/rfc-cleanup-progress.md']
step5 k4 x step4 k22: ['docs/README.md']
step5 k4 x step4 k24: ['docs/investigations/2026-10-doc-map.csv', 'docs/investigations/2026-10-doc-parity.csv', 'docs/rfc-cleanup-progress.md']
# k1–k3 는 겹치는 곳 없음. k4 는 표의 "merges after" 와 본문에서 그 셋이 열려 있지 않을 때만 연다

$ python3 .github/scripts/check_links.py
all 682 relative links resolve
$ git fetch --tags && (cd web && npm ci && npm run doc-map)
1070 links from 213 files → docs/investigations/2026-10-doc-map.csv
0 do not resolve
$ git checkout docs/investigations/2026-10-doc-map.csv   # CSV 는 닫는 PR 만 커밋

# 글투: voice-banned.txt 의 21개 grep → 0, 대시(—)는 표의 "없음" 칸과 "# Part 1 — Why" 머리글 인용뿐, 굵은 글씨 → 0
# 링크는 있는 파일 셋만(../rfc-cleanup.md, ../voice.md, ../panel-compatibility.md), 없는 파일은 백틱

# 정찰 숫자 대조
$ for d in src features abi; do git grep -o -h 'PANEL_RES_[WH]' -- firmware/patternflow/$d | wc -l; done
25
4
7
$ git grep -o -h 'PANEL_RES_[WH]' -- firmware/patternflow/presets | wc -l; ls firmware/patternflow/presets/*.h | wc -l
142
35
$ sed -n 51,52p firmware/toolchain/build_module.py
PANEL_W = 128
PANEL_H = 64
$ grep -n "return width \* _cdepth" firmware/patternflow/src/hub75/ESP32-HUB75-MatrixPanel-I2S-DMA.h
168:    return width * _cdepth * sizeof(ESP32_I2S_DMA_STORAGE_TYPE);
$ grep -n "primaryKey({ columns" web/src/lib/community/server/schema.ts
725:    primaryKey({ columns: [table.sourceSha, table.builderRev] }),

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

• 펌웨어 · web/src 무변경이라 §2.1 의 빌드 · 웹 명령은 해당 없다.

실행법

계획서만 있는 PR 이라 돌릴 것이 없다. 읽을 곳은 docs/investigations/2026-10-cleanup-step5-plan.md 맨 위 「The PRs」 표다. 2단계가 닫히면(§2.12) 총괄이 k1·k2·k3 를 한꺼번에 맡길 수 있다. k2·k3 는 k1 이 머지된 뒤에 머지한다. 셋이 다 머지되고 3단계 k27 · 4단계 k22·k24 가 열려 있지 않을 때 k4 를 맡긴다.

가정

• 「진행 기록의 앞 단계 줄」은 표의 5단계 줄로 읽었다([DONE] 정리 2단계를 PR 열넷으로 나눈 계획서 — 어느 셋을 같이 맡겨도 파일이 안 겹친다 #19–[DONE] 정리 4단계를 PR 스물넷으로 나눈 계획서 — 같이 열릴 수 있는 PR 끼리는 파일이 안 겹친다 #21 이 자기 단계 줄만 고친 것처럼). 「Where it stands」 줄은 닫는 PR 몫이라 두었다.
• k 는 넷이다. §2.7 은 초안 둘만 시키지만, 해상도 자유 초안에 줄 단위 목록까지 넣으면 300줄(§2.1(5))을 넘기 쉽고 한 파일이라 둘이 같이 일할 수도 없다. 목록을 docs/investigations/ 기록(k1)으로 빼고 초안엔 파일별 표와 링크를 둔다(D2). RFC 글과 어긋나는 자리라 질문 31 로 물었다.
• 「셋이 같이 해도」는 「같이 열릴 수 있는 어느 줄끼리도 파일이 안 겹친다」로 읽었다. 5단계는 3·4단계와 같은 때 열릴 수 있어서 그 두 계획서의 표와도 맞춰 봤다. 겹치는 진행 기록 · docs/README.md · CSV 는 k4 에 모으고, k4 는 그 단계들의 닫는 PR 이 열려 있지 않을 때만 연다.
• 같이 고칠 자리: 이 단계는 스크립트를 더하지 않아 web/package.json · check:ci 를 아무도 안 고친다. 같은 성격인 진행 기록 · docs/README.md · CSV 는 k4 하나가 갖는다. 두 초안이 서로를 가리키는 한 줄은 각 초안이 백틱으로 적고 k4 가 링크로 바꾼다.
• AGENTS.md · CHANGELOG.md · .github/ 는 고칠 일이 없어 줄이 없다. 초안은 명령도 경로도 워크플로도 바꾸지 않는다. 필요해지면 「for another k」 로 적고 k4 뒤 따로 PR. 각 PR 의 변경 줄은 본문 ## Changelog 로 간다.
• 없는 §2.9 잠금 · §2.10 글투 검사는 2단계 계획의 k8 · k9 몫이다. 다시 적지 않고 이름만 백틱으로 두었다. 새 RFC 의 Part 1 을 2단계 잠금이 읽는지는 k8 이 파일을 나열하는지 docs/rfc-*.md 를 다 읽는지에 달려서, k4 가 확인하고 아니면 따로 고침 PR 로(발견 11).
• RFC 가 이 단계에 정한 일을 표의 k 에 다 걸었다. 해상도 자유: 25·4·7 목록(k1 · k2), 런타임 지오메트리 구조체와 컴파일 기본값(k2), W×H 캐시 키(k2), 다시 굽지 않는 콘솔 페이지(k2), 하네스 매트릭스(k2), 다른 크기의 가상 패널(k2), 한계 셋(k2). 플레이어: JS 하네스 엔진, 출력 셋, 입력 넷, 계약 다섯, 못 하는 것(k3). Part 2 만 · 이 RFC 꼴 · 끝에 질문(D1, k2 · k3). 「done when」과 §2.12 여섯째 관문(k4). §2.11 라벨 step-5(D7).
• §2.13 답: 3(REST 먼저)은 k2 의 가상 패널과 k3 의 계약 순서로, 5(.human-written 에 더하지 않음)는 두 초안을 그 파일에 넣지 않고 Part 1 을 비워 두는 것으로(D1) 표에 걸었다. 4(메이저 업데이트 없음)는 이 단계가 의존성을 아예 안 더해서 저절로 지켜진다. 6(글투)은 모든 PR 에 걸린다. 1 · 2 는 이 단계와 상관없다.
• 트리가 말하지 않는 숫자(DMA 128 KB)는 드라이버 식으로 계산하고 계산이라고 적었다(D4). 이 환경엔 패널이 없어서 장치로 재 보지 않았다.
• 정찰은 하위 에이전트 둘이 하고, 계획서에 쓴 줄 번호는 직접 다시 대조했다.
• 계획서는 영어로 썼다. docs/investigations/ 의 다른 기록이 영어다. docs/voice.md 대로 절 사이 대시 · 금지어 · 굵은 글씨 · 여는 말 · 맺는 말 없이, 창작자는 「the maintainer」, 질문의 기본값에서만 「you」.
• 작업 글이 「정리 단계 PR 」 꼴이 아니라 ## Upstream 절은 두지 않았다.

Changelog

Docs

• Cleanup step 5 is planned. docs/investigations/2026-10-cleanup-step5-plan.md cuts §2.7 into four PRs: a record of every place the panel size is set, the any-resolution draft, the Linux player draft, and a close that waits until steps 3 and 4 free the files it shares with them. Scouting found that the 36 references §2.7 counts are a floor (the presets alone carry 142), that the site's pattern engine already takes any size while the device and its simulator do not, and that the S-PWM panels the firmware cannot drive are the ones a Colorlight receiving card, one of the player's outputs, is built for.

🤖 Generated with Claude Code

https://claude.ai/code/session_01T3bixs9Ya2G7jhkR72Fq4v